@zeyos/zx 5.3.0 → 5.5.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.
Files changed (114) hide show
  1. package/CHANGELOG.md +125 -0
  2. package/README.md +49 -16
  3. package/dist/types/components/app-sidebar/app-sidebar.d.ts +33 -0
  4. package/dist/types/components/badge/badge.d.ts +5 -4
  5. package/dist/types/components/datebox/date-range-box.d.ts +15 -2
  6. package/dist/types/components/datebox/datebox.d.ts +37 -3
  7. package/dist/types/components/kbd/kbd.d.ts +41 -0
  8. package/dist/types/components/launcher/launcher.d.ts +4 -2
  9. package/dist/types/components/prose/prose.d.ts +69 -0
  10. package/dist/types/components/questionnaire/questionnaire.d.ts +0 -36
  11. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -0
  12. package/dist/types/components/tag-picker/tag-picker.d.ts +11 -5
  13. package/dist/types/components/tree/tree.d.ts +44 -3
  14. package/dist/types/core/icons.d.ts +22 -1
  15. package/dist/types/index.d.ts +4 -2
  16. package/dist/types/internal/app-rail.d.ts +10 -3
  17. package/dist/types/internal/row-actions.d.ts +151 -0
  18. package/dist/zx-zeyos.esm.js +264 -82
  19. package/dist/zx-zeyos.esm.min.js +4 -4
  20. package/dist/zx.css +1288 -439
  21. package/dist/zx.esm.js +952 -392
  22. package/dist/zx.esm.min.js +6 -6
  23. package/dist/zx.global.js +952 -392
  24. package/dist/zx.global.min.js +6 -6
  25. package/dist/zx.min.css +1 -1
  26. package/docs/api.json +112 -4
  27. package/docs/llms.md +433 -38
  28. package/docs/llms.txt +21 -1
  29. package/package.json +1 -1
  30. package/src/components/account-menu/account-menu.js +2 -2
  31. package/src/components/app-rail/app-rail.css +11 -11
  32. package/src/components/app-sidebar/app-sidebar.css +90 -17
  33. package/src/components/app-sidebar/app-sidebar.js +120 -12
  34. package/src/components/badge/badge.css +33 -20
  35. package/src/components/badge/badge.js +5 -4
  36. package/src/components/breadcrumb/breadcrumb.css +28 -3
  37. package/src/components/breadcrumb/breadcrumb.js +2 -2
  38. package/src/components/button/button.css +24 -13
  39. package/src/components/button/button.js +20 -2
  40. package/src/components/calendar/calendar.css +14 -4
  41. package/src/components/card-view/card-view.js +2 -2
  42. package/src/components/chart/chart.js +20 -5
  43. package/src/components/check-button/check-button.css +11 -3
  44. package/src/components/check-button/check-button.js +3 -3
  45. package/src/components/context-menu/context-menu.css +7 -1
  46. package/src/components/date-picker/date-picker.css +6 -0
  47. package/src/components/date-picker/date-picker.js +5 -5
  48. package/src/components/date-picker/date-range-picker.css +6 -0
  49. package/src/components/date-picker/date-range-picker.js +3 -3
  50. package/src/components/date-picker/month-picker.js +3 -3
  51. package/src/components/date-picker/time-picker.css +6 -0
  52. package/src/components/datebox/date-range-box.js +30 -6
  53. package/src/components/datebox/datebox.js +44 -7
  54. package/src/components/dialog/dialog.css +0 -1
  55. package/src/components/dialog/dialog.js +2 -1
  56. package/src/components/dock/dock.js +2 -2
  57. package/src/components/dropdown/dropdown.css +2 -1
  58. package/src/components/entity-ref/entity-ref.css +8 -1
  59. package/src/components/file-item/file-item.css +1 -1
  60. package/src/components/finder/finder.js +2 -2
  61. package/src/components/groupbox/groupbox.js +2 -2
  62. package/src/components/kanban-view/kanban-view.css +8 -4
  63. package/src/components/kanban-view/kanban-view.js +3 -3
  64. package/src/components/kbd/kbd.css +64 -0
  65. package/src/components/kbd/kbd.js +121 -0
  66. package/src/components/launcher/launcher.css +30 -25
  67. package/src/components/launcher/launcher.js +15 -21
  68. package/src/components/list-toolbar/list-toolbar.css +7 -1
  69. package/src/components/menu-button/menu-button.css +9 -2
  70. package/src/components/message/message.css +6 -2
  71. package/src/components/message/message.js +2 -2
  72. package/src/components/module-bar/module-bar.css +11 -1
  73. package/src/components/multi-value-editor/multi-value-editor.js +4 -4
  74. package/src/components/navigation-bar/navigation-bar.css +3 -2
  75. package/src/components/pagination/pagination.js +2 -2
  76. package/src/components/panel/panel.js +2 -2
  77. package/src/components/prose/prose.css +53 -0
  78. package/src/components/prose/prose.js +152 -0
  79. package/src/components/questionnaire/questionnaire.css +7 -17
  80. package/src/components/questionnaire/questionnaire.js +16 -1
  81. package/src/components/rating/rating.css +3 -1
  82. package/src/components/search/search.js +2 -2
  83. package/src/components/select/glyphs.js +3 -3
  84. package/src/components/select/select.css +35 -7
  85. package/src/components/select/select.js +4 -4
  86. package/src/components/stat-tile/stat-tile.css +56 -2
  87. package/src/components/stat-tile/stat-tile.js +25 -2
  88. package/src/components/stepper/stepper.css +2 -1
  89. package/src/components/stepper/stepper.js +3 -3
  90. package/src/components/tabbox/tabbox.css +2 -2
  91. package/src/components/tabbox/tabbox.js +2 -2
  92. package/src/components/table/table.css +52 -16
  93. package/src/components/table/table.js +7 -5
  94. package/src/components/tag-picker/tag-picker.css +56 -43
  95. package/src/components/tag-picker/tag-picker.js +21 -16
  96. package/src/components/tree/tree.css +44 -0
  97. package/src/components/tree/tree.js +97 -9
  98. package/src/components/value-list/value-list.css +25 -4
  99. package/src/components/value-list/value-list.js +2 -1
  100. package/src/components/view/record-view.js +3 -3
  101. package/src/components/view-settings/view-settings.css +2 -1
  102. package/src/components/workspace-switcher/workspace-switcher.js +3 -3
  103. package/src/core/icons.js +34 -3
  104. package/src/elements/define.js +1 -0
  105. package/src/index.js +4 -2
  106. package/src/internal/app-rail.js +5 -1
  107. package/src/internal/row-actions.js +203 -0
  108. package/styles/base.css +26 -1
  109. package/styles/prose.css +306 -0
  110. package/styles/tokens/dark.css +108 -103
  111. package/styles/tokens/global.css +24 -9
  112. package/styles/tokens/semantic.css +520 -198
  113. package/styles/tokens/themes.css +9 -0
  114. package/styles/zx.css +3 -0
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,186 @@ 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; plain and one leading for a record's figures) | 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|folio"`) 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. Data rows follow the control
192
+ height through `--zx-row-height`; set it only to make rows tighter or more relaxed than that.
193
+ 4. **Material** — how surfaces answer light, exported from the studio as token overrides (there
194
+ is no attribute). `Glass` (the default: a thin lit pane), `Deep glass` (a thick one), `Frost`
195
+ (milk glass for reading surfaces), `Smoke` (tinted glass that darkens the scene; dark-first
196
+ products), `Paper`, `Satin` and `Enamel` (opaque: matte, brushed or glazed; no blur, so they
197
+ render cheaply and never depend on what is behind them), or `Flat`. `Aurora` supplies the light glass responds to. Reduced-transparency,
198
+ high-contrast, forced-colour and unsupported-filter environments fall back to solid surfaces on
199
+ their own.
200
+ 5. **Motion** — `data-zx-motion="reduced"` is the only switch; own transitions use `--zx-dur-*`,
201
+ `--zx-ease`, `--zx-ease-spring`, `--zx-ease-drawer`.
202
+ 6. **Colour roles** — `--zx-color-tone-*` for categories (tags, modules, avatars),
203
+ `--zx-color-danger|warning|success|info` for status, `--zx-color-bg-current` for "you are here"
204
+ and `--zx-color-bg-selected` for "what you picked", `--zx-color-bg-chrome` for navigation and
205
+ inspector columns. A module's colour is its `tone` on `ModuleBar`. A product's own colour is a
206
+ role overridden once on `:root`, `light-dark(<light>, <dark>)` where the appearances differ —
207
+ never per theme attribute (see **Override once**).
208
+ 7. **Type** — two registers. Interface type is `--zx-font-sans`, `--zx-font-mono` and
209
+ `--zx-text-base` (every `--zx-text-*` step derives from it). Reading type is a second, separate
210
+ decision for authored content in `.zx-prose`: `--zx-font-prose` (a serif here leaves the
211
+ interface alone), `--zx-prose-size`, `--zx-prose-measure`.
212
+ 8. **Content** — wrap authored text (a document, notes, a message body, an assistant's answer) in
213
+ `.zx-prose`; set emphasis apart with `.zx-callout` (neutral unless it is a status or a
214
+ category). Never style headings and paragraphs per screen.
215
+ 9. **Fields** — `data-zx-fields="quiet"` on property panels (no border or fill until hovered or
216
+ focused).
217
+ 10. **Print** — works without work; keep status badges, hide chrome. Nothing to add.
218
+ 11. **Markup-first pages** — `defineElements()` for `<zx-*>` custom elements where templates are
219
+ authored as HTML.
220
+
221
+ ### Never
222
+
223
+ - No raw colours (`#hex`, `rgb()`, named), no tier-1 tokens (`--zx-gray-*`, `--zx-emerald-*`,
224
+ `--zx-tone-*`), no hard-coded sizes the geometry tokens cover.
225
+ - No application CSS on component internals (`.zx-<component>__<part>` selectors); override a
226
+ token, or use a published hook.
227
+ - No hand-built dropdowns, menus, dialogs, tooltips, tables, date pickers, or toasts.
228
+ - No `innerHTML` with data; `h()` and text nodes.
229
+ - No state classes; state is ARIA and `data-state`, which the stylesheets already match.
230
+ - No second shell, second navigation, or second keyboard convention inside one application.
231
+
50
232
  ## Theming
51
233
 
52
234
  Load `zx.css`, then set the theme on any ancestor (usually `<html>`):
@@ -60,18 +242,53 @@ Themes: `light` | `dark` | `auto` (follows OS).
60
242
  **One geometry.** Spacing steps are multiples of one unit
61
243
  (`--zx-space-unit`, 4px: `--zx-space-1…8` = 4/8/12/16/20/24/32/40px), radius steps are fractions of
62
244
  one base (`--zx-radius`, 4px: `-sm/-md/-lg/-xl` = 2/3/4/6px; `-full` only for shapes whose roundness
63
- is the meaning — badges, avatars, toggles), and controls are `--zx-control-height` (30px) tall.
245
+ is the meaning — status pills, avatars, toggles; a tag takes `-md`; `-panel` is the corner of a panel that holds rounded
246
+ items, a menu or a listbox, concentric with them: the item corner plus the inset between them, 6px
247
+ at the default and square when the base is 0), and controls are `--zx-control-height` (30px) tall.
248
+ A data row — a table row, a single-line list row — is `--zx-row-height`, derived from the control
249
+ height (36px at the default), so every list on a screen shares one rhythm and a tighter product is
250
+ still one decision. Type is one base: `--zx-text-base` (14px) with every `--zx-text-*` step derived
251
+ from it (12 / 13 / 14 / 16 / 18 / 24 / 30px at the default), so changing the base keeps the
252
+ hierarchy; setting `--zx-text-md` alone still moves only the control size.
64
253
  To tighten or loosen an application, override those tokens on `:root` or on any region. The
65
254
  geometry and material tokens (control size, radius, spacing, blur and glass filters, durations,
66
- easings, the type scale) are declared on `:root` only, never on a `[data-zx-theme]` block, so an
67
- override on `:root` reaches nested light and dark regions alike; theme blocks carry colours only:
255
+ easings, the type scale) are declared on `:root` only, never on a `[data-zx-theme]` element, so an
256
+ override on `:root` reaches nested light and dark regions alike — and colours work the same way
257
+ (see **Override once**):
68
258
 
69
259
  ```css
70
260
  :root { --zx-space-unit: 3.5px; --zx-control-height: 28px; }
71
261
  ```
72
262
 
263
+ **Override once.** Every colour role is declared once, on `:root`; a theme element sets only
264
+ `color-scheme`, which picks the half of each `light-dark()` pair it reads. So a colour override
265
+ belongs on `:root` as well, written as `light-dark(<light>, <dark>)` where the two appearances
266
+ differ, and it reaches light, dark, auto and every nested region alike — together with everything
267
+ derived from it (hover, current, the glass and overlay tiers, and the tone tints follow
268
+ `--zx-color-text` and `--zx-color-bg-surface`) and every material the theme studio exports:
269
+
270
+ ```css
271
+ :root {
272
+ --zx-color-bg-page: light-dark(#f7f8fa, #14161b);
273
+ --zx-color-text-muted: light-dark(#5b6170, #a3a9b6);
274
+ }
275
+ ```
276
+
277
+ A value without `light-dark()` applies to both appearances. The accent is a ramp, not a role: set
278
+ `--zx-accent-300…700` (or use a preset) and each appearance takes its own stop. A nested
279
+ `data-zx-preset` region restates the roles that read that ramp (`--zx-color-accent*`,
280
+ `--zx-color-bg-selected`, `--zx-color-ring`, `--zx-focus-ring`, `--zx-color-overlay-selected`, the
281
+ overlay images), so an override of one of those meant to reach such a region too is written
282
+ `:root, [data-zx-preset] { … }`. Never register a colour role with `@property`: a registered colour
283
+ resolves where it is declared and stops following the region. Script that needs a role's value
284
+ reads a probe element's computed `color`, not the property's text, which may be a `light-dark()`
285
+ pair that a canvas cannot parse. `light-dark()` needs a 2024 browser; older ones read Xenon's own
286
+ per-theme fallback, where a `:root` override stops at a nested theme region, so an application that
287
+ supports them puts its own `light-dark()` overrides inside `@supports (color: light-dark(#000,
288
+ #fff))`.
289
+
73
290
  **Accent presets.** A second, orthogonal attribute picks the accent ramp:
74
- `data-zx-preset="zx" | "zeyos" | "ocean" | "violet" | "rose" | "slate"` (`zx` is the default and
291
+ `data-zx-preset="zx" | "zeyos" | "ocean" | "violet" | "rose" | "slate" | "folio"` (`zx` is the default and
75
292
  need not be set). A preset repoints five tier-1 tokens — `--zx-accent-300` … `--zx-accent-700` —
76
293
  and the semantic tier takes its own stop per polarity (600/700 on light surfaces, 300/400/500 on
77
294
  dark), so one five-line block rethemes light, dark, and auto together. Status colours are not part
@@ -90,24 +307,45 @@ Keep the 600 stop at 4.5:1 or better against white and the 400 stop at 4.5:1 aga
90
307
 
91
308
  The theme studio treats those stable IDs as complete recipes: selecting a preset also changes its
92
309
  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
310
+ Its **Material** control is CSS-first: eight materials, each a set of token overrides (there is no
311
+ attribute), composed from six per-theme *ingredients* the stylesheet declares —
312
+ `--zx-color-glass-rim` and `-ring` (the lit top edge and the hairline inner ring), `-lift` (white
313
+ laid on a pane from its top edge, which makes it read as lit rather than tinted), `-shade` (the
314
+ pane's own body: a veil over the scene, white in light and black in dark, that bounds what the
315
+ scene can do to text contrast), `-edge` (the cut outer line a pane needs against a dark scene) and
316
+ `-tint` (smoked glass) — plus `--zx-glass-grain`, a faint grey tooth. One recipe therefore
317
+ serves light and dark alike. **Glass**, the stylesheet default, is a thin lit pane: its light sits
318
+ on the edge, never as a wash on its face, and the filter saturates so colour behind survives the
319
+ blur. **Deep glass** is a thick pane — a double rim with an inner glow, one narrow specular band,
320
+ more refraction, a fine grain. **Frost** is milk glass: heavy diffusion, almost no reflection, text
321
+ as on paper. **Smoke** is tinted glass that darkens what is behind it (sunglass glass in dark).
322
+ **Paper** is opaque and matte, depth from a contact shadow and a modest cast; **Satin** is opaque
323
+ and brushed, a soft sheen across raised surfaces and a bright rim on controls; **Enamel** is an
324
+ opaque body under a glossy coat, a narrow highlight along the top edge and a darker foot, for
325
+ terminals and consoles where text backing must be certain. None of the three filters anything,
326
+ so they render cheaply and survive every fallback unchanged. **Flat** is the opaque semantic
327
+ surfaces. Aurora is
328
+ the independent ambient canvas layer; material is how surfaces respond to that light. The shared
329
+ recipe applies to AppIcons, ordinary controls, persistent chrome, raised cards, and every transient
330
+ overlay: Dropdown, ContextMenu, MenuButton, AccountMenu, AppRail flyouts, Select, TagPicker, date
331
+ pickers, tooltips, column menus, and toasts use `--zx-color-overlay-surface`; Launcher, Modal,
332
+ Dialog, and overlay Sheets use the calmer `--zx-color-overlay-panel`. The modal backdrop is a
100
333
  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,
334
+ layout rather than an overlay and becomes opaque, as do dense data surfaces. Reduced-transparency,
103
335
  increased-contrast, forced-colour, and unsupported-filter environments restore solid surfaces.
104
336
  Top-layer components remain DOM children of their nearest Zx theme scope, so a theme or material
105
337
  set on an application region continues to inherit through its menus, dialogs, tooltips, and toasts.
106
338
 
107
- Define a product theme by overriding **semantic** tokens under a `[data-zx-theme="name"]` selector:
339
+ Define a product theme as an accent ramp (a preset) plus **semantic** token overrides, each declared
340
+ once on `:root` as above — not under a `[data-zx-theme="name"]` selector, which would stop at the
341
+ first nested region:
108
342
  `--zx-color-bg-page/surface/raised/control/muted/hover/selected`, `--zx-color-bg-current` (the
109
343
  neutral "you are here" fill of the current nav item, row, tab, or pressed toggle — never the
110
344
  accent), `--zx-color-bg-chrome` (navigation and inspector columns, one tone off the canvas),
345
+ `--zx-color-text-chrome` (navigation labels at rest, one ink step under the content and above 7:1;
346
+ hover, focus and the current item take the full text colour), `--zx-color-border-chrome` (the line
347
+ where a chrome column meets the canvas: none in light, where the tone step separates them; a
348
+ hairline in dark, under `prefers-contrast: more`, and in forced colours),
111
349
  `--zx-color-glass-chrome/surface`,
112
350
  `--zx-color-overlay-surface/panel/backdrop/border/hover/selected/divider/scrim`,
113
351
  `--zx-overlay-surface-image/toast-image/panel-image`,
@@ -120,12 +358,29 @@ accent), `--zx-color-bg-chrome` (navigation and inspector columns, one tone off
120
358
  tiles, avatars — neither the accent nor a status) and `-solid` (a solid identity fill, such as a
121
359
  module tile, that the white icon glyph reads on at 3:1 in both themes), the chart series
122
360
  `--zx-color-chart-1…8`,
123
- `--zx-focus-ring`, `--zx-control-height/-radius`, `--zx-space-*`, `--zx-radius-*`, `--zx-text-*`
361
+ `--zx-color-ring` with `--zx-focus-ring` (keyboard focus; see **Focus** below),
362
+ `--zx-control-height/-radius`, `--zx-space-*`, `--zx-radius-*`, `--zx-text-*`
124
363
  (`-3xl` for document titles), `--zx-weight-medium/-semibold`, `--zx-tracking-tight/-title`. Never
125
364
  use tier-1 palette tokens (`--zx-gray-*`, `--zx-green-*`, `--zx-emerald-*`, `--zx-tone-*`) or raw
126
365
  color literals in application/component CSS. Prefer the least-specific override that works (global
127
366
  token → then, if needed, a component style).
128
367
 
368
+ **Focus.** Keyboard focus is one quiet line: `--zx-focus-ring` is a single 2px spread shadow in
369
+ `--zx-color-ring` (the accent, at the stop each theme reads as text), opaque, so it clears the 3:1
370
+ a focus indicator needs against everything it sits on — the page, the chrome, a card, a raised
371
+ panel, a current row and a selected row — in both themes, under every preset and tint, and for any
372
+ custom ramp that keeps the promise above. Being one shadow, it works both ways round:
373
+ `box-shadow: var(--zx-focus-ring)` draws it around a control, `box-shadow: inset
374
+ var(--zx-focus-ring)` inside a row, a tab, or a cell. Combine it by listing it after the
375
+ element's own shadows (`var(--zx-focus-ring), var(--zx-drag-shadow)`), with any `inset` layer
376
+ first, since `inset` belongs to one shadow of a list rather than to the list. Where the focused
377
+ element is itself an accent fill — a primary button, a chosen day — the ring would only make it
378
+ look larger, so lead with a 1px line in the fill's ink: `box-shadow: inset 0 0 0 1px
379
+ var(--zx-color-on-accent-solid), var(--zx-focus-ring)` (`--zx-color-on-accent` on a
380
+ `--zx-color-accent` fill). Leave the outline transparent rather than removing it: forced colours
381
+ drop every shadow and paint that outline in the system highlight instead. A product that restyles
382
+ the ring keeps it one shadow, at least 2px, and at 3:1; to recolour it, set `--zx-color-ring`.
383
+
129
384
  **Print.** `zx.css` imports `styles/print.css` last. It releases sticky headers and scroll
130
385
  containers, drops fills, shadows, zebra striping and focus rings, hides overlays and navigation
131
386
  chrome, repeats table headers across pages, keeps cards and rows from breaking, and prints link
@@ -370,6 +625,65 @@ reflection and ElementInternals form association: `<zx-toggle>`, `<zx-check-butt
370
625
  Each component is `new Component(target, options)`. Events are the component-level names (also
371
626
  dispatched as bubbling `zx-<name>` on the root). Detail is always an object.
372
627
 
628
+ <!-- doc:prose -->
629
+ ### Prose — `.zx-prose` and `.zx-callout`
630
+
631
+ The reading register: a class, not a component, that sets authored content — a document, a
632
+ record's notes, a message body, an assistant's answer — in the reading tokens rather than the
633
+ interface ones. Write plain HTML inside it: `h1`–`h4`, `p`, `ul`/`ol`, `blockquote`, `hr`, links,
634
+ inline `code`, `pre`, `kbd`, `mark`, tables, `figure`/`figcaption`, `img`.
635
+
636
+ - **Tokens** — `--zx-font-prose` (the interface stack by default; a serif here leaves the interface
637
+ alone), `--zx-prose-size` (16px, `--zx-text-lg`), `--zx-prose-leading` (1.7), `--zx-prose-measure`
638
+ (62ch, the reading width). Headings scale with the reading size and read `--zx-weight-title`.
639
+ - **Attributes** — `data-size="sm"` sets prose at the interface size, for comments, previews, and
640
+ panels; `data-zx-measure="full"` drops the measure where the column already sets the width.
641
+ - **Rhythm** — one gap between blocks, more above a heading and less below it; links in the body
642
+ colour over a quiet underline, accent on hover; tables without a frame, a muted header over
643
+ hairline rows, `data-align="end"` cells in tabular figures.
644
+ - **Content colour** — a bare `mark` highlights in the amber tone; `mark[data-tone]` in any of the
645
+ nine tones; a bare `span[data-tone]` colours its text, and `data-fill` highlights it as well.
646
+ - **Callout** — `.zx-callout` with an optional `.zx-callout__icon` and a `.zx-callout__body`
647
+ (`.zx-callout__title` for a bold first line): a tinted fill, no frame, at the interface size.
648
+ Neutral by default, because most callouts are emphasis; `data-kind="info|success|warning|danger"`
649
+ makes it a status and `data-tone` a category. Works inside or outside prose.
650
+ - **Specificity** — every rule is `.zx-prose` plus `:where()`, and the stylesheet loads before the
651
+ components, so a badge, an entity reference, or a table placed in prose keeps its own styles,
652
+ while an application's bare element reset cannot undo the rhythm.
653
+ - **Section links** — `proseAnchors(root, options)` ends every `h2`–`h4` with an `id` inside a
654
+ `.zx-prose` under `root` with a small link to itself (`a.zx-prose__anchor`, "Copy link to …").
655
+ It shows while the heading is pointed at or the link has focus (and always on a touch screen or
656
+ under a contrast preference). A click copies the address with the section's hash — the current
657
+ address by default, `href(id)` to build another — and confirms with a tick and a polite "Link
658
+ copied"; it never changes the location, and a middle or modified click is left to the browser.
659
+ Options: `selector`, `label` (`%1` is the heading), `title`, `feedback`, `feedbackDuration`,
660
+ `href`, `oncopy(url, copied)`. It returns `{refresh(), destroy()}`: call `refresh()` after
661
+ re-rendering the content. Headings without an id are skipped — give the ones worth linking a
662
+ stable id. `sectionHref(base, id)` builds the address.
663
+ <!-- /doc -->
664
+
665
+ <!-- doc:kbd -->
666
+ ### Kbd — `kbd(keys, options)`
667
+
668
+ A factory (not a class) returning keycaps: one `<kbd class="zx-kbd">` holding a nested
669
+ `<kbd class="zx-kbd__key">` per key, which is how HTML marks up a combination. Button shortcuts,
670
+ the launcher's hints, and shortcut references all use it, so a key looks the same everywhere.
671
+
672
+ - **Signature** — `kbd(keys, { size, tone })` → `HTMLElement`. `keys` is a chord written like
673
+ `aria-keyshortcuts` (`'Mod+Shift+K'`; a literal plus as `'Mod++'`) or an array of keys for a
674
+ sequence (`['g', 'i']`). `size: 'md'|'sm'` (`sm` inside buttons and menu rows); `tone:
675
+ 'neutral'|'inherit'` (`inherit` draws the caps in the surrounding ink, for a solid button or a
676
+ dark toast). `keyLabels(keys, { apple })` returns the labels without building DOM.
677
+ - **Labels** — `Mod` is ⌘ on Apple platforms and Ctrl elsewhere; `Alt`, `Shift`, `Ctrl`,
678
+ `Backspace`, `Delete`, `Tab` become ⌥ ⇧ ⌃ ⌫ ⌦ ⇥ on Apple platforms and words elsewhere; `Enter`,
679
+ `Escape` and the arrows become ↵, Esc, ↑ ↓ ← →; single letters are upper-cased.
680
+ - **Look** — a surface fill, one hairline and a 1px foot, the label at the small size and medium
681
+ weight, centred on its capital height; a single key is square. Retint it with `--zx-kbd-ink`,
682
+ `--zx-kbd-fill` and `--zx-kbd-line` on any ancestor.
683
+ - **Accessibility** — the caps are presentation. Announce a control's shortcut with
684
+ `aria-keyshortcuts` on the control and mark a hint that repeats it `aria-hidden`.
685
+ <!-- /doc -->
686
+
373
687
  <!-- doc:button -->
374
688
  ### Button — `button(options)` / `buttonGroup(buttons)`
375
689
 
@@ -393,9 +707,9 @@ accept.
393
707
  <!-- doc:badge -->
394
708
  ### Badge — `badge(options)` / `badgeGroup(badges)`
395
709
 
396
- Factories (not classes) returning a status pill: a small, non-interactive `<span>` carrying a
397
- semantic colour — or, with `tone`, a categorical one — used for stages, counts, tags, and
398
- record-header metadata. A badge with no label but a `title` is named for assistive technology
710
+ Factories (not classes) returning a chip: a small, non-interactive `<span>` carrying a semantic
711
+ colour — a status — or, with `tone`, a categorical one — a tag — used for stages, counts, labels,
712
+ and record-header metadata. A badge with no label but a `title` is named for assistive technology
399
713
  through `role="img"`; everything else is plain text and needs no ARIA.
400
714
 
401
715
  - **Options** — `label`, `icon` (an icon name, rendered before the label), `kind:
@@ -408,11 +722,18 @@ through `role="img"`; everything else is plain text and needs no ARIA.
408
722
  accent nor the status set, so a project tagged red never reads as an error. When `tone` is set it
409
723
  decides the colour and `kind` is ignored for it; every `variant` still applies (soft: tinted,
410
724
  borderless; solid: filled with the tone's ink; outline). The badge carries `data-tone`. Badges
411
- are medium weight and sentence case.
725
+ are sentence case.
726
+ - **Two shapes, one construction** — a status is a pill (`--zx-radius-full`); give a workflow state
727
+ `dot: true`, a 6px dot centred in the pill's round end. A tag (any badge with a `tone`) has small
728
+ corners (`--zx-radius-md`). Both are one fill and no line, 12px at weight 500 at either size,
729
+ and their height follows the row they sit in: about five ninths of `--zx-row-height` for `md`
730
+ and half of it for `sm` (20px and 18px in the default row), never below a line of their own text,
731
+ so a chip follows the row height setting without making a row taller. `TagPicker` builds its tags with
732
+ `badge()`, so a label reads the same in a list row, a record header and the field that edits it.
412
733
  - **Neutral and small** — the neutral soft fill is a wash of the text colour, not an opaque surface
413
734
  step, so it stays visible on raised surfaces in the dark theme. `size: 'sm'` fits table cells
414
- and board cards; a small badge with `dot` keeps the 12px text and a full spacing step between
415
- dot and label.
735
+ and board cards; it is shorter and tighter, never smaller type. Under `prefers-contrast: more` a
736
+ soft badge gets its edge back, and under forced colours every badge does.
416
737
  - **Methods** — none. `badge(options)` → `HTMLSpanElement`, `badgeGroup([badge(…), …])` → a wrapping
417
738
  inline row with its own spacing; you own both elements.
418
739
  - **Events** — none; a badge is not interactive.
@@ -1116,9 +1437,19 @@ Text date input with a calendar popover. `DateTimeBox(target, opts)` is a Datebo
1116
1437
  `time: true`, which also brings the TimePicker (and its clock face) into the popover. Format
1117
1438
  tokens are the date-utility ones: `%d %m %Y %H %M`.
1118
1439
 
1119
- - **Options** — `value: Date | number(unix) | string`, `format: '%d.%m.%Y'`, `time: false`, `min`,
1120
- `max`, `placeholder`, `clearable: true` (the clear button shows while there is a value and the
1121
- box is enabled; without `clearable` the input keeps no room for it), `disabled`.
1440
+ - **Options** — `value: Date | number(unix) | string`, `format: '%d.%m.%Y'`, `displayFormat: null`,
1441
+ `time: false`, `min`, `max`, `placeholder`, `clearable: true` (the clear button shows while
1442
+ there is a value and the box is enabled; without `clearable` the input keeps no room for it),
1443
+ `disabled`.
1444
+ - **Two formats** — `format` is what the reader types, and what the field shows while it has
1445
+ focus; it is parsed, so it takes numeric tokens only. `displayFormat` is what the field shows at
1446
+ rest, so a date field reads the way the rest of the screen writes dates (`'%e %b %Y'` → "2 Nov
1447
+ 2026" beside a header that says "Created 19 Jul 2026"). It is never parsed, so month and weekday
1448
+ names (`%b %B %a %A`) are fine; `null` shows `format`. Focus switches the text to the typing
1449
+ format, a valid commit on blur or Enter switches it back, and text that failed to parse stays as
1450
+ typed. With `time`, a format without `%H`/`%M` gets ` %H:%M` appended, the display format too.
1451
+ The placeholder still describes `format`, and string values passed to `set()` are parsed with it.
1452
+ `dateboxFormats({format, displayFormat, time})` → `{format, display}` resolves both the same way.
1122
1453
  - **In a Field** — field types `date`/`datetime` (and `daterange`) fill the control column like a
1123
1454
  text input and give way in a narrow two-column row; standalone, the box keeps its own width.
1124
1455
  - **Methods** — `get(unit='date')` (`'seconds'` → unix), `set(value, {silent})` (accepts a Date;
@@ -1144,7 +1475,7 @@ An inline two-month calendar for picking a start and an end day, plus the form-u
1144
1475
 
1145
1476
  #### DateRangeBox
1146
1477
 
1147
- - **Options** — everything DateRangePicker takes, plus `format: '%d.%m.%Y'`, `separator: ' – '`, `placeholder: null` (derived from the format when null), `clearable: true` (no clear button while disabled, and no room kept for one without it). Typed text is parsed as `"<start><separator><end>"`; a lone date reads as a one-day range and a trailing separator keeps the range half open.
1478
+ - **Options** — everything DateRangePicker takes, plus `format: '%d.%m.%Y'`, `displayFormat: null`, `separator: ' – '`, `placeholder: null` (derived from the format when null), `clearable: true` (no clear button while disabled, and no room kept for one without it). Typed text is parsed as `"<start><separator><end>"`; a lone date reads as a one-day range and a trailing separator keeps the range half open. `displayFormat` is the endpoints' format at rest, as on Datebox (`'%e %b %Y'` → "3 Aug 2026 – 9 Aug 2026"); focus switches to `format`, and text left untouched while the calendar holds focus goes back to the display format.
1148
1479
  - **Methods** — `get(unit = 'date')` (`'seconds'` returns `{start, end}` as Unix seconds), `set(range, {silent})` accepting `{start, end}` of Dates, Unix-seconds numbers, or formatted strings, `clear({silent})`, `open()`, `close()`, `enable()`, `disable()`, `focus()`, `destroy()`.
1149
1480
  - **Events** — `change {start, end}`, `invalid {text}` when the typed value cannot be parsed (the text stays editable and the field takes `data-state="invalid"` plus `aria-invalid`), `open`, `close`.
1150
1481
  <!-- /doc -->
@@ -2032,7 +2363,17 @@ mutate the caller's data.
2032
2363
  - **Options** — `items` (nested), `valueKey: 'ID'`, `labelKey: 'name'`, `childrenKey: 'children'`,
2033
2364
  `expanded: []`, `selection: 'single'|'multi'|false`, `selected: []`, `checkboxes: false`
2034
2365
  (tri-state), `checked: []`, `icons: true`, `renderLabel`, `load: (node)=>Promise<children>`
2035
- (lazy children; mark a branch with `hasChildren: true`), `filter`, `emptyText`, `height`.
2366
+ (lazy children; mark a branch with `hasChildren: true`), `filter`, `emptyText`, `height`,
2367
+ `rowActions: (node) => actions`, `moreLabel: 'More actions'`.
2368
+ - **Row actions** — `rowActions(node)` returns the row's commands: `{icon, label, onSelect(node),
2369
+ disabled?, danger?}` descriptors, or nodes of your own placed as given. One or two show as icon
2370
+ buttons at the row's end; with more, the first shows and the rest fold into a "More actions"
2371
+ menu (a node never folds). They rest out of sight and keep their room, and show while the row is
2372
+ pointed at, focused or selected, while its menu is open, and always on a touch screen, under a
2373
+ contrast preference and in forced colours — the `data-zx-reveal` utility. Every descriptor is
2374
+ also in the row's context menu (right-click, Shift+F10, the Menu key), and each control is named
2375
+ after its action and its row ("Add sub-page: Onboarding"); the row's own name stays its label.
2376
+ Use them only for repeated, secondary commands that are reachable another way too.
2036
2377
  - **Methods** — `setItems()`, `getItems()`, `getNode(id)`, `getPath(id)`, `setFilter(query)` (keeps
2037
2378
  matching nodes' ancestors and opens the surviving branches),
2038
2379
  `expand(id)`/`collapse(id)`/`toggle(id)` (async — they await the loader),
@@ -2045,6 +2386,9 @@ mutate the caller's data.
2045
2386
  activates, Space selects or toggles the checkbox, `*` expands every sibling, typing jumps to the
2046
2387
  next match. A typed character's default action is prevented, so find-as-you-type and page
2047
2388
  shortcuts do not act on it too; typing into a control inside a row is left to that control.
2389
+ With row actions, Tab from the focused row walks that row's actions and then leaves the tree
2390
+ (Shift+Tab comes back); keys pressed on an action belong to it, and clicking one neither selects
2391
+ nor focuses the row.
2048
2392
  - **Appearance** — the selected node of a single-selection tree is where you are: the neutral
2049
2393
  `--zx-color-bg-current` fill, the text colour, a semibold label. A `selection: 'multi'` tree is a
2050
2394
  set of picks and keeps the accent tint. Icons, folders included, are drawn in
@@ -2314,12 +2658,16 @@ yet. Field type: `tagpicker`.
2314
2658
  `filter: 'local'|(query)=>Promise<items>`, `minQuery: 0`, `debounce: 200`, `allowCreate: false`,
2315
2659
  `max` (maximum tags; further options become `aria-disabled`), `closeOnSelect: false`,
2316
2660
  `placeholder`, `listHeight: 260`, `disabled`, `readonly`, `renderItem`, `renderTag`.
2661
+ - **Tags are Badges** — every selected tag is built by `badge()` (`.zx-badge.zx-tag-picker__tag`):
2662
+ the Badge's height from the row, 12px medium type, padding and one fill, with the tag shape's
2663
+ small corners. `toneKey` names a categorical tone from the Badge palette (`blue`, `teal`,
2664
+ `green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`), so a toned tag is exactly the
2665
+ `badge({ tone })` a list row or record header shows for the same item; a tone wins over a colour.
2666
+ An untoned tag keeps the text ink, because in a field it is the value.
2317
2667
  - **Tag identity** — icon values accept a bundled icon name or Node; colors (a CSS colour or a token
2318
2668
  reference such as `var(--zx-color-tone-blue-fg)`) are scoped to the tag and its option through
2319
- `--zx-tag-color`. `toneKey` names a categorical tone from the Badge palette (`blue`, `teal`,
2320
- `green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`): the tag takes its fill and ink as a
2321
- toned Badge does (`data-tone`), and a tone wins over a colour. Custom `renderItem`/`renderTag`
2322
- remain authoritative.
2669
+ `--zx-tag-color`. An option shows its icon on a tile of its colour; inside a tag the icon is a bare
2670
+ glyph, since the tag is already the fill. Custom `renderItem`/`renderTag` remain authoritative.
2323
2671
  - **Read-only** — `readonly` (or `setReadonly(true)`) shows only the tags: no input, chevron, or
2324
2672
  remove buttons, so a full row of tags never wraps onto an empty line.
2325
2673
  - **Methods** — `getValues()`, `getItems()`, `setValues(values, {silent})`, `addValue()`,
@@ -2378,13 +2726,21 @@ returns the component, the way `tooltip()` does; call `.toElement()` for the nod
2378
2726
 
2379
2727
  - **Options** — `label`, `value`, `format: 'number'|'currency'|'percent'|'fileSize'|null|fn`,
2380
2728
  `currency`, `locale`, `caption`, `delta`, `deltaKind: 'positive'|'negative'|'neutral'`,
2381
- `deltaFormat`, `deltaLabel`, `trend: number[]`, `icon`, `kind`, `href`, `clickable`, `loading`,
2382
- `msg`.
2729
+ `deltaFormat`, `deltaLabel`, `trend: number[]`, `icon`, `kind`, `variant: 'default'|'plain'`,
2730
+ `emphasis`, `href`, `clickable`, `loading`, `msg`.
2383
2731
  - **Appearance** — the label is a sentence-case muted line (13px, medium); the value is the loud
2384
2732
  part (24px, weight 650, tabular figures); `caption` is one muted context line under it ("of
2385
2733
  13,184"). `icon` is a muted glyph beside the label, never a coloured chip; `kind` tints only the
2386
2734
  sparkline. The tile is a column with the sparkline at its foot, so tiles in a row are the same
2387
2735
  height and line up whether or not each has a caption, a delta or a trend.
2736
+ - **Framed or plain** — the default is a framed tile on its own surface: use it where a figure
2737
+ stands among other content, as on a dashboard. `variant: 'plain'` drops the frame, the fill and
2738
+ the padding, for a record's own figures under its title: its text sits on the content edge,
2739
+ space alone separates it from the next, and the figure steps down to 16px. Do not draw boxes
2740
+ around plain figures in the layout either. Reflected as `data-variant`.
2741
+ - **One figure leads** — `emphasis: true` sets one figure per row above the others: 24px in a
2742
+ plain row (the record title's size, never above it), 30px on a framed tile. Reflected as
2743
+ `data-emphasis`. The size is `--zx-stat-tile-value-size`, which the loading skeleton reads too.
2388
2744
  - **Methods** — `update(options)`, `getAccessibleName()`.
2389
2745
  - **Events** — `click {event}`.
2390
2746
 
@@ -2782,8 +3138,18 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
2782
3138
  `side: 'left'|'right'|'top'|'bottom'`, `layout: 'tree'|'modules'`, `module`, `moduleBar`
2783
3139
  (`{appearance, labels: 'auto'|'beside'|'below'|'hidden', allModules, label}` for the module
2784
3140
  strip), `label`,
2785
- `header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`, and
2786
- `renderIcon(item, context)`. Icon values may also be names, nodes, components, or factories.
3141
+ `header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`,
3142
+ `moreLabel: 'More actions'`, and `renderIcon(item, context)`. Icon values may also be names,
3143
+ nodes, components, or factories.
3144
+ - **Row actions** — `actions` on a destination lists its commands: `{icon, label, onSelect(item),
3145
+ disabled?, danger?}` descriptors or nodes, laid out as TreeView's `rowActions` (two at most, the
3146
+ rest in a "More actions" menu). They rest out of sight over the end of the row, which keeps room
3147
+ for them, and show while the row is pointed at, holds focus, is the current page or has its menu
3148
+ open — always on a touch screen, under a contrast preference and in forced colours. Each is named
3149
+ after its action and the destination ("Rename: Customers"). Only the actions of the destination
3150
+ holding focus are Tab stops, right after it; a right-click or Shift+F10 on the destination lists
3151
+ them all. The expanded tree and the modules layout's panel draw them; minimized flyouts show the
3152
+ destinations only.
2787
3153
  - **Sections** — an item with `section: true` is a quiet heading over its `children`, which stay
2788
3154
  at its own level: never indented, collapsed, focused, or selected, and it needs no `id`.
2789
3155
  `actions` (a node) adds trailing controls such as an add button. Sections replace stacking
@@ -2930,8 +3296,8 @@ bar.setBadge('mail', 8);
2930
3296
  newest-first handler registry. Existing `DOM.on/remEvt/fireEvt` methods can delegate to this
2931
3297
  triad. Zx never installs globals or alters DOM prototypes; applications decide whether to expose
2932
3298
  these functions globally or compose them into their own UI and routing layer.
2933
- - **Icons** — `icon(name, {size, label})` and `icons`; see the Icons section — bundled inline SVG
2934
- by default, Font Awesome after an opt-in.
3299
+ - **Icons** — `icon(name, {size, label})`, `icons`, and `ICON_SIZE` (one size per role); see the
3300
+ Icons section — bundled inline SVG by default, Font Awesome after an opt-in.
2935
3301
  - **Positioning** — `position(anchor, floating, {placement, offset, flip, matchWidth})` →
2936
3302
  `{update, destroy}`. It anchors a manual popover with CSS anchor positioning where the browser
2937
3303
  supports it and a scroll/resize-tracked fallback where it does not. Options are resolved once,
@@ -3004,6 +3370,26 @@ old `RangeError`, at a call site that can afford to fail: a test, or a build-tim
3004
3370
  Font Awesome elements are sized with `font-size` and occupy 1em; bundled SVGs use width/height
3005
3371
  attributes (default 16). Both honour `label` (`null` ⇒ `aria-hidden`, otherwise `role="img"` +
3006
3372
  `aria-label`).
3373
+
3374
+ **Size an icon by its role.** `ICON_SIZE` names one pixel size per role, so every chevron, every
3375
+ dismiss ×, and every check renders alike wherever it appears, and a call site says what a glyph is
3376
+ for rather than how big it is: `icon('chevron-down', { size: ICON_SIZE.chevron })`. The components
3377
+ use it throughout; use it in application code too, and never write a number for one of these roles.
3378
+
3379
+ - `ICON_SIZE.control` (16) — the default: an icon that is a control's content or leads its label.
3380
+ - `ICON_SIZE.chevron` (14) — dropdown, disclosure, and reorder chevrons; calendar and pager
3381
+ arrows; breadcrumb separators.
3382
+ - `ICON_SIZE.dismiss` (14) — the × that clears a field, closes a tab, dialog, or message, or
3383
+ removes a row.
3384
+ - `ICON_SIZE.check` (14) — the check of a selected option, a pressed toggle button, or a completed
3385
+ step.
3386
+ - `ICON_SIZE.sort` (14) — the sort-direction arrow beside a column heading.
3387
+ - `ICON_SIZE.chip` (12) — any glyph inside a chip or token, its remove × included.
3388
+ - `ICON_SIZE.marker` (8) — a glyph drawn inside a small status marker.
3389
+
3390
+ Several roles share a value and are named apart so one can change on its own. At 14px and below an
3391
+ outline is drawn with a one-pixel line, so the indicator roles also share a stroke weight. A text
3392
+ character is never a stand-in for an icon: draw "×", "✓", or an arrow with `icon()`.
3007
3393
  <!-- /doc -->
3008
3394
 
3009
3395
  <!-- doc:helpers -->
@@ -3109,7 +3495,8 @@ destroys its component.
3109
3495
 
3110
3496
  Registered elements: `<zx-toggle>`, `<zx-check-button>`, `<zx-select items='[…]' required>`,
3111
3497
  `<zx-checklist>`, `<zx-datebox>`, `<zx-timebox>`, `<zx-search>`, `<zx-groupbox>`, `<zx-tabbox>`,
3112
- `<zx-table>`, `<zx-dialog>`.
3498
+ `<zx-table>`, `<zx-dialog>`. `<zx-datebox>` takes `display-format` beside `format`, as the
3499
+ Datebox options `displayFormat` and `format`.
3113
3500
  <!-- /doc -->
3114
3501
 
3115
3502
  <!-- doc:tokens -->
@@ -3180,4 +3567,12 @@ record: native inputs, selects, and textareas inside it drop their border and fi
3180
3567
  (`--zx-color-bg-hover`) or focus (the normal border, the control fill, and the focus ring), so values
3181
3568
  read as text rather than as a wall of boxes. Read-only and disabled fields stay quiet. The rules have
3182
3569
  zero specificity, so a component's own input styling still wins.
3570
+
3571
+ **Revealed actions.** Mark a row or a section heading `data-zx-reveal-host` and a secondary action
3572
+ inside it `data-zx-reveal`: the action rests invisible and appears while the host is pointed at,
3573
+ holds focus, is current or selected, or has a menu open. It keeps its space, so nothing shifts, and
3574
+ stays in the tab order, so focusing it shows it. On touch screens, under `prefers-contrast: more`
3575
+ and in forced colours it is always visible. Use it only for repeated, secondary per-row actions
3576
+ that are reachable another way (a context menu, a keyboard shortcut); a primary action stays
3577
+ visible. Hosts do not nest.
3183
3578
  <!-- /doc -->