@zeyos/zx 5.7.1 → 5.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (326) hide show
  1. package/CHANGELOG.md +296 -0
  2. package/README.md +47 -9
  3. package/dist/types/components/activity-item/activity-item.d.ts +14 -3
  4. package/dist/types/components/agent-avatar/agent-avatar.d.ts +165 -0
  5. package/dist/types/components/agent-avatar/agent-face.d.ts +93 -0
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +21 -9
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +26 -0
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +3 -1
  9. package/dist/types/components/approval-card/approval-card.d.ts +31 -2
  10. package/dist/types/components/aurora/aurora.d.ts +31 -5
  11. package/dist/types/components/calendar/calendar.d.ts +39 -26
  12. package/dist/types/components/chart/chart.d.ts +250 -20
  13. package/dist/types/components/chart/color.d.ts +66 -0
  14. package/dist/types/components/chart/svg-adapter.d.ts +103 -0
  15. package/dist/types/components/chart/svg-geometry.d.ts +203 -0
  16. package/dist/types/components/check-button/check-button.d.ts +1 -4
  17. package/dist/types/components/checklist/checklist.d.ts +19 -5
  18. package/dist/types/components/code-editor/code-editor.d.ts +55 -1
  19. package/dist/types/components/composer/composer.d.ts +41 -6
  20. package/dist/types/components/context-menu/context-menu.d.ts +36 -8
  21. package/dist/types/components/copy/copy-button.d.ts +6 -0
  22. package/dist/types/components/copy/copy-input.d.ts +1 -0
  23. package/dist/types/components/date-picker/date-picker.d.ts +14 -0
  24. package/dist/types/components/date-picker/time-picker.d.ts +26 -17
  25. package/dist/types/components/datebox/datebox.d.ts +8 -4
  26. package/dist/types/components/dialog/dialog.d.ts +13 -2
  27. package/dist/types/components/empty-state/empty-state.d.ts +10 -1
  28. package/dist/types/components/field/field.d.ts +4 -2
  29. package/dist/types/components/form/form.d.ts +2 -1
  30. package/dist/types/components/kanban-view/kanban-card.d.ts +7 -0
  31. package/dist/types/components/kanban-view/kanban-view.d.ts +15 -3
  32. package/dist/types/components/launcher/launcher.d.ts +26 -0
  33. package/dist/types/components/master-panel/master-panel.d.ts +9 -4
  34. package/dist/types/components/menu-button/menu-button.d.ts +29 -5
  35. package/dist/types/components/message/message.d.ts +308 -5
  36. package/dist/types/components/modal/modal.d.ts +11 -0
  37. package/dist/types/components/modal/native-dialog.d.ts +40 -0
  38. package/dist/types/components/module-bar/module-bar.d.ts +9 -2
  39. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +5 -4
  40. package/dist/types/components/number-field/number-field.d.ts +7 -0
  41. package/dist/types/components/pagination/pagination.d.ts +341 -19
  42. package/dist/types/components/run-status/run-status.d.ts +26 -0
  43. package/dist/types/components/run-trace/run-trace.d.ts +10 -6
  44. package/dist/types/components/search/search.d.ts +16 -4
  45. package/dist/types/components/select/select.d.ts +19 -1
  46. package/dist/types/components/sheet/sheet.d.ts +18 -4
  47. package/dist/types/components/slider/slider.d.ts +2 -1
  48. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -3
  49. package/dist/types/components/stepper/stepper.d.ts +17 -4
  50. package/dist/types/components/surface/catalog.d.ts +61 -17
  51. package/dist/types/components/surface/surface.d.ts +6 -4
  52. package/dist/types/components/table/table.d.ts +207 -5
  53. package/dist/types/components/table/window.d.ts +25 -1
  54. package/dist/types/components/toggle/toggle.d.ts +38 -6
  55. package/dist/types/components/tooltip/tooltip.d.ts +5 -4
  56. package/dist/types/components/tree/tree.d.ts +43 -6
  57. package/dist/types/components/truncate/truncate.d.ts +4 -2
  58. package/dist/types/components/value-list/value-list.d.ts +9 -2
  59. package/dist/types/core/date.d.ts +2 -1
  60. package/dist/types/core/drag-axis.d.ts +10 -5
  61. package/dist/types/core/export.d.ts +2 -2
  62. package/dist/types/core/format.d.ts +3 -1
  63. package/dist/types/core/icons.d.ts +36 -3
  64. package/dist/types/core/keyboard.d.ts +7 -3
  65. package/dist/types/core/messages.d.ts +3 -0
  66. package/dist/types/core/storage.d.ts +4 -3
  67. package/dist/types/core/util.d.ts +3 -1
  68. package/dist/types/elements/define.d.ts +5 -2
  69. package/dist/types/index.d.ts +6 -4
  70. package/dist/types/internal/agent-model.d.ts +99 -0
  71. package/dist/types/internal/app-rail.d.ts +37 -2
  72. package/dist/types/internal/collections.d.ts +18 -0
  73. package/dist/types/internal/menu-items.d.ts +27 -0
  74. package/dist/types/internal/overlay-content.d.ts +23 -0
  75. package/dist/types/internal/presence-loop.d.ts +5 -2
  76. package/dist/types/locales/index.d.ts +3 -0
  77. package/dist/types/zeyos/calendar.d.ts +43 -7
  78. package/dist/types/zeyos/connect.d.ts +4 -0
  79. package/dist/types/zeyos/form.d.ts +13 -5
  80. package/dist/types/zeyos/select.d.ts +5 -2
  81. package/dist/types/zeyos/table.d.ts +16 -8
  82. package/dist/types/zeyos/view.d.ts +2 -1
  83. package/dist/zx-zeyos.esm.js +2998 -451
  84. package/dist/zx-zeyos.esm.min.js +4 -4
  85. package/dist/zx.core.css +4 -0
  86. package/dist/zx.core.min.css +1 -1
  87. package/dist/zx.css +948 -48
  88. package/dist/zx.esm.js +7432 -3408
  89. package/dist/zx.esm.min.js +26 -26
  90. package/dist/zx.global.js +7432 -3408
  91. package/dist/zx.global.min.js +26 -26
  92. package/dist/zx.layered.css +950 -48
  93. package/dist/zx.layered.min.css +1 -1
  94. package/dist/zx.min.css +1 -1
  95. package/docs/agent-catalog.json +159 -1
  96. package/docs/agent-surfaces.md +21 -21
  97. package/docs/api.json +3122 -528
  98. package/docs/components/account-menu.md +24 -0
  99. package/docs/components/activity-item.md +23 -0
  100. package/docs/components/activity-list.md +28 -0
  101. package/docs/components/agent-avatar.md +59 -0
  102. package/docs/components/agent-thread.md +275 -0
  103. package/docs/components/app-icon.md +36 -0
  104. package/docs/components/app-sidebar.md +92 -0
  105. package/docs/components/approval-card.md +71 -0
  106. package/docs/components/aurora.md +34 -0
  107. package/docs/components/avatar.md +37 -0
  108. package/docs/components/badge.md +36 -0
  109. package/docs/components/block-view.md +34 -0
  110. package/docs/components/breadcrumb.md +20 -0
  111. package/docs/components/button.md +23 -0
  112. package/docs/components/calendar.md +68 -0
  113. package/docs/components/card-view.md +73 -0
  114. package/docs/components/card.md +25 -0
  115. package/docs/components/chart.md +109 -0
  116. package/docs/components/check-button.md +16 -0
  117. package/docs/components/checklist.md +19 -0
  118. package/docs/components/code-editor.md +38 -0
  119. package/docs/components/composer.md +107 -0
  120. package/docs/components/context-menu.md +32 -0
  121. package/docs/components/copy.md +37 -0
  122. package/docs/components/data-filter.md +16 -0
  123. package/docs/components/date-picker.md +31 -0
  124. package/docs/components/date-range.md +21 -0
  125. package/docs/components/datebox.md +31 -0
  126. package/docs/components/dialog.md +25 -0
  127. package/docs/components/dock.md +57 -0
  128. package/docs/components/dropdown.md +39 -0
  129. package/docs/components/elements.md +63 -0
  130. package/docs/components/empty-state.md +17 -0
  131. package/docs/components/entity-ref.md +26 -0
  132. package/docs/components/field-upload.md +18 -0
  133. package/docs/components/file-item.md +27 -0
  134. package/docs/components/file-list.md +23 -0
  135. package/docs/components/filter-panel.md +45 -0
  136. package/docs/components/filter.md +47 -0
  137. package/docs/components/finder.md +25 -0
  138. package/docs/components/form-widgets.md +42 -0
  139. package/docs/components/form.md +80 -0
  140. package/docs/components/grid.md +26 -0
  141. package/docs/components/groupbox.md +11 -0
  142. package/docs/components/helpers.md +359 -0
  143. package/docs/components/icons.md +87 -0
  144. package/docs/components/index.md +99 -0
  145. package/docs/components/kanban-view.md +42 -0
  146. package/docs/components/kbd.md +23 -0
  147. package/docs/components/kernel.md +41 -0
  148. package/docs/components/launcher.md +66 -0
  149. package/docs/components/layout.md +33 -0
  150. package/docs/components/list-toolbar.md +38 -0
  151. package/docs/components/loading.md +48 -0
  152. package/docs/components/menu-button.md +47 -0
  153. package/docs/components/message.md +76 -0
  154. package/docs/components/modal.md +27 -0
  155. package/docs/components/module-bar.md +71 -0
  156. package/docs/components/multi-value-editor.md +16 -0
  157. package/docs/components/navigation-bar.md +22 -0
  158. package/docs/components/number-field.md +34 -0
  159. package/docs/components/pagination.md +73 -0
  160. package/docs/components/panel.md +28 -0
  161. package/docs/components/prompt-starters.md +40 -0
  162. package/docs/components/prose.md +38 -0
  163. package/docs/components/questionnaire.md +115 -0
  164. package/docs/components/rating.md +19 -0
  165. package/docs/components/run-status.md +50 -0
  166. package/docs/components/run-trace.md +72 -0
  167. package/docs/components/search.md +11 -0
  168. package/docs/components/select.md +129 -0
  169. package/docs/components/sheet-stack.md +39 -0
  170. package/docs/components/sheet.md +77 -0
  171. package/docs/components/skeleton.md +27 -0
  172. package/docs/components/slider.md +29 -0
  173. package/docs/components/sort-control.md +21 -0
  174. package/docs/components/source-list.md +30 -0
  175. package/docs/components/split-view.md +12 -0
  176. package/docs/components/stat-tile.md +49 -0
  177. package/docs/components/stepper.md +27 -0
  178. package/docs/components/surface.md +152 -0
  179. package/docs/components/tabbox.md +33 -0
  180. package/docs/components/table-view.md +43 -0
  181. package/docs/components/table.md +232 -0
  182. package/docs/components/tag-picker.md +39 -0
  183. package/docs/components/timebox.md +16 -0
  184. package/docs/components/toggle.md +21 -0
  185. package/docs/components/tokens.md +82 -0
  186. package/docs/components/toolbar.md +26 -0
  187. package/docs/components/tooltip.md +16 -0
  188. package/docs/components/tree.md +48 -0
  189. package/docs/components/truncate.md +21 -0
  190. package/docs/components/value-list.md +14 -0
  191. package/docs/components/view-settings.md +56 -0
  192. package/docs/components/workspace-switcher.md +42 -0
  193. package/docs/components/zeyos.md +196 -0
  194. package/docs/llms-small.txt +299 -0
  195. package/docs/llms.md +697 -100
  196. package/docs/llms.txt +46 -19
  197. package/package.json +9 -4
  198. package/src/components/activity-item/activity-item.js +21 -2
  199. package/src/components/agent-avatar/agent-avatar.css +195 -0
  200. package/src/components/agent-avatar/agent-avatar.js +333 -0
  201. package/src/components/agent-avatar/agent-face.js +292 -0
  202. package/src/components/agent-thread/ag-ui.js +44 -11
  203. package/src/components/agent-thread/agent-thread.js +103 -11
  204. package/src/components/agent-thread/ui-message-stream.js +3 -1
  205. package/src/components/app-rail/app-rail.css +5 -0
  206. package/src/components/app-sidebar/app-sidebar.css +3 -0
  207. package/src/components/app-sidebar/app-sidebar.js +4 -3
  208. package/src/components/approval-card/approval-card.css +6 -0
  209. package/src/components/approval-card/approval-card.js +55 -7
  210. package/src/components/aurora/aurora.css +149 -14
  211. package/src/components/aurora/aurora.js +49 -6
  212. package/src/components/calendar/calendar.css +6 -2
  213. package/src/components/calendar/calendar.js +127 -47
  214. package/src/components/card-view/card-view.js +5 -6
  215. package/src/components/chart/chart.css +159 -1
  216. package/src/components/chart/chart.js +450 -62
  217. package/src/components/chart/color.js +297 -0
  218. package/src/components/chart/svg-adapter.js +576 -0
  219. package/src/components/chart/svg-geometry.js +323 -0
  220. package/src/components/check-button/check-button.js +3 -18
  221. package/src/components/checklist/checklist.js +46 -17
  222. package/src/components/checklist/field-adapter.js +4 -1
  223. package/src/components/code-editor/code-editor.css +33 -0
  224. package/src/components/code-editor/code-editor.js +97 -8
  225. package/src/components/code-editor/field-adapter.js +3 -0
  226. package/src/components/composer/composer.css +3 -0
  227. package/src/components/composer/composer.js +100 -22
  228. package/src/components/context-menu/context-menu.js +41 -5
  229. package/src/components/copy/copy-button.js +9 -1
  230. package/src/components/copy/copy-input.js +5 -0
  231. package/src/components/data-filter/filter-core.js +0 -1
  232. package/src/components/date-picker/date-picker.css +8 -0
  233. package/src/components/date-picker/date-picker.js +47 -8
  234. package/src/components/date-picker/date-range-picker.js +1 -1
  235. package/src/components/date-picker/month-picker.js +19 -3
  236. package/src/components/date-picker/time-picker.js +54 -19
  237. package/src/components/datebox/date-range-box.js +7 -3
  238. package/src/components/datebox/datebox.js +32 -6
  239. package/src/components/dialog/dialog.css +6 -0
  240. package/src/components/dialog/dialog.js +22 -30
  241. package/src/components/dropdown/dropdown.js +1 -18
  242. package/src/components/empty-state/empty-state.js +21 -2
  243. package/src/components/field/field.js +19 -3
  244. package/src/components/fieldset/fieldset.js +3 -1
  245. package/src/components/filter/filter.js +9 -0
  246. package/src/components/form/form.js +19 -2
  247. package/src/components/kanban-view/kanban-card.js +15 -2
  248. package/src/components/kanban-view/kanban-view.css +21 -0
  249. package/src/components/kanban-view/kanban-view.js +29 -16
  250. package/src/components/launcher/launcher.css +14 -0
  251. package/src/components/launcher/launcher.js +54 -9
  252. package/src/components/master-panel/master-panel.js +24 -22
  253. package/src/components/menu-button/menu-button.js +26 -4
  254. package/src/components/message/message.css +228 -29
  255. package/src/components/message/message.js +664 -30
  256. package/src/components/modal/modal.js +70 -25
  257. package/src/components/modal/native-dialog.js +91 -0
  258. package/src/components/module-bar/module-bar.css +3 -0
  259. package/src/components/module-bar/module-bar.js +17 -4
  260. package/src/components/multi-value-editor/multi-value-editor.css +7 -2
  261. package/src/components/multi-value-editor/multi-value-editor.js +3 -2
  262. package/src/components/navigation-bar/navigation-bar.js +13 -1
  263. package/src/components/number-field/field-adapter.js +3 -0
  264. package/src/components/number-field/number-field.js +2 -1
  265. package/src/components/pagination/pagination.css +26 -2
  266. package/src/components/pagination/pagination.js +551 -65
  267. package/src/components/prose/prose.js +7 -1
  268. package/src/components/rating/field-adapter.js +3 -0
  269. package/src/components/run-status/run-status.js +43 -3
  270. package/src/components/run-trace/run-trace.js +15 -7
  271. package/src/components/search/search.js +3 -18
  272. package/src/components/select/field-adapter.js +8 -1
  273. package/src/components/select/select.js +68 -13
  274. package/src/components/sheet/sheet.js +27 -8
  275. package/src/components/slider/field-adapter.js +3 -0
  276. package/src/components/slider/slider.js +4 -6
  277. package/src/components/stat-tile/stat-tile.js +24 -9
  278. package/src/components/stepper/stepper.css +15 -0
  279. package/src/components/stepper/stepper.js +34 -2
  280. package/src/components/surface/catalog.js +185 -28
  281. package/src/components/surface/surface.js +10 -5
  282. package/src/components/tabbox/tabbox.js +13 -1
  283. package/src/components/table/table.css +160 -2
  284. package/src/components/table/table.js +479 -52
  285. package/src/components/table/window.js +46 -4
  286. package/src/components/table-view/table-view.js +1 -10
  287. package/src/components/tag-picker/field-adapter.js +3 -0
  288. package/src/components/tag-picker/tag-picker.js +2 -0
  289. package/src/components/timebox/field-adapter.js +3 -0
  290. package/src/components/toggle/toggle.js +51 -27
  291. package/src/components/tooltip/tooltip.js +21 -14
  292. package/src/components/tree/tree.js +87 -14
  293. package/src/components/truncate/truncate.js +21 -5
  294. package/src/components/value-list/value-list.js +37 -9
  295. package/src/components/view-settings/view-settings.js +1 -5
  296. package/src/core/component.js +34 -2
  297. package/src/core/date.js +5 -4
  298. package/src/core/drag-axis.js +24 -7
  299. package/src/core/export.js +4 -4
  300. package/src/core/fontawesome.js +34 -3
  301. package/src/core/format.js +3 -1
  302. package/src/core/http.js +23 -11
  303. package/src/core/icons.js +51 -10
  304. package/src/core/keyboard.js +83 -9
  305. package/src/core/messages.js +3 -0
  306. package/src/core/position.js +2 -2
  307. package/src/core/storage.js +80 -31
  308. package/src/core/util.js +16 -5
  309. package/src/elements/define.js +82 -47
  310. package/src/elements/kit.js +46 -35
  311. package/src/index.js +8 -4
  312. package/src/internal/agent-model.js +152 -0
  313. package/src/internal/app-rail.js +53 -2
  314. package/src/internal/collections.js +25 -0
  315. package/src/internal/menu-items.js +59 -0
  316. package/src/internal/overlay-content.js +35 -0
  317. package/src/internal/presence-loop.js +61 -14
  318. package/src/locales/de.js +3 -0
  319. package/src/zeyos/calendar.js +81 -19
  320. package/src/zeyos/connect.js +5 -1
  321. package/src/zeyos/form.js +29 -10
  322. package/src/zeyos/select.js +36 -12
  323. package/src/zeyos/table.js +43 -11
  324. package/src/zeyos/view.js +2 -1
  325. package/styles/tokens/semantic.css +7 -1
  326. package/styles/zx.css +1 -0
package/CHANGELOG.md CHANGED
@@ -8,6 +8,302 @@ and friends remain the complete record.
8
8
 
9
9
  ## Unreleased
10
10
 
11
+ ## 5.8.0 — 2026-11-17
12
+
13
+ Pinned columns and header groups in Table, placements, stacks and highlights for messages, a Chart
14
+ that mounts when it can be measured and follows the theme, a built-in SVG chart renderer that
15
+ agent surfaces draw with by default, overlays and windowed tables that run in a DOM without a top
16
+ layer, a package entry a bundler can prune, a guide to using the class API from a framework, and
17
+ a broad round of fixes: focus traps, nested overlays, field labels, pickers, custom elements, the
18
+ ZeyOS binding's request races, and type declarations that check in a consumer's project.
19
+
20
+ ### Added
21
+
22
+ - **AgentAvatar.** A generated face for an agent without a picture, deterministic from its seed
23
+ (an id, so a rename keeps the face): one of fourteen coloured geometric silhouettes with white
24
+ eyes and dark pupils. The eyes take the agent's `activity` — thinking, working, needs you,
25
+ blocked, offline — beside the Avatar activity dot, and `animate` adds the shared presence motion
26
+ plus blinking. `material: 'soft'` adds a quiet tonal ramp from 28px up. `agentTraits()` and
27
+ `agentFace()` expose the generator as pure data. New tokens `--zx-color-agent-eye` and
28
+ `--zx-color-agent-pupil`.
29
+ - **Agents in navigation and threads.** AppSidebar and ModuleBar items take `agent` (AgentAvatar
30
+ options) and draw the agent's face in place of the icon or tile, with its activity in the
31
+ control's accessible name, and so do Composer mention items and Launcher items. AgentThread and RunTrace authors and
32
+ ActivityItem avatar descriptors take `face`. The Agent workspace layout draws its
33
+ agents with AgentAvatar.
34
+ - **Agents in place of icons.** `emptyState()`, ApprovalCard and RunStatus take `agent` and draw
35
+ the agent's face where they drew an icon — ApprovalCard's looks up at you while the request waits,
36
+ RunStatus's takes the run's expression — and KanbanView assignee descriptors take `face`.
37
+ - **Pagination: Auto page size.** `pageSize: 'auto'`, and `'auto'` among `pageSizes` ("Auto (14)"
38
+ in the select), fits the page to `viewport` — the rows that fit below its sticky header — and
39
+ refits when the viewport or its rows change size, keeping the page's first row. `rowHeight`,
40
+ `perRow`, `reserve`, `minPageSize` and `maxPageSize` cover content that is not a Zx Table;
41
+ `refit()` measures again. The pure `fitPageSize()` is exported.
42
+ - **Pagination: auto-load.** `autoLoad` loads the next page as the end of the list nears, and
43
+ `showAutoLoad` renders a switch between paging and infinite scroll (`setAutoLoad()`, event
44
+ `autoload`). Auto-load waits while the pager is disabled, so an asynchronous loader never gets
45
+ two requests at once. `change` now carries `reason`, `append`, `auto`, `autoLoad` and `mode`.
46
+ - **Aurora: Mesh, Ribbon and Bloom presets and ambient motion.** `motion: 'drift'|'flow'` (and
47
+ `setMotion()`) moves the field by transform alone, behind the reduced-motion preference;
48
+ `--zx-aurora-duration` sets the pace. Presets now write their gradients into `--zx-aurora-image`.
49
+ - **`SvgChartAdapter`: charts with no dependency.** Draws `bar` (grouped), `line`, `pie` and
50
+ `doughnut` charts as SVG — round ticks, a legend, one ring per dataset in a pie, a `<title>` and
51
+ `select` on every mark — coloured from `--zx-color-chart-1`…`-8` through CSS, in both themes and
52
+ every preset. Its `viewBox` follows the plot, so text keeps its size at any width. The first
53
+ drawing grows in unless motion is reduced; `animation` and `legend` are options of the adapter
54
+ and of `chartOptions`. `SvgChartAdapter.supports(type)` names the four types.
55
+ - **`ChartAdapter.mount(viewport, spec)`.** An adapter may draw an element of its own instead of
56
+ painting the canvas; Chart calls `mount()` when an adapter has it, `create()` otherwise. The
57
+ canvas keeps the chart's accessible name and description either way.
58
+ - **Table and Grid: pinned columns and header groups.** `pin: 'start'|'end'` on a column keeps it
59
+ in view while the table scrolls sideways, following the writing direction; several pinned
60
+ columns stack, and the row handle and selection columns stay with the first `'start'` column.
61
+ `group: 'Label'` on adjacent columns renders one spanning header cell above them, announced
62
+ with every cell beneath it. Both work in plain, hierarchical and windowed tables.
63
+ `--zx-table-pin-bg` sets the base of pinned cells.
64
+ - **`Table#setExpanded(ids, { silent })`** replaces the set of expanded branches in one render,
65
+ for restoring a saved state; `true` expands every branch, `false` collapses them all.
66
+ - **`TableColumn.minWidth`**, the narrowest an `fr` column gets (default `5rem`, `0` lifts it).
67
+ - **Message placement.** `placement` on `Message.show()`, the kind shortcuts and
68
+ `Message.progress()` puts a floating message in one of six positions (`top-start`, `top`,
69
+ `top-end`, `bottom-start`, `bottom`, `bottom-end`); `Message.setPlacement()` and
70
+ `Message.getPlacement()` set and read the default, which stays `top-end`. Each placement has its
71
+ own region, marked `data-placement`, and `--zx-message-offset` sets the distance from the
72
+ viewport edge. At 640px and narrower every placement spans the foot of the viewport.
73
+ - **Chart `fill`** (and `setFill()`) takes the height of the container instead of an aspect ratio,
74
+ and `--zx-chart-min-block-size` sets the minimum viewport height, 220px as before unless set.
75
+ `setAspectRatio()`, `setLabel()`, `setDescription()` and `setSummary()` change what were
76
+ constructor-only options, on the class and on `<zx-chart>`.
77
+ - **Chart theme for adapters.** An adapter's `create()` and `update()` receive `spec.theme` with
78
+ `color`, `borderColor`, `background` (the surface, `--zx-color-bg-surface`) and `palette`, the
79
+ eight `--zx-color-chart-*` colours in order. Every
80
+ colour handed to an adapter is `#rrggbb` or `rgba()`, whatever syntax the tokens are written in.
81
+ - **Chart `summaryFormat(value, context)`** formats a cell of the summary table.
82
+ - **Toggle `hideLabel`** keeps the label as the switch's accessible name without drawing it, and
83
+ `setLabel()` replaces it.
84
+ - **CodeEditor error state.** `setHighlight(message, kind)` and `clearHighlight()` show a
85
+ validation or status message as a Field does, `'danger'` marks the textarea invalid and emits
86
+ `invalid`; `getInput()` returns the textarea.
87
+ - **`iconAliases`**, the frozen table of alias names (`edit` → `pen-to-square`, `settings` →
88
+ `gear`, …), exported beside `icons`.
89
+ - **Granular core imports.** `@zeyos/zx/src/core/*.js` is an export with types, so an application
90
+ importing components one by one takes `setTranslator`, `registerIcons` and `icon` from the same
91
+ module instances those components use.
92
+ - **Frameworks guide** in the documentation: mounting the class API from React and Vue, the double
93
+ mount in development, framework content inside a component, controlled props, Groupbox's
94
+ asynchronous events, Chart engine timing, and unit tests under jsdom.
95
+ - The Options tables of the documentation, and `docs/api.json`, state per option how it is changed
96
+ after construction where the source says so: the setter, or that it takes a rebuild.
97
+ - The reference lists the stylesheet name `zx-css` needs for every Form field type.
98
+ - **Message stacks.** Floating messages, and an inline area with `stack: true`, pile the visible
99
+ messages into one stack: the newest in front, two more peeking out behind it. It opens while
100
+ the pointer is over it or focus is inside it, and a press on it (a tap included) keeps it open
101
+ until a press outside it or Escape; no message times out while it is open. `expanded: true`
102
+ keeps it open. `expand()`, `collapse()`, `isExpanded()` and `setStack()` drive it, `expand` and
103
+ `collapse` report it, and the root carries `data-stack` and `data-state`. Bottom placements, and
104
+ every region on a phone, pile upwards; an open floating stack taller than the screen scrolls.
105
+ Closing a message from the keyboard moves focus on to the next one. `messageStackLayout()` is
106
+ the geometry, exported.
107
+ - **Message `highlight`.** `'border'` (or `true`) draws a message's border in its kind colour;
108
+ `'animated'` sends a light round a faint kind-coloured border, and is the still border under
109
+ reduced motion. Per message, as an inline area's default, and on `Message.progress()`.
110
+
111
+ - **`zeyosCalendar()` `timeZone`.** With the ZeyOS instance's zone, all-day appointments are
112
+ recognised from midnight in that zone and shown on the days they name for a viewer anywhere;
113
+ `zeyosAppointmentToEvent()`, `zeyosAppointmentsToEvents()` and `calendarEventToZeyosPatch()`
114
+ take it as `{timeZone}`, so moving one stores that zone's midnight again.
115
+ - **AgentAvatar `spacing`** (`0`, `1` or `2`), so the traits `getTraits()` returns can be given
116
+ back to keep a face exactly; agent and face descriptors accept it too.
117
+ - **`copyButton({signal})`.** Aborting the signal removes the button's listener and timer, and a
118
+ copy still waiting on the clipboard then reports nothing.
119
+ - `messageStackLayout()` and `chartSummaryModel()` are exported from the package entry, as the
120
+ reference already said.
121
+ - The package exports `@zeyos/zx/zx.layered.min.css`.
122
+
123
+ ### Changed
124
+
125
+ - **Layouts:** the record overviews (CRM, issue tracker, record collection) fit their page to the
126
+ window by default and offer the Auto-load switch; the issue tracker starts with it on. The
127
+ website hero drifts.
128
+ - **Documentation:** the Icons page no longer carries the ZeyOS module gallery; the ZeyOS binding's
129
+ module icons stay documented with the binding.
130
+ - **Surface draws its charts.** `chartAdapter` defaults to a shared `SvgChartAdapter`, so a `chart`
131
+ node draws without Chart.js and offers its data table behind a toggle. `chartAdapter: null`
132
+ restores the data table alone; any other adapter is used as before.
133
+ - **Floating messages stack by default.** A floating region piles its messages into one stack
134
+ instead of listing them one below another. `Message.setStack(false)` restores the list, at once
135
+ and for every region; `Message.getStack()` reads the setting.
136
+ - **A message is a plain card.** The kind-tinted gradient and the kind-coloured border are gone:
137
+ every message has the theme's toast surface and a neutral border, and shows its kind in its
138
+ icon; `highlight` is the way to make one stand out. The opaque fallbacks (no backdrop filter,
139
+ reduced transparency, more contrast) are the neutral raised surface instead of the kind's tint.
140
+ - **An option passed as `undefined` keeps its default**, at the top level and inside `msg`.
141
+ It used to override the default with `undefined`. A wrapper can now forward unset props as they
142
+ are; code that passed `undefined` to switch a default off passes `null` (or `false`) instead.
143
+ - **Chart `ready` may fire after the constructor returns.** The engine is created once the chart
144
+ is in a document and has a size, so a chart built with `null` and appended later is ready then.
145
+ `getInstance()` and `resize()` create it on the spot when called after appending. Code that read
146
+ the engine straight after `new Chart()` listens for `ready` or appends first.
147
+ - **Chart follows the theme by itself.** A change of `data-zx-theme` or `data-zx-preset`, of the
148
+ system colour scheme or contrast preference, and showing a hidden chart again update the engine;
149
+ `refreshTheme()` is only needed for changes none of those cover.
150
+ - **`ChartJsAdapter` colours uncoloured datasets from the theme palette**, one colour per series,
151
+ or per value for pie, doughnut and polar-area charts. They were drawn in Chart.js's own default
152
+ colour. A dataset that sets `backgroundColor` or `borderColor` is left as written.
153
+ - **Chart summary numbers are formatted for the active language** with grouping and at most
154
+ twelve significant digits: `1234567.5` reads "1,234,567.5", and `0.1 + 0.2` reads "0.3" rather
155
+ than "0.30000000000000004". `chartSummaryModel()` returns the same text. Use `summaryFormat` for
156
+ another format.
157
+ - **A click on a control inside a table cell no longer raises `rowclick` or `rowdblclick`**, and
158
+ no longer selects the row in a `single` selection. A control is a button, link, field, label,
159
+ an element with a widget role or in the Tab order, editable content, or anything marked
160
+ `data-zx-table-no-edit`. Handlers that called `stopPropagation()` for this can drop it; a
161
+ handler that relied on the row event for clicks on such an element listens on the element.
162
+ - **`fr` columns have a floor and the table scrolls inline below it.** In a container too narrow
163
+ for its columns a table with `fr` widths used to squeeze them, in a windowed table to almost
164
+ nothing; it now keeps each at `minWidth` (5rem by default) and scrolls sideways. Set
165
+ `minWidth: 0` on a column to let it shrink as before.
166
+ - **`iconNames()` includes the alias names.** The list now agrees with what `icon()` renders, so
167
+ it holds more names than glyphs. An icon gallery filters them out with
168
+ `iconNames().filter((name) => !Object.hasOwn(iconAliases, name))`.
169
+ - **StatTile: an explicit `clickable: false` wins over `onclick`.** The tile stays a `<div>` and
170
+ the handler is not called. It used to become a button whenever a handler was passed.
171
+ - **The `code` Form field labels and marks the editor's textarea**, not its frame: the label's
172
+ `for`, `aria-invalid` and the field message's `aria-describedby` are on the `<textarea>`.
173
+ Selectors or tests that looked for `aria-invalid` on `.zx-code-editor` read it from
174
+ `.zx-code-editor__input`.
175
+ - **Sticky table header cells sit at `z-index: 2`** inside the scroll region (they were at 1), and
176
+ the loading bar at 4, to stay above pinned cells. Content an application positions over the
177
+ header inside the table needs a higher value.
178
+ - The package entry no longer keeps every component in a bundle that imports one of them:
179
+ importing `Slider` and `Toggle` from `@zeyos/zx` bundles to about 276 kB minified with esbuild
180
+ 0.28.1, down from about 880 kB; from their own files it is about 49 kB. What registers on import
181
+ is unchanged.
182
+ - `<zx-chart>` applies `label`, `description`, `summary` and `aspect-ratio` in place instead of
183
+ rebuilding the chart.
184
+
185
+ - **MenuButton and ContextMenu update checkbox and radio items themselves.** Choosing a
186
+ `menuitemcheckbox` toggles it, choosing a `menuitemradio` checks it and unchecks the other radio
187
+ items of its section, and `select` reports the new state as `detail.checked`; preventing
188
+ `select` leaves it as it was. The item objects passed in are not modified. An application that
189
+ re-rendered the menu with `setItems()` keeps working; one that relied on the item staying as it
190
+ was prevents `select`.
191
+ - **Calendar `eventDurationEditable` is one option again.** The defaults declared it twice, so the
192
+ per-event reader's key replaced the global setting and every event without a resize flag of its
193
+ own could be resized, even with `editable: false`. `true`, `false` or null (follow `editable`) is
194
+ the resize policy for such events; a string or function still names the per-event field.
195
+ Read-only calendars no longer offer resizing.
196
+ - **Datebox and DateTimeBox `min` and `max` are whole days**, as in the calendar they open: any
197
+ time on the last day can be chosen, and a date outside the range moves to the boundary day and
198
+ keeps its time.
199
+ - **A Composer re-enabled after the agent finished sends the queued message it owed.** It used to
200
+ wait for another busy cycle, so a message sent directly in the meantime overtook it.
201
+ - **MasterPanel header buttons share one listener.** A button's callback still runs with the
202
+ button as `this`; `event.currentTarget` is now the button area.
203
+
204
+ ### Fixed
205
+
206
+ - A Dialog with `closable: false` and a Sheet with `closeButton: false` no longer show a header ✕
207
+ that could be focused and clicked.
208
+ - Modal, Dialog, Sheet and Launcher open, close and are destroyed without throwing where
209
+ `showModal()` or `showPopover()` is missing, as in jsdom, by falling back to the `open`
210
+ attribute; the fallback has no top layer, inertness or backdrop.
211
+ - A Table with `virtual: true` no longer throws where `ResizeObserver` is missing.
212
+ - A horizontal Stepper that wraps no longer draws a connector from the last step of a row to the
213
+ edge of its container.
214
+ - A Chart no longer hands an engine colours in a syntax its own parser may not read
215
+ (`color(srgb …)`, `oklch()`).
216
+ - `icon()` no longer resolves a name through inherited object properties, so a name such as
217
+ `constructor` is an unknown icon.
218
+ - CodeEditor's Tab capture, its Escape release and `indent: ''` are documented.
219
+ - The reference states that a sticky table header needs a bounded `height`, and how `Chart`'s
220
+ `setData()`, `setLoading()` and `setError()` affect the engine.
221
+
222
+ - **Focus and keyboard.** Focus traps (`focusTrap()`, a Sheet with `modal: 'trap-focus'`) no
223
+ longer let Tab escape past a toolbar or tab list at the end of the container, wrap Shift+Tab
224
+ when the container itself has focus, and leave Tab alone inside a dialog opened from the
225
+ trapping sheet. Arrow keys in toolbars, menus and tab lists skip items inside hidden, inert or
226
+ undisplayed groups. In right-to-left layouts, Tabbox and NavigationBar tabs, and the SplitView,
227
+ Dock and resizable Sheet handles (pointer and arrow keys) move toward the side pressed.
228
+ - **Overlays.** Escape in a Launcher opened from a Dialog closes only the Launcher; with several
229
+ modals open, Escape closes the one opened last, whatever order they were created in. Selecting
230
+ text in a light-dismiss Modal or Sheet and releasing over the backdrop no longer closes it.
231
+ Destroying an open Modal, Dialog or Sheet — or one whose `close()` was just called — emits
232
+ `close` once, with its result, and returns focus to the opener. A
233
+ Tooltip adds and removes only its own id in its anchor's `aria-describedby`. A ContextMenu on an
234
+ element that sets its own theme no longer reopens on a right-click inside the open menu, and
235
+ closing it returns focus. Destroying a Composer closes its "replace your text?" dialog.
236
+ - **Field labels.** A Field's label names the input of number, select, tag picker, slider,
237
+ rating and duration fields — it was set on a wrapper and the component's own name won — and
238
+ clicking it focuses the input; the description and error belong to the input too. Form skips
239
+ disabled fields, and fields inside a disabled fieldset, when it validates; a Form or Fieldset
240
+ gives borrowed fields back in their original order.
241
+ - **Select and TagPicker.** `Select.set()` accepts a whole item that is not in the current list;
242
+ priority, status and permission Selects reset to their initial value; in a searchable Select,
243
+ Home and End move the caret once a query is typed; replacing the items of an open list keeps the
244
+ typed query; Enter that confirms Japanese or Chinese input no longer picks an option (Launcher
245
+ too).
246
+ - **Other inputs.** A Checklist value set before its items load — an empty one too — is kept and
247
+ applied when they arrive. Filter reports one `change`, and one `apply` with `autoApply`, per edit. ValueList chips
248
+ are one Tab stop. CodeEditor no longer announces the line and column after every keystroke. The
249
+ MultiValueEditor handle respects reduced motion. Slider steps such as `1.5e-7` get the right
250
+ precision.
251
+ - **Pickers.** TimePicker's arrow keys stay within the hour or minute dial; the minute dial is
252
+ always reachable with Tab (at 12:07 too); tabbing through its fields without editing changes
253
+ nothing and keeps hidden seconds. Choosing a day or month from the keyboard keeps focus in the
254
+ calendar; month grids expose rows; week numbers are right when the week does not start on
255
+ Monday; closing the month/year panel shows the year chosen in it. Datebox and DateRangeBox
256
+ inputs are announced as comboboxes opening a labelled dialog.
257
+ - **Restoring the page.** Toggle, CheckButton, Search, Chart, Calendar and MasterPanel restore an
258
+ enhanced element without writing an inline `style` attribute, so `destroy()` works under a
259
+ strict Content Security Policy. `truncate()` puts back a line count the element already had.
260
+ CopyInput destroyed during a copy no longer fires `copy`; copying a second section link no
261
+ longer leaves a stuck checkmark on the first.
262
+ - **Custom elements** keep the user's value when an attribute rebuilds the component or the
263
+ element is moved. A control inside a disabled `<fieldset>` stays disabled when its own
264
+ `disabled` is removed; a disabled `<zx-checklist>` stays disabled when its items change; a form
265
+ reset restores the items a `<zx-checklist>` started with checked.
266
+ - **Data views.** Pagination with `pageSize: 'auto'` grows back when its viewport does, or when a
267
+ card grid gains columns at the same height, and fits
268
+ card grids to whole rows within `minPageSize`/`maxPageSize`. `ChartJsAdapter` draws axis ticks,
269
+ gridlines and radar labels in the theme's colours, readable in dark mode. A pinned column group's
270
+ label sits at the start of its cell. TreeView: a lazy branch marked expanded is closed until
271
+ loaded, and → and `toggle()` load it. Calendar month and year views are one Tab stop moved by the
272
+ arrow keys, and year-view months are proper grids. KanbanView moves several selected cards from
273
+ the grabbed card's place, and a drop where they started changes nothing. MasterPanel no longer
274
+ keeps replaced buttons' handlers.
275
+ - **SvgChartAdapter.** Extreme values (1e16 beside 1e16 + 2, −1e308 to 1e308) no longer freeze the
276
+ page and always get a few distinct round ticks; slices of values too large to add up are drawn;
277
+ dense lines keep each value's tooltip and click target; dense grouped bars stay inside their
278
+ slots; every dataset of a many-ring pie gets a ring; category labels are measured as drawn and
279
+ shortened to fit.
280
+ - **Agents.** An idle animated AgentAvatar or Avatar no longer freezes after its first frame; in
281
+ right-to-left layouts the notch for the activity dot sits under the dot; pupils stay inside the
282
+ eyes. RunStatus and ApprovalCard keep the agent's face when the summary or title changes, and an
283
+ agent with a numeric `seed` has the same face everywhere. `connectAgUi()` no longer overwrites a
284
+ person's message or a card whose id a streamed message reuses, and continues a saved answer
285
+ without taking over another one named like its continuation. Composer and AgentThread match
286
+ mentions as whole names in any script. Many moving avatars share one reduced-motion watcher.
287
+ - **Core.** `storage()` keeps a value it could not save for later handles of the same namespace,
288
+ after a refused write still reads everything else from the browser, and keeps what it has seen
289
+ when the browser's storage stops answering. `deepMerge()` treats a
290
+ `__proto__` key from parsed JSON as data. `Http` puts query parameters before a URL fragment and
291
+ reports a failed response with an HTML body as the HTTP error. `loadFontAwesome()` no longer
292
+ hangs on a kit script that finished loading already, and waits for one still loading. Two overlays sharing an anchor leave no
293
+ empty `style` attribute. `toCsv()` guards cells starting with a tab or carriage return.
294
+ `parseDate()` accepts a time skipped by a daylight-saving change.
295
+ - **ZeyOS binding.** `loadMore()` during a new search, filter or sort, or after one failed, no
296
+ longer appends the next page of the new results to the old rows; applying a saved view without reloading drops the
297
+ request still in flight; `hasMore` uses the page size each request was sent with; `zeyosForm()`
298
+ shows and saves the record requested last when `load()` overlaps; a choice made while a Select's
299
+ initial value loads is kept; a failed initial lookup is no longer also an unhandled rejection;
300
+ `connect()` reports a resource with no API operation through `onError`.
301
+ - **Types.** The declarations type-check in a project without `skipLibCheck` (Calendar, ModuleBar,
302
+ MultiValueEditor and Sheet reported errors), and the build checks them as a consumer would.
303
+ - **Reference.** The API reference lists every public method, static ones with their class
304
+ (`Select.country()`), and the events declared with `@fires`; Message no longer shows
305
+ MessageQueue's methods.
306
+
11
307
  ## 5.7.1 — 2026-11-13
12
308
 
13
309
  One preventable `cancel` for every way of dismissing an overlay, exact values in NumberField, a
package/README.md CHANGED
@@ -6,6 +6,11 @@ and application layouts in plain ES2022 modules. Source modules run directly in
6
6
  distribution also provides ESM and classic-script bundles. Xenon originated at ZeyOS, while its
7
7
  components and contracts remain product- and framework-agnostic.
8
8
 
9
+ Coding agents start with [docs/llms-small.txt](docs/llms-small.txt) — how every component works,
10
+ the layout and the component for each job, and what never to build, in under 8k tokens — then read
11
+ one component's file in [docs/components/](docs/components/index.md). [docs/llms.md](docs/llms.md)
12
+ is the complete reference; all three ship in the package.
13
+
9
14
  ## Quick start
10
15
 
11
16
  Use the ESM bundle when the application already uses modules:
@@ -44,9 +49,12 @@ Import a component source module directly when a bundler needs the narrowest pos
44
49
  import { Slider } from '@zeyos/zx/src/components/slider/slider.js';
45
50
  ```
46
51
 
47
- The package also exposes the bundled ESM entry for ordinary named imports. JavaScript can be
48
- tree-shaken or imported component by component either way, and [`zx-css`](#installing) does the
49
- same for the stylesheet.
52
+ The package also exposes the bundled ESM entry for ordinary named imports. A bundler drops what
53
+ an application does not import from it, apart from what the entry's Field-adapter registrations
54
+ keep, so the per-component import is the smallest: measured with esbuild 0.28.1, `Slider` and
55
+ `Toggle` bundle to about 49 kB minified from their own files and about 276 kB from the package
56
+ entry. The core modules are importable the same way (`@zeyos/zx/src/core/i18n.js`,
57
+ `@zeyos/zx/src/core/icons.js`), and [`zx-css`](#installing) does the same for the stylesheet.
50
58
 
51
59
  TypeScript definitions ship with the package. They are generated from the JSDoc that documents
52
60
  every option, method, and event, so `new Slider(null, { … })` is checked against `SliderOptions`
@@ -60,10 +68,12 @@ owned root is removed, while an enhanced target is restored.
60
68
  ## Optional integration requirements
61
69
 
62
70
  Zx has no package runtime dependencies and its source modules import no external runtime packages.
63
- Optional integrations still need application-provided assets or clients. `Chart` requires an injected
64
- renderer; the only supplied renderer, `ChartJsAdapter`, requires Chart.js 4 supplied by the host.
65
- There is no built-in chart renderer. Chart.js 4.5.1 is pinned as a development dependency and copied
66
- to the documentation site's self-hosted vendor assets during its build; it is not bundled into Zx.
71
+ Optional integrations still need application-provided assets or clients. `Chart` draws through an
72
+ adapter: the built-in `SvgChartAdapter` draws bar, line, pie and doughnut charts as SVG with nothing
73
+ else loaded, and `Surface` draws its `chart` nodes with it by default; `ChartJsAdapter` draws any
74
+ Chart.js 4 type with a Chart.js the host supplies. Chart.js 4.5.1 is pinned as a development
75
+ dependency and copied to the documentation site's self-hosted vendor assets during its build; it is
76
+ not bundled into Zx.
67
77
  Core icons use bundled SVG by default. Opting into Font Awesome requires host-loaded CSS or a kit.
68
78
  ZeyOS `moduleIcon()`, `moduleChip()`, and `zeyosAppIcon()` default to glyphs from the external custom
69
79
  ZeyOS Font Awesome kit; `standard: true` still needs stock Font Awesome assets. `ZeyOS.connect()`
@@ -139,6 +149,7 @@ ZeyOS binding — see `src/zeyos/modules.js`.
139
149
  | `MenuButton` | APG menu button built on `Dropdown`. |
140
150
  | `ContextMenu` | APG right-click menu for a region or, via `selector`, per row. |
141
151
  | `Sheet` | Dockable panel that can float as a modal or nonmodal dialog. |
152
+ | `SheetStack` | Ordered group of Sheets read as one drill-down, stacked or cascaded side by side. |
142
153
  | `Tooltip`, `tooltip()`, `describe()` | Hover/focus description bubble anchored with `position()`. |
143
154
 
144
155
  ### Data
@@ -154,7 +165,7 @@ ZeyOS binding — see `src/zeyos/modules.js`.
154
165
  | `CardView` | Responsive record cards with configurable fields, safe preview media, grouping, actions, sorting, and selection. |
155
166
  | `KanbanView` | Record board with configurable columns, swim lanes, WIP guidance, and cancelable pointer/keyboard movement. |
156
167
  | `Grid`, `Grid.BillingItems()` | Table-compatible preset surface with editable currencies, units, totals, and sub-items. |
157
- | `Chart`, `ChartJsAdapter` | Accessible chart host requiring an injected renderer; the supplied adapter requires host-provided Chart.js 4. |
168
+ | `Chart`, `SvgChartAdapter`, `ChartJsAdapter` | Accessible chart host; `SvgChartAdapter` draws bar, line, pie and doughnut charts with no dependency, `ChartJsAdapter` any Chart.js type with host-provided Chart.js 4. |
158
169
  | `Calendar` | Agenda/day/week/month/year scheduling with timed collisions, spanning events, range selection, and configurable optimistic drag/resize editing. |
159
170
  | `Filter` | Nested, backend-neutral filter expression editor. |
160
171
  | `DataFilter` | Declarative select, text, and custom filters for client-side row sets. |
@@ -216,6 +227,7 @@ ZeyOS binding — see `src/zeyos/modules.js`.
216
227
  | API | Description |
217
228
  | --- | --- |
218
229
  | `AgentThread` | Accessible conversation feed with streamed answers, versions, and actions. |
230
+ | `AgentAvatar` | Generated agent face — a coloured geometric shape with eyes — that shows its activity. |
219
231
  | `BlockView`, `renderBlocks()` | Safe structured answer content with incremental streaming. |
220
232
  | `Composer` | Message input with attachments, mentions, commands, context, and queued messages. |
221
233
  | `RunTrace` | Tool calls, reasoning summaries, retries, and handoffs within a run. |
@@ -228,6 +240,31 @@ ZeyOS binding — see `src/zeyos/modules.js`.
228
240
  See the [Surface guide](docs/agent-surfaces.md) and [component catalogue](docs/agent-catalog.json)
229
241
  for supported schemas and streaming helpers. Both ship in the package.
230
242
 
243
+ ## Composing surfaces at runtime
244
+
245
+ An agent can put interface in front of a person without writing HTML: the model composes a
246
+ `surface/1` document, and `Surface` (or `openSurface()`) validates it and draws it with Zx
247
+ components. The server gives the model its tools and guide from the catalogue, which imports
248
+ nothing that needs a browser:
249
+
250
+ ```js
251
+ import { CATALOG, surfacePrompt, surfaceTools } from '@zeyos/zx/src/components/surface/catalog.js';
252
+
253
+ const tools = surfaceTools(CATALOG, { profile: 'answer' }); // show_surface only
254
+ const guide = surfacePrompt(CATALOG, { profile: 'answer' }); // the nodes it may use, and when
255
+ ```
256
+
257
+ - **Profiles** — `answer` shows (prose, figures, tables, charts, records, links, layout), `ask`
258
+ adds forms, choices and confirmations, `review` adds proposed changes, and `full` is everything.
259
+ Give the model the narrowest that does the job: `answer` costs less than half of `full`.
260
+ `narrowCatalog(CATALOG, { profile, intents, nodes })` narrows further.
261
+ - **One reply per surface** — every surface ends in exactly one `reply/1`, also when the person
262
+ closes it or it is replaced. Wait for it, and treat it as the person's answer, not as proof that
263
+ anything happened: the server runs its own policy again before it acts.
264
+ - **Errors go back to the model** — what fails validation is dropped and reported (the `error`
265
+ event, `getErrors()`, or `validateDocument()` from `surface/validate.js` on the server); return
266
+ those errors to the model so it can correct the surface and send it again.
267
+
231
268
  ## Start from a layout
232
269
 
233
270
  The [layout gallery](https://zx.zeyos.com/layouts) holds complete, working screens on one shared
@@ -239,7 +276,8 @@ drawers, states, and keyboard map come with it.
239
276
  `agent-workspace`, `invoice-editor`, `item-inventory`, `workflows`, `infrastructure`, `crm`.
240
277
  - **Patterns** — single screens: `master-detail`, `record-collection` (any list of records as a
241
278
  table, list, cards, gallery, or board), `dashboard`, `inbox`, `record-page`, `agent-chat`,
242
- `record-wizard`, `checkout-wizard`, `settings-workspace`, `system-states`, `zeyos-invoices`.
279
+ `agent-canvas`, `record-wizard`, `checkout-wizard`, `settings-workspace`, `system-states`,
280
+ `zeyos-invoices`.
243
281
 
244
282
  `layouts.html#<id>` opens one; `layout.html#<id>` shows it alone. The shell helpers
245
283
  (`layouts/kit.js`, `kit.css`) and the record-screen composition (`createOverview()` in
@@ -1,8 +1,12 @@
1
1
  import { Component } from '../../core/component.js';
2
+ import { AgentAvatar } from '../agent-avatar/agent-avatar.js';
2
3
  import { Avatar } from '../avatar/avatar.js';
3
4
  export type ActivityContent = string | number | Node | Component | null;
4
5
  export type AvatarOptions = import('../avatar/avatar.js').AvatarOptions;
5
- export type ActivityAvatar = AvatarOptions | Element | null;
6
+ export type ActivityAvatarDescriptor = AvatarOptions & {
7
+ face?: import('../../internal/agent-model.js').AuthorFace | true;
8
+ };
9
+ export type ActivityAvatar = ActivityAvatarDescriptor | Element | null;
6
10
  export type ActivityAction = {
7
11
  /**
8
12
  * Stable action identifier.
@@ -190,7 +194,14 @@ export type ActivityItemOptions = {
190
194
  };
191
195
  /** @typedef {string|number|Node|Component|null} ActivityContent */
192
196
  /** @typedef {import('../avatar/avatar.js').AvatarOptions} AvatarOptions */
193
- /** @typedef {AvatarOptions|Element|null} ActivityAvatar */
197
+ /**
198
+ * An avatar descriptor. With `face` (`{seed, tone, body, eyes, material}`, or `true` to derive
199
+ * everything from the name) the actor is an agent and is drawn as its AgentAvatar — `name`,
200
+ * `label`, `size`, `tone`, `activity`, `activityLabel`, `animate` and `phase` carry over, the
201
+ * picture and initials options do not.
202
+ * @typedef {AvatarOptions & {face?: import('../../internal/agent-model.js').AuthorFace|true}} ActivityAvatarDescriptor
203
+ */
204
+ /** @typedef {ActivityAvatarDescriptor|Element|null} ActivityAvatar */
194
205
  /**
195
206
  * @typedef {Object} ActivityAction
196
207
  * @property {string|number} id Stable action identifier.
@@ -264,7 +275,7 @@ export declare class ActivityItem extends Component<ActivityItemOptions> {
264
275
  _original: import("../../core/dom.js").TargetSnapshot;
265
276
  _cleaned: boolean;
266
277
  _headingId: string;
267
- _avatarComponent: Avatar;
278
+ _avatarComponent: AgentAvatar | Avatar;
268
279
  _actionsByKey: Map<any, any>;
269
280
  _activity: ActivityItemOptions;
270
281
  static cssName: string;
@@ -0,0 +1,165 @@
1
+ import { Component } from '../../core/component.js';
2
+ export { AGENT_BODIES, AGENT_EYES, agentFace, agentTraits } from './agent-face.js';
3
+ export type AgentBody = import('./agent-face.js').AgentBody;
4
+ export type AgentEyes = import('./agent-face.js').AgentEyes;
5
+ export type AgentTraits = import('./agent-face.js').AgentTraits;
6
+ export type AgentShape = import('./agent-face.js').AgentShape;
7
+ export type AvatarTone = import('../avatar/avatar.js').AvatarTone;
8
+ export type AgentActivity = import('../../internal/agent-model.js').AgentActivity;
9
+ export type AgentMaterial = 'flat' | 'soft';
10
+ export type AgentAvatarOptions = {
11
+ /**
12
+ * The agent's stable identity — an id. Every trait is derived
13
+ * from it, so renaming an agent does not change its face. `null` uses `name`.
14
+ */
15
+ seed?: string | null;
16
+ /**
17
+ * The agent's name; the seed when `seed` is null.
18
+ */
19
+ name?: string;
20
+ /**
21
+ * Colour from the tone palette; `null` derives it from the
22
+ * seed with `avatarTone()`, so the face matches an initials tile keyed the same way.
23
+ */
24
+ tone?: AvatarTone | null;
25
+ /**
26
+ * The silhouette, instead of the derived one: one of the
27
+ * fourteen in {@link AGENT_BODIES}.
28
+ */
29
+ body?: AgentBody | null;
30
+ /**
31
+ * The eye shape, instead of the derived one.
32
+ */
33
+ eyes?: AgentEyes | null;
34
+ /**
35
+ * How far apart the eyes sit — narrow, middle, wide —
36
+ * instead of the derived spacing. With `tone`, `body` and `eyes` it gives back a look kept from
37
+ * {@link AgentAvatar#getTraits}.
38
+ */
39
+ spacing?: 0 | 1 | 2 | null;
40
+ /**
41
+ * How the body is painted. `flat` is the tone's solid
42
+ * fill; `soft` adds a quiet vertical ramp — a touch lighter at the top, deeper at the foot, the plain
43
+ * tone across the eyes — from 28px up. Below 28px, when offline, in print and in forced colours a
44
+ * soft body is drawn flat.
45
+ */
46
+ material?: AgentMaterial;
47
+ /**
48
+ * Preset — `sm` 24px, `md` 32px, `lg` 40px at the default
49
+ * spacing unit — or a pixel size. Small sizes draw less: no pupils below 20px, larger eyes at 24px
50
+ * and below.
51
+ */
52
+ size?: string | number;
53
+ /**
54
+ * Accessible label; null makes the avatar decorative.
55
+ */
56
+ label?: string | null;
57
+ /**
58
+ * What the agent is doing. The eyes take the
59
+ * activity's expression, the activity dot shows it, and its word joins the accessible name.
60
+ */
61
+ activity?: AgentActivity | null;
62
+ /**
63
+ * The activity's word, when the default is not the one
64
+ * to show.
65
+ */
66
+ activityLabel?: string | null;
67
+ /**
68
+ * Whether to draw the activity dot. Without it, show the
69
+ * activity's word nearby: the expression alone is a weaker signal.
70
+ */
71
+ indicator?: boolean;
72
+ /**
73
+ * Moves the avatar with its activity in the shared presence loop
74
+ * (as Avatar does) and lets its eyes blink, drift and scan. Motion is never the only signal and
75
+ * stops under reduced motion. While it is on, the root's `transform` belongs to the loop.
76
+ */
77
+ animate?: boolean;
78
+ /**
79
+ * Where in its activity's cycle the avatar moves, as a fraction
80
+ * from 0 up to 1. `null` derives one from the seed.
81
+ */
82
+ phase?: number | null;
83
+ /**
84
+ * Localized
85
+ * messages: the activity words, `agent.activity.<activity>`.
86
+ */
87
+ msg?: Record<string, string> | Record<string, Record<string, string>>;
88
+ };
89
+ /**
90
+ * A generated face for an agent without a picture: a coloured geometric silhouette with eyes that
91
+ * take the agent's activity, deterministic from the agent's seed.
92
+ * @extends {Component<AgentAvatarOptions>}
93
+ */
94
+ export declare class AgentAvatar extends Component<AgentAvatarOptions> {
95
+ _createdRoot: boolean;
96
+ _original: import("../../core/dom.js").TargetSnapshot;
97
+ /** @type {Record<string, any>} */
98
+ _state: Record<string, any>;
99
+ /** @type {AgentTraits|null} */
100
+ _traits: AgentTraits | null;
101
+ /** A document-unique id for the soft ramp, so two avatars never share a paint server. */
102
+ _paintId: string;
103
+ _destroyed: boolean;
104
+ /** @type {import('../../internal/presence-loop.js').PresenceHandle|null} */
105
+ _presence: import('../../internal/presence-loop.js').PresenceHandle | null;
106
+ static cssName: string;
107
+ /** @type {Readonly<AgentAvatarOptions>} */
108
+ static defaults: Readonly<AgentAvatarOptions>;
109
+ /** @returns {HTMLElement} */
110
+ render(): HTMLElement;
111
+ /**
112
+ * Replaces identity and presentation values: any option but `msg`.
113
+ * @param {Partial<AgentAvatarOptions>} values New values.
114
+ * @returns {this}
115
+ */
116
+ set(values?: Partial<AgentAvatarOptions>): this;
117
+ /**
118
+ * Sets what the agent is doing and, optionally, the word for it. `null` clears the activity.
119
+ * @param {AgentActivity|null} activity
120
+ * @param {string|null} [label=null] The word, when the default is not the one to show.
121
+ * @returns {this}
122
+ */
123
+ setActivity(activity: AgentActivity | null, label?: string | null): this;
124
+ /**
125
+ * What the agent is doing.
126
+ * @returns {AgentActivity|null} The activity, or null without one.
127
+ */
128
+ getActivity(): AgentActivity | null;
129
+ /**
130
+ * The localized word for the current activity — `activityLabel` when set — or null without an
131
+ * activity. A host that draws the avatar inside a control of its own adds it to that control's
132
+ * name, as AppSidebar and ModuleBar do.
133
+ * @returns {string|null}
134
+ */
135
+ getActivityWord(): string | null;
136
+ /**
137
+ * The traits the face is drawn from, so an application can store them — to keep a look across a
138
+ * rename, or to settle a collision between two agents once — and give them back as the `tone`,
139
+ * `body`, `eyes` and `spacing` options.
140
+ * @returns {AgentTraits}
141
+ */
142
+ getTraits(): AgentTraits;
143
+ /**
144
+ * Leaves the presence loop and restores an enhanced target or removes an owned root. Safe to call
145
+ * more than once: only the first call restores, so a target its owner has reused is left alone.
146
+ * @returns {void}
147
+ */
148
+ destroy(): void;
149
+ /** @returns {AgentTraits} */
150
+ _resolveTraits(): AgentTraits;
151
+ /** @returns {number} The rendered size the level of detail is picked for. */
152
+ _px(): number;
153
+ /** @returns {void} */
154
+ _sync(): void;
155
+ /** The word for the current activity, or null without one. @returns {string|null} */
156
+ _activityWord(): string | null;
157
+ /**
158
+ * Joins, follows, or leaves the shared presence loop, and offsets the eyes' own animations.
159
+ * @param {AgentActivity|null} activity
160
+ * @returns {void}
161
+ */
162
+ _syncMotion(activity: AgentActivity | null): void;
163
+ /** @returns {string} */
164
+ _seedKey(): string;
165
+ }