@oxyhq/bloom 0.44.0 → 0.45.0

package/src/__tests__/ambient-theme.test.tsx

@@ -0,0 +1,136 @@
+import React from 'react';
+import { Text, Pressable } from 'react-native';
+import { act, render, fireEvent } from '@testing-library/react-native';
+
+import { BloomThemeProvider } from '../theme/BloomThemeProvider';
+import { useTheme } from '../theme/use-theme';
+import {
+  useAmbientTheme,
+  ambientTheme,
+  __flushAmbientForTests,
+  __resetAmbientForTests,
+} from '../theme/ambient-store';
+import { buildThemeFromSeed } from '../theme/build-theme-from-seed';
+import { buildTheme } from '../theme/build-theme';
+
+const OXY_PRESET_PRIMARY = buildTheme('oxy', 'light', false).colors.primary;
+const RED_SEED = '#ff0000';
+const RED_SEED_PRIMARY = buildThemeFromSeed(RED_SEED, 'light').colors.primary;
+
+function PrimaryProbe() {
+  const theme = useTheme();
+  return <Text testID="primary">{theme.colors.primary}</Text>;
+}
+
+function AmbientDriver({ debounceMs }: { debounceMs?: number }) {
+  const { seed, setAmbient, clearAmbient } = useAmbientTheme({ debounceMs });
+  return (
+    <>
+      <Text testID="ambient-seed">{seed ?? 'null'}</Text>
+      <Pressable testID="set" onPress={() => setAmbient(RED_SEED)} />
+      <Pressable testID="clear" onPress={() => clearAmbient()} />
+    </>
+  );
+}
+
+describe('ambient theme store', () => {
+  beforeEach(() => {
+    __resetAmbientForTests();
+  });
+  afterEach(() => {
+    __resetAmbientForTests();
+  });
+
+  it('starts empty and returns a stable snapshot ref while unchanged', () => {
+    const { getByTestId } = render(
+      <BloomThemeProvider>
+        <AmbientDriver debounceMs={0} />
+      </BloomThemeProvider>,
+    );
+    expect(getByTestId('ambient-seed').props.children).toBe('null');
+  });
+
+  it('debounces setAmbient and coalesces rapid calls', () => {
+    ambientTheme.setAmbient('#111111');
+    ambientTheme.setAmbient('#222222');
+    ambientTheme.setAmbient(RED_SEED);
+    // Nothing committed yet — still debouncing.
+    expect(ambientTheme.getState().seed).toBeNull();
+    act(() => {
+      __flushAmbientForTests();
+    });
+    // Only the LAST call wins.
+    expect(ambientTheme.getState().seed).toBe(RED_SEED);
+  });
+
+  it('applies debounceMs: 0 synchronously', () => {
+    const { getByTestId } = render(
+      <BloomThemeProvider>
+        <AmbientDriver debounceMs={0} />
+      </BloomThemeProvider>,
+    );
+    act(() => {
+      fireEvent.press(getByTestId('set'));
+    });
+    expect(getByTestId('ambient-seed').props.children).toBe(RED_SEED);
+  });
+});
+
+describe('BloomThemeProvider ambient override / restore', () => {
+  beforeEach(() => {
+    __resetAmbientForTests();
+  });
+  afterEach(() => {
+    __resetAmbientForTests();
+  });
+
+  it('overrides the preset while ambient is set and restores it on clear', () => {
+    const { getByTestId } = render(
+      <BloomThemeProvider>
+        <PrimaryProbe />
+        <AmbientDriver debounceMs={0} />
+      </BloomThemeProvider>,
+    );
+    // Baseline: the oxy preset.
+    expect(getByTestId('primary').props.children).toBe(OXY_PRESET_PRIMARY);
+
+    act(() => {
+      fireEvent.press(getByTestId('set'));
+    });
+    // Ambient seed themes the whole app from the red seed.
+    expect(getByTestId('primary').props.children).toBe(RED_SEED_PRIMARY);
+    expect(RED_SEED_PRIMARY).not.toBe(OXY_PRESET_PRIMARY);
+
+    act(() => {
+      fireEvent.press(getByTestId('clear'));
+    });
+    // Cleared → back to the preset.
+    expect(getByTestId('primary').props.children).toBe(OXY_PRESET_PRIMARY);
+  });
+
+  it('ambient overrides even a static seed prop, then restores it on clear', () => {
+    const staticSeed = '#00ff00';
+    const staticPrimary = buildThemeFromSeed(staticSeed, 'light').colors.primary;
+
+    const { getByTestId } = render(
+      <BloomThemeProvider seed={staticSeed}>
+        <PrimaryProbe />
+        <AmbientDriver debounceMs={0} />
+      </BloomThemeProvider>,
+    );
+    // Static seed prop is active.
+    expect(getByTestId('primary').props.children).toBe(staticPrimary);
+
+    act(() => {
+      fireEvent.press(getByTestId('set'));
+    });
+    // Ambient wins over the static seed prop.
+    expect(getByTestId('primary').props.children).toBe(RED_SEED_PRIMARY);
+
+    act(() => {
+      fireEvent.press(getByTestId('clear'));
+    });
+    // Restored to the static seed prop, NOT the preset.
+    expect(getByTestId('primary').props.children).toBe(staticPrimary);
+  });
+});

package/src/bottom-sheet/BottomSheetBase.tsx

@@ -818,6 +818,14 @@ const styles = StyleSheet.create({
     },
     nonScrollableContent: {
         flex: 1,
+        // A `scrollable={false}` sheet hands its own scrolling to a child
+        // VirtualizedList, which needs a BOUNDED height to scroll. The sheet is
+        // clamped by `maxHeight`, but on web a flex child defaults to
+        // `min-height: auto` and grows to its content instead of shrinking into
+        // that clamp — so the list overflows and is clipped (no scroll). Yoga
+        // already defaults min to 0 on native; making it explicit here fixes the
+        // web output so the bounded height propagates down to the list.
+        minHeight: 0,
     },
 });
 

package/src/theme/BloomThemeProvider.tsx

@@ -24,6 +24,8 @@ import {
 import { useControllableState } from '../hooks/useControllableState';
 import { FontLoader } from '../fonts/FontLoader';
 
+import { useAmbientThemeState } from './ambient-store';
+
 import { applyDarkClass, applyVarsToDocument } from './apply-dark-class';
 import { buildTheme } from './build-theme';
 import { buildThemeFromSeed } from './build-theme-from-seed';
@@ -332,16 +334,40 @@ export function BloomThemeProvider({
 }: BloomThemeProviderProps) {
   const rnScheme = useRNColorScheme();
 
+  // The app-wide ambient override, driven imperatively via `useAmbientTheme()`
+  // from anywhere in the app. Subscribed through the module-level store's
+  // `useSyncExternalStore` (stable snapshot ref while unchanged → React-Compiler
+  // safe). When an ambient seed is set it OVERRIDES the static `seed` prop and
+  // the active preset; clearing it restores them.
+  const ambient = useAmbientThemeState();
+
+  // The EFFECTIVE dynamic seed + accents for this render: ambient wins over the
+  // static props. `null` ambient seed means "no override" → fall back to the
+  // `seed` prop (which itself may be undefined → preset path). When ambient is
+  // active, ambient accents replace the static accent props entirely (a null
+  // ambient accent = "no pin for this artwork colour").
+  const ambientActive = ambient.seed !== null;
+  const effectiveSeed: string | undefined = ambientActive
+    ? ambient.seed ?? undefined
+    : seed;
+  const effectiveSecondary: string | undefined = ambientActive
+    ? ambient.secondary ?? undefined
+    : secondaryColor;
+  const effectiveTertiary: string | undefined = ambientActive
+    ? ambient.tertiary ?? undefined
+    : tertiaryColor;
+
   // The app-wide pinned accents, if any. Memoized so its identity only changes
-  // when a prop changes (keeps the effect/memo deps below stable). Left
+  // when an accent changes (keeps the effect/memo deps below stable). Left
   // `undefined` when neither is set so every downstream call is byte-identical
-  // to the no-accent path.
+  // to the no-accent path. Uses the EFFECTIVE accents so ambient accents apply
+  // to the preset path too when no ambient seed is present.
   const explicitAccents = useMemo<ExplicitAccents | undefined>(
     () =>
-      secondaryColor === undefined && tertiaryColor === undefined
+      effectiveSecondary === undefined && effectiveTertiary === undefined
         ? undefined
-        : { secondaryHex: secondaryColor, tertiaryHex: tertiaryColor },
-    [secondaryColor, tertiaryColor],
+        : { secondaryHex: effectiveSecondary, tertiaryHex: effectiveTertiary },
+    [effectiveSecondary, effectiveTertiary],
   );
 
   const { mode, colorPreset, setMode, setColorPreset, resetTheme, hydrated } = useThemeState({
@@ -371,20 +397,33 @@ export function BloomThemeProvider({
   // colour engine, so there is one code path — no seed/preset duplication.
   const themeVars = useMemo(
     () =>
-      seed
-        ? buildSeedScopeVars({ seed, mode: resolved, secondarySeed: secondaryColor, tertiarySeed: tertiaryColor })
+      effectiveSeed
+        ? buildSeedScopeVars({
+            seed: effectiveSeed,
+            mode: resolved,
+            secondarySeed: effectiveSecondary,
+            tertiarySeed: effectiveTertiary,
+          })
         : buildScopeVars(colorPreset, resolved, explicitAccents),
-    [seed, secondaryColor, tertiaryColor, colorPreset, resolved, explicitAccents],
+    [effectiveSeed, effectiveSecondary, effectiveTertiary, colorPreset, resolved, explicitAccents],
   );
   const themeColors = useMemo(
     () =>
-      seed
-        ? buildThemeFromSeed(seed, resolved, undefined, undefined, {
-            secondarySeed: secondaryColor,
-            tertiarySeed: tertiaryColor,
+      effectiveSeed
+        ? buildThemeFromSeed(effectiveSeed, resolved, undefined, undefined, {
+            secondarySeed: effectiveSecondary,
+            tertiarySeed: effectiveTertiary,
           })
         : buildTheme(colorPreset, resolved, isAdaptive, explicitAccents),
-    [seed, secondaryColor, tertiaryColor, colorPreset, resolved, isAdaptive, explicitAccents],
+    [
+      effectiveSeed,
+      effectiveSecondary,
+      effectiveTertiary,
+      colorPreset,
+      resolved,
+      isAdaptive,
+      explicitAccents,
+    ],
   );
 
   useIsomorphicLayoutEffect(() => {

package/src/theme/ambient-store.ts

@@ -0,0 +1,186 @@
+import { useSyncExternalStore } from 'react';
+
+/**
+ * The current ambient theme override. When `seed` is non-null the whole app is
+ * themed from this dynamic seed (same colour engine the `seed` prop uses),
+ * overriding the active preset / static `seed` prop. `secondary`/`tertiary` pin
+ * this seed's accent families (e.g. the 2nd/3rd colours extracted from artwork).
+ */
+export interface AmbientThemeState {
+  readonly seed: string | null;
+  readonly secondary: string | null;
+  readonly tertiary: string | null;
+}
+
+export interface AmbientAccents {
+  secondary?: string | null;
+  tertiary?: string | null;
+}
+
+export interface AmbientThemeApi {
+  /**
+   * Set the ambient seed (and optional accents). Coalesced through an internal
+   * debounce so rapid hover/scroll doesn't thrash the theme. The debounce lives
+   * HERE — apps never own one.
+   */
+  setAmbient: (seed: string, accents?: AmbientAccents) => void;
+  /** Clear the ambient override, restoring the preset (or the static `seed` prop). */
+  clearAmbient: () => void;
+}
+
+/** Options for {@link useAmbientTheme}. */
+export interface UseAmbientThemeOptions {
+  /**
+   * Debounce, in ms, applied to `setAmbient`/`clearAmbient` before the store
+   * commits. Default `120`. Pass `0` to apply synchronously.
+   */
+  debounceMs?: number;
+}
+
+const DEFAULT_DEBOUNCE_MS = 120;
+
+// A single frozen "no override" snapshot. `getSnapshot` returns this EXACT
+// reference whenever nothing is set, so `useSyncExternalStore` sees a stable
+// identity across renders (React-Compiler-safe: the memoized value never
+// silently goes stale because the snapshot ref only changes on a real commit).
+const EMPTY_STATE: AmbientThemeState = Object.freeze({
+  seed: null,
+  secondary: null,
+  tertiary: null,
+});
+
+let state: AmbientThemeState = EMPTY_STATE;
+const listeners = new Set<() => void>();
+
+// Pending debounced commit. `null` operation means "clear".
+let pendingTimer: ReturnType<typeof setTimeout> | null = null;
+let pendingCommit: (() => void) | null = null;
+
+function emit(): void {
+  for (const listener of listeners) listener();
+}
+
+function commit(next: AmbientThemeState): void {
+  // Skip a no-op commit so subscribers don't re-render for an identical value.
+  if (
+    next.seed === state.seed &&
+    next.secondary === state.secondary &&
+    next.tertiary === state.tertiary
+  ) {
+    return;
+  }
+  state = next;
+  emit();
+}
+
+function schedule(next: AmbientThemeState, debounceMs: number): void {
+  if (pendingTimer !== null) {
+    clearTimeout(pendingTimer);
+    pendingTimer = null;
+  }
+  const run = () => {
+    pendingTimer = null;
+    pendingCommit = null;
+    commit(next);
+  };
+  if (debounceMs <= 0) {
+    run();
+    return;
+  }
+  pendingCommit = run;
+  pendingTimer = setTimeout(run, debounceMs);
+  pendingTimer.unref?.();
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+function getSnapshot(): AmbientThemeState {
+  return state;
+}
+
+/** Internal setter used by the debounced hook API. */
+function setAmbientInternal(seed: string, accents: AmbientAccents | undefined, debounceMs: number): void {
+  schedule(
+    {
+      seed,
+      secondary: accents?.secondary ?? null,
+      tertiary: accents?.tertiary ?? null,
+    },
+    debounceMs,
+  );
+}
+
+/** Internal clear used by the debounced hook API. */
+function clearAmbientInternal(debounceMs: number): void {
+  schedule(EMPTY_STATE, debounceMs);
+}
+
+/**
+ * Read + drive the app-wide ambient theme. Reading returns the current override
+ * (via `useSyncExternalStore` — stable snapshot ref while unchanged); the
+ * returned `setAmbient`/`clearAmbient` are debounced imperative controls.
+ *
+ * `BloomThemeProvider` consumes the SAME store internally, so calling
+ * `setAmbient(...)` from anywhere themes the whole app through the provider's
+ * single apply path — no `seed` prop threading, no app-owned theming store.
+ */
+export function useAmbientTheme(
+  options?: UseAmbientThemeOptions,
+): AmbientThemeState & AmbientThemeApi {
+  const debounceMs = options?.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const current = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  return {
+    seed: current.seed,
+    secondary: current.secondary,
+    tertiary: current.tertiary,
+    setAmbient: (seed, accents) => setAmbientInternal(seed, accents, debounceMs),
+    clearAmbient: () => clearAmbientInternal(debounceMs),
+  };
+}
+
+/**
+ * Provider-side subscription. Returns the current ambient state with a stable
+ * ref while unchanged. Uses the same store, so it stays in lockstep with any
+ * `useAmbientTheme()` caller.
+ */
+export function useAmbientThemeState(): AmbientThemeState {
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * Non-hook imperative escape hatch (e.g. gesture handlers / worklets bridges /
+ * non-React callers). Same debounced store as {@link useAmbientTheme}.
+ */
+export const ambientTheme: AmbientThemeApi & { getState: () => AmbientThemeState } = {
+  setAmbient: (seed, accents) => setAmbientInternal(seed, accents, DEFAULT_DEBOUNCE_MS),
+  clearAmbient: () => clearAmbientInternal(DEFAULT_DEBOUNCE_MS),
+  getState: getSnapshot,
+};
+
+/** Test-only: flush any pending debounced commit synchronously. */
+export function __flushAmbientForTests(): void {
+  if (pendingCommit) {
+    if (pendingTimer !== null) {
+      clearTimeout(pendingTimer);
+      pendingTimer = null;
+    }
+    const run = pendingCommit;
+    pendingCommit = null;
+    run();
+  }
+}
+
+/** Test-only: reset the store to the empty state without notifying via debounce. */
+export function __resetAmbientForTests(): void {
+  if (pendingTimer !== null) {
+    clearTimeout(pendingTimer);
+    pendingTimer = null;
+  }
+  pendingCommit = null;
+  commit(EMPTY_STATE);
+}

package/src/theme/index.ts

@@ -30,6 +30,13 @@ export { buildThemeFromSeed, buildColorsFromSeed } from './build-theme-from-seed
 export type { SeedAccents } from './build-theme-from-seed';
 export { THEME_GRADIENTS } from './gradients';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
+export { useAmbientTheme, ambientTheme } from './ambient-store';
+export type {
+  AmbientThemeState,
+  AmbientThemeApi,
+  AmbientAccents,
+  UseAmbientThemeOptions,
+} from './ambient-store';
 export { useNavigationTheme } from './use-navigation-theme';
 export type { NavigationTheme, NavigationThemeFont } from './use-navigation-theme';
 export type { Theme, ThemeColors, ThemeMode, ThemeGradient, ThemeGradients } from './types';