@cdx-ui/styles 0.0.1-beta.61 → 0.0.1-beta.63

package/README.md

@@ -53,7 +53,7 @@ import pulse from '@cdx-ui/styles/presets/pulse.json';
 
 ### TypeScript exports
 
-The package exports DTCG-compatible type definitions, runtime constants for the override contract, and the `useForgeFonts` hook:
+The package exports DTCG-compatible type definitions, runtime constants, palette generation utilities, theming functions, and the `useForgeFonts` hook:
 
 ```typescript
 import type {
@@ -66,6 +66,14 @@ import type {
   Preset,
   Mode,
   Platform,
+  CssVariableMaps,
+  RuntimeMap,
+  PaletteCategory,
+  PaletteScale,
+  PaletteStep,
+  PaletteTokenMap,
+  ApplyThemeOverrideOptions,
+  ApplyThemeOverrideResult,
 } from '@cdx-ui/styles';
 
 import {
@@ -74,6 +82,14 @@ import {
   SUPPORTED_OVERRIDE_SCHEMA_VERSIONS,
   INPUT_TOKEN_MAP,
   presetFonts,
+  DEFAULT_PRESET,
+  generateColorScale,
+  generatePalettesFromInputs,
+  deriveBaseColorKey,
+  applyThemeOverride,
+  isSchemaVersionSupported,
+  presetPatchToUniwindMaps,
+  themeOverrideToUniwindMaps,
 } from '@cdx-ui/styles';
 ```
 
@@ -85,6 +101,10 @@ import {
 - `Preset` — Union type: `'poise' | 'prestige' | 'pulse'`.
 - `TokenValue` / `TokenGroup` — DTCG leaf node and recursive group types.
 - `Mode` / `Platform` — `'light' | 'dark'` and `'web' | 'ios' | 'android'`.
+- `CssVariableMaps` — Per-mode CSS variable maps ready for `Uniwind.updateCSSVariables`.
+- `RuntimeMap` — Token dot-paths → CSS custom property names.
+- `PaletteCategory` / `PaletteScale` / `PaletteStep` / `PaletteTokenMap` — Palette generation types.
+- `ApplyThemeOverrideOptions` / `ApplyThemeOverrideResult` — Options and result types for `applyThemeOverride`.
 
 **Constants:**
 
@@ -92,12 +112,49 @@ import {
 - `SUPPORTED_OVERRIDE_SCHEMA_VERSIONS` — Array of schema versions accepted by this package version (includes current and optionally one prior version during transition windows).
 - `INPUT_TOKEN_MAP` — Maps known input keys (`brandPrimary`, `accentPrimary`, `basePrimary`, `displayFont`) to the token path pattern each affects. Used by override application to route inputs to the correct palette namespace.
 - `presetFonts` — Allowed display font families per preset, used by the Theme Editor for font selection and by consuming apps for validation.
+- `DEFAULT_PRESET` — The default preset (`'poise'`).
+
+**Palette generation:**
+
+- `generateColorScale(hex, category)` — Generates an 11-step Leonardo contrast scale (50–950) plus an `input` step from a single hex color. Categories: `'brand' | 'accent' | 'base'`. Returns a `PaletteTokenMap` keyed by token dot-paths (e.g. `color.brand.50` through `color.brand.input`).
+- `generatePalettesFromInputs(inputs)` — Iterates `brandPrimary`, `accentPrimary`, `basePrimary` from an override's `inputs` object; calls `generateColorScale` for each present value. Returns a merged `PaletteTokenMap`.
+- `deriveBaseColorKey(brandHex)` — Derives a neutral base color key from a brand hex (brand hue/lightness at 5% saturation). Used by the Theme Editor to automatically compute `basePrimary` from `brandPrimary`.
+
+**Theming utilities:**
+
+- `applyThemeOverride(override, options?)` — High-level orchestrator: validates schema version → applies preset patch (if non-default base) → generates palettes from inputs → merges FI overrides → calls `Uniwind.updateCSSVariables` per mode. Returns a discriminated union: `{ applied: true, light, dark }` or `{ applied: false, reason }`. Options: `runtimeMap`, `runtimePlatform`. Bundles the default runtime map internally. Requires `uniwind` as a peer dependency.
+- `isSchemaVersionSupported(override)` — Schema version gate; returns `true` if the override's `schemaVersion` is in `SUPPORTED_OVERRIDE_SCHEMA_VERSIONS`.
+- `presetPatchToUniwindMaps(patch, runtimeMap, runtimePlatform)` — Walks a nested DTCG preset patch; buckets leaves by mode/platform into per-mode CSS variable maps.
+- `themeOverrideToUniwindMaps(override, runtimeMap)` — Processes a hybrid FI override: palette generation from `inputs`, font mapping, per-mode `overrides` merge, and token-reference alias resolution.
+
+A tree-shakeable subpath is also available:
+
+```typescript
+import {
+  applyThemeOverride,
+  presetPatchToUniwindMaps,
+  themeOverrideToUniwindMaps,
+} from '@cdx-ui/styles/theming';
+```
 
 **Hooks:**
 
 - `useForgeFonts` — Loads all preset display fonts (nine families, three per preset) plus platform web fonts (Inter, IBM Plex Mono) via `expo-font`. Returns `{ loaded: boolean; error: Error | null }`. Call in your root layout and gate rendering on the returned `loaded` boolean. See [Getting Started](../../docs/getting-started.md) for usage.
 - `useCdxFonts` — **Deprecated** alias for `useForgeFonts`. Retained for backward compatibility during the CDX → Forge rename transition. See [Getting Started](../../docs/getting-started.md) for the migration path.
 
+### Runtime artifacts
+
+The build produces runtime JSON artifacts importable from the package:
+
+```typescript
+import runtimeMap from '@cdx-ui/styles/runtime/token-to-css-var.json';
+import prestigePatch from '@cdx-ui/styles/runtime/prestige-vs-default.json';
+import pulsePatch from '@cdx-ui/styles/runtime/pulse-vs-default.json';
+```
+
+- **`runtime/token-to-css-var.json`** — Flat map of ~667 token dot-paths to CSS custom property names (e.g. `"color.brand.500": "--color-brand-500"`). Used internally by `applyThemeOverride`; importable for custom apply logic.
+- **`runtime/prestige-vs-default.json`** / **`runtime/pulse-vs-default.json`** — Sparse preset patches (diff from build default to target preset). Used internally by `applyThemeOverride` when `basePreset` differs from the build default.
+
 ## Token pipeline
 
 The pipeline has two stages — **fetch** and **build** — both run from package scripts.
@@ -144,12 +201,12 @@ pnpm tokens:build
 | `utilities.css` | `@utility` blocks for composite typography (headings, body-xl through body-xs, label-sm, label-xs)  |
 | `vanilla.css`   | Non-Tailwind fallback — `:root` variables + `@media (prefers-color-scheme: dark)` + classes         |
 
-**Planned artifacts** (not yet implemented — tracked for future runtime theming):
+**Runtime artifacts** (generated by `tokens:build`):
 
-| Artifact       | Purpose                                                            | Status  |
-| -------------- | ------------------------------------------------------------------ | ------- |
-| Runtime map    | Theme object path → CSS custom property name for sparse flattening | Planned |
-| Preset patches | Sparse diff from build default → each non-default preset           | Planned |
+| Artifact           | File                               | Purpose                                                            |
+| ------------------ | ---------------------------------- | ------------------------------------------------------------------ |
+| **Runtime map**    | `runtime/token-to-css-var.json`    | Theme object path → CSS custom property name for sparse flattening |
+| **Preset patches** | `runtime/{preset}-vs-default.json` | Sparse diff from build default → each non-default preset           |
 
 ### Validating font tokens
 
@@ -175,7 +232,7 @@ Light/dark mode switching is handled by Uniwind `@variant light/dark` blocks in
 
 ### FI overrides
 
-Financial institution white-labelling uses the hybrid override format — brand inputs (a single hex color expanded into a full palette at runtime) plus optional per-mode semantic token overrides. The Theme API is a pass-through store; validation is performed by the Theme Editor before save. Consuming apps apply overrides at runtime via palette generation + the runtime map + `Uniwind.updateCSSVariables`. See [Override Structure](../../docs/internal/token-architecture/16-override-structure.md) for the payload format and responsibility contract, and [Theme Definition](../../docs/internal/token-architecture/02-theme-definition.md) for the full theme object schema.
+Financial institution white-labelling uses the hybrid override format — brand inputs (a single hex color expanded into a full palette at runtime) plus optional per-mode semantic token overrides. The Theme API is a pass-through store; validation is performed by the Theme Editor before save. Consuming apps apply overrides at runtime via `applyThemeOverride` (which handles palette generation, runtime map lookup, and `Uniwind.updateCSSVariables` calls internally). See [Override Structure](../../docs/internal/token-architecture/16-override-structure.md) for the payload format and responsibility contract, and [Theme Definition](../../docs/internal/token-architecture/02-theme-definition.md) for the full theme object schema.
 
 ## Package structure
 
@@ -185,12 +242,20 @@ styles/
 │   ├── theme.css              # Auto-generated — all token variable declarations
 │   ├── utilities.css          # Auto-generated — composite typography @utility blocks
 │   └── vanilla.css            # Auto-generated — non-Tailwind fallback
+├── runtime/
+│   ├── token-to-css-var.json       # Build-generated — token path → CSS variable name map
+│   ├── prestige-vs-default.json    # Build-generated — sparse preset patch (Poise → Prestige)
+│   └── pulse-vs-default.json       # Build-generated — sparse preset patch (Poise → Pulse)
 ├── scripts/
 │   ├── figma-fetch-variables.mjs   # Figma Variables REST API fetch
 │   ├── build-tokens.mjs            # Style Dictionary build + artifact generation
 │   └── validate-font-tokens.mjs    # CI check: --font-* values match useForgeFonts keys
 ├── src/
-│   ├── index.ts               # Types, override constants, hook re-exports
+│   ├── index.ts               # Public barrel: types, constants, palette, theming, hooks
+│   ├── palette.ts             # Color scale generation (Leonardo contrast algorithm)
+│   ├── theming.ts             # Sparse flatten helpers (presetPatchToUniwindMaps, themeOverrideToUniwindMaps)
+│   ├── applyThemeOverride.ts  # High-level orchestrator (schema gate → patch → palette → apply)
+│   ├── types.ts               # DTCG types, override contract, constants
 │   ├── useForgeFonts.ts       # Font loader hook (expo-font) — loads all preset display fonts
 │   └── useCdxFonts.ts         # Deprecated alias for useForgeFonts
 ├── tokens/
@@ -206,7 +271,7 @@ styles/
 └── tsconfig.build.json
 ```
 
-`css/` files are auto-generated — do not edit directly.
+`css/` and `runtime/` files are auto-generated — do not edit directly.
 
 ## Building
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cdx-ui/styles",
-  "version": "0.0.1-beta.61",
+  "version": "0.0.1-beta.63",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
   "react-native": "src/index.ts",
@@ -65,7 +65,7 @@
     "@expo-google-fonts/manrope": "0.4.2",
     "@expo-google-fonts/outfit": "0.4.3",
     "@expo-google-fonts/public-sans": "0.4.2",
-    "@cdx-ui/utils": "0.0.1-beta.61"
+    "@cdx-ui/utils": "0.0.1-beta.63"
   },
   "peerDependencies": {
     "expo-font": ">=13.0.0",