@zeyos/zx 2.3.0 → 3.0.0

package/CHANGELOG.md

@@ -8,6 +8,93 @@ and friends remain the complete record.
 
 ## Unreleased
 
+## 3.0.0 — 2026-08-24
+
+### Added
+
+- **Xenon application shell components.** `Launcher` combines deterministic local ranking with
+  abortable grouped sources and a Cmd/Ctrl+K dialog; `Avatar` provides a stable initials fallback;
+  `AccountMenu` composes identity with an APG menu; `AppSidebar` is expanded vertical navigation;
+  and minimized `AppRail` keeps descendants in pointer-, focus-, and keyboard-accessible flyouts
+  for both vertical and horizontal placement. All route, permission, session, and persistence work
+  remains application-owned behind cancelable events.
+- **`Grid` and `Grid.BillingItems()`.** The public Table specialization keeps every Table feature
+  while providing a conventional editable billing schema for currencies, units, line totals, and
+  flat parent rows. The default line formula is quantity × unit price; tax, discount, rounding,
+  subtotal, validation, and persistence policy remain caller-owned.
+- **Engine-neutral `Chart` and injected `ChartJsAdapter`.** Chart owns responsive canvas lifecycle,
+  loading/empty/error states, Xenon theme defaults, point-selection events, and a synchronized
+  semantic data table. Chart.js 4.5.1 is pinned only as a development/documentation asset; the Zx
+  runtime has no chart import and no runtime dependency.
+- **Lateral anchored-overlay placement.** `position()`, `Dropdown`, `MenuButton`, and `Tooltip` now
+  accept left/right start/end variants for rail and account surfaces.
+
+- **`Questionnaire`** — a guided, one-question-at-a-time flow for onboarding intake, service
+  checklists, audits and surveys, where a `Form` full of fieldsets is the wrong shape. 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 and the keyboard contract inside a
+  choice group is the browser's. Three things go beyond a stack of fieldsets: an item carries a
+  `when` predicate and a `next` target, so the flow **branches** — conditions cascade, an
+  abandoned branch's answers drop out of `getAnswers()`, progress counts the questions actually
+  reachable, and Back retraces the path walked rather than an array index; an item's answer control
+  can be **any registered `Field` type** (`field: {type: 'date'}`), which is what lets a question
+  ask for a date, a number, a rating or an upload; and `validate` may return a **promise**, so a
+  question can be gated on a server check. `review: true` adds a summary screen with jump-back-to-
+  edit, `advance: 'auto'` moves on by itself after a single choice, and `1`–`9`/`a`–`z` shortcuts
+  are assigned and shown on each answer.
+
+- **`Sheet`** — an edge-anchored `Dialog` covering both side-sheet and mobile-drawer patterns;
+  the two differ only in which edge they take, so `side` (`'start' | 'end' | 'top' | 'bottom'`,
+  logical) replaces a second component. `modal` is three-way rather than a boolean because the
+  three real behaviours do not collapse into two: `true` hands focus containment, page inertness,
+  Escape and the backdrop to the browser via `showModal()`, while `'trap-focus'` and `false` open
+  non-modally and re-implement only what they still want. `backdrop: 'dim'|'blur'|'none'` applies
+  to modal sheets alone — `::backdrop` does not render for a non-modal dialog, and a painted
+  stand-in would make a non-blocking sheet look blocking. Entry **and exit** animate, which a
+  `<dialog>` normally cannot do, via `@starting-style` and `transition-behavior: allow-discrete`
+  on `display`/`overlay`. `resizable`, `snap` detents and swipe-to-dismiss are deliberately one
+  gesture whose meaning is decided when the pointer settles, so the sheet follows the pointer the
+  whole way instead of pinning at its minimum and then vanishing.
+- **`SheetStack`** — several sheets as one drill-down. Small on purpose: nested dialogs already
+  stack in the top layer by open order and Escape already closes only the topmost, so no z-index
+  bookkeeping and no unwinding logic. `stack` slides covered sheets back, scales them down and
+  makes them `inert`; `cascade` shifts each clear of the ones in front by their **measured** size
+  so they sit side by side and all stay usable — usually the right one for an ERP screen, where
+  the parent record should stay readable while a line item is edited.
+- **`Dock`** — a stack of collapsible, resizable panes: the docked inspector column of a design
+  tool, and the detail side of a master–detail screen. A pane is either titled or a **tab group**
+  whose strip replaces the title. Giving the dock a `content` turns it into a region with panes on
+  either `side` of it, and nesting one dock in another's pane gives a workbench. Sizes, collapsed
+  panes and active tabs persist through `storageKey`; content factories run on first reveal.
+- **`Dock.adopt(sheet)`** — a dock can take over a `Sheet`'s positioning, so the sheet becomes a
+  track in the dock's flow instead of an overlay. A dock is a flex container by construction and
+  therefore always a valid host, which is why docking needs no arrangement from the application.
+  `dockAt` hands the sheet back to a free overlay below a breakpoint measured on the **dock's own
+  width**, so a dock inside a split pane behaves correctly where a viewport media query would not.
+  Nothing is rebuilt across the 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.
+- **`--zx-overlay-blur`** — tier-2 semantic token behind `Sheet`'s `'blur'` backdrop, default `8px`.
+
+### Changed
+
+- **`SplitView` now shares one axis-drag engine with `Sheet` and `Dock`**, extracted to
+  `core/drag-axis.js`: pointer capture, one write per frame, telling a click from a zero-distance
+  drag, and the WAI-ARIA keyboard map. Behaviour is unchanged. `resolveSize` moved to the kernel
+  and is re-exported from `split-view.js`, so every existing import keeps working.
+- **`Modal` gained three protected seams** — `mountTarget()`, `_show()` and `_isRealClose()` — so a
+  subclass can live somewhere other than `document.body`, open non-modally, and re-host itself.
+  `Dialog`'s size application became the overridable `_applySize()`. No public behaviour changed.
+- **The modal scroll lock keys off `:modal` rather than `[open]`**, so a non-modal dialog no longer
+  locks the page behind it. `Modal` and `Dialog` always open modally, so neither is affected.
+
+### Removed
+
+- **`Permission` is removed**, not just deprecated. 2.3.0 kept the class around for
+  `gx.zeyos.Permission` while pointing new code at `Select.permission()`; there is no longer a
+  second implementation to keep in sync, and `gx.zeyos.Permission` now builds directly on
+  `Select.permission()` instead of wrapping the removed class. The legacy constructor, options,
+  `get()`/`set()`, and the `change` event are unchanged — only the `zx.Permission` export is gone.
+
 ## 2.3.0 — 2026-08-23
 
 ### Added

package/DESIGN-SYSTEM.md

@@ -0,0 +1,136 @@
+# Xenon design-system audit
+
+Audit date: 2026-08-24. Xenon is the design system; Zx is its dependency-free JavaScript
+implementation. This document records the current coverage against ZeyOS Classic and the work
+needed for an incremental adoption that keeps the existing routing and business logic.
+
+## System boundary
+
+Xenon has four layers:
+
+1. **Foundations** — semantic tokens, typography, spacing, density, themes, icons, motion, i18n,
+   accessibility rules, and the safe DOM kernel.
+2. **Components** — lifecycle-safe controls and containers with one options/events/destroy model.
+3. **Patterns** — repeatable business interactions such as global launch, account/preferences,
+   record detail, transaction entry, filtering, and empty/loading/error handling.
+4. **Application layouts** — rails, bars, workspaces, master/detail, dashboards, inboxes, wizards,
+   and responsive shell geometry.
+
+This separation follows the enterprise-system intent described by the
+[Carbon Design System](https://carbondesignsystem.com/all-about-carbon/what-is-carbon/) and
+[SAP Fiori design principles](https://experience.sap.com/fiori-design-web/design-principles/),
+without copying either system's code, assets, or component contracts.
+
+Zx currently has more than 50 public component classes, 63 registered documentation/demo entries,
+a generated API reference, bundled local icons, and no runtime dependency. The foundations,
+component layer, and persistent application shell now cover the first ZeyOS adoption wave; domain
+patterns remain intentionally application-owned until their business invariants are specified.
+
+## ZeyOS adoption boundary
+
+ZeyOS Classic does not use `gx`. Across its 30 module files it has roughly 2,500 `UI.*` calls and
+2,600 `PG.*` calls. `PG` already owns navigation, transport, history, exit guards, and page
+lifecycle and remains authoritative.
+
+The existing compact DOM surface has 2,668 executable builder calls: 871 bare `__()` calls, 1,710
+parent-returning `parent.__()` calls, and 87 child-returning `parent.$__()` calls. Zx now provides
+the exact compact builder plus pure append/property/event helpers. Existing global and prototype
+names remain application-owned delegation seams; Zx does not install or replace them.
+
+Migration therefore replaces `UI.new*` implementations one family at a time, keeps their current
+DOM/value contracts until call sites reach zero, and leaves `PG`, `MD`, routes, and server payloads
+in place. See [MIGRATION.md](./MIGRATION.md) for the ordering and shell invariants.
+
+## Coverage ledger
+
+| Capability in current ZeyOS | Xenon/Zx status | Decision |
+| --- | --- | --- |
+| Buttons, inputs, toggles, dates, selects, checklists, tags | Covered by public components | Replace `UI.new*` families incrementally and preserve value/event contracts. |
+| Forms and fieldsets | Covered, including component-backed field adapters | Use for record editors; keep validation/business rules application-owned. |
+| Dialogs, sheets, dropdowns, context menus, tooltips, messages | Covered | Consolidate duplicate menu behavior before building account/launcher surfaces. |
+| Tabs, panels, toolbar, breadcrumbs, stepper, split view, dock | Covered | Compose layouts; do not let navigation components own routes. |
+| Sorting, selection, filtering, pagination, trees/finder | Covered | Suitable for generic data screens. |
+| Editable billing/transaction rows | Covered at generic-grid level | `Grid.BillingItems()` composes typed editable currency/unit columns and flat hierarchy over `Table`. Tax, subtotal, posting, rounding, and persistence stay domain code. |
+| Global launcher/search | Covered | `Launcher` combines ranked local applications with abortable grouped sources. ZeyOS still filters the catalogue and resolves selection through `PG`. |
+| Account/profile/preferences menu | Covered at presentation level | `Avatar` and `AccountMenu` provide identity and action UI. ZeyOS supplies role-filtered actions and owns preferences, authentication, and logout. |
+| Persistent app rail / side navigation | Covered | `AppSidebar` is the expanded vertical tree; minimized `AppRail` uses flyouts in every orientation. Both are route- and persistence-agnostic. |
+| Charts and analytical summaries | Covered through an adapter | `Chart` is engine-neutral and accessible; `ChartJsAdapter` accepts an injected Chart.js 4 engine. Chart.js is documentation/test tooling only. |
+| Local product/module icons | Partial | Use bundled icons or registered local assets; do not require the optional remote Font Awesome kit. |
+| Domain entity selectors/cards/links | Partial | Build patterns on `Select`, Table, Panel, and ContextMenu after the shell blockers. |
+| Persistent notification/activity center | Missing, lower priority | `Message` covers ephemeral feedback, not read/unread activity history. |
+
+### Launcher contract
+
+The current launcher searches applications, recent records, and grouped remote record types. A
+replacement supplies pinned-order ranking, request cancellation, Cmd/Ctrl+K, listbox keyboard
+behavior, native link metadata, and a cancelable action. Permission filtering, active-route state,
+cache and recent-history policy remain inputs from ZeyOS, which resolves actions through `PG.go()`.
+The component is deliberately not a second router.
+
+### Account contract
+
+The current account surface includes identity, role-dependent links, language, authentication and
+logout, theme and menu-position preferences, and About/version content. A shared `Menu` should
+first centralize the keyboard/typeahead/selection behavior currently duplicated by `MenuButton`
+and `ContextMenu`; `AccountMenu` then composes that primitive with `Avatar`/`Identity` and emits
+actions without owning routes or session state. `AccountMenu` now provides that composition over
+`MenuButton`; a future shared low-level `Menu` remains an internal consolidation opportunity, not
+an adoption blocker.
+
+## Table and transaction follow-ups
+
+The enhanced `Table` now keeps values numeric while formatting per-row locales, currencies, units,
+and decimals; numeric types infer `NumberField` editors. Flat `parentId` data is projected into a
+cycle-safe ARIA treegrid with local sibling sorting and expand/collapse APIs.
+
+`Grid.BillingItems()` now packages the conventional description, quantity, unit, unit-price,
+currency, line-total, and hierarchy schema while retaining Table's editing contract. Useful
+follow-ups, deliberately separate from this generic preset:
+
+- summary/footer rows and grouped subtotals;
+- column reorder and user-persisted column state;
+- product-specific invoice/transaction presets with tax, discount, rounding, and formula golden tests;
+- server persistence, optimistic rejection, and undo owned by the application/controller layer.
+
+## Chart-engine candidates
+
+Chart.js was selected for the first adapter. It is pinned at 4.5.1 as a development dependency for
+tests and the documentation asset, but is never imported by Zx runtime source. Applications inject
+their chosen engine into the adapter. Published browser artifact sizes below are approximate and
+remain useful when choosing a different future adapter.
+
+| Engine | Current state at audit | Approx. browser cost | Best fit | Main trade-off |
+| --- | --- | ---: | --- | --- |
+| [Chart.js](https://github.com/chartjs/Chart.js/releases) 4.5.1 | Mature, active, MIT | 209 kB / 71 kB gzip (UMD) | Broad default: bar, line, doughnut, mixed business charts | Larger than focused engines; canvas requires a separate accessible data summary. |
+| [Frappe Charts](https://github.com/frappe/charts/releases) 1.6.x | Zero-dependency SVG, ERP-oriented, MIT | 69 kB / 18 kB gzip (UMD) | Lean dashboards with common chart types | GitHub release and npm publication were out of step; ecosystem and extension surface are smaller. |
+| [uPlot](https://github.com/leeoniya/uPlot) 1.6.32 | Active, MIT, highly optimized | 51 kB JS + 2 kB CSS / about 23 kB gzip | Dense time-series and operational telemetry | Deliberately narrow; not a general categorical/stacked business-chart toolkit. |
+| [Apache ECharts](https://echarts.apache.org/en/changelog.html) 6.1.0 | Very capable, active, Apache-2.0 | 1.12 MB / 369 kB gzip (full build) | Advanced analytical visualization | Too large as Xenon's default; only sensible as an opt-in advanced adapter or custom build. |
+
+Implemented architecture: `Chart` accepts an injected engine adapter, maps Xenon semantic tokens,
+owns loading/empty/error states, and mirrors its data in an accessible table. Chart.js is the broad
+default adapter; Frappe Charts remains the lean ERP-oriented alternative, uPlot a specialized
+time-series candidate, and ECharts an opt-in advanced adapter. Any additional package still
+requires explicit dependency approval.
+
+## Review corrections completed
+
+- Generated API records no longer let helper typedefs overwrite component options; inline JSDoc
+  tags are parsed, and audited runtime events are present in types and documentation.
+- Form documentation exposes `Form`, `Fieldset`, and `Field`; `MonthPicker` has its own constructor
+  type.
+- Theme Studio destroys registered component instances on every rebuild and describes its honest
+  family-level coverage.
+- Documentation separates Presets from green-accent Examples and uses callable preset names.
+- Current source and documentation no longer carry branding from the retired framework experiment.
+
+## Recommended sequence
+
+1. Ship the Zx runtime and delegate the current compact DOM/event seams; verify no navigation or
+   listener regressions.
+2. Mount `Launcher`, `Avatar`/`AccountMenu`, and `AppSidebar`/`AppRail` behind the current shell
+   fixtures, permission filters, and preference store.
+3. Replace high-volume `UI.new*` families, one discriminating fixture set at a time.
+4. Introduce `Grid.BillingItems()` where its generic schema fits; add domain presets only with
+   formula and rounding fixtures.
+5. Inject Chart.js into `ChartJsAdapter` only on analytical surfaces that need it; keep the engine
+   out of the base Zx runtime bundle.

package/MIGRATION.md

@@ -4,6 +4,136 @@ Zx replaces the MooTools-era `gx` UI libraries with dependency-free ES2022 modul
 compatibility bundle lets mapped legacy code keep running while classes are migrated one at a
 time. Compatibility constructors warn once per legacy class so remaining call sites are visible.
 
+Xenon is the ZeyOS design system; Zx is its browser implementation. A complete migration therefore
+means more than swapping constructors: foundations, components, application patterns, and layout
+contracts must move together while routing and business behavior stay authoritative.
+
+## Introducing Xenon into ZeyOS Classic
+
+The current ZeyOS Classic application is **not** a `gx.*` application. Its modules call the global
+`UI` factories, use `PG` for routing and page lifecycle, and rely on an extended DOM API including a
+CSS-like `__()` element builder. Do not call `gx.compat.installGlobals()` there: that opt-in helper
+preserves an existing `__()` but installs unrelated `gx` globals and prototype compatibility that
+the current application does not need.
+
+The migration does not need a separate application bridge. Zx now exports the established builder
+directly, including its exact compact tag and property conventions:
+
+```js
+const node = zx.__('button#save.primary', {
+  Daction: 'save',
+  onclick: () => save()
+}, 'Save');
+```
+
+Zx does not install globals or alter DOM prototypes. The current runtime keeps owning its global
+`__`, `_`, `Node._`, `Node.__`, `Node.$__`, and `Element.be` seams during the migration and delegates
+their bodies to `zx.compactElement()`, `zx.appendContent()`, `zx.appendCompact()`,
+`zx.appendCompactChild()`, and `zx.applyCompactProperties()`. Its `DOM.on`, `DOM.remEvt`, and
+`DOM.fireEvt` facade likewise delegates to Zx's shared compact-event helpers, so registration,
+removal, and synthetic firing always see the same handlers. Replace the implementations of
+`UI.new*` component families progressively with Zx components; do not insert a second routing or
+application abstraction between those components and `PG`.
+
+### Keep these authorities in place
+
+- `PG` remains responsible for URL construction, history, transport, exit guards, page dispatch,
+  and the `page:beforeUnmount` / `page:mounted` lifecycle.
+- Existing `MD` handlers and business logic continue receiving the same page data.
+- Existing `UI.new*` call sites keep their DOM return values and `getV` / `setV` / chaining
+  contracts while each factory implementation is replaced. New code uses the Zx component API
+  directly; the old factory is removed when its call-site count reaches zero.
+- Zx owns only the mounted component subtree and tears that subtree down exactly once.
+- New client/schema-driven screens may use `@zeyos/zx/zeyos`; adopting that optional layer is not a
+  prerequisite for converting current server-rendered screens.
+
+Safe bootstrap order is the normal Zx bundle, the current Classic runtime delegating its compact
+DOM seams to Zx, then the existing `Z(data)` application bootstrap. Component actions must call
+`PG.go()` for internal routes; do not let a navigation component fall back to `location.assign()`.
+
+### Recommended adoption waves
+
+1. Mount persistent shell components behind current lifecycle events: launcher, account menu,
+   application rail, detail chrome, and overlays.
+2. Replace the highest-volume `UI.new*` implementations—inputs, Selects, tabs, menus, dialogs, and
+   tables—one family at a time while preserving their existing call-site contract.
+3. Move record and transaction patterns only after old/new behavior has discriminating fixtures.
+4. Use direct Zx and the ZeyOS schema binding for new surfaces; retire an old factory only after its
+   remaining call-site count reaches zero.
+
+### Shell components and ownership
+
+`Search` remains a field-level input. `Launcher` is the shell-level application/record surface: it
+ranks local items, debounces and aborts grouped sources, ignores stale responses, and supplies the
+Cmd/Ctrl+K dialog/listbox interaction. ZeyOS filters permissions, supplies apps/recent records,
+decides caching, and handles the cancelable selection through `PG`; Launcher never becomes a
+router.
+
+`Avatar` and `AccountMenu` provide the identity trigger, profile header, grouped actions, focus
+return, and compact rail presentation. ZeyOS still decides permission-dependent routes, language
+and theme choices, authentication/logout, and About/version data. A selection is a request to the
+application, not a session mutation.
+
+`AppSidebar` is the expanded vertical application tree and is the only presentation with inline
+children. Its collapsed state renders `AppRail`. A standalone rail may be vertical or horizontal,
+but every child collection remains a hover/focus/keyboard flyout. Both components accept native
+links or cancelable actions and expose active/collapsed/expanded state without persisting it.
+
+Use bundled Zx icons or explicitly registered local assets. The optional ZeyOS icon helper's
+remote Font Awesome kit is not appropriate for a dependency-free production shell.
+
+### Persistent shell contract
+
+These invariants were validated while prototyping the replacement shell and remain binding for a
+Xenon implementation:
+
+- Application-menu position is `top`, `bottom`, `left`, `right`, or `none`, defaulting to `left`.
+  Persist it under `zeyos.appMenu.position` (scope-suffixed where separate workspaces share an
+  origin) and publish the resolved value on `:root[data-app-menu-effective]`.
+- Sidebar minimization is a user choice, never a hover side effect. Keep the existing
+  `zeyos.appRail.expanded` preference while migrating and map it to
+  `AppSidebar.setCollapsed(!expanded)`. `AppRail` itself never expands labels or inline children.
+- The minimized rail is 48 px and the expanded sidebar 184 px. The application bar is 48 px; tiles
+  are 30 px, glyphs 22 px, and compact controls 31 px. Workspace tools in a side layout remain
+  inside the rail, and page insets derive from the effective rail/bar geometry.
+- Theme preference is `auto`, `light`, or `dark`, persisted under `zeyos.theme` and applied before
+  paint. `auto` follows the system color-scheme media query.
+- The dark neutral ramp is a coal surface rebased from Carbon Gray 100 toward `#0b0c0e`. Avoid a
+  cyan/slate cast that competes with ZeyOS module colors; module accents must retain clear contrast
+  on both shell and content surfaces.
+
+### Migration proof points
+
+Before replacing any Classic surface, verify that internal navigation and browser history still use
+`PG.go()` without a full reload; page-scoped instances are destroyed exactly once; persistent shell
+listeners do not multiply across navigation or language changes; launcher output matches permission,
+app, recent, and search fixtures; account content matches ordinary/admin/developer roles; and the
+production shell loads no remote UI or icon dependency.
+
+The shell wiring stays direct:
+
+```js
+const launcher = new zx.Launcher(null, {
+  items: applicationCatalogue,
+  sources: recordSources,
+  onselect(event) {
+    event.preventDefault();
+    PG.go(resolveLauncherRoute(event.detail.item));
+  }
+});
+
+const sidebar = new zx.AppSidebar(shellHost, {
+  items: applicationTree,
+  active: currentRouteId,
+  collapsed: !savedAppRailExpanded,
+  footer: accountMenu,
+  onselect(event) {
+    event.preventDefault();
+    PG.go(event.detail.href);
+  }
+});
+```
+
 ## Deployment script swap
 
 For deployments that serve the old libraries directly from
@@ -25,8 +155,9 @@ with this order:
 ```
 
 The compatibility entry exposes both `window.zx` and `window.gx`. Element
-`store`/`retrieve`/`eliminate` is installed automatically. If the application uses `__()`, `_()`,
-`String.prototype.htmlSpecialChars`, or `Array.prototype.findBy`, opt in after both scripts load:
+`store`/`retrieve`/`eliminate` is installed automatically. If a genuine gx application uses its
+free parser, `_()`, `String.prototype.htmlSpecialChars`, or `Array.prototype.findBy`, opt in after
+both scripts load. An existing `__()` is deliberately never replaced:
 
 ```js
 gx.compat.installGlobals();
@@ -251,14 +382,14 @@ list.setValues([1, 2]);
 
 For remote data pass `load: () => Promise<items>` and listen for `loaded`.
 
-### `gx.zeyos.Permission` → `zx.Permission`
+### `gx.zeyos.Permission` → `zx.Select.permission()`
 
 ```js
 // gx
 const permission = new gx.zeyos.Permission(host, { value: true, groups });
 
 // Zx
-const permission = new zx.Permission(host, { value: 'public', groups });
+const permission = zx.Select.permission(host, { value: true, groups });
 permission.on('change', (event) => save(event.detail.value));
 ```
 
@@ -295,6 +426,26 @@ table.addData([{ ID: 1, name: 'Ada' }]);
 
 Use `setData`, `addData`, `updateRow`, `removeRow`, and `getData` for row operations.
 
+### Billing/transaction rows → `zx.Grid.BillingItems()`
+
+Use the generic preset when the existing screen has description, quantity, unit, unit price,
+currency, total, and optional parent rows:
+
+```js
+const items = zx.Grid.BillingItems(host, {
+  data: rows,
+  units: unitChoices,
+  currencies: currencyChoices,
+  oneditcommit(event) {
+    if (!controller.accept(event.detail.changes)) event.preventDefault();
+  }
+});
+```
+
+The default line total is quantity × unit price. Keep taxes, discounts, subtotal/group updates,
+rounding policy, posting, server persistence, and undo in the existing controller. Override
+`lineTotal` only when that calculation is a stable screen-level rule.
+
 ### `gx.zeyos.Tabbox` and `gx.bootstrap.Tabbox` → `zx.Tabbox`
 
 ```js

package/README.md

@@ -1,10 +1,13 @@
-# Zx
+# Xenon Design System (Zx)
 
-Zx is the dependency-free, vanilla-JavaScript component library for ZeyOS business applications:
-ES2022 modules, accessible native controls, semantic design tokens, and lifecycle-safe components.
-Source modules run directly in a browser; the distribution also provides ESM and classic-script
-bundles. An opt-in compatibility layer keeps existing MooTools-era `gx` code running while it is
-modernised.
+Xenon is the dependency-free design system for ZeyOS business applications; Zx is its
+vanilla-JavaScript implementation. It combines foundations, accessible components, repeatable
+workflow patterns, and application layouts in plain ES2022 modules. Source modules run directly in
+a browser; the distribution also provides ESM and classic-script bundles. An opt-in compatibility
+layer remains available for genuine MooTools-era `gx` applications while they are modernised.
+
+The [design-system audit](./DESIGN-SYSTEM.md) records current ZeyOS coverage, missing shell
+patterns, the adoption boundary, transaction-grid follow-ups, and chart-engine candidates.
 
 ## Quick start
 
@@ -95,7 +98,8 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 | `CheckButton` | Two-state pressed button with optional state-specific labels. |
 | `Toggle` | Native-button switch with a separate submitted value. |
 | `Search` | Search input with debounced input, submit, and clear events. |
-| `Select` | APG combobox with local or async filtering and a priority preset. |
+| `Launcher` | Cmd/Ctrl+K application and record launcher with ranked local items and abortable grouped sources. |
+| `Select` | APG combobox with local or async filtering, pinned fixed items, and priority/permission presets. |
 | `Checklist` | Searchable checkbox group with optional async loading. |
 | `TagPicker` | Multi-select combobox that keeps its selection as removable tags. |
 | `NumberField` | APG spinbutton with step buttons, ranges, units, and wrapping. |
@@ -122,12 +126,16 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 | `MenuButton` | APG menu button built on `Dropdown`. |
 | `ContextMenu` | APG right-click menu for a region or, via `selector`, per row. |
 | `Tooltip`, `tooltip()`, `describe()` | Hover/focus description bubble anchored with `position()`. |
+| `Avatar` | Fixed-size user image with initials fallback and optional presence. |
+| `AccountMenu` | Identity trigger and grouped account actions over `MenuButton`. |
 
 ### Data
 
 | API | Description |
 | --- | --- |
-| `Table` | Semantic sortable table with local/server sorting, row selection, and opt-in inline cell/row editing. |
+| `Table` | Sortable/selectable table with typed transaction columns, flat-data hierarchy/treegrid projection, and opt-in cell/row editing. |
+| `Grid`, `Grid.BillingItems()` | Table-compatible preset surface with editable currencies, units, totals, and sub-items. |
+| `Chart`, `ChartJsAdapter` | Accessible engine-neutral chart host and explicitly injected Chart.js adapter. |
 | `DataFilter` | Declarative select, text, and custom filters for client-side row sets. |
 | `TreeView` | APG tree with lazy children, filtering, and tri-state checkboxes. |
 | `Finder` | Miller-columns hierarchy browser with an optional preview pane. |
@@ -137,10 +145,10 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 
 | API | Description |
 | --- | --- |
-| `Permission` | Private, public, or group-level permission selector. |
 | `Field` | Label, description, validation state, and adapter-backed form control. |
 | `Fieldset` | Native fieldset that owns and coordinates fields. |
 | `Form` | Form composition, values, validation, highlighting, and actions. |
+| `Questionnaire` | Guided one-question-at-a-time flow: branching, path-aware progress, review. |
 | `ValueList` | Validated, sortable tag/chip editor. |
 | `MultiValueEditor` | Ordered editable rows with add, remove, and move controls. |
 | `FieldUpload` | Click/drop file upload with progress, abort, validation, and preview. |
@@ -154,6 +162,8 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 | `MasterPanel` | Full-height application panel with fixed header actions and footer. |
 | `Tabbox` | APG tabs in four appearances, with lazy content, closing, badges, and disabled states. |
 | `NavigationBar` | Responsive application navigation with optional tab panels and overflow. |
+| `AppSidebar` | Expanded vertical application navigation with inline disclosure children. |
+| `AppRail` | Minimized vertical/horizontal application navigation with flyout-only descendants. |
 | `Toolbar` | APG toolbar: one tab stop, arrow-key movement, and overflow into a menu. |
 | `SplitView` | Resizable two-pane split with a keyboard-operable separator. |
 | `Stepper` | Linear multi-step progress with completed, active, and error states. |
@@ -241,7 +251,7 @@ through, so a preset rethemes light, dark, and auto at once:
 
 Light surfaces take the 600 and 700 stops, dark ones take 300, 400, and 500 — so keep 600 legible
 against white and 400 against near-black, and `--zx-color-on-accent` stays correct in both. The
-[theme studio](https://zx.zeyos.com/theme.html) renders every component under a live theme and
+[theme studio](https://zx.zeyos.com/theme.html) renders every component family under a live theme and
 exports the result.
 
 Anything beyond the accent is a semantic token override, without reaching into component CSS:
@@ -273,7 +283,7 @@ JavaScript positioning fallback.
 
 ## Development
 
-Install the single development dependency and start the no-build demo server:
+Install the development toolchain and start the no-build demo server:
 
 ```sh
 npm install
@@ -318,12 +328,13 @@ During an incremental migration, load the global API before the compatibility bu
 <script src="/assets/zx.global.js"></script>
 <script src="/assets/zx-compat.global.js"></script>
 <script>
-  // Only when old code relies on __(), _(), or prototype conveniences:
+  // Only for gx-era free functions; an existing ZeyOS __() is preserved:
   gx.compat.installGlobals();
 </script>
 ```
 
 The compatibility bundle always exposes `window.gx` and installs only the element
 `store`/`retrieve`/`eliminate` shim automatically. Legacy globals and prototype conveniences are
-an explicit opt-in through `gx.compat.installGlobals()`. See [MIGRATION.md](./MIGRATION.md) for
+an explicit opt-in through `gx.compat.installGlobals()`; it never replaces an existing `__`.
+See [MIGRATION.md](./MIGRATION.md) for
 class mappings, script replacement, deliberate behavior changes, and unsupported legacy APIs.

package/dist/types/compat/map/data.d.ts

@@ -30,13 +30,14 @@ export declare class Checklist extends ChecklistBase {
 export declare class BootstrapChecklist extends ChecklistBase {
     static legacyName: string;
 }
-/** Legacy permission selector. */
+/** Legacy permission selector, backed by the `Select.permission()` preset. */
 export declare class Permission extends GxWrapper {
     static legacyName: string;
     /** @param {Element|string|null} display @param {Record<string, any>} [options={}] */
     constructor(display: Element | string | null, options?: Record<string, any>);
     /** @returns {unknown} */ get(): unknown;
-    /** @param {unknown} value @param {boolean} [silent=false] @returns {this} */ set(value: unknown, silent?: boolean): this;
+    /** @param {unknown} value @param {boolean} [silent=false] @returns {this} */
+    set(value: unknown, silent?: boolean): this;
 }
 /** Shared full Table wrapper. */
 declare class TableBase extends GxWrapper {