vira 31.19.0 → 31.20.0

package/dist/elements/index.d.ts

@@ -23,3 +23,4 @@ export * from './vira-select.element.js';
 export * from './vira-tabs.element.js';
 export * from './vira-tag.element.js';
 export * from './vira-text-area.element.js';
+export * from './vira-theme-switcher.element.js';

package/dist/elements/index.js

@@ -23,3 +23,4 @@ export * from './vira-select.element.js';
 export * from './vira-tabs.element.js';
 export * from './vira-tag.element.js';
 export * from './vira-text-area.element.js';
+export * from './vira-theme-switcher.element.js';

package/dist/elements/vira-theme-switcher.element.d.ts

@@ -0,0 +1,17 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { ViraThemeClient, ViraThemeSelection } from '../util/vira-theme-client.js';
+/**
+ * A row of buttons for selecting a {@link ViraThemeSelection} (light, dark, or auto). Fires a
+ * `themeSelect` event when the user picks an option; the consumer is responsible for applying the
+ * resulting theme.
+ *
+ * @category Elements
+ */
+export declare const ViraThemeSwitcher: import("element-vir").DeclarativeElementDefinition<"vira-theme-switcher", PartialWithUndefined<{
+    themeClient: Readonly<ViraThemeClient>;
+    /** Override the default English button titles (used as `title` attributes for tooltips). */
+    labels: Readonly<Record<ViraThemeSelection, string>>;
+}>, {
+    internalThemeClient: undefined | Readonly<ViraThemeClient>;
+    currentTheme: ViraThemeSelection;
+}, {}, "vira-theme-switcher-", "vira-theme-switcher-", readonly [], readonly []>;

package/dist/elements/vira-theme-switcher.element.js

@@ -0,0 +1,104 @@
+import { mapEnumToObject } from '@augment-vir/common';
+import { classMap, css, html, listen } from 'element-vir';
+import { AutoTheme24Icon, Moon24Icon, Sun24Icon } from '../icons/index.js';
+import { viraFormCssVars } from '../styles/form-styles.js';
+import { noNativeFormStyles, noNativeSpacing, viraTheme } from '../styles/index.js';
+import { defineViraElement } from '../util/define-vira-element.js';
+import { ViraThemeClient, ViraThemeSelection } from '../util/vira-theme-client.js';
+import { ViraIcon } from './vira-icon.element.js';
+const themeIcons = mapEnumToObject(ViraThemeSelection, (theme) => {
+    const map = {
+        [ViraThemeSelection.Light]: Sun24Icon,
+        [ViraThemeSelection.Dark]: Moon24Icon,
+        [ViraThemeSelection.Auto]: AutoTheme24Icon,
+    };
+    return map[theme];
+});
+const defaultThemeLabels = {
+    [ViraThemeSelection.Light]: 'Light',
+    [ViraThemeSelection.Dark]: 'Dark',
+    [ViraThemeSelection.Auto]: 'Auto',
+};
+/**
+ * A row of buttons for selecting a {@link ViraThemeSelection} (light, dark, or auto). Fires a
+ * `themeSelect` event when the user picks an option; the consumer is responsible for applying the
+ * resulting theme.
+ *
+ * @category Elements
+ */
+export const ViraThemeSwitcher = defineViraElement()({
+    tagName: 'vira-theme-switcher',
+    styles: css `
+        :host {
+            display: inline-flex;
+            align-items: center;
+            box-sizing: border-box;
+            gap: 4px;
+        }
+
+        button {
+            ${noNativeSpacing};
+            ${noNativeFormStyles};
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            border: 1px solid transparent;
+            border-radius: ${viraFormCssVars['vira-form-radius'].value};
+            padding: 2px;
+            cursor: pointer;
+            color: ${viraTheme.colors['vira-grey-foreground-placeholder'].foreground.value};
+
+            &:hover {
+                color: ${viraFormCssVars['vira-form-accent-primary-hover-color'].value};
+                border-color: currentColor;
+            }
+
+            &.selected {
+                pointer-events: none;
+                color: ${viraFormCssVars['vira-form-accent-primary-color'].value};
+                border-color: ${viraFormCssVars['vira-form-accent-primary-color'].value};
+            }
+        }
+
+        ${ViraIcon} {
+            width: 20px;
+            aspect-ratio: 1;
+        }
+    `,
+    state() {
+        return {
+            internalThemeClient: undefined,
+            currentTheme: ViraThemeSelection.Auto,
+        };
+    },
+    render({ inputs, state, updateState }) {
+        const themeClient = inputs.themeClient || state.internalThemeClient || new ViraThemeClient();
+        updateState({
+            internalThemeClient: themeClient,
+            currentTheme: themeClient.currentTheme,
+        });
+        const labels = inputs.labels || defaultThemeLabels;
+        return Object.values(ViraThemeSelection).map((theme) => {
+            return html `
+                <button
+                    class=${classMap({
+                selected: themeClient.currentTheme === theme,
+            })}
+                    title=${labels[theme]}
+                    ${listen('click', (event) => {
+                event.stopPropagation();
+                themeClient.setSelectedTheme(theme);
+                updateState({
+                    currentTheme: themeClient.currentTheme,
+                });
+            })}
+                >
+                    <${ViraIcon.assign({
+                icon: themeIcons[theme],
+                fitContainer: true,
+            })}></${ViraIcon}>
+                </button>
+            `;
+        });
+    },
+});

package/dist/util/index.d.ts

@@ -8,3 +8,4 @@ export * from './shared-text-input-logic.js';
 export * from './vira-form-fields.js';
 export * from './vira-json-schema.js';
 export * from './vira-select-option.js';
+export * from './vira-theme-client.js';

package/dist/util/index.js

@@ -8,3 +8,4 @@ export * from './shared-text-input-logic.js';
 export * from './vira-form-fields.js';
 export * from './vira-json-schema.js';
 export * from './vira-select-option.js';
+export * from './vira-theme-client.js';

package/dist/util/overflow-observer.d.ts

@@ -2,6 +2,7 @@
  * Creates an observer that monitors whether an element's content overflows its visible width. Uses
  * a ResizeObserver for size changes and a MutationObserver for DOM content changes.
  *
+ * @category Util
  * @returns A cleanup function that disconnects all observers.
  */
 export declare function createOverflowObserver({ element, widthElement, onChange, hysteresisPx, }: Readonly<{

package/dist/util/overflow-observer.js

@@ -2,6 +2,7 @@
  * Creates an observer that monitors whether an element's content overflows its visible width. Uses
  * a ResizeObserver for size changes and a MutationObserver for DOM content changes.
  *
+ * @category Util
  * @returns A cleanup function that disconnects all observers.
  */
 export function createOverflowObserver({ element, widthElement, onChange, hysteresisPx = 0, }) {

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';
+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": "31.19.0",
+    "version": "31.20.0",
     "description": "A simple and highly versatile design system using element-vir.",
     "keywords": [
         "design",
@@ -42,10 +42,12 @@
         "@augment-vir/common": "^31.70.1",
         "@augment-vir/web": "^31.70.1",
         "@electrovir/color": "^1.7.9",
+        "@electrovir/local-storage-client": "^0.1.0",
         "date-vir": "^8.3.2",
         "device-navigation": "^4.5.5",
         "json-schema-to-ts": "^3.1.1",
         "lit-css-vars": "^3.6.2",
+        "object-shape-tester": "^6.13.0",
         "observavir": "^2.3.2",
         "page-active": "^1.0.3",
         "spa-router-vir": "^6.6.0",