shelving 1.320.0 → 1.322.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (171) hide show
  1. package/docs/guides/building-with-shelving.md +230 -1
  2. package/docs/llms-full.txt +1395 -351
  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/BackButton.md +75 -0
  7. package/docs/ui/BackButtonProps.md +21 -0
  8. package/docs/ui/Catcher.md +1 -1
  9. package/docs/ui/ClickableProps.md +0 -2
  10. package/docs/ui/ErrorPage.md +2 -1
  11. package/docs/ui/FixedLayout.md +91 -0
  12. package/docs/ui/FixedLayoutProps.md +13 -0
  13. package/docs/ui/GapVariants.md +2 -2
  14. package/docs/ui/Head.md +2 -2
  15. package/docs/ui/HeightVariant.md +30 -0
  16. package/docs/ui/HeightVariants.md +26 -0
  17. package/docs/ui/HorizontalTransition.md +1 -1
  18. package/docs/ui/LinkClickable.md +0 -1
  19. package/docs/ui/Meta.md +3 -1
  20. package/docs/ui/Navigation.md +102 -37
  21. package/docs/ui/NavigationEntryState.md +22 -0
  22. package/docs/ui/NavigationPosition.md +24 -0
  23. package/docs/ui/NavigationPositionContext.md +8 -0
  24. package/docs/ui/NavigationProps.md +12 -2
  25. package/docs/ui/NavigationStore/back.md +6 -4
  26. package/docs/ui/NavigationStore/forward.md +6 -2
  27. package/docs/ui/NavigationStore/history.md +15 -0
  28. package/docs/ui/NavigationStore/listen.md +14 -0
  29. package/docs/ui/NavigationStore/replace.md +15 -0
  30. package/docs/ui/NavigationStore.md +100 -19
  31. package/docs/ui/PaddingVariants.md +2 -2
  32. package/docs/ui/Page.md +12 -8
  33. package/docs/ui/PageLoader.md +2 -1
  34. package/docs/ui/RouteCache.md +77 -36
  35. package/docs/ui/RouteCacheProps.md +3 -3
  36. package/docs/ui/Router.md +12 -6
  37. package/docs/ui/Scroll.md +60 -6
  38. package/docs/ui/ScrollVariants.md +5 -1
  39. package/docs/ui/SidebarLayout.md +17 -8
  40. package/docs/ui/SpaceValue.md +1 -0
  41. package/docs/ui/StackButton.md +64 -0
  42. package/docs/ui/StackButtonProps.md +21 -0
  43. package/docs/ui/TreeApp.md +1 -1
  44. package/docs/ui/VerticalTransition.md +1 -1
  45. package/docs/ui/getBlockClass.md +1 -1
  46. package/docs/ui/getGapClass.md +1 -1
  47. package/docs/ui/getHeightClass.md +64 -0
  48. package/docs/ui/getPaddingClass.md +1 -1
  49. package/docs/ui/getScrollClass.md +4 -2
  50. package/docs/ui/getSpaceClass.md +2 -0
  51. package/docs/ui/mergeMeta.md +2 -1
  52. package/docs/ui.md +25 -17
  53. package/package.json +1 -1
  54. package/ui/README.md +1 -1
  55. package/ui/app/App.md +105 -7
  56. package/ui/button/Clickable.d.ts +1 -3
  57. package/ui/button/Clickable.js +2 -2
  58. package/ui/button/Clickable.tsx +0 -4
  59. package/ui/docs/DocumentationApp.js +4 -1
  60. package/ui/docs/DocumentationApp.tsx +10 -1
  61. package/ui/layout/AppLayout.d.ts +21 -0
  62. package/ui/layout/AppLayout.js +18 -0
  63. package/ui/layout/AppLayout.md +57 -0
  64. package/ui/layout/AppLayout.module.css +106 -0
  65. package/ui/layout/AppLayout.tsx +36 -0
  66. package/ui/layout/FixedLayout.d.ts +18 -0
  67. package/ui/layout/FixedLayout.js +15 -0
  68. package/ui/layout/FixedLayout.md +65 -0
  69. package/ui/layout/FixedLayout.module.css +55 -0
  70. package/ui/layout/FixedLayout.tsx +25 -0
  71. package/ui/layout/SidebarLayout.d.ts +2 -2
  72. package/ui/layout/SidebarLayout.js +3 -4
  73. package/ui/layout/SidebarLayout.md +15 -6
  74. package/ui/layout/SidebarLayout.module.css +11 -16
  75. package/ui/layout/SidebarLayout.tsx +10 -13
  76. package/ui/layout/index.d.ts +2 -1
  77. package/ui/layout/index.js +2 -1
  78. package/ui/layout/index.tsx +2 -1
  79. package/ui/misc/Catcher.d.ts +2 -1
  80. package/ui/misc/Catcher.js +4 -3
  81. package/ui/misc/Catcher.md +1 -1
  82. package/ui/misc/Catcher.tsx +5 -4
  83. package/ui/misc/Loader.d.ts +1 -0
  84. package/ui/misc/Loader.js +6 -2
  85. package/ui/misc/Loader.tsx +11 -2
  86. package/ui/page/Head.d.ts +2 -2
  87. package/ui/page/Head.js +9 -8
  88. package/ui/page/Head.tsx +8 -6
  89. package/ui/page/Page.md +12 -8
  90. package/ui/router/BackButton.d.ts +22 -0
  91. package/ui/router/BackButton.js +19 -0
  92. package/ui/router/BackButton.md +47 -0
  93. package/ui/router/BackButton.tsx +34 -0
  94. package/ui/router/Navigation.d.ts +22 -12
  95. package/ui/router/Navigation.js +67 -51
  96. package/ui/router/Navigation.md +93 -27
  97. package/ui/router/Navigation.test.tsx +27 -7
  98. package/ui/router/Navigation.tsx +90 -53
  99. package/ui/router/NavigationContext.d.ts +9 -1
  100. package/ui/router/NavigationContext.js +9 -0
  101. package/ui/router/NavigationContext.tsx +11 -1
  102. package/ui/router/NavigationStore.d.ts +126 -19
  103. package/ui/router/NavigationStore.js +301 -30
  104. package/ui/router/NavigationStore.md +82 -9
  105. package/ui/router/NavigationStore.test.ts +384 -0
  106. package/ui/router/NavigationStore.tsx +347 -30
  107. package/ui/router/RouteCache.d.ts +16 -22
  108. package/ui/router/RouteCache.js +37 -47
  109. package/ui/router/RouteCache.md +63 -16
  110. package/ui/router/RouteCache.tsx +56 -62
  111. package/ui/router/Router.d.ts +2 -1
  112. package/ui/router/Router.js +9 -14
  113. package/ui/router/Router.md +10 -5
  114. package/ui/router/Router.tsx +9 -20
  115. package/ui/router/StackButton.d.ts +24 -0
  116. package/ui/router/StackButton.js +35 -0
  117. package/ui/router/StackButton.md +34 -0
  118. package/ui/router/StackButton.tsx +44 -0
  119. package/ui/router/index.d.ts +2 -2
  120. package/ui/router/index.js +2 -2
  121. package/ui/router/index.ts +2 -2
  122. package/ui/style/Block.d.ts +3 -2
  123. package/ui/style/Block.js +3 -2
  124. package/ui/style/Block.tsx +4 -2
  125. package/ui/style/Gap.d.ts +1 -1
  126. package/ui/style/Gap.tsx +1 -1
  127. package/ui/style/Height.d.ts +32 -0
  128. package/ui/style/Height.js +13 -0
  129. package/ui/style/Height.module.css +88 -0
  130. package/ui/style/Height.tsx +61 -0
  131. package/ui/style/Padding.d.ts +1 -1
  132. package/ui/style/Padding.tsx +1 -1
  133. package/ui/style/Scroll.d.ts +9 -5
  134. package/ui/style/Scroll.js +6 -4
  135. package/ui/style/Scroll.md +59 -0
  136. package/ui/style/Scroll.module.css +13 -1
  137. package/ui/style/Scroll.tsx +13 -5
  138. package/ui/style/Space.d.ts +1 -1
  139. package/ui/style/Space.module.css +12 -0
  140. package/ui/style/Space.tsx +1 -0
  141. package/ui/style/getHeightClass.md +30 -0
  142. package/ui/style/getSpaceClass.md +2 -0
  143. package/ui/style/index.d.ts +1 -0
  144. package/ui/style/index.js +1 -0
  145. package/ui/style/index.ts +1 -0
  146. package/ui/transition/HorizontalTransition.md +1 -1
  147. package/ui/transition/VerticalTransition.md +1 -1
  148. package/ui/tree/TreeApp.d.ts +1 -1
  149. package/ui/tree/TreeApp.js +5 -2
  150. package/ui/tree/TreeApp.tsx +11 -2
  151. package/ui/util/meta.d.ts +4 -1
  152. package/ui/util/meta.ts +4 -1
  153. package/docs/ui/CenteredLayout.md +0 -66
  154. package/docs/ui/CenteredLayoutProps.md +0 -14
  155. package/docs/ui/NavigationStore/redirect.md +0 -12
  156. package/docs/ui/RouteConfig.md +0 -75
  157. package/docs/ui/RouteConfigProps.md +0 -24
  158. package/docs/ui/RouteContext.md +0 -6
  159. package/docs/ui/RouteState.md +0 -30
  160. package/ui/layout/CenteredLayout.d.ts +0 -21
  161. package/ui/layout/CenteredLayout.js +0 -28
  162. package/ui/layout/CenteredLayout.md +0 -41
  163. package/ui/layout/CenteredLayout.module.css +0 -72
  164. package/ui/layout/CenteredLayout.tsx +0 -56
  165. package/ui/router/RouteConfig.d.ts +0 -28
  166. package/ui/router/RouteConfig.js +0 -30
  167. package/ui/router/RouteConfig.md +0 -42
  168. package/ui/router/RouteConfig.tsx +0 -44
  169. package/ui/router/RouteContext.d.ts +0 -22
  170. package/ui/router/RouteContext.js +0 -8
  171. package/ui/router/RouteContext.tsx +0 -26
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. |
@@ -0,0 +1,75 @@
1
+ # BackButton
2
+
3
+ - Kind: component
4
+ - Import: `import { BackButton } from "shelving/ui";`
5
+
6
+ Back button for the current stack.
7
+ - Goes back to the page before this one in the current stack, wherever you came from.
8
+ - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
9
+ - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
10
+
11
+ The back button for a page header. It goes back to the page before this one in the current stack, wherever you came from.
12
+
13
+ **Things to know:**
14
+
15
+ - It goes to the page before this one in the current stack. If you opened a post from a search, it goes back to the search.
16
+ - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. So a back button always has somewhere to go. Set `href` to the page's natural parent. On an unstacked page (for example a deep link), it goes to `href` and stays unstacked. To go into a stack, the user taps a `<StackButton>`.
17
+ - It is a plain link with `className="back"`. `<Navigation>` turns a click into `NavigationStore.back()`, so the page slides back. A middle-click opens the link in a new browser tab.
18
+ - Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
19
+ - It takes the usual `<Button>` props, except `onClick`.
20
+ - Without the browser Navigation API, and in a server render, it links to `href`.
21
+ - In a server-rendered app the server always renders `href`, and the browser may render the page before this one. React then warns about a hydration mismatch on the first render. A client-only app (with `<App>`) has no mismatch.
22
+
23
+ ## Usage
24
+
25
+ ```tsx
26
+ import { BackButton } from "shelving/ui";
27
+
28
+ function PostPage({ id }: { id: string }) {
29
+ return (
30
+ <>
31
+ <header>
32
+ <BackButton href="/home"/>
33
+ <h1>Post</h1>
34
+ </header>
35
+ {/* … */}
36
+ </>
37
+ );
38
+ }
39
+ ```
40
+
41
+ With a label:
42
+
43
+ ```tsx
44
+ <BackButton href="/profile">Back to profile</BackButton>
45
+ ```
46
+
47
+ To go back to one fixed page (not to the page before), use a link with `className="back"`:
48
+
49
+ ```tsx
50
+ <Button href="/profile" className="back">Profile</Button>
51
+ ```
52
+
53
+ ## Styling
54
+
55
+ `<BackButton>` renders a `<Button>`, so it has the same styling hooks. See `<Button>`.
56
+
57
+
58
+ ## Signatures
59
+
60
+ ```ts
61
+ BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement
62
+ ```
63
+
64
+ ## Parameters
65
+
66
+ | Param | Type | Description |
67
+ | --- | --- | --- |
68
+ | `props` | `BackButtonProps` | |
69
+ | `.href` | `AbsolutePath` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Read only. |
70
+
71
+ ## Returns
72
+
73
+ | Type | Description |
74
+ | --- | --- |
75
+ | `ReactElement` | |
@@ -0,0 +1,21 @@
1
+ # BackButtonProps
2
+
3
+ - Kind: interface
4
+ - Import: `import { BackButtonProps } from "shelving/ui";`
5
+ - Extends: `Omit<ButtonProps, "href" | "onClick">`
6
+
7
+ Props for `<BackButton>`: the `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
8
+
9
+ ## Signatures
10
+
11
+ ```ts
12
+ {
13
+ readonly href: AbsolutePath;
14
+ }
15
+ ```
16
+
17
+ ## Properties
18
+
19
+ | Property | Type | Description |
20
+ | --- | --- | --- |
21
+ | `href` | `AbsolutePath` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Read only. |
@@ -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
 
@@ -17,7 +17,6 @@ Props for a thing that can be clicked — either has a string `href` link or an
17
17
  download?: string | undefined;
18
18
  title?: string | undefined;
19
19
  selected?: boolean | undefined;
20
- back?: boolean | undefined;
21
20
  }
22
21
  ```
23
22
 
@@ -32,4 +31,3 @@ Props for a thing that can be clicked — either has a string `href` link or an
32
31
  | `download` | `string \| undefined` | If `href` is present then this is the suggested filename for downloading. Optional. |
33
32
  | `title` | `string \| undefined` | Title shown on hover. Optional. |
34
33
  | `selected` | `boolean \| undefined` | Whether this is the selected item in a group. Sets `aria-pressed` on a `<button>`, or `aria-current` on an `<a>`. Optional. |
35
- | `back` | `boolean \| undefined` | If `href` is present, then `<Navigation>` opens the link with a back transition. Use it for a "back to" link. Sets `data-back` on the `<a>`. Optional. |
@@ -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. |
package/docs/ui/Head.md CHANGED
@@ -3,10 +3,10 @@
3
3
  - Kind: component
4
4
  - Import: `import { Head } from "shelving/ui";`
5
5
 
6
- Emit the current page's head metadata and sync browser history to its URL.
6
+ Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
7
7
  - Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
8
8
  - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
9
- - Updates `window.history` to match the page URL.
9
+ - When the meta `url` differs from the browser URL (a page that knows its canonical URL), calls `NavigationStore.replace()` with it. Outside `<Navigation>` it does not touch history.
10
10
 
11
11
  Low-level emitter of hoistable head metadata from the current `Meta` context. It outputs `<title>`, `<meta>`, `<link>`, stylesheet, module, and script elements inline, and React 19 hoists each one into the document `<head>`. It also syncs `window.history` to the page URL.
12
12
 
@@ -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. |
@@ -10,7 +10,7 @@ A direction-aware `<Transition>` preset that slides its children horizontally
10
10
  **Things to know:**
11
11
 
12
12
  - Slides right by default and when the type is `"forward"`; slides left when the type is `"back"`.
13
- - Inside `<Navigation>` the direction is automatic: a link click, `NavigationStore.forward()` or `NavigationStore.redirect()` sets the `"forward"` type, and the browser back or forward button sets `"back"`. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
13
+ - Inside `<Navigation>` the direction is automatic: a link click or `NavigationStore.forward()` sets the `"forward"` type, and a `className="back"` link or `NavigationStore.back()` sets `"back"`. The browser back and forward buttons set the type from the page's place in its stack. `NavigationStore.replace()` has no transition. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
14
14
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
15
15
  - The old and new content slide a full width apart, so they sit edge to edge and never overlap.
16
16
  - The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
@@ -17,7 +17,6 @@ LinkClickable({
17
17
  download,
18
18
  title,
19
19
  selected,
20
- back,
21
20
  children = "Go",
22
21
  className,
23
22
  }: StylableClickableProps): ReactElement
package/docs/ui/Meta.md CHANGED
@@ -11,6 +11,7 @@ Combined meta data for a website page — title, URLs, description, CSP, tags, l
11
11
  {
12
12
  readonly root?: ImmutableURL | undefined;
13
13
  readonly url?: ImmutableURL | undefined;
14
+ readonly stack?: AbsolutePath | undefined;
14
15
  readonly app?: string | undefined;
15
16
  readonly title?: string | undefined;
16
17
  readonly description?: string | undefined;
@@ -30,7 +31,8 @@ Combined meta data for a website page — title, URLs, description, CSP, tags, l
30
31
  | Property | Type | Description |
31
32
  | --- | --- | --- |
32
33
  | `root` | `ImmutableURL \| undefined` | Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). Read only. Optional. |
33
- | `url` | `ImmutableURL \| undefined` | URL of the current page (used to update history API and as the initial URL for routing). Read only. Optional. |
34
+ | `url` | `ImmutableURL \| undefined` | URL of the current page (used as the initial URL for routing, and as the page's canonical URL in `<Head>`). Read only. Optional. |
35
+ | `stack` | `AbsolutePath \| undefined` | Root path of the current stack (for example `"/home"`). Set it above `<Navigation>` to choose the stack the app opens in. `<Navigation>` publishes the live stack, which is `"/"` for an unstacked page. Read only. Optional. |
34
36
  | `app` | `string \| undefined` | Title of the entire application. Read only. Optional. |
35
37
  | `title` | `string \| undefined` | Title of the current page (set as `<title>` in `<Head>` Read only. Optional. |
36
38
  | `description` | `string \| undefined` | Description of the current page. Read only. Optional. |