shelving 1.255.1 → 1.256.1

package/README.md

@@ -1,6 +1,6 @@
 # Shelving
 
-[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) [![Release](https://github.com/dhoulb/shelving/actions/workflows/release.yaml/badge.svg)](https://github.com/dhoulb/shelving/actions/workflows/release.yaml) [![npm](https://img.shields.io/npm/dm/shelving.svg)](https://www.npmjs.com/package/shelving)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://www.conventionalcommits.org/) [![Release](https://github.com/dhoulb/shelving/actions/workflows/release.yaml/badge.svg)](https://github.com/dhoulb/shelving/actions/workflows/release.yaml) [![npm](https://img.shields.io/npm/dm/shelving.svg)](https://www.npmjs.com/package/shelving)
 
 TypeScript data toolkit — schema validation, database and API providers, observable state stores, React integration, and typed utility functions.
 

package/package.json

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

package/ui/block/Block.d.ts

@@ -1,6 +1,7 @@
 import type { ReactElement } from "react";
 import { type ColorVariants } from "../style/Color.js";
 import { type IndentVariants } from "../style/Indent.js";
+import { type PaddingVariants } from "../style/Padding.js";
 import { type SpaceVariants } from "../style/Space.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import { type WidthVariants } from "../style/Width.js";
@@ -16,7 +17,7 @@ export type BlockElement = "div" | "section" | "header" | "footer" | "article" |
  *
  * @see https://shelving.cc/ui/BlockProps
  */
-export interface BlockProps extends ColorVariants, IndentVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
+export interface BlockProps extends ColorVariants, PaddingVariants, IndentVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
     /**
      * Element this `<Block>` renders as, e.g. "header" to output a "<header>"
      * @default "div"

package/ui/block/Block.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { getColorClass } from "../style/Color.js";
 import { getIndentClass } from "../style/Indent.js";
+import { getPaddingClass } from "../style/Padding.js";
 import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getWidthClass } from "../style/Width.js";
@@ -19,7 +20,7 @@ const BLOCK_CLASS = getModuleClass(BLOCK_CSS, "block");
  */
 export function getBlockClass(variants) {
     return getClass(BLOCK_CLASS, //
-    getColorClass(variants), getIndentClass(variants), getSpaceClass(variants), getTypographyClass(variants), getWidthClass(variants));
+    getColorClass(variants), getIndentClass(variants), getPaddingClass(variants), getSpaceClass(variants), getTypographyClass(variants), getWidthClass(variants));
 }
 /**
  * Plain `<div>` block with block-level spacing.

package/ui/block/Block.module.css

@@ -14,3 +14,14 @@
 		margin-block: 0;
 	}
 }
+
+@layer overrides {
+	.block {
+		&:first-child {
+			margin-block-start: 0;
+		}
+		&:last-child {
+			margin-block-end: 0;
+		}
+	}
+}

package/ui/block/Block.tsx

@@ -1,6 +1,7 @@
 import type { ReactElement } from "react";
 import { type ColorVariants, getColorClass } from "../style/Color.js";
 import { getIndentClass, type IndentVariants } from "../style/Indent.js";
+import { getPaddingClass, type PaddingVariants } from "../style/Padding.js";
 import { getSpaceClass, type SpaceVariants } from "../style/Space.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
 import { getWidthClass, type WidthVariants } from "../style/Width.js";
@@ -22,7 +23,14 @@ export type BlockElement = "div" | "section" | "header" | "footer" | "article" |
  *
  * @see https://shelving.cc/ui/BlockProps
  */
-export interface BlockProps extends ColorVariants, IndentVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
+export interface BlockProps
+	extends ColorVariants,
+		PaddingVariants,
+		IndentVariants,
+		SpaceVariants,
+		TypographyVariants,
+		WidthVariants,
+		OptionalChildProps {
 	/**
 	 * Element this `<Block>` renders as, e.g. "header" to output a "<header>"
 	 * @default "div"
@@ -45,6 +53,7 @@ export function getBlockClass(variants: BlockProps): string {
 		BLOCK_CLASS, //
 		getColorClass(variants),
 		getIndentClass(variants),
+		getPaddingClass(variants),
 		getSpaceClass(variants),
 		getTypographyClass(variants),
 		getWidthClass(variants),

package/ui/block/Panel.module.css

@@ -28,6 +28,7 @@
 		inline-size: 100%;
 		margin-inline: 0;
 		margin-block: 0;
+		padding-block: var(--panel-padding, var(--space-section));
 		padding-inline: var(--panel-indent, var(--space-normal));
 		border-top: var(--panel-border, var(--panel-stroke, var(--stroke-normal)) solid var(--tint-80));
 		border-bottom: var(--panel-border, var(--panel-stroke, var(--stroke-normal)) solid var(--tint-80));

package/ui/block/Section.module.css

@@ -18,3 +18,15 @@
 		margin-block: var(--section-space, var(--space-section));
 	}
 }
+
+@layer overrides {
+	.prose :where(section, article, aside, nav, header, footer, figure),
+	.section {
+		&:first-child {
+			margin-block-start: 0;
+		}
+		&:last-child {
+			margin-block-end: 0;
+		}
+	}
+}

package/ui/docs/DocumentationApp.d.ts

@@ -0,0 +1,7 @@
+import type { ReactElement } from "react";
+import { type TreeAppProps } from "../tree/TreeApp.js";
+/**
+ * Documentation app.
+ * - Build upon `<TreeApp>` to include a `<DocumentationSearchPage>` at its `/search` URL.
+ */
+export declare function DocumentationApp({ tree, routes, sidebar, ...meta }: TreeAppProps): ReactElement;

package/ui/docs/DocumentationApp.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Menu, MenuItem } from "../menu/Menu.js";
+import { TreeApp } from "../tree/TreeApp.js";
+import { TreeSidebar } from "../tree/TreeSidebar.js";
+import { DocumentationSearchPage } from "./DocumentationSearchPage.js";
+/**
+ * Documentation app.
+ * - Build upon `<TreeApp>` to include a `<DocumentationSearchPage>` at its `/search` URL.
+ */
+export function DocumentationApp({ tree, routes = {
+    "/search": DocumentationSearchPage,
+}, sidebar = (_jsx(TreeSidebar, { tree: tree, children: _jsx(Menu, { children: _jsx(MenuItem, { href: "/search", children: "Search" }) }) })), ...meta }) {
+    return _jsx(TreeApp, { tree: tree, routes: routes, sidebar: sidebar, ...meta });
+}

package/ui/docs/DocumentationApp.tsx

@@ -0,0 +1,26 @@
+import type { ReactElement } from "react";
+import { Menu, MenuItem } from "../menu/Menu.js";
+import { TreeApp, type TreeAppProps } from "../tree/TreeApp.js";
+import { TreeSidebar } from "../tree/TreeSidebar.js";
+import { DocumentationSearchPage } from "./DocumentationSearchPage.js";
+
+/**
+ * Documentation app.
+ * - Build upon `<TreeApp>` to include a `<DocumentationSearchPage>` at its `/search` URL.
+ */
+export function DocumentationApp({
+	tree,
+	routes = {
+		"/search": DocumentationSearchPage,
+	},
+	sidebar = (
+		<TreeSidebar tree={tree}>
+			<Menu>
+				<MenuItem href="/search">Search</MenuItem>
+			</Menu>
+		</TreeSidebar>
+	),
+	...meta
+}: TreeAppProps): ReactElement {
+	return <TreeApp tree={tree} routes={routes} sidebar={sidebar} {...meta} />;
+}

package/ui/docs/DocumentationPage.js

@@ -21,7 +21,8 @@ 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. Data members (properties) are not child elements — they render as the Properties table instead. */
-const KIND_SECTIONS = {
+const KINDS = {
+    module: "Modules",
     component: "Components",
     function: "Functions",
     class: "Classes",
@@ -31,29 +32,6 @@ const KIND_SECTIONS = {
     "static method": "Static methods",
     method: "Methods",
 };
-/** Render a list of tree elements grouped into kind-based card sections, in `KIND_SECTIONS` order. */
-function _renderSections(elements) {
-    return Object.entries(KIND_SECTIONS).map(([kind, label]) => {
-        const group = elements.filter(el => el.props.kind === kind);
-        return group.length ? (_jsxs(Section, { children: [_jsx(Heading, { children: label }), _jsx(TreeCards, { children: group })] }, kind)) : null;
-    });
-}
-/**
- * Children listing for a documentation page — this page's child symbols grouped into kind-based card sections.
- *
- * - Renders nothing when the page has no children (e.g. a leaf symbol).
- * - Cross-tree search and kind filtering live on the index page (`TreeIndexPage`), not here.
- *
- * @param props The page's child elements.
- * @returns The grouped card sections, or `null` when there are no children.
- */
-function DocumentationChildren({ elements }) {
-    const childElements = Array.from(walkElements(elements));
-    // No children → nothing to list.
-    if (!childElements.length)
-        return null;
-    return _renderSections(childElements);
-}
 /**
  * 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, properties, referenced types, and examples.
@@ -69,5 +47,11 @@ function DocumentationChildren({ elements }) {
  * @see https://shelving.cc/ui/DocumentationPage
  */
 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 })] }) }), _jsxs(Block, { indent: "normal", children: [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 })] })] }) }));
+    const elements = Array.from(walkElements(children));
+    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 })] }) }), _jsxs(Block, { indent: "normal", padding: "section", children: [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)))] })), elements.length
+                            ? Object.entries(KINDS).map(([kind, label]) => {
+                                const group = elements.filter(el => el.props.kind === kind);
+                                return group.length ? (_jsxs(Section, { children: [_jsx(Heading, { children: label }), _jsx(TreeCards, { children: group })] }, kind)) : null;
+                            })
+                            : null] })] }) }));
 }

package/ui/docs/DocumentationPage.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 import { walkElements } from "../../util/element.js";
-import type { DocumentationElementProps, TreeElement, TreeElements } from "../../util/tree.js";
+import type { DocumentationElementProps, TreeElement } from "../../util/tree.js";
 import { Block } from "../block/Block.js";
 import { Heading } from "../block/Heading.js";
 import { Panel } from "../block/Panel.js";
@@ -23,7 +23,8 @@ import { DocumentationSignatures } from "./DocumentationSignatures.js";
 import { DocumentationThrows } from "./DocumentationThrows.js";
 
 /** 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 = {
+const KINDS = {
+	module: "Modules",
 	component: "Components",
 	function: "Functions",
 	class: "Classes",
@@ -34,37 +35,6 @@ const KIND_SECTIONS = {
 	method: "Methods",
 };
 
-/** Render a list of tree elements grouped into kind-based card sections, in `KIND_SECTIONS` order. */
-function _renderSections(elements: readonly TreeElement[]): ReactNode {
-	return Object.entries(KIND_SECTIONS).map(([kind, label]) => {
-		const group = elements.filter(el => (el.props as DocumentationElementProps).kind === kind);
-		return group.length ? (
-			<Section key={kind}>
-				<Heading>{label}</Heading>
-				<TreeCards>{group}</TreeCards>
-			</Section>
-		) : null;
-	});
-}
-
-/**
- * Children listing for a documentation page — this page's child symbols grouped into kind-based card sections.
- *
- * - Renders nothing when the page has no children (e.g. a leaf symbol).
- * - Cross-tree search and kind filtering live on the index page (`TreeIndexPage`), not here.
- *
- * @param props The page's child elements.
- * @returns The grouped card sections, or `null` when there are no children.
- */
-function DocumentationChildren({ elements }: { readonly elements?: TreeElements }): ReactNode {
-	const childElements = Array.from(walkElements<TreeElement>(elements));
-
-	// No children → nothing to list.
-	if (!childElements.length) return null;
-
-	return _renderSections(childElements);
-}
-
 /**
  * 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, properties, referenced types, and examples.
@@ -95,6 +65,7 @@ export function DocumentationPage({
 	children,
 	...props
 }: DocumentationElementProps): ReactNode {
+	const elements = Array.from(walkElements<TreeElement>(children));
 	return (
 		<Page title={title ?? name} description={description}>
 			<Block color={getDocumentationKindColor(kind)}>
@@ -110,7 +81,7 @@ export function DocumentationPage({
 						<DocumentationButtons {...props} />
 					</Header>
 				</Panel>
-				<Block indent="normal">
+				<Block indent="normal" padding="section">
 					{signatures?.length || params?.length || returns?.length || throws?.length || properties?.length || types?.length ? (
 						<Section>
 							<DocumentationSignatures signatures={signatures} />
@@ -136,7 +107,17 @@ export function DocumentationPage({
 							))}
 						</Section>
 					)}
-					<DocumentationChildren elements={children} />
+					{elements.length
+						? Object.entries(KINDS).map(([kind, label]) => {
+								const group = elements.filter(el => (el.props as DocumentationElementProps).kind === kind);
+								return group.length ? (
+									<Section key={kind}>
+										<Heading>{label}</Heading>
+										<TreeCards>{group}</TreeCards>
+									</Section>
+								) : null;
+							})
+						: null}
 				</Block>
 			</Block>
 		</Page>

package/ui/{tree/TreeIndexPage.d.ts → docs/DocumentationSearchPage.d.ts}

@@ -1,7 +1,4 @@
 import { type ReactNode } from "react";
-import type { AbsolutePath } from "../../util/path.js";
-/** Canonical URL path of the `TreeIndexPage`, wired as a `<TreeApp>` fallback route. */
-export declare const TREE_INDEX_PATH: AbsolutePath;
 /**
  * Page listing every element in the system in one flat, searchable view.
  *
@@ -9,11 +6,10 @@ export declare const TREE_INDEX_PATH: AbsolutePath;
  * - The kind checkboxes are multi-select — ticking several narrows to a `kind IN […]` filter; ticking none shows every kind.
  * - An empty query lists everything (capped at 100); a non-empty query ranks with `searchTree` and caps at 20.
  * - Reads the whole tree from the surrounding `<TreeProvider>` (the flattened map's root), so it works on every page.
- * - Wired as a `<TreeApp>` fallback route at `TREE_INDEX_PATH` (`/all`) — it's not a node in the tree.
  *
  * @kind component
  * @returns A `<Page>` with a search input, kind checkboxes, and a flat card listing of results.
- * @example <Router routes={{ [TREE_INDEX_PATH]: TreeIndexPage }} />
- * @see https://shelving.cc/ui/TreeIndexPage
+ * @example <Router routes={{ search: DocumentationSearchPage }} />
+ * @see https://shelving.cc/ui/DocumentationSearchPage
  */
-export declare function TreeIndexPage(): ReactNode;
+export declare function DocumentationSearchPage(): ReactNode;

package/ui/{tree/TreeIndexPage.js → docs/DocumentationSearchPage.js}

@@ -3,23 +3,20 @@ import { useMemo, useState } from "react";
 import { toggleArrayItem } from "../../util/array.js";
 import { searchTree } from "../../util/tree.js";
 import { Block } from "../block/Block.js";
+import { Panel } from "../block/Panel.js";
 import { Header, Section } from "../block/Section.js";
 import { Title } from "../block/Title.js";
-import { DocumentationKind } from "../docs/DocumentationKind.js";
 import { CheckboxInput } from "../form/CheckboxInput.js";
 import { TextInput } from "../form/TextInput.js";
 import { Page } from "../page/Page.js";
 import { Row } from "../style/Flex.js";
-import { TreeCards } from "./TreeCards.js";
-import { useTreeMap } from "./TreeContext.js";
-/** Canonical URL path of the `TreeIndexPage`, wired as a `<TreeApp>` fallback route. */
-export const TREE_INDEX_PATH = "/all";
+import { TreeCards } from "../tree/TreeCards.js";
+import { useTreeMap } from "../tree/TreeContext.js";
+import { DocumentationKind } from "./DocumentationKind.js";
 /** Title shown for the index page. */
-const INDEX_TITLE = "All elements";
-/** Description shown for the index page (page `<meta>` description). */
-const INDEX_DESCRIPTION = "Search every documented element in the system.";
+const TITLE = "Search...";
 /** Kinds offered as filter chips, in display order — mirrors `DocumentationPage`'s sections. */
-const INDEX_KINDS = ["component", "function", "class", "interface", "type", "constant", "method", "property"];
+const KINDS = ["module", "component", "function", "class", "interface", "type", "constant", "method", "property"];
 /** Cap on the flat listing when there's no query — keeps "show everything" sane. */
 const INDEX_LIMIT = 100;
 /**
@@ -29,14 +26,13 @@ const INDEX_LIMIT = 100;
  * - The kind checkboxes are multi-select — ticking several narrows to a `kind IN […]` filter; ticking none shows every kind.
  * - An empty query lists everything (capped at 100); a non-empty query ranks with `searchTree` and caps at 20.
  * - Reads the whole tree from the surrounding `<TreeProvider>` (the flattened map's root), so it works on every page.
- * - Wired as a `<TreeApp>` fallback route at `TREE_INDEX_PATH` (`/all`) — it's not a node in the tree.
  *
  * @kind component
  * @returns A `<Page>` with a search input, kind checkboxes, and a flat card listing of results.
- * @example <Router routes={{ [TREE_INDEX_PATH]: TreeIndexPage }} />
- * @see https://shelving.cc/ui/TreeIndexPage
+ * @example <Router routes={{ search: DocumentationSearchPage }} />
+ * @see https://shelving.cc/ui/DocumentationSearchPage
  */
-export function TreeIndexPage() {
+export function DocumentationSearchPage() {
     const [query, setQuery] = useState("");
     const [selected, setSelected] = useState([]);
     const root = useTreeMap().get("/");
@@ -45,12 +41,12 @@ export function TreeIndexPage() {
         if (!root)
             return [];
         const all = searchTree(root, "", { limit: Number.POSITIVE_INFINITY });
-        return INDEX_KINDS.filter(kind => all.some(el => el.props.kind === kind));
+        return KINDS.filter(kind => all.some(el => el.props.kind === kind));
     }, [root]);
     const trimmed = query.trim();
     // Multiple kinds can be ticked at once — an array value decodes to a `kind IN […]` filter.
     const filter = selected.length ? { kind: selected } : undefined;
     // Each element's `key` is its unique canonical path (stamped by `flattenTree()`), so this flat cross-tree listing reconciles correctly.
     const cards = root ? searchTree(root, trimmed, { limit: trimmed ? 20 : INDEX_LIMIT, filter }) : [];
-    return (_jsx(Page, { title: INDEX_TITLE, description: INDEX_DESCRIPTION, children: _jsxs(Block, { indent: "normal", children: [_jsx(Header, { children: _jsx(Title, { children: INDEX_TITLE }) }), _jsxs(Section, { children: [_jsx(TextInput, { name: "search", title: "Search", placeholder: "Search\u2026", value: query, onValue: v => setQuery(v ?? "") }), !!kinds.length && (_jsx(Row, { left: true, wrap: true, children: kinds.map(kind => (_jsx(CheckboxInput, { name: kind, width: "fit", value: selected.includes(kind), onValue: () => setSelected(s => toggleArrayItem(s, kind)), children: _jsx(DocumentationKind, { kind: kind }) }, kind))) }))] }), _jsx(Section, { children: _jsx(TreeCards, { children: cards }) })] }) }));
+    return (_jsxs(Page, { title: TITLE, children: [_jsxs(Panel, { children: [_jsx(Header, { children: _jsx(Title, { center: true, children: TITLE }) }), _jsxs(Section, { children: [_jsx(TextInput, { name: "search", title: "Search", placeholder: "Search\u2026", value: query, onValue: v => setQuery(v ?? "") }), !!kinds.length && (_jsx(Row, { left: true, wrap: true, children: kinds.map(kind => (_jsx(CheckboxInput, { name: kind, width: "fit", value: selected.includes(kind), onValue: () => setSelected(s => toggleArrayItem(s, kind)), children: _jsx(DocumentationKind, { kind: kind }) }, kind))) }))] })] }), _jsx(Block, { indent: "normal", padding: "section", children: _jsx(Section, { children: _jsx(TreeCards, { children: cards }) }) })] }));
 }

package/ui/{tree/TreeIndexPage.tsx → docs/DocumentationSearchPage.tsx}

@@ -1,31 +1,25 @@
 import { type ReactNode, useMemo, useState } from "react";
 import { type ImmutableArray, toggleArrayItem } from "../../util/array.js";
-import type { AbsolutePath } from "../../util/path.js";
 import type { Query } from "../../util/query.js";
 import type { DocumentationElementProps } from "../../util/tree.js";
 import { searchTree } from "../../util/tree.js";
 import { Block } from "../block/Block.js";
+import { Panel } from "../block/Panel.js";
 import { Header, Section } from "../block/Section.js";
 import { Title } from "../block/Title.js";
-import { DocumentationKind } from "../docs/DocumentationKind.js";
 import { CheckboxInput } from "../form/CheckboxInput.js";
 import { TextInput } from "../form/TextInput.js";
 import { Page } from "../page/Page.js";
 import { Row } from "../style/Flex.js";
-import { TreeCards } from "./TreeCards.js";
-import { useTreeMap } from "./TreeContext.js";
-
-/** Canonical URL path of the `TreeIndexPage`, wired as a `<TreeApp>` fallback route. */
-export const TREE_INDEX_PATH = "/all" as AbsolutePath;
+import { TreeCards } from "../tree/TreeCards.js";
+import { useTreeMap } from "../tree/TreeContext.js";
+import { DocumentationKind } from "./DocumentationKind.js";
 
 /** Title shown for the index page. */
-const INDEX_TITLE = "All elements";
-
-/** Description shown for the index page (page `<meta>` description). */
-const INDEX_DESCRIPTION = "Search every documented element in the system.";
+const TITLE = "Search...";
 
 /** Kinds offered as filter chips, in display order — mirrors `DocumentationPage`'s sections. */
-const INDEX_KINDS = ["component", "function", "class", "interface", "type", "constant", "method", "property"];
+const KINDS = ["module", "component", "function", "class", "interface", "type", "constant", "method", "property"];
 
 /** Cap on the flat listing when there's no query — keeps "show everything" sane. */
 const INDEX_LIMIT = 100;
@@ -37,14 +31,13 @@ const INDEX_LIMIT = 100;
  * - The kind checkboxes are multi-select — ticking several narrows to a `kind IN […]` filter; ticking none shows every kind.
  * - An empty query lists everything (capped at 100); a non-empty query ranks with `searchTree` and caps at 20.
  * - Reads the whole tree from the surrounding `<TreeProvider>` (the flattened map's root), so it works on every page.
- * - Wired as a `<TreeApp>` fallback route at `TREE_INDEX_PATH` (`/all`) — it's not a node in the tree.
  *
  * @kind component
  * @returns A `<Page>` with a search input, kind checkboxes, and a flat card listing of results.
- * @example <Router routes={{ [TREE_INDEX_PATH]: TreeIndexPage }} />
- * @see https://shelving.cc/ui/TreeIndexPage
+ * @example <Router routes={{ search: DocumentationSearchPage }} />
+ * @see https://shelving.cc/ui/DocumentationSearchPage
  */
-export function TreeIndexPage(): ReactNode {
+export function DocumentationSearchPage(): ReactNode {
 	const [query, setQuery] = useState("");
 	const [selected, setSelected] = useState<ImmutableArray<string>>([]);
 
@@ -54,7 +47,7 @@ export function TreeIndexPage(): ReactNode {
 	const kinds = useMemo(() => {
 		if (!root) return [];
 		const all = searchTree(root, "", { limit: Number.POSITIVE_INFINITY });
-		return INDEX_KINDS.filter(kind => all.some(el => (el.props as DocumentationElementProps).kind === kind));
+		return KINDS.filter(kind => all.some(el => (el.props as DocumentationElementProps).kind === kind));
 	}, [root]);
 
 	const trimmed = query.trim();
@@ -64,10 +57,10 @@ export function TreeIndexPage(): ReactNode {
 	const cards = root ? searchTree(root, trimmed, { limit: trimmed ? 20 : INDEX_LIMIT, filter }) : [];
 
 	return (
-		<Page title={INDEX_TITLE} description={INDEX_DESCRIPTION}>
-			<Block indent="normal">
+		<Page title={TITLE}>
+			<Panel>
 				<Header>
-					<Title>{INDEX_TITLE}</Title>
+					<Title center>{TITLE}</Title>
 				</Header>
 				<Section>
 					<TextInput name="search" title="Search" placeholder="Search…" value={query} onValue={v => setQuery(v ?? "")} />
@@ -87,6 +80,8 @@ export function TreeIndexPage(): ReactNode {
 						</Row>
 					)}
 				</Section>
+			</Panel>
+			<Block indent="normal" padding="section">
 				<Section>
 					<TreeCards>{cards}</TreeCards>
 				</Section>

package/ui/docs/index.d.ts

@@ -1,13 +1,14 @@
+export * from "./DocumentationApp.js";
 export * from "./DocumentationButtons.js";
 export * from "./DocumentationCard.js";
 export * from "./DocumentationDescription.js";
-export * from "./DocumentationHomePage.js";
 export * from "./DocumentationKind.js";
 export * from "./DocumentationPage.js";
 export * from "./DocumentationParams.js";
 export * from "./DocumentationProperties.js";
 export * from "./DocumentationReferences.js";
 export * from "./DocumentationReturns.js";
+export * from "./DocumentationSearchPage.js";
 export * from "./DocumentationSignatures.js";
 export * from "./DocumentationThrows.js";
 export * from "./DocumentationType.js";

package/ui/docs/index.js

@@ -1,13 +1,14 @@
+export * from "./DocumentationApp.js";
 export * from "./DocumentationButtons.js";
 export * from "./DocumentationCard.js";
 export * from "./DocumentationDescription.js";
-export * from "./DocumentationHomePage.js";
 export * from "./DocumentationKind.js";
 export * from "./DocumentationPage.js";
 export * from "./DocumentationParams.js";
 export * from "./DocumentationProperties.js";
 export * from "./DocumentationReferences.js";
 export * from "./DocumentationReturns.js";
+export * from "./DocumentationSearchPage.js";
 export * from "./DocumentationSignatures.js";
 export * from "./DocumentationThrows.js";
 export * from "./DocumentationType.js";

package/ui/docs/index.ts

@@ -1,13 +1,14 @@
+export * from "./DocumentationApp.js";
 export * from "./DocumentationButtons.js";
 export * from "./DocumentationCard.js";
 export * from "./DocumentationDescription.js";
-export * from "./DocumentationHomePage.js";
 export * from "./DocumentationKind.js";
 export * from "./DocumentationPage.js";
 export * from "./DocumentationParams.js";
 export * from "./DocumentationProperties.js";
 export * from "./DocumentationReferences.js";
 export * from "./DocumentationReturns.js";
+export * from "./DocumentationSearchPage.js";
 export * from "./DocumentationSignatures.js";
 export * from "./DocumentationThrows.js";
 export * from "./DocumentationType.js";

package/ui/form/CheckboxInput.js

@@ -4,6 +4,8 @@ import { getFlexClass } from "../style/Flex.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import { getInputClass } from "./Input.js";
 import INPUT_CSS from "./Input.module.css";
+const INPUT_LABEL_CLASS = getModuleClass(INPUT_CSS, "label");
+const INPUT_PLACEHOLDER_CLASS = getModuleClass(INPUT_CSS, "placeholder");
 /**
  * Checkbox input bound to a `boolean` value, rendered as a labelled `<input type="checkbox">`.
  * - The label content comes from `children`, falling back to `placeholder`/`title`.
@@ -12,7 +14,8 @@ import INPUT_CSS from "./Input.module.css";
  * @example <CheckboxInput name="agree" value={agree} onValue={setAgree}>I agree</CheckboxInput>
  * @see https://shelving.cc/ui/CheckboxInput
  */
-export function CheckboxInput({ name, title, placeholder = title || "Yes", required = false, disabled = false, message = "", value = false, onValue, children, ...variants }) {
+export function CheckboxInput({ name, title, placeholder = "Yes", required = false, disabled = false, message = "", value = false, onValue, children = title, ...variants }) {
     const hasChildren = notNullish(children);
-    return (_jsxs("label", { className: getClass(getInputClass(variants), getModuleClass(INPUT_CSS, "label"), getFlexClass(variants), hasChildren && getModuleClass(INPUT_CSS, "placeholder")), "aria-invalid": !!message, children: [_jsx("input", { name: name, type: "checkbox", defaultChecked: !!value, onChange: e => onValue?.(!!e.currentTarget.checked), required: required, disabled: disabled, title: message, className: getModuleClass(INPUT_CSS, "radio") }), _jsx("span", { children: hasChildren ? children : placeholder })] }));
+    return (_jsxs("label", { className: getClass(getInputClass(variants), //
+        getFlexClass(variants), INPUT_LABEL_CLASS, !hasChildren && INPUT_PLACEHOLDER_CLASS), "aria-invalid": !!message, children: [_jsx("input", { name: name, type: "checkbox", defaultChecked: !!value, onChange: e => onValue?.(!!e.currentTarget.checked), required: required, disabled: disabled, title: message, className: getModuleClass(INPUT_CSS, "radio") }), _jsx("span", { children: hasChildren ? children : placeholder })] }));
 }

package/ui/form/CheckboxInput.tsx

@@ -6,6 +6,9 @@ import type { OptionalChildProps } from "../util/props.js";
 import { getInputClass, type InputVariants, type ValueInputProps } from "./Input.js";
 import INPUT_CSS from "./Input.module.css";
 
+const INPUT_LABEL_CLASS = getModuleClass(INPUT_CSS, "label");
+const INPUT_PLACEHOLDER_CLASS = getModuleClass(INPUT_CSS, "placeholder");
+
 /**
  * Props for `CheckboxInput`, a boolean-valued checkbox input.
  *
@@ -24,23 +27,23 @@ export interface CheckboxProps extends ValueInputProps<boolean>, OptionalChildPr
 export function CheckboxInput({
 	name,
 	title,
-	placeholder = title || "Yes",
+	placeholder = "Yes",
 	required = false,
 	disabled = false,
 	message = "",
 	value = false,
 	onValue,
-	children,
+	children = title,
 	...variants
 }: CheckboxProps): ReactElement {
 	const hasChildren = notNullish(children);
 	return (
 		<label
 			className={getClass(
-				getInputClass(variants),
-				getModuleClass(INPUT_CSS, "label"),
+				getInputClass(variants), //
 				getFlexClass(variants),
-				hasChildren && getModuleClass(INPUT_CSS, "placeholder"),
+				INPUT_LABEL_CLASS,
+				!hasChildren && INPUT_PLACEHOLDER_CLASS,
 			)}
 			aria-invalid={!!message}
 		>

package/ui/form/RadioInput.js

@@ -4,6 +4,8 @@ import { getFlexClass } from "../style/Flex.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import { getInputClass } from "./Input.js";
 import INPUT_CSS from "./Input.module.css";
+const INPUT_LABEL_CLASS = getModuleClass(INPUT_CSS, "label");
+const INPUT_PLACEHOLDER_CLASS = getModuleClass(INPUT_CSS, "placeholder");
 /**
  * Single `<input type="radio">` wrapped in a `<label>` styled as an `<Input>`.
  * - Calls `onValue(true)` when selected; label content comes from `children`, falling back to `placeholder`/`title`.
@@ -12,7 +14,8 @@ import INPUT_CSS from "./Input.module.css";
  * @example <RadioInput name="plan" value={isPro} onValue={selectPro}>Pro</RadioInput>
  * @see https://shelving.cc/ui/RadioInput
  */
-export function RadioInput({ name, title, placeholder = title || "Choose", required = false, disabled = false, message = "", value = false, onValue, children, ...props }) {
+export function RadioInput({ name, title, placeholder = "Choose", required = false, disabled = false, message = "", value = false, onValue, children = title, ...props }) {
     const hasChildren = notNullish(children);
-    return (_jsxs("label", { className: getClass(getInputClass(props), getModuleClass(INPUT_CSS, "label"), getFlexClass(props), hasChildren && getModuleClass(INPUT_CSS, "placeholder")), children: [_jsx("input", { className: getModuleClass(INPUT_CSS, "radio"), type: "radio", name: name, defaultChecked: value, onChange: () => onValue(true), disabled: disabled, required: required, "aria-invalid": !!message }), hasChildren ? children : placeholder] }));
+    return (_jsxs("label", { className: getClass(getInputClass(props), //
+        getFlexClass(props), INPUT_LABEL_CLASS, !hasChildren && INPUT_PLACEHOLDER_CLASS), children: [_jsx("input", { className: getModuleClass(INPUT_CSS, "radio"), type: "radio", name: name, defaultChecked: value, onChange: () => onValue(true), disabled: disabled, required: required, "aria-invalid": !!message }), hasChildren ? children : placeholder] }));
 }