@electrovir/color 1.1.0 → 1.2.0

package/dist/color-class/color-formats.d.ts

@@ -180,6 +180,24 @@ export declare const rawColorFormats: {
  * @enum
  */
 export declare const ColorFormatName: { [Key in ColorFormatName]: Key; };
+/**
+ * {@link ColorFormatName} combined with hex and named CSS color representation.
+ *
+ * @category Internal
+ * @enum
+ */
+export declare const ColorSyntaxName: {
+    readonly hex: "hex";
+    readonly name: "name";
+    readonly rgb: "rgb";
+    readonly hsl: "hsl";
+    readonly hwb: "hwb";
+    readonly lab: "lab";
+    readonly lch: "lch";
+    readonly oklab: "oklab";
+    readonly oklch: "oklch";
+};
+export type ColorSyntaxName = Values<typeof ColorSyntaxName>;
 /**
  * All supported color format names.
  *
@@ -240,6 +258,12 @@ export type ColorValue = {
  * @category Color Format
  */
 export declare const colorFormatsBySpace: { [ColorSpace in ColorSpaceName]: { [ColorFormat in ColorFormatName]: ColorFormatDefinition<ColorSpace, ColorFormat>; }; };
+/**
+ * Determines the color syntax / format in use based on the given CSS color string.
+ *
+ * @category Util
+ */
+export declare function getColorSyntaxFromCssString(cssString: string): ColorSyntaxName;
 /**
  * All possible coordinate names for all supported color formats in a union.
  *

package/dist/color-class/color-formats.js

@@ -151,6 +151,17 @@ export const rawColorFormats = {
  * @enum
  */
 export const ColorFormatName = mapObjectValues(rawColorFormats, (colorName) => colorName);
+/**
+ * {@link ColorFormatName} combined with hex and named CSS color representation.
+ *
+ * @category Internal
+ * @enum
+ */
+export const ColorSyntaxName = {
+    ...ColorFormatName,
+    hex: 'hex',
+    name: 'name',
+};
 /**
  * All supported color formats.
  *
@@ -187,3 +198,37 @@ export const colorFormatsBySpace = getObjectTypedEntries(colorFormats).reduce((a
     })[colorFormatName] = colorFormatDefinition;
     return accum;
 }, {});
+/**
+ * Determines the color syntax / format in use based on the given CSS color string.
+ *
+ * @category Util
+ */
+export function getColorSyntaxFromCssString(cssString) {
+    if (cssString.startsWith('rgb')) {
+        return ColorSyntaxName.rgb;
+    }
+    else if (cssString.startsWith('hsl')) {
+        return ColorSyntaxName.hsl;
+    }
+    else if (cssString.startsWith('hwb')) {
+        return ColorSyntaxName.hwb;
+    }
+    else if (cssString.startsWith('oklab')) {
+        return ColorSyntaxName.oklab;
+    }
+    else if (cssString.startsWith('oklch')) {
+        return ColorSyntaxName.oklch;
+    }
+    else if (cssString.startsWith('lab')) {
+        return ColorSyntaxName.lab;
+    }
+    else if (cssString.startsWith('lch')) {
+        return ColorSyntaxName.lch;
+    }
+    else if (cssString.startsWith('#')) {
+        return ColorSyntaxName.hex;
+    }
+    else {
+        return ColorSyntaxName.name;
+    }
+}

package/dist/color-class/color.d.ts

@@ -1,6 +1,6 @@
 import { type PartialWithUndefined } from '@augment-vir/common';
 import { type RequireExactlyOne } from 'type-fest';
-import { ColorFormatName, type ColorCoordsByFormat, type ColorValue, type HexColor } from './color-formats.js';
+import { ColorFormatName, ColorSyntaxName, type ColorCoordsByFormat, type ColorValue, type HexColor } from './color-formats.js';
 /**
  * An update to an existing {@link Color} instance. Used in {@link Color.set}.
  *
@@ -9,8 +9,8 @@ import { ColorFormatName, type ColorCoordsByFormat, type ColorValue, type HexCol
 export type ColorUpdate = RequireExactlyOne<{
     [FormatName in ColorFormatName]: PartialWithUndefined<Record<ColorCoordsByFormat[FormatName], number>>;
 } & {
-    hex: HexColor;
-    name: string;
+    [ColorSyntaxName.hex]: HexColor;
+    [ColorSyntaxName.name]: string;
 }>;
 /**
  * The values of all supported color formats for a given {@link Color} instance. Accessed via
@@ -19,7 +19,8 @@ export type ColorUpdate = RequireExactlyOne<{
  * @category Internal
  */
 export type AllColorsValues = ColorValue & {
-    hex: HexColor;
+    [ColorSyntaxName.hex]: HexColor;
+    [ColorSyntaxName.name]: string;
     names: string[];
 };
 /**
@@ -46,6 +47,7 @@ export declare class Color {
     /** All current color values. These are updated whenever {@link Color.set} is called. */
     protected readonly _allColors: {
         names: string[];
+        name: string;
         hex: HexColor;
         rgb: {
             r: number;
@@ -112,18 +114,27 @@ export declare class Color {
     /**
      * Converts the values for each supported color format into a padded string for easy display
      * purposes.
+     *
+     * @see `.toCss()`
      */
-    toFormattedStrings(): Record<ColorFormatName | 'hex' | 'names', string>;
+    toFormattedStrings(): Record<ColorSyntaxName | 'names', string>;
     /**
      * Converts the values for each supported color format in a CSS string that can be directly used
      * in any modern CSS code.
+     *
+     * @see `.toFormattedStrings()`
      */
-    toCss(): Record<ColorFormatName | 'hex' | 'name', string>;
+    toCss(): Record<ColorSyntaxName, 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 a single CSS color name string. If there is no color name that
+     * matches the current color, this will be an empty string.
+     */
+    get name(): string;
     /** The current color expressed as an RGB hex string. */
     get hex(): HexColor;
     /** The current color expressed as its RGB coordinate values. */

package/dist/color-class/color.js

@@ -2,7 +2,7 @@ import { assert, assertWrap, check } from '@augment-vir/assert';
 import { copyThroughJson, filterMap, getEnumValues, getObjectTypedEntries, getObjectTypedKeys, joinWithFinalConjunction, mapObjectValues, round, } from '@augment-vir/common';
 import colorNames from 'color-name';
 import { clampGamut, converter, formatHex, parse } from 'culori';
-import { ColorFormatName, colorFormats, } from './color-formats.js';
+import { ColorFormatName, colorFormats, ColorSyntaxName, } from './color-formats.js';
 import { maxColorNameLength } from './color-name-length.js';
 /**
  * A `Color` class with state and the following features:
@@ -37,38 +37,39 @@ export class Color {
     /** All current color values. These are updated whenever {@link Color.set} is called. */
     _allColors = {
         names: ['black'],
-        hex: '#000000',
-        rgb: {
+        [ColorSyntaxName.name]: 'black',
+        [ColorSyntaxName.hex]: '#000000',
+        [ColorSyntaxName.rgb]: {
             r: 0,
             g: 0,
             b: 0,
         },
-        hsl: {
+        [ColorSyntaxName.hsl]: {
             h: 0,
             s: 0,
             l: 0,
         },
-        hwb: {
+        [ColorSyntaxName.hwb]: {
             h: 0,
             w: 0,
             b: 0,
         },
-        lab: {
+        [ColorSyntaxName.lab]: {
             l: 0,
             a: 0,
             b: 0,
         },
-        lch: {
+        [ColorSyntaxName.lch]: {
             l: 0,
             c: 0,
             h: 0,
         },
-        oklab: {
+        [ColorSyntaxName.oklab]: {
             l: 0,
             a: 0,
             b: 0,
         },
-        oklch: {
+        [ColorSyntaxName.oklch]: {
             l: 0,
             c: 0,
             h: 0,
@@ -147,8 +148,9 @@ export class Color {
                 }
             });
         });
-        this._allColors.hex = formatHex(this.#internalColor);
+        this._allColors[ColorSyntaxName.hex] = formatHex(this.#internalColor);
         this._allColors.names = findMatchingColorNames(this.rgb);
+        this._allColors[ColorSyntaxName.name] = this._allColors.names[0] || '';
     }
     /**
      * Create a string that can be serialized into a new {@link Color} instance which will exactly
@@ -164,6 +166,8 @@ export class Color {
     /**
      * Converts the values for each supported color format into a padded string for easy display
      * purposes.
+     *
+     * @see `.toCss()`
      */
     toFormattedStrings() {
         const colorFormatStrings = mapObjectValues(colorFormats, (colorFormatName) => {
@@ -171,14 +175,17 @@ export class Color {
             return coordValues.map((coordValue) => String(coordValue).padStart(6, ' ')).join(' ');
         });
         return {
-            hex: this.hex,
+            [ColorSyntaxName.hex]: this.hex,
             ...colorFormatStrings,
             names: this.names.join(', ').padEnd(maxColorNameLength, ' '),
+            name: (this.names[0] || '').padEnd(maxColorNameLength, ' '),
         };
     }
     /**
      * Converts the values for each supported color format in a CSS string that can be directly used
      * in any modern CSS code.
+     *
+     * @see `.toFormattedStrings()`
      */
     toCss() {
         const colorFormatStrings = mapObjectValues(colorFormats, (colorFormatName) => {
@@ -186,7 +193,7 @@ export class Color {
             return `${colorFormatName}(${coordValues.join(' ')})`;
         });
         return {
-            hex: this.hex,
+            [ColorSyntaxName.hex]: this.hex,
             ...colorFormatStrings,
             name: this.names[0] || '',
         };
@@ -198,37 +205,44 @@ export class Color {
     get names() {
         return copyThroughJson(this._allColors.names);
     }
+    /**
+     * The current color expressed as a single CSS color name string. If there is no color name that
+     * matches the current color, this will be an empty string.
+     */
+    get name() {
+        return this._allColors.names[0] || '';
+    }
     /** The current color expressed as an RGB hex string. */
     get hex() {
-        return copyThroughJson(this._allColors.hex);
+        return copyThroughJson(this._allColors[ColorSyntaxName.hex]);
     }
     /** The current color expressed as its RGB coordinate values. */
     get rgb() {
-        return copyThroughJson(this._allColors.rgb);
+        return copyThroughJson(this._allColors[ColorSyntaxName.rgb]);
     }
     /** The current color expressed as its HSL coordinate values. */
     get hsl() {
-        return copyThroughJson(this._allColors.hsl);
+        return copyThroughJson(this._allColors[ColorSyntaxName.hsl]);
     }
     /** The current color expressed as its HWB coordinate values. */
     get hwb() {
-        return copyThroughJson(this._allColors.hwb);
+        return copyThroughJson(this._allColors[ColorSyntaxName.hwb]);
     }
     /** The current color expressed as its LAB coordinate values. */
     get lab() {
-        return copyThroughJson(this._allColors.lab);
+        return copyThroughJson(this._allColors[ColorSyntaxName.lab]);
     }
     /** The current color expressed as its LCH coordinate values. */
     get lch() {
-        return copyThroughJson(this._allColors.lch);
+        return copyThroughJson(this._allColors[ColorSyntaxName.lch]);
     }
     /** The current color expressed as its Oklab coordinate values. */
     get oklab() {
-        return copyThroughJson(this._allColors.oklab);
+        return copyThroughJson(this._allColors[ColorSyntaxName.oklab]);
     }
     /** The current color expressed as its Oklch coordinate values. */
     get oklch() {
-        return copyThroughJson(this._allColors.oklch);
+        return copyThroughJson(this._allColors[ColorSyntaxName.oklch]);
     }
 }
 function findMatchingColorNames(rgb) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@electrovir/color",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "A wrapper for culori with an extremely simple API.",
     "keywords": [
         "color",