shelving 1.320.0 → 1.322.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/guides/building-with-shelving.md +230 -1
- package/docs/llms-full.txt +1395 -351
- package/docs/ui/App.md +105 -7
- package/docs/ui/AppLayout.md +85 -0
- package/docs/ui/AppLayoutProps.md +21 -0
- package/docs/ui/BackButton.md +75 -0
- package/docs/ui/BackButtonProps.md +21 -0
- package/docs/ui/Catcher.md +1 -1
- package/docs/ui/ClickableProps.md +0 -2
- package/docs/ui/ErrorPage.md +2 -1
- package/docs/ui/FixedLayout.md +91 -0
- package/docs/ui/FixedLayoutProps.md +13 -0
- package/docs/ui/GapVariants.md +2 -2
- package/docs/ui/Head.md +2 -2
- package/docs/ui/HeightVariant.md +30 -0
- package/docs/ui/HeightVariants.md +26 -0
- package/docs/ui/HorizontalTransition.md +1 -1
- package/docs/ui/LinkClickable.md +0 -1
- package/docs/ui/Meta.md +3 -1
- package/docs/ui/Navigation.md +102 -37
- package/docs/ui/NavigationEntryState.md +22 -0
- package/docs/ui/NavigationPosition.md +24 -0
- package/docs/ui/NavigationPositionContext.md +8 -0
- package/docs/ui/NavigationProps.md +12 -2
- package/docs/ui/NavigationStore/back.md +6 -4
- package/docs/ui/NavigationStore/forward.md +6 -2
- package/docs/ui/NavigationStore/history.md +15 -0
- package/docs/ui/NavigationStore/listen.md +14 -0
- package/docs/ui/NavigationStore/replace.md +15 -0
- package/docs/ui/NavigationStore.md +100 -19
- package/docs/ui/PaddingVariants.md +2 -2
- package/docs/ui/Page.md +12 -8
- package/docs/ui/PageLoader.md +2 -1
- package/docs/ui/RouteCache.md +77 -36
- package/docs/ui/RouteCacheProps.md +3 -3
- package/docs/ui/Router.md +12 -6
- package/docs/ui/Scroll.md +60 -6
- package/docs/ui/ScrollVariants.md +5 -1
- package/docs/ui/SidebarLayout.md +17 -8
- package/docs/ui/SpaceValue.md +1 -0
- package/docs/ui/StackButton.md +64 -0
- package/docs/ui/StackButtonProps.md +21 -0
- package/docs/ui/TreeApp.md +1 -1
- package/docs/ui/VerticalTransition.md +1 -1
- package/docs/ui/getBlockClass.md +1 -1
- package/docs/ui/getGapClass.md +1 -1
- package/docs/ui/getHeightClass.md +64 -0
- package/docs/ui/getPaddingClass.md +1 -1
- package/docs/ui/getScrollClass.md +4 -2
- package/docs/ui/getSpaceClass.md +2 -0
- package/docs/ui/mergeMeta.md +2 -1
- package/docs/ui.md +25 -17
- package/package.json +1 -1
- package/ui/README.md +1 -1
- package/ui/app/App.md +105 -7
- package/ui/button/Clickable.d.ts +1 -3
- package/ui/button/Clickable.js +2 -2
- package/ui/button/Clickable.tsx +0 -4
- package/ui/docs/DocumentationApp.js +4 -1
- package/ui/docs/DocumentationApp.tsx +10 -1
- package/ui/layout/AppLayout.d.ts +21 -0
- package/ui/layout/AppLayout.js +18 -0
- package/ui/layout/AppLayout.md +57 -0
- package/ui/layout/AppLayout.module.css +106 -0
- package/ui/layout/AppLayout.tsx +36 -0
- package/ui/layout/FixedLayout.d.ts +18 -0
- package/ui/layout/FixedLayout.js +15 -0
- package/ui/layout/FixedLayout.md +65 -0
- package/ui/layout/FixedLayout.module.css +55 -0
- package/ui/layout/FixedLayout.tsx +25 -0
- package/ui/layout/SidebarLayout.d.ts +2 -2
- package/ui/layout/SidebarLayout.js +3 -4
- package/ui/layout/SidebarLayout.md +15 -6
- package/ui/layout/SidebarLayout.module.css +11 -16
- package/ui/layout/SidebarLayout.tsx +10 -13
- package/ui/layout/index.d.ts +2 -1
- package/ui/layout/index.js +2 -1
- package/ui/layout/index.tsx +2 -1
- package/ui/misc/Catcher.d.ts +2 -1
- package/ui/misc/Catcher.js +4 -3
- package/ui/misc/Catcher.md +1 -1
- package/ui/misc/Catcher.tsx +5 -4
- package/ui/misc/Loader.d.ts +1 -0
- package/ui/misc/Loader.js +6 -2
- package/ui/misc/Loader.tsx +11 -2
- package/ui/page/Head.d.ts +2 -2
- package/ui/page/Head.js +9 -8
- package/ui/page/Head.tsx +8 -6
- package/ui/page/Page.md +12 -8
- package/ui/router/BackButton.d.ts +22 -0
- package/ui/router/BackButton.js +19 -0
- package/ui/router/BackButton.md +47 -0
- package/ui/router/BackButton.tsx +34 -0
- package/ui/router/Navigation.d.ts +22 -12
- package/ui/router/Navigation.js +67 -51
- package/ui/router/Navigation.md +93 -27
- package/ui/router/Navigation.test.tsx +27 -7
- package/ui/router/Navigation.tsx +90 -53
- package/ui/router/NavigationContext.d.ts +9 -1
- package/ui/router/NavigationContext.js +9 -0
- package/ui/router/NavigationContext.tsx +11 -1
- package/ui/router/NavigationStore.d.ts +126 -19
- package/ui/router/NavigationStore.js +301 -30
- package/ui/router/NavigationStore.md +82 -9
- package/ui/router/NavigationStore.test.ts +384 -0
- package/ui/router/NavigationStore.tsx +347 -30
- package/ui/router/RouteCache.d.ts +16 -22
- package/ui/router/RouteCache.js +37 -47
- package/ui/router/RouteCache.md +63 -16
- package/ui/router/RouteCache.tsx +56 -62
- package/ui/router/Router.d.ts +2 -1
- package/ui/router/Router.js +9 -14
- package/ui/router/Router.md +10 -5
- package/ui/router/Router.tsx +9 -20
- package/ui/router/StackButton.d.ts +24 -0
- package/ui/router/StackButton.js +35 -0
- package/ui/router/StackButton.md +34 -0
- package/ui/router/StackButton.tsx +44 -0
- package/ui/router/index.d.ts +2 -2
- package/ui/router/index.js +2 -2
- package/ui/router/index.ts +2 -2
- package/ui/style/Block.d.ts +3 -2
- package/ui/style/Block.js +3 -2
- package/ui/style/Block.tsx +4 -2
- package/ui/style/Gap.d.ts +1 -1
- package/ui/style/Gap.tsx +1 -1
- package/ui/style/Height.d.ts +32 -0
- package/ui/style/Height.js +13 -0
- package/ui/style/Height.module.css +88 -0
- package/ui/style/Height.tsx +61 -0
- package/ui/style/Padding.d.ts +1 -1
- package/ui/style/Padding.tsx +1 -1
- package/ui/style/Scroll.d.ts +9 -5
- package/ui/style/Scroll.js +6 -4
- package/ui/style/Scroll.md +59 -0
- package/ui/style/Scroll.module.css +13 -1
- package/ui/style/Scroll.tsx +13 -5
- package/ui/style/Space.d.ts +1 -1
- package/ui/style/Space.module.css +12 -0
- package/ui/style/Space.tsx +1 -0
- package/ui/style/getHeightClass.md +30 -0
- package/ui/style/getSpaceClass.md +2 -0
- package/ui/style/index.d.ts +1 -0
- package/ui/style/index.js +1 -0
- package/ui/style/index.ts +1 -0
- package/ui/transition/HorizontalTransition.md +1 -1
- package/ui/transition/VerticalTransition.md +1 -1
- package/ui/tree/TreeApp.d.ts +1 -1
- package/ui/tree/TreeApp.js +5 -2
- package/ui/tree/TreeApp.tsx +11 -2
- package/ui/util/meta.d.ts +4 -1
- package/ui/util/meta.ts +4 -1
- package/docs/ui/CenteredLayout.md +0 -66
- package/docs/ui/CenteredLayoutProps.md +0 -14
- package/docs/ui/NavigationStore/redirect.md +0 -12
- package/docs/ui/RouteConfig.md +0 -75
- package/docs/ui/RouteConfigProps.md +0 -24
- package/docs/ui/RouteContext.md +0 -6
- package/docs/ui/RouteState.md +0 -30
- package/ui/layout/CenteredLayout.d.ts +0 -21
- package/ui/layout/CenteredLayout.js +0 -28
- package/ui/layout/CenteredLayout.md +0 -41
- package/ui/layout/CenteredLayout.module.css +0 -72
- package/ui/layout/CenteredLayout.tsx +0 -56
- package/ui/router/RouteConfig.d.ts +0 -28
- package/ui/router/RouteConfig.js +0 -30
- package/ui/router/RouteConfig.md +0 -42
- package/ui/router/RouteConfig.tsx +0 -44
- package/ui/router/RouteContext.d.ts +0 -22
- package/ui/router/RouteContext.js +0 -8
- package/ui/router/RouteContext.tsx +0 -26
package/docs/llms-full.txt
CHANGED
|
@@ -481,7 +481,7 @@ Mirrors `shared/config/` folder-for-folder. Where `shared/config/<area>/` define
|
|
|
481
481
|
- **`app/index.html`** — production HTML shell. References `./style.css` and `./index.tsx`; the bundler resolves and bundles from here.
|
|
482
482
|
- **`app/start.html`** — identical shell for local dev, minus any third-party scripts you don't want running locally.
|
|
483
483
|
- **`app/index.tsx`** — mounts `<App />` into `#root`. Nothing else.
|
|
484
|
-
- **`app/App.tsx`** — the composition root of the client: the `ROUTES` table, the app-level context value, and the provider tree (Shelving's `App`, `Navigation`, `
|
|
484
|
+
- **`app/App.tsx`** — the composition root of the client: the `ROUTES` table, the app-level context value, and the provider tree (Shelving's `App`, `Navigation`, `Dialogs`, `Notices`), and the app shell (layout picker, layout, cache and router — see [The app shell](#the-app-shell)). Every page component is registered here.
|
|
485
485
|
- **`app/start.ts`** — local dev server: `Bun.serve` on the port derived from `APP_URL`, serving the HTML shell for all SPA routes and static files (e.g. `/img/*` mapped to `shared/img/`).
|
|
486
486
|
|
|
487
487
|
### Routing
|
|
@@ -548,6 +548,197 @@ The client has one local database (`DB`, a plain `MemoryDBProvider`). API result
|
|
|
548
548
|
- **No inline `style` props, ever.** All styling lives in `.module.css` files named after their component (`OrderPage.module.css` for `OrderPage.tsx`).
|
|
549
549
|
- Reusable components expose styling options as **variants**: boolean props mapped to class names in the CSS module. Pages compose existing `shelving/ui` primitives (`Button`, `Notice`, `Page`, `Row`, layouts, transitions) rather than styling raw elements.
|
|
550
550
|
|
|
551
|
+
### The app shell
|
|
552
|
+
|
|
553
|
+
The app shell is everything around the pages: the layout, the scroll box, the page cache, the page transition and the tab stacks. **Every part is opt-in.** Start with the smallest shell that works, and add a part only when the app needs it. Each recipe below says what to add and where.
|
|
554
|
+
|
|
555
|
+
The full nesting, from the outside in, is: contexts, then the app-level catcher, then your layout picker, then the layout, then the transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`, then the page. Leave out the parts you do not need, but keep the order. "Composing an app" on `<App>` has the full rules and a complete `App.tsx`.
|
|
556
|
+
|
|
557
|
+
#### A simple site: no layout
|
|
558
|
+
|
|
559
|
+
With no layout, the document body scrolls. This is fine for a site or a small app.
|
|
560
|
+
|
|
561
|
+
```tsx
|
|
562
|
+
<App app="My site" root="https://example.com/">
|
|
563
|
+
<Navigation>
|
|
564
|
+
<PageLoader>
|
|
565
|
+
<Router routes={ROUTES} />
|
|
566
|
+
</PageLoader>
|
|
567
|
+
</Navigation>
|
|
568
|
+
</App>
|
|
569
|
+
```
|
|
570
|
+
|
|
571
|
+
#### A full-screen app with its own scroll box
|
|
572
|
+
|
|
573
|
+
Use `<FixedLayout>`. It locks the body and gives one full-screen content slot inside the safe areas. It does not scroll, so put a `<Scroll vertical cover>` in it. `cover` makes the scroll box fill the slot.
|
|
574
|
+
|
|
575
|
+
```tsx
|
|
576
|
+
<FixedLayout>
|
|
577
|
+
<Scroll vertical cover>
|
|
578
|
+
<PageLoader>
|
|
579
|
+
<Router routes={ROUTES} />
|
|
580
|
+
</PageLoader>
|
|
581
|
+
</Scroll>
|
|
582
|
+
</FixedLayout>
|
|
583
|
+
```
|
|
584
|
+
|
|
585
|
+
#### Content in the middle of the screen
|
|
586
|
+
|
|
587
|
+
A layout never centres. The page centres its own content with `<Block height="full" middle>`. The block is at least as tall as the scroll box, so short content sits in the middle, and tall content starts at the top and scrolls. Use `top` or `bottom` to put it at an edge. This is how to make a log-in page or an error page.
|
|
588
|
+
|
|
589
|
+
```tsx
|
|
590
|
+
<Page title="Log in">
|
|
591
|
+
<Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
|
|
592
|
+
<LoginForm />
|
|
593
|
+
</Block>
|
|
594
|
+
</Page>
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
#### A sidebar
|
|
598
|
+
|
|
599
|
+
Use `<SidebarLayout sidebar>`. On a narrow screen the sidebar becomes a drawer with a menu button. Fill its content slot the same way as any other layout.
|
|
600
|
+
|
|
601
|
+
```tsx
|
|
602
|
+
<SidebarLayout sidebar={<Menu />}>
|
|
603
|
+
<Scroll vertical cover>
|
|
604
|
+
<Router routes={ROUTES} />
|
|
605
|
+
</Scroll>
|
|
606
|
+
</SidebarLayout>
|
|
607
|
+
```
|
|
608
|
+
|
|
609
|
+
#### A tab bar
|
|
610
|
+
|
|
611
|
+
Use `<AppLayout nav>`. It puts the content slot above a bar, at every screen size. The bar has its own view-transition group, so it stays still while pages slide. Set `nav={false}` to hide the bar.
|
|
612
|
+
|
|
613
|
+
```tsx
|
|
614
|
+
<AppLayout nav={<StackBar />}>
|
|
615
|
+
<Scroll vertical cover>
|
|
616
|
+
<Router routes={ROUTES} />
|
|
617
|
+
</Scroll>
|
|
618
|
+
</AppLayout>
|
|
619
|
+
```
|
|
620
|
+
|
|
621
|
+
#### A custom layout with a custom scroll area
|
|
622
|
+
|
|
623
|
+
Make your own frame when no layout fits, for example a header that stays on screen above the content. A frame does three things:
|
|
624
|
+
|
|
625
|
+
1. It locks the document, so only its own boxes scroll.
|
|
626
|
+
2. It fills the screen with `position: absolute; inset: 0`, so it works inside a mount element such as `<div id="root">`.
|
|
627
|
+
3. It gives a content slot with `position: relative`, which a `<Scroll vertical cover>` fills.
|
|
628
|
+
|
|
629
|
+
A frame does not scroll, centre, cache or transition. The app puts those in the slot.
|
|
630
|
+
|
|
631
|
+
```tsx
|
|
632
|
+
export function TopBarLayout({ bar, children }: TopBarLayoutProps): ReactElement {
|
|
633
|
+
return (
|
|
634
|
+
<div className={LAYOUT_CLASS}>
|
|
635
|
+
<header className={BAR_CLASS}>{bar}</header>
|
|
636
|
+
<main className={CONTENT_CLASS}>{children}</main>
|
|
637
|
+
</div>
|
|
638
|
+
);
|
|
639
|
+
}
|
|
640
|
+
```
|
|
641
|
+
|
|
642
|
+
```css
|
|
643
|
+
@layer components {
|
|
644
|
+
html:has(.layout) { height: 100dvh; overflow: hidden; }
|
|
645
|
+
body:has(.layout) { position: fixed; inset: 0; margin: 0; }
|
|
646
|
+
.layout { position: absolute; inset: 0; display: flex; flex-direction: column; }
|
|
647
|
+
.content { position: relative; flex: 1; min-height: 0; overflow: hidden; }
|
|
648
|
+
}
|
|
649
|
+
```
|
|
650
|
+
|
|
651
|
+
`modules/ui/layout/AppLayout.module.css` in Shelving is a full example, with the safe areas.
|
|
652
|
+
|
|
653
|
+
#### Other scroll boxes
|
|
654
|
+
|
|
655
|
+
`<Scroll>` is not only for pages. Use `<Scroll horizontal>` for a wide table, or `<Scroll vertical cover reverse>` for a chat that starts at the end and stays there as messages arrive. See `<Scroll>`.
|
|
656
|
+
|
|
657
|
+
#### Keep page state when you go back
|
|
658
|
+
|
|
659
|
+
By default a page unmounts when you leave it, so its scroll position, toggles and form input are lost. Add `<RouteCache>` to keep recent pages mounted but hidden. Put the scroll box **inside** the cache, so each page keeps its own scroll position.
|
|
660
|
+
|
|
661
|
+
```tsx
|
|
662
|
+
<RouteCache>
|
|
663
|
+
<Scroll vertical cover>
|
|
664
|
+
<PageLoader>
|
|
665
|
+
<Router routes={ROUTES} />
|
|
666
|
+
</PageLoader>
|
|
667
|
+
</Scroll>
|
|
668
|
+
</RouteCache>
|
|
669
|
+
```
|
|
670
|
+
|
|
671
|
+
Keep the layout **outside** the cache, so the chrome has one copy and keeps its own state. Clear a create form after it saves, because the cache keeps its input. See `<RouteCache>`.
|
|
672
|
+
|
|
673
|
+
#### Page transitions
|
|
674
|
+
|
|
675
|
+
Put a page transition, for example `<HorizontalTransition>`, **around** `<RouteCache>` and inside the layout. The pages slide and the chrome stays still. Do not put a transition inside the cache around each page: Safari loses the exit animation.
|
|
676
|
+
|
|
677
|
+
```tsx
|
|
678
|
+
<AppLayout nav={<StackBar />}>
|
|
679
|
+
<HorizontalTransition>
|
|
680
|
+
<RouteCache>
|
|
681
|
+
<Scroll vertical cover>…</Scroll>
|
|
682
|
+
</RouteCache>
|
|
683
|
+
</HorizontalTransition>
|
|
684
|
+
</AppLayout>
|
|
685
|
+
```
|
|
686
|
+
|
|
687
|
+
#### Tab stacks, like a phone app
|
|
688
|
+
|
|
689
|
+
Each tab keeps its own stack of pages, and its back button goes back within that tab. You need four parts:
|
|
690
|
+
|
|
691
|
+
1. Set `stacks` on `<Navigation>` to the root path of each tab, in tab order, and `stack` to the tab the app opens in: `<Navigation stacks={["/home", "/discover", "/profile"]} stack="/home">`.
|
|
692
|
+
2. Make a tab bar of `<StackButton stack="/home">` buttons, and put it in `<AppLayout nav>`.
|
|
693
|
+
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.
|
|
694
|
+
4. Use `<RouteCache>`, so each tab shows the page you left it on.
|
|
695
|
+
|
|
696
|
+
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>`, `NavigationStore`, `<StackButton>` and `<BackButton>`.
|
|
697
|
+
|
|
698
|
+
#### Hide the tab bar on some pages
|
|
699
|
+
|
|
700
|
+
All pages in one stack share one layout, because they share one cache. So a page cannot change the layout itself. Pick the layout props from the URL in your layout picker, above the router:
|
|
701
|
+
|
|
702
|
+
```tsx
|
|
703
|
+
function Shell() {
|
|
704
|
+
const { path } = requireMetaURL();
|
|
705
|
+
return (
|
|
706
|
+
<AppLayout nav={path.startsWith("/squad/") ? false : <StackBar />}>
|
|
707
|
+
<Content />
|
|
708
|
+
</AppLayout>
|
|
709
|
+
);
|
|
710
|
+
}
|
|
711
|
+
```
|
|
712
|
+
|
|
713
|
+
#### Pick a layout by state or path
|
|
714
|
+
|
|
715
|
+
The layout picker is plain React, so any rule works: the session, the path, or both. Swap to another layout only between sections the user does not move back and forth in, such as log-in and the main app, because a new layout mounts a new cache.
|
|
716
|
+
|
|
717
|
+
```tsx
|
|
718
|
+
function Shell({ signedIn }: { signedIn: boolean }) {
|
|
719
|
+
if (!signedIn) return <FixedLayout><Content routes={LOGIN_ROUTES} /></FixedLayout>;
|
|
720
|
+
return <AppLayout nav={<StackBar />}><Content routes={ROUTES} /></AppLayout>;
|
|
721
|
+
}
|
|
722
|
+
```
|
|
723
|
+
|
|
724
|
+
Put the slot content (transition, cache, scroll box, loader and router) in one small `Content` component, and reuse it in each layout.
|
|
725
|
+
|
|
726
|
+
#### Errors and loading
|
|
727
|
+
|
|
728
|
+
A page, an error page or a loading state never renders a layout. `<PageLoader>` catches errors and shows a loading state inside the scroll box, in the layout the user already sees. An app-level `<Catcher>` sits outside every layout, so it picks one itself:
|
|
729
|
+
|
|
730
|
+
```tsx
|
|
731
|
+
function AppError({ reason }: ErrorProps) {
|
|
732
|
+
return (
|
|
733
|
+
<FixedLayout>
|
|
734
|
+
<Scroll vertical cover>
|
|
735
|
+
<ErrorPage reason={reason} />
|
|
736
|
+
</Scroll>
|
|
737
|
+
</FixedLayout>
|
|
738
|
+
);
|
|
739
|
+
}
|
|
740
|
+
```
|
|
741
|
+
|
|
551
742
|
## Boundaries
|
|
552
743
|
|
|
553
744
|
Three mechanisms keep the packages honest:
|
|
@@ -854,6 +1045,44 @@ If every file in that list is in the right place, the client and server share on
|
|
|
854
1045
|
|
|
855
1046
|
## Upgrade notes
|
|
856
1047
|
|
|
1048
|
+
### Tab stacks in `<Navigation>`
|
|
1049
|
+
|
|
1050
|
+
`<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:
|
|
1051
|
+
|
|
1052
|
+
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.
|
|
1053
|
+
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).
|
|
1054
|
+
3. **Remove `<RouteConfig>`.** `<RouteConfig>` and `RouteContext` are removed.
|
|
1055
|
+
- `<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.
|
|
1056
|
+
- `<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.
|
|
1057
|
+
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.
|
|
1058
|
+
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.
|
|
1059
|
+
6. **Use the new buttons (optional).**
|
|
1060
|
+
- `<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.
|
|
1061
|
+
- `<BackButton href="/home"/>` goes back to the page before this one in the current tab, or to `href` when there is none.
|
|
1062
|
+
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>`.
|
|
1063
|
+
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}`.
|
|
1064
|
+
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.
|
|
1065
|
+
|
|
1066
|
+
What changes for users:
|
|
1067
|
+
|
|
1068
|
+
- Each tab remembers the page you left it on, and its back button goes back within that tab.
|
|
1069
|
+
- The browser back button walks the history as before, across tabs. The page slides the right way.
|
|
1070
|
+
- When you go back from a page, it leaves the cache. So the browser forward button then shows that page fresh, from the top.
|
|
1071
|
+
|
|
1072
|
+
See `<Navigation>`, `NavigationStore`, `<RouteCache>`, `<StackButton>` and `<BackButton>` for the full details.
|
|
1073
|
+
|
|
1074
|
+
### Layouts are frames
|
|
1075
|
+
|
|
1076
|
+
Layouts no longer include a `<RouteCache>` or a scroll box. Each layout is a frame with a content slot, so the app chooses the scroll box, the transition and the cache. `<CenteredLayout>` is now `<FixedLayout>`, and it no longer centres or scrolls. `<ErrorPage>` and the `<PageLoader>` fallback no longer render a layout. To upgrade an app:
|
|
1077
|
+
|
|
1078
|
+
1. **Fill the `<SidebarLayout>` slot.** Put `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then your `<Router>` in it. Without a scroll box, the content does not scroll. Put a page transition around the `<RouteCache>`, inside the layout, so the sidebar stays still.
|
|
1079
|
+
2. **Change `<CenteredLayout>` to `<FixedLayout>`.** Put a `<Scroll vertical cover>` in it, then your page or `<Router>`. Move the centring into the page: `<Block height="full" middle width="narrow" padding="xxlarge" indent="normal">`. The new `height` and `middle` block variants put the content in the middle of the screen, and it still scrolls when it is taller. The `width`, `padding` and `indent` props and the `--centered-layout-*` hooks are removed; the background and colour hooks are now `--fixed-layout-background` and `--fixed-layout-color`.
|
|
1080
|
+
3. **Do not render a layout in a page.** A page, an error page or a loading state never renders a layout. Pick the layout once, above the router. An app-level catcher sits outside every layout, so give it one: `<Catcher as={AppError}>`, where `AppError` renders `<ErrorPage>` in a `<FixedLayout>` and a `<Scroll vertical cover>`.
|
|
1081
|
+
4. **Use `<AppLayout>` for a tab bar (optional).** `<AppLayout nav={<StackBar />}>` puts a bar of `<StackButton>`s below the content slot. Set `nav={false}` to hide it for some pages.
|
|
1082
|
+
5. **Rename the scroll focus hook.** `--scrollable-focus-border` is now `--scroll-focus-border`.
|
|
1083
|
+
|
|
1084
|
+
See "Composing an app" on `<App>` for the full nesting rules and an example `App.tsx`, and [The app shell](#the-app-shell) above for each part as a recipe.
|
|
1085
|
+
|
|
857
1086
|
### From `CacheDBProvider` to `HydratingAPIProvider`
|
|
858
1087
|
|
|
859
1088
|
`CacheDBProvider` and the paging in `QueryStore` are removed. To upgrade an app:
|
|
@@ -20036,7 +20265,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20036
20265
|
|
|
20037
20266
|
**Content.** Block-level structure starts with `<Card>`, `<Section>`, and the `<Heading>` / `<Title>` family, with `<Table>`, `<List>`, and `<Figure>` for specific shapes; wrap longform copy in `<Prose>`. Inline pieces — `<Link>`, `<Code>`, `<Strong>`, `<Mark>` — live inside that block content. To render a Markdown string as components, use `<Markup>`.
|
|
20038
20267
|
|
|
20039
|
-
**Structure.** Mount a client app with `<App>`, or render a full server document with `<HTML>` and `<Page>`. Arrange the screen with `<
|
|
20268
|
+
**Structure.** Mount a client app with `<App>`, or render a full server document with `<HTML>` and `<Page>`. Arrange the screen with `<AppLayout>`, `<SidebarLayout>` or `<FixedLayout>`, and drive URLs with `<Navigation>` and `<Router>`. A layout is a frame: it sits above the router, and the app fills its content slot with `<RouteCache>` and `<Scroll>`. See "Composing an app" on `<App>`.
|
|
20040
20269
|
|
|
20041
20270
|
**Interaction.** Forms start at `<Form>`, which wires `<Field>` and the typed inputs to a `FormStore`; `<Button>` is the standalone action. Overlays are `<Dialog>` and `<Modal>`; navigation menus are `<Menu>` and `<MenuItem>`; transient feedback is `<Notice>` (and the global `<Notices>` list); animate enter/leave with `<Transition>`.
|
|
20042
20271
|
|
|
@@ -20150,14 +20379,15 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20150
20379
|
- [DataSchemaInput](ui/DataSchemaInput.md): Show a DataInput for a nested DataSchema.
|
|
20151
20380
|
- [SchemaField](ui/SchemaField.md): Show the appropriate input for a schema, wrapped in a <Field> with its label and message.
|
|
20152
20381
|
- [SelectInput](ui/SelectInput.md): Dropdown input bound to a string value, rendered as a <select> of the provided options.
|
|
20153
|
-
- [
|
|
20154
|
-
- [
|
|
20382
|
+
- [AppLayout](ui/AppLayout.md): Layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app.
|
|
20383
|
+
- [FixedLayout](ui/FixedLayout.md): Layout with no chrome: the whole screen is one content slot.
|
|
20384
|
+
- [SidebarLayout](ui/SidebarLayout.md): Layout with a fixed-width side column (typically navigation) next to a content slot.
|
|
20155
20385
|
- [Menu](ui/Menu.md): A <menu> list of <MenuItem> children.
|
|
20156
20386
|
- [MenuItem](ui/MenuItem.md): A <li> containing an <a> link, plus optional submenu content shown when this item is "proud".
|
|
20157
20387
|
- [Catcher](ui/Catcher.md): React error boundary that renders a fallback component when any descendant throws.
|
|
20158
20388
|
- [ErrorNotice](ui/ErrorNotice.md): Render a caught error as an inline <Notice> with a retry button.
|
|
20159
20389
|
- [PageCatcher](ui/PageCatcher.md): Error boundary for a whole page that renders a full <ErrorPage> fallback on error.
|
|
20160
|
-
- [ErrorPage](ui/ErrorPage.md): Render a caught error as a
|
|
20390
|
+
- [ErrorPage](ui/ErrorPage.md): Render a caught error as a <Page> with an <ErrorNotice> in a narrow column, centred in the middle of the screen.
|
|
20161
20391
|
- [Icon](ui/Icon.md): Render the icon for a given status, coloured to match.
|
|
20162
20392
|
- [Loader](ui/Loader.md): Load a component.
|
|
20163
20393
|
- [PageLoader](ui/PageLoader.md): Load a page.
|
|
@@ -20167,13 +20397,14 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20167
20397
|
- [Empty](ui/Empty.md): Message for a list with nothing in it: centred, grey content with space around it.
|
|
20168
20398
|
- [Notice](ui/Notice.md): Block-level status callout with an icon and message, used to highlight feedback.
|
|
20169
20399
|
- [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
|
|
20400
|
+
- [Head](ui/Head.md): Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
|
|
20171
20401
|
- [HTML](ui/HTML.md): Render the full <html> document shell wrapping <head> and <body>.
|
|
20172
20402
|
- [Page](ui/Page.md): Wrap a single page (or screen) within an app, applying its meta and head tags.
|
|
20173
|
-
- [
|
|
20174
|
-
- [
|
|
20175
|
-
- [
|
|
20403
|
+
- [BackButton](ui/BackButton.md): Back button for the current stack.
|
|
20404
|
+
- [Navigation](ui/Navigation.md): Top-level navigation provider, with one stack of pages for each tab.
|
|
20405
|
+
- [RouteCache](ui/RouteCache.md): 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.
|
|
20176
20406
|
- [Router](ui/Router.md): Match the current URL against routes and render the matched element.
|
|
20407
|
+
- [StackButton](ui/StackButton.md): Button for one stack in a tab bar.
|
|
20177
20408
|
- [Scroll](ui/Scroll.md): Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
|
|
20178
20409
|
- [Cell](ui/Cell.md): Table cell.
|
|
20179
20410
|
- [Table](ui/Table.md): Table block — rendered as <table>.
|
|
@@ -20244,10 +20475,11 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20244
20475
|
- [getFlexClass()](ui/getFlexClass.md): Get the flex layout class for a component from its flex variant props.
|
|
20245
20476
|
- [getGapClass()](ui/getGapClass.md): Get the gap class for a component from its gap variant prop.
|
|
20246
20477
|
- [getGridClass()](ui/getGridClass.md): Get the grid layout class for a component from its grid variant props.
|
|
20478
|
+
- [getHeightClass()](ui/getHeightClass.md): Get the height class for a component from its height, top, middle and bottom variant props.
|
|
20247
20479
|
- [getIndentClass()](ui/getIndentClass.md): Get the inline-padding ("indent") class for a component from its indent variant prop.
|
|
20248
20480
|
- [getPaddingClass()](ui/getPaddingClass.md): Get the block-padding class for a component from its padding variant prop.
|
|
20249
20481
|
- [getRadiusClass()](ui/getRadiusClass.md): Get the corner-radius class for a component from its radius variant prop.
|
|
20250
|
-
- [getScrollClass()](ui/getScrollClass.md): Get the scroll class for a component from its horizontal
|
|
20482
|
+
- [getScrollClass()](ui/getScrollClass.md): Get the scroll class for a component from its horizontal, vertical, cover and reverse variant props.
|
|
20251
20483
|
- [getShadowClass()](ui/getShadowClass.md): Get the drop-shadow class for a component from its shadow variant prop.
|
|
20252
20484
|
- [getSpaceClass()](ui/getSpaceClass.md): Get the block spacing class for a component from its space="" variant prop.
|
|
20253
20485
|
- [getStatusClass()](ui/getStatusClass.md): Get the status tint class for a component from its status variant prop.
|
|
@@ -20295,7 +20527,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20295
20527
|
- [FormStore](ui/FormStore.md): Reactive store holding the current (possibly partial and invalid) value of a form, plus its field messages.
|
|
20296
20528
|
- [NoticesStore](ui/NoticesStore.md): Store holding the live list of NoticeStore notices currently shown.
|
|
20297
20529
|
- [NoticeStore](ui/NoticeStore.md): Store holding a single notice's content and status, owned by a NoticesStore.
|
|
20298
|
-
- [NavigationStore](ui/NavigationStore.md): Store
|
|
20530
|
+
- [NavigationStore](ui/NavigationStore.md): Store that holds the current navigation URL, drives browser history, and keeps a stack of pages for each tab.
|
|
20299
20531
|
|
|
20300
20532
|
## Interfaces
|
|
20301
20533
|
|
|
@@ -20409,7 +20641,8 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20409
20641
|
- [SelectProps](ui/SelectProps.md): Props for SelectInput, a dropdown <select> bound to a string value.
|
|
20410
20642
|
- [TextareaInputProps](ui/TextareaInputProps.md): Props for TextareaInput, a multiline text input bound to a string value.
|
|
20411
20643
|
- [TextInputProps](ui/TextInputProps.md): Props for TextInput, a single-line text input bound to a string value.
|
|
20412
|
-
- [
|
|
20644
|
+
- [AppLayoutProps](ui/AppLayoutProps.md): Props for <AppLayout>: the nav bar content and the content slot children.
|
|
20645
|
+
- [FixedLayoutProps](ui/FixedLayoutProps.md): Props for <FixedLayout>: the content slot children.
|
|
20413
20646
|
- [SidebarLayoutProps](ui/SidebarLayoutProps.md): Props for <SidebarLayout> — the sidebar column content, main children, and a right placement flag.
|
|
20414
20647
|
- [MenuProps](ui/MenuProps.md): Props for <Menu> — optional <MenuItem> children.
|
|
20415
20648
|
- [MenuItemProps](ui/MenuItemProps.md): Props for <MenuItem> — <Clickable> props plus children whose first node is the label and the rest the submenu.
|
|
@@ -20429,21 +20662,24 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20429
20662
|
- [NoticesProps](ui/NoticesProps.md): Props for <Notices> — the place for the list, and flex styling variants for the notices container.
|
|
20430
20663
|
- [HTMLProps](ui/HTMLProps.md): Props for <HTML> — initial Meta (language/root/app) plus the page children.
|
|
20431
20664
|
- [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
|
|
20432
|
-
- [
|
|
20433
|
-
- [
|
|
20434
|
-
- [
|
|
20435
|
-
- [
|
|
20665
|
+
- [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.
|
|
20666
|
+
- [NavigationProps](ui/NavigationProps.md): Props for <Navigation>: the initial Meta (url, root and stack), the stacks, and optional children.
|
|
20667
|
+
- [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationStore saves on each browser history entry.
|
|
20668
|
+
- [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.
|
|
20669
|
+
- [RouteCacheProps](ui/RouteCacheProps.md): Props for <RouteCache>: the maxCached size and the content children to keep alive for each page in the stacks.
|
|
20436
20670
|
- [RouterProps](ui/RouterProps.md): Props for <Router> — the routes to match against plus an optional fallback.
|
|
20671
|
+
- [StackButtonProps](ui/StackButtonProps.md): Props for <StackButton>: the stack it opens, plus the usual Button props except href and onClick.
|
|
20437
20672
|
- [BlockVariants](ui/BlockVariants.md): Variants for block level elements.
|
|
20438
20673
|
- [ColorVariants](ui/ColorVariants.md): Variant props for colouring an element, e.g. color="purple".
|
|
20439
20674
|
- [DurationVariants](ui/DurationVariants.md): Variant props for the transition duration of an element, e.g. duration="fast".
|
|
20440
20675
|
- [FlexVariants](ui/FlexVariants.md): Variant props for flex layout — opt-in modifiers any component can mix in via getFlexClass().
|
|
20441
20676
|
- [GapVariants](ui/GapVariants.md): Variant props for the gap between a component's children, e.g. gap="large".
|
|
20442
20677
|
- [GridVariants](ui/GridVariants.md): Variant props for grid layout, e.g. columns={3} gap="normal".
|
|
20678
|
+
- [HeightVariants](ui/HeightVariants.md): Variant props that set a component's height, and where its content sits inside that height, e.g. height="full" middle.
|
|
20443
20679
|
- [IndentVariants](ui/IndentVariants.md): Variant props for the inline-padding ("indent", left + right) of a component, e.g. indent="normal".
|
|
20444
20680
|
- [PaddingVariants](ui/PaddingVariants.md): Variant props for the block-padding (top + bottom) of a component, e.g. padding="large".
|
|
20445
20681
|
- [RadiusVariants](ui/RadiusVariants.md): Variant props for the corner radius of an element, e.g. radius="large".
|
|
20446
|
-
- [ScrollVariants](ui/ScrollVariants.md): Variant props
|
|
20682
|
+
- [ScrollVariants](ui/ScrollVariants.md): Variant props for a scroll region: which axes scroll, plus cover and reverse.
|
|
20447
20683
|
- [ScrollComponentProps](ui/ScrollComponentProps.md): Props for the Scroll component — children plus scroll-axis variants.
|
|
20448
20684
|
- [ShadowVariants](ui/ShadowVariants.md): Variant props for the drop shadow of an element, e.g. shadow="large".
|
|
20449
20685
|
- [SpaceVariants](ui/SpaceVariants.md): Variants to control block spacing on components, e.g. space="large".
|
|
@@ -20492,6 +20728,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20492
20728
|
- [ColorVariant](ui/ColorVariant.md): Enumerated colour names selectable via the color="purple" prop for components that support that support ColorVariants
|
|
20493
20729
|
- [DurationValue](ui/DurationValue.md): Allowed values for transition timing for components that support DurationVariants
|
|
20494
20730
|
- [ColumnsVariant](ui/ColumnsVariant.md): Number of equal-width columns selectable via the columns variant prop.
|
|
20731
|
+
- [HeightVariant](ui/HeightVariant.md): Enumerated height selectable via the height variant prop.
|
|
20495
20732
|
- [IndentVariant](ui/IndentVariant.md): Allowed values for inline-padding ("indent") for components that support IndentVariants
|
|
20496
20733
|
- [RadiusVariant](ui/RadiusVariant.md): Allowed values for border radius for components that support RadiusVariants
|
|
20497
20734
|
- [ShadowVariant](ui/ShadowVariant.md): Enumerated drop-shadow scale selectable via the shadow="normal" variant prop.
|
|
@@ -20534,7 +20771,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20534
20771
|
- [LOADING_NOTICE](ui/LOADING_NOTICE.md): Shared loading <Notice> element showing the loading spinner.
|
|
20535
20772
|
- [NOTICES](ui/NOTICES.md): Global NoticesStore shown by <Notices>, accepting any of the default statuses.
|
|
20536
20773
|
- [NavigationContext](ui/NavigationContext.md): React context holding the current NavigationStore, provided by <Navigation>.
|
|
20537
|
-
- [
|
|
20774
|
+
- [NavigationPositionContext](ui/NavigationPositionContext.md): React context holding where the app is in its stacks, published by <Navigation> with each URL change.
|
|
20538
20775
|
- [STATUSES](ui/STATUSES.md): Tuple of the status names selectable via the status variant prop.
|
|
20539
20776
|
- [TINT_CLASS](ui/TINT_CLASS.md): CSS class that (re)calculates the full ladder of tint shades from the current global tint colour.
|
|
20540
20777
|
- [FADE_TRANSITION_CLASS](ui/FADE_TRANSITION_CLASS.md): View transition class that fades content in and out.
|
|
@@ -20584,17 +20821,19 @@ Use `<App>` when mounting into an existing HTML page on the client. For server-s
|
|
|
20584
20821
|
The smallest single-screen app — `<App>` wraps a layout and some content:
|
|
20585
20822
|
|
|
20586
20823
|
```tsx
|
|
20587
|
-
import { App,
|
|
20824
|
+
import { App, FixedLayout, Paragraph, Scroll, Section, Title } from "shelving/ui";
|
|
20588
20825
|
|
|
20589
20826
|
function HelloApp() {
|
|
20590
20827
|
return (
|
|
20591
20828
|
<App app="My app">
|
|
20592
|
-
<
|
|
20593
|
-
<
|
|
20594
|
-
<
|
|
20595
|
-
|
|
20596
|
-
|
|
20597
|
-
|
|
20829
|
+
<FixedLayout>
|
|
20830
|
+
<Scroll vertical cover>
|
|
20831
|
+
<Section width="narrow">
|
|
20832
|
+
<Title>Hello</Title>
|
|
20833
|
+
<Paragraph>Welcome to the app.</Paragraph>
|
|
20834
|
+
</Section>
|
|
20835
|
+
</Scroll>
|
|
20836
|
+
</FixedLayout>
|
|
20598
20837
|
</App>
|
|
20599
20838
|
);
|
|
20600
20839
|
}
|
|
@@ -20625,6 +20864,102 @@ export function MyApp() {
|
|
|
20625
20864
|
|
|
20626
20865
|
`<App>` accepts all `PossibleMeta` props (`app`, `root`, `url`, `title`, `language`, `tags`, etc.) and merges them into the context it provides to children. On mount it adds the theme class to `document.body`, which activates the CSS custom property tokens defined in `App.module.css`; on unmount it removes it.
|
|
20627
20866
|
|
|
20867
|
+
## Composing an app
|
|
20868
|
+
|
|
20869
|
+
An app is built from layers, each with one job. Write them in plain sight in `App.tsx`, from the outside in:
|
|
20870
|
+
|
|
20871
|
+
1. **Contexts**: `<App>`, your data contexts, `<Navigation>`, `<DialogsContext>`.
|
|
20872
|
+
2. **App-level catcher**: a last resort, outside every layout.
|
|
20873
|
+
3. **Layout picker**: your own component that picks the layout (and its props) from the session, the path, or any other state.
|
|
20874
|
+
4. **Layout**: `<AppLayout>`, `<SidebarLayout>` or `<FixedLayout>`. It draws the chrome (tab bar, sidebar) and gives a content slot. It knows nothing about the cache.
|
|
20875
|
+
5. **Content**: transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. Put it in a small component of your own, and reuse it in each layout.
|
|
20876
|
+
6. **Page**: `<Page>` with its title, then the page content. A page renders no layout.
|
|
20877
|
+
|
|
20878
|
+
Nesting rules:
|
|
20879
|
+
|
|
20880
|
+
- The layout sits **above** the router. A page, an error page or a loading state never renders a layout.
|
|
20881
|
+
- The transition goes **around** `<RouteCache>`, not inside it.
|
|
20882
|
+
- `<Scroll vertical cover>` goes **inside** `<RouteCache>`, so each page keeps its own scroll.
|
|
20883
|
+
- Chrome that keeps state or animates (a tab bar, a sidebar) stays in the layout, **outside** the cache.
|
|
20884
|
+
- All pages in one stack must share one layout, because they share one `<RouteCache>`. To change the chrome for some pages (hide the tab bar), change a layout prop from the picker, for example `nav={false}`. Swap to another layout only between sections you do not move back and forth in, such as log-in and the main app.
|
|
20885
|
+
|
|
20886
|
+
```tsx
|
|
20887
|
+
import { useStore } from "shelving/react";
|
|
20888
|
+
import {
|
|
20889
|
+
App, AppLayout, Catcher, DialogsContext, Dialogs, ErrorPage, FixedLayout, HorizontalTransition,
|
|
20890
|
+
Navigation, Notices, PageLoader, requireMetaURL, RouteCache, Router, type ErrorProps, type Routes,
|
|
20891
|
+
Scroll, StackButton,
|
|
20892
|
+
} from "shelving/ui";
|
|
20893
|
+
|
|
20894
|
+
const STACKS = ["/home", "/discover", "/profile"] as const;
|
|
20895
|
+
|
|
20896
|
+
/** 1–2. Contexts and the app-level catcher. No layout here. */
|
|
20897
|
+
export function MyApp() {
|
|
20898
|
+
const session = useStore(SESSION).value;
|
|
20899
|
+
return (
|
|
20900
|
+
<App key={session?.id ?? "out"} app="My app" root="https://example.com/">
|
|
20901
|
+
<Navigation stacks={STACKS} stack="/home">
|
|
20902
|
+
<DialogsContext>
|
|
20903
|
+
<Catcher as={AppError}>
|
|
20904
|
+
<Shell signedIn={!!session} />
|
|
20905
|
+
</Catcher>
|
|
20906
|
+
<Dialogs />
|
|
20907
|
+
<Notices />
|
|
20908
|
+
</DialogsContext>
|
|
20909
|
+
</Navigation>
|
|
20910
|
+
</App>
|
|
20911
|
+
);
|
|
20912
|
+
}
|
|
20913
|
+
|
|
20914
|
+
/** 3–4. Pick the layout. Plain React, so any rule works. */
|
|
20915
|
+
function Shell({ signedIn }: { signedIn: boolean }) {
|
|
20916
|
+
const { path } = requireMetaURL();
|
|
20917
|
+
if (!signedIn) return <FixedLayout><Content routes={LOGIN_ROUTES} /></FixedLayout>;
|
|
20918
|
+
return (
|
|
20919
|
+
<AppLayout nav={path.startsWith("/squad/") ? false : <StackBar />}>
|
|
20920
|
+
<Content routes={ROUTES} />
|
|
20921
|
+
</AppLayout>
|
|
20922
|
+
);
|
|
20923
|
+
}
|
|
20924
|
+
|
|
20925
|
+
/** 5. The content of a layout's slot. */
|
|
20926
|
+
function Content({ routes }: { routes: Routes }) {
|
|
20927
|
+
return (
|
|
20928
|
+
<HorizontalTransition>
|
|
20929
|
+
<RouteCache>
|
|
20930
|
+
<Scroll vertical cover>
|
|
20931
|
+
<PageLoader>
|
|
20932
|
+
<Router routes={routes} />
|
|
20933
|
+
</PageLoader>
|
|
20934
|
+
</Scroll>
|
|
20935
|
+
</RouteCache>
|
|
20936
|
+
</HorizontalTransition>
|
|
20937
|
+
);
|
|
20938
|
+
}
|
|
20939
|
+
|
|
20940
|
+
/** The tab bar, in the layout, outside the cache. */
|
|
20941
|
+
function StackBar() {
|
|
20942
|
+
return <>
|
|
20943
|
+
<StackButton stack="/home" title="Home"><HomeIcon /></StackButton>
|
|
20944
|
+
<StackButton stack="/discover" title="Discover"><SearchIcon /></StackButton>
|
|
20945
|
+
<StackButton stack="/profile" title="Profile"><ProfileIcon /></StackButton>
|
|
20946
|
+
</>;
|
|
20947
|
+
}
|
|
20948
|
+
|
|
20949
|
+
/** An error outside every layout: the app picks one here. */
|
|
20950
|
+
function AppError({ reason }: ErrorProps) {
|
|
20951
|
+
return (
|
|
20952
|
+
<FixedLayout>
|
|
20953
|
+
<Scroll vertical cover>
|
|
20954
|
+
<ErrorPage reason={reason} />
|
|
20955
|
+
</Scroll>
|
|
20956
|
+
</FixedLayout>
|
|
20957
|
+
);
|
|
20958
|
+
}
|
|
20959
|
+
```
|
|
20960
|
+
|
|
20961
|
+
Layouts are optional. With no layout, the document body scrolls, which is fine for a simple site. Use a layout when the app scrolls inside its own boxes: it locks the body and gives a content slot. Every layout is a frame: none of them scroll or centre. A page centres its own content, for example with `<Block height="full" middle width="narrow">`.
|
|
20962
|
+
|
|
20628
20963
|
For a documentation site, hand an extracted tree to `<TreeApp>` instead — see the `shelving/extract` guide.
|
|
20629
20964
|
|
|
20630
20965
|
|
|
@@ -23079,7 +23414,6 @@ Props for a thing that can be clicked — either has a string `href` link or an
|
|
|
23079
23414
|
download?: string | undefined;
|
|
23080
23415
|
title?: string | undefined;
|
|
23081
23416
|
selected?: boolean | undefined;
|
|
23082
|
-
back?: boolean | undefined;
|
|
23083
23417
|
}
|
|
23084
23418
|
```
|
|
23085
23419
|
|
|
@@ -23094,7 +23428,6 @@ Props for a thing that can be clicked — either has a string `href` link or an
|
|
|
23094
23428
|
| `download` | `string \| undefined` | If `href` is present then this is the suggested filename for downloading. Optional. |
|
|
23095
23429
|
| `title` | `string \| undefined` | Title shown on hover. Optional. |
|
|
23096
23430
|
| `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
23431
|
|
|
23099
23432
|
|
|
23100
23433
|
---
|
|
@@ -23175,7 +23508,6 @@ LinkClickable({
|
|
|
23175
23508
|
download,
|
|
23176
23509
|
title,
|
|
23177
23510
|
selected,
|
|
23178
|
-
back,
|
|
23179
23511
|
children = "Go",
|
|
23180
23512
|
className,
|
|
23181
23513
|
}: StylableClickableProps): ReactElement
|
|
@@ -30464,14 +30796,127 @@ TextInput({
|
|
|
30464
30796
|
|
|
30465
30797
|
---
|
|
30466
30798
|
|
|
30467
|
-
#
|
|
30799
|
+
# AppLayoutProps
|
|
30800
|
+
|
|
30801
|
+
- Kind: interface
|
|
30802
|
+
- Import: `import { AppLayoutProps } from "shelving/ui";`
|
|
30803
|
+
- Extends: `OptionalChildProps`
|
|
30804
|
+
|
|
30805
|
+
Props for `<AppLayout>`: the `nav` bar content and the content slot `children`.
|
|
30806
|
+
|
|
30807
|
+
## Signatures
|
|
30808
|
+
|
|
30809
|
+
```ts
|
|
30810
|
+
{
|
|
30811
|
+
nav?: ReactNode;
|
|
30812
|
+
}
|
|
30813
|
+
```
|
|
30814
|
+
|
|
30815
|
+
## Properties
|
|
30816
|
+
|
|
30817
|
+
| Property | Type | Description |
|
|
30818
|
+
| --- | --- | --- |
|
|
30819
|
+
| `nav` | `ReactNode` | Items for the bar below the content, for example a `<StackButton>` for each tab. Set `false` (or leave it out) to show no bar. Optional. |
|
|
30820
|
+
|
|
30821
|
+
|
|
30822
|
+
---
|
|
30823
|
+
|
|
30824
|
+
# AppLayout
|
|
30825
|
+
|
|
30826
|
+
- Kind: component
|
|
30827
|
+
- Import: `import { AppLayout } from "shelving/ui";`
|
|
30828
|
+
|
|
30829
|
+
Layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app.
|
|
30830
|
+
- It is a frame only: the content slot does not scroll. Fill it with `<Scroll vertical cover>`, inside `<RouteCache>`, so each page scrolls in its own box.
|
|
30831
|
+
- The bar sits below the content slot, not over it, and it stays still while a page slides.
|
|
30832
|
+
- Set `nav={false}` to hide the bar, for example for a full-screen page. Change the prop in place (from the URL), so the layout and its page cache stay mounted.
|
|
30833
|
+
|
|
30834
|
+
A full-viewport layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app. It is a frame only: it draws the bar and gives the content slot, and the app fills the slot.
|
|
30835
|
+
|
|
30836
|
+
**Things to know:**
|
|
30837
|
+
|
|
30838
|
+
- The content slot does not scroll. Fill it with `<Scroll vertical cover>` inside `<RouteCache>`, so each page scrolls in its own box and keeps its own scroll position.
|
|
30839
|
+
- The bar sits below the content slot, not over it. So pages need no extra space at the bottom for the bar.
|
|
30840
|
+
- The bar shows at every screen size.
|
|
30841
|
+
- The content slot stays clear of the notch and the rounded screen corners, and the bar stays clear of the home bar (safe-area insets).
|
|
30842
|
+
- Each item in the bar takes an equal share of its width, up to `--app-layout-nav-item-width` each.
|
|
30843
|
+
- The bar is outside the page cache, so it has one copy. It keeps its state, and the CSS transitions of its items (an active tab) still play while a page slides.
|
|
30844
|
+
- The bar has its own view-transition group, so it stays still while the page slides under it.
|
|
30845
|
+
- Leave out `nav`, or set it to `false`, to show no bar. The content slot then fills the screen. To hide the bar for some pages, change the prop from the URL, so the layout and its page cache stay mounted: `nav={path.startsWith("/squad/") ? false : <StackBar />}`.
|
|
30846
|
+
- Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
|
|
30847
|
+
|
|
30848
|
+
## Usage
|
|
30849
|
+
|
|
30850
|
+
```tsx
|
|
30851
|
+
import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll, StackButton } from "shelving/ui";
|
|
30852
|
+
|
|
30853
|
+
function StackBar() {
|
|
30854
|
+
return <>
|
|
30855
|
+
<StackButton stack="/home" title="Home"><HomeIcon /></StackButton>
|
|
30856
|
+
<StackButton stack="/discover" title="Discover"><SearchIcon /></StackButton>
|
|
30857
|
+
<StackButton stack="/profile" title="Profile"><ProfileIcon /></StackButton>
|
|
30858
|
+
</>;
|
|
30859
|
+
}
|
|
30860
|
+
|
|
30861
|
+
<AppLayout nav={<StackBar />}>
|
|
30862
|
+
<HorizontalTransition>
|
|
30863
|
+
<RouteCache>
|
|
30864
|
+
<Scroll vertical cover>
|
|
30865
|
+
<PageLoader>
|
|
30866
|
+
<Router routes={ROUTES} />
|
|
30867
|
+
</PageLoader>
|
|
30868
|
+
</Scroll>
|
|
30869
|
+
</RouteCache>
|
|
30870
|
+
</HorizontalTransition>
|
|
30871
|
+
</AppLayout>
|
|
30872
|
+
```
|
|
30873
|
+
|
|
30874
|
+
## Styling
|
|
30875
|
+
|
|
30876
|
+
| Variable | Styles | Default |
|
|
30877
|
+
|---|---|---|
|
|
30878
|
+
| `--app-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
|
|
30879
|
+
| `--app-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
|
|
30880
|
+
| `--app-layout-nav-background` | Bar fill (also fills the home-bar area below it) | `var(--tint-100)` (white) |
|
|
30881
|
+
| `--app-layout-nav-color` | Bar text and icon colour | `var(--tint-00)` (black) |
|
|
30882
|
+
| `--app-layout-nav-border` | Line above the bar | `var(--stroke-normal) solid var(--tint-90)` |
|
|
30883
|
+
| `--app-layout-nav-shadow` | Shadow of the bar, for example a soft shadow above it | `none` |
|
|
30884
|
+
| `--app-layout-nav-item-width` | Largest width of one bar item | `6rem` |
|
|
30885
|
+
|
|
30886
|
+
The bar keeps its items clear of the home bar and the rounded screen corners with safe-area insets.
|
|
30887
|
+
|
|
30888
|
+
**Global tokens it reads** — `--tint-00`, `--tint-90`, `--tint-100`, and `--stroke-normal`.
|
|
30889
|
+
|
|
30890
|
+
|
|
30891
|
+
## Signatures
|
|
30892
|
+
|
|
30893
|
+
```ts
|
|
30894
|
+
AppLayout({ nav, children }: AppLayoutProps): ReactElement
|
|
30895
|
+
```
|
|
30896
|
+
|
|
30897
|
+
## Parameters
|
|
30898
|
+
|
|
30899
|
+
| Param | Type | Description |
|
|
30900
|
+
| --- | --- | --- |
|
|
30901
|
+
| `props` | `AppLayoutProps` | |
|
|
30902
|
+
| `.nav` | `ReactNode` | Items for the bar below the content, for example a `<StackButton>` for each tab. Set `false` (or leave it out) to show no bar. Optional. |
|
|
30903
|
+
|
|
30904
|
+
## Returns
|
|
30905
|
+
|
|
30906
|
+
| Type | Description |
|
|
30907
|
+
| --- | --- |
|
|
30908
|
+
| `ReactElement` | |
|
|
30909
|
+
|
|
30910
|
+
|
|
30911
|
+
---
|
|
30912
|
+
|
|
30913
|
+
# FixedLayoutProps
|
|
30468
30914
|
|
|
30469
30915
|
- Kind: interface
|
|
30470
|
-
- Import: `import {
|
|
30471
|
-
- Extends: `
|
|
30916
|
+
- Import: `import { FixedLayoutProps } from "shelving/ui";`
|
|
30917
|
+
- Extends: `OptionalChildProps`
|
|
30472
30918
|
|
|
30473
|
-
Props for `<
|
|
30474
|
-
(block / inline padding of the scroll area) variants.
|
|
30919
|
+
Props for `<FixedLayout>`: the content slot `children`.
|
|
30475
30920
|
|
|
30476
30921
|
## Signatures
|
|
30477
30922
|
|
|
@@ -30482,66 +30927,91 @@ Props for `<CenteredLayout>` — optional `children` plus `width` (of the centre
|
|
|
30482
30927
|
|
|
30483
30928
|
---
|
|
30484
30929
|
|
|
30485
|
-
#
|
|
30930
|
+
# FixedLayout
|
|
30486
30931
|
|
|
30487
30932
|
- Kind: component
|
|
30488
|
-
- Import: `import {
|
|
30933
|
+
- Import: `import { FixedLayout } from "shelving/ui";`
|
|
30489
30934
|
|
|
30490
|
-
Layout
|
|
30491
|
-
-
|
|
30935
|
+
Layout with no chrome: the whole screen is one content slot.
|
|
30936
|
+
- It locks the document and gives a full-height slot inside the safe areas. It does not scroll or centre.
|
|
30937
|
+
- Fill the slot with `<Scroll vertical cover>`. Used for e.g. log-in and error screens, and full-screen pages.
|
|
30492
30938
|
|
|
30493
|
-
A full-viewport layout
|
|
30939
|
+
A full-viewport layout with no chrome: the whole screen is one content slot. It locks the document, so the page behind never scrolls or rubber-bands, and gives a full-height slot inside the safe areas. Use it for log-in and error screens, and other full-screen pages.
|
|
30494
30940
|
|
|
30495
30941
|
**Things to know:**
|
|
30496
30942
|
|
|
30497
|
-
-
|
|
30498
|
-
-
|
|
30499
|
-
-
|
|
30943
|
+
- It is a frame only. It does not scroll or centre. Fill the slot with `<Scroll vertical cover>`, so the content scrolls inside it.
|
|
30944
|
+
- Centre the content in the page itself, for example with `<Block height="full" middle width="narrow">`: it puts the content in the middle of the screen, and it still scrolls when it is taller.
|
|
30945
|
+
- The slot stays clear of the notch, the home bar and the rounded screen corners (safe-area insets).
|
|
30946
|
+
- For pages that you move back and forth between, put a `<RouteCache>` around the scroll box, as in `<AppLayout>`.
|
|
30947
|
+
- Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
|
|
30500
30948
|
|
|
30501
30949
|
## Usage
|
|
30502
30950
|
|
|
30503
30951
|
```tsx
|
|
30504
|
-
import {
|
|
30952
|
+
import { Block, FixedLayout, Router, Scroll } from "shelving/ui";
|
|
30505
30953
|
|
|
30954
|
+
// The signed-out screens: one layout around their own router.
|
|
30955
|
+
<FixedLayout>
|
|
30956
|
+
<Scroll vertical cover>
|
|
30957
|
+
<Router routes={{
|
|
30958
|
+
"/login": LoginPage,
|
|
30959
|
+
"/register": RegisterPage,
|
|
30960
|
+
}} />
|
|
30961
|
+
</Scroll>
|
|
30962
|
+
</FixedLayout>
|
|
30963
|
+
|
|
30964
|
+
// Each page centres its own content.
|
|
30506
30965
|
function LoginPage() {
|
|
30507
30966
|
return (
|
|
30508
|
-
<
|
|
30509
|
-
<
|
|
30510
|
-
<LoginForm/>
|
|
30511
|
-
</
|
|
30512
|
-
</
|
|
30967
|
+
<Page title="Log in">
|
|
30968
|
+
<Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
|
|
30969
|
+
<LoginForm />
|
|
30970
|
+
</Block>
|
|
30971
|
+
</Page>
|
|
30513
30972
|
);
|
|
30514
30973
|
}
|
|
30515
30974
|
```
|
|
30516
30975
|
|
|
30517
|
-
|
|
30976
|
+
An app-level error, outside every other layout:
|
|
30977
|
+
|
|
30978
|
+
```tsx
|
|
30979
|
+
import { Catcher, ErrorPage, type ErrorProps, FixedLayout, Scroll } from "shelving/ui";
|
|
30980
|
+
|
|
30981
|
+
function AppError({ reason }: ErrorProps) {
|
|
30982
|
+
return (
|
|
30983
|
+
<FixedLayout>
|
|
30984
|
+
<Scroll vertical cover>
|
|
30985
|
+
<ErrorPage reason={reason} />
|
|
30986
|
+
</Scroll>
|
|
30987
|
+
</FixedLayout>
|
|
30988
|
+
);
|
|
30989
|
+
}
|
|
30990
|
+
|
|
30991
|
+
<Catcher as={AppError}>…</Catcher>
|
|
30992
|
+
```
|
|
30518
30993
|
|
|
30519
30994
|
## Styling
|
|
30520
30995
|
|
|
30521
30996
|
| Variable | Styles | Default |
|
|
30522
30997
|
|---|---|---|
|
|
30523
|
-
| `--
|
|
30524
|
-
| `--
|
|
30525
|
-
| `--centered-layout-indent` | Inline (left/right) padding of the scroll area | `var(--space-normal)` |
|
|
30526
|
-
| `--centered-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
|
|
30527
|
-
| `--centered-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
|
|
30528
|
-
|
|
30529
|
-
The column width and the scroll-area padding can also be set per-instance via the `width`, `padding`, and `indent` variant props. The outer element owns its scroll, padding, and safe-area behaviour directly — safe-area insets are applied as transparent borders so they stack with (rather than replace) the padding.
|
|
30998
|
+
| `--fixed-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
|
|
30999
|
+
| `--fixed-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
|
|
30530
31000
|
|
|
30531
|
-
**Global tokens it reads** — `--
|
|
31001
|
+
**Global tokens it reads** — `--tint-00` and `--tint-100`.
|
|
30532
31002
|
|
|
30533
31003
|
|
|
30534
31004
|
## Signatures
|
|
30535
31005
|
|
|
30536
31006
|
```ts
|
|
30537
|
-
|
|
31007
|
+
FixedLayout({ children }: FixedLayoutProps): ReactElement
|
|
30538
31008
|
```
|
|
30539
31009
|
|
|
30540
31010
|
## Parameters
|
|
30541
31011
|
|
|
30542
31012
|
| Param | Type | Description |
|
|
30543
31013
|
| --- | --- | --- |
|
|
30544
|
-
| `props` | `
|
|
31014
|
+
| `props` | `FixedLayoutProps` | |
|
|
30545
31015
|
|
|
30546
31016
|
## Returns
|
|
30547
31017
|
|
|
@@ -30584,14 +31054,14 @@ Props for `<SidebarLayout>` — the `sidebar` column content, main `children`, a
|
|
|
30584
31054
|
- Kind: component
|
|
30585
31055
|
- Import: `import { SidebarLayout } from "shelving/ui";`
|
|
30586
31056
|
|
|
30587
|
-
Layout with a fixed-width side column (typically navigation) next to a
|
|
31057
|
+
Layout with a fixed-width side column (typically navigation) next to a content slot.
|
|
30588
31058
|
- The sidebar is rendered as `<nav>` — it almost always contains the page's primary navigation.
|
|
30589
31059
|
- On narrow viewports the sidebar becomes an off-canvas drawer toggled by a single menu button that switches between a burger and a close icon.
|
|
30590
31060
|
- While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
|
|
30591
31061
|
- Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
|
|
30592
|
-
-
|
|
31062
|
+
- It is a frame only: the content slot does not scroll. Fill it with `<Scroll vertical cover>`, inside `<RouteCache>`, so each page scrolls in its own box. The sidebar stays outside the cache, so it keeps its own state and scroll.
|
|
30593
31063
|
|
|
30594
|
-
A full-viewport layout with a fixed-width side column next to a
|
|
31064
|
+
A full-viewport layout with a fixed-width side column next to a content slot. The sidebar renders as a `<nav>` landmark — it almost always holds the primary navigation. On narrow viewports it collapses to an off-canvas drawer toggled by a single burger/close button.
|
|
30595
31065
|
|
|
30596
31066
|
**Things to know:**
|
|
30597
31067
|
|
|
@@ -30600,12 +31070,15 @@ A full-viewport layout with a fixed-width side column next to a scrollable main
|
|
|
30600
31070
|
- While the drawer is open an overlay dims the page; clicking the overlay closes it.
|
|
30601
31071
|
- Under `prefers-reduced-motion: reduce` the drawer snaps open/closed instead of sliding off-canvas; the overlay keeps its dimming fade, which is opacity-only and therefore reduced-motion-safe.
|
|
30602
31072
|
- Inside a `<Navigation>` context the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
|
|
30603
|
-
- The
|
|
31073
|
+
- It is a frame only. The content slot does not scroll: fill it with `<Scroll vertical cover>` inside `<RouteCache>`, so each page scrolls in its own box. Content put in the slot without a scroll box does not scroll.
|
|
31074
|
+
- The sidebar stays outside the page cache, so it keeps its own scroll position and state as pages change.
|
|
31075
|
+
- On a narrow screen the menu button floats at the top right of the content slot, above the page.
|
|
31076
|
+
- Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
|
|
30604
31077
|
|
|
30605
31078
|
## Usage
|
|
30606
31079
|
|
|
30607
31080
|
```tsx
|
|
30608
|
-
import {
|
|
31081
|
+
import { Menu, MenuItem, PageLoader, RouteCache, Router, Scroll, SidebarLayout } from "shelving/ui";
|
|
30609
31082
|
|
|
30610
31083
|
function AppShell() {
|
|
30611
31084
|
const nav = (
|
|
@@ -30617,13 +31090,19 @@ function AppShell() {
|
|
|
30617
31090
|
);
|
|
30618
31091
|
return (
|
|
30619
31092
|
<SidebarLayout sidebar={nav}>
|
|
30620
|
-
<
|
|
31093
|
+
<RouteCache>
|
|
31094
|
+
<Scroll vertical cover>
|
|
31095
|
+
<PageLoader>
|
|
31096
|
+
<Router routes={ROUTES}/>
|
|
31097
|
+
</PageLoader>
|
|
31098
|
+
</Scroll>
|
|
31099
|
+
</RouteCache>
|
|
30621
31100
|
</SidebarLayout>
|
|
30622
31101
|
);
|
|
30623
31102
|
}
|
|
30624
31103
|
```
|
|
30625
31104
|
|
|
30626
|
-
|
|
31105
|
+
To slide pages, put a transition around the `<RouteCache>`, inside the layout. The sidebar is outside the transition, so it stays still.
|
|
30627
31106
|
|
|
30628
31107
|
## Styling
|
|
30629
31108
|
|
|
@@ -30637,7 +31116,7 @@ Layouts compose naturally as `<Router>` route values — wrap a group of routes
|
|
|
30637
31116
|
| `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-90)` | `none` |
|
|
30638
31117
|
| `--sidebar-layout-shadow` | Drop shadow of the open drawer on a narrow screen | `var(--shadow-large)` |
|
|
30639
31118
|
|
|
30640
|
-
The sidebar
|
|
31119
|
+
The sidebar scrolls on its own. The content slot does not scroll: its `<Scroll vertical cover>` box does.
|
|
30641
31120
|
|
|
30642
31121
|
**Global tokens it reads** — `--tint-00` / `--tint-90` / `--tint-100`, plus `--space-normal`, `--duration-normal`, `--shadow-large`, and `--color-backdrop`.
|
|
30643
31122
|
|
|
@@ -30967,7 +31446,7 @@ A React error boundary that catches errors thrown anywhere in its subtree and re
|
|
|
30967
31446
|
|
|
30968
31447
|
**Things to know:**
|
|
30969
31448
|
|
|
30970
|
-
- `PageCatcher` is a convenience wrapper that renders `ErrorPage` instead — a
|
|
31449
|
+
- `PageCatcher` is a convenience wrapper that renders `ErrorPage` instead — a page with the error in a narrow column. `ErrorPage` renders no layout, so it shows inside the layout around it. An app-level catcher sits outside every layout, so give it one: `<Catcher as={AppError}>`, where `AppError` renders `<ErrorPage>` in a `<FixedLayout>` and `<Scroll vertical cover>` (see `<FixedLayout>`).
|
|
30971
31450
|
- `RetryButton` reads the retry callback from the nearest `Catcher` via context and renders a `<Button>`. It returns `null` when there is no parent catcher to retry.
|
|
30972
31451
|
- `ErrorNotice` and `ErrorPage` can be used standalone when you need to display a known error without a boundary. Both use `getMessage()` to extract a human-readable message, falling back to `"Unknown error"`.
|
|
30973
31452
|
|
|
@@ -31103,7 +31582,8 @@ PageCatcher({ children }: ChildProps): ReactElement
|
|
|
31103
31582
|
- Kind: component
|
|
31104
31583
|
- Import: `import { ErrorPage } from "shelving/ui";`
|
|
31105
31584
|
|
|
31106
|
-
Render a caught error as a
|
|
31585
|
+
Render a caught error as a `<Page>` with an `<ErrorNotice>` in a narrow column, centred in the middle of the screen.
|
|
31586
|
+
- It renders no layout, so it shows inside whatever layout is around it. Outside every layout (an app-level catcher), wrap it in one, for example `<FixedLayout>` with a `<Scroll vertical cover>`.
|
|
31107
31587
|
|
|
31108
31588
|
## Signatures
|
|
31109
31589
|
|
|
@@ -31295,11 +31775,12 @@ Load a page.
|
|
|
31295
31775
|
|
|
31296
31776
|
- Wrapped in `<PageCatcher>` so child components can throw errors.
|
|
31297
31777
|
- Wrapped in `<Suspense>` so child components can throw promises.
|
|
31778
|
+
- It renders no layout, so its loading state and error page show inside whatever layout is around it.
|
|
31298
31779
|
|
|
31299
31780
|
## Signatures
|
|
31300
31781
|
|
|
31301
31782
|
```ts
|
|
31302
|
-
PageLoader({ children, fallback =
|
|
31783
|
+
PageLoader({ children, fallback = PAGE_LOADING }: LoaderProps): ReactElement
|
|
31303
31784
|
```
|
|
31304
31785
|
|
|
31305
31786
|
## Parameters
|
|
@@ -32430,10 +32911,10 @@ close(): void
|
|
|
32430
32911
|
- Kind: component
|
|
32431
32912
|
- Import: `import { Head } from "shelving/ui";`
|
|
32432
32913
|
|
|
32433
|
-
Emit the current page's head metadata and
|
|
32914
|
+
Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
|
|
32434
32915
|
- Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
|
|
32435
32916
|
- Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
|
|
32436
|
-
-
|
|
32917
|
+
- 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
32918
|
|
|
32438
32919
|
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
32920
|
|
|
@@ -32595,16 +33076,20 @@ function UserPage({ id }: { id: string }) {
|
|
|
32595
33076
|
}
|
|
32596
33077
|
```
|
|
32597
33078
|
|
|
32598
|
-
|
|
33079
|
+
A page renders no layout. The layout goes outside the page, above the router, so every page in it shares one frame. See "Composing an app" on `<App>`.
|
|
32599
33080
|
|
|
32600
33081
|
```tsx
|
|
32601
|
-
import { Page,
|
|
33082
|
+
import { Block, FixedLayout, Page, Scroll } from "shelving/ui";
|
|
32602
33083
|
|
|
32603
|
-
<
|
|
32604
|
-
<
|
|
32605
|
-
<
|
|
32606
|
-
|
|
32607
|
-
|
|
33084
|
+
<FixedLayout>
|
|
33085
|
+
<Scroll vertical cover>
|
|
33086
|
+
<Page title="Sign in">
|
|
33087
|
+
<Block height="full" middle width="narrow">
|
|
33088
|
+
<LoginForm/>
|
|
33089
|
+
</Block>
|
|
33090
|
+
</Page>
|
|
33091
|
+
</Scroll>
|
|
33092
|
+
</FixedLayout>
|
|
32608
33093
|
```
|
|
32609
33094
|
|
|
32610
33095
|
|
|
@@ -32627,6 +33112,110 @@ Page({ children, ...meta }: PageProps): ReactElement
|
|
|
32627
33112
|
| `ReactElement` | |
|
|
32628
33113
|
|
|
32629
33114
|
|
|
33115
|
+
---
|
|
33116
|
+
|
|
33117
|
+
# BackButtonProps
|
|
33118
|
+
|
|
33119
|
+
- Kind: interface
|
|
33120
|
+
- Import: `import { BackButtonProps } from "shelving/ui";`
|
|
33121
|
+
- Extends: `Omit<ButtonProps, "href" | "onClick">`
|
|
33122
|
+
|
|
33123
|
+
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`.
|
|
33124
|
+
|
|
33125
|
+
## Signatures
|
|
33126
|
+
|
|
33127
|
+
```ts
|
|
33128
|
+
{
|
|
33129
|
+
readonly href: AbsolutePath;
|
|
33130
|
+
}
|
|
33131
|
+
```
|
|
33132
|
+
|
|
33133
|
+
## Properties
|
|
33134
|
+
|
|
33135
|
+
| Property | Type | Description |
|
|
33136
|
+
| --- | --- | --- |
|
|
33137
|
+
| `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. |
|
|
33138
|
+
|
|
33139
|
+
|
|
33140
|
+
---
|
|
33141
|
+
|
|
33142
|
+
# BackButton
|
|
33143
|
+
|
|
33144
|
+
- Kind: component
|
|
33145
|
+
- Import: `import { BackButton } from "shelving/ui";`
|
|
33146
|
+
|
|
33147
|
+
Back button for the current stack.
|
|
33148
|
+
- Goes back to the page before this one in the current stack, wherever you came from.
|
|
33149
|
+
- 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.
|
|
33150
|
+
- It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
|
|
33151
|
+
|
|
33152
|
+
The back button for a page header. It goes back to the page before this one in the current stack, wherever you came from.
|
|
33153
|
+
|
|
33154
|
+
**Things to know:**
|
|
33155
|
+
|
|
33156
|
+
- 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.
|
|
33157
|
+
- 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>`.
|
|
33158
|
+
- 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.
|
|
33159
|
+
- Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
|
|
33160
|
+
- It takes the usual `<Button>` props, except `onClick`.
|
|
33161
|
+
- Without the browser Navigation API, and in a server render, it links to `href`.
|
|
33162
|
+
- 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.
|
|
33163
|
+
|
|
33164
|
+
## Usage
|
|
33165
|
+
|
|
33166
|
+
```tsx
|
|
33167
|
+
import { BackButton } from "shelving/ui";
|
|
33168
|
+
|
|
33169
|
+
function PostPage({ id }: { id: string }) {
|
|
33170
|
+
return (
|
|
33171
|
+
<>
|
|
33172
|
+
<header>
|
|
33173
|
+
<BackButton href="/home"/>
|
|
33174
|
+
<h1>Post</h1>
|
|
33175
|
+
</header>
|
|
33176
|
+
{/* … */}
|
|
33177
|
+
</>
|
|
33178
|
+
);
|
|
33179
|
+
}
|
|
33180
|
+
```
|
|
33181
|
+
|
|
33182
|
+
With a label:
|
|
33183
|
+
|
|
33184
|
+
```tsx
|
|
33185
|
+
<BackButton href="/profile">Back to profile</BackButton>
|
|
33186
|
+
```
|
|
33187
|
+
|
|
33188
|
+
To go back to one fixed page (not to the page before), use a link with `className="back"`:
|
|
33189
|
+
|
|
33190
|
+
```tsx
|
|
33191
|
+
<Button href="/profile" className="back">Profile</Button>
|
|
33192
|
+
```
|
|
33193
|
+
|
|
33194
|
+
## Styling
|
|
33195
|
+
|
|
33196
|
+
`<BackButton>` renders a `<Button>`, so it has the same styling hooks. See `<Button>`.
|
|
33197
|
+
|
|
33198
|
+
|
|
33199
|
+
## Signatures
|
|
33200
|
+
|
|
33201
|
+
```ts
|
|
33202
|
+
BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement
|
|
33203
|
+
```
|
|
33204
|
+
|
|
33205
|
+
## Parameters
|
|
33206
|
+
|
|
33207
|
+
| Param | Type | Description |
|
|
33208
|
+
| --- | --- | --- |
|
|
33209
|
+
| `props` | `BackButtonProps` | |
|
|
33210
|
+
| `.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. |
|
|
33211
|
+
|
|
33212
|
+
## Returns
|
|
33213
|
+
|
|
33214
|
+
| Type | Description |
|
|
33215
|
+
| --- | --- |
|
|
33216
|
+
| `ReactElement` | |
|
|
33217
|
+
|
|
33218
|
+
|
|
32630
33219
|
---
|
|
32631
33220
|
|
|
32632
33221
|
# NavigationProps
|
|
@@ -32635,14 +33224,24 @@ Page({ children, ...meta }: PageProps): ReactElement
|
|
|
32635
33224
|
- Import: `import { NavigationProps } from "shelving/ui";`
|
|
32636
33225
|
- Extends: `PossibleMeta`
|
|
32637
33226
|
|
|
32638
|
-
Props for `<Navigation
|
|
33227
|
+
Props for `<Navigation>`: the initial `Meta` (url, root and stack), the `stacks`, and optional `children`.
|
|
32639
33228
|
|
|
32640
33229
|
## Signatures
|
|
32641
33230
|
|
|
32642
33231
|
```ts
|
|
32643
|
-
{
|
|
33232
|
+
{
|
|
33233
|
+
readonly stacks?: readonly AbsolutePath[] | undefined;
|
|
33234
|
+
readonly stack?: AbsolutePath | undefined;
|
|
33235
|
+
}
|
|
32644
33236
|
```
|
|
32645
33237
|
|
|
33238
|
+
## Properties
|
|
33239
|
+
|
|
33240
|
+
| Property | Type | Description |
|
|
33241
|
+
| --- | --- | --- |
|
|
33242
|
+
| `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. |
|
|
33243
|
+
| `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. |
|
|
33244
|
+
|
|
32646
33245
|
|
|
32647
33246
|
---
|
|
32648
33247
|
|
|
@@ -32651,78 +33250,141 @@ Props for `<Navigation>` — initial `Meta` (url/base) plus optional `children`.
|
|
|
32651
33250
|
- Kind: component
|
|
32652
33251
|
- Import: `import { Navigation } from "shelving/ui";`
|
|
32653
33252
|
|
|
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).
|
|
33253
|
+
Top-level navigation provider, with one stack of pages for each tab.
|
|
33254
|
+
- Owns a single `NavigationStore` made from the surrounding `<Meta>` url and root.
|
|
33255
|
+
- 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.
|
|
33256
|
+
- Publishes the URL and the current `stack` into `Meta`, and the position in the stacks into `NavigationPositionContext`, all in one render.
|
|
33257
|
+
- 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.
|
|
33258
|
+
- Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
|
|
32661
33259
|
|
|
32662
|
-
Exactly one `<Navigation>` per app
|
|
33260
|
+
Exactly one `<Navigation>` per app. Nested routers share its store.
|
|
32663
33261
|
|
|
32664
|
-
|
|
33262
|
+
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
33263
|
|
|
32666
|
-
|
|
33264
|
+
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
33265
|
|
|
32668
33266
|
**Things to know:**
|
|
32669
33267
|
|
|
32670
|
-
- Same-origin
|
|
32671
|
-
-
|
|
32672
|
-
-
|
|
32673
|
-
-
|
|
32674
|
-
-
|
|
32675
|
-
- The
|
|
32676
|
-
-
|
|
32677
|
-
-
|
|
32678
|
-
-
|
|
33268
|
+
- Same-origin link clicks become `NavigationStore.forward()`, so the page slides forward.
|
|
33269
|
+
- A link with `className="back"` calls `NavigationStore.back()`, so the page slides back. `<BackButton>` sets this class for you.
|
|
33270
|
+
- 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.
|
|
33271
|
+
- 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.
|
|
33272
|
+
- 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.
|
|
33273
|
+
- 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.
|
|
33274
|
+
- 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.
|
|
33275
|
+
- 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 `"/"`.
|
|
33276
|
+
- 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`.
|
|
33277
|
+
- `<Router>` works with no `<Navigation>` (server renders, static renders, tests). `<Navigation>` only makes the URL live on the client.
|
|
33278
|
+
|
|
33279
|
+
### Browser support
|
|
33280
|
+
|
|
33281
|
+
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:
|
|
33282
|
+
|
|
33283
|
+
- Links still go through the app with no page reload, and the browser back button works.
|
|
33284
|
+
- There are no stacks, no slides and no `<RouteCache>`. Each page mounts fresh.
|
|
33285
|
+
- `<StackButton>` is a plain link to its stack's root. `<BackButton>` is a plain link to its `href`.
|
|
32679
33286
|
|
|
32680
33287
|
## Usage
|
|
32681
33288
|
|
|
33289
|
+
### Basic setup
|
|
33290
|
+
|
|
32682
33291
|
```tsx
|
|
32683
|
-
import {
|
|
33292
|
+
import { App, Navigation, Router } from "shelving/ui";
|
|
32684
33293
|
|
|
32685
|
-
<
|
|
33294
|
+
<App root="https://example.com/">
|
|
32686
33295
|
<Navigation>
|
|
32687
33296
|
<Router routes={ROUTES}/>
|
|
32688
33297
|
</Navigation>
|
|
32689
|
-
</
|
|
33298
|
+
</App>
|
|
32690
33299
|
```
|
|
32691
33300
|
|
|
32692
|
-
###
|
|
33301
|
+
### App with a tab bar
|
|
33302
|
+
|
|
33303
|
+
List the root path of each stack in tab order. Put a `<StackButton>` for each stack in the tab bar.
|
|
32693
33304
|
|
|
32694
33305
|
```tsx
|
|
32695
|
-
import { HorizontalTransition, Navigation, Router } from "shelving/ui";
|
|
33306
|
+
import { App, AppLayout, HorizontalTransition, Navigation, PageLoader, RouteCache, Router, Scroll, StackButton } from "shelving/ui";
|
|
33307
|
+
|
|
33308
|
+
const STACKS = ["/home", "/discover", "/profile"] as const;
|
|
33309
|
+
|
|
33310
|
+
const TABS = <>
|
|
33311
|
+
<StackButton stack="/home">Home</StackButton>
|
|
33312
|
+
<StackButton stack="/discover">Discover</StackButton>
|
|
33313
|
+
<StackButton stack="/profile">Profile</StackButton>
|
|
33314
|
+
</>;
|
|
33315
|
+
|
|
33316
|
+
<App root="https://example.com/">
|
|
33317
|
+
<Navigation stacks={STACKS}>
|
|
33318
|
+
<AppLayout nav={TABS}>
|
|
33319
|
+
<HorizontalTransition>
|
|
33320
|
+
<RouteCache>
|
|
33321
|
+
<Scroll vertical cover>
|
|
33322
|
+
<PageLoader>
|
|
33323
|
+
<Router routes={ROUTES}/>
|
|
33324
|
+
</PageLoader>
|
|
33325
|
+
</Scroll>
|
|
33326
|
+
</RouteCache>
|
|
33327
|
+
</HorizontalTransition>
|
|
33328
|
+
</AppLayout>
|
|
33329
|
+
</Navigation>
|
|
33330
|
+
</App>
|
|
33331
|
+
```
|
|
32696
33332
|
|
|
32697
|
-
|
|
32698
|
-
|
|
32699
|
-
|
|
32700
|
-
<Router routes={ROUTES}/>
|
|
32701
|
-
</HorizontalTransition>
|
|
32702
|
-
</Navigation>
|
|
33333
|
+
The tab bar is in the layout, outside the cache, so it stays still while pages slide. See "Composing an app" on `<App>` for the full nesting rules.
|
|
33334
|
+
|
|
33335
|
+
To select a tab when the app starts, pass the starting `stack`. The app decides which stack the opening URL belongs to, for example:
|
|
32703
33336
|
|
|
32704
|
-
|
|
32705
|
-
|
|
33337
|
+
```tsx
|
|
33338
|
+
const path = window.location.pathname;
|
|
33339
|
+
const stack = STACKS.find(s => path === s || path.startsWith(`${s}/`));
|
|
33340
|
+
|
|
33341
|
+
<Navigation stacks={STACKS} stack={stack}>
|
|
33342
|
+
```
|
|
33343
|
+
|
|
33344
|
+
Put the transition **outside** `<RouteCache>`, around the whole cache. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
|
|
33345
|
+
|
|
33346
|
+
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`.
|
|
33347
|
+
|
|
33348
|
+
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.
|
|
33349
|
+
|
|
33350
|
+
### Links
|
|
33351
|
+
|
|
33352
|
+
```tsx
|
|
33353
|
+
// Opens a new page in the current stack. Slides forward.
|
|
33354
|
+
<Button href="/home/post/1">Open post</Button>
|
|
33355
|
+
|
|
33356
|
+
// Goes back to a page. Slides back.
|
|
33357
|
+
// If the page is already in the stack, the stack goes back to it.
|
|
33358
|
+
<Button href="/home" className="back">Back to home</Button>
|
|
33359
|
+
|
|
33360
|
+
// The back button for a page header. Goes to the page before this one in the stack, or to `href`.
|
|
33361
|
+
<BackButton href="/home"/>
|
|
33362
|
+
|
|
33363
|
+
// Changes the URL but keeps the same page. No slide, no new history entry.
|
|
33364
|
+
<Button href="/profile/posts" className="replace">Posts</Button>
|
|
33365
|
+
<Button href="/profile/likes" className="replace">Likes</Button>
|
|
32706
33366
|
```
|
|
32707
33367
|
|
|
32708
33368
|
### Imperative navigation
|
|
32709
33369
|
|
|
32710
|
-
Read the
|
|
33370
|
+
Read the store from anywhere in the tree with `requireNavigation()`:
|
|
32711
33371
|
|
|
32712
33372
|
```tsx
|
|
32713
33373
|
import { requireNavigation } from "shelving/ui";
|
|
32714
33374
|
|
|
32715
33375
|
const nav = requireNavigation();
|
|
32716
|
-
nav.forward("/
|
|
32717
|
-
nav.
|
|
32718
|
-
nav.
|
|
33376
|
+
nav.forward("/home/post/1"); // Open a page in the current stack.
|
|
33377
|
+
nav.back("/home"); // Go back to a page.
|
|
33378
|
+
nav.replace("/login"); // Change the URL of the current page.
|
|
32719
33379
|
```
|
|
32720
33380
|
|
|
33381
|
+
See `NavigationStore` for what each method does.
|
|
33382
|
+
|
|
32721
33383
|
|
|
32722
33384
|
## Signatures
|
|
32723
33385
|
|
|
32724
33386
|
```ts
|
|
32725
|
-
Navigation({ children, ...meta }: NavigationProps): ReactElement
|
|
33387
|
+
Navigation({ children, stacks = [], ...meta }: NavigationProps): ReactElement
|
|
32726
33388
|
```
|
|
32727
33389
|
|
|
32728
33390
|
## Parameters
|
|
@@ -32730,6 +33392,8 @@ Navigation({ children, ...meta }: NavigationProps): ReactElement
|
|
|
32730
33392
|
| Param | Type | Description |
|
|
32731
33393
|
| --- | --- | --- |
|
|
32732
33394
|
| `meta` | `NavigationProps` | |
|
|
33395
|
+
| `.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. |
|
|
33396
|
+
| `.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
33397
|
|
|
32734
33398
|
## Returns
|
|
32735
33399
|
|
|
@@ -32782,6 +33446,72 @@ requireNavigation(): NavigationStore
|
|
|
32782
33446
|
| `unknown` | RequiredError If no `<Navigation>` provider is present above. |
|
|
32783
33447
|
|
|
32784
33448
|
|
|
33449
|
+
---
|
|
33450
|
+
|
|
33451
|
+
# NavigationPositionContext
|
|
33452
|
+
|
|
33453
|
+
- Kind: constant
|
|
33454
|
+
- Import: `import { NavigationPositionContext } from "shelving/ui";`
|
|
33455
|
+
|
|
33456
|
+
React context holding where the app is in its stacks, published by `<Navigation>` with each URL change.
|
|
33457
|
+
- `undefined` without the browser Navigation API, during a server render, or outside `<Navigation>`.
|
|
33458
|
+
- `<RouteCache>`, `<Router>` and `<BackButton>` read it, so they change in the same render as the URL.
|
|
33459
|
+
|
|
33460
|
+
|
|
33461
|
+
---
|
|
33462
|
+
|
|
33463
|
+
# NavigationEntryState
|
|
33464
|
+
|
|
33465
|
+
- Kind: interface
|
|
33466
|
+
- Import: `import { NavigationEntryState } from "shelving/ui";`
|
|
33467
|
+
|
|
33468
|
+
State that `NavigationStore` saves on each browser history entry.
|
|
33469
|
+
|
|
33470
|
+
## Signatures
|
|
33471
|
+
|
|
33472
|
+
```ts
|
|
33473
|
+
{
|
|
33474
|
+
readonly stack: AbsolutePath;
|
|
33475
|
+
readonly depth: number;
|
|
33476
|
+
}
|
|
33477
|
+
```
|
|
33478
|
+
|
|
33479
|
+
## Properties
|
|
33480
|
+
|
|
33481
|
+
| Property | Type | Description |
|
|
33482
|
+
| --- | --- | --- |
|
|
33483
|
+
| `stack` | `AbsolutePath` | Root path of the stack this page is in. Read only. |
|
|
33484
|
+
| `depth` | `number` | Position of this page in its stack, where `0` is the root. Read only. |
|
|
33485
|
+
|
|
33486
|
+
|
|
33487
|
+
---
|
|
33488
|
+
|
|
33489
|
+
# NavigationPosition
|
|
33490
|
+
|
|
33491
|
+
- Kind: interface
|
|
33492
|
+
- Import: `import { NavigationPosition } from "shelving/ui";`
|
|
33493
|
+
- Extends: `NavigationEntryState`
|
|
33494
|
+
|
|
33495
|
+
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.
|
|
33496
|
+
- `undefined` when the browser has no Navigation API, or during a server render.
|
|
33497
|
+
|
|
33498
|
+
## Signatures
|
|
33499
|
+
|
|
33500
|
+
```ts
|
|
33501
|
+
{
|
|
33502
|
+
readonly tops: { readonly [stack: AbsolutePath]: number };
|
|
33503
|
+
readonly parent: AbsolutePath | undefined;
|
|
33504
|
+
}
|
|
33505
|
+
```
|
|
33506
|
+
|
|
33507
|
+
## Properties
|
|
33508
|
+
|
|
33509
|
+
| Property | Type | Description |
|
|
33510
|
+
| --- | --- | --- |
|
|
33511
|
+
| `tops` | `{ readonly [stack: AbsolutePath]: number }` | Depth of the top page of each stack that has pages. Read only. |
|
|
33512
|
+
| `parent` | `AbsolutePath \| undefined` | The page before the current one in its stack, or `undefined` at the bottom of the stack. Read only. |
|
|
33513
|
+
|
|
33514
|
+
|
|
32785
33515
|
---
|
|
32786
33516
|
|
|
32787
33517
|
# NavigationStore
|
|
@@ -32790,46 +33520,120 @@ requireNavigation(): NavigationStore
|
|
|
32790
33520
|
- Import: `import { NavigationStore } from "shelving/ui";`
|
|
32791
33521
|
- Extends: `URLStore`
|
|
32792
33522
|
|
|
32793
|
-
Store
|
|
33523
|
+
Store that holds the current navigation URL, drives browser history, and keeps a stack of pages for each tab.
|
|
32794
33524
|
|
|
32795
|
-
- Extends `URLStore
|
|
32796
|
-
-
|
|
32797
|
-
- `
|
|
32798
|
-
-
|
|
33525
|
+
- Extends `URLStore`, so its `value` is the current URL.
|
|
33526
|
+
- 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.
|
|
33527
|
+
- `stack` is a sub-store that holds the root of the current stack. It only changes when the stack changes.
|
|
33528
|
+
- 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.
|
|
33529
|
+
- Owned by `<Navigation>`. Read it with `requireNavigation()`.
|
|
32799
33530
|
|
|
32800
|
-
The store
|
|
33531
|
+
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
33532
|
|
|
32802
33533
|
**Things to know:**
|
|
32803
33534
|
|
|
32804
|
-
- `
|
|
32805
|
-
-
|
|
32806
|
-
-
|
|
33535
|
+
- `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 `/`.
|
|
33536
|
+
- A page that is not in a listed stack is **unstacked**: it is in the `/` stack. See [Unstacked pages](#unstacked-pages).
|
|
33537
|
+
- `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.
|
|
33538
|
+
- `NavigationStore.history()` returns the pages in the current stack (or a given stack), root first.
|
|
33539
|
+
- `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.
|
|
33540
|
+
- All URLs resolve against the store's `base`. Each method also takes a full same-origin URL.
|
|
33541
|
+
- 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.
|
|
33542
|
+
|
|
33543
|
+
## Methods
|
|
33544
|
+
|
|
33545
|
+
| Method | What it does | Slide |
|
|
33546
|
+
|---|---|---|
|
|
33547
|
+
| `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. |
|
|
33548
|
+
| `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 |
|
|
33549
|
+
| `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 |
|
|
33550
|
+
| `history(stack?)` | Returns the pages in `stack`, root first. | — |
|
|
33551
|
+
|
|
33552
|
+
`stack` defaults to the current stack.
|
|
33553
|
+
|
|
33554
|
+
## Unstacked pages
|
|
33555
|
+
|
|
33556
|
+
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.
|
|
33557
|
+
|
|
33558
|
+
- On an unstacked page, no `<StackButton>` is selected.
|
|
33559
|
+
- Links from an unstacked page push deeper in the `/` stack, even a link to a stack root.
|
|
33560
|
+
- To leave the `/` stack, tap a `<StackButton>`, or name the stack.
|
|
33561
|
+
- 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.
|
|
33562
|
+
- If you list `/` as one of the `stacks`, it is a normal tab, and unstacked pages open in it.
|
|
33563
|
+
|
|
33564
|
+
For example, a login page sends the user home after they log in, and names the Home stack:
|
|
33565
|
+
|
|
33566
|
+
```tsx
|
|
33567
|
+
const nav = requireNavigation();
|
|
33568
|
+
nav.replace("/home", "/home");
|
|
33569
|
+
```
|
|
33570
|
+
|
|
33571
|
+
## How stacks work
|
|
33572
|
+
|
|
33573
|
+
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`.
|
|
33574
|
+
|
|
33575
|
+
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.
|
|
33576
|
+
|
|
33577
|
+
For example, with tabs `/home` and `/profile`:
|
|
33578
|
+
|
|
33579
|
+
| Step | New history entry | Home stack | Profile stack |
|
|
33580
|
+
|---|---|---|---|
|
|
33581
|
+
| Start at `/home` | `/home` (depth 0) | `/home` | — |
|
|
33582
|
+
| Open a post | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | — |
|
|
33583
|
+
| Tap the Profile tab | `/profile` (depth 0) | `/home`, `/home/post/1` | `/profile` |
|
|
33584
|
+
| Tap the Home tab | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | `/profile` |
|
|
33585
|
+
| Tap the back button | `/home` (depth 0) | `/home` | `/profile` |
|
|
33586
|
+
|
|
33587
|
+
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.
|
|
33588
|
+
|
|
33589
|
+
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
33590
|
|
|
32808
33591
|
## Usage
|
|
32809
33592
|
|
|
32810
33593
|
```tsx
|
|
32811
|
-
import { requireNavigation } from "shelving/ui";
|
|
33594
|
+
import { Button, requireNavigation } from "shelving/ui";
|
|
32812
33595
|
|
|
32813
33596
|
function LogoutButton() {
|
|
32814
33597
|
const nav = requireNavigation();
|
|
32815
|
-
return <Button onClick={() => nav.
|
|
33598
|
+
return <Button onClick={() => nav.replace("/login")}>Log out</Button>;
|
|
32816
33599
|
}
|
|
32817
33600
|
```
|
|
32818
33601
|
|
|
32819
|
-
|
|
33602
|
+
Read the current stack in a component:
|
|
33603
|
+
|
|
33604
|
+
```tsx
|
|
33605
|
+
import { useStore } from "shelving/react";
|
|
33606
|
+
import { requireNavigation } from "shelving/ui";
|
|
33607
|
+
|
|
33608
|
+
function TabTitle() {
|
|
33609
|
+
const nav = requireNavigation();
|
|
33610
|
+
const stack = useStore(nav.stack).value;
|
|
33611
|
+
return <h1>{stack === "/profile" ? "Profile" : "Home"}</h1>;
|
|
33612
|
+
}
|
|
33613
|
+
```
|
|
33614
|
+
|
|
33615
|
+
List the pages in a stack (for example, for breadcrumbs):
|
|
33616
|
+
|
|
33617
|
+
```tsx
|
|
33618
|
+
const nav = requireNavigation();
|
|
33619
|
+
nav.history("/home"); // ["/home", "/home/post/1", "/home/post/1/comments"]
|
|
33620
|
+
```
|
|
33621
|
+
|
|
33622
|
+
Make a store by hand only in tests:
|
|
32820
33623
|
|
|
32821
33624
|
```tsx
|
|
32822
33625
|
import { NavigationStore } from "shelving/ui";
|
|
32823
33626
|
|
|
32824
|
-
|
|
32825
|
-
nav
|
|
33627
|
+
// URL, root, starting stack, then the stacks in tab order.
|
|
33628
|
+
const nav = new NavigationStore("https://example.com/home", "https://example.com/", "/home", "/home", "/profile");
|
|
33629
|
+
nav.forward("/home/post/1");
|
|
32826
33630
|
```
|
|
32827
33631
|
|
|
32828
33632
|
|
|
32829
33633
|
## Signatures
|
|
32830
33634
|
|
|
32831
33635
|
```ts
|
|
32832
|
-
new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL)
|
|
33636
|
+
new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL, stack: AbsolutePath = "/", ...stacks: AbsolutePath[])
|
|
32833
33637
|
```
|
|
32834
33638
|
|
|
32835
33639
|
## Parameters
|
|
@@ -32838,6 +33642,8 @@ new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : win
|
|
|
32838
33642
|
| --- | --- | --- |
|
|
32839
33643
|
| `url` | `PossibleURL` | Defaults to `typeof window === "undefined" ? "/" : window.location.href`. |
|
|
32840
33644
|
| `base` | `PossibleURL` | Optional. |
|
|
33645
|
+
| `stack` | `AbsolutePath` | Defaults to `"/"`. |
|
|
33646
|
+
| `stacks` | `AbsolutePath[]` | |
|
|
32841
33647
|
|
|
32842
33648
|
## Returns
|
|
32843
33649
|
|
|
@@ -32849,44 +33655,74 @@ new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : win
|
|
|
32849
33655
|
|
|
32850
33656
|
| Property | Type | Description |
|
|
32851
33657
|
| --- | --- | --- |
|
|
32852
|
-
| `
|
|
33658
|
+
| `stacks` | `readonly AbsolutePath[]` | Root path of each stack, in tab order. A single-stack app has one root. Read only. |
|
|
33659
|
+
| `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. |
|
|
33660
|
+
| `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`. |
|
|
33661
|
+
| `position` | `NavigationPosition \| undefined` | Where the app is now: the current stack and depth, and the top depth of each stack. Read only. |
|
|
32853
33662
|
|
|
32854
33663
|
## Methods
|
|
32855
33664
|
|
|
32856
|
-
- [NavigationStore.
|
|
32857
|
-
- [NavigationStore.
|
|
32858
|
-
- [NavigationStore.
|
|
33665
|
+
- [NavigationStore.listen()](ui/NavigationStore/listen.md): Start listening to the browser (back, forward and swipe).
|
|
33666
|
+
- [NavigationStore.history()](ui/NavigationStore/history.md): Get the pages in a stack, root first, or every page in every stack.
|
|
33667
|
+
- [NavigationStore.forward()](ui/NavigationStore/forward.md): Go forward to a URL, as a link does.
|
|
33668
|
+
- [NavigationStore.back()](ui/NavigationStore/back.md): Go back to a URL, as a back button does.
|
|
33669
|
+
- [NavigationStore.replace()](ui/NavigationStore/replace.md): Replace the current URL, with no transition.
|
|
32859
33670
|
|
|
32860
33671
|
|
|
32861
33672
|
---
|
|
32862
33673
|
|
|
32863
|
-
# NavigationStore.
|
|
33674
|
+
# NavigationStore.listen()
|
|
32864
33675
|
|
|
32865
33676
|
- Kind: method
|
|
32866
33677
|
- Member of: `NavigationStore`
|
|
32867
33678
|
|
|
32868
|
-
|
|
33679
|
+
Start listening to the browser (back, forward and swipe).
|
|
33680
|
+
- Saves the current stack and depth on the current history entry, if it has none.
|
|
33681
|
+
- `<Navigation>` calls it once, when it mounts.
|
|
32869
33682
|
|
|
32870
33683
|
## Signatures
|
|
32871
33684
|
|
|
32872
33685
|
```ts
|
|
32873
|
-
|
|
33686
|
+
listen(): () => void
|
|
32874
33687
|
```
|
|
32875
33688
|
|
|
32876
33689
|
|
|
32877
33690
|
---
|
|
32878
33691
|
|
|
32879
|
-
# NavigationStore.
|
|
33692
|
+
# NavigationStore.history()
|
|
32880
33693
|
|
|
32881
33694
|
- Kind: method
|
|
32882
33695
|
- Member of: `NavigationStore`
|
|
32883
33696
|
|
|
32884
|
-
|
|
33697
|
+
Get the pages in a stack, root first, or every page in every stack.
|
|
33698
|
+
- Read from the browser history entries up to the current one.
|
|
33699
|
+
- A stack whose root entry is gone (the browser keeps a limited history) still starts with its root.
|
|
33700
|
+
- Without the Navigation API this is always empty.
|
|
32885
33701
|
|
|
32886
33702
|
## Signatures
|
|
32887
33703
|
|
|
32888
33704
|
```ts
|
|
32889
|
-
|
|
33705
|
+
history(stack: AbsolutePath = this.stack.value): AbsolutePath[]
|
|
33706
|
+
```
|
|
33707
|
+
|
|
33708
|
+
|
|
33709
|
+
---
|
|
33710
|
+
|
|
33711
|
+
# NavigationStore.forward()
|
|
33712
|
+
|
|
33713
|
+
- Kind: method
|
|
33714
|
+
- Member of: `NavigationStore`
|
|
33715
|
+
|
|
33716
|
+
Go forward to a URL, as a link does.
|
|
33717
|
+
- The URL is the top page of `stack`: switch to that stack, at the same depth. This is a tab switch.
|
|
33718
|
+
- Else push the URL onto `stack`, one level deeper than its top page.
|
|
33719
|
+
- The URL you are already on: replace it instead.
|
|
33720
|
+
- A change of stack slides by tab order. Else it slides forward.
|
|
33721
|
+
|
|
33722
|
+
## Signatures
|
|
33723
|
+
|
|
33724
|
+
```ts
|
|
33725
|
+
forward(possible: PossibleURL, stack: AbsolutePath = this.stack.value): void
|
|
32890
33726
|
```
|
|
32891
33727
|
|
|
32892
33728
|
|
|
@@ -32897,14 +33733,35 @@ redirect(possible: PossibleURL): void
|
|
|
32897
33733
|
- Kind: method
|
|
32898
33734
|
- Member of: `NavigationStore`
|
|
32899
33735
|
|
|
32900
|
-
|
|
32901
|
-
-
|
|
32902
|
-
-
|
|
33736
|
+
Go back to a URL, as a back button does.
|
|
33737
|
+
- 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.
|
|
33738
|
+
- The URL is the root of `stack`: push it at depth 0.
|
|
33739
|
+
- Else push the URL in place of the top page of `stack`.
|
|
33740
|
+
- It works when the app was opened at the current page, so a back button always has somewhere to go.
|
|
33741
|
+
|
|
33742
|
+
## Signatures
|
|
33743
|
+
|
|
33744
|
+
```ts
|
|
33745
|
+
back(possible: PossibleURL, stack: AbsolutePath = this.stack.value): void
|
|
33746
|
+
```
|
|
33747
|
+
|
|
33748
|
+
|
|
33749
|
+
---
|
|
33750
|
+
|
|
33751
|
+
# NavigationStore.replace()
|
|
33752
|
+
|
|
33753
|
+
- Kind: method
|
|
33754
|
+
- Member of: `NavigationStore`
|
|
33755
|
+
|
|
33756
|
+
Replace the current URL, with no transition.
|
|
33757
|
+
- The page stays in the same stack, at the same depth, so a cached page stays mounted.
|
|
33758
|
+
- Use it for a page that knows its canonical URL, or for in-page tabs.
|
|
33759
|
+
- 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")`.
|
|
32903
33760
|
|
|
32904
33761
|
## Signatures
|
|
32905
33762
|
|
|
32906
33763
|
```ts
|
|
32907
|
-
|
|
33764
|
+
replace(possible: PossibleURL, stack: AbsolutePath = this.stack.value): void
|
|
32908
33765
|
```
|
|
32909
33766
|
|
|
32910
33767
|
|
|
@@ -32915,7 +33772,7 @@ back(possible: PossibleURL): void
|
|
|
32915
33772
|
- Kind: interface
|
|
32916
33773
|
- Import: `import { RouteCacheProps } from "shelving/ui";`
|
|
32917
33774
|
|
|
32918
|
-
Props for `<RouteCache
|
|
33775
|
+
Props for `<RouteCache>`: the `maxCached` size and the content `children` to keep alive for each page in the stacks.
|
|
32919
33776
|
|
|
32920
33777
|
## Signatures
|
|
32921
33778
|
|
|
@@ -32930,8 +33787,8 @@ Props for `<RouteCache>` — the `maxCached` size and the content `children` to
|
|
|
32930
33787
|
|
|
32931
33788
|
| Property | Type | Description |
|
|
32932
33789
|
| --- | --- | --- |
|
|
32933
|
-
| `maxCached` | `number \| undefined` | Number of
|
|
32934
|
-
| `children` | `ReactNode` | The content to render for the current
|
|
33790
|
+
| `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`. |
|
|
33791
|
+
| `children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
|
|
32935
33792
|
|
|
32936
33793
|
|
|
32937
33794
|
---
|
|
@@ -32941,171 +33798,105 @@ Props for `<RouteCache>` — the `maxCached` size and the content `children` to
|
|
|
32941
33798
|
- Kind: component
|
|
32942
33799
|
- Import: `import { RouteCache } from "shelving/ui";`
|
|
32943
33800
|
|
|
32944
|
-
Keep-alive page cache
|
|
33801
|
+
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.
|
|
32945
33802
|
|
|
32946
|
-
-
|
|
32947
|
-
|
|
32948
|
-
|
|
32949
|
-
-
|
|
32950
|
-
-
|
|
32951
|
-
-
|
|
32952
|
-
-
|
|
32953
|
-
|
|
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).
|
|
33803
|
+
- Put a page transition around it, and a `<Scroll vertical cover>` inside it, so each kept page scrolls in its own box.
|
|
33804
|
+
- 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.
|
|
33805
|
+
- 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.
|
|
33806
|
+
- 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.
|
|
33807
|
+
- 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.
|
|
33808
|
+
- 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.
|
|
33809
|
+
- `<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.
|
|
33810
|
+
- Without the browser Navigation API (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
|
|
32960
33811
|
|
|
32961
|
-
A keep-alive
|
|
33812
|
+
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.
|
|
32962
33813
|
|
|
32963
|
-
|
|
33814
|
+
Layouts do not include a cache. The app composes it, so it can also choose the transition, or leave the cache out.
|
|
32964
33815
|
|
|
32965
33816
|
**Things to know:**
|
|
32966
33817
|
|
|
32967
|
-
-
|
|
32968
|
-
- A page
|
|
32969
|
-
-
|
|
32970
|
-
- The
|
|
32971
|
-
-
|
|
32972
|
-
-
|
|
32973
|
-
-
|
|
32974
|
-
-
|
|
33818
|
+
- Each page is keyed by its stack and its depth in that stack, not by its URL. See `NavigationStore` for how stacks work.
|
|
33819
|
+
- 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.
|
|
33820
|
+
- 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.
|
|
33821
|
+
- 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.
|
|
33822
|
+
- `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}>`.
|
|
33823
|
+
- The same URL open in two stacks is two separate pages.
|
|
33824
|
+
- 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).
|
|
33825
|
+
- Each kept page is frozen under its own `<Meta>`, so a hidden page never re-renders for another page's URL.
|
|
33826
|
+
- `<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.
|
|
33827
|
+
- **Nesting:** layout, then transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. See the usage below.
|
|
33828
|
+
- 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.
|
|
33829
|
+
- Put a page `<Transition>` **around** the `<RouteCache>`, not inside it. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
|
|
33830
|
+
- 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.
|
|
33831
|
+
- Without the browser Navigation API, or with `maxCached={0}`, there is no cache: the current page renders directly and unmounts when you leave it.
|
|
32975
33832
|
|
|
32976
33833
|
## Usage
|
|
32977
33834
|
|
|
32978
33835
|
```tsx
|
|
32979
|
-
import { RouteCache } from "shelving/ui";
|
|
33836
|
+
import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
|
|
32980
33837
|
|
|
32981
|
-
<
|
|
32982
|
-
<
|
|
32983
|
-
<
|
|
32984
|
-
|
|
32985
|
-
|
|
32986
|
-
|
|
32987
|
-
|
|
32988
|
-
|
|
32989
|
-
|
|
32990
|
-
|
|
32991
|
-
|
|
32992
|
-
RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode
|
|
33838
|
+
<AppLayout nav={<StackBar />}>
|
|
33839
|
+
<HorizontalTransition>
|
|
33840
|
+
<RouteCache>
|
|
33841
|
+
<Scroll vertical cover>
|
|
33842
|
+
<PageLoader>
|
|
33843
|
+
<Router routes={ROUTES}/>
|
|
33844
|
+
</PageLoader>
|
|
33845
|
+
</Scroll>
|
|
33846
|
+
</RouteCache>
|
|
33847
|
+
</HorizontalTransition>
|
|
33848
|
+
</AppLayout>
|
|
32993
33849
|
```
|
|
32994
33850
|
|
|
32995
|
-
|
|
33851
|
+
Keep fewer pages:
|
|
32996
33852
|
|
|
32997
|
-
|
|
32998
|
-
|
|
32999
|
-
|
|
33000
|
-
|
|
33001
|
-
|
|
33002
|
-
|
|
33003
|
-
## Returns
|
|
33004
|
-
|
|
33005
|
-
| Type | Description |
|
|
33006
|
-
| --- | --- |
|
|
33007
|
-
| `ReactNode` | |
|
|
33008
|
-
|
|
33009
|
-
|
|
33010
|
-
---
|
|
33011
|
-
|
|
33012
|
-
# RouteConfigProps
|
|
33013
|
-
|
|
33014
|
-
- Kind: interface
|
|
33015
|
-
- Import: `import { RouteConfigProps } from "shelving/ui";`
|
|
33016
|
-
|
|
33017
|
-
Props for `<RouteConfig>` — the settings of a page for the surrounding `<Router>` and `<RouteCache>`, and the page content.
|
|
33018
|
-
|
|
33019
|
-
## Signatures
|
|
33020
|
-
|
|
33021
|
-
```ts
|
|
33022
|
-
{
|
|
33023
|
-
readonly path?: AbsolutePath | undefined;
|
|
33024
|
-
readonly cache?: boolean | undefined;
|
|
33025
|
-
readonly children?: ReactNode;
|
|
33026
|
-
}
|
|
33853
|
+
```tsx
|
|
33854
|
+
<RouteCache maxCached={5}>
|
|
33855
|
+
<Scroll vertical cover>
|
|
33856
|
+
<Router routes={ROUTES}/>
|
|
33857
|
+
</Scroll>
|
|
33858
|
+
</RouteCache>
|
|
33027
33859
|
```
|
|
33028
33860
|
|
|
33029
|
-
|
|
33030
|
-
|
|
33031
|
-
| Property | Type | Description |
|
|
33032
|
-
| --- | --- | --- |
|
|
33033
|
-
| `path` | `AbsolutePath \| undefined` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. Optional. |
|
|
33034
|
-
| `cache` | `boolean \| undefined` | Set to `false` so `<RouteCache>` drops the page when you leave it, and the next visit shows a new page. Defaults to `true`. Read only. Optional. |
|
|
33035
|
-
| `children` | `ReactNode` | The page content. Read only. Optional. |
|
|
33036
|
-
|
|
33037
|
-
|
|
33038
|
-
---
|
|
33039
|
-
|
|
33040
|
-
# RouteConfig
|
|
33041
|
-
|
|
33042
|
-
- Kind: component
|
|
33043
|
-
- Import: `import { RouteConfig } from "shelving/ui";`
|
|
33044
|
-
|
|
33045
|
-
Configure the current page for the surrounding `<Router>` (and `<RouteCache>`).
|
|
33046
|
-
- `path` says the page owns every path that matches a template. A navigation to a path the page owns keeps the same
|
|
33047
|
-
page mounted, so it keeps its scroll and state, and a `<ViewTransition>` around the page does not run an enter or
|
|
33048
|
-
exit. The page updates for the new URL. Use it for a page whose tabs each have their own path: `path="/dave/{tab}"`.
|
|
33049
|
-
- Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
|
|
33050
|
-
- `cache={false}` makes `<RouteCache>` drop the page when you leave it, so the next visit starts again with no old
|
|
33051
|
-
state. Use it for a form that makes or edits something, for example a "New challenge" page.
|
|
33052
|
-
|
|
33053
|
-
Configure the current page for the surrounding `<Router>` (and `<RouteCache>`, if there is one). It has one prop for each setting, so a page wraps itself in one `<RouteConfig>` for all its settings.
|
|
33054
|
-
|
|
33055
|
-
- `path` says the page owns every path that matches a template. A navigation between paths the page owns keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide. Use it for a page whose tabs each have their own path.
|
|
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.
|
|
33057
|
-
|
|
33058
|
-
**Things to know:**
|
|
33059
|
-
|
|
33060
|
-
- Without `path`, each path is its own page, so `/challenge/123` and `/challenge/456` stay separate pages.
|
|
33061
|
-
- Put the real values in the template (`/dave/{tab}`). A template such as `/{name}/{tab}` makes every profile the same page.
|
|
33062
|
-
- The page still renders for the new URL, so it reads the tab from the URL as usual.
|
|
33063
|
-
- The cache key is the path only, not the `?query`. A page that reads its `?query` once (for example `/new?from=123`) should use `cache={false}`, so a visit with another `?query` does not show the old page.
|
|
33064
|
-
- It works with or without a `<RouteCache>`. In a nested router's page, it tells only that nested router.
|
|
33065
|
-
|
|
33066
|
-
## Usage
|
|
33861
|
+
Clear a create form after it saves. Change the `key` of the `<Form>`, so it mounts again with no input:
|
|
33067
33862
|
|
|
33068
33863
|
```tsx
|
|
33069
|
-
import {
|
|
33070
|
-
|
|
33071
|
-
// Each tab has its own path, and all of them are the same page.
|
|
33072
|
-
function ProfilePage({ name, tab }: { name: string; tab?: string }) {
|
|
33073
|
-
return (
|
|
33074
|
-
<RouteConfig path={`/${name}/{tab}`}>
|
|
33075
|
-
<Page title={name}>
|
|
33076
|
-
<ProfileTabs tab={tab} />
|
|
33077
|
-
</Page>
|
|
33078
|
-
</RouteConfig>
|
|
33079
|
-
);
|
|
33080
|
-
}
|
|
33864
|
+
import { useState } from "react";
|
|
33865
|
+
import { Form, requireNavigation } from "shelving/ui";
|
|
33081
33866
|
|
|
33082
|
-
|
|
33083
|
-
|
|
33867
|
+
function NewPostPage() {
|
|
33868
|
+
const nav = requireNavigation();
|
|
33869
|
+
const [formKey, setFormKey] = useState(0);
|
|
33084
33870
|
return (
|
|
33085
|
-
<
|
|
33086
|
-
|
|
33087
|
-
|
|
33088
|
-
|
|
33089
|
-
|
|
33871
|
+
<Form
|
|
33872
|
+
key={formKey}
|
|
33873
|
+
schema={POST_SCHEMA}
|
|
33874
|
+
onSubmit={async data => {
|
|
33875
|
+
const id = await createPost(data);
|
|
33876
|
+
setFormKey(k => k + 1);
|
|
33877
|
+
nav.forward(`/post/${id}`);
|
|
33878
|
+
}}
|
|
33879
|
+
/>
|
|
33090
33880
|
);
|
|
33091
33881
|
}
|
|
33092
33882
|
```
|
|
33093
33883
|
|
|
33884
|
+
For a plain HTML `<form>`, call `form.reset()` after the submit.
|
|
33885
|
+
|
|
33094
33886
|
|
|
33095
33887
|
## Signatures
|
|
33096
33888
|
|
|
33097
33889
|
```ts
|
|
33098
|
-
|
|
33890
|
+
RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode
|
|
33099
33891
|
```
|
|
33100
33892
|
|
|
33101
33893
|
## Parameters
|
|
33102
33894
|
|
|
33103
33895
|
| Param | Type | Description |
|
|
33104
33896
|
| --- | --- | --- |
|
|
33105
|
-
| `props` | `
|
|
33106
|
-
| `.
|
|
33107
|
-
| `.
|
|
33108
|
-
| `.children` | `ReactNode` | The page content. Read only. Optional. |
|
|
33897
|
+
| `props` | `RouteCacheProps` | |
|
|
33898
|
+
| `.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`. |
|
|
33899
|
+
| `.children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
|
|
33109
33900
|
|
|
33110
33901
|
## Returns
|
|
33111
33902
|
|
|
@@ -33114,50 +33905,6 @@ RouteConfig({ path, cache, children }: RouteConfigProps): ReactNode
|
|
|
33114
33905
|
| `ReactNode` | |
|
|
33115
33906
|
|
|
33116
33907
|
|
|
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
33908
|
---
|
|
33162
33909
|
|
|
33163
33910
|
# RouterProps
|
|
@@ -33197,7 +33944,8 @@ Match the current URL against `routes` and render the matched element.
|
|
|
33197
33944
|
- When `base` is set, the effective path is the URL after stripping the base prefix.
|
|
33198
33945
|
- Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
|
|
33199
33946
|
- 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
|
-
-
|
|
33947
|
+
- 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.
|
|
33948
|
+
- Elsewhere, each path is a new page, so a component route remounts when the path changes.
|
|
33201
33949
|
- Returns `null` when there's no URL in context or the URL is outside the base.
|
|
33202
33950
|
|
|
33203
33951
|
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,7 +33956,8 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
|
|
|
33208
33956
|
- `<Router>` accepts `PossibleMeta` props (`url`, `base`, etc.) to override the surrounding context — this is how nested routers scope themselves.
|
|
33209
33957
|
- 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
33958
|
- Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
|
|
33211
|
-
- `<
|
|
33959
|
+
- 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.
|
|
33960
|
+
- `<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.
|
|
33212
33961
|
|
|
33213
33962
|
## Usage
|
|
33214
33963
|
|
|
@@ -33254,7 +34003,7 @@ Modifier chars are tolerant: one-or-more stars and three-or-more dots are all eq
|
|
|
33254
34003
|
|
|
33255
34004
|
### Layout wrapping
|
|
33256
34005
|
|
|
33257
|
-
Put layout JSX as the route value with another `<Router>` inside. Since `<Router>` reads its URL from `<Meta>`, the inner router sees the same URL.
|
|
34006
|
+
Put layout JSX as the route value with another `<Router>` inside. Since `<Router>` reads its URL from `<Meta>`, the inner router sees the same URL. A layout's content slot does not scroll, so put a `<Scroll vertical cover>` in it (and a `<RouteCache>` around that, to keep pages). See "Composing an app" on `<App>`.
|
|
33258
34007
|
|
|
33259
34008
|
```tsx
|
|
33260
34009
|
const SIDEBARRED_ROUTES = {
|
|
@@ -33267,7 +34016,9 @@ const SIDEBARRED_ROUTES = {
|
|
|
33267
34016
|
"/": <HomePage/>,
|
|
33268
34017
|
"/{...path}": (
|
|
33269
34018
|
<SidebarLayout sidebar={<Nav/>}>
|
|
33270
|
-
<
|
|
34019
|
+
<Scroll vertical cover>
|
|
34020
|
+
<Router routes={SIDEBARRED_ROUTES}/>
|
|
34021
|
+
</Scroll>
|
|
33271
34022
|
</SidebarLayout>
|
|
33272
34023
|
),
|
|
33273
34024
|
}}/>
|
|
@@ -33314,7 +34065,9 @@ const SIDEBARRED_ROUTES = {
|
|
|
33314
34065
|
"/login": <LoginPage/>, // no sidebar
|
|
33315
34066
|
"/{...path}": ( // everything else wrapped
|
|
33316
34067
|
<SidebarLayout sidebar={<Nav/>}>
|
|
33317
|
-
<
|
|
34068
|
+
<Scroll vertical cover>
|
|
34069
|
+
<Router routes={SIDEBARRED_ROUTES}/>
|
|
34070
|
+
</Scroll>
|
|
33318
34071
|
</SidebarLayout>
|
|
33319
34072
|
),
|
|
33320
34073
|
}}/>
|
|
@@ -33322,7 +34075,7 @@ const SIDEBARRED_ROUTES = {
|
|
|
33322
34075
|
|
|
33323
34076
|
### Keeping page state
|
|
33324
34077
|
|
|
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
|
|
34078
|
+
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 in a `<RouteCache>`, with a `<Scroll vertical cover>` between them, 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. Layouts do not do this for you: see `<RouteCache>` for the full nesting.
|
|
33326
34079
|
|
|
33327
34080
|
### SSR / static rendering
|
|
33328
34081
|
|
|
@@ -33464,6 +34217,99 @@ Route table mapping `{ path: RouteComponent | redirectPath | ReactElement }` for
|
|
|
33464
34217
|
- [Route](ui/Route.md): Valid route values:
|
|
33465
34218
|
|
|
33466
34219
|
|
|
34220
|
+
---
|
|
34221
|
+
|
|
34222
|
+
# StackButtonProps
|
|
34223
|
+
|
|
34224
|
+
- Kind: interface
|
|
34225
|
+
- Import: `import { StackButtonProps } from "shelving/ui";`
|
|
34226
|
+
- Extends: `Omit<ButtonProps, "href" | "onClick" | "selected">`
|
|
34227
|
+
|
|
34228
|
+
Props for `<StackButton>`: the `stack` it opens, plus the usual `Button` props except `href` and `onClick`.
|
|
34229
|
+
|
|
34230
|
+
## Signatures
|
|
34231
|
+
|
|
34232
|
+
```ts
|
|
34233
|
+
{
|
|
34234
|
+
readonly stack: AbsolutePath;
|
|
34235
|
+
}
|
|
34236
|
+
```
|
|
34237
|
+
|
|
34238
|
+
## Properties
|
|
34239
|
+
|
|
34240
|
+
| Property | Type | Description |
|
|
34241
|
+
| --- | --- | --- |
|
|
34242
|
+
| `stack` | `AbsolutePath` | Root path of the stack this button opens. It must be one of the `stacks` on `<Navigation>`. Read only. |
|
|
34243
|
+
|
|
34244
|
+
|
|
34245
|
+
---
|
|
34246
|
+
|
|
34247
|
+
# StackButton
|
|
34248
|
+
|
|
34249
|
+
- Kind: component
|
|
34250
|
+
- Import: `import { StackButton } from "shelving/ui";`
|
|
34251
|
+
|
|
34252
|
+
Button for one stack in a tab bar.
|
|
34253
|
+
- Tap another stack's button: go to the page you left in that stack. The page slides left or right by tab order.
|
|
34254
|
+
- Tap the current stack's button: go back to its root.
|
|
34255
|
+
- Tap it again at the root: scroll the page to the top.
|
|
34256
|
+
- It is selected while its stack is the current stack.
|
|
34257
|
+
- Without the browser Navigation API (and in a server render) it is a plain link to the stack's root.
|
|
34258
|
+
|
|
34259
|
+
A button for one stack in a tab bar. It acts like a tab button in a phone app.
|
|
34260
|
+
|
|
34261
|
+
**Things to know:**
|
|
34262
|
+
|
|
34263
|
+
- Tap another stack's button: go to the page you left in that stack. The page slides left or right, by tab order.
|
|
34264
|
+
- Tap the current stack's button: go back to the root of the stack. The page slides back.
|
|
34265
|
+
- Tap it again at the root: scroll the page to the top. It scrolls the window, and each visible `<main>` or `[data-scroll]` element.
|
|
34266
|
+
- 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.
|
|
34267
|
+
- `stack` must be one of the `stacks` on `<Navigation>`.
|
|
34268
|
+
- It takes the usual `<Button>` props, except `href`, `onClick` and `selected`.
|
|
34269
|
+
- 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.
|
|
34270
|
+
- 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.
|
|
34271
|
+
|
|
34272
|
+
## Usage
|
|
34273
|
+
|
|
34274
|
+
```tsx
|
|
34275
|
+
import { Navigation, StackButton } from "shelving/ui";
|
|
34276
|
+
import { HomeIcon, SearchIcon, UserIcon } from "./icons.js";
|
|
34277
|
+
|
|
34278
|
+
<Navigation stacks={["/home", "/discover", "/profile"]}>
|
|
34279
|
+
{/* … */}
|
|
34280
|
+
<nav className="tab-bar">
|
|
34281
|
+
<StackButton stack="/home" title="Home"><HomeIcon/></StackButton>
|
|
34282
|
+
<StackButton stack="/discover" title="Discover"><SearchIcon/></StackButton>
|
|
34283
|
+
<StackButton stack="/profile" title="Profile"><UserIcon/></StackButton>
|
|
34284
|
+
</nav>
|
|
34285
|
+
</Navigation>
|
|
34286
|
+
```
|
|
34287
|
+
|
|
34288
|
+
## Styling
|
|
34289
|
+
|
|
34290
|
+
`<StackButton>` renders a `<Button>`, so it has the same styling hooks. See `<Button>`.
|
|
34291
|
+
|
|
34292
|
+
|
|
34293
|
+
## Signatures
|
|
34294
|
+
|
|
34295
|
+
```ts
|
|
34296
|
+
StackButton({ stack, ...props }: StackButtonProps): ReactElement
|
|
34297
|
+
```
|
|
34298
|
+
|
|
34299
|
+
## Parameters
|
|
34300
|
+
|
|
34301
|
+
| Param | Type | Description |
|
|
34302
|
+
| --- | --- | --- |
|
|
34303
|
+
| `props` | `StackButtonProps` | |
|
|
34304
|
+
| `.stack` | `AbsolutePath` | Root path of the stack this button opens. It must be one of the `stacks` on `<Navigation>`. Read only. |
|
|
34305
|
+
|
|
34306
|
+
## Returns
|
|
34307
|
+
|
|
34308
|
+
| Type | Description |
|
|
34309
|
+
| --- | --- |
|
|
34310
|
+
| `ReactElement` | |
|
|
34311
|
+
|
|
34312
|
+
|
|
33467
34313
|
---
|
|
33468
34314
|
|
|
33469
34315
|
# BlockVariants
|
|
@@ -33490,7 +34336,7 @@ Variants for block level elements.
|
|
|
33490
34336
|
|
|
33491
34337
|
Get the combined `className` string for a block from its styling variants.
|
|
33492
34338
|
|
|
33493
|
-
Composes the base block class and tint ladder with the colour, space, typography, and
|
|
34339
|
+
Composes the base block class and tint ladder with the colour, space, typography, width, and height variant helpers, so anything that wants block-level styling can apply it.
|
|
33494
34340
|
|
|
33495
34341
|
## Signatures
|
|
33496
34342
|
|
|
@@ -33850,7 +34696,7 @@ Variant props for the gap between a component's children, e.g. `gap="large"`.
|
|
|
33850
34696
|
|
|
33851
34697
|
```ts
|
|
33852
34698
|
{
|
|
33853
|
-
gap?: SpaceValue | undefined;
|
|
34699
|
+
gap?: Exclude<SpaceValue, "auto"> | undefined;
|
|
33854
34700
|
}
|
|
33855
34701
|
```
|
|
33856
34702
|
|
|
@@ -33858,7 +34704,7 @@ Variant props for the gap between a component's children, e.g. `gap="large"`.
|
|
|
33858
34704
|
|
|
33859
34705
|
| Property | Type | Description |
|
|
33860
34706
|
| --- | --- | --- |
|
|
33861
|
-
| `gap` | `SpaceValue \| undefined` | Gap between child elements. Optional. |
|
|
34707
|
+
| `gap` | `Exclude<SpaceValue, "auto"> \| undefined` | Gap between child elements. Optional. |
|
|
33862
34708
|
|
|
33863
34709
|
|
|
33864
34710
|
---
|
|
@@ -33881,7 +34727,7 @@ getGapClass({ gap }: GapVariants): string | undefined
|
|
|
33881
34727
|
| Param | Type | Description |
|
|
33882
34728
|
| --- | --- | --- |
|
|
33883
34729
|
| `options` | `GapVariants` | |
|
|
33884
|
-
| `.gap` | `SpaceValue \| undefined` | Gap between child elements. Optional. |
|
|
34730
|
+
| `.gap` | `Exclude<SpaceValue, "auto"> \| undefined` | Gap between child elements. Optional. |
|
|
33885
34731
|
|
|
33886
34732
|
## Returns
|
|
33887
34733
|
|
|
@@ -33996,6 +34842,138 @@ getGridClass({ columns: 3, gap: "normal" })
|
|
|
33996
34842
|
```
|
|
33997
34843
|
|
|
33998
34844
|
|
|
34845
|
+
---
|
|
34846
|
+
|
|
34847
|
+
# HeightVariant
|
|
34848
|
+
|
|
34849
|
+
- Kind: type
|
|
34850
|
+
- Import: `import { HeightVariant } from "shelving/ui";`
|
|
34851
|
+
|
|
34852
|
+
Enumerated height selectable via the `height` variant prop.
|
|
34853
|
+
- `full` — at least the full height of the container.
|
|
34854
|
+
- `1x`–`32x` — at least a multiple of `--space-normal` (1x–8x at 1x intervals, then 10x/12x, then 16x–32x at 4x intervals).
|
|
34855
|
+
- Each value is a minimum (`min-block-size`), so the element grows when its content is taller and nothing is cut off.
|
|
34856
|
+
|
|
34857
|
+
## Signatures
|
|
34858
|
+
|
|
34859
|
+
```ts
|
|
34860
|
+
| "full"
|
|
34861
|
+
| "1x"
|
|
34862
|
+
| "2x"
|
|
34863
|
+
| "3x"
|
|
34864
|
+
| "4x"
|
|
34865
|
+
| "5x"
|
|
34866
|
+
| "6x"
|
|
34867
|
+
| "7x"
|
|
34868
|
+
| "8x"
|
|
34869
|
+
| "10x"
|
|
34870
|
+
| "12x"
|
|
34871
|
+
| "16x"
|
|
34872
|
+
| "20x"
|
|
34873
|
+
| "24x"
|
|
34874
|
+
| "28x"
|
|
34875
|
+
| "32x"
|
|
34876
|
+
```
|
|
34877
|
+
|
|
34878
|
+
|
|
34879
|
+
---
|
|
34880
|
+
|
|
34881
|
+
# HeightVariants
|
|
34882
|
+
|
|
34883
|
+
- Kind: interface
|
|
34884
|
+
- Import: `import { HeightVariants } from "shelving/ui";`
|
|
34885
|
+
|
|
34886
|
+
Variant props that set a component's height, and where its content sits inside that height, e.g. `height="full" middle`.
|
|
34887
|
+
|
|
34888
|
+
## Signatures
|
|
34889
|
+
|
|
34890
|
+
```ts
|
|
34891
|
+
{
|
|
34892
|
+
height?: HeightVariant | undefined;
|
|
34893
|
+
top?: boolean | undefined;
|
|
34894
|
+
middle?: boolean | undefined;
|
|
34895
|
+
bottom?: boolean | undefined;
|
|
34896
|
+
}
|
|
34897
|
+
```
|
|
34898
|
+
|
|
34899
|
+
## Properties
|
|
34900
|
+
|
|
34901
|
+
| Property | Type | Description |
|
|
34902
|
+
| --- | --- | --- |
|
|
34903
|
+
| `height` | `HeightVariant \| undefined` | Height of the element. It is a minimum, so the element grows when its content is taller. Optional. |
|
|
34904
|
+
| `top` | `boolean \| undefined` | Put the content at the top of the element (the default). Optional. |
|
|
34905
|
+
| `middle` | `boolean \| undefined` | Put the content in the vertical middle of the element. Use with `height`. Optional. |
|
|
34906
|
+
| `bottom` | `boolean \| undefined` | Put the content at the bottom of the element. Use with `height`. Optional. |
|
|
34907
|
+
|
|
34908
|
+
|
|
34909
|
+
---
|
|
34910
|
+
|
|
34911
|
+
# getHeightClass()
|
|
34912
|
+
|
|
34913
|
+
- Kind: function
|
|
34914
|
+
- Import: `import { getHeightClass } from "shelving/ui";`
|
|
34915
|
+
|
|
34916
|
+
Get the height class for a component from its `height`, `top`, `middle` and `bottom` variant props.
|
|
34917
|
+
|
|
34918
|
+
The `height` variant prop sets a component's minimum block size, and `top` / `middle` / `bottom` set where its content sits inside that height — `<Block height="full" middle>`, `<Section height="12x" bottom>`. It is the vertical partner of the `width` variant (see `getWidthClass()`).
|
|
34919
|
+
|
|
34920
|
+
`getHeightClass({ height, top, middle, bottom })` maps the props to height classes.
|
|
34921
|
+
|
|
34922
|
+
**Values:**
|
|
34923
|
+
|
|
34924
|
+
- `full` — at least the full height of the container, for example a layout's `<Scroll vertical cover>` box.
|
|
34925
|
+
- `1x` / `2x` / `3x` / `4x` / `5x` / `6x` / `7x` / `8x` / `10x` / `12x` / `16x` / `20x` / `24x` / `28x` / `32x` — at least a multiple of `--space-normal`.
|
|
34926
|
+
|
|
34927
|
+
**Things to know:**
|
|
34928
|
+
|
|
34929
|
+
- Every height is a minimum (`min-block-size`). When the content is taller, the element grows, so a scroll box scrolls it from the top and nothing is cut off.
|
|
34930
|
+
- `top` (the default), `middle` and `bottom` set `align-content` on the element itself. The element keeps its own `display`, so its parent does not need to be a flex box. They only do something when the element is taller than its content, so use them with `height`.
|
|
34931
|
+
- `<Row>` and `<Column>` already have `top` / `middle` / `bottom` flex variants with the same meaning, so `<Column height="full" middle>` also puts its items in the middle (see `getFlexClass()`).
|
|
34932
|
+
- In a flex or grid container, `space="auto"` is the other way to centre a block (see `getSpaceClass()`).
|
|
34933
|
+
- `align-content` on a plain block shipped in Chrome 123, Firefox 125 and Safari 17.4. Older browsers show the content at the top.
|
|
34934
|
+
|
|
34935
|
+
## Usage
|
|
34936
|
+
|
|
34937
|
+
A log-in screen, in the middle of a layout's scroll box:
|
|
34938
|
+
|
|
34939
|
+
```tsx
|
|
34940
|
+
<Page title="Log in">
|
|
34941
|
+
<Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
|
|
34942
|
+
<LoginForm />
|
|
34943
|
+
</Block>
|
|
34944
|
+
</Page>
|
|
34945
|
+
```
|
|
34946
|
+
|
|
34947
|
+
|
|
34948
|
+
## Signatures
|
|
34949
|
+
|
|
34950
|
+
```ts
|
|
34951
|
+
getHeightClass({ height, top, middle, bottom }: HeightVariants): string | undefined
|
|
34952
|
+
```
|
|
34953
|
+
|
|
34954
|
+
## Parameters
|
|
34955
|
+
|
|
34956
|
+
| Param | Type | Description |
|
|
34957
|
+
| --- | --- | --- |
|
|
34958
|
+
| `options` | `HeightVariants` | |
|
|
34959
|
+
| `.height` | `HeightVariant \| undefined` | Height of the element. It is a minimum, so the element grows when its content is taller. Optional. |
|
|
34960
|
+
| `.top` | `boolean \| undefined` | Put the content at the top of the element (the default). Optional. |
|
|
34961
|
+
| `.middle` | `boolean \| undefined` | Put the content in the vertical middle of the element. Use with `height`. Optional. |
|
|
34962
|
+
| `.bottom` | `boolean \| undefined` | Put the content at the bottom of the element. Use with `height`. Optional. |
|
|
34963
|
+
|
|
34964
|
+
## Returns
|
|
34965
|
+
|
|
34966
|
+
| Type | Description |
|
|
34967
|
+
| --- | --- |
|
|
34968
|
+
| `string \| undefined` | The height class string, or `undefined` if no height variants are set. |
|
|
34969
|
+
|
|
34970
|
+
## Examples
|
|
34971
|
+
|
|
34972
|
+
```ts
|
|
34973
|
+
getHeightClass({ height: "full", middle: true }) // "height height-full middle"
|
|
34974
|
+
```
|
|
34975
|
+
|
|
34976
|
+
|
|
33999
34977
|
---
|
|
34000
34978
|
|
|
34001
34979
|
# IndentVariant
|
|
@@ -34101,7 +35079,7 @@ Variant props for the block-padding (top + bottom) of a component, e.g. `padding
|
|
|
34101
35079
|
|
|
34102
35080
|
```ts
|
|
34103
35081
|
{
|
|
34104
|
-
padding?: SpaceValue | undefined;
|
|
35082
|
+
padding?: Exclude<SpaceValue, "auto"> | undefined;
|
|
34105
35083
|
}
|
|
34106
35084
|
```
|
|
34107
35085
|
|
|
@@ -34109,7 +35087,7 @@ Variant props for the block-padding (top + bottom) of a component, e.g. `padding
|
|
|
34109
35087
|
|
|
34110
35088
|
| Property | Type | Description |
|
|
34111
35089
|
| --- | --- | --- |
|
|
34112
|
-
| `padding` | `SpaceValue \| undefined` | Block-padding (top + bottom) of the element. Optional. |
|
|
35090
|
+
| `padding` | `Exclude<SpaceValue, "auto"> \| undefined` | Block-padding (top + bottom) of the element. Optional. |
|
|
34113
35091
|
|
|
34114
35092
|
|
|
34115
35093
|
---
|
|
@@ -34132,7 +35110,7 @@ getPaddingClass({ padding }: PaddingVariants): string | undefined
|
|
|
34132
35110
|
| Param | Type | Description |
|
|
34133
35111
|
| --- | --- | --- |
|
|
34134
35112
|
| `options` | `PaddingVariants` | |
|
|
34135
|
-
| `.padding` | `SpaceValue \| undefined` | Block-padding (top + bottom) of the element. Optional. |
|
|
35113
|
+
| `.padding` | `Exclude<SpaceValue, "auto"> \| undefined` | Block-padding (top + bottom) of the element. Optional. |
|
|
34136
35114
|
|
|
34137
35115
|
## Returns
|
|
34138
35116
|
|
|
@@ -34246,7 +35224,7 @@ getRadiusClass({ radius: "large" }) // "radius-large"
|
|
|
34246
35224
|
- Kind: interface
|
|
34247
35225
|
- Import: `import { ScrollVariants } from "shelving/ui";`
|
|
34248
35226
|
|
|
34249
|
-
Variant props
|
|
35227
|
+
Variant props for a scroll region: which axes scroll, plus `cover` and `reverse`.
|
|
34250
35228
|
|
|
34251
35229
|
## Signatures
|
|
34252
35230
|
|
|
@@ -34254,6 +35232,8 @@ Variant props selecting which scroll axes are enabled on an element.
|
|
|
34254
35232
|
{
|
|
34255
35233
|
vertical?: boolean | undefined;
|
|
34256
35234
|
horizontal?: boolean | undefined;
|
|
35235
|
+
cover?: boolean | undefined;
|
|
35236
|
+
reverse?: boolean | undefined;
|
|
34257
35237
|
}
|
|
34258
35238
|
```
|
|
34259
35239
|
|
|
@@ -34263,6 +35243,8 @@ Variant props selecting which scroll axes are enabled on an element.
|
|
|
34263
35243
|
| --- | --- | --- |
|
|
34264
35244
|
| `vertical` | `boolean \| undefined` | Vertical scrolling (defaults to `false`). Optional. |
|
|
34265
35245
|
| `horizontal` | `boolean \| undefined` | Horizontal scrolling (defaults to `false`). Optional. |
|
|
35246
|
+
| `cover` | `boolean \| undefined` | Cover the nearest positioned ancestor (`position: absolute; inset: 0`), for example a layout's content slot (defaults to `false`). Optional. |
|
|
35247
|
+
| `reverse` | `boolean \| undefined` | Start at the end and stay there as the content grows, for example a chat (defaults to `false`). Put the content in one child. Optional. |
|
|
34266
35248
|
|
|
34267
35249
|
|
|
34268
35250
|
---
|
|
@@ -34272,12 +35254,12 @@ Variant props selecting which scroll axes are enabled on an element.
|
|
|
34272
35254
|
- Kind: function
|
|
34273
35255
|
- Import: `import { getScrollClass } from "shelving/ui";`
|
|
34274
35256
|
|
|
34275
|
-
Get the scroll class for a component from its `horizontal`
|
|
35257
|
+
Get the scroll class for a component from its `horizontal`, `vertical`, `cover` and `reverse` variant props.
|
|
34276
35258
|
|
|
34277
35259
|
## Signatures
|
|
34278
35260
|
|
|
34279
35261
|
```ts
|
|
34280
|
-
getScrollClass({ horizontal, vertical }: ScrollVariants): string
|
|
35262
|
+
getScrollClass({ horizontal, vertical, cover, reverse }: ScrollVariants): string
|
|
34281
35263
|
```
|
|
34282
35264
|
|
|
34283
35265
|
## Parameters
|
|
@@ -34287,6 +35269,8 @@ getScrollClass({ horizontal, vertical }: ScrollVariants): string
|
|
|
34287
35269
|
| `options` | `ScrollVariants` | |
|
|
34288
35270
|
| `.vertical` | `boolean \| undefined` | Vertical scrolling (defaults to `false`). Optional. |
|
|
34289
35271
|
| `.horizontal` | `boolean \| undefined` | Horizontal scrolling (defaults to `false`). Optional. |
|
|
35272
|
+
| `.cover` | `boolean \| undefined` | Cover the nearest positioned ancestor (`position: absolute; inset: 0`), for example a layout's content slot (defaults to `false`). Optional. |
|
|
35273
|
+
| `.reverse` | `boolean \| undefined` | Start at the end and stay there as the content grows, for example a chat (defaults to `false`). Put the content in one child. Optional. |
|
|
34290
35274
|
|
|
34291
35275
|
## Returns
|
|
34292
35276
|
|
|
@@ -34326,6 +35310,66 @@ Props for the `Scroll` component — children plus scroll-axis variants.
|
|
|
34326
35310
|
- Import: `import { Scroll } from "shelving/ui";`
|
|
34327
35311
|
|
|
34328
35312
|
Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
|
|
35313
|
+
- With `cover`, it fills a layout's content slot, so each page in a `<RouteCache>` scrolls in its own box.
|
|
35314
|
+
|
|
35315
|
+
A box that scrolls its content on one or both axes. Use it for a wide table on a small screen, or as the scroll box of each page in an app.
|
|
35316
|
+
|
|
35317
|
+
**Things to know:**
|
|
35318
|
+
|
|
35319
|
+
- Set `vertical`, `horizontal`, or both. With neither, the box clips its content and does not scroll.
|
|
35320
|
+
- Set `cover` to fill the nearest positioned ancestor (`position: absolute; inset: 0`). A layout's content slot is positioned, so `<Scroll vertical cover>` fills it.
|
|
35321
|
+
- Set `reverse` to start at the end and stay there when the content grows, for example a chat. Put the content in one child: only the scroll is reversed, so the child keeps its own order. No script is needed.
|
|
35322
|
+
- Overscroll stops at the box edge (`overscroll-behavior: none`), so a scroll inside the box never scrolls the page behind it.
|
|
35323
|
+
- When the box has keyboard focus, it shows a focus outline.
|
|
35324
|
+
|
|
35325
|
+
## Usage
|
|
35326
|
+
|
|
35327
|
+
### A wide table
|
|
35328
|
+
|
|
35329
|
+
```tsx
|
|
35330
|
+
import { Scroll, Table } from "shelving/ui";
|
|
35331
|
+
|
|
35332
|
+
<Scroll horizontal>
|
|
35333
|
+
<Table>…</Table>
|
|
35334
|
+
</Scroll>
|
|
35335
|
+
```
|
|
35336
|
+
|
|
35337
|
+
### A scroll box for each page
|
|
35338
|
+
|
|
35339
|
+
Put `<Scroll vertical cover>` inside `<RouteCache>`, so each kept page has its own scroll box and keeps its own scroll position. The layout gives its content slot `position: relative`, and the scroll box fills it.
|
|
35340
|
+
|
|
35341
|
+
```tsx
|
|
35342
|
+
import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
|
|
35343
|
+
|
|
35344
|
+
<AppLayout nav={<StackBar />}>
|
|
35345
|
+
<HorizontalTransition>
|
|
35346
|
+
<RouteCache>
|
|
35347
|
+
<Scroll vertical cover>
|
|
35348
|
+
<PageLoader>
|
|
35349
|
+
<Router routes={ROUTES} />
|
|
35350
|
+
</PageLoader>
|
|
35351
|
+
</Scroll>
|
|
35352
|
+
</RouteCache>
|
|
35353
|
+
</HorizontalTransition>
|
|
35354
|
+
</AppLayout>
|
|
35355
|
+
```
|
|
35356
|
+
|
|
35357
|
+
### A chat
|
|
35358
|
+
|
|
35359
|
+
```tsx
|
|
35360
|
+
<Scroll vertical cover reverse>
|
|
35361
|
+
<div>{messages}</div>
|
|
35362
|
+
</Scroll>
|
|
35363
|
+
```
|
|
35364
|
+
|
|
35365
|
+
## Styling
|
|
35366
|
+
|
|
35367
|
+
| Variable | Styles | Default |
|
|
35368
|
+
|---|---|---|
|
|
35369
|
+
| `--scroll-focus-border` | Outline when the box has keyboard focus | `var(--stroke-focus) solid var(--color-focus)` |
|
|
35370
|
+
|
|
35371
|
+
**Global tokens it reads** — `--stroke-focus`, `--stroke-normal`, and `--color-focus`.
|
|
35372
|
+
|
|
34329
35373
|
|
|
34330
35374
|
## Signatures
|
|
34331
35375
|
|
|
@@ -34345,12 +35389,6 @@ Scroll({ children, ...props }: ScrollComponentProps): ReactElement
|
|
|
34345
35389
|
| --- | --- |
|
|
34346
35390
|
| `ReactElement` | A `<div>` element with the computed scroll class. |
|
|
34347
35391
|
|
|
34348
|
-
## Examples
|
|
34349
|
-
|
|
34350
|
-
```ts
|
|
34351
|
-
<Scroll horizontal>{wideContent}</Scroll>
|
|
34352
|
-
```
|
|
34353
|
-
|
|
34354
35392
|
|
|
34355
35393
|
---
|
|
34356
35394
|
|
|
@@ -34460,6 +35498,7 @@ Allowed values for block spacing for components that support `SpaceVariants`
|
|
|
34460
35498
|
| "section"
|
|
34461
35499
|
| "paragraph"
|
|
34462
35500
|
| "none"
|
|
35501
|
+
| "auto"
|
|
34463
35502
|
| "xxsmall"
|
|
34464
35503
|
| "xsmall"
|
|
34465
35504
|
| "small"
|
|
@@ -34517,6 +35556,8 @@ The `space` variant prop sets a block-level element's `margin-block` (top + bott
|
|
|
34517
35556
|
|
|
34518
35557
|
`getSpaceClass({ space })` maps the prop to a margin class (e.g. `space="large"` → `large`). The same scale also backs `getPaddingClass()` (block padding), `getIndentClass()` (inline padding), and `getGapClass()`, so they all move together when you change `--space-normal`.
|
|
34519
35558
|
|
|
35559
|
+
`space="auto"` sets `margin-block: auto`. In a flex or grid container, such as a `<Column>`, the auto margins take the free space, so the block sits in the middle (it still keeps auto margins as a first or last child). In normal block flow they do nothing: to centre a block vertically there, use `height="full" middle` (see `getHeightClass()`). `padding` and `gap` have no `auto`.
|
|
35560
|
+
|
|
34520
35561
|
Alongside the named scale, `space`, `padding`, and `indent` also accept numeric multiples of `--space-normal` — `1x` … `10x` (e.g. `padding="5x"` → `calc(var(--space-normal) * 5)`) — for larger one-off blocks like hero panels.
|
|
34521
35562
|
|
|
34522
35563
|
## Theme variables
|
|
@@ -35693,7 +36734,7 @@ A direction-aware `<Transition>` preset that slides its children horizontally
|
|
|
35693
36734
|
**Things to know:**
|
|
35694
36735
|
|
|
35695
36736
|
- 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
|
|
36737
|
+
- 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
36738
|
- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
|
|
35698
36739
|
- The old and new content slide a full width apart, so they sit edge to edge and never overlap.
|
|
35699
36740
|
- 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 +37144,7 @@ A direction-aware `<Transition>` preset that slides its children vertically —
|
|
|
36103
37144
|
**Things to know:**
|
|
36104
37145
|
|
|
36105
37146
|
- 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
|
|
37147
|
+
- 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
37148
|
- Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
|
|
36108
37149
|
- The old and new content slide a full height apart, so they sit edge to edge and never overlap.
|
|
36109
37150
|
- 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.
|
|
@@ -36211,7 +37252,7 @@ Props for the `TreeApp` component — the tree to render plus optional extra rou
|
|
|
36211
37252
|
|
|
36212
37253
|
Top-level app component for a tree-based documentation site.
|
|
36213
37254
|
|
|
36214
|
-
- Wraps `<App>` with error catching and a sidebar layout.
|
|
37255
|
+
- Wraps `<App>` with error catching and a sidebar layout. Each page is kept in a `<RouteCache>` and scrolls in its own `<Scroll>` box, and a page error shows inside the layout.
|
|
36215
37256
|
- Flattens `tree` once via `<TreeProvider>` wrapping both the sidebar and the router, so everything below shares a single `useTreeMap()` lookup — nothing re-flattens.
|
|
36216
37257
|
- The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
|
|
36217
37258
|
- `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
|
|
@@ -37653,6 +38694,7 @@ Combined meta data for a website page — title, URLs, description, CSP, tags, l
|
|
|
37653
38694
|
{
|
|
37654
38695
|
readonly root?: ImmutableURL | undefined;
|
|
37655
38696
|
readonly url?: ImmutableURL | undefined;
|
|
38697
|
+
readonly stack?: AbsolutePath | undefined;
|
|
37656
38698
|
readonly app?: string | undefined;
|
|
37657
38699
|
readonly title?: string | undefined;
|
|
37658
38700
|
readonly description?: string | undefined;
|
|
@@ -37672,7 +38714,8 @@ Combined meta data for a website page — title, URLs, description, CSP, tags, l
|
|
|
37672
38714
|
| Property | Type | Description |
|
|
37673
38715
|
| --- | --- | --- |
|
|
37674
38716
|
| `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
|
|
38717
|
+
| `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. |
|
|
38718
|
+
| `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
38719
|
| `app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
|
|
37677
38720
|
| `title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
|
|
37678
38721
|
| `description` | `string \| undefined` | Description of the current page. Read only. Optional. |
|
|
@@ -37817,7 +38860,8 @@ mergeMeta(meta1: Meta, meta2: PossibleMeta, caller: AnyCaller = mergeMeta): Meta
|
|
|
37817
38860
|
| --- | --- | --- |
|
|
37818
38861
|
| `meta1` | `Meta` | The existing fully-resolved `Meta` to merge into. |
|
|
37819
38862
|
| `.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
|
|
38863
|
+
| `.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. |
|
|
38864
|
+
| `.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
38865
|
| `.app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
|
|
37822
38866
|
| `.title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
|
|
37823
38867
|
| `.description` | `string \| undefined` | Description of the current page. Read only. Optional. |
|