@electrovir/color 1.4.0 → 1.5.0

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

@@ -23,6 +23,14 @@ export type AllColorsValues = ColorValue & {
     [ColorSyntaxName.name]: string;
     names: string[];
 };
+/**
+ * The output of `Color.serialize()`.
+ *
+ * @category Internal
+ */
+export type SerializedColor = AllColorsValues & {
+    originalColorSyntax: ColorSyntaxName;
+};
 /**
  * A `Color` class with state and the following features:
  *
@@ -39,11 +47,20 @@ export declare class Color {
     constructor(
     /** Any valid CSS color string or an object of color coordinate values. */
     initValue: string | Readonly<ColorUpdate>);
+    /** Checks, with a type guard, that a given input is a Color class instance. */
+    static isColor<T>(value: T): value is Extract<T, Readonly<Color>>;
     /**
      * Create a new {@link Color} instance by parsing the output of another instance's
      * {@link Color.serialize} method.
      */
     static deserialize(input: string): Color;
+    /**
+     * Converts the color class to a CSS string format in the color space and format that it was
+     * originally set with.
+     */
+    toString(): string;
+    /** The color syntax the this color was set with. */
+    protected originalColorSyntax: ColorSyntaxName;
     /** All current color values. These are updated whenever {@link Color.set} is called. */
     protected readonly _allColors: {
         names: string[];

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, ColorSyntaxName, } from './color-formats.js';
+import { ColorFormatName, colorFormats, ColorSyntaxName, getColorSyntaxFromCssString, } from './color-formats.js';
 import { maxColorNameLength } from './color-name-length.js';
 /**
  * A `Color` class with state and the following features:
@@ -21,6 +21,10 @@ export class Color {
     initValue) {
         this.set(initValue);
     }
+    /** Checks, with a type guard, that a given input is a Color class instance. */
+    static isColor(value) {
+        return value instanceof Color;
+    }
     /**
      * Create a new {@link Color} instance by parsing the output of another instance's
      * {@link Color.serialize} method.
@@ -29,10 +33,24 @@ export class Color {
         const parsed = JSON.parse(input);
         const newColor = new Color('black');
         getObjectTypedEntries(parsed).forEach(([key, value,]) => {
-            newColor._allColors[key] = value;
+            if (key === 'originalColorSyntax') {
+                newColor.originalColorSyntax = assertWrap.isEnumValue(value, ColorSyntaxName, 'Cannot deserialize: invalid color syntax.');
+            }
+            else {
+                newColor._allColors[key] = value;
+            }
         });
         return newColor;
     }
+    /**
+     * Converts the color class to a CSS string format in the color space and format that it was
+     * originally set with.
+     */
+    toString() {
+        return this.toCss()[this.originalColorSyntax];
+    }
+    /** The color syntax the this color was set with. */
+    originalColorSyntax = ColorSyntaxName.hex;
     #internalColor = assertWrap.isDefined(parse('black'));
     /** All current color values. These are updated whenever {@link Color.set} is called. */
     _allColors = {
@@ -89,6 +107,7 @@ export class Color {
         if (!newColor) {
             throw new Error(`Unable to parse invalid color string: '${cssColorString}'`);
         }
+        this.originalColorSyntax = getColorSyntaxFromCssString(cssColorString);
         this.#internalColor = newColor;
         this.pullFromInternalColor();
     }
@@ -157,7 +176,10 @@ export class Color {
      * match the current {@link Color} instance.
      */
     serialize() {
-        return JSON.stringify(this.allColors);
+        return JSON.stringify({
+            ...this.allColors,
+            originalColorSyntax: this.originalColorSyntax,
+        });
     }
     /** This individual color expressed in all the supported color formats. */
     get allColors() {

package/dist/demo/all-book-pages.d.ts

@@ -0,0 +1,2 @@
+import { type BookPage } from 'element-book';
+export declare const allBookPages: BookPage[];

package/dist/demo/all-book-pages.js

@@ -0,0 +1,9 @@
+import { colorExamplesPage } from './book-pages/color-examples.book.js';
+import { virColorPickerBookPage } from './book-pages/vir-color-picker.element.book.js';
+import { elementsBookPage, examplesBookPage } from './top-level-pages.js';
+export const allBookPages = [
+    elementsBookPage,
+    examplesBookPage,
+    colorExamplesPage,
+    virColorPickerBookPage,
+];

package/dist/demo/top-level-pages.d.ts

@@ -0,0 +1,2 @@
+export declare const elementsBookPage: import("element-book").BookPage<{}, undefined, {}>;
+export declare const examplesBookPage: import("element-book").BookPage<{}, undefined, {}>;

package/dist/demo/top-level-pages.js

@@ -0,0 +1,9 @@
+import { defineBookPage } from 'element-book';
+export const elementsBookPage = defineBookPage({
+    parent: undefined,
+    title: 'Elements',
+});
+export const examplesBookPage = defineBookPage({
+    parent: undefined,
+    title: 'Examples',
+});

package/dist/demo/vir-color-demo.element.d.ts

@@ -0,0 +1 @@
+export declare const VirColorDemo: import("element-vir").DeclarativeElementDefinition<"vir-color-demo", {}, {}, {}, "vir-color-demo-", "vir-color-demo-", readonly [], readonly []>;

package/dist/demo/vir-color-demo.element.js

@@ -0,0 +1,29 @@
+/* node:coverage disable */
+import { ElementBookApp } from 'element-book';
+import { css, defineElement, html } from 'element-vir';
+import { allBookPages } from './all-book-pages.js';
+export const VirColorDemo = defineElement()({
+    tagName: 'vir-color-demo',
+    styles: css `
+        :host {
+            display: flex;
+            flex-direction: column;
+            height: 100%;
+            width: 100%;
+            box-sizing: border-box;
+        }
+
+        ${ElementBookApp} {
+            flex-grow: 1;
+            max-width: 100%;
+            box-sizing: border-box;
+        }
+    `,
+    render() {
+        return html `
+            <${ElementBookApp.assign({
+            pages: allBookPages,
+        })}></${ElementBookApp}>
+        `;
+    },
+});

package/dist/elements/vir-color-picker.element.d.ts

@@ -0,0 +1,14 @@
+import { type ColorFormatName as ColorFormatNameType } from '../color-class/color-formats.js';
+import { Color } from '../color-class/color.js';
+/**
+ * A color picker element with a swatch that opens a popup with color format sliders.
+ *
+ * @category Elements
+ */
+export declare const VirColorPicker: import("element-vir").DeclarativeElementDefinition<"vir-color-picker", {
+    color: string | Readonly<Color> | undefined;
+}, {
+    selectedFormatName: ColorFormatNameType;
+}, {
+    colorChange: import("element-vir").DefineEvent<string>;
+}, "vir-color-picker-", "vir-color-picker-width" | "vir-color-picker-height", readonly [], readonly []>;

package/dist/elements/vir-color-picker.element.js

@@ -0,0 +1,115 @@
+/* node:coverage disable */
+import { checkWrap } from '@augment-vir/assert';
+import { getObjectTypedValues } from '@augment-vir/common';
+import { css, defineElement, defineElementEvent, html, listen, onResize } from 'element-vir';
+import { setCssVarValue } from 'lit-css-vars';
+import { ViraPopUpTrigger, ViraSelect, viraShadows } from 'vira';
+import { ColorFormatName, } from '../color-class/color-formats.js';
+import { Color } from '../color-class/color.js';
+import { VirColorFormatSliders } from './vir-color-format-sliders.element.js';
+import { VirColorSwatch } from './vir-color-swatch.element.js';
+const colorFormatOptions = getObjectTypedValues(ColorFormatName).map((formatName) => ({
+    value: formatName,
+    label: formatName.toUpperCase(),
+}));
+/**
+ * A color picker element with a swatch that opens a popup with color format sliders.
+ *
+ * @category Elements
+ */
+export const VirColorPicker = defineElement()({
+    tagName: 'vir-color-picker',
+    cssVars: {
+        'vir-color-picker-width': '100px',
+        'vir-color-picker-height': '100px',
+    },
+    styles: ({ cssVars }) => css `
+        :host {
+            display: inline-block;
+        }
+
+        ${ViraPopUpTrigger} {
+            width: 100%;
+            height: 100%;
+            box-sizing: border-box;
+        }
+
+        ${VirColorSwatch} {
+            width: ${cssVars['vir-color-picker-width'].value};
+            height: ${cssVars['vir-color-picker-height'].value};
+            cursor: pointer;
+            box-sizing: border-box;
+        }
+
+        .popup-content {
+            display: flex;
+            flex-direction: column;
+            gap: 16px;
+            padding: 16px;
+            background: white;
+            border: 1px solid #ccc;
+            border-radius: 8px;
+            ${viraShadows.menuShadow}
+        }
+    `,
+    events: {
+        colorChange: defineElementEvent(),
+    },
+    state() {
+        return {
+            selectedFormatName: ColorFormatName.rgb,
+        };
+    },
+    render({ inputs, dispatch, events, state, updateState, host, cssVars }) {
+        const color = Color.isColor(inputs.color)
+            ? inputs.color
+            : new Color(inputs.color || 'black');
+        return html `
+            <${ViraPopUpTrigger.assign({
+            keepOpenAfterInteraction: true,
+        })}
+                ${onResize((size) => {
+            setCssVarValue({
+                onElement: host,
+                forCssVar: cssVars['vir-color-picker-width'],
+                toValue: `${size.contentRect.width}px`,
+            });
+            setCssVarValue({
+                onElement: host,
+                forCssVar: cssVars['vir-color-picker-height'],
+                toValue: `${size.contentRect.height}px`,
+            });
+        })}
+            >
+                <${VirColorSwatch.assign({
+            backgroundColor: color,
+        })}
+                    slot=${ViraPopUpTrigger.slotNames.trigger}
+                ></${VirColorSwatch}>
+                <div class="popup-content" slot=${ViraPopUpTrigger.slotNames.popUp}>
+                    <${ViraSelect.assign({
+            options: colorFormatOptions,
+            value: state.selectedFormatName,
+        })}
+                        ${listen(ViraSelect.events.valueChange, (event) => {
+            const selectedFormat = checkWrap.isEnumValue(event.detail, ColorFormatName);
+            if (selectedFormat) {
+                updateState({
+                    selectedFormatName: selectedFormat,
+                });
+            }
+        })}
+                    ></${ViraSelect}>
+                    <${VirColorFormatSliders.assign({
+            color,
+            colorFormatName: state.selectedFormatName,
+        })}
+                        ${listen(VirColorFormatSliders.events.colorChange, (event) => {
+            dispatch(new events.colorChange(event.detail));
+        })}
+                    ></${VirColorFormatSliders}>
+                </div>
+            </${ViraPopUpTrigger}>
+        `;
+    },
+});

package/dist/elements/vir-color-swatch.element.d.ts

@@ -1,3 +1,4 @@
+import { type Color } from '../color-class/color.js';
 /**
  * Show a background and/or foreground color. Note that if a foreground color is provided that it is
  * not actually applied to anything, you must provide a child element for it to be applied to.
@@ -5,15 +6,15 @@
  * @category Elements
  */
 export declare const VirColorSwatch: import("element-vir").DeclarativeElementDefinition<"vir-color-swatch", ((Required<Pick<{
-    foregroundColor: string;
-    backgroundColor: string;
+    foregroundColor: string | Readonly<Color>;
+    backgroundColor: string | Readonly<Color>;
 }, "foregroundColor">> & Partial<Pick<{
-    foregroundColor: string;
-    backgroundColor: string;
+    foregroundColor: string | Readonly<Color>;
+    backgroundColor: string | Readonly<Color>;
 }, "backgroundColor">>) | (Required<Pick<{
-    foregroundColor: string;
-    backgroundColor: string;
+    foregroundColor: string | Readonly<Color>;
+    backgroundColor: string | Readonly<Color>;
 }, "backgroundColor">> & Partial<Pick<{
-    foregroundColor: string;
-    backgroundColor: string;
+    foregroundColor: string | Readonly<Color>;
+    backgroundColor: string | Readonly<Color>;
 }, "foregroundColor">>)) & {}, {}, {}, "vir-color-swatch-", "vir-color-swatch-", readonly [], readonly []>;

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './elements/vir-color-details.element.js';
 export * from './elements/vir-color-format-sliders.element.js';
 export * from './elements/vir-color-pair-contrast-summary.element.js';
 export * from './elements/vir-color-pair.element.js';
+export * from './elements/vir-color-picker.element.js';
 export * from './elements/vir-color-slider.element.js';
 export * from './elements/vir-color-swatch.element.js';
 export * from './elements/vir-contrast-indicator.element.js';

package/dist/index.js

@@ -8,6 +8,7 @@ export * from './elements/vir-color-details.element.js';
 export * from './elements/vir-color-format-sliders.element.js';
 export * from './elements/vir-color-pair-contrast-summary.element.js';
 export * from './elements/vir-color-pair.element.js';
+export * from './elements/vir-color-picker.element.js';
 export * from './elements/vir-color-slider.element.js';
 export * from './elements/vir-color-swatch.element.js';
 export * from './elements/vir-contrast-indicator.element.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@electrovir/color",
-    "version": "1.4.0",
+    "version": "1.5.0",
     "description": "A wrapper for culori with an extremely simple API.",
     "keywords": [
         "color",
@@ -74,6 +74,7 @@
         "@web/test-runner-visual-regression": "^0.10.0",
         "cspell": "^9.4.0",
         "dependency-cruiser": "^17.3.5",
+        "element-book": "^26.14.1",
         "element-vir": "^26.14.0",
         "esbuild": "^0.27.2",
         "eslint": "^9.39.2",