@zeyos/zx 5.7.1 → 5.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (326) hide show
  1. package/CHANGELOG.md +296 -0
  2. package/README.md +47 -9
  3. package/dist/types/components/activity-item/activity-item.d.ts +14 -3
  4. package/dist/types/components/agent-avatar/agent-avatar.d.ts +165 -0
  5. package/dist/types/components/agent-avatar/agent-face.d.ts +93 -0
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +21 -9
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +26 -0
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +3 -1
  9. package/dist/types/components/approval-card/approval-card.d.ts +31 -2
  10. package/dist/types/components/aurora/aurora.d.ts +31 -5
  11. package/dist/types/components/calendar/calendar.d.ts +39 -26
  12. package/dist/types/components/chart/chart.d.ts +250 -20
  13. package/dist/types/components/chart/color.d.ts +66 -0
  14. package/dist/types/components/chart/svg-adapter.d.ts +103 -0
  15. package/dist/types/components/chart/svg-geometry.d.ts +203 -0
  16. package/dist/types/components/check-button/check-button.d.ts +1 -4
  17. package/dist/types/components/checklist/checklist.d.ts +19 -5
  18. package/dist/types/components/code-editor/code-editor.d.ts +55 -1
  19. package/dist/types/components/composer/composer.d.ts +41 -6
  20. package/dist/types/components/context-menu/context-menu.d.ts +36 -8
  21. package/dist/types/components/copy/copy-button.d.ts +6 -0
  22. package/dist/types/components/copy/copy-input.d.ts +1 -0
  23. package/dist/types/components/date-picker/date-picker.d.ts +14 -0
  24. package/dist/types/components/date-picker/time-picker.d.ts +26 -17
  25. package/dist/types/components/datebox/datebox.d.ts +8 -4
  26. package/dist/types/components/dialog/dialog.d.ts +13 -2
  27. package/dist/types/components/empty-state/empty-state.d.ts +10 -1
  28. package/dist/types/components/field/field.d.ts +4 -2
  29. package/dist/types/components/form/form.d.ts +2 -1
  30. package/dist/types/components/kanban-view/kanban-card.d.ts +7 -0
  31. package/dist/types/components/kanban-view/kanban-view.d.ts +15 -3
  32. package/dist/types/components/launcher/launcher.d.ts +26 -0
  33. package/dist/types/components/master-panel/master-panel.d.ts +9 -4
  34. package/dist/types/components/menu-button/menu-button.d.ts +29 -5
  35. package/dist/types/components/message/message.d.ts +308 -5
  36. package/dist/types/components/modal/modal.d.ts +11 -0
  37. package/dist/types/components/modal/native-dialog.d.ts +40 -0
  38. package/dist/types/components/module-bar/module-bar.d.ts +9 -2
  39. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +5 -4
  40. package/dist/types/components/number-field/number-field.d.ts +7 -0
  41. package/dist/types/components/pagination/pagination.d.ts +341 -19
  42. package/dist/types/components/run-status/run-status.d.ts +26 -0
  43. package/dist/types/components/run-trace/run-trace.d.ts +10 -6
  44. package/dist/types/components/search/search.d.ts +16 -4
  45. package/dist/types/components/select/select.d.ts +19 -1
  46. package/dist/types/components/sheet/sheet.d.ts +18 -4
  47. package/dist/types/components/slider/slider.d.ts +2 -1
  48. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -3
  49. package/dist/types/components/stepper/stepper.d.ts +17 -4
  50. package/dist/types/components/surface/catalog.d.ts +61 -17
  51. package/dist/types/components/surface/surface.d.ts +6 -4
  52. package/dist/types/components/table/table.d.ts +207 -5
  53. package/dist/types/components/table/window.d.ts +25 -1
  54. package/dist/types/components/toggle/toggle.d.ts +38 -6
  55. package/dist/types/components/tooltip/tooltip.d.ts +5 -4
  56. package/dist/types/components/tree/tree.d.ts +43 -6
  57. package/dist/types/components/truncate/truncate.d.ts +4 -2
  58. package/dist/types/components/value-list/value-list.d.ts +9 -2
  59. package/dist/types/core/date.d.ts +2 -1
  60. package/dist/types/core/drag-axis.d.ts +10 -5
  61. package/dist/types/core/export.d.ts +2 -2
  62. package/dist/types/core/format.d.ts +3 -1
  63. package/dist/types/core/icons.d.ts +36 -3
  64. package/dist/types/core/keyboard.d.ts +7 -3
  65. package/dist/types/core/messages.d.ts +3 -0
  66. package/dist/types/core/storage.d.ts +4 -3
  67. package/dist/types/core/util.d.ts +3 -1
  68. package/dist/types/elements/define.d.ts +5 -2
  69. package/dist/types/index.d.ts +6 -4
  70. package/dist/types/internal/agent-model.d.ts +99 -0
  71. package/dist/types/internal/app-rail.d.ts +37 -2
  72. package/dist/types/internal/collections.d.ts +18 -0
  73. package/dist/types/internal/menu-items.d.ts +27 -0
  74. package/dist/types/internal/overlay-content.d.ts +23 -0
  75. package/dist/types/internal/presence-loop.d.ts +5 -2
  76. package/dist/types/locales/index.d.ts +3 -0
  77. package/dist/types/zeyos/calendar.d.ts +43 -7
  78. package/dist/types/zeyos/connect.d.ts +4 -0
  79. package/dist/types/zeyos/form.d.ts +13 -5
  80. package/dist/types/zeyos/select.d.ts +5 -2
  81. package/dist/types/zeyos/table.d.ts +16 -8
  82. package/dist/types/zeyos/view.d.ts +2 -1
  83. package/dist/zx-zeyos.esm.js +2998 -451
  84. package/dist/zx-zeyos.esm.min.js +4 -4
  85. package/dist/zx.core.css +4 -0
  86. package/dist/zx.core.min.css +1 -1
  87. package/dist/zx.css +948 -48
  88. package/dist/zx.esm.js +7432 -3408
  89. package/dist/zx.esm.min.js +26 -26
  90. package/dist/zx.global.js +7432 -3408
  91. package/dist/zx.global.min.js +26 -26
  92. package/dist/zx.layered.css +950 -48
  93. package/dist/zx.layered.min.css +1 -1
  94. package/dist/zx.min.css +1 -1
  95. package/docs/agent-catalog.json +159 -1
  96. package/docs/agent-surfaces.md +21 -21
  97. package/docs/api.json +3122 -528
  98. package/docs/components/account-menu.md +24 -0
  99. package/docs/components/activity-item.md +23 -0
  100. package/docs/components/activity-list.md +28 -0
  101. package/docs/components/agent-avatar.md +59 -0
  102. package/docs/components/agent-thread.md +275 -0
  103. package/docs/components/app-icon.md +36 -0
  104. package/docs/components/app-sidebar.md +92 -0
  105. package/docs/components/approval-card.md +71 -0
  106. package/docs/components/aurora.md +34 -0
  107. package/docs/components/avatar.md +37 -0
  108. package/docs/components/badge.md +36 -0
  109. package/docs/components/block-view.md +34 -0
  110. package/docs/components/breadcrumb.md +20 -0
  111. package/docs/components/button.md +23 -0
  112. package/docs/components/calendar.md +68 -0
  113. package/docs/components/card-view.md +73 -0
  114. package/docs/components/card.md +25 -0
  115. package/docs/components/chart.md +109 -0
  116. package/docs/components/check-button.md +16 -0
  117. package/docs/components/checklist.md +19 -0
  118. package/docs/components/code-editor.md +38 -0
  119. package/docs/components/composer.md +107 -0
  120. package/docs/components/context-menu.md +32 -0
  121. package/docs/components/copy.md +37 -0
  122. package/docs/components/data-filter.md +16 -0
  123. package/docs/components/date-picker.md +31 -0
  124. package/docs/components/date-range.md +21 -0
  125. package/docs/components/datebox.md +31 -0
  126. package/docs/components/dialog.md +25 -0
  127. package/docs/components/dock.md +57 -0
  128. package/docs/components/dropdown.md +39 -0
  129. package/docs/components/elements.md +63 -0
  130. package/docs/components/empty-state.md +17 -0
  131. package/docs/components/entity-ref.md +26 -0
  132. package/docs/components/field-upload.md +18 -0
  133. package/docs/components/file-item.md +27 -0
  134. package/docs/components/file-list.md +23 -0
  135. package/docs/components/filter-panel.md +45 -0
  136. package/docs/components/filter.md +47 -0
  137. package/docs/components/finder.md +25 -0
  138. package/docs/components/form-widgets.md +42 -0
  139. package/docs/components/form.md +80 -0
  140. package/docs/components/grid.md +26 -0
  141. package/docs/components/groupbox.md +11 -0
  142. package/docs/components/helpers.md +359 -0
  143. package/docs/components/icons.md +87 -0
  144. package/docs/components/index.md +99 -0
  145. package/docs/components/kanban-view.md +42 -0
  146. package/docs/components/kbd.md +23 -0
  147. package/docs/components/kernel.md +41 -0
  148. package/docs/components/launcher.md +66 -0
  149. package/docs/components/layout.md +33 -0
  150. package/docs/components/list-toolbar.md +38 -0
  151. package/docs/components/loading.md +48 -0
  152. package/docs/components/menu-button.md +47 -0
  153. package/docs/components/message.md +76 -0
  154. package/docs/components/modal.md +27 -0
  155. package/docs/components/module-bar.md +71 -0
  156. package/docs/components/multi-value-editor.md +16 -0
  157. package/docs/components/navigation-bar.md +22 -0
  158. package/docs/components/number-field.md +34 -0
  159. package/docs/components/pagination.md +73 -0
  160. package/docs/components/panel.md +28 -0
  161. package/docs/components/prompt-starters.md +40 -0
  162. package/docs/components/prose.md +38 -0
  163. package/docs/components/questionnaire.md +115 -0
  164. package/docs/components/rating.md +19 -0
  165. package/docs/components/run-status.md +50 -0
  166. package/docs/components/run-trace.md +72 -0
  167. package/docs/components/search.md +11 -0
  168. package/docs/components/select.md +129 -0
  169. package/docs/components/sheet-stack.md +39 -0
  170. package/docs/components/sheet.md +77 -0
  171. package/docs/components/skeleton.md +27 -0
  172. package/docs/components/slider.md +29 -0
  173. package/docs/components/sort-control.md +21 -0
  174. package/docs/components/source-list.md +30 -0
  175. package/docs/components/split-view.md +12 -0
  176. package/docs/components/stat-tile.md +49 -0
  177. package/docs/components/stepper.md +27 -0
  178. package/docs/components/surface.md +152 -0
  179. package/docs/components/tabbox.md +33 -0
  180. package/docs/components/table-view.md +43 -0
  181. package/docs/components/table.md +232 -0
  182. package/docs/components/tag-picker.md +39 -0
  183. package/docs/components/timebox.md +16 -0
  184. package/docs/components/toggle.md +21 -0
  185. package/docs/components/tokens.md +82 -0
  186. package/docs/components/toolbar.md +26 -0
  187. package/docs/components/tooltip.md +16 -0
  188. package/docs/components/tree.md +48 -0
  189. package/docs/components/truncate.md +21 -0
  190. package/docs/components/value-list.md +14 -0
  191. package/docs/components/view-settings.md +56 -0
  192. package/docs/components/workspace-switcher.md +42 -0
  193. package/docs/components/zeyos.md +196 -0
  194. package/docs/llms-small.txt +299 -0
  195. package/docs/llms.md +697 -100
  196. package/docs/llms.txt +46 -19
  197. package/package.json +9 -4
  198. package/src/components/activity-item/activity-item.js +21 -2
  199. package/src/components/agent-avatar/agent-avatar.css +195 -0
  200. package/src/components/agent-avatar/agent-avatar.js +333 -0
  201. package/src/components/agent-avatar/agent-face.js +292 -0
  202. package/src/components/agent-thread/ag-ui.js +44 -11
  203. package/src/components/agent-thread/agent-thread.js +103 -11
  204. package/src/components/agent-thread/ui-message-stream.js +3 -1
  205. package/src/components/app-rail/app-rail.css +5 -0
  206. package/src/components/app-sidebar/app-sidebar.css +3 -0
  207. package/src/components/app-sidebar/app-sidebar.js +4 -3
  208. package/src/components/approval-card/approval-card.css +6 -0
  209. package/src/components/approval-card/approval-card.js +55 -7
  210. package/src/components/aurora/aurora.css +149 -14
  211. package/src/components/aurora/aurora.js +49 -6
  212. package/src/components/calendar/calendar.css +6 -2
  213. package/src/components/calendar/calendar.js +127 -47
  214. package/src/components/card-view/card-view.js +5 -6
  215. package/src/components/chart/chart.css +159 -1
  216. package/src/components/chart/chart.js +450 -62
  217. package/src/components/chart/color.js +297 -0
  218. package/src/components/chart/svg-adapter.js +576 -0
  219. package/src/components/chart/svg-geometry.js +323 -0
  220. package/src/components/check-button/check-button.js +3 -18
  221. package/src/components/checklist/checklist.js +46 -17
  222. package/src/components/checklist/field-adapter.js +4 -1
  223. package/src/components/code-editor/code-editor.css +33 -0
  224. package/src/components/code-editor/code-editor.js +97 -8
  225. package/src/components/code-editor/field-adapter.js +3 -0
  226. package/src/components/composer/composer.css +3 -0
  227. package/src/components/composer/composer.js +100 -22
  228. package/src/components/context-menu/context-menu.js +41 -5
  229. package/src/components/copy/copy-button.js +9 -1
  230. package/src/components/copy/copy-input.js +5 -0
  231. package/src/components/data-filter/filter-core.js +0 -1
  232. package/src/components/date-picker/date-picker.css +8 -0
  233. package/src/components/date-picker/date-picker.js +47 -8
  234. package/src/components/date-picker/date-range-picker.js +1 -1
  235. package/src/components/date-picker/month-picker.js +19 -3
  236. package/src/components/date-picker/time-picker.js +54 -19
  237. package/src/components/datebox/date-range-box.js +7 -3
  238. package/src/components/datebox/datebox.js +32 -6
  239. package/src/components/dialog/dialog.css +6 -0
  240. package/src/components/dialog/dialog.js +22 -30
  241. package/src/components/dropdown/dropdown.js +1 -18
  242. package/src/components/empty-state/empty-state.js +21 -2
  243. package/src/components/field/field.js +19 -3
  244. package/src/components/fieldset/fieldset.js +3 -1
  245. package/src/components/filter/filter.js +9 -0
  246. package/src/components/form/form.js +19 -2
  247. package/src/components/kanban-view/kanban-card.js +15 -2
  248. package/src/components/kanban-view/kanban-view.css +21 -0
  249. package/src/components/kanban-view/kanban-view.js +29 -16
  250. package/src/components/launcher/launcher.css +14 -0
  251. package/src/components/launcher/launcher.js +54 -9
  252. package/src/components/master-panel/master-panel.js +24 -22
  253. package/src/components/menu-button/menu-button.js +26 -4
  254. package/src/components/message/message.css +228 -29
  255. package/src/components/message/message.js +664 -30
  256. package/src/components/modal/modal.js +70 -25
  257. package/src/components/modal/native-dialog.js +91 -0
  258. package/src/components/module-bar/module-bar.css +3 -0
  259. package/src/components/module-bar/module-bar.js +17 -4
  260. package/src/components/multi-value-editor/multi-value-editor.css +7 -2
  261. package/src/components/multi-value-editor/multi-value-editor.js +3 -2
  262. package/src/components/navigation-bar/navigation-bar.js +13 -1
  263. package/src/components/number-field/field-adapter.js +3 -0
  264. package/src/components/number-field/number-field.js +2 -1
  265. package/src/components/pagination/pagination.css +26 -2
  266. package/src/components/pagination/pagination.js +551 -65
  267. package/src/components/prose/prose.js +7 -1
  268. package/src/components/rating/field-adapter.js +3 -0
  269. package/src/components/run-status/run-status.js +43 -3
  270. package/src/components/run-trace/run-trace.js +15 -7
  271. package/src/components/search/search.js +3 -18
  272. package/src/components/select/field-adapter.js +8 -1
  273. package/src/components/select/select.js +68 -13
  274. package/src/components/sheet/sheet.js +27 -8
  275. package/src/components/slider/field-adapter.js +3 -0
  276. package/src/components/slider/slider.js +4 -6
  277. package/src/components/stat-tile/stat-tile.js +24 -9
  278. package/src/components/stepper/stepper.css +15 -0
  279. package/src/components/stepper/stepper.js +34 -2
  280. package/src/components/surface/catalog.js +185 -28
  281. package/src/components/surface/surface.js +10 -5
  282. package/src/components/tabbox/tabbox.js +13 -1
  283. package/src/components/table/table.css +160 -2
  284. package/src/components/table/table.js +479 -52
  285. package/src/components/table/window.js +46 -4
  286. package/src/components/table-view/table-view.js +1 -10
  287. package/src/components/tag-picker/field-adapter.js +3 -0
  288. package/src/components/tag-picker/tag-picker.js +2 -0
  289. package/src/components/timebox/field-adapter.js +3 -0
  290. package/src/components/toggle/toggle.js +51 -27
  291. package/src/components/tooltip/tooltip.js +21 -14
  292. package/src/components/tree/tree.js +87 -14
  293. package/src/components/truncate/truncate.js +21 -5
  294. package/src/components/value-list/value-list.js +37 -9
  295. package/src/components/view-settings/view-settings.js +1 -5
  296. package/src/core/component.js +34 -2
  297. package/src/core/date.js +5 -4
  298. package/src/core/drag-axis.js +24 -7
  299. package/src/core/export.js +4 -4
  300. package/src/core/fontawesome.js +34 -3
  301. package/src/core/format.js +3 -1
  302. package/src/core/http.js +23 -11
  303. package/src/core/icons.js +51 -10
  304. package/src/core/keyboard.js +83 -9
  305. package/src/core/messages.js +3 -0
  306. package/src/core/position.js +2 -2
  307. package/src/core/storage.js +80 -31
  308. package/src/core/util.js +16 -5
  309. package/src/elements/define.js +82 -47
  310. package/src/elements/kit.js +46 -35
  311. package/src/index.js +8 -4
  312. package/src/internal/agent-model.js +152 -0
  313. package/src/internal/app-rail.js +53 -2
  314. package/src/internal/collections.js +25 -0
  315. package/src/internal/menu-items.js +59 -0
  316. package/src/internal/overlay-content.js +35 -0
  317. package/src/internal/presence-loop.js +61 -14
  318. package/src/locales/de.js +3 -0
  319. package/src/zeyos/calendar.js +81 -19
  320. package/src/zeyos/connect.js +5 -1
  321. package/src/zeyos/form.js +29 -10
  322. package/src/zeyos/select.js +36 -12
  323. package/src/zeyos/table.js +43 -11
  324. package/src/zeyos/view.js +2 -1
  325. package/styles/tokens/semantic.css +7 -1
  326. package/styles/zx.css +1 -0
@@ -0,0 +1,297 @@
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
+
19
+ /** @typedef {{r: number, g: number, b: number, a: number}} RgbaColor Red, green, blue 0–255 and alpha 0–1, unrounded. */
20
+
21
+ const LINEAR_P3_TO_XYZ = [
22
+ [0.4865709486482162, 0.26566769316909306, 0.1982172852343625],
23
+ [0.2289745640697488, 0.6917385218365064, 0.079286914093745],
24
+ [0, 0.04511338185890264, 1.043944368900976]
25
+ ];
26
+ const XYZ_TO_LINEAR_SRGB = [
27
+ [3.2409699419045226, -1.537383177570094, -0.4986107602930034],
28
+ [-0.9692436362808796, 1.8759675015077202, 0.04155505740717559],
29
+ [0.05563007969699366, -0.20397695888897652, 1.0569715142428786]
30
+ ];
31
+ /** Bradford chromatic adaptation from the D50 white `lab()` uses to the D65 white of sRGB. */
32
+ const D50_TO_D65 = [
33
+ [0.9554734527042182, -0.023098536874261423, 0.0632593086610217],
34
+ [-0.028369706963208136, 1.0099954580058226, 0.021041398966943008],
35
+ [0.012314001688319899, -0.020507696433477912, 1.3303659366080753]
36
+ ];
37
+ const D50_WHITE = [0.3457 / 0.3585, 1, (1 - 0.3457 - 0.3585) / 0.3585];
38
+
39
+ /**
40
+ * Parses a computed CSS colour into sRGB channels.
41
+ * @param {unknown} value Colour text.
42
+ * @returns {RgbaColor|null} Null when the text is not one of the supported syntaxes.
43
+ */
44
+ export function parseCssColor(value) {
45
+ if (typeof value !== 'string') return null;
46
+ const text = value.trim().toLowerCase();
47
+ if (!text) return null;
48
+ if (text === 'transparent') return { r: 0, g: 0, b: 0, a: 0 };
49
+ if (text.startsWith('#')) return parseHex(text.slice(1));
50
+
51
+ const call = /^([a-z][a-z0-9-]*)\(\s*(.*?)\s*\)$/s.exec(text);
52
+ if (!call) return null;
53
+ const [, name, body] = call;
54
+ const [channelText, alphaText, ...extra] = body.split('/');
55
+ if (extra.length) return null;
56
+ const parts = channelText.split(/[\s,]+/).filter(Boolean);
57
+ // The legacy comma syntax carries alpha as a fourth argument.
58
+ let alphaPart = alphaText?.trim();
59
+ if (alphaPart === undefined && name !== 'color' && parts.length === 4) alphaPart = parts.pop();
60
+ const alpha = alphaPart === undefined ? 1 : clamp(number(alphaPart, 1), 0, 1);
61
+ if (Number.isNaN(alpha)) return null;
62
+
63
+ const rgb = channels(name, parts);
64
+ if (!rgb || rgb.some(Number.isNaN)) return null;
65
+ return { r: clamp(rgb[0], 0, 1) * 255, g: clamp(rgb[1], 0, 1) * 255, b: clamp(rgb[2], 0, 1) * 255, a: alpha };
66
+ }
67
+
68
+ /**
69
+ * Rewrites a computed CSS colour in a syntax every colour parser reads.
70
+ * @param {unknown} value Colour text, in any syntax `parseCssColor()` supports.
71
+ * @returns {string|null} `#rrggbb` for an opaque colour, `rgba(r, g, b, a)` for a translucent one,
72
+ * null when the text could not be read.
73
+ */
74
+ export function legacyColor(value) {
75
+ const color = parseCssColor(value);
76
+ return color ? formatLegacyColor(color) : null;
77
+ }
78
+
79
+ /**
80
+ * The same colour at another opacity, for the fill under a line or inside a point.
81
+ * @param {unknown} value Colour text.
82
+ * @param {number} alpha Opacity from 0 to 1; it replaces the colour's own.
83
+ * @returns {string|null} `rgba(r, g, b, a)` (or `#rrggbb` at full opacity), null for unreadable text.
84
+ */
85
+ export function withAlpha(value, alpha) {
86
+ const color = parseCssColor(value);
87
+ return color ? formatLegacyColor({ ...color, a: clamp(Number(alpha), 0, 1) }) : null;
88
+ }
89
+
90
+ /**
91
+ * Serialises channels in the legacy syntax.
92
+ * @param {RgbaColor} color Channels.
93
+ * @returns {string}
94
+ */
95
+ export function formatLegacyColor({ r, g, b, a }) {
96
+ const bytes = [r, g, b].map((channel) => clamp(Math.round(channel), 0, 255));
97
+ const alpha = Math.round(clamp(a, 0, 1) * 1000) / 1000;
98
+ if (alpha === 1) return `#${bytes.map((byte) => byte.toString(16).padStart(2, '0')).join('')}`;
99
+ return `rgba(${bytes.join(', ')}, ${alpha})`;
100
+ }
101
+
102
+ /**
103
+ * Reads a colour by painting it: whatever the browser can paint comes back as 8-bit sRGB, so this
104
+ * covers syntaxes `legacyColor()` does not parse. It needs a 2D canvas, and a faint colour loses
105
+ * precision to the canvas's premultiplied 8-bit storage — which is why the parser goes first.
106
+ * @param {unknown} value Colour text.
107
+ * @param {Document|null} [ownerDocument] Document that creates the canvas.
108
+ * @returns {string|null} A legacy colour string, or null when the colour is invalid or no canvas is
109
+ * available.
110
+ */
111
+ export function paintedColor(value, ownerDocument = globalThis.document ?? null) {
112
+ if (typeof value !== 'string' || !value.trim() || !ownerDocument) return null;
113
+ try {
114
+ const canvas = ownerDocument.createElement('canvas');
115
+ canvas.width = 1;
116
+ canvas.height = 1;
117
+ const context = canvas.getContext('2d', { willReadFrequently: true });
118
+ if (!context) return null;
119
+ // An invalid colour leaves the previous fill style in place; a second sentinel tells
120
+ // "rejected" from "happens to equal the first one".
121
+ const accepted = ['#010203', '#040506'].some((sentinel) => {
122
+ context.fillStyle = sentinel;
123
+ context.fillStyle = value;
124
+ return context.fillStyle !== sentinel;
125
+ });
126
+ if (!accepted) return null;
127
+ context.clearRect(0, 0, 1, 1);
128
+ context.fillRect(0, 0, 1, 1);
129
+ const [r, g, b, a] = context.getImageData(0, 0, 1, 1).data;
130
+ return formatLegacyColor({ r, g, b, a: a / 255 });
131
+ } catch {
132
+ return null;
133
+ }
134
+ }
135
+
136
+ /**
137
+ * A colour as an engine can read it: parsed where possible, painted otherwise.
138
+ * @param {unknown} value Computed colour text.
139
+ * @param {Document|null} [ownerDocument] Document for the canvas fallback.
140
+ * @returns {string|undefined} Undefined when neither route could read it.
141
+ */
142
+ export function engineColor(value, ownerDocument) {
143
+ return legacyColor(value) ?? paintedColor(value, ownerDocument) ?? undefined;
144
+ }
145
+
146
+ /** @param {string} hex @returns {RgbaColor|null} */
147
+ function parseHex(hex) {
148
+ if (!/^(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/.test(hex)) return null;
149
+ const digits = hex.length <= 4 ? Array.from(hex, (digit) => digit + digit) : hex.match(/../g) ?? [];
150
+ const [r, g, b, a = 255] = digits.map((pair) => Number.parseInt(pair, 16));
151
+ return { r, g, b, a: a / 255 };
152
+ }
153
+
154
+ /**
155
+ * @param {string} name Function name.
156
+ * @param {string[]} parts Channel tokens.
157
+ * @returns {number[]|null} Gamma-encoded sRGB channels, 0–1 but not yet clipped.
158
+ */
159
+ function channels(name, parts) {
160
+ if (name === 'color') {
161
+ if (parts.length !== 4) return null;
162
+ const [space, ...rest] = parts;
163
+ const [x, y, z] = rest.map((part) => number(part, 1));
164
+ if (space === 'srgb') return [x, y, z];
165
+ if (space === 'srgb-linear') return [x, y, z].map(encode);
166
+ if (space === 'display-p3') return fromXyz(multiply(LINEAR_P3_TO_XYZ, [x, y, z].map(decode)));
167
+ if (space === 'xyz' || space === 'xyz-d65') return fromXyz([x, y, z]);
168
+ if (space === 'xyz-d50') return fromXyz(multiply(D50_TO_D65, [x, y, z]));
169
+ return null;
170
+ }
171
+ if (parts.length !== 3) return null;
172
+ const [first, second, third] = parts;
173
+ switch (name) {
174
+ case 'rgb':
175
+ case 'rgba':
176
+ return parts.map((part) => number(part, 255) / 255);
177
+ case 'hsl':
178
+ case 'hsla':
179
+ return hslToRgb(angle(first), number(second, 100) / 100, number(third, 100) / 100);
180
+ case 'hwb':
181
+ return hwbToRgb(angle(first), number(second, 100) / 100, number(third, 100) / 100);
182
+ case 'oklab':
183
+ return oklabToRgb(number(first, 1), number(second, 0.4), number(third, 0.4));
184
+ case 'oklch':
185
+ return oklabToRgb(number(first, 1), ...polar(number(second, 0.4), angle(third)));
186
+ case 'lab':
187
+ return labToRgb(number(first, 100), number(second, 125), number(third, 125));
188
+ case 'lch':
189
+ return labToRgb(number(first, 100), ...polar(number(second, 150), angle(third)));
190
+ default:
191
+ return null;
192
+ }
193
+ }
194
+
195
+ /**
196
+ * @param {string} token A number, a percentage, or `none`.
197
+ * @param {number} whole What 100% stands for.
198
+ * @returns {number} NaN for anything else.
199
+ */
200
+ function number(token, whole) {
201
+ if (token === 'none') return 0;
202
+ const match = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)(%?)$/.exec(token);
203
+ if (!match) return Number.NaN;
204
+ return match[2] ? Number(match[1]) / 100 * whole : Number(match[1]);
205
+ }
206
+
207
+ /** @param {string} token A hue with an optional unit. @returns {number} Degrees, NaN when unreadable. */
208
+ function angle(token) {
209
+ if (token === 'none') return 0;
210
+ const match = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)(deg|grad|rad|turn)?$/.exec(token);
211
+ if (!match) return Number.NaN;
212
+ const factor = { deg: 1, grad: 0.9, rad: 180 / Math.PI, turn: 360 }[match[2] ?? 'deg'];
213
+ return Number(match[1]) * factor;
214
+ }
215
+
216
+ /** @param {number} chroma @param {number} hue Degrees. @returns {[number, number]} */
217
+ function polar(chroma, hue) {
218
+ const radians = hue * Math.PI / 180;
219
+ return [chroma * Math.cos(radians), chroma * Math.sin(radians)];
220
+ }
221
+
222
+ /** @param {number} hue @param {number} saturation @param {number} lightness @returns {number[]} */
223
+ function hslToRgb(hue, saturation, lightness) {
224
+ const s = clamp(saturation, 0, 1);
225
+ const l = clamp(lightness, 0, 1);
226
+ const h = ((hue % 360) + 360) % 360;
227
+ const amount = s * Math.min(l, 1 - l);
228
+ const channel = (n) => {
229
+ const k = (n + h / 30) % 12;
230
+ return l - amount * Math.max(-1, Math.min(k - 3, 9 - k, 1));
231
+ };
232
+ return [channel(0), channel(8), channel(4)];
233
+ }
234
+
235
+ /** @param {number} hue @param {number} white @param {number} black @returns {number[]} */
236
+ function hwbToRgb(hue, white, black) {
237
+ const w = clamp(white, 0, 1);
238
+ const b = clamp(black, 0, 1);
239
+ if (w + b >= 1) return Array(3).fill(w / (w + b));
240
+ return hslToRgb(hue, 1, 0.5).map((channel) => channel * (1 - w - b) + w);
241
+ }
242
+
243
+ /** @param {number} lightness @param {number} a @param {number} b @returns {number[]} */
244
+ function oklabToRgb(lightness, a, b) {
245
+ const l = (lightness + 0.3963377774 * a + 0.2158037573 * b) ** 3;
246
+ const m = (lightness - 0.1055613458 * a - 0.0638541728 * b) ** 3;
247
+ const s = (lightness - 0.0894841775 * a - 1.291485548 * b) ** 3;
248
+ return [
249
+ 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
250
+ -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
251
+ -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s
252
+ ].map(encode);
253
+ }
254
+
255
+ /** @param {number} lightness @param {number} a @param {number} b @returns {number[]} */
256
+ function labToRgb(lightness, a, b) {
257
+ const kappa = 24389 / 27;
258
+ const epsilon = 216 / 24389;
259
+ const fy = (lightness + 16) / 116;
260
+ const fx = a / 500 + fy;
261
+ const fz = fy - b / 200;
262
+ const xyz = [
263
+ fx ** 3 > epsilon ? fx ** 3 : (116 * fx - 16) / kappa,
264
+ lightness > kappa * epsilon ? fy ** 3 : lightness / kappa,
265
+ fz ** 3 > epsilon ? fz ** 3 : (116 * fz - 16) / kappa
266
+ ].map((component, index) => component * D50_WHITE[index]);
267
+ return fromXyz(multiply(D50_TO_D65, xyz));
268
+ }
269
+
270
+ /** @param {number[]} xyz D65 XYZ. @returns {number[]} */
271
+ function fromXyz(xyz) {
272
+ return multiply(XYZ_TO_LINEAR_SRGB, xyz).map(encode);
273
+ }
274
+
275
+ /** @param {number[][]} matrix @param {number[]} vector @returns {number[]} */
276
+ function multiply(matrix, vector) {
277
+ return matrix.map((row) => row[0] * vector[0] + row[1] * vector[1] + row[2] * vector[2]);
278
+ }
279
+
280
+ /** Linear light to the sRGB transfer curve. @param {number} value @returns {number} */
281
+ function encode(value) {
282
+ const sign = value < 0 ? -1 : 1;
283
+ const absolute = Math.abs(value);
284
+ return absolute <= 0.0031308 ? value * 12.92 : sign * (1.055 * absolute ** (1 / 2.4) - 0.055);
285
+ }
286
+
287
+ /** The sRGB transfer curve to linear light. @param {number} value @returns {number} */
288
+ function decode(value) {
289
+ const sign = value < 0 ? -1 : 1;
290
+ const absolute = Math.abs(value);
291
+ return absolute <= 0.04045 ? value / 12.92 : sign * ((absolute + 0.055) / 1.055) ** 2.4;
292
+ }
293
+
294
+ /** @param {number} value @param {number} min @param {number} max @returns {number} NaN stays NaN. */
295
+ function clamp(value, min, max) {
296
+ return Number.isNaN(value) ? value : Math.min(max, Math.max(min, value));
297
+ }