@zeyos/zx 2.3.0 → 3.0.0

package/docs/llms.md

@@ -1,7 +1,7 @@
-# Zx — agent reference
+# Xenon Design System (Zx) — agent reference
 
-> Zx is the dependency-free, vanilla-JavaScript UI component library for ZeyOS business
-> applications. ES2022 modules, WAI-ARIA-accessible native controls, semantic `--zx-*` design
+> Xenon is the dependency-free design system for ZeyOS business applications; Zx is its
+> vanilla-JavaScript implementation. ES2022 modules, WAI-ARIA-accessible native controls, semantic `--zx-*` design
 > tokens (light/dark + cozy/compact), and lifecycle-safe components. Zero runtime dependencies.
 > This file is the single, complete reference a coding agent needs to build UI with Zx; each
 > component below is wrapped in `<!-- doc:<name> -->` markers so tools can extract a single
@@ -61,7 +61,7 @@ need not be set). A preset repoints five tier-1 tokens — `--zx-accent-300` …
 and the semantic tier takes its own stop per polarity (600/700 on light surfaces, 300/400/500 on
 dark), so one five-line block rethemes light, dark, and auto together. Status colours are not part
 of a preset. Define your own the same way, or build one at `/theme.html` (the theme studio, which
-renders every component live and exports the CSS):
+renders every component family live and exports the CSS):
 
 ```css
 :root {
@@ -211,8 +211,9 @@ reflection and ElementInternals form association: `<zx-toggle>`, `<zx-check-butt
 
 Load `zx-compat.global.js` (or import `zx-compat.esm.js`) →
 `window.gx.{core,ui,util,zeyos,bootstrap}` wrapping Zx components (constructor/option/event-name
-translation, MooTools-style `addEvent`). `gx.compat.installGlobals()` (opt-in) installs `__()`,
-`_()`, `String.htmlSpecialChars`, and the element `store/retrieve` shim. Full namespace listing in
+translation, MooTools-style `addEvent`). `gx.compat.installGlobals()` (opt-in) installs its gx
+`__()` parser only when that name is free, plus `_()`, `String.htmlSpecialChars`, and the element
+`store/retrieve` shim. Full namespace listing in
 the "gx compatibility layer" component section below; class map and unsupported legacy APIs in
 `MIGRATION.md`.
 
@@ -418,6 +419,67 @@ Search input with embedded search and clear buttons (`role="search"`).
 - **Events** — `input {value}` (debounced), `submit {value}` (Enter or the button), `clear`.
 <!-- /doc -->
 
+<!-- doc:launcher -->
+### Launcher — application and record search
+
+A native-dialog launcher for applications, recent records, commands, and grouped remote results.
+Zx owns ranking, focus, request cancellation, and presentation; ZeyOS owns the catalogue,
+permissions, recent-history/cache policy, and the route or command ultimately invoked.
+
+- **Constructor** — `new Launcher(null, options)` owns a body-level dialog;
+  `new Launcher(existingDialog, options)` enhances and later restores an existing `<dialog>`.
+- **Options** — `items`, abortable `sources: [{id, label?, minQuery?, load(query, {signal})}]`,
+  `query`, `debounce: 250`, `minQuery: 0`, `maxResults: 100`, `placeholder`, `label`, `emptyText`,
+  `loadingText`, and `shortcut: 'mod+k'|false`.
+- **Items** — `{id, label, description?, keywords?, group?, icon?, badge?, value?, href?, target?,
+  invoke?, pinned?, disabled?}`. Links stay native so modified and middle clicks work; non-link
+  commands may provide an application-owned `invoke` callback.
+- **Methods** — `open()`, `close()`, `toggle()`, `isOpen()`, `focus()`, `setQuery()`, `getQuery()`,
+  `setItems()`, `setSources()`, `destroy()`.
+- **Events** — cancelable `select {item, value, source, query}`, `query {query}`, `open`, `close`,
+  and `error {source, error}`. Preventing `select` suppresses the supplied link or callback.
+- **Ranking** — local results are case/diacritic-insensitive and deterministic: exact label,
+  label prefix, word prefix, label substring, identifier substring, then acronym prefix. Pinned
+  items retain an explicit order ahead of otherwise equal results. A new async query aborts and
+  ignores stale source work.
+- **Keyboard** — Cmd+K on macOS or Ctrl+K elsewhere opens by default; the shortcut is ignored in
+  editable controls, composition, and modal contexts. Arrow keys, Home/End, and Enter operate the
+  single listbox selection model; Escape closes and restores focus.
+<!-- /doc -->
+
+<!-- doc:avatar -->
+### Avatar
+
+A fixed-geometry user image with deterministic initials fallback. Image loading or failure never
+changes layout, and the component is decorative by default so adjacent identity text is not
+announced twice.
+
+- **Options** — `src`, `name`, `initials`, `label`, `size: 'sm'|'md'|'lg'|<pixels>`,
+  `shape: 'circle'|'rounded'|'square'`, `status: 'online'|'away'|'busy'|'offline'|null`, and
+  `statusLabel`.
+- **Methods** — `set(values)`, `setStatus(status, label?)`, `hasImage()`, `destroy()`.
+- **Accessibility** — set `label` only when the avatar stands alone. Presence is supplementary
+  status, not the account's accessible name; supply `statusLabel` when it conveys information.
+<!-- /doc -->
+
+<!-- doc:account-menu -->
+### AccountMenu
+
+Composes `Avatar` and `MenuButton` into one account trigger and APG menu. The popup repeats the
+identity before its actions; Zx never decides role visibility, changes preferences, signs a user
+out, or mutates the session.
+
+- **Options** — `account: {name, secondary, src?, initials?, status?, statusLabel?}`, `items`,
+  `compact: false`, `label`, and any top/bottom/left/right `placement`.
+- **Methods** — `open()`, `close()`, `toggle()`, `isOpen()`, `setAccount()`, `setItems()`, `focus()`,
+  `getPanel()`, `destroy()`.
+- **Events** — cancelable `select {value, item}`, `open`, and `close`. A canceled selection does
+  not run the item's callback and leaves the menu open, so an application can reject or confirm an
+  action without rebuilding the account surface.
+- **Accessibility** — compact mode is visually avatar-only but keeps the full account-menu name on
+  its single native trigger; MenuButton retains focus return, typeahead, and arrow-key behavior.
+<!-- /doc -->
+
 <!-- doc:select -->
 ### Select — APG editable combobox
 
@@ -442,7 +504,7 @@ Unifies single-select, local filtering, and async loading.
   `Select.permission(target, {groups, value})`, the record-access picker with Private and Public
   pinned above the groups. Its value is the tri-state ZeyOS stores (`false` private, `true` public,
   or a group ID), `groups` takes an array or a loader `(query)=>items`, and the labels come from
-  `msg` (`permission.private`, `permission.public`). Replaces the deprecated `Permission`.
+  `msg` (`permission.private`, `permission.public`).
 - **Keyboard** (APG combobox) — ArrowDown/Alt+ArrowDown open; arrows navigate and wrap; Home/End;
   Enter selects; Esc closes; Tab closes; printable characters filter (editable) or run a typeahead
   (readonly). `aria-activedescendant` tracks the active option.
@@ -675,6 +737,102 @@ Structured modal: a header with title and close button, a body, and footer butto
   `Dialog.prompt({ title, message, value })` → string|null.
 <!-- /doc -->
 
+<!-- doc:sheet -->
+### Sheet
+
+Edge-anchored surface — a `Dialog` attached to one side of the viewport instead of floating in the
+middle. One primitive covers both side sheets and mobile drawers, which differ mainly in the edge they take, so
+`side` replaces what would otherwise be two components. Inherits the whole Dialog anatomy: title,
+footer buttons, switchable views, and focus restoration.
+
+- **Options** — `side: 'end'` (`'start' | 'end' | 'top' | 'bottom'`, logical), `modal: true`
+  (`true | 'trap-focus' | false`), `backdrop: 'dim'` (`'dim' | 'blur' | 'none'`), `size: null`
+  (CSS length or px number, applied to whichever axis `side` implies), `closeButton: true`,
+  plus everything Dialog takes — `title`, `content`, `buttons`, `closable`, `lightDismiss`
+  (defaults to `true` here, unlike Modal), `destroyOnClose`.
+- **Methods** — `open()`, `close(result?)`, `setSide(side)`, `getSide()`, `setSize(size)`,
+  `isModal()`, `isDocked()`, `isOpen()`, `getSize()`, `snapTo(target)`, plus Dialog's `setTitle()`, `setContent()`,
+  `setButtons()`, `addView()`, `showView()`.
+- **Events** — `open`, `close {result}`, `cancel` (preventable with `event.preventDefault()`),
+  `resize {size, ratio}`, `dockchange {docked, dock}`.
+- **Docked** — a sheet has two lives, and it does not choose between them: `Dock.adopt(sheet)`
+  makes it a track in that dock's flow instead of an overlay, and the dock then owns its side,
+  size, and resizing. A docked sheet is always non-modal, `close()` collapses its track to zero
+  rather than sliding away, and Escape and outside-click stop dismissing it — it is part of the
+  layout, not something covering it. `Dock.release(sheet)` hands it back. Nothing is rebuilt
+  across a handoff: the element moves and reopens in place, so DOM state and listeners survive,
+  and no `open`/`close` is emitted for what is only a change of address.
+- **Modality** — `true` delegates focus containment, page inertness, Escape, and the backdrop to
+  the browser through `showModal()`. `'trap-focus'` and `false` open with `show()`, so the page
+  keeps scrolling and stays interactive; Escape and outside-click are re-implemented, and
+  `'trap-focus'` adds `focusTrap()` on top. Only a modal sheet renders a `::backdrop`, so
+  `backdrop` is meaningful only when `modal` is `true`.
+- **Resizing and detents** — `resizable` makes the inner edge draggable between `min` and `max`.
+  `snap` gives it detents: a number at or below 1 is a fraction of the viewport along the sheet's
+  axis, anything larger is pixels, and a string is any CSS length (`'320px'`, `'90%'`). With
+  detents a drag settles on the nearest one rather than where it was released, and `snapTo(index)`
+  or `snapTo(value)` moves there directly. Dragging below half the smallest allowed size dismisses
+  a `closable` sheet, so resize, detent, and swipe-to-dismiss are one gesture whose meaning is
+  decided when the pointer settles. `getSize()` reports the current pixel size. A sheet that is
+  neither `resizable` nor snapping still has a draggable handle where `handle` shows one — that is
+  what makes a drawer dismissible — but the drag may only take size away, never add it, so it
+  cannot be grown by dragging when nothing asked for resizing.
+- **Handle** — `handle: 'auto'` shows a grab handle on `top` and `bottom` sheets, which is what
+  makes them read as drawers; `true` and `false` force it either way. It exists whenever the sheet
+  is `resizable` or has `snap`, visible or not. It is a `separator` with live
+  `aria-valuenow`/`aria-valuemin`/`aria-valuemax`: arrow keys along the axis step it by 16px, Shift
+  by 64px. A docked sheet hides its handle — the dock's own divider resizes it there.
+- **Custom properties** — `--zx-sheet-size` (written by `size`; the per-side default otherwise)
+  and `--zx-sheet-radius` (inner corners of a top/bottom sheet, default `--zx-radius-xl`) are
+  internal geometry, not published styling hooks — prefer the options. `--zx-overlay-blur` is a
+  tier-2 semantic token and is public: it sets the `'blur'` backdrop's radius, default `8px`.
+- **Motion** — entry and exit both animate, via `@starting-style` and
+  `transition-behavior: allow-discrete` on `display`/`overlay`; without them the sheet appears and
+  disappears instantly. All of it sits inside `prefers-reduced-motion: no-preference`.
+- **Keyboard and screen readers** — identical to Dialog: the native `<dialog>` supplies the role
+  and `aria-labelledby` points at the title. Escape closes when `closable`, focus moves to the
+  `[autofocus]` control or the first focusable descendant on open, and returns to the opener on
+  close. Tab cycles within the sheet when `modal` is `true` or `'trap-focus'`.
+<!-- /doc -->
+
+<!-- doc:sheet-stack -->
+### SheetStack
+
+An ordered group of Sheets that reads as one drill-down. Deliberately tiny, because the browser
+already does the hard part: nested dialogs stack in the top layer by open order, so there is no
+z-index bookkeeping, and Escape closes only the topmost, so unwinding one level at a time is
+native. What is left is which sheet sits at which depth, written onto the elements as `data-depth`
+and `--zx-sheet-depth` for CSS to interpret.
+
+Owns no element, so it is a controller rather than a `Component` — constructed with options
+alone, `new SheetStack({…})`.
+
+- **Options** — `layout: 'stack'` (`'stack' | 'cascade'`), `offset: 24`, `scale: 0.04`, `max: 3`.
+- **Methods** — `push(sheet)`, `pop()`, `popTo(sheet)`, `clear()`, `top()`, `size()`, `sheets()`,
+  `has(sheet)`, `on/off/once`, `destroy()`.
+- **Events** — `push {sheet, depth}`, `pop {sheet}`. `pop` fires however a sheet left — popped,
+  dismissed with Escape, or closed by its own button.
+- **Layouts** — `stack` slides each covered sheet back toward its own edge, scales it down, and
+  takes it out of the tab order; only the top one is usable, which is the drill-down feel.
+  `cascade` shifts each covered sheet clear of the ones in front — by their measured size, not a
+  guess — so they sit side by side and all stay usable. `cascade` is usually the right one for an
+  ERP screen, where the parent record should stay readable while a line item is edited.
+- **Depth** — numbered from the top: the visible sheet is `0`. Past `max` a sheet stops being
+  drawn but stays open and in the stack. In a `stack` only the topmost backdrop shades the page;
+  one per depth would compound into black. A `cascade` shades nothing — a backdrop paints directly
+  beneath its own dialog in the top layer, so the top sheet's would dim exactly the sheets the
+  layout exists to keep readable. Pair a cascade with `modal: false` when the page behind it
+  should stay live as well.
+- **Ownership** — the stack never owns its sheets. `destroy()` empties it and strips the depth
+  styling without closing anything.
+- **Accessibility** — for `stack`, covered sheets are `inert`. The browser does that on its own
+  for stacked *modal* dialogs, but a non-modal stack gets nothing, so the attribute is set either
+  way. `cascade` deliberately leaves them interactive.
+- **Gotcha** — `close()` on a dialog dispatches its `close` event in a queued task, not
+  synchronously. `pop()` therefore removes the sheet from the stack itself rather than waiting for
+  the event, so `popTo()` and `clear()` can loop without racing it.
+<!-- /doc -->
+
 <!-- doc:dropdown -->
 ### Dropdown
 
@@ -682,7 +840,8 @@ Generic anchored popover in the top layer, constructed as `new Dropdown(anchor,
 light-dismisses on an outside click or Esc, and mirrors `aria-expanded` onto the anchor.
 
 - **Options** — `content`,
-  `placement: 'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'`, `offset: 4`,
+  `placement: 'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'` plus the matching
+  `left*` and `right*` placements, `offset: 4`,
   `matchWidth: false`, `openOn: 'click'|'manual'`, `closeOnSelect: false`.
 - **Methods** — `open()`, `close()`, `toggle()`, `isOpen()`, `setContent()`, `getPanel()`.
 - **Events** — `open`, `close`.
@@ -695,8 +854,11 @@ A button that opens a `role="menu"`.
 
 - **Options** — `label`, `icon`, `kind`,
   `items: [{ label, icon?, value?, disabled?, danger?, onselect? } | '-']`, `placement`.
-- **Methods** — `setItems()`, `open()`, `close()`, `setLabel()`.
+- **Methods** — `setItems()`, `open()`, `close()`, `setLabel()`, `getTrigger()`, `getPanel()`,
+  `focusFirst()`, `focusLast()`.
 - **Events** — `select {value, item}`, `open`, `close`.
+- **Cancellation** — `select` is cancelable. Preventing it skips the item's `onselect` callback and
+  leaves the menu open, which is the composition seam used by `AccountMenu` and rail flyouts.
 - **Keyboard** — ArrowDown/Enter/Space open and focus the first item; ArrowUp opens and focuses the
   last; arrows cycle; Home/End; typeahead; Enter/Space select; Esc/Tab close.
 <!-- /doc -->
@@ -734,7 +896,11 @@ parked at the pointer, so it flips near a viewport edge like every other floatin
 
 A description bubble anchored to another element. The panel is a manual popover positioned by the kernel's `position()`, so it escapes clipping and stacking contexts and flips near a viewport edge; it carries `role="tooltip"` and a generated id, and the anchor gets `aria-describedby` pointing at it only while it is open — closing puts the anchor's original value back, including no value at all. The bubble is never interactive: `pointer-events: none` keeps it from stealing the hover it depends on, and nothing inside it can take focus. Hover opens it after `delay`; keyboard focus opens it immediately, because a keyboard user cannot hover a moment longer; a touch pointer never opens it, since a bubble with no "move away" gesture would simply stick. Only one is ever visible at a time, which falls out of the dismissal rules rather than a registry.
 
-- **Options** — `content` (string, Node, or a function re-evaluated on every open), `placement` (`'top'` default, plus `bottom`, `top-start`, `top-end`, `bottom-start`, `bottom-end`), `offset` (6), `delay` (400), `hideDelay` (80), `maxWidth` (260; a number is pixels, a string is any CSS length), `trigger` (`'both'` default, or `'hover'`, `'focus'`, `'manual'` — `manual` installs no listeners at all and leaves everything to the methods), `disabled` (false).
+- **Options** — `content` (string, Node, or a function re-evaluated on every open), `placement`
+  (`'top'` default, plus top/bottom/left/right and their start/end variants), `offset` (6), `delay`
+  (400), `hideDelay` (80), `maxWidth` (260; a number is pixels, a string is any CSS length),
+  `trigger` (`'both'` default, or `'hover'`, `'focus'`, `'manual'` — `manual` installs no listeners
+  at all and leaves everything to the methods), `disabled` (false).
 - **Methods** — `show()`, `hide()`, `toggle()`, `isOpen()`, `setContent(content)`, `enable()`, `disable()`, `isDisabled()`, `getAnchor()`, `destroy()`. Convenience factories: `tooltip(anchor, contentOrOptions)` takes either a content value or a full option object, and `describe(anchor, text)` is the one-liner replacement for a `title` attribute. Both return the instance.
 - **Events** — `open`, `close`. Both fire only on a real transition, so a `show()` on an open tooltip is silent.
 - **Keyboard** — Focusing the anchor opens the tooltip at once; moving focus away closes it. `Escape` closes it without moving focus, satisfying WCAG 1.4.13. A `pointerdown` anywhere closes it, and focus that arrives with a click does not re-open it.
@@ -759,22 +925,32 @@ Sortable, selectable, sticky-header data table — one component covering both t
 horizontally, and multi-select adds a tri-state header checkbox plus Shift+click range select.
 
 - **Options** — `columns: [{ id, label, sortable?, width ('120px'|'2fr'|'auto'), align,
+  type?: 'text'|'number'|'currency'|'percent'|'unit', locale?, decimals?, currency?, unit?,
   render?: (row,i)=>Node|string, sortValue?, headerTitle? }]`, `data`, `rowId: 'ID'`,
   `sort: { id, dir }`, `sortMode: 'local'|'server'`, `selectable: false|'single'|'multi'`,
-  `stickyHeader: true`, `height`, `emptyText`, `rowClass`, `zebra: true`.
+  `stickyHeader: true`, `height`, `emptyText`, `rowClass`, `zebra: true`, and
+  `hierarchy: false|{parentId, column?, expanded?}`. Locale, currency, unit, and decimals may be
+  row callbacks; values remain numbers in row data while display formatting is locale-aware.
 - **Methods** — `setData()`, `addData()`, `updateRow(id,row)`, `removeRow(id)`, `getRow(id)`,
   `getData()`, `empty()`, `setSort(id,dir)`, `getSelection()`, `setSelection(ids)`,
   `clearSelection()`, `setLoading(bool)` (busy/skeleton state — dims rows, shows an indeterminate
   top bar, sets `aria-busy`, and is cleared by the next `setData`).
 - **Events** — `rowclick {row, id, index, event}`, `rowdblclick`, `sort {id, dir}`,
-  `selectionchange {rows, ids}`, `datachange {rows}`.
+  `selectionchange {rows, ids}`, `datachange {rows}`, and `rowtoggle {row, id, expanded}`.
+- **Hierarchy** — flat parent references are projected as an ARIA `treegrid`; `getData()` and all
+  editing/mutation APIs stay flat and ID-based. Orphans become roots, cycles render once, local
+  sort reorders siblings without mixing levels, and growing counts visible rows. Use
+  `toggleRow()`, `expandRow()`, `collapseRow()`, `expandAll()`, `collapseAll()`, and
+  `getExpanded()`. The native disclosure button works by pointer and keyboard without selecting
+  or clicking the row.
 - **Editing** — `editMode: false|'cell'|'row'` (default `false`, and completely inert until set).
   `'cell'` edits one cell, `'row'` opens every editable cell of the row and commits them as a unit.
   Editors are sized into the cell without changing row height, and an editing cell carries
   `data-editing="true"` (`data-invalid="true"` plus an `aria-live` message when a validator rejects).
 - **Editable columns** — extra column keys: `editable: false|true|'text'|'number'|'select'|'date'|
-  'checkbox'|'textarea'|((row)=>boolean)` (`true` means `'text'`; a function is evaluated per row, so
-  individual rows stay read-only), `options` for `'select'` (`[{value,label}]`, a `{value: label}` map
+  'checkbox'|'textarea'|((row)=>boolean)` (`true` infers `'number'` for number/currency/percent/unit
+  columns and `'text'` otherwise; a function is evaluated per row, so individual rows stay
+  read-only), `options` for `'select'` (`[{value,label}]`, a `{value: label}` map
   whose keys are always strings, or `(row)=>items`), `editorProps` (forwarded to the underlying
   NumberField/Select/Datebox/Toggle or to the generated `<input>`/`<textarea>`),
   `editor: (row, api)=>Node` for a fully custom editor (`api` is `{value, commit(value), cancel(),
@@ -783,6 +959,10 @@ horizontally, and multi-select adds a tri-state header checkbox plus Shift+click
   seeds the text of a `'text'`/`'textarea'` editor, `parse` converts every editor's raw output back),
   and `validate: (value,row)=>true|string` (a returned string marks the cell invalid, shows the
   message, and refuses the commit).
+- **Transaction editors** — currency and unit columns reuse `NumberField` and show the resolved
+  currency/unit as its suffix unless `editorProps.unit` overrides it. This is a generic typed-grid
+  contract: application code remains responsible for tax, discount, subtotal, and accounting
+  formula rules.
 - **Editing methods** — `startEdit(rowId, columnId)`, `commitEdit()`, `cancelEdit()`, `isEditing()`,
   `getEditing()` → `{id, columnId}|null`.
 - **Editing events** — `editstart {row, id, column, columnId, value}`;
@@ -824,6 +1004,53 @@ horizontally, and multi-select adds a tri-state header checkbox plus Shift+click
   A function is re-called on every render, which is what to use when the placeholder holds controls.
 <!-- /doc -->
 
+<!-- doc:grid -->
+### Grid and `Grid.BillingItems()`
+
+`Grid` is the public extension point for repeatable data-table presets. It subclasses `Table`
+without forking its implementation, so sorting, selection, hierarchy, responsive stacking,
+editable cells/rows, loading, events, and teardown keep the Table contract.
+
+- **Constructor** — `new Grid(target, tableOptions)` accepts the complete `Table` API.
+- **Preset** — `Grid.BillingItems(target, options)` supplies an editable hierarchical billing
+  schema for item, quantity, unit, unit price, currency, and line total. It returns a `Grid`.
+- **Billing options** — `data`, `fields` key overrides, `units`, `currencies`, fallback `currency`,
+  `locale`, `decimals`, `columnOverrides`, complete `columns` replacement, `lineTotal(row, changes)`,
+  and `oneditcommit` in addition to ordinary Table options.
+- **Rows** — default field names are `id`, `parent`, `kind`, `item`, `quantity`, `unit`,
+  `unitPrice`, `currency`, and `total`. `kind: 'group'|'subtotal'|'header'|'section'` is read-only;
+  other rows are editable. Parent references use Table's flat-data treegrid projection.
+- **Calculation boundary** — the default line total is quantity × unit price. Applications own
+  taxes, discounts, rounding, subtotal/group recalculation, optimistic persistence, and server
+  validation; provide `lineTotal` or cancel `editcommit` when product policy differs.
+<!-- /doc -->
+
+<!-- doc:chart -->
+### Chart and `ChartJsAdapter`
+
+An accessible, engine-neutral chart host. Zx renders state, canvas, semantic data summary, tokens,
+and lifecycle; an injected adapter owns the drawing engine. The Zx runtime imports no Chart.js
+code, so future adapters do not change the public `Chart` API.
+
+- **Options** — `adapter`, `type: 'bar'`, `data`, engine-specific `chartOptions`, `label`,
+  `description`, `summary: 'hidden'|'visible'`, `loading`, loading/empty/error text, and
+  `aspectRatio: '16 / 9'`.
+- **Methods** — `setData()`, `setType()`, `update(chartOptions)`, `setAdapter()`, `setLoading()`,
+  `setError()`, `clearError()`, `resize()`, `refreshTheme()`, `getInstance()`, `destroy()`.
+- **Events** — `ready {instance}`, `update {data, type}`, `select {datasetIndex, index, dataset,
+  label, value, nativeEvent}`, and `error {error}`.
+- **Adapter contract** — `adapter.create(canvas, {type, data, options, onSelect})` returns
+  `{update(spec), resize(), destroy(), instance?}`. Implementations must destroy engine resources
+  and must not retain the component after teardown.
+- **`ChartJsAdapter`** — construct it with a Chart.js constructor or namespace:
+  `new ChartJsAdapter(window.Chart)`. The documentation pins Chart.js 4.5.1 as a development-only
+  asset; `package.json` has no runtime dependencies and application builds explicitly choose how
+  the engine is loaded.
+- **Accessibility** — the canvas always has a name and optional description, while synchronized
+  labels and dataset values live in a semantic table. `summary: 'hidden'` keeps it visually hidden
+  for assistive technology; `'visible'` makes exact values part of the interface.
+<!-- /doc -->
+
 <!-- doc:data-filter -->
 ### DataFilter
 
@@ -927,6 +1154,76 @@ Beyond the built-in field types, these widget types wrap whole components, used
   `toggle` (Toggle).
 <!-- /doc -->
 
+<!-- doc:questionnaire -->
+### Questionnaire
+
+A guided, one-question-at-a-time flow: onboarding intake, a service-call checklist, an audit form,
+a feedback survey. The questionnaire owns the ordered items, the active one, the answers,
+validation, progress and navigation; the page, card, dialog or drawer around it owns closing,
+persistence and transport.
+
+The root is a real `<form>` and the choices are native radios and checkboxes carrying the item
+name, so `new FormData(questionnaire.toElement())` reads the answers, arrow keys inside a choice
+group are the browser's rather than ours, and the semantics do not depend on JavaScript. Three
+things separate it from a `Form` with one `Fieldset` per question: it branches, its answer control
+can be any registered `Field` type, and its validation may be asynchronous.
+
+- **Options** — `items: [{name, prompt, description?, section?, required?, multiple?, skippable?,
+  choices?, input?, field?, when?, next?, validate?}]`, `answers: {}` and `active: null` (the
+  resume pair), `progress: true`, `review: false`, `advance: 'manual'|'auto'`, `shortcuts: true`,
+  `allowBack: true`.
+- **Choices** — `[{value, label, description?, icon?, key?, disabled?, exclusive?}]`. `exclusive`
+  is the "None of the above" behaviour: picking it clears the rest of a `multiple` item, and
+  picking anything else clears it.
+- **Methods** — `setItems()`, `getItems()`, `goTo(name)`, `next()`, `previous()`, `skip()`,
+  `submit()`, `getAnswers()`, `getAnswer(name)`, `setAnswers(values, {silent})`,
+  `setAnswer(name, value, {silent})`, `getActive()`, `getPath()`, `getProgress()`, `getState()`,
+  `toFormData()`, `reset()`, `focus()`, `destroy()`. `next()`, `skip()` and `submit()` return
+  **promises** — `next()` because an item's `validate` may be asynchronous, and `skip()` because
+  skipping the last question submits. Everything else is synchronous.
+- **Events** — `change {name, value, answers}`, `navigate {from, to, reason}` **preventable**,
+  `skip {name}`, `invalid {name, message}`, `submit {answers, path}` **preventable**,
+  `complete {answers, path}`.
+- **Branching** — `when(answers)` decides whether an item is asked at all, and `next` (a name, or
+  `(answer, answers) => name`) decides what follows. Conditions **cascade**: each predicate sees
+  only the answers of visible items declared before it, so hiding the VAT question also hides
+  whatever depended on the VAT id. An answer to a conditioned-out question is kept internally —
+  walk back into the branch and it is still there — but is left out of `getAnswers()` and
+  `toFormData()`, so an abandoned branch never submits stale data. A `next` naming a hidden item
+  walks forward from it rather than stranding the reader; naming an item that does not exist
+  throws `RangeError`.
+- **Path and progress** — `getPath()` is the questionnaire's memory of the route walked, and
+  `previous()` pops it: once a branch has been taken, "previous" is not `index - 1`. `getProgress()`
+  returns `{index, answered, total, percent, section}` where `total` is the path plus the items
+  still reachable — exact for a static flow, an estimate once a function `next` can jump somewhere
+  the forward walk cannot predict.
+- **Field answers** — `field: {type: 'date'|'number'|'zxselect'|'rating'|'upload'|…}` hands the
+  answer to a `Field`, so any registered field type works, including ones an application registered
+  itself. The `<legend>` already asks the question, so the Field's own label is hidden from sight
+  but kept as the control's accessible name unless the item gives `field.label` explicitly; the
+  Field draws its own highlight, so a failing answer shows one message, not two.
+- **Validation** — `required` is checked synchronously; an item's `validate(answer, answers)` may
+  return a message, `null`, or a **promise** of either, and a rejection is reported as its message.
+  While the check is pending the root carries `data-state="checking"` and `aria-busy="true"` and
+  the actions are disabled.
+- **Review** — `review: true` shows a summary of every answer on the path before submitting, each
+  with an Edit that reopens that question; Continue from an edited question comes straight back to
+  the review rather than replaying the tail.
+- **Semantics** — the item is a `<fieldset>` and the prompt its `<legend>`; the description and the
+  error are associated through `aria-describedby`, the error is a `role="alert"`, and a failing
+  item carries `aria-invalid="true"`. `data-state` on the root is
+  `asking`, `checking`, `review`, or `complete`. Submitting does not replace the content: it sets
+  `data-state="complete"`, hides the actions, and emits `complete`, leaving the thank-you screen to
+  the application.
+- **Keyboard** — `1`–`9` then `a`–`z` pick the matching answer, assigned in choice order (an
+  explicit `key` is reserved first, so adding one never renumbers the others) and shown as a key
+  cap on each choice; the caps are `aria-hidden`, since a screen-reader user moves through the
+  group with the arrow keys the radios already provide. `Enter` continues, except in a `multiline`
+  input. Shortcuts are suppressed while focus is in a text control. Navigating moves focus to the
+  new question's fieldset, which is what gets the prompt announced; failing validation moves it to
+  the first answer control instead.
+<!-- /doc -->
+
 <!-- doc:value-list -->
 ### ValueList
 
@@ -991,19 +1288,6 @@ yet. Field type: `tagpicker`.
   within the list.
 <!-- /doc -->
 
-<!-- doc:permission -->
-### Permission
-
-Private / public / group record-permission selector. **Deprecated** — use
-`Select.permission(target, {groups})`, which carries the same tri-state value in one control and
-can query the groups remotely. This class stays for `gx.zeyos.Permission` and is removed in 3.0.
-
-- **Options** — `value: true|false|groupId`, `groups: []`, `groupsValueKey: 'ID'`,
-  `groupsLabelKey: 'name'`.
-- **Methods** — `get()` → `'private'|'public'|groupId`, `set(value)`.
-- **Events** — `change {value}`.
-<!-- /doc -->
-
 <!-- doc:groupbox -->
 ### Groupbox
 
@@ -1073,6 +1357,62 @@ markup with no JavaScript.
   because a CSS custom property cannot be used inside a media query.
 <!-- /doc -->
 
+<!-- doc:dock -->
+### Dock
+
+A stack of collapsible, resizable panes: the docked inspector column of a design tool, and the
+detail side of a master–detail screen. Give the root a size of its own (a grid area, `block-size:
+100%`, a flex child) when the panes should fill a shell rather than grow with their content.
+
+- **Options** — `orientation: 'vertical'`, `content: null`, `panes: []`, `resizable: true`,
+  `collapsible: true`, `lazy: true`, `storageKey: null`.
+- **Pane** — `{name, title?, content?, tabs?, active?, size?, min?, grow?, collapsed?,
+  collapsible?, side?}`. `content` takes a string, Node, Component, or a factory called on first
+  reveal. A pane with `tabs` renders its strip in place of the title; `content` is then ignored.
+  `side` (`'start' | 'end'`) only applies when the dock has a `content`.
+- **Tab** — `{name, title, content?}`, same content shapes.
+- **Methods** — `pane(name)`, `names()`, `add(pane, {index})`, `remove(name)`,
+  `collapse(name)`, `expand(name)`, `toggle(name)`, `isCollapsed(name)`, `reveal(name)`,
+  `setSize(name, size)`, `getSize(name)`, `activate(pane, tab)`, `getActive(pane)`,
+  `state()`, `setState(state)`, `adopt(sheet, options)`, `release(sheet)`.
+- **Adopting a Sheet** — `adopt(sheet, {name?, side?, index?, size?, min?, dockAt?})` takes over a
+  `Sheet`'s positioning: it becomes a track in the dock rather than an overlay. The dock owns
+  where it sits, its size, and its resizing; the sheet keeps its content, header, footer, events,
+  and its own `open()`/`close()`. `dockAt` names a breakpoint below which the dock hands the sheet
+  back to a free overlay and reclaims the track, re-adopting it above — measured on the **dock's
+  own width**, so a dock inside a split pane behaves correctly where a viewport media query would
+  not. Because a dock is a flex container by construction it is always a valid host, which is why
+  docking needs no arrangement from the application.
+- **Ownership** — the dock never owns an adopted sheet: `destroy()` releases them rather than
+  destroying them, `remove(name)` on a sheet releases it, and a sheet that destroys itself while
+  adopted drops out of the dock cleanly.
+- **Events** — `collapse {name}`, `expand {name}`, `resize {name, size}`,
+  `tabchange {pane, tab, previous}`, `reveal {name}`.
+- **Sizing** — one custom property per pane and one flex rule: a sized pane is
+  `flex: 0 0 var(--zx-pane-size)`, a collapsed one falls to `flex: 0 0 auto` with its body hidden,
+  and exactly one element grows. With a `content` that is always the content; without one it is the
+  pane declaring `grow`, or the last expanded pane. A drag therefore rewrites at most two
+  properties, and collapsing a pane feeds the grower rather than redistributing across the stack.
+- **Regions** — with `content` the dock is a region rather than a plain stack: panes sit on either
+  `side` of the flexible middle. Nesting one dock inside another dock's pane gives a workbench —
+  a canvas with an inspector column beside it.
+- **`reveal(name)`** — accepts a pane name or a tab name. Expands whichever pane holds it,
+  activates the tab when the name is a tab's, and scrolls it into view.
+- **Persistence** — `storageKey` remembers sizes, collapsed panes, and active tabs through
+  `storage()`, which degrades to memory rather than throwing. `state()`/`setState()` expose the
+  same shape for storing it elsewhere; unknown pane names are ignored, so a stored layout survives
+  a release that added or removed panes.
+- **Keyboard and screen readers** — each pane header is a row, not one big button, so the collapse
+  toggle and the tab strip can coexist; the toggle carries `aria-expanded` and `aria-controls`.
+  Tabs follow the APG tab pattern with one roving tab stop, Left/Right moving between them.
+  Dividers are focusable `separator`s carrying live `aria-valuenow`/`aria-valuemin`/`aria-valuemax`
+  in pixels: Up/Down (or Left/Right when horizontal) resize by 16px, Shift by 64px, and Enter or
+  Space collapses the pane before the divider. A divider with nothing to resize is taken out of the
+  tab order.
+- **Out of scope** — drag-to-rearrange, tear-off panels, and multi-column docks. All three are
+  additive without changing the API above.
+<!-- /doc -->
+
 <!-- doc:tabbox -->
 ### Tabbox — APG tabs
 
@@ -1178,12 +1518,67 @@ menu on narrow widths.
 - **Events** — `change {name}`.
 <!-- /doc -->
 
+<!-- doc:app-sidebar -->
+### AppSidebar — expanded application navigation
+
+Persistent vertical application navigation with header, scrollable tree, and sticky footer slots.
+It is route-agnostic: ZeyOS supplies native `href` values or handles cancelable selections through
+`PG.go()`. This expanded presentation is the only application-nav component that reveals children
+inline.
+
+- **Options** — shared application `items`, `active`, `expanded`, `collapsed`, `side: 'left'|'right'`,
+  `label`, and `header`, `footer`, `railHeader`, `railFooter` content slots.
+- **Methods** — `setItems()`, `setActive()`, `setExpanded()`, `getExpanded()`, `toggleBranch()`,
+  `expand()`, `collapse()`, `setCollapsed()`, `isCollapsed()`, `getRail()`, `destroy()`.
+- **Events** — cancelable `select {item, id, value, href, event}`,
+  `branchchange {item, id, expanded, ids}` (`item`, `id`, and `expanded` are null for a bulk
+  `setExpanded()`), and `collapsechange {collapsed}`.
+- **Minimized state** — collapse composes `AppRail` over the same normalized item tree. Expanded
+  branch IDs survive the round trip but are not rendered inline while minimized.
+- **Semantics** — persistent navigation uses `<nav>` and nested lists with native links and
+  disclosure buttons, not menu or menubar roles. A parent with children is disclosure-only; give
+  it an explicit Overview child when the parent also needs a destination.
+<!-- /doc -->
+
+<!-- doc:app-rail -->
+### AppRail — minimized application navigation
+
+The compact form of application navigation for left, right, top, or bottom placement. It can flow
+vertically or horizontally, but descendants are always anchored flyouts—never inline—and open
+toward the workspace.
+
+- **Options** — shared application `items`, `active`, `orientation: 'vertical'|'horizontal'`,
+  `side: 'left'|'right'|'top'|'bottom'`, `label`, `header`, `footer`, `openDelay: 80`, and
+  `closeDelay: 160`.
+- **Methods** — `setItems()`, `setActive()`, `getItems()`, `openFlyout(id, {focus})`,
+  `closeFlyout()`, `closeAllFlyouts()` (including pending hover/focus timers and descendant
+  branches), `isFlyoutOpen()`, `focus()`, `destroy()`.
+- **Events** — cancelable `select {item, id, value, href, event}` and
+  `flyoutchange {item, id, open}`.
+- **Pointer and focus** — hover or focus reveals a child collection without stealing focus. The
+  close delay covers the trigger-to-panel gap; leaving both trigger and panel closes it. Click,
+  Enter, Space, and the inward arrow also open it, so horizontal subnavigation is discoverable and
+  usable without hover. Escape, outside activation, or selection closes it.
+- **Semantics** — every icon-only destination retains a visible Tooltip and an accessible name.
+  Persistent rail destinations remain native links/buttons in a labelled navigation list; the
+  transient child flyout supplies its own arrow-key focus interaction.
+<!-- /doc -->
+
 <!-- doc:kernel -->
 ### Core helpers
 
 - **Component** — the base class: `on`/`off`/`once`/`emit`, `listen`, `toElement`, `msg`,
   `destroy`, and the static `Component.from(el)`.
-- **DOM** — `h(tag, props, ...children)`, `h.raw(html)`, `htmlEscape`, `resolveElement`.
+- **DOM** — `h(tag, props, ...children)`, `h.raw(html)`, `htmlEscape`, `resolveElement`. The current
+  ZeyOS builder is also first-class: `__(tag#id.class, properties, content)` is the migration alias
+  for `compactElement()`. It preserves `D*` data, `S*` style, boolean/built-in property, attribute,
+  and legacy `on*` callback rules while keeping content text-safe. `applyCompactProperties`,
+  `appendContent`, `appendCompact` (parent return), `appendCompactChild` (child return), and
+  `fragment(...children)` are the pure forms.
+- **Compact events** — `onCompactEvent`, `offCompactEvent`, and `fireCompactEvent` share one
+  newest-first handler registry. Existing `DOM.on/remEvt/fireEvt` methods can delegate to this
+  triad. Zx never installs globals or alters DOM prototypes; the current application owns those
+  temporary seams while `UI.new*` implementations are replaced without rewriting `PG` routing.
 - **Icons** — `icon(name, {size, label})` and `icons`; see the Icons section — bundled inline SVG
   by default, Font Awesome after an opt-in.
 - **Positioning** — `position(anchor, floating, {placement, offset, flip, matchWidth})` →
@@ -1328,8 +1723,9 @@ never imported by `src/index.js`, and adds nothing to an application that does n
 
 - **Loading** — classic: `<script src="/assets/zx-compat.global.js">` → `window.gx`; module:
   `import { gx } from '/assets/zx-compat.esm.js'` (or `src/compat/index.js` in-repo).
-  `gx.compat.installGlobals()` additionally installs the legacy free functions `__()`, `_()`,
-  `String.htmlSpecialChars`, and the element `store`/`retrieve` shim. `gx.install(host)` assigns
+  `gx.compat.installGlobals()` additionally installs the gx `__()` parser only when that name is
+  free, plus `_()`, `String.htmlSpecialChars`, and the element `store`/`retrieve` shim. It never
+  replaces ZeyOS's compact builder. `gx.install(host)` assigns
   the namespace without the optional globals.
 - **`gx.zeyos`** — Select/SelectFilter/SelectDyn/SelectPrio, Table, Tabbox, Panel, MasterPanel,
   Groupbox, Search, Datebox, DatePicker, MonthPicker, TimePicker, Timebox, Toggle, Msgbox, Popup,