@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,45 @@
1
+ # FilterPanel — typed filters from server metadata
2
+
3
+ The filter form a data-driven list needs: field metadata in, a query object out.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/filter-panel · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ The third filter component, and the one a data-driven application reaches for. `DataFilter`
8
+ filters a client-side row set; `Filter` builds a backend-neutral AST with groups and operators.
9
+ `FilterPanel` takes the `{key: {type, label, options, min, max}}` map a list endpoint already
10
+ publishes and gives back a query object — so the shape the server describes is the shape the
11
+ form renders, with no per-application translation layer in between.
12
+
13
+ - **Options** — `fields: Record<string, {type, label?, options?, min?, max?, step?, search?}>`,
14
+ `order` (display order; omitted uses object order), `value` (the applied filters, drafted
15
+ from), `mode: 'draft'|'live'`, `serialize: 'seconds'|'ms'|'iso'|(date, edge) => unknown`,
16
+ `timeZone` (IANA zone the days are counted in; null = the runtime's own), `emptyText`, `msg`.
17
+ - **Types** — `text`, `select`, `date`, `date:range`, `int`, `float`, `number`, and
18
+ `int:range` / `float:range` / `number:range`. An unrecognised type renders a visible,
19
+ labelled placeholder naming it and is excluded from the value — never dropped silently.
20
+ - **Methods** — `getValue()`, `setValue()`, `apply()`, `reset()`, `clear()`.
21
+ - **Events** — `apply {value}`, `change {value, field}`. Values read back from typed controls
22
+ include their normalization, such as integer rounding and numeric bounds.
23
+
24
+ Five behaviours are deliberate rather than incidental:
25
+
26
+ - **A select is multi-valued.** "Open or waiting" is the common request, and single choice turns
27
+ it into two visits. It composes `Checklist`, which brings its own search past eight options,
28
+ and the group is named after the filter rather than after the component.
29
+ - **Each end of a range carries its own accessible name.** One `<label for>` cannot name two
30
+ inputs, and a group label that names neither is worse than no group label.
31
+ - **`clear()` commits; `reset()` does not.** Clear is "no filters" and applies immediately —
32
+ emptying the controls while the list stays filtered is a panel that lies about what is on
33
+ screen. Reset restores the constructed value without committing, which is a host sheet's
34
+ Cancel.
35
+ - **An empty `fields` map is normal.** An instance that configures no filters for a settings
36
+ section is the ordinary case; the panel renders `emptyText`, never an error.
37
+ - **`0` is a value.** `''`, `null`, `[]` and `{from: null, to: null}` are not, and only active
38
+ constraints reach the emitted value.
39
+
40
+ `serialize` decides how a date leaves the component, because the answer is a wire-format
41
+ decision rather than an application one. A range's upper bound takes the **end** of its day, or
42
+ a one-day range matches nothing. `timeZone` decides *which* day: with the ZeyOS instance's zone
43
+ (`'Europe/Vienna'`), 15 January serializes from 23:00 UTC on the 14th wherever the browser is, and
44
+ an incoming Unix timestamp shows as the day it falls on there — the rule `zeyosForm()` and
45
+ `zeyosTable()` apply to date-only fields. An unknown zone throws a `RangeError`.
@@ -0,0 +1,47 @@
1
+ # Filter — dynamic backend-neutral expressions
2
+
3
+ A backend-neutral, nested filter authoring component.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/filter · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ An authoring component for typed, nested filter expressions. It never evaluates application data
8
+ or interpolates query text: it emits a versioned, JSON-safe AST for an allowlisted application
9
+ adapter to compile into its own backend query language.
10
+
11
+ - **AST** — `{version: 1, root: {kind:'group', id, logic:'and'|'or', children}}`; children are
12
+ stable-ID groups or `{kind:'condition', id, field, operator, value}` records. Unknown field or
13
+ operator IDs survive parsing and render as unavailable/invalid instead of being silently lost.
14
+ - **Fields** — `{id,label,type,operators?,defaultOperator?,choices?,loadChoices?,editor?,minQuery?,
15
+ debounce?}`. Built-in types cover text, number/money, date/datetime, boolean, enum/status/
16
+ priority/country/currency/unit/entity, and tags. Compatible operators and their arity come from
17
+ the exported `filterOperators` matrix; applications may explicitly override/add operator IDs. The
18
+ labels in that matrix are English data. `Filter` shows a built-in operator through its
19
+ `filter.op.<id>` message, and an operator the `operators` option supplies through its own `label`.
20
+ - **Relative dates** — `withinLast` and `withinNext` take a span, not two dates: the editor is a
21
+ whole-number amount and a unit select, and the value is the pair `[amount, unit]` with `unit` one
22
+ of `RELATIVE_DATE_UNITS` (`'days'|'weeks'|'months'`), e.g. `[7, 'days']`. `validate()` requires a
23
+ positive whole amount and a known unit; `relativeDateValueError(value)` is the same check for an
24
+ adapter. A value that is not such a pair (two dates) shows as an empty amount.
25
+ - **Options** — `fields`, `value`, `operators`, `allowGroups: true`, `maxDepth: 3`,
26
+ `maxConditions: 50`, `autoApply: false`, `readonly`, `disabled`, `applyLabel`, `clearLabel`,
27
+ `searchable: false`, `layout: 'standard'|'compact'`, `rootLogic: null|'and'|'or'`,
28
+ `showApply: true`, `showRootActions: true`.
29
+ - **Searchable conditions** — opt in to local-search `Select` controls for fields, operators and
30
+ static single-choice/boolean values. Uncommitted search text never becomes a condition value.
31
+ Multi-choice, async and custom editors retain their existing contracts. Compact rows keep field,
32
+ operator, value and removal together, wrapping the value below on narrow containers.
33
+ - **Embedding** — hide internal Apply and duplicate root Add controls when the parent drawer owns
34
+ submission. `rootLogic` fixes the authored root logic; incompatible saved expressions remain
35
+ visible and invalid until corrected, never silently rewritten. Removing the last condition
36
+ returns keyboard focus to Add filter.
37
+ - **Methods** — `getValue()`, atomic `setValue()`, `addCondition()`, `addGroup()`, `update()`,
38
+ `remove()`, `move()`, `validate()`, `apply()`, `clear()`, `focus()`, `setReadonly()`,
39
+ `enable()`/`disable()`.
40
+ - **Events** — `change {value,valid,errors,reason,nodeId}`, `apply {value}`, `invalid {errors}`,
41
+ and abortable async-choice lifecycle `query`, `loaded`, `error`. `apply()` returns null and
42
+ focuses the first invalid condition when validation fails.
43
+ - **Pure exports** — `emptyFilterAst`, `filterCondition`, `filterGroup`, `parseFilterAst`,
44
+ `cloneFilterAst`, `cloneFilterValue`, `stringifyFilterAst`, and `validateFilterAst`.
45
+ - **Boundary** — keep the AST in saved views/audit state and compile it in a backend-specific
46
+ adapter with an allowlist and bound parameters. Do not put SQL, URL query fragments, functions,
47
+ DOM nodes, Dates, non-finite numbers, or other executable/non-JSON values into conditions.
@@ -0,0 +1,25 @@
1
+ # Finder
2
+
3
+ A Miller-columns browser: every column lists the children of the row picked to its left, the way a file browser’s column view works.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/finder · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Miller-columns hierarchy browser: each column lists the children of the row selected in the column
8
+ to its left, like the macOS Finder's column view. The columns are linked listboxes sharing **one**
9
+ tab stop. The constructor applies `path` silently, so read `getNodes()` for the first paint of any
10
+ breadcrumb.
11
+
12
+ - **Options** — `items` (the same nested shape as `TreeView`), `valueKey`, `labelKey`,
13
+ `childrenKey`, `path: []` (initial selection, root first), `load: (node)=>Promise<children>`,
14
+ `preview: (node)=>Node|null` (renders a pane after the last column for a selected leaf),
15
+ `rootLabel`, `columnWidth: 220`, `height: 320`, `icons: true`, `renderItem`, `emptyText` (unset, the
16
+ `finder.noItems` message; `null` shows no text).
17
+ - **Methods** — `getPath()`, `getNodes()`, `getSelection()`, `setPath(ids, {silent, focus})`
18
+ (async — loads every branch along the way), `reveal(id)`, `setItems()`, `focus()`.
19
+ - **Events** — `change {path, nodes, node}`, `activate {node, id}`.
20
+ - **Keyboard** — ↑/↓ move within the active column, → steps into the selected branch and lands on
21
+ its first row, ← returns to the parent column and truncates the path, Home/End, Enter opens a
22
+ leaf, typing jumps to the next match.
23
+ - **Appearance** — the selected row of each column is the path you are on: the neutral
24
+ `--zx-color-bg-current` fill, the text colour and a semibold label, with subtle icons and
25
+ column dividers.
@@ -0,0 +1,42 @@
1
+ # Field widget types
2
+
3
+ The field types backed by a whole Zx component rather than a native input — what turns a Form into a real record editor.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/form-widgets · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Beyond the built-in field types, these widget types wrap whole components, used as
8
+ `{ type, label, props: {…component options…} }`. They are registered by
9
+ `registerFieldAdapters()`, which `src/index.js` calls by default.
10
+
11
+ - `zxselect` (Select), `checklist` (Checklist), `tagpicker` (TagPicker), `number` (NumberField),
12
+ `rating` (Rating), `slider` (Slider).
13
+ - `date`/`month`/`datetime` (Datebox/MonthPicker — pass a `Date` value), `daterange`
14
+ (DateRangeBox — a `{start, end}` value), `time` (Timebox).
15
+ - `valuelist` (ValueList), `multivalueeditor` (MultiValueEditor), `upload` (FieldUpload),
16
+ `toggle` (Toggle), `code` (CodeEditor).
17
+
18
+ **Stylesheet names for `zx-css`.** A field type is registered at run time, so `zx-css` cannot
19
+ follow it from `form` to the component that draws it: name that component's stylesheet beside
20
+ `form`. Each line is field type — component — the name to pass, and the stylesheets that name
21
+ depends on come with it.
22
+
23
+ - `zxselect` — Select — `select`
24
+ - `checklist` — Checklist — `checklist`
25
+ - `tagpicker` — TagPicker — `tag-picker`
26
+ - `number` — NumberField — `number-field`
27
+ - `rating` — Rating — `rating`
28
+ - `slider` — Slider — `slider`
29
+ - `date` — Datebox — `datebox`
30
+ - `datetime` — DateTimeBox — `datebox`
31
+ - `month` — MonthPicker — `date-picker`
32
+ - `daterange` — DateRangeBox — `date-range-box`
33
+ - `time` — Timebox — `timebox`
34
+ - `valuelist` — ValueList — `value-list`
35
+ - `multivalueeditor` — MultiValueEditor — `multi-value-editor`
36
+ - `upload` — FieldUpload — `field-upload`
37
+ - `toggle` — Toggle — `toggle`
38
+ - `code` — CodeEditor — `code-editor`
39
+
40
+ The built-in types — `text`, `password`, `textarea`, `checkbox`, `int`, `float`, `select`,
41
+ `optionlist`, `hidden`, `html`, `custom` — are drawn by Field itself and need `form` alone. A form
42
+ with a Select and a date field is `npx zx-css form select datebox --out public/zx.css`.
@@ -0,0 +1,80 @@
1
+ # Form / Fieldset / Field
2
+
3
+ Fieldsets of typed fields with one values object in and out — the schema-shaped way to build a record editor.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/form · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ ## Form
8
+
9
+ - **Options** — `fieldsets: []`, `actions: [button descriptors]`, `novalidate: true`,
10
+ `idPrefix: null` (handed to the fieldsets it builds; a fieldset's own wins).
11
+ - **Methods** (proxied across the fieldsets) — `getValues()`, `setValues()`, `getField()`,
12
+ `setValue()`, `getValue()`, `reset()`, `setHighlights()`, `clearHighlights()`, `addFieldset()`,
13
+ `setActions()`, `submit()`.
14
+ - **Events** — `submit {values}` (preventable; required/int/float validation runs first),
15
+ `invalid {errors}`, `change {id, value}`.
16
+
17
+ ## Fieldset
18
+
19
+ - **Options** — `title` (the legend: a quiet sentence-case caption, small, medium weight, muted —
20
+ the fields are the content), `columns: 1|2|3`, `fields: { id: Field-options }`,
21
+ `idPrefix: null`.
22
+ - **Keys and ids** — a field key names the value, not an element: it is the field's `name` (and
23
+ a native control's `name`) and its `data-field-id`, never a DOM id by itself. Control ids are
24
+ `<idPrefix>-<key>`, with a prefix generated per instance unless `idPrefix` is given, so a form
25
+ mounted twice repeats no id and a field `stage` never collides with a `#stage` elsewhere; the
26
+ label, description, and message ids derive from it (`<id>-label`). Radio groups are named after
27
+ the control id. An `id` in the field options that differs from the key is used as given.
28
+ - **Methods** — `addField(id, opts|Field|element|component)`, `getField`/`hasField`/`getFields`,
29
+ `getValues`/`setValues`/`getValue`/`setValue`, `reset`, `clear`, `focus(id)`,
30
+ `setHighlights`/`clearHighlights`.
31
+ - **Adopting a component** — `addField(id, component)` wraps any component (or element) that is
32
+ not a registered field type and drives it through its own API. Values: `getValue`/`setValue`,
33
+ `get`/`set`, `getValues`/`setValues`, `isChecked`/`setChecked`, or a `value` property, tried in
34
+ that order (a Toggle reads its on-value, as the `toggle` type does); an element is read through
35
+ `value`, or `checked` for a checkbox or radio. Disabled: `setDisabled(bool)`, then
36
+ `enable()`/`disable()`, then a `disabled` property; a plain wrapper gets `aria-disabled` and its
37
+ form controls disabled. Read-only: `setReadonly`/`setReadOnly` or the element's `readOnly`. The
38
+ component's own `change` becomes the field's `change`, once per edit. Writes keep the caller's
39
+ `silent`: `setValues(values)` lets the component emit its own `change` to its own listeners and
40
+ the field emit one `change`; `setValues(values, {silent: true})` and `reset()` stay quiet.
41
+ Removing the field puts the component back, unsubscribes from it, and undoes the disabled and
42
+ read-only state the field set.
43
+
44
+ ## Field
45
+
46
+ - **Options** — `id` (the control's DOM id; generated when omitted), `name` (the field name and
47
+ native control `name`; defaults to `id` on a standalone field), `type: 'text'`, `label`,
48
+ `description`, `value`, `placeholder`, `required`, `disabled`, `readonly` (shown and focusable,
49
+ not editable; ignored by types whose control has no read-only state, such as `checkbox`,
50
+ `select`, `zxselect`, `date`, `time`), `options`, `layout: 'stack'|'inline'`, `props: {}`.
51
+ - **Properties** — `controlId` (the control's DOM id), `name`.
52
+ - **Built-in types** — `text`, `password`, `textarea`, `checkbox`, `int`, `float`, `select`,
53
+ `optionlist`, `hidden`, `html` (display content as text: no input frame, a control's height,
54
+ inset like the values around it in a quiet form).
55
+ - **Methods** — `getValue`/`setValue`, `focus`, `reset`, `setDisabled`, `setReadonly`,
56
+ `setHighlight(msg, kind)`, `clearHighlight`, `getInput`, `own(child)`, plus the statics
57
+ `Field.register(type, adapter)` and `Field.has(type)`.
58
+ - **Events** — `change {value}`, once per committed edit whatever the type (a typed value on
59
+ leaving the input, a slider on release, `code` when the editor loses focus after an edit);
60
+ `input {value}` for every keystroke or drag step from the types that tell the two apart
61
+ (`code`, `slider`); `invalid {message}`.
62
+ - **Adapters** — `Field.register(type, (field, options) => ({el, get, set, focus, setDisabled,
63
+ setReadonly?, destroy?, labelTarget?}))`. An adapter whose widget reports its own commits
64
+ forwards them with `field.emit('change', {value})` and stops the native `change` its inner
65
+ control bubbles (`field.listen(widget.el, 'change', (e) => e.stopImmediatePropagation())`), so
66
+ the Field does not report the same edit twice.
67
+ - **Labels** — small, medium weight, in the muted text colour: quieter than the values they name.
68
+ With `layout: 'inline'` the label lines up with the control's first line.
69
+
70
+ ## Quiet fields
71
+
72
+ Inside any element with `data-zx-fields="quiet"` — an inspector, a property list, an inline record
73
+ — fields read as values rather than a wall of boxes. Native inputs, selects and textareas, and the
74
+ composite controls (`Select`, `TagPicker`, `NumberField`, `Datebox`, `DateRangeBox`, `Timebox`)
75
+ show no border, fill, chevron, stepper or calendar button until hovered (the hover fill and the
76
+ affordances come back) and their full field chrome and focus ring while focused or open. A
77
+ NumberField's value starts where a quiet text input's text starts, and `html` display content is
78
+ inset to match. Disabled
79
+ and read-only controls never light up; an invalid Datebox keeps its danger border. It is a context
80
+ attribute, not an option: set it on the container.
@@ -0,0 +1,26 @@
1
+ # Grid and `Grid.BillingItems()`
2
+
3
+ A public Table specialization for domain presets; it inherits sorting, selection, hierarchy, typed formatting, and editing without forking them.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/grid · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ `Grid` is the public extension point for repeatable data-table presets. It subclasses `Table`
8
+ without forking its implementation, so sorting, selection, hierarchy, responsive stacking,
9
+ editable cells/rows, loading, events, and teardown keep the Table contract.
10
+
11
+ - **Constructor** — `new Grid(target, tableOptions)` accepts the complete `Table` API and defaults
12
+ editable cells to a single-click trigger. Pinned columns, header groups, `minWidth`,
13
+ `setExpanded()` and the rule that a click on a control inside a cell raises no `rowclick` are
14
+ Table's and apply unchanged.
15
+ - **Preset** — `Grid.BillingItems(target, options)` supplies an editable hierarchical billing
16
+ schema for item, quantity, unit, unit price, currency, and line total. It enables single-click
17
+ editing, hierarchy, row reorder handles, and the column visibility chooser. It returns a `Grid`.
18
+ - **Billing options** — `data`, `fields` key overrides, `units`, `currencies`, fallback `currency`,
19
+ `locale`, `decimals`, `columnOverrides`, complete `columns` replacement, `lineTotal(row, changes)`,
20
+ and `oneditcommit` in addition to ordinary Table options.
21
+ - **Rows** — default field names are `id`, `parent`, `kind`, `item`, `quantity`, `unit`,
22
+ `unitPrice`, `currency`, and `total`. `kind: 'group'|'subtotal'|'header'|'section'` is read-only;
23
+ other rows are editable. Parent references use Table's flat-data treegrid projection.
24
+ - **Calculation boundary** — the default line total is quantity × unit price. Applications own
25
+ taxes, discounts, rounding, subtotal/group recalculation, optimistic persistence, and server
26
+ validation; provide `lineTotal` or cancel `editcommit` when product policy differs.
@@ -0,0 +1,11 @@
1
+ # Groupbox
2
+
3
+ A collapsible section built on native `<details>`, so the keyboard and find-in-page behaviour comes from the platform.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/groupbox · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Collapsible titled section built on the native `<details>` element.
8
+
9
+ - **Options** — `title`, `open: true`.
10
+ - **Methods** — `open()`, `close()`, `toggle()`, `isOpen()`, `setTitle()`, `setContent()`.
11
+ - **Events** — `open`, `close`.
@@ -0,0 +1,359 @@
1
+ # Helper functions
2
+
3
+ The standalone function library that ships alongside the components: dates, formatting, escaping, small utilities, translation, and keyboard behaviours.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/helpers · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Standalone exports with no DOM ownership and no lifecycle, importable individually from the same
8
+ entry point as the components. See also the Kernel section for `Component`, `h`, `icon`, and
9
+ `position` — the substrate the components themselves are built on.
10
+
11
+ - **Dates** — `formatDate(date, fmt, {locale})`, `parseDate(str, fmt)` (returns `null` when the
12
+ string does not match, so it doubles as a validator), `clampDate(date, min, max)`,
13
+ `isSameDay(a, b)`, `addDays(date, n)`, `addMonths(date, n)`, `getWeekStart(lang?)` → `0` (Sunday)
14
+ or `1` (Monday). strftime-style tokens: `%d %m %Y %y %H %M %S %a %A %b %B %s`. Month and weekday
15
+ names come from `Intl` in a supported explicit `locale`, then `getLanguage()`, then English.
16
+ Regional English tags keep their own abbreviations and conventions. Explicit locale names take
17
+ precedence over host date-name translations; without an explicit locale those translations apply.
18
+ Short names use `Intl` unless a host supplies the corresponding short-name key.
19
+ - **Numbers, money and time** — `formatNumber(value, {locale, decimals, minDecimals, maxDecimals,
20
+ group=true})`, `formatCurrency(value, currency, {locale, decimals})`, `formatPercent(value,
21
+ {locale, decimals=0})` (takes a fraction, so `0.42` → `42%`), `formatFileSize(bytes, {locale,
22
+ decimals=1, standard='iec'})` (`'iec'` → KiB/MiB/GiB in steps of 1024, `'si'` → kB/MB/GB in steps
23
+ of 1000; `0` → `'0 B'`, trailing zeros dropped), `formatRelativeTime(date, {now=new Date(),
24
+ locale, numeric='auto'})` (picks the largest sensible unit from second to year; accepts a `Date`,
25
+ Unix seconds, or an ISO string). A supported explicit `locale` takes precedence over
26
+ `getLanguage()`, then English, so `setLanguage()` drives all five when no usable option is given.
27
+ Nothing throws: `null`, `undefined` and `NaN` all format as
28
+ `''`, an invalid currency code falls back to plain number formatting, and every `Intl` instance
29
+ is cached because tables call these once per cell.
30
+ - **Utilities** — `debounce(fn, ms)` (trailing edge, preserves `this`), `throttle(fn, ms,
31
+ {leading=true, trailing=true})` (its rate-limiting counterpart: runs at most once per interval
32
+ and replays the latest arguments on the trailing edge), `uid(prefix='zx')` (unique
33
+ per page load, safe as a DOM id), `deepMerge(a, b)` (never mutates either input; replaces arrays
34
+ rather than concatenating), `clamp(n, min, max)`, `toArray(value)` (null → `[]`, string → single
35
+ entry, iterable/array-like → array), `isElement(value)` (cross-realm safe).
36
+ - **Collections** — `groupBy(items, key)` → `Record<string, T[]>` ordered by first appearance;
37
+ `sortBy(items, ...keys)` returns a **new** array and never mutates its input, taking a property
38
+ name, a `'-name'` prefix or a `{key, dir}` object for descending, or an accessor function,
39
+ comparing digit runs numerically and always sorting `null`, `undefined` and `NaN` last in either
40
+ direction; `uniqueBy(items, key?)` keeps the first occurrence.
41
+ - **Escaping** — `h()` rejects `innerHTML`, `outerHTML`, and `srcdoc` properties regardless of
42
+ casing, and sanitizes `href` through `safeHref`. `htmlEscape(str)`, and `h.raw(html)` as the only
43
+ sanctioned `innerHTML` path, for
44
+ component-generated markup only. `escapeRegExp(value)` makes user input safe as a literal
45
+ pattern, and `highlightMatch(text, query, {className='zx-mark'})` → `DocumentFragment` wraps
46
+ every case-insensitive occurrence in a `<mark>` built from text nodes, with no `innerHTML`
47
+ involved — the pairing every filtering list wants.
48
+ - **Storage** — `storage(namespace, {area='local'})` → `{get, set, remove, keys, clear, migrateLegacy}`, a
49
+ namespaced JSON-encoded view of `localStorage` (or `sessionStorage` with `{area: 'session'}`).
50
+ Keys are written as `zx2:<namespace length>:<namespace>:<key>` (UTF-16 string length), so names
51
+ containing colons cannot overlap. `clear()` empties only its own namespace; `keys()` reports
52
+ namespace-relative names. To retain values from the earlier `zx:` format, call
53
+ `migrateLegacy(['known-key'])` before reading them. It copies only the exact keys you name, only
54
+ when they contain valid JSON and the current key is absent, and returns the names copied.
55
+ Legacy values are never deleted. Migration is recorded once per key, including missing keys;
56
+ removing or clearing a migrated value does not restore it on the next load. Invalid legacy JSON
57
+ remains retryable. Built-in persisted components migrate their own known keys automatically.
58
+ `get(key, fallback)` returns the fallback both for a missing key and for unparseable JSON, and
59
+ `set()` drops values JSON cannot represent rather than throwing. When the area is missing or
60
+ refuses a write — private browsing, a full quota, cookies disabled — the view degrades silently
61
+ to an in-memory map for the life of the page, so callers never need a `try`/`catch`.
62
+ - **Export** — `toCsv(rows, columns, {delimiter=',', header=true, newline='\r\n'})` serialises to
63
+ RFC 4180: fields containing the delimiter, a quote, CR or LF are quoted with inner quotes
64
+ doubled, `Date`s become ISO strings, `null`/`undefined` become empty fields, and text starting
65
+ with `=`, `+`, `-` or `@` is prefixed with a tab so spreadsheets treat it as text rather than a
66
+ formula (numbers are exempt, so negative amounts survive). `columns` accepts plain id strings or
67
+ `{id, label, value(row)}` descriptors. `downloadBlob(filename, data, {type})` saves through a
68
+ temporary object URL, prepending a UTF-8 BOM for `text/csv` so Excel reads it as UTF-8;
69
+ `copyToClipboard(text)` → `Promise<boolean>` uses the async Clipboard API and falls back to a
70
+ hidden textarea, never rejecting.
71
+ - **Translation** — `setTranslator(fn)`, `setLanguage(lang)`, `getLanguage()`,
72
+ `translate(key, args)`, `printf(str, args)` (`%1`, `%2`, … placeholders), `defaultMessages`.
73
+ Every component resolves its built-in strings through `msg()`, so one translator covers the
74
+ library: per-instance `msg` option → `setTranslator()` function → the component's built-in
75
+ defaults → the default English catalogue → the key. The translator answers one key at a time;
76
+ null, undefined, or the key itself means "not translated" and English shows, so an application
77
+ without a translator never sees a raw key. `defaultMessages` is that catalogue — copy it to
78
+ start a locale (`setTranslator((key) => de[key])`), or install the German one below.
79
+ `setLanguage()` also selects the language table of a `msg` option and drives locale-dependent
80
+ behaviour such as the first day of the week and the month and weekday names `formatDate()` writes.
81
+ `translatePlural(key, count, args, {locale}?)` and `component.msgPlural(key, count, ...args)`
82
+ select cardinal forms using `Intl.PluralRules`. Pass the finite numeric count separately from
83
+ display arguments: `translatePlural('items', 2, ['two'])`. At each message source, resolution
84
+ tries `items.<category>`, `items.other`, then `items` (including a legacy alias). Instance overrides
85
+ precede the host translator, inherited component messages, and English defaults. English fallback
86
+ selects its category using English rules. Existing unsuffixed overrides remain valid.
87
+ - **Keyboard** — `focusTrap(container)` → `{activate, deactivate}` confines Tab to a container;
88
+ an empty trap focuses its boundary, temporarily adding `tabindex="-1"` when needed and removing
89
+ it on deactivation. Deactivation restores the previous focus when it is still connected.
90
+ `rovingTabindex(container, itemSelector, {orientation, wrap, rtl: 'auto'})` → `{focusFirst,
91
+ focusLast, destroy}` keeps one tab stop in a group — horizontal arrows follow `dir="rtl"`, and a
92
+ text field, select, or contenteditable item keeps Home/End and its arrows (an arrow leaves a text
93
+ field only from the edge of its text); toggling a `<fieldset disabled>` around items inside the
94
+ container moves the tab stop off them. Removed items regain their original tabindex and are
95
+ released; reinserted items use their new baseline. `typeahead(getItems, onMatch)` →
96
+ `(event|string) => void` resolves buffered printable keystrokes to an item (500 ms buffer,
97
+ repeated-letter cycling).
98
+
99
+ ## Locales
100
+
101
+ [Open the Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales).
102
+
103
+ Its [live language-switching example](https://zx.zeyos.com/docs.html#getting-started/locales/try-language-switching)
104
+ offers English, German, and an application-owned French catalogue. Edit the name, record, and
105
+ count to try positional/named variables, plural forms, and number formatting. Switching preserves
106
+ the input values and recreates the translated Select. French intentionally omits `table.empty`
107
+ to demonstrate English fallback. The embedded example has its own language state, and its running
108
+ source and catalogues are available under Code.
109
+
110
+ ### Language, locale, and catalogue
111
+
112
+ Zx ships English and German interface messages. Other languages can be supplied by the application.
113
+ Locale tags such as `en-GB`, `de-AT`, and `fr-CA` describe language and regional conventions; adding a
114
+ tag to a picker does not install a translation.
115
+
116
+ - `setTranslator(fn)` supplies the words. The function receives a flat message key and returns its text.
117
+ - `setLanguage(tag)` selects the active language for plural rules, default formatting, and language-specific `msg` tables. It does not load a catalogue or change the page's HTML `lang` attribute.
118
+ - `locale` selects formatting on helpers and components that expose this option. It does not select translated interface messages.
119
+ - `displayLocale` controls the names shown by Select.locale() and Select.country(), independently of their selected value.
120
+ - `msg` overrides messages for one component. Application labels, record values, and server text remain application-owned.
121
+
122
+ ### Enable a shipped language
123
+
124
+ Install the catalogue and language before creating components:
125
+
126
+ ```js
127
+ import { setLanguage, setTranslator } from '@zeyos/zx';
128
+ import { de } from '@zeyos/zx/locales/de.js';
129
+
130
+ setTranslator((key) => de[key]);
131
+ setLanguage('de-AT');
132
+ document.documentElement.lang = 'de-AT';
133
+ ```
134
+
135
+ This uses German messages with Austrian formatting conventions. `setTranslator(null)` restores
136
+ English message fallback; call `setLanguage('en')` as well to return formatting to English.
137
+ `en` from `@zeyos/zx/locales/en.js` is the frozen `defaultMessages` object. The optional
138
+ `@zeyos/zx/locales/index.js` exports `en`, `de`, and the frozen `locales` manifest. Importing that
139
+ manifest includes both catalogues; the main entry does not load German automatically.
140
+
141
+ ### Add a new language
142
+
143
+ Create an application-owned module, for example `app/locales/fr.js`, served at `/app/locales/fr.js`.
144
+ This intentionally partial example translates two Select messages:
145
+
146
+ ```js
147
+ export const fr = Object.freeze({
148
+ 'select.none': 'Aucune sélection',
149
+ 'select.empty': 'Aucun résultat'
150
+ });
151
+ ```
152
+
153
+ ```js
154
+ import { setLanguage, setTranslator } from '@zeyos/zx';
155
+ import { fr } from '/app/locales/fr.js';
156
+
157
+ setTranslator((key) => fr[key]);
158
+ setLanguage('fr-FR');
159
+ document.documentElement.lang = 'fr-FR';
160
+ ```
161
+
162
+ Use `defaultMessages` as the inventory of built-in keys to translate. Keep their placeholders,
163
+ including each plural form's placeholders, and test the controls and accessible labels that your
164
+ application uses. A partial catalogue should return `undefined` for untranslated keys so Zx can
165
+ apply its English fallback with English plural rules. Do not fill a partial non-English catalogue
166
+ by spreading `defaultMessages` into it. `null` and an echoed key also mean “no translation”; an
167
+ empty string is an intentional empty translation.
168
+
169
+ Application catalogues need no change to Zx or its shipped manifest. Keep a registry of the languages
170
+ your application actually supports, and pass those tags to Select.locale().
171
+
172
+ ### Regional variants and catalogue lookup
173
+
174
+ The application chooses how a regional tag maps to a catalogue. Zx does not automatically search
175
+ `de-AT`, then `de`, inside your translator. Reuse a language catalogue, or create regional overrides:
176
+
177
+ ```js
178
+ import { setLanguage, setTranslator } from '@zeyos/zx';
179
+ import { en, de } from '@zeyos/zx/locales/index.js';
180
+
181
+ const deAT = Object.freeze({ ...de, 'table.empty': 'Keine Einträge' });
182
+ const catalogues = { en, de, 'de-AT': deAT };
183
+
184
+ function applyLocale(tag) {
185
+ const locale = Intl.getCanonicalLocales(tag)[0];
186
+ const language = new Intl.Locale(locale).language;
187
+ const catalogue = catalogues[locale] ?? catalogues[language];
188
+ setTranslator(catalogue ? (key) => catalogue[key] : null);
189
+ setLanguage(locale);
190
+ document.documentElement.lang = locale;
191
+ }
192
+
193
+ applyLocale('de-AT');
194
+ ```
195
+
196
+ Here `en-GB` reuses English messages, while `de-AT` keeps its regional override. This function expects
197
+ a valid BCP 47 tag; picker values are already canonical. General locale APIs use hyphenated tags.
198
+
199
+ ### Message keys and interpolation variables
200
+
201
+ Use flat string keys for your own messages. A dotted key is a name, not a nested object path.
202
+ Positional placeholders are `%1`, `%2`, and so on; named placeholders use `%name%`:
203
+
204
+ ```js
205
+ import { setLanguage, setTranslator, translate } from '@zeyos/zx';
206
+ import { de } from '@zeyos/zx/locales/de.js';
207
+
208
+ const messages = Object.freeze({
209
+ ...de,
210
+ 'app.welcome': 'Willkommen, %1!',
211
+ 'app.assigned': '%person% bearbeitet %record%.'
212
+ });
213
+ setTranslator((key) => messages[key]);
214
+ setLanguage('de');
215
+
216
+ translate('app.welcome', ['Ada']);
217
+ translate('app.assigned', { person: 'Ada', record: 'INV-42' });
218
+ ```
219
+
220
+ `component.msg(key, ...args)` takes positional arguments. For a named template, use
221
+ `translate(key, values)` or `printf(component.msg(key), values)`. Interpolation produces plain text;
222
+ render it with text nodes or `textContent`.
223
+
224
+ For a single component, pass `msg: { 'select.empty': 'Nothing found here' }`. Resolution is instance
225
+ messages, host translator, inherited component messages, English catalogue, then the key.
226
+ Language-specific tables such as `msg: { de: { 'select.empty': 'Nichts gefunden' } }` match the exact
227
+ active language identifier; provide a `de-AT` table or a flat entry when that is the active tag.
228
+
229
+ ### Plural forms
230
+
231
+ Pass a numeric count separately from its displayed text. The selected cardinal category comes
232
+ from `Intl.PluralRules`; messages remain flat strings:
233
+
234
+ ```js
235
+ import { formatNumber, setLanguage, setTranslator, translatePlural } from '@zeyos/zx';
236
+ import { de } from '@zeyos/zx/locales/de.js';
237
+
238
+ const messages = Object.freeze({
239
+ ...de,
240
+ 'app.results.one': '%1 Ergebnis',
241
+ 'app.results.other': '%1 Ergebnisse'
242
+ });
243
+ setTranslator((key) => messages[key]);
244
+ setLanguage('de');
245
+
246
+ const count = 1200;
247
+ translatePlural('app.results', count, [formatNumber(count)]);
248
+ ```
249
+
250
+ Use `component.msgPlural(key, count, ...args)` inside a component. Supply `.other` and the categories
251
+ your language needs: `.zero`, `.one`, `.two`, `.few`, and `.many` are supported too. At each message
252
+ source, lookup tries the selected category, `.other`, then the unsuffixed key and any supported legacy
253
+ alias before moving to the next source. Existing flat overrides therefore keep their precedence.
254
+ English fallback uses English rules. Custom application keys need their own fallback text; they are
255
+ not part of the built-in English catalogue. Ordinary `translate()` and `msg()` never infer a count.
256
+
257
+ ### Formatting and date-name overrides
258
+
259
+ Formatting uses a supported explicit locale, then the active language, then English. Support is
260
+ checked for the particular Intl service, since a language may support numbers but not plural rules.
261
+ Regional English tags retain their own conventions.
262
+
263
+ ```js
264
+ import { formatCurrency, formatDate, formatNumber } from '@zeyos/zx';
265
+
266
+ formatNumber(1234.5, { locale: 'en-GB', decimals: 2 });
267
+ formatCurrency(1234.5, 'EUR', { locale: 'de-AT' });
268
+ formatDate(new Date(2026, 8, 1), '%b', { locale: 'en-GB' });
269
+ ```
270
+
271
+ Components with a `locale` option can use the same override. For NumberField, locale-aware display
272
+ and parsing apply with `group: true`; ungrouped fields retain their machine-format input behavior.
273
+ Currency, time zone, week start, and display patterns are separate settings where the API exposes
274
+ them; a locale tag alone does not choose them all.
275
+
276
+ `formatDate()` normally obtains month and weekday names from Intl. A host translator can override
277
+ `date.month.0` through `date.month.11` and `date.weekday.0` through `date.weekday.6` (Sunday is zero).
278
+ Use `date.month.short.0` and `date.weekday.short.0` for their short forms. Missing short names come
279
+ from Intl, not a shortened translated long name. These overrides apply when no explicit locale is
280
+ passed; an explicit `formatDate(..., { locale })` takes precedence. `locale: null` remains implicit.
281
+
282
+ ### Use the Select-based pickers
283
+
284
+ Select.locale() and Select.country() return ordinary Select instances. They keep its popup, keyboard map, events, field
285
+ adapter, and `.zx-select` styling, adding item generation, names, flags, and value normalization.
286
+ A locale selection emits `change`; it does not install translations or change the application language.
287
+
288
+ Using `applyLocale()` from the regional-lookup example:
289
+
290
+ ```js
291
+ import { getLanguage, Select } from '@zeyos/zx';
292
+
293
+ const picker = Select.locale(null, {
294
+ locales: ['en-GB', 'de-DE', 'de-AT'],
295
+ value: getLanguage(),
296
+ displayLocale: 'en-GB',
297
+ flags: 'code',
298
+ filter: 'local'
299
+ });
300
+ picker.on('change', ({ detail }) => {
301
+ if (detail.value) applyLocale(detail.value);
302
+ });
303
+ document.querySelector('#language').append(picker.toElement());
304
+ ```
305
+
306
+ `displayLocale` changes the language names shown, while the selected value stays a locale tag.
307
+ Select.locale() filters automatically for lists longer than seven; `filter: 'local'` also enables
308
+ search for short lists. For a form, use the existing Select field preset:
309
+
310
+ ```js
311
+ import { Field } from '@zeyos/zx';
312
+
313
+ const languageField = new Field(null, {
314
+ type: 'zxselect',
315
+ name: 'language',
316
+ label: 'Language',
317
+ value: 'de-AT',
318
+ props: { preset: 'locale', locales: ['en-GB', 'de-AT'], flags: 'code' }
319
+ });
320
+ ```
321
+
322
+ Use `props.preset: 'country'` for the country factory. Preset names are Field adapter options;
323
+ for direct construction call `Select.locale()` or `Select.country()`.
324
+
325
+ ### Switching language at runtime
326
+
327
+ Set the translator and active language together, then refresh your application UI. Zx does not
328
+ broadcast a language-change event or automatically relabel every mounted component. Preserve the
329
+ application's values, destroy affected instances, and recreate them with the new messages; merely
330
+ changing the picker value does not do this. Use each component's documented update methods where
331
+ they cover the text being changed, rather than calling its internal `render()` method.
332
+
333
+ Set the document or region's HTML `lang` for pronunciation, and set `dir="rtl"` when your application
334
+ selects a right-to-left language. Zx does not infer text direction from `setLanguage()`. Verify visible
335
+ labels, accessible names, plural counts, date/number entry, and layout after a switch.
336
+
337
+ ### German catalogue glossary
338
+
339
+ - **Voice** — a business application. The reader is addressed formally ("Sie"), and preferably not
340
+ at all ("Änderungen speichern"). Buttons and menu items use the infinitive ("Speichern",
341
+ "Abbrechen").
342
+ - **Typography** — quotation marks „…“; the ellipsis character attached to its word ("Wird
343
+ geladen…"); a non-breaking space between a number and its unit ("Letzte 30 Tage").
344
+ - **Kept as they are** — Agent, Board, Code, Swimlanes, Tags, Token, Tool, Upload; also Dashboard,
345
+ Prompt, and Tab where a key needs them. A work-in-progress limit is a WIP-Limit.
346
+ - **Agents** — approve → genehmigen, approval → Genehmigung, reject → ablehnen, request → Anfrage,
347
+ run → Ausführung, working time → Laufzeit, step → Schritt, tool call → Tool-Aufruf, retry →
348
+ Wiederholung, stop → stoppen, conversation → Unterhaltung, source → Quelle, attachment → Anhang.
349
+ - **Records** — record → Datensatz, field → Feld, row → Zeile, column → Spalte, view → Ansicht,
350
+ group by → gruppieren nach, no records → Keine Datensätze.
351
+ - **Dates** — event → Termin, date range and period → Zeitraum, week number → Kalenderwoche.
352
+ - **Actions** — choose and select → auswählen, clear → zurücksetzen (a selection: aufheben), search
353
+ → suchen, or durchsuchen with an object, expand → ausklappen, collapse → einklappen, hide →
354
+ ausblenden, remove → entfernen, no matches → Keine Treffer, no results → Keine Ergebnisse.
355
+ - **Parts of the interface** — message → Nachricht in a conversation and Meldung in a notice,
356
+ launcher → Schnellsuche, workspace → Arbeitsbereich, panel → Bereich, sheet → Seitenbereich,
357
+ breadcrumb → Pfadnavigation.
358
+ - **Keys** — arrow keys → Pfeiltasten, Space → Leertaste, Enter → Eingabetaste, Escape → Esc, Ctrl →
359
+ Strg, Delete → Entf.