shelving 1.321.0 → 1.322.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/docs/guides/building-with-shelving.md +204 -1
  2. package/docs/llms-full.txt +793 -115
  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/Dialog.md +3 -1
  8. package/docs/ui/Dialogs.md +4 -0
  9. package/docs/ui/ErrorPage.md +2 -1
  10. package/docs/ui/FixedLayout.md +91 -0
  11. package/docs/ui/FixedLayoutProps.md +13 -0
  12. package/docs/ui/GapVariants.md +2 -2
  13. package/docs/ui/HeightVariant.md +30 -0
  14. package/docs/ui/HeightVariants.md +26 -0
  15. package/docs/ui/Navigation.md +20 -11
  16. package/docs/ui/PaddingVariants.md +2 -2
  17. package/docs/ui/Page.md +12 -8
  18. package/docs/ui/PageLoader.md +2 -1
  19. package/docs/ui/RouteCache.md +22 -17
  20. package/docs/ui/Router.md +9 -5
  21. package/docs/ui/Scroll.md +60 -6
  22. package/docs/ui/ScrollVariants.md +5 -1
  23. package/docs/ui/SidebarLayout.md +17 -8
  24. package/docs/ui/SpaceValue.md +1 -0
  25. package/docs/ui/TreeApp.md +1 -1
  26. package/docs/ui/getBlockClass.md +1 -1
  27. package/docs/ui/getGapClass.md +1 -1
  28. package/docs/ui/getHeightClass.md +64 -0
  29. package/docs/ui/getPaddingClass.md +1 -1
  30. package/docs/ui/getScrollClass.md +4 -2
  31. package/docs/ui/getSpaceClass.md +2 -0
  32. package/docs/ui.md +13 -8
  33. package/package.json +1 -1
  34. package/ui/README.md +1 -1
  35. package/ui/app/App.md +105 -7
  36. package/ui/dialog/Dialog.md +3 -1
  37. package/ui/dialog/Dialogs.d.ts +4 -0
  38. package/ui/dialog/Dialogs.js +4 -0
  39. package/ui/dialog/Dialogs.tsx +4 -0
  40. package/ui/docs/DocumentationApp.js +4 -1
  41. package/ui/docs/DocumentationApp.tsx +10 -1
  42. package/ui/layout/AppLayout.d.ts +21 -0
  43. package/ui/layout/AppLayout.js +18 -0
  44. package/ui/layout/AppLayout.md +57 -0
  45. package/ui/layout/AppLayout.module.css +92 -0
  46. package/ui/layout/AppLayout.tsx +36 -0
  47. package/ui/layout/FixedLayout.d.ts +18 -0
  48. package/ui/layout/FixedLayout.js +15 -0
  49. package/ui/layout/FixedLayout.md +65 -0
  50. package/ui/layout/FixedLayout.module.css +55 -0
  51. package/ui/layout/FixedLayout.tsx +25 -0
  52. package/ui/layout/SidebarLayout.d.ts +2 -2
  53. package/ui/layout/SidebarLayout.js +3 -4
  54. package/ui/layout/SidebarLayout.md +15 -6
  55. package/ui/layout/SidebarLayout.module.css +11 -16
  56. package/ui/layout/SidebarLayout.tsx +10 -13
  57. package/ui/layout/index.d.ts +2 -1
  58. package/ui/layout/index.js +2 -1
  59. package/ui/layout/index.tsx +2 -1
  60. package/ui/misc/Catcher.d.ts +2 -1
  61. package/ui/misc/Catcher.js +4 -3
  62. package/ui/misc/Catcher.md +1 -1
  63. package/ui/misc/Catcher.tsx +5 -4
  64. package/ui/misc/Loader.d.ts +1 -0
  65. package/ui/misc/Loader.js +6 -2
  66. package/ui/misc/Loader.tsx +11 -2
  67. package/ui/page/Page.md +12 -8
  68. package/ui/router/Navigation.md +20 -11
  69. package/ui/router/RouteCache.d.ts +2 -1
  70. package/ui/router/RouteCache.js +2 -1
  71. package/ui/router/RouteCache.md +20 -16
  72. package/ui/router/RouteCache.tsx +2 -1
  73. package/ui/router/Router.md +9 -5
  74. package/ui/style/Block.d.ts +3 -2
  75. package/ui/style/Block.js +3 -2
  76. package/ui/style/Block.tsx +4 -2
  77. package/ui/style/Gap.d.ts +1 -1
  78. package/ui/style/Gap.tsx +1 -1
  79. package/ui/style/Height.d.ts +32 -0
  80. package/ui/style/Height.js +13 -0
  81. package/ui/style/Height.module.css +88 -0
  82. package/ui/style/Height.tsx +61 -0
  83. package/ui/style/Padding.d.ts +1 -1
  84. package/ui/style/Padding.tsx +1 -1
  85. package/ui/style/Scroll.d.ts +9 -5
  86. package/ui/style/Scroll.js +6 -4
  87. package/ui/style/Scroll.md +59 -0
  88. package/ui/style/Scroll.module.css +13 -1
  89. package/ui/style/Scroll.tsx +13 -5
  90. package/ui/style/Space.d.ts +1 -1
  91. package/ui/style/Space.module.css +12 -0
  92. package/ui/style/Space.tsx +1 -0
  93. package/ui/style/getHeightClass.md +30 -0
  94. package/ui/style/getSpaceClass.md +2 -0
  95. package/ui/style/index.d.ts +1 -0
  96. package/ui/style/index.js +1 -0
  97. package/ui/style/index.ts +1 -0
  98. package/ui/tree/TreeApp.d.ts +1 -1
  99. package/ui/tree/TreeApp.js +5 -2
  100. package/ui/tree/TreeApp.tsx +11 -2
  101. package/docs/ui/CenteredLayout.md +0 -66
  102. package/docs/ui/CenteredLayoutProps.md +0 -14
  103. package/ui/layout/CenteredLayout.d.ts +0 -21
  104. package/ui/layout/CenteredLayout.js +0 -28
  105. package/ui/layout/CenteredLayout.md +0 -41
  106. package/ui/layout/CenteredLayout.module.css +0 -72
  107. package/ui/layout/CenteredLayout.tsx +0 -56
@@ -8,9 +8,9 @@
8
8
  /*
9
9
  * Sidebar layout: a fixed-width column on the left, a scrollable main content column on the right.
10
10
  *
11
- * This layout owns its page styling completely: `.main` is the body-filling grid container, and the
12
- * inner `.content` column owns the scroll/safe-area behaviour. The `html`/`body` rules below lock the
13
- * document so `.main` is the only scroll container.
11
+ * This layout is a frame only: `.main` is the body-filling grid container, and the `.content` slot is a
12
+ * positioned box that the app fills with `<Scroll vertical cover>`. The `html`/`body` rules below lock the
13
+ * document, so only the sidebar and the content slot's scroll box scroll.
14
14
  *
15
15
  * On narrow viewports the sidebar becomes an off-canvas drawer that slides off the left edge of the
16
16
  * screen (the right edge for the `.right` variant); the `.toggle` button opens/closes it and the
@@ -24,7 +24,6 @@
24
24
  /*
25
25
  * Lock the document and let `.main` own the page scroll.
26
26
  * - <html> and <body> are pinned to the viewport (no rubber-band on iOS).
27
- * - <body> stacks its children vertically (flex column).
28
27
  * - The `.main` element grows to fill the body.
29
28
  */
30
29
  html:has(.main) {
@@ -45,8 +44,6 @@
45
44
  /* Box */
46
45
  margin: 0;
47
46
  padding: 0;
48
- display: flex;
49
- flex-direction: column;
50
47
 
51
48
  /* Lock body to prevent iOS Safari triggering viewport scrolling on focus change. */
52
49
  position: fixed;
@@ -61,8 +58,9 @@
61
58
  }
62
59
 
63
60
  .main {
64
- /* Grow to fill the body (it is the body's flex child). */
65
- flex: 1;
61
+ /* Fill the locked body, even inside a mount element such as `<div id="root">`. */
62
+ position: absolute;
63
+ inset: 0;
66
64
  display: grid;
67
65
  grid-template-columns: var(--sidebar-layout-width, 17.5rem) 1fr;
68
66
  gap: 0;
@@ -89,15 +87,12 @@
89
87
  }
90
88
 
91
89
  .content {
92
- /* Owns the page scroll for the content column (previously inherited from the shared `.layout`). */
90
+ /* The content slot: a positioned box that `<Scroll vertical cover>` fills. It does not scroll itself. */
91
+ position: relative;
93
92
  min-width: 0;
93
+ min-height: 0;
94
94
  padding: 0;
95
-
96
- /* Scrolling */
97
- display: flow-root;
98
- overflow: hidden auto;
99
- overscroll-behavior: auto contain;
100
- scroll-behavior: smooth;
95
+ overflow: hidden;
101
96
 
102
97
  /* Style */
103
98
 
@@ -173,7 +168,7 @@
173
168
  transform: translateX(0);
174
169
  }
175
170
 
176
- /* Pin the toggle button to the top-right so it stays reachable while the content column scrolls. */
171
+ /* Pin the toggle button to the top-right of the content slot, above its scroll box. */
177
172
  .toggle {
178
173
  display: block;
179
174
  position: absolute;
@@ -3,7 +3,6 @@ import { CloseIcon } from "shelving/icon/CloseIcon";
3
3
  import { MenuIcon } from "shelving/icon/MenuIcon";
4
4
  import { Button } from "../button/Button.js";
5
5
  import { requireMetaURL } from "../misc/MetaContext.js";
6
- import { RouteCache } from "../router/RouteCache.js";
7
6
  import { getClass, getModuleClass } from "../util/css.js";
8
7
  import type { OptionalChildProps } from "../util/props.js";
9
8
  import LAYOUT_CSS from "./SidebarLayout.module.css";
@@ -29,12 +28,12 @@ export interface SidebarLayoutProps extends OptionalChildProps {
29
28
  }
30
29
 
31
30
  /**
32
- * Layout with a fixed-width side column (typically navigation) next to a scrollable main content column.
31
+ * Layout with a fixed-width side column (typically navigation) next to a content slot.
33
32
  * - The sidebar is rendered as `<nav>` — it almost always contains the page's primary navigation.
34
33
  * - 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.
35
34
  * - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
36
35
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
37
- * - 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.
36
+ * - 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.
38
37
  *
39
38
  * @kind component
40
39
  * @see https://shelving.cc/ui/SidebarLayout
@@ -59,17 +58,15 @@ export function SidebarLayout({ sidebar, children, right = false }: SidebarLayou
59
58
  >
60
59
  {sidebar}
61
60
  </nav>
62
- {/* Wrap the scrolling content column in `<RouteCache>` so recently-visited pages stay mounted but hidden — keeping the scroll position of this `.content` container (and all page state) intact across back/forward navigation. The sidebar and drawer state stay outside the cache, so they are neither duplicated nor remounted as the URL changes. */}
63
- <RouteCache>
64
- <div className={LAYOUT_CONTENT_CLASS}>
65
- <div className={LAYOUT_TOGGLE_CLASS}>
66
- <Button title={open ? "Close menu" : "Show menu"} onClick={() => setOpen(o => !o)}>
67
- {open ? <CloseIcon /> : <MenuIcon />}
68
- </Button>
69
- </div>
70
- {children}
61
+ {/* The content slot is a positioned box: the app fills it with `<Scroll vertical cover>` inside `<RouteCache>`. The menu toggle floats above it. */}
62
+ <div className={LAYOUT_CONTENT_CLASS}>
63
+ <div className={LAYOUT_TOGGLE_CLASS}>
64
+ <Button title={open ? "Close menu" : "Show menu"} onClick={() => setOpen(o => !o)}>
65
+ {open ? <CloseIcon /> : <MenuIcon />}
66
+ </Button>
71
67
  </div>
72
- </RouteCache>
68
+ {children}
69
+ </div>
73
70
  {/* Overlay is always mounted (on narrow viewports) so it can fade both in and out via the `open` class — a conditionally-mounted element can't animate on the way out. */}
74
71
  <button
75
72
  type="button"
@@ -1,2 +1,3 @@
1
- export * from "./CenteredLayout.js";
1
+ export * from "./AppLayout.js";
2
+ export * from "./FixedLayout.js";
2
3
  export * from "./SidebarLayout.js";
@@ -1,2 +1,3 @@
1
- export * from "./CenteredLayout.js";
1
+ export * from "./AppLayout.js";
2
+ export * from "./FixedLayout.js";
2
3
  export * from "./SidebarLayout.js";
@@ -1,2 +1,3 @@
1
- export * from "./CenteredLayout.js";
1
+ export * from "./AppLayout.js";
2
+ export * from "./FixedLayout.js";
2
3
  export * from "./SidebarLayout.js";
@@ -55,7 +55,8 @@ export declare function ErrorNotice({ reason }: ErrorProps): ReactElement;
55
55
  */
56
56
  export declare function PageCatcher({ children }: ChildProps): ReactElement;
57
57
  /**
58
- * Render a caught error as a full-page `<Page>` with a centered `<ErrorNotice>`.
58
+ * Render a caught error as a `<Page>` with an `<ErrorNotice>` in a narrow column, centred in the middle of the screen.
59
+ * - 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>`.
59
60
  *
60
61
  * @kind component
61
62
  * @see https://shelving.cc/ui/ErrorPage
@@ -1,9 +1,9 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { Component } from "react";
3
3
  import { getMessage } from "../../util/error.js";
4
+ import { Block } from "../block/Block.js";
4
5
  import { Paragraph } from "../block/Paragraph.js";
5
6
  import { RetryButton, RetryContext } from "../button/RetryButton.js";
6
- import { CenteredLayout } from "../layout/CenteredLayout.js";
7
7
  import { Notice } from "../notice/Notice.js";
8
8
  import { Page } from "../page/Page.js";
9
9
  /**
@@ -59,11 +59,12 @@ export function PageCatcher({ children }) {
59
59
  return _jsx(Catcher, { as: ErrorPage, children: children });
60
60
  }
61
61
  /**
62
- * Render a caught error as a full-page `<Page>` with a centered `<ErrorNotice>`.
62
+ * Render a caught error as a `<Page>` with an `<ErrorNotice>` in a narrow column, centred in the middle of the screen.
63
+ * - 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>`.
63
64
  *
64
65
  * @kind component
65
66
  * @see https://shelving.cc/ui/ErrorPage
66
67
  */
67
68
  export function ErrorPage({ reason }) {
68
- return (_jsx(Page, { title: "Error", children: _jsx(CenteredLayout, { children: _jsx(ErrorNotice, { reason: reason }) }) }));
69
+ return (_jsx(Page, { title: "Error", children: _jsx(Block, { height: "full", middle: true, width: "narrow", padding: "xxlarge", indent: "normal", children: _jsx(ErrorNotice, { reason: reason }) }) }));
69
70
  }
@@ -4,7 +4,7 @@ A React error boundary that catches errors thrown anywhere in its subtree and re
4
4
 
5
5
  **Things to know:**
6
6
 
7
- - `PageCatcher` is a convenience wrapper that renders `ErrorPage` instead — a full-page error display inside a `<CenteredLayout>`.
7
+ - `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>`).
8
8
  - `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.
9
9
  - `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"`.
10
10
 
@@ -1,9 +1,9 @@
1
1
  import { Component, type ReactElement, type ReactNode } from "react";
2
2
  import { getMessage } from "../../util/error.js";
3
3
  import type { Callback } from "../../util/function.js";
4
+ import { Block } from "../block/Block.js";
4
5
  import { Paragraph } from "../block/Paragraph.js";
5
6
  import { RetryButton, RetryContext } from "../button/RetryButton.js";
6
- import { CenteredLayout } from "../layout/CenteredLayout.js";
7
7
  import { Notice } from "../notice/Notice.js";
8
8
  import { Page } from "../page/Page.js";
9
9
  import type { ChildProps } from "../util/props.js";
@@ -96,7 +96,8 @@ export function PageCatcher({ children }: ChildProps): ReactElement {
96
96
  }
97
97
 
98
98
  /**
99
- * Render a caught error as a full-page `<Page>` with a centered `<ErrorNotice>`.
99
+ * Render a caught error as a `<Page>` with an `<ErrorNotice>` in a narrow column, centred in the middle of the screen.
100
+ * - 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>`.
100
101
  *
101
102
  * @kind component
102
103
  * @see https://shelving.cc/ui/ErrorPage
@@ -104,9 +105,9 @@ export function PageCatcher({ children }: ChildProps): ReactElement {
104
105
  export function ErrorPage({ reason }: ErrorProps): ReactElement {
105
106
  return (
106
107
  <Page title="Error">
107
- <CenteredLayout>
108
+ <Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
108
109
  <ErrorNotice reason={reason} />
109
- </CenteredLayout>
110
+ </Block>
110
111
  </Page>
111
112
  );
112
113
  }
@@ -24,6 +24,7 @@ export declare function Loader({ children, fallback }: LoaderProps): ReactElemen
24
24
  *
25
25
  * - Wrapped in `<PageCatcher>` so child components can throw errors.
26
26
  * - Wrapped in `<Suspense>` so child components can throw promises.
27
+ * - It renders no layout, so its loading state and error page show inside whatever layout is around it.
27
28
  *
28
29
  * @kind component
29
30
  * @see https://shelving.cc/ui/PageLoader
package/ui/misc/Loader.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
2
  import { Suspense } from "react";
3
- import { CenteredLayout } from "../layout/CenteredLayout.js";
3
+ import { Block } from "../block/Block.js";
4
+ import { Row } from "../block/Row.js";
4
5
  import { Catcher, PageCatcher } from "./Catcher.js";
5
6
  import { LOADING } from "./Icon.js";
6
7
  /**
@@ -15,15 +16,18 @@ import { LOADING } from "./Icon.js";
15
16
  export function Loader({ children, fallback = LOADING }) {
16
17
  return (_jsx(Catcher, { children: _jsx(Suspense, { fallback: fallback, children: children }) }));
17
18
  }
19
+ /** Default page loading state: the spinner, in the middle of the screen. It renders no layout. */
20
+ const PAGE_LOADING = (_jsx(Block, { height: "full", middle: true, padding: "xxlarge", children: _jsx(Row, { center: true, children: LOADING }) }));
18
21
  /**
19
22
  * Load a page.
20
23
  *
21
24
  * - Wrapped in `<PageCatcher>` so child components can throw errors.
22
25
  * - Wrapped in `<Suspense>` so child components can throw promises.
26
+ * - It renders no layout, so its loading state and error page show inside whatever layout is around it.
23
27
  *
24
28
  * @kind component
25
29
  * @see https://shelving.cc/ui/PageLoader
26
30
  */
27
- export function PageLoader({ children, fallback = _jsx(CenteredLayout, { children: LOADING }) }) {
31
+ export function PageLoader({ children, fallback = PAGE_LOADING }) {
28
32
  return (_jsx(PageCatcher, { children: _jsx(Suspense, { fallback: fallback, children: children }) }));
29
33
  }
@@ -1,5 +1,6 @@
1
1
  import { type ReactElement, type ReactNode, Suspense } from "react";
2
- import { CenteredLayout } from "../layout/CenteredLayout.js";
2
+ import { Block } from "../block/Block.js";
3
+ import { Row } from "../block/Row.js";
3
4
  import type { ChildProps } from "../util/props.js";
4
5
  import { Catcher, PageCatcher } from "./Catcher.js";
5
6
  import { LOADING } from "./Icon.js";
@@ -31,16 +32,24 @@ export function Loader({ children, fallback = LOADING }: LoaderProps): ReactElem
31
32
  );
32
33
  }
33
34
 
35
+ /** Default page loading state: the spinner, in the middle of the screen. It renders no layout. */
36
+ const PAGE_LOADING = (
37
+ <Block height="full" middle padding="xxlarge">
38
+ <Row center>{LOADING}</Row>
39
+ </Block>
40
+ );
41
+
34
42
  /**
35
43
  * Load a page.
36
44
  *
37
45
  * - Wrapped in `<PageCatcher>` so child components can throw errors.
38
46
  * - Wrapped in `<Suspense>` so child components can throw promises.
47
+ * - It renders no layout, so its loading state and error page show inside whatever layout is around it.
39
48
  *
40
49
  * @kind component
41
50
  * @see https://shelving.cc/ui/PageLoader
42
51
  */
43
- export function PageLoader({ children, fallback = <CenteredLayout>{LOADING}</CenteredLayout> }: LoaderProps): ReactElement {
52
+ export function PageLoader({ children, fallback = PAGE_LOADING }: LoaderProps): ReactElement {
44
53
  return (
45
54
  <PageCatcher>
46
55
  <Suspense fallback={fallback}>{children}</Suspense>
package/ui/page/Page.md CHANGED
@@ -22,14 +22,18 @@ function UserPage({ id }: { id: string }) {
22
22
  }
23
23
  ```
24
24
 
25
- Layouts go inside `<Page>`:
25
+ 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>`.
26
26
 
27
27
  ```tsx
28
- import { Page, CenteredLayout } from "shelving/ui";
29
-
30
- <Page title="Sign in">
31
- <CenteredLayout>
32
- <LoginForm/>
33
- </CenteredLayout>
34
- </Page>
28
+ import { Block, FixedLayout, Page, Scroll } from "shelving/ui";
29
+
30
+ <FixedLayout>
31
+ <Scroll vertical cover>
32
+ <Page title="Sign in">
33
+ <Block height="full" middle width="narrow">
34
+ <LoginForm/>
35
+ </Block>
36
+ </Page>
37
+ </Scroll>
38
+ </FixedLayout>
35
39
  ```
@@ -44,26 +44,35 @@ import { App, Navigation, Router } from "shelving/ui";
44
44
  List the root path of each stack in tab order. Put a `<StackButton>` for each stack in the tab bar.
45
45
 
46
46
  ```tsx
47
- import { App, HorizontalTransition, Navigation, RouteCache, Router, StackButton } from "shelving/ui";
47
+ import { App, AppLayout, HorizontalTransition, Navigation, PageLoader, RouteCache, Router, Scroll, StackButton } from "shelving/ui";
48
48
 
49
49
  const STACKS = ["/home", "/discover", "/profile"] as const;
50
50
 
51
+ const TABS = <>
52
+ <StackButton stack="/home">Home</StackButton>
53
+ <StackButton stack="/discover">Discover</StackButton>
54
+ <StackButton stack="/profile">Profile</StackButton>
55
+ </>;
56
+
51
57
  <App root="https://example.com/">
52
58
  <Navigation stacks={STACKS}>
53
- <HorizontalTransition>
54
- <RouteCache>
55
- <Router routes={ROUTES}/>
56
- </RouteCache>
57
- </HorizontalTransition>
58
- <nav className="tab-bar">
59
- <StackButton stack="/home">Home</StackButton>
60
- <StackButton stack="/discover">Discover</StackButton>
61
- <StackButton stack="/profile">Profile</StackButton>
62
- </nav>
59
+ <AppLayout nav={TABS}>
60
+ <HorizontalTransition>
61
+ <RouteCache>
62
+ <Scroll vertical cover>
63
+ <PageLoader>
64
+ <Router routes={ROUTES}/>
65
+ </PageLoader>
66
+ </Scroll>
67
+ </RouteCache>
68
+ </HorizontalTransition>
69
+ </AppLayout>
63
70
  </Navigation>
64
71
  </App>
65
72
  ```
66
73
 
74
+ 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.
75
+
67
76
  To select a tab when the app starts, pass the starting `stack`. The app decides which stack the opening URL belongs to, for example:
68
77
 
69
78
  ```tsx
@@ -17,8 +17,9 @@ export interface RouteCacheProps {
17
17
  readonly children: ReactNode;
18
18
  }
19
19
  /**
20
- * Keep-alive page cache for the pages in the navigation stacks. Drop it into a layout around its scrolling content region.
20
+ * 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.
21
21
  *
22
+ * - Put a page transition around it, and a `<Scroll vertical cover>` inside it, so each kept page scrolls in its own box.
22
23
  * - 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.
23
24
  * - 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.
24
25
  * - 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.
@@ -3,8 +3,9 @@ import { Activity, use, useRef } from "react";
3
3
  import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
4
4
  import { NavigationPositionContext } from "./NavigationContext.js";
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.
@@ -1,8 +1,8 @@
1
1
  # RouteCache
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
- `<SidebarLayout>` and `<CenteredLayout>` already wrap their content in a `<RouteCache>`. Use it by hand only in a custom layout.
5
+ Layouts do not include a cache. The app composes it, so it can also choose the transition, or leave the cache out.
6
6
 
7
7
  **Things to know:**
8
8
 
@@ -15,33 +15,37 @@ A keep-alive cache for the pages in the navigation stacks. Put it in a layout ar
15
15
  - 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).
16
16
  - Each kept page is frozen under its own `<Meta>`, so a hidden page never re-renders for another page's URL.
17
17
  - `<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.
18
- - 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.
19
- - Put a page `<Transition>` around the `<RouteCache>`, not inside it. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
18
+ - **Nesting:** layout, then transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. See the usage below.
19
+ - 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.
20
+ - Put a page `<Transition>` **around** the `<RouteCache>`, not inside it. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
21
+ - 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.
20
22
  - Without the browser Navigation API, or with `maxCached={0}`, there is no cache: the current page renders directly and unmounts when you leave it.
21
23
 
22
24
  ## Usage
23
25
 
24
26
  ```tsx
25
- import { HorizontalTransition, RouteCache, Router } from "shelving/ui";
27
+ import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
26
28
 
27
- function MyLayout() {
28
- return (
29
- <HorizontalTransition>
30
- <RouteCache>
31
- <main className="scroll">
29
+ <AppLayout nav={<StackBar />}>
30
+ <HorizontalTransition>
31
+ <RouteCache>
32
+ <Scroll vertical cover>
33
+ <PageLoader>
32
34
  <Router routes={ROUTES}/>
33
- </main>
34
- </RouteCache>
35
- </HorizontalTransition>
36
- );
37
- }
35
+ </PageLoader>
36
+ </Scroll>
37
+ </RouteCache>
38
+ </HorizontalTransition>
39
+ </AppLayout>
38
40
  ```
39
41
 
40
42
  Keep fewer pages:
41
43
 
42
44
  ```tsx
43
45
  <RouteCache maxCached={5}>
44
- <Router routes={ROUTES}/>
46
+ <Scroll vertical cover>
47
+ <Router routes={ROUTES}/>
48
+ </Scroll>
45
49
  </RouteCache>
46
50
  ```
47
51
 
@@ -30,8 +30,9 @@ export interface RouteCacheProps {
30
30
  }
31
31
 
32
32
  /**
33
- * Keep-alive page cache for the pages in the navigation stacks. Drop it into a layout around its scrolling content region.
33
+ * 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.
34
34
  *
35
+ * - Put a page transition around it, and a `<Scroll vertical cover>` inside it, so each kept page scrolls in its own box.
35
36
  * - 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.
36
37
  * - 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.
37
38
  * - 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.
@@ -9,7 +9,7 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
9
9
  - 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`.
10
10
  - Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
11
11
  - 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.
12
- - `<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.
12
+ - `<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.
13
13
 
14
14
  ## Usage
15
15
 
@@ -55,7 +55,7 @@ Modifier chars are tolerant: one-or-more stars and three-or-more dots are all eq
55
55
 
56
56
  ### Layout wrapping
57
57
 
58
- 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.
58
+ 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>`.
59
59
 
60
60
  ```tsx
61
61
  const SIDEBARRED_ROUTES = {
@@ -68,7 +68,9 @@ const SIDEBARRED_ROUTES = {
68
68
  "/": <HomePage/>,
69
69
  "/{...path}": (
70
70
  <SidebarLayout sidebar={<Nav/>}>
71
- <Router routes={SIDEBARRED_ROUTES}/>
71
+ <Scroll vertical cover>
72
+ <Router routes={SIDEBARRED_ROUTES}/>
73
+ </Scroll>
72
74
  </SidebarLayout>
73
75
  ),
74
76
  }}/>
@@ -115,7 +117,9 @@ const SIDEBARRED_ROUTES = {
115
117
  "/login": <LoginPage/>, // no sidebar
116
118
  "/{...path}": ( // everything else wrapped
117
119
  <SidebarLayout sidebar={<Nav/>}>
118
- <Router routes={SIDEBARRED_ROUTES}/>
120
+ <Scroll vertical cover>
121
+ <Router routes={SIDEBARRED_ROUTES}/>
122
+ </Scroll>
119
123
  </SidebarLayout>
120
124
  ),
121
125
  }}/>
@@ -123,7 +127,7 @@ const SIDEBARRED_ROUTES = {
123
127
 
124
128
  ### Keeping page state
125
129
 
126
- 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 still there when you go back to them, or switch back to their tab. Shelving's `<SidebarLayout>` and `<CenteredLayout>` already do this for you.
130
+ 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.
127
131
 
128
132
  ### SSR / static rendering
129
133
 
@@ -1,3 +1,4 @@
1
+ import { type HeightVariants } from "./Height.js";
1
2
  import { type IndentVariants } from "./Indent.js";
2
3
  import { type PaddingVariants } from "./Padding.js";
3
4
  import { type SpaceVariants } from "./Space.js";
@@ -8,12 +9,12 @@ import { type WidthVariants } from "./Width.js";
8
9
  *
9
10
  * @see https://shelving.cc/ui/BlockVariants
10
11
  */
11
- export interface BlockVariants extends IndentVariants, SpaceVariants, PaddingVariants, TypographyVariants, WidthVariants {
12
+ export interface BlockVariants extends IndentVariants, SpaceVariants, PaddingVariants, TypographyVariants, WidthVariants, HeightVariants {
12
13
  }
13
14
  /**
14
15
  * Get the combined `className` string for a block from its styling variants.
15
16
  *
16
- * 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.
17
+ * 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.
17
18
  *
18
19
  * @returns A space-separated `className` string combining the block class and resolved variant classes.
19
20
  * @example getBlockClass({ space: "large" }) // "block tint …"
package/ui/style/Block.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { getClass, getModuleClass } from "../util/css.js";
2
2
  import BLOCK_CSS from "./Block.module.css";
3
+ import { getHeightClass } from "./Height.js";
3
4
  import { getIndentClass } from "./Indent.js";
4
5
  import { getPaddingClass } from "./Padding.js";
5
6
  import { getSpaceClass } from "./Space.js";
@@ -9,7 +10,7 @@ const BLOCK_CLASS = getModuleClass(BLOCK_CSS, "block");
9
10
  /**
10
11
  * Get the combined `className` string for a block from its styling variants.
11
12
  *
12
- * 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.
13
+ * 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.
13
14
  *
14
15
  * @returns A space-separated `className` string combining the block class and resolved variant classes.
15
16
  * @example getBlockClass({ space: "large" }) // "block tint …"
@@ -17,5 +18,5 @@ const BLOCK_CLASS = getModuleClass(BLOCK_CSS, "block");
17
18
  */
18
19
  export function getBlockClass(variants) {
19
20
  return getClass(BLOCK_CLASS, //
20
- getIndentClass(variants), getPaddingClass(variants), getSpaceClass(variants), getTypographyClass(variants), getWidthClass(variants));
21
+ getIndentClass(variants), getPaddingClass(variants), getSpaceClass(variants), getTypographyClass(variants), getWidthClass(variants), getHeightClass(variants));
21
22
  }
@@ -1,5 +1,6 @@
1
1
  import { getClass, getModuleClass } from "../util/css.js";
2
2
  import BLOCK_CSS from "./Block.module.css";
3
+ import { getHeightClass, type HeightVariants } from "./Height.js";
3
4
  import { getIndentClass, type IndentVariants } from "./Indent.js";
4
5
  import { getPaddingClass, type PaddingVariants } from "./Padding.js";
5
6
  import { getSpaceClass, type SpaceVariants } from "./Space.js";
@@ -13,12 +14,12 @@ const BLOCK_CLASS = getModuleClass(BLOCK_CSS, "block");
13
14
  *
14
15
  * @see https://shelving.cc/ui/BlockVariants
15
16
  */
16
- export interface BlockVariants extends IndentVariants, SpaceVariants, PaddingVariants, TypographyVariants, WidthVariants {}
17
+ export interface BlockVariants extends IndentVariants, SpaceVariants, PaddingVariants, TypographyVariants, WidthVariants, HeightVariants {}
17
18
 
18
19
  /**
19
20
  * Get the combined `className` string for a block from its styling variants.
20
21
  *
21
- * 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.
22
+ * 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.
22
23
  *
23
24
  * @returns A space-separated `className` string combining the block class and resolved variant classes.
24
25
  * @example getBlockClass({ space: "large" }) // "block tint …"
@@ -32,5 +33,6 @@ export function getBlockClass(variants: BlockVariants): string {
32
33
  getSpaceClass(variants),
33
34
  getTypographyClass(variants),
34
35
  getWidthClass(variants),
36
+ getHeightClass(variants),
35
37
  );
36
38
  }
package/ui/style/Gap.d.ts CHANGED
@@ -6,7 +6,7 @@ import type { SpaceValue } from "./Space.js";
6
6
  */
7
7
  export interface GapVariants {
8
8
  /** Gap between child elements. */
9
- gap?: SpaceValue | undefined;
9
+ gap?: Exclude<SpaceValue, "auto"> | undefined;
10
10
  }
11
11
  /**
12
12
  * Get the gap class for a component from its `gap` variant prop.
package/ui/style/Gap.tsx CHANGED
@@ -9,7 +9,7 @@ import type { SpaceValue } from "./Space.js";
9
9
  */
10
10
  export interface GapVariants {
11
11
  /** Gap between child elements. */
12
- gap?: SpaceValue | undefined;
12
+ gap?: Exclude<SpaceValue, "auto"> | undefined;
13
13
  }
14
14
 
15
15
  /**