@electrovir/color 0.0.0

package/dist/color-name-length.d.ts

@@ -0,0 +1,176 @@
+/**
+ * The longest CSS color name. Used for color name padding calculations.
+ *
+ * @category Internal
+ */
+export declare const longestColorName: string;
+/**
+ * All CSS color names with identical value matches to other CSS color names. Used for color name
+ * padding calculations.
+ *
+ * @category Internal
+ */
+export declare const identicalColorNames: Partial<{
+    aliceblue: string[];
+    antiquewhite: string[];
+    aqua: string[];
+    aquamarine: string[];
+    azure: string[];
+    beige: string[];
+    bisque: string[];
+    black: string[];
+    blanchedalmond: string[];
+    blue: string[];
+    blueviolet: string[];
+    brown: string[];
+    burlywood: string[];
+    cadetblue: string[];
+    chartreuse: string[];
+    chocolate: string[];
+    coral: string[];
+    cornflowerblue: string[];
+    cornsilk: string[];
+    crimson: string[];
+    cyan: string[];
+    darkblue: string[];
+    darkcyan: string[];
+    darkgoldenrod: string[];
+    darkgray: string[];
+    darkgreen: string[];
+    darkgrey: string[];
+    darkkhaki: string[];
+    darkmagenta: string[];
+    darkolivegreen: string[];
+    darkorange: string[];
+    darkorchid: string[];
+    darkred: string[];
+    darksalmon: string[];
+    darkseagreen: string[];
+    darkslateblue: string[];
+    darkslategray: string[];
+    darkslategrey: string[];
+    darkturquoise: string[];
+    darkviolet: string[];
+    deeppink: string[];
+    deepskyblue: string[];
+    dimgray: string[];
+    dimgrey: string[];
+    dodgerblue: string[];
+    firebrick: string[];
+    floralwhite: string[];
+    forestgreen: string[];
+    fuchsia: string[];
+    gainsboro: string[];
+    ghostwhite: string[];
+    gold: string[];
+    goldenrod: string[];
+    gray: string[];
+    green: string[];
+    greenyellow: string[];
+    grey: string[];
+    honeydew: string[];
+    hotpink: string[];
+    indianred: string[];
+    indigo: string[];
+    ivory: string[];
+    khaki: string[];
+    lavender: string[];
+    lavenderblush: string[];
+    lawngreen: string[];
+    lemonchiffon: string[];
+    lightblue: string[];
+    lightcoral: string[];
+    lightcyan: string[];
+    lightgoldenrodyellow: string[];
+    lightgray: string[];
+    lightgreen: string[];
+    lightgrey: string[];
+    lightpink: string[];
+    lightsalmon: string[];
+    lightseagreen: string[];
+    lightskyblue: string[];
+    lightslategray: string[];
+    lightslategrey: string[];
+    lightsteelblue: string[];
+    lightyellow: string[];
+    lime: string[];
+    limegreen: string[];
+    linen: string[];
+    magenta: string[];
+    maroon: string[];
+    mediumaquamarine: string[];
+    mediumblue: string[];
+    mediumorchid: string[];
+    mediumpurple: string[];
+    mediumseagreen: string[];
+    mediumslateblue: string[];
+    mediumspringgreen: string[];
+    mediumturquoise: string[];
+    mediumvioletred: string[];
+    midnightblue: string[];
+    mintcream: string[];
+    mistyrose: string[];
+    moccasin: string[];
+    navajowhite: string[];
+    navy: string[];
+    oldlace: string[];
+    olive: string[];
+    olivedrab: string[];
+    orange: string[];
+    orangered: string[];
+    orchid: string[];
+    palegoldenrod: string[];
+    palegreen: string[];
+    paleturquoise: string[];
+    palevioletred: string[];
+    papayawhip: string[];
+    peachpuff: string[];
+    peru: string[];
+    pink: string[];
+    plum: string[];
+    powderblue: string[];
+    purple: string[];
+    rebeccapurple: string[];
+    red: string[];
+    rosybrown: string[];
+    royalblue: string[];
+    saddlebrown: string[];
+    salmon: string[];
+    sandybrown: string[];
+    seagreen: string[];
+    seashell: string[];
+    sienna: string[];
+    silver: string[];
+    skyblue: string[];
+    slateblue: string[];
+    slategray: string[];
+    slategrey: string[];
+    snow: string[];
+    springgreen: string[];
+    steelblue: string[];
+    tan: string[];
+    teal: string[];
+    thistle: string[];
+    tomato: string[];
+    turquoise: string[];
+    violet: string[];
+    wheat: string[];
+    white: string[];
+    whitesmoke: string[];
+    yellow: string[];
+    yellowgreen: string[];
+}>;
+/**
+ * The longest collection of CSS color names with identical values. Used for color name padding
+ * calculations.
+ *
+ * @category Internal
+ */
+export declare const longestIdenticalColorNames: string[];
+/**
+ * The maximum length that a single-value collection of matching CSS color names can be (when joined
+ * with `', '`). Used for color name padding calculations.
+ *
+ * @category Internal
+ */
+export declare const maxColorNameLength: number;

package/dist/color-name-length.js

@@ -0,0 +1,75 @@
+import { check } from '@augment-vir/assert';
+import { filterMap, filterObject, mapObjectValues } from '@augment-vir/common';
+import colorNames from 'color-name';
+/**
+ * The longest CSS color name. Used for color name padding calculations.
+ *
+ * @category Internal
+ */
+export const longestColorName = Object.keys(colorNames).reduce((longest, current) => {
+    if (current.length > longest.length) {
+        return current;
+    }
+    else {
+        return longest;
+    }
+});
+/**
+ * All CSS color names with identical value matches to other CSS color names. Used for color name
+ * padding calculations.
+ *
+ * @category Internal
+ */
+export const identicalColorNames = filterObject(mapObjectValues(colorNames, (colorName, rgbValues) => {
+    const matches = filterMap(Object.entries(colorNames), ([colorName]) => colorName, (innerColorName, [, innerRgbValues,]) => {
+        if (innerColorName === colorName) {
+            return false;
+        }
+        return check.deepEquals(innerRgbValues, rgbValues);
+    });
+    return matches;
+}), (colorName, matches) => !!matches.length);
+/**
+ * The longest collection of CSS color names with identical values. Used for color name padding
+ * calculations.
+ *
+ * @category Internal
+ */
+export const longestIdenticalColorNames = Object.entries(identicalColorNames)
+    .reduce((longest, current) => {
+    const longestString = [
+        longest[0],
+        ...longest[1],
+    ].join(', ');
+    const currentString = [
+        current[0],
+        ...current[1],
+    ].join(', ');
+    if (currentString.length > longestString.length) {
+        return current;
+    }
+    else {
+        return longest;
+    }
+})
+    .reduce((combined, current) => {
+    if (check.isArray(current)) {
+        return [
+            ...combined,
+            ...current,
+        ];
+    }
+    else {
+        return [
+            ...combined,
+            current,
+        ];
+    }
+}, []);
+/**
+ * The maximum length that a single-value collection of matching CSS color names can be (when joined
+ * with `', '`). Used for color name padding calculations.
+ *
+ * @category Internal
+ */
+export const maxColorNameLength = Math.max(longestColorName.length, longestIdenticalColorNames.length + (longestIdenticalColorNames.length - 1) * ', '.length);

package/dist/color.d.ts

@@ -0,0 +1,171 @@
+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;
+    };
+}

package/dist/color.js

@@ -0,0 +1,243 @@
+import { assert, assertWrap, check } from '@augment-vir/assert';
+import { copyThroughJson, filterMap, getObjectTypedEntries, joinWithFinalConjunction, mapObjectValues, round, } from '@augment-vir/common';
+import colorNames from 'color-name';
+import { clampGamut, converter, formatHex, parse } from 'culori';
+import { colorFormatNames, colorFormats, } from './color-formats.js';
+import { maxColorNameLength } from './color-name-length.js';
+/**
+ * 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 class Color {
+    /**
+     * Create a new {@link Color} instance by parsing the output of another instance's
+     * {@link Color.serialize} method.
+     */
+    static deserialize(input) {
+        const parsed = JSON.parse(input);
+        const newColor = new Color('black');
+        getObjectTypedEntries(parsed).forEach(([key, value,]) => {
+            newColor._allColors[key] = value;
+        });
+        return newColor;
+    }
+    #internalColor = assertWrap.isDefined(parse('black'));
+    /** All current color values. These are updated whenever {@link Color.set} is called. */
+    _allColors = {
+        names: ['black'],
+        hex: '#000000',
+        rgb: {
+            r: 0,
+            g: 0,
+            b: 0,
+        },
+        hsl: {
+            h: 0,
+            s: 0,
+            l: 0,
+        },
+        hwb: {
+            h: 0,
+            w: 0,
+            b: 0,
+        },
+        lab: {
+            l: 0,
+            a: 0,
+            b: 0,
+        },
+        lch: {
+            l: 0,
+            c: 0,
+            h: 0,
+        },
+        oklab: {
+            l: 0,
+            a: 0,
+            b: 0,
+        },
+        oklch: {
+            l: 0,
+            c: 0,
+            h: 0,
+        },
+    };
+    constructor(
+    /** Any valid CSS color string or an object of color coordinate values. */
+    initValue) {
+        this.set(initValue);
+    }
+    /** Create a new {@link Color} instance that matches this one exactly. */
+    clone() {
+        return Color.deserialize(this.serialize());
+    }
+    /**
+     * Update the color to match the given string.
+     *
+     * @throws Error if `cssColorString` is not able to be parsed.
+     */
+    setByString(cssColorString) {
+        const newColor = parse(cssColorString);
+        if (!newColor) {
+            throw new Error(`Unable to parse invalid color string: '${cssColorString}'`);
+        }
+        this.#internalColor = newColor;
+        this.pullFromInternalColor();
+    }
+    /**
+     * 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) {
+        if (check.isString(newValue)) {
+            return this.setByString(newValue);
+        }
+        assert.isLengthExactly(Object.keys(newValue), 1, `Cannot set multiple color formats at once: got '${joinWithFinalConjunction(Object.keys(newValue))}'`);
+        if (newValue.hex || newValue.name) {
+            this.setByString(newValue.hex || newValue.name);
+        }
+        else {
+            const [colorFormatName, colorValues,] = assertWrap.isDefined(getObjectTypedEntries(newValue)[0]);
+            const colorFormatDefinition = colorFormats[colorFormatName];
+            const orderedColorCoords = Object.values(mapObjectValues(colorFormatDefinition.coords, (coordName) => {
+                const coordValue = colorValues[coordName];
+                const coordDefinition = assertWrap.isDefined(colorFormatDefinition.coords[coordName]);
+                const rawCoordValue = coordValue != undefined &&
+                    coordValue >= coordDefinition.min &&
+                    coordValue <= coordDefinition.max
+                    ? colorValues[coordName]
+                    : this[colorFormatName][coordName];
+                return assertWrap.isDefined(rawCoordValue);
+            }));
+            this.setByString(`${colorFormatName}(${orderedColorCoords.join(' ')})`);
+        }
+    }
+    /**
+     * Update all internally stored color format values ({@link Color.allColors}) from the updated
+     * internal color object.
+     */
+    pullFromInternalColor() {
+        colorFormatNames.forEach((colorFormatName) => {
+            const colorFormatDefinition = colorFormats[colorFormatName];
+            const originalColorDefinition = check.isKeyOf(this.#internalColor.mode, colorFormats)
+                ? colorFormats[this.#internalColor.mode]
+                : undefined;
+            const converted = clampGamut(colorFormatDefinition.colorSpace === originalColorDefinition?.colorSpace
+                ? colorFormatName
+                : 'rgb')(converter(colorFormatName)(this.#internalColor));
+            /* node:coverage ignore next 5: technically this shouldn't happen, idk how to manually trigger it. */
+            if (!converted) {
+                assert.never(`Failed to convert color '${JSON.stringify(this.#internalColor)}' to '${colorFormatName}'.`);
+            }
+            Object.keys(this[colorFormatName]).forEach((coordName) => {
+                const coordValue = converted[coordName];
+                if (coordValue != undefined) {
+                    this._allColors[colorFormatName][coordName] = round((coordValue || 0) * (colorFormatDefinition.coords[coordName]?.factor || 1), {
+                        digits: colorFormatDefinition.coords[coordName]?.digits || 0,
+                    });
+                }
+            });
+        });
+        this._allColors.hex = formatHex(this.#internalColor);
+        this._allColors.names = findMatchingColorNames(this.rgb);
+    }
+    /**
+     * Create a string that can be serialized into a new {@link Color} instance which will exactly
+     * match the current {@link Color} instance.
+     */
+    serialize() {
+        return JSON.stringify(this.allColors);
+    }
+    /** This individual color expressed in all the supported color formats. */
+    get allColors() {
+        return copyThroughJson(this._allColors);
+    }
+    /**
+     * Converts the values for each supported color format into a padded string for easy display
+     * purposes.
+     */
+    toFormattedStrings() {
+        const colorFormatStrings = mapObjectValues(colorFormats, (colorFormatName) => {
+            const coordValues = Object.values(this[colorFormatName]);
+            return coordValues.map((coordValue) => String(coordValue).padStart(6, ' ')).join(' ');
+        });
+        return {
+            hex: this.hex,
+            ...colorFormatStrings,
+            names: this.names.join(', ').padEnd(maxColorNameLength, ' '),
+        };
+    }
+    /**
+     * Converts the values for each supported color format in a CSS string that can be directly used
+     * in any modern CSS code.
+     */
+    toCss() {
+        const colorFormatStrings = mapObjectValues(colorFormats, (colorFormatName) => {
+            const coordValues = Object.values(this[colorFormatName]);
+            return `${colorFormatName}(${coordValues.join(' ')})`;
+        });
+        return {
+            hex: this.hex,
+            ...colorFormatStrings,
+            name: this.names[0] || '',
+        };
+    }
+    /**
+     * 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() {
+        return copyThroughJson(this._allColors.names);
+    }
+    /** The current color expressed as an RGB hex string. */
+    get hex() {
+        return copyThroughJson(this._allColors.hex);
+    }
+    /** The current color expressed as its RGB coordinate values. */
+    get rgb() {
+        return copyThroughJson(this._allColors.rgb);
+    }
+    /** The current color expressed as its HSL coordinate values. */
+    get hsl() {
+        return copyThroughJson(this._allColors.hsl);
+    }
+    /** The current color expressed as its HWB coordinate values. */
+    get hwb() {
+        return copyThroughJson(this._allColors.hwb);
+    }
+    /** The current color expressed as its LAB coordinate values. */
+    get lab() {
+        return copyThroughJson(this._allColors.lab);
+    }
+    /** The current color expressed as its LCH coordinate values. */
+    get lch() {
+        return copyThroughJson(this._allColors.lch);
+    }
+    /** The current color expressed as its Oklab coordinate values. */
+    get oklab() {
+        return copyThroughJson(this._allColors.oklab);
+    }
+    /** The current color expressed as its Oklch coordinate values. */
+    get oklch() {
+        return copyThroughJson(this._allColors.oklch);
+    }
+}
+function findMatchingColorNames(rgb) {
+    return filterMap(getObjectTypedEntries(colorNames), ([colorName,]) => {
+        return colorName;
+    }, (colorName, [, colorValues,]) => {
+        return check.deepEquals(colorValues, [
+            rgb.r,
+            rgb.g,
+            rgb.b,
+        ]);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './color-formats.js';
+export * from './color-name-length.js';
+export * from './color.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './color-formats.js';
+export * from './color-name-length.js';
+export * from './color.js';