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
@@ -3,50 +3,91 @@
3
3
  - Kind: component
4
4
  - Import: `import { RouteCache } from "shelving/ui";`
5
5
 
6
- Keep-alive page cache keyed by the current URL — drop it into a layout around its scrolling content region.
7
-
8
- - Reads the live URL from the surrounding `<Meta>` context and keeps up to `maxCached` recently-visited
9
- pages mounted but hidden (via React's `<Activity>`), so navigating back/forward to a page restores its
10
- entire DOM and component state — scroll position, toggles, searches, inputs, focus — untouched.
11
- - Pages are kept in a least-recently-used map keyed by `path`; the oldest is unmounted past the limit.
12
- - A page that owns other paths with `<RouteConfig path>` stays mounted when the URL changes to one of them.
13
- - A page with `<RouteConfig cache={false}>` is dropped as soon as you leave it, so the next visit shows a new page.
14
- - Each snapshot is frozen under its own `<MetaContext>`, so the same single `children` element resolves a
15
- different page per path and a hidden page never re-renders for someone else's URL.
16
- - `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
17
- subscriptions/observers/timers pause and resume cleanly as it is hidden and shown.
18
- - Because it wraps the scroll container itself (rather than sitting below it inside the router), the
19
- scroll position of every cached page is preserved — surrounding chrome (sidebar, drawer state) stays
20
- outside the cache, so it is neither duplicated nor remounted on navigation.
21
- - When `maxCached <= 0` the page is rendered directly with no caching (it unmounts as you leave it).
22
-
23
- A keep-alive page cache. Drop it into a layout around its scrolling content region: it reads the current URL from the surrounding `<Meta>` context and keeps a handful of recently-visited pages mounted but *hidden* (using React's [`<Activity>`](https://react.dev/reference/react/Activity)), so navigating back or forward to a page restores its entire DOM and component state — scroll position of every scroll container, open/closed toggles, in-progress searches, form inputs, focus — instead of remounting it fresh at the top.
24
-
25
- Shelving's `<SidebarLayout>` and `<CenteredLayout>` already wrap their scrollable content column in one for you, so pages rendered inside them keep their state across navigation automatically. Reach for it by hand only when building a custom layout.
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
+
8
+ - Put a page transition around it, and a `<Scroll vertical cover>` inside it, so each kept page scrolls in its own box.
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.
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.
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.
12
+ - The top page of each stack is never dropped. Other pages can be dropped past `maxCached`, and show fresh (from the top) when you come back to them.
13
+ - Each kept page is frozen under its own `<MetaContext>`, so the same `children` element renders a different page for each URL, and a hidden page never re-renders for another page's URL.
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.
15
+ - Without the browser Navigation API (older browsers, server renders), or with `maxCached` of `0`, it renders the current page directly with no cache.
16
+
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.
18
+
19
+ Layouts do not include a cache. The app composes it, so it can also choose the transition, or leave the cache out.
26
20
 
27
21
  **Things to know:**
28
22
 
29
- - Pages are kept in a least-recently-used map keyed by `path`. Once `maxCached` pages are retained the least-recently-visited one is unmounted (and loses its state). A never-seen or evicted page mounts fresh at the top.
30
- - A page can own other paths with `<RouteConfig path>`, for example its tabs (`/dave/{tab}`). A navigation to one of those paths keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide.
31
- - A page with `<RouteConfig cache={false}>` is not kept: it unmounts as you leave it, so the next visit starts again. Use it for a form that makes or edits something, so it never shows old input.
32
- - The cache key is the path only, not the `?query`. So `/new?from=a` and `/new?from=b` are one page.
33
- - Pass `maxCached={0}` (or less) to disable caching entirely — the page renders directly and unmounts as soon as you leave it.
34
- - `<Activity mode="hidden">` preserves a hidden page's *state* while unmounting its *effects*, so subscriptions, observers (e.g. infinite-scroll), and timers pause and resume cleanly as the page is hidden and shown.
35
- - Each snapshot is frozen under its own `<Meta>` context, so the same single `children` element resolves a different page per path and a hidden page never re-renders for someone else's URL.
36
- - For per-page **scroll** to be preserved the cache has to wrap the scroll container itself — which is why it lives in the layout (around the scrollable column) rather than below it inside the router. Surrounding chrome (sidebar, drawer state) stays outside the cache, so it is neither duplicated nor remounted on navigation.
23
+ - Each page is keyed by its stack and its depth in that stack, not by its URL. See `NavigationStore` for how stacks work.
24
+ - A page leaves the cache when it leaves its stack: when you go back from it, or when its stack goes back to the root. So a page you went back from mounts fresh the next time you open it.
25
+ - After a browser back, the browser forward button shows the next page fresh (from the top), because that page left its stack when you went back.
26
+ - The top page of each stack is never dropped, so each tab always shows the page you left. Other pages are dropped (least recently used first) past `maxCached`, and mount fresh when you come back to them.
27
+ - `NavigationStore.replace()` and `className="replace"` links keep the same page mounted. A replace to another URL for the same component (for example from `/post/1` to `/post/2`) keeps its state. To reset the state, wrap the page content in an element with a `key`, for example `<Fragment key={id}>`.
28
+ - The same URL open in two stacks is two separate pages.
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).
30
+ - Each kept page is frozen under its own `<Meta>`, so a hidden page never re-renders for another page's URL.
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.
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.
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.
37
37
 
38
38
  ## Usage
39
39
 
40
40
  ```tsx
41
- import { RouteCache } from "shelving/ui";
41
+ import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
42
+
43
+ <AppLayout nav={<StackBar />}>
44
+ <HorizontalTransition>
45
+ <RouteCache>
46
+ <Scroll vertical cover>
47
+ <PageLoader>
48
+ <Router routes={ROUTES}/>
49
+ </PageLoader>
50
+ </Scroll>
51
+ </RouteCache>
52
+ </HorizontalTransition>
53
+ </AppLayout>
54
+ ```
55
+
56
+ Keep fewer pages:
42
57
 
43
- <SidebarLayout sidebar={<Menu/>}>
44
- <RouteCache>
45
- <Router routes={routes}/>
46
- </RouteCache>
47
- </SidebarLayout>
58
+ ```tsx
59
+ <RouteCache maxCached={5}>
60
+ <Scroll vertical cover>
61
+ <Router routes={ROUTES}/>
62
+ </Scroll>
63
+ </RouteCache>
48
64
  ```
49
65
 
66
+ Clear a create form after it saves. Change the `key` of the `<Form>`, so it mounts again with no input:
67
+
68
+ ```tsx
69
+ import { useState } from "react";
70
+ import { Form, requireNavigation } from "shelving/ui";
71
+
72
+ function NewPostPage() {
73
+ const nav = requireNavigation();
74
+ const [formKey, setFormKey] = useState(0);
75
+ return (
76
+ <Form
77
+ key={formKey}
78
+ schema={POST_SCHEMA}
79
+ onSubmit={async data => {
80
+ const id = await createPost(data);
81
+ setFormKey(k => k + 1);
82
+ nav.forward(`/post/${id}`);
83
+ }}
84
+ />
85
+ );
86
+ }
87
+ ```
88
+
89
+ For a plain HTML `<form>`, call `form.reset()` after the submit.
90
+
50
91
 
51
92
  ## Signatures
52
93
 
@@ -59,8 +100,8 @@ RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode
59
100
  | Param | Type | Description |
60
101
  | --- | --- | --- |
61
102
  | `props` | `RouteCacheProps` | |
62
- | `.maxCached` | `number \| undefined` | Number of recently-visited URLs to keep mounted (but hidden) so the entire state of their subtree — scroll position of every scroll container, open/closed toggles, in-progress searches, form inputs, focus — is restored intact when navigating back or forward to them. - Defaults to `10`. Once the limit is reached the least-recently-visited entry is unmounted. - Set to `0` (or less) to disable caching and unmount the subtree as you leave each URL. Read only. Optional. |
63
- | `.children` | `ReactNode` | The content to render for the current URL and keep alive (hidden) for recently-visited URLs. Read only. |
103
+ | `.maxCached` | `number \| undefined` | Number of pages to keep mounted (but hidden), so the whole state of each one (scroll position, toggles, searches, form input, focus) is still there when you come back to it. - The top page of each stack is never dropped, even past the limit, so a tab always shows the page you left. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
104
+ | `.children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
64
105
 
65
106
  ## Returns
66
107
 
@@ -3,7 +3,7 @@
3
3
  - Kind: interface
4
4
  - Import: `import { RouteCacheProps } from "shelving/ui";`
5
5
 
6
- Props for `<RouteCache>` — the `maxCached` size and the content `children` to keep alive per URL.
6
+ Props for `<RouteCache>`: the `maxCached` size and the content `children` to keep alive for each page in the stacks.
7
7
 
8
8
  ## Signatures
9
9
 
@@ -18,5 +18,5 @@ Props for `<RouteCache>` — the `maxCached` size and the content `children` to
18
18
 
19
19
  | Property | Type | Description |
20
20
  | --- | --- | --- |
21
- | `maxCached` | `number \| undefined` | Number of recently-visited URLs to keep mounted (but hidden) so the entire state of their subtree — scroll position of every scroll container, open/closed toggles, in-progress searches, form inputs, focus — is restored intact when navigating back or forward to them. - Defaults to `10`. Once the limit is reached the least-recently-visited entry is unmounted. - Set to `0` (or less) to disable caching and unmount the subtree as you leave each URL. Read only. Optional. |
22
- | `children` | `ReactNode` | The content to render for the current URL and keep alive (hidden) for recently-visited URLs. Read only. |
21
+ | `maxCached` | `number \| undefined` | Number of pages to keep mounted (but hidden), so the whole state of each one (scroll position, toggles, searches, form input, focus) is still there when you come back to it. - The top page of each stack is never dropped, even past the limit, so a tab always shows the page you left. - Set to `0` (or less) to turn the cache off and unmount each page as you leave it. Read only. Defaults to `10`. |
22
+ | `children` | `ReactNode` | The content to render for the current page and keep alive (hidden) for the other pages in the stacks. Read only. |
package/docs/ui/Router.md CHANGED
@@ -8,7 +8,8 @@ Match the current URL against `routes` and render the matched element.
8
8
  - When `base` is set, the effective path is the URL after stripping the base prefix.
9
9
  - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
10
10
  - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
11
- - Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<RouteConfig path>` stays mounted when the path changes to one of them.
11
+ - Inside `<Navigation>` with the Navigation API, each page in a stack is a new page: a link mounts a new page, and `NavigationStore.replace()` keeps the same page mounted (it re-renders with the new URL). A replace that renders another component still mounts it fresh.
12
+ - Elsewhere, each path is a new page, so a component route remounts when the path changes.
12
13
  - Returns `null` when there's no URL in context or the URL is outside the base.
13
14
 
14
15
  A pure URL matcher: it reads the current URL from the surrounding `<Meta>` context, matches it against a `routes` table, and renders the matched element. It has no client requirements, so it works for SSR, static rendering, and tests with no `<Navigation>` at all — wrap it in `<Navigation>` on the client to get live URL updates.
@@ -19,7 +20,8 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
19
20
  - `<Router>` accepts `PossibleMeta` props (`url`, `base`, etc.) to override the surrounding context — this is how nested routers scope themselves.
20
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`.
21
22
  - Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
22
- - `<Router>` itself does not cache pages — wrap it in a `<RouteCache>` (or use a layout that already does) to keep recently-visited pages mounted but hidden so back/forward navigation restores their state.
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>` (with a `<Scroll vertical cover>` between them) to keep recently-visited pages mounted but hidden so back/forward navigation restores their state.
23
25
 
24
26
  ## Usage
25
27
 
@@ -65,7 +67,7 @@ Modifier chars are tolerant: one-or-more stars and three-or-more dots are all eq
65
67
 
66
68
  ### Layout wrapping
67
69
 
68
- 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>`.
69
71
 
70
72
  ```tsx
71
73
  const SIDEBARRED_ROUTES = {
@@ -78,7 +80,9 @@ const SIDEBARRED_ROUTES = {
78
80
  "/": <HomePage/>,
79
81
  "/{...path}": (
80
82
  <SidebarLayout sidebar={<Nav/>}>
81
- <Router routes={SIDEBARRED_ROUTES}/>
83
+ <Scroll vertical cover>
84
+ <Router routes={SIDEBARRED_ROUTES}/>
85
+ </Scroll>
82
86
  </SidebarLayout>
83
87
  ),
84
88
  }}/>
@@ -125,7 +129,9 @@ const SIDEBARRED_ROUTES = {
125
129
  "/login": <LoginPage/>, // no sidebar
126
130
  "/{...path}": ( // everything else wrapped
127
131
  <SidebarLayout sidebar={<Nav/>}>
128
- <Router routes={SIDEBARRED_ROUTES}/>
132
+ <Scroll vertical cover>
133
+ <Router routes={SIDEBARRED_ROUTES}/>
134
+ </Scroll>
129
135
  </SidebarLayout>
130
136
  ),
131
137
  }}/>
@@ -133,7 +139,7 @@ const SIDEBARRED_ROUTES = {
133
139
 
134
140
  ### Keeping page state
135
141
 
136
- 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 (or its scrolling content region) in a `<RouteCache>` to keep recently-visited pages mounted but hidden so their state is restored on back/forward navigation. Shelving's `<SidebarLayout>` and `<CenteredLayout>` already do this for you.
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.
137
143
 
138
144
  ### SSR / static rendering
139
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 selecting which scroll axes are enabled on an element.
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. |
@@ -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 scrollable main content column.
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
- - The scrollable content column is kept alive across navigation via `<RouteCache>`, so returning to a recently-visited page restores its scroll position and state; the sidebar stays mounted throughout.
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 scrollable main content column. 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.
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 layout owns scroll, padding, and safe-area insets so individual pages don't have to.
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 { SidebarLayout, Menu, MenuItem, Router } from "shelving/ui";
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
- <Router routes={ROUTES}/>
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
- Layouts compose naturally as `<Router>` route values — wrap a group of routes in a shared layout, then route further inside it.
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 and content columns own their own scroll behaviour directly (this layout no longer composes a shared `.layout` class).
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
 
@@ -11,6 +11,7 @@ Allowed values for block spacing for components that support `SpaceVariants`
11
11
  | "section"
12
12
  | "paragraph"
13
13
  | "none"
14
+ | "auto"
14
15
  | "xxsmall"
15
16
  | "xsmall"
16
17
  | "small"
@@ -0,0 +1,64 @@
1
+ # StackButton
2
+
3
+ - Kind: component
4
+ - Import: `import { StackButton } from "shelving/ui";`
5
+
6
+ Button for one stack in a tab bar.
7
+ - Tap another stack's button: go to the page you left in that stack. The page slides left or right by tab order.
8
+ - Tap the current stack's button: go back to its root.
9
+ - Tap it again at the root: scroll the page to the top.
10
+ - It is selected while its stack is the current stack.
11
+ - Without the browser Navigation API (and in a server render) it is a plain link to the stack's root.
12
+
13
+ A button for one stack in a tab bar. It acts like a tab button in a phone app.
14
+
15
+ **Things to know:**
16
+
17
+ - Tap another stack's button: go to the page you left in that stack. The page slides left or right, by tab order.
18
+ - Tap the current stack's button: go back to the root of the stack. The page slides back.
19
+ - Tap it again at the root: scroll the page to the top. It scrolls the window, and each visible `<main>` or `[data-scroll]` element.
20
+ - It is selected (`aria-current`) while its stack is the current stack. On an unstacked page (for example a deep link or a login page), no stack button is selected.
21
+ - `stack` must be one of the `stacks` on `<Navigation>`.
22
+ - It takes the usual `<Button>` props, except `href`, `onClick` and `selected`.
23
+ - Without the browser Navigation API, and in a server render, it is a plain link to the stack's root. It is selected while its stack is the starting stack.
24
+ - In a server-rendered app, the server renders a link and the browser renders a button, so React warns about a hydration mismatch on the first render. A client-only app (with `<App>`) has no mismatch.
25
+
26
+ ## Usage
27
+
28
+ ```tsx
29
+ import { Navigation, StackButton } from "shelving/ui";
30
+ import { HomeIcon, SearchIcon, UserIcon } from "./icons.js";
31
+
32
+ <Navigation stacks={["/home", "/discover", "/profile"]}>
33
+ {/* … */}
34
+ <nav className="tab-bar">
35
+ <StackButton stack="/home" title="Home"><HomeIcon/></StackButton>
36
+ <StackButton stack="/discover" title="Discover"><SearchIcon/></StackButton>
37
+ <StackButton stack="/profile" title="Profile"><UserIcon/></StackButton>
38
+ </nav>
39
+ </Navigation>
40
+ ```
41
+
42
+ ## Styling
43
+
44
+ `<StackButton>` renders a `<Button>`, so it has the same styling hooks. See `<Button>`.
45
+
46
+
47
+ ## Signatures
48
+
49
+ ```ts
50
+ StackButton({ stack, ...props }: StackButtonProps): ReactElement
51
+ ```
52
+
53
+ ## Parameters
54
+
55
+ | Param | Type | Description |
56
+ | --- | --- | --- |
57
+ | `props` | `StackButtonProps` | |
58
+ | `.stack` | `AbsolutePath` | Root path of the stack this button opens. It must be one of the `stacks` on `<Navigation>`. Read only. |
59
+
60
+ ## Returns
61
+
62
+ | Type | Description |
63
+ | --- | --- |
64
+ | `ReactElement` | |
@@ -0,0 +1,21 @@
1
+ # StackButtonProps
2
+
3
+ - Kind: interface
4
+ - Import: `import { StackButtonProps } from "shelving/ui";`
5
+ - Extends: `Omit<ButtonProps, "href" | "onClick" | "selected">`
6
+
7
+ Props for `<StackButton>`: the `stack` it opens, plus the usual `Button` props except `href` and `onClick`.
8
+
9
+ ## Signatures
10
+
11
+ ```ts
12
+ {
13
+ readonly stack: AbsolutePath;
14
+ }
15
+ ```
16
+
17
+ ## Properties
18
+
19
+ | Property | Type | Description |
20
+ | --- | --- | --- |
21
+ | `stack` | `AbsolutePath` | Root path of the stack this button opens. It must be one of the `stacks` on `<Navigation>`. Read only. |
@@ -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>`.
@@ -10,7 +10,7 @@ A direction-aware `<Transition>` preset that slides its children vertically —
10
10
  **Things to know:**
11
11
 
12
12
  - Slides down by default and when the type is `"forward"`; slides up 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 height 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.
@@ -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 width variant helpers, so anything that wants block-level styling can apply it.
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
 
@@ -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