@3fn/core 14.0.0 → 15.0.0

package/src/providers/iOSUnitConverter.ts

@@ -1,125 +0,0 @@
-import { PrimitiveToken, PlatformValues } from '../types';
-import { BaseUnitProvider, UnitConversionConfig } from './UnitProvider';
-
-/**
- * iOS-specific unit converter
- * Converts unitless token values to iOS-appropriate units (points, unitless)
- */
-export class iOSUnitConverter extends BaseUnitProvider {
-  readonly platform = 'ios' as const;
-
-  constructor(config: UnitConversionConfig = {}) {
-    super({
-      displayScale: 1.0, // Default @1x scale, can be 2.0 for @2x, 3.0 for @3x
-      ...config
-    });
-  }
-
-  convertToken(token: PrimitiveToken): PlatformValues['ios'] {
-    return this.convertValue(token.baseValue, token.category);
-  }
-
-  convertValue(baseValue: number | string, category: string): PlatformValues['ios'] {
-    switch (category) {
-      case 'spacing':
-      case 'radius':
-      case 'fontSize':
-      case 'tapArea':
-        // Convert to points (1:1 ratio for most values)
-        // Points are device-independent units in iOS
-        return { value: baseValue as number, unit: 'pt' };
-      
-      case 'fontFamily':
-        // Font family remains as string for iOS
-        return { value: baseValue as string, unit: 'fontFamily' };
-
-      case 'fontWeight':
-        // Font weight remains as numeric for iOS
-        return { value: baseValue as number, unit: 'fontWeight' };
-
-      case 'letterSpacing':
-        // Letter spacing converted to em units for iOS
-        return { value: baseValue as number, unit: 'em' };
-      
-      case 'lineHeight':
-        // Line height remains unitless for proper UIKit behavior
-        return { value: baseValue as number, unit: 'unitless' };
-      
-      case 'density':
-        // Density is a multiplier, remains unitless
-        return { value: baseValue as number, unit: 'unitless' };
-      
-      default:
-        // Default to points for unknown categories
-        return { value: baseValue as number, unit: 'pt' };
-    }
-  }
-
-  getConversionFactor(category: string): number | { factor: number; unit: string } {
-    switch (category) {
-      case 'spacing':
-      case 'radius':
-      case 'fontSize':
-      case 'tapArea':
-        return { factor: 1, unit: 'pt' };
-
-      case 'fontFamily':
-        return { factor: 1, unit: 'fontFamily' }; // Pass-through for strings
-
-      case 'fontWeight':
-        return { factor: 1, unit: 'fontWeight' }; // Pass-through for numeric weights
-
-      case 'letterSpacing':
-        return { factor: 1, unit: 'em' }; // 1:1 conversion to em
-      
-      case 'lineHeight':
-      case 'density':
-        return { factor: 1, unit: 'unitless' };
-      
-      default:
-        return { factor: 1, unit: 'pt' };
-    }
-  }
-
-  /**
-   * Get the display scale factor (1.0 for @1x, 2.0 for @2x, 3.0 for @3x)
-   */
-  getDisplayScale(): number {
-    return this.config.displayScale!;
-  }
-
-  /**
-   * Convert points to pixels for a given display scale
-   * This is useful for understanding the actual pixel dimensions
-   */
-  pointsToPixels(pointValue: number, scale?: number): number {
-    const displayScale = scale || this.config.displayScale!;
-    return pointValue * displayScale;
-  }
-
-  /**
-   * Convert pixels to points for a given display scale
-   */
-  pixelsToPoints(pixelValue: number, scale?: number): number {
-    const displayScale = scale || this.config.displayScale!;
-    return pixelValue / displayScale;
-  }
-
-  /**
-   * Handle density considerations for iOS
-   * iOS uses display scale rather than density buckets
-   */
-  applyDensityConsiderations(baseValue: number, category: string): number {
-    // For iOS, density is handled through display scale
-    // Most values remain 1:1 with points, but can be adjusted for specific needs
-    switch (category) {
-      case 'tapArea':
-        // Tap areas might need slight adjustments for different device sizes
-        // but generally remain consistent in points
-        return baseValue;
-      
-      default:
-        return baseValue;
-    }
-  }
-}

package/src/providers/index.ts

@@ -1,26 +0,0 @@
-// Unit Provider interfaces and base classes
-export { UnitProvider, UnitConversionConfig, BaseUnitProvider } from './UnitProvider';
-
-// Platform-specific unit converters
-export { WebUnitConverter } from './WebUnitConverter';
-export { iOSUnitConverter } from './iOSUnitConverter';
-export { AndroidUnitConverter, AndroidDensity } from './AndroidUnitConverter';
-
-// Format Provider interfaces and base classes
-export { FormatProvider, BaseFormatProvider, FormatOptions, FileMetadata } from './FormatProvider';
-
-// Platform-specific format generators
-export { WebFormatGenerator } from './WebFormatGenerator';
-export { iOSFormatGenerator } from './iOSFormatGenerator';
-export { AndroidFormatGenerator } from './AndroidFormatGenerator';
-
-// Path Provider interfaces and base classes
-export { PathProvider, BasePathProvider, PathOptions, BuildSystemConfig, OptimizedFileStructure } from './PathProvider';
-
-// Platform-specific file organizers
-export { WebFileOrganizer } from './WebFileOrganizer';
-export { iOSFileOrganizer } from './iOSFileOrganizer';
-export { AndroidFileOrganizer } from './AndroidFileOrganizer';
-
-// Type exports for convenience
-export type { PlatformValues } from '../types';

package/src/registries/ComponentTokenRegistry.ts

@@ -1,292 +0,0 @@
-/**
- * Component Token Registry
- * 
- * Global registry for component tokens that collects tokens from all components.
- * Follows the same pattern as PrimitiveTokenRegistry and SemanticTokenRegistry.
- * 
- * Provides registration, retrieval, and query methods for component tokens.
- * Detects naming conflicts when two components define tokens with the same name.
- * 
- * @see Requirements 4.1-4.6 in .kiro/specs/037-component-token-generation-pipeline/requirements.md
- */
-
-import type { IRegistry, RegistrationOptions } from './IRegistry';
-
-/**
- * Registered component token with full metadata
- * 
- * This is the structure stored in the ComponentTokenRegistry.
- * It contains all information needed for validation and platform output generation.
- */
-export interface RegisteredComponentToken {
-  /** Full token name (e.g., 'buttonicon.inset.large') */
-  name: string;
-  /** Component this token belongs to */
-  component: string;
-  /** Token family */
-  family: string;
-  /** Resolved numeric value */
-  value: number;
-  /** Reference to primitive token name (if applicable) */
-  primitiveReference?: string;
-  /** Explanation of why this token exists */
-  reasoning: string;
-}
-
-/**
- * Registration options for component tokens.
- *
- * Spec 124 retired `allowOverwrite`: the harvest in `loadComponentTokens` is the sole
- * writer to this registry, so no double-registration path remains and a duplicate token
- * name is always a genuine conflict (thrown by `register`).
- */
-export type ComponentTokenRegistrationOptions = RegistrationOptions;
-
-/**
- * Query options for component tokens
- */
-export interface ComponentTokenQueryOptions {
-  /** Filter by component name */
-  component?: string;
-  /** Filter by token family */
-  family?: string;
-  /** Sort results */
-  sortBy?: 'name' | 'component' | 'family' | 'value';
-}
-
-/**
- * Component Token Registry Implementation
- * 
- * Manages component tokens with indexing by component and family.
- * Implements IRegistry<RegisteredComponentToken> for consistent registry interface.
- */
-class ComponentTokenRegistryImpl implements IRegistry<RegisteredComponentToken> {
-  /**
-   * Registry name for identification
-   */
-  readonly name = 'ComponentTokenRegistry';
-
-  /** Primary token storage by name */
-  private tokens: Map<string, RegisteredComponentToken> = new Map();
-  
-  /** Index by component name */
-  private byComponent: Map<string, RegisteredComponentToken[]> = new Map();
-  
-  /** Index by token family */
-  private byFamily: Map<string, RegisteredComponentToken[]> = new Map();
-
-  /**
-   * Register a single component token
-   *
-   * Implements IRegistry.register() interface.
-   *
-   * @param token - The component token to register
-   * @param _options - Registration options (reserved; `allowOverwrite` retired in Spec 124)
-   * @throws Error if a token with the same name is already registered (genuine conflict —
-   *   the harvest is the sole writer, so a duplicate name means two components defined the
-   *   same token).
-   */
-  register(token: RegisteredComponentToken, _options: ComponentTokenRegistrationOptions = {}): void {
-    // Check for conflicts (genuine duplicate-name guard; no overwrite path remains).
-    if (this.tokens.has(token.name)) {
-      const existing = this.tokens.get(token.name)!;
-      throw new Error(
-        `Component token conflict: "${token.name}" already registered by ` +
-        `${existing.component}. Attempted registration by ${token.component}.`
-      );
-    }
-
-    // Store token
-    this.tokens.set(token.name, token);
-
-    // Index by component
-    if (!this.byComponent.has(token.component)) {
-      this.byComponent.set(token.component, []);
-    }
-    this.byComponent.get(token.component)!.push(token);
-
-    // Index by family
-    if (!this.byFamily.has(token.family)) {
-      this.byFamily.set(token.family, []);
-    }
-    this.byFamily.get(token.family)!.push(token);
-  }
-
-  /**
-   * Register a batch of component tokens for a component
-   * 
-   * This is the primary method called by defineComponentTokens().
-   * 
-   * @param component - Component name (for error messages)
-   * @param tokens - Array of tokens to register
-   * @throws Error if any token conflicts with existing tokens
-   */
-  registerBatch(component: string, tokens: RegisteredComponentToken[]): void {
-    for (const token of tokens) {
-      this.register(token);
-    }
-  }
-
-  /**
-   * Get all registered component tokens
-   * 
-   * Implements IRegistry.query() interface.
-   * 
-   * @returns Array of all registered tokens
-   */
-  query(): RegisteredComponentToken[] {
-    return Array.from(this.tokens.values());
-  }
-
-  /**
-   * Get all registered component tokens (alias for query)
-   * 
-   * @returns Array of all registered tokens
-   */
-  getAll(): RegisteredComponentToken[] {
-    return this.query();
-  }
-
-  /**
-   * Get tokens for a specific component
-   * 
-   * @param componentName - Component name to filter by
-   * @returns Array of tokens for the component
-   */
-  getByComponent(componentName: string): RegisteredComponentToken[] {
-    return this.byComponent.get(componentName) || [];
-  }
-
-  /**
-   * Get tokens by token family
-   * 
-   * @param familyName - Family name to filter by (e.g., 'spacing', 'fontSize')
-   * @returns Array of tokens in the family
-   */
-  getByFamily(familyName: string): RegisteredComponentToken[] {
-    return this.byFamily.get(familyName) || [];
-  }
-
-  /**
-   * Get a specific token by name
-   * 
-   * Implements IRegistry.get() interface.
-   * 
-   * @param tokenName - Full token name (e.g., 'buttonicon.inset.large')
-   * @returns Token if found, undefined otherwise
-   */
-  get(tokenName: string): RegisteredComponentToken | undefined {
-    return this.tokens.get(tokenName);
-  }
-
-  /**
-   * Check if a token exists
-   * 
-   * Implements IRegistry.has() interface.
-   * 
-   * @param tokenName - Full token name to check
-   * @returns True if token exists, false otherwise
-   */
-  has(tokenName: string): boolean {
-    return this.tokens.has(tokenName);
-  }
-
-  /**
-   * Get registry statistics
-   * 
-   * @returns Statistics about registered tokens
-   */
-  getStats(): {
-    totalTokens: number;
-    componentCount: number;
-    familyCount: number;
-    componentStats: Record<string, number>;
-    familyStats: Record<string, number>;
-  } {
-    const componentStats: Record<string, number> = {};
-    for (const [component, tokens] of this.byComponent) {
-      componentStats[component] = tokens.length;
-    }
-
-    const familyStats: Record<string, number> = {};
-    for (const [family, tokens] of this.byFamily) {
-      familyStats[family] = tokens.length;
-    }
-
-    return {
-      totalTokens: this.tokens.size,
-      componentCount: this.byComponent.size,
-      familyCount: this.byFamily.size,
-      componentStats,
-      familyStats,
-    };
-  }
-
-  /**
-   * Remove a token from the registry
-   * 
-   * @param tokenName - Full token name to remove
-   * @returns True if token was removed, false if not found
-   */
-  remove(tokenName: string): boolean {
-    if (!this.tokens.has(tokenName)) {
-      return false;
-    }
-
-    this.removeFromIndexes(tokenName);
-    this.tokens.delete(tokenName);
-    return true;
-  }
-
-  /**
-   * Clear all tokens from the registry
-   * 
-   * Useful for testing to reset state between tests.
-   */
-  clear(): void {
-    this.tokens.clear();
-    this.byComponent.clear();
-    this.byFamily.clear();
-  }
-
-  /**
-   * Remove a token from component and family indexes
-   * 
-   * @param tokenName - Token name to remove from indexes
-   */
-  private removeFromIndexes(tokenName: string): void {
-    const token = this.tokens.get(tokenName);
-    if (!token) return;
-
-    // Remove from component index
-    const componentTokens = this.byComponent.get(token.component);
-    if (componentTokens) {
-      const index = componentTokens.findIndex(t => t.name === tokenName);
-      if (index !== -1) {
-        componentTokens.splice(index, 1);
-      }
-      if (componentTokens.length === 0) {
-        this.byComponent.delete(token.component);
-      }
-    }
-
-    // Remove from family index
-    const familyTokens = this.byFamily.get(token.family);
-    if (familyTokens) {
-      const index = familyTokens.findIndex(t => t.name === tokenName);
-      if (index !== -1) {
-        familyTokens.splice(index, 1);
-      }
-      if (familyTokens.length === 0) {
-        this.byFamily.delete(token.family);
-      }
-    }
-  }
-}
-
-/**
- * Singleton instance of the Component Token Registry
- * 
- * This is the global registry used by defineComponentTokens() and the generation pipeline.
- */
-export const ComponentTokenRegistry = new ComponentTokenRegistryImpl();

package/src/registries/IRegistry.ts

@@ -1,170 +0,0 @@
-/**
- * Common interface for all token registries
- * 
- * This interface establishes a consistent contract for token storage and retrieval
- * across different registry implementations. It enables polymorphic usage of registries
- * and ensures separation of concerns by focusing solely on storage operations without
- * validation logic.
- * 
- * @template TToken - The type of token this registry stores (e.g., PrimitiveToken, SemanticToken)
- * 
- * @example
- * ```typescript
- * // Implementing a registry
- * class MyTokenRegistry implements IRegistry<MyToken> {
- *   readonly name = 'MyTokenRegistry';
- *   
- *   register(token: MyToken, options?: RegistrationOptions): void {
- *     // Storage logic only - no validation
- *   }
- *   
- *   query(): MyToken[] {
- *     // Return all tokens
- *   }
- *   
- *   get(name: string): MyToken | undefined {
- *     // Retrieve specific token
- *   }
- *   
- *   has(name: string): boolean {
- *     // Check token existence
- *   }
- * }
- * ```
- */
-export interface IRegistry<TToken> {
-  /**
-   * Registry name for identification and logging
-   * 
-   * This property helps identify which registry is being used in logs,
-   * error messages, and debugging scenarios.
-   * 
-   * @example
-   * ```typescript
-   * console.log(`Using registry: ${registry.name}`);
-   * // Output: "Using registry: PrimitiveTokenRegistry"
-   * ```
-   */
-  readonly name: string;
-
-  /**
-   * Register a token in the registry
-   * 
-   * This method stores a token without performing validation. Validation should
-   * be performed by the caller before registration using appropriate validators.
-   * 
-   * The registry trusts that tokens passed to this method are valid and focuses
-   * solely on storage operations.
-   * 
-   * @param token - The token to register
-   * @param options - Optional registration options
-   * 
-   * @throws May throw if token with same name already exists (implementation-specific)
-   * 
-   * @example
-   * ```typescript
-   * // Caller validates before registration
-   * const validationResult = validator.validate(token);
-   * if (validationResult.valid) {
-   *   registry.register(token);
-   * }
-   * 
-   * // Skip validation if token is already validated
-   * registry.register(token, { skipValidation: true });
-   * ```
-   */
-  register(token: TToken, options?: RegistrationOptions): void;
-
-  /**
-   * Query all tokens in the registry
-   * 
-   * Returns an array of all registered tokens. The order of tokens in the
-   * returned array is implementation-specific.
-   * 
-   * @returns Array of all registered tokens
-   * 
-   * @example
-   * ```typescript
-   * const allTokens = registry.query();
-   * console.log(`Registry contains ${allTokens.length} tokens`);
-   * 
-   * // Process all tokens
-   * allTokens.forEach(token => {
-   *   console.log(`Token: ${token.name}`);
-   * });
-   * ```
-   */
-  query(): TToken[];
-
-  /**
-   * Get a specific token by name
-   * 
-   * Retrieves a token from the registry by its name. Returns undefined if
-   * the token is not found.
-   * 
-   * @param name - Token name to retrieve
-   * @returns Token if found, undefined otherwise
-   * 
-   * @example
-   * ```typescript
-   * const token = registry.get('space100');
-   * if (token) {
-   *   console.log(`Found token: ${token.name}`);
-   * } else {
-   *   console.log('Token not found');
-   * }
-   * ```
-   */
-  get(name: string): TToken | undefined;
-
-  /**
-   * Check if a token exists in the registry
-   * 
-   * Checks whether a token with the given name is registered without
-   * retrieving the token itself. This is useful for existence checks
-   * before attempting to retrieve or register tokens.
-   * 
-   * @param name - Token name to check
-   * @returns True if token exists, false otherwise
-   * 
-   * @example
-   * ```typescript
-   * if (registry.has('space100')) {
-   *   console.log('Token already registered');
-   * } else {
-   *   registry.register(newToken);
-   * }
-   * ```
-   */
-  has(name: string): boolean;
-}
-
-/**
- * Registration options for token registration
- * 
- * These options control the registration behavior and provide flexibility
- * for different registration scenarios.
- */
-export interface RegistrationOptions {
-  /**
-   * Skip validation during registration
-   * 
-   * When true, the registry assumes the token is already validated and
-   * skips any validation steps. This is useful when:
-   * - Token has been validated by the caller
-   * - Re-registering tokens during system initialization
-   * - Batch operations where validation is performed separately
-   * 
-   * Default: false (validation is performed)
-   * 
-   * @example
-   * ```typescript
-   * // Token already validated by caller
-   * const validationResult = validator.validate(token);
-   * if (validationResult.valid) {
-   *   registry.register(token, { skipValidation: true });
-   * }
-   * ```
-   */
-  skipValidation?: boolean;
-}