@oxyhq/bloom 0.7.0 → 0.7.1

package/lib/typescript/module/theme/native-root-vars.d.ts

@@ -0,0 +1,89 @@
+import { type AppColorName } from './color-presets';
+/**
+ * Publish the active color preset's CSS custom properties into react-native-css's
+ * GLOBAL root-variable family so they reach the ENTIRE native app tree — including
+ * content rendered outside the React subtree of `BloomThemeProvider`: expo-router
+ * navigator screens, `Portal`s, `Dialog`/`BottomSheet` overlays, and any other host
+ * that paints through a separate React root.
+ *
+ * Why a global write is required (native only)
+ * --------------------------------------------
+ * react-native-css resolves a `var(--x)` reference (its `varResolver`) in this order:
+ *   1. `name in inheritedVariables`  — the React-context-inherited vars. This is what
+ *      `VariableContextProvider` populates, but it is React-context-scoped, so it only
+ *      reaches *direct descendants* of the provider in the React tree.
+ *   2. `inlineVariables[name]`        — same-component inline vars.
+ *   3. `variables[name]`             — resolved inherited vars.
+ *   4. `universalVariables(name)`    — a GLOBAL observable family.
+ *   5. `rootVariables(name)`         — a GLOBAL observable family.
+ *   6. the declared fallback.
+ *
+ * `BloomThemeProvider`'s `VariableContextProvider` only feeds path #1, so the navigator
+ * host and every portal/modal — which render outside that subtree — never see the
+ * preset vars and fall through to `rootVariables`/`universalVariables`. By default those
+ * families hold only react-native-css's own `__rn-css-rem`/`__rn-css-color` entries
+ * (Bloom's `global.css` defines the `hsl(var(--primary))` indirection but not the HSL
+ * triples themselves — those are injected at runtime), so the whole tree below the
+ * navigator renders monochrome. Writing the triples into `rootVariables` here is the
+ * exact same mechanism react-native-css uses for compiled `:root {}` / `@theme` vars
+ * (`StyleCollection.inject` does `rootVariables(name).set(valueArray)`), so portaled
+ * content resolves the palette identically regardless of React-tree position.
+ *
+ * Why a STATIC `import`, not a runtime `require` (critical)
+ * ---------------------------------------------------------
+ * react-native-css@3.0.7 ships both a `dist/commonjs` and a `dist/module` build, and
+ * Metro bundles BOTH. In `native-internal/root.js` the variable families are plain
+ * module-local consts — NOT `globalThis`-guarded the way `StyleCollection` is — so the
+ * commonjs `root.js` and the module `root.js` each instantiate their OWN separate
+ * `rootVariables` family. The react-native-css renderer (`react-native-css/src/components/View.tsx`
+ * → `varResolver`) imports its `root.js` via ESM `import`, i.e. the MODULE build. A
+ * runtime `require('react-native-css/native-internal')` resolves the package's `require`
+ * export condition → the COMMONJS build → a DIFFERENT family the renderer never
+ * subscribes to, so the writes are a silent no-op on device. A static top-level
+ * `import` resolves the `import` condition → the MODULE build → the renderer's instance.
+ *
+ * This plain file is the NATIVE/default variant (Metro selects it on iOS/Android,
+ * which have no `.native` override here); the web variant lives in the sibling
+ * `native-root-vars.web.ts` no-op, which web bundlers pick over this one. So the
+ * static `react-native-css/native-internal` import below is never pulled into a web
+ * bundle — only into native. This mirrors Bloom's existing platform-split convention
+ * (`color-scope/index.tsx` + `color-scope/index.web.tsx`, `FontLoader.native.tsx`).
+ *
+ * Keying contract (verified against react-native-css@3.0.7)
+ * ---------------------------------------------------------
+ * The `rootVariables` family is keyed by the BARE variable name, WITHOUT the leading
+ * `--`. The compiler strips it uniformly: a `:root { --primary: ... }` declaration is
+ * stored via `rule.v.push([property.slice(2), value])` then routed into
+ * `shared.rootVariables[name]`, and `@property --x` goes through
+ * `name.startsWith("--") ? name.slice(2) : name`. The lookup side matches: a `var(--x)`
+ * reference compiles to `[{}, "var", ident.slice(2)]`, so `varResolver` looks up the
+ * bare name. `buildScopeVars` returns keys WITH the `--` prefix, so we strip it before
+ * writing each entry.
+ *
+ * Value shape
+ * -----------
+ * Each entry is a `VariableValue[]` — an array of `[value, mediaCondition?]` tuples.
+ * Bloom's preset vars are unconditional, so each is a single-element `[[value]]`, e.g.
+ * `rootVariables('primary').set([['205 87% 53%']])`. This is the same shape the compiler
+ * emits for unconditional `:root` vars.
+ *
+ * This is native-only and additive: the `VariableContextProvider` wrapper stays (it is
+ * the correct, scoped mechanism for `BloomColorScope` subtree overrides and harmlessly
+ * covers direct descendants). The web fork (`native-root-vars.web.ts`) no-ops — web
+ * writes the same vars to `document.documentElement` via `applyColorPresetVars`.
+ */
+/**
+ * Write the preset's CSS vars to react-native-css's global `rootVariables` family
+ * so the whole native tree (navigator screens + portals/modals/bottom-sheets)
+ * resolves the active palette.
+ *
+ * Each `.set` notifies its own observers synchronously (react-native-css only
+ * batches notifications inside its own `StyleCollection.inject`; outside it,
+ * `observableBatch.current` is unset so every `.set` runs observers immediately),
+ * so sequential writes correctly trigger a re-render when the preset/mode changes.
+ *
+ * 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 declare function applyNativeRootVars(colorPreset: AppColorName, mode: 'light' | 'dark'): void;
+//# sourceMappingURL=native-root-vars.d.ts.map

package/lib/typescript/module/theme/native-root-vars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-root-vars.d.ts","sourceRoot":"","sources":["../../../../src/theme/native-root-vars.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAS3F"}

package/lib/typescript/module/theme/native-root-vars.web.d.ts

@@ -0,0 +1,20 @@
+import { type AppColorName } from './color-presets';
+/**
+ * Web fork of `applyNativeRootVars` — a no-op.
+ *
+ * On web, `BloomThemeProvider` already writes the active preset's CSS vars to
+ * `document.documentElement` via `applyColorPresetVars`, which the browser /
+ * react-native-web resolve natively. The native/default variant — the plain
+ * sibling `native-root-vars.ts` — instead publishes those vars into
+ * react-native-css's GLOBAL `rootVariables` family.
+ *
+ * Keeping the native variant's `react-native-css/native-internal` import out of
+ * the web bundle is the whole reason this is a platform-split module: web (and
+ * any non-NativeWind host) picks this `.web` fork over the plain file and so
+ * never statically pulls react-native-css internals.
+ *
+ * The signature is intentionally identical to the plain variant so the import
+ * site in `BloomThemeProvider` is platform-agnostic.
+ */
+export declare function applyNativeRootVars(_colorPreset: AppColorName, _mode: 'light' | 'dark'): void;
+//# sourceMappingURL=native-root-vars.web.d.ts.map

package/lib/typescript/module/theme/native-root-vars.web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-root-vars.web.d.ts","sourceRoot":"","sources":["../../../../src/theme/native-root-vars.web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAE7F"}

package/lib/typescript/module/theme/preset-vars.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preset-vars.d.ts","sourceRoot":"","sources":["../../../../src/theme/preset-vars.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAiC1F,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,YAAY,EACvB,IAAI,EAAE,OAAO,GAAG,MAAM,EACtB,OAAO,GAAE,iBAAsB,GAC9B,YAAY,CAqCd;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,YAAY,EACvB,IAAI,EAAE,OAAO,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,IAAI,CAQN"}
+{"version":3,"file":"preset-vars.d.ts","sourceRoot":"","sources":["../../../../src/theme/preset-vars.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAiC1F,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,YAAY,EACvB,IAAI,EAAE,OAAO,GAAG,MAAM,EACtB,OAAO,GAAE,iBAAsB,GAC9B,YAAY,CAwCd;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,YAAY,EACvB,IAAI,EAAE,OAAO,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,IAAI,CAQN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",

package/src/__tests__/native-root-vars.test.ts

@@ -0,0 +1,125 @@
+type SetCall = ReadonlyArray<readonly [string]>;
+
+/**
+ * Verifies the native/default variant `theme/native-root-vars.ts` publishes the
+ * active preset into react-native-css's GLOBAL `rootVariables` family with the
+ * exact keying and value shape react-native-css itself uses for compiled `:root`
+ * vars, and that the web fork `theme/native-root-vars.web.ts` is an inert no-op.
+ *
+ *  - keys are written WITHOUT the leading `--` (the family is keyed by the bare
+ *    name — confirmed against react-native-css@3.0.7's compiler, which stores
+ *    `:root { --x }` via `slice(2)` and looks up `var(--x)` by the bare name);
+ *  - each value is a single-element value-array `[[value]]` (`VariableValue[]`);
+ *  - the native variant reaches react-native-css via a STATIC ESM import (so
+ *    Metro resolves the `module` build — the SAME family the renderer reads);
+ *  - the web variant never imports react-native-css and writes nothing.
+ *
+ * react-native-css is NOT a Bloom dependency (it arrives transitively via the
+ * host's NativeWind install), so the subpath is mocked virtually here — both for
+ * the runtime `.set` capture AND so ts-jest can compile the static import. The
+ * ambient `src/react-native-css.d.ts` declares the subpath's types for `tsc`.
+ */
+describe('applyNativeRootVars (native variant)', () => {
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  it('writes preset vars to rootVariables with the leading -- stripped', () => {
+    const sets: Record<string, SetCall> = {};
+
+    jest.isolateModules(() => {
+      jest.doMock(
+        'react-native-css/native-internal',
+        () => ({
+          rootVariables: (name: string) => ({
+            set: (value: SetCall) => {
+              sets[name] = value;
+            },
+          }),
+        }),
+        { virtual: true },
+      );
+
+      const { applyNativeRootVars } = require('../theme/native-root-vars') as {
+        applyNativeRootVars: (preset: string, mode: 'light' | 'dark') => void;
+      };
+      applyNativeRootVars('blue', 'light');
+    });
+
+    // Keys are bare (no `--`), and the raw HSL triple is present unwrapped.
+    expect(sets).toHaveProperty('primary');
+    expect(sets).not.toHaveProperty('--primary');
+    expect(sets.primary).toEqual([['205 87% 53%']]);
+
+    // Resolved Tailwind v4 `--color-*` vars are written too, also bare-keyed.
+    expect(sets).toHaveProperty('color-primary');
+    expect(sets['color-primary']).toEqual([['hsl(205 87% 53%)']]);
+
+    // Every value is a single-element value-array `[[value]]` of strings.
+    for (const value of Object.values(sets)) {
+      expect(Array.isArray(value)).toBe(true);
+      expect(value).toHaveLength(1);
+      expect(value[0]).toHaveLength(1);
+      expect(typeof value[0]?.[0]).toBe('string');
+    }
+  });
+
+  it('reflects the resolved mode (dark preset differs from light)', () => {
+    const collect = (mode: 'light' | 'dark'): Record<string, SetCall> => {
+      const sets: Record<string, SetCall> = {};
+      jest.isolateModules(() => {
+        jest.doMock(
+          'react-native-css/native-internal',
+          () => ({
+            rootVariables: (name: string) => ({
+              set: (value: SetCall) => {
+                sets[name] = value;
+              },
+            }),
+          }),
+          { virtual: true },
+        );
+        const { applyNativeRootVars } = require('../theme/native-root-vars') as {
+          applyNativeRootVars: (preset: string, mode: 'light' | 'dark') => void;
+        };
+        applyNativeRootVars('teal', mode);
+      });
+      return sets;
+    };
+
+    expect(collect('light').background).not.toEqual(collect('dark').background);
+  });
+
+  it('guards when rootVariables is not callable (defensive, never throws)', () => {
+    jest.isolateModules(() => {
+      jest.doMock(
+        'react-native-css/native-internal',
+        () => ({ rootVariables: undefined }),
+        { virtual: true },
+      );
+      const { applyNativeRootVars } = require('../theme/native-root-vars') as {
+        applyNativeRootVars: (preset: string, mode: 'light' | 'dark') => void;
+      };
+      expect(() => applyNativeRootVars('blue', 'light')).not.toThrow();
+    });
+  });
+});
+
+describe('applyNativeRootVars (web fork)', () => {
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  it('no-ops on web (vars are written to documentElement there instead)', () => {
+    // The web fork must never touch react-native-css. We assert it neither
+    // imports the subpath nor throws — it is a pure no-op with the same
+    // signature as the native variant.
+    jest.isolateModules(() => {
+      const { applyNativeRootVars } = require('../theme/native-root-vars.web') as {
+        applyNativeRootVars: (preset: string, mode: 'light' | 'dark') => void;
+      };
+      expect(() => applyNativeRootVars('blue', 'light')).not.toThrow();
+      expect(applyNativeRootVars('blue', 'light')).toBeUndefined();
+    });
+  });
+});

package/src/react-native-css.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Ambient declaration for `react-native-css/native-internal`.
+ *
+ * react-native-css is NOT a Bloom dependency — it arrives transitively via the
+ * host app's NativeWind install (NativeWind 5 is built on react-native-css@3).
+ * Bloom's `native-root-vars.native.ts` statically imports `rootVariables` from
+ * this subpath so Metro resolves the `import` export condition to the package's
+ * `module` build — the SAME family instance the react-native-css renderer
+ * (`varResolver`) subscribes to. A runtime `require()` would resolve the
+ * `require` condition to the separate `commonjs` build, whose `rootVariables`
+ * is a distinct, un-observed family instance (see the file-level comment in
+ * `native-root-vars.native.ts`).
+ *
+ * Because the package isn't installed in Bloom, `tsc` can't see its published
+ * types, so we declare the slice we use here — typed to match react-native-css
+ * @3.0.7's `dist/typescript/.../native-internal/root.d.ts` exactly (no `any`,
+ * no shims). This file is `.native`-only in spirit; the web fork never imports
+ * the subpath, so on web bundlers the static import is never reached.
+ */
+declare module 'react-native-css/native-internal' {
+  /**
+   * A leaf style value. Mirrors react-native-css's `compiler.types`
+   * `StyleDescriptor`. Bloom only ever writes string HSL triples / `hsl(...)`
+   * strings, but the family is typed against the full descriptor union.
+   */
+  type StyleDescriptor =
+    | string
+    | number
+    | boolean
+    | undefined
+    | StyleDescriptor[];
+
+  /**
+   * A media-conditioned predicate guarding a variable value. Bloom never emits
+   * conditioned values (its preset vars are unconditional), so the inner shape
+   * is intentionally opaque here — declaring the full recursive union would
+   * duplicate a large compiler type we never construct.
+   */
+  type MediaCondition = readonly unknown[];
+
+  /**
+   * A single variable value: a `[value]` tuple, optionally guarded by media
+   * conditions. Mirrors react-native-css's `VariableValue`. `rootVariables(...).set`
+   * takes a `VariableValue[]` (the variable's full ordered value list).
+   */
+  type VariableValue =
+    | readonly [StyleDescriptor]
+    | readonly [StyleDescriptor, readonly MediaCondition[]];
+
+  /**
+   * The reactive cell react-native-css renders from. `rootVariables(name)`
+   * returns one of these; `.set` replaces its value list and notifies the
+   * renderer's subscribed effects. Mirrors `Observable<StyleDescriptor, VariableValue[]>`.
+   */
+  interface Observable {
+    set: (value: readonly VariableValue[]) => void;
+  }
+
+  /**
+   * The GLOBAL root-variable family — `rootVariables(name)` returns the
+   * observable for the bare variable `name` (no leading `--`). This is the
+   * exact callable react-native-css's compiled `:root {}` / `@theme` vars are
+   * written through (`StyleCollection.inject` → `rootVariables(name).set(...)`).
+   */
+  export const rootVariables: ((name: string) => Observable) & {
+    delete(name: string): boolean;
+    clear(): void;
+  };
+}

package/src/theme/BloomThemeProvider.tsx

@@ -27,7 +27,8 @@ import { FontLoader } from '../fonts/FontLoader';
 import { applyDarkClass, applyColorPresetVars } from './apply-dark-class';
 import { buildTheme } from './build-theme';
 import { type AppColorName } from './color-presets';
-import { buildNativePresetStyle } from './color-scope/style-builder';
+import { buildScopeVars, getVariableContextProvider } from './color-scope/style-builder';
+import { applyNativeRootVars } from './native-root-vars';
 import {
   readPersistedTheme,
   readPersistedThemeSync,
@@ -295,6 +296,17 @@ export function BloomThemeProvider({
     applyColorPresetVars(colorPreset, resolved);
   }, [effectiveMode, resolved, colorPreset]);
 
+  // Native only: publish the preset 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.
+  useIsomorphicLayoutEffect(() => {
+    applyNativeRootVars(colorPreset, resolved);
+  }, [colorPreset, resolved]);
+
   const contextValue = useMemo<BloomThemeContextValue>(
     () => ({
       theme: buildTheme(colorPreset, resolved, isAdaptive),
@@ -310,10 +322,15 @@ export function BloomThemeProvider({
   const shouldAwait = awaitHydration ?? Boolean(persistKey && storage);
   const isGated = shouldAwait && !hydrated;
 
-  const nativeVarsStyle = useMemo(
-    () => (Platform.OS === 'web' ? undefined : buildNativePresetStyle(colorPreset, resolved)),
+  // 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.
+  const nativeVars = useMemo(
+    () => (Platform.OS === 'web' ? null : buildScopeVars(colorPreset, resolved)),
     [colorPreset, resolved],
   );
+  const VariableProvider = getVariableContextProvider();
 
   const content = (
     <FontLoader enabled={fonts} fallback={onFontsLoading}>
@@ -321,12 +338,21 @@ export function BloomThemeProvider({
     </FontLoader>
   );
 
+  if (Platform.OS === 'web') {
+    return <BloomThemeContext.Provider value={contextValue}>{content}</BloomThemeContext.Provider>;
+  }
+
+  // The flex wrapper is still needed for layout; the preset vars now flow
+  // through `VariableContextProvider` rather than an (inert) inline-vars style.
+  // If NativeWind isn't installed the wrapper still renders so we never crash.
+  const nativeTree = <View style={[{ flex: 1 }, nativeWrapperStyle]}>{content}</View>;
+
   return (
     <BloomThemeContext.Provider value={contextValue}>
-      {Platform.OS === 'web' ? (
-        content
+      {VariableProvider && nativeVars ? (
+        <VariableProvider value={nativeVars}>{nativeTree}</VariableProvider>
       ) : (
-        <View style={[{ flex: 1 }, nativeVarsStyle, nativeWrapperStyle]}>{content}</View>
+        nativeTree
       )}
     </BloomThemeContext.Provider>
   );