@su-labs/theme/index.d.ts

A robust and reactive Angular service for managing application themes. It provides a full-featured solution that supports dynamic switching, user preference persistence, and automatic system theme detection.

import * as i0 from '@angular/core';
import { OnDestroy } from '@angular/core';

/** Available theme names */
type SuThemeName = 'light' | 'dark' | 'contrast' | 'custom' | 'system';
/** Theme configuration */
interface SuThemeConfig {
    /** localStorage key for storing selected theme */
    storageKey?: string;
    /** CSS variable prefix, applied to all theme variables */
    cssVarPrefix?: string;
    /** Default theme if nothing saved in localStorage */
    defaultTheme?: SuThemeName;
    /** Optional CSS variable overrides for specific themes */
    themes?: Partial<Record<SuThemeName, ThemeCssVariables>>;
}
/** Available CSS variables for theming */
interface ThemeCssVariables {
    color?: string;
    background?: string;
    'main-accent'?: string;
    'second-accent'?: string;
    'third-accent'?: string;
    [key: string]: string | undefined;
}

/**
 * Service for managing application themes.
 *
 * Provides reactive theme state via signals and methods to set/get the theme.
 * Supports user preference, system-based themes, and custom CSS variable overrides.
 */
declare class SuThemeService implements OnDestroy {
    /** Configuration for the theme, provided during initialization */
    private suThemeConfig;
    /** CSS variable prefix, can be customized */
    private cssVarPrefix;
    /** localStorage key for storing user preference, can be customized */
    private storageKey;
    /** User selected theme (can be 'system') */
    private userPreference;
    /** Current resolved theme signal ('light' | 'dark' | 'contrast' | 'custom') */
    private currentThemeSignal;
    /** Read-only access to the resolved theme signal */
    readonly theme: i0.Signal<SuThemeName>;
    /** System media query listener callback */
    private systemChangeHandler;
    /** MediaQueryList instance for system theme changes */
    private mediaQuery?;
    /**
     * Initialize the service with optional configuration.
     * Should be called from APP_INITIALIZER for default setup.
     * @param config Optional configuration object.
     */
    init(config?: SuThemeConfig): void;
    /**
     * Get the currently active, resolved theme.
     * @returns The resolved theme name ('light', 'dark', 'contrast', 'custom').
     */
    getTheme(): SuThemeName;
    /**
     * Get the user's theme preference (may be 'system').
     * @returns The user preference ('light', 'dark', 'contrast', 'custom', 'system').
     */
    getUserPreference(): SuThemeName;
    /**
     * Set a new theme.
     * @param theme The theme to set ('light', 'dark', 'contrast', 'custom', 'system').
     * @param persist Whether to store the preference in localStorage (default: true).
     */
    setTheme(theme: SuThemeName, persist?: boolean): void;
    /**
     * Resolve the current system theme using prefers-color-scheme.
     * @returns 'dark' if system prefers dark mode, otherwise 'light'.
     */
    private resolveSystemTheme;
    /**
     * Listen to system theme changes and automatically update the theme.
     * Only active when user preference is 'system'.
     */
    private listenToSystemChanges;
    /**
     * Stop listening to system theme changes.
     * Should be called when the service is destroyed or theme is no longer 'system'.
     */
    private stopListeningToSystemChanges;
    /**
     * Apply CSS variables for the given theme.
     * This method applies default variables if they are not overridden in the config.
     * @param theme The theme whose variables should be applied.
     */
    private applyThemeVariables;
    /** Angular lifecycle hook for service destruction */
    ngOnDestroy(): void;
    static ɵfac: i0.ɵɵFactoryDeclaration<SuThemeService, never>;
    static ɵprov: i0.ɵɵInjectableDeclaration<SuThemeService>;
}

export { SuThemeService };
export type { SuThemeConfig, SuThemeName, ThemeCssVariables };