shelving 1.323.2 → 1.324.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 (84) hide show
  1. package/docs/guides/building-with-shelving.md +3 -3
  2. package/docs/llms-full.txt +345 -149
  3. package/docs/react/SequenceTransitionOptions.md +24 -0
  4. package/docs/react/useSequenceTransition.md +70 -0
  5. package/docs/react.md +2 -0
  6. package/docs/ui/BackButton.md +1 -1
  7. package/docs/ui/Head.md +1 -1
  8. package/docs/ui/HorizontalTransition.md +1 -1
  9. package/docs/ui/Image.md +3 -0
  10. package/docs/ui/Meta.md +2 -0
  11. package/docs/ui/Navigation.md +18 -17
  12. package/docs/ui/NavigationContext.md +2 -2
  13. package/docs/ui/NavigationDirection.md +12 -0
  14. package/docs/ui/NavigationEntryState.md +3 -3
  15. package/docs/ui/NavigationEvent.md +28 -0
  16. package/docs/ui/{NavigationStore → NavigationSequence}/back.md +6 -5
  17. package/docs/ui/NavigationSequence/committed.md +13 -0
  18. package/docs/ui/NavigationSequence/current.md +13 -0
  19. package/docs/ui/{NavigationStore → NavigationSequence}/forward.md +4 -4
  20. package/docs/ui/{NavigationStore → NavigationSequence}/history.md +3 -3
  21. package/docs/ui/{NavigationStore → NavigationSequence}/listen.md +3 -3
  22. package/docs/ui/NavigationSequence/publish.md +14 -0
  23. package/docs/ui/{NavigationStore → NavigationSequence}/replace.md +4 -4
  24. package/docs/ui/NavigationSequence.md +187 -0
  25. package/docs/ui/RouteCache.md +16 -15
  26. package/docs/ui/RouteCacheProps.md +1 -1
  27. package/docs/ui/Router.md +2 -2
  28. package/docs/ui/Transition.md +1 -1
  29. package/docs/ui/VerticalTransition.md +1 -1
  30. package/docs/ui/mergeMeta.md +1 -0
  31. package/docs/ui/requireContext.md +1 -1
  32. package/docs/ui/requireNavigation.md +3 -3
  33. package/docs/ui.md +6 -6
  34. package/package.json +1 -1
  35. package/react/index.d.ts +1 -0
  36. package/react/index.js +1 -0
  37. package/react/useSequenceTransition.d.ts +38 -0
  38. package/react/useSequenceTransition.js +44 -0
  39. package/ui/block/Image.d.ts +3 -0
  40. package/ui/block/Image.js +18 -1
  41. package/ui/block/Image.module.css +27 -0
  42. package/ui/block/Image.tsx +24 -1
  43. package/ui/page/Head.d.ts +1 -1
  44. package/ui/page/Head.js +9 -4
  45. package/ui/page/Head.tsx +8 -4
  46. package/ui/router/BackButton.js +6 -3
  47. package/ui/router/BackButton.md +1 -1
  48. package/ui/router/BackButton.tsx +6 -3
  49. package/ui/router/Navigation.d.ts +5 -5
  50. package/ui/router/Navigation.js +24 -49
  51. package/ui/router/Navigation.md +13 -12
  52. package/ui/router/Navigation.tsx +25 -59
  53. package/ui/router/NavigationContext.d.ts +7 -15
  54. package/ui/router/NavigationContext.js +4 -13
  55. package/ui/router/NavigationContext.tsx +7 -17
  56. package/ui/router/{NavigationStore.d.ts → NavigationSequence.d.ts} +93 -51
  57. package/ui/router/{NavigationStore.js → NavigationSequence.js} +132 -80
  58. package/ui/router/NavigationSequence.md +129 -0
  59. package/ui/router/{NavigationStore.test.ts → NavigationSequence.test.ts} +126 -61
  60. package/ui/router/{NavigationStore.tsx → NavigationSequence.tsx} +160 -92
  61. package/ui/router/RouteCache.d.ts +8 -7
  62. package/ui/router/RouteCache.js +34 -29
  63. package/ui/router/RouteCache.md +9 -8
  64. package/ui/router/RouteCache.tsx +39 -36
  65. package/ui/router/Router.d.ts +2 -2
  66. package/ui/router/Router.js +3 -5
  67. package/ui/router/Router.md +1 -1
  68. package/ui/router/Router.tsx +4 -5
  69. package/ui/router/StackButton.d.ts +1 -1
  70. package/ui/router/StackButton.js +5 -7
  71. package/ui/router/StackButton.tsx +6 -7
  72. package/ui/router/index.d.ts +1 -1
  73. package/ui/router/index.js +1 -1
  74. package/ui/router/index.ts +1 -1
  75. package/ui/transition/HorizontalTransition.md +1 -1
  76. package/ui/transition/Transition.md +1 -1
  77. package/ui/transition/VerticalTransition.md +1 -1
  78. package/ui/util/meta.d.ts +2 -0
  79. package/ui/util/meta.ts +2 -0
  80. package/ui/util/requireContext.md +1 -1
  81. package/docs/ui/NavigationPosition.md +0 -24
  82. package/docs/ui/NavigationPositionContext.md +0 -8
  83. package/docs/ui/NavigationStore.md +0 -164
  84. package/ui/router/NavigationStore.md +0 -110
@@ -6,21 +6,22 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
6
6
 
7
7
  **Things to know:**
8
8
 
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
- - 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
- - 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 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.
9
+ - Each page is keyed by the `stack` and `ordinal` in `Meta`, not by its URL. See `NavigationSequence` for how stacks work.
10
+ - It knows nothing about history. It drops pages only when it has more than `maxCached`: first the pages deeper than the current page in its stack (pages you went back from), then the least recently used.
11
+ - So after a back, the forward button shows the page as you left it, while the cache has room.
12
+ - The current page, the root page of each listed stack, and the last page you saw in each listed stack are never dropped. So each tab always shows the page you left, and always has its root below. Floating pages get no such protection.
13
+ - Keep `maxCached` at `2` or more, so a swipe-back can show the page below and still keep the page you are leaving.
13
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 cache renders the root page hidden, so a swipe-back can show it. A hidden page runs no effects until it is shown.
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}>`.
15
+ - `NavigationSequence.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}>`.
15
16
  - The same URL open in two stacks is two separate pages.
16
17
  - 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).
17
- - Each kept page is frozen under its own `<Meta>` and `NavigationPositionContext`, so a hidden page never re-renders for another page's URL.
18
+ - Each kept page is frozen under its own `<Meta>`, so a hidden page never re-renders for another page's URL.
18
19
  - `<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.
19
20
  - **Nesting:** layout, then transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. See the usage below.
20
21
  - 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.
21
22
  - Put a page `<Transition>` **around** the `<RouteCache>`, not inside it. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
22
23
  - Keep the layout **outside** the cache. Chrome in the layout (a sidebar, a tab bar) then has one copy, keeps its own state, and plays its own CSS transitions. Chrome inside the cache gets one copy per kept page.
23
- - Without the browser Navigation API, or with `maxCached={0}`, there is no cache: the current page renders directly and unmounts when you leave it.
24
+ - With no `ordinal` in `Meta` (no browser Navigation API, or a server render), or with `maxCached={0}`, there is no cache: the current page renders directly and unmounts when you leave it.
24
25
 
25
26
  ## Usage
26
27
 
@@ -28,7 +29,7 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
28
29
  import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
29
30
 
30
31
  <AppLayout nav={<StackBar />}>
31
- <HorizontalTransition>
32
+ <HorizontalTransition default="none">
32
33
  <RouteCache>
33
34
  <Scroll vertical cover>
34
35
  <PageLoader>
@@ -1,16 +1,14 @@
1
- import { Activity, type ReactNode, use, useRef } from "react";
1
+ import { Activity, type ReactNode, 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";
5
- import { NavigationPositionContext } from "./NavigationContext.js";
6
- import type { NavigationPosition } from "./NavigationStore.js";
4
+ import { mergeMeta } from "../util/meta.js";
7
5
 
8
6
  /** A cached page: the rendered node, where it is in its stack, and a `used` tick for least-recently-used eviction. */
9
7
  interface _CacheEntry {
10
8
  node: ReactNode;
11
9
  used: number;
12
10
  readonly stack: AbsolutePath | null;
13
- readonly depth: number;
11
+ readonly ordinal: number;
14
12
  }
15
13
 
16
14
  /**
@@ -21,8 +19,9 @@ interface _CacheEntry {
21
19
  export interface RouteCacheProps {
22
20
  /**
23
21
  * 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.
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.
22
+ * - The root page and the last page you saw in 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
23
  * - Floating pages get no such protection.
24
+ * - Keep it at `2` or more, so a swipe-back can show the page below and still keep the page you are leaving.
26
25
  * - Set to `0` (or less) to turn the cache off and unmount each page as you leave it.
27
26
  *
28
27
  * @default 10
@@ -36,22 +35,22 @@ export interface RouteCacheProps {
36
35
  * 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.
37
36
  *
38
37
  * - Put a page transition around it, and a `<Scroll vertical cover>` inside it, so each kept page scrolls in its own box.
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.
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.
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.
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.
38
+ * - Keeps each page 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.
39
+ * - Each page is keyed by the `stack` and `ordinal` in `Meta`, not by its URL. So `NavigationSequence.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.
40
+ * - It knows nothing about history. It only drops pages when it has more than `maxCached`: first the pages deeper than the current page in its stack (pages you went back from), then the least recently used. So after a back, a forward shows the page as you left it, and a cancelled swipe-back still has the page it started from.
41
+ * - The root page and the last page you saw in each listed stack are never dropped. Floating pages (stack `null`) get no such protection.
43
42
  * - 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.
43
+ * - 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.
45
44
  * - `<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.
46
- * - Without the browser Navigation API (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
45
+ * - With no `ordinal` in `Meta` (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
47
46
  *
48
47
  * @kind component
49
48
  * @see https://shelving.cc/ui/RouteCache
50
49
  */
51
50
  export function RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode {
52
- // Read the live URL and the position in the stacks; each navigation re-renders this with both.
51
+ // Read the page from meta; each navigation re-renders this with the new page.
53
52
  const meta = requireMetaURL();
54
- const position = use(NavigationPositionContext);
53
+ const { stack = null, ordinal } = meta;
55
54
  const mapRef = useRef<Map<string, _CacheEntry>>(undefined);
56
55
  const usedRef = useRef(0);
57
56
 
@@ -60,7 +59,7 @@ export function RouteCache({ maxCached = 10, children }: RouteCacheProps): React
60
59
 
61
60
  // No stacks (server render, or no Navigation API): render only the current page.
62
61
  // It is still inside an `<Activity>`, so a server render has the same structure as the first render in the browser, and hydration matches.
63
- if (!position)
62
+ if (ordinal === undefined)
64
63
  return (
65
64
  <Activity mode="visible">
66
65
  <MetaContext value={meta}>{children}</MetaContext>
@@ -68,30 +67,30 @@ export function RouteCache({ maxCached = 10, children }: RouteCacheProps): React
68
67
  );
69
68
 
70
69
  // Find (or make) the entry for the current page.
71
- const { stack, depth, tops } = position;
72
70
  const map = (mapRef.current ??= new Map());
73
- const key = `${stack} ${depth}`;
74
- const entry = map.get(key) ?? { node: null, used: 0, stack, depth };
71
+ const key = `${stack} ${ordinal}`;
72
+ const entry = map.get(key) ?? { node: null, used: 0, stack, ordinal };
75
73
  map.set(key, entry);
76
74
 
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
+ // Snapshot the children under the live meta (frozen), so each kept page keeps rendering for the URL it last had.
76
+ entry.node = <MetaContext value={meta}>{children}</MetaContext>;
79
77
  entry.used = ++usedRef.current;
80
78
 
81
79
  // A listed stack always has its root page below a deeper page, so render the root (hidden) if it is not cached.
82
80
  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 });
81
+ if (stack !== null && ordinal > 0 && !map.has(rootKey)) {
82
+ const rootMeta = { ...mergeMeta(meta, { url: stack, stack, ordinal: 0 }, RouteCache), path: stack, params: {} };
83
+ map.set(rootKey, { node: <MetaContext value={rootMeta}>{children}</MetaContext>, used: 0, stack, ordinal: 0 });
87
84
  }
88
85
 
89
- // Drop the pages that have left their stack.
90
- for (const [k, { stack: s, depth: d }] of map) if (k !== key && !(d <= (tops.get(s) ?? -1))) map.delete(k);
91
-
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.
86
+ // Past the limit, drop pages: never the current page, a stack's root, or the last page seen in each listed stack.
87
+ const last = _getLastUsed(map);
88
+ const droppable = (k: string, e: _CacheEntry) => k !== key && (e.stack === null || (e.ordinal !== 0 && last.get(e.stack) !== k));
93
89
  while (map.size > maxCached) {
94
- const lru = _findLeastRecentlyUsed(map, (k, { stack: s, depth: d }) => k !== key && (s === null || (d !== 0 && tops.get(s) !== d)));
90
+ // First the pages deeper than the current page in its stack (pages you went back from), then the least recently used.
91
+ const lru =
92
+ _findLeastRecentlyUsed(map, (k, e) => e.stack === stack && e.ordinal > ordinal && droppable(k, e)) ??
93
+ _findLeastRecentlyUsed(map, droppable);
95
94
  if (lru === undefined) break;
96
95
  map.delete(lru);
97
96
  }
@@ -104,13 +103,17 @@ export function RouteCache({ maxCached = 10, children }: RouteCacheProps): React
104
103
  ));
105
104
  }
106
105
 
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
- );
106
+ /** Get the key of the most recently used page in each stack. */
107
+ function _getLastUsed(map: Map<string, _CacheEntry>): Map<AbsolutePath | null, string> {
108
+ const last = new Map<AbsolutePath | null, string>();
109
+ const used = new Map<AbsolutePath | null, number>();
110
+ for (const [key, entry] of map) {
111
+ if (entry.used > (used.get(entry.stack) ?? -1)) {
112
+ used.set(entry.stack, entry.used);
113
+ last.set(entry.stack, key);
114
+ }
115
+ }
116
+ return last;
114
117
  }
115
118
 
116
119
  /** Find the key of the least-recently-used entry that may be dropped, or `undefined` if none may. */
@@ -1,4 +1,4 @@
1
- import { type ReactElement } from "react";
1
+ import type { ReactElement } from "react";
2
2
  import type { PossibleMeta } from "../util/meta.js";
3
3
  import type { Routes } from "./Routes.js";
4
4
  /**
@@ -21,7 +21,7 @@ export interface RouterProps extends PossibleMeta {
21
21
  * - When `base` is set, the effective path is the URL after stripping the base prefix.
22
22
  * - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
23
23
  * - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
24
- * - Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationStore.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
24
+ * - Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationSequence.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
25
25
  * - Elsewhere, each path is a new page, so a component route remounts when the path changes.
26
26
  * - Returns `null` when there's no URL in context or the URL is outside the base.
27
27
  *
@@ -1,18 +1,16 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
- import { use } from "react";
3
2
  import { NotFoundError } from "../../error/RequestError.js";
4
3
  import { UnexpectedError } from "../../error/UnexpectedError.js";
5
4
  import { getProps } from "../../util/index.js";
6
5
  import { matchPathTemplate, renderPathTemplate } from "../../util/template.js";
7
6
  import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
8
- import { NavigationPositionContext } from "./NavigationContext.js";
9
7
  /**
10
8
  * Match the current URL against `routes` and render the matched element.
11
9
  * - Reads `url` and `base` from the surrounding `<Meta>` context (override via props).
12
10
  * - When `base` is set, the effective path is the URL after stripping the base prefix.
13
11
  * - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
14
12
  * - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
15
- * - Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationStore.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
13
+ * - Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationSequence.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
16
14
  * - Elsewhere, each path is a new page, so a component route remounts when the path changes.
17
15
  * - Returns `null` when there's no URL in context or the URL is outside the base.
18
16
  *
@@ -24,8 +22,8 @@ export function Router({ routes, fallback, ...meta }) {
24
22
  const combined = requireMetaURL(meta);
25
23
  const path = combined;
26
24
  // Key the page by its place in the stack when there is one, else by its path.
27
- const position = use(NavigationPositionContext);
28
- const key = position ? `${position.stack} ${position.depth}` : combined.path;
25
+ const { stack, ordinal } = combined;
26
+ const key = ordinal !== undefined ? `${stack ?? null} ${ordinal}` : combined.path;
29
27
  const route = _matchRoute(routes, fallback, combined, key);
30
28
  if (route)
31
29
  return _jsx(MetaContext, { value: combined, children: route });
@@ -8,7 +8,7 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
8
8
  - `<Router>` accepts `PossibleMeta` props (`url`, `base`, etc.) to override the surrounding context — this is how nested routers scope themselves.
9
9
  - With a `base` set, the path used for matching is the URL after `matchURLPrefix()` strips the base prefix; URLs outside the base render as `null`.
10
10
  - Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
11
- - Inside `<Navigation>` with stacks, each page in a stack is a new page: a link mounts a new page, and `NavigationStore.replace()` keeps the same page mounted (it re-renders with the new URL). Elsewhere each path is a new page.
11
+ - Inside `<Navigation>` with stacks, each page in a stack is a new page: a link mounts a new page, and `NavigationSequence.replace()` keeps the same page mounted (it re-renders with the new URL). Elsewhere each path is a new page.
12
12
  - `<Router>` itself does not cache pages — wrap it in a `<RouteCache>` (with a `<Scroll vertical cover>` between them) to keep recently-visited pages mounted but hidden so back/forward navigation restores their state.
13
13
 
14
14
  ## Usage
@@ -1,11 +1,10 @@
1
- import { type ReactElement, use } from "react";
1
+ import type { ReactElement } from "react";
2
2
  import { NotFoundError } from "../../error/RequestError.js";
3
3
  import { UnexpectedError } from "../../error/UnexpectedError.js";
4
4
  import { getProps } from "../../util/index.js";
5
5
  import { matchPathTemplate, renderPathTemplate } from "../../util/template.js";
6
6
  import { MetaContext, type MetaURL, requireMetaURL } from "../misc/MetaContext.js";
7
7
  import type { PossibleMeta } from "../util/meta.js";
8
- import { NavigationPositionContext } from "./NavigationContext.js";
9
8
  import type { Routes } from "./Routes.js";
10
9
 
11
10
  /**
@@ -30,7 +29,7 @@ export interface RouterProps extends PossibleMeta {
30
29
  * - When `base` is set, the effective path is the URL after stripping the base prefix.
31
30
  * - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
32
31
  * - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
33
- * - Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationStore.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
32
+ * - Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationSequence.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
34
33
  * - Elsewhere, each path is a new page, so a component route remounts when the path changes.
35
34
  * - Returns `null` when there's no URL in context or the URL is outside the base.
36
35
  *
@@ -43,8 +42,8 @@ export function Router({ routes, fallback, ...meta }: RouterProps): ReactElement
43
42
  const path = combined;
44
43
 
45
44
  // Key the page by its place in the stack when there is one, else by its path.
46
- const position = use(NavigationPositionContext);
47
- const key = position ? `${position.stack} ${position.depth}` : combined.path;
45
+ const { stack, ordinal } = combined;
46
+ const key = ordinal !== undefined ? `${stack ?? null} ${ordinal}` : combined.path;
48
47
 
49
48
  const route = _matchRoute(routes, fallback, combined, key);
50
49
  if (route) return <MetaContext value={combined}>{route}</MetaContext>;
@@ -1,4 +1,4 @@
1
- import { type ReactElement } from "react";
1
+ import type { ReactElement } from "react";
2
2
  import type { AbsolutePath } from "../../util/path.js";
3
3
  import { type ButtonProps } from "../button/Button.js";
4
4
  /**
@@ -1,8 +1,7 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
- import { use } from "react";
3
- import { useStore } from "../../react/useStore.js";
4
2
  import { Button } from "../button/Button.js";
5
- import { NavigationPositionContext, requireNavigation } from "./NavigationContext.js";
3
+ import { requireMetaURL } from "../misc/MetaContext.js";
4
+ import { requireNavigation } from "./NavigationContext.js";
6
5
  /**
7
6
  * Button for one stack in a tab bar.
8
7
  * - Tap another stack's button: go to the page you left in that stack. The page slides left or right by tab order.
@@ -16,15 +15,14 @@ import { NavigationPositionContext, requireNavigation } from "./NavigationContex
16
15
  */
17
16
  export function StackButton({ stack, ...props }) {
18
17
  const nav = requireNavigation();
19
- const current = useStore(nav.stack).value;
20
- const position = use(NavigationPositionContext);
18
+ const { stack: current, ordinal, path } = requireMetaURL();
21
19
  // No Navigation API (or a server render): a plain link to the root, selected while its stack is the current stack.
22
- if (!position)
20
+ if (ordinal === undefined)
23
21
  return _jsx(Button, { ...props, href: stack, selected: current === stack });
24
22
  const onClick = () => {
25
23
  if (current !== stack)
26
24
  return nav.forward(nav.history(stack).at(-1) ?? stack, stack);
27
- if (nav.path !== stack)
25
+ if (path !== stack)
28
26
  return nav.back(stack, stack);
29
27
  window.scrollTo({ top: 0, behavior: "smooth" });
30
28
  for (const el of document.querySelectorAll("main, [data-scroll]"))
@@ -1,8 +1,8 @@
1
- import { type ReactElement, use } from "react";
2
- import { useStore } from "../../react/useStore.js";
1
+ import type { ReactElement } from "react";
3
2
  import type { AbsolutePath } from "../../util/path.js";
4
3
  import { Button, type ButtonProps } from "../button/Button.js";
5
- import { NavigationPositionContext, requireNavigation } from "./NavigationContext.js";
4
+ import { requireMetaURL } from "../misc/MetaContext.js";
5
+ import { requireNavigation } from "./NavigationContext.js";
6
6
 
7
7
  /**
8
8
  * Props for `<StackButton>`: the `stack` it opens, plus the usual `Button` props except `href` and `onClick`.
@@ -27,15 +27,14 @@ export interface StackButtonProps extends Omit<ButtonProps, "href" | "onClick" |
27
27
  */
28
28
  export function StackButton({ stack, ...props }: StackButtonProps): ReactElement {
29
29
  const nav = requireNavigation();
30
- const current = useStore(nav.stack).value;
31
- const position = use(NavigationPositionContext);
30
+ const { stack: current, ordinal, path } = requireMetaURL();
32
31
 
33
32
  // No Navigation API (or a server render): a plain link to the root, selected while its stack is the current stack.
34
- if (!position) return <Button {...props} href={stack} selected={current === stack} />;
33
+ if (ordinal === undefined) return <Button {...props} href={stack} selected={current === stack} />;
35
34
 
36
35
  const onClick = () => {
37
36
  if (current !== stack) return nav.forward(nav.history(stack).at(-1) ?? stack, stack);
38
- if (nav.path !== stack) return nav.back(stack, stack);
37
+ if (path !== stack) return nav.back(stack, stack);
39
38
  window.scrollTo({ top: 0, behavior: "smooth" });
40
39
  for (const el of document.querySelectorAll<HTMLElement>("main, [data-scroll]"))
41
40
  if (el.offsetParent) el.scrollTo({ top: 0, behavior: "smooth" });
@@ -1,7 +1,7 @@
1
1
  export * from "./BackButton.js";
2
2
  export * from "./Navigation.js";
3
3
  export * from "./NavigationContext.js";
4
- export * from "./NavigationStore.js";
4
+ export * from "./NavigationSequence.js";
5
5
  export * from "./RouteCache.js";
6
6
  export * from "./Router.js";
7
7
  export * from "./Routes.js";
@@ -1,7 +1,7 @@
1
1
  export * from "./BackButton.js";
2
2
  export * from "./Navigation.js";
3
3
  export * from "./NavigationContext.js";
4
- export * from "./NavigationStore.js";
4
+ export * from "./NavigationSequence.js";
5
5
  export * from "./RouteCache.js";
6
6
  export * from "./Router.js";
7
7
  export * from "./Routes.js";
@@ -1,7 +1,7 @@
1
1
  export * from "./BackButton.js";
2
2
  export * from "./Navigation.js";
3
3
  export * from "./NavigationContext.js";
4
- export * from "./NavigationStore.js";
4
+ export * from "./NavigationSequence.js";
5
5
  export * from "./RouteCache.js";
6
6
  export * from "./Router.js";
7
7
  export * from "./Routes.js";
@@ -5,7 +5,7 @@ A direction-aware `<Transition>` preset that slides its children horizontally
5
5
  **Things to know:**
6
6
 
7
7
  - Slides right by default and when the type is `"forward"`; slides left when the type is `"back"`.
8
- - Inside `<Navigation>` the direction is automatic: a link click or `NavigationStore.forward()` sets the `"forward"` type, and a `className="back"` link or `NavigationStore.back()` sets `"back"`. The browser back and forward buttons set the type from the page's place in its stack. `NavigationStore.replace()` has no transition. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
8
+ - Inside `<Navigation>` the direction is automatic: a link click or `NavigationSequence.forward()` sets the `"forward"` type, and a `className="back"` link or `NavigationSequence.back()` sets `"back"`. The browser back and forward buttons set the type from the page's place in its stack. `NavigationSequence.replace()` has no transition. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
9
9
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
10
10
  - The old and new content slide a full width apart, so they sit edge to edge and never overlap.
11
11
  - The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
@@ -6,7 +6,7 @@ The base View Transition wrapper. It wraps its children in React 19's `<ViewTran
6
6
 
7
7
  - Set `default` for the base transition; `forward` and `back` default to it and let you pick a direction-aware variant. The class names must correspond to `::view-transition-old(.className)` / `::view-transition-new(.className)` rules in your CSS.
8
8
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`, from `Transition.module.css`).
9
- - Direction is driven by the active view-transition type. `<Navigation>` sets it for each page change (`"forward"` for a link or `NavigationStore.forward()`, `"back"` for the browser back button). For any other change, call `setTransitionType("forward")` (or `"back"`) inside a `startTransition()` callback; the variants read that type to choose the correct slide.
9
+ - Direction is driven by the active view-transition type. `<Navigation>` sets it for each page change (`"forward"` for a link or `NavigationSequence.forward()`, `"back"` for the browser back button). For any other change, call `setTransitionType("forward")` (or `"back"`) inside a `startTransition()` callback; the variants read that type to choose the correct slide.
10
10
  - React runs a view transition only for a transition update (`startTransition()`, `useDeferredValue()` or a Suspense reveal). A sync update, for example a `useStore()` change, swaps the content with no animation.
11
11
  - The preset variants honour `prefers-reduced-motion: reduce` — positional movement (slides, collapse) is removed while opacity-only fades are kept (see each preset's page). Custom transition classes should ship their own `@media (prefers-reduced-motion: reduce)` override; `animation: none` on the `::view-transition-*` pseudo-elements makes the swap an instant cut while the DOM update still happens.
12
12
 
@@ -5,7 +5,7 @@ A direction-aware `<Transition>` preset that slides its children vertically —
5
5
  **Things to know:**
6
6
 
7
7
  - Slides down by default and when the type is `"forward"`; slides up when the type is `"back"`.
8
- - Inside `<Navigation>` the direction is automatic: a link click or `NavigationStore.forward()` sets the `"forward"` type, and a `className="back"` link or `NavigationStore.back()` sets `"back"`. The browser back and forward buttons set the type from the page's place in its stack. `NavigationStore.replace()` has no transition. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
8
+ - Inside `<Navigation>` the direction is automatic: a link click or `NavigationSequence.forward()` sets the `"forward"` type, and a `className="back"` link or `NavigationSequence.back()` sets `"back"`. The browser back and forward buttons set the type from the page's place in its stack. `NavigationSequence.replace()` has no transition. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
9
9
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
10
10
  - The old and new content slide a full height apart, so they sit edge to edge and never overlap.
11
11
  - The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
package/ui/util/meta.d.ts CHANGED
@@ -56,6 +56,8 @@ export interface Meta {
56
56
  readonly url?: ImmutableURL | undefined;
57
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
58
  readonly stack?: AbsolutePath | null | undefined;
59
+ /** Position of the current page in its stack, where `0` is the root. `<Navigation>` publishes it, and `<RouteCache>` and `<Router>` key each page by its stack and ordinal. `undefined` without the Navigation API. */
60
+ readonly ordinal?: number | undefined;
59
61
  /** Title of the entire application. */
60
62
  readonly app?: string | undefined;
61
63
  /** Title of the current page (set as `<title>` in `<Head>` */
package/ui/util/meta.ts CHANGED
@@ -61,6 +61,8 @@ export interface Meta {
61
61
  readonly url?: ImmutableURL | undefined;
62
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
63
  readonly stack?: AbsolutePath | null | undefined;
64
+ /** Position of the current page in its stack, where `0` is the root. `<Navigation>` publishes it, and `<RouteCache>` and `<Router>` key each page by its stack and ordinal. `undefined` without the Navigation API. */
65
+ readonly ordinal?: number | undefined;
64
66
  /** Title of the entire application. */
65
67
  readonly app?: string | undefined;
66
68
  /** Title of the current page (set as `<title>` in `<Head>` */
@@ -13,7 +13,7 @@ Reads a React context and throws `RequiredError` if the value is `null` or `unde
13
13
  ```ts
14
14
  import { requireContext } from "shelving/ui";
15
15
 
16
- function requireNavigation(): NavigationStore {
16
+ function requireNavigation(): NavigationSequence {
17
17
  return requireContext(NavigationContext, requireNavigation);
18
18
  }
19
19
  ```
@@ -1,24 +0,0 @@
1
- # NavigationPosition
2
-
3
- - Kind: interface
4
- - Import: `import { NavigationPosition } from "shelving/ui";`
5
- - Extends: `NavigationEntryState`
6
-
7
- Where the app is now in its stacks: the current stack and depth, the top depth of each stack, and the page before the current one.
8
- - `undefined` when the browser has no Navigation API, or during a server render.
9
-
10
- ## Signatures
11
-
12
- ```ts
13
- {
14
- readonly tops: ReadonlyMap<AbsolutePath | null, number>;
15
- readonly parent: AbsolutePath | undefined;
16
- }
17
- ```
18
-
19
- ## Properties
20
-
21
- | Property | Type | Description |
22
- | --- | --- | --- |
23
- | `tops` | `ReadonlyMap<AbsolutePath \| null, number>` | Depth of the top page of each stack that has pages, including the floating stack (`null`). Read only. |
24
- | `parent` | `AbsolutePath \| undefined` | The page before the current one in its stack, or `undefined` at the bottom of the stack. Read only. |
@@ -1,8 +0,0 @@
1
- # NavigationPositionContext
2
-
3
- - Kind: constant
4
- - Import: `import { NavigationPositionContext } from "shelving/ui";`
5
-
6
- React context holding where the app is in its stacks, published by `<Navigation>` with each URL change.
7
- - `undefined` without the browser Navigation API, during a server render, or outside `<Navigation>`.
8
- - `<RouteCache>`, `<Router>` and `<BackButton>` read it, so they change in the same render as the URL.