UI Library Docs

About

Why this library exists, how to load it, and the conventions it follows.

Tokens and style guidance for building consistent UI. Open Props primitives plus project-level semantic aliases.

Form fields, choice controls, help text, and validation messages.

.form-fields — form and field structure, labels, .input-group with prefix/suffix decoration, reading font for long-form text
<x-select> — select with option groups, custom button content, [raw] inside an input group
<ui-combobox> — autocomplete via mode="none|list|inline|both", async sources and their failures, chips and multiple

role="switch" — on/off toggle
<fieldset> of radios — one of many, plain / segmented / card look, clearing the selection

Hint and validation error under a field — one <small> swapping .field-help → .field-error → .field-success, with aria-invalid and aria-live; the same slot carries a server's rejection
Form field states — the whole vocabulary: :user-valid / :user-invalid, disabled / readonly / locked, flux, busy while a save is in flight, error, which state wins, dirty tracking with .modified
Status messages § Form errors — which surface an error belongs on: the field it is about, or the notification store

JS modules under public/ui/lib/ — orchestration helpers and stores that don't render UI themselves but back the components above.

job-queue.mjs — background queue: volatile closure jobs, plus fetch jobs persisted in IndexedDB and scheduled across tabs by a worker
view.mjs — mount / swap / stop view components
service.mjs — register the parts of a page that hold timers, and stop them all with one call
service-worker.mjs — follow the page's service worker: which one served the page and what version it is, a new one installing or waiting, switching to it, and the precaching worker, which installs a checked snapshot, serves it and answers for its version
stable-table.mjs — re-render <tbody> while preserving hover/focus
notifications.mjs — store backing <ui-statusbar> + <ui-notifications>
toast.mjs — transient announcements
tooltip.mjs — hover/focus descriptions
tree.mjs — decorate a nested <ul>/<li> into an APG tree view
listbox.mjs — decorate elements already in the page into an APG listbox, including one nested inside another composite widget
accordion.mjs — decorate <details>/<summary> into an APG accordion (region wiring, exclusivity, lazy load)
l10n.mjs — translation + reactive locale
scroll-util.mjs — scroll a target into view only when it has left the reading zone, at the golden ratio, on both axes — vertically on the window or an inner scroll box, horizontally on whichever ancestor of the target scrolls sideways

Custom elements and shared CSS patterns, grouped by role. Fields and their validation feedback have their own Forms card above.

<ui-toolbar> — horizontal group with roving tabindex (arrow-key nav)
<ui-tab> / <ui-outlet> — tab list bound to a view switcher
tree() — nested <ul> into an APG tree view (expand/collapse, lazy children)
listbox() — elements already in the page into an APG listbox (roving focus, typeahead)

<ui-dialog> — modal, alert, response and slide (sheet) variants
<ui-menu> — dropdown with submenus; trigger="contextmenu" for right-click menus
<ui-popover> — anchored popover with light-dismiss
toast() — transient status notification
tooltip() — description on hover, on focus, and on a held press

.callout — Callout — a tinted remark about the element beside it, tinted by the caller
<ui-notifications> — persistent list of warnings, opened from a trigger button
<ui-statusbar> — projects the top active notification inline (role="status")
Status messages — inline success / error animations (.status-success, .status-error), empty states, and which surface a form error belongs on
.spin — Loading & spinners — inline spinner, busy overlay, and which to use when
<bg-jobs> — operator table over the job queue: every job in the browser, counts by status, delete and retry