@shohojdhara/atomix 0.3.0 → 0.3.1

package/src/lib/theme/ThemeProvider.tsx

@@ -4,10 +4,11 @@
  * React context provider for theme management
  */
 
-import React, { useState, useEffect, useCallback, useMemo } from 'react';
+import React, { useState, useEffect, useCallback, useMemo, useRef } from 'react';
 import { ThemeManager } from './ThemeManager';
 import { ThemeContext } from './ThemeContext';
-import type { ThemeProviderProps, ThemeMetadata } from './types';
+import type { ThemeProviderProps, ThemeMetadata, Theme } from './types';
+import { isJSTheme } from './themeUtils';
 
 /**
  * ThemeProvider component
@@ -46,11 +47,51 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({
     onThemeChange,
     onError,
 }) => {
-    // Initialize theme manager
+    // Store callbacks in refs to avoid recreating ThemeManager when they change
+    const onThemeChangeRef = useRef(onThemeChange);
+    const onErrorRef = useRef(onError);
+
+    // Update refs when callbacks change
+    useEffect(() => {
+        onThemeChangeRef.current = onThemeChange;
+        onErrorRef.current = onError;
+    }, [onThemeChange, onError]);
+
+    // Create stable wrapper functions that read from refs
+    const handleThemeChange = useCallback((theme: string | Theme) => {
+        onThemeChangeRef.current?.(theme);
+    }, []);
+
+    const handleError = useCallback((error: Error, themeName: string) => {
+        onErrorRef.current?.(error, themeName);
+    }, []);
+
+    // Stabilize themes object reference to prevent unnecessary recreations
+    const themesRef = useRef(themes);
+    const themesStable = useMemo(() => {
+        // Only update if themes object actually changed (shallow comparison)
+        const currentKeys = Object.keys(themes);
+        const prevKeys = Object.keys(themesRef.current);
+        
+        if (currentKeys.length !== prevKeys.length) {
+            themesRef.current = themes;
+            return themes;
+        }
+        
+        const hasChanged = currentKeys.some(key => themes[key] !== themesRef.current[key]);
+        if (hasChanged) {
+            themesRef.current = themes;
+            return themes;
+        }
+        
+        return themesRef.current;
+    }, [themes]);
+
+    // Initialize theme manager (only recreate when config changes, not callbacks)
     const themeManager = useMemo(() => {
         try {
             return new ThemeManager({
-                themes,
+                themes: themesStable,
                 defaultTheme,
                 basePath,
                 cdnPath,
@@ -60,19 +101,73 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({
                 dataAttribute,
                 enablePersistence,
                 useMinified,
-                onThemeChange,
-                onError,
+                onThemeChange: handleThemeChange,
+                onError: handleError,
             });
         } catch (error) {
             console.error('Failed to initialize ThemeManager:', error);
             // Return a minimal fallback manager
-            return new ThemeManager({
-                themes: { [defaultTheme]: { name: defaultTheme } },
-                defaultTheme,
-            });
+            const fallbackThemes: Record<string, ThemeMetadata> = {};
+            let fallbackDefault: string | Theme | undefined = defaultTheme;
+
+            if (typeof defaultTheme === 'string') {
+                // If defaultTheme is a string, add it to fallback themes
+                fallbackThemes[defaultTheme] = { name: defaultTheme };
+            } else if (defaultTheme && typeof defaultTheme === 'object') {
+                // If defaultTheme is a Theme object, add it to fallback themes map
+                // so it can be looked up by name later (e.g., getThemeMetadata, validateTheme)
+                const themeName = defaultTheme.name || 'custom-theme';
+                // Extract ThemeMetadata properties from Theme object (Theme extends ThemeMetadata)
+                // Use themeName (with fallback) instead of defaultTheme.name directly to ensure name is always a string
+                fallbackThemes[themeName] = {
+                    name: themeName,
+                    class: defaultTheme.class,
+                    description: defaultTheme.description,
+                    author: defaultTheme.author,
+                    version: defaultTheme.version,
+                    tags: defaultTheme.tags,
+                    supportsDarkMode: defaultTheme.supportsDarkMode,
+                    status: defaultTheme.status,
+                    a11y: defaultTheme.a11y,
+                    color: defaultTheme.color,
+                    features: defaultTheme.features,
+                    dependencies: defaultTheme.dependencies,
+                };
+                // Keep the Theme object as defaultTheme for ThemeManager
+                fallbackDefault = defaultTheme;
+            } else {
+                // If defaultTheme is undefined, create a minimal fallback theme
+                // to prevent ThemeManager from throwing an error
+                const fallbackThemeName = 'fallback-theme';
+                fallbackThemes[fallbackThemeName] = { name: fallbackThemeName };
+                fallbackDefault = fallbackThemeName;
+            }
+
+            try {
+                return new ThemeManager({
+                    themes: fallbackThemes,
+                    defaultTheme: fallbackDefault,
+                    basePath,
+                    cdnPath,
+                    preload,
+                    lazy,
+                    storageKey,
+                    dataAttribute,
+                    enablePersistence,
+                    useMinified,
+                    onThemeChange: handleThemeChange,
+                    onError: handleError,
+                });
+            } catch (fallbackError) {
+                // If even the fallback fails, log and throw
+                console.error('Failed to create fallback ThemeManager:', fallbackError);
+                throw new Error(
+                    'ThemeManager initialization failed. Please provide a valid themes configuration or defaultTheme.'
+                );
+            }
         }
     }, [
-        themes,
+        themesStable,
         defaultTheme,
         basePath,
         cdnPath,
@@ -82,12 +177,13 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({
         dataAttribute,
         enablePersistence,
         useMinified,
-        onThemeChange,
-        onError,
+        handleThemeChange,
+        handleError,
     ]);
 
     // State
     const [currentTheme, setCurrentTheme] = useState<string>(themeManager.getTheme());
+    const [activeTheme, setActiveTheme] = useState<Theme | null>(themeManager.getActiveTheme());
     const [isLoading, setIsLoading] = useState<boolean>(false);
     const [error, setError] = useState<Error | null>(null);
 
@@ -99,30 +195,38 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({
 
     // Set theme function
     const setTheme = useCallback(
-        async (themeName: string, options?: { fallbackOnError?: boolean }): Promise<void> => {
+        async (themeOrName: string | Theme, options?: { fallbackOnError?: boolean }): Promise<void> => {
             setIsLoading(true);
             setError(null);
 
             try {
-                await themeManager.setTheme(themeName, options);
-                setCurrentTheme(themeName);
+                await themeManager.setTheme(themeOrName, options);
+                setCurrentTheme(themeManager.getTheme());
+                setActiveTheme(themeManager.getActiveTheme());
             } 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;
+
+                // If fallback is enabled and it's safe to fallback
+                if (options?.fallbackOnError && defaultTheme) {
+                    // Avoid infinite loops if fallback is same as current attempt
+                    const targetName = isJSTheme(themeOrName) ? themeOrName.name : themeOrName;
+                    const defName = isJSTheme(defaultTheme) ? defaultTheme.name : defaultTheme;
+
+                    if (targetName !== defName) {
+                        try {
+                            await themeManager.setTheme(defaultTheme, { fallbackOnError: false });
+                            setCurrentTheme(themeManager.getTheme());
+                            setActiveTheme(themeManager.getActiveTheme());
+                            setError(null);
+                            return;
+                        } catch (fallbackErr) {
+                            // If fallback also fails, throw original error
+                            throw error;
+                        }
                     }
                 }
-                
+
                 throw error;
             } finally {
                 setIsLoading(false);
@@ -157,6 +261,7 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({
     useEffect(() => {
         const handleThemeChange = () => {
             setCurrentTheme(themeManager.getTheme());
+            setActiveTheme(themeManager.getActiveTheme());
         };
 
         themeManager.on('themeChange', handleThemeChange);
@@ -166,22 +271,65 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({
         };
     }, [themeManager]);
 
-    // Load initial theme
+    // Track the last themeManager instance we initialized
+    const initializedManagerRef = useRef<ThemeManager | null>(null);
+
+    // Load initial theme (once per themeManager instance)
     useEffect(() => {
+        // Skip if we've already initialized this exact themeManager instance
+        if (initializedManagerRef.current === themeManager) {
+            return;
+        }
+
+        // Mark this themeManager as initialized synchronously before async work
+        // This prevents race conditions where the effect runs again before async completes
+        initializedManagerRef.current = themeManager;
+
+        let isMounted = true;
+
         const loadInitialTheme = async () => {
             setIsLoading(true);
             try {
-                await themeManager.setTheme(themeManager.getTheme());
+                // If currentTheme is set (from config/storage), use it.
+                // If activeTheme is set (from config default), use it.
+                const current = themeManager.getTheme();
+                const active = themeManager.getActiveTheme();
+
+                // Only load if theme is not already loaded
+                const isAlreadyLoaded = themeManager.isThemeLoaded(current) || (active && themeManager.isThemeLoaded(active.name || ''));
+                
+                if (!isAlreadyLoaded) {
+                    // If we have an active object, or a name, ensure it's "set" (loaded).
+                    if (active) {
+                        await themeManager.setTheme(active, { removePrevious: false });
+                    } else if (current) {
+                        await themeManager.setTheme(current, { removePrevious: false });
+                    }
+                }
+
+                // Update state even if theme was already loaded
+                if (isMounted) {
+                    setCurrentTheme(themeManager.getTheme());
+                    setActiveTheme(themeManager.getActiveTheme());
+                }
             } catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
-                setError(error);
-                console.error('Failed to load initial theme:', error);
+                if (isMounted) {
+                    setError(error);
+                    console.error('Failed to load initial theme:', error);
+                }
             } finally {
-                setIsLoading(false);
+                if (isMounted) {
+                    setIsLoading(false);
+                }
             }
         };
 
         loadInitialTheme();
+
+        return () => {
+            isMounted = false;
+        };
     }, [themeManager]);
 
     // Cleanup on unmount
@@ -195,6 +343,7 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({
     const contextValue = useMemo(
         () => ({
             theme: currentTheme,
+            activeTheme,
             setTheme,
             availableThemes,
             isLoading,
@@ -205,6 +354,7 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({
         }),
         [
             currentTheme,
+            activeTheme,
             setTheme,
             availableThemes,
             isLoading,

package/src/lib/theme/composeTheme.ts

@@ -0,0 +1,375 @@
+/**
+ * Theme Composition Utilities
+ * 
+ * Utilities for composing, merging, and extending themes.
+ */
+
+import type { Theme, ThemeOptions } from './types';
+import { createTheme } from './createTheme';
+
+// ============================================================================
+// Deep Merge Utility
+// ============================================================================
+
+/**
+ * Check if value is an object
+ */
+function isObject(item: any): item is Record<string, any> {
+    return item && typeof item === 'object' && !Array.isArray(item) && typeof item !== 'function';
+}
+
+/**
+ * Deep merge multiple objects
+ * Later objects override earlier ones
+ */
+export function deepMerge<T extends Record<string, any>>(...objects: Partial<T>[]): T {
+    if (objects.length === 0) return {} as T;
+    if (objects.length === 1) return objects[0] as T;
+
+    const [target, ...sources] = objects;
+    const result = { ...target } as T;
+
+    for (const source of sources) {
+        if (!source) continue;
+
+        for (const key in source) {
+            if (!source.hasOwnProperty(key)) continue;
+
+            const targetValue = result[key];
+            const sourceValue = source[key];
+
+            if (isObject(targetValue) && isObject(sourceValue)) {
+                // Recursively merge objects
+                result[key] = deepMerge(targetValue as any, sourceValue as any) as any;
+            } else {
+                // Override with source value
+                result[key] = sourceValue as any;
+            }
+        }
+    }
+
+    return result;
+}
+
+// ============================================================================
+// Theme Merging
+// ============================================================================
+
+/**
+ * Merge multiple theme options into a single theme options object
+ * 
+ * @param themes - Theme options to merge
+ * @returns Merged theme options
+ * 
+ * @example
+ * ```typescript
+ * const baseTheme = { palette: { primary: { main: '#000' } } };
+ * const customTheme = { palette: { secondary: { main: '#fff' } } };
+ * const merged = mergeTheme(baseTheme, customTheme);
+ * ```
+ */
+export function mergeTheme(...themes: ThemeOptions[]): ThemeOptions {
+    return deepMerge({}, ...themes);
+}
+
+/**
+ * Extend an existing theme with new options
+ * 
+ * @param baseTheme - Base theme to extend (can be Theme or ThemeOptions)
+ * @param extension - Theme options to extend with
+ * @returns New theme with extended options
+ * 
+ * @example
+ * ```typescript
+ * const base = createTheme({ palette: { primary: { main: '#000' } } });
+ * const extended = extendTheme(base, {
+ *   palette: { secondary: { main: '#fff' } }
+ * });
+ * ```
+ */
+export function extendTheme(baseTheme: Theme | ThemeOptions, extension: ThemeOptions): Theme {
+    // If baseTheme is a complete Theme, extract the options
+    const baseOptions: ThemeOptions = (baseTheme as any).__isJSTheme
+        ? extractThemeOptions(baseTheme as Theme)
+        : (baseTheme as ThemeOptions);
+
+    const merged = mergeTheme(baseOptions, extension);
+    return createTheme(merged);
+}
+
+/**
+ * Extract theme options from a complete Theme object
+ */
+function extractThemeOptions(theme: Theme): ThemeOptions {
+    return {
+        name: theme.name,
+        class: theme.class,
+        description: theme.description,
+        author: theme.author,
+        version: theme.version,
+        tags: theme.tags,
+        supportsDarkMode: theme.supportsDarkMode,
+        status: theme.status,
+        a11y: theme.a11y,
+        color: theme.color,
+        features: theme.features,
+        dependencies: theme.dependencies,
+        palette: {
+            primary: theme.palette.primary,
+            secondary: theme.palette.secondary,
+            error: theme.palette.error,
+            warning: theme.palette.warning,
+            info: theme.palette.info,
+            success: theme.palette.success,
+            background: theme.palette.background,
+            text: theme.palette.text,
+        },
+        typography: {
+            fontFamily: theme.typography.fontFamily,
+            fontSize: theme.typography.fontSize,
+            fontWeightLight: theme.typography.fontWeightLight,
+            fontWeightRegular: theme.typography.fontWeightRegular,
+            fontWeightMedium: theme.typography.fontWeightMedium,
+            fontWeightSemiBold: theme.typography.fontWeightSemiBold,
+            fontWeightBold: theme.typography.fontWeightBold,
+            h1: theme.typography.h1,
+            h2: theme.typography.h2,
+            h3: theme.typography.h3,
+            h4: theme.typography.h4,
+            h5: theme.typography.h5,
+            h6: theme.typography.h6,
+            body1: theme.typography.body1,
+            body2: theme.typography.body2,
+        },
+        shadows: theme.shadows,
+        transitions: theme.transitions,
+        zIndex: theme.zIndex,
+        custom: theme.custom,
+    };
+}
+
+// ============================================================================
+// Theme Variants
+// ============================================================================
+
+/**
+ * Create light and dark variants from a base theme
+ * 
+ * @param baseTheme - Base theme options
+ * @returns Object with light and dark theme variants
+ * 
+ * @example
+ * ```typescript
+ * const { light, dark } = createThemeVariants({
+ *   palette: { primary: { main: '#7AFFD7' } }
+ * });
+ * ```
+ */
+export function createThemeVariants(baseTheme: ThemeOptions): {
+    light: Theme;
+    dark: Theme;
+} {
+    // Light theme (use base as-is or with light adjustments)
+    const lightTheme = createTheme({
+        ...baseTheme,
+        name: `${baseTheme.name || 'Custom'} Light`,
+        supportsDarkMode: false,
+    });
+
+    // Dark theme (invert colors)
+    const darkTheme = createTheme({
+        ...baseTheme,
+        name: `${baseTheme.name || 'Custom'} Dark`,
+        supportsDarkMode: true,
+        palette: {
+            ...baseTheme.palette,
+            background: {
+                default: '#121212',
+                paper: '#1E1E1E',
+                subtle: '#2A2A2A',
+                ...baseTheme.palette?.background,
+            },
+            text: {
+                primary: 'rgba(255, 255, 255, 0.87)',
+                secondary: 'rgba(255, 255, 255, 0.6)',
+                disabled: 'rgba(255, 255, 255, 0.38)',
+                ...baseTheme.palette?.text,
+            },
+        },
+    });
+
+    return { light: lightTheme, dark: darkTheme };
+}
+
+// ============================================================================
+// Theme Overrides
+// ============================================================================
+
+/**
+ * Create a theme with specific overrides
+ * 
+ * @param baseTheme - Base theme
+ * @param overrides - Specific overrides to apply
+ * @returns New theme with overrides
+ * 
+ * @example
+ * ```typescript
+ * const theme = overrideTheme(baseTheme, {
+ *   'palette.primary.main': '#FF0000',
+ *   'typography.fontSize': 16,
+ * });
+ * ```
+ */
+export function overrideTheme(
+    baseTheme: Theme | ThemeOptions,
+    overrides: Record<string, any>
+): Theme {
+    const baseOptions: ThemeOptions = (baseTheme as any).__isJSTheme
+        ? extractThemeOptions(baseTheme as Theme)
+        : (baseTheme as ThemeOptions);
+
+    // Convert dot notation overrides to nested object
+    const nestedOverrides: any = {};
+    for (const [path, value] of Object.entries(overrides)) {
+        const keys = path.split('.');
+        let current = nestedOverrides;
+
+        for (let i = 0; i < keys.length - 1; i++) {
+            const key = keys[i] as string;
+            if (typeof key !== 'string' || key === '') {
+                throw new Error('Invalid override key in theme override: ' + String(key));
+            }
+            if (typeof current !== 'object' || current === null) {
+                throw new Error('Cannot set override for path due to non-object path segment');
+            }
+            if (!(key in current) || typeof current[key] !== 'object' || current[key] === null) {
+                current[key] = {};
+            }
+            current = current[key] as Record<string, any>;
+        }
+
+        const lastKey = keys[keys.length - 1] as string;
+        if (typeof lastKey === 'string') {
+            current[lastKey] = value;
+        }
+
+    }
+
+    return createTheme(deepMerge(baseOptions, nestedOverrides));
+}
+
+// ============================================================================
+// Theme Composition Helpers
+// ============================================================================
+
+/**
+ * Compose multiple themes by merging them in order
+ * 
+ * @param themes - Themes to compose (later themes override earlier ones)
+ * @returns Composed theme
+ * 
+ * @example
+ * ```typescript
+ * const theme = composeThemes(
+ *   baseTheme,
+ *   brandTheme,
+ *   customizationTheme
+ * );
+ * ```
+ */
+export function composeThemes(...themes: (Theme | ThemeOptions)[]): Theme {
+    const options = themes.map((theme) =>
+        (theme as any).__isJSTheme ? extractThemeOptions(theme as Theme) : (theme as ThemeOptions)
+    );
+
+    return createTheme(mergeTheme(...options));
+}
+
+/**
+ * Create a theme preset with common configurations
+ * 
+ * @param preset - Preset name
+ * @param customizations - Additional customizations
+ * @returns Theme with preset applied
+ */
+export function createThemePreset(
+    preset: 'minimal' | 'modern' | 'classic' | 'vibrant',
+    customizations?: ThemeOptions
+): Theme {
+    const presets: Record<string, ThemeOptions> = {
+        minimal: {
+            name: 'Minimal',
+            palette: {
+                primary: { main: '#000000' },
+                secondary: { main: '#FFFFFF' },
+                background: {
+                    default: '#FFFFFF',
+                    paper: '#F5F5F5',
+                    subtle: '#FAFAFA',
+                },
+            },
+            typography: {
+                fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif',
+            },
+        },
+        modern: {
+            name: 'Modern',
+            palette: {
+                primary: { main: '#7AFFD7' },
+                secondary: { main: '#FF5733' },
+                background: {
+                    default: '#FAFAFA',
+                    paper: '#FFFFFF',
+                    subtle: '#F5F5F5',
+                },
+            },
+            typography: {
+                fontFamily: '"Inter", "Roboto", sans-serif',
+            },
+        },
+        classic: {
+            name: 'Classic',
+            palette: {
+                primary: { main: '#1976D2' },
+                secondary: { main: '#DC004E' },
+                background: {
+                    default: '#FFFFFF',
+                    paper: '#F5F5F5',
+                    subtle: '#EEEEEE',
+                },
+            },
+            typography: {
+                fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
+            },
+        },
+        vibrant: {
+            name: 'Vibrant',
+            palette: {
+                primary: { main: '#FF6B6B' },
+                secondary: { main: '#4ECDC4' },
+                background: {
+                    default: '#FFF8F0',
+                    paper: '#FFFFFF',
+                    subtle: '#FFF0E0',
+                },
+            },
+            typography: {
+                fontFamily: '"Poppins", "Roboto", sans-serif',
+            },
+        },
+    };
+
+    const basePreset: ThemeOptions = (presets[preset] ?? presets['modern']) as ThemeOptions;
+    const customThemeOptions: ThemeOptions = customizations ?? ({} as ThemeOptions);
+    return createTheme(mergeTheme(basePreset, customThemeOptions));
+}
+
+export default {
+    deepMerge,
+    mergeTheme,
+    extendTheme,
+    createThemeVariants,
+    overrideTheme,
+    composeThemes,
+    createThemePreset,
+};