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
package/docs/ui/Router.md CHANGED
@@ -21,7 +21,7 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
21
21
  - With a `base` set, the path used for matching is the URL after `matchURLPrefix()` strips the base prefix; URLs outside the base render as `null`.
22
22
  - Pass `fallback` to control no-match behaviour. An explicit `null` renders nothing; leaving it `undefined` throws a `NotFoundError`.
23
23
  - Inside `<Navigation>` with stacks, each page in a stack is a new page: a link mounts a new page, and `NavigationStore.replace()` keeps the same page mounted (it re-renders with the new URL). Elsewhere each path is a new page.
24
- - `<Router>` itself does not cache pages — wrap it in a `<RouteCache>` (or use a layout that already does) to keep recently-visited pages mounted but hidden so back/forward navigation restores their state.
24
+ - `<Router>` itself does not cache pages — wrap it in a `<RouteCache>` (with a `<Scroll vertical cover>` between them) to keep recently-visited pages mounted but hidden so back/forward navigation restores their state.
25
25
 
26
26
  ## Usage
27
27
 
@@ -67,7 +67,7 @@ Modifier chars are tolerant: one-or-more stars and three-or-more dots are all eq
67
67
 
68
68
  ### Layout wrapping
69
69
 
70
- Put layout JSX as the route value with another `<Router>` inside. Since `<Router>` reads its URL from `<Meta>`, the inner router sees the same URL.
70
+ Put layout JSX as the route value with another `<Router>` inside. Since `<Router>` reads its URL from `<Meta>`, the inner router sees the same URL. A layout's content slot does not scroll, so put a `<Scroll vertical cover>` in it (and a `<RouteCache>` around that, to keep pages). See "Composing an app" on `<App>`.
71
71
 
72
72
  ```tsx
73
73
  const SIDEBARRED_ROUTES = {
@@ -80,7 +80,9 @@ const SIDEBARRED_ROUTES = {
80
80
  "/": <HomePage/>,
81
81
  "/{...path}": (
82
82
  <SidebarLayout sidebar={<Nav/>}>
83
- <Router routes={SIDEBARRED_ROUTES}/>
83
+ <Scroll vertical cover>
84
+ <Router routes={SIDEBARRED_ROUTES}/>
85
+ </Scroll>
84
86
  </SidebarLayout>
85
87
  ),
86
88
  }}/>
@@ -127,7 +129,9 @@ const SIDEBARRED_ROUTES = {
127
129
  "/login": <LoginPage/>, // no sidebar
128
130
  "/{...path}": ( // everything else wrapped
129
131
  <SidebarLayout sidebar={<Nav/>}>
130
- <Router routes={SIDEBARRED_ROUTES}/>
132
+ <Scroll vertical cover>
133
+ <Router routes={SIDEBARRED_ROUTES}/>
134
+ </Scroll>
131
135
  </SidebarLayout>
132
136
  ),
133
137
  }}/>
@@ -135,7 +139,7 @@ const SIDEBARRED_ROUTES = {
135
139
 
136
140
  ### Keeping page state
137
141
 
138
- 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.
142
+ By default a page is unmounted when you navigate away and mounted fresh when you return — so scroll position, open/closed toggles, in-progress searches, form inputs, and focus are all lost, and you land back at the top. Wrap the router in a `<RouteCache>`, with a `<Scroll vertical cover>` between them, to keep recently-visited pages mounted but hidden so their state is still there when you go back to them, or switch back to their tab. Layouts do not do this for you: see `<RouteCache>` for the full nesting.
139
143
 
140
144
  ### SSR / static rendering
141
145
 
package/docs/ui/Scroll.md CHANGED
@@ -4,6 +4,66 @@
4
4
  - Import: `import { Scroll } from "shelving/ui";`
5
5
 
6
6
  Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
7
+ - With `cover`, it fills a layout's content slot, so each page in a `<RouteCache>` scrolls in its own box.
8
+
9
+ A box that scrolls its content on one or both axes. Use it for a wide table on a small screen, or as the scroll box of each page in an app.
10
+
11
+ **Things to know:**
12
+
13
+ - Set `vertical`, `horizontal`, or both. With neither, the box clips its content and does not scroll.
14
+ - Set `cover` to fill the nearest positioned ancestor (`position: absolute; inset: 0`). A layout's content slot is positioned, so `<Scroll vertical cover>` fills it.
15
+ - Set `reverse` to start at the end and stay there when the content grows, for example a chat. Put the content in one child: only the scroll is reversed, so the child keeps its own order. No script is needed.
16
+ - Overscroll stops at the box edge (`overscroll-behavior: none`), so a scroll inside the box never scrolls the page behind it.
17
+ - When the box has keyboard focus, it shows a focus outline.
18
+
19
+ ## Usage
20
+
21
+ ### A wide table
22
+
23
+ ```tsx
24
+ import { Scroll, Table } from "shelving/ui";
25
+
26
+ <Scroll horizontal>
27
+ <Table>…</Table>
28
+ </Scroll>
29
+ ```
30
+
31
+ ### A scroll box for each page
32
+
33
+ Put `<Scroll vertical cover>` inside `<RouteCache>`, so each kept page has its own scroll box and keeps its own scroll position. The layout gives its content slot `position: relative`, and the scroll box fills it.
34
+
35
+ ```tsx
36
+ import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
37
+
38
+ <AppLayout nav={<StackBar />}>
39
+ <HorizontalTransition>
40
+ <RouteCache>
41
+ <Scroll vertical cover>
42
+ <PageLoader>
43
+ <Router routes={ROUTES} />
44
+ </PageLoader>
45
+ </Scroll>
46
+ </RouteCache>
47
+ </HorizontalTransition>
48
+ </AppLayout>
49
+ ```
50
+
51
+ ### A chat
52
+
53
+ ```tsx
54
+ <Scroll vertical cover reverse>
55
+ <div>{messages}</div>
56
+ </Scroll>
57
+ ```
58
+
59
+ ## Styling
60
+
61
+ | Variable | Styles | Default |
62
+ |---|---|---|
63
+ | `--scroll-focus-border` | Outline when the box has keyboard focus | `var(--stroke-focus) solid var(--color-focus)` |
64
+
65
+ **Global tokens it reads** — `--stroke-focus`, `--stroke-normal`, and `--color-focus`.
66
+
7
67
 
8
68
  ## Signatures
9
69
 
@@ -22,9 +82,3 @@ Scroll({ children, ...props }: ScrollComponentProps): ReactElement
22
82
  | Type | Description |
23
83
  | --- | --- |
24
84
  | `ReactElement` | A `<div>` element with the computed scroll class. |
25
-
26
- ## Examples
27
-
28
- ```ts
29
- <Scroll horizontal>{wideContent}</Scroll>
30
- ```
@@ -3,7 +3,7 @@
3
3
  - Kind: interface
4
4
  - Import: `import { ScrollVariants } from "shelving/ui";`
5
5
 
6
- Variant props selecting which scroll axes are enabled on an element.
6
+ Variant props for a scroll region: which axes scroll, plus `cover` and `reverse`.
7
7
 
8
8
  ## Signatures
9
9
 
@@ -11,6 +11,8 @@ Variant props selecting which scroll axes are enabled on an element.
11
11
  {
12
12
  vertical?: boolean | undefined;
13
13
  horizontal?: boolean | undefined;
14
+ cover?: boolean | undefined;
15
+ reverse?: boolean | undefined;
14
16
  }
15
17
  ```
16
18
 
@@ -20,3 +22,5 @@ Variant props selecting which scroll axes are enabled on an element.
20
22
  | --- | --- | --- |
21
23
  | `vertical` | `boolean \| undefined` | Vertical scrolling (defaults to `false`). Optional. |
22
24
  | `horizontal` | `boolean \| undefined` | Horizontal scrolling (defaults to `false`). Optional. |
25
+ | `cover` | `boolean \| undefined` | Cover the nearest positioned ancestor (`position: absolute; inset: 0`), for example a layout's content slot (defaults to `false`). Optional. |
26
+ | `reverse` | `boolean \| undefined` | Start at the end and stay there as the content grows, for example a chat (defaults to `false`). Put the content in one child. Optional. |
@@ -3,14 +3,14 @@
3
3
  - Kind: component
4
4
  - Import: `import { SidebarLayout } from "shelving/ui";`
5
5
 
6
- Layout with a fixed-width side column (typically navigation) next to a scrollable main content column.
6
+ Layout with a fixed-width side column (typically navigation) next to a content slot.
7
7
  - The sidebar is rendered as `<nav>` — it almost always contains the page's primary navigation.
8
8
  - On narrow viewports the sidebar becomes an off-canvas drawer toggled by a single menu button that switches between a burger and a close icon.
9
9
  - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
10
10
  - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
11
- - The scrollable content column is kept alive across navigation via `<RouteCache>`, so returning to a recently-visited page restores its scroll position and state; the sidebar stays mounted throughout.
11
+ - It is a frame only: the content slot does not scroll. Fill it with `<Scroll vertical cover>`, inside `<RouteCache>`, so each page scrolls in its own box. The sidebar stays outside the cache, so it keeps its own state and scroll.
12
12
 
13
- A full-viewport layout with a fixed-width side column next to a scrollable main content column. The sidebar renders as a `<nav>` landmark — it almost always holds the primary navigation. On narrow viewports it collapses to an off-canvas drawer toggled by a single burger/close button.
13
+ A full-viewport layout with a fixed-width side column next to a content slot. The sidebar renders as a `<nav>` landmark — it almost always holds the primary navigation. On narrow viewports it collapses to an off-canvas drawer toggled by a single burger/close button.
14
14
 
15
15
  **Things to know:**
16
16
 
@@ -19,12 +19,15 @@ A full-viewport layout with a fixed-width side column next to a scrollable main
19
19
  - While the drawer is open an overlay dims the page; clicking the overlay closes it.
20
20
  - Under `prefers-reduced-motion: reduce` the drawer snaps open/closed instead of sliding off-canvas; the overlay keeps its dimming fade, which is opacity-only and therefore reduced-motion-safe.
21
21
  - Inside a `<Navigation>` context the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
22
- - The layout owns scroll, padding, and safe-area insets so individual pages don't have to.
22
+ - It is a frame only. The content slot does not scroll: fill it with `<Scroll vertical cover>` inside `<RouteCache>`, so each page scrolls in its own box. Content put in the slot without a scroll box does not scroll.
23
+ - The sidebar stays outside the page cache, so it keeps its own scroll position and state as pages change.
24
+ - On a narrow screen the menu button floats at the top right of the content slot, above the page.
25
+ - Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
23
26
 
24
27
  ## Usage
25
28
 
26
29
  ```tsx
27
- import { SidebarLayout, Menu, MenuItem, Router } from "shelving/ui";
30
+ import { Menu, MenuItem, PageLoader, RouteCache, Router, Scroll, SidebarLayout } from "shelving/ui";
28
31
 
29
32
  function AppShell() {
30
33
  const nav = (
@@ -36,13 +39,19 @@ function AppShell() {
36
39
  );
37
40
  return (
38
41
  <SidebarLayout sidebar={nav}>
39
- <Router routes={ROUTES}/>
42
+ <RouteCache>
43
+ <Scroll vertical cover>
44
+ <PageLoader>
45
+ <Router routes={ROUTES}/>
46
+ </PageLoader>
47
+ </Scroll>
48
+ </RouteCache>
40
49
  </SidebarLayout>
41
50
  );
42
51
  }
43
52
  ```
44
53
 
45
- Layouts compose naturally as `<Router>` route values — wrap a group of routes in a shared layout, then route further inside it.
54
+ To slide pages, put a transition around the `<RouteCache>`, inside the layout. The sidebar is outside the transition, so it stays still.
46
55
 
47
56
  ## Styling
48
57
 
@@ -56,7 +65,7 @@ Layouts compose naturally as `<Router>` route values — wrap a group of routes
56
65
  | `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-90)` | `none` |
57
66
  | `--sidebar-layout-shadow` | Drop shadow of the open drawer on a narrow screen | `var(--shadow-large)` |
58
67
 
59
- The sidebar and content columns own their own scroll behaviour directly (this layout no longer composes a shared `.layout` class).
68
+ The sidebar scrolls on its own. The content slot does not scroll: its `<Scroll vertical cover>` box does.
60
69
 
61
70
  **Global tokens it reads** — `--tint-00` / `--tint-90` / `--tint-100`, plus `--space-normal`, `--duration-normal`, `--shadow-large`, and `--color-backdrop`.
62
71
 
@@ -11,6 +11,7 @@ Allowed values for block spacing for components that support `SpaceVariants`
11
11
  | "section"
12
12
  | "paragraph"
13
13
  | "none"
14
+ | "auto"
14
15
  | "xxsmall"
15
16
  | "xsmall"
16
17
  | "small"
@@ -5,7 +5,7 @@
5
5
 
6
6
  Top-level app component for a tree-based documentation site.
7
7
 
8
- - Wraps `<App>` with error catching and a sidebar layout.
8
+ - Wraps `<App>` with error catching and a sidebar layout. Each page is kept in a `<RouteCache>` and scrolls in its own `<Scroll>` box, and a page error shows inside the layout.
9
9
  - Flattens `tree` once via `<TreeProvider>` wrapping both the sidebar and the router, so everything below shares a single `useTreeMap()` lookup — nothing re-flattens.
10
10
  - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
11
11
  - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
@@ -5,7 +5,7 @@
5
5
 
6
6
  Get the combined `className` string for a block from its styling variants.
7
7
 
8
- Composes the base block class and tint ladder with the colour, space, typography, and width variant helpers, so anything that wants block-level styling can apply it.
8
+ Composes the base block class and tint ladder with the colour, space, typography, width, and height variant helpers, so anything that wants block-level styling can apply it.
9
9
 
10
10
  ## Signatures
11
11
 
@@ -16,7 +16,7 @@ getGapClass({ gap }: GapVariants): string | undefined
16
16
  | Param | Type | Description |
17
17
  | --- | --- | --- |
18
18
  | `options` | `GapVariants` | |
19
- | `.gap` | `SpaceValue \| undefined` | Gap between child elements. Optional. |
19
+ | `.gap` | `Exclude<SpaceValue, "auto"> \| undefined` | Gap between child elements. Optional. |
20
20
 
21
21
  ## Returns
22
22
 
@@ -0,0 +1,64 @@
1
+ # getHeightClass()
2
+
3
+ - Kind: function
4
+ - Import: `import { getHeightClass } from "shelving/ui";`
5
+
6
+ Get the height class for a component from its `height`, `top`, `middle` and `bottom` variant props.
7
+
8
+ The `height` variant prop sets a component's minimum block size, and `top` / `middle` / `bottom` set where its content sits inside that height — `<Block height="full" middle>`, `<Section height="12x" bottom>`. It is the vertical partner of the `width` variant (see `getWidthClass()`).
9
+
10
+ `getHeightClass({ height, top, middle, bottom })` maps the props to height classes.
11
+
12
+ **Values:**
13
+
14
+ - `full` — at least the full height of the container, for example a layout's `<Scroll vertical cover>` box.
15
+ - `1x` / `2x` / `3x` / `4x` / `5x` / `6x` / `7x` / `8x` / `10x` / `12x` / `16x` / `20x` / `24x` / `28x` / `32x` — at least a multiple of `--space-normal`.
16
+
17
+ **Things to know:**
18
+
19
+ - Every height is a minimum (`min-block-size`). When the content is taller, the element grows, so a scroll box scrolls it from the top and nothing is cut off.
20
+ - `top` (the default), `middle` and `bottom` set `align-content` on the element itself. The element keeps its own `display`, so its parent does not need to be a flex box. They only do something when the element is taller than its content, so use them with `height`.
21
+ - `<Row>` and `<Column>` already have `top` / `middle` / `bottom` flex variants with the same meaning, so `<Column height="full" middle>` also puts its items in the middle (see `getFlexClass()`).
22
+ - In a flex or grid container, `space="auto"` is the other way to centre a block (see `getSpaceClass()`).
23
+ - `align-content` on a plain block shipped in Chrome 123, Firefox 125 and Safari 17.4. Older browsers show the content at the top.
24
+
25
+ ## Usage
26
+
27
+ A log-in screen, in the middle of a layout's scroll box:
28
+
29
+ ```tsx
30
+ <Page title="Log in">
31
+ <Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
32
+ <LoginForm />
33
+ </Block>
34
+ </Page>
35
+ ```
36
+
37
+
38
+ ## Signatures
39
+
40
+ ```ts
41
+ getHeightClass({ height, top, middle, bottom }: HeightVariants): string | undefined
42
+ ```
43
+
44
+ ## Parameters
45
+
46
+ | Param | Type | Description |
47
+ | --- | --- | --- |
48
+ | `options` | `HeightVariants` | |
49
+ | `.height` | `HeightVariant \| undefined` | Height of the element. It is a minimum, so the element grows when its content is taller. Optional. |
50
+ | `.top` | `boolean \| undefined` | Put the content at the top of the element (the default). Optional. |
51
+ | `.middle` | `boolean \| undefined` | Put the content in the vertical middle of the element. Use with `height`. Optional. |
52
+ | `.bottom` | `boolean \| undefined` | Put the content at the bottom of the element. Use with `height`. Optional. |
53
+
54
+ ## Returns
55
+
56
+ | Type | Description |
57
+ | --- | --- |
58
+ | `string \| undefined` | The height class string, or `undefined` if no height variants are set. |
59
+
60
+ ## Examples
61
+
62
+ ```ts
63
+ getHeightClass({ height: "full", middle: true }) // "height height-full middle"
64
+ ```
@@ -16,7 +16,7 @@ getPaddingClass({ padding }: PaddingVariants): string | undefined
16
16
  | Param | Type | Description |
17
17
  | --- | --- | --- |
18
18
  | `options` | `PaddingVariants` | |
19
- | `.padding` | `SpaceValue \| undefined` | Block-padding (top + bottom) of the element. Optional. |
19
+ | `.padding` | `Exclude<SpaceValue, "auto"> \| undefined` | Block-padding (top + bottom) of the element. Optional. |
20
20
 
21
21
  ## Returns
22
22
 
@@ -3,12 +3,12 @@
3
3
  - Kind: function
4
4
  - Import: `import { getScrollClass } from "shelving/ui";`
5
5
 
6
- Get the scroll class for a component from its `horizontal` / `vertical` variant props.
6
+ Get the scroll class for a component from its `horizontal`, `vertical`, `cover` and `reverse` variant props.
7
7
 
8
8
  ## Signatures
9
9
 
10
10
  ```ts
11
- getScrollClass({ horizontal, vertical }: ScrollVariants): string
11
+ getScrollClass({ horizontal, vertical, cover, reverse }: ScrollVariants): string
12
12
  ```
13
13
 
14
14
  ## Parameters
@@ -18,6 +18,8 @@ getScrollClass({ horizontal, vertical }: ScrollVariants): string
18
18
  | `options` | `ScrollVariants` | |
19
19
  | `.vertical` | `boolean \| undefined` | Vertical scrolling (defaults to `false`). Optional. |
20
20
  | `.horizontal` | `boolean \| undefined` | Horizontal scrolling (defaults to `false`). Optional. |
21
+ | `.cover` | `boolean \| undefined` | Cover the nearest positioned ancestor (`position: absolute; inset: 0`), for example a layout's content slot (defaults to `false`). Optional. |
22
+ | `.reverse` | `boolean \| undefined` | Start at the end and stay there as the content grows, for example a chat (defaults to `false`). Put the content in one child. Optional. |
21
23
 
22
24
  ## Returns
23
25
 
@@ -9,6 +9,8 @@ The `space` variant prop sets a block-level element's `margin-block` (top + bott
9
9
 
10
10
  `getSpaceClass({ space })` maps the prop to a margin class (e.g. `space="large"` → `large`). The same scale also backs `getPaddingClass()` (block padding), `getIndentClass()` (inline padding), and `getGapClass()`, so they all move together when you change `--space-normal`.
11
11
 
12
+ `space="auto"` sets `margin-block: auto`. In a flex or grid container, such as a `<Column>`, the auto margins take the free space, so the block sits in the middle (it still keeps auto margins as a first or last child). In normal block flow they do nothing: to centre a block vertically there, use `height="full" middle` (see `getHeightClass()`). `padding` and `gap` have no `auto`.
13
+
12
14
  Alongside the named scale, `space`, `padding`, and `indent` also accept numeric multiples of `--space-normal` — `1x` … `10x` (e.g. `padding="5x"` → `calc(var(--space-normal) * 5)`) — for larger one-off blocks like hero panels.
13
15
 
14
16
  ## Theme variables
package/docs/ui.md CHANGED
@@ -62,7 +62,7 @@ The components below are listed in the index following this page; this is the sh
62
62
 
63
63
  **Content.** Block-level structure starts with `<Card>`, `<Section>`, and the `<Heading>` / `<Title>` family, with `<Table>`, `<List>`, and `<Figure>` for specific shapes; wrap longform copy in `<Prose>`. Inline pieces — `<Link>`, `<Code>`, `<Strong>`, `<Mark>` — live inside that block content. To render a Markdown string as components, use `<Markup>`.
64
64
 
65
- **Structure.** Mount a client app with `<App>`, or render a full server document with `<HTML>` and `<Page>`. Arrange the screen with `<CenteredLayout>` or `<SidebarLayout>`, and drive URLs with `<Navigation>` and `<Router>`.
65
+ **Structure.** Mount a client app with `<App>`, or render a full server document with `<HTML>` and `<Page>`. Arrange the screen with `<AppLayout>`, `<SidebarLayout>` or `<FixedLayout>`, and drive URLs with `<Navigation>` and `<Router>`. A layout is a frame: it sits above the router, and the app fills its content slot with `<RouteCache>` and `<Scroll>`. See "Composing an app" on `<App>`.
66
66
 
67
67
  **Interaction.** Forms start at `<Form>`, which wires `<Field>` and the typed inputs to a `FormStore`; `<Button>` is the standalone action. Overlays are `<Dialog>` and `<Modal>`; navigation menus are `<Menu>` and `<MenuItem>`; transient feedback is `<Notice>` (and the global `<Notices>` list); animate enter/leave with `<Transition>`.
68
68
 
@@ -176,14 +176,15 @@ The components below are listed in the index following this page; this is the sh
176
176
  - [DataSchemaInput](ui/DataSchemaInput.md): Show a DataInput for a nested DataSchema.
177
177
  - [SchemaField](ui/SchemaField.md): Show the appropriate input for a schema, wrapped in a <Field> with its label and message.
178
178
  - [SelectInput](ui/SelectInput.md): Dropdown input bound to a string value, rendered as a <select> of the provided options.
179
- - [CenteredLayout](ui/CenteredLayout.md): Layout that centres its content with no header/footer and a narrow max-width.
180
- - [SidebarLayout](ui/SidebarLayout.md): Layout with a fixed-width side column (typically navigation) next to a scrollable main content column.
179
+ - [AppLayout](ui/AppLayout.md): Layout with a content slot above a bar of the app's main sections, like the tab bar of a phone app.
180
+ - [FixedLayout](ui/FixedLayout.md): Layout with no chrome: the whole screen is one content slot.
181
+ - [SidebarLayout](ui/SidebarLayout.md): Layout with a fixed-width side column (typically navigation) next to a content slot.
181
182
  - [Menu](ui/Menu.md): A <menu> list of <MenuItem> children.
182
183
  - [MenuItem](ui/MenuItem.md): A <li> containing an <a> link, plus optional submenu content shown when this item is "proud".
183
184
  - [Catcher](ui/Catcher.md): React error boundary that renders a fallback component when any descendant throws.
184
185
  - [ErrorNotice](ui/ErrorNotice.md): Render a caught error as an inline <Notice> with a retry button.
185
186
  - [PageCatcher](ui/PageCatcher.md): Error boundary for a whole page that renders a full <ErrorPage> fallback on error.
186
- - [ErrorPage](ui/ErrorPage.md): Render a caught error as a full-page <Page> with a centered <ErrorNotice>.
187
+ - [ErrorPage](ui/ErrorPage.md): Render a caught error as a <Page> with an <ErrorNotice> in a narrow column, centred in the middle of the screen.
187
188
  - [Icon](ui/Icon.md): Render the icon for a given status, coloured to match.
188
189
  - [Loader](ui/Loader.md): Load a component.
189
190
  - [PageLoader](ui/PageLoader.md): Load a page.
@@ -198,7 +199,7 @@ The components below are listed in the index following this page; this is the sh
198
199
  - [Page](ui/Page.md): Wrap a single page (or screen) within an app, applying its meta and head tags.
199
200
  - [BackButton](ui/BackButton.md): Back button for the current stack.
200
201
  - [Navigation](ui/Navigation.md): Top-level navigation provider, with one stack of pages for each tab.
201
- - [RouteCache](ui/RouteCache.md): Keep-alive page cache for the pages in the navigation stacks. Drop it into a layout around its scrolling content region.
202
+ - [RouteCache](ui/RouteCache.md): 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.
202
203
  - [Router](ui/Router.md): Match the current URL against routes and render the matched element.
203
204
  - [StackButton](ui/StackButton.md): Button for one stack in a tab bar.
204
205
  - [Scroll](ui/Scroll.md): Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
@@ -271,10 +272,11 @@ The components below are listed in the index following this page; this is the sh
271
272
  - [getFlexClass()](ui/getFlexClass.md): Get the flex layout class for a component from its flex variant props.
272
273
  - [getGapClass()](ui/getGapClass.md): Get the gap class for a component from its gap variant prop.
273
274
  - [getGridClass()](ui/getGridClass.md): Get the grid layout class for a component from its grid variant props.
275
+ - [getHeightClass()](ui/getHeightClass.md): Get the height class for a component from its height, top, middle and bottom variant props.
274
276
  - [getIndentClass()](ui/getIndentClass.md): Get the inline-padding ("indent") class for a component from its indent variant prop.
275
277
  - [getPaddingClass()](ui/getPaddingClass.md): Get the block-padding class for a component from its padding variant prop.
276
278
  - [getRadiusClass()](ui/getRadiusClass.md): Get the corner-radius class for a component from its radius variant prop.
277
- - [getScrollClass()](ui/getScrollClass.md): Get the scroll class for a component from its horizontal / vertical variant props.
279
+ - [getScrollClass()](ui/getScrollClass.md): Get the scroll class for a component from its horizontal, vertical, cover and reverse variant props.
278
280
  - [getShadowClass()](ui/getShadowClass.md): Get the drop-shadow class for a component from its shadow variant prop.
279
281
  - [getSpaceClass()](ui/getSpaceClass.md): Get the block spacing class for a component from its space="" variant prop.
280
282
  - [getStatusClass()](ui/getStatusClass.md): Get the status tint class for a component from its status variant prop.
@@ -436,7 +438,8 @@ The components below are listed in the index following this page; this is the sh
436
438
  - [SelectProps](ui/SelectProps.md): Props for SelectInput, a dropdown <select> bound to a string value.
437
439
  - [TextareaInputProps](ui/TextareaInputProps.md): Props for TextareaInput, a multiline text input bound to a string value.
438
440
  - [TextInputProps](ui/TextInputProps.md): Props for TextInput, a single-line text input bound to a string value.
439
- - [CenteredLayoutProps](ui/CenteredLayoutProps.md): Props for <CenteredLayout> — optional children plus width (of the centred column) and padding / indent (block / inline padding of the scroll area) variants.
441
+ - [AppLayoutProps](ui/AppLayoutProps.md): Props for <AppLayout>: the nav bar content and the content slot children.
442
+ - [FixedLayoutProps](ui/FixedLayoutProps.md): Props for <FixedLayout>: the content slot children.
440
443
  - [SidebarLayoutProps](ui/SidebarLayoutProps.md): Props for <SidebarLayout> — the sidebar column content, main children, and a right placement flag.
441
444
  - [MenuProps](ui/MenuProps.md): Props for <Menu> — optional <MenuItem> children.
442
445
  - [MenuItemProps](ui/MenuItemProps.md): Props for <MenuItem> — <Clickable> props plus children whose first node is the label and the rest the submenu.
@@ -469,10 +472,11 @@ The components below are listed in the index following this page; this is the sh
469
472
  - [FlexVariants](ui/FlexVariants.md): Variant props for flex layout — opt-in modifiers any component can mix in via getFlexClass().
470
473
  - [GapVariants](ui/GapVariants.md): Variant props for the gap between a component's children, e.g. gap="large".
471
474
  - [GridVariants](ui/GridVariants.md): Variant props for grid layout, e.g. columns={3} gap="normal".
475
+ - [HeightVariants](ui/HeightVariants.md): Variant props that set a component's height, and where its content sits inside that height, e.g. height="full" middle.
472
476
  - [IndentVariants](ui/IndentVariants.md): Variant props for the inline-padding ("indent", left + right) of a component, e.g. indent="normal".
473
477
  - [PaddingVariants](ui/PaddingVariants.md): Variant props for the block-padding (top + bottom) of a component, e.g. padding="large".
474
478
  - [RadiusVariants](ui/RadiusVariants.md): Variant props for the corner radius of an element, e.g. radius="large".
475
- - [ScrollVariants](ui/ScrollVariants.md): Variant props selecting which scroll axes are enabled on an element.
479
+ - [ScrollVariants](ui/ScrollVariants.md): Variant props for a scroll region: which axes scroll, plus cover and reverse.
476
480
  - [ScrollComponentProps](ui/ScrollComponentProps.md): Props for the Scroll component — children plus scroll-axis variants.
477
481
  - [ShadowVariants](ui/ShadowVariants.md): Variant props for the drop shadow of an element, e.g. shadow="large".
478
482
  - [SpaceVariants](ui/SpaceVariants.md): Variants to control block spacing on components, e.g. space="large".
@@ -521,6 +525,7 @@ The components below are listed in the index following this page; this is the sh
521
525
  - [ColorVariant](ui/ColorVariant.md): Enumerated colour names selectable via the color="purple" prop for components that support that support ColorVariants
522
526
  - [DurationValue](ui/DurationValue.md): Allowed values for transition timing for components that support DurationVariants
523
527
  - [ColumnsVariant](ui/ColumnsVariant.md): Number of equal-width columns selectable via the columns variant prop.
528
+ - [HeightVariant](ui/HeightVariant.md): Enumerated height selectable via the height variant prop.
524
529
  - [IndentVariant](ui/IndentVariant.md): Allowed values for inline-padding ("indent") for components that support IndentVariants
525
530
  - [RadiusVariant](ui/RadiusVariant.md): Allowed values for border radius for components that support RadiusVariants
526
531
  - [ShadowVariant](ui/ShadowVariant.md): Enumerated drop-shadow scale selectable via the shadow="normal" variant prop.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.321.0",
3
+ "version": "1.322.1",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
package/ui/README.md CHANGED
@@ -59,7 +59,7 @@ The components below are listed in the index following this page; this is the sh
59
59
 
60
60
  **Content.** Block-level structure starts with `<Card>`, `<Section>`, and the `<Heading>` / `<Title>` family, with `<Table>`, `<List>`, and `<Figure>` for specific shapes; wrap longform copy in `<Prose>`. Inline pieces — `<Link>`, `<Code>`, `<Strong>`, `<Mark>` — live inside that block content. To render a Markdown string as components, use `<Markup>`.
61
61
 
62
- **Structure.** Mount a client app with `<App>`, or render a full server document with `<HTML>` and `<Page>`. Arrange the screen with `<CenteredLayout>` or `<SidebarLayout>`, and drive URLs with `<Navigation>` and `<Router>`.
62
+ **Structure.** Mount a client app with `<App>`, or render a full server document with `<HTML>` and `<Page>`. Arrange the screen with `<AppLayout>`, `<SidebarLayout>` or `<FixedLayout>`, and drive URLs with `<Navigation>` and `<Router>`. A layout is a frame: it sits above the router, and the app fills its content slot with `<RouteCache>` and `<Scroll>`. See "Composing an app" on `<App>`.
63
63
 
64
64
  **Interaction.** Forms start at `<Form>`, which wires `<Field>` and the typed inputs to a `FormStore`; `<Button>` is the standalone action. Overlays are `<Dialog>` and `<Modal>`; navigation menus are `<Menu>` and `<MenuItem>`; transient feedback is `<Notice>` (and the global `<Notices>` list); animate enter/leave with `<Transition>`.
65
65
 
package/ui/app/App.md CHANGED
@@ -9,17 +9,19 @@ Use `<App>` when mounting into an existing HTML page on the client. For server-s
9
9
  The smallest single-screen app — `<App>` wraps a layout and some content:
10
10
 
11
11
  ```tsx
12
- import { App, CenteredLayout, Section, Title, Paragraph } from "shelving/ui";
12
+ import { App, FixedLayout, Paragraph, Scroll, Section, Title } from "shelving/ui";
13
13
 
14
14
  function HelloApp() {
15
15
  return (
16
16
  <App app="My app">
17
- <CenteredLayout>
18
- <Section width="narrow">
19
- <Title>Hello</Title>
20
- <Paragraph>Welcome to the app.</Paragraph>
21
- </Section>
22
- </CenteredLayout>
17
+ <FixedLayout>
18
+ <Scroll vertical cover>
19
+ <Section width="narrow">
20
+ <Title>Hello</Title>
21
+ <Paragraph>Welcome to the app.</Paragraph>
22
+ </Section>
23
+ </Scroll>
24
+ </FixedLayout>
23
25
  </App>
24
26
  );
25
27
  }
@@ -50,4 +52,100 @@ export function MyApp() {
50
52
 
51
53
  `<App>` accepts all `PossibleMeta` props (`app`, `root`, `url`, `title`, `language`, `tags`, etc.) and merges them into the context it provides to children. On mount it adds the theme class to `document.body`, which activates the CSS custom property tokens defined in `App.module.css`; on unmount it removes it.
52
54
 
55
+ ## Composing an app
56
+
57
+ An app is built from layers, each with one job. Write them in plain sight in `App.tsx`, from the outside in:
58
+
59
+ 1. **Contexts**: `<App>`, your data contexts, `<Navigation>`, `<DialogsContext>`.
60
+ 2. **App-level catcher**: a last resort, outside every layout.
61
+ 3. **Layout picker**: your own component that picks the layout (and its props) from the session, the path, or any other state.
62
+ 4. **Layout**: `<AppLayout>`, `<SidebarLayout>` or `<FixedLayout>`. It draws the chrome (tab bar, sidebar) and gives a content slot. It knows nothing about the cache.
63
+ 5. **Content**: transition, then `<RouteCache>`, then `<Scroll vertical cover>`, then `<PageLoader>`, then `<Router>`. Put it in a small component of your own, and reuse it in each layout.
64
+ 6. **Page**: `<Page>` with its title, then the page content. A page renders no layout.
65
+
66
+ Nesting rules:
67
+
68
+ - The layout sits **above** the router. A page, an error page or a loading state never renders a layout.
69
+ - The transition goes **around** `<RouteCache>`, not inside it.
70
+ - `<Scroll vertical cover>` goes **inside** `<RouteCache>`, so each page keeps its own scroll.
71
+ - Chrome that keeps state or animates (a tab bar, a sidebar) stays in the layout, **outside** the cache.
72
+ - All pages in one stack must share one layout, because they share one `<RouteCache>`. To change the chrome for some pages (hide the tab bar), change a layout prop from the picker, for example `nav={false}`. Swap to another layout only between sections you do not move back and forth in, such as log-in and the main app.
73
+
74
+ ```tsx
75
+ import { useStore } from "shelving/react";
76
+ import {
77
+ App, AppLayout, Catcher, DialogsContext, Dialogs, ErrorPage, FixedLayout, HorizontalTransition,
78
+ Navigation, Notices, PageLoader, requireMetaURL, RouteCache, Router, type ErrorProps, type Routes,
79
+ Scroll, StackButton,
80
+ } from "shelving/ui";
81
+
82
+ const STACKS = ["/home", "/discover", "/profile"] as const;
83
+
84
+ /** 1–2. Contexts and the app-level catcher. No layout here. */
85
+ export function MyApp() {
86
+ const session = useStore(SESSION).value;
87
+ return (
88
+ <App key={session?.id ?? "out"} app="My app" root="https://example.com/">
89
+ <Navigation stacks={STACKS} stack="/home">
90
+ <DialogsContext>
91
+ <Catcher as={AppError}>
92
+ <Shell signedIn={!!session} />
93
+ </Catcher>
94
+ <Dialogs />
95
+ <Notices />
96
+ </DialogsContext>
97
+ </Navigation>
98
+ </App>
99
+ );
100
+ }
101
+
102
+ /** 3–4. Pick the layout. Plain React, so any rule works. */
103
+ function Shell({ signedIn }: { signedIn: boolean }) {
104
+ const { path } = requireMetaURL();
105
+ if (!signedIn) return <FixedLayout><Content routes={LOGIN_ROUTES} /></FixedLayout>;
106
+ return (
107
+ <AppLayout nav={path.startsWith("/squad/") ? false : <StackBar />}>
108
+ <Content routes={ROUTES} />
109
+ </AppLayout>
110
+ );
111
+ }
112
+
113
+ /** 5. The content of a layout's slot. */
114
+ function Content({ routes }: { routes: Routes }) {
115
+ return (
116
+ <HorizontalTransition>
117
+ <RouteCache>
118
+ <Scroll vertical cover>
119
+ <PageLoader>
120
+ <Router routes={routes} />
121
+ </PageLoader>
122
+ </Scroll>
123
+ </RouteCache>
124
+ </HorizontalTransition>
125
+ );
126
+ }
127
+
128
+ /** The tab bar, in the layout, outside the cache. */
129
+ function StackBar() {
130
+ return <>
131
+ <StackButton stack="/home" title="Home"><HomeIcon /></StackButton>
132
+ <StackButton stack="/discover" title="Discover"><SearchIcon /></StackButton>
133
+ <StackButton stack="/profile" title="Profile"><ProfileIcon /></StackButton>
134
+ </>;
135
+ }
136
+
137
+ /** An error outside every layout: the app picks one here. */
138
+ function AppError({ reason }: ErrorProps) {
139
+ return (
140
+ <FixedLayout>
141
+ <Scroll vertical cover>
142
+ <ErrorPage reason={reason} />
143
+ </Scroll>
144
+ </FixedLayout>
145
+ );
146
+ }
147
+ ```
148
+
149
+ Layouts are optional. With no layout, the document body scrolls, which is fine for a simple site. Use a layout when the app scrolls inside its own boxes: it locks the body and gives a content slot. Every layout is a frame: none of them scroll or centre. A page centres its own content, for example with `<Block height="full" middle width="narrow">`.
150
+
53
151
  For a documentation site, hand an extracted tree to `<TreeApp>` instead — see the `shelving/extract` guide.
@@ -16,7 +16,9 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
16
16
  - A change inside an open dialog (new content, a Suspense reveal) runs no view transition, so the dialog never ignores a tap while its content changes. The page ignores taps while a view transition runs.
17
17
  - `Dialog` knows nothing about transitions. React runs a view transition only for an update made inside `startTransition()`, so the code that mounts and unmounts the dialog decides if it animates:
18
18
  - `<Dialogs>` renders a `DialogsStore` inside transitions, so a dialog opened with `DialogsStore.show()` animates in and out for you.
19
- - A `Dialog` you mount yourself appears and goes at once, unless you set the state that mounts and unmounts it inside `startTransition()`. See the declarative example below.
19
+ - A `Dialog` you mount yourself appears and goes at once, unless you set the React state that mounts and unmounts it inside `startTransition()`. See the declarative example below.
20
+ - A `Dialog` you mount from a store read with `useStore()` never animates. `useStore()` applies each change at once, so `startTransition()` around the store write does not help.
21
+ - To open a dialog from app code, use `requireDialogs()` and `DialogsStore.show()`. Pass the `DialogsStore` into any function that opens one.
20
22
  - A browser without view transitions shows and hides the dialog at once.
21
23
  - Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
22
24
 
@@ -57,6 +57,10 @@ export declare function DialogsContext({ children }: DialogsContextProps): React
57
57
  /**
58
58
  * Render the open dialogs from the current `DialogsContext`.
59
59
  *
60
+ * - It renders the list inside a transition, so each dialog animates in and out.
61
+ * - To open a dialog, use `requireDialogs()` and `DialogsStore.show()`. Pass the `DialogsStore` into any function that opens one.
62
+ * - A `<Dialog>` you render from `useStore()` never animates, even if you write the store inside `startTransition()`.
63
+ *
60
64
  * @kind component
61
65
  * @see https://shelving.cc/ui/Dialogs
62
66
  */