shelving 1.322.2 → 1.323.0
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/docs/guides/building-with-shelving.md +1 -1
- package/docs/llms-full.txt +62 -48
- package/docs/ui/BackButton.md +1 -1
- package/docs/ui/Card.md +1 -1
- package/docs/ui/Meta.md +2 -2
- package/docs/ui/Navigation.md +4 -4
- package/docs/ui/NavigationEntryState.md +2 -2
- package/docs/ui/NavigationPosition.md +2 -2
- package/docs/ui/NavigationProps.md +3 -3
- package/docs/ui/NavigationStore/back.md +1 -1
- package/docs/ui/NavigationStore/forward.md +1 -1
- package/docs/ui/NavigationStore/history.md +3 -2
- package/docs/ui/NavigationStore/replace.md +1 -1
- package/docs/ui/NavigationStore.md +26 -15
- package/docs/ui/RouteCache.md +7 -5
- package/docs/ui/RouteCacheProps.md +1 -1
- package/docs/ui/StackButton.md +5 -5
- package/docs/ui/mergeMeta.md +1 -1
- package/package.json +1 -1
- package/ui/block/Card.md +1 -1
- package/ui/block/Card.module.css +10 -5
- package/ui/router/BackButton.md +1 -1
- package/ui/router/Navigation.d.ts +4 -3
- package/ui/router/Navigation.js +1 -1
- package/ui/router/Navigation.md +2 -2
- package/ui/router/Navigation.test.tsx +11 -1
- package/ui/router/Navigation.tsx +6 -5
- package/ui/router/NavigationStore.d.ts +32 -24
- package/ui/router/NavigationStore.js +42 -27
- package/ui/router/NavigationStore.md +18 -10
- package/ui/router/NavigationStore.test.ts +90 -23
- package/ui/router/NavigationStore.tsx +58 -41
- package/ui/router/RouteCache.d.ts +5 -3
- package/ui/router/RouteCache.js +20 -7
- package/ui/router/RouteCache.md +3 -2
- package/ui/router/RouteCache.tsx +30 -9
- package/ui/router/StackButton.d.ts +2 -2
- package/ui/router/StackButton.js +3 -3
- package/ui/router/StackButton.md +3 -3
- package/ui/router/StackButton.tsx +3 -3
- package/ui/util/meta.d.ts +2 -2
- package/ui/util/meta.ts +2 -2
|
@@ -11,8 +11,8 @@ import type { TransitionType } from "../transition/util.js";
|
|
|
11
11
|
* @see https://shelving.cc/ui/NavigationEntryState
|
|
12
12
|
*/
|
|
13
13
|
export interface NavigationEntryState {
|
|
14
|
-
/** Root path of the stack this page is in. */
|
|
15
|
-
readonly stack: AbsolutePath;
|
|
14
|
+
/** Root path of the stack this page is in, or `null` for a floating page. */
|
|
15
|
+
readonly stack: AbsolutePath | null;
|
|
16
16
|
/** Position of this page in its stack, where `0` is the root. */
|
|
17
17
|
readonly depth: number;
|
|
18
18
|
}
|
|
@@ -24,8 +24,8 @@ export interface NavigationEntryState {
|
|
|
24
24
|
* @see https://shelving.cc/ui/NavigationPosition
|
|
25
25
|
*/
|
|
26
26
|
export interface NavigationPosition extends NavigationEntryState {
|
|
27
|
-
/** Depth of the top page of each stack that has pages. */
|
|
28
|
-
readonly tops:
|
|
27
|
+
/** Depth of the top page of each stack that has pages, including the floating stack (`null`). */
|
|
28
|
+
readonly tops: ReadonlyMap<AbsolutePath | null, number>;
|
|
29
29
|
/** The page before the current one in its stack, or `undefined` at the bottom of the stack. */
|
|
30
30
|
readonly parent: AbsolutePath | undefined;
|
|
31
31
|
}
|
|
@@ -49,22 +49,23 @@ type _Navigation = Pick<
|
|
|
49
49
|
*
|
|
50
50
|
* - Extends `URLStore`, so its `value` is the current URL.
|
|
51
51
|
* - With the browser Navigation API, each history entry saves a `NavigationEntryState`, and each stack is read from `navigation.entries()` when it is needed. Nothing else is kept.
|
|
52
|
-
* - `stack` is a sub-store that holds the root of the current stack. It only changes when the stack changes.
|
|
52
|
+
* - `stack` is a sub-store that holds the root of the current stack, or `null` for a floating page. It only changes when the stack changes.
|
|
53
|
+
* - A page outside the listed stacks is floating: its stack is `null`. The floating stack has no root page and no tab.
|
|
54
|
+
* - In a listed stack, depth `0` is always the stack's root path.
|
|
53
55
|
* - Without the Navigation API (older browsers and server renders) there are no stacks: `stack` stays the starting stack, `history()` is empty, and `stack` arguments are ignored.
|
|
54
56
|
* - Owned by `<Navigation>`. Read it with `requireNavigation()`.
|
|
55
57
|
*
|
|
56
58
|
* @see https://shelving.cc/ui/NavigationStore
|
|
57
59
|
*/
|
|
58
60
|
export class NavigationStore extends URLStore {
|
|
59
|
-
/** Root path of each stack, in tab order.
|
|
61
|
+
/** Root path of each stack, in tab order. With none, every page floats. */
|
|
60
62
|
readonly stacks: readonly AbsolutePath[];
|
|
61
63
|
|
|
62
64
|
/**
|
|
63
|
-
* Root path of the current stack.
|
|
64
|
-
* -
|
|
65
|
-
* - It starts at the `stack` given to the constructor (default `"/"`). Without the Navigation API, it stays there.
|
|
65
|
+
* Root path of the current stack, or `null` for a floating page.
|
|
66
|
+
* - It starts at the `stack` given to the constructor (default `null`). Without the Navigation API, it stays there.
|
|
66
67
|
*/
|
|
67
|
-
readonly stack: Store<AbsolutePath>;
|
|
68
|
+
readonly stack: Store<AbsolutePath | null>;
|
|
68
69
|
|
|
69
70
|
/**
|
|
70
71
|
* Transition type of the most recent change, read by `<Navigation>` when the value changes.
|
|
@@ -80,19 +81,28 @@ export class NavigationStore extends URLStore {
|
|
|
80
81
|
private _busy = false;
|
|
81
82
|
|
|
82
83
|
/** Stack of the page the app opens at, when its history entry has no saved stack. */
|
|
83
|
-
private readonly _start: AbsolutePath;
|
|
84
|
+
private readonly _start: AbsolutePath | null;
|
|
84
85
|
|
|
85
86
|
constructor(
|
|
86
87
|
url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href,
|
|
87
88
|
base?: PossibleURL,
|
|
88
|
-
stack: AbsolutePath =
|
|
89
|
+
stack: AbsolutePath | null = null,
|
|
89
90
|
...stacks: AbsolutePath[]
|
|
90
91
|
) {
|
|
91
92
|
super(url, base);
|
|
92
|
-
this.stacks = stacks
|
|
93
|
-
this._start = stack;
|
|
93
|
+
this.stacks = stacks;
|
|
94
|
+
this._start = stack !== null && stacks.includes(stack) ? stack : null;
|
|
94
95
|
this._navigation = _getNavigation();
|
|
95
|
-
this.stack = new Store<AbsolutePath>(this._navigation ? this._getState(this._navigation.currentEntry).stack :
|
|
96
|
+
this.stack = new Store<AbsolutePath | null>(this._navigation ? this._getState(this._navigation.currentEntry).stack : this._start);
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* Path of the current URL relative to the app root (without its `?query`), or `undefined` if the URL is outside the app.
|
|
101
|
+
*
|
|
102
|
+
* @see https://shelving.cc/ui/NavigationStore/path
|
|
103
|
+
*/
|
|
104
|
+
get path(): AbsolutePath | undefined {
|
|
105
|
+
return this._getPath(this.value);
|
|
96
106
|
}
|
|
97
107
|
|
|
98
108
|
/**
|
|
@@ -104,10 +114,10 @@ export class NavigationStore extends URLStore {
|
|
|
104
114
|
get position(): NavigationPosition | undefined {
|
|
105
115
|
if (!this._navigation) return undefined;
|
|
106
116
|
const { stack, depth } = this._getState(this._navigation.currentEntry);
|
|
107
|
-
const tops
|
|
117
|
+
const tops = new Map<AbsolutePath | null, number>();
|
|
108
118
|
for (const s of this._getStacks()) {
|
|
109
119
|
const top = this._getPages(s).at(-1);
|
|
110
|
-
if (top) tops
|
|
120
|
+
if (top) tops.set(s, top.depth);
|
|
111
121
|
}
|
|
112
122
|
return { stack, depth, tops, parent: this.history(stack).at(-2) };
|
|
113
123
|
}
|
|
@@ -161,18 +171,19 @@ export class NavigationStore extends URLStore {
|
|
|
161
171
|
/**
|
|
162
172
|
* Get the pages in a stack, root first, or every page in every stack.
|
|
163
173
|
* - Read from the browser history entries up to the current one.
|
|
164
|
-
* - A stack whose root entry is
|
|
174
|
+
* - A listed stack whose root entry is not in the history (a deep link, or the browser keeps a limited history) still starts with its root.
|
|
175
|
+
* - The floating stack (`null`) has no root, so it starts with its oldest page.
|
|
165
176
|
* - Without the Navigation API this is always empty.
|
|
166
177
|
*
|
|
167
|
-
* @param stack Root path of the stack. Defaults to the current stack.
|
|
178
|
+
* @param stack Root path of the stack, or `null` for the floating stack. Defaults to the current stack.
|
|
168
179
|
* @returns Paths relative to the app root, each with its `?query`.
|
|
169
180
|
* @example nav.history("/home") // ["/home", "/home/post/2"]
|
|
170
181
|
* @see https://shelving.cc/ui/NavigationStore/history
|
|
171
182
|
*/
|
|
172
|
-
history(stack: AbsolutePath = this.stack.value): AbsolutePath[] {
|
|
183
|
+
history(stack: AbsolutePath | null = this.stack.value): AbsolutePath[] {
|
|
173
184
|
const pages = this._getPages(stack);
|
|
174
185
|
const paths = pages.map(p => _getPathWithQuery(p));
|
|
175
|
-
if (pages[0] && pages[0].depth > 0) paths.unshift(stack);
|
|
186
|
+
if (stack !== null && pages[0] && pages[0].depth > 0) paths.unshift(stack);
|
|
176
187
|
return paths;
|
|
177
188
|
}
|
|
178
189
|
|
|
@@ -184,12 +195,12 @@ export class NavigationStore extends URLStore {
|
|
|
184
195
|
* - A change of stack slides by tab order. Else it slides forward.
|
|
185
196
|
*
|
|
186
197
|
* @param possible The destination URL, resolved against `base`.
|
|
187
|
-
* @param stack Root path of the stack to go to. Defaults to the current stack.
|
|
198
|
+
* @param stack Root path of the stack to go to, or `null` for the floating stack. Defaults to the current stack.
|
|
188
199
|
* @throws RequiredError If `possible` cannot be resolved to a valid URL.
|
|
189
200
|
* @example nav.forward("/settings");
|
|
190
201
|
* @see https://shelving.cc/ui/NavigationStore/forward
|
|
191
202
|
*/
|
|
192
|
-
forward(possible: PossibleURL, stack: AbsolutePath = this.stack.value): void {
|
|
203
|
+
forward(possible: PossibleURL, stack: AbsolutePath | null = this.stack.value): void {
|
|
193
204
|
const url = requireURL(possible, this.base, this.forward);
|
|
194
205
|
if (!this._navigation) {
|
|
195
206
|
this._push(url, "forward");
|
|
@@ -201,7 +212,7 @@ export class NavigationStore extends URLStore {
|
|
|
201
212
|
return;
|
|
202
213
|
}
|
|
203
214
|
const top = this._getPages(stack).at(-1);
|
|
204
|
-
const depth = top ? (top.url.href === url.href ? top.depth : top.depth + 1) :
|
|
215
|
+
const depth = top ? (top.url.href === url.href ? top.depth : top.depth + 1) : this._getBottomDepth(url, stack);
|
|
205
216
|
this._push(url, this._getOrder(current, stack) ?? "forward", { stack, depth });
|
|
206
217
|
}
|
|
207
218
|
|
|
@@ -213,12 +224,12 @@ export class NavigationStore extends URLStore {
|
|
|
213
224
|
* - It works when the app was opened at the current page, so a back button always has somewhere to go.
|
|
214
225
|
*
|
|
215
226
|
* @param possible The destination URL, resolved against `base`.
|
|
216
|
-
* @param stack Root path of the stack to go back in. Defaults to the current stack.
|
|
227
|
+
* @param stack Root path of the stack to go back in, or `null` for the floating stack. Defaults to the current stack.
|
|
217
228
|
* @throws RequiredError If `possible` cannot be resolved to a valid URL.
|
|
218
229
|
* @example nav.back("/profile");
|
|
219
230
|
* @see https://shelving.cc/ui/NavigationStore/back
|
|
220
231
|
*/
|
|
221
|
-
back(possible: PossibleURL, stack: AbsolutePath = this.stack.value): void {
|
|
232
|
+
back(possible: PossibleURL, stack: AbsolutePath | null = this.stack.value): void {
|
|
222
233
|
const url = requireURL(possible, this.base, this.back);
|
|
223
234
|
const navigation = this._navigation;
|
|
224
235
|
if (!navigation) {
|
|
@@ -233,7 +244,7 @@ export class NavigationStore extends URLStore {
|
|
|
233
244
|
return;
|
|
234
245
|
}
|
|
235
246
|
// The URL is an earlier page in the stack, else the root of the stack, else it takes the place of the top page.
|
|
236
|
-
const depth = page ? page.depth : this._getPath(url) === stack ? 0 : (pages.at(-1)?.depth ??
|
|
247
|
+
const depth = page ? page.depth : this._getPath(url) === stack ? 0 : (pages.at(-1)?.depth ?? this._getBottomDepth(url, stack));
|
|
237
248
|
this._push(url, this._getOrder(current, stack) ?? "back", { stack, depth });
|
|
238
249
|
}
|
|
239
250
|
|
|
@@ -244,12 +255,12 @@ export class NavigationStore extends URLStore {
|
|
|
244
255
|
* - Pass a `stack` to move the page into that stack: at its root if the URL is the root, else on top of its pages. For example, a login page calls `replace("/home", "/home")`.
|
|
245
256
|
*
|
|
246
257
|
* @param possible The destination URL, resolved against `base`.
|
|
247
|
-
* @param stack Root path of the stack to move the page into. Defaults to the current stack.
|
|
258
|
+
* @param stack Root path of the stack to move the page into, or `null` for the floating stack. Defaults to the current stack.
|
|
248
259
|
* @throws RequiredError If `possible` cannot be resolved to a valid URL.
|
|
249
260
|
* @example nav.replace("/login");
|
|
250
261
|
* @see https://shelving.cc/ui/NavigationStore/replace
|
|
251
262
|
*/
|
|
252
|
-
replace(possible: PossibleURL, stack: AbsolutePath = this.stack.value): void {
|
|
263
|
+
replace(possible: PossibleURL, stack: AbsolutePath | null = this.stack.value): void {
|
|
253
264
|
const url = requireURL(possible, this.base, this.replace);
|
|
254
265
|
const saved = this._navigation?.currentEntry?.getState();
|
|
255
266
|
let state = _isEntryState(saved) ? saved : undefined;
|
|
@@ -257,7 +268,7 @@ export class NavigationStore extends URLStore {
|
|
|
257
268
|
const top = this._getPages(stack)
|
|
258
269
|
.filter(p => p.index !== this._navigation?.currentEntry?.index)
|
|
259
270
|
.at(-1);
|
|
260
|
-
state = { stack, depth: this._getPath(url) === stack ? 0 : top ? top.depth + 1 :
|
|
271
|
+
state = { stack, depth: this._getPath(url) === stack ? 0 : top ? top.depth + 1 : this._getBottomDepth(url, stack) };
|
|
261
272
|
}
|
|
262
273
|
this._write(() => window.history.replaceState(null, "", url.href), state);
|
|
263
274
|
this._change(url, null, state?.stack);
|
|
@@ -292,14 +303,14 @@ export class NavigationStore extends URLStore {
|
|
|
292
303
|
}
|
|
293
304
|
|
|
294
305
|
/** Set the stack first, then the URL, so both are ready when `<Navigation>` reads them. */
|
|
295
|
-
private _change(url: PossibleURL, transition: TransitionType | null, stack?: AbsolutePath): void {
|
|
306
|
+
private _change(url: PossibleURL, transition: TransitionType | null, stack?: AbsolutePath | null): void {
|
|
296
307
|
this.transition = transition;
|
|
297
|
-
if (stack) this.stack.value = stack;
|
|
308
|
+
if (stack !== undefined) this.stack.value = stack;
|
|
298
309
|
this.value = url;
|
|
299
310
|
}
|
|
300
311
|
|
|
301
312
|
/** Get the pages in a stack, root first: the newest entry in the stack, then the newest earlier entry at a lower depth, down to depth 0. */
|
|
302
|
-
private _getPages(stack: AbsolutePath): _Page[] {
|
|
313
|
+
private _getPages(stack: AbsolutePath | null): _Page[] {
|
|
303
314
|
const navigation = this._navigation;
|
|
304
315
|
if (!navigation) return [];
|
|
305
316
|
const entries = navigation.entries();
|
|
@@ -320,16 +331,22 @@ export class NavigationStore extends URLStore {
|
|
|
320
331
|
return pages;
|
|
321
332
|
}
|
|
322
333
|
|
|
323
|
-
/** Get the saved state of an entry, or for an entry with none (the page the app opened at), the starting stack at depth
|
|
334
|
+
/** Get the saved state of an entry, or for an entry with none (for example the page the app opened at), the starting stack at its bottom depth. */
|
|
324
335
|
private _getState(entry: NavigationHistoryEntry | null): NavigationEntryState {
|
|
325
336
|
const state = entry?.getState();
|
|
326
337
|
if (_isEntryState(state) && this._getStacks().includes(state.stack)) return state;
|
|
327
|
-
|
|
338
|
+
const url = entry?.url ? requireURL(entry.url, undefined, this._getState) : undefined;
|
|
339
|
+
return { stack: this._start, depth: url ? this._getBottomDepth(url, this._start) : 0 };
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
/** Get the depth of a URL that is the first page of a stack: `0` for the stack's root path or for the floating stack, else `1` so the root stays below it. */
|
|
343
|
+
private _getBottomDepth(url: ImmutableURL, stack: AbsolutePath | null): number {
|
|
344
|
+
return stack === null || this._getPath(url) === stack ? 0 : 1;
|
|
328
345
|
}
|
|
329
346
|
|
|
330
|
-
/** Get every stack a page can be in: the listed stacks, plus the
|
|
331
|
-
private _getStacks(): AbsolutePath[] {
|
|
332
|
-
return
|
|
347
|
+
/** Get every stack a page can be in: the listed stacks, plus the floating stack (`null`). */
|
|
348
|
+
private _getStacks(): (AbsolutePath | null)[] {
|
|
349
|
+
return [...this.stacks, null];
|
|
333
350
|
}
|
|
334
351
|
|
|
335
352
|
/** Get the path of a URL relative to the app root, or `undefined` if it is outside the app. */
|
|
@@ -349,8 +366,8 @@ export class NavigationStore extends URLStore {
|
|
|
349
366
|
}
|
|
350
367
|
|
|
351
368
|
/** Slide direction between two stacks by tab order, or `undefined` for the same stack. */
|
|
352
|
-
private _getOrder(from: AbsolutePath, to: AbsolutePath): TransitionType | undefined {
|
|
353
|
-
if (from === to) return;
|
|
369
|
+
private _getOrder(from: AbsolutePath | null, to: AbsolutePath | null): TransitionType | undefined {
|
|
370
|
+
if (from === to || from === null || to === null) return;
|
|
354
371
|
const a = this.stacks.indexOf(from);
|
|
355
372
|
const b = this.stacks.indexOf(to);
|
|
356
373
|
if (a < 0 || b < 0) return;
|
|
@@ -376,7 +393,7 @@ function _isEntryState(state: unknown): state is NavigationEntryState {
|
|
|
376
393
|
typeof state === "object" &&
|
|
377
394
|
state !== null &&
|
|
378
395
|
"stack" in state &&
|
|
379
|
-
typeof state.stack === "string" &&
|
|
396
|
+
(typeof state.stack === "string" || state.stack === null) &&
|
|
380
397
|
"depth" in state &&
|
|
381
398
|
typeof state.depth === "number"
|
|
382
399
|
);
|
|
@@ -7,7 +7,8 @@ import { type ReactNode } from "react";
|
|
|
7
7
|
export interface RouteCacheProps {
|
|
8
8
|
/**
|
|
9
9
|
* Number of pages to keep mounted (but hidden), so the whole state of each one (scroll position, toggles, searches, form input, focus) is still there when you come back to it.
|
|
10
|
-
* - The top page of each stack
|
|
10
|
+
* - The root page and the top page of each listed stack are never dropped, even past the limit, so a tab always shows the page you left and always has its root below.
|
|
11
|
+
* - Floating pages get no such protection.
|
|
11
12
|
* - Set to `0` (or less) to turn the cache off and unmount each page as you leave it.
|
|
12
13
|
*
|
|
13
14
|
* @default 10
|
|
@@ -23,8 +24,9 @@ export interface RouteCacheProps {
|
|
|
23
24
|
* - Keeps each page in the stacks mounted but hidden (with React's `<Activity>`), so going back to a page, or switching back to a tab, shows it exactly as you left it.
|
|
24
25
|
* - Each page is keyed by its stack and its depth in that stack, not by its URL. So `NavigationStore.replace()` (a canonical URL, an in-page tab) keeps the same page mounted, and the same URL open in two tabs is two separate pages.
|
|
25
26
|
* - A page leaves the cache as soon as it leaves its stack: when you go back from it, or when a stack is popped to its root. After a browser back, a browser forward shows that page fresh.
|
|
26
|
-
* - The top page of each stack
|
|
27
|
-
* -
|
|
27
|
+
* - The root page and the top page of each listed stack are never dropped. Other pages, and every floating page, can be dropped past `maxCached`, and show fresh (from the top) when you come back to them.
|
|
28
|
+
* - When the current page is deeper than its stack's root and the root page is not cached (for example after a deep link), the root page is rendered hidden, so a swipe-back can show it.
|
|
29
|
+
* - Each kept page is frozen under its own `<MetaContext>` and `NavigationPositionContext`, so the same `children` element renders a different page for each URL, and a hidden page never re-renders for another page's URL.
|
|
28
30
|
* - `<Activity mode="hidden">` keeps a hidden page's state but unmounts its effects, so its subscriptions and timers pause and resume as it is hidden and shown.
|
|
29
31
|
* - Without the browser Navigation API (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
|
|
30
32
|
*
|
package/ui/router/RouteCache.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
2
|
import { Activity, use, useRef } from "react";
|
|
3
3
|
import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
|
|
4
|
+
import { mergeMeta } from "../util/meta.js";
|
|
4
5
|
import { NavigationPositionContext } from "./NavigationContext.js";
|
|
5
6
|
/**
|
|
6
7
|
* Keep-alive page cache for the pages in the navigation stacks. Put it in a layout's content slot, around a `<Scroll vertical cover>` box.
|
|
@@ -9,8 +10,9 @@ import { NavigationPositionContext } from "./NavigationContext.js";
|
|
|
9
10
|
* - Keeps each page in the stacks mounted but hidden (with React's `<Activity>`), so going back to a page, or switching back to a tab, shows it exactly as you left it.
|
|
10
11
|
* - Each page is keyed by its stack and its depth in that stack, not by its URL. So `NavigationStore.replace()` (a canonical URL, an in-page tab) keeps the same page mounted, and the same URL open in two tabs is two separate pages.
|
|
11
12
|
* - A page leaves the cache as soon as it leaves its stack: when you go back from it, or when a stack is popped to its root. After a browser back, a browser forward shows that page fresh.
|
|
12
|
-
* - The top page of each stack
|
|
13
|
-
* -
|
|
13
|
+
* - The root page and the top page of each listed stack are never dropped. Other pages, and every floating page, can be dropped past `maxCached`, and show fresh (from the top) when you come back to them.
|
|
14
|
+
* - When the current page is deeper than its stack's root and the root page is not cached (for example after a deep link), the root page is rendered hidden, so a swipe-back can show it.
|
|
15
|
+
* - Each kept page is frozen under its own `<MetaContext>` and `NavigationPositionContext`, so the same `children` element renders a different page for each URL, and a hidden page never re-renders for another page's URL.
|
|
14
16
|
* - `<Activity mode="hidden">` keeps a hidden page's state but unmounts its effects, so its subscriptions and timers pause and resume as it is hidden and shown.
|
|
15
17
|
* - Without the browser Navigation API (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
|
|
16
18
|
*
|
|
@@ -36,16 +38,23 @@ export function RouteCache({ maxCached = 10, children }) {
|
|
|
36
38
|
const key = `${stack} ${depth}`;
|
|
37
39
|
const entry = map.get(key) ?? { node: null, used: 0, stack, depth };
|
|
38
40
|
map.set(key, entry);
|
|
39
|
-
// Snapshot the children under the live URL (frozen), so each kept page keeps rendering for the URL it last had.
|
|
40
|
-
entry.node =
|
|
41
|
+
// Snapshot the children under the live URL and position (frozen), so each kept page keeps rendering for the URL it last had.
|
|
42
|
+
entry.node = _getNode(children, meta, position);
|
|
41
43
|
entry.used = ++usedRef.current;
|
|
44
|
+
// A listed stack always has its root page below a deeper page, so render the root (hidden) if it is not cached.
|
|
45
|
+
const rootKey = `${stack} 0`;
|
|
46
|
+
if (stack !== null && depth > 0 && !map.has(rootKey)) {
|
|
47
|
+
const rootMeta = { ...mergeMeta(meta, { url: stack, stack }, RouteCache), path: stack, params: {} };
|
|
48
|
+
const rootPosition = { stack, depth: 0, tops, parent: undefined };
|
|
49
|
+
map.set(rootKey, { node: _getNode(children, rootMeta, rootPosition), used: 0, stack, depth: 0 });
|
|
50
|
+
}
|
|
42
51
|
// Drop the pages that have left their stack.
|
|
43
52
|
for (const [k, { stack: s, depth: d }] of map)
|
|
44
|
-
if (k !== key && !(d <= (tops
|
|
53
|
+
if (k !== key && !(d <= (tops.get(s) ?? -1)))
|
|
45
54
|
map.delete(k);
|
|
46
|
-
// Drop the least-recently-used pages past the limit, but never the current page or the top page of a stack.
|
|
55
|
+
// Drop the least-recently-used pages past the limit, but never the current page, or the root or top page of a listed stack.
|
|
47
56
|
while (map.size > maxCached) {
|
|
48
|
-
const lru = _findLeastRecentlyUsed(map, (k, { stack: s, depth: d }) => k !== key && tops
|
|
57
|
+
const lru = _findLeastRecentlyUsed(map, (k, { stack: s, depth: d }) => k !== key && (s === null || (d !== 0 && tops.get(s) !== d)));
|
|
49
58
|
if (lru === undefined)
|
|
50
59
|
break;
|
|
51
60
|
map.delete(lru);
|
|
@@ -53,6 +62,10 @@ export function RouteCache({ maxCached = 10, children }) {
|
|
|
53
62
|
// Render every cached page; only the current one is visible, the rest are kept alive but hidden.
|
|
54
63
|
return Array.from(map, ([k, cached]) => (_jsx(Activity, { mode: k === key ? "visible" : "hidden", children: cached.node }, k)));
|
|
55
64
|
}
|
|
65
|
+
/** Freeze `children` under a URL and a position. */
|
|
66
|
+
function _getNode(children, meta, position) {
|
|
67
|
+
return (_jsx(NavigationPositionContext, { value: position, children: _jsx(MetaContext, { value: meta, children: children }) }));
|
|
68
|
+
}
|
|
56
69
|
/** Find the key of the least-recently-used entry that may be dropped, or `undefined` if none may. */
|
|
57
70
|
function _findLeastRecentlyUsed(map, droppable) {
|
|
58
71
|
let lruKey;
|
package/ui/router/RouteCache.md
CHANGED
|
@@ -9,11 +9,12 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
|
|
|
9
9
|
- Each page is keyed by its stack and its depth in that stack, not by its URL. See `NavigationStore` for how stacks work.
|
|
10
10
|
- A page leaves the cache when it leaves its stack: when you go back from it, or when its stack goes back to the root. So a page you went back from mounts fresh the next time you open it.
|
|
11
11
|
- After a browser back, the browser forward button shows the next page fresh (from the top), because that page left its stack when you went back.
|
|
12
|
-
- The top page of each stack
|
|
12
|
+
- The root page and the top page of each listed stack are never dropped, so each tab always shows the page you left, and always has its root below. Other pages, and every floating page, are dropped (least recently used first) past `maxCached`, and mount fresh when you come back to them.
|
|
13
|
+
- When the current page is deeper than its stack's root and the root page is not cached (for example after a deep link), the cache renders the root page hidden, so a swipe-back can show it. A hidden page runs no effects until it is shown.
|
|
13
14
|
- `NavigationStore.replace()` and `className="replace"` links keep the same page mounted. A replace to another URL for the same component (for example from `/post/1` to `/post/2`) keeps its state. To reset the state, wrap the page content in an element with a `key`, for example `<Fragment key={id}>`.
|
|
14
15
|
- The same URL open in two stacks is two separate pages.
|
|
15
16
|
- A form that makes something stays in the cache with its input. Clear it after a successful submit, so it is empty the next time you see it (see the example below).
|
|
16
|
-
- Each kept page is frozen under its own `<Meta
|
|
17
|
+
- Each kept page is frozen under its own `<Meta>` and `NavigationPositionContext`, so a hidden page never re-renders for another page's URL.
|
|
17
18
|
- `<Activity mode="hidden">` keeps a hidden page's state but unmounts its effects, so subscriptions, observers (for example infinite scroll) and timers pause and resume as the page is hidden and shown.
|
|
18
19
|
- **Nesting:** layout, then transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. See the usage below.
|
|
19
20
|
- The scroll box goes **inside** the cache, so each kept page has its own scroll box and keeps its own scroll position. A scroll box outside the cache is shared by every page, so pages lose their scroll.
|
package/ui/router/RouteCache.tsx
CHANGED
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
import { Activity, type ReactNode, use, useRef } from "react";
|
|
2
2
|
import type { AbsolutePath } from "../../util/path.js";
|
|
3
3
|
import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
|
|
4
|
+
import { type Meta, mergeMeta } from "../util/meta.js";
|
|
4
5
|
import { NavigationPositionContext } from "./NavigationContext.js";
|
|
6
|
+
import type { NavigationPosition } from "./NavigationStore.js";
|
|
5
7
|
|
|
6
8
|
/** A cached page: the rendered node, where it is in its stack, and a `used` tick for least-recently-used eviction. */
|
|
7
9
|
interface _CacheEntry {
|
|
8
10
|
node: ReactNode;
|
|
9
11
|
used: number;
|
|
10
|
-
readonly stack: AbsolutePath;
|
|
12
|
+
readonly stack: AbsolutePath | null;
|
|
11
13
|
readonly depth: number;
|
|
12
14
|
}
|
|
13
15
|
|
|
@@ -19,7 +21,8 @@ interface _CacheEntry {
|
|
|
19
21
|
export interface RouteCacheProps {
|
|
20
22
|
/**
|
|
21
23
|
* Number of pages to keep mounted (but hidden), so the whole state of each one (scroll position, toggles, searches, form input, focus) is still there when you come back to it.
|
|
22
|
-
* - The top page of each stack
|
|
24
|
+
* - The root page and the top page of each listed stack are never dropped, even past the limit, so a tab always shows the page you left and always has its root below.
|
|
25
|
+
* - Floating pages get no such protection.
|
|
23
26
|
* - Set to `0` (or less) to turn the cache off and unmount each page as you leave it.
|
|
24
27
|
*
|
|
25
28
|
* @default 10
|
|
@@ -36,8 +39,9 @@ export interface RouteCacheProps {
|
|
|
36
39
|
* - Keeps each page in the stacks mounted but hidden (with React's `<Activity>`), so going back to a page, or switching back to a tab, shows it exactly as you left it.
|
|
37
40
|
* - Each page is keyed by its stack and its depth in that stack, not by its URL. So `NavigationStore.replace()` (a canonical URL, an in-page tab) keeps the same page mounted, and the same URL open in two tabs is two separate pages.
|
|
38
41
|
* - A page leaves the cache as soon as it leaves its stack: when you go back from it, or when a stack is popped to its root. After a browser back, a browser forward shows that page fresh.
|
|
39
|
-
* - The top page of each stack
|
|
40
|
-
* -
|
|
42
|
+
* - The root page and the top page of each listed stack are never dropped. Other pages, and every floating page, can be dropped past `maxCached`, and show fresh (from the top) when you come back to them.
|
|
43
|
+
* - When the current page is deeper than its stack's root and the root page is not cached (for example after a deep link), the root page is rendered hidden, so a swipe-back can show it.
|
|
44
|
+
* - Each kept page is frozen under its own `<MetaContext>` and `NavigationPositionContext`, so the same `children` element renders a different page for each URL, and a hidden page never re-renders for another page's URL.
|
|
41
45
|
* - `<Activity mode="hidden">` keeps a hidden page's state but unmounts its effects, so its subscriptions and timers pause and resume as it is hidden and shown.
|
|
42
46
|
* - Without the browser Navigation API (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
|
|
43
47
|
*
|
|
@@ -70,16 +74,24 @@ export function RouteCache({ maxCached = 10, children }: RouteCacheProps): React
|
|
|
70
74
|
const entry = map.get(key) ?? { node: null, used: 0, stack, depth };
|
|
71
75
|
map.set(key, entry);
|
|
72
76
|
|
|
73
|
-
// Snapshot the children under the live URL (frozen), so each kept page keeps rendering for the URL it last had.
|
|
74
|
-
entry.node =
|
|
77
|
+
// Snapshot the children under the live URL and position (frozen), so each kept page keeps rendering for the URL it last had.
|
|
78
|
+
entry.node = _getNode(children, meta, position);
|
|
75
79
|
entry.used = ++usedRef.current;
|
|
76
80
|
|
|
81
|
+
// A listed stack always has its root page below a deeper page, so render the root (hidden) if it is not cached.
|
|
82
|
+
const rootKey = `${stack} 0`;
|
|
83
|
+
if (stack !== null && depth > 0 && !map.has(rootKey)) {
|
|
84
|
+
const rootMeta = { ...mergeMeta(meta, { url: stack, stack }, RouteCache), path: stack, params: {} };
|
|
85
|
+
const rootPosition = { stack, depth: 0, tops, parent: undefined };
|
|
86
|
+
map.set(rootKey, { node: _getNode(children, rootMeta, rootPosition), used: 0, stack, depth: 0 });
|
|
87
|
+
}
|
|
88
|
+
|
|
77
89
|
// Drop the pages that have left their stack.
|
|
78
|
-
for (const [k, { stack: s, depth: d }] of map) if (k !== key && !(d <= (tops
|
|
90
|
+
for (const [k, { stack: s, depth: d }] of map) if (k !== key && !(d <= (tops.get(s) ?? -1))) map.delete(k);
|
|
79
91
|
|
|
80
|
-
// Drop the least-recently-used pages past the limit, but never the current page or the top page of a stack.
|
|
92
|
+
// Drop the least-recently-used pages past the limit, but never the current page, or the root or top page of a listed stack.
|
|
81
93
|
while (map.size > maxCached) {
|
|
82
|
-
const lru = _findLeastRecentlyUsed(map, (k, { stack: s, depth: d }) => k !== key && tops
|
|
94
|
+
const lru = _findLeastRecentlyUsed(map, (k, { stack: s, depth: d }) => k !== key && (s === null || (d !== 0 && tops.get(s) !== d)));
|
|
83
95
|
if (lru === undefined) break;
|
|
84
96
|
map.delete(lru);
|
|
85
97
|
}
|
|
@@ -92,6 +104,15 @@ export function RouteCache({ maxCached = 10, children }: RouteCacheProps): React
|
|
|
92
104
|
));
|
|
93
105
|
}
|
|
94
106
|
|
|
107
|
+
/** Freeze `children` under a URL and a position. */
|
|
108
|
+
function _getNode(children: ReactNode, meta: Meta, position: NavigationPosition): ReactNode {
|
|
109
|
+
return (
|
|
110
|
+
<NavigationPositionContext value={position}>
|
|
111
|
+
<MetaContext value={meta}>{children}</MetaContext>
|
|
112
|
+
</NavigationPositionContext>
|
|
113
|
+
);
|
|
114
|
+
}
|
|
115
|
+
|
|
95
116
|
/** Find the key of the least-recently-used entry that may be dropped, or `undefined` if none may. */
|
|
96
117
|
function _findLeastRecentlyUsed(
|
|
97
118
|
map: Map<string, _CacheEntry>,
|
|
@@ -13,8 +13,8 @@ export interface StackButtonProps extends Omit<ButtonProps, "href" | "onClick" |
|
|
|
13
13
|
/**
|
|
14
14
|
* Button for one stack in a tab bar.
|
|
15
15
|
* - Tap another stack's button: go to the page you left in that stack. The page slides left or right by tab order.
|
|
16
|
-
* - Tap the current stack's button: go back to its root.
|
|
17
|
-
* - Tap it again
|
|
16
|
+
* - Tap the current stack's button: go back to its root path.
|
|
17
|
+
* - Tap it again on the root path: scroll the page to the top.
|
|
18
18
|
* - It is selected while its stack is the current stack.
|
|
19
19
|
* - Without the browser Navigation API (and in a server render) it is a plain link to the stack's root.
|
|
20
20
|
*
|
package/ui/router/StackButton.js
CHANGED
|
@@ -6,8 +6,8 @@ import { NavigationPositionContext, requireNavigation } from "./NavigationContex
|
|
|
6
6
|
/**
|
|
7
7
|
* Button for one stack in a tab bar.
|
|
8
8
|
* - Tap another stack's button: go to the page you left in that stack. The page slides left or right by tab order.
|
|
9
|
-
* - Tap the current stack's button: go back to its root.
|
|
10
|
-
* - Tap it again
|
|
9
|
+
* - Tap the current stack's button: go back to its root path.
|
|
10
|
+
* - Tap it again on the root path: scroll the page to the top.
|
|
11
11
|
* - It is selected while its stack is the current stack.
|
|
12
12
|
* - Without the browser Navigation API (and in a server render) it is a plain link to the stack's root.
|
|
13
13
|
*
|
|
@@ -24,7 +24,7 @@ export function StackButton({ stack, ...props }) {
|
|
|
24
24
|
const onClick = () => {
|
|
25
25
|
if (current !== stack)
|
|
26
26
|
return nav.forward(nav.history(stack).at(-1) ?? stack, stack);
|
|
27
|
-
if (nav.
|
|
27
|
+
if (nav.path !== stack)
|
|
28
28
|
return nav.back(stack, stack);
|
|
29
29
|
window.scrollTo({ top: 0, behavior: "smooth" });
|
|
30
30
|
for (const el of document.querySelectorAll("main, [data-scroll]"))
|
package/ui/router/StackButton.md
CHANGED
|
@@ -5,9 +5,9 @@ A button for one stack in a tab bar. It acts like a tab button in a phone app.
|
|
|
5
5
|
**Things to know:**
|
|
6
6
|
|
|
7
7
|
- Tap another stack's button: go to the page you left in that stack. The page slides left or right, by tab order.
|
|
8
|
-
- Tap the current stack's button: go back to the root of the stack. The page slides back.
|
|
9
|
-
- Tap it again
|
|
10
|
-
- It is selected (`aria-current`) while its stack is the current stack. On
|
|
8
|
+
- Tap the current stack's button: go back to the root path of the stack. The page slides back. If the root is not in the history (for example after a deep link), it opens the root.
|
|
9
|
+
- Tap it again on the root path: scroll the page to the top. It scrolls the window, and each visible `<main>` or `[data-scroll]` element.
|
|
10
|
+
- It is selected (`aria-current`) while its stack is the current stack. On a floating page (for example a deep link or a login page), no stack button is selected.
|
|
11
11
|
- `stack` must be one of the `stacks` on `<Navigation>`.
|
|
12
12
|
- It takes the usual `<Button>` props, except `href`, `onClick` and `selected`.
|
|
13
13
|
- Without the browser Navigation API, and in a server render, it is a plain link to the stack's root. It is selected while its stack is the starting stack.
|
|
@@ -17,8 +17,8 @@ export interface StackButtonProps extends Omit<ButtonProps, "href" | "onClick" |
|
|
|
17
17
|
/**
|
|
18
18
|
* Button for one stack in a tab bar.
|
|
19
19
|
* - Tap another stack's button: go to the page you left in that stack. The page slides left or right by tab order.
|
|
20
|
-
* - Tap the current stack's button: go back to its root.
|
|
21
|
-
* - Tap it again
|
|
20
|
+
* - Tap the current stack's button: go back to its root path.
|
|
21
|
+
* - Tap it again on the root path: scroll the page to the top.
|
|
22
22
|
* - It is selected while its stack is the current stack.
|
|
23
23
|
* - Without the browser Navigation API (and in a server render) it is a plain link to the stack's root.
|
|
24
24
|
*
|
|
@@ -35,7 +35,7 @@ export function StackButton({ stack, ...props }: StackButtonProps): ReactElement
|
|
|
35
35
|
|
|
36
36
|
const onClick = () => {
|
|
37
37
|
if (current !== stack) return nav.forward(nav.history(stack).at(-1) ?? stack, stack);
|
|
38
|
-
if (nav.
|
|
38
|
+
if (nav.path !== stack) return nav.back(stack, stack);
|
|
39
39
|
window.scrollTo({ top: 0, behavior: "smooth" });
|
|
40
40
|
for (const el of document.querySelectorAll<HTMLElement>("main, [data-scroll]"))
|
|
41
41
|
if (el.offsetParent) el.scrollTo({ top: 0, behavior: "smooth" });
|
package/ui/util/meta.d.ts
CHANGED
|
@@ -54,8 +54,8 @@ export interface Meta {
|
|
|
54
54
|
readonly root?: ImmutableURL | undefined;
|
|
55
55
|
/** URL of the current page (used as the initial URL for routing, and as the page's canonical URL in `<Head>`). */
|
|
56
56
|
readonly url?: ImmutableURL | undefined;
|
|
57
|
-
/** Root path of the current stack (for example `"/home"`). Set it above `<Navigation>` to choose the stack the app opens in. `<Navigation>` publishes the live stack, which is `
|
|
58
|
-
readonly stack?: AbsolutePath | undefined;
|
|
57
|
+
/** Root path of the current stack (for example `"/home"`). Set it above `<Navigation>` to choose the stack the app opens in. `<Navigation>` publishes the live stack, which is `null` for a floating page. */
|
|
58
|
+
readonly stack?: AbsolutePath | null | undefined;
|
|
59
59
|
/** Title of the entire application. */
|
|
60
60
|
readonly app?: string | undefined;
|
|
61
61
|
/** Title of the current page (set as `<title>` in `<Head>` */
|
package/ui/util/meta.ts
CHANGED
|
@@ -59,8 +59,8 @@ export interface Meta {
|
|
|
59
59
|
readonly root?: ImmutableURL | undefined;
|
|
60
60
|
/** URL of the current page (used as the initial URL for routing, and as the page's canonical URL in `<Head>`). */
|
|
61
61
|
readonly url?: ImmutableURL | undefined;
|
|
62
|
-
/** Root path of the current stack (for example `"/home"`). Set it above `<Navigation>` to choose the stack the app opens in. `<Navigation>` publishes the live stack, which is `
|
|
63
|
-
readonly stack?: AbsolutePath | undefined;
|
|
62
|
+
/** Root path of the current stack (for example `"/home"`). Set it above `<Navigation>` to choose the stack the app opens in. `<Navigation>` publishes the live stack, which is `null` for a floating page. */
|
|
63
|
+
readonly stack?: AbsolutePath | null | undefined;
|
|
64
64
|
/** Title of the entire application. */
|
|
65
65
|
readonly app?: string | undefined;
|
|
66
66
|
/** Title of the current page (set as `<title>` in `<Head>` */
|