shelving 1.252.0 → 1.253.1

package/ui/docs/DocumentationPage.tsx

@@ -16,12 +16,13 @@ import { TreeMarkup } from "../tree/TreeMarkup.js";
 import { DocumentationButtons } from "./DocumentationButtons.js";
 import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKind.js";
 import { DocumentationParams } from "./DocumentationParams.js";
+import { DocumentationProperties } from "./DocumentationProperties.js";
 import { DocumentationReferences } from "./DocumentationReferences.js";
 import { DocumentationReturns } from "./DocumentationReturns.js";
 import { DocumentationSignatures } from "./DocumentationSignatures.js";
 import { DocumentationThrows } from "./DocumentationThrows.js";
 
-/** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. */
+/** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. Data members (properties) are not child elements — they render as the Properties table instead. */
 const KIND_SECTIONS = {
 	component: "Components",
 	function: "Functions",
@@ -30,9 +31,7 @@ const KIND_SECTIONS = {
 	type: "Types",
 	constant: "Constants",
 	"static method": "Static methods",
-	"static property": "Static properties",
 	method: "Methods",
-	property: "Properties",
 };
 
 /** Render a list of tree elements grouped into kind-based card sections, in `KIND_SECTIONS` order. */
@@ -68,11 +67,11 @@ function DocumentationChildren({ elements }: { readonly elements?: TreeElements
 
 /**
  * Page renderer for a `tree-documentation` element — the full detail page for a documented symbol.
- * - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, referenced types, and examples.
- * - In the Parameters / Returns / Throws tables the `Type` column links each type to its documented page via `TreeLink` (exact-match only; compound or builtin types stay plain text), and a row with no hand-written description falls back to the referenced type's own `description`. A parameter/property default renders as a `Defaults to …` line at the foot of its description cell (linking the value when it's a documented token) rather than in a dedicated column.
- * - An options-bag parameter whose type resolves to a documented interface/object type is flattened into indented child rows (one per property), so readers see the individual fields inline.
+ * - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, properties, referenced types, and examples.
+ * - In the Parameters / Returns / Throws / Properties tables the `Type` column links each type to its documented page via `TreeLink` (exact-match only; compound or builtin types stay plain text), and a row with no hand-written description falls back to the referenced type's own `description`. A default renders as a `Defaults to …` note (linking the value when it's a documented token) rather than in a dedicated column.
+ * - A class/interface/object-literal type's data members render as the Properties table (see `DocumentationProperties`); an options-bag parameter whose type resolves to one is flattened into indented child rows from the same structured list.
  * - A `type` alias's referenced type names render as a linked `Type` table, each row carrying the resolved element's `description` (exact-match only).
- * - Child symbols are grouped by `kind` into card sections (Functions, Classes, Methods, Properties, …), each under its own heading.
+ * - Child symbols (functions, classes, methods — not data members) are grouped by `kind` into card sections, each under its own heading.
  * - All sections are conditional — only render when they have entries.
  *
  * @kind component
@@ -90,6 +89,7 @@ export function DocumentationPage({
 	params,
 	returns,
 	throws,
+	properties,
 	types,
 	examples,
 	children,
@@ -110,12 +110,13 @@ export function DocumentationPage({
 						<DocumentationButtons {...props} />
 					</Header>
 				</Panel>
-				{signatures?.length || params?.length || returns?.length || throws?.length || types?.length ? (
+				{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}

package/ui/docs/DocumentationParams.js

@@ -6,28 +6,13 @@ import { Scroll } from "../style/Scroll.js";
 import { Cell } from "../table/Cell.js";
 import { Table } from "../table/Table.js";
 import { getTreeElement, useTreeMap } from "../tree/TreeContext.js";
-import { TreeLink } from "../tree/TreeLink.js";
 import { DocumentationDescription } from "./DocumentationDescription.js";
+import { DocumentationType, splitType } from "./DocumentationType.js";
 const DEFAULT_TYPE = "unknown";
 /** Indentation (non-breaking spaces, so HTML doesn't collapse it) prefixed to a flattened sub-property's name so it reads as nested under its parent param. */
 const SUBPARAM_INDENT = "\u00A0\u00A0\u00A0\u00A0";
-/**
- * Split a type expression on ` | ` into its individual union members.
- * - An `undefined` member is dropped from display and instead flags the value as optional — we often write `| undefined` explicitly (e.g. for `exactOptionalPropertyTypes`, or to allow an explicit `undefined` to trigger a default), which reads as noise in the docs.
- * - When nothing but `undefined` is left, the members are kept as-is rather than emptied.
- */
-function _splitType(type) {
-    const parts = type
-        .split(" | ")
-        .map(part => part.trim())
-        .filter(Boolean);
-    const members = parts.filter(part => part !== "undefined");
-    return members.length ? { members, optional: members.length !== parts.length } : { members: parts, optional: false };
-}
-/** Render a type expression as one linked `Type`-column token per union member, each stacked on its own line (an `undefined` member is dropped — see `_splitType`). */
-function _renderType(members) {
-    return members.map((member, index) => (_jsxs(Fragment, { children: [index > 0 && _jsx("br", {}), _jsx(TreeLink, { name: member, nowrap: true })] }, member)));
-}
+/** Kinds whose `properties` represent an options-bag worth flattening into a param's child rows — interfaces and object-literal `type` aliases, not full classes. */
+const FLATTEN_KINDS = new Set(["interface", "type"]);
 /**
  * Render a documented symbol's parameters as a scrollable table — one row per parameter.
  * - Self-contained: pulls its own copy of the tree map from `useTreeMap()` so the `Type` column can link each type to its documented page via `TreeLink` (exact-match only; compound or builtin types stay plain text).
@@ -46,14 +31,15 @@ export function DocumentationParams({ params }) {
     if (!params?.length)
         return null;
     return (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(Cell, { header: true, width: "fit", children: "Param" }), _jsx(Cell, { header: true, width: "fit", children: "Type" }), _jsx(Cell, { header: true, width: "xxnarrow", grow: true })] }) }), _jsx("tbody", { children: params.map(({ name, type = DEFAULT_TYPE, description, default: def, optional }) => {
-                            const { members, optional: typeOptional } = _splitType(type);
+                            const { members, optional: typeOptional } = splitType(type);
                             // An options-bag param whose (single, concrete) type resolves to a documented interface/object type is flattened into its individual fields as indented child rows.
                             const single = members.length === 1 ? members[0] : undefined;
                             const resolved = single ? getTreeElement(map, single)?.props : undefined;
-                            return (_jsxs(Fragment, { children: [_jsxs("tr", { children: [_jsx("td", { children: _jsx(Code, { nowrap: true, children: name }) }), _jsx("td", { children: _renderType(members) }), _jsx("td", { children: _jsx(DocumentationDescription, { description: description || resolved?.description, default: def, optional: !!optional || typeOptional }) })] }), resolved?.properties?.map(({ name: propName, type: propType = DEFAULT_TYPE, description: propDescription, default: propDef, optional: propOptional, }) => {
-                                        const { members: propMembers, optional: propTypeOptional } = _splitType(propType);
+                            const properties = resolved && FLATTEN_KINDS.has(resolved.kind ?? "") ? resolved.properties : undefined;
+                            return (_jsxs(Fragment, { children: [_jsxs("tr", { children: [_jsx("td", { children: _jsx(Code, { nowrap: true, children: name }) }), _jsx("td", { children: _jsx(DocumentationType, { members: members }) }), _jsx("td", { children: _jsx(DocumentationDescription, { description: description || resolved?.description, default: def, optional: !!optional || typeOptional }) })] }), properties?.map(({ name: propName, type: propType = DEFAULT_TYPE, description: propDescription, default: propDef, optional: propOptional, readonly: propReadonly, }) => {
+                                        const { members: propMembers, optional: propTypeOptional } = splitType(propType);
                                         const propSingle = propMembers[0] ?? DEFAULT_TYPE;
-                                        return (_jsxs("tr", { children: [_jsxs(Cell, { nowrap: true, children: [SUBPARAM_INDENT, _jsx(Code, { nowrap: true, children: `.${propName}` })] }), _jsx("td", { children: _renderType(propMembers) }), _jsx("td", { children: _jsx(DocumentationDescription, { description: propDescription || getTreeElement(map, propSingle)?.props.description, default: propDef, optional: !!propOptional || propTypeOptional }) })] }, `${propName}-${propType}-${propDescription}`));
+                                        return (_jsxs("tr", { children: [_jsxs(Cell, { nowrap: true, children: [SUBPARAM_INDENT, _jsx(Code, { nowrap: true, children: `.${propName}` })] }), _jsx("td", { children: _jsx(DocumentationType, { members: propMembers }) }), _jsx("td", { children: _jsx(DocumentationDescription, { description: propDescription || getTreeElement(map, propSingle)?.props.description, default: propDef, optional: !!propOptional || propTypeOptional, readonly: propReadonly }) })] }, `${propName}-${propType}-${propDescription}`));
                                     })] }, `${name}-${type}`));
                         }) })] }) }) }));
 }

package/ui/docs/DocumentationParams.tsx

@@ -7,37 +7,16 @@ import { Scroll } from "../style/Scroll.js";
 import { Cell } from "../table/Cell.js";
 import { Table } from "../table/Table.js";
 import { getTreeElement, useTreeMap } from "../tree/TreeContext.js";
-import { TreeLink } from "../tree/TreeLink.js";
 import { DocumentationDescription } from "./DocumentationDescription.js";
+import { DocumentationType, splitType } from "./DocumentationType.js";
 
 const DEFAULT_TYPE = "unknown";
 
 /** Indentation (non-breaking spaces, so HTML doesn't collapse it) prefixed to a flattened sub-property's name so it reads as nested under its parent param. */
 const SUBPARAM_INDENT = "\u00A0\u00A0\u00A0\u00A0";
 
-/**
- * Split a type expression on ` | ` into its individual union members.
- * - An `undefined` member is dropped from display and instead flags the value as optional — we often write `| undefined` explicitly (e.g. for `exactOptionalPropertyTypes`, or to allow an explicit `undefined` to trigger a default), which reads as noise in the docs.
- * - When nothing but `undefined` is left, the members are kept as-is rather than emptied.
- */
-function _splitType(type: string): { readonly members: readonly string[]; readonly optional: boolean } {
-	const parts = type
-		.split(" | ")
-		.map(part => part.trim())
-		.filter(Boolean);
-	const members = parts.filter(part => part !== "undefined");
-	return members.length ? { members, optional: members.length !== parts.length } : { members: parts, optional: false };
-}
-
-/** Render a type expression as one linked `Type`-column token per union member, each stacked on its own line (an `undefined` member is dropped — see `_splitType`). */
-function _renderType(members: readonly string[]): ReactNode {
-	return members.map((member, index) => (
-		<Fragment key={member}>
-			{index > 0 && <br />}
-			<TreeLink name={member} nowrap />
-		</Fragment>
-	));
-}
+/** Kinds whose `properties` represent an options-bag worth flattening into a param's child rows — interfaces and object-literal `type` aliases, not full classes. */
+const FLATTEN_KINDS = new Set(["interface", "type"]);
 
 /**
  * Props for `DocumentationParams` — the parameter list to render, one row per parameter.
@@ -82,17 +61,20 @@ export function DocumentationParams({ params }: DocumentationParamsProps): React
 					</thead>
 					<tbody>
 						{params.map(({ name, type = DEFAULT_TYPE, description, default: def, optional }) => {
-							const { members, optional: typeOptional } = _splitType(type);
+							const { members, optional: typeOptional } = splitType(type);
 							// An options-bag param whose (single, concrete) type resolves to a documented interface/object type is flattened into its individual fields as indented child rows.
 							const single = members.length === 1 ? members[0] : undefined;
 							const resolved = single ? (getTreeElement(map, single)?.props as DocumentationElementProps | undefined) : undefined;
+							const properties = resolved && FLATTEN_KINDS.has(resolved.kind ?? "") ? resolved.properties : undefined;
 							return (
 								<Fragment key={`${name}-${type}`}>
 									<tr>
 										<td>
 											<Code nowrap>{name}</Code>
 										</td>
-										<td>{_renderType(members)}</td>
+										<td>
+											<DocumentationType members={members} />
+										</td>
 										<td>
 											<DocumentationDescription
 												description={description || resolved?.description}
@@ -101,15 +83,16 @@ export function DocumentationParams({ params }: DocumentationParamsProps): React
 											/>
 										</td>
 									</tr>
-									{resolved?.properties?.map(
+									{properties?.map(
 										({
 											name: propName,
 											type: propType = DEFAULT_TYPE,
 											description: propDescription,
 											default: propDef,
 											optional: propOptional,
+											readonly: propReadonly,
 										}) => {
-											const { members: propMembers, optional: propTypeOptional } = _splitType(propType);
+											const { members: propMembers, optional: propTypeOptional } = splitType(propType);
 											const propSingle = propMembers[0] ?? DEFAULT_TYPE;
 											return (
 												<tr key={`${propName}-${propType}-${propDescription}`}>
@@ -117,12 +100,15 @@ export function DocumentationParams({ params }: DocumentationParamsProps): React
 														{SUBPARAM_INDENT}
 														<Code nowrap>{`.${propName}`}</Code>
 													</Cell>
-													<td>{_renderType(propMembers)}</td>
+													<td>
+														<DocumentationType members={propMembers} />
+													</td>
 													<td>
 														<DocumentationDescription
 															description={propDescription || getTreeElement(map, propSingle)?.props.description}
 															default={propDef}
 															optional={!!propOptional || propTypeOptional}
+															readonly={propReadonly}
 														/>
 													</td>
 												</tr>

package/ui/docs/DocumentationProperties.d.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+import type { ImmutableArray } from "../../util/array.js";
+import type { DocumentationParam } from "../../util/tree.js";
+/**
+ * Props for `DocumentationProperties` — the data members of a class/interface/object-literal type to render, one row each.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationProperties/DocumentationPropertiesProps
+ */
+export interface DocumentationPropertiesProps {
+    /** Properties to render — one row each. */
+    readonly properties?: ImmutableArray<DocumentationParam> | undefined;
+}
+/**
+ * Render a documented type's data members (properties, getters/setters) as a scrollable table — one row per property.
+ * - Self-contained: pulls its own copy of the tree map from [`useTreeMap()`](/ui/useTreeMap) so the `Type` column can link each type to its documented page via [`TreeLink`](/ui/TreeLink) (exact-match only; compound or builtin types stay plain text).
+ * - Each property name carries a leading `.` (e.g. `.caller`); a union type renders one linked token per member, each on its own line, with a `| undefined` member dropped and marking the property optional.
+ * - Descriptions render as inline markup, with a trailing `Defaults to …` (linked when documented) or `Required.` note — see [`DocumentationDescription`](/ui/DocumentationDescription). A row with no hand-written description falls back to the referenced type's own `description`.
+ * - These are the same structured entries an options-bag parameter is flattened from in [`DocumentationParams`](/ui/DocumentationParams), so the two stay in sync by construction.
+ * - Renders nothing when there are no properties.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the properties table, or `null` when there are none.
+ * @example <DocumentationProperties properties={properties} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationProperties/DocumentationProperties
+ */
+export declare function DocumentationProperties({ properties }: DocumentationPropertiesProps): ReactNode;

package/ui/docs/DocumentationProperties.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Section } from "../block/Section.js";
+import { Code } from "../inline/Code.js";
+import { Scroll } from "../style/Scroll.js";
+import { Cell } from "../table/Cell.js";
+import { Table } from "../table/Table.js";
+import { getTreeElement, useTreeMap } from "../tree/TreeContext.js";
+import { DocumentationDescription } from "./DocumentationDescription.js";
+import { DocumentationType, splitType } from "./DocumentationType.js";
+const DEFAULT_TYPE = "unknown";
+/**
+ * Render a documented type's data members (properties, getters/setters) as a scrollable table — one row per property.
+ * - Self-contained: pulls its own copy of the tree map from [`useTreeMap()`](/ui/useTreeMap) so the `Type` column can link each type to its documented page via [`TreeLink`](/ui/TreeLink) (exact-match only; compound or builtin types stay plain text).
+ * - Each property name carries a leading `.` (e.g. `.caller`); a union type renders one linked token per member, each on its own line, with a `| undefined` member dropped and marking the property optional.
+ * - Descriptions render as inline markup, with a trailing `Defaults to …` (linked when documented) or `Required.` note — see [`DocumentationDescription`](/ui/DocumentationDescription). A row with no hand-written description falls back to the referenced type's own `description`.
+ * - These are the same structured entries an options-bag parameter is flattened from in [`DocumentationParams`](/ui/DocumentationParams), so the two stay in sync by construction.
+ * - Renders nothing when there are no properties.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the properties table, or `null` when there are none.
+ * @example <DocumentationProperties properties={properties} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationProperties/DocumentationProperties
+ */
+export function DocumentationProperties({ properties }) {
+    const map = useTreeMap();
+    if (!properties?.length)
+        return null;
+    return (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(Cell, { header: true, width: "fit", children: "Property" }), _jsx(Cell, { header: true, width: "fit", children: "Type" }), _jsx(Cell, { header: true, width: "xxnarrow", grow: true })] }) }), _jsx("tbody", { children: properties.map(({ name, type = DEFAULT_TYPE, description, default: def, optional, readonly }) => {
+                            const { members, optional: typeOptional } = splitType(type);
+                            return (_jsxs("tr", { children: [_jsx(Cell, { nowrap: true, children: _jsx(Code, { nowrap: true, children: `.${name}` }) }), _jsx("td", { children: _jsx(DocumentationType, { members: members }) }), _jsx("td", { children: _jsx(DocumentationDescription, { description: description || getTreeElement(map, members[0] ?? DEFAULT_TYPE)?.props.description, default: def, optional: !!optional || typeOptional, readonly: readonly }) })] }, `${name}-${type}`));
+                        }) })] }) }) }));
+}

package/ui/docs/DocumentationProperties.tsx

@@ -0,0 +1,83 @@
+import type { ReactNode } from "react";
+import type { ImmutableArray } from "../../util/array.js";
+import type { DocumentationParam } from "../../util/tree.js";
+import { Section } from "../block/Section.js";
+import { Code } from "../inline/Code.js";
+import { Scroll } from "../style/Scroll.js";
+import { Cell } from "../table/Cell.js";
+import { Table } from "../table/Table.js";
+import { getTreeElement, useTreeMap } from "../tree/TreeContext.js";
+import { DocumentationDescription } from "./DocumentationDescription.js";
+import { DocumentationType, splitType } from "./DocumentationType.js";
+
+const DEFAULT_TYPE = "unknown";
+
+/**
+ * Props for `DocumentationProperties` — the data members of a class/interface/object-literal type to render, one row each.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationProperties/DocumentationPropertiesProps
+ */
+export interface DocumentationPropertiesProps {
+	/** Properties to render — one row each. */
+	readonly properties?: ImmutableArray<DocumentationParam> | undefined;
+}
+
+/**
+ * Render a documented type's data members (properties, getters/setters) as a scrollable table — one row per property.
+ * - Self-contained: pulls its own copy of the tree map from [`useTreeMap()`](/ui/useTreeMap) so the `Type` column can link each type to its documented page via [`TreeLink`](/ui/TreeLink) (exact-match only; compound or builtin types stay plain text).
+ * - Each property name carries a leading `.` (e.g. `.caller`); a union type renders one linked token per member, each on its own line, with a `| undefined` member dropped and marking the property optional.
+ * - Descriptions render as inline markup, with a trailing `Defaults to …` (linked when documented) or `Required.` note — see [`DocumentationDescription`](/ui/DocumentationDescription). A row with no hand-written description falls back to the referenced type's own `description`.
+ * - These are the same structured entries an options-bag parameter is flattened from in [`DocumentationParams`](/ui/DocumentationParams), so the two stay in sync by construction.
+ * - Renders nothing when there are no properties.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the properties table, or `null` when there are none.
+ * @example <DocumentationProperties properties={properties} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationProperties/DocumentationProperties
+ */
+export function DocumentationProperties({ properties }: DocumentationPropertiesProps): ReactNode {
+	const map = useTreeMap();
+	if (!properties?.length) return null;
+	return (
+		<Section>
+			<Scroll horizontal>
+				<Table>
+					<thead>
+						<tr>
+							<Cell header width="fit">
+								Property
+							</Cell>
+							<Cell header width="fit">
+								Type
+							</Cell>
+							<Cell header width="xxnarrow" grow />
+						</tr>
+					</thead>
+					<tbody>
+						{properties.map(({ name, type = DEFAULT_TYPE, description, default: def, optional, readonly }) => {
+							const { members, optional: typeOptional } = splitType(type);
+							return (
+								<tr key={`${name}-${type}`}>
+									<Cell nowrap>
+										<Code nowrap>{`.${name}`}</Code>
+									</Cell>
+									<td>
+										<DocumentationType members={members} />
+									</td>
+									<td>
+										<DocumentationDescription
+											description={description || getTreeElement(map, members[0] ?? DEFAULT_TYPE)?.props.description}
+											default={def}
+											optional={!!optional || typeOptional}
+											readonly={readonly}
+										/>
+									</td>
+								</tr>
+							);
+						})}
+					</tbody>
+				</Table>
+			</Scroll>
+		</Section>
+	);
+}

package/ui/docs/DocumentationType.d.ts

@@ -0,0 +1,33 @@
+import { type ReactNode } from "react";
+/**
+ * Split a type expression on ` | ` into its individual union members.
+ * - An `undefined` member is dropped from display and instead flags the value as optional — we often write `| undefined` explicitly (e.g. for `exactOptionalPropertyTypes`, or to allow an explicit `undefined` to trigger a default), which reads as noise in the docs.
+ * - When nothing but `undefined` is left, the members are kept as-is rather than emptied.
+ *
+ * @param type The type expression to split (e.g. `"Schemas<T> | DataSchema<T>"`).
+ * @returns The non-`undefined` members, plus whether an `undefined` member was dropped.
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationType/splitType
+ */
+export declare function splitType(type: string): {
+    readonly members: readonly string[];
+    readonly optional: boolean;
+};
+/**
+ * Props for `DocumentationType` — the union members to render (see [`splitType`](/ui/splitType)).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationType/DocumentationTypeProps
+ */
+export interface DocumentationTypeProps {
+    /** Union members to render — one linked token each, stacked on their own line. */
+    readonly members: readonly string[];
+}
+/**
+ * Render a documentation table's `Type` column — one linked token per union member, each stacked on its own line.
+ * - Each member links to its documented page via [`TreeLink`](/ui/TreeLink) (exact-match only; compound or builtin types stay plain text).
+ *
+ * @kind component
+ * @returns One [`TreeLink`](/ui/TreeLink) per member, separated by line breaks.
+ * @example <DocumentationType members={["Schemas<T>", "DataSchema<T>"]} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationType/DocumentationType
+ */
+export declare function DocumentationType({ members }: DocumentationTypeProps): ReactNode;

package/ui/docs/DocumentationType.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment } from "react";
+import { TreeLink } from "../tree/TreeLink.js";
+/**
+ * Split a type expression on ` | ` into its individual union members.
+ * - An `undefined` member is dropped from display and instead flags the value as optional — we often write `| undefined` explicitly (e.g. for `exactOptionalPropertyTypes`, or to allow an explicit `undefined` to trigger a default), which reads as noise in the docs.
+ * - When nothing but `undefined` is left, the members are kept as-is rather than emptied.
+ *
+ * @param type The type expression to split (e.g. `"Schemas<T> | DataSchema<T>"`).
+ * @returns The non-`undefined` members, plus whether an `undefined` member was dropped.
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationType/splitType
+ */
+export function splitType(type) {
+    const parts = type
+        .split(" | ")
+        .map(part => part.trim())
+        .filter(Boolean);
+    const members = parts.filter(part => part !== "undefined");
+    return members.length ? { members, optional: members.length !== parts.length } : { members: parts, optional: false };
+}
+/**
+ * Render a documentation table's `Type` column — one linked token per union member, each stacked on its own line.
+ * - Each member links to its documented page via [`TreeLink`](/ui/TreeLink) (exact-match only; compound or builtin types stay plain text).
+ *
+ * @kind component
+ * @returns One [`TreeLink`](/ui/TreeLink) per member, separated by line breaks.
+ * @example <DocumentationType members={["Schemas<T>", "DataSchema<T>"]} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationType/DocumentationType
+ */
+export function DocumentationType({ members }) {
+    return members.map((member, index) => (_jsxs(Fragment, { children: [index > 0 && _jsx("br", {}), _jsx(TreeLink, { name: member, nowrap: true })] }, member)));
+}

package/ui/docs/DocumentationType.tsx

@@ -0,0 +1,48 @@
+import { Fragment, type ReactNode } from "react";
+import { TreeLink } from "../tree/TreeLink.js";
+
+/**
+ * Split a type expression on ` | ` into its individual union members.
+ * - An `undefined` member is dropped from display and instead flags the value as optional — we often write `| undefined` explicitly (e.g. for `exactOptionalPropertyTypes`, or to allow an explicit `undefined` to trigger a default), which reads as noise in the docs.
+ * - When nothing but `undefined` is left, the members are kept as-is rather than emptied.
+ *
+ * @param type The type expression to split (e.g. `"Schemas<T> | DataSchema<T>"`).
+ * @returns The non-`undefined` members, plus whether an `undefined` member was dropped.
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationType/splitType
+ */
+export function splitType(type: string): { readonly members: readonly string[]; readonly optional: boolean } {
+	const parts = type
+		.split(" | ")
+		.map(part => part.trim())
+		.filter(Boolean);
+	const members = parts.filter(part => part !== "undefined");
+	return members.length ? { members, optional: members.length !== parts.length } : { members: parts, optional: false };
+}
+
+/**
+ * Props for `DocumentationType` — the union members to render (see [`splitType`](/ui/splitType)).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationType/DocumentationTypeProps
+ */
+export interface DocumentationTypeProps {
+	/** Union members to render — one linked token each, stacked on their own line. */
+	readonly members: readonly string[];
+}
+
+/**
+ * Render a documentation table's `Type` column — one linked token per union member, each stacked on its own line.
+ * - Each member links to its documented page via [`TreeLink`](/ui/TreeLink) (exact-match only; compound or builtin types stay plain text).
+ *
+ * @kind component
+ * @returns One [`TreeLink`](/ui/TreeLink) per member, separated by line breaks.
+ * @example <DocumentationType members={["Schemas<T>", "DataSchema<T>"]} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationType/DocumentationType
+ */
+export function DocumentationType({ members }: DocumentationTypeProps): ReactNode {
+	return members.map((member, index) => (
+		<Fragment key={member}>
+			{index > 0 && <br />}
+			<TreeLink name={member} nowrap />
+		</Fragment>
+	));
+}

package/ui/docs/index.d.ts

@@ -5,7 +5,9 @@ export * from "./DocumentationHomePage.js";
 export * from "./DocumentationKind.js";
 export * from "./DocumentationPage.js";
 export * from "./DocumentationParams.js";
+export * from "./DocumentationProperties.js";
 export * from "./DocumentationReferences.js";
 export * from "./DocumentationReturns.js";
 export * from "./DocumentationSignatures.js";
 export * from "./DocumentationThrows.js";
+export * from "./DocumentationType.js";

package/ui/docs/index.js

@@ -5,7 +5,9 @@ export * from "./DocumentationHomePage.js";
 export * from "./DocumentationKind.js";
 export * from "./DocumentationPage.js";
 export * from "./DocumentationParams.js";
+export * from "./DocumentationProperties.js";
 export * from "./DocumentationReferences.js";
 export * from "./DocumentationReturns.js";
 export * from "./DocumentationSignatures.js";
 export * from "./DocumentationThrows.js";
+export * from "./DocumentationType.js";

package/ui/docs/index.ts

@@ -5,7 +5,9 @@ export * from "./DocumentationHomePage.js";
 export * from "./DocumentationKind.js";
 export * from "./DocumentationPage.js";
 export * from "./DocumentationParams.js";
+export * from "./DocumentationProperties.js";
 export * from "./DocumentationReferences.js";
 export * from "./DocumentationReturns.js";
 export * from "./DocumentationSignatures.js";
 export * from "./DocumentationThrows.js";
+export * from "./DocumentationType.js";

package/ui/layout/CenteredLayout.js

@@ -1,8 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { RouteCache } from "../router/RouteCache.js";
-import { getClass, getModuleClass } from "../util/css.js";
+import { getModuleClass } from "../util/css.js";
 import CENTERED_LAYOUT_CSS from "./CenteredLayout.module.css";
-import { LAYOUT_CLASS } from "./Layout.js";
 /**
  * Layout that centres its content with no header/footer and a narrow max-width.
  * - Used for e.g. login/register/error/form pages where the content is the only focus.
@@ -17,5 +16,5 @@ import { LAYOUT_CLASS } from "./Layout.js";
 export function CenteredLayout({ children, fullWidth = false }) {
     // Wrap the scrolling `<main>` in `<RouteCache>` so recently-visited pages stay mounted but hidden,
     // keeping their scroll position and state intact across back/forward navigation.
-    return (_jsx(RouteCache, { children: _jsx("main", { className: getClass(getModuleClass(CENTERED_LAYOUT_CSS, "main"), LAYOUT_CLASS), children: _jsx("div", { className: getModuleClass(CENTERED_LAYOUT_CSS, "mainInner"), style: fullWidth ? { maxWidth: "none" } : undefined, children: children }) }) }));
+    return (_jsx(RouteCache, { children: _jsx("main", { className: getModuleClass(CENTERED_LAYOUT_CSS, "main"), children: _jsx("div", { className: getModuleClass(CENTERED_LAYOUT_CSS, "mainInner"), style: fullWidth ? { maxWidth: "none" } : undefined, children: children }) }) }));
 }

package/ui/layout/CenteredLayout.md

@@ -27,6 +27,6 @@ Layouts compose naturally as `<Router>` route values — wrap a group of routes
 
 ## Styling
 
-This layout exposes no own `--centered-layout-*` hooks. The inner column is capped at the global `--width-wide` token (dropped when `fullWidth` is set), and the outer element composes the shared `.layout` behaviour, so it reads the layout hooks `--layout-space`, `--layout-padding`, and `--layout-inset-top` / `-bottom` / `-left` / `-right`.
+This layout exposes no own `--centered-layout-*` hooks. The inner column is capped at the global `--width-wide` token (dropped when `fullWidth` is set), and the outer element owns its scroll, padding, and safe-area behaviour directly — reading the layout hooks `--layout-space`, `--layout-padding`, `--layout-body-bg`, and `--layout-inset-top` / `-bottom` / `-left` / `-right`.
 
 **Global tokens it reads** — `--width-wide`.

package/ui/layout/CenteredLayout.module.css

@@ -1,13 +1,73 @@
 @import "../style/layers.css";
+@import "../style/Space.module.css";
+@import "../style/Tint.module.css";
 @import "../style/Width.module.css";
 
+/* Low-priority padding defaults live in `@layer defaults` so consumers can override them */
+/* with normal-specificity selectors without needing `:where()` tricks. */
+@layer defaults {
+	.main {
+		/* Top/bottom use `layout-space` and left/right use `layout-padding`, plus safe-area additions. */
+		padding: var(--layout-space, var(--space-normal)) var(--layout-padding, var(--space-normal));
+		padding-top: calc(var(--layout-space, var(--space-normal)) + max(var(--layout-inset-top, 0px), env(safe-area-inset-top, 0px)));
+		padding-bottom: calc(var(--layout-space, var(--space-normal)) + max(var(--layout-inset-bottom, 0px), env(safe-area-inset-bottom, 0px)));
+		padding-left: calc(var(--layout-padding, var(--space-normal)) + max(var(--layout-inset-left, 0px), env(safe-area-inset-left, 0px)));
+		padding-right: calc(var(--layout-padding, var(--space-normal)) + max(var(--layout-inset-right, 0px), env(safe-area-inset-right, 0px)));
+
+		/* Grow to fill the body. */
+		flex: 1;
+	}
+}
+
 @layer components {
+	/*
+	 * Lock the document and let `.main` own the page scroll.
+	 * - <html> and <body> are pinned to the viewport (no rubber-band on iOS).
+	 * - <body> stacks its children vertically (flex column).
+	 * - The `.main` element grows to fill the body and is the only scroll container.
+	 */
+	html:has(.main) {
+		/* Box */
+		margin: 0;
+		padding: 0;
+		height: 100vh;
+		height: 100dvh; /* Make the height dynamically expand/contract as the address bar shows/hides on iOS. */
+		width: 100vw;
+		width: 100dvw;
+
+		/* Contents */
+		overflow: hidden;
+		overflow-wrap: break-word; /* Break overlong words only as a last resort. */
+	}
+
+	body:has(.main) {
+		/* Box */
+		margin: 0;
+		padding: 0;
+		display: flex;
+		flex-direction: column;
+
+		/* Lock body to prevent iOS Safari triggering viewport scrolling on focus change. */
+		position: fixed;
+		inset: 0;
+
+		/* Layout-specific bg hook. */
+		background: var(--layout-body-bg, var(--tint-100));
+	}
+
 	.main {
-		/* Content */
+		/* Content — a flex column whose inner column centres itself with `margin: auto` (both axes). */
 		display: flex;
 		flex-direction: column;
 		align-items: center;
 		justify-content: start;
+
+		/* Scrolling */
+		overflow-x: hidden;
+		overflow-y: auto;
+		overscroll-behavior-x: auto;
+		overscroll-behavior-y: contain;
+		scroll-behavior: smooth;
 	}
 
 	.mainInner {