zabi-components 7.0.2 → 8.1.0

package/dist/create-theme/lib/ramp-math.js

@@ -0,0 +1,128 @@
+/**
+ * The maths behind every chromatic ramp: one shared lightness curve, one
+ * chroma envelope, and a solver that lands a hue and chroma on a CIE L*.
+ *
+ * It lives here, not in tokens/, because the theme generator ships it: this
+ * directory is copied into dist/create-theme/ and runs under plain Node in an
+ * app's project. tokens/chromatic-scales.js imports it for the library's own
+ * ramps, so the library and a generated brand cannot drift onto two curves.
+ *
+ * Runtime dependency: culori.
+ */
+
+import { converter, formatHex, inGamut } from 'culori';
+
+const toLab = converter('lab');
+const toOklch = converter('oklch');
+const toRgb = converter('rgb');
+const rgbInGamut = inGamut('rgb');
+
+export const RAMP_STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+
+/**
+ * The shared lightness curve, in CIE L*.
+ *
+ * Step 600 sits at L* 47, which is the darkest a fill can be while still
+ * reading as "coloured" and the lightest it can be while keeping >= 4.5:1
+ * against white. Every semantic token resolves to step 600 in light mode
+ * (and mirrors to step 400 in dark).
+ */
+export const TARGET_LIGHTNESS = {
+    50: 97,
+    100: 94,
+    200: 88,
+    300: 80,
+    400: 70,
+    500: 58,
+    600: 47,
+    700: 38,
+    800: 29,
+    900: 20,
+    950: 12,
+};
+
+/**
+ * Chroma envelope across the ramp, as a fraction of peakChroma.
+ * Colour is most saturated in the middle and tapers at both ends, which is how
+ * a ramp stays usable: near-white tints don't turn neon, near-black shades
+ * don't turn muddy.
+ */
+export const CHROMA_ENVELOPE = {
+    50: 0.08,
+    100: 0.16,
+    200: 0.32,
+    300: 0.52,
+    400: 0.74,
+    500: 0.92,
+    600: 1.0,
+    700: 0.94,
+    800: 0.82,
+    900: 0.66,
+    950: 0.48,
+};
+
+export function cieL(color) {
+    return toLab(color).l;
+}
+
+/** Pull chroma down until the colour fits in sRGB, keeping L* and hue. */
+function fitToGamut(oklchColor) {
+    let { l, c, h } = oklchColor;
+    if (rgbInGamut({ mode: 'oklch', l, c, h })) return { mode: 'oklch', l, c, h };
+    let lo = 0;
+    let hi = c;
+    for (let i = 0; i < 40; i += 1) {
+        const mid = (lo + hi) / 2;
+        if (rgbInGamut({ mode: 'oklch', l, c: mid, h })) lo = mid;
+        else hi = mid;
+    }
+    return { mode: 'oklch', l, c: lo, h };
+}
+
+/**
+ * Solve for the OKLCH lightness that lands on a given CIE L*, at a fixed hue
+ * and chroma. OKLCH L and CIE L* are both perceptual but not identical, so a
+ * short bisection is the honest way to hit the target.
+ */
+export function solveForCieL(targetL, chroma, hue) {
+    let lo = 0;
+    let hi = 1;
+    let best = { mode: 'oklch', l: 0.5, c: chroma, h: hue };
+    for (let i = 0; i < 48; i += 1) {
+        const mid = (lo + hi) / 2;
+        const candidate = fitToGamut({ mode: 'oklch', l: mid, c: chroma, h: hue });
+        const actual = cieL(candidate);
+        best = candidate;
+        if (Math.abs(actual - targetL) < 0.01) break;
+        if (actual < targetL) lo = mid;
+        else hi = mid;
+    }
+    return best;
+}
+
+/** The colour at one CIE L*, hue and chroma, as `#rrggbb`. */
+export function hexAt(targetL, chroma, hue) {
+    return formatHex(toRgb(solveForCieL(targetL, chroma, hue)));
+}
+
+/**
+ * One ramp from a seed `{ hue, peakChroma, hueShift }`, as `{ step: '#rrggbb' }`.
+ * Hue is in OKLCH degrees; `hueShift` rotates it linearly from step 50 to 950.
+ */
+export function generateRampFromSeed(seed) {
+    const out = {};
+    for (const step of RAMP_STEPS) {
+        const t = (RAMP_STEPS.indexOf(step)) / (RAMP_STEPS.length - 1);
+        const hue = (seed.hue + (seed.hueShift ?? 0) * t + 360) % 360;
+        const chroma = seed.peakChroma * CHROMA_ENVELOPE[step];
+        out[step] = hexAt(TARGET_LIGHTNESS[step], chroma, hue);
+    }
+    return out;
+}
+
+/** Measured CIE L* of a hex string, to one decimal. */
+export function measureLightness(hex) {
+    return Math.round(cieL(hex) * 10) / 10;
+}
+
+export { toOklch, toLab };

package/dist/create-theme/lib/resolve.js

@@ -0,0 +1,141 @@
+/**
+ * Resolve design tokens the way a browser would, without a browser.
+ *
+ * Pure functions over a `{ '--token': 'value' }` map: no file access and no
+ * dependencies, because the theme generator ships this file to apps
+ * (dist/create-theme/lib/) to run its contrast check. The library's own
+ * guards reach it through scripts/resolve-tokens.js, which adds the PostCSS
+ * reading of stylesheets on top.
+ *
+ * Supported, because it is all the stylesheet uses for a flat colour:
+ *   - `var(--token)` and `var(--token, fallback)`, anywhere in a value
+ *   - `color-mix(in srgb, <opaque> p%, <opaque>)` (either or both percentages)
+ * Anything else (`rgba()`, a mix with `transparent`) is returned as written,
+ * for the caller to composite over a surface or to skip.
+ */
+
+const HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+
+function parseHex(hex) {
+    const h = hex.replace('#', '');
+    const full = h.length === 3 ? h.split('').map((c) => c + c).join('') : h;
+    return [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16));
+}
+
+function toHex(channels) {
+    return '#' + channels.map((c) => Math.round(c).toString(16).padStart(2, '0')).join('');
+}
+
+/** Split on commas that are not inside parentheses. */
+function splitTopLevel(text) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const char of text) {
+        if (char === '(') depth += 1;
+        if (char === ')') depth -= 1;
+        if (char === ',' && depth === 0) {
+            parts.push(current.trim());
+            current = '';
+        } else {
+            current += char;
+        }
+    }
+    parts.push(current.trim());
+    return parts;
+}
+
+/** Index of the parenthesis that closes the one at `open`. */
+function closingParen(text, open) {
+    let depth = 0;
+    for (let i = open; i < text.length; i += 1) {
+        if (text[i] === '(') depth += 1;
+        if (text[i] === ')') {
+            depth -= 1;
+            if (depth === 0) return i;
+        }
+    }
+    return -1;
+}
+
+/**
+ * Replace every `var()` in `value` with what it refers to in `map`.
+ * Returns null when a reference has neither a declaration nor a fallback,
+ * which is what makes a declaration invalid at computed-value time.
+ */
+export function substituteVars(map, value, seen = new Set()) {
+    let out = value.replace(/\/\*[\s\S]*?\*\//g, '').trim();
+    let guard = 0;
+    while (out.includes('var(')) {
+        guard += 1;
+        if (guard > 200) return null;
+        const start = out.indexOf('var(');
+        const end = closingParen(out, start + 3);
+        if (end === -1) return null;
+        const [name, ...fallback] = splitTopLevel(out.slice(start + 4, end));
+        let replacement;
+        if (map[name] !== undefined && !seen.has(name)) {
+            replacement = substituteVars(map, map[name], new Set([...seen, name]));
+        }
+        if (replacement === null || replacement === undefined) {
+            replacement = fallback.length
+                ? substituteVars(map, fallback.join(', '), seen)
+                : null;
+        }
+        if (replacement === null) return null;
+        out = out.slice(0, start) + replacement + out.slice(end + 1);
+    }
+    return out;
+}
+
+/**
+ * `color-mix(in srgb, A p%, B q%)` of two opaque colours, as hex.
+ * Returns null for anything it cannot reduce to one flat colour.
+ */
+export function evaluateColorMix(value) {
+    const match = /^color-mix\(([\s\S]*)\)$/.exec(value.trim());
+    if (!match) return null;
+    const [space, first, second] = splitTopLevel(match[1]);
+    if (!space || !first || !second || space.replace(/\s+/g, ' ') !== 'in srgb') return null;
+
+    const operand = (text) => {
+        const percent = /(-?[\d.]+)%/.exec(text);
+        const colourText = text.replace(/-?[\d.]+%/, '').trim();
+        const colour = HEX.test(colourText) ? colourText : evaluateColorMix(colourText);
+        return colour ? { colour, percent: percent ? Number(percent[1]) : null } : null;
+    };
+    const a = operand(first);
+    const b = operand(second);
+    if (!a || !b) return null;
+
+    let pa = a.percent;
+    let pb = b.percent;
+    if (pa === null && pb === null) { pa = 50; pb = 50; }
+    else if (pa === null) pa = 100 - pb;
+    else if (pb === null) pb = 100 - pa;
+    const total = pa + pb;
+    // A sum under 100% leaves the result partly transparent; over-100 is normalised.
+    if (total <= 0 || total < 100) return null;
+    const wa = pa / total;
+    const ca = parseHex(a.colour);
+    const cb = parseHex(b.colour);
+    return toHex(ca.map((channel, i) => channel * wa + cb[i] * (1 - wa)));
+}
+
+/**
+ * The literal a token computes to: `var()` chains followed and an opaque
+ * `color-mix()` evaluated to hex. Null when the token is not declared.
+ */
+export function resolveTokenValue(map, token) {
+    if (map[token] === undefined) return null;
+    const substituted = substituteVars(map, map[token], new Set([token]));
+    if (substituted === null) return null;
+    if (substituted.startsWith('color-mix(')) return evaluateColorMix(substituted) ?? substituted;
+    return substituted;
+}
+
+/** As above, but only when the result is one flat opaque colour. */
+export function resolveTokenColor(map, token) {
+    const value = resolveTokenValue(map, token);
+    return value && HEX.test(value) ? value.toLowerCase() : null;
+}