@fusion.dev/helix-core 0.57.0 → 0.58.0

package/custom-elements.json

@@ -2095,19 +2095,9 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Reads a design token as the sRGB triple a shader or a 2D canvas can take, and\ntells the host when the palette underneath it moves.\n\n**Two hops, and both are load-bearing.** A custom property's own value is the\nunevaluated function text, so `getComputedStyle` on a probe is the only way\nto see what it resolves to. And what it resolves to is not `rgb()`: the\npalette derives from an `oklch()` seed, and Chrome answers `lab(100 0 0)` for\nwhite. Parsing that with a regular expression for numbers reads the three\nchannels as 100, 0 and 0, which divided by 255 is a dark red.\n\nA screenshot cannot catch that: a warm cast on a saturated gradient is also\nwhat chroma subsampling produces, so the picture agrees with the bug.\n\nThe conversion is therefore the browser's own: fill a pixel and read it back.\nThat holds for `lab()`, `oklch()`, `color-mix()` and whatever a token is\nwritten in next, which is the property worth having in a design system whose\npalette is derived rather than listed.\n\n**A controller and not a mixin**, by this repository's own line: it adds no\nproperty or method a consumer sets. It reacts to lifecycle, holding a probe\nthat has to be created after the host connects and removed when it leaves,\nand it watches for the color mode changing so the host can repaint.\n\n**Client only, and that is the contract rather than a limitation.** There is\nno computed style on a server and no canvas to convert with, so `read`\nanswers the fallback there. Every caller is drawing into a canvas, which does\nnot exist on a server either.",
+          "description": "Reads a design token as the sRGB triple a shader or a 2D canvas can take, and\ntells the host when the palette underneath it moves.\n\n**Two hops, and both are load-bearing.** A custom property's own value is the\nunevaluated function text, so `getComputedStyle` on a probe is the only way\nto see what it resolves to. The second hop is `readColor`, which is shared\nwith every other caller that has a resolved color and needs channels: what it\nresolves to is not `rgb()`, the\npalette derives from an `oklch()` seed, and Chrome answers `lab(100 0 0)` for\nwhite. Parsing that with a regular expression for numbers reads the three\nchannels as 100, 0 and 0, which divided by 255 is a dark red.\n\nA screenshot cannot catch that: a warm cast on a saturated gradient is also\nwhat chroma subsampling produces, so the picture agrees with the bug.\n\nThe conversion is therefore the browser's own: fill a pixel and read it back.\nThat holds for `lab()`, `oklch()`, `color-mix()` and whatever a token is\nwritten in next, which is the property worth having in a design system whose\npalette is derived rather than listed.\n\n**A controller and not a mixin**, by this repository's own line: it adds no\nproperty or method a consumer sets. It reacts to lifecycle, holding a probe\nthat has to be created after the host connects and removed when it leaves,\nand it watches for the color mode changing so the host can repaint.\n\n**Client only, and that is the contract rather than a limitation.** There is\nno computed style on a server and no canvas to convert with, so `read`\nanswers the fallback there. Every caller is drawing into a canvas, which does\nnot exist on a server either.",
           "name": "TokenColorController",
           "members": [
-            {
-              "kind": "field",
-              "name": "context",
-              "type": {
-                "text": "CanvasRenderingContext2D | null"
-              },
-              "privacy": "private",
-              "default": "null",
-              "description": "Where a resolved color is converted, one pixel at a time."
-            },
             {
               "kind": "field",
               "name": "modes",
@@ -5977,6 +5967,54 @@
             "module": "./utils/create-sheet/create-sheet.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "Color",
+          "declaration": {
+            "name": "Color",
+            "module": "./utils/css-color/css-color.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ColorFormat",
+          "declaration": {
+            "name": "ColorFormat",
+            "module": "./utils/css-color/css-color.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "formatColor",
+          "declaration": {
+            "name": "formatColor",
+            "module": "./utils/css-color/css-color.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "parseColor",
+          "declaration": {
+            "name": "parseColor",
+            "module": "./utils/css-color/css-color.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "splitColors",
+          "declaration": {
+            "name": "splitColors",
+            "module": "./utils/css-color/css-color.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "toCss",
+          "declaration": {
+            "name": "toCss",
+            "module": "./utils/css-color/css-color.js"
+          }
+        },
         {
           "kind": "js",
           "name": "customElement",
@@ -6193,6 +6231,22 @@
             "module": "./utils/on-unless-false/on-unless-false.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "ColorBytes",
+          "declaration": {
+            "name": "ColorBytes",
+            "module": "./utils/read-color/read-color.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "readColor",
+          "declaration": {
+            "name": "readColor",
+            "module": "./utils/read-color/read-color.js"
+          }
+        },
         {
           "kind": "js",
           "name": "Row",
@@ -9803,6 +9857,130 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/css-color/css-color.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "splitColors",
+          "return": {
+            "type": {
+              "text": "string[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "value",
+              "type": {
+                "text": "string"
+              }
+            }
+          ],
+          "description": "Splits a comma-separated list of colors, ignoring the commas inside them.\n\nA plain `split(',')` cannot hold the legacy syntaxes:\n`#ef4444, rgb(249 115 22), rgba(34,197,94,.5)` comes apart into six fragments,\nfour of them not colors, and the row quietly renders three swatches instead of\nfour. The modern space-separated forms survive it, which is what makes such a\nlist look like it works.\n\nDepth rather than a regular expression, because the thing that matters is\nwhether a comma is inside a function call and that is exactly what a counter\nanswers. No color syntax nests, so a single counter is enough."
+        },
+        {
+          "kind": "function",
+          "name": "parseColor",
+          "return": {
+            "type": {
+              "text": "Color | null"
+            }
+          },
+          "parameters": [
+            {
+              "name": "value",
+              "type": {
+                "text": "string"
+              }
+            }
+          ],
+          "description": "Any of the syntaxes to the working model, or `null` where it is not a color.\n\nNamed colors are not here. Resolving `rebeccapurple` means either shipping\nthe table of a hundred and forty or asking the browser, and the browser is not\npresent on the server: a field that accepted a name client-side and rejected\nit during a server render would be worse than one that never took it."
+        },
+        {
+          "kind": "function",
+          "name": "formatColor",
+          "return": {
+            "type": {
+              "text": "string"
+            }
+          },
+          "parameters": [
+            {
+              "name": "color",
+              "type": {
+                "text": "Color"
+              }
+            },
+            {
+              "name": "format",
+              "type": {
+                "text": "ColorFormat"
+              }
+            },
+            {
+              "name": "withAlpha",
+              "type": {
+                "text": "boolean"
+              }
+            }
+          ],
+          "description": "The working model back out, in the syntax asked for.\n\nThe alpha is written only where the component carries one. A consumer who did\nnot ask for transparency should not have to strip `ff` off every hex or read\npast a fourth argument they never wanted."
+        },
+        {
+          "kind": "function",
+          "name": "toCss",
+          "return": {
+            "type": {
+              "text": "string"
+            }
+          },
+          "parameters": [
+            {
+              "name": "color",
+              "type": {
+                "text": "Color"
+              }
+            }
+          ],
+          "description": "The color as CSS, for the swatches and the tracks. Always with its alpha."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "splitColors",
+          "declaration": {
+            "name": "splitColors",
+            "module": "src/utils/css-color/css-color.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "parseColor",
+          "declaration": {
+            "name": "parseColor",
+            "module": "src/utils/css-color/css-color.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "formatColor",
+          "declaration": {
+            "name": "formatColor",
+            "module": "src/utils/css-color/css-color.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "toCss",
+          "declaration": {
+            "name": "toCss",
+            "module": "src/utils/css-color/css-color.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/custom-element/custom-element.ts",
@@ -10474,6 +10652,41 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/read-color/read-color.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "readColor",
+          "return": {
+            "type": {
+              "text": "ColorBytes | undefined"
+            }
+          },
+          "parameters": [
+            {
+              "name": "value",
+              "type": {
+                "text": "string"
+              },
+              "description": "A resolved color, as `getComputedStyle` reports one."
+            }
+          ],
+          "description": "A computed color as three sRGB bytes, or nothing where it cannot be read.\n\n**Painting it is the only way to read it.** A color-typed property is\nresolved before it is reported, but resolved is not the same as converted:\nChrome hands back `lab(100 0 0)` for a token built through `oklab`, and\nscraping the first three numbers out of that and calling them red, green and\nblue made white arrive as `rgb(100, 0, 0)`. In light mode the near dots were\n`lab(0 0 0)`, which scrapes to black and looks right, so only dark mode\nshowed it: dark red mixed toward black, on a near-black ground.\n\n**Painted twice, over two different grounds, which is what makes the refusal\nhonest.** Assigning a value the engine will not parse leaves `fillStyle`\nexactly where it was, so a single paint cannot tell a color apart from the\nground it failed to replace. Over black and over white, a value that parsed\ngives the same answer twice and one that did not gives two. A caller then\nchooses its own fallback rather than being handed a color nobody picked,\nwhich is the half both earlier copies of this had to guess at.\n\nA readback is not free, so the answer is held against the string it came\nfrom, refusals included. The oldest goes when the store is full rather than\nall of them, or a page deriving colors on a slider pays for every frame\ntwice."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "readColor",
+          "declaration": {
+            "name": "readColor",
+            "module": "src/utils/read-color/read-color.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/read-series/read-series.ts",

package/dist/controllers/token-color-controller/token-color-controller.d.ts

@@ -7,7 +7,9 @@ export type TokenColor = [number, number, number];
  *
  * **Two hops, and both are load-bearing.** A custom property's own value is the
  * unevaluated function text, so `getComputedStyle` on a probe is the only way
- * to see what it resolves to. And what it resolves to is not `rgb()`: the
+ * to see what it resolves to. The second hop is `readColor`, which is shared
+ * with every other caller that has a resolved color and needs channels: what it
+ * resolves to is not `rgb()`, the
  * palette derives from an `oklch()` seed, and Chrome answers `lab(100 0 0)` for
  * white. Parsing that with a regular expression for numbers reads the three
  * channels as 100, 0 and 0, which divided by 255 is a dark red.
@@ -33,8 +35,6 @@ export type TokenColor = [number, number, number];
 export declare class TokenColorController implements ReactiveController {
     private readonly host;
     private readonly onChange?;
-    /** Where a resolved color is converted, one pixel at a time. */
-    private context;
     /** Watches the document for `data-color-mode`. */
     private modes;
     /** The hidden element a token is resolved against. */

package/dist/controllers/token-color-controller/token-color-controller.js

@@ -1,8 +1,8 @@
+import { readColor } from '../../utils/read-color/read-color.js';
 export class TokenColorController {
     constructor(host, onChange) {
         this.host = host;
         this.onChange = onChange;
-        this.context = null;
         this.announce = () => {
             this.host.requestUpdate();
             this.onChange?.();
@@ -16,10 +16,6 @@ export class TokenColorController {
         this.probe = document.createElement('span');
         this.probe.style.display = 'none';
         document.body.appendChild(this.probe);
-        const swatch = document.createElement('canvas');
-        swatch.width = 1;
-        swatch.height = 1;
-        this.context = swatch.getContext('2d', { willReadFrequently: true });
         this.modes = new MutationObserver(() => this.announce());
         this.modes.observe(document.documentElement, {
             attributeFilter: ['data-color-mode'],
@@ -35,18 +31,18 @@ export class TokenColorController {
         this.scheme = undefined;
         this.probe?.remove();
         this.probe = undefined;
-        this.context = null;
     }
     read(token, fallback) {
-        const { context, probe } = this;
-        if (!context || !probe) {
+        const { probe } = this;
+        if (!probe) {
             return [...fallback];
         }
         probe.style.color = `var(${token})`;
-        context.fillStyle = '#000000';
-        context.fillStyle = getComputedStyle(probe).color;
-        context.fillRect(0, 0, 1, 1);
-        const [r, g, b] = context.getImageData(0, 0, 1, 1).data;
-        return [(r ?? 0) / 255, (g ?? 0) / 255, (b ?? 0) / 255];
+        const read = readColor(getComputedStyle(probe).color);
+        if (!read) {
+            return [...fallback];
+        }
+        const [r, g, b] = read;
+        return [r / 255, g / 255, b / 255];
     }
 }

package/dist/index.d.ts

@@ -37,6 +37,7 @@ export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
 export { closestInstance } from './utils/closest-instance/closest-instance.js';
 export { createSheet } from './utils/create-sheet/create-sheet.js';
+export { type Color, type ColorFormat, formatColor, parseColor, splitColors, toCss, } from './utils/css-color/css-color.js';
 export { customElement, definedTags, duplicateRegistrations, } from './utils/custom-element/custom-element.js';
 export { type DrawIconOptions, drawIcon } from './utils/draw-icon/draw-icon.js';
 export { CHART_PLOT, drawTooltip } from './utils/draw-tooltip/draw-tooltip.js';
@@ -50,6 +51,7 @@ export { type Curve, linePath, type Point } from './utils/line-path/line-path.js
 export { markRegion, type RegionOptions } from './utils/mark-region/mark-region.js';
 export { copiesOf, type MediaCopy, sameCopies, } from './utils/media-copy/media-copy.js';
 export { onUnlessFalse } from './utils/on-unless-false/on-unless-false.js';
+export { type ColorBytes, readColor } from './utils/read-color/read-color.js';
 export { type Row, type RowCell, readRows, readSeries, type Series, type SeriesPoint, } from './utils/read-series/read-series.js';
 export { type Relative, relativeTime, } from './utils/relative-time/relative-time.js';
 export { type ChangeRequestOptions, requestChange, } from './utils/request-change/request-change.js';

package/dist/index.js

@@ -37,6 +37,7 @@ export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
 export { closestInstance } from './utils/closest-instance/closest-instance.js';
 export { createSheet } from './utils/create-sheet/create-sheet.js';
+export { formatColor, parseColor, splitColors, toCss, } from './utils/css-color/css-color.js';
 export { customElement, definedTags, duplicateRegistrations, } from './utils/custom-element/custom-element.js';
 export { drawIcon } from './utils/draw-icon/draw-icon.js';
 export { CHART_PLOT, drawTooltip } from './utils/draw-tooltip/draw-tooltip.js';
@@ -50,6 +51,7 @@ export { linePath } from './utils/line-path/line-path.js';
 export { markRegion } from './utils/mark-region/mark-region.js';
 export { copiesOf, sameCopies, } from './utils/media-copy/media-copy.js';
 export { onUnlessFalse } from './utils/on-unless-false/on-unless-false.js';
+export { readColor } from './utils/read-color/read-color.js';
 export { readRows, readSeries, } from './utils/read-series/read-series.js';
 export { relativeTime, } from './utils/relative-time/relative-time.js';
 export { requestChange, } from './utils/request-change/request-change.js';

package/dist/utils/css-color/css-color.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Reading and writing the color syntaxes a field is allowed to hold.
+ *
+ * **The working model is HSB**, hue and saturation and brightness, because that
+ * is what the panel is: a square of saturation against brightness with a hue
+ * ramp beside it. HSL would put the square's corners somewhere a reader does not
+ * expect, since full saturation in HSL is a mid-lightness band rather than a
+ * corner.
+ *
+ * **Every syntax here is read; three are written.** A field that refuses
+ * `rgb(255 0 0)` because it prefers hex is a field arguing with the person using
+ * it, so the space-separated forms, the comma forms, `rgba` and `hsla` are all
+ * taken. What is written back is whichever of hex, rgb or hsl the component is
+ * set to, so a value stays in the shape the consumer asked for however it was
+ * entered.
+ *
+ * **What is written is the comma form.** Both are valid, and the commas are what
+ * a reader recognizes, what most code around them holds, and what pastes into
+ * anything without a second thought. A syntax a value is handed *out* in is not
+ * the place to be early. `rgba` and `hsla` come with them, since a comma form
+ * with a fourth argument is spelled that way.
+ *
+ * **Core's rather than a field's, because the CSS color grammar is the
+ * platform's.** Nothing here needs a color picker to make sense, and two
+ * families read it already. It is arithmetic with no DOM in it, so it runs on a
+ * server, which is also why named colors are refused below: resolving
+ * `rebeccapurple` means asking a browser that is not there.
+ *
+ * **One decision in here is a default rather than a capability.** What
+ * `formatColor` writes back, the comma form and an alpha only where one was
+ * asked for, is a choice about what a value looks like when it is handed out.
+ * It is core's choice now instead of the picker's, and a caller wanting another
+ * shape formats it itself.
+ */
+/** A color as the panel holds it. Alpha and the two percentages are 0 to 100. */
+export interface Color {
+    alpha: number;
+    brightness: number;
+    hue: number;
+    saturation: number;
+}
+/** The syntaxes a value can be written in. */
+export type ColorFormat = 'hex' | 'hsl' | 'rgb';
+/**
+ * Splits a comma-separated list of colors, ignoring the commas inside them.
+ *
+ * A plain `split(',')` cannot hold the legacy syntaxes:
+ * `#ef4444, rgb(249 115 22), rgba(34,197,94,.5)` comes apart into six fragments,
+ * four of them not colors, and the row quietly renders three swatches instead of
+ * four. The modern space-separated forms survive it, which is what makes such a
+ * list look like it works.
+ *
+ * Depth rather than a regular expression, because the thing that matters is
+ * whether a comma is inside a function call and that is exactly what a counter
+ * answers. No color syntax nests, so a single counter is enough.
+ */
+export declare const splitColors: (value: string) => string[];
+/**
+ * Any of the syntaxes to the working model, or `null` where it is not a color.
+ *
+ * Named colors are not here. Resolving `rebeccapurple` means either shipping
+ * the table of a hundred and forty or asking the browser, and the browser is not
+ * present on the server: a field that accepted a name client-side and rejected
+ * it during a server render would be worse than one that never took it.
+ */
+export declare const parseColor: (value: string) => Color | null;
+/**
+ * The working model back out, in the syntax asked for.
+ *
+ * The alpha is written only where the component carries one. A consumer who did
+ * not ask for transparency should not have to strip `ff` off every hex or read
+ * past a fourth argument they never wanted.
+ */
+export declare const formatColor: (color: Color, format: ColorFormat, withAlpha: boolean) => string;
+/** The color as CSS, for the swatches and the tracks. Always with its alpha. */
+export declare const toCss: (color: Color) => string;

package/dist/utils/css-color/css-color.js

@@ -0,0 +1,168 @@
+const clamp = (value, low, high) => Math.min(high, Math.max(low, value));
+const toAlpha = (token) => {
+    if (token === undefined) {
+        return 100;
+    }
+    const number = Number.parseFloat(token);
+    if (Number.isNaN(number)) {
+        return 100;
+    }
+    return clamp(token.includes('%') ? number : number * 100, 0, 100);
+};
+const toByte = (token) => {
+    const number = Number.parseFloat(token);
+    return clamp(token.includes('%') ? (number / 100) * 255 : number, 0, 255);
+};
+const rgbToHsb = (red, green, blue, alpha) => {
+    const r = red / 255;
+    const g = green / 255;
+    const b = blue / 255;
+    const high = Math.max(r, g, b);
+    const low = Math.min(r, g, b);
+    const span = high - low;
+    let hue = 0;
+    if (span !== 0) {
+        if (high === r) {
+            hue = (g - b) / span + (g < b ? 6 : 0);
+        }
+        else if (high === g) {
+            hue = (b - r) / span + 2;
+        }
+        else {
+            hue = (r - g) / span + 4;
+        }
+        hue *= 60;
+    }
+    return {
+        alpha,
+        brightness: Math.round(high * 100),
+        hue: Math.round(hue),
+        saturation: Math.round(high === 0 ? 0 : (span / high) * 100),
+    };
+};
+const toRgb = (color) => {
+    const hue = (((color.hue % 360) + 360) % 360) / 60;
+    const saturation = color.saturation / 100;
+    const brightness = color.brightness / 100;
+    const chroma = brightness * saturation;
+    const middle = chroma * (1 - Math.abs((hue % 2) - 1));
+    const base = brightness - chroma;
+    const sextants = [
+        [chroma, middle, 0],
+        [middle, chroma, 0],
+        [0, chroma, middle],
+        [0, middle, chroma],
+        [middle, 0, chroma],
+        [chroma, 0, middle],
+    ];
+    const [red, green, blue] = sextants[Math.floor(hue) % 6] ?? [0, 0, 0];
+    return {
+        blue: Math.round((blue + base) * 255),
+        green: Math.round((green + base) * 255),
+        red: Math.round((red + base) * 255),
+    };
+};
+const toHsl = (color) => {
+    const saturation = color.saturation / 100;
+    const brightness = color.brightness / 100;
+    const lightness = (brightness * (2 - saturation)) / 2;
+    return {
+        hue: ((color.hue % 360) + 360) % 360,
+        lightness: Math.round(lightness * 100),
+        saturation: Math.round((lightness === 0 || lightness === 1
+            ? 0
+            : (brightness - lightness) / Math.min(lightness, 1 - lightness)) * 100),
+    };
+};
+export const splitColors = (value) => {
+    const found = [];
+    let depth = 0;
+    let current = '';
+    for (const character of value) {
+        if (character === '(') {
+            depth += 1;
+        }
+        else if (character === ')') {
+            depth = Math.max(0, depth - 1);
+        }
+        if (character === ',' && depth === 0) {
+            found.push(current.trim());
+            current = '';
+        }
+        else {
+            current += character;
+        }
+    }
+    found.push(current.trim());
+    return found.filter(Boolean);
+};
+export const parseColor = (value) => {
+    const text = value.trim().toLowerCase();
+    if (text === '') {
+        return null;
+    }
+    if (text.startsWith('#')) {
+        const digits = text.slice(1);
+        const short = digits.length === 3 || digits.length === 4;
+        const long = digits.length === 6 || digits.length === 8;
+        if ((!short && !long) || !/^[\da-f]+$/.test(digits)) {
+            return null;
+        }
+        const width = short ? 1 : 2;
+        const channel = (index) => {
+            const piece = digits.slice(index * width, index * width + width);
+            return Number.parseInt(short ? piece + piece : piece, 16);
+        };
+        const carriesAlpha = digits.length === 4 || digits.length === 8;
+        return rgbToHsb(channel(0), channel(1), channel(2), carriesAlpha ? Math.round((channel(3) / 255) * 100) : 100);
+    }
+    const call = /^(rgba?|hsla?)\(([^)]*)\)$/.exec(text);
+    if (!call?.[1] || call[2] === undefined) {
+        return null;
+    }
+    const [first = '', second = '', third = '', fourth] = call[2]
+        .replace(/[,/]/g, ' ')
+        .split(/\s+/)
+        .filter(Boolean);
+    if (first === '' || second === '' || third === '') {
+        return null;
+    }
+    const alpha = toAlpha(fourth);
+    if (call[1].startsWith('rgb')) {
+        return rgbToHsb(toByte(first), toByte(second), toByte(third), alpha);
+    }
+    const hue = Number.parseFloat(first);
+    const saturation = clamp(Number.parseFloat(second), 0, 100) / 100;
+    const lightness = clamp(Number.parseFloat(third), 0, 100) / 100;
+    if (Number.isNaN(hue) || Number.isNaN(saturation) || Number.isNaN(lightness)) {
+        return null;
+    }
+    const brightness = lightness + saturation * Math.min(lightness, 1 - lightness);
+    return {
+        alpha,
+        brightness: Math.round(brightness * 100),
+        hue: Math.round(((hue % 360) + 360) % 360),
+        saturation: Math.round((brightness === 0 ? 0 : 2 * (1 - lightness / brightness)) * 100),
+    };
+};
+export const formatColor = (color, format, withAlpha) => {
+    const alpha = clamp(color.alpha, 0, 100) / 100;
+    const opacity = Number(alpha.toFixed(2));
+    if (format === 'hsl') {
+        const { hue, lightness, saturation } = toHsl(color);
+        const body = `${Math.round(hue)}, ${saturation}%, ${lightness}%`;
+        return withAlpha ? `hsla(${body}, ${opacity})` : `hsl(${body})`;
+    }
+    const { blue, green, red } = toRgb(color);
+    if (format === 'rgb') {
+        const body = `${red}, ${green}, ${blue}`;
+        return withAlpha ? `rgba(${body}, ${opacity})` : `rgb(${body})`;
+    }
+    const byte = (one) => one.toString(16).padStart(2, '0');
+    const hex = `#${byte(red)}${byte(green)}${byte(blue)}`;
+    return withAlpha ? hex + byte(Math.round(alpha * 255)) : hex;
+};
+export const toCss = (color) => {
+    const { blue, green, red } = toRgb(color);
+    return `rgb(${red} ${green} ${blue} / ${clamp(color.alpha, 0, 100)}%)`;
+};

package/dist/utils/read-color/read-color.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Reading a computed color the engine has resolved but not converted.
+ *
+ * Distinct from `css-color`, which reads the syntax a *consumer* writes and
+ * runs on a server. This reads what the engine hands back, which can be in any
+ * space the platform supports, and needs a canvas to do it.
+ */
+/** A color as three sRGB bytes, which is what a canvas reports and takes. */
+export type ColorBytes = [number, number, number];
+/**
+ * A computed color as three sRGB bytes, or nothing where it cannot be read.
+ *
+ * **Painting it is the only way to read it.** A color-typed property is
+ * resolved before it is reported, but resolved is not the same as converted:
+ * Chrome hands back `lab(100 0 0)` for a token built through `oklab`, and
+ * scraping the first three numbers out of that and calling them red, green and
+ * blue made white arrive as `rgb(100, 0, 0)`. In light mode the near dots were
+ * `lab(0 0 0)`, which scrapes to black and looks right, so only dark mode
+ * showed it: dark red mixed toward black, on a near-black ground.
+ *
+ * **Painted twice, over two different grounds, which is what makes the refusal
+ * honest.** Assigning a value the engine will not parse leaves `fillStyle`
+ * exactly where it was, so a single paint cannot tell a color apart from the
+ * ground it failed to replace. Over black and over white, a value that parsed
+ * gives the same answer twice and one that did not gives two. A caller then
+ * chooses its own fallback rather than being handed a color nobody picked,
+ * which is the half both earlier copies of this had to guess at.
+ *
+ * A readback is not free, so the answer is held against the string it came
+ * from, refusals included. The oldest goes when the store is full rather than
+ * all of them, or a page deriving colors on a slider pays for every frame
+ * twice.
+ *
+ * @param value A resolved color, as `getComputedStyle` reports one.
+ */
+export declare const readColor: (value: string) => ColorBytes | undefined;

package/dist/utils/read-color/read-color.js

@@ -0,0 +1,36 @@
+let swatch;
+const known = new Map();
+const KEPT = 64;
+const painted = (context, value, under) => {
+    context.fillStyle = under;
+    context.fillStyle = value;
+    context.fillRect(0, 0, 1, 1);
+    const [red, green, blue] = context.getImageData(0, 0, 1, 1).data;
+    return [red ?? 0, green ?? 0, blue ?? 0];
+};
+export const readColor = (value) => {
+    if (known.has(value)) {
+        const seen = known.get(value);
+        return seen ? [...seen] : undefined;
+    }
+    if (typeof document === 'undefined') {
+        return undefined;
+    }
+    if (swatch === undefined) {
+        swatch = document.createElement('canvas').getContext('2d', { willReadFrequently: true });
+    }
+    if (!swatch) {
+        return undefined;
+    }
+    const over = painted(swatch, value, '#000000');
+    const under = painted(swatch, value, '#ffffff');
+    const read = over.every((one, at) => one === under[at]) ? over : undefined;
+    if (known.size >= KEPT) {
+        const oldest = known.keys().next().value;
+        if (oldest !== undefined) {
+            known.delete(oldest);
+        }
+    }
+    known.set(value, read);
+    return read ? [...read] : undefined;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -34,12 +34,12 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.57.0"
+    "@fusion.dev/helix-icons": "0.58.0"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.57.0",
-    "@fusion.dev/helix-testing": "0.57.0",
+    "@fusion.dev/helix-cem": "0.58.0",
+    "@fusion.dev/helix-testing": "0.58.0",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",