shelving 1.229.0 → 1.230.0

package/package.json

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

package/ui/misc/MetaContext.d.ts

@@ -1,20 +1,30 @@
+import type { AnyCaller } from "../../util/function.js";
 import type { AbsolutePath } from "../../util/path.js";
 import { type URIParams } from "../../util/uri.js";
+import { type ImmutableURL } from "../../util/url.js";
 import { type Meta, type PossibleMeta } from "../util/meta.js";
-import type { ChildProps } from "../util/props.js";
 /** Context to store the `Config` object. */
 export declare const MetaContext: import("react").Context<Meta>;
-export interface MetaProps extends PossibleMeta, ChildProps {
-}
-/** Require the current meta context in a component. */
+/**
+ * Use the current meta context in a component.
+ *
+ * @param meta A set of new possible meta data to combine into the current meta context.
+ */
 export declare function requireMeta(meta?: PossibleMeta): Meta;
-/** Get all URI/route params from the current meta context's URL. */
-export declare function requireMetaParams(): URIParams;
+/** A `Meta` object with a defined `url` object, and `path` and `params` properties combined in. */
+export interface MetaURL extends Meta {
+    url: ImmutableURL;
+    /** The path of `url` relative to `meta.root` (i.e. the _site-root-relative_ path). */
+    path: AbsolutePath;
+    /** The `?query` params of `url` extracted as a flat set of parameters. */
+    params: URIParams;
+}
 /**
- * Get the current page's path relative to the site root.
- * - Strips the meta `root` (site base) prefix from the meta `url`, leaving a site-root-relative `AbsolutePath`.
- * - Returns `undefined` when `url` or `root` is unset, or they sit on different origins — the path is then unknowable.
+ * Use the current meta context in a component with some additional URL helpers.
  *
- * @returns The site-root-relative path (e.g. `/util/array`), or `undefined` if it can't be determined.
+ * @param meta A set of new possible meta data to combine into the current meta context.
+ * @returns A `Meta` object with a defined `url` object, and `path` and `params` properties combined in.
+ * @throws {RequiredError} if the current meta has no `url`
+ * @throws {RequiredError} if the current meta `url` does not match the origin of the current meta `root`
  */
-export declare function getMetaPath(): AbsolutePath | undefined;
+export declare function requireMetaURL(meta?: PossibleMeta, caller?: AnyCaller): MetaURL;

package/ui/misc/MetaContext.js

@@ -1,27 +1,35 @@
 import { createContext, use } from "react";
+import { RequiredError } from "../../error/RequiredError.js";
 import { getURIParams } from "../../util/uri.js";
 import { matchURLPrefix } from "../../util/url.js";
 import { mergeMeta } from "../util/meta.js";
 /** Context to store the `Config` object. */
 export const MetaContext = createContext({});
 MetaContext.displayName = "MetaContext";
-/** Require the current meta context in a component. */
+/**
+ * Use the current meta context in a component.
+ *
+ * @param meta A set of new possible meta data to combine into the current meta context.
+ */
 export function requireMeta(meta) {
     const current = use(MetaContext);
     return meta ? mergeMeta(current, meta) : current;
 }
-/** Get all URI/route params from the current meta context's URL. */
-export function requireMetaParams() {
-    return getURIParams(requireMeta().url ?? {}, requireMetaParams);
-}
 /**
- * Get the current page's path relative to the site root.
- * - Strips the meta `root` (site base) prefix from the meta `url`, leaving a site-root-relative `AbsolutePath`.
- * - Returns `undefined` when `url` or `root` is unset, or they sit on different origins — the path is then unknowable.
+ * Use the current meta context in a component with some additional URL helpers.
  *
- * @returns The site-root-relative path (e.g. `/util/array`), or `undefined` if it can't be determined.
+ * @param meta A set of new possible meta data to combine into the current meta context.
+ * @returns A `Meta` object with a defined `url` object, and `path` and `params` properties combined in.
+ * @throws {RequiredError} if the current meta has no `url`
+ * @throws {RequiredError} if the current meta `url` does not match the origin of the current meta `root`
  */
-export function getMetaPath() {
-    const { url, root } = requireMeta();
-    return matchURLPrefix(url, root, getMetaPath);
+export function requireMetaURL(meta, caller = requireMetaURL) {
+    const { url, root, ...combined } = requireMeta(meta);
+    if (!url)
+        throw new RequiredError("Meta URL is required", { received: url, caller });
+    const path = matchURLPrefix(url, root, caller);
+    if (!path)
+        throw new RequiredError("Meta URL and meta root must share an origin", { url, root, caller });
+    const params = getURIParams(url, caller);
+    return { ...combined, url, root, path, params };
 }

package/ui/misc/MetaContext.test.tsx

@@ -1,15 +1,16 @@
 import { describe, expect, test } from "bun:test";
 import type { ReactNode } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
+import { RequiredError } from "../../error/RequiredError.js";
 import { createMeta } from "../util/meta.js";
-import { getMetaPath, MetaContext } from "./MetaContext.js";
+import { MetaContext, requireMetaURL } from "./MetaContext.js";
 
-/** Render `getMetaPath()` from inside a component so its `use(MetaContext)` call is valid. */
+/** Render `requireMetaURL().path` from inside a component so its `use(MetaContext)` call is valid. */
 function Probe(): ReactNode {
-	return getMetaPath() ?? "none";
+	return requireMetaURL().path;
 }
 
-describe("getMetaPath", () => {
+describe("requireMetaURL", () => {
 	test("returns the page path relative to the site root", () => {
 		const html = renderToStaticMarkup(
 			<MetaContext value={createMeta({ root: "http://x.com/sub/", url: "./util/array" })}>
@@ -28,16 +29,17 @@ describe("getMetaPath", () => {
 		expect(html).toBe("/");
 	});
 
-	test("returns undefined when url or root is unset", () => {
-		expect(renderToStaticMarkup(<Probe />)).toBe("none");
+	test("throws RequiredError when url is unset", () => {
+		expect(() => renderToStaticMarkup(<Probe />)).toThrow(RequiredError);
 	});
 
-	test("returns undefined when url and root are on different origins", () => {
-		const html = renderToStaticMarkup(
-			<MetaContext value={createMeta({ root: "http://x.com/", url: "http://y.com/foo" })}>
-				<Probe />
-			</MetaContext>,
-		);
-		expect(html).toBe("none");
+	test("throws RequiredError when url and root are on different origins", () => {
+		expect(() =>
+			renderToStaticMarkup(
+				<MetaContext value={createMeta({ root: "http://x.com/", url: "http://y.com/foo" })}>
+					<Probe />
+				</MetaContext>,
+			),
+		).toThrow(RequiredError);
 	});
 });

package/ui/misc/MetaContext.tsx

@@ -1,35 +1,47 @@
 import { createContext, use } from "react";
+import { RequiredError } from "../../error/RequiredError.js";
+import type { AnyCaller } from "../../util/function.js";
 import type { AbsolutePath } from "../../util/path.js";
 import { getURIParams, type URIParams } from "../../util/uri.js";
-import { matchURLPrefix } from "../../util/url.js";
+import { type ImmutableURL, matchURLPrefix } from "../../util/url.js";
 import { type Meta, mergeMeta, type PossibleMeta } from "../util/meta.js";
-import type { ChildProps } from "../util/props.js";
 
 /** Context to store the `Config` object. */
 export const MetaContext = createContext<Meta>({});
 MetaContext.displayName = "MetaContext";
 
-export interface MetaProps extends PossibleMeta, ChildProps {}
-
-/** Require the current meta context in a component. */
+/**
+ * Use the current meta context in a component.
+ *
+ * @param meta A set of new possible meta data to combine into the current meta context.
+ */
 export function requireMeta(meta?: PossibleMeta): Meta {
 	const current = use(MetaContext);
 	return meta ? mergeMeta(current, meta) : current;
 }
 
-/** Get all URI/route params from the current meta context's URL. */
-export function requireMetaParams(): URIParams {
-	return getURIParams(requireMeta().url ?? {}, requireMetaParams);
+/** A `Meta` object with a defined `url` object, and `path` and `params` properties combined in. */
+export interface MetaURL extends Meta {
+	url: ImmutableURL;
+	/** The path of `url` relative to `meta.root` (i.e. the _site-root-relative_ path). */
+	path: AbsolutePath;
+	/** The `?query` params of `url` extracted as a flat set of parameters. */
+	params: URIParams;
 }
 
 /**
- * Get the current page's path relative to the site root.
- * - Strips the meta `root` (site base) prefix from the meta `url`, leaving a site-root-relative `AbsolutePath`.
- * - Returns `undefined` when `url` or `root` is unset, or they sit on different origins — the path is then unknowable.
+ * Use the current meta context in a component with some additional URL helpers.
  *
- * @returns The site-root-relative path (e.g. `/util/array`), or `undefined` if it can't be determined.
+ * @param meta A set of new possible meta data to combine into the current meta context.
+ * @returns A `Meta` object with a defined `url` object, and `path` and `params` properties combined in.
+ * @throws {RequiredError} if the current meta has no `url`
+ * @throws {RequiredError} if the current meta `url` does not match the origin of the current meta `root`
  */
-export function getMetaPath(): AbsolutePath | undefined {
-	const { url, root } = requireMeta();
-	return matchURLPrefix(url, root, getMetaPath);
+export function requireMetaURL(meta?: PossibleMeta, caller: AnyCaller = requireMetaURL): MetaURL {
+	const { url, root, ...combined } = requireMeta(meta);
+	if (!url) throw new RequiredError("Meta URL is required", { received: url, caller });
+	const path = matchURLPrefix(url, root, caller);
+	if (!path) throw new RequiredError("Meta URL and meta root must share an origin", { url, root, caller });
+	const params = getURIParams(url, caller);
+	return { ...combined, url, root, path, params };
 }

package/ui/misc/README.md

@@ -111,7 +111,7 @@ const [TreeMapping, TreeMapper] = createMapper({
 
 `requireMeta` reads the context and optionally merges in override props — use this in components that need to resolve URLs against the current page.
 
-`requireMetaParams` extracts route placeholder and query params from the current URL.
+`requireMetaURL` resolves the current `url` against the meta `root` and returns the meta extended with the site-root-relative `path` and the extracted query `params`. Throws if `url` is unset or sits on a different origin to `root`.
 
 ## See also
 

package/ui/page/HTML.js

@@ -6,6 +6,6 @@ import { MetaContext, requireMeta } from "../misc/MetaContext.js";
  */
 export function HTML({ children, ...meta }) {
     const merged = requireMeta(meta);
-    const { language, root: base, app } = merged;
-    return (_jsxs("html", { lang: language, children: [_jsxs("head", { children: [_jsx("meta", { charSet: "utf-8" }), base && _jsx("base", { href: base.href }), app && _jsx("title", { children: app })] }), _jsx("body", { children: _jsx(MetaContext, { value: merged, children: children }) })] }));
+    const { language, root, app } = merged;
+    return (_jsxs("html", { lang: language, children: [_jsxs("head", { children: [_jsx("meta", { charSet: "utf-8" }), root && _jsx("base", { href: root.href }), app && _jsx("title", { children: app })] }), _jsx("body", { children: _jsx(MetaContext, { value: merged, children: children }) })] }));
 }

package/ui/page/HTML.tsx

@@ -11,12 +11,12 @@ export interface HTMLProps extends PossibleMeta, ChildProps {}
  */
 export function HTML({ children, ...meta }: HTMLProps): ReactElement {
 	const merged = requireMeta(meta);
-	const { language, root: base, app } = merged;
+	const { language, root, app } = merged;
 	return (
 		<html lang={language}>
 			<head>
 				<meta charSet="utf-8" />
-				{base && <base href={base.href} />}
+				{root && <base href={root.href} />}
 				{app && <title>{app}</title>}
 			</head>
 			<body>

package/ui/router/Navigation.js

@@ -17,8 +17,8 @@ import { NavigationStore } from "./NavigationStore.js";
  * TODO: switch click/popstate handling to the browser Navigation API when broadly supported.
  */
 export function Navigation({ children, ...meta }) {
-    const { url, root: base, ...merged } = requireMeta(meta);
-    const nav = useInstance(NavigationStore, url, base);
+    const { url, root, ...merged } = requireMeta(meta);
+    const nav = useInstance(NavigationStore, url, root);
     useStore(nav);
     useEffect(() => {
         if (typeof document === "undefined" || typeof window === "undefined")
@@ -30,8 +30,8 @@ export function Navigation({ children, ...meta }) {
                 if (anchor instanceof HTMLAnchorElement && anchor.origin === window.location.origin && !anchor.hasAttribute("download")) {
                     e.preventDefault();
                     nav.forward(anchor.href);
-                    return false;
-                } // `return false` stops iOS web app opening every link in a new window.
+                    return false; // `return false` stops iOS web app opening every link in a new window.
+                }
             }
         };
         const onPopState = () => {
@@ -44,7 +44,7 @@ export function Navigation({ children, ...meta }) {
             window.removeEventListener("popstate", onPopState);
         };
     }, [nav]);
-    return (_jsx(NavigationContext, { value: nav, children: _jsx(MetaContext, { value: { root: base, url: nav.value, ...merged }, children: children }) }));
+    return (_jsx(NavigationContext, { value: nav, children: _jsx(MetaContext, { value: { url: nav.value, root, ...merged }, children: children }) }));
 }
 /**
  * Force a full remount of children whenever the navigation URL changes.

package/ui/router/Navigation.tsx

@@ -21,8 +21,8 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {}
  * TODO: switch click/popstate handling to the browser Navigation API when broadly supported.
  */
 export function Navigation({ children, ...meta }: NavigationProps): ReactElement {
-	const { url, root: base, ...merged } = requireMeta(meta);
-	const nav = useInstance(NavigationStore, url, base);
+	const { url, root, ...merged } = requireMeta(meta);
+	const nav = useInstance(NavigationStore, url, root);
 	useStore(nav);
 
 	useEffect(() => {
@@ -36,8 +36,8 @@ export function Navigation({ children, ...meta }: NavigationProps): ReactElement
 				if (anchor instanceof HTMLAnchorElement && anchor.origin === window.location.origin && !anchor.hasAttribute("download")) {
 					e.preventDefault();
 					nav.forward(anchor.href);
-					return false;
-				} // `return false` stops iOS web app opening every link in a new window.
+					return false; // `return false` stops iOS web app opening every link in a new window.
+				}
 			}
 		};
 		const onPopState = () => {
@@ -55,7 +55,7 @@ export function Navigation({ children, ...meta }: NavigationProps): ReactElement
 
 	return (
 		<NavigationContext value={nav}>
-			<MetaContext value={{ root: base, url: nav.value, ...merged }}>{children}</MetaContext>
+			<MetaContext value={{ url: nav.value, root, ...merged }}>{children}</MetaContext>
 		</NavigationContext>
 	);
 }

package/ui/router/Router.d.ts

@@ -2,7 +2,13 @@ import type { ReactElement } from "react";
 import type { PossibleMeta } from "../util/meta.js";
 import type { Routes } from "./Routes.js";
 export interface RouterProps extends PossibleMeta {
+    /** List of routes for the router to match against. */
     readonly routes: Routes;
+    /**
+     * Optional fallback element.
+     * - Explicit `null` means fallback to nothing (router will not throw `NotFoundError`).
+     */
+    readonly fallback?: ReactElement | undefined | null;
 }
 /**
  * Match the current URL against `routes` and render the matched element.
@@ -11,5 +17,7 @@ export interface RouterProps extends PossibleMeta {
  * - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
  * - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
  * - Returns `null` when there's no URL in context or the URL is outside the base.
+ *
+ * @throws {NotFoundError} if no route matches and `fallback` is `undefined`
  */
-export declare function Router({ routes, ...meta }: RouterProps): ReactElement | null;
+export declare function Router({ routes, fallback, ...meta }: RouterProps): ReactElement | null;

package/ui/router/Router.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { NotFoundError } from "../../error/RequestError.js";
 import { UnexpectedError } from "../../error/UnexpectedError.js";
+import { getProps } from "../../util/index.js";
 import { matchPathTemplate, renderPathTemplate } from "../../util/template.js";
-import { getURIParams } from "../../util/uri.js";
-import { matchURLPrefix } from "../../util/url.js";
-import { requireMeta } from "../misc/MetaContext.js";
+import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
 /**
  * Match the current URL against `routes` and render the matched element.
  * - Reads `url` and `base` from the surrounding `<Meta>` context (override via props).
@@ -11,18 +11,20 @@ import { requireMeta } from "../misc/MetaContext.js";
  * - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
  * - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
  * - Returns `null` when there's no URL in context or the URL is outside the base.
+ *
+ * @throws {NotFoundError} if no route matches and `fallback` is `undefined`
  */
-export function Router({ routes, ...meta }) {
-    const { url, root: base } = requireMeta(meta);
-    if (!url)
-        return null;
-    const path = base ? matchURLPrefix(url, base) : url.pathname;
-    if (!path)
-        return null;
-    return _matchRoute(routes, path, url);
+export function Router({ routes, fallback, ...meta }) {
+    const combined = requireMetaURL(meta);
+    const path = combined;
+    const route = _matchRoute(routes, fallback, combined);
+    if (route)
+        return _jsx(MetaContext, { value: combined, children: route });
+    throw new NotFoundError("Tree route not found", { received: path });
 }
-function _matchRoute(routes, path, url, depth = 0) {
-    for (const [route, Route] of Object.entries(routes)) {
+function _matchRoute(routes, fallback, meta, path = meta.path, depth = 0) {
+    for (const [route, Route] of getProps(routes)) {
+        // Try to match this path.
         const placeholders = matchPathTemplate(route, path);
         if (!placeholders)
             continue;
@@ -33,13 +35,17 @@ function _matchRoute(routes, path, url, depth = 0) {
         if (typeof Route === "string") {
             if (depth > 10)
                 throw new UnexpectedError("Infinite redirect loop", { received: route, expected: path, caller: _matchRoute });
-            return _matchRoute(routes, renderPathTemplate(Route, placeholders), url, depth + 1);
+            return _matchRoute(routes, fallback, meta, renderPathTemplate(Route, placeholders), depth + 1);
         }
         // React element — render as-is.
         if (typeof Route !== "function")
             return Route;
-        // Function / component — render with merged URL query params and route placeholders as props (placeholders win on conflict).
-        return _jsx(Route, { ...getURIParams(url), ...placeholders });
+        // Component — render with merged URL query params and route placeholders as props (placeholders win on conflict).
+        _jsx(Route, { ...meta.params, ...placeholders }, path);
     }
-    return null;
+    // No match, try the fallback.
+    if (fallback !== undefined)
+        return fallback;
+    // Fallback is undefined, throw a `NotFoundError`
+    throw new NotFoundError("No matching route found", { received: path, caller: _matchRoute });
 }

package/ui/router/Router.tsx

@@ -1,15 +1,21 @@
 import type { ReactElement } from "react";
+import { NotFoundError } from "../../error/RequestError.js";
 import { UnexpectedError } from "../../error/UnexpectedError.js";
-import type { AbsolutePath } from "../../util/path.js";
+import { getProps } from "../../util/index.js";
 import { matchPathTemplate, renderPathTemplate } from "../../util/template.js";
-import { getURIParams } from "../../util/uri.js";
-import { type ImmutableURL, matchURLPrefix } from "../../util/url.js";
-import { requireMeta } from "../misc/MetaContext.js";
+import { MetaContext, type MetaURL, requireMetaURL } from "../misc/MetaContext.js";
 import type { PossibleMeta } from "../util/meta.js";
 import type { Routes } from "./Routes.js";
 
 export interface RouterProps extends PossibleMeta {
+	/** List of routes for the router to match against. */
 	readonly routes: Routes;
+
+	/**
+	 * Optional fallback element.
+	 * - Explicit `null` means fallback to nothing (router will not throw `NotFoundError`).
+	 */
+	readonly fallback?: ReactElement | undefined | null;
 }
 
 /**
@@ -19,18 +25,27 @@ export interface RouterProps extends PossibleMeta {
  * - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
  * - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
  * - Returns `null` when there's no URL in context or the URL is outside the base.
+ *
+ * @throws {NotFoundError} if no route matches and `fallback` is `undefined`
  */
-export function Router({ routes, ...meta }: RouterProps): ReactElement | null {
-	const { url, root: base } = requireMeta(meta);
-	if (!url) return null;
-	const path = base ? matchURLPrefix(url, base) : url.pathname;
-	if (!path) return null;
-	return _matchRoute(routes, path, url);
+export function Router({ routes, fallback, ...meta }: RouterProps): ReactElement | null {
+	const combined = requireMetaURL(meta);
+	const path = combined;
+	const route = _matchRoute(routes, fallback, combined);
+	if (route) return <MetaContext value={combined}>{route}</MetaContext>;
+	throw new NotFoundError("Tree route not found", { received: path });
 }
 
-function _matchRoute(routes: Routes, path: AbsolutePath, url: ImmutableURL, depth = 0): ReactElement | null {
-	for (const [route, Route] of Object.entries(routes)) {
-		const placeholders = matchPathTemplate(route as AbsolutePath, path);
+function _matchRoute(
+	routes: Routes,
+	fallback: ReactElement | null | undefined,
+	meta: MetaURL,
+	path = meta.path,
+	depth = 0,
+): ReactElement | null | undefined {
+	for (const [route, Route] of getProps(routes)) {
+		// Try to match this path.
+		const placeholders = matchPathTemplate(route, path);
 		if (!placeholders) continue;
 
 		// Skip falsy. Allows a route to be conditionally disabled by setting its value to `null` or `false`.
@@ -39,14 +54,19 @@ function _matchRoute(routes: Routes, path: AbsolutePath, url: ImmutableURL, dept
 		// String value is a redirect; re-run matching with the new path. Guard against infinite redirect loops by limiting depth.
 		if (typeof Route === "string") {
 			if (depth > 10) throw new UnexpectedError("Infinite redirect loop", { received: route, expected: path, caller: _matchRoute });
-			return _matchRoute(routes, renderPathTemplate(Route, placeholders), url, depth + 1);
+			return _matchRoute(routes, fallback, meta, renderPathTemplate(Route, placeholders), depth + 1);
 		}
 
 		// React element — render as-is.
 		if (typeof Route !== "function") return Route;
 
-		// Function / component — render with merged URL query params and route placeholders as props (placeholders win on conflict).
-		return <Route {...getURIParams(url)} {...placeholders} />;
+		// Component — render with merged URL query params and route placeholders as props (placeholders win on conflict).
+		<Route key={path} {...meta.params} {...placeholders} />;
 	}
-	return null;
+
+	// No match, try the fallback.
+	if (fallback !== undefined) return fallback;
+
+	// Fallback is undefined, throw a `NotFoundError`
+	throw new NotFoundError("No matching route found", { received: path, caller: _matchRoute });
 }

package/ui/tree/TreeApp.d.ts

@@ -2,11 +2,12 @@ import type { ReactElement } from "react";
 import type { TreeElement } from "../../util/index.js";
 import type { Routes } from "../router/Routes.js";
 import type { PossibleMeta } from "../util/index.js";
-import type { OptionalChildProps } from "../util/props.js";
-export interface TreeAppProps extends PossibleMeta, OptionalChildProps {
+export interface TreeAppProps extends PossibleMeta {
     /** The tree elements to display. */
     tree: TreeElement;
-    /** Additional routes (merged with the default tree route). */
+    /**
+     * Additional routes.
+     */
     routes?: Routes | undefined;
 }
 /**
@@ -17,4 +18,4 @@ export interface TreeAppProps extends PossibleMeta, OptionalChildProps {
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
  */
-export declare function TreeApp({ tree, routes, children, ...appProps }: TreeAppProps): ReactElement;
+export declare function TreeApp({ tree, routes: extraRoutes, ...meta }: TreeAppProps): ReactElement;

package/ui/tree/TreeApp.js

@@ -2,8 +2,7 @@ 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 { TreePage } from "./TreePage.js";
+import { TreeRouter } from "./TreeRouter.js";
 import { TreeSidebar } from "./TreeSidebar.js";
 /**
  * Top-level app component for a tree-based documentation site.
@@ -13,12 +12,6 @@ import { TreeSidebar } from "./TreeSidebar.js";
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
  */
-export function TreeApp({ tree, routes = {}, children, ...appProps }) {
-    const allRoutes = {
-        ...routes,
-        "/": () => _jsx(TreePage, { tree: tree }),
-        // `{...path}` is a named catchall — captures any remaining segments (including empty) as `path`.
-        "/{...path}": ({ path = "" }) => _jsx(TreePage, { path: `/${path}`, tree: tree }),
-    };
-    return (_jsx(App, { ...appProps, children: _jsx(PageCatcher, { children: _jsx(SidebarLayout, { sidebar: _jsx(TreeSidebar, { tree: tree }), children: children ?? _jsx(Router, { routes: allRoutes }) }) }) }));
+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 }) }) }) }));
 }

package/ui/tree/TreeApp.tsx

@@ -3,17 +3,17 @@ 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 type { OptionalChildProps } from "../util/props.js";
-import { TreePage } from "./TreePage.js";
+import { TreeRouter } from "./TreeRouter.js";
 import { TreeSidebar } from "./TreeSidebar.js";
 
-export interface TreeAppProps extends PossibleMeta, OptionalChildProps {
+export interface TreeAppProps extends PossibleMeta {
 	/** The tree elements to display. */
 	tree: TreeElement;
-	/** Additional routes (merged with the default tree route). */
+	/**
+	 * Additional routes.
+	 */
 	routes?: Routes | undefined;
 }
 
@@ -25,18 +25,13 @@ export interface TreeAppProps extends PossibleMeta, OptionalChildProps {
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
  */
-export function TreeApp({ tree, routes = {}, children, ...appProps }: TreeAppProps): ReactElement {
-	const allRoutes: Routes = {
-		...routes,
-		"/": () => <TreePage tree={tree} />,
-		// `{...path}` is a named catchall — captures any remaining segments (including empty) as `path`.
-		"/{...path}": ({ path = "" }) => <TreePage path={`/${path}`} tree={tree} />,
-	};
-
+export function TreeApp({ tree, routes: extraRoutes, ...meta }: TreeAppProps): ReactElement {
 	return (
-		<App {...appProps}>
+		<App {...meta}>
 			<PageCatcher>
-				<SidebarLayout sidebar={<TreeSidebar tree={tree} />}>{children ?? <Router routes={allRoutes} />}</SidebarLayout>
+				<SidebarLayout sidebar={<TreeSidebar tree={tree} />}>
+					<TreeRouter tree={tree} />
+				</SidebarLayout>
 			</PageCatcher>
 		</App>
 	);

package/ui/tree/TreeRouter.d.ts

@@ -0,0 +1,30 @@
+import type { ReactElement, ReactNode } from "react";
+import { type TreeElement } from "../../util/element.js";
+import { type AbsolutePath } from "../../util/path.js";
+import type { PossibleMeta } from "../util/index.js";
+/** Extras threaded through `TreeRouterMapper` to the page renderer — the site-root-relative path of the page. */
+interface TreeRouterExtras {
+    /** Site-root-relative URL path of the page being rendered. Each page forwards it to its child cards. */
+    readonly path: AbsolutePath;
+}
+/** Mapping + Mapper pair for tree routers — wrap children in `<TreeRouterMapping>` to override. */
+export declare const TreeRouterMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps<TreeRouterExtras>>, TreeRouterMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps<TreeRouterExtras>>;
+export interface TreeRouterProps extends PossibleMeta {
+    /** The tree of elements to match routes for. */
+    readonly tree: TreeElement;
+    /**
+     * Optional fallback element.
+     * - Explicit `null` means fallback to nothing (router will not throw `NotFoundError`).
+     */
+    readonly fallback?: ReactElement | undefined | null;
+}
+/**
+ * Resolve a URL path to a tree element and render it as a full page.
+ * - Walks the tree by matching each path segment to a descendant's `key` (via `resolveElementPath()`).
+ * - `/` renders the root itself; deeper paths render the matching descendant.
+ * - `path` is the site-root-relative path (already stripped of any `APP_URL` subfolder by `<Router>`); it is threaded to the page renderer so child cards build correct hrefs.
+ * - Throws `NotFoundError` if no element matches at any level.
+ * - To override the renderer for a specific element type, wrap in `<TreeRouterMapping mapping={…}>`.
+ */
+export declare function TreeRouter({ tree, fallback, ...meta }: TreeRouterProps): ReactNode;
+export {};

package/ui/tree/{TreePage.js → TreeRouter.js}

@@ -6,8 +6,9 @@ import { DirectoryPage } from "../docs/DirectoryPage.js";
 import { DocumentationPage } from "../docs/DocumentationPage.js";
 import { FilePage } from "../docs/FilePage.js";
 import { createMapper } from "../misc/Mapper.js";
-/** Mapping + Mapper pair for tree pages — wrap children in `<TreePageMapping>` to override. */
-export const [TreePageMapping, TreePageMapper] = createMapper({
+import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
+/** Mapping + Mapper pair for tree routers — wrap children in `<TreeRouterMapping>` to override. */
+export const [TreeRouterMapping, TreeRouterMapper] = createMapper({
     "tree-directory": DirectoryPage,
     "tree-file": FilePage,
     "tree-documentation": DocumentationPage,
@@ -18,12 +19,15 @@ export const [TreePageMapping, TreePageMapper] = createMapper({
  * - `/` renders the root itself; deeper paths render the matching descendant.
  * - `path` is the site-root-relative path (already stripped of any `APP_URL` subfolder by `<Router>`); it is threaded to the page renderer so child cards build correct hrefs.
  * - Throws `NotFoundError` if no element matches at any level.
- * - To override the renderer for a specific element type, wrap in `<TreePageMapping mapping={…}>`.
+ * - To override the renderer for a specific element type, wrap in `<TreeRouterMapping mapping={…}>`.
  */
-export function TreePage({ path = "/", tree }) {
-    const segments = splitPath(path);
-    const element = resolveElementPath(tree, segments);
-    if (!element)
-        throw new NotFoundError("Element not found", { received: path });
-    return _jsx(TreePageMapper, { path: path, children: element });
+export function TreeRouter({ tree, fallback, ...meta }) {
+    const { path, ...combined } = requireMetaURL(meta);
+    // Find a `TreeElement` matching the current URL meta path.
+    const element = resolveElementPath(tree, splitPath(path));
+    // We render either a mapped version of the tree element, or the fallback element.
+    const route = element ? _jsx(TreeRouterMapper, { path: path, children: element }) : fallback;
+    if (route !== undefined)
+        return _jsx(MetaContext, { value: combined, children: route });
+    throw new NotFoundError("Tree route not found", { received: path });
 }

package/ui/tree/{TreePage.test.tsx → TreeRouter.test.tsx}

@@ -3,7 +3,7 @@ import { renderToStaticMarkup } from "react-dom/server";
 import type { TreeElement } from "../../util/element.js";
 import { MetaContext } from "../misc/MetaContext.js";
 import { createMeta } from "../util/meta.js";
-import { TreePage } from "./TreePage.js";
+import { TreeRouter } from "./TreeRouter.js";
 
 /** Minimal tree: root → `util` directory → `array` file. */
 const tree: TreeElement = {
@@ -21,12 +21,12 @@ const tree: TreeElement = {
 	},
 };
 
-describe("TreePage", () => {
+describe("TreeRouter", () => {
 	// When `APP_URL` has a subfolder, the page threads its site-root-relative path to child cards so hrefs include the subfolder exactly once.
 	test("card links include an APP_URL subfolder exactly once", () => {
 		const html = renderToStaticMarkup(
 			<MetaContext value={createMeta({ root: "http://x.com/sub/", url: "./util" })}>
-				<TreePage path="/util" tree={tree} />
+				<TreeRouter tree={tree} />
 			</MetaContext>,
 		);
 		expect(html).toContain('href="http://x.com/sub/util/array"');
@@ -36,7 +36,7 @@ describe("TreePage", () => {
 	test("root page card links include an APP_URL subfolder exactly once", () => {
 		const html = renderToStaticMarkup(
 			<MetaContext value={createMeta({ root: "http://x.com/sub/", url: "./" })}>
-				<TreePage path="/" tree={tree} />
+				<TreeRouter tree={tree} />
 			</MetaContext>,
 		);
 		expect(html).toContain('href="http://x.com/sub/util"');

package/ui/tree/TreeRouter.tsx

@@ -0,0 +1,55 @@
+import type { ReactElement, ReactNode } from "react";
+import { NotFoundError } from "../../error/RequestError.js";
+import { resolveElementPath, type TreeElement } from "../../util/element.js";
+import { type AbsolutePath, splitPath } from "../../util/path.js";
+import { DirectoryPage } from "../docs/DirectoryPage.js";
+import { DocumentationPage } from "../docs/DocumentationPage.js";
+import { FilePage } from "../docs/FilePage.js";
+import { createMapper } from "../misc/Mapper.js";
+import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
+
+import type { PossibleMeta } from "../util/index.js";
+
+/** Extras threaded through `TreeRouterMapper` to the page renderer — the site-root-relative path of the page. */
+interface TreeRouterExtras {
+	/** Site-root-relative URL path of the page being rendered. Each page forwards it to its child cards. */
+	readonly path: AbsolutePath;
+}
+
+/** Mapping + Mapper pair for tree routers — wrap children in `<TreeRouterMapping>` to override. */
+export const [TreeRouterMapping, TreeRouterMapper] = createMapper<TreeRouterExtras>({
+	"tree-directory": DirectoryPage,
+	"tree-file": FilePage,
+	"tree-documentation": DocumentationPage,
+});
+
+export interface TreeRouterProps extends PossibleMeta {
+	/** The tree of elements to match routes for. */
+	readonly tree: TreeElement;
+
+	/**
+	 * Optional fallback element.
+	 * - Explicit `null` means fallback to nothing (router will not throw `NotFoundError`).
+	 */
+	readonly fallback?: ReactElement | undefined | null;
+}
+
+/**
+ * Resolve a URL path to a tree element and render it as a full page.
+ * - Walks the tree by matching each path segment to a descendant's `key` (via `resolveElementPath()`).
+ * - `/` renders the root itself; deeper paths render the matching descendant.
+ * - `path` is the site-root-relative path (already stripped of any `APP_URL` subfolder by `<Router>`); it is threaded to the page renderer so child cards build correct hrefs.
+ * - Throws `NotFoundError` if no element matches at any level.
+ * - To override the renderer for a specific element type, wrap in `<TreeRouterMapping mapping={…}>`.
+ */
+export function TreeRouter({ tree, fallback, ...meta }: TreeRouterProps): ReactNode {
+	const { path, ...combined } = requireMetaURL(meta);
+
+	// Find a `TreeElement` matching the current URL meta path.
+	const element = resolveElementPath(tree, splitPath(path));
+
+	// We render either a mapped version of the tree element, or the fallback element.
+	const route = element ? <TreeRouterMapper path={path}>{element}</TreeRouterMapper> : fallback;
+	if (route !== undefined) return <MetaContext value={combined}>{route}</MetaContext>;
+	throw new NotFoundError("Tree route not found", { received: path });
+}

package/ui/tree/index.d.ts

@@ -1,5 +1,5 @@
 export * from "./TreeApp.js";
 export * from "./TreeCards.js";
 export * from "./TreeMenu.js";
-export * from "./TreePage.js";
+export * from "./TreeRouter.js";
 export * from "./TreeSidebar.js";

package/ui/tree/index.js

@@ -1,5 +1,5 @@
 export * from "./TreeApp.js";
 export * from "./TreeCards.js";
 export * from "./TreeMenu.js";
-export * from "./TreePage.js";
+export * from "./TreeRouter.js";
 export * from "./TreeSidebar.js";

package/ui/tree/index.ts

@@ -1,5 +1,5 @@
 export * from "./TreeApp.js";
 export * from "./TreeCards.js";
 export * from "./TreeMenu.js";
-export * from "./TreePage.js";
+export * from "./TreeRouter.js";
 export * from "./TreeSidebar.js";

package/ui/tree/TreePage.d.ts

@@ -1,24 +0,0 @@
-import type { ReactNode } from "react";
-import { type TreeElement } from "../../util/element.js";
-import { type AbsolutePath } from "../../util/path.js";
-/** Extras threaded through `TreePageMapper` to the page renderer — the site-root-relative path of the page. */
-interface TreePageExtras {
-    /** Site-root-relative URL path of the page being rendered. Each page forwards it to its child cards. */
-    readonly path: AbsolutePath;
-}
-/** Mapping + Mapper pair for tree pages — wrap children in `<TreePageMapping>` to override. */
-export declare const TreePageMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps<TreePageExtras>>, TreePageMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps<TreePageExtras>>;
-export interface TreePageProps {
-    readonly path?: AbsolutePath;
-    readonly tree: TreeElement;
-}
-/**
- * Resolve a URL path to a tree element and render it as a full page.
- * - Walks the tree by matching each path segment to a descendant's `key` (via `resolveElementPath()`).
- * - `/` renders the root itself; deeper paths render the matching descendant.
- * - `path` is the site-root-relative path (already stripped of any `APP_URL` subfolder by `<Router>`); it is threaded to the page renderer so child cards build correct hrefs.
- * - Throws `NotFoundError` if no element matches at any level.
- * - To override the renderer for a specific element type, wrap in `<TreePageMapping mapping={…}>`.
- */
-export declare function TreePage({ path, tree }: TreePageProps): ReactNode;
-export {};

package/ui/tree/TreePage.tsx

@@ -1,41 +0,0 @@
-import type { ReactNode } from "react";
-import { NotFoundError } from "../../error/RequestError.js";
-import { resolveElementPath, type TreeElement } from "../../util/element.js";
-import { type AbsolutePath, splitPath } from "../../util/path.js";
-import { DirectoryPage } from "../docs/DirectoryPage.js";
-import { DocumentationPage } from "../docs/DocumentationPage.js";
-import { FilePage } from "../docs/FilePage.js";
-import { createMapper } from "../misc/Mapper.js";
-
-/** Extras threaded through `TreePageMapper` to the page renderer — the site-root-relative path of the page. */
-interface TreePageExtras {
-	/** Site-root-relative URL path of the page being rendered. Each page forwards it to its child cards. */
-	readonly path: AbsolutePath;
-}
-
-/** Mapping + Mapper pair for tree pages — wrap children in `<TreePageMapping>` to override. */
-export const [TreePageMapping, TreePageMapper] = createMapper<TreePageExtras>({
-	"tree-directory": DirectoryPage,
-	"tree-file": FilePage,
-	"tree-documentation": DocumentationPage,
-});
-
-export interface TreePageProps {
-	readonly path?: AbsolutePath;
-	readonly tree: TreeElement;
-}
-
-/**
- * Resolve a URL path to a tree element and render it as a full page.
- * - Walks the tree by matching each path segment to a descendant's `key` (via `resolveElementPath()`).
- * - `/` renders the root itself; deeper paths render the matching descendant.
- * - `path` is the site-root-relative path (already stripped of any `APP_URL` subfolder by `<Router>`); it is threaded to the page renderer so child cards build correct hrefs.
- * - Throws `NotFoundError` if no element matches at any level.
- * - To override the renderer for a specific element type, wrap in `<TreePageMapping mapping={…}>`.
- */
-export function TreePage({ path = "/", tree }: TreePageProps): ReactNode {
-	const segments = splitPath(path);
-	const element = resolveElementPath(tree, segments);
-	if (!element) throw new NotFoundError("Element not found", { received: path });
-	return <TreePageMapper path={path}>{element}</TreePageMapper>;
-}