@fusion.dev/helix-core 0.56.1 → 0.58.0

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/focusable-elements/focusable-elements.d.ts

@@ -1,14 +1,13 @@
 /**
  * Everything inside `root` the reader can reach with Tab, in document order.
  *
- * Separate from the focus trap because finding is the half most callers want:
- * roving tabindex, arrow-key navigation and "focus the first thing" all need
- * this list and none of them traps anything.
+ * Roving tabindex, arrow-key navigation and "focus the first thing" all need
+ * this list, which is why it is a utility rather than part of anything that
+ * asks for it.
  *
  * Visibility is tested with `getClientRects()` rather than `offsetParent`,
- * which is null for anything inside a `position: fixed` container. A drawer is
- * exactly that, so the `offsetParent` test excluded every control in the thing
- * being trapped.
+ * which is null for anything inside a `position: fixed` container, so the
+ * `offsetParent` test excluded every control on a raised surface.
  */
 export declare const focusableElements: (root: HTMLElement) => HTMLElement[];
 /**
@@ -23,13 +22,13 @@ export declare const deepActiveElement: () => Element | null;
  *
  * `Node.contains` walks `parentNode` and a shadow root's `parentNode` is null,
  * so it answers false for anything inside a component. Paired with
- * `deepActiveElement`, which returns exactly such a node, that pairing is a trap
- * of its own: the two look like they belong together and one of them crosses.
+ * `deepActiveElement`, which returns exactly such a node, the pair is a hazard of
+ * its own: the two look like they belong together and one of them crosses.
  *
  * `contains(deepActiveElement())` is the shape to avoid: focus on a
  * `helix-button` reports as the `<button>` in its shadow root, which is in no
- * light-DOM container anywhere, so a trap written that way reads every reader
- * as already outside it.
+ * light-DOM container anywhere, so a containment test written that way reads
+ * every reader as already outside.
  *
  * `host` is reached without naming `ShadowRoot`, which the server has no global
  * for. This runs from a keydown handler and would never execute there, but a

package/dist/utils/media-copy/media-copy.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What the consumer slotted, as the plain data a media element can be given.
+ *
+ * A media element runs resource selection over its own child nodes and a slot
+ * is one node, so anything wrapping `<video>` or `<audio>` in a shadow root has
+ * to copy rather than slot. The two questions that copying asks are answered
+ * here: which attributes come across, and whether a fresh read differs from the
+ * set already held. When to read, and what to do with the answer, stay with the
+ * element.
+ *
+ * A read of light DOM and nothing else: no media element, no playback state,
+ * nothing drawn, which is what makes it a utility rather than a controller.
+ */
+/** A `<source>` or `<track>` as the consumer wrote it, reduced to what the copy carries. */
+export interface MediaCopy {
+    attrs: Record<string, string>;
+    tag: 'source' | 'track';
+}
+/** The copies to make of what the default slot is given. */
+export declare const copiesOf: (elements: readonly Element[]) => MediaCopy[];
+/**
+ * Whether two reads describe the same media.
+ *
+ * The same set again is not a change. A video reloads for every new list, and
+ * the first `slotchange` reports the children the element has already read.
+ */
+export declare const sameCopies: (one: readonly MediaCopy[], two: readonly MediaCopy[]) => boolean;

package/dist/utils/media-copy/media-copy.js

@@ -0,0 +1,18 @@
+const CARRIED = {
+    source: ['media', 'sizes', 'src', 'srcset', 'type'],
+    track: ['default', 'kind', 'label', 'src', 'srclang'],
+};
+export const copiesOf = (elements) => elements
+    .filter((node) => node instanceof HTMLSourceElement || node instanceof HTMLTrackElement)
+    .map((node) => {
+    const tag = node instanceof HTMLTrackElement ? 'track' : 'source';
+    const attrs = {};
+    for (const name of CARRIED[tag]) {
+        const value = node.getAttribute(name);
+        if (value !== null) {
+            attrs[name] = value;
+        }
+    }
+    return { attrs, tag };
+});
+export const sameCopies = (one, two) => JSON.stringify(one) === JSON.stringify(two);

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.56.1",
+  "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.56.1"
+    "@fusion.dev/helix-icons": "0.58.0"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.56.1",
-    "@fusion.dev/helix-testing": "0.56.1",
+    "@fusion.dev/helix-cem": "0.58.0",
+    "@fusion.dev/helix-testing": "0.58.0",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",

package/dist/controllers/focus-trap-controller/focus-trap-controller.d.ts

@@ -1,26 +0,0 @@
-import type { ReactiveController, ReactiveControllerHost } from 'lit';
-/**
- * Keeps Tab inside a container while it is open, and gives focus back after.
- *
- * A dialog that does not trap focus is one a keyboard user tabs straight out
- * of, into a page they cannot see and cannot get back from. Restoring focus on
- * release matters just as much: without it, closing a drawer drops the reader
- * at the top of the document.
- *
- * Finding the focusable elements is `focusableElements`, which is a utility
- * rather than part of this, because that half is what roving tabindex and
- * arrow-key navigation need and neither of them traps anything.
- */
-export declare class FocusTrapController implements ReactiveController {
-    private container;
-    /** The frame waiting to take focus, so a release can call it off. */
-    private frame;
-    private previous;
-    constructor(host: ReactiveControllerHost);
-    private readonly handleKeydown;
-    /** Starts trapping, remembering where focus came from. */
-    activate(container: HTMLElement): void;
-    /** Stops trapping and returns focus to wherever it was. */
-    deactivate(): void;
-    hostDisconnected(): void;
-}

package/dist/controllers/focus-trap-controller/focus-trap-controller.js

@@ -1,55 +0,0 @@
-import { deepActiveElement, deepContains, focusableElements, } from '../../utils/focusable-elements/focusable-elements.js';
-export class FocusTrapController {
-    constructor(host) {
-        this.container = null;
-        this.previous = null;
-        this.handleKeydown = (event) => {
-            if (event.key !== 'Tab' || !this.container) {
-                return;
-            }
-            const items = focusableElements(this.container);
-            if (items.length === 0) {
-                event.preventDefault();
-                return;
-            }
-            const first = items[0];
-            const last = items.at(-1);
-            const active = deepActiveElement();
-            const at = items.findIndex((item) => item === active || deepContains(item, active));
-            if (event.shiftKey) {
-                if (at <= 0) {
-                    event.preventDefault();
-                    last.focus();
-                }
-            }
-            else if (at === -1 || at === items.length - 1) {
-                event.preventDefault();
-                first.focus();
-            }
-        };
-        host.addController(this);
-    }
-    activate(container) {
-        this.container = container;
-        this.previous = deepActiveElement();
-        document.addEventListener('keydown', this.handleKeydown, true);
-        this.frame = requestAnimationFrame(() => {
-            this.frame = undefined;
-            const items = focusableElements(container);
-            (items[0] ?? container).focus();
-        });
-    }
-    deactivate() {
-        if (this.frame !== undefined) {
-            cancelAnimationFrame(this.frame);
-            this.frame = undefined;
-        }
-        document.removeEventListener('keydown', this.handleKeydown, true);
-        this.container = null;
-        this.previous?.focus();
-        this.previous = null;
-    }
-    hostDisconnected() {
-        this.deactivate();
-    }
-}