color-value-tools 1.2.1 → 1.2.2

package/dist/esm/a11y.js

@@ -0,0 +1,237 @@
+// Luminance, WCAG contrast, perceptual difference and color-blindness simulation.
+import { normalizeColor } from './parse.js';
+import { rgbToHex, rgbToLab } from './convert/spaces.js';
+export function relativeLuminance(color) {
+    var _a, _b, _c;
+    const n = normalizeColor(color);
+    const r = ((_a = n.r) !== null && _a !== void 0 ? _a : 0) / 255;
+    const g = ((_b = n.g) !== null && _b !== void 0 ? _b : 0) / 255;
+    const b = ((_c = n.b) !== null && _c !== void 0 ? _c : 0) / 255;
+    const srgbToLin = (c) => (c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+    const R = srgbToLin(r), G = srgbToLin(g), B = srgbToLin(b);
+    return 0.2126 * R + 0.7152 * G + 0.0722 * B;
+}
+export function contrastRatio(a, b) {
+    const L1 = relativeLuminance(a);
+    const L2 = relativeLuminance(b);
+    const light = Math.max(L1, L2);
+    const dark = Math.min(L1, L2);
+    return +((light + 0.05) / (dark + 0.05)).toFixed(2);
+}
+export function isDark(color, threshold = 0.5) {
+    return relativeLuminance(color) < threshold;
+}
+export function isLight(color, threshold = 0.5) {
+    return !isDark(color, threshold);
+}
+export function wcagLevel(foreground, background) {
+    const ratio = contrastRatio(foreground, background);
+    if (ratio >= 7)
+        return 'AAA';
+    if (ratio >= 4.5)
+        return 'AA';
+    if (ratio >= 3)
+        return 'AA-large';
+    return 'fail';
+}
+export function bestTextColor(background) {
+    const onBlack = contrastRatio(background, '#000000');
+    const onWhite = contrastRatio(background, '#ffffff');
+    return onBlack >= onWhite ? '#000000' : '#ffffff';
+}
+export function bestContrastColor(background, candidates) {
+    let best = candidates[0];
+    let bestRatio = -1;
+    for (const c of candidates) {
+        const ratio = contrastRatio(background, c);
+        if (ratio > bestRatio) {
+            bestRatio = ratio;
+            best = c;
+        }
+    }
+    return best;
+}
+export function colorDeltaE(c1, c2) {
+    var _a, _b, _c, _d, _e, _f;
+    const n1 = normalizeColor(c1);
+    const n2 = normalizeColor(c2);
+    const lab1 = rgbToLab({ r: (_a = n1.r) !== null && _a !== void 0 ? _a : 0, g: (_b = n1.g) !== null && _b !== void 0 ? _b : 0, b: (_c = n1.b) !== null && _c !== void 0 ? _c : 0 });
+    const lab2 = rgbToLab({ r: (_d = n2.r) !== null && _d !== void 0 ? _d : 0, g: (_e = n2.g) !== null && _e !== void 0 ? _e : 0, b: (_f = n2.b) !== null && _f !== void 0 ? _f : 0 });
+    // CIEDE2000
+    const deg = (rad) => rad * (180 / Math.PI);
+    const rad = (d) => d * (Math.PI / 180);
+    const { L: L1, a: a1, b: b1 } = lab1;
+    const { L: L2, a: a2, b: b2 } = lab2;
+    const dL = L2 - L1;
+    const Lm = (L1 + L2) / 2;
+    const C1 = Math.sqrt(a1 * a1 + b1 * b1);
+    const C2 = Math.sqrt(a2 * a2 + b2 * b2);
+    const Cm = (C1 + C2) / 2;
+    const Cm7 = Math.pow(Cm, 7);
+    const G = 0.5 * (1 - Math.sqrt(Cm7 / (Cm7 + Math.pow(25, 7))));
+    const a1p = a1 * (1 + G), a2p = a2 * (1 + G);
+    const C1p = Math.sqrt(a1p * a1p + b1 * b1);
+    const C2p = Math.sqrt(a2p * a2p + b2 * b2);
+    const dCp = C2p - C1p;
+    const Cmp = (C1p + C2p) / 2;
+    let h1p = deg(Math.atan2(b1, a1p));
+    if (h1p < 0)
+        h1p += 360;
+    let h2p = deg(Math.atan2(b2, a2p));
+    if (h2p < 0)
+        h2p += 360;
+    let dhp;
+    if (Math.abs(h1p - h2p) <= 180)
+        dhp = h2p - h1p;
+    else if (h2p <= h1p)
+        dhp = h2p - h1p + 360;
+    else
+        dhp = h2p - h1p - 360;
+    const dHp = 2 * Math.sqrt(C1p * C2p) * Math.sin(rad(dhp / 2));
+    let Hmp;
+    if (Math.abs(h1p - h2p) <= 180)
+        Hmp = (h1p + h2p) / 2;
+    else if (h1p + h2p < 360)
+        Hmp = (h1p + h2p + 360) / 2;
+    else
+        Hmp = (h1p + h2p - 360) / 2;
+    const T = 1 -
+        0.17 * Math.cos(rad(Hmp - 30)) +
+        0.24 * Math.cos(rad(2 * Hmp)) +
+        0.32 * Math.cos(rad(3 * Hmp + 6)) -
+        0.2 * Math.cos(rad(4 * Hmp - 63));
+    const SL = 1 + (0.015 * Math.pow(Lm - 50, 2)) / Math.sqrt(20 + Math.pow(Lm - 50, 2));
+    const SC = 1 + 0.045 * Cmp;
+    const SH = 1 + 0.015 * Cmp * T;
+    const Cmp7 = Math.pow(Cmp, 7);
+    const RC = 2 * Math.sqrt(Cmp7 / (Cmp7 + Math.pow(25, 7)));
+    const dTheta = 30 * Math.exp(-Math.pow((Hmp - 275) / 25, 2));
+    const RT = -Math.sin(rad(2 * dTheta)) * RC;
+    return +Math.sqrt(Math.pow(dL / SL, 2) +
+        Math.pow(dCp / SC, 2) +
+        Math.pow(dHp / SH, 2) +
+        RT * (dCp / SC) * (dHp / SH)).toFixed(4);
+}
+// ─── Color blindness simulation ────────────────────────────────────
+function _simulateCB(color, matrix) {
+    var _a, _b, _c;
+    const n = normalizeColor(color);
+    // linearize
+    const lin = (v) => {
+        const c = v / 255;
+        return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+    };
+    const enc = (v) => {
+        const c = v <= 0.0031308 ? 12.92 * v : 1.055 * Math.pow(v, 1 / 2.4) - 0.055;
+        return Math.round(Math.max(0, Math.min(1, c)) * 255);
+    };
+    const r = lin((_a = n.r) !== null && _a !== void 0 ? _a : 0), g = lin((_b = n.g) !== null && _b !== void 0 ? _b : 0), b = lin((_c = n.b) !== null && _c !== void 0 ? _c : 0);
+    const nr = enc(matrix[0][0] * r + matrix[0][1] * g + matrix[0][2] * b);
+    const ng = enc(matrix[1][0] * r + matrix[1][1] * g + matrix[1][2] * b);
+    const nb = enc(matrix[2][0] * r + matrix[2][1] * g + matrix[2][2] * b);
+    return rgbToHex({ r: nr, g: ng, b: nb });
+}
+const _PROTANOPIA_M = [
+    [0.56667, 0.43333, 0.0],
+    [0.55833, 0.44167, 0.0],
+    [0.0, 0.24167, 0.75833],
+];
+const _DEUTERANOPIA_M = [
+    [0.625, 0.375, 0.0],
+    [0.7, 0.3, 0.0],
+    [0.0, 0.3, 0.7],
+];
+const _TRITANOPIA_M = [
+    [0.95, 0.05, 0.0],
+    [0.0, 0.43333, 0.56667],
+    [0.0, 0.475, 0.525],
+];
+export function simulateProtanopia(color) {
+    return _simulateCB(color, _PROTANOPIA_M);
+}
+export function simulateDeuteranopia(color) {
+    return _simulateCB(color, _DEUTERANOPIA_M);
+}
+export function simulateTritanopia(color) {
+    return _simulateCB(color, _TRITANOPIA_M);
+}
+export function simulateColorBlindness(color, type) {
+    if (type === 'protanopia')
+        return simulateProtanopia(color);
+    if (type === 'deuteranopia')
+        return simulateDeuteranopia(color);
+    return simulateTritanopia(color);
+}
+export function isReadableOnBackground(textColor, background, options) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    const level = (_a = options === null || options === void 0 ? void 0 : options.level) !== null && _a !== void 0 ? _a : 'AA';
+    const large = (_b = options === null || options === void 0 ? void 0 : options.largeText) !== null && _b !== void 0 ? _b : false;
+    const minRequired = level === 'AAA' ? (large ? 4.5 : 7) : large ? 3 : 4.5;
+    // The specific effective background color that minRatio was actually
+    // computed against — wcagLevel below is derived from this same color
+    // (never a hardcoded '#ffffff') so it can't disagree with minRatio/readable.
+    let minRatio;
+    let effectiveBackground;
+    if (typeof background === 'string') {
+        effectiveBackground = background;
+        minRatio = contrastRatio(textColor, background);
+    }
+    else if (background.type === 'semi-transparent') {
+        const underlay = (_c = background.underlay) !== null && _c !== void 0 ? _c : '#ffffff';
+        const fg = normalizeColor(background.color);
+        const bg = normalizeColor(underlay);
+        const alpha = (_d = fg.a) !== null && _d !== void 0 ? _d : 1;
+        const cr = Math.round(((_e = fg.r) !== null && _e !== void 0 ? _e : 0) * alpha + ((_f = bg.r) !== null && _f !== void 0 ? _f : 255) * (1 - alpha));
+        const cg = Math.round(((_g = fg.g) !== null && _g !== void 0 ? _g : 0) * alpha + ((_h = bg.g) !== null && _h !== void 0 ? _h : 255) * (1 - alpha));
+        const cb = Math.round(((_j = fg.b) !== null && _j !== void 0 ? _j : 0) * alpha + ((_k = bg.b) !== null && _k !== void 0 ? _k : 255) * (1 - alpha));
+        effectiveBackground = rgbToHex({ r: cr, g: cg, b: cb });
+        minRatio = contrastRatio(textColor, effectiveBackground);
+    }
+    else {
+        // The worst-case stop (lowest ratio) drives both minRatio and wcagLevel.
+        let worstStop = background.stops[0];
+        let worstRatio = Infinity;
+        for (const stop of background.stops) {
+            const ratio = contrastRatio(textColor, stop);
+            if (ratio < worstRatio) {
+                worstRatio = ratio;
+                worstStop = stop;
+            }
+        }
+        effectiveBackground = worstStop;
+        minRatio = worstRatio;
+    }
+    const wLevel = wcagLevel(textColor, effectiveBackground);
+    return {
+        readable: minRatio >= minRequired,
+        minContrastRatio: +minRatio.toFixed(2),
+        wcagLevel: wLevel,
+    };
+}
+export function bestContrastPalette(background, palettes, options) {
+    let bestIdx = 0;
+    let bestScore = -1;
+    let bestMin = 0, bestAvg = 0;
+    palettes.forEach((palette, idx) => {
+        var _a;
+        const ratios = palette.map((c) => contrastRatio(background, c));
+        const weights = (_a = options === null || options === void 0 ? void 0 : options.weights) !== null && _a !== void 0 ? _a : ratios.map(() => 1);
+        const totalW = weights.reduce((s, w) => s + w, 0);
+        const avg = ratios.reduce((s, r, i) => { var _a; return s + r * ((_a = weights[i]) !== null && _a !== void 0 ? _a : 1); }, 0) / totalW;
+        const min = Math.min(...ratios);
+        // Score: weighted avg with heavy penalty on minimum
+        const score = avg * 0.4 + min * 0.6;
+        if (score > bestScore) {
+            bestScore = score;
+            bestIdx = idx;
+            bestMin = min;
+            bestAvg = avg;
+        }
+    });
+    return {
+        paletteIndex: bestIdx,
+        palette: palettes[bestIdx],
+        minContrastRatio: +bestMin.toFixed(2),
+        avgContrastRatio: +bestAvg.toFixed(2),
+    };
+}

package/dist/esm/cache.d.ts

@@ -0,0 +1,9 @@
+import { normalizeColor } from './parse.js';
+export declare function clearColorCache(): void;
+export declare function getCacheStats(): {
+    size: number;
+    hits: number;
+};
+export declare function enableCache(): void;
+export declare function disableCache(): void;
+export declare function normalizeColorCached(input: string): ReturnType<typeof normalizeColor>;

package/dist/esm/cache.js

@@ -0,0 +1,31 @@
+// Memoized normalizeColor() for performance-sensitive code.
+import { normalizeColor } from './parse.js';
+let _cacheEnabled = true;
+const _normalizeCache = new Map();
+let _cacheHits = 0;
+export function clearColorCache() {
+    _normalizeCache.clear();
+    _cacheHits = 0;
+}
+export function getCacheStats() {
+    return { size: _normalizeCache.size, hits: _cacheHits };
+}
+export function enableCache() {
+    _cacheEnabled = true;
+}
+export function disableCache() {
+    _cacheEnabled = false;
+}
+// Cached normalizer wrapper — use this in performance-sensitive contexts
+export function normalizeColorCached(input) {
+    if (!_cacheEnabled)
+        return normalizeColor(input);
+    const cached = _normalizeCache.get(input);
+    if (cached) {
+        _cacheHits++;
+        return cached;
+    }
+    const result = normalizeColor(input);
+    _normalizeCache.set(input, result);
+    return result;
+}

package/dist/esm/convert/format.d.ts

@@ -0,0 +1,3 @@
+export declare function toDisplayP3Hex(color: string): string;
+export declare function toOklchString(color: string, alpha?: number): string;
+export declare function toColorP3String(color: string, alpha?: number): string;

package/dist/esm/convert/format.js

@@ -0,0 +1,37 @@
+// Formatters that accept any supported CSS color string.
+import { normalizeColor } from '../parse.js';
+import { rgbToDisplayP3, rgbToHex, rgbToOklch } from './spaces.js';
+export function toDisplayP3Hex(color) {
+    const n = normalizeColorRaw(color);
+    const p3 = rgbToDisplayP3({ r: n.r, g: n.g, b: n.b });
+    return rgbToHex({
+        r: Math.round(Math.max(0, Math.min(255, p3.r * 255))),
+        g: Math.round(Math.max(0, Math.min(255, p3.g * 255))),
+        b: Math.round(Math.max(0, Math.min(255, p3.b * 255))),
+    });
+}
+// Internal raw normalizer (no cache, no circular dep issues)
+function normalizeColorRaw(color) {
+    var _a, _b, _c, _d;
+    const n = normalizeColor(color);
+    return { r: (_a = n.r) !== null && _a !== void 0 ? _a : 0, g: (_b = n.g) !== null && _b !== void 0 ? _b : 0, b: (_c = n.b) !== null && _c !== void 0 ? _c : 0, a: (_d = n.a) !== null && _d !== void 0 ? _d : 1 };
+}
+// ─── Formatting ───────────────────────────────────────────────────────────────
+export function toOklchString(color, alpha) {
+    var _a, _b, _c;
+    const n = normalizeColor(color);
+    const { L, C, H } = rgbToOklch({ r: (_a = n.r) !== null && _a !== void 0 ? _a : 0, g: (_b = n.g) !== null && _b !== void 0 ? _b : 0, b: (_c = n.b) !== null && _c !== void 0 ? _c : 0 });
+    const Lr = +L.toFixed(4), Cr = +C.toFixed(4), Hr = +H.toFixed(2);
+    if (alpha !== undefined)
+        return `oklch(${Lr} ${Cr} ${Hr} / ${+alpha.toFixed(3)})`;
+    return `oklch(${Lr} ${Cr} ${Hr})`;
+}
+export function toColorP3String(color, alpha) {
+    var _a, _b, _c;
+    const n = normalizeColor(color);
+    const p3 = rgbToDisplayP3({ r: (_a = n.r) !== null && _a !== void 0 ? _a : 0, g: (_b = n.g) !== null && _b !== void 0 ? _b : 0, b: (_c = n.b) !== null && _c !== void 0 ? _c : 0 });
+    const r = +p3.r.toFixed(4), g = +p3.g.toFixed(4), b = +p3.b.toFixed(4);
+    if (alpha !== undefined)
+        return `color(display-p3 ${r} ${g} ${b} / ${+alpha.toFixed(3)})`;
+    return `color(display-p3 ${r} ${g} ${b})`;
+}

package/dist/esm/convert/index.d.ts

@@ -0,0 +1,2 @@
+export * from './spaces.js';
+export * from './format.js';

package/dist/esm/convert/index.js

@@ -0,0 +1,2 @@
+export * from './spaces.js';
+export * from './format.js';

package/dist/esm/convert/spaces.d.ts

@@ -0,0 +1,189 @@
+export declare function rgbToDisplayP3(rgb: {
+    r: number;
+    g: number;
+    b: number;
+}): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function displayP3ToRgb(p3: {
+    r: number;
+    g: number;
+    b: number;
+}): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function shortHexToRgba(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+} | null;
+export declare function normalizeHex(hex: string): string;
+export declare function hexToRgb(hex: string): [number, number, number];
+export declare function hexToRgba(hex: string, opacity?: number): string;
+export declare function hexToHsl(hex: string): [number, number, number];
+export declare function hslToHex(h: number, s: number, l: number): string;
+export declare function rgbToHex({ r, g, b }: {
+    r: number;
+    g: number;
+    b: number;
+}): string;
+export declare function rgbaToHex({ r, g, b, a }: {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}): string;
+export declare function rgbToRgbaString({ r, g, b }: {
+    r: number;
+    g: number;
+    b: number;
+}, a: number): string;
+export declare function rgbaStringToRgba(str: string): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+} | null;
+export declare function rgbToHsl({ r, g, b, }: {
+    r: number;
+    g: number;
+    b: number;
+}): [number, number, number];
+export declare function hslToRgb(h: number, s: number, l: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function rgbToHsv({ r, g, b, }: {
+    r: number;
+    g: number;
+    b: number;
+}): [number, number, number];
+export declare function hsvToRgb(h: number, s: number, v: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function hexToHsv(hex: string): [number, number, number];
+export declare function hsvToHex(h: number, s: number, v: number): string;
+export declare function hex8ToRgba(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+} | null;
+export declare function rgbaToHex8({ r, g, b, a }: {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}): string;
+export declare function rgbToCmyk({ r, g, b }: {
+    r: number;
+    g: number;
+    b: number;
+}): {
+    c: number;
+    m: number;
+    y: number;
+    k: number;
+};
+export declare function cmykToRgb({ c, m, y, k }: {
+    c: number;
+    m: number;
+    y: number;
+    k: number;
+}): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function rgbToLab({ r, g, b }: {
+    r: number;
+    g: number;
+    b: number;
+}): {
+    L: number;
+    a: number;
+    b: number;
+};
+export declare function labToRgb({ L, a, b }: {
+    L: number;
+    a: number;
+    b: number;
+}): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function rgbToLch({ r, g, b }: {
+    r: number;
+    g: number;
+    b: number;
+}): {
+    L: number;
+    C: number;
+    H: number;
+};
+export declare function lchToRgb({ L, C, H }: {
+    L: number;
+    C: number;
+    H: number;
+}): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function rgbToHwb({ r, g, b, }: {
+    r: number;
+    g: number;
+    b: number;
+}): [number, number, number];
+export declare function hwbToRgb(H: number, W: number, B: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function toHwbString(H: number, W: number, B: number, alpha?: number): string;
+export declare function rgbToOklab({ r, g, b }: {
+    r: number;
+    g: number;
+    b: number;
+}): {
+    L: number;
+    a: number;
+    b: number;
+};
+export declare function oklabToRgb({ L, a, b }: {
+    L: number;
+    a: number;
+    b: number;
+}): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function rgbToOklch({ r, g, b }: {
+    r: number;
+    g: number;
+    b: number;
+}): {
+    L: number;
+    C: number;
+    H: number;
+};
+export declare function oklchToRgb({ L, C, H }: {
+    L: number;
+    C: number;
+    H: number;
+}): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function toHslString(h: number, s: number, l: number, alpha?: number): string;