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
@@ -0,0 +1,88 @@
1
+ @import url("layers.css");
2
+ @import url("Space.module.css");
3
+
4
+ @layer variants {
5
+ /* Every height is a minimum, so the element grows when its content is taller and nothing is cut off. */
6
+ .height {
7
+ min-block-size: var(--height);
8
+ }
9
+
10
+ /* At least the full height of the container (for example a layout's scroll box). */
11
+ .height-full {
12
+ --height: 100%;
13
+ }
14
+
15
+ /* Numeric heights — multiples of `--space-normal` (no `--height-*` tokens; calculated directly). */
16
+ .height-1x {
17
+ --height: calc(1 * var(--space-normal));
18
+ }
19
+
20
+ .height-2x {
21
+ --height: calc(2 * var(--space-normal));
22
+ }
23
+
24
+ .height-3x {
25
+ --height: calc(3 * var(--space-normal));
26
+ }
27
+
28
+ .height-4x {
29
+ --height: calc(4 * var(--space-normal));
30
+ }
31
+
32
+ .height-5x {
33
+ --height: calc(5 * var(--space-normal));
34
+ }
35
+
36
+ .height-6x {
37
+ --height: calc(6 * var(--space-normal));
38
+ }
39
+
40
+ .height-7x {
41
+ --height: calc(7 * var(--space-normal));
42
+ }
43
+
44
+ .height-8x {
45
+ --height: calc(8 * var(--space-normal));
46
+ }
47
+
48
+ .height-10x {
49
+ --height: calc(10 * var(--space-normal));
50
+ }
51
+
52
+ .height-12x {
53
+ --height: calc(12 * var(--space-normal));
54
+ }
55
+
56
+ .height-16x {
57
+ --height: calc(16 * var(--space-normal));
58
+ }
59
+
60
+ .height-20x {
61
+ --height: calc(20 * var(--space-normal));
62
+ }
63
+
64
+ .height-24x {
65
+ --height: calc(24 * var(--space-normal));
66
+ }
67
+
68
+ .height-28x {
69
+ --height: calc(28 * var(--space-normal));
70
+ }
71
+
72
+ .height-32x {
73
+ --height: calc(32 * var(--space-normal));
74
+ }
75
+
76
+ /* Where the content sits inside the height. `align-content` works on a plain block box, so the element keeps its own `display`. On flex boxes such as `<Row>` and `<Column>`, the flex variants with the same names align the items. */
77
+ .top {
78
+ align-content: start;
79
+ }
80
+
81
+ .middle {
82
+ align-content: center;
83
+ }
84
+
85
+ .bottom {
86
+ align-content: end;
87
+ }
88
+ }
@@ -0,0 +1,61 @@
1
+ import { getClass, getModuleClass } from "../util/css.js";
2
+ import HEIGHT_CSS from "./Height.module.css";
3
+
4
+ /**
5
+ * Enumerated height selectable via the `height` variant prop.
6
+ * - `full` — at least the full height of the container.
7
+ * - `1x`–`32x` — at least a multiple of `--space-normal` (1x–8x at 1x intervals, then 10x/12x, then 16x–32x at 4x intervals).
8
+ * - Each value is a minimum (`min-block-size`), so the element grows when its content is taller and nothing is cut off.
9
+ *
10
+ * @see https://shelving.cc/ui/HeightVariant
11
+ */
12
+ export type HeightVariant =
13
+ | "full"
14
+ | "1x"
15
+ | "2x"
16
+ | "3x"
17
+ | "4x"
18
+ | "5x"
19
+ | "6x"
20
+ | "7x"
21
+ | "8x"
22
+ | "10x"
23
+ | "12x"
24
+ | "16x"
25
+ | "20x"
26
+ | "24x"
27
+ | "28x"
28
+ | "32x";
29
+
30
+ /**
31
+ * Variant props that set a component's height, and where its content sits inside that height, e.g. `height="full" middle`.
32
+ *
33
+ * @see https://shelving.cc/ui/HeightVariants
34
+ */
35
+ export interface HeightVariants {
36
+ /** Height of the element. It is a minimum, so the element grows when its content is taller. */
37
+ height?: HeightVariant | undefined;
38
+ /** Put the content at the top of the element (the default). */
39
+ top?: boolean | undefined;
40
+ /** Put the content in the vertical middle of the element. Use with `height`. */
41
+ middle?: boolean | undefined;
42
+ /** Put the content at the bottom of the element. Use with `height`. */
43
+ bottom?: boolean | undefined;
44
+ }
45
+
46
+ /**
47
+ * Get the height class for a component from its `height`, `top`, `middle` and `bottom` variant props.
48
+ *
49
+ * @returns The height class string, or `undefined` if no height variants are set.
50
+ * @example getHeightClass({ height: "full", middle: true }) // "height height-full middle"
51
+ * @see https://shelving.cc/ui/getHeightClass
52
+ */
53
+ export function getHeightClass({ height, top, middle, bottom }: HeightVariants): string | undefined {
54
+ if (height || top || middle || bottom)
55
+ return getClass(
56
+ height && getModuleClass(HEIGHT_CSS, "height", `height-${height}`),
57
+ top && getModuleClass(HEIGHT_CSS, "top"),
58
+ middle && getModuleClass(HEIGHT_CSS, "middle"),
59
+ bottom && getModuleClass(HEIGHT_CSS, "bottom"),
60
+ );
61
+ }
@@ -6,7 +6,7 @@ import type { SpaceValue } from "./Space.js";
6
6
  */
7
7
  export interface PaddingVariants {
8
8
  /** Block-padding (top + bottom) of the element. */
9
- padding?: SpaceValue | undefined;
9
+ padding?: Exclude<SpaceValue, "auto"> | undefined;
10
10
  }
11
11
  /**
12
12
  * Get the block-padding class for a component from its `padding` variant prop.
@@ -9,7 +9,7 @@ import type { SpaceValue } from "./Space.js";
9
9
  */
10
10
  export interface PaddingVariants {
11
11
  /** Block-padding (top + bottom) of the element. */
12
- padding?: SpaceValue | undefined;
12
+ padding?: Exclude<SpaceValue, "auto"> | undefined;
13
13
  }
14
14
 
15
15
  /**
@@ -1,24 +1,28 @@
1
1
  import type { ReactElement } from "react";
2
2
  import type { ChildProps } from "../util/index.js";
3
3
  /**
4
- * Variant props selecting which scroll axes are enabled on an element.
4
+ * Variant props for a scroll region: which axes scroll, plus `cover` and `reverse`.
5
5
  *
6
- * @see https://shelving.cc/ui/ScrollProps
6
+ * @see https://shelving.cc/ui/ScrollVariants
7
7
  */
8
8
  export interface ScrollVariants {
9
9
  /** Vertical scrolling (defaults to `false`). */
10
10
  vertical?: boolean | undefined;
11
11
  /** Horizontal scrolling (defaults to `false`). */
12
12
  horizontal?: boolean | undefined;
13
+ /** Cover the nearest positioned ancestor (`position: absolute; inset: 0`), for example a layout's content slot (defaults to `false`). */
14
+ cover?: boolean | undefined;
15
+ /** Start at the end and stay there as the content grows, for example a chat (defaults to `false`). Put the content in one child. */
16
+ reverse?: boolean | undefined;
13
17
  }
14
18
  /**
15
- * Get the scroll class for a component from its `horizontal` / `vertical` variant props.
19
+ * Get the scroll class for a component from its `horizontal`, `vertical`, `cover` and `reverse` variant props.
16
20
  *
17
21
  * @returns The combined scroll class string (empty when neither axis is enabled).
18
22
  * @example getScrollClass({ horizontal: true }) // "horizontal"
19
23
  * @see https://shelving.cc/ui/getScrollClass
20
24
  */
21
- export declare function getScrollClass({ horizontal, vertical }: ScrollVariants): string;
25
+ export declare function getScrollClass({ horizontal, vertical, cover, reverse }: ScrollVariants): string;
22
26
  /**
23
27
  * Props for the `Scroll` component — children plus scroll-axis variants.
24
28
  *
@@ -28,10 +32,10 @@ export interface ScrollComponentProps extends ChildProps, ScrollVariants {
28
32
  }
29
33
  /**
30
34
  * Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
35
+ * - With `cover`, it fills a layout's content slot, so each page in a `<RouteCache>` scrolls in its own box.
31
36
  *
32
37
  * @returns A `<div>` element with the computed scroll class.
33
38
  * @kind component
34
- * @example <Scroll horizontal>{wideContent}</Scroll>
35
39
  * @see https://shelving.cc/ui/Scroll
36
40
  */
37
41
  export declare function Scroll({ children, ...props }: ScrollComponentProps): ReactElement;
@@ -3,23 +3,25 @@ import { getClass, getModuleClass } from "../util/css.js";
3
3
  import SCROLLABLE_CSS from "./Scroll.module.css";
4
4
  const SCROLL_HORIZONTAL_CLASS = getModuleClass(SCROLLABLE_CSS, "horizontal");
5
5
  const SCROLL_VERTICAL_CLASS = getModuleClass(SCROLLABLE_CSS, "vertical");
6
+ const SCROLL_COVER_CLASS = getModuleClass(SCROLLABLE_CSS, "cover");
7
+ const SCROLL_REVERSE_CLASS = getModuleClass(SCROLLABLE_CSS, "reverse");
6
8
  /**
7
- * Get the scroll class for a component from its `horizontal` / `vertical` variant props.
9
+ * Get the scroll class for a component from its `horizontal`, `vertical`, `cover` and `reverse` variant props.
8
10
  *
9
11
  * @returns The combined scroll class string (empty when neither axis is enabled).
10
12
  * @example getScrollClass({ horizontal: true }) // "horizontal"
11
13
  * @see https://shelving.cc/ui/getScrollClass
12
14
  */
13
- export function getScrollClass({ horizontal, vertical }) {
15
+ export function getScrollClass({ horizontal, vertical, cover, reverse }) {
14
16
  return getClass(horizontal && SCROLL_HORIZONTAL_CLASS, //
15
- vertical && SCROLL_VERTICAL_CLASS);
17
+ vertical && SCROLL_VERTICAL_CLASS, cover && SCROLL_COVER_CLASS, reverse && SCROLL_REVERSE_CLASS);
16
18
  }
17
19
  /**
18
20
  * Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
21
+ * - With `cover`, it fills a layout's content slot, so each page in a `<RouteCache>` scrolls in its own box.
19
22
  *
20
23
  * @returns A `<div>` element with the computed scroll class.
21
24
  * @kind component
22
- * @example <Scroll horizontal>{wideContent}</Scroll>
23
25
  * @see https://shelving.cc/ui/Scroll
24
26
  */
25
27
  export function Scroll({ children, ...props }) {
@@ -0,0 +1,59 @@
1
+ # Scroll
2
+
3
+ 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.
4
+
5
+ **Things to know:**
6
+
7
+ - Set `vertical`, `horizontal`, or both. With neither, the box clips its content and does not scroll.
8
+ - 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.
9
+ - 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.
10
+ - Overscroll stops at the box edge (`overscroll-behavior: none`), so a scroll inside the box never scrolls the page behind it.
11
+ - When the box has keyboard focus, it shows a focus outline.
12
+
13
+ ## Usage
14
+
15
+ ### A wide table
16
+
17
+ ```tsx
18
+ import { Scroll, Table } from "shelving/ui";
19
+
20
+ <Scroll horizontal>
21
+ <Table>…</Table>
22
+ </Scroll>
23
+ ```
24
+
25
+ ### A scroll box for each page
26
+
27
+ 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.
28
+
29
+ ```tsx
30
+ import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
31
+
32
+ <AppLayout nav={<StackBar />}>
33
+ <HorizontalTransition>
34
+ <RouteCache>
35
+ <Scroll vertical cover>
36
+ <PageLoader>
37
+ <Router routes={ROUTES} />
38
+ </PageLoader>
39
+ </Scroll>
40
+ </RouteCache>
41
+ </HorizontalTransition>
42
+ </AppLayout>
43
+ ```
44
+
45
+ ### A chat
46
+
47
+ ```tsx
48
+ <Scroll vertical cover reverse>
49
+ <div>{messages}</div>
50
+ </Scroll>
51
+ ```
52
+
53
+ ## Styling
54
+
55
+ | Variable | Styles | Default |
56
+ |---|---|---|
57
+ | `--scroll-focus-border` | Outline when the box has keyboard focus | `var(--stroke-focus) solid var(--color-focus)` |
58
+
59
+ **Global tokens it reads** — `--stroke-focus`, `--stroke-normal`, and `--color-focus`.
@@ -18,7 +18,7 @@
18
18
  .horizontal,
19
19
  .vertical {
20
20
  /* Style */
21
- outline: var(--scrollable-focus-border, var(--stroke-focus) solid var(--color-focus));
21
+ outline: var(--scroll-focus-border, var(--stroke-focus) solid var(--color-focus));
22
22
  outline-offset: calc(0px - var(--stroke-normal));
23
23
 
24
24
  &:not(:focus-visible) {
@@ -39,4 +39,16 @@
39
39
  overflow-x: auto;
40
40
  overscroll-behavior-x: none;
41
41
  }
42
+
43
+ /* Cover the nearest positioned ancestor (for example a layout's content slot), so the region scrolls inside that box. */
44
+ .cover {
45
+ position: absolute;
46
+ inset: 0;
47
+ }
48
+
49
+ /* Start at the end and stay there when the content grows (for example a chat). Only the scroll is reversed: the content keeps its own order inside its one child. */
50
+ .reverse {
51
+ display: flex;
52
+ flex-direction: column-reverse;
53
+ }
42
54
  }
@@ -5,30 +5,38 @@ import SCROLLABLE_CSS from "./Scroll.module.css";
5
5
 
6
6
  const SCROLL_HORIZONTAL_CLASS = getModuleClass(SCROLLABLE_CSS, "horizontal");
7
7
  const SCROLL_VERTICAL_CLASS = getModuleClass(SCROLLABLE_CSS, "vertical");
8
+ const SCROLL_COVER_CLASS = getModuleClass(SCROLLABLE_CSS, "cover");
9
+ const SCROLL_REVERSE_CLASS = getModuleClass(SCROLLABLE_CSS, "reverse");
8
10
 
9
11
  /**
10
- * Variant props selecting which scroll axes are enabled on an element.
12
+ * Variant props for a scroll region: which axes scroll, plus `cover` and `reverse`.
11
13
  *
12
- * @see https://shelving.cc/ui/ScrollProps
14
+ * @see https://shelving.cc/ui/ScrollVariants
13
15
  */
14
16
  export interface ScrollVariants {
15
17
  /** Vertical scrolling (defaults to `false`). */
16
18
  vertical?: boolean | undefined;
17
19
  /** Horizontal scrolling (defaults to `false`). */
18
20
  horizontal?: boolean | undefined;
21
+ /** Cover the nearest positioned ancestor (`position: absolute; inset: 0`), for example a layout's content slot (defaults to `false`). */
22
+ cover?: boolean | undefined;
23
+ /** Start at the end and stay there as the content grows, for example a chat (defaults to `false`). Put the content in one child. */
24
+ reverse?: boolean | undefined;
19
25
  }
20
26
 
21
27
  /**
22
- * Get the scroll class for a component from its `horizontal` / `vertical` variant props.
28
+ * Get the scroll class for a component from its `horizontal`, `vertical`, `cover` and `reverse` variant props.
23
29
  *
24
30
  * @returns The combined scroll class string (empty when neither axis is enabled).
25
31
  * @example getScrollClass({ horizontal: true }) // "horizontal"
26
32
  * @see https://shelving.cc/ui/getScrollClass
27
33
  */
28
- export function getScrollClass({ horizontal, vertical }: ScrollVariants): string {
34
+ export function getScrollClass({ horizontal, vertical, cover, reverse }: ScrollVariants): string {
29
35
  return getClass(
30
36
  horizontal && SCROLL_HORIZONTAL_CLASS, //
31
37
  vertical && SCROLL_VERTICAL_CLASS,
38
+ cover && SCROLL_COVER_CLASS,
39
+ reverse && SCROLL_REVERSE_CLASS,
32
40
  );
33
41
  }
34
42
 
@@ -41,10 +49,10 @@ export interface ScrollComponentProps extends ChildProps, ScrollVariants {}
41
49
 
42
50
  /**
43
51
  * Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
52
+ * - With `cover`, it fills a layout's content slot, so each page in a `<RouteCache>` scrolls in its own box.
44
53
  *
45
54
  * @returns A `<div>` element with the computed scroll class.
46
55
  * @kind component
47
- * @example <Scroll horizontal>{wideContent}</Scroll>
48
56
  * @see https://shelving.cc/ui/Scroll
49
57
  */
50
58
  export function Scroll({ children, ...props }: ScrollComponentProps): ReactElement {
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * @see https://shelving.cc/ui/SpaceValue
5
5
  */
6
- export type SpaceValue = "section" | "paragraph" | "none" | "xxsmall" | "xsmall" | "small" | "normal" | "large" | "xlarge" | "xxlarge" | "1x" | "2x" | "3x" | "4x" | "5x" | "6x" | "7x" | "8x" | "9x" | "10x";
6
+ export type SpaceValue = "section" | "paragraph" | "none" | "auto" | "xxsmall" | "xsmall" | "small" | "normal" | "large" | "xlarge" | "xxlarge" | "1x" | "2x" | "3x" | "4x" | "5x" | "6x" | "7x" | "8x" | "9x" | "10x";
7
7
  /**
8
8
  * Variants to control block spacing on components, e.g. `space="large"`.
9
9
  *
@@ -23,6 +23,11 @@
23
23
  margin-block: 0;
24
24
  }
25
25
 
26
+ /* Auto margins take the free space in a flex or grid container (for example a `<Column>`), so the block sits in the middle. In normal block flow they compute to 0. */
27
+ .space-auto {
28
+ margin-block: auto;
29
+ }
30
+
26
31
  .space-paragraph {
27
32
  margin-block: var(--space-paragraph);
28
33
  }
@@ -101,3 +106,10 @@
101
106
  margin-block: calc(var(--space-normal) * 10);
102
107
  }
103
108
  }
109
+
110
+ @layer overrides {
111
+ /* Blocks zero the outer margin of a first or last child in this layer (`Block.module.css`). Keep auto margins anyway, so an only child in a column still sits in the middle. The extra always-true pseudo-classes beat that rule's specificity. */
112
+ .space-auto:nth-child(n):nth-last-child(n) {
113
+ margin-block: auto;
114
+ }
115
+ }
@@ -10,6 +10,7 @@ export type SpaceValue =
10
10
  | "section"
11
11
  | "paragraph"
12
12
  | "none"
13
+ | "auto"
13
14
  | "xxsmall"
14
15
  | "xsmall"
15
16
  | "small"
@@ -0,0 +1,30 @@
1
+ # getHeightClass
2
+
3
+ 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()`).
4
+
5
+ `getHeightClass({ height, top, middle, bottom })` maps the props to height classes.
6
+
7
+ **Values:**
8
+
9
+ - `full` — at least the full height of the container, for example a layout's `<Scroll vertical cover>` box.
10
+ - `1x` / `2x` / `3x` / `4x` / `5x` / `6x` / `7x` / `8x` / `10x` / `12x` / `16x` / `20x` / `24x` / `28x` / `32x` — at least a multiple of `--space-normal`.
11
+
12
+ **Things to know:**
13
+
14
+ - 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.
15
+ - `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`.
16
+ - `<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()`).
17
+ - In a flex or grid container, `space="auto"` is the other way to centre a block (see `getSpaceClass()`).
18
+ - `align-content` on a plain block shipped in Chrome 123, Firefox 125 and Safari 17.4. Older browsers show the content at the top.
19
+
20
+ ## Usage
21
+
22
+ A log-in screen, in the middle of a layout's scroll box:
23
+
24
+ ```tsx
25
+ <Page title="Log in">
26
+ <Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
27
+ <LoginForm />
28
+ </Block>
29
+ </Page>
30
+ ```
@@ -4,6 +4,8 @@ The `space` variant prop sets a block-level element's `margin-block` (top + bott
4
4
 
5
5
  `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`.
6
6
 
7
+ `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`.
8
+
7
9
  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.
8
10
 
9
11
  ## Theme variables
@@ -4,6 +4,7 @@ export * from "./Duration.js";
4
4
  export * from "./Flex.js";
5
5
  export * from "./Gap.js";
6
6
  export * from "./Grid.js";
7
+ export * from "./Height.js";
7
8
  export * from "./Indent.js";
8
9
  export * from "./Padding.js";
9
10
  export * from "./Radius.js";
package/ui/style/index.js CHANGED
@@ -4,6 +4,7 @@ export * from "./Duration.js";
4
4
  export * from "./Flex.js";
5
5
  export * from "./Gap.js";
6
6
  export * from "./Grid.js";
7
+ export * from "./Height.js";
7
8
  export * from "./Indent.js";
8
9
  export * from "./Padding.js";
9
10
  export * from "./Radius.js";
package/ui/style/index.ts CHANGED
@@ -4,6 +4,7 @@ export * from "./Duration.js";
4
4
  export * from "./Flex.js";
5
5
  export * from "./Gap.js";
6
6
  export * from "./Grid.js";
7
+ export * from "./Height.js";
7
8
  export * from "./Indent.js";
8
9
  export * from "./Padding.js";
9
10
  export * from "./Radius.js";
@@ -21,7 +21,7 @@ export interface TreeAppProps extends PossibleMeta {
21
21
  /**
22
22
  * Top-level app component for a tree-based documentation site.
23
23
  *
24
- * - Wraps `<App>` with error catching and a sidebar layout.
24
+ * - 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.
25
25
  * - Flattens `tree` once via `<TreeProvider>` wrapping both the sidebar and the router, so everything below shares a single `useTreeMap()` lookup — nothing re-flattens.
26
26
  * - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
27
27
  * - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
@@ -2,15 +2,18 @@ import { jsx as _jsx } from "react/jsx-runtime";
2
2
  import { App } from "../app/App.js";
3
3
  import { SidebarLayout } from "../layout/SidebarLayout.js";
4
4
  import { PageCatcher } from "../misc/Catcher.js";
5
+ import { PageLoader } from "../misc/Loader.js";
5
6
  import { Navigation } from "../router/Navigation.js";
7
+ import { RouteCache } from "../router/RouteCache.js";
6
8
  import { Router } from "../router/Router.js";
9
+ import { Scroll } from "../style/Scroll.js";
7
10
  import { TreeProvider } from "./TreeContext.js";
8
11
  import { TreeRouter } from "./TreeRouter.js";
9
12
  import { TreeSidebar } from "./TreeSidebar.js";
10
13
  /**
11
14
  * Top-level app component for a tree-based documentation site.
12
15
  *
13
- * - Wraps `<App>` with error catching and a sidebar layout.
16
+ * - 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.
14
17
  * - Flattens `tree` once via `<TreeProvider>` wrapping both the sidebar and the router, so everything below shares a single `useTreeMap()` lookup — nothing re-flattens.
15
18
  * - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
16
19
  * - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
@@ -22,5 +25,5 @@ import { TreeSidebar } from "./TreeSidebar.js";
22
25
  */
23
26
  export function TreeApp({ tree, routes, sidebar = _jsx(TreeSidebar, {}), ...meta }) {
24
27
  const fallback = routes && _jsx(Router, { routes: routes });
25
- return (_jsx(App, { ...meta, children: _jsx(Navigation, { children: _jsx(PageCatcher, { children: _jsx(TreeProvider, { tree: tree, children: _jsx(SidebarLayout, { sidebar: sidebar, children: _jsx(TreeRouter, { fallback: fallback }) }) }) }) }) }));
28
+ return (_jsx(App, { ...meta, children: _jsx(Navigation, { children: _jsx(PageCatcher, { children: _jsx(TreeProvider, { tree: tree, children: _jsx(SidebarLayout, { sidebar: sidebar, children: _jsx(RouteCache, { children: _jsx(Scroll, { vertical: true, cover: true, children: _jsx(PageLoader, { children: _jsx(TreeRouter, { fallback: fallback }) }) }) }) }) }) }) }) }));
26
29
  }
@@ -3,9 +3,12 @@ import type { TreeElement } from "../../util/index.js";
3
3
  import { App } from "../app/App.js";
4
4
  import { SidebarLayout } from "../layout/SidebarLayout.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";
8
10
  import type { Routes } from "../router/Routes.js";
11
+ import { Scroll } from "../style/Scroll.js";
9
12
  import type { PossibleMeta } from "../util/index.js";
10
13
  import { TreeProvider } from "./TreeContext.js";
11
14
  import { TreeRouter } from "./TreeRouter.js";
@@ -31,7 +34,7 @@ export interface TreeAppProps extends PossibleMeta {
31
34
  /**
32
35
  * Top-level app component for a tree-based documentation site.
33
36
  *
34
- * - Wraps `<App>` with error catching and a sidebar layout.
37
+ * - 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.
35
38
  * - Flattens `tree` once via `<TreeProvider>` wrapping both the sidebar and the router, so everything below shares a single `useTreeMap()` lookup — nothing re-flattens.
36
39
  * - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
37
40
  * - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
@@ -49,7 +52,13 @@ export function TreeApp({ tree, routes, sidebar = <TreeSidebar />, ...meta }: Tr
49
52
  <PageCatcher>
50
53
  <TreeProvider tree={tree}>
51
54
  <SidebarLayout sidebar={sidebar}>
52
- <TreeRouter fallback={fallback} />
55
+ <RouteCache>
56
+ <Scroll vertical cover>
57
+ <PageLoader>
58
+ <TreeRouter fallback={fallback} />
59
+ </PageLoader>
60
+ </Scroll>
61
+ </RouteCache>
53
62
  </SidebarLayout>
54
63
  </TreeProvider>
55
64
  </PageCatcher>
@@ -1,66 +0,0 @@
1
- # CenteredLayout
2
-
3
- - Kind: component
4
- - Import: `import { CenteredLayout } from "shelving/ui";`
5
-
6
- Layout that centres its content with no header/footer and a narrow max-width.
7
- - Used for e.g. login/register/error/form pages where the content is the only focus.
8
-
9
- A full-viewport layout that centres its content — vertically and horizontally — inside a narrow max-width column. Good for login, registration, error, and other focused single-purpose pages where the content is the only thing on screen. When the content is taller than the viewport it scrolls vertically, pinned to the top so nothing is clipped.
10
-
11
- **Things to know:**
12
-
13
- - Pass the `width` variant to resize the centred column (e.g. `width="normal"`, `width="wide"`, or `width="full"` to fill the available width).
14
- - Pass the `padding` (block / top + bottom) and `indent` (inline / left + right) variants to change the space around the content.
15
- - Like the other full-viewport layouts it owns scroll, padding, and safe-area insets so individual pages don't have to.
16
-
17
- ## Usage
18
-
19
- ```tsx
20
- import { CenteredLayout, Section } from "shelving/ui";
21
-
22
- function LoginPage() {
23
- return (
24
- <CenteredLayout width="narrow">
25
- <Section>
26
- <LoginForm/>
27
- </Section>
28
- </CenteredLayout>
29
- );
30
- }
31
- ```
32
-
33
- Layouts compose naturally as `<Router>` route values — wrap a group of routes in a shared layout, then route further inside it.
34
-
35
- ## Styling
36
-
37
- | Variable | Styles | Default |
38
- |---|---|---|
39
- | `--centered-layout-width` | Width of the centred column (capped at 100%) | `var(--width-narrow)` |
40
- | `--centered-layout-padding` | Block (top/bottom) padding of the scroll area | `var(--space-normal)` |
41
- | `--centered-layout-indent` | Inline (left/right) padding of the scroll area | `var(--space-normal)` |
42
- | `--centered-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
43
- | `--centered-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
44
-
45
- The column width and the scroll-area padding can also be set per-instance via the `width`, `padding`, and `indent` variant props. The outer element owns its scroll, padding, and safe-area behaviour directly — safe-area insets are applied as transparent borders so they stack with (rather than replace) the padding.
46
-
47
- **Global tokens it reads** — `--width-narrow`, `--space-normal`, `--tint-100`, and `--tint-00`.
48
-
49
-
50
- ## Signatures
51
-
52
- ```ts
53
- CenteredLayout({ children, ...props }: CenteredLayoutProps): ReactElement
54
- ```
55
-
56
- ## Parameters
57
-
58
- | Param | Type | Description |
59
- | --- | --- | --- |
60
- | `props` | `CenteredLayoutProps` | |
61
-
62
- ## Returns
63
-
64
- | Type | Description |
65
- | --- | --- |
66
- | `ReactElement` | |
@@ -1,14 +0,0 @@
1
- # CenteredLayoutProps
2
-
3
- - Kind: interface
4
- - Import: `import { CenteredLayoutProps } from "shelving/ui";`
5
- - Extends: `WidthVariants`
6
-
7
- Props for `<CenteredLayout>` — optional `children` plus `width` (of the centred column) and `padding` / `indent`
8
- (block / inline padding of the scroll area) variants.
9
-
10
- ## Signatures
11
-
12
- ```ts
13
- {}
14
- ```