@waveso/docs 0.2.0 → 0.4.0

package/dist/react/next-nav.js

@@ -0,0 +1,32 @@
+"use client";
+import { wrapNextLink } from "./next-link.js";
+import { DocsNav } from "./nav.js";
+import { jsx } from "react/jsx-runtime";
+import NextLink from "next/link";
+import { usePathname } from "next/navigation";
+//#region src/react/next-nav.tsx
+/**
+* {@link DocsNav}, wired to Next's router.
+*
+* Private, and the **only** module in `src/react/` that imports
+* `next/navigation` — named so that is obvious from the file list. Everything
+* else in here takes `pathname` and `Link` as props, which is what lets the
+* components be tested without mounting a router and reused outside Next.
+*
+* The split is not ceremony: `usePathname` is why the consumer used to have to
+* hand-write a `'use client'` wrapper of their own, and deleting that file from
+* the README is most of what `docs.Layout` is for.
+*/
+/** Module scope: a fresh identity here remounts every nav link on every render. */
+const Link = wrapNextLink(NextLink);
+function DocsNextNav({ nav, label, closeLabel }) {
+	return /* @__PURE__ */ jsx(DocsNav, {
+		nav,
+		pathname: usePathname(),
+		Link,
+		...label === void 0 ? {} : { label },
+		...closeLabel === void 0 ? {} : { closeLabel }
+	});
+}
+//#endregion
+export { DocsNextNav };

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

@@ -0,0 +1,22 @@
+import { SearchDialogProps } from "./search-dialog.js";
+import { ReactNode } from "react";
+//#region src/react/next-search.d.ts
+/**
+ * Everything `SearchDialog` takes except the two things Next answers for you.
+ *
+ * `indexUrl` stays required, and `docs.searchIndexUrl` is the only value
+ * anyone should pass: defaulting it to `/search-index.json` would be wrong
+ * under every non-root `basePath`, and wrong as a 404 the reader hits and the
+ * author never sees.
+ */
+type DocsSearchProps = Omit<SearchDialogProps, 'navigate' | 'Link'>;
+/**
+ * Search trigger and dialog for a Next application.
+ *
+ * `next/link` is passed through rather than left to the plain-anchor fallback,
+ * so hovering a result prefetches the page it points at — which is most of why
+ * a hit feels instant when you press Enter.
+ */
+declare function DocsSearch(props: DocsSearchProps): ReactNode;
+//#endregion
+export { DocsSearch, DocsSearchProps };

package/dist/react/next-search.js

@@ -0,0 +1,52 @@
+"use client";
+import { wrapNextLink } from "./next-link.js";
+import { SearchDialog } from "./search-dialog.js";
+import { useCallback } from "react";
+import { jsx } from "react/jsx-runtime";
+import NextLink from "next/link";
+import { useRouter } from "next/navigation";
+//#region src/react/next-search.tsx
+/**
+* {@link SearchDialog}, wired to Next's router and `next/link`.
+*
+* `SearchDialog` takes `navigate` and `Link` as props so it stays
+* host-agnostic, and that seam is why its own tests are worth having — they
+* assert behaviour against a stub router rather than mounting Next. But this
+* package is a Next adapter, so in practice every consumer wrote the same
+* fifteen-line `'use client'` wrapper around `useRouter().push` and
+* `next/link`, and the ones who skipped `Link` lost hover prefetching on
+* every result without anything telling them.
+*
+* So it ships. The same bargain `createDocsRoute` already strikes on the
+* server, where `next/link` and `next/image` are wired by default and
+* overridable through `components`.
+*
+* ```tsx
+* // app/docs/layout.tsx — a Server Component; this file carries the boundary
+* import { DocsSearch } from '@waveso/docs/react/next-search';
+* import { docs } from '@/lib/docs';
+*
+* <DocsSearch indexUrl={docs.searchIndexUrl} />
+* ```
+*/
+const Link = wrapNextLink(NextLink);
+/**
+* Search trigger and dialog for a Next application.
+*
+* `next/link` is passed through rather than left to the plain-anchor fallback,
+* so hovering a result prefetches the page it points at — which is most of why
+* a hit feels instant when you press Enter.
+*/
+function DocsSearch(props) {
+	const router = useRouter();
+	const navigate = useCallback((href) => {
+		router.push(href);
+	}, [router]);
+	return /* @__PURE__ */ jsx(SearchDialog, {
+		...props,
+		navigate,
+		Link
+	});
+}
+//#endregion
+export { DocsSearch };

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

@@ -26,8 +26,39 @@ interface SearchDialogProps {
   placeholder?: string | undefined;
   /** Accessible name for the dialog. Defaults to `'Search documentation'`. */
   dialogLabel?: string | undefined;
-  /** Maximum results rendered. Defaults to 8. */
-  maxResults?: number | undefined;
+  /**
+   * How many results to render at a time. Defaults to 20.
+   *
+   * ⚠️ NOT A CAP. Every match is reachable — the list renders this many, then
+   * another `pageSize` each time the reader scrolls near the end, so the DOM
+   * stays bounded without anything being withheld.
+   *
+   * This was `maxResults`, and it was a hard ceiling of 8. On a *six-page*
+   * site "docs" matches 18, so ten results simply could not be reached, and
+   * the live region announced "8 results" — not a smaller truth but a false
+   * one. The ceiling was justified by a claim nobody had measured, and the
+   * measurement did not support it: on a 300-page corpus (2,100 records) a
+   * query costs 1.3–3.0 ms and rendering *every* row costs 40 ms, 128 ms at
+   * 4x CPU throttle. Paging exists to keep that worst case from ever being
+   * reached, not because the search cannot find things.
+   */
+  pageSize?: number | undefined;
+  /**
+   * Shortest query that runs. Defaults to 2.
+   *
+   * A single character is not a query — measured on this package's own docs,
+   * "a" matches 100% of the corpus, "i" 97%, "s" 93%. Answering those wastes a
+   * render and, worse, teaches a reader mid-word that search returns noise.
+   *
+   * ⚠️ TWO, NOT THREE, AND THE DIFFERENCE MATTERS ON A DOCS SITE. Three would
+   * refuse `ts`, `js`, `id`, `h1`, `px` — every one a real query here, and each
+   * one selective: 10%, 17%, 14%, 3%, 0%. The noise is at one character, so
+   * that is where the floor goes.
+   *
+   * A word like `is` still matches 83%; that is a stopword problem rather than
+   * a length one, and `miniSearchOptions.processTerm` is the tool for it.
+   */
+  minQueryLength?: number | undefined;
   /** Input debounce in milliseconds. Defaults to 120. */
   debounceMs?: number | undefined;
   /** Extra class names for the trigger button, e.g. a navbar's own layout. */
@@ -35,15 +66,27 @@ interface SearchDialogProps {
   /**
    * Overrides applied through `mergeSearchOptions` when the index is
    * deserialised — the escape hatch for tokenisation, `processTerm` and the
-   * query defaults (`fuzzy`, `prefix`, `combineWith`, `boost`) without waiting
-   * on a release of this package.
+   * query defaults, without waiting on a release of this package.
+   *
+   * MiniSearch's own name for the query defaults is `searchOptions`, so they
+   * nest one level down:
+   *
+   * ```tsx
+   * <DocsSearch miniSearchOptions={{ searchOptions: { fuzzy: 0.1 } }} />
+   * ```
+   *
+   * That stutter is why this prop is not called `searchOptions` too. It was,
+   * and `searchOptions={{ fuzzy: 0.1 }}` reads so naturally that both README
+   * examples were written that way — neither compiled, and the flat form is
+   * not a runtime error either. It is a `fuzzy` MiniSearch never reads.
    *
-   * ⚠️ HAND THE IDENTICAL OVERRIDES TO `buildSearchIndex`. `tokenize` and
-   * `processTerm` decide how terms were written into the index; a client that
-   * splits differently from the build looks up terms that were never written
-   * and finds nothing, silently.
+   * ⚠️ HAND THE IDENTICAL OVERRIDES TO THE BUILD — `createDocsRoute`'s
+   * `miniSearchOptions`, or `buildSearchIndex`'s second argument. `tokenize`
+   * and `processTerm` decide how terms were written into the index; a client
+   * that splits differently from the build looks up terms that were never
+   * written and finds nothing, silently.
    */
-  searchOptions?: Partial<Options<SearchRecord>> | undefined;
+  miniSearchOptions?: Partial<Options<SearchRecord>> | undefined;
 }
 /**
  * Search trigger plus its dialog.
@@ -52,6 +95,6 @@ interface SearchDialogProps {
  * 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, className, searchOptions }: SearchDialogProps): ReactNode;
+declare function SearchDialog({ indexUrl, navigate, Link, triggerLabel, placeholder, dialogLabel, pageSize, minQueryLength, debounceMs, className, miniSearchOptions }: SearchDialogProps): ReactNode;
 //#endregion
 export { SearchDialog, SearchDialogProps };

package/dist/react/search-dialog.js

@@ -2,7 +2,7 @@
 import { docsError } from "../docs-error.js";
 import { mergeSearchOptions } from "../search-options.js";
 import { useCallback, useEffect, useId, useRef, useState } from "react";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { createPortal } from "react-dom";
 //#region src/react/search-dialog.tsx
 /**
@@ -26,10 +26,31 @@ const FOCUSABLE_SELECTOR = [
 * 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, className, searchOptions }) {
+function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", placeholder = "Search documentation", dialogLabel = "Search documentation", pageSize = 20, minQueryLength = 2, debounceMs = 120, className, miniSearchOptions }) {
 	const [isOpen, setIsOpen] = useState(false);
 	const [query, setQuery] = useState("");
 	const [hits, setHits] = useState([]);
+	/**
+	* How many of `hits` are rendered.
+	*
+	* `hits` holds every match; this is the window. It grows by `pageSize` when
+	* the reader scrolls near the end, and whenever the keyboard walks past it —
+	* so an option always exists for `aria-activedescendant` to point at.
+	*/
+	const [visibleCount, setVisibleCount] = useState(pageSize);
+	/**
+	* Whether the active option moved because of a key, rather than a pointer.
+	*
+	* ⚠️ THE SCROLL-INTO-VIEW BELOW MUST NOT RUN FOR A HOVER. Pointing at a row
+	* that is half-clipped by the top or bottom edge set the active index, which
+	* scrolled that row flush — moving the whole list under the cursor, which
+	* then landed on a different row. Measured: hovering the visible sliver of a
+	* clipped row jumped the list 28px.
+	*
+	* A ref rather than state: it records how the *last* change happened and must
+	* not itself cause a render.
+	*/
+	const movedByKeyboard = useRef(false);
 	const [activeIndex, setActiveIndex] = useState(0);
 	const [status, setStatus] = useState("idle");
 	const [shortcutHint, setShortcutHint] = useState("");
@@ -39,21 +60,21 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 	const listRef = useRef(null);
 	const returnFocusRef = useRef(null);
 	const indexCacheRef = useRef(/* @__PURE__ */ new Map());
-	const searchOptionsRef = useRef(searchOptions);
+	const miniSearchOptionsRef = useRef(miniSearchOptions);
 	/** 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}`;
 	useEffect(() => {
-		searchOptionsRef.current = searchOptions;
-	}, [searchOptions]);
+		miniSearchOptionsRef.current = miniSearchOptions;
+	}, [miniSearchOptions]);
 	/** Load each URL at most once; a failure evicts that key so a retry can. */
 	const ensureIndex = useCallback(() => {
 		const cache = indexCacheRef.current;
 		let pending = cache.get(indexUrl);
 		if (pending === void 0) {
-			pending = loadIndex(indexUrl, searchOptionsRef.current).catch((error) => {
+			pending = loadIndex(indexUrl, miniSearchOptionsRef.current).catch((error) => {
 				cache.delete(indexUrl);
 				throw error;
 			});
@@ -135,9 +156,10 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 	}, [isOpen]);
 	useEffect(() => {
 		const trimmed = query.trim();
-		if (trimmed === "") {
+		if (trimmed.length < minQueryLength) {
 			setHits([]);
 			setActiveIndex(0);
+			setVisibleCount(pageSize);
 			return;
 		}
 		let isCancelled = false;
@@ -145,8 +167,9 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 			ensureIndex().then((index) => {
 				if (isCancelled) return;
 				setStatus("ready");
-				setHits(index.search(trimmed).slice(0, maxResults).map(toSearchHit).filter(isSearchHit));
+				setHits(index.search(trimmed).map(toSearchHit).filter(isSearchHit));
 				setActiveIndex(0);
+				setVisibleCount(pageSize);
 			}, () => {
 				if (!isCancelled) setStatus("error");
 			});
@@ -158,11 +181,55 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 	}, [
 		query,
 		ensureIndex,
-		maxResults,
-		debounceMs
+		pageSize,
+		debounceMs,
+		minQueryLength
 	]);
+	/**
+	* Reveal another page when the reader nears the end of the list.
+	*
+	* A scroll handler rather than an `IntersectionObserver` on a sentinel: the
+	* scrollport is one element this component already holds a ref to, the test
+	* is one subtraction, and an observer would cost bytes on the largest client
+	* entry this package ships for no behaviour the reader can tell apart.
+	*
+	* `passive`, because this never calls `preventDefault` and a non-passive
+	* scroll listener blocks the compositor on every wheel event.
+	*
+	* No `isOpen` dependency, though the list does not exist while the dialog is
+	* closed: the effect returns early on a null ref, and `hits.length` going
+	* from 0 to N re-runs it — which happens after the list has mounted, because
+	* closing resets the query. The listener attaches exactly when there is
+	* something to scroll.
+	*/
+	useEffect(() => {
+		const list = listRef.current;
+		if (list === null || visibleCount >= hits.length) return;
+		const onScroll = () => {
+			if (list.scrollHeight - list.scrollTop - list.clientHeight < list.clientHeight) setVisibleCount((count) => Math.min(count + pageSize, hits.length));
+		};
+		list.addEventListener("scroll", onScroll, { passive: true });
+		return () => list.removeEventListener("scroll", onScroll);
+	}, [
+		visibleCount,
+		hits.length,
+		pageSize
+	]);
+	useEffect(() => {
+		if (activeIndex >= visibleCount) setVisibleCount(Math.min(activeIndex + 1, hits.length));
+	}, [
+		activeIndex,
+		visibleCount,
+		hits.length
+	]);
+	useEffect(() => {
+		const list = listRef.current;
+		if (list !== null && list.scrollTop !== 0) list.scrollTop = 0;
+	}, [hits]);
 	useEffect(() => {
 		if (hits.length === 0) return;
+		if (!movedByKeyboard.current) return;
+		movedByKeyboard.current = false;
 		(listRef.current?.querySelector(`#${CSS.escape(`${baseId}-option-${activeIndex}`)}`))?.scrollIntoView({ block: "nearest" });
 	}, [
 		activeIndex,
@@ -179,6 +246,7 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 			if (hits.length === 0) return;
 			event.preventDefault();
 			const delta = event.key === "ArrowDown" ? 1 : -1;
+			movedByKeyboard.current = true;
 			setActiveIndex((index) => (index + delta + hits.length) % hits.length);
 			return;
 		}
@@ -190,7 +258,7 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 		}
 	}
 	const activeHit = hits[activeIndex];
-	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("button", {
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs("button", {
 		type: "button",
 		ref: triggerRef,
 		className: ["wave-docs-search-trigger", className].filter(Boolean).join(" "),
@@ -250,11 +318,16 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 					className: "wave-docs-search-results",
 					role: "listbox",
 					"aria-label": dialogLabel,
-					children: hits.map((hit, index) => /* @__PURE__ */ jsx(SearchResultOption, {
+					children: hits.slice(0, visibleCount).map((hit, index) => /* @__PURE__ */ jsx(SearchResultOption, {
 						hit,
 						id: optionId(index),
 						isActive: index === activeIndex,
-						onActivate: () => setActiveIndex(index),
+						setSize: hits.length,
+						posInSet: index + 1,
+						onActivate: () => {
+							movedByKeyboard.current = false;
+							setActiveIndex(index);
+						},
 						onSelect: selectHit,
 						...Link === void 0 ? {} : { Link }
 					}, hit.id))
@@ -262,40 +335,36 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 				/* @__PURE__ */ jsx(SearchStatus, {
 					status,
 					query: query.trim(),
-					hitCount: hits.length
+					hitCount: hits.length,
+					minQueryLength
 				})
 			]
 		})
 	}), 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 SearchResultOption({ hit, id, isActive, setSize, posInSet, 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", {
+	const body = /* @__PURE__ */ jsxs(Fragment$1, { 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))
+	}), /* @__PURE__ */ jsx("span", {
+		className: "wave-docs-search-result-location",
+		"aria-hidden": "true",
+		children: toDisplayPath(hit.href)
 	})] });
 	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(", "),
+		"aria-setsize": setSize,
+		"aria-posinset": posInSet,
+		"aria-label": spokenName(hit),
 		tabIndex: -1,
 		onPointerMove: onActivate,
 		children: Link === void 0 ? /* @__PURE__ */ jsx("a", {
@@ -314,7 +383,7 @@ function SearchResultOption({ hit, id, isActive, onActivate, onSelect, Link }) {
 	});
 }
 /** Loading, failure and empty states, plus a live region for hit counts. */
-function SearchStatus({ status, query, hitCount }) {
+function SearchStatus({ status, query, hitCount, minQueryLength }) {
 	let message = null;
 	let modifier = "";
 	if (status === "error") {
@@ -323,6 +392,9 @@ function SearchStatus({ status, query, hitCount }) {
 	} else if (query === "") {
 		message = "Start typing to search the documentation.";
 		modifier = " wave-docs-search-status-hint";
+	} else if (query.length < minQueryLength) {
+		message = `Keep typing — ${minQueryLength} characters or more.`;
+		modifier = " wave-docs-search-status-hint";
 	} else if (status !== "ready") {
 		message = "Loading the search index…";
 		modifier = " wave-docs-search-status-loading";
@@ -330,7 +402,7 @@ function SearchStatus({ status, query, hitCount }) {
 		message = `No results for “${query}”.`;
 		modifier = " wave-docs-search-status-empty";
 	}
-	return /* @__PURE__ */ jsxs(Fragment, { children: [message === null ? null : /* @__PURE__ */ jsx("p", {
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [message === null ? null : /* @__PURE__ */ jsx("p", {
 		className: `wave-docs-search-status${modifier}`,
 		children: message
 	}), /* @__PURE__ */ jsx("p", {
@@ -348,7 +420,12 @@ function SearchStatus({ status, query, hitCount }) {
 */
 async function loadIndex(url, overrides) {
 	const [{ default: MiniSearchClass }, response] = await Promise.all([import("minisearch"), fetch(url)]);
-	if (!response.ok) throw docsError("search-index-unavailable", `Failed to load the search index from ${url} (HTTP ${response.status}).`);
+	if (!response.ok) throw docsError("search-index-unavailable", response.status === 404 ? `No search index at ${url}. Create the route that serves it:\n\n  // app${url}/route.ts — the whole file\n  import { docs } from '@/lib/docs';
+
+  export const GET = docs.searchIndex;
+  export const dynamic = 'force-static';
+
+Or pass \`search={false}\` to \`docs.Layout\` to hide the trigger.` : `Failed to load the search index from ${url} (HTTP ${response.status}).`);
 	return MiniSearchClass.loadJSONAsync(await response.text(), mergeSearchOptions(overrides));
 }
 /**
@@ -375,24 +452,47 @@ 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.
+* The route, without its anchor, for display only.
 *
-* 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.
+* ⚠️ THE ANCHOR IS NOISE HERE, AND ALMOST ALWAYS A REPEAT. A section's anchor
+* is slugged from its heading, so `/docs/styling#layout-tokens` under a row
+* whose first line already reads "Layout tokens" spends its width restating
+* it — and on a real site it is the part that pushes the line past the
+* ellipsis.
+*
+* What the line is for is "which page does this land on", and the path answers
+* that on its own. Two rows from the same page showing the same path is not
+* ambiguity: they *are* the same page, and their headings above say which part.
+*
+* Display only. `hit.href` keeps the anchor, so the link still deep-links to
+* the section — that is the whole point of section-scoped records.
 */
-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 toDisplayPath(href) {
+	const hash = href.indexOf("#");
+	return hash === -1 ? href : href.slice(0, hash);
+}
+/**
+* What a result is called when it is read aloud.
+*
+* Words, not the route the row displays. `/docs/styling#layout-tokens` is
+* punctuation to a screen reader — spelled out slash by slash — so the visible
+* line and the announced name deliberately carry the same fact in two forms:
+* the route for a sighted reader scanning for where a hit lands, and
+* "Layout tokens, Styling" for a listener.
+*
+* `ancestors` deliberately excludes the page title, so the page comes first
+* here and the enclosing headings follow, outermost first.
+*
+* A page's own record carries `heading === title` and no ancestors, so its name
+* is the heading alone — "Styling, Styling" is not a path, it is a stutter.
+*/
+function spokenName(hit) {
+	if (hit.ancestors.length === 0 && hit.heading === hit.title) return hit.heading;
+	return [
+		hit.heading,
+		hit.title,
+		...hit.ancestors
+	].join(", ");
 }
 function trapFocus(root, event) {
 	if (root === null) return;

package/dist/react/shell-labels.d.ts

@@ -0,0 +1,43 @@
+//#region src/react/shell-labels.d.ts
+/**
+ * Every user-visible string the shell renders that is not the reader's content.
+ *
+ * ⚠️ THERE ARE ONLY FIVE, AND THAT IS THE POINT. `docs.Layout` renders the
+ * whole chrome of a documentation site, and until this existed all five were
+ * hardcoded English with no way to reach them: `DocsNav` declared `label` and
+ * `closeLabel` props, documented them, defaulted them — and the layout that is
+ * the only thing rendering `DocsNav` never passed either, while `DocsLayoutProps`
+ * had no way to say them. Dead options that read as configuration.
+ *
+ * Private module, public type: `next.ts` re-exports {@link DocsLabels} as part
+ * of `DocsLayoutProps`, and this file exists so the Node adapter can name the
+ * type without importing a `'use client'` module for it.
+ *
+ * Not here: the search dialog's strings, which are reachable through
+ * `search={{ … }}`; and the sidebar's own `label`, which is public API on
+ * `DocsSidebar` for anyone composing a shell by hand. This is the set that had
+ * no route at all.
+ */
+interface DocsLabels {
+  /** The navigation landmark's accessible name. Default `'Documentation'`. */
+  nav?: string | undefined;
+  /** The header button that opens the drawer. Default `'Open navigation'`. */
+  openNav?: string | undefined;
+  /** The button that closes the drawer. Default `'Close navigation'`. */
+  closeNav?: string | undefined;
+  /** The skip link's visible text. Default `'Skip to content'`. */
+  skipToContent?: string | undefined;
+}
+/**
+ * The defaults, in one place.
+ *
+ * A `Required<DocsLabels>` rather than four `=` defaults spread across three
+ * components: the previous arrangement is how `DocsSidebar` came to default its
+ * landmark to `'Docs'` while `DocsNav` defaulted the same landmark to
+ * `'Documentation'` — two names for one region, depending on the viewport.
+ */
+declare const DEFAULT_DOCS_LABELS: Required<DocsLabels>;
+/** The given labels over the defaults, with `undefined` treated as unset. */
+declare function resolveLabels(labels: DocsLabels | undefined): Required<DocsLabels>;
+//#endregion
+export { DEFAULT_DOCS_LABELS, DocsLabels, resolveLabels };

package/dist/react/shell-labels.js

@@ -0,0 +1,27 @@
+//#region src/react/shell-labels.ts
+/**
+* The defaults, in one place.
+*
+* A `Required<DocsLabels>` rather than four `=` defaults spread across three
+* components: the previous arrangement is how `DocsSidebar` came to default its
+* landmark to `'Docs'` while `DocsNav` defaulted the same landmark to
+* `'Documentation'` — two names for one region, depending on the viewport.
+*/
+const DEFAULT_DOCS_LABELS = {
+	nav: "Documentation",
+	openNav: "Open navigation",
+	closeNav: "Close navigation",
+	skipToContent: "Skip to content"
+};
+/** The given labels over the defaults, with `undefined` treated as unset. */
+function resolveLabels(labels) {
+	if (labels === void 0) return DEFAULT_DOCS_LABELS;
+	return {
+		nav: labels.nav ?? DEFAULT_DOCS_LABELS.nav,
+		openNav: labels.openNav ?? DEFAULT_DOCS_LABELS.openNav,
+		closeNav: labels.closeNav ?? DEFAULT_DOCS_LABELS.closeNav,
+		skipToContent: labels.skipToContent ?? DEFAULT_DOCS_LABELS.skipToContent
+	};
+}
+//#endregion
+export { DEFAULT_DOCS_LABELS, resolveLabels };

package/dist/react/sidebar.d.ts

@@ -20,9 +20,44 @@ interface DocsSidebarProps {
 /**
  * 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.
+ * ## Prefetch
+ *
+ * Nearby links prefetch; the rest do not. Nearby means the list that directly
+ * contains the current page, plus the heading link of the group the reader is
+ * inside — 5 to 15 warm links on a real sidebar rather than 400 or none.
+ *
+ * ⚠️ THE PREVIOUS NOTE HERE WAS WRONG, AND THE RETRACTION IS THE POINT. It
+ * said prefetch was off because a full-tree sidebar otherwise asks Next to
+ * prefetch every route in it, ~1.8 KB brotli each. That reasoning is correct
+ * for the Pages Router and wrong for the App Router:
+ * `next/dist/client/app-dir/link.js` computes
+ * `const prefetchEnabled = prefetchProp !== false`, and BOTH the hover path
+ * and the touch path bail on it, while the IntersectionObserver is only
+ * registered when it is true. So `prefetch={false}` did not trade viewport
+ * prefetching for hover prefetching — it turned off both, and made every
+ * navigation from the most-clicked control in a docs site a cold RSC
+ * round-trip.
+ *
+ * ## The keyboard model, and why there is no `role="tree"`
+ *
+ * This is the **APG Disclosure Navigation** pattern: a list of links, with a
+ * button per collapsible group. Every link is an ordinary tab stop, Enter
+ * follows it, and the browser does all of it. There is no `tabindex`
+ * anywhere in here and no roving focus, deliberately.
+ *
+ * `role="tree"` is the tempting alternative and it is refused. It removes
+ * every link from the tab order in favour of a single roving tabstop, so a
+ * reader who tabs into the navigation can no longer tab through it; and it
+ * makes a screen reader announce "tree item, level 3" for what is, in every
+ * way that matters to the person hearing it, a link to a page. A docs sidebar
+ * is not a file explorer. `sidebar.test.tsx` asserts the absence of both, so
+ * the decision survives someone reaching for the aria pattern that sounds
+ * closest to "collapsible tree".
+ *
+ * ⚠️ AND IT IS UNOBSERVABLE IN `next dev`. The same file guards the hover path
+ * with `if (!prefetchEnabled || process.env.NODE_ENV === 'development')`, so
+ * nothing prefetches locally whatever this says. Do not "fix" it back because
+ * the network tab looks the same.
  */
 declare function DocsSidebar({ nav, pathname, Link, label, className }: DocsSidebarProps): ReactNode;
 //#endregion