shelving 1.239.0 → 1.240.0

package/package.json

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

package/ui/docs/DocumentationKind.d.ts

@@ -1,4 +1,5 @@
 import type { ReactElement } from "react";
+import type { ImmutableArray } from "../../util/array.js";
 import { type TagProps } from "../misc/Tag.js";
 import type { UIColor } from "../style/Color.js";
 /**
@@ -30,3 +31,28 @@ export declare function getDocumentationKindColor(kind: string): UIColor | undef
  * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKind
  */
 export declare function DocumentationKind({ kind, ...props }: DocumentationKindProps): ReactElement;
+/**
+ * Props for `DocumentationKindChips` — the kinds to offer plus the currently-selected kind.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKindChipsProps
+ */
+export interface DocumentationKindChipsProps {
+    /** The kinds to show as chips, in display order. */
+    readonly kinds: ImmutableArray<string>;
+    /** The currently-selected kind, or `undefined` when none is selected. */
+    readonly value?: string | undefined;
+    /** Called with the clicked kind, or `undefined` when the active chip is clicked again to clear it. */
+    readonly onValue?: ((kind: string | undefined) => void) | undefined;
+}
+/**
+ * Row of clickable kind-filter chips — clicking a chip selects that kind, clicking the active chip clears it.
+ * - Exclusive: at most one kind is selected at a time. The selected chip is shown bold.
+ * - Renders `null` when there are no `kinds`.
+ *
+ * @kind component
+ * @param props The `kinds` to offer, the selected `value`, and an `onValue` callback.
+ * @returns A `<Row>` of colour-coded `<Tag>` chips, or `null` when there are no kinds.
+ * @example <DocumentationKindChips kinds={["function", "class"]} value={kind} onValue={setKind} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKindChips
+ */
+export declare function DocumentationKindChips({ kinds, value, onValue }: DocumentationKindChipsProps): ReactElement | null;

package/ui/docs/DocumentationKind.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Tag } from "../misc/Tag.js";
+import { Row } from "../style/Flex.js";
 /**
  * Mapping from a documented symbol's `kind` to its raw colour variant.
  * - Related kinds share a hue: component/class (purple), function/method (blue), interface/type (aqua).
@@ -40,3 +41,19 @@ export function getDocumentationKindColor(kind) {
 export function DocumentationKind({ kind = "unknown", ...props }) {
     return (_jsx(Tag, { color: getDocumentationKindColor(kind), ...props, children: kind }));
 }
+/**
+ * Row of clickable kind-filter chips — clicking a chip selects that kind, clicking the active chip clears it.
+ * - Exclusive: at most one kind is selected at a time. The selected chip is shown bold.
+ * - Renders `null` when there are no `kinds`.
+ *
+ * @kind component
+ * @param props The `kinds` to offer, the selected `value`, and an `onValue` callback.
+ * @returns A `<Row>` of colour-coded `<Tag>` chips, or `null` when there are no kinds.
+ * @example <DocumentationKindChips kinds={["function", "class"]} value={kind} onValue={setKind} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKindChips
+ */
+export function DocumentationKindChips({ kinds, value, onValue }) {
+    if (!kinds.length)
+        return null;
+    return (_jsx(Row, { left: true, wrap: true, children: kinds.map(kind => (_jsx(Tag, { color: getDocumentationKindColor(kind), weight: kind === value ? "strong" : undefined, onClick: () => onValue?.(kind === value ? undefined : kind), children: kind }, kind))) }));
+}

package/ui/docs/DocumentationKind.tsx

@@ -1,6 +1,8 @@
 import type { ReactElement } from "react";
+import type { ImmutableArray } from "../../util/array.js";
 import { Tag, type TagProps } from "../misc/Tag.js";
 import type { UIColor } from "../style/Color.js";
+import { Row } from "../style/Flex.js";
 
 /**
  * Props for `DocumentationKind` — a `TagProps` plus the documented symbol's `kind`.
@@ -58,3 +60,46 @@ export function DocumentationKind({ kind = "unknown", ...props }: DocumentationK
 		</Tag>
 	);
 }
+
+/**
+ * Props for `DocumentationKindChips` — the kinds to offer plus the currently-selected kind.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKindChipsProps
+ */
+export interface DocumentationKindChipsProps {
+	/** The kinds to show as chips, in display order. */
+	readonly kinds: ImmutableArray<string>;
+	/** The currently-selected kind, or `undefined` when none is selected. */
+	readonly value?: string | undefined;
+	/** Called with the clicked kind, or `undefined` when the active chip is clicked again to clear it. */
+	readonly onValue?: ((kind: string | undefined) => void) | undefined;
+}
+
+/**
+ * Row of clickable kind-filter chips — clicking a chip selects that kind, clicking the active chip clears it.
+ * - Exclusive: at most one kind is selected at a time. The selected chip is shown bold.
+ * - Renders `null` when there are no `kinds`.
+ *
+ * @kind component
+ * @param props The `kinds` to offer, the selected `value`, and an `onValue` callback.
+ * @returns A `<Row>` of colour-coded `<Tag>` chips, or `null` when there are no kinds.
+ * @example <DocumentationKindChips kinds={["function", "class"]} value={kind} onValue={setKind} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKindChips
+ */
+export function DocumentationKindChips({ kinds, value, onValue }: DocumentationKindChipsProps): ReactElement | null {
+	if (!kinds.length) return null;
+	return (
+		<Row left wrap>
+			{kinds.map(kind => (
+				<Tag
+					key={kind}
+					color={getDocumentationKindColor(kind)}
+					weight={kind === value ? "strong" : undefined}
+					onClick={() => onValue?.(kind === value ? undefined : kind)}
+				>
+					{kind}
+				</Tag>
+			))}
+		</Row>
+	);
+}

package/ui/docs/DocumentationPage.js

@@ -1,6 +1,7 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment } from "react";
-import { queryElements } from "../../util/element.js";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment, useMemo, useState } from "react";
+import { walkElements } from "../../util/element.js";
+import { searchTree } from "../../util/tree.js";
 import { Block } from "../block/Block.js";
 import { Definitions } from "../block/Definitions.js";
 import { Heading } from "../block/Heading.js";
@@ -10,6 +11,7 @@ import { Preformatted } from "../block/Preformatted.js";
 import { Prose } from "../block/Prose.js";
 import { Header, Section } from "../block/Section.js";
 import { Title } from "../block/Title.js";
+import { TextInput } from "../form/TextInput.js";
 import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
 import { Page } from "../page/Page.js";
@@ -17,7 +19,7 @@ import { Row } from "../style/Flex.js";
 import { TreeBreadcrumbs } from "../tree/TreeBreadcrumbs.js";
 import { TreeCards } from "../tree/TreeCards.js";
 import { DocumentationButtons } from "./DocumentationButtons.js";
-import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKind.js";
+import { DocumentationKind, DocumentationKindChips, getDocumentationKindColor } from "./DocumentationKind.js";
 import { DocumentationSignatures } from "./DocumentationSignatures.js";
 const DEFAULT_TYPE = "unknown";
 /** Documentation `kind`s grouped into card sections, in display order — pluralised, sentence-case headings. */
@@ -31,6 +33,46 @@ const KIND_SECTIONS = {
     method: "Methods",
     property: "Properties",
 };
+/** 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, { wide: true, children: [_jsx(Heading, { children: label }), _jsx(TreeCards, { children: group })] }, kind)) : null;
+    });
+}
+/**
+ * Interactive children listing for a documentation page — a filter input, kind chips, and grouped cards.
+ *
+ * - Filters this page's own children as you type (ranked via `searchTree`, capped at 20); the kind chips narrow to a single `kind`.
+ * - With an empty filter and no chip selected, shows the normal grouped listing of `children`.
+ * - Renders nothing when the page has no children (e.g. a leaf symbol) — no point showing an empty filter.
+ *
+ * @param props The page's child elements.
+ * @returns The filter controls plus the grouped card sections, or `null` when there are no children.
+ */
+function DocumentationChildren({ elements }) {
+    const [query, setQuery] = useState("");
+    const [chip, setChip] = useState(undefined);
+    const childElements = useMemo(() => Array.from(walkElements(elements)), [elements]);
+    // Kinds present in this page's children, in section order, for the chip row.
+    const kinds = useMemo(() => Object.keys(KIND_SECTIONS).filter(k => childElements.some(el => el.props.kind === k)), [childElements]);
+    // No children → nothing to list or filter.
+    if (!childElements.length)
+        return null;
+    const trimmed = query.trim();
+    const active = !!trimmed || !!chip;
+    // Inactive → normal grouped listing. Active → filter this page's children, grouped the same way.
+    let listing;
+    if (!active) {
+        listing = _renderSections(childElements);
+    }
+    else {
+        const scope = { type: "tree-element", key: "", props: { name: "", children: elements } };
+        const filter = chip ? { kind: chip } : undefined;
+        listing = _renderSections(searchTree(scope, trimmed, { limit: 20, filter }));
+    }
+    return (_jsxs(_Fragment, { children: [_jsxs(Section, { wide: true, children: [_jsx(TextInput, { name: "filter", title: "Filter", placeholder: "Filter\u2026", value: query, onValue: v => setQuery(v ?? "") }), _jsx(DocumentationKindChips, { kinds: kinds, value: chip, onValue: setChip })] }), listing] }));
+}
 /**
  * Page renderer for a `tree-documentation` element — the full detail page for a documented symbol.
  * - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, and examples.
@@ -44,9 +86,5 @@ const KIND_SECTIONS = {
  * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationPage/DocumentationPage
  */
 export function DocumentationPage({ title, name, kind = "unknown", description, content, signatures, params, returns, throws, examples, children, ...props }) {
-    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: getDocumentationKindColor(kind), children: [_jsx(Panel, { children: _jsxs(Header, { wide: true, children: [_jsx(TreeBreadcrumbs, {}), _jsx(Title, { children: _jsxs(Row, { left: true, wrap: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind, size: "normal" })] }) }), _jsx(DocumentationButtons, { ...props })] }) }), signatures?.length || params?.length || returns?.length || throws?.length ? (_jsxs(Section, { wide: true, children: [_jsx(DocumentationSignatures, { signatures: signatures }), params?.length && (_jsxs(Section, { wide: true, children: [_jsx(Label, { children: "Parameters" }), _jsx(Definitions, { children: params.map(({ name, type = DEFAULT_TYPE, description = "", optional }) => (_jsxs(Fragment, { children: [_jsx("dt", { children: _jsxs(Code, { size: "normal", children: [name, optional ? "?" : "", ": ", type] }) }), _jsx("dd", { children: description })] }, `${name}-${type}-${description}`))) })] })), returns?.length && (_jsxs(Section, { wide: true, children: [_jsx(Label, { children: "Returns" }), _jsx(Definitions, { children: returns.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsxs(Fragment, { children: [_jsx("dt", { children: _jsx(Code, { size: "normal", children: type }) }), _jsx("dd", { children: description })] }, `${type}-${description}`))) })] })), throws?.length && (_jsxs(Section, { wide: true, children: [_jsx(Label, { children: "Throws" }), _jsx(Definitions, { children: throws.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsxs(Fragment, { children: [_jsx("dt", { children: _jsx(Code, { size: "normal", children: type }) }), _jsx("dd", { children: description })] }, `${type}-${description}`))) })] }))] })) : null, content && (_jsx(Section, { wide: true, children: _jsx(Prose, { children: _jsx(Markup, { children: content }) }) })), examples?.length && (_jsxs(Section, { wide: true, children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), Object.entries(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, { wide: true, children: [_jsx(Heading, { children: label }), _jsx(TreeCards, { children: group })] }, kind)) : null;
-                })] }) }));
+    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: getDocumentationKindColor(kind), children: [_jsx(Panel, { children: _jsxs(Header, { wide: true, children: [_jsx(TreeBreadcrumbs, {}), _jsx(Title, { children: _jsxs(Row, { left: true, wrap: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind, size: "normal" })] }) }), _jsx(DocumentationButtons, { ...props })] }) }), signatures?.length || params?.length || returns?.length || throws?.length ? (_jsxs(Section, { wide: true, children: [_jsx(DocumentationSignatures, { signatures: signatures }), params?.length && (_jsxs(Section, { wide: true, children: [_jsx(Label, { children: "Parameters" }), _jsx(Definitions, { children: params.map(({ name, type = DEFAULT_TYPE, description = "", optional }) => (_jsxs(Fragment, { children: [_jsx("dt", { children: _jsxs(Code, { size: "normal", children: [name, optional ? "?" : "", ": ", type] }) }), _jsx("dd", { children: description })] }, `${name}-${type}-${description}`))) })] })), returns?.length && (_jsxs(Section, { wide: true, children: [_jsx(Label, { children: "Returns" }), _jsx(Definitions, { children: returns.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsxs(Fragment, { children: [_jsx("dt", { children: _jsx(Code, { size: "normal", children: type }) }), _jsx("dd", { children: description })] }, `${type}-${description}`))) })] })), throws?.length && (_jsxs(Section, { wide: true, children: [_jsx(Label, { children: "Throws" }), _jsx(Definitions, { children: throws.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsxs(Fragment, { children: [_jsx("dt", { children: _jsx(Code, { size: "normal", children: type }) }), _jsx("dd", { children: description })] }, `${type}-${description}`))) })] }))] })) : null, content && (_jsx(Section, { wide: true, children: _jsx(Prose, { children: _jsx(Markup, { children: content }) }) })), examples?.length && (_jsxs(Section, { wide: true, children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), _jsx(DocumentationChildren, { elements: children })] }) }));
 }

package/ui/docs/DocumentationPage.tsx

@@ -1,7 +1,8 @@
-import { Fragment, type ReactNode } from "react";
-import { type Element, queryElements } from "../../util/element.js";
+import { Fragment, type ReactNode, useMemo, useState } from "react";
+import { walkElements } from "../../util/element.js";
 import type { Query } from "../../util/query.js";
-import type { DocumentationElementProps, TreeElement } from "../../util/tree.js";
+import type { DocumentationElementProps, TreeElement, TreeElements } from "../../util/tree.js";
+import { searchTree } from "../../util/tree.js";
 import { Block } from "../block/Block.js";
 import { Definitions } from "../block/Definitions.js";
 import { Heading } from "../block/Heading.js";
@@ -11,6 +12,7 @@ import { Preformatted } from "../block/Preformatted.js";
 import { Prose } from "../block/Prose.js";
 import { Header, Section } from "../block/Section.js";
 import { Title } from "../block/Title.js";
+import { TextInput } from "../form/TextInput.js";
 import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
 import { Page } from "../page/Page.js";
@@ -18,7 +20,7 @@ import { Row } from "../style/Flex.js";
 import { TreeBreadcrumbs } from "../tree/TreeBreadcrumbs.js";
 import { TreeCards } from "../tree/TreeCards.js";
 import { DocumentationButtons } from "./DocumentationButtons.js";
-import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKind.js";
+import { DocumentationKind, DocumentationKindChips, getDocumentationKindColor } from "./DocumentationKind.js";
 import { DocumentationSignatures } from "./DocumentationSignatures.js";
 
 const DEFAULT_TYPE = "unknown";
@@ -35,6 +37,68 @@ const KIND_SECTIONS = {
 	property: "Properties",
 };
 
+/** 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 wide key={kind}>
+				<Heading>{label}</Heading>
+				<TreeCards>{group}</TreeCards>
+			</Section>
+		) : null;
+	});
+}
+
+/**
+ * Interactive children listing for a documentation page — a filter input, kind chips, and grouped cards.
+ *
+ * - Filters this page's own children as you type (ranked via `searchTree`, capped at 20); the kind chips narrow to a single `kind`.
+ * - With an empty filter and no chip selected, shows the normal grouped listing of `children`.
+ * - Renders nothing when the page has no children (e.g. a leaf symbol) — no point showing an empty filter.
+ *
+ * @param props The page's child elements.
+ * @returns The filter controls plus the grouped card sections, or `null` when there are no children.
+ */
+function DocumentationChildren({ elements }: { readonly elements?: TreeElements }): ReactNode {
+	const [query, setQuery] = useState("");
+	const [chip, setChip] = useState<string | undefined>(undefined);
+
+	const childElements = useMemo(() => Array.from(walkElements<TreeElement>(elements)), [elements]);
+
+	// Kinds present in this page's children, in section order, for the chip row.
+	const kinds = useMemo(
+		() => Object.keys(KIND_SECTIONS).filter(k => childElements.some(el => (el.props as DocumentationElementProps).kind === k)),
+		[childElements],
+	);
+
+	// No children → nothing to list or filter.
+	if (!childElements.length) return null;
+
+	const trimmed = query.trim();
+	const active = !!trimmed || !!chip;
+
+	// Inactive → normal grouped listing. Active → filter this page's children, grouped the same way.
+	let listing: ReactNode;
+	if (!active) {
+		listing = _renderSections(childElements);
+	} else {
+		const scope: TreeElement = { type: "tree-element", key: "", props: { name: "", children: elements } };
+		const filter = chip ? ({ kind: chip } as Query) : undefined;
+		listing = _renderSections(searchTree(scope, trimmed, { limit: 20, filter }));
+	}
+
+	return (
+		<>
+			<Section wide>
+				<TextInput name="filter" title="Filter" placeholder="Filter…" value={query} onValue={v => setQuery(v ?? "")} />
+				<DocumentationKindChips kinds={kinds} value={chip} onValue={setChip} />
+			</Section>
+			{listing}
+		</>
+	);
+}
+
 /**
  * Page renderer for a `tree-documentation` element — the full detail page for a documented symbol.
  * - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, and examples.
@@ -144,16 +208,7 @@ export function DocumentationPage({
 						))}
 					</Section>
 				)}
-				{Object.entries(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 wide key={kind}>
-							<Heading>{label}</Heading>
-							<TreeCards>{group}</TreeCards>
-						</Section>
-					) : null;
-				})}
+				<DocumentationChildren elements={children} />
 			</Block>
 		</Page>
 	);

package/ui/tree/TreeApp.d.ts

@@ -21,6 +21,7 @@ export interface TreeAppProps extends PossibleMeta {
  * - Wraps `<App>` with error catching and a sidebar layout.
  * - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
  * - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
+ * - URLs that don't match a tree element fall through to a `<Router>` carrying the built-in `<TreeIndexPage>` (`/all`) plus any extra `routes`.
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
  *

package/ui/tree/TreeApp.js

@@ -2,6 +2,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { App } from "../app/App.js";
 import { SidebarLayout } from "../layout/SidebarLayout.js";
 import { PageCatcher } from "../misc/Catcher.js";
+import { Router } from "../router/Router.js";
+import { TREE_INDEX_PATH, TreeIndexPage } from "./TreeIndexPage.js";
 import { TreeRouter } from "./TreeRouter.js";
 import { TreeSidebar } from "./TreeSidebar.js";
 /**
@@ -10,6 +12,7 @@ import { TreeSidebar } from "./TreeSidebar.js";
  * - Wraps `<App>` with error catching and a sidebar layout.
  * - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
  * - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
+ * - URLs that don't match a tree element fall through to a `<Router>` carrying the built-in `<TreeIndexPage>` (`/all`) plus any extra `routes`.
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
  *
@@ -20,5 +23,7 @@ import { TreeSidebar } from "./TreeSidebar.js";
  * @see https://dhoulb.github.io/shelving/ui/tree/TreeApp/TreeApp
  */
 export function TreeApp({ tree, routes: extraRoutes, ...meta }) {
-    return (_jsx(App, { ...meta, children: _jsx(PageCatcher, { children: _jsx(SidebarLayout, { sidebar: _jsx(TreeSidebar, { tree: tree }), children: _jsx(TreeRouter, { tree: tree }) }) }) }));
+    // URLs that don't resolve to a tree element fall through to this router: the built-in index page plus any extra routes.
+    const fallback = _jsx(Router, { routes: { [TREE_INDEX_PATH]: TreeIndexPage, ...extraRoutes } });
+    return (_jsx(App, { ...meta, children: _jsx(PageCatcher, { children: _jsx(SidebarLayout, { sidebar: _jsx(TreeSidebar, { tree: tree }), children: _jsx(TreeRouter, { tree: tree, fallback: fallback }) }) }) }));
 }

package/ui/tree/TreeApp.tsx

@@ -3,8 +3,10 @@ import type { TreeElement } from "../../util/index.js";
 import { App } from "../app/App.js";
 import { SidebarLayout } from "../layout/SidebarLayout.js";
 import { PageCatcher } from "../misc/Catcher.js";
+import { Router } from "../router/Router.js";
 import type { Routes } from "../router/Routes.js";
 import type { PossibleMeta } from "../util/index.js";
+import { TREE_INDEX_PATH, TreeIndexPage } from "./TreeIndexPage.js";
 import { TreeRouter } from "./TreeRouter.js";
 import { TreeSidebar } from "./TreeSidebar.js";
 
@@ -28,6 +30,7 @@ export interface TreeAppProps extends PossibleMeta {
  * - Wraps `<App>` with error catching and a sidebar layout.
  * - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
  * - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
+ * - URLs that don't match a tree element fall through to a `<Router>` carrying the built-in `<TreeIndexPage>` (`/all`) plus any extra `routes`.
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
  *
@@ -38,11 +41,13 @@ export interface TreeAppProps extends PossibleMeta {
  * @see https://dhoulb.github.io/shelving/ui/tree/TreeApp/TreeApp
  */
 export function TreeApp({ tree, routes: extraRoutes, ...meta }: TreeAppProps): ReactElement {
+	// URLs that don't resolve to a tree element fall through to this router: the built-in index page plus any extra routes.
+	const fallback = <Router routes={{ [TREE_INDEX_PATH]: TreeIndexPage, ...extraRoutes }} />;
 	return (
 		<App {...meta}>
 			<PageCatcher>
 				<SidebarLayout sidebar={<TreeSidebar tree={tree} />}>
-					<TreeRouter tree={tree} />
+					<TreeRouter tree={tree} fallback={fallback} />
 				</SidebarLayout>
 			</PageCatcher>
 		</App>

package/ui/tree/TreeIndexPage.d.ts

@@ -0,0 +1,18 @@
+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.
+ *
+ * - A `<TextInput>` filters as you type; a row of kind chips narrows by `kind` via `searchTree`'s `filter`.
+ * - 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 chips, and a flat card listing of results.
+ * @example <Router routes={{ [TREE_INDEX_PATH]: TreeIndexPage }} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeIndexPage/TreeIndexPage
+ */
+export declare function TreeIndexPage(): ReactNode;

package/ui/tree/TreeIndexPage.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState } from "react";
+import { searchTree } from "../../util/tree.js";
+import { Header, Section } from "../block/Section.js";
+import { Title } from "../block/Title.js";
+import { DocumentationKindChips } from "../docs/DocumentationKind.js";
+import { TextInput } from "../form/TextInput.js";
+import { Page } from "../page/Page.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";
+/** 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.";
+/** Kinds offered as filter chips, in display order — mirrors `DocumentationPage`'s sections. */
+const INDEX_KINDS = ["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;
+/**
+ * Page listing every element in the system in one flat, searchable view.
+ *
+ * - A `<TextInput>` filters as you type; a row of kind chips narrows by `kind` via `searchTree`'s `filter`.
+ * - 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 chips, and a flat card listing of results.
+ * @example <Router routes={{ [TREE_INDEX_PATH]: TreeIndexPage }} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeIndexPage/TreeIndexPage
+ */
+export function TreeIndexPage() {
+    const [query, setQuery] = useState("");
+    const [chip, setChip] = useState(undefined);
+    const root = useTreeMap().get("/");
+    // Kinds actually present anywhere in the tree, in display order, for the chip row.
+    const kinds = useMemo(() => {
+        if (!root)
+            return [];
+        const all = searchTree(root, "", { limit: Number.POSITIVE_INFINITY });
+        return INDEX_KINDS.filter(kind => all.some(el => el.props.kind === kind));
+    }, [root]);
+    const trimmed = query.trim();
+    const filter = chip ? { kind: chip } : 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 (_jsxs(Page, { title: INDEX_TITLE, description: INDEX_DESCRIPTION, children: [_jsx(Header, { wide: true, children: _jsx(Title, { children: INDEX_TITLE }) }), _jsxs(Section, { wide: true, children: [_jsx(TextInput, { name: "search", title: "Search", placeholder: "Search\u2026", value: query, onValue: v => setQuery(v ?? "") }), _jsx(DocumentationKindChips, { kinds: kinds, value: chip, onValue: setChip })] }), _jsx(Section, { wide: true, children: _jsx(TreeCards, { children: cards }) })] }));
+}

package/ui/tree/TreeIndexPage.tsx

@@ -0,0 +1,74 @@
+import { type ReactNode, useMemo, useState } from "react";
+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 { Header, Section } from "../block/Section.js";
+import { Title } from "../block/Title.js";
+import { DocumentationKindChips } from "../docs/DocumentationKind.js";
+import { TextInput } from "../form/TextInput.js";
+import { Page } from "../page/Page.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;
+
+/** 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.";
+
+/** Kinds offered as filter chips, in display order — mirrors `DocumentationPage`'s sections. */
+const INDEX_KINDS = ["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;
+
+/**
+ * Page listing every element in the system in one flat, searchable view.
+ *
+ * - A `<TextInput>` filters as you type; a row of kind chips narrows by `kind` via `searchTree`'s `filter`.
+ * - 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 chips, and a flat card listing of results.
+ * @example <Router routes={{ [TREE_INDEX_PATH]: TreeIndexPage }} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeIndexPage/TreeIndexPage
+ */
+export function TreeIndexPage(): ReactNode {
+	const [query, setQuery] = useState("");
+	const [chip, setChip] = useState<string | undefined>(undefined);
+
+	const root = useTreeMap().get("/");
+
+	// Kinds actually present anywhere in the tree, in display order, for the chip row.
+	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));
+	}, [root]);
+
+	const trimmed = query.trim();
+	const filter = chip ? ({ kind: chip } as Query) : 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 (
+		<Page title={INDEX_TITLE} description={INDEX_DESCRIPTION}>
+			<Header wide>
+				<Title>{INDEX_TITLE}</Title>
+			</Header>
+			<Section wide>
+				<TextInput name="search" title="Search" placeholder="Search…" value={query} onValue={v => setQuery(v ?? "")} />
+				<DocumentationKindChips kinds={kinds} value={chip} onValue={setChip} />
+			</Section>
+			<Section wide>
+				<TreeCards>{cards}</TreeCards>
+			</Section>
+		</Page>
+	);
+}

package/ui/tree/TreeSidebar.d.ts

@@ -1,6 +1,6 @@
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
 import type { AbsolutePath } from "../../util/path.js";
-import type { TreeElement } from "../../util/tree.js";
+import { type TreeElement } from "../../util/tree.js";
 /**
  * Props for the `TreeSidebar` component — the root tree element plus its URL path.
  *
@@ -13,15 +13,17 @@ export interface TreeSidebarProps {
     readonly path?: AbsolutePath | undefined;
 }
 /**
- * Sidebar built from a tree element.
+ * Sidebar built from a tree element, in three sections separated by dividers.
  *
- * - Renders a single "home" `<MenuItem>` for the root element itself, then the root's children as a `<TreeMenuMapper>` underneath.
- * - The home link uses `path` as its href (defaulting to `/`). The children's hrefs are computed by appending their `name` to the root's path.
- * - To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
+ * - **Top:** a "Home" link to the root and an "All elements" link to the `<TreeIndexPage>` (`/all`).
+ * - **Middle:** a `<TextInput>` search-as-you-type filter.
+ * - **Bottom:** the root's children as a `<TreeMenuMapper>` — swapped for a flat ranked list of results (capped at 20) while the search holds a query.
+ *
+ * Child and result hrefs use each element's canonical `path` (or `joinPath(parent, name)` as a fallback). To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
  *
  * @kind component
  * @param props The root `tree` element and optional root `path`.
- * @returns A `<Menu>` with a home link plus the root's children as navigation items.
+ * @returns The sectioned sidebar — home/index links, a search input, and either the tree menu or search results.
  * @example <TreeSidebar tree={tree} />
  * @see https://dhoulb.github.io/shelving/ui/tree/TreeSidebar/TreeSidebar
  */

package/ui/tree/TreeSidebar.js

@@ -1,20 +1,32 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState } from "react";
 import { filterElements } from "../../util/element.js";
+import { flattenTree, searchTree } from "../../util/tree.js";
+import { Divider } from "../block/Divider.js";
+import { TextInput } from "../form/TextInput.js";
 import { Menu, MenuItem } from "../menu/Menu.js";
+import { TREE_INDEX_PATH } from "./TreeIndexPage.js";
 import { matchMenuElement, TreeMenuMapper } from "./TreeMenu.js";
 /**
- * Sidebar built from a tree element.
+ * Sidebar built from a tree element, in three sections separated by dividers.
  *
- * - Renders a single "home" `<MenuItem>` for the root element itself, then the root's children as a `<TreeMenuMapper>` underneath.
- * - The home link uses `path` as its href (defaulting to `/`). The children's hrefs are computed by appending their `name` to the root's path.
- * - To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
+ * - **Top:** a "Home" link to the root and an "All elements" link to the `<TreeIndexPage>` (`/all`).
+ * - **Middle:** a `<TextInput>` search-as-you-type filter.
+ * - **Bottom:** the root's children as a `<TreeMenuMapper>` — swapped for a flat ranked list of results (capped at 20) while the search holds a query.
+ *
+ * Child and result hrefs use each element's canonical `path` (or `joinPath(parent, name)` as a fallback). To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
  *
  * @kind component
  * @param props The root `tree` element and optional root `path`.
- * @returns A `<Menu>` with a home link plus the root's children as navigation items.
+ * @returns The sectioned sidebar — home/index links, a search input, and either the tree menu or search results.
  * @example <TreeSidebar tree={tree} />
  * @see https://dhoulb.github.io/shelving/ui/tree/TreeSidebar/TreeSidebar
  */
 export function TreeSidebar({ tree, path = "/" }) {
-    return (_jsxs(Menu, { children: [_jsx(MenuItem, { href: path, children: tree.props.title ?? tree.props.name }), _jsx(TreeMenuMapper, { path: path, children: filterElements(tree.props.children, matchMenuElement) })] }));
+    const [query, setQuery] = useState("");
+    const trimmed = query.trim();
+    // Flatten once so search results carry a canonical `path` (and a unique `key`) for their links (the sidebar sits outside the router's `<TreeProvider>`).
+    const root = useMemo(() => flattenTree(tree).get("/") ?? tree, [tree]);
+    const results = trimmed ? searchTree(root, trimmed, { limit: 20 }) : null;
+    return (_jsxs(_Fragment, { children: [_jsxs(Menu, { children: [_jsx(MenuItem, { href: path, children: "Home" }), _jsx(MenuItem, { href: TREE_INDEX_PATH, children: "All elements" })] }), _jsx(Divider, {}), _jsx(TextInput, { name: "search", title: "Search", placeholder: "Search\u2026", value: query, onValue: v => setQuery(v ?? "") }), _jsx(Divider, {}), _jsx(Menu, { children: results ? (results.map(el => (_jsx(MenuItem, { href: el.props.path ?? path, children: el.props.title ?? el.props.name }, el.key)))) : (_jsx(TreeMenuMapper, { path: path, children: filterElements(tree.props.children, matchMenuElement) })) })] }));
 }

package/ui/tree/TreeSidebar.tsx

@@ -1,8 +1,11 @@
-import type { ReactNode } from "react";
+import { type ReactNode, useMemo, useState } from "react";
 import { filterElements } from "../../util/element.js";
 import type { AbsolutePath } from "../../util/path.js";
-import type { TreeElement } from "../../util/tree.js";
+import { flattenTree, searchTree, type TreeElement } from "../../util/tree.js";
+import { Divider } from "../block/Divider.js";
+import { TextInput } from "../form/TextInput.js";
 import { Menu, MenuItem } from "../menu/Menu.js";
+import { TREE_INDEX_PATH } from "./TreeIndexPage.js";
 import { matchMenuElement, TreeMenuMapper } from "./TreeMenu.js";
 
 /**
@@ -18,23 +21,48 @@ export interface TreeSidebarProps {
 }
 
 /**
- * Sidebar built from a tree element.
+ * Sidebar built from a tree element, in three sections separated by dividers.
  *
- * - Renders a single "home" `<MenuItem>` for the root element itself, then the root's children as a `<TreeMenuMapper>` underneath.
- * - The home link uses `path` as its href (defaulting to `/`). The children's hrefs are computed by appending their `name` to the root's path.
- * - To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
+ * - **Top:** a "Home" link to the root and an "All elements" link to the `<TreeIndexPage>` (`/all`).
+ * - **Middle:** a `<TextInput>` search-as-you-type filter.
+ * - **Bottom:** the root's children as a `<TreeMenuMapper>` — swapped for a flat ranked list of results (capped at 20) while the search holds a query.
+ *
+ * Child and result hrefs use each element's canonical `path` (or `joinPath(parent, name)` as a fallback). To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
  *
  * @kind component
  * @param props The root `tree` element and optional root `path`.
- * @returns A `<Menu>` with a home link plus the root's children as navigation items.
+ * @returns The sectioned sidebar — home/index links, a search input, and either the tree menu or search results.
  * @example <TreeSidebar tree={tree} />
  * @see https://dhoulb.github.io/shelving/ui/tree/TreeSidebar/TreeSidebar
  */
 export function TreeSidebar({ tree, path = "/" as AbsolutePath }: TreeSidebarProps): ReactNode {
+	const [query, setQuery] = useState("");
+	const trimmed = query.trim();
+
+	// Flatten once so search results carry a canonical `path` (and a unique `key`) for their links (the sidebar sits outside the router's `<TreeProvider>`).
+	const root = useMemo(() => flattenTree(tree).get("/") ?? tree, [tree]);
+	const results = trimmed ? searchTree(root, trimmed, { limit: 20 }) : null;
+
 	return (
-		<Menu>
-			<MenuItem href={path}>{tree.props.title ?? tree.props.name}</MenuItem>
-			<TreeMenuMapper path={path}>{filterElements(tree.props.children, matchMenuElement)}</TreeMenuMapper>
-		</Menu>
+		<>
+			<Menu>
+				<MenuItem href={path}>Home</MenuItem>
+				<MenuItem href={TREE_INDEX_PATH}>All elements</MenuItem>
+			</Menu>
+			<Divider />
+			<TextInput name="search" title="Search" placeholder="Search…" value={query} onValue={v => setQuery(v ?? "")} />
+			<Divider />
+			<Menu>
+				{results ? (
+					results.map(el => (
+						<MenuItem key={el.key} href={el.props.path ?? path}>
+							{el.props.title ?? el.props.name}
+						</MenuItem>
+					))
+				) : (
+					<TreeMenuMapper path={path}>{filterElements(tree.props.children, matchMenuElement)}</TreeMenuMapper>
+				)}
+			</Menu>
+		</>
 	);
 }

package/ui/tree/index.d.ts

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

package/ui/tree/index.js

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

package/ui/tree/index.ts

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

package/util/tree.d.ts

@@ -1,6 +1,7 @@
 import type { ImmutableArray } from "./array.js";
 import type { Element, ElementProps, Elements } from "./element.js";
 import { type AbsolutePath } from "./path.js";
+import type { Query } from "./query.js";
 /**
  * Props for a tree element — must have a `tree-` prefixed type.
  *
@@ -153,6 +154,7 @@ declare module "react" {
  *   - its **flat key** — bare `name` (e.g. `"BooleanSchema"`), or qualified `"Class.member"` for members (e.g. `"BooleanSchema.validate"`). This is what cross-refs (`extends` / `implements`) and README links resolve through.
  *   - its **canonical path** (`element.props.path`, e.g. `"/schema/BooleanSchema"`) — what the router resolves a URL to.
  * - The map values keep their (stamped) children, so the map doubles as the navigable tree: `map.get("/")` is the stamped root and flattening never throws away the hierarchy. The router resolves a URL with `map.get(path)`; the static builder enumerates pages from the path-shaped keys.
+ * - Each stamped element's own `key` is also set to its canonical `path` — so a flat (cross-tree) listing of stamped elements has globally-unique React keys, where the bare `name` would collide (many `get` / `value` / `url`).
  * - Exported names are unique across the package (barrel re-exports enforce it at compile time), so flat-key collisions are vanishingly rare; on a collision the last writer simply wins.
  * - Missing keys (e.g. builtins like `Serializable`) resolve to `undefined` → callers fall back to plain text.
  *
@@ -163,3 +165,33 @@ declare module "react" {
  * @see https://dhoulb.github.io/shelving/util/tree/flattenTree
  */
 export declare function flattenTree(root: TreeElement, base?: ReadonlyMap<string, TreeElement>): Map<string, TreeElement>;
+/**
+ * Options for `searchTree()`.
+ *
+ * @see https://dhoulb.github.io/shelving/util/tree/SearchTreeOptions
+ */
+export interface SearchTreeOptions {
+    /** Maximum number of results to return (defaults to `20`). */
+    readonly limit?: number | undefined;
+    /**
+     * Optional `Query` narrowing the candidates by *any* prop before ranking — the same shape `queryItems()` takes.
+     * - e.g. `{ kind: "method" }` to only rank methods, or `{ source: "…" }` to constrain by source.
+     */
+    readonly filter?: Query | undefined;
+}
+/**
+ * Search the descendants of a tree element and return the best-ranked matches.
+ *
+ * - Walks every descendant of `scope` (depth-first; `scope` itself is not a candidate), optionally narrowed by `options.filter`.
+ * - Tokenises `query` with `getWords()` so quoted phrases match literally: `searchTree(root, '"hello world" foo')` scores the phrase `hello world` *and* the word `foo` independently, stacking their scores.
+ * - Ranks each candidate (case-insensitive) per token, summing: `name` exact > `name` starts-with > `name` includes > `title` includes > `description` includes > `content` includes. A `name` match always outranks a content-only match.
+ * - An empty `query` returns the (filtered) candidates in tree order — useful for a filter-only or "show everything" listing.
+ *
+ * @param scope The element whose descendants are searched.
+ * @param query The search string — bare words plus `"quoted phrases"`.
+ * @param options `limit` (default `20`) and an optional `filter` `Query` over each candidate's props.
+ * @returns The matching descendants, best first, capped at `limit`.
+ * @example searchTree(root, "store", { limit: 10, filter: { kind: "class" } }) // up to 10 classes ranked for "store"
+ * @see https://dhoulb.github.io/shelving/util/tree/searchTree
+ */
+export declare function searchTree(scope: TreeElement, query: string, options?: SearchTreeOptions): TreeElement[];

package/util/tree.js

@@ -1,5 +1,7 @@
 import { walkElements } from "./element.js";
 import { joinPath } from "./path.js";
+import { queryItems } from "./query.js";
+import { getWords } from "./string.js";
 /**
  * Flatten a tree into a `Map` for O(1) lookup, stamping a canonical `path` onto every element as it walks.
  * - Returns a *copy* of the tree, indexed. Each element is rebuilt with its canonical site-root-relative `path`: the root is `/`, each descendant is `parentPath + "/" + name` — so a module `schema` → `/schema`, its class `BooleanSchema` → `/schema/BooleanSchema`, its member `validate` → `/schema/BooleanSchema/validate`. A composite module name (e.g. `"util/string"`) becomes its own multi-segment chunk.
@@ -7,6 +9,7 @@ import { joinPath } from "./path.js";
  *   - its **flat key** — bare `name` (e.g. `"BooleanSchema"`), or qualified `"Class.member"` for members (e.g. `"BooleanSchema.validate"`). This is what cross-refs (`extends` / `implements`) and README links resolve through.
  *   - its **canonical path** (`element.props.path`, e.g. `"/schema/BooleanSchema"`) — what the router resolves a URL to.
  * - The map values keep their (stamped) children, so the map doubles as the navigable tree: `map.get("/")` is the stamped root and flattening never throws away the hierarchy. The router resolves a URL with `map.get(path)`; the static builder enumerates pages from the path-shaped keys.
+ * - Each stamped element's own `key` is also set to its canonical `path` — so a flat (cross-tree) listing of stamped elements has globally-unique React keys, where the bare `name` would collide (many `get` / `value` / `url`).
  * - Exported names are unique across the package (barrel re-exports enforce it at compile time), so flat-key collisions are vanishingly rare; on a collision the last writer simply wins.
  * - Missing keys (e.g. builtins like `Serializable`) resolve to `undefined` → callers fall back to plain text.
  *
@@ -24,7 +27,13 @@ export function flattenTree(root, base) {
 function _flattenElement(element, path, map) {
     // Rebuild children first (bottom-up) so the stamped element carries stamped children — the map doubles as the nested tree.
     const children = Array.from(walkElements(element.props.children), child => _flattenElement(child, joinPath(path, child.props.name), map));
-    const stamped = { ...element, props: { ...element.props, path, children: children.length ? children : undefined } };
+    // Stamp the canonical `path` onto both `props.path` and the element's own `key` — the latter gives a flat listing of tree
+    // elements globally-unique React keys (bare names like `get` / `value` / `url` collide across the tree).
+    const stamped = {
+        ...element,
+        key: path,
+        props: { ...element.props, path, children: children.length ? children : undefined },
+    };
     map.set(_flatKey(stamped), stamped);
     map.set(path, stamped);
     return stamped;
@@ -34,3 +43,74 @@ function _flatKey(element) {
     const { class: className, name } = element.props;
     return className ? `${className}.${name}` : name;
 }
+/**
+ * Search the descendants of a tree element and return the best-ranked matches.
+ *
+ * - Walks every descendant of `scope` (depth-first; `scope` itself is not a candidate), optionally narrowed by `options.filter`.
+ * - Tokenises `query` with `getWords()` so quoted phrases match literally: `searchTree(root, '"hello world" foo')` scores the phrase `hello world` *and* the word `foo` independently, stacking their scores.
+ * - Ranks each candidate (case-insensitive) per token, summing: `name` exact > `name` starts-with > `name` includes > `title` includes > `description` includes > `content` includes. A `name` match always outranks a content-only match.
+ * - An empty `query` returns the (filtered) candidates in tree order — useful for a filter-only or "show everything" listing.
+ *
+ * @param scope The element whose descendants are searched.
+ * @param query The search string — bare words plus `"quoted phrases"`.
+ * @param options `limit` (default `20`) and an optional `filter` `Query` over each candidate's props.
+ * @returns The matching descendants, best first, capped at `limit`.
+ * @example searchTree(root, "store", { limit: 10, filter: { kind: "class" } }) // up to 10 classes ranked for "store"
+ * @see https://dhoulb.github.io/shelving/util/tree/searchTree
+ */
+export function searchTree(scope, query, options) {
+    const { limit = 20, filter } = options ?? {};
+    // Gather every descendant of `scope`, optionally narrowed by a `filter` query over each element's props.
+    let candidates = Array.from(_walkTree(scope));
+    if (filter) {
+        // `queryItems()` is typed for `Data`; element props are plain objects at runtime, so cast for the filter and map back by reference.
+        const allowed = new Set(queryItems(candidates.map(el => el.props), filter));
+        candidates = candidates.filter(el => allowed.has(el.props));
+    }
+    // Tokenise the query — quoted phrases match literally, bare words match individually.
+    const tokens = getWords(query.toLowerCase());
+    // No query → return the (filtered) candidates in tree order, capped at `limit`.
+    if (!tokens.length)
+        return candidates.slice(0, limit);
+    // Score every candidate, drop non-matches, sort by score descending, cap at `limit`.
+    const scored = candidates.map(el => [el, _scoreElement(el.props, tokens)]).filter(([, score]) => score > 0);
+    scored.sort((a, b) => b[1] - a[1]);
+    return scored.slice(0, limit).map(([el]) => el);
+}
+/** Walk every descendant of a tree element depth-first — the element itself is not yielded. */
+function* _walkTree(scope) {
+    for (const child of walkElements(scope.props.children)) {
+        yield child;
+        yield* _walkTree(child);
+    }
+}
+// Score tiers — separated by orders of magnitude so a single higher-tier hit outranks any realistic stack of lower-tier hits (a `name` match always beats a content-only match).
+const _SCORE_NAME_EXACT = 10000;
+const _SCORE_NAME_STARTS = 1000;
+const _SCORE_NAME_INCLUDES = 100;
+const _SCORE_TITLE = 10;
+const _SCORE_DESCRIPTION = 4;
+const _SCORE_CONTENT = 1;
+/** Score one element's props against the (already lower-cased) query tokens — each token contributes its best-matching tier, summed. */
+function _scoreElement(props, tokens) {
+    const name = props.name.toLowerCase();
+    const title = props.title?.toLowerCase() ?? "";
+    const description = props.description?.toLowerCase() ?? "";
+    const content = props.content?.toLowerCase() ?? "";
+    let score = 0;
+    for (const token of tokens) {
+        if (name === token)
+            score += _SCORE_NAME_EXACT;
+        else if (name.startsWith(token))
+            score += _SCORE_NAME_STARTS;
+        else if (name.includes(token))
+            score += _SCORE_NAME_INCLUDES;
+        else if (title.includes(token))
+            score += _SCORE_TITLE;
+        else if (description.includes(token))
+            score += _SCORE_DESCRIPTION;
+        else if (content.includes(token))
+            score += _SCORE_CONTENT;
+    }
+    return score;
+}