flixburst-theme/dist/index.d.mts

A flexible and extensible package for theme management

/**
 * Type definition for the browser themes
 */
declare type Theme = 'light' | 'dark' | 'system';
/**
 * Configuration options for the theme hook
 */
declare type ThemeHookOptions = {
    onSystemThemeChange?: (isDark: boolean) => void;
    onThemeChange?: (theme: Theme) => void;
    initialTheme?: Theme;
};
/**
 * State and methods provided by the theme hook
 */
declare type ThemeHookState = {
    setTheme: (theme: Theme) => void;
    initializeTheme: () => void;
    theme: Theme;
};
/**
 * Parameters for setting up theme management
 */
declare type SetupThemeManagementParams = {
    onSystemThemeChange?: (isDark: boolean) => void;
    onThemeChange?: (theme: Theme) => void;
    setTheme: (theme: Theme) => void;
    initializeTheme: () => void;
};

/**
 * Gets the current system theme preference from the user's OS settings
 * @returns {boolean} true if the system prefers dark mode, false if light mode
 * @example
 * ```ts
 * const prefersDark = getSystemThemePreference();
 * if (prefersDark) {
 *   console.log('System prefers dark mode');
 * }
 * ```
 */
declare const getSystemThemePreference: () => boolean;
/**
 * Determines if dark mode should be active based on the current theme setting
 * @param theme - The theme setting to check ('dark' | 'light' | 'system')
 * @returns {boolean} true if dark mode should be active, false otherwise
 * @example
 * ```ts
 * const shouldDark = shouldUseDarkMode('system'); // Returns true if system prefers dark
 * const shouldDark = shouldUseDarkMode('dark');   // Always returns true
 * const shouldDark = shouldUseDarkMode('light');  // Always returns false
 * ```
 */
declare const shouldUseDarkMode: (theme: Theme) => boolean;
/**
 * Applies the specified theme to the DOM by adding/removing classes and attributes
 * @param isDark - Whether to apply dark mode (true) or light mode (false)
 * @example
 * ```ts
 * applyThemeToDOM(true);  // Applies dark theme
 * applyThemeToDOM(false); // Applies light theme
 * ```
 */
declare const applyThemeToDOM: (isDark: boolean) => void;
/**
 * Sets the theme in localStorage and applies it to the DOM
 * @param theme - The theme to set ('dark' | 'light' | 'system')
 * @example
 * ```ts
 * setTheme('dark');   // Sets and applies dark theme
 * setTheme('light');  // Sets and applies light theme
 * setTheme('system'); // Sets theme to follow system preference
 * ```
 */
declare const setTheme: (theme: Theme) => void;
/**
 * Initializes the theme from localStorage or falls back to system preference
 * @returns {Theme} The initialized theme ('dark' | 'light' | 'system')
 * @example
 * ```ts
 * const theme = initializeTheme();
 * console.log(`Current theme: ${theme}`);
 * ```
 */
declare const initializeTheme: () => Theme;
/**
 * Subscribes to system theme changes and calls the provided callback when changes occur
 * @param callback - Function to call when system theme changes, receives boolean indicating if dark mode is active
 * @returns {() => void} Cleanup function to remove the event listener
 * @example
 * ```ts
 * const unsubscribe = subscribeToSystemTheme((isDark) => {
 *   console.log(`System theme changed to: ${isDark ? 'dark' : 'light'}`);
 * });
 *
 * // Later, to cleanup:
 * unsubscribe();
 * ```
 */
declare const subscribeToSystemTheme: (callback: (isDark: boolean) => void) => (() => void);
/**
 * Sets up theme initialization, system theme subscription, and storage synchronization.
 * Accepts callbacks for theme changes and system theme changes.
 * Returns a cleanup function to remove event listeners.
 *
 * @param setTheme - Function to set the application's theme state.
 * @param initializeTheme - Function to initialize the theme from storage or system preference.
 * @param onThemeChange - Optional callback function called when the theme changes.
 * @param onSystemThemeChange - Optional callback function called when the system theme changes.
 * @returns {() => void} Cleanup function to remove event listeners.
 */
declare const setupThemeManagement: (params: SetupThemeManagementParams) => (() => void);

export { type SetupThemeManagementParams, type Theme, type ThemeHookOptions, type ThemeHookState, applyThemeToDOM, getSystemThemePreference, initializeTheme, setTheme, setupThemeManagement, shouldUseDarkMode, subscribeToSystemTheme };