shelving 1.321.0 → 1.322.1
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 +204 -1
- package/docs/llms-full.txt +793 -115
- package/docs/ui/App.md +105 -7
- package/docs/ui/AppLayout.md +85 -0
- package/docs/ui/AppLayoutProps.md +21 -0
- package/docs/ui/Catcher.md +1 -1
- package/docs/ui/Dialog.md +3 -1
- package/docs/ui/Dialogs.md +4 -0
- 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/HeightVariant.md +30 -0
- package/docs/ui/HeightVariants.md +26 -0
- package/docs/ui/Navigation.md +20 -11
- 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 +22 -17
- package/docs/ui/Router.md +9 -5
- 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/TreeApp.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.md +13 -8
- package/package.json +1 -1
- package/ui/README.md +1 -1
- package/ui/app/App.md +105 -7
- package/ui/dialog/Dialog.md +3 -1
- package/ui/dialog/Dialogs.d.ts +4 -0
- package/ui/dialog/Dialogs.js +4 -0
- package/ui/dialog/Dialogs.tsx +4 -0
- 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 +92 -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/Page.md +12 -8
- package/ui/router/Navigation.md +20 -11
- package/ui/router/RouteCache.d.ts +2 -1
- package/ui/router/RouteCache.js +2 -1
- package/ui/router/RouteCache.md +20 -16
- package/ui/router/RouteCache.tsx +2 -1
- package/ui/router/Router.md +9 -5
- 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/tree/TreeApp.d.ts +1 -1
- package/ui/tree/TreeApp.js +5 -2
- package/ui/tree/TreeApp.tsx +11 -2
- package/docs/ui/CenteredLayout.md +0 -66
- package/docs/ui/CenteredLayoutProps.md +0 -14
- 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/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. Pages slide in the content slot above the bar, so the bar stays still. 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:
|
|
@@ -880,6 +1071,18 @@ What changes for users:
|
|
|
880
1071
|
|
|
881
1072
|
See `<Navigation>`, `NavigationStore`, `<RouteCache>`, `<StackButton>` and `<BackButton>` for the full details.
|
|
882
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
|
+
|
|
883
1086
|
### From `CacheDBProvider` to `HydratingAPIProvider`
|
|
884
1087
|
|
|
885
1088
|
`CacheDBProvider` and the paging in `QueryStore` are removed. To upgrade an app:
|
|
@@ -20062,7 +20265,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20062
20265
|
|
|
20063
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>`.
|
|
20064
20267
|
|
|
20065
|
-
**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>`.
|
|
20066
20269
|
|
|
20067
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>`.
|
|
20068
20271
|
|
|
@@ -20176,14 +20379,15 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20176
20379
|
- [DataSchemaInput](ui/DataSchemaInput.md): Show a DataInput for a nested DataSchema.
|
|
20177
20380
|
- [SchemaField](ui/SchemaField.md): Show the appropriate input for a schema, wrapped in a <Field> with its label and message.
|
|
20178
20381
|
- [SelectInput](ui/SelectInput.md): Dropdown input bound to a string value, rendered as a <select> of the provided options.
|
|
20179
|
-
- [
|
|
20180
|
-
- [
|
|
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.
|
|
20181
20385
|
- [Menu](ui/Menu.md): A <menu> list of <MenuItem> children.
|
|
20182
20386
|
- [MenuItem](ui/MenuItem.md): A <li> containing an <a> link, plus optional submenu content shown when this item is "proud".
|
|
20183
20387
|
- [Catcher](ui/Catcher.md): React error boundary that renders a fallback component when any descendant throws.
|
|
20184
20388
|
- [ErrorNotice](ui/ErrorNotice.md): Render a caught error as an inline <Notice> with a retry button.
|
|
20185
20389
|
- [PageCatcher](ui/PageCatcher.md): Error boundary for a whole page that renders a full <ErrorPage> fallback on error.
|
|
20186
|
-
- [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.
|
|
20187
20391
|
- [Icon](ui/Icon.md): Render the icon for a given status, coloured to match.
|
|
20188
20392
|
- [Loader](ui/Loader.md): Load a component.
|
|
20189
20393
|
- [PageLoader](ui/PageLoader.md): Load a page.
|
|
@@ -20198,7 +20402,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20198
20402
|
- [Page](ui/Page.md): Wrap a single page (or screen) within an app, applying its meta and head tags.
|
|
20199
20403
|
- [BackButton](ui/BackButton.md): Back button for the current stack.
|
|
20200
20404
|
- [Navigation](ui/Navigation.md): Top-level navigation provider, with one stack of pages for each tab.
|
|
20201
|
-
- [RouteCache](ui/RouteCache.md): Keep-alive page cache for the pages in the navigation stacks.
|
|
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.
|
|
20202
20406
|
- [Router](ui/Router.md): Match the current URL against routes and render the matched element.
|
|
20203
20407
|
- [StackButton](ui/StackButton.md): Button for one stack in a tab bar.
|
|
20204
20408
|
- [Scroll](ui/Scroll.md): Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
|
|
@@ -20271,10 +20475,11 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20271
20475
|
- [getFlexClass()](ui/getFlexClass.md): Get the flex layout class for a component from its flex variant props.
|
|
20272
20476
|
- [getGapClass()](ui/getGapClass.md): Get the gap class for a component from its gap variant prop.
|
|
20273
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.
|
|
20274
20479
|
- [getIndentClass()](ui/getIndentClass.md): Get the inline-padding ("indent") class for a component from its indent variant prop.
|
|
20275
20480
|
- [getPaddingClass()](ui/getPaddingClass.md): Get the block-padding class for a component from its padding variant prop.
|
|
20276
20481
|
- [getRadiusClass()](ui/getRadiusClass.md): Get the corner-radius class for a component from its radius variant prop.
|
|
20277
|
-
- [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.
|
|
20278
20483
|
- [getShadowClass()](ui/getShadowClass.md): Get the drop-shadow class for a component from its shadow variant prop.
|
|
20279
20484
|
- [getSpaceClass()](ui/getSpaceClass.md): Get the block spacing class for a component from its space="" variant prop.
|
|
20280
20485
|
- [getStatusClass()](ui/getStatusClass.md): Get the status tint class for a component from its status variant prop.
|
|
@@ -20436,7 +20641,8 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20436
20641
|
- [SelectProps](ui/SelectProps.md): Props for SelectInput, a dropdown <select> bound to a string value.
|
|
20437
20642
|
- [TextareaInputProps](ui/TextareaInputProps.md): Props for TextareaInput, a multiline text input bound to a string value.
|
|
20438
20643
|
- [TextInputProps](ui/TextInputProps.md): Props for TextInput, a single-line text input bound to a string value.
|
|
20439
|
-
- [
|
|
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.
|
|
20440
20646
|
- [SidebarLayoutProps](ui/SidebarLayoutProps.md): Props for <SidebarLayout> — the sidebar column content, main children, and a right placement flag.
|
|
20441
20647
|
- [MenuProps](ui/MenuProps.md): Props for <Menu> — optional <MenuItem> children.
|
|
20442
20648
|
- [MenuItemProps](ui/MenuItemProps.md): Props for <MenuItem> — <Clickable> props plus children whose first node is the label and the rest the submenu.
|
|
@@ -20469,10 +20675,11 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20469
20675
|
- [FlexVariants](ui/FlexVariants.md): Variant props for flex layout — opt-in modifiers any component can mix in via getFlexClass().
|
|
20470
20676
|
- [GapVariants](ui/GapVariants.md): Variant props for the gap between a component's children, e.g. gap="large".
|
|
20471
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.
|
|
20472
20679
|
- [IndentVariants](ui/IndentVariants.md): Variant props for the inline-padding ("indent", left + right) of a component, e.g. indent="normal".
|
|
20473
20680
|
- [PaddingVariants](ui/PaddingVariants.md): Variant props for the block-padding (top + bottom) of a component, e.g. padding="large".
|
|
20474
20681
|
- [RadiusVariants](ui/RadiusVariants.md): Variant props for the corner radius of an element, e.g. radius="large".
|
|
20475
|
-
- [ScrollVariants](ui/ScrollVariants.md): Variant props
|
|
20682
|
+
- [ScrollVariants](ui/ScrollVariants.md): Variant props for a scroll region: which axes scroll, plus cover and reverse.
|
|
20476
20683
|
- [ScrollComponentProps](ui/ScrollComponentProps.md): Props for the Scroll component — children plus scroll-axis variants.
|
|
20477
20684
|
- [ShadowVariants](ui/ShadowVariants.md): Variant props for the drop shadow of an element, e.g. shadow="large".
|
|
20478
20685
|
- [SpaceVariants](ui/SpaceVariants.md): Variants to control block spacing on components, e.g. space="large".
|
|
@@ -20521,6 +20728,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20521
20728
|
- [ColorVariant](ui/ColorVariant.md): Enumerated colour names selectable via the color="purple" prop for components that support that support ColorVariants
|
|
20522
20729
|
- [DurationValue](ui/DurationValue.md): Allowed values for transition timing for components that support DurationVariants
|
|
20523
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.
|
|
20524
20732
|
- [IndentVariant](ui/IndentVariant.md): Allowed values for inline-padding ("indent") for components that support IndentVariants
|
|
20525
20733
|
- [RadiusVariant](ui/RadiusVariant.md): Allowed values for border radius for components that support RadiusVariants
|
|
20526
20734
|
- [ShadowVariant](ui/ShadowVariant.md): Enumerated drop-shadow scale selectable via the shadow="normal" variant prop.
|
|
@@ -20613,17 +20821,19 @@ Use `<App>` when mounting into an existing HTML page on the client. For server-s
|
|
|
20613
20821
|
The smallest single-screen app — `<App>` wraps a layout and some content:
|
|
20614
20822
|
|
|
20615
20823
|
```tsx
|
|
20616
|
-
import { App,
|
|
20824
|
+
import { App, FixedLayout, Paragraph, Scroll, Section, Title } from "shelving/ui";
|
|
20617
20825
|
|
|
20618
20826
|
function HelloApp() {
|
|
20619
20827
|
return (
|
|
20620
20828
|
<App app="My app">
|
|
20621
|
-
<
|
|
20622
|
-
<
|
|
20623
|
-
<
|
|
20624
|
-
|
|
20625
|
-
|
|
20626
|
-
|
|
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>
|
|
20627
20837
|
</App>
|
|
20628
20838
|
);
|
|
20629
20839
|
}
|
|
@@ -20654,6 +20864,102 @@ export function MyApp() {
|
|
|
20654
20864
|
|
|
20655
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.
|
|
20656
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
|
+
|
|
20657
20963
|
For a documentation site, hand an extracted tree to `<TreeApp>` instead — see the `shelving/extract` guide.
|
|
20658
20964
|
|
|
20659
20965
|
|
|
@@ -23557,7 +23863,9 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
|
|
|
23557
23863
|
- A change inside an open dialog (new content, a Suspense reveal) runs no view transition, so the dialog never ignores a tap while its content changes. The page ignores taps while a view transition runs.
|
|
23558
23864
|
- `Dialog` knows nothing about transitions. React runs a view transition only for an update made inside `startTransition()`, so the code that mounts and unmounts the dialog decides if it animates:
|
|
23559
23865
|
- `<Dialogs>` renders a `DialogsStore` inside transitions, so a dialog opened with `DialogsStore.show()` animates in and out for you.
|
|
23560
|
-
- A `Dialog` you mount yourself appears and goes at once, unless you set the state that mounts and unmounts it inside `startTransition()`. See the declarative example below.
|
|
23866
|
+
- A `Dialog` you mount yourself appears and goes at once, unless you set the React state that mounts and unmounts it inside `startTransition()`. See the declarative example below.
|
|
23867
|
+
- A `Dialog` you mount from a store read with `useStore()` never animates. `useStore()` applies each change at once, so `startTransition()` around the store write does not help.
|
|
23868
|
+
- To open a dialog from app code, use `requireDialogs()` and `DialogsStore.show()`. Pass the `DialogsStore` into any function that opens one.
|
|
23561
23869
|
- A browser without view transitions shows and hides the dialog at once.
|
|
23562
23870
|
- Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
|
|
23563
23871
|
|
|
@@ -23851,6 +24159,10 @@ DialogsContext({ children }: DialogsContextProps): ReactElement
|
|
|
23851
24159
|
|
|
23852
24160
|
Render the open dialogs from the current `DialogsContext`.
|
|
23853
24161
|
|
|
24162
|
+
- It renders the list inside a transition, so each dialog animates in and out.
|
|
24163
|
+
- To open a dialog, use `requireDialogs()` and `DialogsStore.show()`. Pass the `DialogsStore` into any function that opens one.
|
|
24164
|
+
- A `<Dialog>` you render from `useStore()` never animates, even if you write the store inside `startTransition()`.
|
|
24165
|
+
|
|
23854
24166
|
## Signatures
|
|
23855
24167
|
|
|
23856
24168
|
```ts
|
|
@@ -30490,14 +30802,127 @@ TextInput({
|
|
|
30490
30802
|
|
|
30491
30803
|
---
|
|
30492
30804
|
|
|
30493
|
-
#
|
|
30805
|
+
# AppLayoutProps
|
|
30806
|
+
|
|
30807
|
+
- Kind: interface
|
|
30808
|
+
- Import: `import { AppLayoutProps } from "shelving/ui";`
|
|
30809
|
+
- Extends: `OptionalChildProps`
|
|
30810
|
+
|
|
30811
|
+
Props for `<AppLayout>`: the `nav` bar content and the content slot `children`.
|
|
30812
|
+
|
|
30813
|
+
## Signatures
|
|
30814
|
+
|
|
30815
|
+
```ts
|
|
30816
|
+
{
|
|
30817
|
+
nav?: ReactNode;
|
|
30818
|
+
}
|
|
30819
|
+
```
|
|
30820
|
+
|
|
30821
|
+
## Properties
|
|
30822
|
+
|
|
30823
|
+
| Property | Type | Description |
|
|
30824
|
+
| --- | --- | --- |
|
|
30825
|
+
| `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. |
|
|
30826
|
+
|
|
30827
|
+
|
|
30828
|
+
---
|
|
30829
|
+
|
|
30830
|
+
# AppLayout
|
|
30831
|
+
|
|
30832
|
+
- Kind: component
|
|
30833
|
+
- Import: `import { AppLayout } from "shelving/ui";`
|
|
30834
|
+
|
|
30835
|
+
Layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app.
|
|
30836
|
+
- 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.
|
|
30837
|
+
- The bar sits below the content slot, not over it, and it stays still while a page slides.
|
|
30838
|
+
- 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.
|
|
30839
|
+
|
|
30840
|
+
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.
|
|
30841
|
+
|
|
30842
|
+
**Things to know:**
|
|
30843
|
+
|
|
30844
|
+
- 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.
|
|
30845
|
+
- The bar sits below the content slot, not over it. So pages need no extra space at the bottom for the bar.
|
|
30846
|
+
- The bar shows at every screen size.
|
|
30847
|
+
- 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).
|
|
30848
|
+
- Each item in the bar takes an equal share of its width, up to `--app-layout-nav-item-width` each.
|
|
30849
|
+
- The bar is outside the page cache, so it has one copy and keeps its state.
|
|
30850
|
+
- The bar has no view-transition name of its own. Pages slide sideways in the content slot above it, so the bar stays still. A named bar would draw above a dialog or notice that covers it during every view transition.
|
|
30851
|
+
- 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 />}`.
|
|
30852
|
+
- Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
|
|
30853
|
+
|
|
30854
|
+
## Usage
|
|
30855
|
+
|
|
30856
|
+
```tsx
|
|
30857
|
+
import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll, StackButton } from "shelving/ui";
|
|
30858
|
+
|
|
30859
|
+
function StackBar() {
|
|
30860
|
+
return <>
|
|
30861
|
+
<StackButton stack="/home" title="Home"><HomeIcon /></StackButton>
|
|
30862
|
+
<StackButton stack="/discover" title="Discover"><SearchIcon /></StackButton>
|
|
30863
|
+
<StackButton stack="/profile" title="Profile"><ProfileIcon /></StackButton>
|
|
30864
|
+
</>;
|
|
30865
|
+
}
|
|
30866
|
+
|
|
30867
|
+
<AppLayout nav={<StackBar />}>
|
|
30868
|
+
<HorizontalTransition>
|
|
30869
|
+
<RouteCache>
|
|
30870
|
+
<Scroll vertical cover>
|
|
30871
|
+
<PageLoader>
|
|
30872
|
+
<Router routes={ROUTES} />
|
|
30873
|
+
</PageLoader>
|
|
30874
|
+
</Scroll>
|
|
30875
|
+
</RouteCache>
|
|
30876
|
+
</HorizontalTransition>
|
|
30877
|
+
</AppLayout>
|
|
30878
|
+
```
|
|
30879
|
+
|
|
30880
|
+
## Styling
|
|
30881
|
+
|
|
30882
|
+
| Variable | Styles | Default |
|
|
30883
|
+
|---|---|---|
|
|
30884
|
+
| `--app-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
|
|
30885
|
+
| `--app-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
|
|
30886
|
+
| `--app-layout-nav-background` | Bar fill (also fills the home-bar area below it) | `var(--tint-100)` (white) |
|
|
30887
|
+
| `--app-layout-nav-color` | Bar text and icon colour | `var(--tint-00)` (black) |
|
|
30888
|
+
| `--app-layout-nav-border` | Line above the bar | `var(--stroke-normal) solid var(--tint-90)` |
|
|
30889
|
+
| `--app-layout-nav-shadow` | Shadow of the bar, for example a soft shadow above it | `none` |
|
|
30890
|
+
| `--app-layout-nav-item-width` | Largest width of one bar item | `6rem` |
|
|
30891
|
+
|
|
30892
|
+
The bar keeps its items clear of the home bar and the rounded screen corners with safe-area insets.
|
|
30893
|
+
|
|
30894
|
+
**Global tokens it reads** — `--tint-00`, `--tint-90`, `--tint-100`, and `--stroke-normal`.
|
|
30895
|
+
|
|
30896
|
+
|
|
30897
|
+
## Signatures
|
|
30898
|
+
|
|
30899
|
+
```ts
|
|
30900
|
+
AppLayout({ nav, children }: AppLayoutProps): ReactElement
|
|
30901
|
+
```
|
|
30902
|
+
|
|
30903
|
+
## Parameters
|
|
30904
|
+
|
|
30905
|
+
| Param | Type | Description |
|
|
30906
|
+
| --- | --- | --- |
|
|
30907
|
+
| `props` | `AppLayoutProps` | |
|
|
30908
|
+
| `.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. |
|
|
30909
|
+
|
|
30910
|
+
## Returns
|
|
30911
|
+
|
|
30912
|
+
| Type | Description |
|
|
30913
|
+
| --- | --- |
|
|
30914
|
+
| `ReactElement` | |
|
|
30915
|
+
|
|
30916
|
+
|
|
30917
|
+
---
|
|
30918
|
+
|
|
30919
|
+
# FixedLayoutProps
|
|
30494
30920
|
|
|
30495
30921
|
- Kind: interface
|
|
30496
|
-
- Import: `import {
|
|
30497
|
-
- Extends: `
|
|
30922
|
+
- Import: `import { FixedLayoutProps } from "shelving/ui";`
|
|
30923
|
+
- Extends: `OptionalChildProps`
|
|
30498
30924
|
|
|
30499
|
-
Props for `<
|
|
30500
|
-
(block / inline padding of the scroll area) variants.
|
|
30925
|
+
Props for `<FixedLayout>`: the content slot `children`.
|
|
30501
30926
|
|
|
30502
30927
|
## Signatures
|
|
30503
30928
|
|
|
@@ -30508,66 +30933,91 @@ Props for `<CenteredLayout>` — optional `children` plus `width` (of the centre
|
|
|
30508
30933
|
|
|
30509
30934
|
---
|
|
30510
30935
|
|
|
30511
|
-
#
|
|
30936
|
+
# FixedLayout
|
|
30512
30937
|
|
|
30513
30938
|
- Kind: component
|
|
30514
|
-
- Import: `import {
|
|
30939
|
+
- Import: `import { FixedLayout } from "shelving/ui";`
|
|
30515
30940
|
|
|
30516
|
-
Layout
|
|
30517
|
-
-
|
|
30941
|
+
Layout with no chrome: the whole screen is one content slot.
|
|
30942
|
+
- It locks the document and gives a full-height slot inside the safe areas. It does not scroll or centre.
|
|
30943
|
+
- Fill the slot with `<Scroll vertical cover>`. Used for e.g. log-in and error screens, and full-screen pages.
|
|
30518
30944
|
|
|
30519
|
-
A full-viewport layout
|
|
30945
|
+
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.
|
|
30520
30946
|
|
|
30521
30947
|
**Things to know:**
|
|
30522
30948
|
|
|
30523
|
-
-
|
|
30524
|
-
-
|
|
30525
|
-
-
|
|
30949
|
+
- It is a frame only. It does not scroll or centre. Fill the slot with `<Scroll vertical cover>`, so the content scrolls inside it.
|
|
30950
|
+
- 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.
|
|
30951
|
+
- The slot stays clear of the notch, the home bar and the rounded screen corners (safe-area insets).
|
|
30952
|
+
- For pages that you move back and forth between, put a `<RouteCache>` around the scroll box, as in `<AppLayout>`.
|
|
30953
|
+
- Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
|
|
30526
30954
|
|
|
30527
30955
|
## Usage
|
|
30528
30956
|
|
|
30529
30957
|
```tsx
|
|
30530
|
-
import {
|
|
30958
|
+
import { Block, FixedLayout, Router, Scroll } from "shelving/ui";
|
|
30531
30959
|
|
|
30960
|
+
// The signed-out screens: one layout around their own router.
|
|
30961
|
+
<FixedLayout>
|
|
30962
|
+
<Scroll vertical cover>
|
|
30963
|
+
<Router routes={{
|
|
30964
|
+
"/login": LoginPage,
|
|
30965
|
+
"/register": RegisterPage,
|
|
30966
|
+
}} />
|
|
30967
|
+
</Scroll>
|
|
30968
|
+
</FixedLayout>
|
|
30969
|
+
|
|
30970
|
+
// Each page centres its own content.
|
|
30532
30971
|
function LoginPage() {
|
|
30533
30972
|
return (
|
|
30534
|
-
<
|
|
30535
|
-
<
|
|
30536
|
-
<LoginForm/>
|
|
30537
|
-
</
|
|
30538
|
-
</
|
|
30973
|
+
<Page title="Log in">
|
|
30974
|
+
<Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
|
|
30975
|
+
<LoginForm />
|
|
30976
|
+
</Block>
|
|
30977
|
+
</Page>
|
|
30539
30978
|
);
|
|
30540
30979
|
}
|
|
30541
30980
|
```
|
|
30542
30981
|
|
|
30543
|
-
|
|
30982
|
+
An app-level error, outside every other layout:
|
|
30983
|
+
|
|
30984
|
+
```tsx
|
|
30985
|
+
import { Catcher, ErrorPage, type ErrorProps, FixedLayout, Scroll } from "shelving/ui";
|
|
30986
|
+
|
|
30987
|
+
function AppError({ reason }: ErrorProps) {
|
|
30988
|
+
return (
|
|
30989
|
+
<FixedLayout>
|
|
30990
|
+
<Scroll vertical cover>
|
|
30991
|
+
<ErrorPage reason={reason} />
|
|
30992
|
+
</Scroll>
|
|
30993
|
+
</FixedLayout>
|
|
30994
|
+
);
|
|
30995
|
+
}
|
|
30996
|
+
|
|
30997
|
+
<Catcher as={AppError}>…</Catcher>
|
|
30998
|
+
```
|
|
30544
30999
|
|
|
30545
31000
|
## Styling
|
|
30546
31001
|
|
|
30547
31002
|
| Variable | Styles | Default |
|
|
30548
31003
|
|---|---|---|
|
|
30549
|
-
| `--
|
|
30550
|
-
| `--
|
|
30551
|
-
| `--centered-layout-indent` | Inline (left/right) padding of the scroll area | `var(--space-normal)` |
|
|
30552
|
-
| `--centered-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
|
|
30553
|
-
| `--centered-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
|
|
31004
|
+
| `--fixed-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
|
|
31005
|
+
| `--fixed-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
|
|
30554
31006
|
|
|
30555
|
-
|
|
30556
|
-
|
|
30557
|
-
**Global tokens it reads** — `--width-narrow`, `--space-normal`, `--tint-100`, and `--tint-00`.
|
|
31007
|
+
**Global tokens it reads** — `--tint-00` and `--tint-100`.
|
|
30558
31008
|
|
|
30559
31009
|
|
|
30560
31010
|
## Signatures
|
|
30561
31011
|
|
|
30562
31012
|
```ts
|
|
30563
|
-
|
|
31013
|
+
FixedLayout({ children }: FixedLayoutProps): ReactElement
|
|
30564
31014
|
```
|
|
30565
31015
|
|
|
30566
31016
|
## Parameters
|
|
30567
31017
|
|
|
30568
31018
|
| Param | Type | Description |
|
|
30569
31019
|
| --- | --- | --- |
|
|
30570
|
-
| `props` | `
|
|
31020
|
+
| `props` | `FixedLayoutProps` | |
|
|
30571
31021
|
|
|
30572
31022
|
## Returns
|
|
30573
31023
|
|
|
@@ -30610,14 +31060,14 @@ Props for `<SidebarLayout>` — the `sidebar` column content, main `children`, a
|
|
|
30610
31060
|
- Kind: component
|
|
30611
31061
|
- Import: `import { SidebarLayout } from "shelving/ui";`
|
|
30612
31062
|
|
|
30613
|
-
Layout with a fixed-width side column (typically navigation) next to a
|
|
31063
|
+
Layout with a fixed-width side column (typically navigation) next to a content slot.
|
|
30614
31064
|
- The sidebar is rendered as `<nav>` — it almost always contains the page's primary navigation.
|
|
30615
31065
|
- 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.
|
|
30616
31066
|
- While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
|
|
30617
31067
|
- Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
|
|
30618
|
-
-
|
|
31068
|
+
- 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.
|
|
30619
31069
|
|
|
30620
|
-
A full-viewport layout with a fixed-width side column next to a
|
|
31070
|
+
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.
|
|
30621
31071
|
|
|
30622
31072
|
**Things to know:**
|
|
30623
31073
|
|
|
@@ -30626,12 +31076,15 @@ A full-viewport layout with a fixed-width side column next to a scrollable main
|
|
|
30626
31076
|
- While the drawer is open an overlay dims the page; clicking the overlay closes it.
|
|
30627
31077
|
- 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.
|
|
30628
31078
|
- Inside a `<Navigation>` context the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
|
|
30629
|
-
- The
|
|
31079
|
+
- 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.
|
|
31080
|
+
- The sidebar stays outside the page cache, so it keeps its own scroll position and state as pages change.
|
|
31081
|
+
- On a narrow screen the menu button floats at the top right of the content slot, above the page.
|
|
31082
|
+
- Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
|
|
30630
31083
|
|
|
30631
31084
|
## Usage
|
|
30632
31085
|
|
|
30633
31086
|
```tsx
|
|
30634
|
-
import {
|
|
31087
|
+
import { Menu, MenuItem, PageLoader, RouteCache, Router, Scroll, SidebarLayout } from "shelving/ui";
|
|
30635
31088
|
|
|
30636
31089
|
function AppShell() {
|
|
30637
31090
|
const nav = (
|
|
@@ -30643,13 +31096,19 @@ function AppShell() {
|
|
|
30643
31096
|
);
|
|
30644
31097
|
return (
|
|
30645
31098
|
<SidebarLayout sidebar={nav}>
|
|
30646
|
-
<
|
|
31099
|
+
<RouteCache>
|
|
31100
|
+
<Scroll vertical cover>
|
|
31101
|
+
<PageLoader>
|
|
31102
|
+
<Router routes={ROUTES}/>
|
|
31103
|
+
</PageLoader>
|
|
31104
|
+
</Scroll>
|
|
31105
|
+
</RouteCache>
|
|
30647
31106
|
</SidebarLayout>
|
|
30648
31107
|
);
|
|
30649
31108
|
}
|
|
30650
31109
|
```
|
|
30651
31110
|
|
|
30652
|
-
|
|
31111
|
+
To slide pages, put a transition around the `<RouteCache>`, inside the layout. The sidebar is outside the transition, so it stays still.
|
|
30653
31112
|
|
|
30654
31113
|
## Styling
|
|
30655
31114
|
|
|
@@ -30663,7 +31122,7 @@ Layouts compose naturally as `<Router>` route values — wrap a group of routes
|
|
|
30663
31122
|
| `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-90)` | `none` |
|
|
30664
31123
|
| `--sidebar-layout-shadow` | Drop shadow of the open drawer on a narrow screen | `var(--shadow-large)` |
|
|
30665
31124
|
|
|
30666
|
-
The sidebar
|
|
31125
|
+
The sidebar scrolls on its own. The content slot does not scroll: its `<Scroll vertical cover>` box does.
|
|
30667
31126
|
|
|
30668
31127
|
**Global tokens it reads** — `--tint-00` / `--tint-90` / `--tint-100`, plus `--space-normal`, `--duration-normal`, `--shadow-large`, and `--color-backdrop`.
|
|
30669
31128
|
|
|
@@ -30993,7 +31452,7 @@ A React error boundary that catches errors thrown anywhere in its subtree and re
|
|
|
30993
31452
|
|
|
30994
31453
|
**Things to know:**
|
|
30995
31454
|
|
|
30996
|
-
- `PageCatcher` is a convenience wrapper that renders `ErrorPage` instead — a
|
|
31455
|
+
- `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>`).
|
|
30997
31456
|
- `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.
|
|
30998
31457
|
- `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"`.
|
|
30999
31458
|
|
|
@@ -31129,7 +31588,8 @@ PageCatcher({ children }: ChildProps): ReactElement
|
|
|
31129
31588
|
- Kind: component
|
|
31130
31589
|
- Import: `import { ErrorPage } from "shelving/ui";`
|
|
31131
31590
|
|
|
31132
|
-
Render a caught error as a
|
|
31591
|
+
Render a caught error as a `<Page>` with an `<ErrorNotice>` in a narrow column, centred in the middle of the screen.
|
|
31592
|
+
- 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>`.
|
|
31133
31593
|
|
|
31134
31594
|
## Signatures
|
|
31135
31595
|
|
|
@@ -31321,11 +31781,12 @@ Load a page.
|
|
|
31321
31781
|
|
|
31322
31782
|
- Wrapped in `<PageCatcher>` so child components can throw errors.
|
|
31323
31783
|
- Wrapped in `<Suspense>` so child components can throw promises.
|
|
31784
|
+
- It renders no layout, so its loading state and error page show inside whatever layout is around it.
|
|
31324
31785
|
|
|
31325
31786
|
## Signatures
|
|
31326
31787
|
|
|
31327
31788
|
```ts
|
|
31328
|
-
PageLoader({ children, fallback =
|
|
31789
|
+
PageLoader({ children, fallback = PAGE_LOADING }: LoaderProps): ReactElement
|
|
31329
31790
|
```
|
|
31330
31791
|
|
|
31331
31792
|
## Parameters
|
|
@@ -32621,16 +33082,20 @@ function UserPage({ id }: { id: string }) {
|
|
|
32621
33082
|
}
|
|
32622
33083
|
```
|
|
32623
33084
|
|
|
32624
|
-
|
|
33085
|
+
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>`.
|
|
32625
33086
|
|
|
32626
33087
|
```tsx
|
|
32627
|
-
import { Page,
|
|
33088
|
+
import { Block, FixedLayout, Page, Scroll } from "shelving/ui";
|
|
32628
33089
|
|
|
32629
|
-
<
|
|
32630
|
-
<
|
|
32631
|
-
<
|
|
32632
|
-
|
|
32633
|
-
|
|
33090
|
+
<FixedLayout>
|
|
33091
|
+
<Scroll vertical cover>
|
|
33092
|
+
<Page title="Sign in">
|
|
33093
|
+
<Block height="full" middle width="narrow">
|
|
33094
|
+
<LoginForm/>
|
|
33095
|
+
</Block>
|
|
33096
|
+
</Page>
|
|
33097
|
+
</Scroll>
|
|
33098
|
+
</FixedLayout>
|
|
32634
33099
|
```
|
|
32635
33100
|
|
|
32636
33101
|
|
|
@@ -32844,26 +33309,35 @@ import { App, Navigation, Router } from "shelving/ui";
|
|
|
32844
33309
|
List the root path of each stack in tab order. Put a `<StackButton>` for each stack in the tab bar.
|
|
32845
33310
|
|
|
32846
33311
|
```tsx
|
|
32847
|
-
import { App, HorizontalTransition, Navigation, RouteCache, Router, StackButton } from "shelving/ui";
|
|
33312
|
+
import { App, AppLayout, HorizontalTransition, Navigation, PageLoader, RouteCache, Router, Scroll, StackButton } from "shelving/ui";
|
|
32848
33313
|
|
|
32849
33314
|
const STACKS = ["/home", "/discover", "/profile"] as const;
|
|
32850
33315
|
|
|
33316
|
+
const TABS = <>
|
|
33317
|
+
<StackButton stack="/home">Home</StackButton>
|
|
33318
|
+
<StackButton stack="/discover">Discover</StackButton>
|
|
33319
|
+
<StackButton stack="/profile">Profile</StackButton>
|
|
33320
|
+
</>;
|
|
33321
|
+
|
|
32851
33322
|
<App root="https://example.com/">
|
|
32852
33323
|
<Navigation stacks={STACKS}>
|
|
32853
|
-
<
|
|
32854
|
-
<
|
|
32855
|
-
<
|
|
32856
|
-
|
|
32857
|
-
|
|
32858
|
-
|
|
32859
|
-
|
|
32860
|
-
|
|
32861
|
-
|
|
32862
|
-
|
|
33324
|
+
<AppLayout nav={TABS}>
|
|
33325
|
+
<HorizontalTransition>
|
|
33326
|
+
<RouteCache>
|
|
33327
|
+
<Scroll vertical cover>
|
|
33328
|
+
<PageLoader>
|
|
33329
|
+
<Router routes={ROUTES}/>
|
|
33330
|
+
</PageLoader>
|
|
33331
|
+
</Scroll>
|
|
33332
|
+
</RouteCache>
|
|
33333
|
+
</HorizontalTransition>
|
|
33334
|
+
</AppLayout>
|
|
32863
33335
|
</Navigation>
|
|
32864
33336
|
</App>
|
|
32865
33337
|
```
|
|
32866
33338
|
|
|
33339
|
+
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.
|
|
33340
|
+
|
|
32867
33341
|
To select a tab when the app starts, pass the starting `stack`. The app decides which stack the opening URL belongs to, for example:
|
|
32868
33342
|
|
|
32869
33343
|
```tsx
|
|
@@ -33330,8 +33804,9 @@ Props for `<RouteCache>`: the `maxCached` size and the content `children` to kee
|
|
|
33330
33804
|
- Kind: component
|
|
33331
33805
|
- Import: `import { RouteCache } from "shelving/ui";`
|
|
33332
33806
|
|
|
33333
|
-
Keep-alive page cache for the pages in the navigation stacks.
|
|
33807
|
+
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.
|
|
33334
33808
|
|
|
33809
|
+
- Put a page transition around it, and a `<Scroll vertical cover>` inside it, so each kept page scrolls in its own box.
|
|
33335
33810
|
- Keeps each page in the stacks mounted but hidden (with React's `<Activity>`), so going back to a page, or switching back to a tab, shows it exactly as you left it.
|
|
33336
33811
|
- Each page is keyed by its stack and its depth in that stack, not by its URL. So `NavigationStore.replace()` (a canonical URL, an in-page tab) keeps the same page mounted, and the same URL open in two tabs is two separate pages.
|
|
33337
33812
|
- 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.
|
|
@@ -33340,9 +33815,9 @@ Keep-alive page cache for the pages in the navigation stacks. Drop it into a lay
|
|
|
33340
33815
|
- `<Activity mode="hidden">` keeps a hidden page's state but unmounts its effects, so its subscriptions and timers pause and resume as it is hidden and shown.
|
|
33341
33816
|
- Without the browser Navigation API (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
|
|
33342
33817
|
|
|
33343
|
-
A keep-alive cache for the pages in the navigation stacks. Put it in a layout around
|
|
33818
|
+
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.
|
|
33344
33819
|
|
|
33345
|
-
|
|
33820
|
+
Layouts do not include a cache. The app composes it, so it can also choose the transition, or leave the cache out.
|
|
33346
33821
|
|
|
33347
33822
|
**Things to know:**
|
|
33348
33823
|
|
|
@@ -33355,33 +33830,37 @@ A keep-alive cache for the pages in the navigation stacks. Put it in a layout ar
|
|
|
33355
33830
|
- A form that makes something stays in the cache with its input. Clear it after a successful submit, so it is empty the next time you see it (see the example below).
|
|
33356
33831
|
- Each kept page is frozen under its own `<Meta>`, so a hidden page never re-renders for another page's URL.
|
|
33357
33832
|
- `<Activity mode="hidden">` keeps a hidden page's state but unmounts its effects, so subscriptions, observers (for example infinite scroll) and timers pause and resume as the page is hidden and shown.
|
|
33358
|
-
-
|
|
33359
|
-
-
|
|
33833
|
+
- **Nesting:** layout, then transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. See the usage below.
|
|
33834
|
+
- 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.
|
|
33835
|
+
- Put a page `<Transition>` **around** the `<RouteCache>`, not inside it. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
|
|
33836
|
+
- 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.
|
|
33360
33837
|
- Without the browser Navigation API, or with `maxCached={0}`, there is no cache: the current page renders directly and unmounts when you leave it.
|
|
33361
33838
|
|
|
33362
33839
|
## Usage
|
|
33363
33840
|
|
|
33364
33841
|
```tsx
|
|
33365
|
-
import { HorizontalTransition, RouteCache, Router } from "shelving/ui";
|
|
33842
|
+
import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
|
|
33366
33843
|
|
|
33367
|
-
|
|
33368
|
-
|
|
33369
|
-
<
|
|
33370
|
-
<
|
|
33371
|
-
<
|
|
33844
|
+
<AppLayout nav={<StackBar />}>
|
|
33845
|
+
<HorizontalTransition>
|
|
33846
|
+
<RouteCache>
|
|
33847
|
+
<Scroll vertical cover>
|
|
33848
|
+
<PageLoader>
|
|
33372
33849
|
<Router routes={ROUTES}/>
|
|
33373
|
-
</
|
|
33374
|
-
</
|
|
33375
|
-
</
|
|
33376
|
-
|
|
33377
|
-
|
|
33850
|
+
</PageLoader>
|
|
33851
|
+
</Scroll>
|
|
33852
|
+
</RouteCache>
|
|
33853
|
+
</HorizontalTransition>
|
|
33854
|
+
</AppLayout>
|
|
33378
33855
|
```
|
|
33379
33856
|
|
|
33380
33857
|
Keep fewer pages:
|
|
33381
33858
|
|
|
33382
33859
|
```tsx
|
|
33383
33860
|
<RouteCache maxCached={5}>
|
|
33384
|
-
<
|
|
33861
|
+
<Scroll vertical cover>
|
|
33862
|
+
<Router routes={ROUTES}/>
|
|
33863
|
+
</Scroll>
|
|
33385
33864
|
</RouteCache>
|
|
33386
33865
|
```
|
|
33387
33866
|
|
|
@@ -33484,7 +33963,7 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
|
|
|
33484
33963
|
- 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`.
|
|
33485
33964
|
- Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
|
|
33486
33965
|
- 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.
|
|
33487
|
-
- `<Router>` itself does not cache pages — wrap it in a `<RouteCache>` (
|
|
33966
|
+
- `<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.
|
|
33488
33967
|
|
|
33489
33968
|
## Usage
|
|
33490
33969
|
|
|
@@ -33530,7 +34009,7 @@ Modifier chars are tolerant: one-or-more stars and three-or-more dots are all eq
|
|
|
33530
34009
|
|
|
33531
34010
|
### Layout wrapping
|
|
33532
34011
|
|
|
33533
|
-
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.
|
|
34012
|
+
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>`.
|
|
33534
34013
|
|
|
33535
34014
|
```tsx
|
|
33536
34015
|
const SIDEBARRED_ROUTES = {
|
|
@@ -33543,7 +34022,9 @@ const SIDEBARRED_ROUTES = {
|
|
|
33543
34022
|
"/": <HomePage/>,
|
|
33544
34023
|
"/{...path}": (
|
|
33545
34024
|
<SidebarLayout sidebar={<Nav/>}>
|
|
33546
|
-
<
|
|
34025
|
+
<Scroll vertical cover>
|
|
34026
|
+
<Router routes={SIDEBARRED_ROUTES}/>
|
|
34027
|
+
</Scroll>
|
|
33547
34028
|
</SidebarLayout>
|
|
33548
34029
|
),
|
|
33549
34030
|
}}/>
|
|
@@ -33590,7 +34071,9 @@ const SIDEBARRED_ROUTES = {
|
|
|
33590
34071
|
"/login": <LoginPage/>, // no sidebar
|
|
33591
34072
|
"/{...path}": ( // everything else wrapped
|
|
33592
34073
|
<SidebarLayout sidebar={<Nav/>}>
|
|
33593
|
-
<
|
|
34074
|
+
<Scroll vertical cover>
|
|
34075
|
+
<Router routes={SIDEBARRED_ROUTES}/>
|
|
34076
|
+
</Scroll>
|
|
33594
34077
|
</SidebarLayout>
|
|
33595
34078
|
),
|
|
33596
34079
|
}}/>
|
|
@@ -33598,7 +34081,7 @@ const SIDEBARRED_ROUTES = {
|
|
|
33598
34081
|
|
|
33599
34082
|
### Keeping page state
|
|
33600
34083
|
|
|
33601
|
-
By default a page is unmounted when you navigate away and mounted fresh when you return — so scroll position, open/closed toggles, in-progress searches, form inputs, and focus are all lost, and you land back at the top. Wrap the router
|
|
34084
|
+
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.
|
|
33602
34085
|
|
|
33603
34086
|
### SSR / static rendering
|
|
33604
34087
|
|
|
@@ -33859,7 +34342,7 @@ Variants for block level elements.
|
|
|
33859
34342
|
|
|
33860
34343
|
Get the combined `className` string for a block from its styling variants.
|
|
33861
34344
|
|
|
33862
|
-
Composes the base block class and tint ladder with the colour, space, typography, and
|
|
34345
|
+
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.
|
|
33863
34346
|
|
|
33864
34347
|
## Signatures
|
|
33865
34348
|
|
|
@@ -34219,7 +34702,7 @@ Variant props for the gap between a component's children, e.g. `gap="large"`.
|
|
|
34219
34702
|
|
|
34220
34703
|
```ts
|
|
34221
34704
|
{
|
|
34222
|
-
gap?: SpaceValue | undefined;
|
|
34705
|
+
gap?: Exclude<SpaceValue, "auto"> | undefined;
|
|
34223
34706
|
}
|
|
34224
34707
|
```
|
|
34225
34708
|
|
|
@@ -34227,7 +34710,7 @@ Variant props for the gap between a component's children, e.g. `gap="large"`.
|
|
|
34227
34710
|
|
|
34228
34711
|
| Property | Type | Description |
|
|
34229
34712
|
| --- | --- | --- |
|
|
34230
|
-
| `gap` | `SpaceValue \| undefined` | Gap between child elements. Optional. |
|
|
34713
|
+
| `gap` | `Exclude<SpaceValue, "auto"> \| undefined` | Gap between child elements. Optional. |
|
|
34231
34714
|
|
|
34232
34715
|
|
|
34233
34716
|
---
|
|
@@ -34250,7 +34733,7 @@ getGapClass({ gap }: GapVariants): string | undefined
|
|
|
34250
34733
|
| Param | Type | Description |
|
|
34251
34734
|
| --- | --- | --- |
|
|
34252
34735
|
| `options` | `GapVariants` | |
|
|
34253
|
-
| `.gap` | `SpaceValue \| undefined` | Gap between child elements. Optional. |
|
|
34736
|
+
| `.gap` | `Exclude<SpaceValue, "auto"> \| undefined` | Gap between child elements. Optional. |
|
|
34254
34737
|
|
|
34255
34738
|
## Returns
|
|
34256
34739
|
|
|
@@ -34365,6 +34848,138 @@ getGridClass({ columns: 3, gap: "normal" })
|
|
|
34365
34848
|
```
|
|
34366
34849
|
|
|
34367
34850
|
|
|
34851
|
+
---
|
|
34852
|
+
|
|
34853
|
+
# HeightVariant
|
|
34854
|
+
|
|
34855
|
+
- Kind: type
|
|
34856
|
+
- Import: `import { HeightVariant } from "shelving/ui";`
|
|
34857
|
+
|
|
34858
|
+
Enumerated height selectable via the `height` variant prop.
|
|
34859
|
+
- `full` — at least the full height of the container.
|
|
34860
|
+
- `1x`–`32x` — at least a multiple of `--space-normal` (1x–8x at 1x intervals, then 10x/12x, then 16x–32x at 4x intervals).
|
|
34861
|
+
- Each value is a minimum (`min-block-size`), so the element grows when its content is taller and nothing is cut off.
|
|
34862
|
+
|
|
34863
|
+
## Signatures
|
|
34864
|
+
|
|
34865
|
+
```ts
|
|
34866
|
+
| "full"
|
|
34867
|
+
| "1x"
|
|
34868
|
+
| "2x"
|
|
34869
|
+
| "3x"
|
|
34870
|
+
| "4x"
|
|
34871
|
+
| "5x"
|
|
34872
|
+
| "6x"
|
|
34873
|
+
| "7x"
|
|
34874
|
+
| "8x"
|
|
34875
|
+
| "10x"
|
|
34876
|
+
| "12x"
|
|
34877
|
+
| "16x"
|
|
34878
|
+
| "20x"
|
|
34879
|
+
| "24x"
|
|
34880
|
+
| "28x"
|
|
34881
|
+
| "32x"
|
|
34882
|
+
```
|
|
34883
|
+
|
|
34884
|
+
|
|
34885
|
+
---
|
|
34886
|
+
|
|
34887
|
+
# HeightVariants
|
|
34888
|
+
|
|
34889
|
+
- Kind: interface
|
|
34890
|
+
- Import: `import { HeightVariants } from "shelving/ui";`
|
|
34891
|
+
|
|
34892
|
+
Variant props that set a component's height, and where its content sits inside that height, e.g. `height="full" middle`.
|
|
34893
|
+
|
|
34894
|
+
## Signatures
|
|
34895
|
+
|
|
34896
|
+
```ts
|
|
34897
|
+
{
|
|
34898
|
+
height?: HeightVariant | undefined;
|
|
34899
|
+
top?: boolean | undefined;
|
|
34900
|
+
middle?: boolean | undefined;
|
|
34901
|
+
bottom?: boolean | undefined;
|
|
34902
|
+
}
|
|
34903
|
+
```
|
|
34904
|
+
|
|
34905
|
+
## Properties
|
|
34906
|
+
|
|
34907
|
+
| Property | Type | Description |
|
|
34908
|
+
| --- | --- | --- |
|
|
34909
|
+
| `height` | `HeightVariant \| undefined` | Height of the element. It is a minimum, so the element grows when its content is taller. Optional. |
|
|
34910
|
+
| `top` | `boolean \| undefined` | Put the content at the top of the element (the default). Optional. |
|
|
34911
|
+
| `middle` | `boolean \| undefined` | Put the content in the vertical middle of the element. Use with `height`. Optional. |
|
|
34912
|
+
| `bottom` | `boolean \| undefined` | Put the content at the bottom of the element. Use with `height`. Optional. |
|
|
34913
|
+
|
|
34914
|
+
|
|
34915
|
+
---
|
|
34916
|
+
|
|
34917
|
+
# getHeightClass()
|
|
34918
|
+
|
|
34919
|
+
- Kind: function
|
|
34920
|
+
- Import: `import { getHeightClass } from "shelving/ui";`
|
|
34921
|
+
|
|
34922
|
+
Get the height class for a component from its `height`, `top`, `middle` and `bottom` variant props.
|
|
34923
|
+
|
|
34924
|
+
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()`).
|
|
34925
|
+
|
|
34926
|
+
`getHeightClass({ height, top, middle, bottom })` maps the props to height classes.
|
|
34927
|
+
|
|
34928
|
+
**Values:**
|
|
34929
|
+
|
|
34930
|
+
- `full` — at least the full height of the container, for example a layout's `<Scroll vertical cover>` box.
|
|
34931
|
+
- `1x` / `2x` / `3x` / `4x` / `5x` / `6x` / `7x` / `8x` / `10x` / `12x` / `16x` / `20x` / `24x` / `28x` / `32x` — at least a multiple of `--space-normal`.
|
|
34932
|
+
|
|
34933
|
+
**Things to know:**
|
|
34934
|
+
|
|
34935
|
+
- 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.
|
|
34936
|
+
- `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`.
|
|
34937
|
+
- `<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()`).
|
|
34938
|
+
- In a flex or grid container, `space="auto"` is the other way to centre a block (see `getSpaceClass()`).
|
|
34939
|
+
- `align-content` on a plain block shipped in Chrome 123, Firefox 125 and Safari 17.4. Older browsers show the content at the top.
|
|
34940
|
+
|
|
34941
|
+
## Usage
|
|
34942
|
+
|
|
34943
|
+
A log-in screen, in the middle of a layout's scroll box:
|
|
34944
|
+
|
|
34945
|
+
```tsx
|
|
34946
|
+
<Page title="Log in">
|
|
34947
|
+
<Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
|
|
34948
|
+
<LoginForm />
|
|
34949
|
+
</Block>
|
|
34950
|
+
</Page>
|
|
34951
|
+
```
|
|
34952
|
+
|
|
34953
|
+
|
|
34954
|
+
## Signatures
|
|
34955
|
+
|
|
34956
|
+
```ts
|
|
34957
|
+
getHeightClass({ height, top, middle, bottom }: HeightVariants): string | undefined
|
|
34958
|
+
```
|
|
34959
|
+
|
|
34960
|
+
## Parameters
|
|
34961
|
+
|
|
34962
|
+
| Param | Type | Description |
|
|
34963
|
+
| --- | --- | --- |
|
|
34964
|
+
| `options` | `HeightVariants` | |
|
|
34965
|
+
| `.height` | `HeightVariant \| undefined` | Height of the element. It is a minimum, so the element grows when its content is taller. Optional. |
|
|
34966
|
+
| `.top` | `boolean \| undefined` | Put the content at the top of the element (the default). Optional. |
|
|
34967
|
+
| `.middle` | `boolean \| undefined` | Put the content in the vertical middle of the element. Use with `height`. Optional. |
|
|
34968
|
+
| `.bottom` | `boolean \| undefined` | Put the content at the bottom of the element. Use with `height`. Optional. |
|
|
34969
|
+
|
|
34970
|
+
## Returns
|
|
34971
|
+
|
|
34972
|
+
| Type | Description |
|
|
34973
|
+
| --- | --- |
|
|
34974
|
+
| `string \| undefined` | The height class string, or `undefined` if no height variants are set. |
|
|
34975
|
+
|
|
34976
|
+
## Examples
|
|
34977
|
+
|
|
34978
|
+
```ts
|
|
34979
|
+
getHeightClass({ height: "full", middle: true }) // "height height-full middle"
|
|
34980
|
+
```
|
|
34981
|
+
|
|
34982
|
+
|
|
34368
34983
|
---
|
|
34369
34984
|
|
|
34370
34985
|
# IndentVariant
|
|
@@ -34470,7 +35085,7 @@ Variant props for the block-padding (top + bottom) of a component, e.g. `padding
|
|
|
34470
35085
|
|
|
34471
35086
|
```ts
|
|
34472
35087
|
{
|
|
34473
|
-
padding?: SpaceValue | undefined;
|
|
35088
|
+
padding?: Exclude<SpaceValue, "auto"> | undefined;
|
|
34474
35089
|
}
|
|
34475
35090
|
```
|
|
34476
35091
|
|
|
@@ -34478,7 +35093,7 @@ Variant props for the block-padding (top + bottom) of a component, e.g. `padding
|
|
|
34478
35093
|
|
|
34479
35094
|
| Property | Type | Description |
|
|
34480
35095
|
| --- | --- | --- |
|
|
34481
|
-
| `padding` | `SpaceValue \| undefined` | Block-padding (top + bottom) of the element. Optional. |
|
|
35096
|
+
| `padding` | `Exclude<SpaceValue, "auto"> \| undefined` | Block-padding (top + bottom) of the element. Optional. |
|
|
34482
35097
|
|
|
34483
35098
|
|
|
34484
35099
|
---
|
|
@@ -34501,7 +35116,7 @@ getPaddingClass({ padding }: PaddingVariants): string | undefined
|
|
|
34501
35116
|
| Param | Type | Description |
|
|
34502
35117
|
| --- | --- | --- |
|
|
34503
35118
|
| `options` | `PaddingVariants` | |
|
|
34504
|
-
| `.padding` | `SpaceValue \| undefined` | Block-padding (top + bottom) of the element. Optional. |
|
|
35119
|
+
| `.padding` | `Exclude<SpaceValue, "auto"> \| undefined` | Block-padding (top + bottom) of the element. Optional. |
|
|
34505
35120
|
|
|
34506
35121
|
## Returns
|
|
34507
35122
|
|
|
@@ -34615,7 +35230,7 @@ getRadiusClass({ radius: "large" }) // "radius-large"
|
|
|
34615
35230
|
- Kind: interface
|
|
34616
35231
|
- Import: `import { ScrollVariants } from "shelving/ui";`
|
|
34617
35232
|
|
|
34618
|
-
Variant props
|
|
35233
|
+
Variant props for a scroll region: which axes scroll, plus `cover` and `reverse`.
|
|
34619
35234
|
|
|
34620
35235
|
## Signatures
|
|
34621
35236
|
|
|
@@ -34623,6 +35238,8 @@ Variant props selecting which scroll axes are enabled on an element.
|
|
|
34623
35238
|
{
|
|
34624
35239
|
vertical?: boolean | undefined;
|
|
34625
35240
|
horizontal?: boolean | undefined;
|
|
35241
|
+
cover?: boolean | undefined;
|
|
35242
|
+
reverse?: boolean | undefined;
|
|
34626
35243
|
}
|
|
34627
35244
|
```
|
|
34628
35245
|
|
|
@@ -34632,6 +35249,8 @@ Variant props selecting which scroll axes are enabled on an element.
|
|
|
34632
35249
|
| --- | --- | --- |
|
|
34633
35250
|
| `vertical` | `boolean \| undefined` | Vertical scrolling (defaults to `false`). Optional. |
|
|
34634
35251
|
| `horizontal` | `boolean \| undefined` | Horizontal scrolling (defaults to `false`). Optional. |
|
|
35252
|
+
| `cover` | `boolean \| undefined` | Cover the nearest positioned ancestor (`position: absolute; inset: 0`), for example a layout's content slot (defaults to `false`). Optional. |
|
|
35253
|
+
| `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. |
|
|
34635
35254
|
|
|
34636
35255
|
|
|
34637
35256
|
---
|
|
@@ -34641,12 +35260,12 @@ Variant props selecting which scroll axes are enabled on an element.
|
|
|
34641
35260
|
- Kind: function
|
|
34642
35261
|
- Import: `import { getScrollClass } from "shelving/ui";`
|
|
34643
35262
|
|
|
34644
|
-
Get the scroll class for a component from its `horizontal`
|
|
35263
|
+
Get the scroll class for a component from its `horizontal`, `vertical`, `cover` and `reverse` variant props.
|
|
34645
35264
|
|
|
34646
35265
|
## Signatures
|
|
34647
35266
|
|
|
34648
35267
|
```ts
|
|
34649
|
-
getScrollClass({ horizontal, vertical }: ScrollVariants): string
|
|
35268
|
+
getScrollClass({ horizontal, vertical, cover, reverse }: ScrollVariants): string
|
|
34650
35269
|
```
|
|
34651
35270
|
|
|
34652
35271
|
## Parameters
|
|
@@ -34656,6 +35275,8 @@ getScrollClass({ horizontal, vertical }: ScrollVariants): string
|
|
|
34656
35275
|
| `options` | `ScrollVariants` | |
|
|
34657
35276
|
| `.vertical` | `boolean \| undefined` | Vertical scrolling (defaults to `false`). Optional. |
|
|
34658
35277
|
| `.horizontal` | `boolean \| undefined` | Horizontal scrolling (defaults to `false`). Optional. |
|
|
35278
|
+
| `.cover` | `boolean \| undefined` | Cover the nearest positioned ancestor (`position: absolute; inset: 0`), for example a layout's content slot (defaults to `false`). Optional. |
|
|
35279
|
+
| `.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. |
|
|
34659
35280
|
|
|
34660
35281
|
## Returns
|
|
34661
35282
|
|
|
@@ -34695,6 +35316,66 @@ Props for the `Scroll` component — children plus scroll-axis variants.
|
|
|
34695
35316
|
- Import: `import { Scroll } from "shelving/ui";`
|
|
34696
35317
|
|
|
34697
35318
|
Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
|
|
35319
|
+
- With `cover`, it fills a layout's content slot, so each page in a `<RouteCache>` scrolls in its own box.
|
|
35320
|
+
|
|
35321
|
+
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.
|
|
35322
|
+
|
|
35323
|
+
**Things to know:**
|
|
35324
|
+
|
|
35325
|
+
- Set `vertical`, `horizontal`, or both. With neither, the box clips its content and does not scroll.
|
|
35326
|
+
- 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.
|
|
35327
|
+
- 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.
|
|
35328
|
+
- Overscroll stops at the box edge (`overscroll-behavior: none`), so a scroll inside the box never scrolls the page behind it.
|
|
35329
|
+
- When the box has keyboard focus, it shows a focus outline.
|
|
35330
|
+
|
|
35331
|
+
## Usage
|
|
35332
|
+
|
|
35333
|
+
### A wide table
|
|
35334
|
+
|
|
35335
|
+
```tsx
|
|
35336
|
+
import { Scroll, Table } from "shelving/ui";
|
|
35337
|
+
|
|
35338
|
+
<Scroll horizontal>
|
|
35339
|
+
<Table>…</Table>
|
|
35340
|
+
</Scroll>
|
|
35341
|
+
```
|
|
35342
|
+
|
|
35343
|
+
### A scroll box for each page
|
|
35344
|
+
|
|
35345
|
+
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.
|
|
35346
|
+
|
|
35347
|
+
```tsx
|
|
35348
|
+
import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
|
|
35349
|
+
|
|
35350
|
+
<AppLayout nav={<StackBar />}>
|
|
35351
|
+
<HorizontalTransition>
|
|
35352
|
+
<RouteCache>
|
|
35353
|
+
<Scroll vertical cover>
|
|
35354
|
+
<PageLoader>
|
|
35355
|
+
<Router routes={ROUTES} />
|
|
35356
|
+
</PageLoader>
|
|
35357
|
+
</Scroll>
|
|
35358
|
+
</RouteCache>
|
|
35359
|
+
</HorizontalTransition>
|
|
35360
|
+
</AppLayout>
|
|
35361
|
+
```
|
|
35362
|
+
|
|
35363
|
+
### A chat
|
|
35364
|
+
|
|
35365
|
+
```tsx
|
|
35366
|
+
<Scroll vertical cover reverse>
|
|
35367
|
+
<div>{messages}</div>
|
|
35368
|
+
</Scroll>
|
|
35369
|
+
```
|
|
35370
|
+
|
|
35371
|
+
## Styling
|
|
35372
|
+
|
|
35373
|
+
| Variable | Styles | Default |
|
|
35374
|
+
|---|---|---|
|
|
35375
|
+
| `--scroll-focus-border` | Outline when the box has keyboard focus | `var(--stroke-focus) solid var(--color-focus)` |
|
|
35376
|
+
|
|
35377
|
+
**Global tokens it reads** — `--stroke-focus`, `--stroke-normal`, and `--color-focus`.
|
|
35378
|
+
|
|
34698
35379
|
|
|
34699
35380
|
## Signatures
|
|
34700
35381
|
|
|
@@ -34714,12 +35395,6 @@ Scroll({ children, ...props }: ScrollComponentProps): ReactElement
|
|
|
34714
35395
|
| --- | --- |
|
|
34715
35396
|
| `ReactElement` | A `<div>` element with the computed scroll class. |
|
|
34716
35397
|
|
|
34717
|
-
## Examples
|
|
34718
|
-
|
|
34719
|
-
```ts
|
|
34720
|
-
<Scroll horizontal>{wideContent}</Scroll>
|
|
34721
|
-
```
|
|
34722
|
-
|
|
34723
35398
|
|
|
34724
35399
|
---
|
|
34725
35400
|
|
|
@@ -34829,6 +35504,7 @@ Allowed values for block spacing for components that support `SpaceVariants`
|
|
|
34829
35504
|
| "section"
|
|
34830
35505
|
| "paragraph"
|
|
34831
35506
|
| "none"
|
|
35507
|
+
| "auto"
|
|
34832
35508
|
| "xxsmall"
|
|
34833
35509
|
| "xsmall"
|
|
34834
35510
|
| "small"
|
|
@@ -34886,6 +35562,8 @@ The `space` variant prop sets a block-level element's `margin-block` (top + bott
|
|
|
34886
35562
|
|
|
34887
35563
|
`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`.
|
|
34888
35564
|
|
|
35565
|
+
`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`.
|
|
35566
|
+
|
|
34889
35567
|
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.
|
|
34890
35568
|
|
|
34891
35569
|
## Theme variables
|
|
@@ -36580,7 +37258,7 @@ Props for the `TreeApp` component — the tree to render plus optional extra rou
|
|
|
36580
37258
|
|
|
36581
37259
|
Top-level app component for a tree-based documentation site.
|
|
36582
37260
|
|
|
36583
|
-
- Wraps `<App>` with error catching and a sidebar layout.
|
|
37261
|
+
- 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.
|
|
36584
37262
|
- Flattens `tree` once via `<TreeProvider>` wrapping both the sidebar and the router, so everything below shares a single `useTreeMap()` lookup — nothing re-flattens.
|
|
36585
37263
|
- The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
|
|
36586
37264
|
- `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
|