shelving 1.322.2 → 1.323.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 +1 -1
- package/docs/llms-full.txt +62 -48
- package/docs/ui/BackButton.md +1 -1
- package/docs/ui/Card.md +1 -1
- package/docs/ui/Meta.md +2 -2
- package/docs/ui/Navigation.md +4 -4
- package/docs/ui/NavigationEntryState.md +2 -2
- package/docs/ui/NavigationPosition.md +2 -2
- package/docs/ui/NavigationProps.md +3 -3
- package/docs/ui/NavigationStore/back.md +1 -1
- package/docs/ui/NavigationStore/forward.md +1 -1
- package/docs/ui/NavigationStore/history.md +3 -2
- package/docs/ui/NavigationStore/replace.md +1 -1
- package/docs/ui/NavigationStore.md +26 -15
- package/docs/ui/RouteCache.md +7 -5
- package/docs/ui/RouteCacheProps.md +1 -1
- package/docs/ui/StackButton.md +5 -5
- package/docs/ui/mergeMeta.md +1 -1
- package/package.json +1 -1
- package/ui/block/Card.md +1 -1
- package/ui/block/Card.module.css +10 -5
- package/ui/router/BackButton.md +1 -1
- package/ui/router/Navigation.d.ts +4 -3
- package/ui/router/Navigation.js +1 -1
- package/ui/router/Navigation.md +2 -2
- package/ui/router/Navigation.test.tsx +11 -1
- package/ui/router/Navigation.tsx +6 -5
- package/ui/router/NavigationStore.d.ts +32 -24
- package/ui/router/NavigationStore.js +42 -27
- package/ui/router/NavigationStore.md +18 -10
- package/ui/router/NavigationStore.test.ts +90 -23
- package/ui/router/NavigationStore.tsx +58 -41
- package/ui/router/RouteCache.d.ts +5 -3
- package/ui/router/RouteCache.js +20 -7
- package/ui/router/RouteCache.md +3 -2
- package/ui/router/RouteCache.tsx +30 -9
- package/ui/router/StackButton.d.ts +2 -2
- package/ui/router/StackButton.js +3 -3
- package/ui/router/StackButton.md +3 -3
- package/ui/router/StackButton.tsx +3 -3
- package/ui/util/meta.d.ts +2 -2
- package/ui/util/meta.ts +2 -2
|
@@ -8,7 +8,9 @@ Store that holds the current navigation URL, drives browser history, and keeps a
|
|
|
8
8
|
|
|
9
9
|
- Extends `URLStore`, so its `value` is the current URL.
|
|
10
10
|
- 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.
|
|
11
|
-
- `stack` is a sub-store that holds the root of the current stack. It only changes when the stack changes.
|
|
11
|
+
- `stack` is a sub-store that holds the root of the current stack, or `null` for a floating page. It only changes when the stack changes.
|
|
12
|
+
- A page outside the listed stacks is floating: its stack is `null`. The floating stack has no root page and no tab.
|
|
13
|
+
- In a listed stack, depth `0` is always the stack's root path.
|
|
12
14
|
- Without the Navigation API (older browsers and server renders) there are no stacks: `stack` stays the starting stack, `history()` is empty, and `stack` arguments are ignored.
|
|
13
15
|
- Owned by `<Navigation>`. Read it with `requireNavigation()`.
|
|
14
16
|
|
|
@@ -16,9 +18,11 @@ The store that holds the current URL, drives browser history, and keeps one stac
|
|
|
16
18
|
|
|
17
19
|
**Things to know:**
|
|
18
20
|
|
|
19
|
-
- `NavigationStore.stacks` is the root path of each stack, in tab order, from the `stacks` prop on `<Navigation>`.
|
|
20
|
-
- A page that is not in a listed stack is **
|
|
21
|
-
-
|
|
21
|
+
- `NavigationStore.stacks` is the root path of each stack, in tab order, from the `stacks` prop on `<Navigation>`. `/` is a normal stack root, like any other path.
|
|
22
|
+
- A page that is not in a listed stack is **floating**: its stack is `null`. See [Floating pages](#floating-pages).
|
|
23
|
+
- In a listed stack, depth `0` is always the stack's root path. A deeper page always has the root below it.
|
|
24
|
+
- `NavigationStore.stack` is a sub-store that holds the root of the current stack, or `null` on a floating page. It changes only when the stack changes, so `useStore(nav.stack)` re-renders only on a tab change.
|
|
25
|
+
- `NavigationStore.path` is the current path relative to the app root, without its `?query`.
|
|
22
26
|
- `NavigationStore.history()` returns the pages in the current stack (or a given stack), root first.
|
|
23
27
|
- `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.
|
|
24
28
|
- All URLs resolve against the store's `base`. Each method also takes a full same-origin URL.
|
|
@@ -33,17 +37,23 @@ The store that holds the current URL, drives browser history, and keeps one stac
|
|
|
33
37
|
| `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 |
|
|
34
38
|
| `history(stack?)` | Returns the pages in `stack`, root first. | — |
|
|
35
39
|
|
|
36
|
-
`stack` defaults to the current stack.
|
|
40
|
+
`stack` defaults to the current stack. Pass `null` to name the floating stack.
|
|
37
41
|
|
|
38
|
-
##
|
|
42
|
+
## Floating pages
|
|
39
43
|
|
|
40
|
-
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
|
|
44
|
+
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 it **floats**: its stack is `null`. For example: a deep link into the app, a fresh open of `/post/9`, or a login page.
|
|
45
|
+
|
|
46
|
+
- The floating stack is outside every tab. It has no root page and no `<StackButton>`, so no stack button is selected on a floating page.
|
|
47
|
+
- Links from a floating page push deeper in the floating stack, even a link to a stack root.
|
|
48
|
+
- To leave the floating stack, tap a `<StackButton>`, or name the stack. To move a page back into it, pass `null` as the `stack`.
|
|
49
|
+
- `<RouteCache>` gives floating pages no protection: they are dropped like any other page past `maxCached`.
|
|
50
|
+
- With no `stacks`, every page floats.
|
|
51
|
+
|
|
52
|
+
## Opening the app
|
|
41
53
|
|
|
42
|
-
- On an unstacked page, no `<StackButton>` is selected.
|
|
43
|
-
- Links from an unstacked page push deeper in the `/` stack, even a link to a stack root.
|
|
44
|
-
- To leave the `/` stack, tap a `<StackButton>`, or name the stack.
|
|
45
54
|
- 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.
|
|
46
|
-
-
|
|
55
|
+
- A deep page the app opens at, in a listed stack, starts at depth 1, so the stack root is its parent. A `<StackButton>` or a back gesture then goes to the root. A stack root starts at depth 0.
|
|
56
|
+
- A `stack` that is not in `stacks` is ignored: the page floats.
|
|
47
57
|
|
|
48
58
|
For example, a login page sends the user home after they log in, and names the Home stack:
|
|
49
59
|
|
|
@@ -117,7 +127,7 @@ nav.forward("/home/post/1");
|
|
|
117
127
|
## Signatures
|
|
118
128
|
|
|
119
129
|
```ts
|
|
120
|
-
new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL, stack: AbsolutePath =
|
|
130
|
+
new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL, stack: AbsolutePath | null = null, ...stacks: AbsolutePath[])
|
|
121
131
|
```
|
|
122
132
|
|
|
123
133
|
## Parameters
|
|
@@ -126,7 +136,7 @@ new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : win
|
|
|
126
136
|
| --- | --- | --- |
|
|
127
137
|
| `url` | `PossibleURL` | Defaults to `typeof window === "undefined" ? "/" : window.location.href`. |
|
|
128
138
|
| `base` | `PossibleURL` | Optional. |
|
|
129
|
-
| `stack` | `AbsolutePath` | Defaults to `
|
|
139
|
+
| `stack` | `AbsolutePath \| null` | Defaults to `null`. |
|
|
130
140
|
| `stacks` | `AbsolutePath[]` | |
|
|
131
141
|
|
|
132
142
|
## Returns
|
|
@@ -139,9 +149,10 @@ new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : win
|
|
|
139
149
|
|
|
140
150
|
| Property | Type | Description |
|
|
141
151
|
| --- | --- | --- |
|
|
142
|
-
| `stacks` | `readonly AbsolutePath[]` | Root path of each stack, in tab order.
|
|
143
|
-
| `stack` | `Store<AbsolutePath>` | Root path of the current stack
|
|
152
|
+
| `stacks` | `readonly AbsolutePath[]` | Root path of each stack, in tab order. With none, every page floats. Read only. |
|
|
153
|
+
| `stack` | `Store<AbsolutePath \| null>` | Root path of the current stack, or `null` for a floating page. - It starts at the `stack` given to the constructor (default `null`). Without the Navigation API, it stays there. Read only. |
|
|
144
154
|
| `transition` | `TransitionType \| null` | Transition type of the most recent change, read by `<Navigation>` when the value changes. - `null` means no transition: a replace, a change the browser already animated (for example a swipe-back), or no Navigation API. Defaults to `null`. |
|
|
155
|
+
| `path` | `AbsolutePath \| undefined` | Path of the current URL relative to the app root (without its `?query`), or `undefined` if the URL is outside the app. Read only. |
|
|
145
156
|
| `position` | `NavigationPosition \| undefined` | Where the app is now: the current stack and depth, and the top depth of each stack. Read only. |
|
|
146
157
|
|
|
147
158
|
## Methods
|
package/docs/ui/RouteCache.md
CHANGED
|
@@ -9,8 +9,9 @@ Keep-alive page cache for the pages in the navigation stacks. Put it in a layout
|
|
|
9
9
|
- 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.
|
|
10
10
|
- 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.
|
|
11
11
|
- 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.
|
|
12
|
-
- The top page of each stack
|
|
13
|
-
-
|
|
12
|
+
- The root page and the top page of each listed stack are never dropped. Other pages, and every floating page, can be dropped past `maxCached`, and show fresh (from the top) when you come back to them.
|
|
13
|
+
- When the current page is deeper than its stack's root and the root page is not cached (for example after a deep link), the root page is rendered hidden, so a swipe-back can show it.
|
|
14
|
+
- Each kept page is frozen under its own `<MetaContext>` and `NavigationPositionContext`, so the same `children` element renders a different page for each URL, and a hidden page never re-renders for another page's URL.
|
|
14
15
|
- `<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.
|
|
15
16
|
- Without the browser Navigation API (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
|
|
16
17
|
|
|
@@ -23,11 +24,12 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
|
|
|
23
24
|
- Each page is keyed by its stack and its depth in that stack, not by its URL. See `NavigationStore` for how stacks work.
|
|
24
25
|
- 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.
|
|
25
26
|
- 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.
|
|
26
|
-
- The top page of each stack
|
|
27
|
+
- The root page and the top page of each listed stack are never dropped, so each tab always shows the page you left, and always has its root below. Other pages, and every floating page, are dropped (least recently used first) past `maxCached`, and mount fresh when you come back to them.
|
|
28
|
+
- When the current page is deeper than its stack's root and the root page is not cached (for example after a deep link), the cache renders the root page hidden, so a swipe-back can show it. A hidden page runs no effects until it is shown.
|
|
27
29
|
- `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}>`.
|
|
28
30
|
- The same URL open in two stacks is two separate pages.
|
|
29
31
|
- 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).
|
|
30
|
-
- Each kept page is frozen under its own `<Meta
|
|
32
|
+
- Each kept page is frozen under its own `<Meta>` and `NavigationPositionContext`, so a hidden page never re-renders for another page's URL.
|
|
31
33
|
- `<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.
|
|
32
34
|
- **Nesting:** layout, then transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. See the usage below.
|
|
33
35
|
- The scroll box goes **inside** the cache, so each kept page has its own scroll box and keeps its own scroll position. A scroll box outside the cache is shared by every page, so pages lose their scroll.
|
|
@@ -100,7 +102,7 @@ RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode
|
|
|
100
102
|
| Param | Type | Description |
|
|
101
103
|
| --- | --- | --- |
|
|
102
104
|
| `props` | `RouteCacheProps` | |
|
|
103
|
-
| `.maxCached` | `number \| undefined` | 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. - The top page of each stack
|
|
105
|
+
| `.maxCached` | `number \| undefined` | 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. - The root page and the top page of each listed stack are never dropped, even past the limit, so a tab always shows the page you left and always has its root below. - Floating pages get no such protection. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
|
|
104
106
|
| `.children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
|
|
105
107
|
|
|
106
108
|
## Returns
|
|
@@ -18,5 +18,5 @@ Props for `<RouteCache>`: the `maxCached` size and the content `children` to kee
|
|
|
18
18
|
|
|
19
19
|
| Property | Type | Description |
|
|
20
20
|
| --- | --- | --- |
|
|
21
|
-
| `maxCached` | `number \| undefined` | 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. - The top page of each stack
|
|
21
|
+
| `maxCached` | `number \| undefined` | 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. - The root page and the top page of each listed stack are never dropped, even past the limit, so a tab always shows the page you left and always has its root below. - Floating pages get no such protection. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
|
|
22
22
|
| `children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
|
package/docs/ui/StackButton.md
CHANGED
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
|
|
6
6
|
Button for one stack in a tab bar.
|
|
7
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 its root.
|
|
9
|
-
- Tap it again
|
|
8
|
+
- Tap the current stack's button: go back to its root path.
|
|
9
|
+
- Tap it again on the root path: scroll the page to the top.
|
|
10
10
|
- It is selected while its stack is the current stack.
|
|
11
11
|
- Without the browser Navigation API (and in a server render) it is a plain link to the stack's root.
|
|
12
12
|
|
|
@@ -15,9 +15,9 @@ A button for one stack in a tab bar. It acts like a tab button in a phone app.
|
|
|
15
15
|
**Things to know:**
|
|
16
16
|
|
|
17
17
|
- Tap another stack's button: go to the page you left in that stack. The page slides left or right, by tab order.
|
|
18
|
-
- Tap the current stack's button: go back to the root of the stack. The page slides back.
|
|
19
|
-
- Tap it again
|
|
20
|
-
- It is selected (`aria-current`) while its stack is the current stack. On
|
|
18
|
+
- Tap the current stack's button: go back to the root path of the stack. The page slides back. If the root is not in the history (for example after a deep link), it opens the root.
|
|
19
|
+
- Tap it again on the root path: scroll the page to the top. It scrolls the window, and each visible `<main>` or `[data-scroll]` element.
|
|
20
|
+
- It is selected (`aria-current`) while its stack is the current stack. On a floating page (for example a deep link or a login page), no stack button is selected.
|
|
21
21
|
- `stack` must be one of the `stacks` on `<Navigation>`.
|
|
22
22
|
- It takes the usual `<Button>` props, except `href`, `onClick` and `selected`.
|
|
23
23
|
- 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.
|
package/docs/ui/mergeMeta.md
CHANGED
|
@@ -23,7 +23,7 @@ mergeMeta(meta1: Meta, meta2: PossibleMeta, caller: AnyCaller = mergeMeta): Meta
|
|
|
23
23
|
| `meta1` | `Meta` | The existing fully-resolved `Meta` to merge into. |
|
|
24
24
|
| `.root` | `ImmutableURL \| undefined` | Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). Read only. Optional. |
|
|
25
25
|
| `.url` | `ImmutableURL \| undefined` | URL of the current page (used as the initial URL for routing, and as the page's canonical URL in `<Head>`). Read only. Optional. |
|
|
26
|
-
| `.stack` | `AbsolutePath \| undefined` | Root path of the current stack (for example `"/home"`). Set it above `<Navigation>` to choose the stack the app opens in. `<Navigation>` publishes the live stack, which is `
|
|
26
|
+
| `.stack` | `AbsolutePath \| null \| undefined` | Root path of the current stack (for example `"/home"`). Set it above `<Navigation>` to choose the stack the app opens in. `<Navigation>` publishes the live stack, which is `null` for a floating page. Read only. Optional. |
|
|
27
27
|
| `.app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
|
|
28
28
|
| `.title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
|
|
29
29
|
| `.description` | `string \| undefined` | Description of the current page. Read only. Optional. |
|
package/package.json
CHANGED
package/ui/block/Card.md
CHANGED
|
@@ -5,7 +5,7 @@ A boxed surface that groups a self-contained piece of content. Rendered as an `<
|
|
|
5
5
|
**Things to know:**
|
|
6
6
|
|
|
7
7
|
- Set `href` or `onClick` to make the whole card navigable — a stretched, visually-hidden overlay `<a>` / `<button>` covers the card while the children render normally inside. Real interactive elements inside the card (inline links, buttons) stay clickable and keyboard-focusable.
|
|
8
|
-
- The overlay
|
|
8
|
+
- The overlay comes first in the card and has no `z-index`. Links and buttons inside the card are `position: relative`, so they paint above it and stay clickable. To put your own absolute layer over the card's content, put it after the content, with no `z-index` and no lasting `transform`. A `transform` makes the layer a stacking context, and a `z-index` can make iOS WebKit drop the layer for one frame when a page view transition starts. Only a keyboard-focused overlay gets a `z-index`, so its focus ring shows above the content.
|
|
9
9
|
- `color=` and `status=` move the tint anchor for the card's scope, so the surface, text, and hover shade all re-derive together — and nested components (`<Tag>`, `<Preformatted>`, `<Button>`) inherit the same tint.
|
|
10
10
|
- A card styles only the box. Lay out its contents with the usual block components (`<Subheading>`, `<Paragraph>`, `<Row>`, …).
|
|
11
11
|
- Cards have no drop shadow by default — set `shadow="small"`, `shadow="normal"` or `shadow="large"` to raise a given card.
|
package/ui/block/Card.module.css
CHANGED
|
@@ -8,11 +8,11 @@
|
|
|
8
8
|
|
|
9
9
|
@layer defaults {
|
|
10
10
|
.card {
|
|
11
|
-
/* Children —
|
|
11
|
+
/* Children — positioned, and after the overlay, so they paint above it and stay clickable.
|
|
12
|
+
* No z-index: iOS WebKit can drop a z-indexed layer for one frame when a page view transition starts. */
|
|
12
13
|
a:any-link,
|
|
13
14
|
button:enabled {
|
|
14
15
|
position: relative;
|
|
15
|
-
z-index: 2;
|
|
16
16
|
}
|
|
17
17
|
}
|
|
18
18
|
}
|
|
@@ -44,9 +44,10 @@
|
|
|
44
44
|
/* Under `.card` so it beats the `.prose a` link rule, and the hidden link text stays hidden inside `<Prose>`. */
|
|
45
45
|
.card > .overlay {
|
|
46
46
|
/* Box */
|
|
47
|
+
|
|
48
|
+
/* First in the card, positioned, with no z-index: it paints above the card's text, and below its positioned links and buttons. */
|
|
47
49
|
position: absolute;
|
|
48
50
|
inset: 0;
|
|
49
|
-
z-index: 1;
|
|
50
51
|
border: 0;
|
|
51
52
|
border-radius: inherit;
|
|
52
53
|
|
|
@@ -54,7 +55,7 @@
|
|
|
54
55
|
background: transparent;
|
|
55
56
|
cursor: pointer;
|
|
56
57
|
|
|
57
|
-
/* Focus ring — drawn on the overlay
|
|
58
|
+
/* Focus ring — drawn on the overlay. The offset pushes it out over the card border, so it sits fully inside the card edge. */
|
|
58
59
|
outline: var(--card-focus-border, var(--stroke-focus) solid var(--color-focus));
|
|
59
60
|
outline-offset: calc(var(--card-stroke, 0px) - var(--stroke-focus));
|
|
60
61
|
|
|
@@ -70,9 +71,13 @@
|
|
|
70
71
|
|
|
71
72
|
@layer overrides {
|
|
72
73
|
.card > .overlay {
|
|
73
|
-
/* Show the focus ring only while the overlay is keyboard-focused. */
|
|
74
|
+
/* Show the focus ring only while the overlay is keyboard-focused. Then lift it, so the ring paints above positioned children (e.g. `.panel`). */
|
|
74
75
|
&:not(:focus-visible) {
|
|
75
76
|
outline-color: transparent;
|
|
76
77
|
}
|
|
78
|
+
|
|
79
|
+
&:focus-visible {
|
|
80
|
+
z-index: 3;
|
|
81
|
+
}
|
|
77
82
|
}
|
|
78
83
|
}
|
package/ui/router/BackButton.md
CHANGED
|
@@ -5,7 +5,7 @@ The back button for a page header. It goes back to the page before this one in t
|
|
|
5
5
|
**Things to know:**
|
|
6
6
|
|
|
7
7
|
- It goes to the page before this one in the current stack. If you opened a post from a search, it goes back to the search.
|
|
8
|
-
- It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. So a back button always has somewhere to go. Set `href` to the page's natural parent. On
|
|
8
|
+
- It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. So a back button always has somewhere to go. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
|
|
9
9
|
- It is a plain link with `className="back"`. `<Navigation>` turns a click into `NavigationStore.back()`, so the page slides back. A middle-click opens the link in a new browser tab.
|
|
10
10
|
- Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
|
|
11
11
|
- It takes the usual `<Button>` props, except `onClick`.
|
|
@@ -11,15 +11,16 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {
|
|
|
11
11
|
/**
|
|
12
12
|
* Root path of each stack, in tab order, for an app with a tab bar (for example `["/home", "/discover", "/profile"]`).
|
|
13
13
|
* - Each stack keeps its own pages, so each tab remembers where you left it, and a back button goes back within its tab.
|
|
14
|
-
* -
|
|
14
|
+
* - A page outside these stacks is floating: its stack is `null`, and no tab is selected.
|
|
15
|
+
* - With no stacks, every page floats.
|
|
15
16
|
*/
|
|
16
17
|
readonly stacks?: readonly AbsolutePath[] | undefined;
|
|
17
18
|
/**
|
|
18
19
|
* Stack of the page the app opens at (for example `"/home"`), like `url` and `root`.
|
|
19
|
-
* - Read from this prop, else from the surrounding `<Meta>`, else `
|
|
20
|
+
* - Read from this prop, else from the surrounding `<Meta>`, else `null` (floating).
|
|
20
21
|
* - Used only when the opening history entry has no saved stack. A reload keeps the stack it had.
|
|
21
22
|
*/
|
|
22
|
-
readonly stack?: AbsolutePath | undefined;
|
|
23
|
+
readonly stack?: AbsolutePath | null | undefined;
|
|
23
24
|
}
|
|
24
25
|
/**
|
|
25
26
|
* Top-level navigation provider, with one stack of pages for each tab.
|
package/ui/router/Navigation.js
CHANGED
|
@@ -21,7 +21,7 @@ import { NavigationStore } from "./NavigationStore.js";
|
|
|
21
21
|
*/
|
|
22
22
|
export function Navigation({ children, stacks = [], ...meta }) {
|
|
23
23
|
const current = requireMeta(meta);
|
|
24
|
-
const nav = useInstance(NavigationStore, current.url, current.root, current.stack ??
|
|
24
|
+
const nav = useInstance(NavigationStore, current.url, current.root, current.stack ?? null, ...stacks);
|
|
25
25
|
// React runs a `<ViewTransition>` only for a transition update, and `useSyncExternalStore()` always renders a sync update.
|
|
26
26
|
// So keep the published values in state, and copy each store change into it inside `startTransition()`.
|
|
27
27
|
const [published, setPublished] = useState(() => _getPublished(nav));
|
package/ui/router/Navigation.md
CHANGED
|
@@ -13,7 +13,7 @@ Give it `stacks` for an app with a tab bar. Each stack is one tab with its own h
|
|
|
13
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
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
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`.
|
|
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`. On a floating page (outside every stack) `stack` is `null`. With no `stacks`, every page floats.
|
|
17
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
18
|
- `<Router>` works with no `<Navigation>` (server renders, static renders, tests). `<Navigation>` only makes the URL live on the client.
|
|
19
19
|
|
|
@@ -86,7 +86,7 @@ const stack = STACKS.find(s => path === s || path.startsWith(`${s}/`));
|
|
|
86
86
|
|
|
87
87
|
Put the transition **outside** `<RouteCache>`, around the whole cache. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
|
|
88
88
|
|
|
89
|
-
The app opens in the `stack` you set on `<Navigation>` (or on the surrounding `<Meta>`, like `url` and `root`), else
|
|
89
|
+
The app opens in the `stack` you set on `<Navigation>` (or on the surrounding `<Meta>`, like `url` and `root`), else the page **floats**: its stack is `null`. A floating page, such as a deep link or a login page, is outside every tab: no tab is selected, and links from it stay floating until you tap a tab or name a stack (for example `nav.replace("/home", "/home")` after a login). `/` is a normal stack root, so a Home tab at `/` is never mixed up with floating pages. See `NavigationStore`.
|
|
90
90
|
|
|
91
91
|
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.
|
|
92
92
|
|
|
@@ -48,7 +48,7 @@ describe("Navigation", () => {
|
|
|
48
48
|
expect(html).toContain('<a href="http://x.com/profile" aria-current="true">Profile</a>');
|
|
49
49
|
});
|
|
50
50
|
|
|
51
|
-
test("selects no stack button on
|
|
51
|
+
test("selects no stack button on a floating page", () => {
|
|
52
52
|
const html = renderToStaticMarkup(
|
|
53
53
|
<Navigation url="http://x.com/settings" stacks={["/home", "/profile"]}>
|
|
54
54
|
<StackButton stack="/home">Home</StackButton>
|
|
@@ -57,4 +57,14 @@ describe("Navigation", () => {
|
|
|
57
57
|
);
|
|
58
58
|
expect(html).not.toContain("aria-current");
|
|
59
59
|
});
|
|
60
|
+
|
|
61
|
+
test("selects no stack button on a floating page when / is a stack", () => {
|
|
62
|
+
const html = renderToStaticMarkup(
|
|
63
|
+
<Navigation url="http://x.com/post/1" stacks={["/", "/profile"]}>
|
|
64
|
+
<StackButton stack="/">Home</StackButton>
|
|
65
|
+
<StackButton stack="/profile">Profile</StackButton>
|
|
66
|
+
</Navigation>,
|
|
67
|
+
);
|
|
68
|
+
expect(html).not.toContain("aria-current");
|
|
69
|
+
});
|
|
60
70
|
});
|
package/ui/router/Navigation.tsx
CHANGED
|
@@ -18,21 +18,22 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {
|
|
|
18
18
|
/**
|
|
19
19
|
* Root path of each stack, in tab order, for an app with a tab bar (for example `["/home", "/discover", "/profile"]`).
|
|
20
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
|
-
* -
|
|
21
|
+
* - A page outside these stacks is floating: its stack is `null`, and no tab is selected.
|
|
22
|
+
* - With no stacks, every page floats.
|
|
22
23
|
*/
|
|
23
24
|
readonly stacks?: readonly AbsolutePath[] | undefined;
|
|
24
25
|
/**
|
|
25
26
|
* 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
|
+
* - Read from this prop, else from the surrounding `<Meta>`, else `null` (floating).
|
|
27
28
|
* - Used only when the opening history entry has no saved stack. A reload keeps the stack it had.
|
|
28
29
|
*/
|
|
29
|
-
readonly stack?: AbsolutePath | undefined;
|
|
30
|
+
readonly stack?: AbsolutePath | null | undefined;
|
|
30
31
|
}
|
|
31
32
|
|
|
32
33
|
/** What `<Navigation>` publishes on each change. */
|
|
33
34
|
interface _Published {
|
|
34
35
|
readonly url: ImmutableURL;
|
|
35
|
-
readonly stack: AbsolutePath;
|
|
36
|
+
readonly stack: AbsolutePath | null;
|
|
36
37
|
readonly position: NavigationPosition | undefined;
|
|
37
38
|
}
|
|
38
39
|
|
|
@@ -51,7 +52,7 @@ interface _Published {
|
|
|
51
52
|
*/
|
|
52
53
|
export function Navigation({ children, stacks = [], ...meta }: NavigationProps): ReactElement {
|
|
53
54
|
const current = requireMeta(meta);
|
|
54
|
-
const nav = useInstance(NavigationStore, current.url, current.root, current.stack ??
|
|
55
|
+
const nav = useInstance(NavigationStore, current.url, current.root, current.stack ?? null, ...stacks);
|
|
55
56
|
|
|
56
57
|
// React runs a `<ViewTransition>` only for a transition update, and `useSyncExternalStore()` always renders a sync update.
|
|
57
58
|
// So keep the published values in state, and copy each store change into it inside `startTransition()`.
|
|
@@ -9,8 +9,8 @@ import type { TransitionType } from "../transition/util.js";
|
|
|
9
9
|
* @see https://shelving.cc/ui/NavigationEntryState
|
|
10
10
|
*/
|
|
11
11
|
export interface NavigationEntryState {
|
|
12
|
-
/** Root path of the stack this page is in. */
|
|
13
|
-
readonly stack: AbsolutePath;
|
|
12
|
+
/** Root path of the stack this page is in, or `null` for a floating page. */
|
|
13
|
+
readonly stack: AbsolutePath | null;
|
|
14
14
|
/** Position of this page in its stack, where `0` is the root. */
|
|
15
15
|
readonly depth: number;
|
|
16
16
|
}
|
|
@@ -21,10 +21,8 @@ export interface NavigationEntryState {
|
|
|
21
21
|
* @see https://shelving.cc/ui/NavigationPosition
|
|
22
22
|
*/
|
|
23
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
|
-
};
|
|
24
|
+
/** Depth of the top page of each stack that has pages, including the floating stack (`null`). */
|
|
25
|
+
readonly tops: ReadonlyMap<AbsolutePath | null, number>;
|
|
28
26
|
/** The page before the current one in its stack, or `undefined` at the bottom of the stack. */
|
|
29
27
|
readonly parent: AbsolutePath | undefined;
|
|
30
28
|
}
|
|
@@ -33,21 +31,22 @@ export interface NavigationPosition extends NavigationEntryState {
|
|
|
33
31
|
*
|
|
34
32
|
* - Extends `URLStore`, so its `value` is the current URL.
|
|
35
33
|
* - 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.
|
|
34
|
+
* - `stack` is a sub-store that holds the root of the current stack, or `null` for a floating page. It only changes when the stack changes.
|
|
35
|
+
* - A page outside the listed stacks is floating: its stack is `null`. The floating stack has no root page and no tab.
|
|
36
|
+
* - In a listed stack, depth `0` is always the stack's root path.
|
|
37
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
38
|
* - Owned by `<Navigation>`. Read it with `requireNavigation()`.
|
|
39
39
|
*
|
|
40
40
|
* @see https://shelving.cc/ui/NavigationStore
|
|
41
41
|
*/
|
|
42
42
|
export declare class NavigationStore extends URLStore {
|
|
43
|
-
/** Root path of each stack, in tab order.
|
|
43
|
+
/** Root path of each stack, in tab order. With none, every page floats. */
|
|
44
44
|
readonly stacks: readonly AbsolutePath[];
|
|
45
45
|
/**
|
|
46
|
-
* Root path of the current stack.
|
|
47
|
-
* -
|
|
48
|
-
* - It starts at the `stack` given to the constructor (default `"/"`). Without the Navigation API, it stays there.
|
|
46
|
+
* Root path of the current stack, or `null` for a floating page.
|
|
47
|
+
* - It starts at the `stack` given to the constructor (default `null`). Without the Navigation API, it stays there.
|
|
49
48
|
*/
|
|
50
|
-
readonly stack: Store<AbsolutePath>;
|
|
49
|
+
readonly stack: Store<AbsolutePath | null>;
|
|
51
50
|
/**
|
|
52
51
|
* Transition type of the most recent change, read by `<Navigation>` when the value changes.
|
|
53
52
|
* - `null` means no transition: a replace, a change the browser already animated (for example a swipe-back), or no Navigation API.
|
|
@@ -61,7 +60,13 @@ export declare class NavigationStore extends URLStore {
|
|
|
61
60
|
private _busy;
|
|
62
61
|
/** Stack of the page the app opens at, when its history entry has no saved stack. */
|
|
63
62
|
private readonly _start;
|
|
64
|
-
constructor(url?: PossibleURL, base?: PossibleURL, stack?: AbsolutePath, ...stacks: AbsolutePath[]);
|
|
63
|
+
constructor(url?: PossibleURL, base?: PossibleURL, stack?: AbsolutePath | null, ...stacks: AbsolutePath[]);
|
|
64
|
+
/**
|
|
65
|
+
* Path of the current URL relative to the app root (without its `?query`), or `undefined` if the URL is outside the app.
|
|
66
|
+
*
|
|
67
|
+
* @see https://shelving.cc/ui/NavigationStore/path
|
|
68
|
+
*/
|
|
69
|
+
get path(): AbsolutePath | undefined;
|
|
65
70
|
/**
|
|
66
71
|
* Where the app is now: the current stack and depth, and the top depth of each stack.
|
|
67
72
|
*
|
|
@@ -81,15 +86,16 @@ export declare class NavigationStore extends URLStore {
|
|
|
81
86
|
/**
|
|
82
87
|
* Get the pages in a stack, root first, or every page in every stack.
|
|
83
88
|
* - Read from the browser history entries up to the current one.
|
|
84
|
-
* - A stack whose root entry is
|
|
89
|
+
* - A listed stack whose root entry is not in the history (a deep link, or the browser keeps a limited history) still starts with its root.
|
|
90
|
+
* - The floating stack (`null`) has no root, so it starts with its oldest page.
|
|
85
91
|
* - Without the Navigation API this is always empty.
|
|
86
92
|
*
|
|
87
|
-
* @param stack Root path of the stack. Defaults to the current stack.
|
|
93
|
+
* @param stack Root path of the stack, or `null` for the floating stack. Defaults to the current stack.
|
|
88
94
|
* @returns Paths relative to the app root, each with its `?query`.
|
|
89
95
|
* @example nav.history("/home") // ["/home", "/home/post/2"]
|
|
90
96
|
* @see https://shelving.cc/ui/NavigationStore/history
|
|
91
97
|
*/
|
|
92
|
-
history(stack?: AbsolutePath): AbsolutePath[];
|
|
98
|
+
history(stack?: AbsolutePath | null): AbsolutePath[];
|
|
93
99
|
/**
|
|
94
100
|
* Go forward to a URL, as a link does.
|
|
95
101
|
* - The URL is the top page of `stack`: switch to that stack, at the same depth. This is a tab switch.
|
|
@@ -98,12 +104,12 @@ export declare class NavigationStore extends URLStore {
|
|
|
98
104
|
* - A change of stack slides by tab order. Else it slides forward.
|
|
99
105
|
*
|
|
100
106
|
* @param possible The destination URL, resolved against `base`.
|
|
101
|
-
* @param stack Root path of the stack to go to. Defaults to the current stack.
|
|
107
|
+
* @param stack Root path of the stack to go to, or `null` for the floating stack. Defaults to the current stack.
|
|
102
108
|
* @throws RequiredError If `possible` cannot be resolved to a valid URL.
|
|
103
109
|
* @example nav.forward("/settings");
|
|
104
110
|
* @see https://shelving.cc/ui/NavigationStore/forward
|
|
105
111
|
*/
|
|
106
|
-
forward(possible: PossibleURL, stack?: AbsolutePath): void;
|
|
112
|
+
forward(possible: PossibleURL, stack?: AbsolutePath | null): void;
|
|
107
113
|
/**
|
|
108
114
|
* Go back to a URL, as a back button does.
|
|
109
115
|
* - The URL is an earlier page in `stack`: go back to it. When it is the entry just before the current one, this goes back in the browser history. Else it pushes the URL again at that page's depth.
|
|
@@ -112,12 +118,12 @@ export declare class NavigationStore extends URLStore {
|
|
|
112
118
|
* - It works when the app was opened at the current page, so a back button always has somewhere to go.
|
|
113
119
|
*
|
|
114
120
|
* @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.
|
|
121
|
+
* @param stack Root path of the stack to go back in, or `null` for the floating stack. Defaults to the current stack.
|
|
116
122
|
* @throws RequiredError If `possible` cannot be resolved to a valid URL.
|
|
117
123
|
* @example nav.back("/profile");
|
|
118
124
|
* @see https://shelving.cc/ui/NavigationStore/back
|
|
119
125
|
*/
|
|
120
|
-
back(possible: PossibleURL, stack?: AbsolutePath): void;
|
|
126
|
+
back(possible: PossibleURL, stack?: AbsolutePath | null): void;
|
|
121
127
|
/**
|
|
122
128
|
* Replace the current URL, with no transition.
|
|
123
129
|
* - The page stays in the same stack, at the same depth, so a cached page stays mounted.
|
|
@@ -125,12 +131,12 @@ export declare class NavigationStore extends URLStore {
|
|
|
125
131
|
* - 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")`.
|
|
126
132
|
*
|
|
127
133
|
* @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.
|
|
134
|
+
* @param stack Root path of the stack to move the page into, or `null` for the floating stack. Defaults to the current stack.
|
|
129
135
|
* @throws RequiredError If `possible` cannot be resolved to a valid URL.
|
|
130
136
|
* @example nav.replace("/login");
|
|
131
137
|
* @see https://shelving.cc/ui/NavigationStore/replace
|
|
132
138
|
*/
|
|
133
|
-
replace(possible: PossibleURL, stack?: AbsolutePath): void;
|
|
139
|
+
replace(possible: PossibleURL, stack?: AbsolutePath | null): void;
|
|
134
140
|
/** Push a URL as a new history entry, with an optional state. */
|
|
135
141
|
private _push;
|
|
136
142
|
/** Change history and then save a state on the new entry, ignoring the events that causes. */
|
|
@@ -141,9 +147,11 @@ export declare class NavigationStore extends URLStore {
|
|
|
141
147
|
private _change;
|
|
142
148
|
/** Get the pages in a stack, root first: the newest entry in the stack, then the newest earlier entry at a lower depth, down to depth 0. */
|
|
143
149
|
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
|
|
150
|
+
/** Get the saved state of an entry, or for an entry with none (for example the page the app opened at), the starting stack at its bottom depth. */
|
|
145
151
|
private _getState;
|
|
146
|
-
/** Get
|
|
152
|
+
/** Get the depth of a URL that is the first page of a stack: `0` for the stack's root path or for the floating stack, else `1` so the root stays below it. */
|
|
153
|
+
private _getBottomDepth;
|
|
154
|
+
/** Get every stack a page can be in: the listed stacks, plus the floating stack (`null`). */
|
|
147
155
|
private _getStacks;
|
|
148
156
|
/** Get the path of a URL relative to the app root, or `undefined` if it is outside the app. */
|
|
149
157
|
private _getPath;
|