@cdx-ui/styles 0.0.1-beta.54 → 0.0.1-beta.56

package/src/__tests__/applyThemeOverride.test.ts

@@ -0,0 +1,488 @@
+import { applyThemeOverride, DEFAULT_PRESET } from '../applyThemeOverride';
+import type { ApplyThemeOverrideResult } from '../applyThemeOverride';
+import type { RuntimeMap } from '../theming';
+import type { ThemeOverride } from '../types';
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+const mockUpdateCSSVariables = jest.fn();
+
+jest.mock('uniwind', () => ({
+  Uniwind: {
+    updateCSSVariables: (...args: unknown[]) => mockUpdateCSSVariables(...args),
+  },
+}));
+
+jest.mock('react-native', () => ({
+  Platform: { OS: 'ios' },
+}));
+
+jest.mock(
+  '../../runtime/prestige-vs-default.json',
+  () => ({
+    modes: {
+      light: {
+        color: {
+          surface: {
+            background: { $type: 'color', $value: '#faf8f5' },
+          },
+        },
+      },
+      dark: {
+        color: {
+          surface: {
+            background: { $type: 'color', $value: '#1c1917' },
+          },
+        },
+      },
+    },
+    platform: {
+      ios: {
+        font: {
+          sans: { $type: 'fontFamily', $value: 'SF Pro Display' },
+        },
+      },
+      web: {
+        font: {
+          sans: { $type: 'fontFamily', $value: 'Libre Franklin' },
+        },
+      },
+    },
+  }),
+  { virtual: true },
+);
+
+jest.mock(
+  '../../runtime/pulse-vs-default.json',
+  () => ({
+    modes: {
+      light: {
+        color: {
+          surface: {
+            background: { $type: 'color', $value: '#f0f4ff' },
+          },
+        },
+      },
+      dark: {
+        color: {
+          surface: {
+            background: { $type: 'color', $value: '#0a0e1a' },
+          },
+        },
+      },
+    },
+  }),
+  { virtual: true },
+);
+
+jest.mock(
+  '../../runtime/token-to-css-var.json',
+  () => ({
+    'color.brand.50': '--color-brand-50',
+    'color.brand.100': '--color-brand-100',
+    'color.brand.200': '--color-brand-200',
+    'color.brand.300': '--color-brand-300',
+    'color.brand.400': '--color-brand-400',
+    'color.brand.500': '--color-brand-500',
+    'color.brand.600': '--color-brand-600',
+    'color.brand.700': '--color-brand-700',
+    'color.brand.800': '--color-brand-800',
+    'color.brand.900': '--color-brand-900',
+    'color.brand.950': '--color-brand-950',
+    'color.brand.input': '--color-brand-input',
+    'color.accent.50': '--color-accent-50',
+    'color.accent.100': '--color-accent-100',
+    'color.accent.500': '--color-accent-500',
+    'color.accent.input': '--color-accent-input',
+    'font.display': '--font-display',
+    'modes.light.color.surface.background': '--color-surface-background',
+    'modes.dark.color.surface.background': '--color-surface-background',
+    'modes.light.color.content.primary': '--color-content-primary',
+    'modes.dark.color.content.primary': '--color-content-primary',
+    'modes.light.font.display': '--font-display',
+    'modes.dark.font.display': '--font-display',
+    'platform.web.font.sans': '--font-sans',
+    'platform.ios.font.sans': '--font-sans',
+    'platform.android.font.sans': '--font-sans',
+  }),
+  { virtual: true },
+);
+
+// ---------------------------------------------------------------------------
+// Test runtime map (used for explicit runtimeMap option tests)
+// ---------------------------------------------------------------------------
+
+const TEST_RUNTIME_MAP: RuntimeMap = {
+  'color.brand.50': '--color-brand-50',
+  'color.brand.100': '--color-brand-100',
+  'color.brand.200': '--color-brand-200',
+  'color.brand.300': '--color-brand-300',
+  'color.brand.400': '--color-brand-400',
+  'color.brand.500': '--color-brand-500',
+  'color.brand.600': '--color-brand-600',
+  'color.brand.700': '--color-brand-700',
+  'color.brand.800': '--color-brand-800',
+  'color.brand.900': '--color-brand-900',
+  'color.brand.950': '--color-brand-950',
+  'color.brand.input': '--color-brand-input',
+  'color.accent.50': '--color-accent-50',
+  'color.accent.100': '--color-accent-100',
+  'color.accent.500': '--color-accent-500',
+  'color.accent.input': '--color-accent-input',
+  'font.display': '--font-display',
+  'modes.light.color.surface.background': '--color-surface-background',
+  'modes.dark.color.surface.background': '--color-surface-background',
+  'modes.light.color.content.primary': '--color-content-primary',
+  'modes.dark.color.content.primary': '--color-content-primary',
+  'modes.light.font.display': '--font-display',
+  'modes.dark.font.display': '--font-display',
+  'platform.web.font.sans': '--font-sans',
+  'platform.ios.font.sans': '--font-sans',
+  'platform.android.font.sans': '--font-sans',
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  mockUpdateCSSVariables.mockClear();
+});
+
+// ---------------------------------------------------------------------------
+// DEFAULT_PRESET
+// ---------------------------------------------------------------------------
+
+describe('DEFAULT_PRESET', () => {
+  it('equals "poise"', () => {
+    expect(DEFAULT_PRESET).toBe('poise');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// applyThemeOverride
+// ---------------------------------------------------------------------------
+
+describe('applyThemeOverride', () => {
+  describe('successful apply (default preset + override)', () => {
+    it('applies brand colour override with default preset', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'poise',
+            schemaVersion: '1.0.0',
+          },
+        },
+        inputs: { brandPrimary: '#0052cc' },
+      };
+
+      const result = applyThemeOverride(override, {
+        runtimeMap: TEST_RUNTIME_MAP,
+        runtimePlatform: 'web',
+      });
+
+      expect(result.applied).toBe(true);
+      if (result.applied) {
+        expect(result.light['--color-brand-input']).toBe('#0052cc');
+        expect(result.dark['--color-brand-input']).toBe('#0052cc');
+        expect(result.light['--color-brand-500']).toBeDefined();
+      }
+      expect(mockUpdateCSSVariables).toHaveBeenCalledTimes(2);
+      expect(mockUpdateCSSVariables).toHaveBeenCalledWith('light', expect.any(Object));
+      expect(mockUpdateCSSVariables).toHaveBeenCalledWith('dark', expect.any(Object));
+    });
+
+    it('applies font input override', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'poise',
+            schemaVersion: '1.0.0',
+          },
+        },
+        inputs: { displayFont: 'Crimson Pro' },
+      };
+
+      const result = applyThemeOverride(override, {
+        runtimeMap: TEST_RUNTIME_MAP,
+        runtimePlatform: 'web',
+      });
+
+      expect(result.applied).toBe(true);
+      if (result.applied) {
+        expect(result.light['--font-display']).toBe('Crimson Pro');
+        expect(result.dark['--font-display']).toBe('Crimson Pro');
+      }
+    });
+
+    it('applies explicit per-mode overrides', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'poise',
+            schemaVersion: '1.0.0',
+          },
+        },
+        overrides: {
+          light: { 'color.surface.background': '#fafafa' },
+          dark: { 'color.surface.background': '#1a1a1a' },
+        },
+      };
+
+      const result = applyThemeOverride(override, {
+        runtimeMap: TEST_RUNTIME_MAP,
+        runtimePlatform: 'web',
+      });
+
+      expect(result.applied).toBe(true);
+      if (result.applied) {
+        expect(result.light['--color-surface-background']).toBe('#fafafa');
+        expect(result.dark['--color-surface-background']).toBe('#1a1a1a');
+      }
+    });
+  });
+
+  describe('non-default preset patch + override', () => {
+    it('applies prestige preset patch before FI override', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'prestige',
+            schemaVersion: '1.0.0',
+          },
+        },
+        inputs: { brandPrimary: '#8b5cf6' },
+      };
+
+      const result = applyThemeOverride(override, {
+        runtimeMap: TEST_RUNTIME_MAP,
+        runtimePlatform: 'ios',
+      });
+
+      expect(result.applied).toBe(true);
+      if (result.applied) {
+        expect(result.light['--color-surface-background']).toBe('#faf8f5');
+        expect(result.dark['--color-surface-background']).toBe('#1c1917');
+        expect(result.light['--color-brand-input']).toBe('#8b5cf6');
+        expect(result.light['--font-sans']).toBe('SF Pro Display');
+      }
+    });
+
+    it('FI override wins over preset patch on collision', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'prestige',
+            schemaVersion: '1.0.0',
+          },
+        },
+        overrides: {
+          light: { 'color.surface.background': '#custom1' },
+          dark: { 'color.surface.background': '#custom2' },
+        },
+      };
+
+      const result = applyThemeOverride(override, {
+        runtimeMap: TEST_RUNTIME_MAP,
+        runtimePlatform: 'web',
+      });
+
+      expect(result.applied).toBe(true);
+      if (result.applied) {
+        expect(result.light['--color-surface-background']).toBe('#custom1');
+        expect(result.dark['--color-surface-background']).toBe('#custom2');
+      }
+    });
+
+    it('applies pulse preset patch with metadata-only override', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'pulse',
+            schemaVersion: '1.0.0',
+          },
+        },
+      };
+
+      const result = applyThemeOverride(override, {
+        runtimeMap: TEST_RUNTIME_MAP,
+        runtimePlatform: 'web',
+      });
+
+      expect(result.applied).toBe(true);
+      if (result.applied) {
+        expect(result.light['--color-surface-background']).toBe('#f0f4ff');
+        expect(result.dark['--color-surface-background']).toBe('#0a0e1a');
+      }
+    });
+  });
+
+  describe('schema version skip', () => {
+    it('returns early without calling Uniwind when schema version is unsupported', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'poise',
+            schemaVersion: '99.0.0',
+          },
+        },
+        inputs: { brandPrimary: '#ff0000' },
+      };
+
+      const result = applyThemeOverride(override, {
+        runtimeMap: TEST_RUNTIME_MAP,
+        runtimePlatform: 'web',
+      });
+
+      expect(result.applied).toBe(false);
+      if (!result.applied) {
+        expect(result.reason).toBe('unsupported_schema_version');
+      }
+      expect(mockUpdateCSSVariables).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('metadata-only override no-op', () => {
+    it('does not call Uniwind when override has only $extensions with default preset', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'poise',
+            schemaVersion: '1.0.0',
+          },
+        },
+      };
+
+      const result = applyThemeOverride(override, {
+        runtimeMap: TEST_RUNTIME_MAP,
+        runtimePlatform: 'web',
+      });
+
+      expect(result.applied).toBe(false);
+      if (!result.applied) {
+        expect(result.reason).toBe('no_theme_changes');
+      }
+      expect(mockUpdateCSSVariables).not.toHaveBeenCalled();
+    });
+
+    it('does not call Uniwind when override has empty inputs/overrides with default preset', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'poise',
+            schemaVersion: '1.0.0',
+          },
+        },
+        inputs: {},
+        overrides: {},
+      };
+
+      const result = applyThemeOverride(override, {
+        runtimeMap: TEST_RUNTIME_MAP,
+        runtimePlatform: 'web',
+      });
+
+      expect(result.applied).toBe(false);
+      if (!result.applied) {
+        expect(result.reason).toBe('no_theme_changes');
+      }
+      expect(mockUpdateCSSVariables).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('default runtimeMap', () => {
+    it('uses bundled token-to-css-var.json when runtimeMap is not provided', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'poise',
+            schemaVersion: '1.0.0',
+          },
+        },
+        inputs: { brandPrimary: '#0052cc' },
+      };
+
+      const result = applyThemeOverride(override, { runtimePlatform: 'web' });
+
+      expect(result.applied).toBe(true);
+      if (result.applied) {
+        expect(result.light['--color-brand-input']).toBe('#0052cc');
+      }
+    });
+  });
+
+  describe('platform auto-detection fallback', () => {
+    it('auto-detects platform from Platform.OS when runtimePlatform is not provided', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'prestige',
+            schemaVersion: '1.0.0',
+          },
+        },
+        inputs: { brandPrimary: '#0052cc' },
+      };
+
+      const result = applyThemeOverride(override) as Extract<
+        ApplyThemeOverrideResult,
+        { applied: true }
+      >;
+
+      expect(result.applied).toBe(true);
+      expect(result.light['--font-sans']).toBe('SF Pro Display');
+    });
+
+    it('falls back to web when react-native is unavailable', () => {
+      jest.resetModules();
+      jest.doMock('react-native', () => {
+        throw new Error('Cannot find module');
+      });
+
+      // Re-import to get fresh module with the new mock
+      const { applyThemeOverride: freshApply } = jest.requireActual('../applyThemeOverride');
+
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'prestige',
+            schemaVersion: '1.0.0',
+          },
+        },
+        inputs: { brandPrimary: '#0052cc' },
+      };
+
+      const result = freshApply(override, { runtimeMap: TEST_RUNTIME_MAP });
+
+      expect(result.applied).toBe(true);
+      if (result.applied) {
+        expect(result.light['--font-sans']).toBe('Libre Franklin');
+      }
+    });
+  });
+
+  describe('when default preset is skipped', () => {
+    it('does not apply preset patch when basePreset is poise', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'poise',
+            schemaVersion: '1.0.0',
+          },
+        },
+        inputs: { brandPrimary: '#0052cc' },
+      };
+
+      const result = applyThemeOverride(override, {
+        runtimeMap: TEST_RUNTIME_MAP,
+        runtimePlatform: 'web',
+      });
+
+      expect(result.applied).toBe(true);
+      if (result.applied) {
+        expect(result.light['--color-surface-background']).toBeUndefined();
+      }
+    });
+  });
+});

package/src/__tests__/generateColorScale.test.ts

@@ -0,0 +1,202 @@
+import { generateColorScale, generatePalettesFromInputs } from '../palette';
+
+const PALETTE_STEPS = [
+  '50',
+  '100',
+  '200',
+  '300',
+  '400',
+  '500',
+  '600',
+  '700',
+  '800',
+  '900',
+  '950',
+] as const;
+
+/**
+ * Calculate WCAG 2.x relative luminance from a hex string.
+ * @see https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+ */
+function relativeLuminance(hex: string): number {
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+
+  const toLinear = (c: number) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+
+/** WCAG 2.x contrast ratio between two hex colours. */
+function contrastRatio(hex1: string, hex2: string): number {
+  const l1 = relativeLuminance(hex1);
+  const l2 = relativeLuminance(hex2);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+// ---------------------------------------------------------------------------
+// generateColorScale
+// ---------------------------------------------------------------------------
+
+describe('generateColorScale', () => {
+  describe('valid hex input → correct 11-step output structure', () => {
+    it('returns all 11 contrast steps plus the input key for brand', () => {
+      const result = generateColorScale('#081728', 'brand');
+
+      for (const step of PALETTE_STEPS) {
+        expect(`color.brand.${step}` in result).toBe(true);
+      }
+      expect('color.brand.input' in result).toBe(true);
+      expect(Object.keys(result)).toHaveLength(12);
+    });
+
+    it('returns all 11 contrast steps plus the input key for accent', () => {
+      const result = generateColorScale('#ffcf23', 'accent');
+
+      for (const step of PALETTE_STEPS) {
+        expect(`color.accent.${step}` in result).toBe(true);
+      }
+      expect('color.accent.input' in result).toBe(true);
+      expect(Object.keys(result)).toHaveLength(12);
+    });
+
+    it('all generated values are valid 7-character hex strings', () => {
+      const result = generateColorScale('#0052cc', 'brand');
+
+      for (const value of Object.values(result)) {
+        expect(value).toMatch(/^#[0-9a-f]{6}$/);
+      }
+    });
+  });
+
+  describe('input preservation', () => {
+    it('preserves the original hex (7-char) verbatim in the input key', () => {
+      const result = generateColorScale('#081728', 'brand');
+      expect(result['color.brand.input']).toBe('#081728');
+    });
+
+    it('normalises shorthand hex (#RGB → #RRGGBB) in the input key', () => {
+      const result = generateColorScale('#F00', 'brand');
+      expect(result['color.brand.input']).toBe('#ff0000');
+    });
+
+    it('lowercases the input hex', () => {
+      const result = generateColorScale('#AABBCC', 'accent');
+      expect(result['color.accent.input']).toBe('#aabbcc');
+    });
+  });
+
+  describe('invalid hex handling', () => {
+    it('throws for a string without leading #', () => {
+      expect(() => generateColorScale('081728', 'brand')).toThrow(TypeError);
+      expect(() => generateColorScale('081728', 'brand')).toThrow(/must be a 4-character/);
+    });
+
+    it('throws for wrong-length hex', () => {
+      expect(() => generateColorScale('#0817', 'brand')).toThrow(TypeError);
+      expect(() => generateColorScale('#08172', 'brand')).toThrow(TypeError);
+      expect(() => generateColorScale('#08172800', 'brand')).toThrow(TypeError);
+    });
+
+    it('throws for non-hex characters', () => {
+      expect(() => generateColorScale('#GGHHII', 'brand')).toThrow(TypeError);
+    });
+
+    it('throws for empty string', () => {
+      expect(() => generateColorScale('', 'brand')).toThrow(TypeError);
+    });
+
+    it('throws for non-string input', () => {
+      expect(() => generateColorScale(123 as unknown as string, 'brand')).toThrow(TypeError);
+    });
+  });
+
+  describe('contrast ratio spot-checks', () => {
+    const WHITE = '#ffffff';
+
+    it('brand palette: step 700 meets WCAG AA for normal text (≥ 4.5:1)', () => {
+      const result = generateColorScale('#081728', 'brand');
+      const ratio = contrastRatio(result['color.brand.700'], WHITE);
+      expect(ratio).toBeGreaterThanOrEqual(4.5);
+    });
+
+    it('brand palette: steps are ordered from lightest (50) to darkest (950)', () => {
+      const result = generateColorScale('#081728', 'brand');
+      const luminances = PALETTE_STEPS.map((step) =>
+        relativeLuminance(result[`color.brand.${step}`]),
+      );
+      for (let i = 1; i < luminances.length; i++) {
+        expect(luminances[i]).toBeLessThanOrEqual(luminances[i - 1]);
+      }
+    });
+
+    it('accent palette: step 700 meets WCAG AA for normal text (≥ 4.5:1)', () => {
+      const result = generateColorScale('#ffcf23', 'accent');
+      const ratio = contrastRatio(result['color.accent.700'], WHITE);
+      expect(ratio).toBeGreaterThanOrEqual(4.5);
+    });
+
+    it('accent palette: step 50 has very low contrast against white (< 1.5:1)', () => {
+      const result = generateColorScale('#ffcf23', 'accent');
+      const ratio = contrastRatio(result['color.accent.50'], WHITE);
+      expect(ratio).toBeLessThan(1.5);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// generatePalettesFromInputs
+// ---------------------------------------------------------------------------
+
+describe('generatePalettesFromInputs', () => {
+  it('generates palettes for both brand and accent colour inputs', () => {
+    const result = generatePalettesFromInputs({
+      brandPrimary: '#0052cc',
+      accentPrimary: '#FF8C42',
+    });
+
+    for (const step of PALETTE_STEPS) {
+      expect(`color.brand.${step}` in result).toBe(true);
+      expect(`color.accent.${step}` in result).toBe(true);
+    }
+    expect(result['color.brand.input']).toBe('#0052cc');
+    expect(result['color.accent.input']).toBe('#ff8c42');
+  });
+
+  it('skips non-colour inputs (e.g. displayFont)', () => {
+    const result = generatePalettesFromInputs({
+      brandPrimary: '#0052cc',
+      displayFont: 'Poppins',
+    });
+
+    expect('color.brand.input' in result).toBe(true);
+    expect(Object.keys(result).every((k) => k.startsWith('color.'))).toBe(true);
+  });
+
+  it('skips colour-input keys with non-string values', () => {
+    const result = generatePalettesFromInputs({
+      brandPrimary: 42 as unknown as string,
+    });
+
+    expect(Object.keys(result)).toHaveLength(0);
+  });
+
+  it('returns an empty object when inputs is empty', () => {
+    const result = generatePalettesFromInputs({});
+    expect(result).toEqual({});
+  });
+
+  it('generates only brand palette when only brandPrimary is provided', () => {
+    const result = generatePalettesFromInputs({
+      brandPrimary: '#081728',
+    });
+
+    expect(Object.keys(result)).toHaveLength(12);
+    for (const key of Object.keys(result)) {
+      expect(key).toMatch(/^color\.brand\./);
+    }
+  });
+});