saturon 0.2.2 → 0.3.0

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright © 2025 Ganemede Labs
+Copyright © 2026 Ganemede Labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -22,7 +22,7 @@ A runtime-extensible JavaScript library for parsing, converting, and manipulatin
 - Infinite nested color functions (e.g. `color-mix(...)` inside `light-dark(...)`)
 - Converts between all modern color spaces (OKLab, Display-P3, Rec.2020, etc.)
 - High-precision color math for serious colorimetry
-- Powerful plugin system for custom color spaces and functions
+- Powerful plugin system for custom color spaces and syntaxes
 - Supports complex color syntaxes like `color(from hsl(240 none calc(-infinity) / 0.5) display-p3 r calc(g + b) 100 / alpha)`
 
 ## 🔧 Installation
@@ -77,14 +77,15 @@ console.log(hwb.toString()); // → hwb(100 7 20)
 
 ```js
 const red = Color.from("hsl(0, 100%, 50%)");
-const mixed = red.mix("hsl(120, 100%, 50%)");
+const green = Color.from("hsl(120, 100%, 50%)");
+const mixed = Color.mix({ in: "hsl", colors: [{ color: red }, { color: green }] });
 console.log(mixed.toString()); // → hsl(60 100 50)
 ```
 
 ### New Named Color Registration
 
 ```js
-registerNamedColor("sunsetblush", [255, 94, 77]);
+register("named-color", [{ name: "sunsetblush", value: [255, 94, 77] }]);
 const rgb = Color.from("rgb(255, 94, 77)");
 console.log(rgb.to("named-color")); // → sunsetblush
 ```
@@ -103,7 +104,7 @@ const converter = {
     fromBridge: (rgb: number[]) => [/* i, ct, cp */],
 };
 
-registerColorFunction("ictcp", converter);
+register("color-function", [{ name: "ictcp", value: converter }]);
 const ictcp = Color.from("ictcp(0.2 0.2 -0.1)");
 console.log(ictcp.to("rgb")); // → rgb(6 7 90)
 ```

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, OutputType, FormattingOptions, NamedColor, ColorSpace, FitMethod, ColorModel, RandomOptions, ComponentOptions, MixItem, IsValidOptions } 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).
@@ -23,24 +23,25 @@ export declare class Color<M extends ColorModel = ColorModel> {
     static from(color: `lch(${string})`): Color<"lch">;
     static from(color: `oklab(${string})`): Color<"oklab">;
     static from(color: `oklch(${string})`): Color<"oklch">;
+    static from(color: `color(srgb ${string})`): Color<"srgb">;
+    static from(color: `color(srgb-linear ${string})`): Color<"srgb-linear">;
+    static from(color: `color(display-p3 ${string})`): Color<"display-p3">;
+    static from(color: `color(rec2020 ${string})`): Color<"rec2020">;
+    static from(color: `color(a98-rgb ${string})`): Color<"a98-rgb">;
+    static from(color: `color(prophoto-rgb ${string})`): Color<"prophoto-rgb">;
+    static from(color: `color(xyz-d65 ${string})`): Color<"xyz-d65">;
+    static from(color: `color(xyz-d50 ${string})`): Color<"xyz-d50">;
+    static from(color: `color(xyz ${string})`): Color<"xyz">;
     static from(color: string): Color<any>;
     static from<T extends ColorModel = ColorModel>(color: string): Color<T>;
     /**
-     * Returns the detected color type, or `undefined` if unrecognized.
-     *
-     * @param color - Color string to analyze.
-     * @param strict - Whether to validate full round-trip conversion.
-     */
-    static type(color: string, strict?: boolean): "hex-color" | "rgb" | "xyz-d65" | "xyz-d50" | "lab" | "oklab" | "srgb" | "srgb-linear" | "display-p3" | "rec2020" | "a98-rgb" | "prophoto-rgb" | "xyz" | "hsl" | "hwb" | "lch" | "oklch" | "named-color" | "color-mix" | "transparent" | "currentColor" | "system-color" | "contrast-color" | "device-cmyk" | "light-dark" | undefined;
-    /**
-     * Validates a color string, optionally for a specific type.
+     * Validates a color string.
      *
      * @param color - Color string to check.
-     * @param type - Optional color type.
+     * @param options - Validation options.
      * @returns `true` if valid, otherwise `false`.
      */
-    static isValid(color: string, type?: ColorType): boolean;
-    static isValid(color: string, type?: string): boolean;
+    static isValid(color: string, options?: IsValidOptions): boolean;
     /**
      * Generates a random `Color` instance.
      *
@@ -50,6 +51,15 @@ export declare class Color<M extends ColorModel = ColorModel> {
      * @throws If an invalid component is specified.
      */
     static random<M extends ColorModel = ColorModel>(options?: RandomOptions<M>): Color<M>;
+    /**
+     * 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<M extends ColorModel = "oklab">(colors: MixItem[], options: MixOptions<M>): Color<M>;
     /**
      * Converts this color to a specified format.
      *
@@ -79,20 +89,22 @@ export declare class Color<M extends ColorModel = ColorModel> {
      * 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.
      */
-    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.
      *
      * @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?: 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,29 +143,29 @@ 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 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
      */
     with(values: Partial<{
-        [K in Component<M> | "alpha"]: number | ((prev: number) => number);
+        [K in Component<M>]: number | ((prev: number) => number);
     }> | ((components: {
-        [K in Component<M> | "alpha"]: number;
+        [K in Component<M>]: number;
     }) => Partial<{
-        [K in Component<M> | "alpha"]: number;
+        [K in Component<M>]: number;
     }> | (number | undefined)[]) | (number | undefined)[]): Color<M>;
     /**
-     * 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: Color<ColorModel> | string, options?: MixOptions): Color<M>;
+    fit(options?: ComponentOptions): Color<M>;
     /**
      * Fits this color within the specified gamut using a given method.
      *
@@ -166,18 +178,18 @@ export declare class Color<M extends ColorModel = ColorModel> {
     /**
      * 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
      * - Ratios ≥ 4.5 are generally accessible for normal text.
      * - For perceptual accuracy, consider using APCA instead.
      */
-    contrast(other: Color<ColorModel> | string): number;
+    contrast(other: Color<ColorModel>): number;
     /**
      * 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
@@ -185,36 +197,36 @@ export declare class Color<M extends ColorModel = ColorModel> {
      * OKLAB's perceptual uniformity allows for a straightforward distance calculation without additional weighting.
      * The result is normalized by a factor of 100 to align with OKLAB's L range (0-1) and approximate the JND scale.
      */
-    deltaEOK(other: Color<ColorModel> | string): number;
+    deltaEOK(other: Color<ColorModel>): number;
     /**
      * 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: Color<ColorModel> | string): number;
+    deltaE76(other: Color<ColorModel>): number;
     /**
      * 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: Color<ColorModel> | string): number;
+    deltaE94(other: Color<ColorModel>): number;
     /**
      * 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: Color<ColorModel> | string): number;
+    deltaE2000(other: Color<ColorModel>): number;
     /**
      * 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
@@ -228,12 +240,12 @@ export declare class Color<M extends ColorModel = ColorModel> {
      *   - {@link deltaE94} (weighted improvements over LAB)
      *   - {@link deltaE2000} (most accurate, accounts for perceptual interactions)
      */
-    equals(other: Color<ColorModel> | string, epsilon?: number): boolean;
+    equals(other: Color<ColorModel>, epsilon?: number): boolean;
     /**
      * 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: ColorSpace | string, epsilon?: number): boolean;