@cdx-ui/styles 0.0.1-beta.8 → 0.0.1-beta.80

package/src/__tests__/applyThemeOverride.test.ts

@@ -0,0 +1,552 @@
+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',
+    'color.base.50': '--color-base-50',
+    'color.base.500': '--color-base-500',
+    'color.base.950': '--color-base-950',
+    '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',
+  'color.base.50': '--color-base-50',
+  'color.base.500': '--color-base-500',
+  'color.base.950': '--color-base-950',
+  '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 a base palette from a basePrimary input', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'poise',
+            schemaVersion: '1.0.0',
+          },
+        },
+        inputs: { brandPrimary: '#0052cc', basePrimary: '#61666c' },
+      };
+
+      const result = applyThemeOverride(override, {
+        runtimeMap: TEST_RUNTIME_MAP,
+        runtimePlatform: 'web',
+      });
+
+      expect(result.applied).toBe(true);
+      if (result.applied) {
+        expect(result.light['--color-base-50']).toBeDefined();
+        expect(result.light['--color-base-500']).toBeDefined();
+        expect(result.dark['--color-base-950']).toBeDefined();
+      }
+    });
+
+    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');
+      }
+    });
+
+    it('resolves alias overrides to var() references end-to-end', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'poise',
+            schemaVersion: '1.0.0',
+          },
+        },
+        inputs: { brandPrimary: '#0052cc' },
+        overrides: {
+          light: { 'color.surface.background': '{color.brand.700}' },
+          dark: { 'color.surface.background': '{color.brand.300}' },
+        },
+      };
+
+      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('var(--color-brand-700)');
+        expect(result.dark['--color-surface-background']).toBe('var(--color-brand-300)');
+        // The referenced primitive is present in the same batch (palette
+        // generation emitted it), so the var() reference resolves.
+        expect(result.light['--color-brand-700']).toBeDefined();
+      }
+      expect(mockUpdateCSSVariables).toHaveBeenCalledWith(
+        'light',
+        expect.objectContaining({ '--color-surface-background': 'var(--color-brand-700)' }),
+      );
+    });
+  });
+
+  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();
+      }
+    });
+  });
+});