@ankhorage/surface 8.0.0 → 9.0.0

package/src/theme/ThemeContext.tsx

@@ -1,94 +0,0 @@
-import React, { createContext, use, 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 { SurfaceTheme, ThemeConfig } from './types';
-
-const defaultTheme = createTheme();
-
-export const ThemeContext = createContext<{
-  theme: SurfaceTheme;
-  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();
-
-  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 value={value}>
-        <OverlayProvider>{children}</OverlayProvider>
-      </ThemeContext>
-    </ResponsiveProvider>
-  );
-};
-
-export const useTheme = () => {
-  return use(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

@@ -1,302 +0,0 @@
-import type { SemanticColorToken } from '@ankhorage/color-theory';
-import {
-  COLOR_HARMONIES,
-  DARK_SEMANTIC_COLOR_REFERENCES,
-  DEFAULT_SEMANTIC_STATUS_COLOR_SEEDS,
-  LIGHT_SEMANTIC_COLOR_REFERENCES,
-} from '@ankhorage/color-theory';
-import type { ThemeConfig } from '@ankhorage/contracts';
-import { describe, expect, it } from 'bun:test';
-
-import { generatePalette, resolveSemanticColors } from './colorEngine';
-import type { ThemeSemantics } from './types';
-
-const mockConfig: ThemeConfig = {
-  id: 'test',
-  name: 'Test Theme',
-  light: {
-    primaryColor: '#3B82F6',
-    harmony: 'triadic',
-  },
-  dark: {
-    primaryColor: '#3B82F6',
-    harmony: 'triadic',
-  },
-};
-
-function expectCompleteSemanticValues(semantics: ThemeSemantics) {
-  visitSemanticValues(semantics);
-}
-
-function visitSemanticValues(value: object): void {
-  for (const entry of Object.values(value)) {
-    if (typeof entry === 'string') {
-      expect(entry.length).toBeGreaterThan(0);
-    } else {
-      visitSemanticValues(entry as object);
-    }
-  }
-}
-
-describe('colorEngine', () => {
-  it('generates a valid palette for light mode', () => {
-    const { colors, swatches, semantics } = generatePalette(mockConfig, 'light');
-
-    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);
-
-    // 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);
-
-    // 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('generates a valid palette for dark mode', () => {
-    const { colors, swatches, semantics } = generatePalette(mockConfig, 'dark');
-
-    expect(colors.background).toBe(semantics.neutral.bg);
-    expect(semantics.surface.inverse).toBe(swatches.neutral[50]);
-    expect(semantics.content.inverse).toBe(swatches.neutral[900]);
-  });
-
-  it('uses the Color Theory status owner independently from brand harmony', () => {
-    const statusConfig: ThemeConfig = {
-      ...mockConfig,
-      light: { primaryColor: '#dc2626', harmony: 'monochromatic' },
-      dark: { primaryColor: '#dc2626', harmony: 'monochromatic' },
-    };
-    const light = generatePalette(statusConfig, 'light');
-    const dark = generatePalette(statusConfig, 'dark');
-
-    expect(light.semantics.danger.base).toBe('#ef4444');
-    expect(light.semantics.success.base).toBe('#22c55e');
-    expect(light.semantics.warning.base).toBe('#f59e0b');
-    expect(light.semantics.error.base).toBe(light.semantics.danger.base);
-    expect(light.semantics.info.base).toBe(DEFAULT_SEMANTIC_STATUS_COLOR_SEEDS.info);
-    expect(light.semantics.info.base).not.toBe(light.semantics.brand.base);
-
-    expect(dark.semantics.danger.base).toBe('#ef4444');
-    expect(dark.semantics.success.base).toBe('#22c55e');
-    expect(dark.semantics.warning.base).toBe('#f59e0b');
-    expect(dark.semantics.error.base).toBe(dark.semantics.danger.base);
-    expect(dark.semantics.info.base).toBe(DEFAULT_SEMANTIC_STATUS_COLOR_SEEDS.info);
-    expect(dark.semantics.info.base).not.toBe(dark.semantics.brand.base);
-    expect(light.semantics.error).toBe(light.semantics.danger);
-    expect(dark.semantics.error).toBe(dark.semantics.danger);
-  });
-
-  it('uses mode-aware role semantics for dark mode soft states', () => {
-    const light = generatePalette(mockConfig, 'light');
-    const dark = generatePalette(mockConfig, 'dark');
-
-    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]);
-  });
-
-  it('preserves the primary color at swatch step 500 in light mode', () => {
-    const { swatches } = generatePalette(mockConfig, 'light');
-    expect(String(swatches.primary[500])).toBe(mockConfig.light.primaryColor);
-  });
-
-  it('preserves the primary color at swatch step 500 in dark mode', () => {
-    const { swatches } = generatePalette(mockConfig, 'dark');
-    expect(String(swatches.primary[500])).toBe(mockConfig.dark.primaryColor);
-  });
-
-  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('throws deterministically on invalid primary color', () => {
-    const config = {
-      ...mockConfig,
-      light: { ...mockConfig.light, primaryColor: 'not-a-hex-color' },
-    };
-    expect(() => generatePalette(config, 'light')).toThrow();
-  });
-
-  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('emits required semantic roles for all harmonies', () => {
-    for (const harmony of COLOR_HARMONIES) {
-      const config = {
-        ...mockConfig,
-        light: { ...mockConfig.light, harmony },
-        dark: { ...mockConfig.dark, harmony },
-      };
-      const light = generatePalette(config, 'light');
-      const dark = generatePalette(config, 'dark');
-      expectCompleteSemanticValues(light.semantics);
-      expectCompleteSemanticValues(dark.semantics);
-    }
-  });
-
-  it('resolves canonical semantic references and returns their selected steps', () => {
-    const light = generatePalette(mockConfig, 'light');
-    const dark = generatePalette(mockConfig, 'dark');
-
-    expect(light.colorDiagnostics.semanticReferences).toBe(LIGHT_SEMANTIC_COLOR_REFERENCES);
-    expect(dark.colorDiagnostics.semanticReferences).toBe(DARK_SEMANTIC_COLOR_REFERENCES);
-    expect(light.colorDiagnostics.generated.swatches).toBe(light.swatches);
-    expect(dark.colorDiagnostics.generated.swatches).toBe(dark.swatches);
-  });
-
-  it('returns measured selections and contrast diagnostics for both modes', () => {
-    for (const mode of ['light', 'dark'] as const) {
-      const palette = generatePalette(mockConfig, mode);
-
-      expect(palette.colorDiagnostics.selections.length).toBeGreaterThan(0);
-      expect(
-        palette.colorDiagnostics.selections.every(({ result }) => result.selected !== null),
-      ).toBe(true);
-      expect(palette.colorDiagnostics.contrasts.length).toBeGreaterThan(0);
-      expect(palette.colorDiagnostics.contrasts.every(({ passes }) => passes)).toBe(true);
-      expect(palette.colorDiagnostics.surfaceSeparation.length).toBeGreaterThan(0);
-    }
-  });
-
-  it('reports neutral and surface-separation evidence without hiding failed separation', () => {
-    const palette = generatePalette(mockConfig, 'light');
-    const failedSeparation = palette.colorDiagnostics.surfaceSeparation.find(
-      ({ passes }) => !passes,
-    );
-
-    expect(palette.colorDiagnostics.generated.neutral.neutralKeyColor).toBe(
-      palette.swatches.neutral[500],
-    );
-    expect(palette.colorDiagnostics.generated.neutral.diagnostics.isUsable).toBeBoolean();
-    expect(failedSeparation).toBeDefined();
-    expect(failedSeparation?.contrast).toBeLessThan(failedSeparation?.minimumContrast ?? 0);
-  });
-
-  it('preserves owner diagnostics for achromatic and low-chroma inputs', () => {
-    const achromaticConfig: ThemeConfig = {
-      ...mockConfig,
-      light: { primaryColor: '#777777', harmony: 'square' },
-    };
-    const palette = generatePalette(achromaticConfig, 'light');
-
-    expect(palette.colorDiagnostics.generated.harmonyRoleColors.diagnostics.isHueReliable).toBe(
-      false,
-    );
-    expect(
-      palette.colorDiagnostics.generated.harmonyRoleColors.diagnostics.warnings.length,
-    ).toBeGreaterThan(0);
-    expect(palette.colorDiagnostics.generated.neutral.diagnostics).toBeDefined();
-  });
-
-  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('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('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();
-    }
-  });
-
-  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();
-  });
-
-  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(/^#/);
-  });
-});

package/src/theme/createTheme.ts

@@ -1,60 +0,0 @@
-import { generatePalette } from './colorEngine';
-import { resolveGlobalTokens } from './resolveGlobalTokens';
-import type { FontWeight, SurfaceTheme, ThemeConfig } from './types';
-
-export { DEFAULT_TOKENS } from './defaultTokens';
-
-export const DEFAULT_CONFIG: ThemeConfig = {
-  id: 'default',
-  name: 'Default',
-  light: { primaryColor: '#3B82F6', harmony: 'monochromatic' },
-  dark: { primaryColor: '#3B82F6', harmony: 'monochromatic' },
-};
-
-const ACTIVE_FONT_WEIGHTS: readonly FontWeight[] = [
-  '100',
-  '200',
-  '300',
-  '400',
-  '500',
-  '600',
-  '700',
-  '800',
-  '900',
-];
-
-export function createTheme(
-  config: ThemeConfig = DEFAULT_CONFIG,
-  mode: 'light' | 'dark' = 'light',
-  activeFontId?: string | null,
-): SurfaceTheme {
-  const { colors, swatches, semantics, colorDiagnostics } = generatePalette(config, mode);
-  const theme: SurfaceTheme = {
-    ...resolveGlobalTokens(config.tokens),
-    colors,
-    swatches,
-    semantics,
-    colorDiagnostics,
-    config,
-  };
-
-  applyActiveFont(theme, activeFontId);
-  return theme;
-}
-
-function applyActiveFont(theme: SurfaceTheme, activeFontId: string | null | undefined): void {
-  if (!activeFontId) return;
-
-  const familyName = toPascalCase(activeFontId);
-  for (const weight of ACTIVE_FONT_WEIGHTS) {
-    theme.typography.fonts.normal[weight] = `${familyName}_${weight}Regular`;
-    theme.typography.fonts.italic[weight] = `${familyName}_${weight}Italic`;
-  }
-}
-
-function toPascalCase(value: string): string {
-  return value
-    .split(/[- ]+/)
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join('');
-}

package/src/theme/defaultTokens.ts

@@ -1,61 +0,0 @@
-import type { FontWeight, ThemeTokens } from './types';
-
-const EMPTY_FONT_MAP: Record<FontWeight, string | undefined> = {
-  '100': undefined,
-  '200': undefined,
-  '300': undefined,
-  '400': undefined,
-  '500': undefined,
-  '600': undefined,
-  '700': undefined,
-  '800': undefined,
-  '900': undefined,
-  bold: undefined,
-  normal: undefined,
-};
-
-export const DEFAULT_TOKENS: Omit<
-  ThemeTokens,
-  'colors' | 'swatches' | 'semantics' | 'colorDiagnostics'
-> = {
-  spacing: { none: 0, xs: 4, s: 8, m: 16, l: 24, xl: 32, xxl: 48 },
-  radii: { none: 0, s: 4, m: 8, l: 16, full: 9999 },
-  typography: {
-    headings: {
-      1: { size: 32, lineHeight: 40, weight: 'bold' },
-      2: { size: 24, lineHeight: 32, weight: 'bold' },
-      3: { size: 20, lineHeight: 28, weight: 'bold' },
-      4: { size: 18, lineHeight: 24, weight: 'semiBold' },
-      5: { size: 16, lineHeight: 22, weight: 'semiBold' },
-      6: { size: 14, lineHeight: 20, weight: 'semiBold' },
-    },
-    sizes: {
-      xs: 12,
-      s: 14,
-      m: 16,
-      l: 18,
-      xl: 20,
-      xxl: 24,
-      '3xl': 30,
-      h1: 32,
-      h2: 24,
-      h3: 20,
-      h4: 18,
-      h5: 16,
-      h6: 14,
-    },
-    weights: {
-      thin: '100',
-      extraLight: '200',
-      light: '300',
-      regular: '400',
-      medium: '500',
-      semiBold: '600',
-      bold: '700',
-      extraBold: '800',
-      black: '900',
-    },
-    fonts: { normal: { ...EMPTY_FONT_MAP }, italic: { ...EMPTY_FONT_MAP } },
-  },
-  shadows: { soft: 2, medium: 4, hard: 8 },
-};

package/src/theme/index.ts

@@ -1,2 +0,0 @@
-export * from './public';
-export * from './ThemeContext';

package/src/theme/public.ts

@@ -1,4 +0,0 @@
-export * from './colorEngine';
-export * from './createTheme';
-export * from './resolveToken';
-export * from './types';

package/src/theme/resolveToken.ts

@@ -1,32 +0,0 @@
-/**
- * 1. Define the Conditional Logic
- * If TValue is a key of TMap, return the map's value type.
- * Otherwise, return TValue itself.
- */
-type ResolvedToken<TMap, TValue> = TValue extends keyof TMap ? TMap[TValue] : TValue;
-
-/**
- * 2. The Generic Function
- */
-export function resolveToken<
-  TMap extends Record<string | number, unknown>,
-  TValue extends string | number | undefined,
->(map: TMap, value: TValue): ResolvedToken<TMap, TValue> {
-  // Undefined check
-  if (value === undefined) {
-    return undefined as ResolvedToken<TMap, TValue>;
-  }
-
-  // Runtime check: Is 'value' a key in 'map'?
-  if (
-    (typeof value === 'string' || typeof value === 'number') &&
-    Object.prototype.hasOwnProperty.call(map, value)
-  ) {
-    // Return the mapped token
-    // We cast to the specific conditional type, strictly safer than 'any'
-    return map[value as keyof TMap] as ResolvedToken<TMap, TValue>;
-  }
-
-  // Fallback: Return raw value
-  return value as ResolvedToken<TMap, TValue>;
-}

package/src/theme/surfaceColorPolicy.ts

@@ -1,7 +0,0 @@
-/** Canonical measurable thresholds used while Surface resolves runtime color semantics. */
-export const SURFACE_COLOR_POLICY = {
-  disabledContrast: 3,
-  surfaceSeparation: 1.05,
-  textContrast: 4.5,
-  uiContrast: 3,
-} as const;

package/src/utils/deepEqual.ts

@@ -1,34 +0,0 @@
-/**
- * Simple deep equality check for JSON-serializable objects.
- * Efficient enough for UI manifests.
- */
-export const isDeepEqual = (a: unknown, b: unknown): boolean => {
-  if (a === b) return true;
-
-  if (a && b && typeof a === 'object' && typeof b === 'object') {
-    if (Array.isArray(a)) {
-      if (!Array.isArray(b) || a.length !== b.length) return false;
-      for (let i = 0; i < a.length; i++) {
-        if (!isDeepEqual(a[i], b[i])) return false;
-      }
-      return true;
-    }
-
-    if (Array.isArray(b)) return false;
-
-    const keysA = Object.keys(a);
-    const keysB = Object.keys(b);
-    if (keysA.length !== keysB.length) return false;
-
-    const objA = a as Record<string, unknown>;
-    const objB = b as Record<string, unknown>;
-
-    for (const key of keysA) {
-      if (!Object.prototype.hasOwnProperty.call(objB, key)) return false;
-      if (!isDeepEqual(objA[key], objB[key])) return false;
-    }
-    return true;
-  }
-
-  return Number.isNaN(a) && Number.isNaN(b);
-};