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

package/src/__tests__/theming.test.ts

@@ -0,0 +1,647 @@
+import {
+  presetPatchToUniwindMaps,
+  themeOverrideToUniwindMaps,
+  isSchemaVersionSupported,
+  type RuntimeMap,
+} from '../theming';
+import type { ThemeOverride, TokenGroup } from '../types';
+
+// ---------------------------------------------------------------------------
+// Mock runtime map — representative subset of the generated map
+// ---------------------------------------------------------------------------
+
+const MOCK_RUNTIME_MAP: RuntimeMap = {
+  // Primitives (mode-independent)
+  '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.200': '--color-accent-200',
+  'color.accent.300': '--color-accent-300',
+  'color.accent.400': '--color-accent-400',
+  'color.accent.500': '--color-accent-500',
+  'color.accent.600': '--color-accent-600',
+  'color.accent.700': '--color-accent-700',
+  'color.accent.800': '--color-accent-800',
+  'color.accent.900': '--color-accent-900',
+  'color.accent.950': '--color-accent-950',
+  'color.accent.input': '--color-accent-input',
+  'font.display': '--font-display',
+
+  // Mode-prefixed semantic tokens
+  '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.color.stroke.primary': '--color-stroke-primary',
+  'modes.dark.color.stroke.primary': '--color-stroke-primary',
+  'modes.light.font.display': '--font-display',
+  'modes.dark.font.display': '--font-display',
+  'modes.light.border-radius.button': '--border-radius-button',
+  'modes.dark.border-radius.button': '--border-radius-button',
+  'modes.light.color.surface.action.strong': '--color-surface-action-strong',
+  'modes.dark.color.surface.action.strong': '--color-surface-action-strong',
+  'modes.light.color.content.link': '--color-content-link',
+  'modes.dark.color.content.link': '--color-content-link',
+
+  // Platform-prefixed tokens
+  'platform.web.font.sans': '--font-sans',
+  'platform.ios.font.sans': '--font-sans',
+  'platform.android.font.sans': '--font-sans',
+  'platform.web.font.mono': '--font-mono',
+  'platform.ios.font.mono': '--font-mono',
+  'platform.android.font.mono': '--font-mono',
+};
+
+// ---------------------------------------------------------------------------
+// presetPatchToUniwindMaps
+// ---------------------------------------------------------------------------
+
+describe('presetPatchToUniwindMaps', () => {
+  it('converts a mode-scoped DTCG patch into per-mode variable maps', () => {
+    const patch: TokenGroup = {
+      modes: {
+        light: {
+          color: {
+            surface: {
+              background: { $type: 'color', $value: '#ffffff' },
+            },
+            content: {
+              primary: { $type: 'color', $value: '#1a1a1a' },
+            },
+          },
+        },
+        dark: {
+          color: {
+            surface: {
+              background: { $type: 'color', $value: '#0d0d0d' },
+            },
+            content: {
+              primary: { $type: 'color', $value: '#f5f5f5' },
+            },
+          },
+        },
+      },
+    } as unknown as TokenGroup;
+
+    const result = presetPatchToUniwindMaps(patch, MOCK_RUNTIME_MAP, 'web');
+
+    expect(result.light).toEqual({
+      '--color-surface-background': '#ffffff',
+      '--color-content-primary': '#1a1a1a',
+    });
+    expect(result.dark).toEqual({
+      '--color-surface-background': '#0d0d0d',
+      '--color-content-primary': '#f5f5f5',
+    });
+  });
+
+  it('places mode-independent primitives in BOTH light and dark maps', () => {
+    const patch: TokenGroup = {
+      color: {
+        brand: {
+          '500': { $type: 'color', $value: '#0052cc' },
+        },
+      },
+    } as unknown as TokenGroup;
+
+    const result = presetPatchToUniwindMaps(patch, MOCK_RUNTIME_MAP, 'web');
+
+    expect(result.light['--color-brand-500']).toBe('#0052cc');
+    expect(result.dark['--color-brand-500']).toBe('#0052cc');
+  });
+
+  it('filters platform tokens to only include matching runtimePlatform', () => {
+    const patch: TokenGroup = {
+      platform: {
+        web: {
+          font: {
+            sans: { $type: 'fontFamily', $value: 'Inter' },
+          },
+        },
+        ios: {
+          font: {
+            sans: { $type: 'fontFamily', $value: 'SF Pro' },
+          },
+        },
+        android: {
+          font: {
+            sans: { $type: 'fontFamily', $value: 'Roboto' },
+          },
+        },
+      },
+    } as unknown as TokenGroup;
+
+    const resultWeb = presetPatchToUniwindMaps(patch, MOCK_RUNTIME_MAP, 'web');
+    expect(resultWeb.light['--font-sans']).toBe('Inter');
+    expect(resultWeb.dark['--font-sans']).toBe('Inter');
+
+    const resultIos = presetPatchToUniwindMaps(patch, MOCK_RUNTIME_MAP, 'ios');
+    expect(resultIos.light['--font-sans']).toBe('SF Pro');
+    expect(resultIos.dark['--font-sans']).toBe('SF Pro');
+
+    const resultAndroid = presetPatchToUniwindMaps(patch, MOCK_RUNTIME_MAP, 'android');
+    expect(resultAndroid.light['--font-sans']).toBe('Roboto');
+    expect(resultAndroid.dark['--font-sans']).toBe('Roboto');
+  });
+
+  it('skips non-matching platform tokens', () => {
+    const patch: TokenGroup = {
+      platform: {
+        ios: {
+          font: {
+            mono: { $type: 'fontFamily', $value: 'Menlo' },
+          },
+        },
+      },
+    } as unknown as TokenGroup;
+
+    const result = presetPatchToUniwindMaps(patch, MOCK_RUNTIME_MAP, 'web');
+    expect(result.light['--font-mono']).toBeUndefined();
+    expect(result.dark['--font-mono']).toBeUndefined();
+  });
+
+  it('silently skips dot-paths not found in the runtime map', () => {
+    const patch: TokenGroup = {
+      modes: {
+        light: {
+          some: {
+            unknown: {
+              token: { $type: 'color', $value: '#abc123' },
+            },
+          },
+        },
+      },
+      color: {
+        surface: {
+          background: { $type: 'color', $value: '#ffffff' },
+        },
+      },
+    } as unknown as TokenGroup;
+
+    const result = presetPatchToUniwindMaps(patch, MOCK_RUNTIME_MAP, 'web');
+
+    expect(Object.keys(result.light)).toHaveLength(0);
+    expect(Object.keys(result.dark)).toHaveLength(0);
+  });
+
+  it('handles mixed mode + primitive + platform tokens', () => {
+    const patch: TokenGroup = {
+      color: {
+        brand: {
+          '500': { $type: 'color', $value: '#336699' },
+        },
+      },
+      modes: {
+        light: {
+          color: {
+            stroke: {
+              primary: { $type: 'color', $value: '#e0e0e0' },
+            },
+          },
+        },
+        dark: {
+          color: {
+            stroke: {
+              primary: { $type: 'color', $value: '#333333' },
+            },
+          },
+        },
+      },
+      platform: {
+        ios: {
+          font: {
+            sans: { $type: 'fontFamily', $value: 'SF Pro Display' },
+          },
+        },
+      },
+    } as unknown as TokenGroup;
+
+    const result = presetPatchToUniwindMaps(patch, MOCK_RUNTIME_MAP, 'ios');
+
+    expect(result.light).toEqual({
+      '--color-brand-500': '#336699',
+      '--color-stroke-primary': '#e0e0e0',
+      '--font-sans': 'SF Pro Display',
+    });
+    expect(result.dark).toEqual({
+      '--color-brand-500': '#336699',
+      '--color-stroke-primary': '#333333',
+      '--font-sans': 'SF Pro Display',
+    });
+  });
+
+  it('converts numeric $value to string', () => {
+    const patch: TokenGroup = {
+      modes: {
+        light: {
+          'border-radius': {
+            button: { $type: 'dimension', $value: 8 },
+          },
+        },
+      },
+    } as unknown as TokenGroup;
+
+    const result = presetPatchToUniwindMaps(patch, MOCK_RUNTIME_MAP, 'web');
+    expect(result.light['--border-radius-button']).toBe('8');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// themeOverrideToUniwindMaps
+// ---------------------------------------------------------------------------
+
+describe('themeOverrideToUniwindMaps', () => {
+  const baseOverride: ThemeOverride = {
+    $extensions: {
+      'com.forge.ui.themeOverride': {
+        basePreset: 'poise',
+        schemaVersion: '1.0.0',
+      },
+    },
+  };
+
+  describe('inputs only', () => {
+    it('generates palette from brandPrimary and places in both mode maps', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        inputs: { brandPrimary: '#0052cc' },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-brand-500']).toBeDefined();
+      expect(result.dark['--color-brand-500']).toBeDefined();
+      expect(result.light['--color-brand-input']).toBe('#0052cc');
+      expect(result.dark['--color-brand-input']).toBe('#0052cc');
+      expect(result.light['--color-brand-500']).toBe(result.dark['--color-brand-500']);
+    });
+
+    it('generates palette from accentPrimary', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        inputs: { accentPrimary: '#ff8c42' },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-accent-input']).toBe('#ff8c42');
+      expect(result.dark['--color-accent-input']).toBe('#ff8c42');
+      expect(result.light['--color-accent-500']).toBeDefined();
+    });
+
+    it('maps displayFont to font.display token path in both modes', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        inputs: { displayFont: 'Crimson Pro' },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--font-display']).toBe('Crimson Pro');
+      expect(result.dark['--font-display']).toBe('Crimson Pro');
+    });
+
+    it('handles both colour and font inputs together', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        inputs: {
+          brandPrimary: '#0052cc',
+          displayFont: 'Outfit',
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-brand-input']).toBe('#0052cc');
+      expect(result.light['--font-display']).toBe('Outfit');
+      expect(result.dark['--font-display']).toBe('Outfit');
+    });
+  });
+
+  describe('overrides only', () => {
+    it('maps explicit per-mode overrides to CSS variables', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        overrides: {
+          light: {
+            'color.surface.background': '#fafafa',
+            'color.content.primary': '#111111',
+          },
+          dark: {
+            'color.surface.background': '#1a1a1a',
+            'color.content.primary': '#eeeeee',
+          },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-surface-background']).toBe('#fafafa');
+      expect(result.light['--color-content-primary']).toBe('#111111');
+      expect(result.dark['--color-surface-background']).toBe('#1a1a1a');
+      expect(result.dark['--color-content-primary']).toBe('#eeeeee');
+    });
+
+    it('handles light-only overrides without dark', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        overrides: {
+          light: {
+            'color.surface.background': '#fefefe',
+          },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-surface-background']).toBe('#fefefe');
+      expect(result.dark['--color-surface-background']).toBeUndefined();
+    });
+  });
+
+  describe('inputs + overrides (collision handling)', () => {
+    it('explicit override wins over palette-generated value on collision', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        inputs: { brandPrimary: '#0052cc' },
+        overrides: {
+          light: {
+            'color.brand.500': '#custom1',
+          },
+          dark: {
+            'color.brand.500': '#custom2',
+          },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-brand-500']).toBe('#custom1');
+      expect(result.dark['--color-brand-500']).toBe('#custom2');
+    });
+
+    it('non-colliding palette values coexist with explicit overrides', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        inputs: { brandPrimary: '#0052cc' },
+        overrides: {
+          light: {
+            'color.surface.background': '#ffffff',
+          },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-brand-input']).toBe('#0052cc');
+      expect(result.light['--color-surface-background']).toBe('#ffffff');
+    });
+
+    it('font input survives when override targets different token', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        inputs: { displayFont: 'Crimson Pro' },
+        overrides: {
+          light: {
+            'color.surface.background': '#ffffff',
+          },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--font-display']).toBe('Crimson Pro');
+      expect(result.light['--color-surface-background']).toBe('#ffffff');
+    });
+  });
+
+  describe('metadata-only override', () => {
+    it('returns empty maps when only $extensions is present', () => {
+      const override: ThemeOverride = {
+        $extensions: {
+          'com.forge.ui.themeOverride': {
+            basePreset: 'prestige',
+            schemaVersion: '1.0.0',
+          },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light).toEqual({});
+      expect(result.dark).toEqual({});
+    });
+  });
+
+  describe('unknown input keys', () => {
+    it('silently ignores input keys not in INPUT_TOKEN_MAP', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        inputs: {
+          brandPrimary: '#0052cc',
+          unknownKey: '#ff0000',
+          anotherUnknown: 'SomeFont',
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-brand-input']).toBe('#0052cc');
+      const allVars = Object.values(result.light);
+      expect(allVars).not.toContain('#ff0000');
+    });
+  });
+
+  describe('missing runtime map entries', () => {
+    it('silently skips override dot-paths not found in the runtime map', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        overrides: {
+          light: {
+            'color.surface.background': '#ffffff',
+            'some.unknown.path': '#aaaaaa',
+          },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-surface-background']).toBe('#ffffff');
+      expect(Object.keys(result.light)).toHaveLength(1);
+    });
+  });
+
+  describe('token-reference aliases', () => {
+    it('resolves an alias override to a CSS var() reference', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        overrides: {
+          light: { 'color.surface.action.strong': '{color.brand.700}' },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-surface-action-strong']).toBe('var(--color-brand-700)');
+    });
+
+    it('supports per-mode step shifts (brand.700 light / brand.300 dark)', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        overrides: {
+          light: { 'color.surface.action.strong': '{color.brand.700}' },
+          dark: { 'color.surface.action.strong': '{color.brand.300}' },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-surface-action-strong']).toBe('var(--color-brand-700)');
+      expect(result.dark['--color-surface-action-strong']).toBe('var(--color-brand-300)');
+    });
+
+    it('resolves aliases targeting the accent scale', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        overrides: {
+          light: { 'color.content.link': '{color.accent.600}' },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-content-link']).toBe('var(--color-accent-600)');
+    });
+
+    it('mixes alias and literal values in the same mode', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        overrides: {
+          light: {
+            'color.surface.action.strong': '{color.brand.700}',
+            'color.surface.background': '#F5F7F6',
+          },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-surface-action-strong']).toBe('var(--color-brand-700)');
+      expect(result.light['--color-surface-background']).toBe('#F5F7F6');
+    });
+
+    it('passes a numeric literal through without alias treatment', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        overrides: {
+          light: { 'border-radius.button': 8 },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--border-radius-button']).toBe('8');
+    });
+
+    it('alias override wins over a palette-generated primitive on collision', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        inputs: { brandPrimary: '#0052cc' },
+        overrides: {
+          light: { 'color.brand.500': '{color.brand.700}' },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-brand-500']).toBe('var(--color-brand-700)');
+    });
+
+    it('skips an alias whose referenced primitive is absent from the runtime map', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        overrides: {
+          light: { 'color.surface.background': '{color.brand.999}' },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-surface-background']).toBeUndefined();
+      expect(Object.keys(result.light)).toHaveLength(0);
+    });
+
+    it('skips an alias targeting a non-primitive token (primitive-only constraint)', () => {
+      const override: ThemeOverride = {
+        ...baseOverride,
+        overrides: {
+          // `color.content.primary` exists only as a mode-prefixed semantic
+          // token, not as a resolvable primitive path — so it is not a valid
+          // alias target and resolution skips it.
+          light: { 'color.surface.action.strong': '{color.content.primary}' },
+        },
+      };
+
+      const result = themeOverrideToUniwindMaps(override, MOCK_RUNTIME_MAP, 'web');
+
+      expect(result.light['--color-surface-action-strong']).toBeUndefined();
+      expect(Object.keys(result.light)).toHaveLength(0);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isSchemaVersionSupported
+// ---------------------------------------------------------------------------
+
+describe('isSchemaVersionSupported', () => {
+  it('returns true for supported schema version (1.0.0)', () => {
+    const override: ThemeOverride = {
+      $extensions: {
+        'com.forge.ui.themeOverride': {
+          basePreset: 'poise',
+          schemaVersion: '1.0.0',
+        },
+      },
+    };
+
+    expect(isSchemaVersionSupported(override)).toBe(true);
+  });
+
+  it('returns false for unsupported schema version', () => {
+    const override: ThemeOverride = {
+      $extensions: {
+        'com.forge.ui.themeOverride': {
+          basePreset: 'poise',
+          schemaVersion: '2.0.0',
+        },
+      },
+    };
+
+    expect(isSchemaVersionSupported(override)).toBe(false);
+  });
+
+  it('returns false for empty string version', () => {
+    const override: ThemeOverride = {
+      $extensions: {
+        'com.forge.ui.themeOverride': {
+          basePreset: 'pulse',
+          schemaVersion: '',
+        },
+      },
+    };
+
+    expect(isSchemaVersionSupported(override)).toBe(false);
+  });
+});