shelving 1.321.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 +204 -1
- package/docs/llms-full.txt +786 -114
- 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/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/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/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/ui/Router.md
CHANGED
|
@@ -21,7 +21,7 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
|
|
|
21
21
|
- 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`.
|
|
22
22
|
- Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
|
|
23
23
|
- 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.
|
|
24
|
-
- `<Router>` itself does not cache pages — wrap it in a `<RouteCache>` (
|
|
24
|
+
- `<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.
|
|
25
25
|
|
|
26
26
|
## Usage
|
|
27
27
|
|
|
@@ -67,7 +67,7 @@ Modifier chars are tolerant: one-or-more stars and three-or-more dots are all eq
|
|
|
67
67
|
|
|
68
68
|
### Layout wrapping
|
|
69
69
|
|
|
70
|
-
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.
|
|
70
|
+
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>`.
|
|
71
71
|
|
|
72
72
|
```tsx
|
|
73
73
|
const SIDEBARRED_ROUTES = {
|
|
@@ -80,7 +80,9 @@ const SIDEBARRED_ROUTES = {
|
|
|
80
80
|
"/": <HomePage/>,
|
|
81
81
|
"/{...path}": (
|
|
82
82
|
<SidebarLayout sidebar={<Nav/>}>
|
|
83
|
-
<
|
|
83
|
+
<Scroll vertical cover>
|
|
84
|
+
<Router routes={SIDEBARRED_ROUTES}/>
|
|
85
|
+
</Scroll>
|
|
84
86
|
</SidebarLayout>
|
|
85
87
|
),
|
|
86
88
|
}}/>
|
|
@@ -127,7 +129,9 @@ const SIDEBARRED_ROUTES = {
|
|
|
127
129
|
"/login": <LoginPage/>, // no sidebar
|
|
128
130
|
"/{...path}": ( // everything else wrapped
|
|
129
131
|
<SidebarLayout sidebar={<Nav/>}>
|
|
130
|
-
<
|
|
132
|
+
<Scroll vertical cover>
|
|
133
|
+
<Router routes={SIDEBARRED_ROUTES}/>
|
|
134
|
+
</Scroll>
|
|
131
135
|
</SidebarLayout>
|
|
132
136
|
),
|
|
133
137
|
}}/>
|
|
@@ -135,7 +139,7 @@ const SIDEBARRED_ROUTES = {
|
|
|
135
139
|
|
|
136
140
|
### Keeping page state
|
|
137
141
|
|
|
138
|
-
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
|
|
142
|
+
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.
|
|
139
143
|
|
|
140
144
|
### SSR / static rendering
|
|
141
145
|
|
package/docs/ui/Scroll.md
CHANGED
|
@@ -4,6 +4,66 @@
|
|
|
4
4
|
- Import: `import { Scroll } from "shelving/ui";`
|
|
5
5
|
|
|
6
6
|
Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
|
|
7
|
+
- With `cover`, it fills a layout's content slot, so each page in a `<RouteCache>` scrolls in its own box.
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
**Things to know:**
|
|
12
|
+
|
|
13
|
+
- Set `vertical`, `horizontal`, or both. With neither, the box clips its content and does not scroll.
|
|
14
|
+
- 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.
|
|
15
|
+
- 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.
|
|
16
|
+
- Overscroll stops at the box edge (`overscroll-behavior: none`), so a scroll inside the box never scrolls the page behind it.
|
|
17
|
+
- When the box has keyboard focus, it shows a focus outline.
|
|
18
|
+
|
|
19
|
+
## Usage
|
|
20
|
+
|
|
21
|
+
### A wide table
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
import { Scroll, Table } from "shelving/ui";
|
|
25
|
+
|
|
26
|
+
<Scroll horizontal>
|
|
27
|
+
<Table>…</Table>
|
|
28
|
+
</Scroll>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### A scroll box for each page
|
|
32
|
+
|
|
33
|
+
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.
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
|
|
37
|
+
|
|
38
|
+
<AppLayout nav={<StackBar />}>
|
|
39
|
+
<HorizontalTransition>
|
|
40
|
+
<RouteCache>
|
|
41
|
+
<Scroll vertical cover>
|
|
42
|
+
<PageLoader>
|
|
43
|
+
<Router routes={ROUTES} />
|
|
44
|
+
</PageLoader>
|
|
45
|
+
</Scroll>
|
|
46
|
+
</RouteCache>
|
|
47
|
+
</HorizontalTransition>
|
|
48
|
+
</AppLayout>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### A chat
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
<Scroll vertical cover reverse>
|
|
55
|
+
<div>{messages}</div>
|
|
56
|
+
</Scroll>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Styling
|
|
60
|
+
|
|
61
|
+
| Variable | Styles | Default |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| `--scroll-focus-border` | Outline when the box has keyboard focus | `var(--stroke-focus) solid var(--color-focus)` |
|
|
64
|
+
|
|
65
|
+
**Global tokens it reads** — `--stroke-focus`, `--stroke-normal`, and `--color-focus`.
|
|
66
|
+
|
|
7
67
|
|
|
8
68
|
## Signatures
|
|
9
69
|
|
|
@@ -22,9 +82,3 @@ Scroll({ children, ...props }: ScrollComponentProps): ReactElement
|
|
|
22
82
|
| Type | Description |
|
|
23
83
|
| --- | --- |
|
|
24
84
|
| `ReactElement` | A `<div>` element with the computed scroll class. |
|
|
25
|
-
|
|
26
|
-
## Examples
|
|
27
|
-
|
|
28
|
-
```ts
|
|
29
|
-
<Scroll horizontal>{wideContent}</Scroll>
|
|
30
|
-
```
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
- Kind: interface
|
|
4
4
|
- Import: `import { ScrollVariants } from "shelving/ui";`
|
|
5
5
|
|
|
6
|
-
Variant props
|
|
6
|
+
Variant props for a scroll region: which axes scroll, plus `cover` and `reverse`.
|
|
7
7
|
|
|
8
8
|
## Signatures
|
|
9
9
|
|
|
@@ -11,6 +11,8 @@ Variant props selecting which scroll axes are enabled on an element.
|
|
|
11
11
|
{
|
|
12
12
|
vertical?: boolean | undefined;
|
|
13
13
|
horizontal?: boolean | undefined;
|
|
14
|
+
cover?: boolean | undefined;
|
|
15
|
+
reverse?: boolean | undefined;
|
|
14
16
|
}
|
|
15
17
|
```
|
|
16
18
|
|
|
@@ -20,3 +22,5 @@ Variant props selecting which scroll axes are enabled on an element.
|
|
|
20
22
|
| --- | --- | --- |
|
|
21
23
|
| `vertical` | `boolean \| undefined` | Vertical scrolling (defaults to `false`). Optional. |
|
|
22
24
|
| `horizontal` | `boolean \| undefined` | Horizontal scrolling (defaults to `false`). Optional. |
|
|
25
|
+
| `cover` | `boolean \| undefined` | Cover the nearest positioned ancestor (`position: absolute; inset: 0`), for example a layout's content slot (defaults to `false`). Optional. |
|
|
26
|
+
| `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. |
|
package/docs/ui/SidebarLayout.md
CHANGED
|
@@ -3,14 +3,14 @@
|
|
|
3
3
|
- Kind: component
|
|
4
4
|
- Import: `import { SidebarLayout } from "shelving/ui";`
|
|
5
5
|
|
|
6
|
-
Layout with a fixed-width side column (typically navigation) next to a
|
|
6
|
+
Layout with a fixed-width side column (typically navigation) next to a content slot.
|
|
7
7
|
- The sidebar is rendered as `<nav>` — it almost always contains the page's primary navigation.
|
|
8
8
|
- 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.
|
|
9
9
|
- While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
|
|
10
10
|
- Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
|
|
11
|
-
-
|
|
11
|
+
- 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.
|
|
12
12
|
|
|
13
|
-
A full-viewport layout with a fixed-width side column next to a
|
|
13
|
+
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.
|
|
14
14
|
|
|
15
15
|
**Things to know:**
|
|
16
16
|
|
|
@@ -19,12 +19,15 @@ A full-viewport layout with a fixed-width side column next to a scrollable main
|
|
|
19
19
|
- While the drawer is open an overlay dims the page; clicking the overlay closes it.
|
|
20
20
|
- 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.
|
|
21
21
|
- Inside a `<Navigation>` context the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
|
|
22
|
-
- The
|
|
22
|
+
- 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.
|
|
23
|
+
- The sidebar stays outside the page cache, so it keeps its own scroll position and state as pages change.
|
|
24
|
+
- On a narrow screen the menu button floats at the top right of the content slot, above the page.
|
|
25
|
+
- Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
|
|
23
26
|
|
|
24
27
|
## Usage
|
|
25
28
|
|
|
26
29
|
```tsx
|
|
27
|
-
import {
|
|
30
|
+
import { Menu, MenuItem, PageLoader, RouteCache, Router, Scroll, SidebarLayout } from "shelving/ui";
|
|
28
31
|
|
|
29
32
|
function AppShell() {
|
|
30
33
|
const nav = (
|
|
@@ -36,13 +39,19 @@ function AppShell() {
|
|
|
36
39
|
);
|
|
37
40
|
return (
|
|
38
41
|
<SidebarLayout sidebar={nav}>
|
|
39
|
-
<
|
|
42
|
+
<RouteCache>
|
|
43
|
+
<Scroll vertical cover>
|
|
44
|
+
<PageLoader>
|
|
45
|
+
<Router routes={ROUTES}/>
|
|
46
|
+
</PageLoader>
|
|
47
|
+
</Scroll>
|
|
48
|
+
</RouteCache>
|
|
40
49
|
</SidebarLayout>
|
|
41
50
|
);
|
|
42
51
|
}
|
|
43
52
|
```
|
|
44
53
|
|
|
45
|
-
|
|
54
|
+
To slide pages, put a transition around the `<RouteCache>`, inside the layout. The sidebar is outside the transition, so it stays still.
|
|
46
55
|
|
|
47
56
|
## Styling
|
|
48
57
|
|
|
@@ -56,7 +65,7 @@ Layouts compose naturally as `<Router>` route values — wrap a group of routes
|
|
|
56
65
|
| `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-90)` | `none` |
|
|
57
66
|
| `--sidebar-layout-shadow` | Drop shadow of the open drawer on a narrow screen | `var(--shadow-large)` |
|
|
58
67
|
|
|
59
|
-
The sidebar
|
|
68
|
+
The sidebar scrolls on its own. The content slot does not scroll: its `<Scroll vertical cover>` box does.
|
|
60
69
|
|
|
61
70
|
**Global tokens it reads** — `--tint-00` / `--tint-90` / `--tint-100`, plus `--space-normal`, `--duration-normal`, `--shadow-large`, and `--color-backdrop`.
|
|
62
71
|
|
package/docs/ui/SpaceValue.md
CHANGED
package/docs/ui/TreeApp.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
|
|
6
6
|
Top-level app component for a tree-based documentation site.
|
|
7
7
|
|
|
8
|
-
- Wraps `<App>` with error catching and a sidebar layout.
|
|
8
|
+
- 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.
|
|
9
9
|
- Flattens `tree` once via `<TreeProvider>` wrapping both the sidebar and the router, so everything below shares a single `useTreeMap()` lookup — nothing re-flattens.
|
|
10
10
|
- The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
|
|
11
11
|
- `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
|
package/docs/ui/getBlockClass.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
|
|
6
6
|
Get the combined `className` string for a block from its styling variants.
|
|
7
7
|
|
|
8
|
-
Composes the base block class and tint ladder with the colour, space, typography, and
|
|
8
|
+
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.
|
|
9
9
|
|
|
10
10
|
## Signatures
|
|
11
11
|
|
package/docs/ui/getGapClass.md
CHANGED
|
@@ -16,7 +16,7 @@ getGapClass({ gap }: GapVariants): string | undefined
|
|
|
16
16
|
| Param | Type | Description |
|
|
17
17
|
| --- | --- | --- |
|
|
18
18
|
| `options` | `GapVariants` | |
|
|
19
|
-
| `.gap` | `SpaceValue \| undefined` | Gap between child elements. Optional. |
|
|
19
|
+
| `.gap` | `Exclude<SpaceValue, "auto"> \| undefined` | Gap between child elements. Optional. |
|
|
20
20
|
|
|
21
21
|
## Returns
|
|
22
22
|
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# getHeightClass()
|
|
2
|
+
|
|
3
|
+
- Kind: function
|
|
4
|
+
- Import: `import { getHeightClass } from "shelving/ui";`
|
|
5
|
+
|
|
6
|
+
Get the height class for a component from its `height`, `top`, `middle` and `bottom` variant props.
|
|
7
|
+
|
|
8
|
+
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()`).
|
|
9
|
+
|
|
10
|
+
`getHeightClass({ height, top, middle, bottom })` maps the props to height classes.
|
|
11
|
+
|
|
12
|
+
**Values:**
|
|
13
|
+
|
|
14
|
+
- `full` — at least the full height of the container, for example a layout's `<Scroll vertical cover>` box.
|
|
15
|
+
- `1x` / `2x` / `3x` / `4x` / `5x` / `6x` / `7x` / `8x` / `10x` / `12x` / `16x` / `20x` / `24x` / `28x` / `32x` — at least a multiple of `--space-normal`.
|
|
16
|
+
|
|
17
|
+
**Things to know:**
|
|
18
|
+
|
|
19
|
+
- 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.
|
|
20
|
+
- `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`.
|
|
21
|
+
- `<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()`).
|
|
22
|
+
- In a flex or grid container, `space="auto"` is the other way to centre a block (see `getSpaceClass()`).
|
|
23
|
+
- `align-content` on a plain block shipped in Chrome 123, Firefox 125 and Safari 17.4. Older browsers show the content at the top.
|
|
24
|
+
|
|
25
|
+
## Usage
|
|
26
|
+
|
|
27
|
+
A log-in screen, in the middle of a layout's scroll box:
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
<Page title="Log in">
|
|
31
|
+
<Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
|
|
32
|
+
<LoginForm />
|
|
33
|
+
</Block>
|
|
34
|
+
</Page>
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
## Signatures
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
getHeightClass({ height, top, middle, bottom }: HeightVariants): string | undefined
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Parameters
|
|
45
|
+
|
|
46
|
+
| Param | Type | Description |
|
|
47
|
+
| --- | --- | --- |
|
|
48
|
+
| `options` | `HeightVariants` | |
|
|
49
|
+
| `.height` | `HeightVariant \| undefined` | Height of the element. It is a minimum, so the element grows when its content is taller. Optional. |
|
|
50
|
+
| `.top` | `boolean \| undefined` | Put the content at the top of the element (the default). Optional. |
|
|
51
|
+
| `.middle` | `boolean \| undefined` | Put the content in the vertical middle of the element. Use with `height`. Optional. |
|
|
52
|
+
| `.bottom` | `boolean \| undefined` | Put the content at the bottom of the element. Use with `height`. Optional. |
|
|
53
|
+
|
|
54
|
+
## Returns
|
|
55
|
+
|
|
56
|
+
| Type | Description |
|
|
57
|
+
| --- | --- |
|
|
58
|
+
| `string \| undefined` | The height class string, or `undefined` if no height variants are set. |
|
|
59
|
+
|
|
60
|
+
## Examples
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
getHeightClass({ height: "full", middle: true }) // "height height-full middle"
|
|
64
|
+
```
|
|
@@ -16,7 +16,7 @@ getPaddingClass({ padding }: PaddingVariants): string | undefined
|
|
|
16
16
|
| Param | Type | Description |
|
|
17
17
|
| --- | --- | --- |
|
|
18
18
|
| `options` | `PaddingVariants` | |
|
|
19
|
-
| `.padding` | `SpaceValue \| undefined` | Block-padding (top + bottom) of the element. Optional. |
|
|
19
|
+
| `.padding` | `Exclude<SpaceValue, "auto"> \| undefined` | Block-padding (top + bottom) of the element. Optional. |
|
|
20
20
|
|
|
21
21
|
## Returns
|
|
22
22
|
|
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
- Kind: function
|
|
4
4
|
- Import: `import { getScrollClass } from "shelving/ui";`
|
|
5
5
|
|
|
6
|
-
Get the scroll class for a component from its `horizontal`
|
|
6
|
+
Get the scroll class for a component from its `horizontal`, `vertical`, `cover` and `reverse` variant props.
|
|
7
7
|
|
|
8
8
|
## Signatures
|
|
9
9
|
|
|
10
10
|
```ts
|
|
11
|
-
getScrollClass({ horizontal, vertical }: ScrollVariants): string
|
|
11
|
+
getScrollClass({ horizontal, vertical, cover, reverse }: ScrollVariants): string
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
## Parameters
|
|
@@ -18,6 +18,8 @@ getScrollClass({ horizontal, vertical }: ScrollVariants): string
|
|
|
18
18
|
| `options` | `ScrollVariants` | |
|
|
19
19
|
| `.vertical` | `boolean \| undefined` | Vertical scrolling (defaults to `false`). Optional. |
|
|
20
20
|
| `.horizontal` | `boolean \| undefined` | Horizontal scrolling (defaults to `false`). Optional. |
|
|
21
|
+
| `.cover` | `boolean \| undefined` | Cover the nearest positioned ancestor (`position: absolute; inset: 0`), for example a layout's content slot (defaults to `false`). Optional. |
|
|
22
|
+
| `.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. |
|
|
21
23
|
|
|
22
24
|
## Returns
|
|
23
25
|
|
package/docs/ui/getSpaceClass.md
CHANGED
|
@@ -9,6 +9,8 @@ The `space` variant prop sets a block-level element's `margin-block` (top + bott
|
|
|
9
9
|
|
|
10
10
|
`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`.
|
|
11
11
|
|
|
12
|
+
`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`.
|
|
13
|
+
|
|
12
14
|
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.
|
|
13
15
|
|
|
14
16
|
## Theme variables
|
package/docs/ui.md
CHANGED
|
@@ -62,7 +62,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
62
62
|
|
|
63
63
|
**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>`.
|
|
64
64
|
|
|
65
|
-
**Structure.** Mount a client app with `<App>`, or render a full server document with `<HTML>` and `<Page>`. Arrange the screen with `<
|
|
65
|
+
**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>`.
|
|
66
66
|
|
|
67
67
|
**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>`.
|
|
68
68
|
|
|
@@ -176,14 +176,15 @@ The components below are listed in the index following this page; this is the sh
|
|
|
176
176
|
- [DataSchemaInput](ui/DataSchemaInput.md): Show a DataInput for a nested DataSchema.
|
|
177
177
|
- [SchemaField](ui/SchemaField.md): Show the appropriate input for a schema, wrapped in a <Field> with its label and message.
|
|
178
178
|
- [SelectInput](ui/SelectInput.md): Dropdown input bound to a string value, rendered as a <select> of the provided options.
|
|
179
|
-
- [
|
|
180
|
-
- [
|
|
179
|
+
- [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.
|
|
180
|
+
- [FixedLayout](ui/FixedLayout.md): Layout with no chrome: the whole screen is one content slot.
|
|
181
|
+
- [SidebarLayout](ui/SidebarLayout.md): Layout with a fixed-width side column (typically navigation) next to a content slot.
|
|
181
182
|
- [Menu](ui/Menu.md): A <menu> list of <MenuItem> children.
|
|
182
183
|
- [MenuItem](ui/MenuItem.md): A <li> containing an <a> link, plus optional submenu content shown when this item is "proud".
|
|
183
184
|
- [Catcher](ui/Catcher.md): React error boundary that renders a fallback component when any descendant throws.
|
|
184
185
|
- [ErrorNotice](ui/ErrorNotice.md): Render a caught error as an inline <Notice> with a retry button.
|
|
185
186
|
- [PageCatcher](ui/PageCatcher.md): Error boundary for a whole page that renders a full <ErrorPage> fallback on error.
|
|
186
|
-
- [ErrorPage](ui/ErrorPage.md): Render a caught error as a
|
|
187
|
+
- [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.
|
|
187
188
|
- [Icon](ui/Icon.md): Render the icon for a given status, coloured to match.
|
|
188
189
|
- [Loader](ui/Loader.md): Load a component.
|
|
189
190
|
- [PageLoader](ui/PageLoader.md): Load a page.
|
|
@@ -198,7 +199,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
198
199
|
- [Page](ui/Page.md): Wrap a single page (or screen) within an app, applying its meta and head tags.
|
|
199
200
|
- [BackButton](ui/BackButton.md): Back button for the current stack.
|
|
200
201
|
- [Navigation](ui/Navigation.md): Top-level navigation provider, with one stack of pages for each tab.
|
|
201
|
-
- [RouteCache](ui/RouteCache.md): Keep-alive page cache for the pages in the navigation stacks.
|
|
202
|
+
- [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.
|
|
202
203
|
- [Router](ui/Router.md): Match the current URL against routes and render the matched element.
|
|
203
204
|
- [StackButton](ui/StackButton.md): Button for one stack in a tab bar.
|
|
204
205
|
- [Scroll](ui/Scroll.md): Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
|
|
@@ -271,10 +272,11 @@ The components below are listed in the index following this page; this is the sh
|
|
|
271
272
|
- [getFlexClass()](ui/getFlexClass.md): Get the flex layout class for a component from its flex variant props.
|
|
272
273
|
- [getGapClass()](ui/getGapClass.md): Get the gap class for a component from its gap variant prop.
|
|
273
274
|
- [getGridClass()](ui/getGridClass.md): Get the grid layout class for a component from its grid variant props.
|
|
275
|
+
- [getHeightClass()](ui/getHeightClass.md): Get the height class for a component from its height, top, middle and bottom variant props.
|
|
274
276
|
- [getIndentClass()](ui/getIndentClass.md): Get the inline-padding ("indent") class for a component from its indent variant prop.
|
|
275
277
|
- [getPaddingClass()](ui/getPaddingClass.md): Get the block-padding class for a component from its padding variant prop.
|
|
276
278
|
- [getRadiusClass()](ui/getRadiusClass.md): Get the corner-radius class for a component from its radius variant prop.
|
|
277
|
-
- [getScrollClass()](ui/getScrollClass.md): Get the scroll class for a component from its horizontal
|
|
279
|
+
- [getScrollClass()](ui/getScrollClass.md): Get the scroll class for a component from its horizontal, vertical, cover and reverse variant props.
|
|
278
280
|
- [getShadowClass()](ui/getShadowClass.md): Get the drop-shadow class for a component from its shadow variant prop.
|
|
279
281
|
- [getSpaceClass()](ui/getSpaceClass.md): Get the block spacing class for a component from its space="" variant prop.
|
|
280
282
|
- [getStatusClass()](ui/getStatusClass.md): Get the status tint class for a component from its status variant prop.
|
|
@@ -436,7 +438,8 @@ The components below are listed in the index following this page; this is the sh
|
|
|
436
438
|
- [SelectProps](ui/SelectProps.md): Props for SelectInput, a dropdown <select> bound to a string value.
|
|
437
439
|
- [TextareaInputProps](ui/TextareaInputProps.md): Props for TextareaInput, a multiline text input bound to a string value.
|
|
438
440
|
- [TextInputProps](ui/TextInputProps.md): Props for TextInput, a single-line text input bound to a string value.
|
|
439
|
-
- [
|
|
441
|
+
- [AppLayoutProps](ui/AppLayoutProps.md): Props for <AppLayout>: the nav bar content and the content slot children.
|
|
442
|
+
- [FixedLayoutProps](ui/FixedLayoutProps.md): Props for <FixedLayout>: the content slot children.
|
|
440
443
|
- [SidebarLayoutProps](ui/SidebarLayoutProps.md): Props for <SidebarLayout> — the sidebar column content, main children, and a right placement flag.
|
|
441
444
|
- [MenuProps](ui/MenuProps.md): Props for <Menu> — optional <MenuItem> children.
|
|
442
445
|
- [MenuItemProps](ui/MenuItemProps.md): Props for <MenuItem> — <Clickable> props plus children whose first node is the label and the rest the submenu.
|
|
@@ -469,10 +472,11 @@ The components below are listed in the index following this page; this is the sh
|
|
|
469
472
|
- [FlexVariants](ui/FlexVariants.md): Variant props for flex layout — opt-in modifiers any component can mix in via getFlexClass().
|
|
470
473
|
- [GapVariants](ui/GapVariants.md): Variant props for the gap between a component's children, e.g. gap="large".
|
|
471
474
|
- [GridVariants](ui/GridVariants.md): Variant props for grid layout, e.g. columns={3} gap="normal".
|
|
475
|
+
- [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.
|
|
472
476
|
- [IndentVariants](ui/IndentVariants.md): Variant props for the inline-padding ("indent", left + right) of a component, e.g. indent="normal".
|
|
473
477
|
- [PaddingVariants](ui/PaddingVariants.md): Variant props for the block-padding (top + bottom) of a component, e.g. padding="large".
|
|
474
478
|
- [RadiusVariants](ui/RadiusVariants.md): Variant props for the corner radius of an element, e.g. radius="large".
|
|
475
|
-
- [ScrollVariants](ui/ScrollVariants.md): Variant props
|
|
479
|
+
- [ScrollVariants](ui/ScrollVariants.md): Variant props for a scroll region: which axes scroll, plus cover and reverse.
|
|
476
480
|
- [ScrollComponentProps](ui/ScrollComponentProps.md): Props for the Scroll component — children plus scroll-axis variants.
|
|
477
481
|
- [ShadowVariants](ui/ShadowVariants.md): Variant props for the drop shadow of an element, e.g. shadow="large".
|
|
478
482
|
- [SpaceVariants](ui/SpaceVariants.md): Variants to control block spacing on components, e.g. space="large".
|
|
@@ -521,6 +525,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
521
525
|
- [ColorVariant](ui/ColorVariant.md): Enumerated colour names selectable via the color="purple" prop for components that support that support ColorVariants
|
|
522
526
|
- [DurationValue](ui/DurationValue.md): Allowed values for transition timing for components that support DurationVariants
|
|
523
527
|
- [ColumnsVariant](ui/ColumnsVariant.md): Number of equal-width columns selectable via the columns variant prop.
|
|
528
|
+
- [HeightVariant](ui/HeightVariant.md): Enumerated height selectable via the height variant prop.
|
|
524
529
|
- [IndentVariant](ui/IndentVariant.md): Allowed values for inline-padding ("indent") for components that support IndentVariants
|
|
525
530
|
- [RadiusVariant](ui/RadiusVariant.md): Allowed values for border radius for components that support RadiusVariants
|
|
526
531
|
- [ShadowVariant](ui/ShadowVariant.md): Enumerated drop-shadow scale selectable via the shadow="normal" variant prop.
|
package/package.json
CHANGED
package/ui/README.md
CHANGED
|
@@ -59,7 +59,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
59
59
|
|
|
60
60
|
**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>`.
|
|
61
61
|
|
|
62
|
-
**Structure.** Mount a client app with `<App>`, or render a full server document with `<HTML>` and `<Page>`. Arrange the screen with `<
|
|
62
|
+
**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>`.
|
|
63
63
|
|
|
64
64
|
**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>`.
|
|
65
65
|
|
package/ui/app/App.md
CHANGED
|
@@ -9,17 +9,19 @@ Use `<App>` when mounting into an existing HTML page on the client. For server-s
|
|
|
9
9
|
The smallest single-screen app — `<App>` wraps a layout and some content:
|
|
10
10
|
|
|
11
11
|
```tsx
|
|
12
|
-
import { App,
|
|
12
|
+
import { App, FixedLayout, Paragraph, Scroll, Section, Title } from "shelving/ui";
|
|
13
13
|
|
|
14
14
|
function HelloApp() {
|
|
15
15
|
return (
|
|
16
16
|
<App app="My app">
|
|
17
|
-
<
|
|
18
|
-
<
|
|
19
|
-
<
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
17
|
+
<FixedLayout>
|
|
18
|
+
<Scroll vertical cover>
|
|
19
|
+
<Section width="narrow">
|
|
20
|
+
<Title>Hello</Title>
|
|
21
|
+
<Paragraph>Welcome to the app.</Paragraph>
|
|
22
|
+
</Section>
|
|
23
|
+
</Scroll>
|
|
24
|
+
</FixedLayout>
|
|
23
25
|
</App>
|
|
24
26
|
);
|
|
25
27
|
}
|
|
@@ -50,4 +52,100 @@ export function MyApp() {
|
|
|
50
52
|
|
|
51
53
|
`<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.
|
|
52
54
|
|
|
55
|
+
## Composing an app
|
|
56
|
+
|
|
57
|
+
An app is built from layers, each with one job. Write them in plain sight in `App.tsx`, from the outside in:
|
|
58
|
+
|
|
59
|
+
1. **Contexts**: `<App>`, your data contexts, `<Navigation>`, `<DialogsContext>`.
|
|
60
|
+
2. **App-level catcher**: a last resort, outside every layout.
|
|
61
|
+
3. **Layout picker**: your own component that picks the layout (and its props) from the session, the path, or any other state.
|
|
62
|
+
4. **Layout**: `<AppLayout>`, `<SidebarLayout>` or `<FixedLayout>`. It draws the chrome (tab bar, sidebar) and gives a content slot. It knows nothing about the cache.
|
|
63
|
+
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.
|
|
64
|
+
6. **Page**: `<Page>` with its title, then the page content. A page renders no layout.
|
|
65
|
+
|
|
66
|
+
Nesting rules:
|
|
67
|
+
|
|
68
|
+
- The layout sits **above** the router. A page, an error page or a loading state never renders a layout.
|
|
69
|
+
- The transition goes **around** `<RouteCache>`, not inside it.
|
|
70
|
+
- `<Scroll vertical cover>` goes **inside** `<RouteCache>`, so each page keeps its own scroll.
|
|
71
|
+
- Chrome that keeps state or animates (a tab bar, a sidebar) stays in the layout, **outside** the cache.
|
|
72
|
+
- 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.
|
|
73
|
+
|
|
74
|
+
```tsx
|
|
75
|
+
import { useStore } from "shelving/react";
|
|
76
|
+
import {
|
|
77
|
+
App, AppLayout, Catcher, DialogsContext, Dialogs, ErrorPage, FixedLayout, HorizontalTransition,
|
|
78
|
+
Navigation, Notices, PageLoader, requireMetaURL, RouteCache, Router, type ErrorProps, type Routes,
|
|
79
|
+
Scroll, StackButton,
|
|
80
|
+
} from "shelving/ui";
|
|
81
|
+
|
|
82
|
+
const STACKS = ["/home", "/discover", "/profile"] as const;
|
|
83
|
+
|
|
84
|
+
/** 1–2. Contexts and the app-level catcher. No layout here. */
|
|
85
|
+
export function MyApp() {
|
|
86
|
+
const session = useStore(SESSION).value;
|
|
87
|
+
return (
|
|
88
|
+
<App key={session?.id ?? "out"} app="My app" root="https://example.com/">
|
|
89
|
+
<Navigation stacks={STACKS} stack="/home">
|
|
90
|
+
<DialogsContext>
|
|
91
|
+
<Catcher as={AppError}>
|
|
92
|
+
<Shell signedIn={!!session} />
|
|
93
|
+
</Catcher>
|
|
94
|
+
<Dialogs />
|
|
95
|
+
<Notices />
|
|
96
|
+
</DialogsContext>
|
|
97
|
+
</Navigation>
|
|
98
|
+
</App>
|
|
99
|
+
);
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** 3–4. Pick the layout. Plain React, so any rule works. */
|
|
103
|
+
function Shell({ signedIn }: { signedIn: boolean }) {
|
|
104
|
+
const { path } = requireMetaURL();
|
|
105
|
+
if (!signedIn) return <FixedLayout><Content routes={LOGIN_ROUTES} /></FixedLayout>;
|
|
106
|
+
return (
|
|
107
|
+
<AppLayout nav={path.startsWith("/squad/") ? false : <StackBar />}>
|
|
108
|
+
<Content routes={ROUTES} />
|
|
109
|
+
</AppLayout>
|
|
110
|
+
);
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** 5. The content of a layout's slot. */
|
|
114
|
+
function Content({ routes }: { routes: Routes }) {
|
|
115
|
+
return (
|
|
116
|
+
<HorizontalTransition>
|
|
117
|
+
<RouteCache>
|
|
118
|
+
<Scroll vertical cover>
|
|
119
|
+
<PageLoader>
|
|
120
|
+
<Router routes={routes} />
|
|
121
|
+
</PageLoader>
|
|
122
|
+
</Scroll>
|
|
123
|
+
</RouteCache>
|
|
124
|
+
</HorizontalTransition>
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** The tab bar, in the layout, outside the cache. */
|
|
129
|
+
function StackBar() {
|
|
130
|
+
return <>
|
|
131
|
+
<StackButton stack="/home" title="Home"><HomeIcon /></StackButton>
|
|
132
|
+
<StackButton stack="/discover" title="Discover"><SearchIcon /></StackButton>
|
|
133
|
+
<StackButton stack="/profile" title="Profile"><ProfileIcon /></StackButton>
|
|
134
|
+
</>;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/** An error outside every layout: the app picks one here. */
|
|
138
|
+
function AppError({ reason }: ErrorProps) {
|
|
139
|
+
return (
|
|
140
|
+
<FixedLayout>
|
|
141
|
+
<Scroll vertical cover>
|
|
142
|
+
<ErrorPage reason={reason} />
|
|
143
|
+
</Scroll>
|
|
144
|
+
</FixedLayout>
|
|
145
|
+
);
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
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">`.
|
|
150
|
+
|
|
53
151
|
For a documentation site, hand an extracted tree to `<TreeApp>` instead — see the `shelving/extract` guide.
|
|
@@ -3,8 +3,11 @@ import { App } from "../app/App.js";
|
|
|
3
3
|
import { SidebarLayout } from "../layout/SidebarLayout.js";
|
|
4
4
|
import { Menu, MenuItem } from "../menu/Menu.js";
|
|
5
5
|
import { PageCatcher } from "../misc/Catcher.js";
|
|
6
|
+
import { PageLoader } from "../misc/Loader.js";
|
|
6
7
|
import { Navigation } from "../router/Navigation.js";
|
|
8
|
+
import { RouteCache } from "../router/RouteCache.js";
|
|
7
9
|
import { Router } from "../router/Router.js";
|
|
10
|
+
import { Scroll } from "../style/Scroll.js";
|
|
8
11
|
import { TreeProvider } from "../tree/TreeContext.js";
|
|
9
12
|
import { TreeRouter } from "../tree/TreeRouter.js";
|
|
10
13
|
import { TreeSidebar } from "../tree/TreeSidebar.js";
|
|
@@ -22,6 +25,6 @@ import { PLAYGROUND_PAGE_PATH } from "./playground.js";
|
|
|
22
25
|
export function DocumentationApp({ tree, routes = {
|
|
23
26
|
"/search": DocumentationSearchPage,
|
|
24
27
|
}, sidebar = (_jsx(TreeSidebar, { children: _jsxs(Menu, { small: true, children: [_jsx(MenuItem, { href: "/search", children: "Search" }), _jsx(MenuItem, { href: `/${PLAYGROUND_PAGE_PATH}`, children: "Playground" })] }) })), ...meta }) {
|
|
25
|
-
const layout = (_jsx(SidebarLayout, { sidebar: sidebar, children: _jsx(TreeRouter, { fallback: _jsx(Router, { routes: routes }) }) }));
|
|
28
|
+
const layout = (_jsx(SidebarLayout, { sidebar: sidebar, children: _jsx(RouteCache, { children: _jsx(Scroll, { vertical: true, cover: true, children: _jsx(PageLoader, { children: _jsx(TreeRouter, { fallback: _jsx(Router, { routes: routes }) }) }) }) }) }));
|
|
26
29
|
return (_jsx(App, { ...meta, children: _jsx(Navigation, { children: _jsx(PageCatcher, { children: _jsx(TreeProvider, { tree: tree, children: _jsx(Router, { routes: { [`/${PLAYGROUND_PAGE_PATH}`]: DocumentationPlaygroundPage }, fallback: layout }) }) }) }) }));
|
|
27
30
|
}
|