@zeyos/zx 5.7.0 → 5.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (330) hide show
  1. package/CHANGELOG.md +330 -0
  2. package/README.md +47 -9
  3. package/dist/types/components/activity-item/activity-item.d.ts +14 -3
  4. package/dist/types/components/agent-avatar/agent-avatar.d.ts +165 -0
  5. package/dist/types/components/agent-avatar/agent-face.d.ts +93 -0
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +21 -9
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +26 -0
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +3 -1
  9. package/dist/types/components/approval-card/approval-card.d.ts +31 -2
  10. package/dist/types/components/aurora/aurora.d.ts +31 -5
  11. package/dist/types/components/calendar/calendar.d.ts +39 -26
  12. package/dist/types/components/chart/chart.d.ts +250 -20
  13. package/dist/types/components/chart/color.d.ts +66 -0
  14. package/dist/types/components/chart/svg-adapter.d.ts +103 -0
  15. package/dist/types/components/chart/svg-geometry.d.ts +203 -0
  16. package/dist/types/components/check-button/check-button.d.ts +1 -4
  17. package/dist/types/components/checklist/checklist.d.ts +48 -5
  18. package/dist/types/components/code-editor/code-editor.d.ts +55 -1
  19. package/dist/types/components/composer/composer.d.ts +41 -6
  20. package/dist/types/components/context-menu/context-menu.d.ts +36 -8
  21. package/dist/types/components/copy/copy-button.d.ts +6 -0
  22. package/dist/types/components/copy/copy-input.d.ts +1 -0
  23. package/dist/types/components/date-picker/date-picker.d.ts +14 -0
  24. package/dist/types/components/date-picker/time-picker.d.ts +26 -17
  25. package/dist/types/components/datebox/datebox.d.ts +8 -4
  26. package/dist/types/components/dialog/dialog.d.ts +15 -4
  27. package/dist/types/components/empty-state/empty-state.d.ts +10 -1
  28. package/dist/types/components/field/field.d.ts +4 -2
  29. package/dist/types/components/form/form.d.ts +2 -1
  30. package/dist/types/components/kanban-view/kanban-card.d.ts +7 -0
  31. package/dist/types/components/kanban-view/kanban-view.d.ts +15 -3
  32. package/dist/types/components/launcher/launcher.d.ts +26 -0
  33. package/dist/types/components/master-panel/master-panel.d.ts +9 -4
  34. package/dist/types/components/menu-button/menu-button.d.ts +29 -5
  35. package/dist/types/components/message/message.d.ts +308 -5
  36. package/dist/types/components/modal/modal.d.ts +45 -8
  37. package/dist/types/components/modal/native-dialog.d.ts +40 -0
  38. package/dist/types/components/module-bar/module-bar.d.ts +9 -2
  39. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +5 -4
  40. package/dist/types/components/number-field/number-field.d.ts +31 -1
  41. package/dist/types/components/pagination/pagination.d.ts +341 -19
  42. package/dist/types/components/run-status/run-status.d.ts +26 -0
  43. package/dist/types/components/run-trace/run-trace.d.ts +10 -6
  44. package/dist/types/components/search/search.d.ts +16 -4
  45. package/dist/types/components/select/select.d.ts +19 -1
  46. package/dist/types/components/sheet/sheet.d.ts +20 -6
  47. package/dist/types/components/slider/slider.d.ts +2 -1
  48. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -3
  49. package/dist/types/components/stepper/stepper.d.ts +17 -4
  50. package/dist/types/components/surface/catalog.d.ts +61 -17
  51. package/dist/types/components/surface/surface.d.ts +6 -4
  52. package/dist/types/components/table/table.d.ts +207 -5
  53. package/dist/types/components/table/window.d.ts +25 -1
  54. package/dist/types/components/toggle/toggle.d.ts +38 -6
  55. package/dist/types/components/tooltip/tooltip.d.ts +5 -4
  56. package/dist/types/components/tree/tree.d.ts +43 -6
  57. package/dist/types/components/truncate/truncate.d.ts +4 -2
  58. package/dist/types/components/value-list/value-list.d.ts +9 -2
  59. package/dist/types/core/date.d.ts +2 -1
  60. package/dist/types/core/dom.d.ts +14 -0
  61. package/dist/types/core/drag-axis.d.ts +10 -5
  62. package/dist/types/core/export.d.ts +2 -2
  63. package/dist/types/core/format.d.ts +3 -1
  64. package/dist/types/core/icons.d.ts +36 -3
  65. package/dist/types/core/keyboard.d.ts +7 -3
  66. package/dist/types/core/messages.d.ts +3 -0
  67. package/dist/types/core/storage.d.ts +4 -3
  68. package/dist/types/core/util.d.ts +3 -1
  69. package/dist/types/elements/define.d.ts +5 -2
  70. package/dist/types/index.d.ts +6 -4
  71. package/dist/types/internal/agent-model.d.ts +99 -0
  72. package/dist/types/internal/app-rail.d.ts +37 -2
  73. package/dist/types/internal/collections.d.ts +18 -0
  74. package/dist/types/internal/menu-items.d.ts +27 -0
  75. package/dist/types/internal/overlay-content.d.ts +23 -0
  76. package/dist/types/internal/presence-loop.d.ts +5 -2
  77. package/dist/types/locales/index.d.ts +3 -0
  78. package/dist/types/zeyos/calendar.d.ts +43 -7
  79. package/dist/types/zeyos/connect.d.ts +4 -0
  80. package/dist/types/zeyos/form.d.ts +13 -5
  81. package/dist/types/zeyos/select.d.ts +5 -2
  82. package/dist/types/zeyos/table.d.ts +16 -8
  83. package/dist/types/zeyos/view.d.ts +2 -1
  84. package/dist/zx-zeyos.esm.js +3161 -515
  85. package/dist/zx-zeyos.esm.min.js +4 -4
  86. package/dist/zx.core.css +4 -0
  87. package/dist/zx.core.min.css +1 -1
  88. package/dist/zx.css +970 -57
  89. package/dist/zx.esm.js +6405 -2249
  90. package/dist/zx.esm.min.js +26 -26
  91. package/dist/zx.global.js +6405 -2249
  92. package/dist/zx.global.min.js +26 -26
  93. package/dist/zx.layered.css +972 -57
  94. package/dist/zx.layered.min.css +1 -1
  95. package/dist/zx.min.css +1 -1
  96. package/docs/agent-catalog.json +159 -1
  97. package/docs/agent-surfaces.md +21 -21
  98. package/docs/api.json +3154 -518
  99. package/docs/components/account-menu.md +24 -0
  100. package/docs/components/activity-item.md +23 -0
  101. package/docs/components/activity-list.md +28 -0
  102. package/docs/components/agent-avatar.md +59 -0
  103. package/docs/components/agent-thread.md +275 -0
  104. package/docs/components/app-icon.md +36 -0
  105. package/docs/components/app-sidebar.md +92 -0
  106. package/docs/components/approval-card.md +71 -0
  107. package/docs/components/aurora.md +34 -0
  108. package/docs/components/avatar.md +37 -0
  109. package/docs/components/badge.md +36 -0
  110. package/docs/components/block-view.md +34 -0
  111. package/docs/components/breadcrumb.md +20 -0
  112. package/docs/components/button.md +23 -0
  113. package/docs/components/calendar.md +68 -0
  114. package/docs/components/card-view.md +73 -0
  115. package/docs/components/card.md +25 -0
  116. package/docs/components/chart.md +109 -0
  117. package/docs/components/check-button.md +16 -0
  118. package/docs/components/checklist.md +19 -0
  119. package/docs/components/code-editor.md +38 -0
  120. package/docs/components/composer.md +107 -0
  121. package/docs/components/context-menu.md +32 -0
  122. package/docs/components/copy.md +37 -0
  123. package/docs/components/data-filter.md +16 -0
  124. package/docs/components/date-picker.md +31 -0
  125. package/docs/components/date-range.md +21 -0
  126. package/docs/components/datebox.md +31 -0
  127. package/docs/components/dialog.md +25 -0
  128. package/docs/components/dock.md +57 -0
  129. package/docs/components/dropdown.md +39 -0
  130. package/docs/components/elements.md +63 -0
  131. package/docs/components/empty-state.md +17 -0
  132. package/docs/components/entity-ref.md +26 -0
  133. package/docs/components/field-upload.md +18 -0
  134. package/docs/components/file-item.md +27 -0
  135. package/docs/components/file-list.md +23 -0
  136. package/docs/components/filter-panel.md +45 -0
  137. package/docs/components/filter.md +47 -0
  138. package/docs/components/finder.md +25 -0
  139. package/docs/components/form-widgets.md +42 -0
  140. package/docs/components/form.md +80 -0
  141. package/docs/components/grid.md +26 -0
  142. package/docs/components/groupbox.md +11 -0
  143. package/docs/components/helpers.md +359 -0
  144. package/docs/components/icons.md +87 -0
  145. package/docs/components/index.md +99 -0
  146. package/docs/components/kanban-view.md +42 -0
  147. package/docs/components/kbd.md +23 -0
  148. package/docs/components/kernel.md +41 -0
  149. package/docs/components/launcher.md +66 -0
  150. package/docs/components/layout.md +33 -0
  151. package/docs/components/list-toolbar.md +38 -0
  152. package/docs/components/loading.md +48 -0
  153. package/docs/components/menu-button.md +47 -0
  154. package/docs/components/message.md +76 -0
  155. package/docs/components/modal.md +27 -0
  156. package/docs/components/module-bar.md +71 -0
  157. package/docs/components/multi-value-editor.md +16 -0
  158. package/docs/components/navigation-bar.md +22 -0
  159. package/docs/components/number-field.md +34 -0
  160. package/docs/components/pagination.md +73 -0
  161. package/docs/components/panel.md +28 -0
  162. package/docs/components/prompt-starters.md +40 -0
  163. package/docs/components/prose.md +38 -0
  164. package/docs/components/questionnaire.md +115 -0
  165. package/docs/components/rating.md +19 -0
  166. package/docs/components/run-status.md +50 -0
  167. package/docs/components/run-trace.md +72 -0
  168. package/docs/components/search.md +11 -0
  169. package/docs/components/select.md +129 -0
  170. package/docs/components/sheet-stack.md +39 -0
  171. package/docs/components/sheet.md +77 -0
  172. package/docs/components/skeleton.md +27 -0
  173. package/docs/components/slider.md +29 -0
  174. package/docs/components/sort-control.md +21 -0
  175. package/docs/components/source-list.md +30 -0
  176. package/docs/components/split-view.md +12 -0
  177. package/docs/components/stat-tile.md +49 -0
  178. package/docs/components/stepper.md +27 -0
  179. package/docs/components/surface.md +152 -0
  180. package/docs/components/tabbox.md +33 -0
  181. package/docs/components/table-view.md +43 -0
  182. package/docs/components/table.md +232 -0
  183. package/docs/components/tag-picker.md +39 -0
  184. package/docs/components/timebox.md +16 -0
  185. package/docs/components/toggle.md +21 -0
  186. package/docs/components/tokens.md +82 -0
  187. package/docs/components/toolbar.md +26 -0
  188. package/docs/components/tooltip.md +16 -0
  189. package/docs/components/tree.md +48 -0
  190. package/docs/components/truncate.md +21 -0
  191. package/docs/components/value-list.md +14 -0
  192. package/docs/components/view-settings.md +56 -0
  193. package/docs/components/workspace-switcher.md +42 -0
  194. package/docs/components/zeyos.md +196 -0
  195. package/docs/llms-small.txt +299 -0
  196. package/docs/llms.md +725 -109
  197. package/docs/llms.txt +46 -19
  198. package/package.json +9 -4
  199. package/src/components/activity-item/activity-item.js +21 -2
  200. package/src/components/agent-avatar/agent-avatar.css +195 -0
  201. package/src/components/agent-avatar/agent-avatar.js +333 -0
  202. package/src/components/agent-avatar/agent-face.js +292 -0
  203. package/src/components/agent-thread/ag-ui.js +44 -11
  204. package/src/components/agent-thread/agent-thread.js +103 -11
  205. package/src/components/agent-thread/ui-message-stream.js +3 -1
  206. package/src/components/app-rail/app-rail.css +5 -0
  207. package/src/components/app-sidebar/app-sidebar.css +3 -0
  208. package/src/components/app-sidebar/app-sidebar.js +4 -3
  209. package/src/components/approval-card/approval-card.css +6 -0
  210. package/src/components/approval-card/approval-card.js +55 -7
  211. package/src/components/aurora/aurora.css +149 -14
  212. package/src/components/aurora/aurora.js +49 -6
  213. package/src/components/button/button.css +24 -11
  214. package/src/components/calendar/calendar.css +6 -2
  215. package/src/components/calendar/calendar.js +127 -47
  216. package/src/components/card-view/card-view.js +5 -6
  217. package/src/components/chart/chart.css +159 -1
  218. package/src/components/chart/chart.js +450 -62
  219. package/src/components/chart/color.js +297 -0
  220. package/src/components/chart/svg-adapter.js +576 -0
  221. package/src/components/chart/svg-geometry.js +323 -0
  222. package/src/components/check-button/check-button.js +3 -18
  223. package/src/components/checklist/checklist.css +9 -1
  224. package/src/components/checklist/checklist.js +105 -20
  225. package/src/components/checklist/field-adapter.js +6 -12
  226. package/src/components/code-editor/code-editor.css +33 -0
  227. package/src/components/code-editor/code-editor.js +97 -8
  228. package/src/components/code-editor/field-adapter.js +3 -0
  229. package/src/components/composer/composer.css +3 -0
  230. package/src/components/composer/composer.js +100 -22
  231. package/src/components/context-menu/context-menu.js +41 -5
  232. package/src/components/copy/copy-button.js +9 -1
  233. package/src/components/copy/copy-input.js +5 -0
  234. package/src/components/data-filter/filter-core.js +0 -1
  235. package/src/components/date-picker/date-picker.css +8 -0
  236. package/src/components/date-picker/date-picker.js +47 -8
  237. package/src/components/date-picker/date-range-picker.js +1 -1
  238. package/src/components/date-picker/month-picker.js +19 -3
  239. package/src/components/date-picker/time-picker.js +54 -19
  240. package/src/components/datebox/date-range-box.js +7 -3
  241. package/src/components/datebox/datebox.js +32 -6
  242. package/src/components/dialog/dialog.css +6 -0
  243. package/src/components/dialog/dialog.js +24 -33
  244. package/src/components/dropdown/dropdown.js +1 -18
  245. package/src/components/empty-state/empty-state.js +21 -2
  246. package/src/components/field/field.js +19 -3
  247. package/src/components/fieldset/fieldset.js +3 -1
  248. package/src/components/filter/filter.js +9 -0
  249. package/src/components/form/form.js +19 -2
  250. package/src/components/kanban-view/kanban-card.js +15 -2
  251. package/src/components/kanban-view/kanban-view.css +21 -0
  252. package/src/components/kanban-view/kanban-view.js +29 -16
  253. package/src/components/launcher/launcher.css +14 -0
  254. package/src/components/launcher/launcher.js +54 -9
  255. package/src/components/master-panel/master-panel.js +24 -22
  256. package/src/components/menu-button/menu-button.js +26 -4
  257. package/src/components/message/message.css +228 -29
  258. package/src/components/message/message.js +664 -30
  259. package/src/components/modal/modal.js +129 -30
  260. package/src/components/modal/native-dialog.js +91 -0
  261. package/src/components/module-bar/module-bar.css +3 -0
  262. package/src/components/module-bar/module-bar.js +17 -4
  263. package/src/components/multi-value-editor/multi-value-editor.css +7 -2
  264. package/src/components/multi-value-editor/multi-value-editor.js +3 -2
  265. package/src/components/navigation-bar/navigation-bar.js +13 -1
  266. package/src/components/number-field/field-adapter.js +3 -0
  267. package/src/components/number-field/number-field.js +70 -16
  268. package/src/components/pagination/pagination.css +26 -2
  269. package/src/components/pagination/pagination.js +551 -65
  270. package/src/components/prose/prose.js +7 -1
  271. package/src/components/rating/field-adapter.js +3 -0
  272. package/src/components/run-status/run-status.js +43 -3
  273. package/src/components/run-trace/run-trace.js +15 -7
  274. package/src/components/search/search.js +3 -18
  275. package/src/components/select/field-adapter.js +8 -1
  276. package/src/components/select/select.js +68 -13
  277. package/src/components/sheet/sheet.js +39 -13
  278. package/src/components/slider/field-adapter.js +3 -0
  279. package/src/components/slider/slider.js +4 -6
  280. package/src/components/stat-tile/stat-tile.js +24 -9
  281. package/src/components/stepper/stepper.css +15 -0
  282. package/src/components/stepper/stepper.js +34 -2
  283. package/src/components/surface/catalog.js +185 -28
  284. package/src/components/surface/surface.js +10 -5
  285. package/src/components/tabbox/tabbox.js +13 -1
  286. package/src/components/table/table.css +160 -2
  287. package/src/components/table/table.js +479 -52
  288. package/src/components/table/window.js +46 -4
  289. package/src/components/table-view/table-view.js +1 -10
  290. package/src/components/tag-picker/field-adapter.js +3 -0
  291. package/src/components/tag-picker/tag-picker.js +2 -0
  292. package/src/components/timebox/field-adapter.js +3 -0
  293. package/src/components/toggle/toggle.js +51 -27
  294. package/src/components/tooltip/tooltip.js +21 -14
  295. package/src/components/tree/tree.js +87 -14
  296. package/src/components/truncate/truncate.js +21 -5
  297. package/src/components/value-list/value-list.js +37 -9
  298. package/src/components/view-settings/view-settings.js +1 -5
  299. package/src/core/component.js +34 -2
  300. package/src/core/date.js +5 -4
  301. package/src/core/dom.js +45 -2
  302. package/src/core/drag-axis.js +24 -7
  303. package/src/core/export.js +4 -4
  304. package/src/core/fontawesome.js +34 -3
  305. package/src/core/format.js +3 -1
  306. package/src/core/http.js +23 -11
  307. package/src/core/icons.js +60 -8
  308. package/src/core/keyboard.js +83 -9
  309. package/src/core/messages.js +3 -0
  310. package/src/core/position.js +4 -3
  311. package/src/core/storage.js +80 -31
  312. package/src/core/util.js +16 -5
  313. package/src/elements/define.js +82 -47
  314. package/src/elements/kit.js +46 -35
  315. package/src/index.js +8 -4
  316. package/src/internal/agent-model.js +152 -0
  317. package/src/internal/app-rail.js +53 -2
  318. package/src/internal/collections.js +25 -0
  319. package/src/internal/menu-items.js +59 -0
  320. package/src/internal/overlay-content.js +35 -0
  321. package/src/internal/presence-loop.js +61 -14
  322. package/src/locales/de.js +3 -0
  323. package/src/zeyos/calendar.js +81 -19
  324. package/src/zeyos/connect.js +5 -1
  325. package/src/zeyos/form.js +29 -10
  326. package/src/zeyos/select.js +36 -12
  327. package/src/zeyos/table.js +43 -11
  328. package/src/zeyos/view.js +2 -1
  329. package/styles/tokens/semantic.css +7 -1
  330. package/styles/zx.css +1 -0
@@ -0,0 +1,87 @@
1
+ # Icons — bundled glyphs or Font Awesome
2
+
3
+ One icon() call, two renderers: the outline SVG glyphs Zx bundles, or Font Awesome once an application loads a kit.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/icons · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ `icon(name, {size, label, class, style, family, fixedWidth})` returns an element: an inline `<svg>`
8
+ from the bundled set, or an `<i>` carrying Font Awesome classes. Both get `class="zx-icon"`, so
9
+ component CSS styles either. Zx renders the bundled glyphs by default and **never loads anything on
10
+ its own** — Font Awesome is an opt-in an application makes.
11
+
12
+ ```js
13
+ import { loadFontAwesome, useFontAwesome, registerIcons } from '/assets/zx.esm.js';
14
+
15
+ await loadFontAwesome({ kit: 'ae8320b210', style: 'duotone' }); // injects the kit, switches over
16
+ useFontAwesome(); // page already carries Font Awesome; no network
17
+ registerIcons({ rocket: ['0 0 512 512', 'M…'] }); // a filled glyph (Font Awesome paths)
18
+ registerIcons({ anchor: ['0 0 24 24', 'M12 6v16…', 'stroke'] }); // an outline glyph (Lucide paths)
19
+ ```
20
+
21
+ - `loadFontAwesome(kit | {kit, style, family, fixedWidth, activate})` — injects the kit script once
22
+ per URL (a kit token expands to `https://kit.fontawesome.com/<token>.js`), adopts a kit the page
23
+ already embeds, then switches the renderer. Rejects if the script fails; kits only load on the
24
+ domains configured in the Font Awesome account.
25
+ - `useFontAwesome(opts)` / `useBuiltinIcons()` / `configureIcons(opts)` / `getIconConfig()` —
26
+ switch or read the renderer without touching the network.
27
+ - `iconNames()` lists every name `icon()` renders as an inline glyph: the bundled set, the glyphs
28
+ added with `registerIcons()`, and the aliases. A bare name that is not in the list renders the
29
+ placeholder. `icons` is the bundled table and `iconAliases` the frozen `alias → bundled name`
30
+ table. An alias is listed beside the glyph it draws, so the list holds more names than glyphs;
31
+ for one entry per glyph, as in an icon gallery, leave them out:
32
+ `iconNames().filter((name) => !Object.hasOwn(iconAliases, name))`.
33
+ - `registerIcons(map)` adds or replaces inline glyphs. `[viewBox, path]` is a filled shape — the
34
+ form Font Awesome path data comes in. `[viewBox, path, 'stroke']` is an outline drawn with the
35
+ bundled pen; its stroke scales with the view box, so a 24-unit outline set such as Lucide renders
36
+ exactly like the bundled glyphs. Anything else throws `TypeError`.
37
+
38
+ **The bundled set is outline.** The inline glyphs are Lucide icons (https://lucide.dev, ISC licence;
39
+ the notice is in `src/core/icons.js`) on a 24-unit grid: `fill="none"`, `stroke="currentColor"`,
40
+ round caps and joins, a stroke of 1.75 units — about 1.2px at the default 16px, the weight of
41
+ 13–14px interface text — and never thinner than one pixel, so 11–13px glyphs stay legible. The
42
+ names are Zx's own (`gear`, `dots`, `warning`, `success`, `drag`, …), not Lucide's. Colour follows
43
+ `currentColor`; muting an icon is the caller's choice. The paint sits on the `<svg>` as attributes,
44
+ so CSS on `.zx-icon` overrides it — `fill: currentColor` turns an outline into its solid form, which
45
+ is how a state such as a set star or a liked heart is shown without a second glyph.
46
+
47
+ **Names decide their own renderer.** A bare name (`'check'`) follows the active provider, and the
48
+ built-in names are translated to their Font Awesome counterparts (`x` → `fa-xmark`, `search` →
49
+ `fa-magnifying-glass`, `warning` → `fa-triangle-exclamation`, …), so component code never changes.
50
+ A bare name may also be an alias, under either renderer: `archive` → `box-archive`, `edit` →
51
+ `pen-to-square`, `settings` → `gear`, `clear` → `x`, `checked` → `check`, `question` → `info`,
52
+ `range` → `filter`, `fields` → `list`, `grid` → `table-cells-large`. A glyph an application
53
+ registered under the alias name itself wins over the alias, which is also how an alias is changed.
54
+ Prefixes override: `'fa:user'`, `'fas:user'`/`'regular:user'`/`'duotone:user'`/`'thin:user'`,
55
+ `'kit:zeyos-notes'` (custom kit icons), `'builtin:check'` (force the inline SVG). A literal class
56
+ list — `'fa-sharp fa-solid fa-user'` — is used verbatim. Unknown names under Font Awesome are
57
+ passed through to the kit, which resolves them in the browser.
58
+
59
+ **An unknown *built-in* name does not throw.** Icon names routinely arrive from a server, and one
60
+ unconfigured name must not take down the screen it appears on, so it renders an empty `<svg>` of
61
+ the requested size — layout does not shift — carrying `data-zx-icon-missing="<name>"`, and reports
62
+ itself once per distinct name through `console.warn`. Pass `icon(name, { strict: true })` for the
63
+ old `RangeError`, at a call site that can afford to fail: a test, or a build-time check.
64
+
65
+ Font Awesome elements are sized with `font-size` and occupy 1em; bundled SVGs use width/height
66
+ attributes (default 16). Both honour `label` (`null` ⇒ `aria-hidden`, otherwise `role="img"` +
67
+ `aria-label`).
68
+
69
+ **Size an icon by its role.** `ICON_SIZE` names one pixel size per role, so every chevron, every
70
+ dismiss ×, and every check renders alike wherever it appears, and a call site says what a glyph is
71
+ for rather than how big it is: `icon('chevron-down', { size: ICON_SIZE.chevron })`. The components
72
+ use it throughout; use it in application code too, and never write a number for one of these roles.
73
+
74
+ - `ICON_SIZE.control` (16) — the default: an icon that is a control's content or leads its label.
75
+ - `ICON_SIZE.chevron` (14) — dropdown, disclosure, and reorder chevrons; calendar and pager
76
+ arrows; breadcrumb separators.
77
+ - `ICON_SIZE.dismiss` (14) — the × that clears a field, closes a tab, dialog, or message, or
78
+ removes a row.
79
+ - `ICON_SIZE.check` (14) — the check of a selected option, a pressed toggle button, or a completed
80
+ step.
81
+ - `ICON_SIZE.sort` (14) — the sort-direction arrow beside a column heading.
82
+ - `ICON_SIZE.chip` (12) — any glyph inside a chip or token, its remove × included.
83
+ - `ICON_SIZE.marker` (8) — a glyph drawn inside a small status marker.
84
+
85
+ Several roles share a value and are named apart so one can change on its own. At 14px and below an
86
+ outline is drawn with a one-pixel line, so the indicator roles also share a stroke weight. A text
87
+ character is never a stand-in for an icon: draw "×", "✓", or an arrow with `icon()`.
@@ -0,0 +1,99 @@
1
+ # Zx components
2
+
3
+ One file per component: its section of the full reference (https://zx.zeyos.com/docs/llms.md), opening with a one-line summary and a link to its live demo. Read https://zx.zeyos.com/docs/llms-small.txt first: it says which layout and which component a screen needs.
4
+
5
+ - [ZeyOS binding (zx-zeyos)](zeyos.md) — `zx-zeyos` is the optional schema-driven layer above `@zeyos/client`: inject a client instance and declare a resource to generate typed Zx controls.
6
+ - [Prose](prose.md) — The reading register for authored content: its own typeface, size, line height, and measure.
7
+ - [Kbd](kbd.md) — Keycaps for every key hint: one construction in buttons, menus, the launcher, and help.
8
+ - [Button](button.md) — Factories that return a real `<button>`, in four weights and two sizes.
9
+ - [Badge](badge.md) — A status pill or a tag you place yourself: kind says how something is doing, tone what it is, and the shape follows.
10
+ - [Toolbar](toolbar.md) — One tab stop, arrow-key navigation, and an overflow menu that swallows what no longer fits.
11
+ - [EmptyState](empty-state.md) — The placeholder that stands where content would have been — in a table body, a panel, or a whole page.
12
+ - [Spinner / ProgressBar / InlineLoading](loading.md) — Three shapes of "wait": a ring when the duration is unknown, a track when the share done is known, and a status line that resolves into its own outcome.
13
+ - [Skeleton](skeleton.md) — Placeholders shaped like the content that is coming, so the layout does not jump when it arrives.
14
+ - [CheckButton](check-button.md) — A button that stays pressed — a checkbox with the presence of a toolbar control.
15
+ - [Toggle](toggle.md) — A labelled switch for settings that take effect immediately.
16
+ - [Search](search.md) — A debounced search field with a clear button and a submit on Enter.
17
+ - [Launcher](launcher.md) — A full application launcher with app tiles, current and pinned state, recent records, grouped asynchronous search, and application-owned routing.
18
+ - [AppIcon](app-icon.md) — A stable application identity with a centred white glyph, module colour, tile or circle geometry, accessible labeling, interaction-aware feedback, badges, selection state, and an optional CSS-first glass material.
19
+ - [Avatar](avatar.md) — A stable-size user image with a deterministic fallback — initials on a tone picked from the name — and an optional text-described presence indicator.
20
+ - [AgentAvatar](agent-avatar.md) — A generated face for an agent without a picture: a coloured geometric shape with eyes that take what the agent is doing.
21
+ - [EntityRef](entity-ref.md) — Dense linked or static record identity with labelled metadata and host-injected actions.
22
+ - [FileItem](file-item.md) — A durable or transient file row with a readable type and size, native downloads, actions, and accessible progress.
23
+ - [FileList](file-list.md) — An accessible ordered file collection with empty/loading states and incremental host-controlled mutation.
24
+ - [ActivityItem](activity-item.md) — One chronological record with actor identity, timestamp, metadata, attachments, content, and host actions.
25
+ - [ActivityList](activity-list.md) — A chronological ordered collection with stable grouping, incremental updates, and loading/empty states.
26
+ - [AccountMenu](account-menu.md) — A single accessible Avatar trigger and grouped account-action popup; identity, permissions, preferences, and sign-out stay application-owned.
27
+ - [WorkspaceSwitcher](workspace-switcher.md) — 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.
28
+ - [Select](select.md) — An APG editable combobox: a real text input, a top-layer listbox, and three filtering modes — none, local, and a function you supply.
29
+ - [SortControl](sort-control.md) — A searchable field selector with an adjacent direction toggle.
30
+ - [Checklist](checklist.md) — A searchable list of checkboxes for picking several records at once, with a static or an asynchronously loaded set of items.
31
+ - [NumberField](number-field.md) — A spinbutton with step buttons: bounded ranges, fractional steps, units, and wrapping.
32
+ - [Rating](rating.md) — A star rating built as a radio group: one tab stop, arrow-key selection, optional half steps, and a read-only display mode.
33
+ - [Slider](slider.md) — A bounded numeric value you set by dragging.
34
+ - [copyButton() / CopyInput](copy.md) — Copying a value, and saying so.
35
+ - [DatePicker / MonthPicker / TimePicker](date-picker.md) — Three inline pickers — a calendar, a month grid, and a time control — each a roving grid with one tab stop.
36
+ - [Datebox / DateTimeBox](datebox.md) — A text date field: it parses what the reader types against a strftime-style format, and keeps unparseable text on screen instead of silently discarding it.
37
+ - [DateRangePicker / DateRangeBox](date-range.md) — Two calendars driven as one roving-focus grid: the first click opens a range, hovering or arrowing previews where it would end, and the second click closes it.
38
+ - [Timebox](timebox.md) — A duration field.
39
+ - [Message](message.md) — Transient notifications: a floating region for toasts, a progress handle for long work, and an inline area for messages that belong to one part of the screen.
40
+ - [Modal](modal.md) — A bare top-layer surface you fill yourself — Dialog’s unopinionated sibling, for overlays that supply their own chrome.
41
+ - [Dialog (extends Modal)](dialog.md) — A modal built on native `<dialog>`: focus trapping, Escape, and the top layer come from the platform, and Modal adds initial focus and the return to the opener on top of them.
42
+ - [Sheet](sheet.md) — An edge-anchored Dialog — one component covers both side sheets and mobile drawers, since only the edge and presentation differ.
43
+ - [SheetStack](sheet-stack.md) — A group of Sheets that reads as one drill-down — and stays small, because the browser already stacks dialogs and already makes Escape unwind them one at a time.
44
+ - [Dropdown](dropdown.md) — A top-layer panel tethered to an anchor.
45
+ - [MenuButton](menu-button.md) — A trigger and its menu, following the APG menu button pattern: typeahead, wrapping arrows, and focus returned to the trigger on close.
46
+ - [ContextMenu](context-menu.md) — Right-click menu for a region or a row.
47
+ - [Tooltip](tooltip.md) — 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.
48
+ - [SplitView](split-view.md) — Two panes and a divider the reader owns: drag it, tab to it and use the arrow keys, double-click to reset, and — where it is allowed — fold a pane away entirely.
49
+ - [Table](table.md) — A sortable, selectable, editable data table with a sticky header for dense records, transactions, and operational workflows.
50
+ - [TableView and the shared RecordView contract](table-view.md) — A schema-friendly record view that composes the full Table: one field contract drives sorting, selection, editable cells, visibility, and stable column order.
51
+ - [CardView](card-view.md) — A compact responsive record collection sharing fields, sort, selection, visibility, order, and serializable state with TableView and KanbanView.
52
+ - [KanbanView](kanban-view.md) — A semantic opportunity board sharing fields, cards, sort, selection, and serializable configuration with the other record views.
53
+ - [Grid and Grid.BillingItems()](grid.md) — A public Table specialization for domain presets; it inherits sorting, selection, hierarchy, typed formatting, and editing without forking them.
54
+ - [Chart, SvgChartAdapter and ChartJsAdapter](chart.md) — An accessible engine-neutral chart host.
55
+ - [Calendar](calendar.md) — A dependency-free scheduling surface with agenda, day, week, month, and year views; local-time event layout; range selection; and pointer or keyboard editing.
56
+ - [DataFilter](data-filter.md) — The filter bar above a list: typed filter descriptors in, the matching rows out.
57
+ - [FilterPanel](filter-panel.md) — The filter form a data-driven list needs: field metadata in, a query object out.
58
+ - [Filter](filter.md) — A backend-neutral, nested filter authoring component.
59
+ - [TreeView](tree.md) — A hierarchy following the APG tree pattern: arrow-key navigation, expand and collapse, typeahead, lazy children, and optional tri-state checkboxes.
60
+ - [Finder](finder.md) — A Miller-columns browser: every column lists the children of the row picked to its left, the way a file browser’s column view works.
61
+ - [Form / Fieldset / Field](form.md) — Fieldsets of typed fields with one values object in and out — the schema-shaped way to build a record editor.
62
+ - [Field widget types](form-widgets.md) — The field types backed by a whole Zx component rather than a native input — what turns a Form into a real record editor.
63
+ - [CodeEditor](code-editor.md) — A dependency-free, text-safe source editor with native undo, IME behavior, indentation and line/column feedback.
64
+ - [Questionnaire](questionnaire.md) — One question at a time, with branching, a path-aware progress bar, and any Zx field type as the answer.
65
+ - [ValueList](value-list.md) — A chip editor for a list of strings, with per-value validation and drag or keyboard reordering.
66
+ - [MultiValueEditor](multi-value-editor.md) — A stack of rows for an ordered list of values, each row with its own remove and reorder controls — for a field that repeats.
67
+ - [FieldUpload](field-upload.md) — Click/drop file upload with progress.
68
+ - [TagPicker](tag-picker.md) — A multi-select combobox that keeps its selection visible as removable tags inside the control — for picking several values out of a large catalogue.
69
+ - [Groupbox](groupbox.md) — A collapsible section built on native `<details>`, so the keyboard and find-in-page behaviour comes from the platform.
70
+ - [Card](card.md) — A semantic content or record surface with optional media, a native title link, secondary actions, and metadata.
71
+ - [StatTile](stat-tile.md) — A labelled number: the metric loud, the label small above it, and — when there is one — a signed change that says which way it went without claiming that way is good.
72
+ - [Aurora](aurora.md) — A CSS-driven, multicolour ambient light field that decorates an existing surface without owning its content or application logic.
73
+ - [Panel / MasterPanel](panel.md) — A raised surface with a title, an optional collapse control, header actions, and a footer — plus MasterPanel, its full-height variant.
74
+ - [stack() / grid() / aspect()](layout.md) — The small pieces under Panel and SplitView: consistent spacing, a grid that reflows on its own width rather than the viewport, and a fixed-ratio box.
75
+ - [Dock](dock.md) — A stack of collapsible, resizable panes — the inspector column of a design tool, and the detail side of a master–detail screen.
76
+ - [Tabbox](tabbox.md) — Manual-activation tabs following the APG pattern: arrow keys move focus, Enter or Space selects, and panels can be built lazily.
77
+ - [Stepper](stepper.md) — The wizard progress rail: four step states, an optional “Step 2 of 4” counter, and a preventable change event so a step can refuse to be left.
78
+ - [Breadcrumb](breadcrumb.md) — 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.
79
+ - [ListToolbar](list-toolbar.md) — The bar above a record view: one search field, a live result count, the tools that change what the list shows, and the shape switch.
80
+ - [ViewSettings](view-settings.md) — 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.
81
+ - [Pagination](pagination.md) — The footer bar of a server-backed list: a page window that never changes width, a page-size select with an Auto size that fits the viewport, a row summary, an append-style Load more mode, and an Auto-load switch for infinite scrolling.
82
+ - [NavigationBar](navigation-bar.md) — The application header: a brand, one row of destinations with badges, and the actions that stay reachable at every width.
83
+ - [AppSidebar](app-sidebar.md) — One application-navigation component with an expanded vertical tree, a minimized vertical rail, and horizontal rail layouts.
84
+ - [ModuleBar](module-bar.md) — The module level of an application: one colour-coded tile per module in a vertical strip or a horizontal bar.
85
+ - [BlockView](block-view.md) — An answer an agent wrote, drawn block by block as prose and written to as it streams.
86
+ - [AgentThread](agent-thread.md) — A conversation with agents: messages, streamed answers, the steps a run took, and the approvals that hold it.
87
+ - [Surface](surface.md) — Interface an agent composes as JSON — a rich answer, or a dialog asking the person something — validated and drawn with the library’s own components.
88
+ - [RunStatus](run-status.md) — Where an agent's run stands: its state in a glyph and a word, what it is doing, its steps, its clock, and what it has cost against its budget.
89
+ - [Composer](composer.md) — The message box of an agent conversation: a growing text with Send and Stop, attachments, @-mentions, / commands, context chips, and queued messages.
90
+ - [PromptStarters](prompt-starters.md) — Starting points for an empty conversation.
91
+ - [ApprovalCard](approval-card.md) — A request that holds an agent’s run until a person answers it: what will happen, a preview of what it produces, and Approve, Edit, and Reject.
92
+ - [RunTrace](run-trace.md) — What an agent did during a run: a one-line summary that opens into a timeline of its steps, each tool call opening to its arguments and result.
93
+ - [SourceList](source-list.md) — The sources an answer cites, as numbered chips with a card of each one’s title, site, and the passage used.
94
+ - [Core helpers](kernel.md) — Core helpers: Component, DOM, Compact events, Icons, Positioning, i18n.
95
+ - [Icons](icons.md) — One icon() call, two renderers: the outline SVG glyphs Zx bundles, or Font Awesome once an application loads a kit.
96
+ - [Helper functions](helpers.md) — The standalone function library that ships alongside the components: dates, formatting, escaping, small utilities, translation, and keyboard behaviours.
97
+ - [truncate()](truncate.md) — 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.
98
+ - [Custom elements](elements.md) — Form controls, containers, the agent kit and the data views also ship as custom elements, so a screen can be written as markup and configured with attributes instead of constructor calls.
99
+ - [Design tokens](tokens.md) — Two tiers of CSS custom properties.
@@ -0,0 +1,42 @@
1
+ # KanbanView
2
+
3
+ A semantic opportunity board sharing fields, cards, sort, selection, and serializable configuration with the other record views.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/kanban-view · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A semantic record board with explicit or data-derived columns, optional swim lanes, shared record
8
+ cards, advisory work-in-progress limits, and equivalent pointer/programmatic/keyboard movement.
9
+
10
+ - **Options** — the shared RecordView options plus `columnBy`, `columns`, `swimlaneBy`,
11
+ `swimlanes`, card title/subtitle/preview/link/actions, `moveMode: 'local'|'external'`,
12
+ `columnOrder`, `swimlaneOrder`, collapsed IDs, `showCounts`, `showEmptyColumns`, `variant`, and
13
+ `label`. Column/lane descriptors use stable `id`, `label`, optional stored `value`, and `accept`;
14
+ columns may also declare an advisory `limit`.
15
+ - **Selection trigger** — `selectionTrigger:'card'` provides the same checkbox-free click and
16
+ keyboard selection as CardView. The default remains `'checkbox'`.
17
+ - **Methods** — configure/get/move columns and swim lanes, collapse either axis, and
18
+ `moveRecord(id,{column?,lane?,index?})`. Board-specific order/collapse joins the common view
19
+ state; record order, movement history, and selection do not. Saved preferences for data-derived
20
+ axes survive an empty/partial result set and reconcile as later records introduce their IDs.
21
+ - **Dense board layout** — bounded muted columns use a stable 20rem rail with native horizontal
22
+ overflow, 48px headings, compact counts, 8–12px card padding, and 8px card gaps. Surface cards
23
+ use an optional square thumbnail and a two-tier hierarchy from shared card field slots:
24
+ `eyebrow-start`, `eyebrow-end`, and `title-prefix`. Unslotted metadata stays as quiet inline
25
+ facts. Titles clamp visually to two lines while retaining their complete accessible text. Move
26
+ and action controls reveal on hover/focus/selection/grab, and remain visible on touch devices.
27
+ - **Assignees** — `assignees` faces (a name, names, or `{name, src?, initials?, tone?}`) are drawn
28
+ like a small Avatar: initials on the tint `avatarTone(name)` picks, so a person has the same
29
+ colour on the board as in every Avatar; a descriptor's own `tone` wins. A descriptor with `face`
30
+ (AgentAvatar traits, or `true`) is an agent, drawn as its generated face.
31
+ - **Movement boundary** — `recordmove {record,id,from,to,column,swimlane,limitExceeded}` is
32
+ cancelable and fires before a commit/request; either the component event or bubbling
33
+ `zx-recordmove` mirror may veto it. `accept` is a hard eligibility gate; WIP is visual advice.
34
+ Local mode clones the moved record and never mutates host data, and a manual local move clears an
35
+ active local sort so saved state matches visible order. External mode emits only, for server
36
+ validation and optimistic rollback owned by ZeyOS.
37
+ - **Keyboard** — focus the move handle; Enter/Space grabs or drops, Escape cancels, Left/Right
38
+ chooses a column, Up/Down chooses a bucket-relative position, and Alt+Up/Down chooses a swim
39
+ lane. A polite live region announces every target, result, and reached/exceeded WIP limit.
40
+ Collapse keeps focus on its control, including when a programmatic collapse hides the focused
41
+ card. Native drag is an enhancement. The pointer-drag preview and a keyboard-grabbed card lift
42
+ on `--zx-drag-shadow`.
@@ -0,0 +1,23 @@
1
+ # Kbd — `kbd(keys, options)`
2
+
3
+ Keycaps for every key hint: one construction in buttons, menus, the launcher, and help.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/kbd · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A factory (not a class) returning keycaps: one `<kbd class="zx-kbd">` holding a nested
8
+ `<kbd class="zx-kbd__key">` per key, which is how HTML marks up a combination. Button shortcuts,
9
+ the launcher's hints, and shortcut references all use it, so a key looks the same everywhere.
10
+
11
+ - **Signature** — `kbd(keys, { size, tone })` → `HTMLElement`. `keys` is a chord written like
12
+ `aria-keyshortcuts` (`'Mod+Shift+K'`; a literal plus as `'Mod++'`) or an array of keys for a
13
+ sequence (`['g', 'i']`). `size: 'md'|'sm'` (`sm` inside buttons and menu rows); `tone:
14
+ 'neutral'|'inherit'` (`inherit` draws the caps in the surrounding ink, for a solid button or a
15
+ dark toast). `keyLabels(keys, { apple })` returns the labels without building DOM.
16
+ - **Labels** — `Mod` is ⌘ on Apple platforms and Ctrl elsewhere; `Alt`, `Shift`, `Ctrl`,
17
+ `Backspace`, `Delete`, `Tab` become ⌥ ⇧ ⌃ ⌫ ⌦ ⇥ on Apple platforms and words elsewhere; `Enter`,
18
+ `Escape` and the arrows become ↵, Esc, ↑ ↓ ← →; single letters are upper-cased.
19
+ - **Look** — a surface fill, one hairline and a 1px foot, the label at the small size and medium
20
+ weight, centred on its capital height; a single key is square. Retint it with `--zx-kbd-ink`,
21
+ `--zx-kbd-fill` and `--zx-kbd-line` on any ancestor.
22
+ - **Accessibility** — the caps are presentation. Announce a control's shortcut with
23
+ `aria-keyshortcuts` on the control and mark a hint that repeats it `aria-hidden`.
@@ -0,0 +1,41 @@
1
+ # Core helpers
2
+
3
+ Core helpers: Component, DOM, Compact events, Icons, Positioning, i18n.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/kernel · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ - **Component** — the base class: `on`/`off`/`once`/`emit`, `listen`, `toElement`, `msg`,
8
+ `destroy`, and the static `Component.from(el)`. Options are merged over the class's
9
+ `static defaults`; a key passed as `undefined` keeps its default (also inside `msg`), `null`
10
+ overrides it. `msg(key, ...args)` always returns text: the
11
+ instance's `msg` option (a `{[lang]: {…}}` table for the active language, then flat keys), else
12
+ the host translator, else the class's built-in `msg` defaults, else the default English
13
+ catalogue, and only then the key itself; `%1`, `%2`, … are filled from `args`.
14
+ - **DOM** — `h(tag, props, ...children)`, `h.raw(html)`, `htmlEscape`, `resolveElement`.
15
+ `__(tag#id.class, properties, content)` is Zx's compact DOM builder and public alias for
16
+ `compactElement()`. It preserves `D*` data, `S*` style, boolean/built-in property, attribute,
17
+ and legacy `on*` callback rules while keeping content text-safe. `applyCompactProperties`,
18
+ `appendContent`, `appendCompact` (parent return), `appendCompactChild` (child return), and
19
+ `fragment(...children)` are the pure forms.
20
+ - **Compact events** — `onCompactEvent`, `offCompactEvent`, and `fireCompactEvent` share one
21
+ newest-first handler registry. Existing `DOM.on/remEvt/fireEvt` methods can delegate to this
22
+ triad. Zx never installs globals or alters DOM prototypes; applications decide whether to expose
23
+ these functions globally or compose them into their own UI and routing layer.
24
+ - **Icons** — `icon(name, {size, label})`, `icons`, `iconAliases`, `iconNames()`, and `ICON_SIZE` (one size per role); see the
25
+ Icons section — bundled inline SVG by default, Font Awesome after an opt-in.
26
+ - **Positioning** — `position(anchor, floating, {placement, offset, flip, matchWidth})` →
27
+ `{update, destroy}`. It anchors a manual popover with CSS anchor positioning where the browser
28
+ supports it and a scroll/resize-tracked fallback where it does not. Options are resolved once,
29
+ so changing a placement means `destroy()` and a fresh `position()` call.
30
+ - **i18n** — `setTranslator`, `setLanguage`, `getLanguage`, `translate`, `translatePlural`, `printf`, and
31
+ `defaultMessages`, the frozen English catalogue of every component key (`table.empty` → "No
32
+ records") that a host copies as the starting point for a locale.
33
+ - **Dates** — `formatDate(d, fmt, {locale})`, `parseDate(s, fmt)` (tokens
34
+ `%d %m %Y %y %H %M %S %a %A %b %B %s`), `clampDate`, `isSameDay`, `addDays`, `addMonths`,
35
+ `getWeekStart`. A supported explicit `locale` takes precedence over `getLanguage()`, then
36
+ English. Names and abbreviations come from `Intl`, preserving regional differences.
37
+ - **Keyboard** — `focusTrap`, `rovingTabindex`, `typeahead`.
38
+ - **Motion** — `prefersReducedMotion(element?)` → boolean, and
39
+ `watchMotion(element, fn, {signal?, immediate?})` → disposer, for code that animates in script;
40
+ see Theming.
41
+ - **Utils** — `debounce`, `uid`, `deepMerge`, `isElement`, `clamp`, `toArray`.
@@ -0,0 +1,66 @@
1
+ # Launcher — application and record search
2
+
3
+ A full application launcher with app tiles, current and pinned state, recent records, grouped asynchronous search, and application-owned routing.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/launcher · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A native-dialog launcher for applications, recent records, commands, and grouped remote results.
8
+ Zx owns ranking, focus, request cancellation, and presentation; ZeyOS owns the catalogue,
9
+ permissions, recent-history/cache policy, and the route or command ultimately invoked.
10
+
11
+ - **Constructor** — `new Launcher(null, options)` owns a top-layer dialog in the opener's nearest
12
+ Zx theme scope — never inside another open dialog, which it stacks above in the top layer. Open,
13
+ it is a modal on the shared overlay stack: Esc and presses inside it reach no popup left open
14
+ behind it, and toasts move into it while it is open;
15
+ `new Launcher(existingDialog, options)` enhances and later restores an existing `<dialog>`.
16
+ - **Options** — `items`, abortable `sources: [{id, label?, minQuery?, when?, order?, load(query, {signal})}]`,
17
+ `query`, `debounce: 250`, `minQuery: 0`, `maxResults: 100`, `placeholder`, `label`, `emptyText`,
18
+ `loadingText`, `shortcut: 'mod+k'|false`, visible `hints` labels `{move, open, back, close}` (or
19
+ `false`), and `scope` to explicitly select an element whose nearest Zx theme scope owns the launcher.
20
+ - **Items** — `{id, label, description?, keywords?, group?, icon?, badge?, hint?, shortcut?, keys?,
21
+ value?, href?, target?, invoke?, pinned?, disabled?, kind?, current?, when?, groupOrder?,
22
+ itemOrder?, items?, placeholder?, order?, agent?}`. `icon` accepts a bundled icon name, Node, or
23
+ factory. `agent` (AgentAvatar options, or `true`) draws the item as the agent's still face
24
+ instead — a tile's size for an `application` — with its activity's word, visually hidden, after
25
+ the label in the option's name. Links stay native so modified and middle clicks work;
26
+ non-link commands may provide an application-owned `invoke` callback. Malformed and executable
27
+ URL schemes are stripped; a descriptor with no safe link or callback is disabled. `hint` is muted
28
+ text at the end of the row (a current value, a project); `shortcut: ['⌘', 'K']` (or Button's
29
+ `{label, keys}`) draws key caps for display only, and `keys: 'Meta+K'` adds `aria-keyshortcuts`.
30
+ - **Pages** — an item with `items` opens a page instead of being selected: an array, or a loader
31
+ `(query, {signal}) => items | Promise<items>` that runs when the page opens and, debounced, as
32
+ its query changes (the loading and empty states show meanwhile; `order: 'source'` keeps the
33
+ loader's order instead of ranking it). Opening a page clears the query, shows a scope chip with
34
+ the item's label before the input — part of the combobox's name, `Search <label>` — and adds
35
+ "⌫ Back" to the footer; `placeholder` sets the page's placeholder. Page rows show a chevron.
36
+ Backspace on an empty query, ArrowLeft on an empty query, or the chip's × goes back one page,
37
+ restoring the query and highlighted row beneath; Escape closes from any page, and the next
38
+ opening starts on the root. Pages nest. `open({page})` opens straight into a page — a local page
39
+ id (at any depth of array pages, the path becoming the back stack) or a page item. A polite
40
+ status line announces each change ("Agents, 7 results").
41
+ - **Methods** — `open({page}?)`, `close()`, `toggle()`, `isOpen()`, `focus()`, `setQuery()`,
42
+ `getQuery()`, `back()`, `getPage()`, `setItems()` (the root's items), `setCurrent()`,
43
+ `setSources()`, `destroy()`.
44
+ - **Events** — cancelable `select {item, value, source, query, page}`, `query {query}`,
45
+ `page {page, path}` (after every page change; `page` is null on the root), `open`, `close`, and
46
+ `error {source, error, page}` (a failing page loader reports as source `page:<id>`). Preventing
47
+ `select` suppresses the supplied link or callback.
48
+ - **Ranking** — local results are case/diacritic-insensitive and deterministic: exact label,
49
+ label prefix, word prefix, label substring, identifier substring, then acronym prefix. Pinned
50
+ items retain an explicit order ahead of otherwise equal results. A new async query aborts and
51
+ ignores stale source work.
52
+ - **Keyboard** — Cmd+K on macOS or Ctrl+K elsewhere opens by default; the shortcut is ignored in
53
+ editable controls, composition, and modal contexts. Application tiles use spatial arrow-key
54
+ movement; Up/Down may continue into record groups. Home/End, Page Up/Down, and Enter operate the
55
+ single listbox selection model; Escape closes and restores focus. Enter, or ArrowRight with the
56
+ caret at the end of the query, opens a page row; Backspace or ArrowLeft on an empty query goes
57
+ back. `aria-current` marks the active destination independently from the keyboard's
58
+ `aria-selected` option.
59
+ - **Optional ZeyOS adapter** — import `zeyosLauncher()` or `buildZeyosLauncherConfig()` from
60
+ `@zeyos/zx/zeyos`. The adapter receives the permitted module/menu catalogue, pins, current
61
+ identifier, recent loader or cache, abortable search, destination resolvers, and application/
62
+ record icon renderers explicitly. It maps the complete shell payload without reading globals or
63
+ taking over application routing.
64
+ - **Appearance** — group labels are sentence-case captions. The application you are in
65
+ (`aria-current="page"`) takes the neutral `--zx-color-bg-current` fill and a semibold label; the
66
+ highlighted row is the lighter hover step. Neither uses the accent.
@@ -0,0 +1,33 @@
1
+ # stack() / grid() / aspect()
2
+
3
+ The small pieces under Panel and SplitView: consistent spacing, a grid that reflows on its own width rather than the viewport, and a fixed-ratio box.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/layout · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ The small layout pieces that sit under Panel, SplitView, and MasterPanel: consistent spacing, a
8
+ grid that reflows on its own width, and a fixed-ratio box. Zx ships no page grid on purpose — an
9
+ ERP screen is a shell of panels, and those components already own that layer. All three are
10
+ factories returning elements, and all three are plain classes that work just as well in static
11
+ markup with no JavaScript.
12
+
13
+ - **Factories** — `stack(options, ...children)`, `grid(options, ...children)`,
14
+ `aspect(options, ...children)`; the classes are `.zx-stack`, `.zx-grid`, `.zx-aspect`.
15
+ - **stack options** — `direction: 'column'|'row'`, `gap: 4` (1–8 picks the matching `--zx-space-*`
16
+ step; any other value is used as a CSS length), `align: 'start'|'center'|'end'|'stretch'|
17
+ 'baseline'`, `justify: 'start'|'center'|'end'|'between'|'around'`, `wrap: false`,
18
+ `inline: false`, `class: ''`.
19
+ - **grid options** — `columns: null` (the count at full width; null fills each row with as many
20
+ `min`-wide tracks as fit), `min: '16rem'` (a number is read as pixels), `gap: 4`,
21
+ `align: 'start'|'center'|'end'|'stretch'`, `class: ''`.
22
+ - **aspect options** — `ratio: '16 / 9'`, `fit: 'cover'|'contain'|'fill'`, `class: ''`.
23
+ - **Behaviour** — the grid reflows intrinsically: each track asks for its share of the row but
24
+ never goes below `min`, so `auto-fit` drops one column at a time as the container narrows. No
25
+ media query is involved, which is why a grid behaves the same in a full-width page, a split
26
+ pane, and a modal — the usual reason a "responsive" grid still breaks inside a narrow panel.
27
+ - **Breakpoints** — `breakpoints` (`sm: 480`, `md: 768`, `lg: 1024`, `xl: 1280`),
28
+ `breakpointOf(width)` → `'xs'|'sm'|'md'|'lg'|'xl'`, `matchBreakpoint(name, width)` (the script
29
+ equivalent of a `min-width` query), and `onBreakpoint(handler, {target})` → `{current, destroy}`,
30
+ which fires immediately and then on every crossing. `target` defaults to the window but takes an
31
+ **element**, watched with a `ResizeObserver` — inside a split pane the viewport width says
32
+ nothing about the space actually available. The scale lives in JavaScript rather than as tokens
33
+ because a CSS custom property cannot be used inside a media query.
@@ -0,0 +1,38 @@
1
+ # ListToolbar — the bar above a record view
2
+
3
+ The bar above a record view: one search field, a live result count, the tools that change what the list shows, and the shape switch.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/list-toolbar · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Every list carries the same four questions — what am I searching for, which records, which
8
+ columns, in what shape. The parts have always existed (`Search`, `SortControl`, `badge()`,
9
+ `button()`); this is the composition, so that every consumer stops assembling it differently and
10
+ forgetting the same thing.
11
+
12
+ - **Options** — `search: {placeholder?, value?, debounce?, clearable?}|false`, `count`,
13
+ `countText`, `views: Array<string|{id, label?, icon?}>` (string presets `auto|table|list|cards|gallery|board`),
14
+ `view`, `tools: [{id, label?, icon?, badge?, badgeKind?, pressed?, disabled?, onclick?}]`,
15
+ `label`, `msg`.
16
+ - **Methods** — `setCount()`, `setBadge()`, `setPressed()`, `setToolDisabled()`, `setTools()`,
17
+ `getTool()`, `getToolsElement()`, `addTool()`, `setView()`, `getView()`, `getSearch()`,
18
+ `setSearch()`, `focusSearch()`, `bind()`, `unbind()`.
19
+ - **Events** — `search {value}`, `viewchange {view, previous}`, `action {id, pressed, tool}`.
20
+
21
+ Three properties are the reason to use this rather than assemble your own:
22
+
23
+ - **A tool's badge is part of its accessible name**, not a second thing beside it — a tool
24
+ showing `2` announces as "Filters (2)". Once filters live behind a panel, a list can show four
25
+ rows out of twenty with nothing on screen saying why, and the badge is what prevents that.
26
+ - **The count line is a live region**, and `setCount(null)` clears it. The previous number
27
+ describes the previous filters; a stale count during a load is worse than none.
28
+ - **Tool buttons meet the 44 px target** at any spacing.
29
+
30
+ The current view and a pressed tool take the neutral `--zx-color-bg-current` fill — a mode the
31
+ list is in, not a pick — never the accent tint.
32
+
33
+ `bind(view)` is optional sugar for a `TableView`, `CardView`, or `KanbanView`: it feature-detects
34
+ rather than importing them, adopts the view's shape, and mounts the view's field chooser into the
35
+ tools slot through the view's public `mountFieldControls()` — for a default `TableView` that is its
36
+ Table's column chooser. `unbind()` hands it back to the view, and a view destroyed first takes it
37
+ with it. A chooser already mounted here with `fieldControls: {target: toolbar.getToolsElement()}`
38
+ is left where it is. The toolbar is fully functional without `bind()`.
@@ -0,0 +1,48 @@
1
+ # Spinner / ProgressBar / InlineLoading
2
+
3
+ Three shapes of "wait": a ring when the duration is unknown, a track when the share done is known, and a status line that resolves into its own outcome.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/loading · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Three shapes of "wait". A **spinner** when the duration is unknown and there is nothing to say
8
+ about progress; a **progress bar** when the completed share is known; **inline loading** when the
9
+ wait resolves into its own outcome in the place it started. `spinner()` is a factory returning an
10
+ element — there is no state to update and nothing to destroy — while the other two are components.
11
+
12
+ ## spinner()
13
+
14
+ - **Signature** — `spinner({size, label, showLabel, kind})` → `HTMLSpanElement`.
15
+ - **Options** — `size: 'sm'|'md'|'lg'` (16px, 24px, 40px), `label: ''`, `showLabel: false`,
16
+ `kind: 'accent'|'current'` — `current` draws the ring in `currentColor`, which is what a ring
17
+ inside a button or a badge needs.
18
+ - **Accessibility** — a `label` makes the element `role="status"` and keeps the text in the
19
+ accessibility tree even when `showLabel` is false; without a label the ring is `aria-hidden`,
20
+ which is correct whenever a nearby element already announces the wait.
21
+
22
+ ## ProgressBar
23
+
24
+ - **Options** — `value: 0`, `max: 100`, `label: ''`, `helperText: ''`,
25
+ `status: 'active'|'success'|'error'`, `indeterminate: false`, `size: 'md'|'sm'`,
26
+ `hideLabel: false`, `showValue: true`, `formatValue: (value, max) => string`.
27
+ - **Methods** — `get()`, `set(value, {silent})` (clamped to `[0, max]`), `percent()`, `setMax()`,
28
+ `setStatus(status, helperText?)`, `setLabel()`, `setHelperText()`, `setIndeterminate(flag)`.
29
+ - **Events** — `change {value, percent}`, `complete {value}` once the value reaches `max`.
30
+ - **Behaviour** — `status` is a display concern only: a run that failed at 100% still reads 100%.
31
+ An indeterminate bar drops `aria-valuenow` rather than reporting a number it does not have, and
32
+ under reduced motion its travelling band becomes a static muted track — visibly busy, never a
33
+ wrong number.
34
+ - **Accessibility** — the track is `role="progressbar"` with `aria-valuemin`, `aria-valuemax`,
35
+ `aria-valuenow`, and `aria-valuetext`, labelled by the visible label (kept for assistive
36
+ technology when `hideLabel` is set).
37
+
38
+ ## InlineLoading
39
+
40
+ - **Options** — `status: 'inactive'|'active'|'success'|'error'`, `description: ''`,
41
+ `size: 'sm'|'md'`, `live: true`.
42
+ - **Methods** — `get()`, `getDescription()`, `set(status, description?, {silent})`,
43
+ `setDescription()`.
44
+ - **Events** — `statuschange {status, description}`.
45
+ - **Accessibility** — the whole element is one polite live region (`role="status"`), so the
46
+ outcome is announced without the focus moving off the control that started the work. Use
47
+ `Message` instead when the outcome deserves a dismissible notification rather than a line of
48
+ text that stays put.
@@ -0,0 +1,47 @@
1
+ # MenuButton — APG menu button
2
+
3
+ A trigger and its menu, following the APG menu button pattern: typeahead, wrapping arrows, and focus returned to the trigger on close.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/menu-button · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A button that opens a `role="menu"`.
8
+
9
+ - **Options** — `label`, `icon`, `kind`, `placement`, and a shared `items` entry model:
10
+ - `'-'` or `{type: 'separator'}` draws a separator; `{type: 'heading', label}` draws a visible,
11
+ non-interactive heading.
12
+ - Actions keep `label`, `icon`, `value`, `disabled`, `danger`, and `onselect`, and may add
13
+ `description`, `badge`, `shortcut`, or a text/Node `adornment`.
14
+ - `href`, `target`, and `rel` render a genuine safe native link, preserving modifier clicks and
15
+ targets. Executable URL schemes are rejected; `_blank` receives `noopener noreferrer` by
16
+ default.
17
+ - `role: 'menuitemcheckbox'|'menuitemradio'` with `checked` exposes an APG checked action.
18
+ Choosing one updates it in place — a checkbox toggles, a radio is checked and the other radio
19
+ items of its section (between separators or headings) are unchecked — and `select` reports the
20
+ new state as `detail.checked`. Preventing `select` leaves the state as it was; the item objects
21
+ passed in are not modified, so call `setItems()` to keep the model in step.
22
+ - `{type: 'choice', label, value, options: [{value, label, icon|glyph}], onselect(value, entry,
23
+ menu)}` draws a setting chosen in place — a theme, a layout: the label, then a small segmented
24
+ group of `menuitemradio` options named by it. Choosing an option checks it and calls
25
+ `onselect`; the menu stays open so the change shows, and `select` does not fire. Left and Right
26
+ move within the row; Up and Down leave it, landing on another row's checked option.
27
+ `AccountMenu` takes the same entries; `ContextMenu`, which closes on every activation, leaves
28
+ them out.
29
+ - **Methods** — `setItems()`, `open({returnFocus})`, `close()`, `toggle()` (opens when closed,
30
+ closes when open, moves no focus), `isOpen()`, `setLabel()`, `getTrigger()`, `getPanel()`,
31
+ `focusFirst({returnFocus})`, `focusLast({returnFocus})`.
32
+ - **Events** — `select {value, item}`, `open`, `close`.
33
+ - **Focus return** — choosing an item closes the menu and returns focus to the trigger before the
34
+ `select` event and the item's `onselect` run, so a dialog they open returns to the trigger when
35
+ it closes, and focus they move themselves stays where they put it. Escape returns focus the same
36
+ way. `returnFocus` sets the destination for one opening: `true` (default) is the trigger, an
37
+ element is that element — the list row a keyboard shortcut opened the menu from — and `false`
38
+ leaves focus alone.
39
+ - **Cancellation** — `select` is cancelable. Preventing it skips the item's `onselect` callback and
40
+ leaves the menu open with focus back on the item, which is the composition seam used by
41
+ `AccountMenu` and rail flyouts.
42
+ - **Keyboard** — ArrowDown/Enter/Space open and focus the first item; ArrowUp opens and focuses the
43
+ last; arrows cycle; Home/End; typeahead; Enter/Space select; Esc/Tab close. Esc reaches the menu
44
+ through the overlay stack, so inside a Sheet or Dialog it closes the menu and leaves the sheet
45
+ open; a menu opened inside a modal Dialog is hosted by it and stays usable.
46
+ - **Appearance** — the highlighted item is a neutral step, a checked item keeps its accent check
47
+ mark, and section headings are sentence-case captions. ContextMenu shares the same rules.