shelving 1.323.3 → 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 (79) hide show
  1. package/docs/guides/building-with-shelving.md +3 -3
  2. package/docs/llms-full.txt +342 -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/Meta.md +2 -0
  10. package/docs/ui/Navigation.md +18 -17
  11. package/docs/ui/NavigationContext.md +2 -2
  12. package/docs/ui/NavigationDirection.md +12 -0
  13. package/docs/ui/NavigationEntryState.md +3 -3
  14. package/docs/ui/NavigationEvent.md +28 -0
  15. package/docs/ui/{NavigationStore → NavigationSequence}/back.md +6 -5
  16. package/docs/ui/NavigationSequence/committed.md +13 -0
  17. package/docs/ui/NavigationSequence/current.md +13 -0
  18. package/docs/ui/{NavigationStore → NavigationSequence}/forward.md +4 -4
  19. package/docs/ui/{NavigationStore → NavigationSequence}/history.md +3 -3
  20. package/docs/ui/{NavigationStore → NavigationSequence}/listen.md +3 -3
  21. package/docs/ui/NavigationSequence/publish.md +14 -0
  22. package/docs/ui/{NavigationStore → NavigationSequence}/replace.md +4 -4
  23. package/docs/ui/NavigationSequence.md +187 -0
  24. package/docs/ui/RouteCache.md +16 -15
  25. package/docs/ui/RouteCacheProps.md +1 -1
  26. package/docs/ui/Router.md +2 -2
  27. package/docs/ui/Transition.md +1 -1
  28. package/docs/ui/VerticalTransition.md +1 -1
  29. package/docs/ui/mergeMeta.md +1 -0
  30. package/docs/ui/requireContext.md +1 -1
  31. package/docs/ui/requireNavigation.md +3 -3
  32. package/docs/ui.md +6 -6
  33. package/package.json +1 -1
  34. package/react/index.d.ts +1 -0
  35. package/react/index.js +1 -0
  36. package/react/useSequenceTransition.d.ts +38 -0
  37. package/react/useSequenceTransition.js +44 -0
  38. package/ui/page/Head.d.ts +1 -1
  39. package/ui/page/Head.js +9 -4
  40. package/ui/page/Head.tsx +8 -4
  41. package/ui/router/BackButton.js +6 -3
  42. package/ui/router/BackButton.md +1 -1
  43. package/ui/router/BackButton.tsx +6 -3
  44. package/ui/router/Navigation.d.ts +5 -5
  45. package/ui/router/Navigation.js +24 -49
  46. package/ui/router/Navigation.md +13 -12
  47. package/ui/router/Navigation.tsx +25 -59
  48. package/ui/router/NavigationContext.d.ts +7 -15
  49. package/ui/router/NavigationContext.js +4 -13
  50. package/ui/router/NavigationContext.tsx +7 -17
  51. package/ui/router/{NavigationStore.d.ts → NavigationSequence.d.ts} +93 -51
  52. package/ui/router/{NavigationStore.js → NavigationSequence.js} +132 -80
  53. package/ui/router/NavigationSequence.md +129 -0
  54. package/ui/router/{NavigationStore.test.ts → NavigationSequence.test.ts} +126 -61
  55. package/ui/router/{NavigationStore.tsx → NavigationSequence.tsx} +160 -92
  56. package/ui/router/RouteCache.d.ts +8 -7
  57. package/ui/router/RouteCache.js +34 -29
  58. package/ui/router/RouteCache.md +9 -8
  59. package/ui/router/RouteCache.tsx +39 -36
  60. package/ui/router/Router.d.ts +2 -2
  61. package/ui/router/Router.js +3 -5
  62. package/ui/router/Router.md +1 -1
  63. package/ui/router/Router.tsx +4 -5
  64. package/ui/router/StackButton.d.ts +1 -1
  65. package/ui/router/StackButton.js +5 -7
  66. package/ui/router/StackButton.tsx +6 -7
  67. package/ui/router/index.d.ts +1 -1
  68. package/ui/router/index.js +1 -1
  69. package/ui/router/index.ts +1 -1
  70. package/ui/transition/HorizontalTransition.md +1 -1
  71. package/ui/transition/Transition.md +1 -1
  72. package/ui/transition/VerticalTransition.md +1 -1
  73. package/ui/util/meta.d.ts +2 -0
  74. package/ui/util/meta.ts +2 -0
  75. package/ui/util/requireContext.md +1 -1
  76. package/docs/ui/NavigationPosition.md +0 -24
  77. package/docs/ui/NavigationPositionContext.md +0 -8
  78. package/docs/ui/NavigationStore.md +0 -164
  79. package/ui/router/NavigationStore.md +0 -110
@@ -0,0 +1,24 @@
1
+ # SequenceTransitionOptions
2
+
3
+ - Kind: interface
4
+ - Import: `import { SequenceTransitionOptions } from "shelving/react";`
5
+
6
+ Options for `useSequenceTransition()`.
7
+
8
+ ## Signatures
9
+
10
+ ```ts
11
+ {
12
+ readonly current: () => T;
13
+ readonly transition?: string | ((value: T) => string | null | undefined) | undefined;
14
+ readonly equal?: ((a: T, b: T) => boolean) | undefined;
15
+ }
16
+ ```
17
+
18
+ ## Properties
19
+
20
+ | Property | Type | Description |
21
+ | --- | --- | --- |
22
+ | `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. |
23
+ | `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. |
24
+ | `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`. |
@@ -0,0 +1,70 @@
1
+ # useSequenceTransition()
2
+
3
+ - Kind: function
4
+ - Import: `import { useSequenceTransition } from "shelving/react";`
5
+
6
+ Subscribe to an async iterable, and set each value it yields inside a React transition.
7
+ - Like `useSequence()`, but each value is set with `setState()` inside `startTransition()`, with a transition type, so a `<ViewTransition>` runs for it.
8
+ - It uses `useState()` and not `useSyncExternalStore()`, because React always renders a `useSyncExternalStore()` update at once, outside any transition.
9
+ - The transition type is shared by the whole React root: the next transition commit takes every type that is waiting.
10
+
11
+ 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.
12
+
13
+ **Things to know:**
14
+
15
+ - It uses `useState()`, not `useSyncExternalStore()`. React always renders a `useSyncExternalStore()` update at once, outside any transition, so a store read can never animate.
16
+ - `current` gives the first value, and is read again when the subscription starts, to catch up on values sent before it started.
17
+ - `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.
18
+ - `equal` skips a value that is the same as the value shown, so it starts no second transition. It defaults to `Object.is`.
19
+ - Transition types belong to the whole React root: the next transition commit takes every type that is waiting.
20
+ - If the sequence throws, the error is re-thrown during render, so the nearest error boundary catches it.
21
+ - Memoise the iterable. The subscription restarts when the iterable changes.
22
+
23
+ ## Usage
24
+
25
+ ```tsx
26
+ import { useSequenceTransition } from "shelving/react";
27
+ import { ViewTransition } from "react";
28
+
29
+ function Slides({ slides }: { slides: SlideSequence }) {
30
+ const slide = useSequenceTransition(slides, {
31
+ current: () => slides.current,
32
+ transition: s => s.direction, // "forward", "back", or undefined for no animation
33
+ equal: (a, b) => a.id === b.id,
34
+ });
35
+ return (
36
+ <ViewTransition update={{ forward: "slide-forward", back: "slide-back", default: "none" }}>
37
+ <Slide slide={slide} />
38
+ </ViewTransition>
39
+ );
40
+ }
41
+ ```
42
+
43
+
44
+ ## Signatures
45
+
46
+ ```ts
47
+ useSequenceTransition(sequence: AsyncIterable<T>, options: SequenceTransitionOptions<T>): T
48
+ ```
49
+
50
+ ## Parameters
51
+
52
+ | Param | Type | Description |
53
+ | --- | --- | --- |
54
+ | `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. |
55
+ | `options` | `SequenceTransitionOptions<T>` | |
56
+ | `.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. |
57
+ | `.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. |
58
+ | `.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`. |
59
+
60
+ ## Returns
61
+
62
+ | Type | Description |
63
+ | --- | --- |
64
+ | `T` | The value shown now. |
65
+
66
+ ## Throws
67
+
68
+ | Type | Description |
69
+ | --- | --- |
70
+ | `unknown` | unknown Re-throws (during render) any error thrown by the sequence, for an error boundary to catch. |
package/docs/react.md CHANGED
@@ -87,9 +87,11 @@ function Toggle() {
87
87
  - [useMap()](react/useMap.md): Create a mutable Map that persists for the lifetime of the component.
88
88
  - [useReduce()](react/useReduce.md): Use memoised value with reduction logic.
89
89
  - [useSequence()](react/useSequence.md): Subscribe to an async iterable for the lifetime of the component.
90
+ - [useSequenceTransition()](react/useSequenceTransition.md): Subscribe to an async iterable, and set each value it yields inside a React transition.
90
91
  - [useStore()](react/useStore.md): Subscribe to a Shelving Store instance to refresh this component when its value changes.
91
92
 
92
93
  ## Interfaces
93
94
 
94
95
  - [APIContext](react/APIContext.md): Bundle of hooks and a provider component returned by createAPIContext()
95
96
  - [DBContext](react/DBContext.md): Bundle of hooks and a provider component returned by createDBContext().
97
+ - [SequenceTransitionOptions](react/SequenceTransitionOptions.md): Options for useSequenceTransition().
@@ -14,7 +14,7 @@ The back button for a page header. It goes back to the page before this one in t
14
14
 
15
15
  - 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.
16
16
  - 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>`.
17
- - 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.
17
+ - 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.
18
18
  - Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
19
19
  - It takes the usual `<Button>` props, except `onClick`.
20
20
  - Without the browser Navigation API, and in a server render, it links to `href`.
package/docs/ui/Head.md CHANGED
@@ -6,7 +6,7 @@
6
6
  Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
7
7
  - Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
8
8
  - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
9
- - 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.
9
+ - 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.
10
10
 
11
11
  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.
12
12
 
@@ -10,7 +10,7 @@ A direction-aware `<Transition>` preset that slides its children horizontally
10
10
  **Things to know:**
11
11
 
12
12
  - Slides right by default and when the type is `"forward"`; slides left when the type is `"back"`.
13
- - 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>`.
13
+ - 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>`.
14
14
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
15
15
  - The old and new content slide a full width apart, so they sit edge to edge and never overlap.
16
16
  - 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/docs/ui/Meta.md CHANGED
@@ -12,6 +12,7 @@ Combined meta data for a website page — title, URLs, description, CSP, tags, l
12
12
  readonly root?: ImmutableURL | undefined;
13
13
  readonly url?: ImmutableURL | undefined;
14
14
  readonly stack?: AbsolutePath | null | undefined;
15
+ readonly ordinal?: number | undefined;
15
16
  readonly app?: string | undefined;
16
17
  readonly title?: string | undefined;
17
18
  readonly description?: string | undefined;
@@ -33,6 +34,7 @@ Combined meta data for a website page — title, URLs, description, CSP, tags, l
33
34
  | `root` | `ImmutableURL \| undefined` | Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). Read only. Optional. |
34
35
  | `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. |
35
36
  | `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. |
37
+ | `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. |
36
38
  | `app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
37
39
  | `title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
38
40
  | `description` | `string \| undefined` | Description of the current page. Read only. Optional. |
@@ -4,28 +4,29 @@
4
4
  - Import: `import { Navigation } from "shelving/ui";`
5
5
 
6
6
  Top-level navigation provider, with one stack of pages for each tab.
7
- - Owns a single `NavigationStore` made from the surrounding `<Meta>` url and root.
8
- - 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.
9
- - Publishes the URL and the current `stack` into `Meta`, and the position in the stacks into `NavigationPositionContext`, all in one render.
10
- - 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.
7
+ - Owns a single `NavigationSequence` made from the surrounding `<Meta>` url and root.
8
+ - 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.
9
+ - Holds the page it shows in its own state, and publishes its `url`, `stack` and `ordinal` into `Meta`. Read the current page from `Meta`.
10
+ - 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.
11
11
  - Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
12
12
 
13
- Exactly one `<Navigation>` per app. Nested routers share its store.
13
+ Exactly one `<Navigation>` per app. Nested routers share its sequence.
14
14
 
15
- 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.
15
+ 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.
16
16
 
17
17
  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.
18
18
 
19
19
  **Things to know:**
20
20
 
21
- - Same-origin link clicks become `NavigationStore.forward()`, so the page slides forward.
22
- - A link with `className="back"` calls `NavigationStore.back()`, so the page slides back. `<BackButton>` sets this class for you.
23
- - 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.
21
+ - Same-origin link clicks become `NavigationSequence.forward()`, so the page slides forward.
22
+ - A link with `className="back"` calls `NavigationSequence.back()`, so the page slides back. `<BackButton>` sets this class for you.
23
+ - 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.
24
24
  - 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.
25
- - 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.
26
- - 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.
25
+ - 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.
26
+ - 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.
27
27
  - 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.
28
- - 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.
28
+ - 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.
29
+ - 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.
29
30
  - 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`.
30
31
  - `<Router>` works with no `<Navigation>` (server renders, static renders, tests). `<Navigation>` only makes the URL live on the client.
31
32
 
@@ -71,7 +72,7 @@ const TABS = (
71
72
  <App root="https://example.com/">
72
73
  <Navigation stacks={STACKS}>
73
74
  <AppLayout nav={TABS}>
74
- <HorizontalTransition>
75
+ <HorizontalTransition default="none">
75
76
  <RouteCache>
76
77
  <Scroll vertical cover>
77
78
  <PageLoader>
@@ -96,9 +97,9 @@ const stack = STACKS.find(s => path === s || path.startsWith(`${s}/`));
96
97
  <Navigation stacks={STACKS} stack={stack}>
97
98
  ```
98
99
 
99
- Put the transition **outside** `<RouteCache>`, around the whole cache. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
100
+ 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>`.
100
101
 
101
- 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`.
102
+ 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`.
102
103
 
103
104
  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.
104
105
 
@@ -122,7 +123,7 @@ Each link pushes a new page onto the current stack, wherever it points. So a lin
122
123
 
123
124
  ### Imperative navigation
124
125
 
125
- Read the store from anywhere in the tree with `requireNavigation()`:
126
+ Read the sequence from anywhere in the tree with `requireNavigation()`:
126
127
 
127
128
  ```tsx
128
129
  import { requireNavigation } from "shelving/ui";
@@ -133,7 +134,7 @@ nav.back("/home"); // Go back to a page.
133
134
  nav.replace("/login"); // Change the URL of the current page.
134
135
  ```
135
136
 
136
- See `NavigationStore` for what each method does.
137
+ See `NavigationSequence` for what each method does.
137
138
 
138
139
 
139
140
  ## Signatures
@@ -3,10 +3,10 @@
3
3
  - Kind: constant
4
4
  - Import: `import { NavigationContext } from "shelving/ui";`
5
5
 
6
- React context holding the current `NavigationStore`, provided by `<Navigation>`.
6
+ React context holding the current `NavigationSequence`, provided by `<Navigation>`.
7
7
 
8
8
  ## Examples
9
9
 
10
10
  ```ts
11
- <NavigationContext value={store}>…</NavigationContext>
11
+ <NavigationContext value={nav}>…</NavigationContext>
12
12
  ```
@@ -0,0 +1,12 @@
1
+ # NavigationDirection
2
+
3
+ - Kind: type
4
+ - Import: `import { NavigationDirection } from "shelving/ui";`
5
+
6
+ Direction of a move in a `NavigationEvent`: `"forward"` or `"back"`.
7
+
8
+ ## Signatures
9
+
10
+ ```ts
11
+ "forward" | "back"
12
+ ```
@@ -3,14 +3,14 @@
3
3
  - Kind: interface
4
4
  - Import: `import { NavigationEntryState } from "shelving/ui";`
5
5
 
6
- State that `NavigationStore` saves on each browser history entry.
6
+ State that `NavigationSequence` saves on each browser history entry.
7
7
 
8
8
  ## Signatures
9
9
 
10
10
  ```ts
11
11
  {
12
12
  readonly stack: AbsolutePath | null;
13
- readonly depth: number;
13
+ readonly ordinal: number;
14
14
  }
15
15
  ```
16
16
 
@@ -19,4 +19,4 @@ State that `NavigationStore` saves on each browser history entry.
19
19
  | Property | Type | Description |
20
20
  | --- | --- | --- |
21
21
  | `stack` | `AbsolutePath \| null` | Root path of the stack this page is in, or `null` for a floating page. Read only. |
22
- | `depth` | `number` | Position of this page in its stack, where `0` is the root. Read only. |
22
+ | `ordinal` | `number` | Position of this page in its stack, where `0` is the root. Read only. |
@@ -0,0 +1,28 @@
1
+ # NavigationEvent
2
+
3
+ - Kind: interface
4
+ - Import: `import { NavigationEvent } from "shelving/ui";`
5
+
6
+ One change of page, published by `NavigationSequence`.
7
+ - 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.
8
+ - A replace has no `direction`, so it shows at once with no transition.
9
+
10
+ ## Signatures
11
+
12
+ ```ts
13
+ {
14
+ readonly url: ImmutableURL;
15
+ readonly stack: AbsolutePath | null;
16
+ readonly ordinal: number | undefined;
17
+ readonly direction?: NavigationDirection | undefined;
18
+ }
19
+ ```
20
+
21
+ ## Properties
22
+
23
+ | Property | Type | Description |
24
+ | --- | --- | --- |
25
+ | `url` | `ImmutableURL` | URL of the page. Read only. |
26
+ | `stack` | `AbsolutePath \| null` | Root path of the stack the page is in, or `null` for a floating page. Read only. |
27
+ | `ordinal` | `number \| undefined` | Position of the page in its stack, where `0` is the root, or `undefined` without the Navigation API. Read only. |
28
+ | `direction` | `NavigationDirection \| undefined` | Direction of the move, or `undefined` for a replace or a change with no slide. Read only. Optional. |
@@ -1,16 +1,17 @@
1
- # NavigationStore.back()
1
+ # NavigationSequence.back()
2
2
 
3
3
  - Kind: method
4
- - Member of: `NavigationStore`
4
+ - Member of: `NavigationSequence`
5
5
 
6
6
  Go back to a URL, as a back button does.
7
- - 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.
8
- - The URL is the root of `stack`: push it at depth 0.
7
+ - 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.
8
+ - The URL is the root of `stack`: push it at ordinal 0.
9
9
  - Else push the URL in place of the top page of `stack`.
10
10
  - It works when the app was opened at the current page, so a back button always has somewhere to go.
11
+ - If the browser refuses to go back with the Navigation API, it uses `history.back()`.
11
12
 
12
13
  ## Signatures
13
14
 
14
15
  ```ts
15
- back(possible: PossibleURL, stack: AbsolutePath | null = this.stack.value): void
16
+ back(possible: PossibleURL, stack: AbsolutePath | null = this._stack): void
16
17
  ```
@@ -0,0 +1,13 @@
1
+ # NavigationSequence.committed()
2
+
3
+ - Kind: method
4
+ - Member of: `NavigationSequence`
5
+
6
+ Tell waiting `publish()` calls that `<Navigation>` has committed a page.
7
+ - `<Navigation>` calls it after each commit.
8
+
9
+ ## Signatures
10
+
11
+ ```ts
12
+ committed(): void
13
+ ```
@@ -0,0 +1,13 @@
1
+ # NavigationSequence.current()
2
+
3
+ - Kind: method
4
+ - Member of: `NavigationSequence`
5
+
6
+ Where the browser history is now, as an event with no direction.
7
+ - `<Navigation>` reads it for its first render, and again when it starts listening, to catch up on changes it missed.
8
+
9
+ ## Signatures
10
+
11
+ ```ts
12
+ current(): NavigationEvent
13
+ ```
@@ -1,10 +1,10 @@
1
- # NavigationStore.forward()
1
+ # NavigationSequence.forward()
2
2
 
3
3
  - Kind: method
4
- - Member of: `NavigationStore`
4
+ - Member of: `NavigationSequence`
5
5
 
6
6
  Go forward to a URL, as a link does.
7
- - The URL is the top page of `stack`: switch to that stack, at the same depth. This is a tab switch.
7
+ - The URL is the top page of `stack`: switch to that stack, at the same ordinal. This is a tab switch.
8
8
  - Else push the URL onto `stack`, one level deeper than its top page.
9
9
  - The URL you are already on: replace it instead.
10
10
  - A change of stack slides by tab order. Else it slides forward.
@@ -12,5 +12,5 @@ Go forward to a URL, as a link does.
12
12
  ## Signatures
13
13
 
14
14
  ```ts
15
- forward(possible: PossibleURL, stack: AbsolutePath | null = this.stack.value): void
15
+ forward(possible: PossibleURL, stack: AbsolutePath | null = this._stack): void
16
16
  ```
@@ -1,7 +1,7 @@
1
- # NavigationStore.history()
1
+ # NavigationSequence.history()
2
2
 
3
3
  - Kind: method
4
- - Member of: `NavigationStore`
4
+ - Member of: `NavigationSequence`
5
5
 
6
6
  Get the pages in a stack, root first, or every page in every stack.
7
7
  - Read from the browser history entries up to the current one.
@@ -12,5 +12,5 @@ Get the pages in a stack, root first, or every page in every stack.
12
12
  ## Signatures
13
13
 
14
14
  ```ts
15
- history(stack: AbsolutePath | null = this.stack.value): AbsolutePath[]
15
+ history(stack: AbsolutePath | null = this._stack): AbsolutePath[]
16
16
  ```
@@ -1,10 +1,10 @@
1
- # NavigationStore.listen()
1
+ # NavigationSequence.listen()
2
2
 
3
3
  - Kind: method
4
- - Member of: `NavigationStore`
4
+ - Member of: `NavigationSequence`
5
5
 
6
6
  Start listening to the browser (back, forward and swipe).
7
- - Saves the current stack and depth on the current history entry, if it has none.
7
+ - Saves the current stack and ordinal on the current history entry, if it has none.
8
8
  - `<Navigation>` calls it once, when it mounts.
9
9
 
10
10
  ## Signatures
@@ -0,0 +1,14 @@
1
+ # NavigationSequence.publish()
2
+
3
+ - Kind: method
4
+ - Member of: `NavigationSequence`
5
+
6
+ Publish an event by hand, without changing history.
7
+ - For example, a swipe-back publishes the page below with `direction: "back"`, so React runs its back transition, and the swipe scrubs it.
8
+ - Then the real `back()` publishes the same page again, which `<Navigation>` skips, or the swipe publishes the current page again to cancel.
9
+
10
+ ## Signatures
11
+
12
+ ```ts
13
+ publish(event: NavigationEvent): Promise<void>
14
+ ```
@@ -1,15 +1,15 @@
1
- # NavigationStore.replace()
1
+ # NavigationSequence.replace()
2
2
 
3
3
  - Kind: method
4
- - Member of: `NavigationStore`
4
+ - Member of: `NavigationSequence`
5
5
 
6
6
  Replace the current URL, with no transition.
7
- - The page stays in the same stack, at the same depth, so a cached page stays mounted.
7
+ - The page stays in the same stack, at the same ordinal, so a cached page stays mounted.
8
8
  - Use it for a page that knows its canonical URL, or for in-page tabs.
9
9
  - 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")`.
10
10
 
11
11
  ## Signatures
12
12
 
13
13
  ```ts
14
- replace(possible: PossibleURL, stack: AbsolutePath | null = this.stack.value): void
14
+ replace(possible: PossibleURL, stack: AbsolutePath | null = this._stack): void
15
15
  ```