@3fn/core 14.1.0 → 15.0.0

package/src/color/OklchValidator.ts

@@ -1,186 +0,0 @@
-/**
- * OklchValidator — Constraint validation for OKLCH color families.
- *
- * Enforces:
- * - Lightness monotonicity (100→500 must decrease)
- * - Minimum step distance (≥0.08 between adjacent steps)
- * - sRGB gamut compliance per token
- * - P3 gamut check (warning, not error)
- * - Chroma monotonicity for steps 300→500 (equal or decreasing)
- * - Hue consistency within a family
- * - Neutral chroma ceiling (C ≤ 0.035)
- * - Neutral partition buffer gaps
- *
- * @see Spec 112 R1 AC6, R2 AC4, R8 AC2-3
- */
-
-import { isInSrgbGamut, type Oklch } from './OklchConverter';
-
-export interface ValidationResult {
-  valid: boolean;
-  errors: string[];
-  warnings: string[];
-}
-
-export interface ColorFamily {
-  name: string;
-  hue: number;
-  lightness: number[];  // steps 100-500 (index 0=100, 4=500)
-  chroma: number[];     // steps 100-500
-}
-
-const MIN_STEP_DISTANCE = 0.08;
-const NEUTRAL_CHROMA_CEILING = 0.035;
-
-export class OklchValidator {
-  /** Validate a complete color family against all constraints. */
-  validateFamily(family: ColorFamily): ValidationResult {
-    const errors: string[] = [];
-    const warnings: string[] = [];
-
-    const lResult = this.validateLightnessScale(family.lightness, family.name);
-    errors.push(...lResult.errors);
-    warnings.push(...lResult.warnings);
-
-    const cResult = this.validateChromaScale(family.chroma, family.name);
-    errors.push(...cResult.errors);
-    warnings.push(...cResult.warnings);
-
-    // Gamut check for each composed token
-    for (let i = 0; i < family.lightness.length; i++) {
-      const step = (i + 1) * 100;
-      const l = family.lightness[i];
-      const c = family.chroma[i];
-      const gResult = this.validateGamut(l, c, family.hue, `${family.name}${step}`);
-      errors.push(...gResult.errors);
-      warnings.push(...gResult.warnings);
-    }
-
-    return { valid: errors.length === 0, errors, warnings };
-  }
-
-  /** Validate lightness scale: must be monotonically decreasing with min step ≥0.08. */
-  validateLightnessScale(steps: number[], familyName = ''): ValidationResult {
-    const errors: string[] = [];
-    const warnings: string[] = [];
-    const prefix = familyName ? `${familyName}: ` : '';
-
-    for (let i = 1; i < steps.length; i++) {
-      if (steps[i] >= steps[i - 1]) {
-        errors.push(`${prefix}Lightness not monotonically decreasing: step ${(i) * 100}(${steps[i - 1]}) → step ${(i + 1) * 100}(${steps[i]})`);
-      }
-      const distance = steps[i - 1] - steps[i];
-      if (distance > 0 && distance < MIN_STEP_DISTANCE - 1e-10) {
-        errors.push(`${prefix}Lightness step distance ${distance.toFixed(3)} < ${MIN_STEP_DISTANCE} between steps ${i * 100} and ${(i + 1) * 100}`);
-      }
-    }
-
-    return { valid: errors.length === 0, errors, warnings };
-  }
-
-  /** Validate chroma scale: steps 300→500 must be equal or decreasing (darker = less chroma). */
-  validateChromaScale(steps: number[], familyName = ''): ValidationResult {
-    const errors: string[] = [];
-    const warnings: string[] = [];
-    const prefix = familyName ? `${familyName}: ` : '';
-
-    // Steps 300-500 are indices 2-4
-    for (let i = 3; i < steps.length && i <= 4; i++) {
-      if (steps[i] > steps[i - 1]) {
-        errors.push(`${prefix}Chroma not monotonically decreasing for steps ${(i) * 100}→${(i + 1) * 100}: ${steps[i - 1]} → ${steps[i]}`);
-      }
-    }
-
-    return { valid: errors.length === 0, errors, warnings };
-  }
-
-  /** Check sRGB gamut compliance. P3-only values get a warning. */
-  validateGamut(l: number, c: number, h: number, tokenName = ''): ValidationResult {
-    const errors: string[] = [];
-    const warnings: string[] = [];
-    const prefix = tokenName ? `${tokenName}: ` : '';
-
-    if (!isInSrgbGamut(l, c, h)) {
-      if (this.isInP3Gamut(l, c, h)) {
-        warnings.push(`${prefix}oklch(${l}, ${c}, ${h}) exceeds sRGB gamut (P3 only)`);
-      } else {
-        errors.push(`${prefix}oklch(${l}, ${c}, ${h}) exceeds both sRGB and P3 gamut`);
-      }
-    }
-
-    return { valid: errors.length === 0, errors, warnings };
-  }
-
-  /** Validate hue consistency: all tokens in a family should reference the same hue. */
-  validateHueConsistency(hues: number[], familyName = ''): ValidationResult {
-    const errors: string[] = [];
-    const warnings: string[] = [];
-    const prefix = familyName ? `${familyName}: ` : '';
-
-    if (hues.length === 0) return { valid: true, errors, warnings };
-    const reference = hues[0];
-    for (let i = 1; i < hues.length; i++) {
-      if (hues[i] !== reference) {
-        errors.push(`${prefix}Hue inconsistency: expected ${reference}, got ${hues[i]} at index ${i}`);
-      }
-    }
-
-    return { valid: errors.length === 0, errors, warnings };
-  }
-
-  /** Validate neutral chroma ceiling (C ≤ 0.035 for all steps). */
-  validateNeutralChroma(chroma: number[], familyName = ''): ValidationResult {
-    const errors: string[] = [];
-    const warnings: string[] = [];
-    const prefix = familyName ? `${familyName}: ` : '';
-
-    for (let i = 0; i < chroma.length; i++) {
-      if (chroma[i] > NEUTRAL_CHROMA_CEILING) {
-        errors.push(`${prefix}Neutral chroma ${chroma[i]} exceeds ceiling ${NEUTRAL_CHROMA_CEILING} at step ${(i + 1) * 100}`);
-      }
-    }
-
-    return { valid: errors.length === 0, errors, warnings };
-  }
-
-  /**
-   * Validate neutral partition buffer gaps.
-   * white500 → gray100: ≥0.08 gap
-   * gray500 → black100: ≥0.04 gap
-   */
-  validateNeutralPartition(
-    whiteLightness: number[],
-    grayLightness: number[],
-    blackLightness: number[]
-  ): ValidationResult {
-    const errors: string[] = [];
-    const warnings: string[] = [];
-    const EPSILON = 1e-10;
-
-    const white500 = whiteLightness[whiteLightness.length - 1];
-    const gray100 = grayLightness[0];
-    const whiteGrayGap = white500 - gray100;
-
-    if (whiteGrayGap < 0.08 - EPSILON) {
-      errors.push(`White→Gray buffer gap ${whiteGrayGap.toFixed(3)} < 0.08 (white500=${white500}, gray100=${gray100})`);
-    }
-
-    const gray500 = grayLightness[grayLightness.length - 1];
-    const black100 = blackLightness[0];
-    const grayBlackGap = gray500 - black100;
-
-    if (grayBlackGap < 0.04 - EPSILON) {
-      errors.push(`Gray→Black buffer gap ${grayBlackGap.toFixed(3)} < 0.04 (gray500=${gray500}, black100=${black100})`);
-    }
-
-    return { valid: errors.length === 0, errors, warnings };
-  }
-
-  /** Approximate P3 gamut check (P3 ≈ 25% larger chroma than sRGB). */
-  private isInP3Gamut(l: number, c: number, h: number): boolean {
-    // Rough heuristic: P3 gamut allows ~25% more chroma than sRGB at most L/H
-    // A proper check would use the P3 color space matrices, but this catches
-    // "way out of gamut" vs "just beyond sRGB but in P3"
-    return isInSrgbGamut(l, c * 0.75, h);
-  }
-}

package/src/color/__tests__/OklchConverter.test.ts

@@ -1,232 +0,0 @@
-/**
- * @category evergreen
- * @purpose Verify OklchConverter: conversion accuracy, WCAG, ΔE₀₀, gamut mapping (Spec 112 R5, R8)
- */
-
-import {
-  toSrgbHex,
-  fromSrgbHex,
-  toRelativeLuminance,
-  contrastRatio,
-  deltaE00,
-  clampToGamut,
-  isInSrgbGamut,
-  Oklch,
-} from '../OklchConverter';
-
-describe('OklchConverter', () => {
-  describe('toSrgbHex', () => {
-    it('converts black correctly', () => {
-      expect(toSrgbHex(0, 0, 0)).toBe('#000000');
-    });
-
-    it('converts white correctly', () => {
-      expect(toSrgbHex(1, 0, 0)).toBe('#ffffff');
-    });
-
-    it('converts a known red-ish color', () => {
-      // oklch(0.63 0.26 29) ≈ #ff0000-ish (saturated red-orange)
-      const hex = toSrgbHex(0.63, 0.26, 29);
-      // Should be a red/orange hex — verify it's in the right ballpark
-      const r = parseInt(hex.slice(1, 3), 16);
-      expect(r).toBeGreaterThan(200);
-    });
-
-    it('converts a known blue', () => {
-      // oklch(0.45 0.20 265) ≈ a medium blue
-      const hex = toSrgbHex(0.45, 0.20, 265);
-      const b = parseInt(hex.slice(5, 7), 16);
-      expect(b).toBeGreaterThan(100);
-    });
-
-    it('converts mid-gray (achromatic)', () => {
-      const hex = toSrgbHex(0.5, 0, 0);
-      const r = parseInt(hex.slice(1, 3), 16);
-      const g = parseInt(hex.slice(3, 5), 16);
-      const b = parseInt(hex.slice(5, 7), 16);
-      // Gray: R ≈ G ≈ B, around 50% perceived = ~109 sRGB
-      expect(Math.abs(r - g)).toBeLessThan(2);
-      expect(Math.abs(g - b)).toBeLessThan(2);
-    });
-
-    it('clamps out-of-gamut values to valid hex', () => {
-      // Very high chroma — likely out of gamut
-      const hex = toSrgbHex(0.7, 0.4, 150);
-      expect(hex).toMatch(/^#[0-9a-f]{6}$/);
-      // All channels should be 0-255 (clamped)
-      const r = parseInt(hex.slice(1, 3), 16);
-      expect(r).toBeGreaterThanOrEqual(0);
-      expect(r).toBeLessThanOrEqual(255);
-    });
-  });
-
-  describe('fromSrgbHex', () => {
-    it('round-trips for in-gamut colors', () => {
-      const testColors: Oklch[] = [
-        { l: 0.5, c: 0.1, h: 30 },
-        { l: 0.7, c: 0.15, h: 200 },
-        { l: 0.3, c: 0.08, h: 310 },
-      ];
-      for (const color of testColors) {
-        const hex = toSrgbHex(color.l, color.c, color.h);
-        const result = fromSrgbHex(hex);
-        // 8-bit quantization introduces errors up to ~0.03 in chroma
-        expect(Math.abs(result.l - color.l)).toBeLessThan(0.03);
-        expect(Math.abs(result.c - color.c)).toBeLessThan(0.04);
-      }
-    });
-
-    it('parses pure red', () => {
-      const result = fromSrgbHex('#ff0000');
-      expect(result.l).toBeGreaterThan(0.5);
-      expect(result.c).toBeGreaterThan(0.2);
-      expect(result.h).toBeLessThan(40); // Red hue
-    });
-
-    it('parses achromatic correctly', () => {
-      const gray = fromSrgbHex('#808080');
-      expect(gray.c).toBeLessThan(0.005);
-    });
-  });
-
-  describe('toRelativeLuminance', () => {
-    it('returns 0 for black', () => {
-      expect(toRelativeLuminance(0, 0, 0)).toBeCloseTo(0, 3);
-    });
-
-    it('returns 1 for white', () => {
-      expect(toRelativeLuminance(1, 0, 0)).toBeCloseTo(1, 3);
-    });
-
-    it('returns ~0.2126 for pure red', () => {
-      // Pure sRGB red (1,0,0) → luminance = 0.2126
-      const redOklch = fromSrgbHex('#ff0000');
-      const lum = toRelativeLuminance(redOklch.l, redOklch.c, redOklch.h);
-      expect(lum).toBeCloseTo(0.2126, 2);
-    });
-
-    it('mid-gray has luminance ~0.18-0.22', () => {
-      const lum = toRelativeLuminance(0.5, 0, 0);
-      expect(lum).toBeGreaterThan(0.1);
-      expect(lum).toBeLessThan(0.3);
-    });
-  });
-
-  describe('contrastRatio', () => {
-    it('black vs white = 21:1', () => {
-      const ratio = contrastRatio({ l: 0, c: 0, h: 0 }, { l: 1, c: 0, h: 0 });
-      expect(ratio).toBeCloseTo(21, 0);
-    });
-
-    it('same color = 1:1', () => {
-      const color: Oklch = { l: 0.5, c: 0.1, h: 200 };
-      expect(contrastRatio(color, color)).toBeCloseTo(1, 1);
-    });
-
-    it('dark text on white background passes WCAG AA', () => {
-      const darkText: Oklch = { l: 0.3, c: 0, h: 0 };
-      const whiteBg: Oklch = { l: 1, c: 0, h: 0 };
-      expect(contrastRatio(darkText, whiteBg)).toBeGreaterThan(4.5);
-    });
-
-    it('is symmetric', () => {
-      const a: Oklch = { l: 0.7, c: 0.15, h: 100 };
-      const b: Oklch = { l: 0.3, c: 0.1, h: 250 };
-      expect(contrastRatio(a, b)).toBeCloseTo(contrastRatio(b, a), 5);
-    });
-  });
-
-  describe('deltaE00', () => {
-    it('identical colors have ΔE₀₀ = 0', () => {
-      const color: Oklch = { l: 0.5, c: 0.15, h: 200 };
-      expect(deltaE00(color, color)).toBeCloseTo(0, 3);
-    });
-
-    it('very similar colors have small ΔE₀₀', () => {
-      const a: Oklch = { l: 0.50, c: 0.15, h: 200 };
-      const b: Oklch = { l: 0.51, c: 0.15, h: 200 };
-      expect(deltaE00(a, b)).toBeLessThan(2);
-    });
-
-    it('very different colors have large ΔE₀₀', () => {
-      const a: Oklch = { l: 0.9, c: 0.05, h: 100 };
-      const b: Oklch = { l: 0.2, c: 0.20, h: 300 };
-      expect(deltaE00(a, b)).toBeGreaterThan(30);
-    });
-
-    it('black vs white has large ΔE₀₀', () => {
-      const black: Oklch = { l: 0, c: 0, h: 0 };
-      const white: Oklch = { l: 1, c: 0, h: 0 };
-      expect(deltaE00(black, white)).toBeGreaterThan(50);
-    });
-  });
-
-  describe('isInSrgbGamut', () => {
-    it('black is in gamut', () => {
-      expect(isInSrgbGamut(0, 0, 0)).toBe(true);
-    });
-
-    it('white is in gamut', () => {
-      expect(isInSrgbGamut(1, 0, 0)).toBe(true);
-    });
-
-    it('moderate chroma is in gamut', () => {
-      expect(isInSrgbGamut(0.6, 0.12, 150)).toBe(true);
-    });
-
-    it('extreme chroma at mid-lightness is out of gamut', () => {
-      expect(isInSrgbGamut(0.5, 0.4, 150)).toBe(false);
-    });
-
-    it('achromatic colors are always in gamut', () => {
-      for (let l = 0; l <= 1; l += 0.1) {
-        expect(isInSrgbGamut(l, 0, 0)).toBe(true);
-      }
-    });
-  });
-
-  describe('clampToGamut', () => {
-    it('returns input unchanged when already in gamut', () => {
-      const result = clampToGamut(0.5, 0.05, 200);
-      expect(result.l).toBeCloseTo(0.5, 3);
-      expect(result.c).toBeCloseTo(0.05, 3);
-      expect(result.h).toBeCloseTo(200, 0);
-    });
-
-    it('reduces chroma for out-of-gamut colors', () => {
-      const result = clampToGamut(0.5, 0.4, 150);
-      expect(result.c).toBeLessThan(0.4);
-      expect(isInSrgbGamut(result.l, result.c, result.h)).toBe(true);
-    });
-
-    it('preserves hue approximately', () => {
-      const result = clampToGamut(0.7, 0.35, 120);
-      // Hue should be close to original (CSS L4 may shift slightly due to clipping)
-      expect(Math.abs(result.h - 120)).toBeLessThan(10);
-    });
-
-    it('handles L=1 (white)', () => {
-      const result = clampToGamut(1, 0.1, 200);
-      expect(result.l).toBe(1);
-      expect(result.c).toBe(0);
-    });
-
-    it('handles L=0 (black)', () => {
-      const result = clampToGamut(0, 0.1, 200);
-      expect(result.l).toBe(0);
-      expect(result.c).toBe(0);
-    });
-
-    it('clamped color is in sRGB gamut', () => {
-      const outOfGamut: Oklch = { l: 0.6, c: 0.35, h: 150 };
-      const clamped = clampToGamut(outOfGamut.l, outOfGamut.c, outOfGamut.h);
-      expect(isInSrgbGamut(clamped.l, clamped.c, clamped.h)).toBe(true);
-    });
-
-    it('produces valid hex output for clamped colors', () => {
-      const clamped = clampToGamut(0.6, 0.35, 150);
-      const hex = toSrgbHex(clamped.l, clamped.c, clamped.h);
-      expect(hex).toMatch(/^#[0-9a-f]{6}$/);
-    });
-  });
-});

package/src/color/__tests__/OklchRegression.test.ts

@@ -1,101 +0,0 @@
-/**
- * @category evergreen
- * @purpose Verify OKLCH migration regression — ΔE₀₀ < 1 for non-intentionally-changed colors (Spec 112 R11 AC4)
- */
-
-import { deltaE00, fromSrgbHex, toSrgbHex, type Oklch } from '../../color/OklchConverter';
-import { composedColorMap } from '../../tokens/color';
-
-/**
- * Pre-migration RGB hex values (from original ColorTokens.ts light.base).
- * These are the reference for regression validation.
- */
-const PRE_MIGRATION_RGB: Record<string, string> = {
-  // Pink
-  pink100: '#ffdae8', pink200: '#ff82b4', pink300: '#ff2a6d', pink400: '#cc2257', pink500: '#801537',
-  // Orange
-  orange100: '#ffe5dc', orange200: '#ffb8a0', orange300: '#ff6b35', orange400: '#cc5529', orange500: '#8f3c1d',
-  // Yellow
-  yellow100: '#fefbcc', yellow200: '#fcf680', yellow300: '#f9f002', yellow400: '#c7c002', yellow500: '#8f8b01',
-  // Purple
-  purple100: '#f3e0ff', purple200: '#d98aff', purple300: '#b026ff', purple400: '#8d1ecc', purple500: '#63158f',
-  // Cyan
-  cyan100: '#ccfbff', cyan200: '#80f6ff', cyan300: '#00f0ff', cyan400: '#00c0cc', cyan500: '#00888f',
-  // Teal (intentionally changed — chroma boost)
-  teal100: '#d9e8ea', teal200: '#4d9ba5', teal300: '#1a535c', teal400: '#15424a', teal500: '#0f2e33',
-  // Green (intentionally changed — lightness redistribution)
-  green100: '#e6fff5', green200: '#80ffbb', green300: '#33ff99', green400: '#00ff88', green500: '#00cc6e',
-  // Neutrals (intentionally changed — partition redesign)
-  white100: '#ffffff', white200: '#f5f5fa', white300: '#e8e8f0', white400: '#c5c5d5', white500: '#9999ab',
-  gray100: '#b2bcc4', gray200: '#5e707c', gray300: '#26323a', gray400: '#182228', gray500: '#10161a',
-  black100: '#3a3a45', black200: '#22222a', black300: '#0a0a0f', black400: '#06060a', black500: '#000000',
-};
-
-/** Colors intentionally changed by the migration (lightness redistribution, chroma boost, neutral redesign). */
-const INTENTIONALLY_CHANGED = new Set([
-  // Pink 100-200: hue normalization (original H≈353-356, normalized to family hue H=10)
-  'pink100', 'pink200',
-  // Teal: chroma boost
-  'teal100', 'teal200', 'teal300', 'teal400', 'teal500',
-  // Green: lightness redistributed from compressed 0.88/0.88 to even steps
-  'green200', 'green300', 'green400', 'green500',
-  // Yellow: lightness redistributed from compressed 0.95/0.93 to even steps
-  'yellow200', 'yellow300', 'yellow400', 'yellow500',
-  // Cyan: lightness redistributed
-  'cyan200', 'cyan300', 'cyan400', 'cyan500',
-  // Neutrals: entire partition redesigned (new L/C/H values)
-  'white100', 'white200', 'white300', 'white400', 'white500',
-  'gray100', 'gray200', 'gray300', 'gray400', 'gray500',
-  'black100', 'black200', 'black300', 'black400', 'black500',
-]);
-
-describe('OKLCH Migration Regression (Spec 112 R11 AC4)', () => {
-  describe('non-intentionally-changed colors: ΔE₀₀ < 3', () => {
-    const nonChanged = Object.keys(PRE_MIGRATION_RGB).filter(k => !INTENTIONALLY_CHANGED.has(k));
-
-    for (const name of nonChanged) {
-      it(`${name}: ΔE₀₀ < 3 vs original RGB`, () => {
-        const composed = composedColorMap.get(name);
-        expect(composed).toBeDefined();
-
-        const originalOklch = fromSrgbHex(PRE_MIGRATION_RGB[name]);
-        const newOklch = composed!.resolved;
-        const dE = deltaE00(originalOklch, newOklch);
-
-        // ΔE₀₀ < 3 for non-intentionally-changed (ideal < 1, but lightness rounding introduces drift)
-        expect(dE).toBeLessThan(3);
-      });
-    }
-  });
-
-  describe('intentionally changed colors: document ΔE₀₀', () => {
-    const changed = Object.keys(PRE_MIGRATION_RGB).filter(k => INTENTIONALLY_CHANGED.has(k));
-
-    for (const name of changed) {
-      it(`${name}: documents intentional change`, () => {
-        const composed = composedColorMap.get(name);
-        expect(composed).toBeDefined();
-
-        const originalOklch = fromSrgbHex(PRE_MIGRATION_RGB[name]);
-        const newOklch = composed!.resolved;
-        const dE = deltaE00(originalOklch, newOklch);
-
-        // Intentional changes are expected to be larger — just verify they're valid colors
-        expect(newOklch.l).toBeGreaterThanOrEqual(0);
-        expect(newOklch.l).toBeLessThanOrEqual(1);
-        // Log for documentation (captured in test output)
-        // eslint-disable-next-line no-console
-        if (dE > 5) {
-          // Large changes are expected for neutral redesign and lightness redistribution
-        }
-      });
-    }
-  });
-
-  it('all 50 composed colors have a pre-migration reference', () => {
-    const composed = Array.from(composedColorMap.keys());
-    const missing = composed.filter(name => !PRE_MIGRATION_RGB[name]);
-    // All composed colors should have a reference (green100 and yellow100 are kept similar)
-    expect(missing).toEqual([]);
-  });
-});