@shohojdhara/atomix 0.3.1 → 0.3.3

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

@@ -0,0 +1,252 @@
+/**
+ * Theme Applicator
+ * 
+ * Applies theme configurations to the DOM, including CSS variables,
+ * component overrides, typography, spacing, and color palettes.
+ */
+
+import { applyCSSVariables, removeCSSVariables } from '../cssVariableMapper';
+import type { Theme, ThemeComponentOverrides, ComponentThemeOverride } from '../types';
+
+/**
+ * Theme applicator class for runtime theme application
+ */
+export class ThemeApplicator {
+  private appliedVars: Set<string> = new Set();
+  private root: HTMLElement;
+
+  constructor(root: HTMLElement = document.documentElement) {
+    this.root = root;
+  }
+
+  /**
+   * Apply a complete theme configuration
+   */
+  applyTheme(theme: Theme): void {
+    // Clear previously applied variables
+    this.clearAppliedVars();
+
+    // Apply global CSS variables
+    if (theme.cssVars) {
+      this.applyGlobalCSSVars(theme.cssVars);
+    }
+
+    // Apply typography system
+    if (theme.typography) {
+      this.applyTypography(theme.typography);
+    }
+
+    // Apply spacing system
+    if (theme.spacing) {
+      this.applySpacing(theme.spacing);
+    }
+
+    // Apply color palette
+    if (theme.palette) {
+      this.applyPalette(theme.palette);
+    }
+
+    // Apply component overrides
+    if (theme.components) {
+      this.applyComponentOverrides(theme.components);
+    }
+  }
+
+  /**
+   * Apply global CSS variables
+   */
+  private applyGlobalCSSVars(vars: Record<string, string | number>): void {
+    Object.entries(vars).forEach(([key, value]) => {
+      this.root.style.setProperty(key, String(value));
+      this.appliedVars.add(key);
+    });
+  }
+
+  /**
+   * Apply typography system
+   */
+  private applyTypography(typography: Theme['typography']): void {
+    if (!typography) return;
+
+    const vars: Record<string, string | number> = {};
+
+    if (typography.fontFamily) {
+      vars['--atomix-font-family'] = typography.fontFamily;
+    }
+
+    if (typography.fontSize) {
+      Object.entries(typography.fontSize).forEach(([key, value]) => {
+        vars[`--atomix-font-size-${key}`] = value;
+      });
+    }
+
+    if (typography.fontWeight) {
+      Object.entries(typography.fontWeight).forEach(([key, value]) => {
+        vars[`--atomix-font-weight-${key}`] = value;
+      });
+    }
+
+    if (typography.lineHeight) {
+      Object.entries(typography.lineHeight).forEach(([key, value]) => {
+        vars[`--atomix-line-height-${key}`] = value;
+      });
+    }
+
+    this.applyGlobalCSSVars(vars);
+  }
+
+  /**
+   * Apply spacing system
+   */
+  private applySpacing(spacing: Record<string, string | number>): void {
+    const vars: Record<string, string | number> = {};
+
+    Object.entries(spacing).forEach(([key, value]) => {
+      vars[`--atomix-space-${key}`] = value;
+    });
+
+    this.applyGlobalCSSVars(vars);
+  }
+
+  /**
+   * Apply color palette
+   */
+  private applyPalette(palette: Theme['palette']): void {
+    if (!palette) return;
+
+    const vars: Record<string, string | number> = {};
+
+    Object.entries(palette).forEach(([colorName, colorScale]) => {
+      if (colorScale) {
+        Object.entries(colorScale).forEach(([shade, value]) => {
+          if (value) {
+            vars[`--atomix-color-${colorName}-${shade}`] = value;
+          }
+        });
+      }
+    });
+
+    this.applyGlobalCSSVars(vars);
+  }
+
+  /**
+   * Apply component-level overrides
+   */
+  private applyComponentOverrides(overrides: ThemeComponentOverrides): void {
+    Object.entries(overrides).forEach(([componentName, override]) => {
+      if (override) {
+        this.applyComponentOverride(componentName, override);
+      }
+    });
+  }
+
+  /**
+   * Apply override for a specific component
+   */
+  private applyComponentOverride(
+    componentName: string,
+    override: ComponentThemeOverride
+  ): void {
+    const vars: Record<string, string | number> = {};
+    const componentKey = componentName.toLowerCase();
+
+    // Apply component-level CSS variables
+    if (override.cssVars) {
+      Object.entries(override.cssVars).forEach(([key, value]) => {
+        // If key doesn't start with --, add component prefix
+        const varKey = key.startsWith('--')
+          ? key
+          : `--atomix-${componentKey}-${key}`;
+        vars[varKey] = value;
+      });
+    }
+
+    // Apply part-specific CSS variables
+    if (override.parts) {
+      Object.entries(override.parts).forEach(([partName, partOverride]) => {
+        if (partOverride.cssVars) {
+          Object.entries(partOverride.cssVars).forEach(([key, value]) => {
+            const varKey = key.startsWith('--')
+              ? key
+              : `--atomix-${componentKey}-${partName}-${key}`;
+            vars[varKey] = value;
+          });
+        }
+      });
+    }
+
+    // Apply variant-specific CSS variables
+    if (override.variants) {
+      Object.entries(override.variants).forEach(([variantName, variantOverride]) => {
+        if (variantOverride.cssVars) {
+          Object.entries(variantOverride.cssVars).forEach(([key, value]) => {
+            const varKey = key.startsWith('--')
+              ? key
+              : `--atomix-${componentKey}-${variantName}-${key}`;
+            vars[varKey] = value;
+          });
+        }
+      });
+    }
+
+    this.applyGlobalCSSVars(vars);
+  }
+
+  /**
+   * Clear all applied CSS variables
+   */
+  private clearAppliedVars(): void {
+    removeCSSVariables(Array.from(this.appliedVars), this.root);
+    this.appliedVars.clear();
+  }
+
+  /**
+   * Get all currently applied variables
+   */
+  getAppliedVars(): string[] {
+    return Array.from(this.appliedVars);
+  }
+
+  /**
+   * Remove theme application
+   */
+  removeTheme(): void {
+    this.clearAppliedVars();
+  }
+
+  /**
+   * Update specific CSS variables without clearing all
+   */
+  updateCSSVars(vars: Record<string, string | number>): void {
+    this.applyGlobalCSSVars(vars);
+  }
+}
+
+/**
+ * Global theme applicator instance
+ */
+let globalApplicator: ThemeApplicator | null = null;
+
+/**
+ * Get or create global theme applicator
+ */
+export function getThemeApplicator(): ThemeApplicator {
+  if (!globalApplicator) {
+    globalApplicator = new ThemeApplicator();
+  }
+  return globalApplicator;
+}
+
+/**
+ * Apply theme using global applicator
+ */
+export function applyTheme(theme: Theme): void {
+  getThemeApplicator().applyTheme(theme);
+}
+
+/**
+ * Remove theme using global applicator
+ */
+export function removeTheme(): void {
+  getThemeApplicator().removeTheme();
+}

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

@@ -0,0 +1,233 @@
+/**
+ * Theme Error Boundary
+ * 
+ * React error boundary for catching and handling theme-related errors.
+ * Prevents the entire app from crashing when theme errors occur.
+ */
+
+import React, { Component, type ReactNode, type ErrorInfo } from 'react';
+import { ThemeError, ThemeErrorCode, getLogger } from '../errors';
+
+/**
+ * Error boundary state
+ */
+interface ThemeErrorBoundaryState {
+  /** Whether an error has occurred */
+  hasError: boolean;
+  /** The error that occurred */
+  error: Error | null;
+  /** Error information */
+  errorInfo: ErrorInfo | null;
+}
+
+/**
+ * Error boundary props
+ */
+export interface ThemeErrorBoundaryProps {
+  /** Child components */
+  children: ReactNode;
+  /** Fallback UI to render when error occurs */
+  fallback?: (error: Error, errorInfo: ErrorInfo) => ReactNode;
+  /** Callback when error occurs */
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+  /** Whether to reset error on children change */
+  resetOnPropsChange?: boolean;
+  /** Custom error message */
+  errorMessage?: string;
+}
+
+/**
+ * Default fallback UI
+ */
+const DefaultFallback: React.FC<{ error: Error; errorInfo: ErrorInfo }> = ({ error, errorInfo }) => {
+  const isThemeError = error instanceof ThemeError;
+  const errorCode = isThemeError ? error.code : ThemeErrorCode.UNKNOWN_ERROR;
+  const context = isThemeError ? error.context : undefined;
+
+  return (
+    <div
+      style={{
+        padding: '2rem',
+        margin: '1rem',
+        border: '1px solid #e0e0e0',
+        borderRadius: '8px',
+        backgroundColor: '#fafafa',
+        color: '#333',
+      }}
+      role="alert"
+    >
+      <h2 style={{ marginTop: 0, color: '#d32f2f' }}>Theme Error</h2>
+      <p>
+        <strong>Error:</strong> {error.message}
+      </p>
+      {isThemeError && (
+        <p>
+          <strong>Error Code:</strong> {errorCode}
+        </p>
+      )}
+      {context && Object.keys(context).length > 0 && (
+        <details style={{ marginTop: '1rem' }}>
+          <summary style={{ cursor: 'pointer', fontWeight: 'bold' }}>
+            Error Context
+          </summary>
+          <pre
+            style={{
+              marginTop: '0.5rem',
+              padding: '0.5rem',
+              backgroundColor: '#f5f5f5',
+              borderRadius: '4px',
+              overflow: 'auto',
+            }}
+          >
+            {JSON.stringify(context, null, 2)}
+          </pre>
+        </details>
+      )}
+      {process.env.NODE_ENV === 'development' && errorInfo && (
+        <details style={{ marginTop: '1rem' }}>
+          <summary style={{ cursor: 'pointer', fontWeight: 'bold' }}>
+            Stack Trace (Development Only)
+          </summary>
+          <pre
+            style={{
+              marginTop: '0.5rem',
+              padding: '0.5rem',
+              backgroundColor: '#f5f5f5',
+              borderRadius: '4px',
+              overflow: 'auto',
+              fontSize: '0.875rem',
+            }}
+          >
+            {errorInfo.componentStack}
+          </pre>
+        </details>
+      )}
+      <button
+        onClick={() => window.location.reload()}
+        style={{
+          marginTop: '1rem',
+          padding: '0.5rem 1rem',
+          backgroundColor: '#1976d2',
+          color: 'white',
+          border: 'none',
+          borderRadius: '4px',
+          cursor: 'pointer',
+        }}
+      >
+        Reload Page
+      </button>
+    </div>
+  );
+};
+
+/**
+ * Theme Error Boundary Component
+ * 
+ * Catches errors in the theme system and displays a fallback UI
+ * instead of crashing the entire application.
+ */
+export class ThemeErrorBoundary extends Component<
+  ThemeErrorBoundaryProps,
+  ThemeErrorBoundaryState
+> {
+  private logger = getLogger();
+
+  constructor(props: ThemeErrorBoundaryProps) {
+    super(props);
+    this.state = {
+      hasError: false,
+      error: null,
+      errorInfo: null,
+    };
+  }
+
+  static getDerivedStateFromError(error: Error): Partial<ThemeErrorBoundaryState> {
+    return {
+      hasError: true,
+      error,
+    };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
+    // Log error
+    const themeError = error instanceof ThemeError
+      ? error
+      : new ThemeError(
+          error.message,
+          ThemeErrorCode.UNKNOWN_ERROR,
+          { componentStack: errorInfo.componentStack }
+        );
+
+    this.logger.error(
+      'Theme error boundary caught an error',
+      themeError,
+      {
+        componentStack: errorInfo.componentStack,
+        errorBoundary: 'ThemeErrorBoundary',
+      }
+    );
+
+    // Update state with error info
+    this.setState({
+      error,
+      errorInfo,
+    });
+
+    // Call custom error handler
+    if (this.props.onError) {
+      try {
+        this.props.onError(error, errorInfo);
+      } catch (handlerError) {
+        this.logger.error(
+          'Error in onError callback',
+          handlerError instanceof Error ? handlerError : new Error(String(handlerError)),
+          { originalError: error.message }
+        );
+      }
+    }
+  }
+
+  componentDidUpdate(prevProps: ThemeErrorBoundaryProps): void {
+    // Reset error if resetOnPropsChange is true and children changed
+    if (
+      this.props.resetOnPropsChange &&
+      this.state.hasError &&
+      prevProps.children !== this.props.children
+    ) {
+      this.setState({
+        hasError: false,
+        error: null,
+        errorInfo: null,
+      });
+    }
+  }
+
+  render(): ReactNode {
+    if (this.state.hasError && this.state.error && this.state.errorInfo) {
+      // Use custom fallback if provided
+      if (this.props.fallback) {
+        return this.props.fallback(this.state.error, this.state.errorInfo);
+      }
+
+      // Use default fallback
+      return <DefaultFallback error={this.state.error} errorInfo={this.state.errorInfo} />;
+    }
+
+    return this.props.children;
+  }
+}
+
+/**
+ * Hook to reset error boundary
+ * 
+ * @param reset - Function to reset the error boundary
+ */
+export function useThemeErrorReset(): () => void {
+  return () => {
+    // This would need to be implemented with a context or ref
+    // For now, it's a placeholder
+    window.location.reload();
+  };
+}
+
+export default ThemeErrorBoundary;

package/src/lib/theme/runtime/ThemeManager.test.ts

@@ -0,0 +1,176 @@
+/**
+ * ThemeManager Tests
+ * 
+ * Tests for the ThemeManager class
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ThemeManager } from './ThemeManager';
+import { ThemeError, ThemeErrorCode } from '../errors';
+import type { ThemeMetadata } from '../types';
+
+// Mock dependencies
+vi.mock('../core/ThemeEngine');
+vi.mock('../config/loader');
+vi.mock('../utils', () => ({
+  isBrowser: () => true,
+  isServer: () => false,
+  createLocalStorageAdapter: () => ({
+    getItem: vi.fn(),
+    setItem: vi.fn(),
+    removeItem: vi.fn(),
+    isAvailable: () => true,
+  }),
+}));
+
+describe('ThemeManager', () => {
+  let themeManager: ThemeManager;
+  const mockThemes: Record<string, ThemeMetadata> = {
+    'test-theme': {
+      name: 'Test Theme',
+      class: 'test-theme',
+      description: 'A test theme',
+    },
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    if (themeManager) {
+      themeManager.destroy();
+    }
+  });
+
+  describe('constructor', () => {
+    it('should create ThemeManager with default config', () => {
+      themeManager = new ThemeManager({ themes: {} });
+      expect(themeManager).toBeInstanceOf(ThemeManager);
+    });
+
+    it('should create ThemeManager with custom config', () => {
+      themeManager = new ThemeManager({
+        themes: mockThemes,
+        basePath: '/custom-themes',
+        storageKey: 'custom-key',
+      });
+      expect(themeManager).toBeInstanceOf(ThemeManager);
+    });
+
+    it('should initialize with themes from config', () => {
+      themeManager = new ThemeManager({ themes: mockThemes });
+      const available = themeManager.getAvailableThemes();
+      expect(available.length).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe('getTheme', () => {
+    it('should return current theme', () => {
+      themeManager = new ThemeManager({ themes: mockThemes });
+      const theme = themeManager.getTheme();
+      expect(typeof theme).toBe('string');
+    });
+
+    it('should return default theme if no theme set', () => {
+      themeManager = new ThemeManager({
+        themes: mockThemes,
+        defaultTheme: 'test-theme',
+      });
+      const theme = themeManager.getTheme();
+      expect(theme).toBe('test-theme');
+    });
+  });
+
+  describe('getAvailableThemes', () => {
+    it('should return available themes', () => {
+      themeManager = new ThemeManager({ themes: mockThemes });
+      const themes = themeManager.getAvailableThemes();
+      expect(Array.isArray(themes)).toBe(true);
+    });
+  });
+
+  describe('event listeners', () => {
+    it('should add theme change listener', () => {
+      themeManager = new ThemeManager({ themes: mockThemes });
+      const listener = vi.fn();
+      themeManager.on('themeChange', listener);
+      // Note: Actual event emission would require theme switching
+      expect(() => themeManager.on('themeChange', listener)).not.toThrow();
+    });
+
+    it('should remove theme change listener', () => {
+      themeManager = new ThemeManager({ themes: mockThemes });
+      const listener = vi.fn();
+      themeManager.on('themeChange', listener);
+      themeManager.off('themeChange', listener);
+      expect(() => themeManager.off('themeChange', listener)).not.toThrow();
+    });
+
+    it('should add theme load listener', () => {
+      themeManager = new ThemeManager({ themes: mockThemes });
+      const listener = vi.fn();
+      themeManager.on('themeLoad', listener);
+      expect(() => themeManager.on('themeLoad', listener)).not.toThrow();
+    });
+
+    it('should add theme error listener', () => {
+      themeManager = new ThemeManager({ themes: mockThemes });
+      const listener = vi.fn();
+      themeManager.on('themeError', listener);
+      expect(() => themeManager.on('themeError', listener)).not.toThrow();
+    });
+  });
+
+  describe('isThemeLoaded', () => {
+    it('should check if theme is loaded', () => {
+      themeManager = new ThemeManager({ themes: mockThemes });
+      const isLoaded = themeManager.isThemeLoaded('test-theme');
+      expect(typeof isLoaded).toBe('boolean');
+    });
+  });
+
+  describe('destroy', () => {
+    it('should destroy theme manager', () => {
+      themeManager = new ThemeManager({ themes: mockThemes });
+      expect(() => themeManager.destroy()).not.toThrow();
+    });
+
+    it('should clear event listeners on destroy', () => {
+      themeManager = new ThemeManager({ themes: mockThemes });
+      const listener = vi.fn();
+      themeManager.on('themeChange', listener);
+      themeManager.destroy();
+      // After destroy, listeners should be cleared
+      expect(() => themeManager.destroy()).not.toThrow();
+    });
+  });
+
+  describe('RTL support', () => {
+    it('should get RTL manager when configured', () => {
+      themeManager = new ThemeManager({
+        themes: mockThemes,
+        rtl: { enabled: true, direction: 'ltr' },
+      });
+      const rtlManager = themeManager.getRTLManager();
+      expect(rtlManager).toBeDefined();
+    });
+
+    it('should set direction', () => {
+      themeManager = new ThemeManager({
+        themes: mockThemes,
+        rtl: { enabled: true, direction: 'ltr' },
+      });
+      expect(() => themeManager.setDirection('rtl')).not.toThrow();
+    });
+
+    it('should get direction', () => {
+      themeManager = new ThemeManager({
+        themes: mockThemes,
+        rtl: { enabled: true, direction: 'ltr' },
+      });
+      const direction = themeManager.getDirection();
+      expect(['ltr', 'rtl']).toContain(direction);
+    });
+  });
+});