shelving 1.206.1 → 1.208.0

package/extract/TypescriptExtractor.d.ts

@@ -4,6 +4,7 @@ import { FileExtractor } from "./FileExtractor.js";
  * File extractor that parses a TypeScript source file into a tree element.
  * - Uses the TypeScript compiler API to parse the AST.
  * - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
+ * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`.
  * - Top-of-file JSDoc comment becomes the file's `content`.
  * - Does not set `title` — TS source files have no confident title source. The renderer falls back to `name`.
  */

package/extract/TypescriptExtractor.js

@@ -5,6 +5,7 @@ import { FileExtractor } from "./FileExtractor.js";
  * File extractor that parses a TypeScript source file into a tree element.
  * - Uses the TypeScript compiler API to parse the AST.
  * - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
+ * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`.
  * - Top-of-file JSDoc comment becomes the file's `content`.
  * - Does not set `title` — TS source files have no confident title source. The renderer falls back to `name`.
  */
@@ -12,17 +13,45 @@ export class TypescriptExtractor extends FileExtractor {
     extractProps(name, text) {
         const source = ts.createSourceFile(name, text, ts.ScriptTarget.Latest, true);
         const content = _getFileDocComment(source);
-        const children = [];
+        // Collect elements by key, merging overloads (same name) by appending signatures.
+        const byKey = new Map();
         for (const statement of source.statements) {
             const element = _extractStatement(statement, source);
-            if (element)
-                children.push(element);
+            if (!element)
+                continue;
+            const existing = byKey.get(element.key);
+            byKey.set(element.key, existing ? _mergeOverloads(existing, element) : element);
         }
         // No `title` — TS source files don't have a confident title source (the filename isn't one).
         // The renderer falls back to `name` when displaying.
-        return { name, content, children };
+        return { name, content, children: Array.from(byKey.values()) };
     }
 }
+/** Merge a newly-extracted overload into the existing documentation element with the same key. */
+function _mergeOverloads(existing, next) {
+    const a = existing.props;
+    const b = next.props;
+    const merged = {
+        ...a,
+        // Keep first description encountered; fill in if `existing` had none.
+        description: a.description ?? b.description,
+        // Append signatures.
+        signatures: _concat(a.signatures, b.signatures),
+        // Append params, returns, throws, examples — never dedupe (per spec).
+        params: _concat(a.params, b.params),
+        returns: _concat(a.returns, b.returns),
+        throws: _concat(a.throws, b.throws),
+        examples: _concat(a.examples, b.examples),
+    };
+    return { ...existing, props: merged };
+}
+function _concat(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return [...a, ...b];
+}
 /** Get the leading JSDoc comment of the file (before the first statement). */
 function _getFileDocComment(source) {
     const { statements } = source;
@@ -57,8 +86,9 @@ function _extractStatement(statement, source) {
     if (!kind)
         return;
     const signature = _getSignature(statement, source);
-    const params = _getParams(statement, source);
-    const returns = _getReturnType(statement, source);
+    const params = _getParams(statement, source, jsDoc?.params);
+    const returns = _getReturns(statement, source, jsDoc?.returns);
+    const throws = jsDoc?.throws;
     const examples = jsDoc?.examples;
     const children = _getClassMembers(statement, source);
     return {
@@ -68,9 +98,10 @@ function _extractStatement(statement, source) {
             name,
             kind,
             description: jsDoc?.description,
-            signature,
+            signatures: signature ? [signature] : undefined,
             params,
             returns,
+            throws,
             examples,
             children,
         },
@@ -125,11 +156,10 @@ function _getSignature(statement, source) {
             return declaration.type.getText(source);
     }
 }
-/** Extract parameters from a function or method declaration. */
-function _getParams(statement, source) {
+/** Extract parameters from a function or method declaration, enriched with JSDoc `@param` descriptions. */
+function _getParams(statement, source, jsDocParams) {
     if (!ts.isFunctionDeclaration(statement))
         return;
-    const jsDocParams = _getJSDoc(statement, source)?.params;
     const params = statement.parameters.map(p => {
         const name = p.name.getText(source);
         const type = p.type?.getText(source);
@@ -139,10 +169,20 @@ function _getParams(statement, source) {
     });
     return params.length ? params : undefined;
 }
-/** Get the return type of a function declaration. */
-function _getReturnType(statement, source) {
-    if (ts.isFunctionDeclaration(statement) && statement.type)
-        return statement.type.getText(source);
+/** Extract return entries — combines the signature return type with any `@returns` descriptions. */
+function _getReturns(statement, source, jsDocReturns) {
+    if (!ts.isFunctionDeclaration(statement))
+        return jsDocReturns;
+    const type = statement.type?.getText(source);
+    if (jsDocReturns?.length) {
+        // Merge: first entry gets the inferred type if it doesn't already have one.
+        const [first, ...rest] = jsDocReturns;
+        if (!first)
+            return jsDocReturns;
+        return [{ type: first.type ?? type, description: first.description }, ...rest];
+    }
+    if (type && type !== "void")
+        return [{ type }];
 }
 /** Extract class or interface members as child elements. */
 function _getClassMembers(statement, source) {
@@ -163,27 +203,30 @@ function _getClassMembers(statement, source) {
         if (ts.isMethodDeclaration(member) || ts.isMethodSignature(member)) {
             const params = member.parameters.map(p => p.getText(source)).join(", ");
             const ret = member.type ? member.type.getText(source) : "void";
-            members.push({
-                type: "tree-documentation",
-                key: requireSlug(name),
-                props: {
-                    name,
-                    description,
-                    kind: "method",
-                    signature: `(${params}) => ${ret}`,
-                },
-            });
+            const signature = `(${params}) => ${ret}`;
+            const key = requireSlug(name);
+            const existingIndex = members.findIndex(m => m.key === key);
+            const existing = members[existingIndex];
+            if (existing) {
+                members[existingIndex] = {
+                    ...existing,
+                    props: { ...existing.props, signatures: _concat(existing.props.signatures, [signature]) },
+                };
+            }
+            else {
+                members.push({
+                    type: "tree-documentation",
+                    key,
+                    props: { name, description, kind: "method", signatures: [signature] },
+                });
+            }
         }
         else if (ts.isPropertyDeclaration(member) || ts.isPropertySignature(member)) {
+            const type = member.type?.getText(source);
             members.push({
                 type: "tree-documentation",
                 key: requireSlug(name),
-                props: {
-                    name,
-                    description,
-                    kind: "property",
-                    signature: member.type?.getText(source),
-                },
+                props: { name, description, kind: "property", signatures: type ? [type] : undefined },
             });
         }
     }
@@ -204,10 +247,14 @@ function _getJSDoc(node, source) {
             continue;
         const description = _parseJSDocComment(text);
         const params = _parseJSDocParams(text);
+        const returns = _parseJSDocReturns(text);
+        const throws = _parseJSDocThrows(text);
         const examples = _parseJSDocExamples(text);
         return {
             description: description || undefined,
             params: params.length ? params : undefined,
+            returns: returns.length ? returns : undefined,
+            throws: throws.length ? throws : undefined,
             examples: examples.length ? examples : undefined,
         };
     }
@@ -229,27 +276,59 @@ function _parseJSDocComment(text) {
     const result = description.join("\n").trim();
     return result || undefined;
 }
-/** Parse `@param` tags from a JSDoc comment. */
+/** Parse `@param` tags from a JSDoc comment. Duplicates are kept (overloads). */
 function _parseJSDocParams(text) {
     const results = [];
-    const regexp = /@param\s+(?:\{[^}]*\}\s+)?(\w+)\s+(.*)/g;
+    // `@param {Type} name description` — type is optional.
+    const regexp = /@param\s+(?:\{([^}]*)\}\s+)?(\w+)\s+(.*)/g;
+    let match;
+    while ((match = regexp.exec(text))) {
+        const type = match[1]?.trim();
+        const name = match[2];
+        const description = match[3]?.trim();
+        if (name)
+            results.push({ name, type: type || undefined, description: description || undefined });
+    }
+    return results;
+}
+/** Parse `@returns` / `@return` tags from a JSDoc comment. */
+function _parseJSDocReturns(text) {
+    const results = [];
+    // `@returns {Type} description` or `@return {Type} description`.
+    const regexp = /@returns?\s+(?:\{([^}]*)\}\s*)?(.*)/g;
+    let match;
+    while ((match = regexp.exec(text))) {
+        const type = match[1]?.trim();
+        const description = match[2]?.trim();
+        if (type || description)
+            results.push({ type: type || undefined, description: description || undefined });
+    }
+    return results;
+}
+/** Parse `@throws` / `@throw` tags from a JSDoc comment. */
+function _parseJSDocThrows(text) {
+    const results = [];
+    // `@throws {Type} description` or `@throw {Type} description`.
+    const regexp = /@throws?\s+(?:\{([^}]*)\}\s*)?(.*)/g;
     let match;
     while ((match = regexp.exec(text))) {
-        const name = match[1];
-        const description = match[2];
-        if (name && description)
-            results.push({ name, description: description.trim() });
+        const type = match[1]?.trim();
+        const description = match[2]?.trim();
+        if (type || description)
+            results.push({ type: type || undefined, description: description || undefined });
     }
     return results;
 }
 /** Parse `@example` tags from a JSDoc comment. */
 function _parseJSDocExamples(text) {
     const results = [];
-    const regexp = /@example\s+(.*)/g;
+    // `@example` followed by the rest of the line.
+    const regexp = /@examples?\s+(.+)/g;
     let match;
     while ((match = regexp.exec(text))) {
-        if (match[1])
-            results.push(match[1].trim());
+        const description = match[1]?.trim();
+        if (description)
+            results.push({ description });
     }
     return results;
 }

package/package.json

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

package/store/URLStore.d.ts

@@ -47,5 +47,20 @@ export declare class URLStore extends BusyStore<ImmutableURL, PossibleURL> {
     omitParams(...keys: string[]): ImmutableURL;
     /** Return the current URL with an additional param. */
     omitParam(key: string): ImmutableURL;
+    /**
+     * Is `target` active relative to this store's URL?
+     * - Active means `target` resolves to the exact same URL as this store's current value.
+     *
+     * @param target URL (or relative path resolved against this store's `base`) to test.
+     */
+    isActive(target: PossibleURL): boolean;
+    /**
+     * Is `target` proud relative to this store's URL?
+     * - Proud means this store's URL is `target` or a descendant of `target` — i.e. `target` sits at or above the current URL in the hierarchy.
+     * - Useful for marking a menu item as "current branch" when the user is somewhere deeper in its sub-tree.
+     *
+     * @param target URL (or relative path resolved against this store's `base`) to test.
+     */
+    isProud(target: PossibleURL): boolean;
     toString(): string;
 }

package/store/URLStore.js

@@ -1,6 +1,6 @@
 import { getGetter, getSetter } from "../util/class.js";
 import { clearURIParams, getURIParam, getURIParams, omitURIParams, requireURIParam, withURIParam, withURIParams, } from "../util/uri.js";
-import { getURL, requireURL } from "../util/url.js";
+import { getURL, isURLActive, isURLProud, requireURL } from "../util/url.js";
 import { BusyStore } from "./BusyStore.js";
 /** Store a URL, e.g. `https://top.com/a/b/c` */
 export class URLStore extends BusyStore {
@@ -105,6 +105,25 @@ export class URLStore extends BusyStore {
     omitParam(key) {
         return omitURIParams(this.value, key);
     }
+    /**
+     * Is `target` active relative to this store's URL?
+     * - Active means `target` resolves to the exact same URL as this store's current value.
+     *
+     * @param target URL (or relative path resolved against this store's `base`) to test.
+     */
+    isActive(target) {
+        return isURLActive(this.value, requireURL(target, this.base, this.isActive));
+    }
+    /**
+     * Is `target` proud relative to this store's URL?
+     * - Proud means this store's URL is `target` or a descendant of `target` — i.e. `target` sits at or above the current URL in the hierarchy.
+     * - Useful for marking a menu item as "current branch" when the user is somewhere deeper in its sub-tree.
+     *
+     * @param target URL (or relative path resolved against this store's `base`) to test.
+     */
+    isProud(target) {
+        return isURLProud(this.value, requireURL(target, this.base, this.isProud));
+    }
     toString() {
         return this.href;
     }

package/ui/app/App.module.css

@@ -102,65 +102,10 @@
 	--shadow-element: 0 3px 16px -8px var(--color-overlay);
 	--shadow-block: 0 4px 24px -12px var(--color-overlay);
 
-	/* Primary colors */
-	--primary-text: var(--color-blue);
-	--primary-contrast: var(--color-white);
-	--primary-surface: color-mix(in srgb, var(--primary-text) 12%, white);
-
-	/* Secondary colors */
-	--secondary-text: var(--color-purple);
-	--secondary-contrast: var(--color-white);
-	--secondary-surface: color-mix(in srgb, var(--secondary-text) 12%, white);
-
-	/* Tertiary colors */
-	--tertiary-text: var(--color-cyan);
-	--tertiary-contrast: var(--color-white);
-	--tertiary-surface: color-mix(in srgb, var(--tertiary-text) 12%, white);
-
-	/* Quiet colors */
-	--quiet-text: var(--color-quiet);
-	--quiet-contrast: var(--color-contrast);
-	--quiet-surface: var(--color-surface);
-
 	/* Focus colors */
 	--focus-text: var(--color-focus);
 	--focus-contrast: var(--color-white);
 	--focus-surface: color-mix(in srgb, var(--focus-text) 12%, white);
-
-	/* Loading colors */
-	--loading-text: var(--color-loading);
-	--loading-contrast: var(--color-contrast);
-	--loading-surface: var(--color-surface);
-
-	/* Info colors */
-	--info-text: var(--color-blue);
-	--info-contrast: var(--color-white);
-	--info-surface: color-mix(in srgb, var(--info-text) 12%, white);
-
-	/* Success colors */
-	--success-text: var(--color-green);
-	--success-contrast: var(--color-white);
-	--success-surface: color-mix(in srgb, var(--success-text) 12%, white);
-
-	/* Warning colors */
-	--warning-text: var(--color-orange);
-	--warning-contrast: var(--color-white);
-	--warning-surface: color-mix(in srgb, var(--warning-text) 12%, white);
-
-	/* Error colors */
-	--error-text: var(--color-red);
-	--error-contrast: var(--color-white);
-	--error-surface: color-mix(in srgb, var(--error-text) 12%, white);
-
-	/* Danger colors */
-	--danger-text: var(--color-red);
-	--danger-contrast: var(--color-white);
-	--danger-surface: color-mix(in srgb, var(--danger-text) 12%, white);
-
-	/* Highlight colors */
-	--highlight-text: var(--color-yellow);
-	--highlight-contrast: var(--color-black);
-	--highlight-surface: color-mix(in srgb, var(--highlight-text) 12%, white);
 }
 
 .app {

package/ui/docs/DirectoryCard.js

@@ -1,5 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { TREE_CARD_CLASS, TREE_CARD_DESCRIPTION_CLASS, TREE_CARD_TITLE_CLASS } from "../tree/TreeCards.js";
+import { requireTreeHref } from "../tree/TreePathContext.js";
 /** Card renderer for a `tree-directory` element. */
 export function DirectoryCard({ title, name, description }) {
-    return (_jsxs("div", { children: [_jsx("h3", { children: title ?? name }), description && _jsx("p", { children: description })] }));
+    const href = requireTreeHref();
+    return (_jsxs("a", { className: TREE_CARD_CLASS, href: href, children: [_jsx("h3", { className: TREE_CARD_TITLE_CLASS, children: title ?? name }), description && _jsx("p", { className: TREE_CARD_DESCRIPTION_CLASS, children: description })] }));
 }

package/ui/docs/DirectoryCard.tsx

@@ -1,12 +1,15 @@
 import type { ReactNode } from "react";
 import type { DirectoryElementProps } from "../../util/element.js";
+import { TREE_CARD_CLASS, TREE_CARD_DESCRIPTION_CLASS, TREE_CARD_TITLE_CLASS } from "../tree/TreeCards.js";
+import { requireTreeHref } from "../tree/TreePathContext.js";
 
 /** Card renderer for a `tree-directory` element. */
 export function DirectoryCard({ title, name, description }: DirectoryElementProps): ReactNode {
+	const href = requireTreeHref();
 	return (
-		<div>
-			<h3>{title ?? name}</h3>
-			{description && <p>{description}</p>}
-		</div>
+		<a className={TREE_CARD_CLASS} href={href}>
+			<h3 className={TREE_CARD_TITLE_CLASS}>{title ?? name}</h3>
+			{description && <p className={TREE_CARD_DESCRIPTION_CLASS}>{description}</p>}
+		</a>
 	);
 }

package/ui/docs/DocumentationCard.d.ts

@@ -1,4 +1,4 @@
 import type { ReactNode } from "react";
 import type { DocumentationElementProps } from "../../util/element.js";
 /** Card renderer for a `tree-documentation` element. */
-export declare function DocumentationCard({ title, name, description, signature }: DocumentationElementProps): ReactNode;
+export declare function DocumentationCard({ title, name, kind, description, signatures }: DocumentationElementProps): ReactNode;

package/ui/docs/DocumentationCard.js

@@ -1,5 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { TREE_CARD_CLASS, TREE_CARD_DESCRIPTION_CLASS, TREE_CARD_TITLE_CLASS } from "../index.js";
+import { requireTreeHref } from "../tree/TreePathContext.js";
+import { DocumentationKind } from "./DocumentationKind.js";
 /** Card renderer for a `tree-documentation` element. */
-export function DocumentationCard({ title, name, description, signature }) {
-    return (_jsxs("div", { children: [_jsx("h3", { children: _jsx("code", { children: title ?? name }) }), signature && (_jsx("pre", { children: _jsx("code", { children: signature }) })), description && _jsx("p", { children: description })] }));
+export function DocumentationCard({ title, name, kind, description, signatures }) {
+    const href = requireTreeHref();
+    return (_jsxs("a", { className: TREE_CARD_CLASS, href: href, children: [_jsx("h3", { className: TREE_CARD_TITLE_CLASS, children: _jsx("code", { children: title ?? name }) }), kind && _jsx(DocumentationKind, { kind: kind }), signatures?.map(sig => (_jsx("pre", { children: _jsx("code", { children: sig }) }, sig))), description && _jsx("p", { className: TREE_CARD_DESCRIPTION_CLASS, children: description })] }));
 }

package/ui/docs/DocumentationCard.tsx

@@ -1,19 +1,24 @@
 import type { ReactNode } from "react";
 import type { DocumentationElementProps } from "../../util/element.js";
+import { TREE_CARD_CLASS, TREE_CARD_DESCRIPTION_CLASS, TREE_CARD_TITLE_CLASS } from "../index.js";
+import { requireTreeHref } from "../tree/TreePathContext.js";
+import { DocumentationKind } from "./DocumentationKind.js";
 
 /** Card renderer for a `tree-documentation` element. */
-export function DocumentationCard({ title, name, description, signature }: DocumentationElementProps): ReactNode {
+export function DocumentationCard({ title, name, kind, description, signatures }: DocumentationElementProps): ReactNode {
+	const href = requireTreeHref();
 	return (
-		<div>
-			<h3>
+		<a className={TREE_CARD_CLASS} href={href}>
+			<h3 className={TREE_CARD_TITLE_CLASS}>
 				<code>{title ?? name}</code>
 			</h3>
-			{signature && (
-				<pre>
-					<code>{signature}</code>
+			{kind && <DocumentationKind kind={kind} />}
+			{signatures?.map(sig => (
+				<pre key={sig}>
+					<code>{sig}</code>
 				</pre>
-			)}
-			{description && <p>{description}</p>}
-		</div>
+			))}
+			{description && <p className={TREE_CARD_DESCRIPTION_CLASS}>{description}</p>}
+		</a>
 	);
 }

package/ui/docs/DocumentationKind.d.ts

@@ -0,0 +1,13 @@
+import type { ReactElement } from "react";
+/** Props for `DocumentationKind`. */
+export interface DocumentationKindProps {
+    /** The documentation kind (e.g. `"function"`, `"class"`, `"interface"`, `"type"`, `"constant"`, `"method"`, `"property"`). */
+    readonly kind: string;
+}
+/**
+ * Colour-coded tag for a documented symbol's kind.
+ * - Thin wrapper over `<Tag>` that maps the kind string to a raw colour variant.
+ *
+ * @example <DocumentationKind kind="function" />
+ */
+export declare function DocumentationKind({ kind }: DocumentationKindProps): ReactElement;

package/ui/docs/DocumentationKind.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Tag } from "../misc/Tag.js";
+/** Mapping from a documented symbol's `kind` to its tag colour. */
+const KIND_COLOR = {
+    function: "blue",
+    class: "purple",
+    interface: "cyan",
+    type: "pink",
+    constant: "green",
+    method: "orange",
+    property: "yellow",
+};
+/**
+ * Colour-coded tag for a documented symbol's kind.
+ * - Thin wrapper over `<Tag>` that maps the kind string to a raw colour variant.
+ *
+ * @example <DocumentationKind kind="function" />
+ */
+export function DocumentationKind({ kind }) {
+    const color = KIND_COLOR[kind];
+    return _jsx(Tag, { ...(color ? { [color]: true } : {}), children: kind });
+}

package/ui/docs/DocumentationKind.tsx

@@ -0,0 +1,31 @@
+import type { ReactElement } from "react";
+import type { Color } from "../misc/Color.js";
+import { Tag } from "../misc/Tag.js";
+
+/** Props for `DocumentationKind`. */
+export interface DocumentationKindProps {
+	/** The documentation kind (e.g. `"function"`, `"class"`, `"interface"`, `"type"`, `"constant"`, `"method"`, `"property"`). */
+	readonly kind: string;
+}
+
+/** Mapping from a documented symbol's `kind` to its tag colour. */
+const KIND_COLOR: { readonly [K in string]?: Color } = {
+	function: "blue",
+	class: "purple",
+	interface: "cyan",
+	type: "pink",
+	constant: "green",
+	method: "orange",
+	property: "yellow",
+};
+
+/**
+ * Colour-coded tag for a documented symbol's kind.
+ * - Thin wrapper over `<Tag>` that maps the kind string to a raw colour variant.
+ *
+ * @example <DocumentationKind kind="function" />
+ */
+export function DocumentationKind({ kind }: DocumentationKindProps): ReactElement {
+	const color = KIND_COLOR[kind];
+	return <Tag {...(color ? { [color]: true } : {})}>{kind}</Tag>;
+}

package/ui/docs/DocumentationPage.d.ts

@@ -2,7 +2,7 @@ import type { ReactNode } from "react";
 import type { DocumentationElementProps } from "../../util/element.js";
 /**
  * Page renderer for a `tree-documentation` element.
- * - Renders title, signature, description, parameters, return type, and child symbols.
- * - All props are optional; only sections with data are shown (so this works for any `kind`).
+ * - Renders title, signatures (one per overload), description, parameters, returns, throws, examples, and child symbols.
+ * - All sections are conditional — only render when their array has entries.
  */
-export declare function DocumentationPage({ title, name, description, signature, params, returns, children, }: DocumentationElementProps): ReactNode;
+export declare function DocumentationPage({ title, name, kind, description, signatures, params, returns, throws, examples, children, }: DocumentationElementProps): ReactNode;

package/ui/docs/DocumentationPage.js

@@ -1,11 +1,13 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Page } from "../page/Page.js";
 import { TreeCards } from "../tree/TreeCards.js";
+import { DocumentationKind } from "./DocumentationKind.js";
+const DEFAULT_TYPE = "unknown";
 /**
  * Page renderer for a `tree-documentation` element.
- * - Renders title, signature, description, parameters, return type, and child symbols.
- * - All props are optional; only sections with data are shown (so this works for any `kind`).
+ * - Renders title, signatures (one per overload), description, parameters, returns, throws, examples, and child symbols.
+ * - All sections are conditional — only render when their array has entries.
  */
-export function DocumentationPage({ title, name, description, signature, params, returns, children, }) {
-    return (_jsxs(Page, { title: title ?? name, children: [signature && (_jsx("pre", { children: _jsx("code", { children: signature }) })), description && _jsx("p", { children: description }), params && (_jsxs("section", { children: [_jsx("h2", { children: "Parameters" }), _jsx("dl", { children: params.map(p => (_jsxs("div", { children: [_jsxs("dt", { children: [_jsx("code", { children: p.name }), p.type && (_jsxs(_Fragment, { children: [": ", _jsx("code", { children: p.type })] })), p.optional && _jsx(_Fragment, { children: " (optional)" })] }), p.description && _jsx("dd", { children: p.description })] }, p.name))) })] })), returns && (_jsxs("section", { children: [_jsx("h2", { children: "Returns" }), _jsx("p", { children: _jsx("code", { children: returns }) })] })), children && _jsx(TreeCards, { children: children })] }));
+export function DocumentationPage({ title, name, kind, description, signatures, params, returns, throws, examples, children, }) {
+    return (_jsxs(Page, { title: title ?? name, children: [kind && _jsx(DocumentationKind, { kind: kind }), signatures?.map(sig => (_jsx("pre", { children: _jsx("code", { children: sig }) }, sig))), description && _jsx("p", { children: description }), params?.length && (_jsxs("section", { children: [_jsx("h2", { children: "Parameters" }), _jsx("dl", { children: params.map(({ name, type = DEFAULT_TYPE, description = "", optional }) => (_jsxs("div", { children: [_jsxs("dt", { children: [_jsx("code", { children: name }), ": ", _jsx("code", { children: type ?? DEFAULT_TYPE }), optional && _jsx(_Fragment, { children: " (optional)" })] }), description && _jsx("dd", { children: description })] }, `${name}-${type}-${description}`))) })] })), returns?.length && (_jsxs("section", { children: [_jsx("h2", { children: "Returns" }), _jsx("dl", { children: returns.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsxs("div", { children: [_jsx("dt", { children: _jsx("code", { children: type }) }), description && _jsx("dd", { children: description })] }, `${type}-${description}`))) })] })), throws?.length && (_jsxs("section", { children: [_jsx("h2", { children: "Throws" }), _jsx("dl", { children: throws.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsxs("div", { children: [_jsx("dt", { children: _jsx("code", { children: type }) }), description && _jsx("dd", { children: description })] }, `${type}-${description}`))) })] })), examples?.length && (_jsxs("section", { children: [_jsx("h2", { children: "Examples" }), examples.map(({ description }) => (_jsx("pre", { children: _jsx("code", { children: description }) }, description)))] })), children && _jsx(TreeCards, { children: children })] }));
 }