shelving 1.320.0 → 1.322.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 +230 -1
- package/docs/llms-full.txt +1395 -351
- package/docs/ui/App.md +105 -7
- package/docs/ui/AppLayout.md +85 -0
- package/docs/ui/AppLayoutProps.md +21 -0
- package/docs/ui/BackButton.md +75 -0
- package/docs/ui/BackButtonProps.md +21 -0
- package/docs/ui/Catcher.md +1 -1
- package/docs/ui/ClickableProps.md +0 -2
- package/docs/ui/ErrorPage.md +2 -1
- package/docs/ui/FixedLayout.md +91 -0
- package/docs/ui/FixedLayoutProps.md +13 -0
- package/docs/ui/GapVariants.md +2 -2
- package/docs/ui/Head.md +2 -2
- package/docs/ui/HeightVariant.md +30 -0
- package/docs/ui/HeightVariants.md +26 -0
- 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 +102 -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/PaddingVariants.md +2 -2
- package/docs/ui/Page.md +12 -8
- package/docs/ui/PageLoader.md +2 -1
- package/docs/ui/RouteCache.md +77 -36
- package/docs/ui/RouteCacheProps.md +3 -3
- package/docs/ui/Router.md +12 -6
- package/docs/ui/Scroll.md +60 -6
- package/docs/ui/ScrollVariants.md +5 -1
- package/docs/ui/SidebarLayout.md +17 -8
- package/docs/ui/SpaceValue.md +1 -0
- package/docs/ui/StackButton.md +64 -0
- package/docs/ui/StackButtonProps.md +21 -0
- package/docs/ui/TreeApp.md +1 -1
- package/docs/ui/VerticalTransition.md +1 -1
- package/docs/ui/getBlockClass.md +1 -1
- package/docs/ui/getGapClass.md +1 -1
- package/docs/ui/getHeightClass.md +64 -0
- package/docs/ui/getPaddingClass.md +1 -1
- package/docs/ui/getScrollClass.md +4 -2
- package/docs/ui/getSpaceClass.md +2 -0
- package/docs/ui/mergeMeta.md +2 -1
- package/docs/ui.md +25 -17
- package/package.json +1 -1
- package/ui/README.md +1 -1
- package/ui/app/App.md +105 -7
- package/ui/button/Clickable.d.ts +1 -3
- package/ui/button/Clickable.js +2 -2
- package/ui/button/Clickable.tsx +0 -4
- package/ui/docs/DocumentationApp.js +4 -1
- package/ui/docs/DocumentationApp.tsx +10 -1
- package/ui/layout/AppLayout.d.ts +21 -0
- package/ui/layout/AppLayout.js +18 -0
- package/ui/layout/AppLayout.md +57 -0
- package/ui/layout/AppLayout.module.css +106 -0
- package/ui/layout/AppLayout.tsx +36 -0
- package/ui/layout/FixedLayout.d.ts +18 -0
- package/ui/layout/FixedLayout.js +15 -0
- package/ui/layout/FixedLayout.md +65 -0
- package/ui/layout/FixedLayout.module.css +55 -0
- package/ui/layout/FixedLayout.tsx +25 -0
- package/ui/layout/SidebarLayout.d.ts +2 -2
- package/ui/layout/SidebarLayout.js +3 -4
- package/ui/layout/SidebarLayout.md +15 -6
- package/ui/layout/SidebarLayout.module.css +11 -16
- package/ui/layout/SidebarLayout.tsx +10 -13
- package/ui/layout/index.d.ts +2 -1
- package/ui/layout/index.js +2 -1
- package/ui/layout/index.tsx +2 -1
- package/ui/misc/Catcher.d.ts +2 -1
- package/ui/misc/Catcher.js +4 -3
- package/ui/misc/Catcher.md +1 -1
- package/ui/misc/Catcher.tsx +5 -4
- package/ui/misc/Loader.d.ts +1 -0
- package/ui/misc/Loader.js +6 -2
- package/ui/misc/Loader.tsx +11 -2
- package/ui/page/Head.d.ts +2 -2
- package/ui/page/Head.js +9 -8
- package/ui/page/Head.tsx +8 -6
- package/ui/page/Page.md +12 -8
- 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 +93 -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 +16 -22
- package/ui/router/RouteCache.js +37 -47
- package/ui/router/RouteCache.md +63 -16
- package/ui/router/RouteCache.tsx +56 -62
- package/ui/router/Router.d.ts +2 -1
- package/ui/router/Router.js +9 -14
- package/ui/router/Router.md +10 -5
- 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/style/Block.d.ts +3 -2
- package/ui/style/Block.js +3 -2
- package/ui/style/Block.tsx +4 -2
- package/ui/style/Gap.d.ts +1 -1
- package/ui/style/Gap.tsx +1 -1
- package/ui/style/Height.d.ts +32 -0
- package/ui/style/Height.js +13 -0
- package/ui/style/Height.module.css +88 -0
- package/ui/style/Height.tsx +61 -0
- package/ui/style/Padding.d.ts +1 -1
- package/ui/style/Padding.tsx +1 -1
- package/ui/style/Scroll.d.ts +9 -5
- package/ui/style/Scroll.js +6 -4
- package/ui/style/Scroll.md +59 -0
- package/ui/style/Scroll.module.css +13 -1
- package/ui/style/Scroll.tsx +13 -5
- package/ui/style/Space.d.ts +1 -1
- package/ui/style/Space.module.css +12 -0
- package/ui/style/Space.tsx +1 -0
- package/ui/style/getHeightClass.md +30 -0
- package/ui/style/getSpaceClass.md +2 -0
- package/ui/style/index.d.ts +1 -0
- package/ui/style/index.js +1 -0
- package/ui/style/index.ts +1 -0
- package/ui/transition/HorizontalTransition.md +1 -1
- package/ui/transition/VerticalTransition.md +1 -1
- package/ui/tree/TreeApp.d.ts +1 -1
- package/ui/tree/TreeApp.js +5 -2
- package/ui/tree/TreeApp.tsx +11 -2
- package/ui/util/meta.d.ts +4 -1
- package/ui/util/meta.ts +4 -1
- package/docs/ui/CenteredLayout.md +0 -66
- package/docs/ui/CenteredLayoutProps.md +0 -14
- 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/layout/CenteredLayout.d.ts +0 -21
- package/ui/layout/CenteredLayout.js +0 -28
- package/ui/layout/CenteredLayout.md +0 -41
- package/ui/layout/CenteredLayout.module.css +0 -72
- package/ui/layout/CenteredLayout.tsx +0 -56
- 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/Navigation.md
CHANGED
|
@@ -1,56 +1,122 @@
|
|
|
1
1
|
# Navigation
|
|
2
2
|
|
|
3
|
-
The top-level navigation provider for a client-side app. It owns
|
|
3
|
+
The top-level navigation provider for a client-side app. It owns one `NavigationStore`, turns link clicks into navigation, and publishes the live URL into `<Meta>`, so each `<Router>` re-renders when the URL changes. Use exactly one `<Navigation>` per app. Nested routers all share its store.
|
|
4
|
+
|
|
5
|
+
Give it `stacks` for an app with a tab bar. Each stack is one tab with its own history of pages, like a phone app: each tab remembers where you left it, and a back button goes back within its tab.
|
|
4
6
|
|
|
5
7
|
**Things to know:**
|
|
6
8
|
|
|
7
|
-
- Same-origin
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
- The
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
9
|
+
- Same-origin link clicks become `NavigationStore.forward()`, so the page slides forward.
|
|
10
|
+
- A link with `className="back"` calls `NavigationStore.back()`, so the page slides back. `<BackButton>` sets this class for you.
|
|
11
|
+
- A link with `className="replace"` calls `NavigationStore.replace()`. It changes the URL with no new history entry and no slide, and keeps the same page mounted. Use it for tabs inside a page.
|
|
12
|
+
- Clicks with a modifier key (Cmd, Ctrl, Shift, Alt), a middle-click, and links with `download` or a `target` other than `_self` go to the browser as usual.
|
|
13
|
+
- It publishes each page change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` such as `<HorizontalTransition>` slides the page. A replace has no transition.
|
|
14
|
+
- The browser back and forward buttons slide too. Inside a stack the direction comes from the depth of the page. Across stacks it comes from tab order.
|
|
15
|
+
- When the browser already animated the change (for example a swipe-back on a phone), there is no view transition, so the page does not slide twice.
|
|
16
|
+
- It publishes `stack` (the root of the current stack) into `<Meta>` beside `url`, so any component can read the current tab with `requireMeta().stack`. With no `stacks`, the app has one stack, and `stack` is `"/"`.
|
|
17
|
+
- It reads the start URL and root from the surrounding `<Meta>`, so set `url` and `root` on an ancestor `<App>` or `<HTML>`. In the browser the URL falls back to `window.location.href`.
|
|
18
|
+
- `<Router>` works with no `<Navigation>` (server renders, static renders, tests). `<Navigation>` only makes the URL live on the client.
|
|
19
|
+
|
|
20
|
+
### Browser support
|
|
21
|
+
|
|
22
|
+
Stacks and slides use the browser [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API). Without it (older browsers, a server render, or a sandboxed frame), `<Navigation>` falls back to plain navigation:
|
|
23
|
+
|
|
24
|
+
- Links still go through the app with no page reload, and the browser back button works.
|
|
25
|
+
- There are no stacks, no slides and no `<RouteCache>`. Each page mounts fresh.
|
|
26
|
+
- `<StackButton>` is a plain link to its stack's root. `<BackButton>` is a plain link to its `href`.
|
|
16
27
|
|
|
17
28
|
## Usage
|
|
18
29
|
|
|
30
|
+
### Basic setup
|
|
31
|
+
|
|
19
32
|
```tsx
|
|
20
|
-
import {
|
|
33
|
+
import { App, Navigation, Router } from "shelving/ui";
|
|
21
34
|
|
|
22
|
-
<
|
|
35
|
+
<App root="https://example.com/">
|
|
23
36
|
<Navigation>
|
|
24
37
|
<Router routes={ROUTES}/>
|
|
25
38
|
</Navigation>
|
|
26
|
-
</
|
|
39
|
+
</App>
|
|
27
40
|
```
|
|
28
41
|
|
|
29
|
-
###
|
|
42
|
+
### App with a tab bar
|
|
43
|
+
|
|
44
|
+
List the root path of each stack in tab order. Put a `<StackButton>` for each stack in the tab bar.
|
|
30
45
|
|
|
31
46
|
```tsx
|
|
32
|
-
import { HorizontalTransition, Navigation, Router } from "shelving/ui";
|
|
47
|
+
import { App, AppLayout, HorizontalTransition, Navigation, PageLoader, RouteCache, Router, Scroll, StackButton } from "shelving/ui";
|
|
33
48
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
</
|
|
39
|
-
</
|
|
49
|
+
const STACKS = ["/home", "/discover", "/profile"] as const;
|
|
50
|
+
|
|
51
|
+
const TABS = <>
|
|
52
|
+
<StackButton stack="/home">Home</StackButton>
|
|
53
|
+
<StackButton stack="/discover">Discover</StackButton>
|
|
54
|
+
<StackButton stack="/profile">Profile</StackButton>
|
|
55
|
+
</>;
|
|
56
|
+
|
|
57
|
+
<App root="https://example.com/">
|
|
58
|
+
<Navigation stacks={STACKS}>
|
|
59
|
+
<AppLayout nav={TABS}>
|
|
60
|
+
<HorizontalTransition>
|
|
61
|
+
<RouteCache>
|
|
62
|
+
<Scroll vertical cover>
|
|
63
|
+
<PageLoader>
|
|
64
|
+
<Router routes={ROUTES}/>
|
|
65
|
+
</PageLoader>
|
|
66
|
+
</Scroll>
|
|
67
|
+
</RouteCache>
|
|
68
|
+
</HorizontalTransition>
|
|
69
|
+
</AppLayout>
|
|
70
|
+
</Navigation>
|
|
71
|
+
</App>
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The tab bar is in the layout, outside the cache, so it stays still while pages slide. See "Composing an app" on `<App>` for the full nesting rules.
|
|
75
|
+
|
|
76
|
+
To select a tab when the app starts, pass the starting `stack`. The app decides which stack the opening URL belongs to, for example:
|
|
40
77
|
|
|
41
|
-
|
|
42
|
-
|
|
78
|
+
```tsx
|
|
79
|
+
const path = window.location.pathname;
|
|
80
|
+
const stack = STACKS.find(s => path === s || path.startsWith(`${s}/`));
|
|
81
|
+
|
|
82
|
+
<Navigation stacks={STACKS} stack={stack}>
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Put the transition **outside** `<RouteCache>`, around the whole cache. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
|
|
86
|
+
|
|
87
|
+
The app opens in the `stack` you set on `<Navigation>` (or on the surrounding `<Meta>`, like `url` and `root`), else in the `/` stack. A page in the `/` stack, such as a deep link or a login page, is **unstacked**: no tab is selected, and links from it stay unstacked until you tap a tab or name a stack (for example `nav.replace("/home", "/home")` after a login). See `NavigationStore`.
|
|
88
|
+
|
|
89
|
+
Each link pushes a new page onto the current stack, wherever it points. So a link from `/home` to `/profile/settings` opens the settings page in the Home tab, and the Profile tab stays where it was. Tap a `<StackButton>` to change tab.
|
|
90
|
+
|
|
91
|
+
### Links
|
|
92
|
+
|
|
93
|
+
```tsx
|
|
94
|
+
// Opens a new page in the current stack. Slides forward.
|
|
95
|
+
<Button href="/home/post/1">Open post</Button>
|
|
96
|
+
|
|
97
|
+
// Goes back to a page. Slides back.
|
|
98
|
+
// If the page is already in the stack, the stack goes back to it.
|
|
99
|
+
<Button href="/home" className="back">Back to home</Button>
|
|
100
|
+
|
|
101
|
+
// The back button for a page header. Goes to the page before this one in the stack, or to `href`.
|
|
102
|
+
<BackButton href="/home"/>
|
|
103
|
+
|
|
104
|
+
// Changes the URL but keeps the same page. No slide, no new history entry.
|
|
105
|
+
<Button href="/profile/posts" className="replace">Posts</Button>
|
|
106
|
+
<Button href="/profile/likes" className="replace">Likes</Button>
|
|
43
107
|
```
|
|
44
108
|
|
|
45
109
|
### Imperative navigation
|
|
46
110
|
|
|
47
|
-
Read the
|
|
111
|
+
Read the store from anywhere in the tree with `requireNavigation()`:
|
|
48
112
|
|
|
49
113
|
```tsx
|
|
50
114
|
import { requireNavigation } from "shelving/ui";
|
|
51
115
|
|
|
52
116
|
const nav = requireNavigation();
|
|
53
|
-
nav.forward("/
|
|
54
|
-
nav.
|
|
55
|
-
nav.
|
|
117
|
+
nav.forward("/home/post/1"); // Open a page in the current stack.
|
|
118
|
+
nav.back("/home"); // Go back to a page.
|
|
119
|
+
nav.replace("/login"); // Change the URL of the current page.
|
|
56
120
|
```
|
|
121
|
+
|
|
122
|
+
See `NavigationStore` for what each method does.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { describe, expect, test } from "bun:test";
|
|
2
2
|
import type { ReactNode } from "react";
|
|
3
3
|
import { renderToStaticMarkup } from "react-dom/server";
|
|
4
|
-
import {
|
|
4
|
+
import { BackButton, Navigation, requireMetaURL, StackButton } from "shelving/ui";
|
|
5
5
|
|
|
6
6
|
/** Render `requireMetaURL().path` from inside a component so its `use(MetaContext)` call is valid. */
|
|
7
7
|
function Probe(): ReactNode {
|
|
@@ -27,14 +27,34 @@ describe("Navigation", () => {
|
|
|
27
27
|
expect(html).toBe("/sub");
|
|
28
28
|
});
|
|
29
29
|
|
|
30
|
-
test("
|
|
30
|
+
test("renders a back button as a link to its href with a back class", () => {
|
|
31
31
|
const html = renderToStaticMarkup(
|
|
32
|
-
<Navigation url="http://x.com/
|
|
33
|
-
<
|
|
34
|
-
Back
|
|
35
|
-
</Button>
|
|
32
|
+
<Navigation url="http://x.com/home/post/1" stacks={["/home", "/profile"]}>
|
|
33
|
+
<BackButton href="/home">Back</BackButton>
|
|
36
34
|
</Navigation>,
|
|
37
35
|
);
|
|
38
|
-
expect(html).toContain('
|
|
36
|
+
expect(html).toContain('href="http://x.com/home"');
|
|
37
|
+
expect(html).toContain('class="back"');
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
test("renders a stack button as a link to its root, selected in the starting stack", () => {
|
|
41
|
+
const html = renderToStaticMarkup(
|
|
42
|
+
<Navigation url="http://x.com/profile/settings" stacks={["/home", "/profile"]} stack="/profile">
|
|
43
|
+
<StackButton stack="/home">Home</StackButton>
|
|
44
|
+
<StackButton stack="/profile">Profile</StackButton>
|
|
45
|
+
</Navigation>,
|
|
46
|
+
);
|
|
47
|
+
expect(html).toContain('<a href="http://x.com/home">Home</a>');
|
|
48
|
+
expect(html).toContain('<a href="http://x.com/profile" aria-current="true">Profile</a>');
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
test("selects no stack button on an unstacked page", () => {
|
|
52
|
+
const html = renderToStaticMarkup(
|
|
53
|
+
<Navigation url="http://x.com/settings" stacks={["/home", "/profile"]}>
|
|
54
|
+
<StackButton stack="/home">Home</StackButton>
|
|
55
|
+
<StackButton stack="/profile">Profile</StackButton>
|
|
56
|
+
</Navigation>,
|
|
57
|
+
);
|
|
58
|
+
expect(html).not.toContain("aria-current");
|
|
39
59
|
});
|
|
40
60
|
});
|
package/ui/router/Navigation.tsx
CHANGED
|
@@ -1,93 +1,130 @@
|
|
|
1
1
|
import { type ReactElement, startTransition, useEffect, useState } from "react";
|
|
2
2
|
import { useInstance } from "../../react/useInstance.js";
|
|
3
|
+
import type { AbsolutePath } from "../../util/path.js";
|
|
4
|
+
import type { ImmutableURL } from "../../util/url.js";
|
|
3
5
|
import { MetaContext, requireMeta } from "../misc/MetaContext.js";
|
|
4
6
|
import { setTransitionType } from "../transition/util.js";
|
|
5
7
|
import { mergeMeta, type PossibleMeta } from "../util/index.js";
|
|
6
8
|
import type { OptionalChildProps } from "../util/props.js";
|
|
7
|
-
import { NavigationContext } from "./NavigationContext.js";
|
|
8
|
-
import { NavigationStore } from "./NavigationStore.js";
|
|
9
|
+
import { NavigationContext, NavigationPositionContext } from "./NavigationContext.js";
|
|
10
|
+
import { type NavigationPosition, NavigationStore } from "./NavigationStore.js";
|
|
9
11
|
|
|
10
12
|
/**
|
|
11
|
-
* Props for `<Navigation
|
|
13
|
+
* Props for `<Navigation>`: the initial `Meta` (url, root and stack), the `stacks`, and optional `children`.
|
|
12
14
|
*
|
|
13
15
|
* @see https://shelving.cc/ui/NavigationProps
|
|
14
16
|
*/
|
|
15
|
-
export interface NavigationProps extends PossibleMeta, OptionalChildProps {
|
|
17
|
+
export interface NavigationProps extends PossibleMeta, OptionalChildProps {
|
|
18
|
+
/**
|
|
19
|
+
* Root path of each stack, in tab order, for an app with a tab bar (for example `["/home", "/discover", "/profile"]`).
|
|
20
|
+
* - Each stack keeps its own pages, so each tab remembers where you left it, and a back button goes back within its tab.
|
|
21
|
+
* - With no stacks, the app has one stack at `"/"`, and `stack` in `Meta` is `"/"`.
|
|
22
|
+
*/
|
|
23
|
+
readonly stacks?: readonly AbsolutePath[] | undefined;
|
|
24
|
+
/**
|
|
25
|
+
* Stack of the page the app opens at (for example `"/home"`), like `url` and `root`.
|
|
26
|
+
* - Read from this prop, else from the surrounding `<Meta>`, else `"/"`.
|
|
27
|
+
* - Used only when the opening history entry has no saved stack. A reload keeps the stack it had.
|
|
28
|
+
*/
|
|
29
|
+
readonly stack?: AbsolutePath | undefined;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** What `<Navigation>` publishes on each change. */
|
|
33
|
+
interface _Published {
|
|
34
|
+
readonly url: ImmutableURL;
|
|
35
|
+
readonly stack: AbsolutePath;
|
|
36
|
+
readonly position: NavigationPosition | undefined;
|
|
37
|
+
}
|
|
16
38
|
|
|
17
39
|
/**
|
|
18
|
-
* Top-level navigation provider.
|
|
19
|
-
* - Owns a single `NavigationStore`
|
|
20
|
-
* -
|
|
21
|
-
* -
|
|
22
|
-
* - Publishes
|
|
23
|
-
* -
|
|
24
|
-
* - Skips the transition when the browser already animated the change (`PopStateEvent.hasUAVisualTransition`, e.g. a swipe-back gesture).
|
|
40
|
+
* Top-level navigation provider, with one stack of pages for each tab.
|
|
41
|
+
* - Owns a single `NavigationStore` made from the surrounding `<Meta>` url and root.
|
|
42
|
+
* - Turns clicks on same-origin links into `NavigationStore.forward()`, or `NavigationStore.back()` for a link with `className="back"`, or `NavigationStore.replace()` for a link with `className="replace"`. Clicks with a modifier key, or on links with `download` or a `target`, are left to the browser.
|
|
43
|
+
* - Publishes the URL and the current `stack` into `Meta`, and the position in the stacks into `NavigationPositionContext`, all in one render.
|
|
44
|
+
* - Publishes each change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition. A replace, or a change the browser already animated (for example a swipe-back), has no transition.
|
|
45
|
+
* - Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
|
|
25
46
|
*
|
|
26
|
-
* Exactly one `<Navigation>` per app
|
|
27
|
-
*
|
|
28
|
-
* TODO: switch click/popstate handling to the browser Navigation API when broadly supported.
|
|
47
|
+
* Exactly one `<Navigation>` per app. Nested routers share its store.
|
|
29
48
|
*
|
|
30
49
|
* @kind component
|
|
31
50
|
* @see https://shelving.cc/ui/Navigation
|
|
32
51
|
*/
|
|
33
|
-
export function Navigation({ children, ...meta }: NavigationProps): ReactElement {
|
|
52
|
+
export function Navigation({ children, stacks = [], ...meta }: NavigationProps): ReactElement {
|
|
34
53
|
const current = requireMeta(meta);
|
|
35
|
-
const nav = useInstance(NavigationStore, current.url, current.root);
|
|
54
|
+
const nav = useInstance(NavigationStore, current.url, current.root, current.stack ?? "/", ...stacks);
|
|
36
55
|
|
|
37
56
|
// React runs a `<ViewTransition>` only for a transition update, and `useSyncExternalStore()` always renders a sync update.
|
|
38
|
-
// So keep the published
|
|
39
|
-
const [
|
|
57
|
+
// So keep the published values in state, and copy each store change into it inside `startTransition()`.
|
|
58
|
+
const [published, setPublished] = useState<_Published>(() => _getPublished(nav));
|
|
40
59
|
|
|
41
60
|
useEffect(() => {
|
|
42
|
-
|
|
61
|
+
const stopListening = nav.listen();
|
|
43
62
|
|
|
44
|
-
//
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
63
|
+
// Publish the latest values once for each change, even when the URL and the stack both change.
|
|
64
|
+
let last = nav.value.href;
|
|
65
|
+
let lastStack = nav.stack.value;
|
|
66
|
+
let pending = false;
|
|
67
|
+
const publish = () => {
|
|
68
|
+
const { value, transition } = nav;
|
|
69
|
+
if (value.href === last && nav.stack.value === lastStack) return;
|
|
70
|
+
last = value.href;
|
|
71
|
+
lastStack = nav.stack.value;
|
|
72
|
+
if (pending) return;
|
|
73
|
+
pending = true;
|
|
74
|
+
if (!transition) {
|
|
75
|
+
pending = false;
|
|
76
|
+
return setPublished(_getPublished(nav));
|
|
77
|
+
}
|
|
78
|
+
// React renders a transition that starts inside a browser history event as a sync update with no view transition, so leave the event first.
|
|
79
|
+
setTimeout(() => {
|
|
80
|
+
pending = false;
|
|
51
81
|
startTransition(() => {
|
|
52
|
-
setTransitionType(
|
|
53
|
-
|
|
54
|
-
})
|
|
55
|
-
);
|
|
56
|
-
}
|
|
82
|
+
setTransitionType(transition);
|
|
83
|
+
setPublished(_getPublished(nav));
|
|
84
|
+
});
|
|
85
|
+
});
|
|
86
|
+
};
|
|
87
|
+
const stopURL = nav.subscribe(publish);
|
|
88
|
+
const stopStack = nav.stack.subscribe(publish);
|
|
89
|
+
|
|
90
|
+
// The first render may have run before the store saw the current history entry.
|
|
91
|
+
setPublished(p => (p.url.href === nav.value.href && p.stack === nav.stack.value ? p : _getPublished(nav)));
|
|
57
92
|
|
|
58
93
|
const onClick = (e: MouseEvent) => {
|
|
59
|
-
if (e.target instanceof Element)
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
const href = window.location.href;
|
|
73
|
-
// `"back"` for a `popstate`. `null` means no transition, because the browser already animated the change (e.g. a swipe-back gesture).
|
|
74
|
-
if (href !== nav.value.href) nav.transition = e.hasUAVisualTransition ? null : "back";
|
|
75
|
-
nav.value = href;
|
|
94
|
+
if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || !(e.target instanceof Element))
|
|
95
|
+
return;
|
|
96
|
+
const anchor =
|
|
97
|
+
e.target.closest("a") ||
|
|
98
|
+
(!e.target.closest("button, label") && e.target.closest(".targeted")?.querySelector<HTMLAnchorElement>("a.target[href]"));
|
|
99
|
+
if (!(anchor instanceof HTMLAnchorElement) || anchor.origin !== window.location.origin) return;
|
|
100
|
+
if (anchor.hasAttribute("download") || (anchor.target && anchor.target !== "_self")) return;
|
|
101
|
+
e.preventDefault();
|
|
102
|
+
const { classList, href } = anchor;
|
|
103
|
+
if (classList.contains("back")) nav.back(href);
|
|
104
|
+
else if (classList.contains("replace")) nav.replace(href);
|
|
105
|
+
else nav.forward(href);
|
|
106
|
+
return false; // `return false` stops iOS web app opening every link in a new window.
|
|
76
107
|
};
|
|
77
|
-
|
|
78
108
|
document.addEventListener("click", onClick);
|
|
79
|
-
window.addEventListener("popstate", onPopState);
|
|
80
109
|
|
|
81
110
|
return () => {
|
|
82
111
|
document.removeEventListener("click", onClick);
|
|
83
|
-
|
|
84
|
-
|
|
112
|
+
stopURL();
|
|
113
|
+
stopStack();
|
|
114
|
+
stopListening();
|
|
85
115
|
};
|
|
86
116
|
}, [nav]);
|
|
87
117
|
|
|
118
|
+
const { url, stack, position } = published;
|
|
88
119
|
return (
|
|
89
120
|
<NavigationContext value={nav}>
|
|
90
|
-
<
|
|
121
|
+
<NavigationPositionContext value={position}>
|
|
122
|
+
<MetaContext value={mergeMeta(current, { url, stack }, Navigation)}>{children}</MetaContext>
|
|
123
|
+
</NavigationPositionContext>
|
|
91
124
|
</NavigationContext>
|
|
92
125
|
);
|
|
93
126
|
}
|
|
127
|
+
|
|
128
|
+
function _getPublished(nav: NavigationStore): _Published {
|
|
129
|
+
return { url: nav.value, stack: nav.stack.value, position: nav.position };
|
|
130
|
+
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { NavigationStore } from "./NavigationStore.js";
|
|
1
|
+
import type { NavigationPosition, NavigationStore } from "./NavigationStore.js";
|
|
2
2
|
/**
|
|
3
3
|
* React context holding the current `NavigationStore`, provided by `<Navigation>`.
|
|
4
4
|
*
|
|
@@ -14,3 +14,11 @@ export declare const NavigationContext: import("react").Context<NavigationStore
|
|
|
14
14
|
* @see https://shelving.cc/ui/requireNavigation
|
|
15
15
|
*/
|
|
16
16
|
export declare function requireNavigation(): NavigationStore;
|
|
17
|
+
/**
|
|
18
|
+
* React context holding where the app is in its stacks, published by `<Navigation>` with each URL change.
|
|
19
|
+
* - `undefined` without the browser Navigation API, during a server render, or outside `<Navigation>`.
|
|
20
|
+
* - `<RouteCache>`, `<Router>` and `<BackButton>` read it, so they change in the same render as the URL.
|
|
21
|
+
*
|
|
22
|
+
* @see https://shelving.cc/ui/NavigationPositionContext
|
|
23
|
+
*/
|
|
24
|
+
export declare const NavigationPositionContext: import("react").Context<NavigationPosition | undefined>;
|
|
@@ -18,3 +18,12 @@ NavigationContext.displayName = "NavigationContext";
|
|
|
18
18
|
export function requireNavigation() {
|
|
19
19
|
return requireContext(NavigationContext, requireNavigation);
|
|
20
20
|
}
|
|
21
|
+
/**
|
|
22
|
+
* React context holding where the app is in its stacks, published by `<Navigation>` with each URL change.
|
|
23
|
+
* - `undefined` without the browser Navigation API, during a server render, or outside `<Navigation>`.
|
|
24
|
+
* - `<RouteCache>`, `<Router>` and `<BackButton>` read it, so they change in the same render as the URL.
|
|
25
|
+
*
|
|
26
|
+
* @see https://shelving.cc/ui/NavigationPositionContext
|
|
27
|
+
*/
|
|
28
|
+
export const NavigationPositionContext = createContext(undefined);
|
|
29
|
+
NavigationPositionContext.displayName = "NavigationPositionContext";
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { createContext } from "react";
|
|
2
2
|
import { requireContext } from "../util/context.js";
|
|
3
|
-
import type { NavigationStore } from "./NavigationStore.js";
|
|
3
|
+
import type { NavigationPosition, NavigationStore } from "./NavigationStore.js";
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
6
|
* React context holding the current `NavigationStore`, provided by `<Navigation>`.
|
|
@@ -21,3 +21,13 @@ NavigationContext.displayName = "NavigationContext";
|
|
|
21
21
|
export function requireNavigation(): NavigationStore {
|
|
22
22
|
return requireContext(NavigationContext, requireNavigation);
|
|
23
23
|
}
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* React context holding where the app is in its stacks, published by `<Navigation>` with each URL change.
|
|
27
|
+
* - `undefined` without the browser Navigation API, during a server render, or outside `<Navigation>`.
|
|
28
|
+
* - `<RouteCache>`, `<Router>` and `<BackButton>` read it, so they change in the same render as the URL.
|
|
29
|
+
*
|
|
30
|
+
* @see https://shelving.cc/ui/NavigationPositionContext
|
|
31
|
+
*/
|
|
32
|
+
export const NavigationPositionContext = createContext<NavigationPosition | undefined>(undefined);
|
|
33
|
+
NavigationPositionContext.displayName = "NavigationPositionContext";
|
|
@@ -1,47 +1,154 @@
|
|
|
1
|
+
import { Store } from "../../store/Store.js";
|
|
1
2
|
import { URLStore } from "../../store/URLStore.js";
|
|
3
|
+
import type { AbsolutePath } from "../../util/path.js";
|
|
2
4
|
import { type PossibleURL } from "../../util/url.js";
|
|
3
5
|
import type { TransitionType } from "../transition/util.js";
|
|
4
6
|
/**
|
|
5
|
-
*
|
|
7
|
+
* State that `NavigationStore` saves on each browser history entry.
|
|
6
8
|
*
|
|
7
|
-
*
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
* @see https://shelving.cc/ui/NavigationEntryState
|
|
10
|
+
*/
|
|
11
|
+
export interface NavigationEntryState {
|
|
12
|
+
/** Root path of the stack this page is in. */
|
|
13
|
+
readonly stack: AbsolutePath;
|
|
14
|
+
/** Position of this page in its stack, where `0` is the root. */
|
|
15
|
+
readonly depth: number;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Where the app is now in its stacks: the current stack and depth, the top depth of each stack, and the page before the current one.
|
|
19
|
+
* - `undefined` when the browser has no Navigation API, or during a server render.
|
|
20
|
+
*
|
|
21
|
+
* @see https://shelving.cc/ui/NavigationPosition
|
|
22
|
+
*/
|
|
23
|
+
export interface NavigationPosition extends NavigationEntryState {
|
|
24
|
+
/** Depth of the top page of each stack that has pages. */
|
|
25
|
+
readonly tops: {
|
|
26
|
+
readonly [stack: AbsolutePath]: number;
|
|
27
|
+
};
|
|
28
|
+
/** The page before the current one in its stack, or `undefined` at the bottom of the stack. */
|
|
29
|
+
readonly parent: AbsolutePath | undefined;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Store that holds the current navigation URL, drives browser history, and keeps a stack of pages for each tab.
|
|
33
|
+
*
|
|
34
|
+
* - Extends `URLStore`, so its `value` is the current URL.
|
|
35
|
+
* - 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.
|
|
36
|
+
* - `stack` is a sub-store that holds the root of the current stack. It only changes when the stack changes.
|
|
37
|
+
* - 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
|
+
* - Owned by `<Navigation>`. Read it with `requireNavigation()`.
|
|
11
39
|
*
|
|
12
40
|
* @see https://shelving.cc/ui/NavigationStore
|
|
13
41
|
*/
|
|
14
42
|
export declare class NavigationStore extends URLStore {
|
|
15
|
-
/**
|
|
43
|
+
/** Root path of each stack, in tab order. A single-stack app has one root. */
|
|
44
|
+
readonly stacks: readonly AbsolutePath[];
|
|
45
|
+
/**
|
|
46
|
+
* Root path of the current stack.
|
|
47
|
+
* - Always set. With no `stacks`, it is `"/"`.
|
|
48
|
+
* - It starts at the `stack` given to the constructor (default `"/"`). Without the Navigation API, it stays there.
|
|
49
|
+
*/
|
|
50
|
+
readonly stack: Store<AbsolutePath>;
|
|
51
|
+
/**
|
|
52
|
+
* Transition type of the most recent change, read by `<Navigation>` when the value changes.
|
|
53
|
+
* - `null` means no transition: a replace, a change the browser already animated (for example a swipe-back), or no Navigation API.
|
|
54
|
+
*/
|
|
16
55
|
transition: TransitionType | null;
|
|
17
|
-
|
|
56
|
+
/** The browser Navigation API, or `undefined` when it is not available. */
|
|
57
|
+
private readonly _navigation;
|
|
58
|
+
/** Transition sent with the next navigation, and whether the browser animates it. */
|
|
59
|
+
private _info;
|
|
60
|
+
/** `true` while the store changes history itself, so it ignores the events that causes. */
|
|
61
|
+
private _busy;
|
|
62
|
+
/** Stack of the page the app opens at, when its history entry has no saved stack. */
|
|
63
|
+
private readonly _start;
|
|
64
|
+
constructor(url?: PossibleURL, base?: PossibleURL, stack?: AbsolutePath, ...stacks: AbsolutePath[]);
|
|
18
65
|
/**
|
|
19
|
-
*
|
|
66
|
+
* Where the app is now: the current stack and depth, and the top depth of each stack.
|
|
67
|
+
*
|
|
68
|
+
* @returns The position, or `undefined` without the Navigation API.
|
|
69
|
+
* @see https://shelving.cc/ui/NavigationStore/position
|
|
70
|
+
*/
|
|
71
|
+
get position(): NavigationPosition | undefined;
|
|
72
|
+
/**
|
|
73
|
+
* Start listening to the browser (back, forward and swipe).
|
|
74
|
+
* - Saves the current stack and depth on the current history entry, if it has none.
|
|
75
|
+
* - `<Navigation>` calls it once, when it mounts.
|
|
76
|
+
*
|
|
77
|
+
* @returns A function that stops listening.
|
|
78
|
+
* @see https://shelving.cc/ui/NavigationStore/listen
|
|
79
|
+
*/
|
|
80
|
+
listen(): () => void;
|
|
81
|
+
/**
|
|
82
|
+
* Get the pages in a stack, root first, or every page in every stack.
|
|
83
|
+
* - Read from the browser history entries up to the current one.
|
|
84
|
+
* - A stack whose root entry is gone (the browser keeps a limited history) still starts with its root.
|
|
85
|
+
* - Without the Navigation API this is always empty.
|
|
86
|
+
*
|
|
87
|
+
* @param stack Root path of the stack. Defaults to the current stack.
|
|
88
|
+
* @returns Paths relative to the app root, each with its `?query`.
|
|
89
|
+
* @example nav.history("/home") // ["/home", "/home/post/2"]
|
|
90
|
+
* @see https://shelving.cc/ui/NavigationStore/history
|
|
91
|
+
*/
|
|
92
|
+
history(stack?: AbsolutePath): AbsolutePath[];
|
|
93
|
+
/**
|
|
94
|
+
* Go forward to a URL, as a link does.
|
|
95
|
+
* - The URL is the top page of `stack`: switch to that stack, at the same depth. This is a tab switch.
|
|
96
|
+
* - Else push the URL onto `stack`, one level deeper than its top page.
|
|
97
|
+
* - The URL you are already on: replace it instead.
|
|
98
|
+
* - A change of stack slides by tab order. Else it slides forward.
|
|
20
99
|
*
|
|
21
100
|
* @param possible The destination URL, resolved against `base`.
|
|
101
|
+
* @param stack Root path of the stack to go to. Defaults to the current stack.
|
|
22
102
|
* @throws RequiredError If `possible` cannot be resolved to a valid URL.
|
|
23
103
|
* @example nav.forward("/settings");
|
|
24
104
|
* @see https://shelving.cc/ui/NavigationStore/forward
|
|
25
105
|
*/
|
|
26
|
-
forward(possible: PossibleURL): void;
|
|
106
|
+
forward(possible: PossibleURL, stack?: AbsolutePath): void;
|
|
27
107
|
/**
|
|
28
|
-
*
|
|
108
|
+
* Go back to a URL, as a back button does.
|
|
109
|
+
* - 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.
|
|
110
|
+
* - The URL is the root of `stack`: push it at depth 0.
|
|
111
|
+
* - Else push the URL in place of the top page of `stack`.
|
|
112
|
+
* - It works when the app was opened at the current page, so a back button always has somewhere to go.
|
|
29
113
|
*
|
|
30
114
|
* @param possible The destination URL, resolved against `base`.
|
|
115
|
+
* @param stack Root path of the stack to go back in. Defaults to the current stack.
|
|
31
116
|
* @throws RequiredError If `possible` cannot be resolved to a valid URL.
|
|
32
|
-
* @example nav.
|
|
33
|
-
* @see https://shelving.cc/ui/NavigationStore/
|
|
117
|
+
* @example nav.back("/profile");
|
|
118
|
+
* @see https://shelving.cc/ui/NavigationStore/back
|
|
34
119
|
*/
|
|
35
|
-
|
|
120
|
+
back(possible: PossibleURL, stack?: AbsolutePath): void;
|
|
36
121
|
/**
|
|
37
|
-
*
|
|
38
|
-
* -
|
|
39
|
-
* -
|
|
122
|
+
* Replace the current URL, with no transition.
|
|
123
|
+
* - The page stays in the same stack, at the same depth, so a cached page stays mounted.
|
|
124
|
+
* - Use it for a page that knows its canonical URL, or for in-page tabs.
|
|
125
|
+
* - 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")`.
|
|
40
126
|
*
|
|
41
127
|
* @param possible The destination URL, resolved against `base`.
|
|
128
|
+
* @param stack Root path of the stack to move the page into. Defaults to the current stack.
|
|
42
129
|
* @throws RequiredError If `possible` cannot be resolved to a valid URL.
|
|
43
|
-
* @example nav.
|
|
44
|
-
* @see https://shelving.cc/ui/NavigationStore/
|
|
130
|
+
* @example nav.replace("/login");
|
|
131
|
+
* @see https://shelving.cc/ui/NavigationStore/replace
|
|
45
132
|
*/
|
|
46
|
-
|
|
133
|
+
replace(possible: PossibleURL, stack?: AbsolutePath): void;
|
|
134
|
+
/** Push a URL as a new history entry, with an optional state. */
|
|
135
|
+
private _push;
|
|
136
|
+
/** Change history and then save a state on the new entry, ignoring the events that causes. */
|
|
137
|
+
private _write;
|
|
138
|
+
/** Save a state on the current entry. */
|
|
139
|
+
private _update;
|
|
140
|
+
/** Set the stack first, then the URL, so both are ready when `<Navigation>` reads them. */
|
|
141
|
+
private _change;
|
|
142
|
+
/** 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. */
|
|
143
|
+
private _getPages;
|
|
144
|
+
/** 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. */
|
|
145
|
+
private _getState;
|
|
146
|
+
/** Get every stack a page can be in: the listed stacks, plus the unstacked `"/"` stack. */
|
|
147
|
+
private _getStacks;
|
|
148
|
+
/** Get the path of a URL relative to the app root, or `undefined` if it is outside the app. */
|
|
149
|
+
private _getPath;
|
|
150
|
+
/** Direction of a change the store did not make: tab order across stacks, else depth, else position. */
|
|
151
|
+
private _getDirection;
|
|
152
|
+
/** Slide direction between two stacks by tab order, or `undefined` for the same stack. */
|
|
153
|
+
private _getOrder;
|
|
47
154
|
}
|