shelving 1.246.0 → 1.247.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.0",
+	"version": "1.247.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

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";
@@ -15,10 +16,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 +64,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 +77,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("th", { children: "Parameter" }), _jsx("th", { children: "Type" }), _jsx("th", { 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("td", { children: _jsx(Code, { children: name }) }), _jsx("td", { children: _jsx(TreeLink, { name: type }) }), _jsx("td", { children: def ? _jsx(Code, { children: def }) : "-" }), _jsx("td", { children: description || resolved?.description || "" })] }), resolved?.properties?.map(prop => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(Code, { children: `.${prop.name}` }) }), _jsx("td", { children: _jsx(TreeLink, { name: prop.type ?? DEFAULT_TYPE }) }), _jsx("td", { children: prop.default ? _jsx(Code, { children: prop.default }) : "-" }), _jsx("td", { 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("th", { children: "Return" }) }) }), _jsx("tbody", { children: returns.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type }) }), _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 }) }), _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 })] }) }));
 }

package/ui/docs/DocumentationPage.tsx

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import { Fragment, 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";
@@ -16,12 +16,19 @@ 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: ReadonlyMap<string, TreeElement>, type: string, description?: string | undefined): string {
+	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",
@@ -69,7 +76,10 @@ function DocumentationChildren({ elements }: { readonly elements?: TreeElements
 
 /**
  * Page renderer for a `tree-documentation` element — the full detail page for a documented symbol.
- * - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, 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.
  *
@@ -89,10 +99,12 @@ export function DocumentationPage({
 	params,
 	returns,
 	throws,
+	types,
 	examples,
 	children,
 	...props
 }: DocumentationElementProps): ReactNode {
+	const map = useTreeMap();
 	return (
 		<Page title={title ?? name} description={description}>
 			<Block color={getDocumentationKindColor(kind)}>
@@ -108,7 +120,7 @@ export function DocumentationPage({
 						<DocumentationButtons {...props} />
 					</Header>
 				</Panel>
-				{signatures?.length || params?.length || returns?.length || throws?.length ? (
+				{signatures?.length || params?.length || returns?.length || throws?.length || types?.length ? (
 					<Section>
 						<DocumentationSignatures signatures={signatures} />
 						{params?.length && (
@@ -120,22 +132,39 @@ export function DocumentationPage({
 												<th>Parameter</th>
 												<th>Type</th>
 												<th>Default</th>
-												<th>Description</th>
 											</tr>
 										</thead>
 										<tbody>
-											{params.map(({ name, type = DEFAULT_TYPE, description = "", default: def }) => (
-												<tr key={`${name}-${type}-${description}`}>
-													<td>
-														<Code>{name}</Code>
-													</td>
-													<td>
-														<Code>{type}</Code>
-													</td>
-													<td>{def ? <Code>{def}</Code> : "-"}</td>
-													<td>{description}</td>
-												</tr>
-											))}
+											{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>{name}</Code>
+															</td>
+															<td>
+																<TreeLink name={type} />
+															</td>
+															<td>{def ? <Code>{def}</Code> : "-"}</td>
+															<td>{description || resolved?.description || ""}</td>
+														</tr>
+														{resolved?.properties?.map(prop => (
+															<tr key={`${name}.${prop.name}`}>
+																<td>
+																	<Code>{`.${prop.name}`}</Code>
+																</td>
+																<td>
+																	<TreeLink name={prop.type ?? DEFAULT_TYPE} />
+																</td>
+																<td>{prop.default ? <Code>{prop.default}</Code> : "-"}</td>
+																<td>{_getRowDescription(map, prop.type ?? DEFAULT_TYPE, prop.description)}</td>
+															</tr>
+														))}
+													</Fragment>
+												);
+											})}
 										</tbody>
 									</Table>
 								</Scroll>
@@ -148,16 +177,15 @@ export function DocumentationPage({
 										<thead>
 											<tr>
 												<th>Return</th>
-												<th>Description</th>
 											</tr>
 										</thead>
 										<tbody>
-											{returns.map(({ type = DEFAULT_TYPE, description = "" }) => (
+											{returns.map(({ type = DEFAULT_TYPE, description }) => (
 												<tr key={`${type}-${description}`}>
 													<td>
-														<Code>{type}</Code>
+														<TreeLink name={type} />
 													</td>
-													<td>{description}</td>
+													<td>{_getRowDescription(map, type, description)}</td>
 												</tr>
 											))}
 										</tbody>
@@ -172,16 +200,38 @@ export function DocumentationPage({
 										<thead>
 											<tr>
 												<th>Throws</th>
-												<th>Description</th>
 											</tr>
 										</thead>
 										<tbody>
-											{throws.map(({ type = DEFAULT_TYPE, description = "" }) => (
+											{throws.map(({ type = DEFAULT_TYPE, description }) => (
 												<tr key={`${type}-${description}`}>
 													<td>
-														<Code>{type}</Code>
+														<TreeLink name={type} />
+													</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>{description}</td>
+													<td>{_getRowDescription(map, type)}</td>
 												</tr>
 											))}
 										</tbody>

package/ui/tree/TreeButton.d.ts

@@ -14,8 +14,8 @@ export interface TreeButtonProps extends ButtonVariants {
 /**
  * Small button linking to a specific tree element, resolved by reference string.
  *
- * - Looks `name` up in the flattened tree map (`useTreeMap()`) — by flat key (`"Store"`, `"Store.get"`) or canonical path (`"/schema/BooleanSchema"`) — and links to the element's canonical `path`.
- * - A hit becomes an `<a>` link; a miss (e.g. a builtin like `Serializable`) stays a plain non-link label so it still reads as text.
+ * - Resolves `name` via `getTreeElement()` — by flat key (`"Store"`, `"Store.get"`) or canonical path (`"/schema/BooleanSchema"`), falling back to the bare name for a single generic type (`"Schema<T>"` → `"Schema"`) — and links to the element's canonical `path`.
+ * - A hit becomes an `<a>` link; a miss (e.g. a builtin like `Serializable`, or a compound type like `Foo | null`) stays a plain non-link label so it still reads as text.
  * - Defaults to `small plain` styling; pass other `ButtonVariants` to override.
  *
  * @param props The element reference `name`, optional `children` label, and button variants.

package/ui/tree/TreeButton.js

@@ -1,11 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Button } from "../form/Button.js";
-import { useTreeMap } from "./TreeContext.js";
+import { getTreeElement, useTreeMap } from "./TreeContext.js";
 /**
  * Small button linking to a specific tree element, resolved by reference string.
  *
- * - Looks `name` up in the flattened tree map (`useTreeMap()`) — by flat key (`"Store"`, `"Store.get"`) or canonical path (`"/schema/BooleanSchema"`) — and links to the element's canonical `path`.
- * - A hit becomes an `<a>` link; a miss (e.g. a builtin like `Serializable`) stays a plain non-link label so it still reads as text.
+ * - Resolves `name` via `getTreeElement()` — by flat key (`"Store"`, `"Store.get"`) or canonical path (`"/schema/BooleanSchema"`), falling back to the bare name for a single generic type (`"Schema<T>"` → `"Schema"`) — and links to the element's canonical `path`.
+ * - A hit becomes an `<a>` link; a miss (e.g. a builtin like `Serializable`, or a compound type like `Foo | null`) stays a plain non-link label so it still reads as text.
  * - Defaults to `small plain` styling; pass other `ButtonVariants` to override.
  *
  * @param props The element reference `name`, optional `children` label, and button variants.
@@ -14,7 +14,7 @@ import { useTreeMap } from "./TreeContext.js";
  * @see https://dhoulb.github.io/shelving/ui/tree/TreeButton/TreeButton
  */
 export function TreeButton({ name, children, small = true, plain = true, ...variants }) {
-    const element = useTreeMap().get(name);
+    const element = getTreeElement(useTreeMap(), name);
     const href = element?.props.path;
     // A resolved element links via its canonical `path`; an unresolved reference is disabled (no `href`) so it renders as a non-link label rather than an empty `<a>`.
     return (_jsx(Button, { small: small, plain: plain, ...variants, ...(href ? { href } : { disabled: true }), children: children ?? element?.props.title ?? name }));

package/ui/tree/TreeButton.test.tsx

@@ -60,4 +60,15 @@ describe("TreeButton", () => {
 		expect(html).toContain("Serializable"); // still reads as text
 		expect(html).not.toContain("Serializable</a>"); // but is not a link
 	});
+
+	test("links a generic reference by its bare type name", () => {
+		// `Store<T>` isn't a key, but stripping the generics resolves `Store`.
+		const html = render(<TreeButton name="Store<T>" />);
+		expect(html).toContain('href="http://x.com/Store"');
+	});
+
+	test("leaves a compound generic reference unresolved", () => {
+		const html = render(<TreeButton name="Store<T> | null" />);
+		expect(html).not.toContain("</a>"); // not `Identifier<…>`-shaped, so no link
+	});
 });

package/ui/tree/TreeButton.tsx

@@ -1,6 +1,6 @@
 import type { ReactElement, ReactNode } from "react";
 import { Button, type ButtonVariants } from "../form/Button.js";
-import { useTreeMap } from "./TreeContext.js";
+import { getTreeElement, useTreeMap } from "./TreeContext.js";
 
 /**
  * Props for the `TreeButton` component — the element reference plus button variants.
@@ -17,8 +17,8 @@ export interface TreeButtonProps extends ButtonVariants {
 /**
  * Small button linking to a specific tree element, resolved by reference string.
  *
- * - Looks `name` up in the flattened tree map (`useTreeMap()`) — by flat key (`"Store"`, `"Store.get"`) or canonical path (`"/schema/BooleanSchema"`) — and links to the element's canonical `path`.
- * - A hit becomes an `<a>` link; a miss (e.g. a builtin like `Serializable`) stays a plain non-link label so it still reads as text.
+ * - Resolves `name` via `getTreeElement()` — by flat key (`"Store"`, `"Store.get"`) or canonical path (`"/schema/BooleanSchema"`), falling back to the bare name for a single generic type (`"Schema<T>"` → `"Schema"`) — and links to the element's canonical `path`.
+ * - A hit becomes an `<a>` link; a miss (e.g. a builtin like `Serializable`, or a compound type like `Foo | null`) stays a plain non-link label so it still reads as text.
  * - Defaults to `small plain` styling; pass other `ButtonVariants` to override.
  *
  * @param props The element reference `name`, optional `children` label, and button variants.
@@ -27,7 +27,7 @@ export interface TreeButtonProps extends ButtonVariants {
  * @see https://dhoulb.github.io/shelving/ui/tree/TreeButton/TreeButton
  */
 export function TreeButton({ name, children, small = true, plain = true, ...variants }: TreeButtonProps): ReactElement {
-	const element = useTreeMap().get(name);
+	const element = getTreeElement(useTreeMap(), name);
 	const href = element?.props.path;
 	// A resolved element links via its canonical `path`; an unresolved reference is disabled (no `href`) so it renders as a non-link label rather than an empty `<a>`.
 	return (

package/ui/tree/TreeContext.d.ts

@@ -33,3 +33,17 @@ export declare function TreeProvider({ tree, children }: {
  * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/useTreeMap
  */
 export declare function useTreeMap(): ReadonlyMap<string, TreeElement>;
+/**
+ * Resolve a reference string to its tree element — by exact key first, then by the bare type name when the whole reference is a single generic type.
+ *
+ * - Exact lookup handles flat keys (`"BooleanSchema"`, `"Store.get"`) and canonical paths (`"/schema/BooleanSchema"`).
+ * - On a miss, a `Foo<…>`-shaped reference retries with the generics stripped (`"Schema<T>"` → `"Schema"`), so a generic type name still links without the extractor storing a separate un-generic'd key — the generics stay in the displayed label.
+ * - A compound reference (`"Schema<T> | null"`, `"Omit<X, 'k'>"`) only retries on the leading identifier when the whole string is `Identifier<…>`; otherwise it stays a miss and the caller falls back to plain text.
+ *
+ * @param map The flattened tree lookup map (from `useTreeMap()`).
+ * @param ref The reference string — a flat key, canonical path, or raw type expression.
+ * @returns The resolved element, or `undefined` on a miss.
+ * @example getTreeElement(useTreeMap(), "Schema<T>") // the `Schema` element
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/getTreeElement
+ */
+export declare function getTreeElement(map: ReadonlyMap<string, TreeElement>, ref: string): TreeElement | undefined;

package/ui/tree/TreeContext.js

@@ -38,3 +38,23 @@ export function TreeProvider({ tree, children }) {
 export function useTreeMap() {
     return use(TreeContext);
 }
+/**
+ * Resolve a reference string to its tree element — by exact key first, then by the bare type name when the whole reference is a single generic type.
+ *
+ * - Exact lookup handles flat keys (`"BooleanSchema"`, `"Store.get"`) and canonical paths (`"/schema/BooleanSchema"`).
+ * - On a miss, a `Foo<…>`-shaped reference retries with the generics stripped (`"Schema<T>"` → `"Schema"`), so a generic type name still links without the extractor storing a separate un-generic'd key — the generics stay in the displayed label.
+ * - A compound reference (`"Schema<T> | null"`, `"Omit<X, 'k'>"`) only retries on the leading identifier when the whole string is `Identifier<…>`; otherwise it stays a miss and the caller falls back to plain text.
+ *
+ * @param map The flattened tree lookup map (from `useTreeMap()`).
+ * @param ref The reference string — a flat key, canonical path, or raw type expression.
+ * @returns The resolved element, or `undefined` on a miss.
+ * @example getTreeElement(useTreeMap(), "Schema<T>") // the `Schema` element
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/getTreeElement
+ */
+export function getTreeElement(map, ref) {
+    const exact = map.get(ref);
+    if (exact || !ref.includes("<"))
+        return exact;
+    // Strip a whole-string generic wrapper (`Foo<…>` → `Foo`) and retry; leave compound expressions (unions, etc.) unresolved.
+    return map.get(ref.replace(/^([\w$.]+)<.*>$/s, "$1"));
+}

package/ui/tree/TreeContext.tsx

@@ -40,3 +40,23 @@ export function TreeProvider({ tree, children }: { readonly tree: TreeElement; r
 export function useTreeMap(): ReadonlyMap<string, TreeElement> {
 	return use(TreeContext);
 }
+
+/**
+ * Resolve a reference string to its tree element — by exact key first, then by the bare type name when the whole reference is a single generic type.
+ *
+ * - Exact lookup handles flat keys (`"BooleanSchema"`, `"Store.get"`) and canonical paths (`"/schema/BooleanSchema"`).
+ * - On a miss, a `Foo<…>`-shaped reference retries with the generics stripped (`"Schema<T>"` → `"Schema"`), so a generic type name still links without the extractor storing a separate un-generic'd key — the generics stay in the displayed label.
+ * - A compound reference (`"Schema<T> | null"`, `"Omit<X, 'k'>"`) only retries on the leading identifier when the whole string is `Identifier<…>`; otherwise it stays a miss and the caller falls back to plain text.
+ *
+ * @param map The flattened tree lookup map (from `useTreeMap()`).
+ * @param ref The reference string — a flat key, canonical path, or raw type expression.
+ * @returns The resolved element, or `undefined` on a miss.
+ * @example getTreeElement(useTreeMap(), "Schema<T>") // the `Schema` element
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/getTreeElement
+ */
+export function getTreeElement(map: ReadonlyMap<string, TreeElement>, ref: string): TreeElement | undefined {
+	const exact = map.get(ref);
+	if (exact || !ref.includes("<")) return exact;
+	// Strip a whole-string generic wrapper (`Foo<…>` → `Foo`) and retry; leave compound expressions (unions, etc.) unresolved.
+	return map.get(ref.replace(/^([\w$.]+)<.*>$/s, "$1"));
+}

package/ui/tree/TreeLink.d.ts

@@ -0,0 +1,26 @@
+import type { ReactElement, ReactNode } from "react";
+/**
+ * Props for the `TreeLink` component — the element reference plus an optional label.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeLink/TreeLinkProps
+ */
+export interface TreeLinkProps {
+    /** Reference to an element in the tree — a flat key (`"BooleanSchema"`, `"Store.get"`) or a canonical path (`"/schema/BooleanSchema"`). */
+    readonly name: string;
+    /** Visible label — defaults to `name` (typically a raw type expression like `"SlugSchemaOptions"`). */
+    readonly children?: ReactNode | undefined;
+}
+/**
+ * Inline `Code` token linking to a specific tree element, resolved by reference string — the link-styled counterpart of `TreeButton`.
+ *
+ * - Resolves `name` via `getTreeElement()` — by flat key or canonical path, falling back to the bare name for a single generic type (`Schema<T>` → `Schema`) — and links to the element's canonical `path`.
+ * - A hit becomes a `<Link>` wrapping a `<Code>` token; a miss (e.g. a builtin like `string` or a compound type like `T | null` that isn't an exact token) stays a plain `<Code>` so it still reads as code.
+ * - Designed for the `Type` column of the documentation Parameters / Returns / Throws / Types tables, where only exact-match type names should link.
+ *
+ * @kind component
+ * @param props The element reference `name` and optional `children` label.
+ * @returns A `<Code>` token, wrapped in a `<Link>` when the reference resolves.
+ * @example <TreeLink name="BooleanSchema" />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeLink/TreeLink
+ */
+export declare function TreeLink({ name, children }: TreeLinkProps): ReactElement;

package/ui/tree/TreeLink.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Code } from "../inline/Code.js";
+import { Link } from "../inline/Link.js";
+import { getTreeElement, useTreeMap } from "./TreeContext.js";
+/**
+ * Inline `Code` token linking to a specific tree element, resolved by reference string — the link-styled counterpart of `TreeButton`.
+ *
+ * - Resolves `name` via `getTreeElement()` — by flat key or canonical path, falling back to the bare name for a single generic type (`Schema<T>` → `Schema`) — and links to the element's canonical `path`.
+ * - A hit becomes a `<Link>` wrapping a `<Code>` token; a miss (e.g. a builtin like `string` or a compound type like `T | null` that isn't an exact token) stays a plain `<Code>` so it still reads as code.
+ * - Designed for the `Type` column of the documentation Parameters / Returns / Throws / Types tables, where only exact-match type names should link.
+ *
+ * @kind component
+ * @param props The element reference `name` and optional `children` label.
+ * @returns A `<Code>` token, wrapped in a `<Link>` when the reference resolves.
+ * @example <TreeLink name="BooleanSchema" />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeLink/TreeLink
+ */
+export function TreeLink({ name, children }) {
+    const href = getTreeElement(useTreeMap(), name)?.props.path;
+    const code = _jsx(Code, { children: children ?? name });
+    // A resolved reference links via its canonical `path`; an unresolved one stays a plain code token rather than an empty link.
+    return href ? _jsx(Link, { href: href, children: code }) : code;
+}

package/ui/tree/TreeLink.tsx

@@ -0,0 +1,36 @@
+import type { ReactElement, ReactNode } from "react";
+import { Code } from "../inline/Code.js";
+import { Link } from "../inline/Link.js";
+import { getTreeElement, useTreeMap } from "./TreeContext.js";
+
+/**
+ * Props for the `TreeLink` component — the element reference plus an optional label.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeLink/TreeLinkProps
+ */
+export interface TreeLinkProps {
+	/** Reference to an element in the tree — a flat key (`"BooleanSchema"`, `"Store.get"`) or a canonical path (`"/schema/BooleanSchema"`). */
+	readonly name: string;
+	/** Visible label — defaults to `name` (typically a raw type expression like `"SlugSchemaOptions"`). */
+	readonly children?: ReactNode | undefined;
+}
+
+/**
+ * Inline `Code` token linking to a specific tree element, resolved by reference string — the link-styled counterpart of `TreeButton`.
+ *
+ * - Resolves `name` via `getTreeElement()` — by flat key or canonical path, falling back to the bare name for a single generic type (`Schema<T>` → `Schema`) — and links to the element's canonical `path`.
+ * - A hit becomes a `<Link>` wrapping a `<Code>` token; a miss (e.g. a builtin like `string` or a compound type like `T | null` that isn't an exact token) stays a plain `<Code>` so it still reads as code.
+ * - Designed for the `Type` column of the documentation Parameters / Returns / Throws / Types tables, where only exact-match type names should link.
+ *
+ * @kind component
+ * @param props The element reference `name` and optional `children` label.
+ * @returns A `<Code>` token, wrapped in a `<Link>` when the reference resolves.
+ * @example <TreeLink name="BooleanSchema" />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeLink/TreeLink
+ */
+export function TreeLink({ name, children }: TreeLinkProps): ReactElement {
+	const href = getTreeElement(useTreeMap(), name)?.props.path;
+	const code = <Code>{children ?? name}</Code>;
+	// A resolved reference links via its canonical `path`; an unresolved one stays a plain code token rather than an empty link.
+	return href ? <Link href={href}>{code}</Link> : code;
+}

package/ui/tree/index.d.ts

@@ -5,6 +5,7 @@ export * from "./TreeCard.js";
 export * from "./TreeCards.js";
 export * from "./TreeContext.js";
 export * from "./TreeIndexPage.js";
+export * from "./TreeLink.js";
 export * from "./TreeMenu.js";
 export * from "./TreePage.js";
 export * from "./TreeRouter.js";

package/ui/tree/index.js

@@ -5,6 +5,7 @@ export * from "./TreeCard.js";
 export * from "./TreeCards.js";
 export * from "./TreeContext.js";
 export * from "./TreeIndexPage.js";
+export * from "./TreeLink.js";
 export * from "./TreeMenu.js";
 export * from "./TreePage.js";
 export * from "./TreeRouter.js";

package/ui/tree/index.ts

@@ -5,6 +5,7 @@ export * from "./TreeCard.js";
 export * from "./TreeCards.js";
 export * from "./TreeContext.js";
 export * from "./TreeIndexPage.js";
+export * from "./TreeLink.js";
 export * from "./TreeMenu.js";
 export * from "./TreePage.js";
 export * from "./TreeRouter.js";

package/util/tree.d.ts

@@ -127,10 +127,20 @@ export interface DocumentationElementProps extends TreeElementProps {
     readonly class?: string | undefined;
     /** Whether the property is read-only — a `readonly` field, or a getter with no matching setter. */
     readonly readonly?: boolean | undefined;
-    /** Name of the class/interface this class/interface extends (e.g. `"AbstractStore"`). Raw string — resolved to a link at render time. */
+    /** Full type text of the class/interface this extends, including any generic arguments (e.g. `"AbstractStore<string>"`, `"Omit<StringSchemaOptions, 'value'>"`). Resolved to a link at render time, trimming generics to the bare name; builtins/wrappers that don't resolve stay as text. */
     readonly extends?: string | undefined;
-    /** Names of the interfaces this class/interface implements (e.g. `["Serializable"]`). Raw strings — resolved to links at render time; builtins simply stay as text. */
+    /** Full type text of the interfaces this implements, including generic arguments (e.g. `["Serializable<string>"]`). Resolved to links at render time (generics trimmed for lookup); builtins simply stay as text. */
     readonly implements?: ImmutableArray<string> | undefined;
+    /**
+     * Type names referenced by a `type` alias's body (e.g. `["OtherType"]` for `type X = string | OtherType`).
+     * - Raw identifier strings — resolved to links at render time; the alias's own generic parameters and primitive keywords are excluded, and unresolved names stay as plain text.
+     */
+    readonly types?: ImmutableArray<string> | undefined;
+    /**
+     * Structured member list for an `interface` or object-literal `type` — each property's `name`, `type`, optionality, `default`, and `description`.
+     * - Reuses the `DocumentationParam` shape so an options-bag parameter can be flattened into its individual fields at render time.
+     */
+    readonly properties?: ImmutableArray<DocumentationParam> | undefined;
 }
 /**
  * Element representing a documented code symbol.
@@ -185,8 +195,9 @@ export interface SearchTreeOptions {
  * Search the descendants of a tree element and return the best-ranked matches.
  *
  * - Walks every descendant of `scope` (depth-first; `scope` itself is not a candidate), optionally narrowed by `options.filter`.
- * - Tokenises `query` with `getWords()` so quoted phrases match literally: `searchTree(root, '"hello world" foo')` scores the phrase `hello world` *and* the word `foo` independently, stacking their scores.
- * - Ranks each candidate (case-insensitive) per token, summing: `name` exact > `name` starts-with > `name` includes > `title` includes > `description` includes > `content` includes. A `name` match always outranks a content-only match.
+ * - Tokenises `query` with `getWords()` so quoted phrases match literally: `searchTree(root, '"hello world" foo')` matches the phrase `hello world` *and* the word `foo`.
+ * - Requires *every* token to match (AND, not OR): a candidate is only returned when each token matches at least one of its props. So `date util` returns only elements matching both `date` and `util`, not either alone.
+ * - Ranks each candidate (case-insensitive) per token, summing each token's best tier: `name` exact > `name` starts-with > `name` includes > `title` includes > `description` includes > `content` includes. A `name` match always outranks a content-only match.
  * - An empty `query` returns the (filtered) candidates in tree order — useful for a filter-only or "show everything" listing.
  *
  * @param scope The element whose descendants are searched.

package/util/tree.js

@@ -47,8 +47,9 @@ function _flatKey(element) {
  * Search the descendants of a tree element and return the best-ranked matches.
  *
  * - Walks every descendant of `scope` (depth-first; `scope` itself is not a candidate), optionally narrowed by `options.filter`.
- * - Tokenises `query` with `getWords()` so quoted phrases match literally: `searchTree(root, '"hello world" foo')` scores the phrase `hello world` *and* the word `foo` independently, stacking their scores.
- * - Ranks each candidate (case-insensitive) per token, summing: `name` exact > `name` starts-with > `name` includes > `title` includes > `description` includes > `content` includes. A `name` match always outranks a content-only match.
+ * - Tokenises `query` with `getWords()` so quoted phrases match literally: `searchTree(root, '"hello world" foo')` matches the phrase `hello world` *and* the word `foo`.
+ * - Requires *every* token to match (AND, not OR): a candidate is only returned when each token matches at least one of its props. So `date util` returns only elements matching both `date` and `util`, not either alone.
+ * - Ranks each candidate (case-insensitive) per token, summing each token's best tier: `name` exact > `name` starts-with > `name` includes > `title` includes > `description` includes > `content` includes. A `name` match always outranks a content-only match.
  * - An empty `query` returns the (filtered) candidates in tree order — useful for a filter-only or "show everything" listing.
  *
  * @param scope The element whose descendants are searched.
@@ -91,7 +92,7 @@ const _SCORE_NAME_INCLUDES = 100;
 const _SCORE_TITLE = 10;
 const _SCORE_DESCRIPTION = 4;
 const _SCORE_CONTENT = 1;
-/** Score one element's props against the (already lower-cased) query tokens — each token contributes its best-matching tier, summed. */
+/** Score one element's props against the (already lower-cased) query tokens — every token must match (AND), each contributing its best-matching tier, summed. */
 function _scoreElement(props, tokens) {
     const name = props.name.toLowerCase();
     const title = props.title?.toLowerCase() ?? "";
@@ -99,6 +100,7 @@ function _scoreElement(props, tokens) {
     const content = props.content?.toLowerCase() ?? "";
     let score = 0;
     for (const token of tokens) {
+        // Every token must match somewhere — a single token that matches nothing drops the candidate entirely (AND, not OR).
         if (name === token)
             score += _SCORE_NAME_EXACT;
         else if (name.startsWith(token))
@@ -111,6 +113,8 @@ function _scoreElement(props, tokens) {
             score += _SCORE_DESCRIPTION;
         else if (content.includes(token))
             score += _SCORE_CONTENT;
+        else
+            return 0;
     }
     return score;
 }