@oxyhq/bloom 0.78.0 → 0.79.1

package/src/provider/index.tsx

@@ -18,11 +18,13 @@
  * Nesting extra contexts costs nothing at runtime — the win is that scope is no
  * longer a per-app decision.
  *
- * EXPO/EXPO-ROUTER APPS ONLY. The scroll-restoration provider it mounts imports
- * `expo-router` (its web implementation keys offsets on the focused route), so
- * a Vite/SPA consumer that has no expo-router cannot resolve this module. Those
- * apps keep mounting `BloomThemeProvider` (and any other piece they need)
- * directly — that is not a lesser path, just the one without a router.
+ * EXPO/EXPO-ROUTER APPS ONLY, and now for one narrow reason: it binds the
+ * scroll store to the expo-router ADAPTER, which is the only module in the
+ * scroll primitive that imports `expo-router`. The scroll core itself is
+ * router-agnostic, so a Vite/SPA consumer can mount
+ * `<ScrollRestorationProvider adapter={...}>` from `@oxyhq/bloom/scroll` with
+ * an adapter for its own router — alongside `BloomThemeProvider` and whatever
+ * else it needs — rather than going without.
  *
  * NOT included, on purpose — these are OUTLETS, not state, and their placement
  * in the tree is a real app decision (z-order, safe areas, and mounting a
@@ -36,7 +38,8 @@ import { ImageResolverProvider, type ImageResolver } from '../image-resolver';
 import { BloomHapticsProvider } from '../hooks/useHaptics';
 import { TabBarMinimizeProvider } from '../tab-bar/minimize-context';
 import { BloomThemeProvider, type BloomThemeProviderProps } from '../theme';
-import { ScrollRestorationProvider } from './scroll-provider';
+import { ScrollRestorationProvider } from '../scroll/context';
+import { expoRouterScrollAdapter } from '../scroll/expo-router';
 
 export interface BloomProviderProps extends Omit<BloomThemeProviderProps, 'children'> {
   children: ReactNode;
@@ -61,7 +64,7 @@ export function BloomProvider({
     // never changes the tree shape and remounts everything below it.
     <ImageResolverProvider value={imageResolver ?? null}>
       <BloomThemeProvider {...themeProps}>
-        <ScrollRestorationProvider>
+        <ScrollRestorationProvider adapter={expoRouterScrollAdapter}>
           <BloomHapticsProvider enabled={haptics}>
             <TabBarMinimizeProvider>{children}</TabBarMinimizeProvider>
           </BloomHapticsProvider>

package/src/scroll/context.tsx

@@ -0,0 +1,107 @@
+/**
+ * The provider and context both platform barrels share.
+ *
+ * Nothing here is platform-specific: the provider holds an offset store and the
+ * router adapter, and that composition is identical on web and native. Keeping
+ * it in one module also guarantees ONE context identity — a provider mounted
+ * from the native barrel and a hook imported from the web barrel would
+ * otherwise read two different contexts and the hook would throw.
+ */
+import { createContext, useContext, useEffect, useMemo } from 'react';
+
+import { ScrollOffsetStore } from './store';
+import type {
+  ScrollRestorationProviderProps,
+  ScrollRouterAdapter,
+} from './types';
+
+export interface ScrollRestorationContextValue {
+  store: ScrollOffsetStore;
+  adapter: ScrollRouterAdapter;
+}
+
+const ScrollRestorationContext =
+  createContext<ScrollRestorationContextValue | null>(null);
+ScrollRestorationContext.displayName = 'BloomScrollRestorationContext';
+
+/**
+ * Holds the offset map and the router binding for the subtree. One provider
+ * near the app root is enough; the store lives as long as the provider, so
+ * offsets survive navigating away and back (including browser Back/Forward).
+ */
+export function ScrollRestorationProvider({
+  children,
+  adapter,
+}: ScrollRestorationProviderProps) {
+  const store = useMemo(() => new ScrollOffsetStore(), []);
+  const value = useMemo(() => ({ store, adapter }), [store, adapter]);
+
+  useManualBrowserScrollRestoration();
+
+  return (
+    <ScrollRestorationContext.Provider value={value}>
+      {children}
+    </ScrollRestorationContext.Provider>
+  );
+}
+
+export function useScrollRestorationContext(): ScrollRestorationContextValue {
+  const value = useContext(ScrollRestorationContext);
+  if (value === null) {
+    throw new Error(
+      'useScrollRestoration must be used within a <ScrollRestorationProvider>.',
+    );
+  }
+  return value;
+}
+
+/**
+ * Take over scroll restoration from the browser for as long as this provider is
+ * mounted, and hand it back both on unmount and on `pagehide`.
+ *
+ * The browser's default `'auto'` restoration fights our restore on
+ * Back/Forward, so it has to be turned off — but only while something is
+ * actually going to restore instead. Two moments where that stops being true:
+ *
+ *  - **Unmount.** This used to run at MODULE scope, which meant merely
+ *    importing the module disabled the browser's own restoration. Now that the
+ *    core is importable by apps that mount no provider (and by SSR and Node
+ *    tooling), that would have left those apps with neither restoration. Tying
+ *    the switch to the provider's lifetime makes it describe exactly the period
+ *    during which a replacement exists. The provider mounts at the app root on
+ *    the first commit, which is before any navigation can create a history
+ *    entry, so nothing is lost by not doing it at module scope.
+ *  - **`pagehide`.** The offset map lives in memory only. A reload starts with
+ *    an empty one, and a bfcache restore resumes a document whose provider is
+ *    already mounted and whose focus effects therefore never re-run — so in
+ *    both cases `'manual'` means NOBODY restores. Handing the mode back to the
+ *    browser on the way out lets it do the job we are no longer able to.
+ *    (react-router does exactly this, for the same reason.)
+ *
+ * The feature detect is also the platform test — `history` exists on web and
+ * nowhere else — so this stays one implementation rather than a fork. On React
+ * Native and during SSR it is a no-op.
+ */
+function useManualBrowserScrollRestoration(): void {
+  useEffect(() => {
+    if (
+      typeof window === 'undefined' ||
+      typeof history === 'undefined' ||
+      !('scrollRestoration' in history)
+    ) {
+      return undefined;
+    }
+    const previous = history.scrollRestoration;
+    history.scrollRestoration = 'manual';
+
+    const handBackToBrowser = () => {
+      history.scrollRestoration = 'auto';
+    };
+    window.addEventListener('pagehide', handBackToBrowser);
+
+    return () => {
+      window.removeEventListener('pagehide', handBackToBrowser);
+      history.scrollRestoration = previous;
+    };
+  }, []);
+}

package/src/scroll/expo-router/index.ts

@@ -0,0 +1,140 @@
+/**
+ * The expo-router binding for `@oxyhq/bloom/scroll`.
+ *
+ * This is the only file in the scroll primitive that knows a router exists. It
+ * is separate from the core so a consumer with a different router — or none —
+ * can still use the core with its own adapter; before the split, a module-scope
+ * `expo-router` import made the whole subpath unresolvable for them.
+ *
+ * The navigation hooks come from `expo-router` (which re-exports React
+ * Navigation's) rather than from `@react-navigation/native` directly. Every Oxy
+ * app uses expo-router as its router, so it is always a DIRECT, top-level
+ * dependency that resolves cleanly under Bun's isolated linker — whereas
+ * `@react-navigation/native` is only a nested/transitive dependency of
+ * expo-router and would fail to resolve when bundling those apps.
+ */
+import { useMemo } from 'react';
+import { useFocusEffect, useRoute } from 'expo-router';
+
+import type { ScreenFocusEffect, ScrollRouterAdapter } from '../types';
+
+/**
+ * Params that describe how a screen was REACHED rather than what it shows, and
+ * so must not contribute to a content id — the same screen showing the same
+ * thing would otherwise get two ids depending on how the user got there.
+ *
+ * - `screen` / `params` are React Navigation's nested-navigator plumbing.
+ *   expo-router strips both wherever it derives a URL from state
+ *   (`global-state/getRouteInfoFromState.js` deletes them before building the
+ *   pathname; `global-state/stateUtils.js` deletes `screen` from a payload;
+ *   `hooks/useSearchParams.js` skips both).
+ * - `initial` is React Navigation's reserved anchor flag, set by expo-router's
+ *   `withAnchor` handling in `global-state/getNavigationAction.js` — which also
+ *   warns if an app supplies it as a real param.
+ */
+const NON_CONTENT_PARAM_KEYS = new Set(['screen', 'params', 'initial']);
+
+/**
+ * expo-router's own internal params all carry this prefix
+ * (`build/navigationParams.js` — `__internal_expo_router_no_animation`,
+ * `__internal__expo_router_is_preview_navigation`, and the two zoom-transition
+ * ids, verified identical in expo-router 56.2.10 and 57.0.9). They are appended
+ * to the params of an ordinary navigation, so matching the prefix rather than
+ * the four literals means a fifth one added upstream cannot silently split one
+ * screen's content id in two.
+ */
+const INTERNAL_PARAM_PREFIX = '__internal';
+
+/**
+ * Depth at which nested param objects stop being described. React Navigation
+ * expects params to be serializable, but nothing enforces it, and a serializer
+ * that a cyclic value can hang is not one to put on a render path. Four levels
+ * is far past anything a URL produces.
+ */
+const MAX_PARAM_DEPTH = 4;
+
+function serializeValue(value: unknown, depth: number): string {
+  if (value === undefined) return '~undefined';
+  if (value === null) return '~null';
+  // JSON.stringify quotes and escapes, so a string can never be confused with
+  // a marker above or with the punctuation of a nested structure below.
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  if (depth >= MAX_PARAM_DEPTH) return '~deep';
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => serializeValue(entry, depth + 1)).join(',')}]`;
+  }
+  if (typeof value === 'object') {
+    const source = value as Record<string, unknown>;
+    return `{${Object.keys(source)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${serializeValue(source[key], depth + 1)}`)
+      .join(',')}}`;
+  }
+  // A function, symbol or bigint reached a screen's params. Nothing about it
+  // identifies content, and it cannot be compared across renders anyway.
+  return '~opaque';
+}
+
+/**
+ * Render a screen's params as a stable string. Keys are SORTED so params that
+ * differ only in insertion order — routinely, since expo-router rebuilds the
+ * object on every navigation — can never produce two ids for one screen.
+ *
+ * The exclusions apply at the top level only, because that is where React
+ * Navigation and expo-router inject theirs; a nested user object keeps every
+ * key it has.
+ */
+function serializeContentParams(params: object | undefined): string {
+  if (params === undefined) return '';
+  const source = params as Record<string, unknown>;
+  return Object.keys(source)
+    .filter(
+      (key) =>
+        !NON_CONTENT_PARAM_KEYS.has(key) && !key.startsWith(INTERNAL_PARAM_PREFIX),
+    )
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${serializeValue(source[key], 1)}`)
+    .join(',');
+}
+
+/**
+ * Identify WHAT the calling screen is showing: its route name plus its params.
+ *
+ * `useRoute()` is the source, and it has to be: it reads the route object of
+ * the nearest screen, so a background screen keeps reporting its own content.
+ * `usePathname()` would not do — it reads the globally focused route, so a
+ * background screen would adopt the foreground one's pathname and save its
+ * offset under a key that is not its own.
+ *
+ * `route.key` is deliberately NOT part of this. An offset belongs to what the
+ * user was looking at, not to the history slot it occupied — see
+ * `deriveScrollKey` for the full reasoning and the trade it makes.
+ *
+ * Params are what separate two screens sharing a route name. That matters most
+ * where expo-router RECYCLES a route object: `layouts/StackClient.js` reuses
+ * the current route — key included — when `NAVIGATE` targets the current route
+ * name and `getSingularId` matches, i.e. when only the query changed. Measured
+ * on 56.2.10 and 57.0.9: `search?q=cats` -> `search?q=dogs` keeps one key and
+ * swaps `params`, so without the params the two searches would share an offset.
+ */
+function useScreenContentId(): string | null {
+  const route = useRoute();
+  const contentId = `${route.name}?${serializeContentParams(route.params)}`;
+  return useMemo(() => contentId, [contentId]);
+}
+
+function useScreenFocusEffect(effect: ScreenFocusEffect): void {
+  useFocusEffect(effect);
+}
+
+/**
+ * The adapter to hand `<ScrollRestorationProvider adapter={...}>` in an
+ * expo-router app. A module-level constant, as the adapter contract requires.
+ */
+export const expoRouterScrollAdapter: ScrollRouterAdapter = {
+  useScreenContentId,
+  useScreenFocusEffect,
+};

package/src/scroll/index.ts

@@ -1,47 +1,114 @@
 /**
- * Native variant of the scroll-restoration primitive — a deliberate no-op.
+ * Native variant of the scroll-restoration primitive.
  *
- * React Navigation's native-stack keeps every screen mounted while it is in the
- * stack, so a list's scroll position survives a push/pop for free. There is
- * nothing to save or restore. We still ship the full API surface (provider +
- * hook) so consumers write one set of call sites that compile and run on every
- * platform; on native the provider just renders its children and the hook does
- * nothing.
+ * React Navigation's native-stack keeps every screen MOUNTED while it is in the
+ * stack, so a list's scroll position survives a push/pop for free — this file
+ * must not interfere with that, and does not: nothing here runs on focus.
+ *
+ * What native does not survive is a KEY CHANGE: an in-screen tab or folder swap
+ * that re-keys a list, and a screen that genuinely unmounts and remounts. The
+ * effect below is therefore keyed on the storage key (plus `enabled`) rather
+ * than on focus, which draws exactly that line with no bookkeeping: React
+ * re-runs it when the key changes and leaves it alone when a push/pop merely
+ * re-focuses the same screen showing the same content.
  *
  * Web bundlers select `./index.web` via the `"browser"` export condition in
  * `package.json`; native bundlers fall through to this file.
  */
-import type { ReactElement } from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { useScrollRestorationContext } from './context';
+import { createScroller } from './scrollable.native';
+import { deriveScrollKey } from './store';
 import type {
-  ScrollRestorationProviderProps,
+  ScrollRestorationBinding,
   ScrollRestorationTarget,
   UseScrollRestorationOptions,
 } from './types';
 
+export { ScrollRestorationProvider } from './context';
+
 export type {
+  ScreenFocusEffect,
   ScrollableHandle,
+  ScrollRestorationBinding,
   ScrollRestorationProviderProps,
   ScrollRestorationTarget,
+  ScrollRouterAdapter,
   UseScrollRestorationOptions,
 } from './types';
 
 /**
- * No-op provider. Renders children unchanged — native scroll persistence is
- * handled by the navigator, so no per-route state is kept.
- */
-export function ScrollRestorationProvider({
-  children,
-}: ScrollRestorationProviderProps): ReactElement {
-  return children as ReactElement;
-}
-
-/**
- * No-op hook. Accepts the same arguments as the web implementation so call
- * sites are identical across platforms.
+ * Preserve and restore the scroll offset of `target` across content changes,
+ * keyed by the content its screen is showing plus an optional `options.key`.
+ *
+ * Behaviour (native):
+ * - Offsets are recorded from the returned `onScroll` binding, which the caller
+ *   wires onto the list. There is no other way to observe a list's offset.
+ * - When the storage key changes — a re-keyed list, a remount, or `enabled`
+ *   turning on — the saved offset is applied, or 0 when the key was never seen.
+ * - A push/pop that re-focuses the same screen scrolls nothing. The navigator
+ *   already preserved the position, and re-applying it would at best be a
+ *   no-op and at worst fight a list that has legitimately moved on.
  */
 export function useScrollRestoration(
-  _target: ScrollRestorationTarget,
-  _options?: UseScrollRestorationOptions,
-): void {
-  // Intentionally empty: native-stack already preserves scroll position.
+  target: ScrollRestorationTarget,
+  options?: UseScrollRestorationOptions,
+): ScrollRestorationBinding {
+  const { store, adapter } = useScrollRestorationContext();
+  const contentId = adapter.useScreenContentId();
+  const enabled = options?.enabled ?? true;
+  const scrollKey = deriveScrollKey(contentId, options?.key);
+
+  // The key the live `onScroll` binding is allowed to record against. It is
+  // assigned by the effect below only AFTER that effect's own write has landed,
+  // and cleared by its cleanup — so the relayout the outgoing content emits
+  // while a new key is already rendered is never attributed to the new key.
+  const recordingKeyRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!enabled || scrollKey === null) return undefined;
+
+    const scroller = createScroller(target);
+    let frame: number | null = null;
+
+    // Restore and reset are ONE write: a miss reads 0, and 0 is exactly what a
+    // list showing content never seen this session must be sent to rather than
+    // left at the offset its predecessor had.
+    const apply = (): void => {
+      frame = null;
+      scroller.setOffset(store.read(scrollKey));
+      recordingKeyRef.current = scrollKey;
+    };
+
+    // Defer one frame. This effect fires in the same commit that rendered the
+    // incoming rows, and a list cannot honour an offset before it has laid them
+    // out — the write would be clamped to whatever height it has reached so
+    // far, with no second chance (unlike web, native gets no scroll event to
+    // re-apply from). One frame is all that is needed because `enabled` has
+    // already guaranteed the rows are there; what remains is the layout pass.
+    if (typeof requestAnimationFrame === 'function') {
+      frame = requestAnimationFrame(apply);
+    } else {
+      // No frame scheduler (SSR, or a bare Node import of this barrel).
+      // Applying immediately is still the correct write; only the wait is lost.
+      apply();
+    }
+
+    return () => {
+      if (frame !== null) cancelAnimationFrame(frame);
+      recordingKeyRef.current = null;
+    };
+  }, [store, scrollKey, enabled, target]);
+
+  const onScroll = useCallback<ScrollRestorationBinding['onScroll']>(
+    (event) => {
+      const key = recordingKeyRef.current;
+      if (key === null) return;
+      store.save(key, event.nativeEvent.contentOffset.y);
+    },
+    [store],
+  );
+
+  return useMemo(() => ({ onScroll }), [onScroll]);
 }