@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,34 @@
1
+ # Aurora
2
+
3
+ A CSS-driven, multicolour ambient light field that decorates an existing surface without owning its content or application logic.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/aurora · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A decorative, CSS-driven ambient light field for an existing application surface. Aurora enhances
8
+ the target in place: it does not wrap, replace, or relocate the surface's content, and it does not
9
+ own routing, overlays, or interaction. Its gradients sit behind the target's children, so raised
10
+ Cards and other Liquid Glass surfaces can pick up the underlying colour naturally.
11
+
12
+ - **Options** — `preset: 'source'|'confluence'|'horizon'|'diagonal'|'edge'|'curtain'|'mesh'|'ribbon'|'bloom'`,
13
+ `colors: []` (zero to four concrete CSS colours),
14
+ `intensity: 'subtle'|'balanced'|'vivid'`, `motion: 'none'|'drift'|'flow'`.
15
+ - **Methods** — `setPreset(preset)`, `setColors(colors)`, `setIntensity(intensity)`,
16
+ `setMotion(motion)`.
17
+ - **Palette** — an empty list uses semantic accent, info, success, and warning colours. One colour
18
+ fills all four fields; two alternate; three repeat the second colour in the fourth field; four
19
+ map directly. Network/image-bearing CSS values and palettes longer than four are rejected.
20
+ - **Geometry** — Source starts at the leading chrome; Confluence meets from the corners; Horizon
21
+ forms a shallow top band; Diagonal crosses the surface; Edge preserves a neutral centre; Curtain
22
+ descends as four elongated fields; Mesh binds four fields with a wash in the middle; Ribbon hangs
23
+ two arcs of light from above the top edge; Bloom rises from below the bottom edge. All are
24
+ ordinary CSS gradients, written into `--zx-aurora-image`.
25
+ - **Motion** — `drift` lets the field breathe while two lights wander across it; `flow` turns a disc
26
+ of colour slowly behind it. For either, Aurora adds one `<span class="zx-aurora__motion"
27
+ aria-hidden="true">` as the target's first child, clipped to the surface, and moves its layers by
28
+ transform alone, so nothing repaints. `--zx-aurora-duration` (18s) sets the pace. Readers who ask
29
+ for reduced motion see the static field.
30
+ - **Lifecycle** — `destroy()` removes an owned root or restores every original attribute and child
31
+ of an enhanced target. Content is never rebuilt when a setter changes the effect; `setMotion()`
32
+ adds or removes only the motion element.
33
+ - **Accessibility** — the light field is pointer-transparent and purely decorative. Forced-colour
34
+ and reduced-transparency preferences remove it entirely.
@@ -0,0 +1,37 @@
1
+ # Avatar
2
+
3
+ A stable-size user image with a deterministic fallback — initials on a tone picked from the name — and an optional text-described presence indicator.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/avatar · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A fixed-geometry user image with a deterministic fallback: initials on a tint from the categorical
8
+ tone palette, picked by a stable hash of the name. Image loading or failure never changes layout,
9
+ and the component is decorative by default so adjacent identity text is not announced twice.
10
+
11
+ - **Options** — `src`, `name`, `initials`, `label`, `size: 'sm'|'md'|'lg'|<pixels>` (24 / 32 /
12
+ 40px at the default spacing unit), `shape: 'circle'|'rounded'|'square'`, `tone:
13
+ 'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'|null`, `status:
14
+ 'online'|'away'|'busy'|'offline'|null`, `statusLabel`, `activity:
15
+ 'idle'|'thinking'|'working'|'needs-you'|'blocked'|'offline'|null`, `activityLabel`, `animate: false`, and `phase: null|number`.
16
+ - **Fallback** — no ring; the `--zx-color-tone-*-bg` fill with its `-fg` ink, initials at 0.4× the
17
+ size (never under 10px), weight 600, one initial below 24px. `tone: null` derives the tone with
18
+ `avatarTone(name)` (exported from the module): FNV-1a over the trimmed, NFC-normalised,
19
+ lower-cased name, mapped onto the eight chromatic tones, so a person keeps their colour on every
20
+ screen. `slate`, the neutral, is reserved for an avatar with no name and can be set explicitly.
21
+ The root carries `data-tone`. `avatarInitials(name, limit = 2)` returns the initials.
22
+ - **Agent activity** — `activity` draws what an agent is doing as a dot whose shape differs as
23
+ well as its tone: solid success (working), solid info (thinking), solid warning (needs you), a
24
+ danger square (blocked), a hollow ring (idle), and a dashed ring (offline). Its word ("Needs
25
+ you", or `activityLabel`) joins the accessible name and the dot's tooltip, and the root carries
26
+ `data-activity`. When both are given, `activity` wins over `status`. `animate: true` moves the
27
+ avatar with its activity — idle breathes, thinking sways, working bobs, needs-you leans and
28
+ blinks — in the one `requestAnimationFrame` loop every animated avatar on the page shares: only
29
+ on screen, never while the page is hidden, and back at rest under reduced motion (the system's
30
+ or a `data-zx-motion="reduced"` region). While it is on, the loop owns the root's `transform`. `phase` sets where in its activity's cycle the avatar moves, as a fraction from 0 up to 1
31
+ (whole turns wrap): two avatars of one agent on the same screen — a roster and an inspector —
32
+ at `phase: 0` and `phase: 0.5` move half a cycle apart. `null` derives the phase from the name
33
+ (or the initials), so avatars of the same agent without a phase move in step.
34
+ - **Methods** — `set(values)` (any option above, `phase` included, applied while the avatar moves), `setStatus(status, label?)`,
35
+ `setActivity(activity, label?)`, `getActivity()`, `hasImage()`, `destroy()`.
36
+ - **Accessibility** — set `label` only when the avatar stands alone. Presence is supplementary
37
+ status, not the account's accessible name; supply `statusLabel` when it conveys information.
@@ -0,0 +1,36 @@
1
+ # Badge — `badge(options)` / `badgeGroup(badges)`
2
+
3
+ A status pill or a tag you place yourself: kind says how something is doing, tone what it is, and the shape follows.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/badge · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Factories (not classes) returning a chip: a small, non-interactive `<span>` carrying a semantic
8
+ colour — a status — or, with `tone`, a categorical one — a tag — used for stages, counts, labels,
9
+ and record-header metadata. A badge with no label but a `title` is named for assistive technology
10
+ through `role="img"`; everything else is plain text and needs no ARIA.
11
+
12
+ - **Options** — `label`, `icon` (an icon name, rendered before the label), `kind:
13
+ 'neutral'|'accent'|'success'|'warning'|'danger'|'info'`, `tone:
14
+ 'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'|null`, `variant:
15
+ 'soft'|'solid'|'outline'`, `size: 'md'|'sm'`, `dot` (a leading status dot instead of an icon),
16
+ `title`.
17
+ - **`kind` vs `tone`** — `kind` says how something is doing (status); `tone` says what it is (a
18
+ project, a label, a module) and draws from the `--zx-color-tone-*` palette, which is neither the
19
+ accent nor the status set, so a project tagged red never reads as an error. When `tone` is set it
20
+ decides the colour and `kind` is ignored for it; every `variant` still applies (soft: tinted,
21
+ borderless; solid: filled with the tone's ink; outline). The badge carries `data-tone`. Badges
22
+ are sentence case.
23
+ - **Two shapes, one construction** — a status is a pill (`--zx-radius-full`); give a workflow state
24
+ `dot: true`, a 6px dot centred in the pill's round end. A tag (any badge with a `tone`) has small
25
+ corners (`--zx-radius-md`). Both are one fill and no line, 12px at weight 500 at either size,
26
+ and their height follows the row they sit in: about five ninths of `--zx-row-height` for `md`
27
+ and half of it for `sm` (20px and 18px in the default row), never below a line of their own text,
28
+ so a chip follows the row height setting without making a row taller. `TagPicker` builds its tags with
29
+ `badge()`, so a label reads the same in a list row, a record header and the field that edits it.
30
+ - **Neutral and small** — the neutral soft fill is a wash of the text colour, not an opaque surface
31
+ step, so it stays visible on raised surfaces in the dark theme. `size: 'sm'` fits table cells
32
+ and board cards; it is shorter and tighter, never smaller type. Under `prefers-contrast: more` a
33
+ soft badge gets its edge back, and under forced colours every badge does.
34
+ - **Methods** — none. `badge(options)` → `HTMLSpanElement`, `badgeGroup([badge(…), …])` → a wrapping
35
+ inline row with its own spacing; you own both elements.
36
+ - **Events** — none; a badge is not interactive.
@@ -0,0 +1,34 @@
1
+ # BlockView — `new BlockView(target, options)` / `renderBlocks(blocks, options)`
2
+
3
+ An answer an agent wrote, drawn block by block as prose and written to as it streams.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/block-view · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ An answer an agent wrote, drawn block by block as semantic elements inside `.zx-prose`, and
8
+ written to as it streams. Finished blocks are never redrawn: `append()` and `appendText()` touch
9
+ only the last block, so a reader's selection or focus in an earlier paragraph survives the rest of
10
+ the answer arriving.
11
+
12
+ - **Options** — `blocks: []`, `headingLevel: 3` (the element level of a level-2 `heading` block;
13
+ set it one below the heading that names the answer), `size: 'sm'|'md'` (interface or reading
14
+ size), `streaming: false`, `sources: null` (names the citation buttons by title), `msg`.
15
+ - **Methods** — `setBlocks(blocks, {streaming?})`, `append(block)`, `appendText(text)` (continues
16
+ the last paragraph, or opens one; a blank line in the text starts a new paragraph; a marker split
17
+ across two chunks resolves when its close arrives), `end()`, `stop()` (adds "Stopped here."),
18
+ `setSources(sources)`, `setArtifactState(id, {expanded, controls})` (reflects whether the
19
+ application has the artifact open somewhere), `getBlocks()`, `isStreaming()`, `toText()`,
20
+ `toMarkdown()`, `destroy()`. A single line break in model text is kept (an address, a sign-off); a
21
+ blank line starts a new paragraph.
22
+ - **Events** — `cite {n, source}` from a citation button, `artifact {id}` from an artifact card,
23
+ `end` when a streamed answer is marked finished.
24
+ - **Rendering** — code is a figure with its language, a copy button and a focusable `<pre>`
25
+ (`lines: true` on a code block numbers its lines and wraps long ones under their own indent, for
26
+ code read at length in an inspector),
27
+ coloured for js, ts, json, sql, python, shell and css (anything else stays plain); a wide table
28
+ scrolls inside the answer and becomes a named, focusable region only while it overflows; figures
29
+ are a `<dl>` with tabular numbers; a callout uses `.zx-callout` with its tone as `data-kind`.
30
+ - **Static** — `renderBlocks(blocks, options)` returns a `DocumentFragment` for a transcript or a
31
+ print view: citations are plain superscripts and artifacts plain cards. `blocksToMarkdown(blocks)`
32
+ and `blocksToText(blocks)` export an answer for copying and search.
33
+ - **State** — `data-state` is `streaming`, `done` or `stopped`; the root is `aria-busy` while it
34
+ streams. Streamed text is never inside a live region.
@@ -0,0 +1,20 @@
1
+ # Breadcrumb
2
+
3
+ The trail of ancestors above the current page, with the middle levels collapsing into an ellipsis menu when there is no room for all of them.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/breadcrumb · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ The trail above a hierarchy view. It pairs directly with `Finder` and `TreeView`: feed
8
+ `getNodes()` from a Finder's `change` event into `setItems()` and the two stay in step. When
9
+ `maxVisible` is exceeded the middle collapses behind an ellipsis `MenuButton`, always keeping the
10
+ first and last items.
11
+
12
+ - **Options** — `items: [{name, label, icon?, href?}]`, `maxVisible: 0` (0 shows all),
13
+ `separator: 'chevron'|'slash'`, `rootIcon: null`.
14
+ - **Methods** — `setItems()`, `getItems()`, `push(item)`, `pop()`, `truncateTo(name)`, `destroy()`.
15
+ - **Events** — `select {name, item, index}` **preventable**, including overflow items. An item
16
+ with an `href` renders as a real `<a>` in the trail or overflow, and its
17
+ default is left alone, so ordinary navigation and middle-click still work; without one it renders
18
+ as a `<button>` and only the event fires.
19
+ - **Semantics** — `<nav aria-label="Breadcrumb"><ol>`; the last item is plain text carrying
20
+ `aria-current="page"` and is deliberately not interactive; separators are `aria-hidden`.
@@ -0,0 +1,23 @@
1
+ # Button — `button(options)` / `buttonGroup(buttons)`
2
+
3
+ Factories that return a real `<button>`, in four weights and two sizes.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/button · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Factories (not classes) returning elements, used both standalone and as the
8
+ `buttons: [{ label, kind, action|onclick }]` descriptors Dialog, Modal, Panel, and MasterPanel
9
+ accept.
10
+
11
+ - **`button(options)`** → `HTMLButtonElement`. Options: `label`, `icon` (an icon name), `kind:
12
+ 'default'|'primary'|'danger'|'ghost'`, `size: 'md'|'sm'`, `disabled`, `title`, `onclick`.
13
+ - **Shortcut hints** — `shortcut: {label:'N', keys:'N'}` adds a visible key hint, hover text and
14
+ `aria-keyshortcuts`. The host binds the action and owns editing/modality/permission guards;
15
+ a hint never installs a global handler. Dialog and Sheet footer descriptors accept it too.
16
+ - **`buttonGroup([button(…), …])`** → a container that joins the buttons into one control.
17
+ - **Appearance** — `primary` is the screen's one solid accent and reads the
18
+ `--zx-color-accent-solid*` roles, so in dark it keeps the deep stop with white ink rather than a
19
+ bright slab. A `ghost` button's icon is drawn in `--zx-color-text-subtle` until hovered. A button
20
+ with `aria-pressed="true"` (a Toolbar item with `active`, a view toggle) is a mode, not a pick:
21
+ it stays neutral, never the accent, and is drawn with a stronger fill plus a frame in
22
+ `--zx-color-text-subtle` (3:1 against its neighbours in both themes), so a pressed segment of a
23
+ `buttonGroup` is told apart without relying on the fill alone.
@@ -0,0 +1,68 @@
1
+ # Calendar
2
+
3
+ A dependency-free scheduling surface with agenda, day, week, month, and year views; local-time event layout; range selection; and pointer or keyboard editing.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/calendar · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A dependency-free scheduling surface for operational events. One component owns agenda, day,
8
+ week, month, and year views; local-time range math; timed collision columns; multi-day lanes;
9
+ loading and empty states; pointer range selection; and equivalent pointer/keyboard move and resize
10
+ interactions. Visible ranges use an exclusive `end`, so `dateschange` can be passed directly to a
11
+ windowed loader.
12
+
13
+ - **Options** — `events`, `date`, `view: 'month'`, `views: ['agenda','day','week','month','year']`,
14
+ `locale`, `weekStart: 1`, `weekNumbers: true`, `workweek: false`, `agendaDays: 14`,
15
+ `slotDuration: 30`, `slotMinTime: 0`, `slotMaxTime: 1440`, `scrollTime: 480`, `eventLimit: 3`,
16
+ `selectable: false`, `editable: false`, `eventStartEditable` (`true`/`false` overrides
17
+ `editable` for moving), `eventDurationEditable` (`true`/`false` overrides `editable` for
18
+ resizing; a string or function instead names the per-event resize field, `'durationEditable'`
19
+ by default), `optimistic: true`, `nowIndicator: true`, `now`, `disabled`, `msg`, and `renderEvent(event)`.
20
+ - **Messages** — every key is namespaced `calendar.*`: `calendar.today`, `calendar.previous`,
21
+ `calendar.next`, `calendar.new`, `calendar.agenda`/`day`/`week`/`month`/`year` (the view
22
+ switch), `calendar.viewSwitch`, `calendar.label` (the root's name), `calendar.loading`,
23
+ `calendar.noEvents`, `calendar.allDay`, `calendar.more` and `calendar.weekNumber` (`%1`),
24
+ `calendar.dayEvent`/`calendar.dayEvents`, `calendar.resize`, `calendar.moveStarted`,
25
+ `calendar.resizeStarted`, `calendar.editPreview` (`%1` title, `%2`–`%3` the times),
26
+ `calendar.editCancelled`, `calendar.editCommitted`. Until 6.0 the bare keys of earlier versions
27
+ (`today`, `next`, `loading`, …, and `calendar` for `calendar.label`) are still honoured, read
28
+ right after the namespaced key in the `msg` option and in the host translator; rename them.
29
+ The built-in English now lives in the default catalogue rather than in `Calendar.defaults.msg`,
30
+ so a host translator reaches every calendar string.
31
+ - **Event input** — generic records default to `{id,title,start,end,allDay,color,location,editable,
32
+ durationEditable}`. Every field has a string-or-function reader (`eventId`, `eventTitle`,
33
+ `eventStart`, …); numeric dates use `dateUnit: 'milliseconds'|'seconds'`. Inputs are normalized
34
+ atomically, duplicate IDs and inverted intervals throw, Dates are copied, text is never parsed as
35
+ HTML, and suspicious CSS colour strings are ignored.
36
+ - **Methods** — `getEvents()`, `setEvents()`, `addEvent()`, `updateEvent()`, `removeEvent()`,
37
+ `getDate()`, `setDate()`, `getView()`, `setView()`, `prev()`, `next()`, `today()`,
38
+ `setLoading()`, `focusEvent()`, `destroy()`. `prev()`/`next()` step one visible period and clamp
39
+ the day of month into the target month, so a 29th–31st anchor cannot skip a shorter month; the
40
+ same arithmetic is exported as `calendarPageDate()` and `addCalendarMonths()`.
41
+ - **Events** — `dateschange {view,start,end}`, `viewchange {view,oldView}`, `eventclick`,
42
+ `eventdblclick`, `dateclick {date,allDay,view}`, `select {start,end,allDay,view}`,
43
+ `new {date,view}`, `moreclick {date,count}`, `eventschange {events}`, and cancelable
44
+ `eventchange {event,oldEvent,action,delta,jsEvent,revert}`.
45
+ - **Persistence** — `optimistic: true` updates local events before `eventchange`; call the
46
+ idempotent, version-guarded `detail.revert()` if persistence fails. With `optimistic: false`, the
47
+ component stays controlled: it emits the proposal without changing data, and the application
48
+ applies an accepted response through `updateEvent()` or `setEvents()`. Zx does not send requests.
49
+ - **View layout** — agenda days keep every event in one vertically stacked content column. Month
50
+ uses a continuous seven-day grid with full-height day boundaries and event lanes overlaid below
51
+ the date labels; today is indicated with accent text instead of a decorative edge highlight.
52
+ - **Appearance** — the view switch is one framed control with the current view on the neutral
53
+ `--zx-color-bg-current` fill; weekday headings are sentence case; inner grid lines use
54
+ `--zx-color-border-subtle`; the New button is the solid primary (`--zx-color-accent-solid`).
55
+ - **Pointer editing** — a timed move preserves the point where the event was grabbed and snaps the
56
+ resulting start to `slotDuration`. The lower grip stretches the event in its original day column,
57
+ while pointer capture keeps either interaction active if the pointer leaves the event surface.
58
+ - **Keyboard** — time slots and date grids use arrow-key navigation, Home/End, PageUp/PageDown,
59
+ Enter/Space activation, and roving focus. On an editable event, Space grabs it, arrows propose a
60
+ slot/day move (or change the focused resize grip), Space drops, and Escape cancels. Live status
61
+ text announces the edit and its proposed times.
62
+ - **ZeyOS binding** — `zeyosCalendar()` maps current appointment occurrence rows (`ID`, `name`,
63
+ `location`, `color`, `datefrom`, `dateto`, and association text). `calendarEventToZeyosPatch()`
64
+ returns the base `ID` with Unix-second dates. Pass the instance's `timeZone` to both so an all-day
65
+ appointment is recognised from midnight in that zone and lands on the right days for a viewer
66
+ elsewhere; without it the viewer's own midnight is used. The current server already expands recurrence into
67
+ the requested window; recurrence rules, DAV synchronization, permissions, and routes therefore
68
+ remain in ZeyOS instead of being reimplemented in core.
@@ -0,0 +1,73 @@
1
+ # CardView
2
+
3
+ A compact responsive record collection sharing fields, sort, selection, visibility, order, and serializable state with TableView and KanbanView.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/card-view · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A responsive semantic record collection using the same fields, records, sort, selection, and
8
+ portable state as TableView and KanbanView.
9
+
10
+ - **Options** — the shared RecordView options plus `titleField`, `subtitleField`, `preview`,
11
+ `previewAlt`, `link`, `actions`, `groupBy`, `groupOrder`, `minCardWidth`, `maxColumns`,
12
+ `variant: 'outlined'|'raised'|'filled'`, `loadingCount`, `headingLevel`, `label` (null
13
+ resolves message `cardView.label`, "Card view"), `keyboard: 'tabs'|'roving'` (default `'tabs'`),
14
+ `collapsibleGroups`, `collapsedGroups`, and `renderGroupHeading`.
15
+ - **Methods** — the shared RecordView methods plus `setGroupCollapsed(id, collapsed, {silent})` and
16
+ `getCollapsedGroups()`. **Events** — the shared set plus `recordaction` and
17
+ `groupcollapse {id, collapsed, collapsedGroups}` (also a `statechange` with reason
18
+ `'groupcollapse'`). The view state carries `collapsedGroups`.
19
+ - **Messages** — `cardView.label`, `cardView.sort`, `cardView.sortCards`, `cardView.unsorted`,
20
+ `cardView.sortAscending`/`cardView.sortDescending` (`%1` the field), `cardView.ungrouped`
21
+ ("Ungrouped"), `cardView.groupEmpty` ("No records in this group."), `table.empty` for the empty
22
+ collection ("No records", shared with Table), and the card's own `recordCard.select`,
23
+ `recordCard.actions` (`%1` the title), `recordCard.untitled`, `recordCard.selected`,
24
+ `recordCard.notSelected`. English comes from the default catalogue; override per instance
25
+ through `msg`, or for every instance through `setTranslator()`.
26
+ - **Selection trigger** — `selectionTrigger:'checkbox'` preserves existing selection behavior.
27
+ With `'card'`, selectable backgrounds toggle on click, Enter or Space, Shift+click selects a range,
28
+ and the checkbox is omitted. Links, actions and text selection keep their native behavior. Selection
29
+ remains announced through the card's ARIA description. This option also works in KanbanView.
30
+ - **Cards** — each record is a focusable `<li>` with a native title link, separate secondary
31
+ actions, optional native multi-select checkbox, labelled metadata, and a global ARIA selection
32
+ description that retains valid listitem semantics.
33
+ CardView uses a dense collection rhythm: titles clamp to two lines, previews stay at
34
+ thumbnail/avatar scale, and visible fields become compact labelled metadata chips. Title/subtitle
35
+ fields are not duplicated in metadata unless their field sets `duplicate:true`.
36
+ - **Shared card slots** — a visible field may set
37
+ `view.card.slot: 'eyebrow-start'|'eyebrow-end'|'title-prefix'`. These slots create a semantic
38
+ eyebrow row or put labelled content immediately before (and outside) the title heading/link.
39
+ Unknown slots remain ordinary metadata; visibility and field order still control rendering.
40
+ - **Media and URLs** — `preview` accepts a field ID or callback returning an image URL,
41
+ `{src,alt,fit}`, Node, or null. Executable/non-image schemes are rejected and image failures show
42
+ a stable fallback. Title/action links are normalized; `_blank` links receive `noopener`.
43
+ - **Grouping and layout** — `groupBy` is a field ID or callback; `groupOrder` may deliberately show
44
+ empty groups. Cards reflow through container queries and may cap columns without viewport logic.
45
+ - **Keyboard model** — `keyboard: 'roving'` is the recommended setting for lists; `'tabs'` stays the
46
+ default for compatibility, and makes every card, title link, checkbox, and action its own Tab
47
+ stop (44 stops for 22 selectable cards). `'roving'` follows the WAI-ARIA APG **Grid** pattern with
48
+ row focus, the same model as `Table`: the content is `role="grid"` (`aria-multiselectable` for
49
+ `multi`), each card a `row` with `aria-selected` when selectable, and the collection is one Tab
50
+ stop. Grid rather than listbox because a card holds a link and buttons, which a listbox option
51
+ would flatten. ArrowUp/ArrowDown move to the card above or below — columns are measured from the
52
+ rendered positions, and the column you travel in is remembered — ArrowLeft/ArrowRight within a
53
+ row, Home/End to the first or last card, PageUp/PageDown by a visible page. Enter activates
54
+ (`recordclick`), Space toggles selection in `selectable` modes (activates otherwise),
55
+ Shift+movement extends a `multi` selection, Ctrl/Cmd+A selects every rendered card. Title links,
56
+ checkboxes, and actions get `tabindex="-1"`: they still work with the pointer, and Enter on the
57
+ card is the keyboard route. The current card is kept by record id across `setData`, sorting,
58
+ grouping, and collapsing, and focus is restored with `preventScroll`. Focus shows as an inset
59
+ `--zx-focus-ring` with a transparent outline for forced-colors mode.
60
+ - **Group headings** — `renderGroupHeading({id, label, count, records, collapsed, toggle})` returns
61
+ the heading content in place of the label. `collapsibleGroups: true` makes each heading an APG
62
+ disclosure: a button with `aria-expanded` and `aria-controls` pointing at the group's list, which
63
+ holds the label (and so the custom content, which must then not contain interactive elements).
64
+ A collapsed group keeps its heading and renders no cards; `collapsedGroups` sets the initial
65
+ ones. In the roving model a collapsible heading is a row in the arrow-key order: Enter or Space
66
+ toggles it, ArrowLeft collapses, ArrowRight expands, and collapsing the group of the focused card
67
+ moves focus to its heading.
68
+ - **Interaction** — By default Enter activates a focused card; Space toggles selection. With
69
+ `selectionTrigger:'card'`, Enter also toggles selection. Links, actions,
70
+ selection controls, and selected text do not also activate the card. `recordaction` adds the
71
+ resolved action to the shared event set.
72
+ - **Appearance** — a selected card is a pick and keeps the accent: the `--zx-color-bg-selected`
73
+ tint inside an accent outline. Metadata pairs are borderless tinted chips, not boxes in a box.
@@ -0,0 +1,25 @@
1
+ # Card
2
+
3
+ A semantic content or record surface with optional media, a native title link, secondary actions, and metadata.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/card · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A semantic content or record surface. Card is intentionally not a Panel preset: it has no
8
+ disclosure state or application chrome, and composes as one repeated item in a grid or list. A
9
+ linked Card keeps the root non-interactive and renders a real title anchor as its primary action,
10
+ so buttons and links in its action, content, and footer regions remain valid sibling controls.
11
+
12
+ - **Options** — `title: ''`, `media: null`, `content: null`, `actions: []`, `footer: null`,
13
+ `link: null|string|{href, target?, rel?, onclick?}`, `variant: 'outlined'|'raised'|'filled'`,
14
+ `orientation: 'vertical'|'horizontal'`, `headingLevel: 3`.
15
+ - **Methods** — `setTitle()`, `setMedia()`, `setContent()`, `setActions()`, `setFooter()`,
16
+ `setLink()`.
17
+ - **Content** — media, body, and footer accept text, a Node, a Component, or null. Enhanced target
18
+ children become body content when no explicit content is supplied, and `destroy()` restores the
19
+ target exactly.
20
+ - **Interaction** — `link` stretches the native title anchor across the visual surface; secondary
21
+ controls stay above it and are never nested inside it. A linked card requires a non-empty title.
22
+ Executable/data URL schemes are rejected. Commands belong in `actions`, and selectable cards
23
+ should compose a native checkbox or radio.
24
+ - **Layout** — horizontal media uses the public `--zx-card-media-size` hook and stacks through a
25
+ container query when the card itself becomes narrow.
@@ -0,0 +1,109 @@
1
+ # Chart, `SvgChartAdapter` and `ChartJsAdapter`
2
+
3
+ An accessible engine-neutral chart host.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/chart · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ An accessible, engine-neutral chart host. Zx renders state, canvas, semantic data summary, tokens,
8
+ and lifecycle; an adapter owns the drawing. Two are supplied: `SvgChartAdapter` draws bar, line,
9
+ pie and doughnut charts as SVG and needs nothing else; `ChartJsAdapter` draws any Chart.js type
10
+ with a Chart.js 4 the host supplies (the Zx runtime imports no Chart.js code). Without an adapter
11
+ Chart draws nothing, and the data lives in its summary table alone.
12
+
13
+ ```js
14
+ const chart = new Chart(null, {
15
+ adapter: new SvgChartAdapter(),
16
+ type: 'bar',
17
+ label: 'Invoiced and collected per week',
18
+ data: { labels: ['Week 1', 'Week 2'], datasets: [{ label: 'Invoiced', data: [52300, 61200] }] }
19
+ });
20
+ ```
21
+
22
+ - **Options** — `adapter`, `type: 'bar'`, `data`, engine-specific `chartOptions`, `label`,
23
+ `description`, `summary: 'hidden'|'visible'`, `summaryFormat: null`, `loading`,
24
+ loading/empty/error text, `aspectRatio: '16 / 9'`, and `fill: false`.
25
+ - **Methods** — `setData()`, `setType()`, `update(chartOptions)`, `setAdapter()`, `setLoading()`,
26
+ `setError()`, `clearError()`, `setLabel()`, `setDescription()`, `setSummary()`,
27
+ `setAspectRatio()`, `setFill()`, `resize()`, `refreshTheme()`, `getInstance()`, `destroy()`.
28
+ - **Events** — `ready {instance}`, `update {data, type}`, `select {datasetIndex, index, dataset,
29
+ label, value, nativeEvent}`, and `error {error}`.
30
+ - **When the engine exists** — the engine is created once the chart is in a document, its
31
+ viewport has a size, and it has data and an adapter; `ready` fires then, not necessarily inside
32
+ the constructor. A chart constructed on a target that is already laid out mounts synchronously;
33
+ one built with `null` and appended later mounts when the browser reports its size.
34
+ `getInstance()` and `resize()` do not wait: called after the chart is appended, they create the
35
+ engine on the spot, and `getInstance()` returns null while there is none. A chart that is
36
+ loading, empty, or in error has no engine. Where there is no `ResizeObserver` or no layout at
37
+ all (jsdom), nothing can report a size and the engine is created as soon as there is data.
38
+ - **State changes and the engine** — `setData()` clears both the loading state and an error.
39
+ `setLoading(true)` and `setError()` destroy the engine; the next `setData()`,
40
+ `setLoading(false)` or `clearError()` creates a new one and fires `ready` again, so do not hold
41
+ on to an instance across them. `setAdapter()` replaces the engine as well.
42
+ - **Sizing** — by default the viewport takes the width it is given and derives its height from
43
+ `aspectRatio` (`setAspectRatio()` changes it; null restores the default), never less than
44
+ `--zx-chart-min-block-size` (220px unless set, on the chart or any ancestor). `fill: true` (or
45
+ `setFill()`) takes the block size of the container instead: the root is 100% tall, the viewport
46
+ takes what the description and a visible summary leave, `aspectRatio` is not used, and there is
47
+ no minimum unless `--zx-chart-min-block-size` sets one. The container needs a height of its
48
+ own. The chart follows its viewport; `resize()` is for an engine that needs telling after
49
+ something else changed.
50
+ - **Theme** — the chart resolves `--zx-color-text`, `--zx-color-border` and the categorical
51
+ palette `--zx-color-chart-1`…`-8` on its root and hands them to the adapter as values. It does
52
+ so again by itself when a `data-zx-theme` or `data-zx-preset` attribute changes anywhere in the
53
+ document, when the system colour scheme or contrast preference changes, and when the chart is
54
+ shown again after being hidden or moved. `refreshTheme()` is only for changes none of those
55
+ cover: a stylesheet swap, a class, an inline custom property.
56
+ - **Adapter contract** — `adapter.create(canvas, {type, data, options, theme, reducedMotion, onSelect})`
57
+ returns `{update(spec), resize(), destroy(), instance?}`; `update(spec)` is called for new data,
58
+ type or options and whenever the theme or the motion preference changes. An adapter that draws
59
+ an element of its own implements `mount(viewport, spec)` instead, with the same spec and handle:
60
+ Chart calls `mount()` when an adapter has it, `create()` otherwise. The canvas then stays in
61
+ place, empty, keeping the chart's accessible name and description; what `mount()` appends lies
62
+ over it, is presentational (`aria-hidden="true"`), and goes with the handle's `destroy()`. `spec.theme` is
63
+ `{color?, borderColor?, palette}`: text colour, grid and axis colour, and the series colours in
64
+ order (empty where the tokens are not defined; series beyond the eighth start over).
65
+ `spec.options` is the application's `chartOptions` over `color` and `borderColor`, the same two
66
+ strings in the shape Chart.js reads. Every colour is `#rrggbb` when opaque and
67
+ `rgba(r, g, b, a)` when translucent — never `color()`, `oklch()`, `light-dark()` or a `var()` —
68
+ so an engine with its own colour parser reads it. Implementations must destroy engine
69
+ resources and must not retain the component after teardown. `reducedMotion` is true under the
70
+ system preference or inside a `data-zx-motion="reduced"` region, and an adapter must then turn its
71
+ engine's animation off; Chart watches for the answer changing and updates the mounted engine.
72
+ - **`SvgChartAdapter`** — `new SvgChartAdapter({animation: true, legend: null})` draws `bar`
73
+ (grouped), `line`, `pie` and `doughnut`; any other type puts the chart in its error state, and
74
+ `SvgChartAdapter.supports(type)` answers first. A value is a number, or the `y` (else `r`) of a
75
+ point object; null and anything not finite is a gap — no bar, a break in the line, no slice.
76
+ Bars stand on zero; a line's scale spans its data; ticks fall on 1, 2 or 5 × 10ⁿ and are written
77
+ compactly in the active language ("250K"). Pie and doughnut draw one ring per dataset, a slice
78
+ per positive value. The legend lists the series (the labels, for pie and doughnut) when there are
79
+ two or more and for the arc kinds; `legend: true|false` forces it. Colours come through CSS from
80
+ `--zx-color-chart-1`…`-8`, so a theme or preset switch repaints without a redraw; a dataset's own
81
+ colour keys are not read, and series past the eighth take the palette again, lighter (dashed, for
82
+ a line). The plot's `viewBox` is its size in pixels, so text keeps its size: it scales with the
83
+ viewport and is laid out again on the next resize, thinning category labels rather than
84
+ overlapping them. Each mark has a `<title>` ("Week 1 · Invoiced: 52,300") and pressing one fires
85
+ `select` with the usual detail; there is no keyboard path through the marks — the summary table is
86
+ the accessible one. The first drawing grows in unless motion is reduced (system, or a
87
+ `data-zx-motion="reduced"` region) or `animation` is false; per chart, `chartOptions.animation` and
88
+ `chartOptions.legend` decide over the adapter's options. `getInstance()` returns the drawing
89
+ element. One adapter serves any number of charts.
90
+ - **`ChartJsAdapter`** — construct it with a Chart.js constructor or namespace:
91
+ `new ChartJsAdapter(window.Chart)`. The documentation pins Chart.js 4.5.1 as a development dependency and copies it to its
92
+ self-hosted vendor assets during the website build; `package.json` has no runtime dependencies and application builds explicitly choose how
93
+ the engine is loaded. Under reduced motion it sets `animation: false`, over any animation the
94
+ application configured. A dataset that names neither `backgroundColor` nor `borderColor` is
95
+ coloured from the theme palette: one colour per series (a bar filled with it, a line, radar or
96
+ point series stroked with it and filled at half opacity), or one per value for `pie`,
97
+ `doughnut` and `polarArea`. A dataset that names either is left exactly as written.
98
+ - **Accessibility** — the canvas always has a name and optional description, whichever adapter
99
+ draws, while synchronized labels and dataset values live in a semantic table.
100
+ `summary: 'hidden'` keeps it visually hidden for assistive technology; `'visible'` makes exact
101
+ values part of the interface. `setLabel()`
102
+ renames the canvas and the table's caption, `setDescription()` and `setSummary()` change the
103
+ other two.
104
+ - **Summary values** — a number is written for the active language (the chart's `lang`, else
105
+ `getLanguage()`) with grouping and up to twelve significant digits: `1234567.5` reads
106
+ "1,234,567.5" and `0.1 + 0.2` reads "0.3". For a point object the value is its `y`, else its
107
+ `r`. `summaryFormat(value, context)` returns the text of one cell instead — a currency, a unit,
108
+ a percentage — with `context` `{dataset, datasetIndex, index, label, raw, formatted}`, where
109
+ `formatted` is the default text; returning null or undefined keeps it.
@@ -0,0 +1,16 @@
1
+ # CheckButton
2
+
3
+ A button that stays pressed — a checkbox with the presence of a toolbar control.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/check-button · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Two-state pressed button on a native `<button aria-pressed>`. The check indicator has a glyph in
8
+ both states — an empty box when off, a check when on — so an unpressed or disabled button still
9
+ reads as a two-state control. Pressed, the button goes neutral (the `--zx-color-bg-current` fill,
10
+ a stronger border, the text colour); only the check glyph, the mark, keeps the accent.
11
+
12
+ - **Options** — `label: '' | [onLabel, offLabel]`, `checked: false`, `icon: true`,
13
+ `disabled: false`.
14
+ - **Methods** — `get()`, `set(checked, {silent})`, `toggle()`, `setLabel()`, `enable()`/`disable()`.
15
+ - **Events** — `change {checked}`, fired only on a real state change.
16
+ - **Keyboard** — Space/Enter.
@@ -0,0 +1,19 @@
1
+ # Checklist
2
+
3
+ A searchable list of checkboxes for picking several records at once, with a static or an asynchronously loaded set of items.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/checklist · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Searchable multi-check list with optional async loading.
8
+
9
+ - **Options** — `items`, `valueKey: 'ID'`, `labelKey: 'name'`, `checkedKey: 'on'`, `search: true`,
10
+ `height: 280`, `defaultChecked: false`, `label: null` (heading text and the group's accessible
11
+ name; null uses the `checklist.label` message), `disabled: false`, `hideLabel: false` (leaves out
12
+ the heading; the group keeps its text as `aria-label`), `load: async ()=>items`.
13
+ - **In a Field** — field type `checklist` draws no heading of its own: the field's label names the
14
+ group (`aria-labelledby`).
15
+ - **Methods** — `setItems()`, `getValues()`, `setValues(ids)`, `checkAll()`/`uncheckAll()`,
16
+ `search(query)`, `reload()`, `setLabel(text)`, `enable()`/`disable()`, `isDisabled()`. Disabled,
17
+ the search field and every checkbox are disabled (`aria-disabled="true"` on the group) through
18
+ searches, `setItems()` and reloads; values can still be set from code.
19
+ - **Events** — `change {values}`, `loaded`.
@@ -0,0 +1,38 @@
1
+ # CodeEditor — structured text without an editor dependency
2
+
3
+ A dependency-free, text-safe source editor with native undo, IME behavior, indentation and line/column feedback.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/code-editor · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A textarea that behaves like a source editor, and deliberately not more than that: native undo,
8
+ native IME, and no syntax engine. It never executes or injects the value, so it is the safe
9
+ surface for structured text — templates, queries, configuration — while rich HTML authoring
10
+ stays a separate policy decision.
11
+
12
+ - **Options** — `value`, `name`, `language` (shown to the reader and exposed as data),
13
+ `label`, `placeholder`, `rows` (clamped 2–100), `indent: '\t'` (inserted by Tab, removed by
14
+ Shift+Tab; `' '` for two spaces, `''` to leave Tab alone), `wrap: 'off'|'soft'|'hard'`,
15
+ `spellcheck`, `readOnly`, `disabled`, `status` (the line/column readout).
16
+ - **Methods** — `setValue()`, `getValue()`, `setLanguage()`, `setReadOnly()`,
17
+ `enable()`/`disable()`, `getInput()` (the
18
+ native textarea: the element that carries the name, validity and description, and the one a
19
+ `<label for>` names), `setHighlight(message, kind = 'danger')`, `clearHighlight()`, `focus()`.
20
+ - **Events** — `input {value}`, `change {value}`, `invalid {message}`.
21
+ - **Tab** — while `indent` is non-empty the editor captures Tab: Tab inserts the indent at the
22
+ caret or indents every selected line, Shift+Tab outdents them, and focus stays in the editor.
23
+ That is what a code surface has to do and what makes it a keyboard trap if nothing else is
24
+ arranged — so Escape releases the capture until the next keystroke in the editor: Escape then
25
+ Tab (or Shift+Tab) leaves the field, and any other key, or leaving the editor, restores
26
+ indentation. `indent: ''` switches the capture off: Tab and Shift+Tab move focus as in any other
27
+ field and nothing is indented. Tab with Ctrl, Alt or Meta, and Tab in a read-only or disabled
28
+ editor, are never captured.
29
+ - **Error state** — a standalone editor reports a validation or status message the way a Field
30
+ does. `setHighlight(message, kind)` shows it under the text and reflects `kind`
31
+ (`'danger'|'warning'|'success'`) as `data-state` on the root. `'danger'` is the error state: the
32
+ textarea gets `aria-invalid="true"`, the message is announced as an alert, the frame takes the
33
+ danger colour, and `invalid {message}` is emitted. The message describes the textarea
34
+ (`aria-describedby`) for as long as it is shown; an empty message, or `clearHighlight()`, clears
35
+ it.
36
+ - **In a Form** — a `code` field adapter is registered by `registerFieldAdapters()`. Set the
37
+ Field's own message there (`field.setHighlight()`), not the editor's: the Field labels the
38
+ textarea, marks it invalid and describes it with its message, and the editor's frame follows.