@zeyos/zx 5.7.0 → 5.8.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 (330) hide show
  1. package/CHANGELOG.md +330 -0
  2. package/README.md +47 -9
  3. package/dist/types/components/activity-item/activity-item.d.ts +14 -3
  4. package/dist/types/components/agent-avatar/agent-avatar.d.ts +165 -0
  5. package/dist/types/components/agent-avatar/agent-face.d.ts +93 -0
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +21 -9
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +26 -0
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +3 -1
  9. package/dist/types/components/approval-card/approval-card.d.ts +31 -2
  10. package/dist/types/components/aurora/aurora.d.ts +31 -5
  11. package/dist/types/components/calendar/calendar.d.ts +39 -26
  12. package/dist/types/components/chart/chart.d.ts +250 -20
  13. package/dist/types/components/chart/color.d.ts +66 -0
  14. package/dist/types/components/chart/svg-adapter.d.ts +103 -0
  15. package/dist/types/components/chart/svg-geometry.d.ts +203 -0
  16. package/dist/types/components/check-button/check-button.d.ts +1 -4
  17. package/dist/types/components/checklist/checklist.d.ts +48 -5
  18. package/dist/types/components/code-editor/code-editor.d.ts +55 -1
  19. package/dist/types/components/composer/composer.d.ts +41 -6
  20. package/dist/types/components/context-menu/context-menu.d.ts +36 -8
  21. package/dist/types/components/copy/copy-button.d.ts +6 -0
  22. package/dist/types/components/copy/copy-input.d.ts +1 -0
  23. package/dist/types/components/date-picker/date-picker.d.ts +14 -0
  24. package/dist/types/components/date-picker/time-picker.d.ts +26 -17
  25. package/dist/types/components/datebox/datebox.d.ts +8 -4
  26. package/dist/types/components/dialog/dialog.d.ts +15 -4
  27. package/dist/types/components/empty-state/empty-state.d.ts +10 -1
  28. package/dist/types/components/field/field.d.ts +4 -2
  29. package/dist/types/components/form/form.d.ts +2 -1
  30. package/dist/types/components/kanban-view/kanban-card.d.ts +7 -0
  31. package/dist/types/components/kanban-view/kanban-view.d.ts +15 -3
  32. package/dist/types/components/launcher/launcher.d.ts +26 -0
  33. package/dist/types/components/master-panel/master-panel.d.ts +9 -4
  34. package/dist/types/components/menu-button/menu-button.d.ts +29 -5
  35. package/dist/types/components/message/message.d.ts +308 -5
  36. package/dist/types/components/modal/modal.d.ts +45 -8
  37. package/dist/types/components/modal/native-dialog.d.ts +40 -0
  38. package/dist/types/components/module-bar/module-bar.d.ts +9 -2
  39. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +5 -4
  40. package/dist/types/components/number-field/number-field.d.ts +31 -1
  41. package/dist/types/components/pagination/pagination.d.ts +341 -19
  42. package/dist/types/components/run-status/run-status.d.ts +26 -0
  43. package/dist/types/components/run-trace/run-trace.d.ts +10 -6
  44. package/dist/types/components/search/search.d.ts +16 -4
  45. package/dist/types/components/select/select.d.ts +19 -1
  46. package/dist/types/components/sheet/sheet.d.ts +20 -6
  47. package/dist/types/components/slider/slider.d.ts +2 -1
  48. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -3
  49. package/dist/types/components/stepper/stepper.d.ts +17 -4
  50. package/dist/types/components/surface/catalog.d.ts +61 -17
  51. package/dist/types/components/surface/surface.d.ts +6 -4
  52. package/dist/types/components/table/table.d.ts +207 -5
  53. package/dist/types/components/table/window.d.ts +25 -1
  54. package/dist/types/components/toggle/toggle.d.ts +38 -6
  55. package/dist/types/components/tooltip/tooltip.d.ts +5 -4
  56. package/dist/types/components/tree/tree.d.ts +43 -6
  57. package/dist/types/components/truncate/truncate.d.ts +4 -2
  58. package/dist/types/components/value-list/value-list.d.ts +9 -2
  59. package/dist/types/core/date.d.ts +2 -1
  60. package/dist/types/core/dom.d.ts +14 -0
  61. package/dist/types/core/drag-axis.d.ts +10 -5
  62. package/dist/types/core/export.d.ts +2 -2
  63. package/dist/types/core/format.d.ts +3 -1
  64. package/dist/types/core/icons.d.ts +36 -3
  65. package/dist/types/core/keyboard.d.ts +7 -3
  66. package/dist/types/core/messages.d.ts +3 -0
  67. package/dist/types/core/storage.d.ts +4 -3
  68. package/dist/types/core/util.d.ts +3 -1
  69. package/dist/types/elements/define.d.ts +5 -2
  70. package/dist/types/index.d.ts +6 -4
  71. package/dist/types/internal/agent-model.d.ts +99 -0
  72. package/dist/types/internal/app-rail.d.ts +37 -2
  73. package/dist/types/internal/collections.d.ts +18 -0
  74. package/dist/types/internal/menu-items.d.ts +27 -0
  75. package/dist/types/internal/overlay-content.d.ts +23 -0
  76. package/dist/types/internal/presence-loop.d.ts +5 -2
  77. package/dist/types/locales/index.d.ts +3 -0
  78. package/dist/types/zeyos/calendar.d.ts +43 -7
  79. package/dist/types/zeyos/connect.d.ts +4 -0
  80. package/dist/types/zeyos/form.d.ts +13 -5
  81. package/dist/types/zeyos/select.d.ts +5 -2
  82. package/dist/types/zeyos/table.d.ts +16 -8
  83. package/dist/types/zeyos/view.d.ts +2 -1
  84. package/dist/zx-zeyos.esm.js +3161 -515
  85. package/dist/zx-zeyos.esm.min.js +4 -4
  86. package/dist/zx.core.css +4 -0
  87. package/dist/zx.core.min.css +1 -1
  88. package/dist/zx.css +970 -57
  89. package/dist/zx.esm.js +6405 -2249
  90. package/dist/zx.esm.min.js +26 -26
  91. package/dist/zx.global.js +6405 -2249
  92. package/dist/zx.global.min.js +26 -26
  93. package/dist/zx.layered.css +972 -57
  94. package/dist/zx.layered.min.css +1 -1
  95. package/dist/zx.min.css +1 -1
  96. package/docs/agent-catalog.json +159 -1
  97. package/docs/agent-surfaces.md +21 -21
  98. package/docs/api.json +3154 -518
  99. package/docs/components/account-menu.md +24 -0
  100. package/docs/components/activity-item.md +23 -0
  101. package/docs/components/activity-list.md +28 -0
  102. package/docs/components/agent-avatar.md +59 -0
  103. package/docs/components/agent-thread.md +275 -0
  104. package/docs/components/app-icon.md +36 -0
  105. package/docs/components/app-sidebar.md +92 -0
  106. package/docs/components/approval-card.md +71 -0
  107. package/docs/components/aurora.md +34 -0
  108. package/docs/components/avatar.md +37 -0
  109. package/docs/components/badge.md +36 -0
  110. package/docs/components/block-view.md +34 -0
  111. package/docs/components/breadcrumb.md +20 -0
  112. package/docs/components/button.md +23 -0
  113. package/docs/components/calendar.md +68 -0
  114. package/docs/components/card-view.md +73 -0
  115. package/docs/components/card.md +25 -0
  116. package/docs/components/chart.md +109 -0
  117. package/docs/components/check-button.md +16 -0
  118. package/docs/components/checklist.md +19 -0
  119. package/docs/components/code-editor.md +38 -0
  120. package/docs/components/composer.md +107 -0
  121. package/docs/components/context-menu.md +32 -0
  122. package/docs/components/copy.md +37 -0
  123. package/docs/components/data-filter.md +16 -0
  124. package/docs/components/date-picker.md +31 -0
  125. package/docs/components/date-range.md +21 -0
  126. package/docs/components/datebox.md +31 -0
  127. package/docs/components/dialog.md +25 -0
  128. package/docs/components/dock.md +57 -0
  129. package/docs/components/dropdown.md +39 -0
  130. package/docs/components/elements.md +63 -0
  131. package/docs/components/empty-state.md +17 -0
  132. package/docs/components/entity-ref.md +26 -0
  133. package/docs/components/field-upload.md +18 -0
  134. package/docs/components/file-item.md +27 -0
  135. package/docs/components/file-list.md +23 -0
  136. package/docs/components/filter-panel.md +45 -0
  137. package/docs/components/filter.md +47 -0
  138. package/docs/components/finder.md +25 -0
  139. package/docs/components/form-widgets.md +42 -0
  140. package/docs/components/form.md +80 -0
  141. package/docs/components/grid.md +26 -0
  142. package/docs/components/groupbox.md +11 -0
  143. package/docs/components/helpers.md +359 -0
  144. package/docs/components/icons.md +87 -0
  145. package/docs/components/index.md +99 -0
  146. package/docs/components/kanban-view.md +42 -0
  147. package/docs/components/kbd.md +23 -0
  148. package/docs/components/kernel.md +41 -0
  149. package/docs/components/launcher.md +66 -0
  150. package/docs/components/layout.md +33 -0
  151. package/docs/components/list-toolbar.md +38 -0
  152. package/docs/components/loading.md +48 -0
  153. package/docs/components/menu-button.md +47 -0
  154. package/docs/components/message.md +76 -0
  155. package/docs/components/modal.md +27 -0
  156. package/docs/components/module-bar.md +71 -0
  157. package/docs/components/multi-value-editor.md +16 -0
  158. package/docs/components/navigation-bar.md +22 -0
  159. package/docs/components/number-field.md +34 -0
  160. package/docs/components/pagination.md +73 -0
  161. package/docs/components/panel.md +28 -0
  162. package/docs/components/prompt-starters.md +40 -0
  163. package/docs/components/prose.md +38 -0
  164. package/docs/components/questionnaire.md +115 -0
  165. package/docs/components/rating.md +19 -0
  166. package/docs/components/run-status.md +50 -0
  167. package/docs/components/run-trace.md +72 -0
  168. package/docs/components/search.md +11 -0
  169. package/docs/components/select.md +129 -0
  170. package/docs/components/sheet-stack.md +39 -0
  171. package/docs/components/sheet.md +77 -0
  172. package/docs/components/skeleton.md +27 -0
  173. package/docs/components/slider.md +29 -0
  174. package/docs/components/sort-control.md +21 -0
  175. package/docs/components/source-list.md +30 -0
  176. package/docs/components/split-view.md +12 -0
  177. package/docs/components/stat-tile.md +49 -0
  178. package/docs/components/stepper.md +27 -0
  179. package/docs/components/surface.md +152 -0
  180. package/docs/components/tabbox.md +33 -0
  181. package/docs/components/table-view.md +43 -0
  182. package/docs/components/table.md +232 -0
  183. package/docs/components/tag-picker.md +39 -0
  184. package/docs/components/timebox.md +16 -0
  185. package/docs/components/toggle.md +21 -0
  186. package/docs/components/tokens.md +82 -0
  187. package/docs/components/toolbar.md +26 -0
  188. package/docs/components/tooltip.md +16 -0
  189. package/docs/components/tree.md +48 -0
  190. package/docs/components/truncate.md +21 -0
  191. package/docs/components/value-list.md +14 -0
  192. package/docs/components/view-settings.md +56 -0
  193. package/docs/components/workspace-switcher.md +42 -0
  194. package/docs/components/zeyos.md +196 -0
  195. package/docs/llms-small.txt +299 -0
  196. package/docs/llms.md +725 -109
  197. package/docs/llms.txt +46 -19
  198. package/package.json +9 -4
  199. package/src/components/activity-item/activity-item.js +21 -2
  200. package/src/components/agent-avatar/agent-avatar.css +195 -0
  201. package/src/components/agent-avatar/agent-avatar.js +333 -0
  202. package/src/components/agent-avatar/agent-face.js +292 -0
  203. package/src/components/agent-thread/ag-ui.js +44 -11
  204. package/src/components/agent-thread/agent-thread.js +103 -11
  205. package/src/components/agent-thread/ui-message-stream.js +3 -1
  206. package/src/components/app-rail/app-rail.css +5 -0
  207. package/src/components/app-sidebar/app-sidebar.css +3 -0
  208. package/src/components/app-sidebar/app-sidebar.js +4 -3
  209. package/src/components/approval-card/approval-card.css +6 -0
  210. package/src/components/approval-card/approval-card.js +55 -7
  211. package/src/components/aurora/aurora.css +149 -14
  212. package/src/components/aurora/aurora.js +49 -6
  213. package/src/components/button/button.css +24 -11
  214. package/src/components/calendar/calendar.css +6 -2
  215. package/src/components/calendar/calendar.js +127 -47
  216. package/src/components/card-view/card-view.js +5 -6
  217. package/src/components/chart/chart.css +159 -1
  218. package/src/components/chart/chart.js +450 -62
  219. package/src/components/chart/color.js +297 -0
  220. package/src/components/chart/svg-adapter.js +576 -0
  221. package/src/components/chart/svg-geometry.js +323 -0
  222. package/src/components/check-button/check-button.js +3 -18
  223. package/src/components/checklist/checklist.css +9 -1
  224. package/src/components/checklist/checklist.js +105 -20
  225. package/src/components/checklist/field-adapter.js +6 -12
  226. package/src/components/code-editor/code-editor.css +33 -0
  227. package/src/components/code-editor/code-editor.js +97 -8
  228. package/src/components/code-editor/field-adapter.js +3 -0
  229. package/src/components/composer/composer.css +3 -0
  230. package/src/components/composer/composer.js +100 -22
  231. package/src/components/context-menu/context-menu.js +41 -5
  232. package/src/components/copy/copy-button.js +9 -1
  233. package/src/components/copy/copy-input.js +5 -0
  234. package/src/components/data-filter/filter-core.js +0 -1
  235. package/src/components/date-picker/date-picker.css +8 -0
  236. package/src/components/date-picker/date-picker.js +47 -8
  237. package/src/components/date-picker/date-range-picker.js +1 -1
  238. package/src/components/date-picker/month-picker.js +19 -3
  239. package/src/components/date-picker/time-picker.js +54 -19
  240. package/src/components/datebox/date-range-box.js +7 -3
  241. package/src/components/datebox/datebox.js +32 -6
  242. package/src/components/dialog/dialog.css +6 -0
  243. package/src/components/dialog/dialog.js +24 -33
  244. package/src/components/dropdown/dropdown.js +1 -18
  245. package/src/components/empty-state/empty-state.js +21 -2
  246. package/src/components/field/field.js +19 -3
  247. package/src/components/fieldset/fieldset.js +3 -1
  248. package/src/components/filter/filter.js +9 -0
  249. package/src/components/form/form.js +19 -2
  250. package/src/components/kanban-view/kanban-card.js +15 -2
  251. package/src/components/kanban-view/kanban-view.css +21 -0
  252. package/src/components/kanban-view/kanban-view.js +29 -16
  253. package/src/components/launcher/launcher.css +14 -0
  254. package/src/components/launcher/launcher.js +54 -9
  255. package/src/components/master-panel/master-panel.js +24 -22
  256. package/src/components/menu-button/menu-button.js +26 -4
  257. package/src/components/message/message.css +228 -29
  258. package/src/components/message/message.js +664 -30
  259. package/src/components/modal/modal.js +129 -30
  260. package/src/components/modal/native-dialog.js +91 -0
  261. package/src/components/module-bar/module-bar.css +3 -0
  262. package/src/components/module-bar/module-bar.js +17 -4
  263. package/src/components/multi-value-editor/multi-value-editor.css +7 -2
  264. package/src/components/multi-value-editor/multi-value-editor.js +3 -2
  265. package/src/components/navigation-bar/navigation-bar.js +13 -1
  266. package/src/components/number-field/field-adapter.js +3 -0
  267. package/src/components/number-field/number-field.js +70 -16
  268. package/src/components/pagination/pagination.css +26 -2
  269. package/src/components/pagination/pagination.js +551 -65
  270. package/src/components/prose/prose.js +7 -1
  271. package/src/components/rating/field-adapter.js +3 -0
  272. package/src/components/run-status/run-status.js +43 -3
  273. package/src/components/run-trace/run-trace.js +15 -7
  274. package/src/components/search/search.js +3 -18
  275. package/src/components/select/field-adapter.js +8 -1
  276. package/src/components/select/select.js +68 -13
  277. package/src/components/sheet/sheet.js +39 -13
  278. package/src/components/slider/field-adapter.js +3 -0
  279. package/src/components/slider/slider.js +4 -6
  280. package/src/components/stat-tile/stat-tile.js +24 -9
  281. package/src/components/stepper/stepper.css +15 -0
  282. package/src/components/stepper/stepper.js +34 -2
  283. package/src/components/surface/catalog.js +185 -28
  284. package/src/components/surface/surface.js +10 -5
  285. package/src/components/tabbox/tabbox.js +13 -1
  286. package/src/components/table/table.css +160 -2
  287. package/src/components/table/table.js +479 -52
  288. package/src/components/table/window.js +46 -4
  289. package/src/components/table-view/table-view.js +1 -10
  290. package/src/components/tag-picker/field-adapter.js +3 -0
  291. package/src/components/tag-picker/tag-picker.js +2 -0
  292. package/src/components/timebox/field-adapter.js +3 -0
  293. package/src/components/toggle/toggle.js +51 -27
  294. package/src/components/tooltip/tooltip.js +21 -14
  295. package/src/components/tree/tree.js +87 -14
  296. package/src/components/truncate/truncate.js +21 -5
  297. package/src/components/value-list/value-list.js +37 -9
  298. package/src/components/view-settings/view-settings.js +1 -5
  299. package/src/core/component.js +34 -2
  300. package/src/core/date.js +5 -4
  301. package/src/core/dom.js +45 -2
  302. package/src/core/drag-axis.js +24 -7
  303. package/src/core/export.js +4 -4
  304. package/src/core/fontawesome.js +34 -3
  305. package/src/core/format.js +3 -1
  306. package/src/core/http.js +23 -11
  307. package/src/core/icons.js +60 -8
  308. package/src/core/keyboard.js +83 -9
  309. package/src/core/messages.js +3 -0
  310. package/src/core/position.js +4 -3
  311. package/src/core/storage.js +80 -31
  312. package/src/core/util.js +16 -5
  313. package/src/elements/define.js +82 -47
  314. package/src/elements/kit.js +46 -35
  315. package/src/index.js +8 -4
  316. package/src/internal/agent-model.js +152 -0
  317. package/src/internal/app-rail.js +53 -2
  318. package/src/internal/collections.js +25 -0
  319. package/src/internal/menu-items.js +59 -0
  320. package/src/internal/overlay-content.js +35 -0
  321. package/src/internal/presence-loop.js +61 -14
  322. package/src/locales/de.js +3 -0
  323. package/src/zeyos/calendar.js +81 -19
  324. package/src/zeyos/connect.js +5 -1
  325. package/src/zeyos/form.js +29 -10
  326. package/src/zeyos/select.js +36 -12
  327. package/src/zeyos/table.js +43 -11
  328. package/src/zeyos/view.js +2 -1
  329. package/styles/tokens/semantic.css +7 -1
  330. package/styles/zx.css +1 -0
package/docs/llms.md CHANGED
@@ -8,14 +8,18 @@
8
8
  > its component, and lists the theme settings to decide. Each
9
9
  > component below is wrapped in `<!-- doc:<name> -->` markers so tools can extract a single
10
10
  > component's section (`website/docs.html` renders them as each component's Reference tab).
11
+ > A smaller first read is `docs/llms-small.txt` (under 8k tokens), and each section is also its own
12
+ > file, `docs/components/<name>.md`.
11
13
 
12
14
  ## Optional integration requirements
13
15
 
14
16
  Zx has no package runtime dependencies and its source modules import no external runtime packages.
15
- Optional integrations still need application-provided assets or clients. `Chart` requires an injected
16
- renderer; the only supplied renderer, `ChartJsAdapter`, requires Chart.js 4 supplied by the host.
17
- There is no built-in chart renderer. Chart.js 4.5.1 is pinned as a development dependency and copied
18
- to the documentation site's self-hosted vendor assets during its build; it is not bundled into Zx.
17
+ Optional integrations still need application-provided assets or clients. `Chart` draws through an
18
+ adapter: the built-in `SvgChartAdapter` draws bar, line, pie and doughnut charts as SVG with nothing
19
+ else loaded, and `Surface` draws its `chart` nodes with it by default; `ChartJsAdapter` draws any
20
+ Chart.js 4 type with a Chart.js the host supplies. Chart.js 4.5.1 is pinned as a development
21
+ dependency and copied to the documentation site's self-hosted vendor assets during its build; it is
22
+ not bundled into Zx.
19
23
  Core icons use bundled SVG by default. Opting into Font Awesome requires host-loaded CSS or a kit.
20
24
  ZeyOS `moduleIcon()`, `moduleChip()`, and `zeyosAppIcon()` default to glyphs from the external custom
21
25
  ZeyOS Font Awesome kit; `standard: true` still needs stock Font Awesome assets. `ZeyOS.connect()`
@@ -34,7 +38,10 @@ const t = new Table(target, options);
34
38
  **owns** its root element; retrieve it with `t.toElement()` (or `t.el`) and insert it. A non-null
35
39
  target is *enhanced in place* and restored on `destroy()`.
36
40
  - **Options** — a plain object; each component declares `static defaults`. Never mutate the passed
37
- object.
41
+ object. An option passed as `undefined` is an option not passed: it keeps the declared default,
42
+ at the top level and inside `msg`, so a wrapper can forward `{ label: props.label }` without
43
+ filtering unset props. `null` is a value and overrides the default. The merged options are
44
+ frozen; change a live component through its methods (see "Using Zx from a framework").
38
45
  - **Value/data** — set via constructor options and mutated via methods (`set`, `setData`, …);
39
46
  read via getters/methods (`.value`, `getValues()`, …).
40
47
 
@@ -55,8 +62,18 @@ const t = new Table(target, options);
55
62
 
56
63
  - ESM: `import { … } from '/assets/zx.esm.js'` (or `../src/index.js` in-repo, no build).
57
64
  - Granular: `import { Slider } from '@zeyos/zx/src/components/slider/slider.js'` — one component
58
- rather than the whole library, for consumers running a bundler. Two components bundle 26 kB
59
- minified against 157 kB through the package entry. `zx-css` does the same for the stylesheet.
65
+ rather than the whole library, for consumers running a bundler. Measured with esbuild 0.28.1
66
+ (`--bundle --minify --format=esm --target=es2022`): `Slider` and `Toggle` from their own files
67
+ bundle to about 49 kB (14 kB gzip), against about 276 kB (76 kB gzip) imported from the package
68
+ entry; `button()` alone is 15 kB against 279 kB. The package entry is one module that registers
69
+ the Field adapters, so a bundler keeps what those registrations reach and drops the rest; the
70
+ whole library is about 1.3 MB minified. Import `dist/zx.esm.js` (what `@zeyos/zx` resolves to),
71
+ not `dist/zx.esm.min.js`: a bundler given the minified file keeps most of it (about 0.9 MB for
72
+ one `button()`). The core modules
73
+ are importable the same way — `setTranslator` from `@zeyos/zx/src/core/i18n.js`, `registerIcons`
74
+ and `icon` from `@zeyos/zx/src/core/icons.js` — and they are the module instances the
75
+ per-component files import, so a translator or a glyph registered there reaches every component
76
+ imported granularly. `zx-css` does the same for the stylesheet.
60
77
  - Global: `<script src="/assets/zx.global.js">` → `window.zx.*`.
61
78
  - Styles: load `/assets/zx.css` once, or one of the stylesheets below.
62
79
  - Build bundles with `npm run build` (esbuild). No build is needed to develop against `src/`.
@@ -91,8 +108,9 @@ source of any module it imports, because a component may draw another's markup w
91
108
  A name is the file name of a stylesheet under `src/components/`: `select`, `progress-bar`,
92
109
  `button` for `button()`, `layout` for `stack()` and `grid()`. An unknown name fails and lists the
93
110
  known ones. Name what the page draws by hand as well: a `Form` that uses `type: 'zxselect'` needs
94
- `form select`, because a field type is registered at run time, not imported. The print rules are not
95
- part of a subset: a page that prints loads `@zeyos/zx/styles/print.css` after it.
111
+ `form select`, because a field type is registered at run time, not imported — "Field widget types"
112
+ lists the name for every type. The print rules are not part of a subset: a page that prints loads
113
+ `@zeyos/zx/styles/print.css` after it.
96
114
 
97
115
  **The layered build** puts the whole library in `@layer zx`, and an unlayered rule beats any layered
98
116
  one whatever its specificity, so `button { padding: 0 }` overrides `.zx-btn[data-size="sm"]` with no
@@ -172,6 +190,7 @@ Patterns — single screens that recur in every application:
172
190
  | `inbox` | Inbox | three panes: folders, conversations, the open thread with a reply |
173
191
  | `record-page` | Record page | one record: summary header, tabs for lines, files and history, editable details |
174
192
  | `agent-chat` | Agent chat | one agent run: plan, tool calls, an approval that holds it, a streamed answer with sources |
193
+ | `agent-canvas` | Agent canvas | every answer a `surface/1` document — figures and a chart, a review, forms, a questionnaire — with its JSON, versions and reply in a panel |
175
194
  | `record-wizard` | Record wizard | creation in validated vertical steps with a running total and a review |
176
195
  | `checkout-wizard` | Checkout wizard | a focused horizontal flow beside a live summary |
177
196
  | `settings-workspace` | Settings workspace | personal settings in sections, saved together |
@@ -201,7 +220,7 @@ a second navigation.
201
220
  | A tree | `TreeView` (one column) or `Finder` (Miller columns) | nested `<ul>`s |
202
221
  | Events over time | `Calendar` (agenda, day, week, month, year) | — |
203
222
  | One number with context | `StatTile` (delta, sparkline, loading; plain and one leading for a record's figures) | a card with a big figure |
204
- | A chart | `Chart` with `ChartJsAdapter` (Chart.js injected, never bundled) | — |
223
+ | A chart | `Chart` with `SvgChartAdapter` (bar, line, pie, doughnut; no dependency), or `ChartJsAdapter` for other types (Chart.js injected, never bundled) | a hand-drawn SVG |
205
224
  | A linked record inline | `EntityRef` | a link |
206
225
  | Files | `FileItem` / `FileList`; uploading: `FieldUpload` | — |
207
226
  | History, comments, a feed | `ActivityItem` / `ActivityList` | — |
@@ -675,6 +694,191 @@ new ModuleBar(header, buildZeyosModuleBarConfig(state, { orientation: 'horizonta
675
694
  the bar directly.
676
695
  <!-- /doc -->
677
696
 
697
+ ## Using Zx from a framework
698
+
699
+ The class API is imperative: `new Component(target, options)` builds DOM, methods change it, and
700
+ `destroy()` takes it away. A framework component wraps that in its mount and unmount hooks. The
701
+ `<zx-*>` elements (next section) are the alternative where a framework should render a tag and
702
+ set properties instead.
703
+
704
+ **Mount and unmount.** Create the component when the host element exists and destroy it when the
705
+ host goes away. Nothing else is needed for cleanup: `destroy()` aborts every listener, removes a
706
+ root the component created, and restores a target it enhanced.
707
+
708
+ ```jsx
709
+ // React
710
+ import { useEffect, useRef } from 'react';
711
+ import { Toggle } from '@zeyos/zx';
712
+
713
+ export function ZxToggle({ checked, label, onChange }) {
714
+ const host = useRef(null);
715
+ const toggle = useRef(null);
716
+ const handler = useRef(onChange);
717
+ handler.current = onChange;
718
+
719
+ useEffect(() => {
720
+ const instance = new Toggle(null, { checked, label });
721
+ instance.on('change', (event) => handler.current?.(event.detail.checked));
722
+ host.current.append(instance.toElement());
723
+ toggle.current = instance;
724
+ return () => { instance.destroy(); toggle.current = null; };
725
+ }, []);
726
+
727
+ // Props that arrive later go through setters.
728
+ // `silent` keeps the write from coming back as a `change` event.
729
+ useEffect(() => {
730
+ toggle.current?.set(Boolean(checked), { silent: true });
731
+ }, [checked]);
732
+ useEffect(() => {
733
+ toggle.current?.setLabel(label ?? null);
734
+ }, [label]);
735
+
736
+ return <span ref={host} />;
737
+ }
738
+ ```
739
+
740
+ ```vue
741
+ <!-- Vue -->
742
+ <script setup>
743
+ import { onBeforeUnmount, onMounted, ref, watch } from 'vue';
744
+ import { Toggle } from '@zeyos/zx';
745
+
746
+ const props = defineProps({ modelValue: Boolean, label: String });
747
+ const emit = defineEmits(['update:modelValue']);
748
+ const host = ref(null);
749
+ let toggle = null;
750
+
751
+ onMounted(() => {
752
+ toggle = new Toggle(null, { checked: props.modelValue, label: props.label });
753
+ toggle.on('change', (event) => emit('update:modelValue', event.detail.checked));
754
+ host.value.append(toggle.toElement());
755
+ });
756
+ watch(() => props.modelValue, (value) => toggle?.set(Boolean(value), { silent: true }));
757
+ watch(() => props.label, (value) => toggle?.setLabel(value ?? null));
758
+ onBeforeUnmount(() => { toggle?.destroy(); toggle = null; });
759
+ </script>
760
+
761
+ <template><span ref="host" /></template>
762
+ ```
763
+
764
+ - **Target `null`, then append.** The component owns its root and `destroy()` removes it, so the
765
+ framework's own element is left exactly as it rendered it. Passing the framework's element as the
766
+ target enhances it in place — Zx then writes classes, attributes and children the framework did
767
+ not render, and puts them back on `destroy()`. A Groupbox given anything but a `<details>`
768
+ replaces that element in the document with one until it is destroyed, so give it `null`.
769
+ - **Unset props.** `{ label: props.label }` with the prop unset passes `undefined`, which keeps
770
+ the default. Pass `null` to mean "none".
771
+ - **Events.** Subscribe with `on()` or an `on<type>` option; both end with `destroy()`. Read the
772
+ current callback from a ref, as above, instead of re-creating the component when a callback's
773
+ identity changes.
774
+
775
+ **The effect runs twice in development.** React's StrictMode mounts, unmounts, and mounts again;
776
+ a component created in the first mount and not destroyed in its cleanup is a second set of DOM and
777
+ listeners beside the first. Returning `destroy()` from the effect is the whole fix, and it is safe
778
+ to call more than once. Where a component enhances an existing element and the code cannot be sure
779
+ the previous one is gone, `Component.from(element)` returns the component registered on a root
780
+ element, or null: `Component.from(element)?.destroy()` before constructing. Floating toasts
781
+ outlive the code that showed them; a view that unmounts its themed shell while toasts are on
782
+ screen calls `Message.disposeRegion(shell)` in the same cleanup.
783
+
784
+ **Framework content inside a component.** Options such as a Dialog's, Sheet's, Modal's, Panel's or
785
+ Card's `content`, and a Panel's or Card's `footer`, take a DOM node. Create an element, hand it to
786
+ the component, and let the framework render into it through a portal, so the content stays part
787
+ of the framework's tree (context, events, updates) while Zx decides where it sits:
788
+
789
+ ```jsx
790
+ // React
791
+ import { useEffect, useRef, useState } from 'react';
792
+ import { createPortal } from 'react-dom';
793
+ import { Dialog } from '@zeyos/zx';
794
+
795
+ export function ZxDialog({ open, title, onClose, children }) {
796
+ const [body] = useState(() => document.createElement('div'));
797
+ const [dialog, setDialog] = useState(null);
798
+ const closed = useRef(onClose);
799
+ closed.current = onClose;
800
+
801
+ useEffect(() => {
802
+ const instance = new Dialog(null, { title, content: body });
803
+ instance.on('close', () => closed.current?.());
804
+ setDialog(instance);
805
+ return () => instance.destroy();
806
+ }, []);
807
+
808
+ useEffect(() => { dialog?.setTitle(title ?? ''); }, [dialog, title]);
809
+ useEffect(() => {
810
+ if (!dialog || dialog.isOpen() === Boolean(open)) return;
811
+ if (open) dialog.open(); else dialog.close();
812
+ }, [dialog, open]);
813
+
814
+ return createPortal(children, body);
815
+ }
816
+ ```
817
+
818
+ In Vue the same element is the target of `<Teleport :to="body">`. Do not let the framework render
819
+ into an element the component fills itself (a table body, a select's list): the next render of
820
+ either side removes the other's nodes. Cell and item renderers (`render`, `renderCard`, …) return
821
+ nodes; build those with the framework only if it can render into a detached element you create.
822
+
823
+ **Controlled wrappers.** A wrapper that owns the value writes it down with a setter and hears it
824
+ back through an event, and the two must not chase each other:
825
+
826
+ - Write with `{ silent: true }` where the setter takes it — `set(value, { silent })` on Toggle,
827
+ CheckButton, Select and the other value controls, `Table#setSort(id, dir, { silent })`,
828
+ `Table#setExpanded(ids, { silent })` — so the write raises no event. Check the method's
829
+ signature: not every setter emits, and not every one that does takes `silent`.
830
+ - Compare before writing an open state: `if (dialog.isOpen() !== open)`. `open()` and `close()`
831
+ emit, and `close` after a programmatic `close()` would otherwise be reported back as the user's.
832
+ - Which options have a setter is stated per option: the documentation's Options tables carry a
833
+ **Change** column, generated into `docs/api.json` as `update: { methods: ['setTitle()'] }` or
834
+ `update: { rebuild: true }`. `rebuild` means the option is read at construction — destroy the
835
+ component and create it again with the new options (in React, a `key` made of those options does
836
+ it). An option with neither is not stated: look for a method under another name before
837
+ rebuilding.
838
+
839
+ **Groupbox reports `open` and `close` later.** Groupbox is a native `<details>`; its events come
840
+ from the element's `toggle` event, which the browser dispatches in a later task, after the click
841
+ that changed the state. Between the two, `isOpen()` already reports the new state and the wrapper's
842
+ `open` prop still holds the old one. A wrapper that writes its prop back on every render —
843
+ `open ? box.open() : box.close()` — therefore reverts the reader's click whenever anything
844
+ re-renders in that gap, and then receives no event at all, because the state is back where it was.
845
+ Write `open` only when the prop itself changes, and take the state from the event:
846
+
847
+ ```jsx
848
+ useEffect(() => { // runs when the prop changes, not on every render
849
+ if (box.current && box.current.isOpen() !== open) {
850
+ if (open) box.current.open(); else box.current.close();
851
+ }
852
+ }, [open]);
853
+ // constructed with: onopen: () => setOpen(true), onclose: () => setOpen(false)
854
+ ```
855
+
856
+ A programmatic `open()` or `close()` is reported the same way, one task later, and has no
857
+ `silent` form; setting the state to what it already is reports nothing.
858
+
859
+ **Chart creates its engine when it can be measured.** `new Chart(...)` followed by
860
+ `chart.getInstance()` in the same effect returns the engine only if the chart is already in the
861
+ document and laid out; a chart appended later creates it then. Listen for `ready` (the `onready`
862
+ option) to reach the engine, or call `getInstance()` after appending, which creates it on the
863
+ spot. `setLoading(true)` and `setError()` destroy the engine and a later `setData()`,
864
+ `setLoading(false)` or `clearError()` creates a new one and fires `ready` again, so never keep the
865
+ instance across them. Theme changes reach the engine without a call.
866
+
867
+ **Testing under jsdom.** The components construct, open, close and destroy in a DOM without
868
+ layout or top layer:
869
+
870
+ - Modal, Dialog, Sheet and Launcher fall back to the `open` attribute where `showModal()` or
871
+ `showPopover()` is missing. `open()`, `close(result)`, `isOpen()`, Escape, `cancel`, the `open`
872
+ and `close` events and `destroy()` behave as in a browser. There is no top layer, no inert
873
+ page, no backdrop, and no `aria-modal` in the fallback, so a test cannot assert focus
874
+ containment or that the rest of the page is unreachable — use a browser for those. `close` is
875
+ reported asynchronously, as in a browser: `await` a tick before asserting on it.
876
+ - `Table` with `virtual: true` works without `ResizeObserver`: it draws for an assumed row height
877
+ (36px) and viewport. Stepper keeps every connector, and Chart creates its engine as soon as it
878
+ has data, since nothing will ever report a size.
879
+ - Everything measured is zero, so assertions on geometry (pinned-column offsets, a wrapped
880
+ stepper, an overflow menu) belong in a browser test.
881
+
678
882
  ## Custom elements
679
883
 
680
884
  `defineElements()` (not auto-called) registers light-DOM `<zx-*>` wrappers with attribute↔option
@@ -768,7 +972,9 @@ accept.
768
972
  `--zx-color-accent-solid*` roles, so in dark it keeps the deep stop with white ink rather than a
769
973
  bright slab. A `ghost` button's icon is drawn in `--zx-color-text-subtle` until hovered. A button
770
974
  with `aria-pressed="true"` (a Toolbar item with `active`, a view toggle) is a mode, not a pick:
771
- it takes the neutral `--zx-color-bg-current` fill and the text colour, never the accent.
975
+ it stays neutral, never the accent, and is drawn with a stronger fill plus a frame in
976
+ `--zx-color-text-subtle` (3:1 against its neighbours in both themes), so a pressed segment of a
977
+ `buttonGroup` is told apart without relying on the fill alone.
772
978
  <!-- /doc -->
773
979
 
774
980
  <!-- doc:badge -->
@@ -827,8 +1033,8 @@ a `MenuButton`, where choosing one activates the original control.
827
1033
  in visual order under `dir="rtl"`; Home/End jump to the first and last control. A text field, select,
828
1034
  or contenteditable item keeps its own keys: Home/End and the arrows move its caret, and an arrow
829
1035
  moves on to the neighbouring control only once the caret is at that edge of the text.
830
- - **Pressed items** — an item with `active` renders `aria-pressed="true"` and takes the neutral
831
- `--zx-color-bg-current` fill, never the accent.
1036
+ - **Pressed items** — an item with `active` renders `aria-pressed="true"` and takes Button's
1037
+ neutral pressed fill and frame, never the accent.
832
1038
  <!-- /doc -->
833
1039
 
834
1040
  <!-- doc:empty-state -->
@@ -839,7 +1045,9 @@ yet: an optional decorative icon, a headline, a sentence, and optional actions.
839
1045
  paragraph rather than a heading, so dropping one into a Table's empty slot or a Panel body never
840
1046
  disturbs the page's heading outline.
841
1047
 
842
- - **Options** — `icon` (an icon name, `null` for none; default `'folder-open'`), `title`,
1048
+ - **Options** — `icon` (an icon name, `null` for none; default `'folder-open'`), `agent`
1049
+ (`{seed?, name?, tone?, body?, eyes?, material?}` or `true`: an agent's AgentAvatar face, at rest,
1050
+ in place of the icon — an empty conversation, an agent with nothing to do yet), `title`,
843
1051
  `description`, `actions: [Element | buttonOptions]`, `size: 'md'|'sm'`, `align: 'center'|'start'`.
844
1052
  - **Methods** — none. `emptyState(options)` → `HTMLDivElement`, which you own and place yourself.
845
1053
  - **Events** — none; action buttons carry their own `onclick`.
@@ -938,11 +1146,17 @@ a stronger border, the text colour); only the check glyph, the mark, keeps the a
938
1146
 
939
1147
  Switch (`role="switch"`, `aria-checked`).
940
1148
 
941
- - **Options** — `checked: false`, `value: true`, `label: null`, `disabled: false`.
1149
+ - **Options** — `checked: false`, `value: true`, `label: null`, `hideLabel: false`,
1150
+ `disabled: false`.
942
1151
  - **Label** — start-aligned and wrapping like text within the available width, the track level
943
- with its first line.
1152
+ with its first line. It is the switch's accessible name. `hideLabel: true` keeps it for assistive
1153
+ technology only: no visible text, and the label becomes the switch's `aria-label` — for a switch
1154
+ whose meaning the layout already shows, such as a table cell under a column header. With no
1155
+ label at all, name the switch from outside: a Field or `<label for>` around it, or
1156
+ `aria-labelledby` on the element.
944
1157
  - **Methods** — `get()`, `set(checked, {silent})`, `toggle()`, `getValue()` (returns
945
- `options.value` when on, `false` when off), `enable()`/`disable()`.
1158
+ `options.value` when on, `false` when off), `setLabel(label)` (null removes it),
1159
+ `enable()`/`disable()`.
946
1160
  - **Events** — `change {checked, value}`.
947
1161
  - **Keyboard** — Space/Enter.
948
1162
  <!-- /doc -->
@@ -975,8 +1189,10 @@ permissions, recent-history/cache policy, and the route or command ultimately in
975
1189
  `false`), and `scope` to explicitly select an element whose nearest Zx theme scope owns the launcher.
976
1190
  - **Items** — `{id, label, description?, keywords?, group?, icon?, badge?, hint?, shortcut?, keys?,
977
1191
  value?, href?, target?, invoke?, pinned?, disabled?, kind?, current?, when?, groupOrder?,
978
- itemOrder?, items?, placeholder?, order?}`. `icon` accepts a bundled icon name, Node, or
979
- factory. Links stay native so modified and middle clicks work;
1192
+ itemOrder?, items?, placeholder?, order?, agent?}`. `icon` accepts a bundled icon name, Node, or
1193
+ factory. `agent` (AgentAvatar options, or `true`) draws the item as the agent's still face
1194
+ instead — a tile's size for an `application` — with its activity's word, visually hidden, after
1195
+ the label in the option's name. Links stay native so modified and middle clicks work;
980
1196
  non-link commands may provide an application-owned `invoke` callback. Malformed and executable
981
1197
  URL schemes are stripped; a descriptor with no safe link or callback is disabled. `hint` is muted
982
1198
  text at the end of the row (a current value, a project); `shortcut: ['⌘', 'K']` (or Button's
@@ -1091,6 +1307,64 @@ and the component is decorative by default so adjacent identity text is not anno
1091
1307
  status, not the account's accessible name; supply `statusLabel` when it conveys information.
1092
1308
  <!-- /doc -->
1093
1309
 
1310
+ <!-- doc:agent-avatar -->
1311
+ ### AgentAvatar
1312
+
1313
+ A generated face for an agent that has no picture: a coloured geometric silhouette with eyes that
1314
+ take the agent's activity. Everything about it is derived from a
1315
+ seed, so the same agent has the same face on every screen; it is decorative by default, like
1316
+ Avatar.
1317
+
1318
+ - **Options** — `seed` (the agent's stable id; `null` uses `name`, but a rename then changes the
1319
+ face), `name`, `tone` (the Avatar tones, or `null` to derive it), `body` and `eyes` (fix one
1320
+ trait instead of deriving it), `spacing: 0|1|2` (the eye spacing), `material: 'flat'|'soft'`, `size: 'sm'|'md'|'lg'|<pixels>` (24 / 32 / 40px at the default
1321
+ spacing unit), `label`, `activity: 'idle'|'thinking'|'working'|'needs-you'|'blocked'|'offline'|null`,
1322
+ `activityLabel`, `indicator: true`, `animate: false`, and `phase: null|number`.
1323
+ - **Silhouettes** — fourteen, filled with the tone's `-solid`: circle, squircle, hexagon,
1324
+ triangle, drop, tilted pill, clover, dome, wedge, pentagon, trapezoid, cross, diamond and
1325
+ octagon; polygons round their corners. Eyes are `round`, `oval` or `square`, white with dark
1326
+ pupils, in `--zx-color-agent-eye` and `--zx-color-agent-pupil`, which keep their
1327
+ colour in both themes.
1328
+ - **Material** — `material: 'soft'` paints the body with a quiet vertical ramp: 10% toward the eye
1329
+ white at the top, the plain tone from 30% to 50% — across the eyes, which keep their flat-fill
1330
+ contrast — and 14% toward the pupil ink at the foot. It is an application-wide choice, not a
1331
+ trait. A soft avatar is drawn flat below 28px, when offline, in print and in forced colours; the
1332
+ root carries `data-material`.
1333
+ - **Traits** — `agentTraits(seed, overrides?)` returns `{tone, body, eyes, spacing}`. The tone is
1334
+ `avatarTone(seed)`, so the face matches an initials Avatar keyed the same way; each other trait
1335
+ hashes the same normalised key with its own salt. The tables `AGENT_BODIES` and `AGENT_EYES` are
1336
+ contract, order and length included. `agentFace(traits, activity, px)` returns the
1337
+ drawing as plain data (`{tag, part, attrs, children?}` in a 64-unit view box), for tests or a
1338
+ server.
1339
+ - **Sizes** — small sizes draw less: no pupils below 20px, and larger eyes at 24px and below.
1340
+ - **Activity** — the eyes take a static expression: open (idle), looking up and aside (thinking),
1341
+ lowered (working), wide (needs you), flat bars (blocked), closed on a faded, colourless face
1342
+ (offline). No mouths and nothing angry or sad. The Avatar activity dot (`indicator`) and the
1343
+ activity word in the accessible name stay the primary signal; the root carries `data-activity`.
1344
+ The dot is notched out of the face with a mask rather than ringed in a surface colour, so it reads
1345
+ on any background, glass navigation included.
1346
+ `animate: true` moves the root in the shared presence loop exactly as Avatar does and lets the eyes
1347
+ blink, drift and scan — never without the motion preference, and not inside a
1348
+ `data-zx-motion="reduced"` region. `phase` offsets both.
1349
+ - **Methods** — `set(values)` (any option above), `setActivity(activity, label?)`,
1350
+ `getActivity()`, `getActivityWord()` (the localized word, for a host that names its own
1351
+ control), `getTraits()`, `destroy()`. No events: wrap it in a button or link to make it
1352
+ interactive.
1353
+ - **In navigation** — `AppSidebar` and `ModuleBar` items take `agent` (these options, or `true`)
1354
+ and draw the AgentAvatar in place of their icon or tile, with the activity in the control's
1355
+ name; Composer mention items and Launcher items take `agent` too; AgentThread and RunTrace authors and ActivityItem
1356
+ avatar descriptors take `face`. Only a
1357
+ face's trait strings are read, so agent-supplied data cannot animate or name it.
1358
+ - **Elsewhere** — `emptyState()`, ApprovalCard and RunStatus take `agent` (traits and `name`, or
1359
+ `true`) in place of their icon: still and decorative, ApprovalCard's face looking up at you while
1360
+ the request waits, RunStatus's with the run's expression. KanbanView assignee descriptors take
1361
+ `face`, so an agent on a card's team is drawn as its face. The thread adapters
1362
+ (`connectAgUi()`, `connectUiMessageStream()`) draw the faces the thread's own `authors` give.
1363
+ Message `leading` and Card `media` accept an AgentAvatar like any other component.
1364
+ - **Accessibility** — the SVG is always hidden. With `label` the root is `role="img"`, named
1365
+ "label, activity word"; without one it is `aria-hidden`, for use beside the agent's name.
1366
+ <!-- /doc -->
1367
+
1094
1368
  <!-- doc:entity-ref -->
1095
1369
  ### EntityRef
1096
1370
 
@@ -1171,7 +1445,9 @@ One chronological activity entry. It owns actor/avatar anatomy, semantic time, s
1171
1445
  attachments, and actions; the application owns posting, reactions, permissions, routing,
1172
1446
  persistence, and sanitization before any rich content becomes a Node.
1173
1447
 
1174
- - **Options** — `id`, `actor`, `avatar` (Avatar options or Element), `title`, `content`,
1448
+ - **Options** — `id`, `actor`, `avatar` (Avatar options or Element; with `face` — `{seed, tone,
1449
+ body, eyes, material}` or `true` — an agent's `AgentAvatar`, taking `name`, `label`, `size`,
1450
+ `tone`, `activity`, `activityLabel`, `animate` and `phase`), `title`, `content`,
1175
1451
  `timestamp`, `timeLabel`, `metadata`, `attachments`, `actions`, `kind`, and
1176
1452
  `headingLevel: 1..6`. Content slots accept text, Nodes, or Components and never parse HTML.
1177
1453
  - **Actions** — Elements pass through; descriptors accept
@@ -1430,12 +1706,15 @@ from `Select`, with its themed popover and keyboard behavior.
1430
1706
  Searchable multi-check list with optional async loading.
1431
1707
 
1432
1708
  - **Options** — `items`, `valueKey: 'ID'`, `labelKey: 'name'`, `checkedKey: 'on'`, `search: true`,
1433
- `height: 280`, `defaultChecked: false`, `hideLabel: false` (leaves out the heading; the group
1434
- keeps its text as `aria-label`), `load: async ()=>items`.
1709
+ `height: 280`, `defaultChecked: false`, `label: null` (heading text and the group's accessible
1710
+ name; null uses the `checklist.label` message), `disabled: false`, `hideLabel: false` (leaves out
1711
+ the heading; the group keeps its text as `aria-label`), `load: async ()=>items`.
1435
1712
  - **In a Field** — field type `checklist` draws no heading of its own: the field's label names the
1436
1713
  group (`aria-labelledby`).
1437
1714
  - **Methods** — `setItems()`, `getValues()`, `setValues(ids)`, `checkAll()`/`uncheckAll()`,
1438
- `search(query)`, `reload()`.
1715
+ `search(query)`, `reload()`, `setLabel(text)`, `enable()`/`disable()`, `isDisabled()`. Disabled,
1716
+ the search field and every checkbox are disabled (`aria-disabled="true"` on the group) through
1717
+ searches, `setItems()` and reloads; values can still be set from code.
1439
1718
  - **Events** — `change {values}`, `loaded`.
1440
1719
  <!-- /doc -->
1441
1720
 
@@ -1447,7 +1726,8 @@ buttons are `tabindex="-1"`/`aria-hidden` pointer affordances — the input itse
1447
1726
  Field type: `number`.
1448
1727
 
1449
1728
  - **Options** — `value` (number|null), `min`, `max`, `step: 1`, `largeStep: 10` (PageUp/PageDown
1450
- multiplier), `precision` (decimals; derived from `step` when null), `wrap: false` (stepping past
1729
+ multiplier), `precision` (decimals; derived from `step` when null), `snap: true` (see
1730
+ **Snapping**), `wrap: false` (stepping past
1451
1731
  a bound jumps to the other one), `placeholder`, `unit` (suffix rendered inside the control),
1452
1732
  `group: false` (thousands separators while idle), `locale`, `disabled`, `readonly`, `required`,
1453
1733
  `name`.
@@ -1455,6 +1735,11 @@ Field type: `number`.
1455
1735
  the range; `''`/null clear it), `stepUp(n)`, `stepDown(n)`, `setRange(min, max)`,
1456
1736
  `setReadonly()`, `reset()`, `focus()`, `getInput()`, `enable()`/`disable()`.
1457
1737
  - **Events** — `change {value}` (committed), `input {value}` (per keystroke, possibly unsnapped).
1738
+ - **Snapping** — by default a typed or assigned value is moved onto the `step` grid (step 2 turns
1739
+ 123 into 124) and rounded to the step's decimals. That suits quantities; it is wrong for a value
1740
+ that is not a multiple of anything — an identifier, a seed, a measurement. `snap: false` keeps
1741
+ the value exactly as entered: `step` is then only what the buttons and arrow keys add, decimals
1742
+ are rounded only to an explicit `precision`, and `min`/`max` still clamp.
1458
1743
  - **Keyboard** — ↑/↓ one step, PageUp/PageDown `largeStep` steps, Home/End jump to `min`/`max` when
1459
1744
  set (otherwise they keep their caret meaning), Enter commits, wheel steps while focused.
1460
1745
  - **Also exported** — `parseNumber(raw)` (accepts `.` and `,` as the decimal separator, ignores
@@ -1521,12 +1806,14 @@ to a hidden textarea when the async Clipboard API is unavailable or denied.
1521
1806
 
1522
1807
  #### copyButton()
1523
1808
 
1524
- - **Signature** — `copyButton({text, label, title, feedback, feedbackDuration, size, kind, oncopy})`
1809
+ - **Signature** — `copyButton({text, label, title, feedback, feedbackDuration, size, kind, oncopy, signal})`
1525
1810
  → `HTMLButtonElement`.
1526
1811
  - **Options** — `text: ''` — a string, or **a function returning one**, which is what a button
1527
1812
  beside a live value needs so the copy is never stale; `label: ''` (empty renders an icon-only
1528
1813
  ghost button), `title`, `feedback` (by default the `copy.copy` and `copy.copied` messages, and `null` gives no text), `feedbackDuration: 2000`,
1529
- `size: 'md'|'sm'`, `kind: 'default'|'primary'|'ghost'`.
1814
+ `size: 'md'|'sm'`, `kind: 'default'|'primary'|'ghost'`, `signal` (an `AbortSignal`: aborting
1815
+ removes the button's listener and timer, and a copy still waiting on the clipboard then reports
1816
+ nothing — what a component owning the button passes from its own lifecycle).
1530
1817
  - **Events** — `oncopy(text, copied)` is called for every attempt; `copied` is `false` when the
1531
1818
  clipboard refused the write, and the button then stays untouched rather than claiming a copy
1532
1819
  that did not happen.
@@ -1646,24 +1933,63 @@ use `TimePicker` or `DateTimeBox`.
1646
1933
 
1647
1934
  Floating toasts come from statics; `new Message(target)` gives an inline, non-floating area with
1648
1935
  the same `.show()`. The toast region is `role="status"`/`aria-live` (`role="alert"` for errors).
1649
- The shared floating region is fixed to the upper-right logical corner by default, sizes to its
1650
- messages rather than the page, and uses the translucent glass surface tokens with a solid fallback.
1936
+ A floating region sits at the top of the viewport on the inline-end side by default (`top-end`:
1937
+ the upper right in a left-to-right page), sizes to its messages rather than the page, and uses the
1938
+ translucent glass surface tokens with a solid fallback. A message is a plain card with a neutral
1939
+ border; its kind shows in the icon. Floating messages pile into a stack that opens on hover, focus,
1940
+ or a press (see **Stack**).
1651
1941
 
1652
1942
  - **Statics** — `Message.info/success/warning/error(msg, opts)`,
1653
- `Message.show(msg, { kind, timeout=4000, closable, scope? })` → `{ close() }`,
1654
- `Message.progress(text, {scope?})` → `{ update(pct, text?), done(), fail(text?) }`. `scope` is
1655
- an element or selector whose nearest Zx theme scope owns that floating region; without it the
1656
- focused opener supplies the scope.
1943
+ `Message.show(msg, { kind, timeout=4000, closable, highlight?, scope?, placement? })` → `{ close() }`,
1944
+ `Message.progress(text, {scope?, placement?, highlight?})` → `{ update(pct, text?), done(), fail(text?) }`,
1945
+ `Message.setPlacement(placement)` / `Message.getPlacement()`,
1946
+ `Message.setStack(enabled)` / `Message.getStack()`. `scope` is an element or selector
1947
+ whose nearest Zx theme scope owns that floating region; without it the focused opener supplies
1948
+ the scope.
1949
+ - **Placement** — `placement: 'top-start'|'top'|'top-end'|'bottom-start'|'bottom'|'bottom-end'`
1950
+ per call, default `'top-end'`: the block edge, then the inline position, logical, so `start` and
1951
+ `end` follow the writing direction and `top`/`bottom` alone are centred.
1952
+ `Message.setPlacement(placement)` sets the default for calls that name none and returns the
1953
+ placement now in effect (anything unknown restores `'top-end'`); it applies to messages shown
1954
+ from then on. Messages of one placement share a region, so a scope has one region per placement
1955
+ in use, each carrying `data-placement`. At the foot the newest toast is nearest the edge. The
1956
+ distance from the viewport edge is the `--zx-message-offset` custom property (default
1957
+ `var(--zx-space-4)`), read from the region's theme scope: set it there or on `:root` to clear a
1958
+ header or a status bar. At 640px and narrower every placement spans the foot of the viewport,
1959
+ full width. An inline area ignores `placement`.
1657
1960
  - **Region lifecycle** — a floating region is created on the first toast for its scope and removed
1658
1961
  when its last toast closes. One whose host was emptied or left the document is replaced on the
1659
1962
  next toast rather than reused, and a scope that is itself detached falls back to the focused
1660
- element's scope. `Message.disposeRegion(scope)` → boolean removes a scope's region at once,
1661
- toasts and all, for a host torn down while toasts are still showing. While a modal Dialog or
1963
+ element's scope. `Message.disposeRegion(scope)` → boolean removes a scope's regions at once — all
1964
+ placements, toasts and all — for a host torn down while toasts are still showing. While a modal Dialog or
1662
1965
  Sheet is open the region moves into the topmost one, so toasts and their actions stay visible
1663
1966
  and clickable above it, and moves back when it closes. A press on a toast dismisses no open menu
1664
1967
  or drawer.
1665
1968
  - **Per-message options** — `kind: 'info'`, `timeout`, `closable: true`, `maxVisible: 5` (extras
1666
- queue, and hovering pauses dismissal).
1969
+ queue, and hovering pauses dismissal), `highlight: false`.
1970
+ - **Highlight** — `highlight: 'border'` (or `true`) draws the message's border in the kind colour;
1971
+ `highlight: 'animated'` draws it faintly with a light travelling round it, and is the still
1972
+ kind-coloured border under `prefers-reduced-motion: reduce`. Per message, or as an inline area's
1973
+ default; the message carries it as `data-highlight`. `false` (the default) is the plain card.
1974
+ - **Stack** — floating regions stack by default, and `stack: true` makes an inline area stack:
1975
+ the visible messages pile into one stack, the newest in front, the next two peeking out behind
1976
+ it a step smaller, the rest out of sight. `Message.setStack(false)` lists floating messages one
1977
+ below another instead (at once, those on screen included; `getStack()` reads it). It
1978
+ opens — every visible message laid out with its own height — while the pointer is over it or
1979
+ focus is inside it; a press on it that is not on a button (a tap included) keeps it open until a
1980
+ press outside it, Escape (which returns focus to where it came from), or `collapse()`. While it
1981
+ is open by any of these no message in it times out. The outside press is handled after its own
1982
+ click handlers, so a button elsewhere can toggle the stack with
1983
+ `isExpanded() ? collapse() : expand()`. Closing a message from the keyboard moves focus to the
1984
+ same control of the next message, and from the last one back to where it was before it came
1985
+ into the stack. An open floating stack taller than the viewport becomes a scrolling list
1986
+ (`data-overflow`) with the newest message in view. `expanded: true` keeps it open without
1987
+ holding the timers. Instance methods: `expand()` (opens and keeps it open), `collapse()`,
1988
+ `isExpanded()`, `setStack(enabled)`; events `expand` and `collapse`. The root carries
1989
+ `data-stack` and `data-state="collapsed"|"expanded"`; document order follows the visual order,
1990
+ so Tab meets the messages as they are seen. A stack at the top (inline areas, `top*`) piles
1991
+ downwards, one at the foot (`bottom*`, and every region at 640px and narrower) upwards. The
1992
+ geometry is the exported pure helper `messageStackLayout(heights, expanded)`.
1667
1993
  - **Action** — `action: { label, onclick?, kind? }` renders one small button (`.zx-btn`,
1668
1994
  `data-size="sm"`, secondary unless `kind` is `primary`/`danger`/`ghost`) in a toast or an inline
1669
1995
  message; activating it runs `onclick(event)` and closes the message. A message with an action
@@ -1688,7 +2014,19 @@ panel material; the backdrop uses `--zx-color-overlay-backdrop`, and focus retur
1688
2014
  scope is resolved again on every `open()`; a `scope` element not yet in the document leaves the
1689
2015
  dialog detached until then, rather than parking it on `<body>` outside the theme.
1690
2016
  - **Methods** — `open()`, `close(result?)`, `setContent()`, `isOpen()`.
1691
- - **Events** — `open`, `close {result}`, `cancel` (Esc; preventable with `event.preventDefault()`).
2017
+ - **Events** — `open`, `close {result}`, `cancel {reason}`.
2018
+ - **Dismissal** — everything the reader does to dismiss an overlay raises `cancel` first, with
2019
+ `reason` `'escape'`, `'close-button'` (Dialog/Sheet header ✕), `'button'` (a footer button whose
2020
+ action is `'cancel'`), `'backdrop'` (`lightDismiss`), `'outside'` or `'drag'` (Sheet).
2021
+ `event.preventDefault()` keeps it open, which is the place for an "unsaved changes" check.
2022
+ A programmatic `close()` raises no `cancel`. Escape is handled by Zx rather than by the browser's
2023
+ close request, so preventing it holds however often the key is pressed; a handler that calls
2024
+ `preventDefault()` on the Escape keydown (a popup inside the dialog, your own) keeps the key.
2025
+ - **Without `showModal()`** — in a DOM that has `<dialog>` but not `showModal()` (jsdom, for unit
2026
+ tests), Modal, Dialog and Sheet present themselves through the `open` attribute instead.
2027
+ `open()`, `close(result)`, `isOpen()`, Escape, `cancel`, the events and `destroy()` work the
2028
+ same; there is no top layer, no inert page, no backdrop and no `aria-modal`, so modality itself
2029
+ is not testable there.
1692
2030
  <!-- /doc -->
1693
2031
 
1694
2032
  <!-- doc:dialog -->
@@ -1698,6 +2036,8 @@ Structured modal: a header with title and close button, a body, and footer butto
1698
2036
 
1699
2037
  - **Options** — `title`, `size: 'sm'|'md'|'lg'|number`,
1700
2038
  `buttons: [{ label, kind, action: 'close'|'cancel'|fn(dialog), autofocus, shortcut }]`, `closable: true`.
2039
+ `closable: false` refuses Escape and takes the header ✕ away entirely: it is not displayed, not
2040
+ focusable, and closes nothing. Close such a dialog from a footer button or with `close()`.
1701
2041
  - **Methods** — `setTitle()`, `setContent()`, `setButtons()`,
1702
2042
  `addView(key, { content, buttons? })`, `showView(key)`.
1703
2043
  - **Statics returning Promises** — `Dialog.alert({ title, message, okLabel })`,
@@ -1724,13 +2064,15 @@ When a Dock adopts it, the Sheet becomes an opaque layout surface instead.
1724
2064
 
1725
2065
  - **Options** — `side: 'end'` (`'start' | 'end' | 'top' | 'bottom'`, logical), `modal: true`
1726
2066
  (`true | 'trap-focus' | false`), `backdrop: 'dim'` (`'dim' | 'blur' | 'none'`), `size: null`
1727
- (CSS length or px number, applied to whichever axis `side` implies), `closeButton: true`,
1728
- plus everything Dialog takes — `title`, `content`, `buttons`, `closable`, `lightDismiss`
2067
+ (CSS length or px number, applied to whichever axis `side` implies), `closeButton: true`
2068
+ (independent of `closable`, which governs Escape; when false the ✕ is not displayed, not
2069
+ focusable, and closes nothing), plus everything Dialog takes — `title`, `content`, `buttons`, `closable`, `lightDismiss`
1729
2070
  (defaults to `true` here, unlike Modal), `destroyOnClose`, `scope`.
1730
2071
  - **Methods** — `open()`, `close(result?)`, `setSide(side)`, `getSide()`, `setSize(size)`,
1731
2072
  `isModal()`, `isDocked()`, `isOpen()`, `getSize()`, `snapTo(target)`, plus Dialog's `setTitle()`, `setContent()`,
1732
2073
  `setButtons()`, `addView()`, `showView()`.
1733
- - **Events** — `open`, `close {result}`, `cancel` (preventable with `event.preventDefault()`),
2074
+ - **Events** — `open`, `close {result}`, `cancel {reason}` (preventable; raised by Escape, the ✕,
2075
+ a backdrop click or outside press, and a dismissing drag — see Modal's **Dismissal**),
1734
2076
  `resize {size, ratio}`, `dockchange {docked, dock}`.
1735
2077
  - **Docked** — a sheet has two lives, and it does not choose between them: `Dock.adopt(sheet)`
1736
2078
  makes it a track in that dock's flow instead of an overlay, and the dock then owns its side,
@@ -1754,7 +2096,9 @@ When a Dock adopts it, the Sheet becomes an opaque layout surface instead.
1754
2096
  dialog while open, so it stays usable above it, closes when the dialog closes, and goes back to
1755
2097
  its theme scope when it closes. Their top-layer backdrop is
1756
2098
  explicitly transparent and non-filtering; `backdrop` is meaningful only when `modal` is `true`.
1757
- A docked Sheet remains a native non-modal dialog in its Dock's flow.
2099
+ A docked Sheet remains a native non-modal dialog in its Dock's flow. Where the platform has no
2100
+ `showPopover()` (jsdom), a floating non-modal sheet is presented the same in-flow way, without
2101
+ the top layer.
1758
2102
  - **Resizing and detents** — `resizable` makes the inner edge draggable between `min` and `max`.
1759
2103
  `snap` gives it detents: a number at or below 1 is a fraction of the viewport along the sheet's
1760
2104
  axis, anything larger is pixels, and a string is any CSS length (`'320px'`, `'90%'`). With
@@ -1874,8 +2218,11 @@ A button that opens a `role="menu"`.
1874
2218
  - `href`, `target`, and `rel` render a genuine safe native link, preserving modifier clicks and
1875
2219
  targets. Executable URL schemes are rejected; `_blank` receives `noopener noreferrer` by
1876
2220
  default.
1877
- - `role: 'menuitemcheckbox'|'menuitemradio'` with `checked` exposes an APG checked action. The
1878
- application owns state changes and calls `setItems()` with the new model.
2221
+ - `role: 'menuitemcheckbox'|'menuitemradio'` with `checked` exposes an APG checked action.
2222
+ Choosing one updates it in place — a checkbox toggles, a radio is checked and the other radio
2223
+ items of its section (between separators or headings) are unchecked — and `select` reports the
2224
+ new state as `detail.checked`. Preventing `select` leaves the state as it was; the item objects
2225
+ passed in are not modified, so call `setItems()` to keep the model in step.
1879
2226
  - `{type: 'choice', label, value, options: [{value, label, icon|glyph}], onselect(value, entry,
1880
2227
  menu)}` draws a setting chosen in place — a theme, a layout: the label, then a small segmented
1881
2228
  group of `menuitemradio` options named by it. Choosing an option checks it and calls
@@ -1938,7 +2285,7 @@ parked at the pointer, so it flips near a viewport edge like every other floatin
1938
2285
  <!-- doc:tooltip -->
1939
2286
  ### Tooltip
1940
2287
 
1941
- A description bubble anchored to another element. The panel is a manual popover positioned by the kernel's `position()`, so it escapes clipping and stacking contexts and flips near a viewport edge; it carries `role="tooltip"` and a generated id, and the anchor gets `aria-describedby` pointing at it only while it is open — closing puts the anchor's original value back, including no value at all. The bubble contains no focusable controls and stays visible while the pointer is over either the anchor or the bubble. Keyboard focus on the anchor independently keeps it visible. Hover opens it after `delay`; keyboard focus opens it immediately, because a keyboard user cannot hover a moment longer; a touch pointer never opens it, since a bubble with no "move away" gesture would simply stick. Only one is ever visible at a time, which falls out of the dismissal rules rather than a registry.
2288
+ A description bubble anchored to another element. The panel is a manual popover positioned by the kernel's `position()`, so it escapes clipping and stacking contexts and flips near a viewport edge; it carries `role="tooltip"` and a generated id, and the anchor's `aria-describedby` includes its id only while it is open — opening adds the id to whatever the attribute holds then, and closing removes only that id, so ids added by others (a field error) stay. The bubble contains no focusable controls and stays visible while the pointer is over either the anchor or the bubble. Keyboard focus on the anchor independently keeps it visible. Hover opens it after `delay`; keyboard focus opens it immediately, because a keyboard user cannot hover a moment longer; a touch pointer never opens it, since a bubble with no "move away" gesture would simply stick. Only one is ever visible at a time, which falls out of the dismissal rules rather than a registry.
1942
2289
 
1943
2290
  - **Options** — `content` (string, Node, or a function re-evaluated on every open), `placement`
1944
2291
  (`'top'` default, plus top/bottom/left/right and their start/end variants), `offset` (6), `delay`
@@ -1977,7 +2324,8 @@ Sortable, selectable, sticky-header data table. `fr` widths fill the container w
1977
2324
  widths scroll horizontally, and multi-select adds a tri-state header checkbox plus Shift+click
1978
2325
  range select.
1979
2326
 
1980
- - **Options** — `columns: [{ id, label, ariaLabel?, sortable?, width ('120px'|'2fr'|'auto'), align,
2327
+ - **Options** — `columns: [{ id, label, ariaLabel?, sortable?, width ('120px'|'2fr'|'auto'),
2328
+ minWidth?, pin?: 'start'|'end', group?, align,
1981
2329
  type?: 'text'|'number'|'currency'|'percent'|'unit', locale?, decimals?, currency?, unit?,
1982
2330
  render?: (row,i)=>Node|string, sortValue?, headerTitle? }]`, `data`, `rowId: 'ID'`,
1983
2331
  `sort: { id, dir }`, `sortMode: 'local'|'server'`, `selectable: false|'single'|'multi'`,
@@ -1992,6 +2340,38 @@ range select.
1992
2340
  the selected row of a `selectable: 'single'` table is the current record of a master–detail list
1993
2341
  and takes the neutral `--zx-color-bg-current` fill. Sortable and plain headers set the same type,
1994
2342
  and the scroll region reserves no scrollbar gutter until the table actually scrolls.
2343
+ - **Column widths** — `fr` columns share what the columns with a CSS length leave over, and never
2344
+ less than their `minWidth` (a CSS length or a number of pixels, default `'5rem'`; `0` lifts the
2345
+ floor). The table takes a minimum width from those floors, so a container too narrow for them
2346
+ scrolls the table inline instead of squeezing the `fr` columns to nothing — in a windowed table
2347
+ as well. `minWidth` is also honoured on an `auto` column of a table with a fixed layout (one
2348
+ with `fr` columns, or `virtual`), where it has no default; a column with a CSS length `width`
2349
+ ignores it.
2350
+ - **Sticky header** — `stickyHeader: true` sticks the column headers to the top of the table's
2351
+ **own scroll region** while its rows scroll. That takes a bounded region: set `height`, or use
2352
+ `virtual`, which caps the region at the window height. A table without one grows to the height
2353
+ of its rows, never scrolls itself, and its header leaves with the page; to keep a header in view
2354
+ while the *page* scrolls, give the table the height of the area it sits in. Header cells sit at
2355
+ `z-index: 2` inside the scroll region.
2356
+ - **Pinned columns** — `pin: 'start'|'end'` on a column keeps it in view at that inline edge of
2357
+ the scroll region while the table scrolls sideways (`position: sticky`, so it follows the
2358
+ writing direction). A pinned column stays where the column order puts it and sticks once it
2359
+ reaches the edge: declare a `'start'` column before the columns it should stay in front of and
2360
+ an `'end'` column after them. Several pinned columns stack in column order, and the row handle
2361
+ and selection checkbox columns are pinned along with the first `'start'` column. Give a pinned
2362
+ column a `width` or keep it short — what is pinned is taken from the room the others scroll in.
2363
+ A cell focused by keyboard scrolls clear of the pinned columns. Pinning is not applied while
2364
+ the table is stacked (`responsive`). Pinned cells are opaque and paint the row's fill
2365
+ themselves; `--zx-table-pin-bg` sets their base, the header background unless set. Cells carry
2366
+ `data-pin="start"|"end"`, and `data-pin-edge` on the column next to the scrolling ones.
2367
+ - **Header groups** — `group: 'Label'` on adjacent visible columns (with the same `pin`) gives
2368
+ them one shared header cell in a second header row above the column labels: a
2369
+ `<th scope="col">` with the right `colspan`, so assistive technology announces the group with
2370
+ every cell beneath it. Columns without a `group` have a blank above them. The group row holds
2371
+ no controls and takes no part in sorting or keyboard navigation; it counts as a row in
2372
+ `aria-rowcount`/`aria-rowindex`. Hiding or reordering columns regroups what is left: a group
2373
+ interrupted by another column becomes two cells. It works in plain, hierarchical and windowed
2374
+ tables, and sticks with the header.
1995
2375
  - **Columns in the DOM** — every header and body cell carries `data-column="<id>"` in every mode,
1996
2376
  read-only included, so a table can be styled per column. A column with `label: ''` (icons,
1997
2377
  actions) keeps a blank header named by `ariaLabel`, or by its id; `ariaLabel` also names the
@@ -2006,6 +2386,11 @@ range select.
2006
2386
  - **Events** — `rowclick {row, id, index, event}`, `rowdblclick`, `sort {id, dir}`,
2007
2387
  `selectionchange {rows, ids}`, `datachange {rows}`, and `rowtoggle {row, id, expanded}`.
2008
2388
  `rowclick` fires for Enter on a focused row as well as for a click; `event` is then the keydown.
2389
+ A click on a control inside a cell belongs to that control: it raises neither `rowclick` nor
2390
+ `rowdblclick` and does not select the row in a `single` selection. A control is a button, link,
2391
+ field or `<label>`, an element with a widget role or in the Tab order, editable content, or
2392
+ anything marked `data-zx-table-no-edit` — so a Toggle, a menu button or a link rendered into a
2393
+ cell needs no `stopPropagation()`. Mark a custom clickable element the same way.
2009
2394
  - **Keyboard** — an *interactive* table implements the WAI-ARIA APG **Grid** pattern
2010
2395
  (`role="grid"`, with `aria-multiselectable` for `selectable: 'multi'`), or the **Treegrid**
2011
2396
  pattern with `hierarchy`. A table is interactive when it is `selectable`, has `editMode` or
@@ -2047,7 +2432,13 @@ range select.
2047
2432
  editing/mutation APIs stay flat and ID-based. Orphans become roots, cycles render once, local
2048
2433
  sort reorders siblings without mixing levels, and growing counts visible rows. Use
2049
2434
  `toggleRow()`, `expandRow()`, `collapseRow()`, `expandAll()`, `collapseAll()`, and
2050
- `getExpanded()`. The native disclosure button works by pointer and keyboard without selecting
2435
+ `getExpanded()`. `hierarchy.expanded` is read at construction only; `setExpanded(ids, {silent})`
2436
+ replaces the whole set afterwards in one render, which is what to call when restoring a saved
2437
+ state (a loop over `expandRow()` renders once per branch). `true` expands every branch, `false`
2438
+ or `[]` collapses them all; ids are compared as `rowId` returns them (`1` is not `'1'`), and ids
2439
+ that are not branches of the current data are dropped. Unless silent it emits one `rowtoggle`
2440
+ per branch whose state changed, after the render; a set equal to the current one renders and
2441
+ fires nothing. The native disclosure button works by pointer and keyboard without selecting
2051
2442
  or clicking the row.
2052
2443
  - **Editing** — `editMode: false|'cell'|'row'` (default `false`, and completely inert until set),
2053
2444
  plus `editTrigger: 'double'|'single'` (Table defaults to double; Grid defaults to single).
@@ -2118,7 +2509,8 @@ range select.
2118
2509
  height for all, following `--zx-row-height`, so rows of differing height are not supported, and
2119
2510
  long text is cut short with an ellipsis rather than wrapped. Column widths cannot follow content
2120
2511
  that is not drawn, so the layout is fixed: `auto` columns share the width evenly, and a column that
2121
- needs more sets `width`. **Find-in-page does not see rows that are not drawn**, and printing prints
2512
+ needs more sets `width`. It needs no `ResizeObserver`: where there is none (jsdom) the window
2513
+ draws for an assumed row height and viewport. **Find-in-page does not see rows that are not drawn**, and printing prints
2122
2514
  the drawn rows only.
2123
2515
  - **Responsive stacking** — `responsive: false|'sm'|'md'|'lg'|'xl'` stacks each row into a card of
2124
2516
  label/value pairs below that width, instead of leaving a horizontal scrollbar with the data
@@ -2286,7 +2678,8 @@ cards, advisory work-in-progress limits, and equivalent pointer/programmatic/key
2286
2678
  and action controls reveal on hover/focus/selection/grab, and remain visible on touch devices.
2287
2679
  - **Assignees** — `assignees` faces (a name, names, or `{name, src?, initials?, tone?}`) are drawn
2288
2680
  like a small Avatar: initials on the tint `avatarTone(name)` picks, so a person has the same
2289
- colour on the board as in every Avatar; a descriptor's own `tone` wins.
2681
+ colour on the board as in every Avatar; a descriptor's own `tone` wins. A descriptor with `face`
2682
+ (AgentAvatar traits, or `true`) is an agent, drawn as its generated face.
2290
2683
  - **Movement boundary** — `recordmove {record,id,from,to,column,swimlane,limitExceeded}` is
2291
2684
  cancelable and fires before a commit/request; either the component event or bubbling
2292
2685
  `zx-recordmove` mirror may veto it. `accept` is a hard eligibility gate; WIP is visual advice.
@@ -2309,7 +2702,9 @@ without forking its implementation, so sorting, selection, hierarchy, responsive
2309
2702
  editable cells/rows, loading, events, and teardown keep the Table contract.
2310
2703
 
2311
2704
  - **Constructor** — `new Grid(target, tableOptions)` accepts the complete `Table` API and defaults
2312
- editable cells to a single-click trigger.
2705
+ editable cells to a single-click trigger. Pinned columns, header groups, `minWidth`,
2706
+ `setExpanded()` and the rule that a click on a control inside a cell raises no `rowclick` are
2707
+ Table's and apply unchanged.
2313
2708
  - **Preset** — `Grid.BillingItems(target, options)` supplies an editable hierarchical billing
2314
2709
  schema for item, quantity, unit, unit price, currency, and line total. It enables single-click
2315
2710
  editing, hierarchy, row reorder handles, and the column visibility chooser. It returns a `Grid`.
@@ -2325,33 +2720,111 @@ editable cells/rows, loading, events, and teardown keep the Table contract.
2325
2720
  <!-- /doc -->
2326
2721
 
2327
2722
  <!-- doc:chart -->
2328
- ### Chart and `ChartJsAdapter`
2723
+ ### Chart, `SvgChartAdapter` and `ChartJsAdapter`
2329
2724
 
2330
2725
  An accessible, engine-neutral chart host. Zx renders state, canvas, semantic data summary, tokens,
2331
- and lifecycle; an injected adapter owns the drawing engine. The Zx runtime imports no Chart.js
2332
- code. A renderer must be injected: without one Chart cannot draw data. The only supplied renderer
2333
- is `ChartJsAdapter`, which requires host-provided Chart.js 4.
2726
+ and lifecycle; an adapter owns the drawing. Two are supplied: `SvgChartAdapter` draws bar, line,
2727
+ pie and doughnut charts as SVG and needs nothing else; `ChartJsAdapter` draws any Chart.js type
2728
+ with a Chart.js 4 the host supplies (the Zx runtime imports no Chart.js code). Without an adapter
2729
+ Chart draws nothing, and the data lives in its summary table alone.
2730
+
2731
+ ```js
2732
+ const chart = new Chart(null, {
2733
+ adapter: new SvgChartAdapter(),
2734
+ type: 'bar',
2735
+ label: 'Invoiced and collected per week',
2736
+ data: { labels: ['Week 1', 'Week 2'], datasets: [{ label: 'Invoiced', data: [52300, 61200] }] }
2737
+ });
2738
+ ```
2334
2739
 
2335
2740
  - **Options** — `adapter`, `type: 'bar'`, `data`, engine-specific `chartOptions`, `label`,
2336
- `description`, `summary: 'hidden'|'visible'`, `loading`, loading/empty/error text, and
2337
- `aspectRatio: '16 / 9'`.
2741
+ `description`, `summary: 'hidden'|'visible'`, `summaryFormat: null`, `loading`,
2742
+ loading/empty/error text, `aspectRatio: '16 / 9'`, and `fill: false`.
2338
2743
  - **Methods** — `setData()`, `setType()`, `update(chartOptions)`, `setAdapter()`, `setLoading()`,
2339
- `setError()`, `clearError()`, `resize()`, `refreshTheme()`, `getInstance()`, `destroy()`.
2744
+ `setError()`, `clearError()`, `setLabel()`, `setDescription()`, `setSummary()`,
2745
+ `setAspectRatio()`, `setFill()`, `resize()`, `refreshTheme()`, `getInstance()`, `destroy()`.
2340
2746
  - **Events** — `ready {instance}`, `update {data, type}`, `select {datasetIndex, index, dataset,
2341
2747
  label, value, nativeEvent}`, and `error {error}`.
2342
- - **Adapter contract** — `adapter.create(canvas, {type, data, options, reducedMotion, onSelect})`
2343
- returns `{update(spec), resize(), destroy(), instance?}`. Implementations must destroy engine
2748
+ - **When the engine exists** — the engine is created once the chart is in a document, its
2749
+ viewport has a size, and it has data and an adapter; `ready` fires then, not necessarily inside
2750
+ the constructor. A chart constructed on a target that is already laid out mounts synchronously;
2751
+ one built with `null` and appended later mounts when the browser reports its size.
2752
+ `getInstance()` and `resize()` do not wait: called after the chart is appended, they create the
2753
+ engine on the spot, and `getInstance()` returns null while there is none. A chart that is
2754
+ loading, empty, or in error has no engine. Where there is no `ResizeObserver` or no layout at
2755
+ all (jsdom), nothing can report a size and the engine is created as soon as there is data.
2756
+ - **State changes and the engine** — `setData()` clears both the loading state and an error.
2757
+ `setLoading(true)` and `setError()` destroy the engine; the next `setData()`,
2758
+ `setLoading(false)` or `clearError()` creates a new one and fires `ready` again, so do not hold
2759
+ on to an instance across them. `setAdapter()` replaces the engine as well.
2760
+ - **Sizing** — by default the viewport takes the width it is given and derives its height from
2761
+ `aspectRatio` (`setAspectRatio()` changes it; null restores the default), never less than
2762
+ `--zx-chart-min-block-size` (220px unless set, on the chart or any ancestor). `fill: true` (or
2763
+ `setFill()`) takes the block size of the container instead: the root is 100% tall, the viewport
2764
+ takes what the description and a visible summary leave, `aspectRatio` is not used, and there is
2765
+ no minimum unless `--zx-chart-min-block-size` sets one. The container needs a height of its
2766
+ own. The chart follows its viewport; `resize()` is for an engine that needs telling after
2767
+ something else changed.
2768
+ - **Theme** — the chart resolves `--zx-color-text`, `--zx-color-border` and the categorical
2769
+ palette `--zx-color-chart-1`…`-8` on its root and hands them to the adapter as values. It does
2770
+ so again by itself when a `data-zx-theme` or `data-zx-preset` attribute changes anywhere in the
2771
+ document, when the system colour scheme or contrast preference changes, and when the chart is
2772
+ shown again after being hidden or moved. `refreshTheme()` is only for changes none of those
2773
+ cover: a stylesheet swap, a class, an inline custom property.
2774
+ - **Adapter contract** — `adapter.create(canvas, {type, data, options, theme, reducedMotion, onSelect})`
2775
+ returns `{update(spec), resize(), destroy(), instance?}`; `update(spec)` is called for new data,
2776
+ type or options and whenever the theme or the motion preference changes. An adapter that draws
2777
+ an element of its own implements `mount(viewport, spec)` instead, with the same spec and handle:
2778
+ Chart calls `mount()` when an adapter has it, `create()` otherwise. The canvas then stays in
2779
+ place, empty, keeping the chart's accessible name and description; what `mount()` appends lies
2780
+ over it, is presentational (`aria-hidden="true"`), and goes with the handle's `destroy()`. `spec.theme` is
2781
+ `{color?, borderColor?, palette}`: text colour, grid and axis colour, and the series colours in
2782
+ order (empty where the tokens are not defined; series beyond the eighth start over).
2783
+ `spec.options` is the application's `chartOptions` over `color` and `borderColor`, the same two
2784
+ strings in the shape Chart.js reads. Every colour is `#rrggbb` when opaque and
2785
+ `rgba(r, g, b, a)` when translucent — never `color()`, `oklch()`, `light-dark()` or a `var()` —
2786
+ so an engine with its own colour parser reads it. Implementations must destroy engine
2344
2787
  resources and must not retain the component after teardown. `reducedMotion` is true under the
2345
2788
  system preference or inside a `data-zx-motion="reduced"` region, and an adapter must then turn its
2346
2789
  engine's animation off; Chart watches for the answer changing and updates the mounted engine.
2790
+ - **`SvgChartAdapter`** — `new SvgChartAdapter({animation: true, legend: null})` draws `bar`
2791
+ (grouped), `line`, `pie` and `doughnut`; any other type puts the chart in its error state, and
2792
+ `SvgChartAdapter.supports(type)` answers first. A value is a number, or the `y` (else `r`) of a
2793
+ point object; null and anything not finite is a gap — no bar, a break in the line, no slice.
2794
+ Bars stand on zero; a line's scale spans its data; ticks fall on 1, 2 or 5 × 10ⁿ and are written
2795
+ compactly in the active language ("250K"). Pie and doughnut draw one ring per dataset, a slice
2796
+ per positive value. The legend lists the series (the labels, for pie and doughnut) when there are
2797
+ two or more and for the arc kinds; `legend: true|false` forces it. Colours come through CSS from
2798
+ `--zx-color-chart-1`…`-8`, so a theme or preset switch repaints without a redraw; a dataset's own
2799
+ colour keys are not read, and series past the eighth take the palette again, lighter (dashed, for
2800
+ a line). The plot's `viewBox` is its size in pixels, so text keeps its size: it scales with the
2801
+ viewport and is laid out again on the next resize, thinning category labels rather than
2802
+ overlapping them. Each mark has a `<title>` ("Week 1 · Invoiced: 52,300") and pressing one fires
2803
+ `select` with the usual detail; there is no keyboard path through the marks — the summary table is
2804
+ the accessible one. The first drawing grows in unless motion is reduced (system, or a
2805
+ `data-zx-motion="reduced"` region) or `animation` is false; per chart, `chartOptions.animation` and
2806
+ `chartOptions.legend` decide over the adapter's options. `getInstance()` returns the drawing
2807
+ element. One adapter serves any number of charts.
2347
2808
  - **`ChartJsAdapter`** — construct it with a Chart.js constructor or namespace:
2348
2809
  `new ChartJsAdapter(window.Chart)`. The documentation pins Chart.js 4.5.1 as a development dependency and copies it to its
2349
2810
  self-hosted vendor assets during the website build; `package.json` has no runtime dependencies and application builds explicitly choose how
2350
2811
  the engine is loaded. Under reduced motion it sets `animation: false`, over any animation the
2351
- application configured.
2352
- - **Accessibility** — the canvas always has a name and optional description, while synchronized
2353
- labels and dataset values live in a semantic table. `summary: 'hidden'` keeps it visually hidden
2354
- for assistive technology; `'visible'` makes exact values part of the interface.
2812
+ application configured. A dataset that names neither `backgroundColor` nor `borderColor` is
2813
+ coloured from the theme palette: one colour per series (a bar filled with it, a line, radar or
2814
+ point series stroked with it and filled at half opacity), or one per value for `pie`,
2815
+ `doughnut` and `polarArea`. A dataset that names either is left exactly as written.
2816
+ - **Accessibility** — the canvas always has a name and optional description, whichever adapter
2817
+ draws, while synchronized labels and dataset values live in a semantic table.
2818
+ `summary: 'hidden'` keeps it visually hidden for assistive technology; `'visible'` makes exact
2819
+ values part of the interface. `setLabel()`
2820
+ renames the canvas and the table's caption, `setDescription()` and `setSummary()` change the
2821
+ other two.
2822
+ - **Summary values** — a number is written for the active language (the chart's `lang`, else
2823
+ `getLanguage()`) with grouping and up to twelve significant digits: `1234567.5` reads
2824
+ "1,234,567.5" and `0.1 + 0.2` reads "0.3". For a point object the value is its `y`, else its
2825
+ `r`. `summaryFormat(value, context)` returns the text of one cell instead — a currency, a unit,
2826
+ a percentage — with `context` `{dataset, datasetIndex, index, label, raw, formatted}`, where
2827
+ `formatted` is the default text; returning null or undefined keeps it.
2355
2828
  <!-- /doc -->
2356
2829
 
2357
2830
  <!-- doc:calendar -->
@@ -2366,8 +2839,10 @@ windowed loader.
2366
2839
  - **Options** — `events`, `date`, `view: 'month'`, `views: ['agenda','day','week','month','year']`,
2367
2840
  `locale`, `weekStart: 1`, `weekNumbers: true`, `workweek: false`, `agendaDays: 14`,
2368
2841
  `slotDuration: 30`, `slotMinTime: 0`, `slotMaxTime: 1440`, `scrollTime: 480`, `eventLimit: 3`,
2369
- `selectable: false`, `editable: false`, `eventStartEditable`, `eventDurationEditable`,
2370
- `optimistic: true`, `nowIndicator: true`, `now`, `disabled`, `msg`, and `renderEvent(event)`.
2842
+ `selectable: false`, `editable: false`, `eventStartEditable` (`true`/`false` overrides
2843
+ `editable` for moving), `eventDurationEditable` (`true`/`false` overrides `editable` for
2844
+ resizing; a string or function instead names the per-event resize field, `'durationEditable'`
2845
+ by default), `optimistic: true`, `nowIndicator: true`, `now`, `disabled`, `msg`, and `renderEvent(event)`.
2371
2846
  - **Messages** — every key is namespaced `calendar.*`: `calendar.today`, `calendar.previous`,
2372
2847
  `calendar.next`, `calendar.new`, `calendar.agenda`/`day`/`week`/`month`/`year` (the view
2373
2848
  switch), `calendar.viewSwitch`, `calendar.label` (the root's name), `calendar.loading`,
@@ -2412,7 +2887,9 @@ windowed loader.
2412
2887
  text announces the edit and its proposed times.
2413
2888
  - **ZeyOS binding** — `zeyosCalendar()` maps current appointment occurrence rows (`ID`, `name`,
2414
2889
  `location`, `color`, `datefrom`, `dateto`, and association text). `calendarEventToZeyosPatch()`
2415
- returns the base `ID` with Unix-second dates. The current server already expands recurrence into
2890
+ returns the base `ID` with Unix-second dates. Pass the instance's `timeZone` to both so an all-day
2891
+ appointment is recognised from midnight in that zone and lands on the right days for a viewer
2892
+ elsewhere; without it the viewer's own midnight is used. The current server already expands recurrence into
2416
2893
  the requested window; recurrence rules, DAV synchronization, permissions, and routes therefore
2417
2894
  remain in ZeyOS instead of being reimplemented in core.
2418
2895
  <!-- /doc -->
@@ -2533,7 +3010,9 @@ mutate the caller's data.
2533
3010
  - **Options** — `items` (nested), `valueKey: 'ID'`, `labelKey: 'name'`, `childrenKey: 'children'`,
2534
3011
  `expanded: []`, `selection: 'single'|'multi'|false`, `selected: []`, `checkboxes: false`
2535
3012
  (tri-state), `checked: []`, `icons: true`, `renderLabel`, `load: (node)=>Promise<children>`
2536
- (lazy children; mark a branch with `hasChildren: true`), `filter`, `emptyText`, `height`,
3013
+ (lazy children; mark a branch with `hasChildren: true` — it counts as open only once its
3014
+ children are loaded, so → and `toggle()` load it, `*` loads and opens lazy siblings, and
3015
+ `expandAll()`, filtering and `expanded` leave unloaded branches closed), `filter`, `emptyText`, `height`,
2537
3016
  `rowActions: (node) => actions`, `moreLabel`. Unset, `label`, `emptyText` and `moreLabel` read the
2538
3017
  `tree.label`, `tree.noItems` and `tree.more` messages; `tree.empty` still wins over `emptyText`, and
2539
3018
  `emptyText: null` shows no text.
@@ -2678,10 +3157,37 @@ Beyond the built-in field types, these widget types wrap whole components, used
2678
3157
  `registerFieldAdapters()`, which `src/index.js` calls by default.
2679
3158
 
2680
3159
  - `zxselect` (Select), `checklist` (Checklist), `tagpicker` (TagPicker), `number` (NumberField),
2681
- `rating` (Rating).
2682
- - `date`/`month`/`datetime` (Datebox/MonthPicker — pass a `Date` value), `time` (Timebox).
3160
+ `rating` (Rating), `slider` (Slider).
3161
+ - `date`/`month`/`datetime` (Datebox/MonthPicker — pass a `Date` value), `daterange`
3162
+ (DateRangeBox — a `{start, end}` value), `time` (Timebox).
2683
3163
  - `valuelist` (ValueList), `multivalueeditor` (MultiValueEditor), `upload` (FieldUpload),
2684
- `toggle` (Toggle).
3164
+ `toggle` (Toggle), `code` (CodeEditor).
3165
+
3166
+ **Stylesheet names for `zx-css`.** A field type is registered at run time, so `zx-css` cannot
3167
+ follow it from `form` to the component that draws it: name that component's stylesheet beside
3168
+ `form`. Each line is field type — component — the name to pass, and the stylesheets that name
3169
+ depends on come with it.
3170
+
3171
+ - `zxselect` — Select — `select`
3172
+ - `checklist` — Checklist — `checklist`
3173
+ - `tagpicker` — TagPicker — `tag-picker`
3174
+ - `number` — NumberField — `number-field`
3175
+ - `rating` — Rating — `rating`
3176
+ - `slider` — Slider — `slider`
3177
+ - `date` — Datebox — `datebox`
3178
+ - `datetime` — DateTimeBox — `datebox`
3179
+ - `month` — MonthPicker — `date-picker`
3180
+ - `daterange` — DateRangeBox — `date-range-box`
3181
+ - `time` — Timebox — `timebox`
3182
+ - `valuelist` — ValueList — `value-list`
3183
+ - `multivalueeditor` — MultiValueEditor — `multi-value-editor`
3184
+ - `upload` — FieldUpload — `field-upload`
3185
+ - `toggle` — Toggle — `toggle`
3186
+ - `code` — CodeEditor — `code-editor`
3187
+
3188
+ The built-in types — `text`, `password`, `textarea`, `checkbox`, `int`, `float`, `select`,
3189
+ `optionlist`, `hidden`, `html`, `custom` — are drawn by Field itself and need `form` alone. A form
3190
+ with a Select and a date field is `npx zx-css form select datebox --out public/zx.css`.
2685
3191
  <!-- /doc -->
2686
3192
 
2687
3193
  <!-- doc:code-editor -->
@@ -2693,17 +3199,32 @@ surface for structured text — templates, queries, configuration — while rich
2693
3199
  stays a separate policy decision.
2694
3200
 
2695
3201
  - **Options** — `value`, `name`, `language` (shown to the reader and exposed as data),
2696
- `label`, `placeholder`, `rows` (clamped 2–100), `indent` (inserted by Tab, removed by
2697
- Shift+Tab), `wrap: 'off'|'soft'|'hard'`, `spellcheck`, `readOnly`, `disabled`,
2698
- `status` (the line/column readout).
2699
- - **Methods** — `setValue()`.
2700
- - **Events** — `input {value}`, `change {value}`.
2701
-
2702
- Tab indents rather than moving focus, which is what a code surface has to do and what makes it a
2703
- keyboard trap if nothing else is arranged — so Escape releases the capture until the next
2704
- keystroke in the editor: Escape then Tab (or Shift+Tab) leaves the field, and any other key,
2705
- or leaving the editor, restores indentation. A `code` Form field adapter is registered by
2706
- `registerFieldAdapters()`.
3202
+ `label`, `placeholder`, `rows` (clamped 2–100), `indent: '\t'` (inserted by Tab, removed by
3203
+ Shift+Tab; `' '` for two spaces, `''` to leave Tab alone), `wrap: 'off'|'soft'|'hard'`,
3204
+ `spellcheck`, `readOnly`, `disabled`, `status` (the line/column readout).
3205
+ - **Methods** — `setValue()`, `getValue()`, `setLanguage()`, `setReadOnly()`,
3206
+ `enable()`/`disable()`, `getInput()` (the
3207
+ native textarea: the element that carries the name, validity and description, and the one a
3208
+ `<label for>` names), `setHighlight(message, kind = 'danger')`, `clearHighlight()`, `focus()`.
3209
+ - **Events** — `input {value}`, `change {value}`, `invalid {message}`.
3210
+ - **Tab** — while `indent` is non-empty the editor captures Tab: Tab inserts the indent at the
3211
+ caret or indents every selected line, Shift+Tab outdents them, and focus stays in the editor.
3212
+ That is what a code surface has to do and what makes it a keyboard trap if nothing else is
3213
+ arranged — so Escape releases the capture until the next keystroke in the editor: Escape then
3214
+ Tab (or Shift+Tab) leaves the field, and any other key, or leaving the editor, restores
3215
+ indentation. `indent: ''` switches the capture off: Tab and Shift+Tab move focus as in any other
3216
+ field and nothing is indented. Tab with Ctrl, Alt or Meta, and Tab in a read-only or disabled
3217
+ editor, are never captured.
3218
+ - **Error state** — a standalone editor reports a validation or status message the way a Field
3219
+ does. `setHighlight(message, kind)` shows it under the text and reflects `kind`
3220
+ (`'danger'|'warning'|'success'`) as `data-state` on the root. `'danger'` is the error state: the
3221
+ textarea gets `aria-invalid="true"`, the message is announced as an alert, the frame takes the
3222
+ danger colour, and `invalid {message}` is emitted. The message describes the textarea
3223
+ (`aria-describedby`) for as long as it is shown; an empty message, or `clearHighlight()`, clears
3224
+ it.
3225
+ - **In a Form** — a `code` field adapter is registered by `registerFieldAdapters()`. Set the
3226
+ Field's own message there (`field.setHighlight()`), not the editor's: the Field labels the
3227
+ textarea, marks it invalid and describes it with its message, and the editor's frame follows.
2707
3228
  <!-- /doc -->
2708
3229
 
2709
3230
  <!-- doc:questionnaire -->
@@ -2974,6 +3495,11 @@ returns the component, the way `tooltip()` does; call `.toElement()` for the nod
2974
3495
  decoration and saying the delta twice is worse than saying it once.
2975
3496
  - **The element follows the behaviour** — `href` renders an `<a>`, `onclick` without `href` a
2976
3497
  `<button>`, neither a `<div>` with `role="group"`. Never a div with a click handler.
3498
+ `clickable: true` renders the button without an `onclick` option, for subscribing with
3499
+ `on('click', …)`. An explicit `clickable: false` wins over `onclick`: the tile stays a `<div>`
3500
+ and the handler is never called, for a caller that always passes a handler and decides per tile
3501
+ whether it applies. It never turns a tile with an `href` into anything but a link. Leave
3502
+ `onclick` out, rather than passing an empty function, for a tile that does nothing.
2977
3503
  - **`loading: true` renders a skeleton shaped like the tile**, not a spinner.
2978
3504
 
2979
3505
  Nothing in it assumes a fixed set of buckets or a fixed label: the content of a dashboard tile
@@ -2988,18 +3514,27 @@ the target in place: it does not wrap, replace, or relocate the surface's conten
2988
3514
  own routing, overlays, or interaction. Its gradients sit behind the target's children, so raised
2989
3515
  Cards and other Liquid Glass surfaces can pick up the underlying colour naturally.
2990
3516
 
2991
- - **Options** — `preset: 'source'|'confluence'|'horizon'|'diagonal'|'edge'|'curtain'`,
3517
+ - **Options** — `preset: 'source'|'confluence'|'horizon'|'diagonal'|'edge'|'curtain'|'mesh'|'ribbon'|'bloom'`,
2992
3518
  `colors: []` (zero to four concrete CSS colours),
2993
- `intensity: 'subtle'|'balanced'|'vivid'`.
2994
- - **Methods** — `setPreset(preset)`, `setColors(colors)`, `setIntensity(intensity)`.
3519
+ `intensity: 'subtle'|'balanced'|'vivid'`, `motion: 'none'|'drift'|'flow'`.
3520
+ - **Methods** — `setPreset(preset)`, `setColors(colors)`, `setIntensity(intensity)`,
3521
+ `setMotion(motion)`.
2995
3522
  - **Palette** — an empty list uses semantic accent, info, success, and warning colours. One colour
2996
3523
  fills all four fields; two alternate; three repeat the second colour in the fourth field; four
2997
3524
  map directly. Network/image-bearing CSS values and palettes longer than four are rejected.
2998
3525
  - **Geometry** — Source starts at the leading chrome; Confluence meets from the corners; Horizon
2999
3526
  forms a shallow top band; Diagonal crosses the surface; Edge preserves a neutral centre; Curtain
3000
- descends as four elongated fields. All use ordinary CSS gradients without animation.
3527
+ descends as four elongated fields; Mesh binds four fields with a wash in the middle; Ribbon hangs
3528
+ two arcs of light from above the top edge; Bloom rises from below the bottom edge. All are
3529
+ ordinary CSS gradients, written into `--zx-aurora-image`.
3530
+ - **Motion** — `drift` lets the field breathe while two lights wander across it; `flow` turns a disc
3531
+ of colour slowly behind it. For either, Aurora adds one `<span class="zx-aurora__motion"
3532
+ aria-hidden="true">` as the target's first child, clipped to the surface, and moves its layers by
3533
+ transform alone, so nothing repaints. `--zx-aurora-duration` (18s) sets the pace. Readers who ask
3534
+ for reduced motion see the static field.
3001
3535
  - **Lifecycle** — `destroy()` removes an owned root or restores every original attribute and child
3002
- of an enhanced target. Content is never rebuilt when a setter changes the effect.
3536
+ of an enhanced target. Content is never rebuilt when a setter changes the effect; `setMotion()`
3537
+ adds or removes only the motion element.
3003
3538
  - **Accessibility** — the light field is pointer-transparent and purely decorative. Forced-colour
3004
3539
  and reduced-transparency preferences remove it entirely.
3005
3540
  <!-- /doc -->
@@ -3159,7 +3694,9 @@ complete, or errored. It promotes the markup the checkout and record wizards use
3159
3694
  Advancing past a step marks it complete automatically, and only steps the `clickable` policy allows
3160
3695
  are rendered as real buttons — the rest are not focusable at all. A horizontal rail fills the width
3161
3696
  it is given: the labels keep their own width and the connectors stretch to take the slack, wrapping
3162
- onto more lines only when the container is too narrow to hold them.
3697
+ onto more lines only when the container is too narrow to hold them. A wrapped row ends at its last
3698
+ step: no connector runs on from it to the container's edge. The component marks that step with
3699
+ `data-row-end` as the layout changes.
3163
3700
 
3164
3701
  - **Options** — `steps: [{name, title, description?, optional?, disabled?}]`, `active` (defaults to
3165
3702
  the first enabled step), `orientation: 'horizontal'|'vertical'`, `clickable:
@@ -3308,16 +3845,48 @@ pager.on('change', async ({ detail }) => {
3308
3845
 
3309
3846
  In `mode: 'loadmore'` each `change` is one `binding.loadMore()`, which appends.
3310
3847
 
3311
- - **Options** — `page: 1`, `pageSize: 25`, `total: 0`, `pageSizes: [25, 50, 100]`, `siblings: 1`,
3312
- `boundaries: 1`, `showPageSize: true`, `showSummary: true` (renders "26–50 of 312"),
3313
- `mode: 'pages'|'loadmore'`, `disabled: false`.
3314
- - **Methods** — `setPage(n)`, `setTotal(n)`, `setPageSize(n)`, `setState({page, pageSize, total},
3315
- {silent})`, `getState()` → `{page, pageSize, total, pages, offset}`, `enable()`/`disable()`,
3316
- `destroy()`.
3317
- - **Events** — `change {page, pageSize, offset, total, pages}`, fired for a page change, a
3318
- page-size change (which resets to page 1), and Load more.
3848
+ **Fitting the page.** `pageSize: 'auto'` (and `'auto'` among `pageSizes`, shown as "Auto (14)")
3849
+ shows as many rows as fit `viewport`, the element the rows scroll in, below its sticky `thead`. It
3850
+ measures again whenever the viewport or its content changes size — a window, a drawer, the row height,
3851
+ a table stacking into cards — and keeps the page's first row on the new page. A Zx Table is
3852
+ measured by its first body row, anything else by `--zx-row-height`; `rowHeight`, `perRow` (a card
3853
+ grid's columns) and `reserve` take numbers or functions of the viewport for other content. Call
3854
+ `refit()` after swapping what the viewport shows.
3855
+
3856
+ **Auto-load.** `autoLoad: true` turns paging into infinite scroll: the next page loads by itself
3857
+ when the end of the viewport (or, without one, the pager) comes within `autoLoadMargin` pixels —
3858
+ half the viewport by default. `showAutoLoad: true` adds an Auto-load switch, so the reader chooses;
3859
+ switching between paging and appending returns to page 1. Load more stays as the keyboard's way on.
3860
+ Disable the pager while a page is in flight and enable it when the rows land; auto-load waits:
3861
+
3862
+ ```js
3863
+ const pager = new Pagination(footer, { pageSize: 'auto', pageSizes: ['auto', 25, 50], viewport: list, showAutoLoad: true });
3864
+ pager.on('change', async ({ detail }) => {
3865
+ pager.disable();
3866
+ // Appending adds one page; paging shows one; restarting an appending list shows all loaded so far.
3867
+ const from = detail.append || detail.mode === 'pages' ? detail.offset : 0;
3868
+ const rows = await fetchRows(from, detail.offset + detail.pageSize - from);
3869
+ if (detail.append) table.addData(rows); else table.setData(rows);
3870
+ pager.enable();
3871
+ });
3872
+ ```
3873
+
3874
+ - **Options** — `page: 1`, `pageSize: 25` (or `'auto'`), `total: 0`, `pageSizes: [25, 50, 100]`
3875
+ (may include `'auto'`), `siblings: 1`, `boundaries: 1`, `showPageSize: true`, `showSummary: true`
3876
+ (renders "26–50 of 312"), `mode: 'pages'|'loadmore'`, `autoLoad: false`, `showAutoLoad: false`,
3877
+ `viewport: null` (element, selector, or function), `rowHeight`, `perRow: 1`, `reserve`,
3878
+ `minPageSize: 5`, `maxPageSize: 200`, `autoLoadMargin: null`, `disabled: false`.
3879
+ - **Methods** — `setPage(n)`, `setTotal(n)`, `setPageSize(n|'auto')`, `setState({page, pageSize,
3880
+ total}, {silent})`, `setAutoLoad(on, {silent})`, `refit()`, `getState()` → `{page, pageSize,
3881
+ total, pages, offset, auto, autoLoad, mode}`, `enable()`/`disable()`, `destroy()`.
3882
+ - **Events** — `change {page, pageSize, offset, total, pages, auto, autoLoad, mode, reason,
3883
+ append}`, where `reason` is `page`, `pageSize`, `fit`, `more`, `scroll`, `mode`, or `state`, and
3884
+ `append` means "add rows `offset … offset + pageSize` after the shown ones" (otherwise show rows
3885
+ `offset …` while paging, `0 … page × pageSize` while appending). `autoload {autoLoad}` when the
3886
+ switch flips.
3319
3887
  - **Also exported** — `paginationRange({page, pages, siblings, boundaries})` → `Array<number|'…'>`,
3320
- the pure page-window calculation, usable on its own.
3888
+ the pure page-window calculation, and `fitPageSize({available, rowHeight, perRow, reserve, min,
3889
+ max})` → the fitted size (0 when nothing can be measured), both usable on their own.
3321
3890
  - **Semantics** — `<nav aria-label="Pagination">`; the current page carries `aria-current="page"`;
3322
3891
  previous/next are labelled icon buttons that go `disabled` at the ends; the ellipses are
3323
3892
  `aria-hidden` spans, not buttons.
@@ -3363,6 +3932,11 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
3363
3932
  `header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`,
3364
3933
  `moreLabel` (by default the `appSidebar.more` message), and `renderIcon(item, context)`. Icon values may also be names,
3365
3934
  nodes, components, or factories.
3935
+ - **Agents** — an item's `agent` (AgentAvatar options, or `true`) draws the destination as an
3936
+ agent: an `AgentAvatar` in place of its icon, in the tree, on the rail and in flyouts, sized by
3937
+ the icon slot, `name` defaulting to the label. It is drawn at rest and flat, at the small level of
3938
+ detail whatever the slot measures — the activity is the face and the dot, never motion — and the activity's word joins the control's accessible name, with the
3939
+ count when there is one ("Ledger, Needs you (1)"). Redraw with `setItems()` when it changes.
3366
3940
  - **Row actions** — `actions` on a destination lists its commands: `{icon, label, onSelect(item),
3367
3941
  disabled?, danger?}` descriptors or nodes, laid out as TreeView's `rowActions` (two at most, the
3368
3942
  rest in a "More actions" menu). They rest out of sight over the end of the row, which keeps room
@@ -3461,7 +4035,10 @@ bar.setBadge('mail', 8);
3461
4035
  pinned, unpinned ones are under "All modules" only), `group` (the catalogue heading), and
3462
4036
  `description`. Children are the module's menu. A `section` at the top level heads its modules:
3463
4037
  a caption over them while names are printed beside the tiles, a short rule between groups on an
3464
- icon strip or bar, and their group in the catalogue.
4038
+ icon strip or bar, and their group in the catalogue. `agent` (AgentAvatar options, or `true`)
4039
+ draws the module as an agent: its `AgentAvatar` at the size of the tile in place of the tile,
4040
+ whatever the `appearance`, at rest, with the activity's word in the tile's accessible name
4041
+ ("Ledger, Needs you (2)"); `tone` and `color` then do not apply.
3465
4042
  - **Options** — `items`, `active` (a module or anything in a module's menu),
3466
4043
  `orientation: 'vertical'|'horizontal'`, `side`, `appearance: 'tint'|'solid'|'plain'` (the glyph
3467
4044
  on a tint of the module colour; the solid identity tile; monochrome glyphs),
@@ -3613,7 +4190,9 @@ agents' answers as they stream (`BlockView` with a `SourceList`), the steps a ru
3613
4190
  its version (`versions[]`); a `trace`'s `title` replaces its summary (a plan:
3614
4191
  "Plan · 5 of 6 done"); a `notice` is named by its own text and may carry `action: {id, label}`
3615
4192
  (`action {item, action: id}`); an author with an `icon` is drawn as a tinted tile instead of
3616
- initials (round for a `model`; `tone: 'accent'` for the accent's quiet fill); an `approval`'s
4193
+ initials (round for a `model`; `tone: 'accent'` for the accent's quiet fill); an agent author with
4194
+ `face` (`{seed, tone, body, eyes, material}` or `true`) is drawn as its generated `AgentAvatar`,
4195
+ with the author's `activity` — `face` wins over `icon`; an `approval`'s
3617
4196
  `editedKeys` say which values the person changed. `setArtifactState()` is remembered for answers
3618
4197
  drawn later; `sourceIcons` is handed to every `SourceList`.
3619
4198
  - **Placeholders** — a `{type: 'zx-placeholder', id, author?, lines?}` item stands for something
@@ -3671,7 +4250,9 @@ agents' answers as they stream (`BlockView` with a `SourceList`), the steps a ru
3671
4250
  Draws a server's AI SDK UI message stream (the response header `x-vercel-ai-ui-message-stream: v1`;
3672
4251
  `UI_MESSAGE_STREAM_VERSION` is the version implemented) in a thread. The application keeps the
3673
4252
  request, the event source, retries, and authentication: it strips the `data: ` framing and the
3674
- `[DONE]` sentinel, and hands each parsed part to `handle()`.
4253
+ `[DONE]` sentinel, and hands each parsed part to `handle()`. Authors are drawn from the thread's own
4254
+ `authors`: an agent given a `face` there is drawn as its AgentAvatar in every item the stream
4255
+ writes, and the stream can never set or change one.
3675
4256
 
3676
4257
  ```js
3677
4258
  const stream = connectUiMessageStream(thread, {
@@ -3765,7 +4346,9 @@ for await (const part of parsedParts(response)) stream.handle(part);
3765
4346
 
3766
4347
  `connectAgUi()` draws an [AG-UI](https://docs.ag-ui.com) event stream in a thread. It implements
3767
4348
  AG-UI `AG_UI_VERSION` (`'1.0'`). It takes events already parsed — the application keeps the
3768
- transport, retries and authentication — and returns `{handle(event), state(), destroy()}`.
4349
+ transport, retries and authentication — and returns `{handle(event), state(), destroy()}`. As with
4350
+ the UI message stream, faces come from the thread's own `authors`, never from the events, and a
4351
+ `runStatus` given an `agent` keeps it while the run's states change its expression.
3769
4352
 
3770
4353
  ```js
3771
4354
  const status = new RunStatus(null, { compact: true });
@@ -3863,7 +4446,9 @@ in `src/components/surface/catalog.js` and `validate.js`, importable on a server
3863
4446
  `catalog` (a narrowed catalog; the full one by default), `token: null` (the application's opaque
3864
4447
  string, at most 512 characters, copied unchanged into every reply), `reply: null` (a stored reply:
3865
4448
  the surface starts as its receipt), `labelledBy: null` (the id of a title shown by a host),
3866
- `chartAdapter: null` (draws `chart` nodes; without one a chart shows its data table), `msg`.
4449
+ `chartAdapter` (draws `chart` nodes: a shared `SvgChartAdapter` by default, offering each chart's
4450
+ data table behind a toggle; pass another adapter to draw with it, or `null` to draw none and show
4451
+ each chart's data table instead), `msg`.
3867
4452
  - **Methods** — `apply(op)`, `write(chunk)` (operation lines in chunks), `end()` (the stream is
3868
4453
  over), `getValues()`, `getErrors()`, `cancel(reason)`, `supersede()`, `focus()`, `toDocument()`,
3869
4454
  `getReply()`, `destroy()`.
@@ -3876,6 +4461,17 @@ in `src/components/surface/catalog.js` and `validate.js`, importable on a server
3876
4461
  disabled. A node that fails while drawing shows the same line beside the rest of the surface, and
3877
4462
  is reported as `draw-failed`. One operation costs what it touches: a `data` operation redraws only
3878
4463
  the nodes bound to the path it changed.
4464
+ - **Catalog and profiles** — every node in `CATALOG` carries `use` (one sentence: when to pick it)
4465
+ and `avoid` (one sentence naming the node or intent to use instead); the guide `surfacePrompt()`
4466
+ writes both under each node, and leaves out an `avoid` whose alternative the catalog lacks.
4467
+ `PROFILES` names four nested sets: `answer` (a `show` surface of `text`, `heading`, `list`,
4468
+ `callout`, `figures`, `table`, `stat`, `badge`, `chart`, `code`, `link`, `ref`, `empty`, `stack`,
4469
+ `columns` and `group`), `ask` (adds the `ask`, `choose` and `confirm` intents with `fields` and
4470
+ `choice`), `review` (adds the `review` intent with `diff`) and `full` (everything, also `quote`
4471
+ and `questionnaire`). `narrowCatalog(CATALOG, { profile })` starts from one, and `intents` and
4472
+ `nodes` narrow within it; `surfaceSchema()`, `surfaceTools()` and `surfacePrompt()` take the same
4473
+ `profile` option, and leaving it out keeps the whole catalog. Give the model the narrowest
4474
+ profile that does the job: `answer` costs well under half the prompt and tools of `full`.
3879
4475
  - **Limits** — 400 nodes, depth 12, 20,000 characters per string, 1,000 rows per table, 50 fields,
3880
4476
  64 choices, 8 actions, 1 MB of data, and 100,000 table cells across all tables, each `$data`
3881
4477
  binding counted where it is used. What is over a limit is dropped and reported, and the table
@@ -3999,8 +4595,10 @@ announces nothing itself; the thread the run belongs to announces its milestones
3999
4595
  sentence, text only), `steps: {done, total}|null`, `started`, `finished` and `waitingSince`
4000
4596
  (local ISO date-time strings or `Date`s), `workMs` (milliseconds worked; the row shows only when
4001
4597
  it is a number), `tokens: [in, out]|number|null` (the pair, or the total as one number),
4002
- `tokenBudget: number|null`, `cost: {amount, budget?, currency}|null`, `model`,
4003
- `actions: [{label, kind?, icon?, onclick?}]`, `ticking: true`, `compact: false|true|'icon'`,
4598
+ `tokenBudget: number|null`, `cost: {amount, budget?, currency}|null`, `model`, `agent`
4599
+ (`{seed?, name?, tone?, body?, eyes?, material?}` or `true`: the agent's face before the state,
4600
+ working while it runs, looking up while it waits, blocked when blocked or failed, at rest
4601
+ otherwise; the compact pill leaves it out), `actions: [{label, kind?, icon?, onclick?}]`, `ticking: true`, `compact: false|true|'icon'`,
4004
4602
  `now: (() => Date)|null`, `locale`, and `msg` (the `agent.status.*` words and the `runStatus.*`
4005
4603
  labels).
4006
4604
  - **Rendering** — the state line; the summary; a `role="progressbar"` whose `aria-valuetext` reads
@@ -4048,7 +4646,8 @@ the application, which owns the conversation and the transport.
4048
4646
  `queue: false`, `queueLimit: 10` (see Queue),
4049
4647
  `disabled: false`, `attachments: false`, `accept: ''` (the `<input type="file">` syntax),
4050
4648
  `maxFiles: 10`, `mentions: null|{trigger: '@', items}` where `items` is `[{id, label,
4051
- description?, icon?}]` or `(query) => items | Promise<items>`, `commands: null|LauncherItem[]`,
4649
+ description?, icon?, agent?}]` (`agent`: AgentAvatar options or `true` draws the item as its still
4650
+ face instead of the icon, with an activity's word in the option's name) or `(query) => items | Promise<items>`, `commands: null|LauncherItem[]`,
4052
4651
  `tools: []` (`[{id, label, icon, pressed?, expanded?, controls?, disabled?}]` — `pressed` makes a
4053
4652
  toggle, `expanded`/`controls` a disclosure; see Tools), `icons: {}` (`attach`, `commands` glyphs),
4054
4653
  `context: [{id, label,
@@ -4186,7 +4785,9 @@ into the record of what was decided, by whom, and when. The card never acts on i
4186
4785
  the answer, and the application carries it out.
4187
4786
 
4188
4787
  - **Options** — `title`, `description`, `icon: null` (an icon name for the tinted tile), `tone:
4189
- 'blue'` (`slate|blue|teal|green|amber|orange|red|pink|violet`), `headingLevel: 3`,
4788
+ 'blue'` (`slate|blue|teal|green|amber|orange|red|pink|violet`), `agent: null` (the asking
4789
+ agent's AgentAvatar face in place of the tile — `{seed?, name?, tone?, body?, eyes?, material?}`
4790
+ or `true`; it looks up at you while the request waits and rests once answered), `headingLevel: 3`,
4190
4791
  `status: 'pending'|'approved'|'rejected'|'expired'`, `details: Node|Block[]|null` (recipients,
4191
4792
  amounts, records), `preview: {label, content: Node|Block[]}|null` (behind a disclosure; `blocks`
4192
4793
  is accepted for `content`, as the thread model spells it), `fields: Record<string,
@@ -4205,7 +4806,7 @@ the answer, and the application carries it out.
4205
4806
  the values. `changed` names the fields this save changed. `editedKeys` is the union the card
4206
4807
  will list (null when it lists every field), so the application can store it with the record.
4207
4808
  Prevent an answer to refuse or defer it, then settle the card with `setStatus()`.
4208
- - **Methods** — `update(partial)` changes any of `title`, `description`, `icon`, `tone`,
4809
+ - **Methods** — `update(partial)` changes any of `title`, `description`, `icon`, `tone`, `agent`,
4209
4810
  `details`, `preview`, `fields`, `values`, `confirmText`, `reason`, `edited`, `editedKeys` in
4210
4811
  place (see below); `setStatus(status, {by?, at?, reason?})` (emits nothing; `at` defaults to
4211
4812
  now; closes any of the card's open dialogs), `getStatus()`, `getValues()` (a copy, edits
@@ -4299,7 +4900,8 @@ only when the application calls `setSteps()`, `upsert()` or `setLabel()`.
4299
4900
  otherwise) and the result or the error, each in a focusable `<pre>` with a copy button. A
4300
4901
  `handoff` step reads "Finance agent handed over to Collections agent" beside both authors'
4301
4902
  avatars joined by a dotted line — round for a `person`, a rounded square for an agent or a
4302
- model — and its own label moves to the meta line.
4903
+ model, and an agent author with `face` as its still `AgentAvatar` — and its own label moves to
4904
+ the meta line.
4303
4905
  - **Accessibility** — the summary and every step with content follow the APG Disclosure pattern
4304
4906
  (`aria-expanded`, `aria-controls`); in a `selectable` trace a step without content is a plain
4305
4907
  `<button>`. A step's links are buttons beside its row, never inside it, so no control holds
@@ -4348,7 +4950,9 @@ a thumbnail, or any other remote resource.
4348
4950
  ### Core helpers
4349
4951
 
4350
4952
  - **Component** — the base class: `on`/`off`/`once`/`emit`, `listen`, `toElement`, `msg`,
4351
- `destroy`, and the static `Component.from(el)`. `msg(key, ...args)` always returns text: the
4953
+ `destroy`, and the static `Component.from(el)`. Options are merged over the class's
4954
+ `static defaults`; a key passed as `undefined` keeps its default (also inside `msg`), `null`
4955
+ overrides it. `msg(key, ...args)` always returns text: the
4352
4956
  instance's `msg` option (a `{[lang]: {…}}` table for the active language, then flat keys), else
4353
4957
  the host translator, else the class's built-in `msg` defaults, else the default English
4354
4958
  catalogue, and only then the key itself; `%1`, `%2`, … are filled from `args`.
@@ -4362,7 +4966,7 @@ a thumbnail, or any other remote resource.
4362
4966
  newest-first handler registry. Existing `DOM.on/remEvt/fireEvt` methods can delegate to this
4363
4967
  triad. Zx never installs globals or alters DOM prototypes; applications decide whether to expose
4364
4968
  these functions globally or compose them into their own UI and routing layer.
4365
- - **Icons** — `icon(name, {size, label})`, `icons`, and `ICON_SIZE` (one size per role); see the
4969
+ - **Icons** — `icon(name, {size, label})`, `icons`, `iconAliases`, `iconNames()`, and `ICON_SIZE` (one size per role); see the
4366
4970
  Icons section — bundled inline SVG by default, Font Awesome after an opt-in.
4367
4971
  - **Positioning** — `position(anchor, floating, {placement, offset, flip, matchWidth})` →
4368
4972
  `{update, destroy}`. It anchors a manual popover with CSS anchor positioning where the browser
@@ -4405,7 +5009,12 @@ registerIcons({ anchor: ['0 0 24 24', 'M12 6v16…', 'stroke'] }); // an outlin
4405
5009
  domains configured in the Font Awesome account.
4406
5010
  - `useFontAwesome(opts)` / `useBuiltinIcons()` / `configureIcons(opts)` / `getIconConfig()` —
4407
5011
  switch or read the renderer without touching the network.
4408
- - `iconNames()` lists every inline glyph, bundled and registered; `icons` is the bundled table.
5012
+ - `iconNames()` lists every name `icon()` renders as an inline glyph: the bundled set, the glyphs
5013
+ added with `registerIcons()`, and the aliases. A bare name that is not in the list renders the
5014
+ placeholder. `icons` is the bundled table and `iconAliases` the frozen `alias → bundled name`
5015
+ table. An alias is listed beside the glyph it draws, so the list holds more names than glyphs;
5016
+ for one entry per glyph, as in an icon gallery, leave them out:
5017
+ `iconNames().filter((name) => !Object.hasOwn(iconAliases, name))`.
4409
5018
  - `registerIcons(map)` adds or replaces inline glyphs. `[viewBox, path]` is a filled shape — the
4410
5019
  form Font Awesome path data comes in. `[viewBox, path, 'stroke']` is an outline drawn with the
4411
5020
  bundled pen; its stroke scales with the view box, so a 24-unit outline set such as Lucide renders
@@ -4423,6 +5032,10 @@ is how a state such as a set star or a liked heart is shown without a second gly
4423
5032
  **Names decide their own renderer.** A bare name (`'check'`) follows the active provider, and the
4424
5033
  built-in names are translated to their Font Awesome counterparts (`x` → `fa-xmark`, `search` →
4425
5034
  `fa-magnifying-glass`, `warning` → `fa-triangle-exclamation`, …), so component code never changes.
5035
+ A bare name may also be an alias, under either renderer: `archive` → `box-archive`, `edit` →
5036
+ `pen-to-square`, `settings` → `gear`, `clear` → `x`, `checked` → `check`, `question` → `info`,
5037
+ `range` → `filter`, `fields` → `list`, `grid` → `table-cells-large`. A glyph an application
5038
+ registered under the alias name itself wins over the alias, which is also how an alias is changed.
4426
5039
  Prefixes override: `'fa:user'`, `'fas:user'`/`'regular:user'`/`'duotone:user'`/`'thin:user'`,
4427
5040
  `'kit:zeyos-notes'` (custom kit icons), `'builtin:check'` (force the inline SVG). A literal class
4428
5041
  list — `'fa-sharp fa-solid fa-user'` — is used verbatim. Unknown names under Font Awesome are
@@ -4954,7 +5567,10 @@ in component CSS.
4954
5567
  properties for restyling one component without touching its internals. Each falls back to the
4955
5568
  semantic token it replaces, so setting none of them changes nothing:
4956
5569
  `--zx-table-header-bg`, `--zx-table-row-hover-bg`, `--zx-table-row-selected-bg`,
4957
- `--zx-table-border-color`, `--zx-button-radius`, `--zx-panel-header-bg`.
5570
+ `--zx-table-border-color`, `--zx-table-pin-bg` (the opaque base of pinned columns; the header
5571
+ background unless set), `--zx-button-radius`, `--zx-panel-header-bg`, `--zx-message-offset`
5572
+ (the distance of floating messages from the viewport edge; `--zx-space-4` unless set).
5573
+ `--zx-chart-min-block-size` is public as well, with a fixed 220px default rather than a token.
4958
5574
  Reach for the least specific override that works: a global semantic token first, one of these
4959
5575
  second, an internal selector never. Component CSS declares many other `--zx-<component>-*`
4960
5576
  properties — those are internal geometry, not API, and will change without notice.