claritykit-svelte/dist/utils/theme.d.ts

A comprehensive Svelte component library focused on accessibility, ADHD-optimized design, developer experience, and full SSR compatibility

/**
 * Theme management utilities for ClarityKit
 * Provides robust theme switching and detection capabilities with SSR support
 */
export type Theme = 'light' | 'dark' | 'auto';
/**
 * Gets the user's preferred color scheme from the system
 * @returns 'light' or 'dark' based on system preference, defaults to 'light' for SSR
 */
export declare function getSystemTheme(): 'light' | 'dark';
/**
 * Gets the current theme preference from localStorage
 * @returns The stored theme preference or 'auto' if none is set
 */
export declare function getStoredTheme(): Theme;
/**
 * Stores the theme preference in localStorage
 * @param theme - The theme to store
 */
export declare function setStoredTheme(theme: Theme): void;
/**
 * Resolves the effective theme based on user preference and system settings
 * @param preference - The user's theme preference
 * @returns The actual theme to apply ('light' or 'dark')
 */
export declare function resolveTheme(preference: Theme): 'light' | 'dark';
/**
 * Applies the theme to the document by adding/removing CSS classes
 * @param theme - The theme to apply ('light' or 'dark')
 */
export declare function applyTheme(theme: 'light' | 'dark'): void;
/**
 * Gets the currently applied theme from the document
 * @returns The currently applied theme or environment-appropriate fallback
 */
export declare function getCurrentAppliedTheme(): 'light' | 'dark';
/**
 * Creates a media query listener for system theme changes
 * @param callback - Function to call when system theme changes
 * @returns Function to remove the listener
 */
export declare function watchSystemTheme(callback: (theme: 'light' | 'dark') => void): () => void;
/**
 * Theme manager class that handles all theme-related operations with SSR support
 */
export declare class ThemeManager {
    private currentPreference;
    private systemThemeWatcher?;
    private listeners;
    private isInitialized;
    constructor();
    /**
     * Initializes the theme manager (client-side only)
     */
    private initialize;
    /**
     * Ensures the theme manager is initialized (for lazy initialization on client)
     */
    private ensureInitialized;
    /**
     * Sets up the system theme watcher (client-side only)
     */
    private setupSystemWatcher;
    /**
     * Cleans up the system theme watcher
     */
    private cleanupSystemWatcher;
    /**
     * Updates the applied theme based on current preference
     */
    private updateTheme;
    /**
     * Applies theme and notifies listeners
     */
    private applyAndNotify;
    /**
     * Sets the theme preference
     * @param theme - The theme preference to set
     */
    setTheme(theme: Theme): void;
    /**
     * Gets the current theme preference
     * @returns The current theme preference
     */
    getThemePreference(): Theme;
    /**
     * Gets the currently applied theme
     * @returns The currently applied theme
     */
    getCurrentTheme(): 'light' | 'dark';
    /**
     * Toggles between light and dark themes
     * If current preference is 'auto', sets to the opposite of current system theme
     */
    toggleTheme(): void;
    /**
     * Adds a listener for theme changes
     * @param listener - Function to call when theme changes
     * @returns Function to remove the listener
     */
    onThemeChange(listener: (theme: 'light' | 'dark') => void): () => void;
    /**
     * Cleans up all listeners and watchers
     */
    destroy(): void;
}
/**
 * Gets the server-safe default theme for SSR rendering
 * This ensures consistent initial rendering between server and client
 * @returns Default theme for server-side rendering
 */
export declare function getSSRDefaultTheme(): 'light' | 'dark';
/**
 * Gets the default theme for the current environment
 * Uses light for SSR, but can use system preference for browser/tests
 * @returns Default theme for current environment
 */
export declare function getEnvironmentDefaultTheme(): 'light' | 'dark';
/**
 * Gets the effective theme for SSR rendering based on stored preference
 * This helps prevent hydration mismatches by using stored preference if available
 * @returns Theme to use for server-side rendering
 */
export declare function getSSRTheme(): 'light' | 'dark';
/**
 * Initializes theme on client-side after hydration
 * This should be called in onMount to ensure proper theme application after SSR
 */
export declare function initializeClientTheme(): void;
/**
 * Gets or creates the global theme manager instance
 * @returns The global theme manager
 */
export declare function getThemeManager(): ThemeManager;
/**
 * Utility function to set theme preference using the global manager
 * @param theme - The theme to set
 */
export declare function setTheme(theme: Theme): void;
/**
 * Utility function to toggle theme using the global manager
 */
export declare function toggleTheme(): void;
/**
 * Utility function to get current theme preference
 * @returns The current theme preference
 */
export declare function getThemePreference(): Theme;
/**
 * Utility function to add theme change listener
 * @param listener - Function to call when theme changes
 * @returns Function to remove the listener
 */
export declare function onThemeChange(listener: (theme: 'light' | 'dark') => void): () => void;
//# sourceMappingURL=theme.d.ts.map