@zeyos/zx 5.7.1 → 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 (326) hide show
  1. package/CHANGELOG.md +296 -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 +19 -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 +13 -2
  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 +11 -0
  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 +7 -0
  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 +18 -4
  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/drag-axis.d.ts +10 -5
  61. package/dist/types/core/export.d.ts +2 -2
  62. package/dist/types/core/format.d.ts +3 -1
  63. package/dist/types/core/icons.d.ts +36 -3
  64. package/dist/types/core/keyboard.d.ts +7 -3
  65. package/dist/types/core/messages.d.ts +3 -0
  66. package/dist/types/core/storage.d.ts +4 -3
  67. package/dist/types/core/util.d.ts +3 -1
  68. package/dist/types/elements/define.d.ts +5 -2
  69. package/dist/types/index.d.ts +6 -4
  70. package/dist/types/internal/agent-model.d.ts +99 -0
  71. package/dist/types/internal/app-rail.d.ts +37 -2
  72. package/dist/types/internal/collections.d.ts +18 -0
  73. package/dist/types/internal/menu-items.d.ts +27 -0
  74. package/dist/types/internal/overlay-content.d.ts +23 -0
  75. package/dist/types/internal/presence-loop.d.ts +5 -2
  76. package/dist/types/locales/index.d.ts +3 -0
  77. package/dist/types/zeyos/calendar.d.ts +43 -7
  78. package/dist/types/zeyos/connect.d.ts +4 -0
  79. package/dist/types/zeyos/form.d.ts +13 -5
  80. package/dist/types/zeyos/select.d.ts +5 -2
  81. package/dist/types/zeyos/table.d.ts +16 -8
  82. package/dist/types/zeyos/view.d.ts +2 -1
  83. package/dist/zx-zeyos.esm.js +2998 -451
  84. package/dist/zx-zeyos.esm.min.js +4 -4
  85. package/dist/zx.core.css +4 -0
  86. package/dist/zx.core.min.css +1 -1
  87. package/dist/zx.css +948 -48
  88. package/dist/zx.esm.js +7432 -3408
  89. package/dist/zx.esm.min.js +26 -26
  90. package/dist/zx.global.js +7432 -3408
  91. package/dist/zx.global.min.js +26 -26
  92. package/dist/zx.layered.css +950 -48
  93. package/dist/zx.layered.min.css +1 -1
  94. package/dist/zx.min.css +1 -1
  95. package/docs/agent-catalog.json +159 -1
  96. package/docs/agent-surfaces.md +21 -21
  97. package/docs/api.json +3122 -528
  98. package/docs/components/account-menu.md +24 -0
  99. package/docs/components/activity-item.md +23 -0
  100. package/docs/components/activity-list.md +28 -0
  101. package/docs/components/agent-avatar.md +59 -0
  102. package/docs/components/agent-thread.md +275 -0
  103. package/docs/components/app-icon.md +36 -0
  104. package/docs/components/app-sidebar.md +92 -0
  105. package/docs/components/approval-card.md +71 -0
  106. package/docs/components/aurora.md +34 -0
  107. package/docs/components/avatar.md +37 -0
  108. package/docs/components/badge.md +36 -0
  109. package/docs/components/block-view.md +34 -0
  110. package/docs/components/breadcrumb.md +20 -0
  111. package/docs/components/button.md +23 -0
  112. package/docs/components/calendar.md +68 -0
  113. package/docs/components/card-view.md +73 -0
  114. package/docs/components/card.md +25 -0
  115. package/docs/components/chart.md +109 -0
  116. package/docs/components/check-button.md +16 -0
  117. package/docs/components/checklist.md +19 -0
  118. package/docs/components/code-editor.md +38 -0
  119. package/docs/components/composer.md +107 -0
  120. package/docs/components/context-menu.md +32 -0
  121. package/docs/components/copy.md +37 -0
  122. package/docs/components/data-filter.md +16 -0
  123. package/docs/components/date-picker.md +31 -0
  124. package/docs/components/date-range.md +21 -0
  125. package/docs/components/datebox.md +31 -0
  126. package/docs/components/dialog.md +25 -0
  127. package/docs/components/dock.md +57 -0
  128. package/docs/components/dropdown.md +39 -0
  129. package/docs/components/elements.md +63 -0
  130. package/docs/components/empty-state.md +17 -0
  131. package/docs/components/entity-ref.md +26 -0
  132. package/docs/components/field-upload.md +18 -0
  133. package/docs/components/file-item.md +27 -0
  134. package/docs/components/file-list.md +23 -0
  135. package/docs/components/filter-panel.md +45 -0
  136. package/docs/components/filter.md +47 -0
  137. package/docs/components/finder.md +25 -0
  138. package/docs/components/form-widgets.md +42 -0
  139. package/docs/components/form.md +80 -0
  140. package/docs/components/grid.md +26 -0
  141. package/docs/components/groupbox.md +11 -0
  142. package/docs/components/helpers.md +359 -0
  143. package/docs/components/icons.md +87 -0
  144. package/docs/components/index.md +99 -0
  145. package/docs/components/kanban-view.md +42 -0
  146. package/docs/components/kbd.md +23 -0
  147. package/docs/components/kernel.md +41 -0
  148. package/docs/components/launcher.md +66 -0
  149. package/docs/components/layout.md +33 -0
  150. package/docs/components/list-toolbar.md +38 -0
  151. package/docs/components/loading.md +48 -0
  152. package/docs/components/menu-button.md +47 -0
  153. package/docs/components/message.md +76 -0
  154. package/docs/components/modal.md +27 -0
  155. package/docs/components/module-bar.md +71 -0
  156. package/docs/components/multi-value-editor.md +16 -0
  157. package/docs/components/navigation-bar.md +22 -0
  158. package/docs/components/number-field.md +34 -0
  159. package/docs/components/pagination.md +73 -0
  160. package/docs/components/panel.md +28 -0
  161. package/docs/components/prompt-starters.md +40 -0
  162. package/docs/components/prose.md +38 -0
  163. package/docs/components/questionnaire.md +115 -0
  164. package/docs/components/rating.md +19 -0
  165. package/docs/components/run-status.md +50 -0
  166. package/docs/components/run-trace.md +72 -0
  167. package/docs/components/search.md +11 -0
  168. package/docs/components/select.md +129 -0
  169. package/docs/components/sheet-stack.md +39 -0
  170. package/docs/components/sheet.md +77 -0
  171. package/docs/components/skeleton.md +27 -0
  172. package/docs/components/slider.md +29 -0
  173. package/docs/components/sort-control.md +21 -0
  174. package/docs/components/source-list.md +30 -0
  175. package/docs/components/split-view.md +12 -0
  176. package/docs/components/stat-tile.md +49 -0
  177. package/docs/components/stepper.md +27 -0
  178. package/docs/components/surface.md +152 -0
  179. package/docs/components/tabbox.md +33 -0
  180. package/docs/components/table-view.md +43 -0
  181. package/docs/components/table.md +232 -0
  182. package/docs/components/tag-picker.md +39 -0
  183. package/docs/components/timebox.md +16 -0
  184. package/docs/components/toggle.md +21 -0
  185. package/docs/components/tokens.md +82 -0
  186. package/docs/components/toolbar.md +26 -0
  187. package/docs/components/tooltip.md +16 -0
  188. package/docs/components/tree.md +48 -0
  189. package/docs/components/truncate.md +21 -0
  190. package/docs/components/value-list.md +14 -0
  191. package/docs/components/view-settings.md +56 -0
  192. package/docs/components/workspace-switcher.md +42 -0
  193. package/docs/components/zeyos.md +196 -0
  194. package/docs/llms-small.txt +299 -0
  195. package/docs/llms.md +697 -100
  196. package/docs/llms.txt +46 -19
  197. package/package.json +9 -4
  198. package/src/components/activity-item/activity-item.js +21 -2
  199. package/src/components/agent-avatar/agent-avatar.css +195 -0
  200. package/src/components/agent-avatar/agent-avatar.js +333 -0
  201. package/src/components/agent-avatar/agent-face.js +292 -0
  202. package/src/components/agent-thread/ag-ui.js +44 -11
  203. package/src/components/agent-thread/agent-thread.js +103 -11
  204. package/src/components/agent-thread/ui-message-stream.js +3 -1
  205. package/src/components/app-rail/app-rail.css +5 -0
  206. package/src/components/app-sidebar/app-sidebar.css +3 -0
  207. package/src/components/app-sidebar/app-sidebar.js +4 -3
  208. package/src/components/approval-card/approval-card.css +6 -0
  209. package/src/components/approval-card/approval-card.js +55 -7
  210. package/src/components/aurora/aurora.css +149 -14
  211. package/src/components/aurora/aurora.js +49 -6
  212. package/src/components/calendar/calendar.css +6 -2
  213. package/src/components/calendar/calendar.js +127 -47
  214. package/src/components/card-view/card-view.js +5 -6
  215. package/src/components/chart/chart.css +159 -1
  216. package/src/components/chart/chart.js +450 -62
  217. package/src/components/chart/color.js +297 -0
  218. package/src/components/chart/svg-adapter.js +576 -0
  219. package/src/components/chart/svg-geometry.js +323 -0
  220. package/src/components/check-button/check-button.js +3 -18
  221. package/src/components/checklist/checklist.js +46 -17
  222. package/src/components/checklist/field-adapter.js +4 -1
  223. package/src/components/code-editor/code-editor.css +33 -0
  224. package/src/components/code-editor/code-editor.js +97 -8
  225. package/src/components/code-editor/field-adapter.js +3 -0
  226. package/src/components/composer/composer.css +3 -0
  227. package/src/components/composer/composer.js +100 -22
  228. package/src/components/context-menu/context-menu.js +41 -5
  229. package/src/components/copy/copy-button.js +9 -1
  230. package/src/components/copy/copy-input.js +5 -0
  231. package/src/components/data-filter/filter-core.js +0 -1
  232. package/src/components/date-picker/date-picker.css +8 -0
  233. package/src/components/date-picker/date-picker.js +47 -8
  234. package/src/components/date-picker/date-range-picker.js +1 -1
  235. package/src/components/date-picker/month-picker.js +19 -3
  236. package/src/components/date-picker/time-picker.js +54 -19
  237. package/src/components/datebox/date-range-box.js +7 -3
  238. package/src/components/datebox/datebox.js +32 -6
  239. package/src/components/dialog/dialog.css +6 -0
  240. package/src/components/dialog/dialog.js +22 -30
  241. package/src/components/dropdown/dropdown.js +1 -18
  242. package/src/components/empty-state/empty-state.js +21 -2
  243. package/src/components/field/field.js +19 -3
  244. package/src/components/fieldset/fieldset.js +3 -1
  245. package/src/components/filter/filter.js +9 -0
  246. package/src/components/form/form.js +19 -2
  247. package/src/components/kanban-view/kanban-card.js +15 -2
  248. package/src/components/kanban-view/kanban-view.css +21 -0
  249. package/src/components/kanban-view/kanban-view.js +29 -16
  250. package/src/components/launcher/launcher.css +14 -0
  251. package/src/components/launcher/launcher.js +54 -9
  252. package/src/components/master-panel/master-panel.js +24 -22
  253. package/src/components/menu-button/menu-button.js +26 -4
  254. package/src/components/message/message.css +228 -29
  255. package/src/components/message/message.js +664 -30
  256. package/src/components/modal/modal.js +70 -25
  257. package/src/components/modal/native-dialog.js +91 -0
  258. package/src/components/module-bar/module-bar.css +3 -0
  259. package/src/components/module-bar/module-bar.js +17 -4
  260. package/src/components/multi-value-editor/multi-value-editor.css +7 -2
  261. package/src/components/multi-value-editor/multi-value-editor.js +3 -2
  262. package/src/components/navigation-bar/navigation-bar.js +13 -1
  263. package/src/components/number-field/field-adapter.js +3 -0
  264. package/src/components/number-field/number-field.js +2 -1
  265. package/src/components/pagination/pagination.css +26 -2
  266. package/src/components/pagination/pagination.js +551 -65
  267. package/src/components/prose/prose.js +7 -1
  268. package/src/components/rating/field-adapter.js +3 -0
  269. package/src/components/run-status/run-status.js +43 -3
  270. package/src/components/run-trace/run-trace.js +15 -7
  271. package/src/components/search/search.js +3 -18
  272. package/src/components/select/field-adapter.js +8 -1
  273. package/src/components/select/select.js +68 -13
  274. package/src/components/sheet/sheet.js +27 -8
  275. package/src/components/slider/field-adapter.js +3 -0
  276. package/src/components/slider/slider.js +4 -6
  277. package/src/components/stat-tile/stat-tile.js +24 -9
  278. package/src/components/stepper/stepper.css +15 -0
  279. package/src/components/stepper/stepper.js +34 -2
  280. package/src/components/surface/catalog.js +185 -28
  281. package/src/components/surface/surface.js +10 -5
  282. package/src/components/tabbox/tabbox.js +13 -1
  283. package/src/components/table/table.css +160 -2
  284. package/src/components/table/table.js +479 -52
  285. package/src/components/table/window.js +46 -4
  286. package/src/components/table-view/table-view.js +1 -10
  287. package/src/components/tag-picker/field-adapter.js +3 -0
  288. package/src/components/tag-picker/tag-picker.js +2 -0
  289. package/src/components/timebox/field-adapter.js +3 -0
  290. package/src/components/toggle/toggle.js +51 -27
  291. package/src/components/tooltip/tooltip.js +21 -14
  292. package/src/components/tree/tree.js +87 -14
  293. package/src/components/truncate/truncate.js +21 -5
  294. package/src/components/value-list/value-list.js +37 -9
  295. package/src/components/view-settings/view-settings.js +1 -5
  296. package/src/core/component.js +34 -2
  297. package/src/core/date.js +5 -4
  298. package/src/core/drag-axis.js +24 -7
  299. package/src/core/export.js +4 -4
  300. package/src/core/fontawesome.js +34 -3
  301. package/src/core/format.js +3 -1
  302. package/src/core/http.js +23 -11
  303. package/src/core/icons.js +51 -10
  304. package/src/core/keyboard.js +83 -9
  305. package/src/core/messages.js +3 -0
  306. package/src/core/position.js +2 -2
  307. package/src/core/storage.js +80 -31
  308. package/src/core/util.js +16 -5
  309. package/src/elements/define.js +82 -47
  310. package/src/elements/kit.js +46 -35
  311. package/src/index.js +8 -4
  312. package/src/internal/agent-model.js +152 -0
  313. package/src/internal/app-rail.js +53 -2
  314. package/src/internal/collections.js +25 -0
  315. package/src/internal/menu-items.js +59 -0
  316. package/src/internal/overlay-content.js +35 -0
  317. package/src/internal/presence-loop.js +61 -14
  318. package/src/locales/de.js +3 -0
  319. package/src/zeyos/calendar.js +81 -19
  320. package/src/zeyos/connect.js +5 -1
  321. package/src/zeyos/form.js +29 -10
  322. package/src/zeyos/select.js +36 -12
  323. package/src/zeyos/table.js +43 -11
  324. package/src/zeyos/view.js +2 -1
  325. package/styles/tokens/semantic.css +7 -1
  326. package/styles/zx.css +1 -0
@@ -0,0 +1,152 @@
1
+ # Surface — `new Surface(target, options)` / `openSurface()` / `elicit()` / `surfaceText()`
2
+
3
+ Interface an agent composes as JSON — a rich answer, or a dialog asking the person something — validated and drawn with the library’s own components.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/surface · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Interface an agent composes as JSON — a rich answer, or a dialog asking the person something —
8
+ validated and drawn with the library's own components. A surface declares one `intent`, which fixes
9
+ its frame, default actions and reply, and composes its body from catalog nodes laid out by id. The
10
+ format, the node reference and the rules a model reads are in `docs/agent-surfaces.md`; the catalog
11
+ functions (`narrowCatalog`, `surfaceSchema`, `surfaceTools`, `surfacePrompt`) and the validator are
12
+ in `src/components/surface/catalog.js` and `validate.js`, importable on a server.
13
+
14
+ - **Options** — `document` (a whole surface; leave it out to stream), `policy`, `resolve: {ref,
15
+ link, asset, entities}`, `authors`, `userInitiated: false`, `headingLevel: 3`, `locale`,
16
+ `catalog` (a narrowed catalog; the full one by default), `token: null` (the application's opaque
17
+ string, at most 512 characters, copied unchanged into every reply), `reply: null` (a stored reply:
18
+ the surface starts as its receipt), `labelledBy: null` (the id of a title shown by a host),
19
+ `chartAdapter` (draws `chart` nodes: a shared `SvgChartAdapter` by default, offering each chart's
20
+ data table behind a toggle; pass another adapter to draw with it, or `null` to draw none and show
21
+ each chart's data table instead), `msg`.
22
+ - **Methods** — `apply(op)`, `write(chunk)` (operation lines in chunks), `end()` (the stream is
23
+ over), `getValues()`, `getErrors()`, `cancel(reason)`, `supersede()`, `focus()`, `toDocument()`,
24
+ `getReply()`, `destroy()`.
25
+ - **Events** — `reply {reply}` exactly once, `error {errors}` each time new problems are found,
26
+ `change {name, value}`, `ready` at the first drawn state, `end`.
27
+ - **Streaming** — every line is validated before it is drawn. A child that has not arrived is a
28
+ skeleton line, and every action but Cancel stays disabled until the surface's `end`. What is
29
+ invalid is dropped and reported; an unknown node, or one outside a narrowed catalog, draws "This
30
+ part could not be shown". A surface whose stream ends without its `end` keeps its actions
31
+ disabled. A node that fails while drawing shows the same line beside the rest of the surface, and
32
+ is reported as `draw-failed`. One operation costs what it touches: a `data` operation redraws only
33
+ the nodes bound to the path it changed.
34
+ - **Catalog and profiles** — every node in `CATALOG` carries `use` (one sentence: when to pick it)
35
+ and `avoid` (one sentence naming the node or intent to use instead); the guide `surfacePrompt()`
36
+ writes both under each node, and leaves out an `avoid` whose alternative the catalog lacks.
37
+ `PROFILES` names four nested sets: `answer` (a `show` surface of `text`, `heading`, `list`,
38
+ `callout`, `figures`, `table`, `stat`, `badge`, `chart`, `code`, `link`, `ref`, `empty`, `stack`,
39
+ `columns` and `group`), `ask` (adds the `ask`, `choose` and `confirm` intents with `fields` and
40
+ `choice`), `review` (adds the `review` intent with `diff`) and `full` (everything, also `quote`
41
+ and `questionnaire`). `narrowCatalog(CATALOG, { profile })` starts from one, and `intents` and
42
+ `nodes` narrow within it; `surfaceSchema()`, `surfaceTools()` and `surfacePrompt()` take the same
43
+ `profile` option, and leaving it out keeps the whole catalog. Give the model the narrowest
44
+ profile that does the job: `answer` costs well under half the prompt and tools of `full`.
45
+ - **Limits** — 400 nodes, depth 12, 20,000 characters per string, 1,000 rows per table, 50 fields,
46
+ 64 choices, 8 actions, 1 MB of data, and 100,000 table cells across all tables, each `$data`
47
+ binding counted where it is used. What is over a limit is dropped and reported, and the table
48
+ budget holds while a surface streams; rows past it draw the fallback.
49
+ - **Actions** — the intent's defaults (`submit`, `confirm`, `approve`/`reject`) or the surface's own,
50
+ plus Cancel for `ask`, `choose`, `confirm` and `questionnaire`, and for a `review` left without
51
+ its `reject`. The ids `cancel` and `dismiss` are reserved: an action using one is dropped and
52
+ reported, as is any action of a `questionnaire`'s own. Escape closes whatever waits for an answer
53
+ (`cancel`, or `dismiss` for a `show` surface with actions), except while it closes something
54
+ inside the surface (an open picker, an expanded list) or another handler took it. The answering
55
+ defaults (`submit`, `confirm`, `approve`) and an own action with `kind: 'primary'` check the
56
+ visible inputs first, move focus to the first invalid one, and send the values; any other own
57
+ action replies at once with `values: {}`. With several primary actions the one pressed answers,
58
+ and Enter in a field presses the first. A single `choice` must be picked before an answering
59
+ action replies; a `multiple` one may be empty. A questionnaire's `next` that names a dropped step,
60
+ or can lead back to its own step, is dropped and reported.
61
+ - **Policy** — `policy(action, surface)` returns `'allow'`, `'confirm'` (a confirmation Dialog),
62
+ `'type-to-confirm'` (`Dialog.confirm({confirmText})`) or `'deny'` (the action is not drawn, and
63
+ the reply lists it under `removed`), or `{level, confirmText?, message?}`. Supply `confirmText`
64
+ for `type-to-confirm`: without it the person types the fixed word "confirm"
65
+ (`surface.typeToConfirm`), never text from the surface. A questionnaire's own Submit is put to the
66
+ policy up front, as `submit`; denied, it is hidden and reported. The policy is synchronous:
67
+ nothing waits for it, so a Promise denies, like a policy that throws. Anything else counts as
68
+ `confirm`. Nothing in a surface can lower it: `kind: 'danger'` is presentation only, and
69
+ confirmation keys in a surface are dropped.
70
+ - **Reply** — `{zx: 'reply/1', surface, action, key, values, confirmation, at, token?, removed?,
71
+ reason?}`. `key` is `<surface>#<action>`; `confirmation` is `clicked`, `typed` or `null`;
72
+ `reason` says why a closing reply (`cancel`, `dismiss`) was sent: `cancelled`, `escape`,
73
+ `closed`, `superseded`, `stopped`, `destroyed`, or the application's. Submit and every action
74
+ reply, and so do Cancel, Escape, `cancel()`, `supersede()` and destroying an unanswered surface
75
+ (`dismiss`), whatever happens while its receipt is drawn. When its run stops, the application
76
+ calls `surface.cancel('stopped')`. A surface
77
+ whose `begin` never validated still replies once: `surface` is the id it was given when that was
78
+ a valid id, `null` otherwise. A reply records what the page did; the server runs its policy again
79
+ before it acts.
80
+ - **Conditions** — a node's `visible` and a schema property's `x-zx.visible` are evaluated as values
81
+ change. A hidden input keeps what was typed, is not required, and is left out of `getValues()`
82
+ and the reply. A node that hides while it holds the focus hands it to the input whose value hid
83
+ it.
84
+ - **Receipt** — answered, the surface carries `data-state="answered"`: inputs become read-only
85
+ displays of what was answered, tables stay with their selected rows marked, and the actions give
86
+ way to a verdict line. A restored surface (`reply`) shows what that reply answered.
87
+ `surfaceText(document, reply)` gives the same receipt as plain text, with choice titles rather
88
+ than raw values and never a hidden input or step, whatever the reply carries.
89
+ - **Field types** — a schema property's `x-zx.field` draws through `Field`. The surface registers the
90
+ types it needs only where nothing draws them yet, so an adapter the application registered with
91
+ `Field.register()` stays.
92
+ - **Placement** — `openSurface(document, {placement, target, …})` resolves with the reply. A sheet
93
+ or a dialog the document asks for is honoured only with `userInitiated`; otherwise the surface goes
94
+ inline into `target`. Closing the sheet or dialog replies `cancel`. A document that cannot begin
95
+ rejects with a `TypeError` (its `errors` attached) before anything opens; given its `reply`, it
96
+ resolves with it at once. `signal` withdraws it: on abort the surface is cancelled with the reason
97
+ `stopped` and the promise resolves that reply — a sheet or dialog closes, an inline surface stays
98
+ as its receipt — and a signal already aborted resolves it without drawing anything. Removing an
99
+ inline `target` is not noticed: abort the signal or destroy the surface so the promise settles.
100
+ - **Elicitation** — `elicit({message, requestedSchema}, options)` draws an `ask` form in a Dialog,
101
+ or inline into `options.target`, and resolves `{action: 'accept', content}`, `{action: 'decline'}`
102
+ or `{action: 'cancel'}`. A schema outside the subset (a nested object, a pattern, …) rejects with
103
+ a `TypeError` naming what is unsupported. The message is drawn as plain text, never as markup;
104
+ the labels resolve through `msg` (by language, then flat), the host translator, then English.
105
+ `options.signal` withdraws the request: it resolves `cancel`.
106
+ - **MCP elicitation** — `elicitationHandler({serverName, authors?, target?, open?, msg?})` returns
107
+ `(params, {signal}?) => Promise<{action, content?}>` for an MCP client to install; `MCP_ELICITATION_VERSION`
108
+ (`'2026-07-28'`) names the revision it implements. Call it with the `params` of an
109
+ `elicitation/create` request, or of each `inputRequests` entry whose `method` is
110
+ `elicitation/create` in an `input_required` result, and send what it resolves back — in
111
+ `inputResponses` under the same key, with `requestState` echoed unchanged. Fields a mode does not
112
+ use, such as an `elicitationId`, are ignored. The byline says "Asked by <server>": the
113
+ `authors[serverName].name` when listed, else `serverName`, which is required. Abort `signal` when
114
+ the request is withdrawn (the server cancelled it, the call timed out, the session closed, or the
115
+ inline `target` was removed): the surface is cancelled, nothing opens, and it resolves `cancel`.
116
+ - Form mode, the default without `mode`, is `elicit()`; a schema outside the subset rejects with
117
+ its `TypeError`, so the client can answer the server with an error. Single and multiple choice
118
+ (`enum`, `oneOf`, `items.enum`, `items.anyOf`) and defaults are supported; the deprecated
119
+ `enumNames` is reported as unsupported.
120
+ - URL mode is a `confirm` surface that asks first: the server's message as plain text, the page's
121
+ host emphasised, its full address, a warning for an internationalised host, and no link. Nothing
122
+ is fetched or opened before the person agrees. Open page opens the address in a new tab with
123
+ `noopener` and `noreferrer`, inside the click, and resolves `{action: 'accept'}`; Decline
124
+ resolves `decline`; Cancel, Escape or closing the dialog resolves `cancel`. The address must be
125
+ an absolute lower-case `https://` URL without credentials, checked and normalised like a surface
126
+ link; anything else rejects with a `TypeError`. `open(url)` replaces the opener: it must open a
127
+ browsing context that cannot reach the application, and `false` or a throw answers `cancel`.
128
+
129
+ ```js
130
+ const answer = elicitationHandler({ serverName: 'Orders server' });
131
+ const inputResponses = {};
132
+ for (const [key, request] of Object.entries(result.inputRequests ?? {})) {
133
+ if (request.method === 'elicitation/create') inputResponses[key] = await answer(request.params);
134
+ }
135
+ await client.callTool({ ...call, inputResponses, requestState: result.requestState });
136
+ ```
137
+ - **Safety** — no string reaches the page as HTML. Records are drawn through `resolve.ref` as an
138
+ `EntityRef`; links are `https:` only, show their host, and pass `resolve.link`, which may refuse
139
+ them; nothing is loaded from an address the surface gives.
140
+ - **Accessibility** — a surface that asks is a `<form>` labelled by its title, any other a labelled
141
+ region; the title is at `headingLevel` and its `heading` nodes one and two below, up to h6; a chart offers its data table; the byline says
142
+ "Composed by <author>".
143
+
144
+ ```js
145
+ const surface = new Surface(null, {
146
+ document, // from the model's show_surface call
147
+ token: issuedToken,
148
+ policy: (action) => (action.tool === 'mail.send' ? 'confirm' : 'allow'),
149
+ resolve: { entities: ['company'], ref: (ref) => ({ id: ref.id, title: names[ref.id] }) },
150
+ onreply: ({ detail }) => sendToolResult(detail.reply)
151
+ });
152
+ ```
@@ -0,0 +1,33 @@
1
+ # Tabbox — APG tabs
2
+
3
+ Manual-activation tabs following the APG pattern: arrow keys move focus, Enter or Space selects, and panels can be built lazily.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/tabbox · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Four appearances, all square-cornered. `divided` (the default) sets flat blocks on a muted track,
8
+ split by hairline dividers, above a bordered panel, with the active block lifted onto the panel
9
+ surface. `bracket` outlines folder tabs that fuse into that same panel, the active tab bridging
10
+ the seam. `line` underlines the active tab in the text colour across a full-width rule, for page-
11
+ and section-level navigation. `segmented` renders a compact framed group with the active tab on
12
+ the neutral `--zx-color-bg-current` fill, so the row reads as one control inside a toolbar or card
13
+ header. The active tab is where you are, not a pick: every variant gives it the text colour and a
14
+ semibold label, and none uses the accent. Tab badges are neutral counts, not accent bubbles.
15
+
16
+ `divided` and `bracket` draw the panel box themselves; `line` and `segmented` leave the panel bare
17
+ for the surrounding layout to frame. The boxed variants read `--zx-tabbox-radius` (default `0px`)
18
+ from the component root, so `el.style.setProperty('--zx-tabbox-radius', 'var(--zx-radius-lg)')`
19
+ restores rounded corners without forking the stylesheet.
20
+
21
+ - **Options** — `tabs: [{ name, title, content, icon?, closable?, disabled? }]`, `active`,
22
+ `variant: 'divided'|'bracket'|'line'|'segmented'`, `keepAlive: true`, `label` (the tab list's
23
+ accessible name — give one whenever a page has more than one tab list).
24
+ - **Methods** — `addTab()`, `removeTab()`, `openTab(name)`, `getActive()`, `setTitle()`,
25
+ `setBadge(name, text|null)`, `enableTab()`/`disableTab()`.
26
+ - **Events** — `change {name, previous}` (preventable), `close {name}`.
27
+ - **Behaviour** — a `closable` tab renders a × that closes it on click, and `close` fires for that
28
+ gesture just as it does for Delete. `removeTab()` is the silent programmatic path. Closing the
29
+ active tab activates its neighbour through the usual `change` event, so a `preventDefault()` on
30
+ that change also vetoes the close.
31
+ - **Keyboard** — ArrowLeft/Right and Home/End move focus, Enter/Space activate, Delete closes a
32
+ closable tab. The × is a plain glyph rather than a nested button (buttons cannot nest), so
33
+ keyboard and screen-reader users close through Delete; focus lands on the neighbouring tab.
@@ -0,0 +1,43 @@
1
+ # TableView and the shared RecordView contract
2
+
3
+ A schema-friendly record view that composes the full Table: one field contract drives sorting, selection, editable cells, visibility, and stable column order.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/table-view · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ **`fieldControls` takes an object.** `true` and `false` behave as they always have; a
8
+ `{label, target}` object names the chooser's trigger and mounts the disclosure into a host
9
+ element — a list toolbar, say — instead of the view's own. `label` omitted resolves
10
+ `recordView.fields`. This is what lets a translated application use the chooser at all: the
11
+ trigger used to be the literal `Fields`, with no way to change it or move it. `TableView`,
12
+ `CardView`, and `KanbanView` all honour `target`.
13
+
14
+ **The chooser is public.** `getFieldControls()` returns the view's field chooser — the shared
15
+ disclosure, or for a `TableView` with `fieldControls: true` its Table's column chooser — and
16
+ `mountFieldControls(target)` moves it into a host element (`null` hands it back). The view keeps
17
+ owning it wherever it sits and removes it on `destroy()`; `ListToolbar.bind()` uses exactly this.
18
+ In the shared chooser the move buttons keep focus on the field they moved (or its other button once
19
+ one end disables), a polite live region announces "Name moved to position 2 of 5"
20
+ (`recordView.fieldMoved`), and Escape closes the disclosure and returns focus to its trigger.
21
+
22
+ `TableView` is the record-oriented entry point above the lower-level `Table`. It extends
23
+ `RecordView` and composes one complete `Table`, so editing, hierarchy, growing, row movement,
24
+ responsive stacking, loading, and advanced table events remain available through `getTable()`.
25
+
26
+ - **Shared fields** — every view accepts `fields: [{id,label,get?,render?,sortValue?,sortable?,
27
+ visible?,duplicate?,type?,view?}]`. Primitive rendered values become text; an explicit Node is
28
+ adopted. `field.view.table` carries Table-only column keys without changing CardView or KanbanView.
29
+ - **Shared options** — `data`, `recordId: 'ID'`, `sort`, `sortMode: 'local'|'server'`,
30
+ `selectable: false|'single'|'multi'`, `selection`, `fieldOrder`, `hiddenFields`,
31
+ `fieldControls: true`, and `emptyText`. At least one field remains visible.
32
+ - **Shared methods** — `setData()`, `addData()`, `updateRecord()`, `removeRecord()`, `getRecord()`,
33
+ `getData()`, field getters/order/visibility methods, `setSort()`/`getSort()`, selection methods,
34
+ `setLoading()`, `getViewState()`, `setViewState()`, `getFieldControls()`, and
35
+ `mountFieldControls(target)`.
36
+ - **Portable state** — `{version:1,fieldOrder,hiddenFields,sort}` is JSON-safe configuration only.
37
+ Records, selection, DOM nodes, rendered values, and callbacks are never serialized. A state from
38
+ one record view may seed another; unknown fields are ignored and new fields append.
39
+ - **TableView composition** — `table: {...}` forwards every advanced Table option, while shared
40
+ fields/data/id/sort/selection/visibility/order win on overlaps. `getTable()` returns the composed
41
+ instance. Row events become shared `recordclick`/`recorddblclick` details.
42
+ - **Events** — `recordclick`, `recorddblclick`, `datachange`, `selectionchange`, `sortchange`,
43
+ `fieldvisibilitychange`, `fieldorderchange`, and `statechange {state,reason}`.
@@ -0,0 +1,232 @@
1
+ # Table
2
+
3
+ A sortable, selectable, editable data table with a sticky header for dense records, transactions, and operational workflows.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/table · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ **Group and section rows.** `rowKind` names the field (or a callback) that classifies a row, and
8
+ `rowKinds` maps a kind to `{span, render, class}`. A `span: true` row renders one
9
+ `<th scope="colgroup">` across every rendered cell — including the selection and reorder columns —
10
+ and carries no others, which is what a heading row in a billing document actually is. Both
11
+ default to null, so a table that sets neither renders exactly as before. While any spanning row is
12
+ present the header sort controls are withheld and `setSort()` is a no-op: sorting a grouped table
13
+ scatters its positions out of their sections, and silently doing so is worse than not offering it.
14
+ The stacked presentation renders the heading alone rather than a row of labelled blanks.
15
+
16
+ Sortable, selectable, sticky-header data table. `fr` widths fill the container while px/auto
17
+ widths scroll horizontally, and multi-select adds a tri-state header checkbox plus Shift+click
18
+ range select.
19
+
20
+ - **Options** — `columns: [{ id, label, ariaLabel?, sortable?, width ('120px'|'2fr'|'auto'),
21
+ minWidth?, pin?: 'start'|'end', group?, align,
22
+ type?: 'text'|'number'|'currency'|'percent'|'unit', locale?, decimals?, currency?, unit?,
23
+ render?: (row,i)=>Node|string, sortValue?, headerTitle? }]`, `data`, `rowId: 'ID'`,
24
+ `sort: { id, dir }`, `sortMode: 'local'|'server'`, `selectable: false|'single'|'multi'`,
25
+ `stickyHeader: true`, `height`, `virtual: false`, `emptyText`, `rowClass`, `zebra: true`, `variant:
26
+ 'default'|'plain'`, `hierarchy: false|{parentId, column?, expanded?}`, `interactive: false`,
27
+ and `label`/`labelledBy`. Locale, currency, unit, and decimals may be row callbacks; values
28
+ remain numbers in row data while display formatting is locale-aware.
29
+ - **Appearance** — the header sits on the table's surface (no band) in the muted text colour at a
30
+ medium weight, sentence case; the sorted column's label takes the text colour beside its arrow.
31
+ Rows are divided by `--zx-color-border-subtle`, the header by the ordinary border, and every cell
32
+ uses tabular figures. Checked rows of a multi-selection keep the accent tint (`--zx-color-bg-selected`);
33
+ the selected row of a `selectable: 'single'` table is the current record of a master–detail list
34
+ and takes the neutral `--zx-color-bg-current` fill. Sortable and plain headers set the same type,
35
+ and the scroll region reserves no scrollbar gutter until the table actually scrolls.
36
+ - **Column widths** — `fr` columns share what the columns with a CSS length leave over, and never
37
+ less than their `minWidth` (a CSS length or a number of pixels, default `'5rem'`; `0` lifts the
38
+ floor). The table takes a minimum width from those floors, so a container too narrow for them
39
+ scrolls the table inline instead of squeezing the `fr` columns to nothing — in a windowed table
40
+ as well. `minWidth` is also honoured on an `auto` column of a table with a fixed layout (one
41
+ with `fr` columns, or `virtual`), where it has no default; a column with a CSS length `width`
42
+ ignores it.
43
+ - **Sticky header** — `stickyHeader: true` sticks the column headers to the top of the table's
44
+ **own scroll region** while its rows scroll. That takes a bounded region: set `height`, or use
45
+ `virtual`, which caps the region at the window height. A table without one grows to the height
46
+ of its rows, never scrolls itself, and its header leaves with the page; to keep a header in view
47
+ while the *page* scrolls, give the table the height of the area it sits in. Header cells sit at
48
+ `z-index: 2` inside the scroll region.
49
+ - **Pinned columns** — `pin: 'start'|'end'` on a column keeps it in view at that inline edge of
50
+ the scroll region while the table scrolls sideways (`position: sticky`, so it follows the
51
+ writing direction). A pinned column stays where the column order puts it and sticks once it
52
+ reaches the edge: declare a `'start'` column before the columns it should stay in front of and
53
+ an `'end'` column after them. Several pinned columns stack in column order, and the row handle
54
+ and selection checkbox columns are pinned along with the first `'start'` column. Give a pinned
55
+ column a `width` or keep it short — what is pinned is taken from the room the others scroll in.
56
+ A cell focused by keyboard scrolls clear of the pinned columns. Pinning is not applied while
57
+ the table is stacked (`responsive`). Pinned cells are opaque and paint the row's fill
58
+ themselves; `--zx-table-pin-bg` sets their base, the header background unless set. Cells carry
59
+ `data-pin="start"|"end"`, and `data-pin-edge` on the column next to the scrolling ones.
60
+ - **Header groups** — `group: 'Label'` on adjacent visible columns (with the same `pin`) gives
61
+ them one shared header cell in a second header row above the column labels: a
62
+ `<th scope="col">` with the right `colspan`, so assistive technology announces the group with
63
+ every cell beneath it. Columns without a `group` have a blank above them. The group row holds
64
+ no controls and takes no part in sorting or keyboard navigation; it counts as a row in
65
+ `aria-rowcount`/`aria-rowindex`. Hiding or reordering columns regroups what is left: a group
66
+ interrupted by another column becomes two cells. It works in plain, hierarchical and windowed
67
+ tables, and sticks with the header.
68
+ - **Columns in the DOM** — every header and body cell carries `data-column="<id>"` in every mode,
69
+ read-only included, so a table can be styled per column. A column with `label: ''` (icons,
70
+ actions) keeps a blank header named by `ariaLabel`, or by its id; `ariaLabel` also names the
71
+ column in the chooser and its cell editors.
72
+ - **`variant: 'plain'`** — for a table inside a card or panel that already draws the box: no outer
73
+ frame, no header band, no zebra, hairline row dividers. Reflected as `data-variant="plain"` on the
74
+ root; TableView passes it through `table: { variant: 'plain' }`.
75
+ - **Methods** — `setData()`, `addData()`, `updateRow(id,row)`, `removeRow(id)`, `getRow(id)`,
76
+ `getData()`, `empty()`, `setSort(id,dir)`, `getSort()`, `clearSort()`, `getSelection()`, `setSelection(ids)`,
77
+ `clearSelection()`, `reveal(id)`, `setLoading(bool)` (busy/skeleton state — dims rows, shows an
78
+ indeterminate top bar, sets `aria-busy`, and is cleared by the next `setData`).
79
+ - **Events** — `rowclick {row, id, index, event}`, `rowdblclick`, `sort {id, dir}`,
80
+ `selectionchange {rows, ids}`, `datachange {rows}`, and `rowtoggle {row, id, expanded}`.
81
+ `rowclick` fires for Enter on a focused row as well as for a click; `event` is then the keydown.
82
+ A click on a control inside a cell belongs to that control: it raises neither `rowclick` nor
83
+ `rowdblclick` and does not select the row in a `single` selection. A control is a button, link,
84
+ field or `<label>`, an element with a widget role or in the Tab order, editable content, or
85
+ anything marked `data-zx-table-no-edit` — so a Toggle, a menu button or a link rendered into a
86
+ cell needs no `stopPropagation()`. Mark a custom clickable element the same way.
87
+ - **Keyboard** — an *interactive* table implements the WAI-ARIA APG **Grid** pattern
88
+ (`role="grid"`, with `aria-multiselectable` for `selectable: 'multi'`), or the **Treegrid**
89
+ pattern with `hierarchy`. A table is interactive when it is `selectable`, has `editMode` or
90
+ `hierarchy`, sets `interactive: true`, or has a `rowclick`/`rowdblclick` listener attached through
91
+ `on()` or an `onrowclick`/`onrowdblclick` option (attaching one later turns the grid on). A host
92
+ that listens only for the bubbling `zx-rowclick` DOM event passes `interactive: true`. TableView
93
+ always bridges `rowclick` to `recordclick`, so its table is always a grid. Any other table keeps
94
+ plain `<table>` semantics, no grid role, no name unless `label` is given, and no row Tab stop.
95
+ In a grid the rows are one Tab stop with a roving `tabindex`; the row checkboxes and disclosure
96
+ buttons leave the Tab order because the row keys cover them (links and buttons a host renders
97
+ in cells keep theirs). Focus is on rows by default and on cells when `editMode` is set —
98
+ reflected as `data-focus="row"|"cell"` on the root. ArrowUp/ArrowDown move a row,
99
+ ArrowLeft/ArrowRight a cell (cell focus), Home/End go to the first/last row (cell focus:
100
+ first/last cell of the row) and Ctrl+Home/End to the first/last row's corner cell,
101
+ PageUp/PageDown move by the rows visible in the scroll region (10 when the table does not scroll
102
+ itself). Enter activates exactly like a click (`rowclick`; selects in `single`), Enter/F2 on an
103
+ editable cell opens its editor, Space toggles the row's selection when `selectable` (activates
104
+ otherwise), Shift+ArrowUp/Down extends a `multi` selection from its anchor, and Ctrl/Cmd+A
105
+ selects the rows in the DOM — like the header checkbox, not the rows `growing` holds back nor the
106
+ children of collapsed branches. A sort, new data, or a change in expansion starts the anchor
107
+ over. Treegrid: ArrowRight expands a collapsed row, then moves into its first child; ArrowLeft
108
+ collapses an expanded row, then moves to its parent. With cell focus, ArrowLeft from the first
109
+ cell lands on the row and ArrowRight from the row goes back to its first cell. The focused row
110
+ (and column) is kept by id across `setData`, sorting, expansion, growing, and `updateRow`; when
111
+ a collapsed ancestor hides it, the ancestor takes focus, and when it is gone, its neighbour does.
112
+ Focus is only restored when the body had it, and without scrolling, so a polling refresh never
113
+ pulls the page back to the table. An emptied table keeps focus on its frame until rows return.
114
+ Column headers keep their sort buttons in the Tab order rather than joining arrow navigation —
115
+ the one deliberate departure from the APG grid, which puts the header row inside it. Rows and
116
+ cells show an inset `--zx-focus-ring` with a transparent outline that forced colours paint.
117
+ - **Naming** — `label` or `labelledBy` (an element id) names the table; a grid without either is
118
+ named by the `table.label` message (English "Table"), so pass a real name. Row controls are named
119
+ after the row's first cell with text through `table.selectRow` (`Select %1`), `table.expandRow`,
120
+ `table.collapseRow`, and `table.moveRow`; `table.row` (`row %1`) stands in for a row without
121
+ text, and `table.selectAll` names the header checkbox. Sort buttons and selection checkboxes are
122
+ at least 24×24 px targets; the checkbox is drawn so the glyph stays `--zx-space-4` while a
123
+ transparent border makes up the target.
124
+ - **Hierarchy** — flat parent references are projected as an ARIA `treegrid`; `getData()` and all
125
+ editing/mutation APIs stay flat and ID-based. Orphans become roots, cycles render once, local
126
+ sort reorders siblings without mixing levels, and growing counts visible rows. Use
127
+ `toggleRow()`, `expandRow()`, `collapseRow()`, `expandAll()`, `collapseAll()`, and
128
+ `getExpanded()`. `hierarchy.expanded` is read at construction only; `setExpanded(ids, {silent})`
129
+ replaces the whole set afterwards in one render, which is what to call when restoring a saved
130
+ state (a loop over `expandRow()` renders once per branch). `true` expands every branch, `false`
131
+ or `[]` collapses them all; ids are compared as `rowId` returns them (`1` is not `'1'`), and ids
132
+ that are not branches of the current data are dropped. Unless silent it emits one `rowtoggle`
133
+ per branch whose state changed, after the render; a set equal to the current one renders and
134
+ fires nothing. The native disclosure button works by pointer and keyboard without selecting
135
+ or clicking the row.
136
+ - **Editing** — `editMode: false|'cell'|'row'` (default `false`, and completely inert until set),
137
+ plus `editTrigger: 'double'|'single'` (Table defaults to double; Grid defaults to single).
138
+ `'cell'` edits one cell, `'row'` opens every editable cell of the row and commits them as a unit.
139
+ Editors are sized into the cell without changing row height, and an editing cell carries
140
+ `data-editing="true"` (`data-invalid="true"` plus an `aria-live` message when a validator rejects).
141
+ Text, number, and date editors select their content on entry, so typing replaces the value
142
+ ("6" over "1.00" gives 6); a textarea keeps its caret.
143
+ - **Editable columns** — extra column keys: `editable: false|true|'text'|'number'|'select'|'date'|
144
+ 'checkbox'|'textarea'|((row)=>boolean)` (`true` infers `'number'` for number/currency/percent/unit
145
+ columns and `'text'` otherwise; a function is evaluated per row, so individual rows stay
146
+ read-only), `options` for `'select'` (`[{value,label}]`, a `{value: label}` map
147
+ whose keys are always strings, or `(row)=>items`), `editorProps` (forwarded to the underlying
148
+ NumberField/Select/Datebox/Toggle or to the generated `<input>`/`<textarea>`),
149
+ `editor: (row, api)=>Node` for a fully custom editor (`api` is `{value, commit(value), cancel(),
150
+ row, column}`; it wins over `editable`, but a per-row `editable` function returning `false` still
151
+ marks the cell read-only), `parse: (raw,row)=>value` and `format: (value,row)=>string` (`format`
152
+ seeds the text of a `'text'`/`'textarea'` editor, `parse` converts every editor's raw output back),
153
+ and `validate: (value,row)=>true|string` (a returned string marks the cell invalid, shows the
154
+ message, and refuses the commit).
155
+ - **Transaction editors** — currency and unit columns reuse `NumberField` and show the resolved
156
+ currency/unit as its suffix unless `editorProps.unit` overrides it. This is a generic typed-grid
157
+ contract: application code remains responsible for tax, discount, subtotal, and accounting
158
+ formula rules.
159
+ - **Editing methods** — `startEdit(rowId, columnId)`, `commitEdit()`, `cancelEdit()`, `isEditing()`,
160
+ `getEditing()` → `{id, columnId}|null`.
161
+ - **Editing events** — `editstart {row, id, column, columnId, value}`;
162
+ `editcommit {row, id, column, columnId, value, previous, changes}` — **cancelable**:
163
+ `preventDefault()` on the component event (`table.on('editcommit', …)` or the `oneditcommit` option,
164
+ not the mirrored `zx-editcommit` DOM event) keeps the editor open so a server round-trip can reject
165
+ the change (`changes` is the `{columnId: value}` map and holds every changed cell in row mode);
166
+ `editcancel {row, id, column, columnId}`;
167
+ `editinvalid {row, id, column, columnId, value, message}`. A committed change is written
168
+ back through `updateRow()`, so `datachange` fires exactly as for a programmatic row update — a
169
+ commit with no changes emits `editcommit` with an empty `changes` map and leaves the data alone.
170
+ Sorting, filtering, or `setData()` while editing cancels the edit cleanly and emits `editcancel`.
171
+ - **Editing keyboard** — Enter or F2 on a focused editable cell starts editing (editable cells share
172
+ one roving tab stop); the configured single/double pointer gesture starts it without emitting
173
+ `rowdblclick`. Enter commits and
174
+ returns focus to the cell (Shift+Enter stays a newline in a `'textarea'`, Space toggles a
175
+ `'checkbox'`), Escape cancels and returns focus to the cell, Tab commits and moves to the next
176
+ editable cell (Shift+Tab the previous), wrapping across rows, and tabbing past the last editable
177
+ cell commits and leaves the table normally. Clicking outside the editor commits rather than
178
+ discarding what was typed.
179
+ - **Growing** — `growing: <number>` renders that many rows and offers a control for the next batch,
180
+ instead of laying out a result set nobody will scroll through. `growBy(count?)`, `showAll()`,
181
+ `getRenderedCount()`, and `grow {rendered, total}`. `setData()` starts the batch over, since a new
182
+ result set is not the old one grown. Row indices stay absolute — a row's index is its place in the
183
+ data, not in what is on screen. **Select-all covers the rendered rows, not the whole result set**;
184
+ call `showAll()` first to mean all of them. While growing, the table carries `aria-rowcount` and
185
+ each row an `aria-rowindex`, so assistive technology hears the real total rather than the size of
186
+ the batch.
187
+ - **Windowed rendering** — `virtual: true` draws only the rows in view and one viewport of overscan
188
+ above and below; spacer rows keep the scroll height, so what the table costs stops depending on
189
+ how many rows it holds. It is off by default, and a table that does not ask for it renders exactly
190
+ as before. A windowed table is one grid over all of its rows, so `virtual` implies `interactive`:
191
+ the table carries `aria-rowcount`, every drawn row an `aria-rowindex`, and the whole keyboard map
192
+ moves through every row, drawing the one it lands on. The focused row and the row being edited
193
+ stay drawn wherever the reader scrolls. Sorting, filtering through `setData()`, section rows,
194
+ hierarchy, row-level controls in cells, inline editing, and the sticky header work as usual, and
195
+ `getData()`, `getSelection()`, and exports built on them read the data, not the DOM. Selection
196
+ reaches rows that are not drawn: a Shift range covers them, and **the header checkbox and
197
+ Ctrl/Cmd+A take every row**, not only the drawn ones. `reveal(id)` scrolls a row into view, drawing
198
+ it first, and returns whether it could; it works without `virtual` too, on any row in the DOM.
199
+ `getRenderedCount()` reports the rows drawn. `virtual` wins over `growing`, and the conflict is
200
+ reported once through the console. Limits: give the table a `height`, or its scroll region stops at
201
+ the height of the window. **Rows have one height:** the table measures one row and takes that
202
+ height for all, following `--zx-row-height`, so rows of differing height are not supported, and
203
+ long text is cut short with an ellipsis rather than wrapped. Column widths cannot follow content
204
+ that is not drawn, so the layout is fixed: `auto` columns share the width evenly, and a column that
205
+ needs more sets `width`. It needs no `ResizeObserver`: where there is none (jsdom) the window
206
+ draws for an assumed row height and viewport. **Find-in-page does not see rows that are not drawn**, and printing prints
207
+ the drawn rows only.
208
+ - **Responsive stacking** — `responsive: false|'sm'|'md'|'lg'|'xl'` stacks each row into a card of
209
+ label/value pairs below that width, instead of leaving a horizontal scrollbar with the data
210
+ hidden behind it. The width measured is **the table's own container**, not the viewport, so this
211
+ triggers inside a narrow split pane on a wide screen. A column with `popin: false` leads the card
212
+ instead of becoming another labelled line — the identifying column usually wants that. Every cell
213
+ carries `data-label`, so the labels are there whether or not the option is on. `isStacked()`
214
+ reports the current state and `stackedchange {stacked}` fires on each crossing. Stacking drops
215
+ `display: table`, which drops the implicit ARIA roles, so the component states
216
+ `table`/`rowgroup`/`row`/`cell`/`columnheader` explicitly for exactly as long as the mode is on.
217
+ - **Empty state** — `emptyText` takes a string, a Node, or a function returning one, so an empty
218
+ table can carry an icon, an explanation, and the action that resolves it (`emptyState({…})`).
219
+ A function is re-called on every render, which is what to use when the placeholder holds controls.
220
+ - **Row order** — `rowReorder: true` adds a dedicated drag handle. Pointer drag moves rows before
221
+ or after a sibling; Space/Enter grabs/releases the same handle and ArrowUp/ArrowDown moves it for
222
+ keyboard users. `moveRow(id, targetId, position)` exposes the same guarded operation. Hierarchical
223
+ rows only move among siblings, and an active local sort disables manual order. A cancelable
224
+ `rowmove {row,id,target,targetId,position}` fires before `datachange`.
225
+ - **Column visibility** — `columnVisibility: true` renders a chooser; `hiddenColumns` seeds it.
226
+ `getVisibleColumns()`, `getHiddenColumns()`, `setColumnVisible()`, and `toggleColumn()` preserve
227
+ caller column order and never allow the final visible column to disappear.
228
+ - **Column order** — `columnReorder: true` adds up/down buttons to the chooser and ArrowUp/
229
+ ArrowDown support while a column option is focused. `getColumns()`, `setColumns()`,
230
+ `getColumnOrder()`, `setColumnOrder()`, and `moveColumn()` reconcile stale saved IDs and keep
231
+ hidden/sorted state attached to stable column IDs. `columnorderchange {order}` fires after a
232
+ user or non-silent programmatic change.
@@ -0,0 +1,39 @@
1
+ # TagPicker
2
+
3
+ A multi-select combobox that keeps its selection visible as removable tags inside the control — for picking several values out of a large catalogue.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/tag-picker · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Multi-select combobox that renders its selection as removable tags inside the control (APG combobox
8
+ plus multi-selectable listbox). Use it when the catalogue is too large to show in full: `Checklist`
9
+ shows a fixed set, and `ValueList` takes free text with no catalogue. Unknown IDs passed to
10
+ `setValues` still render as tags, so a stored selection survives a catalogue that has not loaded
11
+ yet. Field type: `tagpicker`.
12
+
13
+ - **Options** — `items`, `values: []`, `valueKey: 'ID'`, `labelKey: 'name'`, `iconKey: 'icon'`,
14
+ `colorKey: 'color'`, `toneKey: 'tone'`, `searchKeys`,
15
+ `filter: 'local'|(query)=>Promise<items>`, `minQuery: 0`, `debounce: 200`, `allowCreate: false`,
16
+ `max` (maximum tags; further options become `aria-disabled`), `closeOnSelect: false`,
17
+ `placeholder`, `listHeight: 260`, `disabled`, `readonly`, `renderItem`, `renderTag`.
18
+ - **Tags are Badges** — every selected tag is built by `badge()` (`.zx-badge.zx-tag-picker__tag`):
19
+ the Badge's height from the row, 12px medium type, padding and one fill, with the tag shape's
20
+ small corners. `toneKey` names a categorical tone from the Badge palette (`blue`, `teal`,
21
+ `green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`), so a toned tag is exactly the
22
+ `badge({ tone })` a list row or record header shows for the same item; a tone wins over a colour.
23
+ An untoned tag keeps the text ink, because in a field it is the value.
24
+ - **Tag identity** — icon values accept a bundled icon name or Node; colors (a CSS colour or a token
25
+ reference such as `var(--zx-color-tone-blue-fg)`) are scoped to the tag and its option through
26
+ `--zx-tag-color`. An option shows its icon on a tile of its colour; inside a tag the icon is a bare
27
+ glyph, since the tag is already the fill. Custom `renderItem`/`renderTag` remain authoritative.
28
+ - **Read-only** — `readonly` (or `setReadonly(true)`) shows only the tags: no input, chevron, or
29
+ remove buttons, so a full row of tags never wraps onto an empty line.
30
+ - **Methods** — `getValues()`, `getItems()`, `setValues(values, {silent})`, `addValue()`,
31
+ `removeValue()`, `clear()`, `reset()`, `setItems()`, `isFull()`, `open()`/`close()`, `focus()`,
32
+ `setReadonly()`, `enable()`/`disable()`.
33
+ - **Events** — `change {values, items}`, `add {value, item}`, `remove {value, item}`,
34
+ `create {value, item}`, `query {query}`, `open`, `close`.
35
+ - **Keyboard** — ↓ opens and moves, ↑ moves, Enter toggles the active option (or creates one from
36
+ the query), Escape closes, Backspace on an empty input removes the last tag, Home/End jump
37
+ within the list.
38
+ - **Quiet fields** — inside `[data-zx-fields="quiet"]` the tags read as the value: no border, fill
39
+ or chevron until hover; full field chrome while focused or open.
@@ -0,0 +1,16 @@
1
+ # Timebox
2
+
3
+ A duration field.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/timebox · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Duration input (H:MM[:SS], optional sign) — a length of time, not a time of day. For a time of day
8
+ use `TimePicker` or `DateTimeBox`.
9
+
10
+ - **Options** — `value: 0`, `unit: 'minutes'|'seconds'|'hours'`, `seconds: false`, `signed: false`,
11
+ `disabled`.
12
+ - **Methods** — `get(unit)`, `set(value, unit?, {silent})`, `enable()`/`disable()`.
13
+ - **Events** — `change {value}`, in `options.unit`.
14
+ - **Also exported** — the pure helpers `splitTime` and `joinTime`.
15
+ - **Quiet fields** — inside `[data-zx-fields="quiet"]` the segments (native inputs) and the sign
16
+ button drop their border and fill until hover or focus; the sign keeps its colour.
@@ -0,0 +1,21 @@
1
+ # Toggle
2
+
3
+ A labelled switch for settings that take effect immediately.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/toggle · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Switch (`role="switch"`, `aria-checked`).
8
+
9
+ - **Options** — `checked: false`, `value: true`, `label: null`, `hideLabel: false`,
10
+ `disabled: false`.
11
+ - **Label** — start-aligned and wrapping like text within the available width, the track level
12
+ with its first line. It is the switch's accessible name. `hideLabel: true` keeps it for assistive
13
+ technology only: no visible text, and the label becomes the switch's `aria-label` — for a switch
14
+ whose meaning the layout already shows, such as a table cell under a column header. With no
15
+ label at all, name the switch from outside: a Field or `<label for>` around it, or
16
+ `aria-labelledby` on the element.
17
+ - **Methods** — `get()`, `set(checked, {silent})`, `toggle()`, `getValue()` (returns
18
+ `options.value` when on, `false` when off), `setLabel(label)` (null removes it),
19
+ `enable()`/`disable()`.
20
+ - **Events** — `change {checked, value}`.
21
+ - **Keyboard** — Space/Enter.