shelving 1.253.0 → 1.253.1

package/extract/TypescriptExtractor.d.ts

@@ -9,9 +9,9 @@ import { FileExtractor } from "./FileExtractor.js";
  * - Class declarations synthesise their `signatures`, `params`, and `returns` from the constructor — `new ClassName<…>(…)` including generics, one signature per constructor overload, with `returns` set to the class type. Param descriptions come from the constructor's `@param` first, then the class's `@param`.
  * - 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.
+ * - Sets `title` on every `tree-documentation` child — `name()` for functions, `Class.name()` for methods, bare `name` for other kinds. (Data members are not child elements — see `properties` below.)
  * - 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.
+ * - Records a structured `properties` list for classes, interfaces, and object-literal `type` aliases — each data member's (property/getter/setter) name, type, optionality, default, and description. This is the single source for a type's data members: they render as the type's Properties table and flatten into an options-bag parameter's fields at render time, rather than each becoming its own child element. Methods stay as child elements.
  * - Names a destructured (binding-pattern) parameter for the Param column — which has no name of its own — from an explicit `@param`, else its rest element (`...options`), else a type-derived fallback (`props` / `options`). The signature still shows the full `{ … }`.
  * - 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.

package/extract/TypescriptExtractor.js

@@ -10,9 +10,9 @@ import { extractMarkdownProps } from "./MarkupExtractor.js";
  * - Class declarations synthesise their `signatures`, `params`, and `returns` from the constructor — `new ClassName<…>(…)` including generics, one signature per constructor overload, with `returns` set to the class type. Param descriptions come from the constructor's `@param` first, then the class's `@param`.
  * - 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.
+ * - Sets `title` on every `tree-documentation` child — `name()` for functions, `Class.name()` for methods, bare `name` for other kinds. (Data members are not child elements — see `properties` below.)
  * - 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.
+ * - Records a structured `properties` list for classes, interfaces, and object-literal `type` aliases — each data member's (property/getter/setter) name, type, optionality, default, and description. This is the single source for a type's data members: they render as the type's Properties table and flatten into an options-bag parameter's fields at render time, rather than each becoming its own child element. Methods stay as child elements.
  * - Names a destructured (binding-pattern) parameter for the Param column — which has no name of its own — from an explicit `@param`, else its rest element (`...options`), else a type-derived fallback (`props` / `options`). The signature still shows the full `{ … }`.
  * - 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.
@@ -199,12 +199,14 @@ function _getReferencedTypes(statement, source) {
     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.
+ * Extract structured property entries from a class, interface, or object-literal `type` alias, mirroring the `DocumentationParam` shape.
+ * - This is the single source of truth for a type's data members: properties (and getters/setters) are documented here as a structured list, not as their own child elements. Methods stay as child elements (see `_getClassMembers`).
+ * - Used both to render the type's own Properties table and to 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/protected, `_`-prefixed, `override`, and `declare` members. Optionality comes from a `?` token; defaults from a class-field initializer or a member's `@default` JSDoc; descriptions from each member's own JSDoc.
+ * - Getters/setters fold into a single entry per name (the getter's type wins for a get/set pair).
  */
 function _getProperties(statement, source) {
-    const members = ts.isInterfaceDeclaration(statement)
+    const members = ts.isInterfaceDeclaration(statement) || ts.isClassDeclaration(statement)
         ? statement.members
         : ts.isTypeAliasDeclaration(statement) && ts.isTypeLiteralNode(statement.type)
             ? statement.type.members
@@ -213,19 +215,48 @@ function _getProperties(statement, source) {
         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 modifiers = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined;
+        // Skip private/protected (not public API), `override` (documented on the base class), and `declare` (ambient re-declarations).
+        if (modifiers?.some(m => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword))
+            continue;
+        if (modifiers?.some(m => m.kind === ts.SyntaxKind.OverrideKeyword || m.kind === ts.SyntaxKind.DeclareKeyword))
+            continue;
         const jsDoc = _getJSDoc(member, source);
-        properties.push({
-            name,
-            type: member.type?.getText(source),
-            description: jsDoc?.description,
-            optional: !!member.questionToken,
-            default: jsDoc?.default,
-        });
+        if (ts.isPropertySignature(member) || ts.isPropertyDeclaration(member)) {
+            // A class field's initializer is its default; otherwise fall back to an explicit `@default` tag.
+            const def = (ts.isPropertyDeclaration(member) ? member.initializer?.getText(source) : undefined) ?? jsDoc?.default;
+            properties.push({
+                name,
+                type: member.type?.getText(source),
+                description: jsDoc?.description,
+                optional: !!member.questionToken,
+                default: def,
+                readonly: modifiers?.some(m => m.kind === ts.SyntaxKind.ReadonlyKeyword) || undefined,
+            });
+        }
+        else if (ts.isGetAccessor(member) || ts.isSetAccessor(member)) {
+            const type = ts.isGetAccessor(member) ? member.type?.getText(source) : member.parameters[0]?.type?.getText(source);
+            const index = properties.findIndex(p => p.name === name);
+            const found = index >= 0 ? properties[index] : undefined;
+            // Fold a get/set pair into one entry: the getter's declared type wins, and the matching setter clears read-only.
+            if (found) {
+                properties[index] = { ...found, type: ts.isGetAccessor(member) && type ? type : found.type, readonly: undefined };
+            }
+            else {
+                // A lone getter is read-only until a setter is seen; a lone setter is writable.
+                properties.push({
+                    name,
+                    type,
+                    description: jsDoc?.description,
+                    optional: false,
+                    default: jsDoc?.default,
+                    readonly: ts.isGetAccessor(member) || undefined,
+                });
+            }
+        }
     }
     return properties.length ? properties : undefined;
 }
@@ -434,12 +465,12 @@ function _getReturns(statement, source, jsDocReturns, name) {
         return [{ type }];
 }
 /**
- * Extract class or interface members as child elements.
- * - `className` is stamped onto every member as its `class` prop (the source of the qualified flat key and the "member of …" affordance) and is prebaked into the member `title` (`Class.name` / `Class.name()`).
+ * Extract a class or interface's **methods** as child elements.
+ * - Data members (properties, getters/setters) are NOT child elements — they're collected as a structured list by [`_getProperties`](#) and rendered as the type's Properties table instead. Only methods, which carry their own params/returns/throws docs, warrant a dedicated page.
+ * - `className` is stamped onto every method as its `class` prop (the source of the qualified flat key and the "member of …" affordance) and is prebaked into the member `title` (`Class.name()`).
  * - Members declared with the `override` modifier are skipped — the base class already documents them, so a subclass page lists only its newly-introduced API.
- * - Members declared with the `declare` modifier are skipped — they're ambient type-only re-declarations (e.g. narrowing an inherited property's type), not new API.
- * - Getters/setters fold into a single `property` element per name; a getter with no matching setter is `readonly`.
- * - `static` members are labelled `static method` / `static property` so the docs site groups them in their own sections, separate from instance `method` / `property`, and their rendered signature is prefixed with the `static ` keyword.
+ * - Members declared with the `declare` modifier are skipped — they're ambient type-only re-declarations, not new API.
+ * - `static` methods are labelled `static method` so the docs site groups them in their own section, separate from instance `method`s, and their rendered signature is prefixed with the `static ` keyword.
  */
 function _getClassMembers(statement, source, className) {
     if (!ts.isClassDeclaration(statement) && !ts.isInterfaceDeclaration(statement))
@@ -459,7 +490,7 @@ function _getClassMembers(statement, source, className) {
         // Skip `declare` members — ambient type-only re-declarations (e.g. a subclass narrowing an inherited property's type), not new API.
         if (modifiers?.some(m => m.kind === ts.SyntaxKind.DeclareKeyword))
             continue;
-        // `static` members are grouped and labelled separately from instance members (`static method` / `static property`),
+        // `static` methods are grouped and labelled separately from instance methods (`static method`),
         // and carry the `static ` keyword in their rendered signature.
         const isStatic = modifiers?.some(m => m.kind === ts.SyntaxKind.StaticKeyword);
         const staticPrefix = isStatic ? "static " : "";
@@ -495,58 +526,7 @@ function _getClassMembers(statement, source, className) {
                 });
             }
         }
-        else if (ts.isPropertyDeclaration(member) || ts.isPropertySignature(member)) {
-            const type = member.type?.getText(source);
-            const readonly = modifiers?.some(m => m.kind === ts.SyntaxKind.ReadonlyKeyword) || undefined;
-            members.push({
-                type: "tree-documentation",
-                key: name,
-                props: {
-                    name,
-                    title: `${className}.${name}`,
-                    description,
-                    content,
-                    kind: isStatic ? "static property" : "property",
-                    class: className,
-                    readonly,
-                    signatures: type ? [`${staticPrefix}${readonly ? "readonly " : ""}${name}: ${type}`] : undefined,
-                },
-            });
-        }
-        else if (ts.isGetAccessor(member) || ts.isSetAccessor(member)) {
-            // Getters/setters fold into one `property`. A getter alone (no setter) is read-only; a setter clears that.
-            const type = ts.isGetAccessor(member) ? member.type?.getText(source) : member.parameters[0]?.type?.getText(source);
-            const key = name;
-            const existingIndex = members.findIndex(m => m.key === key);
-            const existing = members[existingIndex];
-            if (existing) {
-                members[existingIndex] = {
-                    ...existing,
-                    props: {
-                        ...existing.props,
-                        // A getter + setter pair is writable — drop the read-only flag and the `readonly ` signature prefix.
-                        readonly: undefined,
-                        signatures: type ? [`${staticPrefix}${name}: ${type}`] : existing.props.signatures,
-                    },
-                };
-            }
-            else {
-                members.push({
-                    type: "tree-documentation",
-                    key,
-                    props: {
-                        name,
-                        title: `${className}.${name}`,
-                        description,
-                        content,
-                        kind: isStatic ? "static property" : "property",
-                        class: className,
-                        readonly: ts.isGetAccessor(member) || undefined,
-                        signatures: type ? [`${staticPrefix}${ts.isGetAccessor(member) ? "readonly " : ""}${name}: ${type}`] : undefined,
-                    },
-                });
-            }
-        }
+        // Properties, getters, and setters are not child elements — `_getProperties` collects them as a structured list instead.
     }
     return members.length ? members : undefined;
 }

package/package.json

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

package/ui/block/Card.module.css

@@ -68,7 +68,8 @@
 
 @layer overrides {
 	.card {
-		&:has(.overlay:not(focus-visible)) {
+		/* Show the focus ring only while the navigable overlay is keyboard-focused; hide it otherwise (including non-clickable cards, which have no overlay). */
+		&:not(:has(.overlay:focus-visible)) {
 			outline-color: transparent;
 		}
 	}

package/ui/docs/DocumentationDescription.d.ts

@@ -11,16 +11,19 @@ export interface DocumentationDescriptionProps {
     readonly default?: string | undefined;
     /** Whether the value is optional — pass an explicit boolean to opt into the note: `false` appends `Required.` (when there's no default), `true` appends nothing. Leave `undefined` to suppress the note entirely (e.g. for returns/throws). */
     readonly optional?: boolean | undefined;
+    /** Whether the value is read-only — appends a trailing `Readonly` note at the very end (after any `Defaults to …` / `Required.`). */
+    readonly readonly?: boolean | undefined;
 }
 /**
  * Render a documentation table row's description cell.
- * - The description is parsed as inline markup (`context="inline"`), so backticks, emphasis and links resolve rather than showing as literal source.
- * - When a `default` is given it renders a trailing `Defaults to …` note on the same line (linking the value when it's a documented token); otherwise, when `optional` is explicitly `false`, it renders `Required.` for clarity.
+ * - The description is parsed as inline markup via `TreeMarkup` (`context="inline"`), so backticks, emphasis and links resolve rather than showing as literal source — and each inline-code span auto-links to its documented token when one exists.
+ * - When a `default` is given it renders a trailing `Defaults to …` note on the same line (linking the value when it's a documented token); otherwise, when `optional` is explicitly `false`, it renders a `required` `<Tag>`. (Optionality has no tag — it's implicit, and an optional value usually carries the longer `Defaults to …` text instead.)
+ * - When `readonly` is set, a `readonly` `<Tag>` is appended at the very end (after any default/required note).
  * - Wrapped in `<Prose>` so markup-produced `<code>` (and other inline) elements pick up the standard prose typography (the chip background, etc.) — a bare `<code>` is only styled inside a `.prose` ancestor.
  *
  * @kind component
- * @returns The description and any trailing note wrapped in a `<Prose>`, or `null` when both are empty.
- * @example <DocumentationDescription description="The `foo` value." optional={false} />
+ * @returns The description and any trailing notes wrapped in a `<Prose>`, or `null` when all are empty.
+ * @example <DocumentationDescription description="The `foo` value." optional={false} readonly />
  * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationDescription/DocumentationDescription
  */
-export declare function DocumentationDescription({ description, default: def, optional }: DocumentationDescriptionProps): ReactNode;
+export declare function DocumentationDescription({ description, default: def, optional, readonly }: DocumentationDescriptionProps): ReactNode;

package/ui/docs/DocumentationDescription.js

@@ -1,22 +1,24 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Prose } from "../block/Prose.js";
-import { Markup } from "../misc/Markup.js";
+import { Tag } from "../misc/Tag.js";
 import { TreeLink } from "../tree/TreeLink.js";
+import { TreeMarkup } from "../tree/TreeMarkup.js";
 /**
  * Render a documentation table row's description cell.
- * - The description is parsed as inline markup (`context="inline"`), so backticks, emphasis and links resolve rather than showing as literal source.
- * - When a `default` is given it renders a trailing `Defaults to …` note on the same line (linking the value when it's a documented token); otherwise, when `optional` is explicitly `false`, it renders `Required.` for clarity.
+ * - The description is parsed as inline markup via `TreeMarkup` (`context="inline"`), so backticks, emphasis and links resolve rather than showing as literal source — and each inline-code span auto-links to its documented token when one exists.
+ * - When a `default` is given it renders a trailing `Defaults to …` note on the same line (linking the value when it's a documented token); otherwise, when `optional` is explicitly `false`, it renders a `required` `<Tag>`. (Optionality has no tag — it's implicit, and an optional value usually carries the longer `Defaults to …` text instead.)
+ * - When `readonly` is set, a `readonly` `<Tag>` is appended at the very end (after any default/required note).
  * - Wrapped in `<Prose>` so markup-produced `<code>` (and other inline) elements pick up the standard prose typography (the chip background, etc.) — a bare `<code>` is only styled inside a `.prose` ancestor.
  *
  * @kind component
- * @returns The description and any trailing note wrapped in a `<Prose>`, or `null` when both are empty.
- * @example <DocumentationDescription description="The `foo` value." optional={false} />
+ * @returns The description and any trailing notes wrapped in a `<Prose>`, or `null` when all are empty.
+ * @example <DocumentationDescription description="The `foo` value." optional={false} readonly />
  * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationDescription/DocumentationDescription
  */
-export function DocumentationDescription({ description, default: def, optional }) {
-    const body = description ? _jsx(Markup, { context: "inline", children: description }) : null;
-    const note = def ? (_jsxs(_Fragment, { children: ["Defaults to ", _jsx(TreeLink, { name: def })] })) : optional === false ? (_jsx(_Fragment, { children: "Required." })) : null;
-    if (!body && !note)
+export function DocumentationDescription({ description, default: def, optional, readonly }) {
+    const body = description ? _jsx(TreeMarkup, { context: "inline", children: description }) : null;
+    const requirement = def ? (_jsxs(_Fragment, { children: ["Defaults to ", _jsx(TreeLink, { name: def })] })) : optional === false ? (_jsx(Tag, { children: "required" })) : null;
+    if (!body && !requirement && !readonly)
         return null;
-    return (_jsxs(Prose, { children: [body, body && note ? " " : null, note] }));
+    return (_jsxs(Prose, { children: [body, requirement ? (_jsxs(_Fragment, { children: [body ? " " : null, requirement] })) : null, readonly ? (_jsxs(_Fragment, { children: [body || requirement ? " " : null, _jsx(Tag, { children: "readonly" })] })) : null] }));
 }

package/ui/docs/DocumentationDescription.tsx

@@ -1,7 +1,8 @@
 import type { ReactNode } from "react";
 import { Prose } from "../block/Prose.js";
-import { Markup } from "../misc/Markup.js";
+import { Tag } from "../misc/Tag.js";
 import { TreeLink } from "../tree/TreeLink.js";
+import { TreeMarkup } from "../tree/TreeMarkup.js";
 
 /**
  * Props for `DocumentationDescription` — a description cell's resolved text, plus an optional default/optionality note.
@@ -15,34 +16,47 @@ export interface DocumentationDescriptionProps {
 	readonly default?: string | undefined;
 	/** Whether the value is optional — pass an explicit boolean to opt into the note: `false` appends `Required.` (when there's no default), `true` appends nothing. Leave `undefined` to suppress the note entirely (e.g. for returns/throws). */
 	readonly optional?: boolean | undefined;
+	/** Whether the value is read-only — appends a trailing `Readonly` note at the very end (after any `Defaults to …` / `Required.`). */
+	readonly readonly?: boolean | undefined;
 }
 
 /**
  * Render a documentation table row's description cell.
- * - The description is parsed as inline markup (`context="inline"`), so backticks, emphasis and links resolve rather than showing as literal source.
- * - When a `default` is given it renders a trailing `Defaults to …` note on the same line (linking the value when it's a documented token); otherwise, when `optional` is explicitly `false`, it renders `Required.` for clarity.
+ * - The description is parsed as inline markup via `TreeMarkup` (`context="inline"`), so backticks, emphasis and links resolve rather than showing as literal source — and each inline-code span auto-links to its documented token when one exists.
+ * - When a `default` is given it renders a trailing `Defaults to …` note on the same line (linking the value when it's a documented token); otherwise, when `optional` is explicitly `false`, it renders a `required` `<Tag>`. (Optionality has no tag — it's implicit, and an optional value usually carries the longer `Defaults to …` text instead.)
+ * - When `readonly` is set, a `readonly` `<Tag>` is appended at the very end (after any default/required note).
  * - Wrapped in `<Prose>` so markup-produced `<code>` (and other inline) elements pick up the standard prose typography (the chip background, etc.) — a bare `<code>` is only styled inside a `.prose` ancestor.
  *
  * @kind component
- * @returns The description and any trailing note wrapped in a `<Prose>`, or `null` when both are empty.
- * @example <DocumentationDescription description="The `foo` value." optional={false} />
+ * @returns The description and any trailing notes wrapped in a `<Prose>`, or `null` when all are empty.
+ * @example <DocumentationDescription description="The `foo` value." optional={false} readonly />
  * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationDescription/DocumentationDescription
  */
-export function DocumentationDescription({ description, default: def, optional }: DocumentationDescriptionProps): ReactNode {
-	const body = description ? <Markup context="inline">{description}</Markup> : null;
-	const note = def ? (
+export function DocumentationDescription({ description, default: def, optional, readonly }: DocumentationDescriptionProps): ReactNode {
+	const body = description ? <TreeMarkup context="inline">{description}</TreeMarkup> : null;
+	const requirement = def ? (
 		<>
 			Defaults to <TreeLink name={def} />
 		</>
 	) : optional === false ? (
-		<>Required.</>
+		<Tag>required</Tag>
 	) : null;
-	if (!body && !note) return null;
+	if (!body && !requirement && !readonly) return null;
 	return (
 		<Prose>
 			{body}
-			{body && note ? " " : null}
-			{note}
+			{requirement ? (
+				<>
+					{body ? " " : null}
+					{requirement}
+				</>
+			) : null}
+			{readonly ? (
+				<>
+					{body || requirement ? " " : null}
+					<Tag>readonly</Tag>
+				</>
+			) : null}
 		</Prose>
 	);
 }

package/ui/docs/DocumentationPage.d.ts

@@ -2,11 +2,11 @@ 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, 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`. A parameter/property default renders as a `Defaults to …` line at the foot of its description cell (linking the value when it's a documented token) rather than in a dedicated column.
- * - An options-bag parameter whose type resolves to a documented interface/object type is flattened into indented child rows (one per property), so readers see the individual fields inline.
+ * - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, properties, referenced types, and examples.
+ * - In the Parameters / Returns / Throws / Properties 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`. A default renders as a `Defaults to …` note (linking the value when it's a documented token) rather than in a dedicated column.
+ * - A class/interface/object-literal type's data members render as the Properties table (see `DocumentationProperties`); an options-bag parameter whose type resolves to one is flattened into indented child rows from the same structured list.
  * - 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.
+ * - Child symbols (functions, classes, methods — not data members) are grouped by `kind` into card sections, each under its own heading.
  * - All sections are conditional — only render when they have entries.
  *
  * @kind component
@@ -14,4 +14,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, types, examples, children, ...props }: DocumentationElementProps): ReactNode;
+export declare function DocumentationPage({ title, name, kind, description, content, signatures, params, returns, throws, properties, types, examples, children, ...props }: DocumentationElementProps): ReactNode;

package/ui/docs/DocumentationPage.js

@@ -15,11 +15,12 @@ import { TreeMarkup } from "../tree/TreeMarkup.js";
 import { DocumentationButtons } from "./DocumentationButtons.js";
 import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKind.js";
 import { DocumentationParams } from "./DocumentationParams.js";
+import { DocumentationProperties } from "./DocumentationProperties.js";
 import { DocumentationReferences } from "./DocumentationReferences.js";
 import { DocumentationReturns } from "./DocumentationReturns.js";
 import { DocumentationSignatures } from "./DocumentationSignatures.js";
 import { DocumentationThrows } from "./DocumentationThrows.js";
-/** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. */
+/** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. Data members (properties) are not child elements — they render as the Properties table instead. */
 const KIND_SECTIONS = {
     component: "Components",
     function: "Functions",
@@ -28,9 +29,7 @@ const KIND_SECTIONS = {
     type: "Types",
     constant: "Constants",
     "static method": "Static methods",
-    "static property": "Static properties",
     method: "Methods",
-    property: "Properties",
 };
 /** Render a list of tree elements grouped into kind-based card sections, in `KIND_SECTIONS` order. */
 function _renderSections(elements) {
@@ -57,11 +56,11 @@ 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, 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`. A parameter/property default renders as a `Defaults to …` line at the foot of its description cell (linking the value when it's a documented token) rather than in a dedicated column.
- * - An options-bag parameter whose type resolves to a documented interface/object type is flattened into indented child rows (one per property), so readers see the individual fields inline.
+ * - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, properties, referenced types, and examples.
+ * - In the Parameters / Returns / Throws / Properties 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`. A default renders as a `Defaults to …` note (linking the value when it's a documented token) rather than in a dedicated column.
+ * - A class/interface/object-literal type's data members render as the Properties table (see `DocumentationProperties`); an options-bag parameter whose type resolves to one is flattened into indented child rows from the same structured list.
  * - 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.
+ * - Child symbols (functions, classes, methods — not data members) are grouped by `kind` into card sections, each under its own heading.
  * - All sections are conditional — only render when they have entries.
  *
  * @kind component
@@ -69,6 +68,6 @@ 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, types, 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 || types?.length ? (_jsxs(Section, { children: [_jsx(DocumentationSignatures, { signatures: signatures }), _jsx(DocumentationParams, { params: params }), _jsx(DocumentationReturns, { returns: returns }), _jsx(DocumentationThrows, { throws: throws }), _jsx(DocumentationReferences, { types: types })] })) : null, content && (_jsx(Section, { children: _jsx(Prose, { children: _jsx(TreeMarkup, { 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, properties, types, 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 || properties?.length || types?.length ? (_jsxs(Section, { children: [_jsx(DocumentationSignatures, { signatures: signatures }), _jsx(DocumentationParams, { params: params }), _jsx(DocumentationReturns, { returns: returns }), _jsx(DocumentationThrows, { throws: throws }), _jsx(DocumentationProperties, { properties: properties }), _jsx(DocumentationReferences, { types: types })] })) : null, content && (_jsx(Section, { children: _jsx(Prose, { children: _jsx(TreeMarkup, { 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.test.tsx

@@ -32,16 +32,45 @@ describe("DocumentationPage", () => {
 	test("renders a section only for kinds that have children", () => {
 		const html = render(
 			<DocumentationPage path="/Store" name="Store" kind="class">
-				{[doc("get", "method"), doc("size", "property")]}
+				{[doc("get", "method")]}
 			</DocumentationPage>,
 			"./Store",
 		);
 		expect(html).toContain("Methods");
-		expect(html).toContain("Properties");
 		expect(html).not.toContain("Functions");
 		expect(html).not.toContain("Interfaces");
 	});
 
+	test("renders properties as a table with dot-prefixed names, dropping `| undefined` as optional", () => {
+		const html = render(
+			<DocumentationPage
+				path="/Opts"
+				name="Opts"
+				kind="interface"
+				properties={[
+					{ name: "caller", type: "AnyCaller | undefined", description: "The caller." },
+					{ name: "id", type: "string", description: "The id." },
+					{ name: "timeout", type: "number", description: "The timeout.", default: "20000" },
+					{ name: "size", type: "number", description: "The size.", readonly: true },
+				]}
+			/>,
+			"./Opts",
+		);
+		// Dedicated Properties table with dot-prefixed names.
+		expect(html).toContain(">Property</th>");
+		expect(html).toContain(">.caller</code>");
+		expect(html).toContain(">.timeout</code>");
+		// `| undefined` is dropped from the type and marks the property optional (no `Required.`).
+		expect(html).toContain(">AnyCaller</code>");
+		expect(html).not.toContain(">undefined</code>");
+		// A property with no default and no optionality gets a `required` tag; one with a default surfaces `Defaults to …`.
+		expect(html).toContain(">required</span>");
+		expect(html).toContain("Defaults to");
+		expect(html).toContain("20000");
+		// A read-only property appends a `readonly` tag at the end of its description.
+		expect(html).toContain(">readonly</span>");
+	});
+
 	test("renders parameters as a table, folding any default into the description as a `Defaults to …` line", () => {
 		const html = render(
 			<DocumentationPage
@@ -60,10 +89,10 @@ describe("DocumentationPage", () => {
 		expect(html).toContain(">Param</th>");
 		expect(html).toContain(">Type</th>");
 		expect(html).not.toContain(">Default</th>");
-		// A param with a default surfaces it as a `Defaults to …` note in its description; a param with neither a default nor optionality is marked `Required.`.
+		// A param with a default surfaces it as a `Defaults to …` note in its description; a param with neither a default nor optionality gets a `required` tag.
 		expect(html).toContain("Defaults to");
 		expect(html).toContain("false");
-		expect(html).toContain("Required.");
+		expect(html).toContain(">required</span>");
 		// Returns table headers.
 		expect(html).toContain(">Return</th>");
 		expect(html).toContain("The new thing.");
@@ -110,19 +139,16 @@ describe("DocumentationPage", () => {
 		expect(html).not.toContain("`code`");
 	});
 
-	test("groups static members into their own sections, before instance sections", () => {
+	test("groups static methods into their own section, before instance methods", () => {
 		const html = render(
 			<DocumentationPage path="/Color" name="Color" kind="class">
-				{[doc("from", "static method"), doc("DEFAULT", "static property"), doc("toString", "method"), doc("red", "property")]}
+				{[doc("from", "static method"), doc("toString", "method")]}
 			</DocumentationPage>,
 			"./Color",
 		);
 		expect(html).toContain("Static methods");
-		expect(html).toContain("Static properties");
 		expect(html).toContain("Methods");
-		expect(html).toContain("Properties");
-		// Static sections render before their instance counterparts (the `Methods` / `Properties` headings use a capital, so they don't match inside `Static methods`).
+		// Static methods render before instance methods (the `Methods` heading uses a capital, so it doesn't match inside `Static methods`).
 		expect(html.indexOf("Static methods")).toBeLessThan(html.indexOf("Methods"));
-		expect(html.indexOf("Static properties")).toBeLessThan(html.indexOf("Properties"));
 	});
 });

package/ui/docs/DocumentationPage.tsx

@@ -16,12 +16,13 @@ import { TreeMarkup } from "../tree/TreeMarkup.js";
 import { DocumentationButtons } from "./DocumentationButtons.js";
 import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKind.js";
 import { DocumentationParams } from "./DocumentationParams.js";
+import { DocumentationProperties } from "./DocumentationProperties.js";
 import { DocumentationReferences } from "./DocumentationReferences.js";
 import { DocumentationReturns } from "./DocumentationReturns.js";
 import { DocumentationSignatures } from "./DocumentationSignatures.js";
 import { DocumentationThrows } from "./DocumentationThrows.js";
 
-/** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. */
+/** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. Data members (properties) are not child elements — they render as the Properties table instead. */
 const KIND_SECTIONS = {
 	component: "Components",
 	function: "Functions",
@@ -30,9 +31,7 @@ const KIND_SECTIONS = {
 	type: "Types",
 	constant: "Constants",
 	"static method": "Static methods",
-	"static property": "Static properties",
 	method: "Methods",
-	property: "Properties",
 };
 
 /** Render a list of tree elements grouped into kind-based card sections, in `KIND_SECTIONS` order. */
@@ -68,11 +67,11 @@ 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, 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`. A parameter/property default renders as a `Defaults to …` line at the foot of its description cell (linking the value when it's a documented token) rather than in a dedicated column.
- * - An options-bag parameter whose type resolves to a documented interface/object type is flattened into indented child rows (one per property), so readers see the individual fields inline.
+ * - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, properties, referenced types, and examples.
+ * - In the Parameters / Returns / Throws / Properties 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`. A default renders as a `Defaults to …` note (linking the value when it's a documented token) rather than in a dedicated column.
+ * - A class/interface/object-literal type's data members render as the Properties table (see `DocumentationProperties`); an options-bag parameter whose type resolves to one is flattened into indented child rows from the same structured list.
  * - 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.
+ * - Child symbols (functions, classes, methods — not data members) are grouped by `kind` into card sections, each under its own heading.
  * - All sections are conditional — only render when they have entries.
  *
  * @kind component
@@ -90,6 +89,7 @@ export function DocumentationPage({
 	params,
 	returns,
 	throws,
+	properties,
 	types,
 	examples,
 	children,
@@ -110,12 +110,13 @@ export function DocumentationPage({
 						<DocumentationButtons {...props} />
 					</Header>
 				</Panel>
-				{signatures?.length || params?.length || returns?.length || throws?.length || types?.length ? (
+				{signatures?.length || params?.length || returns?.length || throws?.length || properties?.length || types?.length ? (
 					<Section>
 						<DocumentationSignatures signatures={signatures} />
 						<DocumentationParams params={params} />
 						<DocumentationReturns returns={returns} />
 						<DocumentationThrows throws={throws} />
+						<DocumentationProperties properties={properties} />
 						<DocumentationReferences types={types} />
 					</Section>
 				) : null}