saturon 0.2.3 → 0.3.0

package/dist/Color.js

@@ -1,7 +1,8 @@
-import { colorModels, colorTypes, colorSpaces } from "./converters.js";
-import { cache, clean, fit } from "./utils.js";
-import { EASINGS } from "./math.js";
+import { colorModels, colorSpaces } from "./converters.js";
+import { cache, fit, mixTwo, normalize } from "./utils.js";
+import { EPSILON } from "./math.js";
 import { config } from "./config.js";
+import { formatters, isValid, parseNode, tokenize, validateTokens } from "./engine.js";
 /**
  * The `Color` class represents a dynamic CSS color object, allowing for the manipulation
  * and retrieval of colors in various formats (e.g., RGB, HEX, HSL).
@@ -22,60 +23,27 @@ export class Color {
     }
     static from(color) {
         /* eslint-enable no-unused-vars, @typescript-eslint/no-explicit-any */
-        const c = clean(color);
-        for (const type in colorTypes) {
-            const t = type;
-            const { parse, bridge, toBridge, isValid } = colorTypes[t];
-            if (!isValid(c))
-                continue;
-            const parsed = parse(c);
-            const coords = t in colorModels ? parsed : toBridge(parsed);
-            const model = (t in colorModels ? t : bridge);
+        const tokens = tokenize(color);
+        const tree = validateTokens(tokens);
+        try {
+            const { model, coords } = parseNode(tree);
             return new Color(model, coords);
         }
-        throw new Error(`Unsupported or invalid color format: '${color}'.`);
+        catch (error) {
+            throw new Error(`Failed to parse color string '${color}'`, { cause: error });
+        }
     }
     /**
-     * Returns the detected color type, or `undefined` if unrecognized.
+     * Validates a color string.
      *
-     * @param color - Color string to analyze.
-     * @param strict - Whether to validate full round-trip conversion.
+     * @param color - Color string to check.
+     * @param options - Validation options.
+     * @returns `true` if valid, otherwise `false`.
      */
-    static type(color, strict = false) {
-        const c = clean(color);
-        for (const type in colorTypes) {
-            const t = type;
-            const { isValid, bridge, parse, toBridge } = colorTypes[t];
-            if (!isValid(c))
-                continue;
-            if (!strict)
-                return t;
-            try {
-                const parsed = parse(c);
-                const coords = t in colorModels ? parsed : toBridge(parsed);
-                const model = (type in colorModels ? type : bridge);
-                return typeof new Color(model, coords) === "object" ? t : undefined;
-            }
-            catch {
-                return undefined;
-            }
-        }
-        return undefined;
-    }
-    static isValid(color, type) {
+    static isValid(color, options = {}) {
+        const { rule } = options;
         try {
-            if (type) {
-                const t = type?.trim().toLowerCase();
-                const c = clean(color);
-                const { isValid, bridge, parse, toBridge } = colorTypes[t];
-                if (!isValid(c))
-                    return false;
-                const parsed = parse(c);
-                const coords = t in colorModels ? parsed : toBridge(parsed);
-                const model = (t in colorModels ? t : bridge);
-                return !!new Color(model, coords);
-            }
-            return !!Color.from(color);
+            return isValid(color, rule) && !!Color.from(color);
         }
         catch {
             return false;
@@ -93,7 +61,7 @@ export class Color {
         const models = Object.keys(colorModels);
         const model = options.model ?? models[Math.floor(Math.random() * models.length)];
         const { components } = colorModels[model];
-        const valid = new Set([...Object.keys(components), "alpha"]);
+        const valid = new Set(Object.keys(components));
         for (const section of ["limits", "bias", "base", "deviation"]) {
             const record = options[section];
             if (!record)
@@ -142,10 +110,67 @@ export class Color {
         }
         return new Color(model, coords);
     }
+    /**
+     * Statically mixes multiple colors together by specified percentages.
+     * Fully compliant with CSS Color Module Level 5 specification constraints.
+     *
+     * @param colors - Array of MixItems containing colors and optional percentages.
+     * @param options - Options containing the interpolation space and hue policy.
+     * @returns A new `Color` instance representing the mixed color.
+     */
+    static mix(colors, options) {
+        const { in: model = "oklab", hue = "shorter" } = options;
+        if (!colors || colors.length === 0) {
+            throw new Error("At least one color must be provided in the colors array.");
+        }
+        if (colors.length === 1)
+            return colors[0].color.in(model);
+        const weights = colors.map((c) => (c.percentage !== undefined ? c.percentage / 100 : undefined));
+        const definedSum = weights.reduce((sum, w) => sum + (w || 0), 0);
+        const missingCount = weights.filter((w) => w === undefined).length;
+        let alphaMult = 1;
+        if (weights.length > 0 && weights.every((w) => w === 0)) {
+            alphaMult = 0;
+            for (let i = 0; i < weights.length; i++)
+                weights[i] = 1 / weights.length;
+        }
+        else if (missingCount === 0 && definedSum < 1) {
+            alphaMult = definedSum;
+        }
+        if (alphaMult > 0) {
+            if (missingCount > 0) {
+                const remaining = Math.max(0, 1 - definedSum);
+                const share = remaining / missingCount;
+                for (let i = 0; i < weights.length; i++) {
+                    if (weights[i] === undefined)
+                        weights[i] = share;
+                }
+            }
+            else if (definedSum > 0 && definedSum !== 1) {
+                for (let i = 0; i < weights.length; i++) {
+                    weights[i] = weights[i] / definedSum;
+                }
+            }
+        }
+        let accColor = colors[0].color.in(model);
+        let accWeight = weights[0];
+        for (let i = 1; i < colors.length; i++) {
+            const currentWeight = weights[i];
+            accWeight += currentWeight;
+            const t = accWeight === 0 ? 0 : currentWeight / accWeight;
+            accColor = mixTwo(accColor, colors[i].color.in(model), t, model, hue);
+        }
+        if (alphaMult !== 1) {
+            const finalCoords = [...accColor.coords];
+            finalCoords[3] = (finalCoords[3] ?? 1) * alphaMult;
+            return new Color(model, finalCoords);
+        }
+        return accColor;
+    }
     to(type, options = {}) {
         const t = type.toLowerCase();
         const { legacy = false, fit = config.defaults.fit, precision, units = false } = options;
-        const conv = colorTypes[t];
+        const conv = formatters[t];
         if (!conv)
             throw new Error(`Unsupported color type: '${t}'.`);
         const { fromBridge, bridge, format } = conv;
@@ -223,7 +248,7 @@ export class Color {
      * @returns The formatted color string.
      */
     toString(options = {}) {
-        const { format } = colorTypes[this.model];
+        const { format } = formatters[this.model];
         const { legacy = false, fit = config.defaults.fit, precision, units = false } = options;
         return format?.(this.coords, { legacy, fit, precision, units });
     }
@@ -231,20 +256,17 @@ export class Color {
      * Returns the color as an object of component values.
      *
      * @param options - Optional retrieval options.
-     * @returns An object mapping each component (and alpha) to its numeric value.
+     * @returns An object mapping each component to its numeric value.
      * @throws If the model has no defined components.
      */
+    // eslint-disable-next-line no-unused-vars
     toObject(options = {}) {
         const coords = this.toArray(options);
         const { components } = colorModels[this.model];
         if (!components)
             throw new Error(`Model ${this.model} does not have defined components.`);
-        const fullComponents = {
-            ...components,
-            alpha: { index: 3, value: [0, 1], precision: 3 },
-        };
         const result = {}; // eslint-disable-line no-unused-vars
-        for (const [name, { index }] of Object.entries(fullComponents))
+        for (const [name, { index }] of Object.entries(components))
             result[name] = coords[index];
         return result;
     }
@@ -252,7 +274,7 @@ export class Color {
      * Returns the color as an array of component values, optionally normalized and fitted.
      *
      * @param options - Conversion configuration.
-     * @returns An array of normalized color components and alpha.
+     * @returns An array of normalized color components.
      * @throws If the model has no defined components.
      */
     toArray(options = {}) {
@@ -261,22 +283,7 @@ export class Color {
         const { components } = colorModels[model];
         if (!components)
             throw new Error(`Model ${model} does not have defined components.`);
-        const defs = {
-            ...components,
-            alpha: { index: 3, value: [0, 1], precision: 3 },
-        };
-        const normalize = (c, i) => {
-            const v = Object.values(defs)[i]?.value;
-            const [min, max] = Array.isArray(v) ? v : v === "hue" ? [0, 360] : [0, 100];
-            if (Number.isNaN(c))
-                return 0;
-            if (c === Infinity)
-                return max;
-            if (c === -Infinity)
-                return min;
-            return typeof c === "number" ? c : 0;
-        };
-        const norm = coords.slice(0, 3).map(normalize);
+        const norm = coords.slice(0, 3).map((c, i) => normalize(c, Object.values(components)[i].value));
         const fitted = fit(norm, model, {
             method: method,
             precision,
@@ -328,36 +335,21 @@ export class Color {
      *   - A partial object mapping component names to numbers or update functions
      *   - A function that receives current components and returns partial updates or an array of values
      *   - An array of new values corresponding to component indices
-     * @param normalize - Whether to normalize component values to their valid ranges. Defaults to `true`.
+     * @param normalized - Whether to normalize component values to their valid ranges. Defaults to `true`.
      *   When `false`, values are not clamped or validated against their ranges.
      * @returns A new Color instance with the updated component values
      */
     /* eslint-disable no-unused-vars */
-    with(values, normalize = true) {
-        const normRange = (defValue) => Array.isArray(defValue) ? defValue : defValue === "hue" ? [0, 360] : [0, 100];
-        const normalizeComponent = (c, defValue) => {
-            if (normalize === false)
-                return c;
-            const [min, max] = normRange(defValue);
-            if (Number.isNaN(c))
-                return 0;
-            if (c === Infinity)
-                return max;
-            if (c === -Infinity)
-                return min;
-            return c;
-        };
+    with(values) {
         const { model } = this;
         const coords = this.coords.slice();
-        const defs = {
-            ...colorModels[model].components, // eslint-disable-line @typescript-eslint/no-explicit-any
-            alpha: { index: 3, value: [0, 1], precision: 3 },
-        };
-        const names = Object.keys(defs);
+        const { components } = colorModels[model];
+        const names = Object.keys(components);
+        const componentDefs = Object.values(components);
         const newValues = typeof values === "function"
             ? values(Object.fromEntries(names.map((k) => {
-                const def = defs[k];
-                return [k, normalizeComponent(coords[def.index], def.value)];
+                const def = components[k];
+                return [k, normalize(coords[def.index], def.value)];
             })))
             : values;
         if (Array.isArray(newValues)) {
@@ -365,8 +357,8 @@ export class Color {
                 const incoming = newValues[i];
                 if (typeof incoming !== "number")
                     return curr;
-                const def = Object.values(defs).find((d) => d.index === i);
-                return normalizeComponent(incoming, def.value);
+                const def = componentDefs.find((d) => d.index === i);
+                return normalize(incoming, def.value);
             });
             return new Color(model, [...adjusted.slice(0, 3), coords[3] ?? 1]);
         }
@@ -374,114 +366,28 @@ export class Color {
         for (const name of names) {
             if (!(name in newValues))
                 continue;
-            const { index, value } = defs[name];
+            const { index, value } = components[name];
             const raw = newValues[name];
-            const prev = normalizeComponent(coords[index], value);
+            const prev = normalize(coords[index], value);
             const val = typeof raw === "function"
-                ? normalizeComponent(raw(prev), value)
+                ? normalize(raw(prev), value)
                 : typeof raw === "number"
-                    ? normalizeComponent(raw, value)
+                    ? normalize(raw, value)
                     : coords[index];
             next[index] = val;
         }
         return new Color(model, [...next.slice(0, 3), next[3] ?? coords[3]]);
     }
     /**
-     * Mixes this color with another by a specified amount.
+     * Creates a new Color instance with values fitted to the color model's gamut.
      *
-     * @param other - The color to mix with. Can be a string or a `Color` instance.
-     * @param options - Options for how the colors are mixed.
-     * @returns A new `Color` instance representing the mixed color.
-     * @throws If the color model does not have defined components.
+     * @param options - Configuration options for fitting
+     * @returns A new Color instance with fitted values
      */
-    mix(other, options = {}) {
-        const { model } = this;
-        const A = this.coords.slice();
-        const B = (typeof other === "string" ? Color.from(other) : other).in(model).coords.slice();
-        const { components } = colorModels[model]; // eslint-disable-line @typescript-eslint/no-explicit-any
-        if (!components)
-            throw new Error(`Model ${model} does not have defined components.`);
-        const defs = {
-            ...components,
-            alpha: { index: 3, value: [0, 1], precision: 3 },
-        };
-        const normRange = (v) => Array.isArray(v) ? v : v === "hue" ? [0, 360] : [0, 100];
-        const repairPair = (a, b, v) => {
-            const [min, max] = normRange(v);
-            const fixInf = (x) => (x === Infinity ? max : x === -Infinity ? min : x);
-            a = fixInf(a);
-            b = fixInf(b);
-            const aNaN = Number.isNaN(a);
-            const bNaN = Number.isNaN(b);
-            if (aNaN && bNaN)
-                return { a: 0, b: 0 };
-            if (aNaN)
-                return { a: b, b };
-            if (bNaN)
-                return { a, b: a };
-            return { a, b, ok: true };
-        };
-        const hueIndex = defs.h?.index ?? -1;
-        for (const key in defs) {
-            const { index, value } = defs[key];
-            if (index > 3)
-                continue;
-            const r = repairPair(A[index], B[index], value);
-            if (r.ok) {
-                const [min, max] = normRange(value);
-                const fixInf = (x) => (x === Infinity ? max : x === -Infinity ? min : x);
-                A[index] = fixInf(A[index]);
-                B[index] = fixInf(B[index]);
-            }
-            else {
-                A[index] = r.a;
-                B[index] = r.b;
-            }
-        }
-        const { hue = "shorter", amount = 0.5, easing = "linear", gamma = 1.0 } = options;
-        const ease = typeof easing === "function" ? easing : EASINGS[easing];
-        const t = ease(Math.min(1, Math.max(0, amount)));
-        const tt = Math.pow(t, 1 / gamma);
-        const wrap = (v) => ((v % 360) + 360) % 360;
-        const hueDelta = (a, b) => {
-            const d = wrap(b - a);
-            return d > 180 ? d - 360 : d;
-        };
-        const hueDeltaLong = (a, b) => hueDelta(a, b) >= 0 ? hueDelta(a, b) - 360 : hueDelta(a, b) + 360;
-        const interpHue = (a, b, t, method) => {
-            switch (method) {
-                case "shorter":
-                    return wrap(a + t * hueDelta(a, b));
-                case "longer":
-                    return wrap(a + t * hueDeltaLong(a, b));
-                case "increasing":
-                    return wrap(a * (1 - t) + (b < a ? b + 360 : b) * t);
-                case "decreasing":
-                    return wrap(a * (1 - t) + (b > a ? b - 360 : b) * t);
-            }
-            throw new Error(`Invalid hue interpolation: ${method}`);
-        };
-        if (tt === 0)
-            return new Color(model, [...A]);
-        if (tt === 1)
-            return new Color(model, [...B]);
-        const aA = A[3];
-        const aB = B[3];
-        const resolvedA = A.slice(0, 3);
-        const resolvedB = B.slice(0, 3);
-        if (aA < 1 || aB < 1) {
-            const premixed = resolvedA.map((a, i) => {
-                const b = resolvedB[i];
-                return i === hueIndex ? interpHue(a, b, tt, hue) : a * aA * (1 - tt) + b * aB * tt;
-            });
-            const a = aA * (1 - tt) + aB * tt;
-            const out = a > 0
-                ? premixed.map((v, i) => (i === hueIndex ? v : v / a))
-                : resolvedA.map((_, i) => (i === hueIndex ? premixed[i] : 0));
-            return new Color(model, [...out, a]);
-        }
-        const mixed = resolvedA.map((a, i) => i === hueIndex ? interpHue(a, resolvedB[i], tt, hue) : a + (resolvedB[i] - a) * tt);
-        return new Color(model, [...mixed, 1]);
+    fit(options = {}) {
+        const { fit: method = config.defaults.fit, precision } = options;
+        const fitted = this.toArray({ fit: method, precision });
+        return new Color(this.model, fitted);
     }
     /**
      * Fits this color within the specified gamut using a given method.
@@ -498,21 +404,10 @@ export class Color {
         const fitted = this.in(g).toArray({ fit: method, precision: null });
         return new Color(g, fitted).in(this.model);
     }
-    /**
-     * Creates a new Color instance with values fitted to the color model's gamut.
-     *
-     * @param options - Configuration options for fitting
-     * @returns A new Color instance with fitted values
-     */
-    fit(options = {}) {
-        const { fit: method = config.defaults.fit, precision } = options;
-        const fitted = this.toArray({ fit: method, precision });
-        return new Color(this.model, fitted);
-    }
     /**
      * Calculates the WCAG 2.1 contrast ratio between this color and another.
      *
-     * @param other - The comparison color (instance or string).
+     * @param other - The comparison Color instance.
      * @returns Contrast ratio from 1 to 21.
      *
      * @remarks
@@ -520,15 +415,14 @@ export class Color {
      * - For perceptual accuracy, consider using APCA instead.
      */
     contrast(other) {
-        const o = typeof other === "string" ? Color.from(other) : other;
         const [, L1] = this.in("xyz-d65").toArray({ fit: "none", precision: null });
-        const [, L2] = o.in("xyz-d65").toArray({ fit: "none", precision: null });
+        const [, L2] = other.in("xyz-d65").toArray({ fit: "none", precision: null });
         return (Math.max(L1, L2) + 0.05) / (Math.min(L1, L2) + 0.05);
     }
     /**
      * Calculates the color difference (ΔEOK) between the current color and another color using the OKLAB color space.
      *
-     * @param other - The other color to compare against (as a Color instance or string).
+     * @param other - The other Color instance to compare against.
      * @returns A number in range (0-1) (smaller indicates more similar colors).
      *
      * @remarks
@@ -539,7 +433,7 @@ export class Color {
     deltaEOK(other) {
         const coordsOptions = { fit: "none", precision: null };
         const [L1, a1, b1] = this.in("oklab").toArray(coordsOptions);
-        const [L2, a2, b2] = (typeof other === "string" ? Color.from(other) : other).in("oklab").toArray(coordsOptions);
+        const [L2, a2, b2] = other.in("oklab").toArray(coordsOptions);
         const ΔL = L1 - L2;
         const ΔA = a1 - a2;
         const ΔB = b1 - b2;
@@ -550,13 +444,13 @@ export class Color {
      * Calculates the color difference (ΔE) between two colors using the CIE76 formula.
      * This is a simple Euclidean distance in LAB color space.
      *
-     * @param other - The other color to compare against (as a Color instance or string).
+     * @param other - The other Color instance to compare against.
      * @returns A number in range (0-1) (smaller indicates more similar colors).
      */
     deltaE76(other) {
         const coordsOptions = { fit: "none", precision: null };
         const [L1, a1, b1] = this.in("lab").toArray(coordsOptions);
-        const [L2, a2, b2] = (typeof other === "string" ? Color.from(other) : other).in("lab").toArray(coordsOptions);
+        const [L2, a2, b2] = other.in("lab").toArray(coordsOptions);
         const ΔL = L1 - L2;
         const ΔA = a1 - a2;
         const ΔB = b1 - b2;
@@ -566,13 +460,13 @@ export class Color {
      * Calculates the color difference (ΔE) between two colors using the CIE94 formula.
      * This method improves perceptual accuracy over CIE76 by applying weighting factors.
      *
-     * @param other - The other color to compare against (as a Color instance or string).
+     * @param other - The other Color instance to compare against.
      * @returns A number in range (0-1) (smaller indicates more similar colors).
      */
     deltaE94(other) {
         const coordsOptions = { fit: "none", precision: null };
         const [L1, a1, b1] = this.in("lab").toArray(coordsOptions);
-        const [L2, a2, b2] = (typeof other === "string" ? Color.from(other) : other).in("lab").toArray(coordsOptions);
+        const [L2, a2, b2] = other.in("lab").toArray(coordsOptions);
         const ΔL = L1 - L2;
         const ΔA = a1 - a2;
         const ΔB = b1 - b2;
@@ -590,13 +484,13 @@ export class Color {
      * Calculates the color difference (ΔE) between two colors using the CIEDE2000 formula.
      * This is the most perceptually accurate method, accounting for interactions between hue, chroma, and lightness.
      *
-     * @param other - The other color to compare against (as a Color instance or string).
+     * @param other - The other Color instance to compare against.
      * @returns A number in range (0-1) (smaller indicates more similar colors).
      */
     deltaE2000(other) {
         const coordsOptions = { fit: "none", precision: null };
         const [L1, a1, b1] = this.in("lab").toArray(coordsOptions);
-        const [L2, a2, b2] = (typeof other === "string" ? Color.from(other) : other).in("lab").toArray(coordsOptions);
+        const [L2, a2, b2] = other.in("lab").toArray(coordsOptions);
         const π = Math.PI, d2r = π / 180, r2d = 180 / π;
         const C1 = Math.sqrt(a1 ** 2 + b1 ** 2);
         const C2 = Math.sqrt(a2 ** 2 + b2 ** 2);
@@ -634,7 +528,7 @@ export class Color {
         const Cdash = (Cdash1 + Cdash2) / 2;
         const Cdash7 = Math.pow(Cdash, 7);
         const hsum = h1 + h2;
-        let hdash = 0;
+        let hdash;
         if (Cdash1 === 0 && Cdash2 === 0) {
             hdash = hsum;
         }
@@ -668,8 +562,8 @@ export class Color {
     /**
      * Checks numeric equality with another color within a tolerance.
      *
-     * @param other - Color or string to compare.
-     * @param epsilon - Allowed floating-point difference (default: 1e-5).
+     * @param other - Color instnace to compare.
+     * @param epsilon - Allowed floating-point difference (defaults to the value of `EPSILON` in `"saturon/math"`).
      * @returns `true` if equal within tolerance.
      *
      * @remarks
@@ -683,24 +577,23 @@ export class Color {
      *   - {@link deltaE94} (weighted improvements over LAB)
      *   - {@link deltaE2000} (most accurate, accounts for perceptual interactions)
      */
-    equals(other, epsilon = 1e-5) {
-        const o = typeof other === "string" ? Color.from(other) : other;
+    equals(other, epsilon = EPSILON) {
         const thisCoords = this.toArray({ fit: "none", precision: null });
-        const otherCoords = o.toArray({ fit: "none", precision: null });
-        if (o.model === this.model)
+        const otherCoords = other.toArray({ fit: "none", precision: null });
+        if (other.model === this.model)
             return thisCoords.every((v, i) => Math.abs(v - otherCoords[i]) <= epsilon);
         const a = this.in("xyz-d65").toArray({ fit: "none", precision: null });
-        const b = o.in("xyz-d65").toArray({ fit: "none", precision: null });
+        const b = other.in("xyz-d65").toArray({ fit: "none", precision: null });
         return a.every((v, i) => Math.abs(v - b[i]) <= epsilon);
     }
     /**
      * Determines whether this color lies within a given gamut.
      *
      * @param gamut - Target color space.
-     * @param epsilon - Floating-point tolerance (default: 1e-5).
+     * @param epsilon - Floating-point tolerance (defaults to the value of `EPSILON` in `"saturon/math"`).
      * @returns `true` if inside gamut, else `false`.
      */
-    inGamut(gamut, epsilon = 1e-5) {
+    inGamut(gamut, epsilon = EPSILON) {
         const g = gamut.trim().toLowerCase();
         if (!(g in colorSpaces))
             throw new Error(`Unsupported color gamut: '${g}'.`);