@oxyhq/bloom 0.6.20 → 0.6.22
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.
- package/lib/commonjs/scroll/index.js +39 -0
- package/lib/commonjs/scroll/index.js.map +1 -0
- package/lib/commonjs/scroll/index.web.js +143 -0
- package/lib/commonjs/scroll/index.web.js.map +1 -0
- package/lib/commonjs/scroll/scrollable.web.js +64 -0
- package/lib/commonjs/scroll/scrollable.web.js.map +1 -0
- package/lib/commonjs/scroll/store.js +90 -0
- package/lib/commonjs/scroll/store.js.map +1 -0
- package/lib/commonjs/scroll/types.js +6 -0
- package/lib/commonjs/scroll/types.js.map +1 -0
- package/lib/commonjs/theme/color-scope/index.web.js +18 -5
- package/lib/commonjs/theme/color-scope/index.web.js.map +1 -1
- package/lib/module/scroll/index.js +34 -0
- package/lib/module/scroll/index.js.map +1 -0
- package/lib/module/scroll/index.web.js +137 -0
- package/lib/module/scroll/index.web.js.map +1 -0
- package/lib/module/scroll/scrollable.web.js +60 -0
- package/lib/module/scroll/scrollable.web.js.map +1 -0
- package/lib/module/scroll/store.js +84 -0
- package/lib/module/scroll/store.js.map +1 -0
- package/lib/module/scroll/types.js +4 -0
- package/lib/module/scroll/types.js.map +1 -0
- package/lib/module/theme/color-scope/index.web.js +18 -5
- package/lib/module/theme/color-scope/index.web.js.map +1 -1
- package/lib/typescript/commonjs/scroll/index.d.ts +27 -0
- package/lib/typescript/commonjs/scroll/index.d.ts.map +1 -0
- package/lib/typescript/commonjs/scroll/index.web.d.ts +22 -0
- package/lib/typescript/commonjs/scroll/index.web.d.ts.map +1 -0
- package/lib/typescript/commonjs/scroll/scrollable.web.d.ts +17 -0
- package/lib/typescript/commonjs/scroll/scrollable.web.d.ts.map +1 -0
- package/lib/typescript/commonjs/scroll/store.d.ts +46 -0
- package/lib/typescript/commonjs/scroll/store.d.ts.map +1 -0
- package/lib/typescript/commonjs/scroll/types.d.ts +46 -0
- package/lib/typescript/commonjs/scroll/types.d.ts.map +1 -0
- package/lib/typescript/commonjs/theme/color-scope/index.web.d.ts.map +1 -1
- package/lib/typescript/module/scroll/index.d.ts +27 -0
- package/lib/typescript/module/scroll/index.d.ts.map +1 -0
- package/lib/typescript/module/scroll/index.web.d.ts +22 -0
- package/lib/typescript/module/scroll/index.web.d.ts.map +1 -0
- package/lib/typescript/module/scroll/scrollable.web.d.ts +17 -0
- package/lib/typescript/module/scroll/scrollable.web.d.ts.map +1 -0
- package/lib/typescript/module/scroll/store.d.ts +46 -0
- package/lib/typescript/module/scroll/store.d.ts.map +1 -0
- package/lib/typescript/module/scroll/types.d.ts +46 -0
- package/lib/typescript/module/scroll/types.d.ts.map +1 -0
- package/lib/typescript/module/theme/color-scope/index.web.d.ts.map +1 -1
- package/package.json +22 -1
- package/src/__tests__/BloomColorScope.test.tsx +67 -0
- package/src/__tests__/scroll-native.test.ts +25 -0
- package/src/__tests__/scroll-store.test.ts +85 -0
- package/src/scroll/index.ts +47 -0
- package/src/scroll/index.web.tsx +167 -0
- package/src/scroll/scrollable.web.ts +75 -0
- package/src/scroll/store.ts +84 -0
- package/src/scroll/types.ts +48 -0
- package/src/theme/color-scope/index.web.tsx +26 -2
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oxyhq/bloom",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.22",
|
|
4
4
|
"description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
|
|
5
5
|
"main": "lib/commonjs/index.js",
|
|
6
6
|
"module": "lib/module/index.js",
|
|
@@ -535,6 +535,22 @@
|
|
|
535
535
|
"default": "./lib/commonjs/fonts/index.js"
|
|
536
536
|
}
|
|
537
537
|
},
|
|
538
|
+
"./scroll": {
|
|
539
|
+
"react-native": "./src/scroll/index.ts",
|
|
540
|
+
"browser": {
|
|
541
|
+
"types": "./lib/typescript/module/scroll/index.web.d.ts",
|
|
542
|
+
"import": "./lib/module/scroll/index.web.js",
|
|
543
|
+
"require": "./lib/commonjs/scroll/index.web.js"
|
|
544
|
+
},
|
|
545
|
+
"import": {
|
|
546
|
+
"types": "./lib/typescript/module/scroll/index.d.ts",
|
|
547
|
+
"default": "./lib/module/scroll/index.js"
|
|
548
|
+
},
|
|
549
|
+
"require": {
|
|
550
|
+
"types": "./lib/typescript/commonjs/scroll/index.d.ts",
|
|
551
|
+
"default": "./lib/commonjs/scroll/index.js"
|
|
552
|
+
}
|
|
553
|
+
},
|
|
538
554
|
"./package.json": "./package.json"
|
|
539
555
|
},
|
|
540
556
|
"files": [
|
|
@@ -615,6 +631,7 @@
|
|
|
615
631
|
}
|
|
616
632
|
},
|
|
617
633
|
"devDependencies": {
|
|
634
|
+
"@react-navigation/native": "^7.0.0",
|
|
618
635
|
"@storybook/addon-docs": "^10",
|
|
619
636
|
"@storybook/react-vite": "^10",
|
|
620
637
|
"@testing-library/react-native": "^13.3.3",
|
|
@@ -645,6 +662,7 @@
|
|
|
645
662
|
"vite": "^7"
|
|
646
663
|
},
|
|
647
664
|
"peerDependencies": {
|
|
665
|
+
"@react-navigation/native": ">=6.0.0",
|
|
648
666
|
"expo": "*",
|
|
649
667
|
"expo-font": "*",
|
|
650
668
|
"react": ">=18.0.0",
|
|
@@ -658,6 +676,9 @@
|
|
|
658
676
|
"sonner-native": ">=0.17.0"
|
|
659
677
|
},
|
|
660
678
|
"peerDependenciesMeta": {
|
|
679
|
+
"@react-navigation/native": {
|
|
680
|
+
"optional": true
|
|
681
|
+
},
|
|
661
682
|
"expo": {
|
|
662
683
|
"optional": true
|
|
663
684
|
},
|
|
@@ -4,6 +4,7 @@ import { render } from '@testing-library/react-native';
|
|
|
4
4
|
|
|
5
5
|
import { BloomThemeProvider } from '../theme/BloomThemeProvider';
|
|
6
6
|
import { BloomColorScope } from '../theme/color-scope';
|
|
7
|
+
import { BloomColorScope as BloomColorScopeWeb } from '../theme/color-scope/index.web';
|
|
7
8
|
import { useBloomTheme } from '../theme/use-theme';
|
|
8
9
|
|
|
9
10
|
function CurrentPreset() {
|
|
@@ -86,4 +87,70 @@ describe('BloomColorScope', () => {
|
|
|
86
87
|
).toThrow('BloomColorScope must be used within a <BloomThemeProvider>');
|
|
87
88
|
consoleError.mockRestore();
|
|
88
89
|
});
|
|
90
|
+
|
|
91
|
+
// Web variant: regression for the production crash on mention.earth profile
|
|
92
|
+
// screens. On web the `asChild` child is frequently an RNW component whose
|
|
93
|
+
// `style` is a React Native style ARRAY. The web variant must merge styles as
|
|
94
|
+
// an array (RNW flattens it) and must NOT spread the array into an object
|
|
95
|
+
// literal — that copies the array's numeric indices as keys and makes RNW
|
|
96
|
+
// throw `Failed to set an indexed property [0] on 'CSSStyleDeclaration'`.
|
|
97
|
+
describe('web variant (index.web)', () => {
|
|
98
|
+
it('merges an array-valued child style without producing numeric index keys (asChild)', () => {
|
|
99
|
+
const { getByTestId } = render(
|
|
100
|
+
<BloomThemeProvider defaultColorPreset="blue" fonts={false}>
|
|
101
|
+
<BloomColorScopeWeb colorPreset="purple" asChild>
|
|
102
|
+
<StyledChild style={[{ padding: 8 }, { margin: 4 }]} />
|
|
103
|
+
</BloomColorScopeWeb>
|
|
104
|
+
</BloomThemeProvider>,
|
|
105
|
+
);
|
|
106
|
+
|
|
107
|
+
expect(getByTestId('preset').props.children).toBe('purple');
|
|
108
|
+
|
|
109
|
+
const mergedStyle = getByTestId('styled-child').props.style;
|
|
110
|
+
// The merge must be an array (the RNW-safe form), never an object literal
|
|
111
|
+
// with the array's numeric indices spread in as keys.
|
|
112
|
+
expect(Array.isArray(mergedStyle)).toBe(true);
|
|
113
|
+
|
|
114
|
+
// No numeric index keys must appear anywhere in the merged style. If the
|
|
115
|
+
// child array had been spread into an object literal, we'd see '0', '1'.
|
|
116
|
+
const collectKeys = (value: unknown): string[] => {
|
|
117
|
+
if (Array.isArray(value)) return value.flatMap(collectKeys);
|
|
118
|
+
if (value && typeof value === 'object') return Object.keys(value);
|
|
119
|
+
return [];
|
|
120
|
+
};
|
|
121
|
+
const keys = collectKeys(mergedStyle);
|
|
122
|
+
expect(keys).not.toContain('0');
|
|
123
|
+
expect(keys).not.toContain('1');
|
|
124
|
+
|
|
125
|
+
// The child's own array styles must be preserved (and win over scope vars).
|
|
126
|
+
const flat = (Array.isArray(mergedStyle) ? mergedStyle : [mergedStyle])
|
|
127
|
+
.flat(Infinity)
|
|
128
|
+
.filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === 'object');
|
|
129
|
+
expect(flat).toEqual(
|
|
130
|
+
expect.arrayContaining([
|
|
131
|
+
expect.objectContaining({ padding: 8 }),
|
|
132
|
+
expect.objectContaining({ margin: 4 }),
|
|
133
|
+
]),
|
|
134
|
+
);
|
|
135
|
+
});
|
|
136
|
+
|
|
137
|
+
it('clones the single child and merges scope vars into its style array (asChild)', () => {
|
|
138
|
+
const { getByTestId } = render(
|
|
139
|
+
<BloomThemeProvider defaultColorPreset="blue" fonts={false}>
|
|
140
|
+
<BloomColorScopeWeb colorPreset="purple" asChild>
|
|
141
|
+
<StyledChild style={{ padding: 8 }} />
|
|
142
|
+
</BloomColorScopeWeb>
|
|
143
|
+
</BloomThemeProvider>,
|
|
144
|
+
);
|
|
145
|
+
|
|
146
|
+
const mergedStyle = getByTestId('styled-child').props.style;
|
|
147
|
+
expect(Array.isArray(mergedStyle)).toBe(true);
|
|
148
|
+
const flat = (Array.isArray(mergedStyle) ? mergedStyle : [mergedStyle])
|
|
149
|
+
.flat(Infinity)
|
|
150
|
+
.filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === 'object');
|
|
151
|
+
expect(flat).toEqual(
|
|
152
|
+
expect.arrayContaining([expect.objectContaining({ padding: 8 })]),
|
|
153
|
+
);
|
|
154
|
+
});
|
|
155
|
+
});
|
|
89
156
|
});
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import {
|
|
2
|
+
ScrollRestorationProvider,
|
|
3
|
+
useScrollRestoration,
|
|
4
|
+
} from '../scroll/index';
|
|
5
|
+
|
|
6
|
+
// The native barrel is a deliberate no-op: native-stack already preserves
|
|
7
|
+
// scroll. These tests pin that contract so a future refactor can't silently
|
|
8
|
+
// turn the native path into something that touches the DOM or throws.
|
|
9
|
+
|
|
10
|
+
describe('native scroll-restoration barrel', () => {
|
|
11
|
+
it('ScrollRestorationProvider renders its children unchanged', () => {
|
|
12
|
+
const child = { sentinel: true } as unknown as React.ReactElement;
|
|
13
|
+
expect(ScrollRestorationProvider({ children: child })).toBe(child);
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
it('useScrollRestoration is a no-op for any target/options', () => {
|
|
17
|
+
const ref = { current: null };
|
|
18
|
+
expect(() => useScrollRestoration(ref)).not.toThrow();
|
|
19
|
+
expect(() => useScrollRestoration('window')).not.toThrow();
|
|
20
|
+
expect(() =>
|
|
21
|
+
useScrollRestoration(ref, { key: 'feed', enabled: true }),
|
|
22
|
+
).not.toThrow();
|
|
23
|
+
expect(useScrollRestoration(ref)).toBeUndefined();
|
|
24
|
+
});
|
|
25
|
+
});
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { ScrollOffsetStore, deriveScrollKey } from '../scroll/store';
|
|
2
|
+
|
|
3
|
+
describe('deriveScrollKey', () => {
|
|
4
|
+
it('returns null when there is no route key', () => {
|
|
5
|
+
expect(deriveScrollKey(undefined)).toBeNull();
|
|
6
|
+
expect(deriveScrollKey(undefined, 'feed')).toBeNull();
|
|
7
|
+
});
|
|
8
|
+
|
|
9
|
+
it('returns the route key verbatim when no sub-key is given', () => {
|
|
10
|
+
expect(deriveScrollKey('Home-abc')).toBe('Home-abc');
|
|
11
|
+
});
|
|
12
|
+
|
|
13
|
+
it('treats an empty sub-key the same as no sub-key', () => {
|
|
14
|
+
expect(deriveScrollKey('Home-abc', '')).toBe('Home-abc');
|
|
15
|
+
});
|
|
16
|
+
|
|
17
|
+
it('composes route key and sub-key for multiple lists on one route', () => {
|
|
18
|
+
const a = deriveScrollKey('Profile-xyz', 'posts');
|
|
19
|
+
const b = deriveScrollKey('Profile-xyz', 'media');
|
|
20
|
+
expect(a).not.toBe(b);
|
|
21
|
+
expect(a).toBe('Profile-xyz\0posts');
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
it('does not collide across routes that share a sub-key', () => {
|
|
25
|
+
expect(deriveScrollKey('A', 'feed')).not.toBe(deriveScrollKey('B', 'feed'));
|
|
26
|
+
});
|
|
27
|
+
});
|
|
28
|
+
|
|
29
|
+
describe('ScrollOffsetStore', () => {
|
|
30
|
+
it('reads 0 for an unseen key so callers can restore unconditionally', () => {
|
|
31
|
+
const store = new ScrollOffsetStore();
|
|
32
|
+
expect(store.read('missing')).toBe(0);
|
|
33
|
+
expect(store.has('missing')).toBe(false);
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
it('saves and reads an offset back', () => {
|
|
37
|
+
const store = new ScrollOffsetStore();
|
|
38
|
+
store.save('k', 420);
|
|
39
|
+
expect(store.read('k')).toBe(420);
|
|
40
|
+
expect(store.has('k')).toBe(true);
|
|
41
|
+
expect(store.size).toBe(1);
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
it('keeps offsets independent per key', () => {
|
|
45
|
+
const store = new ScrollOffsetStore();
|
|
46
|
+
store.save('a', 100);
|
|
47
|
+
store.save('b', 250);
|
|
48
|
+
expect(store.read('a')).toBe(100);
|
|
49
|
+
expect(store.read('b')).toBe(250);
|
|
50
|
+
expect(store.size).toBe(2);
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
it('overwrites the offset on subsequent saves', () => {
|
|
54
|
+
const store = new ScrollOffsetStore();
|
|
55
|
+
store.save('k', 100);
|
|
56
|
+
store.save('k', 300);
|
|
57
|
+
expect(store.read('k')).toBe(300);
|
|
58
|
+
expect(store.size).toBe(1);
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
it('clamps negative offsets to 0 (e.g. rubber-band overscroll)', () => {
|
|
62
|
+
const store = new ScrollOffsetStore();
|
|
63
|
+
store.save('k', -50);
|
|
64
|
+
expect(store.read('k')).toBe(0);
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
it('forgets a single key', () => {
|
|
68
|
+
const store = new ScrollOffsetStore();
|
|
69
|
+
store.save('a', 1);
|
|
70
|
+
store.save('b', 2);
|
|
71
|
+
store.forget('a');
|
|
72
|
+
expect(store.has('a')).toBe(false);
|
|
73
|
+
expect(store.read('b')).toBe(2);
|
|
74
|
+
expect(store.size).toBe(1);
|
|
75
|
+
});
|
|
76
|
+
|
|
77
|
+
it('clears every key', () => {
|
|
78
|
+
const store = new ScrollOffsetStore();
|
|
79
|
+
store.save('a', 1);
|
|
80
|
+
store.save('b', 2);
|
|
81
|
+
store.clear();
|
|
82
|
+
expect(store.size).toBe(0);
|
|
83
|
+
expect(store.has('a')).toBe(false);
|
|
84
|
+
});
|
|
85
|
+
});
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Native variant of the scroll-restoration primitive — a deliberate no-op.
|
|
3
|
+
*
|
|
4
|
+
* React Navigation's native-stack keeps every screen mounted while it is in the
|
|
5
|
+
* stack, so a list's scroll position survives a push/pop for free. There is
|
|
6
|
+
* nothing to save or restore. We still ship the full API surface (provider +
|
|
7
|
+
* hook) so consumers write one set of call sites that compile and run on every
|
|
8
|
+
* platform; on native the provider just renders its children and the hook does
|
|
9
|
+
* nothing.
|
|
10
|
+
*
|
|
11
|
+
* Web bundlers select `./index.web` via the `"browser"` export condition in
|
|
12
|
+
* `package.json`; native bundlers fall through to this file.
|
|
13
|
+
*/
|
|
14
|
+
import type { ReactElement } from 'react';
|
|
15
|
+
import type {
|
|
16
|
+
ScrollRestorationProviderProps,
|
|
17
|
+
ScrollRestorationTarget,
|
|
18
|
+
UseScrollRestorationOptions,
|
|
19
|
+
} from './types';
|
|
20
|
+
|
|
21
|
+
export type {
|
|
22
|
+
ScrollableHandle,
|
|
23
|
+
ScrollRestorationProviderProps,
|
|
24
|
+
ScrollRestorationTarget,
|
|
25
|
+
UseScrollRestorationOptions,
|
|
26
|
+
} from './types';
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* No-op provider. Renders children unchanged — native scroll persistence is
|
|
30
|
+
* handled by the navigator, so no per-route state is kept.
|
|
31
|
+
*/
|
|
32
|
+
export function ScrollRestorationProvider({
|
|
33
|
+
children,
|
|
34
|
+
}: ScrollRestorationProviderProps): ReactElement {
|
|
35
|
+
return children as ReactElement;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* No-op hook. Accepts the same arguments as the web implementation so call
|
|
40
|
+
* sites are identical across platforms.
|
|
41
|
+
*/
|
|
42
|
+
export function useScrollRestoration(
|
|
43
|
+
_target: ScrollRestorationTarget,
|
|
44
|
+
_options?: UseScrollRestorationOptions,
|
|
45
|
+
): void {
|
|
46
|
+
// Intentionally empty: native-stack already preserves scroll position.
|
|
47
|
+
}
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Web variant of the scroll-restoration primitive.
|
|
3
|
+
*
|
|
4
|
+
* Mirrors the proven Bluesky pattern (`history.scrollRestoration = 'manual'`
|
|
5
|
+
* plus an in-memory `Map<routeKey, offset>` saved on blur and restored on focus
|
|
6
|
+
* inside a single `requestAnimationFrame`) with one deliberate difference:
|
|
7
|
+
* Bluesky restores the WINDOW scroller, whereas Oxy apps keep multi-column
|
|
8
|
+
* layouts whose feed scrolls an INNER container. So we restore the offset of a
|
|
9
|
+
* caller-registered scrollable (a ref to an element / RN scroll component, or
|
|
10
|
+
* the `'window'` sentinel), keyed by the active navigation route.
|
|
11
|
+
*
|
|
12
|
+
* Native bundlers use `./index.ts` (a no-op); web bundlers select this file via
|
|
13
|
+
* the `"browser"` export condition in `package.json`.
|
|
14
|
+
*/
|
|
15
|
+
import { createContext, useCallback, useContext, useMemo, useRef } from 'react';
|
|
16
|
+
import { useFocusEffect, useRoute } from '@react-navigation/native';
|
|
17
|
+
|
|
18
|
+
import { createScroller } from './scrollable.web';
|
|
19
|
+
import { ScrollOffsetStore, deriveScrollKey } from './store';
|
|
20
|
+
import type {
|
|
21
|
+
ScrollRestorationProviderProps,
|
|
22
|
+
ScrollRestorationTarget,
|
|
23
|
+
UseScrollRestorationOptions,
|
|
24
|
+
} from './types';
|
|
25
|
+
|
|
26
|
+
export type {
|
|
27
|
+
ScrollableHandle,
|
|
28
|
+
ScrollRestorationProviderProps,
|
|
29
|
+
ScrollRestorationTarget,
|
|
30
|
+
UseScrollRestorationOptions,
|
|
31
|
+
} from './types';
|
|
32
|
+
|
|
33
|
+
const ScrollOffsetContext = createContext<ScrollOffsetStore | null>(null);
|
|
34
|
+
ScrollOffsetContext.displayName = 'BloomScrollOffsetContext';
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Switch the browser to manual scroll restoration exactly once per document.
|
|
38
|
+
*
|
|
39
|
+
* The browser's default `'auto'` restoration fights our manual restore on
|
|
40
|
+
* Back/Forward navigations. Doing this at module scope (guarded for SSR) means
|
|
41
|
+
* it is set before any provider mounts, matching Bluesky's module-level call.
|
|
42
|
+
*/
|
|
43
|
+
if (typeof history !== 'undefined' && 'scrollRestoration' in history) {
|
|
44
|
+
history.scrollRestoration = 'manual';
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Holds the per-route offset map for the subtree. One provider near the app
|
|
49
|
+
* root is enough; the store lives for the document's lifetime so offsets
|
|
50
|
+
* survive navigating away and back (including browser Back/Forward).
|
|
51
|
+
*/
|
|
52
|
+
export function ScrollRestorationProvider({
|
|
53
|
+
children,
|
|
54
|
+
}: ScrollRestorationProviderProps) {
|
|
55
|
+
const store = useMemo(() => new ScrollOffsetStore(), []);
|
|
56
|
+
return (
|
|
57
|
+
<ScrollOffsetContext.Provider value={store}>
|
|
58
|
+
{children}
|
|
59
|
+
</ScrollOffsetContext.Provider>
|
|
60
|
+
);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
function useScrollOffsetStore(): ScrollOffsetStore {
|
|
64
|
+
const store = useContext(ScrollOffsetContext);
|
|
65
|
+
if (store === null) {
|
|
66
|
+
throw new Error(
|
|
67
|
+
'useScrollRestoration must be used within a <ScrollRestorationProvider>.',
|
|
68
|
+
);
|
|
69
|
+
}
|
|
70
|
+
return store;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Preserve and restore the scroll offset of `target` across navigation, keyed
|
|
75
|
+
* by the active route (plus an optional `options.key` for routes that host
|
|
76
|
+
* multiple scrollables).
|
|
77
|
+
*
|
|
78
|
+
* Behaviour (web):
|
|
79
|
+
* - On every scroll while the screen is focused, the current offset is saved.
|
|
80
|
+
* - On focus, the saved offset is applied in a single `requestAnimationFrame`,
|
|
81
|
+
* giving a remounted list one frame to lay out its content first (no retry
|
|
82
|
+
* loops, no hide/show tricks).
|
|
83
|
+
* - On blur, the latest offset is captured as a final safety net.
|
|
84
|
+
*/
|
|
85
|
+
export function useScrollRestoration(
|
|
86
|
+
target: ScrollRestorationTarget,
|
|
87
|
+
options?: UseScrollRestorationOptions,
|
|
88
|
+
): void {
|
|
89
|
+
const store = useScrollOffsetStore();
|
|
90
|
+
const route = useRoute();
|
|
91
|
+
const subKey = options?.key;
|
|
92
|
+
const enabled = options?.enabled ?? true;
|
|
93
|
+
|
|
94
|
+
const scrollKey = deriveScrollKey(route.key, subKey);
|
|
95
|
+
|
|
96
|
+
// Keep the latest target/enabled/key in refs so the focus effect can read
|
|
97
|
+
// them without being re-subscribed on every render.
|
|
98
|
+
const targetRef = useRef(target);
|
|
99
|
+
targetRef.current = target;
|
|
100
|
+
const enabledRef = useRef(enabled);
|
|
101
|
+
enabledRef.current = enabled;
|
|
102
|
+
const scrollKeyRef = useRef(scrollKey);
|
|
103
|
+
scrollKeyRef.current = scrollKey;
|
|
104
|
+
|
|
105
|
+
useFocusEffect(
|
|
106
|
+
// The effect identity is intentionally stable across renders: it reads all
|
|
107
|
+
// varying inputs from refs. React Navigation re-runs it on each focus.
|
|
108
|
+
useCallback(
|
|
109
|
+
() => {
|
|
110
|
+
const key = scrollKeyRef.current;
|
|
111
|
+
if (!enabledRef.current || key === null) return undefined;
|
|
112
|
+
|
|
113
|
+
const scroller = createScroller(targetRef.current);
|
|
114
|
+
const element =
|
|
115
|
+
targetRef.current === 'window'
|
|
116
|
+
? (typeof window !== 'undefined' ? window : null)
|
|
117
|
+
: resolveScrollEventTarget(targetRef.current);
|
|
118
|
+
|
|
119
|
+
const save = () => {
|
|
120
|
+
const currentKey = scrollKeyRef.current;
|
|
121
|
+
if (enabledRef.current && currentKey !== null) {
|
|
122
|
+
store.save(currentKey, scroller.getOffset());
|
|
123
|
+
}
|
|
124
|
+
};
|
|
125
|
+
|
|
126
|
+
// Restore on the next frame so a freshly remounted list has rendered
|
|
127
|
+
// its content (and thus reached its full scroll height) before we move.
|
|
128
|
+
const frame = requestAnimationFrame(() => {
|
|
129
|
+
scroller.setOffset(store.read(key));
|
|
130
|
+
});
|
|
131
|
+
|
|
132
|
+
element?.addEventListener('scroll', save, { passive: true });
|
|
133
|
+
|
|
134
|
+
return () => {
|
|
135
|
+
cancelAnimationFrame(frame);
|
|
136
|
+
element?.removeEventListener('scroll', save);
|
|
137
|
+
// Final capture on blur, covering navigations that don't fire a
|
|
138
|
+
// trailing scroll event.
|
|
139
|
+
save();
|
|
140
|
+
};
|
|
141
|
+
},
|
|
142
|
+
[store],
|
|
143
|
+
),
|
|
144
|
+
);
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Resolve the EventTarget to listen for `scroll` on. RNW scroll components
|
|
149
|
+
* expose `getScrollableNode()`; raw refs may hold the DOM node directly.
|
|
150
|
+
*/
|
|
151
|
+
function resolveScrollEventTarget(
|
|
152
|
+
target: Exclude<ScrollRestorationTarget, 'window'>,
|
|
153
|
+
): EventTarget | null {
|
|
154
|
+
const current = (target as { current: unknown }).current;
|
|
155
|
+
if (current == null) return null;
|
|
156
|
+
if (typeof EventTarget !== 'undefined' && current instanceof EventTarget) {
|
|
157
|
+
return current;
|
|
158
|
+
}
|
|
159
|
+
const handle = current as { getScrollableNode?: () => unknown };
|
|
160
|
+
if (typeof handle.getScrollableNode === 'function') {
|
|
161
|
+
const node = handle.getScrollableNode();
|
|
162
|
+
if (typeof EventTarget !== 'undefined' && node instanceof EventTarget) {
|
|
163
|
+
return node;
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
return null;
|
|
167
|
+
}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import type { ScrollableHandle, ScrollRestorationTarget } from './types';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* A normalized read/write interface over whatever the caller registered, so
|
|
5
|
+
* the hook does not branch on target shape. Both methods are no-ops when the
|
|
6
|
+
* underlying element is not yet (or no longer) attached.
|
|
7
|
+
*/
|
|
8
|
+
export interface ResolvedScroller {
|
|
9
|
+
getOffset: () => number;
|
|
10
|
+
setOffset: (offset: number) => void;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
function isElement(value: unknown): value is HTMLElement {
|
|
14
|
+
return typeof HTMLElement !== 'undefined' && value instanceof HTMLElement;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
function hasGetScrollableNode(
|
|
18
|
+
value: unknown,
|
|
19
|
+
): value is Required<Pick<ScrollableHandle, 'getScrollableNode'>> {
|
|
20
|
+
return (
|
|
21
|
+
typeof value === 'object' &&
|
|
22
|
+
value !== null &&
|
|
23
|
+
typeof (value as ScrollableHandle).getScrollableNode === 'function'
|
|
24
|
+
);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Resolve the live DOM element a target currently points at, or `null`.
|
|
29
|
+
*
|
|
30
|
+
* RNW scroll components expose `getScrollableNode()`; plain refs may hold the
|
|
31
|
+
* DOM node directly. We never cache the node because RNW can swap it across
|
|
32
|
+
* renders — we re-resolve on every read/write.
|
|
33
|
+
*/
|
|
34
|
+
function resolveElement(target: ScrollRestorationTarget): HTMLElement | null {
|
|
35
|
+
if (target === 'window') return null;
|
|
36
|
+
|
|
37
|
+
const current = (target as { current: unknown }).current;
|
|
38
|
+
if (current == null) return null;
|
|
39
|
+
|
|
40
|
+
if (isElement(current)) return current;
|
|
41
|
+
|
|
42
|
+
if (hasGetScrollableNode(current)) {
|
|
43
|
+
const node = current.getScrollableNode();
|
|
44
|
+
if (isElement(node)) return node;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
return null;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Build a {@link ResolvedScroller} for a target. The window sentinel reads and
|
|
52
|
+
* writes the document scroller; everything else operates on the resolved
|
|
53
|
+
* element's `scrollTop`.
|
|
54
|
+
*/
|
|
55
|
+
export function createScroller(target: ScrollRestorationTarget): ResolvedScroller {
|
|
56
|
+
if (target === 'window') {
|
|
57
|
+
return {
|
|
58
|
+
getOffset: () => (typeof window === 'undefined' ? 0 : window.scrollY),
|
|
59
|
+
setOffset: (offset) => {
|
|
60
|
+
if (typeof window !== 'undefined') window.scrollTo(0, offset);
|
|
61
|
+
},
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
return {
|
|
66
|
+
getOffset: () => {
|
|
67
|
+
const element = resolveElement(target);
|
|
68
|
+
return element ? element.scrollTop : 0;
|
|
69
|
+
},
|
|
70
|
+
setOffset: (offset) => {
|
|
71
|
+
const element = resolveElement(target);
|
|
72
|
+
if (element) element.scrollTop = offset;
|
|
73
|
+
},
|
|
74
|
+
};
|
|
75
|
+
}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure, platform-agnostic core of the scroll-restoration primitive.
|
|
3
|
+
*
|
|
4
|
+
* This file deliberately contains NO React and NO DOM/native imports so the
|
|
5
|
+
* logic can be unit-tested in isolation and shared verbatim by the web and
|
|
6
|
+
* native barrels. The web barrel drives it with real scroll offsets; the
|
|
7
|
+
* native barrel never instantiates it (native-stack already restores scroll).
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Separator between the navigation route key and an optional caller-supplied
|
|
12
|
+
* sub-key. A route may host more than one independently-scrolling list (e.g.
|
|
13
|
+
* a tabbed profile screen), so each list contributes its own sub-key.
|
|
14
|
+
*
|
|
15
|
+
* `\0` (NUL) can never appear in a React Navigation route key or in a
|
|
16
|
+
* developer-authored sub-key, so it is collision-free as a delimiter. It is
|
|
17
|
+
* written as an escape sequence (not a literal byte) so the source stays
|
|
18
|
+
* text-diffable.
|
|
19
|
+
*/
|
|
20
|
+
const COMPOSITE_KEY_SEPARATOR = '\0';
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Derive the storage key for a scrollable from its owning route key and an
|
|
24
|
+
* optional caller sub-key.
|
|
25
|
+
*
|
|
26
|
+
* - `routeKey` is React Navigation's stable per-route `route.key`.
|
|
27
|
+
* - `subKey` distinguishes multiple scrollables that share a single route.
|
|
28
|
+
*
|
|
29
|
+
* Returns `null` when there is no route key to anchor against (the scrollable
|
|
30
|
+
* is not inside a navigator), which the caller treats as "do not persist".
|
|
31
|
+
*/
|
|
32
|
+
export function deriveScrollKey(
|
|
33
|
+
routeKey: string | undefined,
|
|
34
|
+
subKey?: string,
|
|
35
|
+
): string | null {
|
|
36
|
+
if (!routeKey) return null;
|
|
37
|
+
if (subKey === undefined || subKey === '') return routeKey;
|
|
38
|
+
return `${routeKey}${COMPOSITE_KEY_SEPARATOR}${subKey}`;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* In-memory map of `scrollKey -> last-known scroll offset`.
|
|
43
|
+
*
|
|
44
|
+
* Mirrors the semantics of Bluesky's `Map<screenKey, scrollY>`: offsets live
|
|
45
|
+
* only for the lifetime of the document/session. We never persist them — a
|
|
46
|
+
* full reload should start at the top — and we never auto-evict, because a
|
|
47
|
+
* route can be revisited via browser Forward/Back long after it blurred.
|
|
48
|
+
*/
|
|
49
|
+
export class ScrollOffsetStore {
|
|
50
|
+
private readonly offsets = new Map<string, number>();
|
|
51
|
+
|
|
52
|
+
/** Persist the offset for a key. A negative offset is clamped to 0. */
|
|
53
|
+
save(key: string, offset: number): void {
|
|
54
|
+
this.offsets.set(key, offset > 0 ? offset : 0);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Read the saved offset for a key. Returns `0` when nothing was saved, so
|
|
59
|
+
* callers can restore unconditionally (an unseen list restores to the top).
|
|
60
|
+
*/
|
|
61
|
+
read(key: string): number {
|
|
62
|
+
return this.offsets.get(key) ?? 0;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** Whether an offset was ever saved for this key. */
|
|
66
|
+
has(key: string): boolean {
|
|
67
|
+
return this.offsets.has(key);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** Drop a saved offset (e.g. when a route is permanently removed). */
|
|
71
|
+
forget(key: string): void {
|
|
72
|
+
this.offsets.delete(key);
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Clear every saved offset. Primarily for tests and full resets. */
|
|
76
|
+
clear(): void {
|
|
77
|
+
this.offsets.clear();
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Number of distinct keys currently tracked. */
|
|
81
|
+
get size(): number {
|
|
82
|
+
return this.offsets.size;
|
|
83
|
+
}
|
|
84
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import type { ReactNode, RefObject } from 'react';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Anything `useScrollRestoration` knows how to read/write a vertical scroll
|
|
5
|
+
* offset from. The hook accepts a ref to one of these:
|
|
6
|
+
*
|
|
7
|
+
* - a React Native `ScrollView` / `FlatList` ref (which on web is backed by a
|
|
8
|
+
* DOM node and exposes `getScrollableNode()`),
|
|
9
|
+
* - a raw DOM element ref (when a component renders its own scroll container),
|
|
10
|
+
* - the literal `'window'` sentinel, for the rare layout where the list IS the
|
|
11
|
+
* window scroller (matches Bluesky's default).
|
|
12
|
+
*
|
|
13
|
+
* Native never reads any of these — the native hook is a no-op — so the type is
|
|
14
|
+
* intentionally permissive rather than coupled to a specific RN class.
|
|
15
|
+
*/
|
|
16
|
+
export interface ScrollableHandle {
|
|
17
|
+
/** Imperative scroll API exposed by RN scrollables. */
|
|
18
|
+
scrollTo?: (options: { x?: number; y?: number; animated?: boolean }) => void;
|
|
19
|
+
/** Web/RNW path: returns the underlying DOM node. */
|
|
20
|
+
getScrollableNode?: () => unknown;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* The accepted ref shapes. `'window'` is a sentinel for the document scroller.
|
|
25
|
+
*/
|
|
26
|
+
export type ScrollRestorationTarget =
|
|
27
|
+
| RefObject<ScrollableHandle | null>
|
|
28
|
+
| RefObject<unknown>
|
|
29
|
+
| 'window';
|
|
30
|
+
|
|
31
|
+
export interface UseScrollRestorationOptions {
|
|
32
|
+
/**
|
|
33
|
+
* Sub-key to disambiguate multiple scrollables that live on the same route
|
|
34
|
+
* (e.g. the tabs of a profile screen). Combined with the active route key to
|
|
35
|
+
* form the storage key. Omit when a route has a single scrollable.
|
|
36
|
+
*/
|
|
37
|
+
key?: string;
|
|
38
|
+
/**
|
|
39
|
+
* When `false`, the hook is inert (saves and restores are skipped). Useful to
|
|
40
|
+
* gate restoration behind a feature flag without changing call sites.
|
|
41
|
+
* Defaults to `true`.
|
|
42
|
+
*/
|
|
43
|
+
enabled?: boolean;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export interface ScrollRestorationProviderProps {
|
|
47
|
+
children: ReactNode;
|
|
48
|
+
}
|