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

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';

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