vira 33.5.1 → 33.7.0

package/dist/elements/index.d.ts

@@ -33,6 +33,7 @@ export * from './vira-link.element.js';
 export * from './vira-modal.element.js';
 export * from './vira-progress.element.js';
 export * from './vira-relative-time.element.js';
+export * from './vira-slider.element.js';
 export * from './vira-tabs.element.js';
 export * from './vira-tag.element.js';
 export * from './vira-text-area.element.js';

package/dist/elements/index.js

@@ -33,6 +33,7 @@ export * from './vira-link.element.js';
 export * from './vira-modal.element.js';
 export * from './vira-progress.element.js';
 export * from './vira-relative-time.element.js';
+export * from './vira-slider.element.js';
 export * from './vira-tabs.element.js';
 export * from './vira-tag.element.js';
 export * from './vira-text-area.element.js';

package/dist/elements/vira-slider.element.d.ts

@@ -0,0 +1,35 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+/**
+ * Inputs for {@link ViraSlider}.
+ *
+ * @category Internal
+ */
+export type ViraSliderInputs = {
+    value: number;
+} & PartialWithUndefined<{
+    /** Defaults to `0`. */
+    min: number;
+    /** Defaults to `100`. */
+    max: number;
+    /** Defaults to `1`. */
+    step: number;
+    isDisabled: boolean;
+    /** The slider's accessible name. It is not rendered visibly. */
+    label: string;
+}>;
+/**
+ * A themed replacement for `<input type="range">`. The track, fill, and thumb are drawn with Vira's
+ * form colors, so they follow the current theme (including dark mode) where a browser's native
+ * range styling does not. An invisible native range input sits on top, so keyboard, pointer, and
+ * screen reader behavior are the browser's own.
+ *
+ * `valueChange` fires on every change while dragging. The slider is controlled: it only moves when
+ * `value` is updated in response.
+ *
+ * @category Input
+ * @category Elements
+ * @see https://electrovir.github.io/vira/book/elements/vira-slider
+ */
+export declare const ViraSlider: import("element-vir").DeclarativeElementDefinition<"vira-slider", Readonly<ViraSliderInputs>, {}, {
+    valueChange: import("element-vir").DefineElementEvent<number>;
+}, "vira-slider-", "vira-slider-track-height" | "vira-slider-thumb-size" | "vira-slider-track-color" | "vira-slider-fill-color" | "vira-slider-thumb-color" | "vira-slider-thumb-hover-color" | "vira-slider-thumb-active-color", readonly [], readonly []>;

package/dist/elements/vira-slider.element.js

@@ -0,0 +1,179 @@
+import { extractEventTarget } from '@augment-vir/web';
+import { classMap, css, defineElementEvent, html, ifDefined, listen } from 'element-vir';
+import { viraDisabledStyles } from '../styles/disabled.js';
+import { createFocusStyles } from '../styles/focus.js';
+import { viraFormCssVars } from '../styles/form-styles.js';
+import { defineViraElement } from '../util/define-vira-element.js';
+/**
+ * A themed replacement for `<input type="range">`. The track, fill, and thumb are drawn with Vira's
+ * form colors, so they follow the current theme (including dark mode) where a browser's native
+ * range styling does not. An invisible native range input sits on top, so keyboard, pointer, and
+ * screen reader behavior are the browser's own.
+ *
+ * `valueChange` fires on every change while dragging. The slider is controlled: it only moves when
+ * `value` is updated in response.
+ *
+ * @category Input
+ * @category Elements
+ * @see https://electrovir.github.io/vira/book/elements/vira-slider
+ */
+export const ViraSlider = defineViraElement()({
+    tagName: 'vira-slider',
+    cssVars: {
+        'vira-slider-track-height': '4px',
+        'vira-slider-thumb-size': '16px',
+        'vira-slider-track-color': viraFormCssVars['vira-form-border-color'].value,
+        'vira-slider-fill-color': viraFormCssVars['vira-form-accent-primary-color'].value,
+        'vira-slider-thumb-color': viraFormCssVars['vira-form-accent-primary-color'].value,
+        'vira-slider-thumb-hover-color': viraFormCssVars['vira-form-accent-primary-hover-color'].value,
+        'vira-slider-thumb-active-color': viraFormCssVars['vira-form-accent-primary-active-color'].value,
+    },
+    styles({ cssVars }) {
+        return css `
+            :host {
+                display: inline-flex;
+                width: 160px;
+                vertical-align: middle;
+            }
+
+            .slider {
+                position: relative;
+                flex-grow: 1;
+                height: ${cssVars['vira-slider-thumb-size'].value};
+
+                &.disabled {
+                    ${viraDisabledStyles};
+                }
+            }
+
+            .track,
+            .fill {
+                position: absolute;
+                top: 50%;
+                left: 0;
+                height: ${cssVars['vira-slider-track-height'].value};
+                transform: translateY(-50%);
+                border-radius: ${cssVars['vira-slider-track-height'].value};
+                pointer-events: none;
+            }
+
+            .track {
+                width: 100%;
+                background-color: ${cssVars['vira-slider-track-color'].value};
+            }
+
+            .fill {
+                background-color: ${cssVars['vira-slider-fill-color'].value};
+            }
+
+            .thumb {
+                position: absolute;
+                top: 0;
+                width: ${cssVars['vira-slider-thumb-size'].value};
+                height: ${cssVars['vira-slider-thumb-size'].value};
+                box-sizing: border-box;
+                border-radius: 50%;
+                border: 2px solid ${viraFormCssVars['vira-form-background-color'].value};
+                background-color: ${cssVars['vira-slider-thumb-color'].value};
+                pointer-events: none;
+            }
+
+            input {
+                position: absolute;
+                inset: 0;
+                width: 100%;
+                height: 100%;
+                margin: 0;
+                padding: 0;
+                appearance: none;
+                background: transparent;
+                opacity: 0;
+                cursor: pointer;
+
+                /*
+                    The invisible native thumb must match the drawn thumb's width so the browser
+                    maps pointer positions to the same values the drawn thumb shows.
+                */
+                &::-webkit-slider-thumb {
+                    appearance: none;
+                    width: ${cssVars['vira-slider-thumb-size'].value};
+                    height: ${cssVars['vira-slider-thumb-size'].value};
+                }
+                &::-moz-range-thumb {
+                    width: ${cssVars['vira-slider-thumb-size'].value};
+                    height: ${cssVars['vira-slider-thumb-size'].value};
+                    border: none;
+                }
+
+                &:hover ~ .thumb {
+                    background-color: ${cssVars['vira-slider-thumb-hover-color'].value};
+                }
+                &:active ~ .thumb {
+                    background-color: ${cssVars['vira-slider-thumb-active-color'].value};
+                }
+                &:focus-visible:not(:active) ~ .thumb::after {
+                    ${createFocusStyles({
+            elementBorderSize: '2px',
+            borderRadius: '50%',
+            noNesting: true,
+        })}
+                }
+            }
+        `;
+    },
+    events: {
+        valueChange: defineElementEvent(),
+    },
+    render({ inputs, dispatch, events, cssVars }) {
+        const min = inputs.min ?? 0;
+        const max = inputs.max ?? 100;
+        const fraction = max > min ? Math.min(1, Math.max(0, (inputs.value - min) / (max - min))) : 0;
+        const thumbOffset = css `calc((100% - ${cssVars['vira-slider-thumb-size'].value}) * ${fraction})`;
+        return html `
+            <div
+                class="slider ${classMap({
+            disabled: !!inputs.isDisabled,
+        })}"
+            >
+                <div class="track"></div>
+                <div
+                    class="fill"
+                    style=${css `
+                        width: calc(
+                            ${thumbOffset} + ${cssVars['vira-slider-thumb-size'].value} / 2
+                        );
+                    `}
+                ></div>
+                <input
+                    type="range"
+                    min=${min}
+                    max=${max}
+                    step=${inputs.step ?? 1}
+                    aria-label=${ifDefined(inputs.label || undefined)}
+                    ?disabled=${inputs.isDisabled}
+                    .value=${String(inputs.value)}
+                    ${listen('input', (event) => {
+            const inputElement = extractEventTarget(event, HTMLInputElement);
+            const newValue = Number(inputElement.value);
+            /**
+             * Snap the native input back to the controlled value; it only moves once
+             * the new value is assigned back in.
+             */
+            inputElement.value = String(inputs.value);
+            if (newValue !== inputs.value) {
+                dispatch(new events.valueChange({
+                    detail: newValue,
+                }));
+            }
+        })}
+                />
+                <div
+                    class="thumb"
+                    style=${css `
+                        left: ${thumbOffset};
+                    `}
+                ></div>
+            </div>
+        `;
+    },
+});

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.5.1",
+    "version": "33.7.0",
     "description": "A simple and highly versatile design system using element-vir.",
     "keywords": [
         "design",