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

package/src/index.ts

@@ -1,115 +1,45 @@
 // ---------------------------------------------------------------------------
-// Types
+// Types & Constants
 // ---------------------------------------------------------------------------
 
-/** A DTCG token leaf node. */
-export interface TokenValue {
-  $type: string;
-  $value: string | number;
-  $extensions?: Record<string, unknown>;
-}
-
-/** Recursive token group — every non-leaf node in a theme object. */
-export interface TokenGroup {
-  [key: string]: TokenValue | TokenGroup;
-}
-
-/** The three built-in Forge UI theme presets. */
-export type Preset = 'poise' | 'prestige' | 'pulse';
-
-/** Theme metadata stored under `$extensions.com.forge.ui.theme`. */
-export interface ThemeMetadata {
-  name: string;
-  preset: Preset;
-  schemaVersion: string;
-}
-
-/** Override metadata stored under `$extensions.com.forge.ui.themeOverride`. */
-export interface ThemeOverrideMetadata {
-  basePreset: Preset;
-  schemaVersion: string;
-}
-
-/**
- * A complete Forge 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.forge.ui.theme': ThemeMetadata;
-    [key: string]: unknown;
-  };
-  modes: {
-    light: TokenGroup;
-    dark: TokenGroup;
-  };
-  platform: {
-    web: TokenGroup;
-    ios: TokenGroup;
-    android: TokenGroup;
-  };
-};
-
-/**
- * A theme override using the hybrid input + semantic structure.
- *
- * - `inputs` — flat map of abstract FI-selected brand values (e.g.
- *   `brandPrimary`, `displayFont`). Palette generation expands these into
- *   full token scales at runtime.
- * - `overrides` — per-mode flat maps of token dot-paths to resolved values
- *   for direct semantic token overrides beyond what inputs generate.
- * - `$extensions` — required metadata including base preset and schema version.
- */
-export interface ThemeOverride {
-  $extensions: {
-    'com.forge.ui.themeOverride': ThemeOverrideMetadata;
-    [key: string]: unknown;
-  };
-  inputs?: Record<string, string | number>;
-  overrides?: Partial<Record<Mode, Record<string, string | number>>>;
-}
-
-export type Mode = 'light' | 'dark';
-export type Platform = 'web' | 'ios' | 'android';
+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';
 
 // ---------------------------------------------------------------------------
-// Constants
+// Palette generation
 // ---------------------------------------------------------------------------
 
-/** Current override schema version. Consuming apps gate compatibility on this. */
-export const OVERRIDE_SCHEMA_VERSION = '1.0.0' as const;
-
-/**
- * Schema versions that consuming apps accept. Includes the current version and
- * may include the immediately prior version during transition windows.
- * @see docs/internal/token-architecture/16-override-structure.md § 4
- */
-export const SUPPORTED_OVERRIDE_SCHEMA_VERSIONS: readonly string[] = ['1.0.0'] as const;
+export { generateColorScale, generatePalettesFromInputs } from './palette';
+export type { PaletteCategory, PaletteScale, PaletteStep, PaletteTokenMap } from './palette';
 
-/**
- * Schema-level mapping from known input keys to the token path pattern each
- * affects. Used by override application (S5) to route inputs to the correct
- * palette/token namespace. Distinct from the full runtime map (S3).
- */
-export const INPUT_TOKEN_MAP = {
-  brandPrimary: 'color.brand',
-  accentPrimary: 'color.accent',
-  basePrimary: 'color.base',
-  displayFont: 'font.display',
-} as const satisfies Record<string, string>;
+// ---------------------------------------------------------------------------
+// Theming utilities
+// ---------------------------------------------------------------------------
 
-/**
- * Allowed display font families per preset, consumed by the theme editor for
- * font selection and by consuming apps for validation.
- */
-export const presetFonts: Record<Preset, readonly string[]> = {
-  poise: ['Crimson Pro', 'Bitter', 'DM Sans'],
-  prestige: ['Libre Caslon Text', 'Cormorant', 'Libre Franklin'],
-  pulse: ['Outfit', 'Manrope', 'Public Sans'],
-} as const;
+export {
+  isSchemaVersionSupported,
+  presetPatchToUniwindMaps,
+  themeOverrideToUniwindMaps,
+  applyThemeOverride,
+  DEFAULT_PRESET,
+} from './theming';
+export type { CssVariableMaps, RuntimeMap } from './theming';
+export type { ApplyThemeOverrideOptions, ApplyThemeOverrideResult } from './applyThemeOverride';
 
 // ---------------------------------------------------------------------------
 // Hooks

package/src/palette.ts

@@ -0,0 +1,226 @@
+import { BackgroundColor, Color, Theme, type CssColor } from '@adobe/leonardo-contrast-colors';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Palette step keys produced by `generateColorScale`. */
+export type PaletteStep =
+  | '50'
+  | '100'
+  | '200'
+  | '300'
+  | '400'
+  | '500'
+  | '600'
+  | '700'
+  | '800'
+  | '900'
+  | '950'
+  | 'input';
+
+/** Token category that supports palette generation. */
+export type PaletteCategory = 'brand' | 'accent';
+
+/** Map of palette step → resolved hex color. */
+export type PaletteScale = Record<PaletteStep, string>;
+
+/** Map of token dot-path → resolved hex color (e.g. `color.brand.500` → `#548cdc`). */
+export type PaletteTokenMap = Record<string, string>;
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const REFERENCE_BACKGROUND = '#ffffff';
+
+const PALETTE_STEPS = [
+  '50',
+  '100',
+  '200',
+  '300',
+  '400',
+  '500',
+  '600',
+  '700',
+  '800',
+  '900',
+  '950',
+] as const;
+
+/**
+ * Contrast ratios for each palette step against white (#ffffff).
+ *
+ * Step 700 targets WCAG AA for normal text (≥ 4.5:1).
+ */
+const CONTRAST_RATIOS: Record<(typeof PALETTE_STEPS)[number], number> = {
+  '50': 1.04,
+  '100': 1.16,
+  '200': 1.46,
+  '300': 1.85,
+  '400': 2.45,
+  '500': 3.4,
+  '600': 4.8,
+  '700': 6.4,
+  '800': 8.6,
+  '900': 12,
+  '950': 16.8,
+};
+
+const HEX_REGEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate and normalise a hex color string.
+ *
+ * Accepts `#RGB` (4 chars) or `#RRGGBB` (7 chars). Throws a descriptive
+ * `TypeError` for any other input.
+ *
+ * @returns The normalised 7-character hex string (e.g. `#aabbcc`).
+ */
+function validateHex(hex: string): CssColor {
+  if (typeof hex !== 'string') {
+    throw new TypeError(`Invalid hex color: expected a string, received ${typeof hex}`);
+  }
+
+  if (!HEX_REGEX.test(hex)) {
+    throw new TypeError(
+      `Invalid hex color "${hex}": must be a 4-character (#RGB) or 7-character (#RRGGBB) hex string starting with "#"`,
+    );
+  }
+
+  if (hex.length === 4) {
+    const [, r, g, b] = hex;
+    return `#${r}${r}${g}${g}${b}${b}`.toLowerCase() as CssColor;
+  }
+
+  return hex.toLowerCase() as CssColor;
+}
+
+// ---------------------------------------------------------------------------
+// Core generation — wraps Leonardo behind a thin interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate an 11-step contrast-based color scale from a single hex color.
+ *
+ * Uses `@adobe/leonardo-contrast-colors` internally. The generation algorithm
+ * is wrapped behind this function so the underlying library is swappable
+ * without changing the public API.
+ *
+ * @param hex  - A valid hex color string (`#RGB` or `#RRGGBB`).
+ * @param category - The token namespace (`'brand'` or `'accent'`).
+ * @returns A `PaletteTokenMap` keyed by token dot-paths
+ *   (e.g. `"color.brand.50"` through `"color.brand.950"` plus `"color.brand.input"`).
+ */
+export function generateColorScale(hex: string, category: PaletteCategory): PaletteTokenMap {
+  const normalised = validateHex(hex);
+
+  const ratiosObject: Record<string, number> = {};
+  for (const step of PALETTE_STEPS) {
+    ratiosObject[step] = CONTRAST_RATIOS[step];
+  }
+
+  const color = new Color({
+    name: 'palette',
+    colorKeys: [normalised],
+    colorSpace: 'CAM02p',
+    ratios: ratiosObject,
+    smooth: true,
+    output: 'HEX',
+  });
+
+  const bg = new BackgroundColor({
+    name: 'background',
+    colorKeys: [REFERENCE_BACKGROUND],
+    colorSpace: 'CAM02p',
+    smooth: true,
+    ratios: [],
+    output: 'HEX',
+  });
+
+  const theme = new Theme({
+    colors: [color],
+    backgroundColor: bg,
+    lightness: 100,
+    contrast: 1,
+    saturation: 100,
+    output: 'HEX',
+    formula: 'wcag2',
+  });
+
+  const pairs = theme.contrastColorPairs;
+
+  const tokenPrefix = `color.${category}`;
+  const result: PaletteTokenMap = {};
+
+  for (const step of PALETTE_STEPS) {
+    result[`${tokenPrefix}.${step}`] = pairs[step].toLowerCase();
+  }
+
+  result[`${tokenPrefix}.input`] = normalised;
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Convenience wrapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Colour-input keys whose token path starts with `color.` — these trigger
+ * palette generation. Mirrors the colour entries from `INPUT_TOKEN_MAP`
+ * (defined in the package barrel) without creating a circular import.
+ *
+ * Keep in sync with `INPUT_TOKEN_MAP` in `./index.ts`.
+ */
+const COLOR_INPUT_ENTRIES: readonly (readonly [string, string])[] = [
+  ['brandPrimary', 'color.brand'],
+  ['accentPrimary', 'color.accent'],
+] as const;
+
+/**
+ * Generate palettes for all colour inputs in a theme override `inputs` object.
+ *
+ * Iterates over known colour-input keys that map to a `color.*` token
+ * namespace. For each matching key present in `inputs`, runs
+ * `generateColorScale` and merges the results into a single flat map of
+ * token dot-paths to hex values — ready for the S5 override application
+ * merge step.
+ *
+ * Non-colour inputs (e.g. `displayFont`) are silently skipped.
+ *
+ * @param inputs - The `inputs` object from a `ThemeOverride`.
+ * @returns A merged `Record<string, string>` of all generated token
+ *   dot-paths to hex values.
+ *
+ * @example
+ * ```ts
+ * const inputs = { brandPrimary: '#0052cc', accentPrimary: '#FF8C42', displayFont: 'Poppins' };
+ * const result = generatePalettesFromInputs(inputs);
+ * // {
+ * //   "color.brand.50": "#...", …, "color.brand.input": "#0052cc",
+ * //   "color.accent.50": "#...", …, "color.accent.input": "#ff8c42"
+ * // }
+ * ```
+ */
+export function generatePalettesFromInputs(
+  inputs: Record<string, string | number>,
+): PaletteTokenMap {
+  const result: PaletteTokenMap = {};
+
+  for (const [inputKey, tokenPath] of COLOR_INPUT_ENTRIES) {
+    const value = inputs[inputKey];
+    if (typeof value !== 'string') continue;
+
+    const category = tokenPath.replace('color.', '') as PaletteCategory;
+    const scale = generateColorScale(value, category);
+
+    Object.assign(result, scale);
+  }
+
+  return result;
+}

package/src/theming.ts

@@ -0,0 +1,230 @@
+import { generatePalettesFromInputs } from './palette';
+import {
+  INPUT_TOKEN_MAP,
+  SUPPORTED_OVERRIDE_SCHEMA_VERSIONS,
+  type Mode,
+  type Platform,
+  type ThemeOverride,
+  type TokenGroup,
+  type TokenValue,
+} from './types';
+
+// ---------------------------------------------------------------------------
+// Re-export orchestrator
+// ---------------------------------------------------------------------------
+
+export { applyThemeOverride, DEFAULT_PRESET } from './applyThemeOverride';
+export type { ApplyThemeOverrideOptions, ApplyThemeOverrideResult } from './applyThemeOverride';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Per-mode CSS variable maps ready for `Uniwind.updateCSSVariables`. */
+export interface CssVariableMaps {
+  light: Record<string, string>;
+  dark: Record<string, string>;
+}
+
+/** Runtime map: token dot-paths → CSS custom property names. */
+export type RuntimeMap = Record<string, string>;
+
+// ---------------------------------------------------------------------------
+// Schema version gate
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a `ThemeOverride`'s schema version is supported by the current
+ * build of `@cdx-ui/styles`.
+ */
+export function isSchemaVersionSupported(override: ThemeOverride): boolean {
+  const version = override.$extensions['com.forge.ui.themeOverride'].schemaVersion;
+  return SUPPORTED_OVERRIDE_SCHEMA_VERSIONS.includes(version);
+}
+
+// ---------------------------------------------------------------------------
+// DTCG tree walker
+// ---------------------------------------------------------------------------
+
+function isTokenValue(node: unknown): node is TokenValue {
+  return typeof node === 'object' && node !== null && '$value' in node && '$type' in node;
+}
+
+/**
+ * Recursively walk a nested DTCG object and collect all `$value` leaves with
+ * their full dot-path.
+ */
+function flattenDtcg(
+  node: TokenGroup,
+  prefix: string,
+  result: Record<string, string | number>,
+): void {
+  for (const key of Object.keys(node)) {
+    if (key.startsWith('$')) continue;
+
+    const child = node[key];
+    const path = prefix ? `${prefix}.${key}` : key;
+
+    if (isTokenValue(child)) {
+      result[path] = child.$value;
+    } else if (typeof child === 'object' && child !== null) {
+      flattenDtcg(child, path, result);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shared mode-bucketing
+// ---------------------------------------------------------------------------
+
+function bucketByMode(
+  flatTokens: Record<string, string | number>,
+  runtimeMap: RuntimeMap,
+  runtimePlatform: Platform,
+): CssVariableMaps {
+  const light: Record<string, string> = {};
+  const dark: Record<string, string> = {};
+
+  for (const [dotPath, value] of Object.entries(flatTokens)) {
+    const strValue = String(value);
+
+    if (dotPath.startsWith('modes.light.')) {
+      const cssVar = runtimeMap[dotPath];
+      if (cssVar) light[cssVar] = strValue;
+    } else if (dotPath.startsWith('modes.dark.')) {
+      const cssVar = runtimeMap[dotPath];
+      if (cssVar) dark[cssVar] = strValue;
+    } else if (dotPath.startsWith('platform.')) {
+      const segments = dotPath.split('.');
+      const platform = segments[1];
+      if (platform !== runtimePlatform) continue;
+
+      const cssVar = runtimeMap[dotPath];
+      if (cssVar) {
+        light[cssVar] = strValue;
+        dark[cssVar] = strValue;
+      }
+    } else {
+      const cssVar = runtimeMap[dotPath];
+      if (cssVar) {
+        light[cssVar] = strValue;
+        dark[cssVar] = strValue;
+      }
+    }
+  }
+
+  return { light, dark };
+}
+
+// ---------------------------------------------------------------------------
+// Preset patch → Uniwind maps
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a nested DTCG preset patch (sparse, `$type`/`$value` leaves) into
+ * per-mode CSS variable maps suitable for `Uniwind.updateCSSVariables`.
+ *
+ * @param patch - A sparse DTCG token object (preset patch).
+ * @param runtimeMap - The generated token-to-CSS-var mapping.
+ * @param runtimePlatform - Current platform (`'web' | 'ios' | 'android'`).
+ */
+export function presetPatchToUniwindMaps(
+  patch: TokenGroup,
+  runtimeMap: RuntimeMap,
+  runtimePlatform: Platform,
+): CssVariableMaps {
+  const flat: Record<string, string | number> = {};
+  flattenDtcg(patch, '', flat);
+  return bucketByMode(flat, runtimeMap, runtimePlatform);
+}
+
+// ---------------------------------------------------------------------------
+// FI override → Uniwind maps
+// ---------------------------------------------------------------------------
+
+/**
+ * Non-color input keys from INPUT_TOKEN_MAP whose token path does NOT start
+ * with `color.`. These are handled separately from palette generation.
+ */
+const FONT_INPUT_ENTRIES: readonly (readonly [string, string])[] = (
+  Object.entries(INPUT_TOKEN_MAP) as [string, string][]
+).filter(([, tokenPath]) => !tokenPath.startsWith('color.'));
+
+/**
+ * Convert a hybrid FI override (`ThemeOverride`) into per-mode CSS variable
+ * maps suitable for `Uniwind.updateCSSVariables`.
+ *
+ * Processing:
+ * 1. Generate palettes from color `inputs` (via S4).
+ * 2. Map font inputs to token paths.
+ * 3. For each mode, merge palette + fonts + explicit `overrides.{mode}` entries.
+ * 4. Map all token dot-paths to CSS variable names via runtime map.
+ *
+ * @param override - A `ThemeOverride` object.
+ * @param runtimeMap - The generated token-to-CSS-var mapping.
+ * @param runtimePlatform - Current platform (`'web' | 'ios' | 'android'`).
+ */
+export function themeOverrideToUniwindMaps(
+  override: ThemeOverride,
+  runtimeMap: RuntimeMap,
+  // runtimePlatform: Platform,
+): CssVariableMaps {
+  const light: Record<string, string> = {};
+  const dark: Record<string, string> = {};
+
+  const inputs = override.inputs;
+  const overrides = override.overrides;
+
+  if (!inputs && !overrides) {
+    return { light, dark };
+  }
+
+  // --- Palette generation from colour inputs ---
+  let paletteTokens: Record<string, string> = {};
+  if (inputs) {
+    paletteTokens = generatePalettesFromInputs(inputs);
+  }
+
+  // --- Font input mapping ---
+  const fontTokens: Record<string, string> = {};
+  if (inputs) {
+    for (const [inputKey, tokenPath] of FONT_INPUT_ENTRIES) {
+      const value = inputs[inputKey];
+      if (value !== undefined) {
+        fontTokens[tokenPath] = String(value);
+      }
+    }
+  }
+
+  // --- Merge per mode ---
+  const modes: Mode[] = ['light', 'dark'];
+
+  for (const mode of modes) {
+    const bucket = mode === 'light' ? light : dark;
+
+    // 1. Palette-generated primitives (mode-independent → both buckets)
+    for (const [dotPath, hexValue] of Object.entries(paletteTokens)) {
+      const cssVar = runtimeMap[dotPath];
+      if (cssVar) bucket[cssVar] = hexValue;
+    }
+
+    // 2. Font input mappings (mode-independent → both buckets)
+    for (const [tokenPath, value] of Object.entries(fontTokens)) {
+      const modePrefixed = `modes.${mode}.${tokenPath}`;
+      const cssVar = runtimeMap[modePrefixed] ?? runtimeMap[tokenPath];
+      if (cssVar) bucket[cssVar] = value;
+    }
+
+    // 3. Explicit per-mode overrides (wins on collision)
+    const modeOverrides = overrides?.[mode];
+    if (modeOverrides) {
+      for (const [dotPath, value] of Object.entries(modeOverrides)) {
+        const modePrefixed = `modes.${mode}.${dotPath}`;
+        const cssVar = runtimeMap[modePrefixed] ?? runtimeMap[dotPath];
+        if (cssVar) bucket[cssVar] = String(value);
+      }
+    }
+  }
+
+  return { light, dark };
+}