@oxyhq/bloom 0.78.0 → 0.79.1

package/src/scroll/store.ts

@@ -3,16 +3,12 @@
  *
  * This file deliberately contains NO React and NO DOM/native imports so the
  * logic can be unit-tested in isolation and shared verbatim by the web and
- * native barrels. The web barrel drives it with real scroll offsets; the
- * native barrel never instantiates it (native-stack already restores scroll).
+ * native barrels.
  */
-
 /**
- * Separator between the navigation route key and an optional caller-supplied
- * sub-key. A route may host more than one independently-scrolling list (e.g.
- * a tabbed profile screen), so each list contributes its own sub-key.
+ * Separator between the two components of a storage key.
  *
- * `\0` (NUL) can never appear in a React Navigation route key or in a
+ * `\0` (NUL) can never appear in a router-derived content id or in a
  * developer-authored sub-key, so it is collision-free as a delimiter. It is
  * written as an escape sequence (not a literal byte) so the source stays
  * text-diffable.
@@ -20,31 +16,51 @@
 const COMPOSITE_KEY_SEPARATOR = '\0';
 
 /**
- * Derive the storage key for a scrollable from its owning route key and an
- * optional caller sub-key.
+ * Derive the storage key for a scrollable from WHAT its screen is showing plus
+ * an optional caller sub-key.
+ *
+ * The key is CONTENT identity, deliberately not the navigation entry. An offset
+ * belongs to what the user was looking at, so returning to it restores however
+ * they got there — browser Back or Forward, a tab press, an in-app link — and
+ * only content never seen this session opens at the top. Keying on the entry
+ * would defeat that: a tab press and `router.replace` both mint a fresh entry,
+ * so both would open at the top even though the user has been there.
+ *
+ * The trade, chosen rather than overlooked: the same content occupying two LIVE
+ * entries now shares one offset. Pushing `/@alice` on top of `/@alice` in a
+ * native stack restores the first one's position instead of opening at the top,
+ * and while both are mounted each writes to the same key. That is the price of
+ * a tab press restoring, which is the behaviour that was asked for.
  *
- * - `routeKey` is React Navigation's stable per-route `route.key`.
- * - `subKey` distinguishes multiple scrollables that share a single route.
+ * The key is always the same two-field composite, with an absent sub-key
+ * written as empty, so two different identities can never collapse onto one key
+ * by omission.
  *
- * Returns `null` when there is no route key to anchor against (the scrollable
- * is not inside a navigator), which the caller treats as "do not persist".
+ * Returns `null` when there is no content id to anchor against (the scrollable
+ * is not inside a navigator, or the adapter cannot answer), which every caller
+ * treats as "do not persist and do not restore".
  */
 export function deriveScrollKey(
-  routeKey: string | undefined,
+  contentId: string | null,
   subKey?: string,
 ): string | null {
-  if (!routeKey) return null;
-  if (subKey === undefined || subKey === '') return routeKey;
-  return `${routeKey}${COMPOSITE_KEY_SEPARATOR}${subKey}`;
+  if (!contentId) return null;
+  return [contentId, subKey ?? ''].join(COMPOSITE_KEY_SEPARATOR);
 }
 
 /**
  * In-memory map of `scrollKey -> last-known scroll offset`.
  *
- * Mirrors the semantics of Bluesky's `Map<screenKey, scrollY>`: offsets live
- * only for the lifetime of the document/session. We never persist them — a
- * full reload should start at the top — and we never auto-evict, because a
- * route can be revisited via browser Forward/Back long after it blurred.
+ * Offsets live only for the lifetime of the document/session. We never persist
+ * them — a full reload should start at the top — and we never auto-evict,
+ * because an entry can be revisited via browser Forward/Back long after it
+ * blurred.
+ *
+ * Deliberately an instance held in React context rather than a module-level
+ * singleton: a dependency tree can legitimately contain two copies of Bloom
+ * (a hoisted one plus a nested one under another Oxy package), and a
+ * module-global would then exist twice with no way for either half to see the
+ * other's offsets.
  */
 export class ScrollOffsetStore {
   private readonly offsets = new Map<string, number>();
@@ -55,19 +71,25 @@ export class ScrollOffsetStore {
   }
 
   /**
-   * Read the saved offset for a key. Returns `0` when nothing was saved, so
-   * callers can restore unconditionally (an unseen list restores to the top).
+   * Read the saved offset for a key. Returns `0` when nothing was saved, which
+   * is the same value a caller writes when {@link has} is false — an unseen
+   * list restores to the top.
    */
   read(key: string): number {
     return this.offsets.get(key) ?? 0;
   }
 
-  /** Whether an offset was ever saved for this key. */
+  /**
+   * Whether an offset was ever saved for this key. This — not `read() > 0` —
+   * is what separates "restore" from "reset": a key that was never seen and a
+   * key deliberately saved at the top both read 0, and only the store knows
+   * which is which.
+   */
   has(key: string): boolean {
     return this.offsets.has(key);
   }
 
-  /** Drop a saved offset (e.g. when a route is permanently removed). */
+  /** Drop a saved offset (e.g. when an entry is permanently removed). */
   forget(key: string): void {
     this.offsets.delete(key);
   }

package/src/scroll/types.ts

@@ -1,21 +1,25 @@
 import type { ReactNode, RefObject } from 'react';
+import type { NativeScrollEvent, NativeSyntheticEvent } from 'react-native';
 
 /**
  * Anything `useScrollRestoration` knows how to read/write a vertical scroll
  * offset from. The hook accepts a ref to one of these:
  *
- * - a React Native `ScrollView` / `FlatList` ref (which on web is backed by a
- *   DOM node and exposes `getScrollableNode()`),
+ * - a React Native `ScrollView` / `FlatList` / `FlashList` ref (which on web is
+ *   backed by a DOM node and exposes `getScrollableNode()`),
  * - a raw DOM element ref (when a component renders its own scroll container),
- * - the literal `'window'` sentinel, for the rare layout where the list IS the
- *   window scroller (matches Bluesky's default).
+ * - the literal `'window'` sentinel, for the layout where the list IS the
+ *   document scroller.
  *
- * Native never reads any of these — the native hook is a no-op — so the type is
- * intentionally permissive rather than coupled to a specific RN class.
+ * The two imperative methods are the native write path; web writes `scrollTop`
+ * on the resolved DOM node instead. Both are optional because a given ref only
+ * ever exposes one of them (list vs. scroll view).
  */
 export interface ScrollableHandle {
-  /** Imperative scroll API exposed by RN scrollables. */
+  /** `ScrollView`'s imperative scroll API. */
   scrollTo?: (options: { x?: number; y?: number; animated?: boolean }) => void;
+  /** `FlatList`/`FlashList`'s imperative scroll API. */
+  scrollToOffset?: (options: { offset: number; animated?: boolean }) => void;
   /** Web/RNW path: returns the underlying DOM node. */
   getScrollableNode?: () => unknown;
 }
@@ -28,21 +32,87 @@ export type ScrollRestorationTarget =
   | RefObject<unknown>
   | 'window';
 
+/** The effect shape `useScreenFocusEffect` runs — mirrors `useEffect`'s. */
+export type ScreenFocusEffect = () => (() => void) | void;
+
+/**
+ * The router bindings the scroll core needs, and the ONLY thing it knows about
+ * routing. Keeping this to two hooks is what lets the core ship without a
+ * router import, so a Vite/SPA consumer can supply its own adapter (or none).
+ *
+ * Both members are HOOKS: the core calls them from `useScrollRestoration`, so
+ * the adapter value must be referentially stable for the lifetime of the
+ * provider (a module-level constant, which is what every adapter Bloom ships
+ * is). Swapping in a different adapter at runtime would change the hook order
+ * of every consumer below it.
+ */
+export interface ScrollRouterAdapter {
+  /**
+   * Identify WHAT the calling screen is showing — its route and params, not the
+   * history slot it occupies. Offsets are remembered per content, so returning
+   * to something already seen restores it however the user got there.
+   *
+   * It must describe the screen the CALLER is rendered inside, never the
+   * globally focused one: a background screen has to keep reporting its own
+   * content, or it would save its offset under the foreground screen's key.
+   *
+   * `null` when the adapter cannot answer (a scrollable rendered outside any
+   * navigator), which makes the hook inert rather than guessing.
+   */
+  useScreenContentId(): string | null;
+  /**
+   * Run `effect` while the calling screen is focused, and its cleanup on blur.
+   * Re-runs when `effect`'s identity changes AND the screen is focused — that
+   * is what makes an in-screen key change (a tab or folder swap) visible to a
+   * hook that never blurred.
+   */
+  useScreenFocusEffect(effect: ScreenFocusEffect): void;
+}
+
 export interface UseScrollRestorationOptions {
   /**
-   * Sub-key to disambiguate multiple scrollables that live on the same route
-   * (e.g. the tabs of a profile screen). Combined with the active route key to
-   * form the storage key. Omit when a route has a single scrollable.
+   * Sub-key distinguishing scrollables that share one screen AND one content
+   * id — the tabs of a profile, the folders of a saved-items screen. Changing
+   * it while the screen stays focused saves the outgoing list's offset and
+   * restores (or resets) the incoming one.
    */
   key?: string;
   /**
-   * When `false`, the hook is inert (saves and restores are skipped). Useful to
-   * gate restoration behind a feature flag without changing call sites.
+   * When `false` the hook is completely inert: no save, no restore, no reset.
+   *
+   * On NATIVE this is load-bearing rather than a feature flag. Restoring into a
+   * list whose rows have not been laid out yet lands at the wrong place (or is
+   * clamped away), and native has no equivalent of the web path's re-apply
+   * loop — so the caller gates on its own content being present, e.g.
+   * `enabled: rows.length > 0`. Flipping it from `false` to `true` is what
+   * triggers the restore.
+   *
    * Defaults to `true`.
    */
   enabled?: boolean;
 }
 
+/**
+ * What `useScrollRestoration` hands back. Identical on both platforms so call
+ * sites are written once.
+ */
+export interface ScrollRestorationBinding {
+  /**
+   * Wire onto the list being restored: `<FlashList onScroll={scroll.onScroll}>`.
+   *
+   * Native has no way to observe a list's offset from outside it, so this is
+   * how offsets are recorded there. On web it is a stable no-op — the web path
+   * subscribes to the resolved DOM node's own `scroll` event, which needs
+   * nothing from the caller — and passing it costs nothing.
+   */
+  onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+}
+
 export interface ScrollRestorationProviderProps {
   children: ReactNode;
+  /**
+   * Binds the store to a router. Must be referentially stable — see
+   * {@link ScrollRouterAdapter}.
+   */
+  adapter: ScrollRouterAdapter;
 }

package/src/theme/__tests__/__fixtures__/golden-resolved-tokens.json

@@ -66,8 +66,8 @@
     "--surface-foreground": "rgb(215 229 232)",
     "--popover": "rgb(21 34 36)",
     "--popover-foreground": "rgb(215 229 232)",
-    "--primary": "rgb(80 150 161)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(55 126 138)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(213 49 120)",
     "--secondary-foreground": "rgb(255 255 255)",
     "--tertiary": "rgb(174 97 0)",
@@ -186,8 +186,8 @@
     "--surface-foreground": "rgb(220 227 238)",
     "--popover": "rgb(25 32 40)",
     "--popover-foreground": "rgb(220 227 238)",
-    "--primary": "rgb(29 155 240)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(0 121 192)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(214 58 43)",
     "--secondary-foreground": "rgb(255 255 255)",
     "--tertiary": "rgb(252 220 0)",
@@ -306,8 +306,8 @@
     "--surface-foreground": "rgb(217 230 220)",
     "--popover": "rgb(23 34 28)",
     "--popover-foreground": "rgb(217 230 220)",
-    "--primary": "rgb(16 185 129)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(0 133 91)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(216 52 80)",
     "--secondary-foreground": "rgb(255 255 255)",
     "--tertiary": "rgb(165 64 234)",
@@ -366,7 +366,7 @@
     "--surface-foreground": "rgb(36 26 14)",
     "--popover": "rgb(255 234 215)",
     "--popover-foreground": "rgb(36 26 14)",
-    "--primary": "rgb(157 99 0)",
+    "--primary": "rgb(150 94 0)",
     "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(0 117 141)",
     "--secondary-foreground": "rgb(255 255 255)",
@@ -426,8 +426,8 @@
     "--surface-foreground": "rgb(244 223 203)",
     "--popover": "rgb(40 30 17)",
     "--popover-foreground": "rgb(244 223 203)",
-    "--primary": "rgb(245 158 11)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(163 103 0)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(0 213 255)",
     "--secondary-foreground": "rgb(0 0 0)",
     "--tertiary": "rgb(78 98 255)",
@@ -486,8 +486,8 @@
     "--surface-foreground": "rgb(33 27 13)",
     "--popover": "rgb(250 236 213)",
     "--popover-foreground": "rgb(33 27 13)",
-    "--primary": "rgb(255 195 0)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(135 102 0)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(0 114 158)",
     "--secondary-foreground": "rgb(255 255 255)",
     "--tertiary": "rgb(117 66 250)",
@@ -666,8 +666,8 @@
     "--surface-foreground": "rgb(249 220 217)",
     "--popover": "rgb(43 28 26)",
     "--popover-foreground": "rgb(249 220 217)",
-    "--primary": "rgb(250 76 75)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(218 52 55)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(0 126 166)",
     "--secondary-foreground": "rgb(255 255 255)",
     "--tertiary": "rgb(90 250 115)",
@@ -786,8 +786,8 @@
     "--surface-foreground": "rgb(231 224 238)",
     "--popover": "rgb(33 30 40)",
     "--popover-foreground": "rgb(231 224 238)",
-    "--primary": "rgb(155 113 255)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(132 85 239)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(254 199 0)",
     "--secondary-foreground": "rgb(0 0 0)",
     "--tertiary": "rgb(118 245 94)",
@@ -906,8 +906,8 @@
     "--surface-foreground": "rgb(245 220 227)",
     "--popover": "rgb(41 28 33)",
     "--popover-foreground": "rgb(245 220 227)",
-    "--primary": "rgb(240 75 156)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(210 50 132)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(0 237 255)",
     "--secondary-foreground": "rgb(0 0 0)",
     "--tertiary": "rgb(100 250 110)",
@@ -1026,8 +1026,8 @@
     "--surface-foreground": "rgb(219 227 237)",
     "--popover": "rgb(24 33 39)",
     "--popover-foreground": "rgb(219 227 237)",
-    "--primary": "rgb(14 165 233)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(0 124 177)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(213 61 30)",
     "--secondary-foreground": "rgb(255 255 255)",
     "--tertiary": "rgb(253 200 0)",
@@ -1146,8 +1146,8 @@
     "--surface-foreground": "rgb(248 221 209)",
     "--popover": "rgb(43 28 21)",
     "--popover-foreground": "rgb(248 221 209)",
-    "--primary": "rgb(249 115 22)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(192 84 0)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(0 255 254)",
     "--secondary-foreground": "rgb(0 0 0)",
     "--tertiary": "rgb(81 97 255)",
@@ -1266,8 +1266,8 @@
     "--surface-foreground": "rgb(215 230 225)",
     "--popover": "rgb(21 34 32)",
     "--popover-foreground": "rgb(215 230 225)",
-    "--primary": "rgb(20 184 166)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(0 131 118)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(212 63 10)",
     "--secondary-foreground": "rgb(255 255 255)",
     "--tertiary": "rgb(193 53 190)",
@@ -1386,8 +1386,8 @@
     "--surface-foreground": "rgb(237 222 235)",
     "--popover": "rgb(37 29 38)",
     "--popover-foreground": "rgb(237 222 235)",
-    "--primary": "rgb(196 110 222)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(165 81 191)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(0 253 200)",
     "--secondary-foreground": "rgb(0 0 0)",
     "--tertiary": "rgb(142 249 86)",
@@ -1446,8 +1446,8 @@
     "--surface-foreground": "rgb(24 29 18)",
     "--popover": "rgb(234 240 222)",
     "--popover-foreground": "rgb(24 29 18)",
-    "--primary": "rgb(139 255 0)",
-    "--primary-foreground": "rgb(0 0 0)",
+    "--primary": "rgb(63 120 0)",
+    "--primary-foreground": "rgb(255 255 255)",
     "--secondary": "rgb(79 79 255)",
     "--secondary-foreground": "rgb(255 255 255)",
     "--tertiary": "rgb(190 36 152)",