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
@@ -0,0 +1,129 @@
1
+ # NavigationSequence
2
+
3
+ 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.
4
+
5
+ **Things to know:**
6
+
7
+ - 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 }`.
8
+ - 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.
9
+ - 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.
10
+ - `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.
11
+ - `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.
12
+ - A page that is not in a listed stack is **floating**: its stack is `null`. See [Floating pages](#floating-pages).
13
+ - In a listed stack, ordinal `0` is always the stack's root path. A deeper page always has the root below it.
14
+ - `NavigationSequence.history()` returns the pages in the current stack (or a given stack), root first.
15
+ - `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.
16
+ - Events sent in the same microtask merge: only the last one is shown.
17
+ - All URLs resolve against the sequence's `base`. Each method also takes a full same-origin URL.
18
+ - 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.
19
+
20
+ ## Methods
21
+
22
+ | Method | What it does | Slide |
23
+ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
24
+ | `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. |
25
+ | `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 |
26
+ | `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 |
27
+ | `history(stack?)` | Returns the pages in `stack`, root first. | — |
28
+ | `current()` | Returns where the browser history is now, as an event with no direction. | — |
29
+ | `publish(event)` | Sends an event by hand. Resolves when `<Navigation>` has committed it. | The event's `direction` |
30
+
31
+ `stack` defaults to the current stack. Pass `null` to name the floating stack.
32
+
33
+ ## Floating pages
34
+
35
+ A page changes stack only when you say so: with a `<StackButton>`, or with a `stack` argument to `forward()`, `back()` or `replace()`. Links never change stack. The page the app opens at starts in the `stack` set on `<Navigation>` (or the surrounding `<Meta>`), else it **floats**: its stack is `null`. For example: a deep link into the app, a fresh open of `/post/9`, or a login page.
36
+
37
+ - The floating stack is outside every tab. It has no root page and no `<StackButton>`, so no stack button is selected on a floating page.
38
+ - Links from a floating page push deeper in the floating stack, even a link to a stack root.
39
+ - To leave the floating stack, tap a `<StackButton>`, or name the stack. To move a page back into it, pass `null` as the `stack`.
40
+ - `<RouteCache>` gives floating pages no protection: they are dropped like any other page past `maxCached`.
41
+ - With no `stacks`, every page floats.
42
+
43
+ ## Opening the app
44
+
45
+ - 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.
46
+ - 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.
47
+ - A `stack` that is not in `stacks` is ignored: the page floats.
48
+
49
+ For example, a login page sends the user home after they log in, and names the Home stack:
50
+
51
+ ```tsx
52
+ const nav = requireNavigation();
53
+ nav.replace("/home", "/home");
54
+ ```
55
+
56
+ ## How stacks work
57
+
58
+ 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`.
59
+
60
+ 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.
61
+
62
+ For example, with tabs `/home` and `/profile`:
63
+
64
+ | Step | New history entry | Home stack | Profile stack |
65
+ | ------------------- | -------------------------- | ----------------------- | ------------- |
66
+ | Start at `/home` | `/home` (ordinal 0) | `/home` | — |
67
+ | Open a post | `/home/post/1` (ordinal 1) | `/home`, `/home/post/1` | — |
68
+ | Tap the Profile tab | `/profile` (ordinal 0) | `/home`, `/home/post/1` | `/profile` |
69
+ | Tap the Home tab | `/home/post/1` (ordinal 1) | `/home`, `/home/post/1` | `/profile` |
70
+ | Tap the back button | `/home` (ordinal 0) | `/home` | `/profile` |
71
+
72
+ 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.
73
+
74
+ 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.
75
+
76
+ ## Usage
77
+
78
+ ```tsx
79
+ import { Button, requireNavigation } from "shelving/ui";
80
+
81
+ function LogoutButton() {
82
+ const nav = requireNavigation();
83
+ return <Button onClick={() => nav.replace("/login")}>Log out</Button>;
84
+ }
85
+ ```
86
+
87
+ Read the current stack in a component from `Meta`:
88
+
89
+ ```tsx
90
+ import { requireMeta } from "shelving/ui";
91
+
92
+ function TabTitle() {
93
+ const { stack } = requireMeta();
94
+ return <h1>{stack === "/profile" ? "Profile" : "Home"}</h1>;
95
+ }
96
+ ```
97
+
98
+ Show the page below during a swipe-back. React runs the back transition, and the swipe scrubs it:
99
+
100
+ ```tsx
101
+ const nav = requireNavigation();
102
+ const { stack = null, ordinal } = requireMetaURL();
103
+ const parent = ordinal ? nav.history(stack)[ordinal - 1] : undefined;
104
+ if (parent) {
105
+ // Start the swipe: show the page below with the back transition.
106
+ await nav.publish({ url: requireURL(parent, nav.base), stack, ordinal: ordinal - 1, direction: "back" });
107
+ // Release: go back for real. It publishes the same page, so it is skipped.
108
+ nav.back(parent);
109
+ // Or cancel: show the old page again, with no transition.
110
+ // await nav.publish({ ...from, direction: undefined });
111
+ }
112
+ ```
113
+
114
+ List the pages in a stack (for example, for breadcrumbs):
115
+
116
+ ```tsx
117
+ const nav = requireNavigation();
118
+ nav.history("/home"); // ["/home", "/home/post/1", "/home/post/1/comments"]
119
+ ```
120
+
121
+ Make a sequence by hand only in tests:
122
+
123
+ ```tsx
124
+ import { NavigationSequence } from "shelving/ui";
125
+
126
+ // URL, root, starting stack, then the stacks in tab order.
127
+ const nav = new NavigationSequence("https://example.com/home", "https://example.com/", "/home", "/home", "/profile");
128
+ nav.forward("/home/post/1");
129
+ ```
@@ -1,7 +1,16 @@
1
1
  import { afterEach, beforeEach, describe, expect, test } from "bun:test";
2
- import { NavigationStore } from "shelving/ui";
2
+ import { type NavigationEvent, NavigationSequence } from "shelving/ui";
3
+
4
+ /** Records the last event, so tests can read its direction straight away. */
5
+ class TestSequence extends NavigationSequence {
6
+ last: NavigationEvent | undefined;
7
+ override resolve(event: NavigationEvent): void {
8
+ this.last = event;
9
+ super.resolve(event);
10
+ }
11
+ }
3
12
 
4
- // A small fake of the browser Navigation API and `window.history`, enough for `NavigationStore`.
13
+ // A small fake of the browser Navigation API and `window.history`, enough for `NavigationSequence`.
5
14
 
6
15
  type Listener = (e: Record<string, unknown>) => void;
7
16
 
@@ -78,7 +87,7 @@ const globals = globalThis as { navigation?: unknown; window?: unknown };
78
87
  let fake: FakeNavigation;
79
88
 
80
89
  /** Open the app at `path`, in `stack` (by default the stack whose root is `path`, else `/`). */
81
- function setup(path = "/home", stack: string | null = (STACKS as readonly string[]).includes(path) ? path : null): NavigationStore {
90
+ function setup(path = "/home", stack: string | null = (STACKS as readonly string[]).includes(path) ? path : null): TestSequence {
82
91
  fake = new FakeNavigation(`${ORIGIN}${path}`);
83
92
  globals.navigation = fake;
84
93
  globals.window = {
@@ -90,15 +99,15 @@ function setup(path = "/home", stack: string | null = (STACKS as readonly string
90
99
  addEventListener: () => undefined,
91
100
  removeEventListener: () => undefined,
92
101
  };
93
- const nav = new NavigationStore(`${ORIGIN}${path}`, `${ORIGIN}/`, stack as `/${string}` | null, ...STACKS);
102
+ const nav = new TestSequence(`${ORIGIN}${path}`, `${ORIGIN}/`, stack as `/${string}` | null, ...STACKS);
94
103
  nav.listen();
95
104
  return nav;
96
105
  }
97
106
 
98
107
  function getEntries(): string[] {
99
108
  return fake.list.map(e => {
100
- const s = e.state as { stack: string | null; depth: number } | undefined;
101
- return `${new URL(e.url).pathname}${s ? ` ${s.stack}@${s.depth}` : ""}`;
109
+ const s = e.state as { stack: string | null; ordinal: number } | undefined;
110
+ return `${new URL(e.url).pathname}${s ? ` ${s.stack}@${s.ordinal}` : ""}`;
102
111
  });
103
112
  }
104
113
 
@@ -112,21 +121,21 @@ afterEach(() => {
112
121
  delete globals.window;
113
122
  });
114
123
 
115
- describe("NavigationStore", () => {
124
+ describe("NavigationSequence", () => {
116
125
  test("has no history without the Navigation API", () => {
117
- const nav = new NavigationStore(`${ORIGIN}/home`, `${ORIGIN}/`, "/home", ...STACKS);
118
- expect(nav.stack.value).toBe("/home");
126
+ const nav = new TestSequence(`${ORIGIN}/home`, `${ORIGIN}/`, "/home", ...STACKS);
127
+ expect(nav.stack).toBe("/home");
119
128
  expect(nav.history("/home")).toEqual([]);
120
- expect(nav.position).toBe(undefined);
129
+ expect(nav.current().ordinal).toBe(undefined);
121
130
  });
122
131
 
123
132
  test("floats every page with no stacks", () => {
124
- expect(new NavigationStore(`${ORIGIN}/home`, `${ORIGIN}/`).stack.value).toBe(null);
133
+ expect(new TestSequence(`${ORIGIN}/home`, `${ORIGIN}/`).stack).toBe(null);
125
134
  fake = new FakeNavigation(`${ORIGIN}/a/b`);
126
135
  globals.navigation = fake;
127
136
  globals.window = { location: { href: `${ORIGIN}/a/b` } };
128
- const nav = new NavigationStore(`${ORIGIN}/a/b`, `${ORIGIN}/`);
129
- expect(nav.stack.value).toBe(null);
137
+ const nav = new TestSequence(`${ORIGIN}/a/b`, `${ORIGIN}/`);
138
+ expect(nav.stack).toBe(null);
130
139
  expect(nav.history()).toEqual(["/a/b"]);
131
140
  });
132
141
 
@@ -135,19 +144,19 @@ describe("NavigationStore", () => {
135
144
  location: { href: `${ORIGIN}/home` },
136
145
  history: { pushState: () => undefined, replaceState: () => undefined },
137
146
  };
138
- const nav = new NavigationStore(`${ORIGIN}/home`, `${ORIGIN}/`, "/home", ...STACKS);
147
+ const nav = new TestSequence(`${ORIGIN}/home`, `${ORIGIN}/`, "/home", ...STACKS);
139
148
  nav.forward("/profile/settings");
140
149
  nav.back("/discover");
141
- expect(nav.stack.value).toBe("/home");
150
+ expect(nav.stack).toBe("/home");
142
151
  });
143
152
 
144
153
  test("opens in the starting stack", () => {
145
154
  const nav = setup("/profile/settings", "/profile");
146
- expect(nav.stack.value).toBe("/profile");
155
+ expect(nav.stack).toBe("/profile");
147
156
  expect(getEntries()).toEqual(["/profile/settings /profile@1"]);
148
157
  });
149
158
 
150
- test("opens a stack root at depth 0", () => {
159
+ test("opens a stack root at ordinal 0", () => {
151
160
  setup("/profile", "/profile");
152
161
  expect(getEntries()).toEqual(["/profile /profile@0"]);
153
162
  });
@@ -155,7 +164,7 @@ describe("NavigationStore", () => {
155
164
  test("keeps the stack root below a deep page the app opens at", () => {
156
165
  const nav = setup("/discover/fitness", "/discover");
157
166
  expect(nav.history()).toEqual(["/discover", "/discover/fitness"]);
158
- expect(nav.position?.parent).toBe("/discover");
167
+ expect(nav.history().at(-2)).toBe("/discover");
159
168
  nav.back("/discover");
160
169
  expect(getEntries()).toEqual(["/discover/fitness /discover@1", "/discover /discover@0"]);
161
170
  expect(nav.history()).toEqual(["/discover"]);
@@ -165,7 +174,7 @@ describe("NavigationStore", () => {
165
174
  fake = new FakeNavigation(`${ORIGIN}/a/b`);
166
175
  globals.navigation = fake;
167
176
  globals.window = { location: { href: `${ORIGIN}/a/b` } };
168
- const nav = new NavigationStore(`${ORIGIN}/a/b`, `${ORIGIN}/`, "/", "/");
177
+ const nav = new TestSequence(`${ORIGIN}/a/b`, `${ORIGIN}/`, "/", "/");
169
178
  expect(nav.history()).toEqual(["/", "/a/b"]);
170
179
  });
171
180
 
@@ -173,42 +182,42 @@ describe("NavigationStore", () => {
173
182
  fake = new FakeNavigation(`${ORIGIN}/post/1`);
174
183
  globals.navigation = fake;
175
184
  globals.window = { location: { href: `${ORIGIN}/post/1` } };
176
- const nav = new NavigationStore(`${ORIGIN}/post/1`, `${ORIGIN}/`, null, "/", "/discover");
177
- expect(nav.stack.value).toBe(null);
185
+ const nav = new TestSequence(`${ORIGIN}/post/1`, `${ORIGIN}/`, null, "/", "/discover");
186
+ expect(nav.stack).toBe(null);
178
187
  expect(nav.history("/")).toEqual([]);
179
188
  });
180
189
 
181
190
  test("opens a stack root as floating with no starting stack", () => {
182
191
  const nav = setup("/profile", null);
183
- expect(nav.stack.value).toBe(null);
192
+ expect(nav.stack).toBe(null);
184
193
  expect(getEntries()).toEqual(["/profile null@0"]);
185
194
  });
186
195
 
187
196
  test("floats a starting stack that is not listed", () => {
188
197
  const nav = setup("/other/1", "/other");
189
- expect(nav.stack.value).toBe(null);
198
+ expect(nav.stack).toBe(null);
190
199
  });
191
200
 
192
201
  test("keeps the saved stack after a reload", () => {
193
202
  fake = new FakeNavigation(`${ORIGIN}/home/post/1`);
194
- (fake.list[0] as FakeEntry).state = { stack: "/home", depth: 1 };
203
+ (fake.list[0] as FakeEntry).state = { stack: "/home", ordinal: 1 };
195
204
  globals.navigation = fake;
196
205
  globals.window = { location: { href: `${ORIGIN}/home/post/1` } };
197
- const nav = new NavigationStore(`${ORIGIN}/home/post/1`, `${ORIGIN}/`, "/profile", ...STACKS);
198
- expect(nav.stack.value).toBe("/home");
206
+ const nav = new TestSequence(`${ORIGIN}/home/post/1`, `${ORIGIN}/`, "/profile", ...STACKS);
207
+ expect(nav.stack).toBe("/home");
199
208
  });
200
209
 
201
210
  describe("floating pages", () => {
202
211
  test("open any other page in the floating stack", () => {
203
212
  const nav = setup("/profile/settings");
204
- expect(nav.stack.value).toBe(null);
213
+ expect(nav.stack).toBe(null);
205
214
  expect(getEntries()).toEqual(["/profile/settings null@0"]);
206
215
  });
207
216
 
208
217
  test("push links deeper in the floating stack", () => {
209
218
  const nav = setup("/login");
210
219
  nav.forward("/login/reset");
211
- expect(nav.stack.value).toBe(null);
220
+ expect(nav.stack).toBe(null);
212
221
  expect(nav.history()).toEqual(["/login", "/login/reset"]);
213
222
  });
214
223
 
@@ -218,27 +227,27 @@ describe("NavigationStore", () => {
218
227
  expect(getEntries().at(-1)).toBe("/home null@1");
219
228
  nav.replace("/profile");
220
229
  expect(getEntries().at(-1)).toBe("/profile null@1");
221
- expect(nav.stack.value).toBe(null);
230
+ expect(nav.stack).toBe(null);
222
231
  });
223
232
 
224
233
  test("move back into the floating stack when forward names it", () => {
225
234
  const nav = setup("/home");
226
235
  nav.forward("/login", null);
227
- expect(nav.stack.value).toBe(null);
236
+ expect(nav.stack).toBe(null);
228
237
  expect(getEntries().at(-1)).toBe("/login null@0");
229
238
  });
230
239
 
231
240
  test("move into a stack when forward names it", () => {
232
241
  const nav = setup("/login");
233
242
  nav.forward("/home", "/home");
234
- expect(nav.stack.value).toBe("/home");
243
+ expect(nav.stack).toBe("/home");
235
244
  expect(getEntries().at(-1)).toBe("/home /home@0");
236
245
  });
237
246
 
238
247
  test("move into a stack when a replace names it", () => {
239
248
  const nav = setup("/login");
240
249
  nav.replace("/home", "/home");
241
- expect(nav.stack.value).toBe("/home");
250
+ expect(nav.stack).toBe("/home");
242
251
  expect(getEntries()).toEqual(["/home /home@0"]);
243
252
  });
244
253
 
@@ -254,13 +263,13 @@ describe("NavigationStore", () => {
254
263
  test("move into a stack when back names it", () => {
255
264
  const nav = setup("/home/post/1");
256
265
  nav.back("/home", "/home");
257
- expect(nav.stack.value).toBe("/home");
266
+ expect(nav.stack).toBe("/home");
258
267
  expect(getEntries().at(-1)).toBe("/home /home@0");
259
268
  });
260
269
 
261
270
  test("have no parent", () => {
262
271
  const nav = setup("/home/post/1");
263
- expect(nav.position?.parent).toBe(undefined);
272
+ expect(nav.history().at(-2)).toBe(undefined);
264
273
  });
265
274
  });
266
275
 
@@ -277,24 +286,24 @@ describe("NavigationStore", () => {
277
286
  nav.forward("/home/post/1");
278
287
  nav.forward("/home/post/1/comments");
279
288
  expect(nav.history("/home")).toEqual(["/home", "/home/post/1", "/home/post/1/comments"]);
280
- expect(nav.transition).toBe("forward");
289
+ expect(nav.last?.direction ?? null).toBe("forward");
281
290
  });
282
291
 
283
292
  test("pushes onto the current stack wherever the link points", () => {
284
293
  const nav = setup();
285
294
  nav.forward("/profile/settings");
286
- expect(nav.stack.value).toBe("/home");
295
+ expect(nav.stack).toBe("/home");
287
296
  expect(nav.history("/home")).toEqual(["/home", "/profile/settings"]);
288
297
  });
289
298
 
290
- test("switches stack at the same depth and slides by tab order", () => {
299
+ test("switches stack at the same ordinal and slides by tab order", () => {
291
300
  const nav = setup();
292
301
  nav.forward("/home/post/1");
293
302
  nav.forward("/profile", "/profile");
294
- expect(nav.transition).toBe("forward");
303
+ expect(nav.last?.direction ?? null).toBe("forward");
295
304
  nav.forward("/home/post/1", "/home");
296
- expect(nav.transition).toBe("back");
297
- expect(nav.stack.value).toBe("/home");
305
+ expect(nav.last?.direction ?? null).toBe("back");
306
+ expect(nav.stack).toBe("/home");
298
307
  expect(getEntries().at(-1)).toBe("/home/post/1 /home@1");
299
308
  expect(nav.history("/home")).toEqual(["/home", "/home/post/1"]);
300
309
  expect(nav.history("/profile")).toEqual(["/profile"]);
@@ -304,7 +313,7 @@ describe("NavigationStore", () => {
304
313
  const nav = setup();
305
314
  nav.forward("/home");
306
315
  expect(fake.list.length).toBe(1);
307
- expect(nav.transition).toBe(null);
316
+ expect(nav.last?.direction ?? null).toBe(null);
308
317
  });
309
318
  });
310
319
 
@@ -315,10 +324,52 @@ describe("NavigationStore", () => {
315
324
  nav.back("/home");
316
325
  expect(fake.index).toBe(0);
317
326
  expect(fake.list.length).toBe(2);
318
- expect(nav.transition).toBe("back");
327
+ expect(nav.last?.direction ?? null).toBe("back");
319
328
  expect(nav.history("/home")).toEqual(["/home"]);
320
329
  });
321
330
 
331
+ test("falls back to history.back() when traverseTo() throws", () => {
332
+ const nav = setup();
333
+ nav.forward("/home/post/1");
334
+ const win = globals.window as { history: { back?: () => void } };
335
+ const traverse = fake.traverseTo.bind(fake);
336
+ win.history.back = () => void traverse(fake.list[fake.index - 1]?.key ?? "");
337
+ fake.traverseTo = () => {
338
+ throw new Error("Invalid state");
339
+ };
340
+ nav.back("/home");
341
+ expect(fake.index).toBe(0);
342
+ expect(nav.history("/home")).toEqual(["/home"]);
343
+ });
344
+
345
+ test("falls back to history.back() when traverseTo() rejects", async () => {
346
+ const nav = setup();
347
+ nav.forward("/home/post/1");
348
+ let backs = 0;
349
+ const win = globals.window as { history: { back?: () => void } };
350
+ win.history.back = () => void backs++;
351
+ const fail = Object.assign(new Error("Invalid state"), { name: "SecurityError" });
352
+ fake.traverseTo = () => ({ committed: Promise.reject(fail), finished: Promise.reject(fail) }) as never;
353
+ nav.back("/home");
354
+ await Promise.resolve();
355
+ await Promise.resolve();
356
+ expect(backs).toBe(1);
357
+ });
358
+
359
+ test("does not fall back when a newer navigation stops the traverse", async () => {
360
+ const nav = setup();
361
+ nav.forward("/home/post/1");
362
+ let backs = 0;
363
+ const win = globals.window as { history: { back?: () => void } };
364
+ win.history.back = () => void backs++;
365
+ const abort = Object.assign(new Error("Stopped"), { name: "AbortError" });
366
+ fake.traverseTo = () => ({ committed: Promise.reject(abort), finished: Promise.reject(abort) }) as never;
367
+ nav.back("/home");
368
+ await Promise.resolve();
369
+ await Promise.resolve();
370
+ expect(backs).toBe(0);
371
+ });
372
+
322
373
  test("pushes the page again when other stacks are in between", () => {
323
374
  const nav = setup();
324
375
  nav.forward("/home/post/1");
@@ -342,12 +393,12 @@ describe("NavigationStore", () => {
342
393
  });
343
394
 
344
395
  describe("replace()", () => {
345
- test("keeps the stack and depth", () => {
396
+ test("keeps the stack and ordinal", () => {
346
397
  const nav = setup();
347
398
  nav.forward("/home/post/1");
348
399
  nav.replace("/home/post/1/info");
349
400
  expect(getEntries().at(-1)).toBe("/home/post/1/info /home@1");
350
- expect(nav.transition).toBe(null);
401
+ expect(nav.last?.direction ?? null).toBe(null);
351
402
  });
352
403
 
353
404
  test("puts the state back after another script replaces the entry", () => {
@@ -355,7 +406,7 @@ describe("NavigationStore", () => {
355
406
  nav.forward("/home/post/1");
356
407
  fake.replace(`${ORIGIN}/home/post/1?x=1`);
357
408
  expect(getEntries().at(-1)).toBe("/home/post/1 /home@1");
358
- expect(nav.value.href).toBe(`${ORIGIN}/home/post/1?x=1`);
409
+ expect(nav.url.href).toBe(`${ORIGIN}/home/post/1?x=1`);
359
410
  });
360
411
  });
361
412
 
@@ -402,18 +453,18 @@ describe("NavigationStore", () => {
402
453
  });
403
454
 
404
455
  describe("browser back and forward", () => {
405
- test("slides by depth in a stack and by tab order across stacks", () => {
456
+ test("slides by ordinal in a stack and by tab order across stacks", () => {
406
457
  const nav = setup();
407
458
  nav.forward("/home/post/1");
408
459
  nav.forward("/profile", "/profile");
409
460
  fake.go(-1);
410
- expect(nav.transition).toBe("back");
411
- expect(nav.stack.value).toBe("/home");
461
+ expect(nav.last?.direction ?? null).toBe("back");
462
+ expect(nav.stack).toBe("/home");
412
463
  fake.go(-1);
413
- expect(nav.transition).toBe("back");
414
- expect(nav.value.pathname).toBe("/home");
464
+ expect(nav.last?.direction ?? null).toBe("back");
465
+ expect(nav.url.pathname).toBe("/home");
415
466
  fake.go(1);
416
- expect(nav.transition).toBe("forward");
467
+ expect(nav.last?.direction ?? null).toBe("forward");
417
468
  });
418
469
 
419
470
  test("slides forward when undoing a pushed back", () => {
@@ -423,7 +474,7 @@ describe("NavigationStore", () => {
423
474
  nav.forward("/home/post/1", "/home");
424
475
  nav.back("/home");
425
476
  fake.go(-1);
426
- expect(nav.transition).toBe("forward");
477
+ expect(nav.last?.direction ?? null).toBe("forward");
427
478
  });
428
479
  });
429
480
 
@@ -433,19 +484,33 @@ describe("NavigationStore", () => {
433
484
  expect(nav.path).toBe("/home/post/1");
434
485
  });
435
486
 
436
- test("position has the depth of each stack's top page and the parent", () => {
487
+ test("current() has the stack and ordinal of the history entry", () => {
437
488
  const nav = setup();
438
489
  nav.forward("/home/post/1");
439
490
  nav.forward("/profile", "/profile");
440
491
  nav.forward("/home/post/1", "/home");
441
- expect(nav.position).toEqual({
442
- stack: "/home",
443
- depth: 1,
444
- tops: new Map([
445
- ["/home", 1],
446
- ["/profile", 0],
447
- ]),
448
- parent: "/home",
492
+ expect(nav.current()).toEqual({ url: nav.url, stack: "/home", ordinal: 1 });
493
+ expect(nav.history().at(-2)).toBe("/home");
494
+ });
495
+
496
+ test("each change publishes one event", async () => {
497
+ const nav = setup();
498
+ const next = nav.next();
499
+ nav.forward("/home/post/1");
500
+ const { value } = await next;
501
+ expect(value).toEqual({ url: nav.url, stack: "/home", ordinal: 1, direction: "forward" });
502
+ });
503
+
504
+ test("publish() resolves when committed() is called", async () => {
505
+ const nav = setup();
506
+ let done = false;
507
+ const promise = nav.publish({ ...nav.current(), direction: "back" }).then(() => {
508
+ done = true;
449
509
  });
510
+ await Promise.resolve();
511
+ expect(done).toBe(false);
512
+ nav.committed();
513
+ await promise;
514
+ expect(done).toBe(true);
450
515
  });
451
516
  });