shelving 1.246.1 → 1.248.0

package/extract/TypescriptExtractor.d.ts

@@ -9,7 +9,9 @@ import { FileExtractor } from "./FileExtractor.js";
  * - A `@kind` tag in a symbol's JSDoc overrides the inferred kind — e.g. `@kind component` relabels a React component (otherwise a `function`) so the docs site groups and colours it as a component. The override also drops the trailing `()` from the title, since a non-function kind reads as a bare name.
  * - Sets `description` (a plain-text summary from the first JSDoc paragraph) on every `tree-documentation` child.
  * - Sets `title` on every `tree-documentation` child — `name()` for functions, `Class.name()` for methods, `Class.name` for properties, bare `name` for other kinds.
- * - Records relational metadata as raw strings for render-time linking: `class` (owning class), `readonly`, `extends`, `implements`.
+ * - Records relational metadata as raw strings for render-time linking: `class` (owning class), `readonly`, `extends` / `implements` (full heritage type text including generic arguments, e.g. `AbstractStore<string>` or `Omit<StringSchemaOptions, "value">`), and `types` (the type names a `type` alias's body references, e.g. `OtherType` in `string | OtherType`).
+ * - Records a structured `properties` list for interfaces and object-literal `type` aliases — each member's name, type, optionality, `@default`, and description — so an options-bag parameter can be flattened into its fields at render time.
+ * - Pretty-prints object-literal signatures (interfaces and object-literal `type` aliases) as multi-line `{ … }` blocks, one member per line; other type bodies (`string | null`, mapped types, …) are emitted verbatim.
  * - Members declared with the `override` or `declare` modifier are skipped — the base class already documents overrides, and `declare` members are ambient type-only re-declarations rather than new API.
  * - Keys are the raw declared `name` (case-preserving) so case-distinct exports like `Collection` and `COLLECTION` stay separate.
  * - The file element itself has no `title` — a TS source file has no confident title source; renderers fall back to `name`.

package/extract/TypescriptExtractor.js

@@ -10,7 +10,9 @@ import { extractMarkdownProps } from "./MarkupExtractor.js";
  * - A `@kind` tag in a symbol's JSDoc overrides the inferred kind — e.g. `@kind component` relabels a React component (otherwise a `function`) so the docs site groups and colours it as a component. The override also drops the trailing `()` from the title, since a non-function kind reads as a bare name.
  * - Sets `description` (a plain-text summary from the first JSDoc paragraph) on every `tree-documentation` child.
  * - Sets `title` on every `tree-documentation` child — `name()` for functions, `Class.name()` for methods, `Class.name` for properties, bare `name` for other kinds.
- * - Records relational metadata as raw strings for render-time linking: `class` (owning class), `readonly`, `extends`, `implements`.
+ * - Records relational metadata as raw strings for render-time linking: `class` (owning class), `readonly`, `extends` / `implements` (full heritage type text including generic arguments, e.g. `AbstractStore<string>` or `Omit<StringSchemaOptions, "value">`), and `types` (the type names a `type` alias's body references, e.g. `OtherType` in `string | OtherType`).
+ * - Records a structured `properties` list for interfaces and object-literal `type` aliases — each member's name, type, optionality, `@default`, and description — so an options-bag parameter can be flattened into its fields at render time.
+ * - Pretty-prints object-literal signatures (interfaces and object-literal `type` aliases) as multi-line `{ … }` blocks, one member per line; other type bodies (`string | null`, mapped types, …) are emitted verbatim.
  * - Members declared with the `override` or `declare` modifier are skipped — the base class already documents overrides, and `declare` members are ambient type-only re-declarations rather than new API.
  * - Keys are the raw declared `name` (case-preserving) so case-distinct exports like `Collection` and `COLLECTION` stay separate.
  * - The file element itself has no `title` — a TS source file has no confident title source; renderers fall back to `name`.
@@ -114,6 +116,9 @@ function _extractStatement(statement, source) {
     const examples = jsDoc?.examples;
     // Heritage (`extends` / `implements`) is only meaningful for classes and interfaces.
     const heritage = _getHeritage(statement, source);
+    // Referenced type names (type aliases) and structured property lists (interfaces / object-literal types) — both resolved to links at render time.
+    const types = _getReferencedTypes(statement, source);
+    const properties = _getProperties(statement, source);
     const children = _getClassMembers(statement, source, name);
     return {
         type: "tree-documentation",
@@ -132,18 +137,21 @@ function _extractStatement(statement, source) {
             examples,
             extends: heritage?.extends,
             implements: heritage?.implements,
+            types,
+            properties,
             children,
         },
     };
 }
-/** Extract the `extends` (single base type) and `implements` (interface list) names from a class or interface declaration. */
+/** Extract the `extends` (single base type) and `implements` (interface list) heritage from a class or interface declaration, as full type text including any generic arguments (e.g. `AbstractStore<string>`, `Omit<StringSchemaOptions, "value">`). */
 function _getHeritage(statement, source) {
     if (!ts.isClassDeclaration(statement) && !ts.isInterfaceDeclaration(statement))
         return;
     let extendsName;
     const implementsNames = [];
     for (const clause of statement.heritageClauses ?? []) {
-        const names = clause.types.map(t => t.expression.getText(source));
+        // Full text — keep generic arguments (`Foo<T>`) and wrappers (`Omit<…>`) intact; render-time lookup trims them to the bare name to resolve a link.
+        const names = clause.types.map(t => t.getText(source));
         // `extends` keeps the first base type; an interface extending several still surfaces its primary base.
         if (clause.token === ts.SyntaxKind.ExtendsKeyword)
             extendsName ??= names[0];
@@ -154,6 +162,62 @@ function _getHeritage(statement, source) {
         return;
     return { extends: extendsName, implements: implementsNames.length ? implementsNames : undefined };
 }
+/**
+ * Collect the type names a `type` alias's body references (e.g. `OtherType` in `type X = string | OtherType`), for render-time linking.
+ * - Walks the whole type expression so names nested inside generics, unions, arrays, etc. are all caught.
+ * - Primitive keyword types (`string`, `number`, …) aren't type references so they're naturally excluded; the alias's own generic parameters are filtered out explicitly.
+ * - Order-preserving and de-duplicated. Unresolved names (builtins like `Record`, externals) simply stay as plain text at render time.
+ */
+function _getReferencedTypes(statement, source) {
+    if (!ts.isTypeAliasDeclaration(statement))
+        return;
+    const generics = new Set(statement.typeParameters?.map(t => t.name.text) ?? []);
+    const names = [];
+    const seen = new Set();
+    const visit = (node) => {
+        if (ts.isTypeReferenceNode(node)) {
+            const name = node.typeName.getText(source);
+            if (!generics.has(name) && !seen.has(name)) {
+                seen.add(name);
+                names.push(name);
+            }
+        }
+        node.forEachChild(visit);
+    };
+    visit(statement.type);
+    return names.length ? names : undefined;
+}
+/**
+ * Extract structured property entries from an interface or object-literal `type` alias, mirroring the `DocumentationParam` shape.
+ * - Lets a consumer flatten an options-bag parameter into its individual fields at render time (resolve the param's type in the tree map, then list these).
+ * - Skips private `_`-prefixed members. Descriptions and `@default` values come from each member's own JSDoc.
+ */
+function _getProperties(statement, source) {
+    const members = ts.isInterfaceDeclaration(statement)
+        ? statement.members
+        : ts.isTypeAliasDeclaration(statement) && ts.isTypeLiteralNode(statement.type)
+            ? statement.type.members
+            : undefined;
+    if (!members)
+        return;
+    const properties = [];
+    for (const member of members) {
+        if (!ts.isPropertySignature(member))
+            continue;
+        const name = member.name && ts.isIdentifier(member.name) ? member.name.text : undefined;
+        if (!name || name.startsWith("_"))
+            continue;
+        const jsDoc = _getJSDoc(member, source);
+        properties.push({
+            name,
+            type: member.type?.getText(source),
+            description: jsDoc?.description,
+            optional: !!member.questionToken,
+            default: jsDoc?.default,
+        });
+    }
+    return properties.length ? properties : undefined;
+}
 /**
  * Combine the JSDoc leading-description text and any unhandled `@rule` blocks into a single markup content string.
  * - Unhandled rules (anything not `@param`/`@returns`/`@throws`/`@example`/`@see`) are appended after the description, separated by blank lines, with their `@name` preserved.
@@ -211,12 +275,13 @@ function _getSignatures(statement, source, name) {
         return _getConstructorSignatures(statement, source, name);
     }
     if (ts.isInterfaceDeclaration(statement)) {
-        // Emit `{ member; member }` — the same shape a `type` object body produces, distinguished only by the `kind` badge.
-        const members = statement.members.map(m => m.getText(source).replace(/;\s*$/, "").trim()).join("; ");
-        return [members ? `{ ${members} }` : "{}"];
+        // Emit a pretty-printed `{ member; member }` block — the same shape a `type` object body produces, distinguished only by the `kind` badge.
+        return [_formatObjectSignature(statement.members, source)];
     }
     if (ts.isTypeAliasDeclaration(statement)) {
-        // Emit only the type body (e.g. `{ a: string }` or `string | null`) — the alias name is already the page title.
+        // Pretty-print object-literal aliases multi-line like an interface; emit other bodies (`string | null`, mapped types, …) verbatim. The alias name is already the page title.
+        if (ts.isTypeLiteralNode(statement.type))
+            return [_formatObjectSignature(statement.type.members, source)];
         return [statement.type.getText(source)];
     }
     if (ts.isVariableStatement(statement)) {
@@ -225,6 +290,13 @@ function _getSignatures(statement, source, name) {
             return [`${name}: ${declaration.type.getText(source)}`];
     }
 }
+/** Pretty-print object-type members as a multi-line `{ … }` block — one member per tab-indented line ending in `;` — or `{}` when empty. */
+function _formatObjectSignature(members, source) {
+    if (!members.length)
+        return "{}";
+    const lines = members.map(m => `\t${m.getText(source).replace(/;\s*$/, "").trim()};`);
+    return `{\n${lines.join("\n")}\n}`;
+}
 /** Render a class's generic parameter names as `<P, R>` (names only, no constraints), or `""` when non-generic. */
 function _getTypeParamNames(statement, source) {
     const { typeParameters } = statement;
@@ -438,6 +510,7 @@ function _getJSDoc(node, source) {
         return;
     const description = ts.getTextOfJSDocComment(jsDoc.comment)?.trim();
     let kind;
+    let def;
     const params = [];
     const returns = [];
     const throws = [];
@@ -469,6 +542,9 @@ function _getJSDoc(node, source) {
             // `@kind <name>` overrides the AST-inferred kind (e.g. `@kind component` for a React component declared as a function).
             if (name === "kind")
                 kind = comment?.match(/^[\w-]+/)?.[0];
+            // `@default <value>` documents a property's default — surfaced structurally (e.g. on `properties`) rather than rendered into the body.
+            else if (name === "default")
+                def = comment || undefined;
             else if (name === "example") {
                 if (comment)
                     examples.push({ description: comment });
@@ -480,6 +556,7 @@ function _getJSDoc(node, source) {
     return {
         description: description || undefined,
         kind,
+        default: def,
         params: params.length ? params : undefined,
         returns: returns.length ? returns : undefined,
         throws: throws.length ? throws : undefined,

package/package.json

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

package/ui/block/Table.md

@@ -9,6 +9,7 @@ A data table — renders a `<table>`. Compose the usual `<thead>` / `<tbody>` /
 - Wrap a wide table in a horizontally scrollable container if it may exceed the content width on small screens.
 - Like the other block components it collapses its outer block margin when it is the first or last child.
 - Spans the full width of its container by default; set the `width` variant (`narrow` / `normal` / `wide` / `full` / `fit`) to constrain it.
+- Size columns with [`<TableHeader>`](/ui/TableHeader) / [`<TableCell>`](/ui/TableCell) and the `width` variant — `width="fit"` hugs the content, and `width="12x" grow` gives a column a hard minimum it can grow past (cells honour `min-width`, so the table scrolls rather than collapsing the column on a narrow screen). A column's width is the widest of its cells.
 - Inside [`Prose`](/ui/Prose) a raw `<table>` picks up the same styling, so Markdown-rendered tables match component ones.
 
 ## Usage
@@ -50,6 +51,7 @@ import { Table } from "shelving/ui";
 
 ## See also
 
+- [`TableHeader`](/ui/TableHeader) / [`TableCell`](/ui/TableCell) — `<th>` / `<td>` cells that set column widths and typography via variants.
 - [`Definitions`](/ui/Definitions) — term/value pairs when a two-column key/value layout fits better than a grid.
 - [`Prose`](/ui/Prose) — styles raw `<table>` inside longform content.
 - [`ui`](/ui) — the styling system: tint ladder, label tokens, and theming.

package/ui/block/TableCell.d.ts

@@ -0,0 +1,23 @@
+import type { ReactElement } from "react";
+import { type TypographyVariants } from "../style/Typography.js";
+import { type WidthVariants } from "../style/Width.js";
+import type { ChildProps } from "../util/props.js";
+/**
+ * Props for `TableCell` — width and typography variants plus `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/TableCell/TableCellProps
+ */
+export interface TableCellProps extends WidthVariants, TypographyVariants, ChildProps {
+}
+/**
+ * Table body cell — rendered as `<td>`.
+ * - Sets its column's width via the `width` variant. Unlike a `<col>`, a cell honours `min-width`, so `width="12x" grow` gives the column a hard minimum that fills the remaining space and keeps the table from collapsing the column on a narrow viewport.
+ * - A column's width is the widest of its cells, so use this to size a column that has no header to set the width on.
+ *
+ * @kind component
+ * @param props Width and typography variant props plus `children`.
+ * @returns Rendered `<td>` element.
+ * @example <TableCell width="12x" grow>A longer description that wants a sensible minimum width.</TableCell>
+ * @see https://dhoulb.github.io/shelving/ui/block/TableCell/TableCell
+ */
+export declare function TableCell({ children, ...props }: TableCellProps): ReactElement;

package/ui/block/TableCell.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getTypographyClass } from "../style/Typography.js";
+import { getWidthClass } from "../style/Width.js";
+import { getClass } from "../util/css.js";
+/**
+ * Table body cell — rendered as `<td>`.
+ * - Sets its column's width via the `width` variant. Unlike a `<col>`, a cell honours `min-width`, so `width="12x" grow` gives the column a hard minimum that fills the remaining space and keeps the table from collapsing the column on a narrow viewport.
+ * - A column's width is the widest of its cells, so use this to size a column that has no header to set the width on.
+ *
+ * @kind component
+ * @param props Width and typography variant props plus `children`.
+ * @returns Rendered `<td>` element.
+ * @example <TableCell width="12x" grow>A longer description that wants a sensible minimum width.</TableCell>
+ * @see https://dhoulb.github.io/shelving/ui/block/TableCell/TableCell
+ */
+export function TableCell({ children, ...props }) {
+    return _jsx("td", { className: getClass(getWidthClass(props), getTypographyClass(props)) || undefined, children: children });
+}

package/ui/block/TableCell.md

@@ -0,0 +1,35 @@
+# TableCell
+
+A table body cell — renders a `<td>`. Use it for the body rows of a [`Table`](/ui/Table); it sets the column's width and cell typography.
+
+**Things to know:**
+
+- Set the column's width with the `width` variant. Because a cell (unlike a `<col>`) honours `min-width`, `width="12x" grow` gives the column a *hard* minimum that fills the remaining space and keeps the table from collapsing the column on a narrow screen — the table scrolls instead. See [`getWidthClass`](/ui/getWidthClass).
+- A column's width is the widest of its cells, so this is how you size a column that has no header to set the width on (e.g. a trailing description column).
+- Carries the same [typography variants](/ui/getTypographyClass) as the prose components (`size`, `weight`, `font`, `tint`, alignment).
+- For a column that does have a header, prefer setting the width once on its [`TableHeader`](/ui/TableHeader).
+
+## Usage
+
+```tsx
+import { Table, TableCell } from "shelving/ui";
+
+<Table>
+  <tbody>
+    <tr>
+      <TableCell>name</TableCell>
+      <TableCell width="12x" grow>A longer description that should keep a sensible minimum width.</TableCell>
+    </tr>
+  </tbody>
+</Table>
+```
+
+## Styling
+
+`TableCell` paints nothing of its own — it composes the [`width`](/ui/getWidthClass) and [`typography`](/ui/getTypographyClass) variants onto a `<td>`, and inherits the cell styling (borders, padding) from the surrounding [`Table`](/ui/Table). It exposes no hooks of its own.
+
+## See also
+
+- [`TableHeader`](/ui/TableHeader) — the `<th>` equivalent for header cells.
+- [`Table`](/ui/Table) — the table the cells belong to.
+- [`getWidthClass`](/ui/getWidthClass) — the full `width` / `grow` variant reference.

package/ui/block/TableCell.tsx

@@ -0,0 +1,27 @@
+import type { ReactElement } from "react";
+import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
+import { getWidthClass, type WidthVariants } from "../style/Width.js";
+import { getClass } from "../util/css.js";
+import type { ChildProps } from "../util/props.js";
+
+/**
+ * Props for `TableCell` — width and typography variants plus `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/TableCell/TableCellProps
+ */
+export interface TableCellProps extends WidthVariants, TypographyVariants, ChildProps {}
+
+/**
+ * Table body cell — rendered as `<td>`.
+ * - Sets its column's width via the `width` variant. Unlike a `<col>`, a cell honours `min-width`, so `width="12x" grow` gives the column a hard minimum that fills the remaining space and keeps the table from collapsing the column on a narrow viewport.
+ * - A column's width is the widest of its cells, so use this to size a column that has no header to set the width on.
+ *
+ * @kind component
+ * @param props Width and typography variant props plus `children`.
+ * @returns Rendered `<td>` element.
+ * @example <TableCell width="12x" grow>A longer description that wants a sensible minimum width.</TableCell>
+ * @see https://dhoulb.github.io/shelving/ui/block/TableCell/TableCell
+ */
+export function TableCell({ children, ...props }: TableCellProps): ReactElement {
+	return <td className={getClass(getWidthClass(props), getTypographyClass(props)) || undefined}>{children}</td>;
+}

package/ui/block/TableHeader.d.ts

@@ -0,0 +1,23 @@
+import type { ReactElement } from "react";
+import { type TypographyVariants } from "../style/Typography.js";
+import { type WidthVariants } from "../style/Width.js";
+import type { ChildProps } from "../util/props.js";
+/**
+ * Props for `TableHeader` — width and typography variants plus `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/TableHeader/TableHeaderProps
+ */
+export interface TableHeaderProps extends WidthVariants, TypographyVariants, ChildProps {
+}
+/**
+ * Table header cell — rendered as `<th>`.
+ * - Sets its column's width via the `width` variant (e.g. `width="fit"` to hug the content). Unlike a `<col>`, a cell honours `min-width`, so `width="12x" grow` gives the column a hard minimum it can grow past.
+ * - A column's width is the widest of its cells, so sizing the `<th>` sizes the whole column.
+ *
+ * @kind component
+ * @param props Width and typography variant props plus `children`.
+ * @returns Rendered `<th>` element.
+ * @example <TableHeader width="fit">Parameter</TableHeader>
+ * @see https://dhoulb.github.io/shelving/ui/block/TableHeader/TableHeader
+ */
+export declare function TableHeader({ children, ...props }: TableHeaderProps): ReactElement;

package/ui/block/TableHeader.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getTypographyClass } from "../style/Typography.js";
+import { getWidthClass } from "../style/Width.js";
+import { getClass } from "../util/css.js";
+/**
+ * Table header cell — rendered as `<th>`.
+ * - Sets its column's width via the `width` variant (e.g. `width="fit"` to hug the content). Unlike a `<col>`, a cell honours `min-width`, so `width="12x" grow` gives the column a hard minimum it can grow past.
+ * - A column's width is the widest of its cells, so sizing the `<th>` sizes the whole column.
+ *
+ * @kind component
+ * @param props Width and typography variant props plus `children`.
+ * @returns Rendered `<th>` element.
+ * @example <TableHeader width="fit">Parameter</TableHeader>
+ * @see https://dhoulb.github.io/shelving/ui/block/TableHeader/TableHeader
+ */
+export function TableHeader({ children, ...props }) {
+    return _jsx("th", { className: getClass(getWidthClass(props), getTypographyClass(props)) || undefined, children: children });
+}

package/ui/block/TableHeader.md

@@ -0,0 +1,43 @@
+# TableHeader
+
+A table header cell — renders a `<th>`. Use it for the header row of a [`Table`](/ui/Table); it sets the column's width and label typography.
+
+**Things to know:**
+
+- Set the column's width with the `width` variant — `width="fit"` hugs the content. Because a cell (unlike a `<col>`) honours `min-width`, `width="12x" grow` gives the column a *hard* minimum it can grow past, so the table scrolls rather than collapsing the column on a narrow screen. See [`getWidthClass`](/ui/getWidthClass).
+- A column's width is the widest of its cells, so sizing the `<th>` sizes the whole column — set the width once on the header instead of on every body cell.
+- Carries the same [typography variants](/ui/getTypographyClass) as the prose components (`size`, `weight`, `font`, `tint`, alignment), though the `Table` already styles header cells in the label style by default.
+- For a column that has no header, set the width on its [`TableCell`](/ui/TableCell)s instead.
+
+## Usage
+
+```tsx
+import { Table, TableCell, TableHeader } from "shelving/ui";
+
+<Table>
+  <thead>
+    <tr>
+      <TableHeader width="fit">Parameter</TableHeader>
+      <TableHeader width="fit">Type</TableHeader>
+      <TableHeader width="12x" grow>Description</TableHeader>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <TableCell>name</TableCell>
+      <TableCell>string</TableCell>
+      <TableCell>The name of the thing.</TableCell>
+    </tr>
+  </tbody>
+</Table>
+```
+
+## Styling
+
+`TableHeader` paints nothing of its own — it composes the [`width`](/ui/getWidthClass) and [`typography`](/ui/getTypographyClass) variants onto a `<th>`, and inherits the header styling (label font, borders, padding) from the surrounding [`Table`](/ui/Table). It exposes no hooks of its own.
+
+## See also
+
+- [`TableCell`](/ui/TableCell) — the `<td>` equivalent for body cells.
+- [`Table`](/ui/Table) — the table the cells belong to.
+- [`getWidthClass`](/ui/getWidthClass) — the full `width` / `grow` variant reference.

package/ui/block/TableHeader.tsx

@@ -0,0 +1,27 @@
+import type { ReactElement } from "react";
+import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
+import { getWidthClass, type WidthVariants } from "../style/Width.js";
+import { getClass } from "../util/css.js";
+import type { ChildProps } from "../util/props.js";
+
+/**
+ * Props for `TableHeader` — width and typography variants plus `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/TableHeader/TableHeaderProps
+ */
+export interface TableHeaderProps extends WidthVariants, TypographyVariants, ChildProps {}
+
+/**
+ * Table header cell — rendered as `<th>`.
+ * - Sets its column's width via the `width` variant (e.g. `width="fit"` to hug the content). Unlike a `<col>`, a cell honours `min-width`, so `width="12x" grow` gives the column a hard minimum it can grow past.
+ * - A column's width is the widest of its cells, so sizing the `<th>` sizes the whole column.
+ *
+ * @kind component
+ * @param props Width and typography variant props plus `children`.
+ * @returns Rendered `<th>` element.
+ * @example <TableHeader width="fit">Parameter</TableHeader>
+ * @see https://dhoulb.github.io/shelving/ui/block/TableHeader/TableHeader
+ */
+export function TableHeader({ children, ...props }: TableHeaderProps): ReactElement {
+	return <th className={getClass(getWidthClass(props), getTypographyClass(props)) || undefined}>{children}</th>;
+}

package/ui/block/index.d.ts

@@ -14,5 +14,7 @@ export * from "./Preformatted.js";
 export * from "./Prose.js";
 export * from "./Subheading.js";
 export * from "./Table.js";
+export * from "./TableCell.js";
+export * from "./TableHeader.js";
 export * from "./Title.js";
 export * from "./Video.js";

package/ui/block/index.js

@@ -14,5 +14,7 @@ export * from "./Preformatted.js";
 export * from "./Prose.js";
 export * from "./Subheading.js";
 export * from "./Table.js";
+export * from "./TableCell.js";
+export * from "./TableHeader.js";
 export * from "./Title.js";
 export * from "./Video.js";

package/ui/block/index.ts

@@ -14,5 +14,7 @@ export * from "./Preformatted.js";
 export * from "./Prose.js";
 export * from "./Subheading.js";
 export * from "./Table.js";
+export * from "./TableCell.js";
+export * from "./TableHeader.js";
 export * from "./Title.js";
 export * from "./Video.js";

package/ui/docs/DocumentationPage.d.ts

@@ -1,8 +1,11 @@
-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.
- * - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, and examples.
+ * - 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`.
+ * - 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.
+ * - 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.
  * - All sections are conditional — only render when they have entries.
  *
@@ -12,4 +15,4 @@ import type { DocumentationElementProps } from "../../util/tree.js";
  * @example <DocumentationPage {...element.props} />
  * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationPage/DocumentationPage
  */
-export declare function DocumentationPage({ title, name, kind, description, content, signatures, params, returns, throws, examples, children, ...props }: DocumentationElementProps): ReactNode;
+export declare function DocumentationPage({ title, name, kind, description, content, signatures, params, returns, throws, types, examples, children, ...props }: DocumentationElementProps): ReactNode;

package/ui/docs/DocumentationPage.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment } from "react";
 import { walkElements } from "../../util/element.js";
 import { Block } from "../block/Block.js";
 import { Heading } from "../block/Heading.js";
@@ -7,6 +8,8 @@ import { Preformatted } from "../block/Preformatted.js";
 import { Prose } from "../block/Prose.js";
 import { Header, Section } from "../block/Section.js";
 import { Table } from "../block/Table.js";
+import { TableCell } from "../block/TableCell.js";
+import { TableHeader } from "../block/TableHeader.js";
 import { Title } from "../block/Title.js";
 import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
@@ -15,10 +18,16 @@ import { Row } from "../style/Flex.js";
 import { Scroll } from "../style/Scroll.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 { 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 || "";
+}
 /** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. */
 const KIND_SECTIONS = {
     component: "Components",
@@ -57,7 +66,10 @@ function DocumentationChildren({ elements }) {
 }
 /**
  * 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, and examples.
+ * - 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`.
+ * - 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.
+ * - 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.
  * - All sections are conditional — only render when they have entries.
  *
@@ -67,6 +79,11 @@ function DocumentationChildren({ elements }) {
  * @example <DocumentationPage {...element.props} />
  * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationPage/DocumentationPage
  */
-export function DocumentationPage({ title, name, kind = "unknown", description, content, signatures, params, returns, throws, examples, children, ...props }) {
-    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: getDocumentationKindColor(kind), children: [_jsx(Panel, { children: _jsxs(Header, { children: [_jsx(TreeBreadcrumbs, {}), _jsx(Title, { children: _jsxs(Row, { left: true, wrap: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind, size: "normal" })] }) }), _jsx(DocumentationButtons, { ...props })] }) }), signatures?.length || params?.length || returns?.length || throws?.length ? (_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("th", { children: "Parameter" }), _jsx("th", { children: "Type" }), _jsx("th", { children: "Default" }), _jsx("th", { children: "Description" })] }) }), _jsx("tbody", { children: params.map(({ name, type = DEFAULT_TYPE, description = "", default: def }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(Code, { children: name }) }), _jsx("td", { children: _jsx(Code, { children: type }) }), _jsx("td", { children: def ? _jsx(Code, { children: def }) : "-" }), _jsx("td", { children: description })] }, `${name}-${type}-${description}`))) })] }) }) })), returns?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: "Return" }), _jsx("th", { children: "Description" })] }) }), _jsx("tbody", { children: returns.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(Code, { children: type }) }), _jsx("td", { children: description })] }, `${type}-${description}`))) })] }) }) })), throws?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: "Throws" }), _jsx("th", { children: "Description" })] }) }), _jsx("tbody", { children: throws.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(Code, { children: type }) }), _jsx("td", { children: description })] }, `${type}-${description}`))) })] }) }) }))] })) : 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 })] }) }));
+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(TableHeader, { width: "fit", children: "Param" }), _jsx(TableHeader, { width: "fit", children: "Type" }), _jsx(TableHeader, { width: "fit", children: "Default" })] }) }), _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(TableCell, { children: _jsx(Code, { children: name }) }), _jsx(TableCell, { children: _jsx(TreeLink, { name: type }) }), _jsx(TableCell, { children: def ? _jsx(Code, { children: def }) : "-" }), _jsx(TableCell, { width: "20x", grow: true, children: description || resolved?.description || "" })] }), resolved?.properties?.map(prop => (_jsxs("tr", { children: [_jsx(TableCell, { children: _jsx(Code, { children: `.${prop.name}` }) }), _jsx(TableCell, { children: _jsx(TreeLink, { name: prop.type ?? DEFAULT_TYPE }) }), _jsx(TableCell, { children: prop.default ? _jsx(Code, { children: prop.default }) : "-" }), _jsx(TableCell, { width: "20x", grow: true, children: _getRowDescription(map, prop.type ?? DEFAULT_TYPE, prop.description) })] }, `${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(TableHeader, { width: "fit", children: "Return" }) }) }), _jsx("tbody", { children: returns.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx(TableCell, { children: _jsx(TreeLink, { name: type }) }), _jsx(TableCell, { width: "20x", grow: true, 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(TableHeader, { width: "fit", children: "Throws" }) }) }), _jsx("tbody", { children: throws.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx(TableCell, { children: _jsx(TreeLink, { name: type }) }), _jsx(TableCell, { width: "20x", grow: true, 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(TableHeader, { width: "fit", children: "Type" }) }) }), _jsx("tbody", { children: types.map(type => (_jsxs("tr", { children: [_jsx(TableCell, { children: _jsx(TreeLink, { name: type }) }), _jsx(TableCell, { width: "20x", grow: true, 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 })] }) }));
 }

package/ui/docs/DocumentationPage.md

@@ -6,7 +6,7 @@ The full detail page for a documented symbol — the default renderer for `tree-
 
 - Above the title it renders an ancestor trail via [`TreeBreadcrumbs`](/ui/TreeBreadcrumbs), so it needs a [`TreeProvider`](/ui/TreeProvider) above it to resolve the ancestors.
 - The title carries a [`DocumentationKind`](/ui/DocumentationKind) tag, and below it [`DocumentationButtons`](/ui/DocumentationButtons) lists the symbol's relations (`member of`, `extends`, `implements`) as links.
-- It renders the signature(s) via [`DocumentationSignatures`](/ui/DocumentationSignatures) (one block per overload, each carrying the symbol's name), then prose content, then conditional `Parameters` / `Returns` / `Throws` / `Examples` sections — each only appears when it has entries. Parameters render as a [`Table`](/ui/Table) (`Parameter` / `Type` / `Default` / `Description` columns, a `-` standing in where a parameter has no default); Returns and Throws render as two-column tables (`Return` / `Throws` plus `Description`), with the type in the first column.
+- It renders the signature(s) via [`DocumentationSignatures`](/ui/DocumentationSignatures) (one block per overload, each carrying the symbol's name), then prose content, then conditional `Parameters` / `Returns` / `Throws` / `Examples` sections — each only appears when it has entries. Parameters render as a [`Table`](/ui/Table) (`Param` / `Type` / `Default` / `Description` columns, a `-` standing in where a parameter has no default); Returns and Throws render as two-column tables (`Return` / `Throws` plus `Description`), with the type in the first column.
 - Child symbols follow, grouped by `kind` into card sections (`Components`, `Functions`, `Classes`, `Interfaces`, `Types`, `Constants`, `Methods`, `Properties`) rendered as [`DocumentationCard`](/ui/DocumentationCard)s inside a [`TreeCards`](/ui/TreeCards) listing. A new documented kind needs an entry in `KIND_SECTIONS` here (and a colour in [`DocumentationKind`](/ui/DocumentationKind)).
 
 ## Usage

package/ui/docs/DocumentationPage.test.tsx

@@ -57,7 +57,7 @@ describe("DocumentationPage", () => {
 			"./makeThing",
 		);
 		// Parameters table headers — name, type, default, description in separate columns.
-		expect(html).toContain("<th>Parameter</th>");
+		expect(html).toContain("<th>Param</th>");
 		expect(html).toContain("<th>Type</th>");
 		expect(html).toContain("<th>Default</th>");
 		// A param with a default renders it; one without gets a hyphen.