@zeyos/zx 5.4.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 (113) hide show
  1. package/CHANGELOG.md +80 -0
  2. package/README.md +23 -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 +1225 -433
  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 +243 -37
  28. package/docs/llms.txt +2 -0
  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.js +2 -2
  71. package/src/components/module-bar/module-bar.css +11 -1
  72. package/src/components/multi-value-editor/multi-value-editor.js +4 -4
  73. package/src/components/navigation-bar/navigation-bar.css +3 -2
  74. package/src/components/pagination/pagination.js +2 -2
  75. package/src/components/panel/panel.js +2 -2
  76. package/src/components/prose/prose.css +53 -0
  77. package/src/components/prose/prose.js +152 -0
  78. package/src/components/questionnaire/questionnaire.css +7 -17
  79. package/src/components/questionnaire/questionnaire.js +16 -1
  80. package/src/components/rating/rating.css +3 -1
  81. package/src/components/search/search.js +2 -2
  82. package/src/components/select/glyphs.js +3 -3
  83. package/src/components/select/select.css +35 -7
  84. package/src/components/select/select.js +4 -4
  85. package/src/components/stat-tile/stat-tile.css +56 -2
  86. package/src/components/stat-tile/stat-tile.js +25 -2
  87. package/src/components/stepper/stepper.css +2 -1
  88. package/src/components/stepper/stepper.js +3 -3
  89. package/src/components/tabbox/tabbox.css +2 -2
  90. package/src/components/tabbox/tabbox.js +2 -2
  91. package/src/components/table/table.css +52 -16
  92. package/src/components/table/table.js +7 -5
  93. package/src/components/tag-picker/tag-picker.css +56 -43
  94. package/src/components/tag-picker/tag-picker.js +21 -16
  95. package/src/components/tree/tree.css +44 -0
  96. package/src/components/tree/tree.js +97 -9
  97. package/src/components/value-list/value-list.css +25 -4
  98. package/src/components/value-list/value-list.js +2 -1
  99. package/src/components/view/record-view.js +3 -3
  100. package/src/components/view-settings/view-settings.css +2 -1
  101. package/src/components/workspace-switcher/workspace-switcher.js +3 -3
  102. package/src/core/icons.js +34 -3
  103. package/src/elements/define.js +1 -0
  104. package/src/index.js +4 -2
  105. package/src/internal/app-rail.js +5 -1
  106. package/src/internal/row-actions.js +203 -0
  107. package/styles/base.css +26 -1
  108. package/styles/prose.css +306 -0
  109. package/styles/tokens/dark.css +97 -120
  110. package/styles/tokens/global.css +24 -9
  111. package/styles/tokens/semantic.css +464 -184
  112. package/styles/tokens/themes.css +9 -0
  113. package/styles/zx.css +3 -0
package/docs/api.json CHANGED
@@ -555,6 +555,12 @@
555
555
  "default": "'Applications'",
556
556
  "description": "Navigation accessible label."
557
557
  },
558
+ {
559
+ "name": "moreLabel",
560
+ "type": "string",
561
+ "default": "'More actions'",
562
+ "description": "Name of a destination's overflow menu when its `actions` fold; every action name is followed by the destination's label."
563
+ },
558
564
  {
559
565
  "name": "header",
560
566
  "type": "Node|string|number|{toElement: () => Node|null}|null",
@@ -995,7 +1001,7 @@
995
1001
  "name": "tone",
996
1002
  "type": "BadgeTone|null",
997
1003
  "default": "null",
998
- "description": "Categorical colour — a project, a label, a module — from the tone palette rather than the status set, so a tag never reads as a warning. When set it decides the colour and `kind` is ignored for it; `variant` still applies. Unknown names are ignored."
1004
+ "description": "Categorical colour — a project, a label, a module — from the tone palette rather than the status set, so a tag never reads as a warning. When set it decides the colour and the shape — a tag's small corners instead of a status pill — and `kind` is ignored for it; `variant` still applies. Unknown names are ignored."
999
1005
  },
1000
1006
  {
1001
1007
  "name": "variant",
@@ -2873,7 +2879,13 @@
2873
2879
  "name": "format",
2874
2880
  "type": "string",
2875
2881
  "default": "'%d.%m.%Y'",
2876
- "description": "Kernel date format used for both endpoints."
2882
+ "description": "Kernel date format the reader types for both endpoints, shown while the field has focus. Numeric tokens only, since it is parsed."
2883
+ },
2884
+ {
2885
+ "name": "displayFormat",
2886
+ "type": "string|null",
2887
+ "default": "null",
2888
+ "description": "Format both endpoints are shown in while the field does not have focus. It is never parsed, so it may use any `formatDate()` token, month and weekday names included. Null shows `format`."
2877
2889
  },
2878
2890
  {
2879
2891
  "name": "separator",
@@ -3170,7 +3182,13 @@
3170
3182
  "name": "format",
3171
3183
  "type": "string",
3172
3184
  "default": "'%d.%m.%Y'",
3173
- "description": "Kernel date format."
3185
+ "description": "Kernel date format the reader types, shown while the field has focus. Numeric tokens only (`%d %e %m %Y %y %H %M %S`), since it is parsed."
3186
+ },
3187
+ {
3188
+ "name": "displayFormat",
3189
+ "type": "string|null",
3190
+ "default": "null",
3191
+ "description": "Format the field shows while it does not have focus, so a date reads as the rest of the screen writes dates. It is never parsed, so it may use any `formatDate()` token, month and weekday names included. Null shows `format`."
3174
3192
  },
3175
3193
  {
3176
3194
  "name": "time",
@@ -5912,6 +5930,24 @@
5912
5930
  }
5913
5931
  ]
5914
5932
  },
5933
+ "Kbd": {
5934
+ "options": [
5935
+ {
5936
+ "name": "size",
5937
+ "type": "'md'|'sm'",
5938
+ "default": "'md'",
5939
+ "description": "Keycap size; `sm` sits inside a button or a menu row."
5940
+ },
5941
+ {
5942
+ "name": "tone",
5943
+ "type": "'neutral'|'inherit'",
5944
+ "default": "'neutral'",
5945
+ "description": "`inherit` draws the keycaps in the surrounding ink — on a solid primary button, a dark toast — instead of the neutral surface keycap."
5946
+ }
5947
+ ],
5948
+ "events": [],
5949
+ "methods": []
5950
+ },
5915
5951
  "Launcher": {
5916
5952
  "options": [
5917
5953
  {
@@ -7769,6 +7805,54 @@
7769
7805
  "events": [],
7770
7806
  "methods": []
7771
7807
  },
7808
+ "ProseAnchors": {
7809
+ "options": [
7810
+ {
7811
+ "name": "selector",
7812
+ "type": "string",
7813
+ "default": "'h2[id], h3[id], h4[id]'",
7814
+ "description": "The headings that get a link, inside a `.zx-prose` under the root. A heading without an `id` has nothing to link to and is skipped."
7815
+ },
7816
+ {
7817
+ "name": "label",
7818
+ "type": "string",
7819
+ "default": "'Copy link to %1'",
7820
+ "description": "The link's accessible name; `%1` is the heading."
7821
+ },
7822
+ {
7823
+ "name": "title",
7824
+ "type": "string",
7825
+ "default": "'Copy link'",
7826
+ "description": "The link's tooltip."
7827
+ },
7828
+ {
7829
+ "name": "feedback",
7830
+ "type": "string",
7831
+ "default": "'Link copied'",
7832
+ "description": "What the live region says after a copy."
7833
+ },
7834
+ {
7835
+ "name": "feedbackDuration",
7836
+ "type": "number",
7837
+ "default": "2000",
7838
+ "description": "Milliseconds the tick and the message stay."
7839
+ },
7840
+ {
7841
+ "name": "href",
7842
+ "type": "(id: string) => string",
7843
+ "default": null,
7844
+ "description": "The address copied for a heading id. Defaults to the current address with its hash replaced (`sectionHref(location.href, id)`)."
7845
+ }
7846
+ ],
7847
+ "events": [
7848
+ {
7849
+ "name": "copy",
7850
+ "payload": null,
7851
+ "description": "Called with the address and whether the clipboard took it."
7852
+ }
7853
+ ],
7854
+ "methods": []
7855
+ },
7772
7856
  "Questionnaire": {
7773
7857
  "options": [
7774
7858
  {
@@ -9810,6 +9894,18 @@
9810
9894
  "default": "'neutral'",
9811
9895
  "description": "Semantic intent. It tints the sparkline and never the value, which stays at full text contrast whatever intent a record carries."
9812
9896
  },
9897
+ {
9898
+ "name": "variant",
9899
+ "type": "StatTileVariant",
9900
+ "default": "'default'",
9901
+ "description": "`'default'` is a framed tile on its own surface, for a figure that stands among other content (a dashboard). `'plain'` drops the frame, the fill and the padding and sets the figure a size smaller, for a row of figures on a page (a record's amounts under its title). Reflected as `data-variant` on the root."
9902
+ },
9903
+ {
9904
+ "name": "emphasis",
9905
+ "type": "boolean",
9906
+ "default": "false",
9907
+ "description": "The figure leads its row: in a plain row it is set at the display size while the others stay smaller, on a framed tile one step above the display size. Give it to one tile per row. Reflected as `data-emphasis=\"true\"`."
9908
+ },
9813
9909
  {
9814
9910
  "name": "href",
9815
9911
  "type": "string|null",
@@ -10811,7 +10907,7 @@
10811
10907
  "name": "toneKey",
10812
10908
  "type": "TagValueReader",
10813
10909
  "default": "'tone'",
10814
- "description": "Optional item tone property or reader: a categorical tone name from the Badge palette (`blue`, `teal`, `green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`). A toned tag takes the palette's fill and ink, as a Badge with that `tone` does; a tone wins over a colour, and unknown names are ignored."
10910
+ "description": "Optional item tone property or reader: a categorical tone name from the Badge palette (`blue`, `teal`, `green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`). Every tag is built by `badge()`, so a toned tag is the Badge with that `tone` — the same shape, size, fill and ink it has in a list row or a record header; a tone wins over a colour, and unknown names are ignored."
10815
10911
  },
10816
10912
  {
10817
10913
  "name": "searchKeys",
@@ -11537,6 +11633,18 @@
11537
11633
  "default": "null",
11538
11634
  "description": "Label renderer."
11539
11635
  },
11636
+ {
11637
+ "name": "rowActions",
11638
+ "type": "((node: TreeNode) => Array<RowAction|Node>)|null",
11639
+ "default": "null",
11640
+ "description": "A row's actions: `{icon, label, onSelect(node), disabled?, danger?}` descriptors, or nodes placed as given. They rest out of sight and show while the row is pointed at, focused or selected; one or two show as icon buttons, more fold after the first into a \"More actions\" menu. Every descriptor is also in the row's context menu, and the focused row's actions follow it in the Tab order."
11641
+ },
11642
+ {
11643
+ "name": "moreLabel",
11644
+ "type": "string",
11645
+ "default": "'More actions'",
11646
+ "description": "Name of a row's overflow menu; every action name is followed by the row's name (\"More actions: Q3 plan\")."
11647
+ },
11540
11648
  {
11541
11649
  "name": "load",
11542
11650
  "type": "((node: TreeNode) => Promise<TreeNode[]>|TreeNode[])|null",
package/docs/llms.md CHANGED
@@ -147,7 +147,7 @@ a second navigation.
147
147
  | A spreadsheet-like editable grid (lines, positions) | `Grid` (`Grid.BillingItems()`) | `Table` with `editMode` — that is for occasional cell edits |
148
148
  | A tree | `TreeView` (one column) or `Finder` (Miller columns) | nested `<ul>`s |
149
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 |
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
151
  | A chart | `Chart` with `ChartJsAdapter` (Chart.js injected, never bundled) | — |
152
152
  | A linked record inline | `EntityRef` | a link |
153
153
  | Files | `FileItem` / `FileList`; uploading: `FieldUpload` | — |
@@ -183,12 +183,13 @@ the library already reads — never as component CSS:
183
183
 
184
184
  1. **Theme** — `data-zx-theme="auto"` unless the product pins `light` or `dark`. Both must work; a
185
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
186
+ 2. **Accent** — a preset (`data-zx-preset="zx|zeyos|ocean|violet|rose|slate|folio"`) or a five-stop
187
187
  `--zx-accent-300…700` ramp built in the theme studio (<https://zx.zeyos.com/theme.html>), which
188
188
  exports the CSS. Never a one-off colour on a button.
189
189
  3. **Geometry** — the rhythm is three tokens on `:root` (or on a dense region): `--zx-space-unit`,
190
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.
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.
192
193
  4. **Material** — how surfaces answer light, exported from the studio as token overrides (there
193
194
  is no attribute). `Glass` (the default: a thin lit pane), `Deep glass` (a thick one), `Frost`
194
195
  (milk glass for reading surfaces), `Smoke` (tinted glass that darkens the scene; dark-first
@@ -201,13 +202,20 @@ the library already reads — never as component CSS:
201
202
  6. **Colour roles** — `--zx-color-tone-*` for categories (tags, modules, avatars),
202
203
  `--zx-color-danger|warning|success|info` for status, `--zx-color-bg-current` for "you are here"
203
204
  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
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
208
216
  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
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
211
219
  authored as HTML.
212
220
 
213
221
  ### Never
@@ -234,18 +242,53 @@ Themes: `light` | `dark` | `auto` (follows OS).
234
242
  **One geometry.** Spacing steps are multiples of one unit
235
243
  (`--zx-space-unit`, 4px: `--zx-space-1…8` = 4/8/12/16/20/24/32/40px), radius steps are fractions of
236
244
  one base (`--zx-radius`, 4px: `-sm/-md/-lg/-xl` = 2/3/4/6px; `-full` only for shapes whose roundness
237
- 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.
238
253
  To tighten or loosen an application, override those tokens on `:root` or on any region. The
239
254
  geometry and material tokens (control size, radius, spacing, blur and glass filters, durations,
240
- easings, the type scale) are declared on `:root` only, never on a `[data-zx-theme]` block, so an
241
- 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**):
242
258
 
243
259
  ```css
244
260
  :root { --zx-space-unit: 3.5px; --zx-control-height: 28px; }
245
261
  ```
246
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
+
247
290
  **Accent presets.** A second, orthogonal attribute picks the accent ramp:
248
- `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
249
292
  need not be set). A preset repoints five tier-1 tokens — `--zx-accent-300` … `--zx-accent-700` —
250
293
  and the semantic tier takes its own stop per polarity (600/700 on light surfaces, 300/400/500 on
251
294
  dark), so one five-line block rethemes light, dark, and auto together. Status colours are not part
@@ -293,10 +336,16 @@ increased-contrast, forced-colour, and unsupported-filter environments restore s
293
336
  Top-layer components remain DOM children of their nearest Zx theme scope, so a theme or material
294
337
  set on an application region continues to inherit through its menus, dialogs, tooltips, and toasts.
295
338
 
296
- 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:
297
342
  `--zx-color-bg-page/surface/raised/control/muted/hover/selected`, `--zx-color-bg-current` (the
298
343
  neutral "you are here" fill of the current nav item, row, tab, or pressed toggle — never the
299
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),
300
349
  `--zx-color-glass-chrome/surface`,
301
350
  `--zx-color-overlay-surface/panel/backdrop/border/hover/selected/divider/scrim`,
302
351
  `--zx-overlay-surface-image/toast-image/panel-image`,
@@ -309,12 +358,29 @@ accent), `--zx-color-bg-chrome` (navigation and inspector columns, one tone off
309
358
  tiles, avatars — neither the accent nor a status) and `-solid` (a solid identity fill, such as a
310
359
  module tile, that the white icon glyph reads on at 3:1 in both themes), the chart series
311
360
  `--zx-color-chart-1…8`,
312
- `--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-*`
313
363
  (`-3xl` for document titles), `--zx-weight-medium/-semibold`, `--zx-tracking-tight/-title`. Never
314
364
  use tier-1 palette tokens (`--zx-gray-*`, `--zx-green-*`, `--zx-emerald-*`, `--zx-tone-*`) or raw
315
365
  color literals in application/component CSS. Prefer the least-specific override that works (global
316
366
  token → then, if needed, a component style).
317
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
+
318
384
  **Print.** `zx.css` imports `styles/print.css` last. It releases sticky headers and scroll
319
385
  containers, drops fills, shadows, zebra striping and focus rings, hides overlays and navigation
320
386
  chrome, repeats table headers across pages, keeps cards and rows from breaking, and prints link
@@ -559,6 +625,65 @@ reflection and ElementInternals form association: `<zx-toggle>`, `<zx-check-butt
559
625
  Each component is `new Component(target, options)`. Events are the component-level names (also
560
626
  dispatched as bubbling `zx-<name>` on the root). Detail is always an object.
561
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
+
562
687
  <!-- doc:button -->
563
688
  ### Button — `button(options)` / `buttonGroup(buttons)`
564
689
 
@@ -582,9 +707,9 @@ accept.
582
707
  <!-- doc:badge -->
583
708
  ### Badge — `badge(options)` / `badgeGroup(badges)`
584
709
 
585
- Factories (not classes) returning a status pill: a small, non-interactive `<span>` carrying a
586
- semantic colour — or, with `tone`, a categorical one — used for stages, counts, tags, and
587
- 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
588
713
  through `role="img"`; everything else is plain text and needs no ARIA.
589
714
 
590
715
  - **Options** — `label`, `icon` (an icon name, rendered before the label), `kind:
@@ -597,11 +722,18 @@ through `role="img"`; everything else is plain text and needs no ARIA.
597
722
  accent nor the status set, so a project tagged red never reads as an error. When `tone` is set it
598
723
  decides the colour and `kind` is ignored for it; every `variant` still applies (soft: tinted,
599
724
  borderless; solid: filled with the tone's ink; outline). The badge carries `data-tone`. Badges
600
- 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.
601
733
  - **Neutral and small** — the neutral soft fill is a wash of the text colour, not an opaque surface
602
734
  step, so it stays visible on raised surfaces in the dark theme. `size: 'sm'` fits table cells
603
- and board cards; a small badge with `dot` keeps the 12px text and a full spacing step between
604
- 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.
605
737
  - **Methods** — none. `badge(options)` → `HTMLSpanElement`, `badgeGroup([badge(…), …])` → a wrapping
606
738
  inline row with its own spacing; you own both elements.
607
739
  - **Events** — none; a badge is not interactive.
@@ -1305,9 +1437,19 @@ Text date input with a calendar popover. `DateTimeBox(target, opts)` is a Datebo
1305
1437
  `time: true`, which also brings the TimePicker (and its clock face) into the popover. Format
1306
1438
  tokens are the date-utility ones: `%d %m %Y %H %M`.
1307
1439
 
1308
- - **Options** — `value: Date | number(unix) | string`, `format: '%d.%m.%Y'`, `time: false`, `min`,
1309
- `max`, `placeholder`, `clearable: true` (the clear button shows while there is a value and the
1310
- 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.
1311
1453
  - **In a Field** — field types `date`/`datetime` (and `daterange`) fill the control column like a
1312
1454
  text input and give way in a narrow two-column row; standalone, the box keeps its own width.
1313
1455
  - **Methods** — `get(unit='date')` (`'seconds'` → unix), `set(value, {silent})` (accepts a Date;
@@ -1333,7 +1475,7 @@ An inline two-month calendar for picking a start and an end day, plus the form-u
1333
1475
 
1334
1476
  #### DateRangeBox
1335
1477
 
1336
- - **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.
1337
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()`.
1338
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`.
1339
1481
  <!-- /doc -->
@@ -2221,7 +2363,17 @@ mutate the caller's data.
2221
2363
  - **Options** — `items` (nested), `valueKey: 'ID'`, `labelKey: 'name'`, `childrenKey: 'children'`,
2222
2364
  `expanded: []`, `selection: 'single'|'multi'|false`, `selected: []`, `checkboxes: false`
2223
2365
  (tri-state), `checked: []`, `icons: true`, `renderLabel`, `load: (node)=>Promise<children>`
2224
- (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.
2225
2377
  - **Methods** — `setItems()`, `getItems()`, `getNode(id)`, `getPath(id)`, `setFilter(query)` (keeps
2226
2378
  matching nodes' ancestors and opens the surviving branches),
2227
2379
  `expand(id)`/`collapse(id)`/`toggle(id)` (async — they await the loader),
@@ -2234,6 +2386,9 @@ mutate the caller's data.
2234
2386
  activates, Space selects or toggles the checkbox, `*` expands every sibling, typing jumps to the
2235
2387
  next match. A typed character's default action is prevented, so find-as-you-type and page
2236
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.
2237
2392
  - **Appearance** — the selected node of a single-selection tree is where you are: the neutral
2238
2393
  `--zx-color-bg-current` fill, the text colour, a semibold label. A `selection: 'multi'` tree is a
2239
2394
  set of picks and keeps the accent tint. Icons, folders included, are drawn in
@@ -2503,12 +2658,16 @@ yet. Field type: `tagpicker`.
2503
2658
  `filter: 'local'|(query)=>Promise<items>`, `minQuery: 0`, `debounce: 200`, `allowCreate: false`,
2504
2659
  `max` (maximum tags; further options become `aria-disabled`), `closeOnSelect: false`,
2505
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.
2506
2667
  - **Tag identity** — icon values accept a bundled icon name or Node; colors (a CSS colour or a token
2507
2668
  reference such as `var(--zx-color-tone-blue-fg)`) are scoped to the tag and its option through
2508
- `--zx-tag-color`. `toneKey` names a categorical tone from the Badge palette (`blue`, `teal`,
2509
- `green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`): the tag takes its fill and ink as a
2510
- toned Badge does (`data-tone`), and a tone wins over a colour. Custom `renderItem`/`renderTag`
2511
- 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.
2512
2671
  - **Read-only** — `readonly` (or `setReadonly(true)`) shows only the tags: no input, chevron, or
2513
2672
  remove buttons, so a full row of tags never wraps onto an empty line.
2514
2673
  - **Methods** — `getValues()`, `getItems()`, `setValues(values, {silent})`, `addValue()`,
@@ -2567,13 +2726,21 @@ returns the component, the way `tooltip()` does; call `.toElement()` for the nod
2567
2726
 
2568
2727
  - **Options** — `label`, `value`, `format: 'number'|'currency'|'percent'|'fileSize'|null|fn`,
2569
2728
  `currency`, `locale`, `caption`, `delta`, `deltaKind: 'positive'|'negative'|'neutral'`,
2570
- `deltaFormat`, `deltaLabel`, `trend: number[]`, `icon`, `kind`, `href`, `clickable`, `loading`,
2571
- `msg`.
2729
+ `deltaFormat`, `deltaLabel`, `trend: number[]`, `icon`, `kind`, `variant: 'default'|'plain'`,
2730
+ `emphasis`, `href`, `clickable`, `loading`, `msg`.
2572
2731
  - **Appearance** — the label is a sentence-case muted line (13px, medium); the value is the loud
2573
2732
  part (24px, weight 650, tabular figures); `caption` is one muted context line under it ("of
2574
2733
  13,184"). `icon` is a muted glyph beside the label, never a coloured chip; `kind` tints only the
2575
2734
  sparkline. The tile is a column with the sparkline at its foot, so tiles in a row are the same
2576
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.
2577
2744
  - **Methods** — `update(options)`, `getAccessibleName()`.
2578
2745
  - **Events** — `click {event}`.
2579
2746
 
@@ -2971,8 +3138,18 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
2971
3138
  `side: 'left'|'right'|'top'|'bottom'`, `layout: 'tree'|'modules'`, `module`, `moduleBar`
2972
3139
  (`{appearance, labels: 'auto'|'beside'|'below'|'hidden', allModules, label}` for the module
2973
3140
  strip), `label`,
2974
- `header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`, and
2975
- `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.
2976
3153
  - **Sections** — an item with `section: true` is a quiet heading over its `children`, which stay
2977
3154
  at its own level: never indented, collapsed, focused, or selected, and it needs no `id`.
2978
3155
  `actions` (a node) adds trailing controls such as an add button. Sections replace stacking
@@ -3119,8 +3296,8 @@ bar.setBadge('mail', 8);
3119
3296
  newest-first handler registry. Existing `DOM.on/remEvt/fireEvt` methods can delegate to this
3120
3297
  triad. Zx never installs globals or alters DOM prototypes; applications decide whether to expose
3121
3298
  these functions globally or compose them into their own UI and routing layer.
3122
- - **Icons** — `icon(name, {size, label})` and `icons`; see the Icons section — bundled inline SVG
3123
- 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.
3124
3301
  - **Positioning** — `position(anchor, floating, {placement, offset, flip, matchWidth})` →
3125
3302
  `{update, destroy}`. It anchors a manual popover with CSS anchor positioning where the browser
3126
3303
  supports it and a scroll/resize-tracked fallback where it does not. Options are resolved once,
@@ -3193,6 +3370,26 @@ old `RangeError`, at a call site that can afford to fail: a test, or a build-tim
3193
3370
  Font Awesome elements are sized with `font-size` and occupy 1em; bundled SVGs use width/height
3194
3371
  attributes (default 16). Both honour `label` (`null` ⇒ `aria-hidden`, otherwise `role="img"` +
3195
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()`.
3196
3393
  <!-- /doc -->
3197
3394
 
3198
3395
  <!-- doc:helpers -->
@@ -3298,7 +3495,8 @@ destroys its component.
3298
3495
 
3299
3496
  Registered elements: `<zx-toggle>`, `<zx-check-button>`, `<zx-select items='[…]' required>`,
3300
3497
  `<zx-checklist>`, `<zx-datebox>`, `<zx-timebox>`, `<zx-search>`, `<zx-groupbox>`, `<zx-tabbox>`,
3301
- `<zx-table>`, `<zx-dialog>`.
3498
+ `<zx-table>`, `<zx-dialog>`. `<zx-datebox>` takes `display-format` beside `format`, as the
3499
+ Datebox options `displayFormat` and `format`.
3302
3500
  <!-- /doc -->
3303
3501
 
3304
3502
  <!-- doc:tokens -->
@@ -3369,4 +3567,12 @@ record: native inputs, selects, and textareas inside it drop their border and fi
3369
3567
  (`--zx-color-bg-hover`) or focus (the normal border, the control fill, and the focus ring), so values
3370
3568
  read as text rather than as a wall of boxes. Read-only and disabled fields stay quiet. The rules have
3371
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.
3372
3578
  <!-- /doc -->
package/docs/llms.txt CHANGED
@@ -37,6 +37,8 @@ exports and as `window.zx.*`.
37
37
  building anything.
38
38
 
39
39
  ## Components
40
+ - Foundations: `.zx-prose` (the reading register for authored content) and `.zx-callout`;
41
+ `kbd()` (keycaps for every shortcut hint).
40
42
  - Inputs: `button()`, `buttonGroup()`, `badge()`/`badgeGroup()`, `CheckButton`,
41
43
  `Toggle`, `Search`,
42
44
  `Select` (APG combobox; `filter: false|'local'|async`; priority, status, permission, and