@shohojdhara/atomix 0.3.4 → 0.3.6

package/src/lib/theme/{core → devtools}/ThemeValidator.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Theme, ThemeMetadata } from '../types';
-import { getContrastRatio, getLuminance } from '../themeUtils';
+import { getContrastRatio, getLuminance } from '../utils/themeUtils';
 
 /**
  * Validation result
@@ -392,8 +392,11 @@ export class ThemeValidator {
 
     for (let i = 0; i < numericEntries.length; i++) {
       for (let j = i + 1; j < numericEntries.length; j++) {
-        const [keyA, valueA] = numericEntries[i];
-        const [keyB, valueB] = numericEntries[j];
+        const entryA = numericEntries[i];
+        const entryB = numericEntries[j];
+        if (!entryA || !entryB) continue;
+        const [keyA, valueA] = entryA;
+        const [keyB, valueB] = entryB;
         const diff = Math.abs(valueA - valueB);
         if (diff < 10 && diff > 0) {
           warnings.push(

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

@@ -4,10 +4,6 @@
  * Developer tools for theme management and debugging
  */
 
-// CLI Tools
-export { ThemeCLI, createCLI, runCLI } from './CLI';
-export type { CLICommand } from './CLI';
-
 // React Components
 export { ThemePreview } from './Preview';
 export type { ThemePreviewProps } from './Preview';
@@ -20,3 +16,17 @@ export type { ThemeComparatorProps } from './Comparator';
 
 export { ThemeLiveEditor } from './LiveEditor';
 export type { ThemeLiveEditorProps } from './LiveEditor';
+
+// Validator (devtools only)
+export { ThemeValidator } from './ThemeValidator';
+export type {
+  ValidationResult,
+  A11yIssue,
+} from './ThemeValidator';
+
+// Hooks
+export { useHistory } from './useHistory';
+export type {
+  UseHistoryOptions,
+  UseHistoryReturn,
+} from './useHistory';

package/src/lib/theme/devtools/useHistory.ts

@@ -0,0 +1,130 @@
+/**
+ * useHistory Hook
+ * 
+ * React hook for managing undo/redo history
+ */
+
+import { useState, useCallback, useRef, useEffect } from 'react';
+
+export interface UseHistoryOptions {
+  /** Maximum number of history entries (default: 50) */
+  maxHistorySize?: number;
+  /** Initial state */
+  initialState?: any;
+}
+
+export interface UseHistoryReturn<T> {
+  /** Current state */
+  state: T;
+  /** Update state and add to history */
+  setState: (newState: T) => void;
+  /** Undo last change */
+  undo: () => void;
+  /** Redo last undone change */
+  redo: () => void;
+  /** Check if undo is available */
+  canUndo: boolean;
+  /** Check if redo is available */
+  canRedo: boolean;
+  /** Clear history */
+  clearHistory: () => void;
+  /** Get history statistics */
+  getHistoryStats: () => { currentIndex: number; totalEntries: number };
+}
+
+/**
+ * useHistory hook
+ * 
+ * Provides undo/redo functionality for state management
+ * 
+ * @example
+ * ```tsx
+ * const { state, setState, undo, redo, canUndo, canRedo } = useHistory({
+ *   initialState: theme,
+ *   maxHistorySize: 50
+ * });
+ * ```
+ */
+export function useHistory<T>(options: UseHistoryOptions = {}): UseHistoryReturn<T> {
+  const { maxHistorySize = 50, initialState } = options;
+  
+  const [state, setStateInternal] = useState<T>(initialState as T);
+  const historyRef = useRef<T[]>([initialState as T]);
+  const currentIndexRef = useRef<number>(0);
+  const [canUndo, setCanUndo] = useState(false);
+  const [canRedo, setCanRedo] = useState(false);
+
+  const updateHistoryState = useCallback(() => {
+    setCanUndo(currentIndexRef.current > 0);
+    setCanRedo(currentIndexRef.current < historyRef.current.length - 1);
+  }, []);
+
+  const setState = useCallback((newState: T) => {
+    // Remove any future history if we're not at the end
+    if (currentIndexRef.current < historyRef.current.length - 1) {
+      historyRef.current = historyRef.current.slice(0, currentIndexRef.current + 1);
+    }
+
+    // Add new state to history
+    historyRef.current.push(newState);
+    currentIndexRef.current = historyRef.current.length - 1;
+
+    // Limit history size
+    if (historyRef.current.length > maxHistorySize) {
+      historyRef.current.shift();
+      currentIndexRef.current--;
+    }
+
+    setStateInternal(newState);
+    updateHistoryState();
+  }, [maxHistorySize, updateHistoryState]);
+
+  const undo = useCallback(() => {
+    if (currentIndexRef.current > 0) {
+      currentIndexRef.current--;
+      const previousState = historyRef.current[currentIndexRef.current];
+      setStateInternal(previousState as T);
+      updateHistoryState();
+    }
+  }, [updateHistoryState]);
+
+  const redo = useCallback(() => {
+    if (currentIndexRef.current < historyRef.current.length - 1) {
+      currentIndexRef.current++;
+      const nextState = historyRef.current[currentIndexRef.current];
+      setStateInternal(nextState as T);
+      updateHistoryState();
+    }
+  }, [updateHistoryState]);
+
+  const clearHistory = useCallback(() => {
+    const currentState = historyRef.current[currentIndexRef.current];
+    historyRef.current = [currentState as T];
+    currentIndexRef.current = 0;
+    updateHistoryState();
+  }, [updateHistoryState]);
+
+  const getHistoryStats = useCallback(() => {
+    return {
+      currentIndex: currentIndexRef.current,
+      totalEntries: historyRef.current.length,
+    };
+  }, []);
+
+  // Initialize undo/redo state
+  useEffect(() => {
+    updateHistoryState();
+  }, [updateHistoryState]);
+
+  return {
+    state,
+    setState,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    clearHistory,
+    getHistoryStats,
+  };
+}
+

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

@@ -0,0 +1,12 @@
+/**
+ * Theme Errors
+ * 
+ * Error classes and error handling utilities
+ */
+
+export {
+  ThemeError,
+  ThemeErrorCode,
+  getLogger,
+} from './errors';
+

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

@@ -0,0 +1,79 @@
+/**
+ * CSS File Utilities
+ * 
+ * Save CSS to file system (Node.js only).
+ */
+
+/**
+ * Save CSS to file
+ * 
+ * Writes CSS string to a file. Only works in Node.js environment.
+ * 
+ * @param css - CSS string to save
+ * @param filePath - Output file path
+ * @throws Error if called in browser environment
+ * 
+ * @example
+ * ```typescript
+ * const css = ':root { --atomix-color-primary: #7AFFD7; }';
+ * await saveCSSFile(css, './themes/custom.css');
+ * ```
+ */
+export async function saveCSSFile(
+  css: string,
+  filePath: string
+): Promise<void> {
+  // Check if in browser environment
+  if (typeof window !== 'undefined') {
+    throw new Error(
+      'saveCSSFile can only be used in Node.js environment. ' +
+      'Use injectCSS() for browser environments.'
+    );
+  }
+
+  // Dynamic import to avoid bundling Node.js modules in browser builds
+  const fs = await import('fs/promises');
+  const path = await import('path');
+
+  // Ensure directory exists
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true });
+
+  // Write file
+  await fs.writeFile(filePath, css, 'utf8');
+}
+
+/**
+ * Save CSS to file (synchronous version)
+ * 
+ * Synchronous version of saveCSSFile. Only works in Node.js environment.
+ * 
+ * @param css - CSS string to save
+ * @param filePath - Output file path
+ * @throws Error if called in browser environment
+ */
+export function saveCSSFileSync(css: string, filePath: string): void {
+  // Check if in browser environment
+  if (typeof window !== 'undefined') {
+    throw new Error(
+      'saveCSSFileSync can only be used in Node.js environment. ' +
+      'Use injectCSS() for browser environments.'
+    );
+  }
+
+  // Use require for synchronous file operations
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const fs = require('fs');
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const path = require('path');
+
+  // Ensure directory exists
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Write file
+  fs.writeFileSync(filePath, css, 'utf8');
+}
+

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

@@ -0,0 +1,89 @@
+/**
+ * CSS Variable Generator
+ * 
+ * Generates CSS custom properties from design tokens.
+ */
+
+import type { DesignTokens } from '../tokens/tokens';
+
+/**
+ * Options for CSS variable generation
+ */
+export interface GenerateCSSVariablesOptions {
+  /** CSS selector for the variables (default: ':root') */
+  selector?: string;
+  /** Prefix for CSS variables (default: 'atomix') */
+  prefix?: string;
+}
+
+/**
+ * Generate CSS variables from tokens
+ * 
+ * Converts flat token object to CSS custom properties.
+ * 
+ * @param tokens - Design tokens object
+ * @param options - Generation options
+ * @returns CSS string with custom properties
+ * 
+ * @example
+ * ```typescript
+ * const tokens = {
+ *   'primary': '#7c3aed',
+ *   'spacing-4': '1rem',
+ * };
+ * 
+ * const css = generateCSSVariables(tokens);
+ * // Returns: ":root {\n  --atomix-primary: #7c3aed;\n  --atomix-spacing-4: 1rem;\n}"
+ * ```
+ */
+export function generateCSSVariables(
+  tokens: DesignTokens,
+  options: GenerateCSSVariablesOptions = {}
+): string {
+  const {
+    selector = ':root',
+    prefix = 'atomix',
+  } = options;
+
+  // Filter out undefined values and generate CSS variables
+  const variables = Object.entries(tokens)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => {
+      // Convert token key to CSS variable name
+      // 'color-primary' -> '--atomix-color-primary'
+      const varName = `--${prefix}-${key}`;
+      return `  ${varName}: ${value};`;
+    })
+    .join('\n');
+
+  // Return formatted CSS
+  return `${selector} {\n${variables}\n}`;
+}
+
+/**
+ * Generate CSS variables with custom selector
+ * 
+ * Useful for theme-specific selectors like `[data-theme="dark"]`
+ * 
+ * @param tokens - Design tokens object
+ * @param selector - CSS selector (e.g., '[data-theme="dark"]')
+ * @param prefix - CSS variable prefix
+ * @returns CSS string
+ * 
+ * @example
+ * ```typescript
+ * const css = generateCSSVariablesForSelector(
+ *   tokens,
+ *   '[data-theme="dark"]',
+ *   'atomix'
+ * );
+ * ```
+ */
+export function generateCSSVariablesForSelector(
+  tokens: DesignTokens,
+  selector: string,
+  prefix: string = 'atomix'
+): string {
+  return generateCSSVariables(tokens, { selector, prefix });
+}
+

package/src/lib/theme/{generateCSSVariables.ts → generators/generateCSSVariables.ts}

@@ -16,9 +16,9 @@
  * @see src/styles/03-generic/_generic.root.scss for SCSS token definitions
  */
 
-import type { Theme } from './types';
-import { isBrowser } from './utils';
-import { hexToRgb, alpha, lighten, darken, emphasize } from './themeUtils';
+import type { Theme } from '../types';
+import { isBrowser } from '../utils/domUtils';
+import { hexToRgb, alpha, lighten, darken, emphasize } from '../utils/themeUtils';
 
 // ============================================================================
 // CSS Variable Generation
@@ -47,7 +47,7 @@ function flattenObject(
     result: Record<string, string> = {}
 ): Record<string, string> {
     for (const key in obj) {
-        if (!obj.hasOwnProperty(key)) continue;
+        if (!Object.prototype.hasOwnProperty.call(obj, key)) continue;
 
         const value = obj[key];
         const newKey = prefix ? `${prefix}-${key}` : key;
@@ -133,14 +133,6 @@ function generatePaletteVariables(palette: Theme['palette'], prefix: string): Re
             if (key !== 'light' && key !== 'dark') {
                 const colorScale = generateColorScale(color.main, prefix, key);
                 Object.assign(vars, colorScale);
-                
-                // Add semantic aliases that map to scale steps (for backward compatibility)
-                // primary-main → primary-6 (main color)
-                vars[`${prefix}-${key}-main`] = colorScale[`${prefix}-${key}-6`] || color.main;
-                // primary-light → primary-3 (light variant)
-                vars[`${prefix}-${key}-light`] = colorScale[`${prefix}-${key}-3`] || color.light || color.main;
-                // primary-dark → primary-9 (dark variant)
-                vars[`${prefix}-${key}-dark`] = colorScale[`${prefix}-${key}-9`] || color.dark || color.main;
             } else {
                 // For light/dark, use the provided values directly
                 vars[`${prefix}-${key}-main`] = color.main;
@@ -658,8 +650,6 @@ function generateBorderRadiusVariables(
 
     // 2X large border radius (maps to spacing-4 = 16px)
     vars[`${prefix}-border-radius-xxl`] = formatValue(borderRadius.xxl, '1rem');
-    // Also add deprecated 2xl alias for consistency
-    vars[`${prefix}-border-radius-2xl`] = formatValue(borderRadius.xxl, '1rem');
 
     // 3X large border radius (maps to spacing-6 = 24px)
     vars[`${prefix}-border-radius-3xl`] = formatValue(borderRadius['3xl'], '1.5rem');

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

@@ -0,0 +1,19 @@
+/**
+ * CSS Generators
+ * 
+ * Generators for creating CSS from themes and tokens
+ */
+
+export {
+  generateCSSVariables,
+  generateCSSVariablesForSelector,
+  type GenerateCSSVariablesOptions,
+} from './generateCSS';
+
+export { generateCSSVariables as generateCSSVariablesFromTheme } from './generateCSSVariables';
+
+export {
+  saveCSSFile,
+  saveCSSFileSync,
+} from './cssFile';
+

package/src/lib/theme/i18n/rtl.ts

@@ -4,7 +4,8 @@
  * Provides utilities for managing RTL text direction in themes
  */
 
-import { getLogger } from '../errors';
+import { getLogger } from '../errors/errors';
+import { DEFAULT_RTL_CONFIG as BASE_RTL_CONFIG } from '../constants/constants';
 
 /**
  * RTL configuration options
@@ -38,14 +39,12 @@ const RTL_LOCALES = new Set([
   'sd', // Sindhi
 ]);
 
+
 /**
- * Default RTL configuration
+ * Default RTL configuration (extends base config with locale)
  */
 const DEFAULT_RTL_CONFIG: Required<Omit<RTLConfig, 'locale'>> & { locale?: string } = {
-  enabled: false,
-  direction: 'ltr',
-  dataAttribute: 'data-direction',
-  autoDetect: false,
+  ...BASE_RTL_CONFIG,
   locale: undefined,
 };
 
@@ -93,7 +92,8 @@ export class RTLManager {
 
     // Try navigator.language first
     const lang: string = navigator.language || (navigator.languages && navigator.languages[0]) || 'en';
-    return String(lang).split('-')[0].toLowerCase();
+    const langParts = String(lang).split('-');
+    return langParts[0] ? langParts[0].toLowerCase() : 'en';
   }
 
   /**

package/src/lib/theme/index.ts

@@ -1,28 +1,134 @@
 /**
  * Theme System Exports
  * 
- * Central export point for all theme-related functionality
+ * Unified theme system - handles both DesignTokens and Theme objects.
+ * 
+ * @example
+ * ```typescript
+ * import { createTheme, injectTheme } from '@shohojdhara/atomix/theme';
+ * 
+ * // Using DesignTokens (recommended - flat structure)
+ * const css = createTheme({ 'primary': '#7AFFD7', 'spacing-4': '1rem' });
+ * injectTheme(css);
+ * 
+ * // Or use with ThemeProvider
+ * import { ThemeProvider } from '@shohojdhara/atomix/theme';
+ * const tokens = { 'primary': '#7c3aed' };
+ * <ThemeProvider defaultTheme={tokens}>...</ThemeProvider>
+ * ```
+ */
+
+// ============================================================================
+// Core Theme Functions
+// ============================================================================
+
+// Unified createTheme (handles both DesignTokens and Theme objects)
+export { createTheme } from './core';
+
+// Theme object creation
+export { createThemeObject } from './core';
+
+// Theme composition
+export { deepMerge, mergeTheme, extendTheme } from './core';
+
+// Theme registry
+export { ThemeRegistry } from './core';
+
+// ============================================================================
+// Theme Injection and Management
+// ============================================================================
+
+import { injectCSS, removeCSS, isCSSInjected } from './utils/injectCSS';
+import { saveCSSFile, saveCSSFileSync } from './generators/cssFile';
+
+/**
+ * Inject theme CSS into DOM
+ */
+export function injectTheme(css: string, id: string = 'atomix-theme'): void {
+  injectCSS(css, id);
+}
+
+/**
+ * Remove theme from DOM
+ */
+export function removeTheme(id: string = 'atomix-theme'): void {
+  removeCSS(id);
+}
+
+/**
+ * Save theme to CSS file
  */
+export async function saveTheme(css: string, filePath: string): Promise<void> {
+  await saveCSSFile(css, filePath);
+}
 
-// Core theme system
+// ============================================================================
+// Token Utilities
+// ============================================================================
+
+export { createTokens, defaultTokens, type DesignTokens } from './tokens';
+
+// ============================================================================
+// CSS Generation
+// ============================================================================
+
+export {
+  generateCSSVariables,
+  generateCSSVariablesForSelector,
+  type GenerateCSSVariablesOptions,
+} from './generators';
+
+// ============================================================================
+// Injection Utilities
+// ============================================================================
+
+export { injectCSS, removeCSS, isCSSInjected } from './utils/injectCSS';
+
+// ============================================================================
+// File Utilities
+// ============================================================================
+
+export { saveCSSFile, saveCSSFileSync } from './generators/cssFile';
+
+// ============================================================================
+// Config Loader
+// ============================================================================
+
+export {
+  loadThemeFromConfig,
+  loadThemeFromConfigSync,
+} from './config/configLoader';
+
+// ============================================================================
+// React Integration
+// ============================================================================
+
+// Core React components and hooks
 export { ThemeProvider } from './runtime/ThemeProvider';
 export { useTheme } from './runtime/useTheme';
-export { ThemeContext } from './ThemeContext';
-export { ThemeManager } from './runtime/ThemeManager';
+export { ThemeContext } from './runtime/ThemeContext';
 export { ThemeErrorBoundary } from './runtime/ThemeErrorBoundary';
 
-// Theme creation
-export { createTheme } from './createTheme';
-export { createThemeFromConfig } from './createThemeFromConfig';
-
-// Theme utilities
-export { quickTheme, createDarkVariant, validateTheme, themeToCSS, exportTheme, importTheme } from '../theme-tools';
+// Theme application
+export { ThemeApplicator, getThemeApplicator, applyTheme } from './runtime/ThemeApplicator';
 
 // DevTools (for development and debugging)
 export * from './devtools';
 
-// Theme application
-export { ThemeApplicator, getThemeApplicator, applyTheme, removeTheme } from './runtime/ThemeApplicator';
+// Theme adapter (converts between Theme and DesignTokens)
+export {
+  themeToDesignTokens,
+  designTokensToCSSVars,
+  createDesignTokensFromTheme,
+  designTokensToTheme,
+} from './adapters';
+
+// Theme helpers (utilities for working with themes and DesignTokens)
+export {
+  getDesignTokensFromTheme,
+  isDesignTokens,
+  isThemeObject,
+} from './utils/themeHelpers';
 
 // CSS variable utilities
 export {
@@ -36,7 +142,7 @@ export {
   mergeCSSVars,
   isValidCSSVariableName,
   extractComponentName,
-} from './cssVariableMapper';
+} from './adapters/cssVariableMapper';
 
 // RTL Support
 export { RTLManager } from './i18n/rtl';
@@ -45,7 +151,6 @@ export { RTLManager } from './i18n/rtl';
 export type {
   Theme,
   ThemeMetadata,
-  ThemeManagerConfig,
   ThemeChangeEvent,
   ThemeLoadOptions,
   ThemeValidationResult,
@@ -61,6 +166,6 @@ export type { ThemeErrorBoundaryProps } from './runtime/ThemeErrorBoundary';
 export type {
   CSSVariableConfig,
   CSSVariableNamingOptions,
-} from './cssVariableMapper';
+} from './adapters/cssVariableMapper';
 
 export type { RTLConfig } from './i18n/rtl';