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
@@ -0,0 +1,106 @@
1
+ @import url("../style/layers.css");
2
+ @import url("../style/Stroke.module.css");
3
+ @import url("../style/Tint.module.css");
4
+
5
+ /*
6
+ * App layout: a content slot above a bar of the app's main sections (a tab bar).
7
+ *
8
+ * The layout is a frame only. It does not scroll: the `.content` slot is a positioned box, and the app fills it
9
+ * with `<Scroll vertical cover>` (inside `<RouteCache>`), so each page scrolls in its own box. The bar sits below
10
+ * the slot, not over it, so the slot never needs to know the bar's height.
11
+ */
12
+
13
+ @layer components {
14
+ /*
15
+ * Lock the document so the content slot is the only place that scrolls.
16
+ * - <html> and <body> are pinned to the viewport (no rubber-band on iOS).
17
+ */
18
+ html:has(.layout) {
19
+ /* Box */
20
+ margin: 0;
21
+ padding: 0;
22
+ height: 100vh;
23
+ height: 100dvh; /* Expand and contract as the address bar shows and hides on iOS. */
24
+ width: 100vw;
25
+ width: 100dvw;
26
+
27
+ /* Contents */
28
+ overflow: hidden;
29
+ overflow-wrap: break-word; /* Break overlong words only as a last resort. */
30
+ }
31
+
32
+ body:has(.layout) {
33
+ /* Box */
34
+ margin: 0;
35
+ padding: 0;
36
+
37
+ /* Lock body to prevent iOS Safari triggering viewport scrolling on focus change. */
38
+ position: fixed;
39
+ inset: 0;
40
+
41
+ /* Style */
42
+ background: var(--app-layout-background, var(--tint-100));
43
+ color: var(--app-layout-color, var(--tint-00));
44
+ }
45
+
46
+ .layout {
47
+ /* Fill the locked body, even inside a mount element such as `<div id="root">`. `absolute`, not `fixed`: iOS Safari paints the status bar from a fixed element at the top edge. */
48
+ position: absolute;
49
+ inset: 0;
50
+
51
+ /* Stack the content slot above the bar. */
52
+ display: flex;
53
+ flex-direction: column;
54
+ }
55
+
56
+ /* The content slot: a positioned box that `<Scroll vertical cover>` fills. */
57
+ .content {
58
+ position: relative;
59
+ flex: 1;
60
+ min-height: 0;
61
+ overflow: hidden;
62
+
63
+ /* Keep the slot clear of the notch and the rounded corners (an absolute child fills the box inside the borders). The bar handles the bottom. */
64
+ border-top: env(safe-area-inset-top, 0) solid transparent;
65
+ border-left: env(safe-area-inset-left, 0) solid transparent;
66
+ border-right: env(safe-area-inset-right, 0) solid transparent;
67
+ }
68
+
69
+ /* The bar. Its transparent bottom border keeps the items clear of the home bar, and its background fills that area. */
70
+ .nav {
71
+ /* Box */
72
+ display: flex;
73
+ justify-content: center;
74
+ border-block-start: var(--app-layout-nav-border, var(--stroke-normal) solid var(--tint-90));
75
+ border-block-end: env(safe-area-inset-bottom, 0) solid transparent;
76
+ padding-inline: env(safe-area-inset-left, 0) env(safe-area-inset-right, 0);
77
+
78
+ /* Style */
79
+ background: var(--app-layout-nav-background, var(--tint-100));
80
+ color: var(--app-layout-nav-color, var(--tint-00));
81
+ box-shadow: var(--app-layout-nav-shadow, none);
82
+
83
+ /* Its own view-transition group, so a page slide passes under it and the bar stays still. */
84
+ view-transition-name: app-layout-nav;
85
+
86
+ /* Each item takes an equal share of the bar. */
87
+ > * {
88
+ flex: 1;
89
+ max-width: var(--app-layout-nav-item-width, 6rem);
90
+ }
91
+ }
92
+ }
93
+
94
+ /* The bar stays still, so it never makes a view transition last longer. */
95
+ ::view-transition-group(app-layout-nav) {
96
+ animation-duration: 0s;
97
+ }
98
+
99
+ /* Show only the live bar during a view transition, so the CSS transitions of its items (an active tab) play with no cross-fade. */
100
+ ::view-transition-old(app-layout-nav) {
101
+ display: none;
102
+ }
103
+
104
+ ::view-transition-new(app-layout-nav) {
105
+ animation: none;
106
+ }
@@ -0,0 +1,36 @@
1
+ import type { ReactElement, ReactNode } from "react";
2
+ import { getModuleClass } from "../util/css.js";
3
+ import type { OptionalChildProps } from "../util/props.js";
4
+ import LAYOUT_CSS from "./AppLayout.module.css";
5
+
6
+ const LAYOUT_CLASS = getModuleClass(LAYOUT_CSS, "layout");
7
+ const LAYOUT_CONTENT_CLASS = getModuleClass(LAYOUT_CSS, "content");
8
+ const LAYOUT_NAV_CLASS = getModuleClass(LAYOUT_CSS, "nav");
9
+
10
+ /**
11
+ * Props for `<AppLayout>`: the `nav` bar content and the content slot `children`.
12
+ *
13
+ * @see https://shelving.cc/ui/AppLayoutProps
14
+ */
15
+ export interface AppLayoutProps extends OptionalChildProps {
16
+ /** Items for the bar below the content, for example a `<StackButton>` for each tab. Set `false` (or leave it out) to show no bar. */
17
+ nav?: ReactNode;
18
+ }
19
+
20
+ /**
21
+ * Layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app.
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.
23
+ * - The bar sits below the content slot, not over it, and it stays still while a page slides.
24
+ * - 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.
25
+ *
26
+ * @kind component
27
+ * @see https://shelving.cc/ui/AppLayout
28
+ */
29
+ export function AppLayout({ nav, children }: AppLayoutProps): ReactElement {
30
+ return (
31
+ <div className={LAYOUT_CLASS}>
32
+ <main className={LAYOUT_CONTENT_CLASS}>{children}</main>
33
+ {nav ? <nav className={LAYOUT_NAV_CLASS}>{nav}</nav> : null}
34
+ </div>
35
+ );
36
+ }
@@ -0,0 +1,18 @@
1
+ import type { ReactElement } from "react";
2
+ import type { OptionalChildProps } from "../util/props.js";
3
+ /**
4
+ * Props for `<FixedLayout>`: the content slot `children`.
5
+ *
6
+ * @see https://shelving.cc/ui/FixedLayoutProps
7
+ */
8
+ export interface FixedLayoutProps extends OptionalChildProps {
9
+ }
10
+ /**
11
+ * Layout with no chrome: the whole screen is one content slot.
12
+ * - It locks the document and gives a full-height slot inside the safe areas. It does not scroll or centre.
13
+ * - Fill the slot with `<Scroll vertical cover>`. Used for e.g. log-in and error screens, and full-screen pages.
14
+ *
15
+ * @kind component
16
+ * @see https://shelving.cc/ui/FixedLayout
17
+ */
18
+ export declare function FixedLayout({ children }: FixedLayoutProps): ReactElement;
@@ -0,0 +1,15 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { getModuleClass } from "../util/css.js";
3
+ import LAYOUT_CSS from "./FixedLayout.module.css";
4
+ const LAYOUT_CLASS = getModuleClass(LAYOUT_CSS, "layout");
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
+ * @kind component
11
+ * @see https://shelving.cc/ui/FixedLayout
12
+ */
13
+ export function FixedLayout({ children }) {
14
+ return _jsx("main", { className: LAYOUT_CLASS, children: children });
15
+ }
@@ -0,0 +1,65 @@
1
+ # FixedLayout
2
+
3
+ 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.
4
+
5
+ **Things to know:**
6
+
7
+ - It is a frame only. It does not scroll or centre. Fill the slot with `<Scroll vertical cover>`, so the content scrolls inside it.
8
+ - 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.
9
+ - The slot stays clear of the notch, the home bar and the rounded screen corners (safe-area insets).
10
+ - For pages that you move back and forth between, put a `<RouteCache>` around the scroll box, as in `<AppLayout>`.
11
+ - Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
12
+
13
+ ## Usage
14
+
15
+ ```tsx
16
+ import { Block, FixedLayout, Router, Scroll } from "shelving/ui";
17
+
18
+ // The signed-out screens: one layout around their own router.
19
+ <FixedLayout>
20
+ <Scroll vertical cover>
21
+ <Router routes={{
22
+ "/login": LoginPage,
23
+ "/register": RegisterPage,
24
+ }} />
25
+ </Scroll>
26
+ </FixedLayout>
27
+
28
+ // Each page centres its own content.
29
+ function LoginPage() {
30
+ return (
31
+ <Page title="Log in">
32
+ <Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
33
+ <LoginForm />
34
+ </Block>
35
+ </Page>
36
+ );
37
+ }
38
+ ```
39
+
40
+ An app-level error, outside every other layout:
41
+
42
+ ```tsx
43
+ import { Catcher, ErrorPage, type ErrorProps, FixedLayout, Scroll } from "shelving/ui";
44
+
45
+ function AppError({ reason }: ErrorProps) {
46
+ return (
47
+ <FixedLayout>
48
+ <Scroll vertical cover>
49
+ <ErrorPage reason={reason} />
50
+ </Scroll>
51
+ </FixedLayout>
52
+ );
53
+ }
54
+
55
+ <Catcher as={AppError}>…</Catcher>
56
+ ```
57
+
58
+ ## Styling
59
+
60
+ | Variable | Styles | Default |
61
+ |---|---|---|
62
+ | `--fixed-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
63
+ | `--fixed-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
64
+
65
+ **Global tokens it reads** — `--tint-00` and `--tint-100`.
@@ -0,0 +1,55 @@
1
+ @import url("../style/layers.css");
2
+ @import url("../style/Tint.module.css");
3
+
4
+ /*
5
+ * Fixed layout: the whole screen as one content slot.
6
+ *
7
+ * The layout is a frame only. It locks the document and gives a full-height, positioned slot inside the
8
+ * safe areas. It does not scroll or centre: the app fills the slot with `<Scroll vertical cover>`.
9
+ */
10
+
11
+ @layer components {
12
+ /*
13
+ * Lock the document so the content slot is the only place that scrolls.
14
+ * - <html> and <body> are pinned to the viewport (no rubber-band on iOS).
15
+ */
16
+ html:has(.layout) {
17
+ /* Box */
18
+ margin: 0;
19
+ padding: 0;
20
+ height: 100vh;
21
+ height: 100dvh; /* Expand and contract as the address bar shows and hides on iOS. */
22
+ width: 100vw;
23
+ width: 100dvw;
24
+
25
+ /* Contents */
26
+ overflow: hidden;
27
+ overflow-wrap: break-word; /* Break overlong words only as a last resort. */
28
+ }
29
+
30
+ body:has(.layout) {
31
+ /* Box */
32
+ margin: 0;
33
+ padding: 0;
34
+
35
+ /* Lock body to prevent iOS Safari triggering viewport scrolling on focus change. */
36
+ position: fixed;
37
+ inset: 0;
38
+
39
+ /* Style */
40
+ background: var(--fixed-layout-background, var(--tint-100));
41
+ color: var(--fixed-layout-color, var(--tint-00));
42
+ }
43
+
44
+ /* The content slot: a positioned box that fills the screen, and that `<Scroll vertical cover>` fills. Transparent borders keep it inside the safe areas (an absolute child fills the box inside the borders). */
45
+ .layout {
46
+ /* Fill the locked body, even inside a mount element such as `<div id="root">`. `absolute`, not `fixed`: iOS Safari paints the status bar from a fixed element at the top edge. */
47
+ position: absolute;
48
+ inset: 0;
49
+ overflow: hidden;
50
+ border-top: env(safe-area-inset-top, 0) solid transparent;
51
+ border-bottom: env(safe-area-inset-bottom, 0) solid transparent;
52
+ border-left: env(safe-area-inset-left, 0) solid transparent;
53
+ border-right: env(safe-area-inset-right, 0) solid transparent;
54
+ }
55
+ }
@@ -0,0 +1,25 @@
1
+ import type { ReactElement } from "react";
2
+ import { getModuleClass } from "../util/css.js";
3
+ import type { OptionalChildProps } from "../util/props.js";
4
+ import LAYOUT_CSS from "./FixedLayout.module.css";
5
+
6
+ const LAYOUT_CLASS = getModuleClass(LAYOUT_CSS, "layout");
7
+
8
+ /**
9
+ * Props for `<FixedLayout>`: the content slot `children`.
10
+ *
11
+ * @see https://shelving.cc/ui/FixedLayoutProps
12
+ */
13
+ export interface FixedLayoutProps extends OptionalChildProps {}
14
+
15
+ /**
16
+ * Layout with no chrome: the whole screen is one content slot.
17
+ * - It locks the document and gives a full-height slot inside the safe areas. It does not scroll or centre.
18
+ * - Fill the slot with `<Scroll vertical cover>`. Used for e.g. log-in and error screens, and full-screen pages.
19
+ *
20
+ * @kind component
21
+ * @see https://shelving.cc/ui/FixedLayout
22
+ */
23
+ export function FixedLayout({ children }: FixedLayoutProps): ReactElement {
24
+ return <main className={LAYOUT_CLASS}>{children}</main>;
25
+ }
@@ -12,12 +12,12 @@ export interface SidebarLayoutProps extends OptionalChildProps {
12
12
  right?: boolean | undefined;
13
13
  }
14
14
  /**
15
- * Layout with a fixed-width side column (typically navigation) next to a scrollable main content column.
15
+ * Layout with a fixed-width side column (typically navigation) next to a content slot.
16
16
  * - The sidebar is rendered as `<nav>` — it almost always contains the page's primary navigation.
17
17
  * - 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.
18
18
  * - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
19
19
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
20
- * - 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.
20
+ * - 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.
21
21
  *
22
22
  * @kind component
23
23
  * @see https://shelving.cc/ui/SidebarLayout
@@ -4,7 +4,6 @@ import { CloseIcon } from "shelving/icon/CloseIcon";
4
4
  import { MenuIcon } from "shelving/icon/MenuIcon";
5
5
  import { Button } from "../button/Button.js";
6
6
  import { requireMetaURL } from "../misc/MetaContext.js";
7
- import { RouteCache } from "../router/RouteCache.js";
8
7
  import { getClass, getModuleClass } from "../util/css.js";
9
8
  import LAYOUT_CSS from "./SidebarLayout.module.css";
10
9
  const LAYOUT_SIDEBAR_CLASS = getModuleClass(LAYOUT_CSS, "sidebar");
@@ -15,12 +14,12 @@ const LAYOUT_MAIN_CLASS = getModuleClass(LAYOUT_CSS, "main");
15
14
  const LAYOUT_OPEN_CLASS = getModuleClass(LAYOUT_CSS, "open");
16
15
  const LAYOUT_RIGHT_CLASS = getModuleClass(LAYOUT_CSS, "right");
17
16
  /**
18
- * Layout with a fixed-width side column (typically navigation) next to a scrollable main content column.
17
+ * Layout with a fixed-width side column (typically navigation) next to a content slot.
19
18
  * - The sidebar is rendered as `<nav>` — it almost always contains the page's primary navigation.
20
19
  * - 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.
21
20
  * - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
22
21
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
23
- * - 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.
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. The sidebar stays outside the cache, so it keeps its own state and scroll.
24
23
  *
25
24
  * @kind component
26
25
  * @see https://shelving.cc/ui/SidebarLayout
@@ -35,5 +34,5 @@ export function SidebarLayout({ sidebar, children, right = false }) {
35
34
  }, [path]);
36
35
  // DOM order is always sidebar → content → overlay; the `right` variant flips the visual column order in CSS, so the markup never reshuffles.
37
36
  return (_jsxs("main", { className: getClass(LAYOUT_MAIN_CLASS, right && LAYOUT_RIGHT_CLASS), children: [_jsx("nav", { className: getClass(LAYOUT_SIDEBAR_CLASS, //
38
- open && LAYOUT_OPEN_CLASS), children: sidebar }), _jsx(RouteCache, { children: _jsxs("div", { className: LAYOUT_CONTENT_CLASS, children: [_jsx("div", { className: LAYOUT_TOGGLE_CLASS, children: _jsx(Button, { title: open ? "Close menu" : "Show menu", onClick: () => setOpen(o => !o), children: open ? _jsx(CloseIcon, {}) : _jsx(MenuIcon, {}) }) }), children] }) }), _jsx("button", { type: "button", className: getClass(LAYOUT_OVERLAY_CLASS, open && LAYOUT_OPEN_CLASS), "aria-label": "Close menu", onClick: () => setOpen(false) })] }));
37
+ open && LAYOUT_OPEN_CLASS), children: sidebar }), _jsxs("div", { className: LAYOUT_CONTENT_CLASS, children: [_jsx("div", { className: LAYOUT_TOGGLE_CLASS, children: _jsx(Button, { title: open ? "Close menu" : "Show menu", onClick: () => setOpen(o => !o), children: open ? _jsx(CloseIcon, {}) : _jsx(MenuIcon, {}) }) }), children] }), _jsx("button", { type: "button", className: getClass(LAYOUT_OVERLAY_CLASS, open && LAYOUT_OPEN_CLASS), "aria-label": "Close menu", onClick: () => setOpen(false) })] }));
39
38
  }
@@ -1,6 +1,6 @@
1
1
  # SidebarLayout
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
5
  **Things to know:**
6
6
 
@@ -9,12 +9,15 @@ A full-viewport layout with a fixed-width side column next to a scrollable main
9
9
  - While the drawer is open an overlay dims the page; clicking the overlay closes it.
10
10
  - 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.
11
11
  - Inside a `<Navigation>` context the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
12
- - The layout owns scroll, padding, and safe-area insets so individual pages don't have to.
12
+ - 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.
13
+ - The sidebar stays outside the page cache, so it keeps its own scroll position and state as pages change.
14
+ - On a narrow screen the menu button floats at the top right of the content slot, above the page.
15
+ - Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
13
16
 
14
17
  ## Usage
15
18
 
16
19
  ```tsx
17
- import { SidebarLayout, Menu, MenuItem, Router } from "shelving/ui";
20
+ import { Menu, MenuItem, PageLoader, RouteCache, Router, Scroll, SidebarLayout } from "shelving/ui";
18
21
 
19
22
  function AppShell() {
20
23
  const nav = (
@@ -26,13 +29,19 @@ function AppShell() {
26
29
  );
27
30
  return (
28
31
  <SidebarLayout sidebar={nav}>
29
- <Router routes={ROUTES}/>
32
+ <RouteCache>
33
+ <Scroll vertical cover>
34
+ <PageLoader>
35
+ <Router routes={ROUTES}/>
36
+ </PageLoader>
37
+ </Scroll>
38
+ </RouteCache>
30
39
  </SidebarLayout>
31
40
  );
32
41
  }
33
42
  ```
34
43
 
35
- Layouts compose naturally as `<Router>` route values — wrap a group of routes in a shared layout, then route further inside it.
44
+ To slide pages, put a transition around the `<RouteCache>`, inside the layout. The sidebar is outside the transition, so it stays still.
36
45
 
37
46
  ## Styling
38
47
 
@@ -46,6 +55,6 @@ Layouts compose naturally as `<Router>` route values — wrap a group of routes
46
55
  | `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-90)` | `none` |
47
56
  | `--sidebar-layout-shadow` | Drop shadow of the open drawer on a narrow screen | `var(--shadow-large)` |
48
57
 
49
- The sidebar and content columns own their own scroll behaviour directly (this layout no longer composes a shared `.layout` class).
58
+ The sidebar scrolls on its own. The content slot does not scroll: its `<Scroll vertical cover>` box does.
50
59
 
51
60
  **Global tokens it reads** — `--tint-00` / `--tint-90` / `--tint-100`, plus `--space-normal`, `--duration-normal`, `--shadow-large`, and `--color-backdrop`.
@@ -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