@oxyhq/bloom 0.7.7 → 0.8.0

package/src/theme/preset-vars.ts

@@ -1,5 +1,10 @@
 import { Platform } from 'react-native';
 import { APP_COLOR_PRESETS, type AppColorName, type PresetTokens } from './color-presets';
+// Circular at the module graph level (`token-registry` imports `getPresetVars`
+// from here), but safe: `getResolvedTokens` is only referenced inside the
+// `applyPresetVarsToDocument` function body — i.e. at call time, after both
+// modules have finished evaluating — never during module initialization.
+import { getResolvedTokens } from './token-registry';
 
 function extractHue(hslVar: string): number {
   return parseInt(hslVar.split(' ')[0] ?? '0', 10);
@@ -9,168 +14,6 @@ function extractSat(hslVar: string): number {
   return parseInt(hslVar.split(' ')[1] ?? '0', 10);
 }
 
-/**
- * Convert a shadcn-style HSL triple (`'H S% L%'`, optionally with an alpha tail
- * `'H S% L% / A'`) into an sRGB `rgb(...)` string.
- *
- * Why rgb and not hsl (the native alpha-utility bug this fixes)
- * -------------------------------------------------------------
- * Tailwind v4 compiles an alpha-on-theme-color utility (`bg-primary/10`) into a
- * `color-mix(... var(--color-primary) 10%, transparent)` declaration. On native,
- * react-native-css resolves that `color-mix` at runtime via `colorjs.io/fn`, but
- * its `color-mix` implementation registers ONLY the `sRGB`, `P3`, and `OKLab`
- * color spaces — never `HSL`. So if `--color-primary` resolves to an `hsl(...)`
- * string, `parse('hsl(...)')` throws, the mix is swallowed, and the utility
- * silently produces no color. Emitting the resolved var as `rgb(...)` (a space
- * colorjs.io always has registered) makes the alpha utilities resolve on native,
- * matching web. Full (non-alpha) utilities already worked because React Native's
- * native color parser handles `hsl()` directly; only `color-mix` was affected.
- *
- * Output is space-separated channels (`rgb(31 153 239)`), the modern CSS syntax
- * parsed by both `colorjs.io/fn` (with only sRGB/P3/OKLab registered) and
- * react-native-web / browsers. An alpha tail emits `rgb(r g b / a)`, likewise
- * parsed by both.
- *
- * Pure function — standard HSL→sRGB conversion, channels rounded to integers.
- * Tolerates a `deg` suffix on the hue and `%` suffixes on saturation/lightness.
- */
-export function hslTripletToRgb(triplet: string): string {
-  const [colorPart, alphaPart] = triplet.split('/').map((part) => part.trim());
-  const channels = (colorPart ?? '').split(/\s+/).filter(Boolean);
-
-  const hue = parseFloat((channels[0] ?? '0').replace(/deg$/i, ''));
-  const sat = parseFloat((channels[1] ?? '0').replace('%', '')) / 100;
-  const light = parseFloat((channels[2] ?? '0').replace('%', '')) / 100;
-
-  const h = Number.isFinite(hue) ? hue : 0;
-  const s = Number.isFinite(sat) ? sat : 0;
-  const l = Number.isFinite(light) ? light : 0;
-
-  const chroma = (1 - Math.abs(2 * l - 1)) * s;
-  const huePrime = ((((h % 360) + 360) % 360) / 60);
-  const second = chroma * (1 - Math.abs((huePrime % 2) - 1));
-
-  let r = 0;
-  let g = 0;
-  let b = 0;
-  if (huePrime < 1) {
-    [r, g, b] = [chroma, second, 0];
-  } else if (huePrime < 2) {
-    [r, g, b] = [second, chroma, 0];
-  } else if (huePrime < 3) {
-    [r, g, b] = [0, chroma, second];
-  } else if (huePrime < 4) {
-    [r, g, b] = [0, second, chroma];
-  } else if (huePrime < 5) {
-    [r, g, b] = [second, 0, chroma];
-  } else {
-    [r, g, b] = [chroma, 0, second];
-  }
-
-  const match = l - chroma / 2;
-  const red = Math.round((r + match) * 255);
-  const green = Math.round((g + match) * 255);
-  const blue = Math.round((b + match) * 255);
-
-  if (alphaPart !== undefined && alphaPart !== '') {
-    const alpha = alphaPart.endsWith('%')
-      ? parseFloat(alphaPart) / 100
-      : parseFloat(alphaPart);
-    const safeAlpha = Number.isFinite(alpha) ? alpha : 1;
-    return `rgb(${red} ${green} ${blue} / ${safeAlpha})`;
-  }
-
-  return `rgb(${red} ${green} ${blue})`;
-}
-
-/**
- * Prefix that marks a Tailwind v4 resolved color var (`--color-primary`). These
- * are already emitted as full `rgb(...)` colors by `getPresetVars` and must be
- * written to web verbatim — wrapping them would corrupt the value.
- */
-const RESOLVED_COLOR_VAR_PREFIX = '--color-';
-
-/**
- * Matches a shadcn-style raw HSL triple — `H S% L%`, optionally with an alpha
- * tail `H S% L% / A`. The value starts with a digit (or a leading `-`) and
- * carries at least one `%` (the saturation/lightness units), which together
- * distinguish a bare triple from an already-resolved CSS color (`rgb(...)`,
- * `hsl(...)`, `#fff`, named colors) or a unitless/length token (`--radius`).
- * Mirrors the triple shape parsed by `hslTripletToRgb`.
- */
-const RAW_HSL_TRIPLE = /^-?\d[\d.]*\s+[\d.]+%/;
-
-/**
- * Transform a single preset var into the value to write to a WEB element
- * (`document.documentElement` or a `BloomColorScope` subtree element).
- *
- * The web apps (Vite + Tailwind v4 + shadcn) compile their `@theme inline`
- * block so the color utilities reference the BASE token directly — e.g.
- * `.bg-background { background-color: var(--background) }`. So on web the base
- * `--x` tokens MUST resolve to a COMPLETE CSS color; a bare HSL triple
- * (`185 50% 5%`) is invalid as a `background-color` value and renders
- * transparent (the production incident this fixes). We therefore wrap raw
- * triples in `hsl(...)`, preserving the exact preset color math (and any `/ A`
- * alpha tail, valid in modern `hsl(H S% L% / A)` syntax) with zero rounding
- * drift.
- *
- * Values that are already full colors pass through unchanged:
- *   - `--color-*` resolved vars (already `rgb(...)` from `getPresetVars`),
- *   - any value not shaped like a raw HSL triple (`--radius: 0.5rem`,
- *     pre-resolved `rgb(...)`/`hsl(...)`, etc.).
- *
- * NATIVE never calls this — `getPresetVars` returns raw triples verbatim and
- * `native-root-vars.native.ts` writes them through bloom's `hsl(var(--x))`
- * native `global.css` indirection. Pure function — no side effects — so it is
- * unit-testable in isolation.
- */
-export function toWebColorValue(key: string, value: string): string {
-  if (key.startsWith(RESOLVED_COLOR_VAR_PREFIX)) return value;
-  if (!RAW_HSL_TRIPLE.test(value)) return value;
-  return `hsl(${value})`;
-}
-
-const RESOLVED_COLOR_MAP: Record<string, string> = {
-  '--background': '--color-background',
-  '--foreground': '--color-foreground',
-  '--primary': '--color-primary',
-  '--primary-foreground': '--color-primary-foreground',
-  '--secondary': '--color-secondary',
-  '--secondary-foreground': '--color-secondary-foreground',
-  '--muted': '--color-muted',
-  '--muted-foreground': '--color-muted-foreground',
-  '--accent': '--color-accent',
-  '--accent-foreground': '--color-accent-foreground',
-  '--destructive': '--color-destructive',
-  '--border': '--color-border',
-  '--input': '--color-input',
-  '--ring': '--color-ring',
-  '--popover': '--color-popover',
-  '--popover-foreground': '--color-popover-foreground',
-  '--surface': '--color-surface',
-  '--surface-foreground': '--color-surface-foreground',
-  '--card': '--color-card',
-  '--card-foreground': '--color-card-foreground',
-};
-
-export interface PresetVarsOptions {
-  /**
-   * Also emit Tailwind v4 resolved `--color-*` vars (as sRGB `rgb(...)` strings)
-   * alongside the raw HSL triples. Needed when scoping a subtree where
-   * Tailwind's `@theme` block has already precomputed `--color-*` at `:root`,
-   * so overriding `--background` alone wouldn't cascade to `bg-background`.
-   *
-   * The resolved vars are emitted as `rgb(...)` rather than `hsl(...)` so the
-   * alpha-on-theme-color utilities (`bg-primary/10`, `text-foreground/50`)
-   * resolve on native: Tailwind compiles those to a runtime `color-mix(...)` that
-   * react-native-css evaluates via `colorjs.io/fn`, which only registers the
-   * sRGB/P3/OKLab spaces (not HSL) — so an `hsl(...)` var would throw and the
-   * utility would silently render no color. See `hslTripletToRgb`. Default
-   * `false`.
-   */
-  includeResolvedColorVars?: boolean;
-}
-
 /**
  * Bloom's base preset tokens extended with the surface/card/chart/sidebar
  * tokens that apps layer on top of the core shadcn palette. Synthesized from
@@ -178,11 +21,15 @@ export interface PresetVarsOptions {
  *
  * This is the single source of truth for extended theming vars — consumer apps
  * must not redefine these per-app.
+ *
+ * Values are platform-agnostic **raw HSL triples** (`'185 100% 20%'`, optionally
+ * with a `/ A` alpha tail). The single canonical resolver `getResolvedTokens`
+ * (in `token-registry.ts`) converts these to sRGB `rgb(...)` for BOTH web and
+ * native runtime writes — this function only produces the raw triple map.
  */
 export function getPresetVars(
   colorName: AppColorName,
   mode: 'light' | 'dark',
-  options: PresetVarsOptions = {},
 ): PresetTokens {
   const preset = APP_COLOR_PRESETS[colorName];
   const base = mode === 'light' ? preset.light : preset.dark;
@@ -215,14 +62,7 @@ export function getPresetVars(
     '--sidebar-ring': get('--ring'),
   };
 
-  if (!options.includeResolvedColorVars) return extended;
-
-  const resolved: PresetTokens = { ...extended };
-  for (const [rawKey, colorKey] of Object.entries(RESOLVED_COLOR_MAP)) {
-    const value = extended[rawKey];
-    if (value) resolved[colorKey] = hslTripletToRgb(value);
-  }
-  return resolved;
+  return extended;
 }
 
 /**
@@ -231,21 +71,20 @@ export function getPresetVars(
  * call this only when an app needs the extended (card/chart/sidebar) tokens on
  * the document root.
  *
- * The base raw-HSL-triple tokens are wrapped to full `hsl(...)` colors via
- * `toWebColorValue` so `var(--x)` (the form Tailwind v4 `@theme inline`
- * compiles to) resolves directly on web; `--color-*` rgb vars pass through. See
- * `toWebColorValue` for the web var contract.
+ * Tokens are resolved to sRGB `rgb(...)` via the single canonical
+ * `getResolvedTokens` pipeline, so `var(--x)` — the form Tailwind v4
+ * `@theme inline` compiles its color utilities to — resolves directly to a
+ * valid color on web.
  */
 export function applyPresetVarsToDocument(
   colorName: AppColorName,
   mode: 'light' | 'dark',
-  options?: PresetVarsOptions,
 ): void {
   if (Platform.OS !== 'web' || typeof document === 'undefined') return;
 
-  const vars = getPresetVars(colorName, mode, options);
+  const vars = getResolvedTokens(colorName, mode);
   const root = document.documentElement.style;
   for (const [key, value] of Object.entries(vars)) {
-    root.setProperty(key, toWebColorValue(key, value));
+    root.setProperty(key, value);
   }
 }

package/src/theme/token-registry.ts

@@ -0,0 +1,159 @@
+import { APP_COLOR_NAMES, type AppColorName } from './color-presets';
+import { getPresetVars } from './preset-vars';
+
+/**
+ * The canonical set of Bloom theme token names — WITHOUT the leading `--`.
+ *
+ * This is the single source of truth for which tokens a preset produces. It
+ * covers exactly the keys returned by `getPresetVars(name, mode)` (the base
+ * shadcn palette plus the synthesized extended tokens: card/chart/content-area/
+ * sidebar-*). The list is intentionally hand-maintained and verified by
+ * `token-registry.test.ts` against the live `getPresetVars('oxy', 'light')`
+ * output, so any drift in the preset shape fails CI.
+ *
+ * Order mirrors `getPresetVars`'s insertion order: base tokens first (in the
+ * order they appear in the preset data), then the synthesized extended tokens.
+ */
+export const CANONICAL_TOKENS = [
+  'background',
+  'foreground',
+  'surface',
+  'surface-foreground',
+  'popover',
+  'popover-foreground',
+  'primary',
+  'primary-foreground',
+  'secondary',
+  'secondary-foreground',
+  'muted',
+  'muted-foreground',
+  'accent',
+  'accent-foreground',
+  'destructive',
+  'border',
+  'input',
+  'ring',
+  'sidebar',
+  'card',
+  'card-foreground',
+  'chart-1',
+  'chart-2',
+  'chart-3',
+  'chart-4',
+  'chart-5',
+  'content-area',
+  'sidebar-foreground',
+  'sidebar-primary',
+  'sidebar-primary-foreground',
+  'sidebar-accent',
+  'sidebar-accent-foreground',
+  'sidebar-border',
+  'sidebar-ring',
+] as const;
+
+/** A canonical token name (no leading `--`). */
+export type CanonicalToken = (typeof CANONICAL_TOKENS)[number];
+
+/**
+ * Matches a shadcn-style raw HSL triple — `H S% L%`, optionally with an alpha
+ * tail `H S% L% / A`. The value starts with a digit (or a leading `-`) and
+ * carries at least one `%` (the saturation/lightness units), which distinguishes
+ * a bare triple from an already-resolved color (`rgb(...)`, `#fff`) or a
+ * unitless/length token (`--radius: 0.5rem`).
+ */
+const RAW_HSL_TRIPLE = /^-?\d[\d.]*\s+[\d.]+%/;
+
+/**
+ * Convert a shadcn-style HSL triple (`'H S% L%'`, optionally with an alpha tail
+ * `'H S% L% / A'`) into an sRGB `rgb(...)` string.
+ *
+ * Standard HSL→sRGB math with integer-rounded channels and modern
+ * space-separated output (`rgb(r g b)` / `rgb(r g b / a)`). This is the SINGLE
+ * conversion the whole library uses — web document writes, web scope vars, and
+ * native `rootVariables` all flow through `getResolvedTokens`, which calls this.
+ * The byte-for-byte output is frozen by the golden parity fixture
+ * (`__fixtures__/golden-resolved-tokens.json`), so the visible palette cannot
+ * drift.
+ *
+ * Task 2's `oklchToSrgb` (in `color-space.ts`) stays available for a FUTURE
+ * OKLCH re-authoring of the seed palette; it is intentionally NOT used here —
+ * routing through OKLCH would shift the rounded channels off the frozen palette.
+ *
+ * Pure function — no side effects.
+ */
+export function hslToSrgb(triple: string): string {
+  const [colorPart, alphaPart] = triple.split('/').map((part) => part.trim());
+  const channels = (colorPart ?? '').split(/\s+/).filter(Boolean);
+
+  const hue = parseFloat((channels[0] ?? '0').replace(/deg$/i, ''));
+  const sat = parseFloat((channels[1] ?? '0').replace('%', '')) / 100;
+  const light = parseFloat((channels[2] ?? '0').replace('%', '')) / 100;
+
+  const h = Number.isFinite(hue) ? hue : 0;
+  const s = Number.isFinite(sat) ? sat : 0;
+  const l = Number.isFinite(light) ? light : 0;
+
+  const chroma = (1 - Math.abs(2 * l - 1)) * s;
+  const huePrime = ((((h % 360) + 360) % 360) / 60);
+  const second = chroma * (1 - Math.abs((huePrime % 2) - 1));
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  if (huePrime < 1) {
+    [r, g, b] = [chroma, second, 0];
+  } else if (huePrime < 2) {
+    [r, g, b] = [second, chroma, 0];
+  } else if (huePrime < 3) {
+    [r, g, b] = [0, chroma, second];
+  } else if (huePrime < 4) {
+    [r, g, b] = [0, second, chroma];
+  } else if (huePrime < 5) {
+    [r, g, b] = [second, 0, chroma];
+  } else {
+    [r, g, b] = [chroma, 0, second];
+  }
+
+  const match = l - chroma / 2;
+  const red = Math.round((r + match) * 255);
+  const green = Math.round((g + match) * 255);
+  const blue = Math.round((b + match) * 255);
+
+  if (alphaPart !== undefined && alphaPart !== '') {
+    const alpha = alphaPart.endsWith('%')
+      ? parseFloat(alphaPart) / 100
+      : parseFloat(alphaPart);
+    const safeAlpha = Number.isFinite(alpha) ? alpha : 1;
+    return `rgb(${red} ${green} ${blue} / ${safeAlpha})`;
+  }
+
+  return `rgb(${red} ${green} ${blue})`;
+}
+
+/**
+ * Resolve a preset's canonical runtime color tokens to sRGB `rgb(...)` strings.
+ *
+ * THE single source of runtime color tokens for the whole library, on BOTH web
+ * and native. Takes the raw triple map from `getPresetVars(preset, mode)` (base
+ * + extended) and converts every value that looks like an HSL triple via
+ * `hslToSrgb`. Non-triple values (already-resolved colors, length/radius tokens)
+ * pass through unchanged. Keys retain the `--` prefix, so each `--x` token IS a
+ * full CSS color — no resolved-color companion universe, no per-platform wrapping.
+ *
+ * The result is frozen by the golden parity fixture
+ * (`__fixtures__/golden-resolved-tokens.json`), guaranteeing the visible palette
+ * matches the previous resolved-color pipeline byte-for-byte.
+ */
+export function getResolvedTokens(
+  preset: AppColorName,
+  mode: 'light' | 'dark',
+): Record<string, string> {
+  const raw = getPresetVars(preset, mode);
+  const resolved: Record<string, string> = {};
+  for (const [key, value] of Object.entries(raw)) {
+    resolved[key] = RAW_HSL_TRIPLE.test(value) ? hslToSrgb(value) : value;
+  }
+  return resolved;
+}
+
+export { APP_COLOR_NAMES };

package/src/theme/types.ts

@@ -14,9 +14,12 @@ export interface ThemeColors {
 
   primary: string;
   primaryForeground: string;
+  /** Preset accent tint (`--accent`) — a soft brand-tinted surface, NOT the page surface. */
   primaryLight: string;
+  /** Focus-ring shade (`--ring`) — the preset's emphasized ring/border color, NOT the page background. */
   primaryDark: string;
 
+  /** Preset secondary surface (`--secondary`) — a muted companion surface, NOT a mirror of `primary`. */
   secondary: string;
 
   tint: string;