@shohojdhara/atomix 0.3.5 → 0.3.7

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

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.ts → errors/errors.ts}

@@ -120,7 +120,7 @@ export class ThemeLogger {
 
   constructor(config: LoggerConfig = {}) {
     this.config = {
-      level: config.level ?? (process.env.NODE_ENV === 'production' ? LogLevel.WARN : LogLevel.INFO),
+      level: config.level ?? (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production' ? LogLevel.WARN : LogLevel.INFO),
       enableConsole: config.enableConsole ?? true,
       onError: config.onError,
       onWarn: config.onWarn,

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/generators/generateCSSNested.ts

@@ -0,0 +1,130 @@
+/**
+ * CSS Variable Generator for Nested Tokens
+ *
+ * Generates CSS custom properties from nested token structures.
+ */
+
+import type { DesignTokens } from '../tokens/tokens';
+import { generateCSSVariables } from './generateCSS';
+import { ThemeNaming } from '../../utils/themeNaming';
+
+/**
+ * Options for CSS variable generation with nested support
+ */
+export interface GenerateNestedCSSVariablesOptions {
+  /** CSS selector for the variables (default: ':root') */
+  selector?: string;
+  /** Prefix for CSS variables (default: 'atomix') */
+  prefix?: string;
+  /** Separator for nested tokens (default: '-') */
+  separator?: string;
+  /** Whether to flatten nested objects (default: true) */
+  flatten?: boolean;
+}
+
+/**
+ * Generate CSS variables from nested token structure
+ *
+ * Converts nested token object to CSS custom properties.
+ * Supports both nested objects and flat token structures.
+ *
+ * @param tokens - Design tokens object (can be nested)
+ * @param options - Generation options
+ * @returns CSS string with custom properties
+ *
+ * @example
+ * ```typescript
+ * const tokens = {
+ *   color: {
+ *     primary: '#7c3aed',
+ *     secondary: '#10b981',
+ *   },
+ *   spacing: {
+ *     small: '0.5rem',
+ *     medium: '1rem',
+ *   },
+ * };
+ *
+ * const css = generateNestedCSSVariables(tokens);
+ * // Returns: ":root {
+  --atomix-color-primary: #7c3aed;
+  --atomix-color-secondary: #10b981;
+  --atomix-spacing-small: 0.5rem;
+  --atomix-spacing-medium: 1rem;
+}"
+ * ```
+ */
+export function generateNestedCSSVariables(
+  tokens: DesignTokens,
+  options: GenerateNestedCSSVariablesOptions = {}
+): string {
+  const {
+    selector = ':root',
+    prefix = 'atomix',
+    separator = '-',
+    flatten = true,
+  } = options;
+
+  // Flatten nested token structure
+  const flattened = flatten ? flattenTokens(tokens, separator) : tokens;
+
+  // Generate CSS variables using the original function
+  return generateCSSVariables(flattened, { selector, prefix });
+}
+
+/**
+ * Flatten nested token structure
+ *
+ * @param tokens - Token object (can be nested)
+ * @param separator - Separator for nested keys
+ * @returns Flattened token object
+ */
+function flattenTokens(tokens: DesignTokens, separator: string): DesignTokens {
+  const result: DesignTokens = {};
+
+  for (const [key, value] of Object.entries(tokens)) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      // Recursively flatten nested objects
+      const flattened = flattenTokens(value, separator);
+
+      // Combine keys with separator
+      for (const [nestedKey, nestedValue] of Object.entries(flattened)) {
+        const newKey = `${key}${separator}${nestedKey}`;
+        result[newKey] = nestedValue;
+      }
+    } else {
+      // Direct value
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Generate CSS variables with custom selector for nested tokens
+ *
+ * @param tokens - Design tokens object
+ * @param selector - CSS selector (e.g., '[data-theme="dark"]')
+ * @param prefix - CSS variable prefix
+ * @param separator - Separator for nested keys
+ * @returns CSS string
+ *
+ * @example
+ * ```typescript
+ * const css = generateNestedCSSVariablesForSelector(
+ *   tokens,
+ *   '[data-theme="dark"]',
+ *   'atomix',
+ *   '-'
+ * );
+ * ```
+ */
+export function generateNestedCSSVariablesForSelector(
+  tokens: DesignTokens,
+  selector: string,
+  prefix: string = 'atomix',
+  separator: string = '-'
+): string {
+  return generateNestedCSSVariables(tokens, { selector, prefix, separator });
+}

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
@@ -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,25 @@
+/**
+ * CSS Generators
+ * 
+ * Generators for creating CSS from themes and tokens
+ */
+
+export {
+  generateCSSVariables,
+  generateCSSVariablesForSelector,
+  type GenerateCSSVariablesOptions,
+} from './generateCSS';
+
+export {
+  generateNestedCSSVariables,
+  generateNestedCSSVariablesForSelector,
+  type GenerateNestedCSSVariablesOptions,
+} from './generateCSSNested';
+
+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,
 };