shelving 1.322.3 → 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.
Files changed (39) hide show
  1. package/docs/guides/building-with-shelving.md +1 -1
  2. package/docs/llms-full.txt +61 -47
  3. package/docs/ui/BackButton.md +1 -1
  4. package/docs/ui/Meta.md +2 -2
  5. package/docs/ui/Navigation.md +4 -4
  6. package/docs/ui/NavigationEntryState.md +2 -2
  7. package/docs/ui/NavigationPosition.md +2 -2
  8. package/docs/ui/NavigationProps.md +3 -3
  9. package/docs/ui/NavigationStore/back.md +1 -1
  10. package/docs/ui/NavigationStore/forward.md +1 -1
  11. package/docs/ui/NavigationStore/history.md +3 -2
  12. package/docs/ui/NavigationStore/replace.md +1 -1
  13. package/docs/ui/NavigationStore.md +26 -15
  14. package/docs/ui/RouteCache.md +7 -5
  15. package/docs/ui/RouteCacheProps.md +1 -1
  16. package/docs/ui/StackButton.md +5 -5
  17. package/docs/ui/mergeMeta.md +1 -1
  18. package/package.json +1 -1
  19. package/ui/router/BackButton.md +1 -1
  20. package/ui/router/Navigation.d.ts +4 -3
  21. package/ui/router/Navigation.js +1 -1
  22. package/ui/router/Navigation.md +2 -2
  23. package/ui/router/Navigation.test.tsx +11 -1
  24. package/ui/router/Navigation.tsx +6 -5
  25. package/ui/router/NavigationStore.d.ts +32 -24
  26. package/ui/router/NavigationStore.js +42 -27
  27. package/ui/router/NavigationStore.md +18 -10
  28. package/ui/router/NavigationStore.test.ts +90 -23
  29. package/ui/router/NavigationStore.tsx +58 -41
  30. package/ui/router/RouteCache.d.ts +5 -3
  31. package/ui/router/RouteCache.js +20 -7
  32. package/ui/router/RouteCache.md +3 -2
  33. package/ui/router/RouteCache.tsx +30 -9
  34. package/ui/router/StackButton.d.ts +2 -2
  35. package/ui/router/StackButton.js +3 -3
  36. package/ui/router/StackButton.md +3 -3
  37. package/ui/router/StackButton.tsx +3 -3
  38. package/ui/util/meta.d.ts +2 -2
  39. 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: { readonly [stack: AbsolutePath]: number };
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. A single-stack app has one root. */
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
- * - Always set. With no `stacks`, it is `"/"`.
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.length ? 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 : 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: { [stack: AbsolutePath]: number } = {};
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[s] = top.depth;
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 gone (the browser keeps a limited history) still starts with its root.
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) : 0;
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 ?? 0);
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 : 0 };
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 0. */
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
- return { stack: this._start, depth: 0 };
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 unstacked `"/"` stack. */
331
- private _getStacks(): AbsolutePath[] {
332
- return Array.from(new Set([...this.stacks, this._start, "/" as const]));
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 is never dropped, even past the limit, so a tab always shows the page you left.
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 is never dropped. Other pages can be dropped past `maxCached`, and show fresh (from the top) when you come back to them.
27
- * - Each kept page is frozen under its own `<MetaContext>`, so the same `children` element renders a different page for each URL, and a hidden page never re-renders for another page's URL.
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
  *
@@ -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 is never dropped. Other pages can be dropped past `maxCached`, and show fresh (from the top) when you come back to them.
13
- * - Each kept page is frozen under its own `<MetaContext>`, so the same `children` element renders a different page for each URL, and a hidden page never re-renders for another page's URL.
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 = _jsx(MetaContext, { value: meta, children: children });
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[s] ?? -1)))
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[s] !== d);
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;
@@ -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 is never dropped, so each tab always shows the page you left. Other pages are dropped (least recently used first) past `maxCached`, and mount fresh when you come back to them.
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>`, so a hidden page never re-renders for another page's URL.
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.
@@ -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 is never dropped, even past the limit, so a tab always shows the page you left.
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 is never dropped. Other pages can be dropped past `maxCached`, and show fresh (from the top) when you come back to them.
40
- * - Each kept page is frozen under its own `<MetaContext>`, so the same `children` element renders a different page for each URL, and a hidden page never re-renders for another page's URL.
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 = <MetaContext value={meta}>{children}</MetaContext>;
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[s] ?? -1))) map.delete(k);
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[s] !== d);
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 at the root: scroll the page to the top.
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
  *
@@ -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 at the root: scroll the page to the top.
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.history(stack).length > 1)
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]"))
@@ -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 at the root: 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 an unstacked page (for example a deep link or a login page), no stack button is selected.
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 at the root: scroll the page to the top.
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.history(stack).length > 1) return nav.back(stack, stack);
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 `"/"` for an unstacked page. */
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 `"/"` for an unstacked page. */
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>` */