@shohojdhara/atomix 0.3.2 → 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/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
  */
@@ -559,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-tools.ts

@@ -0,0 +1,185 @@
+/**
+ * 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 { ComponentOverrideManager } from './theme/overrides/ComponentOverrides';
+import { WhiteLabelManager } from './theme/whitelabel/WhiteLabelManager';
+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',
+  });
+}
+
+/**
+ * Apply overrides to theme easily
+ */
+export function applyOverrides(
+  theme: Theme,
+  overrides: Record<string, any>
+): Theme {
+  const manager = new ComponentOverrideManager(theme);
+  
+  Object.entries(overrides).forEach(([component, override]) => {
+    manager.addOverride(component, override);
+  });
+  
+  const overriddenTheme = manager.getThemeWithOverrides();
+  if (!overriddenTheme) {
+    throw new Error('Failed to get theme with overrides: theme was not set');
+  }
+  
+  return overriddenTheme;
+}
+
+/**
+ * Apply white label configuration
+ */
+export function applyWhiteLabel(
+  theme: Theme,
+  brand: {
+    name: string;
+    primaryColor: string;
+    logo?: string;
+  }
+): Theme {
+  const manager = new WhiteLabelManager(theme);
+  
+  manager.configure({
+    brand: {
+      name: brand.name,
+      primaryColor: brand.primaryColor,
+      logo: brand.logo,
+    },
+    themeOverrides: {
+      palette: {
+        primary: { main: brand.primaryColor },
+      },
+    },
+  });
+  
+  const whiteLabeledTheme = manager.getWhiteLabeledTheme();
+  if (!whiteLabeledTheme) {
+    throw new Error('Failed to get white labeled theme: theme was not set');
+  }
+  
+  return whiteLabeledTheme;
+}
+
+/**
+ * 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 { ComponentOverrideManager } from './theme/overrides/ComponentOverrides';
+export { WhiteLabelManager } from './theme/whitelabel/WhiteLabelManager';
+export { RTLManager } from './theme/i18n/rtl';
+export { ThemeAnalytics } from './theme/monitoring/ThemeAnalytics';