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

package/src/ui/themes/README.md

@@ -0,0 +1,281 @@
+# Advanced Theme System
+
+Sistema avançado de temas para o React Design System, com suporte a múltiplos temas, CSS variables, herança de temas e transições suaves.
+
+## Características
+
+- ✅ **Múltiplos Temas Simultâneos**: Registre e use vários temas na mesma aplicação
+- ✅ **CSS Variables**: Geração automática de variáveis CSS a partir de tokens
+- ✅ **Theme Inheritance**: Herde de temas base (light/dark) e customize apenas o necessário
+- ✅ **Transições Suaves**: Transições animadas entre temas
+- ✅ **Persistência**: Salva preferências de tema no localStorage
+- ✅ **Type-Safe**: Totalmente tipado com TypeScript
+
+## Uso Básico
+
+### Usando o AdvancedThemeProvider
+
+```tsx
+import { AdvancedThemeProvider, useAdvancedTheme } from '@fabio.caffarello/react-design-system';
+
+function App() {
+  return (
+    <AdvancedThemeProvider
+      defaultTheme="light"
+      options={{
+        enableCSSVariables: true,
+        enableTransitions: true,
+        transitionDuration: '200ms',
+      }}
+    >
+      <MyComponent />
+    </AdvancedThemeProvider>
+  );
+}
+
+function MyComponent() {
+  const { currentTheme, setTheme, tokens } = useAdvancedTheme();
+  
+  return (
+    <div>
+      <p>Current theme: {currentTheme}</p>
+      <button onClick={() => setTheme('dark')}>Switch to Dark</button>
+    </div>
+  );
+}
+```
+
+## Criando Temas Customizados
+
+### Usando ThemeBuilder
+
+```tsx
+import { ThemeBuilder } from '@fabio.caffarello/react-design-system';
+
+const customTheme = ThemeBuilder.create({
+  name: 'my-custom-theme',
+  base: 'light', // Herda de 'light'
+  colors: {
+    primary: {
+      DEFAULT: {
+        hex: '#8b5cf6', // Roxo customizado
+        rgb: { r: 139, g: 92, b: 246 },
+      },
+    },
+  },
+  spacing: {
+    // Override spacing tokens se necessário
+  },
+}).build();
+```
+
+### Registrando Temas no Provider
+
+```tsx
+<AdvancedThemeProvider
+  defaultTheme="light"
+  initialThemes={[
+    {
+      name: 'brand-theme',
+      base: 'light',
+      colors: {
+        primary: {
+          DEFAULT: { hex: '#your-brand-color' },
+        },
+      },
+    },
+  ]}
+>
+  <App />
+</AdvancedThemeProvider>
+```
+
+### Registrando Temas Dinamicamente
+
+```tsx
+function ThemeManager() {
+  const { registerTheme, setTheme } = useAdvancedTheme();
+  
+  const handleCreateTheme = () => {
+    const newTheme = registerTheme({
+      name: 'dynamic-theme',
+      base: 'dark',
+      colors: {
+        primary: {
+          DEFAULT: { hex: '#ff6b6b' },
+        },
+      },
+    });
+    
+    setTheme(newTheme.name);
+  };
+  
+  return <button onClick={handleCreateTheme}>Create Theme</button>;
+}
+```
+
+## CSS Variables
+
+Quando `enableCSSVariables` está ativado, o sistema gera automaticamente variáveis CSS:
+
+```css
+:root {
+  --color-primary-default: #6366f1;
+  --color-primary-light: #818cf8;
+  --color-primary-dark: #4f46e5;
+  --spacing-xs: 4px;
+  --spacing-sm: 8px;
+  --font-size-h1: 2.25rem;
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+  /* ... */
+}
+```
+
+Você pode usar essas variáveis em seu CSS:
+
+```css
+.my-component {
+  background-color: var(--color-primary-default);
+  padding: var(--spacing-md);
+  box-shadow: var(--shadow-md);
+}
+```
+
+## API
+
+### AdvancedThemeProvider Props
+
+```typescript
+interface AdvancedThemeProviderProps {
+  children: ReactNode;
+  defaultTheme?: string; // Nome do tema padrão (default: 'light')
+  options?: ThemeBuilderOptions;
+  initialThemes?: CustomThemeConfig[]; // Temas para registrar na inicialização
+}
+```
+
+### ThemeBuilderOptions
+
+```typescript
+interface ThemeBuilderOptions {
+  enableCSSVariables?: boolean; // Gerar CSS variables (default: true)
+  enableTransitions?: boolean; // Habilitar transições (default: true)
+  transitionDuration?: string; // Duração da transição (default: '200ms')
+  storageKey?: string; // Chave do localStorage (default: 'theme')
+}
+```
+
+### useAdvancedTheme Hook
+
+```typescript
+interface AdvancedThemeContextValue {
+  currentTheme: string; // Nome do tema atual
+  themes: Record<string, Theme>; // Todos os temas registrados
+  setTheme: (themeName: string) => void; // Mudar tema
+  registerTheme: (config: CustomThemeConfig) => Theme; // Registrar novo tema
+  removeTheme: (themeName: string) => boolean; // Remover tema
+  getTheme: (themeName?: string) => Theme | undefined; // Obter tema
+  tokens: Theme | null; // Tokens do tema atual
+  options: ThemeBuilderOptions; // Opções atuais
+  setOptions: (options: Partial<ThemeBuilderOptions>) => void; // Atualizar opções
+}
+```
+
+## Theme Inheritance
+
+Temas podem herdar de temas base (light ou dark) e sobrescrever apenas o necessário:
+
+```tsx
+const brandTheme = ThemeBuilder.create({
+  name: 'brand',
+  base: 'light', // Herda todos os tokens de 'light'
+  colors: {
+    // Apenas sobrescreve cores
+    primary: {
+      DEFAULT: { hex: '#custom-color' },
+    },
+  },
+  // Outros tokens são herdados de 'light'
+}).build();
+```
+
+## Exemplos
+
+### Toggle de Tema
+
+```tsx
+function ThemeToggle() {
+  const { currentTheme, setTheme, themes } = useAdvancedTheme();
+  
+  return (
+    <select
+      value={currentTheme}
+      onChange={(e) => setTheme(e.target.value)}
+    >
+      {Object.keys(themes).map((name) => (
+        <option key={name} value={name}>
+          {name}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+### Criar Tema Dinamicamente
+
+```tsx
+function ThemeCreator() {
+  const { registerTheme, setTheme } = useAdvancedTheme();
+  const [color, setColor] = useState('#6366f1');
+  
+  const createTheme = () => {
+    const theme = registerTheme({
+      name: `custom-${Date.now()}`,
+      base: 'light',
+      colors: {
+        primary: {
+          DEFAULT: { hex: color },
+        },
+      },
+    });
+    
+    setTheme(theme.name);
+  };
+  
+  return (
+    <div>
+      <input
+        type="color"
+        value={color}
+        onChange={(e) => setColor(e.target.value)}
+      />
+      <button onClick={createTheme}>Create Theme</button>
+    </div>
+  );
+}
+```
+
+## Migração do ThemeProvider Original
+
+O `ThemeProvider` original ainda está disponível e funciona normalmente. Para migrar para o sistema avançado:
+
+**Antes:**
+```tsx
+import { ThemeProvider, useTheme } from '@fabio.caffarello/react-design-system';
+
+<ThemeProvider defaultTheme="light">
+  <App />
+</ThemeProvider>
+```
+
+**Depois:**
+```tsx
+import { AdvancedThemeProvider, useAdvancedTheme } from '@fabio.caffarello/react-design-system';
+
+<AdvancedThemeProvider defaultTheme="light">
+  <App />
+</AdvancedThemeProvider>
+```
+
+O `AdvancedThemeProvider` é compatível com os temas `light` e `dark` padrão, então a migração é simples.

package/src/ui/themes/ThemeBuilder.ts

@@ -0,0 +1,149 @@
+/**
+ * Theme Builder
+ * 
+ * Builder Pattern for creating custom themes.
+ * Supports theme inheritance and CSS variable generation.
+ */
+
+import { TokensFactory, type TokenSet, type ThemeMode } from '../tokens/tokens.factory';
+import type { CustomThemeConfig, Theme } from './types';
+
+export class ThemeBuilder {
+  private config: CustomThemeConfig;
+  private baseFactory: TokensFactory;
+
+  constructor(config: CustomThemeConfig) {
+    this.config = config;
+    const baseMode: ThemeMode = config.base || 'light';
+    this.baseFactory = new TokensFactory(baseMode);
+  }
+
+  /**
+   * Build a complete theme from configuration
+   */
+  build(): Theme {
+    // Start with base token set
+    const baseTokenSet = this.baseFactory.createTokenSet();
+
+    // Merge custom overrides
+    const mergedTokens: TokenSet = {
+      spacing: { ...baseTokenSet.spacing, ...this.config.spacing },
+      typography: { ...baseTokenSet.typography, ...this.config.typography },
+      colors: this.mergeColors(baseTokenSet.colors, this.config.colors),
+      breakpoints: baseTokenSet.breakpoints, // Breakpoints are usually not customized
+      shadows: { ...baseTokenSet.shadows, ...this.config.shadows },
+      radius: { ...baseTokenSet.radius, ...this.config.radius },
+      borders: { ...baseTokenSet.borders, ...this.config.borders },
+      animations: { ...baseTokenSet.animations, ...this.config.animations },
+      zIndex: { ...baseTokenSet.zIndex, ...this.config.zIndex },
+      opacity: { ...baseTokenSet.opacity, ...this.config.opacity },
+      gradients: { ...baseTokenSet.gradients, ...this.config.gradients },
+    };
+
+    // Generate CSS variables
+    const cssVariables = this.generateCSSVariables(mergedTokens);
+
+    return {
+      name: this.config.name,
+      mode: this.config.base || 'light',
+      ...mergedTokens,
+      cssVariables,
+    };
+  }
+
+  /**
+   * Merge color overrides with base colors
+   */
+  private mergeColors(
+    baseColors: Record<string, unknown>,
+    colorOverrides?: Partial<Record<string, Partial<unknown>>>
+  ): Record<string, unknown> {
+    if (!colorOverrides) {
+      return baseColors;
+    }
+
+    const merged = { ...baseColors };
+    for (const [role, override] of Object.entries(colorOverrides)) {
+      if (merged[role]) {
+        merged[role] = { ...merged[role], ...override };
+      }
+    }
+    return merged;
+  }
+
+  /**
+   * Generate CSS variables from token set
+   */
+  private generateCSSVariables(tokens: TokenSet): Record<string, string> {
+    const variables: Record<string, string> = {};
+
+    // Color variables
+    for (const [role, color] of Object.entries(tokens.colors)) {
+      if (color && typeof color === 'object') {
+        for (const [shade, value] of Object.entries(color)) {
+          if (value && typeof value === 'object' && 'hex' in value) {
+            const varName = `--color-${role}-${shade.toLowerCase()}`;
+            variables[varName] = (value as { hex: string }).hex;
+          }
+        }
+      }
+    }
+
+    // Spacing variables
+    for (const [name, token] of Object.entries(tokens.spacing)) {
+      if (token && typeof token === 'object' && 'px' in token) {
+        variables[`--spacing-${name}`] = (token as { px: string }).px;
+      }
+    }
+
+    // Typography variables
+    for (const [name, token] of Object.entries(tokens.typography)) {
+      if (token && typeof token === 'object') {
+        if ('fontSize' in token) {
+          variables[`--font-size-${name}`] = (token as { fontSize: string }).fontSize;
+        }
+        if ('lineHeight' in token) {
+          variables[`--line-height-${name}`] = (token as { lineHeight: string }).lineHeight;
+        }
+        if ('fontWeight' in token) {
+          variables[`--font-weight-${name}`] = (token as { fontWeight: string }).fontWeight;
+        }
+      }
+    }
+
+    // Shadow variables
+    for (const [name, token] of Object.entries(tokens.shadows)) {
+      if (token && typeof token === 'object' && 'value' in token) {
+        variables[`--shadow-${name}`] = (token as { value: string }).value;
+      }
+    }
+
+    // Radius variables
+    for (const [name, token] of Object.entries(tokens.radius)) {
+      if (token && typeof token === 'object' && 'value' in token) {
+        variables[`--radius-${name}`] = (token as { value: string }).value;
+      }
+    }
+
+    // Animation variables
+    for (const [name, token] of Object.entries(tokens.animations)) {
+      if (token && typeof token === 'object') {
+        if ('duration' in token) {
+          variables[`--animation-duration-${name}`] = (token as { duration: string }).duration;
+        }
+        if ('easing' in token) {
+          variables[`--animation-easing-${name}`] = (token as { easing: string }).easing;
+        }
+      }
+    }
+
+    return variables;
+  }
+
+  /**
+   * Create a theme builder instance
+   */
+  static create(config: CustomThemeConfig): ThemeBuilder {
+    return new ThemeBuilder(config);
+  }
+}

package/src/ui/themes/ThemeRegistry.ts

@@ -0,0 +1,187 @@
+/**
+ * Theme Registry
+ * 
+ * Central registry for managing multiple themes.
+ * Supports theme registration, retrieval, and switching.
+ */
+
+import { ThemeBuilder } from './ThemeBuilder';
+import { createTokenSet } from '../tokens/tokens.factory';
+import type { CustomThemeConfig, Theme, ThemeRegistry } from './types';
+
+export class ThemeRegistryManager {
+  private themes: ThemeRegistry = {};
+  private defaultTheme: string = 'light';
+
+  /**
+   * Register a new theme
+   */
+  register(config: CustomThemeConfig): Theme {
+    const builder = ThemeBuilder.create(config);
+    const theme = builder.build();
+    this.themes[theme.name] = theme;
+    return theme;
+  }
+
+  /**
+   * Register built-in themes (light and dark)
+   */
+  registerBuiltInThemes(): void {
+    // Register light theme with CSS variables
+    const lightTokenSet = createTokenSet('light');
+    const lightTheme: Theme = {
+      name: 'light',
+      mode: 'light',
+      ...lightTokenSet,
+      cssVariables: this.generateCSSVariables(lightTokenSet),
+    };
+    this.themes['light'] = lightTheme;
+
+    // Register dark theme with CSS variables
+    const darkTokenSet = createTokenSet('dark');
+    const darkTheme: Theme = {
+      name: 'dark',
+      mode: 'dark',
+      ...darkTokenSet,
+      cssVariables: this.generateCSSVariables(darkTokenSet),
+    };
+    this.themes['dark'] = darkTheme;
+
+    this.defaultTheme = 'light';
+  }
+
+  /**
+   * Generate CSS variables from token set
+   */
+  private generateCSSVariables(tokens: unknown): Record<string, string> {
+    const variables: Record<string, string> = {};
+
+    // Color variables
+    for (const [role, color] of Object.entries(tokens.colors || {})) {
+      if (color && typeof color === 'object') {
+        for (const [shade, value] of Object.entries(color)) {
+          if (value && typeof value === 'object' && 'hex' in value) {
+            const varName = `--color-${role}-${shade.toLowerCase()}`;
+            variables[varName] = (value as { hex: string }).hex;
+          }
+        }
+      }
+    }
+
+    // Spacing variables
+    for (const [name, token] of Object.entries(tokens.spacing || {})) {
+      if (token && typeof token === 'object' && 'px' in token) {
+        variables[`--spacing-${name}`] = (token as { px: string }).px;
+      }
+    }
+
+    // Typography variables
+    for (const [name, token] of Object.entries(tokens.typography || {})) {
+      if (token && typeof token === 'object') {
+        if ('fontSize' in token) {
+          variables[`--font-size-${name}`] = (token as { fontSize: string }).fontSize;
+        }
+        if ('lineHeight' in token) {
+          variables[`--line-height-${name}`] = (token as { lineHeight: string }).lineHeight;
+        }
+        if ('fontWeight' in token) {
+          variables[`--font-weight-${name}`] = (token as { fontWeight: string }).fontWeight;
+        }
+      }
+    }
+
+    // Shadow variables
+    for (const [name, token] of Object.entries(tokens.shadows || {})) {
+      if (token && typeof token === 'object' && 'value' in token) {
+        variables[`--shadow-${name}`] = (token as { value: string }).value;
+      }
+    }
+
+    // Radius variables
+    for (const [name, token] of Object.entries(tokens.radius || {})) {
+      if (token && typeof token === 'object' && 'value' in token) {
+        variables[`--radius-${name}`] = (token as { value: string }).value;
+      }
+    }
+
+    // Animation variables
+    for (const [name, token] of Object.entries(tokens.animations || {})) {
+      if (token && typeof token === 'object') {
+        if ('duration' in token) {
+          variables[`--animation-duration-${name}`] = (token as { duration: string }).duration;
+        }
+        if ('easing' in token) {
+          variables[`--animation-easing-${name}`] = (token as { easing: string }).easing;
+        }
+      }
+    }
+
+    return variables;
+  }
+
+  /**
+   * Get a theme by name
+   */
+  get(name: string): Theme | undefined {
+    return this.themes[name];
+  }
+
+  /**
+   * Get all registered themes
+   */
+  getAll(): ThemeRegistry {
+    return { ...this.themes };
+  }
+
+  /**
+   * Check if a theme exists
+   */
+  has(name: string): boolean {
+    return name in this.themes;
+  }
+
+  /**
+   * Remove a theme
+   */
+  remove(name: string): boolean {
+    if (name === 'light' || name === 'dark') {
+      return false; // Cannot remove built-in themes
+    }
+    if (this.has(name)) {
+      delete this.themes[name];
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get default theme name
+   */
+  getDefaultTheme(): string {
+    return this.defaultTheme;
+  }
+
+  /**
+   * Set default theme
+   */
+  setDefaultTheme(name: string): void {
+    if (this.has(name)) {
+      this.defaultTheme = name;
+    }
+  }
+
+  /**
+   * Get theme names
+   */
+  getThemeNames(): string[] {
+    return Object.keys(this.themes);
+  }
+}
+
+/**
+ * Global theme registry instance
+ */
+export const themeRegistry = new ThemeRegistryManager();
+
+// Initialize with built-in themes
+themeRegistry.registerBuiltInThemes();

package/src/ui/themes/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Themes Module
+ * 
+ * Exports for the advanced theme system.
+ */
+
+export { ThemeBuilder } from './ThemeBuilder';
+export { ThemeRegistryManager, themeRegistry } from './ThemeRegistry';
+export type {
+  CustomThemeConfig,
+  Theme,
+  ThemeRegistry,
+  ThemeBuilderOptions,
+} from './types';
+export {
+  mergeDeep,
+  toCSSVariableName,
+  applyCSSVariables,
+  removeCSSVariables,
+} from './utils';

package/src/ui/themes/types.ts

@@ -0,0 +1,53 @@
+/**
+ * Theme Types
+ * 
+ * Type definitions for the advanced theme system.
+ */
+
+import type { TokenSet, ThemeMode } from '../tokens/tokens.factory';
+import type { ColorRole, SemanticColor } from '../tokens/colors';
+
+/**
+ * Custom theme configuration
+ * Allows partial overrides of the default token set
+ */
+export interface CustomThemeConfig {
+  name: string;
+  base?: ThemeMode; // Base theme to inherit from
+  colors?: Partial<Record<ColorRole, Partial<SemanticColor>>>;
+  spacing?: Partial<TokenSet['spacing']>;
+  typography?: Partial<TokenSet['typography']>;
+  shadows?: Partial<TokenSet['shadows']>;
+  radius?: Partial<TokenSet['radius']>;
+  borders?: Partial<TokenSet['borders']>;
+  animations?: Partial<TokenSet['animations']>;
+  zIndex?: Partial<TokenSet['zIndex']>;
+  opacity?: Partial<TokenSet['opacity']>;
+  gradients?: Partial<TokenSet['gradients']>;
+}
+
+/**
+ * Complete theme definition
+ */
+export interface Theme extends TokenSet {
+  name: string;
+  mode: ThemeMode;
+  cssVariables: Record<string, string>;
+}
+
+/**
+ * Theme registry
+ */
+export interface ThemeRegistry {
+  [themeName: string]: Theme;
+}
+
+/**
+ * Theme builder options
+ */
+export interface ThemeBuilderOptions {
+  enableCSSVariables?: boolean;
+  enableTransitions?: boolean;
+  transitionDuration?: string;
+  storageKey?: string;
+}