@ankhorage/surface 0.2.3 → 1.0.0

package/src/theme/colorEngine.test.ts

@@ -1,8 +1,13 @@
+import type { SemanticColorToken } from '@ankhorage/color-theory';
+import {
+  DARK_SEMANTIC_COLOR_REFERENCES,
+  LIGHT_SEMANTIC_COLOR_REFERENCES,
+} from '@ankhorage/color-theory';
+import type { ThemeConfig } from '@ankhorage/contracts';
 import { describe, expect, it } from 'bun:test';
-import { oklch } from 'culori';
 
-import { generatePalette } from './colorEngine';
-import type { ColorTone, ThemeConfig, ThemeSemantics } from './types';
+import { generatePalette, resolveSemanticColors } from './colorEngine';
+import type { ThemeSemantics } from './types';
 
 const mockConfig: ThemeConfig = {
   id: 'test',
@@ -10,53 +15,19 @@ const mockConfig: ThemeConfig = {
   light: {
     primaryColor: '#3B82F6',
     harmony: 'triadic',
-    colorTone: 'neutral',
   },
   dark: {
     primaryColor: '#3B82F6',
     harmony: 'triadic',
-    colorTone: 'neutral',
   },
 };
 
-function configForColorTone(colorTone: ColorTone): ThemeConfig {
-  return {
-    ...mockConfig,
-    light: {
-      ...mockConfig.light,
-      colorTone,
-    },
-    dark: {
-      ...mockConfig.dark,
-      colorTone,
-    },
-  };
-}
-
-function lightness(hex: string): number {
-  const color = oklch(hex);
-  if (!color) {
-    throw new Error(`Expected valid OKLCH color for ${hex}.`);
-  }
-  return color.l;
-}
-
-function chroma(hex: string): number {
-  const color = oklch(hex);
-  if (!color) {
-    throw new Error(`Expected valid OKLCH color for ${hex}.`);
-  }
-  return color.c;
-}
-
 function expectRequiredSemanticRoles(semantics: ThemeSemantics) {
   expect(semantics.neutral.bg).toBeDefined();
   expect(semantics.neutral.surface).toBeDefined();
   expect(semantics.neutral.text).toBeDefined();
   expect(semantics.brand.base).toBeDefined();
   expect(semantics.secondary.base).toBeDefined();
-  expect(semantics.accent.base).toBeDefined();
-  expect(semantics.highlight.base).toBeDefined();
   expect(semantics.danger.base).toBeDefined();
   expect(semantics.success.base).toBeDefined();
   expect(semantics.warning.base).toBeDefined();
@@ -69,159 +40,192 @@ function expectRequiredSemanticRoles(semantics: ThemeSemantics) {
 }
 
 describe('colorEngine', () => {
-  it('should generate a stable palette with deterministic chroma hierarchy', () => {
-    const { colors, semantics, scales } = generatePalette(mockConfig, 'light');
+  it('generates a valid palette for light mode', () => {
+    const { colors, swatches, semantics } = generatePalette(mockConfig, 'light');
 
-    // Primary should be defined
     expect(colors.primary).toBeDefined();
+    expect(swatches.primary).toBeDefined();
+    expect(swatches.neutral).toBeDefined();
+    expect(Object.keys(swatches.primary)).toHaveLength(11);
+    expect(Object.keys(swatches.neutral)).toHaveLength(11);
 
-    // 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();
+    // Surface semantic aliases
     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();
+    // Surface runtime semantic aliases derived from ordinal swatches
+    expect(semantics.accent.base).toBeDefined();
+    expect(semantics.highlight.base).toBeDefined();
+    // accent/highlight are Surface semantic aliases (tertiary/quaternary fallback to primary when absent)
+    expect(semantics.accent.base).toBe(colors.accent);
+    expect(semantics.highlight.base).toBe(colors.highlight);
   });
 
-  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);
+  it('generates a valid palette for dark mode', () => {
+    const { colors, semantics } = generatePalette(mockConfig, 'dark');
 
-      expect(diff1).toBeGreaterThan(115);
-      expect(diff1).toBeLessThan(125);
-      expect(diff2).toBeGreaterThan(235);
-      expect(diff2).toBeLessThan(245);
-    }
+    expect(colors.background).toBe(semantics.neutral.bg);
+    expect(semantics.content.inverse).toBe(semantics.brand.onSolidText);
   });
 
-  it('should handle monochromatic harmony (one hue)', () => {
-    const config = {
-      ...mockConfig,
-      light: { ...mockConfig.light, harmony: 'monochromatic' as const },
-    };
-    const { colors } = generatePalette(config, 'light');
+  it('uses mode-aware role semantics for dark mode soft states', () => {
+    const light = generatePalette(mockConfig, 'light');
+    const dark = generatePalette(mockConfig, 'dark');
 
-    const p = oklch(colors.primary);
-    const s = oklch(colors.secondary);
+    expect(light.semantics.brand.softBg).toBe(light.swatches.primary[100]);
+    expect(light.semantics.brand.softHover).toBe(light.swatches.primary[200]);
+    expect(light.semantics.brand.softActive).toBe(light.swatches.primary[300]);
+    expect(dark.semantics.brand.softBg).toBe(dark.swatches.primary[900]);
+    expect(dark.semantics.brand.softHover).toBe(dark.swatches.primary[800]);
+    expect(dark.semantics.brand.softActive).toBe(dark.swatches.primary[700]);
+  });
 
-    expect(p?.h).toBeCloseTo(s?.h ?? 0, 0);
+  it('preserves the primary color at swatch step 500 in light mode', () => {
+    const { swatches } = generatePalette(mockConfig, 'light');
+    expect(swatches.primary[500]).toBe(mockConfig.light.primaryColor);
   });
 
-  it('should generate dark mode colors correctly', () => {
-    const { colors, semantics } = generatePalette(mockConfig, 'dark');
+  it('preserves the primary color at swatch step 500 in dark mode', () => {
+    const { swatches } = generatePalette(mockConfig, 'dark');
+    expect(swatches.primary[500]).toBe(mockConfig.dark.primaryColor);
+  });
 
-    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('provides a neutral swatch with neutralKeyColor at step 500', () => {
+    const { swatches } = generatePalette(mockConfig, 'light');
+    // neutral swatch must have a step 500 entry
+    expect(swatches.neutral[500]).toBeDefined();
   });
 
-  it('should fall back to a default color if primaryColor is invalid', () => {
+  it('throws deterministically on invalid primary color', () => {
     const config = {
       ...mockConfig,
-      light: { ...mockConfig.light, primaryColor: 'invalid-color' },
+      light: { ...mockConfig.light, primaryColor: 'not-a-hex-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);
+    expect(() => generatePalette(config, 'light')).toThrow();
   });
 
-  it('keeps fluorescent and obsidian dark surfaces low-lightness', () => {
-    const fluorescent = generatePalette(configForColorTone('fluorescent'), 'dark');
-    const obsidian = generatePalette(configForColorTone('obsidian'), 'dark');
-
-    expect(lightness(fluorescent.semantics.neutral.bg)).toBeLessThan(0.2);
-    expect(lightness(fluorescent.semantics.surface.default)).toBeLessThan(0.2);
-    expect(lightness(obsidian.semantics.neutral.bg)).toBeLessThan(0.2);
-    expect(lightness(obsidian.semantics.surface.default)).toBeLessThan(0.2);
+  it('throws deterministically on invalid primary color in dark mode', () => {
+    const config = {
+      ...mockConfig,
+      dark: { ...mockConfig.dark, primaryColor: 'rgb(0,0,0)' },
+    };
+    expect(() => generatePalette(config, 'dark')).toThrow();
   });
 
-  it('keeps fluorescent action colors higher chroma than neutral actions', () => {
-    const fluorescent = generatePalette(configForColorTone('fluorescent'), 'light');
-    const neutral = generatePalette(configForColorTone('neutral'), 'light');
-
-    expect(chroma(fluorescent.semantics.brand.base)).toBeGreaterThan(
-      chroma(neutral.semantics.action.neutral.base),
-    );
-    expect(chroma(fluorescent.semantics.accent.base)).toBeGreaterThan(
-      chroma(neutral.semantics.action.neutral.base),
-    );
+  it('emits required semantic roles for all harmonies', () => {
+    const harmonies = [
+      'monochromatic',
+      'analogous',
+      'complementary',
+      'triadic',
+      'tetradic',
+      'splitComplementary',
+    ] as const;
+
+    for (const harmony of harmonies) {
+      const config = {
+        ...mockConfig,
+        light: { ...mockConfig.light, harmony },
+        dark: { ...mockConfig.dark, harmony },
+      };
+      const light = generatePalette(config, 'light');
+      const dark = generatePalette(config, 'dark');
+      expectRequiredSemanticRoles(light.semantics);
+      expectRequiredSemanticRoles(dark.semantics);
+    }
   });
 
-  it('keeps pastel backgrounds lower chroma than foreground and action colors', () => {
-    const { semantics } = generatePalette(configForColorTone('pastel'), 'light');
-
-    expect(chroma(semantics.neutral.bg)).toBeLessThan(chroma(semantics.brand.base));
-    expect(chroma(semantics.neutral.bg)).toBeLessThan(chroma(semantics.accent.base));
-    expect(chroma(semantics.surface.default)).toBeLessThan(chroma(semantics.action.primary.base));
+  it('generates ordinal chromatic role swatches (no accent/highlight as swatch keys)', () => {
+    const { swatches } = generatePalette(mockConfig, 'light');
+    const keys = Object.keys(swatches);
+    expect(keys).not.toContain('accent');
+    expect(keys).not.toContain('highlight');
+    expect(keys).not.toContain('surfaceTint');
+    expect(keys).not.toContain('base');
+    // ordinal roles are present
+    expect(keys).toContain('primary');
+    expect(keys).toContain('neutral');
   });
 
-  it('keeps earth action colors aligned with mineral-like chroma', () => {
-    const earth = generatePalette(configForColorTone('earth'), 'light');
-    const mineral = generatePalette(configForColorTone('mineral'), 'light');
-
-    expect(chroma(earth.semantics.brand.base)).toBeGreaterThan(chroma(earth.semantics.neutral.bg));
-    expect(chroma(earth.semantics.secondary.base)).toBeCloseTo(
-      chroma(mineral.semantics.secondary.base),
-      3,
-    );
+  it('semantic resolver maps all SemanticColorToken entries for light mode', () => {
+    const { swatches } = generatePalette(mockConfig, 'light');
+    // Build a minimal GeneratedThemeModeColors for resolver testing
+    const generated = {
+      harmonyRoleColors: {} as never,
+      swatches,
+      neutral: { neutralKeyColor: swatches.neutral[500], diagnostics: {} as never },
+    };
+    const resolved = resolveSemanticColors(generated, LIGHT_SEMANTIC_COLOR_REFERENCES);
+    const tokens: SemanticColorToken[] = [
+      'background',
+      'surface',
+      'surfaceRaised',
+      'border',
+      'divider',
+      'text',
+      'textMuted',
+      'disabledBg',
+      'disabledText',
+      'brand',
+      'brandEmphasis',
+      'action',
+      'actionEmphasis',
+    ];
+    for (const token of tokens) {
+      expect(resolved[token]).toBeDefined();
+      expect(typeof resolved[token]).toBe('string');
+    }
   });
 
-  it('emits required semantic roles for every color tone', () => {
-    const colorTones: readonly ColorTone[] = [
-      'neutral',
-      'pastel',
-      'earth',
-      'mineral',
-      'muted',
-      'jewel',
-      'fluorescent',
-      'obsidian',
-      'vaporwave',
-      'monochromeAccent',
+  it('semantic resolver maps all SemanticColorToken entries for dark mode', () => {
+    const { swatches } = generatePalette(mockConfig, 'dark');
+    const generated = {
+      harmonyRoleColors: {} as never,
+      swatches,
+      neutral: { neutralKeyColor: swatches.neutral[500], diagnostics: {} as never },
+    };
+    const resolved = resolveSemanticColors(generated, DARK_SEMANTIC_COLOR_REFERENCES);
+    const tokens: SemanticColorToken[] = [
+      'background',
+      'surface',
+      'surfaceRaised',
+      'border',
+      'divider',
+      'text',
+      'textMuted',
+      'disabledBg',
+      'disabledText',
+      'brand',
+      'brandEmphasis',
+      'action',
+      'actionEmphasis',
     ];
+    for (const token of tokens) {
+      expect(resolved[token]).toBeDefined();
+    }
+  });
 
-    for (const colorTone of colorTones) {
-      const light = generatePalette(configForColorTone(colorTone), 'light');
-      const dark = generatePalette(configForColorTone(colorTone), 'dark');
+  it('neutral semantics power backgrounds, borders, text in light mode', () => {
+    const { semantics } = generatePalette(mockConfig, 'light');
+    expect(semantics.neutral.bg).toBeDefined();
+    expect(semantics.neutral.bgSubtle).toBeDefined();
+    expect(semantics.neutral.surface).toBeDefined();
+    expect(semantics.neutral.surfaceHover).toBeDefined();
+    expect(semantics.neutral.border).toBeDefined();
+    expect(semantics.neutral.borderStrong).toBeDefined();
+    expect(semantics.neutral.divider).toBeDefined();
+    expect(semantics.neutral.text).toBeDefined();
+    expect(semantics.neutral.textMuted).toBeDefined();
+    expect(semantics.neutral.textSubtle).toBeDefined();
+  });
 
-      expectRequiredSemanticRoles(light.semantics);
-      expectRequiredSemanticRoles(dark.semantics);
-    }
+  it('readable foregrounds are generated for brand base in both modes', () => {
+    const light = generatePalette(mockConfig, 'light');
+    const dark = generatePalette(mockConfig, 'dark');
+    expect(light.semantics.brand.onSolidText).toMatch(/^#/);
+    expect(dark.semantics.brand.onSolidText).toMatch(/^#/);
   });
 });