@3fn/core 14.1.0 → 15.0.0

package/src/blend/ThemeAwareBlendUtilities.web.ts

@@ -1,323 +0,0 @@
-/**
- * Theme-Aware Blend Utilities for Web (Vanilla TypeScript)
- * 
- * Provides factory functions that wrap blend utilities for use in Web Components.
- * Components read theme colors from CSS custom properties on document.documentElement
- * and use these utilities to calculate state colors (hover, pressed, disabled, etc.).
- * 
- * Architecture: DesignerPunk uses vanilla Web Components (extending HTMLElement, Shadow DOM),
- * NOT React. Theme colors are accessed via getComputedStyle(document.documentElement).
- * 
- * @module blend/ThemeAwareBlendUtilities.web
- * @see Requirements: 11.4 - Theme-aware wrapper functions
- */
-
-import {
-  hexToRgb,
-  rgbToHex,
-  calculateDarkerBlend,
-  calculateLighterBlend,
-  calculateSaturateBlend,
-  calculateDesaturateBlend,
-  RGB
-} from './ColorSpaceUtils';
-
-/**
- * Theme mode type for light/dark theme support
- */
-export type ThemeMode = 'light' | 'dark';
-
-/**
- * Theme context interface for blend utilities
- */
-export interface BlendThemeContext {
-  /** Current theme mode (light or dark) */
-  mode: ThemeMode;
-  /** Primary color for the current theme */
-  primaryColor: string;
-  /** On-primary color (text/icon color on primary background) */
-  onPrimaryColor: string;
-  /** Surface color for the current theme */
-  surfaceColor: string;
-  /** On-surface color (text/icon color on surface background) */
-  onSurfaceColor: string;
-}
-
-/**
- * Blend token values from semantic blend tokens
- * These match the CSS custom properties and design token definitions
- */
-export const BlendTokenValues = {
-  /** Hover state darkening - blend200 (8%) */
-  hoverDarker: 0.08,
-  /** Pressed state darkening - blend300 (12%) */
-  pressedDarker: 0.12,
-  /** Focus state saturation increase - blend200 (8%) */
-  focusSaturate: 0.08,
-  /**
-   * Disabled state desaturation - blend300 (12%)
-   * @deprecated 2026-07-15 — DesignerPunk does not support disabled states; if an action
-   * is unavailable, do not render the component. Scheduled for removal at the next major.
-   */
-  disabledDesaturate: 0.12,
-  /** Icon optical balance lightening - blend200 (8%) */
-  iconLighter: 0.08
-} as const;
-
-/**
- * Result type for blend utility functions
- */
-export interface BlendUtilitiesResult {
-  /**
-   * Calculate hover color by darkening the base color
-   * @param baseColor - Base color as hex string (e.g., "#A855F7")
-   * @returns Darkened hex color string for hover state
-   */
-  hoverColor: (baseColor: string) => string;
-  
-  /**
-   * Calculate pressed color by darkening the base color more than hover
-   * @param baseColor - Base color as hex string (e.g., "#A855F7")
-   * @returns Darkened hex color string for pressed state
-   */
-  pressedColor: (baseColor: string) => string;
-  
-  /**
-   * Calculate focus color by saturating the base color
-   * @param baseColor - Base color as hex string (e.g., "#A855F7")
-   * @returns Saturated hex color string for focus state
-   */
-  focusColor: (baseColor: string) => string;
-  
-  /**
-   * Calculate disabled color by desaturating the base color
-   * @param baseColor - Base color as hex string (e.g., "#A855F7")
-   * @returns Desaturated hex color string for disabled state
-   * @deprecated 2026-07-15 — DesignerPunk does not support disabled states; if an action
-   * is unavailable, do not render the component. For non-disabled desaturation, use the
-   * generic desaturate() utility. Scheduled for removal at the next major.
-   */
-  disabledColor: (baseColor: string) => string;
-  
-  /**
-   * Calculate icon color with optical balance adjustment
-   * @param baseColor - Base color as hex string (e.g., "#A855F7")
-   * @returns Lightened hex color string for icon optical balance
-   */
-  iconColor: (baseColor: string) => string;
-  
-  /**
-   * Generic darker blend function
-   * @param color - Base color as hex string
-   * @param amount - Blend amount (0.0-1.0)
-   * @returns Darkened hex color string
-   */
-  darkerBlend: (color: string, amount: number) => string;
-  
-  /**
-   * Generic lighter blend function
-   * @param color - Base color as hex string
-   * @param amount - Blend amount (0.0-1.0)
-   * @returns Lightened hex color string
-   */
-  lighterBlend: (color: string, amount: number) => string;
-  
-  /**
-   * Generic saturate blend function
-   * @param color - Base color as hex string
-   * @param amount - Blend amount (0.0-1.0)
-   * @returns Saturated hex color string
-   */
-  saturate: (color: string, amount: number) => string;
-  
-  /**
-   * Generic desaturate blend function
-   * @param color - Base color as hex string
-   * @param amount - Blend amount (0.0-1.0)
-   * @returns Desaturated hex color string
-   */
-  desaturate: (color: string, amount: number) => string;
-}
-
-/**
- * Apply darker blend to a hex color string.
- * Returns original color if parsing fails (invalid input handling).
- * 
- * @param color - Hex color string (e.g., "#A855F7")
- * @param amount - Blend amount as decimal (0.0-1.0)
- * @returns Darkened hex color string
- */
-function darkerBlend(color: string, amount: number): string {
-  try {
-    const rgb: RGB = hexToRgb(color);
-    const blended = calculateDarkerBlend(rgb, amount);
-    return rgbToHex(blended);
-  } catch {
-    // Return original color if parsing fails (Requirement 2.6)
-    return color;
-  }
-}
-
-/**
- * Apply lighter blend to a hex color string.
- * Returns original color if parsing fails (invalid input handling).
- * 
- * @param color - Hex color string (e.g., "#A855F7")
- * @param amount - Blend amount as decimal (0.0-1.0)
- * @returns Lightened hex color string
- */
-function lighterBlend(color: string, amount: number): string {
-  try {
-    const rgb: RGB = hexToRgb(color);
-    const blended = calculateLighterBlend(rgb, amount);
-    return rgbToHex(blended);
-  } catch {
-    // Return original color if parsing fails (Requirement 2.6)
-    return color;
-  }
-}
-
-/**
- * Apply saturate blend to a hex color string.
- * Returns original color if parsing fails (invalid input handling).
- * 
- * @param color - Hex color string (e.g., "#A855F7")
- * @param amount - Blend amount as decimal (0.0-1.0)
- * @returns Saturated hex color string
- */
-function saturate(color: string, amount: number): string {
-  try {
-    const rgb: RGB = hexToRgb(color);
-    const blended = calculateSaturateBlend(rgb, amount);
-    return rgbToHex(blended);
-  } catch {
-    // Return original color if parsing fails (Requirement 2.6)
-    return color;
-  }
-}
-
-/**
- * Apply desaturate blend to a hex color string.
- * Returns original color if parsing fails (invalid input handling).
- * 
- * @param color - Hex color string (e.g., "#A855F7")
- * @param amount - Blend amount as decimal (0.0-1.0)
- * @returns Desaturated hex color string
- */
-function desaturate(color: string, amount: number): string {
-  try {
-    const rgb: RGB = hexToRgb(color);
-    const blended = calculateDesaturateBlend(rgb, amount);
-    return rgbToHex(blended);
-  } catch {
-    // Return original color if parsing fails (Requirement 2.6)
-    return color;
-  }
-}
-
-/**
- * Create blend utilities with theme-aware convenience functions.
- * 
- * This is a factory function that creates blend utilities. It provides both 
- * generic blend functions and semantic convenience functions for common 
- * component states.
- * 
- * Usage in Web Components:
- * 1. Read theme colors from CSS custom properties via getComputedStyle()
- * 2. Pass colors to these utility functions to calculate state colors
- * 
- * @returns Object containing all blend utility functions
- * 
- * @example
- * ```typescript
- * // In a Web Component
- * class MyButton extends HTMLElement {
- *   private _calculateBlendColors(): void {
- *     const computedStyle = getComputedStyle(document.documentElement);
- *     const primaryColor = computedStyle.getPropertyValue('--color-primary').trim();
- *     
- *     const blendUtils = createBlendUtilities();
- *     this._hoverColor = blendUtils.hoverColor(primaryColor);
- *     this._pressedColor = blendUtils.pressedColor(primaryColor);
- *   }
- * }
- * ```
- */
-export function createBlendUtilities(): BlendUtilitiesResult {
-  return {
-    // Semantic convenience functions using blend token values
-    hoverColor: (baseColor: string) => darkerBlend(baseColor, BlendTokenValues.hoverDarker),
-    pressedColor: (baseColor: string) => darkerBlend(baseColor, BlendTokenValues.pressedDarker),
-    focusColor: (baseColor: string) => saturate(baseColor, BlendTokenValues.focusSaturate),
-    // deprecated 2026-07-15 (no-disabled-states philosophy) — removal at next major
-    disabledColor: (baseColor: string) => desaturate(baseColor, BlendTokenValues.disabledDesaturate),
-    iconColor: (baseColor: string) => lighterBlend(baseColor, BlendTokenValues.iconLighter),
-    
-    // Generic blend functions for custom usage
-    darkerBlend,
-    lighterBlend,
-    saturate,
-    desaturate
-  };
-}
-
-/**
- * Get blend utilities for use in Web Components and vanilla TypeScript.
- * 
- * This is the primary export for web platform usage. Web Components should:
- * 1. Read theme colors from CSS custom properties
- * 2. Use these utilities to calculate state colors
- * 3. Apply calculated colors to component styling
- * 
- * @returns Object containing all blend utility functions
- * 
- * @example
- * ```typescript
- * // In a Web Component
- * class ButtonCTA extends HTMLElement {
- *   connectedCallback() {
- *     const computedStyle = getComputedStyle(document.documentElement);
- *     const primaryColor = computedStyle.getPropertyValue('--color-primary').trim();
- *     
- *     const blendUtils = getBlendUtilities();
- *     this._hoverColor = blendUtils.hoverColor(primaryColor);
- *     this._pressedColor = blendUtils.pressedColor(primaryColor);
- *   }
- * }
- * ```
- * 
- * @example
- * ```typescript
- * // For SSR, testing, or build-time calculations
- * import { getBlendUtilities } from '@3fn/core/blend';
- * 
- * const blendUtils = getBlendUtilities();
- * const hoverColor = blendUtils.hoverColor('#A855F7');
- * ```
- */
-export function getBlendUtilities(): BlendUtilitiesResult {
-  return createBlendUtilities();
-}
-
-/**
- * Alias for getBlendUtilities() - kept for backward compatibility.
- * 
- * @deprecated Use getBlendUtilities() instead. This alias will be removed in a future version.
- * @returns Object containing all blend utility functions
- */
-export function useBlendUtilities(): BlendUtilitiesResult {
-  // Alias for backward compatibility during migration
-  return createBlendUtilities();
-}
-
-// Re-export blend token values for direct access
-export { BlendTokenValues as blendTokens };
-
-// Default export for convenience
-export default {
-  getBlendUtilities,
-  createBlendUtilities,
-  BlendTokenValues,
-  // Deprecated alias - kept for backward compatibility
-  useBlendUtilities
-};

package/src/blend/__tests__/BlendCalculator.test.ts

@@ -1,393 +0,0 @@
-/**
- * @category evergreen
- * @purpose Verify BlendCalculator functionality works correctly
- */
-/**
- * BlendCalculator Integration Tests
- * 
- * Tests the BlendCalculator orchestrator with all blend directions
- * and verifies integration with color space utilities and blend tokens.
- * 
- * Note: Input colors are arbitrary — they test pure blend math, not token values.
- */
-
-import { BlendCalculator, calculateBlend } from '../BlendCalculator';
-import { blendTokens, BlendDirection } from '../../tokens/BlendTokens';
-import { hexToRgb } from '../ColorSpaceUtils';
-
-describe('BlendCalculator', () => {
-  let calculator: BlendCalculator;
-
-  beforeEach(() => {
-    calculator = new BlendCalculator();
-  });
-
-  describe('calculateBlend method', () => {
-    describe('darker blend direction', () => {
-      it('should darken purple500 with blend200', () => {
-        const result = calculator.calculateBlend(
-          '#A855F7',
-          blendTokens.blend200,
-          BlendDirection.DARKER
-        );
-
-        // Verify result is a valid hex color
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-
-        // Verify color is darker than original
-        const original = hexToRgb('#A855F7');
-        const darkened = hexToRgb(result);
-        expect(darkened.r).toBeLessThan(original.r);
-        expect(darkened.g).toBeLessThan(original.g);
-        expect(darkened.b).toBeLessThan(original.b);
-      });
-
-      it('should darken blue500 with blend300', () => {
-        const result = calculator.calculateBlend(
-          '#3B82F6',
-          blendTokens.blend300,
-          BlendDirection.DARKER
-        );
-
-        const original = hexToRgb('#3B82F6');
-        const darkened = hexToRgb(result);
-        expect(darkened.r).toBeLessThan(original.r);
-        expect(darkened.g).toBeLessThan(original.g);
-        expect(darkened.b).toBeLessThan(original.b);
-      });
-
-      it('should produce darker colors with increasing blend values', () => {
-        const base = '#A855F7';
-        const blend100Result = calculator.calculateBlend(base, blendTokens.blend100, BlendDirection.DARKER);
-        const blend200Result = calculator.calculateBlend(base, blendTokens.blend200, BlendDirection.DARKER);
-        const blend300Result = calculator.calculateBlend(base, blendTokens.blend300, BlendDirection.DARKER);
-
-        const rgb100 = hexToRgb(blend100Result);
-        const rgb200 = hexToRgb(blend200Result);
-        const rgb300 = hexToRgb(blend300Result);
-
-        // Higher blend values should produce darker colors
-        expect(rgb200.r).toBeLessThan(rgb100.r);
-        expect(rgb300.r).toBeLessThan(rgb200.r);
-      });
-    });
-
-    describe('lighter blend direction', () => {
-      it('should lighten purple500 with blend200', () => {
-        const result = calculator.calculateBlend(
-          '#A855F7',
-          blendTokens.blend200,
-          BlendDirection.LIGHTER
-        );
-
-        // Verify result is a valid hex color
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-
-        // Verify color is lighter than original
-        const original = hexToRgb('#A855F7');
-        const lightened = hexToRgb(result);
-        expect(lightened.r).toBeGreaterThan(original.r);
-        expect(lightened.g).toBeGreaterThan(original.g);
-        expect(lightened.b).toBeGreaterThan(original.b);
-      });
-
-      it('should lighten blue500 with blend300', () => {
-        const result = calculator.calculateBlend(
-          '#3B82F6',
-          blendTokens.blend300,
-          BlendDirection.LIGHTER
-        );
-
-        const original = hexToRgb('#3B82F6');
-        const lightened = hexToRgb(result);
-        expect(lightened.r).toBeGreaterThan(original.r);
-        expect(lightened.g).toBeGreaterThan(original.g);
-        expect(lightened.b).toBeGreaterThan(original.b);
-      });
-
-      it('should produce lighter colors with increasing blend values', () => {
-        const base = '#A855F7';
-        const blend100Result = calculator.calculateBlend(base, blendTokens.blend100, BlendDirection.LIGHTER);
-        const blend200Result = calculator.calculateBlend(base, blendTokens.blend200, BlendDirection.LIGHTER);
-        const blend300Result = calculator.calculateBlend(base, blendTokens.blend300, BlendDirection.LIGHTER);
-
-        const rgb100 = hexToRgb(blend100Result);
-        const rgb200 = hexToRgb(blend200Result);
-        const rgb300 = hexToRgb(blend300Result);
-
-        // Higher blend values should produce lighter colors
-        expect(rgb200.r).toBeGreaterThan(rgb100.r);
-        expect(rgb300.r).toBeGreaterThan(rgb200.r);
-      });
-    });
-
-    describe('saturate blend direction', () => {
-      it('should saturate purple500 with blend200', () => {
-        const result = calculator.calculateBlend(
-          '#A855F7',
-          blendTokens.blend200,
-          BlendDirection.SATURATE
-        );
-
-        // Verify result is a valid hex color
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-        
-        // Result should be different from original (more saturated)
-        expect(result).not.toBe('#A855F7');
-      });
-
-      it('should saturate blue500 with blend300', () => {
-        const result = calculator.calculateBlend(
-          '#3B82F6',
-          blendTokens.blend300,
-          BlendDirection.SATURATE
-        );
-
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-        expect(result).not.toBe('#3B82F6');
-      });
-
-      it('should handle saturation at maximum (clamped to 1.0)', () => {
-        // Start with a highly saturated color
-        const result = calculator.calculateBlend(
-          '#FF0000',
-          blendTokens.blend500,
-          BlendDirection.SATURATE
-        );
-
-        // Should still return valid hex color
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-      });
-    });
-
-    describe('desaturate blend direction', () => {
-      it('should desaturate purple500 with blend200', () => {
-        const result = calculator.calculateBlend(
-          '#A855F7',
-          blendTokens.blend200,
-          BlendDirection.DESATURATE
-        );
-
-        // Verify result is a valid hex color
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-        
-        // Result should be different from original (less saturated)
-        expect(result).not.toBe('#A855F7');
-      });
-
-      it('should desaturate blue500 with blend300', () => {
-        const result = calculator.calculateBlend(
-          '#3B82F6',
-          blendTokens.blend300,
-          BlendDirection.DESATURATE
-        );
-
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-        expect(result).not.toBe('#3B82F6');
-      });
-
-      it('should handle desaturation at minimum (clamped to 0.0)', () => {
-        // Start with a gray color (low saturation)
-        const result = calculator.calculateBlend(
-          '#808080',
-          blendTokens.blend500,
-          BlendDirection.DESATURATE
-        );
-
-        // Should still return valid hex color
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-      });
-    });
-
-    describe('error handling', () => {
-      it('should throw error for invalid hex color', () => {
-        expect(() => {
-          calculator.calculateBlend(
-            'invalid',
-            blendTokens.blend200,
-            BlendDirection.DARKER
-          );
-        }).toThrow('Invalid hex color');
-      });
-
-      it('should throw error for unsupported blend direction', () => {
-        expect(() => {
-          calculator.calculateBlend(
-            '#A855F7',
-            blendTokens.blend200,
-            'invalid' as BlendDirection
-          );
-        }).toThrow('Unsupported blend direction');
-      });
-    });
-
-    describe('integration with all blend tokens', () => {
-      it('should work with blend100', () => {
-        const result = calculator.calculateBlend(
-          '#A855F7',
-          blendTokens.blend100,
-          BlendDirection.DARKER
-        );
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-      });
-
-      it('should work with blend200', () => {
-        const result = calculator.calculateBlend(
-          '#A855F7',
-          blendTokens.blend200,
-          BlendDirection.DARKER
-        );
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-      });
-
-      it('should work with blend300', () => {
-        const result = calculator.calculateBlend(
-          '#A855F7',
-          blendTokens.blend300,
-          BlendDirection.DARKER
-        );
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-      });
-
-      it('should work with blend400', () => {
-        const result = calculator.calculateBlend(
-          '#A855F7',
-          blendTokens.blend400,
-          BlendDirection.DARKER
-        );
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-      });
-
-      it('should work with blend500', () => {
-        const result = calculator.calculateBlend(
-          '#A855F7',
-          blendTokens.blend500,
-          BlendDirection.DARKER
-        );
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-      });
-    });
-
-    describe('hex format handling', () => {
-      it('should handle hex colors with # prefix', () => {
-        const result = calculator.calculateBlend(
-          '#A855F7',
-          blendTokens.blend200,
-          BlendDirection.DARKER
-        );
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-      });
-
-      it('should handle hex colors without # prefix', () => {
-        const result = calculator.calculateBlend(
-          'A855F7',
-          blendTokens.blend200,
-          BlendDirection.DARKER
-        );
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-      });
-
-      it('should handle 3-digit hex colors', () => {
-        const result = calculator.calculateBlend(
-          '#ABC',
-          blendTokens.blend200,
-          BlendDirection.DARKER
-        );
-        expect(result).toMatch(/^#[0-9A-F]{6}$/);
-      });
-    });
-  });
-
-  describe('calculateBlend convenience function', () => {
-    it('should work with darker direction', () => {
-      const result = calculateBlend(
-        '#A855F7',
-        blendTokens.blend200,
-        BlendDirection.DARKER
-      );
-      expect(result).toMatch(/^#[0-9A-F]{6}$/);
-    });
-
-    it('should work with lighter direction', () => {
-      const result = calculateBlend(
-        '#A855F7',
-        blendTokens.blend200,
-        BlendDirection.LIGHTER
-      );
-      expect(result).toMatch(/^#[0-9A-F]{6}$/);
-    });
-
-    it('should work with saturate direction', () => {
-      const result = calculateBlend(
-        '#A855F7',
-        blendTokens.blend200,
-        BlendDirection.SATURATE
-      );
-      expect(result).toMatch(/^#[0-9A-F]{6}$/);
-    });
-
-    it('should work with desaturate direction', () => {
-      const result = calculateBlend(
-        '#A855F7',
-        blendTokens.blend200,
-        BlendDirection.DESATURATE
-      );
-      expect(result).toMatch(/^#[0-9A-F]{6}$/);
-    });
-
-    it('should produce same results as BlendCalculator instance', () => {
-      const instanceResult = calculator.calculateBlend(
-        '#A855F7',
-        blendTokens.blend200,
-        BlendDirection.DARKER
-      );
-      const functionResult = calculateBlend(
-        '#A855F7',
-        blendTokens.blend200,
-        BlendDirection.DARKER
-      );
-      expect(functionResult).toBe(instanceResult);
-    });
-  });
-
-  describe('cross-direction integration', () => {
-    it('should produce different results for different directions', () => {
-      const base = '#A855F7';
-      const token = blendTokens.blend200;
-
-      const darker = calculator.calculateBlend(base, token, BlendDirection.DARKER);
-      const lighter = calculator.calculateBlend(base, token, BlendDirection.LIGHTER);
-      const saturated = calculator.calculateBlend(base, token, BlendDirection.SATURATE);
-      const desaturated = calculator.calculateBlend(base, token, BlendDirection.DESATURATE);
-
-      // All results should be different
-      expect(darker).not.toBe(lighter);
-      expect(darker).not.toBe(saturated);
-      expect(darker).not.toBe(desaturated);
-      expect(lighter).not.toBe(saturated);
-      expect(lighter).not.toBe(desaturated);
-      expect(saturated).not.toBe(desaturated);
-    });
-
-    it('should work with multiple colors and directions', () => {
-      const colors = ['#A855F7', '#3B82F6', '#10B981', '#EF4444'];
-      const directions = [
-        BlendDirection.DARKER,
-        BlendDirection.LIGHTER,
-        BlendDirection.SATURATE,
-        BlendDirection.DESATURATE
-      ];
-
-      colors.forEach(color => {
-        directions.forEach(direction => {
-          const result = calculator.calculateBlend(
-            color,
-            blendTokens.blend200,
-            direction
-          );
-          expect(result).toMatch(/^#[0-9A-F]{6}$/);
-        });
-      });
-    });
-  });
-});