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
@@ -713,7 +713,7 @@ Each tab keeps its own stack of pages, and its back button goes back within that
713
713
  3. Put `<BackButton href="/home" />` in each page header. It goes back in the current tab, or to `href` when there is no page before.
714
714
  4. Use `<RouteCache>`, so each tab shows the page you left it on.
715
715
 
716
- Use `className="replace"` on in-page tab links (for example `/dave/posts` and `/dave/likes`), so they change the URL without a new page. See `<Navigation>`, `NavigationStore`, `<StackButton>` and `<BackButton>`.
716
+ Use `className="replace"` on in-page tab links (for example `/dave/posts` and `/dave/likes`), so they change the URL without a new page. See `<Navigation>`, `NavigationSequence`, `<StackButton>` and `<BackButton>`.
717
717
 
718
718
  #### Hide the tab bar on some pages
719
719
 
@@ -1083,7 +1083,7 @@ If every file in that list is in the right place, the client and server share on
1083
1083
  3. **Remove `<RouteConfig>`.** `<RouteConfig>` and `RouteContext` are removed.
1084
1084
  - `<RouteConfig path>` kept a page mounted for its tabs (for example `/dave/{tab}`). Instead, add `className="replace"` to each in-page tab link: `<Button href="/dave/posts" className="replace">Posts</Button>`. A replace keeps the same page mounted, with no slide and no new history entry.
1085
1085
  - `<RouteConfig cache={false}>` unmounted a create form when you left it. Instead, clear the form after a successful submit: change the `key` of the `<Form>`, or call `form.reset()` on a plain HTML form. See `<RouteCache>` for an example.
1086
- 4. **Canonical URLs.** `<Head>` no longer writes browser history itself. When a page renders a `<Head>` with a `url` that is not the current URL, `<Head>` calls `NavigationStore.replace()`. You do not need to change anything, but do not also call `window.history.replaceState()` for it.
1086
+ 4. **Canonical URLs.** `<Head>` no longer writes browser history itself. When a page renders a `<Head>` with a `url` that is not the current URL, `<Head>` calls `NavigationSequence.replace()`. You do not need to change anything, but do not also call `window.history.replaceState()` for it.
1087
1087
  5. **Add stacks (optional).** For an app with a tab bar, set `stacks` on `<Navigation>` to the root path of each tab, in tab order: `<Navigation stacks={["/home", "/discover", "/profile"]}>`. Each link then opens a new page in the current tab, wherever it points. Set `stack` on `<Navigation>` to the stack the app opens in. With no `stack`, the page floats (its stack is `null`): it is outside every tab, so no tab is selected until the user taps a tab, or the app names a stack. Deep links and login pages float. `/` is a normal stack root, so a Home tab can be `/`. A login page calls `nav.replace("/home", "/home")` to send the user into the Home tab.
1088
1088
  6. **Use the new buttons (optional).**
1089
1089
  - `<StackButton stack="/home">` is a tab bar button. It goes to the page you left in that tab, goes back to the tab's root when you are already in it, and scrolls to the top at the root.
@@ -1098,7 +1098,7 @@ What changes for users:
1098
1098
  - The browser back button walks the history as before, across tabs. The page slides the right way.
1099
1099
  - When you go back from a page, it leaves the cache. So the browser forward button then shows that page fresh, from the top.
1100
1100
 
1101
- See `<Navigation>`, `NavigationStore`, `<RouteCache>`, `<StackButton>` and `<BackButton>` for the full details.
1101
+ See `<Navigation>`, `NavigationSequence`, `<RouteCache>`, `<StackButton>` and `<BackButton>` for the full details.
1102
1102
 
1103
1103
  ### Layouts are frames
1104
1104
 
@@ -11478,12 +11478,14 @@ function Toggle() {
11478
11478
  - [useMap()](react/useMap.md): Create a mutable Map that persists for the lifetime of the component.
11479
11479
  - [useReduce()](react/useReduce.md): Use memoised value with reduction logic.
11480
11480
  - [useSequence()](react/useSequence.md): Subscribe to an async iterable for the lifetime of the component.
11481
+ - [useSequenceTransition()](react/useSequenceTransition.md): Subscribe to an async iterable, and set each value it yields inside a React transition.
11481
11482
  - [useStore()](react/useStore.md): Subscribe to a Shelving Store instance to refresh this component when its value changes.
11482
11483
 
11483
11484
  ## Interfaces
11484
11485
 
11485
11486
  - [APIContext](react/APIContext.md): Bundle of hooks and a provider component returned by createAPIContext()
11486
11487
  - [DBContext](react/DBContext.md): Bundle of hooks and a provider component returned by createDBContext().
11488
+ - [SequenceTransitionOptions](react/SequenceTransitionOptions.md): Options for useSequenceTransition().
11487
11489
 
11488
11490
 
11489
11491
  ---
@@ -12054,6 +12056,108 @@ useSequence(sequence?: AsyncIterable<T>): T | undefined
12054
12056
  | `unknown` | unknown Re-throws (during render) any error thrown by the sequence, for an error boundary to catch. |
12055
12057
 
12056
12058
 
12059
+ ---
12060
+
12061
+ # SequenceTransitionOptions
12062
+
12063
+ - Kind: interface
12064
+ - Import: `import { SequenceTransitionOptions } from "shelving/react";`
12065
+
12066
+ Options for `useSequenceTransition()`.
12067
+
12068
+ ## Signatures
12069
+
12070
+ ```ts
12071
+ {
12072
+ readonly current: () => T;
12073
+ readonly transition?: string | ((value: T) => string | null | undefined) | undefined;
12074
+ readonly equal?: ((a: T, b: T) => boolean) | undefined;
12075
+ }
12076
+ ```
12077
+
12078
+ ## Properties
12079
+
12080
+ | Property | Type | Description |
12081
+ | --- | --- | --- |
12082
+ | `current` | `() => T` | Read the current value. - Called for the first render, and again when the subscription starts, to catch up on values sent before it started. Read only. |
12083
+ | `transition` | `string \| ((value: T) => string \| null \| undefined) \| undefined` | Transition type for a value, or a fixed type for every value. - A value with a type is set inside `startTransition()` with that type, so a `<ViewTransition>` can animate it. - A value with no type (`undefined` or `null`) is set at once, with no transition. Read only. Optional. |
12084
+ | `equal` | `((a: T, b: T) => boolean) \| undefined` | Is a new value the same as the shown value? A value that is the same is skipped, so it starts no second transition. Read only. Defaults to `Object.is`. |
12085
+
12086
+
12087
+ ---
12088
+
12089
+ # useSequenceTransition()
12090
+
12091
+ - Kind: function
12092
+ - Import: `import { useSequenceTransition } from "shelving/react";`
12093
+
12094
+ Subscribe to an async iterable, and set each value it yields inside a React transition.
12095
+ - Like `useSequence()`, but each value is set with `setState()` inside `startTransition()`, with a transition type, so a `<ViewTransition>` runs for it.
12096
+ - It uses `useState()` and not `useSyncExternalStore()`, because React always renders a `useSyncExternalStore()` update at once, outside any transition.
12097
+ - The transition type is shared by the whole React root: the next transition commit takes every type that is waiting.
12098
+
12099
+ Subscribe to an `AsyncIterable` and set each value it yields inside a React transition, with a transition type. A `<ViewTransition>` (or a `<Transition>` such as `<HorizontalTransition>`) around the content that reads the value then animates each change. `<Navigation>` uses it to slide pages.
12100
+
12101
+ **Things to know:**
12102
+
12103
+ - It uses `useState()`, not `useSyncExternalStore()`. React always renders a `useSyncExternalStore()` update at once, outside any transition, so a store read can never animate.
12104
+ - `current` gives the first value, and is read again when the subscription starts, to catch up on values sent before it started.
12105
+ - `transition` is a fixed type, or a function that returns the type for each value. A value with no type is set at once, with no transition.
12106
+ - `equal` skips a value that is the same as the value shown, so it starts no second transition. It defaults to `Object.is`.
12107
+ - Transition types belong to the whole React root: the next transition commit takes every type that is waiting.
12108
+ - If the sequence throws, the error is re-thrown during render, so the nearest error boundary catches it.
12109
+ - Memoise the iterable. The subscription restarts when the iterable changes.
12110
+
12111
+ ## Usage
12112
+
12113
+ ```tsx
12114
+ import { useSequenceTransition } from "shelving/react";
12115
+ import { ViewTransition } from "react";
12116
+
12117
+ function Slides({ slides }: { slides: SlideSequence }) {
12118
+ const slide = useSequenceTransition(slides, {
12119
+ current: () => slides.current,
12120
+ transition: s => s.direction, // "forward", "back", or undefined for no animation
12121
+ equal: (a, b) => a.id === b.id,
12122
+ });
12123
+ return (
12124
+ <ViewTransition update={{ forward: "slide-forward", back: "slide-back", default: "none" }}>
12125
+ <Slide slide={slide} />
12126
+ </ViewTransition>
12127
+ );
12128
+ }
12129
+ ```
12130
+
12131
+
12132
+ ## Signatures
12133
+
12134
+ ```ts
12135
+ useSequenceTransition(sequence: AsyncIterable<T>, options: SequenceTransitionOptions<T>): T
12136
+ ```
12137
+
12138
+ ## Parameters
12139
+
12140
+ | Param | Type | Description |
12141
+ | --- | --- | --- |
12142
+ | `sequence` | `AsyncIterable<T>` | An object implementing the `AsyncIterable` interface. - Subscription is recreated every time this value changes. - Memoise this value to persist the subscription for the lifetime of the component. |
12143
+ | `options` | `SequenceTransitionOptions<T>` | |
12144
+ | `.current` | `() => T` | Read the current value. - Called for the first render, and again when the subscription starts, to catch up on values sent before it started. Read only. |
12145
+ | `.transition` | `string \| ((value: T) => string \| null \| undefined) \| undefined` | Transition type for a value, or a fixed type for every value. - A value with a type is set inside `startTransition()` with that type, so a `<ViewTransition>` can animate it. - A value with no type (`undefined` or `null`) is set at once, with no transition. Read only. Optional. |
12146
+ | `.equal` | `((a: T, b: T) => boolean) \| undefined` | Is a new value the same as the shown value? A value that is the same is skipped, so it starts no second transition. Read only. Defaults to `Object.is`. |
12147
+
12148
+ ## Returns
12149
+
12150
+ | Type | Description |
12151
+ | --- | --- |
12152
+ | `T` | The value shown now. |
12153
+
12154
+ ## Throws
12155
+
12156
+ | Type | Description |
12157
+ | --- | --- |
12158
+ | `unknown` | unknown Re-throws (during render) any error thrown by the sequence, for an error boundary to catch. |
12159
+
12160
+
12057
12161
  ---
12058
12162
 
12059
12163
  # useStore()
@@ -20521,7 +20625,7 @@ The components below are listed in the index following this page; this is the sh
20521
20625
  - [requireMetaURL()](ui/requireMetaURL.md): Read the current Meta context and derive URL helpers (path and params) from its url.
20522
20626
  - [getTagClass()](ui/getTagClass.md): Build the combined className string for a <Tag> from its styling variants.
20523
20627
  - [Message()](ui/Message.md): Status-coloured paragraph used for inline feedback messages.
20524
- - [requireNavigation()](ui/requireNavigation.md): Read the current NavigationStore from context, throwing if used outside <Navigation>.
20628
+ - [requireNavigation()](ui/requireNavigation.md): Read the current NavigationSequence from context, throwing if used outside <Navigation>.
20525
20629
  - [getBlockClass()](ui/getBlockClass.md): Get the combined className string for a block from its styling variants.
20526
20630
  - [getColorClass()](ui/getColorClass.md): CSS class that applies color tinting to an element.
20527
20631
  - [getDurationClass()](ui/getDurationClass.md): Get the transition-duration class for a component from its duration variant prop.
@@ -20580,7 +20684,7 @@ The components below are listed in the index following this page; this is the sh
20580
20684
  - [FormStore](ui/FormStore.md): Reactive store holding the current (possibly partial and invalid) value of a form, plus its field messages.
20581
20685
  - [NoticesStore](ui/NoticesStore.md): Store holding the live list of NoticeStore notices currently shown.
20582
20686
  - [NoticeStore](ui/NoticeStore.md): Store holding a single notice's content and status, owned by a NoticesStore.
20583
- - [NavigationStore](ui/NavigationStore.md): Store that holds the current navigation URL, drives browser history, and keeps a stack of pages for each tab.
20687
+ - [NavigationSequence](ui/NavigationSequence.md): Sequence of navigation events that drives browser history and keeps a stack of pages for each tab.
20584
20688
 
20585
20689
  ## Interfaces
20586
20690
 
@@ -20717,8 +20821,8 @@ The components below are listed in the index following this page; this is the sh
20717
20821
  - [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
20718
20822
  - [BackButtonProps](ui/BackButtonProps.md): Props for <BackButton>: the href to go back to when the stack has no page before this one, plus the usual Button props except onClick.
20719
20823
  - [NavigationProps](ui/NavigationProps.md): Props for <Navigation>: the initial Meta (url, root and stack), the stacks, and optional children.
20720
- - [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationStore saves on each browser history entry.
20721
- - [NavigationPosition](ui/NavigationPosition.md): 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.
20824
+ - [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationSequence saves on each browser history entry.
20825
+ - [NavigationEvent](ui/NavigationEvent.md): One change of page, published by NavigationSequence.
20722
20826
  - [RouteCacheProps](ui/RouteCacheProps.md): Props for <RouteCache>: the maxCached size and the content children to keep alive for each page in the stacks.
20723
20827
  - [RouterProps](ui/RouterProps.md): Props for <Router> — the routes to match against plus an optional fallback.
20724
20828
  - [StackButtonProps](ui/StackButtonProps.md): Props for <StackButton>: the stack it opens, plus the usual Button props except href and onClick.
@@ -20774,6 +20878,7 @@ The components below are listed in the index following this page; this is the sh
20774
20878
  - [TextFormatter](ui/TextFormatter.md): Formats a string for display in a text input.
20775
20879
  - [Mapping](ui/Mapping.md): Dispatch table from a JSX.IntrinsicElements key to a renderer component.
20776
20880
  - [NoticesPosition](ui/NoticesPosition.md): Place on the screen where <Notices> shows the list of notices: a corner, or the centre of the top or bottom edge.
20881
+ - [NavigationDirection](ui/NavigationDirection.md): Direction of a move in a NavigationEvent: "forward" or "back".
20777
20882
  - [RouteProps](ui/RouteProps.md): Props for a component that works as a route in the router.
20778
20883
  - [RouteComponent](ui/RouteComponent.md): React component usable as a route value — a function or class component accepting RouteProps.
20779
20884
  - [Route](ui/Route.md): Valid route values:
@@ -20823,8 +20928,7 @@ The components below are listed in the index following this page; this is the sh
20823
20928
  - [EMPTY_LOADING](ui/EMPTY_LOADING.md): Loading spinner in an <Empty>, for a list or form that is still loading. The empty message replaces it in the same place.
20824
20929
  - [LOADING_NOTICE](ui/LOADING_NOTICE.md): Shared loading <Notice> element showing the loading spinner.
20825
20930
  - [NOTICES](ui/NOTICES.md): Global NoticesStore shown by <Notices>, accepting any of the default statuses.
20826
- - [NavigationContext](ui/NavigationContext.md): React context holding the current NavigationStore, provided by <Navigation>.
20827
- - [NavigationPositionContext](ui/NavigationPositionContext.md): React context holding where the app is in its stacks, published by <Navigation> with each URL change.
20931
+ - [NavigationContext](ui/NavigationContext.md): React context holding the current NavigationSequence, provided by <Navigation>.
20828
20932
  - [STATUSES](ui/STATUSES.md): Tuple of the status names selectable via the status variant prop.
20829
20933
  - [TINT_CLASS](ui/TINT_CLASS.md): CSS class that (re)calculates the full ladder of tint shades from the current global tint colour.
20830
20934
  - [FADE_TRANSITION_CLASS](ui/FADE_TRANSITION_CLASS.md): View transition class that fades content in and out.
@@ -22119,6 +22223,9 @@ Props for `Image` — an `src`, optional `alt` text, plus space and width varian
22119
22223
  - Import: `import { Image } from "shelving/ui";`
22120
22224
 
22121
22225
  Image block — renders an `<img>` with space and width variants applied.
22226
+ - It loads `lazy`, and fades in once when it loads. An image that is already loaded when it mounts shows at once.
22227
+ - It never holds a transition (such as a page change): React waits only for an eager `<img>` with no `onLoad`.
22228
+ - The load state is the `data-loaded` attribute (none, `fade`, then `done`), set on the element directly, so a load never re-renders.
22122
22229
 
22123
22230
  ## Signatures
22124
22231
 
@@ -33074,7 +33181,7 @@ close(): void
33074
33181
  Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
33075
33182
  - Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
33076
33183
  - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
33077
- - When the meta `url` differs from the browser URL (a page that knows its canonical URL), calls `NavigationStore.replace()` with it. Outside `<Navigation>` it does not touch history.
33184
+ - When the meta `url` differs from the browser URL (a page that knows its canonical URL), calls `NavigationSequence.replace()` with it. It only does this for the page the browser history is on (the same `stack` and `ordinal`), so a page shown ahead of history, such as a swipe-back preview, leaves history alone. Outside `<Navigation>` it does not touch history.
33078
33185
 
33079
33186
  Low-level emitter of hoistable head metadata from the current `Meta` context. It outputs `<title>`, `<meta>`, `<link>`, stylesheet, module, and script elements inline, and React 19 hoists each one into the document `<head>`. It also syncs `window.history` to the page URL.
33080
33187
 
@@ -33316,7 +33423,7 @@ The back button for a page header. It goes back to the page before this one in t
33316
33423
 
33317
33424
  - It goes to the page before this one in the current stack. If you opened a post from a search, it goes back to the search.
33318
33425
  - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. So a back button always has somewhere to go. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
33319
- - It is a plain link with `className="back"`. `<Navigation>` turns a click into `NavigationStore.back()`, so the page slides back. A middle-click opens the link in a new browser tab.
33426
+ - It is a plain link with `className="back"`. `<Navigation>` turns a click into `NavigationSequence.back()`, so the page slides back. A middle-click opens the link in a new browser tab.
33320
33427
  - Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
33321
33428
  - It takes the usual `<Button>` props, except `onClick`.
33322
33429
  - Without the browser Navigation API, and in a server render, it links to `href`.
@@ -33414,28 +33521,29 @@ Props for `<Navigation>`: the initial `Meta` (url, root and stack), the `stacks`
33414
33521
  - Import: `import { Navigation } from "shelving/ui";`
33415
33522
 
33416
33523
  Top-level navigation provider, with one stack of pages for each tab.
33417
- - Owns a single `NavigationStore` made from the surrounding `<Meta>` url and root.
33418
- - Turns clicks on same-origin links into `NavigationStore.forward()`, or `NavigationStore.back()` for a link with `className="back"`, or `NavigationStore.replace()` for a link with `className="replace"`. Clicks with a modifier key, or on links with `download` or a `target`, are left to the browser.
33419
- - Publishes the URL and the current `stack` into `Meta`, and the position in the stacks into `NavigationPositionContext`, all in one render.
33420
- - Publishes each change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition. A replace, or a change the browser already animated (for example a swipe-back), has no transition.
33524
+ - Owns a single `NavigationSequence` made from the surrounding `<Meta>` url and root.
33525
+ - Turns clicks on same-origin links into `NavigationSequence.forward()`, or `NavigationSequence.back()` for a link with `className="back"`, or `NavigationSequence.replace()` for a link with `className="replace"`. Clicks with a modifier key, or on links with `download` or a `target`, are left to the browser.
33526
+ - Holds the page it shows in its own state, and publishes its `url`, `stack` and `ordinal` into `Meta`. Read the current page from `Meta`.
33527
+ - Takes each `NavigationEvent` with `useSequenceTransition()`. A move is set inside `startTransition()` with its `"forward"` or `"back"` type, so a `<Transition>` around the routes runs a view transition. A replace has no transition. An event for the page already shown is skipped.
33421
33528
  - Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
33422
33529
 
33423
- Exactly one `<Navigation>` per app. Nested routers share its store.
33530
+ Exactly one `<Navigation>` per app. Nested routers share its sequence.
33424
33531
 
33425
- The top-level navigation provider for a client-side app. It owns one `NavigationStore`, turns link clicks into navigation, and publishes the live URL into `<Meta>`, so each `<Router>` re-renders when the URL changes. Use exactly one `<Navigation>` per app. Nested routers all share its store.
33532
+ The top-level navigation provider for a client-side app. It owns one `NavigationSequence`, turns link clicks into navigation, holds the page it shows in its own state, and publishes that page into `<Meta>`, so each `<Router>` re-renders when the page changes. Use exactly one `<Navigation>` per app. Nested routers all share its sequence.
33426
33533
 
33427
33534
  Give it `stacks` for an app with a tab bar. Each stack is one tab with its own history of pages, like a phone app: each tab remembers where you left it, and a back button goes back within its tab.
33428
33535
 
33429
33536
  **Things to know:**
33430
33537
 
33431
- - Same-origin link clicks become `NavigationStore.forward()`, so the page slides forward.
33432
- - A link with `className="back"` calls `NavigationStore.back()`, so the page slides back. `<BackButton>` sets this class for you.
33433
- - A link with `className="replace"` calls `NavigationStore.replace()`. It changes the URL with no new history entry and no slide, and keeps the same page mounted. Use it for tabs inside a page.
33538
+ - Same-origin link clicks become `NavigationSequence.forward()`, so the page slides forward.
33539
+ - A link with `className="back"` calls `NavigationSequence.back()`, so the page slides back. `<BackButton>` sets this class for you.
33540
+ - A link with `className="replace"` calls `NavigationSequence.replace()`. It changes the URL with no new history entry and no slide, and keeps the same page mounted. Use it for tabs inside a page.
33434
33541
  - Clicks with a modifier key (Cmd, Ctrl, Shift, Alt), a middle-click, and links with `download` or a `target` other than `_self` go to the browser as usual.
33435
- - It publishes each page change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` such as `<HorizontalTransition>` slides the page. A replace has no transition.
33436
- - The browser back and forward buttons slide too. Inside a stack the direction comes from the depth of the page. Across stacks it comes from tab order.
33542
+ - It takes each `NavigationEvent` with `useSequenceTransition()`. A move is set inside `startTransition()` with its `"forward"` or `"back"` transition type, so a `<Transition>` such as `<HorizontalTransition>` slides the page. A replace has no transition. An event for the page already shown is skipped.
33543
+ - The browser back and forward buttons slide too. Inside a stack the direction comes from the ordinal of the page. Across stacks it comes from tab order.
33437
33544
  - When the browser already animated the change (for example a swipe-back on a phone), there is no view transition, so the page does not slide twice.
33438
- - It publishes `stack` (the root of the current stack) into `<Meta>` beside `url`, so any component can read the current tab with `requireMeta().stack`. On a floating page (outside every stack) `stack` is `null`. With no `stacks`, every page floats.
33545
+ - It publishes `url`, `stack` (the root of the current stack) and `ordinal` (the page's place in its stack) into `<Meta>`, so any component can read the page on screen with `requireMeta()`. On a floating page (outside every stack) `stack` is `null`. With no `stacks`, every page floats.
33546
+ - When it starts listening it reads the current history entry, so a `replace()` sent before that (for example from a page's first effect) is not lost.
33439
33547
  - It reads the start URL and root from the surrounding `<Meta>`, so set `url` and `root` on an ancestor `<App>` or `<HTML>`. In the browser the URL falls back to `window.location.href`.
33440
33548
  - `<Router>` works with no `<Navigation>` (server renders, static renders, tests). `<Navigation>` only makes the URL live on the client.
33441
33549
 
@@ -33481,7 +33589,7 @@ const TABS = (
33481
33589
  <App root="https://example.com/">
33482
33590
  <Navigation stacks={STACKS}>
33483
33591
  <AppLayout nav={TABS}>
33484
- <HorizontalTransition>
33592
+ <HorizontalTransition default="none">
33485
33593
  <RouteCache>
33486
33594
  <Scroll vertical cover>
33487
33595
  <PageLoader>
@@ -33506,9 +33614,9 @@ const stack = STACKS.find(s => path === s || path.startsWith(`${s}/`));
33506
33614
  <Navigation stacks={STACKS} stack={stack}>
33507
33615
  ```
33508
33616
 
33509
- Put the transition **outside** `<RouteCache>`, around the whole cache. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
33617
+ Put the transition **outside** `<RouteCache>`, around the whole cache, with no `key`. A page change is an update of the transition, and it slides by type. Set `default="none"`, so a change with no type (a replace) does not animate. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`. The app also works with no `<RouteCache>`: put the transition around the `<Router>`.
33510
33618
 
33511
- The app opens in the `stack` you set on `<Navigation>` (or on the surrounding `<Meta>`, like `url` and `root`), else the page **floats**: its stack is `null`. A floating page, such as a deep link or a login page, is outside every tab: no tab is selected, and links from it stay floating until you tap a tab or name a stack (for example `nav.replace("/home", "/home")` after a login). `/` is a normal stack root, so a Home tab at `/` is never mixed up with floating pages. See `NavigationStore`.
33619
+ The app opens in the `stack` you set on `<Navigation>` (or on the surrounding `<Meta>`, like `url` and `root`), else the page **floats**: its stack is `null`. A floating page, such as a deep link or a login page, is outside every tab: no tab is selected, and links from it stay floating until you tap a tab or name a stack (for example `nav.replace("/home", "/home")` after a login). `/` is a normal stack root, so a Home tab at `/` is never mixed up with floating pages. See `NavigationSequence`.
33512
33620
 
33513
33621
  Each link pushes a new page onto the current stack, wherever it points. So a link from `/home` to `/profile/settings` opens the settings page in the Home tab, and the Profile tab stays where it was. Tap a `<StackButton>` to change tab.
33514
33622
 
@@ -33532,7 +33640,7 @@ Each link pushes a new page onto the current stack, wherever it points. So a lin
33532
33640
 
33533
33641
  ### Imperative navigation
33534
33642
 
33535
- Read the store from anywhere in the tree with `requireNavigation()`:
33643
+ Read the sequence from anywhere in the tree with `requireNavigation()`:
33536
33644
 
33537
33645
  ```tsx
33538
33646
  import { requireNavigation } from "shelving/ui";
@@ -33543,7 +33651,7 @@ nav.back("/home"); // Go back to a page.
33543
33651
  nav.replace("/login"); // Change the URL of the current page.
33544
33652
  ```
33545
33653
 
33546
- See `NavigationStore` for what each method does.
33654
+ See `NavigationSequence` for what each method does.
33547
33655
 
33548
33656
 
33549
33657
  ## Signatures
@@ -33574,12 +33682,12 @@ Navigation({ children, stacks = [], ...meta }: NavigationProps): ReactElement
33574
33682
  - Kind: constant
33575
33683
  - Import: `import { NavigationContext } from "shelving/ui";`
33576
33684
 
33577
- React context holding the current `NavigationStore`, provided by `<Navigation>`.
33685
+ React context holding the current `NavigationSequence`, provided by `<Navigation>`.
33578
33686
 
33579
33687
  ## Examples
33580
33688
 
33581
33689
  ```ts
33582
- <NavigationContext value={store}>…</NavigationContext>
33690
+ <NavigationContext value={nav}>…</NavigationContext>
33583
33691
  ```
33584
33692
 
33585
33693
 
@@ -33590,19 +33698,19 @@ React context holding the current `NavigationStore`, provided by `<Navigation>`.
33590
33698
  - Kind: function
33591
33699
  - Import: `import { requireNavigation } from "shelving/ui";`
33592
33700
 
33593
- Read the current `NavigationStore` from context, throwing if used outside `<Navigation>`.
33701
+ Read the current `NavigationSequence` from context, throwing if used outside `<Navigation>`.
33594
33702
 
33595
33703
  ## Signatures
33596
33704
 
33597
33705
  ```ts
33598
- requireNavigation(): NavigationStore
33706
+ requireNavigation(): NavigationSequence
33599
33707
  ```
33600
33708
 
33601
33709
  ## Returns
33602
33710
 
33603
33711
  | Type | Description |
33604
33712
  | --- | --- |
33605
- | `NavigationStore` | The current `NavigationStore`. |
33713
+ | `NavigationSequence` | The current `NavigationSequence`. |
33606
33714
 
33607
33715
  ## Throws
33608
33716
 
@@ -33611,18 +33719,6 @@ requireNavigation(): NavigationStore
33611
33719
  | `unknown` | RequiredError If no `<Navigation>` provider is present above. |
33612
33720
 
33613
33721
 
33614
- ---
33615
-
33616
- # NavigationPositionContext
33617
-
33618
- - Kind: constant
33619
- - Import: `import { NavigationPositionContext } from "shelving/ui";`
33620
-
33621
- React context holding where the app is in its stacks, published by `<Navigation>` with each URL change.
33622
- - `undefined` without the browser Navigation API, during a server render, or outside `<Navigation>`.
33623
- - `<RouteCache>`, `<Router>` and `<BackButton>` read it, so they change in the same render as the URL.
33624
-
33625
-
33626
33722
  ---
33627
33723
 
33628
33724
  # NavigationEntryState
@@ -33630,14 +33726,14 @@ React context holding where the app is in its stacks, published by `<Navigation>
33630
33726
  - Kind: interface
33631
33727
  - Import: `import { NavigationEntryState } from "shelving/ui";`
33632
33728
 
33633
- State that `NavigationStore` saves on each browser history entry.
33729
+ State that `NavigationSequence` saves on each browser history entry.
33634
33730
 
33635
33731
  ## Signatures
33636
33732
 
33637
33733
  ```ts
33638
33734
  {
33639
33735
  readonly stack: AbsolutePath | null;
33640
- readonly depth: number;
33736
+ readonly ordinal: number;
33641
33737
  }
33642
33738
  ```
33643
33739
 
@@ -33646,26 +33742,44 @@ State that `NavigationStore` saves on each browser history entry.
33646
33742
  | Property | Type | Description |
33647
33743
  | --- | --- | --- |
33648
33744
  | `stack` | `AbsolutePath \| null` | Root path of the stack this page is in, or `null` for a floating page. Read only. |
33649
- | `depth` | `number` | Position of this page in its stack, where `0` is the root. Read only. |
33745
+ | `ordinal` | `number` | Position of this page in its stack, where `0` is the root. Read only. |
33746
+
33747
+
33748
+ ---
33749
+
33750
+ # NavigationDirection
33751
+
33752
+ - Kind: type
33753
+ - Import: `import { NavigationDirection } from "shelving/ui";`
33754
+
33755
+ Direction of a move in a `NavigationEvent`: `"forward"` or `"back"`.
33756
+
33757
+ ## Signatures
33758
+
33759
+ ```ts
33760
+ "forward" | "back"
33761
+ ```
33650
33762
 
33651
33763
 
33652
33764
  ---
33653
33765
 
33654
- # NavigationPosition
33766
+ # NavigationEvent
33655
33767
 
33656
33768
  - Kind: interface
33657
- - Import: `import { NavigationPosition } from "shelving/ui";`
33658
- - Extends: `NavigationEntryState`
33769
+ - Import: `import { NavigationEvent } from "shelving/ui";`
33659
33770
 
33660
- 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.
33661
- - `undefined` when the browser has no Navigation API, or during a server render.
33771
+ One change of page, published by `NavigationSequence`.
33772
+ - A move (a link, a back button, the browser back and forward buttons) has a `direction`, so `<Navigation>` shows it inside a view transition of that type.
33773
+ - A replace has no `direction`, so it shows at once with no transition.
33662
33774
 
33663
33775
  ## Signatures
33664
33776
 
33665
33777
  ```ts
33666
33778
  {
33667
- readonly tops: ReadonlyMap<AbsolutePath | null, number>;
33668
- readonly parent: AbsolutePath | undefined;
33779
+ readonly url: ImmutableURL;
33780
+ readonly stack: AbsolutePath | null;
33781
+ readonly ordinal: number | undefined;
33782
+ readonly direction?: NavigationDirection | undefined;
33669
33783
  }
33670
33784
  ```
33671
33785
 
@@ -33673,50 +33787,58 @@ Where the app is now in its stacks: the current stack and depth, the top depth o
33673
33787
 
33674
33788
  | Property | Type | Description |
33675
33789
  | --- | --- | --- |
33676
- | `tops` | `ReadonlyMap<AbsolutePath \| null, number>` | Depth of the top page of each stack that has pages, including the floating stack (`null`). Read only. |
33677
- | `parent` | `AbsolutePath \| undefined` | The page before the current one in its stack, or `undefined` at the bottom of the stack. Read only. |
33790
+ | `url` | `ImmutableURL` | URL of the page. Read only. |
33791
+ | `stack` | `AbsolutePath \| null` | Root path of the stack the page is in, or `null` for a floating page. Read only. |
33792
+ | `ordinal` | `number \| undefined` | Position of the page in its stack, where `0` is the root, or `undefined` without the Navigation API. Read only. |
33793
+ | `direction` | `NavigationDirection \| undefined` | Direction of the move, or `undefined` for a replace or a change with no slide. Read only. Optional. |
33678
33794
 
33679
33795
 
33680
33796
  ---
33681
33797
 
33682
- # NavigationStore
33798
+ # NavigationSequence
33683
33799
 
33684
33800
  - Kind: class
33685
- - Import: `import { NavigationStore } from "shelving/ui";`
33686
- - Extends: `URLStore`
33801
+ - Import: `import { NavigationSequence } from "shelving/ui";`
33802
+ - Extends: `DeferredSequence<NavigationEvent>`
33687
33803
 
33688
- Store that holds the current navigation URL, drives browser history, and keeps a stack of pages for each tab.
33804
+ Sequence of navigation events that drives browser history and keeps a stack of pages for each tab.
33689
33805
 
33690
- - Extends `URLStore`, so its `value` is the current URL.
33806
+ - It is not a store: it holds no "current page" for the UI. Each change of page (a move, a replace, or the browser back and forward buttons) publishes one `NavigationEvent`, and `<Navigation>` keeps the page it shows in its own state.
33807
+ - `url`, `stack` and `ordinal` say where the browser history is now. The page on screen can differ for a moment, for example during a swipe-back preview. To read the page on screen, read `Meta`.
33808
+ - `publish()` sends an event by hand, for example to show the page below during a swipe-back.
33691
33809
  - 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.
33692
- - `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.
33693
33810
  - A page outside the listed stacks is floating: its stack is `null`. The floating stack has no root page and no tab.
33694
- - In a listed stack, depth `0` is always the stack's root path.
33811
+ - In a listed stack, ordinal `0` is always the stack's root path.
33695
33812
  - 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.
33696
33813
  - Owned by `<Navigation>`. Read it with `requireNavigation()`.
33697
33814
 
33698
- The store that holds the current URL, drives browser history, and keeps one stack of pages for each tab. It extends `URLStore`, so its `value` is the current URL. `<Navigation>` owns it. Read it with `requireNavigation()`, and do not make your own.
33815
+ The sequence of navigation events that drives browser history and keeps one stack of pages for each tab. It is not a store: it holds no "current page" for the UI. Each change of page publishes one `NavigationEvent`, and `<Navigation>` keeps the page it shows in its own state. `<Navigation>` owns it. Read it with `requireNavigation()`, and do not make your own.
33699
33816
 
33700
33817
  **Things to know:**
33701
33818
 
33702
- - `NavigationStore.stacks` is the root path of each stack, in tab order, from the `stacks` prop on `<Navigation>`. `/` is a normal stack root, like any other path.
33819
+ - Each change of page (a link, a back button, a replace, or the browser back and forward buttons) publishes one `NavigationEvent`: `{ url, stack, ordinal, direction }`.
33820
+ - A move has a `direction` (`"forward"` or `"back"`), so `<Navigation>` shows it in a view transition of that type. A replace has no `direction`, so it shows at once.
33821
+ - To read the page on screen, read `Meta` (`requireMeta()` or `requireMetaURL()`), not the sequence. The two can differ for a moment, for example during a swipe-back.
33822
+ - `NavigationSequence.url`, `NavigationSequence.stack` and `NavigationSequence.path` say where the browser history is now. `NavigationSequence.current()` returns the same as an event with no direction.
33823
+ - `NavigationSequence.stacks` is the root path of each stack, in tab order, from the `stacks` prop on `<Navigation>`. `/` is a normal stack root, like any other path.
33703
33824
  - A page that is not in a listed stack is **floating**: its stack is `null`. See [Floating pages](#floating-pages).
33704
- - In a listed stack, depth `0` is always the stack's root path. A deeper page always has the root below it.
33705
- - `NavigationStore.stack` is a sub-store that holds the root of the current stack, or `null` on a floating page. It changes only when the stack changes, so `useStore(nav.stack)` re-renders only on a tab change.
33706
- - `NavigationStore.path` is the current path relative to the app root, without its `?query`.
33707
- - `NavigationStore.history()` returns the pages in the current stack (or a given stack), root first.
33708
- - `NavigationStore.position` is the current stack and depth, the depth of the top page of each stack, and the page before this one. `<RouteCache>` and `<BackButton>` use it.
33709
- - All URLs resolve against the store's `base`. Each method also takes a full same-origin URL.
33710
- - Without the browser Navigation API there is no stack history: `stack` stays the starting stack, `history()` returns `[]`, `position` is `undefined`, and every `stack` argument is ignored. `forward()` and `back()` push a history entry, and `replace()` replaces it.
33825
+ - In a listed stack, ordinal `0` is always the stack's root path. A deeper page always has the root below it.
33826
+ - `NavigationSequence.history()` returns the pages in the current stack (or a given stack), root first.
33827
+ - `NavigationSequence.publish()` sends an event by hand, for example to show the page below during a swipe-back. It returns a promise that resolves when `<Navigation>` has committed the event.
33828
+ - Events sent in the same microtask merge: only the last one is shown.
33829
+ - All URLs resolve against the sequence's `base`. Each method also takes a full same-origin URL.
33830
+ - Without the browser Navigation API there is no stack history: `stack` stays the starting stack, `history()` returns `[]`, `ordinal` is `undefined`, and every `stack` argument is ignored. `forward()` and `back()` push a history entry, and `replace()` replaces it.
33711
33831
 
33712
33832
  ## Methods
33713
33833
 
33714
- | Method | What it does | Slide |
33715
- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
33716
- | `forward(href, stack?)` | Opens `href` as a new page on top of the stack. If `href` is the top page of another stack, it switches to that stack (a tab switch). If `href` is the current URL, it is a replace. | Forward. Across stacks, by tab order. |
33717
- | `back(href, stack?)` | Goes back to `href`. If `href` is in the stack, the stack goes back to it, and the pages above it leave the stack. If `href` is the root of the stack, the stack goes to its root. Otherwise `href` takes the place of the top page of the stack. | Back |
33718
- | `replace(href, stack?)` | Changes the URL of the current page. The stack, the depth and the mounted page stay the same. No new history entry. With another `stack`, the page moves into that stack: at its root if `href` is the root, else on top of its pages. | None |
33719
- | `history(stack?)` | Returns the pages in `stack`, root first. | — |
33834
+ | Method | What it does | Slide |
33835
+ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
33836
+ | `forward(href, stack?)` | Opens `href` as a new page on top of the stack. If `href` is the top page of another stack, it switches to that stack (a tab switch). If `href` is the current URL, it is a replace. | Forward. Across stacks, by tab order. |
33837
+ | `back(href, stack?)` | Goes back to `href`. If `href` is in the stack, the stack goes back to it, and the pages above it leave the stack. If `href` is the root of the stack, the stack goes to its root. Otherwise `href` takes the place of the top page of the stack. If the browser refuses the Navigation API back, it uses `history.back()`. | Back |
33838
+ | `replace(href, stack?)` | Changes the URL of the current page. The stack, the ordinal and the mounted page stay the same. No new history entry. With another `stack`, the page moves into that stack: at its root if `href` is the root, else on top of its pages. | None |
33839
+ | `history(stack?)` | Returns the pages in `stack`, root first. | — |
33840
+ | `current()` | Returns where the browser history is now, as an event with no direction. | — |
33841
+ | `publish(event)` | Sends an event by hand. Resolves when `<Navigation>` has committed it. | The event's `direction` |
33720
33842
 
33721
33843
  `stack` defaults to the current stack. Pass `null` to name the floating stack.
33722
33844
 
@@ -33733,7 +33855,7 @@ A page changes stack only when you say so: with a `<StackButton>`, or with a `st
33733
33855
  ## Opening the app
33734
33856
 
33735
33857
  - To select a tab when the app starts, set `stack` on `<Navigation>`. The app decides which stack the opening URL belongs to. After a reload, each history entry keeps the stack it had.
33736
- - A deep page the app opens at, in a listed stack, starts at depth 1, so the stack root is its parent. A `<StackButton>` or a back gesture then goes to the root. A stack root starts at depth 0.
33858
+ - A deep page the app opens at, in a listed stack, starts at ordinal 1, so the stack root is its parent. A `<StackButton>` or a back gesture then goes to the root. A stack root starts at ordinal 0.
33737
33859
  - A `stack` that is not in `stacks` is ignored: the page floats.
33738
33860
 
33739
33861
  For example, a login page sends the user home after they log in, and names the Home stack:
@@ -33745,23 +33867,23 @@ nav.replace("/home", "/home");
33745
33867
 
33746
33868
  ## How stacks work
33747
33869
 
33748
- The store saves a small state on each browser history entry: the `stack` the page is in, and its `depth` in that stack (`0` is the root). See `NavigationEntryState`. To read a stack, the store walks back through the browser history from the current entry. It takes the newest entry in that stack, then the newest earlier entry with a lower depth, and so on down to depth `0`.
33870
+ The sequence saves a small state on each browser history entry: the `stack` the page is in, and its `ordinal` in that stack (`0` is the root). See `NavigationEntryState`. To read a stack, the sequence walks back through the browser history from the current entry. It takes the newest entry in that stack, then the newest earlier entry with a lower ordinal, and so on down to ordinal `0`.
33749
33871
 
33750
- Why depth? A browser history entry cannot be changed or removed. So when you go back in one stack while another stack's pages are after it in the history, the store cannot go back in the browser. It pushes a new entry for the page you went back to, at that page's depth. The pages that were above it now have a higher depth than the newest entry, so they are no longer in the stack.
33872
+ Why ordinal? A browser history entry cannot be changed or removed. So when you go back in one stack while another stack's pages are after it in the history, the sequence cannot go back in the browser. It pushes a new entry for the page you went back to, at that page's ordinal. The pages that were above it now have a higher ordinal than the newest entry, so they are no longer in the stack.
33751
33873
 
33752
33874
  For example, with tabs `/home` and `/profile`:
33753
33875
 
33754
- | Step | New history entry | Home stack | Profile stack |
33755
- | ------------------- | ------------------------ | ----------------------- | ------------- |
33756
- | Start at `/home` | `/home` (depth 0) | `/home` | — |
33757
- | Open a post | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | — |
33758
- | Tap the Profile tab | `/profile` (depth 0) | `/home`, `/home/post/1` | `/profile` |
33759
- | Tap the Home tab | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | `/profile` |
33760
- | Tap the back button | `/home` (depth 0) | `/home` | `/profile` |
33876
+ | Step | New history entry | Home stack | Profile stack |
33877
+ | ------------------- | -------------------------- | ----------------------- | ------------- |
33878
+ | Start at `/home` | `/home` (ordinal 0) | `/home` | — |
33879
+ | Open a post | `/home/post/1` (ordinal 1) | `/home`, `/home/post/1` | — |
33880
+ | Tap the Profile tab | `/profile` (ordinal 0) | `/home`, `/home/post/1` | `/profile` |
33881
+ | Tap the Home tab | `/home/post/1` (ordinal 1) | `/home`, `/home/post/1` | `/profile` |
33882
+ | Tap the back button | `/home` (ordinal 0) | `/home` | `/profile` |
33761
33883
 
33762
33884
  When the page you go back to is the entry just before the current one, `back()` goes back in the browser history and pushes nothing.
33763
33885
 
33764
- The browser back and forward buttons walk the history entries one at a time, as usual. Each entry knows its stack and depth, so the stacks are always right and the slide goes the right way.
33886
+ The browser back and forward buttons walk the history entries one at a time, as usual. Each entry knows its stack and ordinal, so the stacks are always right and the slide goes the right way.
33765
33887
 
33766
33888
  ## Usage
33767
33889
 
@@ -33774,19 +33896,33 @@ function LogoutButton() {
33774
33896
  }
33775
33897
  ```
33776
33898
 
33777
- Read the current stack in a component:
33899
+ Read the current stack in a component from `Meta`:
33778
33900
 
33779
33901
  ```tsx
33780
- import { useStore } from "shelving/react";
33781
- import { requireNavigation } from "shelving/ui";
33902
+ import { requireMeta } from "shelving/ui";
33782
33903
 
33783
33904
  function TabTitle() {
33784
- const nav = requireNavigation();
33785
- const stack = useStore(nav.stack).value;
33905
+ const { stack } = requireMeta();
33786
33906
  return <h1>{stack === "/profile" ? "Profile" : "Home"}</h1>;
33787
33907
  }
33788
33908
  ```
33789
33909
 
33910
+ Show the page below during a swipe-back. React runs the back transition, and the swipe scrubs it:
33911
+
33912
+ ```tsx
33913
+ const nav = requireNavigation();
33914
+ const { stack = null, ordinal } = requireMetaURL();
33915
+ const parent = ordinal ? nav.history(stack)[ordinal - 1] : undefined;
33916
+ if (parent) {
33917
+ // Start the swipe: show the page below with the back transition.
33918
+ await nav.publish({ url: requireURL(parent, nav.base), stack, ordinal: ordinal - 1, direction: "back" });
33919
+ // Release: go back for real. It publishes the same page, so it is skipped.
33920
+ nav.back(parent);
33921
+ // Or cancel: show the old page again, with no transition.
33922
+ // await nav.publish({ ...from, direction: undefined });
33923
+ }
33924
+ ```
33925
+
33790
33926
  List the pages in a stack (for example, for breadcrumbs):
33791
33927
 
33792
33928
  ```tsx
@@ -33794,13 +33930,13 @@ const nav = requireNavigation();
33794
33930
  nav.history("/home"); // ["/home", "/home/post/1", "/home/post/1/comments"]
33795
33931
  ```
33796
33932
 
33797
- Make a store by hand only in tests:
33933
+ Make a sequence by hand only in tests:
33798
33934
 
33799
33935
  ```tsx
33800
- import { NavigationStore } from "shelving/ui";
33936
+ import { NavigationSequence } from "shelving/ui";
33801
33937
 
33802
33938
  // URL, root, starting stack, then the stacks in tab order.
33803
- const nav = new NavigationStore("https://example.com/home", "https://example.com/", "/home", "/home", "/profile");
33939
+ const nav = new NavigationSequence("https://example.com/home", "https://example.com/", "/home", "/home", "/profile");
33804
33940
  nav.forward("/home/post/1");
33805
33941
  ```
33806
33942
 
@@ -33808,7 +33944,7 @@ nav.forward("/home/post/1");
33808
33944
  ## Signatures
33809
33945
 
33810
33946
  ```ts
33811
- new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL, stack: AbsolutePath | null = null, ...stacks: AbsolutePath[])
33947
+ new NavigationSequence(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL, stack: AbsolutePath | null = null, ...stacks: AbsolutePath[])
33812
33948
  ```
33813
33949
 
33814
33950
  ## Parameters
@@ -33824,36 +33960,91 @@ new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : win
33824
33960
 
33825
33961
  | Type | Description |
33826
33962
  | --- | --- |
33827
- | `NavigationStore` | |
33963
+ | `NavigationSequence` | |
33828
33964
 
33829
33965
  ## Properties
33830
33966
 
33831
33967
  | Property | Type | Description |
33832
33968
  | --- | --- | --- |
33833
33969
  | `stacks` | `readonly AbsolutePath[]` | Root path of each stack, in tab order. With none, every page floats. Read only. |
33834
- | `stack` | `Store<AbsolutePath \| null>` | Root path of the current stack, or `null` for a floating page. - It starts at the `stack` given to the constructor (default `null`). Without the Navigation API, it stays there. Read only. |
33835
- | `transition` | `TransitionType \| null` | Transition type of the most recent change, read by `<Navigation>` when the value changes. - `null` means no transition: a replace, a change the browser already animated (for example a swipe-back), or no Navigation API. Defaults to `null`. |
33970
+ | `base` | `ImmutableURL \| undefined` | Base URL of the app, used to resolve relative URLs and to work out paths. Read only. |
33971
+ | `url` | `ImmutableURL` | URL the browser history is on now. Read only. |
33972
+ | `stack` | `AbsolutePath \| null` | Root path of the stack the browser history is on now, or `null` for a floating page. Read only. |
33836
33973
  | `path` | `AbsolutePath \| undefined` | Path of the current URL relative to the app root (without its `?query`), or `undefined` if the URL is outside the app. Read only. |
33837
- | `position` | `NavigationPosition \| undefined` | Where the app is now: the current stack and depth, and the top depth of each stack. Read only. |
33838
33974
 
33839
33975
  ## Methods
33840
33976
 
33841
- - [NavigationStore.listen()](ui/NavigationStore/listen.md): Start listening to the browser (back, forward and swipe).
33842
- - [NavigationStore.history()](ui/NavigationStore/history.md): Get the pages in a stack, root first, or every page in every stack.
33843
- - [NavigationStore.forward()](ui/NavigationStore/forward.md): Go forward to a URL, as a link does.
33844
- - [NavigationStore.back()](ui/NavigationStore/back.md): Go back to a URL, as a back button does.
33845
- - [NavigationStore.replace()](ui/NavigationStore/replace.md): Replace the current URL, with no transition.
33977
+ - [NavigationSequence.current()](ui/NavigationSequence/current.md): Where the browser history is now, as an event with no direction.
33978
+ - [NavigationSequence.publish()](ui/NavigationSequence/publish.md): Publish an event by hand, without changing history.
33979
+ - [NavigationSequence.committed()](ui/NavigationSequence/committed.md): Tell waiting publish() calls that <Navigation> has committed a page.
33980
+ - [NavigationSequence.listen()](ui/NavigationSequence/listen.md): Start listening to the browser (back, forward and swipe).
33981
+ - [NavigationSequence.history()](ui/NavigationSequence/history.md): Get the pages in a stack, root first, or every page in every stack.
33982
+ - [NavigationSequence.forward()](ui/NavigationSequence/forward.md): Go forward to a URL, as a link does.
33983
+ - [NavigationSequence.back()](ui/NavigationSequence/back.md): Go back to a URL, as a back button does.
33984
+ - [NavigationSequence.replace()](ui/NavigationSequence/replace.md): Replace the current URL, with no transition.
33985
+
33986
+
33987
+ ---
33988
+
33989
+ # NavigationSequence.current()
33990
+
33991
+ - Kind: method
33992
+ - Member of: `NavigationSequence`
33993
+
33994
+ Where the browser history is now, as an event with no direction.
33995
+ - `<Navigation>` reads it for its first render, and again when it starts listening, to catch up on changes it missed.
33996
+
33997
+ ## Signatures
33998
+
33999
+ ```ts
34000
+ current(): NavigationEvent
34001
+ ```
34002
+
34003
+
34004
+ ---
34005
+
34006
+ # NavigationSequence.publish()
34007
+
34008
+ - Kind: method
34009
+ - Member of: `NavigationSequence`
34010
+
34011
+ Publish an event by hand, without changing history.
34012
+ - For example, a swipe-back publishes the page below with `direction: "back"`, so React runs its back transition, and the swipe scrubs it.
34013
+ - Then the real `back()` publishes the same page again, which `<Navigation>` skips, or the swipe publishes the current page again to cancel.
34014
+
34015
+ ## Signatures
34016
+
34017
+ ```ts
34018
+ publish(event: NavigationEvent): Promise<void>
34019
+ ```
34020
+
34021
+
34022
+ ---
34023
+
34024
+ # NavigationSequence.committed()
34025
+
34026
+ - Kind: method
34027
+ - Member of: `NavigationSequence`
34028
+
34029
+ Tell waiting `publish()` calls that `<Navigation>` has committed a page.
34030
+ - `<Navigation>` calls it after each commit.
34031
+
34032
+ ## Signatures
34033
+
34034
+ ```ts
34035
+ committed(): void
34036
+ ```
33846
34037
 
33847
34038
 
33848
34039
  ---
33849
34040
 
33850
- # NavigationStore.listen()
34041
+ # NavigationSequence.listen()
33851
34042
 
33852
34043
  - Kind: method
33853
- - Member of: `NavigationStore`
34044
+ - Member of: `NavigationSequence`
33854
34045
 
33855
34046
  Start listening to the browser (back, forward and swipe).
33856
- - Saves the current stack and depth on the current history entry, if it has none.
34047
+ - Saves the current stack and ordinal on the current history entry, if it has none.
33857
34048
  - `<Navigation>` calls it once, when it mounts.
33858
34049
 
33859
34050
  ## Signatures
@@ -33865,10 +34056,10 @@ listen(): () => void
33865
34056
 
33866
34057
  ---
33867
34058
 
33868
- # NavigationStore.history()
34059
+ # NavigationSequence.history()
33869
34060
 
33870
34061
  - Kind: method
33871
- - Member of: `NavigationStore`
34062
+ - Member of: `NavigationSequence`
33872
34063
 
33873
34064
  Get the pages in a stack, root first, or every page in every stack.
33874
34065
  - Read from the browser history entries up to the current one.
@@ -33879,19 +34070,19 @@ Get the pages in a stack, root first, or every page in every stack.
33879
34070
  ## Signatures
33880
34071
 
33881
34072
  ```ts
33882
- history(stack: AbsolutePath | null = this.stack.value): AbsolutePath[]
34073
+ history(stack: AbsolutePath | null = this._stack): AbsolutePath[]
33883
34074
  ```
33884
34075
 
33885
34076
 
33886
34077
  ---
33887
34078
 
33888
- # NavigationStore.forward()
34079
+ # NavigationSequence.forward()
33889
34080
 
33890
34081
  - Kind: method
33891
- - Member of: `NavigationStore`
34082
+ - Member of: `NavigationSequence`
33892
34083
 
33893
34084
  Go forward to a URL, as a link does.
33894
- - The URL is the top page of `stack`: switch to that stack, at the same depth. This is a tab switch.
34085
+ - The URL is the top page of `stack`: switch to that stack, at the same ordinal. This is a tab switch.
33895
34086
  - Else push the URL onto `stack`, one level deeper than its top page.
33896
34087
  - The URL you are already on: replace it instead.
33897
34088
  - A change of stack slides by tab order. Else it slides forward.
@@ -33899,46 +34090,47 @@ Go forward to a URL, as a link does.
33899
34090
  ## Signatures
33900
34091
 
33901
34092
  ```ts
33902
- forward(possible: PossibleURL, stack: AbsolutePath | null = this.stack.value): void
34093
+ forward(possible: PossibleURL, stack: AbsolutePath | null = this._stack): void
33903
34094
  ```
33904
34095
 
33905
34096
 
33906
34097
  ---
33907
34098
 
33908
- # NavigationStore.back()
34099
+ # NavigationSequence.back()
33909
34100
 
33910
34101
  - Kind: method
33911
- - Member of: `NavigationStore`
34102
+ - Member of: `NavigationSequence`
33912
34103
 
33913
34104
  Go back to a URL, as a back button does.
33914
- - The URL is an earlier page in `stack`: go back to it. When it is the entry just before the current one, this goes back in the browser history. Else it pushes the URL again at that page's depth.
33915
- - The URL is the root of `stack`: push it at depth 0.
34105
+ - The URL is an earlier page in `stack`: go back to it. When it is the entry just before the current one, this goes back in the browser history. Else it pushes the URL again at that page's ordinal.
34106
+ - The URL is the root of `stack`: push it at ordinal 0.
33916
34107
  - Else push the URL in place of the top page of `stack`.
33917
34108
  - It works when the app was opened at the current page, so a back button always has somewhere to go.
34109
+ - If the browser refuses to go back with the Navigation API, it uses `history.back()`.
33918
34110
 
33919
34111
  ## Signatures
33920
34112
 
33921
34113
  ```ts
33922
- back(possible: PossibleURL, stack: AbsolutePath | null = this.stack.value): void
34114
+ back(possible: PossibleURL, stack: AbsolutePath | null = this._stack): void
33923
34115
  ```
33924
34116
 
33925
34117
 
33926
34118
  ---
33927
34119
 
33928
- # NavigationStore.replace()
34120
+ # NavigationSequence.replace()
33929
34121
 
33930
34122
  - Kind: method
33931
- - Member of: `NavigationStore`
34123
+ - Member of: `NavigationSequence`
33932
34124
 
33933
34125
  Replace the current URL, with no transition.
33934
- - The page stays in the same stack, at the same depth, so a cached page stays mounted.
34126
+ - The page stays in the same stack, at the same ordinal, so a cached page stays mounted.
33935
34127
  - Use it for a page that knows its canonical URL, or for in-page tabs.
33936
34128
  - 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")`.
33937
34129
 
33938
34130
  ## Signatures
33939
34131
 
33940
34132
  ```ts
33941
- replace(possible: PossibleURL, stack: AbsolutePath | null = this.stack.value): void
34133
+ replace(possible: PossibleURL, stack: AbsolutePath | null = this._stack): void
33942
34134
  ```
33943
34135
 
33944
34136
 
@@ -33964,7 +34156,7 @@ Props for `<RouteCache>`: the `maxCached` size and the content `children` to kee
33964
34156
 
33965
34157
  | Property | Type | Description |
33966
34158
  | --- | --- | --- |
33967
- | `maxCached` | `number \| undefined` | 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. - 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. - Floating pages get no such protection. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
34159
+ | `maxCached` | `number \| undefined` | 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. - 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. - Floating pages get no such protection. - Keep it at `2` or more, so a swipe-back can show the page below and still keep the page you are leaving. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
33968
34160
  | `children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
33969
34161
 
33970
34162
 
@@ -33978,14 +34170,14 @@ Props for `<RouteCache>`: the `maxCached` size and the content `children` to kee
33978
34170
  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.
33979
34171
 
33980
34172
  - Put a page transition around it, and a `<Scroll vertical cover>` inside it, so each kept page scrolls in its own box.
33981
- - 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.
33982
- - 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.
33983
- - 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.
33984
- - 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.
34173
+ - 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.
34174
+ - 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.
34175
+ - 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.
34176
+ - The root page and the last page you saw in each listed stack are never dropped. Floating pages (stack `null`) get no such protection.
33985
34177
  - 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.
33986
- - 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.
34178
+ - 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.
33987
34179
  - `<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.
33988
- - Without the browser Navigation API (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
34180
+ - With no `ordinal` in `Meta` (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
33989
34181
 
33990
34182
  A keep-alive cache for the pages in the navigation stacks. Put it in a layout's content slot, around a `<Scroll vertical cover>` box. It keeps each page in the stacks mounted but hidden (with React's [`<Activity>`](https://react.dev/reference/react/Activity)), so when you go back to a page, or switch back to a tab, the page is exactly as you left it: scroll position, toggles, searches, form input and focus.
33991
34183
 
@@ -33993,21 +34185,22 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
33993
34185
 
33994
34186
  **Things to know:**
33995
34187
 
33996
- - Each page is keyed by its stack and its depth in that stack, not by its URL. See `NavigationStore` for how stacks work.
33997
- - 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.
33998
- - 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.
33999
- - 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.
34188
+ - Each page is keyed by the `stack` and `ordinal` in `Meta`, not by its URL. See `NavigationSequence` for how stacks work.
34189
+ - 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.
34190
+ - So after a back, the forward button shows the page as you left it, while the cache has room.
34191
+ - 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.
34192
+ - Keep `maxCached` at `2` or more, so a swipe-back can show the page below and still keep the page you are leaving.
34000
34193
  - 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.
34001
- - `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}>`.
34194
+ - `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}>`.
34002
34195
  - The same URL open in two stacks is two separate pages.
34003
34196
  - 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).
34004
- - Each kept page is frozen under its own `<Meta>` and `NavigationPositionContext`, so a hidden page never re-renders for another page's URL.
34197
+ - Each kept page is frozen under its own `<Meta>`, so a hidden page never re-renders for another page's URL.
34005
34198
  - `<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.
34006
34199
  - **Nesting:** layout, then transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. See the usage below.
34007
34200
  - 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.
34008
34201
  - Put a page `<Transition>` **around** the `<RouteCache>`, not inside it. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
34009
34202
  - 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.
34010
- - Without the browser Navigation API, or with `maxCached={0}`, there is no cache: the current page renders directly and unmounts when you leave it.
34203
+ - 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.
34011
34204
 
34012
34205
  ## Usage
34013
34206
 
@@ -34015,7 +34208,7 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
34015
34208
  import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
34016
34209
 
34017
34210
  <AppLayout nav={<StackBar />}>
34018
- <HorizontalTransition>
34211
+ <HorizontalTransition default="none">
34019
34212
  <RouteCache>
34020
34213
  <Scroll vertical cover>
34021
34214
  <PageLoader>
@@ -34074,7 +34267,7 @@ RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode
34074
34267
  | Param | Type | Description |
34075
34268
  | --- | --- | --- |
34076
34269
  | `props` | `RouteCacheProps` | |
34077
- | `.maxCached` | `number \| undefined` | 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. - 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. - Floating pages get no such protection. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
34270
+ | `.maxCached` | `number \| undefined` | 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. - 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. - Floating pages get no such protection. - Keep it at `2` or more, so a swipe-back can show the page below and still keep the page you are leaving. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
34078
34271
  | `.children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
34079
34272
 
34080
34273
  ## Returns
@@ -34123,7 +34316,7 @@ Match the current URL against `routes` and render the matched element.
34123
34316
  - When `base` is set, the effective path is the URL after stripping the base prefix.
34124
34317
  - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
34125
34318
  - 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.
34126
- - 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.
34319
+ - 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.
34127
34320
  - Elsewhere, each path is a new page, so a component route remounts when the path changes.
34128
34321
  - Returns `null` when there's no URL in context or the URL is outside the base.
34129
34322
 
@@ -34135,7 +34328,7 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
34135
34328
  - `<Router>` accepts `PossibleMeta` props (`url`, `base`, etc.) to override the surrounding context — this is how nested routers scope themselves.
34136
34329
  - 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`.
34137
34330
  - Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
34138
- - 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.
34331
+ - 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.
34139
34332
  - `<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.
34140
34333
 
34141
34334
  ## Usage
@@ -36939,7 +37132,7 @@ A direction-aware `<Transition>` preset that slides its children horizontally
36939
37132
  **Things to know:**
36940
37133
 
36941
37134
  - Slides right by default and when the type is `"forward"`; slides left when the type is `"back"`.
36942
- - 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>`.
37135
+ - 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>`.
36943
37136
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
36944
37137
  - The old and new content slide a full width apart, so they sit edge to edge and never overlap.
36945
37138
  - 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.
@@ -37084,7 +37277,7 @@ The base View Transition wrapper. It wraps its children in React 19's `<ViewTran
37084
37277
 
37085
37278
  - 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.
37086
37279
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`, from `Transition.module.css`).
37087
- - 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.
37280
+ - 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.
37088
37281
  - 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.
37089
37282
  - 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.
37090
37283
 
@@ -37349,7 +37542,7 @@ A direction-aware `<Transition>` preset that slides its children vertically —
37349
37542
  **Things to know:**
37350
37543
 
37351
37544
  - Slides down by default and when the type is `"forward"`; slides up when the type is `"back"`.
37352
- - 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>`.
37545
+ - 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>`.
37353
37546
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
37354
37547
  - The old and new content slide a full height apart, so they sit edge to edge and never overlap.
37355
37548
  - 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.
@@ -38423,7 +38616,7 @@ Reads a React context and throws `RequiredError` if the value is `null` or `unde
38423
38616
  ```ts
38424
38617
  import { requireContext } from "shelving/ui";
38425
38618
 
38426
- function requireNavigation(): NavigationStore {
38619
+ function requireNavigation(): NavigationSequence {
38427
38620
  return requireContext(NavigationContext, requireNavigation);
38428
38621
  }
38429
38622
  ```
@@ -38900,6 +39093,7 @@ Combined meta data for a website page — title, URLs, description, CSP, tags, l
38900
39093
  readonly root?: ImmutableURL | undefined;
38901
39094
  readonly url?: ImmutableURL | undefined;
38902
39095
  readonly stack?: AbsolutePath | null | undefined;
39096
+ readonly ordinal?: number | undefined;
38903
39097
  readonly app?: string | undefined;
38904
39098
  readonly title?: string | undefined;
38905
39099
  readonly description?: string | undefined;
@@ -38921,6 +39115,7 @@ Combined meta data for a website page — title, URLs, description, CSP, tags, l
38921
39115
  | `root` | `ImmutableURL \| undefined` | Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). Read only. Optional. |
38922
39116
  | `url` | `ImmutableURL \| undefined` | URL of the current page (used as the initial URL for routing, and as the page's canonical URL in `<Head>`). Read only. Optional. |
38923
39117
  | `stack` | `AbsolutePath \| null \| undefined` | 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. Read only. Optional. |
39118
+ | `ordinal` | `number \| undefined` | 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. Read only. Optional. |
38924
39119
  | `app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
38925
39120
  | `title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
38926
39121
  | `description` | `string \| undefined` | Description of the current page. Read only. Optional. |
@@ -39067,6 +39262,7 @@ mergeMeta(meta1: Meta, meta2: PossibleMeta, caller: AnyCaller = mergeMeta): Meta
39067
39262
  | `.root` | `ImmutableURL \| undefined` | Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). Read only. Optional. |
39068
39263
  | `.url` | `ImmutableURL \| undefined` | URL of the current page (used as the initial URL for routing, and as the page's canonical URL in `<Head>`). Read only. Optional. |
39069
39264
  | `.stack` | `AbsolutePath \| null \| undefined` | 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. Read only. Optional. |
39265
+ | `.ordinal` | `number \| undefined` | 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. Read only. Optional. |
39070
39266
  | `.app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
39071
39267
  | `.title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
39072
39268
  | `.description` | `string \| undefined` | Description of the current page. Read only. Optional. |