vira 32.0.0-beta.0 → 32.0.0

package/{src/util/vira-select-option.ts → dist/util/vira-select-option.d.ts}

@@ -1,5 +1,4 @@
-import {type PartialWithUndefined} from '@augment-vir/common';
-
+import { type PartialWithUndefined } from '@augment-vir/common';
 /**
  * Options for `ViraSelect` and `ViraDropdown`.
  *
@@ -14,7 +13,6 @@ export type ViraSelectOption = {
 } & PartialWithUndefined<{
     disabled: boolean;
 }>;
-
 /**
  * A group of options for `ViraSelect`, rendered as an `<optgroup>`.
  *
@@ -25,14 +23,9 @@ export type ViraSelectOptionGroup = {
     groupName: string;
     options: ReadonlyArray<Readonly<ViraSelectOption>>;
 };
-
 /**
  * Type guard to determine if a `ViraSelect` options entry is a group.
  *
  * @category Internal
  */
-export function isViraSelectOptionGroup(
-    entry: Readonly<ViraSelectOption> | Readonly<ViraSelectOptionGroup>,
-): entry is Readonly<ViraSelectOptionGroup> {
-    return 'groupName' in entry;
-}
+export declare function isViraSelectOptionGroup(entry: Readonly<ViraSelectOption> | Readonly<ViraSelectOptionGroup>): entry is Readonly<ViraSelectOptionGroup>;

package/dist/util/vira-select-option.js

@@ -0,0 +1,8 @@
+/**
+ * Type guard to determine if a `ViraSelect` options entry is a group.
+ *
+ * @category Internal
+ */
+export function isViraSelectOptionGroup(entry) {
+    return 'groupName' in entry;
+}

package/dist/util/vira-theme-client.d.ts

@@ -0,0 +1,83 @@
+import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { LocalStorageClient } from '@electrovir/local-storage-client';
+/**
+ * A user-facing selection of which theme to display. `Auto` follows the system color scheme; the
+ * other values force a specific theme regardless of system preference.
+ *
+ * @category Internal
+ */
+export declare enum ViraThemeSelection {
+    Light = "light",
+    Dark = "dark",
+    Auto = "auto"
+}
+/**
+ * Used by {@link ViraThemeClient} to apply themes. By default, vira themes will be applied (via
+ * {@link defaultApplyThemeCallback}).
+ *
+ * @category Internal
+ * @default `defaultApplyThemeCallback`
+ */
+export type ApplyThemeCallback = (params: Readonly<{
+    useDarkTheme: boolean;
+}>) => MaybePromise<void>;
+/**
+ * Default implementation of {@link ApplyThemeCallback}, which simply applies Vira themes.
+ *
+ * @category Internal
+ */
+export declare const defaultApplyThemeCallback: ApplyThemeCallback;
+/**
+ * Constructor params for {@link ViraThemeClient}.
+ *
+ * @category Internal
+ */
+export type ViraThemeClientParams = PartialWithUndefined<{
+    /**
+     * Called whenever the effective theme should change. If not provided, the default Vira themes
+     * will be used.
+     */
+    applyTheme: ApplyThemeCallback;
+    /**
+     * Override the LocalStorage store name used for theme persistence. Useful if a single page
+     * hosts multiple isolated theme clients.
+     *
+     * @default 'vira-theme'
+     */
+    storeName: string;
+}>;
+declare const themeStorageShapes: {
+    selectedTheme: import("object-shape-tester").Shape<{
+        theme: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TLiteral<ViraThemeSelection.Light> | import("@sinclair/typebox").TLiteral<ViraThemeSelection.Dark> | import("@sinclair/typebox").TLiteral<ViraThemeSelection.Auto>)[]>>;
+    }>;
+};
+/**
+ * Tracks the user's {@link ViraThemeSelection} and bridges it to a consumer-supplied `applyTheme`
+ * callback. Persists the selection in LocalStorage via an internal `LocalStorageClient`, and
+ * listens for system color-scheme changes to re-apply the theme in auto mode without persisting.
+ *
+ * The initial theme is applied during construction.
+ *
+ * @category Util
+ */
+export declare class ViraThemeClient {
+    /** The callback that will be called to apply a new theme. */
+    protected readonly applyThemeCallback: ApplyThemeCallback;
+    /** Contains the user's last selected theme, saving and loading it to disk for persistence. */
+    protected readonly localStorageClient: LocalStorageClient<typeof themeStorageShapes>;
+    /** A callback to remove the global theme preference listener. */
+    protected readonly removeThemePreferenceListener: () => void;
+    constructor(params?: Readonly<ViraThemeClientParams>);
+    /**
+     * The currently selected theme. If you use multiple clients to set the same theme, this might
+     * get out of sync.
+     */
+    get currentTheme(): ViraThemeSelection;
+    /** Set the selected theme. */
+    setSelectedTheme(selection: ViraThemeSelection): void;
+    /** Cleanup internal state and listeners. */
+    destroy(): void;
+    /** Apply the currently selected theme. */
+    protected applySelection(selection: ViraThemeSelection): void;
+}
+export {};

package/dist/util/vira-theme-client.js

@@ -0,0 +1,93 @@
+import { assert } from '@augment-vir/assert';
+import { LocalStorageClient } from '@electrovir/local-storage-client';
+import { defineShape, enumShape } from 'object-shape-tester';
+import { applyColorThemeViaStyleElement } from 'theme-vir/dist/color-theme/apply-color-theme.js';
+import { listenTo } from 'typed-event-target';
+import { viraTheme, viraThemeDarkOverride } from '../styles/vira-color-theme.js';
+/**
+ * A user-facing selection of which theme to display. `Auto` follows the system color scheme; the
+ * other values force a specific theme regardless of system preference.
+ *
+ * @category Internal
+ */
+export var ViraThemeSelection;
+(function (ViraThemeSelection) {
+    ViraThemeSelection["Light"] = "light";
+    ViraThemeSelection["Dark"] = "dark";
+    ViraThemeSelection["Auto"] = "auto";
+})(ViraThemeSelection || (ViraThemeSelection = {}));
+/**
+ * Default implementation of {@link ApplyThemeCallback}, which simply applies Vira themes.
+ *
+ * @category Internal
+ */
+export const defaultApplyThemeCallback = ({ useDarkTheme }) => {
+    applyColorThemeViaStyleElement(viraTheme, useDarkTheme ? viraThemeDarkOverride : undefined);
+};
+const darkSchemeMediaQuery = '(prefers-color-scheme: dark)';
+const themeStorageShapes = {
+    selectedTheme: defineShape({
+        theme: enumShape(ViraThemeSelection),
+    }),
+};
+/**
+ * Tracks the user's {@link ViraThemeSelection} and bridges it to a consumer-supplied `applyTheme`
+ * callback. Persists the selection in LocalStorage via an internal `LocalStorageClient`, and
+ * listens for system color-scheme changes to re-apply the theme in auto mode without persisting.
+ *
+ * The initial theme is applied during construction.
+ *
+ * @category Util
+ */
+export class ViraThemeClient {
+    /** The callback that will be called to apply a new theme. */
+    applyThemeCallback = defaultApplyThemeCallback;
+    /** Contains the user's last selected theme, saving and loading it to disk for persistence. */
+    localStorageClient;
+    /** A callback to remove the global theme preference listener. */
+    removeThemePreferenceListener = listenTo(globalThis.matchMedia(darkSchemeMediaQuery), 'change', (event) => {
+        assert.instanceOf(event, MediaQueryListEvent);
+        if (this.currentTheme === ViraThemeSelection.Auto) {
+            void this.applyThemeCallback({
+                useDarkTheme: event.matches,
+            });
+        }
+    });
+    constructor(params = {}) {
+        if (params.applyTheme) {
+            this.applyThemeCallback = params.applyTheme;
+        }
+        this.localStorageClient = new LocalStorageClient(themeStorageShapes, {
+            storeName: params.storeName || 'vira-theme',
+        });
+        this.applySelection(this.currentTheme);
+    }
+    /**
+     * The currently selected theme. If you use multiple clients to set the same theme, this might
+     * get out of sync.
+     */
+    get currentTheme() {
+        return this.localStorageClient.get.selectedTheme()?.theme || ViraThemeSelection.Auto;
+    }
+    /** Set the selected theme. */
+    setSelectedTheme(selection) {
+        this.applySelection(selection);
+        this.localStorageClient.set.selectedTheme({
+            theme: selection,
+        });
+    }
+    /** Cleanup internal state and listeners. */
+    destroy() {
+        this.removeThemePreferenceListener();
+        this.localStorageClient.destroy();
+    }
+    /** Apply the currently selected theme. */
+    applySelection(selection) {
+        const useDarkTheme = selection === ViraThemeSelection.Dark ||
+            (selection === ViraThemeSelection.Auto &&
+                globalThis.matchMedia(darkSchemeMediaQuery).matches);
+        void this.applyThemeCallback({
+            useDarkTheme,
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vira",
-    "version": "32.0.0-beta.0",
+    "version": "32.0.0",
     "description": "A simple and highly versatile design system using element-vir.",
     "keywords": [
         "design",
@@ -27,9 +27,9 @@
     },
     "sideEffects": false,
     "type": "module",
-    "main": "src/index.ts",
-    "module": "src/index.ts",
-    "types": "src/index.ts",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
     "scripts": {
         "build": "npm run docs",
         "compile": "virmator compile",
@@ -38,13 +38,13 @@
         "test:docs": "virmator docs check"
     },
     "dependencies": {
-        "@augment-vir/assert": "^32.3.0-beta.0",
-        "@augment-vir/common": "^32.3.0-beta.0",
-        "@augment-vir/web": "^32.3.0-beta.0",
-        "@electrovir/color": "^2.0.0-beta.0",
+        "@augment-vir/assert": "^32.3.0",
+        "@augment-vir/common": "^32.3.0",
+        "@augment-vir/web": "^32.3.0",
+        "@electrovir/color": "^2.0.0",
         "@electrovir/local-storage-client": "^0.1.1",
         "date-vir": "^9.1.1",
-        "device-navigation": "^5.0.0-beta.0",
+        "device-navigation": "^5.0.0",
         "json-schema-to-ts": "^3.1.1",
         "lit-css-vars": "^3.6.3",
         "object-shape-tester": "^6.15.0",
@@ -54,7 +54,7 @@
         "typed-event-target": "^4.3.3"
     },
     "devDependencies": {
-        "@augment-vir/test": "^32.3.0-beta.0",
+        "@augment-vir/test": "^32.3.0",
         "@web/dev-server-esbuild": "^2.0.0",
         "@web/test-runner": "^1.0.0",
         "@web/test-runner-commands": "^1.0.1",
@@ -64,16 +64,16 @@
         "istanbul-smart-text-reporter": "^1.1.5",
         "lucide-static": "^1.42.0",
         "markdown-code-example-inserter": "^3.0.6",
-        "theme-vir": "^29.0.0-beta.0",
+        "theme-vir": "^29.0.0",
         "typedoc": "^0.28.20",
         "typescript": "^6.0.3",
         "vite": "^8.2.2",
         "vite-tsconfig-paths": "^6.1.1"
     },
     "peerDependencies": {
-        "element-vir": "^27.0.0-beta.3",
+        "element-vir": "^27.0.0",
         "lucide-static": ">=0.460",
-        "theme-vir": "^29.0.0-beta.0"
+        "theme-vir": "^29.0.0"
     },
     "engines": {
         "node": ">=22"

package/src/elements/color/vira-all-color-space-sliders.element.ts

@@ -1,66 +0,0 @@
-/* node:coverage disable */
-
-import {getObjectTypedKeys, getObjectTypedValues} from '@augment-vir/common';
-import {colorFormatsBySpace} from '@electrovir/color/dist/data/color-class/color-formats.js';
-import {type Color} from '@electrovir/color/dist/data/color-class/color.js';
-import {css, defineElement, defineElementEvent, html, listen} from 'element-vir';
-import {ViraColorFormatSliders} from './vira-color-format-sliders.element.js';
-
-/**
- * Color sliders for all color spaces.
- *
- * @category Elements
- */
-export const ViraAllColorSpaceSliders = defineElement<{color: Readonly<Color>}>()({
-    tagName: 'vira-all-color-space-sliders',
-    styles: css`
-        :host {
-            display: flex;
-            flex-direction: column;
-            gap: 16px;
-        }
-
-        .color-space {
-            display: flex;
-            flex-wrap: wrap;
-            column-gap: 32px;
-            row-gap: 8px;
-        }
-    `,
-    events: {
-        colorChange: defineElementEvent<string>(),
-    },
-    render({inputs, dispatch, events}) {
-        const colorSpaceTemplates = getObjectTypedValues(colorFormatsBySpace).map(
-            (colorSpaceFormats) => {
-                const formatTemplates = getObjectTypedKeys(colorSpaceFormats).map(
-                    (colorFormatName) => {
-                        return html`
-                            <${ViraColorFormatSliders.assign({
-                                color: inputs.color,
-                                colorFormatName,
-                                showFormatName: true,
-                            })}
-                                ${listen(ViraColorFormatSliders.events.colorChange, (event) => {
-                                    dispatch(
-                                        new events.colorChange({
-                                            detail: event.detail,
-                                        }),
-                                    );
-                                })}
-                            ></${ViraColorFormatSliders}>
-                        `;
-                    },
-                );
-
-                return html`
-                    <section class="color-space">${formatTemplates}</section>
-                `;
-            },
-        );
-
-        return html`
-            ${colorSpaceTemplates}
-        `;
-    },
-});

package/src/elements/color/vira-all-spaces-color-picker.element.ts

@@ -1,85 +0,0 @@
-/* node:coverage disable */
-
-import {
-    type ColorSyntaxName,
-    getColorSyntaxFromCssString,
-} from '@electrovir/color/dist/data/color-class/color-formats.js';
-import {Color} from '@electrovir/color/dist/data/color-class/color.js';
-import {css, defineElement, defineElementEvent, html, listen} from 'element-vir';
-import {ViraAllColorSpaceSliders} from './vira-all-color-space-sliders.element.js';
-import {ViraColorDetails} from './vira-color-details.element.js';
-
-/**
- * A color picker element that shows sliders for all supported color spaces at once, as well as all
- * the values for all supported color spaces in a table.
- *
- * @category Elements
- */
-export const ViraAllSpacesColorPicker = defineElement<{color: string}>()({
-    tagName: 'vira-all-spaces-color-picker',
-    styles: css`
-        :host {
-            display: flex;
-            flex-direction: column;
-            gap: 16px;
-        }
-    `,
-    events: {
-        colorChange: defineElementEvent<string>(),
-    },
-    state() {
-        return {
-            inputColorString: undefined as undefined | string,
-            overrideInputColor: undefined as undefined | ColorSyntaxName,
-        };
-    },
-    render({inputs, dispatch, events, state, updateState}) {
-        const color = new Color(inputs.color);
-
-        if (state.overrideInputColor) {
-            updateState({
-                inputColorString: color.toCss()[state.overrideInputColor],
-            });
-        }
-
-        if (state.inputColorString == undefined) {
-            updateState({
-                inputColorString: inputs.color,
-            });
-        }
-
-        return html`
-            <${ViraColorDetails.assign({
-                color: inputs.color,
-                showInput: true,
-            })}
-                ${listen(ViraColorDetails.events.colorChange, (event) => {
-                    updateState({
-                        inputColorString: event.detail,
-                        overrideInputColor: undefined,
-                    });
-                    dispatch(
-                        new events.colorChange({
-                            detail: event.detail,
-                        }),
-                    );
-                })}
-            ></${ViraColorDetails}>
-            <${ViraAllColorSpaceSliders.assign({
-                color,
-            })}
-                ${listen(ViraAllColorSpaceSliders.events.colorChange, (event) => {
-                    const colorSyntax = getColorSyntaxFromCssString(state.inputColorString || '#');
-                    updateState({
-                        overrideInputColor: colorSyntax,
-                    });
-                    dispatch(
-                        new events.colorChange({
-                            detail: event.detail,
-                        }),
-                    );
-                })}
-            ></${ViraAllColorSpaceSliders}>
-        `;
-    },
-});

package/src/elements/color/vira-color-format-sliders.element.ts

@@ -1,78 +0,0 @@
-/* node:coverage disable */
-
-import {getObjectTypedKeys} from '@augment-vir/common';
-import {
-    type ColorCoordinateName,
-    type ColorFormatName,
-    colorFormats,
-} from '@electrovir/color/dist/data/color-class/color-formats.js';
-import {type Color, type ColorUpdate} from '@electrovir/color/dist/data/color-class/color.js';
-import {css, defineElement, defineElementEvent, html, listen, nothing} from 'element-vir';
-import {noNativeSpacing} from '../../styles/native-styles.js';
-import {ViraColorSlider} from './vira-color-slider.element.js';
-
-/**
- * Color sliders for all coordinates within a specific color format.
- *
- * @category Elements
- */
-export const ViraColorFormatSliders = defineElement<{
-    color: Readonly<Color>;
-    colorFormatName: ColorFormatName;
-    showFormatName: boolean;
-}>()({
-    tagName: 'vira-color-format-sliders',
-    styles: css`
-        :host {
-            display: flex;
-            flex-direction: column;
-        }
-
-        h3 {
-            ${noNativeSpacing};
-        }
-    `,
-    events: {
-        colorChange: defineElementEvent<string>(),
-    },
-    render({inputs, dispatch, events}) {
-        const colorFormat = colorFormats[inputs.colorFormatName];
-
-        const coordinateTemplates = getObjectTypedKeys(colorFormat.coords).map(
-            (colorCoordinate: ColorCoordinateName) => {
-                return html`
-                    <${ViraColorSlider.assign({
-                        color: inputs.color,
-                        colorCoordinateName: colorCoordinate,
-                        colorFormatName: inputs.colorFormatName,
-                    })}
-                        ${listen(ViraColorSlider.events.valueChange, (event) => {
-                            const newColor = inputs.color.clone();
-
-                            newColor.set({
-                                [inputs.colorFormatName]: {
-                                    [colorCoordinate]: event.detail,
-                                },
-                            } as ColorUpdate);
-                            const newValue = newColor.toCss()[colorFormat.conversionFormat];
-                            dispatch(
-                                new events.colorChange({
-                                    detail: newValue,
-                                }),
-                            );
-                        })}
-                    ></${ViraColorSlider}>
-                `;
-            },
-        );
-
-        return html`
-            ${inputs.showFormatName
-                ? html`
-                      <h3>${inputs.colorFormatName}</h3>
-                  `
-                : nothing}
-            ${coordinateTemplates}
-        `;
-    },
-});

package/src/elements/color/vira-color-slider.element.ts

@@ -1,169 +0,0 @@
-/* node:coverage disable */
-
-import {assert, assertWrap} from '@augment-vir/assert';
-import {createArray} from '@augment-vir/common';
-import {extractEventTarget} from '@augment-vir/web';
-import {
-    type ColorCoordinateName,
-    type ColorFormatDefinition,
-    type ColorFormatName,
-    colorFormats,
-} from '@electrovir/color/dist/data/color-class/color-formats.js';
-import {Color, type ColorUpdate} from '@electrovir/color/dist/data/color-class/color.js';
-import {
-    css,
-    defineElement,
-    defineElementEvent,
-    html,
-    listen,
-    onDomRendered,
-    unsafeCSS,
-} from 'element-vir';
-import {viraFontCssVars} from '../../styles/font.js';
-import {ViraInput} from '../vira-input.element.js';
-
-/**
- * A slider for a specific color coordinate in a specific color space in a specific color.
- *
- * @category Elements
- */
-export const ViraColorSlider = defineElement<{
-    color: Readonly<Color>;
-    colorFormatName: ColorFormatName;
-    colorCoordinateName: ColorCoordinateName;
-}>()({
-    tagName: 'vira-color-slider',
-    cssVars: {
-        'vira-color-slider-gradient': 'black',
-    },
-    styles: ({cssVars}) => {
-        return css`
-            :host {
-                display: flex;
-                align-items: center;
-                font-family: ${viraFontCssVars['vira-monospace'].value};
-                gap: 2px;
-            }
-
-            input[type='range'] {
-                flex-grow: 1;
-                appearance: none;
-                background: ${cssVars['vira-color-slider-gradient'].value};
-                height: 9px;
-                border-radius: 4px;
-                cursor: pointer;
-            }
-
-            ${ViraInput} {
-                width: 76px;
-            }
-
-            .coordinate {
-                font-size: 18px;
-                margin-top: -4px;
-            }
-        `;
-    },
-    events: {
-        valueChange: defineElementEvent<number>(),
-    },
-    render({inputs, events, dispatch, cssVars}) {
-        const formatDefinition: ColorFormatDefinition = colorFormats[inputs.colorFormatName];
-        const coordinateDefinition = formatDefinition.coords[inputs.colorCoordinateName];
-
-        if (!coordinateDefinition) {
-            throw new Error(
-                `Invalid color coordinate '${inputs.colorCoordinateName}' for color format '${inputs.colorFormatName}'`,
-            );
-        }
-
-        const totalStops = 10;
-
-        const colorStops: string[] = createArray(totalStops, (index) => {
-            const value =
-                coordinateDefinition.min +
-                (coordinateDefinition.max - coordinateDefinition.min) * (index / totalStops);
-
-            const stopColor = new Color({
-                [inputs.colorFormatName]: {
-                    ...inputs.color[inputs.colorFormatName],
-                    [inputs.colorCoordinateName]: value,
-                },
-            } as ColorUpdate);
-
-            return stopColor.toCss()[formatDefinition.conversionFormat];
-        });
-
-        const gradient = css`linear-gradient(to right, ${unsafeCSS(colorStops.join(','))})`;
-
-        const coordinateValue = assertWrap.isNumber(
-            (
-                inputs.color[inputs.colorFormatName] as Record<
-                    ColorCoordinateName,
-                    undefined | string | number
-                >
-            )[inputs.colorCoordinateName],
-        );
-
-        const displayValue = coordinateDefinition.radix
-            ? Math.round(coordinateValue)
-                  .toString(coordinateDefinition.radix)
-                  .toUpperCase()
-                  .padStart(coordinateDefinition.radixPad || 0, '0')
-            : String(coordinateValue);
-
-        return html`
-            <span class="coordinate">${inputs.colorCoordinateName.toUpperCase()}</span>
-            <input
-                type="range"
-                style=${css`
-                    ${cssVars['vira-color-slider-gradient'].name}: ${gradient};
-                `}
-                step=${Math.pow(10, coordinateDefinition.digits ? -coordinateDefinition.digits : 0)}
-                ${onDomRendered((element) => {
-                    /**
-                     * We must set these imperatively to force the input element to match the
-                     * inputs, otherwise when swapping color formats these color sliders don't
-                     * update correctly.
-                     */
-                    assert.instanceOf(element, HTMLInputElement);
-
-                    element.min = String(coordinateDefinition.min);
-                    element.max = String(coordinateDefinition.max);
-                    element.value = String(coordinateValue);
-                })}
-                ${listen('input', (event) => {
-                    const element = extractEventTarget(event, HTMLInputElement);
-                    const newValue = Number(element.value);
-                    if (isNaN(newValue)) {
-                        return;
-                    }
-
-                    dispatch(
-                        new events.valueChange({
-                            detail: newValue,
-                        }),
-                    );
-                })}
-            />
-            <${ViraInput.assign({
-                value: displayValue,
-            })}
-                ${listen(ViraInput.events.valueChange, (event) => {
-                    const newValue = coordinateDefinition.radix
-                        ? parseInt(event.detail, coordinateDefinition.radix)
-                        : Number(event.detail);
-                    if (isNaN(newValue)) {
-                        return;
-                    }
-
-                    dispatch(
-                        new events.valueChange({
-                            detail: newValue,
-                        }),
-                    );
-                })}
-            ></${ViraInput}>
-        `;
-    },
-});