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.
- package/docs/guides/building-with-shelving.md +3 -3
- package/docs/llms-full.txt +345 -149
- package/docs/react/SequenceTransitionOptions.md +24 -0
- package/docs/react/useSequenceTransition.md +70 -0
- package/docs/react.md +2 -0
- package/docs/ui/BackButton.md +1 -1
- package/docs/ui/Head.md +1 -1
- package/docs/ui/HorizontalTransition.md +1 -1
- package/docs/ui/Image.md +3 -0
- package/docs/ui/Meta.md +2 -0
- package/docs/ui/Navigation.md +18 -17
- package/docs/ui/NavigationContext.md +2 -2
- package/docs/ui/NavigationDirection.md +12 -0
- package/docs/ui/NavigationEntryState.md +3 -3
- package/docs/ui/NavigationEvent.md +28 -0
- package/docs/ui/{NavigationStore → NavigationSequence}/back.md +6 -5
- package/docs/ui/NavigationSequence/committed.md +13 -0
- package/docs/ui/NavigationSequence/current.md +13 -0
- package/docs/ui/{NavigationStore → NavigationSequence}/forward.md +4 -4
- package/docs/ui/{NavigationStore → NavigationSequence}/history.md +3 -3
- package/docs/ui/{NavigationStore → NavigationSequence}/listen.md +3 -3
- package/docs/ui/NavigationSequence/publish.md +14 -0
- package/docs/ui/{NavigationStore → NavigationSequence}/replace.md +4 -4
- package/docs/ui/NavigationSequence.md +187 -0
- package/docs/ui/RouteCache.md +16 -15
- package/docs/ui/RouteCacheProps.md +1 -1
- package/docs/ui/Router.md +2 -2
- package/docs/ui/Transition.md +1 -1
- package/docs/ui/VerticalTransition.md +1 -1
- package/docs/ui/mergeMeta.md +1 -0
- package/docs/ui/requireContext.md +1 -1
- package/docs/ui/requireNavigation.md +3 -3
- package/docs/ui.md +6 -6
- package/package.json +1 -1
- package/react/index.d.ts +1 -0
- package/react/index.js +1 -0
- package/react/useSequenceTransition.d.ts +38 -0
- package/react/useSequenceTransition.js +44 -0
- package/ui/block/Image.d.ts +3 -0
- package/ui/block/Image.js +18 -1
- package/ui/block/Image.module.css +27 -0
- package/ui/block/Image.tsx +24 -1
- package/ui/page/Head.d.ts +1 -1
- package/ui/page/Head.js +9 -4
- package/ui/page/Head.tsx +8 -4
- package/ui/router/BackButton.js +6 -3
- package/ui/router/BackButton.md +1 -1
- package/ui/router/BackButton.tsx +6 -3
- package/ui/router/Navigation.d.ts +5 -5
- package/ui/router/Navigation.js +24 -49
- package/ui/router/Navigation.md +13 -12
- package/ui/router/Navigation.tsx +25 -59
- package/ui/router/NavigationContext.d.ts +7 -15
- package/ui/router/NavigationContext.js +4 -13
- package/ui/router/NavigationContext.tsx +7 -17
- package/ui/router/{NavigationStore.d.ts → NavigationSequence.d.ts} +93 -51
- package/ui/router/{NavigationStore.js → NavigationSequence.js} +132 -80
- package/ui/router/NavigationSequence.md +129 -0
- package/ui/router/{NavigationStore.test.ts → NavigationSequence.test.ts} +126 -61
- package/ui/router/{NavigationStore.tsx → NavigationSequence.tsx} +160 -92
- package/ui/router/RouteCache.d.ts +8 -7
- package/ui/router/RouteCache.js +34 -29
- package/ui/router/RouteCache.md +9 -8
- package/ui/router/RouteCache.tsx +39 -36
- package/ui/router/Router.d.ts +2 -2
- package/ui/router/Router.js +3 -5
- package/ui/router/Router.md +1 -1
- package/ui/router/Router.tsx +4 -5
- package/ui/router/StackButton.d.ts +1 -1
- package/ui/router/StackButton.js +5 -7
- package/ui/router/StackButton.tsx +6 -7
- package/ui/router/index.d.ts +1 -1
- package/ui/router/index.js +1 -1
- package/ui/router/index.ts +1 -1
- package/ui/transition/HorizontalTransition.md +1 -1
- package/ui/transition/Transition.md +1 -1
- package/ui/transition/VerticalTransition.md +1 -1
- package/ui/util/meta.d.ts +2 -0
- package/ui/util/meta.ts +2 -0
- package/ui/util/requireContext.md +1 -1
- package/docs/ui/NavigationPosition.md +0 -24
- package/docs/ui/NavigationPositionContext.md +0 -8
- package/docs/ui/NavigationStore.md +0 -164
- package/ui/router/NavigationStore.md +0 -110
|
@@ -1,10 +1,8 @@
|
|
|
1
|
-
import {
|
|
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 `
|
|
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
|
|
13
|
+
readonly ordinal: number;
|
|
16
14
|
}
|
|
17
15
|
/**
|
|
18
|
-
*
|
|
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/
|
|
18
|
+
* @see https://shelving.cc/ui/NavigationDirection
|
|
22
19
|
*/
|
|
23
|
-
export
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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
|
-
*
|
|
39
|
+
* Sequence of navigation events that drives browser history and keeps a stack of pages for each tab.
|
|
31
40
|
*
|
|
32
|
-
* -
|
|
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,
|
|
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/
|
|
50
|
+
* @see https://shelving.cc/ui/NavigationSequence
|
|
41
51
|
*/
|
|
42
|
-
export declare class
|
|
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
|
-
*
|
|
47
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
77
|
+
* URL the browser history is on now.
|
|
66
78
|
*
|
|
67
|
-
* @see https://shelving.cc/ui/
|
|
79
|
+
* @see https://shelving.cc/ui/NavigationSequence/url
|
|
68
80
|
*/
|
|
69
|
-
get
|
|
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
|
|
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
|
-
* @
|
|
74
|
-
* @see https://shelving.cc/ui/NavigationStore/position
|
|
92
|
+
* @see https://shelving.cc/ui/NavigationSequence/current
|
|
75
93
|
*/
|
|
76
|
-
|
|
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
|
|
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/
|
|
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/
|
|
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
|
|
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/
|
|
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
|
|
116
|
-
* - The URL is the root of `stack`: push it at
|
|
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/
|
|
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
|
|
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/
|
|
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
|
-
/**
|
|
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
|
|
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
|
|
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
|
|
153
|
-
private
|
|
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
|
|
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 {
|
|
2
|
-
import {
|
|
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
|
-
*
|
|
6
|
+
* Sequence of navigation events that drives browser history and keeps a stack of pages for each tab.
|
|
7
7
|
*
|
|
8
|
-
* -
|
|
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,
|
|
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/
|
|
17
|
+
* @see https://shelving.cc/ui/NavigationSequence
|
|
17
18
|
*/
|
|
18
|
-
export class
|
|
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
|
-
*
|
|
23
|
-
*
|
|
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
|
-
|
|
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(
|
|
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.
|
|
49
|
+
this._stack = this._navigation ? this._getState(this._navigation.currentEntry).stack : this._start;
|
|
45
50
|
}
|
|
46
51
|
/**
|
|
47
|
-
*
|
|
52
|
+
* URL the browser history is on now.
|
|
48
53
|
*
|
|
49
|
-
* @see https://shelving.cc/ui/
|
|
54
|
+
* @see https://shelving.cc/ui/NavigationSequence/url
|
|
50
55
|
*/
|
|
51
|
-
get
|
|
52
|
-
return this.
|
|
56
|
+
get url() {
|
|
57
|
+
return this._url;
|
|
53
58
|
}
|
|
54
59
|
/**
|
|
55
|
-
*
|
|
60
|
+
* Root path of the stack the browser history is on now, or `null` for a floating page.
|
|
56
61
|
*
|
|
57
|
-
* @
|
|
58
|
-
* @see https://shelving.cc/ui/NavigationStore/position
|
|
62
|
+
* @see https://shelving.cc/ui/NavigationSequence/stack
|
|
59
63
|
*/
|
|
60
|
-
get
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
|
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/
|
|
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/
|
|
168
|
+
* @see https://shelving.cc/ui/NavigationSequence/history
|
|
131
169
|
*/
|
|
132
|
-
history(stack = this.
|
|
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].
|
|
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
|
|
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/
|
|
188
|
+
* @see https://shelving.cc/ui/NavigationSequence/forward
|
|
151
189
|
*/
|
|
152
|
-
forward(possible, stack = this.
|
|
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.
|
|
159
|
-
if (stack === current && url.href === this.
|
|
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
|
|
165
|
-
this._push(url, this._getOrder(current, stack) ?? "forward", { stack,
|
|
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
|
|
170
|
-
* - The URL is the root of `stack`: push it at
|
|
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/
|
|
217
|
+
* @see https://shelving.cc/ui/NavigationSequence/back
|
|
179
218
|
*/
|
|
180
|
-
back(possible, stack = this.
|
|
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.
|
|
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
|
-
|
|
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
|
|
196
|
-
this._push(url, this._getOrder(current, stack) ?? "back", { stack,
|
|
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
|
|
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/
|
|
256
|
+
* @see https://shelving.cc/ui/NavigationSequence/replace
|
|
209
257
|
*/
|
|
210
|
-
replace(possible, stack = this.
|
|
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,
|
|
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
|
-
/**
|
|
252
|
-
_change(url,
|
|
253
|
-
this.
|
|
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.
|
|
256
|
-
this.
|
|
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
|
|
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
|
|
313
|
+
let ordinal = Number.POSITIVE_INFINITY;
|
|
266
314
|
const current = navigation.currentEntry?.index ?? -1;
|
|
267
|
-
for (let i = current; i >= 0 &&
|
|
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.
|
|
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
|
-
|
|
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
|
|
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,
|
|
336
|
+
return { stack: this._start, ordinal: url ? this._getBottomOrdinal(url, this._start) : 0 };
|
|
289
337
|
}
|
|
290
|
-
/** Get the
|
|
291
|
-
|
|
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
|
|
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.
|
|
312
|
-
return to.
|
|
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
|
-
"
|
|
345
|
-
typeof state.
|
|
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
|
}
|