@3fn/core 14.1.0 → 15.0.0

package/src/resolvers/AndroidColorResolver.ts

@@ -1,333 +0,0 @@
-/**
- * Android Color Resolver
- * 
- * Generates resource qualifiers (values/values-night) with configuration detection.
- * Supports native Android light/dark mode via resource qualifiers and theme switching.
- * 
- * Output Format:
- * - XML color resources in values/ and values-night/ directories
- * - Automatic mode detection via Android configuration
- * - Theme switching via custom theme attributes
- */
-
-import { ColorTokenValue } from '../types/PrimitiveToken';
-import { ModeThemeResolver, UserTheme } from './ModeThemeResolver';
-
-/**
- * Android XML output options
- */
-export interface AndroidOutputOptions {
-  /** Include theme switching support */
-  includeThemeSwitching?: boolean;
-  /** Default theme to use */
-  defaultTheme?: UserTheme;
-  /** Resource file name (default: 'design_system_colors') */
-  resourceFileName?: string;
-}
-
-/**
- * AndroidColorResolver generates XML color resources for Android platform
- */
-export class AndroidColorResolver {
-  private resolver: ModeThemeResolver;
-
-  constructor() {
-    this.resolver = new ModeThemeResolver();
-  }
-
-  /**
-   * Convert hex color to Android color resource format
-   * Android uses #AARRGGBB or #RRGGBB format
-   * 
-   * @param hex - Hex color string (e.g., '#FF6B35')
-   * @returns Android color resource value
-   */
-  private hexToAndroidColor(hex: string): string {
-    // Ensure hex starts with #
-    return hex.startsWith('#') ? hex.toUpperCase() : `#${hex.toUpperCase()}`;
-  }
-
-  /**
-   * Generate XML color resource for a single color token
-   * 
-   * @param tokenName - Name of the color token (e.g., 'purple300')
-   * @param colorValue - Hex color value
-   * @returns XML color resource line
-   */
-  private generateColorResource(tokenName: string, colorValue: string): string {
-    const snakeCaseName = tokenName.replace(/([A-Z])/g, '_$1').toLowerCase();
-    return `    <color name="${snakeCaseName}">${this.hexToAndroidColor(colorValue)}</color>`;
-  }
-
-  /**
-   * Generate values/colors.xml for light mode
-   * 
-   * @param tokens - Object mapping token names to color values
-   * @param options - Android output options
-   * @returns XML content for values/colors.xml
-   */
-  generateLightModeColors(
-    tokens: Record<string, ColorTokenValue>,
-    options: AndroidOutputOptions = {}
-  ): string {
-    const { defaultTheme = 'base' } = options;
-
-    let xml = '<?xml version="1.0" encoding="utf-8"?>\n';
-    xml += '<!--\n';
-    xml += '  Design System Color Tokens - Light Mode\n';
-    xml += '  Generated with mode-aware and theme-aware support\n';
-    xml += '-->\n';
-    xml += '<resources>\n';
-
-    Object.entries(tokens).forEach(([tokenName, colorValue]) => {
-      const allValues = this.resolver.resolveAll(colorValue);
-      xml += this.generateColorResource(tokenName, allValues.light[defaultTheme]);
-      xml += '\n';
-    });
-
-    xml += '</resources>\n';
-
-    return xml;
-  }
-
-  /**
-   * Generate values-night/colors.xml for dark mode
-   * 
-   * @param tokens - Object mapping token names to color values
-   * @param options - Android output options
-   * @returns XML content for values-night/colors.xml
-   */
-  generateDarkModeColors(
-    tokens: Record<string, ColorTokenValue>,
-    options: AndroidOutputOptions = {}
-  ): string {
-    const { defaultTheme = 'base' } = options;
-
-    let xml = '<?xml version="1.0" encoding="utf-8"?>\n';
-    xml += '<!--\n';
-    xml += '  Design System Color Tokens - Dark Mode\n';
-    xml += '  Generated with mode-aware and theme-aware support\n';
-    xml += '-->\n';
-    xml += '<resources>\n';
-
-    Object.entries(tokens).forEach(([tokenName, colorValue]) => {
-      const allValues = this.resolver.resolveAll(colorValue);
-      xml += this.generateColorResource(tokenName, allValues.dark[defaultTheme]);
-      xml += '\n';
-    });
-
-    xml += '</resources>\n';
-
-    return xml;
-  }
-
-  /**
-   * Generate WCAG theme colors for light mode
-   * 
-   * @param tokens - Object mapping token names to color values
-   * @returns XML content for values/colors_wcag.xml
-   */
-  generateLightModeWcagColors(
-    tokens: Record<string, ColorTokenValue>
-  ): string {
-    let xml = '<?xml version="1.0" encoding="utf-8"?>\n';
-    xml += '<!--\n';
-    xml += '  Design System Color Tokens - Light Mode (WCAG Theme)\n';
-    xml += '  Generated with WCAG 2.2 compliant colors\n';
-    xml += '-->\n';
-    xml += '<resources>\n';
-
-    Object.entries(tokens).forEach(([tokenName, colorValue]) => {
-      const allValues = this.resolver.resolveAll(colorValue);
-      const snakeCaseName = tokenName.replace(/([A-Z])/g, '_$1').toLowerCase();
-      xml += `    <color name="${snakeCaseName}_wcag">${this.hexToAndroidColor(allValues.light.wcag)}</color>\n`;
-    });
-
-    xml += '</resources>\n';
-
-    return xml;
-  }
-
-  /**
-   * Generate WCAG theme colors for dark mode
-   * 
-   * @param tokens - Object mapping token names to color values
-   * @returns XML content for values-night/colors_wcag.xml
-   */
-  generateDarkModeWcagColors(
-    tokens: Record<string, ColorTokenValue>
-  ): string {
-    let xml = '<?xml version="1.0" encoding="utf-8"?>\n';
-    xml += '<!--\n';
-    xml += '  Design System Color Tokens - Dark Mode (WCAG Theme)\n';
-    xml += '  Generated with WCAG 2.2 compliant colors\n';
-    xml += '-->\n';
-    xml += '<resources>\n';
-
-    Object.entries(tokens).forEach(([tokenName, colorValue]) => {
-      const allValues = this.resolver.resolveAll(colorValue);
-      const snakeCaseName = tokenName.replace(/([A-Z])/g, '_$1').toLowerCase();
-      xml += `    <color name="${snakeCaseName}_wcag">${this.hexToAndroidColor(allValues.dark.wcag)}</color>\n`;
-    });
-
-    xml += '</resources>\n';
-
-    return xml;
-  }
-
-  /**
-   * Generate Kotlin extension functions for color access
-   * 
-   * @param tokens - Object mapping token names to color values
-   * @param options - Android output options
-   * @returns Kotlin extension code
-   */
-  generateKotlinExtension(
-    tokens: Record<string, ColorTokenValue>,
-    options: AndroidOutputOptions = {}
-  ): string {
-    const { includeThemeSwitching = true } = options;
-
-    let kotlin = '/**\n';
-    kotlin += ' * Design System Color Tokens\n';
-    kotlin += ' * Generated with mode-aware and theme-aware support\n';
-    kotlin += ' */\n\n';
-
-    kotlin += 'package com.designsystem.tokens\n\n';
-
-    kotlin += 'import android.content.Context\n';
-    kotlin += 'import android.content.SharedPreferences\n';
-    kotlin += 'import androidx.annotation.ColorRes\n';
-    kotlin += 'import androidx.core.content.ContextCompat\n\n';
-
-    kotlin += '/**\n';
-    kotlin += ' * Design System color token extensions\n';
-    kotlin += ' */\n';
-    kotlin += 'object DesignSystemColors {\n\n';
-
-    // Generate color getters
-    Object.keys(tokens).forEach(tokenName => {
-      const snakeCaseName = tokenName.replace(/([A-Z])/g, '_$1').toLowerCase();
-      const camelCaseName = tokenName.charAt(0).toLowerCase() + tokenName.slice(1);
-
-      kotlin += `    /**\n`;
-      kotlin += `     * Get ${tokenName} color with theme support\n`;
-      kotlin += `     */\n`;
-      kotlin += `    fun ${camelCaseName}(context: Context): Int {\n`;
-
-      if (includeThemeSwitching) {
-        kotlin += `        val prefs = context.getSharedPreferences("design_system", Context.MODE_PRIVATE)\n`;
-        kotlin += `        val theme = prefs.getString("theme", "base") ?: "base"\n`;
-        kotlin += `        \n`;
-        kotlin += `        val colorRes = if (theme == "wcag") {\n`;
-        kotlin += `            R.color.${snakeCaseName}_wcag\n`;
-        kotlin += `        } else {\n`;
-        kotlin += `            R.color.${snakeCaseName}\n`;
-        kotlin += `        }\n`;
-        kotlin += `        \n`;
-        kotlin += `        return ContextCompat.getColor(context, colorRes)\n`;
-      } else {
-        kotlin += `        return ContextCompat.getColor(context, R.color.${snakeCaseName})\n`;
-      }
-
-      kotlin += `    }\n\n`;
-    });
-
-    // Add theme switching helper
-    if (includeThemeSwitching) {
-      kotlin += `    /**\n`;
-      kotlin += `     * Set design system theme\n`;
-      kotlin += `     */\n`;
-      kotlin += `    fun setTheme(context: Context, theme: String) {\n`;
-      kotlin += `        val prefs = context.getSharedPreferences("design_system", Context.MODE_PRIVATE)\n`;
-      kotlin += `        prefs.edit().putString("theme", theme).apply()\n`;
-      kotlin += `    }\n\n`;
-
-      kotlin += `    /**\n`;
-      kotlin += `     * Get current design system theme\n`;
-      kotlin += `     */\n`;
-      kotlin += `    fun getTheme(context: Context): String {\n`;
-      kotlin += `        val prefs = context.getSharedPreferences("design_system", Context.MODE_PRIVATE)\n`;
-      kotlin += `        return prefs.getString("theme", "base") ?: "base"\n`;
-      kotlin += `    }\n`;
-    }
-
-    kotlin += '}\n';
-
-    return kotlin;
-  }
-
-  /**
-   * Generate complete Android resource structure
-   * Returns object with all necessary files
-   * 
-   * @param tokens - Object mapping token names to color values
-   * @param options - Android output options
-   * @returns Object containing all Android resource files
-   */
-  generateAndroidResources(
-    tokens: Record<string, ColorTokenValue>,
-    options: AndroidOutputOptions = {}
-  ): {
-    'values/colors.xml': string;
-    'values-night/colors.xml': string;
-    'values/colors_wcag.xml'?: string;
-    'values-night/colors_wcag.xml'?: string;
-    'kotlin/DesignSystemColors.kt': string;
-  } {
-    const { includeThemeSwitching = true } = options;
-
-    const resources: any = {
-      'values/colors.xml': this.generateLightModeColors(tokens, options),
-      'values-night/colors.xml': this.generateDarkModeColors(tokens, options),
-      'kotlin/DesignSystemColors.kt': this.generateKotlinExtension(tokens, options)
-    };
-
-    if (includeThemeSwitching) {
-      resources['values/colors_wcag.xml'] = this.generateLightModeWcagColors(tokens);
-      resources['values-night/colors_wcag.xml'] = this.generateDarkModeWcagColors(tokens);
-    }
-
-    return resources;
-  }
-
-  /**
-   * Generate usage example documentation
-   * 
-   * @returns Kotlin usage example code
-   */
-  generateUsageExample(): string {
-    let example = '/**\n';
-    example += ' * Usage Examples\n';
-    example += ' */\n\n';
-
-    example += '// MARK: - Basic Usage\n\n';
-    example += '// Use color tokens in your views\n';
-    example += 'view.setBackgroundColor(DesignSystemColors.purple300(context))\n';
-    example += 'textView.setTextColor(DesignSystemColors.gray300(context))\n\n';
-
-    example += '// MARK: - Theme Switching\n\n';
-    example += '// Switch to WCAG theme\n';
-    example += 'DesignSystemColors.setTheme(context, "wcag")\n\n';
-
-    example += '// Switch back to base theme\n';
-    example += 'DesignSystemColors.setTheme(context, "base")\n\n';
-
-    example += '// Get current theme\n';
-    example += 'val currentTheme = DesignSystemColors.getTheme(context)\n\n';
-
-    example += '// MARK: - Automatic Mode Detection\n\n';
-    example += '// Colors automatically adapt to light/dark mode\n';
-    example += '// based on system configuration (values/values-night)\n';
-    example += '// No additional code needed!\n';
-
-    return example;
-  }
-
-  /**
-   * Get resolver instance for direct color resolution
-   */
-  getResolver(): ModeThemeResolver {
-    return this.resolver;
-  }
-}

package/src/resolvers/ModeThemeResolver.ts

@@ -1,152 +0,0 @@
-/**
- * Mode Theme Resolver
- * 
- * Core resolution logic for handling colorToken[systemMode][userTheme] pattern.
- * Resolves color tokens based on system mode (light/dark) and user theme preference (base/wcag).
- * 
- * Resolution Pattern: colorToken[systemMode][userTheme]
- * - systemMode: 'light' | 'dark' (detected from system preferences)
- * - userTheme: 'base' | 'wcag' (user preference, defaults to 'base')
- */
-
-import { ColorTokenValue, ModeThemeValues } from '../types/PrimitiveToken';
-
-/**
- * System mode options
- */
-export type SystemMode = 'light' | 'dark';
-
-/**
- * User theme options
- */
-export type UserTheme = 'base' | 'wcag';
-
-/**
- * Resolution result containing resolved color and metadata
- */
-export interface ColorResolutionResult {
-  /** Resolved hex color value */
-  color: string;
-  /** System mode used for resolution */
-  mode: SystemMode;
-  /** User theme used for resolution */
-  theme: UserTheme;
-  /** Whether default theme was used */
-  usedDefaultTheme: boolean;
-}
-
-/**
- * ModeThemeResolver handles resolution of mode-aware color tokens
- */
-export class ModeThemeResolver {
-  private defaultTheme: UserTheme = 'base';
-
-  /**
-   * Resolve color token value based on system mode and user theme
-   * 
-   * @param colorValue - Color token value with mode/theme structure
-   * @param systemMode - System mode (light/dark), defaults to 'light'
-   * @param userTheme - User theme preference (base/wcag), defaults to 'base'
-   * @returns Resolved color resolution result
-   */
-  resolve(
-    colorValue: ColorTokenValue,
-    systemMode: SystemMode = 'light',
-    userTheme?: UserTheme
-  ): ColorResolutionResult {
-    // Use default theme if not specified
-    const resolvedTheme = userTheme ?? this.defaultTheme;
-    const usedDefaultTheme = userTheme === undefined;
-
-    // Resolve: colorToken[systemMode][userTheme]
-    const modeValues: ModeThemeValues = colorValue[systemMode];
-    const resolvedColor: string = modeValues[resolvedTheme];
-
-    return {
-      color: resolvedColor,
-      mode: systemMode,
-      theme: resolvedTheme,
-      usedDefaultTheme
-    };
-  }
-
-  /**
-   * Get default theme
-   */
-  getDefaultTheme(): UserTheme {
-    return this.defaultTheme;
-  }
-
-  /**
-   * Set default theme
-   * 
-   * @param theme - Theme to set as default
-   */
-  setDefaultTheme(theme: UserTheme): void {
-    this.defaultTheme = theme;
-  }
-
-  /**
-   * Resolve all mode/theme combinations for a color token
-   * Useful for generating platform-specific outputs that need all variants
-   * 
-   * @param colorValue - Color token value with mode/theme structure
-   * @returns Object containing all mode/theme combinations
-   */
-  resolveAll(colorValue: ColorTokenValue): {
-    light: { base: string; wcag: string };
-    dark: { base: string; wcag: string };
-  } {
-    return {
-      light: {
-        base: colorValue.light.base,
-        wcag: colorValue.light.wcag
-      },
-      dark: {
-        base: colorValue.dark.base,
-        wcag: colorValue.dark.wcag
-      }
-    };
-  }
-
-  /**
-   * Validate color token value structure
-   * 
-   * @param colorValue - Color token value to validate
-   * @returns True if valid, false otherwise
-   */
-  validate(colorValue: ColorTokenValue): boolean {
-    try {
-      // Check light mode exists
-      if (!colorValue.light || typeof colorValue.light !== 'object') {
-        return false;
-      }
-
-      // Check dark mode exists
-      if (!colorValue.dark || typeof colorValue.dark !== 'object') {
-        return false;
-      }
-
-      // Check light mode themes
-      if (typeof colorValue.light.base !== 'string' || typeof colorValue.light.wcag !== 'string') {
-        return false;
-      }
-
-      // Check dark mode themes
-      if (typeof colorValue.dark.base !== 'string' || typeof colorValue.dark.wcag !== 'string') {
-        return false;
-      }
-
-      // Validate color format: rgba() (current standard) or hex (legacy/test)
-      const colorPattern = /^(rgba\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*[\d.]+\s*\)|#[0-9A-Fa-f]{6})$/;
-      return (
-        colorPattern.test(colorValue.light.base) &&
-        colorPattern.test(colorValue.light.wcag) &&
-        colorPattern.test(colorValue.dark.base) &&
-        colorPattern.test(colorValue.dark.wcag)
-      );
-    } catch {
-      return false;
-    }
-  }
-}

package/src/resolvers/SemanticOverrideResolver.ts

@@ -1,155 +0,0 @@
-/**
- * SemanticOverrideResolver — Level 2 of the two-level mode-aware resolution system.
- *
- * Sits between Registry and Generation in the token pipeline. For dark mode,
- * swaps primitiveReferences on overridden tokens. For light mode, passes
- * tokens through unchanged.
- *
- * @see design.md § "Two-Level Resolution"
- * @see tasks.md Task 2.2
- */
-
-import type { SemanticToken } from '../types/SemanticToken';
-import type { SemanticTokenRegistry } from '../registries/SemanticTokenRegistry';
-import type { SemanticOverrideMap, ThemeContext, ContextOverrideSet } from '../tokens/themes/types';
-import type { ThemeRegistry } from '../themes/ThemeRegistry';
-import type { ResolvedThemeSet } from '../themes/ResolvedThemeSet';
-
-export interface OverrideValidationResult {
-  valid: boolean;
-  errors: string[];
-}
-
-export interface ResolvedTokenSets {
-  light: SemanticToken[];
-  dark: SemanticToken[];
-}
-
-export interface ContextResolvedTokenSets {
-  'light-base': SemanticToken[];
-  'light-wcag': SemanticToken[];
-  'dark-base': SemanticToken[];
-  'dark-wcag': SemanticToken[];
-}
-
-/** Apply a single override to a token (if present in the map). */
-function applyOverride(token: SemanticToken, overrides: SemanticOverrideMap): SemanticToken {
-  const override = overrides[token.name];
-  if (!override) return token;
-  return {
-    ...token,
-    primitiveReferences: override.primitiveReferences,
-    modifiers: 'modifiers' in override ? override.modifiers : token.modifiers,
-  };
-}
-
-export class SemanticOverrideResolver {
-  constructor(
-    private registry: SemanticTokenRegistry,
-    private overrides: SemanticOverrideMap
-  ) {}
-
-  /** Validate all override keys exist in the semantic token registry. */
-  validate(): OverrideValidationResult {
-    const errors: string[] = [];
-    for (const key of Object.keys(this.overrides)) {
-      if (!this.registry.get(key)) {
-        errors.push(`Orphaned override key "${key}": no matching semantic token in registry`);
-      }
-    }
-    return { valid: errors.length === 0, errors };
-  }
-
-  /** Validate a ContextOverrideSet — all keys in all maps must exist in registry. */
-  validateAll(contextOverrides: ContextOverrideSet): OverrideValidationResult {
-    const errors: string[] = [];
-    for (const [context, overrideMap] of Object.entries(contextOverrides)) {
-      for (const key of Object.keys(overrideMap!)) {
-        if (!this.registry.get(key)) {
-          errors.push(`Orphaned override key "${key}" in ${context}: no matching semantic token in registry`);
-        }
-      }
-    }
-    return { valid: errors.length === 0, errors };
-  }
-
-  /** Resolve a single token for the given mode (Phase 1 API — backward compatible). */
-  resolve(token: SemanticToken, mode: 'light' | 'dark'): SemanticToken {
-    if (mode === 'light') return token;
-    return applyOverride(token, this.overrides);
-  }
-
-  /** Produce light and dark token sets (Phase 1 API — backward compatible). */
-  resolveAll(tokens: SemanticToken[]): ResolvedTokenSets {
-    return {
-      light: tokens.map(t => this.resolve(t, 'light')),
-      dark: tokens.map(t => this.resolve(t, 'dark')),
-    };
-  }
-
-  /**
-   * Produce 4 context-resolved token sets from a ContextOverrideSet.
-   * Each context applies its override maps in order: context-specific last wins.
-   */
-  resolveAllContexts(tokens: SemanticToken[], contextOverrides: ContextOverrideSet): ContextResolvedTokenSets {
-    const contexts: ThemeContext[] = ['light-base', 'light-wcag', 'dark-base', 'dark-wcag'];
-    const result = {} as ContextResolvedTokenSets;
-
-    for (const ctx of contexts) {
-      const overrideMap = contextOverrides[ctx];
-      result[ctx] = tokens.map(t => overrideMap ? applyOverride(t, overrideMap) : t);
-    }
-
-    return result;
-  }
-
-  /**
-   * Resolve tokens for all registered themes in a ThemeRegistry.
-   * Returns a ResolvedThemeSet per context (mode × theme combination).
-   *
-   * For themes with mode 'both', produces two sets (light + dark).
-   * For themes with mode 'dark' or 'light', produces one set.
-   *
-   * The base theme (light-base, dark-base) is always included as the
-   * no-override baseline, even if no 'base' theme is registered.
-   */
-  resolveForRegistry(tokens: SemanticToken[], themeRegistry: ThemeRegistry): ResolvedThemeSet[] {
-    const results: ResolvedThemeSet[] = [];
-
-    // Always include the base contexts (no overrides)
-    results.push({
-      theme: null,
-      contextKey: 'light-base',
-      mode: 'light',
-      themeId: 'base',
-      tokens: tokens.map(t => ({ ...t })),
-    });
-    results.push({
-      theme: null,
-      contextKey: 'dark-base',
-      mode: 'dark',
-      themeId: 'base',
-      tokens: tokens.map(t => ({ ...t })),
-    });
-
-    // Resolve each registered theme
-    for (const theme of themeRegistry.getAll()) {
-      const modes: Array<'light' | 'dark'> =
-        theme.mode === 'both' ? ['light', 'dark'] :
-        theme.mode === 'dark' ? ['dark'] :
-        ['light'];
-
-      for (const mode of modes) {
-        results.push({
-          theme,
-          contextKey: `${mode}-${theme.name}`,
-          mode,
-          themeId: theme.name,
-          tokens: tokens.map(t => applyOverride(t, theme.overrides)),
-        });
-      }
-    }
-
-    return results;
-  }
-}