@zeyos/zx 3.0.0 → 4.1.0

package/docs/llms.md

@@ -1,6 +1,6 @@
 # Xenon Design System (Zx) — agent reference
 
-> Xenon is the dependency-free design system for ZeyOS business applications; Zx is its
+> Xenon is a dependency-free design system for browser applications; Zx is its product-agnostic
 > 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
@@ -73,6 +73,11 @@ renders every component family live and exports the CSS):
 Keep the 600 stop at 4.5:1 or better against white and the 400 stop at 4.5:1 against the dark page
 — that is what makes `--zx-color-on-accent` legible without being restated per theme.
 
+The theme studio treats those stable IDs as complete recipes: selecting a preset also changes its
+density, neutral tint, radius, control height, base text size, font stack, and material strength.
+Its **Material** control is CSS-first (`Flat`, `Glass`, or `Deep glass`); only the deep setting uses
+backdrop blur, and components fall back to solid surfaces under reduced-transparency preferences.
+
 Define a product theme by overriding **semantic** tokens under a `[data-zx-theme="name"]` selector:
 `--zx-color-bg-page/surface/raised/control/hover/selected`, `--zx-color-border(-strong/-control)`,
 `--zx-color-text(-muted/-placeholder)`, `--zx-color-accent(-hover)/on-accent`,
@@ -85,8 +90,8 @@ override that works (global token → then, if needed, a component style).
 
 For ZeyOS business data use the **dedicated client library** `@zeyos/client`
 (`npm install @zeyos/client`) — a zero-dependency, typed OpenAPI client (accounts,
-transactions/invoices, tickets, 50+ resources), OAuth2/session auth, retries, schema
-introspection. It replaces the legacy `gx.zeyos.Client` / `gx.zeyos.Request`.
+transactions/invoices, tickets, 50+ resources), OAuth2/session auth, retries, and schema
+introspection. Zx accepts the client by injection and does not bundle it.
 
 ```js
 import { createZeyosClient, MemoryTokenStore, normalizeListResult } from '@zeyos/client';
@@ -207,16 +212,6 @@ reflection and ElementInternals form association: `<zx-toggle>`, `<zx-check-butt
 `<zx-checklist>`, `<zx-datebox>`, `<zx-timebox>`, `<zx-search>`, `<zx-groupbox>`, `<zx-tabbox>`,
 `<zx-table>`, `<zx-dialog>`.
 
-## gx compatibility
-
-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 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`.
-
 ## Conventions (editing component source)
 
 Follow `AGENTS.md`. Key rules: never declare instance class fields for state used in `render()`
@@ -229,14 +224,13 @@ pattern with `:focus-visible` rings and `prefers-reduced-motion` guards.
 
 ```
 src/components/<name>/   component + CSS      src/core/   kernel (component, dom, http, i18n, date…)
-src/compat/              gx compat layer      styles/     tokens + base.css
 website/                 marketing page + docs.html (docs.js)          specs/  per-component specs
 website/demos/           per-component demo modules    website/layouts/  application layout examples
 tests/                   node unit + smoke    dist/       built bundles
 
 npm run serve   # http://127.0.0.1:8321/website/docs.html  (no build)
 npm test        # node --test tests/unit/*.test.js  +  node tests/lint-tokens.js
-npm run build   # dist/: zx.esm.js, zx.global.js (window.zx), zx-compat.global.js (window.gx), zx.css
+npm run build   # dist/: ESM, global, ZeyOS binding, and CSS assets
 node tools/build-module-tokens.js   # regenerate styles/tokens/modules.css from src/zeyos/modules.js
 ```
 
@@ -428,14 +422,16 @@ permissions, recent-history/cache policy, and the route or command ultimately in
 
 - **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})}]`,
+- **Options** — `items`, abortable `sources: [{id, label?, minQuery?, when?, order?, load(query, {signal})}]`,
   `query`, `debounce: 250`, `minQuery: 0`, `maxResults: 100`, `placeholder`, `label`, `emptyText`,
-  `loadingText`, and `shortcut: 'mod+k'|false`.
+  `loadingText`, `shortcut: 'mod+k'|false`, and visible `hints` labels (or `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.
+  invoke?, pinned?, disabled?, kind?, current?, when?, groupOrder?, itemOrder?}`. `icon` accepts a
+  bundled icon name, Node, or factory. Links stay native so modified and middle clicks work;
+  non-link commands may provide an application-owned `invoke` callback. Malformed and executable
+  URL schemes are stripped; a descriptor with no safe link or callback is disabled.
 - **Methods** — `open()`, `close()`, `toggle()`, `isOpen()`, `focus()`, `setQuery()`, `getQuery()`,
-  `setItems()`, `setSources()`, `destroy()`.
+  `setItems()`, `setCurrent()`, `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,
@@ -443,8 +439,39 @@ permissions, recent-history/cache policy, and the route or command ultimately in
   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.
+  editable controls, composition, and modal contexts. Application tiles use spatial arrow-key
+  movement; Up/Down may continue into record groups. Home/End, Page Up/Down, and Enter operate the
+  single listbox selection model; Escape closes and restores focus. `aria-current` marks the
+  active destination independently from the keyboard's `aria-selected` option.
+- **Optional ZeyOS adapter** — import `zeyosLauncher()` or `buildZeyosLauncherConfig()` from
+  `@zeyos/zx/zeyos`. The adapter receives the permitted module/menu catalogue, pins, current
+  identifier, recent loader or cache, abortable search, destination resolvers, and application/
+  record icon renderers explicitly. It maps the complete shell payload without reading globals or
+  taking over application routing.
+<!-- /doc -->
+
+<!-- doc:app-icon -->
+### AppIcon — application identity
+
+A fixed-size, product-agnostic application tile. It keeps glyph geometry stable in launchers,
+sidebars, entity results, and recent-item rows while identity colour and material remain explicit
+options rather than application globals.
+
+- **Options** — `icon` (bundled name, Node, or lazy renderer), `color`, `size: 36`,
+  `iconSize: '52%'`, `label`, `badge`, `selected: false`, `glass: false|'subtle'|'strong'`, and
+  additional `class` names.
+- **Methods** — `set(partialOptions)` updates the existing root; `destroy()` restores an enhanced
+  target. `appIcon(options)` is the element-returning convenience factory.
+- **ZeyOS preset** — import `zeyosAppIcon(module, options)` from `@zeyos/zx/zeyos`. Every current
+  ZeyOS application/module has a canonical colour and icon mapping in `src/zeyos/modules.js`;
+  entity names and aliases resolve through the same catalogue. `moduleChip()` is the compatible
+  alias. An application may call `useZeyosIcons()` for the existing custom glyph kit or inject an
+  offline `icon` override; Zx never loads a network asset automatically.
+- **Material** — subtle glass is a CSS border/highlight treatment; strong glass progressively adds
+  `backdrop-filter`. `prefers-reduced-transparency` and browsers without support receive a solid
+  tile. The glyph and label semantics do not depend on the visual treatment.
+- **Accessibility** — a non-empty `label` gives the root `role="img"`; otherwise it is decorative.
+  The badge is visual supplementary status, so include its meaning in `label` when it matters.
 <!-- /doc -->
 
 <!-- doc:avatar -->
@@ -485,26 +512,34 @@ out, or mutates the session.
 
 Unifies single-select, local filtering, and async loading.
 
-- **Options** — `items: []`, `fixedItems: []`, `valueKey: 'ID'` (string key or `(item)=>id`),
-  `labelKey: 'name'` (string or `(item)=>string`), `renderItem`, `renderValue`, `value`,
-  `disabled`, `placeholder`, `clearable: false`, `filter: false | 'local' | async (query)=>items`,
-  `searchKeys`, `minQuery: 0`, `debounce: 200`, `listHeight: 280`, `groupKey`.
+- **Options** — `items: []`, `fixedItems: []`, optional `fixedLabel`, `valueKey: 'ID'` (string key or `(item)=>id`),
+  `labelKey: 'name'` (string or `(item)=>string`), `renderItem`, `renderValue`,
+  `renderValueAdornment`, `renderNone`, `noneLabel`, `actions`, `value`, `disabled`, `placeholder`,
+  `clearable: false`, `filter: false | 'local' | async (query)=>items`, `searchKeys`,
+  `minQuery: 0`, `debounce: 200`, `listHeight: 280`, `groupKey`.
 - **Getters** — `.value`, `.selected`.
-- **Methods** — `set(id, {silent})`, `setItems()`, `setFixedItems()`, `reset()`, `open()`/`close()`,
-  `enable()`/`disable()`, `focus()`.
-- **Events** — `change {value, item}` (`item` is null on clear), `open`, `close`, `query {query}`,
-  `loaded {items}`.
+- **Methods** — `set(id, {silent})`, `setItems()`, `setFixedItems()`, `setActions()`, `reset()`,
+  `open()`/`close()`, `enable()`/`disable()`, `focus()`.
+- **Events** — `change {value, item}` (`item` is null on clear), preventable
+  `action {id, action, query, select}`, `open`, `close`, `query {query}`, `loaded {items}`.
 - **Fixed choices** — `fixedItems` pins entries to the top of the list, separated by a rule (the
   rule is dropped when `groupKey` is on, since a heading already divides them). They belong to the
   control, not to its data: a `filter` function replaces `items` on every query, while the pinned
   entries are narrowed locally against the same query and stay resolvable by `set()`. They survive
   `setItems()` and are shown below `minQuery`. Use them for choices with no row in the source —
   "Unassigned", "Everyone", "Private".
-- **Presets** — `Select.priority(target, opts)`, a 5-level priority picker;
-  `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`).
+- **Presets** — `Select.priority(target, opts)` renders the five-level, five-square ZeyOS priority
+  scale; `Select.status(target, opts)` supplies shape- and semantic-color-distinct workflow states
+  and accepts replacement `items`; `Select.permission(target, {groups, value})` pins Private and
+  Public above record-access groups. Its value is the tri-state ZeyOS stores (`false` private,
+  `true` public, or a group ID), and `groups` takes an array or loader `(query)=>items`.
+- **Entity preset** — `Select.entity(target, options)` renders icon/color, label, and secondary
+  text using `iconKey`, `colorKey`, and `subtitleKey` (or `renderIcon`). `recent` pins a deduplicated
+  **Recent** section above ordinary/local/async results; `create: true|actionDescriptor` appends an
+  application-owned command at the bottom without changing the selected ID. `recentLabel` and the
+  ordinary Select options remain overridable. For schema-driven ZeyOS loading,
+  `zeyosEntitySelect(client, resource, options)` and `buildZeyosEntitySelectConfig()` compose this
+  preset from `@zeyos/zx/zeyos`; the core preset itself is backend-neutral.
 - **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.
@@ -703,6 +738,8 @@ use `TimePicker` or `DateTimeBox`.
 
 Floating toasts come from statics; `new Message(target)` gives an inline, non-floating area with
 the same `.show()`. The toast region is `role="status"`/`aria-live` (`role="alert"` for errors).
+The shared floating region is fixed to the upper-right logical corner by default, sizes to its
+messages rather than the page, and uses the translucent glass surface tokens with a solid fallback.
 
 - **Statics** — `Message.info/success/warning/error(msg, opts)`,
   `Message.show(msg, { kind, timeout=4000, closable })` → `{ close() }`,
@@ -920,9 +957,9 @@ Two panes with a divider the user owns. The layout is a three-track CSS grid dri
 <!-- doc:table -->
 ### Table
 
-Sortable, selectable, sticky-header data table — one component covering both the legacy
-`gx.ui.Table` and `SimpleTable`. `fr` widths fill the container while px/auto widths scroll
-horizontally, and multi-select adds a tri-state header checkbox plus Shift+click range select.
+Sortable, selectable, sticky-header data table. `fr` widths fill the container while px/auto
+widths scroll 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?,
@@ -943,7 +980,8 @@ horizontally, and multi-select adds a tri-state header checkbox plus Shift+click
   `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).
+- **Editing** — `editMode: false|'cell'|'row'` (default `false`, and completely inert until set),
+  plus `editTrigger: 'double'|'single'` (Table defaults to double; Grid defaults to single).
   `'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).
@@ -976,7 +1014,8 @@ horizontally, and multi-select adds a tri-state header checkbox plus Shift+click
   commit with no changes emits `editcommit` with an empty `changes` map and leaves the data alone.
   Sorting, filtering, or `setData()` while editing cancels the edit cleanly and emits `editcancel`.
 - **Editing keyboard** — Enter or F2 on a focused editable cell starts editing (editable cells share
-  one roving tab stop), double-click starts editing without emitting `rowdblclick`, Enter commits and
+  one roving tab stop); the configured single/double pointer gesture starts it without emitting
+  `rowdblclick`. Enter commits and
   returns focus to the cell (Shift+Enter stays a newline in a `'textarea'`, Space toggles a
   `'checkbox'`), Escape cancels and returns focus to the cell, Tab commits and moves to the next
   editable cell (Shift+Tab the previous), wrapping across rows, and tabbing past the last editable
@@ -1002,6 +1041,14 @@ horizontally, and multi-select adds a tri-state header checkbox plus Shift+click
 - **Empty state** — `emptyText` takes a string, a Node, or a function returning one, so an empty
   table can carry an icon, an explanation, and the action that resolves it (`emptyState({…})`).
   A function is re-called on every render, which is what to use when the placeholder holds controls.
+- **Row order** — `rowReorder: true` adds a dedicated drag handle. Pointer drag moves rows before
+  or after a sibling; Space/Enter grabs/releases the same handle and ArrowUp/ArrowDown moves it for
+  keyboard users. `moveRow(id, targetId, position)` exposes the same guarded operation. Hierarchical
+  rows only move among siblings, and an active local sort disables manual order. A cancelable
+  `rowmove {row,id,target,targetId,position}` fires before `datachange`.
+- **Column visibility** — `columnVisibility: true` renders a chooser; `hiddenColumns` seeds it.
+  `getVisibleColumns()`, `getHiddenColumns()`, `setColumnVisible()`, and `toggleColumn()` preserve
+  caller column order and never allow the final visible column to disappear.
 <!-- /doc -->
 
 <!-- doc:grid -->
@@ -1011,9 +1058,11 @@ horizontally, and multi-select adds a tri-state header checkbox plus Shift+click
 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.
+- **Constructor** — `new Grid(target, tableOptions)` accepts the complete `Table` API and defaults
+  editable cells to a single-click trigger.
 - **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`.
+  schema for item, quantity, unit, unit price, currency, and line total. It enables single-click
+  editing, hierarchy, row reorder handles, and the column visibility chooser. 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.
@@ -1064,6 +1113,35 @@ Declarative client-side filter bar producing a filtered array, commonly wired to
 - **Events** — `filter {rows, state}`.
 <!-- /doc -->
 
+<!-- doc:filter -->
+### Filter — dynamic backend-neutral expressions
+
+An authoring component for typed, nested filter expressions. It never evaluates application data
+or interpolates query text: it emits a versioned, JSON-safe AST for an allowlisted application
+adapter to compile into its own backend query language.
+
+- **AST** — `{version: 1, root: {kind:'group', id, logic:'and'|'or', children}}`; children are
+  stable-ID groups or `{kind:'condition', id, field, operator, value}` records. Unknown field or
+  operator IDs survive parsing and render as unavailable/invalid instead of being silently lost.
+- **Fields** — `{id,label,type,operators?,defaultOperator?,choices?,loadChoices?,editor?,minQuery?,
+  debounce?}`. Built-in types cover text, number/money, date/datetime, boolean, enum/status/
+  priority/country/currency/unit/entity, and tags. Compatible operators and their arity come from
+  the exported `filterOperators` matrix; applications may explicitly override/add operator IDs.
+- **Options** — `fields`, `value`, `operators`, `allowGroups: true`, `maxDepth: 3`,
+  `maxConditions: 50`, `autoApply: false`, `readonly`, `disabled`, `applyLabel`, `clearLabel`.
+- **Methods** — `getValue()`, atomic `setValue()`, `addCondition()`, `addGroup()`, `update()`,
+  `remove()`, `move()`, `validate()`, `apply()`, `clear()`, `focus()`, `setReadonly()`,
+  `enable()`/`disable()`.
+- **Events** — `change {value,valid,errors,reason,nodeId}`, `apply {value}`, `invalid {errors}`,
+  and abortable async-choice lifecycle `query`, `loaded`, `error`. `apply()` returns null and
+  focuses the first invalid condition when validation fails.
+- **Pure exports** — `emptyFilterAst`, `filterCondition`, `filterGroup`, `parseFilterAst`,
+  `cloneFilterAst`, `cloneFilterValue`, `stringifyFilterAst`, and `validateFilterAst`.
+- **Boundary** — keep the AST in saved views/audit state and compile it in a backend-specific
+  adapter with an allowlist and bound parameters. Do not put SQL, URL query fragments, functions,
+  DOM nodes, Dates, non-finite numbers, or other executable/non-JSON values into conditions.
+<!-- /doc -->
+
 <!-- doc:tree -->
 ### TreeView
 
@@ -1274,10 +1352,13 @@ shows a fixed set, and `ValueList` takes free text with no catalogue. Unknown ID
 `setValues` still render as tags, so a stored selection survives a catalogue that has not loaded
 yet. Field type: `tagpicker`.
 
-- **Options** — `items`, `values: []`, `valueKey: 'ID'`, `labelKey: 'name'`, `searchKeys`,
+- **Options** — `items`, `values: []`, `valueKey: 'ID'`, `labelKey: 'name'`, `iconKey: 'icon'`,
+  `colorKey: 'color'`, `searchKeys`,
   `filter: 'local'|(query)=>Promise<items>`, `minQuery: 0`, `debounce: 200`, `allowCreate: false`,
   `max` (maximum tags; further options become `aria-disabled`), `closeOnSelect: false`,
   `placeholder`, `listHeight: 260`, `disabled`, `readonly`, `renderItem`, `renderTag`.
+- **Tag identity** — icon values accept a bundled icon name or Node; colors are scoped to the tag
+  and its option through `--zx-tag-color`. Custom `renderItem`/`renderTag` remain authoritative.
 - **Methods** — `getValues()`, `getItems()`, `setValues(values, {silent})`, `addValue()`,
   `removeValue()`, `clear()`, `reset()`, `setItems()`, `isFull()`, `open()`/`close()`, `focus()`,
   `setReadonly()`, `enable()`/`disable()`.
@@ -1298,6 +1379,30 @@ Collapsible titled section built on the native `<details>` element.
 - **Events** — `open`, `close`.
 <!-- /doc -->
 
+<!-- doc:card -->
+### Card
+
+A semantic content or record surface. Card is intentionally not a Panel preset: it has no
+disclosure state or application chrome, and composes as one repeated item in a grid or list. A
+linked Card keeps the root non-interactive and renders a real title anchor as its primary action,
+so buttons and links in its action, content, and footer regions remain valid sibling controls.
+
+- **Options** — `title: ''`, `media: null`, `content: null`, `actions: []`, `footer: null`,
+  `link: null|string|{href, target?, rel?, onclick?}`, `variant: 'outlined'|'raised'|'filled'`,
+  `orientation: 'vertical'|'horizontal'`, `headingLevel: 3`.
+- **Methods** — `setTitle()`, `setMedia()`, `setContent()`, `setActions()`, `setFooter()`,
+  `setLink()`.
+- **Content** — media, body, and footer accept text, a Node, a Component, or null. Enhanced target
+  children become body content when no explicit content is supplied, and `destroy()` restores the
+  target exactly.
+- **Interaction** — `link` stretches the native title anchor across the visual surface; secondary
+  controls stay above it and are never nested inside it. A linked card requires a non-empty title.
+  Executable/data URL schemes are rejected. Commands belong in `actions`, and selectable cards
+  should compose a native checkbox or radio.
+- **Layout** — horizontal media uses the public `--zx-card-media-size` hook and stacks through a
+  container query when the card itself becomes narrow.
+<!-- /doc -->
+
 <!-- doc:panel -->
 ### Panel / MasterPanel
 
@@ -1519,49 +1624,36 @@ menu on narrow widths.
 <!-- /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()`.
+### AppSidebar — application navigation in every presentation
+
+One route-agnostic application-navigation owner with an expanded vertical tree, a minimized
+vertical rail, and horizontal rail layouts. It mounts exactly one presentation at a time while
+preserving active and expanded branch state. Only the expanded vertical state reveals descendants
+inline; every rail state opens descendants toward the workspace in anchored flyouts.
+
+- **Options** — `items`, `active`, `expanded`, `collapsed`, `collapsible`,
+  `orientation: 'vertical'|'horizontal'`, `side: 'left'|'right'|'top'|'bottom'`, `label`,
+  `header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`, and
+  `renderIcon(item, context)`. Icon values may also be names, nodes, components, or factories.
+- **Methods** — `setItems()`, `getItems()`, `setActive()`, `setExpanded()`, `getExpanded()`,
+  `toggleBranch()`, `expand()`, `collapse()`, `setCollapsed()`, `isCollapsed()`,
+  `setLayout({orientation, side})`, `openFlyout(id, {focus})`, `closeFlyout()`,
+  `closeAllFlyouts()`, `isFlyoutOpen()`, `focus()`, `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
+  `branchchange {item, id, expanded, ids}`, `collapsechange {collapsed}`, 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.
+- **Presentation state** — horizontal navigation is always effectively minimized and never exposes
+  an expand control. Switching layouts does not erase the saved vertical collapsed preference or
+  expanded branch IDs. `AppSidebar` is the single public application-navigation component; use
+  `collapsed: true` or `orientation: 'horizontal'` for its rail presentations.
+- **Pointer and focus** — hover or focus reveals rail descendants without stealing focus. Click,
+  Enter, Space, and the arrow toward the workspace also open a flyout; Escape, outside activation,
+  or selection closes it. Expanded navigation supports arrows plus Home/End across visible rows.
+- **Semantics** — persistent navigation uses `<nav>` and nested lists with native links and
+  disclosure buttons, not menu or menubar roles. Icon-only destinations retain an accessible name
+  and Tooltip. A parent with children is disclosure-only; add an Overview child when it also needs
+  a destination. Malformed and executable URL schemes are stripped; an item with no remaining
+  link or callback is disabled in every presentation.
 <!-- /doc -->
 
 <!-- doc:kernel -->
@@ -1569,16 +1661,16 @@ toward the workspace.
 
 - **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`. 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,
+- **DOM** — `h(tag, props, ...children)`, `h.raw(html)`, `htmlEscape`, `resolveElement`.
+  `__(tag#id.class, properties, content)` is Zx's compact DOM builder and public 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.
+  triad. Zx never installs globals or alters DOM prototypes; applications decide whether to expose
+  these functions globally or compose them into their own UI and routing layer.
 - **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})` →
@@ -1714,40 +1806,6 @@ bug wearing a layout costume, while a tooltip that is always there is noise.
   `data-lines` plus `--zx-truncate-lines` select the multi-line form.
 <!-- /doc -->
 
-<!-- doc:gx-compat -->
-### gx compatibility layer
-
-Opt-in re-implementation of the legacy MooTools-era `gx` API on top of Zx, so existing ZeyOS
-screens keep running while their code is modernised file by file. It lives in its own bundle, is
-never imported by `src/index.js`, and adds nothing to an application that does not load it.
-
-- **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 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,
-  Dialog, Dropdown, Checklist, Permission, Client, Request, Factory.
-- **`gx.bootstrap`** — Form, Fieldset, Field, the Select variants, Checklist, Table, Tabbox,
-  NavigationBar, MenuButton, Message, Popup/PopupAlert/PopupConfirm, CheckButton, DataFilter,
-  ValueList, MultiValueEditor, FieldUpload, Timebox.
-- **`gx.util`** — `formatNum`, `formatTime`, `getMinutes`, `getNumber`, `printf`, `parseResult`,
-  `Parse`, `isArray`/`isObject`/`isFunction`/`isString`/`isNumber`/`isElement`/`isNode`,
-  `Console`.
-- **`gx.ui`** — Container, SimpleTable, Timebox, and the inert visual-effect stubs
-  Blend/Collapse/Hud/Toggling/HGroup/Templates. **`gx.core`** — Settings. **`gx.compat`** —
-  installGlobals, installElementStorage, parse, GxWrapper.
-- **Migrating off it** — legacy classes collapse onto fewer Zx components: all four Select
-  variants → one `Select` with a `filter` option; `gx.ui.Table` + `SimpleTable` → one `Table`;
-  `Msgbox`/`bootstrap.Message` → `Message`; `Popup`/`PopupAlert`/`PopupConfirm` → `Modal`/`Dialog`
-  with Promise-returning statics; `gx.zeyos.Client`/`Request` → `@zeyos/client`. Anything that
-  depended on MooTools prototype extensions is gone. `MIGRATION.md` has the full map and the
-  deliberate behaviour changes; `website/compat.html` runs legacy snippets against Zx as a smoke
-  test.
-<!-- /doc -->
-
 <!-- doc:elements -->
 ### Custom elements — `defineElements()`
 

package/docs/llms.txt

@@ -1,10 +1,10 @@
 # Xenon Design System (Zx)
 
-> Xenon is the dependency-free design system for ZeyOS business applications; Zx is its
+> Xenon is a dependency-free design system for browser applications; Zx is its product-agnostic
 > vanilla-JavaScript implementation. ES2022 modules, WAI-ARIA-accessible native
 > controls, semantic `--zx-*` design tokens with light/dark/density theming, and lifecycle-safe
 > components. Source modules run directly in the browser; a build step emits ESM, IIFE-global,
-> gx-compatibility, and CSS bundles. Zero runtime dependencies.
+> ZeyOS binding, and CSS bundles. Zero runtime dependencies.
 
 Instantiate every component as `new Component(target, options)` where `target` is an Element, a
 selector string, or `null` (the component creates and owns its root, retrieved via `.toElement()`).
@@ -13,45 +13,48 @@ Subscribe with `.on(type, fn)` or an `on<type>` option; handlers receive a `Cust
 exports and as `window.zx.*`.
 
 ## Documentation
-- [Documentation site](../website/docs.html): getting started, every component with a live demo and its JavaScript source, and the application layouts. Machine index: [website/llms.txt](../website/llms.txt).
-- [README](../README.md): what Zx is, quick start (ESM + global script), component index, theming, browser support, gx compat.
+- [Documentation site](https://zx.zeyos.com/docs.html): getting started, every component with a live demo and its JavaScript source, and the application layouts. Machine index: [llms.txt](https://zx.zeyos.com/llms.txt).
+- [README](../README.md): what Zx is, quick start (ESM + global script), component index, theming, and browser support.
 - [API reference](llms.md): per-component constructor options, methods, and events for all public components plus the core helpers.
-- [Skill](../.claude/skills/zx/SKILL.md): task-oriented guide — mental model, recipes, ZeyOS HTTP client, theming, gotchas, commands.
+- [Skill](https://zx.zeyos.com/skills/zx/SKILL.md): task-oriented guide — mental model, recipes, ZeyOS HTTP client, theming, gotchas, commands.
 - [Changelog](../CHANGELOG.md): what changed in each release, including behaviour changes an upgrade has to account for.
-- [Migration guide](../MIGRATION.md): gx→zx class map, script-tag replacement, deliberate behavior changes, unsupported legacy APIs.
-- [Contributor contract](../AGENTS.md): conventions for editing component source (token rules, render-time state, listeners, ARIA/APG).
+- [Contributor contract](https://github.com/zeyos/zx/blob/main/AGENTS.md): conventions for editing component source (token rules, render-time state, listeners, ARIA/APG).
 
 ## Components
 - Inputs and identity: `button()`, `buttonGroup()`, `badge()`/`badgeGroup()`, `CheckButton`,
-  `Toggle`, `Search`, `Launcher`, `Avatar`, `AccountMenu`, `Select` (APG combobox;
-  `filter: false|'local'|async`), `Checklist`, `TagPicker`, `NumberField`, `Rating`, `Slider`,
+  `Toggle`, `Search`, `AppIcon` (+ `zeyosAppIcon()` presets), `Avatar`,
+  `Select` (APG combobox; `filter: false|'local'|async`; priority, status, permission, and
+  `Select.entity()` presets), `Checklist`, `TagPicker` (icon/color identity), `NumberField`, `Rating`, `Slider`,
   `copyButton()`/`CopyInput`, `DatePicker`, `MonthPicker`, `TimePicker`,
   `Datebox`/`DateTimeBox`, `DateRangePicker`/`DateRangeBox`, `Timebox`.
 - Overlays: `Message` (toasts/inline/progress), `Modal`, `Dialog` (+ `alert`/`confirm`/`prompt` Promises), `Sheet` (edge-anchored Dialog; `side`, `modal: true|'trap-focus'|false`, `backdrop`, `snap` detents, swipe-to-dismiss), `SheetStack` (drill-down; `stack`/`cascade`), `Dropdown`, `MenuButton`, `ContextMenu` (right-click; `selector` for per-row menus), `Tooltip`/`tooltip()`/`describe()`.
-- Data: `Table` (sortable, selectable, sticky header, opt-in inline cell/row editing via
-  `editMode`), `Grid` with `Grid.BillingItems()`, engine-neutral `Chart` with injected
-  `ChartJsAdapter`, `DataFilter`, `Pagination` (+ pure `paginationRange()`), `TreeView` (APG tree),
+- Data: `Table` (sortable, selectable, sticky header, opt-in inline cell/row editing, row reorder,
+  column visibility), `Grid` with single-click editing and `Grid.BillingItems()`, engine-neutral
+  `Chart` with injected `ChartJsAdapter`, backend-neutral nested `Filter`, simple client-side
+  `DataFilter`, `Pagination` (+ pure `paginationRange()`), `TreeView` (APG tree),
   `Finder` (Miller columns).
 - Forms: `Form`, `Fieldset`, `Questionnaire` (guided one-question-at-a-time flow with branching), `Field` (type registry), `ValueList`, `MultiValueEditor`, `FieldUpload`.
 - Layout: `stack()`/`grid()`/`aspect()` (spacing, an intrinsically reflowing grid, a fixed-ratio
-  box), `Groupbox`, `Panel` (header/footer action buttons), `MasterPanel`, `Tabbox`
-  (`variant: 'divided'|'bracket'|'line'|'segmented'`), `NavigationBar`, expanded `AppSidebar`,
-  minimized `AppRail`, `Toolbar` (APG toolbar with overflow menu), `SplitView`, `Dock`
+  box), `Groupbox`, `Card` (media/title link/actions/footer), `Panel` (header/footer action
+  buttons), `MasterPanel`, `Tabbox`
+  (`variant: 'divided'|'bracket'|'line'|'segmented'`), `NavigationBar`, `AppSidebar` (expanded and
+  minimized vertical states plus horizontal rail layouts), `AccountMenu`, `Launcher`,
+  `spinner()`/`ProgressBar`/`InlineLoading`, `skeleton()`/`skeletonText()`/`skeletonTable()`,
+  `Toolbar` (APG toolbar with overflow menu), `SplitView`, `Dock`
   (collapsible resizable pane stack; tab groups, regions, adopts a `Sheet`), `Stepper`,
   `Breadcrumb`, `emptyState()`.
-- Feedback: `spinner()` (unknown duration), `ProgressBar` (known share; determinate or indeterminate), `InlineLoading` (a wait resolving into its outcome in place), `skeleton()`/`skeletonText()`/`skeletonTable()` (placeholders shaped like the content; `aria-hidden`, set `aria-busy` on the region).
-- Core: `Component`, `h`/`icon`, `position`, `breakpoints`/`breakpointOf`/`matchBreakpoint`/`onBreakpoint` (named width bands, observed on an element or the window), `Http`/`zeyosService`, i18n, date utils, `defineElements` (declarative `<zx-*>` custom elements).
+- Core: `Component`, `h`/`__`/`icon`, `position`, `breakpoints`/`breakpointOf`/`matchBreakpoint`/`onBreakpoint` (named width bands, observed on an element or the window), `Http`/`zeyosService`, i18n, date utils, `defineElements` (declarative `<zx-*>` custom elements).
 - Helpers: `formatNumber`/`formatCurrency`/`formatPercent`/`formatFileSize`/`formatRelativeTime` (locale-aware, cached `Intl`), `debounce`/`throttle`, `groupBy`/`sortBy`/`uniqueBy`, `escapeRegExp`/`highlightMatch`, `storage()` (namespaced JSON, degrades to memory), `toCsv`/`downloadBlob`/`copyToClipboard`, `truncate()`/`isTruncated()` (line clamp with the full value on hover).
 
 ## Theming
-Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) and `data-zx-density` (`cozy`|`compact`) on any ancestor. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. Never use tier-1 palette tokens or raw color literals in application CSS.
+Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) and `data-zx-density` (`cozy`|`compact`) on any ancestor. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. The theme studio controls accent, neutral tint, density, font, type size, radius, control height, and CSS-first glass material. Never use tier-1 palette tokens or raw color literals in application CSS.
 
 ## Talking to ZeyOS
-Use the dedicated ZeyOS client library **`@zeyos/client`** (`npm install @zeyos/client`) for ZeyOS business data: `createZeyosClient({ platform, auth })`, typed `client.api.list/get/create/update<Resource>` over the full OpenAPI surface, `normalizeListResult`. It replaces the legacy `gx.zeyos.Client`/`gx.zeyos.Request`. See the `website/layouts/zeyos-invoices.layout.js` layout for a Zx-components-on-@zeyos/client reference. Zx also ships a minimal `Http`/`zeyosService` for ad-hoc in-app `remotecall`, but `@zeyos/client` is the recommended default.
+Use the dedicated ZeyOS client library **`@zeyos/client`** (`npm install @zeyos/client`) for ZeyOS business data: `createZeyosClient({ platform, auth })`, typed `client.api.list/get/create/update<Resource>` over the full OpenAPI surface, and `normalizeListResult`. Zx accepts the client by injection and does not bundle it. See the `website/layouts/zeyos-invoices.layout.js` layout for a Zx-components-on-@zeyos/client reference. Zx also ships a minimal `Http`/`zeyosService` for ad-hoc in-app `remotecall`, but `@zeyos/client` is the recommended default.
 
 ## Installing
-`npm install @zeyos/zx`. Entry points: `.` (components), `./zeyos` (ZeyOS binding), `./compat`
-(gx namespace), `./zx.css` (styles), `./global` (classic script tag). Docs: https://zx.zeyos.com
+`npm install @zeyos/zx`. Entry points: `.` (components), `./zeyos` (ZeyOS binding), `./zx.css`
+(styles), and `./global` (classic script tag). Docs: https://zx.zeyos.com
 
 ## Commands
 `npm run serve` (no-build documentation at http://127.0.0.1:8321/website/docs.html) · `npm test` (unit + token lint) · `npm run build` (dist bundles).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zeyos/zx",
-  "version": "3.0.0",
-  "description": "Dependency-free JavaScript implementation of the Xenon Design System for ZeyOS.",
+  "version": "4.1.0",
+  "description": "Dependency-free JavaScript implementation of the Xenon Design System.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://zx.zeyos.com",
@@ -25,9 +25,7 @@
   "sideEffects": [
     "*.css",
     "./dist/zx.global.js",
-    "./dist/zx.global.min.js",
-    "./dist/zx-compat.global.js",
-    "./dist/zx-compat.global.min.js"
+    "./dist/zx.global.min.js"
   ],
   "exports": {
     ".": {
@@ -38,23 +36,15 @@
       "types": "./dist/types/zeyos/index.d.ts",
       "default": "./dist/zx-zeyos.esm.js"
     },
-    "./compat": {
-      "types": "./dist/types/compat/index.d.ts",
-      "default": "./dist/zx-compat.esm.js"
-    },
     "./global": {
       "types": "./dist/types/index.d.ts",
       "default": "./dist/zx.global.js"
     },
-    "./compat-global": {
-      "types": "./dist/types/compat/index.d.ts",
-      "default": "./dist/zx-compat.global.js"
-    },
     "./zx.css": "./dist/zx.css",
     "./zx.min.css": "./dist/zx.min.css",
-    "./src/*.js": {
-      "types": "./dist/types/*.d.ts",
-      "default": "./src/*.js"
+    "./src/components/*.js": {
+      "types": "./dist/types/components/*.d.ts",
+      "default": "./src/components/*.js"
     },
     "./styles/*": "./styles/*",
     "./dist/*": "./dist/*",
@@ -68,13 +58,14 @@
     "dist/types",
     "styles",
     "src",
+    "!src/compat",
+    "!src/compat-entry.js",
     "docs/llms.md",
     "docs/llms.txt",
     "docs/api.json",
     "CHANGELOG.md",
     "README.md",
     "DESIGN-SYSTEM.md",
-    "MIGRATION.md",
     "LICENSE"
   ],
   "engines": {