shelving 1.320.0 → 1.321.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/guides/building-with-shelving.md +26 -0
- package/docs/llms-full.txt +629 -257
- package/docs/ui/BackButton.md +75 -0
- package/docs/ui/BackButtonProps.md +21 -0
- package/docs/ui/ClickableProps.md +0 -2
- package/docs/ui/Head.md +2 -2
- package/docs/ui/HorizontalTransition.md +1 -1
- package/docs/ui/LinkClickable.md +0 -1
- package/docs/ui/Meta.md +3 -1
- package/docs/ui/Navigation.md +93 -37
- package/docs/ui/NavigationEntryState.md +22 -0
- package/docs/ui/NavigationPosition.md +24 -0
- package/docs/ui/NavigationPositionContext.md +8 -0
- package/docs/ui/NavigationProps.md +12 -2
- package/docs/ui/NavigationStore/back.md +6 -4
- package/docs/ui/NavigationStore/forward.md +6 -2
- package/docs/ui/NavigationStore/history.md +15 -0
- package/docs/ui/NavigationStore/listen.md +14 -0
- package/docs/ui/NavigationStore/replace.md +15 -0
- package/docs/ui/NavigationStore.md +100 -19
- package/docs/ui/RouteCache.md +72 -36
- package/docs/ui/RouteCacheProps.md +3 -3
- package/docs/ui/Router.md +4 -2
- package/docs/ui/StackButton.md +64 -0
- package/docs/ui/StackButtonProps.md +21 -0
- package/docs/ui/VerticalTransition.md +1 -1
- package/docs/ui/mergeMeta.md +2 -1
- package/docs/ui.md +13 -10
- package/package.json +1 -1
- package/ui/button/Clickable.d.ts +1 -3
- package/ui/button/Clickable.js +2 -2
- package/ui/button/Clickable.tsx +0 -4
- package/ui/page/Head.d.ts +2 -2
- package/ui/page/Head.js +9 -8
- package/ui/page/Head.tsx +8 -6
- package/ui/router/BackButton.d.ts +22 -0
- package/ui/router/BackButton.js +19 -0
- package/ui/router/BackButton.md +47 -0
- package/ui/router/BackButton.tsx +34 -0
- package/ui/router/Navigation.d.ts +22 -12
- package/ui/router/Navigation.js +67 -51
- package/ui/router/Navigation.md +84 -27
- package/ui/router/Navigation.test.tsx +27 -7
- package/ui/router/Navigation.tsx +90 -53
- package/ui/router/NavigationContext.d.ts +9 -1
- package/ui/router/NavigationContext.js +9 -0
- package/ui/router/NavigationContext.tsx +11 -1
- package/ui/router/NavigationStore.d.ts +126 -19
- package/ui/router/NavigationStore.js +301 -30
- package/ui/router/NavigationStore.md +82 -9
- package/ui/router/NavigationStore.test.ts +384 -0
- package/ui/router/NavigationStore.tsx +347 -30
- package/ui/router/RouteCache.d.ts +15 -22
- package/ui/router/RouteCache.js +36 -47
- package/ui/router/RouteCache.md +59 -16
- package/ui/router/RouteCache.tsx +55 -62
- package/ui/router/Router.d.ts +2 -1
- package/ui/router/Router.js +9 -14
- package/ui/router/Router.md +2 -1
- package/ui/router/Router.tsx +9 -20
- package/ui/router/StackButton.d.ts +24 -0
- package/ui/router/StackButton.js +35 -0
- package/ui/router/StackButton.md +34 -0
- package/ui/router/StackButton.tsx +44 -0
- package/ui/router/index.d.ts +2 -2
- package/ui/router/index.js +2 -2
- package/ui/router/index.ts +2 -2
- package/ui/transition/HorizontalTransition.md +1 -1
- package/ui/transition/VerticalTransition.md +1 -1
- package/ui/util/meta.d.ts +4 -1
- package/ui/util/meta.ts +4 -1
- package/docs/ui/NavigationStore/redirect.md +0 -12
- package/docs/ui/RouteConfig.md +0 -75
- package/docs/ui/RouteConfigProps.md +0 -24
- package/docs/ui/RouteContext.md +0 -6
- package/docs/ui/RouteState.md +0 -30
- package/ui/router/RouteConfig.d.ts +0 -28
- package/ui/router/RouteConfig.js +0 -30
- package/ui/router/RouteConfig.md +0 -42
- package/ui/router/RouteConfig.tsx +0 -44
- package/ui/router/RouteContext.d.ts +0 -22
- package/ui/router/RouteContext.js +0 -8
- package/ui/router/RouteContext.tsx +0 -26
package/docs/llms-full.txt
CHANGED
|
@@ -854,6 +854,32 @@ If every file in that list is in the right place, the client and server share on
|
|
|
854
854
|
|
|
855
855
|
## Upgrade notes
|
|
856
856
|
|
|
857
|
+
### Tab stacks in `<Navigation>`
|
|
858
|
+
|
|
859
|
+
`<Navigation>` now keeps one stack of pages for each tab, like a phone app. It uses the browser [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API). Some names and props changed. To upgrade an app:
|
|
860
|
+
|
|
861
|
+
1. **Rename `redirect()` to `replace()`.** Change each `nav.redirect(url)` to `nav.replace(url)`. It does the same thing: it changes the URL of the current page with no new history entry and no slide.
|
|
862
|
+
2. **Change the `back` prop to a class.** The `back` prop on `<Button>` and `<Link>` is removed, and so is the `data-back` attribute. Change `<Button href="/profile" back>` to `<Button href="/profile" className="back">`. For a page-header back button, use `<BackButton href="/profile"/>` (see step 6).
|
|
863
|
+
3. **Remove `<RouteConfig>`.** `<RouteConfig>` and `RouteContext` are removed.
|
|
864
|
+
- `<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.
|
|
865
|
+
- `<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.
|
|
866
|
+
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 `NavigationStore.replace()`. You do not need to change anything, but do not also call `window.history.replaceState()` for it.
|
|
867
|
+
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 app opens in the `/` stack, which is unstacked: no tab is selected until the user taps a tab, or the app names a stack. Deep links and login pages are unstacked. A login page calls `nav.replace("/home", "/home")` to send the user into the Home tab.
|
|
868
|
+
6. **Use the new buttons (optional).**
|
|
869
|
+
- `<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.
|
|
870
|
+
- `<BackButton href="/home"/>` goes back to the page before this one in the current tab, or to `href` when there is none.
|
|
871
|
+
7. **Move the page transition outside `<RouteCache>`.** Put `<HorizontalTransition>` (or any page `<Transition>`) around the `<RouteCache>`, not inside it around each page. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
|
|
872
|
+
8. **Check pages that change URL for the same component.** `<RouteCache>` now keys each page by its stack and depth, not by its path. A replace from `/post/1` to `/post/2` keeps the same component mounted with its state. If the page must reset, wrap its content in an element with `key={id}`.
|
|
873
|
+
9. **Know the fallback.** Without the Navigation API (older browsers), links still work with no page reload, but there are no stacks, no slides and no page cache. `<StackButton>` and `<BackButton>` become plain links.
|
|
874
|
+
|
|
875
|
+
What changes for users:
|
|
876
|
+
|
|
877
|
+
- Each tab remembers the page you left it on, and its back button goes back within that tab.
|
|
878
|
+
- The browser back button walks the history as before, across tabs. The page slides the right way.
|
|
879
|
+
- When you go back from a page, it leaves the cache. So the browser forward button then shows that page fresh, from the top.
|
|
880
|
+
|
|
881
|
+
See `<Navigation>`, `NavigationStore`, `<RouteCache>`, `<StackButton>` and `<BackButton>` for the full details.
|
|
882
|
+
|
|
857
883
|
### From `CacheDBProvider` to `HydratingAPIProvider`
|
|
858
884
|
|
|
859
885
|
`CacheDBProvider` and the paging in `QueryStore` are removed. To upgrade an app:
|
|
@@ -20167,13 +20193,14 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20167
20193
|
- [Empty](ui/Empty.md): Message for a list with nothing in it: centred, grey content with space around it.
|
|
20168
20194
|
- [Notice](ui/Notice.md): Block-level status callout with an icon and message, used to highlight feedback.
|
|
20169
20195
|
- [Notices](ui/Notices.md): Render the global list of notices and subscribe to incoming "notice" events.
|
|
20170
|
-
- [Head](ui/Head.md): Emit the current page's head metadata and
|
|
20196
|
+
- [Head](ui/Head.md): Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
|
|
20171
20197
|
- [HTML](ui/HTML.md): Render the full <html> document shell wrapping <head> and <body>.
|
|
20172
20198
|
- [Page](ui/Page.md): Wrap a single page (or screen) within an app, applying its meta and head tags.
|
|
20173
|
-
- [
|
|
20174
|
-
- [
|
|
20175
|
-
- [
|
|
20199
|
+
- [BackButton](ui/BackButton.md): Back button for the current stack.
|
|
20200
|
+
- [Navigation](ui/Navigation.md): Top-level navigation provider, with one stack of pages for each tab.
|
|
20201
|
+
- [RouteCache](ui/RouteCache.md): Keep-alive page cache for the pages in the navigation stacks. Drop it into a layout around its scrolling content region.
|
|
20176
20202
|
- [Router](ui/Router.md): Match the current URL against routes and render the matched element.
|
|
20203
|
+
- [StackButton](ui/StackButton.md): Button for one stack in a tab bar.
|
|
20177
20204
|
- [Scroll](ui/Scroll.md): Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
|
|
20178
20205
|
- [Cell](ui/Cell.md): Table cell.
|
|
20179
20206
|
- [Table](ui/Table.md): Table block — rendered as <table>.
|
|
@@ -20295,7 +20322,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20295
20322
|
- [FormStore](ui/FormStore.md): Reactive store holding the current (possibly partial and invalid) value of a form, plus its field messages.
|
|
20296
20323
|
- [NoticesStore](ui/NoticesStore.md): Store holding the live list of NoticeStore notices currently shown.
|
|
20297
20324
|
- [NoticeStore](ui/NoticeStore.md): Store holding a single notice's content and status, owned by a NoticesStore.
|
|
20298
|
-
- [NavigationStore](ui/NavigationStore.md): Store
|
|
20325
|
+
- [NavigationStore](ui/NavigationStore.md): Store that holds the current navigation URL, drives browser history, and keeps a stack of pages for each tab.
|
|
20299
20326
|
|
|
20300
20327
|
## Interfaces
|
|
20301
20328
|
|
|
@@ -20429,11 +20456,13 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20429
20456
|
- [NoticesProps](ui/NoticesProps.md): Props for <Notices> — the place for the list, and flex styling variants for the notices container.
|
|
20430
20457
|
- [HTMLProps](ui/HTMLProps.md): Props for <HTML> — initial Meta (language/root/app) plus the page children.
|
|
20431
20458
|
- [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
|
|
20432
|
-
- [
|
|
20433
|
-
- [
|
|
20434
|
-
- [
|
|
20435
|
-
- [
|
|
20459
|
+
- [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.
|
|
20460
|
+
- [NavigationProps](ui/NavigationProps.md): Props for <Navigation>: the initial Meta (url, root and stack), the stacks, and optional children.
|
|
20461
|
+
- [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationStore saves on each browser history entry.
|
|
20462
|
+
- [NavigationPosition](ui/NavigationPosition.md): Where the app is now in its stacks: the current stack and depth, the top depth of each stack, and the page before the current one.
|
|
20463
|
+
- [RouteCacheProps](ui/RouteCacheProps.md): Props for <RouteCache>: the maxCached size and the content children to keep alive for each page in the stacks.
|
|
20436
20464
|
- [RouterProps](ui/RouterProps.md): Props for <Router> — the routes to match against plus an optional fallback.
|
|
20465
|
+
- [StackButtonProps](ui/StackButtonProps.md): Props for <StackButton>: the stack it opens, plus the usual Button props except href and onClick.
|
|
20437
20466
|
- [BlockVariants](ui/BlockVariants.md): Variants for block level elements.
|
|
20438
20467
|
- [ColorVariants](ui/ColorVariants.md): Variant props for colouring an element, e.g. color="purple".
|
|
20439
20468
|
- [DurationVariants](ui/DurationVariants.md): Variant props for the transition duration of an element, e.g. duration="fast".
|
|
@@ -20534,7 +20563,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20534
20563
|
- [LOADING_NOTICE](ui/LOADING_NOTICE.md): Shared loading <Notice> element showing the loading spinner.
|
|
20535
20564
|
- [NOTICES](ui/NOTICES.md): Global NoticesStore shown by <Notices>, accepting any of the default statuses.
|
|
20536
20565
|
- [NavigationContext](ui/NavigationContext.md): React context holding the current NavigationStore, provided by <Navigation>.
|
|
20537
|
-
- [
|
|
20566
|
+
- [NavigationPositionContext](ui/NavigationPositionContext.md): React context holding where the app is in its stacks, published by <Navigation> with each URL change.
|
|
20538
20567
|
- [STATUSES](ui/STATUSES.md): Tuple of the status names selectable via the status variant prop.
|
|
20539
20568
|
- [TINT_CLASS](ui/TINT_CLASS.md): CSS class that (re)calculates the full ladder of tint shades from the current global tint colour.
|
|
20540
20569
|
- [FADE_TRANSITION_CLASS](ui/FADE_TRANSITION_CLASS.md): View transition class that fades content in and out.
|
|
@@ -23079,7 +23108,6 @@ Props for a thing that can be clicked — either has a string `href` link or an
|
|
|
23079
23108
|
download?: string | undefined;
|
|
23080
23109
|
title?: string | undefined;
|
|
23081
23110
|
selected?: boolean | undefined;
|
|
23082
|
-
back?: boolean | undefined;
|
|
23083
23111
|
}
|
|
23084
23112
|
```
|
|
23085
23113
|
|
|
@@ -23094,7 +23122,6 @@ Props for a thing that can be clicked — either has a string `href` link or an
|
|
|
23094
23122
|
| `download` | `string \| undefined` | If `href` is present then this is the suggested filename for downloading. Optional. |
|
|
23095
23123
|
| `title` | `string \| undefined` | Title shown on hover. Optional. |
|
|
23096
23124
|
| `selected` | `boolean \| undefined` | Whether this is the selected item in a group. Sets `aria-pressed` on a `<button>`, or `aria-current` on an `<a>`. Optional. |
|
|
23097
|
-
| `back` | `boolean \| undefined` | If `href` is present, then `<Navigation>` opens the link with a back transition. Use it for a "back to" link. Sets `data-back` on the `<a>`. Optional. |
|
|
23098
23125
|
|
|
23099
23126
|
|
|
23100
23127
|
---
|
|
@@ -23175,7 +23202,6 @@ LinkClickable({
|
|
|
23175
23202
|
download,
|
|
23176
23203
|
title,
|
|
23177
23204
|
selected,
|
|
23178
|
-
back,
|
|
23179
23205
|
children = "Go",
|
|
23180
23206
|
className,
|
|
23181
23207
|
}: StylableClickableProps): ReactElement
|
|
@@ -32430,10 +32456,10 @@ close(): void
|
|
|
32430
32456
|
- Kind: component
|
|
32431
32457
|
- Import: `import { Head } from "shelving/ui";`
|
|
32432
32458
|
|
|
32433
|
-
Emit the current page's head metadata and
|
|
32459
|
+
Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
|
|
32434
32460
|
- Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
|
|
32435
32461
|
- Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
|
|
32436
|
-
-
|
|
32462
|
+
- When the meta `url` differs from the browser URL (a page that knows its canonical URL), calls `NavigationStore.replace()` with it. Outside `<Navigation>` it does not touch history.
|
|
32437
32463
|
|
|
32438
32464
|
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.
|
|
32439
32465
|
|
|
@@ -32627,6 +32653,110 @@ Page({ children, ...meta }: PageProps): ReactElement
|
|
|
32627
32653
|
| `ReactElement` | |
|
|
32628
32654
|
|
|
32629
32655
|
|
|
32656
|
+
---
|
|
32657
|
+
|
|
32658
|
+
# BackButtonProps
|
|
32659
|
+
|
|
32660
|
+
- Kind: interface
|
|
32661
|
+
- Import: `import { BackButtonProps } from "shelving/ui";`
|
|
32662
|
+
- Extends: `Omit<ButtonProps, "href" | "onClick">`
|
|
32663
|
+
|
|
32664
|
+
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`.
|
|
32665
|
+
|
|
32666
|
+
## Signatures
|
|
32667
|
+
|
|
32668
|
+
```ts
|
|
32669
|
+
{
|
|
32670
|
+
readonly href: AbsolutePath;
|
|
32671
|
+
}
|
|
32672
|
+
```
|
|
32673
|
+
|
|
32674
|
+
## Properties
|
|
32675
|
+
|
|
32676
|
+
| Property | Type | Description |
|
|
32677
|
+
| --- | --- | --- |
|
|
32678
|
+
| `href` | `AbsolutePath` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Read only. |
|
|
32679
|
+
|
|
32680
|
+
|
|
32681
|
+
---
|
|
32682
|
+
|
|
32683
|
+
# BackButton
|
|
32684
|
+
|
|
32685
|
+
- Kind: component
|
|
32686
|
+
- Import: `import { BackButton } from "shelving/ui";`
|
|
32687
|
+
|
|
32688
|
+
Back button for the current stack.
|
|
32689
|
+
- Goes back to the page before this one in the current stack, wherever you came from.
|
|
32690
|
+
- Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
|
|
32691
|
+
- It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
|
|
32692
|
+
|
|
32693
|
+
The back button for a page header. It goes back to the page before this one in the current stack, wherever you came from.
|
|
32694
|
+
|
|
32695
|
+
**Things to know:**
|
|
32696
|
+
|
|
32697
|
+
- 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.
|
|
32698
|
+
- 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 an unstacked page (for example a deep link), it goes to `href` and stays unstacked. To go into a stack, the user taps a `<StackButton>`.
|
|
32699
|
+
- 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.
|
|
32700
|
+
- Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
|
|
32701
|
+
- It takes the usual `<Button>` props, except `onClick`.
|
|
32702
|
+
- Without the browser Navigation API, and in a server render, it links to `href`.
|
|
32703
|
+
- In a server-rendered app the server always renders `href`, and the browser may render the page before this one. React then warns about a hydration mismatch on the first render. A client-only app (with `<App>`) has no mismatch.
|
|
32704
|
+
|
|
32705
|
+
## Usage
|
|
32706
|
+
|
|
32707
|
+
```tsx
|
|
32708
|
+
import { BackButton } from "shelving/ui";
|
|
32709
|
+
|
|
32710
|
+
function PostPage({ id }: { id: string }) {
|
|
32711
|
+
return (
|
|
32712
|
+
<>
|
|
32713
|
+
<header>
|
|
32714
|
+
<BackButton href="/home"/>
|
|
32715
|
+
<h1>Post</h1>
|
|
32716
|
+
</header>
|
|
32717
|
+
{/* … */}
|
|
32718
|
+
</>
|
|
32719
|
+
);
|
|
32720
|
+
}
|
|
32721
|
+
```
|
|
32722
|
+
|
|
32723
|
+
With a label:
|
|
32724
|
+
|
|
32725
|
+
```tsx
|
|
32726
|
+
<BackButton href="/profile">Back to profile</BackButton>
|
|
32727
|
+
```
|
|
32728
|
+
|
|
32729
|
+
To go back to one fixed page (not to the page before), use a link with `className="back"`:
|
|
32730
|
+
|
|
32731
|
+
```tsx
|
|
32732
|
+
<Button href="/profile" className="back">Profile</Button>
|
|
32733
|
+
```
|
|
32734
|
+
|
|
32735
|
+
## Styling
|
|
32736
|
+
|
|
32737
|
+
`<BackButton>` renders a `<Button>`, so it has the same styling hooks. See `<Button>`.
|
|
32738
|
+
|
|
32739
|
+
|
|
32740
|
+
## Signatures
|
|
32741
|
+
|
|
32742
|
+
```ts
|
|
32743
|
+
BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement
|
|
32744
|
+
```
|
|
32745
|
+
|
|
32746
|
+
## Parameters
|
|
32747
|
+
|
|
32748
|
+
| Param | Type | Description |
|
|
32749
|
+
| --- | --- | --- |
|
|
32750
|
+
| `props` | `BackButtonProps` | |
|
|
32751
|
+
| `.href` | `AbsolutePath` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Read only. |
|
|
32752
|
+
|
|
32753
|
+
## Returns
|
|
32754
|
+
|
|
32755
|
+
| Type | Description |
|
|
32756
|
+
| --- | --- |
|
|
32757
|
+
| `ReactElement` | |
|
|
32758
|
+
|
|
32759
|
+
|
|
32630
32760
|
---
|
|
32631
32761
|
|
|
32632
32762
|
# NavigationProps
|
|
@@ -32635,14 +32765,24 @@ Page({ children, ...meta }: PageProps): ReactElement
|
|
|
32635
32765
|
- Import: `import { NavigationProps } from "shelving/ui";`
|
|
32636
32766
|
- Extends: `PossibleMeta`
|
|
32637
32767
|
|
|
32638
|
-
Props for `<Navigation
|
|
32768
|
+
Props for `<Navigation>`: the initial `Meta` (url, root and stack), the `stacks`, and optional `children`.
|
|
32639
32769
|
|
|
32640
32770
|
## Signatures
|
|
32641
32771
|
|
|
32642
32772
|
```ts
|
|
32643
|
-
{
|
|
32773
|
+
{
|
|
32774
|
+
readonly stacks?: readonly AbsolutePath[] | undefined;
|
|
32775
|
+
readonly stack?: AbsolutePath | undefined;
|
|
32776
|
+
}
|
|
32644
32777
|
```
|
|
32645
32778
|
|
|
32779
|
+
## Properties
|
|
32780
|
+
|
|
32781
|
+
| Property | Type | Description |
|
|
32782
|
+
| --- | --- | --- |
|
|
32783
|
+
| `stacks` | `readonly AbsolutePath[] \| undefined` | Root path of each stack, in tab order, for an app with a tab bar (for example `["/home", "/discover", "/profile"]`). - Each stack keeps its own pages, so each tab remembers where you left it, and a back button goes back within its tab. - With no stacks, the app has one stack at `"/"`, and `stack` in `Meta` is `"/"`. Read only. Optional. |
|
|
32784
|
+
| `stack` | `AbsolutePath \| undefined` | Stack of the page the app opens at (for example `"/home"`), like `url` and `root`. - Read from this prop, else from the surrounding `<Meta>`, else `"/"`. - Used only when the opening history entry has no saved stack. A reload keeps the stack it had. Read only. Optional. |
|
|
32785
|
+
|
|
32646
32786
|
|
|
32647
32787
|
---
|
|
32648
32788
|
|
|
@@ -32651,78 +32791,132 @@ Props for `<Navigation>` — initial `Meta` (url/base) plus optional `children`.
|
|
|
32651
32791
|
- Kind: component
|
|
32652
32792
|
- Import: `import { Navigation } from "shelving/ui";`
|
|
32653
32793
|
|
|
32654
|
-
Top-level navigation provider.
|
|
32655
|
-
- Owns a single `NavigationStore`
|
|
32656
|
-
-
|
|
32657
|
-
-
|
|
32658
|
-
- Publishes
|
|
32659
|
-
-
|
|
32660
|
-
- Skips the transition when the browser already animated the change (`PopStateEvent.hasUAVisualTransition`, e.g. a swipe-back gesture).
|
|
32794
|
+
Top-level navigation provider, with one stack of pages for each tab.
|
|
32795
|
+
- Owns a single `NavigationStore` made from the surrounding `<Meta>` url and root.
|
|
32796
|
+
- Turns clicks on same-origin links into `NavigationStore.forward()`, or `NavigationStore.back()` for a link with `className="back"`, or `NavigationStore.replace()` for a link with `className="replace"`. Clicks with a modifier key, or on links with `download` or a `target`, are left to the browser.
|
|
32797
|
+
- Publishes the URL and the current `stack` into `Meta`, and the position in the stacks into `NavigationPositionContext`, all in one render.
|
|
32798
|
+
- Publishes each change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition. A replace, or a change the browser already animated (for example a swipe-back), has no transition.
|
|
32799
|
+
- Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
|
|
32661
32800
|
|
|
32662
|
-
Exactly one `<Navigation>` per app
|
|
32801
|
+
Exactly one `<Navigation>` per app. Nested routers share its store.
|
|
32663
32802
|
|
|
32664
|
-
|
|
32803
|
+
The top-level navigation provider for a client-side app. It owns one `NavigationStore`, turns link clicks into navigation, and publishes the live URL into `<Meta>`, so each `<Router>` re-renders when the URL changes. Use exactly one `<Navigation>` per app. Nested routers all share its store.
|
|
32665
32804
|
|
|
32666
|
-
|
|
32805
|
+
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.
|
|
32667
32806
|
|
|
32668
32807
|
**Things to know:**
|
|
32669
32808
|
|
|
32670
|
-
- Same-origin
|
|
32671
|
-
-
|
|
32672
|
-
-
|
|
32673
|
-
-
|
|
32674
|
-
-
|
|
32675
|
-
- The
|
|
32676
|
-
-
|
|
32677
|
-
-
|
|
32678
|
-
-
|
|
32809
|
+
- Same-origin link clicks become `NavigationStore.forward()`, so the page slides forward.
|
|
32810
|
+
- A link with `className="back"` calls `NavigationStore.back()`, so the page slides back. `<BackButton>` sets this class for you.
|
|
32811
|
+
- A link with `className="replace"` calls `NavigationStore.replace()`. It changes the URL with no new history entry and no slide, and keeps the same page mounted. Use it for tabs inside a page.
|
|
32812
|
+
- 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.
|
|
32813
|
+
- 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.
|
|
32814
|
+
- 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.
|
|
32815
|
+
- 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.
|
|
32816
|
+
- It publishes `stack` (the root of the current stack) into `<Meta>` beside `url`, so any component can read the current tab with `requireMeta().stack`. With no `stacks`, the app has one stack, and `stack` is `"/"`.
|
|
32817
|
+
- 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`.
|
|
32818
|
+
- `<Router>` works with no `<Navigation>` (server renders, static renders, tests). `<Navigation>` only makes the URL live on the client.
|
|
32819
|
+
|
|
32820
|
+
### Browser support
|
|
32821
|
+
|
|
32822
|
+
Stacks and slides use the browser [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API). Without it (older browsers, a server render, or a sandboxed frame), `<Navigation>` falls back to plain navigation:
|
|
32823
|
+
|
|
32824
|
+
- Links still go through the app with no page reload, and the browser back button works.
|
|
32825
|
+
- There are no stacks, no slides and no `<RouteCache>`. Each page mounts fresh.
|
|
32826
|
+
- `<StackButton>` is a plain link to its stack's root. `<BackButton>` is a plain link to its `href`.
|
|
32679
32827
|
|
|
32680
32828
|
## Usage
|
|
32681
32829
|
|
|
32830
|
+
### Basic setup
|
|
32831
|
+
|
|
32682
32832
|
```tsx
|
|
32683
|
-
import {
|
|
32833
|
+
import { App, Navigation, Router } from "shelving/ui";
|
|
32684
32834
|
|
|
32685
|
-
<
|
|
32835
|
+
<App root="https://example.com/">
|
|
32686
32836
|
<Navigation>
|
|
32687
32837
|
<Router routes={ROUTES}/>
|
|
32688
32838
|
</Navigation>
|
|
32689
|
-
</
|
|
32839
|
+
</App>
|
|
32690
32840
|
```
|
|
32691
32841
|
|
|
32692
|
-
###
|
|
32842
|
+
### App with a tab bar
|
|
32843
|
+
|
|
32844
|
+
List the root path of each stack in tab order. Put a `<StackButton>` for each stack in the tab bar.
|
|
32693
32845
|
|
|
32694
32846
|
```tsx
|
|
32695
|
-
import { HorizontalTransition, Navigation, Router } from "shelving/ui";
|
|
32847
|
+
import { App, HorizontalTransition, Navigation, RouteCache, Router, StackButton } from "shelving/ui";
|
|
32696
32848
|
|
|
32697
|
-
|
|
32698
|
-
<Navigation>
|
|
32699
|
-
<HorizontalTransition>
|
|
32700
|
-
<Router routes={ROUTES}/>
|
|
32701
|
-
</HorizontalTransition>
|
|
32702
|
-
</Navigation>
|
|
32849
|
+
const STACKS = ["/home", "/discover", "/profile"] as const;
|
|
32703
32850
|
|
|
32704
|
-
|
|
32705
|
-
<
|
|
32851
|
+
<App root="https://example.com/">
|
|
32852
|
+
<Navigation stacks={STACKS}>
|
|
32853
|
+
<HorizontalTransition>
|
|
32854
|
+
<RouteCache>
|
|
32855
|
+
<Router routes={ROUTES}/>
|
|
32856
|
+
</RouteCache>
|
|
32857
|
+
</HorizontalTransition>
|
|
32858
|
+
<nav className="tab-bar">
|
|
32859
|
+
<StackButton stack="/home">Home</StackButton>
|
|
32860
|
+
<StackButton stack="/discover">Discover</StackButton>
|
|
32861
|
+
<StackButton stack="/profile">Profile</StackButton>
|
|
32862
|
+
</nav>
|
|
32863
|
+
</Navigation>
|
|
32864
|
+
</App>
|
|
32865
|
+
```
|
|
32866
|
+
|
|
32867
|
+
To select a tab when the app starts, pass the starting `stack`. The app decides which stack the opening URL belongs to, for example:
|
|
32868
|
+
|
|
32869
|
+
```tsx
|
|
32870
|
+
const path = window.location.pathname;
|
|
32871
|
+
const stack = STACKS.find(s => path === s || path.startsWith(`${s}/`));
|
|
32872
|
+
|
|
32873
|
+
<Navigation stacks={STACKS} stack={stack}>
|
|
32874
|
+
```
|
|
32875
|
+
|
|
32876
|
+
Put the transition **outside** `<RouteCache>`, around the whole cache. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
|
|
32877
|
+
|
|
32878
|
+
The app opens in the `stack` you set on `<Navigation>` (or on the surrounding `<Meta>`, like `url` and `root`), else in the `/` stack. A page in the `/` stack, such as a deep link or a login page, is **unstacked**: no tab is selected, and links from it stay unstacked until you tap a tab or name a stack (for example `nav.replace("/home", "/home")` after a login). See `NavigationStore`.
|
|
32879
|
+
|
|
32880
|
+
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.
|
|
32881
|
+
|
|
32882
|
+
### Links
|
|
32883
|
+
|
|
32884
|
+
```tsx
|
|
32885
|
+
// Opens a new page in the current stack. Slides forward.
|
|
32886
|
+
<Button href="/home/post/1">Open post</Button>
|
|
32887
|
+
|
|
32888
|
+
// Goes back to a page. Slides back.
|
|
32889
|
+
// If the page is already in the stack, the stack goes back to it.
|
|
32890
|
+
<Button href="/home" className="back">Back to home</Button>
|
|
32891
|
+
|
|
32892
|
+
// The back button for a page header. Goes to the page before this one in the stack, or to `href`.
|
|
32893
|
+
<BackButton href="/home"/>
|
|
32894
|
+
|
|
32895
|
+
// Changes the URL but keeps the same page. No slide, no new history entry.
|
|
32896
|
+
<Button href="/profile/posts" className="replace">Posts</Button>
|
|
32897
|
+
<Button href="/profile/likes" className="replace">Likes</Button>
|
|
32706
32898
|
```
|
|
32707
32899
|
|
|
32708
32900
|
### Imperative navigation
|
|
32709
32901
|
|
|
32710
|
-
Read the
|
|
32902
|
+
Read the store from anywhere in the tree with `requireNavigation()`:
|
|
32711
32903
|
|
|
32712
32904
|
```tsx
|
|
32713
32905
|
import { requireNavigation } from "shelving/ui";
|
|
32714
32906
|
|
|
32715
32907
|
const nav = requireNavigation();
|
|
32716
|
-
nav.forward("/
|
|
32717
|
-
nav.
|
|
32718
|
-
nav.
|
|
32908
|
+
nav.forward("/home/post/1"); // Open a page in the current stack.
|
|
32909
|
+
nav.back("/home"); // Go back to a page.
|
|
32910
|
+
nav.replace("/login"); // Change the URL of the current page.
|
|
32719
32911
|
```
|
|
32720
32912
|
|
|
32913
|
+
See `NavigationStore` for what each method does.
|
|
32914
|
+
|
|
32721
32915
|
|
|
32722
32916
|
## Signatures
|
|
32723
32917
|
|
|
32724
32918
|
```ts
|
|
32725
|
-
Navigation({ children, ...meta }: NavigationProps): ReactElement
|
|
32919
|
+
Navigation({ children, stacks = [], ...meta }: NavigationProps): ReactElement
|
|
32726
32920
|
```
|
|
32727
32921
|
|
|
32728
32922
|
## Parameters
|
|
@@ -32730,6 +32924,8 @@ Navigation({ children, ...meta }: NavigationProps): ReactElement
|
|
|
32730
32924
|
| Param | Type | Description |
|
|
32731
32925
|
| --- | --- | --- |
|
|
32732
32926
|
| `meta` | `NavigationProps` | |
|
|
32927
|
+
| `.stacks` | `readonly AbsolutePath[] \| undefined` | Root path of each stack, in tab order, for an app with a tab bar (for example `["/home", "/discover", "/profile"]`). - Each stack keeps its own pages, so each tab remembers where you left it, and a back button goes back within its tab. - With no stacks, the app has one stack at `"/"`, and `stack` in `Meta` is `"/"`. Read only. Optional. |
|
|
32928
|
+
| `.stack` | `AbsolutePath \| undefined` | Stack of the page the app opens at (for example `"/home"`), like `url` and `root`. - Read from this prop, else from the surrounding `<Meta>`, else `"/"`. - Used only when the opening history entry has no saved stack. A reload keeps the stack it had. Read only. Optional. |
|
|
32733
32929
|
|
|
32734
32930
|
## Returns
|
|
32735
32931
|
|
|
@@ -32782,6 +32978,72 @@ requireNavigation(): NavigationStore
|
|
|
32782
32978
|
| `unknown` | RequiredError If no `<Navigation>` provider is present above. |
|
|
32783
32979
|
|
|
32784
32980
|
|
|
32981
|
+
---
|
|
32982
|
+
|
|
32983
|
+
# NavigationPositionContext
|
|
32984
|
+
|
|
32985
|
+
- Kind: constant
|
|
32986
|
+
- Import: `import { NavigationPositionContext } from "shelving/ui";`
|
|
32987
|
+
|
|
32988
|
+
React context holding where the app is in its stacks, published by `<Navigation>` with each URL change.
|
|
32989
|
+
- `undefined` without the browser Navigation API, during a server render, or outside `<Navigation>`.
|
|
32990
|
+
- `<RouteCache>`, `<Router>` and `<BackButton>` read it, so they change in the same render as the URL.
|
|
32991
|
+
|
|
32992
|
+
|
|
32993
|
+
---
|
|
32994
|
+
|
|
32995
|
+
# NavigationEntryState
|
|
32996
|
+
|
|
32997
|
+
- Kind: interface
|
|
32998
|
+
- Import: `import { NavigationEntryState } from "shelving/ui";`
|
|
32999
|
+
|
|
33000
|
+
State that `NavigationStore` saves on each browser history entry.
|
|
33001
|
+
|
|
33002
|
+
## Signatures
|
|
33003
|
+
|
|
33004
|
+
```ts
|
|
33005
|
+
{
|
|
33006
|
+
readonly stack: AbsolutePath;
|
|
33007
|
+
readonly depth: number;
|
|
33008
|
+
}
|
|
33009
|
+
```
|
|
33010
|
+
|
|
33011
|
+
## Properties
|
|
33012
|
+
|
|
33013
|
+
| Property | Type | Description |
|
|
33014
|
+
| --- | --- | --- |
|
|
33015
|
+
| `stack` | `AbsolutePath` | Root path of the stack this page is in. Read only. |
|
|
33016
|
+
| `depth` | `number` | Position of this page in its stack, where `0` is the root. Read only. |
|
|
33017
|
+
|
|
33018
|
+
|
|
33019
|
+
---
|
|
33020
|
+
|
|
33021
|
+
# NavigationPosition
|
|
33022
|
+
|
|
33023
|
+
- Kind: interface
|
|
33024
|
+
- Import: `import { NavigationPosition } from "shelving/ui";`
|
|
33025
|
+
- Extends: `NavigationEntryState`
|
|
33026
|
+
|
|
33027
|
+
Where the app is now in its stacks: the current stack and depth, the top depth of each stack, and the page before the current one.
|
|
33028
|
+
- `undefined` when the browser has no Navigation API, or during a server render.
|
|
33029
|
+
|
|
33030
|
+
## Signatures
|
|
33031
|
+
|
|
33032
|
+
```ts
|
|
33033
|
+
{
|
|
33034
|
+
readonly tops: { readonly [stack: AbsolutePath]: number };
|
|
33035
|
+
readonly parent: AbsolutePath | undefined;
|
|
33036
|
+
}
|
|
33037
|
+
```
|
|
33038
|
+
|
|
33039
|
+
## Properties
|
|
33040
|
+
|
|
33041
|
+
| Property | Type | Description |
|
|
33042
|
+
| --- | --- | --- |
|
|
33043
|
+
| `tops` | `{ readonly [stack: AbsolutePath]: number }` | Depth of the top page of each stack that has pages. Read only. |
|
|
33044
|
+
| `parent` | `AbsolutePath \| undefined` | The page before the current one in its stack, or `undefined` at the bottom of the stack. Read only. |
|
|
33045
|
+
|
|
33046
|
+
|
|
32785
33047
|
---
|
|
32786
33048
|
|
|
32787
33049
|
# NavigationStore
|
|
@@ -32790,46 +33052,120 @@ requireNavigation(): NavigationStore
|
|
|
32790
33052
|
- Import: `import { NavigationStore } from "shelving/ui";`
|
|
32791
33053
|
- Extends: `URLStore`
|
|
32792
33054
|
|
|
32793
|
-
Store
|
|
33055
|
+
Store that holds the current navigation URL, drives browser history, and keeps a stack of pages for each tab.
|
|
32794
33056
|
|
|
32795
|
-
- Extends `URLStore
|
|
32796
|
-
-
|
|
32797
|
-
- `
|
|
32798
|
-
-
|
|
33057
|
+
- Extends `URLStore`, so its `value` is the current URL.
|
|
33058
|
+
- 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.
|
|
33059
|
+
- `stack` is a sub-store that holds the root of the current stack. It only changes when the stack changes.
|
|
33060
|
+
- 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.
|
|
33061
|
+
- Owned by `<Navigation>`. Read it with `requireNavigation()`.
|
|
32799
33062
|
|
|
32800
|
-
The store
|
|
33063
|
+
The store that holds the current URL, drives browser history, and keeps one stack of pages for each tab. It extends `URLStore`, so its `value` is the current URL. `<Navigation>` owns it. Read it with `requireNavigation()`, and do not make your own.
|
|
32801
33064
|
|
|
32802
33065
|
**Things to know:**
|
|
32803
33066
|
|
|
32804
|
-
- `
|
|
32805
|
-
-
|
|
32806
|
-
-
|
|
33067
|
+
- `NavigationStore.stacks` is the root path of each stack, in tab order, from the `stacks` prop on `<Navigation>`. With no stacks the app has one stack at `/`.
|
|
33068
|
+
- A page that is not in a listed stack is **unstacked**: it is in the `/` stack. See [Unstacked pages](#unstacked-pages).
|
|
33069
|
+
- `NavigationStore.stack` is a sub-store that holds the root of the current stack. It is always set: with no stacks it is `"/"`. It changes only when the stack changes, so `useStore(nav.stack)` re-renders only on a tab change.
|
|
33070
|
+
- `NavigationStore.history()` returns the pages in the current stack (or a given stack), root first.
|
|
33071
|
+
- `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.
|
|
33072
|
+
- All URLs resolve against the store's `base`. Each method also takes a full same-origin URL.
|
|
33073
|
+
- 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.
|
|
33074
|
+
|
|
33075
|
+
## Methods
|
|
33076
|
+
|
|
33077
|
+
| Method | What it does | Slide |
|
|
33078
|
+
|---|---|---|
|
|
33079
|
+
| `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. |
|
|
33080
|
+
| `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 |
|
|
33081
|
+
| `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 |
|
|
33082
|
+
| `history(stack?)` | Returns the pages in `stack`, root first. | — |
|
|
33083
|
+
|
|
33084
|
+
`stack` defaults to the current stack.
|
|
33085
|
+
|
|
33086
|
+
## Unstacked pages
|
|
33087
|
+
|
|
33088
|
+
A page changes stack only when you say so: with a `<StackButton>`, or with a `stack` argument to `forward()`, `back()` or `replace()`. Links never change stack. The page the app opens at starts in the `stack` set on `<Navigation>` (or the surrounding `<Meta>`), else in the `/` stack. A page in the `/` stack is **unstacked**. For example: a deep link into the app, a fresh open of `/post/9`, or a login page.
|
|
33089
|
+
|
|
33090
|
+
- On an unstacked page, no `<StackButton>` is selected.
|
|
33091
|
+
- Links from an unstacked page push deeper in the `/` stack, even a link to a stack root.
|
|
33092
|
+
- To leave the `/` stack, tap a `<StackButton>`, or name the stack.
|
|
33093
|
+
- 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.
|
|
33094
|
+
- If you list `/` as one of the `stacks`, it is a normal tab, and unstacked pages open in it.
|
|
33095
|
+
|
|
33096
|
+
For example, a login page sends the user home after they log in, and names the Home stack:
|
|
33097
|
+
|
|
33098
|
+
```tsx
|
|
33099
|
+
const nav = requireNavigation();
|
|
33100
|
+
nav.replace("/home", "/home");
|
|
33101
|
+
```
|
|
33102
|
+
|
|
33103
|
+
## How stacks work
|
|
33104
|
+
|
|
33105
|
+
The store saves a small state on each browser history entry: the `stack` the page is in, and its `depth` in that stack (`0` is the root). See `NavigationEntryState`. To read a stack, the store walks back through the browser history from the current entry. It takes the newest entry in that stack, then the newest earlier entry with a lower depth, and so on down to depth `0`.
|
|
33106
|
+
|
|
33107
|
+
Why depth? A browser history entry cannot be changed or removed. So when you go back in one stack while another stack's pages are after it in the history, the store cannot go back in the browser. It pushes a new entry for the page you went back to, at that page's depth. The pages that were above it now have a higher depth than the newest entry, so they are no longer in the stack.
|
|
33108
|
+
|
|
33109
|
+
For example, with tabs `/home` and `/profile`:
|
|
33110
|
+
|
|
33111
|
+
| Step | New history entry | Home stack | Profile stack |
|
|
33112
|
+
|---|---|---|---|
|
|
33113
|
+
| Start at `/home` | `/home` (depth 0) | `/home` | — |
|
|
33114
|
+
| Open a post | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | — |
|
|
33115
|
+
| Tap the Profile tab | `/profile` (depth 0) | `/home`, `/home/post/1` | `/profile` |
|
|
33116
|
+
| Tap the Home tab | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | `/profile` |
|
|
33117
|
+
| Tap the back button | `/home` (depth 0) | `/home` | `/profile` |
|
|
33118
|
+
|
|
33119
|
+
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.
|
|
33120
|
+
|
|
33121
|
+
The browser back and forward buttons walk the history entries one at a time, as usual. Each entry knows its stack and depth, so the stacks are always right and the slide goes the right way.
|
|
32807
33122
|
|
|
32808
33123
|
## Usage
|
|
32809
33124
|
|
|
32810
33125
|
```tsx
|
|
32811
|
-
import { requireNavigation } from "shelving/ui";
|
|
33126
|
+
import { Button, requireNavigation } from "shelving/ui";
|
|
32812
33127
|
|
|
32813
33128
|
function LogoutButton() {
|
|
32814
33129
|
const nav = requireNavigation();
|
|
32815
|
-
return <Button onClick={() => nav.
|
|
33130
|
+
return <Button onClick={() => nav.replace("/login")}>Log out</Button>;
|
|
32816
33131
|
}
|
|
32817
33132
|
```
|
|
32818
33133
|
|
|
32819
|
-
|
|
33134
|
+
Read the current stack in a component:
|
|
33135
|
+
|
|
33136
|
+
```tsx
|
|
33137
|
+
import { useStore } from "shelving/react";
|
|
33138
|
+
import { requireNavigation } from "shelving/ui";
|
|
33139
|
+
|
|
33140
|
+
function TabTitle() {
|
|
33141
|
+
const nav = requireNavigation();
|
|
33142
|
+
const stack = useStore(nav.stack).value;
|
|
33143
|
+
return <h1>{stack === "/profile" ? "Profile" : "Home"}</h1>;
|
|
33144
|
+
}
|
|
33145
|
+
```
|
|
33146
|
+
|
|
33147
|
+
List the pages in a stack (for example, for breadcrumbs):
|
|
33148
|
+
|
|
33149
|
+
```tsx
|
|
33150
|
+
const nav = requireNavigation();
|
|
33151
|
+
nav.history("/home"); // ["/home", "/home/post/1", "/home/post/1/comments"]
|
|
33152
|
+
```
|
|
33153
|
+
|
|
33154
|
+
Make a store by hand only in tests:
|
|
32820
33155
|
|
|
32821
33156
|
```tsx
|
|
32822
33157
|
import { NavigationStore } from "shelving/ui";
|
|
32823
33158
|
|
|
32824
|
-
|
|
32825
|
-
nav
|
|
33159
|
+
// URL, root, starting stack, then the stacks in tab order.
|
|
33160
|
+
const nav = new NavigationStore("https://example.com/home", "https://example.com/", "/home", "/home", "/profile");
|
|
33161
|
+
nav.forward("/home/post/1");
|
|
32826
33162
|
```
|
|
32827
33163
|
|
|
32828
33164
|
|
|
32829
33165
|
## Signatures
|
|
32830
33166
|
|
|
32831
33167
|
```ts
|
|
32832
|
-
new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL)
|
|
33168
|
+
new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL, stack: AbsolutePath = "/", ...stacks: AbsolutePath[])
|
|
32833
33169
|
```
|
|
32834
33170
|
|
|
32835
33171
|
## Parameters
|
|
@@ -32838,6 +33174,8 @@ new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : win
|
|
|
32838
33174
|
| --- | --- | --- |
|
|
32839
33175
|
| `url` | `PossibleURL` | Defaults to `typeof window === "undefined" ? "/" : window.location.href`. |
|
|
32840
33176
|
| `base` | `PossibleURL` | Optional. |
|
|
33177
|
+
| `stack` | `AbsolutePath` | Defaults to `"/"`. |
|
|
33178
|
+
| `stacks` | `AbsolutePath[]` | |
|
|
32841
33179
|
|
|
32842
33180
|
## Returns
|
|
32843
33181
|
|
|
@@ -32849,180 +33187,131 @@ new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : win
|
|
|
32849
33187
|
|
|
32850
33188
|
| Property | Type | Description |
|
|
32851
33189
|
| --- | --- | --- |
|
|
32852
|
-
| `
|
|
33190
|
+
| `stacks` | `readonly AbsolutePath[]` | Root path of each stack, in tab order. A single-stack app has one root. Read only. |
|
|
33191
|
+
| `stack` | `Store<AbsolutePath>` | Root path of the current stack. - Always set. With no `stacks`, it is `"/"`. - It starts at the `stack` given to the constructor (default `"/"`). Without the Navigation API, it stays there. Read only. |
|
|
33192
|
+
| `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`. |
|
|
33193
|
+
| `position` | `NavigationPosition \| undefined` | Where the app is now: the current stack and depth, and the top depth of each stack. Read only. |
|
|
32853
33194
|
|
|
32854
33195
|
## Methods
|
|
32855
33196
|
|
|
32856
|
-
- [NavigationStore.
|
|
32857
|
-
- [NavigationStore.
|
|
32858
|
-
- [NavigationStore.
|
|
33197
|
+
- [NavigationStore.listen()](ui/NavigationStore/listen.md): Start listening to the browser (back, forward and swipe).
|
|
33198
|
+
- [NavigationStore.history()](ui/NavigationStore/history.md): Get the pages in a stack, root first, or every page in every stack.
|
|
33199
|
+
- [NavigationStore.forward()](ui/NavigationStore/forward.md): Go forward to a URL, as a link does.
|
|
33200
|
+
- [NavigationStore.back()](ui/NavigationStore/back.md): Go back to a URL, as a back button does.
|
|
33201
|
+
- [NavigationStore.replace()](ui/NavigationStore/replace.md): Replace the current URL, with no transition.
|
|
32859
33202
|
|
|
32860
33203
|
|
|
32861
33204
|
---
|
|
32862
33205
|
|
|
32863
|
-
# NavigationStore.
|
|
33206
|
+
# NavigationStore.listen()
|
|
32864
33207
|
|
|
32865
33208
|
- Kind: method
|
|
32866
33209
|
- Member of: `NavigationStore`
|
|
32867
33210
|
|
|
32868
|
-
|
|
33211
|
+
Start listening to the browser (back, forward and swipe).
|
|
33212
|
+
- Saves the current stack and depth on the current history entry, if it has none.
|
|
33213
|
+
- `<Navigation>` calls it once, when it mounts.
|
|
32869
33214
|
|
|
32870
33215
|
## Signatures
|
|
32871
33216
|
|
|
32872
33217
|
```ts
|
|
32873
|
-
|
|
33218
|
+
listen(): () => void
|
|
32874
33219
|
```
|
|
32875
33220
|
|
|
32876
33221
|
|
|
32877
33222
|
---
|
|
32878
33223
|
|
|
32879
|
-
# NavigationStore.
|
|
33224
|
+
# NavigationStore.history()
|
|
32880
33225
|
|
|
32881
33226
|
- Kind: method
|
|
32882
33227
|
- Member of: `NavigationStore`
|
|
32883
33228
|
|
|
32884
|
-
|
|
33229
|
+
Get the pages in a stack, root first, or every page in every stack.
|
|
33230
|
+
- Read from the browser history entries up to the current one.
|
|
33231
|
+
- A stack whose root entry is gone (the browser keeps a limited history) still starts with its root.
|
|
33232
|
+
- Without the Navigation API this is always empty.
|
|
32885
33233
|
|
|
32886
33234
|
## Signatures
|
|
32887
33235
|
|
|
32888
33236
|
```ts
|
|
32889
|
-
|
|
33237
|
+
history(stack: AbsolutePath = this.stack.value): AbsolutePath[]
|
|
32890
33238
|
```
|
|
32891
33239
|
|
|
32892
33240
|
|
|
32893
33241
|
---
|
|
32894
33242
|
|
|
32895
|
-
# NavigationStore.
|
|
33243
|
+
# NavigationStore.forward()
|
|
32896
33244
|
|
|
32897
33245
|
- Kind: method
|
|
32898
33246
|
- Member of: `NavigationStore`
|
|
32899
33247
|
|
|
32900
|
-
|
|
32901
|
-
-
|
|
32902
|
-
-
|
|
33248
|
+
Go forward to a URL, as a link does.
|
|
33249
|
+
- The URL is the top page of `stack`: switch to that stack, at the same depth. This is a tab switch.
|
|
33250
|
+
- Else push the URL onto `stack`, one level deeper than its top page.
|
|
33251
|
+
- The URL you are already on: replace it instead.
|
|
33252
|
+
- A change of stack slides by tab order. Else it slides forward.
|
|
32903
33253
|
|
|
32904
33254
|
## Signatures
|
|
32905
33255
|
|
|
32906
33256
|
```ts
|
|
32907
|
-
|
|
33257
|
+
forward(possible: PossibleURL, stack: AbsolutePath = this.stack.value): void
|
|
32908
33258
|
```
|
|
32909
33259
|
|
|
32910
33260
|
|
|
32911
33261
|
---
|
|
32912
33262
|
|
|
32913
|
-
#
|
|
33263
|
+
# NavigationStore.back()
|
|
32914
33264
|
|
|
32915
|
-
- Kind:
|
|
32916
|
-
-
|
|
33265
|
+
- Kind: method
|
|
33266
|
+
- Member of: `NavigationStore`
|
|
32917
33267
|
|
|
32918
|
-
|
|
33268
|
+
Go back to a URL, as a back button does.
|
|
33269
|
+
- 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.
|
|
33270
|
+
- The URL is the root of `stack`: push it at depth 0.
|
|
33271
|
+
- Else push the URL in place of the top page of `stack`.
|
|
33272
|
+
- It works when the app was opened at the current page, so a back button always has somewhere to go.
|
|
32919
33273
|
|
|
32920
33274
|
## Signatures
|
|
32921
33275
|
|
|
32922
33276
|
```ts
|
|
32923
|
-
|
|
32924
|
-
readonly maxCached?: number | undefined;
|
|
32925
|
-
readonly children: ReactNode;
|
|
32926
|
-
}
|
|
33277
|
+
back(possible: PossibleURL, stack: AbsolutePath = this.stack.value): void
|
|
32927
33278
|
```
|
|
32928
33279
|
|
|
32929
|
-
## Properties
|
|
32930
|
-
|
|
32931
|
-
| Property | Type | Description |
|
|
32932
|
-
| --- | --- | --- |
|
|
32933
|
-
| `maxCached` | `number \| undefined` | Number of recently-visited URLs to keep mounted (but hidden) so the entire state of their subtree — scroll position of every scroll container, open/closed toggles, in-progress searches, form inputs, focus — is restored intact when navigating back or forward to them. - Defaults to `10`. Once the limit is reached the least-recently-visited entry is unmounted. - Set to `0` (or less) to disable caching and unmount the subtree as you leave each URL. Read only. Optional. |
|
|
32934
|
-
| `children` | `ReactNode` | The content to render for the current URL and keep alive (hidden) for recently-visited URLs. Read only. |
|
|
32935
|
-
|
|
32936
33280
|
|
|
32937
33281
|
---
|
|
32938
33282
|
|
|
32939
|
-
#
|
|
32940
|
-
|
|
32941
|
-
- Kind: component
|
|
32942
|
-
- Import: `import { RouteCache } from "shelving/ui";`
|
|
32943
|
-
|
|
32944
|
-
Keep-alive page cache keyed by the current URL — drop it into a layout around its scrolling content region.
|
|
32945
|
-
|
|
32946
|
-
- Reads the live URL from the surrounding `<Meta>` context and keeps up to `maxCached` recently-visited
|
|
32947
|
-
pages mounted but hidden (via React's `<Activity>`), so navigating back/forward to a page restores its
|
|
32948
|
-
entire DOM and component state — scroll position, toggles, searches, inputs, focus — untouched.
|
|
32949
|
-
- Pages are kept in a least-recently-used map keyed by `path`; the oldest is unmounted past the limit.
|
|
32950
|
-
- A page that owns other paths with `<RouteConfig path>` stays mounted when the URL changes to one of them.
|
|
32951
|
-
- A page with `<RouteConfig cache={false}>` is dropped as soon as you leave it, so the next visit shows a new page.
|
|
32952
|
-
- Each snapshot is frozen under its own `<MetaContext>`, so the same single `children` element resolves a
|
|
32953
|
-
different page per path and a hidden page never re-renders for someone else's URL.
|
|
32954
|
-
- `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
|
|
32955
|
-
subscriptions/observers/timers pause and resume cleanly as it is hidden and shown.
|
|
32956
|
-
- Because it wraps the scroll container itself (rather than sitting below it inside the router), the
|
|
32957
|
-
scroll position of every cached page is preserved — surrounding chrome (sidebar, drawer state) stays
|
|
32958
|
-
outside the cache, so it is neither duplicated nor remounted on navigation.
|
|
32959
|
-
- When `maxCached <= 0` the page is rendered directly with no caching (it unmounts as you leave it).
|
|
32960
|
-
|
|
32961
|
-
A keep-alive page cache. Drop it into a layout around its scrolling content region: it reads the current URL from the surrounding `<Meta>` context and keeps a handful of recently-visited pages mounted but *hidden* (using React's [`<Activity>`](https://react.dev/reference/react/Activity)), so navigating back or forward to a page restores its entire DOM and component state — scroll position of every scroll container, open/closed toggles, in-progress searches, form inputs, focus — instead of remounting it fresh at the top.
|
|
33283
|
+
# NavigationStore.replace()
|
|
32962
33284
|
|
|
32963
|
-
|
|
32964
|
-
|
|
32965
|
-
**Things to know:**
|
|
32966
|
-
|
|
32967
|
-
- Pages are kept in a least-recently-used map keyed by `path`. Once `maxCached` pages are retained the least-recently-visited one is unmounted (and loses its state). A never-seen or evicted page mounts fresh at the top.
|
|
32968
|
-
- A page can own other paths with `<RouteConfig path>`, for example its tabs (`/dave/{tab}`). A navigation to one of those paths keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide.
|
|
32969
|
-
- A page with `<RouteConfig cache={false}>` is not kept: it unmounts as you leave it, so the next visit starts again. Use it for a form that makes or edits something, so it never shows old input.
|
|
32970
|
-
- The cache key is the path only, not the `?query`. So `/new?from=a` and `/new?from=b` are one page.
|
|
32971
|
-
- Pass `maxCached={0}` (or less) to disable caching entirely — the page renders directly and unmounts as soon as you leave it.
|
|
32972
|
-
- `<Activity mode="hidden">` preserves a hidden page's *state* while unmounting its *effects*, so subscriptions, observers (e.g. infinite-scroll), and timers pause and resume cleanly as the page is hidden and shown.
|
|
32973
|
-
- Each snapshot is frozen under its own `<Meta>` context, so the same single `children` element resolves a different page per path and a hidden page never re-renders for someone else's URL.
|
|
32974
|
-
- For per-page **scroll** to be preserved the cache has to wrap the scroll container itself — which is why it lives in the layout (around the scrollable column) rather than below it inside the router. Surrounding chrome (sidebar, drawer state) stays outside the cache, so it is neither duplicated nor remounted on navigation.
|
|
32975
|
-
|
|
32976
|
-
## Usage
|
|
32977
|
-
|
|
32978
|
-
```tsx
|
|
32979
|
-
import { RouteCache } from "shelving/ui";
|
|
32980
|
-
|
|
32981
|
-
<SidebarLayout sidebar={<Menu/>}>
|
|
32982
|
-
<RouteCache>
|
|
32983
|
-
<Router routes={routes}/>
|
|
32984
|
-
</RouteCache>
|
|
32985
|
-
</SidebarLayout>
|
|
32986
|
-
```
|
|
33285
|
+
- Kind: method
|
|
33286
|
+
- Member of: `NavigationStore`
|
|
32987
33287
|
|
|
33288
|
+
Replace the current URL, with no transition.
|
|
33289
|
+
- The page stays in the same stack, at the same depth, so a cached page stays mounted.
|
|
33290
|
+
- Use it for a page that knows its canonical URL, or for in-page tabs.
|
|
33291
|
+
- 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")`.
|
|
32988
33292
|
|
|
32989
33293
|
## Signatures
|
|
32990
33294
|
|
|
32991
33295
|
```ts
|
|
32992
|
-
|
|
33296
|
+
replace(possible: PossibleURL, stack: AbsolutePath = this.stack.value): void
|
|
32993
33297
|
```
|
|
32994
33298
|
|
|
32995
|
-
## Parameters
|
|
32996
|
-
|
|
32997
|
-
| Param | Type | Description |
|
|
32998
|
-
| --- | --- | --- |
|
|
32999
|
-
| `props` | `RouteCacheProps` | |
|
|
33000
|
-
| `.maxCached` | `number \| undefined` | Number of recently-visited URLs to keep mounted (but hidden) so the entire state of their subtree — scroll position of every scroll container, open/closed toggles, in-progress searches, form inputs, focus — is restored intact when navigating back or forward to them. - Defaults to `10`. Once the limit is reached the least-recently-visited entry is unmounted. - Set to `0` (or less) to disable caching and unmount the subtree as you leave each URL. Read only. Optional. |
|
|
33001
|
-
| `.children` | `ReactNode` | The content to render for the current URL and keep alive (hidden) for recently-visited URLs. Read only. |
|
|
33002
|
-
|
|
33003
|
-
## Returns
|
|
33004
|
-
|
|
33005
|
-
| Type | Description |
|
|
33006
|
-
| --- | --- |
|
|
33007
|
-
| `ReactNode` | |
|
|
33008
|
-
|
|
33009
33299
|
|
|
33010
33300
|
---
|
|
33011
33301
|
|
|
33012
|
-
#
|
|
33302
|
+
# RouteCacheProps
|
|
33013
33303
|
|
|
33014
33304
|
- Kind: interface
|
|
33015
|
-
- Import: `import {
|
|
33305
|
+
- Import: `import { RouteCacheProps } from "shelving/ui";`
|
|
33016
33306
|
|
|
33017
|
-
Props for `<
|
|
33307
|
+
Props for `<RouteCache>`: the `maxCached` size and the content `children` to keep alive for each page in the stacks.
|
|
33018
33308
|
|
|
33019
33309
|
## Signatures
|
|
33020
33310
|
|
|
33021
33311
|
```ts
|
|
33022
33312
|
{
|
|
33023
|
-
readonly
|
|
33024
|
-
readonly
|
|
33025
|
-
readonly children?: ReactNode;
|
|
33313
|
+
readonly maxCached?: number | undefined;
|
|
33314
|
+
readonly children: ReactNode;
|
|
33026
33315
|
}
|
|
33027
33316
|
```
|
|
33028
33317
|
|
|
@@ -33030,82 +33319,111 @@ Props for `<RouteConfig>` — the settings of a page for the surrounding `<Route
|
|
|
33030
33319
|
|
|
33031
33320
|
| Property | Type | Description |
|
|
33032
33321
|
| --- | --- | --- |
|
|
33033
|
-
| `
|
|
33034
|
-
| `
|
|
33035
|
-
| `children` | `ReactNode` | The page content. Read only. Optional. |
|
|
33322
|
+
| `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 is never dropped, even past the limit, so a tab always shows the page you left. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
|
|
33323
|
+
| `children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
|
|
33036
33324
|
|
|
33037
33325
|
|
|
33038
33326
|
---
|
|
33039
33327
|
|
|
33040
|
-
#
|
|
33328
|
+
# RouteCache
|
|
33041
33329
|
|
|
33042
33330
|
- Kind: component
|
|
33043
|
-
- Import: `import {
|
|
33331
|
+
- Import: `import { RouteCache } from "shelving/ui";`
|
|
33332
|
+
|
|
33333
|
+
Keep-alive page cache for the pages in the navigation stacks. Drop it into a layout around its scrolling content region.
|
|
33044
33334
|
|
|
33045
|
-
|
|
33046
|
-
-
|
|
33047
|
-
|
|
33048
|
-
|
|
33049
|
-
-
|
|
33050
|
-
-
|
|
33051
|
-
|
|
33335
|
+
- 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.
|
|
33336
|
+
- 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.
|
|
33337
|
+
- 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.
|
|
33338
|
+
- The top page of each stack is never dropped. Other pages can be dropped past `maxCached`, and show fresh (from the top) when you come back to them.
|
|
33339
|
+
- 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.
|
|
33340
|
+
- `<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.
|
|
33341
|
+
- Without the browser Navigation API (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
|
|
33052
33342
|
|
|
33053
|
-
|
|
33343
|
+
A keep-alive cache for the pages in the navigation stacks. Put it in a layout around the scrolling content region. It keeps each page in the stacks mounted but hidden (with React's [`<Activity>`](https://react.dev/reference/react/Activity)), so when you go back to a page, or switch back to a tab, the page is exactly as you left it: scroll position, toggles, searches, form input and focus.
|
|
33054
33344
|
|
|
33055
|
-
|
|
33056
|
-
- `cache={false}` tells `<RouteCache>` to drop the page when you leave it. The next visit starts again, with no old state. Use it for a form that makes or edits something, so it never shows old input.
|
|
33345
|
+
`<SidebarLayout>` and `<CenteredLayout>` already wrap their content in a `<RouteCache>`. Use it by hand only in a custom layout.
|
|
33057
33346
|
|
|
33058
33347
|
**Things to know:**
|
|
33059
33348
|
|
|
33060
|
-
-
|
|
33061
|
-
-
|
|
33062
|
-
-
|
|
33063
|
-
- The
|
|
33064
|
-
-
|
|
33349
|
+
- Each page is keyed by its stack and its depth in that stack, not by its URL. See `NavigationStore` for how stacks work.
|
|
33350
|
+
- 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.
|
|
33351
|
+
- 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.
|
|
33352
|
+
- The top page of each stack is never dropped, so each tab always shows the page you left. Other pages are dropped (least recently used first) past `maxCached`, and mount fresh when you come back to them.
|
|
33353
|
+
- `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}>`.
|
|
33354
|
+
- The same URL open in two stacks is two separate pages.
|
|
33355
|
+
- 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).
|
|
33356
|
+
- Each kept page is frozen under its own `<Meta>`, so a hidden page never re-renders for another page's URL.
|
|
33357
|
+
- `<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.
|
|
33358
|
+
- The cache must wrap the scroll container itself to keep each page's scroll. So it goes in the layout around the scrolling column, not inside the router. Chrome outside the cache (a sidebar, a tab bar) is not duplicated or remounted.
|
|
33359
|
+
- Put a page `<Transition>` around the `<RouteCache>`, not inside it. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
|
|
33360
|
+
- Without the browser Navigation API, or with `maxCached={0}`, there is no cache: the current page renders directly and unmounts when you leave it.
|
|
33065
33361
|
|
|
33066
33362
|
## Usage
|
|
33067
33363
|
|
|
33068
33364
|
```tsx
|
|
33069
|
-
import {
|
|
33365
|
+
import { HorizontalTransition, RouteCache, Router } from "shelving/ui";
|
|
33070
33366
|
|
|
33071
|
-
|
|
33072
|
-
function ProfilePage({ name, tab }: { name: string; tab?: string }) {
|
|
33367
|
+
function MyLayout() {
|
|
33073
33368
|
return (
|
|
33074
|
-
<
|
|
33075
|
-
<
|
|
33076
|
-
<
|
|
33077
|
-
|
|
33078
|
-
|
|
33369
|
+
<HorizontalTransition>
|
|
33370
|
+
<RouteCache>
|
|
33371
|
+
<main className="scroll">
|
|
33372
|
+
<Router routes={ROUTES}/>
|
|
33373
|
+
</main>
|
|
33374
|
+
</RouteCache>
|
|
33375
|
+
</HorizontalTransition>
|
|
33079
33376
|
);
|
|
33080
33377
|
}
|
|
33378
|
+
```
|
|
33379
|
+
|
|
33380
|
+
Keep fewer pages:
|
|
33381
|
+
|
|
33382
|
+
```tsx
|
|
33383
|
+
<RouteCache maxCached={5}>
|
|
33384
|
+
<Router routes={ROUTES}/>
|
|
33385
|
+
</RouteCache>
|
|
33386
|
+
```
|
|
33081
33387
|
|
|
33082
|
-
|
|
33083
|
-
|
|
33388
|
+
Clear a create form after it saves. Change the `key` of the `<Form>`, so it mounts again with no input:
|
|
33389
|
+
|
|
33390
|
+
```tsx
|
|
33391
|
+
import { useState } from "react";
|
|
33392
|
+
import { Form, requireNavigation } from "shelving/ui";
|
|
33393
|
+
|
|
33394
|
+
function NewPostPage() {
|
|
33395
|
+
const nav = requireNavigation();
|
|
33396
|
+
const [formKey, setFormKey] = useState(0);
|
|
33084
33397
|
return (
|
|
33085
|
-
<
|
|
33086
|
-
|
|
33087
|
-
|
|
33088
|
-
|
|
33089
|
-
|
|
33398
|
+
<Form
|
|
33399
|
+
key={formKey}
|
|
33400
|
+
schema={POST_SCHEMA}
|
|
33401
|
+
onSubmit={async data => {
|
|
33402
|
+
const id = await createPost(data);
|
|
33403
|
+
setFormKey(k => k + 1);
|
|
33404
|
+
nav.forward(`/post/${id}`);
|
|
33405
|
+
}}
|
|
33406
|
+
/>
|
|
33090
33407
|
);
|
|
33091
33408
|
}
|
|
33092
33409
|
```
|
|
33093
33410
|
|
|
33411
|
+
For a plain HTML `<form>`, call `form.reset()` after the submit.
|
|
33412
|
+
|
|
33094
33413
|
|
|
33095
33414
|
## Signatures
|
|
33096
33415
|
|
|
33097
33416
|
```ts
|
|
33098
|
-
|
|
33417
|
+
RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode
|
|
33099
33418
|
```
|
|
33100
33419
|
|
|
33101
33420
|
## Parameters
|
|
33102
33421
|
|
|
33103
33422
|
| Param | Type | Description |
|
|
33104
33423
|
| --- | --- | --- |
|
|
33105
|
-
| `props` | `
|
|
33106
|
-
| `.
|
|
33107
|
-
| `.
|
|
33108
|
-
| `.children` | `ReactNode` | The page content. Read only. Optional. |
|
|
33424
|
+
| `props` | `RouteCacheProps` | |
|
|
33425
|
+
| `.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 is never dropped, even past the limit, so a tab always shows the page you left. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
|
|
33426
|
+
| `.children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
|
|
33109
33427
|
|
|
33110
33428
|
## Returns
|
|
33111
33429
|
|
|
@@ -33114,50 +33432,6 @@ RouteConfig({ path, cache, children }: RouteConfigProps): ReactNode
|
|
|
33114
33432
|
| `ReactNode` | |
|
|
33115
33433
|
|
|
33116
33434
|
|
|
33117
|
-
---
|
|
33118
|
-
|
|
33119
|
-
# RouteState
|
|
33120
|
-
|
|
33121
|
-
- Kind: interface
|
|
33122
|
-
- Import: `import { RouteState } from "shelving/ui";`
|
|
33123
|
-
|
|
33124
|
-
The route state of one page, shared by `<Router>`, `<RouteCache>` and `<RouteConfig>`.
|
|
33125
|
-
- `path` is the template of the paths the page owns, set by `<RouteConfig path>`.
|
|
33126
|
-
- `cache` is `false` when `<RouteCache>` drops the page as you leave it, set by `<RouteConfig cache>`.
|
|
33127
|
-
- `entry` is the page's `<RouteCache>` entry, so `<RouteConfig>` in a top-level page also tells the cache.
|
|
33128
|
-
- `router` marks a state made by `<Router>`, so a nested router does not pass the cache entry on.
|
|
33129
|
-
|
|
33130
|
-
## Signatures
|
|
33131
|
-
|
|
33132
|
-
```ts
|
|
33133
|
-
{
|
|
33134
|
-
path?: AbsolutePath | undefined;
|
|
33135
|
-
cache?: boolean | undefined;
|
|
33136
|
-
readonly entry?: RouteState | undefined;
|
|
33137
|
-
readonly router?: true | undefined;
|
|
33138
|
-
}
|
|
33139
|
-
```
|
|
33140
|
-
|
|
33141
|
-
## Properties
|
|
33142
|
-
|
|
33143
|
-
| Property | Type | Description |
|
|
33144
|
-
| --- | --- | --- |
|
|
33145
|
-
| `path` | `AbsolutePath \| undefined` | Optional. |
|
|
33146
|
-
| `cache` | `boolean \| undefined` | Optional. |
|
|
33147
|
-
| `entry` | `RouteState \| undefined` | Read only. Optional. |
|
|
33148
|
-
| `router` | `true \| undefined` | Read only. Optional. |
|
|
33149
|
-
|
|
33150
|
-
|
|
33151
|
-
---
|
|
33152
|
-
|
|
33153
|
-
# RouteContext
|
|
33154
|
-
|
|
33155
|
-
- Kind: constant
|
|
33156
|
-
- Import: `import { RouteContext } from "shelving/ui";`
|
|
33157
|
-
|
|
33158
|
-
React context holding the `RouteState` of the current page, provided by `<Router>` and `<RouteCache>`.
|
|
33159
|
-
|
|
33160
|
-
|
|
33161
33435
|
---
|
|
33162
33436
|
|
|
33163
33437
|
# RouterProps
|
|
@@ -33197,7 +33471,8 @@ Match the current URL against `routes` and render the matched element.
|
|
|
33197
33471
|
- When `base` is set, the effective path is the URL after stripping the base prefix.
|
|
33198
33472
|
- Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
|
|
33199
33473
|
- 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.
|
|
33200
|
-
-
|
|
33474
|
+
- Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationStore.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
|
|
33475
|
+
- Elsewhere, each path is a new page, so a component route remounts when the path changes.
|
|
33201
33476
|
- Returns `null` when there's no URL in context or the URL is outside the base.
|
|
33202
33477
|
|
|
33203
33478
|
A pure URL matcher: it reads the current URL from the surrounding `<Meta>` context, matches it against a `routes` table, and renders the matched element. It has no client requirements, so it works for SSR, static rendering, and tests with no `<Navigation>` at all — wrap it in `<Navigation>` on the client to get live URL updates.
|
|
@@ -33208,6 +33483,7 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
|
|
|
33208
33483
|
- `<Router>` accepts `PossibleMeta` props (`url`, `base`, etc.) to override the surrounding context — this is how nested routers scope themselves.
|
|
33209
33484
|
- 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`.
|
|
33210
33485
|
- Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
|
|
33486
|
+
- Inside `<Navigation>` with stacks, each page in a stack is a new page: a link mounts a new page, and `NavigationStore.replace()` keeps the same page mounted (it re-renders with the new URL). Elsewhere each path is a new page.
|
|
33211
33487
|
- `<Router>` itself does not cache pages — wrap it in a `<RouteCache>` (or use a layout that already does) to keep recently-visited pages mounted but hidden so back/forward navigation restores their state.
|
|
33212
33488
|
|
|
33213
33489
|
## Usage
|
|
@@ -33322,7 +33598,7 @@ const SIDEBARRED_ROUTES = {
|
|
|
33322
33598
|
|
|
33323
33599
|
### Keeping page state
|
|
33324
33600
|
|
|
33325
|
-
By default a page is unmounted when you navigate away and mounted fresh when you return — so scroll position, open/closed toggles, in-progress searches, form inputs, and focus are all lost, and you land back at the top. Wrap the router (or its scrolling content region) in a `<RouteCache>` to keep recently-visited pages mounted but hidden so their state is
|
|
33601
|
+
By default a page is unmounted when you navigate away and mounted fresh when you return — so scroll position, open/closed toggles, in-progress searches, form inputs, and focus are all lost, and you land back at the top. Wrap the router (or its scrolling content region) in a `<RouteCache>` to keep recently-visited pages mounted but hidden so their state is still there when you go back to them, or switch back to their tab. Shelving's `<SidebarLayout>` and `<CenteredLayout>` already do this for you.
|
|
33326
33602
|
|
|
33327
33603
|
### SSR / static rendering
|
|
33328
33604
|
|
|
@@ -33464,6 +33740,99 @@ Route table mapping `{ path: RouteComponent | redirectPath | ReactElement }` for
|
|
|
33464
33740
|
- [Route](ui/Route.md): Valid route values:
|
|
33465
33741
|
|
|
33466
33742
|
|
|
33743
|
+
---
|
|
33744
|
+
|
|
33745
|
+
# StackButtonProps
|
|
33746
|
+
|
|
33747
|
+
- Kind: interface
|
|
33748
|
+
- Import: `import { StackButtonProps } from "shelving/ui";`
|
|
33749
|
+
- Extends: `Omit<ButtonProps, "href" | "onClick" | "selected">`
|
|
33750
|
+
|
|
33751
|
+
Props for `<StackButton>`: the `stack` it opens, plus the usual `Button` props except `href` and `onClick`.
|
|
33752
|
+
|
|
33753
|
+
## Signatures
|
|
33754
|
+
|
|
33755
|
+
```ts
|
|
33756
|
+
{
|
|
33757
|
+
readonly stack: AbsolutePath;
|
|
33758
|
+
}
|
|
33759
|
+
```
|
|
33760
|
+
|
|
33761
|
+
## Properties
|
|
33762
|
+
|
|
33763
|
+
| Property | Type | Description |
|
|
33764
|
+
| --- | --- | --- |
|
|
33765
|
+
| `stack` | `AbsolutePath` | Root path of the stack this button opens. It must be one of the `stacks` on `<Navigation>`. Read only. |
|
|
33766
|
+
|
|
33767
|
+
|
|
33768
|
+
---
|
|
33769
|
+
|
|
33770
|
+
# StackButton
|
|
33771
|
+
|
|
33772
|
+
- Kind: component
|
|
33773
|
+
- Import: `import { StackButton } from "shelving/ui";`
|
|
33774
|
+
|
|
33775
|
+
Button for one stack in a tab bar.
|
|
33776
|
+
- Tap another stack's button: go to the page you left in that stack. The page slides left or right by tab order.
|
|
33777
|
+
- Tap the current stack's button: go back to its root.
|
|
33778
|
+
- Tap it again at the root: scroll the page to the top.
|
|
33779
|
+
- It is selected while its stack is the current stack.
|
|
33780
|
+
- Without the browser Navigation API (and in a server render) it is a plain link to the stack's root.
|
|
33781
|
+
|
|
33782
|
+
A button for one stack in a tab bar. It acts like a tab button in a phone app.
|
|
33783
|
+
|
|
33784
|
+
**Things to know:**
|
|
33785
|
+
|
|
33786
|
+
- Tap another stack's button: go to the page you left in that stack. The page slides left or right, by tab order.
|
|
33787
|
+
- Tap the current stack's button: go back to the root of the stack. The page slides back.
|
|
33788
|
+
- Tap it again at the root: scroll the page to the top. It scrolls the window, and each visible `<main>` or `[data-scroll]` element.
|
|
33789
|
+
- It is selected (`aria-current`) while its stack is the current stack. On an unstacked page (for example a deep link or a login page), no stack button is selected.
|
|
33790
|
+
- `stack` must be one of the `stacks` on `<Navigation>`.
|
|
33791
|
+
- It takes the usual `<Button>` props, except `href`, `onClick` and `selected`.
|
|
33792
|
+
- 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.
|
|
33793
|
+
- In a server-rendered app, the server renders a link and the browser renders a button, so React warns about a hydration mismatch on the first render. A client-only app (with `<App>`) has no mismatch.
|
|
33794
|
+
|
|
33795
|
+
## Usage
|
|
33796
|
+
|
|
33797
|
+
```tsx
|
|
33798
|
+
import { Navigation, StackButton } from "shelving/ui";
|
|
33799
|
+
import { HomeIcon, SearchIcon, UserIcon } from "./icons.js";
|
|
33800
|
+
|
|
33801
|
+
<Navigation stacks={["/home", "/discover", "/profile"]}>
|
|
33802
|
+
{/* … */}
|
|
33803
|
+
<nav className="tab-bar">
|
|
33804
|
+
<StackButton stack="/home" title="Home"><HomeIcon/></StackButton>
|
|
33805
|
+
<StackButton stack="/discover" title="Discover"><SearchIcon/></StackButton>
|
|
33806
|
+
<StackButton stack="/profile" title="Profile"><UserIcon/></StackButton>
|
|
33807
|
+
</nav>
|
|
33808
|
+
</Navigation>
|
|
33809
|
+
```
|
|
33810
|
+
|
|
33811
|
+
## Styling
|
|
33812
|
+
|
|
33813
|
+
`<StackButton>` renders a `<Button>`, so it has the same styling hooks. See `<Button>`.
|
|
33814
|
+
|
|
33815
|
+
|
|
33816
|
+
## Signatures
|
|
33817
|
+
|
|
33818
|
+
```ts
|
|
33819
|
+
StackButton({ stack, ...props }: StackButtonProps): ReactElement
|
|
33820
|
+
```
|
|
33821
|
+
|
|
33822
|
+
## Parameters
|
|
33823
|
+
|
|
33824
|
+
| Param | Type | Description |
|
|
33825
|
+
| --- | --- | --- |
|
|
33826
|
+
| `props` | `StackButtonProps` | |
|
|
33827
|
+
| `.stack` | `AbsolutePath` | Root path of the stack this button opens. It must be one of the `stacks` on `<Navigation>`. Read only. |
|
|
33828
|
+
|
|
33829
|
+
## Returns
|
|
33830
|
+
|
|
33831
|
+
| Type | Description |
|
|
33832
|
+
| --- | --- |
|
|
33833
|
+
| `ReactElement` | |
|
|
33834
|
+
|
|
33835
|
+
|
|
33467
33836
|
---
|
|
33468
33837
|
|
|
33469
33838
|
# BlockVariants
|
|
@@ -35693,7 +36062,7 @@ A direction-aware `<Transition>` preset that slides its children horizontally
|
|
|
35693
36062
|
**Things to know:**
|
|
35694
36063
|
|
|
35695
36064
|
- Slides right by default and when the type is `"forward"`; slides left when the type is `"back"`.
|
|
35696
|
-
- Inside `<Navigation>` the direction is automatic: a link click
|
|
36065
|
+
- Inside `<Navigation>` the direction is automatic: a link click or `NavigationStore.forward()` sets the `"forward"` type, and a `className="back"` link or `NavigationStore.back()` sets `"back"`. The browser back and forward buttons set the type from the page's place in its stack. `NavigationStore.replace()` has no transition. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
|
|
35697
36066
|
- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
|
|
35698
36067
|
- The old and new content slide a full width apart, so they sit edge to edge and never overlap.
|
|
35699
36068
|
- 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.
|
|
@@ -36103,7 +36472,7 @@ A direction-aware `<Transition>` preset that slides its children vertically —
|
|
|
36103
36472
|
**Things to know:**
|
|
36104
36473
|
|
|
36105
36474
|
- Slides down by default and when the type is `"forward"`; slides up when the type is `"back"`.
|
|
36106
|
-
- Inside `<Navigation>` the direction is automatic: a link click
|
|
36475
|
+
- Inside `<Navigation>` the direction is automatic: a link click or `NavigationStore.forward()` sets the `"forward"` type, and a `className="back"` link or `NavigationStore.back()` sets `"back"`. The browser back and forward buttons set the type from the page's place in its stack. `NavigationStore.replace()` has no transition. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
|
|
36107
36476
|
- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
|
|
36108
36477
|
- The old and new content slide a full height apart, so they sit edge to edge and never overlap.
|
|
36109
36478
|
- 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.
|
|
@@ -37653,6 +38022,7 @@ Combined meta data for a website page — title, URLs, description, CSP, tags, l
|
|
|
37653
38022
|
{
|
|
37654
38023
|
readonly root?: ImmutableURL | undefined;
|
|
37655
38024
|
readonly url?: ImmutableURL | undefined;
|
|
38025
|
+
readonly stack?: AbsolutePath | undefined;
|
|
37656
38026
|
readonly app?: string | undefined;
|
|
37657
38027
|
readonly title?: string | undefined;
|
|
37658
38028
|
readonly description?: string | undefined;
|
|
@@ -37672,7 +38042,8 @@ Combined meta data for a website page — title, URLs, description, CSP, tags, l
|
|
|
37672
38042
|
| Property | Type | Description |
|
|
37673
38043
|
| --- | --- | --- |
|
|
37674
38044
|
| `root` | `ImmutableURL \| undefined` | Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). Read only. Optional. |
|
|
37675
|
-
| `url` | `ImmutableURL \| undefined` | URL of the current page (used
|
|
38045
|
+
| `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. |
|
|
38046
|
+
| `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 `"/"` for an unstacked page. Read only. Optional. |
|
|
37676
38047
|
| `app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
|
|
37677
38048
|
| `title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
|
|
37678
38049
|
| `description` | `string \| undefined` | Description of the current page. Read only. Optional. |
|
|
@@ -37817,7 +38188,8 @@ mergeMeta(meta1: Meta, meta2: PossibleMeta, caller: AnyCaller = mergeMeta): Meta
|
|
|
37817
38188
|
| --- | --- | --- |
|
|
37818
38189
|
| `meta1` | `Meta` | The existing fully-resolved `Meta` to merge into. |
|
|
37819
38190
|
| `.root` | `ImmutableURL \| undefined` | Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). Read only. Optional. |
|
|
37820
|
-
| `.url` | `ImmutableURL \| undefined` | URL of the current page (used
|
|
38191
|
+
| `.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. |
|
|
38192
|
+
| `.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 `"/"` for an unstacked page. Read only. Optional. |
|
|
37821
38193
|
| `.app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
|
|
37822
38194
|
| `.title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
|
|
37823
38195
|
| `.description` | `string \| undefined` | Description of the current page. Read only. Optional. |
|