shelving 1.253.0 → 1.253.2

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 {

package/ui/layout/CenteredLayout.tsx

@@ -1,9 +1,8 @@
 import type { ReactElement } from "react";
 import { RouteCache } from "../router/RouteCache.js";
-import { getClass, getModuleClass } from "../util/css.js";
+import { getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import CENTERED_LAYOUT_CSS from "./CenteredLayout.module.css";
-import { LAYOUT_CLASS } from "./Layout.js";
 
 /**
  * Props for `<CenteredLayout>` — optional `children` and a `fullWidth` flag to drop the max-width.
@@ -30,7 +29,7 @@ export function CenteredLayout({ children, fullWidth = false }: CenteredLayoutPr
 	// keeping their scroll position and state intact across back/forward navigation.
 	return (
 		<RouteCache>
-			<main className={getClass(getModuleClass(CENTERED_LAYOUT_CSS, "main"), LAYOUT_CLASS)}>
+			<main className={getModuleClass(CENTERED_LAYOUT_CSS, "main")}>
 				<div className={getModuleClass(CENTERED_LAYOUT_CSS, "mainInner")} style={fullWidth ? { maxWidth: "none" } : undefined}>
 					{children}
 				</div>

package/ui/layout/Layout.d.ts

@@ -1,10 +1,3 @@
-/**
- * Resolved `.layout` class for composing the layout's padding/scroll/safe-area behaviour onto a custom element.
- *
- * @example <main className={LAYOUT_CLASS}>…</main>
- * @see https://dhoulb.github.io/shelving/ui/layout/Layout/LAYOUT_CLASS
- */
-export declare const LAYOUT_CLASS: string | undefined;
 /**
  * Track the dynamic viewport height so layout safe-area insets follow the on-screen keyboard.
  *

package/ui/layout/Layout.js

@@ -1,12 +1,3 @@
-import { getModuleClass } from "../util/css.js";
-import styles from "./Layout.module.css";
-/**
- * Resolved `.layout` class for composing the layout's padding/scroll/safe-area behaviour onto a custom element.
- *
- * @example <main className={LAYOUT_CLASS}>…</main>
- * @see https://dhoulb.github.io/shelving/ui/layout/Layout/LAYOUT_CLASS
- */
-export const LAYOUT_CLASS = getModuleClass(styles, "layout");
 /**
  * Track the dynamic viewport height so layout safe-area insets follow the on-screen keyboard.
  *

package/ui/layout/Layout.ts

@@ -1,14 +1,3 @@
-import { getModuleClass } from "../util/css.js";
-import styles from "./Layout.module.css";
-
-/**
- * Resolved `.layout` class for composing the layout's padding/scroll/safe-area behaviour onto a custom element.
- *
- * @example <main className={LAYOUT_CLASS}>…</main>
- * @see https://dhoulb.github.io/shelving/ui/layout/Layout/LAYOUT_CLASS
- */
-export const LAYOUT_CLASS = getModuleClass(styles, "layout");
-
 /**
  * Track the dynamic viewport height so layout safe-area insets follow the on-screen keyboard.
  *

package/ui/layout/SidebarLayout.js

@@ -5,7 +5,6 @@ import { Button } from "../form/Button.js";
 import { requireMetaURL } from "../misc/MetaContext.js";
 import { RouteCache } from "../router/RouteCache.js";
 import { getClass, getModuleClass } from "../util/css.js";
-import { LAYOUT_CLASS } from "./Layout.js";
 import SIDEBAR_LAYOUT_CSS from "./SidebarLayout.module.css";
 /**
  * Layout with a fixed-width side column (typically navigation) next to a scrollable main content column.
@@ -37,7 +36,7 @@ export function SidebarLayout({ sidebar, children, right = false }) {
     // — keeping the scroll position of this `.content` container (and all page state) intact across
     // back/forward navigation. The sidebar and drawer state stay outside the cache, so they are neither
     // duplicated nor remounted as the URL changes.
-    const contentEl = (_jsx(RouteCache, { children: _jsxs("div", { className: getClass(LAYOUT_CLASS, getModuleClass(SIDEBAR_LAYOUT_CSS, "content")), children: [_jsx("div", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "toggle"), children: _jsx(Button, { title: open ? "Close menu" : "Show menu", onClick: () => setOpen(o => !o), children: open ? _jsx(XMarkIcon, {}) : _jsx(Bars3Icon, {}) }) }), _jsx("div", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "contentInner"), children: children })] }) }, "content"));
+    const contentEl = (_jsx(RouteCache, { children: _jsxs("div", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "content"), children: [_jsx("div", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "toggle"), children: _jsx(Button, { title: open ? "Close menu" : "Show menu", onClick: () => setOpen(o => !o), children: open ? _jsx(XMarkIcon, {}) : _jsx(Bars3Icon, {}) }) }), _jsx("div", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "contentInner"), children: children })] }) }, "content"));
     const overlayEl = open && (_jsx("button", { type: "button", className: getModuleClass(SIDEBAR_LAYOUT_CSS, "overlay"), "aria-label": "Close menu", onClick: () => setOpen(false) }, "overlay"));
-    return (_jsx("main", { className: getClass(getModuleClass(SIDEBAR_LAYOUT_CSS, "main"), LAYOUT_CLASS), children: right ? [contentEl, sidebarEl, overlayEl] : [sidebarEl, contentEl, overlayEl] }));
+    return (_jsx("main", { className: getModuleClass(SIDEBAR_LAYOUT_CSS, "main"), children: right ? [contentEl, sidebarEl, overlayEl] : [sidebarEl, contentEl, overlayEl] }));
 }