shelving 1.320.0 → 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 +629 -257
- package/docs/ui/BackButton.md +75 -0
- package/docs/ui/BackButtonProps.md +21 -0
- package/docs/ui/ClickableProps.md +0 -2
- package/docs/ui/Head.md +2 -2
- package/docs/ui/HorizontalTransition.md +1 -1
- 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/StackButton.md +64 -0
- package/docs/ui/StackButtonProps.md +21 -0
- package/docs/ui/VerticalTransition.md +1 -1
- package/docs/ui/mergeMeta.md +2 -1
- package/docs/ui.md +13 -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/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/HorizontalTransition.md +1 -1
- package/ui/transition/VerticalTransition.md +1 -1
- 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
package/ui/router/RouteCache.md
CHANGED
|
@@ -1,28 +1,71 @@
|
|
|
1
1
|
# RouteCache
|
|
2
2
|
|
|
3
|
-
A keep-alive
|
|
3
|
+
A keep-alive cache for the pages in the navigation stacks. Put it in a layout around the scrolling content region. It keeps each page in the stacks mounted but hidden (with React's [`<Activity>`](https://react.dev/reference/react/Activity)), so when you go back to a page, or switch back to a tab, the page is exactly as you left it: scroll position, toggles, searches, form input and focus.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
`<SidebarLayout>` and `<CenteredLayout>` already wrap their content in a `<RouteCache>`. Use it by hand only in a custom layout.
|
|
6
6
|
|
|
7
7
|
**Things to know:**
|
|
8
8
|
|
|
9
|
-
-
|
|
10
|
-
- A page
|
|
11
|
-
-
|
|
12
|
-
- The
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
9
|
+
- Each page is keyed by its stack and its depth in that stack, not by its URL. See `NavigationStore` for how stacks work.
|
|
10
|
+
- A page leaves the cache when it leaves its stack: when you go back from it, or when its stack goes back to the root. So a page you went back from mounts fresh the next time you open it.
|
|
11
|
+
- After a browser back, the browser forward button shows the next page fresh (from the top), because that page left its stack when you went back.
|
|
12
|
+
- The top page of each stack is never dropped, so each tab always shows the page you left. Other pages are dropped (least recently used first) past `maxCached`, and mount fresh when you come back to them.
|
|
13
|
+
- `NavigationStore.replace()` and `className="replace"` links keep the same page mounted. A replace to another URL for the same component (for example from `/post/1` to `/post/2`) keeps its state. To reset the state, wrap the page content in an element with a `key`, for example `<Fragment key={id}>`.
|
|
14
|
+
- The same URL open in two stacks is two separate pages.
|
|
15
|
+
- A form that makes something stays in the cache with its input. Clear it after a successful submit, so it is empty the next time you see it (see the example below).
|
|
16
|
+
- Each kept page is frozen under its own `<Meta>`, so a hidden page never re-renders for another page's URL.
|
|
17
|
+
- `<Activity mode="hidden">` keeps a hidden page's state but unmounts its effects, so subscriptions, observers (for example infinite scroll) and timers pause and resume as the page is hidden and shown.
|
|
18
|
+
- The cache must wrap the scroll container itself to keep each page's scroll. So it goes in the layout around the scrolling column, not inside the router. Chrome outside the cache (a sidebar, a tab bar) is not duplicated or remounted.
|
|
19
|
+
- Put a page `<Transition>` around the `<RouteCache>`, not inside it. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
|
|
20
|
+
- Without the browser Navigation API, or with `maxCached={0}`, there is no cache: the current page renders directly and unmounts when you leave it.
|
|
17
21
|
|
|
18
22
|
## Usage
|
|
19
23
|
|
|
20
24
|
```tsx
|
|
21
|
-
import { RouteCache } from "shelving/ui";
|
|
25
|
+
import { HorizontalTransition, RouteCache, Router } from "shelving/ui";
|
|
22
26
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
<
|
|
26
|
-
|
|
27
|
-
|
|
27
|
+
function MyLayout() {
|
|
28
|
+
return (
|
|
29
|
+
<HorizontalTransition>
|
|
30
|
+
<RouteCache>
|
|
31
|
+
<main className="scroll">
|
|
32
|
+
<Router routes={ROUTES}/>
|
|
33
|
+
</main>
|
|
34
|
+
</RouteCache>
|
|
35
|
+
</HorizontalTransition>
|
|
36
|
+
);
|
|
37
|
+
}
|
|
28
38
|
```
|
|
39
|
+
|
|
40
|
+
Keep fewer pages:
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
<RouteCache maxCached={5}>
|
|
44
|
+
<Router routes={ROUTES}/>
|
|
45
|
+
</RouteCache>
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Clear a create form after it saves. Change the `key` of the `<Form>`, so it mounts again with no input:
|
|
49
|
+
|
|
50
|
+
```tsx
|
|
51
|
+
import { useState } from "react";
|
|
52
|
+
import { Form, requireNavigation } from "shelving/ui";
|
|
53
|
+
|
|
54
|
+
function NewPostPage() {
|
|
55
|
+
const nav = requireNavigation();
|
|
56
|
+
const [formKey, setFormKey] = useState(0);
|
|
57
|
+
return (
|
|
58
|
+
<Form
|
|
59
|
+
key={formKey}
|
|
60
|
+
schema={POST_SCHEMA}
|
|
61
|
+
onSubmit={async data => {
|
|
62
|
+
const id = await createPost(data);
|
|
63
|
+
setFormKey(k => k + 1);
|
|
64
|
+
nav.forward(`/post/${id}`);
|
|
65
|
+
}}
|
|
66
|
+
/>
|
|
67
|
+
);
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
For a plain HTML `<form>`, call `form.reset()` after the submit.
|
package/ui/router/RouteCache.tsx
CHANGED
|
@@ -1,84 +1,87 @@
|
|
|
1
|
-
import { Activity, type ReactNode, useRef } from "react";
|
|
1
|
+
import { Activity, type ReactNode, use, useRef } from "react";
|
|
2
2
|
import type { AbsolutePath } from "../../util/path.js";
|
|
3
|
-
import { matchPathTemplate } from "../../util/template.js";
|
|
4
3
|
import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
|
|
5
|
-
import {
|
|
4
|
+
import { NavigationPositionContext } from "./NavigationContext.js";
|
|
6
5
|
|
|
7
|
-
/** A cached page: the rendered node
|
|
8
|
-
interface
|
|
6
|
+
/** A cached page: the rendered node, where it is in its stack, and a `used` tick for least-recently-used eviction. */
|
|
7
|
+
interface _CacheEntry {
|
|
9
8
|
node: ReactNode;
|
|
10
9
|
used: number;
|
|
11
|
-
readonly
|
|
10
|
+
readonly stack: AbsolutePath;
|
|
11
|
+
readonly depth: number;
|
|
12
12
|
}
|
|
13
13
|
|
|
14
14
|
/**
|
|
15
|
-
* Props for `<RouteCache
|
|
15
|
+
* Props for `<RouteCache>`: the `maxCached` size and the content `children` to keep alive for each page in the stacks.
|
|
16
16
|
*
|
|
17
17
|
* @see https://shelving.cc/ui/RouteCacheProps
|
|
18
18
|
*/
|
|
19
19
|
export interface RouteCacheProps {
|
|
20
20
|
/**
|
|
21
|
-
* Number of
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
21
|
+
* Number of pages to keep mounted (but hidden), so the whole state of each one (scroll position, toggles, searches, form input, focus) is still there when you come back to it.
|
|
22
|
+
* - The top page of each stack is never dropped, even past the limit, so a tab always shows the page you left.
|
|
23
|
+
* - Set to `0` (or less) to turn the cache off and unmount each page as you leave it.
|
|
24
|
+
*
|
|
25
|
+
* @default 10
|
|
26
26
|
*/
|
|
27
27
|
readonly maxCached?: number | undefined;
|
|
28
|
-
/** The content to render for the current
|
|
28
|
+
/** The content to render for the current page and keep alive (hidden) for the other pages in the stacks. */
|
|
29
29
|
readonly children: ReactNode;
|
|
30
30
|
}
|
|
31
31
|
|
|
32
32
|
/**
|
|
33
|
-
* Keep-alive page cache
|
|
33
|
+
* Keep-alive page cache for the pages in the navigation stacks. Drop it into a layout around its scrolling content region.
|
|
34
34
|
*
|
|
35
|
-
* -
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
* -
|
|
39
|
-
* -
|
|
40
|
-
* -
|
|
41
|
-
* -
|
|
42
|
-
* different page per path and a hidden page never re-renders for someone else's URL.
|
|
43
|
-
* - `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
|
|
44
|
-
* subscriptions/observers/timers pause and resume cleanly as it is hidden and shown.
|
|
45
|
-
* - Because it wraps the scroll container itself (rather than sitting below it inside the router), the
|
|
46
|
-
* scroll position of every cached page is preserved — surrounding chrome (sidebar, drawer state) stays
|
|
47
|
-
* outside the cache, so it is neither duplicated nor remounted on navigation.
|
|
48
|
-
* - When `maxCached <= 0` the page is rendered directly with no caching (it unmounts as you leave it).
|
|
35
|
+
* - Keeps each page in the stacks mounted but hidden (with React's `<Activity>`), so going back to a page, or switching back to a tab, shows it exactly as you left it.
|
|
36
|
+
* - Each page is keyed by its stack and its depth in that stack, not by its URL. So `NavigationStore.replace()` (a canonical URL, an in-page tab) keeps the same page mounted, and the same URL open in two tabs is two separate pages.
|
|
37
|
+
* - A page leaves the cache as soon as it leaves its stack: when you go back from it, or when a stack is popped to its root. After a browser back, a browser forward shows that page fresh.
|
|
38
|
+
* - The top page of each stack is never dropped. Other pages can be dropped past `maxCached`, and show fresh (from the top) when you come back to them.
|
|
39
|
+
* - Each kept page is frozen under its own `<MetaContext>`, so the same `children` element renders a different page for each URL, and a hidden page never re-renders for another page's URL.
|
|
40
|
+
* - `<Activity mode="hidden">` keeps a hidden page's state but unmounts its effects, so its subscriptions and timers pause and resume as it is hidden and shown.
|
|
41
|
+
* - Without the browser Navigation API (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
|
|
49
42
|
*
|
|
50
43
|
* @kind component
|
|
51
44
|
* @see https://shelving.cc/ui/RouteCache
|
|
52
45
|
*/
|
|
53
46
|
export function RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode {
|
|
54
|
-
// Read the live URL
|
|
47
|
+
// Read the live URL and the position in the stacks; each navigation re-renders this with both.
|
|
55
48
|
const meta = requireMetaURL();
|
|
56
|
-
const
|
|
49
|
+
const position = use(NavigationPositionContext);
|
|
50
|
+
const mapRef = useRef<Map<string, _CacheEntry>>(undefined);
|
|
57
51
|
const usedRef = useRef(0);
|
|
58
52
|
|
|
59
|
-
// Caching
|
|
53
|
+
// Caching turned off: render the page directly, so it unmounts as soon as you leave it.
|
|
60
54
|
if (maxCached <= 0) return <MetaContext value={meta}>{children}</MetaContext>;
|
|
61
55
|
|
|
62
|
-
//
|
|
56
|
+
// No stacks (server render, or no Navigation API): render only the current page.
|
|
57
|
+
// It is still inside an `<Activity>`, so a server render has the same structure as the first render in the browser, and hydration matches.
|
|
58
|
+
if (!position)
|
|
59
|
+
return (
|
|
60
|
+
<Activity mode="visible">
|
|
61
|
+
<MetaContext value={meta}>{children}</MetaContext>
|
|
62
|
+
</Activity>
|
|
63
|
+
);
|
|
64
|
+
|
|
65
|
+
// Find (or make) the entry for the current page.
|
|
66
|
+
const { stack, depth, tops } = position;
|
|
63
67
|
const map = (mapRef.current ??= new Map());
|
|
64
|
-
const key =
|
|
65
|
-
const entry = map.get(key) ?? { node: null, used: 0,
|
|
68
|
+
const key = `${stack} ${depth}`;
|
|
69
|
+
const entry = map.get(key) ?? { node: null, used: 0, stack, depth };
|
|
66
70
|
map.set(key, entry);
|
|
67
71
|
|
|
68
|
-
// Snapshot the children under the live URL (frozen) so each kept
|
|
69
|
-
|
|
70
|
-
entry.node = (
|
|
71
|
-
<RouteContext value={entry.state}>
|
|
72
|
-
<MetaContext value={meta}>{children}</MetaContext>
|
|
73
|
-
</RouteContext>
|
|
74
|
-
);
|
|
72
|
+
// Snapshot the children under the live URL (frozen), so each kept page keeps rendering for the URL it last had.
|
|
73
|
+
entry.node = <MetaContext value={meta}>{children}</MetaContext>;
|
|
75
74
|
entry.used = ++usedRef.current;
|
|
76
75
|
|
|
77
|
-
// Drop the pages that
|
|
78
|
-
for (const [k, {
|
|
76
|
+
// Drop the pages that have left their stack.
|
|
77
|
+
for (const [k, { stack: s, depth: d }] of map) if (k !== key && !(d <= (tops[s] ?? -1))) map.delete(k);
|
|
79
78
|
|
|
80
|
-
//
|
|
81
|
-
while (map.size > maxCached)
|
|
79
|
+
// Drop the least-recently-used pages past the limit, but never the current page or the top page of a stack.
|
|
80
|
+
while (map.size > maxCached) {
|
|
81
|
+
const lru = _findLeastRecentlyUsed(map, (k, { stack: s, depth: d }) => k !== key && tops[s] !== d);
|
|
82
|
+
if (lru === undefined) break;
|
|
83
|
+
map.delete(lru);
|
|
84
|
+
}
|
|
82
85
|
|
|
83
86
|
// Render every cached page; only the current one is visible, the rest are kept alive but hidden.
|
|
84
87
|
return Array.from(map, ([k, cached]) => (
|
|
@@ -88,25 +91,15 @@ export function RouteCache({ maxCached = 10, children }: RouteCacheProps): React
|
|
|
88
91
|
));
|
|
89
92
|
}
|
|
90
93
|
|
|
91
|
-
/** Find the key of the
|
|
92
|
-
function
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
ownerUsed = used;
|
|
98
|
-
ownerKey = key;
|
|
99
|
-
}
|
|
100
|
-
}
|
|
101
|
-
return ownerKey;
|
|
102
|
-
}
|
|
103
|
-
|
|
104
|
-
/** Find the key of the least-recently-used (lowest `used` tick) entry in the cache map. */
|
|
105
|
-
function _findLeastRecentlyUsed(map: Map<AbsolutePath, CacheEntry>): AbsolutePath {
|
|
106
|
-
let lruKey!: AbsolutePath;
|
|
94
|
+
/** Find the key of the least-recently-used entry that may be dropped, or `undefined` if none may. */
|
|
95
|
+
function _findLeastRecentlyUsed(
|
|
96
|
+
map: Map<string, _CacheEntry>,
|
|
97
|
+
droppable: (key: string, entry: _CacheEntry) => boolean,
|
|
98
|
+
): string | undefined {
|
|
99
|
+
let lruKey: string | undefined;
|
|
107
100
|
let lruUsed = Number.POSITIVE_INFINITY;
|
|
108
101
|
for (const [key, entry] of map) {
|
|
109
|
-
if (entry.used < lruUsed) {
|
|
102
|
+
if (entry.used < lruUsed && droppable(key, entry)) {
|
|
110
103
|
lruUsed = entry.used;
|
|
111
104
|
lruKey = key;
|
|
112
105
|
}
|
package/ui/router/Router.d.ts
CHANGED
|
@@ -21,7 +21,8 @@ export interface RouterProps extends PossibleMeta {
|
|
|
21
21
|
* - When `base` is set, the effective path is the URL after stripping the base prefix.
|
|
22
22
|
* - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
|
|
23
23
|
* - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
|
|
24
|
-
* -
|
|
24
|
+
* - Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationStore.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
|
|
25
|
+
* - Elsewhere, each path is a new page, so a component route remounts when the path changes.
|
|
25
26
|
* - Returns `null` when there's no URL in context or the URL is outside the base.
|
|
26
27
|
*
|
|
27
28
|
* @kind component
|
package/ui/router/Router.js
CHANGED
|
@@ -1,18 +1,19 @@
|
|
|
1
1
|
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
|
-
import { use
|
|
2
|
+
import { use } from "react";
|
|
3
3
|
import { NotFoundError } from "../../error/RequestError.js";
|
|
4
4
|
import { UnexpectedError } from "../../error/UnexpectedError.js";
|
|
5
5
|
import { getProps } from "../../util/index.js";
|
|
6
6
|
import { matchPathTemplate, renderPathTemplate } from "../../util/template.js";
|
|
7
7
|
import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
|
|
8
|
-
import {
|
|
8
|
+
import { NavigationPositionContext } from "./NavigationContext.js";
|
|
9
9
|
/**
|
|
10
10
|
* Match the current URL against `routes` and render the matched element.
|
|
11
11
|
* - Reads `url` and `base` from the surrounding `<Meta>` context (override via props).
|
|
12
12
|
* - When `base` is set, the effective path is the URL after stripping the base prefix.
|
|
13
13
|
* - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
|
|
14
14
|
* - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
|
|
15
|
-
* -
|
|
15
|
+
* - Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationStore.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
|
|
16
|
+
* - Elsewhere, each path is a new page, so a component route remounts when the path changes.
|
|
16
17
|
* - Returns `null` when there's no URL in context or the URL is outside the base.
|
|
17
18
|
*
|
|
18
19
|
* @kind component
|
|
@@ -22,18 +23,12 @@ import { RouteContext } from "./RouteContext.js";
|
|
|
22
23
|
export function Router({ routes, fallback, ...meta }) {
|
|
23
24
|
const combined = requireMetaURL(meta);
|
|
24
25
|
const path = combined;
|
|
25
|
-
//
|
|
26
|
-
|
|
27
|
-
const
|
|
28
|
-
const
|
|
29
|
-
const prev = pageRef.current;
|
|
30
|
-
const page = prev && (prev.key === combined.path || (prev.state.path && matchPathTemplate(prev.state.path, combined.path)))
|
|
31
|
-
? prev
|
|
32
|
-
: { key: combined.path, state: { router: true, entry: parent?.router ? undefined : parent } };
|
|
33
|
-
pageRef.current = page;
|
|
34
|
-
const route = _matchRoute(routes, fallback, combined, page.key);
|
|
26
|
+
// Key the page by its place in the stack when there is one, else by its path.
|
|
27
|
+
const position = use(NavigationPositionContext);
|
|
28
|
+
const key = position ? `${position.stack} ${position.depth}` : combined.path;
|
|
29
|
+
const route = _matchRoute(routes, fallback, combined, key);
|
|
35
30
|
if (route)
|
|
36
|
-
return
|
|
31
|
+
return _jsx(MetaContext, { value: combined, children: route });
|
|
37
32
|
throw new NotFoundError("Tree route not found", { received: path });
|
|
38
33
|
}
|
|
39
34
|
function _matchRoute(routes, fallback, meta, key, path = meta.path, depth = 0) {
|
package/ui/router/Router.md
CHANGED
|
@@ -8,6 +8,7 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
|
|
|
8
8
|
- `<Router>` accepts `PossibleMeta` props (`url`, `base`, etc.) to override the surrounding context — this is how nested routers scope themselves.
|
|
9
9
|
- With a `base` set, the path used for matching is the URL after `matchURLPrefix()` strips the base prefix; URLs outside the base render as `null`.
|
|
10
10
|
- Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
|
|
11
|
+
- Inside `<Navigation>` with stacks, each page in a stack is a new page: a link mounts a new page, and `NavigationStore.replace()` keeps the same page mounted (it re-renders with the new URL). Elsewhere each path is a new page.
|
|
11
12
|
- `<Router>` itself does not cache pages — wrap it in a `<RouteCache>` (or use a layout that already does) to keep recently-visited pages mounted but hidden so back/forward navigation restores their state.
|
|
12
13
|
|
|
13
14
|
## Usage
|
|
@@ -122,7 +123,7 @@ const SIDEBARRED_ROUTES = {
|
|
|
122
123
|
|
|
123
124
|
### Keeping page state
|
|
124
125
|
|
|
125
|
-
By default a page is unmounted when you navigate away and mounted fresh when you return — so scroll position, open/closed toggles, in-progress searches, form inputs, and focus are all lost, and you land back at the top. Wrap the router (or its scrolling content region) in a `<RouteCache>` to keep recently-visited pages mounted but hidden so their state is
|
|
126
|
+
By default a page is unmounted when you navigate away and mounted fresh when you return — so scroll position, open/closed toggles, in-progress searches, form inputs, and focus are all lost, and you land back at the top. Wrap the router (or its scrolling content region) in a `<RouteCache>` to keep recently-visited pages mounted but hidden so their state is still there when you go back to them, or switch back to their tab. Shelving's `<SidebarLayout>` and `<CenteredLayout>` already do this for you.
|
|
126
127
|
|
|
127
128
|
### SSR / static rendering
|
|
128
129
|
|
package/ui/router/Router.tsx
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
import { type ReactElement, use
|
|
1
|
+
import { type ReactElement, use } from "react";
|
|
2
2
|
import { NotFoundError } from "../../error/RequestError.js";
|
|
3
3
|
import { UnexpectedError } from "../../error/UnexpectedError.js";
|
|
4
4
|
import { getProps } from "../../util/index.js";
|
|
5
5
|
import { matchPathTemplate, renderPathTemplate } from "../../util/template.js";
|
|
6
6
|
import { MetaContext, type MetaURL, requireMetaURL } from "../misc/MetaContext.js";
|
|
7
7
|
import type { PossibleMeta } from "../util/meta.js";
|
|
8
|
-
import {
|
|
8
|
+
import { NavigationPositionContext } from "./NavigationContext.js";
|
|
9
9
|
import type { Routes } from "./Routes.js";
|
|
10
10
|
|
|
11
11
|
/**
|
|
@@ -30,7 +30,8 @@ export interface RouterProps extends PossibleMeta {
|
|
|
30
30
|
* - When `base` is set, the effective path is the URL after stripping the base prefix.
|
|
31
31
|
* - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
|
|
32
32
|
* - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
|
|
33
|
-
* -
|
|
33
|
+
* - Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationStore.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
|
|
34
|
+
* - Elsewhere, each path is a new page, so a component route remounts when the path changes.
|
|
34
35
|
* - Returns `null` when there's no URL in context or the URL is outside the base.
|
|
35
36
|
*
|
|
36
37
|
* @kind component
|
|
@@ -41,24 +42,12 @@ export function Router({ routes, fallback, ...meta }: RouterProps): ReactElement
|
|
|
41
42
|
const combined = requireMetaURL(meta);
|
|
42
43
|
const path = combined;
|
|
43
44
|
|
|
44
|
-
//
|
|
45
|
-
|
|
46
|
-
const
|
|
47
|
-
const pageRef = useRef<{ key: string; state: RouteState }>(undefined);
|
|
48
|
-
const prev = pageRef.current;
|
|
49
|
-
const page =
|
|
50
|
-
prev && (prev.key === combined.path || (prev.state.path && matchPathTemplate(prev.state.path, combined.path)))
|
|
51
|
-
? prev
|
|
52
|
-
: { key: combined.path, state: { router: true, entry: parent?.router ? undefined : parent } as RouteState };
|
|
53
|
-
pageRef.current = page;
|
|
45
|
+
// Key the page by its place in the stack when there is one, else by its path.
|
|
46
|
+
const position = use(NavigationPositionContext);
|
|
47
|
+
const key = position ? `${position.stack} ${position.depth}` : combined.path;
|
|
54
48
|
|
|
55
|
-
const route = _matchRoute(routes, fallback, combined,
|
|
56
|
-
if (route)
|
|
57
|
-
return (
|
|
58
|
-
<RouteContext value={page.state}>
|
|
59
|
-
<MetaContext value={combined}>{route}</MetaContext>
|
|
60
|
-
</RouteContext>
|
|
61
|
-
);
|
|
49
|
+
const route = _matchRoute(routes, fallback, combined, key);
|
|
50
|
+
if (route) return <MetaContext value={combined}>{route}</MetaContext>;
|
|
62
51
|
throw new NotFoundError("Tree route not found", { received: path });
|
|
63
52
|
}
|
|
64
53
|
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { type ReactElement } from "react";
|
|
2
|
+
import type { AbsolutePath } from "../../util/path.js";
|
|
3
|
+
import { type ButtonProps } from "../button/Button.js";
|
|
4
|
+
/**
|
|
5
|
+
* Props for `<StackButton>`: the `stack` it opens, plus the usual `Button` props except `href` and `onClick`.
|
|
6
|
+
*
|
|
7
|
+
* @see https://shelving.cc/ui/StackButtonProps
|
|
8
|
+
*/
|
|
9
|
+
export interface StackButtonProps extends Omit<ButtonProps, "href" | "onClick" | "selected"> {
|
|
10
|
+
/** Root path of the stack this button opens. It must be one of the `stacks` on `<Navigation>`. */
|
|
11
|
+
readonly stack: AbsolutePath;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Button for one stack in a tab bar.
|
|
15
|
+
* - Tap another stack's button: go to the page you left in that stack. The page slides left or right by tab order.
|
|
16
|
+
* - Tap the current stack's button: go back to its root.
|
|
17
|
+
* - Tap it again at the root: scroll the page to the top.
|
|
18
|
+
* - It is selected while its stack is the current stack.
|
|
19
|
+
* - Without the browser Navigation API (and in a server render) it is a plain link to the stack's root.
|
|
20
|
+
*
|
|
21
|
+
* @kind component
|
|
22
|
+
* @see https://shelving.cc/ui/StackButton
|
|
23
|
+
*/
|
|
24
|
+
export declare function StackButton({ stack, ...props }: StackButtonProps): ReactElement;
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
|
+
import { use } from "react";
|
|
3
|
+
import { useStore } from "../../react/useStore.js";
|
|
4
|
+
import { Button } from "../button/Button.js";
|
|
5
|
+
import { NavigationPositionContext, requireNavigation } from "./NavigationContext.js";
|
|
6
|
+
/**
|
|
7
|
+
* Button for one stack in a tab bar.
|
|
8
|
+
* - Tap another stack's button: go to the page you left in that stack. The page slides left or right by tab order.
|
|
9
|
+
* - Tap the current stack's button: go back to its root.
|
|
10
|
+
* - Tap it again at the root: scroll the page to the top.
|
|
11
|
+
* - It is selected while its stack is the current stack.
|
|
12
|
+
* - Without the browser Navigation API (and in a server render) it is a plain link to the stack's root.
|
|
13
|
+
*
|
|
14
|
+
* @kind component
|
|
15
|
+
* @see https://shelving.cc/ui/StackButton
|
|
16
|
+
*/
|
|
17
|
+
export function StackButton({ stack, ...props }) {
|
|
18
|
+
const nav = requireNavigation();
|
|
19
|
+
const current = useStore(nav.stack).value;
|
|
20
|
+
const position = use(NavigationPositionContext);
|
|
21
|
+
// No Navigation API (or a server render): a plain link to the root, selected while its stack is the current stack.
|
|
22
|
+
if (!position)
|
|
23
|
+
return _jsx(Button, { ...props, href: stack, selected: current === stack });
|
|
24
|
+
const onClick = () => {
|
|
25
|
+
if (current !== stack)
|
|
26
|
+
return nav.forward(nav.history(stack).at(-1) ?? stack, stack);
|
|
27
|
+
if (nav.history(stack).length > 1)
|
|
28
|
+
return nav.back(stack, stack);
|
|
29
|
+
window.scrollTo({ top: 0, behavior: "smooth" });
|
|
30
|
+
for (const el of document.querySelectorAll("main, [data-scroll]"))
|
|
31
|
+
if (el.offsetParent)
|
|
32
|
+
el.scrollTo({ top: 0, behavior: "smooth" });
|
|
33
|
+
};
|
|
34
|
+
return _jsx(Button, { ...props, selected: current === stack, onClick: onClick });
|
|
35
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# StackButton
|
|
2
|
+
|
|
3
|
+
A button for one stack in a tab bar. It acts like a tab button in a phone app.
|
|
4
|
+
|
|
5
|
+
**Things to know:**
|
|
6
|
+
|
|
7
|
+
- Tap another stack's button: go to the page you left in that stack. The page slides left or right, by tab order.
|
|
8
|
+
- Tap the current stack's button: go back to the root of the stack. The page slides back.
|
|
9
|
+
- Tap it again at the root: scroll the page to the top. It scrolls the window, and each visible `<main>` or `[data-scroll]` element.
|
|
10
|
+
- It is selected (`aria-current`) while its stack is the current stack. On an unstacked page (for example a deep link or a login page), no stack button is selected.
|
|
11
|
+
- `stack` must be one of the `stacks` on `<Navigation>`.
|
|
12
|
+
- It takes the usual `<Button>` props, except `href`, `onClick` and `selected`.
|
|
13
|
+
- Without the browser Navigation API, and in a server render, it is a plain link to the stack's root. It is selected while its stack is the starting stack.
|
|
14
|
+
- In a server-rendered app, the server renders a link and the browser renders a button, so React warns about a hydration mismatch on the first render. A client-only app (with `<App>`) has no mismatch.
|
|
15
|
+
|
|
16
|
+
## Usage
|
|
17
|
+
|
|
18
|
+
```tsx
|
|
19
|
+
import { Navigation, StackButton } from "shelving/ui";
|
|
20
|
+
import { HomeIcon, SearchIcon, UserIcon } from "./icons.js";
|
|
21
|
+
|
|
22
|
+
<Navigation stacks={["/home", "/discover", "/profile"]}>
|
|
23
|
+
{/* … */}
|
|
24
|
+
<nav className="tab-bar">
|
|
25
|
+
<StackButton stack="/home" title="Home"><HomeIcon/></StackButton>
|
|
26
|
+
<StackButton stack="/discover" title="Discover"><SearchIcon/></StackButton>
|
|
27
|
+
<StackButton stack="/profile" title="Profile"><UserIcon/></StackButton>
|
|
28
|
+
</nav>
|
|
29
|
+
</Navigation>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Styling
|
|
33
|
+
|
|
34
|
+
`<StackButton>` renders a `<Button>`, so it has the same styling hooks. See `<Button>`.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { type ReactElement, use } from "react";
|
|
2
|
+
import { useStore } from "../../react/useStore.js";
|
|
3
|
+
import type { AbsolutePath } from "../../util/path.js";
|
|
4
|
+
import { Button, type ButtonProps } from "../button/Button.js";
|
|
5
|
+
import { NavigationPositionContext, requireNavigation } from "./NavigationContext.js";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Props for `<StackButton>`: the `stack` it opens, plus the usual `Button` props except `href` and `onClick`.
|
|
9
|
+
*
|
|
10
|
+
* @see https://shelving.cc/ui/StackButtonProps
|
|
11
|
+
*/
|
|
12
|
+
export interface StackButtonProps extends Omit<ButtonProps, "href" | "onClick" | "selected"> {
|
|
13
|
+
/** Root path of the stack this button opens. It must be one of the `stacks` on `<Navigation>`. */
|
|
14
|
+
readonly stack: AbsolutePath;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Button for one stack in a tab bar.
|
|
19
|
+
* - Tap another stack's button: go to the page you left in that stack. The page slides left or right by tab order.
|
|
20
|
+
* - Tap the current stack's button: go back to its root.
|
|
21
|
+
* - Tap it again at the root: scroll the page to the top.
|
|
22
|
+
* - It is selected while its stack is the current stack.
|
|
23
|
+
* - Without the browser Navigation API (and in a server render) it is a plain link to the stack's root.
|
|
24
|
+
*
|
|
25
|
+
* @kind component
|
|
26
|
+
* @see https://shelving.cc/ui/StackButton
|
|
27
|
+
*/
|
|
28
|
+
export function StackButton({ stack, ...props }: StackButtonProps): ReactElement {
|
|
29
|
+
const nav = requireNavigation();
|
|
30
|
+
const current = useStore(nav.stack).value;
|
|
31
|
+
const position = use(NavigationPositionContext);
|
|
32
|
+
|
|
33
|
+
// No Navigation API (or a server render): a plain link to the root, selected while its stack is the current stack.
|
|
34
|
+
if (!position) return <Button {...props} href={stack} selected={current === stack} />;
|
|
35
|
+
|
|
36
|
+
const onClick = () => {
|
|
37
|
+
if (current !== stack) return nav.forward(nav.history(stack).at(-1) ?? stack, stack);
|
|
38
|
+
if (nav.history(stack).length > 1) return nav.back(stack, stack);
|
|
39
|
+
window.scrollTo({ top: 0, behavior: "smooth" });
|
|
40
|
+
for (const el of document.querySelectorAll<HTMLElement>("main, [data-scroll]"))
|
|
41
|
+
if (el.offsetParent) el.scrollTo({ top: 0, behavior: "smooth" });
|
|
42
|
+
};
|
|
43
|
+
return <Button {...props} selected={current === stack} onClick={onClick} />;
|
|
44
|
+
}
|
package/ui/router/index.d.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
+
export * from "./BackButton.js";
|
|
1
2
|
export * from "./Navigation.js";
|
|
2
3
|
export * from "./NavigationContext.js";
|
|
3
4
|
export * from "./NavigationStore.js";
|
|
4
5
|
export * from "./RouteCache.js";
|
|
5
|
-
export * from "./RouteConfig.js";
|
|
6
|
-
export * from "./RouteContext.js";
|
|
7
6
|
export * from "./Router.js";
|
|
8
7
|
export * from "./Routes.js";
|
|
8
|
+
export * from "./StackButton.js";
|
package/ui/router/index.js
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
+
export * from "./BackButton.js";
|
|
1
2
|
export * from "./Navigation.js";
|
|
2
3
|
export * from "./NavigationContext.js";
|
|
3
4
|
export * from "./NavigationStore.js";
|
|
4
5
|
export * from "./RouteCache.js";
|
|
5
|
-
export * from "./RouteConfig.js";
|
|
6
|
-
export * from "./RouteContext.js";
|
|
7
6
|
export * from "./Router.js";
|
|
8
7
|
export * from "./Routes.js";
|
|
8
|
+
export * from "./StackButton.js";
|
package/ui/router/index.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
+
export * from "./BackButton.js";
|
|
1
2
|
export * from "./Navigation.js";
|
|
2
3
|
export * from "./NavigationContext.js";
|
|
3
4
|
export * from "./NavigationStore.js";
|
|
4
5
|
export * from "./RouteCache.js";
|
|
5
|
-
export * from "./RouteConfig.js";
|
|
6
|
-
export * from "./RouteContext.js";
|
|
7
6
|
export * from "./Router.js";
|
|
8
7
|
export * from "./Routes.js";
|
|
8
|
+
export * from "./StackButton.js";
|
|
@@ -5,7 +5,7 @@ A direction-aware `<Transition>` preset that slides its children horizontally
|
|
|
5
5
|
**Things to know:**
|
|
6
6
|
|
|
7
7
|
- Slides right by default and when the type is `"forward"`; slides left when the type is `"back"`.
|
|
8
|
-
- Inside `<Navigation>` the direction is automatic: a link click
|
|
8
|
+
- Inside `<Navigation>` the direction is automatic: a link click or `NavigationStore.forward()` sets the `"forward"` type, and a `className="back"` link or `NavigationStore.back()` sets `"back"`. The browser back and forward buttons set the type from the page's place in its stack. `NavigationStore.replace()` has no transition. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
|
|
9
9
|
- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
|
|
10
10
|
- The old and new content slide a full width apart, so they sit edge to edge and never overlap.
|
|
11
11
|
- The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
|
|
@@ -5,7 +5,7 @@ A direction-aware `<Transition>` preset that slides its children vertically —
|
|
|
5
5
|
**Things to know:**
|
|
6
6
|
|
|
7
7
|
- Slides down by default and when the type is `"forward"`; slides up when the type is `"back"`.
|
|
8
|
-
- Inside `<Navigation>` the direction is automatic: a link click
|
|
8
|
+
- Inside `<Navigation>` the direction is automatic: a link click or `NavigationStore.forward()` sets the `"forward"` type, and a `className="back"` link or `NavigationStore.back()` sets `"back"`. The browser back and forward buttons set the type from the page's place in its stack. `NavigationStore.replace()` has no transition. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
|
|
9
9
|
- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
|
|
10
10
|
- The old and new content slide a full height apart, so they sit edge to edge and never overlap.
|
|
11
11
|
- The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
|