@shohojdhara/atomix 0.3.1 → 0.3.3

package/src/lib/theme/errors.ts

@@ -0,0 +1,233 @@
+/**
+ * Theme System Error Handling
+ * 
+ * Centralized error handling for the Atomix theme system.
+ * Provides custom error classes and logging utilities.
+ */
+
+/**
+ * Theme error codes
+ */
+export enum ThemeErrorCode {
+  /** Theme not found in registry */
+  THEME_NOT_FOUND = 'THEME_NOT_FOUND',
+  /** Theme failed to load */
+  THEME_LOAD_FAILED = 'THEME_LOAD_FAILED',
+  /** Theme validation failed */
+  THEME_VALIDATION_FAILED = 'THEME_VALIDATION_FAILED',
+  /** Configuration loading failed */
+  CONFIG_LOAD_FAILED = 'CONFIG_LOAD_FAILED',
+  /** Configuration validation failed */
+  CONFIG_VALIDATION_FAILED = 'CONFIG_VALIDATION_FAILED',
+  /** Circular dependency detected */
+  CIRCULAR_DEPENDENCY = 'CIRCULAR_DEPENDENCY',
+  /** Missing dependency */
+  MISSING_DEPENDENCY = 'MISSING_DEPENDENCY',
+  /** Storage operation failed */
+  STORAGE_ERROR = 'STORAGE_ERROR',
+  /** Invalid theme name */
+  INVALID_THEME_NAME = 'INVALID_THEME_NAME',
+  /** CSS injection failed */
+  CSS_INJECTION_FAILED = 'CSS_INJECTION_FAILED',
+  /** Unknown error */
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
+}
+
+/**
+ * Custom error class for theme-related errors
+ */
+export class ThemeError extends Error {
+  /** Error code */
+  public readonly code: ThemeErrorCode;
+  /** Additional context */
+  public readonly context?: Record<string, unknown>;
+  /** Timestamp */
+  public readonly timestamp: number;
+
+  constructor(
+    message: string,
+    code: ThemeErrorCode = ThemeErrorCode.UNKNOWN_ERROR,
+    context?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'ThemeError';
+    this.code = code;
+    this.context = context;
+    this.timestamp = Date.now();
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ThemeError);
+    }
+  }
+
+  /**
+   * Convert error to JSON for logging
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      context: this.context,
+      timestamp: this.timestamp,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Log level
+ */
+export enum LogLevel {
+  ERROR = 0,
+  WARN = 1,
+  INFO = 2,
+  DEBUG = 3,
+}
+
+/**
+ * Logger configuration
+ */
+export interface LoggerConfig {
+  /** Minimum log level */
+  level?: LogLevel;
+  /** Enable console output */
+  enableConsole?: boolean;
+  /** Custom error handler */
+  onError?: (error: ThemeError | Error, context?: Record<string, unknown>) => void;
+  /** Custom warn handler */
+  onWarn?: (message: string, context?: Record<string, unknown>) => void;
+  /** Custom info handler */
+  onInfo?: (message: string, context?: Record<string, unknown>) => void;
+  /** Custom debug handler */
+  onDebug?: (message: string, context?: Record<string, unknown>) => void;
+}
+
+/**
+ * Theme Logger
+ * 
+ * Centralized logging for the theme system.
+ * Replaces console statements with structured logging.
+ */
+export class ThemeLogger {
+  private config: Required<Omit<LoggerConfig, 'onError' | 'onWarn' | 'onInfo' | 'onDebug'>> & {
+    onError?: LoggerConfig['onError'];
+    onWarn?: LoggerConfig['onWarn'];
+    onInfo?: LoggerConfig['onInfo'];
+    onDebug?: LoggerConfig['onDebug'];
+  };
+
+  constructor(config: LoggerConfig = {}) {
+    this.config = {
+      level: config.level ?? (process.env.NODE_ENV === 'production' ? LogLevel.WARN : LogLevel.INFO),
+      enableConsole: config.enableConsole ?? true,
+      onError: config.onError,
+      onWarn: config.onWarn,
+      onInfo: config.onInfo,
+      onDebug: config.onDebug,
+    };
+  }
+
+  /**
+   * Log an error
+   */
+  error(
+    message: string,
+    error?: Error | ThemeError,
+    context?: Record<string, unknown>
+  ): void {
+    if (this.config.level < LogLevel.ERROR) {
+      return;
+    }
+
+    const errorObj = error instanceof Error ? error : new Error(message);
+    const themeError = error instanceof ThemeError 
+      ? error 
+      : new ThemeError(message, ThemeErrorCode.UNKNOWN_ERROR, context);
+
+    if (this.config.enableConsole) {
+      console.error(`[ThemeError] ${message}`, {
+        error: errorObj,
+        context: { ...context, ...themeError.context },
+        code: themeError.code,
+      });
+    }
+
+    this.config.onError?.(themeError, context);
+  }
+
+  /**
+   * Log a warning
+   */
+  warn(message: string, context?: Record<string, unknown>): void {
+    if (this.config.level < LogLevel.WARN) {
+      return;
+    }
+
+    if (this.config.enableConsole) {
+      console.warn(`[ThemeWarning] ${message}`, context || {});
+    }
+
+    this.config.onWarn?.(message, context);
+  }
+
+  /**
+   * Log an info message
+   */
+  info(message: string, context?: Record<string, unknown>): void {
+    if (this.config.level < LogLevel.INFO) {
+      return;
+    }
+
+    if (this.config.enableConsole) {
+      console.info(`[ThemeInfo] ${message}`, context || {});
+    }
+
+    this.config.onInfo?.(message, context);
+  }
+
+  /**
+   * Log a debug message
+   */
+  debug(message: string, context?: Record<string, unknown>): void {
+    if (this.config.level < LogLevel.DEBUG) {
+      return;
+    }
+
+    if (this.config.enableConsole) {
+      console.debug(`[ThemeDebug] ${message}`, context || {});
+    }
+
+    this.config.onDebug?.(message, context);
+  }
+}
+
+/**
+ * Default logger instance
+ */
+let defaultLogger: ThemeLogger | null = null;
+
+/**
+ * Get or create default logger
+ */
+export function getLogger(): ThemeLogger {
+  if (!defaultLogger) {
+    defaultLogger = new ThemeLogger();
+  }
+  return defaultLogger;
+}
+
+/**
+ * Set default logger
+ */
+export function setLogger(logger: ThemeLogger): void {
+  defaultLogger = logger;
+}
+
+/**
+ * Create a logger with custom config
+ */
+export function createLogger(config: LoggerConfig): ThemeLogger {
+  return new ThemeLogger(config);
+}

package/src/lib/theme/generateCSSVariables.ts

@@ -96,8 +96,8 @@ function generateColorScale(baseColor: string, prefix: string, colorName: string
 function generatePaletteVariables(palette: Theme['palette'], prefix: string): Record<string, string> {
     const vars: Record<string, string> = {};
 
-    // Primary, secondary, error, warning, info, success
-    const colorKeys = ['primary', 'secondary', 'error', 'warning', 'info', 'success'] as const;
+    // Primary, secondary, error, warning, info, success, light, dark
+    const colorKeys = ['primary', 'secondary', 'error', 'warning', 'info', 'success', 'light', 'dark'] as const;
     colorKeys.forEach((key) => {
         const color = palette[key];
         if (color && typeof color === 'object') {
@@ -125,9 +125,11 @@ function generatePaletteVariables(palette: Theme['palette'], prefix: string): Re
             // Border subtle: light version for borders
             vars[`${prefix}-${key}-border-subtle`] = alpha(color.main, 0.2);
 
-            // Generate full color scale (1-10)
-            const colorScale = generateColorScale(color.main, prefix, key);
-            Object.assign(vars, colorScale);
+            // Generate full color scale (1-10) - only for primary, not for light/dark
+            if (key !== 'light' && key !== 'dark') {
+                const colorScale = generateColorScale(color.main, prefix, key);
+                Object.assign(vars, colorScale);
+            }
         }
     });
 
@@ -160,11 +162,62 @@ function generatePaletteVariables(palette: Theme['palette'], prefix: string): Re
     // Background mappings to SCSS body variables
     if (palette.background) {
         vars[`${prefix}-body-bg`] = palette.background.default;
+        
+        // Generate background subtle variants
+        if (palette.background.default) {
+            vars[`${prefix}-primary-bg-subtle`] = palette.background.default;
+        }
+        if (palette.background.paper) {
+            vars[`${prefix}-secondary-bg-subtle`] = palette.background.paper;
+            vars[`${prefix}-tertiary-bg-subtle`] = palette.background.paper;
+        }
+        if (palette.background.subtle) {
+            vars[`${prefix}-invert-bg-subtle`] = palette.background.subtle;
+        }
+        
+        // Brand bg subtle (uses primary color with alpha)
+        if (palette.primary) {
+            vars[`${prefix}-brand-bg-subtle`] = alpha(palette.primary.main, 0.1);
+        }
     }
 
     // Text mappings to SCSS body variables
     if (palette.text) {
         vars[`${prefix}-body-color`] = palette.text.primary;
+        
+        // Generate text emphasis variants
+        if (palette.text.primary) {
+            vars[`${prefix}-primary-text-emphasis`] = palette.text.primary;
+        }
+        if (palette.text.secondary) {
+            vars[`${prefix}-secondary-text-emphasis`] = palette.text.secondary;
+            vars[`${prefix}-tertiary-text-emphasis`] = palette.text.secondary;
+        }
+        if (palette.text.disabled) {
+            vars[`${prefix}-disabled-text-emphasis`] = palette.text.disabled;
+        }
+        
+        // Invert text emphasis (opposite of primary)
+        if (palette.text.primary) {
+            // Invert would be the opposite - for light themes, use dark; for dark themes, use light
+            // This is a simplified approach - actual inversion depends on theme mode
+            vars[`${prefix}-invert-text-emphasis`] = palette.text.primary;
+        }
+    }
+
+    // Brand text emphasis (uses primary color)
+    if (palette.primary) {
+        vars[`${prefix}-brand-text-emphasis`] = palette.primary.main;
+        // Brand border subtle
+        vars[`${prefix}-brand-border-subtle`] = alpha(palette.primary.main, 0.2);
+    }
+    
+    // Light and dark border subtle (if light/dark colors exist)
+    if (palette.light && typeof palette.light === 'object') {
+        vars[`${prefix}-light-border-subtle`] = alpha(palette.light.main, 0.2);
+    }
+    if (palette.dark && typeof palette.dark === 'object') {
+        vars[`${prefix}-dark-border-subtle`] = alpha(palette.dark.main, 0.2);
     }
 
     // Heading color (defaults to text primary)
@@ -185,9 +238,8 @@ function generatePaletteVariables(palette: Theme['palette'], prefix: string): Re
         if (linkHoverRgb) {
             vars[`${prefix}-link-hover-color-rgb`] = `${linkHoverRgb.r}, ${linkHoverRgb.g}, ${linkHoverRgb.b}`;
         }
-        // Link decoration (default: underline)
-        vars[`${prefix}-link-decoration`] = 'underline';
-        vars[`${prefix}-link-hover-decoration`] = 'none';
+        // Link decoration (default: none, matching tokens list)
+        vars[`${prefix}-link-decoration`] = 'none';
     }
 
     // Border color (defaults to subtle gray)
@@ -224,6 +276,29 @@ function generatePaletteVariables(palette: Theme['palette'], prefix: string): Re
         vars[`${prefix}-code-color`] = palette.text.secondary;
     }
 
+    // Generate gradient tokens for all colors
+    // Gradients use the color scale (lighter to darker variations)
+    const gradientColors = ['primary', 'secondary', 'error', 'warning', 'info', 'success', 'light', 'dark'] as const;
+    gradientColors.forEach((key) => {
+        const color = palette[key];
+        if (color && typeof color === 'object') {
+            // Generate gradient using color scale steps
+            // Use steps 1, 3, 5 from the color scale for a smooth gradient
+            const color1 = lighten(color.main, 0.6);
+            const color2 = lighten(color.main, 0.3);
+            const color3 = color.main;
+            vars[`${prefix}-${key}-gradient`] = `linear-gradient(135deg, ${color1}, ${color2}, ${color3})`;
+        }
+    });
+    
+    // Default gradient (uses gray scale)
+    if (palette.text?.primary) {
+        const gray1 = lighten(palette.text.primary, 0.8);
+        const gray2 = lighten(palette.text.primary, 0.6);
+        const gray3 = lighten(palette.text.primary, 0.4);
+        vars[`${prefix}-gradient`] = `linear-gradient(135deg, ${gray1}, ${gray2}, ${gray3})`;
+    }
+
     return vars;
 }
 
@@ -379,7 +454,16 @@ function generateTransitionVariables(
 function generateZIndexVariables(zIndex: Theme['zIndex'], prefix: string): Record<string, string> {
     const vars: Record<string, string> = {};
 
-    // Map to SCSS z-layers
+    // Generate z-index scale (matching tokens list)
+    vars[`${prefix}-z-n1`] = '-1';
+    vars[`${prefix}-z-0`] = '0';
+    vars[`${prefix}-z-1`] = '1';
+    vars[`${prefix}-z-2`] = '2';
+    vars[`${prefix}-z-3`] = '3';
+    vars[`${prefix}-z-4`] = '4';
+    vars[`${prefix}-z-5`] = '5';
+
+    // Map to SCSS z-layers (semantic z-index values)
     if (zIndex.mobileStepper) vars[`${prefix}-z-dropdown`] = String(zIndex.mobileStepper);
     if (zIndex.appBar) vars[`${prefix}-z-sticky`] = String(zIndex.appBar);
     vars[`${prefix}-z-fixed`] = '1030'; // Default fixed

package/src/lib/theme/generators/CSSGenerator.ts

@@ -0,0 +1,311 @@
+/**
+ * CSS Generator
+ * 
+ * Optimized CSS variable generation from theme objects
+ */
+
+import type { Theme } from '../types';
+
+/**
+ * CSS generation options
+ */
+export interface CSSGeneratorOptions {
+  /** CSS selector (default: ':root') */
+  selector?: string;
+  /** CSS variable prefix (default: 'atomix') */
+  prefix?: string;
+  /** Include comments */
+  includeComments?: boolean;
+  /** Minify output */
+  minify?: boolean;
+  /** Custom property formatter */
+  formatProperty?: (path: string[], value: any) => string;
+}
+
+/**
+ * CSS Generator
+ * 
+ * Generates optimized CSS custom properties from theme objects
+ */
+export class CSSGenerator {
+  private options: Required<Omit<CSSGeneratorOptions, 'formatProperty'>> & {
+    formatProperty?: CSSGeneratorOptions['formatProperty'];
+  };
+
+  constructor(options: CSSGeneratorOptions = {}) {
+    this.options = {
+      selector: options.selector || ':root',
+      prefix: options.prefix || 'atomix',
+      includeComments: options.includeComments ?? true,
+      minify: options.minify ?? false,
+      formatProperty: options.formatProperty,
+    };
+  }
+
+  /**
+   * Generate CSS from theme
+   */
+  generate(theme: Theme): string {
+    const variables = this.extractVariables(theme);
+    return this.formatCSS(variables);
+  }
+
+  /**
+   * Extract CSS variables from theme
+   */
+  private extractVariables(theme: Theme): Map<string, string> {
+    const variables = new Map<string, string>();
+
+    // Palette
+    this.extractPalette(theme.palette, variables);
+
+    // Typography
+    this.extractTypography(theme.typography, variables);
+
+    // Spacing (generate common values)
+    this.extractSpacing(theme.spacing, variables);
+
+    // Breakpoints
+    this.extractBreakpoints(theme.breakpoints, variables);
+
+    // Shadows
+    this.extractShadows(theme.shadows, variables);
+
+    // Transitions
+    this.extractTransitions(theme.transitions, variables);
+
+    // Z-index
+    this.extractZIndex(theme.zIndex, variables);
+
+    // Border radius
+    this.extractBorderRadius(theme.borderRadius, variables);
+
+    // Custom properties
+    this.extractCustom(theme.custom, variables);
+
+    return variables;
+  }
+
+  /**
+   * Extract palette variables
+   */
+  private extractPalette(palette: Theme['palette'], variables: Map<string, string>): void {
+    const colors = ['primary', 'secondary', 'error', 'warning', 'info', 'success'] as const;
+
+    for (const color of colors) {
+      const colorObj = palette[color];
+      if (colorObj) {
+        variables.set(`palette-${color}-main`, colorObj.main);
+        if (colorObj.light) variables.set(`palette-${color}-light`, colorObj.light);
+        if (colorObj.dark) variables.set(`palette-${color}-dark`, colorObj.dark);
+        if (colorObj.contrastText) variables.set(`palette-${color}-contrast-text`, colorObj.contrastText);
+      }
+    }
+
+    // Background
+    if (palette.background) {
+      variables.set('background-default', palette.background.default);
+      variables.set('background-paper', palette.background.paper);
+      variables.set('background-subtle', palette.background.subtle);
+    }
+
+    // Text
+    if (palette.text) {
+      variables.set('text-primary', palette.text.primary);
+      variables.set('text-secondary', palette.text.secondary);
+      variables.set('text-disabled', palette.text.disabled);
+    }
+  }
+
+  /**
+   * Extract typography variables
+   */
+  private extractTypography(typography: Theme['typography'], variables: Map<string, string>): void {
+    variables.set('font-family', typography.fontFamily);
+    variables.set('font-size', `${typography.fontSize}px`);
+
+    // Font weights
+    if (typography.fontWeightLight) variables.set('font-weight-light', String(typography.fontWeightLight));
+    if (typography.fontWeightRegular) variables.set('font-weight-regular', String(typography.fontWeightRegular));
+    if (typography.fontWeightMedium) variables.set('font-weight-medium', String(typography.fontWeightMedium));
+    if (typography.fontWeightSemiBold) variables.set('font-weight-semibold', String(typography.fontWeightSemiBold));
+    if (typography.fontWeightBold) variables.set('font-weight-bold', String(typography.fontWeightBold));
+
+    // Headings
+    const headings = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] as const;
+    for (const heading of headings) {
+      const h = typography[heading];
+      if (h) {
+        if (h.fontSize) variables.set(`typography-${heading}-font-size`, String(h.fontSize));
+        if (h.fontWeight) variables.set(`typography-${heading}-font-weight`, String(h.fontWeight));
+        if (h.lineHeight) variables.set(`typography-${heading}-line-height`, String(h.lineHeight));
+      }
+    }
+
+    // Body
+    if (typography.body1) {
+      if (typography.body1.fontSize) variables.set('typography-body1-font-size', String(typography.body1.fontSize));
+      if (typography.body1.fontWeight) variables.set('typography-body1-font-weight', String(typography.body1.fontWeight));
+      if (typography.body1.lineHeight) variables.set('typography-body1-line-height', String(typography.body1.lineHeight));
+    }
+
+    if (typography.body2) {
+      if (typography.body2.fontSize) variables.set('typography-body2-font-size', String(typography.body2.fontSize));
+      if (typography.body2.fontWeight) variables.set('typography-body2-font-weight', String(typography.body2.fontWeight));
+      if (typography.body2.lineHeight) variables.set('typography-body2-line-height', String(typography.body2.lineHeight));
+    }
+  }
+
+  /**
+   * Extract spacing variables
+   */
+  private extractSpacing(spacing: Theme['spacing'], variables: Map<string, string>): void {
+    // Generate common spacing values
+    for (let i = 0; i <= 12; i++) {
+      try {
+        const value = spacing(i);
+        variables.set(`spacing-${i}`, value);
+      } catch {
+        // Ignore errors
+      }
+    }
+  }
+
+  /**
+   * Extract breakpoint variables
+   */
+  private extractBreakpoints(breakpoints: Theme['breakpoints'], variables: Map<string, string>): void {
+    const keys = ['xs', 'sm', 'md', 'lg', 'xl'] as const;
+    for (const key of keys) {
+      const value = breakpoints.values[key];
+      if (value !== undefined) {
+        variables.set(`breakpoint-${key}`, `${value}px`);
+      }
+    }
+  }
+
+  /**
+   * Extract shadow variables
+   */
+  private extractShadows(shadows: Theme['shadows'], variables: Map<string, string>): void {
+    const keys = ['xs', 'sm', 'md', 'lg', 'xl'] as const;
+    for (const key of keys) {
+      const shadow = shadows[key];
+      if (shadow) {
+        variables.set(`shadow-${key}`, shadow);
+      }
+    }
+  }
+
+  /**
+   * Extract transition variables
+   */
+  private extractTransitions(transitions: Theme['transitions'], variables: Map<string, string>): void {
+    if (transitions.duration) {
+      const durations = ['shortest', 'shorter', 'short', 'standard', 'complex'] as const;
+      for (const key of durations) {
+        const value = transitions.duration[key];
+        if (value !== undefined) {
+          variables.set(`transition-duration-${key}`, `${value}ms`);
+        }
+      }
+    }
+
+    if (transitions.easing) {
+      const easings = ['easeInOut', 'easeOut', 'easeIn', 'sharp'] as const;
+      for (const key of easings) {
+        const value = transitions.easing[key];
+        if (value) {
+          variables.set(`transition-easing-${key}`, value);
+        }
+      }
+    }
+  }
+
+  /**
+   * Extract z-index variables
+   */
+  private extractZIndex(zIndex: Theme['zIndex'], variables: Map<string, string>): void {
+    const keys = ['mobileStepper', 'speedDial', 'appBar', 'drawer', 'modal', 'snackbar', 'tooltip'] as const;
+    for (const key of keys) {
+      const value = zIndex[key];
+      if (value !== undefined) {
+        variables.set(`z-index-${key}`, String(value));
+      }
+    }
+  }
+
+  /**
+   * Extract border radius variables
+   */
+  private extractBorderRadius(borderRadius: Theme['borderRadius'], variables: Map<string, string>): void {
+    const keys = ['base', 'sm', 'md', 'lg', 'xl', 'xxl', '3xl', '4xl', 'pill'] as const;
+    for (const key of keys) {
+      const value = borderRadius[key];
+      if (value !== undefined) {
+        variables.set(`border-radius-${key}`, String(value));
+      }
+    }
+  }
+
+  /**
+   * Extract custom properties
+   */
+  private extractCustom(custom: Theme['custom'], variables: Map<string, string>): void {
+    for (const [key, value] of Object.entries(custom)) {
+      if (value !== undefined && value !== null) {
+        variables.set(`custom-${key}`, String(value));
+      }
+    }
+  }
+
+  /**
+   * Format CSS from variables
+   */
+  private formatCSS(variables: Map<string, string>): string {
+    const { selector, prefix, includeComments, minify } = this.options;
+    const indent = minify ? '' : '  ';
+    const newline = minify ? '' : '\n';
+    const space = minify ? '' : ' ';
+
+    let css = '';
+
+    if (includeComments && !minify) {
+      css += `/* Atomix Theme CSS Variables */${newline}`;
+      css += `/* Generated from theme configuration */${newline}${newline}`;
+    }
+
+    css += `${selector}${space}{${newline}`;
+
+    for (const [key, value] of variables.entries()) {
+      const property = this.formatPropertyName(key);
+      css += `${indent}--${prefix}-${property}:${space}${value};${newline}`;
+    }
+
+    css += `}${newline}`;
+
+    return css;
+  }
+
+  /**
+   * Format property name
+   */
+  private formatPropertyName(key: string): string {
+    if (this.options.formatProperty) {
+      return this.options.formatProperty(key.split('-'), key);
+    }
+    return key;
+  }
+}
+
+/**
+ * Generate CSS variables from theme
+ * 
+ * @param theme - Theme object
+ * @param options - Generation options
+ * @returns CSS string
+ */
+export function generateCSS(theme: Theme, options: CSSGeneratorOptions = {}): string {
+  const generator = new CSSGenerator(options);
+  return generator.generate(theme);
+}