shelving 1.323.3 → 1.325.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/guides/building-with-shelving.md +3 -3
- package/docs/llms-full.txt +412 -149
- package/docs/react/SequenceTransitionOptions.md +26 -0
- package/docs/react/useSequenceTransition.md +71 -0
- package/docs/react.md +2 -0
- package/docs/ui/BackButton.md +1 -1
- package/docs/ui/Head.md +1 -1
- package/docs/ui/HorizontalTransition.md +1 -1
- package/docs/ui/Meta.md +2 -0
- package/docs/ui/Navigation.md +19 -17
- package/docs/ui/NavigationContext.md +2 -2
- package/docs/ui/NavigationDirection.md +12 -0
- package/docs/ui/NavigationEntryState.md +3 -3
- package/docs/ui/NavigationEvent.md +28 -0
- package/docs/ui/{NavigationStore → NavigationSequence}/back.md +6 -5
- package/docs/ui/NavigationSequence/committed.md +13 -0
- package/docs/ui/NavigationSequence/current.md +13 -0
- package/docs/ui/{NavigationStore → NavigationSequence}/forward.md +4 -4
- package/docs/ui/{NavigationStore → NavigationSequence}/history.md +3 -3
- package/docs/ui/{NavigationStore → NavigationSequence}/listen.md +3 -3
- package/docs/ui/NavigationSequence/publish.md +14 -0
- package/docs/ui/{NavigationStore → NavigationSequence}/replace.md +4 -4
- package/docs/ui/NavigationSequence.md +187 -0
- package/docs/ui/RouteCache.md +16 -15
- package/docs/ui/RouteCacheProps.md +1 -1
- package/docs/ui/Router.md +2 -2
- package/docs/ui/Transition.md +1 -1
- package/docs/ui/VerticalTransition.md +1 -1
- package/docs/ui/isKeyboardOpen.md +27 -0
- package/docs/ui/mergeMeta.md +1 -0
- package/docs/ui/requireContext.md +1 -1
- package/docs/ui/requireNavigation.md +3 -3
- package/docs/ui/waitForKeyboard.md +29 -0
- package/docs/ui.md +8 -6
- package/package.json +1 -1
- package/react/index.d.ts +1 -0
- package/react/index.js +1 -0
- package/react/useSequenceTransition.d.ts +45 -0
- package/react/useSequenceTransition.js +56 -0
- package/ui/page/Head.d.ts +1 -1
- package/ui/page/Head.js +9 -4
- package/ui/page/Head.tsx +8 -4
- package/ui/router/BackButton.js +6 -3
- package/ui/router/BackButton.md +1 -1
- package/ui/router/BackButton.tsx +6 -3
- package/ui/router/Navigation.d.ts +6 -5
- package/ui/router/Navigation.js +36 -49
- package/ui/router/Navigation.md +13 -12
- package/ui/router/Navigation.tsx +37 -59
- package/ui/router/NavigationContext.d.ts +7 -15
- package/ui/router/NavigationContext.js +4 -13
- package/ui/router/NavigationContext.tsx +7 -17
- package/ui/router/{NavigationStore.d.ts → NavigationSequence.d.ts} +93 -51
- package/ui/router/{NavigationStore.js → NavigationSequence.js} +132 -80
- package/ui/router/NavigationSequence.md +129 -0
- package/ui/router/{NavigationStore.test.ts → NavigationSequence.test.ts} +126 -61
- package/ui/router/{NavigationStore.tsx → NavigationSequence.tsx} +160 -92
- package/ui/router/RouteCache.d.ts +8 -7
- package/ui/router/RouteCache.js +34 -29
- package/ui/router/RouteCache.md +9 -8
- package/ui/router/RouteCache.tsx +39 -36
- package/ui/router/Router.d.ts +2 -2
- package/ui/router/Router.js +3 -5
- package/ui/router/Router.md +1 -1
- package/ui/router/Router.tsx +4 -5
- package/ui/router/StackButton.d.ts +1 -1
- package/ui/router/StackButton.js +5 -7
- package/ui/router/StackButton.tsx +6 -7
- package/ui/router/index.d.ts +1 -1
- package/ui/router/index.js +1 -1
- package/ui/router/index.ts +1 -1
- package/ui/transition/HorizontalTransition.md +1 -1
- package/ui/transition/Transition.md +1 -1
- package/ui/transition/VerticalTransition.md +1 -1
- package/ui/util/index.d.ts +1 -0
- package/ui/util/index.js +1 -0
- package/ui/util/index.ts +1 -0
- package/ui/util/keyboard.d.ts +24 -0
- package/ui/util/keyboard.js +82 -0
- package/ui/util/keyboard.test.ts +12 -0
- package/ui/util/keyboard.ts +81 -0
- package/ui/util/meta.d.ts +2 -0
- package/ui/util/meta.ts +2 -0
- package/ui/util/requireContext.md +1 -1
- package/docs/ui/NavigationPosition.md +0 -24
- package/docs/ui/NavigationPositionContext.md +0 -8
- package/docs/ui/NavigationStore.md +0 -164
- package/ui/router/NavigationStore.md +0 -110
package/docs/llms-full.txt
CHANGED
|
@@ -713,7 +713,7 @@ Each tab keeps its own stack of pages, and its back button goes back within that
|
|
|
713
713
|
3. Put `<BackButton href="/home" />` in each page header. It goes back in the current tab, or to `href` when there is no page before.
|
|
714
714
|
4. Use `<RouteCache>`, so each tab shows the page you left it on.
|
|
715
715
|
|
|
716
|
-
Use `className="replace"` on in-page tab links (for example `/dave/posts` and `/dave/likes`), so they change the URL without a new page. See `<Navigation>`, `
|
|
716
|
+
Use `className="replace"` on in-page tab links (for example `/dave/posts` and `/dave/likes`), so they change the URL without a new page. See `<Navigation>`, `NavigationSequence`, `<StackButton>` and `<BackButton>`.
|
|
717
717
|
|
|
718
718
|
#### Hide the tab bar on some pages
|
|
719
719
|
|
|
@@ -1083,7 +1083,7 @@ If every file in that list is in the right place, the client and server share on
|
|
|
1083
1083
|
3. **Remove `<RouteConfig>`.** `<RouteConfig>` and `RouteContext` are removed.
|
|
1084
1084
|
- `<RouteConfig path>` kept a page mounted for its tabs (for example `/dave/{tab}`). Instead, add `className="replace"` to each in-page tab link: `<Button href="/dave/posts" className="replace">Posts</Button>`. A replace keeps the same page mounted, with no slide and no new history entry.
|
|
1085
1085
|
- `<RouteConfig cache={false}>` unmounted a create form when you left it. Instead, clear the form after a successful submit: change the `key` of the `<Form>`, or call `form.reset()` on a plain HTML form. See `<RouteCache>` for an example.
|
|
1086
|
-
4. **Canonical URLs.** `<Head>` no longer writes browser history itself. When a page renders a `<Head>` with a `url` that is not the current URL, `<Head>` calls `
|
|
1086
|
+
4. **Canonical URLs.** `<Head>` no longer writes browser history itself. When a page renders a `<Head>` with a `url` that is not the current URL, `<Head>` calls `NavigationSequence.replace()`. You do not need to change anything, but do not also call `window.history.replaceState()` for it.
|
|
1087
1087
|
5. **Add stacks (optional).** For an app with a tab bar, set `stacks` on `<Navigation>` to the root path of each tab, in tab order: `<Navigation stacks={["/home", "/discover", "/profile"]}>`. Each link then opens a new page in the current tab, wherever it points. Set `stack` on `<Navigation>` to the stack the app opens in. With no `stack`, the page floats (its stack is `null`): it is outside every tab, so no tab is selected until the user taps a tab, or the app names a stack. Deep links and login pages float. `/` is a normal stack root, so a Home tab can be `/`. A login page calls `nav.replace("/home", "/home")` to send the user into the Home tab.
|
|
1088
1088
|
6. **Use the new buttons (optional).**
|
|
1089
1089
|
- `<StackButton stack="/home">` is a tab bar button. It goes to the page you left in that tab, goes back to the tab's root when you are already in it, and scrolls to the top at the root.
|
|
@@ -1098,7 +1098,7 @@ What changes for users:
|
|
|
1098
1098
|
- The browser back button walks the history as before, across tabs. The page slides the right way.
|
|
1099
1099
|
- When you go back from a page, it leaves the cache. So the browser forward button then shows that page fresh, from the top.
|
|
1100
1100
|
|
|
1101
|
-
See `<Navigation>`, `
|
|
1101
|
+
See `<Navigation>`, `NavigationSequence`, `<RouteCache>`, `<StackButton>` and `<BackButton>` for the full details.
|
|
1102
1102
|
|
|
1103
1103
|
### Layouts are frames
|
|
1104
1104
|
|
|
@@ -11478,12 +11478,14 @@ function Toggle() {
|
|
|
11478
11478
|
- [useMap()](react/useMap.md): Create a mutable Map that persists for the lifetime of the component.
|
|
11479
11479
|
- [useReduce()](react/useReduce.md): Use memoised value with reduction logic.
|
|
11480
11480
|
- [useSequence()](react/useSequence.md): Subscribe to an async iterable for the lifetime of the component.
|
|
11481
|
+
- [useSequenceTransition()](react/useSequenceTransition.md): Subscribe to an async iterable, and set each value it yields inside a React transition.
|
|
11481
11482
|
- [useStore()](react/useStore.md): Subscribe to a Shelving Store instance to refresh this component when its value changes.
|
|
11482
11483
|
|
|
11483
11484
|
## Interfaces
|
|
11484
11485
|
|
|
11485
11486
|
- [APIContext](react/APIContext.md): Bundle of hooks and a provider component returned by createAPIContext()
|
|
11486
11487
|
- [DBContext](react/DBContext.md): Bundle of hooks and a provider component returned by createDBContext().
|
|
11488
|
+
- [SequenceTransitionOptions](react/SequenceTransitionOptions.md): Options for useSequenceTransition().
|
|
11487
11489
|
|
|
11488
11490
|
|
|
11489
11491
|
---
|
|
@@ -12054,6 +12056,111 @@ useSequence(sequence?: AsyncIterable<T>): T | undefined
|
|
|
12054
12056
|
| `unknown` | unknown Re-throws (during render) any error thrown by the sequence, for an error boundary to catch. |
|
|
12055
12057
|
|
|
12056
12058
|
|
|
12059
|
+
---
|
|
12060
|
+
|
|
12061
|
+
# SequenceTransitionOptions
|
|
12062
|
+
|
|
12063
|
+
- Kind: interface
|
|
12064
|
+
- Import: `import { SequenceTransitionOptions } from "shelving/react";`
|
|
12065
|
+
|
|
12066
|
+
Options for `useSequenceTransition()`.
|
|
12067
|
+
|
|
12068
|
+
## Signatures
|
|
12069
|
+
|
|
12070
|
+
```ts
|
|
12071
|
+
{
|
|
12072
|
+
readonly current: () => T;
|
|
12073
|
+
readonly transition?: string | ((value: T) => string | null | undefined) | undefined;
|
|
12074
|
+
readonly equal?: ((a: T, b: T) => boolean) | undefined;
|
|
12075
|
+
readonly wait?: ((value: T) => PromiseLike<void> | void) | undefined;
|
|
12076
|
+
}
|
|
12077
|
+
```
|
|
12078
|
+
|
|
12079
|
+
## Properties
|
|
12080
|
+
|
|
12081
|
+
| Property | Type | Description |
|
|
12082
|
+
| --- | --- | --- |
|
|
12083
|
+
| `current` | `() => T` | Read the current value. - Called for the first render, and again when the subscription starts, to catch up on values sent before it started. Read only. |
|
|
12084
|
+
| `transition` | `string \| ((value: T) => string \| null \| undefined) \| undefined` | Transition type for a value, or a fixed type for every value. - A value with a type is set inside `startTransition()` with that type, so a `<ViewTransition>` can animate it. - A value with no type (`undefined` or `null`) is set at once, with no transition. Read only. Optional. |
|
|
12085
|
+
| `equal` | `((a: T, b: T) => boolean) \| undefined` | Is a new value the same as the shown value? A value that is the same is skipped, so it starts no second transition. Read only. Defaults to `Object.is`. |
|
|
12086
|
+
| `wait` | `((value: T) => PromiseLike<void> \| void) \| undefined` | Wait before a value with a transition type is set, for example until the on-screen keyboard is down. - Return a promise to wait for it, or nothing to set the value at once. - A newer value that arrives while it waits wins: the older value is never set. - Values with no transition type never wait. Read only. Optional. |
|
|
12087
|
+
|
|
12088
|
+
|
|
12089
|
+
---
|
|
12090
|
+
|
|
12091
|
+
# useSequenceTransition()
|
|
12092
|
+
|
|
12093
|
+
- Kind: function
|
|
12094
|
+
- Import: `import { useSequenceTransition } from "shelving/react";`
|
|
12095
|
+
|
|
12096
|
+
Subscribe to an async iterable, and set each value it yields inside a React transition.
|
|
12097
|
+
- Like `useSequence()`, but each value is set with `setState()` inside `startTransition()`, with a transition type, so a `<ViewTransition>` runs for it.
|
|
12098
|
+
- It uses `useState()` and not `useSyncExternalStore()`, because React always renders a `useSyncExternalStore()` update at once, outside any transition.
|
|
12099
|
+
- The transition type is shared by the whole React root: the next transition commit takes every type that is waiting.
|
|
12100
|
+
|
|
12101
|
+
Subscribe to an `AsyncIterable` and set each value it yields inside a React transition, with a transition type. A `<ViewTransition>` (or a `<Transition>` such as `<HorizontalTransition>`) around the content that reads the value then animates each change. `<Navigation>` uses it to slide pages.
|
|
12102
|
+
|
|
12103
|
+
**Things to know:**
|
|
12104
|
+
|
|
12105
|
+
- It uses `useState()`, not `useSyncExternalStore()`. React always renders a `useSyncExternalStore()` update at once, outside any transition, so a store read can never animate.
|
|
12106
|
+
- `current` gives the first value, and is read again when the subscription starts, to catch up on values sent before it started.
|
|
12107
|
+
- `transition` is a fixed type, or a function that returns the type for each value. A value with no type is set at once, with no transition.
|
|
12108
|
+
- `equal` skips a value that is the same as the value shown, so it starts no second transition. It defaults to `Object.is`.
|
|
12109
|
+
- Transition types belong to the whole React root: the next transition commit takes every type that is waiting.
|
|
12110
|
+
- If the sequence throws, the error is re-thrown during render, so the nearest error boundary catches it.
|
|
12111
|
+
- Memoise the iterable. The subscription restarts when the iterable changes.
|
|
12112
|
+
|
|
12113
|
+
## Usage
|
|
12114
|
+
|
|
12115
|
+
```tsx
|
|
12116
|
+
import { useSequenceTransition } from "shelving/react";
|
|
12117
|
+
import { ViewTransition } from "react";
|
|
12118
|
+
|
|
12119
|
+
function Slides({ slides }: { slides: SlideSequence }) {
|
|
12120
|
+
const slide = useSequenceTransition(slides, {
|
|
12121
|
+
current: () => slides.current,
|
|
12122
|
+
transition: s => s.direction, // "forward", "back", or undefined for no animation
|
|
12123
|
+
equal: (a, b) => a.id === b.id,
|
|
12124
|
+
});
|
|
12125
|
+
return (
|
|
12126
|
+
<ViewTransition update={{ forward: "slide-forward", back: "slide-back", default: "none" }}>
|
|
12127
|
+
<Slide slide={slide} />
|
|
12128
|
+
</ViewTransition>
|
|
12129
|
+
);
|
|
12130
|
+
}
|
|
12131
|
+
```
|
|
12132
|
+
|
|
12133
|
+
|
|
12134
|
+
## Signatures
|
|
12135
|
+
|
|
12136
|
+
```ts
|
|
12137
|
+
useSequenceTransition(sequence: AsyncIterable<T>, options: SequenceTransitionOptions<T>): T
|
|
12138
|
+
```
|
|
12139
|
+
|
|
12140
|
+
## Parameters
|
|
12141
|
+
|
|
12142
|
+
| Param | Type | Description |
|
|
12143
|
+
| --- | --- | --- |
|
|
12144
|
+
| `sequence` | `AsyncIterable<T>` | An object implementing the `AsyncIterable` interface. - Subscription is recreated every time this value changes. - Memoise this value to persist the subscription for the lifetime of the component. |
|
|
12145
|
+
| `options` | `SequenceTransitionOptions<T>` | |
|
|
12146
|
+
| `.current` | `() => T` | Read the current value. - Called for the first render, and again when the subscription starts, to catch up on values sent before it started. Read only. |
|
|
12147
|
+
| `.transition` | `string \| ((value: T) => string \| null \| undefined) \| undefined` | Transition type for a value, or a fixed type for every value. - A value with a type is set inside `startTransition()` with that type, so a `<ViewTransition>` can animate it. - A value with no type (`undefined` or `null`) is set at once, with no transition. Read only. Optional. |
|
|
12148
|
+
| `.equal` | `((a: T, b: T) => boolean) \| undefined` | Is a new value the same as the shown value? A value that is the same is skipped, so it starts no second transition. Read only. Defaults to `Object.is`. |
|
|
12149
|
+
| `.wait` | `((value: T) => PromiseLike<void> \| void) \| undefined` | Wait before a value with a transition type is set, for example until the on-screen keyboard is down. - Return a promise to wait for it, or nothing to set the value at once. - A newer value that arrives while it waits wins: the older value is never set. - Values with no transition type never wait. Read only. Optional. |
|
|
12150
|
+
|
|
12151
|
+
## Returns
|
|
12152
|
+
|
|
12153
|
+
| Type | Description |
|
|
12154
|
+
| --- | --- |
|
|
12155
|
+
| `T` | The value shown now. |
|
|
12156
|
+
|
|
12157
|
+
## Throws
|
|
12158
|
+
|
|
12159
|
+
| Type | Description |
|
|
12160
|
+
| --- | --- |
|
|
12161
|
+
| `unknown` | unknown Re-throws (during render) any error thrown by the sequence, for an error boundary to catch. |
|
|
12162
|
+
|
|
12163
|
+
|
|
12057
12164
|
---
|
|
12058
12165
|
|
|
12059
12166
|
# useStore()
|
|
@@ -20521,7 +20628,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20521
20628
|
- [requireMetaURL()](ui/requireMetaURL.md): Read the current Meta context and derive URL helpers (path and params) from its url.
|
|
20522
20629
|
- [getTagClass()](ui/getTagClass.md): Build the combined className string for a <Tag> from its styling variants.
|
|
20523
20630
|
- [Message()](ui/Message.md): Status-coloured paragraph used for inline feedback messages.
|
|
20524
|
-
- [requireNavigation()](ui/requireNavigation.md): Read the current
|
|
20631
|
+
- [requireNavigation()](ui/requireNavigation.md): Read the current NavigationSequence from context, throwing if used outside <Navigation>.
|
|
20525
20632
|
- [getBlockClass()](ui/getBlockClass.md): Get the combined className string for a block from its styling variants.
|
|
20526
20633
|
- [getColorClass()](ui/getColorClass.md): CSS class that applies color tinting to an element.
|
|
20527
20634
|
- [getDurationClass()](ui/getDurationClass.md): Get the transition-duration class for a component from its duration variant prop.
|
|
@@ -20551,6 +20658,8 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20551
20658
|
- [focusFirstFocusable()](ui/focusFirstFocusable.md): Focus on the first focusable element inside an element.
|
|
20552
20659
|
- [loopFocus()](ui/loopFocus.md): Loop focus inside an element so it can't escape — refocus the first focusable child when focus moves out.
|
|
20553
20660
|
- [eventLoopFocus()](ui/eventLoopFocus.md): Loop focus inside an element in response to a blur event — a ready-made onBlur handler that traps focus.
|
|
20661
|
+
- [isKeyboardOpen()](ui/isKeyboardOpen.md): Is the on-screen keyboard open (or still closing)?
|
|
20662
|
+
- [waitForKeyboard()](ui/waitForKeyboard.md): Lower the on-screen keyboard, and wait until it is down.
|
|
20554
20663
|
- [joinMetaCSP()](ui/joinMetaCSP.md): Turn a deconstructed MetaCSP into a Content-Security-Policy string.
|
|
20555
20664
|
- [joinTitles()](ui/joinTitles.md): Join several page or site titles together with - , skipping empty values.
|
|
20556
20665
|
- [mergeMeta()](ui/mergeMeta.md): Merge a PossibleMeta onto an existing Meta, resolving URLs and assets in the process.
|
|
@@ -20580,7 +20689,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20580
20689
|
- [FormStore](ui/FormStore.md): Reactive store holding the current (possibly partial and invalid) value of a form, plus its field messages.
|
|
20581
20690
|
- [NoticesStore](ui/NoticesStore.md): Store holding the live list of NoticeStore notices currently shown.
|
|
20582
20691
|
- [NoticeStore](ui/NoticeStore.md): Store holding a single notice's content and status, owned by a NoticesStore.
|
|
20583
|
-
- [
|
|
20692
|
+
- [NavigationSequence](ui/NavigationSequence.md): Sequence of navigation events that drives browser history and keeps a stack of pages for each tab.
|
|
20584
20693
|
|
|
20585
20694
|
## Interfaces
|
|
20586
20695
|
|
|
@@ -20717,8 +20826,8 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20717
20826
|
- [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
|
|
20718
20827
|
- [BackButtonProps](ui/BackButtonProps.md): Props for <BackButton>: the href to go back to when the stack has no page before this one, plus the usual Button props except onClick.
|
|
20719
20828
|
- [NavigationProps](ui/NavigationProps.md): Props for <Navigation>: the initial Meta (url, root and stack), the stacks, and optional children.
|
|
20720
|
-
- [NavigationEntryState](ui/NavigationEntryState.md): State that
|
|
20721
|
-
- [
|
|
20829
|
+
- [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationSequence saves on each browser history entry.
|
|
20830
|
+
- [NavigationEvent](ui/NavigationEvent.md): One change of page, published by NavigationSequence.
|
|
20722
20831
|
- [RouteCacheProps](ui/RouteCacheProps.md): Props for <RouteCache>: the maxCached size and the content children to keep alive for each page in the stacks.
|
|
20723
20832
|
- [RouterProps](ui/RouterProps.md): Props for <Router> — the routes to match against plus an optional fallback.
|
|
20724
20833
|
- [StackButtonProps](ui/StackButtonProps.md): Props for <StackButton>: the stack it opens, plus the usual Button props except href and onClick.
|
|
@@ -20774,6 +20883,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20774
20883
|
- [TextFormatter](ui/TextFormatter.md): Formats a string for display in a text input.
|
|
20775
20884
|
- [Mapping](ui/Mapping.md): Dispatch table from a JSX.IntrinsicElements key to a renderer component.
|
|
20776
20885
|
- [NoticesPosition](ui/NoticesPosition.md): Place on the screen where <Notices> shows the list of notices: a corner, or the centre of the top or bottom edge.
|
|
20886
|
+
- [NavigationDirection](ui/NavigationDirection.md): Direction of a move in a NavigationEvent: "forward" or "back".
|
|
20777
20887
|
- [RouteProps](ui/RouteProps.md): Props for a component that works as a route in the router.
|
|
20778
20888
|
- [RouteComponent](ui/RouteComponent.md): React component usable as a route value — a function or class component accepting RouteProps.
|
|
20779
20889
|
- [Route](ui/Route.md): Valid route values:
|
|
@@ -20823,8 +20933,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20823
20933
|
- [EMPTY_LOADING](ui/EMPTY_LOADING.md): Loading spinner in an <Empty>, for a list or form that is still loading. The empty message replaces it in the same place.
|
|
20824
20934
|
- [LOADING_NOTICE](ui/LOADING_NOTICE.md): Shared loading <Notice> element showing the loading spinner.
|
|
20825
20935
|
- [NOTICES](ui/NOTICES.md): Global NoticesStore shown by <Notices>, accepting any of the default statuses.
|
|
20826
|
-
- [NavigationContext](ui/NavigationContext.md): React context holding the current
|
|
20827
|
-
- [NavigationPositionContext](ui/NavigationPositionContext.md): React context holding where the app is in its stacks, published by <Navigation> with each URL change.
|
|
20936
|
+
- [NavigationContext](ui/NavigationContext.md): React context holding the current NavigationSequence, provided by <Navigation>.
|
|
20828
20937
|
- [STATUSES](ui/STATUSES.md): Tuple of the status names selectable via the status variant prop.
|
|
20829
20938
|
- [TINT_CLASS](ui/TINT_CLASS.md): CSS class that (re)calculates the full ladder of tint shades from the current global tint colour.
|
|
20830
20939
|
- [FADE_TRANSITION_CLASS](ui/FADE_TRANSITION_CLASS.md): View transition class that fades content in and out.
|
|
@@ -33077,7 +33186,7 @@ close(): void
|
|
|
33077
33186
|
Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
|
|
33078
33187
|
- Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
|
|
33079
33188
|
- Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
|
|
33080
|
-
- When the meta `url` differs from the browser URL (a page that knows its canonical URL), calls `
|
|
33189
|
+
- When the meta `url` differs from the browser URL (a page that knows its canonical URL), calls `NavigationSequence.replace()` with it. It only does this for the page the browser history is on (the same `stack` and `ordinal`), so a page shown ahead of history, such as a swipe-back preview, leaves history alone. Outside `<Navigation>` it does not touch history.
|
|
33081
33190
|
|
|
33082
33191
|
Low-level emitter of hoistable head metadata from the current `Meta` context. It outputs `<title>`, `<meta>`, `<link>`, stylesheet, module, and script elements inline, and React 19 hoists each one into the document `<head>`. It also syncs `window.history` to the page URL.
|
|
33083
33192
|
|
|
@@ -33319,7 +33428,7 @@ The back button for a page header. It goes back to the page before this one in t
|
|
|
33319
33428
|
|
|
33320
33429
|
- 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.
|
|
33321
33430
|
- 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>`.
|
|
33322
|
-
- It is a plain link with `className="back"`. `<Navigation>` turns a click into `
|
|
33431
|
+
- It is a plain link with `className="back"`. `<Navigation>` turns a click into `NavigationSequence.back()`, so the page slides back. A middle-click opens the link in a new browser tab.
|
|
33323
33432
|
- Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
|
|
33324
33433
|
- It takes the usual `<Button>` props, except `onClick`.
|
|
33325
33434
|
- Without the browser Navigation API, and in a server render, it links to `href`.
|
|
@@ -33417,28 +33526,30 @@ Props for `<Navigation>`: the initial `Meta` (url, root and stack), the `stacks`
|
|
|
33417
33526
|
- Import: `import { Navigation } from "shelving/ui";`
|
|
33418
33527
|
|
|
33419
33528
|
Top-level navigation provider, with one stack of pages for each tab.
|
|
33420
|
-
- Owns a single `
|
|
33421
|
-
- Turns clicks on same-origin links into `
|
|
33422
|
-
-
|
|
33423
|
-
-
|
|
33529
|
+
- Owns a single `NavigationSequence` made from the surrounding `<Meta>` url and root.
|
|
33530
|
+
- Turns clicks on same-origin links into `NavigationSequence.forward()`, or `NavigationSequence.back()` for a link with `className="back"`, or `NavigationSequence.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.
|
|
33531
|
+
- Holds the page it shows in its own state, and publishes its `url`, `stack` and `ordinal` into `Meta`. Read the current page from `Meta`.
|
|
33532
|
+
- Before a move slides, it lowers the on-screen keyboard and waits until it is down (`waitForKeyboard()`), because a keyboard that closes during the slide resizes the page in the middle of it.
|
|
33533
|
+
- Takes each `NavigationEvent` with `useSequenceTransition()`. A move is set inside `startTransition()` with its `"forward"` or `"back"` type, so a `<Transition>` around the routes runs a view transition. A replace has no transition. An event for the page already shown is skipped.
|
|
33424
33534
|
- Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
|
|
33425
33535
|
|
|
33426
|
-
Exactly one `<Navigation>` per app. Nested routers share its
|
|
33536
|
+
Exactly one `<Navigation>` per app. Nested routers share its sequence.
|
|
33427
33537
|
|
|
33428
|
-
The top-level navigation provider for a client-side app. It owns one `
|
|
33538
|
+
The top-level navigation provider for a client-side app. It owns one `NavigationSequence`, turns link clicks into navigation, holds the page it shows in its own state, and publishes that page into `<Meta>`, so each `<Router>` re-renders when the page changes. Use exactly one `<Navigation>` per app. Nested routers all share its sequence.
|
|
33429
33539
|
|
|
33430
33540
|
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.
|
|
33431
33541
|
|
|
33432
33542
|
**Things to know:**
|
|
33433
33543
|
|
|
33434
|
-
- Same-origin link clicks become `
|
|
33435
|
-
- A link with `className="back"` calls `
|
|
33436
|
-
- A link with `className="replace"` calls `
|
|
33544
|
+
- Same-origin link clicks become `NavigationSequence.forward()`, so the page slides forward.
|
|
33545
|
+
- A link with `className="back"` calls `NavigationSequence.back()`, so the page slides back. `<BackButton>` sets this class for you.
|
|
33546
|
+
- A link with `className="replace"` calls `NavigationSequence.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.
|
|
33437
33547
|
- 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.
|
|
33438
|
-
- It
|
|
33439
|
-
- The browser back and forward buttons slide too. Inside a stack the direction comes from the
|
|
33548
|
+
- It takes each `NavigationEvent` with `useSequenceTransition()`. A move is set inside `startTransition()` with its `"forward"` or `"back"` transition type, so a `<Transition>` such as `<HorizontalTransition>` slides the page. A replace has no transition. An event for the page already shown is skipped.
|
|
33549
|
+
- The browser back and forward buttons slide too. Inside a stack the direction comes from the ordinal of the page. Across stacks it comes from tab order.
|
|
33440
33550
|
- 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.
|
|
33441
|
-
- It publishes `stack` (the root of the current stack) into `<Meta
|
|
33551
|
+
- It publishes `url`, `stack` (the root of the current stack) and `ordinal` (the page's place in its stack) into `<Meta>`, so any component can read the page on screen with `requireMeta()`. On a floating page (outside every stack) `stack` is `null`. With no `stacks`, every page floats.
|
|
33552
|
+
- When it starts listening it reads the current history entry, so a `replace()` sent before that (for example from a page's first effect) is not lost.
|
|
33442
33553
|
- 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`.
|
|
33443
33554
|
- `<Router>` works with no `<Navigation>` (server renders, static renders, tests). `<Navigation>` only makes the URL live on the client.
|
|
33444
33555
|
|
|
@@ -33484,7 +33595,7 @@ const TABS = (
|
|
|
33484
33595
|
<App root="https://example.com/">
|
|
33485
33596
|
<Navigation stacks={STACKS}>
|
|
33486
33597
|
<AppLayout nav={TABS}>
|
|
33487
|
-
<HorizontalTransition>
|
|
33598
|
+
<HorizontalTransition default="none">
|
|
33488
33599
|
<RouteCache>
|
|
33489
33600
|
<Scroll vertical cover>
|
|
33490
33601
|
<PageLoader>
|
|
@@ -33509,9 +33620,9 @@ const stack = STACKS.find(s => path === s || path.startsWith(`${s}/`));
|
|
|
33509
33620
|
<Navigation stacks={STACKS} stack={stack}>
|
|
33510
33621
|
```
|
|
33511
33622
|
|
|
33512
|
-
Put the transition **outside** `<RouteCache>`, around the whole cache. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
|
|
33623
|
+
Put the transition **outside** `<RouteCache>`, around the whole cache, with no `key`. A page change is an update of the transition, and it slides by type. Set `default="none"`, so a change with no type (a replace) does not animate. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`. The app also works with no `<RouteCache>`: put the transition around the `<Router>`.
|
|
33513
33624
|
|
|
33514
|
-
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 `
|
|
33625
|
+
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 `NavigationSequence`.
|
|
33515
33626
|
|
|
33516
33627
|
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.
|
|
33517
33628
|
|
|
@@ -33535,7 +33646,7 @@ Each link pushes a new page onto the current stack, wherever it points. So a lin
|
|
|
33535
33646
|
|
|
33536
33647
|
### Imperative navigation
|
|
33537
33648
|
|
|
33538
|
-
Read the
|
|
33649
|
+
Read the sequence from anywhere in the tree with `requireNavigation()`:
|
|
33539
33650
|
|
|
33540
33651
|
```tsx
|
|
33541
33652
|
import { requireNavigation } from "shelving/ui";
|
|
@@ -33546,7 +33657,7 @@ nav.back("/home"); // Go back to a page.
|
|
|
33546
33657
|
nav.replace("/login"); // Change the URL of the current page.
|
|
33547
33658
|
```
|
|
33548
33659
|
|
|
33549
|
-
See `
|
|
33660
|
+
See `NavigationSequence` for what each method does.
|
|
33550
33661
|
|
|
33551
33662
|
|
|
33552
33663
|
## Signatures
|
|
@@ -33577,12 +33688,12 @@ Navigation({ children, stacks = [], ...meta }: NavigationProps): ReactElement
|
|
|
33577
33688
|
- Kind: constant
|
|
33578
33689
|
- Import: `import { NavigationContext } from "shelving/ui";`
|
|
33579
33690
|
|
|
33580
|
-
React context holding the current `
|
|
33691
|
+
React context holding the current `NavigationSequence`, provided by `<Navigation>`.
|
|
33581
33692
|
|
|
33582
33693
|
## Examples
|
|
33583
33694
|
|
|
33584
33695
|
```ts
|
|
33585
|
-
<NavigationContext value={
|
|
33696
|
+
<NavigationContext value={nav}>…</NavigationContext>
|
|
33586
33697
|
```
|
|
33587
33698
|
|
|
33588
33699
|
|
|
@@ -33593,19 +33704,19 @@ React context holding the current `NavigationStore`, provided by `<Navigation>`.
|
|
|
33593
33704
|
- Kind: function
|
|
33594
33705
|
- Import: `import { requireNavigation } from "shelving/ui";`
|
|
33595
33706
|
|
|
33596
|
-
Read the current `
|
|
33707
|
+
Read the current `NavigationSequence` from context, throwing if used outside `<Navigation>`.
|
|
33597
33708
|
|
|
33598
33709
|
## Signatures
|
|
33599
33710
|
|
|
33600
33711
|
```ts
|
|
33601
|
-
requireNavigation():
|
|
33712
|
+
requireNavigation(): NavigationSequence
|
|
33602
33713
|
```
|
|
33603
33714
|
|
|
33604
33715
|
## Returns
|
|
33605
33716
|
|
|
33606
33717
|
| Type | Description |
|
|
33607
33718
|
| --- | --- |
|
|
33608
|
-
| `
|
|
33719
|
+
| `NavigationSequence` | The current `NavigationSequence`. |
|
|
33609
33720
|
|
|
33610
33721
|
## Throws
|
|
33611
33722
|
|
|
@@ -33614,18 +33725,6 @@ requireNavigation(): NavigationStore
|
|
|
33614
33725
|
| `unknown` | RequiredError If no `<Navigation>` provider is present above. |
|
|
33615
33726
|
|
|
33616
33727
|
|
|
33617
|
-
---
|
|
33618
|
-
|
|
33619
|
-
# NavigationPositionContext
|
|
33620
|
-
|
|
33621
|
-
- Kind: constant
|
|
33622
|
-
- Import: `import { NavigationPositionContext } from "shelving/ui";`
|
|
33623
|
-
|
|
33624
|
-
React context holding where the app is in its stacks, published by `<Navigation>` with each URL change.
|
|
33625
|
-
- `undefined` without the browser Navigation API, during a server render, or outside `<Navigation>`.
|
|
33626
|
-
- `<RouteCache>`, `<Router>` and `<BackButton>` read it, so they change in the same render as the URL.
|
|
33627
|
-
|
|
33628
|
-
|
|
33629
33728
|
---
|
|
33630
33729
|
|
|
33631
33730
|
# NavigationEntryState
|
|
@@ -33633,14 +33732,14 @@ React context holding where the app is in its stacks, published by `<Navigation>
|
|
|
33633
33732
|
- Kind: interface
|
|
33634
33733
|
- Import: `import { NavigationEntryState } from "shelving/ui";`
|
|
33635
33734
|
|
|
33636
|
-
State that `
|
|
33735
|
+
State that `NavigationSequence` saves on each browser history entry.
|
|
33637
33736
|
|
|
33638
33737
|
## Signatures
|
|
33639
33738
|
|
|
33640
33739
|
```ts
|
|
33641
33740
|
{
|
|
33642
33741
|
readonly stack: AbsolutePath | null;
|
|
33643
|
-
readonly
|
|
33742
|
+
readonly ordinal: number;
|
|
33644
33743
|
}
|
|
33645
33744
|
```
|
|
33646
33745
|
|
|
@@ -33649,26 +33748,44 @@ State that `NavigationStore` saves on each browser history entry.
|
|
|
33649
33748
|
| Property | Type | Description |
|
|
33650
33749
|
| --- | --- | --- |
|
|
33651
33750
|
| `stack` | `AbsolutePath \| null` | Root path of the stack this page is in, or `null` for a floating page. Read only. |
|
|
33652
|
-
| `
|
|
33751
|
+
| `ordinal` | `number` | Position of this page in its stack, where `0` is the root. Read only. |
|
|
33653
33752
|
|
|
33654
33753
|
|
|
33655
33754
|
---
|
|
33656
33755
|
|
|
33657
|
-
#
|
|
33756
|
+
# NavigationDirection
|
|
33757
|
+
|
|
33758
|
+
- Kind: type
|
|
33759
|
+
- Import: `import { NavigationDirection } from "shelving/ui";`
|
|
33760
|
+
|
|
33761
|
+
Direction of a move in a `NavigationEvent`: `"forward"` or `"back"`.
|
|
33762
|
+
|
|
33763
|
+
## Signatures
|
|
33764
|
+
|
|
33765
|
+
```ts
|
|
33766
|
+
"forward" | "back"
|
|
33767
|
+
```
|
|
33768
|
+
|
|
33769
|
+
|
|
33770
|
+
---
|
|
33771
|
+
|
|
33772
|
+
# NavigationEvent
|
|
33658
33773
|
|
|
33659
33774
|
- Kind: interface
|
|
33660
|
-
- Import: `import {
|
|
33661
|
-
- Extends: `NavigationEntryState`
|
|
33775
|
+
- Import: `import { NavigationEvent } from "shelving/ui";`
|
|
33662
33776
|
|
|
33663
|
-
|
|
33664
|
-
-
|
|
33777
|
+
One change of page, published by `NavigationSequence`.
|
|
33778
|
+
- A move (a link, a back button, the browser back and forward buttons) has a `direction`, so `<Navigation>` shows it inside a view transition of that type.
|
|
33779
|
+
- A replace has no `direction`, so it shows at once with no transition.
|
|
33665
33780
|
|
|
33666
33781
|
## Signatures
|
|
33667
33782
|
|
|
33668
33783
|
```ts
|
|
33669
33784
|
{
|
|
33670
|
-
readonly
|
|
33671
|
-
readonly
|
|
33785
|
+
readonly url: ImmutableURL;
|
|
33786
|
+
readonly stack: AbsolutePath | null;
|
|
33787
|
+
readonly ordinal: number | undefined;
|
|
33788
|
+
readonly direction?: NavigationDirection | undefined;
|
|
33672
33789
|
}
|
|
33673
33790
|
```
|
|
33674
33791
|
|
|
@@ -33676,50 +33793,58 @@ Where the app is now in its stacks: the current stack and depth, the top depth o
|
|
|
33676
33793
|
|
|
33677
33794
|
| Property | Type | Description |
|
|
33678
33795
|
| --- | --- | --- |
|
|
33679
|
-
| `
|
|
33680
|
-
| `
|
|
33796
|
+
| `url` | `ImmutableURL` | URL of the page. Read only. |
|
|
33797
|
+
| `stack` | `AbsolutePath \| null` | Root path of the stack the page is in, or `null` for a floating page. Read only. |
|
|
33798
|
+
| `ordinal` | `number \| undefined` | Position of the page in its stack, where `0` is the root, or `undefined` without the Navigation API. Read only. |
|
|
33799
|
+
| `direction` | `NavigationDirection \| undefined` | Direction of the move, or `undefined` for a replace or a change with no slide. Read only. Optional. |
|
|
33681
33800
|
|
|
33682
33801
|
|
|
33683
33802
|
---
|
|
33684
33803
|
|
|
33685
|
-
#
|
|
33804
|
+
# NavigationSequence
|
|
33686
33805
|
|
|
33687
33806
|
- Kind: class
|
|
33688
|
-
- Import: `import {
|
|
33689
|
-
- Extends: `
|
|
33807
|
+
- Import: `import { NavigationSequence } from "shelving/ui";`
|
|
33808
|
+
- Extends: `DeferredSequence<NavigationEvent>`
|
|
33690
33809
|
|
|
33691
|
-
|
|
33810
|
+
Sequence of navigation events that drives browser history and keeps a stack of pages for each tab.
|
|
33692
33811
|
|
|
33693
|
-
-
|
|
33812
|
+
- It is not a store: it holds no "current page" for the UI. Each change of page (a move, a replace, or the browser back and forward buttons) publishes one `NavigationEvent`, and `<Navigation>` keeps the page it shows in its own state.
|
|
33813
|
+
- `url`, `stack` and `ordinal` say where the browser history is now. The page on screen can differ for a moment, for example during a swipe-back preview. To read the page on screen, read `Meta`.
|
|
33814
|
+
- `publish()` sends an event by hand, for example to show the page below during a swipe-back.
|
|
33694
33815
|
- 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.
|
|
33695
|
-
- `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.
|
|
33696
33816
|
- A page outside the listed stacks is floating: its stack is `null`. The floating stack has no root page and no tab.
|
|
33697
|
-
- In a listed stack,
|
|
33817
|
+
- In a listed stack, ordinal `0` is always the stack's root path.
|
|
33698
33818
|
- 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.
|
|
33699
33819
|
- Owned by `<Navigation>`. Read it with `requireNavigation()`.
|
|
33700
33820
|
|
|
33701
|
-
The
|
|
33821
|
+
The sequence of navigation events that drives browser history and keeps one stack of pages for each tab. It is not a store: it holds no "current page" for the UI. Each change of page publishes one `NavigationEvent`, and `<Navigation>` keeps the page it shows in its own state. `<Navigation>` owns it. Read it with `requireNavigation()`, and do not make your own.
|
|
33702
33822
|
|
|
33703
33823
|
**Things to know:**
|
|
33704
33824
|
|
|
33705
|
-
-
|
|
33825
|
+
- Each change of page (a link, a back button, a replace, or the browser back and forward buttons) publishes one `NavigationEvent`: `{ url, stack, ordinal, direction }`.
|
|
33826
|
+
- A move has a `direction` (`"forward"` or `"back"`), so `<Navigation>` shows it in a view transition of that type. A replace has no `direction`, so it shows at once.
|
|
33827
|
+
- To read the page on screen, read `Meta` (`requireMeta()` or `requireMetaURL()`), not the sequence. The two can differ for a moment, for example during a swipe-back.
|
|
33828
|
+
- `NavigationSequence.url`, `NavigationSequence.stack` and `NavigationSequence.path` say where the browser history is now. `NavigationSequence.current()` returns the same as an event with no direction.
|
|
33829
|
+
- `NavigationSequence.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.
|
|
33706
33830
|
- A page that is not in a listed stack is **floating**: its stack is `null`. See [Floating pages](#floating-pages).
|
|
33707
|
-
- In a listed stack,
|
|
33708
|
-
- `
|
|
33709
|
-
- `
|
|
33710
|
-
-
|
|
33711
|
-
-
|
|
33712
|
-
-
|
|
33713
|
-
- Without the browser Navigation API there is no stack history: `stack` stays the starting stack, `history()` returns `[]`, `position` is `undefined`, and every `stack` argument is ignored. `forward()` and `back()` push a history entry, and `replace()` replaces it.
|
|
33831
|
+
- In a listed stack, ordinal `0` is always the stack's root path. A deeper page always has the root below it.
|
|
33832
|
+
- `NavigationSequence.history()` returns the pages in the current stack (or a given stack), root first.
|
|
33833
|
+
- `NavigationSequence.publish()` sends an event by hand, for example to show the page below during a swipe-back. It returns a promise that resolves when `<Navigation>` has committed the event.
|
|
33834
|
+
- Events sent in the same microtask merge: only the last one is shown.
|
|
33835
|
+
- All URLs resolve against the sequence's `base`. Each method also takes a full same-origin URL.
|
|
33836
|
+
- Without the browser Navigation API there is no stack history: `stack` stays the starting stack, `history()` returns `[]`, `ordinal` is `undefined`, and every `stack` argument is ignored. `forward()` and `back()` push a history entry, and `replace()` replaces it.
|
|
33714
33837
|
|
|
33715
33838
|
## Methods
|
|
33716
33839
|
|
|
33717
|
-
| Method | What it does
|
|
33718
|
-
| ----------------------- |
|
|
33719
|
-
| `forward(href, stack?)` | Opens `href` as a new page on top of the stack. If `href` is the top page of another stack, it switches to that stack (a tab switch). If `href` is the current URL, it is a replace.
|
|
33720
|
-
| `back(href, stack?)` | Goes back to `href`. If `href` is in the stack, the stack goes back to it, and the pages above it leave the stack. If `href` is the root of the stack, the stack goes to its root. Otherwise `href` takes the place of the top page of the stack. | Back |
|
|
33721
|
-
| `replace(href, stack?)` | Changes the URL of the current page. The stack, the
|
|
33722
|
-
| `history(stack?)` | Returns the pages in `stack`, root first.
|
|
33840
|
+
| Method | What it does | Slide |
|
|
33841
|
+
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
|
|
33842
|
+
| `forward(href, stack?)` | Opens `href` as a new page on top of the stack. If `href` is the top page of another stack, it switches to that stack (a tab switch). If `href` is the current URL, it is a replace. | Forward. Across stacks, by tab order. |
|
|
33843
|
+
| `back(href, stack?)` | Goes back to `href`. If `href` is in the stack, the stack goes back to it, and the pages above it leave the stack. If `href` is the root of the stack, the stack goes to its root. Otherwise `href` takes the place of the top page of the stack. If the browser refuses the Navigation API back, it uses `history.back()`. | Back |
|
|
33844
|
+
| `replace(href, stack?)` | Changes the URL of the current page. The stack, the ordinal 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 |
|
|
33845
|
+
| `history(stack?)` | Returns the pages in `stack`, root first. | — |
|
|
33846
|
+
| `current()` | Returns where the browser history is now, as an event with no direction. | — |
|
|
33847
|
+
| `publish(event)` | Sends an event by hand. Resolves when `<Navigation>` has committed it. | The event's `direction` |
|
|
33723
33848
|
|
|
33724
33849
|
`stack` defaults to the current stack. Pass `null` to name the floating stack.
|
|
33725
33850
|
|
|
@@ -33736,7 +33861,7 @@ A page changes stack only when you say so: with a `<StackButton>`, or with a `st
|
|
|
33736
33861
|
## Opening the app
|
|
33737
33862
|
|
|
33738
33863
|
- 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.
|
|
33739
|
-
- A deep page the app opens at, in a listed stack, starts at
|
|
33864
|
+
- A deep page the app opens at, in a listed stack, starts at ordinal 1, so the stack root is its parent. A `<StackButton>` or a back gesture then goes to the root. A stack root starts at ordinal 0.
|
|
33740
33865
|
- A `stack` that is not in `stacks` is ignored: the page floats.
|
|
33741
33866
|
|
|
33742
33867
|
For example, a login page sends the user home after they log in, and names the Home stack:
|
|
@@ -33748,23 +33873,23 @@ nav.replace("/home", "/home");
|
|
|
33748
33873
|
|
|
33749
33874
|
## How stacks work
|
|
33750
33875
|
|
|
33751
|
-
The
|
|
33876
|
+
The sequence saves a small state on each browser history entry: the `stack` the page is in, and its `ordinal` in that stack (`0` is the root). See `NavigationEntryState`. To read a stack, the sequence walks back through the browser history from the current entry. It takes the newest entry in that stack, then the newest earlier entry with a lower ordinal, and so on down to ordinal `0`.
|
|
33752
33877
|
|
|
33753
|
-
Why
|
|
33878
|
+
Why ordinal? A browser history entry cannot be changed or removed. So when you go back in one stack while another stack's pages are after it in the history, the sequence cannot go back in the browser. It pushes a new entry for the page you went back to, at that page's ordinal. The pages that were above it now have a higher ordinal than the newest entry, so they are no longer in the stack.
|
|
33754
33879
|
|
|
33755
33880
|
For example, with tabs `/home` and `/profile`:
|
|
33756
33881
|
|
|
33757
|
-
| Step | New history entry
|
|
33758
|
-
| ------------------- |
|
|
33759
|
-
| Start at `/home` | `/home` (
|
|
33760
|
-
| Open a post | `/home/post/1` (
|
|
33761
|
-
| Tap the Profile tab | `/profile` (
|
|
33762
|
-
| Tap the Home tab | `/home/post/1` (
|
|
33763
|
-
| Tap the back button | `/home` (
|
|
33882
|
+
| Step | New history entry | Home stack | Profile stack |
|
|
33883
|
+
| ------------------- | -------------------------- | ----------------------- | ------------- |
|
|
33884
|
+
| Start at `/home` | `/home` (ordinal 0) | `/home` | — |
|
|
33885
|
+
| Open a post | `/home/post/1` (ordinal 1) | `/home`, `/home/post/1` | — |
|
|
33886
|
+
| Tap the Profile tab | `/profile` (ordinal 0) | `/home`, `/home/post/1` | `/profile` |
|
|
33887
|
+
| Tap the Home tab | `/home/post/1` (ordinal 1) | `/home`, `/home/post/1` | `/profile` |
|
|
33888
|
+
| Tap the back button | `/home` (ordinal 0) | `/home` | `/profile` |
|
|
33764
33889
|
|
|
33765
33890
|
When the page you go back to is the entry just before the current one, `back()` goes back in the browser history and pushes nothing.
|
|
33766
33891
|
|
|
33767
|
-
The browser back and forward buttons walk the history entries one at a time, as usual. Each entry knows its stack and
|
|
33892
|
+
The browser back and forward buttons walk the history entries one at a time, as usual. Each entry knows its stack and ordinal, so the stacks are always right and the slide goes the right way.
|
|
33768
33893
|
|
|
33769
33894
|
## Usage
|
|
33770
33895
|
|
|
@@ -33777,19 +33902,33 @@ function LogoutButton() {
|
|
|
33777
33902
|
}
|
|
33778
33903
|
```
|
|
33779
33904
|
|
|
33780
|
-
Read the current stack in a component
|
|
33905
|
+
Read the current stack in a component from `Meta`:
|
|
33781
33906
|
|
|
33782
33907
|
```tsx
|
|
33783
|
-
import {
|
|
33784
|
-
import { requireNavigation } from "shelving/ui";
|
|
33908
|
+
import { requireMeta } from "shelving/ui";
|
|
33785
33909
|
|
|
33786
33910
|
function TabTitle() {
|
|
33787
|
-
const
|
|
33788
|
-
const stack = useStore(nav.stack).value;
|
|
33911
|
+
const { stack } = requireMeta();
|
|
33789
33912
|
return <h1>{stack === "/profile" ? "Profile" : "Home"}</h1>;
|
|
33790
33913
|
}
|
|
33791
33914
|
```
|
|
33792
33915
|
|
|
33916
|
+
Show the page below during a swipe-back. React runs the back transition, and the swipe scrubs it:
|
|
33917
|
+
|
|
33918
|
+
```tsx
|
|
33919
|
+
const nav = requireNavigation();
|
|
33920
|
+
const { stack = null, ordinal } = requireMetaURL();
|
|
33921
|
+
const parent = ordinal ? nav.history(stack)[ordinal - 1] : undefined;
|
|
33922
|
+
if (parent) {
|
|
33923
|
+
// Start the swipe: show the page below with the back transition.
|
|
33924
|
+
await nav.publish({ url: requireURL(parent, nav.base), stack, ordinal: ordinal - 1, direction: "back" });
|
|
33925
|
+
// Release: go back for real. It publishes the same page, so it is skipped.
|
|
33926
|
+
nav.back(parent);
|
|
33927
|
+
// Or cancel: show the old page again, with no transition.
|
|
33928
|
+
// await nav.publish({ ...from, direction: undefined });
|
|
33929
|
+
}
|
|
33930
|
+
```
|
|
33931
|
+
|
|
33793
33932
|
List the pages in a stack (for example, for breadcrumbs):
|
|
33794
33933
|
|
|
33795
33934
|
```tsx
|
|
@@ -33797,13 +33936,13 @@ const nav = requireNavigation();
|
|
|
33797
33936
|
nav.history("/home"); // ["/home", "/home/post/1", "/home/post/1/comments"]
|
|
33798
33937
|
```
|
|
33799
33938
|
|
|
33800
|
-
Make a
|
|
33939
|
+
Make a sequence by hand only in tests:
|
|
33801
33940
|
|
|
33802
33941
|
```tsx
|
|
33803
|
-
import {
|
|
33942
|
+
import { NavigationSequence } from "shelving/ui";
|
|
33804
33943
|
|
|
33805
33944
|
// URL, root, starting stack, then the stacks in tab order.
|
|
33806
|
-
const nav = new
|
|
33945
|
+
const nav = new NavigationSequence("https://example.com/home", "https://example.com/", "/home", "/home", "/profile");
|
|
33807
33946
|
nav.forward("/home/post/1");
|
|
33808
33947
|
```
|
|
33809
33948
|
|
|
@@ -33811,7 +33950,7 @@ nav.forward("/home/post/1");
|
|
|
33811
33950
|
## Signatures
|
|
33812
33951
|
|
|
33813
33952
|
```ts
|
|
33814
|
-
new
|
|
33953
|
+
new NavigationSequence(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL, stack: AbsolutePath | null = null, ...stacks: AbsolutePath[])
|
|
33815
33954
|
```
|
|
33816
33955
|
|
|
33817
33956
|
## Parameters
|
|
@@ -33827,36 +33966,91 @@ new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : win
|
|
|
33827
33966
|
|
|
33828
33967
|
| Type | Description |
|
|
33829
33968
|
| --- | --- |
|
|
33830
|
-
| `
|
|
33969
|
+
| `NavigationSequence` | |
|
|
33831
33970
|
|
|
33832
33971
|
## Properties
|
|
33833
33972
|
|
|
33834
33973
|
| Property | Type | Description |
|
|
33835
33974
|
| --- | --- | --- |
|
|
33836
33975
|
| `stacks` | `readonly AbsolutePath[]` | Root path of each stack, in tab order. With none, every page floats. Read only. |
|
|
33837
|
-
| `
|
|
33838
|
-
| `
|
|
33976
|
+
| `base` | `ImmutableURL \| undefined` | Base URL of the app, used to resolve relative URLs and to work out paths. Read only. |
|
|
33977
|
+
| `url` | `ImmutableURL` | URL the browser history is on now. Read only. |
|
|
33978
|
+
| `stack` | `AbsolutePath \| null` | Root path of the stack the browser history is on now, or `null` for a floating page. Read only. |
|
|
33839
33979
|
| `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. |
|
|
33840
|
-
| `position` | `NavigationPosition \| undefined` | Where the app is now: the current stack and depth, and the top depth of each stack. Read only. |
|
|
33841
33980
|
|
|
33842
33981
|
## Methods
|
|
33843
33982
|
|
|
33844
|
-
- [
|
|
33845
|
-
- [
|
|
33846
|
-
- [
|
|
33847
|
-
- [
|
|
33848
|
-
- [
|
|
33983
|
+
- [NavigationSequence.current()](ui/NavigationSequence/current.md): Where the browser history is now, as an event with no direction.
|
|
33984
|
+
- [NavigationSequence.publish()](ui/NavigationSequence/publish.md): Publish an event by hand, without changing history.
|
|
33985
|
+
- [NavigationSequence.committed()](ui/NavigationSequence/committed.md): Tell waiting publish() calls that <Navigation> has committed a page.
|
|
33986
|
+
- [NavigationSequence.listen()](ui/NavigationSequence/listen.md): Start listening to the browser (back, forward and swipe).
|
|
33987
|
+
- [NavigationSequence.history()](ui/NavigationSequence/history.md): Get the pages in a stack, root first, or every page in every stack.
|
|
33988
|
+
- [NavigationSequence.forward()](ui/NavigationSequence/forward.md): Go forward to a URL, as a link does.
|
|
33989
|
+
- [NavigationSequence.back()](ui/NavigationSequence/back.md): Go back to a URL, as a back button does.
|
|
33990
|
+
- [NavigationSequence.replace()](ui/NavigationSequence/replace.md): Replace the current URL, with no transition.
|
|
33991
|
+
|
|
33992
|
+
|
|
33993
|
+
---
|
|
33994
|
+
|
|
33995
|
+
# NavigationSequence.current()
|
|
33996
|
+
|
|
33997
|
+
- Kind: method
|
|
33998
|
+
- Member of: `NavigationSequence`
|
|
33999
|
+
|
|
34000
|
+
Where the browser history is now, as an event with no direction.
|
|
34001
|
+
- `<Navigation>` reads it for its first render, and again when it starts listening, to catch up on changes it missed.
|
|
34002
|
+
|
|
34003
|
+
## Signatures
|
|
34004
|
+
|
|
34005
|
+
```ts
|
|
34006
|
+
current(): NavigationEvent
|
|
34007
|
+
```
|
|
33849
34008
|
|
|
33850
34009
|
|
|
33851
34010
|
---
|
|
33852
34011
|
|
|
33853
|
-
#
|
|
34012
|
+
# NavigationSequence.publish()
|
|
33854
34013
|
|
|
33855
34014
|
- Kind: method
|
|
33856
|
-
- Member of: `
|
|
34015
|
+
- Member of: `NavigationSequence`
|
|
34016
|
+
|
|
34017
|
+
Publish an event by hand, without changing history.
|
|
34018
|
+
- For example, a swipe-back publishes the page below with `direction: "back"`, so React runs its back transition, and the swipe scrubs it.
|
|
34019
|
+
- Then the real `back()` publishes the same page again, which `<Navigation>` skips, or the swipe publishes the current page again to cancel.
|
|
34020
|
+
|
|
34021
|
+
## Signatures
|
|
34022
|
+
|
|
34023
|
+
```ts
|
|
34024
|
+
publish(event: NavigationEvent): Promise<void>
|
|
34025
|
+
```
|
|
34026
|
+
|
|
34027
|
+
|
|
34028
|
+
---
|
|
34029
|
+
|
|
34030
|
+
# NavigationSequence.committed()
|
|
34031
|
+
|
|
34032
|
+
- Kind: method
|
|
34033
|
+
- Member of: `NavigationSequence`
|
|
34034
|
+
|
|
34035
|
+
Tell waiting `publish()` calls that `<Navigation>` has committed a page.
|
|
34036
|
+
- `<Navigation>` calls it after each commit.
|
|
34037
|
+
|
|
34038
|
+
## Signatures
|
|
34039
|
+
|
|
34040
|
+
```ts
|
|
34041
|
+
committed(): void
|
|
34042
|
+
```
|
|
34043
|
+
|
|
34044
|
+
|
|
34045
|
+
---
|
|
34046
|
+
|
|
34047
|
+
# NavigationSequence.listen()
|
|
34048
|
+
|
|
34049
|
+
- Kind: method
|
|
34050
|
+
- Member of: `NavigationSequence`
|
|
33857
34051
|
|
|
33858
34052
|
Start listening to the browser (back, forward and swipe).
|
|
33859
|
-
- Saves the current stack and
|
|
34053
|
+
- Saves the current stack and ordinal on the current history entry, if it has none.
|
|
33860
34054
|
- `<Navigation>` calls it once, when it mounts.
|
|
33861
34055
|
|
|
33862
34056
|
## Signatures
|
|
@@ -33868,10 +34062,10 @@ listen(): () => void
|
|
|
33868
34062
|
|
|
33869
34063
|
---
|
|
33870
34064
|
|
|
33871
|
-
#
|
|
34065
|
+
# NavigationSequence.history()
|
|
33872
34066
|
|
|
33873
34067
|
- Kind: method
|
|
33874
|
-
- Member of: `
|
|
34068
|
+
- Member of: `NavigationSequence`
|
|
33875
34069
|
|
|
33876
34070
|
Get the pages in a stack, root first, or every page in every stack.
|
|
33877
34071
|
- Read from the browser history entries up to the current one.
|
|
@@ -33882,19 +34076,19 @@ Get the pages in a stack, root first, or every page in every stack.
|
|
|
33882
34076
|
## Signatures
|
|
33883
34077
|
|
|
33884
34078
|
```ts
|
|
33885
|
-
history(stack: AbsolutePath | null = this.
|
|
34079
|
+
history(stack: AbsolutePath | null = this._stack): AbsolutePath[]
|
|
33886
34080
|
```
|
|
33887
34081
|
|
|
33888
34082
|
|
|
33889
34083
|
---
|
|
33890
34084
|
|
|
33891
|
-
#
|
|
34085
|
+
# NavigationSequence.forward()
|
|
33892
34086
|
|
|
33893
34087
|
- Kind: method
|
|
33894
|
-
- Member of: `
|
|
34088
|
+
- Member of: `NavigationSequence`
|
|
33895
34089
|
|
|
33896
34090
|
Go forward to a URL, as a link does.
|
|
33897
|
-
- The URL is the top page of `stack`: switch to that stack, at the same
|
|
34091
|
+
- The URL is the top page of `stack`: switch to that stack, at the same ordinal. This is a tab switch.
|
|
33898
34092
|
- Else push the URL onto `stack`, one level deeper than its top page.
|
|
33899
34093
|
- The URL you are already on: replace it instead.
|
|
33900
34094
|
- A change of stack slides by tab order. Else it slides forward.
|
|
@@ -33902,46 +34096,47 @@ Go forward to a URL, as a link does.
|
|
|
33902
34096
|
## Signatures
|
|
33903
34097
|
|
|
33904
34098
|
```ts
|
|
33905
|
-
forward(possible: PossibleURL, stack: AbsolutePath | null = this.
|
|
34099
|
+
forward(possible: PossibleURL, stack: AbsolutePath | null = this._stack): void
|
|
33906
34100
|
```
|
|
33907
34101
|
|
|
33908
34102
|
|
|
33909
34103
|
---
|
|
33910
34104
|
|
|
33911
|
-
#
|
|
34105
|
+
# NavigationSequence.back()
|
|
33912
34106
|
|
|
33913
34107
|
- Kind: method
|
|
33914
|
-
- Member of: `
|
|
34108
|
+
- Member of: `NavigationSequence`
|
|
33915
34109
|
|
|
33916
34110
|
Go back to a URL, as a back button does.
|
|
33917
|
-
- 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
|
|
33918
|
-
- The URL is the root of `stack`: push it at
|
|
34111
|
+
- The URL is an earlier page in `stack`: go back to it. When it is the entry just before the current one, this goes back in the browser history. Else it pushes the URL again at that page's ordinal.
|
|
34112
|
+
- The URL is the root of `stack`: push it at ordinal 0.
|
|
33919
34113
|
- Else push the URL in place of the top page of `stack`.
|
|
33920
34114
|
- It works when the app was opened at the current page, so a back button always has somewhere to go.
|
|
34115
|
+
- If the browser refuses to go back with the Navigation API, it uses `history.back()`.
|
|
33921
34116
|
|
|
33922
34117
|
## Signatures
|
|
33923
34118
|
|
|
33924
34119
|
```ts
|
|
33925
|
-
back(possible: PossibleURL, stack: AbsolutePath | null = this.
|
|
34120
|
+
back(possible: PossibleURL, stack: AbsolutePath | null = this._stack): void
|
|
33926
34121
|
```
|
|
33927
34122
|
|
|
33928
34123
|
|
|
33929
34124
|
---
|
|
33930
34125
|
|
|
33931
|
-
#
|
|
34126
|
+
# NavigationSequence.replace()
|
|
33932
34127
|
|
|
33933
34128
|
- Kind: method
|
|
33934
|
-
- Member of: `
|
|
34129
|
+
- Member of: `NavigationSequence`
|
|
33935
34130
|
|
|
33936
34131
|
Replace the current URL, with no transition.
|
|
33937
|
-
- The page stays in the same stack, at the same
|
|
34132
|
+
- The page stays in the same stack, at the same ordinal, so a cached page stays mounted.
|
|
33938
34133
|
- Use it for a page that knows its canonical URL, or for in-page tabs.
|
|
33939
34134
|
- 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")`.
|
|
33940
34135
|
|
|
33941
34136
|
## Signatures
|
|
33942
34137
|
|
|
33943
34138
|
```ts
|
|
33944
|
-
replace(possible: PossibleURL, stack: AbsolutePath | null = this.
|
|
34139
|
+
replace(possible: PossibleURL, stack: AbsolutePath | null = this._stack): void
|
|
33945
34140
|
```
|
|
33946
34141
|
|
|
33947
34142
|
|
|
@@ -33967,7 +34162,7 @@ Props for `<RouteCache>`: the `maxCached` size and the content `children` to kee
|
|
|
33967
34162
|
|
|
33968
34163
|
| Property | Type | Description |
|
|
33969
34164
|
| --- | --- | --- |
|
|
33970
|
-
| `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
|
|
34165
|
+
| `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 last page you saw in 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. - Keep it at `2` or more, so a swipe-back can show the page below and still keep the page you are leaving. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
|
|
33971
34166
|
| `children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
|
|
33972
34167
|
|
|
33973
34168
|
|
|
@@ -33981,14 +34176,14 @@ Props for `<RouteCache>`: the `maxCached` size and the content `children` to kee
|
|
|
33981
34176
|
Keep-alive page cache for the pages in the navigation stacks. Put it in a layout's content slot, around a `<Scroll vertical cover>` box.
|
|
33982
34177
|
|
|
33983
34178
|
- Put a page transition around it, and a `<Scroll vertical cover>` inside it, so each kept page scrolls in its own box.
|
|
33984
|
-
- Keeps each page
|
|
33985
|
-
- Each page is keyed by
|
|
33986
|
-
-
|
|
33987
|
-
- The root page and the
|
|
34179
|
+
- Keeps each page 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.
|
|
34180
|
+
- Each page is keyed by the `stack` and `ordinal` in `Meta`, not by its URL. So `NavigationSequence.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.
|
|
34181
|
+
- It knows nothing about history. It only drops pages when it has more than `maxCached`: first the pages deeper than the current page in its stack (pages you went back from), then the least recently used. So after a back, a forward shows the page as you left it, and a cancelled swipe-back still has the page it started from.
|
|
34182
|
+
- The root page and the last page you saw in each listed stack are never dropped. Floating pages (stack `null`) get no such protection.
|
|
33988
34183
|
- 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.
|
|
33989
|
-
- Each kept page is frozen under its own `<MetaContext
|
|
34184
|
+
- 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.
|
|
33990
34185
|
- `<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.
|
|
33991
|
-
-
|
|
34186
|
+
- With no `ordinal` in `Meta` (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
|
|
33992
34187
|
|
|
33993
34188
|
A keep-alive cache for the pages in the navigation stacks. Put it in a layout's content slot, around a `<Scroll vertical cover>` box. 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.
|
|
33994
34189
|
|
|
@@ -33996,21 +34191,22 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
|
|
|
33996
34191
|
|
|
33997
34192
|
**Things to know:**
|
|
33998
34193
|
|
|
33999
|
-
- Each page is keyed by
|
|
34000
|
-
-
|
|
34001
|
-
-
|
|
34002
|
-
- The root page and the
|
|
34194
|
+
- Each page is keyed by the `stack` and `ordinal` in `Meta`, not by its URL. See `NavigationSequence` for how stacks work.
|
|
34195
|
+
- It knows nothing about history. It drops pages only when it has more than `maxCached`: first the pages deeper than the current page in its stack (pages you went back from), then the least recently used.
|
|
34196
|
+
- So after a back, the forward button shows the page as you left it, while the cache has room.
|
|
34197
|
+
- The current page, the root page of each listed stack, and the last page you saw in each listed stack are never dropped. So each tab always shows the page you left, and always has its root below. Floating pages get no such protection.
|
|
34198
|
+
- Keep `maxCached` at `2` or more, so a swipe-back can show the page below and still keep the page you are leaving.
|
|
34003
34199
|
- 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.
|
|
34004
|
-
- `
|
|
34200
|
+
- `NavigationSequence.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}>`.
|
|
34005
34201
|
- The same URL open in two stacks is two separate pages.
|
|
34006
34202
|
- 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).
|
|
34007
|
-
- Each kept page is frozen under its own `<Meta
|
|
34203
|
+
- Each kept page is frozen under its own `<Meta>`, so a hidden page never re-renders for another page's URL.
|
|
34008
34204
|
- `<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.
|
|
34009
34205
|
- **Nesting:** layout, then transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. See the usage below.
|
|
34010
34206
|
- 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.
|
|
34011
34207
|
- Put a page `<Transition>` **around** the `<RouteCache>`, not inside it. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
|
|
34012
34208
|
- Keep the layout **outside** the cache. Chrome in the layout (a sidebar, a tab bar) then has one copy, keeps its own state, and plays its own CSS transitions. Chrome inside the cache gets one copy per kept page.
|
|
34013
|
-
-
|
|
34209
|
+
- With no `ordinal` in `Meta` (no browser Navigation API, or a server render), or with `maxCached={0}`, there is no cache: the current page renders directly and unmounts when you leave it.
|
|
34014
34210
|
|
|
34015
34211
|
## Usage
|
|
34016
34212
|
|
|
@@ -34018,7 +34214,7 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
|
|
|
34018
34214
|
import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
|
|
34019
34215
|
|
|
34020
34216
|
<AppLayout nav={<StackBar />}>
|
|
34021
|
-
<HorizontalTransition>
|
|
34217
|
+
<HorizontalTransition default="none">
|
|
34022
34218
|
<RouteCache>
|
|
34023
34219
|
<Scroll vertical cover>
|
|
34024
34220
|
<PageLoader>
|
|
@@ -34077,7 +34273,7 @@ RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode
|
|
|
34077
34273
|
| Param | Type | Description |
|
|
34078
34274
|
| --- | --- | --- |
|
|
34079
34275
|
| `props` | `RouteCacheProps` | |
|
|
34080
|
-
| `.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
|
|
34276
|
+
| `.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 last page you saw in 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. - Keep it at `2` or more, so a swipe-back can show the page below and still keep the page you are leaving. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
|
|
34081
34277
|
| `.children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
|
|
34082
34278
|
|
|
34083
34279
|
## Returns
|
|
@@ -34126,7 +34322,7 @@ Match the current URL against `routes` and render the matched element.
|
|
|
34126
34322
|
- When `base` is set, the effective path is the URL after stripping the base prefix.
|
|
34127
34323
|
- Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
|
|
34128
34324
|
- 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.
|
|
34129
|
-
- Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `
|
|
34325
|
+
- Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationSequence.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
|
|
34130
34326
|
- Elsewhere, each path is a new page, so a component route remounts when the path changes.
|
|
34131
34327
|
- Returns `null` when there's no URL in context or the URL is outside the base.
|
|
34132
34328
|
|
|
@@ -34138,7 +34334,7 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
|
|
|
34138
34334
|
- `<Router>` accepts `PossibleMeta` props (`url`, `base`, etc.) to override the surrounding context — this is how nested routers scope themselves.
|
|
34139
34335
|
- 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`.
|
|
34140
34336
|
- Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
|
|
34141
|
-
- Inside `<Navigation>` with stacks, each page in a stack is a new page: a link mounts a new page, and `
|
|
34337
|
+
- Inside `<Navigation>` with stacks, each page in a stack is a new page: a link mounts a new page, and `NavigationSequence.replace()` keeps the same page mounted (it re-renders with the new URL). Elsewhere each path is a new page.
|
|
34142
34338
|
- `<Router>` itself does not cache pages — wrap it in a `<RouteCache>` (with a `<Scroll vertical cover>` between them) to keep recently-visited pages mounted but hidden so back/forward navigation restores their state.
|
|
34143
34339
|
|
|
34144
34340
|
## Usage
|
|
@@ -36942,7 +37138,7 @@ A direction-aware `<Transition>` preset that slides its children horizontally
|
|
|
36942
37138
|
**Things to know:**
|
|
36943
37139
|
|
|
36944
37140
|
- Slides right by default and when the type is `"forward"`; slides left when the type is `"back"`.
|
|
36945
|
-
- Inside `<Navigation>` the direction is automatic: a link click or `
|
|
37141
|
+
- Inside `<Navigation>` the direction is automatic: a link click or `NavigationSequence.forward()` sets the `"forward"` type, and a `className="back"` link or `NavigationSequence.back()` sets `"back"`. The browser back and forward buttons set the type from the page's place in its stack. `NavigationSequence.replace()` has no transition. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
|
|
36946
37142
|
- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
|
|
36947
37143
|
- The old and new content slide a full width apart, so they sit edge to edge and never overlap.
|
|
36948
37144
|
- 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.
|
|
@@ -37087,7 +37283,7 @@ The base View Transition wrapper. It wraps its children in React 19's `<ViewTran
|
|
|
37087
37283
|
|
|
37088
37284
|
- Set `default` for the base transition; `forward` and `back` default to it and let you pick a direction-aware variant. The class names must correspond to `::view-transition-old(.className)` / `::view-transition-new(.className)` rules in your CSS.
|
|
37089
37285
|
- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`, from `Transition.module.css`).
|
|
37090
|
-
- Direction is driven by the active view-transition type. `<Navigation>` sets it for each page change (`"forward"` for a link or `
|
|
37286
|
+
- Direction is driven by the active view-transition type. `<Navigation>` sets it for each page change (`"forward"` for a link or `NavigationSequence.forward()`, `"back"` for the browser back button). For any other change, call `setTransitionType("forward")` (or `"back"`) inside a `startTransition()` callback; the variants read that type to choose the correct slide.
|
|
37091
37287
|
- React runs a view transition only for a transition update (`startTransition()`, `useDeferredValue()` or a Suspense reveal). A sync update, for example a `useStore()` change, swaps the content with no animation.
|
|
37092
37288
|
- The preset variants honour `prefers-reduced-motion: reduce` — positional movement (slides, collapse) is removed while opacity-only fades are kept (see each preset's page). Custom transition classes should ship their own `@media (prefers-reduced-motion: reduce)` override; `animation: none` on the `::view-transition-*` pseudo-elements makes the swap an instant cut while the DOM update still happens.
|
|
37093
37289
|
|
|
@@ -37352,7 +37548,7 @@ A direction-aware `<Transition>` preset that slides its children vertically —
|
|
|
37352
37548
|
**Things to know:**
|
|
37353
37549
|
|
|
37354
37550
|
- Slides down by default and when the type is `"forward"`; slides up when the type is `"back"`.
|
|
37355
|
-
- Inside `<Navigation>` the direction is automatic: a link click or `
|
|
37551
|
+
- Inside `<Navigation>` the direction is automatic: a link click or `NavigationSequence.forward()` sets the `"forward"` type, and a `className="back"` link or `NavigationSequence.back()` sets `"back"`. The browser back and forward buttons set the type from the page's place in its stack. `NavigationSequence.replace()` has no transition. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
|
|
37356
37552
|
- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
|
|
37357
37553
|
- The old and new content slide a full height apart, so they sit edge to edge and never overlap.
|
|
37358
37554
|
- 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.
|
|
@@ -38426,7 +38622,7 @@ Reads a React context and throws `RequiredError` if the value is `null` or `unde
|
|
|
38426
38622
|
```ts
|
|
38427
38623
|
import { requireContext } from "shelving/ui";
|
|
38428
38624
|
|
|
38429
|
-
function requireNavigation():
|
|
38625
|
+
function requireNavigation(): NavigationSequence {
|
|
38430
38626
|
return requireContext(NavigationContext, requireNavigation);
|
|
38431
38627
|
}
|
|
38432
38628
|
```
|
|
@@ -38763,6 +38959,70 @@ eventLoopFocus({ currentTarget, relatedTarget }: { currentTarget: Element; relat
|
|
|
38763
38959
|
```
|
|
38764
38960
|
|
|
38765
38961
|
|
|
38962
|
+
---
|
|
38963
|
+
|
|
38964
|
+
# isKeyboardOpen()
|
|
38965
|
+
|
|
38966
|
+
- Kind: function
|
|
38967
|
+
- Import: `import { isKeyboardOpen } from "shelving/ui";`
|
|
38968
|
+
|
|
38969
|
+
Is the on-screen keyboard open (or still closing)?
|
|
38970
|
+
- On iOS (Safari, home-screen web apps and `WKWebView`) the keyboard makes the visual viewport shorter than the window.
|
|
38971
|
+
- Returns `false` when the page is zoomed in, because a zoomed visual viewport is also shorter than the window.
|
|
38972
|
+
- Returns `false` where the keyboard resizes the whole page (Android Chrome by default), and with no on-screen keyboard.
|
|
38973
|
+
|
|
38974
|
+
## Signatures
|
|
38975
|
+
|
|
38976
|
+
```ts
|
|
38977
|
+
isKeyboardOpen(): boolean
|
|
38978
|
+
```
|
|
38979
|
+
|
|
38980
|
+
## Returns
|
|
38981
|
+
|
|
38982
|
+
| Type | Description |
|
|
38983
|
+
| --- | --- |
|
|
38984
|
+
| `boolean` | `true` when the visual viewport is much shorter than the window. |
|
|
38985
|
+
|
|
38986
|
+
## Examples
|
|
38987
|
+
|
|
38988
|
+
```ts
|
|
38989
|
+
if (isKeyboardOpen()) await waitForKeyboard();
|
|
38990
|
+
```
|
|
38991
|
+
|
|
38992
|
+
|
|
38993
|
+
---
|
|
38994
|
+
|
|
38995
|
+
# waitForKeyboard()
|
|
38996
|
+
|
|
38997
|
+
- Kind: function
|
|
38998
|
+
- Import: `import { waitForKeyboard } from "shelving/ui";`
|
|
38999
|
+
|
|
39000
|
+
Lower the on-screen keyboard, and wait until it is down.
|
|
39001
|
+
- Blurs the focused text field, if there is one, so the keyboard starts to close.
|
|
39002
|
+
- When the keyboard is open (`isKeyboardOpen()`) or a field was just blurred, it waits until the keyboard is down and the
|
|
39003
|
+
viewport has stopped changing size, for at most half a second.
|
|
39004
|
+
- Returns nothing when there is nothing to wait for, so a caller can go on at once without a promise.
|
|
39005
|
+
- Use it before a page slide: a keyboard that closes during a view transition resizes the page in the middle of it.
|
|
39006
|
+
|
|
39007
|
+
## Signatures
|
|
39008
|
+
|
|
39009
|
+
```ts
|
|
39010
|
+
waitForKeyboard(): Promise<void> | void
|
|
39011
|
+
```
|
|
39012
|
+
|
|
39013
|
+
## Returns
|
|
39014
|
+
|
|
39015
|
+
| Type | Description |
|
|
39016
|
+
| --- | --- |
|
|
39017
|
+
| `Promise<void> \| void` | A promise that resolves when the keyboard is down, or nothing when it is down already. |
|
|
39018
|
+
|
|
39019
|
+
## Examples
|
|
39020
|
+
|
|
39021
|
+
```ts
|
|
39022
|
+
const waiting = waitForKeyboard(); if (waiting) await waiting;
|
|
39023
|
+
```
|
|
39024
|
+
|
|
39025
|
+
|
|
38766
39026
|
---
|
|
38767
39027
|
|
|
38768
39028
|
# MetaTags
|
|
@@ -38903,6 +39163,7 @@ Combined meta data for a website page — title, URLs, description, CSP, tags, l
|
|
|
38903
39163
|
readonly root?: ImmutableURL | undefined;
|
|
38904
39164
|
readonly url?: ImmutableURL | undefined;
|
|
38905
39165
|
readonly stack?: AbsolutePath | null | undefined;
|
|
39166
|
+
readonly ordinal?: number | undefined;
|
|
38906
39167
|
readonly app?: string | undefined;
|
|
38907
39168
|
readonly title?: string | undefined;
|
|
38908
39169
|
readonly description?: string | undefined;
|
|
@@ -38924,6 +39185,7 @@ Combined meta data for a website page — title, URLs, description, CSP, tags, l
|
|
|
38924
39185
|
| `root` | `ImmutableURL \| undefined` | Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). Read only. Optional. |
|
|
38925
39186
|
| `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. |
|
|
38926
39187
|
| `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. |
|
|
39188
|
+
| `ordinal` | `number \| undefined` | Position of the current page in its stack, where `0` is the root. `<Navigation>` publishes it, and `<RouteCache>` and `<Router>` key each page by its stack and ordinal. `undefined` without the Navigation API. Read only. Optional. |
|
|
38927
39189
|
| `app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
|
|
38928
39190
|
| `title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
|
|
38929
39191
|
| `description` | `string \| undefined` | Description of the current page. Read only. Optional. |
|
|
@@ -39070,6 +39332,7 @@ mergeMeta(meta1: Meta, meta2: PossibleMeta, caller: AnyCaller = mergeMeta): Meta
|
|
|
39070
39332
|
| `.root` | `ImmutableURL \| undefined` | Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). Read only. Optional. |
|
|
39071
39333
|
| `.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. |
|
|
39072
39334
|
| `.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. |
|
|
39335
|
+
| `.ordinal` | `number \| undefined` | Position of the current page in its stack, where `0` is the root. `<Navigation>` publishes it, and `<RouteCache>` and `<Router>` key each page by its stack and ordinal. `undefined` without the Navigation API. Read only. Optional. |
|
|
39073
39336
|
| `.app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
|
|
39074
39337
|
| `.title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
|
|
39075
39338
|
| `.description` | `string \| undefined` | Description of the current page. Read only. Optional. |
|