@shohojdhara/atomix 0.3.1 → 0.3.3

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

@@ -0,0 +1,98 @@
+/**
+ * Theme Configuration Types
+ * 
+ * Type definitions for the theme configuration system
+ */
+
+import type {
+  ThemeConfig,
+  ThemeDefinition,
+  CSSThemeDefinition,
+  JSThemeDefinition,
+  BuildConfig,
+  RuntimeConfig,
+  IntegrationConfig,
+} from '../../../../theme.config';
+
+/**
+ * Configuration loader options
+ */
+export interface ConfigLoaderOptions {
+  /** Path to theme config file (default: 'theme.config.ts') */
+  configPath?: string;
+  /** Enable validation */
+  validate?: boolean;
+  /** Environment-specific overrides */
+  env?: 'development' | 'production' | 'test';
+}
+
+/**
+ * Loaded and validated theme configuration
+ */
+export interface LoadedThemeConfig extends ThemeConfig {
+  /** Whether config was validated */
+  validated: boolean;
+  /** Validation errors (if any) */
+  errors?: string[];
+  /** Validation warnings (if any) */
+  warnings?: string[];
+}
+
+/**
+ * Theme metadata extracted from config
+ */
+export interface ThemeMetadata {
+  /** Theme identifier */
+  id: string;
+  /** Display name */
+  name: string;
+  /** Theme type */
+  type: 'css' | 'js';
+  /** Class name for CSS themes */
+  class?: string;
+  /** Description */
+  description?: string;
+  /** Author */
+  author?: string;
+  /** Version */
+  version?: string;
+  /** Tags */
+  tags?: string[];
+  /** Supports dark mode */
+  supportsDarkMode?: boolean;
+  /** Status */
+  status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
+  /** Accessibility info */
+  a11y?: {
+    contrastTarget?: number;
+    modes?: string[];
+  };
+  /** Primary color */
+  color?: string;
+  /** Features */
+  features?: string[];
+  /** Dependencies */
+  dependencies?: string[];
+}
+
+/**
+ * Configuration validation result
+ */
+export interface ConfigValidationResult {
+  /** Whether config is valid */
+  valid: boolean;
+  /** Validation errors */
+  errors: string[];
+  /** Validation warnings */
+  warnings: string[];
+}
+
+export type {
+  ThemeConfig,
+  ThemeDefinition,
+  CSSThemeDefinition,
+  JSThemeDefinition,
+  BuildConfig,
+  RuntimeConfig,
+  IntegrationConfig,
+};

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

@@ -0,0 +1,326 @@
+/**
+ * Theme Configuration Validator
+ * 
+ * Validates theme configuration structure and values
+ */
+
+import type {
+  ThemeConfig,
+  ThemeDefinition,
+  CSSThemeDefinition,
+  JSThemeDefinition,
+  ConfigValidationResult,
+} from './types';
+
+/**
+ * Validate theme configuration
+ * 
+ * @param config - Configuration to validate
+ * @returns Validation result with errors and warnings
+ */
+export function validateConfig(config: any): ConfigValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Validate top-level structure
+  if (!config || typeof config !== 'object') {
+    errors.push('Configuration must be an object');
+    return { valid: false, errors, warnings };
+  }
+
+  // Validate themes
+  if (!config.themes || typeof config.themes !== 'object') {
+    errors.push('Configuration must have a "themes" object');
+  } else {
+    const themeErrors = validateThemes(config.themes);
+    errors.push(...themeErrors.errors);
+    warnings.push(...themeErrors.warnings);
+  }
+
+  // Validate build config
+  if (config.build) {
+    const buildErrors = validateBuildConfig(config.build);
+    errors.push(...buildErrors.errors);
+    warnings.push(...buildErrors.warnings);
+  } else {
+    warnings.push('No build configuration provided, using defaults');
+  }
+
+  // Validate runtime config
+  if (config.runtime) {
+    const runtimeErrors = validateRuntimeConfig(config.runtime);
+    errors.push(...runtimeErrors.errors);
+    warnings.push(...runtimeErrors.warnings);
+  } else {
+    warnings.push('No runtime configuration provided, using defaults');
+  }
+
+  // Validate integration config
+  if (config.integration) {
+    const integrationErrors = validateIntegrationConfig(config.integration);
+    errors.push(...integrationErrors.errors);
+    warnings.push(...integrationErrors.warnings);
+  } else {
+    warnings.push('No integration configuration provided, using defaults');
+  }
+
+  // Validate dependencies
+  if (config.dependencies) {
+    const depErrors = validateDependencies(config.dependencies, config.themes || {});
+    errors.push(...depErrors.errors);
+    warnings.push(...depErrors.warnings);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Validate themes object
+ */
+function validateThemes(themes: Record<string, any>): ConfigValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (Object.keys(themes).length === 0) {
+    warnings.push('No themes defined in configuration');
+  }
+
+  for (const [themeId, theme] of Object.entries(themes)) {
+    // Validate theme ID
+    if (!themeId || typeof themeId !== 'string') {
+      errors.push(`Invalid theme ID: ${themeId}`);
+      continue;
+    }
+
+    // Validate theme object
+    if (!theme || typeof theme !== 'object') {
+      errors.push(`Theme "${themeId}" must be an object`);
+      continue;
+    }
+
+    // Validate theme type
+    if (!theme.type || (theme.type !== 'css' && theme.type !== 'js')) {
+      errors.push(`Theme "${themeId}" must have type "css" or "js"`);
+      continue;
+    }
+
+    // Validate required fields
+    if (!theme.name || typeof theme.name !== 'string') {
+      errors.push(`Theme "${themeId}" must have a "name" string`);
+    }
+
+    // Validate CSS theme
+    if (theme.type === 'css') {
+      const cssErrors = validateCSSTheme(themeId, theme);
+      errors.push(...cssErrors.errors);
+      warnings.push(...cssErrors.warnings);
+    }
+
+    // Validate JS theme
+    if (theme.type === 'js') {
+      const jsErrors = validateJSTheme(themeId, theme);
+      errors.push(...jsErrors.errors);
+      warnings.push(...jsErrors.warnings);
+    }
+
+    // Validate metadata
+    if (theme.version && !isValidSemver(theme.version)) {
+      warnings.push(`Theme "${themeId}" has invalid version format: ${theme.version}`);
+    }
+
+    if (theme.status && !['stable', 'beta', 'experimental', 'deprecated'].includes(theme.status)) {
+      warnings.push(`Theme "${themeId}" has invalid status: ${theme.status}`);
+    }
+
+    // Validate color format
+    if (theme.color && !isValidColor(theme.color)) {
+      warnings.push(`Theme "${themeId}" has invalid color format: ${theme.color}`);
+    }
+
+    // Validate accessibility
+    if (theme.a11y) {
+      if (theme.a11y.contrastTarget && (theme.a11y.contrastTarget < 1 || theme.a11y.contrastTarget > 21)) {
+        warnings.push(`Theme "${themeId}" has invalid contrast target: ${theme.a11y.contrastTarget}`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Validate CSS theme
+ */
+function validateCSSTheme(themeId: string, theme: any): ConfigValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // CSS themes don't require createTheme function
+  // But can have optional cssPath
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Validate JS theme
+ */
+function validateJSTheme(themeId: string, theme: any): ConfigValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // JS themes must have createTheme function
+  if (!theme.createTheme || typeof theme.createTheme !== 'function') {
+    errors.push(`JS theme "${themeId}" must have a "createTheme" function`);
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Validate build configuration
+ */
+function validateBuildConfig(build: any): ConfigValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!build.output || typeof build.output !== 'object') {
+    errors.push('Build config must have an "output" object');
+  } else {
+    if (!build.output.directory || typeof build.output.directory !== 'string') {
+      errors.push('Build output must have a "directory" string');
+    }
+    if (!build.output.formats || typeof build.output.formats !== 'object') {
+      errors.push('Build output must have a "formats" object');
+    }
+  }
+
+  if (!build.sass || typeof build.sass !== 'object') {
+    errors.push('Build config must have a "sass" object');
+  } else {
+    if (build.sass.style && !['expanded', 'compressed', 'compact', 'nested'].includes(build.sass.style)) {
+      warnings.push(`Invalid Sass style: ${build.sass.style}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Validate runtime configuration
+ */
+function validateRuntimeConfig(runtime: any): ConfigValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (runtime.basePath && typeof runtime.basePath !== 'string') {
+    errors.push('Runtime basePath must be a string');
+  }
+
+  if (runtime.defaultTheme && typeof runtime.defaultTheme !== 'string') {
+    errors.push('Runtime defaultTheme must be a string');
+  }
+
+  if (runtime.preload && !Array.isArray(runtime.preload)) {
+    errors.push('Runtime preload must be an array');
+  }
+
+  if (runtime.storageKey && typeof runtime.storageKey !== 'string') {
+    errors.push('Runtime storageKey must be a string');
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Validate integration configuration
+ */
+function validateIntegrationConfig(integration: any): ConfigValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!integration.classNames || typeof integration.classNames !== 'object') {
+    errors.push('Integration config must have a "classNames" object');
+  } else {
+    if (!integration.classNames.theme || typeof integration.classNames.theme !== 'string') {
+      errors.push('Integration classNames must have a "theme" string');
+    }
+    if (!integration.classNames.colorMode || typeof integration.classNames.colorMode !== 'string') {
+      errors.push('Integration classNames must have a "colorMode" string');
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Validate dependencies
+ */
+function validateDependencies(
+  dependencies: Record<string, string[]>,
+  themes: Record<string, any>
+): ConfigValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  for (const [themeId, deps] of Object.entries(dependencies)) {
+    // Check if theme exists
+    if (!themes[themeId]) {
+      warnings.push(`Dependencies defined for non-existent theme: ${themeId}`);
+      continue;
+    }
+
+    // Validate dependencies array
+    if (!Array.isArray(deps)) {
+      errors.push(`Dependencies for "${themeId}" must be an array`);
+      continue;
+    }
+
+    // Check if all dependencies exist
+    for (const dep of deps) {
+      if (!themes[dep]) {
+        errors.push(`Theme "${themeId}" depends on non-existent theme: ${dep}`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Check if string is valid semver
+ */
+function isValidSemver(version: string): boolean {
+  const semverRegex = /^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/;
+  return semverRegex.test(version);
+}
+
+/**
+ * Check if string is valid color
+ */
+function isValidColor(color: string): boolean {
+  // Hex color
+  if (/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/.test(color)) {
+    return true;
+  }
+  // RGB/RGBA
+  if (/^rgba?\(/.test(color)) {
+    return true;
+  }
+  // HSL/HSLA
+  if (/^hsla?\(/.test(color)) {
+    return true;
+  }
+  // Named colors (basic check)
+  const namedColors = [
+    'black', 'white', 'red', 'green', 'blue', 'yellow', 'cyan', 'magenta',
+    'transparent', 'currentColor',
+  ];
+  if (namedColors.includes(color.toLowerCase())) {
+    return true;
+  }
+  return false;
+}

package/src/lib/theme/constants.ts

@@ -0,0 +1,183 @@
+/**
+ * Theme System Constants
+ * 
+ * Centralized constants for the theme system to avoid magic numbers and strings.
+ */
+
+/**
+ * Default storage key for theme persistence
+ */
+export const DEFAULT_STORAGE_KEY = 'atomix-theme';
+
+/**
+ * Default data attribute name for theme
+ */
+export const DEFAULT_DATA_ATTRIBUTE = 'data-theme';
+
+/**
+ * Default base path for theme CSS files
+ */
+export const DEFAULT_BASE_PATH = '/themes';
+
+/**
+ * Default style ID for injected JS theme CSS
+ */
+export const DEFAULT_STYLE_ID = 'atomix-js-theme-styles';
+
+/**
+ * Default cache configuration
+ */
+export const DEFAULT_CACHE_CONFIG = {
+  maxSize: 50,
+  ttl: 0, // No expiration by default
+} as const;
+
+/**
+ * Default engine cache configuration
+ */
+export const DEFAULT_ENGINE_CACHE_CONFIG = {
+  maxSize: 10,
+  ttl: 0, // No expiration by default
+} as const;
+
+/**
+ * Theme link ID prefix
+ */
+export const THEME_LINK_ID_PREFIX = 'atomix-theme-';
+
+/**
+ * CSS file extensions
+ */
+export const CSS_EXTENSIONS = {
+  expanded: '.css',
+  compressed: '.min.css',
+} as const;
+
+/**
+ * Default config file path
+ */
+export const DEFAULT_CONFIG_PATH = 'theme.config.ts';
+
+/**
+ * Default config file path (relative)
+ */
+export const DEFAULT_CONFIG_RELATIVE_PATH = '../../../../theme.config';
+
+/**
+ * Validation thresholds
+ */
+export const VALIDATION_THRESHOLDS = {
+  /** Minimum contrast ratio for accessibility (WCAG AA) */
+  MIN_CONTRAST_RATIO: 4.5,
+  /** Critical contrast ratio threshold (below this is error) */
+  CRITICAL_CONTRAST_RATIO: 3.0,
+  /** Minimum font size for accessibility (px) */
+  MIN_FONT_SIZE: 12,
+  /** Maximum transition duration (ms) */
+  MAX_TRANSITION_DURATION: 10000,
+  /** Maximum z-index value */
+  MAX_Z_INDEX: 10000,
+  /** Maximum border radius (px) */
+  MAX_BORDER_RADIUS: 1000,
+  /** Maximum custom property depth */
+  MAX_CUSTOM_PROPERTY_DEPTH: 10,
+} as const;
+
+/**
+ * Default theme metadata
+ */
+export const DEFAULT_THEME_METADATA = {
+  status: 'stable' as const,
+  supportsDarkMode: false,
+} as const;
+
+/**
+ * RTL locales (right-to-left languages)
+ */
+export const RTL_LOCALES = [
+  'ar', // Arabic
+  'he', // Hebrew
+  'fa', // Persian/Farsi
+  'ur', // Urdu
+  'yi', // Yiddish
+  'ku', // Kurdish
+  'sd', // Sindhi
+] as const;
+
+/**
+ * Default RTL configuration
+ */
+export const DEFAULT_RTL_CONFIG = {
+  enabled: false,
+  direction: 'ltr' as const,
+  dataAttribute: 'data-direction',
+  autoDetect: false,
+} as const;
+
+/**
+ * Analytics default configuration
+ */
+export const DEFAULT_ANALYTICS_CONFIG = {
+  enabled: true,
+  trackPerformance: true,
+  trackErrors: true,
+  bufferSize: 100,
+  flushInterval: 5000, // 5 seconds
+} as const;
+
+/**
+ * Logger default configuration
+ */
+export const DEFAULT_LOGGER_CONFIG = {
+  level: process.env.NODE_ENV === 'production' ? 1 : 2, // WARN in prod, INFO in dev
+  enableConsole: true,
+} as const;
+
+/**
+ * Environment-specific defaults
+ */
+export const ENV_DEFAULTS = {
+  development: {
+    useMinified: false,
+    lazy: false,
+    enableSourceMaps: true,
+  },
+  production: {
+    useMinified: true,
+    lazy: true,
+    enableSourceMaps: false,
+  },
+  test: {
+    enablePersistence: false,
+    preload: [],
+  },
+} as const;
+
+/**
+ * Integration default class names
+ */
+export const DEFAULT_INTEGRATION_CLASS_NAMES = {
+  theme: 'data-theme',
+  colorMode: 'data-atomix-color-mode',
+} as const;
+
+/**
+ * Integration default CSS variables
+ */
+export const DEFAULT_INTEGRATION_CSS_VARIABLES = {
+  colorMode: '--storybook-color-mode',
+} as const;
+
+/**
+ * Build default output directory
+ */
+export const DEFAULT_BUILD_OUTPUT_DIR = 'themes';
+
+/**
+ * Build default SASS configuration
+ */
+export const DEFAULT_SASS_CONFIG = {
+  style: 'expanded' as const,
+  sourceMap: true,
+  loadPaths: ['src'] as string[],
+};