@shohojdhara/atomix 0.5.2 → 0.5.4

package/src/lib/config/types.ts

@@ -0,0 +1,389 @@
+/**
+ * Configuration Types
+ *
+ * Type definitions for the Atomix configuration system.
+ */
+
+import type { Theme } from '../theme/types';
+
+/**
+ * Design token categories
+ */
+export type DesignTokenCategory =
+  | 'colors'
+  | 'spacing'
+  | 'typography'
+  | 'borderRadius'
+  | 'shadows'
+  | 'zIndex'
+  | 'transitions'
+  | 'breakpoints';
+
+/**
+ * Design token value types
+ */
+export type DesignTokenValue = string | number;
+
+/**
+ * Color Scale (1-10)
+ */
+export interface ColorScale {
+  1?: string;
+  2?: string;
+  3?: string;
+  4?: string;
+  5?: string;
+  6?: string;
+  7?: string;
+  8?: string;
+  9?: string;
+  10?: string;
+  [key: string]: string | undefined;
+}
+
+/**
+ * Palette Color Options
+ */
+export interface PaletteColorOptions {
+  main: string;
+  light?: string;
+  dark?: string;
+  contrastText?: string;
+}
+
+/**
+ * Interactive Effect Configuration
+ */
+export interface InteractiveEffectsConfig {
+  /** Vortex & flow field effects */
+  vortex?: {
+    enabled?: boolean;
+    strength?: number;
+    radius?: number;
+    decay?: number;
+    curlNoise?: boolean;
+    velocityTracking?: boolean;
+  };
+
+  /** Chromatic aberration effects */
+  chromaticAberration?: {
+    enabled?: boolean;
+    mode?: 'longitudinal' | 'lateral' | 'hybrid';
+    redShift?: number;
+    greenShift?: number;
+    blueShift?: number;
+    edgeOnly?: boolean;
+    edgeThreshold?: number;
+  };
+
+  /** Mouse interaction settings */
+  mouseInteraction?: {
+    sensitivity?: number;
+    trailEffect?: boolean;
+    pressureSensitivity?: boolean;
+  };
+
+  /** Animation speed controls */
+  animationSpeed?: {
+    base?: number;
+    timeMultiplier?: number;
+  };
+}
+
+/**
+ * Optimization Configuration
+ */
+export interface OptimizationConfig {
+  /** Responsive breakpoint system */
+  responsive?: {
+    breakpoints?: {
+      mobile?: string;
+      tablet?: string;
+      desktop?: string;
+      wide?: string;
+    };
+    /** Device-aware parameter scaling */
+    deviceScaling?: {
+      mobile?: number;
+      tablet?: number;
+      desktop?: number;
+    };
+  };
+
+  /** Performance monitoring */
+  performance?: {
+    enabled?: boolean;
+    fpsTarget?: number;
+    autoScaling?: boolean;
+    monitorDashboard?: boolean;
+  };
+
+  /** Auto-scaling logic based on device capabilities */
+  autoScaling?: {
+    enabled?: boolean;
+    qualityThresholds?: {
+      lowEnd?: number;
+      midRange?: number;
+      highEnd?: number;
+    };
+  };
+}
+
+/**
+ * Visual Polish Configuration
+ */
+export interface VisualPolishConfig {
+  /** Advanced border effects */
+  borders?: {
+    iridescentGlow?: boolean;
+    shimmerEffect?: boolean;
+    beveledEdges?: boolean;
+    pulsingGlow?: boolean;
+  };
+
+  /** Content-aware blur */
+  contentAwareBlur?: {
+    enabled?: boolean;
+    depthDetection?: boolean;
+    edgePreservation?: boolean;
+    variableRadius?: boolean;
+  };
+
+  /** Holographic effect modes */
+  holographicEffects?: {
+    enabled?: boolean;
+    rainbowDiffraction?: boolean;
+    scanlineAnimation?: boolean;
+    gridOverlay?: boolean;
+    dataStream?: boolean;
+    pulseRings?: boolean;
+  };
+}
+
+/**
+ * Design Tokens Schema (Tailwind-like)
+ */
+export interface ThemeTokens {
+  /** Color palette */
+  colors?: Record<string, string | PaletteColorOptions | ColorScale | Record<string, string>>;
+  /** Spacing scale */
+  spacing?: Record<string, string>;
+  /** Border radius scale */
+  borderRadius?: Record<string, string>;
+  /** Typography scale and settings */
+  typography?: {
+    fontFamilies?: Record<string, string>;
+    fontSizes?: Record<string, string>;
+    fontWeights?: Record<string, string | number>;
+    lineHeights?: Record<string, string | number>;
+    letterSpacings?: Record<string, string>;
+  };
+  /** Shadow scale */
+  shadows?: Record<string, string>;
+  /** Z-index scale */
+  zIndex?: Record<string, string | number>;
+  /** Breakpoints scale */
+  breakpoints?: Record<string, string | number>;
+  /** Transitions settings */
+  transitions?: {
+    durations?: Record<string, string>;
+    easings?: Record<string, string>;
+  };
+}
+
+/**
+ * CSS Theme Definition
+ */
+export interface CSSThemeDefinition {
+  type: 'css';
+  name: string;
+  class?: string;
+  description?: string;
+  author?: string;
+  version?: string;
+  tags?: string[];
+  supportsDarkMode?: boolean;
+  status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
+  a11y?: {
+    contrastTarget?: number;
+    modes?: string[];
+  };
+  color?: string;
+  features?: string[];
+  dependencies?: string[];
+  cssPath?: string;
+}
+
+/**
+ * JavaScript Theme Definition
+ */
+export interface JSThemeDefinition {
+  type: 'js';
+  name: string;
+  class?: string;
+  description?: string;
+  author?: string;
+  version?: string;
+  tags?: string[];
+  supportsDarkMode?: boolean;
+  status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
+  a11y?: {
+    contrastTarget?: number;
+    modes?: string[];
+  };
+  color?: string;
+  features?: string[];
+  dependencies?: string[];
+  createTheme: () => Theme;
+}
+
+/**
+ * Theme Definition (CSS or JS)
+ */
+export type ThemeDefinition = CSSThemeDefinition | JSThemeDefinition;
+
+/**
+ * Build configuration
+ */
+export interface BuildConfig {
+  output?: {
+    directory?: string;
+    formats?: {
+      expanded?: string;
+      compressed?: string;
+    };
+  };
+  sass?: {
+    style?: 'expanded' | 'compressed';
+    sourceMap?: boolean;
+    loadPaths?: string[];
+  };
+}
+
+/**
+ * Runtime configuration
+ */
+export interface RuntimeConfig {
+  basePath?: string;
+  cdnPath?: string | null;
+  preload?: string[];
+  lazy?: boolean;
+  defaultTheme?: string;
+  storageKey?: string;
+  dataAttribute?: string;
+  enablePersistence?: boolean;
+  useMinified?: boolean;
+}
+
+/**
+ * Integration settings
+ */
+export interface IntegrationConfig {
+  cssVariables?: Record<string, string>;
+  classNames?: {
+    theme?: string;
+    colorMode?: string;
+  };
+}
+
+/**
+ * Plugin Configuration
+ */
+export interface PluginConfig {
+  name: string;
+  options?: Record<string, any>;
+}
+
+/**
+ * Token Provider Configuration
+ */
+export interface TokenProviderConfig {
+  type: 'figma' | 'style-dictionary' | 'w3c' | string;
+  options?: Record<string, any>;
+}
+
+/**
+ * Token Engine Configuration
+ */
+export interface TokenEngineConfig {
+  providers?: Record<string, TokenProviderConfig>;
+  sync?: {
+    pull?: boolean;
+    push?: boolean;
+    onBuild?: boolean;
+  };
+}
+
+/**
+ * CLI component generator defaults
+ */
+export interface GeneratorConfig {
+  /** Default output directory for generated components */
+  outputPath?: string;
+  /** Override detected framework */
+  framework?: 'react' | 'next' | 'vanilla';
+  /** Per-feature defaults */
+  features?: {
+    storybook?: boolean;
+    hook?: boolean;
+    styles?: boolean;
+    tests?: boolean;
+  };
+  /** Composable hooks directory relative to project root */
+  hookOutputDir?: string;
+  /** Story file: side-effect import for global Atomix styles */
+  storybookCssImport?: string;
+  /** Barrel file strategy for new components */
+  barrel?: 'index' | 'none';
+}
+
+/**
+ * Atomix Configuration Interface
+ *
+ * Tailwind-like configuration for external developers.
+ */
+export interface AtomixConfig {
+  prefix?: string;
+  plugins?: (string | PluginConfig)[];
+  tokenEngine?: TokenEngineConfig;
+  ai?: {
+    provider?: 'openai' | 'anthropic';
+    model?: string;
+    apiKey?: string;
+    temperature?: number;
+    maxTokens?: number;
+    rateLimit?: {
+      requests: number;
+      windowMs: number;
+    };
+  };
+  telemetry?: {
+    enabled?: boolean;
+    path?: string;
+    anonymize?: boolean;
+  };
+  generator?: GeneratorConfig;
+  interactiveEffects?: InteractiveEffectsConfig;
+  optimization?: OptimizationConfig;
+  visualPolish?: VisualPolishConfig;
+  theme?: {
+    extend?: ThemeTokens;
+    tokens?: ThemeTokens;
+    themes?: Record<string, ThemeDefinition>;
+  };
+  /** @internal Build configuration */
+  build?: BuildConfig;
+  /** @internal Runtime configuration */
+  runtime?: RuntimeConfig;
+  /** @internal Integration settings */
+  integration?: IntegrationConfig;
+  /** @internal Theme dependencies mapping */
+  dependencies?: Record<string, string[]>;
+}
+
+/**
+ * Helper function to define Atomix configuration with type safety
+ */
+export function defineConfig(config: AtomixConfig): AtomixConfig {
+  return config;
+}

package/src/lib/config/validator.ts

@@ -0,0 +1,305 @@
+/**
+ * Configuration Validator
+ * 
+ * Provides detailed validation and feedback for Atomix configurations,
+ * especially for advanced features (Phases 2, 3, and 4).
+ */
+
+import type { AtomixConfig } from './types';
+import { validateConfig } from './loader';
+
+/**
+ * Validation result with detailed information
+ */
+export interface ValidationResult {
+  /** Whether the configuration is valid */
+  isValid: boolean;
+  /** Warnings about potential issues */
+  warnings: string[];
+  /** Suggestions for improvement */
+  suggestions: string[];
+  /** Performance impact assessment */
+  performanceImpact: 'low' | 'medium' | 'high';
+  /** Compatibility report */
+  compatibility: {
+    /** Browser support status */
+    browsers: boolean;
+    /** SSR support status */
+    ssr: boolean;
+    /** Framework compatibility */
+    frameworks: ('react' | 'vue' | 'angular' | 'svelte' | 'vanillajs')[];
+  };
+}
+
+/**
+ * Validate an Atomix configuration with detailed feedback
+ * 
+ * @param config - The configuration to validate
+ * @param options - Validation options
+ * @returns Detailed validation result
+ * 
+ * @example
+ * ```typescript
+ * import { validateConfiguration } from '@shohojdhara/atomix/config';
+ * 
+ * const config = { /* your config *\/ };
+ * const result = validateConfiguration(config);
+ * 
+ * if (!result.isValid) {
+ *   console.warn('Warnings:', result.warnings);
+ *   console.info('Suggestions:', result.suggestions);
+ * }
+ * ```
+ */
+export function validateConfiguration(
+  config: AtomixConfig,
+  options?: {
+    /** Include performance impact analysis (default: true) */
+    performanceAnalysis?: boolean;
+    /** Include compatibility report (default: true) */
+    compatibilityReport?: boolean;
+  }
+): ValidationResult {
+  const { performanceAnalysis = true, compatibilityReport = true } = options || {};
+  
+  const warnings: string[] = [];
+  const suggestions: string[] = [];
+  let performanceImpact: 'low' | 'medium' | 'high' = 'low';
+  
+  // Use the existing validation
+  const baseWarnings = validateConfig(config);
+  warnings.push(...baseWarnings);
+  
+  // Analyze advanced features for performance impact
+  if (performanceAnalysis) {
+    performanceImpact = analyzePerformanceImpact(config);
+  }
+  
+  // Generate suggestions based on configuration
+  generateSuggestions(config, suggestions);
+  
+  // Determine overall validity
+  const isValid = warnings.length === 0;
+  
+  // Generate compatibility report
+  const compatibility = compatibilityReport 
+    ? generateCompatibilityReport(config) 
+    : {
+        browsers: true,
+        ssr: true,
+        frameworks: ['react', 'vue', 'angular', 'svelte', 'vanillajs'] as ('react' | 'vue' | 'angular' | 'svelte' | 'vanillajs')[]
+      };
+  
+  return {
+    isValid,
+    warnings,
+    suggestions,
+    performanceImpact,
+    compatibility
+  };
+}
+
+/**
+ * Analyze the performance impact of a configuration
+ */
+function analyzePerformanceImpact(config: AtomixConfig): 'low' | 'medium' | 'high' {
+  let impactScore = 0;
+  
+  // Analyze interactive effects
+  if (config.interactiveEffects) {
+    const ie = config.interactiveEffects;
+    
+    if (ie.vortex?.enabled) {
+      impactScore += 2;
+    }
+    if (ie.chromaticAberration?.enabled) {
+      impactScore += 1;
+    }
+    if (ie.mouseInteraction?.trailEffect) {
+      impactScore += 1;
+    }
+    if (ie.mouseInteraction?.pressureSensitivity) {
+      impactScore += 1;
+    }
+  }
+  
+  // Analyze visual polish effects
+  if (config.visualPolish) {
+    const vp = config.visualPolish;
+    
+    if (vp.borders?.iridescentGlow) {
+      impactScore += 1;
+    }
+    if (vp.borders?.shimmerEffect) {
+      impactScore += 1;
+    }
+    if (vp.contentAwareBlur?.enabled) {
+      impactScore += 2;
+    }
+    if (vp.holographicEffects?.enabled) {
+      impactScore += 2;
+    }
+    if (vp.holographicEffects?.scanlineAnimation) {
+      impactScore += 1;
+    }
+    if (vp.holographicEffects?.dataStream) {
+      impactScore += 1;
+    }
+    if (vp.holographicEffects?.pulseRings) {
+      impactScore += 1;
+    }
+  }
+  
+  // Analyze optimization settings
+  if (config.optimization?.autoScaling?.enabled) {
+    impactScore -= 1; // This improves performance
+  }
+  
+  if (impactScore >= 6) return 'high';
+  if (impactScore >= 3) return 'medium';
+  return 'low';
+}
+
+/**
+ * Generate suggestions based on the configuration
+ */
+function generateSuggestions(config: AtomixConfig, suggestions: string[]): void {
+  // Suggest enabling performance optimizations if heavy effects are used
+  if (config.interactiveEffects || config.visualPolish?.holographicEffects?.enabled) {
+    if (!config.optimization?.autoScaling?.enabled) {
+      suggestions.push(
+        'Consider enabling auto-scaling in optimization settings to adjust effects ' +
+        'based on device performance: optimization.autoScaling.enabled = true'
+      );
+    }
+    
+    if (!config.optimization?.performance?.fpsTarget) {
+      suggestions.push(
+        'Set a target FPS in optimization.performance.fpsTarget to ensure smooth performance ' +
+        'when using interactive effects'
+      );
+    }
+  }
+  
+  // Suggest responsive breakpoints if optimization is partially configured
+  if (config.optimization && !config.optimization.responsive) {
+    suggestions.push(
+      'Consider adding responsive breakpoints in optimization.responsive.breakpoints ' +
+      'to adapt advanced effects based on device type'
+    );
+  }
+  
+  // Suggest disabling heavy effects on lower-end devices
+  if (config.visualPolish?.holographicEffects?.enabled) {
+    suggestions.push(
+      'For better performance on lower-end devices, consider conditionally disabling ' +
+      'holographic effects based on device capabilities'
+    );
+  }
+  
+  // Suggest using content-aware blur with performance considerations
+  if (config.visualPolish?.contentAwareBlur?.enabled) {
+    suggestions.push(
+      'Content-aware blur can be expensive; consider setting a maximum blur radius ' +
+      'or using simpler blur techniques for mobile devices'
+    );
+  }
+  
+  // Suggest using chromatic aberration适度
+  if (config.interactiveEffects?.chromaticAberration?.enabled) {
+    if (config.interactiveEffects.chromaticAberration.redShift && 
+        Math.abs(config.interactiveEffects.chromaticAberration.redShift) > 0.05) {
+      suggestions.push(
+        'High chromatic aberration red shift values (>0.05) may cause discomfort for some users; ' +
+        'consider reducing to improve accessibility'
+      );
+    }
+    
+    if (config.interactiveEffects.chromaticAberration.blueShift && 
+        Math.abs(config.interactiveEffects.chromaticAberration.blueShift) > 0.05) {
+      suggestions.push(
+        'High chromatic aberration blue shift values (>0.05) may cause discomfort for some users; ' +
+        'consider reducing to improve accessibility'
+      );
+    }
+  }
+}
+
+/**
+ * Generate a compatibility report for the configuration
+ */
+function generateCompatibilityReport(config: AtomixConfig): ValidationResult['compatibility'] {
+  // Advanced effects may not work well on older browsers
+  const hasHeavyEffects = 
+    config.visualPolish?.holographicEffects?.enabled ||
+    config.visualPolish?.contentAwareBlur?.enabled ||
+    config.interactiveEffects?.vortex?.enabled ||
+    config.interactiveEffects?.chromaticAberration?.enabled;
+  
+  return {
+    browsers: !hasHeavyEffects, // May have issues on older browsers
+    ssr: true, // Works fine with SSR
+    frameworks: ['react', 'vue', 'angular', 'svelte', 'vanillajs'] as ('react' | 'vue' | 'angular' | 'svelte' | 'vanillajs')[] // Compatible with all
+  };
+}
+
+/**
+ * Print a detailed configuration report to the console
+ * 
+ * @param config - The configuration to analyze
+ * @param title - Optional title for the report
+ * 
+ * @example
+ * ```typescript
+ * import { printConfigReport } from '@shohojdhara/atomix/config';
+ * 
+ * const config = { /* your config *\/ };
+ * printConfigReport(config, 'My Application Config');
+ * ```
+ */
+export function printConfigReport(config: AtomixConfig, title?: string): void {
+  const result = validateConfiguration(config);
+  
+  const reportTitle = title ? `Atomix Configuration Report: ${title}` : 'Atomix Configuration Report';
+  console.log(`\n${reportTitle}`);
+  console.log('='.repeat(reportTitle.length));
+  
+  console.log(`\n✅ Valid: ${result.isValid ? 'Yes' : 'No'}`);
+  console.log(`⚡ Performance Impact: ${result.performanceImpact.toUpperCase()}`);
+  
+  if (result.warnings.length > 0) {
+    console.log('\n⚠️  WARNINGS:');
+    result.warnings.forEach(warning => {
+      console.log(`  • ${warning}`);
+    });
+  }
+  
+  if (result.suggestions.length > 0) {
+    console.log('\n💡 SUGGESTIONS:');
+    result.suggestions.forEach(suggestion => {
+      console.log(`  • ${suggestion}`);
+    });
+  }
+  
+  console.log('\n🌐 COMPATIBILITY:');
+  console.log(`  Browser Support: ${result.compatibility.browsers ? '✅ Good' : '⚠️  May have issues'}`);
+  console.log(`  SSR Support: ${result.compatibility.ssr ? '✅ Full' : '❌ Limited'}`);
+  
+  console.log('\n📋 FEATURES DETECTED:');
+  const featuresDetected = [];
+  
+  if (config.interactiveEffects) featuresDetected.push('Interactive Effects');
+  if (config.optimization) featuresDetected.push('Optimization');
+  if (config.visualPolish) featuresDetected.push('Visual Polish');
+  if (config.ai) featuresDetected.push('AI Integration');
+  if (config.tokenEngine) featuresDetected.push('Token Engine');
+  if (config.generator) featuresDetected.push('Component Generator');
+  
+  if (featuresDetected.length > 0) {
+    featuresDetected.forEach(feature => console.log(`  • ${feature}`));
+  } else {
+    console.log('  • None - Standard configuration');
+  }
+  
+  console.log('');
+}

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

@@ -4,7 +4,7 @@
  * Adapters for working with DesignTokens and CSS variables
  */
 
-export { designTokensToCSSVars } from './themeAdapter';
+export { designTokensToTheme, themeToDesignTokens, designTokensToCSSVars, configToTokens } from './themeAdapter';
 
 export {
   generateCSSVariableName,