@shohojdhara/atomix 0.2.8 → 0.2.9

package/src/lib/theme/ThemeProvider.tsx

@@ -0,0 +1,227 @@
+/**
+ * Theme Provider
+ * 
+ * React context provider for theme management
+ */
+
+import React, { useState, useEffect, useCallback, useMemo } from 'react';
+import { ThemeManager } from './ThemeManager';
+import { ThemeContext } from './ThemeContext';
+import type { ThemeProviderProps, ThemeMetadata } from './types';
+
+/**
+ * ThemeProvider component
+ * 
+ * Provides theme context to child components and manages theme state.
+ * 
+ * @example
+ * ```tsx
+ * import { ThemeProvider } from '@shohojdhara/atomix/theme';
+ * import { themesConfig } from '@shohojdhara/atomix/themes/themes.config';
+ * 
+ * function App() {
+ *   return (
+ *     <ThemeProvider
+ *       themes={themesConfig.metadata}
+ *       defaultTheme="shaj-default"
+ *     >
+ *       <YourApp />
+ *     </ThemeProvider>
+ *   );
+ * }
+ * ```
+ */
+export const ThemeProvider: React.FC<ThemeProviderProps> = ({
+    children,
+    defaultTheme = 'shaj-default',
+    themes = {},
+    basePath = '/themes',
+    cdnPath = null,
+    preload = [],
+    lazy = true,
+    storageKey = 'atomix-theme',
+    dataAttribute = 'data-theme',
+    enablePersistence = true,
+    useMinified = false,
+    onThemeChange,
+    onError,
+}) => {
+    // Initialize theme manager
+    const themeManager = useMemo(() => {
+        try {
+            return new ThemeManager({
+                themes,
+                defaultTheme,
+                basePath,
+                cdnPath,
+                preload,
+                lazy,
+                storageKey,
+                dataAttribute,
+                enablePersistence,
+                useMinified,
+                onThemeChange,
+                onError,
+            });
+        } catch (error) {
+            console.error('Failed to initialize ThemeManager:', error);
+            // Return a minimal fallback manager
+            return new ThemeManager({
+                themes: { [defaultTheme]: { name: defaultTheme } },
+                defaultTheme,
+            });
+        }
+    }, [
+        themes,
+        defaultTheme,
+        basePath,
+        cdnPath,
+        preload,
+        lazy,
+        storageKey,
+        dataAttribute,
+        enablePersistence,
+        useMinified,
+        onThemeChange,
+        onError,
+    ]);
+
+    // State
+    const [currentTheme, setCurrentTheme] = useState<string>(themeManager.getTheme());
+    const [isLoading, setIsLoading] = useState<boolean>(false);
+    const [error, setError] = useState<Error | null>(null);
+
+    // Get available themes
+    const availableThemes = useMemo<ThemeMetadata[]>(
+        () => themeManager.getAvailableThemes(),
+        [themeManager]
+    );
+
+    // Set theme function
+    const setTheme = useCallback(
+        async (themeName: string, options?: { fallbackOnError?: boolean }): Promise<void> => {
+            setIsLoading(true);
+            setError(null);
+
+            try {
+                await themeManager.setTheme(themeName, options);
+                setCurrentTheme(themeName);
+            } catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                setError(error);
+                
+                // If fallback is enabled and theme is not default, try to fallback
+                if (options?.fallbackOnError && themeName !== defaultTheme) {
+                    try {
+                        await themeManager.setTheme(defaultTheme, { fallbackOnError: false });
+                        setCurrentTheme(defaultTheme);
+                        setError(null);
+                        return;
+                    } catch (fallbackErr) {
+                        // If fallback also fails, throw original error
+                        throw error;
+                    }
+                }
+                
+                throw error;
+            } finally {
+                setIsLoading(false);
+            }
+        },
+        [themeManager, defaultTheme]
+    );
+
+    // Check if theme is loaded
+    const isThemeLoaded = useCallback(
+        (themeName: string): boolean => {
+            return themeManager.isThemeLoaded(themeName);
+        },
+        [themeManager]
+    );
+
+    // Preload theme
+    const preloadTheme = useCallback(
+        async (themeName: string): Promise<void> => {
+            try {
+                await themeManager.preloadTheme(themeName);
+            } catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                setError(error);
+                throw error;
+            }
+        },
+        [themeManager]
+    );
+
+    // Listen for theme changes
+    useEffect(() => {
+        const handleThemeChange = () => {
+            setCurrentTheme(themeManager.getTheme());
+        };
+
+        themeManager.on('themeChange', handleThemeChange);
+
+        return () => {
+            themeManager.off('themeChange', handleThemeChange);
+        };
+    }, [themeManager]);
+
+    // Load initial theme
+    useEffect(() => {
+        const loadInitialTheme = async () => {
+            setIsLoading(true);
+            try {
+                await themeManager.setTheme(themeManager.getTheme());
+            } catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                setError(error);
+                console.error('Failed to load initial theme:', error);
+            } finally {
+                setIsLoading(false);
+            }
+        };
+
+        loadInitialTheme();
+    }, [themeManager]);
+
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            themeManager.destroy();
+        };
+    }, [themeManager]);
+
+    // Context value
+    const contextValue = useMemo(
+        () => ({
+            theme: currentTheme,
+            setTheme,
+            availableThemes,
+            isLoading,
+            error,
+            isThemeLoaded,
+            preloadTheme,
+            themeManager,
+        }),
+        [
+            currentTheme,
+            setTheme,
+            availableThemes,
+            isLoading,
+            error,
+            isThemeLoaded,
+            preloadTheme,
+            themeManager,
+        ]
+    );
+
+    return (
+        <ThemeContext.Provider value={contextValue}>
+            {children}
+        </ThemeContext.Provider>
+    );
+};
+
+ThemeProvider.displayName = 'ThemeProvider';
+
+export default ThemeProvider;

package/src/lib/theme/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Theme Module Entry Point
+ * 
+ * Exports all theme management utilities for the Atomix Design System
+ */
+
+// Core theme manager
+export { ThemeManager } from './ThemeManager';
+export { default as ThemeManagerDefault } from './ThemeManager';
+
+// React integration
+export { ThemeProvider } from './ThemeProvider';
+export { default as ThemeProviderDefault } from './ThemeProvider';
+export { useTheme } from './useTheme';
+export { default as useThemeDefault } from './useTheme';
+export { ThemeContext } from './ThemeContext';
+export { default as ThemeContextDefault } from './ThemeContext';
+
+// Types
+export type {
+    ThemeMetadata,
+    ThemeManagerConfig,
+    ThemeChangeEvent,
+    ThemeLoadOptions,
+    ThemeValidationResult,
+    ThemeManagerEvent,
+    ThemeChangeCallback,
+    ThemeLoadCallback,
+    ThemeErrorCallback,
+    ThemeEventListeners,
+    UseThemeOptions,
+    UseThemeReturn,
+    ThemeProviderProps,
+    ThemeContextValue,
+    StorageAdapter,
+} from './types';
+
+// Utilities
+export {
+    isBrowser,
+    isServer,
+    getThemeLinkId,
+    buildThemePath,
+    loadThemeCSS,
+    removeThemeCSS,
+    removeAllThemeCSS,
+    applyThemeAttributes,
+    removeThemeAttributes,
+    getCurrentThemeFromDOM,
+    getSystemTheme,
+    isThemeLoaded,
+    validateThemeMetadata,
+    isValidThemeName,
+    createLocalStorageAdapter,
+    debounce,
+} from './utils';

package/src/lib/theme/types.ts

@@ -0,0 +1,247 @@
+/**
+ * Theme Manager Type Definitions
+ * 
+ * TypeScript types and interfaces for the Atomix Design System theme management system.
+ */
+
+import type { ThemeManager as ThemeManagerType } from './ThemeManager';
+
+/**
+ * Theme metadata interface matching themes.config.js structure
+ */
+export interface ThemeMetadata {
+    /** Display name of the theme */
+    name: string;
+    /** Unique identifier/class name for the theme */
+    class?: string;
+    /** Theme description */
+    description?: string;
+    /** Theme author */
+    author?: string;
+    /** Theme version (semver) */
+    version?: string;
+    /** Theme tags for categorization */
+    tags?: string[];
+    /** Whether the theme supports dark mode */
+    supportsDarkMode?: boolean;
+    /** Theme status: stable, beta, experimental, deprecated */
+    status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
+    /** Accessibility information */
+    a11y?: {
+        /** Target contrast ratio */
+        contrastTarget?: number;
+        /** Supported color modes */
+        modes?: string[];
+    };
+    /** Primary theme color (for UI display) */
+    color?: string;
+    /** Theme features list */
+    features?: string[];
+    /** Theme dependencies (other themes required) */
+    dependencies?: string[];
+}
+
+/**
+ * Theme manager configuration options
+ */
+export interface ThemeManagerConfig {
+    /** Available themes metadata */
+    themes: Record<string, ThemeMetadata>;
+    /** Default theme to use */
+    defaultTheme?: string;
+    /** Base path for theme CSS files */
+    basePath?: string;
+    /** CDN path for theme CSS files (optional) */
+    cdnPath?: string | null;
+    /** Themes to preload on initialization */
+    preload?: string[];
+    /** Enable lazy loading of themes */
+    lazy?: boolean;
+    /** localStorage key for persistence */
+    storageKey?: string;
+    /** Data attribute name for theme */
+    dataAttribute?: string;
+    /** Enable persistence */
+    enablePersistence?: boolean;
+    /** Custom CSS file extension */
+    cssExtension?: string;
+    /** Use minified CSS files */
+    useMinified?: boolean;
+    /** Callback when theme changes */
+    onThemeChange?: (theme: string) => void;
+    /** Callback when theme load fails */
+    onError?: (error: Error, themeName: string) => void;
+}
+
+/**
+ * Theme change event payload
+ */
+export interface ThemeChangeEvent {
+    /** Previous theme name */
+    previousTheme: string | null;
+    /** New theme name */
+    currentTheme: string;
+    /** Timestamp of the change */
+    timestamp: number;
+    /** Whether the change was from user action or system */
+    source: 'user' | 'system' | 'storage';
+}
+
+/**
+ * Theme load options
+ */
+export interface ThemeLoadOptions {
+    /** Force reload even if already loaded */
+    force?: boolean;
+    /** Preload without applying */
+    preload?: boolean;
+    /** Remove previous theme CSS */
+    removePrevious?: boolean;
+    /** Custom CSS path override */
+    customPath?: string;
+    /** Fallback to default theme on error */
+    fallbackOnError?: boolean;
+}
+
+/**
+ * Theme validation result
+ */
+export interface ThemeValidationResult {
+    /** Whether the theme is valid */
+    valid: boolean;
+    /** Validation errors */
+    errors: string[];
+    /** Validation warnings */
+    warnings: string[];
+}
+
+/**
+ * Theme manager event types
+ */
+export type ThemeManagerEvent = 'themeChange' | 'themeLoad' | 'themeError';
+
+/**
+ * Theme change callback function
+ */
+export type ThemeChangeCallback = (event: ThemeChangeEvent) => void;
+
+/**
+ * Theme load callback function
+ */
+export type ThemeLoadCallback = (themeName: string) => void;
+
+/**
+ * Theme error callback function
+ */
+export type ThemeErrorCallback = (error: Error, themeName: string) => void;
+
+/**
+ * Event listener map
+ */
+export interface ThemeEventListeners {
+    themeChange: ThemeChangeCallback[];
+    themeLoad: ThemeLoadCallback[];
+    themeError: ThemeErrorCallback[];
+}
+
+/**
+ * React hook options for useTheme
+ */
+export interface UseThemeOptions {
+    /** Default theme (overrides ThemeProvider default) */
+    defaultTheme?: string;
+    /** Enable persistence for this hook instance */
+    enablePersistence?: boolean;
+    /** Custom storage key */
+    storageKey?: string;
+    /** Callback when theme changes */
+    onChange?: (theme: string) => void;
+}
+
+/**
+ * React hook return type for useTheme
+ */
+export interface UseThemeReturn {
+    /** Current theme name */
+    theme: string;
+    /** Function to change theme */
+    setTheme: (theme: string, options?: ThemeLoadOptions) => Promise<void>;
+    /** Available themes */
+    availableThemes: ThemeMetadata[];
+    /** Whether a theme is currently loading */
+    isLoading: boolean;
+    /** Current error, if any */
+    error: Error | null;
+    /** Whether a specific theme is loaded */
+    isThemeLoaded: (themeName: string) => boolean;
+    /** Preload a theme */
+    preloadTheme: (themeName: string) => Promise<void>;
+}
+
+/**
+ * Theme provider props
+ */
+export interface ThemeProviderProps {
+    /** Child components */
+    children: React.ReactNode;
+    /** Default theme */
+    defaultTheme?: string;
+    /** Available themes */
+    themes?: Record<string, ThemeMetadata>;
+    /** Base path for theme CSS */
+    basePath?: string;
+    /** CDN path for theme CSS */
+    cdnPath?: string | null;
+    /** Themes to preload */
+    preload?: string[];
+    /** Enable lazy loading */
+    lazy?: boolean;
+    /** localStorage key */
+    storageKey?: string;
+    /** Data attribute name */
+    dataAttribute?: string;
+    /** Enable persistence */
+    enablePersistence?: boolean;
+    /** Use minified CSS */
+    useMinified?: boolean;
+    /** Callback when theme changes */
+    onThemeChange?: (theme: string) => void;
+    /** Callback on error */
+    onError?: (error: Error, themeName: string) => void;
+}
+
+/**
+ * Theme context value
+ */
+export interface ThemeContextValue {
+    /** Current theme */
+    theme: string;
+    /** Set theme function */
+    setTheme: (theme: string, options?: ThemeLoadOptions) => Promise<void>;
+    /** Available themes */
+    availableThemes: ThemeMetadata[];
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Check if theme is loaded */
+    isThemeLoaded: (themeName: string) => boolean;
+    /** Preload theme */
+    preloadTheme: (themeName: string) => Promise<void>;
+    /** Theme manager instance */
+    themeManager: ThemeManagerType;
+}
+
+/**
+ * Storage adapter interface for custom storage implementations
+ */
+export interface StorageAdapter {
+    /** Get item from storage */
+    getItem(key: string): string | null;
+    /** Set item in storage */
+    setItem(key: string, value: string): void;
+    /** Remove item from storage */
+    removeItem(key: string): void;
+    /** Check if storage is available */
+    isAvailable(): boolean;
+}

package/src/lib/theme/useTheme.test.tsx

@@ -0,0 +1,66 @@
+import React from 'react';
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useTheme } from './useTheme';
+import { ThemeContext } from './ThemeContext';
+import type { ThemeContextValue } from './types';
+
+describe('useTheme', () => {
+    const mockSetTheme = vi.fn(() => Promise.resolve());
+    const mockPreloadTheme = vi.fn(() => Promise.resolve());
+    const mockIsThemeLoaded = vi.fn(() => true);
+
+    const mockContextValue: ThemeContextValue = {
+        theme: 'default-theme',
+        setTheme: mockSetTheme,
+        availableThemes: [{ name: 'Default', class: 'default-theme' }],
+        isLoading: false,
+        error: null,
+        isThemeLoaded: mockIsThemeLoaded,
+        preloadTheme: mockPreloadTheme,
+        themeManager: {} as any, // We don't need the actual manager for this test
+    };
+
+    it('should throw error when used outside ThemeProvider', () => {
+        const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+
+        expect(() => {
+            renderHook(() => useTheme());
+        }).toThrow('useTheme must be used within a ThemeProvider');
+
+        consoleSpy.mockRestore();
+    });
+
+    it('should return theme context values', () => {
+        const wrapper = ({ children }: { children: React.ReactNode }) => (
+            <ThemeContext.Provider value={mockContextValue}>
+                {children}
+            </ThemeContext.Provider>
+        );
+
+        const { result } = renderHook(() => useTheme(), { wrapper });
+
+        expect(result.current.theme).toBe('default-theme');
+        expect(result.current.availableThemes).toHaveLength(1);
+        expect(result.current.isLoading).toBe(false);
+    });
+
+    it('should call onChange callback when provided', async () => {
+        const onChangeSpy = vi.fn();
+
+        const wrapper = ({ children }: { children: React.ReactNode }) => (
+            <ThemeContext.Provider value={mockContextValue}>
+                {children}
+            </ThemeContext.Provider>
+        );
+
+        const { result } = renderHook(() => useTheme({ onChange: onChangeSpy }), { wrapper });
+
+        await act(async () => {
+            await result.current.setTheme('new-theme');
+        });
+
+        expect(mockSetTheme).toHaveBeenCalledWith('new-theme');
+        expect(onChangeSpy).toHaveBeenCalledWith('new-theme');
+    });
+});

package/src/lib/theme/useTheme.ts

@@ -0,0 +1,80 @@
+/**
+ * useTheme Hook
+ * 
+ * React hook for accessing and managing theme state
+ */
+
+import { useContext, useCallback } from 'react';
+import { ThemeContext } from './ThemeContext';
+import type { UseThemeReturn, UseThemeOptions, ThemeLoadOptions } from './types';
+
+/**
+ * useTheme hook
+ * 
+ * Access theme context and manage theme state in React components.
+ * Must be used within a ThemeProvider.
+ * 
+ * @param options - Hook options
+ * @returns Theme state and methods
+ * 
+ * @example
+ * ```tsx
+ * function ThemeSwitcher() {
+ *   const { theme, setTheme, availableThemes, isLoading } = useTheme();
+ * 
+ *   return (
+ *     <select value={theme} onChange={(e) => setTheme(e.target.value)}>
+ *       {availableThemes.map(t => (
+ *         <option key={t.class} value={t.class}>{t.name}</option>
+ *       ))}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+export const useTheme = (options: UseThemeOptions = {}): UseThemeReturn => {
+    const context = useContext(ThemeContext);
+
+    if (!context) {
+        throw new Error(
+            'useTheme must be used within a ThemeProvider. ' +
+            'Wrap your component tree with <ThemeProvider> to use this hook.'
+        );
+    }
+
+    const {
+        theme,
+        setTheme: contextSetTheme,
+        availableThemes,
+        isLoading,
+        error,
+        isThemeLoaded,
+        preloadTheme,
+    } = context;
+
+    // Extract onChange callback to avoid dependency on entire options object
+    const onChange = options?.onChange;
+
+    // Wrap setTheme to call onChange callback if provided
+    const setTheme = useCallback(
+        async (themeName: string, themeOptions?: ThemeLoadOptions): Promise<void> => {
+            await contextSetTheme(themeName, themeOptions);
+            if (onChange) {
+                onChange(themeName);
+            }
+        },
+        [contextSetTheme, onChange]
+    );
+
+    return {
+        theme,
+        setTheme,
+        availableThemes,
+        isLoading,
+        error,
+        isThemeLoaded,
+        preloadTheme,
+    };
+};
+
+export default useTheme;