@cdx-ui/styles 0.0.1-beta.9 → 0.0.1-beta.91

package/src/__tests__/types.test.ts

@@ -0,0 +1,72 @@
+import {
+  OVERRIDE_SCHEMA_VERSION,
+  SUPPORTED_OVERRIDE_SCHEMA_VERSIONS,
+  INPUT_TOKEN_MAP,
+  presetFonts,
+} from '../types';
+import type { Preset } from '../types';
+
+describe('OVERRIDE_SCHEMA_VERSION', () => {
+  it('is the current 1.0.0 schema version', () => {
+    expect(OVERRIDE_SCHEMA_VERSION).toBe('1.0.0');
+  });
+
+  it('matches semver MAJOR.MINOR.PATCH shape', () => {
+    expect(OVERRIDE_SCHEMA_VERSION).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+});
+
+describe('SUPPORTED_OVERRIDE_SCHEMA_VERSIONS', () => {
+  it('includes the current OVERRIDE_SCHEMA_VERSION', () => {
+    expect(SUPPORTED_OVERRIDE_SCHEMA_VERSIONS).toContain(OVERRIDE_SCHEMA_VERSION);
+  });
+
+  it('is a non-empty array of semver strings', () => {
+    expect(Array.isArray(SUPPORTED_OVERRIDE_SCHEMA_VERSIONS)).toBe(true);
+    expect(SUPPORTED_OVERRIDE_SCHEMA_VERSIONS.length).toBeGreaterThan(0);
+    for (const v of SUPPORTED_OVERRIDE_SCHEMA_VERSIONS) {
+      expect(v).toMatch(/^\d+\.\d+\.\d+$/);
+    }
+  });
+});
+
+describe('INPUT_TOKEN_MAP', () => {
+  it('maps every known input key to a dotted token path', () => {
+    expect(INPUT_TOKEN_MAP).toEqual({
+      brandPrimary: 'color.brand',
+      accentPrimary: 'color.accent',
+      basePrimary: 'color.base',
+      displayFont: 'font.display',
+    });
+  });
+
+  it('uses dotted-path token namespaces for every value', () => {
+    for (const value of Object.values(INPUT_TOKEN_MAP)) {
+      expect(value).toMatch(/^[a-z]+(\.[a-z]+)+$/);
+    }
+  });
+});
+
+describe('presetFonts', () => {
+  const expectedPresets: Preset[] = ['poise', 'prestige', 'pulse'];
+
+  it('exposes exactly the three built-in presets as keys', () => {
+    expect(Object.keys(presetFonts).sort()).toEqual([...expectedPresets].sort());
+  });
+
+  it.each(expectedPresets)('declares 3 display font families for %s', (preset) => {
+    expect(presetFonts[preset]).toHaveLength(3);
+    for (const family of presetFonts[preset]) {
+      expect(typeof family).toBe('string');
+      expect(family.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('matches the canonical preset → families map', () => {
+    expect(presetFonts).toEqual({
+      poise: ['Crimson Pro', 'Bitter', 'DM Sans'],
+      prestige: ['Libre Caslon Text', 'Cormorant', 'Libre Franklin'],
+      pulse: ['Outfit', 'Manrope', 'Public Sans'],
+    });
+  });
+});

package/src/__tests__/useCdxFonts.test.ts

@@ -0,0 +1,27 @@
+/* eslint-disable @typescript-eslint/no-deprecated -- this entire test exercises the deprecated alias intentionally */
+import { useFonts } from 'expo-font';
+import * as useCdxFontsModule from '../useCdxFonts';
+import * as useForgeFontsModule from '../useForgeFonts';
+
+jest.mock('react-native', () => ({
+  Platform: { OS: 'ios' },
+}));
+
+jest.mock('expo-font', () => ({
+  useFonts: jest.fn(() => [true, null]),
+}));
+
+const mockedUseFonts = useFonts as jest.MockedFunction<typeof useFonts>;
+
+describe('useCdxFonts', () => {
+  it('re-exports useForgeFonts as the exact same function (deprecated alias)', () => {
+    expect(useCdxFontsModule.useCdxFonts).toBe(useForgeFontsModule.useForgeFonts);
+  });
+
+  it('invokes the underlying useFonts when called', () => {
+    mockedUseFonts.mockClear();
+    const result = useCdxFontsModule.useCdxFonts();
+    expect(mockedUseFonts).toHaveBeenCalledTimes(1);
+    expect(result).toEqual({ loaded: true, error: null });
+  });
+});

package/src/__tests__/useForgeFonts.test.ts

@@ -0,0 +1,226 @@
+/**
+ * `useForgeFonts` decides which web-only fonts to bundle at *module evaluation*
+ * time (the `webFonts` const reads `Platform.OS` once). To exercise both
+ * branches we re-require the module under `jest.isolateModules` with a fresh
+ * `react-native` mock per case.
+ */
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface CallResult {
+  hookResult: { loaded: boolean; error: Error | null };
+  capturedMap: Record<string, unknown>;
+  mockUseFonts: jest.Mock;
+}
+
+function setupAndCall(opts: {
+  platformOS: 'ios' | 'android' | 'web';
+  result?: [boolean, Error | null];
+}): CallResult {
+  const result: [boolean, Error | null] = opts.result ?? [true, null];
+  const mockUseFonts = jest.fn((_map: Record<string, unknown>) => result);
+
+  let hookResult: CallResult['hookResult'] = { loaded: false, error: null };
+
+  jest.isolateModules(() => {
+    jest.doMock('react-native', () => ({ Platform: { OS: opts.platformOS } }));
+    jest.doMock('expo-font', () => ({ useFonts: mockUseFonts }));
+
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require('../useForgeFonts') as typeof import('../useForgeFonts');
+    hookResult = mod.useForgeFonts();
+  });
+
+  const capturedMap: Record<string, unknown> = mockUseFonts.mock.calls[0][0];
+
+  return { hookResult, capturedMap, mockUseFonts };
+}
+
+// Expected display font keys — every preset, every weight, every italic variant.
+// Mirrors the `displayFonts` map in `useForgeFonts.ts`.
+const POISE_DISPLAY_FONT_KEYS = [
+  'Crimson Pro',
+  'Crimson Pro Medium',
+  'Crimson Pro SemiBold',
+  'Crimson Pro Bold',
+  'Crimson Pro Italic',
+  'Crimson Pro Medium Italic',
+  'Crimson Pro SemiBold Italic',
+  'Crimson Pro Bold Italic',
+  'Bitter',
+  'Bitter Medium',
+  'Bitter SemiBold',
+  'Bitter Bold',
+  'Bitter Italic',
+  'Bitter Medium Italic',
+  'Bitter SemiBold Italic',
+  'Bitter Bold Italic',
+  'DM Sans',
+  'DM Sans Medium',
+  'DM Sans SemiBold',
+  'DM Sans Bold',
+  'DM Sans Italic',
+  'DM Sans Medium Italic',
+  'DM Sans SemiBold Italic',
+  'DM Sans Bold Italic',
+];
+
+const PRESTIGE_DISPLAY_FONT_KEYS = [
+  'Libre Caslon Text',
+  'Libre Caslon Text Medium',
+  'Libre Caslon Text SemiBold',
+  'Libre Caslon Text Bold',
+  'Libre Caslon Text Italic',
+  'Libre Caslon Text Medium Italic',
+  'Libre Caslon Text SemiBold Italic',
+  'Libre Caslon Text Bold Italic',
+  'Cormorant',
+  'Cormorant Medium',
+  'Cormorant SemiBold',
+  'Cormorant Bold',
+  'Cormorant Italic',
+  'Cormorant Medium Italic',
+  'Cormorant SemiBold Italic',
+  'Cormorant Bold Italic',
+  'Libre Franklin',
+  'Libre Franklin Medium',
+  'Libre Franklin SemiBold',
+  'Libre Franklin Bold',
+  'Libre Franklin Italic',
+  'Libre Franklin Medium Italic',
+  'Libre Franklin SemiBold Italic',
+  'Libre Franklin Bold Italic',
+];
+
+const PULSE_DISPLAY_FONT_KEYS = [
+  'Outfit',
+  'Outfit Medium',
+  'Outfit SemiBold',
+  'Outfit Bold',
+  'Outfit Italic',
+  'Outfit Medium Italic',
+  'Outfit SemiBold Italic',
+  'Outfit Bold Italic',
+  'Manrope',
+  'Manrope Medium',
+  'Manrope SemiBold',
+  'Manrope Bold',
+  'Manrope Italic',
+  'Manrope Medium Italic',
+  'Manrope SemiBold Italic',
+  'Manrope Bold Italic',
+  'Public Sans',
+  'Public Sans Medium',
+  'Public Sans SemiBold',
+  'Public Sans Bold',
+  'Public Sans Italic',
+  'Public Sans Medium Italic',
+  'Public Sans SemiBold Italic',
+  'Public Sans Bold Italic',
+];
+
+const ALL_DISPLAY_FONT_KEYS = [
+  ...POISE_DISPLAY_FONT_KEYS,
+  ...PRESTIGE_DISPLAY_FONT_KEYS,
+  ...PULSE_DISPLAY_FONT_KEYS,
+];
+
+const WEB_ONLY_FONT_KEYS = [
+  'Inter',
+  'Inter Medium',
+  'Inter SemiBold',
+  'Inter Bold',
+  'Inter Italic',
+  'Inter Medium Italic',
+  'Inter SemiBold Italic',
+  'Inter Bold Italic',
+  'IBM Plex Mono',
+  'IBM Plex Mono Medium',
+  'IBM Plex Mono SemiBold',
+  'IBM Plex Mono Bold',
+  'IBM Plex Mono Italic',
+  'IBM Plex Mono Medium Italic',
+  'IBM Plex Mono SemiBold Italic',
+  'IBM Plex Mono Bold Italic',
+];
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('useForgeFonts', () => {
+  describe('return shape', () => {
+    it('returns { loaded, error } in the loaded state', () => {
+      const { hookResult } = setupAndCall({ platformOS: 'ios', result: [true, null] });
+      expect(hookResult).toEqual({ loaded: true, error: null });
+    });
+
+    it('returns { loaded: false, error: null } while still loading', () => {
+      const { hookResult } = setupAndCall({ platformOS: 'ios', result: [false, null] });
+      expect(hookResult).toEqual({ loaded: false, error: null });
+    });
+
+    it('propagates the error from useFonts', () => {
+      const err = new Error('boom');
+      const { hookResult } = setupAndCall({ platformOS: 'ios', result: [false, err] });
+      expect(hookResult.loaded).toBe(false);
+      expect(hookResult.error).toBe(err);
+    });
+  });
+
+  describe('font map (display fonts)', () => {
+    it.each(['ios', 'android', 'web'] as const)(
+      'passes every display font (Poise + Prestige + Pulse) when Platform.OS is %s',
+      (platformOS) => {
+        const { capturedMap } = setupAndCall({ platformOS });
+        for (const key of ALL_DISPLAY_FONT_KEYS) {
+          expect(capturedMap).toHaveProperty(key);
+        }
+      },
+    );
+
+    it('passes 72 display font keys (24 per preset × 3 presets)', () => {
+      const { capturedMap } = setupAndCall({ platformOS: 'ios' });
+      const displayKeys = Object.keys(capturedMap).filter((k) => !WEB_ONLY_FONT_KEYS.includes(k));
+      expect(displayKeys).toHaveLength(ALL_DISPLAY_FONT_KEYS.length);
+    });
+  });
+
+  describe('web-only fonts', () => {
+    it('excludes Inter and IBM Plex Mono on ios', () => {
+      const { capturedMap } = setupAndCall({ platformOS: 'ios' });
+      for (const key of WEB_ONLY_FONT_KEYS) {
+        expect(capturedMap).not.toHaveProperty(key);
+      }
+    });
+
+    it('excludes Inter and IBM Plex Mono on android', () => {
+      const { capturedMap } = setupAndCall({ platformOS: 'android' });
+      for (const key of WEB_ONLY_FONT_KEYS) {
+        expect(capturedMap).not.toHaveProperty(key);
+      }
+    });
+
+    it('includes every Inter and IBM Plex Mono weight/italic on web', () => {
+      const { capturedMap } = setupAndCall({ platformOS: 'web' });
+      for (const key of WEB_ONLY_FONT_KEYS) {
+        expect(capturedMap).toHaveProperty(key);
+      }
+    });
+
+    it('still passes display fonts alongside web fonts when on web', () => {
+      const { capturedMap } = setupAndCall({ platformOS: 'web' });
+      const totalKeys = Object.keys(capturedMap);
+      expect(totalKeys).toHaveLength(ALL_DISPLAY_FONT_KEYS.length + WEB_ONLY_FONT_KEYS.length);
+    });
+  });
+
+  describe('useFonts invocation', () => {
+    it('calls useFonts exactly once per hook call', () => {
+      const { mockUseFonts } = setupAndCall({ platformOS: 'ios' });
+      expect(mockUseFonts).toHaveBeenCalledTimes(1);
+    });
+  });
+});

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 };
+}

package/src/index.ts

@@ -1,73 +1,49 @@
 // ---------------------------------------------------------------------------
-// Types
+// Types & Constants
 // ---------------------------------------------------------------------------
 
-/** A DTCG token leaf node. */
-export interface TokenValue {
-  $type: string;
-  $value: string | number;
-  $extensions?: Record<string, unknown>;
-}
+export {
+  OVERRIDE_SCHEMA_VERSION,
+  SUPPORTED_OVERRIDE_SCHEMA_VERSIONS,
+  INPUT_TOKEN_MAP,
+  presetFonts,
+} from './types';
+export type {
+  TokenValue,
+  TokenGroup,
+  Preset,
+  ThemeMetadata,
+  ThemeOverrideMetadata,
+  ThemeObject,
+  ThemeOverride,
+  Mode,
+  Platform,
+} from './types';
 
-/** Recursive token group — every non-leaf node in a theme object. */
-export interface TokenGroup {
-  [key: string]: TokenValue | TokenGroup;
-}
-
-/** Theme metadata stored under `$extensions.com.candescent.theme`. */
-export interface ThemeMetadata {
-  name: string;
-  preset: string;
-  schemaVersion: string;
-}
-
-/** Override metadata stored under `$extensions.com.candescent.themeOverride`. */
-export interface ThemeOverrideMetadata {
-  basePreset: string;
-  fiId: string;
-  fiName: string;
-  schemaVersion: string;
-}
+// ---------------------------------------------------------------------------
+// Palette generation
+// ---------------------------------------------------------------------------
 
-/**
- * A complete CDX UI theme object (DTCG-compatible).
- *
- * Presets (Poise, Prestige, Pulse) are full theme objects. At runtime the
- * build-time default preset is augmented by FI overrides via
- * `applyThemeOverrides`.
- */
-export type ThemeObject = TokenGroup & {
-  $extensions: {
-    'com.candescent.theme': ThemeMetadata;
-    [key: string]: unknown;
-  };
-  modes: {
-    light: TokenGroup;
-    dark: TokenGroup;
-  };
-  platform: {
-    web: TokenGroup;
-    ios: TokenGroup;
-    android: TokenGroup;
-  };
-};
+export { generateColorScale, generatePalettesFromInputs, deriveBaseColorKey } from './palette';
+export type { PaletteCategory, PaletteScale, PaletteStep, PaletteTokenMap } from './palette';
 
-/**
- * A theme override — a strict subset of the theme object schema containing
- * only the token paths that differ from the base preset.
- */
-export type ThemeOverride = TokenGroup & {
-  $extensions?: {
-    'com.candescent.themeOverride'?: ThemeOverrideMetadata;
-    [key: string]: unknown;
-  };
-};
+// ---------------------------------------------------------------------------
+// Theming utilities
+// ---------------------------------------------------------------------------
 
-export type Mode = 'light' | 'dark';
-export type Platform = 'web' | 'ios' | 'android';
+export {
+  isSchemaVersionSupported,
+  presetPatchToUniwindMaps,
+  themeOverrideToUniwindMaps,
+  applyThemeOverride,
+  DEFAULT_PRESET,
+} from './theming';
+export type { CssVariableMaps, RuntimeMap } from './theming';
+export type { ApplyThemeOverrideOptions, ApplyThemeOverrideResult } from './applyThemeOverride';
 
 // ---------------------------------------------------------------------------
 // Hooks
 // ---------------------------------------------------------------------------
 
+export { useForgeFonts } from './useForgeFonts';
 export { useCdxFonts } from './useCdxFonts';