@shohojdhara/atomix 0.5.2 → 0.5.4

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

@@ -0,0 +1,221 @@
+/**
+ * Theme Configuration Loader
+ * 
+ * Loads and validates the theme configuration from atomix.config.ts (and other formats)
+ */
+
+import type {
+  ConfigLoaderOptions,
+  LoadedThemeConfig,
+  ConfigValidationResult,
+} from './types';
+import { validateConfig } from './validator';
+import { ThemeError, ThemeErrorCode, getLogger } from '../errors';
+import {
+  DEFAULT_ATOMIX_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 atomix.config.ts (and other formats)
+ * 
+ * @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_ATOMIX_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 config dynamically
+    if (typeof window !== 'undefined') {
+      throw new Error('Theme config loading not supported in browser environment');
+    }
+
+    // In ESM environments, require might be undefined.
+    let nodeRequire: any;
+    try {
+      nodeRequire = require;
+    } catch {
+      // require is not defined
+    }
+
+    if (!nodeRequire) {
+      throw new Error('Theme config loading not supported in this environment (require is undefined)');
+    }
+
+    // Type for config module
+    interface ConfigModule {
+      default?: any;
+      [key: string]: unknown;
+    }
+
+    let configModule: ConfigModule;
+
+    // First, try to resolve the config file path using our unified approach
+    let resolvedConfigPath: string | null = null;
+    
+    // If a specific config path is provided, try to use it
+    if (configPath && configPath !== DEFAULT_ATOMIX_CONFIG_PATH) {
+      const path = nodeRequire('path') as typeof import('path');
+      const fs = nodeRequire('fs') as typeof import('fs');
+      const fullPath = path.resolve(process.cwd(), configPath);
+      
+      if (fs.existsSync(fullPath)) {
+        resolvedConfigPath = fullPath;
+      }
+    } else {
+      // Otherwise, look for any of the supported config formats
+      const possiblePaths = [
+        'atomix.config.ts',
+        'atomix.config.js',
+        'atomix.config.json'
+      ];
+      
+      const path = nodeRequire('path') as typeof import('path');
+      const fs = nodeRequire('fs') as typeof import('fs');
+      
+      for (const fileName of possiblePaths) {
+        const fullPath = path.resolve(process.cwd(), fileName);
+        if (fs.existsSync(fullPath)) {
+          resolvedConfigPath = fullPath;
+          break;
+        }
+      }
+    }
+
+    if (!resolvedConfigPath) {
+      throw new ThemeError(
+        `Config file not found: ${configPath}`,
+        ThemeErrorCode.CONFIG_LOAD_FAILED,
+        { configPath }
+      );
+    }
+
+    // Handle JSON files differently
+    if (resolvedConfigPath.endsWith('.json')) {
+      const fs = nodeRequire('fs') as typeof import('fs');
+      configModule = JSON.parse(fs.readFileSync(resolvedConfigPath, 'utf8'));
+    } else {
+      // Use require (Node.js/CommonJS) for JS/TS files
+      try {
+        const resolvedPath = nodeRequire.resolve(resolvedConfigPath);
+        if (nodeRequire.cache && nodeRequire.cache[resolvedPath]) {
+          delete nodeRequire.cache[resolvedPath];
+        }
+        configModule = nodeRequire(resolvedConfigPath) as ConfigModule;
+      } catch (requireError) {
+        const errorMessage = requireError instanceof Error
+          ? requireError.message
+          : String(requireError);
+        throw new ThemeError(
+          `Cannot load config: ${errorMessage}`,
+          ThemeErrorCode.CONFIG_LOAD_FAILED,
+          { configPath: resolvedConfigPath, error: errorMessage }
+        );
+      }
+    }
+
+    const rawConfig = configModule.default || configModule;
+
+    // Process the AtomixConfig structure
+    const processedConfig: LoadedThemeConfig = {
+      themes: rawConfig.theme?.themes || {},
+      build: rawConfig.build || {},
+      runtime: rawConfig.runtime || {},
+      integration: rawConfig.integration || {},
+      dependencies: rawConfig.dependencies || {},
+      validated: false, // Will be set after validation
+      // Store tokens for generator
+      __tokens: rawConfig.theme?.tokens,
+      __extend: rawConfig.theme?.extend,
+    };
+
+    // Store the raw config in the result for later use
+    Object.assign(processedConfig, rawConfig);
+
+    config = processedConfig;
+
+    // Validate the config if requested
+    if (validate) {
+      const validationResult = validateConfig(config);
+      if (!validationResult.valid) {
+        logger.warn(`Configuration validation warnings:\n${validationResult.warnings.join('\n')}`);
+        if (validationResult.errors.length > 0) {
+          logger.error(`Configuration validation errors:\n${validationResult.errors.join('\n')}`);
+          throw new ThemeError(
+            'Configuration validation failed',
+            ThemeErrorCode.CONFIG_VALIDATION_FAILED,
+            { errors: validationResult.errors }
+          );
+        }
+      }
+      config.validated = true;
+    } else {
+      config.validated = false;
+    }
+
+    // Cache the loaded config
+    cachedConfig = config;
+
+    logger.info(`Successfully loaded theme configuration from ${resolvedConfigPath}`);
+    return config;
+  } catch (error) {
+    if (error instanceof ThemeError) {
+      throw error;
+    }
+    
+    throw new ThemeError(
+      `Failed to load theme configuration: ${(error as Error).message}`,
+      ThemeErrorCode.CONFIG_LOAD_FAILED,
+      { configPath, error: (error as Error).stack }
+    );
+  }
+}
+
+/**
+ * Clear the configuration cache
+ * 
+ * This is useful when the config file has been modified and needs to be reloaded
+ */
+export function clearConfigCache(): void {
+  cachedConfig = null;
+  logger.debug('Configuration cache cleared');
+}

package/src/lib/theme/core/createTheme.ts

@@ -1,93 +1,169 @@
 /**
  * Core Theme Functions
  *
- * Simplified theme system using DesignTokens only.
+ * Unified theme system that handles both DesignTokens and Theme objects.
  * Config-first approach: loads from atomix.config.ts when no input is provided.
+ * Config-first approach: loads advanced features from config when available.
  */
 
 import type { DesignTokens } from '../tokens/tokens';
+import type { Theme } from '../types';
 import type { GenerateCSSVariablesOptions } from '../generators/generateCSS';
 import { createTokens } from '../tokens/tokens';
 import { generateCSSVariables } from '../generators/generateCSS';
-import { ThemeError, ThemeErrorCode } from '../errors/errors';
+import { themeToDesignTokens } from '../adapters/themeAdapter';
+import { loadThemeFromConfigSync } from '../config/configLoader';
+import { loadAtomixConfig } from '../../config/loader';
 
 /**
- * Create theme CSS from DesignTokens
- *
+ * Create theme CSS from tokens or Theme object
+ * 
  * **Config-First Approach**: If no input is provided, loads from `atomix.config.ts`.
- *
- * @param input - DesignTokens (partial) or undefined (loads from config)
+ * Config file is required for automatic loading.
+ * 
+ * @param input - DesignTokens (partial), Theme object, or undefined (loads from config)
  * @param options - CSS generation options (prefix is automatically read from config if not provided)
  * @returns CSS string with custom properties
  * @throws Error if config loading fails when no input is provided
- *
+ * 
  * @example
  * ```typescript
- * // Loads from atomix.config.ts
+ * // Loads from atomix.config.ts (config file required)
  * const css = createTheme();
- *
+ * 
  * // Using DesignTokens
  * const css = createTheme({
  *   'primary': '#7c3aed',
  *   'spacing-4': '1rem',
  * });
- *
+ * 
+ * // Using Theme object
+ * const theme = createThemeObject({ palette: { primary: { main: '#7c3aed' } } });
+ * const css = createTheme(theme);
+ * 
  * // With custom options
  * const css = createTheme(undefined, { prefix: 'myapp', selector: ':root' });
  * ```
  */
 export function createTheme(
-  input?: Partial<DesignTokens>,
+  input?: Partial<DesignTokens> | Theme,
   options?: GenerateCSSVariablesOptions
 ): string {
-  // Validate options if provided
-  if (options?.prefix) {
-    const prefixPattern = /^[a-z][a-z0-9-]*$/;
-    if (!prefixPattern.test(options.prefix)) {
-      throw new ThemeError(
-        `Invalid CSS variable prefix: "${options.prefix}". Prefix must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens (e.g., "atomix", "my-app").`,
-        ThemeErrorCode.THEME_VALIDATION_FAILED,
-        { prefix: options.prefix, pattern: prefixPattern.toString() }
-      );
-    }
-  }
+  let tokens: Partial<DesignTokens>;
+  let configPrefix: string | undefined;
 
-  // Validate selector if provided
-  if (options?.selector) {
-    // Basic validation - selector should be a valid CSS selector
-    if (typeof options.selector !== 'string' || options.selector.trim().length === 0) {
-      throw new ThemeError(
-        `Invalid CSS selector: "${options.selector}". Selector must be a non-empty string (e.g., ":root", ".my-theme").`,
-        ThemeErrorCode.THEME_VALIDATION_FAILED,
-        { selector: options.selector }
-      );
+  // If no input provided, load from config (required)
+  if (!input) {
+    const configTokens = loadThemeFromConfigSync();
+    
+    // Get prefix from config
+    try {
+      // Use the imported function directly instead of require to avoid bundling issues
+      const config = loadAtomixConfig({ configPath: 'atomix.config.ts', required: true });
+      configPrefix = config?.prefix;
+    } catch (error) {
+      // Prefix loading failed, but tokens were loaded, so continue
+    }
+    
+    tokens = configTokens;
+  } else {
+    // Check if it's a Theme object
+    const isThemeObject = (input as any).__isJSTheme === true || 
+      ((input as any).palette && (input as any).typography);
+    
+    if (isThemeObject) {
+      // Convert Theme object to DesignTokens
+      tokens = themeToDesignTokens(input as Theme);
+    } else {
+      // Use DesignTokens directly
+      tokens = input as Partial<DesignTokens>;
     }
   }
 
+  // Merge with defaults and generate CSS
+  const allTokens = createTokens(tokens);
+
+  // Get prefix from options, config, or use default
+  const prefix = options?.prefix ?? configPrefix ?? 'atomix';
+
+  return generateCSSVariables(allTokens, { ...options, prefix });
+}
+
+// Helper type guard function
+function isThemeObject(obj: any): obj is Theme {
+  return obj && typeof obj === 'object' && (
+    obj.palette || 
+    obj.typography || 
+    obj.spacing || 
+    obj.breakpoints ||
+    obj.colors
+  );
+}
+
+/**
+ * Create theme CSS from tokens or Theme object (asynchronous version)
+ * 
+ * **Config-First Approach**: If no input is provided, loads from `atomix.config.ts`.
+ * Config file is required for automatic loading.
+ * 
+ * @param input - DesignTokens (partial), Theme object, or undefined (loads from config)
+ * @param options - CSS generation options (prefix is automatically read from config if not provided)
+ * @returns Promise resolving to CSS string with custom properties
+ * @throws Error if config loading fails when no input is provided
+ * 
+ * @example
+ * ```typescript
+ * // Loads from atomix.config.ts (config file required)
+ * const css = await createThemeAsync();
+ * 
+ * // Using DesignTokens
+ * const css = await createThemeAsync({
+ *   'primary': '#7c3aed',
+ *   'spacing-4': '1rem',
+ * });
+ * 
+ * // Using Theme object
+ * const theme = createThemeObject({ palette: { primary: { main: '#7c3aed' } } });
+ * const css = await createThemeAsync(theme);
+ * 
+ * // With custom options
+ * const css = await createThemeAsync(undefined, { prefix: 'myapp', selector: ':root' });
+ * ```
+ */
+export async function createThemeAsync(
+  input?: Partial<DesignTokens> | Theme,
+  options?: GenerateCSSVariablesOptions
+): Promise<string> {
   // Determine tokens based on input
   let tokens: Partial<DesignTokens>;
-
+  
   if (!input) {
-    // Auto-loading config from file system is removed for browser compatibility.
-    // If no input is provided, we return an empty theme (using defaults only) or user must provide tokens.
-    // This allows createTheme to be isomorphic.
-
-    // Warn in development if no input provided
-    if (process.env.NODE_ENV !== 'production' && typeof window !== 'undefined') {
-      console.warn('Atomix: createTheme() called without tokens. Using default tokens only.');
+    // Load from config when no input provided
+    if (typeof window !== 'undefined') {
+      throw new Error('createTheme: No input provided and config loading is not available in browser environment. Please provide tokens explicitly or use Node.js/SSR environment.');
     }
-
-    tokens = {};
-  } else {
-    // Validate input tokens structure
-    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
-      throw new ThemeError(
-        `Invalid tokens input. Expected an object with DesignTokens, but received: ${typeof input}.`,
-        ThemeErrorCode.THEME_VALIDATION_FAILED,
-        { inputType: typeof input }
-      );
+    
+    // Dynamically import config loaders in a way that prevents bundling in browser
+    const { loadThemeFromConfigSync } = await import('../config/configLoader');
+    const { loadAtomixConfig } = await import('../../config/loader');
+    
+    tokens = loadThemeFromConfigSync();
+    
+    // Get prefix from config if needed
+    if (!options?.prefix) {
+      try {
+        const config = loadAtomixConfig({ configPath: 'atomix.config.ts', required: false });
+        options = { ...options, prefix: config?.prefix || 'atomix' };
+      } catch (error) {
+        // If config loading fails, use default prefix
+        options = { ...options, prefix: 'atomix' };
+      }
     }
-
+  } else if (isThemeObject(input)) {
+    // Convert Theme object to DesignTokens
+    const { themeToDesignTokens } = await import('../adapters/themeAdapter');
+    tokens = themeToDesignTokens(input);
+  } else {
     // Use DesignTokens directly
     tokens = input;
   }

package/src/lib/theme/core/createThemeObject.ts

@@ -242,16 +242,16 @@ function createPaletteColor(color: Partial<PaletteColor> | string): PaletteColor
   if (typeof color === 'string') {
     return {
       main: color,
-      light: lighten(color),
-      dark: darken(color),
+      light: lighten(color, 0.15),
+      dark: darken(color, 0.15),
       contrastText: getContrastText(color),
     };
   }
 
   return {
     main: color.main || '#000000',
-    light: color.light || lighten(color.main || '#000000'),
-    dark: color.dark || darken(color.main || '#000000'),
+    light: color.light || lighten(color.main || '#000000', 0.15),
+    dark: color.dark || darken(color.main || '#000000', 0.15),
     contrastText: color.contrastText || getContrastText(color.main || '#000000'),
   };
 }
@@ -327,6 +327,7 @@ export function createThemeObject(...options: ThemeOptions[]): Theme {
     }),
     background: {
       default: mergedOptions.palette?.background?.default || DEFAULT_PALETTE.background.default,
+      paper: mergedOptions.palette?.background?.paper || DEFAULT_PALETTE.background.paper,
       subtle: mergedOptions.palette?.background?.subtle || DEFAULT_PALETTE.background.subtle,
     },
     text: {
@@ -334,6 +335,8 @@ export function createThemeObject(...options: ThemeOptions[]): Theme {
       secondary: mergedOptions.palette?.text?.secondary || DEFAULT_PALETTE.text.secondary,
       disabled: mergedOptions.palette?.text?.disabled || DEFAULT_PALETTE.text.disabled,
     },
+    // Spread other palette properties
+    ...mergedOptions.palette,
   };
 
   // Create typography

package/src/lib/theme/hooks/useThemeSwitcher.ts

@@ -0,0 +1,164 @@
+/**
+ * useThemeSwitcher Hook
+ * 
+ * React hook for managing theme switching with persistence and system preference detection.
+ * Provides an easy-to-use API for dark/light mode toggling.
+ * 
+ * @example
+ * ```tsx
+ * import { useThemeSwitcher } from '@shohojdhara/atomix/theme';
+ * 
+ * function ThemeToggle() {
+ *   const { mode, toggle, setMode, isDark } = useThemeSwitcher();
+ *   
+ *   return (
+ *     <button onClick={toggle}>
+ *       {isDark ? '☀️ Light' : '🌙 Dark'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import {
+  switchTheme,
+  toggleTheme,
+  getCurrentTheme,
+  getSystemTheme,
+  initializeTheme,
+  listenToSystemTheme,
+  type ThemeMode,
+  type ThemeSwitcherOptions,
+} from '../utils/themeUtils';
+
+export interface UseThemeSwitcherOptions extends ThemeSwitcherOptions {
+  /** Initial theme mode (default: 'system') */
+  initialMode?: ThemeMode;
+  /** Automatically sync with system preference (default: false) */
+  syncWithSystem?: boolean;
+}
+
+export interface UseThemeSwitcherReturn {
+  /** Current theme mode */
+  mode: ThemeMode;
+  /** Whether current theme is dark */
+  isDark: boolean;
+  /** Whether current theme is light */
+  isLight: boolean;
+  /** Toggle between light and dark */
+  toggle: () => ThemeMode;
+  /** Set specific theme mode */
+  setMode: (mode: ThemeMode) => void;
+  /** Reset to system preference */
+  resetToSystem: () => void;
+  /** Clear saved preference */
+  clearPreference: () => void;
+}
+
+/**
+ * Hook for managing theme switching
+ * 
+ * @param options - Configuration options
+ * @returns Theme switcher controls
+ */
+export function useThemeSwitcher(options: UseThemeSwitcherOptions = {}): UseThemeSwitcherReturn {
+  const {
+    initialMode = 'system',
+    syncWithSystem = false,
+    storageKey = 'atomix-theme',
+    enableTransition = true,
+    transitionDuration = 300,
+  } = options;
+
+  // State for current mode
+  const [mode, setModeState] = useState<ThemeMode>(() => {
+    if (typeof window === 'undefined') return initialMode;
+    
+    // Check for saved preference first
+    const saved = getCurrentTheme(storageKey);
+    if (saved && saved !== 'system') return saved;
+    
+    // Fall back to initial mode or system
+    return initialMode === 'system' ? getSystemTheme() : initialMode;
+  });
+
+  // Initialize theme on mount
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    
+    // Initialize with proper theme application
+    initializeTheme({
+      storageKey,
+      enableTransition,
+      transitionDuration,
+    });
+    
+    // Update state to match initialized theme
+    setModeState(getCurrentTheme(storageKey));
+  }, [storageKey, enableTransition, transitionDuration]);
+
+  // Listen for system theme changes if enabled
+  useEffect(() => {
+    if (!syncWithSystem) return;
+    
+    const cleanup = listenToSystemTheme((newMode) => {
+      setModeState(newMode);
+      switchTheme(newMode, {
+        storageKey,
+        enableTransition,
+        transitionDuration,
+      });
+    });
+    
+    return cleanup;
+  }, [syncWithSystem, storageKey, enableTransition, transitionDuration]);
+
+  // Toggle theme
+  const toggle = useCallback((): ThemeMode => {
+    const newMode = toggleTheme({
+      storageKey,
+      enableTransition,
+      transitionDuration,
+    });
+    setModeState(newMode);
+    return newMode;
+  }, [storageKey, enableTransition, transitionDuration]);
+
+  // Set specific mode
+  const setMode = useCallback((newMode: ThemeMode) => {
+    switchTheme(newMode, {
+      storageKey,
+      enableTransition,
+      transitionDuration,
+    });
+    setModeState(newMode);
+  }, [storageKey, enableTransition, transitionDuration]);
+
+  // Reset to system preference
+  const resetToSystem = useCallback(() => {
+    const systemMode = getSystemTheme();
+    switchTheme(systemMode, {
+      storageKey,
+      enableTransition,
+      transitionDuration,
+    });
+    setModeState(systemMode);
+  }, [storageKey, enableTransition, transitionDuration]);
+
+  // Clear saved preference
+  const clearPreference = useCallback(() => {
+    if (typeof window === 'undefined') return;
+    localStorage.removeItem(storageKey);
+  }, [storageKey]);
+
+  return {
+    mode,
+    isDark: mode === 'dark',
+    isLight: mode === 'light',
+    toggle,
+    setMode,
+    resetToSystem,
+    clearPreference,
+  };
+}