@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
@@ -10,6 +10,28 @@ export type ChartData = {
10
10
  [key: string]: unknown;
11
11
  };
12
12
  export type ChartText = (key: string, ...args: unknown[]) => string;
13
+ export type ChartTheme = {
14
+ /**
15
+ * Text colour, from `--zx-color-text`. Absent where the token is not
16
+ * defined (no Zx stylesheet).
17
+ */
18
+ color?: string;
19
+ /**
20
+ * Grid and axis line colour, from `--zx-color-border`. Absent
21
+ * where the token is not defined.
22
+ */
23
+ borderColor?: string;
24
+ /**
25
+ * The surface the chart is drawn on, from `--zx-color-bg-surface`,
26
+ * for what has to mask the grid behind a label. Absent where the token is not defined.
27
+ */
28
+ background?: string;
29
+ /**
30
+ * The categorical series colours, `--zx-color-chart-1` to `-8`, in
31
+ * order; empty where the tokens are not defined. Series beyond the eighth start over.
32
+ */
33
+ palette: string[];
34
+ };
13
35
  export type ChartSpec = {
14
36
  /**
15
37
  * Chart type.
@@ -20,9 +42,17 @@ export type ChartSpec = {
20
42
  */
21
43
  data: ChartData;
22
44
  /**
23
- * Engine-specific options.
45
+ * Engine-specific options: the application's
46
+ * `chartOptions`, over `color` and `borderColor` from the theme (the same strings as
47
+ * `theme.color` and `theme.borderColor`, in the shape Chart.js reads them). Chart.js takes the
48
+ * colours of its axes from its global defaults rather than from these, so `ChartJsAdapter` also
49
+ * gives every scale the theme's colours wherever the options leave one unset.
24
50
  */
25
51
  options: Record<string, unknown>;
52
+ /**
53
+ * Resolved theme colours, including the categorical palette.
54
+ */
55
+ theme: ChartTheme;
26
56
  /**
27
57
  * Whether the chart must not animate: the operating system asks
28
58
  * for reduced motion, or the host sits inside a `data-zx-motion="reduced"` region. An adapter turns
@@ -36,11 +66,12 @@ export type ChartSpec = {
36
66
  };
37
67
  export type ChartHandle = {
38
68
  /**
39
- * Update the mounted chart.
69
+ * Update the mounted chart. Called for new data, type
70
+ * or options, and whenever the theme or the motion preference changes.
40
71
  */
41
72
  update: (spec: ChartSpec) => void;
42
73
  /**
43
- * Resize the mounted chart.
74
+ * Resize the mounted chart; called when the viewport changes size.
44
75
  */
45
76
  resize: () => void;
46
77
  /**
@@ -53,8 +84,52 @@ export type ChartHandle = {
53
84
  instance?: unknown;
54
85
  };
55
86
  export type ChartAdapter = {
56
- create: (canvas: HTMLCanvasElement, spec: ChartSpec) => ChartHandle;
87
+ /**
88
+ * Creates the
89
+ * engine on the chart's canvas. Chart calls it once the canvas is connected to a document and its
90
+ * viewport has a size, so the engine can measure the canvas and `spec.theme` carries real values;
91
+ * a chart that is loading, empty or in error has no engine. Where the environment has no
92
+ * `ResizeObserver`, or no layout at all, there is nothing to wait for and `create()` runs as soon
93
+ * as the chart has data.
94
+ */
95
+ create?: (canvas: HTMLCanvasElement, spec: ChartSpec) => ChartHandle;
96
+ /**
97
+ * Creates the engine
98
+ * with an element of its own, appended to the chart's viewport, at the moment `create()` would
99
+ * run. The canvas stays in place, empty, and keeps the chart's accessible name and description;
100
+ * what the adapter appends lies over it, is presentational (`aria-hidden="true"`), and is removed
101
+ * by the handle's `destroy()`. `SvgChartAdapter` is one.
102
+ */
103
+ mount?: (viewport: HTMLElement, spec: ChartSpec) => ChartHandle;
57
104
  };
105
+ export type ChartSummaryContext = {
106
+ /**
107
+ * The series the value belongs to.
108
+ */
109
+ dataset: ChartDataset;
110
+ /**
111
+ * Index of that series in `data.datasets`.
112
+ */
113
+ datasetIndex: number;
114
+ /**
115
+ * Index of the value in the series, and of its row in the table.
116
+ */
117
+ index: number;
118
+ /**
119
+ * Entry of `data.labels` at that index; undefined where there is none.
120
+ */
121
+ label: unknown;
122
+ /**
123
+ * The entry of `dataset.data` as it was given — the whole point object
124
+ * where `value` is its `y` or `r`.
125
+ */
126
+ raw: unknown;
127
+ /**
128
+ * The text the table would show without `summaryFormat`.
129
+ */
130
+ formatted: string;
131
+ };
132
+ export type ChartSummaryFormat = (value: unknown, context: ChartSummaryContext) => string | null | undefined;
58
133
  export type ChartJsAdapterOptions = Object;
59
134
  export type ChartSelectDetail = {
60
135
  /**
@@ -84,7 +159,9 @@ export type ChartSelectDetail = {
84
159
  };
85
160
  export type ChartOptions = {
86
161
  /**
87
- * Injected engine adapter.
162
+ * The engine that draws: `new SvgChartAdapter()`
163
+ * needs nothing else, `new ChartJsAdapter(Chart)` an injected Chart.js. Without one the chart
164
+ * draws nothing, and its data lives in the summary table alone.
88
165
  */
89
166
  adapter?: ChartAdapter | null;
90
167
  /**
@@ -112,6 +189,13 @@ export type ChartOptions = {
112
189
  * Semantic data-table presentation.
113
190
  */
114
191
  summary?: 'hidden' | 'visible';
192
+ /**
193
+ * Formats a summary-table value. Without
194
+ * it a number is written for the active language (`lang`, else `getLanguage()`) with grouping and
195
+ * up to twelve significant digits — `1234567.5` reads "1,234,567.5", `0.1 + 0.2` reads "0.3" —
196
+ * and any other value as its own text.
197
+ */
198
+ summaryFormat?: ChartSummaryFormat | null;
115
199
  /**
116
200
  * Initial loading state.
117
201
  */
@@ -132,9 +216,17 @@ export type ChartOptions = {
132
216
  */
133
217
  errorText?: string | null;
134
218
  /**
135
- * Responsive container aspect ratio.
219
+ * Responsive container aspect ratio. Not used in
220
+ * `fill` mode.
136
221
  */
137
222
  aspectRatio?: string;
223
+ /**
224
+ * Takes the block size of the container instead of deriving it
225
+ * from `aspectRatio`: the root is 100% tall and the viewport takes what the description and a
226
+ * visible summary leave. The container needs a height of its own. The minimum viewport height
227
+ * is the `--zx-chart-min-block-size` custom property: 220px by default, none in `fill` mode.
228
+ */
229
+ fill?: boolean;
138
230
  /**
139
231
  * Engine-ready listener.
140
232
  */
@@ -162,11 +254,31 @@ export type ChartOptions = {
162
254
  /** @typedef {{label?: string, data?: unknown[], [key: string]: unknown}} ChartDataset */
163
255
  /** @typedef {{labels?: unknown[], datasets?: ChartDataset[], [key: string]: unknown}} ChartData */
164
256
  /** @typedef {(key: string, ...args: unknown[]) => string} ChartText Resolves a message. */
257
+ /**
258
+ * @typedef {Object} ChartTheme
259
+ * The theme as the chart root resolves it, read when the engine is created and again on every
260
+ * update. Every colour is a string a CSS Color 3 parser reads: `#rrggbb` when opaque,
261
+ * `rgba(r, g, b, a)` when translucent — never `color()`, `oklch()`, `light-dark()` or a `var()`.
262
+ * @property {string} [color] Text colour, from `--zx-color-text`. Absent where the token is not
263
+ * defined (no Zx stylesheet).
264
+ * @property {string} [borderColor] Grid and axis line colour, from `--zx-color-border`. Absent
265
+ * where the token is not defined.
266
+ * @property {string} [background] The surface the chart is drawn on, from `--zx-color-bg-surface`,
267
+ * for what has to mask the grid behind a label. Absent where the token is not defined.
268
+ * @property {string[]} palette The categorical series colours, `--zx-color-chart-1` to `-8`, in
269
+ * order; empty where the tokens are not defined. Series beyond the eighth start over.
270
+ */
165
271
  /**
166
272
  * @typedef {Object} ChartSpec
273
+ * What a `ChartAdapter` receives in `create()` and in every `update()`.
167
274
  * @property {string} type Chart type.
168
275
  * @property {ChartData} data Chart data.
169
- * @property {Record<string, unknown>} options Engine-specific options.
276
+ * @property {Record<string, unknown>} options Engine-specific options: the application's
277
+ * `chartOptions`, over `color` and `borderColor` from the theme (the same strings as
278
+ * `theme.color` and `theme.borderColor`, in the shape Chart.js reads them). Chart.js takes the
279
+ * colours of its axes from its global defaults rather than from these, so `ChartJsAdapter` also
280
+ * gives every scale the theme's colours wherever the options leave one unset.
281
+ * @property {ChartTheme} theme Resolved theme colours, including the categorical palette.
170
282
  * @property {boolean} reducedMotion Whether the chart must not animate: the operating system asks
171
283
  * for reduced motion, or the host sits inside a `data-zx-motion="reduced"` region. An adapter turns
172
284
  * its engine's own animation off when this is true; `ChartJsAdapter` sets `animation: false`.
@@ -174,12 +286,44 @@ export type ChartOptions = {
174
286
  */
175
287
  /**
176
288
  * @typedef {Object} ChartHandle
177
- * @property {(spec: ChartSpec) => void} update Update the mounted chart.
178
- * @property {() => void} resize Resize the mounted chart.
289
+ * @property {(spec: ChartSpec) => void} update Update the mounted chart. Called for new data, type
290
+ * or options, and whenever the theme or the motion preference changes.
291
+ * @property {() => void} resize Resize the mounted chart; called when the viewport changes size.
179
292
  * @property {() => void} destroy Destroy the mounted chart.
180
293
  * @property {unknown} [instance] Engine instance.
181
294
  */
182
- /** @typedef {{create: (canvas: HTMLCanvasElement, spec: ChartSpec) => ChartHandle}} ChartAdapter */
295
+ /**
296
+ * @typedef {Object} ChartAdapter
297
+ * The contract between Chart and a chart engine. An engine that paints a canvas implements
298
+ * `create()`; one that draws an element of its own, such as an SVG, implements `mount()`. Chart
299
+ * calls `mount()` when an adapter has it, `create()` otherwise.
300
+ * @property {(canvas: HTMLCanvasElement, spec: ChartSpec) => ChartHandle} [create] Creates the
301
+ * engine on the chart's canvas. Chart calls it once the canvas is connected to a document and its
302
+ * viewport has a size, so the engine can measure the canvas and `spec.theme` carries real values;
303
+ * a chart that is loading, empty or in error has no engine. Where the environment has no
304
+ * `ResizeObserver`, or no layout at all, there is nothing to wait for and `create()` runs as soon
305
+ * as the chart has data.
306
+ * @property {(viewport: HTMLElement, spec: ChartSpec) => ChartHandle} [mount] Creates the engine
307
+ * with an element of its own, appended to the chart's viewport, at the moment `create()` would
308
+ * run. The canvas stays in place, empty, and keeps the chart's accessible name and description;
309
+ * what the adapter appends lies over it, is presentational (`aria-hidden="true"`), and is removed
310
+ * by the handle's `destroy()`. `SvgChartAdapter` is one.
311
+ */
312
+ /**
313
+ * @typedef {Object} ChartSummaryContext
314
+ * @property {ChartDataset} dataset The series the value belongs to.
315
+ * @property {number} datasetIndex Index of that series in `data.datasets`.
316
+ * @property {number} index Index of the value in the series, and of its row in the table.
317
+ * @property {unknown} label Entry of `data.labels` at that index; undefined where there is none.
318
+ * @property {unknown} raw The entry of `dataset.data` as it was given — the whole point object
319
+ * where `value` is its `y` or `r`.
320
+ * @property {string} formatted The text the table would show without `summaryFormat`.
321
+ */
322
+ /**
323
+ * @typedef {(value: unknown, context: ChartSummaryContext) => string|null|undefined} ChartSummaryFormat
324
+ * Formats one cell of the summary table. `value` is the data entry, or `y` (else `r`) of a point
325
+ * object; the returned text is the cell, and null or undefined keeps `context.formatted`.
326
+ */
183
327
  /**
184
328
  * @typedef {Object} ChartJsAdapterOptions
185
329
  * Generated API marker for the adapter class; its constructor accepts an injected engine and
@@ -196,7 +340,9 @@ export type ChartOptions = {
196
340
  */
197
341
  /**
198
342
  * @typedef {Object} ChartOptions
199
- * @property {ChartAdapter|null} [adapter=null] Injected engine adapter.
343
+ * @property {ChartAdapter|null} [adapter=null] The engine that draws: `new SvgChartAdapter()`
344
+ * needs nothing else, `new ChartJsAdapter(Chart)` an injected Chart.js. Without one the chart
345
+ * draws nothing, and its data lives in the summary table alone.
200
346
  * @property {string} [type='bar'] Chart type passed to the adapter.
201
347
  * @property {ChartData} [data={labels: [], datasets: []}] Chart data.
202
348
  * @property {Record<string, unknown>} [chartOptions={}] Engine-specific options.
@@ -204,6 +350,10 @@ export type ChartOptions = {
204
350
  * the `chart.label` message ("Chart").
205
351
  * @property {string} [description=''] Accessible description.
206
352
  * @property {'hidden'|'visible'} [summary='hidden'] Semantic data-table presentation.
353
+ * @property {ChartSummaryFormat|null} [summaryFormat=null] Formats a summary-table value. Without
354
+ * it a number is written for the active language (`lang`, else `getLanguage()`) with grouping and
355
+ * up to twelve significant digits — `1234567.5` reads "1,234,567.5", `0.1 + 0.2` reads "0.3" —
356
+ * and any other value as its own text.
207
357
  * @property {boolean} [loading=false] Initial loading state.
208
358
  * @property {string|null} [emptyText] Empty-state text, by default the `chart.empty` message
209
359
  * ("No chart data"). Null shows none.
@@ -211,7 +361,12 @@ export type ChartOptions = {
211
361
  * ("Loading chart…"). Null shows none.
212
362
  * @property {string|null} [errorText] Error fallback text, by default the `chart.error` message
213
363
  * ("Unable to render chart"). Null shows none.
214
- * @property {string} [aspectRatio='16 / 9'] Responsive container aspect ratio.
364
+ * @property {string} [aspectRatio='16 / 9'] Responsive container aspect ratio. Not used in
365
+ * `fill` mode.
366
+ * @property {boolean} [fill=false] Takes the block size of the container instead of deriving it
367
+ * from `aspectRatio`: the root is 100% tall and the viewport takes what the description and a
368
+ * visible summary leave. The container needs a height of its own. The minimum viewport height
369
+ * is the `--zx-chart-min-block-size` custom property: 220px by default, none in `fill` mode.
215
370
  * @property {(event: CustomEvent<{instance: unknown}>) => void} [onready] Engine-ready listener.
216
371
  * @property {(event: CustomEvent<{data: ChartData, type: string}>) => void} [onupdate] Update listener.
217
372
  * @property {(event: CustomEvent<ChartSelectDetail>) => void} [onselect] Point-selection listener.
@@ -227,10 +382,7 @@ export type ChartOptions = {
227
382
  */
228
383
  export declare class Chart extends Component<ChartOptions> {
229
384
  _createdRoot: boolean;
230
- _original: {
231
- attributes: string[][];
232
- children: ChildNode[];
233
- };
385
+ _snapshot: import("../../core/dom.js").TargetSnapshot;
234
386
  _adapter: ChartAdapter;
235
387
  _type: string;
236
388
  _data: ChartData;
@@ -241,7 +393,10 @@ export declare class Chart extends Component<ChartOptions> {
241
393
  _hasError: boolean;
242
394
  _handle: ChartHandle;
243
395
  _destroyed: boolean;
396
+ _themeKey: string;
397
+ _sized: boolean;
244
398
  _observer: ResizeObserver;
399
+ _themeObserver: MutationObserver;
245
400
  _stopWatchingMotion: () => void;
246
401
  static cssName: string;
247
402
  /** @type {Readonly<ChartOptions>} */
@@ -268,16 +423,80 @@ export declare class Chart extends Component<ChartOptions> {
268
423
  setError(error: unknown): this;
269
424
  /** Clears the error and remounts when data and an adapter are available. @returns {this} */
270
425
  clearError(): this;
271
- /** Requests an engine resize. @returns {this} */
426
+ /**
427
+ * Changes the accessible name of the canvas and the caption of the summary table.
428
+ * @param {string|null} label Label; null or blank text reads the `chart.label` message.
429
+ * @returns {this}
430
+ */
431
+ setLabel(label: string | null): this;
432
+ /**
433
+ * Changes the description under the chart, which also describes the canvas.
434
+ * @param {string|null} description Description; null or empty text shows none.
435
+ * @returns {this}
436
+ */
437
+ setDescription(description: string | null): this;
438
+ /**
439
+ * Shows the summary table or leaves it to assistive technology only.
440
+ * @param {'hidden'|'visible'} summary Presentation.
441
+ * @returns {this}
442
+ */
443
+ setSummary(summary: 'hidden' | 'visible'): this;
444
+ /**
445
+ * Changes the aspect ratio of the viewport. It has no effect while the chart is in `fill` mode.
446
+ * @param {string|number|null} aspectRatio A CSS `aspect-ratio` value such as `'16 / 9'` or `2`;
447
+ * null or blank text restores the default.
448
+ * @returns {this}
449
+ */
450
+ setAspectRatio(aspectRatio: string | number | null): this;
451
+ /**
452
+ * Switches `fill` mode, in which the chart takes the block size of its container.
453
+ * @param {boolean} [fill=true] Whether to fill the container.
454
+ * @returns {this}
455
+ */
456
+ setFill(fill?: boolean): this;
457
+ /**
458
+ * Requests an engine resize. The chart follows its viewport on its own; this is for an engine
459
+ * that needs telling after something else changed.
460
+ * @returns {this}
461
+ */
272
462
  resize(): this;
273
- /** Re-applies computed theme defaults through the adapter update path. @returns {this} */
463
+ /**
464
+ * Re-applies computed theme values through the adapter update path. The chart does this itself
465
+ * when a `data-zx-theme` or `data-zx-preset` attribute changes anywhere in the document, when the
466
+ * system colour scheme or contrast preference changes, and when it is shown again after being
467
+ * hidden or moved; call it after changing tokens in a way none of those cover — a stylesheet
468
+ * swap, a class, or an inline custom property.
469
+ * @returns {this}
470
+ */
274
471
  refreshTheme(): this;
275
- /** Returns the underlying engine instance when the adapter exposes it. @returns {unknown} */
472
+ /**
473
+ * Returns the underlying engine instance when the adapter exposes it. The engine exists once
474
+ * the chart is connected, displayed, and has data; asking for it right after appending the
475
+ * chart creates it then rather than on the next frame.
476
+ * @returns {unknown} Null while there is no engine.
477
+ */
276
478
  getInstance(): unknown;
277
479
  /** Destroys the engine/observer and restores or removes the host. @returns {void} */
278
480
  destroy(): void;
279
481
  /** @param {boolean} emitUpdate @returns {void} */
280
482
  _mountOrUpdate(emitUpdate: boolean): void;
483
+ /**
484
+ * Whether an engine can be created now: the canvas is in a document and its viewport has a size.
485
+ * An environment that cannot say — no `ResizeObserver` to report the size later, or no layout at
486
+ * all (jsdom measures everything as zero) — is not made to wait for an answer it will never get.
487
+ * @returns {boolean}
488
+ */
489
+ _canMount(): boolean;
490
+ /**
491
+ * The viewport changed size: create the engine if it was waiting for one, otherwise resize it.
492
+ * A viewport that had no size and has one again was hidden or moved, possibly into another
493
+ * theme region, so the theme is read again too.
494
+ * @param {ResizeObserverEntry[]} entries
495
+ * @returns {void}
496
+ */
497
+ _viewportResized(entries: ResizeObserverEntry[]): void;
498
+ /** Updates the engine when the theme it was given is no longer the one the root resolves. @returns {void} */
499
+ _syncTheme(): void;
281
500
  /** @returns {ChartSpec} */
282
501
  _spec(): ChartSpec;
283
502
  /** @returns {void} */
@@ -327,7 +546,8 @@ export declare function isEmptyChartData(data: ChartData): boolean;
327
546
  */
328
547
  export declare function chartSummaryTable(data: ChartData, label?: string): HTMLTableElement;
329
548
  /**
330
- * Produces the exact text matrix rendered by the semantic chart summary.
549
+ * Produces the exact text matrix rendered by the semantic chart summary, with numbers written for
550
+ * the active language.
331
551
  * @param {ChartData} data Chart data.
332
552
  * @returns {{headers: string[], rows: Array<{label: string, values: string[]}>}}
333
553
  */
@@ -338,6 +558,16 @@ export declare function chartSummaryModel(data: ChartData): {
338
558
  values: string[];
339
559
  }>;
340
560
  };
561
+ export type SummaryFormatting = {
562
+ /**
563
+ * Number-formatting locale; the active language by default.
564
+ */
565
+ locale?: string;
566
+ /**
567
+ * The chart's `summaryFormat`.
568
+ */
569
+ format?: ChartSummaryFormat | null;
570
+ };
341
571
  /** Fired after the adapter creates an engine instance. @event Chart#ready @type {CustomEvent<{instance: unknown}>} */
342
572
  /** Fired after an existing chart updates. @event Chart#update @type {CustomEvent<{data: ChartData, type: string}>} */
343
573
  /** Fired when the engine reports a selected point. @event Chart#select @type {CustomEvent<ChartSelectDetail>} */
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Colours for chart engines.
3
+ *
4
+ * A browser reports a computed colour in the syntax it was authored in: a token mixed with
5
+ * `color-mix()` reads back as `color(srgb 1 1 1 / 0.09)` or `oklab(…)`, a wide-gamut one as
6
+ * `oklch(…)` or `color(display-p3 …)`. Chart engines usually bring their own colour parser, and
7
+ * most of those stop at CSS Color 3. `legacyColor()` rewrites a computed colour as `#rrggbb`, or as
8
+ * `rgba(r, g, b, a)` when it is translucent — the two forms every parser reads.
9
+ *
10
+ * The conversion is arithmetic and needs no DOM. Its limits: it reads the syntaxes a computed
11
+ * value can take (hex, `rgb()`, `hsl()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, and
12
+ * `color()` in srgb, srgb-linear, display-p3, xyz, xyz-d65 and xyz-d50) — no colour names except
13
+ * `transparent`, no `color-mix()`, `light-dark()` or `var()`, which only an element can resolve;
14
+ * and a colour outside the sRGB gamut is clipped per channel rather than gamut-mapped.
15
+ * `paintedColor()` covers what the parser does not, by painting the colour on a canvas.
16
+ * @module zx/components/chart/color
17
+ */
18
+ export type RgbaColor = {
19
+ r: number;
20
+ g: number;
21
+ b: number;
22
+ a: number;
23
+ };
24
+ /**
25
+ * Parses a computed CSS colour into sRGB channels.
26
+ * @param {unknown} value Colour text.
27
+ * @returns {RgbaColor|null} Null when the text is not one of the supported syntaxes.
28
+ */
29
+ export declare function parseCssColor(value: unknown): RgbaColor | null;
30
+ /**
31
+ * Rewrites a computed CSS colour in a syntax every colour parser reads.
32
+ * @param {unknown} value Colour text, in any syntax `parseCssColor()` supports.
33
+ * @returns {string|null} `#rrggbb` for an opaque colour, `rgba(r, g, b, a)` for a translucent one,
34
+ * null when the text could not be read.
35
+ */
36
+ export declare function legacyColor(value: unknown): string | null;
37
+ /**
38
+ * The same colour at another opacity, for the fill under a line or inside a point.
39
+ * @param {unknown} value Colour text.
40
+ * @param {number} alpha Opacity from 0 to 1; it replaces the colour's own.
41
+ * @returns {string|null} `rgba(r, g, b, a)` (or `#rrggbb` at full opacity), null for unreadable text.
42
+ */
43
+ export declare function withAlpha(value: unknown, alpha: number): string | null;
44
+ /**
45
+ * Serialises channels in the legacy syntax.
46
+ * @param {RgbaColor} color Channels.
47
+ * @returns {string}
48
+ */
49
+ export declare function formatLegacyColor({ r, g, b, a }: RgbaColor): string;
50
+ /**
51
+ * Reads a colour by painting it: whatever the browser can paint comes back as 8-bit sRGB, so this
52
+ * covers syntaxes `legacyColor()` does not parse. It needs a 2D canvas, and a faint colour loses
53
+ * precision to the canvas's premultiplied 8-bit storage — which is why the parser goes first.
54
+ * @param {unknown} value Colour text.
55
+ * @param {Document|null} [ownerDocument] Document that creates the canvas.
56
+ * @returns {string|null} A legacy colour string, or null when the colour is invalid or no canvas is
57
+ * available.
58
+ */
59
+ export declare function paintedColor(value: unknown, ownerDocument?: Document | null): string | null;
60
+ /**
61
+ * A colour as an engine can read it: parsed where possible, painted otherwise.
62
+ * @param {unknown} value Computed colour text.
63
+ * @param {Document|null} [ownerDocument] Document for the canvas fallback.
64
+ * @returns {string|undefined} Undefined when neither route could read it.
65
+ */
66
+ export declare function engineColor(value: unknown, ownerDocument?: Document | null): string | undefined;
@@ -0,0 +1,103 @@
1
+ export type ChartData = import('./chart.js').ChartData;
2
+ export type ChartHandle = import('./chart.js').ChartHandle;
3
+ export type ChartSpec = import('./chart.js').ChartSpec;
4
+ export type SvgChartAdapterOptions = {
5
+ /**
6
+ * Whether a chart grows into place the first time it is
7
+ * drawn. Reduced motion stops it whatever this says; `chartOptions.animation` decides per chart.
8
+ */
9
+ animation?: boolean;
10
+ /**
11
+ * Whether a legend is drawn: null draws one for two or
12
+ * more series and for pie and doughnut charts; `chartOptions.legend` decides per chart.
13
+ */
14
+ legend?: boolean | null;
15
+ };
16
+ export type SeriesModel = {
17
+ /**
18
+ * Index of the dataset.
19
+ */
20
+ index: number;
21
+ /**
22
+ * The dataset's label, or "Series n".
23
+ */
24
+ name: string;
25
+ /**
26
+ * One per category; NaN where there is no value.
27
+ */
28
+ values: number[];
29
+ };
30
+ export type ChartModel = {
31
+ /**
32
+ * One per category.
33
+ */
34
+ labels: string[];
35
+ /**
36
+ * One per dataset.
37
+ */
38
+ series: SeriesModel[];
39
+ };
40
+ export type Formats = {
41
+ /**
42
+ * Tick labels.
43
+ */
44
+ ticks: (ticks: number[], step: number) => (value: number) => string;
45
+ /**
46
+ * A value as the tooltip writes it.
47
+ */
48
+ value: (value: number) => string;
49
+ /**
50
+ * A share of a pie.
51
+ */
52
+ percent: (value: number) => string;
53
+ };
54
+ /**
55
+ * @typedef {Object} SeriesModel
56
+ * @property {number} index Index of the dataset.
57
+ * @property {string} name The dataset's label, or "Series n".
58
+ * @property {number[]} values One per category; NaN where there is no value.
59
+ */
60
+ /**
61
+ * @typedef {Object} ChartModel
62
+ * @property {string[]} labels One per category.
63
+ * @property {SeriesModel[]} series One per dataset.
64
+ */
65
+ /**
66
+ * @typedef {Object} Formats
67
+ * @property {(ticks: number[], step: number) => (value: number) => string} ticks Tick labels.
68
+ * @property {(value: number) => string} value A value as the tooltip writes it.
69
+ * @property {(value: number) => string} percent A share of a pie.
70
+ */
71
+ /**
72
+ * A chart engine with no dependency: draws `bar` (grouped), `line`, `pie` and `doughnut` charts as
73
+ * SVG for `Chart`, through the adapter's `mount()` contract. Colours come from the theme's chart
74
+ * palette (`--zx-color-chart-1`…`-8`) through CSS, so a theme or preset switch repaints without a
75
+ * redraw. The drawing is presentational: the chart's canvas keeps its accessible name and
76
+ * description, and its summary table carries the values.
77
+ *
78
+ * `Surface` draws its `chart` nodes with a shared instance unless the application passes another
79
+ * adapter, or `null` for the data table alone.
80
+ */
81
+ export declare class SvgChartAdapter {
82
+ /** @type {Readonly<Required<SvgChartAdapterOptions>>} */
83
+ options: Readonly<Required<SvgChartAdapterOptions>>;
84
+ /**
85
+ * @param {SvgChartAdapterOptions} [options={}] Defaults for every chart the adapter draws.
86
+ */
87
+ constructor(options?: SvgChartAdapterOptions);
88
+ /**
89
+ * Whether the adapter draws a chart type: `bar`, `line`, `pie` or `doughnut`.
90
+ * @param {string} type Chart type.
91
+ * @returns {boolean}
92
+ */
93
+ static supports(type: string): boolean;
94
+ /**
95
+ * Draws one chart into the viewport Chart hands over and returns its lifecycle handle. The
96
+ * handle's `instance` is the drawing element.
97
+ * @param {HTMLElement} viewport The chart's viewport; the drawing is appended to it and removed
98
+ * by the handle's `destroy()`.
99
+ * @param {ChartSpec} spec Initial chart specification.
100
+ * @returns {ChartHandle}
101
+ */
102
+ mount(viewport: HTMLElement, spec: ChartSpec): ChartHandle;
103
+ }