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.
Files changed (101) hide show
  1. package/docs/guides/building-with-shelving.md +204 -1
  2. package/docs/llms-full.txt +786 -114
  3. package/docs/ui/App.md +105 -7
  4. package/docs/ui/AppLayout.md +85 -0
  5. package/docs/ui/AppLayoutProps.md +21 -0
  6. package/docs/ui/Catcher.md +1 -1
  7. package/docs/ui/ErrorPage.md +2 -1
  8. package/docs/ui/FixedLayout.md +91 -0
  9. package/docs/ui/FixedLayoutProps.md +13 -0
  10. package/docs/ui/GapVariants.md +2 -2
  11. package/docs/ui/HeightVariant.md +30 -0
  12. package/docs/ui/HeightVariants.md +26 -0
  13. package/docs/ui/Navigation.md +20 -11
  14. package/docs/ui/PaddingVariants.md +2 -2
  15. package/docs/ui/Page.md +12 -8
  16. package/docs/ui/PageLoader.md +2 -1
  17. package/docs/ui/RouteCache.md +22 -17
  18. package/docs/ui/Router.md +9 -5
  19. package/docs/ui/Scroll.md +60 -6
  20. package/docs/ui/ScrollVariants.md +5 -1
  21. package/docs/ui/SidebarLayout.md +17 -8
  22. package/docs/ui/SpaceValue.md +1 -0
  23. package/docs/ui/TreeApp.md +1 -1
  24. package/docs/ui/getBlockClass.md +1 -1
  25. package/docs/ui/getGapClass.md +1 -1
  26. package/docs/ui/getHeightClass.md +64 -0
  27. package/docs/ui/getPaddingClass.md +1 -1
  28. package/docs/ui/getScrollClass.md +4 -2
  29. package/docs/ui/getSpaceClass.md +2 -0
  30. package/docs/ui.md +13 -8
  31. package/package.json +1 -1
  32. package/ui/README.md +1 -1
  33. package/ui/app/App.md +105 -7
  34. package/ui/docs/DocumentationApp.js +4 -1
  35. package/ui/docs/DocumentationApp.tsx +10 -1
  36. package/ui/layout/AppLayout.d.ts +21 -0
  37. package/ui/layout/AppLayout.js +18 -0
  38. package/ui/layout/AppLayout.md +57 -0
  39. package/ui/layout/AppLayout.module.css +106 -0
  40. package/ui/layout/AppLayout.tsx +36 -0
  41. package/ui/layout/FixedLayout.d.ts +18 -0
  42. package/ui/layout/FixedLayout.js +15 -0
  43. package/ui/layout/FixedLayout.md +65 -0
  44. package/ui/layout/FixedLayout.module.css +55 -0
  45. package/ui/layout/FixedLayout.tsx +25 -0
  46. package/ui/layout/SidebarLayout.d.ts +2 -2
  47. package/ui/layout/SidebarLayout.js +3 -4
  48. package/ui/layout/SidebarLayout.md +15 -6
  49. package/ui/layout/SidebarLayout.module.css +11 -16
  50. package/ui/layout/SidebarLayout.tsx +10 -13
  51. package/ui/layout/index.d.ts +2 -1
  52. package/ui/layout/index.js +2 -1
  53. package/ui/layout/index.tsx +2 -1
  54. package/ui/misc/Catcher.d.ts +2 -1
  55. package/ui/misc/Catcher.js +4 -3
  56. package/ui/misc/Catcher.md +1 -1
  57. package/ui/misc/Catcher.tsx +5 -4
  58. package/ui/misc/Loader.d.ts +1 -0
  59. package/ui/misc/Loader.js +6 -2
  60. package/ui/misc/Loader.tsx +11 -2
  61. package/ui/page/Page.md +12 -8
  62. package/ui/router/Navigation.md +20 -11
  63. package/ui/router/RouteCache.d.ts +2 -1
  64. package/ui/router/RouteCache.js +2 -1
  65. package/ui/router/RouteCache.md +20 -16
  66. package/ui/router/RouteCache.tsx +2 -1
  67. package/ui/router/Router.md +9 -5
  68. package/ui/style/Block.d.ts +3 -2
  69. package/ui/style/Block.js +3 -2
  70. package/ui/style/Block.tsx +4 -2
  71. package/ui/style/Gap.d.ts +1 -1
  72. package/ui/style/Gap.tsx +1 -1
  73. package/ui/style/Height.d.ts +32 -0
  74. package/ui/style/Height.js +13 -0
  75. package/ui/style/Height.module.css +88 -0
  76. package/ui/style/Height.tsx +61 -0
  77. package/ui/style/Padding.d.ts +1 -1
  78. package/ui/style/Padding.tsx +1 -1
  79. package/ui/style/Scroll.d.ts +9 -5
  80. package/ui/style/Scroll.js +6 -4
  81. package/ui/style/Scroll.md +59 -0
  82. package/ui/style/Scroll.module.css +13 -1
  83. package/ui/style/Scroll.tsx +13 -5
  84. package/ui/style/Space.d.ts +1 -1
  85. package/ui/style/Space.module.css +12 -0
  86. package/ui/style/Space.tsx +1 -0
  87. package/ui/style/getHeightClass.md +30 -0
  88. package/ui/style/getSpaceClass.md +2 -0
  89. package/ui/style/index.d.ts +1 -0
  90. package/ui/style/index.js +1 -0
  91. package/ui/style/index.ts +1 -0
  92. package/ui/tree/TreeApp.d.ts +1 -1
  93. package/ui/tree/TreeApp.js +5 -2
  94. package/ui/tree/TreeApp.tsx +11 -2
  95. package/docs/ui/CenteredLayout.md +0 -66
  96. package/docs/ui/CenteredLayoutProps.md +0 -14
  97. package/ui/layout/CenteredLayout.d.ts +0 -21
  98. package/ui/layout/CenteredLayout.js +0 -28
  99. package/ui/layout/CenteredLayout.md +0 -41
  100. package/ui/layout/CenteredLayout.module.css +0 -72
  101. package/ui/layout/CenteredLayout.tsx +0 -56
package/docs/ui/App.md CHANGED
@@ -16,17 +16,19 @@ Use `<App>` when mounting into an existing HTML page on the client. For server-s
16
16
  The smallest single-screen app — `<App>` wraps a layout and some content:
17
17
 
18
18
  ```tsx
19
- import { App, CenteredLayout, Section, Title, Paragraph } from "shelving/ui";
19
+ import { App, FixedLayout, Paragraph, Scroll, Section, Title } from "shelving/ui";
20
20
 
21
21
  function HelloApp() {
22
22
  return (
23
23
  <App app="My app">
24
- <CenteredLayout>
25
- <Section width="narrow">
26
- <Title>Hello</Title>
27
- <Paragraph>Welcome to the app.</Paragraph>
28
- </Section>
29
- </CenteredLayout>
24
+ <FixedLayout>
25
+ <Scroll vertical cover>
26
+ <Section width="narrow">
27
+ <Title>Hello</Title>
28
+ <Paragraph>Welcome to the app.</Paragraph>
29
+ </Section>
30
+ </Scroll>
31
+ </FixedLayout>
30
32
  </App>
31
33
  );
32
34
  }
@@ -57,6 +59,102 @@ export function MyApp() {
57
59
 
58
60
  `<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.
59
61
 
62
+ ## Composing an app
63
+
64
+ An app is built from layers, each with one job. Write them in plain sight in `App.tsx`, from the outside in:
65
+
66
+ 1. **Contexts**: `<App>`, your data contexts, `<Navigation>`, `<DialogsContext>`.
67
+ 2. **App-level catcher**: a last resort, outside every layout.
68
+ 3. **Layout picker**: your own component that picks the layout (and its props) from the session, the path, or any other state.
69
+ 4. **Layout**: `<AppLayout>`, `<SidebarLayout>` or `<FixedLayout>`. It draws the chrome (tab bar, sidebar) and gives a content slot. It knows nothing about the cache.
70
+ 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.
71
+ 6. **Page**: `<Page>` with its title, then the page content. A page renders no layout.
72
+
73
+ Nesting rules:
74
+
75
+ - The layout sits **above** the router. A page, an error page or a loading state never renders a layout.
76
+ - The transition goes **around** `<RouteCache>`, not inside it.
77
+ - `<Scroll vertical cover>` goes **inside** `<RouteCache>`, so each page keeps its own scroll.
78
+ - Chrome that keeps state or animates (a tab bar, a sidebar) stays in the layout, **outside** the cache.
79
+ - 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.
80
+
81
+ ```tsx
82
+ import { useStore } from "shelving/react";
83
+ import {
84
+ App, AppLayout, Catcher, DialogsContext, Dialogs, ErrorPage, FixedLayout, HorizontalTransition,
85
+ Navigation, Notices, PageLoader, requireMetaURL, RouteCache, Router, type ErrorProps, type Routes,
86
+ Scroll, StackButton,
87
+ } from "shelving/ui";
88
+
89
+ const STACKS = ["/home", "/discover", "/profile"] as const;
90
+
91
+ /** 1–2. Contexts and the app-level catcher. No layout here. */
92
+ export function MyApp() {
93
+ const session = useStore(SESSION).value;
94
+ return (
95
+ <App key={session?.id ?? "out"} app="My app" root="https://example.com/">
96
+ <Navigation stacks={STACKS} stack="/home">
97
+ <DialogsContext>
98
+ <Catcher as={AppError}>
99
+ <Shell signedIn={!!session} />
100
+ </Catcher>
101
+ <Dialogs />
102
+ <Notices />
103
+ </DialogsContext>
104
+ </Navigation>
105
+ </App>
106
+ );
107
+ }
108
+
109
+ /** 3–4. Pick the layout. Plain React, so any rule works. */
110
+ function Shell({ signedIn }: { signedIn: boolean }) {
111
+ const { path } = requireMetaURL();
112
+ if (!signedIn) return <FixedLayout><Content routes={LOGIN_ROUTES} /></FixedLayout>;
113
+ return (
114
+ <AppLayout nav={path.startsWith("/squad/") ? false : <StackBar />}>
115
+ <Content routes={ROUTES} />
116
+ </AppLayout>
117
+ );
118
+ }
119
+
120
+ /** 5. The content of a layout's slot. */
121
+ function Content({ routes }: { routes: Routes }) {
122
+ return (
123
+ <HorizontalTransition>
124
+ <RouteCache>
125
+ <Scroll vertical cover>
126
+ <PageLoader>
127
+ <Router routes={routes} />
128
+ </PageLoader>
129
+ </Scroll>
130
+ </RouteCache>
131
+ </HorizontalTransition>
132
+ );
133
+ }
134
+
135
+ /** The tab bar, in the layout, outside the cache. */
136
+ function StackBar() {
137
+ return <>
138
+ <StackButton stack="/home" title="Home"><HomeIcon /></StackButton>
139
+ <StackButton stack="/discover" title="Discover"><SearchIcon /></StackButton>
140
+ <StackButton stack="/profile" title="Profile"><ProfileIcon /></StackButton>
141
+ </>;
142
+ }
143
+
144
+ /** An error outside every layout: the app picks one here. */
145
+ function AppError({ reason }: ErrorProps) {
146
+ return (
147
+ <FixedLayout>
148
+ <Scroll vertical cover>
149
+ <ErrorPage reason={reason} />
150
+ </Scroll>
151
+ </FixedLayout>
152
+ );
153
+ }
154
+ ```
155
+
156
+ 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">`.
157
+
60
158
  For a documentation site, hand an extracted tree to `<TreeApp>` instead — see the `shelving/extract` guide.
61
159
 
62
160
 
@@ -0,0 +1,85 @@
1
+ # AppLayout
2
+
3
+ - Kind: component
4
+ - Import: `import { AppLayout } from "shelving/ui";`
5
+
6
+ Layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app.
7
+ - 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.
8
+ - The bar sits below the content slot, not over it, and it stays still while a page slides.
9
+ - 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.
10
+
11
+ 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.
12
+
13
+ **Things to know:**
14
+
15
+ - 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.
16
+ - The bar sits below the content slot, not over it. So pages need no extra space at the bottom for the bar.
17
+ - The bar shows at every screen size.
18
+ - 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).
19
+ - Each item in the bar takes an equal share of its width, up to `--app-layout-nav-item-width` each.
20
+ - The bar is outside the page cache, so it has one copy. It keeps its state, and the CSS transitions of its items (an active tab) still play while a page slides.
21
+ - The bar has its own view-transition group, so it stays still while the page slides under it.
22
+ - 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 />}`.
23
+ - Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
24
+
25
+ ## Usage
26
+
27
+ ```tsx
28
+ import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll, StackButton } from "shelving/ui";
29
+
30
+ function StackBar() {
31
+ return <>
32
+ <StackButton stack="/home" title="Home"><HomeIcon /></StackButton>
33
+ <StackButton stack="/discover" title="Discover"><SearchIcon /></StackButton>
34
+ <StackButton stack="/profile" title="Profile"><ProfileIcon /></StackButton>
35
+ </>;
36
+ }
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
+ ## Styling
52
+
53
+ | Variable | Styles | Default |
54
+ |---|---|---|
55
+ | `--app-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
56
+ | `--app-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
57
+ | `--app-layout-nav-background` | Bar fill (also fills the home-bar area below it) | `var(--tint-100)` (white) |
58
+ | `--app-layout-nav-color` | Bar text and icon colour | `var(--tint-00)` (black) |
59
+ | `--app-layout-nav-border` | Line above the bar | `var(--stroke-normal) solid var(--tint-90)` |
60
+ | `--app-layout-nav-shadow` | Shadow of the bar, for example a soft shadow above it | `none` |
61
+ | `--app-layout-nav-item-width` | Largest width of one bar item | `6rem` |
62
+
63
+ The bar keeps its items clear of the home bar and the rounded screen corners with safe-area insets.
64
+
65
+ **Global tokens it reads** — `--tint-00`, `--tint-90`, `--tint-100`, and `--stroke-normal`.
66
+
67
+
68
+ ## Signatures
69
+
70
+ ```ts
71
+ AppLayout({ nav, children }: AppLayoutProps): ReactElement
72
+ ```
73
+
74
+ ## Parameters
75
+
76
+ | Param | Type | Description |
77
+ | --- | --- | --- |
78
+ | `props` | `AppLayoutProps` | |
79
+ | `.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. |
80
+
81
+ ## Returns
82
+
83
+ | Type | Description |
84
+ | --- | --- |
85
+ | `ReactElement` | |
@@ -0,0 +1,21 @@
1
+ # AppLayoutProps
2
+
3
+ - Kind: interface
4
+ - Import: `import { AppLayoutProps } from "shelving/ui";`
5
+ - Extends: `OptionalChildProps`
6
+
7
+ Props for `<AppLayout>`: the `nav` bar content and the content slot `children`.
8
+
9
+ ## Signatures
10
+
11
+ ```ts
12
+ {
13
+ nav?: ReactNode;
14
+ }
15
+ ```
16
+
17
+ ## Properties
18
+
19
+ | Property | Type | Description |
20
+ | --- | --- | --- |
21
+ | `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. |
@@ -13,7 +13,7 @@ A React error boundary that catches errors thrown anywhere in its subtree and re
13
13
 
14
14
  **Things to know:**
15
15
 
16
- - `PageCatcher` is a convenience wrapper that renders `ErrorPage` instead — a full-page error display inside a `<CenteredLayout>`.
16
+ - `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>`).
17
17
  - `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.
18
18
  - `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"`.
19
19
 
@@ -3,7 +3,8 @@
3
3
  - Kind: component
4
4
  - Import: `import { ErrorPage } from "shelving/ui";`
5
5
 
6
- Render a caught error as a full-page `<Page>` with a centered `<ErrorNotice>`.
6
+ Render a caught error as a `<Page>` with an `<ErrorNotice>` in a narrow column, centred in the middle of the screen.
7
+ - 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>`.
7
8
 
8
9
  ## Signatures
9
10
 
@@ -0,0 +1,91 @@
1
+ # FixedLayout
2
+
3
+ - Kind: component
4
+ - Import: `import { FixedLayout } from "shelving/ui";`
5
+
6
+ Layout with no chrome: the whole screen is one content slot.
7
+ - It locks the document and gives a full-height slot inside the safe areas. It does not scroll or centre.
8
+ - Fill the slot with `<Scroll vertical cover>`. Used for e.g. log-in and error screens, and full-screen pages.
9
+
10
+ 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.
11
+
12
+ **Things to know:**
13
+
14
+ - It is a frame only. It does not scroll or centre. Fill the slot with `<Scroll vertical cover>`, so the content scrolls inside it.
15
+ - 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.
16
+ - The slot stays clear of the notch, the home bar and the rounded screen corners (safe-area insets).
17
+ - For pages that you move back and forth between, put a `<RouteCache>` around the scroll box, as in `<AppLayout>`.
18
+ - Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
19
+
20
+ ## Usage
21
+
22
+ ```tsx
23
+ import { Block, FixedLayout, Router, Scroll } from "shelving/ui";
24
+
25
+ // The signed-out screens: one layout around their own router.
26
+ <FixedLayout>
27
+ <Scroll vertical cover>
28
+ <Router routes={{
29
+ "/login": LoginPage,
30
+ "/register": RegisterPage,
31
+ }} />
32
+ </Scroll>
33
+ </FixedLayout>
34
+
35
+ // Each page centres its own content.
36
+ function LoginPage() {
37
+ return (
38
+ <Page title="Log in">
39
+ <Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
40
+ <LoginForm />
41
+ </Block>
42
+ </Page>
43
+ );
44
+ }
45
+ ```
46
+
47
+ An app-level error, outside every other layout:
48
+
49
+ ```tsx
50
+ import { Catcher, ErrorPage, type ErrorProps, FixedLayout, Scroll } from "shelving/ui";
51
+
52
+ function AppError({ reason }: ErrorProps) {
53
+ return (
54
+ <FixedLayout>
55
+ <Scroll vertical cover>
56
+ <ErrorPage reason={reason} />
57
+ </Scroll>
58
+ </FixedLayout>
59
+ );
60
+ }
61
+
62
+ <Catcher as={AppError}>…</Catcher>
63
+ ```
64
+
65
+ ## Styling
66
+
67
+ | Variable | Styles | Default |
68
+ |---|---|---|
69
+ | `--fixed-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
70
+ | `--fixed-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
71
+
72
+ **Global tokens it reads** — `--tint-00` and `--tint-100`.
73
+
74
+
75
+ ## Signatures
76
+
77
+ ```ts
78
+ FixedLayout({ children }: FixedLayoutProps): ReactElement
79
+ ```
80
+
81
+ ## Parameters
82
+
83
+ | Param | Type | Description |
84
+ | --- | --- | --- |
85
+ | `props` | `FixedLayoutProps` | |
86
+
87
+ ## Returns
88
+
89
+ | Type | Description |
90
+ | --- | --- |
91
+ | `ReactElement` | |
@@ -0,0 +1,13 @@
1
+ # FixedLayoutProps
2
+
3
+ - Kind: interface
4
+ - Import: `import { FixedLayoutProps } from "shelving/ui";`
5
+ - Extends: `OptionalChildProps`
6
+
7
+ Props for `<FixedLayout>`: the content slot `children`.
8
+
9
+ ## Signatures
10
+
11
+ ```ts
12
+ {}
13
+ ```
@@ -9,7 +9,7 @@ Variant props for the gap between a component's children, e.g. `gap="large"`.
9
9
 
10
10
  ```ts
11
11
  {
12
- gap?: SpaceValue | undefined;
12
+ gap?: Exclude<SpaceValue, "auto"> | undefined;
13
13
  }
14
14
  ```
15
15
 
@@ -17,4 +17,4 @@ Variant props for the gap between a component's children, e.g. `gap="large"`.
17
17
 
18
18
  | Property | Type | Description |
19
19
  | --- | --- | --- |
20
- | `gap` | `SpaceValue \| undefined` | Gap between child elements. Optional. |
20
+ | `gap` | `Exclude<SpaceValue, "auto"> \| undefined` | Gap between child elements. Optional. |
@@ -0,0 +1,30 @@
1
+ # HeightVariant
2
+
3
+ - Kind: type
4
+ - Import: `import { HeightVariant } from "shelving/ui";`
5
+
6
+ Enumerated height selectable via the `height` variant prop.
7
+ - `full` — at least the full height of the container.
8
+ - `1x`–`32x` — at least a multiple of `--space-normal` (1x–8x at 1x intervals, then 10x/12x, then 16x–32x at 4x intervals).
9
+ - Each value is a minimum (`min-block-size`), so the element grows when its content is taller and nothing is cut off.
10
+
11
+ ## Signatures
12
+
13
+ ```ts
14
+ | "full"
15
+ | "1x"
16
+ | "2x"
17
+ | "3x"
18
+ | "4x"
19
+ | "5x"
20
+ | "6x"
21
+ | "7x"
22
+ | "8x"
23
+ | "10x"
24
+ | "12x"
25
+ | "16x"
26
+ | "20x"
27
+ | "24x"
28
+ | "28x"
29
+ | "32x"
30
+ ```
@@ -0,0 +1,26 @@
1
+ # HeightVariants
2
+
3
+ - Kind: interface
4
+ - Import: `import { HeightVariants } from "shelving/ui";`
5
+
6
+ Variant props that set a component's height, and where its content sits inside that height, e.g. `height="full" middle`.
7
+
8
+ ## Signatures
9
+
10
+ ```ts
11
+ {
12
+ height?: HeightVariant | undefined;
13
+ top?: boolean | undefined;
14
+ middle?: boolean | undefined;
15
+ bottom?: boolean | undefined;
16
+ }
17
+ ```
18
+
19
+ ## Properties
20
+
21
+ | Property | Type | Description |
22
+ | --- | --- | --- |
23
+ | `height` | `HeightVariant \| undefined` | Height of the element. It is a minimum, so the element grows when its content is taller. Optional. |
24
+ | `top` | `boolean \| undefined` | Put the content at the top of the element (the default). Optional. |
25
+ | `middle` | `boolean \| undefined` | Put the content in the vertical middle of the element. Use with `height`. Optional. |
26
+ | `bottom` | `boolean \| undefined` | Put the content at the bottom of the element. Use with `height`. Optional. |
@@ -56,26 +56,35 @@ import { App, Navigation, Router } from "shelving/ui";
56
56
  List the root path of each stack in tab order. Put a `<StackButton>` for each stack in the tab bar.
57
57
 
58
58
  ```tsx
59
- import { App, HorizontalTransition, Navigation, RouteCache, Router, StackButton } from "shelving/ui";
59
+ import { App, AppLayout, HorizontalTransition, Navigation, PageLoader, RouteCache, Router, Scroll, StackButton } from "shelving/ui";
60
60
 
61
61
  const STACKS = ["/home", "/discover", "/profile"] as const;
62
62
 
63
+ const TABS = <>
64
+ <StackButton stack="/home">Home</StackButton>
65
+ <StackButton stack="/discover">Discover</StackButton>
66
+ <StackButton stack="/profile">Profile</StackButton>
67
+ </>;
68
+
63
69
  <App root="https://example.com/">
64
70
  <Navigation stacks={STACKS}>
65
- <HorizontalTransition>
66
- <RouteCache>
67
- <Router routes={ROUTES}/>
68
- </RouteCache>
69
- </HorizontalTransition>
70
- <nav className="tab-bar">
71
- <StackButton stack="/home">Home</StackButton>
72
- <StackButton stack="/discover">Discover</StackButton>
73
- <StackButton stack="/profile">Profile</StackButton>
74
- </nav>
71
+ <AppLayout nav={TABS}>
72
+ <HorizontalTransition>
73
+ <RouteCache>
74
+ <Scroll vertical cover>
75
+ <PageLoader>
76
+ <Router routes={ROUTES}/>
77
+ </PageLoader>
78
+ </Scroll>
79
+ </RouteCache>
80
+ </HorizontalTransition>
81
+ </AppLayout>
75
82
  </Navigation>
76
83
  </App>
77
84
  ```
78
85
 
86
+ 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.
87
+
79
88
  To select a tab when the app starts, pass the starting `stack`. The app decides which stack the opening URL belongs to, for example:
80
89
 
81
90
  ```tsx
@@ -9,7 +9,7 @@ Variant props for the block-padding (top + bottom) of a component, e.g. `padding
9
9
 
10
10
  ```ts
11
11
  {
12
- padding?: SpaceValue | undefined;
12
+ padding?: Exclude<SpaceValue, "auto"> | undefined;
13
13
  }
14
14
  ```
15
15
 
@@ -17,4 +17,4 @@ Variant props for the block-padding (top + bottom) of a component, e.g. `padding
17
17
 
18
18
  | Property | Type | Description |
19
19
  | --- | --- | --- |
20
- | `padding` | `SpaceValue \| undefined` | Block-padding (top + bottom) of the element. Optional. |
20
+ | `padding` | `Exclude<SpaceValue, "auto"> \| undefined` | Block-padding (top + bottom) of the element. Optional. |
package/docs/ui/Page.md CHANGED
@@ -29,16 +29,20 @@ function UserPage({ id }: { id: string }) {
29
29
  }
30
30
  ```
31
31
 
32
- Layouts go inside `<Page>`:
32
+ 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>`.
33
33
 
34
34
  ```tsx
35
- import { Page, CenteredLayout } from "shelving/ui";
36
-
37
- <Page title="Sign in">
38
- <CenteredLayout>
39
- <LoginForm/>
40
- </CenteredLayout>
41
- </Page>
35
+ import { Block, FixedLayout, Page, Scroll } from "shelving/ui";
36
+
37
+ <FixedLayout>
38
+ <Scroll vertical cover>
39
+ <Page title="Sign in">
40
+ <Block height="full" middle width="narrow">
41
+ <LoginForm/>
42
+ </Block>
43
+ </Page>
44
+ </Scroll>
45
+ </FixedLayout>
42
46
  ```
43
47
 
44
48
 
@@ -7,11 +7,12 @@ Load a page.
7
7
 
8
8
  - Wrapped in `<PageCatcher>` so child components can throw errors.
9
9
  - Wrapped in `<Suspense>` so child components can throw promises.
10
+ - It renders no layout, so its loading state and error page show inside whatever layout is around it.
10
11
 
11
12
  ## Signatures
12
13
 
13
14
  ```ts
14
- PageLoader({ children, fallback = <CenteredLayout>{LOADING}</CenteredLayout> }: LoaderProps): ReactElement
15
+ PageLoader({ children, fallback = PAGE_LOADING }: LoaderProps): ReactElement
15
16
  ```
16
17
 
17
18
  ## Parameters
@@ -3,8 +3,9 @@
3
3
  - Kind: component
4
4
  - Import: `import { RouteCache } from "shelving/ui";`
5
5
 
6
- Keep-alive page cache for the pages in the navigation stacks. Drop it into a layout around its scrolling content region.
6
+ 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.
7
7
 
8
+ - Put a page transition around it, and a `<Scroll vertical cover>` inside it, so each kept page scrolls in its own box.
8
9
  - 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.
9
10
  - 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.
10
11
  - 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.
@@ -13,9 +14,9 @@ Keep-alive page cache for the pages in the navigation stacks. Drop it into a lay
13
14
  - `<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.
14
15
  - Without the browser Navigation API (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
15
16
 
16
- A keep-alive cache for the pages in the navigation stacks. Put it in a layout around the scrolling content region. It keeps each page in the stacks mounted but hidden (with React's [`<Activity>`](https://react.dev/reference/react/Activity)), so when you go back to a page, or switch back to a tab, the page is exactly as you left it: scroll position, toggles, searches, form input and focus.
17
+ 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.
17
18
 
18
- `<SidebarLayout>` and `<CenteredLayout>` already wrap their content in a `<RouteCache>`. Use it by hand only in a custom layout.
19
+ Layouts do not include a cache. The app composes it, so it can also choose the transition, or leave the cache out.
19
20
 
20
21
  **Things to know:**
21
22
 
@@ -28,33 +29,37 @@ A keep-alive cache for the pages in the navigation stacks. Put it in a layout ar
28
29
  - 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).
29
30
  - Each kept page is frozen under its own `<Meta>`, so a hidden page never re-renders for another page's URL.
30
31
  - `<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.
31
- - The cache must wrap the scroll container itself to keep each page's scroll. So it goes in the layout around the scrolling column, not inside the router. Chrome outside the cache (a sidebar, a tab bar) is not duplicated or remounted.
32
- - Put a page `<Transition>` around the `<RouteCache>`, not inside it. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
32
+ - **Nesting:** layout, then transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. See the usage below.
33
+ - 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.
34
+ - Put a page `<Transition>` **around** the `<RouteCache>`, not inside it. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
35
+ - 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.
33
36
  - Without the browser Navigation API, or with `maxCached={0}`, there is no cache: the current page renders directly and unmounts when you leave it.
34
37
 
35
38
  ## Usage
36
39
 
37
40
  ```tsx
38
- import { HorizontalTransition, RouteCache, Router } from "shelving/ui";
41
+ import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
39
42
 
40
- function MyLayout() {
41
- return (
42
- <HorizontalTransition>
43
- <RouteCache>
44
- <main className="scroll">
43
+ <AppLayout nav={<StackBar />}>
44
+ <HorizontalTransition>
45
+ <RouteCache>
46
+ <Scroll vertical cover>
47
+ <PageLoader>
45
48
  <Router routes={ROUTES}/>
46
- </main>
47
- </RouteCache>
48
- </HorizontalTransition>
49
- );
50
- }
49
+ </PageLoader>
50
+ </Scroll>
51
+ </RouteCache>
52
+ </HorizontalTransition>
53
+ </AppLayout>
51
54
  ```
52
55
 
53
56
  Keep fewer pages:
54
57
 
55
58
  ```tsx
56
59
  <RouteCache maxCached={5}>
57
- <Router routes={ROUTES}/>
60
+ <Scroll vertical cover>
61
+ <Router routes={ROUTES}/>
62
+ </Scroll>
58
63
  </RouteCache>
59
64
  ```
60
65