@ankhorage/surface 0.1.4 → 0.1.6

package/src/theme/ThemeContext.tsx

@@ -0,0 +1,95 @@
+import React, { createContext, useContext, useMemo } from 'react';
+
+import { useFontContext } from '../context/FontContext';
+import { ResponsiveProvider } from '../core/responsive/ResponsiveProvider';
+import { OverlayProvider } from '../internal/overlay/OverlayProvider';
+import { isDeepEqual } from '../utils/deepEqual';
+import { deepMerge } from '../utils/deepMerge';
+import { createTheme } from './createTheme';
+import type { AnkhTheme, ThemeConfig } from './types';
+
+const defaultTheme = createTheme();
+
+export const ThemeContext = createContext<{
+  theme: AnkhTheme;
+  mode: 'light' | 'dark';
+  setThemeConfig: (config: Partial<ThemeConfig>) => void;
+  setMode: (mode: 'light' | 'dark') => void;
+  _hasProvider?: boolean;
+}>({
+  theme: defaultTheme,
+  mode: 'light',
+  setThemeConfig: () => {
+    /* fallback */
+  },
+  setMode: () => {
+    /* fallback */
+  },
+  _hasProvider: false,
+});
+
+export const ThemeProvider = ({
+  children,
+  initialConfig,
+  initialMode = 'light',
+}: {
+  children: React.ReactNode;
+  initialConfig?: Partial<ThemeConfig>;
+  initialMode?: 'light' | 'dark';
+}) => {
+  const [config, setConfig] = React.useState<ThemeConfig>(() =>
+    initialConfig ? deepMerge(defaultTheme.config, initialConfig) : defaultTheme.config,
+  );
+  const [mode, setMode] = React.useState<'light' | 'dark'>(initialMode);
+  const { activeFontId } = useFontContext();
+
+  // Keep state in sync with prop for real-time Studio updates
+  React.useEffect(() => {
+    if (initialConfig) {
+      setConfig((prev) => {
+        const merged = deepMerge(prev, initialConfig);
+        if (isDeepEqual(prev, merged)) return prev;
+        return merged;
+      });
+    }
+  }, [initialConfig]);
+
+  const theme = useMemo(
+    () => createTheme(config, mode, activeFontId),
+    [config, mode, activeFontId],
+  );
+
+  const value = useMemo(
+    () => ({
+      theme,
+      mode,
+      setThemeConfig: (newConfig: Partial<ThemeConfig>) =>
+        setConfig((prev) => deepMerge(prev, newConfig)),
+      setMode,
+      _hasProvider: true,
+    }),
+    [theme, mode],
+  );
+
+  return (
+    <ResponsiveProvider>
+      <ThemeContext.Provider value={value}>
+        <OverlayProvider>{children}</OverlayProvider>
+      </ThemeContext.Provider>
+    </ResponsiveProvider>
+  );
+};
+
+export const useTheme = () => {
+  return useContext(ThemeContext);
+};
+
+export const useThemeConfig = () => {
+  const { setThemeConfig } = useTheme();
+  return setThemeConfig;
+};
+
+export const useThemeMode = () => {
+  const { mode, setMode } = useTheme();
+  return { mode, setMode };
+};

package/src/theme/colorEngine.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'bun:test';
+import { oklch } from 'culori';
+
+import { generatePalette } from './colorEngine';
+import type { ThemeConfig } from './types';
+
+const mockConfig: ThemeConfig = {
+  id: 'test',
+  name: 'Test Theme',
+  light: {
+    primaryColor: '#3B82F6',
+    harmony: 'triadic',
+    systemTone: 'neutral',
+  },
+  dark: {
+    primaryColor: '#3B82F6',
+    harmony: 'triadic',
+    systemTone: 'neutral',
+  },
+};
+
+describe('colorEngine', () => {
+  it('should generate a stable palette with deterministic chroma hierarchy', () => {
+    const { colors, semantics, scales } = generatePalette(mockConfig, 'light');
+
+    // Primary should be defined
+    expect(colors.primary).toBeDefined();
+
+    // Verify neutral surface chroma is strictly limited
+    const neutralBg = oklch(semantics.neutral.bg);
+    expect(neutralBg?.c).toBeLessThanOrEqual(0.021); // Small epsilon for float
+
+    // Verify presence of new tokens
+    expect(semantics.neutral.bgSubtle).toBeDefined();
+    expect(semantics.brand.onSolidText).toBeDefined();
+    expect(semantics.brand.softBg).toBeDefined();
+    expect(semantics.surface.default).toBe(semantics.neutral.surface);
+    expect(semantics.content.muted).toBe(semantics.neutral.textMuted);
+    expect(semantics.border.focus).toBe(semantics.brand.outline);
+    expect(semantics.action.primary.base).toBe(semantics.brand.base);
+    expect(semantics.action.danger.base).toBe(semantics.danger.base);
+
+    // Verify scale coverage
+    const primaryScale = scales.primary;
+    const neutralScale = scales.neutral;
+    expect(primaryScale).toBeDefined();
+    expect(neutralScale).toBeDefined();
+    if (!primaryScale || !neutralScale) throw new Error('Expected generated scales');
+    expect(Object.keys(primaryScale)).toHaveLength(11);
+    expect(neutralScale[50]).toBeDefined();
+    expect(neutralScale[950]).toBeDefined();
+  });
+
+  it('should respect triadic hue offsets (120 degrees)', () => {
+    const { colors } = generatePalette(mockConfig, 'light');
+
+    const p = oklch(colors.primary);
+    const s = oklch(colors.secondary);
+    const a = oklch(colors.accent);
+
+    if (p && s && a) {
+      const h1 = p.h ?? 0;
+      const h2 = s.h ?? 0;
+      const h3 = a.h ?? 0;
+
+      // Check distance (allowing for small float rounding and perceptual shift)
+      const diff1 = Math.abs((h2 - h1 + 360) % 360);
+      const diff2 = Math.abs((h3 - h1 + 360) % 360);
+
+      expect(diff1).toBeGreaterThan(115);
+      expect(diff1).toBeLessThan(125);
+      expect(diff2).toBeGreaterThan(235);
+      expect(diff2).toBeLessThan(245);
+    }
+  });
+
+  it('should handle monochromatic harmony (one hue)', () => {
+    const config = {
+      ...mockConfig,
+      light: { ...mockConfig.light, harmony: 'monochromatic' as const },
+    };
+    const { colors } = generatePalette(config, 'light');
+
+    const p = oklch(colors.primary);
+    const s = oklch(colors.secondary);
+
+    expect(p?.h).toBeCloseTo(s?.h ?? 0, 0);
+  });
+
+  it('should generate dark mode colors correctly', () => {
+    const { colors, semantics } = generatePalette(mockConfig, 'dark');
+
+    const bg = oklch(colors.background);
+    expect(bg?.l).toBeLessThan(0.2); // Should be dark
+    expect(colors.background).toBe(semantics.neutral.bg);
+    expect(semantics.content.inverse).toBe(semantics.brand.onSolidText);
+  });
+
+  it('should fall back to a default color if primaryColor is invalid', () => {
+    const config = {
+      ...mockConfig,
+      light: { ...mockConfig.light, primaryColor: 'invalid-color' },
+    };
+
+    // Should not throw
+    const { colors } = generatePalette(config, 'light');
+    expect(colors.primary).toBeDefined();
+    // Default fallback blue #3B82F6 in OKLCH
+    const p = oklch(colors.primary);
+    const fallbackBlue = oklch('#3B82F6');
+    expect(fallbackBlue).toBeDefined();
+    expect(p?.h).toBeCloseTo(fallbackBlue?.h ?? 0, 0);
+  });
+});

package/src/theme/colorEngine.ts

@@ -0,0 +1,480 @@
+import { formatHex, modeOklch, oklch, useMode } from 'culori';
+
+import type {
+  ActionSemantics,
+  BorderSemantics,
+  ColorHarmony,
+  ColorScale,
+  ColorTone,
+  ContentSemantics,
+  NeutralSemantics,
+  RoleSemantics,
+  SurfaceSemantics,
+  SystemTone,
+  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;
+
+/**
+ * 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 tone
+ */
+const TONE_LIGHTNESS_ANCHORS: Record<ColorTone, number> = {
+  grayscale: 0.62,
+  earth: 0.55,
+  pastel: 0.7,
+  jewel: 0.62,
+  fluorescent: 0.65,
+};
+
+/**
+ * Chroma curve per step to prevent "tinted whites" and "glow"
+ * Peak energy at 500, falloff at extremes.
+ */
+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 CHROMA_ANCHORS: Record<ColorTone, number> = {
+  grayscale: 0,
+  earth: 0.05,
+  pastel: 0.08,
+  jewel: 0.16,
+  fluorescent: 0.26,
+};
+
+/**
+ * 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;
+}
+
+/**
+ * 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];
+  }
+}
+
+/**
+ * System Tone Assignment Logic
+ */
+function getSystemToneMapping(system: SystemTone): {
+  bg: ColorTone;
+  surface: ColorTone;
+  primary: ColorTone;
+  secondary: ColorTone;
+  accent: ColorTone;
+  highlight: ColorTone;
+} {
+  switch (system) {
+    case 'pastel':
+      return {
+        bg: 'pastel',
+        surface: 'pastel',
+        primary: 'pastel',
+        secondary: 'pastel',
+        accent: 'jewel',
+        highlight: 'fluorescent',
+      };
+    case 'earth':
+      return {
+        bg: 'earth',
+        surface: 'earth',
+        primary: 'earth',
+        secondary: 'earth',
+        accent: 'jewel',
+        highlight: 'jewel',
+      };
+    case 'jewel':
+      return {
+        bg: 'grayscale',
+        surface: 'grayscale',
+        primary: 'jewel',
+        secondary: 'jewel',
+        accent: 'jewel',
+        highlight: 'fluorescent',
+      };
+    case 'fluorescent':
+      return {
+        bg: 'grayscale',
+        surface: 'grayscale',
+        primary: 'jewel',
+        secondary: 'jewel',
+        accent: 'fluorescent',
+        highlight: 'fluorescent',
+      };
+    default: // neutral
+      return {
+        bg: 'grayscale',
+        surface: 'grayscale',
+        primary: 'jewel',
+        secondary: 'pastel',
+        accent: 'jewel',
+        highlight: 'fluorescent',
+      };
+  }
+}
+
+/**
+ * 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;
+}
+
+export function generatePalette(
+  config: ThemeConfig,
+  mode: 'light' | 'dark' = 'light',
+): {
+  colors: Record<string, string>;
+  scales: Record<string, ColorScale>;
+  semantics: ThemeSemantics;
+} {
+  const modeConfig = mode === 'dark' ? config.dark : config.light;
+  const { primaryColor, harmony, systemTone } = modeConfig;
+
+  let base = oklch(primaryColor) as OklchColor | undefined;
+  if (!base) {
+    console.warn(
+      `[colorEngine] Invalid primary color: "${primaryColor}". Falling back to default blue.`,
+    );
+    base = oklch('#3B82F6') as OklchColor;
+  }
+
+  const baseHue = base.h ?? 0;
+  const hues = getHarmonyHues(baseHue, harmony);
+  const toneMap = getSystemToneMapping(systemTone);
+
+  // 1. Resolve Chromas
+  const getC = (t: ColorTone) => CHROMA_ANCHORS[t];
+  const getHue = (index: number, fallback: number) => hues[index] ?? fallback;
+
+  const primaryChroma = getC(toneMap.primary);
+  const secondaryChroma = getC(toneMap.secondary) * CHROMA_HIERARCHY.secondary;
+  const tertiaryChroma = getC(toneMap.accent) * CHROMA_HIERARCHY.accent;
+  const highlightChroma = getC(toneMap.highlight);
+  const surfaceChroma = Math.min(0.02, getC(toneMap.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: ColorTone) => TONE_LIGHTNESS_ANCHORS[t];
+
+  const primaryBase: OklchColor = {
+    mode: 'oklch',
+    l: getL(toneMap.primary),
+    c: primaryChroma,
+    h: pHue,
+  };
+  const secondaryBase: OklchColor = {
+    mode: 'oklch',
+    l: getL(toneMap.secondary),
+    c: secondaryChroma,
+    h: sHue,
+  };
+  const accentBase: OklchColor = {
+    mode: 'oklch',
+    l: getL(toneMap.accent),
+    c: tertiaryChroma,
+    h: aHue,
+  };
+  const highlightBase: OklchColor = {
+    mode: 'oklch',
+    l: getL(toneMap.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];
+  };
+
+  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 getColorMapping = (scale: ColorScale, neutralScale: ColorScale): RoleSemantics => {
+    const solid = getStep(scale, steps.solid);
+    const softChromaLimit = 0.08;
+
+    // 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;
+    };
+
+    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)),
+    };
+  };
+
+  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 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 surface: SurfaceSemantics = {
+    default: neutral.surface,
+    subtle: neutral.bgSubtle,
+    raised: neutral.surface,
+  };
+
+  const content: ContentSemantics = {
+    default: neutral.text,
+    muted: neutral.textMuted,
+    subtle: neutral.textSubtle,
+    inverse: brand.onSolidText,
+  };
+
+  const border: BorderSemantics = {
+    default: neutral.border,
+    strong: neutral.borderStrong,
+    focus: brand.outline,
+  };
+
+  const action: ActionSemantics = {
+    primary: brand,
+    neutral: neutralAction,
+    danger,
+  };
+
+  return {
+    colors,
+    scales,
+    semantics: {
+      neutral,
+      brand,
+      secondary: getColorMapping(scales.secondary, scales.neutral),
+      accent: getColorMapping(scales.accent, scales.neutral),
+      highlight: getColorMapping(scales.highlight, scales.neutral),
+      danger,
+      success,
+      warning,
+      surface,
+      content,
+      border,
+      action,
+    },
+  };
+}