@space-man/react-theme-animation 2.0.0 → 2.1.0

package/dist/cjs/hooks/use-theme-animation.js

@@ -86,8 +86,8 @@ const useThemeAnimation = (props = {}) => {
             onColorThemeChange(newColorTheme);
         }
     }, [onColorThemeChange, externalColorTheme, colorStorageKey]);
-    const switchTheme = (0, react_1.useCallback)(async (newTheme) => {
-        if (!ref.current || !(0, animations_1.supportsViewTransitions)() || (0, animations_1.prefersReducedMotion)()) {
+    const switchTheme = (0, react_1.useCallback)(async (newTheme, animationOff = false) => {
+        if (!ref.current || !(0, animations_1.supportsViewTransitions)() || (0, animations_1.prefersReducedMotion)() || animationOff) {
             setTheme(newTheme);
             return;
         }
@@ -182,19 +182,19 @@ const useThemeAnimation = (props = {}) => {
         }
         setColorTheme(newColorTheme);
     }, [colorThemes, setColorTheme]);
-    const toggleTheme = (0, react_1.useCallback)(async () => {
+    const toggleTheme = (0, react_1.useCallback)(async (animationOff = false) => {
         const newTheme = resolvedTheme === 'dark' ? 'light' : 'dark';
-        await switchTheme(newTheme);
+        await switchTheme(newTheme, animationOff);
     }, [resolvedTheme, switchTheme]);
-    const toggleLightTheme = (0, react_1.useCallback)(async () => {
+    const toggleLightTheme = (0, react_1.useCallback)(async (animationOff = false) => {
         if (resolvedTheme === 'light')
             return;
-        await switchTheme('light');
+        await switchTheme('light', animationOff);
     }, [resolvedTheme, switchTheme]);
-    const toggleDarkTheme = (0, react_1.useCallback)(async () => {
+    const toggleDarkTheme = (0, react_1.useCallback)(async (animationOff = false) => {
         if (resolvedTheme === 'dark')
             return;
-        await switchTheme('dark');
+        await switchTheme('dark', animationOff);
     }, [resolvedTheme, switchTheme]);
     const toggleColorTheme = (0, react_1.useCallback)(() => {
         const currentIndex = colorThemes.indexOf(currentColorTheme);

package/dist/cjs/index.d.ts

@@ -2,6 +2,8 @@ export { useThemeAnimation } from './hooks/use-theme-animation';
 export { ThemeSwitcher } from './components/ThemeSwitcher';
 export { ThemeSelector } from './components/ThemeSelector';
 export { SpacemanThemeProvider, useSpacemanTheme } from './components/SpacemanThemeProvider';
+export { NextThemeProvider, useNextTheme } from './components/NextThemeProvider';
+export { TanStackThemeProvider, useTanStackTheme } from './components/TanStackThemeProvider';
 export { ViteThemeProvider, useViteTheme } from './components/ViteThemeProvider';
 export type { UseThemeAnimationProps, UseThemeAnimationReturn, ThemeSwitcherProps, ThemeSelectorProps, Theme, ColorTheme, SlideDirection, } from './types';
 export { ThemeAnimationType } from './types';

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.prefersReducedMotion = exports.supportsViewTransitions = exports.resolveTheme = exports.getSystemTheme = exports.injectBaseStyles = exports.ThemeAnimationType = exports.useViteTheme = exports.ViteThemeProvider = exports.useSpacemanTheme = exports.SpacemanThemeProvider = exports.ThemeSelector = exports.ThemeSwitcher = exports.useThemeAnimation = void 0;
+exports.prefersReducedMotion = exports.supportsViewTransitions = exports.resolveTheme = exports.getSystemTheme = exports.injectBaseStyles = exports.ThemeAnimationType = exports.useViteTheme = exports.ViteThemeProvider = exports.useTanStackTheme = exports.TanStackThemeProvider = exports.useNextTheme = exports.NextThemeProvider = exports.useSpacemanTheme = exports.SpacemanThemeProvider = exports.ThemeSelector = exports.ThemeSwitcher = exports.useThemeAnimation = void 0;
 var use_theme_animation_1 = require("./hooks/use-theme-animation");
 Object.defineProperty(exports, "useThemeAnimation", { enumerable: true, get: function () { return use_theme_animation_1.useThemeAnimation; } });
 var ThemeSwitcher_1 = require("./components/ThemeSwitcher");
@@ -10,6 +10,13 @@ Object.defineProperty(exports, "ThemeSelector", { enumerable: true, get: functio
 var SpacemanThemeProvider_1 = require("./components/SpacemanThemeProvider");
 Object.defineProperty(exports, "SpacemanThemeProvider", { enumerable: true, get: function () { return SpacemanThemeProvider_1.SpacemanThemeProvider; } });
 Object.defineProperty(exports, "useSpacemanTheme", { enumerable: true, get: function () { return SpacemanThemeProvider_1.useSpacemanTheme; } });
+// Framework-specific optimized providers
+var NextThemeProvider_1 = require("./components/NextThemeProvider");
+Object.defineProperty(exports, "NextThemeProvider", { enumerable: true, get: function () { return NextThemeProvider_1.NextThemeProvider; } });
+Object.defineProperty(exports, "useNextTheme", { enumerable: true, get: function () { return NextThemeProvider_1.useNextTheme; } });
+var TanStackThemeProvider_1 = require("./components/TanStackThemeProvider");
+Object.defineProperty(exports, "TanStackThemeProvider", { enumerable: true, get: function () { return TanStackThemeProvider_1.TanStackThemeProvider; } });
+Object.defineProperty(exports, "useTanStackTheme", { enumerable: true, get: function () { return TanStackThemeProvider_1.useTanStackTheme; } });
 var ViteThemeProvider_1 = require("./components/ViteThemeProvider");
 Object.defineProperty(exports, "ViteThemeProvider", { enumerable: true, get: function () { return ViteThemeProvider_1.ViteThemeProvider; } });
 Object.defineProperty(exports, "useViteTheme", { enumerable: true, get: function () { return ViteThemeProvider_1.useViteTheme; } });

package/dist/cjs/types/index.d.ts

@@ -38,11 +38,11 @@ export interface UseThemeAnimationReturn {
     resolvedTheme: 'light' | 'dark';
     setTheme: (theme: Theme) => void;
     setColorTheme: (colorTheme: ColorTheme) => void;
-    switchTheme: (theme: Theme) => Promise<void>;
+    switchTheme: (theme: Theme, animationOff?: boolean) => Promise<void>;
     switchColorTheme: (colorTheme: string) => void;
-    toggleTheme: () => Promise<void>;
-    toggleLightTheme: () => Promise<void>;
-    toggleDarkTheme: () => Promise<void>;
+    toggleTheme: (animationOff?: boolean) => Promise<void>;
+    toggleLightTheme: (animationOff?: boolean) => Promise<void>;
+    toggleDarkTheme: (animationOff?: boolean) => Promise<void>;
     toggleColorTheme: () => void;
     createColorThemeToggle: (targetColorTheme: string) => () => void;
     isColorThemeActive: (targetColorTheme: string) => boolean;

package/dist/esm/components/NextThemeProvider.d.ts

@@ -0,0 +1,81 @@
+import React, { ReactNode } from 'react';
+import { Theme, ColorTheme, ThemeAnimationType } from '../types';
+/**
+ * Context type for the Next Theme Provider
+ */
+interface NextThemeContextType {
+    ref: React.RefObject<HTMLButtonElement | null>;
+    theme: Theme;
+    colorTheme: ColorTheme;
+    resolvedTheme: 'light' | 'dark';
+    systemTheme: 'light' | 'dark';
+    setTheme: (theme: Theme) => void;
+    setColorTheme: (colorTheme: ColorTheme) => void;
+    switchTheme: (theme: Theme, animationOff?: boolean) => Promise<void>;
+    switchColorTheme: (colorTheme: string) => void;
+    toggleTheme: (animationOff?: boolean) => Promise<void>;
+    toggleLightTheme: (animationOff?: boolean) => Promise<void>;
+    toggleDarkTheme: (animationOff?: boolean) => Promise<void>;
+    toggleColorTheme: () => void;
+    createColorThemeToggle: (targetColorTheme: string) => () => void;
+    isColorThemeActive: (targetColorTheme: string) => boolean;
+    switchThemeFromElement: (theme: Theme, element: HTMLButtonElement) => Promise<void>;
+}
+/**
+ * Props for the Next Theme Provider
+ */
+interface NextThemeProviderProps {
+    children: ReactNode;
+    themes?: Theme[];
+    colorThemes?: ColorTheme[];
+    defaultTheme?: Theme;
+    defaultColorTheme?: ColorTheme;
+    animationType?: ThemeAnimationType;
+    duration?: number;
+    storageKey?: string;
+    colorStorageKey?: string;
+    attribute?: 'class' | 'data-theme';
+    globalClassName?: string;
+    colorThemePrefix?: string;
+    nonce?: string;
+    disableAnimationOnInit?: boolean;
+    disablePreHydrationScript?: boolean;
+}
+/**
+ * Next Theme Provider - Next.js optimized theme management with animations
+ *
+ * This provider is specifically optimized for Next.js and SSR frameworks with
+ * pre-hydration script injection to prevent flash of wrong theme.
+ *
+ * Features:
+ * - Pre-hydration script for flash prevention (SSR apps)
+ * - Animated theme transitions via View Transitions API
+ * - Multi-dimensional theming (theme + colorTheme)
+ * - System theme detection
+ * - CSP support via nonce prop
+ *
+ * @param children - React children to wrap with theme context
+ * @param themes - Available theme options
+ * @param colorThemes - Available color theme options
+ * @param defaultTheme - Default theme to use
+ * @param defaultColorTheme - Default color theme to use
+ * @param animationType - Animation type for theme transitions
+ * @param duration - Animation duration in milliseconds
+ * @param storageKey - LocalStorage key for theme preference
+ * @param colorStorageKey - LocalStorage key for color theme preference
+ * @param attribute - HTML attribute to use for theme ('class' or 'data-theme')
+ * @param globalClassName - Class name for dark theme (when using 'class' attribute)
+ * @param colorThemePrefix - Prefix for color theme classes
+ * @param nonce - CSP nonce for inline script (SSR apps)
+ * @param disableAnimationOnInit - Skip animation during initial hydration
+ * @param disablePreHydrationScript - Disable flash prevention script (for SPAs without SSR)
+ */
+export declare const NextThemeProvider: React.FC<NextThemeProviderProps>;
+/**
+ * Hook to consume the Next Theme context
+ *
+ * @returns Theme context value with all theme state and methods
+ * @throws Error if used outside of NextThemeProvider
+ */
+export declare const useNextTheme: () => NextThemeContextType;
+export {};

package/dist/esm/components/NextThemeProvider.js

@@ -0,0 +1,185 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { createContext, useContext, useState, useEffect, useCallback, } from 'react';
+import { useThemeAnimation } from '../hooks/use-theme-animation';
+import { ThemeAnimationType } from '../types';
+const NextThemeContext = createContext(undefined);
+/**
+ * Pre-hydration script content generator
+ * This script runs BEFORE React hydrates to prevent flash of wrong theme
+ */
+const generatePreHydrationScript = (storageKey, colorStorageKey, defaultTheme, defaultColorTheme, attribute, globalClassName, colorThemePrefix) => {
+    return `
+(function() {
+  try {
+    var theme = localStorage.getItem('${storageKey}') || '${defaultTheme}';
+    var colorTheme = localStorage.getItem('${colorStorageKey}') || '${defaultColorTheme}';
+    var resolved = theme === 'system' 
+      ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
+      : theme;
+    
+    if ('${attribute}' === 'class') {
+      if (resolved === 'dark') {
+        document.documentElement.classList.add('${globalClassName}');
+      } else {
+        document.documentElement.classList.remove('${globalClassName}');
+      }
+    } else {
+      document.documentElement.setAttribute('data-theme', resolved);
+    }
+    
+    document.documentElement.style.colorScheme = resolved;
+    document.documentElement.classList.add('${colorThemePrefix}' + colorTheme);
+  } catch (e) {
+    console.warn('Theme pre-hydration script failed:', e);
+  }
+})();
+`;
+};
+/**
+ * Pre-hydration script component
+ * Injects inline script before React hydration to prevent theme flash
+ */
+const ThemePreHydrationScript = React.memo(({ storageKey, colorStorageKey, defaultTheme, defaultColorTheme, attribute, globalClassName, colorThemePrefix, nonce, }) => {
+    const scriptContent = generatePreHydrationScript(storageKey, colorStorageKey, defaultTheme, defaultColorTheme, attribute, globalClassName, colorThemePrefix);
+    return (_jsx("script", { nonce: nonce, suppressHydrationWarning: true, dangerouslySetInnerHTML: { __html: scriptContent } }));
+});
+ThemePreHydrationScript.displayName = 'ThemePreHydrationScript';
+/**
+ * Next Theme Provider - Next.js optimized theme management with animations
+ *
+ * This provider is specifically optimized for Next.js and SSR frameworks with
+ * pre-hydration script injection to prevent flash of wrong theme.
+ *
+ * Features:
+ * - Pre-hydration script for flash prevention (SSR apps)
+ * - Animated theme transitions via View Transitions API
+ * - Multi-dimensional theming (theme + colorTheme)
+ * - System theme detection
+ * - CSP support via nonce prop
+ *
+ * @param children - React children to wrap with theme context
+ * @param themes - Available theme options
+ * @param colorThemes - Available color theme options
+ * @param defaultTheme - Default theme to use
+ * @param defaultColorTheme - Default color theme to use
+ * @param animationType - Animation type for theme transitions
+ * @param duration - Animation duration in milliseconds
+ * @param storageKey - LocalStorage key for theme preference
+ * @param colorStorageKey - LocalStorage key for color theme preference
+ * @param attribute - HTML attribute to use for theme ('class' or 'data-theme')
+ * @param globalClassName - Class name for dark theme (when using 'class' attribute)
+ * @param colorThemePrefix - Prefix for color theme classes
+ * @param nonce - CSP nonce for inline script (SSR apps)
+ * @param disableAnimationOnInit - Skip animation during initial hydration
+ * @param disablePreHydrationScript - Disable flash prevention script (for SPAs without SSR)
+ */
+export const NextThemeProvider = ({ children, themes = ['light', 'dark', 'system'], colorThemes = ['default'], defaultTheme = 'system', defaultColorTheme = 'default', animationType = ThemeAnimationType.CIRCLE, duration = 750, storageKey = 'theme', colorStorageKey = 'color-theme', attribute = 'class', globalClassName = 'dark', colorThemePrefix = 'theme-', nonce, disableAnimationOnInit = true, disablePreHydrationScript = false, }) => {
+    const [mounted, setMounted] = useState(false);
+    const themeState = useThemeAnimation({
+        themes,
+        colorThemes,
+        defaultTheme,
+        defaultColorTheme,
+        animationType,
+        duration,
+        storageKey,
+        colorStorageKey,
+        globalClassName: attribute === 'class' ? globalClassName : undefined,
+        colorThemePrefix,
+    });
+    useEffect(() => {
+        setMounted(true);
+    }, []);
+    const switchThemeWithHydrationAwareness = useCallback(async (theme, animationOff = false) => {
+        if (!mounted && disableAnimationOnInit) {
+            themeState.setTheme(theme);
+        }
+        else {
+            await themeState.switchTheme(theme, animationOff);
+        }
+    }, [mounted, disableAnimationOnInit, themeState]);
+    const switchThemeFromElement = useCallback(async (theme, element) => {
+        if (!mounted && disableAnimationOnInit) {
+            themeState.setTheme(theme);
+            return;
+        }
+        if (themeState.ref.current) {
+            const originalRef = themeState.ref.current;
+            Object.defineProperty(themeState.ref, 'current', {
+                value: element,
+                writable: true,
+                configurable: true,
+            });
+            await themeState.switchTheme(theme);
+            Object.defineProperty(themeState.ref, 'current', {
+                value: originalRef,
+                writable: true,
+                configurable: true,
+            });
+        }
+        else {
+            Object.defineProperty(themeState.ref, 'current', {
+                value: element,
+                writable: true,
+                configurable: true,
+            });
+            await themeState.switchTheme(theme);
+        }
+    }, [mounted, disableAnimationOnInit, themeState]);
+    const systemTheme = typeof window !== 'undefined' && window.matchMedia('(prefers-color-scheme: dark)').matches
+        ? 'dark'
+        : 'light';
+    if (!mounted) {
+        const loadingContextValue = {
+            ref: { current: null },
+            theme: defaultTheme,
+            colorTheme: defaultColorTheme,
+            resolvedTheme: defaultTheme === 'dark' ? 'dark' : 'light',
+            systemTheme: 'light',
+            setTheme: () => { },
+            setColorTheme: () => { },
+            switchTheme: async () => { },
+            switchThemeFromElement: async () => { },
+            switchColorTheme: () => { },
+            toggleTheme: async () => { },
+            toggleLightTheme: async () => { },
+            toggleDarkTheme: async () => { },
+            toggleColorTheme: () => { },
+            createColorThemeToggle: () => () => { },
+            isColorThemeActive: () => false,
+        };
+        return (_jsxs(NextThemeContext.Provider, { value: loadingContextValue, children: [!disablePreHydrationScript && (_jsx(ThemePreHydrationScript, { storageKey: storageKey, colorStorageKey: colorStorageKey, defaultTheme: defaultTheme, defaultColorTheme: defaultColorTheme, attribute: attribute, globalClassName: globalClassName, colorThemePrefix: colorThemePrefix, nonce: nonce })), children] }));
+    }
+    const contextValue = {
+        ref: themeState.ref,
+        theme: themeState.theme,
+        colorTheme: themeState.colorTheme,
+        resolvedTheme: themeState.resolvedTheme,
+        systemTheme,
+        setTheme: themeState.setTheme,
+        setColorTheme: themeState.setColorTheme,
+        switchTheme: switchThemeWithHydrationAwareness,
+        switchThemeFromElement,
+        switchColorTheme: themeState.switchColorTheme,
+        toggleTheme: themeState.toggleTheme,
+        toggleLightTheme: themeState.toggleLightTheme,
+        toggleDarkTheme: themeState.toggleDarkTheme,
+        toggleColorTheme: themeState.toggleColorTheme,
+        createColorThemeToggle: themeState.createColorThemeToggle,
+        isColorThemeActive: themeState.isColorThemeActive,
+    };
+    return (_jsxs(NextThemeContext.Provider, { value: contextValue, children: [!disablePreHydrationScript && (_jsx(ThemePreHydrationScript, { storageKey: storageKey, colorStorageKey: colorStorageKey, defaultTheme: defaultTheme, defaultColorTheme: defaultColorTheme, attribute: attribute, globalClassName: globalClassName, colorThemePrefix: colorThemePrefix, nonce: nonce })), children] }));
+};
+/**
+ * Hook to consume the Next Theme context
+ *
+ * @returns Theme context value with all theme state and methods
+ * @throws Error if used outside of NextThemeProvider
+ */
+export const useNextTheme = () => {
+    const context = useContext(NextThemeContext);
+    if (context === undefined) {
+        throw new Error('useNextTheme must be used within a NextThemeProvider');
+    }
+    return context;
+};

package/dist/esm/components/TanStackThemeProvider.d.ts

@@ -0,0 +1,68 @@
+import React, { ReactNode } from 'react';
+import { Theme, ColorTheme, ThemeAnimationType } from '../types';
+/**
+ * Context type for the TanStack Start Theme Provider
+ */
+interface TanStackThemeContextType {
+    ref: React.RefObject<HTMLButtonElement | null>;
+    theme: Theme;
+    colorTheme: ColorTheme;
+    resolvedTheme: 'light' | 'dark';
+    systemTheme: 'light' | 'dark';
+    isHydrated: boolean;
+    setTheme: (theme: Theme) => void;
+    setColorTheme: (colorTheme: ColorTheme) => void;
+    switchTheme: (theme: Theme, animationOff?: boolean) => Promise<void>;
+    switchColorTheme: (colorTheme: string) => void;
+    toggleTheme: (animationOff?: boolean) => Promise<void>;
+    toggleLightTheme: (animationOff?: boolean) => Promise<void>;
+    toggleDarkTheme: (animationOff?: boolean) => Promise<void>;
+    toggleColorTheme: () => void;
+    createColorThemeToggle: (targetColorTheme: string) => () => void;
+    isColorThemeActive: (targetColorTheme: string) => boolean;
+    switchThemeFromElement: (theme: Theme, element: HTMLButtonElement) => Promise<void>;
+}
+/**
+ * Props for the TanStack Start Theme Provider
+ */
+interface TanStackThemeProviderProps {
+    children: ReactNode;
+    themes?: Theme[];
+    colorThemes?: ColorTheme[];
+    defaultTheme?: Theme;
+    defaultColorTheme?: ColorTheme;
+    animationType?: ThemeAnimationType;
+    duration?: number;
+    /** Storage key for theme preference */
+    storageKey?: string;
+    /** Storage key for color theme preference */
+    colorStorageKey?: string;
+    /** Class name for dark theme */
+    globalClassName?: string;
+    /** Prefix for color theme classes */
+    colorThemePrefix?: string;
+}
+/**
+ * TanStack Start Theme Provider - Optimized for TanStack Start Framework
+ *
+ * @param children - React children to wrap with theme context
+ * @param themes - Available theme options
+ * @param colorThemes - Available color theme options
+ * @param defaultTheme - Default theme to use
+ * @param defaultColorTheme - Default color theme to use
+ * @param animationType - Animation type for theme transitions
+ * @param duration - Animation duration in milliseconds
+ * @param storageKey - LocalStorage key for theme preference
+ * @param colorStorageKey - LocalStorage key for color theme preference
+ * @param globalClassName - Class name for dark theme
+ * @param colorThemePrefix - Prefix for color theme classes
+ */
+export declare const TanStackThemeProvider: React.FC<TanStackThemeProviderProps>;
+/**
+ * Hook to consume the TanStack Theme context
+ *
+ * @returns Theme context value with all theme state and methods
+ * @throws Error if used outside of TanStackThemeProvider
+ */
+export declare const useTanStackTheme: () => TanStackThemeContextType;
+export {};

package/dist/esm/components/TanStackThemeProvider.js

@@ -0,0 +1,178 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useCallback, useSyncExternalStore, } from 'react';
+import { useThemeAnimation } from '../hooks/use-theme-animation';
+import { ThemeAnimationType } from '../types';
+const TanStackThemeContext = createContext(undefined);
+/**
+ * Custom hook to detect hydration state
+ * This is a simplified version compatible with TanStack Start's isomorphic model
+ *
+ * In TanStack Start, you can also use the built-in `useHydrated()` hook
+ * from `@tanstack/start` if available
+ */
+const useHydrated = () => {
+    return useSyncExternalStore(
+    // Subscribe function (no-op for hydration state)
+    () => () => { }, 
+    // Client snapshot: always true after hydration
+    () => true, 
+    // Server snapshot: always false during SSR
+    () => false);
+};
+/**
+ * TanStack Start Theme Provider - Optimized for TanStack Start Framework
+ *
+ * @param children - React children to wrap with theme context
+ * @param themes - Available theme options
+ * @param colorThemes - Available color theme options
+ * @param defaultTheme - Default theme to use
+ * @param defaultColorTheme - Default color theme to use
+ * @param animationType - Animation type for theme transitions
+ * @param duration - Animation duration in milliseconds
+ * @param storageKey - LocalStorage key for theme preference
+ * @param colorStorageKey - LocalStorage key for color theme preference
+ * @param globalClassName - Class name for dark theme
+ * @param colorThemePrefix - Prefix for color theme classes
+ */
+export const TanStackThemeProvider = ({ children, themes = ['light', 'dark', 'system'], colorThemes = ['default'], defaultTheme = 'system', defaultColorTheme = 'default', animationType = ThemeAnimationType.CIRCLE, duration = 750, storageKey = 'theme', colorStorageKey = 'color-theme', globalClassName = 'dark', colorThemePrefix = 'theme-', }) => {
+    const isHydrated = useHydrated();
+    const themeState = useThemeAnimation({
+        themes,
+        colorThemes,
+        defaultTheme,
+        defaultColorTheme,
+        animationType,
+        duration,
+        storageKey,
+        colorStorageKey,
+        globalClassName,
+        colorThemePrefix,
+    });
+    // Hydration-aware theme switch: instant during hydration, animated after
+    const switchThemeWithHydrationAwareness = useCallback(async (theme, animationOff = false) => {
+        if (!isHydrated) {
+            // During hydration: instant switch, no animation
+            themeState.setTheme(theme);
+        }
+        else {
+            // After hydration: animated switch
+            await themeState.switchTheme(theme, animationOff);
+        }
+    }, [isHydrated, themeState]);
+    const toggleThemeWithHydrationAwareness = useCallback(async (animationOff = false) => {
+        if (!isHydrated) {
+            const nextTheme = themeState.resolvedTheme === 'dark' ? 'light' : 'dark';
+            themeState.setTheme(nextTheme);
+        }
+        else {
+            await themeState.toggleTheme(animationOff);
+        }
+    }, [isHydrated, themeState]);
+    const toggleLightThemeWithHydrationAwareness = useCallback(async (animationOff = false) => {
+        if (!isHydrated) {
+            themeState.setTheme('light');
+        }
+        else {
+            await themeState.toggleLightTheme(animationOff);
+        }
+    }, [isHydrated, themeState]);
+    const toggleDarkThemeWithHydrationAwareness = useCallback(async (animationOff = false) => {
+        if (!isHydrated) {
+            themeState.setTheme('dark');
+        }
+        else {
+            await themeState.toggleDarkTheme(animationOff);
+        }
+    }, [isHydrated, themeState]);
+    const switchThemeFromElement = useCallback(async (theme, element) => {
+        if (!isHydrated) {
+            themeState.setTheme(theme);
+            return;
+        }
+        if (themeState.ref.current) {
+            const originalRef = themeState.ref.current;
+            Object.defineProperty(themeState.ref, 'current', {
+                value: element,
+                writable: true,
+                configurable: true,
+            });
+            await themeState.switchTheme(theme);
+            Object.defineProperty(themeState.ref, 'current', {
+                value: originalRef,
+                writable: true,
+                configurable: true,
+            });
+        }
+        else {
+            Object.defineProperty(themeState.ref, 'current', {
+                value: element,
+                writable: true,
+                configurable: true,
+            });
+            await themeState.switchTheme(theme);
+        }
+    }, [isHydrated, themeState]);
+    const systemTheme = typeof window !== 'undefined' && window.matchMedia('(prefers-color-scheme: dark)').matches
+        ? 'dark'
+        : 'light';
+    // During SSR/hydration: provide safe context without animations
+    if (!isHydrated) {
+        const loadingContextValue = {
+            ref: { current: null },
+            theme: defaultTheme,
+            colorTheme: defaultColorTheme,
+            resolvedTheme: defaultTheme === 'dark' ? 'dark' : 'light',
+            systemTheme: 'light',
+            isHydrated: false,
+            setTheme: themeState.setTheme,
+            setColorTheme: themeState.setColorTheme,
+            switchTheme: async (theme, animationOff = false) => themeState.setTheme(theme),
+            switchThemeFromElement: async (theme) => themeState.setTheme(theme),
+            switchColorTheme: themeState.switchColorTheme,
+            toggleTheme: async (animationOff = false) => {
+                const nextTheme = themeState.resolvedTheme === 'dark' ? 'light' : 'dark';
+                themeState.setTheme(nextTheme);
+            },
+            toggleLightTheme: async (animationOff = false) => themeState.setTheme('light'),
+            toggleDarkTheme: async (animationOff = false) => themeState.setTheme('dark'),
+            toggleColorTheme: themeState.toggleColorTheme,
+            createColorThemeToggle: themeState.createColorThemeToggle,
+            isColorThemeActive: themeState.isColorThemeActive,
+        };
+        return (_jsx(TanStackThemeContext.Provider, { value: loadingContextValue, children: children }));
+    }
+    // After hydration: full context with animations enabled
+    const contextValue = {
+        ref: themeState.ref,
+        theme: themeState.theme,
+        colorTheme: themeState.colorTheme,
+        resolvedTheme: themeState.resolvedTheme,
+        systemTheme,
+        isHydrated: true,
+        setTheme: themeState.setTheme,
+        setColorTheme: themeState.setColorTheme,
+        switchTheme: switchThemeWithHydrationAwareness,
+        switchThemeFromElement,
+        switchColorTheme: themeState.switchColorTheme,
+        toggleTheme: toggleThemeWithHydrationAwareness,
+        toggleLightTheme: toggleLightThemeWithHydrationAwareness,
+        toggleDarkTheme: toggleDarkThemeWithHydrationAwareness,
+        toggleColorTheme: themeState.toggleColorTheme,
+        createColorThemeToggle: themeState.createColorThemeToggle,
+        isColorThemeActive: themeState.isColorThemeActive,
+    };
+    return (_jsx(TanStackThemeContext.Provider, { value: contextValue, children: children }));
+};
+/**
+ * Hook to consume the TanStack Theme context
+ *
+ * @returns Theme context value with all theme state and methods
+ * @throws Error if used outside of TanStackThemeProvider
+ */
+export const useTanStackTheme = () => {
+    const context = useContext(TanStackThemeContext);
+    if (context === undefined) {
+        throw new Error('useTanStackTheme must be used within a TanStackThemeProvider');
+    }
+    return context;
+};

package/dist/esm/components/ViteThemeProvider.d.ts

@@ -8,11 +8,11 @@ interface ViteThemeContextType {
     systemTheme: 'light' | 'dark';
     setTheme: (theme: Theme) => void;
     setColorTheme: (colorTheme: ColorTheme) => void;
-    switchTheme: (theme: Theme) => Promise<void>;
+    switchTheme: (theme: Theme, animationOff?: boolean) => Promise<void>;
     switchColorTheme: (colorTheme: string) => void;
-    toggleTheme: () => Promise<void>;
-    toggleLightTheme: () => Promise<void>;
-    toggleDarkTheme: () => Promise<void>;
+    toggleTheme: (animationOff?: boolean) => Promise<void>;
+    toggleLightTheme: (animationOff?: boolean) => Promise<void>;
+    toggleDarkTheme: (animationOff?: boolean) => Promise<void>;
     toggleColorTheme: () => void;
     createColorThemeToggle: (targetColorTheme: string) => () => void;
     isColorThemeActive: (targetColorTheme: string) => boolean;
@@ -33,6 +33,29 @@ interface ViteThemeProviderProps {
     globalClassName?: string;
     colorThemePrefix?: string;
 }
+/**
+ * Vite Theme Provider - Optimized for Vite SPA applications
+ *
+ * This provider is designed for Vite-based single-page applications with optional
+ * transition disabling to prevent flash during theme switches.
+ *
+ * Note: For flash prevention on initial load, add a script to your index.html
+ * or inject it via Vite plugin to apply theme before React loads.
+ *
+ * @param children - React children to wrap with theme context
+ * @param themes - Available theme options
+ * @param colorThemes - Available color theme options
+ * @param defaultTheme - Default theme to use
+ * @param defaultColorTheme - Default color theme to use
+ * @param animationType - Animation type for theme transitions
+ * @param duration - Animation duration in milliseconds
+ * @param attribute - HTML attribute to use for theme ('class' or 'data-theme')
+ * @param disableTransitionOnChange - Temporarily disable CSS transitions during theme switch
+ * @param storageKey - LocalStorage key for theme preference
+ * @param colorStorageKey - LocalStorage key for color theme preference
+ * @param globalClassName - Class name for dark theme (when using 'class' attribute)
+ * @param colorThemePrefix - Prefix for color theme classes
+ */
 export declare const ViteThemeProvider: React.FC<ViteThemeProviderProps>;
 export declare const useViteTheme: () => ViteThemeContextType;
 export {};