@zeyos/zx 5.2.0 → 5.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/api.json CHANGED
@@ -1914,6 +1914,30 @@
1914
1914
  "type": "string|null",
1915
1915
  "default": "null",
1916
1916
  "description": "Accessible collection label; null resolves message `cardView.label`, \"Card view\"."
1917
+ },
1918
+ {
1919
+ "name": "keyboard",
1920
+ "type": "'tabs'|'roving'",
1921
+ "default": "'tabs'",
1922
+ "description": "Keyboard model. `'tabs'` makes every card, title link, checkbox, and action its own Tab stop. `'roving'` — recommended for lists — follows the APG Grid pattern with row focus: the collection is one Tab stop, the arrow keys, Home/End, and PageUp/PageDown move between cards, Enter activates, Space selects, and the controls inside a card stay pointer targets with `tabindex=\"-1\"`."
1923
+ },
1924
+ {
1925
+ "name": "collapsibleGroups",
1926
+ "type": "boolean",
1927
+ "default": "false",
1928
+ "description": "Whether group headings carry a toggle that hides and shows the group's cards."
1929
+ },
1930
+ {
1931
+ "name": "collapsedGroups",
1932
+ "type": "unknown[]",
1933
+ "default": "[]",
1934
+ "description": "Group ids that start collapsed."
1935
+ },
1936
+ {
1937
+ "name": "renderGroupHeading",
1938
+ "type": "((context:CardGroupHeadingContext)=>Node|string|null|undefined)|null",
1939
+ "default": "null",
1940
+ "description": "Content of a group heading in place of its label. With `collapsibleGroups` it is placed inside the toggle button, so it must not contain interactive elements."
1917
1941
  }
1918
1942
  ],
1919
1943
  "events": [
@@ -1921,6 +1945,11 @@
1921
1945
  "name": "recordaction",
1922
1946
  "payload": "Record<string,unknown>",
1923
1947
  "description": ""
1948
+ },
1949
+ {
1950
+ "name": "groupcollapse",
1951
+ "payload": "{id:string,collapsed:boolean,collapsedGroups:string[]}",
1952
+ "description": ""
1924
1953
  }
1925
1954
  ],
1926
1955
  "methods": [
@@ -1936,6 +1965,18 @@
1936
1965
  "returns": "this",
1937
1966
  "description": "Restores shared and CardView configuration. Unknown shared fields reconcile in RecordView."
1938
1967
  },
1968
+ {
1969
+ "name": "setGroupCollapsed",
1970
+ "signature": "setGroupCollapsed(id, [collapsed], [options])",
1971
+ "returns": "this",
1972
+ "description": "Collapses or expands one group. A collapsed group keeps its heading and hides its cards."
1973
+ },
1974
+ {
1975
+ "name": "getCollapsedGroups",
1976
+ "signature": "getCollapsedGroups()",
1977
+ "returns": "string[]",
1978
+ "description": "Returns the collapsed group ids."
1979
+ },
1939
1980
  {
1940
1981
  "name": "destroy",
1941
1982
  "signature": "destroy()",
package/docs/llms.md CHANGED
@@ -3,7 +3,9 @@
3
3
  > Xenon is a dependency-free design system for browser applications; Zx is its product-agnostic
4
4
  > vanilla-JavaScript implementation. ES2022 modules, WAI-ARIA-accessible native controls, semantic `--zx-*` design
5
5
  > tokens (light/dark, one token-driven geometry), and lifecycle-safe components. Zero runtime dependencies.
6
- > This file is the single, complete reference a coding agent needs to build UI with Zx; each
6
+ > This file is the single, complete reference a coding agent needs to build UI with Zx. Read
7
+ > "Choosing what to build with" first: it maps every screen to a layout to start from, every job to
8
+ > its component, and lists the theme settings to decide. Each
7
9
  > component below is wrapped in `<!-- doc:<name> -->` markers so tools can extract a single
8
10
  > component's section (`website/docs.html` renders them as each component's Reference tab).
9
11
 
@@ -47,6 +49,178 @@ const t = new Table(target, options);
47
49
  - Styles: load `/assets/zx.css` once.
48
50
  - Build bundles with `npm run build` (esbuild). No build is needed to develop against `src/`.
49
51
 
52
+ ## Choosing what to build with
53
+
54
+ Three decisions come before any code: which **layout** the screen is, which **component** does
55
+ each job, and which **theme settings** the application pins. The library already answers most of
56
+ them. A screen that invents its own shell, table, menu, or colour is the exception to justify,
57
+ never the default — it costs the accessibility, keyboard map, theming, and print behaviour the
58
+ standard parts already have.
59
+
60
+ ### Start from a layout, not a blank page
61
+
62
+ Every layout in the gallery (<https://zx.zeyos.com/layouts>, `layouts.html#<id>` opens one,
63
+ `layout.html#<id>` shows it alone) is a complete, working screen on one shared application shell,
64
+ and its source is public: `https://zx.zeyos.com/layouts/<id>.layout.js` with `<id>.layout.css`
65
+ (in the repository, `website/layouts/`). Open the closest one, keep its anatomy — the columns,
66
+ the pane headers, the toolbar, the drawers, the states, the keyboard map — and change the data,
67
+ the fields, and the copy.
68
+
69
+ The helpers a layout imports are public too, and meant to be copied beside application code
70
+ (they are documentation-site modules, not package exports; import them relatively):
71
+
72
+ - `layouts/kit.js` + `kit.css` — the shell: `.shell` and its columns, `paneHeader()`,
73
+ `propList()`, `.list-row`, `.surface`, `suiteNav()` (module strip + module menu, with a
74
+ `workspace` switcher), `adaptiveShell()` (every column stays reachable at any width),
75
+ `shortcuts()` and `shortcutSheet()` (`?`), `toast()`, `loadChartJs()`.
76
+ - `layouts/overview.js` + `overview.css` — `createOverview()`: one toolbar over one record set
77
+ shown as table, list, cards, gallery, or board; search; filters as editable chips with a Filters
78
+ drawer; a View settings drawer; grouping, sorting, paging, selection and bulk actions; a base
79
+ filter for tabs and scopes; split empty states. The record collection, CRM, and issue tracker
80
+ are all this one composition.
81
+
82
+ Which layout a screen is:
83
+
84
+ | The screen | Start from | Not from |
85
+ | --- | --- | --- |
86
+ | A list of records of one type (companies, tickets, orders, files) | **Record collection** (`record-collection`) — the toolbar, chips, drawers and pager come with it | a bare `Table` under a heading |
87
+ | A list beside the record being edited | **Master–detail** (`master-detail`) | two unrelated panes |
88
+ | One record on its own page | **Record page** (`record-page`) | a form |
89
+ | Figures, charts, a period switch | **Dashboard** (`dashboard`) | cards of big numbers |
90
+ | Settings in sections | **Settings workspace** (`settings-workspace`) | one long form |
91
+ | Creating something in steps | **Record wizard** (`record-wizard`, vertical steps) or **Checkout wizard** (`checkout-wizard`, horizontal) | tabs |
92
+ | Conversations, triage | **Inbox** (`inbox`) or the **Mail** template | — |
93
+ | An assistant | **Agent chat** (`agent-chat`, one run with tools and approvals) or the **AI chat** template | a chat bubble list |
94
+ | Empty, loading, error, offline, confirmation | **System states** (`system-states`) — every screen needs these; copy them | ad-hoc messages |
95
+ | A whole application | the closest **template** below; they share one shell | a new shell |
96
+
97
+ Templates — complete applications with navigation, lists, records, and editors together:
98
+
99
+ | id | Screen | Use it for |
100
+ | --- | --- | --- |
101
+ | `mail` | Mail | a keyboard-first inbox: split streams, one-key triage, snooze, inline reply |
102
+ | `issue-tracker` | Issue tracker | work items grouped by status or on a board, chips, sub-items, activity, properties edited in place |
103
+ | `wiki` | Knowledge base | nested pages in spaces, a reading column with a live outline, comments, Markdown editing |
104
+ | `ai-chat` | AI chat | chat with an assistant: tool steps, sources, artifacts with versions, per-chat settings |
105
+ | `agent-workspace` | Agent workspace | a team of agents: roster with presence, plans and logs, approvals, a palette, a terminal |
106
+ | `invoice-editor` | Invoice editor | a document edited beside its live page, totals per rate, a send step that locks it |
107
+ | `item-inventory` | Item & inventory | one master-data record: levels per location, linked documents, tabbed settings, a log |
108
+ | `workflows` | Workflows | recurring processes as step flows: built, run, measured |
109
+ | `infrastructure` | Infrastructure | monitoring: health, alerts, traffic, drill-down to the unit |
110
+ | `crm` | CRM | companies, people, deals: editable collections with saved views, record pages, a stage board |
111
+
112
+ Patterns — single screens that recur in every application:
113
+
114
+ | id | Screen | What it shows |
115
+ | --- | --- | --- |
116
+ | `master-detail` | Master–detail | a filterable list beside the record being edited; save, revert, unsaved-change checks |
117
+ | `record-collection` | Record collection | one record type as table, list, cards, gallery, and board under one toolbar; filter chips and drawers |
118
+ | `dashboard` | Dashboard | figures, a chart, tabbed detail, one period switch redrawing all of it |
119
+ | `inbox` | Inbox | three panes: folders, conversations, the open thread with a reply |
120
+ | `record-page` | Record page | one record: summary header, tabs for lines, files and history, editable details |
121
+ | `agent-chat` | Agent chat | one agent run: plan, tool calls, an approval that holds it, a streamed answer with sources |
122
+ | `record-wizard` | Record wizard | creation in validated vertical steps with a running total and a review |
123
+ | `checkout-wizard` | Checkout wizard | a focused horizontal flow beside a live summary |
124
+ | `settings-workspace` | Settings workspace | personal settings in sections, saved together |
125
+ | `system-states` | System states | every empty, loading, error, and confirmation state, with an offline switch |
126
+ | `zeyos-invoices` | ZeyOS invoices | a table and a form generated from the ZeyOS schema, beside the ZeyOS module navigation |
127
+
128
+ Every application shares one shell: `AppSidebar` (or `ModuleBar` for the module level) with
129
+ `AccountMenu`, a `WorkspaceSwitcher` where users have several workspaces, a `Launcher` as the
130
+ command palette, `?` for the shortcut sheet, and `data-zx-theme` honoured throughout. Do not design
131
+ a second navigation.
132
+
133
+ ### The component for the job
134
+
135
+ | Job | Use | Rather than |
136
+ | --- | --- | --- |
137
+ | Records the user scans, sorts, selects | `Table`; `TableView` when the same records also appear as cards or a board | a styled `<table>`, a list of `<div>`s |
138
+ | Records as cards or a gallery | `CardView` (`keyboard: 'roving'`, `groupBy`, `collapsibleGroups`) | `Card`s in a CSS grid |
139
+ | Records by stage, dragged between columns | `KanbanView` | — |
140
+ | One record set, several presentations, one state | `RecordView` family + `ListToolbar` + `ViewSettings` + `Pagination` — `createOverview()` wires them | three components with three states |
141
+ | The bar above a record view | `ListToolbar` (search, live count, view switch, badged tools) | a row of buttons |
142
+ | Sorting outside a header | `SortControl` | two selects |
143
+ | Paging | `Pagination` (`paginationRange()` for the numbers) | — |
144
+ | Filters, quick and client-side | `DataFilter` | — |
145
+ | Filters typed from a server's field metadata | `FilterPanel` (`mode: 'draft'|'live'`) | — |
146
+ | Filters the user composes, nested, serialisable | `Filter` (an AST; `parseFilterAst()`/`stringifyFilterAst()`) | — |
147
+ | A spreadsheet-like editable grid (lines, positions) | `Grid` (`Grid.BillingItems()`) | `Table` with `editMode` — that is for occasional cell edits |
148
+ | A tree | `TreeView` (one column) or `Finder` (Miller columns) | nested `<ul>`s |
149
+ | Events over time | `Calendar` (agenda, day, week, month, year) | — |
150
+ | One number with context | `StatTile` (delta, sparkline, loading) | a card with a big figure |
151
+ | A chart | `Chart` with `ChartJsAdapter` (Chart.js injected, never bundled) | — |
152
+ | A linked record inline | `EntityRef` | a link |
153
+ | Files | `FileItem` / `FileList`; uploading: `FieldUpload` | — |
154
+ | History, comments, a feed | `ActivityItem` / `ActivityList` | — |
155
+ | Choose one of many | `Select` (`filter: 'local'` or async for long lists; `Select.entity()` for records; `Select.priority()` / `Select.status()` presets); native radios for a handful of visible options | a custom dropdown |
156
+ | Choose many | `TagPicker` (identity, colour, icons), `Checklist` (a plain list) | — |
157
+ | On or off | `Toggle` (takes effect at once), `CheckButton` (a mode in a toolbar), a native checkbox inside a form | — |
158
+ | Search | `Search` | an input with an icon |
159
+ | Number, date, time, range | `NumberField`, `Datebox` / `DateTimeBox`, `Timebox`, `DateRangeBox`, `Slider`, `Rating` | plain inputs |
160
+ | A form | `Form` → `Fieldset` → `Field` (the type registry); `Questionnaire` for one question at a time | hand-laid inputs |
161
+ | Structured text, code | `CodeEditor` | a textarea |
162
+ | Repeating values | `ValueList`, `MultiValueEditor` | — |
163
+ | Confirm, alert, prompt | `Dialog.confirm()` / `Dialog.alert()` / `Dialog.prompt()` (Promises) | `window.confirm` |
164
+ | A task in a window | `Dialog` (header, footer, buttons); `Modal` is the bare surface | — |
165
+ | Edit without leaving the list | `Sheet` (`side: 'end'`); drill-down: `SheetStack`; a persistent pane: `Dock` | a dialog |
166
+ | Transient status | `Message.success()` / `.info()` / `.warning()` / `.error()` (toasts); inline `Message` for a region | an alert bar built by hand |
167
+ | Actions on a thing | `MenuButton`; `ContextMenu` (right-click and Shift+F10; one instance per table via `selector`) | a floating `<div>` |
168
+ | Anchored content, hints | `Dropdown`; `tooltip()` / `describe()` | `title` attributes alone |
169
+ | A row of actions | `Toolbar` (overflow menu, one Tab stop) | a flex row of buttons |
170
+ | Navigation | `AppSidebar` (tree, sections, `layout: 'modules'`), `ModuleBar`, `NavigationBar`, `Tabbox` (in-page), `Breadcrumb` (where am I), `Stepper` (a sequence) | — |
171
+ | Commands by keyboard | `Launcher` | — |
172
+ | Account and workspace | `AccountMenu`, `WorkspaceSwitcher` | — |
173
+ | Grouping content | `Card`, `Panel` (actions in the header or footer), `Groupbox`, `MasterPanel`, `SplitView`, `stack()` / `grid()` / `aspect()` | ad-hoc wrappers |
174
+ | Identity and status marks | `Avatar`, `AppIcon`, `badge()` (`kind` says how it is doing, `tone` what it is) | coloured spans |
175
+ | Nothing yet, loading, failed | `emptyState()`, `skeleton()` / `skeletonText()` / `skeletonTable()`, `InlineLoading`, `spinner()`, `ProgressBar` | a blank area |
176
+ | Ambient colour behind a hero, a login, a launcher | `Aurora` | CSS gradients |
177
+ | Icons | `icon(name)` — the bundled set or Font Awesome, whichever the application opted into | inline SVG |
178
+
179
+ ### Theming decisions
180
+
181
+ Decide these once per application, in this order, and express each as the attribute or token
182
+ the library already reads — never as component CSS:
183
+
184
+ 1. **Theme** — `data-zx-theme="auto"` unless the product pins `light` or `dark`. Both must work; a
185
+ region may differ from the page.
186
+ 2. **Accent** — a preset (`data-zx-preset="zx|zeyos|ocean|violet|rose|slate"`) or a five-stop
187
+ `--zx-accent-300…700` ramp built in the theme studio (<https://zx.zeyos.com/theme.html>), which
188
+ exports the CSS. Never a one-off colour on a button.
189
+ 3. **Geometry** — the rhythm is three tokens on `:root` (or on a dense region): `--zx-space-unit`,
190
+ `--zx-control-height`, `--zx-radius`. Dense data tools sit around 3.5px / 28px; comfortable
191
+ products around 4.5px / 32–34px. Never a per-component size.
192
+ 4. **Material** — how surfaces answer light, exported from the studio as token overrides (there
193
+ is no attribute). `Glass` (the default: a thin lit pane), `Deep glass` (a thick one), `Frost`
194
+ (milk glass for reading surfaces), `Smoke` (tinted glass that darkens the scene; dark-first
195
+ products), `Paper`, `Satin` and `Enamel` (opaque: matte, brushed or glazed; no blur, so they
196
+ render cheaply and never depend on what is behind them), or `Flat`. `Aurora` supplies the light glass responds to. Reduced-transparency,
197
+ high-contrast, forced-colour and unsupported-filter environments fall back to solid surfaces on
198
+ their own.
199
+ 5. **Motion** — `data-zx-motion="reduced"` is the only switch; own transitions use `--zx-dur-*`,
200
+ `--zx-ease`, `--zx-ease-spring`, `--zx-ease-drawer`.
201
+ 6. **Colour roles** — `--zx-color-tone-*` for categories (tags, modules, avatars),
202
+ `--zx-color-danger|warning|success|info` for status, `--zx-color-bg-current` for "you are here"
203
+ and `--zx-color-bg-selected` for "what you picked", `--zx-color-bg-chrome` for navigation and
204
+ inspector columns. A module's colour is its `tone` on `ModuleBar`.
205
+ 7. **Type** — `--zx-font-sans`, `--zx-font-mono`, `--zx-text-md` (the control size); the steps
206
+ follow.
207
+ 8. **Fields** — `data-zx-fields="quiet"` on property panels (no border or fill until hovered or
208
+ focused).
209
+ 9. **Print** — works without work; keep status badges, hide chrome. Nothing to add.
210
+ 10. **Markup-first pages** — `defineElements()` for `<zx-*>` custom elements where templates are
211
+ authored as HTML.
212
+
213
+ ### Never
214
+
215
+ - No raw colours (`#hex`, `rgb()`, named), no tier-1 tokens (`--zx-gray-*`, `--zx-emerald-*`,
216
+ `--zx-tone-*`), no hard-coded sizes the geometry tokens cover.
217
+ - No application CSS on component internals (`.zx-<component>__<part>` selectors); override a
218
+ token, or use a published hook.
219
+ - No hand-built dropdowns, menus, dialogs, tooltips, tables, date pickers, or toasts.
220
+ - No `innerHTML` with data; `h()` and text nodes.
221
+ - No state classes; state is ARIA and `data-state`, which the stylesheets already match.
222
+ - No second shell, second navigation, or second keyboard convention inside one application.
223
+
50
224
  ## Theming
51
225
 
52
226
  Load `zx.css`, then set the theme on any ancestor (usually `<html>`):
@@ -90,16 +264,31 @@ Keep the 600 stop at 4.5:1 or better against white and the 400 stop at 4.5:1 aga
90
264
 
91
265
  The theme studio treats those stable IDs as complete recipes: selecting a preset also changes its
92
266
  spacing unit, neutral tint, radius, control height, base text size, font stack, and material strength.
93
- Its **Material** control is CSS-first (`Flat`, `Glass`, or `Deep glass`). Aurora is the independent
94
- ambient canvas layer; material controls how surfaces respond to that light. The shared recipe
95
- applies to AppIcons, ordinary controls, persistent chrome, raised cards, and every transient overlay: Dropdown, ContextMenu,
96
- MenuButton, AccountMenu, AppRail flyouts, Select, TagPicker, date pickers, tooltips, column menus,
97
- and toasts use `--zx-color-overlay-surface`; Launcher, Modal, Dialog, and overlay Sheets use the
98
- calmer `--zx-color-overlay-panel`. Both tiers combine a translucent base, responsive specular and
99
- Aurora tint layers, backdrop filtering, and dedicated state/divider roles; the modal backdrop is a
267
+ Its **Material** control is CSS-first: eight materials, each a set of token overrides (there is no
268
+ attribute), composed from six per-theme *ingredients* the stylesheet declares —
269
+ `--zx-color-glass-rim` and `-ring` (the lit top edge and the hairline inner ring), `-lift` (white
270
+ laid on a pane from its top edge, which makes it read as lit rather than tinted), `-shade` (the
271
+ pane's own body: a veil over the scene, white in light and black in dark, that bounds what the
272
+ scene can do to text contrast), `-edge` (the cut outer line a pane needs against a dark scene) and
273
+ `-tint` (smoked glass) — plus `--zx-glass-grain`, a faint grey tooth. One recipe therefore
274
+ serves light and dark alike. **Glass**, the stylesheet default, is a thin lit pane: its light sits
275
+ on the edge, never as a wash on its face, and the filter saturates so colour behind survives the
276
+ blur. **Deep glass** is a thick pane — a double rim with an inner glow, one narrow specular band,
277
+ more refraction, a fine grain. **Frost** is milk glass: heavy diffusion, almost no reflection, text
278
+ as on paper. **Smoke** is tinted glass that darkens what is behind it (sunglass glass in dark).
279
+ **Paper** is opaque and matte, depth from a contact shadow and a modest cast; **Satin** is opaque
280
+ and brushed, a soft sheen across raised surfaces and a bright rim on controls; **Enamel** is an
281
+ opaque body under a glossy coat, a narrow highlight along the top edge and a darker foot, for
282
+ terminals and consoles where text backing must be certain. None of the three filters anything,
283
+ so they render cheaply and survive every fallback unchanged. **Flat** is the opaque semantic
284
+ surfaces. Aurora is
285
+ the independent ambient canvas layer; material is how surfaces respond to that light. The shared
286
+ recipe applies to AppIcons, ordinary controls, persistent chrome, raised cards, and every transient
287
+ overlay: Dropdown, ContextMenu, MenuButton, AccountMenu, AppRail flyouts, Select, TagPicker, date
288
+ pickers, tooltips, column menus, and toasts use `--zx-color-overlay-surface`; Launcher, Modal,
289
+ Dialog, and overlay Sheets use the calmer `--zx-color-overlay-panel`. The modal backdrop is a
100
290
  separate material token so it does not erase the light the panel should refract. A docked Sheet is
101
- layout rather than an overlay and becomes opaque, as do dense data surfaces. Glass and Deep glass
102
- progressively raise translucency, blur, highlights, and elevation; reduced-transparency,
291
+ layout rather than an overlay and becomes opaque, as do dense data surfaces. Reduced-transparency,
103
292
  increased-contrast, forced-colour, and unsupported-filter environments restore solid surfaces.
104
293
  Top-layer components remain DOM children of their nearest Zx theme scope, so a theme or material
105
294
  set on an application region continues to inherit through its menus, dialogs, tooltips, and toasts.
@@ -1700,8 +1889,13 @@ portable state as TableView and KanbanView.
1700
1889
 
1701
1890
  - **Options** — the shared RecordView options plus `titleField`, `subtitleField`, `preview`,
1702
1891
  `previewAlt`, `link`, `actions`, `groupBy`, `groupOrder`, `minCardWidth`, `maxColumns`,
1703
- `variant: 'outlined'|'raised'|'filled'`, `loadingCount`, `headingLevel`, and `label` (null
1704
- resolves message `cardView.label`, "Card view").
1892
+ `variant: 'outlined'|'raised'|'filled'`, `loadingCount`, `headingLevel`, `label` (null
1893
+ resolves message `cardView.label`, "Card view"), `keyboard: 'tabs'|'roving'` (default `'tabs'`),
1894
+ `collapsibleGroups`, `collapsedGroups`, and `renderGroupHeading`.
1895
+ - **Methods** — the shared RecordView methods plus `setGroupCollapsed(id, collapsed, {silent})` and
1896
+ `getCollapsedGroups()`. **Events** — the shared set plus `recordaction` and
1897
+ `groupcollapse {id, collapsed, collapsedGroups}` (also a `statechange` with reason
1898
+ `'groupcollapse'`). The view state carries `collapsedGroups`.
1705
1899
  - **Messages** — `cardView.label`, `cardView.sort`, `cardView.sortCards`, `cardView.unsorted`,
1706
1900
  `cardView.sortAscending`/`cardView.sortDescending` (`%1` the field), `cardView.ungrouped`
1707
1901
  ("Ungrouped"), `cardView.groupEmpty` ("No records in this group."), `table.empty` for the empty
@@ -1728,6 +1922,29 @@ portable state as TableView and KanbanView.
1728
1922
  a stable fallback. Title/action links are normalized; `_blank` links receive `noopener`.
1729
1923
  - **Grouping and layout** — `groupBy` is a field ID or callback; `groupOrder` may deliberately show
1730
1924
  empty groups. Cards reflow through container queries and may cap columns without viewport logic.
1925
+ - **Keyboard model** — `keyboard: 'roving'` is the recommended setting for lists; `'tabs'` stays the
1926
+ default for compatibility, and makes every card, title link, checkbox, and action its own Tab
1927
+ stop (44 stops for 22 selectable cards). `'roving'` follows the WAI-ARIA APG **Grid** pattern with
1928
+ row focus, the same model as `Table`: the content is `role="grid"` (`aria-multiselectable` for
1929
+ `multi`), each card a `row` with `aria-selected` when selectable, and the collection is one Tab
1930
+ stop. Grid rather than listbox because a card holds a link and buttons, which a listbox option
1931
+ would flatten. ArrowUp/ArrowDown move to the card above or below — columns are measured from the
1932
+ rendered positions, and the column you travel in is remembered — ArrowLeft/ArrowRight within a
1933
+ row, Home/End to the first or last card, PageUp/PageDown by a visible page. Enter activates
1934
+ (`recordclick`), Space toggles selection in `selectable` modes (activates otherwise),
1935
+ Shift+movement extends a `multi` selection, Ctrl/Cmd+A selects every rendered card. Title links,
1936
+ checkboxes, and actions get `tabindex="-1"`: they still work with the pointer, and Enter on the
1937
+ card is the keyboard route. The current card is kept by record id across `setData`, sorting,
1938
+ grouping, and collapsing, and focus is restored with `preventScroll`. Focus shows as an inset
1939
+ `--zx-focus-ring` with a transparent outline for forced-colors mode.
1940
+ - **Group headings** — `renderGroupHeading({id, label, count, records, collapsed, toggle})` returns
1941
+ the heading content in place of the label. `collapsibleGroups: true` makes each heading an APG
1942
+ disclosure: a button with `aria-expanded` and `aria-controls` pointing at the group's list, which
1943
+ holds the label (and so the custom content, which must then not contain interactive elements).
1944
+ A collapsed group keeps its heading and renders no cards; `collapsedGroups` sets the initial
1945
+ ones. In the roving model a collapsible heading is a row in the arrow-key order: Enter or Space
1946
+ toggles it, ArrowLeft collapses, ArrowRight expands, and collapsing the group of the focused card
1947
+ moves focus to its heading.
1731
1948
  - **Interaction** — By default Enter activates a focused card; Space toggles selection. With
1732
1949
  `selectionTrigger:'card'`, Enter also toggles selection. Links, actions,
1733
1950
  selection controls, and selected text do not also activate the card. `recordaction` adds the
package/docs/llms.txt CHANGED
@@ -18,6 +18,24 @@ exports and as `window.zx.*`.
18
18
  - [API reference](llms.md): per-component constructor options, methods, and events for all public components plus the core helpers.
19
19
  - [Changelog](../CHANGELOG.md): what changed in each release, including behaviour changes an upgrade has to account for.
20
20
 
21
+ ## Start here: choosing
22
+ - Start every screen from the closest **layout**, never from a blank page. Gallery:
23
+ https://zx.zeyos.com/layouts (`layouts.html#<id>` opens one); source
24
+ `https://zx.zeyos.com/layouts/<id>.layout.js` + `<id>.layout.css`; the shell helpers
25
+ `layouts/kit.js` + `kit.css`, and `layouts/overview.js` + `overview.css` (`createOverview()`,
26
+ the toolbar-chips-drawers-pager composition every record screen uses). They are site modules,
27
+ not package exports: copy them beside the application.
28
+ - Templates (complete applications on one shell): `mail`, `issue-tracker`, `wiki`, `ai-chat`,
29
+ `agent-workspace`, `invoice-editor`, `item-inventory`, `workflows`, `infrastructure`, `crm`.
30
+ Patterns (single screens): `master-detail`, `record-collection` (any list of records),
31
+ `dashboard`, `inbox`, `record-page`, `agent-chat`, `record-wizard`, `checkout-wizard`,
32
+ `settings-workspace`, `system-states` (every empty, loading, error, and confirmation state),
33
+ `zeyos-invoices`.
34
+ - The agent reference's **"Choosing what to build with"** section maps each screen to its layout
35
+ and each job to its component, lists the theming decisions (theme, accent preset, geometry
36
+ tokens, material, motion, colour roles), and what never to build by hand. Read it before
37
+ building anything.
38
+
21
39
  ## Components
22
40
  - Inputs: `button()`, `buttonGroup()`, `badge()`/`badgeGroup()`, `CheckButton`,
23
41
  `Toggle`, `Search`,
@@ -60,7 +78,7 @@ exports and as `window.zx.*`.
60
78
  - 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).
61
79
 
62
80
  ## Theming
63
- Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) on any ancestor. There is one geometry: spacing steps are multiples of `--zx-space-unit` (4px), radius steps are fractions of `--zx-radius` (4px: 2/3/4/6px), and controls are `--zx-control-height` (30px) tall — override those to tighten or loosen an application. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. The theme studio controls accent, neutral tint, spacing, font, type size, radius, control height, and CSS-first glass material. Compact menus, pickers, tooltips, column menus, and toasts share responsive compact glass; Launcher, Modal, Dialog, and floating Sheets share a calmer reading panel. Both preserve scoped theme inheritance and refract Aurora/page content; docked Sheets and dense data surfaces remain opaque. Never use tier-1 palette tokens or raw color literals in application CSS.
81
+ Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) on any ancestor. There is one geometry: spacing steps are multiples of `--zx-space-unit` (4px), radius steps are fractions of `--zx-radius` (4px: 2/3/4/6px), and controls are `--zx-control-height` (30px) tall — override those to tighten or loosen an application. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. The theme studio controls accent, neutral tint, spacing, font, type size, radius, control height, and the CSS-first material: Glass (the default, a thin lit pane), Deep glass, Frost (milk glass), Smoke (tinted), Paper, Satin and Enamel (opaque, no blur), or Flat — each a token-override recipe composed from the theme's glass ingredients (`--zx-color-glass-rim/-ring/-lift/-shade/-edge/-tint`). Compact menus, pickers, tooltips, column menus, and toasts share responsive compact glass; Launcher, Modal, Dialog, and floating Sheets share a calmer reading panel. Both preserve scoped theme inheritance and refract Aurora/page content; docked Sheets and dense data surfaces remain opaque. Never use tier-1 palette tokens or raw color literals in application CSS.
64
82
 
65
83
  ## Talking to ZeyOS
66
84
  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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zeyos/zx",
3
- "version": "5.2.0",
3
+ "version": "5.4.0",
4
4
  "description": "Dependency-free JavaScript implementation of the Xenon Design System.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -59,6 +59,77 @@
59
59
  line-height: 1.3;
60
60
  }
61
61
 
62
+ /* The heading row: a plain wrapper in the tab model, a grid row in the roving one. */
63
+ .zx-card-view__group-header {
64
+ border-radius: var(--zx-radius-sm);
65
+ }
66
+
67
+ .zx-card-view__group-header:focus-visible {
68
+ outline: 2px solid transparent;
69
+ box-shadow: inset var(--zx-focus-ring);
70
+ }
71
+
72
+ /* A collapsible heading is an APG disclosure: the button carries the label, the chevron turns. */
73
+ .zx-card-view__group-toggle {
74
+ display: inline-flex;
75
+ align-items: center;
76
+ gap: var(--zx-space-1);
77
+ min-block-size: 0;
78
+ margin-inline-start: calc(-1 * var(--zx-space-1));
79
+ padding: var(--zx-space-1);
80
+ border: 0;
81
+ border-radius: var(--zx-radius-sm);
82
+ background: none;
83
+ color: inherit;
84
+ font: inherit;
85
+ cursor: pointer;
86
+ }
87
+
88
+ .zx-card-view__group-toggle:hover {
89
+ background: var(--zx-color-bg-hover);
90
+ }
91
+
92
+ .zx-card-view__group-toggle:focus-visible {
93
+ outline: 2px solid transparent;
94
+ box-shadow: var(--zx-focus-ring);
95
+ }
96
+
97
+ .zx-card-view__group-toggle > .zx-icon {
98
+ flex: none;
99
+ color: var(--zx-color-text-subtle);
100
+ }
101
+
102
+ .zx-card-view__group-toggle[aria-expanded="false"] > .zx-icon {
103
+ transform: rotate(-90deg);
104
+ }
105
+
106
+ .zx-card-view__group[data-collapsed="true"] .zx-card-view__group-heading {
107
+ margin-block-end: 0;
108
+ }
109
+
110
+ .zx-card-view__list[hidden] {
111
+ display: none;
112
+ }
113
+
114
+ /* Roving focus sits inside the card, so a host that restyles cards into flush rows still shows
115
+ it; the transparent outline is what forced-colors mode paints. */
116
+ .zx-card-view[data-keyboard="roving"] .zx-record-card:focus-visible {
117
+ outline: 2px solid transparent;
118
+ outline-offset: -2px;
119
+ box-shadow: inset var(--zx-focus-ring);
120
+ }
121
+
122
+ .zx-card-view__content[data-empty-focus]:focus-visible {
123
+ outline: 2px solid transparent;
124
+ box-shadow: inset var(--zx-focus-ring);
125
+ }
126
+
127
+ @media (prefers-reduced-motion: no-preference) {
128
+ .zx-card-view__group-toggle > .zx-icon {
129
+ transition: transform var(--zx-dur-fast) var(--zx-ease);
130
+ }
131
+ }
132
+
62
133
  .zx-card-view__list {
63
134
  display: grid;
64
135
  grid-template-columns: repeat(auto-fill,