@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
package/docs/llms.txt CHANGED
@@ -6,33 +6,59 @@
6
6
  > and lifecycle-safe components. Source modules run directly in the browser; a build step emits ESM, IIFE-global,
7
7
  > ZeyOS binding, and CSS bundles. Zero runtime dependencies.
8
8
 
9
+ ## Rules for agents
10
+ - Start every screen from the closest layout (see "Start here: choosing"), never from a blank page.
11
+ - Use only the options, methods, and events the reference documents; never style component internals.
12
+ - Style with semantic `--zx-*` tokens only: no raw colours, no tier-1 palette tokens, no fixed sizes.
13
+ - Never assign `innerHTML` with data; build with `h()` and text nodes.
14
+ - Render every icon through `icon(name)`, never as hand-written SVG or icon-font markup.
15
+ - Put any animation of your own inside `@media (prefers-reduced-motion: no-preference)`.
16
+ - At runtime, have the model emit `surface/1` JSON for the application to validate and draw, never HTML.
17
+ - Give the model the narrowest surface profile that does the job: `answer`, then `ask`, `review`, `full`.
18
+ - Treat a surface reply as the person's answer, not as proof that anything happened.
19
+
20
+ ## Writing Zx code
9
21
  Instantiate every component as `new Component(target, options)` where `target` is an Element, a
10
22
  selector string, or `null` (the component creates and owns its root, retrieved via `.toElement()`).
11
23
  Subscribe with `.on(type, fn)` or an `on<type>` option; handlers receive a `CustomEvent` whose
12
24
  `.detail` is an object. Call `.destroy()` to clean up. The same API is available as ESM named
13
25
  exports and as `window.zx.*`.
14
26
 
27
+ - [Small reference](https://zx.zeyos.com/docs/llms-small.txt): read this first — the mental model, the layout and the component for each job, what never to build, and surface profiles, in under 8k tokens.
28
+ - [Component files](https://zx.zeyos.com/docs/components/index.md): one Markdown file per component (`docs/components/<id>.md`), each its section of the full reference with a one-line summary and its live demo.
29
+ - [API reference](https://zx.zeyos.com/docs/llms.md): the complete reference — options, methods, events, core helpers, and the theming decisions.
30
+ - [Documentation site](https://zx.zeyos.com/docs.html): supported APIs, live demos, and example source; every component page can copy its reference and a prompt for a coding agent.
31
+ - [Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales): add languages, regional catalogues, custom message keys, interpolation variables, plurals, and formatting options.
32
+ - [Frameworks guide](https://zx.zeyos.com/docs.html#getting-started/frameworks): mount the class API from React or Vue — lifecycle, the double mount in development, framework content inside a component, controlled props, and unit tests under jsdom.
33
+ - [README](https://zx.zeyos.com/README.md): installation, component index, theming, and browser support.
34
+ - [Changelog](https://zx.zeyos.com/CHANGELOG.md): supported changes and upgrade notes.
35
+
36
+ ## Composing surfaces at runtime
37
+ A model composes interface as `surface/1` JSON — a rich answer, a form, a choice, a confirmation,
38
+ a review — and the application validates it and draws it with Zx components (`Surface`,
39
+ `openSurface()`). On the server, `surfaceTools(CATALOG, { profile })` and
40
+ `surfacePrompt(CATALOG, { profile })` from `@zeyos/zx/src/components/surface/catalog.js` give the
41
+ model its tools and guide for the narrowest profile that does the job. Every surface ends in
42
+ exactly one reply; when validation reports errors, return them to the model to correct the surface.
43
+
44
+ - [Surface guide](https://zx.zeyos.com/docs/agent-surfaces.md): the model-facing guide — intents, every node with when to use it and when not to, rules, worked examples, and the reply contract.
45
+ - [Surface catalogue](https://zx.zeyos.com/docs/agent-catalog.json): the machine-readable catalogue, its JSON Schema, the tool definitions, and what each profile keeps.
46
+ - [Surface component](https://zx.zeyos.com/docs/components/surface.md): `Surface`, `openSurface()`, `elicit()` — options, policy, streaming, and the reply.
47
+
15
48
  ## Optional integration requirements
16
49
 
17
50
  Zx has no package runtime dependencies and its source modules import no external runtime packages.
18
- Optional integrations still need application-provided assets or clients. `Chart` requires an injected
19
- renderer; the only supplied renderer, `ChartJsAdapter`, requires Chart.js 4 supplied by the host.
20
- There is no built-in chart renderer. Chart.js 4.5.1 is pinned as a development dependency and copied
21
- to the documentation site's self-hosted vendor assets during its build; it is not bundled into Zx.
51
+ Optional integrations still need application-provided assets or clients. `Chart` draws through an
52
+ adapter: the built-in `SvgChartAdapter` draws bar, line, pie and doughnut charts as SVG with nothing
53
+ else loaded, and `Surface` draws its `chart` nodes with it by default; `ChartJsAdapter` draws any
54
+ Chart.js 4 type with a Chart.js the host supplies. Chart.js 4.5.1 is pinned as a development
55
+ dependency and copied to the documentation site's self-hosted vendor assets during its build; it is
56
+ not bundled into Zx.
22
57
  Core icons use bundled SVG by default. Opting into Font Awesome requires host-loaded CSS or a kit.
23
58
  ZeyOS `moduleIcon()`, `moduleChip()`, and `zeyosAppIcon()` default to glyphs from the external custom
24
59
  ZeyOS Font Awesome kit; `standard: true` still needs stock Font Awesome assets. `ZeyOS.connect()`
25
60
  requires an injected compatible client and never imports the client package.
26
61
 
27
- ## Documentation
28
- - [Documentation site](https://zx.zeyos.com/docs.html): supported APIs, live demos, and example source.
29
- - [Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales): add languages, regional catalogues, custom message keys, interpolation variables, plurals, and formatting options.
30
- - [README](https://zx.zeyos.com/README.md): installation, component index, theming, and browser support.
31
- - [API reference](https://zx.zeyos.com/docs/llms.md): options, methods, events, and core helpers.
32
- - [Surface guide](https://zx.zeyos.com/docs/agent-surfaces.md): agent-authored surfaces and their reply contract.
33
- - [Component catalogue](https://zx.zeyos.com/docs/agent-catalog.json): machine-readable surface component schemas.
34
- - [Changelog](https://zx.zeyos.com/CHANGELOG.md): supported changes and upgrade notes.
35
-
36
62
  ## Start here: choosing
37
63
  - Start every screen from the closest **layout**, never from a blank page. Gallery:
38
64
  https://zx.zeyos.com/layouts (`layouts.html#<id>` opens one); source
@@ -43,9 +69,9 @@ requires an injected compatible client and never imports the client package.
43
69
  - Templates (complete applications on one shell): `mail`, `issue-tracker`, `wiki`, `ai-chat`,
44
70
  `agent-workspace`, `invoice-editor`, `item-inventory`, `workflows`, `infrastructure`, `crm`.
45
71
  Patterns (single screens): `master-detail`, `record-collection` (any list of records),
46
- `dashboard`, `inbox`, `record-page`, `agent-chat`, `record-wizard`, `checkout-wizard`,
47
- `settings-workspace`, `system-states` (every empty, loading, error, and confirmation state),
48
- `zeyos-invoices`.
72
+ `dashboard`, `inbox`, `record-page`, `agent-chat`, `agent-canvas` (answers as surfaces),
73
+ `record-wizard`, `checkout-wizard`, `settings-workspace`, `system-states` (every empty,
74
+ loading, error, and confirmation state), `zeyos-invoices`.
49
75
  - The agent reference's **"Choosing what to build with"** section maps each screen to its layout
50
76
  and each job to its component, lists the theming decisions (theme, accent preset, geometry
51
77
  tokens, material, motion, colour roles), and what never to build by hand. Read it before
@@ -67,13 +93,13 @@ requires an injected compatible client and never imports the client package.
67
93
  `Table` (sortable, selectable, sticky header, opt-in inline cell/row editing, row reorder,
68
94
  column visibility), shared `RecordView` state through `TableView`, `CardView`, and `KanbanView`,
69
95
  `Grid` with single-click editing and `Grid.BillingItems()`, engine-neutral
70
- `Chart` requiring an injected renderer (`ChartJsAdapter` requires host-provided Chart.js 4), `Calendar` (agenda/day/week/month/year, pointer/keyboard
96
+ `Chart` with the built-in `SvgChartAdapter` (bar, line, pie, doughnut; no dependency) or `ChartJsAdapter` (host-provided Chart.js 4), `Calendar` (agenda/day/week/month/year, pointer/keyboard
71
97
  drag and resize, `optimistic: true|false`), backend-neutral nested `Filter`, simple client-side
72
98
  `DataFilter`, `FilterPanel` (typed filter form built from a server's own field metadata;
73
99
  `mode: 'draft'|'live'`, `serialize`), `ListToolbar` (search, live result count, view switch, and
74
100
  tools whose badge is part of the accessible name), `ViewSettings` (view-settings drawer content:
75
101
  reorder, hide, and add fields, grouping, board axes; `bind()` to a record view),
76
- `Pagination` (+ pure `paginationRange()`),
102
+ `Pagination` (+ pure `paginationRange()` and `fitPageSize()`),
77
103
  `SortControl` (searchable field selector with a direction toggle, one atomic `{id,dir}`),
78
104
  `TreeView` (APG tree), `Finder` (Miller columns).
79
105
  - Forms: `Form`, `Fieldset`, `Questionnaire` (guided one-question-at-a-time flow with branching), `Field` (type registry), `CodeEditor` (structured text in a native textarea; never executes or injects the value), `ValueList`, `MultiValueEditor`, `FieldUpload`.
@@ -83,7 +109,8 @@ requires an injected compatible client and never imports the client package.
83
109
  circular `zeyosAppIcon()` application presets and compact `moduleChip()` identities),
84
110
  `Aurora` (one- to four-colour ambient
85
111
  canvas light; shared material roles govern chrome and overlays), `Avatar` (person presence, or an
86
- agent's `activity` with an opt-in shared presence animation), `Panel` (header/footer action
112
+ agent's `activity` with an opt-in shared presence animation), `AgentAvatar` (a generated
113
+ face for an agent without a picture: a coloured geometric shape whose eyes take its `activity`, `material: 'flat'|'soft'`), `Panel` (header/footer action
87
114
  buttons), `MasterPanel`, `Tabbox`
88
115
  (`variant: 'divided'|'bracket'|'line'|'segmented'`), `NavigationBar`, `AppSidebar` (expanded and
89
116
  minimized vertical states plus horizontal rail layouts; sections; a modules layout), `ModuleBar`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zeyos/zx",
3
- "version": "5.7.0",
3
+ "version": "5.8.0",
4
4
  "description": "Dependency-free JavaScript implementation of the Xenon Design System.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -50,10 +50,15 @@
50
50
  "./zx.core.css": "./dist/zx.core.css",
51
51
  "./zx.core.min.css": "./dist/zx.core.min.css",
52
52
  "./zx.layered.css": "./dist/zx.layered.css",
53
+ "./zx.layered.min.css": "./dist/zx.layered.min.css",
53
54
  "./src/components/*.js": {
54
55
  "types": "./dist/types/components/*.d.ts",
55
56
  "default": "./src/components/*.js"
56
57
  },
58
+ "./src/core/*.js": {
59
+ "types": "./dist/types/core/*.d.ts",
60
+ "default": "./src/core/*.js"
61
+ },
57
62
  "./locales/*.js": {
58
63
  "types": "./dist/types/locales/*.d.ts",
59
64
  "default": "./src/locales/*.js"
@@ -71,14 +76,13 @@
71
76
  },
72
77
  "files": [
73
78
  "dist",
74
- "dist/types",
75
79
  "bin",
76
80
  "styles",
77
81
  "src",
78
- "!src/compat",
79
- "!src/compat-entry.js",
80
82
  "docs/llms.md",
81
83
  "docs/llms.txt",
84
+ "docs/llms-small.txt",
85
+ "docs/components",
82
86
  "docs/api.json",
83
87
  "docs/agent-surfaces.md",
84
88
  "docs/agent-catalog.json",
@@ -102,6 +106,7 @@
102
106
  "prepublishOnly": "npm test && npm run build",
103
107
  "build:api": "node tools/build-api.js",
104
108
  "build:catalog": "node tools/build-agent-catalog.js",
109
+ "build:agent-docs": "node tools/build-agent-docs.js",
105
110
  "build:types": "tsc --project tsconfig.json",
106
111
  "test:browser": "node tools/run-regressions.js && node tools/run-smoke.js",
107
112
  "test:visual": "node tools/visual-diff.js",
@@ -4,14 +4,23 @@ import { h, restoreTarget, safeHref, snapshotTarget } from '../../core/dom.js';
4
4
  import { icon } from '../../core/icons.js';
5
5
  import { printf } from '../../core/i18n.js';
6
6
  import { isElement, uid } from '../../core/util.js';
7
+ import { AgentAvatar } from '../agent-avatar/agent-avatar.js';
7
8
  import { Avatar } from '../avatar/avatar.js';
9
+ import { agentAvatarOptions, authorFace } from '../../internal/agent-model.js';
8
10
  import { badge } from '../badge/badge.js';
9
11
  import { button } from '../button/button.js';
10
12
  import { dateLocale } from '../../internal/date-locale.js';
11
13
 
12
14
  /** @typedef {string|number|Node|Component|null} ActivityContent */
13
15
  /** @typedef {import('../avatar/avatar.js').AvatarOptions} AvatarOptions */
14
- /** @typedef {AvatarOptions|Element|null} ActivityAvatar */
16
+ /**
17
+ * An avatar descriptor. With `face` (`{seed, tone, body, eyes, material}`, or `true` to derive
18
+ * everything from the name) the actor is an agent and is drawn as its AgentAvatar — `name`,
19
+ * `label`, `size`, `tone`, `activity`, `activityLabel`, `animate` and `phase` carry over, the
20
+ * picture and initials options do not.
21
+ * @typedef {AvatarOptions & {face?: import('../../internal/agent-model.js').AuthorFace|true}} ActivityAvatarDescriptor
22
+ */
23
+ /** @typedef {ActivityAvatarDescriptor|Element|null} ActivityAvatar */
15
24
 
16
25
  /**
17
26
  * @typedef {Object} ActivityAction
@@ -258,9 +267,19 @@ export class ActivityItem extends Component {
258
267
  if (!value || typeof value !== 'object' || Array.isArray(value)) {
259
268
  throw new TypeError('ActivityItem avatar must be an Element, descriptor, or null');
260
269
  }
270
+ const name = value.name || textAlternative(actor);
271
+ const face = authorFace({ kind: 'agent', face: value.face });
272
+ if (face) {
273
+ this._avatarComponent = new AgentAvatar(null, agentAvatarOptions(face, {
274
+ name, label: value.label ?? null, size: value.size ?? 'md',
275
+ activity: value.activity ?? null, activityLabel: value.activityLabel ?? null,
276
+ animate: Boolean(value.animate), phase: value.phase ?? null
277
+ }, { fallback: { tone: value.tone ?? null } }));
278
+ return this._avatarComponent.toElement();
279
+ }
261
280
  const settings = {
262
281
  ...value,
263
- name: value.name || textAlternative(actor),
282
+ name,
264
283
  label: value.label ?? null,
265
284
  size: value.size ?? 'md'
266
285
  };
@@ -0,0 +1,195 @@
1
+ /*
2
+ * AgentAvatar — a generated face. The component writes `data-tone`, `data-size` and `data-activity`;
3
+ * the face is an SVG in a 64-unit view box whose parts carry `zx-agent-avatar__*` classes: a
4
+ * free-standing silhouette in the tone's solid fill with white eyes and dark pupils. The presets are
5
+ * the Avatar's: 24 / 32 / 40px at the default spacing unit.
6
+ */
7
+ .zx-agent-avatar {
8
+ --zx-agent-avatar-size: var(--zx-space-7);
9
+ /* The activity dot and where its notch is cut: the inline end, mirrored in right-to-left. */
10
+ --zx-agent-avatar-dot: max(8px, calc(var(--zx-agent-avatar-size) * .3));
11
+ --zx-agent-avatar-dot-x: calc(100% - var(--zx-agent-avatar-dot) / 2);
12
+ position: relative;
13
+ display: inline-grid;
14
+ flex: none;
15
+ place-items: center;
16
+ inline-size: var(--zx-agent-avatar-size);
17
+ block-size: var(--zx-agent-avatar-size);
18
+ vertical-align: middle;
19
+ }
20
+
21
+ .zx-agent-avatar[data-size="sm"] { --zx-agent-avatar-size: var(--zx-space-6); }
22
+ .zx-agent-avatar[data-size="lg"] { --zx-agent-avatar-size: var(--zx-space-8); }
23
+ .zx-agent-avatar:dir(rtl) { --zx-agent-avatar-dot-x: calc(var(--zx-agent-avatar-dot) / 2); }
24
+
25
+ .zx-agent-avatar[data-tone="blue"] { --zx-agent-avatar-solid: var(--zx-color-tone-blue-solid); }
26
+ .zx-agent-avatar[data-tone="teal"] { --zx-agent-avatar-solid: var(--zx-color-tone-teal-solid); }
27
+ .zx-agent-avatar[data-tone="green"] { --zx-agent-avatar-solid: var(--zx-color-tone-green-solid); }
28
+ .zx-agent-avatar[data-tone="amber"] { --zx-agent-avatar-solid: var(--zx-color-tone-amber-solid); }
29
+ .zx-agent-avatar[data-tone="orange"] { --zx-agent-avatar-solid: var(--zx-color-tone-orange-solid); }
30
+ .zx-agent-avatar[data-tone="red"] { --zx-agent-avatar-solid: var(--zx-color-tone-red-solid); }
31
+ .zx-agent-avatar[data-tone="pink"] { --zx-agent-avatar-solid: var(--zx-color-tone-pink-solid); }
32
+ .zx-agent-avatar[data-tone="violet"] { --zx-agent-avatar-solid: var(--zx-color-tone-violet-solid); }
33
+ .zx-agent-avatar[data-tone="slate"] { --zx-agent-avatar-solid: var(--zx-color-tone-slate-solid); }
34
+
35
+ .zx-agent-avatar__face {
36
+ display: block;
37
+ inline-size: 100%;
38
+ block-size: 100%;
39
+ overflow: visible;
40
+ }
41
+
42
+ .zx-agent-avatar__body {
43
+ fill: var(--zx-agent-avatar-solid);
44
+ stroke: var(--zx-agent-avatar-solid);
45
+ }
46
+
47
+ /*
48
+ * The soft material: the component writes `data-material="soft"`, a linear gradient into the face,
49
+ * and `--zx-agent-avatar-paint` (that gradient, falling back to the solid fill). The stops are mixed
50
+ * here from the tone and the two eye inks, so a theme change recolours them without a redraw.
51
+ */
52
+ .zx-agent-avatar[data-material="soft"] .zx-agent-avatar__body {
53
+ fill: var(--zx-agent-avatar-paint, var(--zx-agent-avatar-solid));
54
+ stroke: var(--zx-agent-avatar-paint, var(--zx-agent-avatar-solid));
55
+ }
56
+
57
+ .zx-agent-avatar__stop-lit { stop-color: color-mix(in srgb, var(--zx-agent-avatar-solid) 90%, var(--zx-color-agent-eye)); }
58
+ .zx-agent-avatar__stop-base { stop-color: var(--zx-agent-avatar-solid); }
59
+ .zx-agent-avatar__stop-shade { stop-color: color-mix(in srgb, var(--zx-agent-avatar-solid) 86%, var(--zx-color-agent-pupil)); }
60
+
61
+ @media print {
62
+ .zx-agent-avatar[data-material="soft"] .zx-agent-avatar__body {
63
+ fill: var(--zx-agent-avatar-solid);
64
+ stroke: var(--zx-agent-avatar-solid);
65
+ }
66
+ }
67
+
68
+ .zx-agent-avatar__sclera { fill: var(--zx-color-agent-eye); }
69
+ .zx-agent-avatar__pupil { fill: var(--zx-color-agent-pupil); }
70
+
71
+ .zx-agent-avatar__line {
72
+ fill: none;
73
+ stroke: var(--zx-color-agent-eye);
74
+ stroke-linecap: round;
75
+ stroke-linejoin: round;
76
+ }
77
+
78
+ /* Offline is closed eyes on a faded, colourless face; the dot keeps its own colour. */
79
+ .zx-agent-avatar[data-activity="offline"] > .zx-agent-avatar__face {
80
+ filter: grayscale(1);
81
+ opacity: .55;
82
+ }
83
+
84
+ /*
85
+ * The Avatar activity dot: shape and tone per activity. It is notched out of the face with a mask
86
+ * rather than ringed in a surface colour, so it reads on any background — glass navigation, hover
87
+ * and current rows, an Aurora — and a hollow dot shows that background through it.
88
+ */
89
+ .zx-agent-avatar__activity {
90
+ position: absolute;
91
+ inset-inline-end: 0;
92
+ inset-block-end: 0;
93
+ box-sizing: border-box;
94
+ inline-size: var(--zx-agent-avatar-dot);
95
+ block-size: var(--zx-agent-avatar-dot);
96
+ border-radius: 50%;
97
+ background: var(--zx-color-text-muted);
98
+ }
99
+
100
+ .zx-agent-avatar__activity[hidden] { display: none; }
101
+
102
+ .zx-agent-avatar:has(> .zx-agent-avatar__activity:not([hidden])) > .zx-agent-avatar__face {
103
+ --zx-agent-avatar-notch: calc(var(--zx-agent-avatar-dot) * .6 + 2px);
104
+ mask-image: radial-gradient(circle at var(--zx-agent-avatar-dot-x) calc(100% - var(--zx-agent-avatar-dot) / 2),
105
+ transparent var(--zx-agent-avatar-notch), var(--zx-color-agent-pupil) calc(var(--zx-agent-avatar-notch) + .5px));
106
+ }
107
+
108
+ .zx-agent-avatar[data-activity="working"] > .zx-agent-avatar__activity { background: var(--zx-color-success); }
109
+ .zx-agent-avatar[data-activity="thinking"] > .zx-agent-avatar__activity { background: var(--zx-color-info); }
110
+ .zx-agent-avatar[data-activity="needs-you"] > .zx-agent-avatar__activity { background: var(--zx-color-warning); }
111
+
112
+ .zx-agent-avatar[data-activity="blocked"] > .zx-agent-avatar__activity {
113
+ border-radius: 15%;
114
+ background: var(--zx-color-danger);
115
+ }
116
+
117
+ .zx-agent-avatar[data-activity="idle"] > .zx-agent-avatar__activity {
118
+ border: 1.5px solid var(--zx-color-text-muted);
119
+ background: transparent;
120
+ }
121
+
122
+ .zx-agent-avatar[data-activity="offline"] > .zx-agent-avatar__activity {
123
+ border: 1.5px dashed var(--zx-color-text-subtle);
124
+ background: transparent;
125
+ }
126
+
127
+ /*
128
+ * Motion. The root moves in the shared presence loop, which writes only its `transform`; the eyes
129
+ * blink, drift and scan here. Everything stops inside a `data-zx-motion="reduced"` region through
130
+ * styles/base.css, and none of it runs without the motion preference.
131
+ */
132
+ .zx-agent-avatar[data-animate] {
133
+ transform-origin: 50% 75%;
134
+ }
135
+
136
+ .zx-agent-avatar :is(.zx-agent-avatar__eye, .zx-agent-avatar__look, .zx-agent-avatar__gaze) {
137
+ transform-box: fill-box;
138
+ transform-origin: center;
139
+ }
140
+
141
+ @media (prefers-reduced-motion: no-preference) {
142
+ .zx-agent-avatar[data-animate] {
143
+ will-change: transform;
144
+ }
145
+
146
+ .zx-agent-avatar[data-animate]:is([data-activity="idle"], [data-activity="thinking"], [data-activity="working"]) .zx-agent-avatar__eye {
147
+ animation: zx-agent-avatar-blink 5.2s var(--zx-agent-avatar-delay, 0s) infinite;
148
+ }
149
+
150
+ .zx-agent-avatar[data-animate][data-activity="needs-you"] .zx-agent-avatar__eye {
151
+ animation: zx-agent-avatar-double-blink 3.6s var(--zx-agent-avatar-delay, 0s) infinite;
152
+ }
153
+
154
+ .zx-agent-avatar[data-animate][data-activity="thinking"] .zx-agent-avatar__gaze {
155
+ animation: zx-agent-avatar-ponder 3.4s ease-in-out var(--zx-agent-avatar-delay, 0s) infinite;
156
+ }
157
+
158
+ .zx-agent-avatar[data-animate][data-activity="working"] .zx-agent-avatar__gaze {
159
+ animation: zx-agent-avatar-scan 2.2s ease-in-out var(--zx-agent-avatar-delay, 0s) infinite;
160
+ }
161
+ }
162
+
163
+ @keyframes zx-agent-avatar-blink {
164
+ 0%, 93%, 100% { transform: scaleY(1); }
165
+ 95.5% { transform: scaleY(.08); }
166
+ }
167
+
168
+ @keyframes zx-agent-avatar-double-blink {
169
+ 0%, 80%, 86%, 92%, 100% { transform: scaleY(1); }
170
+ 83%, 89% { transform: scaleY(.1); }
171
+ }
172
+
173
+ @keyframes zx-agent-avatar-ponder {
174
+ 0%, 100% { transform: translateX(-1.5px); }
175
+ 50% { transform: translateX(1.5px); }
176
+ }
177
+
178
+ @keyframes zx-agent-avatar-scan {
179
+ 0%, 100% { transform: translateX(-2px); }
180
+ 50% { transform: translateX(2px); }
181
+ }
182
+
183
+ /* Forced colours: the body in the text colour, eyes cut out of it in the canvas colour. */
184
+ @media (forced-colors: active) {
185
+ .zx-agent-avatar__body,
186
+ .zx-agent-avatar[data-material] .zx-agent-avatar__body { fill: CanvasText; stroke: CanvasText; }
187
+ .zx-agent-avatar__sclera { fill: Canvas; }
188
+ .zx-agent-avatar__line { stroke: Canvas; }
189
+ .zx-agent-avatar__pupil { fill: CanvasText; }
190
+ .zx-agent-avatar[data-activity] > .zx-agent-avatar__activity { background: CanvasText; }
191
+ .zx-agent-avatar:is([data-activity="idle"], [data-activity="offline"]) > .zx-agent-avatar__activity {
192
+ border-color: CanvasText;
193
+ background: Canvas;
194
+ }
195
+ }