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

package/src/palette.ts

@@ -0,0 +1,307 @@
+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' | 'base';
+
+/** 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;
+}
+
+// ---------------------------------------------------------------------------
+// Base color-key derivation
+// ---------------------------------------------------------------------------
+
+/** Saturation (0–1) applied to the brand hue to produce the base color key. */
+const BASE_SATURATION = 0.05;
+
+/** Convert a normalised hex string to HSL (`h` in degrees, `s`/`l` in 0–1). */
+function hexToHsl(hex: CssColor): { h: number; s: number; l: number } {
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+  const l = (max + min) / 2;
+
+  let h = 0;
+  let s = 0;
+  if (delta !== 0) {
+    s = l > 0.5 ? delta / (2 - max - min) : delta / (max + min);
+    switch (max) {
+      case r:
+        h = (g - b) / delta + (g < b ? 6 : 0);
+        break;
+      case g:
+        h = (b - r) / delta + 2;
+        break;
+      default:
+        h = (r - g) / delta + 4;
+        break;
+    }
+    h *= 60;
+  }
+
+  return { h, s, l };
+}
+
+/** Convert HSL (`h` in degrees, `s`/`l` in 0–1) to a normalised hex string. */
+function hslToHex({ h, s, l }: { h: number; s: number; l: number }): CssColor {
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const hp = (((h % 360) + 360) % 360) / 60;
+  const x = c * (1 - Math.abs((hp % 2) - 1));
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  if (hp < 1) [r, g, b] = [c, x, 0];
+  else if (hp < 2) [r, g, b] = [x, c, 0];
+  else if (hp < 3) [r, g, b] = [0, c, x];
+  else if (hp < 4) [r, g, b] = [0, x, c];
+  else if (hp < 5) [r, g, b] = [x, 0, c];
+  else [r, g, b] = [c, 0, x];
+
+  const m = l - c / 2;
+  const toHex = (v: number) =>
+    Math.round((v + m) * 255)
+      .toString(16)
+      .padStart(2, '0');
+
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}` as CssColor;
+}
+
+/**
+ * Derive the base palette color key from a brand color.
+ *
+ * The base scale shares the brand's hue and lightness but is nearly neutral:
+ * the brand color is converted to HSL and its saturation is lowered to
+ * {@link BASE_SATURATION} (5%). The resulting hex is the color key fed to
+ * {@link generateColorScale} for the `base` category.
+ *
+ * @param brandHex - A valid hex color string (`#RGB` or `#RRGGBB`).
+ * @returns The normalised hex color key for the base scale.
+ */
+export function deriveBaseColorKey(brandHex: string): string {
+  const { h, l } = hexToHsl(validateHex(brandHex));
+  return hslToHex({ h, s: BASE_SATURATION, l });
+}
+
+// ---------------------------------------------------------------------------
+// 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'],
+  ['basePrimary', 'color.base'],
+] 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,268 @@
+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.'));
+
+/**
+ * Matches a token-reference alias value such as `{color.brand.700}` and
+ * captures the referenced token dot-path.
+ */
+const TOKEN_ALIAS_REGEX = /^\{([^}]+)\}$/;
+
+/**
+ * Resolve an `overrides.{mode}` value into the string written to the CSS
+ * variable map.
+ *
+ * - **Token-reference alias** (`{color.brand.700}`) → resolves the referenced
+ *   token path via the runtime map and returns a CSS `var()` reference
+ *   (`var(--color-brand-700)`), so the override tracks its source through the
+ *   cascade — the same mechanism the base theme uses for its semantic tokens.
+ *   Returns `null` when the referenced path is absent from the runtime map
+ *   (e.g. a non-primitive target), so the caller skips it; this enforces the
+ *   primitive-only alias constraint at the resolution layer.
+ * - **Literal value** (`#F5F7F6`, `8`) → returned as-is (stringified).
+ *
+ * @see docs/internal/token-architecture/16-override-structure.md — Token-reference aliases vs. literal values
+ */
+function resolveOverrideValue(value: string | number, runtimeMap: RuntimeMap): string | null {
+  if (typeof value === 'string') {
+    const aliasMatch = TOKEN_ALIAS_REGEX.exec(value);
+    if (aliasMatch) {
+      const referencedPath = aliasMatch[1].trim();
+      const targetCssVar = runtimeMap[referencedPath];
+      return targetCssVar ? `var(${targetCssVar})` : null;
+    }
+  }
+  return String(value);
+}
+
+/**
+ * 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). Values may be
+    //    token-reference aliases (resolved to a CSS var() reference) or
+    //    literals; see resolveOverrideValue.
+    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) continue;
+
+        const resolved = resolveOverrideValue(value, runtimeMap);
+        if (resolved !== null) bucket[cssVar] = resolved;
+      }
+    }
+  }
+
+  return { light, dark };
+}

package/src/types.ts

@@ -0,0 +1,112 @@
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** 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';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** 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;
+
+/**
+ * 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>;
+
+/**
+ * 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;