@ankhorage/surface 0.2.4 → 1.0.0

package/src/theme/colorEngine.ts

@@ -1,314 +1,113 @@
-import { formatHex, modeOklch, oklch, useMode } from 'culori';
+import type {
+  ColorSwatch,
+  GeneratedThemeModeColors,
+  GeneratedThemeSwatches,
+  HexColor,
+  SemanticColorReferenceMap,
+  SemanticColorToken,
+} from '@ankhorage/color-theory';
+import {
+  generateColorSwatch,
+  generateThemeModeColors,
+  getReadableForeground,
+  parseHexColorOrThrow,
+} from '@ankhorage/color-theory';
+import type { ThemeConfig } from '@ankhorage/contracts';
 
 import type {
   ActionSemantics,
   BorderSemantics,
-  ColorHarmony,
-  ColorScale,
-  ColorTone,
   ContentSemantics,
   NeutralSemantics,
   RoleSemantics,
   SurfaceSemantics,
-  ThemeConfig,
   ThemeSemantics,
 } from './types';
 
-useMode(modeOklch);
-
-interface OklchColor {
-  mode: 'oklch';
-  l: number;
-  c: number;
-  h?: number;
-}
-
-export const SCALE_STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const;
-
-type RolePaletteKind =
-  | 'grayscale'
-  | 'neutral'
-  | 'pastel'
-  | 'earth'
-  | 'mineral'
-  | 'muted'
-  | 'jewel'
-  | 'fluorescent'
-  | 'obsidian'
-  | 'vaporwave'
-  | 'monochromeAccent';
-
-/**
- * Deterministic Lightness Curves (OKLCH L)
- */
-const LIGHTNESS_CURVES = {
-  light: [0.98, 0.95, 0.9, 0.82, 0.72, 0.62, 0.52, 0.42, 0.32, 0.22, 0.15],
-  dark: [0.12, 0.16, 0.2, 0.26, 0.34, 0.62, 0.7, 0.78, 0.86, 0.92, 0.96],
-} as const;
-
-/**
- * Lightness anchors per internal palette kind
- */
-const ROLE_PALETTE_LIGHTNESS_ANCHORS: Record<RolePaletteKind, number> = {
-  grayscale: 0.62,
-  neutral: 0.62,
-  pastel: 0.7,
-  earth: 0.55,
-  mineral: 0.58,
-  muted: 0.6,
-  jewel: 0.62,
-  fluorescent: 0.65,
-  obsidian: 0.12,
-  vaporwave: 0.7,
-  monochromeAccent: 0.62,
-};
+// Fixed hex values for semantic status colors (not theme-generated)
+const DANGER_HEX = parseHexColorOrThrow('#ef4444');
+const SUCCESS_HEX = parseHexColorOrThrow('#22c55e');
+const WARNING_HEX = parseHexColorOrThrow('#f59e0b');
 
 /**
- * Chroma curve per step to prevent "tinted whites" and "glow"
- * Peak energy at 500, falloff at extremes.
+ * Surface semantic resolver: maps color-theory SemanticColorToken references
+ * to hex values from the generated swatches.
  */
-const CHROMA_BY_STEP = [0.1, 0.18, 0.3, 0.45, 0.7, 1.0, 0.92, 0.8, 0.6, 0.4, 0.25] as const;
-
-/**
- * Deterministic Chroma Anchors (OKLCH C)
- */
-const ROLE_PALETTE_CHROMA_ANCHORS: Record<RolePaletteKind, number> = {
-  grayscale: 0,
-  neutral: 0.02,
-  pastel: 0.08,
-  earth: 0.05,
-  mineral: 0.07,
-  muted: 0.04,
-  jewel: 0.16,
-  fluorescent: 0.26,
-  obsidian: 0.01,
-  vaporwave: 0.2,
-  monochromeAccent: 0.02,
-};
-
-/**
- * Chroma Hierarchy Rule
- */
-const CHROMA_HIERARCHY = {
-  primary: 1.0,
-  secondary: 0.7,
-  accent: 0.4,
-  surface: 0.1,
-} as const;
-
-/**
- * Semantic Step Mapping
- */
-const SEMANTIC_STEPS = {
-  light: {
-    bg: 0, // 50
-    bgSubtle: 1, // 100
-    surface: 1, // 100
-    surfaceHover: 2, // 200
-    surfaceActive: 3, // 300
-    border: 3, // 300
-    borderStrong: 4, // 400
-    divider: 2, // 200
-    text: 9, // 900
-    textMuted: 7, // 700
-    textSubtle: 6, // 600
-    solid: 5, // 500
-    softBg: 1, // 100
-    softHover: 2, // 200
-    softActive: 3, // 300
-    outline: 4, // 400
-  },
-  dark: {
-    bg: 0, // 50
-    bgSubtle: 1, // 100
-    surface: 1, // 100
-    surfaceHover: 2, // 200
-    surfaceActive: 3, // 300
-    border: 3, // 300
-    borderStrong: 4, // 400
-    divider: 2, // 200
-    text: 10, // 950
-    textMuted: 8, // 800
-    textSubtle: 7, // 700
-    solid: 5, // 500
-    softBg: 1, // 100
-    softHover: 2, // 200
-    softActive: 3, // 300
-    outline: 4, // 400
-  },
-} as const;
-
-export function generateColorScale(baseColor: OklchColor, isDark: boolean): ColorScale {
-  const scale: Partial<ColorScale> = {};
-  const curve = isDark ? LIGHTNESS_CURVES.dark : LIGHTNESS_CURVES.light;
-
-  // Dark-mode chroma rule: reduce chroma by 25%
-  const chromaMultiplier = isDark ? 0.75 : 1.0;
-  const targetChroma = baseColor.c * chromaMultiplier;
-
-  SCALE_STEPS.forEach((step, index) => {
-    const lightness = curve[index];
-    const chromaByStep = CHROMA_BY_STEP[index];
-    if (lightness === undefined || chromaByStep === undefined) {
-      return;
-    }
-    // Apply chroma falloff curve per step
-    const stepChroma = targetChroma * chromaByStep;
-    const stepColor = { ...baseColor, l: lightness, c: stepChroma };
-    scale[step as keyof ColorScale] = formatHex(stepColor);
-  });
-
-  return scale as ColorScale;
+export type SurfaceSemanticColors = Record<SemanticColorToken, HexColor>;
+
+export function resolveSemanticColors(
+  generated: GeneratedThemeModeColors,
+  references: SemanticColorReferenceMap,
+): SurfaceSemanticColors {
+  return Object.fromEntries(
+    Object.entries(references).map(([token, ref]) => {
+      const swatch = generated.swatches[ref.role];
+      if (!swatch) {
+        throw new Error(`Missing swatch for role '${ref.role}' (token: '${token}')`);
+      }
+      return [token, swatch[ref.step]];
+    }),
+  ) as SurfaceSemanticColors;
 }
 
-/**
- * Deterministic Harmony Hues
- */
-function getHarmonyHues(baseHue: number, mode: ColorHarmony): number[] {
-  const h = (baseHue + 360) % 360;
-  switch (mode) {
-    case 'monochromatic':
-      return [h];
-    case 'analogous':
-      return [h, (h - 30 + 360) % 360, (h + 30) % 360];
-    case 'complementary':
-      return [h, (h + 180) % 360];
-    case 'splitComplementary':
-      return [h, (h + 150) % 360, (h + 210) % 360];
-    case 'triadic':
-      return [h, (h + 120) % 360, (h + 240) % 360];
-    case 'tetradic':
-      return [h, (h + 90) % 360, (h + 180) % 360, (h + 270) % 360];
-    default:
-      return [h];
+function buildNeutralSemantics(neutralSwatch: ColorSwatch, isDark: boolean): NeutralSemantics {
+  if (isDark) {
+    return {
+      bg: neutralSwatch[950],
+      bgSubtle: neutralSwatch[900],
+      surface: neutralSwatch[900],
+      surfaceHover: neutralSwatch[800],
+      surfaceActive: neutralSwatch[700],
+      border: neutralSwatch[800],
+      borderStrong: neutralSwatch[600],
+      divider: neutralSwatch[800],
+      text: neutralSwatch[50],
+      textMuted: neutralSwatch[200],
+      textSubtle: neutralSwatch[300],
+    };
   }
+  return {
+    bg: neutralSwatch[50],
+    bgSubtle: neutralSwatch[100],
+    surface: neutralSwatch[100],
+    surfaceHover: neutralSwatch[200],
+    surfaceActive: neutralSwatch[300],
+    border: neutralSwatch[200],
+    borderStrong: neutralSwatch[300],
+    divider: neutralSwatch[200],
+    text: neutralSwatch[900],
+    textMuted: neutralSwatch[700],
+    textSubtle: neutralSwatch[600],
+  };
 }
 
-function getColorToneRolePalette(colorTone: ColorTone): {
-  bg: RolePaletteKind;
-  surface: RolePaletteKind;
-  primary: RolePaletteKind;
-  secondary: RolePaletteKind;
-  accent: RolePaletteKind;
-  highlight: RolePaletteKind;
-} {
-  switch (colorTone) {
-    case 'pastel':
-      return {
-        bg: 'pastel',
-        surface: 'pastel',
-        primary: 'jewel',
-        secondary: 'jewel',
-        accent: 'jewel',
-        highlight: 'fluorescent',
-      };
-
-    case 'earth':
-      return {
-        bg: 'earth',
-        surface: 'earth',
-        primary: 'mineral',
-        secondary: 'mineral',
-        accent: 'jewel',
-        highlight: 'jewel',
-      };
-
-    case 'mineral':
-      return {
-        bg: 'mineral',
-        surface: 'mineral',
-        primary: 'jewel',
-        secondary: 'mineral',
-        accent: 'jewel',
-        highlight: 'fluorescent',
-      };
-
-    case 'muted':
-      return {
-        bg: 'muted',
-        surface: 'muted',
-        primary: 'jewel',
-        secondary: 'muted',
-        accent: 'jewel',
-        highlight: 'fluorescent',
-      };
+function buildRoleSemantics(swatch: ColorSwatch, isDark: boolean): RoleSemantics {
+  const base = swatch[500];
+  const { foreground: onSolidText } = getReadableForeground(base);
 
-    case 'jewel':
-      return {
-        bg: 'grayscale',
-        surface: 'grayscale',
-        primary: 'jewel',
-        secondary: 'jewel',
-        accent: 'jewel',
-        highlight: 'fluorescent',
-      };
-
-    case 'fluorescent':
-      return {
-        bg: 'obsidian',
-        surface: 'obsidian',
-        primary: 'fluorescent',
-        secondary: 'jewel',
-        accent: 'fluorescent',
-        highlight: 'fluorescent',
-      };
-
-    case 'obsidian':
-      return {
-        bg: 'obsidian',
-        surface: 'obsidian',
-        primary: 'fluorescent',
-        secondary: 'jewel',
-        accent: 'fluorescent',
-        highlight: 'fluorescent',
-      };
-
-    case 'vaporwave':
-      return {
-        bg: 'pastel',
-        surface: 'pastel',
-        primary: 'fluorescent',
-        secondary: 'jewel',
-        accent: 'fluorescent',
-        highlight: 'fluorescent',
-      };
-
-    case 'monochromeAccent':
-      return {
-        bg: 'grayscale',
-        surface: 'grayscale',
-        primary: 'jewel',
-        secondary: 'grayscale',
-        accent: 'jewel',
-        highlight: 'fluorescent',
-      };
-
-    default: // neutral
-      return {
-        bg: 'grayscale',
-        surface: 'grayscale',
-        primary: 'jewel',
-        secondary: 'pastel',
-        accent: 'jewel',
-        highlight: 'fluorescent',
-      };
+  if (isDark) {
+    return {
+      base,
+      hover: swatch[400],
+      strong: swatch[300],
+      softBg: swatch[900],
+      softHover: swatch[800],
+      softActive: swatch[700],
+      outline: swatch[500],
+      onSolidText,
+    };
   }
-}
-
-/**
- * Simple OKLCH L-based contrast check
- */
-function getBestContrast(solidHex: string, neutral50: string, neutral950: string): string {
-  const solid = oklch(solidHex);
-  const n50 = oklch(neutral50);
-  const n950 = oklch(neutral950);
 
-  if (!solid || !n50 || !n950) return neutral50;
-
-  const diff50 = Math.abs(solid.l - n50.l);
-  const diff950 = Math.abs(solid.l - n950.l);
-
-  return diff50 >= diff950 ? neutral50 : neutral950;
+  return {
+    base,
+    hover: swatch[600],
+    strong: swatch[700],
+    softBg: swatch[100],
+    softHover: swatch[200],
+    softActive: swatch[300],
+    outline: swatch[400],
+    onSolidText,
+  };
 }
 
 export function generatePalette(
@@ -316,200 +115,37 @@ export function generatePalette(
   mode: 'light' | 'dark' = 'light',
 ): {
   colors: Record<string, string>;
-  scales: Record<string, ColorScale>;
+  swatches: GeneratedThemeSwatches;
   semantics: ThemeSemantics;
 } {
   const modeConfig = mode === 'dark' ? config.dark : config.light;
-  const { primaryColor, harmony, colorTone } = modeConfig;
-
-  let base = oklch(primaryColor);
-  if (!base) {
-    console.warn(
-      `[colorEngine] Invalid primary color: "${primaryColor}". Falling back to default blue.`,
-    );
-    base = oklch('#3B82F6');
-  }
-
-  const baseHue = base?.h ?? 0;
-  const hues = getHarmonyHues(baseHue, harmony);
-  const rolePalette = getColorToneRolePalette(colorTone);
-
-  // 1. Resolve Chromas
-  const getC = (t: RolePaletteKind) => ROLE_PALETTE_CHROMA_ANCHORS[t];
-  const getHue = (index: number, fallback: number) => hues[index] ?? fallback;
-
-  const primaryChroma = getC(rolePalette.primary);
-  const secondaryChroma = getC(rolePalette.secondary) * CHROMA_HIERARCHY.secondary;
-  const tertiaryChroma = getC(rolePalette.accent) * CHROMA_HIERARCHY.accent;
-  const highlightChroma = getC(rolePalette.highlight);
-  const surfaceChroma = Math.min(0.02, getC(rolePalette.bg) * CHROMA_HIERARCHY.surface);
-
-  // 2. Stable Role Assignment
-  let pHue = getHue(0, baseHue);
-  let sHue = getHue(0, baseHue);
-  let aHue = getHue(0, baseHue);
-  let hHue =
-    harmony === 'tetradic' ? getHue(3, getHue(0, baseHue)) : (getHue(0, baseHue) + 60) % 360; // Yellow-ish offset if no tetradic
-
-  switch (harmony) {
-    case 'complementary':
-      pHue = getHue(0, pHue);
-      aHue = getHue(1, pHue);
-      sHue = (getHue(0, pHue) + 30) % 360;
-      break;
-    case 'splitComplementary':
-    case 'triadic':
-      pHue = getHue(0, pHue);
-      sHue = getHue(1, pHue);
-      aHue = getHue(2, sHue);
-      break;
-    case 'tetradic':
-      pHue = getHue(0, pHue);
-      sHue = getHue(1, pHue);
-      aHue = getHue(2, sHue);
-      hHue = getHue(3, aHue);
-      break;
-    case 'analogous':
-      pHue = getHue(1, pHue);
-      sHue = getHue(0, pHue);
-      aHue = getHue(2, sHue);
-      break;
-  }
-
-  // 3. Build Bases with tuned lightness
-  const getL = (t: RolePaletteKind) => ROLE_PALETTE_LIGHTNESS_ANCHORS[t];
-
-  const primaryBase: OklchColor = {
-    mode: 'oklch',
-    l: getL(rolePalette.primary),
-    c: primaryChroma,
-    h: pHue,
-  };
-  const secondaryBase: OklchColor = {
-    mode: 'oklch',
-    l: getL(rolePalette.secondary),
-    c: secondaryChroma,
-    h: sHue,
-  };
-  const accentBase: OklchColor = {
-    mode: 'oklch',
-    l: getL(rolePalette.accent),
-    c: tertiaryChroma,
-    h: aHue,
-  };
-  const highlightBase: OklchColor = {
-    mode: 'oklch',
-    l: getL(rolePalette.highlight),
-    c: highlightChroma,
-    h: hHue,
-  };
-  const dangerBase: OklchColor = {
-    mode: 'oklch',
-    l: 0.6,
-    c: 0.2,
-    h: 25,
-  };
-  const successBase: OklchColor = {
-    mode: 'oklch',
-    l: 0.6,
-    c: 0.2,
-    h: 145,
-  };
-  const warningBase: OklchColor = {
-    mode: 'oklch',
-    l: 0.75,
-    c: 0.15,
-    h: 85,
-  };
-
-  const neutralBase: OklchColor =
-    surfaceChroma === 0
-      ? { mode: 'oklch', l: 0.62, c: 0 }
-      : { mode: 'oklch', l: 0.62, c: surfaceChroma, h: 260 };
-
-  // 4. Generate Scales
   const isDark = mode === 'dark';
-  const scales = {
-    primary: generateColorScale(primaryBase, isDark),
-    secondary: generateColorScale(secondaryBase, isDark),
-    accent: generateColorScale(accentBase, isDark),
-    highlight: generateColorScale(highlightBase, isDark),
-    neutral: generateColorScale(neutralBase, isDark),
-    danger: generateColorScale(dangerBase, isDark),
-    success: generateColorScale(successBase, isDark),
-    warning: generateColorScale(warningBase, isDark),
-  };
 
-  // 5. Mappings
-  const steps = isDark ? SEMANTIC_STEPS.dark : SEMANTIC_STEPS.light;
-  const getStep = (s: ColorScale, idx: number) => {
-    const key = SCALE_STEPS[idx] ?? SCALE_STEPS[SCALE_STEPS.length - 1] ?? 950;
-    return s[key];
-  };
+  // Throws deterministically on invalid primary color
+  parseHexColorOrThrow(modeConfig.primaryColor);
 
-  const getNeutralMapping = (scale: ColorScale): NeutralSemantics => ({
-    bg: getStep(scale, steps.bg),
-    bgSubtle: getStep(scale, steps.bgSubtle),
-    surface: getStep(scale, steps.surface),
-    surfaceHover: getStep(scale, steps.surfaceHover),
-    surfaceActive: getStep(scale, steps.surfaceActive),
-    border: getStep(scale, steps.border),
-    borderStrong: getStep(scale, steps.borderStrong),
-    divider: getStep(scale, steps.divider),
-    text: getStep(scale, steps.text),
-    textMuted: getStep(scale, steps.textMuted),
-    textSubtle: getStep(scale, steps.textSubtle),
-  });
+  const generated = generateThemeModeColors(modeConfig);
 
-  const getColorMapping = (scale: ColorScale, neutralScale: ColorScale): RoleSemantics => {
-    const solid = getStep(scale, steps.solid);
-    const softChromaLimit = 0.08;
+  const { swatches } = generated;
+  const neutralSwatch = swatches.neutral;
 
-    // Chroma capping for soft tokens
-    const getSoftStep = (idx: number) => {
-      const hex = getStep(scale, idx);
-      const color = oklch(hex);
-      if (color && color.c > softChromaLimit) {
-        return formatHex({ ...color, c: softChromaLimit });
-      }
-      return hex;
-    };
+  const neutral = buildNeutralSemantics(neutralSwatch, isDark);
+  const brand = buildRoleSemantics(swatches.primary, isDark);
 
-    return {
-      base: solid,
-      hover: getStep(scale, 6), // 600
-      strong: getStep(scale, 7), // 700
-      softBg: getSoftStep(steps.softBg),
-      softHover: getSoftStep(steps.softHover),
-      softActive: getSoftStep(steps.softActive),
-      outline: getStep(scale, steps.outline),
-      onSolidText: getBestContrast(solid, getStep(neutralScale, 0), getStep(neutralScale, 10)),
-    };
-  };
+  // Fallback to primary swatch for missing ordinal roles
+  const secondarySwatch = swatches.secondary ?? swatches.primary;
+  const tertiarySwatch = swatches.tertiary ?? swatches.primary;
+  const quaternarySwatch = swatches.quaternary ?? swatches.primary;
 
-  const neutral = getNeutralMapping(scales.neutral);
-  const brand = getColorMapping(scales.primary, scales.neutral);
-  const neutralAction = getColorMapping(scales.neutral, scales.neutral);
-  const danger = getColorMapping(scales.danger, scales.neutral);
-  const success = getColorMapping(scales.success, scales.neutral);
-  const warning = getColorMapping(scales.warning, scales.neutral);
+  const dangerSwatch = generateColorSwatch(DANGER_HEX).swatch;
+  const successSwatch = generateColorSwatch(SUCCESS_HEX).swatch;
+  const warningSwatch = generateColorSwatch(WARNING_HEX).swatch;
 
-  const colors: Record<string, string> = {
-    primary: getStep(scales.primary, steps.solid),
-    secondary: getStep(scales.secondary, steps.solid),
-    accent: getStep(scales.accent, steps.solid),
-    highlight: getStep(scales.highlight, steps.solid),
-    background: neutral.bg,
-    surface: neutral.surface,
-    text: neutral.text,
-    textSecondary: neutral.textMuted,
-    border: neutral.border,
-    error: getStep(scales.danger, steps.solid),
-    success: getStep(scales.success, steps.solid),
-    warning: getStep(scales.warning, steps.solid),
-  };
+  const danger = buildRoleSemantics(dangerSwatch, isDark);
+  const success = buildRoleSemantics(successSwatch, isDark);
+  const warning = buildRoleSemantics(warningSwatch, isDark);
 
-  const surface: SurfaceSemantics = {
+  const surfaceSemantics: SurfaceSemantics = {
     default: neutral.surface,
     subtle: neutral.bgSubtle,
     raised: neutral.surface,
@@ -530,23 +166,38 @@ export function generatePalette(
 
   const action: ActionSemantics = {
     primary: brand,
-    neutral: neutralAction,
+    neutral: buildRoleSemantics(neutralSwatch, isDark),
     danger,
   };
 
+  const colors: Record<string, string> = {
+    primary: brand.base,
+    secondary: secondarySwatch[500],
+    accent: tertiarySwatch[500],
+    highlight: quaternarySwatch[500],
+    background: neutral.bg,
+    surface: neutral.surface,
+    text: neutral.text,
+    textSecondary: neutral.textMuted,
+    border: neutral.border,
+    error: danger.base,
+    success: success.base,
+    warning: warning.base,
+  };
+
   return {
     colors,
-    scales,
+    swatches,
     semantics: {
       neutral,
       brand,
-      secondary: getColorMapping(scales.secondary, scales.neutral),
-      accent: getColorMapping(scales.accent, scales.neutral),
-      highlight: getColorMapping(scales.highlight, scales.neutral),
+      secondary: buildRoleSemantics(secondarySwatch, isDark),
+      accent: buildRoleSemantics(tertiarySwatch, isDark),
+      highlight: buildRoleSemantics(quaternarySwatch, isDark),
       danger,
       success,
       warning,
-      surface,
+      surface: surfaceSemantics,
       content,
       border,
       action,