@lostgradient/cinder 0.27.1 → 0.28.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 (261) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/components.json +1 -1
  3. package/dist/_internal/code-highlighter-context.d.ts +28 -0
  4. package/dist/cli/index.js +12 -8
  5. package/dist/components/approval-card/index.js +4 -4
  6. package/dist/components/button/button.css +25 -0
  7. package/dist/components/calendar/calendar.css +14 -0
  8. package/dist/components/capability-gate/capability-gate.css +5 -0
  9. package/dist/components/checkbox/checkbox.css +19 -0
  10. package/dist/components/chip/chip.css +14 -0
  11. package/dist/components/code-block/code-block.d.svelte.ts +1 -1
  12. package/dist/components/code-block/code-block.examples.json +1 -1
  13. package/dist/components/code-block/code-block.schema.js +3 -3
  14. package/dist/components/code-block/code-block.svelte.d.ts +1 -1
  15. package/dist/components/code-block/code-block.types.d.ts +14 -12
  16. package/dist/components/code-block/index.js +2 -2
  17. package/dist/components/color-picker/color-picker.css +2 -0
  18. package/dist/components/combobox/combobox.css +9 -1
  19. package/dist/components/command-palette/command-palette.css +7 -5
  20. package/dist/components/file-upload/file-upload.css +2 -1
  21. package/dist/components/guidance-region/index.css +1 -1
  22. package/dist/components/image/image.examples.json +1 -1
  23. package/dist/components/input/input.css +20 -6
  24. package/dist/components/json-schema-editor/index.js +5 -5
  25. package/dist/components/json-schema-editor/json-view-highlighter.d.ts +14 -0
  26. package/dist/components/key-value-editor/index.css +1 -1
  27. package/dist/components/modal-region/index.css +1 -1
  28. package/dist/components/multi-select/multi-select.css +9 -0
  29. package/dist/components/pagination/pagination.css +12 -0
  30. package/dist/components/pin-input/pin-input.css +9 -1
  31. package/dist/components/radio-group/radio-group.css +16 -0
  32. package/dist/components/run-step-timeline/index.js +2 -2
  33. package/dist/components/schema-form/index.js +2 -2
  34. package/dist/components/schema-form/schema-form.css +9 -0
  35. package/dist/components/segmented-control/segmented-control.css +3 -3
  36. package/dist/components/selection-popover/selection-popover.css +7 -1
  37. package/dist/components/tag-input/tag-input.css +10 -1
  38. package/dist/components/terminal-frame/index.js +2 -2
  39. package/dist/components/terminal-frame/terminal-frame.schema.js +2 -2
  40. package/dist/components/terminal-frame/terminal-frame.types.d.ts +8 -0
  41. package/dist/components/textarea/textarea.css +1 -1
  42. package/dist/components/toggle/toggle.css +16 -0
  43. package/dist/components/tree/tree.examples.json +1 -1
  44. package/dist/components/virtual-list/index.js +2 -2
  45. package/dist/components/virtual-list/virtual-list.css +42 -9
  46. package/dist/highlighters/shiki/default.d.ts +13 -1
  47. package/dist/highlighters/shiki/default.js +2 -2
  48. package/dist/highlighters/shiki/index.d.ts +20 -12
  49. package/dist/highlighters/shiki/index.js +2 -2
  50. package/dist/index.browser.css +1 -1
  51. package/dist/index.d.ts +2 -0
  52. package/dist/index.js +23 -23
  53. package/dist/scripts/knowledge/index.d.ts +5 -1
  54. package/dist/server/components/approval-card/index.js +1 -1
  55. package/dist/server/components/code-block/index.js +1 -1
  56. package/dist/server/components/color-field/index.js +2 -2
  57. package/dist/server/components/color-picker/index.js +2 -2
  58. package/dist/server/components/json-schema-editor/index.js +2 -2
  59. package/dist/server/components/run-step-timeline/index.js +1 -1
  60. package/dist/server/components/terminal-frame/index.js +1 -1
  61. package/dist/server/components/virtual-list/index.js +1 -1
  62. package/dist/server/github-dark-e7nywpbe.js +3 -0
  63. package/dist/server/github-light-bqtmm1zq.js +3 -0
  64. package/dist/server/highlighters/shiki/default.js +2 -2
  65. package/dist/server/highlighters/shiki/index.js +2 -2
  66. package/dist/server/index.js +6 -6
  67. package/dist/server/{index.server-4qyyw4y5.js → index.server-043cfznf.js} +1 -1
  68. package/dist/server/{index.server-p46tn4eb.js → index.server-09tjs48p.js} +2 -2
  69. package/dist/server/index.server-0hyvdf74.js +8 -0
  70. package/dist/server/{index.server-dxgkh9tk.js → index.server-17thvpd3.js} +1 -1
  71. package/dist/server/index.server-19z6hqd6.js +4 -0
  72. package/dist/server/index.server-31020qgk.js +3 -0
  73. package/dist/server/{index.server-w3nqzde5.js → index.server-45wmvjrn.js} +3 -3
  74. package/dist/server/{index.server-3tkgm2gn.js → index.server-6mb7w5g4.js} +2 -2
  75. package/dist/server/{index.server-2vxmn7x1.js → index.server-c5yajkkc.js} +4 -4
  76. package/dist/server/index.server-e6fknxd9.js +4 -0
  77. package/dist/server/index.server-fev4kwm0.js +4 -0
  78. package/dist/server/index.server-k4vjk75r.js +4 -0
  79. package/dist/server/index.server-mjbtd1gs.js +7 -0
  80. package/dist/server/{index.server-2bfkhzzq.js → index.server-rkp4py5n.js} +2 -2
  81. package/dist/server/index.server-wdz9tsq4.js +3 -0
  82. package/dist/server/index.server-zj9909hd.js +4 -0
  83. package/dist/server/json-68twtta3.js +3 -0
  84. package/dist/server/tokens/registry.generated.js +1 -1
  85. package/dist/server/tokens/runtime/index.js +92 -0
  86. package/dist/styles/check-token-contrast-test-values.d.ts +1 -3
  87. package/dist/styles/token-contrast-test-readers.d.ts +1 -1
  88. package/dist/tokens/registry.generated.js +2 -2
  89. package/dist/tokens/resolved/dark-reduced-motion.json +104 -43
  90. package/dist/tokens/resolved/dark.json +104 -43
  91. package/dist/tokens/resolved/light-reduced-motion.json +104 -43
  92. package/dist/tokens/resolved/light.json +104 -43
  93. package/dist/tokens/runtime/authoring-catalogue.d.ts +19 -0
  94. package/dist/tokens/runtime/authoring-catalogue.generated.d.ts +8 -0
  95. package/dist/tokens/runtime/authoring-palette.d.ts +25 -0
  96. package/dist/tokens/runtime/authoring-profiles.d.ts +48 -0
  97. package/dist/tokens/runtime/authoring-provenance.d.ts +31 -0
  98. package/dist/tokens/runtime/authoring-types.d.ts +182 -0
  99. package/dist/tokens/runtime/base-corpus.d.ts +29 -0
  100. package/dist/tokens/runtime/base-corpus.generated.d.ts +8 -0
  101. package/dist/tokens/runtime/context-order.d.ts +60 -0
  102. package/dist/tokens/runtime/context-stack.d.ts +11 -0
  103. package/dist/tokens/runtime/contrast/color-difference.d.ts +16 -0
  104. package/dist/{styles/color-contrast-utilities.d.ts → tokens/runtime/contrast/color-math.d.ts} +2 -17
  105. package/dist/tokens/runtime/contrast/color-mix.d.ts +3 -0
  106. package/dist/tokens/runtime/contrast/css-color.d.ts +29 -0
  107. package/dist/tokens/runtime/contrast/index.d.ts +7 -0
  108. package/dist/tokens/runtime/contrast/measure.d.ts +45 -0
  109. package/dist/tokens/runtime/contrast/pairings.d.ts +36 -0
  110. package/dist/tokens/runtime/contrast/thresholds.d.ts +47 -0
  111. package/dist/tokens/runtime/corpus-documents.d.ts +36 -0
  112. package/dist/tokens/runtime/corpus-validation.d.ts +10 -0
  113. package/dist/tokens/runtime/corpus.d.ts +35 -0
  114. package/dist/tokens/runtime/css-configuration.d.ts +1 -0
  115. package/dist/tokens/runtime/css-stylelint.d.ts +2 -0
  116. package/dist/tokens/runtime/css-support.d.ts +110 -0
  117. package/dist/tokens/runtime/evaluate.d.ts +95 -0
  118. package/dist/tokens/runtime/evaluated-provenance.d.ts +36 -0
  119. package/dist/tokens/runtime/index.d.ts +38 -0
  120. package/dist/tokens/runtime/index.js +95 -0
  121. package/dist/tokens/runtime/package-version.generated.d.ts +9 -0
  122. package/dist/tokens/runtime/projection.d.ts +32 -0
  123. package/dist/tokens/runtime/registry.d.ts +125 -0
  124. package/dist/tokens/runtime/resolve-extends.d.ts +30 -0
  125. package/dist/tokens/runtime/resolve-references.d.ts +49 -0
  126. package/dist/tokens/runtime/resolve-shared.d.ts +34 -0
  127. package/dist/tokens/runtime/resolve.d.ts +44 -0
  128. package/dist/tokens/runtime/resolver-order.d.ts +89 -0
  129. package/dist/tokens/runtime/source-digest.d.ts +20 -0
  130. package/dist/tokens/runtime/stylesheet-skeleton.d.ts +31 -0
  131. package/dist/tokens/runtime/theme-runtime.test-support.d.ts +24 -0
  132. package/dist/tokens/runtime/theme-sources.d.ts +46 -0
  133. package/dist/tokens/runtime/theme-stylesheet.d.ts +31 -0
  134. package/dist/tokens/runtime/types.d.ts +115 -0
  135. package/dist/tokens/runtime/validate-resolver.d.ts +31 -0
  136. package/dist/tokens/runtime/validate-schema.d.ts +22 -0
  137. package/dist/tokens/runtime/validate-tokens.d.ts +25 -0
  138. package/dist/tokens/runtime/validate-values.d.ts +33 -0
  139. package/dist/tokens/runtime/validate.d.ts +3 -0
  140. package/dist/tokens/runtime/value-color-parse.d.ts +128 -0
  141. package/dist/tokens/runtime/value-color.d.ts +85 -0
  142. package/dist/tokens/runtime/value-entry.d.ts +3 -0
  143. package/dist/tokens/runtime/value-formatters.d.ts +59 -0
  144. package/dist/tokens/sets/colors.tokens.json +65 -13
  145. package/dist/tokens/sets/foundation.tokens.json +23 -0
  146. package/dist/tokens/sets/semantic.tokens.json +136 -30
  147. package/dist/utilities/highlighter.d.ts +5 -5
  148. package/dist/utilities/retrying-loader-cache.d.ts +3 -6
  149. package/package.json +15 -3
  150. package/src/_internal/code-highlighter-context.ts +41 -0
  151. package/src/components/button/button.css +25 -0
  152. package/src/components/calendar/calendar.css +14 -0
  153. package/src/components/capability-gate/capability-gate.css +5 -0
  154. package/src/components/checkbox/checkbox.css +19 -0
  155. package/src/components/chip/chip.css +14 -0
  156. package/src/components/code-block/code-block.examples.json +1 -1
  157. package/src/components/code-block/code-block.schema.json +2 -2
  158. package/src/components/code-block/code-block.schema.ts +2 -2
  159. package/src/components/code-block/code-block.svelte +15 -19
  160. package/src/components/code-block/code-block.types.ts +14 -12
  161. package/src/components/color-picker/color-picker.css +2 -0
  162. package/src/components/combobox/combobox.css +9 -1
  163. package/src/components/command-palette/command-palette.css +7 -5
  164. package/src/components/file-upload/file-upload.css +2 -1
  165. package/src/components/image/image.examples.json +1 -1
  166. package/src/components/input/input.css +20 -6
  167. package/src/components/json-schema-editor/json-view-highlighter.ts +23 -0
  168. package/src/components/json-schema-editor/json-view.svelte +2 -0
  169. package/src/components/multi-select/multi-select.css +9 -0
  170. package/src/components/pagination/pagination.css +12 -0
  171. package/src/components/pin-input/pin-input.css +9 -1
  172. package/src/components/radio-group/radio-group.css +16 -0
  173. package/src/components/schema-form/schema-form.css +9 -0
  174. package/src/components/segmented-control/segmented-control.css +3 -3
  175. package/src/components/selection-popover/selection-popover.css +7 -1
  176. package/src/components/tag-input/tag-input.css +10 -1
  177. package/src/components/terminal-frame/terminal-frame.schema.json +5 -0
  178. package/src/components/terminal-frame/terminal-frame.schema.ts +6 -0
  179. package/src/components/terminal-frame/terminal-frame.svelte +6 -2
  180. package/src/components/terminal-frame/terminal-frame.types.ts +8 -0
  181. package/src/components/textarea/textarea.css +1 -1
  182. package/src/components/toggle/toggle.css +16 -0
  183. package/src/components/tree/tree.examples.json +1 -1
  184. package/src/components/virtual-list/virtual-list.css +42 -9
  185. package/src/components/virtual-list/virtual-list.svelte +54 -20
  186. package/src/highlighters/shiki/default.ts +13 -1
  187. package/src/highlighters/shiki/index.ts +20 -12
  188. package/src/index.ts +5 -0
  189. package/src/styles/foundation.css +33 -1
  190. package/src/styles/tokens-base.css +4 -4
  191. package/src/tokens/registry.generated.json +3 -3
  192. package/src/tokens/resolved/dark-reduced-motion.json +104 -43
  193. package/src/tokens/resolved/dark.json +104 -43
  194. package/src/tokens/resolved/light-reduced-motion.json +104 -43
  195. package/src/tokens/resolved/light.json +104 -43
  196. package/src/tokens/runtime/authoring-catalogue.generated.ts +19300 -0
  197. package/src/tokens/runtime/authoring-catalogue.ts +256 -0
  198. package/src/tokens/runtime/authoring-palette.ts +100 -0
  199. package/src/tokens/runtime/authoring-profiles.ts +288 -0
  200. package/src/tokens/runtime/authoring-provenance.ts +290 -0
  201. package/src/tokens/runtime/authoring-types.ts +199 -0
  202. package/src/tokens/runtime/base-corpus.generated.ts +10 -0
  203. package/src/tokens/runtime/base-corpus.ts +78 -0
  204. package/src/tokens/runtime/context-order.ts +182 -0
  205. package/src/tokens/runtime/context-stack.ts +52 -0
  206. package/src/tokens/runtime/contrast/color-difference.ts +114 -0
  207. package/src/tokens/runtime/contrast/color-math.ts +89 -0
  208. package/src/tokens/runtime/contrast/color-mix.ts +20 -0
  209. package/src/tokens/runtime/contrast/css-color.ts +312 -0
  210. package/src/tokens/runtime/contrast/index.ts +7 -0
  211. package/src/tokens/runtime/contrast/measure.ts +185 -0
  212. package/src/tokens/runtime/contrast/pairings.ts +324 -0
  213. package/src/tokens/runtime/contrast/thresholds.ts +81 -0
  214. package/src/tokens/runtime/corpus-documents.ts +289 -0
  215. package/src/tokens/runtime/corpus-validation.ts +336 -0
  216. package/src/tokens/runtime/corpus.ts +179 -0
  217. package/src/tokens/runtime/css-configuration.ts +1 -0
  218. package/src/tokens/runtime/css-stylelint.ts +15 -0
  219. package/src/tokens/runtime/css-support.ts +407 -0
  220. package/src/tokens/runtime/evaluate.ts +262 -0
  221. package/src/tokens/runtime/evaluated-provenance.ts +116 -0
  222. package/src/tokens/runtime/format-validator.generated.d.ts +18 -0
  223. package/src/tokens/runtime/format-validator.generated.js +13029 -0
  224. package/src/tokens/runtime/index.ts +78 -0
  225. package/src/tokens/runtime/package-version.generated.ts +9 -0
  226. package/src/tokens/runtime/projection.ts +65 -0
  227. package/src/tokens/runtime/registry.ts +365 -0
  228. package/src/tokens/runtime/resolve-extends.ts +211 -0
  229. package/src/tokens/runtime/resolve-references.ts +313 -0
  230. package/src/tokens/runtime/resolve-shared.ts +186 -0
  231. package/src/tokens/runtime/resolve.ts +246 -0
  232. package/src/tokens/runtime/resolver-order.ts +326 -0
  233. package/src/tokens/runtime/resolver-validator.generated.d.ts +18 -0
  234. package/src/tokens/runtime/resolver-validator.generated.js +15492 -0
  235. package/src/tokens/runtime/source-digest.ts +49 -0
  236. package/src/tokens/runtime/stylesheet-skeleton.ts +123 -0
  237. package/src/tokens/runtime/theme-sources.ts +121 -0
  238. package/src/tokens/runtime/theme-stylesheet.ts +177 -0
  239. package/src/tokens/runtime/types.ts +140 -0
  240. package/src/tokens/runtime/validate-resolver.ts +338 -0
  241. package/src/tokens/runtime/validate-schema.ts +269 -0
  242. package/src/tokens/runtime/validate-tokens.ts +181 -0
  243. package/src/tokens/runtime/validate-values.ts +396 -0
  244. package/src/tokens/runtime/validate.ts +57 -0
  245. package/src/tokens/runtime/value-color-parse.ts +309 -0
  246. package/src/tokens/runtime/value-color.ts +217 -0
  247. package/src/tokens/runtime/value-entry.ts +52 -0
  248. package/src/tokens/runtime/value-formatters.ts +414 -0
  249. package/src/tokens/sets/colors.tokens.json +65 -13
  250. package/src/tokens/sets/foundation.tokens.json +23 -0
  251. package/src/tokens/sets/semantic.tokens.json +136 -30
  252. package/src/utilities/highlighter.ts +5 -5
  253. package/src/utilities/retrying-loader-cache.ts +3 -6
  254. package/dist/components/code-block/code-block-default-highlighter.d.ts +0 -40
  255. package/dist/server/index.server-298z43yn.js +0 -4
  256. package/dist/server/index.server-3h11wjyh.js +0 -8
  257. package/dist/server/index.server-a3aerbfr.js +0 -4
  258. package/dist/server/index.server-kge3zp6n.js +0 -4
  259. package/dist/server/index.server-syf81nwz.js +0 -6
  260. package/dist/server/index.server-zs08f5te.js +0 -3
  261. package/src/components/code-block/code-block-default-highlighter.ts +0 -63
@@ -0,0 +1,312 @@
1
+ /**
2
+ * A deliberately small evaluator for the CSS color syntax the token projection emits:
3
+ * literals (`oklch()`, hex, `rgb()`, `transparent`), `var()` aliases resolved through the same
4
+ * property map, `light-dark()`, `color-mix(in oklch, ...)` and relative `oklch(from ...)`.
5
+ *
6
+ * Anything else (another interpolation space, a gradient, an image, an unsupported function) is
7
+ * returned as a typed failure so the caller reports Needs review. It never guesses a color.
8
+ */
9
+
10
+ import { converter, parse, type Oklch } from 'culori';
11
+
12
+ export type CssColorFailureCode =
13
+ 'missing-property' | 'unsupported-syntax' | 'gradient-or-image' | 'reference-cycle';
14
+
15
+ export type CssColor = { l: number; c: number; h: number | undefined; alpha: number };
16
+ export type CssColorResult =
17
+ { ok: true; color: CssColor } | { ok: false; code: CssColorFailureCode; reason: string };
18
+
19
+ export type CssColorOptions = {
20
+ /** Selects the arm of `light-dark()`. */
21
+ theme: 'light' | 'dark';
22
+ };
23
+
24
+ const toOklch = converter('oklch');
25
+ const MAX_DEPTH = 32;
26
+
27
+ const fail = (code: CssColorFailureCode, reason: string): CssColorResult => ({
28
+ ok: false,
29
+ code,
30
+ reason,
31
+ });
32
+
33
+ /** Split on top-level separators, keeping parenthesised groups whole. */
34
+ function splitTopLevel(input: string, separator: 'comma' | 'space'): string[] {
35
+ const parts: string[] = [];
36
+ let depth = 0;
37
+ let current = '';
38
+ for (const character of input) {
39
+ if (character === '(') depth += 1;
40
+ if (character === ')') depth -= 1;
41
+ const isSeparator =
42
+ depth === 0 && (separator === 'comma' ? character === ',' : /\s/.test(character));
43
+ if (isSeparator) {
44
+ if (current.trim() !== '') parts.push(current.trim());
45
+ current = '';
46
+ } else {
47
+ current += character;
48
+ }
49
+ }
50
+ if (current.trim() !== '') parts.push(current.trim());
51
+ return parts;
52
+ }
53
+
54
+ /** The inside of `name( ... )` when `value` is exactly one such call. */
55
+ function callArguments(value: string, name: string): string | null {
56
+ const lower = value.toLowerCase();
57
+ if (!lower.startsWith(`${name}(`) || !value.endsWith(')')) return null;
58
+ let depth = 0;
59
+ for (let index = name.length; index < value.length; index += 1) {
60
+ if (value[index] === '(') depth += 1;
61
+ if (value[index] === ')') depth -= 1;
62
+ if (depth === 0 && index < value.length - 1) return null;
63
+ }
64
+ return value.slice(name.length + 1, -1);
65
+ }
66
+
67
+ const CHANNELS = ['l', 'c', 'h', 'alpha'] as const;
68
+ type Variables = { l: number; c: number; h: number; alpha: number };
69
+
70
+ /** `calc()`, `min()`, `max()` over numbers and the relative-color channel keywords. */
71
+ function evaluateExpression(source: string, variables: Variables): number | null {
72
+ const tokens = source.match(
73
+ /min\(|max\(|calc\(|[A-Za-z]+|\d*\.?\d+(?:e[+-]?\d+)?%?|[()+\-*/,]/gi,
74
+ );
75
+ if (tokens === null || tokens.join('') !== source.replace(/\s+/g, '')) return null;
76
+ let position = 0;
77
+ const peek = () => tokens[position];
78
+ const take = () => tokens[position++];
79
+
80
+ function primary(): number | null {
81
+ const token = take();
82
+ if (token === undefined) return null;
83
+ if (token === '(') return group();
84
+ if (/^calc\($/i.test(token)) return group();
85
+ if (/^(min|max)\($/i.test(token)) {
86
+ const values: number[] = [];
87
+ do {
88
+ const value = sum();
89
+ if (value === null) return null;
90
+ values.push(value);
91
+ } while (peek() === ',' && take() !== undefined);
92
+ if (take() !== ')') return null;
93
+ return token.toLowerCase().startsWith('min') ? Math.min(...values) : Math.max(...values);
94
+ }
95
+ if (token === '-') {
96
+ const value = primary();
97
+ return value === null ? null : -value;
98
+ }
99
+ const channel = CHANNELS.find((name) => name === token);
100
+ if (channel !== undefined) return variables[channel];
101
+ const number = Number.parseFloat(token);
102
+ if (/^\d|^\./.test(token) && Number.isFinite(number))
103
+ return token.endsWith('%') ? number : number;
104
+ return null;
105
+ }
106
+ function group(): number | null {
107
+ const value = sum();
108
+ return take() === ')' ? value : null;
109
+ }
110
+ function product(): number | null {
111
+ let value = primary();
112
+ while (value !== null && (peek() === '*' || peek() === '/')) {
113
+ const operator = take();
114
+ const right = primary();
115
+ if (right === null) return null;
116
+ value = operator === '*' ? value * right : value / right;
117
+ }
118
+ return value;
119
+ }
120
+ function sum(): number | null {
121
+ let value = product();
122
+ while (value !== null && (peek() === '+' || peek() === '-')) {
123
+ const operator = take();
124
+ const right = product();
125
+ if (right === null) return null;
126
+ value = operator === '+' ? value + right : value - right;
127
+ }
128
+ return value;
129
+ }
130
+ const result = sum();
131
+ return position === tokens.length ? result : null;
132
+ }
133
+
134
+ function channelValue(
135
+ token: string,
136
+ variables: Variables,
137
+ channel: 'l' | 'c' | 'h' | 'alpha',
138
+ ): number | null {
139
+ if (token === 'none') return 0;
140
+ if (/^[\d.]+%$/.test(token)) {
141
+ const fraction = Number.parseFloat(token) / 100;
142
+ if (channel === 'l' || channel === 'alpha') return fraction;
143
+ if (channel === 'c') return fraction * 0.4;
144
+ return null;
145
+ }
146
+ return evaluateExpression(token, variables);
147
+ }
148
+
149
+ function mixColors(
150
+ first: { color: CssColor; weight: number },
151
+ second: { color: CssColor; weight: number },
152
+ ): CssColor {
153
+ const total = first.weight + second.weight;
154
+ if (total <= 0) return { ...first.color, alpha: 0 };
155
+ const a = first.weight / total;
156
+ const b = second.weight / total;
157
+ // The alpha multiplier applies when the percentages sum to less than 100%.
158
+ const multiplier = Math.min(1, total / 100);
159
+ const alpha = (first.color.alpha * a + second.color.alpha * b) * multiplier;
160
+ const premultiplied = (x: number, y: number) =>
161
+ alpha === 0
162
+ ? 0
163
+ : (x * first.color.alpha * a + y * second.color.alpha * b) / (alpha / multiplier);
164
+ const l = premultiplied(first.color.l, second.color.l);
165
+ const c = premultiplied(first.color.c, second.color.c);
166
+ // An achromatic color has a missing hue, so the other color's hue is used as is.
167
+ const firstHue = first.color.h ?? second.color.h ?? 0;
168
+ const secondHue = second.color.h ?? first.color.h ?? 0;
169
+ let delta = secondHue - firstHue;
170
+ if (delta > 180) delta -= 360;
171
+ if (delta < -180) delta += 360;
172
+ const hueWeight = first.color.alpha * a + second.color.alpha * b;
173
+ const hue =
174
+ hueWeight === 0 ? firstHue : firstHue + (delta * (second.color.alpha * b)) / hueWeight;
175
+ return { l, c, h: ((hue % 360) + 360) % 360, alpha };
176
+ }
177
+
178
+ function fromCulori(parsed: ReturnType<typeof parse>): CssColor | null {
179
+ if (parsed === undefined) return null;
180
+ const oklch: Oklch = toOklch(parsed);
181
+ return { l: oklch.l, c: oklch.c, h: oklch.h, alpha: oklch.alpha ?? 1 };
182
+ }
183
+
184
+ function mixArgument(argument: string): { color: string; percent: number | null } | null {
185
+ const parts = splitTopLevel(argument, 'space');
186
+ const percentAt = parts.findIndex((part) => /^[\d.]+%$/.test(part));
187
+ if (percentAt === -1) return { color: parts.join(' '), percent: null };
188
+ if (percentAt !== 0 && percentAt !== parts.length - 1) return null;
189
+ const percent = Number.parseFloat(parts[percentAt]!);
190
+ const rest = parts.filter((_, index) => index !== percentAt).join(' ');
191
+ return { color: rest, percent };
192
+ }
193
+
194
+ function evaluate(
195
+ value: string,
196
+ properties: Readonly<Record<string, string>>,
197
+ options: CssColorOptions,
198
+ seen: readonly string[],
199
+ ): CssColorResult {
200
+ const source = value.trim();
201
+ if (seen.length > MAX_DEPTH)
202
+ return fail('reference-cycle', `Too many nested references in ${value}.`);
203
+ if (/gradient\(|url\(|image-set\(|image\(/i.test(source)) {
204
+ return fail('gradient-or-image', `${value} is a gradient or an image.`);
205
+ }
206
+
207
+ const variable = callArguments(source, 'var');
208
+ if (variable !== null) {
209
+ const [name, ...fallback] = splitTopLevel(variable, 'comma');
210
+ if (name === undefined) return fail('unsupported-syntax', `${value} names no property.`);
211
+ if (seen.includes(name)) return fail('reference-cycle', `${name} refers to itself.`);
212
+ const target = properties[name];
213
+ if (target === undefined) {
214
+ if (fallback.length > 0) return evaluate(fallback.join(','), properties, options, seen);
215
+ return fail('missing-property', `${name} has no value in this context.`);
216
+ }
217
+ return evaluate(target, properties, options, [...seen, name]);
218
+ }
219
+
220
+ const lightDark = callArguments(source, 'light-dark');
221
+ if (lightDark !== null) {
222
+ const arms = splitTopLevel(lightDark, 'comma');
223
+ const arm = arms[options.theme === 'light' ? 0 : 1];
224
+ if (arms.length !== 2 || arm === undefined) {
225
+ return fail('unsupported-syntax', `${value} is not a two-argument light-dark().`);
226
+ }
227
+ return evaluate(arm, properties, options, seen);
228
+ }
229
+
230
+ const mix = callArguments(source, 'color-mix');
231
+ if (mix !== null) {
232
+ const [space, ...rest] = splitTopLevel(mix, 'comma');
233
+ if (space?.replace(/\s+/g, ' ').toLowerCase() !== 'in oklch' || rest.length !== 2) {
234
+ return fail('unsupported-syntax', `${value} mixes outside oklch or has not two colors.`);
235
+ }
236
+ const mixArguments = rest.map(mixArgument);
237
+ const [firstArgument, secondArgument] = mixArguments;
238
+ if (!firstArgument || !secondArgument) {
239
+ return fail('unsupported-syntax', `${value} has a misplaced percentage.`);
240
+ }
241
+ const evaluated = [firstArgument, secondArgument].map((argument) =>
242
+ evaluate(argument.color, properties, options, seen),
243
+ );
244
+ const [first, second] = evaluated;
245
+ if (first === undefined || !first.ok) return first ?? fail('unsupported-syntax', value);
246
+ if (second === undefined || !second.ok) return second ?? fail('unsupported-syntax', value);
247
+ let firstWeight = firstArgument.percent;
248
+ let secondWeight = secondArgument.percent;
249
+ if (firstWeight === null && secondWeight === null) {
250
+ firstWeight = 50;
251
+ secondWeight = 50;
252
+ } else if (firstWeight === null) firstWeight = 100 - (secondWeight ?? 0);
253
+ else if (secondWeight === null) secondWeight = 100 - firstWeight;
254
+ return {
255
+ ok: true,
256
+ color: mixColors(
257
+ { color: first.color, weight: firstWeight },
258
+ { color: second.color, weight: secondWeight ?? 0 },
259
+ ),
260
+ };
261
+ }
262
+
263
+ const oklchCall = callArguments(source, 'oklch');
264
+ if (oklchCall !== null && /^\s*from\s/i.test(oklchCall)) {
265
+ const tokens = splitTopLevel(oklchCall, 'space');
266
+ const origin = tokens[1];
267
+ const slash = tokens.indexOf('/');
268
+ const channels = tokens.slice(2, slash === -1 ? undefined : slash);
269
+ if (origin === undefined || channels.length !== 3) {
270
+ return fail('unsupported-syntax', `${value} is not a three-channel relative color.`);
271
+ }
272
+ const base = evaluate(origin, properties, options, seen);
273
+ if (!base.ok) return base;
274
+ const variables: Variables = {
275
+ l: base.color.l,
276
+ c: base.color.c,
277
+ h: base.color.h ?? 0,
278
+ alpha: base.color.alpha,
279
+ };
280
+ const [l, c, h] = [
281
+ channelValue(channels[0]!, variables, 'l'),
282
+ channelValue(channels[1]!, variables, 'c'),
283
+ channelValue(channels[2]!, variables, 'h'),
284
+ ];
285
+ const alphaToken = slash === -1 ? undefined : tokens[slash + 1];
286
+ const alpha =
287
+ alphaToken === undefined ? variables.alpha : channelValue(alphaToken, variables, 'alpha');
288
+ if (l === null || c === null || h === null || alpha === null) {
289
+ return fail(
290
+ 'unsupported-syntax',
291
+ `${value} uses an expression this evaluator does not support.`,
292
+ );
293
+ }
294
+ return { ok: true, color: { l, c: Math.max(0, c), h, alpha } };
295
+ }
296
+
297
+ if (/\bfrom\b|\bvar\(|\bcalc\(|\bcolor-mix\(|\blight-dark\(/i.test(source)) {
298
+ return fail('unsupported-syntax', `${value} uses syntax this evaluator does not support.`);
299
+ }
300
+ const color = fromCulori(parse(source));
301
+ if (color === null) return fail('unsupported-syntax', `${value} is not a supported color.`);
302
+ return { ok: true, color };
303
+ }
304
+
305
+ /** Evaluate one CSS color value against a context's property map. */
306
+ export function evaluateCssColor(
307
+ value: string,
308
+ properties: Readonly<Record<string, string>>,
309
+ options: CssColorOptions,
310
+ ): CssColorResult {
311
+ return evaluate(value, properties, options, []);
312
+ }
@@ -0,0 +1,7 @@
1
+ export * from './color-difference.ts';
2
+ export * from './color-math.ts';
3
+ export * from './color-mix.ts';
4
+ export * from './css-color.ts';
5
+ export * from './measure.ts';
6
+ export * from './pairings.ts';
7
+ export * from './thresholds.ts';
@@ -0,0 +1,185 @@
1
+ /**
2
+ * Measures one pairing against one context's property map.
3
+ *
4
+ * Colors come from the CSS the projection emits, evaluated by `css-color.ts`. A translucent
5
+ * foreground is composited over its background, and a translucent background over its
6
+ * declared backdrop, in gamma-encoded sRGB the way the browser paints. A value that cannot be
7
+ * evaluated, a translucent background with no known backdrop, or a gradient or image is
8
+ * reported as `needs-review`, never as a ratio.
9
+ */
10
+
11
+ import { converter, type Oklch } from 'culori';
12
+
13
+ import { contrastRatio, decodeSrgb, relativeLuminance, type Rgb } from './color-math.ts';
14
+ import {
15
+ evaluateCssColor,
16
+ type CssColor,
17
+ type CssColorFailureCode,
18
+ type CssColorOptions,
19
+ } from './css-color.ts';
20
+ import type { ContrastPairing } from './pairings.ts';
21
+
22
+ const toSrgb = converter('rgb');
23
+ const toLinear = converter('lrgb');
24
+
25
+ export type NeedsReviewCode =
26
+ CssColorFailureCode | 'unknown-background' | 'invalid-opacity' | 'unknown-opacity';
27
+
28
+ export type StackLayer = {
29
+ role: 'foreground' | 'background' | 'backdrop';
30
+ property: string;
31
+ /** The CSS value as the context's property map holds it. */
32
+ value: string;
33
+ /** Gamma-encoded sRGB after clamping, with the alpha the layer carried. */
34
+ rgb: { r: number; g: number; b: number; alpha: number };
35
+ /** True when the color is outside the sRGB gamut and was clamped to measure it. */
36
+ clamped: boolean;
37
+ };
38
+
39
+ export type PairingMeasurement =
40
+ | {
41
+ status: 'measured';
42
+ /** The unrounded WCAG contrast ratio. */
43
+ ratio: number;
44
+ stack: StackLayer[];
45
+ /** True when any layer was clamped into sRGB to be measured. */
46
+ clamped: boolean;
47
+ /** The foreground as painted over the ground, and the opaque ground, in gamma sRGB. */
48
+ ink: StackLayer['rgb'];
49
+ ground: StackLayer['rgb'];
50
+ }
51
+ | {
52
+ status: 'needs-review';
53
+ code: NeedsReviewCode;
54
+ reason: string;
55
+ /** The CSS property whose value could not be measured. */
56
+ property: string;
57
+ };
58
+
59
+ type Resolved =
60
+ { ok: true; layer: StackLayer } | { ok: false; code: NeedsReviewCode; reason: string };
61
+
62
+ const GAMUT_EPSILON = 0.001;
63
+
64
+ function resolveLayer(
65
+ role: StackLayer['role'],
66
+ property: string,
67
+ properties: Readonly<Record<string, string>>,
68
+ options: CssColorOptions,
69
+ ): Resolved {
70
+ const value = properties[property];
71
+ if (value === undefined) {
72
+ return { ok: false, code: 'missing-property', reason: `${property} has no value here.` };
73
+ }
74
+ const evaluated = evaluateCssColor(value, properties, options);
75
+ if (!evaluated.ok) return { ok: false, code: evaluated.code, reason: evaluated.reason };
76
+ return { ok: true, layer: toLayer(role, property, value, evaluated.color) };
77
+ }
78
+
79
+ /** An OKLCH value for culori; an achromatic color has no hue, and the key is left off. */
80
+ function oklchSource(color: CssColor): Oklch {
81
+ return color.h === undefined
82
+ ? { mode: 'oklch', l: color.l, c: color.c }
83
+ : { mode: 'oklch', l: color.l, c: color.c, h: color.h };
84
+ }
85
+
86
+ function toLayer(
87
+ role: StackLayer['role'],
88
+ property: string,
89
+ value: string,
90
+ color: CssColor,
91
+ ): StackLayer {
92
+ const source = oklchSource(color);
93
+ const { r, g, b } = toSrgb(source);
94
+ // The gamut test is on linear channels, with the same tolerance the Cinder gamut suite uses.
95
+ const linear = toLinear(source);
96
+ const inGamut = [linear.r, linear.g, linear.b].every(
97
+ (channel) => channel >= -GAMUT_EPSILON && channel <= 1 + GAMUT_EPSILON,
98
+ );
99
+ const clamp = (channel: number) => Math.min(1, Math.max(0, channel));
100
+ return {
101
+ role,
102
+ property,
103
+ value,
104
+ rgb: { r: clamp(r), g: clamp(g), b: clamp(b), alpha: Math.min(1, Math.max(0, color.alpha)) },
105
+ clamped: !inGamut,
106
+ };
107
+ }
108
+
109
+ /** Paint `top` over an opaque `under`, in gamma-encoded sRGB. */
110
+ function paint(top: StackLayer['rgb'], under: StackLayer['rgb']): StackLayer['rgb'] {
111
+ const mix = (a: number, b: number) => a * top.alpha + b * (1 - top.alpha);
112
+ return { r: mix(top.r, under.r), g: mix(top.g, under.g), b: mix(top.b, under.b), alpha: 1 };
113
+ }
114
+
115
+ function luminanceOf(rgb: StackLayer['rgb']): number {
116
+ const linear: Rgb = [decodeSrgb(rgb.r), decodeSrgb(rgb.g), decodeSrgb(rgb.b)];
117
+ return relativeLuminance(linear);
118
+ }
119
+
120
+ export function measurePairing(
121
+ pairing: ContrastPairing,
122
+ properties: Readonly<Record<string, string>>,
123
+ options: CssColorOptions,
124
+ ): PairingMeasurement {
125
+ const review = (property: string, code: NeedsReviewCode, reason: string): PairingMeasurement => ({
126
+ status: 'needs-review',
127
+ code,
128
+ reason,
129
+ property,
130
+ });
131
+
132
+ const foreground = resolveLayer('foreground', pairing.foreground, properties, options);
133
+ if (!foreground.ok) return review(pairing.foreground, foreground.code, foreground.reason);
134
+ const background = resolveLayer('background', pairing.background, properties, options);
135
+ if (!background.ok) return review(pairing.background, background.code, background.reason);
136
+
137
+ const stack: StackLayer[] = [foreground.layer, background.layer];
138
+ let ground = background.layer.rgb;
139
+ if (ground.alpha < 1) {
140
+ if (pairing.backdrop === undefined) {
141
+ return review(
142
+ pairing.background,
143
+ 'unknown-background',
144
+ `${pairing.background} is translucent and the pairing names no surface beneath it.`,
145
+ );
146
+ }
147
+ const backdrop = resolveLayer('backdrop', pairing.backdrop, properties, options);
148
+ if (!backdrop.ok) return review(pairing.backdrop, backdrop.code, backdrop.reason);
149
+ if (backdrop.layer.rgb.alpha < 1) {
150
+ return review(
151
+ pairing.backdrop,
152
+ 'unknown-background',
153
+ `${pairing.backdrop} is translucent, so the surface beneath the pairing is unknown.`,
154
+ );
155
+ }
156
+ stack.push(backdrop.layer);
157
+ ground = paint(ground, backdrop.layer.rgb);
158
+ }
159
+
160
+ let ink = foreground.layer.rgb;
161
+ if (pairing.opacity !== undefined) {
162
+ const raw = properties[pairing.opacity];
163
+ if (raw === undefined) {
164
+ return review(pairing.opacity, 'unknown-opacity', `${pairing.opacity} has no value here.`);
165
+ }
166
+ const opacity = Number(raw);
167
+ if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) {
168
+ return review(
169
+ pairing.opacity,
170
+ 'invalid-opacity',
171
+ `${pairing.opacity} is ${raw}, not 0 to 1.`,
172
+ );
173
+ }
174
+ ink = { ...ink, alpha: ink.alpha * opacity };
175
+ }
176
+ const painted = ink.alpha < 1 ? paint(ink, ground) : ink;
177
+ return {
178
+ status: 'measured',
179
+ ratio: contrastRatio(luminanceOf(painted), luminanceOf(ground)),
180
+ stack,
181
+ clamped: stack.some((layer) => layer.clamped),
182
+ ink: painted,
183
+ ground,
184
+ };
185
+ }