@zeyos/zx 5.6.0 → 5.7.1

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 (227) hide show
  1. package/CHANGELOG.md +188 -0
  2. package/README.md +73 -7
  3. package/bin/zx-css.js +328 -0
  4. package/dist/types/components/account-menu/account-menu.d.ts +4 -2
  5. package/dist/types/components/activity-list/activity-list.d.ts +14 -8
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +142 -14
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
  9. package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
  10. package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
  11. package/dist/types/components/calendar/calendar-model.d.ts +9 -2
  12. package/dist/types/components/calendar/calendar.d.ts +12 -4
  13. package/dist/types/components/chart/chart.d.ts +25 -13
  14. package/dist/types/components/checklist/checklist.d.ts +29 -0
  15. package/dist/types/components/code-editor/code-editor.d.ts +7 -2
  16. package/dist/types/components/composer/composer.d.ts +206 -4
  17. package/dist/types/components/composer/queue.d.ts +76 -0
  18. package/dist/types/components/copy/copy-button.d.ts +6 -4
  19. package/dist/types/components/copy/copy-input.d.ts +10 -6
  20. package/dist/types/components/datebox/date-range-box.d.ts +33 -0
  21. package/dist/types/components/datebox/placeholder.d.ts +7 -0
  22. package/dist/types/components/dialog/dialog.d.ts +2 -2
  23. package/dist/types/components/dock/dock.d.ts +12 -3
  24. package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
  25. package/dist/types/components/field-upload/field-upload.d.ts +3 -2
  26. package/dist/types/components/file-item/file-item.d.ts +3 -2
  27. package/dist/types/components/file-list/file-list.d.ts +14 -8
  28. package/dist/types/components/filter/filter-model.d.ts +31 -1
  29. package/dist/types/components/filter/filter.d.ts +20 -2
  30. package/dist/types/components/finder/finder.d.ts +14 -6
  31. package/dist/types/components/flag/flag.d.ts +99 -0
  32. package/dist/types/components/grid/grid.d.ts +1 -1
  33. package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
  34. package/dist/types/components/launcher/launcher.d.ts +2 -0
  35. package/dist/types/components/modal/modal.d.ts +34 -8
  36. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
  37. package/dist/types/components/number-field/number-field.d.ts +41 -7
  38. package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
  39. package/dist/types/components/prose/prose.d.ts +9 -6
  40. package/dist/types/components/questionnaire/conditions.d.ts +270 -0
  41. package/dist/types/components/questionnaire/items.d.ts +52 -30
  42. package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
  43. package/dist/types/components/rating/rating.d.ts +5 -3
  44. package/dist/types/components/select/country.d.ts +106 -0
  45. package/dist/types/components/select/field-adapter.d.ts +2 -1
  46. package/dist/types/components/select/locale.d.ts +102 -0
  47. package/dist/types/components/select/select.d.ts +41 -2
  48. package/dist/types/components/sheet/sheet.d.ts +2 -2
  49. package/dist/types/components/slider/slider.d.ts +1 -0
  50. package/dist/types/components/sort-control/sort-control.d.ts +7 -3
  51. package/dist/types/components/source-list/source-list.d.ts +7 -5
  52. package/dist/types/components/split-view/split-view.d.ts +5 -3
  53. package/dist/types/components/surface/catalog.d.ts +260 -0
  54. package/dist/types/components/surface/elicit.d.ts +81 -0
  55. package/dist/types/components/surface/mcp.d.ts +165 -0
  56. package/dist/types/components/surface/schema.d.ts +314 -0
  57. package/dist/types/components/surface/stream.d.ts +118 -0
  58. package/dist/types/components/surface/surface.d.ts +718 -0
  59. package/dist/types/components/surface/text.d.ts +277 -0
  60. package/dist/types/components/surface/validate.d.ts +339 -0
  61. package/dist/types/components/table/table.d.ts +55 -3
  62. package/dist/types/components/table/window.d.ts +203 -0
  63. package/dist/types/components/toolbar/toolbar.d.ts +10 -6
  64. package/dist/types/components/tooltip/tooltip.d.ts +2 -2
  65. package/dist/types/components/tree/tree.d.ts +20 -13
  66. package/dist/types/core/component.d.ts +10 -0
  67. package/dist/types/core/date.d.ts +8 -1
  68. package/dist/types/core/dom.d.ts +15 -0
  69. package/dist/types/core/http.d.ts +10 -0
  70. package/dist/types/core/i18n.d.ts +38 -0
  71. package/dist/types/core/messages.d.ts +344 -1
  72. package/dist/types/core/storage.d.ts +7 -2
  73. package/dist/types/elements/define.d.ts +21 -46
  74. package/dist/types/elements/definitions.d.ts +147 -0
  75. package/dist/types/elements/kit.d.ts +7 -0
  76. package/dist/types/elements/reflect.d.ts +6 -3
  77. package/dist/types/index.d.ts +10 -1
  78. package/dist/types/internal/date-locale.d.ts +7 -0
  79. package/dist/types/internal/json-patch.d.ts +146 -0
  80. package/dist/types/locales/de.d.ts +13 -0
  81. package/dist/types/locales/en.d.ts +2 -0
  82. package/dist/types/locales/index.d.ts +823 -0
  83. package/dist/types/zeyos/view.d.ts +8 -1
  84. package/dist/zx-zeyos.esm.js +16852 -15131
  85. package/dist/zx-zeyos.esm.min.js +5 -5
  86. package/dist/zx.core.css +1276 -0
  87. package/dist/zx.core.min.css +1 -0
  88. package/dist/zx.css +520 -143
  89. package/dist/zx.esm.js +40940 -29684
  90. package/dist/zx.esm.min.js +36 -23
  91. package/dist/zx.global.js +40940 -29684
  92. package/dist/zx.global.min.js +36 -23
  93. package/dist/zx.layered.css +17315 -0
  94. package/dist/zx.layered.min.css +1 -0
  95. package/dist/zx.min.css +1 -1
  96. package/docs/agent-catalog.json +12501 -0
  97. package/docs/agent-surfaces.md +340 -0
  98. package/docs/api.json +909 -137
  99. package/docs/llms.md +1046 -80
  100. package/docs/llms.txt +30 -9
  101. package/package.json +29 -6
  102. package/src/components/account-menu/account-menu.js +6 -3
  103. package/src/components/activity-item/activity-item.js +2 -1
  104. package/src/components/activity-list/activity-list.js +16 -10
  105. package/src/components/agent-thread/ag-ui.js +1439 -0
  106. package/src/components/agent-thread/agent-thread.js +359 -54
  107. package/src/components/agent-thread/ui-message-stream.js +1281 -0
  108. package/src/components/app-sidebar/app-sidebar.js +18 -8
  109. package/src/components/approval-card/approval-card.js +3 -2
  110. package/src/components/block-view/block-view.js +7 -6
  111. package/src/components/breadcrumb/breadcrumb.js +8 -5
  112. package/src/components/button/button.css +24 -11
  113. package/src/components/calendar/calendar-model.js +8 -2
  114. package/src/components/calendar/calendar.js +53 -18
  115. package/src/components/chart/chart.js +54 -23
  116. package/src/components/checklist/checklist.css +9 -1
  117. package/src/components/checklist/checklist.js +59 -3
  118. package/src/components/checklist/field-adapter.js +2 -11
  119. package/src/components/code-editor/code-editor.js +45 -8
  120. package/src/components/code-editor/field-adapter.js +1 -1
  121. package/src/components/composer/composer.css +80 -1
  122. package/src/components/composer/composer.js +390 -16
  123. package/src/components/composer/queue.js +78 -0
  124. package/src/components/context-menu/context-menu.js +12 -1
  125. package/src/components/copy/copy-button.js +9 -7
  126. package/src/components/copy/copy-input.js +10 -6
  127. package/src/components/date-picker/date-picker.js +2 -1
  128. package/src/components/date-picker/date-range-picker.js +8 -7
  129. package/src/components/datebox/date-range-box.js +3 -9
  130. package/src/components/datebox/datebox.js +18 -21
  131. package/src/components/datebox/placeholder.js +18 -0
  132. package/src/components/dialog/dialog.js +4 -5
  133. package/src/components/dock/dock.js +34 -13
  134. package/src/components/entity-ref/entity-ref.js +16 -5
  135. package/src/components/field-upload/field-upload.js +81 -38
  136. package/src/components/file-item/file-item.js +70 -40
  137. package/src/components/file-list/file-list.js +15 -9
  138. package/src/components/filter/filter-model.js +46 -8
  139. package/src/components/filter/filter.css +3 -3
  140. package/src/components/filter/filter.js +29 -10
  141. package/src/components/filter-panel/filter-panel.js +13 -5
  142. package/src/components/finder/finder.js +50 -26
  143. package/src/components/flag/flag.css +40 -0
  144. package/src/components/flag/flag.js +177 -0
  145. package/src/components/form/form.js +1 -1
  146. package/src/components/grid/grid.js +22 -8
  147. package/src/components/kanban-view/kanban-view.js +51 -81
  148. package/src/components/launcher/launcher.js +17 -2
  149. package/src/components/list-toolbar/list-toolbar.js +2 -1
  150. package/src/components/master-panel/master-panel.js +1 -1
  151. package/src/components/menu-button/menu-button.js +4 -0
  152. package/src/components/message/message.js +3 -0
  153. package/src/components/modal/modal.js +62 -8
  154. package/src/components/multi-value-editor/multi-value-editor.js +10 -9
  155. package/src/components/navigation-bar/navigation-bar.js +3 -3
  156. package/src/components/number-field/number-field.js +98 -29
  157. package/src/components/prompt-starters/prompt-starters.css +91 -0
  158. package/src/components/prompt-starters/prompt-starters.js +206 -0
  159. package/src/components/prose/prose.js +14 -10
  160. package/src/components/questionnaire/conditions.js +666 -0
  161. package/src/components/questionnaire/items.js +150 -41
  162. package/src/components/questionnaire/questionnaire.js +126 -32
  163. package/src/components/rating/rating.js +5 -4
  164. package/src/components/run-status/run-status.js +2 -2
  165. package/src/components/select/country.js +136 -0
  166. package/src/components/select/field-adapter.js +7 -2
  167. package/src/components/select/locale.js +219 -0
  168. package/src/components/select/select.css +20 -22
  169. package/src/components/select/select.js +94 -12
  170. package/src/components/sheet/sheet-stack.js +10 -1
  171. package/src/components/sheet/sheet.js +12 -5
  172. package/src/components/slider/slider.js +7 -2
  173. package/src/components/sort-control/sort-control.js +15 -5
  174. package/src/components/source-list/source-list.js +7 -4
  175. package/src/components/split-view/split-view.js +5 -3
  176. package/src/components/surface/catalog.js +1334 -0
  177. package/src/components/surface/elicit.js +107 -0
  178. package/src/components/surface/mcp.js +243 -0
  179. package/src/components/surface/schema.js +644 -0
  180. package/src/components/surface/stream.js +245 -0
  181. package/src/components/surface/surface.css +308 -0
  182. package/src/components/surface/surface.js +2291 -0
  183. package/src/components/surface/text.js +513 -0
  184. package/src/components/surface/validate.js +2218 -0
  185. package/src/components/tabbox/tabbox.js +9 -0
  186. package/src/components/table/table.css +63 -3
  187. package/src/components/table/table.js +167 -28
  188. package/src/components/table/window.js +317 -0
  189. package/src/components/toolbar/toolbar.js +12 -7
  190. package/src/components/tooltip/tooltip.css +2 -3
  191. package/src/components/tooltip/tooltip.js +32 -5
  192. package/src/components/tree/tree.js +53 -23
  193. package/src/core/component.js +25 -1
  194. package/src/core/date.js +62 -16
  195. package/src/core/dom.js +67 -4
  196. package/src/core/format.js +15 -13
  197. package/src/core/http.js +29 -20
  198. package/src/core/i18n.js +83 -10
  199. package/src/core/icons.js +13 -2
  200. package/src/core/keyboard.js +79 -8
  201. package/src/core/messages.js +376 -2
  202. package/src/core/overlay-host.js +1 -0
  203. package/src/core/position.js +3 -2
  204. package/src/core/storage.js +59 -6
  205. package/src/elements/define.js +178 -130
  206. package/src/elements/definitions.js +229 -0
  207. package/src/elements/kit.js +444 -0
  208. package/src/elements/reflect.js +8 -3
  209. package/src/index.js +10 -1
  210. package/src/internal/date-locale.js +11 -0
  211. package/src/internal/json-patch.js +405 -0
  212. package/src/locales/de.js +911 -0
  213. package/src/locales/en.js +2 -0
  214. package/src/locales/index.js +7 -0
  215. package/src/zeyos/calendar.js +2 -1
  216. package/src/zeyos/form.js +2 -1
  217. package/src/zeyos/launcher.js +7 -6
  218. package/src/zeyos/module-bar.js +2 -1
  219. package/src/zeyos/schema.js +37 -23
  220. package/src/zeyos/select.js +4 -3
  221. package/src/zeyos/table.js +2 -13
  222. package/src/zeyos/view.js +57 -17
  223. package/styles/core.css +11 -0
  224. package/styles/tokens/semantic.css +1 -0
  225. package/styles/zeyos.css +2 -0
  226. package/styles/zx.css +4 -8
  227. package/styles/zx.layered.css +1 -0
package/CHANGELOG.md CHANGED
@@ -8,6 +8,194 @@ and friends remain the complete record.
8
8
 
9
9
  ## Unreleased
10
10
 
11
+ ## 5.7.1 — 2026-11-13
12
+
13
+ One preventable `cancel` for every way of dismissing an overlay, exact values in NumberField, a
14
+ lockable Checklist, and fixes for strict Content Security Policies and the pressed button state.
15
+
16
+ ### Added
17
+
18
+ - **`cancel` covers every dismissal.** Modal, Dialog and Sheet now raise the preventable `cancel`
19
+ for the header ✕, a backdrop click, a press outside a non-modal Sheet and a dismissing drag, not
20
+ only for Escape, and `event.detail.reason` names the gesture (`'escape'`, `'close-button'`,
21
+ `'button'`, `'backdrop'`, `'outside'`, `'drag'`). One listener is now enough for an "unsaved
22
+ changes" check. A programmatic `close()` still raises none.
23
+ - **`NumberField` `snap: false`** keeps a typed or assigned value exactly as entered instead of
24
+ moving it onto the `step` grid; `step` then only sets the button and arrow-key increment.
25
+ - **`Checklist`** `label` and `disabled` options, `setLabel()`, `enable()`, `disable()` and
26
+ `isDisabled()`.
27
+ - Bundled icons `download`, `box-archive`, `pencil` and `pen-to-square`, with `archive` and `edit`
28
+ as aliases. A glyph registered under an alias name with `registerIcons()` keeps precedence.
29
+
30
+ ### Changed
31
+
32
+ - A listener that treated `cancel` as "Escape was pressed" now also runs for the other dismissal
33
+ gestures; read `event.detail.reason` to tell them apart.
34
+ - A pressed button (`aria-pressed="true"`) has a stronger neutral fill and a frame that holds 3:1
35
+ against its neighbours in both themes. A pressed `ghost` button gains the frame too.
36
+
37
+ ### Fixed
38
+
39
+ - Escape on a modal overlay whose `cancel` was prevented no longer closes it on the third press.
40
+ - Anchored popups (Select, TagPicker, Dropdown, Tooltip, Datebox, Composer) no longer write an
41
+ empty `style=""` attribute on close, which a `style-src` policy without `'unsafe-inline'`
42
+ blocked and reported. Restoring an enhanced target's inline style no longer writes the attribute
43
+ either.
44
+
45
+ ## 5.7.0 — 2026-11-09
46
+
47
+ Locale and country Select presets, complete English/German catalogues and plural messages,
48
+ agent surfaces and protocol adapters, and fixes across forms, data views and overlays.
49
+
50
+ ### Added
51
+
52
+ - `translatePlural(key, count, args, {locale}?)` and `Component.msgPlural(key, count, ...args)`
53
+ select cardinal forms with an explicit numeric count, preserving existing message overrides.
54
+ - English catalogue export and an opt-in English/German manifest at `@zeyos/zx/locales/en.js`
55
+ and `@zeyos/zx/locales/index.js`.
56
+ - Optional ZeyOS module palette at `@zeyos/zx/styles/zeyos.css`.
57
+ - Explicit legacy storage migration with `storage(namespace).migrateLegacy(['known-key'])`.
58
+ - **`Select.locale()`** and **`Select.country()`** — Select presets over a list of locales or ISO 3166-1
59
+ countries, named by `Intl.DisplayNames` with no translation table. A locale shows its native name
60
+ with the interface's name beneath; the value is the canonical BCP 47 tag or the upper-case
61
+ alpha-2 code. Both take `preferred` choices pinned above the list, `displayLocale`, and a `flags`
62
+ mode, and return ordinary Select instances. `Select.localeItems()` and `Select.countryItems()`
63
+ expose the item builders, and `canonicalLocale()` normalizes locale tags. Field type `zxselect`
64
+ supports `preset: 'locale'` or `'country'`.
65
+ - **Locales guide** — adding languages and message keys, positional and named variables, plural
66
+ forms, regional formatting, and switching language at runtime. Its live example switches between
67
+ English, German and a custom French catalogue, with editable variables and counts.
68
+ - **`flag()`** — draws a country flag as the platform's emoji, a muted code chip where the platform
69
+ has no flag glyphs, or an image from a flag set the application serves (`src: '/flags/{code}.svg'`).
70
+ `flagEmoji()`, `supportsFlagEmoji()` and `COUNTRY_CODES` go with it.
71
+ - **Surface** — an agent composes an answer or a dialog as JSON, whole or streamed, and Zx validates
72
+ and draws it with library components: `show`, `ask`, `choose`, `confirm`, `review` and
73
+ `questionnaire` intents, tables, charts, conditional fields and a review of proposed changes.
74
+ Model output is data, never code or markup. No URL from a model is loaded. The application's
75
+ `policy()` decides how each action is confirmed, and nothing in a surface can lower that. Every
76
+ surface ends in exactly one reply, which carries the application's `token`, and stays as a
77
+ read-only receipt. `openSurface()`, `elicit()` and `surfaceText()` go with it, and AgentThread
78
+ draws `surface` items (`thread.surface(id)`, the `reply` event).
79
+ - **`narrowCatalog()`, `surfaceSchema()`, `surfaceTools()` and `surfacePrompt()`** — generate a
80
+ model's prompt, schema and tool definitions at runtime, from all of the catalog or a narrowed
81
+ part of it. `catalog.js` imports without a DOM, so a server can use it. Model output reaches a
82
+ surface as operation lines, as a tool call's arguments, or in a fence in the answer text, split
83
+ out by `inlineSplitter()`.
84
+ - **`connectAgUi(thread, options)`** and `AG_UI_VERSION` — draw an AG-UI 1.0 event stream in an
85
+ AgentThread: run status, answers, trace steps, approvals, the application's own tiles, surfaces
86
+ and JSON Patch state, with reasoning kept private. The application keeps the transport.
87
+ - **`elicitationHandler()`** and `MCP_ELICITATION_VERSION` — MCP elicitation 2026-07-28, also
88
+ accepting 2025-11-25. Form mode goes through `elicit()`; URL mode asks first, naming the host.
89
+ - **Questionnaire** `when`, `next` and `validate` accept plain-JSON forms beside functions:
90
+ conditions with `all`, `any` and `not`, first-match `next` with `$review` and `$submit`, and rule
91
+ lists.
92
+ - **AgentThread** `upsert(item, {after})` places a new item after another.
93
+ - **Custom elements for the agent kit and the data views** — `<zx-agent-thread>`,
94
+ `<zx-composer>`, `<zx-block-view>`, `<zx-run-trace>`, `<zx-approval-card>`, `<zx-source-list>`,
95
+ `<zx-run-status>`, `<zx-card-view>`, `<zx-kanban-view>`, `<zx-tree>` and `<zx-chart>`. Data options
96
+ are properties and are never written back to attributes; methods are forwarded to the component,
97
+ and calls made before it exists are queued; events reach the host under their plain names as well
98
+ as `zx-<type>`.
99
+ - **`connectUiMessageStream(thread, options)`** and `UI_MESSAGE_STREAM_VERSION` — draw an AI SDK UI
100
+ message stream (`v1`) in an AgentThread: text, private reasoning, tool steps, approvals, sources,
101
+ files, data parts and application tiles. The application keeps the transport. `replay(messageId)`
102
+ rebuilds a response fed again after a reconnect, so its text is not doubled.
103
+ - **PromptStarters** — conversation starters for an empty conversation, with `items`, `label`,
104
+ `columns`, `headingLevel`, `setItems()` and a `pick` event. A pick is reported and never sent.
105
+ - **Queued messages in Composer** — `queue` and `queueLimit`, `getQueue()`, `clearQueue()`,
106
+ `removeQueued(id)`, and `queue` and `dequeue` events. A queued message goes out as a normal `send`
107
+ with `queued: true`, one each time busy ends.
108
+ - **Table `virtual: true`** — windowed rendering: only the rows in view and one viewport of overscan
109
+ above and below are in the DOM, and the table stays one grid over all its rows. Off by default.
110
+ `reveal(id)` scrolls a row into view, drawing it first in a windowed table.
111
+ - **`zx-css`** — `npx zx-css select table --out public/zx.css` writes one stylesheet with the core
112
+ sheet and everything those components reach, in `zx.css` order, with `--min`, `--layer` and
113
+ `--list`.
114
+ - **`zx.core.css` and `zx.layered.css`** — the core sheet on its own, and an opt-in build with the
115
+ whole library in `@layer zx`, so unlayered application rules win. `./src/components/*.css` exports
116
+ one component's own rules.
117
+ - **`@zeyos/zx/locales/de.js`** — a complete German message catalogue, installed with
118
+ `setTranslator((key) => de[key])` and `setLanguage('de')`. A test keeps it complete, and the
119
+ reference lists its glossary.
120
+
121
+ ### Changed
122
+
123
+ - Storage keys use length-prefixed namespaces, preventing collisions when names contain colons.
124
+ Built-in persisted components migrate known legacy keys once, preserving the originals. Applications
125
+ using `storage()` directly should call `migrateLegacy()` for their own known keys before reading.
126
+ - Generic stylesheets exclude the ZeyOS module palette; import `styles/zeyos.css` to retain those colours.
127
+ - Locale-aware formatting preserves regional English conventions and follows a usable explicit locale,
128
+ then the active language, then English. Explicit date locales take precedence over host date names.
129
+ - Built-in counts and ZeyOS control defaults use the message catalogue. Caller and server labels remain
130
+ unchanged. Short date names use locale abbreviations unless explicitly translated.
131
+ - The package includes the Surface guide and catalogue; documented ESM entries preserve field-adapter
132
+ registration when bundled with tree-shaking. Development tools are pinned to the lockfile versions.
133
+ - The documentation's ZeyOS client asset has a reproducible build command and a verified source manifest.
134
+ - Component documentation explains host-provided integrations: Chart needs a rendering adapter
135
+ (`ChartJsAdapter` uses Chart.js), Font Awesome modes need their icon assets, and ZeyOS data
136
+ bindings need a compatible client. The library has no runtime package dependencies.
137
+ - Theme Studio groups specimens into named sections, with a responsive grid, sticky section
138
+ navigation and colour swatches grouped by semantic role. Website navigation adds icons for
139
+ Docs, Layouts and Theme Studio.
140
+ - Composer mention suggestions use the floating overlay material, including glass and
141
+ forced-colour treatment where supported.
142
+ - The `agent-chat` layout includes an interactive credit-note question built with Surface and
143
+ uses the submitted values in the answer.
144
+ - The `ai-chat` layout's empty state uses PromptStarters, and focus moves to the composer after a
145
+ pick.
146
+ - The library's remaining text, in Select, Table, Datebox, Filter and the rest, now goes through the
147
+ message catalogue, so a translator reaches it. English remains the fallback, with singular and
148
+ plural forms selected from explicit counts.
149
+ - Month and weekday names, and dates in Calendar, ActivityItem, AgentThread and Surface, follow
150
+ `setLanguage()`. With no language set, nothing changes.
151
+ - Text options whose default moved to the catalogue no longer hold that English text, so
152
+ `component.options.label`, `treeEl.label` and `chartEl.emptyText` read `null` or `undefined` until
153
+ set. Read the text with `component.msg('tree.label')`.
154
+ - `null` in a text option that used to print the word "null" now shows nothing.
155
+ - PageUp, PageDown and Ctrl+Home/End inside a control in a thread item stay with the control.
156
+ - An answer finishing no longer drowns out "needs your approval" or "needs your answer".
157
+
158
+ ### Removed
159
+
160
+ - The `filter.choosePart` message, so a host override of it stops applying. Use
161
+ `filter.choosePart.field`, `.operator` and `.value`.
162
+
163
+ ### Fixed
164
+
165
+ - Country Select presets search custom descriptions. Blurring an unchanged Datebox preserves hidden time fields
166
+ and emits no change. Disabled AppSidebar items remain inert under keyboard activation.
167
+ - Empty focus traps focus their boundary and restore its attributes on release. AgentThread follows its
168
+ current scroll container after reparenting and releases listeners from the previous one.
169
+ - AG-UI durations are omitted when event timestamps use different clocks or move backwards.
170
+ - Filter empty-state markup and Select reset, spinner, disabled and overlay styling follow semantic
171
+ tokens and logical layout. CSS checks cover SVG data-URL paint and shared layout styles.
172
+ - Questionnaire ignores stale asynchronous validation, validates the final answer once, refreshes
173
+ replaced field definitions, and includes earlier applicable answers in native form data.
174
+ - Slider number-box commits, locale-aware NumberField stepping, normalized FilterPanel values,
175
+ Select typing and async item replacement, locale extension labels, and nested Datebox dismissal.
176
+ - NumberField preserves localized digits and minus signs while editing and committing grouped values.
177
+ - Persistent messages retain their duration. Tabbox restores a tab stop; MenuButton preserves Tab
178
+ navigation; Breadcrumb overflow keeps links and cancellation; ContextMenu restores invoking focus.
179
+ - Launcher ignores stale close events, Dock restores lazy content and destroys hosted sheets,
180
+ SheetStack raises native dialogs correctly, Dialog respects IME composition, and Tooltip remains
181
+ visible while the pointer moves onto its bubble.
182
+ - Calendar positions events by local clock time on daylight-saving transitions, retains keyboard
183
+ focus across periods, and rejects invalid resize steps. CodeEditor indentation participates in
184
+ native undo where supported and commits once on blur.
185
+ - Tree and Finder ignore stale lazy loads after replacement or destruction. Kanban recomputes its
186
+ drop target during stationary-pointer auto-scroll and on release.
187
+ - Http honors cancellation and multipart names, distinguishes timeouts, and accepts legacy
188
+ false-valued success envelopes. FieldUpload with Http retains upload progress and client defaults.
189
+ - AgentThread metadata patches preserve streamed blocks. The DOM builder rejects raw HTML sinks
190
+ and unsafe links; roving focus releases removed nodes, and repeated-letter typeahead cycles.
191
+ - Landing-page modules and styles load from the same asset revision.
192
+ - ZeyOS views can opt into `savedViewFallback: 'baseline'` to browse records when the saved-view
193
+ registry cannot be read, preserving the document and reporting the failure until recovery.
194
+ - `printf()` fills every placeholder in one pass, so a value holding `%word%` stays as written.
195
+ - `AgentThread.remove()` gives the next item its byline back when it now starts a turn, and moves
196
+ focus to a neighbour when the removed item held it.
197
+ - A destroyed AgentThread takes no more items.
198
+
11
199
  ## 5.6.0 — 2026-11-03
12
200
 
13
201
  Agents: a conversation with AI agents drawn from plain JSON — streamed answers, the steps a run
package/README.md CHANGED
@@ -44,9 +44,9 @@ Import a component source module directly when a bundler needs the narrowest pos
44
44
  import { Slider } from '@zeyos/zx/src/components/slider/slider.js';
45
45
  ```
46
46
 
47
- The package also exposes the bundled ESM entry for ordinary named imports. Load the complete
48
- stylesheet either way: it contains the shared tokens and cross-component states that make the
49
- system coherent, while JavaScript can still be tree-shaken or imported component by component.
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.
50
50
 
51
51
  TypeScript definitions ship with the package. They are generated from the JSDoc that documents
52
52
  every option, method, and event, so `new Slider(null, { … })` is checked against `SliderOptions`
@@ -57,6 +57,18 @@ Components accept an existing element or selector as their first argument. Passi
57
57
  the component create and own its root. Call `destroy()` when a component is no longer needed; an
58
58
  owned root is removed, while an enhanced target is restored.
59
59
 
60
+ ## Optional integration requirements
61
+
62
+ 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.
67
+ Core icons use bundled SVG by default. Opting into Font Awesome requires host-loaded CSS or a kit.
68
+ ZeyOS `moduleIcon()`, `moduleChip()`, and `zeyosAppIcon()` default to glyphs from the external custom
69
+ ZeyOS Font Awesome kit; `standard: true` still needs stock Font Awesome assets. `ZeyOS.connect()`
70
+ requires an injected compatible client and never imports the client package.
71
+
60
72
  ## Component index
61
73
 
62
74
  The groups match the demo sidebar.
@@ -100,7 +112,7 @@ ZeyOS binding — see `src/zeyos/modules.js`.
100
112
  | `CheckButton` | Two-state pressed button with optional state-specific labels. |
101
113
  | `Toggle` | Native-button switch with a separate submitted value. |
102
114
  | `Search` | Search input with debounced input, submit, and clear events. |
103
- | `Select` | APG combobox with local or async filtering, pinned items, priority/status/permission presets, and an optional ZeyOS entity picker. |
115
+ | `Select` | APG combobox with local or async filtering, pinned items, locale/country/priority/status/permission presets, and an optional ZeyOS entity picker. `Select.locale()` and `Select.country()` return ordinary Select instances; `Select.localeItems()` and `Select.countryItems()` generate rows without DOM. |
104
116
  | `Checklist` | Searchable checkbox group with optional async loading. |
105
117
  | `TagPicker` | Multi-select combobox that keeps its selection as removable tags. |
106
118
  | `NumberField` | APG spinbutton with step buttons, ranges, units, and wrapping. |
@@ -126,6 +138,7 @@ ZeyOS binding — see `src/zeyos/modules.js`.
126
138
  | `Dropdown` | Generic anchored popover with placement fallback. |
127
139
  | `MenuButton` | APG menu button built on `Dropdown`. |
128
140
  | `ContextMenu` | APG right-click menu for a region or, via `selector`, per row. |
141
+ | `Sheet` | Dockable panel that can float as a modal or nonmodal dialog. |
129
142
  | `Tooltip`, `tooltip()`, `describe()` | Hover/focus description bubble anchored with `position()`. |
130
143
 
131
144
  ### Data
@@ -136,14 +149,18 @@ ZeyOS binding — see `src/zeyos/modules.js`.
136
149
  | `FileItem`, `FileList` | Durable and transient file presentation with MIME/size metadata, status, progress, downloads, and collection states. |
137
150
  | `ActivityItem`, `ActivityList` | Chronological activity entries and grouped collections with actor, time, attachment, action, loading, and empty slots. |
138
151
  | `Table` | Sortable/selectable table with typed transaction columns, flat-data hierarchy/treegrid projection, and opt-in cell/row editing. |
152
+ | `RecordView` | Shared record collection state for table, card, and Kanban views. |
139
153
  | `TableView` | Record-oriented Table composition with shared fields, portable state, column visibility/order, sorting, and selection. |
140
154
  | `CardView` | Responsive record cards with configurable fields, safe preview media, grouping, actions, sorting, and selection. |
141
155
  | `KanbanView` | Record board with configurable columns, swim lanes, WIP guidance, and cancelable pointer/keyboard movement. |
142
156
  | `Grid`, `Grid.BillingItems()` | Table-compatible preset surface with editable currencies, units, totals, and sub-items. |
143
- | `Chart`, `ChartJsAdapter` | Accessible engine-neutral chart host and explicitly injected Chart.js adapter. |
157
+ | `Chart`, `ChartJsAdapter` | Accessible chart host requiring an injected renderer; the supplied adapter requires host-provided Chart.js 4. |
144
158
  | `Calendar` | Agenda/day/week/month/year scheduling with timed collisions, spanning events, range selection, and configurable optimistic drag/resize editing. |
159
+ | `Filter` | Nested, backend-neutral filter expression editor. |
145
160
  | `DataFilter` | Declarative select, text, and custom filters for client-side row sets. |
146
161
  | `FilterPanel` | Typed filter form built from a server's own field metadata, drafted then applied. |
162
+ | `SortControl` | Searchable sort field and direction control. |
163
+ | `ViewSettings` | Portable field visibility, order, grouping, and view settings. |
147
164
  | `ListToolbar` | Search, result count, view switch, and badged tools above a record view. |
148
165
  | `TreeView` | APG tree with lazy children, filtering, tri-state checkboxes, and hover-revealed `rowActions`. |
149
166
  | `Finder` | Miller-columns hierarchy browser with an optional preview pane. |
@@ -181,6 +198,8 @@ ZeyOS binding — see `src/zeyos/modules.js`.
181
198
  | `AppSidebar` | Expanded or minimized vertical application navigation plus horizontal rails; descendants are inline only while expanded. Sections group a tree; `layout: 'modules'` puts a module strip beside one module's menu. |
182
199
  | `ModuleBar` | Colour-coded module tiles in a strip or bar: flyout menus, live badges, one Tab stop, and an "All modules" catalogue for what does not fit. |
183
200
  | `Toolbar` | APG toolbar: one tab stop, arrow-key movement, and overflow into a menu. |
201
+ | `Dock` | Resizable, collapsible pane layout with tabs and hosted Sheets. |
202
+ | `WorkspaceSwitcher` | Workspace identity and switching menu. |
184
203
  | `SplitView` | Resizable two-pane split with a keyboard-operable separator. |
185
204
  | `Stepper` | Linear multi-step progress with completed, active, and error states. |
186
205
  | `Breadcrumb` | Hierarchy trail with middle-collapse, pairing with `Finder` and `TreeView`. |
@@ -192,6 +211,23 @@ ZeyOS binding — see `src/zeyos/modules.js`.
192
211
  | `skeleton()`, `skeletonText()`, `skeletonTable()` | Placeholders shaped like the content that is coming. |
193
212
  | `truncate()` | Clamps text to a number of lines, with the full value on hover. |
194
213
 
214
+ ### Agents
215
+
216
+ | API | Description |
217
+ | --- | --- |
218
+ | `AgentThread` | Accessible conversation feed with streamed answers, versions, and actions. |
219
+ | `BlockView`, `renderBlocks()` | Safe structured answer content with incremental streaming. |
220
+ | `Composer` | Message input with attachments, mentions, commands, context, and queued messages. |
221
+ | `RunTrace` | Tool calls, reasoning summaries, retries, and handoffs within a run. |
222
+ | `RunStatus` | Run state, steps, elapsed work, tokens, and cost. |
223
+ | `ApprovalCard` | Application-controlled approval, editing, rejection, and typed confirmation. |
224
+ | `SourceList` | Citations and source metadata without loading remote content. |
225
+ | `PromptStarters` | Suggested conversation starters that report a selection. |
226
+ | `Surface` | Validated agent-authored forms, tables, choices, and reviews with one reply. |
227
+
228
+ See the [Surface guide](docs/agent-surfaces.md) and [component catalogue](docs/agent-catalog.json)
229
+ for supported schemas and streaming helpers. Both ship in the package.
230
+
195
231
  ## Start from a layout
196
232
 
197
233
  The [layout gallery](https://zx.zeyos.com/layouts) holds complete, working screens on one shared
@@ -372,7 +408,7 @@ JavaScript positioning fallback.
372
408
  Install the development toolchain and start the no-build demo server:
373
409
 
374
410
  ```sh
375
- npm install
411
+ npm ci
376
412
  npm run serve
377
413
  ```
378
414
 
@@ -389,6 +425,15 @@ npm run build:site # assembles the deployable documentation site into site/
389
425
  npm run serve:site # serves site/ exactly as it will be deployed
390
426
  ```
391
427
 
428
+ Browser checks use an already-installed Chrome. Set `ZX_BROWSER_CHANNEL` to another installed
429
+ Playwright browser channel, or `ZX_BROWSER_EXECUTABLE_PATH` to an executable path; use one option
430
+ at a time. No browser is downloaded by the checks.
431
+
432
+ The checked-in ZeyOS client asset has a source and checksum manifest. To refresh it from a local
433
+ client checkout, run `node tools/build-client-vendor.js --source /path/to/client`; verify it with
434
+ `node tools/build-client-vendor.js --check`. Ordinary site builds verify the asset without needing
435
+ that checkout or a network connection.
436
+
392
437
  ## Installing
393
438
 
394
439
  ```sh
@@ -400,7 +445,28 @@ import { Table, Message } from '@zeyos/zx';
400
445
  import '@zeyos/zx/zx.css';
401
446
  ```
402
447
 
448
+ `zx.css` is the whole library. To load only what an application uses, `zx-css` writes one stylesheet
449
+ for the components named: the tokens and base rules, then those components and everything they
450
+ depend on, resolved from the source.
451
+
452
+ ```sh
453
+ npx zx-css select table --out public/zx.css --min
454
+ npx zx-css select table --list # the files it contains, in order
455
+ ```
456
+
403
457
  Additional entry points: `@zeyos/zx/zeyos` (the schema-driven ZeyOS binding) and
404
- `@zeyos/zx/global` for classic script tags.
458
+ `@zeyos/zx/global` for classic script tags. For styles, `@zeyos/zx/zx.core.css` is the tokens, base
459
+ rules, icons and reading type, `@zeyos/zx/src/components/select/select.css` is one component's own
460
+ rules, and `@zeyos/zx/zx.layered.css` puts the whole library in `@layer zx`, so that unlayered
461
+ application rules win without a specificity fight, and so do unlayered resets and third-party
462
+ stylesheets: `docs/llms.md` covers when to choose it.
463
+
464
+ ZeyOS module colours are optional: import `@zeyos/zx/styles/zeyos.css` when using the ZeyOS binding.
465
+ The generic core and full-library stylesheets do not include that product palette.
466
+
467
+ The [Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales) covers the shipped
468
+ English/German catalogues, adding application languages and regional variants, custom messages and
469
+ variables, plural forms, formatting, and runtime language switching. `Select.locale()` and `Select.country()`
470
+ return ordinary Select instances; selecting a locale is separate from installing its translations.
405
471
 
406
472
  Documentation lives at <https://zx.zeyos.com>.