shelving 1.254.1 → 1.255.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.254.1",
+	"version": "1.255.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/ui/README.md

@@ -25,7 +25,7 @@ The styling system lives in `style/` and has four moving parts: design tokens, t
 
 **Cascade layers.** Styles are ordered by `@layer`, lowest to highest priority: `defaults` (`:root` tokens, the tint ladder, body baseline) → `components` (the bulk of the CSS: `.card`, `.button`, …) → `variants` (cross-cutting opt-in modifiers, which always beat components) → `overrides` (top-priority structural fixes like `:first-child` / `:last-child` margin collapses). Unlayered rules beat all layered rules, so a theme should set tokens at `:root` or wrap its rules in `@layer`.
 
-**Styling props.** The cross-cutting visual options are props, each backed by a helper in `style/` that maps the prop to a class. Colour and status move the tint anchor — `getColorClass()` and `getStatusClass()`; font size, weight, family, and case, plus text alignment, tint, and wrapping, all come from `getTypographyClass()`; spacing, padding, and gap from `getSpaceClass()`, `getPaddingClass()`, and `getGapClass()`; width constraints from `getWidthClass()`; flex layout from `getFlexClass()`; and opt-in scrolling from `getScrollClass()`. Each helper's page lists its exact prop values and what they set. A component opts into the props it wants by extending the matching `*Props` interfaces and composing the `getXxxClass(props)` calls.
+**Styling props.** The cross-cutting visual options are props, each backed by a helper in `style/` that maps the prop to a class. Colour and status move the tint anchor — `getColorClass()` and `getStatusClass()`; font size, weight, family, and case, plus text alignment, tint, and wrapping, all come from `getTypographyClass()`; spacing, block-padding, inline-padding ("indent"), and gap from `getSpaceClass()`, `getPaddingClass()`, `getIndentClass()`, and `getGapClass()`; width constraints from `getWidthClass()`; flex layout from `getFlexClass()`; and opt-in scrolling from `getScrollClass()`. Each helper's page lists its exact prop values and what they set. A component opts into the props it wants by extending the matching `*Props` interfaces and composing the `getXxxClass(props)` calls.
 
 Each painting component also exposes its own theme hooks — a single tint hook (`--card-tint`) to recolour the whole component, plus per-property hooks (`--card-background`, `--card-radius`, …) for surgical overrides. Those are documented in each component's own **Styling** section (see `<Card>` for the precedent).
 

package/ui/block/Block.d.ts

@@ -1,5 +1,6 @@
 import type { ReactElement } from "react";
 import { type ColorVariants } from "../style/Color.js";
+import { type IndentVariants } from "../style/Indent.js";
 import { type SpaceVariants } from "../style/Space.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import { type WidthVariants } from "../style/Width.js";
@@ -15,7 +16,7 @@ export type BlockElement = "div" | "section" | "header" | "footer" | "article" |
  *
  * @see https://shelving.cc/ui/BlockProps
  */
-export interface BlockProps extends ColorVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
+export interface BlockProps extends ColorVariants, IndentVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
     /**
      * Element this `<Block>` renders as, e.g. "header" to output a "<header>"
      * @default "div"

package/ui/block/Block.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { getColorClass } from "../style/Color.js";
+import { getIndentClass } from "../style/Indent.js";
 import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getWidthClass } from "../style/Width.js";
@@ -18,7 +19,7 @@ const BLOCK_CLASS = getModuleClass(BLOCK_CSS, "block");
  */
 export function getBlockClass(variants) {
     return getClass(BLOCK_CLASS, //
-    getColorClass(variants), getSpaceClass(variants), getTypographyClass(variants), getWidthClass(variants));
+    getColorClass(variants), getIndentClass(variants), getSpaceClass(variants), getTypographyClass(variants), getWidthClass(variants));
 }
 /**
  * Plain `<div>` block with block-level spacing.

package/ui/block/Block.module.css

@@ -1,5 +1,6 @@
 @import "../style/layers.css";
 @import "../style/Color.module.css";
+@import "../style/Indent.module.css";
 @import "../style/Space.module.css";
 @import "../style/Typography.module.css";
 @import "../style/Width.module.css";

package/ui/block/Block.tsx

@@ -1,5 +1,6 @@
 import type { ReactElement } from "react";
 import { type ColorVariants, getColorClass } from "../style/Color.js";
+import { getIndentClass, type IndentVariants } from "../style/Indent.js";
 import { getSpaceClass, type SpaceVariants } from "../style/Space.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
 import { getWidthClass, type WidthVariants } from "../style/Width.js";
@@ -21,7 +22,7 @@ export type BlockElement = "div" | "section" | "header" | "footer" | "article" |
  *
  * @see https://shelving.cc/ui/BlockProps
  */
-export interface BlockProps extends ColorVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
+export interface BlockProps extends ColorVariants, IndentVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
 	/**
 	 * Element this `<Block>` renders as, e.g. "header" to output a "<header>"
 	 * @default "div"
@@ -43,6 +44,7 @@ export function getBlockClass(variants: BlockProps): string {
 	return getClass(
 		BLOCK_CLASS, //
 		getColorClass(variants),
+		getIndentClass(variants),
 		getSpaceClass(variants),
 		getTypographyClass(variants),
 		getWidthClass(variants),

package/ui/block/Panel.d.ts

@@ -1,5 +1,6 @@
 import type { ReactElement } from "react";
 import { type ColorVariants } from "../style/Color.js";
+import { type IndentVariants } from "../style/Indent.js";
 import { type PaddingVariants } from "../style/Padding.js";
 import { type StatusVariants } from "../style/Status.js";
 import { type TypographyVariants } from "../style/Typography.js";
@@ -10,7 +11,7 @@ import type { BlockElement } from "./Block.js";
  *
  * @see https://shelving.cc/ui/PanelProps
  */
-export interface PanelProps extends ColorVariants, PaddingVariants, StatusVariants, TypographyVariants, OptionalChildProps {
+export interface PanelProps extends ColorVariants, IndentVariants, PaddingVariants, StatusVariants, TypographyVariants, OptionalChildProps {
     /**
      * Element this `<Panel>` renders as, e.g. "header" to output a "<header>"
      * @default "section"

package/ui/block/Panel.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { getColorClass } from "../style/Color.js";
+import { getIndentClass } from "../style/Indent.js";
 import { getPaddingClass } from "../style/Padding.js";
 import { getStatusClass } from "../style/Status.js";
 import { getTypographyClass } from "../style/Typography.js";
@@ -21,5 +22,5 @@ const PANEL_CLASS = getModuleClass(PANEL_CSS, "panel");
  */
 export function Panel({ as: Element = "section", children, ...props }) {
     return (_jsx(Element, { className: getClass(PANEL_CLASS, //
-        getStatusClass(props), getColorClass(props), getPaddingClass(props), getTypographyClass(props)), children: children }));
+        getStatusClass(props), getColorClass(props), getIndentClass(props), getPaddingClass(props), getTypographyClass(props)), children: children }));
 }

package/ui/block/Panel.md

@@ -5,7 +5,8 @@ A full-width vertical region that paints the current surface colour. Use panels
 **Things to know:**
 
 - A panel always spans the full width of its container. To constrain the content inside, compose a `<Block>` `width="narrow"` (or `width="wide"`) within it.
-- Block margin is always zero so panels stack flush; control the vertical breathing room with the `padding` variant (`<Panel padding="large">`, `<Panel padding="none">`). Inline padding is fixed.
+- Block margin is always zero so panels stack flush; control the vertical breathing room with the `padding` variant (`<Panel padding="large">`, `<Panel padding="none">`).
+- Inline padding ("indent") keeps content off the edges by default. Override it per-property with `--panel-indent`, or change it with the shared `indent` variant (`<Panel indent="large">`, `<Panel indent="none">`).
 - `color=` / `status=` move the tint anchor for the whole panel scope, so the surface, border, and text re-derive together and cascade into nested content.
 - The top and bottom borders are dropped on the first and last panel so the page doesn't gain stray edge lines.
 
@@ -39,5 +40,6 @@ import { Panel, Block, Title, Paragraph } from "shelving/ui";
 | `--panel-color` | Text colour | `var(--tint-00)` |
 | `--panel-border` | Top/bottom border shorthand | `var(--panel-stroke) solid var(--tint-80)` |
 | `--panel-stroke` | Border thickness | `var(--stroke-normal)` (2px) |
+| `--panel-indent` | Inline padding (left + right) keeping content off the edges | `var(--space-normal)` (16px) |
 
-**Global tokens it reads:** the tint-ladder steps `--tint-00` / `--tint-80` / `--tint-90`, plus `--stroke-normal`. Vertical padding comes from the shared `padding` variant.
+**Global tokens it reads:** the tint-ladder steps `--tint-00` / `--tint-80` / `--tint-90`, plus `--stroke-normal` and `--space-normal`. Vertical padding comes from the shared `padding` variant; inline padding from the shared `indent` variant.

package/ui/block/Panel.module.css

@@ -3,14 +3,18 @@
 @import "../style/Typography.module.css";
 @import "../style/Status.module.css";
 @import "../style/Color.module.css";
+@import "../style/Indent.module.css";
 @import "../style/Padding.module.css";
+@import "../style/Space.module.css";
 
 /*
  * Full-width vertical region that paints the current surface. Panels always have zero block-space
  * (they butt up against each other vertically to create stacked page sections). Vertical breathing
  * room comes from the shared `padding` variant (`.large`, `.xxlarge`, etc. from `style/Padding`);
  * with no `padding` the block padding is zero and the inner `<Section>` margins provide the spacing.
- * For narrower content inside a wide panel, compose a `<Block narrow>` (or `<Block wide>`) inside it.
+ * Inline padding ("indent") keeps content off the edges by default (`--panel-indent`); override it
+ * with the shared `indent` variant. For narrower content inside a wide panel, compose a
+ * `<Block narrow>` (or `<Block wide>`) inside it.
  */
 @layer components {
 	.panel {
@@ -20,9 +24,11 @@
 		/* Box */
 		position: relative;
 		display: flow-root;
+		box-sizing: border-box;
 		inline-size: 100%;
 		margin-inline: 0;
 		margin-block: 0;
+		padding-inline: var(--panel-indent, var(--space-normal));
 		border-top: var(--panel-border, var(--panel-stroke, var(--stroke-normal)) solid var(--tint-80));
 		border-bottom: var(--panel-border, var(--panel-stroke, var(--stroke-normal)) solid var(--tint-80));
 

package/ui/block/Panel.tsx

@@ -1,5 +1,6 @@
 import type { ReactElement } from "react";
 import { type ColorVariants, getColorClass } from "../style/Color.js";
+import { getIndentClass, type IndentVariants } from "../style/Indent.js";
 import { getPaddingClass, type PaddingVariants } from "../style/Padding.js";
 import { getStatusClass, type StatusVariants } from "../style/Status.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
@@ -15,7 +16,7 @@ const PANEL_CLASS = getModuleClass(PANEL_CSS, "panel");
  *
  * @see https://shelving.cc/ui/PanelProps
  */
-export interface PanelProps extends ColorVariants, PaddingVariants, StatusVariants, TypographyVariants, OptionalChildProps {
+export interface PanelProps extends ColorVariants, IndentVariants, PaddingVariants, StatusVariants, TypographyVariants, OptionalChildProps {
 	/**
 	 * Element this `<Panel>` renders as, e.g. "header" to output a "<header>"
 	 * @default "section"
@@ -43,6 +44,7 @@ export function Panel({ as: Element = "section", children, ...props }: PanelProp
 				PANEL_CLASS, //
 				getStatusClass(props),
 				getColorClass(props),
+				getIndentClass(props),
 				getPaddingClass(props),
 				getTypographyClass(props),
 			)}

package/ui/block/Section.d.ts

@@ -1,5 +1,6 @@
 import type { ReactElement } from "react";
 import { type ColorVariants } from "../style/Color.js";
+import { type IndentVariants } from "../style/Indent.js";
 import { type SpaceVariants } from "../style/Space.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import { type WidthVariants } from "../style/Width.js";
@@ -10,7 +11,7 @@ import type { BlockElement } from "./Block.js";
  *
  * @see https://shelving.cc/ui/SectionProps
  */
-export interface SectionProps extends ColorVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
+export interface SectionProps extends ColorVariants, IndentVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
     /**
      * Element this `<Section>` renders as, e.g. "header" to output a "<header>"
      * @default "section"

package/ui/block/Section.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { getColorClass } from "../style/Color.js";
+import { getIndentClass } from "../style/Indent.js";
 import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getWidthClass } from "../style/Width.js";
@@ -18,7 +19,7 @@ const SECTION_CLASS = getModuleClass(SECTION_CSS, "section");
  */
 export function getSectionClass(variants) {
     return getClass(SECTION_CLASS, //
-    getColorClass(variants), getSpaceClass(variants), getTypographyClass(variants), getWidthClass(variants));
+    getColorClass(variants), getIndentClass(variants), getSpaceClass(variants), getTypographyClass(variants), getWidthClass(variants));
 }
 /**
  * `<section>` block with section-level spacing.

package/ui/block/Section.md

@@ -5,8 +5,8 @@ A landmark content region — renders a `<section>` with block-level spacing and
 **Things to know:**
 
 - Pick the component whose HTML element matches the semantic meaning rather than reaching for a generic `<Block>`. `<Section>` is a `<section>`, `<Figure>` a `<figure>`, and so on.
-- Every section centres its content and caps the line length so text never touches the viewport edges. Nested sections relax that cap so they can fill their parent.
-- Sections default to the `--width-normal` content width, so most of the time you set no width at all. Pass `width="narrow"` / `"wide"` / `"full"` (or `"fit"`) to change that, and the usual `color` / `space` / typography variants to retint and respace.
+- Every section centres its content and caps the line length, but it adds **no inline padding of its own**, so its content can run to the edge of its container. Keep content off the edges by placing the section inside something that already pads — a `<Panel>`, a `<Block indent="normal">`, or a layout that pads its scroll area — or by giving the section its own `indent` variant (`<Section indent="normal">`).
+- Sections default to the `--width-normal` content width, so most of the time you set no width at all. Pass `width="narrow"` / `"wide"` / `"full"` (or `"fit"`) to change that, and the usual `color` / `space` / `indent` / typography variants to retint, respace, and inset.
 - Pair `Figure` with `<Caption>` for a `<figure>` / `<figcaption>` pair.
 
 ## Usage
@@ -43,7 +43,6 @@ import { Header, Nav, Footer } from "shelving/ui";
 | Variable | Styles | Default |
 |---|---|---|
 | `--section-width` | Content width | `var(--width-normal)` (55rem) |
-| `--section-indent` | Inline gutter kept on each side so text doesn't touch the edges | `var(--space-normal)` (16px) |
 | `--section-space` | Outer block margin (top + bottom) | `var(--space-section)` (2rem) |
 
-**Global tokens it reads:** `--space-normal`, `--space-section`, and `--width-normal` (the default content width). The `width` variant (`narrow` / `normal` / `wide` / `full` / `fit`) comes from the shared `shelving/ui` styling system.
+**Global tokens it reads:** `--space-section` and `--width-normal` (the default content width). The `width` variant (`narrow` / `normal` / `wide` / `full` / `fit`) and the `indent` variant (inline padding, via `getIndentClass()`) come from the shared `shelving/ui` styling system.

package/ui/block/Section.module.css

@@ -1,5 +1,6 @@
 @import "../style/layers.css";
 @import "../style/Color.module.css";
+@import "../style/Indent.module.css";
 @import "../style/Typography.module.css";
 @import "../style/Space.module.css";
 @import "../style/Width.module.css";
@@ -10,15 +11,10 @@
 		/* Box */
 		position: relative;
 		display: block;
-		box-sizing: border-box;
-		max-inline-size: calc(100% - (var(--section-indent, var(--space-normal)) * 2)); /* Stop text touching the sides. */
+		box-sizing: border-box; /* Keep the `indent` variant's inline padding inside the width. */
+		max-inline-size: 100%;
 		inline-size: var(--section-width, var(--width-normal)); /* Default to the normal content width; override with the `width` variant. */
 		margin-inline: auto;
 		margin-block: var(--section-space, var(--space-section));
-
-		.prose :where(section, article, aside, nav, header, footer, figure),
-		.section {
-			max-inline-size: 100%; /* Nested sections can touch the side again */
-		}
 	}
 }

package/ui/block/Section.tsx

@@ -1,5 +1,6 @@
 import type { ReactElement } from "react";
 import { type ColorVariants, getColorClass } from "../style/Color.js";
+import { getIndentClass, type IndentVariants } from "../style/Indent.js";
 import { getSpaceClass, type SpaceVariants } from "../style/Space.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
 import { getWidthClass, type WidthVariants } from "../style/Width.js";
@@ -15,7 +16,7 @@ const SECTION_CLASS = getModuleClass(SECTION_CSS, "section");
  *
  * @see https://shelving.cc/ui/SectionProps
  */
-export interface SectionProps extends ColorVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
+export interface SectionProps extends ColorVariants, IndentVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
 	/**
 	 * Element this `<Section>` renders as, e.g. "header" to output a "<header>"
 	 * @default "section"
@@ -37,6 +38,7 @@ export function getSectionClass(variants: SectionProps): string {
 	return getClass(
 		SECTION_CLASS, //
 		getColorClass(variants),
+		getIndentClass(variants),
 		getSpaceClass(variants),
 		getTypographyClass(variants),
 		getWidthClass(variants),

package/ui/docs/DocumentationHomePage.js

@@ -19,5 +19,5 @@ import { TreeMarkup } from "../tree/TreeMarkup.js";
  * @see https://shelving.cc/ui/DocumentationHomePage
  */
 export function DocumentationHomePage({ title, name, description, content, children }) {
-    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: "red", children: [_jsx(Panel, { padding: "5x", children: _jsx(Title, { center: true, children: title ?? name }) }), content && (_jsx(Section, { children: _jsx(Prose, { children: _jsx(TreeMarkup, { children: content }) }) })), _jsx(Section, { children: _jsx(TreeCards, { children: children }) })] }) }));
+    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: "red", children: [_jsx(Panel, { padding: "5x", children: _jsx(Title, { center: true, children: title ?? name }) }), _jsxs(Block, { indent: "normal", children: [content && (_jsx(Section, { children: _jsx(Prose, { children: _jsx(TreeMarkup, { children: content }) }) })), _jsx(Section, { children: _jsx(TreeCards, { children: children }) })] })] }) }));
 }

package/ui/docs/DocumentationHomePage.tsx

@@ -27,16 +27,18 @@ export function DocumentationHomePage({ title, name, description, content, child
 				<Panel padding="5x">
 					<Title center>{title ?? name}</Title>
 				</Panel>
-				{content && (
+				<Block indent="normal">
+					{content && (
+						<Section>
+							<Prose>
+								<TreeMarkup>{content}</TreeMarkup>
+							</Prose>
+						</Section>
+					)}
 					<Section>
-						<Prose>
-							<TreeMarkup>{content}</TreeMarkup>
-						</Prose>
+						<TreeCards>{children}</TreeCards>
 					</Section>
-				)}
-				<Section>
-					<TreeCards>{children}</TreeCards>
-				</Section>
+				</Block>
 			</Block>
 		</Page>
 	);

package/ui/docs/DocumentationPage.js

@@ -69,5 +69,5 @@ function DocumentationChildren({ elements }) {
  * @see https://shelving.cc/ui/DocumentationPage
  */
 export function DocumentationPage({ title, name, kind = "unknown", description, content, signatures, params, returns, throws, properties, types, examples, children, ...props }) {
-    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: getDocumentationKindColor(kind), children: [_jsx(Panel, { children: _jsxs(Header, { children: [_jsx(TreeBreadcrumbs, {}), _jsx(Title, { children: _jsxs(Row, { left: true, wrap: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind, size: "normal" })] }) }), _jsx(DocumentationButtons, { ...props })] }) }), signatures?.length || params?.length || returns?.length || throws?.length || properties?.length || types?.length ? (_jsxs(Section, { children: [_jsx(DocumentationSignatures, { signatures: signatures }), _jsx(DocumentationParams, { params: params }), _jsx(DocumentationReturns, { returns: returns }), _jsx(DocumentationThrows, { throws: throws }), _jsx(DocumentationProperties, { properties: properties }), _jsx(DocumentationReferences, { types: types })] })) : null, content && (_jsx(Section, { children: _jsx(Prose, { children: _jsx(TreeMarkup, { children: content }) }) })), examples?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), _jsx(DocumentationChildren, { elements: children })] }) }));
+    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: getDocumentationKindColor(kind), children: [_jsx(Panel, { children: _jsxs(Header, { children: [_jsx(TreeBreadcrumbs, {}), _jsx(Title, { children: _jsxs(Row, { left: true, wrap: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind, size: "normal" })] }) }), _jsx(DocumentationButtons, { ...props })] }) }), _jsxs(Block, { indent: "normal", children: [signatures?.length || params?.length || returns?.length || throws?.length || properties?.length || types?.length ? (_jsxs(Section, { children: [_jsx(DocumentationSignatures, { signatures: signatures }), _jsx(DocumentationParams, { params: params }), _jsx(DocumentationReturns, { returns: returns }), _jsx(DocumentationThrows, { throws: throws }), _jsx(DocumentationProperties, { properties: properties }), _jsx(DocumentationReferences, { types: types })] })) : null, content && (_jsx(Section, { children: _jsx(Prose, { children: _jsx(TreeMarkup, { children: content }) }) })), examples?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), _jsx(DocumentationChildren, { elements: children })] })] }) }));
 }

package/ui/docs/DocumentationPage.tsx

@@ -110,32 +110,34 @@ export function DocumentationPage({
 						<DocumentationButtons {...props} />
 					</Header>
 				</Panel>
-				{signatures?.length || params?.length || returns?.length || throws?.length || properties?.length || types?.length ? (
-					<Section>
-						<DocumentationSignatures signatures={signatures} />
-						<DocumentationParams params={params} />
-						<DocumentationReturns returns={returns} />
-						<DocumentationThrows throws={throws} />
-						<DocumentationProperties properties={properties} />
-						<DocumentationReferences types={types} />
-					</Section>
-				) : null}
-				{content && (
-					<Section>
-						<Prose>
-							<TreeMarkup>{content}</TreeMarkup>
-						</Prose>
-					</Section>
-				)}
-				{examples?.length && (
-					<Section>
-						<Heading>Examples</Heading>
-						{examples.map(({ description }) => (
-							<Preformatted key={description}>{description}</Preformatted>
-						))}
-					</Section>
-				)}
-				<DocumentationChildren elements={children} />
+				<Block indent="normal">
+					{signatures?.length || params?.length || returns?.length || throws?.length || properties?.length || types?.length ? (
+						<Section>
+							<DocumentationSignatures signatures={signatures} />
+							<DocumentationParams params={params} />
+							<DocumentationReturns returns={returns} />
+							<DocumentationThrows throws={throws} />
+							<DocumentationProperties properties={properties} />
+							<DocumentationReferences types={types} />
+						</Section>
+					) : null}
+					{content && (
+						<Section>
+							<Prose>
+								<TreeMarkup>{content}</TreeMarkup>
+							</Prose>
+						</Section>
+					)}
+					{examples?.length && (
+						<Section>
+							<Heading>Examples</Heading>
+							{examples.map(({ description }) => (
+								<Preformatted key={description}>{description}</Preformatted>
+							))}
+						</Section>
+					)}
+					<DocumentationChildren elements={children} />
+				</Block>
 			</Block>
 		</Page>
 	);

package/ui/form/Form.d.ts

@@ -3,6 +3,7 @@ import type { DataSchema } from "../../schema/DataSchema.js";
 import type { Data, PartialData } from "../../util/data.js";
 import type { ImmutableDictionary } from "../../util/dictionary.js";
 import type { Arguments } from "../../util/function.js";
+import { type IndentVariants } from "../style/Indent.js";
 import { type NoticeCallback } from "../util/notice.js";
 import type { OptionalChildProps } from "../util/props.js";
 import { FormStore } from "./FormStore.js";
@@ -19,7 +20,7 @@ export type FormCallback<T extends Data> = (data: T, event: SubmitEvent<HTMLForm
  *
  * @see https://shelving.cc/ui/FormProps
  */
-export interface FormProps<T extends Data> extends OptionalChildProps {
+export interface FormProps<T extends Data> extends IndentVariants, OptionalChildProps {
     /** Schema for the form. */
     schema: DataSchema<T>;
     /** Initial data for the form. */

package/ui/form/Form.js

@@ -2,7 +2,8 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useInstance } from "../../react/useInstance.js";
 import { useStore } from "../../react/useStore.js";
 import { isAsync } from "../../util/async.js";
-import { getModuleClass } from "../util/css.js";
+import { getIndentClass } from "../style/Indent.js";
+import { getClass, getModuleClass } from "../util/css.js";
 import { notifySuccess, notifyThrown } from "../util/notice.js";
 import FORM_CSS from "./Form.module.css";
 import { FormContext } from "./FormContext.js";
@@ -11,7 +12,7 @@ import { FormFooter } from "./FormFooter.js";
 import { FormStore } from "./FormStore.js";
 const FORM_CLASS = getModuleClass(FORM_CSS, "form");
 const FORM_FIELDSET_CLASS = getModuleClass(FORM_CSS, "fieldset");
-export function Form({ schema, data: initialData, onSubmit, submit, messages, children = (_jsxs(_Fragment, { children: [_jsx(FormFields, {}), _jsx(FormFooter, { submit: submit })] })), }) {
+export function Form({ schema, data: initialData, onSubmit, submit, messages, children = (_jsxs(_Fragment, { children: [_jsx(FormFields, {}), _jsx(FormFooter, { submit: submit })] })), ...props }) {
     // Create a form store instance and subscribe to changes in it.
     const store = useStore(useInstance(FormStore, schema, initialData, messages));
     const busy = useStore(store.busy).value;
@@ -26,7 +27,7 @@ export function Form({ schema, data: initialData, onSubmit, submit, messages, ch
             // Close the parent dialog on successful submit.
             if (result)
                 dialog?.close();
-        }, className: FORM_CLASS, noValidate: true, children: _jsx("fieldset", { className: FORM_FIELDSET_CLASS, disabled: busy, children: _jsx(FormContext, { value: store, children: children }) }) }, store.key));
+        }, className: getClass(FORM_CLASS, getIndentClass(props)), noValidate: true, children: _jsx("fieldset", { className: FORM_FIELDSET_CLASS, disabled: busy, children: _jsx(FormContext, { value: store, children: children }) }) }, store.key));
 }
 /**
  * Run a form submit callback and publish success/error notices based on its return or thrown value.

package/ui/form/Form.md

@@ -105,4 +105,4 @@ When an `onSubmit` callback returns a non-empty `ReactNode`, `Form` dispatches i
 |---|---|---|
 | `--form-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
 
-**Global tokens it reads:** `--space-paragraph`.
+**Global tokens it reads:** `--space-paragraph`. The `indent` variant (inline padding, via `getIndentClass()`) comes from the shared `shelving/ui` styling system — set `<Form indent="normal">` to inset the form's content from the edges.

package/ui/form/Form.module.css

@@ -1,4 +1,5 @@
 @import "../style/layers.css";
+@import "../style/Indent.module.css";
 @import "../style/Space.module.css";
 
 @layer components {

package/ui/form/Form.tsx

@@ -6,7 +6,8 @@ import { isAsync } from "../../util/async.js";
 import type { Data, PartialData } from "../../util/data.js";
 import type { ImmutableDictionary } from "../../util/dictionary.js";
 import type { Arguments } from "../../util/function.js";
-import { getModuleClass } from "../util/css.js";
+import { getIndentClass, type IndentVariants } from "../style/Indent.js";
+import { getClass, getModuleClass } from "../util/css.js";
 import { type NoticeCallback, notifySuccess, notifyThrown } from "../util/notice.js";
 import type { OptionalChildProps } from "../util/props.js";
 import FORM_CSS from "./Form.module.css";
@@ -35,7 +36,7 @@ export type FormCallback<T extends Data> = (
  *
  * @see https://shelving.cc/ui/FormProps
  */
-export interface FormProps<T extends Data> extends OptionalChildProps {
+export interface FormProps<T extends Data> extends IndentVariants, OptionalChildProps {
 	/** Schema for the form. */
 	schema: DataSchema<T>;
 	/** Initial data for the form. */
@@ -71,6 +72,7 @@ export function Form({
 			<FormFooter submit={submit} />
 		</>
 	),
+	...props
 }: FormProps<Data>): ReactElement {
 	// Create a form store instance and subscribe to changes in it.
 	const store = useStore(useInstance(FormStore, schema, initialData, messages));
@@ -94,7 +96,7 @@ export function Form({
 				// Close the parent dialog on successful submit.
 				if (result) dialog?.close();
 			}}
-			className={FORM_CLASS}
+			className={getClass(FORM_CLASS, getIndentClass(props))}
 			noValidate={true}
 		>
 			<fieldset className={FORM_FIELDSET_CLASS} disabled={busy}>

package/ui/style/Indent.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Allowed values for inline-padding ("indent") for components that support `IndentVariants`
+ *
+ * @see https://shelving.cc/ui/IndentVariant
+ */
+export type IndentVariant = "none" | "xxsmall" | "xsmall" | "small" | "normal" | "large" | "xlarge" | "xxlarge" | "1x" | "2x" | "3x" | "4x" | "5x" | "6x" | "7x" | "8x" | "9x" | "10x";
+/**
+ * Variant props for the inline-padding ("indent", left + right) of a component, e.g. `indent="normal"`.
+ *
+ * @see https://shelving.cc/ui/IndentVariants
+ */
+export interface IndentVariants {
+    /** Inline-padding (left + right) of the element, keeping its content off the edges. */
+    indent?: IndentVariant | undefined;
+}
+/**
+ * Get the inline-padding ("indent") class for a component from its `indent` variant prop.
+ *
+ * @param variants
+ * @returns The indent class string, or `undefined` when no `indent` is set.
+ * @example getIndentClass({ indent: "normal" }) // "indent-normal"
+ * @see https://shelving.cc/ui/getIndentClass
+ */
+export declare function getIndentClass({ indent }: IndentVariants): string | undefined;

package/ui/style/Indent.js

@@ -0,0 +1,13 @@
+import { getModuleClass } from "../util/css.js";
+import INDENT_CSS from "./Indent.module.css";
+/**
+ * Get the inline-padding ("indent") class for a component from its `indent` variant prop.
+ *
+ * @param variants
+ * @returns The indent class string, or `undefined` when no `indent` is set.
+ * @example getIndentClass({ indent: "normal" }) // "indent-normal"
+ * @see https://shelving.cc/ui/getIndentClass
+ */
+export function getIndentClass({ indent }) {
+    return indent && getModuleClass(INDENT_CSS, `indent-${indent}`);
+}

package/ui/style/Indent.module.css

@@ -0,0 +1,62 @@
+@import "layers.css";
+@import "Space.module.css";
+
+@layer variants {
+	/* Inline-padding ("indent") variants — left + right padding to keep content off the edges. */
+	.indent-none {
+		padding-inline: 0;
+	}
+	.indent-xxsmall {
+		padding-inline: var(--space-xxsmall);
+	}
+	.indent-xsmall {
+		padding-inline: var(--space-xsmall);
+	}
+	.indent-small {
+		padding-inline: var(--space-small);
+	}
+	.indent-normal {
+		padding-inline: var(--space-normal);
+	}
+	.indent-large {
+		padding-inline: var(--space-large);
+	}
+	.indent-xlarge {
+		padding-inline: var(--space-xlarge);
+	}
+	.indent-xxlarge {
+		padding-inline: var(--space-xxlarge);
+	}
+
+	/* Numeric inline-padding multiples of `--space-normal` (`1x` … `10x`). */
+	.indent-1x {
+		padding-inline: calc(var(--space-normal) * 1);
+	}
+	.indent-2x {
+		padding-inline: calc(var(--space-normal) * 2);
+	}
+	.indent-3x {
+		padding-inline: calc(var(--space-normal) * 3);
+	}
+	.indent-4x {
+		padding-inline: calc(var(--space-normal) * 4);
+	}
+	.indent-5x {
+		padding-inline: calc(var(--space-normal) * 5);
+	}
+	.indent-6x {
+		padding-inline: calc(var(--space-normal) * 6);
+	}
+	.indent-7x {
+		padding-inline: calc(var(--space-normal) * 7);
+	}
+	.indent-8x {
+		padding-inline: calc(var(--space-normal) * 8);
+	}
+	.indent-9x {
+		padding-inline: calc(var(--space-normal) * 9);
+	}
+	.indent-10x {
+		padding-inline: calc(var(--space-normal) * 10);
+	}
+}

package/ui/style/Indent.tsx

@@ -0,0 +1,49 @@
+import { getModuleClass } from "../util/css.js";
+import INDENT_CSS from "./Indent.module.css";
+
+/**
+ * Allowed values for inline-padding ("indent") for components that support `IndentVariants`
+ *
+ * @see https://shelving.cc/ui/IndentVariant
+ */
+export type IndentVariant =
+	| "none"
+	| "xxsmall"
+	| "xsmall"
+	| "small"
+	| "normal"
+	| "large"
+	| "xlarge"
+	| "xxlarge"
+	| "1x"
+	| "2x"
+	| "3x"
+	| "4x"
+	| "5x"
+	| "6x"
+	| "7x"
+	| "8x"
+	| "9x"
+	| "10x";
+
+/**
+ * Variant props for the inline-padding ("indent", left + right) of a component, e.g. `indent="normal"`.
+ *
+ * @see https://shelving.cc/ui/IndentVariants
+ */
+export interface IndentVariants {
+	/** Inline-padding (left + right) of the element, keeping its content off the edges. */
+	indent?: IndentVariant | undefined;
+}
+
+/**
+ * Get the inline-padding ("indent") class for a component from its `indent` variant prop.
+ *
+ * @param variants
+ * @returns The indent class string, or `undefined` when no `indent` is set.
+ * @example getIndentClass({ indent: "normal" }) // "indent-normal"
+ * @see https://shelving.cc/ui/getIndentClass
+ */
+export function getIndentClass({ indent }: IndentVariants): string | undefined {
+	return indent && getModuleClass(INDENT_CSS, `indent-${indent}`);
+}

package/ui/style/getSpaceClass.md

@@ -2,9 +2,9 @@
 
 The `space` variant prop sets a block-level element's `margin-block` (top + bottom) from the spacing scale — `<Section space="large">`, `<Paragraph space="none">`. It's an **override** for one-off spacing; for an app-wide change, retune the spacing variables below in a theme file.
 
-`getSpaceClass({ space })` maps the prop to a margin class (e.g. `space="large"` → `large`). The same scale also backs `getPaddingClass()` and `getGapClass()`, so all three move together when you change `--space-normal`.
+`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`.
 
-Alongside the named scale, `space` and `padding` 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.
+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.
 
 ## Theme variables
 

package/ui/style/index.d.ts

@@ -2,6 +2,7 @@ export * from "./Color.js";
 export * from "./Duration.js";
 export * from "./Flex.js";
 export * from "./Gap.js";
+export * from "./Indent.js";
 export * from "./Padding.js";
 export * from "./Radius.js";
 export * from "./Scroll.js";

package/ui/style/index.js

@@ -2,6 +2,7 @@ export * from "./Color.js";
 export * from "./Duration.js";
 export * from "./Flex.js";
 export * from "./Gap.js";
+export * from "./Indent.js";
 export * from "./Padding.js";
 export * from "./Radius.js";
 export * from "./Scroll.js";

package/ui/style/index.tsx

@@ -2,6 +2,7 @@ export * from "./Color.js";
 export * from "./Duration.js";
 export * from "./Flex.js";
 export * from "./Gap.js";
+export * from "./Indent.js";
 export * from "./Padding.js";
 export * from "./Radius.js";
 export * from "./Scroll.js";

package/ui/tree/TreeIndexPage.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
 import { toggleArrayItem } from "../../util/array.js";
 import { searchTree } from "../../util/tree.js";
+import { Block } from "../block/Block.js";
 import { Header, Section } from "../block/Section.js";
 import { Title } from "../block/Title.js";
 import { DocumentationKind } from "../docs/DocumentationKind.js";
@@ -51,5 +52,5 @@ export function TreeIndexPage() {
     const filter = selected.length ? { kind: selected } : undefined;
     // Each element's `key` is its unique canonical path (stamped by `flattenTree()`), so this flat cross-tree listing reconciles correctly.
     const cards = root ? searchTree(root, trimmed, { limit: trimmed ? 20 : INDEX_LIMIT, filter }) : [];
-    return (_jsxs(Page, { title: INDEX_TITLE, description: INDEX_DESCRIPTION, children: [_jsx(Header, { children: _jsx(Title, { children: INDEX_TITLE }) }), _jsxs(Section, { children: [_jsx(TextInput, { name: "search", title: "Search", placeholder: "Search\u2026", value: query, onValue: v => setQuery(v ?? "") }), !!kinds.length && (_jsx(Row, { left: true, wrap: true, children: kinds.map(kind => (_jsx(CheckboxInput, { name: kind, width: "fit", value: selected.includes(kind), onValue: () => setSelected(s => toggleArrayItem(s, kind)), children: _jsx(DocumentationKind, { kind: kind }) }, kind))) }))] }), _jsx(Section, { children: _jsx(TreeCards, { children: cards }) })] }));
+    return (_jsx(Page, { title: INDEX_TITLE, description: INDEX_DESCRIPTION, children: _jsxs(Block, { indent: "normal", children: [_jsx(Header, { children: _jsx(Title, { children: INDEX_TITLE }) }), _jsxs(Section, { children: [_jsx(TextInput, { name: "search", title: "Search", placeholder: "Search\u2026", value: query, onValue: v => setQuery(v ?? "") }), !!kinds.length && (_jsx(Row, { left: true, wrap: true, children: kinds.map(kind => (_jsx(CheckboxInput, { name: kind, width: "fit", value: selected.includes(kind), onValue: () => setSelected(s => toggleArrayItem(s, kind)), children: _jsx(DocumentationKind, { kind: kind }) }, kind))) }))] }), _jsx(Section, { children: _jsx(TreeCards, { children: cards }) })] }) }));
 }

package/ui/tree/TreeIndexPage.tsx

@@ -4,6 +4,7 @@ import type { AbsolutePath } from "../../util/path.js";
 import type { Query } from "../../util/query.js";
 import type { DocumentationElementProps } from "../../util/tree.js";
 import { searchTree } from "../../util/tree.js";
+import { Block } from "../block/Block.js";
 import { Header, Section } from "../block/Section.js";
 import { Title } from "../block/Title.js";
 import { DocumentationKind } from "../docs/DocumentationKind.js";
@@ -64,30 +65,32 @@ export function TreeIndexPage(): ReactNode {
 
 	return (
 		<Page title={INDEX_TITLE} description={INDEX_DESCRIPTION}>
-			<Header>
-				<Title>{INDEX_TITLE}</Title>
-			</Header>
-			<Section>
-				<TextInput name="search" title="Search" placeholder="Search…" value={query} onValue={v => setQuery(v ?? "")} />
-				{!!kinds.length && (
-					<Row left wrap>
-						{kinds.map(kind => (
-							<CheckboxInput
-								key={kind}
-								name={kind}
-								width="fit"
-								value={selected.includes(kind)}
-								onValue={() => setSelected(s => toggleArrayItem(s, kind))}
-							>
-								<DocumentationKind kind={kind} />
-							</CheckboxInput>
-						))}
-					</Row>
-				)}
-			</Section>
-			<Section>
-				<TreeCards>{cards}</TreeCards>
-			</Section>
+			<Block indent="normal">
+				<Header>
+					<Title>{INDEX_TITLE}</Title>
+				</Header>
+				<Section>
+					<TextInput name="search" title="Search" placeholder="Search…" value={query} onValue={v => setQuery(v ?? "")} />
+					{!!kinds.length && (
+						<Row left wrap>
+							{kinds.map(kind => (
+								<CheckboxInput
+									key={kind}
+									name={kind}
+									width="fit"
+									value={selected.includes(kind)}
+									onValue={() => setSelected(s => toggleArrayItem(s, kind))}
+								>
+									<DocumentationKind kind={kind} />
+								</CheckboxInput>
+							))}
+						</Row>
+					)}
+				</Section>
+				<Section>
+					<TreeCards>{cards}</TreeCards>
+				</Section>
+			</Block>
 		</Page>
 	);
 }

package/ui/tree/TreePage.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Block } from "../block/Block.js";
 import { Prose } from "../block/Prose.js";
 import { Header, Section } from "../block/Section.js";
 import { Title } from "../block/Title.js";
@@ -17,5 +18,5 @@ import { TreeMarkup } from "./TreeMarkup.js";
  * @see https://shelving.cc/ui/TreePage
  */
 export function TreePage({ title, name, description, content, children }) {
-    return (_jsxs(Page, { title: title ?? name, description: description, children: [_jsx(Header, { children: _jsx(Title, { children: title ?? name }) }), _jsx(Section, { children: content && (_jsx(Prose, { children: _jsx(TreeMarkup, { children: content }) })) }), _jsx(Section, { children: _jsx(TreeCards, { children: children }) })] }));
+    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { indent: "normal", children: [_jsx(Header, { children: _jsx(Title, { children: title ?? name }) }), _jsx(Section, { children: content && (_jsx(Prose, { children: _jsx(TreeMarkup, { children: content }) })) }), _jsx(Section, { children: _jsx(TreeCards, { children: children }) })] }) }));
 }

package/ui/tree/TreePage.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { TreeElementProps } from "../../util/tree.js";
+import { Block } from "../block/Block.js";
 import { Prose } from "../block/Prose.js";
 import { Header, Section } from "../block/Section.js";
 import { Title } from "../block/Title.js";
@@ -21,19 +22,21 @@ import { TreeMarkup } from "./TreeMarkup.js";
 export function TreePage({ title, name, description, content, children }: TreeElementProps): ReactNode {
 	return (
 		<Page title={title ?? name} description={description}>
-			<Header>
-				<Title>{title ?? name}</Title>
-			</Header>
-			<Section>
-				{content && (
-					<Prose>
-						<TreeMarkup>{content}</TreeMarkup>
-					</Prose>
-				)}
-			</Section>
-			<Section>
-				<TreeCards>{children}</TreeCards>
-			</Section>
+			<Block indent="normal">
+				<Header>
+					<Title>{title ?? name}</Title>
+				</Header>
+				<Section>
+					{content && (
+						<Prose>
+							<TreeMarkup>{content}</TreeMarkup>
+						</Prose>
+					)}
+				</Section>
+				<Section>
+					<TreeCards>{children}</TreeCards>
+				</Section>
+			</Block>
 		</Page>
 	);
 }