@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,299 @@
1
+ # Xenon Design System (Zx) — small reference
2
+
3
+ > Xenon is a dependency-free design system for browser applications; Zx is its vanilla-JavaScript
4
+ > implementation. This is the small tier of its agent documentation: how every component works,
5
+ > which layout and which component a screen needs, what never to build, and how a model composes
6
+ > surfaces at runtime. Each component has its own file, listed at the end; the complete reference is
7
+ > https://zx.zeyos.com/docs/llms.md.
8
+
9
+ ## Mental model
10
+
11
+ Every visual component is an ES class extending `Component`, instantiated identically:
12
+
13
+ ```js
14
+ import { Table, Dialog, Toggle } from '/assets/zx.esm.js'; // or window.zx.* from zx.global.js
15
+ const t = new Table(target, options);
16
+ ```
17
+
18
+ - **`target`** — an `Element`, a selector string, or `null`. `null` means the component creates and
19
+ **owns** its root element; retrieve it with `t.toElement()` (or `t.el`) and insert it. A non-null
20
+ target is *enhanced in place* and restored on `destroy()`.
21
+ - **Options** — a plain object; each component declares `static defaults`. Never mutate the passed
22
+ object. An option passed as `undefined` is an option not passed: it keeps the declared default,
23
+ at the top level and inside `msg`, so a wrapper can forward `{ label: props.label }` without
24
+ filtering unset props. `null` is a value and overrides the default. The merged options are
25
+ frozen; change a live component through its methods (see "Using Zx from a framework").
26
+ - **Value/data** — set via constructor options and mutated via methods (`set`, `setData`, …);
27
+ read via getters/methods (`.value`, `getValues()`, …).
28
+
29
+ ### Events & lifecycle
30
+
31
+ - Subscribe with `t.on('change', fn)` (alias `addEvent`), `t.once(...)`, or an `on<type>` function
32
+ **option** (`onchange`, `onrowclick`, …). Handlers receive a `CustomEvent`; read `event.detail`
33
+ (always an object, e.g. `{ value, item }`).
34
+ - Every `emit` also dispatches a **bubbling, composed** `zx-<type>` `CustomEvent` on `t.el`, so
35
+ `t.el.addEventListener('zx-change', …)` and event delegation work.
36
+ - Mutation boundaries may opt into honoring cancellation of that mirrored DOM event; Kanban's
37
+ `zx-recordmove` does, so delegated hosts can veto a move without a component reference.
38
+ - `t.destroy()` aborts all listeners (one AbortController), unregisters the element, and removes an
39
+ owned root. `Component.from(el)` returns the component for a root element (replaces the legacy
40
+ `el.retrieve('com')`).
41
+
42
+ ## Start from a layout, not a blank page
43
+
44
+ Every layout in the gallery (<https://zx.zeyos.com/layouts>, `layouts.html#<id>` opens one,
45
+ `layout.html#<id>` shows it alone) is a complete, working screen on one shared application shell,
46
+ and its source is public: `https://zx.zeyos.com/layouts/<id>.layout.js` with `<id>.layout.css`
47
+ (in the repository, `website/layouts/`). Open the closest one, keep its anatomy — the columns,
48
+ the pane headers, the toolbar, the drawers, the states, the keyboard map — and change the data,
49
+ the fields, and the copy.
50
+
51
+ The helpers a layout imports are public too, and meant to be copied beside application code
52
+ (they are documentation-site modules, not package exports; import them relatively):
53
+
54
+ - `layouts/kit.js` + `kit.css` — the shell: `.shell` and its columns, `paneHeader()`,
55
+ `propList()`, `.list-row`, `.surface`, `suiteNav()` (module strip + module menu, with a
56
+ `workspace` switcher), `adaptiveShell()` (every column stays reachable at any width),
57
+ `shortcuts()` and `shortcutSheet()` (`?`), `toast()`, `loadChartJs()`.
58
+ - `layouts/overview.js` + `overview.css` — `createOverview()`: one toolbar over one record set
59
+ shown as table, list, cards, gallery, or board; search; filters as editable chips with a Filters
60
+ drawer; a View settings drawer; grouping, sorting, paging, selection and bulk actions; a base
61
+ filter for tabs and scopes; split empty states. The record collection, CRM, and issue tracker
62
+ are all this one composition.
63
+
64
+ Which layout a screen is:
65
+
66
+ | The screen | Start from | Not from |
67
+ | --- | --- | --- |
68
+ | A list of records of one type (companies, tickets, orders, files) | **Record collection** (`record-collection`) — the toolbar, chips, drawers and pager come with it | a bare `Table` under a heading |
69
+ | A list beside the record being edited | **Master–detail** (`master-detail`) | two unrelated panes |
70
+ | One record on its own page | **Record page** (`record-page`) | a form |
71
+ | Figures, charts, a period switch | **Dashboard** (`dashboard`) | cards of big numbers |
72
+ | Settings in sections | **Settings workspace** (`settings-workspace`) | one long form |
73
+ | Creating something in steps | **Record wizard** (`record-wizard`, vertical steps) or **Checkout wizard** (`checkout-wizard`, horizontal) | tabs |
74
+ | Conversations, triage | **Inbox** (`inbox`) or the **Mail** template | — |
75
+ | An assistant | **Agent chat** (`agent-chat`, one run with tools and approvals) or the **AI chat** template | a chat bubble list |
76
+ | Empty, loading, error, offline, confirmation | **System states** (`system-states`) — every screen needs these; copy them | ad-hoc messages |
77
+ | A whole application | the closest **template** below; they share one shell | a new shell |
78
+
79
+ Templates — complete applications with navigation, lists, records, and editors together:
80
+
81
+ | id | Screen | Use it for |
82
+ | --- | --- | --- |
83
+ | `mail` | Mail | a keyboard-first inbox: split streams, one-key triage, snooze, inline reply |
84
+ | `issue-tracker` | Issue tracker | work items grouped by status or on a board, chips, sub-items, activity, properties edited in place |
85
+ | `wiki` | Knowledge base | nested pages in spaces, a reading column with a live outline, comments, Markdown editing |
86
+ | `ai-chat` | AI chat | chat with an assistant: tool steps, sources, artifacts with versions, per-chat settings |
87
+ | `agent-workspace` | Agent workspace | a team of agents: roster with presence, plans and logs, approvals, a palette, a terminal |
88
+ | `invoice-editor` | Invoice editor | a document edited beside its live page, totals per rate, a send step that locks it |
89
+ | `item-inventory` | Item & inventory | one master-data record: levels per location, linked documents, tabbed settings, a log |
90
+ | `workflows` | Workflows | recurring processes as step flows: built, run, measured |
91
+ | `infrastructure` | Infrastructure | monitoring: health, alerts, traffic, drill-down to the unit |
92
+ | `crm` | CRM | companies, people, deals: editable collections with saved views, record pages, a stage board |
93
+
94
+ Patterns — single screens that recur in every application:
95
+
96
+ | id | Screen | What it shows |
97
+ | --- | --- | --- |
98
+ | `master-detail` | Master–detail | a filterable list beside the record being edited; save, revert, unsaved-change checks |
99
+ | `record-collection` | Record collection | one record type as table, list, cards, gallery, and board under one toolbar; filter chips and drawers |
100
+ | `dashboard` | Dashboard | figures, a chart, tabbed detail, one period switch redrawing all of it |
101
+ | `inbox` | Inbox | three panes: folders, conversations, the open thread with a reply |
102
+ | `record-page` | Record page | one record: summary header, tabs for lines, files and history, editable details |
103
+ | `agent-chat` | Agent chat | one agent run: plan, tool calls, an approval that holds it, a streamed answer with sources |
104
+ | `agent-canvas` | Agent canvas | every answer a `surface/1` document — figures and a chart, a review, forms, a questionnaire — with its JSON, versions and reply in a panel |
105
+ | `record-wizard` | Record wizard | creation in validated vertical steps with a running total and a review |
106
+ | `checkout-wizard` | Checkout wizard | a focused horizontal flow beside a live summary |
107
+ | `settings-workspace` | Settings workspace | personal settings in sections, saved together |
108
+ | `system-states` | System states | every empty, loading, error, and confirmation state, with an offline switch |
109
+ | `zeyos-invoices` | ZeyOS invoices | a table and a form generated from the ZeyOS schema, beside the ZeyOS module navigation |
110
+
111
+ Every application shares one shell: `AppSidebar` (or `ModuleBar` for the module level) with
112
+ `AccountMenu`, a `WorkspaceSwitcher` where users have several workspaces, a `Launcher` as the
113
+ command palette, `?` for the shortcut sheet, and `data-zx-theme` honoured throughout. Do not design
114
+ a second navigation.
115
+
116
+ ## The component for the job
117
+
118
+ | Job | Use | Rather than |
119
+ | --- | --- | --- |
120
+ | Records the user scans, sorts, selects | `Table`; `TableView` when the same records also appear as cards or a board | a styled `<table>`, a list of `<div>`s |
121
+ | Records as cards or a gallery | `CardView` (`keyboard: 'roving'`, `groupBy`, `collapsibleGroups`) | `Card`s in a CSS grid |
122
+ | Records by stage, dragged between columns | `KanbanView` | — |
123
+ | One record set, several presentations, one state | `RecordView` family + `ListToolbar` + `ViewSettings` + `Pagination` — `createOverview()` wires them | three components with three states |
124
+ | The bar above a record view | `ListToolbar` (search, live count, view switch, badged tools) | a row of buttons |
125
+ | Sorting outside a header | `SortControl` | two selects |
126
+ | Paging | `Pagination` (`paginationRange()` for the numbers) | — |
127
+ | Filters, quick and client-side | `DataFilter` | — |
128
+ | Filters typed from a server's field metadata | `FilterPanel` (`mode: 'draft'|'live'`) | — |
129
+ | Filters the user composes, nested, serialisable | `Filter` (an AST; `parseFilterAst()`/`stringifyFilterAst()`) | — |
130
+ | A spreadsheet-like editable grid (lines, positions) | `Grid` (`Grid.BillingItems()`) | `Table` with `editMode` — that is for occasional cell edits |
131
+ | A tree | `TreeView` (one column) or `Finder` (Miller columns) | nested `<ul>`s |
132
+ | Events over time | `Calendar` (agenda, day, week, month, year) | — |
133
+ | One number with context | `StatTile` (delta, sparkline, loading; plain and one leading for a record's figures) | a card with a big figure |
134
+ | A chart | `Chart` with `SvgChartAdapter` (bar, line, pie, doughnut; no dependency), or `ChartJsAdapter` for other types (Chart.js injected, never bundled) | a hand-drawn SVG |
135
+ | A linked record inline | `EntityRef` | a link |
136
+ | Files | `FileItem` / `FileList`; uploading: `FieldUpload` | — |
137
+ | History, comments, a feed | `ActivityItem` / `ActivityList` | — |
138
+ | Choose one of many | `Select` (`filter: 'local'` or async for long lists; `Select.entity()` for records; `Select.priority()` / `Select.status()` presets); native radios for a handful of visible options | a custom dropdown |
139
+ | Choose many | `TagPicker` (identity, colour, icons), `Checklist` (a plain list) | — |
140
+ | On or off | `Toggle` (takes effect at once), `CheckButton` (a mode in a toolbar), a native checkbox inside a form | — |
141
+ | Search | `Search` | an input with an icon |
142
+ | Number, date, time, range | `NumberField`, `Datebox` / `DateTimeBox`, `Timebox`, `DateRangeBox`, `Slider`, `Rating` | plain inputs |
143
+ | A form | `Form` → `Fieldset` → `Field` (the type registry); `Questionnaire` for one question at a time | hand-laid inputs |
144
+ | Structured text, code | `CodeEditor` | a textarea |
145
+ | Repeating values | `ValueList`, `MultiValueEditor` | — |
146
+ | Confirm, alert, prompt | `Dialog.confirm()` / `Dialog.alert()` / `Dialog.prompt()` (Promises) | `window.confirm` |
147
+ | A task in a window | `Dialog` (header, footer, buttons); `Modal` is the bare surface | — |
148
+ | Edit without leaving the list | `Sheet` (`side: 'end'`); drill-down: `SheetStack`; a persistent pane: `Dock` | a dialog |
149
+ | Transient status | `Message.success()` / `.info()` / `.warning()` / `.error()` (toasts); inline `Message` for a region | an alert bar built by hand |
150
+ | Actions on a thing | `MenuButton`; `ContextMenu` (right-click and Shift+F10; one instance per table via `selector`) | a floating `<div>` |
151
+ | Anchored content, hints | `Dropdown`; `tooltip()` / `describe()` | `title` attributes alone |
152
+ | A row of actions | `Toolbar` (overflow menu, one Tab stop) | a flex row of buttons |
153
+ | Navigation | `AppSidebar` (tree, sections, `layout: 'modules'`), `ModuleBar`, `NavigationBar`, `Tabbox` (in-page), `Breadcrumb` (where am I), `Stepper` (a sequence) | — |
154
+ | Commands by keyboard | `Launcher` | — |
155
+ | Account and workspace | `AccountMenu`, `WorkspaceSwitcher` | — |
156
+ | Grouping content | `Card`, `Panel` (actions in the header or footer), `Groupbox`, `MasterPanel`, `SplitView`, `stack()` / `grid()` / `aspect()` | ad-hoc wrappers |
157
+ | Identity and status marks | `Avatar`, `AppIcon`, `badge()` (`kind` says how it is doing, `tone` what it is) | coloured spans |
158
+ | Nothing yet, loading, failed | `emptyState()`, `skeleton()` / `skeletonText()` / `skeletonTable()`, `InlineLoading`, `spinner()`, `ProgressBar` | a blank area |
159
+ | Ambient colour behind a hero, a login, a launcher | `Aurora` | CSS gradients |
160
+ | Icons | `icon(name)` — the bundled set or Font Awesome, whichever the application opted into | inline SVG |
161
+
162
+ ## Never
163
+
164
+ - No raw colours (`#hex`, `rgb()`, named), no tier-1 tokens (`--zx-gray-*`, `--zx-emerald-*`,
165
+ `--zx-tone-*`), no hard-coded sizes the geometry tokens cover.
166
+ - No application CSS on component internals (`.zx-<component>__<part>` selectors); override a
167
+ token, or use a published hook.
168
+ - No hand-built dropdowns, menus, dialogs, tooltips, tables, date pickers, or toasts.
169
+ - No `innerHTML` with data; `h()` and text nodes.
170
+ - No state classes; state is ARIA and `data-state`, which the stylesheets already match.
171
+ - No second shell, second navigation, or second keyboard convention inside one application.
172
+
173
+ The theming decisions — theme, accent, geometry, material, motion, colour roles, type — are in "Choosing what to build with" in https://zx.zeyos.com/docs/llms.md.
174
+
175
+ ## Composing surfaces at runtime
176
+
177
+ At runtime, a model composes interface as `surface/1` JSON — never HTML — and the application validates it and draws it with Zx components. Each surface declares one intent and ends in exactly one reply; treat a reply as the person's answer, not as proof that anything happened. When validation reports errors, return them to the model so it can correct the surface.
178
+
179
+ | Intent | Needs | Default actions | Reply values |
180
+ | --- | --- | --- | --- |
181
+ | `show` | — | — | No values. Actions are optional; closing the surface replies `dismiss`. |
182
+ | `ask` | a `fields` | Submit, Cancel | The values of its inputs, by name. |
183
+ | `choose` | a `choice` | Submit, Cancel | The picked value under the choice's name; a list when `multiple`. |
184
+ | `confirm` | — | Confirm, Cancel | `{}`. The application may ask the person to type a confirmation. |
185
+ | `review` | a `diff` or a `table` | Approve selected, Reject | The ids of the accepted diff rows or selected table rows, under the input's name. |
186
+ | `questionnaire` | a `questionnaire` | Cancel | `{answers, path}`: the answers by step name and the steps taken. |
187
+
188
+ Give the model the narrowest profile that does the job — `surfacePrompt(CATALOG, { profile })`, `surfaceTools(CATALOG, { profile })`, `narrowCatalog(CATALOG, { profile })`; leaving it out is the whole catalog:
189
+
190
+ - `answer` — intents `show`; nodes `text`, `heading`, `list`, `code`, `callout`, `figures`, `table`, `stat`, `badge`, `ref`, `link`, `chart`, `empty`, `stack`, `columns`, `group`.
191
+ - `ask` — intents `show`, `ask`, `choose`, `confirm`; nodes `text`, `heading`, `list`, `code`, `callout`, `figures`, `table`, `stat`, `badge`, `ref`, `link`, `chart`, `empty`, `stack`, `columns`, `group`, `fields`, `choice`.
192
+ - `review` — intents `show`, `ask`, `choose`, `confirm`, `review`; nodes `text`, `heading`, `list`, `code`, `callout`, `figures`, `table`, `stat`, `badge`, `ref`, `link`, `chart`, `empty`, `stack`, `columns`, `group`, `fields`, `choice`, `diff`.
193
+ - `full` — intents `show`, `ask`, `choose`, `confirm`, `review`, `questionnaire`; nodes `text`, `heading`, `list`, `quote`, `code`, `callout`, `figures`, `table`, `stat`, `badge`, `ref`, `link`, `chart`, `empty`, `stack`, `columns`, `group`, `fields`, `choice`, `diff`, `questionnaire`.
194
+
195
+ Limits per surface: 400 nodes, 8 actions, 20,000 characters per string. Every node says when to use it and when not to in the guide and the catalogue.
196
+
197
+ - Model-facing guide: https://zx.zeyos.com/docs/agent-surfaces.md
198
+ - Catalogue, JSON Schema and tool definitions: https://zx.zeyos.com/docs/agent-catalog.json
199
+ - The Surface component: https://zx.zeyos.com/docs/components/surface.md
200
+
201
+ ## Component files
202
+
203
+ Each is the component's section of the full reference: https://zx.zeyos.com/docs/components/<id>.md.
204
+
205
+ - [ZeyOS binding (zx-zeyos)](https://zx.zeyos.com/docs/components/zeyos.md)
206
+ - [Prose](https://zx.zeyos.com/docs/components/prose.md)
207
+ - [Kbd](https://zx.zeyos.com/docs/components/kbd.md)
208
+ - [Button](https://zx.zeyos.com/docs/components/button.md)
209
+ - [Badge](https://zx.zeyos.com/docs/components/badge.md)
210
+ - [Toolbar](https://zx.zeyos.com/docs/components/toolbar.md)
211
+ - [EmptyState](https://zx.zeyos.com/docs/components/empty-state.md)
212
+ - [Spinner / ProgressBar / InlineLoading](https://zx.zeyos.com/docs/components/loading.md)
213
+ - [Skeleton](https://zx.zeyos.com/docs/components/skeleton.md)
214
+ - [CheckButton](https://zx.zeyos.com/docs/components/check-button.md)
215
+ - [Toggle](https://zx.zeyos.com/docs/components/toggle.md)
216
+ - [Search](https://zx.zeyos.com/docs/components/search.md)
217
+ - [Launcher](https://zx.zeyos.com/docs/components/launcher.md)
218
+ - [AppIcon](https://zx.zeyos.com/docs/components/app-icon.md)
219
+ - [Avatar](https://zx.zeyos.com/docs/components/avatar.md)
220
+ - [AgentAvatar](https://zx.zeyos.com/docs/components/agent-avatar.md)
221
+ - [EntityRef](https://zx.zeyos.com/docs/components/entity-ref.md)
222
+ - [FileItem](https://zx.zeyos.com/docs/components/file-item.md)
223
+ - [FileList](https://zx.zeyos.com/docs/components/file-list.md)
224
+ - [ActivityItem](https://zx.zeyos.com/docs/components/activity-item.md)
225
+ - [ActivityList](https://zx.zeyos.com/docs/components/activity-list.md)
226
+ - [AccountMenu](https://zx.zeyos.com/docs/components/account-menu.md)
227
+ - [WorkspaceSwitcher](https://zx.zeyos.com/docs/components/workspace-switcher.md)
228
+ - [Select](https://zx.zeyos.com/docs/components/select.md)
229
+ - [SortControl](https://zx.zeyos.com/docs/components/sort-control.md)
230
+ - [Checklist](https://zx.zeyos.com/docs/components/checklist.md)
231
+ - [NumberField](https://zx.zeyos.com/docs/components/number-field.md)
232
+ - [Rating](https://zx.zeyos.com/docs/components/rating.md)
233
+ - [Slider](https://zx.zeyos.com/docs/components/slider.md)
234
+ - [copyButton() / CopyInput](https://zx.zeyos.com/docs/components/copy.md)
235
+ - [DatePicker / MonthPicker / TimePicker](https://zx.zeyos.com/docs/components/date-picker.md)
236
+ - [Datebox / DateTimeBox](https://zx.zeyos.com/docs/components/datebox.md)
237
+ - [DateRangePicker / DateRangeBox](https://zx.zeyos.com/docs/components/date-range.md)
238
+ - [Timebox](https://zx.zeyos.com/docs/components/timebox.md)
239
+ - [Message](https://zx.zeyos.com/docs/components/message.md)
240
+ - [Modal](https://zx.zeyos.com/docs/components/modal.md)
241
+ - [Dialog (extends Modal)](https://zx.zeyos.com/docs/components/dialog.md)
242
+ - [Sheet](https://zx.zeyos.com/docs/components/sheet.md)
243
+ - [SheetStack](https://zx.zeyos.com/docs/components/sheet-stack.md)
244
+ - [Dropdown](https://zx.zeyos.com/docs/components/dropdown.md)
245
+ - [MenuButton](https://zx.zeyos.com/docs/components/menu-button.md)
246
+ - [ContextMenu](https://zx.zeyos.com/docs/components/context-menu.md)
247
+ - [Tooltip](https://zx.zeyos.com/docs/components/tooltip.md)
248
+ - [SplitView](https://zx.zeyos.com/docs/components/split-view.md)
249
+ - [Table](https://zx.zeyos.com/docs/components/table.md)
250
+ - [TableView and the shared RecordView contract](https://zx.zeyos.com/docs/components/table-view.md)
251
+ - [CardView](https://zx.zeyos.com/docs/components/card-view.md)
252
+ - [KanbanView](https://zx.zeyos.com/docs/components/kanban-view.md)
253
+ - [Grid and Grid.BillingItems()](https://zx.zeyos.com/docs/components/grid.md)
254
+ - [Chart, SvgChartAdapter and ChartJsAdapter](https://zx.zeyos.com/docs/components/chart.md)
255
+ - [Calendar](https://zx.zeyos.com/docs/components/calendar.md)
256
+ - [DataFilter](https://zx.zeyos.com/docs/components/data-filter.md)
257
+ - [FilterPanel](https://zx.zeyos.com/docs/components/filter-panel.md)
258
+ - [Filter](https://zx.zeyos.com/docs/components/filter.md)
259
+ - [TreeView](https://zx.zeyos.com/docs/components/tree.md)
260
+ - [Finder](https://zx.zeyos.com/docs/components/finder.md)
261
+ - [Form / Fieldset / Field](https://zx.zeyos.com/docs/components/form.md)
262
+ - [Field widget types](https://zx.zeyos.com/docs/components/form-widgets.md)
263
+ - [CodeEditor](https://zx.zeyos.com/docs/components/code-editor.md)
264
+ - [Questionnaire](https://zx.zeyos.com/docs/components/questionnaire.md)
265
+ - [ValueList](https://zx.zeyos.com/docs/components/value-list.md)
266
+ - [MultiValueEditor](https://zx.zeyos.com/docs/components/multi-value-editor.md)
267
+ - [FieldUpload](https://zx.zeyos.com/docs/components/field-upload.md)
268
+ - [TagPicker](https://zx.zeyos.com/docs/components/tag-picker.md)
269
+ - [Groupbox](https://zx.zeyos.com/docs/components/groupbox.md)
270
+ - [Card](https://zx.zeyos.com/docs/components/card.md)
271
+ - [StatTile](https://zx.zeyos.com/docs/components/stat-tile.md)
272
+ - [Aurora](https://zx.zeyos.com/docs/components/aurora.md)
273
+ - [Panel / MasterPanel](https://zx.zeyos.com/docs/components/panel.md)
274
+ - [stack() / grid() / aspect()](https://zx.zeyos.com/docs/components/layout.md)
275
+ - [Dock](https://zx.zeyos.com/docs/components/dock.md)
276
+ - [Tabbox](https://zx.zeyos.com/docs/components/tabbox.md)
277
+ - [Stepper](https://zx.zeyos.com/docs/components/stepper.md)
278
+ - [Breadcrumb](https://zx.zeyos.com/docs/components/breadcrumb.md)
279
+ - [ListToolbar](https://zx.zeyos.com/docs/components/list-toolbar.md)
280
+ - [ViewSettings](https://zx.zeyos.com/docs/components/view-settings.md)
281
+ - [Pagination](https://zx.zeyos.com/docs/components/pagination.md)
282
+ - [NavigationBar](https://zx.zeyos.com/docs/components/navigation-bar.md)
283
+ - [AppSidebar](https://zx.zeyos.com/docs/components/app-sidebar.md)
284
+ - [ModuleBar](https://zx.zeyos.com/docs/components/module-bar.md)
285
+ - [BlockView](https://zx.zeyos.com/docs/components/block-view.md)
286
+ - [AgentThread](https://zx.zeyos.com/docs/components/agent-thread.md)
287
+ - [Surface](https://zx.zeyos.com/docs/components/surface.md)
288
+ - [RunStatus](https://zx.zeyos.com/docs/components/run-status.md)
289
+ - [Composer](https://zx.zeyos.com/docs/components/composer.md)
290
+ - [PromptStarters](https://zx.zeyos.com/docs/components/prompt-starters.md)
291
+ - [ApprovalCard](https://zx.zeyos.com/docs/components/approval-card.md)
292
+ - [RunTrace](https://zx.zeyos.com/docs/components/run-trace.md)
293
+ - [SourceList](https://zx.zeyos.com/docs/components/source-list.md)
294
+ - [Core helpers](https://zx.zeyos.com/docs/components/kernel.md)
295
+ - [Icons](https://zx.zeyos.com/docs/components/icons.md)
296
+ - [Helper functions](https://zx.zeyos.com/docs/components/helpers.md)
297
+ - [truncate()](https://zx.zeyos.com/docs/components/truncate.md)
298
+ - [Custom elements](https://zx.zeyos.com/docs/components/elements.md)
299
+ - [Design tokens](https://zx.zeyos.com/docs/components/tokens.md)