@shohojdhara/atomix 0.3.1 → 0.3.3

package/src/lib/theme/runtime/ThemeProvider.tsx

@@ -0,0 +1,318 @@
+/**
+ * Theme Provider
+ * 
+ * React context provider for theme management
+ * Updated to use the new ThemeEngine architecture
+ */
+
+import React, { useState, useEffect, useCallback, useMemo, useRef } from 'react';
+import { ThemeManager } from './ThemeManager';
+import { ThemeContext } from '../ThemeContext';
+import type { ThemeProviderProps, ThemeMetadata, Theme, ThemeLoadOptions } from '../types';
+import { isJSTheme } from '../themeUtils';
+import { getLogger } from '../errors';
+
+/**
+ * ThemeProvider component
+ * 
+ * Provides theme context to child components and manages theme state.
+ * Uses the new ThemeEngine-based ThemeManager.
+ * 
+ * @example
+ * ```tsx
+ * import { ThemeProvider } from '@shohojdhara/atomix/theme';
+ * 
+ * function App() {
+ *   return (
+ *     <ThemeProvider>
+ *       <YourApp />
+ *     </ThemeProvider>
+ *   );
+ * }
+ * ```
+ */
+export const ThemeProvider: React.FC<ThemeProviderProps> = ({
+    children,
+    defaultTheme,
+    themes = {},
+    basePath = '/themes',
+    cdnPath = null,
+    preload = [],
+    lazy = true,
+    storageKey = 'atomix-theme',
+    dataAttribute = 'data-theme',
+    enablePersistence = true,
+    useMinified = false,
+    onThemeChange,
+    onError,
+}) => {
+    // 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]);
+
+    const logger = useMemo(() => getLogger(), []);
+
+    // Initialize theme manager (only recreate when config changes, not callbacks)
+    const themeManager = useMemo(() => {
+        try {
+            return new ThemeManager({
+                themes: themesStable,
+                defaultTheme,
+                basePath,
+                cdnPath,
+                preload,
+                lazy,
+                storageKey,
+                dataAttribute,
+                enablePersistence,
+                useMinified,
+                onThemeChange: handleThemeChange,
+                onError: handleError,
+            });
+        } catch (error) {
+            logger.error(
+                'Failed to create ThemeManager',
+                error instanceof Error ? error : new Error(String(error)),
+                { themes: Object.keys(themesStable), defaultTheme }
+            );
+            // Return a minimal manager that won't crash
+            return new ThemeManager({
+                themes: {},
+                defaultTheme,
+                basePath,
+                storageKey,
+                enablePersistence: false,
+            });
+        }
+    }, [
+        themesStable,
+        defaultTheme,
+        basePath,
+        cdnPath,
+        preload,
+        lazy,
+        storageKey,
+        dataAttribute,
+        enablePersistence,
+        useMinified,
+        handleThemeChange,
+        handleError,
+        logger,
+    ]);
+
+    // State for React re-renders
+    const [currentTheme, setCurrentTheme] = useState<string>(() => {
+        if (typeof defaultTheme === 'string') {
+            return defaultTheme;
+        }
+        if (isJSTheme(defaultTheme)) {
+            return defaultTheme.name || 'js-theme';
+        }
+        return ''; // No default theme - use built-in styles
+    });
+
+    const [activeTheme, setActiveTheme] = useState<Theme | null>(() => {
+        if (isJSTheme(defaultTheme)) {
+            return defaultTheme;
+        }
+        return null;
+    });
+
+    const [availableThemes, setAvailableThemes] = useState<ThemeMetadata[]>(() => {
+        return themeManager.getAvailableThemes();
+    });
+
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState<Error | null>(null);
+
+    // Use refs to store stable event handlers
+    const themeChangeHandlerRef = useRef<() => void>();
+    const themeLoadHandlerRef = useRef<() => void>();
+    const themeErrorHandlerRef = useRef<(err: Error) => void>();
+
+    // Track if we've initialized to prevent loops
+    const initializedRef = useRef(false);
+
+    // Update state when theme changes
+    useEffect(() => {
+        let isMounted = true;
+
+        // Create stable handlers that use the current themeManager
+        themeChangeHandlerRef.current = () => {
+            if (!isMounted) return;
+            setCurrentTheme(prev => {
+                const current = themeManager.getTheme();
+                // Prevent unnecessary updates
+                if (current === prev) return prev;
+                return current;
+            });
+            setActiveTheme(prev => {
+                const current = themeManager.getActiveTheme();
+                // Prevent unnecessary updates by comparing references
+                if (current === prev) return prev;
+                if (!current && !prev) return prev;
+                return current;
+            });
+            setAvailableThemes(prev => {
+                const current = themeManager.getAvailableThemes();
+                // Only update if actually different
+                if (current.length !== prev.length) return current;
+                // Compare by name since ThemeMetadata doesn't have id
+                const hasChanged = current.some((t, i) => t.name !== prev[i]?.name || t.class !== prev[i]?.class);
+                return hasChanged ? current : prev;
+            });
+        };
+
+        themeLoadHandlerRef.current = () => {
+            if (!isMounted) return;
+            setCurrentTheme(prev => {
+                const current = themeManager.getTheme();
+                if (current === prev) return prev;
+                return current;
+            });
+            setActiveTheme(prev => {
+                const current = themeManager.getActiveTheme();
+                if (current === prev) return prev;
+                if (!current && !prev) return prev;
+                return current;
+            });
+        };
+
+        themeErrorHandlerRef.current = (err: Error) => {
+            if (!isMounted) return;
+            setError(err);
+            setIsLoading(false);
+        };
+
+        // Wrapper functions that call the refs
+        const onThemeChangeEvent = () => themeChangeHandlerRef.current?.();
+        const onThemeLoadEvent = () => themeLoadHandlerRef.current?.();
+        const onThemeErrorEvent = (err: Error) => themeErrorHandlerRef.current?.(err);
+
+        // Set initial state only once on first mount
+        // Use functional updates to avoid stale closures
+        if (!initializedRef.current) {
+            initializedRef.current = true;
+            // Use functional updates to get current state and compare
+            setCurrentTheme(prev => {
+                const current = themeManager.getTheme();
+                return current !== prev ? current : prev;
+            });
+            setActiveTheme(prev => {
+                const current = themeManager.getActiveTheme();
+                return current !== prev ? current : prev;
+            });
+            setAvailableThemes(prev => {
+                const current = themeManager.getAvailableThemes();
+                if (current.length !== prev.length) return current;
+                const hasChanged = current.some((t, i) => t.name !== prev[i]?.name || t.class !== prev[i]?.class);
+                return hasChanged ? current : prev;
+            });
+        }
+
+        // Register event listeners
+        themeManager.on('themeChange', onThemeChangeEvent);
+        themeManager.on('themeLoad', onThemeLoadEvent);
+        themeManager.on('themeError', onThemeErrorEvent);
+
+        return () => {
+            isMounted = false;
+            themeManager.off('themeChange', onThemeChangeEvent);
+            themeManager.off('themeLoad', onThemeLoadEvent);
+            themeManager.off('themeError', onThemeErrorEvent);
+        };
+    }, [themeManager]);
+
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            themeManager.destroy();
+        };
+    }, [themeManager]);
+
+    // Context value
+    const contextValue = useMemo(() => ({
+        theme: currentTheme,
+        activeTheme,
+        setTheme: async (theme: string | Theme, options?: ThemeLoadOptions) => {
+            setIsLoading(true);
+            setError(null);
+            try {
+                await themeManager.setTheme(theme, options);
+            } catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                setError(error);
+                throw err;
+            } finally {
+                setIsLoading(false);
+            }
+        },
+        availableThemes,
+        isLoading,
+        error,
+        isThemeLoaded: (themeName: string) => themeManager.isThemeLoaded(themeName),
+        preloadTheme: async (themeName: string) => {
+            setIsLoading(true);
+            try {
+                await themeManager.preloadTheme(themeName);
+            } catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                setError(error);
+            } finally {
+                setIsLoading(false);
+            }
+        },
+        themeManager: themeManager,
+    }), [
+        currentTheme,
+        activeTheme,
+        availableThemes,
+        isLoading,
+        error,
+        themeManager,
+    ]);
+
+    return (
+        <ThemeContext.Provider value={contextValue}>
+            {children}
+        </ThemeContext.Provider>
+    );
+};
+
+export default ThemeProvider;

package/src/lib/theme/runtime/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Theme Runtime Module
+ * 
+ * Runtime components for theme management
+ */
+
+export { ThemeManager } from './ThemeManager';
+export { ThemeProvider } from './ThemeProvider';
+export { ThemeErrorBoundary } from './ThemeErrorBoundary';
+export { useTheme } from './useTheme';
+export type { ThemeErrorBoundaryProps } from './ThemeErrorBoundary';
+
+export type {
+  ThemeManagerConfig,
+  ThemeChangeEvent,
+  ThemeLoadOptions,
+} from '../types';

package/src/lib/theme/runtime/useTheme.ts

@@ -0,0 +1,52 @@
+/**
+ * useTheme Hook
+ * 
+ * React hook for accessing theme context
+ * Updated to work with new ThemeEngine architecture
+ */
+
+import { useContext } from 'react';
+import { ThemeContext } from '../ThemeContext';
+import type { UseThemeReturn } from '../types';
+
+/**
+ * useTheme hook
+ * 
+ * Access theme context and theme management functions
+ * 
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { theme, setTheme, availableThemes } = useTheme();
+ *   
+ *   return (
+ *     <div>
+ *       <p>Current theme: {theme}</p>
+ *       <button onClick={() => setTheme('dark-theme')}>
+ *         Switch to Dark
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useTheme(): UseThemeReturn {
+    const context = useContext(ThemeContext);
+
+    if (!context) {
+        throw new Error('useTheme must be used within a ThemeProvider');
+    }
+
+    return {
+        theme: context.theme,
+        activeTheme: context.activeTheme,
+        setTheme: context.setTheme,
+        availableThemes: context.availableThemes,
+        isLoading: context.isLoading,
+        error: context.error,
+        isThemeLoaded: context.isThemeLoaded,
+        preloadTheme: context.preloadTheme,
+    };
+}
+
+export default useTheme;

package/src/lib/theme/themeUtils.ts

@@ -5,7 +5,7 @@
  * spacing helpers, and theme value accessors.
  */
 
-import type { Theme, SpacingFunction } from './types';
+import type { Theme, SpacingFunction, SpacingOptions } from './types';
 
 // ============================================================================
 // Color Manipulation Utilities
@@ -150,15 +150,37 @@ export function emphasize(color: string, coefficient: number = 0.15): string {
 // ============================================================================
 
 /**
- * Create a spacing function with a given base unit
+ * Create a spacing function from various input types
  * 
- * @param base - Base spacing unit in pixels, default 4
+ * @param spacingInput - Spacing configuration (number, array, or function), default 4
  * @returns Spacing function
  */
-export function createSpacing(base: number = 4): SpacingFunction {
+export function createSpacing(spacingInput: SpacingOptions = 4): SpacingFunction {
+    // If it's already a function, return it
+    if (typeof spacingInput === 'function') {
+        return spacingInput;
+    }
+
+    // If it's a number, create a function that multiplies by that number
+    if (typeof spacingInput === 'number') {
+        return (...values: number[]) => {
+            if (values.length === 0) return '0px';
+            return values.map((value) => `${value * spacingInput}px`).join(' ');
+        };
+    }
+
+    // If it's an array, use it as a scale
+    if (Array.isArray(spacingInput)) {
+        return (...values: number[]) => {
+            if (values.length === 0) return '0px';
+            return values.map((value) => `${spacingInput[value] || value}px`).join(' ');
+        };
+    }
+
+    // Default to 4px base
     return (...values: number[]) => {
         if (values.length === 0) return '0px';
-        return values.map((value) => `${value * base}px`).join(' ');
+        return values.map((value) => `${value * 4}px`).join(' ');
     };
 }
 

package/src/lib/theme/types.ts

@@ -4,7 +4,8 @@
  * TypeScript types and interfaces for the Atomix Design System theme management system.
  */
 
-import type { ThemeManager as ThemeManagerType } from './ThemeManager';
+import type { ThemeManager as ThemeManagerType } from './runtime/ThemeManager';
+import type { PartStyleProps } from '../types/partProps';
 
 /**
  * Theme metadata interface matching themes.config.js structure
@@ -71,6 +72,8 @@ export interface ThemeManagerConfig {
     onThemeChange?: (theme: string | Theme) => void;
     /** Callback when theme load fails */
     onError?: (error: Error, themeName: string) => void;
+    /** RTL configuration */
+    rtl?: import('./i18n/rtl').RTLConfig;
 }
 
 /**
@@ -182,6 +185,62 @@ export interface UseThemeReturn {
     preloadTheme: (themeName: string) => Promise<void>;
 }
 
+/**
+ * Component-level theme override configuration
+ */
+export interface ComponentThemeOverride {
+  /** CSS variable overrides for the component */
+  cssVars?: Record<string, string | number>;
+  
+  /** Default prop overrides */
+  defaultProps?: Record<string, any>;
+  
+  /** Part-specific overrides */
+  parts?: Record<string, {
+    cssVars?: Record<string, string | number>;
+    className?: string;
+  }>;
+  
+  /** Variant overrides */
+  variants?: Record<string, {
+    cssVars?: Record<string, string | number>;
+    className?: string;
+  }>;
+  
+  /** Additional className for the component */
+  className?: string;
+}
+
+/**
+ * Theme component overrides for all components
+ */
+export interface ThemeComponentOverrides {
+  Button?: ComponentThemeOverride;
+  Card?: ComponentThemeOverride;
+  Input?: ComponentThemeOverride;
+  Modal?: ComponentThemeOverride;
+  Dropdown?: ComponentThemeOverride;
+  Badge?: ComponentThemeOverride;
+  Tabs?: ComponentThemeOverride;
+  Progress?: ComponentThemeOverride;
+  Tooltip?: ComponentThemeOverride;
+  Select?: ComponentThemeOverride;
+  Checkbox?: ComponentThemeOverride;
+  Radio?: ComponentThemeOverride;
+  Textarea?: ComponentThemeOverride;
+  FormGroup?: ComponentThemeOverride;
+  Navbar?: ComponentThemeOverride;
+  Accordion?: ComponentThemeOverride;
+  DataTable?: ComponentThemeOverride;
+  Avatar?: ComponentThemeOverride;
+  List?: ComponentThemeOverride;
+  Popover?: ComponentThemeOverride;
+  Messages?: ComponentThemeOverride;
+  Callout?: ComponentThemeOverride;
+  Spinner?: ComponentThemeOverride;
+  [key: string]: ComponentThemeOverride | undefined;
+}
+
 /**
  * Theme provider props
  */
@@ -557,6 +616,8 @@ export interface Theme extends ThemeMetadata {
     borderRadius: Required<BorderRadiusOptions>;
     /** Custom properties */
     custom: ThemeCustomProperties;
+    /** Global CSS variables to apply */
+    cssVars?: Record<string, string | number>;
     /** Indicates this is a JS theme (not CSS-only) */
     __isJSTheme: true;
 }

package/src/lib/theme/utils.ts

@@ -6,6 +6,7 @@
  */
 
 import type { ThemeMetadata, ThemeValidationResult } from './types';
+import { THEME_LINK_ID_PREFIX } from './constants';
 
 /**
  * Check if code is running in a browser environment
@@ -25,7 +26,7 @@ export const isServer = (): boolean => {
  * Generate a unique ID for theme link elements
  */
 export const getThemeLinkId = (themeName: string): string => {
-    return `atomix-theme-${themeName}`;
+    return `${THEME_LINK_ID_PREFIX}${themeName}`;
 };
 
 /**
@@ -65,28 +66,24 @@ export const buildThemePath = (
     return `${cleanBasePath}/${cleanFileName}`;
 };
 
+
+
 /**
- * Load theme CSS file dynamically
+ * Load theme CSS from a full path
  * 
- * @param themeName - Name of the theme to load
- * @param basePath - Base path for theme files
- * @param useMinified - Whether to use minified CSS
- * @param cdnPath - Optional CDN path
+ * @param fullPath - Full path to the CSS file
+ * @param linkId - ID for the link element
  * @returns Promise that resolves when CSS is loaded
  */
 export const loadThemeCSS = (
-    themeName: string,
-    basePath: string = '/themes',
-    useMinified: boolean = false,
-    cdnPath: string | null = null
+    fullPath: string,
+    linkId: string
 ): Promise<void> => {
     if (isServer()) {
         return Promise.resolve();
     }
 
     return new Promise((resolve, reject) => {
-        const linkId = getThemeLinkId(themeName);
-
         // Check if theme is already loaded
         const existingLink = document.getElementById(linkId);
         if (existingLink) {
@@ -99,10 +96,10 @@ export const loadThemeCSS = (
         link.id = linkId;
         link.rel = 'stylesheet';
         link.type = 'text/css';
-        link.href = buildThemePath(themeName, basePath, useMinified, cdnPath);
+        link.href = fullPath;
 
         // Add data attribute for tracking
-        link.setAttribute('data-atomix-theme', themeName);
+        link.setAttribute('data-atomix-theme', 'true');
 
         // Handle load success
         link.onload = () => {
@@ -113,7 +110,7 @@ export const loadThemeCSS = (
         link.onerror = () => {
             // Remove failed link element
             link.remove();
-            reject(new Error(`Failed to load theme: ${themeName}`));
+            reject(new Error(`Failed to load theme CSS: ${fullPath}`));
         };
 
         // Append to head
@@ -124,15 +121,19 @@ export const loadThemeCSS = (
 /**
  * Remove theme CSS from the DOM
  * 
- * @param themeName - Name of the theme to remove
+ * @param themeNameOrLinkId - Name of the theme or link ID to remove
  */
-export const removeThemeCSS = (themeName: string): void => {
+export const removeThemeCSS = (themeNameOrLinkId: string): void => {
     if (isServer()) {
         return;
     }
 
-    const linkId = getThemeLinkId(themeName);
-    const link = document.getElementById(linkId);
+    // Try as link ID first, then as theme name
+    let link = document.getElementById(themeNameOrLinkId);
+    if (!link) {
+        const linkId = getThemeLinkId(themeNameOrLinkId);
+        link = document.getElementById(linkId);
+    }
 
     if (link) {
         link.remove();
@@ -154,12 +155,12 @@ export const removeAllThemeCSS = (): void => {
 /**
  * Apply theme data attributes to the document
  * 
- * @param themeName - Name of the theme
  * @param dataAttribute - Data attribute name (default: 'data-theme')
+ * @param themeName - Name of the theme
  */
 export const applyThemeAttributes = (
-    themeName: string,
-    dataAttribute: string = 'data-theme'
+    dataAttribute: string,
+    themeName: string
 ): void => {
     if (isServer()) {
         return;