@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
@@ -1,17 +1,39 @@
1
1
  import { Component } from '../../core/component.js';
2
- import { h } from '../../core/dom.js';
2
+ import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
3
+ import { formatNumber } from '../../core/format.js';
3
4
  import { translate } from '../../core/i18n.js';
4
5
  import { prefersReducedMotion, watchMotion } from '../../core/motion.js';
5
6
  import { uid } from '../../core/util.js';
7
+ import { engineColor, withAlpha } from './color.js';
6
8
 
7
9
  /** @typedef {{label?: string, data?: unknown[], [key: string]: unknown}} ChartDataset */
8
10
  /** @typedef {{labels?: unknown[], datasets?: ChartDataset[], [key: string]: unknown}} ChartData */
9
11
  /** @typedef {(key: string, ...args: unknown[]) => string} ChartText Resolves a message. */
12
+ /**
13
+ * @typedef {Object} ChartTheme
14
+ * The theme as the chart root resolves it, read when the engine is created and again on every
15
+ * update. Every colour is a string a CSS Color 3 parser reads: `#rrggbb` when opaque,
16
+ * `rgba(r, g, b, a)` when translucent — never `color()`, `oklch()`, `light-dark()` or a `var()`.
17
+ * @property {string} [color] Text colour, from `--zx-color-text`. Absent where the token is not
18
+ * defined (no Zx stylesheet).
19
+ * @property {string} [borderColor] Grid and axis line colour, from `--zx-color-border`. Absent
20
+ * where the token is not defined.
21
+ * @property {string} [background] The surface the chart is drawn on, from `--zx-color-bg-surface`,
22
+ * for what has to mask the grid behind a label. Absent where the token is not defined.
23
+ * @property {string[]} palette The categorical series colours, `--zx-color-chart-1` to `-8`, in
24
+ * order; empty where the tokens are not defined. Series beyond the eighth start over.
25
+ */
10
26
  /**
11
27
  * @typedef {Object} ChartSpec
28
+ * What a `ChartAdapter` receives in `create()` and in every `update()`.
12
29
  * @property {string} type Chart type.
13
30
  * @property {ChartData} data Chart data.
14
- * @property {Record<string, unknown>} options Engine-specific options.
31
+ * @property {Record<string, unknown>} options Engine-specific options: the application's
32
+ * `chartOptions`, over `color` and `borderColor` from the theme (the same strings as
33
+ * `theme.color` and `theme.borderColor`, in the shape Chart.js reads them). Chart.js takes the
34
+ * colours of its axes from its global defaults rather than from these, so `ChartJsAdapter` also
35
+ * gives every scale the theme's colours wherever the options leave one unset.
36
+ * @property {ChartTheme} theme Resolved theme colours, including the categorical palette.
15
37
  * @property {boolean} reducedMotion Whether the chart must not animate: the operating system asks
16
38
  * for reduced motion, or the host sits inside a `data-zx-motion="reduced"` region. An adapter turns
17
39
  * its engine's own animation off when this is true; `ChartJsAdapter` sets `animation: false`.
@@ -19,12 +41,44 @@ import { uid } from '../../core/util.js';
19
41
  */
20
42
  /**
21
43
  * @typedef {Object} ChartHandle
22
- * @property {(spec: ChartSpec) => void} update Update the mounted chart.
23
- * @property {() => void} resize Resize the mounted chart.
44
+ * @property {(spec: ChartSpec) => void} update Update the mounted chart. Called for new data, type
45
+ * or options, and whenever the theme or the motion preference changes.
46
+ * @property {() => void} resize Resize the mounted chart; called when the viewport changes size.
24
47
  * @property {() => void} destroy Destroy the mounted chart.
25
48
  * @property {unknown} [instance] Engine instance.
26
49
  */
27
- /** @typedef {{create: (canvas: HTMLCanvasElement, spec: ChartSpec) => ChartHandle}} ChartAdapter */
50
+ /**
51
+ * @typedef {Object} ChartAdapter
52
+ * The contract between Chart and a chart engine. An engine that paints a canvas implements
53
+ * `create()`; one that draws an element of its own, such as an SVG, implements `mount()`. Chart
54
+ * calls `mount()` when an adapter has it, `create()` otherwise.
55
+ * @property {(canvas: HTMLCanvasElement, spec: ChartSpec) => ChartHandle} [create] Creates the
56
+ * engine on the chart's canvas. Chart calls it once the canvas is connected to a document and its
57
+ * viewport has a size, so the engine can measure the canvas and `spec.theme` carries real values;
58
+ * a chart that is loading, empty or in error has no engine. Where the environment has no
59
+ * `ResizeObserver`, or no layout at all, there is nothing to wait for and `create()` runs as soon
60
+ * as the chart has data.
61
+ * @property {(viewport: HTMLElement, spec: ChartSpec) => ChartHandle} [mount] Creates the engine
62
+ * with an element of its own, appended to the chart's viewport, at the moment `create()` would
63
+ * run. The canvas stays in place, empty, and keeps the chart's accessible name and description;
64
+ * what the adapter appends lies over it, is presentational (`aria-hidden="true"`), and is removed
65
+ * by the handle's `destroy()`. `SvgChartAdapter` is one.
66
+ */
67
+ /**
68
+ * @typedef {Object} ChartSummaryContext
69
+ * @property {ChartDataset} dataset The series the value belongs to.
70
+ * @property {number} datasetIndex Index of that series in `data.datasets`.
71
+ * @property {number} index Index of the value in the series, and of its row in the table.
72
+ * @property {unknown} label Entry of `data.labels` at that index; undefined where there is none.
73
+ * @property {unknown} raw The entry of `dataset.data` as it was given — the whole point object
74
+ * where `value` is its `y` or `r`.
75
+ * @property {string} formatted The text the table would show without `summaryFormat`.
76
+ */
77
+ /**
78
+ * @typedef {(value: unknown, context: ChartSummaryContext) => string|null|undefined} ChartSummaryFormat
79
+ * Formats one cell of the summary table. `value` is the data entry, or `y` (else `r`) of a point
80
+ * object; the returned text is the cell, and null or undefined keeps `context.formatted`.
81
+ */
28
82
  /**
29
83
  * @typedef {Object} ChartJsAdapterOptions
30
84
  * Generated API marker for the adapter class; its constructor accepts an injected engine and
@@ -41,7 +95,9 @@ import { uid } from '../../core/util.js';
41
95
  */
42
96
  /**
43
97
  * @typedef {Object} ChartOptions
44
- * @property {ChartAdapter|null} [adapter=null] Injected engine adapter.
98
+ * @property {ChartAdapter|null} [adapter=null] The engine that draws: `new SvgChartAdapter()`
99
+ * needs nothing else, `new ChartJsAdapter(Chart)` an injected Chart.js. Without one the chart
100
+ * draws nothing, and its data lives in the summary table alone.
45
101
  * @property {string} [type='bar'] Chart type passed to the adapter.
46
102
  * @property {ChartData} [data={labels: [], datasets: []}] Chart data.
47
103
  * @property {Record<string, unknown>} [chartOptions={}] Engine-specific options.
@@ -49,6 +105,10 @@ import { uid } from '../../core/util.js';
49
105
  * the `chart.label` message ("Chart").
50
106
  * @property {string} [description=''] Accessible description.
51
107
  * @property {'hidden'|'visible'} [summary='hidden'] Semantic data-table presentation.
108
+ * @property {ChartSummaryFormat|null} [summaryFormat=null] Formats a summary-table value. Without
109
+ * it a number is written for the active language (`lang`, else `getLanguage()`) with grouping and
110
+ * up to twelve significant digits — `1234567.5` reads "1,234,567.5", `0.1 + 0.2` reads "0.3" —
111
+ * and any other value as its own text.
52
112
  * @property {boolean} [loading=false] Initial loading state.
53
113
  * @property {string|null} [emptyText] Empty-state text, by default the `chart.empty` message
54
114
  * ("No chart data"). Null shows none.
@@ -56,7 +116,12 @@ import { uid } from '../../core/util.js';
56
116
  * ("Loading chart…"). Null shows none.
57
117
  * @property {string|null} [errorText] Error fallback text, by default the `chart.error` message
58
118
  * ("Unable to render chart"). Null shows none.
59
- * @property {string} [aspectRatio='16 / 9'] Responsive container aspect ratio.
119
+ * @property {string} [aspectRatio='16 / 9'] Responsive container aspect ratio. Not used in
120
+ * `fill` mode.
121
+ * @property {boolean} [fill=false] Takes the block size of the container instead of deriving it
122
+ * from `aspectRatio`: the root is 100% tall and the viewport takes what the description and a
123
+ * visible summary leave. The container needs a height of its own. The minimum viewport height
124
+ * is the `--zx-chart-min-block-size` custom property: 220px by default, none in `fill` mode.
60
125
  * @property {(event: CustomEvent<{instance: unknown}>) => void} [onready] Engine-ready listener.
61
126
  * @property {(event: CustomEvent<{data: ChartData, type: string}>) => void} [onupdate] Update listener.
62
127
  * @property {(event: CustomEvent<ChartSelectDetail>) => void} [onselect] Point-selection listener.
@@ -83,12 +148,14 @@ export class Chart extends Component {
83
148
  label: null,
84
149
  description: '',
85
150
  summary: 'hidden',
151
+ summaryFormat: null,
86
152
  loading: false,
87
153
  // Undefined rather than null, which shows nothing.
88
154
  emptyText: undefined,
89
155
  loadingText: undefined,
90
156
  errorText: undefined,
91
- aspectRatio: '16 / 9'
157
+ aspectRatio: '16 / 9',
158
+ fill: false
92
159
  };
93
160
 
94
161
  /**
@@ -106,10 +173,7 @@ export class Chart extends Component {
106
173
  this._createdRoot = this.el === null;
107
174
  const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
108
175
  this.el = root;
109
- this._original = this._createdRoot ? null : {
110
- attributes: Array.from(root.attributes, (attribute) => [attribute.name, attribute.value]),
111
- children: Array.from(root.childNodes)
112
- };
176
+ this._snapshot = this._createdRoot ? null : snapshotTarget(root);
113
177
  this._adapter = this.options.adapter;
114
178
  this._type = String(this.options.type || 'bar');
115
179
  this._data = normalizeChartData(this.options.data);
@@ -120,6 +184,8 @@ export class Chart extends Component {
120
184
  this._hasError = false;
121
185
  this._handle = null;
122
186
  this._destroyed = false;
187
+ this._themeKey = '';
188
+ this._sized = false;
123
189
 
124
190
  const descriptionId = uid('zx-chart-description');
125
191
  const canvas = /** @type {HTMLCanvasElement} */ (h('canvas', {
@@ -133,7 +199,8 @@ export class Chart extends Component {
133
199
  ref: 'viewport',
134
200
  class: 'zx-chart__viewport'
135
201
  }, canvas);
136
- viewport.style.setProperty('--zx-chart-aspect-ratio', String(this.options.aspectRatio));
202
+ viewport.style.setProperty('--zx-chart-aspect-ratio', aspectRatioText(this.options.aspectRatio));
203
+ root.toggleAttribute('data-fill', Boolean(this.options.fill));
137
204
  const description = h('p', {
138
205
  ref: 'description',
139
206
  class: 'zx-chart__description',
@@ -154,8 +221,28 @@ export class Chart extends Component {
154
221
  this._renderSummary();
155
222
  this._syncState();
156
223
 
157
- this._observer = typeof ResizeObserver === 'function' ? new ResizeObserver(() => this.resize()) : null;
224
+ // The viewport has no size until the root is connected and displayed, and loses it when the
225
+ // root leaves the document: one observer both creates the engine at the right moment and
226
+ // keeps it sized. Constructed on a target that is already laid out, the chart does not wait
227
+ // for it — the constructor mounts synchronously.
228
+ this._observer = typeof ResizeObserver === 'function'
229
+ ? new ResizeObserver((entries) => this._viewportResized(entries))
230
+ : null;
158
231
  this._observer?.observe(viewport);
232
+ // Theme colours reach the engine as values, not as CSS, so a theme switch has to be noticed:
233
+ // the theme and preset attributes anywhere in the document, and the system preferences the
234
+ // tokens answer to.
235
+ this._themeObserver = typeof MutationObserver === 'function'
236
+ ? new MutationObserver(() => this._syncTheme())
237
+ : null;
238
+ const documentElement = root.ownerDocument?.documentElement;
239
+ if (documentElement) {
240
+ this._themeObserver?.observe(documentElement, { attributes: true, attributeFilter: THEME_ATTRIBUTES, subtree: true });
241
+ }
242
+ for (const query of THEME_QUERIES) {
243
+ const media = typeof globalThis.matchMedia === 'function' ? globalThis.matchMedia(query) : null;
244
+ if (typeof media?.addEventListener === 'function') this.listen(media, 'change', () => this._syncTheme());
245
+ }
159
246
  // The engine tweens in script, where no stylesheet can reach it: when motion is reduced, or
160
247
  // stops being reduced, the mounted chart is updated with the new answer in its spec.
161
248
  this._stopWatchingMotion = watchMotion(root, () => this._mountOrUpdate(false));
@@ -223,20 +310,94 @@ export class Chart extends Component {
223
310
  return this;
224
311
  }
225
312
 
226
- /** Requests an engine resize. @returns {this} */
313
+ /**
314
+ * Changes the accessible name of the canvas and the caption of the summary table.
315
+ * @param {string|null} label Label; null or blank text reads the `chart.label` message.
316
+ * @returns {this}
317
+ */
318
+ setLabel(label) {
319
+ this._label = String(label ?? '').trim() || this.msg('chart.label');
320
+ this.refs.canvas.setAttribute('aria-label', this._label);
321
+ this._renderSummary();
322
+ return this;
323
+ }
324
+
325
+ /**
326
+ * Changes the description under the chart, which also describes the canvas.
327
+ * @param {string|null} description Description; null or empty text shows none.
328
+ * @returns {this}
329
+ */
330
+ setDescription(description) {
331
+ this.refs.description.textContent = String(description ?? '');
332
+ return this;
333
+ }
334
+
335
+ /**
336
+ * Shows the summary table or leaves it to assistive technology only.
337
+ * @param {'hidden'|'visible'} summary Presentation.
338
+ * @returns {this}
339
+ */
340
+ setSummary(summary) {
341
+ this.refs.summary.dataset.summary = summary === 'visible' ? 'visible' : 'hidden';
342
+ return this;
343
+ }
344
+
345
+ /**
346
+ * Changes the aspect ratio of the viewport. It has no effect while the chart is in `fill` mode.
347
+ * @param {string|number|null} aspectRatio A CSS `aspect-ratio` value such as `'16 / 9'` or `2`;
348
+ * null or blank text restores the default.
349
+ * @returns {this}
350
+ */
351
+ setAspectRatio(aspectRatio) {
352
+ this.refs.viewport.style.setProperty('--zx-chart-aspect-ratio', aspectRatioText(aspectRatio));
353
+ return this;
354
+ }
355
+
356
+ /**
357
+ * Switches `fill` mode, in which the chart takes the block size of its container.
358
+ * @param {boolean} [fill=true] Whether to fill the container.
359
+ * @returns {this}
360
+ */
361
+ setFill(fill = true) {
362
+ this.el.toggleAttribute('data-fill', Boolean(fill));
363
+ return this;
364
+ }
365
+
366
+ /**
367
+ * Requests an engine resize. The chart follows its viewport on its own; this is for an engine
368
+ * that needs telling after something else changed.
369
+ * @returns {this}
370
+ */
227
371
  resize() {
228
- try { this._handle?.resize?.(); } catch (error) { this.setError(error); }
372
+ if (!this._handle) {
373
+ this._mountOrUpdate(false);
374
+ return this;
375
+ }
376
+ try { this._handle.resize?.(); } catch (error) { this.setError(error); }
229
377
  return this;
230
378
  }
231
379
 
232
- /** Re-applies computed theme defaults through the adapter update path. @returns {this} */
380
+ /**
381
+ * Re-applies computed theme values through the adapter update path. The chart does this itself
382
+ * when a `data-zx-theme` or `data-zx-preset` attribute changes anywhere in the document, when the
383
+ * system colour scheme or contrast preference changes, and when it is shown again after being
384
+ * hidden or moved; call it after changing tokens in a way none of those cover — a stylesheet
385
+ * swap, a class, or an inline custom property.
386
+ * @returns {this}
387
+ */
233
388
  refreshTheme() {
234
389
  this._mountOrUpdate(true);
235
390
  return this;
236
391
  }
237
392
 
238
- /** Returns the underlying engine instance when the adapter exposes it. @returns {unknown} */
393
+ /**
394
+ * Returns the underlying engine instance when the adapter exposes it. The engine exists once
395
+ * the chart is connected, displayed, and has data; asking for it right after appending the
396
+ * chart creates it then rather than on the next frame.
397
+ * @returns {unknown} Null while there is no engine.
398
+ */
239
399
  getInstance() {
400
+ if (!this._handle) this._mountOrUpdate(false);
240
401
  return this._handle?.instance ?? null;
241
402
  }
242
403
 
@@ -244,36 +405,40 @@ export class Chart extends Component {
244
405
  destroy() {
245
406
  if (this._destroyed) return;
246
407
  this._destroyed = true;
247
- const original = this._original;
248
408
  this._observer?.disconnect();
409
+ this._themeObserver?.disconnect();
249
410
  this._stopWatchingMotion?.();
250
411
  this._destroyHandle();
251
412
  super.destroy();
252
- if (!this._createdRoot && original) {
253
- for (const attribute of Array.from(this.el.attributes)) this.el.removeAttribute(attribute.name);
254
- for (const [name, value] of original.attributes) this.el.setAttribute(name, value);
255
- this.el.replaceChildren(...original.children);
256
- }
413
+ if (!this._createdRoot) restoreTarget(this.el, this._snapshot);
257
414
  }
258
415
 
259
416
  /** @param {boolean} emitUpdate @returns {void} */
260
417
  _mountOrUpdate(emitUpdate) {
418
+ if (this._destroyed) return;
261
419
  this._syncState();
262
420
  if (this._loading || this._hasError || isEmptyChartData(this._data)) {
263
421
  this._destroyHandle();
264
422
  return;
265
423
  }
266
- if (!this._adapter || typeof this._adapter.create !== 'function') {
424
+ const adapter = this._adapter;
425
+ if (!adapter || (typeof adapter.mount !== 'function' && typeof adapter.create !== 'function')) {
267
426
  this._destroyHandle();
268
427
  return;
269
428
  }
429
+ // Not connected or not laid out yet: the viewport observer comes back here when it is.
430
+ if (!this._handle && !this._canMount()) return;
270
431
  const spec = this._spec();
271
432
  try {
272
433
  if (this._handle) this._handle.update(spec);
273
434
  else {
274
- this._handle = this._adapter.create(/** @type {HTMLCanvasElement} */ (this.refs.canvas), spec);
435
+ // An adapter that draws its own element gets the viewport; one that paints gets the canvas.
436
+ const mounts = typeof adapter.mount === 'function';
437
+ this._handle = mounts
438
+ ? adapter.mount(/** @type {HTMLElement} */ (this.refs.viewport), spec)
439
+ : adapter.create(/** @type {HTMLCanvasElement} */ (this.refs.canvas), spec);
275
440
  if (!this._handle || typeof this._handle.destroy !== 'function') {
276
- throw new TypeError('Chart adapter create() must return a lifecycle handle');
441
+ throw new TypeError(`Chart adapter ${mounts ? 'mount' : 'create'}() must return a lifecycle handle`);
277
442
  }
278
443
  this.emit('ready', { instance: this.getInstance() });
279
444
  }
@@ -283,15 +448,62 @@ export class Chart extends Component {
283
448
  }
284
449
  }
285
450
 
451
+ /**
452
+ * Whether an engine can be created now: the canvas is in a document and its viewport has a size.
453
+ * An environment that cannot say — no `ResizeObserver` to report the size later, or no layout at
454
+ * all (jsdom measures everything as zero) — is not made to wait for an answer it will never get.
455
+ * @returns {boolean}
456
+ */
457
+ _canMount() {
458
+ if (!this._observer) return true;
459
+ const viewport = /** @type {HTMLElement} */ (this.refs.viewport);
460
+ if (!viewport.isConnected) return false;
461
+ const { width, height } = viewport.getBoundingClientRect();
462
+ if (width > 0 && height > 0) return true;
463
+ const page = viewport.ownerDocument.documentElement.getBoundingClientRect();
464
+ return page.width === 0 && page.height === 0;
465
+ }
466
+
467
+ /**
468
+ * The viewport changed size: create the engine if it was waiting for one, otherwise resize it.
469
+ * A viewport that had no size and has one again was hidden or moved, possibly into another
470
+ * theme region, so the theme is read again too.
471
+ * @param {ResizeObserverEntry[]} entries
472
+ * @returns {void}
473
+ */
474
+ _viewportResized(entries) {
475
+ if (this._destroyed) return;
476
+ const box = entries[entries.length - 1]?.contentRect;
477
+ const sized = Boolean(box && box.width > 0 && box.height > 0);
478
+ const shown = sized && !this._sized;
479
+ this._sized = sized;
480
+ if (!this._handle) {
481
+ this._mountOrUpdate(false);
482
+ return;
483
+ }
484
+ if (shown) this._syncTheme();
485
+ this.resize();
486
+ }
487
+
488
+ /** Updates the engine when the theme it was given is no longer the one the root resolves. @returns {void} */
489
+ _syncTheme() {
490
+ if (this._destroyed || !this._handle) return;
491
+ if (themeKey(chartTheme(/** @type {HTMLElement} */ (this.el))) === this._themeKey) return;
492
+ this._mountOrUpdate(false);
493
+ }
494
+
286
495
  /** @returns {ChartSpec} */
287
496
  _spec() {
497
+ const theme = chartTheme(/** @type {HTMLElement} */ (this.el));
498
+ this._themeKey = themeKey(theme);
499
+ const themed = {};
500
+ if (theme.color) themed.color = theme.color;
501
+ if (theme.borderColor) themed.borderColor = theme.borderColor;
288
502
  return {
289
503
  type: this._type,
290
504
  data: cloneChartValue(this._data),
291
- options: {
292
- ...themeChartOptions(/** @type {HTMLElement} */ (this.el)),
293
- ...cloneChartValue(this._chartOptions)
294
- },
505
+ options: { ...themed, ...cloneChartValue(this._chartOptions) },
506
+ theme,
295
507
  reducedMotion: prefersReducedMotion(this.el),
296
508
  onSelect: (detail) => this.emit('select', detail)
297
509
  };
@@ -328,7 +540,10 @@ export class Chart extends Component {
328
540
 
329
541
  /** @returns {void} */
330
542
  _renderSummary() {
331
- this.refs.summary.replaceChildren(summaryTable(this._data, this._label, (key, ...args) => this.msg(key, ...args)));
543
+ this.refs.summary.replaceChildren(summaryTable(this._data, this._label, (key, ...args) => this.msg(key, ...args), {
544
+ locale: this.options.lang ?? this.options.language ?? undefined,
545
+ format: typeof this.options.summaryFormat === 'function' ? this.options.summaryFormat : null
546
+ }));
332
547
  }
333
548
  }
334
549
 
@@ -404,6 +619,7 @@ function chartJsConfig(spec, defaults, getInstance) {
404
619
  ...cloneChartValue(defaults),
405
620
  ...supplied
406
621
  };
622
+ themeChartScales(options, spec);
407
623
  // Reduced motion wins over any animation the application configured: a person who asked for
408
624
  // less motion gets it from every chart, not only from the ones that remembered to ask.
409
625
  if (spec.reducedMotion) options.animation = false;
@@ -425,7 +641,117 @@ function chartJsConfig(spec, defaults, getInstance) {
425
641
  nativeEvent: event?.native ?? event ?? null
426
642
  });
427
643
  };
428
- return { type: spec.type, data: cloneChartValue(spec.data), options };
644
+ return { type: spec.type, data: paletteChartData(cloneChartValue(spec.data), spec.type, spec.theme?.palette), options };
645
+ }
646
+
647
+ /** Chart.js types whose single dataset is coloured per value rather than per series. */
648
+ const ARC_TYPES = new Set(['pie', 'doughnut', 'polarArea']);
649
+ /** Chart.js types drawn on an `x` and a `y` scale unless their datasets name others. */
650
+ const CARTESIAN_TYPES = new Set(['bar', 'line', 'scatter', 'bubble']);
651
+ /** Chart.js types drawn on one radial `r` scale unless their datasets name another. */
652
+ const RADIAL_TYPES = new Set(['radar', 'polarArea']);
653
+ /** How opaque a radial tick label's backdrop is: Chart.js's own white backdrop is 0.75. */
654
+ const TICK_BACKDROP_ALPHA = 0.75;
655
+
656
+ /**
657
+ * Gives every scale the chart will draw the theme's colours, wherever the options leave one
658
+ * unset. Chart.js 4 reads a scale's tick, title, grid and border colours from its global defaults
659
+ * (`#666`, `rgba(0, 0, 0, 0.1)`), not from the chart's own `color` and `borderColor`, so without
660
+ * this the axes of a dark chart are nearly invisible. Only scales that exist are touched — those
661
+ * the options configure and the ones the datasets' types draw on — because naming a scale makes
662
+ * Chart.js draw it, axes on a pie included.
663
+ * @param {Record<string, any>} options Chart.js options, already a copy; written to.
664
+ * @param {ChartSpec} spec Chart specification.
665
+ * @returns {void}
666
+ */
667
+ function themeChartScales(options, spec) {
668
+ const { color, borderColor, background } = spec.theme ?? /** @type {Partial<ChartTheme>} */ ({});
669
+ if (!color && !borderColor) return;
670
+ const configured = isPlainObject(options.scales) ? options.scales : {};
671
+ /** @type {Map<string, boolean>} Scale id to whether it is radial. */
672
+ const scales = new Map(Object.entries(configured)
673
+ .map(([id, scale]) => [id, isPlainObject(scale) && scale.type === 'radialLinear']));
674
+ const datasets = Array.isArray(spec.data?.datasets) ? spec.data.datasets : [];
675
+ for (const dataset of datasets) {
676
+ const type = String(dataset?.type ?? spec.type);
677
+ if (CARTESIAN_TYPES.has(type)) {
678
+ for (const axis of ['x', 'y']) {
679
+ const id = String(dataset?.[`${axis}AxisID`] ?? axis);
680
+ if (!scales.has(id)) scales.set(id, false);
681
+ }
682
+ } else if (RADIAL_TYPES.has(type)) {
683
+ scales.set(String(dataset?.rAxisID ?? 'r'), true);
684
+ }
685
+ }
686
+ if (scales.size === 0) return;
687
+ const themed = { ...configured };
688
+ for (const [id, radial] of scales) {
689
+ if (configured[id] !== undefined && !isPlainObject(configured[id])) continue;
690
+ const scale = { ...(configured[id] ?? {}) };
691
+ fillColour(scale, 'ticks', 'color', color);
692
+ fillColour(scale, 'grid', 'color', borderColor);
693
+ if (radial) {
694
+ fillColour(scale, 'pointLabels', 'color', color);
695
+ fillColour(scale, 'angleLines', 'color', borderColor);
696
+ // Radial tick labels sit on a white backdrop by default, which a light label cannot be read on.
697
+ if (background) fillColour(scale, 'ticks', 'backdropColor', withAlpha(background, TICK_BACKDROP_ALPHA) ?? background);
698
+ } else {
699
+ fillColour(scale, 'title', 'color', color);
700
+ fillColour(scale, 'border', 'color', borderColor);
701
+ }
702
+ themed[id] = scale;
703
+ }
704
+ options.scales = themed;
705
+ }
706
+
707
+ /**
708
+ * Sets `scale[part][key]` to a theme colour unless the options already say something there.
709
+ * @param {Record<string, any>} scale One scale's options; written to.
710
+ * @param {string} part Option group, such as `ticks` or `grid`.
711
+ * @param {string} key Option inside it.
712
+ * @param {string|undefined} value Theme colour; nothing happens without one.
713
+ * @returns {void}
714
+ */
715
+ function fillColour(scale, part, key, value) {
716
+ if (!value) return;
717
+ if (scale[part] !== undefined && !isPlainObject(scale[part])) return;
718
+ const group = { ...(scale[part] ?? {}) };
719
+ if (group[key] === undefined) group[key] = value;
720
+ scale[part] = group;
721
+ }
722
+
723
+ /** @param {unknown} value @returns {value is Record<string, any>} Whether the value is a plain object. */
724
+ function isPlainObject(value) {
725
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
726
+ const prototype = Object.getPrototypeOf(value);
727
+ return prototype === Object.prototype || prototype === null;
728
+ }
729
+
730
+ /**
731
+ * Gives every dataset that names no colour of its own one from the theme palette: per series, or
732
+ * per value for the arc types. A dataset with a `backgroundColor` or a `borderColor` is left
733
+ * exactly as the application wrote it.
734
+ * @param {ChartData} data Chart data, already a copy.
735
+ * @param {string} type Chart type.
736
+ * @param {string[]} [palette] Resolved palette.
737
+ * @returns {ChartData}
738
+ */
739
+ function paletteChartData(data, type, palette) {
740
+ if (!Array.isArray(palette) || !palette.length || !Array.isArray(data?.datasets)) return data;
741
+ const colour = (index) => palette[index % palette.length];
742
+ data.datasets.forEach((dataset, index) => {
743
+ if (!dataset || typeof dataset !== 'object') return;
744
+ if (dataset.backgroundColor !== undefined || dataset.borderColor !== undefined) return;
745
+ const datasetType = String(dataset.type ?? type);
746
+ if (ARC_TYPES.has(datasetType)) {
747
+ dataset.backgroundColor = (Array.isArray(dataset.data) ? dataset.data : []).map((_, point) => colour(point));
748
+ return;
749
+ }
750
+ dataset.borderColor = colour(index);
751
+ // A bar is its fill; a line, radar or point series fills under and inside its stroke.
752
+ dataset.backgroundColor = datasetType === 'bar' ? colour(index) : withAlpha(colour(index), 0.5) ?? colour(index);
753
+ });
754
+ return data;
429
755
  }
430
756
 
431
757
  /**
@@ -482,17 +808,18 @@ const catalogueText = (key, ...args) => translate(key, args);
482
808
  * @returns {HTMLTableElement}
483
809
  */
484
810
  export function chartSummaryTable(data, label = translate('chart.summary')) {
485
- return summaryTable(data, label, catalogueText);
811
+ return summaryTable(data, label, catalogueText, {});
486
812
  }
487
813
 
488
814
  /**
489
815
  * @param {ChartData} data Chart data.
490
816
  * @param {string} label Caption.
491
817
  * @param {ChartText} text Resolves the table's own words; a Chart passes its `msg()`.
818
+ * @param {SummaryFormatting} formatting How values are written.
492
819
  * @returns {HTMLTableElement}
493
820
  */
494
- function summaryTable(data, label, text) {
495
- const summary = summaryModel(data, text);
821
+ function summaryTable(data, label, text, formatting) {
822
+ const summary = summaryModel(data, text, formatting);
496
823
  const table = /** @type {HTMLTableElement} */ (h('table', { class: 'zx-chart__table' },
497
824
  h('caption', {}, label),
498
825
  h('thead', {}, h('tr', {}, h('th', { scope: 'col' }, text('chart.summaryLabel')),
@@ -504,20 +831,28 @@ function summaryTable(data, label, text) {
504
831
  }
505
832
 
506
833
  /**
507
- * Produces the exact text matrix rendered by the semantic chart summary.
834
+ * Produces the exact text matrix rendered by the semantic chart summary, with numbers written for
835
+ * the active language.
508
836
  * @param {ChartData} data Chart data.
509
837
  * @returns {{headers: string[], rows: Array<{label: string, values: string[]}>}}
510
838
  */
511
839
  export function chartSummaryModel(data) {
512
- return summaryModel(data, catalogueText);
840
+ return summaryModel(data, catalogueText, {});
513
841
  }
514
842
 
843
+ /**
844
+ * @typedef {Object} SummaryFormatting
845
+ * @property {string} [locale] Number-formatting locale; the active language by default.
846
+ * @property {ChartSummaryFormat|null} [format] The chart's `summaryFormat`.
847
+ */
848
+
515
849
  /**
516
850
  * @param {ChartData} data Chart data.
517
851
  * @param {ChartText} text Resolves the name of an unnamed series.
852
+ * @param {SummaryFormatting} formatting How values are written.
518
853
  * @returns {{headers: string[], rows: Array<{label: string, values: string[]}>}}
519
854
  */
520
- function summaryModel(data, text) {
855
+ function summaryModel(data, text, formatting) {
521
856
  const datasets = Array.isArray(data?.datasets) ? data.datasets : [];
522
857
  const labels = Array.isArray(data?.labels) ? data.labels : [];
523
858
  const length = Math.max(labels.length,
@@ -526,47 +861,100 @@ function summaryModel(data, text) {
526
861
  headers: datasets.map((dataset, index) => String(dataset.label ?? text('chart.series', index + 1))),
527
862
  rows: Array.from({ length }, (_, index) => ({
528
863
  label: String(labels[index] ?? index + 1),
529
- values: datasets.map((dataset) => summaryValue(dataset.data?.[index]))
864
+ values: datasets.map((dataset, datasetIndex) => {
865
+ const raw = dataset.data?.[index];
866
+ const value = summaryCellValue(raw);
867
+ const formatted = summaryValue(value, formatting.locale);
868
+ if (typeof formatting.format !== 'function') return formatted;
869
+ const custom = formatting.format(value, { dataset, datasetIndex, index, label: labels[index], raw, formatted });
870
+ return custom == null ? formatted : String(custom);
871
+ })
530
872
  }))
531
873
  };
532
874
  }
533
875
 
534
- /** @param {unknown} value @returns {string} */
535
- function summaryValue(value) {
876
+ /**
877
+ * The value a data entry stands for in the table: `y`, else `r`, of a point object.
878
+ * @param {unknown} raw Data entry.
879
+ * @returns {unknown}
880
+ */
881
+ function summaryCellValue(raw) {
882
+ if (raw && typeof raw === 'object') {
883
+ if ('y' in raw) return raw.y;
884
+ if ('r' in raw) return raw.r;
885
+ }
886
+ return raw;
887
+ }
888
+
889
+ /** Significant digits a summary number keeps: enough for any real value, too few for float noise. */
890
+ const SUMMARY_PRECISION = 12;
891
+
892
+ /**
893
+ * @param {unknown} value Cell value.
894
+ * @param {string} [locale] Number-formatting locale; the active language by default.
895
+ * @returns {string}
896
+ */
897
+ function summaryValue(value, locale) {
536
898
  if (value == null) return '';
899
+ if (typeof value === 'number' && Number.isFinite(value)) {
900
+ // A whole number is exact as it stands; rounding it to the precision would change large counts.
901
+ if (Number.isInteger(value)) return formatNumber(value, { locale, maxDecimals: 0 });
902
+ const magnitude = value === 0 ? 0 : Math.floor(Math.log10(Math.abs(value)));
903
+ const maxDecimals = Math.min(20, Math.max(0, SUMMARY_PRECISION - 1 - magnitude));
904
+ return formatNumber(Number(value.toPrecision(SUMMARY_PRECISION)), { locale, maxDecimals });
905
+ }
537
906
  if (typeof value === 'object') {
538
- if ('y' in value) return String(value.y ?? '');
539
- if ('r' in value) return String(value.r ?? '');
540
907
  try { return JSON.stringify(value); } catch { return String(value); }
541
908
  }
542
909
  return String(value);
543
910
  }
544
911
 
545
- /** @param {HTMLElement} root @returns {Record<string, unknown>} */
546
- function themeChartOptions(root) {
547
- if (typeof getComputedStyle !== 'function') return {};
548
- return {
549
- color: themeColour(root, '--zx-color-text'),
550
- borderColor: themeColour(root, '--zx-color-border')
551
- };
912
+ /** @param {unknown} aspectRatio @returns {string} A CSS `aspect-ratio` value; the default for none. */
913
+ function aspectRatioText(aspectRatio) {
914
+ return String(aspectRatio ?? '').trim() || String(Chart.defaults.aspectRatio);
552
915
  }
553
916
 
917
+ /** Attributes whose change anywhere above a chart can change the colours its tokens resolve to. */
918
+ const THEME_ATTRIBUTES = ['data-zx-theme', 'data-zx-preset'];
919
+ /** System preferences the semantic tokens answer to. */
920
+ const THEME_QUERIES = ['(prefers-color-scheme: dark)', '(prefers-contrast: more)', '(forced-colors: active)'];
921
+ const PALETTE_TOKENS = Array.from({ length: 8 }, (_, index) => `--zx-color-chart-${index + 1}`);
922
+
554
923
  /**
555
- * A colour token as the chart root paints it. The token's text may be a `light-dark()` pair, which
556
- * only an element can resolve (it takes that element's colour scheme) and a canvas cannot parse, so
557
- * the colour is read back from a hidden probe inside the root.
558
- * @param {HTMLElement} root
559
- * @param {string} token
560
- * @returns {string | undefined} The computed colour, or undefined where the token is not defined.
924
+ * The theme as the chart root resolves it. A token's text may be a `light-dark()` pair or a
925
+ * `color-mix()`, which only an element can resolve (it takes that element's colour scheme), so each
926
+ * colour is read back from a hidden probe inside the root; and the computed value may be written
927
+ * as `color(srgb …)` or `oklch(…)`, which an engine's own parser may not read, so it is rewritten
928
+ * as `#rrggbb` or `rgba()` (see `color.js`). A root outside a document resolves nothing.
929
+ * @param {HTMLElement} root Chart root.
930
+ * @returns {ChartTheme}
561
931
  */
562
- function themeColour(root, token) {
563
- if (!getComputedStyle(root).getPropertyValue(token).trim()) return undefined;
932
+ function chartTheme(root) {
933
+ /** @type {ChartTheme} */
934
+ const theme = { palette: [] };
935
+ if (typeof getComputedStyle !== 'function' || !root.isConnected) return theme;
936
+ const declared = getComputedStyle(root);
564
937
  const probe = h('span', { hidden: true });
565
- probe.style.color = `var(${token})`;
566
938
  root.append(probe);
567
- const colour = getComputedStyle(probe).color;
939
+ const read = (token) => {
940
+ if (!declared.getPropertyValue(token).trim()) return undefined;
941
+ probe.style.color = `var(${token})`;
942
+ return engineColor(getComputedStyle(probe).color, root.ownerDocument);
943
+ };
944
+ const color = read('--zx-color-text');
945
+ const borderColor = read('--zx-color-border');
946
+ const background = read('--zx-color-bg-surface');
947
+ if (color) theme.color = color;
948
+ if (borderColor) theme.borderColor = borderColor;
949
+ if (background) theme.background = background;
950
+ theme.palette = /** @type {string[]} */ (PALETTE_TOKENS.map(read).filter(Boolean));
568
951
  probe.remove();
569
- return colour || undefined;
952
+ return theme;
953
+ }
954
+
955
+ /** @param {ChartTheme} theme @returns {string} One string per distinct theme. */
956
+ function themeKey(theme) {
957
+ return [theme.color ?? '', theme.borderColor ?? '', theme.background ?? '', ...theme.palette].join('|');
570
958
  }
571
959
 
572
960
  /** @param {unknown} error @param {unknown} fallback @returns {string} */