saturon 0.2.2 → 0.2.3

package/dist/Color.d.ts

@@ -1,4 +1,4 @@
-import type { Component, MixOptions, ColorType, OutputType, FormattingOptions, NamedColor, ColorSpace, FitMethod, ColorModel, RandomOptions, GetOptions } from "./types.js";
+import type { Component, MixOptions, ColorType, OutputType, FormattingOptions, NamedColor, ColorSpace, FitMethod, ColorModel, RandomOptions, ComponentOptions } from "./types.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).
@@ -82,7 +82,7 @@ export declare class Color<M extends ColorModel = ColorModel> {
      * @returns An object mapping each component (and alpha) to its numeric value.
      * @throws If the model has no defined components.
      */
-    toObject(options?: GetOptions): { [key in Component<M>]: number; };
+    toObject(options?: ComponentOptions): { [key in Component<M>]: number; };
     /**
      * Returns the color as an array of component values, optionally normalized and fitted.
      *
@@ -90,9 +90,9 @@ export declare class Color<M extends ColorModel = ColorModel> {
      * @returns An array of normalized color components and alpha.
      * @throws If the model has no defined components.
      */
-    toArray(options?: GetOptions): number[];
+    toArray(options?: ComponentOptions): number[];
     /**
-     * Returns a new `Color` instance with updated or replaced component values.
+     * Creates a new Color instance with modified component values.
      *
      * This method supports several flexible update styles:
      *
@@ -131,12 +131,14 @@ export declare class Color<M extends ColorModel = ColorModel> {
      * color.with(({ r, g, b }) => [r * 0.5, g * 0.5, b * 0.5, 1]);
      * ```
      *
-     * @param values - Either:
-     * - a partial object of component values,
-     * - an updater function returning an object or array,
-     * - or an array of new coordinates.
-     * @returns A new `Color` instance with updated values.
-     * @throws If the color model has no defined components.
+     * @template M - The color model type
+     * @param values - The new component values to apply. Can be:
+     *   - 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`.
+     *   When `false`, values are not clamped or validated against their ranges.
+     * @returns A new Color instance with the updated component values
      */
     with(values: Partial<{
         [K in Component<M> | "alpha"]: number | ((prev: number) => number);
@@ -144,7 +146,7 @@ export declare class Color<M extends ColorModel = ColorModel> {
         [K in Component<M> | "alpha"]: number;
     }) => Partial<{
         [K in Component<M> | "alpha"]: number;
-    }> | (number | undefined)[]) | (number | undefined)[]): Color<M>;
+    }> | (number | undefined)[]) | (number | undefined)[], normalize?: boolean): Color<M>;
     /**
      * Mixes this color with another by a specified amount.
      *
@@ -163,6 +165,13 @@ export declare class Color<M extends ColorModel = ColorModel> {
      * @throws If the gamut is unsupported.
      */
     within(gamut: ColorSpace, method?: FitMethod): Color<M>;
+    /**
+     * 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?: ComponentOptions): Color<M>;
     /**
      * Calculates the WCAG 2.1 contrast ratio between this color and another.
      *

package/dist/Color.js

@@ -115,7 +115,7 @@ export class Color {
                 value = base + Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v) * dev;
             }
             else {
-                let [min, max] = comp.value === "angle" ? [0, 360] : comp.value === "percentage" ? [0, 100] : comp.value;
+                let [min, max] = comp.value === "hue" ? [0, 360] : comp.value === "percentage" ? [0, 100] : comp.value;
                 const limits = options.limits?.[name];
                 if (limits) {
                     const [lMin, lMax] = limits;
@@ -128,7 +128,7 @@ export class Color {
                     r = biasFn(r);
                 value = min + r * (max - min);
             }
-            if (comp.value === "angle")
+            if (comp.value === "hue")
                 value = ((value % 360) + 360) % 360;
             else if (comp.value === "percentage")
                 value = Math.min(100, Math.max(0, value));
@@ -179,7 +179,6 @@ export class Color {
             cache.set("paths", paths);
         }
         const key = `${from}-${to}`;
-        const coords = this.coords.slice(0, 3);
         if (!paths.has(key)) {
             const queue = [from], parent = { [from]: null };
             for (let i = 0; i < queue.length; i++) {
@@ -202,7 +201,7 @@ export class Color {
             }
             paths.set(key, path);
         }
-        let value = [...coords];
+        let value = [...this.coords.map((v) => (isNaN(v) ? 0 : v))];
         const path = paths.get(key);
         for (let i = 0; i < path.length - 1; i++) {
             const a = path[i], b = path[i + 1];
@@ -268,7 +267,7 @@ export class Color {
         };
         const normalize = (c, i) => {
             const v = Object.values(defs)[i]?.value;
-            const [min, max] = Array.isArray(v) ? v : v === "angle" ? [0, 360] : [0, 100];
+            const [min, max] = Array.isArray(v) ? v : v === "hue" ? [0, 360] : [0, 100];
             if (Number.isNaN(c))
                 return 0;
             if (c === Infinity)
@@ -282,10 +281,10 @@ export class Color {
             method: method,
             precision,
         });
-        return [...fitted.slice(0, 3), coords[3]];
+        return [...fitted, coords[3]];
     }
     /**
-     * Returns a new `Color` instance with updated or replaced component values.
+     * Creates a new Color instance with modified component values.
      *
      * This method supports several flexible update styles:
      *
@@ -324,68 +323,65 @@ export class Color {
      * color.with(({ r, g, b }) => [r * 0.5, g * 0.5, b * 0.5, 1]);
      * ```
      *
-     * @param values - Either:
-     * - a partial object of component values,
-     * - an updater function returning an object or array,
-     * - or an array of new coordinates.
-     * @returns A new `Color` instance with updated values.
-     * @throws If the color model has no defined components.
+     * @template M - The color model type
+     * @param values - The new component values to apply. Can be:
+     *   - 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`.
+     *   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) {
-        /* eslint-enable 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;
+        };
         const { model } = this;
-        const coords = this.toArray({ fit: "none", precision: null });
-        const { components } = colorModels[model];
-        if (!components)
-            throw new Error(`Model ${model} does not have defined components.`);
+        const coords = this.coords.slice();
         const defs = {
-            ...components,
+            ...colorModels[model].components, // eslint-disable-line @typescript-eslint/no-explicit-any
             alpha: { index: 3, value: [0, 1], precision: 3 },
         };
         const names = Object.keys(defs);
-        let newValues;
-        if (typeof values === "function") {
-            const result = values(Object.fromEntries(names.map((c) => [c, coords[defs[c].index]])));
-            newValues = result;
-        }
-        else {
-            newValues = values;
-        }
+        const newValues = typeof values === "function"
+            ? values(Object.fromEntries(names.map((k) => {
+                const def = defs[k];
+                return [k, normalizeComponent(coords[def.index], def.value)];
+            })))
+            : values;
         if (Array.isArray(newValues)) {
             const adjusted = coords.map((curr, i) => {
                 const incoming = newValues[i];
-                const { value } = Object.values(defs).find((d) => d.index === i);
                 if (typeof incoming !== "number")
                     return curr;
-                const [min, max] = Array.isArray(value) ? value : value === "angle" ? [0, 360] : [0, 100];
-                if (Number.isNaN(incoming))
-                    return 0;
-                if (incoming === Infinity)
-                    return max;
-                if (incoming === -Infinity)
-                    return min;
-                return incoming;
+                const def = Object.values(defs).find((d) => d.index === i);
+                return normalizeComponent(incoming, def.value);
             });
-            return new Color(model, [...adjusted.slice(0, 3), coords[3]]);
+            return new Color(model, [...adjusted.slice(0, 3), coords[3] ?? 1]);
         }
         const next = [...coords];
         for (const name of names) {
             if (!(name in newValues))
                 continue;
             const { index, value } = defs[name];
-            const current = coords[index];
             const raw = newValues[name];
-            let val = typeof raw === "function" ? raw(current) : raw;
-            if (typeof val === "number") {
-                const [min, max] = Array.isArray(value) ? value : value === "angle" ? [0, 360] : [0, 100];
-                if (Number.isNaN(val))
-                    val = 0;
-                else if (val === Infinity)
-                    val = max;
-                else if (val === -Infinity)
-                    val = min;
-            }
+            const prev = normalizeComponent(coords[index], value);
+            const val = typeof raw === "function"
+                ? normalizeComponent(raw(prev), value)
+                : typeof raw === "number"
+                    ? normalizeComponent(raw, value)
+                    : coords[index];
             next[index] = val;
         }
         return new Color(model, [...next.slice(0, 3), next[3] ?? coords[3]]);
@@ -400,71 +396,92 @@ export class Color {
      */
     mix(other, options = {}) {
         const { model } = this;
-        const coords = this.toArray({ fit: "none", precision: null });
-        const { components } = colorModels[model];
+        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 { hue = "shorter", amount = 0.5, easing = "linear", gamma = 1.0 } = options;
         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 = (((b - a) % 360) + 360) % 360;
+            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 interpolateHue = (a, b, t, method) => {
-            const wrapped = (v) => ((v % 360) + 360) % 360;
+        const interpHue = (a, b, t, method) => {
             switch (method) {
                 case "shorter":
-                    return wrapped(a + t * hueDelta(a, b));
+                    return wrap(a + t * hueDelta(a, b));
                 case "longer":
-                    return wrapped(a + t * hueDeltaLong(a, b));
+                    return wrap(a + t * hueDeltaLong(a, b));
                 case "increasing":
-                    return wrapped(a * (1 - t) + (b < a ? b + 360 : b) * t);
+                    return wrap(a * (1 - t) + (b < a ? b + 360 : b) * t);
                 case "decreasing":
-                    return wrapped(a * (1 - t) + (b > a ? b - 360 : b) * t);
-                default:
-                    throw new Error(`Invalid hue interpolation method: ${method}`);
+                    return wrap(a * (1 - t) + (b > a ? b - 360 : b) * t);
             }
+            throw new Error(`Invalid hue interpolation: ${method}`);
         };
-        const t = Math.max(0, Math.min(1, amount));
-        const ease = typeof easing === "function" ? easing : EASINGS[easing];
-        const tt = Math.pow(ease(t), 1 / gamma);
-        const otherColor = (typeof other === "string" ? Color.from(other) : other);
-        const thisCoords = coords.slice(0, 3);
-        const otherCoords = otherColor.in(model).toArray({ fit: "none", precision: null }).slice(0, 3);
-        const thisAlpha = coords[3];
-        const otherAlpha = otherColor.coords[3];
-        const hueIndex = Object.entries(defs).find(([k]) => k === "h")?.[1].index;
-        if (t === 0)
-            return new Color(model, [...thisCoords, thisAlpha]);
-        if (t === 1)
-            return new Color(model, [...otherCoords, otherAlpha]);
-        if (thisAlpha < 1 || otherAlpha < 1) {
-            const premixed = thisCoords.map((start, i) => {
-                const end = otherCoords[i];
-                if (i === hueIndex)
-                    return interpolateHue(start, end, tt, hue);
-                const a = start * thisAlpha;
-                const b = end * otherAlpha;
-                return a * (1 - tt) + b * tt;
+        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 mixedAlpha = thisAlpha * (1 - tt) + otherAlpha * tt;
-            const mixed = mixedAlpha > 0
-                ? premixed.map((c, i) => (i === hueIndex ? c : c / mixedAlpha))
-                : thisCoords.map((_, i) => (i === hueIndex ? premixed[i] : 0));
-            return new Color(model, [...mixed, mixedAlpha]);
+            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 mixedCoords = thisCoords.map((start, i) => {
-            const entry = Object.values(defs).find((d) => d.index === i);
-            if (!entry)
-                return start;
-            const end = otherCoords[i];
-            return entry.value === "angle" ? interpolateHue(start, end, tt, hue) : start + (end - start) * tt;
-        });
-        return new Color(model, [...mixedCoords, 1]);
+        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]);
     }
     /**
      * Fits this color within the specified gamut using a given method.
@@ -481,6 +498,17 @@ 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.
      *
@@ -657,8 +685,10 @@ export class Color {
      */
     equals(other, epsilon = 1e-5) {
         const o = typeof other === "string" ? Color.from(other) : other;
+        const thisCoords = this.toArray({ fit: "none", precision: null });
+        const otherCoords = o.toArray({ fit: "none", precision: null });
         if (o.model === this.model)
-            return this.coords.every((v, i) => Math.abs(v - o.coords[i]) <= epsilon);
+            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 });
         return a.every((v, i) => Math.abs(v - b[i]) <= epsilon);
@@ -680,7 +710,7 @@ export class Color {
         const coords = this.in(g).toArray({ fit: "none", precision: null });
         return Object.values(components).every(({ index, value }) => {
             const v = coords[index];
-            const [min, max] = Array.isArray(value) ? value : value === "angle" ? [0, 360] : [0, 100];
+            const [min, max] = Array.isArray(value) ? value : value === "hue" ? [0, 360] : [0, 100];
             return v >= min - epsilon && v <= max + epsilon;
         });
     }

package/dist/converters.d.ts

@@ -342,7 +342,7 @@ export declare const colorModels: {
         readonly components: {
             readonly h: {
                 readonly index: 0;
-                readonly value: "angle";
+                readonly value: "hue";
                 readonly precision: 0;
             };
             readonly s: {
@@ -364,7 +364,7 @@ export declare const colorModels: {
         readonly components: {
             readonly h: {
                 readonly index: 0;
-                readonly value: "angle";
+                readonly value: "hue";
                 readonly precision: 0;
             };
             readonly w: {
@@ -420,7 +420,7 @@ export declare const colorModels: {
             };
             readonly h: {
                 readonly index: 2;
-                readonly value: "angle";
+                readonly value: "hue";
                 readonly precision: 5;
             };
         };
@@ -466,7 +466,7 @@ export declare const colorModels: {
             };
             readonly h: {
                 readonly index: 2;
-                readonly value: "angle";
+                readonly value: "hue";
                 readonly precision: 5;
             };
         };

package/dist/converters.js

@@ -331,7 +331,7 @@ export const colorModels = {
         supportsLegacy: true,
         alphaVariant: "hsla",
         components: {
-            h: { index: 0, value: "angle", precision: 0 },
+            h: { index: 0, value: "hue", precision: 0 },
             s: { index: 1, value: "percentage", precision: 0 },
             l: { index: 2, value: "percentage", precision: 0 },
         },
@@ -341,7 +341,7 @@ export const colorModels = {
     },
     hwb: {
         components: {
-            h: { index: 0, value: "angle", precision: 0 },
+            h: { index: 0, value: "hue", precision: 0 },
             w: { index: 1, value: "percentage", precision: 0 },
             b: { index: 2, value: "percentage", precision: 0 },
         },
@@ -365,7 +365,7 @@ export const colorModels = {
         components: {
             l: { index: 0, value: "percentage", precision: 5 },
             c: { index: 1, value: [0, 150], precision: 5 },
-            h: { index: 2, value: "angle", precision: 5 },
+            h: { index: 2, value: "hue", precision: 5 },
         },
         bridge: "lab",
         toBridge: LCH_to_LAB,
@@ -387,7 +387,7 @@ export const colorModels = {
         components: {
             l: { index: 0, value: [0, 1], precision: 5 },
             c: { index: 1, value: [0, 0.4], precision: 5 },
-            h: { index: 2, value: "angle", precision: 5 },
+            h: { index: 2, value: "hue", precision: 5 },
         },
         bridge: "oklab",
         toBridge: OKLCH_to_OKLAB,
@@ -418,14 +418,9 @@ export const colorBases = {
             const HEX = str.slice(1);
             if (![3, 4, 6, 8].includes(HEX.length))
                 throw new Error("Invalid hex color length.");
-            for (const ch of HEX) {
-                const code = ch.charCodeAt(0);
-                const isDigit = code >= 48 && code <= 57;
-                const isLower = code >= 97 && code <= 102;
-                const isUpper = code >= 65 && code <= 70;
-                if (!(isDigit || isLower || isUpper))
+            for (const ch of HEX)
+                if (!/^[0-9a-fA-F]$/.test(ch))
                     throw new Error("Invalid hex color character.");
-            }
             const expand = (c) => parseInt(c.length === 1 ? c + c : c, 16);
             const [r, g, b, a = 255] = HEX.length <= 4
                 ? HEX.split("").map(expand)
@@ -595,7 +590,7 @@ export const colorBases = {
                 if (!comps) {
                     throw new Error(`Unknown color model: ${model}.`);
                 }
-                const hasHue = Object.values(comps).some((c) => c.value === "angle");
+                const hasHue = Object.values(comps).some((c) => c.value === "hue");
                 if (!hasHue) {
                     throw new Error(`Hue interpolation not supported in ${model} space.`);
                 }
@@ -607,18 +602,17 @@ export const colorBases = {
             const { color: color2, weight: weight2 } = extractColorAndWeight(parts[2]);
             const { amount, alphaMultiplier = 1 } = getWeight2Prime(weight1, weight2);
             return color1
-                .with({ alpha: (a) => a * alphaMultiplier })
+                .with({ alpha: (a) => (isNaN(a) ? a : a * alphaMultiplier) }, false)
                 .in(model)
-                .mix(color2.with({ alpha: (a) => a * alphaMultiplier }), { amount, hue })
-                .in("rgb")
-                .toArray({ fit: "none", precision: null });
+                .mix(color2.with({ alpha: (a) => (isNaN(a) ? a : a * alphaMultiplier) }, false), { amount, hue })
+                .in("rgb").coords;
         },
     },
     transparent: {
         isValid: (str) => str === "transparent",
         bridge: "rgb",
         toBridge: (coords) => coords,
-        parse: (str) => [0, 0, 0, 0], // eslint-disable-line no-unused-vars
+        parse: (str) => [NaN, NaN, NaN, 0], // eslint-disable-line no-unused-vars
     },
 };
 /**
@@ -651,7 +645,7 @@ export const colorTypes = {
         toBridge: (coords) => coords,
         parse: (str) => {
             const inner = str.slice(15, -1);
-            const [, luminance] = Color.from(inner).in("xyz-d65").toArray({ fit: "none", precision: null });
+            const [, luminance] = Color.from(inner).in("xyz-d65").coords;
             return luminance > 0.5 ? [0, 0, 0, 1] : [255, 255, 255, 1];
         },
     },
@@ -745,7 +739,7 @@ export const colorTypes = {
             if (idx < tokens.length && tokens[idx] === ",") {
                 idx++;
                 const fallbackStr = tokens.slice(idx).join(" ");
-                return Color.from(fallbackStr).in("rgb").toArray({ fit: "none", precision: null });
+                return Color.from(fallbackStr).in("rgb").coords;
             }
             const red = 1 - Math.min(1, c * (1 - k) + k);
             const green = 1 - Math.min(1, m * (1 - k) + k);
@@ -816,7 +810,7 @@ export const colorTypes = {
             }
             const [color1, color2] = parts;
             const { theme } = config;
-            return Color.from(theme === "light" ? color1 : color2).toArray({ fit: "none", precision: null });
+            return Color.from(theme === "light" ? color1 : color2).coords;
         },
     },
 };