@oxyhq/bloom 0.78.0 → 0.79.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/README.md +3 -3
  2. package/lib/commonjs/provider/index.js +11 -7
  3. package/lib/commonjs/provider/index.js.map +1 -1
  4. package/lib/commonjs/scroll/context.js +96 -0
  5. package/lib/commonjs/scroll/context.js.map +1 -0
  6. package/lib/commonjs/scroll/expo-router/index.js +133 -0
  7. package/lib/commonjs/scroll/expo-router/index.js.map +1 -0
  8. package/lib/commonjs/scroll/index.js +85 -21
  9. package/lib/commonjs/scroll/index.js.map +1 -1
  10. package/lib/commonjs/scroll/index.web.js +184 -118
  11. package/lib/commonjs/scroll/index.web.js.map +1 -1
  12. package/lib/commonjs/scroll/scrollable.native.js +58 -0
  13. package/lib/commonjs/scroll/scrollable.native.js.map +1 -0
  14. package/lib/commonjs/scroll/store.js +47 -25
  15. package/lib/commonjs/scroll/store.js.map +1 -1
  16. package/lib/commonjs/theme/color-policy.js +11 -9
  17. package/lib/commonjs/theme/color-policy.js.map +1 -1
  18. package/lib/module/provider/index.js +10 -6
  19. package/lib/module/provider/index.js.map +1 -1
  20. package/lib/module/scroll/context.js +90 -0
  21. package/lib/module/scroll/context.js.map +1 -0
  22. package/lib/module/scroll/expo-router/index.js +128 -0
  23. package/lib/module/scroll/expo-router/index.js.map +1 -0
  24. package/lib/module/scroll/index.js +80 -21
  25. package/lib/module/scroll/index.js.map +1 -1
  26. package/lib/module/scroll/index.web.js +181 -119
  27. package/lib/module/scroll/index.web.js.map +1 -1
  28. package/lib/module/scroll/scrollable.native.js +54 -0
  29. package/lib/module/scroll/scrollable.native.js.map +1 -0
  30. package/lib/module/scroll/store.js +47 -25
  31. package/lib/module/scroll/store.js.map +1 -1
  32. package/lib/module/theme/color-policy.js +11 -9
  33. package/lib/module/theme/color-policy.js.map +1 -1
  34. package/lib/typescript/commonjs/provider/index.d.ts +7 -5
  35. package/lib/typescript/commonjs/provider/index.d.ts.map +1 -1
  36. package/lib/typescript/commonjs/scroll/context.d.ts +14 -0
  37. package/lib/typescript/commonjs/scroll/context.d.ts.map +1 -0
  38. package/lib/typescript/commonjs/scroll/expo-router/index.d.ts +7 -0
  39. package/lib/typescript/commonjs/scroll/expo-router/index.d.ts.map +1 -0
  40. package/lib/typescript/commonjs/scroll/index.d.ts +14 -23
  41. package/lib/typescript/commonjs/scroll/index.d.ts.map +1 -1
  42. package/lib/typescript/commonjs/scroll/index.web.d.ts +17 -19
  43. package/lib/typescript/commonjs/scroll/index.web.d.ts.map +1 -1
  44. package/lib/typescript/commonjs/scroll/scrollable.native.d.ts +23 -0
  45. package/lib/typescript/commonjs/scroll/scrollable.native.d.ts.map +1 -0
  46. package/lib/typescript/commonjs/scroll/store.d.ts +41 -22
  47. package/lib/typescript/commonjs/scroll/store.d.ts.map +1 -1
  48. package/lib/typescript/commonjs/scroll/types.d.ts +82 -12
  49. package/lib/typescript/commonjs/scroll/types.d.ts.map +1 -1
  50. package/lib/typescript/commonjs/theme/color-policy.d.ts.map +1 -1
  51. package/lib/typescript/module/provider/index.d.ts +7 -5
  52. package/lib/typescript/module/provider/index.d.ts.map +1 -1
  53. package/lib/typescript/module/scroll/context.d.ts +14 -0
  54. package/lib/typescript/module/scroll/context.d.ts.map +1 -0
  55. package/lib/typescript/module/scroll/expo-router/index.d.ts +7 -0
  56. package/lib/typescript/module/scroll/expo-router/index.d.ts.map +1 -0
  57. package/lib/typescript/module/scroll/index.d.ts +14 -23
  58. package/lib/typescript/module/scroll/index.d.ts.map +1 -1
  59. package/lib/typescript/module/scroll/index.web.d.ts +17 -19
  60. package/lib/typescript/module/scroll/index.web.d.ts.map +1 -1
  61. package/lib/typescript/module/scroll/scrollable.native.d.ts +23 -0
  62. package/lib/typescript/module/scroll/scrollable.native.d.ts.map +1 -0
  63. package/lib/typescript/module/scroll/store.d.ts +41 -22
  64. package/lib/typescript/module/scroll/store.d.ts.map +1 -1
  65. package/lib/typescript/module/scroll/types.d.ts +82 -12
  66. package/lib/typescript/module/scroll/types.d.ts.map +1 -1
  67. package/lib/typescript/module/theme/color-policy.d.ts.map +1 -1
  68. package/package.json +15 -1
  69. package/src/__tests__/BloomProvider.web.test.tsx +8 -15
  70. package/src/__tests__/optional-peer-imports.test.ts +2 -2
  71. package/src/__tests__/scroll-expo-router-adapter.test.tsx +164 -0
  72. package/src/__tests__/scroll-native.test.tsx +465 -0
  73. package/src/__tests__/scroll-store.test.ts +41 -17
  74. package/src/__tests__/scroll-web.test.tsx +547 -111
  75. package/src/provider/index.tsx +10 -7
  76. package/src/scroll/context.tsx +107 -0
  77. package/src/scroll/expo-router/index.ts +140 -0
  78. package/src/scroll/index.ts +92 -25
  79. package/src/scroll/index.web.tsx +219 -162
  80. package/src/scroll/scrollable.native.ts +64 -0
  81. package/src/scroll/store.ts +47 -25
  82. package/src/scroll/types.ts +82 -12
  83. package/src/theme/__tests__/__fixtures__/golden-resolved-tokens.json +27 -27
  84. package/src/theme/__tests__/__snapshots__/visual-gallery.test.tsx.snap +55 -55
  85. package/src/theme/__tests__/policy-legibility.test.ts +21 -1
  86. package/src/theme/color-policy.ts +13 -9
  87. package/lib/commonjs/provider/scroll-provider.js +0 -13
  88. package/lib/commonjs/provider/scroll-provider.js.map +0 -1
  89. package/lib/commonjs/provider/scroll-provider.web.js +0 -13
  90. package/lib/commonjs/provider/scroll-provider.web.js.map +0 -1
  91. package/lib/module/provider/scroll-provider.js +0 -16
  92. package/lib/module/provider/scroll-provider.js.map +0 -1
  93. package/lib/module/provider/scroll-provider.web.js +0 -5
  94. package/lib/module/provider/scroll-provider.web.js.map +0 -1
  95. package/lib/typescript/commonjs/provider/scroll-provider.d.ts +0 -14
  96. package/lib/typescript/commonjs/provider/scroll-provider.d.ts.map +0 -1
  97. package/lib/typescript/commonjs/provider/scroll-provider.web.d.ts +0 -3
  98. package/lib/typescript/commonjs/provider/scroll-provider.web.d.ts.map +0 -1
  99. package/lib/typescript/module/provider/scroll-provider.d.ts +0 -14
  100. package/lib/typescript/module/provider/scroll-provider.d.ts.map +0 -1
  101. package/lib/typescript/module/provider/scroll-provider.web.d.ts +0 -3
  102. package/lib/typescript/module/provider/scroll-provider.web.d.ts.map +0 -1
  103. package/src/__tests__/scroll-native.test.ts +0 -25
  104. package/src/provider/scroll-provider.ts +0 -13
  105. package/src/provider/scroll-provider.web.ts +0 -2
@@ -3,22 +3,22 @@
3
3
  /**
4
4
  * Web variant of the scroll-restoration primitive.
5
5
  *
6
- * Mirrors the proven Bluesky pattern (`history.scrollRestoration = 'manual'`
7
- * plus an in-memory `Map<routeKey, offset>`) with two deliberate differences
8
- * forced by Oxy's layouts and the behaviour of the (expo-router-wrapped)
9
- * React Navigation web stack:
6
+ * Mirrors the proven Bluesky pattern (manual `history.scrollRestoration` plus
7
+ * an in-memory `Map<key, offset>`) with three deliberate differences forced by
8
+ * Oxy's layouts and by the behaviour of the (expo-router-wrapped) React
9
+ * Navigation web stack:
10
10
  *
11
11
  * 1. Bluesky restores the WINDOW scroller, whereas Oxy apps keep multi-column
12
12
  * layouts whose feed scrolls an INNER container. So we restore the offset
13
13
  * of a caller-registered scrollable (a ref to an element / RN scroll
14
- * component, or the `'window'` sentinel), keyed by the active route.
14
+ * component, or the `'window'` sentinel).
15
15
  *
16
- * 2. The web stack HIDES the background screen on push. While
17
- * hidden, the previous screen's scroll container collapses
18
- * (`scrollHeight === clientHeight`) and the navigator forces its
19
- * `scrollTop` to 0. The screen is NOT unmounted, so a virtualized list
20
- * (e.g. FlashList) keeps its rows but re-lays them out over SEVERAL frames
21
- * once the screen is re-shown. Two problems follow, both handled here:
16
+ * 2. The web stack HIDES the background screen on push. While hidden, the
17
+ * previous screen's scroll container collapses (`scrollHeight ===
18
+ * clientHeight`) and the navigator forces its `scrollTop` to 0. The screen
19
+ * is NOT unmounted, so a virtualized list (e.g. FlashList) keeps its rows
20
+ * but re-lays them out over SEVERAL frames once the screen is re-shown. Two
21
+ * problems follow, both handled here:
22
22
  *
23
23
  * (a) A blur-time read of `scrollTop` returns the navigator's forced 0,
24
24
  * not the user's real offset — saving it would clobber the good
@@ -32,32 +32,26 @@
32
32
  * sticks (the content has grown tall enough) or a small frame cap is
33
33
  * reached.
34
34
  *
35
- * Native bundlers use `./index.ts` (a no-op); web bundlers select this file via
36
- * the `"browser"` export condition in `package.json`.
35
+ * 3. A document-scrolled app (one window scroller shared by every route) has
36
+ * no per-screen container to reset, so an unrecognised key MUST be written
37
+ * to 0 explicitly. Doing nothing leaves the previous screen's offset in
38
+ * place and the new screen opens mid-page.
37
39
  *
38
- * The navigation hooks are imported from `expo-router` (which re-exports
39
- * `useFocusEffect` and `useRoute` from its bundled React Navigation core) rather
40
- * than from `@react-navigation/native` directly. Every Oxy app uses expo-router
41
- * as its router, so it is always a DIRECT, top-level dependency that resolves
42
- * cleanly under Bun's isolated linker — whereas `@react-navigation/native` is
43
- * only a nested/transitive dependency of expo-router and would fail to resolve
44
- * when bundling those apps.
40
+ * Native bundlers use `./index.ts`; web bundlers select this file via the
41
+ * `"browser"` export condition in `package.json`.
45
42
  */
46
- import { createContext, useCallback, useContext, useMemo, useRef } from 'react';
47
- import { useFocusEffect, useRoute } from 'expo-router';
43
+ import { useCallback, useRef } from 'react';
44
+ import { useScrollRestorationContext } from "./context.js";
48
45
  import { createScroller } from "./scrollable.web.js";
49
- import { ScrollOffsetStore, deriveScrollKey } from "./store.js";
50
- import { jsx as _jsx } from "react/jsx-runtime";
51
- const ScrollOffsetContext = /*#__PURE__*/createContext(null);
52
- ScrollOffsetContext.displayName = 'BloomScrollOffsetContext';
53
-
46
+ import { deriveScrollKey } from "./store.js";
47
+ export { ScrollRestorationProvider } from "./context.js";
54
48
  /**
55
- * Maximum number of animation frames the focus restore will re-apply the saved
56
- * offset before giving up. A virtualized list re-lays out its rows over a
57
- * handful of frames after its screen is re-shown; ~30 frames (≈0.5s at 60fps)
58
- * is comfortably longer than any observed relayout while staying short enough
59
- * that the loop never lingers as a perceptible cost. The loop normally exits
60
- * far earlier — as soon as the write sticks.
49
+ * Maximum number of animation frames the restore will re-apply the saved offset
50
+ * before giving up. A virtualized list re-lays out its rows over a handful of
51
+ * frames after its screen is re-shown; ~30 frames (≈0.5s at 60fps) is
52
+ * comfortably longer than any observed relayout while staying short enough that
53
+ * the loop never lingers as a perceptible cost. The loop normally exits far
54
+ * earlier — as soon as the write sticks.
61
55
  */
62
56
  const RESTORE_FRAME_CAP = 30;
63
57
 
@@ -71,108 +65,167 @@ const RESTORE_FRAME_CAP = 30;
71
65
  const RESTORE_STICK_TOLERANCE_PX = 2;
72
66
 
73
67
  /**
74
- * Switch the browser to manual scroll restoration exactly once per document.
75
- *
76
- * The browser's default `'auto'` restoration fights our manual restore on
77
- * Back/Forward navigations. Doing this at module scope (guarded for SSR) means
78
- * it is set before any provider mounts, matching Bluesky's module-level call.
68
+ * The web binding is a constant: this platform observes offsets by subscribing
69
+ * to the resolved DOM node's own `scroll` event, so it needs nothing from the
70
+ * caller. It is still returned and still safe to spread onto a list — so a
71
+ * call site is written once and runs on both platforms.
79
72
  */
80
- if (typeof history !== 'undefined' && 'scrollRestoration' in history) {
81
- history.scrollRestoration = 'manual';
82
- }
73
+ const WEB_BINDING = {
74
+ onScroll: () => undefined
75
+ };
83
76
 
84
77
  /**
85
- * Holds the per-route offset map for the subtree. One provider near the app
86
- * root is enough; the store lives for the document's lifetime so offsets
87
- * survive navigating away and back (including browser Back/Forward).
78
+ * Events that mean the USER has taken over the scroller, and the restore must
79
+ * stop trying to put them back.
80
+ *
81
+ * The browser's own restoration is specified the same way: HTML §7.4.6.5 has
82
+ * the UA re-attempt the saved position and "may continue to attempt to do so
83
+ * periodically, until document's has been scrolled by the user becomes true".
84
+ * Without this the loop fights anyone who starts scrolling inside the frame
85
+ * budget, yanking them back once per frame for up to {@link RESTORE_FRAME_CAP}
86
+ * frames.
87
+ *
88
+ * Two designs were rejected, and the reasons are the point:
89
+ *
90
+ * - **"Any `scroll` event aborts"** — the obvious version, and it aborts on the
91
+ * FIRST frame every time: `setOffset` is itself a scroll, so the loop would
92
+ * cancel on the event its own write produced and no restore would ever
93
+ * complete.
94
+ * - **"Abort on an offset we did not write"** — tempting because it needs no
95
+ * listeners, but a virtualized list inserting rows ABOVE the viewport makes
96
+ * the browser's scroll anchoring move `scrollTop` on its own. That is
97
+ * precisely the situation the loop exists for, so the unexplained-delta test
98
+ * would abort exactly when it must not.
99
+ *
100
+ * What is being detected is user INPUT, so this detects user input. `pointerdown`
101
+ * covers a scrollbar drag and a touch-less press; `keydown` covers arrow/page
102
+ * keys, and reaches us whenever focus is inside the scroller it would scroll.
88
103
  */
89
- export function ScrollRestorationProvider({
90
- children
91
- }) {
92
- const store = useMemo(() => new ScrollOffsetStore(), []);
93
- return /*#__PURE__*/_jsx(ScrollOffsetContext.Provider, {
94
- value: store,
95
- children: children
96
- });
97
- }
98
- function useScrollOffsetStore() {
99
- const store = useContext(ScrollOffsetContext);
100
- if (store === null) {
101
- throw new Error('useScrollRestoration must be used within a <ScrollRestorationProvider>.');
102
- }
103
- return store;
104
- }
104
+ const USER_TAKEOVER_EVENTS = ['wheel', 'touchstart', 'pointerdown', 'keydown'];
105
105
 
106
106
  /**
107
107
  * Preserve and restore the scroll offset of `target` across navigation, keyed
108
- * by the active route (plus an optional `options.key` for routes that host
109
- * multiple scrollables).
108
+ * by the content its screen is showing plus an optional `options.key`.
110
109
  *
111
110
  * Behaviour (web):
112
111
  * - On every scroll while the screen is focused, the current offset is recorded
113
- * in memory and persisted. This live stream of saves is the source of truth.
114
- * - On focus, the saved offset is re-applied across a bounded run of animation
115
- * frames, stopping as soon as the write sticks (the list has re-rendered its
116
- * rows and grown tall enough) or {@link RESTORE_FRAME_CAP} is reached. A
117
- * saved offset of 0 is a no-op (nothing to restore).
118
- * - On blur, the LAST OBSERVED offset is persisted as a final safety net — not
119
- * a fresh `scrollTop` read, which the navigator may already have forced to 0
120
- * while collapsing the hidden screen.
112
+ * under the key that was live when the listener was attached. This stream of
113
+ * saves is the source of truth.
114
+ * - On focus and again whenever the key changes while the screen STAYS
115
+ * focused, which is how an in-screen tab or folder swap is seen at all — the
116
+ * offset saved for the new key is re-applied across a bounded run of
117
+ * animation frames, stopping as soon as the write sticks or
118
+ * {@link RESTORE_FRAME_CAP} is reached. Content never seen this session is
119
+ * written to 0 once instead; a write to 0 always sticks, so it needs no loop.
120
+ * - On blur (and on a key change), the LAST OBSERVED offset is persisted under
121
+ * the OUTGOING key as a final safety net — not a fresh `scrollTop` read,
122
+ * which the navigator may already have forced to 0 while collapsing the
123
+ * hidden screen.
121
124
  */
122
125
  export function useScrollRestoration(target, options) {
123
- const store = useScrollOffsetStore();
124
- const route = useRoute();
125
- const subKey = options?.key;
126
+ const {
127
+ store,
128
+ adapter
129
+ } = useScrollRestorationContext();
130
+ const contentId = adapter.useScreenContentId();
126
131
  const enabled = options?.enabled ?? true;
127
- const scrollKey = deriveScrollKey(route.key, subKey);
132
+ const scrollKey = deriveScrollKey(contentId, options?.key);
128
133
 
129
- // Keep the latest target/enabled/key in refs so the focus effect can read
130
- // them without being re-subscribed on every render.
131
- const targetRef = useRef(target);
132
- targetRef.current = target;
133
- const enabledRef = useRef(enabled);
134
- enabledRef.current = enabled;
135
- const scrollKeyRef = useRef(scrollKey);
136
- scrollKeyRef.current = scrollKey;
137
- useFocusEffect(
138
- // The effect identity is intentionally stable across renders: it reads all
139
- // varying inputs from refs. expo-router's `useFocusEffect` re-runs it on
140
- // each focus.
134
+ // The key this hook instance has already sent to the top. Writing 0 is a
135
+ // one-time ARRIVAL action: a later re-run for the SAME key (`enabled` turning
136
+ // on once the rows exist, a screen regaining focus) must not repeat it,
137
+ // because by then the user may have scrolled somewhere the hook never got to
138
+ // record. Restoring twice is harmless; resetting twice is data loss.
139
+ const resetKeyRef = useRef(null);
140
+ adapter.useScreenFocusEffect(
141
+ // Every varying input is a dependency rather than a ref read, so the
142
+ // session below CLOSES OVER the key it belongs to. That is what makes a
143
+ // key change mid-focus correct in both directions: the outgoing session's
144
+ // cleanup persists to the old key, and the incoming one restores the new.
141
145
  useCallback(() => {
142
- const key = scrollKeyRef.current;
143
- if (!enabledRef.current || key === null) return undefined;
144
- const scroller = createScroller(targetRef.current);
145
- const element = targetRef.current === 'window' ? typeof window !== 'undefined' ? window : null : resolveScrollEventTarget(targetRef.current);
146
+ if (!enabled || scrollKey === null) return undefined;
147
+ const scroller = createScroller(target);
148
+ const element = target === 'window' ? typeof window === 'undefined' ? null : window : resolveScrollEventTarget(target);
146
149
 
147
- // The last offset the live scroll listener observed for this focus
148
- // session. This — not a blur-time `getOffset()` — is what we persist on
149
- // blur, because by blur time the navigator may have collapsed the
150
- // hidden screen and forced its `scrollTop` to 0 (bug A). `null` means
151
- // the user never scrolled this session, so there is nothing newer to
152
- // persist than what the scroll listener already saved live.
150
+ // The last offset the live scroll listener observed for this session.
151
+ // This — not a cleanup-time `getOffset()` — is what we persist at the
152
+ // end, because by then the navigator may have collapsed the hidden
153
+ // screen and forced its `scrollTop` to 0 (problem A). `null` means the
154
+ // user never scrolled this session, so there is nothing newer to persist
155
+ // than what the scroll listener already saved live.
153
156
  let lastObservedOffset = null;
157
+
158
+ // The 0 WE wrote, which a real browser dispatches back as a `scroll`
159
+ // event (jsdom does not, so the test for this emits it explicitly).
160
+ // Persisting it would record an offset the user never chose, under a key
161
+ // another LIVE screen may share — the two-live-entries trade content
162
+ // keying makes (see `deriveScrollKey`) means a sibling showing the same
163
+ // content can save a real offset between our write and its echo, and the
164
+ // echo would clobber it.
165
+ let echoOffset = null;
154
166
  const save = () => {
155
- const currentKey = scrollKeyRef.current;
156
- if (!enabledRef.current || currentKey === null) return;
157
167
  const offset = scroller.getOffset();
158
168
  // Ignore a spurious 0 produced by the navigator collapsing a hidden
159
169
  // background screen: while collapsed the container cannot scroll, so
160
- // its `scrollTop` is forced to 0. Persisting it would clobber the
161
- // good offset recorded by earlier live saves (bug A). A genuine
170
+ // its `scrollTop` is forced to 0. Persisting it would clobber the good
171
+ // offset recorded by earlier live saves (problem A). A genuine
162
172
  // scroll-to-top keeps the container scrollable and is saved normally.
163
173
  if (offset === 0 && !scroller.canScroll()) return;
174
+ if (offset === echoOffset) {
175
+ // Our own write coming back. Consume the arming so a real scroll to
176
+ // the same offset later is saved normally.
177
+ echoOffset = null;
178
+ return;
179
+ }
180
+ echoOffset = null;
164
181
  lastObservedOffset = offset;
165
- store.save(currentKey, offset);
182
+ store.save(scrollKey, offset);
166
183
  };
167
184
 
168
- // Restore across a bounded run of frames. A freshly re-shown
169
- // virtualized list re-lays out its rows over several frames, so a
170
- // single write while it is still collapsed would be clamped to 0 and
171
- // never re-applied (bug B). We re-apply each frame until the write
172
- // sticks or the frame cap is hit.
173
- const targetOffset = store.read(key);
185
+ // Restore and reset are ONE write. A miss reads 0, and 0 is exactly what
186
+ // an unseen screen must be written to left alone it would show the
187
+ // previous screen's offset, since a document-scrolled app shares one
188
+ // scroller across every route.
189
+ const targetOffset = store.read(scrollKey);
190
+
191
+ // They remain two DECISIONS, though, and `read` cannot tell them apart:
192
+ // a key never seen and a key deliberately saved at the top both read 0.
193
+ // Only the first is a RESET, and a reset is a one-time ARRIVAL action
194
+ // gated on `resetKeyRef` — repeating it on a later re-run for the same
195
+ // key would send a user who has since scrolled back to the top, and the
196
+ // hook was inert while they did it so there is nothing to restore them
197
+ // to afterwards. A 0 the user deliberately saved is theirs, and always
198
+ // re-applies. `has` is the only thing that answers this.
199
+ const isReset = !store.has(scrollKey);
200
+ const alreadyReset = isReset && resetKeyRef.current === scrollKey;
201
+ if (isReset) resetKeyRef.current = scrollKey;
174
202
  let rafId = null;
175
- if (targetOffset > 0 && typeof requestAnimationFrame !== 'undefined') {
203
+ const stopRestore = () => {
204
+ if (rafId === null) return;
205
+ cancelAnimationFrame(rafId);
206
+ rafId = null;
207
+ };
208
+ if (alreadyReset) {
209
+ // Nothing to write: this content has already been sent to the top once
210
+ // and the user is wherever they have moved to since.
211
+ } else if (targetOffset === 0) {
212
+ // A write to 0 is never clamped away, so it needs no re-apply loop.
213
+ echoOffset = 0;
214
+ scroller.setOffset(0);
215
+ } else if (typeof requestAnimationFrame !== 'undefined') {
216
+ // Re-apply across a bounded run of frames. A freshly re-shown
217
+ // virtualized list re-lays out its rows over several frames, so a
218
+ // single write while it is still collapsed would be clamped to 0 and
219
+ // never re-applied (problem B).
220
+ //
221
+ // KNOWN PROPERTY, not a bug: each of these writes echoes back as a
222
+ // `scroll` event and IS persisted (only the reset arms `echoOffset`,
223
+ // and `canScroll()` is always true for the `'window'` sentinel so the
224
+ // collapsed-container guard never fires there). A loop that reaches
225
+ // the target self-heals on its last echo. A loop that exhausts the cap
226
+ // leaves the CLAMPED offset stored — which is the right thing to
227
+ // remember when the content genuinely shrank, since that is as far as
228
+ // the user can now scroll.
176
229
  let framesLeft = RESTORE_FRAME_CAP;
177
230
  const applyOffset = () => {
178
231
  rafId = null;
@@ -186,26 +239,35 @@ export function useScrollRestoration(target, options) {
186
239
  }
187
240
  };
188
241
  rafId = requestAnimationFrame(applyOffset);
242
+ // Only while a loop is actually in flight — the reset path has nothing
243
+ // to abort, and the listeners would be idle on every screen.
244
+ for (const type of USER_TAKEOVER_EVENTS) {
245
+ element?.addEventListener(type, stopRestore, {
246
+ passive: true
247
+ });
248
+ }
189
249
  }
190
250
  element?.addEventListener('scroll', save, {
191
251
  passive: true
192
252
  });
193
253
  return () => {
194
- if (rafId !== null) cancelAnimationFrame(rafId);
254
+ stopRestore();
195
255
  element?.removeEventListener('scroll', save);
196
- // Final capture on blur: persist the last offset the scroll listener
197
- // OBSERVED, never a fresh read (which the navigator may have forced
198
- // to 0 while collapsing the hidden screen). When the user never
199
- // scrolled this session there is nothing newer to persist than the
200
- // live saves already recorded.
256
+ // Removing a listener that was never added is a no-op, so this needs no
257
+ // flag tracking whether the loop branch ran.
258
+ for (const type of USER_TAKEOVER_EVENTS) {
259
+ element?.removeEventListener(type, stopRestore);
260
+ }
261
+ // Final capture: persist the last offset the scroll listener OBSERVED,
262
+ // never a fresh read (which the navigator may have forced to 0 while
263
+ // collapsing the hidden screen). When the user never scrolled this
264
+ // session there is nothing newer than the live saves already recorded.
201
265
  if (lastObservedOffset !== null) {
202
- const currentKey = scrollKeyRef.current;
203
- if (enabledRef.current && currentKey !== null) {
204
- store.save(currentKey, lastObservedOffset);
205
- }
266
+ store.save(scrollKey, lastObservedOffset);
206
267
  }
207
268
  };
208
- }, [store]));
269
+ }, [store, scrollKey, enabled, target]));
270
+ return WEB_BINDING;
209
271
  }
210
272
 
211
273
  /**
@@ -1 +1 @@
1
- {"version":3,"names":["createContext","useCallback","useContext","useMemo","useRef","useFocusEffect","useRoute","createScroller","ScrollOffsetStore","deriveScrollKey","jsx","_jsx","ScrollOffsetContext","displayName","RESTORE_FRAME_CAP","RESTORE_STICK_TOLERANCE_PX","history","scrollRestoration","ScrollRestorationProvider","children","store","Provider","value","useScrollOffsetStore","Error","useScrollRestoration","target","options","route","subKey","key","enabled","scrollKey","targetRef","current","enabledRef","scrollKeyRef","undefined","scroller","element","window","resolveScrollEventTarget","lastObservedOffset","save","currentKey","offset","getOffset","canScroll","targetOffset","read","rafId","requestAnimationFrame","framesLeft","applyOffset","setOffset","reached","Math","abs","addEventListener","passive","cancelAnimationFrame","removeEventListener","EventTarget","handle","getScrollableNode","node"],"sourceRoot":"../../../src","sources":["scroll/index.web.tsx"],"mappings":"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","ignoreList":[]}
1
+ {"version":3,"names":["useCallback","useRef","useScrollRestorationContext","createScroller","deriveScrollKey","ScrollRestorationProvider","RESTORE_FRAME_CAP","RESTORE_STICK_TOLERANCE_PX","WEB_BINDING","onScroll","undefined","USER_TAKEOVER_EVENTS","useScrollRestoration","target","options","store","adapter","contentId","useScreenContentId","enabled","scrollKey","key","resetKeyRef","useScreenFocusEffect","scroller","element","window","resolveScrollEventTarget","lastObservedOffset","echoOffset","save","offset","getOffset","canScroll","targetOffset","read","isReset","has","alreadyReset","current","rafId","stopRestore","cancelAnimationFrame","setOffset","requestAnimationFrame","framesLeft","applyOffset","reached","Math","abs","type","addEventListener","passive","removeEventListener","EventTarget","handle","getScrollableNode","node"],"sourceRoot":"../../../src","sources":["scroll/index.web.tsx"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,WAAW,EAAEC,MAAM,QAAQ,OAAO;AAE3C,SAASC,2BAA2B,QAAQ,cAAW;AACvD,SAASC,cAAc,QAAQ,qBAAkB;AACjD,SAASC,eAAe,QAAQ,YAAS;AAOzC,SAASC,yBAAyB,QAAQ,cAAW;AAYrD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,iBAAiB,GAAG,EAAE;;AAE5B;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,0BAA0B,GAAG,CAAC;;AAEpC;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,WAAqC,GAAG;EAAEC,QAAQ,EAAEA,CAAA,KAAMC;AAAU,CAAC;;AAE3E;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,oBAAoB,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,CAAC;;AAE9E;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,oBAAoBA,CAClCC,MAA+B,EAC/BC,OAAqC,EACX;EAC1B,MAAM;IAAEC,KAAK;IAAEC;EAAQ,CAAC,GAAGd,2BAA2B,CAAC,CAAC;EACxD,MAAMe,SAAS,GAAGD,OAAO,CAACE,kBAAkB,CAAC,CAAC;EAC9C,MAAMC,OAAO,GAAGL,OAAO,EAAEK,OAAO,IAAI,IAAI;EACxC,MAAMC,SAAS,GAAGhB,eAAe,CAACa,SAAS,EAAEH,OAAO,EAAEO,GAAG,CAAC;;EAE1D;EACA;EACA;EACA;EACA;EACA,MAAM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","ignoreList":[]}
@@ -0,0 +1,54 @@
1
+ "use strict";
2
+
3
+ /**
4
+ * The write half of a scrollable, on native. There is no read half: native
5
+ * offers no way to sample a list's offset from outside it, so offsets arrive
6
+ * through the `onScroll` binding the hook returns instead.
7
+ */
8
+
9
+ function hasScrollToOffset(value) {
10
+ return typeof value === 'object' && value !== null && typeof value.scrollToOffset === 'function';
11
+ }
12
+ function hasScrollTo(value) {
13
+ return typeof value === 'object' && value !== null && typeof value.scrollTo === 'function';
14
+ }
15
+
16
+ /**
17
+ * Build a {@link NativeScroller} for a target.
18
+ *
19
+ * `scrollToOffset` (`FlatList`, `FlashList`) is preferred over `scrollTo`
20
+ * (`ScrollView`) because a list exposes both shapes on some versions and only
21
+ * the former accounts for the list's own header. The `'window'` sentinel has no
22
+ * native meaning — there is no document scroller — so it resolves to a no-op
23
+ * rather than an error: a call site shared with web legitimately passes it.
24
+ *
25
+ * The handle is re-resolved on every write; it is never cached, because a ref
26
+ * can be swapped or detached between the schedule and the write.
27
+ */
28
+ export function createScroller(target) {
29
+ if (target === 'window') {
30
+ return {
31
+ setOffset: () => undefined
32
+ };
33
+ }
34
+ return {
35
+ setOffset: offset => {
36
+ const current = target.current;
37
+ if (current == null) return;
38
+ if (hasScrollToOffset(current)) {
39
+ current.scrollToOffset({
40
+ offset,
41
+ animated: false
42
+ });
43
+ return;
44
+ }
45
+ if (hasScrollTo(current)) {
46
+ current.scrollTo({
47
+ y: offset,
48
+ animated: false
49
+ });
50
+ }
51
+ }
52
+ };
53
+ }
54
+ //# sourceMappingURL=scrollable.native.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"names":["hasScrollToOffset","value","scrollToOffset","hasScrollTo","scrollTo","createScroller","target","setOffset","undefined","offset","current","animated","y"],"sourceRoot":"../../../src","sources":["scroll/scrollable.native.ts"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;;AAKA,SAASA,iBAAiBA,CACxBC,KAAc,EAC+C;EAC7D,OACE,OAAOA,KAAK,KAAK,QAAQ,IACzBA,KAAK,KAAK,IAAI,IACd,OAAQA,KAAK,CAAsBC,cAAc,KAAK,UAAU;AAEpE;AAEA,SAASC,WAAWA,CAClBF,KAAc,EACyC;EACvD,OACE,OAAOA,KAAK,KAAK,QAAQ,IACzBA,KAAK,KAAK,IAAI,IACd,OAAQA,KAAK,CAAsBG,QAAQ,KAAK,UAAU;AAE9D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAC5BC,MAA+B,EACf;EAChB,IAAIA,MAAM,KAAK,QAAQ,EAAE;IACvB,OAAO;MAAEC,SAAS,EAAEA,CAAA,KAAMC;IAAU,CAAC;EACvC;EAEA,OAAO;IACLD,SAAS,EAAGE,MAAM,IAAK;MACrB,MAAMC,OAAO,GAAGJ,MAAM,CAACI,OAAO;MAC9B,IAAIA,OAAO,IAAI,IAAI,EAAE;MACrB,IAAIV,iBAAiB,CAACU,OAAO,CAAC,EAAE;QAC9BA,OAAO,CAACR,cAAc,CAAC;UAAEO,MAAM;UAAEE,QAAQ,EAAE;QAAM,CAAC,CAAC;QACnD;MACF;MACA,IAAIR,WAAW,CAACO,OAAO,CAAC,EAAE;QACxBA,OAAO,CAACN,QAAQ,CAAC;UAAEQ,CAAC,EAAEH,MAAM;UAAEE,QAAQ,EAAE;QAAM,CAAC,CAAC;MAClD;IACF;EACF,CAAC;AACH","ignoreList":[]}
@@ -5,16 +5,12 @@
5
5
  *
6
6
  * This file deliberately contains NO React and NO DOM/native imports so the
7
7
  * logic can be unit-tested in isolation and shared verbatim by the web and
8
- * native barrels. The web barrel drives it with real scroll offsets; the
9
- * native barrel never instantiates it (native-stack already restores scroll).
8
+ * native barrels.
10
9
  */
11
-
12
10
  /**
13
- * Separator between the navigation route key and an optional caller-supplied
14
- * sub-key. A route may host more than one independently-scrolling list (e.g.
15
- * a tabbed profile screen), so each list contributes its own sub-key.
11
+ * Separator between the two components of a storage key.
16
12
  *
17
- * `\0` (NUL) can never appear in a React Navigation route key or in a
13
+ * `\0` (NUL) can never appear in a router-derived content id or in a
18
14
  * developer-authored sub-key, so it is collision-free as a delimiter. It is
19
15
  * written as an escape sequence (not a literal byte) so the source stays
20
16
  * text-diffable.
@@ -22,28 +18,48 @@
22
18
  const COMPOSITE_KEY_SEPARATOR = '\0';
23
19
 
24
20
  /**
25
- * Derive the storage key for a scrollable from its owning route key and an
26
- * optional caller sub-key.
21
+ * Derive the storage key for a scrollable from WHAT its screen is showing plus
22
+ * an optional caller sub-key.
23
+ *
24
+ * The key is CONTENT identity, deliberately not the navigation entry. An offset
25
+ * belongs to what the user was looking at, so returning to it restores however
26
+ * they got there — browser Back or Forward, a tab press, an in-app link — and
27
+ * only content never seen this session opens at the top. Keying on the entry
28
+ * would defeat that: a tab press and `router.replace` both mint a fresh entry,
29
+ * so both would open at the top even though the user has been there.
30
+ *
31
+ * The trade, chosen rather than overlooked: the same content occupying two LIVE
32
+ * entries now shares one offset. Pushing `/@alice` on top of `/@alice` in a
33
+ * native stack restores the first one's position instead of opening at the top,
34
+ * and while both are mounted each writes to the same key. That is the price of
35
+ * a tab press restoring, which is the behaviour that was asked for.
27
36
  *
28
- * - `routeKey` is React Navigation's stable per-route `route.key`.
29
- * - `subKey` distinguishes multiple scrollables that share a single route.
37
+ * The key is always the same two-field composite, with an absent sub-key
38
+ * written as empty, so two different identities can never collapse onto one key
39
+ * by omission.
30
40
  *
31
- * Returns `null` when there is no route key to anchor against (the scrollable
32
- * is not inside a navigator), which the caller treats as "do not persist".
41
+ * Returns `null` when there is no content id to anchor against (the scrollable
42
+ * is not inside a navigator, or the adapter cannot answer), which every caller
43
+ * treats as "do not persist and do not restore".
33
44
  */
34
- export function deriveScrollKey(routeKey, subKey) {
35
- if (!routeKey) return null;
36
- if (subKey === undefined || subKey === '') return routeKey;
37
- return `${routeKey}${COMPOSITE_KEY_SEPARATOR}${subKey}`;
45
+ export function deriveScrollKey(contentId, subKey) {
46
+ if (!contentId) return null;
47
+ return [contentId, subKey ?? ''].join(COMPOSITE_KEY_SEPARATOR);
38
48
  }
39
49
 
40
50
  /**
41
51
  * In-memory map of `scrollKey -> last-known scroll offset`.
42
52
  *
43
- * Mirrors the semantics of Bluesky's `Map<screenKey, scrollY>`: offsets live
44
- * only for the lifetime of the document/session. We never persist them — a
45
- * full reload should start at the top and we never auto-evict, because a
46
- * route can be revisited via browser Forward/Back long after it blurred.
53
+ * Offsets live only for the lifetime of the document/session. We never persist
54
+ * them a full reload should start at the top and we never auto-evict,
55
+ * because an entry can be revisited via browser Forward/Back long after it
56
+ * blurred.
57
+ *
58
+ * Deliberately an instance held in React context rather than a module-level
59
+ * singleton: a dependency tree can legitimately contain two copies of Bloom
60
+ * (a hoisted one plus a nested one under another Oxy package), and a
61
+ * module-global would then exist twice with no way for either half to see the
62
+ * other's offsets.
47
63
  */
48
64
  export class ScrollOffsetStore {
49
65
  offsets = new Map();
@@ -54,19 +70,25 @@ export class ScrollOffsetStore {
54
70
  }
55
71
 
56
72
  /**
57
- * Read the saved offset for a key. Returns `0` when nothing was saved, so
58
- * callers can restore unconditionally (an unseen list restores to the top).
73
+ * Read the saved offset for a key. Returns `0` when nothing was saved, which
74
+ * is the same value a caller writes when {@link has} is false — an unseen
75
+ * list restores to the top.
59
76
  */
60
77
  read(key) {
61
78
  return this.offsets.get(key) ?? 0;
62
79
  }
63
80
 
64
- /** Whether an offset was ever saved for this key. */
81
+ /**
82
+ * Whether an offset was ever saved for this key. This — not `read() > 0` —
83
+ * is what separates "restore" from "reset": a key that was never seen and a
84
+ * key deliberately saved at the top both read 0, and only the store knows
85
+ * which is which.
86
+ */
65
87
  has(key) {
66
88
  return this.offsets.has(key);
67
89
  }
68
90
 
69
- /** Drop a saved offset (e.g. when a route is permanently removed). */
91
+ /** Drop a saved offset (e.g. when an entry is permanently removed). */
70
92
  forget(key) {
71
93
  this.offsets.delete(key);
72
94
  }
@@ -1 +1 @@
1
- {"version":3,"names":["COMPOSITE_KEY_SEPARATOR","deriveScrollKey","routeKey","subKey","undefined","ScrollOffsetStore","offsets","Map","save","key","offset","set","read","get","has","forget","delete","clear","size"],"sourceRoot":"../../../src","sources":["scroll/store.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMA,uBAAuB,GAAG,IAAI;;AAEpC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,eAAeA,CAC7BC,QAA4B,EAC5BC,MAAe,EACA;EACf,IAAI,CAACD,QAAQ,EAAE,OAAO,IAAI;EAC1B,IAAIC,MAAM,KAAKC,SAAS,IAAID,MAAM,KAAK,EAAE,EAAE,OAAOD,QAAQ;EAC1D,OAAO,GAAGA,QAAQ,GAAGF,uBAAuB,GAAGG,MAAM,EAAE;AACzD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAME,iBAAiB,CAAC;EACZC,OAAO,GAAG,IAAIC,GAAG,CAAiB,CAAC;;EAEpD;EACAC,IAAIA,CAACC,GAAW,EAAEC,MAAc,EAAQ;IACtC,IAAI,CAACJ,OAAO,CAACK,GAAG,CAACF,GAAG,EAAEC,MAAM,GAAG,CAAC,GAAGA,MAAM,GAAG,CAAC,CAAC;EAChD;;EAEA;AACF;AACA;AACA;EACEE,IAAIA,CAACH,GAAW,EAAU;IACxB,OAAO,IAAI,CAACH,OAAO,CAACO,GAAG,CAACJ,GAAG,CAAC,IAAI,CAAC;EACnC;;EAEA;EACAK,GAAGA,CAACL,GAAW,EAAW;IACxB,OAAO,IAAI,CAACH,OAAO,CAACQ,GAAG,CAACL,GAAG,CAAC;EAC9B;;EAEA;EACAM,MAAMA,CAACN,GAAW,EAAQ;IACxB,IAAI,CAACH,OAAO,CAACU,MAAM,CAACP,GAAG,CAAC;EAC1B;;EAEA;EACAQ,KAAKA,CAAA,EAAS;IACZ,IAAI,CAACX,OAAO,CAACW,KAAK,CAAC,CAAC;EACtB;;EAEA;EACA,IAAIC,IAAIA,CAAA,EAAW;IACjB,OAAO,IAAI,CAACZ,OAAO,CAACY,IAAI;EAC1B;AACF","ignoreList":[]}
1
+ {"version":3,"names":["COMPOSITE_KEY_SEPARATOR","deriveScrollKey","contentId","subKey","join","ScrollOffsetStore","offsets","Map","save","key","offset","set","read","get","has","forget","delete","clear","size"],"sourceRoot":"../../../src","sources":["scroll/store.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMA,uBAAuB,GAAG,IAAI;;AAEpC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,eAAeA,CAC7BC,SAAwB,EACxBC,MAAe,EACA;EACf,IAAI,CAACD,SAAS,EAAE,OAAO,IAAI;EAC3B,OAAO,CAACA,SAAS,EAAEC,MAAM,IAAI,EAAE,CAAC,CAACC,IAAI,CAACJ,uBAAuB,CAAC;AAChE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMK,iBAAiB,CAAC;EACZC,OAAO,GAAG,IAAIC,GAAG,CAAiB,CAAC;;EAEpD;EACAC,IAAIA,CAACC,GAAW,EAAEC,MAAc,EAAQ;IACtC,IAAI,CAACJ,OAAO,CAACK,GAAG,CAACF,GAAG,EAAEC,MAAM,GAAG,CAAC,GAAGA,MAAM,GAAG,CAAC,CAAC;EAChD;;EAEA;AACF;AACA;AACA;AACA;EACEE,IAAIA,CAACH,GAAW,EAAU;IACxB,OAAO,IAAI,CAACH,OAAO,CAACO,GAAG,CAACJ,GAAG,CAAC,IAAI,CAAC;EACnC;;EAEA;AACF;AACA;AACA;AACA;AACA;EACEK,GAAGA,CAACL,GAAW,EAAW;IACxB,OAAO,IAAI,CAACH,OAAO,CAACQ,GAAG,CAACL,GAAG,CAAC;EAC9B;;EAEA;EACAM,MAAMA,CAACN,GAAW,EAAQ;IACxB,IAAI,CAACH,OAAO,CAACU,MAAM,CAACP,GAAG,CAAC;EAC1B;;EAEA;EACAQ,KAAKA,CAAA,EAAS;IACZ,IAAI,CAACX,OAAO,CAACW,KAAK,CAAC,CAAC;EACtB;;EAEA;EACA,IAAIC,IAAIA,CAAA,EAAW;IACjB,OAAO,IAAI,CAACZ,OAAO,CAACY,IAAI;EAC1B;AACF","ignoreList":[]}