shelving 1.321.0 → 1.322.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/docs/guides/building-with-shelving.md +204 -1
  2. package/docs/llms-full.txt +786 -114
  3. package/docs/ui/App.md +105 -7
  4. package/docs/ui/AppLayout.md +85 -0
  5. package/docs/ui/AppLayoutProps.md +21 -0
  6. package/docs/ui/Catcher.md +1 -1
  7. package/docs/ui/ErrorPage.md +2 -1
  8. package/docs/ui/FixedLayout.md +91 -0
  9. package/docs/ui/FixedLayoutProps.md +13 -0
  10. package/docs/ui/GapVariants.md +2 -2
  11. package/docs/ui/HeightVariant.md +30 -0
  12. package/docs/ui/HeightVariants.md +26 -0
  13. package/docs/ui/Navigation.md +20 -11
  14. package/docs/ui/PaddingVariants.md +2 -2
  15. package/docs/ui/Page.md +12 -8
  16. package/docs/ui/PageLoader.md +2 -1
  17. package/docs/ui/RouteCache.md +22 -17
  18. package/docs/ui/Router.md +9 -5
  19. package/docs/ui/Scroll.md +60 -6
  20. package/docs/ui/ScrollVariants.md +5 -1
  21. package/docs/ui/SidebarLayout.md +17 -8
  22. package/docs/ui/SpaceValue.md +1 -0
  23. package/docs/ui/TreeApp.md +1 -1
  24. package/docs/ui/getBlockClass.md +1 -1
  25. package/docs/ui/getGapClass.md +1 -1
  26. package/docs/ui/getHeightClass.md +64 -0
  27. package/docs/ui/getPaddingClass.md +1 -1
  28. package/docs/ui/getScrollClass.md +4 -2
  29. package/docs/ui/getSpaceClass.md +2 -0
  30. package/docs/ui.md +13 -8
  31. package/package.json +1 -1
  32. package/ui/README.md +1 -1
  33. package/ui/app/App.md +105 -7
  34. package/ui/docs/DocumentationApp.js +4 -1
  35. package/ui/docs/DocumentationApp.tsx +10 -1
  36. package/ui/layout/AppLayout.d.ts +21 -0
  37. package/ui/layout/AppLayout.js +18 -0
  38. package/ui/layout/AppLayout.md +57 -0
  39. package/ui/layout/AppLayout.module.css +106 -0
  40. package/ui/layout/AppLayout.tsx +36 -0
  41. package/ui/layout/FixedLayout.d.ts +18 -0
  42. package/ui/layout/FixedLayout.js +15 -0
  43. package/ui/layout/FixedLayout.md +65 -0
  44. package/ui/layout/FixedLayout.module.css +55 -0
  45. package/ui/layout/FixedLayout.tsx +25 -0
  46. package/ui/layout/SidebarLayout.d.ts +2 -2
  47. package/ui/layout/SidebarLayout.js +3 -4
  48. package/ui/layout/SidebarLayout.md +15 -6
  49. package/ui/layout/SidebarLayout.module.css +11 -16
  50. package/ui/layout/SidebarLayout.tsx +10 -13
  51. package/ui/layout/index.d.ts +2 -1
  52. package/ui/layout/index.js +2 -1
  53. package/ui/layout/index.tsx +2 -1
  54. package/ui/misc/Catcher.d.ts +2 -1
  55. package/ui/misc/Catcher.js +4 -3
  56. package/ui/misc/Catcher.md +1 -1
  57. package/ui/misc/Catcher.tsx +5 -4
  58. package/ui/misc/Loader.d.ts +1 -0
  59. package/ui/misc/Loader.js +6 -2
  60. package/ui/misc/Loader.tsx +11 -2
  61. package/ui/page/Page.md +12 -8
  62. package/ui/router/Navigation.md +20 -11
  63. package/ui/router/RouteCache.d.ts +2 -1
  64. package/ui/router/RouteCache.js +2 -1
  65. package/ui/router/RouteCache.md +20 -16
  66. package/ui/router/RouteCache.tsx +2 -1
  67. package/ui/router/Router.md +9 -5
  68. package/ui/style/Block.d.ts +3 -2
  69. package/ui/style/Block.js +3 -2
  70. package/ui/style/Block.tsx +4 -2
  71. package/ui/style/Gap.d.ts +1 -1
  72. package/ui/style/Gap.tsx +1 -1
  73. package/ui/style/Height.d.ts +32 -0
  74. package/ui/style/Height.js +13 -0
  75. package/ui/style/Height.module.css +88 -0
  76. package/ui/style/Height.tsx +61 -0
  77. package/ui/style/Padding.d.ts +1 -1
  78. package/ui/style/Padding.tsx +1 -1
  79. package/ui/style/Scroll.d.ts +9 -5
  80. package/ui/style/Scroll.js +6 -4
  81. package/ui/style/Scroll.md +59 -0
  82. package/ui/style/Scroll.module.css +13 -1
  83. package/ui/style/Scroll.tsx +13 -5
  84. package/ui/style/Space.d.ts +1 -1
  85. package/ui/style/Space.module.css +12 -0
  86. package/ui/style/Space.tsx +1 -0
  87. package/ui/style/getHeightClass.md +30 -0
  88. package/ui/style/getSpaceClass.md +2 -0
  89. package/ui/style/index.d.ts +1 -0
  90. package/ui/style/index.js +1 -0
  91. package/ui/style/index.ts +1 -0
  92. package/ui/tree/TreeApp.d.ts +1 -1
  93. package/ui/tree/TreeApp.js +5 -2
  94. package/ui/tree/TreeApp.tsx +11 -2
  95. package/docs/ui/CenteredLayout.md +0 -66
  96. package/docs/ui/CenteredLayoutProps.md +0 -14
  97. package/ui/layout/CenteredLayout.d.ts +0 -21
  98. package/ui/layout/CenteredLayout.js +0 -28
  99. package/ui/layout/CenteredLayout.md +0 -41
  100. package/ui/layout/CenteredLayout.module.css +0 -72
  101. package/ui/layout/CenteredLayout.tsx +0 -56
@@ -3,8 +3,11 @@ import { App } from "../app/App.js";
3
3
  import { SidebarLayout } from "../layout/SidebarLayout.js";
4
4
  import { Menu, MenuItem } from "../menu/Menu.js";
5
5
  import { PageCatcher } from "../misc/Catcher.js";
6
+ import { PageLoader } from "../misc/Loader.js";
6
7
  import { Navigation } from "../router/Navigation.js";
8
+ import { RouteCache } from "../router/RouteCache.js";
7
9
  import { Router } from "../router/Router.js";
10
+ import { Scroll } from "../style/Scroll.js";
8
11
  import type { TreeAppProps } from "../tree/TreeApp.js";
9
12
  import { TreeProvider } from "../tree/TreeContext.js";
10
13
  import { TreeRouter } from "../tree/TreeRouter.js";
@@ -38,7 +41,13 @@ export function DocumentationApp({
38
41
  }: TreeAppProps): ReactElement {
39
42
  const layout = (
40
43
  <SidebarLayout sidebar={sidebar}>
41
- <TreeRouter fallback={<Router routes={routes} />} />
44
+ <RouteCache>
45
+ <Scroll vertical cover>
46
+ <PageLoader>
47
+ <TreeRouter fallback={<Router routes={routes} />} />
48
+ </PageLoader>
49
+ </Scroll>
50
+ </RouteCache>
42
51
  </SidebarLayout>
43
52
  );
44
53
  return (
@@ -0,0 +1,21 @@
1
+ import type { ReactElement, ReactNode } from "react";
2
+ import type { OptionalChildProps } from "../util/props.js";
3
+ /**
4
+ * Props for `<AppLayout>`: the `nav` bar content and the content slot `children`.
5
+ *
6
+ * @see https://shelving.cc/ui/AppLayoutProps
7
+ */
8
+ export interface AppLayoutProps extends OptionalChildProps {
9
+ /** Items for the bar below the content, for example a `<StackButton>` for each tab. Set `false` (or leave it out) to show no bar. */
10
+ nav?: ReactNode;
11
+ }
12
+ /**
13
+ * Layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app.
14
+ * - 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.
15
+ * - The bar sits below the content slot, not over it, and it stays still while a page slides.
16
+ * - 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.
17
+ *
18
+ * @kind component
19
+ * @see https://shelving.cc/ui/AppLayout
20
+ */
21
+ export declare function AppLayout({ nav, children }: AppLayoutProps): ReactElement;
@@ -0,0 +1,18 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { getModuleClass } from "../util/css.js";
3
+ import LAYOUT_CSS from "./AppLayout.module.css";
4
+ const LAYOUT_CLASS = getModuleClass(LAYOUT_CSS, "layout");
5
+ const LAYOUT_CONTENT_CLASS = getModuleClass(LAYOUT_CSS, "content");
6
+ const LAYOUT_NAV_CLASS = getModuleClass(LAYOUT_CSS, "nav");
7
+ /**
8
+ * Layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app.
9
+ * - 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.
10
+ * - The bar sits below the content slot, not over it, and it stays still while a page slides.
11
+ * - 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.
12
+ *
13
+ * @kind component
14
+ * @see https://shelving.cc/ui/AppLayout
15
+ */
16
+ export function AppLayout({ nav, children }) {
17
+ return (_jsxs("div", { className: LAYOUT_CLASS, children: [_jsx("main", { className: LAYOUT_CONTENT_CLASS, children: children }), nav ? _jsx("nav", { className: LAYOUT_NAV_CLASS, children: nav }) : null] }));
18
+ }
@@ -0,0 +1,57 @@
1
+ # AppLayout
2
+
3
+ A full-viewport layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app. It is a frame only: it draws the bar and gives the content slot, and the app fills the slot.
4
+
5
+ **Things to know:**
6
+
7
+ - The content slot does not scroll. Fill it with `<Scroll vertical cover>` inside `<RouteCache>`, so each page scrolls in its own box and keeps its own scroll position.
8
+ - The bar sits below the content slot, not over it. So pages need no extra space at the bottom for the bar.
9
+ - The bar shows at every screen size.
10
+ - The content slot stays clear of the notch and the rounded screen corners, and the bar stays clear of the home bar (safe-area insets).
11
+ - Each item in the bar takes an equal share of its width, up to `--app-layout-nav-item-width` each.
12
+ - The bar is outside the page cache, so it has one copy. It keeps its state, and the CSS transitions of its items (an active tab) still play while a page slides.
13
+ - The bar has its own view-transition group, so it stays still while the page slides under it.
14
+ - Leave out `nav`, or set it to `false`, to show no bar. The content slot then fills the screen. To hide the bar for some pages, change the prop from the URL, so the layout and its page cache stay mounted: `nav={path.startsWith("/squad/") ? false : <StackBar />}`.
15
+ - Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
16
+
17
+ ## Usage
18
+
19
+ ```tsx
20
+ import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll, StackButton } from "shelving/ui";
21
+
22
+ function StackBar() {
23
+ return <>
24
+ <StackButton stack="/home" title="Home"><HomeIcon /></StackButton>
25
+ <StackButton stack="/discover" title="Discover"><SearchIcon /></StackButton>
26
+ <StackButton stack="/profile" title="Profile"><ProfileIcon /></StackButton>
27
+ </>;
28
+ }
29
+
30
+ <AppLayout nav={<StackBar />}>
31
+ <HorizontalTransition>
32
+ <RouteCache>
33
+ <Scroll vertical cover>
34
+ <PageLoader>
35
+ <Router routes={ROUTES} />
36
+ </PageLoader>
37
+ </Scroll>
38
+ </RouteCache>
39
+ </HorizontalTransition>
40
+ </AppLayout>
41
+ ```
42
+
43
+ ## Styling
44
+
45
+ | Variable | Styles | Default |
46
+ |---|---|---|
47
+ | `--app-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
48
+ | `--app-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
49
+ | `--app-layout-nav-background` | Bar fill (also fills the home-bar area below it) | `var(--tint-100)` (white) |
50
+ | `--app-layout-nav-color` | Bar text and icon colour | `var(--tint-00)` (black) |
51
+ | `--app-layout-nav-border` | Line above the bar | `var(--stroke-normal) solid var(--tint-90)` |
52
+ | `--app-layout-nav-shadow` | Shadow of the bar, for example a soft shadow above it | `none` |
53
+ | `--app-layout-nav-item-width` | Largest width of one bar item | `6rem` |
54
+
55
+ The bar keeps its items clear of the home bar and the rounded screen corners with safe-area insets.
56
+
57
+ **Global tokens it reads** — `--tint-00`, `--tint-90`, `--tint-100`, and `--stroke-normal`.
@@ -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;