shelving 1.217.0 → 1.218.0

package/package.json

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

package/ui/docs/DocumentationPage.d.ts

@@ -1,8 +1,9 @@
 import type { ReactNode } from "react";
-import type { DocumentationElementProps } from "../../util/element.js";
+import { type DocumentationElementProps } from "../../util/element.js";
 /**
- * Page renderer for a `tree-documentation` element.
- * - Renders title, signatures (one per overload), content, parameters, returns, throws, examples, and child symbols.
- * - All sections are conditional — only render when their array has entries.
+ * Page renderer for a `tree-documentation` element (also used for `tree-file` elements, whose props are a compatible subset).
+ * - Renders title, signatures (one per overload), content, parameters, returns, throws, and examples.
+ * - 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.
  */
 export declare function DocumentationPage({ title, name, kind, description, content, signatures, params, returns, throws, examples, children, }: DocumentationElementProps): ReactNode;

package/ui/docs/DocumentationPage.js

@@ -1,4 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { queryElements } from "../../util/element.js";
 import { Definition, Definitions } from "../block/Definitions.js";
 import { Flex } from "../block/Flex.js";
 import { Heading } from "../block/Heading.js";
@@ -13,13 +14,28 @@ import { Page } from "../page/Page.js";
 import { TreeCards } from "../tree/TreeCards.js";
 import { DocumentationKind } from "./DocumentationKind.js";
 const DEFAULT_TYPE = "unknown";
+/** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. */
+const KIND_SECTIONS = [
+    ["function", "Functions"],
+    ["class", "Classes"],
+    ["interface", "Interfaces"],
+    ["type", "Types"],
+    ["constant", "Constants"],
+    ["method", "Methods"],
+    ["property", "Properties"],
+];
 /**
- * Page renderer for a `tree-documentation` element.
- * - Renders title, signatures (one per overload), content, parameters, returns, throws, examples, and child symbols.
- * - All sections are conditional — only render when their array has entries.
+ * Page renderer for a `tree-documentation` element (also used for `tree-file` elements, whose props are a compatible subset).
+ * - Renders title, signatures (one per overload), content, parameters, returns, throws, and examples.
+ * - 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.
  */
 export function DocumentationPage({ title, name, kind, description, content, signatures, params, returns, throws, examples, children, }) {
     const { url } = requireMeta();
     const path = (url?.pathname ?? "/");
-    return (_jsxs(Page, { title: title ?? name, description: description, children: [_jsx(Title, { children: _jsxs(Flex, { left: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind })] }) }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), params?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Parameters" }), _jsx(Definitions, { row: true, children: params.map(({ name, type = DEFAULT_TYPE, description = "", optional }) => (_jsx(Definition, { term: _jsxs(_Fragment, { children: [_jsx(Code, { children: name }), ": ", _jsx(Code, { children: type }), optional && _jsx(_Fragment, { children: " (optional)" })] }), children: description }, `${name}-${type}-${description}`))) })] })), returns?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Returns" }), _jsx(Definitions, { row: true, children: returns.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), throws?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Throws" }), _jsx(Definitions, { row: true, children: throws.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), examples?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), _jsx(TreeCards, { path: path, children: children })] }));
+    return (_jsxs(Page, { title: title ?? name, description: description, children: [_jsx(Title, { children: _jsxs(Flex, { left: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind })] }) }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), params?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Parameters" }), _jsx(Definitions, { row: true, children: params.map(({ name, type = DEFAULT_TYPE, description = "", optional }) => (_jsx(Definition, { term: _jsxs(_Fragment, { children: [_jsx(Code, { children: name }), ": ", _jsx(Code, { children: type }), optional && _jsx(_Fragment, { children: " (optional)" })] }), children: description }, `${name}-${type}-${description}`))) })] })), returns?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Returns" }), _jsx(Definitions, { row: true, children: returns.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), throws?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Throws" }), _jsx(Definitions, { row: true, children: throws.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), examples?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), KIND_SECTIONS.map(([kind, label]) => {
+                // Pre-filter the children for this kind; only render the section when it has cards.
+                const group = Array.from(queryElements(children, { "props.kind": kind }));
+                return group.length ? (_jsxs(Section, { children: [_jsx(Heading, { children: label }), _jsx(TreeCards, { path: path, children: group })] }, kind)) : null;
+            })] }));
 }

package/ui/docs/DocumentationPage.test.tsx

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import type { DocumentationElement } from "../../util/element.js";
+import { DocumentationPage } from "./DocumentationPage.js";
+
+/** Make a minimal `tree-documentation` child element of a given kind. */
+function doc(name: string, kind: string): DocumentationElement {
+	return { type: "tree-documentation", key: name, props: { name, kind } };
+}
+
+describe("DocumentationPage", () => {
+	test("groups child symbols into kind-based sections, in order", () => {
+		const html = renderToStaticMarkup(
+			<DocumentationPage name="array">
+				{[doc("getThing", "function"), doc("Widget", "class"), doc("getOther", "function")]}
+			</DocumentationPage>,
+		);
+		expect(html).toContain("Functions");
+		expect(html).toContain("Classes");
+		// Sections render in `KIND_SECTIONS` order — functions before classes.
+		expect(html.indexOf("Functions")).toBeLessThan(html.indexOf("Classes"));
+	});
+
+	test("renders a section only for kinds that have children", () => {
+		const html = renderToStaticMarkup(
+			<DocumentationPage name="Store" kind="class">
+				{[doc("get", "method"), doc("size", "property")]}
+			</DocumentationPage>,
+		);
+		expect(html).toContain("Methods");
+		expect(html).toContain("Properties");
+		expect(html).not.toContain("Functions");
+		expect(html).not.toContain("Interfaces");
+	});
+});

package/ui/docs/DocumentationPage.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
-import type { DocumentationElementProps } from "../../util/element.js";
+import { type DocumentationElementProps, type Element, queryElements, type TreeElement } from "../../util/element.js";
 import type { AbsolutePath } from "../../util/path.js";
+import type { Query } from "../../util/query.js";
 import { Definition, Definitions } from "../block/Definitions.js";
 import { Flex } from "../block/Flex.js";
 import { Heading } from "../block/Heading.js";
@@ -17,10 +18,22 @@ import { DocumentationKind } from "./DocumentationKind.js";
 
 const DEFAULT_TYPE = "unknown";
 
+/** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. */
+const KIND_SECTIONS: ReadonlyArray<readonly [kind: string, label: string]> = [
+	["function", "Functions"],
+	["class", "Classes"],
+	["interface", "Interfaces"],
+	["type", "Types"],
+	["constant", "Constants"],
+	["method", "Methods"],
+	["property", "Properties"],
+];
+
 /**
- * Page renderer for a `tree-documentation` element.
- * - Renders title, signatures (one per overload), content, parameters, returns, throws, examples, and child symbols.
- * - All sections are conditional — only render when their array has entries.
+ * Page renderer for a `tree-documentation` element (also used for `tree-file` elements, whose props are a compatible subset).
+ * - Renders title, signatures (one per overload), content, parameters, returns, throws, and examples.
+ * - 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.
  */
 export function DocumentationPage({
 	title,
@@ -105,7 +118,16 @@ export function DocumentationPage({
 					))}
 				</Section>
 			)}
-			<TreeCards path={path}>{children}</TreeCards>
+			{KIND_SECTIONS.map(([kind, label]) => {
+				// Pre-filter the children for this kind; only render the section when it has cards.
+				const group = Array.from(queryElements(children, { "props.kind": kind } as Query<Element>)) as TreeElement[];
+				return group.length ? (
+					<Section key={kind}>
+						<Heading>{label}</Heading>
+						<TreeCards path={path}>{group}</TreeCards>
+					</Section>
+				) : null;
+			})}
 		</Page>
 	);
 }