ng-hub-ui-utils 22.11.0 → 22.12.0

package/README.md

@@ -591,6 +591,30 @@ These functions back the i18n system and are exported for direct use:
 -   `reflow(element: HTMLElement): DOMRect` - Forces browser reflow
 -   `getActiveElement(root?: Document | ShadowRoot): Element | null` - Gets active element including Shadow DOM
 
+### Colour Functions
+
+-   `parseColor(value): HubRgb | null` - Parses hex (3/4/6/8), `rgb()`, `hsl()`, `oklch()`, `oklab()`, the 148 CSS named colours and `transparent`, in modern and legacy syntax. No DOM, so it runs under SSR. Returns `null` — never throws — for anything it cannot resolve, `var()` and `currentColor` included
+-   `toRgb(color): HubRgb | null` - Normalises a string or parsed colour to channels
+-   `toHex(color): string | null` - Renders as `#rrggbb`, or `#rrggbbaa` when translucent
+-   `isValidColor(value): boolean` - Whether the parser can resolve the string
+-   `HUB_NAMED_COLORS: Readonly<Record<string, string>>` - The 148 CSS named colours
+
+### Contrast Functions
+
+-   `relativeLuminance(color): number | null` - WCAG 2 relative luminance, 0 to 1
+-   `contrastRatio(a, b): number | null` - WCAG 2 contrast ratio, 1 to 21
+-   `contrastAPCA(text, background): number | null` - APCA lightness contrast, polarity-aware
+-   `compositeOver(foreground, background): HubColor` - Blends translucent over opaque
+-   `readableOn(background, metric?): string` - Black or white, whichever reads better. Defaults to `'lightness'`, the same decision `--hub-sys-color-*-on` makes in CSS; `'apca'` and `'wcag'` are also available
+-   `HUB_INK_LIGHTNESS_THRESHOLD: number` - The OKLCh lightness above which a surface takes dark ink
+
+### OKLCh Functions
+
+-   `rgbToOklch(color): HubOklch` / `oklchToRgb(color): HubRgb` - Conversions in the space the design system mixes in
+-   `maxSrgbChroma(l, h): number` - Highest in-gamut chroma for a hue at a lightness. The sRGB gamut is not a cylinder — at L 0.578 blue reaches 0.232 and amber only 0.119 — so a palette cannot give every hue the same absolute chroma
+-   `isInSrgbGamut(color): boolean` - Whether the colour survives the trip to sRGB
+-   `clampToSrgbGamut(color): HubOklch` - Reduces chroma until it fits, preserving lightness and hue
+
 ### Focus Functions
 
 -   `getFocusableBoundaryElements(element: HTMLElement): HTMLElement[]` - Gets first and last focusable elements

package/fesm2022/ng-hub-ui-utils.mjs

@@ -29,6 +29,633 @@ function resolveHubAccent(value) {
     return /^[a-zA-Z][\w-]*$/.test(color) ? `var(--hub-sys-color-${color}, ${color})` : color;
 }
 
+/**
+ * Conversions between sRGB and OKLab / OKLCh, using Björn Ottosson's matrices.
+ *
+ * @see https://bottosson.github.io/posts/oklab/
+ */
+/** Expands an sRGB channel (0-255) to its linear-light value (0-1). */
+function toLinear(channel) {
+    const v = channel / 255;
+    return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+}
+/** Compresses a linear-light value (0-1) back to an sRGB channel (0-255), unclamped. */
+function fromLinear(value) {
+    const v = value <= 0.0031308 ? value * 12.92 : 1.055 * Math.pow(value, 1 / 2.4) - 0.055;
+    return v * 255;
+}
+/** Converts an sRGB colour to OKLCh. Alpha is carried through untouched. */
+function rgbToOklch({ r, g, b, a }) {
+    const lr = toLinear(r);
+    const lg = toLinear(g);
+    const lb = toLinear(b);
+    const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+    const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+    const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+    const okL = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+    const okA = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+    const okB = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+    const hue = (Math.atan2(okB, okA) * 180) / Math.PI;
+    return { l: okL, c: Math.hypot(okA, okB), h: hue < 0 ? hue + 360 : hue, a };
+}
+/**
+ * Converts OKLCh to sRGB **without** gamut mapping: channels outside 0-255 are returned
+ * as-is so callers can detect the overflow. Use {@link isInSrgbGamut} to test, or
+ * {@link clampToSrgbGamut} to reduce chroma until the colour fits.
+ */
+function oklchToRgb({ l, c, h, a }) {
+    const rad = (h * Math.PI) / 180;
+    const okA = c * Math.cos(rad);
+    const okB = c * Math.sin(rad);
+    const lCube = Math.pow(l + 0.3963377774 * okA + 0.2158037573 * okB, 3);
+    const mCube = Math.pow(l - 0.1055613458 * okA - 0.0638541728 * okB, 3);
+    const sCube = Math.pow(l - 0.0894841775 * okA - 1.291485548 * okB, 3);
+    return {
+        r: fromLinear(4.0767416621 * lCube - 3.3077115913 * mCube + 0.2309699292 * sCube),
+        g: fromLinear(-1.2684380046 * lCube + 2.6097574011 * mCube - 0.3413193965 * sCube),
+        b: fromLinear(-0.0041960863 * lCube - 0.7034186147 * mCube + 1.707614701 * sCube),
+        a
+    };
+}
+/** Whether an OKLCh colour survives the trip to sRGB without any channel overflowing. */
+function isInSrgbGamut(color) {
+    const { r, g, b } = oklchToRgb(color);
+    return [r, g, b].every((channel) => channel >= -0.02 && channel <= 255.02);
+}
+/**
+ * The highest chroma the given hue can reach at the given lightness inside sRGB.
+ *
+ * The gamut is not a cylinder — at L 0.578 blue reaches ~0.23 while amber stops at ~0.12 —
+ * so a palette that assigns every role the same absolute chroma cannot be built. Callers
+ * scale against this ceiling instead.
+ *
+ * @param l Perceptual lightness, 0-1.
+ * @param h Hue angle in degrees.
+ * @returns The maximum in-gamut chroma, found by bisection.
+ */
+function maxSrgbChroma(l, h) {
+    let low = 0;
+    let high = 0.4;
+    for (let i = 0; i < 32; i++) {
+        const mid = (low + high) / 2;
+        if (isInSrgbGamut({ l, c: mid, h, a: 1 })) {
+            low = mid;
+        }
+        else {
+            high = mid;
+        }
+    }
+    return low;
+}
+/**
+ * Reduces chroma until the colour fits in sRGB, preserving lightness and hue.
+ *
+ * Preferred over clipping the RGB channels, which shifts both hue and lightness in ways
+ * that are visible precisely on the saturated brand colours this is most often used on.
+ */
+function clampToSrgbGamut(color) {
+    if (isInSrgbGamut(color)) {
+        return color;
+    }
+    return { ...color, c: maxSrgbChroma(color.l, color.h) };
+}
+
+/**
+ * The 148 CSS named colours, as defined by CSS Color Module Level 4.
+ *
+ * Kept as a plain hex map rather than parsed at load time: the table is the single
+ * reason a bareword such as `rebeccapurple` can be resolved without a DOM, which is what
+ * makes colour parsing work under server-side rendering.
+ *
+ * @see https://www.w3.org/TR/css-color-4/#named-colors
+ */
+const HUB_NAMED_COLORS = {
+    aliceblue: '#f0f8ff',
+    antiquewhite: '#faebd7',
+    aqua: '#00ffff',
+    aquamarine: '#7fffd4',
+    azure: '#f0ffff',
+    beige: '#f5f5dc',
+    bisque: '#ffe4c4',
+    black: '#000000',
+    blanchedalmond: '#ffebcd',
+    blue: '#0000ff',
+    blueviolet: '#8a2be2',
+    brown: '#a52a2a',
+    burlywood: '#deb887',
+    cadetblue: '#5f9ea0',
+    chartreuse: '#7fff00',
+    chocolate: '#d2691e',
+    coral: '#ff7f50',
+    cornflowerblue: '#6495ed',
+    cornsilk: '#fff8dc',
+    crimson: '#dc143c',
+    cyan: '#00ffff',
+    darkblue: '#00008b',
+    darkcyan: '#008b8b',
+    darkgoldenrod: '#b8860b',
+    darkgray: '#a9a9a9',
+    darkgreen: '#006400',
+    darkgrey: '#a9a9a9',
+    darkkhaki: '#bdb76b',
+    darkmagenta: '#8b008b',
+    darkolivegreen: '#556b2f',
+    darkorange: '#ff8c00',
+    darkorchid: '#9932cc',
+    darkred: '#8b0000',
+    darksalmon: '#e9967a',
+    darkseagreen: '#8fbc8f',
+    darkslateblue: '#483d8b',
+    darkslategray: '#2f4f4f',
+    darkslategrey: '#2f4f4f',
+    darkturquoise: '#00ced1',
+    darkviolet: '#9400d3',
+    deeppink: '#ff1493',
+    deepskyblue: '#00bfff',
+    dimgray: '#696969',
+    dimgrey: '#696969',
+    dodgerblue: '#1e90ff',
+    firebrick: '#b22222',
+    floralwhite: '#fffaf0',
+    forestgreen: '#228b22',
+    fuchsia: '#ff00ff',
+    gainsboro: '#dcdcdc',
+    ghostwhite: '#f8f8ff',
+    gold: '#ffd700',
+    goldenrod: '#daa520',
+    gray: '#808080',
+    green: '#008000',
+    greenyellow: '#adff2f',
+    grey: '#808080',
+    honeydew: '#f0fff0',
+    hotpink: '#ff69b4',
+    indianred: '#cd5c5c',
+    indigo: '#4b0082',
+    ivory: '#fffff0',
+    khaki: '#f0e68c',
+    lavender: '#e6e6fa',
+    lavenderblush: '#fff0f5',
+    lawngreen: '#7cfc00',
+    lemonchiffon: '#fffacd',
+    lightblue: '#add8e6',
+    lightcoral: '#f08080',
+    lightcyan: '#e0ffff',
+    lightgoldenrodyellow: '#fafad2',
+    lightgray: '#d3d3d3',
+    lightgreen: '#90ee90',
+    lightgrey: '#d3d3d3',
+    lightpink: '#ffb6c1',
+    lightsalmon: '#ffa07a',
+    lightseagreen: '#20b2aa',
+    lightskyblue: '#87cefa',
+    lightslategray: '#778899',
+    lightslategrey: '#778899',
+    lightsteelblue: '#b0c4de',
+    lightyellow: '#ffffe0',
+    lime: '#00ff00',
+    limegreen: '#32cd32',
+    linen: '#faf0e6',
+    magenta: '#ff00ff',
+    maroon: '#800000',
+    mediumaquamarine: '#66cdaa',
+    mediumblue: '#0000cd',
+    mediumorchid: '#ba55d3',
+    mediumpurple: '#9370db',
+    mediumseagreen: '#3cb371',
+    mediumslateblue: '#7b68ee',
+    mediumspringgreen: '#00fa9a',
+    mediumturquoise: '#48d1cc',
+    mediumvioletred: '#c71585',
+    midnightblue: '#191970',
+    mintcream: '#f5fffa',
+    mistyrose: '#ffe4e1',
+    moccasin: '#ffe4b5',
+    navajowhite: '#ffdead',
+    navy: '#000080',
+    oldlace: '#fdf5e6',
+    olive: '#808000',
+    olivedrab: '#6b8e23',
+    orange: '#ffa500',
+    orangered: '#ff4500',
+    orchid: '#da70d6',
+    palegoldenrod: '#eee8aa',
+    palegreen: '#98fb98',
+    paleturquoise: '#afeeee',
+    palevioletred: '#db7093',
+    papayawhip: '#ffefd5',
+    peachpuff: '#ffdab9',
+    peru: '#cd853f',
+    pink: '#ffc0cb',
+    plum: '#dda0dd',
+    powderblue: '#b0e0e6',
+    purple: '#800080',
+    rebeccapurple: '#663399',
+    red: '#ff0000',
+    rosybrown: '#bc8f8f',
+    royalblue: '#4169e1',
+    saddlebrown: '#8b4513',
+    salmon: '#fa8072',
+    sandybrown: '#f4a460',
+    seagreen: '#2e8b57',
+    seashell: '#fff5ee',
+    sienna: '#a0522d',
+    silver: '#c0c0c0',
+    skyblue: '#87ceeb',
+    slateblue: '#6a5acd',
+    slategray: '#708090',
+    slategrey: '#708090',
+    snow: '#fffafa',
+    springgreen: '#00ff7f',
+    steelblue: '#4682b4',
+    tan: '#d2b48c',
+    teal: '#008080',
+    thistle: '#d8bfd8',
+    tomato: '#ff6347',
+    turquoise: '#40e0d0',
+    violet: '#ee82ee',
+    wheat: '#f5deb3',
+    white: '#ffffff',
+    whitesmoke: '#f5f5f5',
+    yellow: '#ffff00',
+    yellowgreen: '#9acd32'
+};
+
+const HEX_PATTERN = /^#([0-9a-f]{3,8})$/;
+const FUNCTION_PATTERN = /^([a-z]+)\((.*)\)$/;
+/** Constrains a value to a range, used on the way out so callers never see an out-of-range channel. */
+function clamp$1(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * Reads one numeric component.
+ *
+ * `none` resolves to 0 per CSS Color 4, and a percentage is scaled by `percentBase` —
+ * which differs per channel, so the caller supplies it (255 for rgb, 100 for hsl, 1 for
+ * an OKLCh lightness).
+ *
+ * @returns The parsed number, or `null` when the token is not a number at all.
+ */
+function readNumber(token, percentBase) {
+    if (token === 'none') {
+        return 0;
+    }
+    const isPercentage = token.endsWith('%');
+    const parsed = Number.parseFloat(isPercentage ? token.slice(0, -1) : token);
+    if (Number.isNaN(parsed)) {
+        return null;
+    }
+    return isPercentage ? (parsed / 100) * percentBase : parsed;
+}
+/** Reads a hue angle, honouring the four CSS angle units and normalising to 0-360 degrees. */
+function readHue(token) {
+    if (token === 'none') {
+        return 0;
+    }
+    const match = /^(-?[\d.]+)(deg|rad|turn|grad)?$/.exec(token);
+    if (!match) {
+        return null;
+    }
+    const value = Number.parseFloat(match[1]);
+    const degrees = match[2] === 'rad'
+        ? (value * 180) / Math.PI
+        : match[2] === 'turn'
+            ? value * 360
+            : match[2] === 'grad'
+                ? value * 0.9
+                : value;
+    return ((degrees % 360) + 360) % 360;
+}
+/** Reads an alpha component, accepting both `0.5` and `50%`. Missing alpha means opaque. */
+function readAlpha(token) {
+    if (token === undefined) {
+        return 1;
+    }
+    const parsed = readNumber(token, 1);
+    return parsed === null ? null : clamp$1(parsed, 0, 1);
+}
+/**
+ * Splits a colour function's argument list into components plus an optional alpha.
+ *
+ * Handles the modern (`0 0 0 / 50%`) and legacy (`0, 0, 0, 0.5`) syntaxes in one pass, so
+ * every colour function below is spared knowing which of the two it was given.
+ */
+function splitComponents(body) {
+    const [values, slashAlpha] = body.split('/');
+    const components = values
+        .trim()
+        .split(/[\s,]+/)
+        .filter(Boolean);
+    if (slashAlpha !== undefined) {
+        return { components, alpha: slashAlpha.trim() };
+    }
+    // Legacy `rgba()` / `hsla()` carry alpha as a fourth comma-separated component.
+    return components.length === 4
+        ? { components: components.slice(0, 3), alpha: components[3] }
+        : { components, alpha: undefined };
+}
+/** Converts an HSL triplet (hue in degrees, saturation and lightness 0-1) to sRGB channels. */
+function hslToRgbChannels(h, s, l) {
+    const chroma = (1 - Math.abs(2 * l - 1)) * s;
+    const sector = h / 60;
+    const secondary = chroma * (1 - Math.abs((sector % 2) - 1));
+    const offset = l - chroma / 2;
+    const rgb = sector < 1
+        ? [chroma, secondary, 0]
+        : sector < 2
+            ? [secondary, chroma, 0]
+            : sector < 3
+                ? [0, chroma, secondary]
+                : sector < 4
+                    ? [0, secondary, chroma]
+                    : sector < 5
+                        ? [secondary, 0, chroma]
+                        : [chroma, 0, secondary];
+    return [(rgb[0] + offset) * 255, (rgb[1] + offset) * 255, (rgb[2] + offset) * 255];
+}
+/** Expands `#rgb`, `#rgba`, `#rrggbb` and `#rrggbbaa` into channels. */
+function parseHex(digits) {
+    const expanded = digits.length === 3 || digits.length === 4
+        ? digits
+            .split('')
+            .map((digit) => digit + digit)
+            .join('')
+        : digits;
+    if (expanded.length !== 6 && expanded.length !== 8) {
+        return null;
+    }
+    const channel = (index) => Number.parseInt(expanded.slice(index * 2, index * 2 + 2), 16);
+    return {
+        r: channel(0),
+        g: channel(1),
+        b: channel(2),
+        a: expanded.length === 8 ? channel(3) / 255 : 1
+    };
+}
+/**
+ * Parses any CSS colour string into sRGB channels, with no DOM involved.
+ *
+ * Accepts hex (3/4/6/8 digits), `rgb()`/`rgba()`, `hsl()`/`hsla()`, `oklch()`, `oklab()`,
+ * the 148 CSS named colours and `transparent`, in both modern and legacy syntax. Anything
+ * else — including `var(...)`, `currentColor` and CIE `lab()`/`lch()` — returns `null`
+ * rather than throwing, because every caller here has a sensible fallback and none of them
+ * can act on an exception.
+ *
+ * Colours outside the sRGB gamut (an `oklch()` with excess chroma) come back clamped per
+ * channel; use the OKLCh helpers directly when the overflow itself matters.
+ *
+ * @param value The CSS colour string.
+ * @returns The parsed colour, or `null` when the string is not a resolvable colour.
+ */
+function parseColor(value) {
+    const input = value?.trim().toLowerCase();
+    if (!input) {
+        return null;
+    }
+    if (input === 'transparent') {
+        return { r: 0, g: 0, b: 0, a: 0 };
+    }
+    const named = HUB_NAMED_COLORS[input];
+    if (named) {
+        return parseHex(named.slice(1));
+    }
+    const hex = HEX_PATTERN.exec(input);
+    if (hex) {
+        return parseHex(hex[1]);
+    }
+    const fn = FUNCTION_PATTERN.exec(input);
+    if (!fn) {
+        return null;
+    }
+    const [, name, body] = fn;
+    const { components, alpha: rawAlpha } = splitComponents(body);
+    const alpha = readAlpha(rawAlpha);
+    if (alpha === null || components.length !== 3) {
+        return null;
+    }
+    if (name === 'rgb' || name === 'rgba') {
+        const channels = components.map((component) => readNumber(component, 255));
+        if (channels.some((channel) => channel === null)) {
+            return null;
+        }
+        const [r, g, b] = channels;
+        return { r: clamp$1(r, 0, 255), g: clamp$1(g, 0, 255), b: clamp$1(b, 0, 255), a: alpha };
+    }
+    if (name === 'hsl' || name === 'hsla') {
+        const h = readHue(components[0]);
+        const s = readNumber(components[1], 1);
+        const l = readNumber(components[2], 1);
+        if (h === null || s === null || l === null) {
+            return null;
+        }
+        const [r, g, b] = hslToRgbChannels(h, clamp$1(s, 0, 1), clamp$1(l, 0, 1));
+        return { r, g, b, a: alpha };
+    }
+    if (name === 'oklch' || name === 'oklab') {
+        // Percentages on the chroma and a/b axes are relative to a 0.4 reference per CSS Color 4.
+        const l = readNumber(components[0], 1);
+        const second = readNumber(components[1], 0.4);
+        const third = name === 'oklch' ? readHue(components[2]) : readNumber(components[2], 0.4);
+        if (l === null || second === null || third === null) {
+            return null;
+        }
+        const polar = name === 'oklch'
+            ? { c: second, h: third }
+            : { c: Math.hypot(second, third), h: ((Math.atan2(third, second) * 180) / Math.PI + 360) % 360 };
+        const { r, g, b } = oklchToRgb({ l, c: polar.c, h: polar.h, a: alpha });
+        return { r: clamp$1(r, 0, 255), g: clamp$1(g, 0, 255), b: clamp$1(b, 0, 255), a: alpha };
+    }
+    return null;
+}
+/**
+ * Normalises any accepted colour to a {@link HubRgb}, so helpers can take strings or
+ * already-parsed colours without each of them repeating the check.
+ */
+function toRgb(color) {
+    return typeof color === 'string' ? parseColor(color) : color;
+}
+/**
+ * Renders a colour as a `#rrggbb` hex string, or `#rrggbbaa` when it is translucent.
+ *
+ * @param color A CSS colour string or parsed colour.
+ * @returns The hex string, or `null` when the input could not be parsed.
+ */
+function toHex(color) {
+    const rgb = toRgb(color);
+    if (!rgb) {
+        return null;
+    }
+    const pair = (channel) => Math.round(clamp$1(channel, 0, 255))
+        .toString(16)
+        .padStart(2, '0');
+    const alpha = rgb.a < 1 ? pair(rgb.a * 255) : '';
+    return `#${pair(rgb.r)}${pair(rgb.g)}${pair(rgb.b)}${alpha}`;
+}
+/**
+ * Whether a string is a colour this parser can resolve.
+ *
+ * Note this is narrower than "valid CSS": `var(--x)` and `currentColor` are valid in a
+ * stylesheet but have no value outside the cascade, so they are reported as invalid here.
+ */
+function isValidColor(value) {
+    return parseColor(value) !== null;
+}
+
+/**
+ * Contrast and readability helpers.
+ *
+ * The WCAG 2 relative-luminance and contrast-ratio formulas, and the APCA implementation,
+ * follow chroma.js (BSD-3-Clause, Copyright (c) 2011-2025 Gregor Aisch). APCA itself is
+ * specified by Myndex.
+ *
+ * @see https://www.w3.org/TR/WCAG20/#contrast-ratiodef
+ * @see https://readtech.org/ARC/
+ */
+/** Linearises one sRGB channel for the WCAG luminance sum. */
+function linearise(channel) {
+    const v = channel / 255;
+    return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+}
+/**
+ * WCAG 2 relative luminance, 0 (black) to 1 (white).
+ *
+ * Alpha is ignored: a translucent colour has no luminance of its own until it is composited,
+ * so blend it with {@link compositeOver} first when that matters.
+ *
+ * @param color A CSS colour string or parsed colour.
+ * @returns The relative luminance, or `null` when the colour could not be parsed.
+ */
+function relativeLuminance(color) {
+    const rgb = toRgb(color);
+    if (!rgb) {
+        return null;
+    }
+    return 0.2126 * linearise(rgb.r) + 0.7152 * linearise(rgb.g) + 0.0722 * linearise(rgb.b);
+}
+/**
+ * Composites a translucent foreground over an opaque background, in sRGB.
+ *
+ * Kept simple on purpose: it matches what a browser does for a plain `background-color`
+ * stack, which is the only case the contrast helpers need.
+ */
+function compositeOver(foreground, background) {
+    const fg = toRgb(foreground);
+    const bg = toRgb(background);
+    if (!fg || !bg) {
+        return foreground;
+    }
+    if (fg.a >= 1) {
+        return fg;
+    }
+    return {
+        r: bg.r + (fg.r - bg.r) * fg.a,
+        g: bg.g + (fg.g - bg.g) * fg.a,
+        b: bg.b + (fg.b - bg.b) * fg.a,
+        a: 1
+    };
+}
+/**
+ * WCAG 2 contrast ratio between two colours, from 1 (identical) to 21 (black on white).
+ *
+ * The thresholds that matter: 4.5 for body text at AA, 3 for large text and UI components,
+ * 7 for AAA.
+ *
+ * @param a First colour.
+ * @param b Second colour.
+ * @returns The ratio, or `null` when either colour could not be parsed.
+ */
+function contrastRatio(a, b) {
+    const first = relativeLuminance(a);
+    const second = relativeLuminance(b);
+    if (first === null || second === null) {
+        return null;
+    }
+    return first > second ? (first + 0.05) / (second + 0.05) : (second + 0.05) / (first + 0.05);
+}
+const APCA_W_OFFSET = 0.027;
+const APCA_P_IN = 0.0005;
+const APCA_P_OUT = 0.1;
+const APCA_R_SCALE = 1.14;
+const APCA_B_THRESHOLD = 0.022;
+const APCA_B_EXP = 1.414;
+/** APCA's own luminance, which differs from WCAG's in both exponent and channel handling. */
+function apcaLuminance(r, g, b) {
+    return 0.2126729 * Math.pow(r / 255, 2.4) + 0.7151522 * Math.pow(g / 255, 2.4) + 0.072175 * Math.pow(b / 255, 2.4);
+}
+/**
+ * APCA (Accessible Perceptual Contrast Algorithm) lightness contrast, roughly -108 to 106.
+ *
+ * Unlike the WCAG ratio it is polarity-aware — dark-on-light and light-on-dark of the same
+ * pair score differently — which is why it predicts real readability better, particularly
+ * for the mid-lightness accents this design system is full of. The sign carries the
+ * polarity; compare `Math.abs()` against a threshold (60 is a common floor for body text).
+ *
+ * APCA is still a draft, so treat the number as guidance rather than as a conformance claim.
+ *
+ * @param text The text colour. A translucent value is composited over `background` first.
+ * @param background The background colour.
+ * @returns The APCA score, or `null` when either colour could not be parsed.
+ */
+function contrastAPCA(text, background) {
+    const bg = toRgb(background);
+    if (!bg) {
+        return null;
+    }
+    const fg = toRgb(compositeOver(text, bg));
+    if (!fg) {
+        return null;
+    }
+    const rawText = apcaLuminance(fg.r, fg.g, fg.b);
+    const rawBg = apcaLuminance(bg.r, bg.g, bg.b);
+    // Soft-clamp near-black levels, where the power curve would otherwise overstate contrast.
+    const yText = rawText >= APCA_B_THRESHOLD ? rawText : rawText + Math.pow(APCA_B_THRESHOLD - rawText, APCA_B_EXP);
+    const yBg = rawBg >= APCA_B_THRESHOLD ? rawBg : rawBg + Math.pow(APCA_B_THRESHOLD - rawBg, APCA_B_EXP);
+    const normalPolarity = Math.pow(yBg, 0.56) - Math.pow(yText, 0.57);
+    const reversePolarity = Math.pow(yBg, 0.65) - Math.pow(yText, 0.62);
+    const contrast = Math.abs(yBg - yText) < APCA_P_IN ? 0 : yText < yBg ? normalPolarity * APCA_R_SCALE : reversePolarity * APCA_R_SCALE;
+    const scaled = Math.abs(contrast) < APCA_P_OUT ? 0 : contrast > 0 ? contrast - APCA_W_OFFSET : contrast + APCA_W_OFFSET;
+    return scaled * 100;
+}
+/** The two ends every readable-foreground decision picks between. */
+const INK = '#000000';
+const PAPER = '#ffffff';
+/**
+ * The perceptual lightness above which a surface takes dark ink.
+ *
+ * Must stay in step with the `--hub-sys-color-*-on` token, which computes the same decision
+ * in CSS as `oklch(from … clamp(0, (0.62 - l) * 1000, 1) 0 h)`. If the two ever diverge, the
+ * same accent gets one ink colour from the stylesheet and another from TypeScript.
+ */
+const HUB_INK_LIGHTNESS_THRESHOLD = 0.62;
+/**
+ * Picks black or white — whichever reads better on the given background.
+ *
+ * Defaults to `'lightness'`: a threshold on OKLCh perceptual lightness, which is exactly what
+ * the `--hub-sys-color-*-on` token computes in CSS. Choosing it over the WCAG ratio is not a
+ * preference but a measured decision — maximising the WCAG 2 ratio puts **black** text on the
+ * design system's own blue, green and red accents, because that formula underweights blue at
+ * mid lightness. APCA agrees with the lightness rule on all nine semantic roles; WCAG disagrees
+ * on three of them.
+ *
+ * Unparseable input yields black, the safer default on the light surfaces this library assumes.
+ *
+ * @param background The surface the text will sit on.
+ * @param metric `'lightness'` (default) matches the design-system token; `'apca'` maximises the
+ * APCA score; `'wcag'` maximises the WCAG 2 ratio — correct for conformance arithmetic, but a
+ * poor predictor of what actually reads well on a saturated accent.
+ * @returns `'#000000'` or `'#ffffff'`.
+ */
+function readableOn(background, metric = 'lightness') {
+    const rgb = toRgb(background);
+    if (!rgb) {
+        return INK;
+    }
+    if (metric === 'lightness') {
+        return rgbToOklch(rgb).l >= HUB_INK_LIGHTNESS_THRESHOLD ? INK : PAPER;
+    }
+    const score = (foreground) => metric === 'apca' ? Math.abs(contrastAPCA(foreground, rgb) ?? 0) : (contrastRatio(foreground, rgb) ?? 0);
+    return score(PAPER) > score(INK) ? PAPER : INK;
+}
+
 /**
  * Clamps a value into the `[0, max]` range.
  *
@@ -2518,5 +3145,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { ContentRef, FOCUSABLE_ELEMENTS_SELECTOR, GetPipe, HUB_DROPDOWN_POSITIONS, HUB_TOOLTIP_ADAPTER, HUB_TRANSLATION_CONFIG, HUB_TRANSLATION_PREFIX, HUB_TRANSLATION_SOURCE, HubDragDropService, HubOverflowTooltipDirective, HubTooltipController, HubTooltipDirective, HubTranslationService, IsObjectPipe, IsObservablePipe, IsStringPipe, OverlayPosition, OverlayRef, OverlayService, PopupService, ScrollBar, TooltipDirective, TranslatePipe, UcfirstPipe, UnwrapAsyncPipe, clamp, closest, computeTargetIndex, containsNode, copyArrayItem, createNativeDragImage, createPointerDragSession, debouncedSignal, equals, generateUniqueId, getActiveElement, getFocusableBoundaryElements, getValue, getValueInRange, hubCompleteTransition, hubFocusTrap, hubRunTransition, hubTooltipAdapter, interpolateString, isDefined, isInteger, isNumber, isObject, isPromise, isString, mergeDeep, moveItemInArray, padNumber, provideHubTooltip, provideHubTranslation, provideHubTranslationAdapter, reflow, regExpEscape, registerOverlayKeydown, removeAccents, resolveDropPosition, resolveHubAccent, runInZone, toAbsoluteIndex, toInteger, toString, transferArrayItem };
+export { ContentRef, FOCUSABLE_ELEMENTS_SELECTOR, GetPipe, HUB_DROPDOWN_POSITIONS, HUB_INK_LIGHTNESS_THRESHOLD, HUB_NAMED_COLORS, HUB_TOOLTIP_ADAPTER, HUB_TRANSLATION_CONFIG, HUB_TRANSLATION_PREFIX, HUB_TRANSLATION_SOURCE, HubDragDropService, HubOverflowTooltipDirective, HubTooltipController, HubTooltipDirective, HubTranslationService, IsObjectPipe, IsObservablePipe, IsStringPipe, OverlayPosition, OverlayRef, OverlayService, PopupService, ScrollBar, TooltipDirective, TranslatePipe, UcfirstPipe, UnwrapAsyncPipe, clamp, clampToSrgbGamut, closest, compositeOver, computeTargetIndex, containsNode, contrastAPCA, contrastRatio, copyArrayItem, createNativeDragImage, createPointerDragSession, debouncedSignal, equals, generateUniqueId, getActiveElement, getFocusableBoundaryElements, getValue, getValueInRange, hubCompleteTransition, hubFocusTrap, hubRunTransition, hubTooltipAdapter, interpolateString, isDefined, isInSrgbGamut, isInteger, isNumber, isObject, isPromise, isString, isValidColor, maxSrgbChroma, mergeDeep, moveItemInArray, oklchToRgb, padNumber, parseColor, provideHubTooltip, provideHubTranslation, provideHubTranslationAdapter, readableOn, reflow, regExpEscape, registerOverlayKeydown, relativeLuminance, removeAccents, resolveDropPosition, resolveHubAccent, rgbToOklch, runInZone, toAbsoluteIndex, toHex, toInteger, toRgb, toString, transferArrayItem };
 //# sourceMappingURL=ng-hub-ui-utils.mjs.map