@fabio.caffarello/react-design-system 1.7.0 → 1.9.0

package/src/ui/providers/ConfigProvider.tsx

@@ -0,0 +1,256 @@
+'use client';
+
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+import { SPACING_TOKENS } from '../tokens/spacing';
+import { TYPOGRAPHY_TOKENS } from '../tokens/typography';
+import { BREAKPOINT_TOKENS } from '../tokens/breakpoints';
+import { ANIMATION_TOKENS } from '../tokens/animations';
+import type { BreakpointName, BreakpointToken } from '../tokens/breakpoints';
+import type { SpacingToken } from '../tokens/spacing';
+import type { TypographyToken } from '../tokens/typography';
+import type { AnimationToken } from '../tokens/animations';
+
+/**
+ * Design System Configuration
+ * 
+ * Centralizes all design system configuration including:
+ * - Breakpoints for responsive design
+ * - Design tokens (spacing, typography, colors)
+ * - Behavior configurations (animations, transitions)
+ * - Feature flags
+ */
+export interface DesignSystemConfig {
+  /**
+   * Responsive breakpoints
+   */
+  breakpoints: Record<BreakpointName, { name: BreakpointName; minWidth: number; px: string; rem: string; tailwind: string }>;
+  
+  /**
+   * Spacing tokens
+   */
+  spacing: typeof SPACING_TOKENS;
+  
+  /**
+   * Typography tokens
+   */
+  typography: typeof TYPOGRAPHY_TOKENS;
+  
+  /**
+   * Animation tokens
+   */
+  animations: typeof ANIMATION_TOKENS;
+  
+  /**
+   * Feature flags
+   */
+  features: {
+    /**
+     * Enable reduced motion for accessibility
+     */
+    reducedMotion?: boolean;
+    
+    /**
+     * Enable high contrast mode
+     */
+    highContrast?: boolean;
+    
+    /**
+     * Enable debug mode
+     */
+    debug?: boolean;
+  };
+  
+  /**
+   * Behavior configurations
+   */
+  behavior: {
+    /**
+     * Default animation duration in ms
+     */
+    defaultAnimationDuration?: number;
+    
+    /**
+     * Default transition duration in ms
+     */
+    defaultTransitionDuration?: number;
+    
+    /**
+     * Enable focus visible outline
+     */
+    focusVisible?: boolean;
+  };
+}
+
+/**
+ * Default design system configuration
+ */
+const defaultConfig: DesignSystemConfig = {
+  breakpoints: BREAKPOINT_TOKENS,
+  spacing: SPACING_TOKENS,
+  typography: TYPOGRAPHY_TOKENS,
+  animations: ANIMATION_TOKENS,
+  features: {
+    reducedMotion: false,
+    highContrast: false,
+    debug: false,
+  },
+  behavior: {
+    defaultAnimationDuration: 200,
+    defaultTransitionDuration: 150,
+    focusVisible: true,
+  },
+};
+
+export interface ConfigContextValue {
+  config: DesignSystemConfig;
+  /**
+   * Get spacing token by scale
+   */
+  getSpacing: (scale: keyof typeof SPACING_TOKENS) => SpacingToken;
+  /**
+   * Get breakpoint value
+   */
+  getBreakpoint: (name: BreakpointName) => BreakpointToken;
+  /**
+   * Check if feature is enabled
+   */
+  isFeatureEnabled: (feature: keyof DesignSystemConfig['features']) => boolean;
+  /**
+   * Update configuration (for runtime updates)
+   */
+  updateConfig: (updates: Partial<DesignSystemConfig>) => void;
+}
+
+const ConfigContext = createContext<ConfigContextValue | undefined>(undefined);
+
+export interface ConfigProviderProps {
+  children: ReactNode;
+  /**
+   * Custom configuration to override defaults
+   */
+  config?: Partial<DesignSystemConfig>;
+  /**
+   * Strategy for configuration (default, custom, theme-based)
+   */
+  strategy?: 'default' | 'custom' | 'theme-based';
+}
+
+/**
+ * ConfigProvider Component
+ * 
+ * Provides design system configuration context to the application.
+ * Uses Strategy Pattern for different configuration strategies.
+ * 
+ * @example
+ * ```tsx
+ * <ConfigProvider config={{ features: { debug: true } }}>
+ *   <App />
+ * </ConfigProvider>
+ * ```
+ */
+export function ConfigProvider({
+  children,
+  config: customConfig,
+  strategy = 'default',
+}: ConfigProviderProps) {
+  // Merge custom config with defaults
+  const config = useMemo<DesignSystemConfig>(() => {
+    const baseConfig = { ...defaultConfig };
+    
+    if (customConfig) {
+      return {
+        ...baseConfig,
+        ...customConfig,
+        breakpoints: customConfig.breakpoints || baseConfig.breakpoints,
+        spacing: customConfig.spacing || baseConfig.spacing,
+        typography: customConfig.typography || baseConfig.typography,
+        animations: customConfig.animations || baseConfig.animations,
+        features: {
+          ...baseConfig.features,
+          ...customConfig.features,
+        },
+        behavior: {
+          ...baseConfig.behavior,
+          ...customConfig.behavior,
+        },
+      };
+    }
+    
+    return baseConfig;
+  }, [customConfig]);
+
+  // Apply reduced motion if enabled
+  useMemo(() => {
+    if (config.features.reducedMotion && typeof document !== 'undefined') {
+      document.documentElement.style.setProperty('--motion-reduce', '1');
+    } else if (typeof document !== 'undefined') {
+      document.documentElement.style.removeProperty('--motion-reduce');
+    }
+  }, [config.features.reducedMotion]);
+
+  // Apply high contrast if enabled
+  useMemo(() => {
+    if (config.features.highContrast && typeof document !== 'undefined') {
+      document.documentElement.classList.add('high-contrast');
+    } else if (typeof document !== 'undefined') {
+      document.documentElement.classList.remove('high-contrast');
+    }
+  }, [config.features.highContrast]);
+
+  const getSpacing = useMemo(
+    () => (scale: keyof typeof SPACING_TOKENS) => {
+      return config.spacing[scale];
+    },
+    [config.spacing]
+  );
+
+  const getBreakpoint = useMemo(
+    () => (name: BreakpointName) => {
+      return config.breakpoints[name];
+    },
+    [config.breakpoints]
+  );
+
+  const isFeatureEnabled = useMemo(
+    () => (feature: keyof DesignSystemConfig['features']) => {
+      return config.features[feature] ?? false;
+    },
+    [config.features]
+  );
+
+  const updateConfig = useMemo(
+    () => (updates: Partial<DesignSystemConfig>) => {
+      // This is a placeholder - in a real implementation, you'd use state
+      // For now, config is immutable. Future enhancement could add state management.
+      console.warn('ConfigProvider: updateConfig called but config is immutable. Consider using state management for dynamic updates.');
+    },
+    []
+  );
+
+  const value: ConfigContextValue = {
+    config,
+    getSpacing,
+    getBreakpoint,
+    isFeatureEnabled,
+    updateConfig,
+  };
+
+  return (
+    <ConfigContext.Provider value={value}>
+      {children}
+    </ConfigContext.Provider>
+  );
+}
+
+/**
+ * Hook to use config context
+ * 
+ * @throws Error if used outside ConfigProvider
+ */
+export function useConfig(): ConfigContextValue {
+  const context = useContext(ConfigContext);
+  if (context === undefined) {
+    throw new Error('useConfig must be used within a ConfigProvider');
+  }
+  return context;
+}

package/src/ui/providers/ThemeProvider.tsx

@@ -2,7 +2,7 @@
 
 import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
 import { COLOR_TOKENS_LIGHT, COLOR_TOKENS_DARK, type ColorRole, type SemanticColor } from '../tokens/colors';
-import type { ThemeMode } from '../tokens/tokens.factory';
+import type { ThemeMode } from '../tokens';
 
 export interface ThemeContextValue {
   theme: ThemeMode;

package/src/ui/providers/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Providers Export
+ * 
+ * Centralized export for all design system providers
+ */
+
+export { AppProvider, useApp, type AppProviderProps, type AppProviderConfig } from './AppProvider';
+export { ConfigProvider, useConfig, type ConfigProviderProps, type DesignSystemConfig, type ConfigContextValue } from './ConfigProvider';
+export { ThemeProvider, useTheme, type ThemeProviderProps, type ThemeContextValue } from './ThemeProvider';

package/src/ui/shared/errors/RegistryErrors.ts

@@ -0,0 +1,31 @@
+/**
+ * Custom error classes for Registry operations
+ */
+
+export class RegistryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RegistryError';
+  }
+}
+
+export class EntryNotFoundError extends RegistryError {
+  constructor(id: string, registryName: string) {
+    super(`Entry "${id}" not found in ${registryName}`);
+    this.name = 'EntryNotFoundError';
+  }
+}
+
+export class DuplicateEntryError extends RegistryError {
+  constructor(id: string, registryName: string) {
+    super(`Duplicate entry "${id}" in ${registryName}`);
+    this.name = 'DuplicateEntryError';
+  }
+}
+
+export class InvalidEntryError extends RegistryError {
+  constructor(reason: string) {
+    super(`Invalid entry: ${reason}`);
+    this.name = 'InvalidEntryError';
+  }
+}

package/src/ui/shared/errors/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared error classes
+ */
+
+export {
+  RegistryError,
+  EntryNotFoundError,
+  DuplicateEntryError,
+  InvalidEntryError,
+} from './RegistryErrors';

package/src/ui/shared/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared utilities and patterns
+ */
+
+export * from './utils';
+export * from './errors';
+export * from './patterns';
+export * from './validation';

package/src/ui/shared/patterns/BaseRegistry.ts

@@ -0,0 +1,290 @@
+import { z } from 'zod';
+import { compareByOrder } from '../utils/comparators';
+import {
+  EntryNotFoundError,
+  DuplicateEntryError,
+  InvalidEntryError
+} from '../errors/RegistryErrors';
+
+/**
+ * Registry Entry Base Interface
+ */
+export interface RegistryEntry {
+  id: string;
+  metadata?: {
+    order?: number;
+    label?: string;
+    description?: string;
+    tags?: string[];
+  };
+}
+
+/**
+ * Registry Configuration Options
+ */
+export interface RegistryOptions {
+  /**
+   * Registry name (for error messages and logging)
+   */
+  name: string;
+
+  /**
+   * Whether to allow duplicate registrations (overwrite existing)
+   * Default: true (with warning)
+   */
+  allowDuplicates?: boolean;
+
+  /**
+   * Whether to throw errors or log warnings
+   * Default: 'warn'
+   */
+  errorMode?: 'throw' | 'warn' | 'silent';
+
+  /**
+   * Whether to validate entries on registration
+   * Default: true
+   */
+  validateOnRegister?: boolean;
+}
+
+/**
+ * Base Registry Abstract Class
+ *
+ * Provides common registry functionality with consistent behavior.
+ * Subclasses must implement ID generation strategy.
+ *
+ * @example
+ * class ComponentRegistry extends BaseRegistry<ComponentEntry> {
+ *   protected generateEntryId(entry: ComponentEntry): string {
+ *     return entry.id;
+ *   }
+ *
+ *   protected validateEntry(entry: ComponentEntry): void {
+ *     if (!entry.component) {
+ *       throw new InvalidEntryError('Missing component');
+ *     }
+ *   }
+ * }
+ */
+export abstract class BaseRegistry<T extends RegistryEntry> {
+  protected entries: Map<string, T> = new Map();
+  protected options: Required<RegistryOptions>;
+  protected schema?: z.ZodSchema<T>;
+
+  constructor(options: RegistryOptions, schema?: z.ZodSchema<T>) {
+    this.options = {
+      allowDuplicates: true,
+      errorMode: 'warn',
+      validateOnRegister: true,
+      ...options,
+    };
+    this.schema = schema;
+  }
+
+  /**
+   * Generate unique ID for an entry
+   * Must be implemented by subclasses
+   */
+  protected abstract generateEntryId(entry: T): string;
+
+  /**
+   * Validate an entry before registration
+   * Can be overridden by subclasses for custom validation
+   *
+   * If a Zod schema is provided, it will be validated first.
+   * Then custom validation logic can be added by overriding this method.
+   */
+  protected validateEntry(entry: T): void {
+    // Zod schema validation if provided
+    if (this.schema) {
+      const result = this.schema.safeParse(entry);
+      if (!result.success) {
+        const errors = result.error.issues
+          .map(issue => `${issue.path.join('.')}: ${issue.message}`)
+          .join(', ');
+        throw new InvalidEntryError(`Schema validation failed: ${errors}`);
+      }
+    }
+
+    // Basic ID validation
+    if (!entry.id && !this.generateEntryId(entry)) {
+      throw new InvalidEntryError('Entry must have an ID');
+    }
+  }
+
+  /**
+   * Register an entry
+   */
+  register(entry: T): void {
+    if (this.options.validateOnRegister) {
+      this.validateEntry(entry);
+    }
+
+    const id = this.generateEntryId(entry);
+    const entryWithId = { ...entry, id };
+
+    if (this.entries.has(id)) {
+      this.handleDuplicate(id);
+    }
+
+    this.entries.set(id, entryWithId);
+    this.onRegister(entryWithId);
+  }
+
+  /**
+   * Register multiple entries at once
+   */
+  registerMany(entries: T[]): void {
+    entries.forEach(entry => this.register(entry));
+  }
+
+  /**
+   * Unregister an entry by ID
+   */
+  unregister(id: string): boolean {
+    const entry = this.entries.get(id);
+    if (!entry) return false;
+
+    this.entries.delete(id);
+    this.onUnregister(entry);
+    return true;
+  }
+
+  /**
+   * Unregister multiple entries
+   */
+  unregisterMany(ids: string[]): number {
+    let count = 0;
+    ids.forEach(id => {
+      if (this.unregister(id)) count++;
+    });
+    return count;
+  }
+
+  /**
+   * Get entry by ID
+   */
+  get(id: string): T | undefined {
+    return this.entries.get(id);
+  }
+
+  /**
+   * Get entry by ID or throw error
+   */
+  getOrThrow(id: string): T {
+    const entry = this.get(id);
+    if (!entry) {
+      throw new EntryNotFoundError(id, this.options.name);
+    }
+    return entry;
+  }
+
+  /**
+   * Check if entry exists
+   */
+  has(id: string): boolean {
+    return this.entries.has(id);
+  }
+
+  /**
+   * Get all entries
+   */
+  getAll(): T[] {
+    return Array.from(this.entries.values()).sort(compareByOrder);
+  }
+
+  /**
+   * Get all IDs
+   */
+  getAllIds(): string[] {
+    return Array.from(this.entries.keys());
+  }
+
+  /**
+   * Get count of entries
+   */
+  count(): number {
+    return this.entries.size;
+  }
+
+  /**
+   * Check if registry is empty
+   */
+  isEmpty(): boolean {
+    return this.entries.size === 0;
+  }
+
+  /**
+   * Clear all entries
+   */
+  clear(): void {
+    const entries = Array.from(this.entries.values());
+    this.entries.clear();
+    entries.forEach(entry => this.onUnregister(entry));
+  }
+
+  /**
+   * Find entries matching predicate
+   */
+  find(predicate: (entry: T) => boolean): T[] {
+    return this.getAll().filter(predicate);
+  }
+
+  /**
+   * Find first entry matching predicate
+   */
+  findOne(predicate: (entry: T) => boolean): T | undefined {
+    return this.getAll().find(predicate);
+  }
+
+  /**
+   * Handle duplicate registration
+   */
+  protected handleDuplicate(id: string): void {
+    const message = `Entry "${id}" already exists in ${this.options.name}`;
+
+    switch (this.options.errorMode) {
+      case 'throw':
+        if (!this.options.allowDuplicates) {
+          throw new DuplicateEntryError(id, this.options.name);
+        }
+        break;
+      case 'warn':
+        console.warn(message + '. Overwriting.');
+        break;
+      case 'silent':
+        break;
+    }
+  }
+
+  /**
+   * Hook called after successful registration
+   * Can be overridden by subclasses
+   */
+  protected onRegister(entry: T): void {
+    // Override in subclasses if needed
+  }
+
+  /**
+   * Hook called after unregistration
+   * Can be overridden by subclasses
+   */
+  protected onUnregister(entry: T): void {
+    // Override in subclasses if needed
+  }
+
+  /**
+   * Export entries as JSON
+   */
+  toJSON(): T[] {
+    return this.getAll();
+  }
+
+  /**
+   * Load entries from JSON
+   */
+  fromJSON(entries: T[]): void {
+    this.clear();
+    this.registerMany(entries);
+  }
+}

package/src/ui/shared/patterns/CategorizedRegistry.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { BaseRegistry, type RegistryEntry, type RegistryOptions } from './BaseRegistry';
+
+/**
+ * Entry with category
+ */
+export interface CategorizedEntry extends RegistryEntry {
+  category: string;
+}
+
+/**
+ * Registry for entries with categories
+ * Adds category-based filtering
+ */
+export abstract class CategorizedRegistry<T extends CategorizedEntry> extends BaseRegistry<T> {
+  constructor(options: RegistryOptions, schema?: z.ZodSchema<T>) {
+    super(options, schema);
+  }
+  /**
+   * Get all entries in a category
+   */
+  getByCategory(category: string): T[] {
+    return this.find(entry => entry.category === category);
+  }
+
+  /**
+   * Get all categories
+   */
+  getCategories(): string[] {
+    const categories = new Set<string>();
+    this.entries.forEach(entry => categories.add(entry.category));
+    return Array.from(categories).sort();
+  }
+
+  /**
+   * Check if category exists
+   */
+  hasCategory(category: string): boolean {
+    return Array.from(this.entries.values()).some(entry => entry.category === category);
+  }
+
+  /**
+   * Count entries in category
+   */
+  countByCategory(category: string): number {
+    return this.getByCategory(category).length;
+  }
+}

package/src/ui/shared/patterns/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared design patterns
+ */
+
+export { BaseRegistry, type RegistryEntry, type RegistryOptions } from './BaseRegistry';
+export { CategorizedRegistry, type CategorizedEntry } from './CategorizedRegistry';