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

package/src/__tests__/theming.test.ts

@@ -0,0 +1,525 @@
+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',
+
+  // 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);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 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);
+  });
+});

package/src/applyThemeOverride.ts

@@ -0,0 +1,139 @@
+import prestigePatch from '../runtime/prestige-vs-default.json';
+import pulsePatch from '../runtime/pulse-vs-default.json';
+import defaultRuntimeMap from '../runtime/token-to-css-var.json';
+import type { Platform, Preset, ThemeOverride, TokenGroup } from './types';
+import {
+  isSchemaVersionSupported,
+  presetPatchToUniwindMaps,
+  themeOverrideToUniwindMaps,
+  type CssVariableMaps,
+  type RuntimeMap,
+} from './theming';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** The build-time default preset. Apps ship with Poise baked into CSS. */
+export const DEFAULT_PRESET: Preset = 'poise';
+
+// ---------------------------------------------------------------------------
+// Preset patch lookup
+// ---------------------------------------------------------------------------
+
+const PRESET_PATCHES: Record<Preset, TokenGroup | null> = {
+  poise: null,
+  prestige: prestigePatch,
+  pulse: pulsePatch,
+};
+
+// ---------------------------------------------------------------------------
+// Platform detection
+// ---------------------------------------------------------------------------
+
+function detectPlatform(): Platform {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { Platform: RNPlatform } = require('react-native');
+    const os = RNPlatform.OS as string;
+    if (os === 'ios' || os === 'android') return os;
+    return 'web';
+  } catch {
+    return 'web';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Result type
+// ---------------------------------------------------------------------------
+
+export type ApplyThemeOverrideResult =
+  | { applied: true; light: Record<string, string>; dark: Record<string, string> }
+  | { applied: false; reason: 'unsupported_schema_version' | 'no_theme_changes' };
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface ApplyThemeOverrideOptions {
+  runtimeMap?: RuntimeMap;
+  runtimePlatform?: Platform;
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply a `ThemeOverride` end-to-end: schema version gate, preset patch
+ * selection, palette generation, and `Uniwind.updateCSSVariables` calls.
+ *
+ * Encapsulates the full runtime theme application sequence so consuming
+ * apps don't need to orchestrate lower-level utilities or import Uniwind
+ * directly.
+ */
+export function applyThemeOverride(
+  override: ThemeOverride,
+  options: ApplyThemeOverrideOptions = {},
+): ApplyThemeOverrideResult {
+  const { runtimeMap = defaultRuntimeMap, runtimePlatform = detectPlatform() } = options;
+
+  // --- Schema version gate ---
+  if (!isSchemaVersionSupported(override)) {
+    return { applied: false, reason: 'unsupported_schema_version' };
+  }
+
+  const basePreset = override.$extensions['com.forge.ui.themeOverride'].basePreset;
+  const hasInputs = override.inputs !== undefined && Object.keys(override.inputs).length > 0;
+  const hasOverrides =
+    override.overrides !== undefined && Object.keys(override.overrides).length > 0;
+
+  // --- Metadata-only check ---
+  const isDefaultPreset = basePreset === DEFAULT_PRESET;
+  if (isDefaultPreset && !hasInputs && !hasOverrides) {
+    return { applied: false, reason: 'no_theme_changes' };
+  }
+
+  // --- Preset patch step ---
+  let presetMaps: CssVariableMaps = { light: {}, dark: {} };
+  if (!isDefaultPreset) {
+    const patch = PRESET_PATCHES[basePreset];
+    if (patch) {
+      presetMaps = presetPatchToUniwindMaps(patch, runtimeMap, runtimePlatform);
+    }
+  }
+
+  // --- FI override step ---
+  let overrideMaps: CssVariableMaps = { light: {}, dark: {} };
+  if (hasInputs || hasOverrides) {
+    overrideMaps = themeOverrideToUniwindMaps(override, runtimeMap);
+  }
+
+  // --- Merge per mode (FI wins on collision) ---
+  const mergedLight = { ...presetMaps.light, ...overrideMaps.light };
+  const mergedDark = { ...presetMaps.dark, ...overrideMaps.dark };
+
+  // --- Non-default preset with no FI changes still needs patch application ---
+  if (Object.keys(mergedLight).length === 0 && Object.keys(mergedDark).length === 0) {
+    return { applied: false, reason: 'no_theme_changes' };
+  }
+
+  // --- Apply via Uniwind ---
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { Uniwind } = require('uniwind');
+    if (Object.keys(mergedLight).length > 0) {
+      Uniwind.updateCSSVariables('light', mergedLight);
+    }
+    if (Object.keys(mergedDark).length > 0) {
+      Uniwind.updateCSSVariables('dark', mergedDark);
+    }
+  } catch {
+    throw new Error(
+      'applyThemeOverride requires "uniwind" to be installed. ' +
+        'Add it as a dependency in your app.',
+    );
+  }
+
+  return { applied: true, light: mergedLight, dark: mergedDark };
+}