@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,82 @@
1
+ # Design tokens
2
+
3
+ Two tiers of CSS custom properties.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/tokens · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Two tiers of CSS custom properties. Dark mode is a pure token/attribute swap
8
+ (`[data-zx-theme="dark"]`), there is one geometry derived from `--zx-space-unit` and
9
+ `--zx-radius`, and `tests/lint-tokens.js` forbids raw colour literals and tier-1 colour references
10
+ in component CSS.
11
+
12
+ - **Tier 1** — the global palette and primitives in `styles/tokens/global.css`: `--zx-gray-0…950`,
13
+ `--zx-emerald-*` (the brand ramp the default accent reads), the status ramps
14
+ `--zx-green/red/amber/blue-*` (green is a yellow-green, deliberately apart from the brand), the
15
+ tone ramps `--zx-tone-<hue>-300/500/700` — none of them referenced by components — plus the
16
+ spacing scale (`--zx-space-unit`, `--zx-space-1…8`), the radius scale (`--zx-radius`,
17
+ `--zx-radius-sm/md/lg/xl/full`), the type scale (`--zx-text-xs…3xl`, 12–30px), weights
18
+ (`--zx-weight-medium` 500, `--zx-weight-semibold` 600), tracking (`--zx-tracking-tight`
19
+ -0.01em, set on `.zx-scope`; `--zx-tracking-title` -0.015em), shadows, and motion
20
+ (`--zx-dur-fast` 120ms, `--zx-dur-base` 180ms — both 0ms in a reduced-motion region — and the
21
+ curves `--zx-ease`, `--zx-ease-spring`, `--zx-ease-drawer`).
22
+ - **Tier 2** — the semantic set, the only tokens components may use: `--zx-color-*`,
23
+ `--zx-control-*`, `--zx-focus-ring`, `--zx-surface-shadow` (the contact shadow of a resting
24
+ surface: a panel, an outlined card in a lane, a slider thumb), `--zx-overlay-shadow`,
25
+ `--zx-drag-shadow` (an item being dragged; its own value in dark, with a faint light rim). The
26
+ lint also rejects the accent ramp `--zx-accent-*`, the module palette `--zx-module-*`, and the
27
+ raw `--zx-shadow-*` steps in component and layout CSS, and any `outline: 0`/`outline: none`:
28
+ forced-colors mode drops the box-shadow focus ring, so components make the outline transparent
29
+ and `styles/base.css` repaints it in a system colour there. The roles that carry the visual
30
+ language:
31
+ - **Columns.** `--zx-color-bg-surface` is the working canvas; `--zx-color-bg-chrome` is the
32
+ navigation and inspector tone beside it (one step below the canvas in light, between page and
33
+ canvas in dark), so tone rather than a line separates them. Dividers inside a column use
34
+ `--zx-color-border-subtle`; `--zx-color-border` is for frames.
35
+ - **Current vs selected.** Where you *are* — the active navigation item, the current row, the
36
+ open node, the active view — is neutral: `--zx-color-bg-current` (translucent text, about 8%,
37
+ so it works on any column), text colour, weight 600. Hover is `--zx-color-bg-hover`, about half
38
+ as strong. What you have *picked* keeps the accent tint `--zx-color-bg-selected`.
39
+ - **Text.** `--zx-color-text`, `--zx-color-text-muted` (secondary text, 4.5:1 on every column and
40
+ on a current row), `--zx-color-text-subtle` (icons and non-essential meta, 3:1),
41
+ `--zx-color-text-placeholder`.
42
+ - **Solid accent.** `--zx-color-accent-solid` (`-hover`, `-active`) with
43
+ `--zx-color-on-accent-solid` is the one primary action per screen: the 600 stop with white ink in
44
+ both themes. `--zx-color-accent` is the accent as text, marks, and focus (600 in light, 400 in
45
+ dark) and pairs with `--zx-color-on-accent` when something is filled with it.
46
+ - **Status.** `--zx-color-success/warning/danger/info` and their `-bg` fills mean state and
47
+ nothing else; they ship with an icon or a word.
48
+ - **Tones.** `--zx-color-tone-{blue,teal,green,amber,orange,red,pink,violet,slate}-bg` and `-fg`:
49
+ categorical colour for tags, chips, icon tiles, and avatars — neither the accent nor a status. A
50
+ soft fill (13% of the tone over the surface in light, 20% in dark) with ink at 4.5:1 or better.
51
+ - **Chart series.** `--zx-color-chart-1…8`, assigned in order, never cycled: blue, orange, teal,
52
+ amber, pink, green, violet, red. Neighbours stay apart under red-green colour-vision deficiency
53
+ and every series clears 3:1 as a mark on the light and the dark surface; the list does not open
54
+ on the accent.
55
+ - **Component styling hooks** — a short, deliberately small set of component-level custom
56
+ properties for restyling one component without touching its internals. Each falls back to the
57
+ semantic token it replaces, so setting none of them changes nothing:
58
+ `--zx-table-header-bg`, `--zx-table-row-hover-bg`, `--zx-table-row-selected-bg`,
59
+ `--zx-table-border-color`, `--zx-table-pin-bg` (the opaque base of pinned columns; the header
60
+ background unless set), `--zx-button-radius`, `--zx-panel-header-bg`, `--zx-message-offset`
61
+ (the distance of floating messages from the viewport edge; `--zx-space-4` unless set).
62
+ `--zx-chart-min-block-size` is public as well, with a fixed 220px default rather than a token.
63
+ Reach for the least specific override that works: a global semantic token first, one of these
64
+ second, an internal selector never. Component CSS declares many other `--zx-<component>-*`
65
+ properties — those are internal geometry, not API, and will change without notice.
66
+
67
+ **Base typography.** `.zx-scope` sets Inter with `--zx-tracking-tight` and the `cv11` feature (the
68
+ single-storey a, chosen because it reads rounder and calmer at 13–14px; fonts without it ignore it).
69
+
70
+ **Quiet fields.** Put `data-zx-fields="quiet"` on a property panel, an inspector, or an inline
71
+ record: native inputs, selects, and textareas inside it drop their border and fill until hover
72
+ (`--zx-color-bg-hover`) or focus (the normal border, the control fill, and the focus ring), so values
73
+ read as text rather than as a wall of boxes. Read-only and disabled fields stay quiet. The rules have
74
+ zero specificity, so a component's own input styling still wins.
75
+
76
+ **Revealed actions.** Mark a row or a section heading `data-zx-reveal-host` and a secondary action
77
+ inside it `data-zx-reveal`: the action rests invisible and appears while the host is pointed at,
78
+ holds focus, is current or selected, or has a menu open. It keeps its space, so nothing shifts, and
79
+ stays in the tab order, so focusing it shows it. On touch screens, under `prefers-contrast: more`
80
+ and in forced colours it is always visible. Use it only for repeated, secondary per-row actions
81
+ that are reachable another way (a context menu, a keyboard shortcut); a primary action stays
82
+ visible. Hosts do not nest.
@@ -0,0 +1,26 @@
1
+ # Toolbar — APG toolbar
2
+
3
+ One tab stop, arrow-key navigation, and an overflow menu that swallows what no longer fits.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/toolbar · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A single non-wrapping row of controls that is one tab stop: arrows move between the controls, and
8
+ what no longer fits collapses into a trailing overflow menu. Items are `button()` descriptors,
9
+ ready-made Elements, or `'-'` for a separator; a `ResizeObserver` remeasures the row, hides the
10
+ items that overflow — removing them from the tab order and the roving group — and mirrors them into
11
+ a `MenuButton`, where choosing one activates the original control.
12
+
13
+ - **Options** — `items: [Element | '-' | {name, label, icon, kind, size, disabled, title, active,
14
+ onclick}]`, `align: 'start'|'end'|'between'`, `label` (accessible name, by default the `toolbar.label` message),
15
+ `overflow` (default `true`), `overflowLabel` (by default the `toolbar.more` message), `dense`; `null` gives either
16
+ no name. `active` renders the item as a pressed toggle (`aria-pressed`).
17
+ - **Methods** — `setItems()`, `getItem(name)`, `enable(name)`, `disable(name)`,
18
+ `setActive(name, active?)`, `destroy()`.
19
+ - **Events** — `action {name, item}`, emitted for descriptor-built items in addition to their own
20
+ `onclick`, from the row and from the overflow menu alike.
21
+ - **Keyboard** — Tab reaches the toolbar once; ArrowLeft/ArrowRight move between controls and wrap,
22
+ in visual order under `dir="rtl"`; Home/End jump to the first and last control. A text field, select,
23
+ or contenteditable item keeps its own keys: Home/End and the arrows move its caret, and an arrow
24
+ moves on to the neighbouring control only once the caret is at that edge of the text.
25
+ - **Pressed items** — an item with `active` renders `aria-pressed="true"` and takes Button's
26
+ neutral pressed fill and frame, never the accent.
@@ -0,0 +1,16 @@
1
+ # Tooltip
2
+
3
+ A description bubble that stays visible over its anchor or bubble: hover opens it after a beat, keyboard focus opens it at once, and touch leaves it alone.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/tooltip · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A description bubble anchored to another element. The panel is a manual popover positioned by the kernel's `position()`, so it escapes clipping and stacking contexts and flips near a viewport edge; it carries `role="tooltip"` and a generated id, and the anchor's `aria-describedby` includes its id only while it is open — opening adds the id to whatever the attribute holds then, and closing removes only that id, so ids added by others (a field error) stay. The bubble contains no focusable controls and stays visible while the pointer is over either the anchor or the bubble. Keyboard focus on the anchor independently keeps it visible. Hover opens it after `delay`; keyboard focus opens it immediately, because a keyboard user cannot hover a moment longer; a touch pointer never opens it, since a bubble with no "move away" gesture would simply stick. Only one is ever visible at a time, which falls out of the dismissal rules rather than a registry.
8
+
9
+ - **Options** — `content` (string, Node, or a function re-evaluated on every open), `placement`
10
+ (`'top'` default, plus top/bottom/left/right and their start/end variants), `offset` (6), `delay`
11
+ (400), `hideDelay` (80), `maxWidth` (260; a number is pixels, a string is any CSS length),
12
+ `trigger` (`'both'` default, or `'hover'`, `'focus'`, `'manual'` — `manual` installs no listeners
13
+ at all and leaves everything to the methods), `disabled` (false).
14
+ - **Methods** — `show()`, `hide()`, `toggle()`, `isOpen()`, `setContent(content)`, `enable()`, `disable()`, `isDisabled()`, `getAnchor()`, `destroy()`. Convenience factories: `tooltip(anchor, contentOrOptions)` takes either a content value or a full option object, and `describe(anchor, text)` is the one-liner replacement for a `title` attribute. Both return the instance.
15
+ - **Events** — `open`, `close`. Both fire only on a real transition, so a `show()` on an open tooltip is silent.
16
+ - **Keyboard** — Focusing the anchor opens the tooltip at once; it closes after both focus and hover have left the anchor and bubble. `Escape` closes it without moving focus (WCAG 1.4.13 "dismissible") — and only it, when it is the topmost open overlay, so one press never closes a tooltip and the menu beneath it. A `pointerdown` anywhere closes it, and focus that arrives with a click does not re-open it. A closed tooltip listens to nothing outside its anchor; an open one is an entry on the shared overlay stack.
@@ -0,0 +1,48 @@
1
+ # TreeView
2
+
3
+ A hierarchy following the APG tree pattern: arrow-key navigation, expand and collapse, typeahead, lazy children, and optional tri-state checkboxes.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/tree · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Hierarchical tree implementing the APG **tree** pattern. Rows render as a flat list carrying
8
+ `aria-level`/`aria-setsize`/`aria-posinset` (the flattened variant the APG allows) rather than
9
+ nested `role="group"` containers. The component clones `items`, so lazily loaded children never
10
+ mutate the caller's data.
11
+
12
+ - **Options** — `items` (nested), `valueKey: 'ID'`, `labelKey: 'name'`, `childrenKey: 'children'`,
13
+ `expanded: []`, `selection: 'single'|'multi'|false`, `selected: []`, `checkboxes: false`
14
+ (tri-state), `checked: []`, `icons: true`, `renderLabel`, `load: (node)=>Promise<children>`
15
+ (lazy children; mark a branch with `hasChildren: true` — it counts as open only once its
16
+ children are loaded, so → and `toggle()` load it, `*` loads and opens lazy siblings, and
17
+ `expandAll()`, filtering and `expanded` leave unloaded branches closed), `filter`, `emptyText`, `height`,
18
+ `rowActions: (node) => actions`, `moreLabel`. Unset, `label`, `emptyText` and `moreLabel` read the
19
+ `tree.label`, `tree.noItems` and `tree.more` messages; `tree.empty` still wins over `emptyText`, and
20
+ `emptyText: null` shows no text.
21
+ - **Row actions** — `rowActions(node)` returns the row's commands: `{icon, label, onSelect(node),
22
+ disabled?, danger?}` descriptors, or nodes of your own placed as given. One or two show as icon
23
+ buttons at the row's end; with more, the first shows and the rest fold into a "More actions"
24
+ menu (a node never folds). They rest out of sight and keep their room, and show while the row is
25
+ pointed at, focused or selected, while its menu is open, and always on a touch screen, under a
26
+ contrast preference and in forced colours — the `data-zx-reveal` utility. Every descriptor is
27
+ also in the row's context menu (right-click, Shift+F10, the Menu key), and each control is named
28
+ after its action and its row ("Add sub-page: Onboarding"); the row's own name stays its label.
29
+ Use them only for repeated, secondary commands that are reachable another way too.
30
+ - **Methods** — `setItems()`, `getItems()`, `getNode(id)`, `getPath(id)`, `setFilter(query)` (keeps
31
+ matching nodes' ancestors and opens the surviving branches),
32
+ `expand(id)`/`collapse(id)`/`toggle(id)` (async — they await the loader),
33
+ `expandAll()`/`collapseAll()`, `reveal(id)`, `select(id, {additive})`,
34
+ `getSelection()`/`setSelection()`/`clearSelection()`, `check(id, checked)`,
35
+ `getChecked({leavesOnly})`, `setChecked()`, `focusNode(id)`.
36
+ - **Events** — `select {node, id, ids}`, `expand`, `collapse`, `activate {node, id}` (Enter or
37
+ double-click), `check {ids, node}`.
38
+ - **Keyboard** — ↑/↓ move, → expands then descends, ← collapses then ascends, Home/End, Enter
39
+ activates, Space selects or toggles the checkbox, `*` expands every sibling, typing jumps to the
40
+ next match. A typed character's default action is prevented, so find-as-you-type and page
41
+ shortcuts do not act on it too; typing into a control inside a row is left to that control.
42
+ With row actions, Tab from the focused row walks that row's actions and then leaves the tree
43
+ (Shift+Tab comes back); keys pressed on an action belong to it, and clicking one neither selects
44
+ nor focuses the row.
45
+ - **Appearance** — the selected node of a single-selection tree is where you are: the neutral
46
+ `--zx-color-bg-current` fill, the text colour, a semibold label. A `selection: 'multi'` tree is a
47
+ set of picks and keeps the accent tint. Icons, folders included, are drawn in
48
+ `--zx-color-text-subtle`; badges are plain muted counts.
@@ -0,0 +1,21 @@
1
+ # truncate()
2
+
3
+ Clamps text to a number of lines and hands the cut-off text back on hover — because a cell that silently drops the end of a value is a data-loss bug wearing a layout costume.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/truncate · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Clamps text to a number of lines and gives the cut-off text back on hover. The tooltip half is
8
+ what makes it more than a CSS class: a cell that silently drops the end of a value is a data-loss
9
+ bug wearing a layout costume, while a tooltip that is always there is noise.
10
+
11
+ - **Signature** — `truncate(target, {lines, title})` → `{update, isTruncated, destroy}`.
12
+ - **Options** — `lines: 1` (1–10; one line ends in an ellipsis, more clamp the block),
13
+ `title: true` — sets a native `title` **only while the text is actually cut off**, re-measured
14
+ through a `ResizeObserver` on every resize, and restores any previous title on `destroy()`.
15
+ - **Controller** — `update()` re-measures and returns the current state, `isTruncated()` reports
16
+ the last measurement, `destroy()` removes the class, the observer, and any title it set.
17
+ - **Exported helper** — `isTruncated(element)` compares scroll and client sizes on both axes (a
18
+ single line runs out of width, a clamped block runs out of height) with a one-pixel tolerance
19
+ for the sub-pixel difference fractional zoom produces.
20
+ - **Class** — `.zx-truncate` alone does the clamping from static markup with no JavaScript;
21
+ `data-lines` plus `--zx-truncate-lines` select the multi-line form.
@@ -0,0 +1,14 @@
1
+ # ValueList
2
+
3
+ A chip editor for a list of strings, with per-value validation and drag or keyboard reordering.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/value-list · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Tag/chip input. Enter adds a value, Backspace on an empty input removes the last one, and dragging
8
+ or Ctrl+Arrow reorders.
9
+
10
+ - **Options** — `values: []`, `placeholder`, `deletable: true`, `sortable: true`, `unique: true`,
11
+ `validate: (str)=>bool|string`.
12
+ - **Methods** — `getValues()`, `setValues()`, `addValue()`, `removeValue()`, `focus()`,
13
+ `enable()`/`disable()`.
14
+ - **Events** — `change {values}`, `add {value}`, `remove {value}`.
@@ -0,0 +1,56 @@
1
+ # ViewSettings — the content of a view-settings drawer
2
+
3
+ The content of a view-settings drawer: arrange and hide the shown fields, add a hidden one back, and choose grouping and the board’s columns and swim lanes.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/view-settings · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Which fields a record view shows and in what order, which hidden field to bring back, what the
8
+ records are grouped by, and which fields a board uses for columns and swim lanes. It is content,
9
+ not a container: put it in a `Sheet`, a `Dropdown`, or a settings page.
10
+
11
+ - **Options** — `fields: ViewSettingsField[]` (a `ViewField` plus `type`, `groupable`, `locked`),
12
+ `fieldOrder`, `hiddenFields`, `groupBy`, `grouping: boolean|{fields?}`,
13
+ `board: {columnBy, swimlaneBy, showEmptyColumns?, fields?}|false` (`fields` restricts the
14
+ Columns and Swim lanes choices; default: the Group by fields), `sections` (order and presence of
15
+ `'fields'|'grouping'|'board'`), `types: Record<type, {icon?, label?}>`, `searchThreshold` (8),
16
+ `headingLevel` (3), `label`, `msg`.
17
+ - **Methods** — `getState()`, `setState(partial, {silent})`, `setFields()`, `getFields()`,
18
+ `showField()`, `hideField()`, `moveField(id, index)`, `bind(view, {board?})`, `unbind()`,
19
+ `focus()`, `destroy()`.
20
+ - **Events** — `change {state, reason: 'order'|'visibility'|'group'|'board'}`,
21
+ `fieldorderchange {order}`, `fieldvisibilitychange {visible, hidden}`, `groupchange {field}`,
22
+ `boardchange {board}`.
23
+ - **State** — `{fieldOrder, hiddenFields, groupBy, board}`: JSON-safe, ready to persist.
24
+
25
+ The shown fields are listed in order, each with a drag handle, its type glyph, and a hide button;
26
+ the hidden ones follow with an explicit **Add** button, which puts the field at the end of the
27
+ shown list. Above `searchThreshold` fields a search narrows the hidden list (label, id, and type
28
+ name, ignoring case and accents) and Enter adds the first match. A `locked` field — the record
29
+ title — has neither handle nor hide button and keeps its place while the others move around it.
30
+ `locked` governs only what the panel offers: a bound view has no such notion, so a locked field the
31
+ view hides itself appears under Hidden with Add like any other. The last shown field cannot be
32
+ hidden.
33
+
34
+ Rows reorder by pointer (mouse, touch, and pen share one path: drag the handle, an insertion line
35
+ shows where it lands, Escape cancels; near the top or bottom edge of the nearest scroll container,
36
+ the container scrolls) and by keyboard on the focused handle: ArrowUp/ArrowDown
37
+ move one step, Home/End to the ends, Space or Enter picks the row up and drops it, Escape returns
38
+ it. Every move is announced in a polite live region ("Owner moved to position 3 of 6"). A redraw
39
+ from outside — `setState()`, `setFields()`, a bound view's change — cancels a pick-up or drag in
40
+ progress (announced) and keeps focus on the same field's control.
41
+
42
+ The type glyph comes from a built-in map that `types` extends: text, number (int, float,
43
+ percent), money, date, datetime, time, boolean, select (enum), status, priority, entity, tags,
44
+ url, email, image, file, rating. The type name is the glyph's `title` and visually hidden text,
45
+ so it is seen and heard. Grouping and the board offer fields with `groupable !== false` and a
46
+ discrete type (text, select, status, priority, boolean, entity), or `groupable: true`;
47
+ `grouping.fields` restricts the Group by choices.
48
+
49
+ `bind(view)` connects a `TableView`, `CardView`, or `KanbanView`: it reads the view's fields and
50
+ state, pushes order and visibility through `setFieldOrder()`/`setFieldVisible()`, and follows the
51
+ view's own `statechange`; `unbind()` releases the view. A panel given its own `fields` lists
52
+ those and no others (the title a card draws is not a column to offer); given none, it lists every
53
+ field the view has. The view's labels and types win over the panel's descriptors, which add only
54
+ `locked`, `groupable`, and a type where the view has just the `'text'` default. While bound the view owns the field list: call the view's `setFields()` — the
55
+ panel's own `setFields()` is not pushed and lasts until the view's next change. Grouping and board
56
+ changes are only emitted — the host applies them.
@@ -0,0 +1,42 @@
1
+ # WorkspaceSwitcher
2
+
3
+ The current workspace at the head of a navigation column — tile, name, and secondary line — opening a menu of the workspaces with the current one checked, then the application’s own actions.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/workspace-switcher · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Composes `AppIcon` and `MenuButton` into the workspace switcher at the head of a navigation column:
8
+ a trigger with the current workspace's tile, name and secondary line, opening an APG menu of the
9
+ workspaces with the current one checked, then the application's own actions. Zx never decides
10
+ which workspaces a user may see, loads another workspace, or changes the session — switching is a
11
+ cancelable event the application acts on.
12
+
13
+ - **Options** — `workspaces: [{id, label, secondary?, icon?, tone?, color?, src?, initials?, badge?,
14
+ disabled?}]` (the tile is the image, else the icon, else the initial, on the tone — derived from
15
+ the label when neither `tone` nor `color` is given), `active` (defaults to the first enabled
16
+ workspace, which also replaces an id that is not listed or is disabled), `items` (actions after
17
+ the workspaces; the separator between them is added for you), `compact: false`, `heading` (null
18
+ resolves message `workspaceSwitcher.heading`, "Workspaces"; `''` leaves it out), `label` (`%1` is
19
+ the active workspace's name, filled in again after every switch; null resolves
20
+ `workspaceSwitcher.label`, "Switch workspace: %1", or `workspaceSwitcher.labelEmpty`, "Switch
21
+ workspace", while no workspace is active), and any `placement` (default `bottom-start`).
22
+ - **Messages** — `workspaceSwitcher.heading`, `workspaceSwitcher.label` (`%1` the workspace name),
23
+ `workspaceSwitcher.labelEmpty`; override them per instance through `msg`, or for every instance
24
+ through `setTranslator()`.
25
+ - **Methods** — `getActive()`, `setActive(id, {silent = true})` (`silent: false` emits `select`
26
+ first), `setWorkspaces(list)` (keeps the active workspace while it is still listed and enabled,
27
+ else the first enabled one becomes active), `setItems()`,
28
+ `setCompact(compact)`, `open()`, `close()`, `toggle()`, `isOpen()`, `focus()`, `getPanel()`,
29
+ `destroy()`.
30
+ - **Events** — cancelable `select {workspace, id, previous}`: a canceled switch keeps the previous
31
+ workspace active and the menu open. Cancelable `action {value, item}` for the extra items: a
32
+ canceled action does not run the item's callback. Both honour `preventDefault()` on the component
33
+ event and on the bubbling `zx-select` / `zx-action` DOM event alike. `open` and `close`. Choosing the current
34
+ workspace again only closes the menu.
35
+ - **Semantics** — one native `<button aria-haspopup="menu" aria-expanded>` trigger, named "Switch
36
+ workspace: <name>" (or the custom `label`) in both states; compact mode shows the tile alone and adds the name as its
37
+ `title`. Workspaces are `menuitemradio` rows with `aria-checked` under a presentational heading;
38
+ MenuButton keeps focus return, typeahead and the arrow-key map.
39
+ - **Appearance** — the trigger is a flat full-width row (tile, name, secondary line, chevron) with
40
+ the hover fill, at least a control and a space-2 tall; its tile is the module bar's tile size, so
41
+ as an `AppSidebar` `railHeader` it lines up with the module tiles under it. Keep it in step with a
42
+ modules sidebar by calling `setCompact(presentation !== 'expanded')` on `presentationchange`.
@@ -0,0 +1,196 @@
1
+ # ZeyOS binding (zx-zeyos)
2
+
3
+ `zx-zeyos` is the optional schema-driven layer above `@zeyos/client`: inject a client instance and declare a resource to generate typed Zx controls.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/layouts.html#zeyos-invoices · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ `zx-zeyos` is the optional schema-driven layer above `@zeyos/client`: inject a client instance and
8
+ declare a resource to generate typed Zx controls. It is a separate ESM entry at
9
+ `dist/zx-zeyos.esm.js` (or `src/zeyos/index.js` during no-build development) and is deliberately
10
+ not re-exported from `src/index.js`. The binding has zero runtime dependencies and never imports or
11
+ bundles `@zeyos/client`; the application owns client creation, authentication, and transport.
12
+
13
+ ```js
14
+ import { createZeyosClient } from '@zeyos/client';
15
+ import {
16
+ connect, createLegacySavedViewTransport, createSavedViewRegistry,
17
+ dataFilterStateToFilters, legacySavedViewRequest, zeyosForm, zeyosSelect, zeyosTable, zeyosView
18
+ } from '/assets/zx-zeyos.esm.js';
19
+ import { CardView, TableView } from '/assets/zx.esm.js';
20
+
21
+ const client = createZeyosClient({ platform, auth });
22
+ const api = connect(client, { locale: 'en-GB' });
23
+
24
+ const list = zeyosTable(client, 'transactions', {
25
+ fields: ['transactionnum', 'account', 'date', 'netamount', 'status'],
26
+ sort: { id: 'date', dir: 'desc' },
27
+ selectable: 'multi'
28
+ });
29
+ await list.load();
30
+
31
+ const editor = zeyosForm(client, 'transactions', {
32
+ fields: ['transactionnum', 'account', 'date', 'netamount', 'status'],
33
+ onSaved: () => list.load()
34
+ });
35
+ await editor.load(transactionId);
36
+ await editor.save();
37
+
38
+ const records = zeyosView(client, 'transactions', TableView, {
39
+ fields: ['transactionnum', 'account', 'date', 'netamount', 'status'],
40
+ savedViews: {
41
+ transport: savedViewTransport,
42
+ scope: { userId: currentUserId, workspaceId: currentWorkspaceId }
43
+ }
44
+ });
45
+ await records.ready; // restores a compatible default before the first list request
46
+ await records.load();
47
+ await records.saveView({ name: 'My open invoices', setDefault: true });
48
+ ```
49
+
50
+ - `connect(client, { onError, locale })` returns `{client, list, get, create, update, reportError}`;
51
+ generated forms/tables use the same operation discovery and default `Message.error` reporting.
52
+ - `zeyosSelect(client, resource, opts)` returns an async Zx `Select`. Options include `fields`,
53
+ `labelKey`, `valueKey`, `searchFields`, `filters`, `limit`, and normal Select options. Its list
54
+ operation receives a query built by `buildListQuery`.
55
+ - `zeyosForm(client, resource, opts)` returns
56
+ `{form, ready, load(id), save(), getForm(), destroy()}`. `fields` is an ordered allow-list;
57
+ `exclude`, `labels`, `formats`, `timeZone`, `title`, `columns`, `value|id`, and `onSaved` curate
58
+ behavior. `load` maps stored timestamps to `Date`; `save` validates and creates/updates, maps back
59
+ to Unix seconds, calls `onSaved`, and shows a success toast. Its toasts (that confirmation and a
60
+ failed request's report) appear in the theme scope of `scope` — default: the form's own element,
61
+ so a form in a scoped dialog toasts inside that scope, and the confirmation stays there when
62
+ `onSaved` closes and destroys the dialog; `notify: false` raises none, leaving the
63
+ promise's result or rejection to the caller.
64
+ - `zeyosTable(client, resource, opts)` returns
65
+ `{table, load(), setSearch(), setFilters(), loadMore(), count, page, pageSize, hasMore, destroy()}`.
66
+ Columns come from schema metadata, sorting uses `sortMode:'server'`, and paging is zero-based with
67
+ `pageSize: 50` by default: page zero replaces rows while later pages append them using server
68
+ `limit`/`offset` and `count`; `load({page, pageSize, replace: true})` replaces at any page. A
69
+ one-based `Pagination` maps onto it as `load({page: detail.page - 1, pageSize: detail.pageSize,
70
+ replace: true})` (offset `(page - 1) * pageSize`), feeding `result.count` back through
71
+ `setTotal()`. A response that resolves after `destroy()` is ignored and later loads reject; page
72
+ must be a non-negative integer and page size a positive integer (`RangeError`), filters an object
73
+ (`TypeError`), and every argument is checked before any is applied, so a rejected call changes
74
+ nothing. Table presentation options and
75
+ listeners pass through — `variant`, `zebra`, `stickyHeader`, `responsive`, `growing`, `emptyText`,
76
+ `rowClass`, `rowKind(s)`, `columnVisibility`, `columnReorder`, `hiddenColumns`, `on<event>`;
77
+ `onrowclick` runs beside `onRowClick`. The binding owns `columns`, `data`, and `sortMode`, and
78
+ leaves out editing, `rowReorder`, and `hierarchy`, which change rows it never persists.
79
+ - `buildZeyosViewConfig(client, resource, opts)` resolves one schema to shared `ViewField[]`, a
80
+ complete projection, and view options. `zeyosView(client, resource, CardView|TableView|KanbanView,
81
+ opts)` returns `{view, load(), setSearch(), setFilters(), loadMore(), count, page, hasMore,
82
+ savedViews, ready, restoreDefault(), captureView(), saveView(), applyView(), destroy()}` with
83
+ paging and server sort. Paging is the same loader as `zeyosTable()` — same `pageSize: 50` default,
84
+ validation, `replace`/`pageSize` load options, and destroy guard. Title, preview, group, column, and swim-lane fields stay in the projection
85
+ even when hidden. Without `savedViews`, the host may persist `view.getViewState()` directly.
86
+ `savedViewFallback: 'error'` is the default: a saved-view initialization failure blocks loads.
87
+ Opt into `'baseline'` to load records using the configured query and sort when the registry
88
+ cannot be read. The failure is reported and `ready` still rejects; capture, save, apply, and
89
+ default restoration remain blocked. Later operations retry initialization so repaired storage
90
+ can restore its default. The unreadable document is never rewritten automatically, and a
91
+ failure while applying a view or query cannot fall back.
92
+ - `createSavedViewRegistry(transport, {userId,workspaceId,resource})` coordinates private named
93
+ Table/Card/Kanban configurations as one versioned, atomically replaced document. Entries capture
94
+ component state plus filters/search and an explicit presentation type, never records, selection,
95
+ pages, callbacks, or DOM. Duplicate names, defaults, migration, type mismatch, failed writes, and
96
+ teardown are explicit. `workspaceId:null` addresses ZeyOS's base workspace.
97
+ - `createLegacySavedViewTransport(request)` reuses the authenticated `fields`, `fields_save`, and
98
+ `fields_remove` endpoints through one reserved, namespaced `userfields` record.
99
+ `legacySavedViewRequest(PG.load.bind(PG))` is the optional Promise bridge for a legacy host. The
100
+ scope's `userId` is intentionally not sent to the endpoint; the server session remains authority.
101
+
102
+ Field mapping is schema-driven: entity/FK → async `zxselect`; enum/list → `optionlist` or native
103
+ `select` with readable labels (a schema `{value, label}` as given, a stored constant in sentence
104
+ case — `INVOICED` → "Invoiced", `PARTLYPAID` → "Partly paid"); date-only bigints (indexed `date`,
105
+ `duedate`, `birthdate`, `datefrom`/`dateto` outside appointments and events, `datecancel`,
106
+ `lastbilling`) → `date`; other date/time bigints and `lastmodified` → `datetime`;
107
+ `formats: { field: 'date' }` overrides the guess; money/price/numeric
108
+ → right-aligned `float`/number columns (amount columns use the row currency); boolean/checked →
109
+ `toggle` and a check column; percent/progress → numeric percent; email/tel/url → typed text; arrays
110
+ → `valuelist`; long text/JSON → `textarea`; short scalar text → `text`.
111
+
112
+ ZeyOS queries always use `filters` (plural), not `filter`. Full-text input becomes `query`; sort is
113
+ sent as signed server fields (`+field`/`-field`); projection supports aliases and dot joins; and
114
+ search/filter/sort/pagination remain server-side. ZeyOS timestamps are integer Unix seconds, so
115
+ forms convert them to/from `Date`. A date-only field stores midnight of a calendar day in the
116
+ instance's zone — a day, not an instant: tables show it with no time, and forms edit it as that day,
117
+ so neither the viewer's zone nor daylight saving moves it. Pass the instance's IANA zone as
118
+ `timeZone` (table, form, view; default: the runtime's own); `unixSecondsToCalendarDay(seconds, tz)`
119
+ and `calendarDayToUnixSeconds(date, tz)` do the same conversion for application code. Use
120
+ `dataFilterStateToFilters(state, defs, {timeZone})` before `tableBinding.setFilters(...)` when wiring
121
+ a `DataFilter`: with `timeZone`, a `format: 'date'` value (`Date` or `YYYY-MM-DD`) becomes that
122
+ day's midnight in the zone, as forms store it, while `datetime` values stay instants; without it,
123
+ dates convert as exact instants. `FilterPanel` takes the same `timeZone` option.
124
+
125
+ ## Module icons and colours
126
+
127
+ `src/zeyos/modules.js` is the configuration file for module identity — one entry per ZeyOS module,
128
+ holding the icon and the colour it is drawn in:
129
+
130
+ ```js
131
+ notes: { label: 'Notes', icon: 'zeyos-notes', color: '#008853', fa: 'note-sticky' }
132
+ ```
133
+
134
+ `icon` is the glyph's name in the ZeyOS Font Awesome kit (61 custom `zeyos-*` icons, rendered as
135
+ `<i class="fa-kit fa-zeyos-notes">`); `fa` is a stock Font Awesome fallback that also exists in
136
+ Font Awesome Free. Colours are the ZeyOS runtime palette (`ICO.Colors`) where ZeyOS defines one and
137
+ Zx defaults elsewhere; they are also emitted as `--zx-module-*` CSS custom properties, generated
138
+ from this file by `tools/build-module-tokens.js` and checked by the unit tests.
139
+
140
+ ```js
141
+ import { moduleChip, moduleColor, registerModules, useZeyosIcons } from '/assets/zx-zeyos.esm.js';
142
+
143
+ await useZeyosIcons(); // loads ZEYOS_ICON_KIT, switches Zx to Font Awesome
144
+ nav.append(moduleChip('tickets', { size: 24, title: true })); // glyph on the module colour
145
+ moduleColor('invoices'); // '#535494' — aliases resolve to their module
146
+ registerModules({ tickets: '#f04639', 'my-fork': { label: 'My Fork', icon: 'zeyos-weblets' } });
147
+ ```
148
+
149
+ - `moduleIcon(name, {size, label, standard})` → the bare glyph; `standard: true` uses the stock
150
+ Font Awesome fallback, for pages on a kit without the ZeyOS uploads. Stock Font Awesome
151
+ CSS or kit assets must still be loaded by the host.
152
+ - `moduleChip(name, {size, iconSize, label, title, standard})` → `<span class="zx-module-icon">`
153
+ with a centred white glyph on the module colour. `moduleGlyphColor(hex)` remains available as a
154
+ separate contrast helper for non-AppIcon integrations that deliberately choose their foreground.
155
+ - `moduleInfo`/`moduleColor`/`moduleIconName`/`moduleKeys`/`normalizeModuleName` read the config.
156
+ Module, entity, and API resource names are all accepted, case-insensitively, with dots and
157
+ underscores normalized: `'transactions.billing'`, `'invoices'`, and `'Transactions Billing'` all
158
+ land on `transactions-billing`. Unknown names fall back to the `default` module — lookups never
159
+ throw.
160
+ - `registerModules(map)` adds forks and weblets or overrides shipped entries (a bare string sets
161
+ the colour only). Runtime ZeyOS menu data is authoritative: feed its colours in at startup.
162
+
163
+ ## Module bar from the ZeyOS menu
164
+
165
+ The module bar and the module-layout sidebar read the same shell state the launcher does, plus
166
+ each module's menu and its counts:
167
+
168
+ ```js
169
+ import { buildZeyosAppSidebarConfig, buildZeyosModuleBarConfig } from '/assets/zx-zeyos.esm.js';
170
+ import { AppSidebar, ModuleBar } from '/assets/zx.esm.js';
171
+
172
+ const state = {
173
+ modules: ['messages', 'tasks', 'billing', 'contacts', 'calendar', 'tickets'],
174
+ pinned: ['messages', 'tasks', 'billing', 'tickets'], // the rest are under "All modules"
175
+ activeIdentifier: 'tickets',
176
+ active: 'tickets-mine', // a menu entry, when more precise
177
+ canUseModule: (module) => permissions.has(module),
178
+ menus: { tickets: [{ id: 'tickets-mine', label: 'My tickets' }, ['tickets-all', 'All tickets', '#tickets']] },
179
+ badges: { messages: 7, 'tickets-mine': 3 },
180
+ resolveApplication: (app) => ({ href: routeFor(app) })
181
+ };
182
+ new AppSidebar(nav, buildZeyosAppSidebarConfig(state, { onselect: route }));
183
+ new ModuleBar(header, buildZeyosModuleBarConfig(state, { orientation: 'horizontal', side: 'top' }));
184
+ ```
185
+
186
+ - `zeyosModuleItems(state, {standardIcons})` → `ModuleItem[]`: every permitted module, fork, and
187
+ weblet, with its kit icon (or `renderApplicationIcon(app, normalized)`), its colour — the
188
+ payload's, else the registry's, so `registerModules()` reaches the bar — its menu from
189
+ `menus[identifier]` (objects or `[id, label, href]` arrays, sections, nesting; unsafe hrefs are
190
+ disabled), its badge from `badges`, `pinned` from the pinned order, and forks and weblets in
191
+ their own catalogue group (`labels.forks`, `labels.weblets`). A module with a menu is a panel
192
+ module; one without is a destination.
193
+ - `buildZeyosModuleBarConfig(state, options)` → ModuleBar options; `buildZeyosAppSidebarConfig()`
194
+ → AppSidebar options in `layout: 'modules'`. Both draw the classic ZeyOS identity tiles
195
+ (`appearance: 'solid'`) unless told otherwise. `zeyosModuleBar(target, state, options)` creates
196
+ the bar directly.