@shohojdhara/atomix 0.3.1 → 0.3.3

package/src/lib/theme/builders/ThemeBuilder.ts

@@ -0,0 +1,372 @@
+/**
+ * Theme Builder
+ * 
+ * Fluent API for building theme configurations with type safety and validation.
+ */
+
+import type { Theme, ThemeComponentOverrides, ComponentThemeOverride } from '../types';
+
+/**
+ * Theme builder class with fluent API
+ */
+export class ThemeBuilder {
+  private theme: Partial<Theme> = {};
+
+  /**
+   * Set theme name
+   */
+  setName(name: string): this {
+    this.theme.name = name;
+    return this;
+  }
+
+  /**
+   * Set global CSS variables
+   */
+  setCSSVars(vars: Record<string, string | number>): this {
+    this.theme.cssVars = { ...this.theme.cssVars, ...vars };
+    return this;
+  }
+
+  /**
+   * Add a single CSS variable
+   */
+  addCSSVar(key: string, value: string | number): this {
+    if (!this.theme.cssVars) {
+      this.theme.cssVars = {};
+    }
+    this.theme.cssVars[key] = value;
+    return this;
+  }
+
+  /**
+   * Set typography configuration
+   */
+  setTypography(typography: Theme['typography']): this {
+    this.theme.typography = typography;
+    return this;
+  }
+
+  /**
+   * Set font family
+   */
+  setFontFamily(fontFamily: string): this {
+    if (!this.theme.typography) {
+      this.theme.typography = {};
+    }
+    this.theme.typography.fontFamily = fontFamily;
+    return this;
+  }
+
+  /**
+   * Set font sizes
+   */
+  setFontSizes(fontSize: Record<string, string>): this {
+    if (!this.theme.typography) {
+      this.theme.typography = {};
+    }
+    this.theme.typography.fontSize = fontSize;
+    return this;
+  }
+
+  /**
+   * Set font weights
+   */
+  setFontWeights(fontWeight: Record<string, number>): this {
+    if (!this.theme.typography) {
+      this.theme.typography = {};
+    }
+    this.theme.typography.fontWeight = fontWeight;
+    return this;
+  }
+
+  /**
+   * Set line heights
+   */
+  setLineHeights(lineHeight: Record<string, number>): this {
+    if (!this.theme.typography) {
+      this.theme.typography = {};
+    }
+    this.theme.typography.lineHeight = lineHeight;
+    return this;
+  }
+
+  /**
+   * Set spacing system
+   */
+  setSpacing(spacing: Record<string, string | number>): this {
+    this.theme.spacing = spacing;
+    return this;
+  }
+
+  /**
+   * Set color palette
+   */
+  setPalette(palette: Theme['palette']): this {
+    this.theme.palette = palette;
+    return this;
+  }
+
+  /**
+   * Set a specific color scale
+   */
+  setColorScale(
+    colorName: keyof NonNullable<Theme['palette']>,
+    scale: NonNullable<Theme['palette']>[typeof colorName]
+  ): this {
+    if (!this.theme.palette) {
+      this.theme.palette = {};
+    }
+    this.theme.palette[colorName] = scale;
+    return this;
+  }
+
+  /**
+   * Override a component's configuration
+   */
+  overrideComponent<C extends keyof ThemeComponentOverrides>(
+    component: C,
+    override: ThemeComponentOverrides[C]
+  ): this {
+    if (!this.theme.components) {
+      this.theme.components = {};
+    }
+    this.theme.components[component] = override;
+    return this;
+  }
+
+  /**
+   * Set component CSS variables
+   */
+  setComponentCSSVars<C extends keyof ThemeComponentOverrides>(
+    component: C,
+    vars: Record<string, string | number>
+  ): this {
+    if (!this.theme.components) {
+      this.theme.components = {};
+    }
+    if (!this.theme.components[component]) {
+      this.theme.components[component] = {} as any;
+    }
+    const componentOverride = this.theme.components[component] as ComponentThemeOverride;
+    componentOverride.cssVars = { ...componentOverride.cssVars, ...vars };
+    return this;
+  }
+
+  /**
+   * Set component default props
+   */
+  setComponentDefaultProps<C extends keyof ThemeComponentOverrides>(
+    component: C,
+    defaultProps: Record<string, any>
+  ): this {
+    if (!this.theme.components) {
+      this.theme.components = {};
+    }
+    if (!this.theme.components[component]) {
+      this.theme.components[component] = {} as any;
+    }
+    const componentOverride = this.theme.components[component] as ComponentThemeOverride;
+    componentOverride.defaultProps = { ...componentOverride.defaultProps, ...defaultProps };
+    return this;
+  }
+
+  /**
+   * Set component part styles
+   */
+  setComponentPart<C extends keyof ThemeComponentOverrides>(
+    component: C,
+    partName: string,
+    partConfig: {
+      cssVars?: Record<string, string | number>;
+      className?: string;
+    }
+  ): this {
+    if (!this.theme.components) {
+      this.theme.components = {};
+    }
+    if (!this.theme.components[component]) {
+      this.theme.components[component] = {} as any;
+    }
+    const componentOverride = this.theme.components[component] as ComponentThemeOverride;
+    if (!componentOverride.parts) {
+      componentOverride.parts = {};
+    }
+    componentOverride.parts[partName] = partConfig;
+    return this;
+  }
+
+  /**
+   * Set component variant styles
+   */
+  setComponentVariant<C extends keyof ThemeComponentOverrides>(
+    component: C,
+    variantName: string,
+    variantConfig: {
+      cssVars?: Record<string, string | number>;
+      className?: string;
+    }
+  ): this {
+    if (!this.theme.components) {
+      this.theme.components = {};
+    }
+    if (!this.theme.components[component]) {
+      this.theme.components[component] = {} as any;
+    }
+    const componentOverride = this.theme.components[component] as ComponentThemeOverride;
+    if (!componentOverride.variants) {
+      componentOverride.variants = {};
+    }
+    componentOverride.variants[variantName] = variantConfig;
+    return this;
+  }
+
+  /**
+   * Merge with another theme
+   */
+  merge(otherTheme: Partial<Theme>): this {
+    // Deep merge logic
+    if (otherTheme.name) this.theme.name = otherTheme.name;
+    
+    if (otherTheme.cssVars) {
+      this.theme.cssVars = { ...this.theme.cssVars, ...otherTheme.cssVars };
+    }
+
+    if (otherTheme.typography) {
+      this.theme.typography = {
+        ...this.theme.typography,
+        ...otherTheme.typography,
+        fontSize: {
+          ...this.theme.typography?.fontSize,
+          ...otherTheme.typography.fontSize,
+        },
+        fontWeight: {
+          ...this.theme.typography?.fontWeight,
+          ...otherTheme.typography.fontWeight,
+        },
+        lineHeight: {
+          ...this.theme.typography?.lineHeight,
+          ...otherTheme.typography.lineHeight,
+        },
+      };
+    }
+
+    if (otherTheme.spacing) {
+      this.theme.spacing = { ...this.theme.spacing, ...otherTheme.spacing };
+    }
+
+    if (otherTheme.palette) {
+      this.theme.palette = {
+        ...this.theme.palette,
+        ...otherTheme.palette,
+      };
+    }
+
+    if (otherTheme.components) {
+      this.theme.components = {
+        ...this.theme.components,
+        ...otherTheme.components,
+      };
+    }
+
+    return this;
+  }
+
+  /**
+   * Clone the current builder
+   */
+  clone(): ThemeBuilder {
+    const newBuilder = new ThemeBuilder();
+    newBuilder.theme = JSON.parse(JSON.stringify(this.theme));
+    return newBuilder;
+  }
+
+  /**
+   * Build and return the theme
+   */
+  build(): Theme {
+    if (!this.theme.name) {
+      throw new Error('Theme name is required. Use setName() to set it.');
+    }
+
+    return this.theme as Theme;
+  }
+
+  /**
+   * Build without validation (returns partial theme)
+   */
+  buildPartial(): Partial<Theme> {
+    return { ...this.theme };
+  }
+
+  /**
+   * Reset the builder
+   */
+  reset(): this {
+    this.theme = {};
+    return this;
+  }
+
+  /**
+   * Get current theme state
+   */
+  getTheme(): Partial<Theme> {
+    return { ...this.theme };
+  }
+}
+
+/**
+ * Create a new theme builder
+ */
+export function createThemeBuilder(): ThemeBuilder {
+  return new ThemeBuilder();
+}
+
+/**
+ * Create a theme from a base theme
+ */
+export function extendTheme(baseTheme: Theme): ThemeBuilder {
+  const builder = new ThemeBuilder();
+  builder.merge(baseTheme);
+  return builder;
+}
+
+/**
+ * Quick theme creation helper
+ */
+export function createTheme(config: {
+  name: string;
+  cssVars?: Record<string, string | number>;
+  typography?: Theme['typography'];
+  spacing?: Record<string, string | number>;
+  palette?: Theme['palette'];
+  components?: ThemeComponentOverrides;
+}): Theme {
+  const builder = new ThemeBuilder();
+  
+  builder.setName(config.name);
+  
+  if (config.cssVars) {
+    builder.setCSSVars(config.cssVars);
+  }
+  
+  if (config.typography) {
+    builder.setTypography(config.typography);
+  }
+  
+  if (config.spacing) {
+    builder.setSpacing(config.spacing);
+  }
+  
+  if (config.palette) {
+    builder.setPalette(config.palette);
+  }
+  
+  if (config.components) {
+    Object.entries(config.components).forEach(([component, override]) => {
+      builder.overrideComponent(component as any, override as any);
+    });
+  }
+  
+  return builder.build();
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Theme Configuration Module
+ * 
+ * Exports for theme configuration loading and validation
+ */
+
+export { loadThemeConfig, clearConfigCache, getCachedConfig, reloadThemeConfig } from './loader';
+export { validateConfig } from './validator';
+export type {
+  ConfigLoaderOptions,
+  LoadedThemeConfig,
+  ConfigValidationResult,
+  ThemeMetadata,
+  ThemeConfig,
+  ThemeDefinition,
+  CSSThemeDefinition,
+  JSThemeDefinition,
+  BuildConfig,
+  RuntimeConfig,
+  IntegrationConfig,
+} from './types';

package/src/lib/theme/config/loader.ts

@@ -0,0 +1,276 @@
+/**
+ * Theme Configuration Loader
+ * 
+ * Loads and validates the theme configuration from theme.config.ts
+ */
+
+import type {
+  ConfigLoaderOptions,
+  LoadedThemeConfig,
+  ConfigValidationResult,
+} from './types';
+import { validateConfig } from './validator';
+import { ThemeError, ThemeErrorCode, getLogger } from '../errors';
+import {
+  DEFAULT_CONFIG_PATH,
+  DEFAULT_CONFIG_RELATIVE_PATH,
+  DEFAULT_BASE_PATH,
+  DEFAULT_STORAGE_KEY,
+  DEFAULT_DATA_ATTRIBUTE,
+  DEFAULT_INTEGRATION_CLASS_NAMES,
+  DEFAULT_INTEGRATION_CSS_VARIABLES,
+  DEFAULT_BUILD_OUTPUT_DIR,
+  DEFAULT_SASS_CONFIG,
+  ENV_DEFAULTS,
+} from '../constants';
+
+/**
+ * Cache for loaded configuration
+ */
+let cachedConfig: LoadedThemeConfig | null = null;
+
+/**
+ * Logger instance
+ */
+const logger = getLogger();
+
+/**
+ * Load theme configuration from theme.config.ts
+ * 
+ * @param options - Loader options
+ * @returns Loaded and validated theme configuration
+ * 
+ * @example
+ * ```typescript
+ * import { loadThemeConfig } from '@shohojdhara/atomix/theme/config';
+ * const config = loadThemeConfig();
+ * ```
+ */
+export function loadThemeConfig(
+  options: ConfigLoaderOptions = {}
+): LoadedThemeConfig {
+  const {
+    configPath = DEFAULT_CONFIG_PATH,
+    validate = true,
+    env = typeof process !== 'undefined' && process.env ? (process.env.NODE_ENV === 'production' ? 'production' : 'development') : 'development',
+  } = options;
+
+  // Return cached config if available
+  if (cachedConfig) {
+    return cachedConfig;
+  }
+
+  // Try to load config dynamically
+  let config: LoadedThemeConfig;
+  
+  try {
+    // In browser/Vite environment, we can't load theme.config.ts dynamically
+    // This is expected and we'll use the fallback config
+    if (typeof window !== 'undefined') {
+      throw new Error('Theme config loading not supported in browser environment');
+    }
+    
+    // In Node.js/bundler environment, try require (CommonJS) first
+    // Check if we're in a browser environment first
+    if (typeof window !== 'undefined' || typeof require === 'undefined') {
+      throw new Error('Theme config loading not supported in browser environment');
+    }
+    
+    // Type for theme config module
+    interface ThemeConfigModule {
+      default?: LoadedThemeConfig;
+      [key: string]: unknown;
+    }
+    
+    let themeConfigModule: ThemeConfigModule;
+    
+    // Try require (Node.js/CommonJS) - works in Node.js environments
+    try {
+      // Try relative path first (for build tools)
+      try {
+        themeConfigModule = require(DEFAULT_CONFIG_RELATIVE_PATH) as ThemeConfigModule;
+      } catch {
+        // If relative path fails, try to resolve from process.cwd()
+        const path = require('path') as typeof import('path');
+        const fs = require('fs') as typeof import('fs');
+        const configFilePath = path.resolve(process.cwd(), configPath);
+        
+        // Check if file exists
+        if (fs.existsSync(configFilePath)) {
+          // Delete from cache to force reload
+          const resolvedPath = require.resolve(configFilePath);
+          if (require.cache && require.cache[resolvedPath]) {
+            delete require.cache[resolvedPath];
+          }
+          themeConfigModule = require(configFilePath) as ThemeConfigModule;
+        } else {
+          throw new Error(`Config file not found: ${configFilePath}`);
+        }
+      }
+    } catch (requireError) {
+      // If require fails, throw to fall through to error handling
+      const errorMessage = requireError instanceof Error 
+        ? requireError.message 
+        : String(requireError);
+      throw new ThemeError(
+        `Cannot load theme config: ${errorMessage}`,
+        ThemeErrorCode.CONFIG_LOAD_FAILED,
+        { configPath, error: errorMessage }
+      );
+    }
+    
+    const rawConfig = (themeConfigModule.default || themeConfigModule) as LoadedThemeConfig;
+
+    // Apply environment-specific overrides
+    const processedConfig = applyEnvOverrides(rawConfig, env);
+
+    // Validate if requested
+    let validationResult: ConfigValidationResult | null = null;
+    if (validate) {
+      validationResult = validateConfig(processedConfig);
+    }
+
+    config = {
+      ...processedConfig,
+      validated: validate,
+      errors: validationResult?.errors,
+      warnings: validationResult?.warnings,
+    };
+  } catch (error) {
+    // Fallback: return default config structure
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.warn(`Failed to load theme config from ${configPath}`, {
+      configPath,
+      error: errorMessage,
+    });
+    
+    config = {
+      themes: {},
+      build: {
+        output: {
+          directory: DEFAULT_BUILD_OUTPUT_DIR,
+          formats: {
+            expanded: '.css',
+            compressed: '.min.css',
+          },
+        },
+        sass: {
+          ...DEFAULT_SASS_CONFIG,
+          loadPaths: [...DEFAULT_SASS_CONFIG.loadPaths],
+        },
+      },
+      runtime: {
+        basePath: DEFAULT_BASE_PATH,
+        cdnPath: null,
+        preload: [],
+        lazy: true,
+        defaultTheme: '', // No default - use built-in styles (empty string instead of undefined)
+        storageKey: DEFAULT_STORAGE_KEY,
+        dataAttribute: DEFAULT_DATA_ATTRIBUTE,
+        enablePersistence: true,
+        useMinified: env === 'production',
+      },
+      integration: {
+        cssVariables: DEFAULT_INTEGRATION_CSS_VARIABLES,
+        classNames: DEFAULT_INTEGRATION_CLASS_NAMES,
+      },
+      dependencies: {},
+      validated: false,
+      errors: [`Failed to load config: ${error instanceof Error ? error.message : String(error)}`],
+      warnings: [],
+    };
+  }
+
+  // Cache the loaded config
+  cachedConfig = config;
+
+  return config;
+}
+
+/**
+ * Apply environment-specific overrides to configuration
+ * 
+ * @param config - Base configuration
+ * @param env - Environment name
+ * @returns Configuration with environment overrides applied
+ */
+function applyEnvOverrides(
+  config: LoadedThemeConfig,
+  env: 'development' | 'production' | 'test'
+): LoadedThemeConfig {
+  const overridden = { ...config };
+
+  // Production overrides
+  if (env === 'production') {
+    if (overridden.runtime) {
+      overridden.runtime = {
+        ...overridden.runtime,
+        useMinified: true,
+        lazy: true,
+      };
+    }
+  }
+
+  // Development overrides
+  if (env === 'development') {
+    if (overridden.runtime) {
+      overridden.runtime = {
+        ...overridden.runtime,
+        useMinified: false,
+        lazy: false,
+      };
+    }
+    if (overridden.build) {
+      overridden.build = {
+        ...overridden.build,
+        sass: {
+          ...overridden.build.sass,
+          sourceMap: true,
+        },
+      };
+    }
+  }
+
+  // Test overrides
+  if (env === 'test') {
+    if (overridden.runtime) {
+      overridden.runtime = {
+        ...overridden.runtime,
+        enablePersistence: false,
+        preload: [],
+      };
+    }
+  }
+
+  return overridden;
+}
+
+/**
+ * Clear the cached configuration
+ * Useful for testing or hot reloading
+ */
+export function clearConfigCache(): void {
+  cachedConfig = null;
+}
+
+/**
+ * Get cached configuration without loading
+ * 
+ * @returns Cached configuration or null
+ */
+export function getCachedConfig(): LoadedThemeConfig | null {
+  return cachedConfig;
+}
+
+/**
+ * Reload configuration (clears cache and loads fresh)
+ * 
+ * @param options - Loader options
+ * @returns Freshly loaded configuration
+ */
+export function reloadThemeConfig(
+  options: ConfigLoaderOptions = {}
+): LoadedThemeConfig {
+  clearConfigCache();
+  return loadThemeConfig(options);
+}