Skip to content
liasoftPublic

About

A Bootstrap 5 web-components UI kit — app shell, navigation, dashboards, data tables and a data-driven form system. Built with Lit.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

@liasoft/lit-ui

A Bootstrap 5 web-components UI kit for admin panels: application shell, navigation, dashboards, data tables and a data-driven form system — built with Lit.

Pages are described as plain data. A listing is a TableListing object, a form is a FormDefinition, the sidebar is a NavItem[]. You hand those to a component and get a complete, accessible, dark-mode-aware page — no templating, no framework.


Install

npm install @liasoft/lit-ui bootstrap
import '@liasoft/lit-ui/styles.css';
import { initTheme, installConfirmHandler } from '@liasoft/lit-ui';

initTheme();
const uninstallConfirm = installConfirmHandler(); // call on app teardown

Import the whole kit, or just the families you need:

import '@liasoft/lit-ui';                      // registers all 70 elements
import '@liasoft/lit-ui/components/table';     // or a subset

Light DOM, on purpose

Components render into the light DOM, not shadow DOM. This kit is Bootstrap: its stylesheet, its utility classes and its JavaScript plugins (Collapse, Dropdown, Modal, Popover) all need to see the rendered markup. Shadow roots would cut every one of those off.

The consequence: load styles.css once, globally. There is no per-component style encapsulation, and your own CSS can reach kit internals — which is usually what you want in an admin UI, but it is a real trade-off worth knowing about.


Claude Code

The kit ships first-class Claude Code support: the repo doubles as a plugin marketplace, and the lit-ui plugin carries one knowledge skill per component family plus an overview that maps use cases to families. An agent working in your repo loads exactly the component knowledge it needs — nothing more:

/plugin marketplace add liasoft/lit-ui
/plugin install lit-ui@lit-ui

After that, asking Claude Code to "add a members listing with row actions" makes it reach for TableListing and lia-data-table the way this README would.

The same skills ship in the npm package, matching the installed version, under node_modules/@liasoft/lit-ui/plugins/lit-ui/skills/. Point other agents (Codex, Copilot) at overview/SKILL.md there, for example from your AGENTS.md.

What changed

CHANGELOG.md lists every release: new components and options, fixes, and what to change when you upgrade.


A complete page

For a routed app, start with the complete shell and page recipe. Extend LiaTransparentElement for app/view wrappers, let lia-page own the heading and gutter, and use lia-card for titled sections. Set the shell’s content-class="" when a router view or error boundary wraps the page.

import { html, render } from 'lit';
import '@liasoft/lit-ui';

render(html`
  <lia-app-shell
    brand-label="Orbit Console"
    .navItems=${nav}
    .user=${{ loginname: 'amara', isAdmin: true }}
    .searchEnabled=${false}
  >
    <lia-page .title=${'Members'} icon="fa-solid fa-users"
      .actions=${[{ id: 'add', label: 'Invite a member', icon: 'fa-solid fa-plus',
                    variant: 'primary' }]}
    >
      <lia-card .title=${'Members'} icon="fa-solid fa-users" .content=${html`
      <lia-data-table
        listing-id="members"
        .columns=${[
          { key: 'name',    label: 'Name',    sortable: true },
          { key: 'quota',   label: 'Quota',   renderer: 'progressbar' },
          { key: 'active',  label: 'Active',  renderer: 'boolean' },
        ]}
        .rows=${members}
        selectable
        .rowActions=${(row) => [
          { id: 'edit',   icon: 'fa-solid fa-pen',   href: `#/members/${row.id}` },
          { id: 'delete', icon: 'fa-solid fa-trash', variant: 'outline-danger',
            confirm: { message: `Delete ${row.name}?` } },
        ]}
        @lia-action=${(e) => console.log(e.detail.action.id, e.detail.row)}
      ></lia-data-table>`}></lia-card>
    </lia-page>
  </lia-app-shell>
`, document.querySelector('#app'));

This composes the sidebar, navbar, heading toolbar and attached table with pagination, column manager and search. Supply nav, members and your action handlers; install the confirmation handler from the setup above for styled per-row dialogs. Enable global search only when the app handles lia-search and supplies results.


The families

Family Elements
primitives lia-icon lia-button lia-action-bar lia-badge lia-progress lia-card lia-empty-state lia-spinner lia-copy-button lia-tooltip lia-popover lia-key-value
layout lia-app-shell lia-navbar lia-sidebar lia-sub-sidebar lia-page lia-page-heading lia-footer lia-global-search lia-theme-toggle lia-breadcrumb
feedback lia-alert lia-alert-stack lia-banner lia-modal lia-confirm-dialog lia-delete-confirm lia-toast lia-toast-container lia-hint lia-error-boundary
table lia-table lia-data-table lia-pagination
form lia-form lia-form-field lia-form-section lia-inline-edit lia-stepper lia-wizard
dashboard lia-stat-card lia-stat-row lia-info-card lia-activity-list lia-chart lia-widget-grid
settings lia-settings-page lia-settings-nav lia-settings-group
auth lia-auth-layout lia-login-form lia-forgot-password-form lia-reset-password-form lia-two-factor-form lia-two-factor-setup lia-otp-prompt lia-credentials-prompt lia-question-dialog lia-profile-form lia-password-strength lia-code-input
editors lia-record-editor lia-log-viewer lia-diff-view lia-code-block lia-api-keys-panel lia-file-tree

The form system

One FormDefinition drives everything — 24 field types, two-column rows, input-group composition, conditional visibility and validation:

const form: FormDefinition = {
  title: 'Host settings',
  sections: {
    general: {
      title: 'General',
      icon: 'fa-solid fa-gear',
      fields: {
        hostname: {
          type: 'text',
          label: { title: 'Hostname', description: 'Fully qualified.' },
          mandatory: true,
        },
        tls: { type: 'switch', label: 'Enable TLS' },
        cert: {
          type: 'select',
          label: 'Certificate',
          options: certs,
          showWhen: { field: 'tls', truthy: true },   // conditional
        },
        quota: {
          type: 'textul',                              // number + "unlimited" (-1)
          label: 'Storage quota',
          nextTo: { unit: { type: 'select', options: units, prefix: 'per' } },
        },
      },
    },
  },
};
<lia-form .definition=${form} @lia-submit=${(e) => save(e.detail.values)}></lia-form>

Field types: text password number email url tel date datetime-local time file hidden textarea select checkbox radio switch textul label infotext longtext link itemlist image custom.

Beyond the field types, the system supports conditional rules (showWhen, hideWhen, disabledWhen, readonlyWhen, requiredWhen), cross-field validators (requiredIf, requiredUnless, requiredWithout, requiredOneOf), debounced async validation with abort semantics, and dependent option lists.


Theming

Configure the SCSS tokens when you load the stylesheet, and everything follows — including Bootstrap itself. Tokens are !default variables, and Sass only lets a @use override them through with (...); variables defined in your own file before a plain @use have no effect. Configuration values must be literals or expressions of your own, not variables of the module being configured:

Compiling the SCSS yourself needs two packages that @liasoft/lit-ui does not install for you (Bootstrap comes from the install step above): Sass and Font Awesome, whose Sass the stylesheet imports.

npm install --save-dev sass@^1.85 @fortawesome/fontawesome-free@^7.3
// src/theme.scss
@use 'pkg:@liasoft/lit-ui/scss/app' with (
  $lia-800: #0f766e,          // your brand
  $primary: #0f766e,
  $lia-sidebar-width: 280px,
  $fa-font-path: '/webfonts'  // where you serve the Font Awesome font files
);

Compile it with Sass's Node package importer, which follows the package exports map (./scss/* maps to src/styles/*), and a load path for the Bootstrap and Font Awesome Sass the stylesheet imports:

npx sass --pkg-importer=node --load-path=node_modules src/theme.scss dist/theme.css

A plain sass CLI does not read package exports on its own, so the bare @liasoft/lit-ui/scss/app form only works where your bundler resolves it for you. Plain Sass does not copy font files: $fa-font-path is written into the CSS as-is, so copy node_modules/@fortawesome/fontawesome-free/webfonts to the matching location of your site (the default is a package specifier that only a bundler can follow). See Sass's @use configuration and loading a module that contains imports.

Light and dark are both first-class via Bootstrap 5.3's data-bs-theme. initTheme() wires the stored preference and follows the OS when set to auto; <lia-theme-toggle> gives users the switch.


The demo app

npm install
npm run dev        # http://localhost:5180

45 routes covering every element and every meaningful state, plus six complete page compositions under Full pages — an admin dashboard, a settings page with sub-sidebar navigation, a log viewer, a usage page, a sign-in screen and an install wizard. Each demo shows the data object that drives it next to the live example.

Scripts

Command What it does
npm run dev demo app with HMR
npm run build library + demo
npm run build:lib ES bundle, per-family entry points, dist/liasoft-lit-ui.css, .d.ts
npm run typecheck tsc --noEmit (strict, no unused)

Status

The 0.1.x series (see package.json for the current release). There is no automated test suite yet — the kit is verified by a typecheck, both builds, a check that the documented Sass theming example compiles, and a headless render of every demo route. Treat the component APIs as unstable until 1.0.

License

MIT.

About

A Bootstrap 5 web-components UI kit — app shell, navigation, dashboards, data tables and a data-driven form system. Built with Lit.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages