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
@@ -1,10 +1,8 @@
1
- import { Store } from "../../store/Store.js";
2
- import { URLStore } from "../../store/URLStore.js";
1
+ import { DeferredSequence } from "../../sequence/DeferredSequence.js";
3
2
  import type { AbsolutePath } from "../../util/path.js";
4
- import { type PossibleURL } from "../../util/url.js";
5
- import type { TransitionType } from "../transition/util.js";
3
+ import { type ImmutableURL, type PossibleURL } from "../../util/url.js";
6
4
  /**
7
- * State that `NavigationStore` saves on each browser history entry.
5
+ * State that `NavigationSequence` saves on each browser history entry.
8
6
  *
9
7
  * @see https://shelving.cc/ui/NavigationEntryState
10
8
  */
@@ -12,46 +10,60 @@ export interface NavigationEntryState {
12
10
  /** Root path of the stack this page is in, or `null` for a floating page. */
13
11
  readonly stack: AbsolutePath | null;
14
12
  /** Position of this page in its stack, where `0` is the root. */
15
- readonly depth: number;
13
+ readonly ordinal: number;
16
14
  }
17
15
  /**
18
- * 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.
19
- * - `undefined` when the browser has no Navigation API, or during a server render.
16
+ * Direction of a move in a `NavigationEvent`: `"forward"` or `"back"`.
20
17
  *
21
- * @see https://shelving.cc/ui/NavigationPosition
18
+ * @see https://shelving.cc/ui/NavigationDirection
22
19
  */
23
- export interface NavigationPosition extends NavigationEntryState {
24
- /** Depth of the top page of each stack that has pages, including the floating stack (`null`). */
25
- readonly tops: ReadonlyMap<AbsolutePath | null, number>;
26
- /** The page before the current one in its stack, or `undefined` at the bottom of the stack. */
27
- readonly parent: AbsolutePath | undefined;
20
+ export type NavigationDirection = "forward" | "back";
21
+ /**
22
+ * One change of page, published by `NavigationSequence`.
23
+ * - 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.
24
+ * - A replace has no `direction`, so it shows at once with no transition.
25
+ *
26
+ * @see https://shelving.cc/ui/NavigationEvent
27
+ */
28
+ export interface NavigationEvent {
29
+ /** URL of the page. */
30
+ readonly url: ImmutableURL;
31
+ /** Root path of the stack the page is in, or `null` for a floating page. */
32
+ readonly stack: AbsolutePath | null;
33
+ /** Position of the page in its stack, where `0` is the root, or `undefined` without the Navigation API. */
34
+ readonly ordinal: number | undefined;
35
+ /** Direction of the move, or `undefined` for a replace or a change with no slide. */
36
+ readonly direction?: NavigationDirection | undefined;
28
37
  }
29
38
  /**
30
- * Store that holds the current navigation URL, drives browser history, and keeps a stack of pages for each tab.
39
+ * Sequence of navigation events that drives browser history and keeps a stack of pages for each tab.
31
40
  *
32
- * - Extends `URLStore`, so its `value` is the current URL.
41
+ * - 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.
42
+ * - `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`.
43
+ * - `publish()` sends an event by hand, for example to show the page below during a swipe-back.
33
44
  * - 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.
34
- * - `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.
35
45
  * - A page outside the listed stacks is floating: its stack is `null`. The floating stack has no root page and no tab.
36
- * - In a listed stack, depth `0` is always the stack's root path.
46
+ * - In a listed stack, ordinal `0` is always the stack's root path.
37
47
  * - 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.
38
48
  * - Owned by `<Navigation>`. Read it with `requireNavigation()`.
39
49
  *
40
- * @see https://shelving.cc/ui/NavigationStore
50
+ * @see https://shelving.cc/ui/NavigationSequence
41
51
  */
42
- export declare class NavigationStore extends URLStore {
52
+ export declare class NavigationSequence extends DeferredSequence<NavigationEvent> {
43
53
  /** Root path of each stack, in tab order. With none, every page floats. */
44
54
  readonly stacks: readonly AbsolutePath[];
45
55
  /**
46
- * Root path of the current stack, or `null` for a floating page.
47
- * - It starts at the `stack` given to the constructor (default `null`). Without the Navigation API, it stays there.
48
- */
49
- readonly stack: Store<AbsolutePath | null>;
50
- /**
51
- * Transition type of the most recent change, read by `<Navigation>` when the value changes.
52
- * - `null` means no transition: a replace, a change the browser already animated (for example a swipe-back), or no Navigation API.
56
+ * Base URL of the app, used to resolve relative URLs and to work out paths.
57
+ *
58
+ * @see https://shelving.cc/ui/NavigationSequence/base
53
59
  */
54
- transition: TransitionType | null;
60
+ readonly base: ImmutableURL | undefined;
61
+ /** URL the browser history is on now. */
62
+ private _url;
63
+ /** Stack the browser history is on now. Without the Navigation API, it stays at the starting stack. */
64
+ private _stack;
65
+ /** Callbacks waiting for `<Navigation>` to commit the next event. */
66
+ private _waiting;
55
67
  /** The browser Navigation API, or `undefined` when it is not available. */
56
68
  private readonly _navigation;
57
69
  /** Transition sent with the next navigation, and whether the browser animates it. */
@@ -62,25 +74,54 @@ export declare class NavigationStore extends URLStore {
62
74
  private readonly _start;
63
75
  constructor(url?: PossibleURL, base?: PossibleURL, stack?: AbsolutePath | null, ...stacks: AbsolutePath[]);
64
76
  /**
65
- * Path of the current URL relative to the app root (without its `?query`), or `undefined` if the URL is outside the app.
77
+ * URL the browser history is on now.
66
78
  *
67
- * @see https://shelving.cc/ui/NavigationStore/path
79
+ * @see https://shelving.cc/ui/NavigationSequence/url
68
80
  */
69
- get path(): AbsolutePath | undefined;
81
+ get url(): ImmutableURL;
82
+ /**
83
+ * Root path of the stack the browser history is on now, or `null` for a floating page.
84
+ *
85
+ * @see https://shelving.cc/ui/NavigationSequence/stack
86
+ */
87
+ get stack(): AbsolutePath | null;
70
88
  /**
71
- * Where the app is now: the current stack and depth, and the top depth of each stack.
89
+ * Where the browser history is now, as an event with no direction.
90
+ * - `<Navigation>` reads it for its first render, and again when it starts listening, to catch up on changes it missed.
72
91
  *
73
- * @returns The position, or `undefined` without the Navigation API.
74
- * @see https://shelving.cc/ui/NavigationStore/position
92
+ * @see https://shelving.cc/ui/NavigationSequence/current
75
93
  */
76
- get position(): NavigationPosition | undefined;
94
+ current(): NavigationEvent;
95
+ /**
96
+ * Publish an event by hand, without changing history.
97
+ * - For example, a swipe-back publishes the page below with `direction: "back"`, so React runs its back transition, and the swipe scrubs it.
98
+ * - Then the real `back()` publishes the same page again, which `<Navigation>` skips, or the swipe publishes the current page again to cancel.
99
+ *
100
+ * @param event The event to publish.
101
+ * @returns A promise that resolves when `<Navigation>` has committed the event.
102
+ * @see https://shelving.cc/ui/NavigationSequence/publish
103
+ */
104
+ publish(event: NavigationEvent): Promise<void>;
105
+ /**
106
+ * Tell waiting `publish()` calls that `<Navigation>` has committed a page.
107
+ * - `<Navigation>` calls it after each commit.
108
+ *
109
+ * @see https://shelving.cc/ui/NavigationSequence/committed
110
+ */
111
+ committed(): void;
112
+ /**
113
+ * Path of the current URL relative to the app root (without its `?query`), or `undefined` if the URL is outside the app.
114
+ *
115
+ * @see https://shelving.cc/ui/NavigationSequence/path
116
+ */
117
+ get path(): AbsolutePath | undefined;
77
118
  /**
78
119
  * Start listening to the browser (back, forward and swipe).
79
- * - Saves the current stack and depth on the current history entry, if it has none.
120
+ * - Saves the current stack and ordinal on the current history entry, if it has none.
80
121
  * - `<Navigation>` calls it once, when it mounts.
81
122
  *
82
123
  * @returns A function that stops listening.
83
- * @see https://shelving.cc/ui/NavigationStore/listen
124
+ * @see https://shelving.cc/ui/NavigationSequence/listen
84
125
  */
85
126
  listen(): () => void;
86
127
  /**
@@ -93,12 +134,12 @@ export declare class NavigationStore extends URLStore {
93
134
  * @param stack Root path of the stack, or `null` for the floating stack. Defaults to the current stack.
94
135
  * @returns Paths relative to the app root, each with its `?query`.
95
136
  * @example nav.history("/home") // ["/home", "/home/post/2"]
96
- * @see https://shelving.cc/ui/NavigationStore/history
137
+ * @see https://shelving.cc/ui/NavigationSequence/history
97
138
  */
98
139
  history(stack?: AbsolutePath | null): AbsolutePath[];
99
140
  /**
100
141
  * Go forward to a URL, as a link does.
101
- * - The URL is the top page of `stack`: switch to that stack, at the same depth. This is a tab switch.
142
+ * - The URL is the top page of `stack`: switch to that stack, at the same ordinal. This is a tab switch.
102
143
  * - Else push the URL onto `stack`, one level deeper than its top page.
103
144
  * - The URL you are already on: replace it instead.
104
145
  * - A change of stack slides by tab order. Else it slides forward.
@@ -107,26 +148,27 @@ export declare class NavigationStore extends URLStore {
107
148
  * @param stack Root path of the stack to go to, or `null` for the floating stack. Defaults to the current stack.
108
149
  * @throws RequiredError If `possible` cannot be resolved to a valid URL.
109
150
  * @example nav.forward("/settings");
110
- * @see https://shelving.cc/ui/NavigationStore/forward
151
+ * @see https://shelving.cc/ui/NavigationSequence/forward
111
152
  */
112
153
  forward(possible: PossibleURL, stack?: AbsolutePath | null): void;
113
154
  /**
114
155
  * Go back to a URL, as a back button does.
115
- * - 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.
116
- * - The URL is the root of `stack`: push it at depth 0.
156
+ * - 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.
157
+ * - The URL is the root of `stack`: push it at ordinal 0.
117
158
  * - Else push the URL in place of the top page of `stack`.
118
159
  * - It works when the app was opened at the current page, so a back button always has somewhere to go.
160
+ * - If the browser refuses to go back with the Navigation API, it uses `history.back()`.
119
161
  *
120
162
  * @param possible The destination URL, resolved against `base`.
121
163
  * @param stack Root path of the stack to go back in, or `null` for the floating stack. Defaults to the current stack.
122
164
  * @throws RequiredError If `possible` cannot be resolved to a valid URL.
123
165
  * @example nav.back("/profile");
124
- * @see https://shelving.cc/ui/NavigationStore/back
166
+ * @see https://shelving.cc/ui/NavigationSequence/back
125
167
  */
126
168
  back(possible: PossibleURL, stack?: AbsolutePath | null): void;
127
169
  /**
128
170
  * Replace the current URL, with no transition.
129
- * - The page stays in the same stack, at the same depth, so a cached page stays mounted.
171
+ * - The page stays in the same stack, at the same ordinal, so a cached page stays mounted.
130
172
  * - Use it for a page that knows its canonical URL, or for in-page tabs.
131
173
  * - 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")`.
132
174
  *
@@ -134,7 +176,7 @@ export declare class NavigationStore extends URLStore {
134
176
  * @param stack Root path of the stack to move the page into, or `null` for the floating stack. Defaults to the current stack.
135
177
  * @throws RequiredError If `possible` cannot be resolved to a valid URL.
136
178
  * @example nav.replace("/login");
137
- * @see https://shelving.cc/ui/NavigationStore/replace
179
+ * @see https://shelving.cc/ui/NavigationSequence/replace
138
180
  */
139
181
  replace(possible: PossibleURL, stack?: AbsolutePath | null): void;
140
182
  /** Push a URL as a new history entry, with an optional state. */
@@ -143,19 +185,19 @@ export declare class NavigationStore extends URLStore {
143
185
  private _write;
144
186
  /** Save a state on the current entry. */
145
187
  private _update;
146
- /** Set the stack first, then the URL, so both are ready when `<Navigation>` reads them. */
188
+ /** Record where history is now, and publish it as an event. */
147
189
  private _change;
148
- /** Get the pages in a stack, root first: the newest entry in the stack, then the newest earlier entry at a lower depth, down to depth 0. */
190
+ /** Get the pages in a stack, root first: the newest entry in the stack, then the newest earlier entry at a lower ordinal, down to ordinal 0. */
149
191
  private _getPages;
150
- /** Get the saved state of an entry, or for an entry with none (for example the page the app opened at), the starting stack at its bottom depth. */
192
+ /** Get the saved state of an entry, or for an entry with none (for example the page the app opened at), the starting stack at its bottom ordinal. */
151
193
  private _getState;
152
- /** Get the depth of a URL that is the first page of a stack: `0` for the stack's root path or for the floating stack, else `1` so the root stays below it. */
153
- private _getBottomDepth;
194
+ /** Get the ordinal of a URL that is the first page of a stack: `0` for the stack's root path or for the floating stack, else `1` so the root stays below it. */
195
+ private _getBottomOrdinal;
154
196
  /** Get every stack a page can be in: the listed stacks, plus the floating stack (`null`). */
155
197
  private _getStacks;
156
198
  /** Get the path of a URL relative to the app root, or `undefined` if it is outside the app. */
157
199
  private _getPath;
158
- /** Direction of a change the store did not make: tab order across stacks, else depth, else position. */
200
+ /** Direction of a change the store did not make: tab order across stacks, else ordinal, else position. */
159
201
  private _getDirection;
160
202
  /** Slide direction between two stacks by tab order, or `undefined` for the same stack. */
161
203
  private _getOrder;
@@ -1,33 +1,36 @@
1
- import { Store } from "../../store/Store.js";
2
- import { URLStore } from "../../store/URLStore.js";
1
+ import { DeferredSequence } from "../../sequence/DeferredSequence.js";
2
+ import { createDeferred } from "../../util/async.js";
3
3
  import { BLACKHOLE } from "../../util/function.js";
4
- import { matchURLPrefix, requireURL } from "../../util/url.js";
4
+ import { getURL, matchURLPrefix, requireURL } from "../../util/url.js";
5
5
  /**
6
- * Store that holds the current navigation URL, drives browser history, and keeps a stack of pages for each tab.
6
+ * Sequence of navigation events that drives browser history and keeps a stack of pages for each tab.
7
7
  *
8
- * - Extends `URLStore`, so its `value` is the current URL.
8
+ * - 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.
9
+ * - `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`.
10
+ * - `publish()` sends an event by hand, for example to show the page below during a swipe-back.
9
11
  * - 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.
10
- * - `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.
11
12
  * - A page outside the listed stacks is floating: its stack is `null`. The floating stack has no root page and no tab.
12
- * - In a listed stack, depth `0` is always the stack's root path.
13
+ * - In a listed stack, ordinal `0` is always the stack's root path.
13
14
  * - 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.
14
15
  * - Owned by `<Navigation>`. Read it with `requireNavigation()`.
15
16
  *
16
- * @see https://shelving.cc/ui/NavigationStore
17
+ * @see https://shelving.cc/ui/NavigationSequence
17
18
  */
18
- export class NavigationStore extends URLStore {
19
+ export class NavigationSequence extends DeferredSequence {
19
20
  /** Root path of each stack, in tab order. With none, every page floats. */
20
21
  stacks;
21
22
  /**
22
- * Root path of the current stack, or `null` for a floating page.
23
- * - It starts at the `stack` given to the constructor (default `null`). Without the Navigation API, it stays there.
24
- */
25
- stack;
26
- /**
27
- * Transition type of the most recent change, read by `<Navigation>` when the value changes.
28
- * - `null` means no transition: a replace, a change the browser already animated (for example a swipe-back), or no Navigation API.
23
+ * Base URL of the app, used to resolve relative URLs and to work out paths.
24
+ *
25
+ * @see https://shelving.cc/ui/NavigationSequence/base
29
26
  */
30
- transition = null;
27
+ base;
28
+ /** URL the browser history is on now. */
29
+ _url;
30
+ /** Stack the browser history is on now. Without the Navigation API, it stays at the starting stack. */
31
+ _stack;
32
+ /** Callbacks waiting for `<Navigation>` to commit the next event. */
33
+ _waiting = [];
31
34
  /** The browser Navigation API, or `undefined` when it is not available. */
32
35
  _navigation;
33
36
  /** Transition sent with the next navigation, and whether the browser animates it. */
@@ -37,45 +40,80 @@ export class NavigationStore extends URLStore {
37
40
  /** Stack of the page the app opens at, when its history entry has no saved stack. */
38
41
  _start;
39
42
  constructor(url = typeof window === "undefined" ? "/" : window.location.href, base, stack = null, ...stacks) {
40
- super(url, base);
43
+ super();
44
+ this.base = getURL(base);
45
+ this._url = requireURL(url, this.base, NavigationSequence);
41
46
  this.stacks = stacks;
42
47
  this._start = stack !== null && stacks.includes(stack) ? stack : null;
43
48
  this._navigation = _getNavigation();
44
- this.stack = new Store(this._navigation ? this._getState(this._navigation.currentEntry).stack : this._start);
49
+ this._stack = this._navigation ? this._getState(this._navigation.currentEntry).stack : this._start;
45
50
  }
46
51
  /**
47
- * Path of the current URL relative to the app root (without its `?query`), or `undefined` if the URL is outside the app.
52
+ * URL the browser history is on now.
48
53
  *
49
- * @see https://shelving.cc/ui/NavigationStore/path
54
+ * @see https://shelving.cc/ui/NavigationSequence/url
50
55
  */
51
- get path() {
52
- return this._getPath(this.value);
56
+ get url() {
57
+ return this._url;
53
58
  }
54
59
  /**
55
- * Where the app is now: the current stack and depth, and the top depth of each stack.
60
+ * Root path of the stack the browser history is on now, or `null` for a floating page.
56
61
  *
57
- * @returns The position, or `undefined` without the Navigation API.
58
- * @see https://shelving.cc/ui/NavigationStore/position
62
+ * @see https://shelving.cc/ui/NavigationSequence/stack
59
63
  */
60
- get position() {
61
- if (!this._navigation)
62
- return undefined;
63
- const { stack, depth } = this._getState(this._navigation.currentEntry);
64
- const tops = new Map();
65
- for (const s of this._getStacks()) {
66
- const top = this._getPages(s).at(-1);
67
- if (top)
68
- tops.set(s, top.depth);
69
- }
70
- return { stack, depth, tops, parent: this.history(stack).at(-2) };
64
+ get stack() {
65
+ return this._stack;
66
+ }
67
+ /**
68
+ * Where the browser history is now, as an event with no direction.
69
+ * - `<Navigation>` reads it for its first render, and again when it starts listening, to catch up on changes it missed.
70
+ *
71
+ * @see https://shelving.cc/ui/NavigationSequence/current
72
+ */
73
+ current() {
74
+ const navigation = this._navigation;
75
+ return { url: this._url, stack: this._stack, ordinal: navigation ? this._getState(navigation.currentEntry).ordinal : undefined };
76
+ }
77
+ /**
78
+ * Publish an event by hand, without changing history.
79
+ * - For example, a swipe-back publishes the page below with `direction: "back"`, so React runs its back transition, and the swipe scrubs it.
80
+ * - Then the real `back()` publishes the same page again, which `<Navigation>` skips, or the swipe publishes the current page again to cancel.
81
+ *
82
+ * @param event The event to publish.
83
+ * @returns A promise that resolves when `<Navigation>` has committed the event.
84
+ * @see https://shelving.cc/ui/NavigationSequence/publish
85
+ */
86
+ publish(event) {
87
+ const { promise, resolve } = createDeferred();
88
+ this._waiting.push(resolve);
89
+ this.resolve(event);
90
+ return promise;
91
+ }
92
+ /**
93
+ * Tell waiting `publish()` calls that `<Navigation>` has committed a page.
94
+ * - `<Navigation>` calls it after each commit.
95
+ *
96
+ * @see https://shelving.cc/ui/NavigationSequence/committed
97
+ */
98
+ committed() {
99
+ for (const resolve of this._waiting.splice(0))
100
+ resolve();
101
+ }
102
+ /**
103
+ * Path of the current URL relative to the app root (without its `?query`), or `undefined` if the URL is outside the app.
104
+ *
105
+ * @see https://shelving.cc/ui/NavigationSequence/path
106
+ */
107
+ get path() {
108
+ return this._getPath(this._url);
71
109
  }
72
110
  /**
73
111
  * Start listening to the browser (back, forward and swipe).
74
- * - Saves the current stack and depth on the current history entry, if it has none.
112
+ * - Saves the current stack and ordinal on the current history entry, if it has none.
75
113
  * - `<Navigation>` calls it once, when it mounts.
76
114
  *
77
115
  * @returns A function that stops listening.
78
- * @see https://shelving.cc/ui/NavigationStore/listen
116
+ * @see https://shelving.cc/ui/NavigationSequence/listen
79
117
  */
80
118
  listen() {
81
119
  const navigation = this._navigation;
@@ -127,18 +165,18 @@ export class NavigationStore extends URLStore {
127
165
  * @param stack Root path of the stack, or `null` for the floating stack. Defaults to the current stack.
128
166
  * @returns Paths relative to the app root, each with its `?query`.
129
167
  * @example nav.history("/home") // ["/home", "/home/post/2"]
130
- * @see https://shelving.cc/ui/NavigationStore/history
168
+ * @see https://shelving.cc/ui/NavigationSequence/history
131
169
  */
132
- history(stack = this.stack.value) {
170
+ history(stack = this._stack) {
133
171
  const pages = this._getPages(stack);
134
172
  const paths = pages.map(p => _getPathWithQuery(p));
135
- if (stack !== null && pages[0] && pages[0].depth > 0)
173
+ if (stack !== null && pages[0] && pages[0].ordinal > 0)
136
174
  paths.unshift(stack);
137
175
  return paths;
138
176
  }
139
177
  /**
140
178
  * Go forward to a URL, as a link does.
141
- * - The URL is the top page of `stack`: switch to that stack, at the same depth. This is a tab switch.
179
+ * - The URL is the top page of `stack`: switch to that stack, at the same ordinal. This is a tab switch.
142
180
  * - Else push the URL onto `stack`, one level deeper than its top page.
143
181
  * - The URL you are already on: replace it instead.
144
182
  * - A change of stack slides by tab order. Else it slides forward.
@@ -147,57 +185,67 @@ export class NavigationStore extends URLStore {
147
185
  * @param stack Root path of the stack to go to, or `null` for the floating stack. Defaults to the current stack.
148
186
  * @throws RequiredError If `possible` cannot be resolved to a valid URL.
149
187
  * @example nav.forward("/settings");
150
- * @see https://shelving.cc/ui/NavigationStore/forward
188
+ * @see https://shelving.cc/ui/NavigationSequence/forward
151
189
  */
152
- forward(possible, stack = this.stack.value) {
190
+ forward(possible, stack = this._stack) {
153
191
  const url = requireURL(possible, this.base, this.forward);
154
192
  if (!this._navigation) {
155
193
  this._push(url, "forward");
156
194
  return;
157
195
  }
158
- const current = this.stack.value;
159
- if (stack === current && url.href === this.value.href) {
196
+ const current = this._stack;
197
+ if (stack === current && url.href === this._url.href) {
160
198
  this.replace(url);
161
199
  return;
162
200
  }
163
201
  const top = this._getPages(stack).at(-1);
164
- const depth = top ? (top.url.href === url.href ? top.depth : top.depth + 1) : this._getBottomDepth(url, stack);
165
- this._push(url, this._getOrder(current, stack) ?? "forward", { stack, depth });
202
+ const ordinal = top ? (top.url.href === url.href ? top.ordinal : top.ordinal + 1) : this._getBottomOrdinal(url, stack);
203
+ this._push(url, this._getOrder(current, stack) ?? "forward", { stack, ordinal });
166
204
  }
167
205
  /**
168
206
  * Go back to a URL, as a back button does.
169
- * - 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.
170
- * - The URL is the root of `stack`: push it at depth 0.
207
+ * - 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.
208
+ * - The URL is the root of `stack`: push it at ordinal 0.
171
209
  * - Else push the URL in place of the top page of `stack`.
172
210
  * - It works when the app was opened at the current page, so a back button always has somewhere to go.
211
+ * - If the browser refuses to go back with the Navigation API, it uses `history.back()`.
173
212
  *
174
213
  * @param possible The destination URL, resolved against `base`.
175
214
  * @param stack Root path of the stack to go back in, or `null` for the floating stack. Defaults to the current stack.
176
215
  * @throws RequiredError If `possible` cannot be resolved to a valid URL.
177
216
  * @example nav.back("/profile");
178
- * @see https://shelving.cc/ui/NavigationStore/back
217
+ * @see https://shelving.cc/ui/NavigationSequence/back
179
218
  */
180
- back(possible, stack = this.stack.value) {
219
+ back(possible, stack = this._stack) {
181
220
  const url = requireURL(possible, this.base, this.back);
182
221
  const navigation = this._navigation;
183
222
  if (!navigation) {
184
223
  this._push(url, "back");
185
224
  return;
186
225
  }
187
- const current = this.stack.value;
226
+ const current = this._stack;
188
227
  const pages = this._getPages(stack);
189
228
  const page = pages.slice(0, -1).findLast(p => p.url.href === url.href);
190
229
  if (page && stack === current && page.index === (navigation.currentEntry?.index ?? 0) - 1) {
191
- navigation.traverseTo(page.key, { info: this._getOrder(current, stack) ?? "back" }).finished?.catch(BLACKHOLE);
230
+ // Some browsers refuse `traverseTo()` in some frames (Safari throws `SecurityError` in a sandboxed iframe), so fall back to `history.back()`.
231
+ const fallback = (e) => void (_isAbort(e) || window.history.back());
232
+ try {
233
+ const result = navigation.traverseTo(page.key, { info: this._getOrder(current, stack) ?? "back" });
234
+ result.committed?.catch(fallback);
235
+ result.finished?.catch(BLACKHOLE);
236
+ }
237
+ catch (e) {
238
+ fallback(e);
239
+ }
192
240
  return;
193
241
  }
194
242
  // The URL is an earlier page in the stack, else the root of the stack, else it takes the place of the top page.
195
- const depth = page ? page.depth : this._getPath(url) === stack ? 0 : (pages.at(-1)?.depth ?? this._getBottomDepth(url, stack));
196
- this._push(url, this._getOrder(current, stack) ?? "back", { stack, depth });
243
+ const ordinal = page ? page.ordinal : this._getPath(url) === stack ? 0 : (pages.at(-1)?.ordinal ?? this._getBottomOrdinal(url, stack));
244
+ this._push(url, this._getOrder(current, stack) ?? "back", { stack, ordinal });
197
245
  }
198
246
  /**
199
247
  * Replace the current URL, with no transition.
200
- * - The page stays in the same stack, at the same depth, so a cached page stays mounted.
248
+ * - The page stays in the same stack, at the same ordinal, so a cached page stays mounted.
201
249
  * - Use it for a page that knows its canonical URL, or for in-page tabs.
202
250
  * - 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")`.
203
251
  *
@@ -205,9 +253,9 @@ export class NavigationStore extends URLStore {
205
253
  * @param stack Root path of the stack to move the page into, or `null` for the floating stack. Defaults to the current stack.
206
254
  * @throws RequiredError If `possible` cannot be resolved to a valid URL.
207
255
  * @example nav.replace("/login");
208
- * @see https://shelving.cc/ui/NavigationStore/replace
256
+ * @see https://shelving.cc/ui/NavigationSequence/replace
209
257
  */
210
- replace(possible, stack = this.stack.value) {
258
+ replace(possible, stack = this._stack) {
211
259
  const url = requireURL(possible, this.base, this.replace);
212
260
  const saved = this._navigation?.currentEntry?.getState();
213
261
  let state = _isEntryState(saved) ? saved : undefined;
@@ -215,7 +263,7 @@ export class NavigationStore extends URLStore {
215
263
  const top = this._getPages(stack)
216
264
  .filter(p => p.index !== this._navigation?.currentEntry?.index)
217
265
  .at(-1);
218
- state = { stack, depth: this._getPath(url) === stack ? 0 : top ? top.depth + 1 : this._getBottomDepth(url, stack) };
266
+ state = { stack, ordinal: this._getPath(url) === stack ? 0 : top ? top.ordinal + 1 : this._getBottomOrdinal(url, stack) };
219
267
  }
220
268
  this._write(() => window.history.replaceState(null, "", url.href), state);
221
269
  this._change(url, null, state?.stack);
@@ -248,47 +296,47 @@ export class NavigationStore extends URLStore {
248
296
  this._busy = busy;
249
297
  }
250
298
  }
251
- /** Set the stack first, then the URL, so both are ready when `<Navigation>` reads them. */
252
- _change(url, transition, stack) {
253
- this.transition = transition;
299
+ /** Record where history is now, and publish it as an event. */
300
+ _change(url, direction, stack) {
301
+ this._url = requireURL(url, this.base, this._change);
254
302
  if (stack !== undefined)
255
- this.stack.value = stack;
256
- this.value = url;
303
+ this._stack = stack;
304
+ this.resolve({ ...this.current(), direction: direction ?? undefined });
257
305
  }
258
- /** Get the pages in a stack, root first: the newest entry in the stack, then the newest earlier entry at a lower depth, down to depth 0. */
306
+ /** Get the pages in a stack, root first: the newest entry in the stack, then the newest earlier entry at a lower ordinal, down to ordinal 0. */
259
307
  _getPages(stack) {
260
308
  const navigation = this._navigation;
261
309
  if (!navigation)
262
310
  return [];
263
311
  const entries = navigation.entries();
264
312
  const pages = [];
265
- let depth = Number.POSITIVE_INFINITY;
313
+ let ordinal = Number.POSITIVE_INFINITY;
266
314
  const current = navigation.currentEntry?.index ?? -1;
267
- for (let i = current; i >= 0 && depth > 0; i--) {
315
+ for (let i = current; i >= 0 && ordinal > 0; i--) {
268
316
  const entry = entries[i];
269
317
  // The current entry may not have its state saved yet (before `listen()`), so use its default.
270
318
  const state = i === current && entry ? this._getState(entry) : entry?.getState();
271
- if (!entry?.url || !_isEntryState(state) || state.stack !== stack || state.depth >= depth)
319
+ if (!entry?.url || !_isEntryState(state) || state.stack !== stack || state.ordinal >= ordinal)
272
320
  continue;
273
321
  const url = requireURL(entry.url, undefined, this._getPages);
274
322
  const path = this._getPath(url);
275
323
  if (!path)
276
324
  continue;
277
- depth = state.depth;
325
+ ordinal = state.ordinal;
278
326
  pages.unshift({ ...state, url, path, index: entry.index, key: entry.key });
279
327
  }
280
328
  return pages;
281
329
  }
282
- /** Get the saved state of an entry, or for an entry with none (for example the page the app opened at), the starting stack at its bottom depth. */
330
+ /** Get the saved state of an entry, or for an entry with none (for example the page the app opened at), the starting stack at its bottom ordinal. */
283
331
  _getState(entry) {
284
332
  const state = entry?.getState();
285
333
  if (_isEntryState(state) && this._getStacks().includes(state.stack))
286
334
  return state;
287
335
  const url = entry?.url ? requireURL(entry.url, undefined, this._getState) : undefined;
288
- return { stack: this._start, depth: url ? this._getBottomDepth(url, this._start) : 0 };
336
+ return { stack: this._start, ordinal: url ? this._getBottomOrdinal(url, this._start) : 0 };
289
337
  }
290
- /** Get the depth of a URL that is the first page of a stack: `0` for the stack's root path or for the floating stack, else `1` so the root stays below it. */
291
- _getBottomDepth(url, stack) {
338
+ /** Get the ordinal of a URL that is the first page of a stack: `0` for the stack's root path or for the floating stack, else `1` so the root stays below it. */
339
+ _getBottomOrdinal(url, stack) {
292
340
  return stack === null || this._getPath(url) === stack ? 0 : 1;
293
341
  }
294
342
  /** Get every stack a page can be in: the listed stacks, plus the floating stack (`null`). */
@@ -299,7 +347,7 @@ export class NavigationStore extends URLStore {
299
347
  _getPath(url) {
300
348
  return matchURLPrefix(url, this.base ?? new URL("/", url));
301
349
  }
302
- /** Direction of a change the store did not make: tab order across stacks, else depth, else position. */
350
+ /** Direction of a change the store did not make: tab order across stacks, else ordinal, else position. */
303
351
  _getDirection(e) {
304
352
  if (e.navigationType !== "traverse")
305
353
  return null;
@@ -308,8 +356,8 @@ export class NavigationStore extends URLStore {
308
356
  const order = this._getOrder(from.stack, to.stack);
309
357
  if (order)
310
358
  return order;
311
- if (to.depth !== from.depth)
312
- return to.depth < from.depth ? "back" : "forward";
359
+ if (to.ordinal !== from.ordinal)
360
+ return to.ordinal < from.ordinal ? "back" : "forward";
313
361
  return (this._navigation?.currentEntry?.index ?? 0) < e.from.index ? "back" : "forward";
314
362
  }
315
363
  /** Slide direction between two stacks by tab order, or `undefined` for the same stack. */
@@ -341,6 +389,10 @@ function _isEntryState(state) {
341
389
  state !== null &&
342
390
  "stack" in state &&
343
391
  (typeof state.stack === "string" || state.stack === null) &&
344
- "depth" in state &&
345
- typeof state.depth === "number");
392
+ "ordinal" in state &&
393
+ typeof state.ordinal === "number");
394
+ }
395
+ /** Is an error a navigation that was stopped by a newer one? That is not a failure, so it needs no fallback. */
396
+ function _isAbort(e) {
397
+ return e instanceof Error && e.name === "AbortError";
346
398
  }