@electrovir/color/dist/color.d.ts

A wrapper for culori with an extremely simple API.

import { type PartialWithUndefined } from '@augment-vir/common';
import { type RequireExactlyOne } from 'type-fest';
import { type ColorCoordsByFormat, type ColorFormatName, type ColorValues, type HexColor } from './color-formats.js';
/**
 * An update to an existing {@link Color} instance. Used in {@link Color.set}.
 *
 * @category Internal
 */
export type ColorUpdate = RequireExactlyOne<{
    [FormatName in ColorFormatName]: PartialWithUndefined<Record<ColorCoordsByFormat[FormatName], number>>;
} & {
    hex: HexColor;
    name: string;
}>;
/**
 * The values of all supported color formats for a given {@link Color} instance. Accessed via
 * {@link Color.allColors}.
 *
 * @category Internal
 */
export type AllColorsValues = ColorValues & {
    hex: HexColor;
    names: string[];
};
/**
 * A `Color` class with state and the following features:
 *
 * - Color coordinates do not change when they become `'none'`, they stay at their previous value.
 *   This makes for a much smoother UI experience.
 * - All relevant color spaces and formats are always set (no extra conversions necessary).
 * - Matching CSS color names are tracked.
 * - This class is exported correctly and the types aren't a mess.
 *
 * @category Color
 */
export declare class Color {
    #private;
    /**
     * Create a new {@link Color} instance by parsing the output of another instance's
     * {@link Color.serialize} method.
     */
    static deserialize(input: string): Color;
    /** All current color values. These are updated whenever {@link Color.set} is called. */
    protected readonly _allColors: {
        names: string[];
        hex: HexColor;
        rgb: {
            r: number;
            g: number;
            b: number;
        };
        hsl: {
            h: number;
            s: number;
            l: number;
        };
        hwb: {
            h: number;
            w: number;
            b: number;
        };
        lab: {
            l: number;
            a: number;
            b: number;
        };
        lch: {
            l: number;
            c: number;
            h: number;
        };
        oklab: {
            l: number;
            a: number;
            b: number;
        };
        oklch: {
            l: number;
            c: number;
            h: number;
        };
    };
    constructor(
    /** Any valid CSS color string or an object of color coordinate values. */
    initValue: string | Readonly<ColorUpdate>);
    /** Create a new {@link Color} instance that matches this one exactly. */
    clone(): Color;
    /**
     * Update the color to match the given string.
     *
     * @throws Error if `cssColorString` is not able to be parsed.
     */
    protected setByString(cssColorString: string): void;
    /**
     * Update the current color by setting a whole new color, a single coordinate in a single color
     * format, or multiple coordinates in a single color format. This mutates the current
     * {@link Color} instance.
     */
    set(newValue: Readonly<ColorUpdate> | string): void;
    /**
     * Update all internally stored color format values ({@link Color.allColors}) from the updated
     * internal color object.
     */
    protected pullFromInternalColor(): void;
    /**
     * Create a string that can be serialized into a new {@link Color} instance which will exactly
     * match the current {@link Color} instance.
     */
    serialize(): string;
    /** This individual color expressed in all the supported color formats. */
    get allColors(): AllColorsValues;
    /**
     * Converts the values for each supported color format into a padded string for easy display
     * purposes.
     */
    toFormattedStrings(): Record<ColorFormatName | 'hex' | 'names', string>;
    /**
     * Converts the values for each supported color format in a CSS string that can be directly used
     * in any modern CSS code.
     */
    toCss(): Record<ColorFormatName | 'hex' | 'name', string>;
    /**
     * The current color expressed as hardcoded CSS color keywords. If no CSS color keywords match
     * the current color, this array will be empty.
     */
    get names(): string[];
    /** The current color expressed as an RGB hex string. */
    get hex(): HexColor;
    /** The current color expressed as its RGB coordinate values. */
    get rgb(): {
        r: number;
        g: number;
        b: number;
    };
    /** The current color expressed as its HSL coordinate values. */
    get hsl(): {
        h: number;
        s: number;
        l: number;
    };
    /** The current color expressed as its HWB coordinate values. */
    get hwb(): {
        b: number;
        h: number;
        w: number;
    };
    /** The current color expressed as its LAB coordinate values. */
    get lab(): {
        b: number;
        l: number;
        a: number;
    };
    /** The current color expressed as its LCH coordinate values. */
    get lch(): {
        h: number;
        l: number;
        c: number;
    };
    /** The current color expressed as its Oklab coordinate values. */
    get oklab(): {
        b: number;
        l: number;
        a: number;
    };
    /** The current color expressed as its Oklch coordinate values. */
    get oklch(): {
        h: number;
        l: number;
        c: number;
    };
}