saturon 0.2.3 → 0.3.0

package/dist/types.d.ts

@@ -1,7 +1,8 @@
 import { Color } from "./Color.js";
 import { systemColors } from "./config.js";
-import { namedColors, colorTypes, colorModels, colorBases, colorSpaces } from "./converters.js";
-import { EASINGS, fitMethods } from "./math.js";
+import { namedColors, colorModels, colorSpaces } from "./converters.js";
+import { fitMethods } from "./math.js";
+import { formatters, ParseNode } from "./engine.js";
 /** Represents the config object. */
 export type Config = {
     /** The theme of the application, either "light" or "dark". */
@@ -18,10 +19,6 @@ export type Config = {
 };
 /** Represents a plugin type for the `Color` class. */
 export type Plugin = (colorClass: typeof Color) => void;
-/** Represents the available `<color>`s. */
-export type ColorType = keyof typeof colorTypes;
-/** Represents the available `<color-base>`s. */
-export type ColorBase = keyof typeof colorBases;
 /** Represents the available `<color-function>`s. */
 export type ColorFunction = keyof typeof colorModels;
 /** Represents the available color spaces for `<color()>` function. */
@@ -32,58 +29,8 @@ export type ColorModel = keyof typeof colorModels;
 export type NamedColor = keyof typeof namedColors;
 /** Represents a `<system-color>` identifier. */
 export type SystemColor = keyof typeof systemColors;
-/** Represents the color types that support conversion from XYZ. */
-export type OutputType = {
-    [K in ColorType]: (typeof colorTypes)[K] extends {
-        fromBridge?: (components: number[]) => number[];
-        format?: (coords: number[]) => string | undefined;
-    } ? K : never;
-}[ColorType];
-/** Represents a converter for `<color>`s. */
-export type ColorConverter = {
-    /**
-     * Checks whether a given string is a valid representation of this color type.
-     *
-     * @param str - The string to validate.
-     * @returns `true` if the string is valid for this color type, otherwise `false`.
-     */
-    isValid: (str: string) => boolean;
-    /** The intermediate "bridge" color space used for conversion. Must be another `<color-function>` identifier (e.g., `"rgb"`, `"xyz"`). */
-    bridge: string;
-    /**
-     * Converts coordinates from the native color function into the bridge color space.
-     *
-     * @param coords - The coordinates in the native color function's space.
-     * @returns The coordinates converted to the bridge color space.
-     */
-    toBridge: (coords: number[]) => number[];
-    /**
-     * Parses a string representation of the color into its numeric coordinates.
-     *
-     * @param str - The string to parse.
-     * @returns The numeric coordinates of the color.
-     */
-    parse: (str: string) => number[];
-} & ({
-    /**
-     * Converts coordinates from the bridge color space back into the native color function's coordinate system.
-     *
-     * @param coords - The coordinates in the bridge color space.
-     * @returns The coordinates converted back to the native color function's space.
-     */
-    fromBridge: (coords: number[]) => number[];
-    /**
-     * Formats numeric component values into a valid CSS color string.
-     *
-     * @param coords - The numeric component values to format.
-     * @param options - Optional formatting options.
-     * @returns A formatted CSS color string, or `undefined` if formatting fails.
-     */
-    format: (coords: number[], options?: FormattingOptions) => string | undefined;
-} | {
-    fromBridge?: undefined;
-    format?: undefined;
-});
+/** Represents the color types that can be formatted to string output. */
+export type OutputType = keyof typeof formatters;
 /** Represents a converter for `<color-function>`s. */
 export type ColorModelConverter = {
     /** The target color gamut identifier that the function should be clamped to (e.g., `"srgb"`, `"display-p3"`), or `null` for color spaces without a fixed gamut (e.g., `lab`, `lch`). */
@@ -138,6 +85,43 @@ export type ColorSpaceConverter = {
     /** Matrix to convert from the bridge color space. */
     fromBridgeMatrix: number[][];
 };
+/** Represents an interface for serializing internal color data structures into specific string formats. */
+export type ColorFormatter = {
+    /** The intermediate "bridge" color space used for conversion (e.g., `"rgb"`, `"srgb"`). */
+    bridge: string;
+    /**
+     * Translates coordinates from the bridge color space into the format's local coordinate system.
+     *
+     * @param coords - The coordinates in the bridge color space.
+     * @returns The transformed coordinate values.
+     */
+    fromBridge: (coords: number[]) => number[];
+    /**
+     * Converts native channel coordinates into their string representation.
+     *
+     * @param coords - The coordinate array to format, with optional alpha at the last index.
+     * @param options - Options for adjusting output format, legacy syntax, and precision.
+     * @returns The formatted color string, or `undefined` if formatting fails.
+     */
+    format: (coords: number[], options?: FormattingOptions) => string | undefined;
+};
+/** Defines a grammar rule specification used to extend the CSS color parser engine. */
+export type GrammarRuleSpec = {
+    /** The name or names of existing grammar rules to append this rule to (e.g., `"<color>"`). */
+    appendTo?: string | string[];
+    /** The CSS-style syntax matching pattern for the custom grammar statement. */
+    rule: string;
+    /**
+     * Translates a matched abstract syntax tree node into a color model and coordinate array.
+     *
+     * @param node - The matched parse tree node.
+     * @returns The color model identifier and calculated coordinate values.
+     */
+    parse?: (node: ParseNode) => {
+        model: ColorModel;
+        coords: number[];
+    };
+};
 /** Defines the properties of a color component within a converter. */
 export type ComponentDefinition = {
     /** Position of the component in the color array */
@@ -152,11 +136,9 @@ export type ComponentDefinition = {
  *
  * @template M - The color model type.
  */
-export type Component<M extends ColorModel> = keyof (typeof colorModels)[M]["components"] | "alpha";
+export type Component<M extends ColorModel> = keyof (typeof colorModels)[M]["components"];
 /** Specifies the method used for interpolating hue values during color mixing. */
 export type HueInterpolationMethod = "shorter" | "longer" | "increasing" | "decreasing";
-/** Represents the set of valid easing function names. */
-export type Easing = keyof typeof EASINGS;
 /** Represents a gamut mapping method. */
 export type FitFunction = (coords: number[], model: ColorFunction) => number[];
 /** Describes the available methods for fitting the color into the target gamut. */
@@ -168,14 +150,19 @@ export type ComponentOptions = {
     /** Overrides the auto precision of the output color components, or `null` to disable rounding. */
     precision?: number | null;
 };
-/** Options for formatting color output. */
+/** Options for formatting color components. */
 export type FormattingOptions = ComponentOptions & {
     /** Use legacy syntax (e.g., `"rgba(255, 0, 0, 0.5)"`). */
     legacy?: boolean;
     /** Output components with optional unit suffixes (e.g., `"hsl(250deg 74% 54%)"`). */
     units?: boolean;
 };
-/** Options for generating a random Color instance. */
+/** Options for validating color strings with `Color.isValid()`. */
+export type IsValidOptions = {
+    /** The specific rule or color type to validate against (e.g., `"<rgb()>"`, `"<hex-color>"`, `"<color-base>"`). If omitted, validates against all supported formats. */
+    rule?: string;
+};
+/** Options for generating a random Color instance with `Color.random()`. */
 export type RandomOptions<M extends ColorModel = ColorModel> = {
     /** The color model to use (e.g., "rgb" or "hsl"). */
     model?: M;
@@ -188,14 +175,17 @@ export type RandomOptions<M extends ColorModel = ColorModel> = {
     /** Optional deviation values for each channel, used to control randomness. */
     deviation?: Partial<Record<Component<M>, number>>;
 };
-/** Options for mixing two colors. */
-export type MixOptions = {
-    /** Amount of the second color to mix in, between 0 and 1. */
-    amount?: number;
-    /** Method for interpolating hue values. */
+/** Represents an individual color component within a color-mix array in `Color.mix()`. */
+export type MixItem = {
+    /** The Color instance to be mixed. */
+    color: Color<ColorModel>;
+    /** The optional user-specified mixing weight percentage (0 to 100). */
+    percentage?: number;
+};
+/** Options configuring color mixing behavior in `Color.mix()`. */
+export type MixOptions<M extends ColorModel = "oklab"> = {
+    /** The color model to perform the mix in. If omitted, the mix is performed in OKLAB. */
+    in?: M;
+    /** The strategy used for hue interpolation in cylindrical spaces (e.g., "shorter", "longer"). */
     hue?: HueInterpolationMethod;
-    /** Easing function to apply to the interpolation parameter. */
-    easing?: Easing | ((t: number) => number);
-    /** Gamma correction value to use during mixing. */
-    gamma?: number;
 };

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
 import { Color } from "./Color.js";
-import type { ColorBase, ColorConverter, ColorFunction, ColorModelConverter, ColorModel, ColorSpace, ColorSpaceConverter, ColorType, ComponentDefinition, FitFunction, FitMethod, FormattingOptions, NamedColor, Plugin, Config, OutputType, SystemColor } from "./types.js";
+import type { ColorModel, ColorSpaceConverter, ComponentDefinition, FitMethod, Plugin, Config, HueInterpolationMethod } from "./types.js";
 /** Global cache for internal Color operations. */
 export declare const cache: Map<any, any>;
 /** Registered plugin functions for the Color class. */
@@ -29,133 +29,14 @@ export declare function configure(options: Partial<Config>): void;
  * @throws If no plugins are provided or a plugin is not a function.
  */
 export declare function use(...pluginFns: Plugin[]): void;
-declare const getterRegistry: {
-    readonly "color-types": () => ColorType[];
-    readonly "color-bases": () => ColorBase[];
-    readonly "color-functions": () => ColorFunction[];
-    readonly "color-models": () => ColorModel[];
-    readonly "color-spaces": () => ColorSpace[];
-    readonly "named-colors": () => NamedColor[];
-    readonly "system-colors": () => SystemColor[];
-    readonly "output-types": () => OutputType[];
-    readonly plugins: () => string[];
-    readonly "fit-methods": () => FitMethod[];
-};
-type Getter = keyof typeof getterRegistry;
-/**
- * Retrieve a list of registered items of a specified type.
- *
- * @param type - The getter type, e.g. "color-types".
- * @returns The array returned by the getter.
- */
-export declare function get<T extends Getter>(type: T): ReturnType<(typeof getterRegistry)[T]>;
-declare const converterRegistry: {
-    readonly "color-type": {
-        readonly fn: (name: string, value: ColorConverter) => void;
-    };
-    readonly "color-base": {
-        readonly fn: (name: string, value: ColorConverter) => void;
-    };
-    readonly "color-function": {
-        readonly fn: (name: string, value: ColorModelConverter) => void;
-    };
-    readonly "color-space": {
-        readonly fn: (name: string, value: ColorSpaceConverter) => void;
-    };
-    readonly "named-color": {
-        readonly fn: (name: string, value: number[]) => void;
-    };
-    readonly "fit-method": {
-        readonly fn: (name: string, value: FitFunction) => void;
-    };
-};
-type ConverterType = keyof typeof converterRegistry;
-type ConverterEntry<T extends ConverterType> = {
-    name: string;
-    value: Parameters<(typeof converterRegistry)[T]["fn"]>[1];
-};
-/**
- * Bulk register multiple converters of a specified type.
- *
- * @param type - The converter type, e.g. "color-function".
- * @param entries - Array of { name, value } objects.
- */
-export declare function register<T extends ConverterType>(type: T, entries: ConverterEntry<T>[]): void;
-/**
- * Registers a new `<color>` converter under the specified name.
- *
- * @param name - Unique name for the `<color>` converter.
- * @param converter - Converter implementing color conversion logic.
- * @throws If the name is already used or the converter is invalid.
- */
-export declare function registerColorType(name: string, converter: ColorConverter): void;
-/**
- * Registers a new `<color-base>` converter under the specified name.
- *
- * @param name - The unique name for the `<color-base>` converter.
- * @param converter - Converter implementing color conversion logic.
- * @throws If the name is already used or the converter is invalid.
- */
-export declare function registerColorBase(name: string, converter: ColorConverter): void;
-/**
- * Registers a new `<color-function>` converter under the specified name.
- *
- * @param name - The unique name for the `<color-function>` converter.
- * @param converter - Converter implementing color conversion logic.
- * @throws If the name is already used or the converter is invalid.
- */
-export declare function registerColorFunction(name: string, converter: ColorModelConverter): void;
-/**
- * Registers a new color space converter for `<color()>` function under the specified name.
- *
- * @param name - The unique name for the color space converter.
- * @param converter - Converter implementing color space conversion logic.
- * @throws If the name is already used or the converter is invalid.
- */
-export declare function registerColorSpace(name: string, converter: ColorSpaceConverter): void;
 /**
- * Registers a new `<named-color>` with the specified RGB value.
+ * Normalizes a component value to a valid range based on the component definition.
  *
- * @param name - Color name (letters only, case-insensitive).
- * @param rgb - RGB array [r, g, b].
- * @throws If RGB is invalid, or the name or value is already registered.
+ * @param component - The numeric component value to normalize
+ * @param value - The component definition that specifies the valid range (either a [min, max] tuple, "hue" for [0, 360], or a default [0, 100] range)
+ * @returns The normalized component value, clamped to the valid range or 0/max/min for NaN/Infinity cases
  */
-export declare function registerNamedColor(name: string, rgb: number[]): void;
-/**
- * Registers a new fit method under a specified name.
- *
- * @param name - Name for the fit method (whitespace → hyphens, lowercased).
- * @param method - The fit function.
- * @throws If name exists or method is not a function.
- */
-export declare function registerFitMethod(name: string, method: FitFunction): void;
-/**
- * Unregisters one or more color types from the registry.
- *
- * @param types - Names of color types to remove.
- */
-export declare function unregister(...types: string[]): void;
-/**
- * Cleans and normalizes a CSS color string.
- *
- * @param color - The CSS color string.
- * @returns The normalized string.
- */
-export declare function clean(color: string): string;
-/**
- * Extracts a balanced expression from a string starting at a given index.
- *
- * - If the character at `start` is '(', extracts the full parenthetical expression (including nested parentheses).
- * - Otherwise, extracts a contiguous sequence of alphanumeric characters, hyphens, percent signs, or '#'.
- *
- * @param input - The string to extract from.
- * @param start - Index to start extraction.
- * @returns An object with the extracted `expression` and the index `end` after it.
- */
-export declare function extractBalancedExpression(input: string, start: number): {
-    expression: string;
-    end: number;
-};
+export declare function normalize(component: number, value: ComponentDefinition["value"]): number;
 /**
  * Fits or clips color coordinates to a specified model and gamut.
  *
@@ -169,21 +50,6 @@ export declare function fit(coords: number[], model: ColorModel, options?: {
     method?: FitMethod;
     precision?: number | null;
 }): number[];
-/**
- * Converts a color model converter to `<color>` converter.
- *
- * @param name - The name of the color model.
- * @param converter - The color model converter definition.
- * @returns An object of type `ColorConverter`.
- */
-export declare function modelConverterToColorConverter(name: string, converter: ColorModelConverter): {
-    isValid: (str: string) => boolean;
-    bridge: string;
-    toBridge: (coords: number[]) => number[];
-    parse: (str: string) => number[];
-    fromBridge: (coords: number[]) => number[];
-    format: ([c1, c2, c3, a]: number[], options?: FormattingOptions) => string;
-};
 /**
  * Converts a color space converter to a color model converter.
  *
@@ -202,4 +68,7 @@ export declare function spaceConverterToModelConverter<const C extends readonly
     toBridge: (coords: number[]) => number[];
     fromBridge: (coords: number[]) => number[];
 };
-export {};
+export declare function hueDelta(a: number, b: number): number;
+export declare function hueDeltaLong(a: number, b: number): number;
+export declare function interpHue(a: number, b: number, t: number, method: string): number;
+export declare function mixTwo<M extends ColorModel = "oklab">(colorA: Color<M>, colorB: Color<M>, t: number, model?: M, hue?: HueInterpolationMethod): Color<M>;