@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
@@ -0,0 +1,76 @@
1
+ # Message — toasts, inline, progress
2
+
3
+ Transient notifications: a floating region for toasts, a progress handle for long work, and an inline area for messages that belong to one part of the screen.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/message · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Floating toasts come from statics; `new Message(target)` gives an inline, non-floating area with
8
+ the same `.show()`. The toast region is `role="status"`/`aria-live` (`role="alert"` for errors).
9
+ A floating region sits at the top of the viewport on the inline-end side by default (`top-end`:
10
+ the upper right in a left-to-right page), sizes to its messages rather than the page, and uses the
11
+ translucent glass surface tokens with a solid fallback. A message is a plain card with a neutral
12
+ border; its kind shows in the icon. Floating messages pile into a stack that opens on hover, focus,
13
+ or a press (see **Stack**).
14
+
15
+ - **Statics** — `Message.info/success/warning/error(msg, opts)`,
16
+ `Message.show(msg, { kind, timeout=4000, closable, highlight?, scope?, placement? })` → `{ close() }`,
17
+ `Message.progress(text, {scope?, placement?, highlight?})` → `{ update(pct, text?), done(), fail(text?) }`,
18
+ `Message.setPlacement(placement)` / `Message.getPlacement()`,
19
+ `Message.setStack(enabled)` / `Message.getStack()`. `scope` is an element or selector
20
+ whose nearest Zx theme scope owns that floating region; without it the focused opener supplies
21
+ the scope.
22
+ - **Placement** — `placement: 'top-start'|'top'|'top-end'|'bottom-start'|'bottom'|'bottom-end'`
23
+ per call, default `'top-end'`: the block edge, then the inline position, logical, so `start` and
24
+ `end` follow the writing direction and `top`/`bottom` alone are centred.
25
+ `Message.setPlacement(placement)` sets the default for calls that name none and returns the
26
+ placement now in effect (anything unknown restores `'top-end'`); it applies to messages shown
27
+ from then on. Messages of one placement share a region, so a scope has one region per placement
28
+ in use, each carrying `data-placement`. At the foot the newest toast is nearest the edge. The
29
+ distance from the viewport edge is the `--zx-message-offset` custom property (default
30
+ `var(--zx-space-4)`), read from the region's theme scope: set it there or on `:root` to clear a
31
+ header or a status bar. At 640px and narrower every placement spans the foot of the viewport,
32
+ full width. An inline area ignores `placement`.
33
+ - **Region lifecycle** — a floating region is created on the first toast for its scope and removed
34
+ when its last toast closes. One whose host was emptied or left the document is replaced on the
35
+ next toast rather than reused, and a scope that is itself detached falls back to the focused
36
+ element's scope. `Message.disposeRegion(scope)` → boolean removes a scope's regions at once — all
37
+ placements, toasts and all — for a host torn down while toasts are still showing. While a modal Dialog or
38
+ Sheet is open the region moves into the topmost one, so toasts and their actions stay visible
39
+ and clickable above it, and moves back when it closes. A press on a toast dismisses no open menu
40
+ or drawer.
41
+ - **Per-message options** — `kind: 'info'`, `timeout`, `closable: true`, `maxVisible: 5` (extras
42
+ queue, and hovering pauses dismissal), `highlight: false`.
43
+ - **Highlight** — `highlight: 'border'` (or `true`) draws the message's border in the kind colour;
44
+ `highlight: 'animated'` draws it faintly with a light travelling round it, and is the still
45
+ kind-coloured border under `prefers-reduced-motion: reduce`. Per message, or as an inline area's
46
+ default; the message carries it as `data-highlight`. `false` (the default) is the plain card.
47
+ - **Stack** — floating regions stack by default, and `stack: true` makes an inline area stack:
48
+ the visible messages pile into one stack, the newest in front, the next two peeking out behind
49
+ it a step smaller, the rest out of sight. `Message.setStack(false)` lists floating messages one
50
+ below another instead (at once, those on screen included; `getStack()` reads it). It
51
+ opens — every visible message laid out with its own height — while the pointer is over it or
52
+ focus is inside it; a press on it that is not on a button (a tap included) keeps it open until a
53
+ press outside it, Escape (which returns focus to where it came from), or `collapse()`. While it
54
+ is open by any of these no message in it times out. The outside press is handled after its own
55
+ click handlers, so a button elsewhere can toggle the stack with
56
+ `isExpanded() ? collapse() : expand()`. Closing a message from the keyboard moves focus to the
57
+ same control of the next message, and from the last one back to where it was before it came
58
+ into the stack. An open floating stack taller than the viewport becomes a scrolling list
59
+ (`data-overflow`) with the newest message in view. `expanded: true` keeps it open without
60
+ holding the timers. Instance methods: `expand()` (opens and keeps it open), `collapse()`,
61
+ `isExpanded()`, `setStack(enabled)`; events `expand` and `collapse`. The root carries
62
+ `data-stack` and `data-state="collapsed"|"expanded"`; document order follows the visual order,
63
+ so Tab meets the messages as they are seen. A stack at the top (inline areas, `top*`) piles
64
+ downwards, one at the foot (`bottom*`, and every region at 640px and narrower) upwards. The
65
+ geometry is the exported pure helper `messageStackLayout(heights, expanded)`.
66
+ - **Action** — `action: { label, onclick?, kind? }` renders one small button (`.zx-btn`,
67
+ `data-size="sm"`, secondary unless `kind` is `primary`/`danger`/`ghost`) in a toast or an inline
68
+ message; activating it runs `onclick(event)` and closes the message. A message with an action
69
+ stays at least 8000ms (`timeout: 0` still persists). Every message holds its timer while the
70
+ pointer is over it or focus is inside it (WCAG 2.2.1) and resumes once neither is; the region is
71
+ not modal, so Tab moves between the action and the close button, and closing a message that holds
72
+ focus returns focus to where it came from. The live region still announces the text.
73
+ - **Leading** — `leading: Node | component` (an Avatar, say) replaces the kind icon. It is
74
+ decorative; the text must name what it shows.
75
+ - **Handle** — every `show()` (static or inline) and `info/success/warning/error()` return
76
+ `{ close() }`; closing twice, or a queued message, is safe.
@@ -0,0 +1,27 @@
1
+ # Modal
2
+
3
+ A bare top-layer surface you fill yourself — Dialog’s unopinionated sibling, for overlays that supply their own chrome.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/modal · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Thin overlay on the native `<dialog>` element. The surface uses the shared, reading-sized overlay
8
+ panel material; the backdrop uses `--zx-color-overlay-backdrop`, and focus returns to the opener on close.
9
+
10
+ - **Options** — `content`, `width: 'auto'`, `closable: true`, `lightDismiss: false`,
11
+ `destroyOnClose: false`, `scope: null` (the opener's nearest Zx theme scope by default). The
12
+ scope is resolved again on every `open()`; a `scope` element not yet in the document leaves the
13
+ dialog detached until then, rather than parking it on `<body>` outside the theme.
14
+ - **Methods** — `open()`, `close(result?)`, `setContent()`, `isOpen()`.
15
+ - **Events** — `open`, `close {result}`, `cancel {reason}`.
16
+ - **Dismissal** — everything the reader does to dismiss an overlay raises `cancel` first, with
17
+ `reason` `'escape'`, `'close-button'` (Dialog/Sheet header ✕), `'button'` (a footer button whose
18
+ action is `'cancel'`), `'backdrop'` (`lightDismiss`), `'outside'` or `'drag'` (Sheet).
19
+ `event.preventDefault()` keeps it open, which is the place for an "unsaved changes" check.
20
+ A programmatic `close()` raises no `cancel`. Escape is handled by Zx rather than by the browser's
21
+ close request, so preventing it holds however often the key is pressed; a handler that calls
22
+ `preventDefault()` on the Escape keydown (a popup inside the dialog, your own) keeps the key.
23
+ - **Without `showModal()`** — in a DOM that has `<dialog>` but not `showModal()` (jsdom, for unit
24
+ tests), Modal, Dialog and Sheet present themselves through the `open` attribute instead.
25
+ `open()`, `close(result)`, `isOpen()`, Escape, `cancel`, the events and `destroy()` work the
26
+ same; there is no top layer, no inert page, no backdrop and no `aria-modal`, so modality itself
27
+ is not testable there.
@@ -0,0 +1,71 @@
1
+ # ModuleBar — the module level of an application
2
+
3
+ The module level of an application: one colour-coded tile per module in a vertical strip or a horizontal bar.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/module-bar · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ One colour-coded tile per module, in a vertical strip or a horizontal bar: the level above an
8
+ application's menus. Use it on its own — the classic module bar in an application header, beside
9
+ a tree-layout `AppSidebar` — or through `AppSidebar`'s `layout: 'modules'`, which composes it.
10
+
11
+ ```js
12
+ import { ModuleBar } from '/assets/zx.esm.js';
13
+
14
+ const bar = new ModuleBar(null, {
15
+ items: [
16
+ { id: 'mail', label: 'Mail', icon: 'envelope', tone: 'blue', badge: 7, children: [
17
+ { id: 'inbox', label: 'Inbox', href: '#inbox' }, { id: 'sent', label: 'Sent', href: '#sent' }
18
+ ] },
19
+ { id: 'billing', label: 'Billing', icon: 'file-invoice', color: '#535494', href: '#billing' }
20
+ ],
21
+ active: 'inbox',
22
+ onselect: (event) => { event.preventDefault(); route(event.detail.id); }
23
+ });
24
+ bar.setBadge('mail', 8);
25
+ ```
26
+
27
+ - **Items** (`ModuleItem`) — the `AppNavItem` shape plus `tone` (a categorical tone that follows
28
+ the theme) or `color` (any CSS colour; it wins), `pinned: true|number` (when any module is
29
+ pinned, unpinned ones are under "All modules" only), `group` (the catalogue heading), and
30
+ `description`. Children are the module's menu. A `section` at the top level heads its modules:
31
+ a caption over them while names are printed beside the tiles, a short rule between groups on an
32
+ icon strip or bar, and their group in the catalogue. `agent` (AgentAvatar options, or `true`)
33
+ draws the module as an agent: its `AgentAvatar` at the size of the tile in place of the tile,
34
+ whatever the `appearance`, at rest, with the activity's word in the tile's accessible name
35
+ ("Ledger, Needs you (2)"); `tone` and `color` then do not apply.
36
+ - **Options** — `items`, `active` (a module or anything in a module's menu),
37
+ `orientation: 'vertical'|'horizontal'`, `side`, `appearance: 'tint'|'solid'|'plain'` (the glyph
38
+ on a tint of the module colour; the solid identity tile; monochrome glyphs),
39
+ `labels: 'hidden'|'below'|'beside'` (names under the tiles of a vertical strip, or beside them —
40
+ a navigation column of its own, a row per module with its count at the end),
41
+ `menus: 'flyout'|'none'`, `expanded`, `controls`, `allModules: 'auto'|'always'|'never'`,
42
+ `header`, `footer`, `label` (default "Modules"), `openDelay`, `closeDelay`, `renderIcon`.
43
+ - **Menus** — with `menus: 'flyout'` a module's children open beside its tile on hover, focus,
44
+ click, or the arrow toward the workspace, exactly like a rail. With `menus: 'none'` an adjacent
45
+ panel the application owns shows them: every module then fires `select`, `setExpanded(id)`
46
+ names the module the panel shows, and each tile with a menu reports `aria-expanded` and
47
+ `aria-controls` the `controls` id.
48
+ - **Overflow** — modules that do not fit move behind the "All modules" button; the current module
49
+ (and the expanded one) always stays. The catalogue lists every module as a labelled tile,
50
+ grouped by `group`, with a filter field past twelve modules. `partitionModules(items, capacity,
51
+ keep, reserve)` is the pure function deciding what shows; `reserve` keeps the button's slot for
52
+ `allModules: 'always'`.
53
+ - **Methods** — `setItems()`, `getItems()`, `setActive()`, `setBadge(id, badge)` (in place, on the
54
+ tile, in its menu, and in the catalogue), `setExpanded(id)`, `setLabels(labels)` (how a column
55
+ expands to names and collapses to icons), `setLayout({orientation, side})`,
56
+ `openFlyout()`, `closeFlyout()`, `closeAllFlyouts()`, `isFlyoutOpen()`, `openAllModules()`,
57
+ `closeAllModules()`, `isAllModulesOpen()`, `focus()`, `destroy()`.
58
+ - **Events** — cancelable `select {item, id, value, href, event}`, `flyoutchange {item, id, open}`,
59
+ `overflowchange {visible, overflow}`, and `allmodules {open}`.
60
+ - **Keyboard** — the bar is one Tab stop, on the current module. Arrow keys along the bar move
61
+ between tiles and wrap; Home and End go to the first and last control; typing jumps to the next
62
+ module whose name starts with the letters typed; the arrow toward the workspace opens a menu and
63
+ moves into it; Escape, or the arrow back toward the strip, closes a menu onto its tile; Escape
64
+ closes the catalogue onto its button, and so does tabbing out of it. In the catalogue, arrows
65
+ move across the grid, typing goes to the filter field (past twelve modules), and Enter chooses.
66
+ - **Semantics** — a `<nav>` of native links and buttons, never a menu or menubar. The module that
67
+ is or holds the current page carries `aria-current` (`page` or `true`); an icon-only tile's
68
+ accessible name is its label, with its count ("Mail (7)"), and it has a tooltip. Current is
69
+ the neutral `--zx-color-bg-current` fill behind the tile, never the accent or an edge bar.
70
+ - **Geometry** — a target is one control plus a space step, a tile one control less one, so
71
+ `--zx-control-height` resizes the bar; a coarse pointer keeps a 40px target.
@@ -0,0 +1,16 @@
1
+ # MultiValueEditor
2
+
3
+ A stack of rows for an ordered list of values, each row with its own remove and reorder controls — for a field that repeats.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/multi-value-editor · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Ordered value editor with explicit rows (add / remove / move).
8
+
9
+ - **Options** — `values`, `options` (allowed values, which turns the rows into selects),
10
+ `addLabel`, `reorder: 'both'` (`'both'` | `'buttons'` | `'drag'` | `'none'` — a drag handle, the
11
+ up/down buttons, both, or neither).
12
+ - **Methods** — `getValues()`, `setValues()`.
13
+ - **Events** — `change {values}`.
14
+ - Dragging goes through a dedicated handle, so text selection inside a row's input still works. The
15
+ handle is also a keyboard control (Arrow keys, Home, End), which is what keeps `reorder: 'drag'`
16
+ operable without a pointer.
@@ -0,0 +1,22 @@
1
+ # NavigationBar
2
+
3
+ The application header: a brand, one row of destinations with badges, and the actions that stay reachable at every width.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/navigation-bar · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Application navigation bar: brand, items, and right-aligned actions. Items overflow into a "More"
8
+ menu on narrow widths.
9
+
10
+ - **Options** — `title`, `items: [{ name, title, badge? }]`, `active`, `actions: []`,
11
+ `overflow: true`, `overflowBelow: '44rem'`, `minVisible: 0`.
12
+ - **Methods** — `setTitle()`, `setItems()`, `setActive()`, `setBadge()`, `setActions()`.
13
+ - **Events** — `change {name}`.
14
+
15
+ **Overflow is a default, not a law.** Collapsing every item behind "More" is right for a top app
16
+ bar and wrong for a phone bottom bar, where the navigation is the point. `overflow: false` keeps
17
+ every item at every width; `overflowBelow` moves the threshold; `minVisible: n` pins the first `n`
18
+ items and overflows the rest. At the default the collapse is a container query with no observer
19
+ installed; any other threshold installs a `ResizeObserver`, which is the cost of asking for one.
20
+
21
+ The current item is the neutral `--zx-color-bg-current` fill with the text colour and a semibold
22
+ label; item badges are neutral counts. Only the brand mark keeps the accent.
@@ -0,0 +1,34 @@
1
+ # NumberField
2
+
3
+ A spinbutton with step buttons: bounded ranges, fractional steps, units, and wrapping.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/number-field · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Numeric input with decrement/increment buttons, following the APG **spinbutton** pattern. The step
8
+ buttons are `tabindex="-1"`/`aria-hidden` pointer affordances — the input itself is the spinbutton.
9
+ Field type: `number`.
10
+
11
+ - **Options** — `value` (number|null), `min`, `max`, `step: 1`, `largeStep: 10` (PageUp/PageDown
12
+ multiplier), `precision` (decimals; derived from `step` when null), `snap: true` (see
13
+ **Snapping**), `wrap: false` (stepping past
14
+ a bound jumps to the other one), `placeholder`, `unit` (suffix rendered inside the control),
15
+ `group: false` (thousands separators while idle), `locale`, `disabled`, `readonly`, `required`,
16
+ `name`.
17
+ - **Methods** — `get()`, `set(value, {silent})` (parses strings, snaps to the step grid, clamps to
18
+ the range; `''`/null clear it), `stepUp(n)`, `stepDown(n)`, `setRange(min, max)`,
19
+ `setReadonly()`, `reset()`, `focus()`, `getInput()`, `enable()`/`disable()`.
20
+ - **Events** — `change {value}` (committed), `input {value}` (per keystroke, possibly unsnapped).
21
+ - **Snapping** — by default a typed or assigned value is moved onto the `step` grid (step 2 turns
22
+ 123 into 124) and rounded to the step's decimals. That suits quantities; it is wrong for a value
23
+ that is not a multiple of anything — an identifier, a seed, a measurement. `snap: false` keeps
24
+ the value exactly as entered: `step` is then only what the buttons and arrow keys add, decimals
25
+ are rounded only to an explicit `precision`, and `min`/`max` still clamp.
26
+ - **Keyboard** — ↑/↓ one step, PageUp/PageDown `largeStep` steps, Home/End jump to `min`/`max` when
27
+ set (otherwise they keep their caret meaning), Enter commits, wheel steps while focused.
28
+ - **Also exported** — `parseNumber(raw)` (accepts `.` and `,` as the decimal separator, ignores
29
+ grouping, returns null for junk) and `snapNumber(value, {min, max, step, precision})`.
30
+ - **In a Field** — field type `number` fills the control column like a text input and takes the
31
+ field key as its `name`.
32
+ - **Quiet fields** — inside `[data-zx-fields="quiet"]` the number reads as text: no border, no
33
+ fill, the value start-aligned with the quiet values around it, both steppers at the trailing end
34
+ and hidden (kept in the layout so nothing moves) until hover or focus; full chrome on focus.
@@ -0,0 +1,73 @@
1
+ # Pagination
2
+
3
+ The footer bar of a server-backed list: a page window that never changes width, a page-size select with an Auto size that fits the viewport, a row summary, an append-style Load more mode, and an Auto-load switch for infinite scrolling.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/pagination · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ The pager for a server-backed list. It owns no data: `getState()` and every `change` hand back
8
+ the `page`, `pageSize`, and zero-based `offset = (page - 1) * pageSize` a query needs. `page` is
9
+ 1-based and always clamped into `[1, pages]`; a `total` of 0 is treated as one empty page rather
10
+ than zero pages.
11
+
12
+ The ZeyOS bindings page differently — zero-based, `pageSize: 50`, appending pages above zero — so
13
+ driving `zeyosTable()` (or `zeyosView()`) takes one mapping in the `change` listener:
14
+
15
+ ```js
16
+ const binding = zeyosTable(client, 'contacts', { pageSize: 25 });
17
+ const pager = new Pagination(host, { pageSize: binding.pageSize });
18
+ pager.on('change', async ({ detail }) => {
19
+ const result = await binding.load({ page: detail.page - 1, pageSize: detail.pageSize, replace: true });
20
+ pager.setTotal(result.count ?? 0); // silent, so it cannot loop
21
+ });
22
+ ```
23
+
24
+ In `mode: 'loadmore'` each `change` is one `binding.loadMore()`, which appends.
25
+
26
+ **Fitting the page.** `pageSize: 'auto'` (and `'auto'` among `pageSizes`, shown as "Auto (14)")
27
+ shows as many rows as fit `viewport`, the element the rows scroll in, below its sticky `thead`. It
28
+ measures again whenever the viewport or its content changes size — a window, a drawer, the row height,
29
+ a table stacking into cards — and keeps the page's first row on the new page. A Zx Table is
30
+ measured by its first body row, anything else by `--zx-row-height`; `rowHeight`, `perRow` (a card
31
+ grid's columns) and `reserve` take numbers or functions of the viewport for other content. Call
32
+ `refit()` after swapping what the viewport shows.
33
+
34
+ **Auto-load.** `autoLoad: true` turns paging into infinite scroll: the next page loads by itself
35
+ when the end of the viewport (or, without one, the pager) comes within `autoLoadMargin` pixels —
36
+ half the viewport by default. `showAutoLoad: true` adds an Auto-load switch, so the reader chooses;
37
+ switching between paging and appending returns to page 1. Load more stays as the keyboard's way on.
38
+ Disable the pager while a page is in flight and enable it when the rows land; auto-load waits:
39
+
40
+ ```js
41
+ const pager = new Pagination(footer, { pageSize: 'auto', pageSizes: ['auto', 25, 50], viewport: list, showAutoLoad: true });
42
+ pager.on('change', async ({ detail }) => {
43
+ pager.disable();
44
+ // Appending adds one page; paging shows one; restarting an appending list shows all loaded so far.
45
+ const from = detail.append || detail.mode === 'pages' ? detail.offset : 0;
46
+ const rows = await fetchRows(from, detail.offset + detail.pageSize - from);
47
+ if (detail.append) table.addData(rows); else table.setData(rows);
48
+ pager.enable();
49
+ });
50
+ ```
51
+
52
+ - **Options** — `page: 1`, `pageSize: 25` (or `'auto'`), `total: 0`, `pageSizes: [25, 50, 100]`
53
+ (may include `'auto'`), `siblings: 1`, `boundaries: 1`, `showPageSize: true`, `showSummary: true`
54
+ (renders "26–50 of 312"), `mode: 'pages'|'loadmore'`, `autoLoad: false`, `showAutoLoad: false`,
55
+ `viewport: null` (element, selector, or function), `rowHeight`, `perRow: 1`, `reserve`,
56
+ `minPageSize: 5`, `maxPageSize: 200`, `autoLoadMargin: null`, `disabled: false`.
57
+ - **Methods** — `setPage(n)`, `setTotal(n)`, `setPageSize(n|'auto')`, `setState({page, pageSize,
58
+ total}, {silent})`, `setAutoLoad(on, {silent})`, `refit()`, `getState()` → `{page, pageSize,
59
+ total, pages, offset, auto, autoLoad, mode}`, `enable()`/`disable()`, `destroy()`.
60
+ - **Events** — `change {page, pageSize, offset, total, pages, auto, autoLoad, mode, reason,
61
+ append}`, where `reason` is `page`, `pageSize`, `fit`, `more`, `scroll`, `mode`, or `state`, and
62
+ `append` means "add rows `offset … offset + pageSize` after the shown ones" (otherwise show rows
63
+ `offset …` while paging, `0 … page × pageSize` while appending). `autoload {autoLoad}` when the
64
+ switch flips.
65
+ - **Also exported** — `paginationRange({page, pages, siblings, boundaries})` → `Array<number|'…'>`,
66
+ the pure page-window calculation, and `fitPageSize({available, rowHeight, perRow, reserve, min,
67
+ max})` → the fitted size (0 when nothing can be measured), both usable on their own.
68
+ - **Semantics** — `<nav aria-label="Pagination">`; the current page carries `aria-current="page"`;
69
+ previous/next are labelled icon buttons that go `disabled` at the ends; the ellipses are
70
+ `aria-hidden` spans, not buttons.
71
+ - **Appearance** — the summary and the page-size select sit together at the start of the bar,
72
+ the pager alone at the end; the current page is the neutral `--zx-color-bg-current` fill with a
73
+ semibold figure: where you are, not a call to action.
@@ -0,0 +1,28 @@
1
+ # Panel / MasterPanel
2
+
3
+ A raised surface with a title, an optional collapse control, header actions, and a footer — plus MasterPanel, its full-height variant.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/panel · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ ## Panel
8
+
9
+ Framed, optionally collapsible section. Its header is a row rather than one big button: the chevron
10
+ and title form the collapse control and `buttons` sit at the trailing edge beside it, so clicking
11
+ an action never collapses the panel. The footer bar appears as soon as it has `footer` content,
12
+ `footerButtons`, or both, and its buttons are right-aligned.
13
+
14
+ - **Options** — `title`, `content`, `open: true`, `collapsible: true`, `buttons: []` (elements or
15
+ `button()` descriptors, right-aligned in the header), `footer`, `footerButtons: []`
16
+ (right-aligned in the footer).
17
+ - **Methods** — `setTitle()`, `setContent()`, `setButtons()`, `setFooter()`, `setFooterButtons()`,
18
+ `open()`/`close()`/`toggle()`, `isOpen()`.
19
+ - **Events** — `open`, `close`.
20
+
21
+ ## MasterPanel
22
+
23
+ Full-height application panel with a fixed header (title plus action buttons) and an optional
24
+ fixed footer, while the body scrolls.
25
+
26
+ - **Options** — `title`, `content`, `buttons: []`,
27
+ `module: <ZeyOS module name → accent token>`, `footer`.
28
+ - **Methods** — `setTitle()`, `setContent()`, `setButtons()`, `setFooter()`.
@@ -0,0 +1,40 @@
1
+ # PromptStarters — starting points for an empty conversation
2
+
3
+ Starting points for an empty conversation.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/prompt-starters · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A labelled group of buttons, each with a title and, muted beneath it, its description or else its
8
+ text. PromptStarters only reports the pick and never sends anything: the application decides
9
+ whether a starter fills the composer or sends at once.
10
+
11
+ - **Constructor** — `new PromptStarters(null, options)` creates its own root; `new
12
+ PromptStarters(element, options)` takes over an element and restores it on `destroy()`.
13
+ - **Options** — `items: [{id, title, text, description?, icon?}]`, `label` (the group's accessible
14
+ name, English `Suggestions`), `columns: 'auto'|1|2`, `headingLevel: null`, `msg`. An item without
15
+ `id`, `title` or `text` is left out, as is a repeated id; other fields on an item are handed back
16
+ in `pick`. `text` keeps its spaces and line breaks, so a prompt can end where the person goes on
17
+ writing.
18
+ - **Columns** — `'auto'` is two columns and one in a container narrower than 32rem, read through a
19
+ container query, so it behaves the same in a split pane, a dialog or a phone. The root fills the
20
+ width it is given.
21
+ - **Heading** — `headingLevel: null` keeps `label` for assistive technology only. A level draws it
22
+ above the starters as a heading of that level, which then names the group.
23
+ - **Methods** — `setItems(items)` (the focus on a starter stays on the starter with the same id;
24
+ emits nothing), `destroy()`.
25
+ - **Events** — `pick {item}`, with a copy of the starter as given.
26
+ - **Keyboard** — each starter is a button in the Tab order, pressed with Enter or Space. There are
27
+ no custom keys.
28
+ - **Accessibility** — the root is `role="group"`. Each button is named by its title and described
29
+ by the line beneath it. The line is clamped to two lines on screen; its whole text stays the
30
+ description. Without items the group is hidden.
31
+
32
+ ```js
33
+ const starters = new PromptStarters(null, {
34
+ items: [
35
+ { id: 'reply', title: 'Draft a reply', text: 'Draft a short, friendly reply to this customer:\n\n' },
36
+ { id: 'review', title: 'Prepare the review', text: 'Summarise this week’s escalations.', icon: 'list' }
37
+ ],
38
+ onpick: ({ detail }) => composer.setValue(detail.item.text).focus()
39
+ });
40
+ ```
@@ -0,0 +1,38 @@
1
+ # Prose — `.zx-prose` and `.zx-callout`
2
+
3
+ The reading register for authored content: its own typeface, size, line height, and measure.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/prose · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ The reading register: a class, not a component, that sets authored content — a document, a
8
+ record's notes, a message body, an assistant's answer — in the reading tokens rather than the
9
+ interface ones. Write plain HTML inside it: `h1`–`h4`, `p`, `ul`/`ol`, `blockquote`, `hr`, links,
10
+ inline `code`, `pre`, `kbd`, `mark`, tables, `figure`/`figcaption`, `img`.
11
+
12
+ - **Tokens** — `--zx-font-prose` (the interface stack by default; a serif here leaves the interface
13
+ alone), `--zx-prose-size` (16px, `--zx-text-lg`), `--zx-prose-leading` (1.7), `--zx-prose-measure`
14
+ (62ch, the reading width). Headings scale with the reading size and read `--zx-weight-title`.
15
+ - **Attributes** — `data-size="sm"` sets prose at the interface size, for comments, previews, and
16
+ panels; `data-zx-measure="full"` drops the measure where the column already sets the width.
17
+ - **Rhythm** — one gap between blocks, more above a heading and less below it; links in the body
18
+ colour over a quiet underline, accent on hover; tables without a frame, a muted header over
19
+ hairline rows, `data-align="end"` cells in tabular figures.
20
+ - **Content colour** — a bare `mark` highlights in the amber tone; `mark[data-tone]` in any of the
21
+ nine tones; a bare `span[data-tone]` colours its text, and `data-fill` highlights it as well.
22
+ - **Callout** — `.zx-callout` with an optional `.zx-callout__icon` and a `.zx-callout__body`
23
+ (`.zx-callout__title` for a bold first line): a tinted fill, no frame, at the interface size.
24
+ Neutral by default, because most callouts are emphasis; `data-kind="info|success|warning|danger"`
25
+ makes it a status and `data-tone` a category. Works inside or outside prose.
26
+ - **Specificity** — every rule is `.zx-prose` plus `:where()`, and the stylesheet loads before the
27
+ components, so a badge, an entity reference, or a table placed in prose keeps its own styles,
28
+ while an application's bare element reset cannot undo the rhythm.
29
+ - **Section links** — `proseAnchors(root, options)` ends every `h2`–`h4` with an `id` inside a
30
+ `.zx-prose` under `root` with a small link to itself (`a.zx-prose__anchor`, "Copy link to …").
31
+ It shows while the heading is pointed at or the link has focus (and always on a touch screen or
32
+ under a contrast preference). A click copies the address with the section's hash — the current
33
+ address by default, `href(id)` to build another — and confirms with a tick and a polite "Link
34
+ copied"; it never changes the location, and a middle or modified click is left to the browser.
35
+ Options: `selector`, `label` (`%1` is the heading), `title`, `feedback`, `feedbackDuration`,
36
+ `href`, `oncopy(url, copied)`. It returns `{refresh(), destroy()}`: call `refresh()` after
37
+ re-rendering the content. Headings without an id are skipped — give the ones worth linking a
38
+ stable id. `sectionHref(base, id)` builds the address.
@@ -0,0 +1,115 @@
1
+ # Questionnaire
2
+
3
+ One question at a time, with branching, a path-aware progress bar, and any Zx field type as the answer.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/questionnaire · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A guided, one-question-at-a-time flow: onboarding intake, a service-call checklist, an audit form,
8
+ a feedback survey. The questionnaire owns the ordered items, the active one, the answers,
9
+ validation, progress and navigation; the page, card, dialog or drawer around it owns closing,
10
+ persistence and transport.
11
+
12
+ The created root is a real `<form>`, so `new FormData(questionnaire.toElement())` reads the
13
+ applicable answers. When enhancing a non-form target, pass its contained `<form>` to `FormData`
14
+ or call `toFormData()`. Choices are native radios and checkboxes carrying the item name, and
15
+ arrow keys inside a choice group use the browser's navigation. Three
16
+ things separate it from a `Form` with one `Fieldset` per question: it branches, its answer control
17
+ can be any registered `Field` type, and its validation may be asynchronous.
18
+
19
+ - **Options** — `items: [{name, prompt, description?, section?, required?, multiple?, skippable?,
20
+ choices?, input?, field?, when?, next?, validate?}]`, `answers: {}` and `active: null` (the
21
+ resume pair), `progress: true`, `review: false`, `advance: 'manual'|'auto'`, `shortcuts: true`,
22
+ `allowBack: true`.
23
+ - **Choices** — `[{value, label, description?, icon?, key?, disabled?, exclusive?}]`. `exclusive`
24
+ is the "None of the above" behaviour: picking it clears the rest of a `multiple` item, and
25
+ picking anything else clears it.
26
+ - **Methods** — `setItems()`, `getItems()`, `goTo(name)`, `next()`, `previous()`, `skip()`,
27
+ `submit()`, `getAnswers()`, `getAnswer(name)`, `setAnswers(values, {silent})`,
28
+ `setAnswer(name, value, {silent})`, `getActive()`, `getPath()`, `getProgress()`, `getState()`,
29
+ `toFormData()`, `reset()`, `focus()`, `destroy()`. `next()`, `skip()` and `submit()` return
30
+ **promises** — `next()` because an item's `validate` may be asynchronous, and `skip()` because
31
+ skipping the last question submits. Everything else is synchronous. Async validation applies
32
+ only to the answer and step it started on; editing, navigating, replacing items, resetting, or
33
+ destroying the questionnaire invalidates a pending result. The last answer is validated once,
34
+ and skipping an optional last question does not validate it again.
35
+ - **Events** — `change {name, value, answers}`, `navigate {from, to, reason}` **preventable**,
36
+ `skip {name}`, `invalid {name, message}`, `submit {answers, path}` **preventable**,
37
+ `complete {answers, path}`.
38
+ - **Branching** — `when(answers)` decides whether an item is asked at all, and `next` (a name, or
39
+ `(answer, answers) => name`) decides what follows. Conditions **cascade**: each predicate sees
40
+ only the answers of visible items declared before it, so hiding the VAT question also hides
41
+ whatever depended on the VAT id. An answer to a conditioned-out question is kept internally —
42
+ walk back into the branch and it is still there — but is left out of `getAnswers()` and
43
+ `toFormData()` and native `new FormData(questionnaire.toElement())`, so an abandoned branch
44
+ never submits stale data. Native form data includes applicable answers from earlier steps too. A `next` naming a hidden item
45
+ walks forward from it rather than stranding the reader; naming an item that does not exist
46
+ throws `RangeError`. `next: '$review'` opens the review screen and `next: '$submit'` submits at
47
+ once, wherever the item stands; an item of that name goes first. A `when`, `next` or `validate`
48
+ that is neither a function nor a declarative form (`false`, `[]`, `{}`) reads as absent, so
49
+ `validate: strict && check` is safe.
50
+ - **Declarative logic** — `when`, `next` and `validate` also take plain JSON, so a questionnaire can
51
+ be stored, sent, or written by an agent; the function forms keep working beside them.
52
+ - A condition is `{field, op, value?}` with `op` one of `eq`, `ne`, `in`, `nin`, `gt`, `gte`,
53
+ `lt`, `lte`, `empty`, `filled`, `contains`, combined with `{all: […]}`, `{any: […]}` and
54
+ `{not: …}`, at most four levels deep. A `when` condition may only name items declared before
55
+ it, and sees only their visible answers, so it cascades like a predicate. A `value` is never
56
+ `null`: an unanswered item has no answer to compare, so test it with `empty` or `filled`. A
57
+ `Date` answer compares by its local date against `YYYY-MM-DD`, and by its local
58
+ `YYYY-MM-DDTHH:MM` against a date-time.
59
+ - `next` may be a list of branches, `[{if: condition, goto: name}, …, {goto: name}]`; the first
60
+ match wins, and no match falls through to the next visible item. A branch condition may also
61
+ name the item itself.
62
+ - `validate` may be a list of rules, each one key plus an optional `message`: `{required: true}`,
63
+ `{minLength: n}`, `{maxLength: n}` (characters, or entries of a multiple answer),
64
+ `{minimum: n}`, `{maximum: n}`, `{format: 'date'|'date-time'|'time'|'email'|'uri'}`,
65
+ `{oneOf: [values]}`. Rules other than `required` pass an empty answer; there are no patterns.
66
+ A `{required: true}` rule marks the item required, like `required: true`.
67
+ A rule's own `message` wins; otherwise its text resolves through `msg()` under
68
+ `questionnaire.rule.<rule>` (`minLength`, `maxLength`, `minItems`, `maxItems`, `minimum`,
69
+ `maximum`, `oneOf`, `date`, `dateTime`, `time`, `email`, `uri`), the same keys a Surface's
70
+ fields use.
71
+ - A malformed condition, branch list or rule list throws `TypeError` when the items are set.
72
+ `evaluate(condition, answers)`, `resolveNext(next, answer, answers)`, `checkRules(rules,
73
+ value)` and the shape checks `checkCondition()`, `checkNext()` and `checkRuleList()` are pure
74
+ exports of `src/components/questionnaire/conditions.js`, for evaluating the same JSON elsewhere.
75
+
76
+ ```js
77
+ items: [
78
+ { name: 'method', prompt: 'How will you pay?', required: true,
79
+ choices: [{ value: 'card', label: 'Card' }, { value: 'transfer', label: 'Bank transfer' }],
80
+ next: [{ if: { field: 'method', op: 'eq', value: 'card' }, goto: '$submit' }] },
81
+ { name: 'iban', prompt: 'IBAN', input: {},
82
+ when: { field: 'method', op: 'eq', value: 'transfer' },
83
+ validate: [{ required: true }, { minLength: 15, message: 'An IBAN has at least 15 characters.' }] }
84
+ ]
85
+ ```
86
+ - **Path and progress** — `getPath()` is the questionnaire's memory of the route walked, and
87
+ `previous()` pops it: once a branch has been taken, "previous" is not `index - 1`. `getProgress()`
88
+ returns `{index, answered, total, percent, section}` where `total` is the path plus the items
89
+ still reachable — exact for a static flow, an estimate once a function `next` can jump somewhere
90
+ the forward walk cannot predict.
91
+ - **Field answers** — `field: {type: 'date'|'number'|'zxselect'|'rating'|'upload'|…}` hands the
92
+ answer to a `Field`, so any registered field type works, including ones an application registered
93
+ itself. The `<legend>` already asks the question, so the Field's own label is hidden from sight
94
+ but kept as the control's accessible name unless the item gives `field.label` explicitly; the
95
+ Field draws its own highlight, so a failing answer shows one message, not two.
96
+ - **Validation** — `required` and declarative rules are checked synchronously; a function
97
+ `validate(answer, answers)` may return a message, `null`, or a **promise** of either, and a rejection is reported as its message.
98
+ While the check is pending the root carries `data-state="checking"` and `aria-busy="true"` and
99
+ the actions are disabled.
100
+ - **Review** — `review: true` shows a summary of every answer on the path before submitting, each
101
+ with an Edit that reopens that question; Continue from an edited question comes straight back to
102
+ the review rather than replaying the tail.
103
+ - **Semantics** — the item is a `<fieldset>` and the prompt its `<legend>`; the description and the
104
+ error are associated through `aria-describedby`, the error is a `role="alert"`, and a failing
105
+ item carries `aria-invalid="true"`. `data-state` on the root is
106
+ `asking`, `checking`, `review`, or `complete`. Submitting does not replace the content: it sets
107
+ `data-state="complete"`, hides the actions, and emits `complete`, leaving the thank-you screen to
108
+ the application.
109
+ - **Keyboard** — `1`–`9` then `a`–`z` pick the matching answer, assigned in choice order (an
110
+ explicit `key` is reserved first, so adding one never renumbers the others) and shown as a key
111
+ cap on each choice; the caps are `aria-hidden`, since a screen-reader user moves through the
112
+ group with the arrow keys the radios already provide. `Enter` continues, except in a `multiline`
113
+ input. Shortcuts are suppressed while focus is in a text control. Navigating moves focus to the
114
+ new question's fieldset, which is what gets the prompt announced; failing validation moves it to
115
+ the first answer control instead.
@@ -0,0 +1,19 @@
1
+ # Rating
2
+
3
+ A star rating built as a radio group: one tab stop, arrow-key selection, optional half steps, and a read-only display mode.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/rating · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Star rating built as an APG **radio group**: one radio per selectable step, a single tab stop,
8
+ arrow-key selection. Field type: `rating`.
9
+
10
+ - **Options** — `value: 0` (0 = unrated), `max: 5`, `allowHalf: false` (renders two radios per
11
+ symbol so every reachable value has a nameable control), `clearable: true` (re-selecting the
12
+ current value clears it), `readonly`, `disabled`, `label: 'Rating'`, `icon: 'star'`,
13
+ `labels: []` (per-step accessible names, lowest first), `showValue: false`, `count` (rating
14
+ count shown beside the value), `size: 'sm'|'md'|'lg'`.
15
+ - **Methods** — `get()`, `set(value, {silent})`, `clear()`, `reset()`, `setCount()`,
16
+ `setReadonly()`, `focus()`, `enable()`/`disable()`.
17
+ - **Events** — `change {value}`, `hover {value|null}` (pointer or focus preview; null on leave).
18
+ - **Keyboard** — ←/↓ and →/↑ step, Home selects the first step, End the last, Delete/Backspace
19
+ clear.