@oxyhq/bloom 0.6.21 → 0.6.23

package/src/scroll/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Native variant of the scroll-restoration primitive — a deliberate no-op.
+ *
+ * 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.
+ *
+ * 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 type {
+  ScrollRestorationProviderProps,
+  ScrollRestorationTarget,
+  UseScrollRestorationOptions,
+} from './types';
+
+export type {
+  ScrollableHandle,
+  ScrollRestorationProviderProps,
+  ScrollRestorationTarget,
+  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.
+ */
+export function useScrollRestoration(
+  _target: ScrollRestorationTarget,
+  _options?: UseScrollRestorationOptions,
+): void {
+  // Intentionally empty: native-stack already preserves scroll position.
+}

package/src/scroll/index.web.tsx

@@ -0,0 +1,253 @@
+/**
+ * Web variant of the scroll-restoration primitive.
+ *
+ * Mirrors the proven Bluesky pattern (`history.scrollRestoration = 'manual'`
+ * plus an in-memory `Map<routeKey, offset>`) with two deliberate differences
+ * forced by Oxy's layouts and the behaviour of React Navigation's web stack:
+ *
+ *  1. Bluesky restores the WINDOW scroller, whereas Oxy apps keep multi-column
+ *     layouts whose feed scrolls an INNER container. So we restore the offset
+ *     of a caller-registered scrollable (a ref to an element / RN scroll
+ *     component, or the `'window'` sentinel), keyed by the active route.
+ *
+ *  2. React Navigation's web stack HIDES the background screen on push. While
+ *     hidden, the previous screen's scroll container collapses
+ *     (`scrollHeight === clientHeight`) and the navigator forces its
+ *     `scrollTop` to 0. The screen is NOT unmounted, so a virtualized list
+ *     (e.g. FlashList) keeps its rows but re-lays them out over SEVERAL frames
+ *     once the screen is re-shown. Two problems follow, both handled here:
+ *
+ *       (a) A blur-time read of `scrollTop` returns the navigator's forced 0,
+ *           not the user's real offset — saving it would clobber the good
+ *           value. We therefore persist the last offset OBSERVED by the live
+ *           scroll listener, never a fresh read taken at blur time.
+ *
+ *       (b) A single-frame restore writes `scrollTop` while the list is still
+ *           collapsed; the write is clamped to 0 and never re-applied once the
+ *           content grows. We therefore re-apply the target offset across a
+ *           bounded run of animation frames, stopping as soon as the write
+ *           sticks (the content has grown tall enough) or a small frame cap is
+ *           reached.
+ *
+ * Native bundlers use `./index.ts` (a no-op); web bundlers select this file via
+ * the `"browser"` export condition in `package.json`.
+ */
+import { createContext, useCallback, useContext, useMemo, useRef } from 'react';
+import { useFocusEffect, useRoute } from '@react-navigation/native';
+
+import { createScroller } from './scrollable.web';
+import { ScrollOffsetStore, deriveScrollKey } from './store';
+import type {
+  ScrollRestorationProviderProps,
+  ScrollRestorationTarget,
+  UseScrollRestorationOptions,
+} from './types';
+
+export type {
+  ScrollableHandle,
+  ScrollRestorationProviderProps,
+  ScrollRestorationTarget,
+  UseScrollRestorationOptions,
+} from './types';
+
+const ScrollOffsetContext = createContext<ScrollOffsetStore | null>(null);
+ScrollOffsetContext.displayName = 'BloomScrollOffsetContext';
+
+/**
+ * Maximum number of animation frames the focus restore will re-apply the saved
+ * offset before giving up. A virtualized list re-lays out its rows over a
+ * handful of frames after its screen is re-shown; ~30 frames (≈0.5s at 60fps)
+ * is comfortably longer than any observed relayout while staying short enough
+ * that the loop never lingers as a perceptible cost. The loop normally exits
+ * far earlier — as soon as the write sticks.
+ */
+const RESTORE_FRAME_CAP = 30;
+
+/**
+ * Tolerance (in CSS pixels) for considering a restore "stuck". After writing
+ * `element.scrollTop = target`, the browser may clamp it to the current
+ * `scrollHeight - clientHeight`; if the resulting offset is within this many
+ * pixels of the target we treat the restore as complete. Sub-pixel rounding and
+ * fractional device-pixel ratios make an exact equality check unreliable.
+ */
+const RESTORE_STICK_TOLERANCE_PX = 2;
+
+/**
+ * Switch the browser to manual scroll restoration exactly once per document.
+ *
+ * The browser's default `'auto'` restoration fights our manual restore on
+ * Back/Forward navigations. Doing this at module scope (guarded for SSR) means
+ * it is set before any provider mounts, matching Bluesky's module-level call.
+ */
+if (typeof history !== 'undefined' && 'scrollRestoration' in history) {
+  history.scrollRestoration = 'manual';
+}
+
+/**
+ * Holds the per-route offset map for the subtree. One provider near the app
+ * root is enough; the store lives for the document's lifetime so offsets
+ * survive navigating away and back (including browser Back/Forward).
+ */
+export function ScrollRestorationProvider({
+  children,
+}: ScrollRestorationProviderProps) {
+  const store = useMemo(() => new ScrollOffsetStore(), []);
+  return (
+    <ScrollOffsetContext.Provider value={store}>
+      {children}
+    </ScrollOffsetContext.Provider>
+  );
+}
+
+function useScrollOffsetStore(): ScrollOffsetStore {
+  const store = useContext(ScrollOffsetContext);
+  if (store === null) {
+    throw new Error(
+      'useScrollRestoration must be used within a <ScrollRestorationProvider>.',
+    );
+  }
+  return store;
+}
+
+/**
+ * Preserve and restore the scroll offset of `target` across navigation, keyed
+ * by the active route (plus an optional `options.key` for routes that host
+ * multiple scrollables).
+ *
+ * Behaviour (web):
+ * - On every scroll while the screen is focused, the current offset is recorded
+ *   in memory and persisted. This live stream of saves is the source of truth.
+ * - On focus, the saved offset is re-applied across a bounded run of animation
+ *   frames, stopping as soon as the write sticks (the list has re-rendered its
+ *   rows and grown tall enough) or {@link RESTORE_FRAME_CAP} is reached. A
+ *   saved offset of 0 is a no-op (nothing to restore).
+ * - On blur, the LAST OBSERVED offset is persisted as a final safety net — not
+ *   a fresh `scrollTop` read, which the navigator may already have forced to 0
+ *   while collapsing the hidden screen.
+ */
+export function useScrollRestoration(
+  target: ScrollRestorationTarget,
+  options?: UseScrollRestorationOptions,
+): void {
+  const store = useScrollOffsetStore();
+  const route = useRoute();
+  const subKey = options?.key;
+  const enabled = options?.enabled ?? true;
+
+  const scrollKey = deriveScrollKey(route.key, subKey);
+
+  // Keep the latest target/enabled/key in refs so the focus effect can read
+  // them without being re-subscribed on every render.
+  const targetRef = useRef(target);
+  targetRef.current = target;
+  const enabledRef = useRef(enabled);
+  enabledRef.current = enabled;
+  const scrollKeyRef = useRef(scrollKey);
+  scrollKeyRef.current = scrollKey;
+
+  useFocusEffect(
+    // The effect identity is intentionally stable across renders: it reads all
+    // varying inputs from refs. React Navigation re-runs it on each focus.
+    useCallback(
+      () => {
+        const key = scrollKeyRef.current;
+        if (!enabledRef.current || key === null) return undefined;
+
+        const scroller = createScroller(targetRef.current);
+        const element =
+          targetRef.current === 'window'
+            ? (typeof window !== 'undefined' ? window : null)
+            : resolveScrollEventTarget(targetRef.current);
+
+        // The last offset the live scroll listener observed for this focus
+        // session. This — not a blur-time `getOffset()` — is what we persist on
+        // blur, because by blur time the navigator may have collapsed the
+        // hidden screen and forced its `scrollTop` to 0 (bug A). `null` means
+        // the user never scrolled this session, so there is nothing newer to
+        // persist than what the scroll listener already saved live.
+        let lastObservedOffset: number | null = null;
+
+        const save = () => {
+          const currentKey = scrollKeyRef.current;
+          if (!enabledRef.current || currentKey === null) return;
+          const offset = scroller.getOffset();
+          // Ignore a spurious 0 produced by the navigator collapsing a hidden
+          // background screen: while collapsed the container cannot scroll, so
+          // its `scrollTop` is forced to 0. Persisting it would clobber the
+          // good offset recorded by earlier live saves (bug A). A genuine
+          // scroll-to-top keeps the container scrollable and is saved normally.
+          if (offset === 0 && !scroller.canScroll()) return;
+          lastObservedOffset = offset;
+          store.save(currentKey, offset);
+        };
+
+        // Restore across a bounded run of frames. A freshly re-shown
+        // virtualized list re-lays out its rows over several frames, so a
+        // single write while it is still collapsed would be clamped to 0 and
+        // never re-applied (bug B). We re-apply each frame until the write
+        // sticks or the frame cap is hit.
+        const targetOffset = store.read(key);
+        let rafId: number | null = null;
+
+        if (targetOffset > 0 && typeof requestAnimationFrame !== 'undefined') {
+          let framesLeft = RESTORE_FRAME_CAP;
+          const applyOffset = () => {
+            rafId = null;
+            scroller.setOffset(targetOffset);
+            framesLeft -= 1;
+            // Stop once the write took effect (content grew tall enough) or we
+            // exhaust the frame budget. `getOffset` re-reads the clamped value.
+            const reached =
+              Math.abs(scroller.getOffset() - targetOffset) <=
+              RESTORE_STICK_TOLERANCE_PX;
+            if (!reached && framesLeft > 0) {
+              rafId = requestAnimationFrame(applyOffset);
+            }
+          };
+          rafId = requestAnimationFrame(applyOffset);
+        }
+
+        element?.addEventListener('scroll', save, { passive: true });
+
+        return () => {
+          if (rafId !== null) cancelAnimationFrame(rafId);
+          element?.removeEventListener('scroll', save);
+          // Final capture on blur: persist the last offset the scroll listener
+          // OBSERVED, never a fresh read (which the navigator may have forced
+          // to 0 while collapsing the hidden screen). When the user never
+          // scrolled this session there is nothing newer to persist than the
+          // live saves already recorded.
+          if (lastObservedOffset !== null) {
+            const currentKey = scrollKeyRef.current;
+            if (enabledRef.current && currentKey !== null) {
+              store.save(currentKey, lastObservedOffset);
+            }
+          }
+        };
+      },
+      [store],
+    ),
+  );
+}
+
+/**
+ * Resolve the EventTarget to listen for `scroll` on. RNW scroll components
+ * expose `getScrollableNode()`; raw refs may hold the DOM node directly.
+ */
+function resolveScrollEventTarget(
+  target: Exclude<ScrollRestorationTarget, 'window'>,
+): EventTarget | null {
+  const current = (target as { current: unknown }).current;
+  if (current == null) return null;
+  if (typeof EventTarget !== 'undefined' && current instanceof EventTarget) {
+    return current;
+  }
+  const handle = current as { getScrollableNode?: () => unknown };
+  if (typeof handle.getScrollableNode === 'function') {
+    const node = handle.getScrollableNode();
+    if (typeof EventTarget !== 'undefined' && node instanceof EventTarget) {
+      return node;
+    }
+  }
+  return null;
+}

package/src/scroll/scrollable.web.ts

@@ -0,0 +1,92 @@
+import type { ScrollableHandle, ScrollRestorationTarget } from './types';
+
+/**
+ * A normalized read/write interface over whatever the caller registered, so
+ * the hook does not branch on target shape. All methods are safe no-ops when
+ * the underlying element is not yet (or no longer) attached.
+ */
+export interface ResolvedScroller {
+  getOffset: () => number;
+  setOffset: (offset: number) => void;
+  /**
+   * Whether the scroll container can currently hold a non-zero offset, i.e.
+   * its content is taller than its viewport (`scrollHeight > clientHeight`).
+   *
+   * React Navigation's web stack collapses a hidden background screen so its
+   * content height drops to the viewport height; while collapsed the container
+   * cannot be scrolled and its `scrollTop` is forced to 0. The hook uses this
+   * to ignore a spurious 0 read coming from a collapsed container rather than
+   * persisting it over a previously-saved good offset. The `'window'` scroller
+   * is never collapsed by the navigator, so it always reports `true`.
+   */
+  canScroll: () => boolean;
+}
+
+function isElement(value: unknown): value is HTMLElement {
+  return typeof HTMLElement !== 'undefined' && value instanceof HTMLElement;
+}
+
+function hasGetScrollableNode(
+  value: unknown,
+): value is Required<Pick<ScrollableHandle, 'getScrollableNode'>> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as ScrollableHandle).getScrollableNode === 'function'
+  );
+}
+
+/**
+ * Resolve the live DOM element a target currently points at, or `null`.
+ *
+ * RNW scroll components expose `getScrollableNode()`; plain refs may hold the
+ * DOM node directly. We never cache the node because RNW can swap it across
+ * renders — we re-resolve on every read/write.
+ */
+function resolveElement(target: ScrollRestorationTarget): HTMLElement | null {
+  if (target === 'window') return null;
+
+  const current = (target as { current: unknown }).current;
+  if (current == null) return null;
+
+  if (isElement(current)) return current;
+
+  if (hasGetScrollableNode(current)) {
+    const node = current.getScrollableNode();
+    if (isElement(node)) return node;
+  }
+
+  return null;
+}
+
+/**
+ * Build a {@link ResolvedScroller} for a target. The window sentinel reads and
+ * writes the document scroller; everything else operates on the resolved
+ * element's `scrollTop`.
+ */
+export function createScroller(target: ScrollRestorationTarget): ResolvedScroller {
+  if (target === 'window') {
+    return {
+      getOffset: () => (typeof window === 'undefined' ? 0 : window.scrollY),
+      setOffset: (offset) => {
+        if (typeof window !== 'undefined') window.scrollTo(0, offset);
+      },
+      canScroll: () => true,
+    };
+  }
+
+  return {
+    getOffset: () => {
+      const element = resolveElement(target);
+      return element ? element.scrollTop : 0;
+    },
+    setOffset: (offset) => {
+      const element = resolveElement(target);
+      if (element) element.scrollTop = offset;
+    },
+    canScroll: () => {
+      const element = resolveElement(target);
+      return element ? element.scrollHeight > element.clientHeight : false;
+    },
+  };
+}

package/src/scroll/store.ts

@@ -0,0 +1,84 @@
+/**
+ * Pure, platform-agnostic core of the scroll-restoration primitive.
+ *
+ * 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).
+ */
+
+/**
+ * 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.
+ *
+ * `\0` (NUL) can never appear in a React Navigation route key 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.
+ */
+const COMPOSITE_KEY_SEPARATOR = '\0';
+
+/**
+ * Derive the storage key for a scrollable from its owning route key and an
+ * optional caller sub-key.
+ *
+ * - `routeKey` is React Navigation's stable per-route `route.key`.
+ * - `subKey` distinguishes multiple scrollables that share a single route.
+ *
+ * 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".
+ */
+export function deriveScrollKey(
+  routeKey: string | undefined,
+  subKey?: string,
+): string | null {
+  if (!routeKey) return null;
+  if (subKey === undefined || subKey === '') return routeKey;
+  return `${routeKey}${COMPOSITE_KEY_SEPARATOR}${subKey}`;
+}
+
+/**
+ * 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.
+ */
+export class ScrollOffsetStore {
+  private readonly offsets = new Map<string, number>();
+
+  /** Persist the offset for a key. A negative offset is clamped to 0. */
+  save(key: string, offset: number): void {
+    this.offsets.set(key, offset > 0 ? offset : 0);
+  }
+
+  /**
+   * 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(key: string): number {
+    return this.offsets.get(key) ?? 0;
+  }
+
+  /** Whether an offset was ever saved for this key. */
+  has(key: string): boolean {
+    return this.offsets.has(key);
+  }
+
+  /** Drop a saved offset (e.g. when a route is permanently removed). */
+  forget(key: string): void {
+    this.offsets.delete(key);
+  }
+
+  /** Clear every saved offset. Primarily for tests and full resets. */
+  clear(): void {
+    this.offsets.clear();
+  }
+
+  /** Number of distinct keys currently tracked. */
+  get size(): number {
+    return this.offsets.size;
+  }
+}

package/src/scroll/types.ts

@@ -0,0 +1,48 @@
+import type { ReactNode, RefObject } from 'react';
+
+/**
+ * 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 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).
+ *
+ * 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.
+ */
+export interface ScrollableHandle {
+  /** Imperative scroll API exposed by RN scrollables. */
+  scrollTo?: (options: { x?: number; y?: number; animated?: boolean }) => void;
+  /** Web/RNW path: returns the underlying DOM node. */
+  getScrollableNode?: () => unknown;
+}
+
+/**
+ * The accepted ref shapes. `'window'` is a sentinel for the document scroller.
+ */
+export type ScrollRestorationTarget =
+  | RefObject<ScrollableHandle | null>
+  | RefObject<unknown>
+  | 'window';
+
+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.
+   */
+  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.
+   * Defaults to `true`.
+   */
+  enabled?: boolean;
+}
+
+export interface ScrollRestorationProviderProps {
+  children: ReactNode;
+}