@waveso/docs 0.1.0

package/dist/react/markdown-components.d.ts

@@ -0,0 +1,84 @@
+import { CalloutProps } from "./callout.js";
+import { YouTubeProps } from "./youtube.js";
+import { ComponentProps, ComponentType, JSX, ReactNode } from "react";
+//#region src/react/markdown-components.d.ts
+/**
+ * The component map handed to `hast-util-to-jsx-runtime`.
+ *
+ * Deliberately not that package's own `Components` type. `Components` is keyed
+ * by `keyof JSX.IntrinsicElements` resolved from the *global* `JSX` namespace,
+ * which React 19 no longer declares — so under this repo's config it collapses
+ * to a `string`-keyed map of `any`, and elsewhere it rejects the custom tag
+ * names our pipeline emits (`callout`, `youtube`). Keying off `React.JSX`
+ * explicitly gives real prop types in both worlds and room for our own tags.
+ *
+ * Note the absence of `node`: {@link DocContent} renders with `passNode: false`,
+ * so a component here can spread its props onto a DOM element without leaking
+ * `node="[object Object]"` into the HTML.
+ */
+type MarkdownComponents = { [Tag in keyof JSX.IntrinsicElements]?: ComponentType<JSX.IntrinsicElements[Tag]>; } & {
+  /** `<callout type="warning">`, emitted from `> [!WARNING]`. */
+  callout?: ComponentType<CalloutProps>;
+  /** `<youtube id="...">`, emitted from a bare YouTube URL. */
+  youtube?: ComponentType<YouTubeProps>;
+};
+/**
+ * Props the injected link component must accept.
+ *
+ * Shaped to be satisfied by `next/link` without this package ever importing it
+ * — importing `next/*` here would couple the React layer to Next, and keeping
+ * it host-agnostic is half the point of the package. Do not "simplify" this
+ * by importing `next/link` directly.
+ */
+interface DocsLinkProps extends Omit<ComponentProps<'a'>, 'href' | 'ref'> {
+  href: string;
+  /** Honoured by `next/link`; ignored by a plain `<a>`. */
+  prefetch?: boolean | undefined;
+  children?: ReactNode;
+}
+/** A `next/link`-compatible component. */
+type DocsLinkComponent = ComponentType<DocsLinkProps>;
+/**
+ * Props the injected image component must accept.
+ *
+ * `width`/`height` are required because `next/image` refuses to render without
+ * them (short of `fill`); they come from the build-time `ImageResolver`.
+ */
+interface DocsImageProps {
+  src: string;
+  alt: string;
+  width: number;
+  height: number;
+  title?: string | undefined;
+  className?: string | undefined;
+  sizes?: string | undefined;
+  loading?: 'eager' | 'lazy' | undefined;
+}
+/** A `next/image`-compatible component. */
+type DocsImageComponent = ComponentType<DocsImageProps>;
+interface MarkdownComponentsOptions {
+  /** Client-side router link, e.g. `next/link`. Falls back to `<a>`. */
+  Link?: DocsLinkComponent | undefined;
+  /** Optimising image component, e.g. `next/image`. Falls back to `<img>`. */
+  Image?: DocsImageComponent | undefined;
+}
+/**
+ * Build the default component map, optionally injecting host-specific link and
+ * image components.
+ *
+ * Call it once at module scope: every call returns fresh component identities,
+ * and remounting the whole document on each render is not what you want.
+ *
+ * @example
+ * ```tsx
+ * // Next.js
+ * const components = createMarkdownComponents({ Link, Image });
+ * // Any other host — plain <a> and <img>
+ * const components = createMarkdownComponents();
+ * ```
+ */
+declare function createMarkdownComponents(options?: MarkdownComponentsOptions): MarkdownComponents;
+/** The map used when a caller supplies none. Plain `<a>` and `<img>`. */
+declare const defaultMarkdownComponents: MarkdownComponents;
+//#endregion
+export { DocsImageComponent, DocsImageProps, DocsLinkComponent, DocsLinkProps, MarkdownComponents, MarkdownComponentsOptions, createMarkdownComponents, defaultMarkdownComponents };

package/dist/react/markdown-components.js

@@ -0,0 +1,122 @@
+import { Callout } from "./callout.js";
+import { YouTube } from "./youtube.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/markdown-components.tsx
+/** Schemes we send to a new tab. `mailto:`/`tel:` are left to the OS. */
+const HTTP_SCHEME = /^https?:\/\//i;
+/** Any URL with a scheme, or protocol-relative. */
+const ABSOLUTE_URL = /^([a-z][a-z0-9+.-]*:|\/\/)/i;
+function joinClassNames(...values) {
+	const joined = values.filter(Boolean).join(" ");
+	return joined === "" ? void 0 : joined;
+}
+function toDimension(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+}
+function createAnchor(Link) {
+	return function MarkdownAnchor({ href, children, ...rest }) {
+		if (href === void 0) return /* @__PURE__ */ jsx("a", {
+			...rest,
+			children
+		});
+		if (HTTP_SCHEME.test(href) || href.startsWith("//")) return /* @__PURE__ */ jsxs("a", {
+			...rest,
+			href,
+			target: "_blank",
+			rel: "noopener noreferrer",
+			children: [children, /* @__PURE__ */ jsx("span", {
+				className: "wave-docs-sr-only",
+				children: " (opens in a new tab)"
+			})]
+		});
+		if (href.startsWith("#") || ABSOLUTE_URL.test(href) || Link === void 0) return /* @__PURE__ */ jsx("a", {
+			...rest,
+			href,
+			children
+		});
+		return /* @__PURE__ */ jsx(Link, {
+			...rest,
+			href,
+			children
+		});
+	};
+}
+function createImage(Image) {
+	return function MarkdownImage({ src, alt, width, height, title, className, ...rest }) {
+		const resolvedWidth = toDimension(width);
+		const resolvedHeight = toDimension(height);
+		if (Image !== void 0 && typeof src === "string" && resolvedWidth !== void 0 && resolvedHeight !== void 0) return /* @__PURE__ */ jsx(Image, {
+			src,
+			alt: alt ?? "",
+			width: resolvedWidth,
+			height: resolvedHeight,
+			title,
+			className: joinClassNames("wave-docs-image", className),
+			loading: "lazy"
+		});
+		return /* @__PURE__ */ jsx("img", {
+			...rest,
+			src,
+			alt: alt ?? "",
+			width,
+			height,
+			title,
+			className: joinClassNames("wave-docs-image", className),
+			loading: "lazy",
+			decoding: "async"
+		});
+	};
+}
+/**
+* A table wrapped in its own scroll container.
+*
+* A wide table cannot be made scrollable by CSS alone without an extra
+* element, and a scroll container that is not focusable cannot be scrolled by
+* keyboard at all — hence the `tabIndex`, which is the documented exception to
+* "no tabindex on non-interactive elements", not a violation of it. A labelled
+* `<section>` is a `region` landmark, so the tab stop announces itself instead
+* of being a mystery stop in the tab order.
+*/
+function MarkdownTable({ className, ...rest }) {
+	return /* @__PURE__ */ jsx("section", {
+		className: "wave-docs-table-scroll",
+		"aria-label": "Table",
+		tabIndex: 0,
+		children: /* @__PURE__ */ jsx("table", {
+			...rest,
+			className: joinClassNames("wave-docs-table", className)
+		})
+	});
+}
+/**
+* Build the default component map, optionally injecting host-specific link and
+* image components.
+*
+* Call it once at module scope: every call returns fresh component identities,
+* and remounting the whole document on each render is not what you want.
+*
+* @example
+* ```tsx
+* // Next.js
+* const components = createMarkdownComponents({ Link, Image });
+* // Any other host — plain <a> and <img>
+* const components = createMarkdownComponents();
+* ```
+*/
+function createMarkdownComponents(options = {}) {
+	return {
+		a: createAnchor(options.Link),
+		img: createImage(options.Image),
+		table: MarkdownTable,
+		callout: Callout,
+		youtube: YouTube
+	};
+}
+/** The map used when a caller supplies none. Plain `<a>` and `<img>`. */
+const defaultMarkdownComponents = createMarkdownComponents();
+//#endregion
+export { createMarkdownComponents, defaultMarkdownComponents };

package/dist/react/search-dialog.d.ts

@@ -0,0 +1,41 @@
+import { DocsLinkComponent } from "./markdown-components.js";
+import { ReactNode } from "react";
+//#region src/react/search-dialog.d.ts
+interface SearchDialogProps {
+  /**
+   * URL of the serialised index, e.g. `/search-index.json`. Whatever
+   * `writeSearchIndex` wrote, served as a static asset.
+   */
+  indexUrl: string;
+  /**
+   * Router navigation for the selected result. Injected rather than imported
+   * so this component stays host-agnostic — `next/navigation`'s
+   * `useRouter().push`, a `react-router` navigate, or `location.assign`.
+   */
+  navigate: (href: string) => void;
+  /**
+   * Optional link component for results, e.g. `next/link`, so hovering a hit
+   * prefetches the page. Results fall back to a plain anchor.
+   */
+  Link?: DocsLinkComponent;
+  /** Trigger button label. Defaults to `'Search'`. */
+  triggerLabel?: string;
+  /** Input placeholder. Defaults to `'Search documentation'`. */
+  placeholder?: string;
+  /** Accessible name for the dialog. Defaults to `'Search documentation'`. */
+  dialogLabel?: string;
+  /** Maximum results rendered. Defaults to 8. */
+  maxResults?: number;
+  /** Input debounce in milliseconds. Defaults to 120. */
+  debounceMs?: number;
+}
+/**
+ * Search trigger plus its dialog.
+ *
+ * Render it once, wherever the trigger belongs — the dialog itself is
+ * portalled to `document.body`, so a navbar's stacking context cannot trap
+ * it behind the page.
+ */
+declare function SearchDialog({ indexUrl, navigate, Link, triggerLabel, placeholder, dialogLabel, maxResults, debounceMs }: SearchDialogProps): ReactNode;
+//#endregion
+export { SearchDialog, SearchDialogProps };

package/dist/react/search-dialog.js

@@ -0,0 +1,404 @@
+"use client";
+import { SEARCH_INDEX_OPTIONS } from "../search-options.js";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { createPortal } from "react-dom";
+//#region src/react/search-dialog.tsx
+/**
+* Tab stops inside the dialog. Every clause excludes `tabindex="-1"`: the
+* result links are anchors *and* are deliberately out of the tab order, and a
+* trap that counted them would let Tab escape the dialog at the last real
+* control.
+*/
+const FOCUSABLE_SELECTOR = [
+	"a[href]",
+	"button:not([disabled])",
+	"input:not([disabled])",
+	"select:not([disabled])",
+	"textarea:not([disabled])",
+	"[tabindex]"
+].map((selector) => `${selector}:not([tabindex="-1"])`).join(", ");
+/**
+* Search trigger plus its dialog.
+*
+* Render it once, wherever the trigger belongs — the dialog itself is
+* portalled to `document.body`, so a navbar's stacking context cannot trap
+* it behind the page.
+*/
+function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", placeholder = "Search documentation", dialogLabel = "Search documentation", maxResults = 8, debounceMs = 120 }) {
+	const [isOpen, setIsOpen] = useState(false);
+	const [query, setQuery] = useState("");
+	const [hits, setHits] = useState([]);
+	const [activeIndex, setActiveIndex] = useState(0);
+	const [status, setStatus] = useState("idle");
+	const [shortcutHint, setShortcutHint] = useState("");
+	const dialogRef = useRef(null);
+	const triggerRef = useRef(null);
+	const inputRef = useRef(null);
+	const listRef = useRef(null);
+	const returnFocusRef = useRef(null);
+	const indexRef = useRef(null);
+	/** Whether the dialog has ever been open. See the focus effect below. */
+	const hasOpenedRef = useRef(false);
+	const baseId = useId();
+	const listId = `${baseId}-results`;
+	const optionId = (index) => `${baseId}-option-${index}`;
+	/** Load the index at most once; a failure clears the cache so a retry can. */
+	const ensureIndex = useCallback(() => {
+		let pending = indexRef.current;
+		if (pending === null) {
+			pending = loadIndex(indexUrl).catch((error) => {
+				indexRef.current = null;
+				throw error;
+			});
+			indexRef.current = pending;
+		}
+		return pending;
+	}, [indexUrl]);
+	const warmIndex = useCallback(() => {
+		if (indexRef.current !== null) return;
+		setStatus("loading");
+		ensureIndex().then(() => setStatus("ready"), () => setStatus("error"));
+	}, [ensureIndex]);
+	const openDialog = useCallback(() => {
+		returnFocusRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+		setIsOpen(true);
+		warmIndex();
+	}, [warmIndex]);
+	const closeDialog = useCallback(() => {
+		setIsOpen(false);
+	}, []);
+	useEffect(() => {
+		function handleShortcut(event) {
+			if (!(event.metaKey || event.ctrlKey)) return;
+			if (event.key.toLowerCase() !== "k") return;
+			event.preventDefault();
+			if (isOpen) closeDialog();
+			else openDialog();
+		}
+		document.addEventListener("keydown", handleShortcut);
+		return () => document.removeEventListener("keydown", handleShortcut);
+	}, [
+		isOpen,
+		openDialog,
+		closeDialog
+	]);
+	useEffect(() => {
+		const isApple = /mac|iphone|ipad|ipod/i.test(navigator.userAgent);
+		setShortcutHint(isApple ? "⌘K" : "Ctrl K");
+	}, []);
+	useEffect(() => {
+		if (isOpen) {
+			hasOpenedRef.current = true;
+			inputRef.current?.focus();
+			return;
+		}
+		if (!hasOpenedRef.current) return;
+		const previous = returnFocusRef.current;
+		returnFocusRef.current = null;
+		(previous !== null && previous !== document.body && previous.isConnected ? previous : triggerRef.current)?.focus();
+	}, [isOpen]);
+	useEffect(() => {
+		if (!isOpen) return;
+		const { body } = document;
+		const previousOverflow = body.style.overflow;
+		body.style.overflow = "hidden";
+		return () => {
+			body.style.overflow = previousOverflow;
+		};
+	}, [isOpen]);
+	useEffect(() => {
+		if (isOpen) return;
+		setQuery("");
+		setHits([]);
+		setActiveIndex(0);
+	}, [isOpen]);
+	useEffect(() => {
+		const trimmed = query.trim();
+		if (trimmed === "") {
+			setHits([]);
+			setActiveIndex(0);
+			return;
+		}
+		let isCancelled = false;
+		const timer = setTimeout(() => {
+			ensureIndex().then((index) => {
+				if (isCancelled) return;
+				setStatus("ready");
+				setHits(index.search(trimmed).slice(0, maxResults).map(toSearchHit).filter(isSearchHit));
+				setActiveIndex(0);
+			}, () => {
+				if (!isCancelled) setStatus("error");
+			});
+		}, debounceMs);
+		return () => {
+			isCancelled = true;
+			clearTimeout(timer);
+		};
+	}, [
+		query,
+		ensureIndex,
+		maxResults,
+		debounceMs
+	]);
+	useEffect(() => {
+		if (hits.length === 0) return;
+		(listRef.current?.querySelector(`#${CSS.escape(`${baseId}-option-${activeIndex}`)}`))?.scrollIntoView({ block: "nearest" });
+	}, [
+		activeIndex,
+		hits,
+		baseId
+	]);
+	const selectHit = useCallback((hit) => {
+		closeDialog();
+		navigate(hit.href);
+	}, [closeDialog, navigate]);
+	function handleDialogKeyDown(event) {
+		if (event.key === "Escape") {
+			event.preventDefault();
+			event.stopPropagation();
+			closeDialog();
+			return;
+		}
+		if (event.key === "Tab") {
+			trapFocus(dialogRef.current, event);
+			return;
+		}
+		if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+			if (hits.length === 0) return;
+			event.preventDefault();
+			const delta = event.key === "ArrowDown" ? 1 : -1;
+			setActiveIndex((index) => (index + delta + hits.length) % hits.length);
+			return;
+		}
+		if (event.key === "Enter") {
+			const hit = hits[activeIndex];
+			if (hit === void 0) return;
+			event.preventDefault();
+			selectHit(hit);
+		}
+	}
+	const activeHit = hits[activeIndex];
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("button", {
+		type: "button",
+		ref: triggerRef,
+		className: "wave-docs-search-trigger",
+		"aria-label": triggerLabel,
+		"aria-keyshortcuts": "Meta+K Control+K",
+		onClick: openDialog,
+		onPointerEnter: warmIndex,
+		onFocus: warmIndex,
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "wave-docs-search-trigger-label",
+			children: triggerLabel
+		}), shortcutHint === "" ? null : /* @__PURE__ */ jsx("kbd", {
+			className: "wave-docs-search-trigger-kbd",
+			children: shortcutHint
+		})]
+	}), isOpen ? createPortal(/* @__PURE__ */ jsx("div", {
+		className: "wave-docs-search-backdrop",
+		onMouseDown: (event) => {
+			if (event.target === event.currentTarget) closeDialog();
+		},
+		children: /* @__PURE__ */ jsxs("div", {
+			ref: dialogRef,
+			className: "wave-docs-search-dialog",
+			role: "dialog",
+			"aria-modal": "true",
+			"aria-label": dialogLabel,
+			onKeyDown: handleDialogKeyDown,
+			children: [
+				/* @__PURE__ */ jsxs("div", {
+					className: "wave-docs-search-input-row",
+					children: [/* @__PURE__ */ jsx("input", {
+						ref: inputRef,
+						className: "wave-docs-search-input",
+						type: "text",
+						role: "combobox",
+						"aria-label": dialogLabel,
+						"aria-expanded": hits.length > 0,
+						"aria-controls": listId,
+						"aria-autocomplete": "list",
+						...activeHit === void 0 ? {} : { "aria-activedescendant": optionId(activeIndex) },
+						placeholder,
+						value: query,
+						onChange: (event) => setQuery(event.target.value),
+						autoComplete: "off",
+						autoCorrect: "off",
+						spellCheck: false
+					}), /* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: "wave-docs-search-close",
+						onClick: closeDialog,
+						children: "Close"
+					})]
+				}),
+				/* @__PURE__ */ jsx("div", {
+					ref: listRef,
+					id: listId,
+					className: "wave-docs-search-results",
+					role: "listbox",
+					"aria-label": dialogLabel,
+					children: hits.map((hit, index) => /* @__PURE__ */ jsx(SearchResultOption, {
+						hit,
+						id: optionId(index),
+						isActive: index === activeIndex,
+						onActivate: () => setActiveIndex(index),
+						onSelect: selectHit,
+						...Link === void 0 ? {} : { Link }
+					}, hit.id))
+				}),
+				/* @__PURE__ */ jsx(SearchStatus, {
+					status,
+					query: query.trim(),
+					hitCount: hits.length
+				})
+			]
+		})
+	}), document.body) : null] });
+}
+/** One result row: a real link, so middle-click and "open in new tab" work. */
+function SearchResultOption({ hit, id, isActive, onActivate, onSelect, Link }) {
+	function handleClick(event) {
+		if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+		event.preventDefault();
+		onSelect(hit);
+	}
+	const trail = toBreadcrumbs(hit);
+	const body = /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+		className: "wave-docs-search-result-heading",
+		children: hit.heading
+	}), trail.length === 0 ? null : /* @__PURE__ */ jsx("span", {
+		className: "wave-docs-search-result-breadcrumb",
+		children: trail.map((crumb, index) => /* @__PURE__ */ jsxs("span", {
+			className: "wave-docs-search-result-crumb",
+			children: [index === 0 ? null : /* @__PURE__ */ jsx("span", {
+				className: "wave-docs-search-result-crumb-separator",
+				"aria-hidden": "true",
+				children: "›"
+			}), crumb.text]
+		}, crumb.key))
+	})] });
+	return /* @__PURE__ */ jsx("div", {
+		id,
+		className: isActive ? "wave-docs-search-result wave-docs-search-result-active" : "wave-docs-search-result",
+		role: "option",
+		"aria-selected": isActive,
+		"aria-label": [hit.heading, ...trail.map((crumb) => crumb.text)].join(", "),
+		tabIndex: -1,
+		onPointerMove: onActivate,
+		children: Link === void 0 ? /* @__PURE__ */ jsx("a", {
+			className: "wave-docs-search-result-link",
+			href: hit.href,
+			tabIndex: -1,
+			onClick: handleClick,
+			children: body
+		}) : /* @__PURE__ */ jsx(Link, {
+			className: "wave-docs-search-result-link",
+			href: hit.href,
+			tabIndex: -1,
+			onClick: handleClick,
+			children: body
+		})
+	});
+}
+/** Loading, failure and empty states, plus a live region for hit counts. */
+function SearchStatus({ status, query, hitCount }) {
+	let message = null;
+	let modifier = "";
+	if (status === "error") {
+		message = "Search is unavailable right now. Try reloading the page.";
+		modifier = " wave-docs-search-status-error";
+	} else if (query === "") {
+		message = "Start typing to search the documentation.";
+		modifier = " wave-docs-search-status-hint";
+	} else if (status !== "ready") {
+		message = "Loading the search index…";
+		modifier = " wave-docs-search-status-loading";
+	} else if (hitCount === 0) {
+		message = `No results for “${query}”.`;
+		modifier = " wave-docs-search-status-empty";
+	}
+	return /* @__PURE__ */ jsxs(Fragment, { children: [message === null ? null : /* @__PURE__ */ jsx("p", {
+		className: `wave-docs-search-status${modifier}`,
+		children: message
+	}), /* @__PURE__ */ jsx("p", {
+		className: "wave-docs-search-announcer",
+		role: "status",
+		"aria-live": "polite",
+		children: query === "" || status !== "ready" ? "" : `${hitCount} ${hitCount === 1 ? "result" : "results"}`
+	})] });
+}
+/**
+* Fetch and deserialise the index.
+*
+* `loadJSONAsync` yields between chunks so deserialising a large index does
+* not freeze the frame the dialog just opened in.
+*/
+async function loadIndex(url) {
+	const [{ default: MiniSearchClass }, response] = await Promise.all([import("minisearch"), fetch(url)]);
+	if (!response.ok) throw new Error(`Failed to load the search index from ${url} (HTTP ${response.status}).`);
+	return MiniSearchClass.loadJSONAsync(await response.text(), SEARCH_INDEX_OPTIONS);
+}
+/**
+* Narrow one MiniSearch result. Its stored fields are untyped by design, and
+* an index built without `storeFields` yields rows with nothing to render —
+* those are dropped rather than rendered blank.
+*/
+function toSearchHit(result) {
+	if (typeof result !== "object" || result === null) return void 0;
+	const { id, title, heading, href, ancestors } = result;
+	if (typeof id !== "string") return void 0;
+	if (typeof title !== "string") return void 0;
+	if (typeof heading !== "string") return void 0;
+	if (typeof href !== "string") return void 0;
+	return {
+		id,
+		title,
+		heading,
+		href,
+		ancestors: Array.isArray(ancestors) ? ancestors.filter((entry) => typeof entry === "string") : []
+	};
+}
+function isSearchHit(hit) {
+	return hit !== void 0;
+}
+/**
+* Page title first, then the ancestor headings: `ancestors` deliberately excludes
+* the page title so the index does not carry it twice.
+*
+* A page's lead record carries `heading === title` and no ancestors (see
+* `extractSearchRecords`), so its trail would be the one string already printed
+* above it. "Installation" over "Installation" is not a path, it is a bug that
+* reads as a rendering glitch — such a hit gets no trail at all.
+*/
+function toBreadcrumbs(hit) {
+	if (hit.ancestors.length === 0 && hit.heading === hit.title) return [];
+	let trail = "";
+	return [hit.title, ...hit.ancestors].map((text) => {
+		trail = trail === "" ? text : `${trail}/${text}`;
+		return {
+			key: trail,
+			text
+		};
+	});
+}
+function trapFocus(root, event) {
+	if (root === null) return;
+	const focusable = root.querySelectorAll(FOCUSABLE_SELECTOR);
+	const first = focusable[0];
+	const last = focusable[focusable.length - 1];
+	if (first === void 0 || last === void 0) {
+		event.preventDefault();
+		return;
+	}
+	if (event.shiftKey && document.activeElement === first) {
+		event.preventDefault();
+		last.focus();
+	} else if (!event.shiftKey && document.activeElement === last) {
+		event.preventDefault();
+		first.focus();
+	}
+}
+//#endregion
+export { SearchDialog };

package/dist/react/sidebar.d.ts

@@ -0,0 +1,29 @@
+import { DocNavNode } from "../types.js";
+import { DocsLinkComponent } from "./markdown-components.js";
+import { ReactNode } from "react";
+//#region src/react/sidebar.d.ts
+interface DocsSidebarProps {
+  /** The tree from `@waveso/docs/source`. */
+  nav: DocNavNode[];
+  /**
+   * Current route, used for `aria-current` and for deciding which groups open.
+   * Passed in rather than read from `next/navigation` so this component stays
+   * host-agnostic and testable without a router.
+   */
+  pathname: string;
+  /** Client-side router link, e.g. `next/link`. Falls back to `<a>`. */
+  Link?: DocsLinkComponent | undefined;
+  /** Accessible name for the landmark. Distinguish multiple navs on a page. */
+  label?: string | undefined;
+  className?: string | undefined;
+}
+/**
+ * The docs navigation tree.
+ *
+ * Prefetch is off by default on the injected link. A full-tree sidebar on a
+ * few hundred pages otherwise asks Next to prefetch every route in it —
+ * ~1.8 KB brotli each, all of it wasted on the routes nobody clicks.
+ */
+declare function DocsSidebar({ nav, pathname, Link, label, className }: DocsSidebarProps): ReactNode;
+//#endregion
+export { DocsSidebar, DocsSidebarProps };