shelving 1.319.1 → 1.321.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 +26 -0
- package/docs/llms-full.txt +752 -265
- package/docs/ui/BackButton.md +75 -0
- package/docs/ui/BackButtonProps.md +21 -0
- package/docs/ui/ClickableProps.md +0 -2
- package/docs/ui/FADE_TRANSITION_CLASS.md +9 -0
- package/docs/ui/FadeTransition.md +13 -0
- package/docs/ui/Head.md +2 -2
- package/docs/ui/HorizontalTransition.md +21 -5
- package/docs/ui/LinkClickable.md +0 -1
- package/docs/ui/Meta.md +3 -1
- package/docs/ui/Navigation.md +93 -37
- package/docs/ui/NavigationEntryState.md +22 -0
- package/docs/ui/NavigationPosition.md +24 -0
- package/docs/ui/NavigationPositionContext.md +8 -0
- package/docs/ui/NavigationProps.md +12 -2
- package/docs/ui/NavigationStore/back.md +6 -4
- package/docs/ui/NavigationStore/forward.md +6 -2
- package/docs/ui/NavigationStore/history.md +15 -0
- package/docs/ui/NavigationStore/listen.md +14 -0
- package/docs/ui/NavigationStore/replace.md +15 -0
- package/docs/ui/NavigationStore.md +100 -19
- package/docs/ui/RouteCache.md +72 -36
- package/docs/ui/RouteCacheProps.md +3 -3
- package/docs/ui/Router.md +4 -2
- package/docs/ui/SLIDE_DOWN_TRANSITION_CLASS.md +9 -0
- package/docs/ui/SLIDE_LEFT_TRANSITION_CLASS.md +9 -0
- package/docs/ui/SLIDE_RIGHT_TRANSITION_CLASS.md +9 -0
- package/docs/ui/SLIDE_UP_TRANSITION_CLASS.md +9 -0
- package/docs/ui/StackButton.md +64 -0
- package/docs/ui/StackButtonProps.md +21 -0
- package/docs/ui/VerticalTransition.md +21 -5
- package/docs/ui/mergeMeta.md +2 -1
- package/docs/ui.md +18 -10
- package/package.json +1 -1
- package/ui/button/Clickable.d.ts +1 -3
- package/ui/button/Clickable.js +2 -2
- package/ui/button/Clickable.tsx +0 -4
- package/ui/dialog/Dialog.d.ts +0 -1
- package/ui/dialog/Dialog.js +2 -2
- package/ui/dialog/Dialog.tsx +2 -2
- package/ui/notice/NoticesTransition.module.css +1 -1
- package/ui/page/Head.d.ts +2 -2
- package/ui/page/Head.js +9 -8
- package/ui/page/Head.tsx +8 -6
- package/ui/router/BackButton.d.ts +22 -0
- package/ui/router/BackButton.js +19 -0
- package/ui/router/BackButton.md +47 -0
- package/ui/router/BackButton.tsx +34 -0
- package/ui/router/Navigation.d.ts +22 -12
- package/ui/router/Navigation.js +67 -51
- package/ui/router/Navigation.md +84 -27
- package/ui/router/Navigation.test.tsx +27 -7
- package/ui/router/Navigation.tsx +90 -53
- package/ui/router/NavigationContext.d.ts +9 -1
- package/ui/router/NavigationContext.js +9 -0
- package/ui/router/NavigationContext.tsx +11 -1
- package/ui/router/NavigationStore.d.ts +126 -19
- package/ui/router/NavigationStore.js +301 -30
- package/ui/router/NavigationStore.md +82 -9
- package/ui/router/NavigationStore.test.ts +384 -0
- package/ui/router/NavigationStore.tsx +347 -30
- package/ui/router/RouteCache.d.ts +15 -22
- package/ui/router/RouteCache.js +36 -47
- package/ui/router/RouteCache.md +59 -16
- package/ui/router/RouteCache.tsx +55 -62
- package/ui/router/Router.d.ts +2 -1
- package/ui/router/Router.js +9 -14
- package/ui/router/Router.md +2 -1
- package/ui/router/Router.tsx +9 -20
- package/ui/router/StackButton.d.ts +24 -0
- package/ui/router/StackButton.js +35 -0
- package/ui/router/StackButton.md +34 -0
- package/ui/router/StackButton.tsx +44 -0
- package/ui/router/index.d.ts +2 -2
- package/ui/router/index.js +2 -2
- package/ui/router/index.ts +2 -2
- package/ui/transition/FadeTransition.d.ts +9 -1
- package/ui/transition/FadeTransition.js +12 -2
- package/ui/transition/FadeTransition.md +13 -0
- package/ui/transition/{FadeTransition.css → FadeTransition.module.css} +9 -2
- package/ui/transition/FadeTransition.tsx +13 -2
- package/ui/transition/HorizontalTransition.d.ts +18 -1
- package/ui/transition/HorizontalTransition.js +21 -2
- package/ui/transition/HorizontalTransition.md +21 -5
- package/ui/transition/{HorizontalTransition.css → HorizontalTransition.module.css} +17 -5
- package/ui/transition/HorizontalTransition.tsx +30 -2
- package/ui/transition/VerticalTransition.d.ts +18 -1
- package/ui/transition/VerticalTransition.js +21 -2
- package/ui/transition/VerticalTransition.md +21 -5
- package/ui/transition/{VerticalTransition.css → VerticalTransition.module.css} +17 -5
- package/ui/transition/VerticalTransition.tsx +25 -2
- package/ui/util/meta.d.ts +4 -1
- package/ui/util/meta.ts +4 -1
- package/docs/ui/NavigationStore/redirect.md +0 -12
- package/docs/ui/RouteConfig.md +0 -75
- package/docs/ui/RouteConfigProps.md +0 -24
- package/docs/ui/RouteContext.md +0 -6
- package/docs/ui/RouteState.md +0 -30
- package/ui/router/RouteConfig.d.ts +0 -28
- package/ui/router/RouteConfig.js +0 -30
- package/ui/router/RouteConfig.md +0 -42
- package/ui/router/RouteConfig.tsx +0 -44
- package/ui/router/RouteContext.d.ts +0 -22
- package/ui/router/RouteContext.js +0 -8
- package/ui/router/RouteContext.tsx +0 -26
|
@@ -1,60 +1,331 @@
|
|
|
1
|
+
import { Store } from "../../store/Store.js";
|
|
1
2
|
import { URLStore } from "../../store/URLStore.js";
|
|
2
|
-
import {
|
|
3
|
+
import { BLACKHOLE } from "../../util/function.js";
|
|
4
|
+
import { matchURLPrefix, requireURL } from "../../util/url.js";
|
|
3
5
|
/**
|
|
4
|
-
* Store
|
|
6
|
+
* Store that holds the current navigation URL, drives browser history, and keeps a stack of pages for each tab.
|
|
5
7
|
*
|
|
6
|
-
* - Extends `URLStore
|
|
7
|
-
* -
|
|
8
|
-
* - `
|
|
9
|
-
* -
|
|
8
|
+
* - Extends `URLStore`, so its `value` is the current URL.
|
|
9
|
+
* - 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. It only changes when the stack changes.
|
|
11
|
+
* - 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.
|
|
12
|
+
* - Owned by `<Navigation>`. Read it with `requireNavigation()`.
|
|
10
13
|
*
|
|
11
14
|
* @see https://shelving.cc/ui/NavigationStore
|
|
12
15
|
*/
|
|
13
16
|
export class NavigationStore extends URLStore {
|
|
14
|
-
/**
|
|
15
|
-
|
|
16
|
-
|
|
17
|
+
/** Root path of each stack, in tab order. A single-stack app has one root. */
|
|
18
|
+
stacks;
|
|
19
|
+
/**
|
|
20
|
+
* Root path of the current stack.
|
|
21
|
+
* - Always set. With no `stacks`, it is `"/"`.
|
|
22
|
+
* - It starts at the `stack` given to the constructor (default `"/"`). Without the Navigation API, it stays there.
|
|
23
|
+
*/
|
|
24
|
+
stack;
|
|
25
|
+
/**
|
|
26
|
+
* Transition type of the most recent change, read by `<Navigation>` when the value changes.
|
|
27
|
+
* - `null` means no transition: a replace, a change the browser already animated (for example a swipe-back), or no Navigation API.
|
|
28
|
+
*/
|
|
29
|
+
transition = null;
|
|
30
|
+
/** The browser Navigation API, or `undefined` when it is not available. */
|
|
31
|
+
_navigation;
|
|
32
|
+
/** Transition sent with the next navigation, and whether the browser animates it. */
|
|
33
|
+
_info = undefined;
|
|
34
|
+
/** `true` while the store changes history itself, so it ignores the events that causes. */
|
|
35
|
+
_busy = false;
|
|
36
|
+
/** Stack of the page the app opens at, when its history entry has no saved stack. */
|
|
37
|
+
_start;
|
|
38
|
+
constructor(url = typeof window === "undefined" ? "/" : window.location.href, base, stack = "/", ...stacks) {
|
|
17
39
|
super(url, base);
|
|
40
|
+
this.stacks = stacks.length ? stacks : ["/"];
|
|
41
|
+
this._start = stack;
|
|
42
|
+
this._navigation = _getNavigation();
|
|
43
|
+
this.stack = new Store(this._navigation ? this._getState(this._navigation.currentEntry).stack : stack);
|
|
18
44
|
}
|
|
19
45
|
/**
|
|
20
|
-
*
|
|
46
|
+
* Where the app is now: the current stack and depth, and the top depth of each stack.
|
|
47
|
+
*
|
|
48
|
+
* @returns The position, or `undefined` without the Navigation API.
|
|
49
|
+
* @see https://shelving.cc/ui/NavigationStore/position
|
|
50
|
+
*/
|
|
51
|
+
get position() {
|
|
52
|
+
if (!this._navigation)
|
|
53
|
+
return undefined;
|
|
54
|
+
const { stack, depth } = this._getState(this._navigation.currentEntry);
|
|
55
|
+
const tops = {};
|
|
56
|
+
for (const s of this._getStacks()) {
|
|
57
|
+
const top = this._getPages(s).at(-1);
|
|
58
|
+
if (top)
|
|
59
|
+
tops[s] = top.depth;
|
|
60
|
+
}
|
|
61
|
+
return { stack, depth, tops, parent: this.history(stack).at(-2) };
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Start listening to the browser (back, forward and swipe).
|
|
65
|
+
* - Saves the current stack and depth on the current history entry, if it has none.
|
|
66
|
+
* - `<Navigation>` calls it once, when it mounts.
|
|
67
|
+
*
|
|
68
|
+
* @returns A function that stops listening.
|
|
69
|
+
* @see https://shelving.cc/ui/NavigationStore/listen
|
|
70
|
+
*/
|
|
71
|
+
listen() {
|
|
72
|
+
const navigation = this._navigation;
|
|
73
|
+
if (!navigation) {
|
|
74
|
+
if (typeof window === "undefined")
|
|
75
|
+
return BLACKHOLE;
|
|
76
|
+
const onPopState = () => this._change(window.location.href, null);
|
|
77
|
+
window.addEventListener("popstate", onPopState);
|
|
78
|
+
return () => window.removeEventListener("popstate", onPopState);
|
|
79
|
+
}
|
|
80
|
+
// Save the state of the entry the app opened at.
|
|
81
|
+
const { currentEntry } = navigation;
|
|
82
|
+
if (currentEntry && !_isEntryState(currentEntry.getState()))
|
|
83
|
+
this._update(this._getState(currentEntry));
|
|
84
|
+
const onNavigate = (e) => {
|
|
85
|
+
const info = e.info;
|
|
86
|
+
this._info = e.hasUAVisualTransition ? null : info === "forward" || info === "back" ? info : undefined;
|
|
87
|
+
};
|
|
88
|
+
const onChange = (e) => {
|
|
89
|
+
if (this._busy)
|
|
90
|
+
return;
|
|
91
|
+
const entry = navigation.currentEntry;
|
|
92
|
+
if (!entry?.url)
|
|
93
|
+
return;
|
|
94
|
+
// Another script replaced the entry with no state (for example `history.replaceState()`), so put the old state back.
|
|
95
|
+
if (e.navigationType === "replace" && !_isEntryState(entry.getState())) {
|
|
96
|
+
const from = e.from.getState();
|
|
97
|
+
if (_isEntryState(from))
|
|
98
|
+
this._update(from);
|
|
99
|
+
}
|
|
100
|
+
const info = this._info;
|
|
101
|
+
this._info = undefined;
|
|
102
|
+
this._change(entry.url, info === undefined ? this._getDirection(e) : info, this._getState(entry).stack);
|
|
103
|
+
};
|
|
104
|
+
navigation.addEventListener("navigate", onNavigate);
|
|
105
|
+
navigation.addEventListener("currententrychange", onChange);
|
|
106
|
+
return () => {
|
|
107
|
+
navigation.removeEventListener("navigate", onNavigate);
|
|
108
|
+
navigation.removeEventListener("currententrychange", onChange);
|
|
109
|
+
};
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Get the pages in a stack, root first, or every page in every stack.
|
|
113
|
+
* - Read from the browser history entries up to the current one.
|
|
114
|
+
* - A stack whose root entry is gone (the browser keeps a limited history) still starts with its root.
|
|
115
|
+
* - Without the Navigation API this is always empty.
|
|
116
|
+
*
|
|
117
|
+
* @param stack Root path of the stack. Defaults to the current stack.
|
|
118
|
+
* @returns Paths relative to the app root, each with its `?query`.
|
|
119
|
+
* @example nav.history("/home") // ["/home", "/home/post/2"]
|
|
120
|
+
* @see https://shelving.cc/ui/NavigationStore/history
|
|
121
|
+
*/
|
|
122
|
+
history(stack = this.stack.value) {
|
|
123
|
+
const pages = this._getPages(stack);
|
|
124
|
+
const paths = pages.map(p => _getPathWithQuery(p));
|
|
125
|
+
if (pages[0] && pages[0].depth > 0)
|
|
126
|
+
paths.unshift(stack);
|
|
127
|
+
return paths;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Go forward to a URL, as a link does.
|
|
131
|
+
* - The URL is the top page of `stack`: switch to that stack, at the same depth. This is a tab switch.
|
|
132
|
+
* - Else push the URL onto `stack`, one level deeper than its top page.
|
|
133
|
+
* - The URL you are already on: replace it instead.
|
|
134
|
+
* - A change of stack slides by tab order. Else it slides forward.
|
|
21
135
|
*
|
|
22
136
|
* @param possible The destination URL, resolved against `base`.
|
|
137
|
+
* @param stack Root path of the stack to go to. Defaults to the current stack.
|
|
23
138
|
* @throws RequiredError If `possible` cannot be resolved to a valid URL.
|
|
24
139
|
* @example nav.forward("/settings");
|
|
25
140
|
* @see https://shelving.cc/ui/NavigationStore/forward
|
|
26
141
|
*/
|
|
27
|
-
forward(possible) {
|
|
28
|
-
this.
|
|
29
|
-
|
|
30
|
-
|
|
142
|
+
forward(possible, stack = this.stack.value) {
|
|
143
|
+
const url = requireURL(possible, this.base, this.forward);
|
|
144
|
+
if (!this._navigation) {
|
|
145
|
+
this._push(url, "forward");
|
|
146
|
+
return;
|
|
147
|
+
}
|
|
148
|
+
const current = this.stack.value;
|
|
149
|
+
if (stack === current && url.href === this.value.href) {
|
|
150
|
+
this.replace(url);
|
|
151
|
+
return;
|
|
152
|
+
}
|
|
153
|
+
const top = this._getPages(stack).at(-1);
|
|
154
|
+
const depth = top ? (top.url.href === url.href ? top.depth : top.depth + 1) : 0;
|
|
155
|
+
this._push(url, this._getOrder(current, stack) ?? "forward", { stack, depth });
|
|
31
156
|
}
|
|
32
157
|
/**
|
|
33
|
-
*
|
|
158
|
+
* Go back to a URL, as a back button does.
|
|
159
|
+
* - 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.
|
|
160
|
+
* - The URL is the root of `stack`: push it at depth 0.
|
|
161
|
+
* - Else push the URL in place of the top page of `stack`.
|
|
162
|
+
* - It works when the app was opened at the current page, so a back button always has somewhere to go.
|
|
34
163
|
*
|
|
35
164
|
* @param possible The destination URL, resolved against `base`.
|
|
165
|
+
* @param stack Root path of the stack to go back in. Defaults to the current stack.
|
|
36
166
|
* @throws RequiredError If `possible` cannot be resolved to a valid URL.
|
|
37
|
-
* @example nav.
|
|
38
|
-
* @see https://shelving.cc/ui/NavigationStore/
|
|
167
|
+
* @example nav.back("/profile");
|
|
168
|
+
* @see https://shelving.cc/ui/NavigationStore/back
|
|
39
169
|
*/
|
|
40
|
-
|
|
41
|
-
this.
|
|
42
|
-
|
|
43
|
-
|
|
170
|
+
back(possible, stack = this.stack.value) {
|
|
171
|
+
const url = requireURL(possible, this.base, this.back);
|
|
172
|
+
const navigation = this._navigation;
|
|
173
|
+
if (!navigation) {
|
|
174
|
+
this._push(url, "back");
|
|
175
|
+
return;
|
|
176
|
+
}
|
|
177
|
+
const current = this.stack.value;
|
|
178
|
+
const pages = this._getPages(stack);
|
|
179
|
+
const page = pages.slice(0, -1).findLast(p => p.url.href === url.href);
|
|
180
|
+
if (page && stack === current && page.index === (navigation.currentEntry?.index ?? 0) - 1) {
|
|
181
|
+
navigation.traverseTo(page.key, { info: this._getOrder(current, stack) ?? "back" }).finished?.catch(BLACKHOLE);
|
|
182
|
+
return;
|
|
183
|
+
}
|
|
184
|
+
// The URL is an earlier page in the stack, else the root of the stack, else it takes the place of the top page.
|
|
185
|
+
const depth = page ? page.depth : this._getPath(url) === stack ? 0 : (pages.at(-1)?.depth ?? 0);
|
|
186
|
+
this._push(url, this._getOrder(current, stack) ?? "back", { stack, depth });
|
|
44
187
|
}
|
|
45
188
|
/**
|
|
46
|
-
*
|
|
47
|
-
* -
|
|
48
|
-
* -
|
|
189
|
+
* Replace the current URL, with no transition.
|
|
190
|
+
* - The page stays in the same stack, at the same depth, so a cached page stays mounted.
|
|
191
|
+
* - Use it for a page that knows its canonical URL, or for in-page tabs.
|
|
192
|
+
* - 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")`.
|
|
49
193
|
*
|
|
50
194
|
* @param possible The destination URL, resolved against `base`.
|
|
195
|
+
* @param stack Root path of the stack to move the page into. Defaults to the current stack.
|
|
51
196
|
* @throws RequiredError If `possible` cannot be resolved to a valid URL.
|
|
52
|
-
* @example nav.
|
|
53
|
-
* @see https://shelving.cc/ui/NavigationStore/
|
|
197
|
+
* @example nav.replace("/login");
|
|
198
|
+
* @see https://shelving.cc/ui/NavigationStore/replace
|
|
54
199
|
*/
|
|
55
|
-
|
|
56
|
-
this.
|
|
57
|
-
|
|
58
|
-
|
|
200
|
+
replace(possible, stack = this.stack.value) {
|
|
201
|
+
const url = requireURL(possible, this.base, this.replace);
|
|
202
|
+
const saved = this._navigation?.currentEntry?.getState();
|
|
203
|
+
let state = _isEntryState(saved) ? saved : undefined;
|
|
204
|
+
if (state && stack !== state.stack) {
|
|
205
|
+
const top = this._getPages(stack)
|
|
206
|
+
.filter(p => p.index !== this._navigation?.currentEntry?.index)
|
|
207
|
+
.at(-1);
|
|
208
|
+
state = { stack, depth: this._getPath(url) === stack ? 0 : top ? top.depth + 1 : 0 };
|
|
209
|
+
}
|
|
210
|
+
this._write(() => window.history.replaceState(null, "", url.href), state);
|
|
211
|
+
this._change(url, null, state?.stack);
|
|
212
|
+
}
|
|
213
|
+
/** Push a URL as a new history entry, with an optional state. */
|
|
214
|
+
_push(url, transition, state) {
|
|
215
|
+
this._write(() => window.history.pushState(null, "", url.href), state);
|
|
216
|
+
this._change(url, this._navigation ? transition : null, state?.stack);
|
|
217
|
+
}
|
|
218
|
+
/** Change history and then save a state on the new entry, ignoring the events that causes. */
|
|
219
|
+
_write(write, state) {
|
|
220
|
+
this._busy = true;
|
|
221
|
+
try {
|
|
222
|
+
write();
|
|
223
|
+
if (state)
|
|
224
|
+
this._update(state);
|
|
225
|
+
}
|
|
226
|
+
finally {
|
|
227
|
+
this._busy = false;
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
/** Save a state on the current entry. */
|
|
231
|
+
_update(state) {
|
|
232
|
+
const busy = this._busy;
|
|
233
|
+
this._busy = true;
|
|
234
|
+
try {
|
|
235
|
+
this._navigation?.updateCurrentEntry({ state });
|
|
236
|
+
}
|
|
237
|
+
finally {
|
|
238
|
+
this._busy = busy;
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
/** Set the stack first, then the URL, so both are ready when `<Navigation>` reads them. */
|
|
242
|
+
_change(url, transition, stack) {
|
|
243
|
+
this.transition = transition;
|
|
244
|
+
if (stack)
|
|
245
|
+
this.stack.value = stack;
|
|
246
|
+
this.value = url;
|
|
247
|
+
}
|
|
248
|
+
/** 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. */
|
|
249
|
+
_getPages(stack) {
|
|
250
|
+
const navigation = this._navigation;
|
|
251
|
+
if (!navigation)
|
|
252
|
+
return [];
|
|
253
|
+
const entries = navigation.entries();
|
|
254
|
+
const pages = [];
|
|
255
|
+
let depth = Number.POSITIVE_INFINITY;
|
|
256
|
+
const current = navigation.currentEntry?.index ?? -1;
|
|
257
|
+
for (let i = current; i >= 0 && depth > 0; i--) {
|
|
258
|
+
const entry = entries[i];
|
|
259
|
+
// The current entry may not have its state saved yet (before `listen()`), so use its default.
|
|
260
|
+
const state = i === current && entry ? this._getState(entry) : entry?.getState();
|
|
261
|
+
if (!entry?.url || !_isEntryState(state) || state.stack !== stack || state.depth >= depth)
|
|
262
|
+
continue;
|
|
263
|
+
const url = requireURL(entry.url, undefined, this._getPages);
|
|
264
|
+
const path = this._getPath(url);
|
|
265
|
+
if (!path)
|
|
266
|
+
continue;
|
|
267
|
+
depth = state.depth;
|
|
268
|
+
pages.unshift({ ...state, url, path, index: entry.index, key: entry.key });
|
|
269
|
+
}
|
|
270
|
+
return pages;
|
|
59
271
|
}
|
|
272
|
+
/** Get the saved state of an entry, or for an entry with none (the page the app opened at), the starting stack at depth 0. */
|
|
273
|
+
_getState(entry) {
|
|
274
|
+
const state = entry?.getState();
|
|
275
|
+
if (_isEntryState(state) && this._getStacks().includes(state.stack))
|
|
276
|
+
return state;
|
|
277
|
+
return { stack: this._start, depth: 0 };
|
|
278
|
+
}
|
|
279
|
+
/** Get every stack a page can be in: the listed stacks, plus the unstacked `"/"` stack. */
|
|
280
|
+
_getStacks() {
|
|
281
|
+
return Array.from(new Set([...this.stacks, this._start, "/"]));
|
|
282
|
+
}
|
|
283
|
+
/** Get the path of a URL relative to the app root, or `undefined` if it is outside the app. */
|
|
284
|
+
_getPath(url) {
|
|
285
|
+
return matchURLPrefix(url, this.base ?? new URL("/", url));
|
|
286
|
+
}
|
|
287
|
+
/** Direction of a change the store did not make: tab order across stacks, else depth, else position. */
|
|
288
|
+
_getDirection(e) {
|
|
289
|
+
if (e.navigationType !== "traverse")
|
|
290
|
+
return null;
|
|
291
|
+
const from = this._getState(e.from);
|
|
292
|
+
const to = this._getState(this._navigation?.currentEntry ?? null);
|
|
293
|
+
const order = this._getOrder(from.stack, to.stack);
|
|
294
|
+
if (order)
|
|
295
|
+
return order;
|
|
296
|
+
if (to.depth !== from.depth)
|
|
297
|
+
return to.depth < from.depth ? "back" : "forward";
|
|
298
|
+
return (this._navigation?.currentEntry?.index ?? 0) < e.from.index ? "back" : "forward";
|
|
299
|
+
}
|
|
300
|
+
/** Slide direction between two stacks by tab order, or `undefined` for the same stack. */
|
|
301
|
+
_getOrder(from, to) {
|
|
302
|
+
if (from === to)
|
|
303
|
+
return;
|
|
304
|
+
const a = this.stacks.indexOf(from);
|
|
305
|
+
const b = this.stacks.indexOf(to);
|
|
306
|
+
if (a < 0 || b < 0)
|
|
307
|
+
return;
|
|
308
|
+
return b > a ? "forward" : "back";
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
/** Get the browser Navigation API, or `undefined` if it is missing or unusable (for example in a sandboxed frame). */
|
|
312
|
+
function _getNavigation() {
|
|
313
|
+
if (typeof navigation === "undefined" || typeof window === "undefined")
|
|
314
|
+
return;
|
|
315
|
+
if (!navigation.currentEntry)
|
|
316
|
+
return;
|
|
317
|
+
return navigation;
|
|
318
|
+
}
|
|
319
|
+
/** Get a page's path with its `?query`. */
|
|
320
|
+
function _getPathWithQuery({ path, url }) {
|
|
321
|
+
return `${path}${url.search}`;
|
|
322
|
+
}
|
|
323
|
+
/** Is a value a `NavigationEntryState`? */
|
|
324
|
+
function _isEntryState(state) {
|
|
325
|
+
return (typeof state === "object" &&
|
|
326
|
+
state !== null &&
|
|
327
|
+
"stack" in state &&
|
|
328
|
+
typeof state.stack === "string" &&
|
|
329
|
+
"depth" in state &&
|
|
330
|
+
typeof state.depth === "number");
|
|
60
331
|
}
|
|
@@ -1,29 +1,102 @@
|
|
|
1
1
|
# NavigationStore
|
|
2
2
|
|
|
3
|
-
The store
|
|
3
|
+
The store that holds the current URL, drives browser history, and keeps one stack of pages for each tab. It extends `URLStore`, so its `value` is the current URL. `<Navigation>` owns it. Read it with `requireNavigation()`, and do not make your own.
|
|
4
4
|
|
|
5
5
|
**Things to know:**
|
|
6
6
|
|
|
7
|
-
- `
|
|
8
|
-
-
|
|
9
|
-
-
|
|
7
|
+
- `NavigationStore.stacks` is the root path of each stack, in tab order, from the `stacks` prop on `<Navigation>`. With no stacks the app has one stack at `/`.
|
|
8
|
+
- A page that is not in a listed stack is **unstacked**: it is in the `/` stack. See [Unstacked pages](#unstacked-pages).
|
|
9
|
+
- `NavigationStore.stack` is a sub-store that holds the root of the current stack. It is always set: with no stacks it is `"/"`. It changes only when the stack changes, so `useStore(nav.stack)` re-renders only on a tab change.
|
|
10
|
+
- `NavigationStore.history()` returns the pages in the current stack (or a given stack), root first.
|
|
11
|
+
- `NavigationStore.position` is the current stack and depth, the depth of the top page of each stack, and the page before this one. `<RouteCache>` and `<BackButton>` use it.
|
|
12
|
+
- All URLs resolve against the store's `base`. Each method also takes a full same-origin URL.
|
|
13
|
+
- Without the browser Navigation API there is no stack history: `stack` stays the starting stack, `history()` returns `[]`, `position` is `undefined`, and every `stack` argument is ignored. `forward()` and `back()` push a history entry, and `replace()` replaces it.
|
|
14
|
+
|
|
15
|
+
## Methods
|
|
16
|
+
|
|
17
|
+
| Method | What it does | Slide |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| `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. |
|
|
20
|
+
| `back(href, stack?)` | Goes back to `href`. If `href` is in the stack, the stack goes back to it, and the pages above it leave the stack. If `href` is the root of the stack, the stack goes to its root. Otherwise `href` takes the place of the top page of the stack. | Back |
|
|
21
|
+
| `replace(href, stack?)` | Changes the URL of the current page. The stack, the depth and the mounted page stay the same. No new history entry. With another `stack`, the page moves into that stack: at its root if `href` is the root, else on top of its pages. | None |
|
|
22
|
+
| `history(stack?)` | Returns the pages in `stack`, root first. | — |
|
|
23
|
+
|
|
24
|
+
`stack` defaults to the current stack.
|
|
25
|
+
|
|
26
|
+
## Unstacked pages
|
|
27
|
+
|
|
28
|
+
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 in the `/` stack. A page in the `/` stack is **unstacked**. For example: a deep link into the app, a fresh open of `/post/9`, or a login page.
|
|
29
|
+
|
|
30
|
+
- On an unstacked page, no `<StackButton>` is selected.
|
|
31
|
+
- Links from an unstacked page push deeper in the `/` stack, even a link to a stack root.
|
|
32
|
+
- To leave the `/` stack, tap a `<StackButton>`, or name the stack.
|
|
33
|
+
- 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.
|
|
34
|
+
- If you list `/` as one of the `stacks`, it is a normal tab, and unstacked pages open in it.
|
|
35
|
+
|
|
36
|
+
For example, a login page sends the user home after they log in, and names the Home stack:
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
const nav = requireNavigation();
|
|
40
|
+
nav.replace("/home", "/home");
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## How stacks work
|
|
44
|
+
|
|
45
|
+
The store saves a small state on each browser history entry: the `stack` the page is in, and its `depth` in that stack (`0` is the root). See `NavigationEntryState`. To read a stack, the store walks back through the browser history from the current entry. It takes the newest entry in that stack, then the newest earlier entry with a lower depth, and so on down to depth `0`.
|
|
46
|
+
|
|
47
|
+
Why depth? A browser history entry cannot be changed or removed. So when you go back in one stack while another stack's pages are after it in the history, the store cannot go back in the browser. It pushes a new entry for the page you went back to, at that page's depth. The pages that were above it now have a higher depth than the newest entry, so they are no longer in the stack.
|
|
48
|
+
|
|
49
|
+
For example, with tabs `/home` and `/profile`:
|
|
50
|
+
|
|
51
|
+
| Step | New history entry | Home stack | Profile stack |
|
|
52
|
+
|---|---|---|---|
|
|
53
|
+
| Start at `/home` | `/home` (depth 0) | `/home` | — |
|
|
54
|
+
| Open a post | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | — |
|
|
55
|
+
| Tap the Profile tab | `/profile` (depth 0) | `/home`, `/home/post/1` | `/profile` |
|
|
56
|
+
| Tap the Home tab | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | `/profile` |
|
|
57
|
+
| Tap the back button | `/home` (depth 0) | `/home` | `/profile` |
|
|
58
|
+
|
|
59
|
+
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.
|
|
60
|
+
|
|
61
|
+
The browser back and forward buttons walk the history entries one at a time, as usual. Each entry knows its stack and depth, so the stacks are always right and the slide goes the right way.
|
|
10
62
|
|
|
11
63
|
## Usage
|
|
12
64
|
|
|
13
65
|
```tsx
|
|
14
|
-
import { requireNavigation } from "shelving/ui";
|
|
66
|
+
import { Button, requireNavigation } from "shelving/ui";
|
|
15
67
|
|
|
16
68
|
function LogoutButton() {
|
|
17
69
|
const nav = requireNavigation();
|
|
18
|
-
return <Button onClick={() => nav.
|
|
70
|
+
return <Button onClick={() => nav.replace("/login")}>Log out</Button>;
|
|
19
71
|
}
|
|
20
72
|
```
|
|
21
73
|
|
|
22
|
-
|
|
74
|
+
Read the current stack in a component:
|
|
75
|
+
|
|
76
|
+
```tsx
|
|
77
|
+
import { useStore } from "shelving/react";
|
|
78
|
+
import { requireNavigation } from "shelving/ui";
|
|
79
|
+
|
|
80
|
+
function TabTitle() {
|
|
81
|
+
const nav = requireNavigation();
|
|
82
|
+
const stack = useStore(nav.stack).value;
|
|
83
|
+
return <h1>{stack === "/profile" ? "Profile" : "Home"}</h1>;
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
List the pages in a stack (for example, for breadcrumbs):
|
|
88
|
+
|
|
89
|
+
```tsx
|
|
90
|
+
const nav = requireNavigation();
|
|
91
|
+
nav.history("/home"); // ["/home", "/home/post/1", "/home/post/1/comments"]
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Make a store by hand only in tests:
|
|
23
95
|
|
|
24
96
|
```tsx
|
|
25
97
|
import { NavigationStore } from "shelving/ui";
|
|
26
98
|
|
|
27
|
-
|
|
28
|
-
nav
|
|
99
|
+
// URL, root, starting stack, then the stacks in tab order.
|
|
100
|
+
const nav = new NavigationStore("https://example.com/home", "https://example.com/", "/home", "/home", "/profile");
|
|
101
|
+
nav.forward("/home/post/1");
|
|
29
102
|
```
|