@oxyhq/bloom 0.43.0 → 0.44.1

package/src/theme/BloomThemeProvider.tsx

@@ -24,11 +24,13 @@ import {
 import { useControllableState } from '../hooks/useControllableState';
 import { FontLoader } from '../fonts/FontLoader';
 
-import { applyDarkClass, applyColorPresetVars } from './apply-dark-class';
+import { applyDarkClass, applyVarsToDocument } from './apply-dark-class';
 import { buildTheme } from './build-theme';
+import { buildThemeFromSeed } from './build-theme-from-seed';
+import { buildSeedScopeVars } from './color-scope/seed-scope';
 import { type AppColorName } from './color-presets';
 import { buildScopeVars, getVariableContextProvider } from './color-scope/style-builder';
-import { applyNativeRootVars } from './native-root-vars';
+import { applyVarsToRootVariables } from './native-root-vars';
 import {
   readPersistedTheme,
   readPersistedThemeSync,
@@ -151,6 +153,17 @@ export interface BloomThemeProviderProps {
    */
   tertiaryColor?: string;
 
+  /**
+   * Optional DYNAMIC seed colour, `#rrggbb`. When set, the WHOLE app themes from
+   * this seed instead of the named `colorPreset` (via the same colour engine the
+   * preset path uses) — driving app-wide dynamic theming (e.g. tint everything to
+   * the artwork the user is viewing/hovering). `secondaryColor`/`tertiaryColor`
+   * act as this seed's pinned secondary/tertiary accents (e.g. the 2nd/3rd colours
+   * extracted from that artwork). Omit / pass `undefined` to fall back to the
+   * preset — so clearing it restores the app's default theme.
+   */
+  seed?: string;
+
   children: React.ReactNode;
 }
 
@@ -314,6 +327,7 @@ export function BloomThemeProvider({
   nativeWrapperStyle,
   secondaryColor,
   tertiaryColor,
+  seed,
   children,
 }: BloomThemeProviderProps) {
   const rnScheme = useRNColorScheme();
@@ -349,45 +363,67 @@ export function BloomThemeProvider({
   // Apply native color scheme, dark class, and CSS vars whenever the resolved
   // mode or preset changes. `useIsomorphicLayoutEffect` runs before paint on
   // both native and web, eliminating the previous render-time side effect.
+  // The single `--x -> value` record + JS theme for the ACTIVE source, computed
+  // ONCE and applied identically to web (document), native (rootVariables +
+  // VariableContext), and the JS `theme` context. The source is a DYNAMIC seed
+  // (whole-app dynamic theming — `secondaryColor`/`tertiaryColor` pin this seed's
+  // accents) when `seed` is set, else the named preset. Both go through the same
+  // colour engine, so there is one code path — no seed/preset duplication.
+  const themeVars = useMemo(
+    () =>
+      seed
+        ? buildSeedScopeVars({ seed, mode: resolved, secondarySeed: secondaryColor, tertiarySeed: tertiaryColor })
+        : buildScopeVars(colorPreset, resolved, explicitAccents),
+    [seed, secondaryColor, tertiaryColor, colorPreset, resolved, explicitAccents],
+  );
+  const themeColors = useMemo(
+    () =>
+      seed
+        ? buildThemeFromSeed(seed, resolved, undefined, undefined, {
+            secondarySeed: secondaryColor,
+            tertiarySeed: tertiaryColor,
+          })
+        : buildTheme(colorPreset, resolved, isAdaptive, explicitAccents),
+    [seed, secondaryColor, tertiaryColor, colorPreset, resolved, isAdaptive, explicitAccents],
+  );
+
   useIsomorphicLayoutEffect(() => {
     setColorSchemeSafe(effectiveMode);
     applyDarkClass(resolved);
-    applyColorPresetVars(colorPreset, resolved, explicitAccents);
-  }, [effectiveMode, resolved, colorPreset, explicitAccents]);
+    applyVarsToDocument(themeVars);
+  }, [effectiveMode, resolved, themeVars]);
 
-  // Native only: publish the preset vars into react-native-css's GLOBAL root
+  // Native only: publish the same vars into react-native-css's GLOBAL root
   // variable family so they reach the ENTIRE app tree — navigator screens and
   // every portal/modal/bottom-sheet that paints outside the provider's React
   // subtree (and therefore never sees the `VariableContextProvider` vars below).
   // Web writes the same vars to `document.documentElement` above, so this no-ops
-  // there. Runs before paint via `useIsomorphicLayoutEffect`, matching the
-  // sibling `applyColorPresetVars` side effect.
+  // there. Runs before paint via `useIsomorphicLayoutEffect`.
   useIsomorphicLayoutEffect(() => {
-    applyNativeRootVars(colorPreset, resolved, explicitAccents);
-  }, [colorPreset, resolved, explicitAccents]);
+    applyVarsToRootVariables(themeVars);
+  }, [themeVars]);
 
   const contextValue = useMemo<BloomThemeContextValue>(
     () => ({
-      theme: buildTheme(colorPreset, resolved, isAdaptive, explicitAccents),
+      theme: themeColors,
       mode,
       colorPreset,
       setMode,
       setColorPreset,
       resetTheme,
     }),
-    [colorPreset, resolved, isAdaptive, explicitAccents, mode, setMode, setColorPreset, resetTheme],
+    [themeColors, mode, colorPreset, setMode, setColorPreset, resetTheme],
   );
 
   const shouldAwait = awaitHydration ?? Boolean(persistKey && storage);
   const isGated = shouldAwait && !hydrated;
 
-  // The full `--name -> value` record for the active preset. On native this is
-  // handed to `VariableContextProvider` so descendants resolve `var(--primary)`
-  // etc. through react-native-css's real VariableContext. Web writes these to
-  // `document.documentElement` via `applyColorPresetVars`, so it's unused there.
+  // On native, the same record is handed to `VariableContextProvider` so
+  // descendants resolve `var(--primary)` etc. through react-native-css's real
+  // VariableContext. Web writes them to `document.documentElement` above.
   const nativeVars = useMemo(
-    () => (Platform.OS === 'web' ? null : buildScopeVars(colorPreset, resolved, explicitAccents)),
-    [colorPreset, resolved, explicitAccents],
+    () => (Platform.OS === 'web' ? null : themeVars),
+    [themeVars],
   );
   const VariableProvider = getVariableContextProvider();
 

package/src/theme/apply-dark-class.ts

@@ -26,18 +26,25 @@ export function applyDarkClass(resolved: 'light' | 'dark') {
  * Includes extended tokens (card, chart-*, content-area, sidebar-*) so consumer
  * apps don't need to synthesize them.
  */
+/**
+ * Write a pre-computed `--x -> value` record to the document root (web only).
+ * The single web writer primitive: both the preset path (`applyColorPresetVars`)
+ * and `BloomThemeProvider`'s dynamic-seed path feed their already-resolved vars
+ * through here, so the "write to document" logic lives in exactly one place.
+ */
+export function applyVarsToDocument(vars: Record<string, string>) {
+  if (Platform.OS !== 'web' || typeof document === 'undefined') return;
+  const root = document.documentElement.style;
+  for (const [key, value] of Object.entries(vars)) {
+    root.setProperty(key, value);
+  }
+}
+
 export function applyColorPresetVars(
   preset: AppColorName,
   resolved: 'light' | 'dark',
   accents?: ExplicitAccents,
 ) {
-  if (Platform.OS !== 'web' || typeof document === 'undefined') return;
   if (!APP_COLOR_PRESETS[preset]) return;
-
-  const vars = getResolvedTokens(preset, resolved, accents);
-  const root = document.documentElement.style;
-
-  for (const [key, value] of Object.entries(vars)) {
-    root.setProperty(key, value);
-  }
+  applyVarsToDocument(getResolvedTokens(preset, resolved, accents));
 }

package/src/theme/native-root-vars.native.ts

@@ -122,17 +122,26 @@ import { getResolvedTokens } from './token-registry';
  * Defensive guard: if a host ships a react-native-css build that doesn't expose
  * `rootVariables` as a callable (it always does on @3), we bail rather than throw.
  */
-export function applyNativeRootVars(
-  colorPreset: AppColorName,
-  mode: 'light' | 'dark',
-  accents?: ExplicitAccents,
-): void {
+/**
+ * Write a pre-computed `--x -> value` record into react-native-css's global
+ * `rootVariables` family. The single native writer primitive: both the preset
+ * path (`applyNativeRootVars`) and `BloomThemeProvider`'s dynamic-seed path feed
+ * their already-resolved vars through here, so the global-write logic lives in
+ * exactly one place.
+ */
+export function applyVarsToRootVariables(vars: Record<string, string>): void {
   if (typeof rootVariables !== 'function') return;
-
-  const vars = getResolvedTokens(colorPreset, mode, accents);
   for (const [key, value] of Object.entries(vars)) {
-    // The family is keyed by the bare name; `getResolvedTokens` keys include `--`.
+    // The family is keyed by the bare name; the var keys include `--`.
     const name = key.startsWith('--') ? key.slice(2) : key;
     rootVariables(name).set([[value]]);
   }
 }
+
+export function applyNativeRootVars(
+  colorPreset: AppColorName,
+  mode: 'light' | 'dark',
+  accents?: ExplicitAccents,
+): void {
+  applyVarsToRootVariables(getResolvedTokens(colorPreset, mode, accents));
+}

package/src/theme/native-root-vars.ts

@@ -31,6 +31,11 @@ import type { ExplicitAccents } from './preset-vars';
  * The signature is intentionally identical to those variants so the import site in
  * `BloomThemeProvider` is platform-agnostic.
  */
+/** Neutral-default no-op of the native root-vars writer primitive. */
+export function applyVarsToRootVariables(_vars: Record<string, string>): void {
+  // Intentionally empty — the native variant does the real work.
+}
+
 export function applyNativeRootVars(
   _colorPreset: AppColorName,
   _mode: 'light' | 'dark',

package/src/theme/native-root-vars.web.ts

@@ -18,6 +18,11 @@ import type { ExplicitAccents } from './preset-vars';
  * The signature is intentionally identical to the plain variant so the import
  * site in `BloomThemeProvider` is platform-agnostic.
  */
+/** Web no-op of the native root-vars writer primitive (web writes to the document). */
+export function applyVarsToRootVariables(_vars: Record<string, string>): void {
+  // Intentionally empty — web applies vars to `document.documentElement`.
+}
+
 export function applyNativeRootVars(
   _colorPreset: AppColorName,
   _mode: 'light' | 'dark',