@zeyos/zx 5.7.1 → 5.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (326) hide show
  1. package/CHANGELOG.md +296 -0
  2. package/README.md +47 -9
  3. package/dist/types/components/activity-item/activity-item.d.ts +14 -3
  4. package/dist/types/components/agent-avatar/agent-avatar.d.ts +165 -0
  5. package/dist/types/components/agent-avatar/agent-face.d.ts +93 -0
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +21 -9
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +26 -0
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +3 -1
  9. package/dist/types/components/approval-card/approval-card.d.ts +31 -2
  10. package/dist/types/components/aurora/aurora.d.ts +31 -5
  11. package/dist/types/components/calendar/calendar.d.ts +39 -26
  12. package/dist/types/components/chart/chart.d.ts +250 -20
  13. package/dist/types/components/chart/color.d.ts +66 -0
  14. package/dist/types/components/chart/svg-adapter.d.ts +103 -0
  15. package/dist/types/components/chart/svg-geometry.d.ts +203 -0
  16. package/dist/types/components/check-button/check-button.d.ts +1 -4
  17. package/dist/types/components/checklist/checklist.d.ts +19 -5
  18. package/dist/types/components/code-editor/code-editor.d.ts +55 -1
  19. package/dist/types/components/composer/composer.d.ts +41 -6
  20. package/dist/types/components/context-menu/context-menu.d.ts +36 -8
  21. package/dist/types/components/copy/copy-button.d.ts +6 -0
  22. package/dist/types/components/copy/copy-input.d.ts +1 -0
  23. package/dist/types/components/date-picker/date-picker.d.ts +14 -0
  24. package/dist/types/components/date-picker/time-picker.d.ts +26 -17
  25. package/dist/types/components/datebox/datebox.d.ts +8 -4
  26. package/dist/types/components/dialog/dialog.d.ts +13 -2
  27. package/dist/types/components/empty-state/empty-state.d.ts +10 -1
  28. package/dist/types/components/field/field.d.ts +4 -2
  29. package/dist/types/components/form/form.d.ts +2 -1
  30. package/dist/types/components/kanban-view/kanban-card.d.ts +7 -0
  31. package/dist/types/components/kanban-view/kanban-view.d.ts +15 -3
  32. package/dist/types/components/launcher/launcher.d.ts +26 -0
  33. package/dist/types/components/master-panel/master-panel.d.ts +9 -4
  34. package/dist/types/components/menu-button/menu-button.d.ts +29 -5
  35. package/dist/types/components/message/message.d.ts +308 -5
  36. package/dist/types/components/modal/modal.d.ts +11 -0
  37. package/dist/types/components/modal/native-dialog.d.ts +40 -0
  38. package/dist/types/components/module-bar/module-bar.d.ts +9 -2
  39. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +5 -4
  40. package/dist/types/components/number-field/number-field.d.ts +7 -0
  41. package/dist/types/components/pagination/pagination.d.ts +341 -19
  42. package/dist/types/components/run-status/run-status.d.ts +26 -0
  43. package/dist/types/components/run-trace/run-trace.d.ts +10 -6
  44. package/dist/types/components/search/search.d.ts +16 -4
  45. package/dist/types/components/select/select.d.ts +19 -1
  46. package/dist/types/components/sheet/sheet.d.ts +18 -4
  47. package/dist/types/components/slider/slider.d.ts +2 -1
  48. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -3
  49. package/dist/types/components/stepper/stepper.d.ts +17 -4
  50. package/dist/types/components/surface/catalog.d.ts +61 -17
  51. package/dist/types/components/surface/surface.d.ts +6 -4
  52. package/dist/types/components/table/table.d.ts +207 -5
  53. package/dist/types/components/table/window.d.ts +25 -1
  54. package/dist/types/components/toggle/toggle.d.ts +38 -6
  55. package/dist/types/components/tooltip/tooltip.d.ts +5 -4
  56. package/dist/types/components/tree/tree.d.ts +43 -6
  57. package/dist/types/components/truncate/truncate.d.ts +4 -2
  58. package/dist/types/components/value-list/value-list.d.ts +9 -2
  59. package/dist/types/core/date.d.ts +2 -1
  60. package/dist/types/core/drag-axis.d.ts +10 -5
  61. package/dist/types/core/export.d.ts +2 -2
  62. package/dist/types/core/format.d.ts +3 -1
  63. package/dist/types/core/icons.d.ts +36 -3
  64. package/dist/types/core/keyboard.d.ts +7 -3
  65. package/dist/types/core/messages.d.ts +3 -0
  66. package/dist/types/core/storage.d.ts +4 -3
  67. package/dist/types/core/util.d.ts +3 -1
  68. package/dist/types/elements/define.d.ts +5 -2
  69. package/dist/types/index.d.ts +6 -4
  70. package/dist/types/internal/agent-model.d.ts +99 -0
  71. package/dist/types/internal/app-rail.d.ts +37 -2
  72. package/dist/types/internal/collections.d.ts +18 -0
  73. package/dist/types/internal/menu-items.d.ts +27 -0
  74. package/dist/types/internal/overlay-content.d.ts +23 -0
  75. package/dist/types/internal/presence-loop.d.ts +5 -2
  76. package/dist/types/locales/index.d.ts +3 -0
  77. package/dist/types/zeyos/calendar.d.ts +43 -7
  78. package/dist/types/zeyos/connect.d.ts +4 -0
  79. package/dist/types/zeyos/form.d.ts +13 -5
  80. package/dist/types/zeyos/select.d.ts +5 -2
  81. package/dist/types/zeyos/table.d.ts +16 -8
  82. package/dist/types/zeyos/view.d.ts +2 -1
  83. package/dist/zx-zeyos.esm.js +2998 -451
  84. package/dist/zx-zeyos.esm.min.js +4 -4
  85. package/dist/zx.core.css +4 -0
  86. package/dist/zx.core.min.css +1 -1
  87. package/dist/zx.css +948 -48
  88. package/dist/zx.esm.js +7432 -3408
  89. package/dist/zx.esm.min.js +26 -26
  90. package/dist/zx.global.js +7432 -3408
  91. package/dist/zx.global.min.js +26 -26
  92. package/dist/zx.layered.css +950 -48
  93. package/dist/zx.layered.min.css +1 -1
  94. package/dist/zx.min.css +1 -1
  95. package/docs/agent-catalog.json +159 -1
  96. package/docs/agent-surfaces.md +21 -21
  97. package/docs/api.json +3122 -528
  98. package/docs/components/account-menu.md +24 -0
  99. package/docs/components/activity-item.md +23 -0
  100. package/docs/components/activity-list.md +28 -0
  101. package/docs/components/agent-avatar.md +59 -0
  102. package/docs/components/agent-thread.md +275 -0
  103. package/docs/components/app-icon.md +36 -0
  104. package/docs/components/app-sidebar.md +92 -0
  105. package/docs/components/approval-card.md +71 -0
  106. package/docs/components/aurora.md +34 -0
  107. package/docs/components/avatar.md +37 -0
  108. package/docs/components/badge.md +36 -0
  109. package/docs/components/block-view.md +34 -0
  110. package/docs/components/breadcrumb.md +20 -0
  111. package/docs/components/button.md +23 -0
  112. package/docs/components/calendar.md +68 -0
  113. package/docs/components/card-view.md +73 -0
  114. package/docs/components/card.md +25 -0
  115. package/docs/components/chart.md +109 -0
  116. package/docs/components/check-button.md +16 -0
  117. package/docs/components/checklist.md +19 -0
  118. package/docs/components/code-editor.md +38 -0
  119. package/docs/components/composer.md +107 -0
  120. package/docs/components/context-menu.md +32 -0
  121. package/docs/components/copy.md +37 -0
  122. package/docs/components/data-filter.md +16 -0
  123. package/docs/components/date-picker.md +31 -0
  124. package/docs/components/date-range.md +21 -0
  125. package/docs/components/datebox.md +31 -0
  126. package/docs/components/dialog.md +25 -0
  127. package/docs/components/dock.md +57 -0
  128. package/docs/components/dropdown.md +39 -0
  129. package/docs/components/elements.md +63 -0
  130. package/docs/components/empty-state.md +17 -0
  131. package/docs/components/entity-ref.md +26 -0
  132. package/docs/components/field-upload.md +18 -0
  133. package/docs/components/file-item.md +27 -0
  134. package/docs/components/file-list.md +23 -0
  135. package/docs/components/filter-panel.md +45 -0
  136. package/docs/components/filter.md +47 -0
  137. package/docs/components/finder.md +25 -0
  138. package/docs/components/form-widgets.md +42 -0
  139. package/docs/components/form.md +80 -0
  140. package/docs/components/grid.md +26 -0
  141. package/docs/components/groupbox.md +11 -0
  142. package/docs/components/helpers.md +359 -0
  143. package/docs/components/icons.md +87 -0
  144. package/docs/components/index.md +99 -0
  145. package/docs/components/kanban-view.md +42 -0
  146. package/docs/components/kbd.md +23 -0
  147. package/docs/components/kernel.md +41 -0
  148. package/docs/components/launcher.md +66 -0
  149. package/docs/components/layout.md +33 -0
  150. package/docs/components/list-toolbar.md +38 -0
  151. package/docs/components/loading.md +48 -0
  152. package/docs/components/menu-button.md +47 -0
  153. package/docs/components/message.md +76 -0
  154. package/docs/components/modal.md +27 -0
  155. package/docs/components/module-bar.md +71 -0
  156. package/docs/components/multi-value-editor.md +16 -0
  157. package/docs/components/navigation-bar.md +22 -0
  158. package/docs/components/number-field.md +34 -0
  159. package/docs/components/pagination.md +73 -0
  160. package/docs/components/panel.md +28 -0
  161. package/docs/components/prompt-starters.md +40 -0
  162. package/docs/components/prose.md +38 -0
  163. package/docs/components/questionnaire.md +115 -0
  164. package/docs/components/rating.md +19 -0
  165. package/docs/components/run-status.md +50 -0
  166. package/docs/components/run-trace.md +72 -0
  167. package/docs/components/search.md +11 -0
  168. package/docs/components/select.md +129 -0
  169. package/docs/components/sheet-stack.md +39 -0
  170. package/docs/components/sheet.md +77 -0
  171. package/docs/components/skeleton.md +27 -0
  172. package/docs/components/slider.md +29 -0
  173. package/docs/components/sort-control.md +21 -0
  174. package/docs/components/source-list.md +30 -0
  175. package/docs/components/split-view.md +12 -0
  176. package/docs/components/stat-tile.md +49 -0
  177. package/docs/components/stepper.md +27 -0
  178. package/docs/components/surface.md +152 -0
  179. package/docs/components/tabbox.md +33 -0
  180. package/docs/components/table-view.md +43 -0
  181. package/docs/components/table.md +232 -0
  182. package/docs/components/tag-picker.md +39 -0
  183. package/docs/components/timebox.md +16 -0
  184. package/docs/components/toggle.md +21 -0
  185. package/docs/components/tokens.md +82 -0
  186. package/docs/components/toolbar.md +26 -0
  187. package/docs/components/tooltip.md +16 -0
  188. package/docs/components/tree.md +48 -0
  189. package/docs/components/truncate.md +21 -0
  190. package/docs/components/value-list.md +14 -0
  191. package/docs/components/view-settings.md +56 -0
  192. package/docs/components/workspace-switcher.md +42 -0
  193. package/docs/components/zeyos.md +196 -0
  194. package/docs/llms-small.txt +299 -0
  195. package/docs/llms.md +697 -100
  196. package/docs/llms.txt +46 -19
  197. package/package.json +9 -4
  198. package/src/components/activity-item/activity-item.js +21 -2
  199. package/src/components/agent-avatar/agent-avatar.css +195 -0
  200. package/src/components/agent-avatar/agent-avatar.js +333 -0
  201. package/src/components/agent-avatar/agent-face.js +292 -0
  202. package/src/components/agent-thread/ag-ui.js +44 -11
  203. package/src/components/agent-thread/agent-thread.js +103 -11
  204. package/src/components/agent-thread/ui-message-stream.js +3 -1
  205. package/src/components/app-rail/app-rail.css +5 -0
  206. package/src/components/app-sidebar/app-sidebar.css +3 -0
  207. package/src/components/app-sidebar/app-sidebar.js +4 -3
  208. package/src/components/approval-card/approval-card.css +6 -0
  209. package/src/components/approval-card/approval-card.js +55 -7
  210. package/src/components/aurora/aurora.css +149 -14
  211. package/src/components/aurora/aurora.js +49 -6
  212. package/src/components/calendar/calendar.css +6 -2
  213. package/src/components/calendar/calendar.js +127 -47
  214. package/src/components/card-view/card-view.js +5 -6
  215. package/src/components/chart/chart.css +159 -1
  216. package/src/components/chart/chart.js +450 -62
  217. package/src/components/chart/color.js +297 -0
  218. package/src/components/chart/svg-adapter.js +576 -0
  219. package/src/components/chart/svg-geometry.js +323 -0
  220. package/src/components/check-button/check-button.js +3 -18
  221. package/src/components/checklist/checklist.js +46 -17
  222. package/src/components/checklist/field-adapter.js +4 -1
  223. package/src/components/code-editor/code-editor.css +33 -0
  224. package/src/components/code-editor/code-editor.js +97 -8
  225. package/src/components/code-editor/field-adapter.js +3 -0
  226. package/src/components/composer/composer.css +3 -0
  227. package/src/components/composer/composer.js +100 -22
  228. package/src/components/context-menu/context-menu.js +41 -5
  229. package/src/components/copy/copy-button.js +9 -1
  230. package/src/components/copy/copy-input.js +5 -0
  231. package/src/components/data-filter/filter-core.js +0 -1
  232. package/src/components/date-picker/date-picker.css +8 -0
  233. package/src/components/date-picker/date-picker.js +47 -8
  234. package/src/components/date-picker/date-range-picker.js +1 -1
  235. package/src/components/date-picker/month-picker.js +19 -3
  236. package/src/components/date-picker/time-picker.js +54 -19
  237. package/src/components/datebox/date-range-box.js +7 -3
  238. package/src/components/datebox/datebox.js +32 -6
  239. package/src/components/dialog/dialog.css +6 -0
  240. package/src/components/dialog/dialog.js +22 -30
  241. package/src/components/dropdown/dropdown.js +1 -18
  242. package/src/components/empty-state/empty-state.js +21 -2
  243. package/src/components/field/field.js +19 -3
  244. package/src/components/fieldset/fieldset.js +3 -1
  245. package/src/components/filter/filter.js +9 -0
  246. package/src/components/form/form.js +19 -2
  247. package/src/components/kanban-view/kanban-card.js +15 -2
  248. package/src/components/kanban-view/kanban-view.css +21 -0
  249. package/src/components/kanban-view/kanban-view.js +29 -16
  250. package/src/components/launcher/launcher.css +14 -0
  251. package/src/components/launcher/launcher.js +54 -9
  252. package/src/components/master-panel/master-panel.js +24 -22
  253. package/src/components/menu-button/menu-button.js +26 -4
  254. package/src/components/message/message.css +228 -29
  255. package/src/components/message/message.js +664 -30
  256. package/src/components/modal/modal.js +70 -25
  257. package/src/components/modal/native-dialog.js +91 -0
  258. package/src/components/module-bar/module-bar.css +3 -0
  259. package/src/components/module-bar/module-bar.js +17 -4
  260. package/src/components/multi-value-editor/multi-value-editor.css +7 -2
  261. package/src/components/multi-value-editor/multi-value-editor.js +3 -2
  262. package/src/components/navigation-bar/navigation-bar.js +13 -1
  263. package/src/components/number-field/field-adapter.js +3 -0
  264. package/src/components/number-field/number-field.js +2 -1
  265. package/src/components/pagination/pagination.css +26 -2
  266. package/src/components/pagination/pagination.js +551 -65
  267. package/src/components/prose/prose.js +7 -1
  268. package/src/components/rating/field-adapter.js +3 -0
  269. package/src/components/run-status/run-status.js +43 -3
  270. package/src/components/run-trace/run-trace.js +15 -7
  271. package/src/components/search/search.js +3 -18
  272. package/src/components/select/field-adapter.js +8 -1
  273. package/src/components/select/select.js +68 -13
  274. package/src/components/sheet/sheet.js +27 -8
  275. package/src/components/slider/field-adapter.js +3 -0
  276. package/src/components/slider/slider.js +4 -6
  277. package/src/components/stat-tile/stat-tile.js +24 -9
  278. package/src/components/stepper/stepper.css +15 -0
  279. package/src/components/stepper/stepper.js +34 -2
  280. package/src/components/surface/catalog.js +185 -28
  281. package/src/components/surface/surface.js +10 -5
  282. package/src/components/tabbox/tabbox.js +13 -1
  283. package/src/components/table/table.css +160 -2
  284. package/src/components/table/table.js +479 -52
  285. package/src/components/table/window.js +46 -4
  286. package/src/components/table-view/table-view.js +1 -10
  287. package/src/components/tag-picker/field-adapter.js +3 -0
  288. package/src/components/tag-picker/tag-picker.js +2 -0
  289. package/src/components/timebox/field-adapter.js +3 -0
  290. package/src/components/toggle/toggle.js +51 -27
  291. package/src/components/tooltip/tooltip.js +21 -14
  292. package/src/components/tree/tree.js +87 -14
  293. package/src/components/truncate/truncate.js +21 -5
  294. package/src/components/value-list/value-list.js +37 -9
  295. package/src/components/view-settings/view-settings.js +1 -5
  296. package/src/core/component.js +34 -2
  297. package/src/core/date.js +5 -4
  298. package/src/core/drag-axis.js +24 -7
  299. package/src/core/export.js +4 -4
  300. package/src/core/fontawesome.js +34 -3
  301. package/src/core/format.js +3 -1
  302. package/src/core/http.js +23 -11
  303. package/src/core/icons.js +51 -10
  304. package/src/core/keyboard.js +83 -9
  305. package/src/core/messages.js +3 -0
  306. package/src/core/position.js +2 -2
  307. package/src/core/storage.js +80 -31
  308. package/src/core/util.js +16 -5
  309. package/src/elements/define.js +82 -47
  310. package/src/elements/kit.js +46 -35
  311. package/src/index.js +8 -4
  312. package/src/internal/agent-model.js +152 -0
  313. package/src/internal/app-rail.js +53 -2
  314. package/src/internal/collections.js +25 -0
  315. package/src/internal/menu-items.js +59 -0
  316. package/src/internal/overlay-content.js +35 -0
  317. package/src/internal/presence-loop.js +61 -14
  318. package/src/locales/de.js +3 -0
  319. package/src/zeyos/calendar.js +81 -19
  320. package/src/zeyos/connect.js +5 -1
  321. package/src/zeyos/form.js +29 -10
  322. package/src/zeyos/select.js +36 -12
  323. package/src/zeyos/table.js +43 -11
  324. package/src/zeyos/view.js +2 -1
  325. package/styles/tokens/semantic.css +7 -1
  326. package/styles/zx.css +1 -0
@@ -0,0 +1,50 @@
1
+ # RunStatus
2
+
3
+ Where an agent's run stands: its state in a glyph and a word, what it is doing, its steps, its clock, and what it has cost against its budget.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/run-status · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Where an agent's run stands, for a run panel or a narrow header: the state as a glyph and a word,
8
+ one sentence on what is happening, the steps as a progressbar, when it started and how long the
9
+ agent has worked, the tokens, and the cost against a budget. It draws the values it is given and
10
+ announces nothing itself; the thread the run belongs to announces its milestones.
11
+
12
+ - **Options** — `state` (a run state: `queued`, `running`, `waiting`, `paused`, `blocked`, `done`,
13
+ `failed`, `stopped`, `skipped`; default `'queued'`, reflected as `data-state`), `summary` (one
14
+ sentence, text only), `steps: {done, total}|null`, `started`, `finished` and `waitingSince`
15
+ (local ISO date-time strings or `Date`s), `workMs` (milliseconds worked; the row shows only when
16
+ it is a number), `tokens: [in, out]|number|null` (the pair, or the total as one number),
17
+ `tokenBudget: number|null`, `cost: {amount, budget?, currency}|null`, `model`, `agent`
18
+ (`{seed?, name?, tone?, body?, eyes?, material?}` or `true`: the agent's face before the state,
19
+ working while it runs, looking up while it waits, blocked when blocked or failed, at rest
20
+ otherwise; the compact pill leaves it out), `actions: [{label, kind?, icon?, onclick?}]`, `ticking: true`, `compact: false|true|'icon'`,
21
+ `now: (() => Date)|null`, `locale`, and `msg` (the `agent.status.*` words and the `runStatus.*`
22
+ labels).
23
+ - **Rendering** — the state line; the summary; a `role="progressbar"` whose `aria-valuetext` reads
24
+ "3 of 6 steps"; the actions as small buttons; and a `<dl>` of Started, Working time, Waiting
25
+ since (while `waiting`) or Blocked since (while `blocked`), Finished / Failed at / Stopped at
26
+ (once the run is over), Model, Tokens ("18,420 in · 1,236 out", or "22,840" for a total) and
27
+ Cost. With a `budget` the cost is a `role="meter"` reading "€0.14 of €2.00" whose `data-level`
28
+ is `warning` from 80% and `danger` at 100%. With a `tokenBudget` the tokens are a meter the same
29
+ way, in the locale's compact figures (`Intl.NumberFormat` `notation: 'compact'`): "22.8K of 60K
30
+ tokens"; without one they stay text. A time on another day than today shows its date too.
31
+ - **Blocked** — `blocked` is a glyph and the word "Blocked" in the danger tone, and the steps bar
32
+ takes the danger tone. A blocked run is not over: it shows "Blocked since" from `waitingSince`
33
+ and never a finished time.
34
+ - **Compact** — `compact: true` (reflected as `data-compact`) draws only the state, glyph and
35
+ word, as a pill for a header too narrow for the panel. `compact: 'icon'`
36
+ (`data-compact="icon"`) draws the glyph alone, for a list row: the word stays in the pill,
37
+ visually hidden, as its accessible text, and is the pill's `title` tooltip.
38
+ - **Ticking** — while `state` is `running` and `ticking` is on, the working time counts on once a
39
+ second from `workMs` and the moment of the last `update()`, through one interval that sleeps
40
+ while the page is hidden. Leaving `running` freezes the clock where it stands. `now` replaces
41
+ the clock, both for that count and for deciding whether a time is today; a fixed `now` makes the
42
+ panel deterministic for screenshots and tests. It is fixed at construction.
43
+ - **Focus** — `update()` keeps focus where it was: an action row whose labels, kinds, and icons did
44
+ not change is kept as it is, so the focused button never leaves the DOM; otherwise focus goes to
45
+ the action at the same index, or the nearest one left. When no action is left the panel itself
46
+ holds focus (`tabindex="-1"`, removed again once focus moves on).
47
+ - **Methods** — `update(values)` merges new values and redraws (the clock carries on unless the
48
+ update brings a new `workMs`; `locale`, `msg`, `now`, and `onaction` are fixed), `getState()`
49
+ (the values as copies, `tokenBudget` included, `workMs` counted up to now), `destroy()`.
50
+ - **Events** — `action {index, action}`, after the descriptor's own `onclick`.
@@ -0,0 +1,72 @@
1
+ # RunTrace
2
+
3
+ What an agent did during a run: a one-line summary that opens into a timeline of its steps, each tool call opening to its arguments and result.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/run-trace · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ What an agent did during a run: a one-line summary ("Worked for 41 s · 5 tool calls · 9 sources ·
8
+ 1 retry") that opens into a timeline of its steps. A tool call opens to the arguments it was made
9
+ with and what came back; a retry is drawn under the call it repeats; a hand-off shows both agents.
10
+ The same component draws a plan: `task` steps under a `label` of the plan's own, the people's
11
+ `ask` and `decision` steps among them, chosen one at a time with `selectable`. The trace changes
12
+ only when the application calls `setSteps()`, `upsert()` or `setLabel()`.
13
+
14
+ - **Options** — `steps: []` (`TraceStep[]`, in the order they started), `open: false` (the step
15
+ list starts open), `label: null` (text the summary reads instead of the computed line — "Close
16
+ September · 2 of 5 done"; every state but done still follows it as a word, "· Running"),
17
+ `authors: {}` (who the steps' `actor` and `to` keys name), `showArguments: true`,
18
+ `maxResult: 4000` (characters of a result shown before a "Show all" button; 0 shows every
19
+ result whole), `summary: true` (false: no summary line, the list always shows — for a run panel
20
+ whose state is told beside it), `kindIcons: null` (whether a step leads with its kind's glyph;
21
+ null hides them for a plan whose steps are all `task`s), `selectable: false` (every step can be chosen, see Events), `ticking: false`
22
+ (a running step that has `at` counts its time once a second, on from its `ms` when it was
23
+ resumed), `now: null` (`() => Date`, the
24
+ clock `ticking` counts against, for an application whose world is fixed on another date; real
25
+ time when null), `formatTime: null` (`(at) => string`, how a step's start time is written;
26
+ "10:31:05" when null), `icons: {}` (glyph per step kind over the built-in `search`→search,
27
+ `read`→file, `query`→table, `write`→type, `run`→code, `call`→gear, `handoff`→link-2,
28
+ `think`→dots, `task`→list, `ask`→mail, `decision`→check), `msg` (`runTrace.*` and the
29
+ `agent.status.*` words).
30
+ - **Methods** — `setSteps(steps)` (open steps stay open, focus stays on its step),
31
+ `upsert(step)` (replaces the step with the same `id` and redraws only that step, keeping its
32
+ retries, its open state, and focus on its row or links; a new step is appended, under the step
33
+ it repeats when it has `retryOf`), `setLabel(text|null)` (null or `''` goes back to the computed
34
+ line), `expand(id?)` (opens the list, and that step), `collapse(id?)` (closes the list, or only
35
+ that step), `reveal(id)` (opens the list and the step, scrolls to it, focuses its row and marks
36
+ it `data-state="revealed"` for 2 s; the scroll jumps under reduced motion), `getSteps()`,
37
+ `isOpen()`, `destroy()` (also stops the clock).
38
+ - **Events** — `toggle {id, open}` whenever the list (`id: null`) or a step opens or closes, from a
39
+ click or a method; `reveal {id}`; `open {step, ref}` when one of a step's links is activated
40
+ (copies; the application opens what the `ref` names); `select {id}` in a `selectable` trace when
41
+ the reader activates a row with nothing to open, or opens a step's disclosure (not from
42
+ `expand()` or `reveal()`, so an application can answer `select` with them).
43
+ - **Rendering** — while a step runs the summary reads "Working…" with the step's `doing` line, and
44
+ the step shows "Reading the policy…"; with `ticking` and an `at`, its end shows how long it has
45
+ run ("41 s", "1 min 42 s"). A waiting or blocked run says so and names the step ("Blocked after
46
+ 12 s · 3 tool calls"); paused, stopped and failed runs say so first ("Failed after 12 s · 3
47
+ tool calls"); a run no step of which has started reads "Not started · 6 steps". Counts are left
48
+ out at zero, and `think`, `handoff`, `task`, `ask` and `decision` steps are not tool calls. Each
49
+ step's muted meta line follows its label and wraps under it only when narrow: the `count`, a
50
+ search's `sources`, the actor's name, the start time (`<time>`, tabular figures) and the
51
+ `tokens` it used ("912 tokens"), each only when present. A step's `refs` (`ItemRef[]`, `{id,
52
+ label, icon?, entity?}`) are quiet underlined link buttons under its words, with the glyph when
53
+ `icon` is set. A step with `args`, `result`, `error` or `detail` is a disclosure holding the tool
54
+ name (mono), the detail, the arguments (pretty-printed when they parse as JSON, verbatim
55
+ otherwise) and the result or the error, each in a focusable `<pre>` with a copy button. A
56
+ `handoff` step reads "Finance agent handed over to Collections agent" beside both authors'
57
+ avatars joined by a dotted line — round for a `person`, a rounded square for an agent or a
58
+ model, and an agent author with `face` as its still `AgentAvatar` — and its own label moves to
59
+ the meta line.
60
+ - **Accessibility** — the summary and every step with content follow the APG Disclosure pattern
61
+ (`aria-expanded`, `aria-controls`); in a `selectable` trace a step without content is a plain
62
+ `<button>`. A step's links are buttons beside its row, never inside it, so no control holds
63
+ another; each is reached with Tab. The running step carries `aria-current="step"`. Every state
64
+ is a glyph and a word: visible for waiting, blocked, failed, stopped, skipped and queued steps
65
+ (blocked and failed in the danger tone), visually hidden beside a finished step's duration and a
66
+ running step's "…ing" line. The running glyph pulses only without a reduced-motion preference.
67
+ The clock is one interval for the whole trace, running only while a counting step is in the open
68
+ list and the page is visible. The trace has no live region; the thread it sits in announces
69
+ milestones.
70
+ - **State** — the root's `data-state` is the run's state (`running`, `waiting`, `blocked`,
71
+ `paused`, `stopped`, `failed`, `queued`, `done`), and it is hidden while it has no steps. Each
72
+ step's `<li>` carries `data-kind` and `data-status`.
@@ -0,0 +1,11 @@
1
+ # Search
2
+
3
+ A debounced search field with a clear button and a submit on Enter.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/search · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Search input with embedded search and clear buttons (`role="search"`).
8
+
9
+ - **Options** — `placeholder`, `value`, `clearable: true`, `debounce: 250`.
10
+ - **Methods** — `get()`, `set(value, {silent})`, `focus()`, `clear()`.
11
+ - **Events** — `input {value}` (debounced), `submit {value}` (Enter or the button), `clear`.
@@ -0,0 +1,129 @@
1
+ # Select — APG editable combobox
2
+
3
+ An APG editable combobox: a real text input, a top-layer listbox, and three filtering modes — none, local, and a function you supply.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/select · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Unifies single-select, local filtering, and async loading.
8
+
9
+ - **Options** — `items: []`, `fixedItems: []`, optional `fixedLabel`, `valueKey: 'ID'` (string key or `(item)=>id`),
10
+ `labelKey: 'name'` (string or `(item)=>string`), `renderItem`, `renderValue`,
11
+ `renderValueAdornment`, `renderNone`, `noneLabel`, `actions`, `value`, `disabled`, `placeholder`,
12
+ `label` (accessible combobox name; defaults to the placeholder or "Select"),
13
+ `clearable: false`, `filter: false | 'local' | async (query)=>items`, `searchKeys`,
14
+ `minQuery: 0`, `debounce: 200`, `listHeight: 280`, `groupKey`.
15
+ - **Getters** — `.value`, `.selected`.
16
+ - **Methods** — `get()` (the same as `.value`), `set(id, {silent})`, `setItems()`,
17
+ `setFixedItems()`, `setActions()`, `reset()`, `open()`/`close()`, `enable()`/`disable()`,
18
+ `focus()`.
19
+ - **Events** — `change {value, item}` (`item` is null on clear), preventable
20
+ `action {id, action, query, select}`, `open`, `close`, `query {query}`, `loaded {items}`.
21
+ - **Fixed choices** — `fixedItems` pins entries to the top of the list, separated by a rule (the
22
+ rule is dropped when `groupKey` is on, since a heading already divides them). They belong to the
23
+ control, not to its data: a `filter` function replaces `items` on every query, while the pinned
24
+ entries are narrowed locally against the same query and stay resolvable by `set()`. They survive
25
+ `setItems()` and are shown below `minQuery`. Use them for choices with no row in the source —
26
+ "Unassigned", "Everyone", "Private".
27
+ - **Presets** — `Select.priority(target, opts)` renders the five-level ZeyOS priority scale (values
28
+ 0–4) as grey signal bars filled to the level; only the highest is coloured, a danger square with
29
+ "!". A "No priority" row (value null, message `priority.none`) heads the list and is the empty
30
+ control's placeholder; `clearable: false` removes it, as does a `required` `zxselect` field with
31
+ `preset: 'priority'`. `Select.status(target, opts)` supplies shape- and semantic-color-distinct workflow states
32
+ and accepts replacement `items` (each `{ID, name, indicator, tone, description?, shortcut?}`);
33
+ `Select.permission(target, {groups, value})` pins Private and
34
+ Public above record-access groups. Its value is the tri-state ZeyOS stores (`false` private,
35
+ `true` public, or a group ID), and `groups` takes an array or loader `(query)=>items`.
36
+ - **Glyphs** — `statusIcon(status, {tone?, indicator?, label?})` and `priorityIcon(level, {label?})`
37
+ return the exact glyphs the two presets draw (`.zx-status-icon`, `.zx-priority-icon`; inside a
38
+ Select they also carry `.zx-select__status-indicator` / `.zx-select__priority-icon`), for list
39
+ rows, board columns, filter chips, and headings. Status ids: `backlog` (dotted ring), `todo`
40
+ (empty ring), `in-progress` (ring with a centre dot), `in-review` or `review` (half filled),
41
+ `ready` (a third filled), `waiting` (two thirds filled), `done` (filled, check), `canceled` or
42
+ `cancelled` (filled, cross), `duplicate` (ring with a slash); a `Select.status` item object is
43
+ accepted too, and an unknown id draws a muted empty ring. Indicators: `dotted`, `ring`,
44
+ `progress`, `review`, `ready`, `waiting`, `done`, `canceled`, `duplicate`; tones: `muted`,
45
+ `neutral`, `warning`, `info`, `accent`, `success`, `danger`. Priority levels: `null` (no
46
+ priority, dashes), `0` lowest … `3` high (signal bars filled to the level), `4` highest (danger
47
+ square with "!"). Both are decorative (`aria-hidden`) — always pair them with the status or
48
+ priority as text, or a tooltip on the control holding them; `label` instead makes a standalone
49
+ glyph `role="img"` with that name.
50
+ - **Entity preset** — `Select.entity(target, options)` renders icon/color, label, and secondary
51
+ text using `iconKey`, `colorKey`, and `subtitleKey` (or `renderIcon`). `colorKey` takes a CSS
52
+ colour or a token reference (`var(--zx-color-tone-blue-fg)`); without one the glyph is a neutral
53
+ tile in muted ink. `recent` pins a deduplicated
54
+ **Recent** section above ordinary/local/async results; `create: true|actionDescriptor` appends an
55
+ application-owned command at the bottom without changing the selected ID. `recentLabel` and the
56
+ ordinary Select options remain overridable. For schema-driven ZeyOS loading,
57
+ `zeyosEntitySelect(client, resource, options)` and `buildZeyosEntitySelectConfig()` compose this
58
+ preset from `@zeyos/zx/zeyos`; the core preset itself is backend-neutral.
59
+ - **Keyboard** (APG combobox) — ArrowDown/Alt+ArrowDown open; arrows navigate and wrap; Home/End;
60
+ Enter selects; Esc closes; Tab closes; printable characters filter (editable) or run a typeahead
61
+ (readonly). `aria-activedescendant` tracks the active option.
62
+ - **Appearance** — the highlighted option is a neutral step; a chosen option is a pick and keeps
63
+ the accent tint and its check mark. Group labels are sentence-case captions. The focus ring
64
+ follows keyboard focus: a click on a read-only input (no `filter`) does not draw it
65
+ (`data-focus-origin="pointer"` on the root until the next key). Disabled, the whole control fades
66
+ as a disabled Field does, and not a second time inside one.
67
+ - **Quiet fields** — inside `[data-zx-fields="quiet"]` the value reads as text: no border, fill,
68
+ chevron or clear button until hover; full field chrome while focused or open.
69
+
70
+ ## Select.locale()
71
+
72
+ `Select.locale(target, options)` returns an ordinary Select: each locale is named in its own language ("Deutsch") with the interface's
73
+ name for it beneath ("German"), and the flag of its region or a language chip before it. Names come
74
+ from `Intl.DisplayNames`, so no translation table ships. The value is the canonical BCP 47 tag
75
+ (`'de-AT'`); `set()` and `value` accept any spelling of a listed tag (`'de_at'`). Everything else —
76
+ keyboard map, events, `clearable`, `disabled`, `msg` — is Select's. Field type: `zxselect` with
77
+ `props.preset: 'locale'`.
78
+
79
+ The picker supplies locale names, not translations for the application. It emits `change` without
80
+ changing the active language. See the [Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales)
81
+ for catalogues, message variables, formatting, and runtime language switching.
82
+
83
+ ```js
84
+ Select.locale(el, { locales: ['en-GB', 'de', 'de-AT', 'fr'], value: 'de' });
85
+ ```
86
+
87
+ - **Options** — `locales` (tags or `{code, name?, description?, region?}`; invalid tags are left
88
+ out; a short list of common languages by default), `preferred: []` and `preferredLabel` (pinned
89
+ above the list), `displayLocale` (default: the `lang` option, then `getLanguage()`),
90
+ `display: 'both'|'native'|'localized'`, `flags: 'auto'|'emoji'|'code'|'none'|(region, item) => Node`,
91
+ `flagUrl` (image template, `{code}`/`{CODE}`), `flagRegions` (`{ en: 'GB' }` — a language's flag
92
+ when its likely region is not the one meant), `sort: false`, plus Select options. Message overrides
93
+ retain the `localePicker.*` keys. A list longer
94
+ than seven filters locally by native name, localized name, and tag.
95
+ - **Flags** — a full-tag `flagRegions` override wins, then the tag's own region (`de-AT` → Austria),
96
+ then a language-level override, then the language's likely region (`Intl.Locale#maximize()`:
97
+ `ja` → Japan). A locale with no country (`es-419`) shows
98
+ its language chip. `flags: 'code'` shows chips throughout — the honest choice where a language is
99
+ not a country.
100
+ - **Statics** — `Select.localeItems(locales, options)` returns the rows without the DOM;
101
+ `canonicalLocale(tag)` canonicalizes one tag.
102
+
103
+ ## Select.country()
104
+
105
+ `Select.country(target, options)` returns an ordinary Select: a filterable list of ISO 3166-1 countries, named in the interface's language by
106
+ `Intl.DisplayNames` and drawn with their flags. The value is the upper-case alpha-2 code (`'DE'`);
107
+ `set()` accepts either case. Search matches the name, the code, and the English name, so "Germany"
108
+ finds Deutschland in a German interface. Field type: `zxselect` with `props.preset: 'country'`.
109
+ Custom descriptions are searchable too. Its `displayLocale` names countries without changing the
110
+ application language; see the [Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales).
111
+
112
+ ```js
113
+ Select.country(el, { preferred: ['DE', 'AT', 'CH'], value: 'AT', clearable: true });
114
+ ```
115
+
116
+ - **Options** — `countries` (codes or `{code, name?, description?}`; all of `COUNTRY_CODES` by
117
+ default), `preferred: []` and `preferredLabel`, `displayLocale`, `flags`, `flagUrl`,
118
+ `showCode: false`, `sort: true` (by name, with `Intl.Collator`), plus Select options. Message
119
+ overrides retain the `countryPicker.*` keys.
120
+ - **Statics** — `Select.countryItems(countries, options)` returns the rows without the DOM.
121
+
122
+ ## flag()
123
+
124
+ `flag(code, { kind, src, text, label })` draws one flag as a `.zx-flag` span — for a picker row, a
125
+ table cell, a profile. `kind: 'auto'` (default) draws the platform's flag emoji where it has them
126
+ (`supportsFlagEmoji()`) and a muted code chip where it does not (Windows); `'emoji'`, `'code'`, and
127
+ `'image'` force one. Zx ships no flag artwork: `src: '/flags/{code}.svg'` draws from any flag set
128
+ the application serves. Decorative (`aria-hidden`) unless `label` is given. Also exported:
129
+ `flagEmoji(code)`, `supportsFlagEmoji()`, and `COUNTRY_CODES`.
@@ -0,0 +1,39 @@
1
+ # SheetStack
2
+
3
+ A group of Sheets that reads as one drill-down — and stays small, because the browser already stacks dialogs and already makes Escape unwind them one at a time.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/sheet-stack · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ An ordered group of Sheets that reads as one drill-down. Deliberately tiny, because the browser
8
+ already does the hard part: nested dialogs stack in the top layer by open order, so there is no
9
+ z-index bookkeeping, and Escape closes only the topmost, so unwinding one level at a time is
10
+ native. What is left is which sheet sits at which depth, written onto the elements as `data-depth`
11
+ and `--zx-sheet-depth` for CSS to interpret.
12
+
13
+ Owns no element, so it is a controller rather than a `Component` — constructed with options
14
+ alone, `new SheetStack({…})`.
15
+
16
+ - **Options** — `layout: 'stack'` (`'stack' | 'cascade'`), `offset: 24`, `scale: 0.04`, `max: 3`.
17
+ - **Methods** — `push(sheet)`, `pop()`, `popTo(sheet)`, `clear()`, `top()`, `size()`, `sheets()`,
18
+ `has(sheet)`, `on/off/once`, `destroy()`.
19
+ - **Events** — `push {sheet, depth}`, `pop {sheet}`. `pop` fires however a sheet left — popped,
20
+ dismissed with Escape, or closed by its own button.
21
+ - **Layouts** — `stack` slides each covered sheet back toward its own edge, scales it down, and
22
+ takes it out of the tab order; only the top one is usable, which is the drill-down feel.
23
+ `cascade` shifts each covered sheet clear of the ones in front — by their measured size, not a
24
+ guess — so they sit side by side and all stay usable. `cascade` is usually the right one for an
25
+ ERP screen, where the parent record should stay readable while a line item is edited.
26
+ - **Depth** — numbered from the top: the visible sheet is `0`. Past `max` a sheet stops being
27
+ drawn but stays open and in the stack. In a `stack` only the topmost backdrop shades the page;
28
+ one per depth would compound into black. A `cascade` shades nothing — a backdrop paints directly
29
+ beneath its own dialog in the top layer, so the top sheet's would dim exactly the sheets the
30
+ layout exists to keep readable. Pair a cascade with `modal: false` when the page behind it
31
+ should stay live as well.
32
+ - **Ownership** — the stack never owns its sheets. `destroy()` empties it and strips the depth
33
+ styling without closing anything.
34
+ - **Accessibility** — for `stack`, covered sheets are `inert`. The browser does that on its own
35
+ for stacked *modal* dialogs, but a non-modal stack gets nothing, so the attribute is set either
36
+ way. `cascade` deliberately leaves them interactive.
37
+ - **Gotcha** — `close()` on a dialog dispatches its `close` event in a queued task, not
38
+ synchronously. `pop()` therefore removes the sheet from the stack itself rather than waiting for
39
+ the event, so `popTo()` and `clear()` can loop without racing it.
@@ -0,0 +1,77 @@
1
+ # Sheet
2
+
3
+ An edge-anchored Dialog — one component covers both side sheets and mobile drawers, since only the edge and presentation differ.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/sheet · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Edge-anchored surface — a `Dialog` attached to one side of the viewport instead of floating in the
8
+ middle. One primitive covers both side sheets and mobile drawers, which differ mainly in the edge they take, so
9
+ `side` replaces what would otherwise be two components. Inherits the whole Dialog anatomy: title,
10
+ footer buttons, switchable views, focus restoration, and the reading-sized overlay panel material.
11
+ When a Dock adopts it, the Sheet becomes an opaque layout surface instead.
12
+
13
+ - **Options** — `side: 'end'` (`'start' | 'end' | 'top' | 'bottom'`, logical), `modal: true`
14
+ (`true | 'trap-focus' | false`), `backdrop: 'dim'` (`'dim' | 'blur' | 'none'`), `size: null`
15
+ (CSS length or px number, applied to whichever axis `side` implies), `closeButton: true`
16
+ (independent of `closable`, which governs Escape; when false the ✕ is not displayed, not
17
+ focusable, and closes nothing), plus everything Dialog takes — `title`, `content`, `buttons`, `closable`, `lightDismiss`
18
+ (defaults to `true` here, unlike Modal), `destroyOnClose`, `scope`.
19
+ - **Methods** — `open()`, `close(result?)`, `setSide(side)`, `getSide()`, `setSize(size)`,
20
+ `isModal()`, `isDocked()`, `isOpen()`, `getSize()`, `snapTo(target)`, plus Dialog's `setTitle()`, `setContent()`,
21
+ `setButtons()`, `addView()`, `showView()`.
22
+ - **Events** — `open`, `close {result}`, `cancel {reason}` (preventable; raised by Escape, the ✕,
23
+ a backdrop click or outside press, and a dismissing drag — see Modal's **Dismissal**),
24
+ `resize {size, ratio}`, `dockchange {docked, dock}`.
25
+ - **Docked** — a sheet has two lives, and it does not choose between them: `Dock.adopt(sheet)`
26
+ makes it a track in that dock's flow instead of an overlay, and the dock then owns its side,
27
+ size, and resizing. A docked sheet is always non-modal, `close()` collapses its track to zero
28
+ rather than sliding away, and Escape and outside-click stop dismissing it — it is part of the
29
+ layout, not something covering it. `Dock.release(sheet)` hands it back. Nothing is rebuilt
30
+ across a handoff: the element moves and reopens in place, so DOM state and listeners survive,
31
+ and no `open`/`close` is emitted for what is only a change of address.
32
+ - **Modality** — `true` delegates focus containment, page inertness, Escape, and the backdrop to
33
+ the browser through `showModal()`. Floating `'trap-focus'` and `false` sheets use a manual
34
+ Popover top layer, so they stay viewport-anchored even inside a transformed or clipped theme
35
+ scope while the page keeps scrolling and stays interactive. Escape and outside-click are
36
+ re-implemented through the overlay stack, and `'trap-focus'` adds `focusTrap()` on top: Esc
37
+ closes the sheet when focus is in it (or in a popup it opened) and no popup above it takes the
38
+ key first, an Esc already handled inside (`defaultPrevented`) is ignored, and a press inside a
39
+ menu or dropdown anchored in the sheet counts as inside the sheet. Closing the sheet closes the
40
+ popups it opened. Light dismiss stops at the first layer that contains the press: a press inside
41
+ the upper of two light-dismiss sheets (or inside any overlay above this one) closes neither the
42
+ lower sheet nor anything beneath it; a press outside every layer closes each one that
43
+ light-dismisses. A floating non-modal sheet opened from inside a modal Dialog is hosted by that
44
+ dialog while open, so it stays usable above it, closes when the dialog closes, and goes back to
45
+ its theme scope when it closes. Their top-layer backdrop is
46
+ explicitly transparent and non-filtering; `backdrop` is meaningful only when `modal` is `true`.
47
+ A docked Sheet remains a native non-modal dialog in its Dock's flow. Where the platform has no
48
+ `showPopover()` (jsdom), a floating non-modal sheet is presented the same in-flow way, without
49
+ the top layer.
50
+ - **Resizing and detents** — `resizable` makes the inner edge draggable between `min` and `max`.
51
+ `snap` gives it detents: a number at or below 1 is a fraction of the viewport along the sheet's
52
+ axis, anything larger is pixels, and a string is any CSS length (`'320px'`, `'90%'`). With
53
+ detents a drag settles on the nearest one rather than where it was released, and `snapTo(index)`
54
+ or `snapTo(value)` moves there directly. Dragging below half the smallest allowed size dismisses
55
+ a `closable` sheet, so resize, detent, and swipe-to-dismiss are one gesture whose meaning is
56
+ decided when the pointer settles. `getSize()` reports the current pixel size. A sheet that is
57
+ neither `resizable` nor snapping still has a draggable handle where `handle` shows one — that is
58
+ what makes a drawer dismissible — but the drag may only take size away, never add it, so it
59
+ cannot be grown by dragging when nothing asked for resizing.
60
+ - **Handle** — `handle: 'auto'` shows a grab handle on `top` and `bottom` sheets, which is what
61
+ makes them read as drawers; `true` and `false` force it either way. It exists whenever the sheet
62
+ is `resizable` or has `snap`, visible or not. It is a `separator` with live
63
+ `aria-valuenow`/`aria-valuemin`/`aria-valuemax`: arrow keys along the axis step it by 16px, Shift
64
+ by 64px. A docked sheet hides its handle — the dock's own divider resizes it there.
65
+ - **Custom properties** — `--zx-sheet-size` (written by `size`; the per-side default otherwise)
66
+ and `--zx-sheet-radius` (inner corners of a top/bottom sheet, default `--zx-radius-lg`) are
67
+ internal geometry, not published styling hooks — prefer the options. `--zx-overlay-blur` is a
68
+ tier-2 semantic token and is public: it sets the `'blur'` backdrop's radius, default `8px`.
69
+ - **Motion** — entry and exit both animate, via `@starting-style` and
70
+ `transition-behavior: allow-discrete` on `display`/`overlay`; without them the sheet appears and
71
+ disappears instantly. The slide (and a docked track's collapse, and a stack's shift) runs on
72
+ `--zx-ease-drawer`; the fade keeps `--zx-ease`. All of it sits inside
73
+ `prefers-reduced-motion: no-preference`, and stops inside a `data-zx-motion="reduced"` region.
74
+ - **Keyboard and screen readers** — identical to Dialog: the native `<dialog>` supplies the role
75
+ and `aria-labelledby` points at the title. Escape closes when `closable`, focus moves to the
76
+ `[autofocus]` control or the first focusable descendant on open, and returns to the opener on
77
+ close. Tab cycles within the sheet when `modal` is `true` or `'trap-focus'`.
@@ -0,0 +1,27 @@
1
+ # Skeleton
2
+
3
+ Placeholders shaped like the content that is coming, so the layout does not jump when it arrives.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/skeleton · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Placeholders shaped like the content that is coming, so the layout does not jump when it arrives.
8
+ That is the whole reason to prefer them over a spinner, and the reason they only pay off where the
9
+ shape is genuinely known. All three are factories returning elements.
10
+
11
+ - **Factories** — `skeleton({width, height, radius})` → one block; `skeletonText({lines, width,
12
+ heading, lastLineWidth})` → a stack of lines; `skeletonTable({rows, columns, header})` → the
13
+ grid a table will fill.
14
+ - **skeleton options** — `width: '100%'`, `height: '1rem'` (a number is read as pixels),
15
+ `radius: 'sm'|'md'|'full'`. Equal sides plus `radius: 'full'` gives the circle an avatar or icon
16
+ placeholder needs.
17
+ - **skeletonText options** — `lines: 3` (1–20), `width: '100%'`, `heading: false` (draws the first
18
+ line taller), `lastLineWidth: '60%'` — the short final line is what makes the block read as
19
+ prose rather than as a filled rectangle.
20
+ - **skeletonTable options** — `rows: 5` (1–50), `columns: 4` (1–20), `header: true`. Rendered as
21
+ plain elements, not a `<table>`: there is no data to expose, and a table whose cells are all
22
+ empty is worse for assistive technology than no table at all.
23
+ - **Accessibility** — every skeleton is `aria-hidden`, because a screen reader gains nothing from
24
+ an announced grey box. Set `aria-busy="true"` on the region being filled and remove it together
25
+ with the placeholder.
26
+ - **Behaviour** — the pulse is wrapped in `prefers-reduced-motion: no-preference`; without motion
27
+ a legible static block stays behind.
@@ -0,0 +1,29 @@
1
+ # Slider
2
+
3
+ A bounded numeric value you set by dragging.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/slider · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A bounded numeric value set by dragging — a discount rate, a threshold, a weighting. Built on a
8
+ native `<input type="range">`, which is where the whole keyboard map and the announcement come
9
+ from; everything Zx adds is chrome around it. Field type: `slider`.
10
+
11
+ - **Options** — `value: 0`, `min: 0`, `max: 100`, `step: 1`, `label: ''`, `hideLabel: false`,
12
+ `showValue: true`, `showBounds: false` (draws `min` and `max` either side of the track),
13
+ `showInput: false` (adds a number box for entering a value precisely instead of aiming at it),
14
+ `unit: ''`, `marks: null` (numbers, or `{value, label}` objects), `disabled: false`,
15
+ `readonly: false`, `size: 'md'|'sm'`, `formatValue: (value) => string`. Each mark sits under
16
+ the thumb's centre at its value; the outermost labels end flush with the track instead of
17
+ spilling out of the component.
18
+ - **Methods** — `get()`, `set(value, {silent})`, `setRange(min, max, step?)`, `setLabel()`,
19
+ `setReadonly()`, `focus()`, `enable()`/`disable()`. `value` is also a getter/setter.
20
+ - **Events** — `input {value}` continuously while dragging, `change {value}` once the value is
21
+ committed (pointer released, a range key pressed, or the optional number box committed).
22
+ - **Behaviour** — values snap to the step grid anchored at `min`, so 5…95 by 10 gives 5, 15, 25 —
23
+ not 10, 20, 30. Bounds win over the grid, so a `max` that is not a whole number of steps above
24
+ `min` stays reachable. A fractional step snaps to the decimals it carries: 0.1 gives 0.3, never
25
+ 0.30000000000000004. `stepPrecision(step)` is exported for the same arithmetic elsewhere;
26
+ snapping itself reuses `snapNumber` from NumberField.
27
+ - **Keyboard** — arrows step by `step`, Page Up/Page Down jump, Home and End go to the bounds —
28
+ all native. A read-only slider stays focusable and announced but refuses every edit, pointer and
29
+ keyboard alike; a disabled one leaves the tab order entirely.
@@ -0,0 +1,21 @@
1
+ # SortControl
2
+
3
+ A searchable field selector with an adjacent direction toggle.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/sort-control · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A searchable field selector with an adjacent icon button to reverse the direction. Each field
8
+ appears once. Changing fields preserves direction; toggling direction preserves the field. Built
9
+ from `Select`, with its themed popover and keyboard behavior.
10
+
11
+ - **Options** — `fields: [{id,label}]`, `value: {id,dir:'asc'|'desc'}` (null selects the first field
12
+ ascending), `label` (by default the `sortControl.label` message, and `null` gives no name), `labels: {asc,desc}` to override
13
+ the `sortControl.ascending` and `sortControl.descending` messages, `disabled`.
14
+ - **Methods** — defensive `getValue()`, `setValue(value,{silent})`, `enable()`, `disable()`,
15
+ `focus()`, `destroy()`. Unknown fields or directions are rejected. An empty catalogue disables
16
+ selection and returns null.
17
+ - **Keyboard** — Tab reaches the direction button and field selector; Space/Enter toggle the
18
+ focused direction button. The field retains Select’s combobox keyboard map. The button’s
19
+ accessible name includes the current direction; its hover title shows current → next direction.
20
+ - **Events** — one `change {value:{id,dir}}` event per changed field or direction. Typed search text does
21
+ not change the sort. The application applies the resulting state to its table, data source or route.
@@ -0,0 +1,30 @@
1
+ # SourceList
2
+
3
+ The sources an answer cites, as numbered chips with a card of each one’s title, site, and the passage used.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/source-list · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ The sources an answer cites: a numbered chip (or row) for each, naming its site or title, with a
8
+ card of its title, where it is, and the passage used on hover and focus. It never loads a favicon,
9
+ a thumbnail, or any other remote resource.
10
+
11
+ - **Options** — `sources: []` (`Source[]`, numbered in order as the answer's `[n]` markers are),
12
+ `label` (the visible label naming the list, by default the `sourceList.label` message; `''` or
13
+ `null` drops it and names the list with that message), `layout: 'chips'|'list'` (`list` gives each source a row with
14
+ its title and site), `numbered: true`, `icons: {}` (glyph per kind over the built-in
15
+ `web`→link-2, `file`→file, `record`→table, `call`→gear), `msg`.
16
+ - **Methods** — `setSources(sources)` (focus stays on the same source), `highlight(n)` (a number is
17
+ the 1-based position, a string an `id`: scrolls to it, focuses it, and marks it
18
+ `data-state="highlighted"` for 2 s — the answer to a BlockView `cite`), `getSources()`,
19
+ `destroy()`.
20
+ - **Events** — `select {source, n}`, **preventable** (on the component or on the bubbling
21
+ `zx-select`). Unprevented, a `web` source opens its `href` in a new tab with
22
+ `noopener,noreferrer`, and only when `safeHref()` accepts it and it is an absolute `https:` URL;
23
+ the card shows that host. Every other kind is the application's to act on, for example
24
+ `runTrace.reveal(source.call)`.
25
+ - **Accessibility** — each source is a native `<button>` named "Source 1: bank.example" (the
26
+ visible number and name, plus visually hidden words); its card is a `Tooltip`, so it is the
27
+ button's description while open. The list is an `<ol>` labelled by the visible label. It is not
28
+ a landmark, so a thread with many answers does not repeat a "Sources" region.
29
+ - **Privacy** — the pure `sourceHref(source)` returns the only address a source may open, or null;
30
+ nothing is fetched to draw a source.
@@ -0,0 +1,12 @@
1
+ # SplitView
2
+
3
+ Two panes and a divider the reader owns: drag it, tab to it and use the arrow keys, double-click to reset, and — where it is allowed — fold a pane away entirely.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/split-view · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Two panes with a divider the user owns. The layout is a three-track CSS grid driven by one custom property, `--zx-split-size`, so a drag writes a single style value per frame and the browser does the rest. That property holds whatever was asked for: `38%` stays a percentage and keeps tracking the container until someone drags, at which point it becomes pixels and stays put. The divider follows the WAI-ARIA window splitter pattern — a focusable `separator` with live pixel `aria-valuenow`/`aria-valuemin`/`aria-valuemax` — and a `ResizeObserver` re-clamps the size when the container shrinks, bailing on a container that measures zero (a hidden tab, a detached node) rather than flattening a good size to nothing. A split view given an existing element with children adopts the first two as its panes and hands them back on `destroy()`.
8
+
9
+ - **Options** — `orientation` (`'horizontal'` default: panes side by side behind a vertical divider; `'vertical'` stacks them), `start` / `end` (Node, Component, string, or null), `size` (`'38%'`; a number is pixels, a string is any CSS length), `min` (160), `max` (null — "whatever the container allows"), `collapsible` (`false`, `'start'`, or `'end'`), `collapsed` (false, true, or a pane name), `snap` (0 — a radius in pixels within which a settled drag lands exactly on the initial size, the minimum, or the maximum), `storageKey` (null; storage failures degrade to memory rather than throwing), `disabled` (false), `label` (`'Resize panes'`).
10
+ - **Methods** — `setSize(value)`, `getSize()` (pixels), `getRatio()`, `setStart(content)`, `setEnd(content)`, `collapse(which)`, `expand()`, `isCollapsed()` (returns the pane name or false), `enable()`, `disable()`, `isDisabled()`, `destroy()`. The setters are programmatic and emit nothing.
11
+ - **Events** — `resize` `{size, ratio}`, throttled to at most once per animation frame during a drag; `resizeend` `{size, ratio}` once an interaction settles (a drag ends, a key moves the divider, a double-click resets it); `collapse` `{pane}`; `expand`. A press that never moved is a click, not a resize, and reports nothing.
12
+ - **Keyboard** — With the divider focused: `←` / `→` (horizontal) or `↑` / `↓` (vertical) move it 16px, `Shift` with an arrow moves 64px, `Home` goes to the minimum, `End` to the maximum, and `Enter` or `Space` folds a collapsible pane away and brings it back. Any key that moves the divider expands a collapsed pane first. Double-clicking the divider resets it to the initial `size`.
@@ -0,0 +1,49 @@
1
+ # StatTile — `statTile(options)` / `StatTile`
2
+
3
+ A labelled number: the metric loud, the label small above it, and — when there is one — a signed change that says which way it went without claiming that way is good.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/stat-tile · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A labelled number with optional delta, trend and icon: the most-copied snippet in any
8
+ application UI, and the reason competing template products advertise a card count rather than a
9
+ component count. `statTile()` is the convenience form of `new StatTile(null, options)` and
10
+ returns the component, the way `tooltip()` does; call `.toElement()` for the node to place.
11
+
12
+ - **Options** — `label`, `value`, `format: 'number'|'currency'|'percent'|'fileSize'|null|fn`,
13
+ `currency`, `locale`, `caption`, `delta`, `deltaKind: 'positive'|'negative'|'neutral'`,
14
+ `deltaFormat`, `deltaLabel`, `trend: number[]`, `icon`, `kind`, `variant: 'default'|'plain'`,
15
+ `emphasis`, `href`, `clickable`, `loading`, `msg`.
16
+ - **Appearance** — the label is a sentence-case muted line (13px, medium); the value is the loud
17
+ part (24px, weight 650, tabular figures); `caption` is one muted context line under it ("of
18
+ 13,184"). `icon` is a muted glyph beside the label, never a coloured chip; `kind` tints only the
19
+ sparkline. The tile is a column with the sparkline at its foot, so tiles in a row are the same
20
+ height and line up whether or not each has a caption, a delta or a trend.
21
+ - **Framed or plain** — the default is a framed tile on its own surface: use it where a figure
22
+ stands among other content, as on a dashboard. `variant: 'plain'` drops the frame, the fill and
23
+ the padding, for a record's own figures under its title: its text sits on the content edge,
24
+ space alone separates it from the next, and the figure steps down to 16px. Do not draw boxes
25
+ around plain figures in the layout either. Reflected as `data-variant`.
26
+ - **One figure leads** — `emphasis: true` sets one figure per row above the others: 24px in a
27
+ plain row (the record title's size, never above it), 30px on a framed tile. Reflected as
28
+ `data-emphasis`. The size is `--zx-stat-tile-value-size`, which the loading skeleton reads too.
29
+ - **Methods** — `update(options)`, `getAccessibleName()`.
30
+ - **Events** — `click {event}`.
31
+
32
+ - **A delta is never colour alone.** It carries its sign and a direction glyph, and `deltaKind`
33
+ decides the colour rather than the sign — rising ticket counts are not a success, and a
34
+ component that assumes "up is good" is wrong for half the metrics in any business.
35
+ - **The accessible name is label + value (with its caption) + spoken delta** ("Active items,
36
+ 2,184 of 13,184, up 2 vs. last week"). The visible
37
+ `+2` row and the sparkline are `aria-hidden`, because a sparkline nobody can read is
38
+ decoration and saying the delta twice is worse than saying it once.
39
+ - **The element follows the behaviour** — `href` renders an `<a>`, `onclick` without `href` a
40
+ `<button>`, neither a `<div>` with `role="group"`. Never a div with a click handler.
41
+ `clickable: true` renders the button without an `onclick` option, for subscribing with
42
+ `on('click', …)`. An explicit `clickable: false` wins over `onclick`: the tile stays a `<div>`
43
+ and the handler is never called, for a caller that always passes a handler and decides per tile
44
+ whether it applies. It never turns a tile with an `href` into anything but a link. Leave
45
+ `onclick` out, rather than passing an empty function, for a tile that does nothing.
46
+ - **`loading: true` renders a skeleton shaped like the tile**, not a spinner.
47
+
48
+ Nothing in it assumes a fixed set of buckets or a fixed label: the content of a dashboard tile
49
+ is the instance's, not the library's.
@@ -0,0 +1,27 @@
1
+ # Stepper
2
+
3
+ The wizard progress rail: four step states, an optional “Step 2 of 4” counter, and a preventable change event so a step can refuse to be left.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/stepper · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Linear progress through a multi-step flow: a numbered `<ol>` where each step is upcoming, active,
8
+ complete, or errored. It promotes the markup the checkout and record wizards used to hand-roll.
9
+ Advancing past a step marks it complete automatically, and only steps the `clickable` policy allows
10
+ are rendered as real buttons — the rest are not focusable at all. A horizontal rail fills the width
11
+ it is given: the labels keep their own width and the connectors stretch to take the slack, wrapping
12
+ onto more lines only when the container is too narrow to hold them. A wrapped row ends at its last
13
+ step: no connector runs on from it to the container's edge. The component marks that step with
14
+ `data-row-end` as the layout changes.
15
+
16
+ - **Options** — `steps: [{name, title, description?, optional?, disabled?}]`, `active` (defaults to
17
+ the first enabled step), `orientation: 'horizontal'|'vertical'`, `clickable:
18
+ 'completed'|'all'|false` (default `'completed'`, so users can go back but not skip ahead),
19
+ `showNumbers: true`, `counter: false` (adds a "Step 2 of 4" line).
20
+ - **Methods** — `setSteps()`, `goTo(name)`, `next()`, `previous()`, `getActive()`, `getIndex()`,
21
+ `complete(name)`/`uncomplete(name)`, `setError(name, boolean)`, `setDisabled(name, boolean)`,
22
+ `getState()` → `{active, index, completed, errored}`, `destroy()`.
23
+ - **Events** — `change {name, previous, index}`, **preventable** with `event.preventDefault()` so a
24
+ step can refuse to be left until its form validates.
25
+ - **Semantics** — the active step carries `aria-current="step"`; every step carries
26
+ `data-state="upcoming"|"active"|"complete"|"error"`, and complete and errored steps swap the
27
+ number for a `check` or `warning` glyph.