vira 33.6.0 → 33.7.0

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

@@ -1,5 +1,6 @@
-import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { type MaybePromise, type PartialWithUndefined, type RequireOneOrNone } from '@augment-vir/common';
 import { LocalStorageClient } from '@electrovir/local-storage-client';
+import { ListenTarget } from 'typed-event-target';
 /**
  * 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.
@@ -11,6 +12,39 @@ export declare enum ViraThemeSelection {
     Dark = "dark",
     Auto = "auto"
 }
+declare const ViraThemeAppliedEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: ViraThemeSelection.Light | ViraThemeSelection.Dark;
+}) => import("typed-event-target").TypedCustomEvent<ViraThemeSelection.Light | ViraThemeSelection.Dark, "vira-theme-applied">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE" | "prototype"> & Pick<import("typed-event-target").TypedCustomEvent<ViraThemeSelection.Light | ViraThemeSelection.Dark, "vira-theme-applied">, "type">;
+/**
+ * Fired by {@link ViraThemeClient} whenever its applied theme changes, including when the system
+ * color scheme flips while the selection is `Auto`. Not fired when a new selection leaves the
+ * applied theme the same (such as switching from `Dark` to `Auto` on a dark system).
+ *
+ * @category Internal
+ */
+export declare class ViraThemeAppliedEvent extends ViraThemeAppliedEvent_base {
+}
+/**
+ * Persists the selection of a {@link ViraThemeClient}.
+ *
+ * @category Internal
+ */
+export type ViraThemeStorage = {
+    /** The previously saved selection. `undefined` (nothing saved yet) is treated as `Auto`. */
+    init: ViraThemeSelection | undefined;
+    /** Called after the selection has already been applied, so it can be async. */
+    save(selection: ViraThemeSelection): MaybePromise<void>;
+};
 /**
  * Used by {@link ViraThemeClient} to apply themes. By default, vira themes will be applied (via
  * {@link defaultApplyThemeCallback}).
@@ -38,6 +72,7 @@ export type ViraThemeClientParams = PartialWithUndefined<{
      * will be used.
      */
     applyTheme: ApplyThemeCallback;
+}> & RequireOneOrNone<{
     /**
      * Override the LocalStorage store name used for theme persistence. Useful if a single page
      * hosts multiple isolated theme clients.
@@ -45,6 +80,11 @@ export type ViraThemeClientParams = PartialWithUndefined<{
      * @default 'vira-theme'
      */
     storeName: string;
+    /**
+     * Where to persist the selected theme. If not provided, the selection is persisted in
+     * LocalStorage under `storeName`.
+     */
+    storage: ViraThemeStorage;
 }>;
 declare const themeStorageShapes: {
     selectedTheme: import("object-shape-tester").Shape<{
@@ -53,18 +93,25 @@ declare const themeStorageShapes: {
 };
 /**
  * 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.
+ * callback. Persists the selection through `storage` (LocalStorage by default), and listens for
+ * system color-scheme changes to re-apply the theme in auto mode without persisting. Listen for
+ * {@link ViraThemeAppliedEvent} to react to the displayed theme changing.
  *
  * The initial theme is applied during construction.
  *
  * @category Util
  */
-export declare class ViraThemeClient {
+export declare class ViraThemeClient extends ListenTarget<ViraThemeAppliedEvent> {
     /** 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>;
+    /** The default storage, only created when no `storage` param is given. */
+    protected readonly localStorageClient: LocalStorageClient<typeof themeStorageShapes> | undefined;
+    /** Persists the user's selected theme. */
+    protected readonly storage: ViraThemeStorage;
+    /** The user's selected theme. */
+    protected selectedTheme: ViraThemeSelection;
+    /** The theme that is currently displayed. */
+    protected appliedTheme: Exclude<ViraThemeSelection, ViraThemeSelection.Auto> | undefined;
     /** A callback to remove the global theme preference listener. */
     protected readonly removeThemePreferenceListener: () => void;
     constructor(params?: Readonly<ViraThemeClientParams>);
@@ -73,11 +120,13 @@ export declare class ViraThemeClient {
      * get out of sync.
      */
     getCurrentTheme(): ViraThemeSelection;
+    /** The theme that is currently displayed, with `Auto` resolved from the system color scheme. */
+    getAppliedTheme(): Exclude<ViraThemeSelection, ViraThemeSelection.Auto>;
     /** Set the selected theme. */
     setSelectedTheme(selection: ViraThemeSelection): void;
     /** Cleanup internal state and listeners. */
     destroy(): void;
-    /** Apply the currently selected theme. */
+    /** Apply the given selection and fire {@link ViraThemeAppliedEvent} if the result changed. */
     protected applySelection(selection: ViraThemeSelection): void;
 }
 export {};

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

@@ -2,7 +2,7 @@ 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 { defineTypedCustomEvent, ListenTarget, 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
@@ -16,6 +16,15 @@ export var ViraThemeSelection;
     ViraThemeSelection["Dark"] = "dark";
     ViraThemeSelection["Auto"] = "auto";
 })(ViraThemeSelection || (ViraThemeSelection = {}));
+/**
+ * Fired by {@link ViraThemeClient} whenever its applied theme changes, including when the system
+ * color scheme flips while the selection is `Auto`. Not fired when a new selection leaves the
+ * applied theme the same (such as switching from `Dark` to `Auto` on a dark system).
+ *
+ * @category Internal
+ */
+export class ViraThemeAppliedEvent extends defineTypedCustomEvent()('vira-theme-applied') {
+}
 /**
  * Default implementation of {@link ApplyThemeCallback}, which simply applies Vira themes.
  *
@@ -32,62 +41,94 @@ const themeStorageShapes = {
 };
 /**
  * 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.
+ * callback. Persists the selection through `storage` (LocalStorage by default), and listens for
+ * system color-scheme changes to re-apply the theme in auto mode without persisting. Listen for
+ * {@link ViraThemeAppliedEvent} to react to the displayed theme changing.
  *
  * The initial theme is applied during construction.
  *
  * @category Util
  */
-export class ViraThemeClient {
+export class ViraThemeClient extends ListenTarget {
     /** 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. */
+    /** The default storage, only created when no `storage` param is given. */
     localStorageClient;
+    /** Persists the user's selected theme. */
+    storage;
+    /** The user's selected theme. */
+    selectedTheme;
+    /** The theme that is currently displayed. */
+    appliedTheme;
     /** A callback to remove the global theme preference listener. */
     removeThemePreferenceListener = listenTo(globalThis.matchMedia(darkSchemeMediaQuery), 'change', (event) => {
         assert.instanceOf(event, MediaQueryListEvent);
-        if (this.getCurrentTheme() === ViraThemeSelection.Auto) {
-            void this.applyThemeCallback({
-                useDarkTheme: event.matches,
-            });
+        if (this.selectedTheme === ViraThemeSelection.Auto) {
+            this.applySelection(ViraThemeSelection.Auto);
         }
     });
     constructor(params = {}) {
+        super();
         if (params.applyTheme) {
             this.applyThemeCallback = params.applyTheme;
         }
-        this.localStorageClient = new LocalStorageClient(themeStorageShapes, {
-            storeName: params.storeName || 'vira-theme',
-        });
-        this.applySelection(this.getCurrentTheme());
+        if (params.storage) {
+            this.storage = params.storage;
+        }
+        else {
+            const localStorageClient = new LocalStorageClient(themeStorageShapes, {
+                storeName: params.storeName || 'vira-theme',
+            });
+            this.localStorageClient = localStorageClient;
+            this.storage = {
+                init: localStorageClient.get.selectedTheme()?.theme,
+                save(theme) {
+                    localStorageClient.set.selectedTheme({
+                        theme,
+                    });
+                },
+            };
+        }
+        this.selectedTheme = this.storage.init || ViraThemeSelection.Auto;
+        this.applySelection(this.selectedTheme);
     }
     /**
      * The currently selected theme. If you use multiple clients to set the same theme, this might
      * get out of sync.
      */
     getCurrentTheme() {
-        return this.localStorageClient.get.selectedTheme()?.theme || ViraThemeSelection.Auto;
+        return this.selectedTheme;
+    }
+    /** The theme that is currently displayed, with `Auto` resolved from the system color scheme. */
+    getAppliedTheme() {
+        return this.appliedTheme || ViraThemeSelection.Light;
     }
     /** Set the selected theme. */
     setSelectedTheme(selection) {
+        this.selectedTheme = selection;
         this.applySelection(selection);
-        this.localStorageClient.set.selectedTheme({
-            theme: selection,
-        });
+        void this.storage.save(selection);
     }
     /** Cleanup internal state and listeners. */
     destroy() {
         this.removeThemePreferenceListener();
-        this.localStorageClient.destroy();
+        this.localStorageClient?.destroy();
+        super.destroy();
     }
-    /** Apply the currently selected theme. */
+    /** Apply the given selection and fire {@link ViraThemeAppliedEvent} if the result changed. */
     applySelection(selection) {
         const useDarkTheme = selection === ViraThemeSelection.Dark ||
             (selection === ViraThemeSelection.Auto &&
                 globalThis.matchMedia(darkSchemeMediaQuery).matches);
+        const appliedTheme = useDarkTheme ? ViraThemeSelection.Dark : ViraThemeSelection.Light;
         void this.applyThemeCallback({
             useDarkTheme,
         });
+        if (appliedTheme !== this.appliedTheme) {
+            this.appliedTheme = appliedTheme;
+            this.dispatch(new ViraThemeAppliedEvent({
+                detail: appliedTheme,
+            }));
+        }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vira",
-    "version": "33.6.0",
+    "version": "33.7.0",
     "description": "A simple and highly versatile design system using element-vir.",
     "keywords": [
         "design",