@3fn/core 14.1.0 → 15.0.0

package/src/providers/AndroidUnitConverter.ts

@@ -1,177 +0,0 @@
-import { PrimitiveToken, PlatformValues } from '../types';
-import { BaseUnitProvider, UnitConversionConfig } from './UnitProvider';
-
-/**
- * Android density buckets and their scale factors
- */
-export enum AndroidDensity {
-  LDPI = 0.75,    // ~120dpi
-  MDPI = 1.0,     // ~160dpi (baseline)
-  HDPI = 1.5,     // ~240dpi
-  XHDPI = 2.0,    // ~320dpi
-  XXHDPI = 3.0,   // ~480dpi
-  XXXHDPI = 4.0   // ~640dpi
-}
-
-/**
- * Android-specific unit converter
- * Converts unitless token values to Android-appropriate units (dp, sp, unitless)
- */
-export class AndroidUnitConverter extends BaseUnitProvider {
-  readonly platform = 'android' as const;
-
-  constructor(config: UnitConversionConfig = {}) {
-    super({
-      densityFactor: AndroidDensity.MDPI, // Default to MDPI (1.0)
-      ...config
-    });
-  }
-
-  convertToken(token: PrimitiveToken): PlatformValues['android'] {
-    return this.convertValue(token.baseValue, token.category);
-  }
-
-  convertValue(baseValue: number | string, category: string): PlatformValues['android'] {
-    switch (category) {
-      case 'spacing':
-      case 'radius':
-      case 'tapArea':
-        // Convert to density-independent pixels (dp)
-        // dp values remain consistent across different screen densities
-        return { value: baseValue as number, unit: 'dp' };
-      
-      case 'fontSize':
-        // Convert to scale-independent pixels (sp) for text
-        // sp respects user's font size preferences
-        return { value: baseValue as number, unit: 'sp' };
-
-      case 'fontFamily':
-        // Font family remains as string for Android
-        return { value: baseValue as string, unit: 'fontFamily' };
-
-      case 'fontWeight':
-        // Font weight remains as numeric for Android
-        return { value: baseValue as number, unit: 'fontWeight' };
-
-      case 'letterSpacing':
-        // Letter spacing converted to em units for Android
-        return { value: baseValue as number, unit: 'em' };
-      
-      case 'lineHeight':
-        // Line height remains unitless for proper Android 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 dp for unknown categories
-        return { value: baseValue as number, unit: 'dp' };
-    }
-  }
-
-  getConversionFactor(category: string): number | { factor: number; unit: string } {
-    switch (category) {
-      case 'spacing':
-      case 'radius':
-      case 'tapArea':
-        return { factor: 1, unit: 'dp' };
-      
-      case 'fontSize':
-        return { factor: 1, unit: 'sp' };
-
-      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: 'dp' };
-    }
-  }
-
-  /**
-   * Get the current density factor
-   */
-  getDensityFactor(): number {
-    return this.config.densityFactor!;
-  }
-
-  /**
-   * Convert dp to pixels for a given density
-   */
-  dpToPixels(dpValue: number, density?: AndroidDensity): number {
-    const densityFactor = density || this.config.densityFactor!;
-    return dpValue * densityFactor;
-  }
-
-  /**
-   * Convert pixels to dp for a given density
-   */
-  pixelsToDp(pixelValue: number, density?: AndroidDensity): number {
-    const densityFactor = density || this.config.densityFactor!;
-    return pixelValue / densityFactor;
-  }
-
-  /**
-   * Convert sp to pixels for a given density
-   * Note: sp also considers user font scale preferences
-   */
-  spToPixels(spValue: number, density?: AndroidDensity, fontScale: number = 1.0): number {
-    const densityFactor = density || this.config.densityFactor!;
-    return spValue * densityFactor * fontScale;
-  }
-
-  /**
-   * Handle density bucket considerations
-   * Ensures values work well across different Android density buckets
-   */
-  handleDensityBuckets(baseValue: number, category: string): Record<string, number> {
-    const results: Record<string, number> = {};
-    
-    Object.entries(AndroidDensity).forEach(([key, densityFactor]) => {
-      if (typeof densityFactor === 'number') {
-        switch (category) {
-          case 'spacing':
-          case 'radius':
-          case 'tapArea':
-            // dp values remain consistent across densities
-            results[key] = baseValue;
-            break;
-          
-          case 'fontSize':
-            // sp values remain consistent across densities
-            results[key] = baseValue;
-            break;
-          
-          default:
-            results[key] = baseValue;
-            break;
-        }
-      }
-    });
-    
-    return results;
-  }
-
-  /**
-   * Validate that values work well across density buckets
-   */
-  validateAcrossDensities(baseValue: number, category: string): boolean {
-    const densityResults = this.handleDensityBuckets(baseValue, category);
-    
-    // Ensure all density results are positive and reasonable
-    return Object.values(densityResults).every(value => 
-      value > 0 && value < 1000 // Reasonable upper bound
-    );
-  }
-}

package/src/providers/FormatProvider.ts

@@ -1,187 +0,0 @@
-import { PrimitiveToken, SemanticToken } from '../types';
-import { TranslationOutput, TargetPlatform, OutputFormat } from '../types/TranslationOutput';
-
-/**
- * Base interface for format generation providers
- * Defines consistent contract for generating platform-specific token syntax
- */
-export interface FormatProvider {
-  /**
-   * Platform identifier for this format provider
-   */
-  readonly platform: TargetPlatform;
-
-  /**
-   * Output format(s) supported by this provider
-   */
-  readonly formats: OutputFormat[];
-
-  /**
-   * Generate platform-specific token constant declaration
-   * @param token - The primitive or semantic token to format
-   * @returns Platform-specific constant declaration string
-   */
-  formatToken(token: PrimitiveToken | SemanticToken): string;
-
-  /**
-   * Generate complete file content with all tokens
-   * @param tokens - Array of tokens to include in the file
-   * @param options - Optional formatting options
-   * @returns Complete file content string
-   */
-  generateFile(tokens: (PrimitiveToken | SemanticToken)[], options?: FormatOptions): string;
-
-  /**
-   * Generate file header/preamble with imports and metadata
-   * @param metadata - Optional metadata to include in header
-   * @returns File header string
-   */
-  generateHeader(metadata?: FileMetadata): string;
-
-  /**
-   * Generate file footer/closing content
-   * @returns File footer string
-   */
-  generateFooter(): string;
-
-  /**
-   * Validate that generated syntax is correct for the platform
-   * @param content - Generated file content to validate
-   * @returns Validation result with any errors
-   */
-  validateSyntax(content: string): { valid: boolean; errors?: string[] };
-
-  /**
-   * Get naming convention for token on this platform
-   * @param tokenName - Original token name
-   * @param category - Token category
-   * @returns Platform-appropriate token name
-   */
-  getTokenName(tokenName: string, category: string): string;
-}
-
-/**
- * Options for format generation
- */
-export interface FormatOptions {
-  /** Include comments in generated file */
-  includeComments?: boolean;
-  
-  /** Group tokens by category */
-  groupByCategory?: boolean;
-  
-  /** Sort tokens alphabetically */
-  sortAlphabetically?: boolean;
-  
-  /** Include mathematical relationships in comments */
-  includeMathematicalContext?: boolean;
-  
-  /** Custom formatting preferences */
-  customOptions?: Record<string, any>;
-}
-
-/**
- * Metadata for generated files
- */
-export interface FileMetadata {
-  /** Generation timestamp */
-  generatedAt?: Date;
-  
-  /** System version */
-  version?: string;
-  
-  /** Additional metadata */
-  custom?: Record<string, any>;
-}
-
-/**
- * Abstract base class providing common format generation functionality
- */
-export abstract class BaseFormatProvider implements FormatProvider {
-  abstract readonly platform: TargetPlatform;
-  abstract readonly formats: OutputFormat[];
-
-  abstract formatToken(token: PrimitiveToken | SemanticToken): string;
-  abstract generateHeader(metadata?: FileMetadata): string;
-  abstract generateFooter(): string;
-  abstract validateSyntax(content: string): { valid: boolean; errors?: string[] };
-  abstract getTokenName(tokenName: string, category: string): string;
-
-  generateFile(tokens: (PrimitiveToken | SemanticToken)[], options: FormatOptions = {}): string {
-    const {
-      includeComments = true,
-      groupByCategory = true,
-      sortAlphabetically = false,
-      includeMathematicalContext = false
-    } = options;
-
-    let processedTokens = [...tokens];
-
-    // Sort if requested
-    if (sortAlphabetically) {
-      processedTokens.sort((a, b) => a.name.localeCompare(b.name));
-    }
-
-    // Group by category if requested
-    const tokenGroups = groupByCategory
-      ? this.groupTokensByCategory(processedTokens)
-      : { all: processedTokens };
-
-    // Generate file content
-    const parts: string[] = [];
-    parts.push(this.generateHeader());
-
-    for (const [category, categoryTokens] of Object.entries(tokenGroups)) {
-      if (groupByCategory && category !== 'all') {
-        parts.push(this.generateCategoryComment(category));
-      }
-
-      for (const token of categoryTokens) {
-        if (includeComments && includeMathematicalContext && 'mathematicalRelationship' in token) {
-          parts.push(this.generateMathematicalComment(token as PrimitiveToken));
-        }
-        parts.push(this.formatToken(token));
-      }
-
-      if (groupByCategory && category !== 'all') {
-        parts.push(''); // Add spacing between categories
-      }
-    }
-
-    parts.push(this.generateFooter());
-
-    return parts.join('\n');
-  }
-
-  protected groupTokensByCategory(tokens: (PrimitiveToken | SemanticToken)[]): Record<string, (PrimitiveToken | SemanticToken)[]> {
-    const groups: Record<string, (PrimitiveToken | SemanticToken)[]> = {};
-
-    for (const token of tokens) {
-      const category = token.category;
-      if (!groups[category]) {
-        groups[category] = [];
-      }
-      groups[category].push(token);
-    }
-
-    return groups;
-  }
-
-  protected generateCategoryComment(category: string): string {
-    return `// ${category.toUpperCase()} TOKENS`;
-  }
-
-  protected generateMathematicalComment(token: PrimitiveToken): string {
-    return `// ${token.mathematicalRelationship}`;
-  }
-
-  protected formatValue(value: number | string | object, unit: string): string {
-    if (typeof value === 'object') {
-      return JSON.stringify(value);
-    }
-    if (typeof value === 'string') {
-      return `"${value}"`;
-    }
-    return unit === 'unitless' ? String(value) : `${value}${unit}`;
-  }
-}

package/src/providers/PathProvider.ts

@@ -1,197 +0,0 @@
-import { TargetPlatform, OutputFormat } from '../types/TranslationOutput';
-
-/**
- * Base interface for path organization providers
- * Defines consistent contract for organizing tokens into platform-specific file structures
- */
-export interface PathProvider {
-    /**
-     * Platform identifier for this path provider
-     */
-    readonly platform: TargetPlatform;
-
-    /**
-     * Get the base directory for token files on this platform
-     * @returns Base directory path
-     */
-    getBaseDirectory(): string;
-
-    /**
-     * Get the complete file path for a token file
-     * @param format - Output format for the file
-     * @param options - Optional path generation options
-     * @returns Complete file path
-     */
-    getFilePath(format: OutputFormat, options?: PathOptions): string;
-
-    /**
-     * Get the directory structure for organizing token files
-     * @returns Array of subdirectory paths
-     */
-    getDirectoryStructure(): string[];
-
-    /**
-     * Get the file naming pattern for this platform
-     * @param format - Output format
-     * @returns File name with extension
-     */
-    getFileName(format: OutputFormat): string;
-
-    /**
-     * Get build system integration configuration
-     * @returns Build system integration details
-     */
-    getBuildSystemIntegration(): BuildSystemConfig;
-
-    /**
-     * Validate that the file path follows platform conventions
-     * @param filePath - File path to validate
-     * @returns Validation result
-     */
-    validatePath(filePath: string): { valid: boolean; errors?: string[] };
-
-    /**
-     * Optimize file organization for platform-specific build systems
-     * @param files - Array of file paths to optimize
-     * @returns Optimized file organization
-     */
-    optimizeForBuildSystem(files: string[]): OptimizedFileStructure;
-}
-
-/**
- * Options for path generation
- */
-export interface PathOptions {
-    /** Include subdirectories in path */
-    includeSubdirectories?: boolean;
-
-    /** Custom base directory override */
-    customBaseDirectory?: string;
-
-    /** Group files by category */
-    groupByCategory?: boolean;
-
-    /** Additional path customization */
-    customOptions?: Record<string, any>;
-}
-
-/**
- * Build system integration configuration
- */
-export interface BuildSystemConfig {
-    /** Build system type (webpack, gradle, xcode, etc.) */
-    buildSystemType: string;
-
-    /** Import/require patterns for the platform */
-    importPatterns: string[];
-
-    /** File watching patterns */
-    watchPatterns?: string[];
-
-    /** Tree-shaking optimization hints */
-    treeShakingHints?: string[];
-
-    /** Additional build configuration */
-    additionalConfig?: Record<string, any>;
-}
-
-/**
- * Optimized file structure for build system integration
- */
-export interface OptimizedFileStructure {
-    /** Primary token file path */
-    primaryFile: string;
-
-    /** Additional supporting files */
-    supportingFiles?: string[];
-
-    /** Recommended import path */
-    importPath: string;
-
-    /** Build optimization recommendations */
-    optimizations: string[];
-}
-
-/**
- * Abstract base class providing common path organization functionality
- */
-export abstract class BasePathProvider implements PathProvider {
-    abstract readonly platform: TargetPlatform;
-
-    abstract getBaseDirectory(): string;
-    abstract getFileName(format: OutputFormat): string;
-    abstract getBuildSystemIntegration(): BuildSystemConfig;
-
-    getFilePath(format: OutputFormat, options: PathOptions = {}): string {
-        const {
-            includeSubdirectories = true,
-            customBaseDirectory,
-            groupByCategory = false
-        } = options;
-
-        const baseDir = customBaseDirectory || this.getBaseDirectory();
-        const fileName = this.getFileName(format);
-
-        if (!includeSubdirectories) {
-            return `${baseDir}/${fileName}`;
-        }
-
-        const subdirs = this.getDirectoryStructure();
-        const subdirPath = subdirs.length > 0 ? `/${subdirs.join('/')}` : '';
-
-        return `${baseDir}${subdirPath}/${fileName}`;
-    }
-
-    getDirectoryStructure(): string[] {
-        // Default implementation returns empty array (flat structure)
-        // Override in platform-specific implementations if needed
-        return [];
-    }
-
-    validatePath(filePath: string): { valid: boolean; errors?: string[] } {
-        const errors: string[] = [];
-
-        // Basic validation
-        if (!filePath || filePath.trim() === '') {
-            errors.push('File path cannot be empty');
-        }
-
-        if (filePath.includes('..')) {
-            errors.push('File path cannot contain parent directory references (..)');
-        }
-
-        if (filePath.startsWith('/')) {
-            errors.push('File path should be relative, not absolute');
-        }
-
-        return {
-            valid: errors.length === 0,
-            errors: errors.length > 0 ? errors : undefined
-        };
-    }
-
-    optimizeForBuildSystem(files: string[]): OptimizedFileStructure {
-        // Default implementation - override in platform-specific implementations
-        const primaryFile = files[0] || '';
-        const buildConfig = this.getBuildSystemIntegration();
-
-        return {
-            primaryFile,
-            supportingFiles: files.slice(1),
-            importPath: this.getImportPath(primaryFile),
-            optimizations: buildConfig.treeShakingHints || []
-        };
-    }
-
-    protected getImportPath(filePath: string): string {
-        // Remove file extension and convert to import path
-        return filePath.replace(/\.[^/.]+$/, '').replace(/\\/g, '/');
-    }
-
-    protected ensureExtension(fileName: string, extension: string): string {
-        if (!fileName.endsWith(extension)) {
-            return `${fileName}${extension}`;
-        }
-        return fileName;
-    }
-}

package/src/providers/UnitProvider.ts

@@ -1,106 +0,0 @@
-import { PrimitiveToken, PlatformValues } from '../types';
-
-/**
- * Base interface for unit conversion providers
- * Defines consistent contract for converting unitless token values to platform-specific units
- */
-export interface UnitProvider {
-  /**
-   * Platform identifier for this unit provider
-   */
-  readonly platform: 'web' | 'ios' | 'android';
-
-  /**
-   * Convert a primitive token's base value to platform-specific unit
-   * @param token - The primitive token to convert
-   * @returns Platform-specific value with unit
-   */
-  convertToken(token: PrimitiveToken): PlatformValues[keyof PlatformValues];
-
-  /**
-   * Convert a raw base value to platform-specific unit for a given token category
-   * @param baseValue - The unitless base value to convert (number or string for categorical tokens)
-   * @param category - The token category (spacing, fontSize, etc.)
-   * @returns Platform-specific value with unit
-   */
-  convertValue(baseValue: number | string, category: string): PlatformValues[keyof PlatformValues];
-
-  /**
-   * Get the conversion factor for a specific token category
-   * @param category - The token category
-   * @returns Conversion factor or configuration for the category
-   */
-  getConversionFactor(category: string): number | { factor: number; unit: string };
-
-  /**
-   * Validate that the converted value maintains mathematical relationships
-   * @param originalValue - Original unitless value (number or string for categorical tokens)
-   * @param convertedValue - Converted platform-specific value
-   * @param category - Token category
-   * @returns True if conversion maintains mathematical relationships
-   */
-  validateConversion(originalValue: number | string, convertedValue: PlatformValues[keyof PlatformValues], category: string): boolean;
-}
-
-/**
- * Configuration interface for unit conversion settings
- */
-export interface UnitConversionConfig {
-  baseFontSize?: number;
-  densityFactor?: number;
-  displayScale?: number;
-}
-
-/**
- * Abstract base class providing common unit conversion functionality
- */
-export abstract class BaseUnitProvider implements UnitProvider {
-  abstract readonly platform: 'web' | 'ios' | 'android';
-  protected config: UnitConversionConfig;
-
-  constructor(config: UnitConversionConfig = {}) {
-    this.config = {
-      baseFontSize: 16,
-      densityFactor: 1.0,
-      displayScale: 1.0,
-      ...config
-    };
-  }
-
-  abstract convertToken(token: PrimitiveToken): PlatformValues[keyof PlatformValues];
-  abstract convertValue(baseValue: number | string, category: string): PlatformValues[keyof PlatformValues];
-  abstract getConversionFactor(category: string): number | { factor: number; unit: string };
-
-  validateConversion(originalValue: number | string, convertedValue: PlatformValues[keyof PlatformValues], category: string): boolean {
-    // For string values (like fontFamily), just ensure they match
-    if (typeof originalValue === 'string') {
-      return convertedValue.value === originalValue;
-    }
-
-    // Basic validation - ensure converted numeric value is positive and maintains proportional relationships
-    if (typeof convertedValue.value === 'number' && convertedValue.value < 0) return false;
-
-    // For unitless values (like lineHeight), the value should remain the same
-    if (convertedValue.unit === 'unitless') {
-      return Math.abs((convertedValue.value as number) - originalValue) < 0.001;
-    }
-
-    // For pass-through values (fontFamily, fontWeight, letterSpacing), the value should remain the same
-    if (convertedValue.unit === 'fontFamily' || convertedValue.unit === 'fontWeight' || convertedValue.unit === 'em') {
-      if (typeof convertedValue.value === 'number' && typeof originalValue === 'number') {
-        return Math.abs(convertedValue.value - originalValue) < 0.001;
-      }
-      return convertedValue.value === originalValue;
-    }
-
-    // For other units, ensure the conversion factor is applied correctly (originalValue must be numeric here)
-    if (typeof originalValue !== 'number') return false;
-
-    const conversionFactor = this.getConversionFactor(category);
-    const expectedValue = typeof conversionFactor === 'number'
-      ? originalValue * conversionFactor
-      : originalValue * conversionFactor.factor;
-
-    return Math.abs((convertedValue.value as number) - expectedValue) < 0.001;
-  }
-}