@shohojdhara/atomix 0.3.2 → 0.3.4

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/ThemeManager.test.ts

@@ -10,7 +10,23 @@ import { ThemeError, ThemeErrorCode } from '../errors';
 import type { ThemeMetadata } from '../types';
 
 // Mock dependencies
-vi.mock('../core/ThemeEngine');
+vi.mock('../core/ThemeEngine', () => {
+  return {
+    ThemeEngine: class {
+      initialize = vi.fn().mockResolvedValue(undefined);
+      on = vi.fn();
+      getRegistry = vi.fn().mockReturnValue({
+        has: vi.fn().mockReturnValue(false),
+        register: vi.fn(),
+        getAllMetadata: vi.fn().mockReturnValue([]),
+      });
+      setTheme = vi.fn().mockResolvedValue(undefined);
+      getActiveTheme = vi.fn().mockReturnValue(null);
+      isThemeLoaded = vi.fn().mockReturnValue(false);
+      preloadTheme = vi.fn().mockResolvedValue(undefined);
+    },
+  };
+});
 vi.mock('../config/loader');
 vi.mock('../utils', () => ({
   isBrowser: () => true,

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

@@ -63,7 +63,7 @@ const DEFAULT_CONFIG: Partial<ThemeManagerConfig> = {
  *   // No defaultTheme - uses built-in styles
  * });
  * 
- * await themeManager.setTheme('flashtrade');
+ * await themeManager.setTheme('my-custom-theme');
  * ```
  */
 export class ThemeManager {
@@ -356,13 +356,13 @@ export class ThemeManager {
    * Emit theme error event
    */
   private emitThemeError(error: Error, themeName: string): void {
-    const themeError = error instanceof ThemeError 
-      ? error 
+    const themeError = error instanceof ThemeError
+      ? error
       : new ThemeError(
-          error.message,
-          ThemeErrorCode.THEME_LOAD_FAILED,
-          { themeName, originalError: error.message }
-        );
+        error.message,
+        ThemeErrorCode.THEME_LOAD_FAILED,
+        { themeName, originalError: error.message }
+      );
 
     if (this.config.onError) {
       try {

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

@@ -5,6 +5,7 @@
  */
 
 import type { ThemeManager as ThemeManagerType } from './runtime/ThemeManager';
+import type { PartStyleProps } from '../types/partProps';
 
 /**
  * Theme metadata interface matching themes.config.js structure
@@ -184,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
  */
@@ -277,7 +334,6 @@ export interface PaletteOptions {
     /** Background colors */
     background?: {
         default?: string;
-        paper?: string;
         subtle?: string;
     };
     /** Text colors */
@@ -559,6 +615,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-tools.ts

@@ -0,0 +1,125 @@
+/**
+ * Theme Tools for Library Users
+ * 
+ * Developer-friendly utilities for working with Atomix themes
+ */
+
+import { Theme, ThemeMetadata } from './theme/types';
+import { createTheme } from './theme/createTheme';
+import { extendTheme, mergeTheme } from './theme/composeTheme';
+import { generateCSSVariables } from './theme/generateCSSVariables';
+
+/**
+ * Quick theme creator with sensible defaults
+ */
+export function quickTheme(name: string, primaryColor: string, secondaryColor?: string): Theme {
+  return createTheme({
+    name,
+    palette: {
+      primary: { main: primaryColor },
+      secondary: secondaryColor ? { main: secondaryColor } : undefined,
+    },
+  });
+}
+
+/**
+ * Create a dark theme variant from a light theme
+ */
+export function createDarkVariant(lightTheme: Theme): Theme {
+  return extendTheme(lightTheme, {
+    name: `${lightTheme.name} Dark`,
+    palette: {
+      mode: 'dark',
+      background: {
+        default: '#121212',
+        paper: '#1e1e1e',
+      },
+      text: {
+        primary: '#ffffff',
+        secondary: 'rgba(255, 255, 255, 0.7)',
+      },
+    },
+  });
+}
+
+/**
+ * Validate theme structure
+ */
+export function validateTheme(theme: Theme): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (!theme.name) {
+    errors.push('Theme must have a name');
+  }
+
+  if (!theme.palette) {
+    errors.push('Theme must have a palette');
+  }
+
+  if (theme.palette && !theme.palette.primary) {
+    errors.push('Theme palette must have a primary color');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Generate CSS string from theme
+ */
+export function themeToCSS(theme: Theme, selector = ':root'): string {
+  return generateCSSVariables(theme, {
+    selector,
+    prefix: 'atomix',
+  });
+}
+
+/**
+ * Get theme metadata
+ */
+export function getThemeMetadata(theme: Theme): ThemeMetadata {
+  return {
+    name: theme.name || 'Custom Theme',
+    description: theme.description,
+    author: theme.author,
+    version: theme.version || '1.0.0',
+    tags: theme.tags || [],
+    supportsDarkMode: theme.palette?.mode === 'dark',
+    status: 'stable',
+    color: theme.palette?.primary?.main || '#7AFFD7',
+  };
+}
+
+/**
+ * Check if theme supports dark mode
+ */
+export function supportsDarkMode(theme: Theme): boolean {
+  return theme.palette?.mode === 'dark' ||
+    theme.supportsDarkMode === true ||
+    Boolean(theme.a11y?.modes?.includes('dark'));
+}
+
+/**
+ * Export theme as JSON
+ */
+export function exportTheme(theme: Theme): string {
+  return JSON.stringify(theme, null, 2);
+}
+
+/**
+ * Import theme from JSON
+ */
+export function importTheme(json: string): Theme {
+  try {
+    return JSON.parse(json) as Theme;
+  } catch (error) {
+    throw new Error('Invalid theme JSON');
+  }
+}
+
+// Re-export commonly used functions
+export { createTheme, extendTheme, mergeTheme };
+export { generateCSSVariables };
+export { RTLManager } from './theme/i18n/rtl';