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

A simple and highly versatile design system using element-vir.

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 {};