shelving 1.251.0 → 1.251.1

package/package.json

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

package/ui/docs/DocumentationPage.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 import type { DocumentationElementProps } from "../../util/tree.js";
 /**
  * Page renderer for a `tree-documentation` element — the full detail page for a documented symbol.

package/ui/docs/DocumentationPage.js

@@ -1,5 +1,4 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment } from "react";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { walkElements } from "../../util/element.js";
 import { Block } from "../block/Block.js";
 import { Heading } from "../block/Heading.js";
@@ -8,31 +7,18 @@ import { Preformatted } from "../block/Preformatted.js";
 import { Prose } from "../block/Prose.js";
 import { Header, Section } from "../block/Section.js";
 import { Title } from "../block/Title.js";
-import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
 import { Page } from "../page/Page.js";
 import { Row } from "../style/Flex.js";
-import { Scroll } from "../style/Scroll.js";
-import { Cell } from "../table/Cell.js";
-import { Table } from "../table/Table.js";
 import { TreeBreadcrumbs } from "../tree/TreeBreadcrumbs.js";
 import { TreeCards } from "../tree/TreeCards.js";
-import { getTreeElement, useTreeMap } from "../tree/TreeContext.js";
-import { TreeLink } from "../tree/TreeLink.js";
 import { DocumentationButtons } from "./DocumentationButtons.js";
 import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKind.js";
+import { DocumentationParams } from "./DocumentationParams.js";
+import { DocumentationReferences } from "./DocumentationReferences.js";
+import { DocumentationReturns } from "./DocumentationReturns.js";
 import { DocumentationSignatures } from "./DocumentationSignatures.js";
-const DEFAULT_TYPE = "unknown";
-/** Resolve a table row's description — the manually-written one, falling back to the referenced type's own `description` from the tree map (exact-match only). */
-function _getRowDescription(map, type, description) {
-    return description || getTreeElement(map, type)?.props.description || "";
-}
-/** Render a parameter/property row's description, appending a `Defaults to …` line (linking the value if it's a documented token) when a default exists. */
-function _renderRowDescription(description, def) {
-    if (!def)
-        return description;
-    return (_jsxs(_Fragment, { children: [description, description && _jsx("br", {}), "Defaults to ", _jsx(TreeLink, { name: def })] }));
-}
+import { DocumentationThrows } from "./DocumentationThrows.js";
 /** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. */
 const KIND_SECTIONS = {
     component: "Components",
@@ -84,10 +70,5 @@ function DocumentationChildren({ elements }) {
  * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationPage/DocumentationPage
  */
 export function DocumentationPage({ title, name, kind = "unknown", description, content, signatures, params, returns, throws, types, examples, children, ...props }) {
-    const map = useTreeMap();
-    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 || types?.length ? (_jsxs(Section, { children: [_jsx(DocumentationSignatures, { signatures: signatures }), params?.length && (_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 }) => {
-                                                // An options-bag param whose type resolves to a documented interface/object type is flattened into its individual fields as indented child rows.
-                                                const resolved = getTreeElement(map, type)?.props;
-                                                return (_jsxs(Fragment, { children: [_jsxs("tr", { children: [_jsx("td", { children: _jsx(Code, { nowrap: true, children: name }) }), _jsx("td", { children: _jsx(TreeLink, { name: type, nowrap: true }) }), _jsx("td", { children: _renderRowDescription(description || resolved?.description || "", def) })] }), resolved?.properties?.map(prop => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(Code, { nowrap: true, children: `.${prop.name}` }) }), _jsx("td", { children: _jsx(TreeLink, { name: prop.type ?? DEFAULT_TYPE, nowrap: true }) }), _jsx("td", { children: _renderRowDescription(_getRowDescription(map, prop.type ?? DEFAULT_TYPE, prop.description), prop.default) })] }, `${name}.${prop.name}`)))] }, `${name}-${type}`));
-                                            }) })] }) }) })), returns?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsx("tr", { children: _jsx("th", { children: "Return" }) }) }), _jsx("tbody", { children: returns.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type, nowrap: true }) }), _jsx("td", { children: _getRowDescription(map, type, description) })] }, `${type}-${description}`))) })] }) }) })), throws?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsx("tr", { children: _jsx("th", { children: "Throws" }) }) }), _jsx("tbody", { children: throws.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type, nowrap: true }) }), _jsx("td", { children: _getRowDescription(map, type, description) })] }, `${type}-${description}`))) })] }) }) })), types?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsx("tr", { children: _jsx("th", { children: "Type" }) }) }), _jsx("tbody", { children: types.map(type => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type }) }), _jsx("td", { children: _getRowDescription(map, type) })] }, type))) })] }) }) }))] })) : null, content && (_jsx(Section, { children: _jsx(Prose, { children: _jsx(Markup, { 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 })] }) }), signatures?.length || params?.length || returns?.length || throws?.length || types?.length ? (_jsxs(Section, { children: [_jsx(DocumentationSignatures, { signatures: signatures }), _jsx(DocumentationParams, { params: params }), _jsx(DocumentationReturns, { returns: returns }), _jsx(DocumentationThrows, { throws: throws }), _jsx(DocumentationReferences, { types: types })] })) : null, content && (_jsx(Section, { children: _jsx(Prose, { children: _jsx(Markup, { 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

@@ -1,4 +1,4 @@
-import { Fragment, type ReactNode } from "react";
+import type { ReactNode } from "react";
 import { walkElements } from "../../util/element.js";
 import type { DocumentationElementProps, TreeElement, TreeElements } from "../../util/tree.js";
 import { Block } from "../block/Block.js";
@@ -8,39 +8,18 @@ import { Preformatted } from "../block/Preformatted.js";
 import { Prose } from "../block/Prose.js";
 import { Header, Section } from "../block/Section.js";
 import { Title } from "../block/Title.js";
-import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
 import { Page } from "../page/Page.js";
 import { Row } from "../style/Flex.js";
-import { Scroll } from "../style/Scroll.js";
-import { Cell } from "../table/Cell.js";
-import { Table } from "../table/Table.js";
 import { TreeBreadcrumbs } from "../tree/TreeBreadcrumbs.js";
 import { TreeCards } from "../tree/TreeCards.js";
-import { getTreeElement, useTreeMap } from "../tree/TreeContext.js";
-import { TreeLink } from "../tree/TreeLink.js";
 import { DocumentationButtons } from "./DocumentationButtons.js";
 import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKind.js";
+import { DocumentationParams } from "./DocumentationParams.js";
+import { DocumentationReferences } from "./DocumentationReferences.js";
+import { DocumentationReturns } from "./DocumentationReturns.js";
 import { DocumentationSignatures } from "./DocumentationSignatures.js";
-
-const DEFAULT_TYPE = "unknown";
-
-/** Resolve a table row's description — the manually-written one, falling back to the referenced type's own `description` from the tree map (exact-match only). */
-function _getRowDescription(map: ReadonlyMap<string, TreeElement>, type: string, description?: string | undefined): string {
-	return description || getTreeElement(map, type)?.props.description || "";
-}
-
-/** Render a parameter/property row's description, appending a `Defaults to …` line (linking the value if it's a documented token) when a default exists. */
-function _renderRowDescription(description: string, def?: string | undefined): ReactNode {
-	if (!def) return description;
-	return (
-		<>
-			{description}
-			{description && <br />}
-			Defaults to <TreeLink name={def} />
-		</>
-	);
-}
+import { DocumentationThrows } from "./DocumentationThrows.js";
 
 /** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. */
 const KIND_SECTIONS = {
@@ -116,7 +95,6 @@ export function DocumentationPage({
 	children,
 	...props
 }: DocumentationElementProps): ReactNode {
-	const map = useTreeMap();
 	return (
 		<Page title={title ?? name} description={description}>
 			<Block color={getDocumentationKindColor(kind)}>
@@ -135,129 +113,10 @@ export function DocumentationPage({
 				{signatures?.length || params?.length || returns?.length || throws?.length || types?.length ? (
 					<Section>
 						<DocumentationSignatures signatures={signatures} />
-						{params?.length && (
-							<Section>
-								<Scroll horizontal>
-									<Table>
-										<thead>
-											<tr>
-												<Cell header width="fit">
-													Param
-												</Cell>
-												<Cell header width="fit">
-													Type
-												</Cell>
-												<Cell header width="xxnarrow" grow />
-											</tr>
-										</thead>
-										<tbody>
-											{params.map(({ name, type = DEFAULT_TYPE, description, default: def }) => {
-												// An options-bag param whose type resolves to a documented interface/object type is flattened into its individual fields as indented child rows.
-												const resolved = getTreeElement(map, type)?.props as DocumentationElementProps | undefined;
-												return (
-													<Fragment key={`${name}-${type}`}>
-														<tr>
-															<td>
-																<Code nowrap>{name}</Code>
-															</td>
-															<td>
-																<TreeLink name={type} nowrap />
-															</td>
-															<td>{_renderRowDescription(description || resolved?.description || "", def)}</td>
-														</tr>
-														{resolved?.properties?.map(prop => (
-															<tr key={`${name}.${prop.name}`}>
-																<td>
-																	<Code nowrap>{`.${prop.name}`}</Code>
-																</td>
-																<td>
-																	<TreeLink name={prop.type ?? DEFAULT_TYPE} nowrap />
-																</td>
-																<td>
-																	{_renderRowDescription(
-																		_getRowDescription(map, prop.type ?? DEFAULT_TYPE, prop.description),
-																		prop.default,
-																	)}
-																</td>
-															</tr>
-														))}
-													</Fragment>
-												);
-											})}
-										</tbody>
-									</Table>
-								</Scroll>
-							</Section>
-						)}
-						{returns?.length && (
-							<Section>
-								<Scroll horizontal>
-									<Table>
-										<thead>
-											<tr>
-												<th>Return</th>
-											</tr>
-										</thead>
-										<tbody>
-											{returns.map(({ type = DEFAULT_TYPE, description }) => (
-												<tr key={`${type}-${description}`}>
-													<td>
-														<TreeLink name={type} nowrap />
-													</td>
-													<td>{_getRowDescription(map, type, description)}</td>
-												</tr>
-											))}
-										</tbody>
-									</Table>
-								</Scroll>
-							</Section>
-						)}
-						{throws?.length && (
-							<Section>
-								<Scroll horizontal>
-									<Table>
-										<thead>
-											<tr>
-												<th>Throws</th>
-											</tr>
-										</thead>
-										<tbody>
-											{throws.map(({ type = DEFAULT_TYPE, description }) => (
-												<tr key={`${type}-${description}`}>
-													<td>
-														<TreeLink name={type} nowrap />
-													</td>
-													<td>{_getRowDescription(map, type, description)}</td>
-												</tr>
-											))}
-										</tbody>
-									</Table>
-								</Scroll>
-							</Section>
-						)}
-						{types?.length && (
-							<Section>
-								<Scroll horizontal>
-									<Table>
-										<thead>
-											<tr>
-												<th>Type</th>
-											</tr>
-										</thead>
-										<tbody>
-											{types.map(type => (
-												<tr key={type}>
-													<td>
-														<TreeLink name={type} />
-													</td>
-													<td>{_getRowDescription(map, type)}</td>
-												</tr>
-											))}
-										</tbody>
-									</Table>
-								</Scroll>
-							</Section>
-						)}
+						<DocumentationParams params={params} />
+						<DocumentationReturns returns={returns} />
+						<DocumentationThrows throws={throws} />
+						<DocumentationReferences types={types} />
 					</Section>
 				) : null}
 				{content && (

package/ui/docs/DocumentationParams.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from "react";
+import type { ImmutableArray } from "../../util/array.js";
+import type { DocumentationParam } from "../../util/tree.js";
+/**
+ * Props for `DocumentationParams` — the parameter list to render, one row per parameter.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationParams/DocumentationParamsProps
+ */
+export interface DocumentationParamsProps {
+    /** Parameters to render — one row each, with options-bag params flattened into indented child rows. */
+    readonly params?: ImmutableArray<DocumentationParam> | undefined;
+}
+/**
+ * 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()`](/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).
+ * - A row with no hand-written description falls back to the referenced type's own `description`, and a default renders as a `Defaults to …` line at the foot of the description cell (linking the value when it's a documented token).
+ * - 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 nothing when there are no parameters.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the parameters table, or `null` when there are none.
+ * @example <DocumentationParams params={params} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationParams/DocumentationParams
+ */
+export declare function DocumentationParams({ params }: DocumentationParamsProps): ReactNode;

package/ui/docs/DocumentationParams.js

@@ -0,0 +1,32 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment } from "react";
+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 { TreeLink } from "../tree/TreeLink.js";
+const DEFAULT_TYPE = "unknown";
+/**
+ * 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()`](/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).
+ * - A row with no hand-written description falls back to the referenced type's own `description`, and a default renders as a `Defaults to …` line at the foot of the description cell (linking the value when it's a documented token).
+ * - 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 nothing when there are no parameters.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the parameters table, or `null` when there are none.
+ * @example <DocumentationParams params={params} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationParams/DocumentationParams
+ */
+export function DocumentationParams({ params }) {
+    const map = useTreeMap();
+    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 }) => {
+                            // An options-bag param whose type resolves to a documented interface/object type is flattened into its individual fields as indented child rows.
+                            const resolved = getTreeElement(map, type)?.props;
+                            return (_jsxs(Fragment, { children: [_jsxs("tr", { children: [_jsx("td", { children: _jsx(Code, { nowrap: true, children: name }) }), _jsx("td", { children: _jsx(TreeLink, { name: type, nowrap: true }) }), _jsxs("td", { children: [description || getTreeElement(map, type)?.props.description, def && (_jsxs(_Fragment, { children: ["Defaults to ", _jsx(TreeLink, { name: def })] }))] })] }), resolved?.properties?.map(({ name: propName, type: propType = DEFAULT_TYPE, description: propDescription, default: propDef }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(Code, { nowrap: true, children: `.${propName}` }) }), _jsx("td", { children: _jsx(TreeLink, { name: propType, nowrap: true }) }), _jsxs("td", { children: [propDescription || getTreeElement(map, propType)?.props.description, propDef && (_jsxs(_Fragment, { children: ["Defaults to ", _jsx(TreeLink, { name: propDef })] }))] })] }, `${propName}-${propType}-${propDescription}`)))] }, `${name}-${type}`));
+                        }) })] }) }) }));
+}

package/ui/docs/DocumentationParams.tsx

@@ -0,0 +1,104 @@
+import { Fragment, type ReactNode } from "react";
+import type { ImmutableArray } from "../../util/array.js";
+import type { DocumentationElementProps, 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 { TreeLink } from "../tree/TreeLink.js";
+
+const DEFAULT_TYPE = "unknown";
+
+/**
+ * Props for `DocumentationParams` — the parameter list to render, one row per parameter.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationParams/DocumentationParamsProps
+ */
+export interface DocumentationParamsProps {
+	/** Parameters to render — one row each, with options-bag params flattened into indented child rows. */
+	readonly params?: ImmutableArray<DocumentationParam> | undefined;
+}
+
+/**
+ * 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()`](/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).
+ * - A row with no hand-written description falls back to the referenced type's own `description`, and a default renders as a `Defaults to …` line at the foot of the description cell (linking the value when it's a documented token).
+ * - 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 nothing when there are no parameters.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the parameters table, or `null` when there are none.
+ * @example <DocumentationParams params={params} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationParams/DocumentationParams
+ */
+export function DocumentationParams({ params }: DocumentationParamsProps): ReactNode {
+	const map = useTreeMap();
+	if (!params?.length) return null;
+	return (
+		<Section>
+			<Scroll horizontal>
+				<Table>
+					<thead>
+						<tr>
+							<Cell header width="fit">
+								Param
+							</Cell>
+							<Cell header width="fit">
+								Type
+							</Cell>
+							<Cell header width="xxnarrow" grow />
+						</tr>
+					</thead>
+					<tbody>
+						{params.map(({ name, type = DEFAULT_TYPE, description, default: def }) => {
+							// An options-bag param whose type resolves to a documented interface/object type is flattened into its individual fields as indented child rows.
+							const resolved = getTreeElement(map, type)?.props as DocumentationElementProps | undefined;
+							return (
+								<Fragment key={`${name}-${type}`}>
+									<tr>
+										<td>
+											<Code nowrap>{name}</Code>
+										</td>
+										<td>
+											<TreeLink name={type} nowrap />
+										</td>
+										<td>
+											{description || getTreeElement(map, type)?.props.description}
+											{def && (
+												<>
+													Defaults to <TreeLink name={def} />
+												</>
+											)}
+										</td>
+									</tr>
+									{resolved?.properties?.map(
+										({ name: propName, type: propType = DEFAULT_TYPE, description: propDescription, default: propDef }) => (
+											<tr key={`${propName}-${propType}-${propDescription}`}>
+												<td>
+													<Code nowrap>{`.${propName}`}</Code>
+												</td>
+												<td>
+													<TreeLink name={propType} nowrap />
+												</td>
+												<td>
+													{propDescription || getTreeElement(map, propType)?.props.description}
+													{propDef && (
+														<>
+															Defaults to <TreeLink name={propDef} />
+														</>
+													)}
+												</td>
+											</tr>
+										),
+									)}
+								</Fragment>
+							);
+						})}
+					</tbody>
+				</Table>
+			</Scroll>
+		</Section>
+	);
+}

package/ui/docs/DocumentationReferences.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+import type { ImmutableArray } from "../../util/array.js";
+/**
+ * Props for `DocumentationReferences` — the referenced type names to render, one row each.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationReferences/DocumentationReferencesProps
+ */
+export interface DocumentationReferencesProps {
+    /** Type names referenced by a `type` alias's body — one row each, resolved to links at render time. */
+    readonly types?: ImmutableArray<string> | undefined;
+}
+/**
+ * Render a `type` alias's referenced type names as a scrollable table — one row per referenced type.
+ * - Self-contained: pulls its own copy of the tree map from [`useTreeMap()`](/ui/useTreeMap) so each name links to its documented page via [`TreeLink`](/ui/TreeLink) (exact-match only; unresolved names stay plain text), with the row carrying the resolved element's `description`.
+ * - Renders nothing when there are no referenced types.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the references table, or `null` when there are none.
+ * @example <DocumentationReferences types={types} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationReferences/DocumentationReferences
+ */
+export declare function DocumentationReferences({ types }: DocumentationReferencesProps): ReactNode;

package/ui/docs/DocumentationReferences.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Section } from "../block/Section.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 { TreeLink } from "../tree/TreeLink.js";
+/**
+ * Render a `type` alias's referenced type names as a scrollable table — one row per referenced type.
+ * - Self-contained: pulls its own copy of the tree map from [`useTreeMap()`](/ui/useTreeMap) so each name links to its documented page via [`TreeLink`](/ui/TreeLink) (exact-match only; unresolved names stay plain text), with the row carrying the resolved element's `description`.
+ * - Renders nothing when there are no referenced types.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the references table, or `null` when there are none.
+ * @example <DocumentationReferences types={types} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationReferences/DocumentationReferences
+ */
+export function DocumentationReferences({ types }) {
+    const map = useTreeMap();
+    if (!types?.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: "Type" }), _jsx(Cell, { header: true, width: "xxnarrow", grow: true })] }) }), _jsx("tbody", { children: types.map(type => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type }) }), _jsx("td", { children: getTreeElement(map, type)?.props.description })] }, type))) })] }) }) }));
+}

package/ui/docs/DocumentationReferences.tsx

@@ -0,0 +1,59 @@
+import type { ReactNode } from "react";
+import type { ImmutableArray } from "../../util/array.js";
+import { Section } from "../block/Section.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 { TreeLink } from "../tree/TreeLink.js";
+
+/**
+ * Props for `DocumentationReferences` — the referenced type names to render, one row each.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationReferences/DocumentationReferencesProps
+ */
+export interface DocumentationReferencesProps {
+	/** Type names referenced by a `type` alias's body — one row each, resolved to links at render time. */
+	readonly types?: ImmutableArray<string> | undefined;
+}
+
+/**
+ * Render a `type` alias's referenced type names as a scrollable table — one row per referenced type.
+ * - Self-contained: pulls its own copy of the tree map from [`useTreeMap()`](/ui/useTreeMap) so each name links to its documented page via [`TreeLink`](/ui/TreeLink) (exact-match only; unresolved names stay plain text), with the row carrying the resolved element's `description`.
+ * - Renders nothing when there are no referenced types.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the references table, or `null` when there are none.
+ * @example <DocumentationReferences types={types} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationReferences/DocumentationReferences
+ */
+export function DocumentationReferences({ types }: DocumentationReferencesProps): ReactNode {
+	const map = useTreeMap();
+	if (!types?.length) return null;
+	return (
+		<Section>
+			<Scroll horizontal>
+				<Table>
+					<thead>
+						<tr>
+							<Cell header width="fit">
+								Type
+							</Cell>
+							<Cell header width="xxnarrow" grow />
+						</tr>
+					</thead>
+					<tbody>
+						{types.map(type => (
+							<tr key={type}>
+								<td>
+									<TreeLink name={type} />
+								</td>
+								<td>{getTreeElement(map, type)?.props.description}</td>
+							</tr>
+						))}
+					</tbody>
+				</Table>
+			</Scroll>
+		</Section>
+	);
+}

package/ui/docs/DocumentationReturns.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from "react";
+import type { ImmutableArray } from "../../util/array.js";
+import type { DocumentationReturn } from "../../util/tree.js";
+/**
+ * Props for `DocumentationReturns` — the `@returns` entries to render, one row each.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationReturns/DocumentationReturnsProps
+ */
+export interface DocumentationReturnsProps {
+    /** Return entries to render — one row per documented return type. */
+    readonly returns?: ImmutableArray<DocumentationReturn> | undefined;
+}
+/**
+ * Render a documented symbol's `@returns` entries as a scrollable table — one row per return type.
+ * - 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).
+ * - A row with no hand-written description falls back to the referenced type's own `description`.
+ * - Renders nothing when there are no return entries.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the returns table, or `null` when there are none.
+ * @example <DocumentationReturns returns={returns} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationReturns/DocumentationReturns
+ */
+export declare function DocumentationReturns({ returns }: DocumentationReturnsProps): ReactNode;

package/ui/docs/DocumentationReturns.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Section } from "../block/Section.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 { TreeLink } from "../tree/TreeLink.js";
+const DEFAULT_TYPE = "unknown";
+/**
+ * Render a documented symbol's `@returns` entries as a scrollable table — one row per return type.
+ * - 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).
+ * - A row with no hand-written description falls back to the referenced type's own `description`.
+ * - Renders nothing when there are no return entries.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the returns table, or `null` when there are none.
+ * @example <DocumentationReturns returns={returns} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationReturns/DocumentationReturns
+ */
+export function DocumentationReturns({ returns }) {
+    const map = useTreeMap();
+    if (!returns?.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: "Return" }), _jsx(Cell, { header: true, width: "xxnarrow", grow: true })] }) }), _jsx("tbody", { children: returns.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type, nowrap: true }) }), _jsx("td", { children: description || getTreeElement(map, type)?.props.description })] }, `${type}-${description}`))) })] }) }) }));
+}

package/ui/docs/DocumentationReturns.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from "react";
+import type { ImmutableArray } from "../../util/array.js";
+import type { DocumentationReturn } from "../../util/tree.js";
+import { Section } from "../block/Section.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 { TreeLink } from "../tree/TreeLink.js";
+
+const DEFAULT_TYPE = "unknown";
+
+/**
+ * Props for `DocumentationReturns` — the `@returns` entries to render, one row each.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationReturns/DocumentationReturnsProps
+ */
+export interface DocumentationReturnsProps {
+	/** Return entries to render — one row per documented return type. */
+	readonly returns?: ImmutableArray<DocumentationReturn> | undefined;
+}
+
+/**
+ * Render a documented symbol's `@returns` entries as a scrollable table — one row per return type.
+ * - 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).
+ * - A row with no hand-written description falls back to the referenced type's own `description`.
+ * - Renders nothing when there are no return entries.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the returns table, or `null` when there are none.
+ * @example <DocumentationReturns returns={returns} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationReturns/DocumentationReturns
+ */
+export function DocumentationReturns({ returns }: DocumentationReturnsProps): ReactNode {
+	const map = useTreeMap();
+	if (!returns?.length) return null;
+	return (
+		<Section>
+			<Scroll horizontal>
+				<Table>
+					<thead>
+						<tr>
+							<Cell header width="fit">
+								Return
+							</Cell>
+							<Cell header width="xxnarrow" grow />
+						</tr>
+					</thead>
+					<tbody>
+						{returns.map(({ type = DEFAULT_TYPE, description }) => (
+							<tr key={`${type}-${description}`}>
+								<td>
+									<TreeLink name={type} nowrap />
+								</td>
+								<td>{description || getTreeElement(map, type)?.props.description}</td>
+							</tr>
+						))}
+					</tbody>
+				</Table>
+			</Scroll>
+		</Section>
+	);
+}

package/ui/docs/DocumentationThrows.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from "react";
+import type { ImmutableArray } from "../../util/array.js";
+import type { DocumentationThrow } from "../../util/tree.js";
+/**
+ * Props for `DocumentationThrows` — the `@throws` entries to render, one row each.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationThrows/DocumentationThrowsProps
+ */
+export interface DocumentationThrowsProps {
+    /** Throw entries to render — one row per documented thrown type. */
+    readonly throws?: ImmutableArray<DocumentationThrow> | undefined;
+}
+/**
+ * Render a documented symbol's `@throws` entries as a scrollable table — one row per thrown type.
+ * - 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).
+ * - A row with no hand-written description falls back to the referenced type's own `description`.
+ * - Renders nothing when there are no throw entries.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the throws table, or `null` when there are none.
+ * @example <DocumentationThrows throws={throws} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationThrows/DocumentationThrows
+ */
+export declare function DocumentationThrows({ throws }: DocumentationThrowsProps): ReactNode;

package/ui/docs/DocumentationThrows.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Section } from "../block/Section.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 { TreeLink } from "../tree/TreeLink.js";
+const DEFAULT_TYPE = "unknown";
+/**
+ * Render a documented symbol's `@throws` entries as a scrollable table — one row per thrown type.
+ * - 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).
+ * - A row with no hand-written description falls back to the referenced type's own `description`.
+ * - Renders nothing when there are no throw entries.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the throws table, or `null` when there are none.
+ * @example <DocumentationThrows throws={throws} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationThrows/DocumentationThrows
+ */
+export function DocumentationThrows({ throws }) {
+    const map = useTreeMap();
+    if (!throws?.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: "Throws" }), _jsx(Cell, { header: true, width: "xxnarrow", grow: true })] }) }), _jsx("tbody", { children: throws.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type, nowrap: true }) }), _jsx("td", { children: description || getTreeElement(map, type)?.props.description })] }, `${type}-${description}`))) })] }) }) }));
+}

package/ui/docs/DocumentationThrows.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from "react";
+import type { ImmutableArray } from "../../util/array.js";
+import type { DocumentationThrow } from "../../util/tree.js";
+import { Section } from "../block/Section.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 { TreeLink } from "../tree/TreeLink.js";
+
+const DEFAULT_TYPE = "unknown";
+
+/**
+ * Props for `DocumentationThrows` — the `@throws` entries to render, one row each.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationThrows/DocumentationThrowsProps
+ */
+export interface DocumentationThrowsProps {
+	/** Throw entries to render — one row per documented thrown type. */
+	readonly throws?: ImmutableArray<DocumentationThrow> | undefined;
+}
+
+/**
+ * Render a documented symbol's `@throws` entries as a scrollable table — one row per thrown type.
+ * - 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).
+ * - A row with no hand-written description falls back to the referenced type's own `description`.
+ * - Renders nothing when there are no throw entries.
+ *
+ * @kind component
+ * @returns A [`<Section>`](/ui/Section) containing the throws table, or `null` when there are none.
+ * @example <DocumentationThrows throws={throws} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationThrows/DocumentationThrows
+ */
+export function DocumentationThrows({ throws }: DocumentationThrowsProps): ReactNode {
+	const map = useTreeMap();
+	if (!throws?.length) return null;
+	return (
+		<Section>
+			<Scroll horizontal>
+				<Table>
+					<thead>
+						<tr>
+							<Cell header width="fit">
+								Throws
+							</Cell>
+							<Cell header width="xxnarrow" grow />
+						</tr>
+					</thead>
+					<tbody>
+						{throws.map(({ type = DEFAULT_TYPE, description }) => (
+							<tr key={`${type}-${description}`}>
+								<td>
+									<TreeLink name={type} nowrap />
+								</td>
+								<td>{description || getTreeElement(map, type)?.props.description}</td>
+							</tr>
+						))}
+					</tbody>
+				</Table>
+			</Scroll>
+		</Section>
+	);
+}

package/ui/docs/index.d.ts

@@ -3,4 +3,8 @@ export * from "./DocumentationCard.js";
 export * from "./DocumentationHomePage.js";
 export * from "./DocumentationKind.js";
 export * from "./DocumentationPage.js";
+export * from "./DocumentationParams.js";
+export * from "./DocumentationReferences.js";
+export * from "./DocumentationReturns.js";
 export * from "./DocumentationSignatures.js";
+export * from "./DocumentationThrows.js";

package/ui/docs/index.js

@@ -3,4 +3,8 @@ export * from "./DocumentationCard.js";
 export * from "./DocumentationHomePage.js";
 export * from "./DocumentationKind.js";
 export * from "./DocumentationPage.js";
+export * from "./DocumentationParams.js";
+export * from "./DocumentationReferences.js";
+export * from "./DocumentationReturns.js";
 export * from "./DocumentationSignatures.js";
+export * from "./DocumentationThrows.js";

package/ui/docs/index.ts

@@ -3,4 +3,8 @@ export * from "./DocumentationCard.js";
 export * from "./DocumentationHomePage.js";
 export * from "./DocumentationKind.js";
 export * from "./DocumentationPage.js";
+export * from "./DocumentationParams.js";
+export * from "./DocumentationReferences.js";
+export * from "./DocumentationReturns.js";
 export * from "./DocumentationSignatures.js";
+export * from "./DocumentationThrows.js";