@waveso/docs 0.2.0 → 0.3.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

@@ -35,15 +35,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.
    *
-   * ⚠️ 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.
+   * 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 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 +64,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, maxResults, 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,7 +26,7 @@ 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", maxResults = 8, debounceMs = 120, className, miniSearchOptions }) {
 	const [isOpen, setIsOpen] = useState(false);
 	const [query, setQuery] = useState("");
 	const [hits, setHits] = useState([]);
@@ -39,21 +39,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;
 			});
@@ -190,7 +190,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(" "),
@@ -276,7 +276,7 @@ function SearchResultOption({ hit, id, isActive, onActivate, onSelect, Link }) {
 		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", {
@@ -330,7 +330,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 +348,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));
 }
 /**

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

package/dist/react/sidebar.js

@@ -1,6 +1,7 @@
 "use client";
-import { useId, useRef, useState } from "react";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { nearestScrollTop } from "./nearest-scroll-top.js";
+import { useId, useLayoutEffect, useRef, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/sidebar.tsx
 /** Trailing slashes are a routing detail, not a difference in identity. */
 function normalizeHref(href) {
@@ -21,9 +22,44 @@ function containsActive(node, pathname) {
 /**
 * 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.
 */
 function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
 	const baseId = useId();
@@ -39,7 +75,23 @@ function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
 			[key]: isOpen
 		}));
 	};
+	const navRef = useRef(null);
+	useLayoutEffect(() => {
+		const active = navRef.current?.querySelector("[aria-current=\"page\"]");
+		if (!(active instanceof HTMLElement)) return;
+		const port = scrollableAncestor(active);
+		if (port === null) return;
+		const next = nearestScrollTop({
+			itemTop: active.getBoundingClientRect().top - port.getBoundingClientRect().top + port.scrollTop,
+			itemHeight: active.offsetHeight,
+			viewHeight: port.clientHeight,
+			scrollTop: port.scrollTop,
+			scrollHeight: port.scrollHeight
+		});
+		if (next !== void 0) port.scrollTop = next;
+	}, [pathname]);
 	return /* @__PURE__ */ jsx("nav", {
+		ref: navRef,
 		"aria-label": label,
 		className: ["wave-docs-sidebar", className].filter(Boolean).join(" "),
 		children: /* @__PURE__ */ jsx(NavList, {
@@ -53,7 +105,27 @@ function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
 		})
 	});
 }
+/**
+* The nearest ancestor that actually scrolls, or `null`.
+*
+* ⚠️ THIS EXISTS SO `scrollIntoView` DOES NOT HAVE TO. `scrollIntoView({ block:
+* 'nearest' })` reads as exactly the right call and scrolls **every**
+* scrollable ancestor including the document — so on a docs page it brings the
+* sidebar item into view and jumps the article the reader came to read, on the
+* one navigation where they know precisely what they asked for.
+* `sidebar.test.tsx` spies on it and asserts it is never called.
+*/
+function scrollableAncestor(element) {
+	let current = element.parentElement;
+	while (current !== null) {
+		const overflow = getComputedStyle(current).overflowY;
+		if ((overflow === "auto" || overflow === "scroll") && current.scrollHeight > current.clientHeight) return current;
+		current = current.parentElement;
+	}
+	return null;
+}
 function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, id }) {
+	const holdsActive = nodes.some((node) => (node.type === "page" || node.type === "link" && !node.external) && isActiveHref(pathname, node.href));
 	return /* @__PURE__ */ jsx("ul", {
 		id,
 		className: "wave-docs-sidebar__list",
@@ -74,6 +146,7 @@ function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, i
 						href: node.href,
 						isExternal: node.external,
 						isActive: !node.external && isActiveHref(pathname, node.href),
+						isNearby: holdsActive,
 						Link,
 						children: node.title
 					})
@@ -84,6 +157,7 @@ function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, i
 						href: node.href,
 						isExternal: false,
 						isActive: isActiveHref(pathname, node.href),
+						isNearby: holdsActive,
 						Link,
 						children: node.title
 					})
@@ -122,10 +196,11 @@ function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle }) {
 					className: "wave-docs-sidebar__group-title",
 					children: node.title
 				}), /* @__PURE__ */ jsx(Chevron, { isOpen })]
-			}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(NavLink, {
+			}) : /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(NavLink, {
 				href: node.href,
 				isExternal: false,
 				isActive: isGroupActive,
+				isNearby: hasActive,
 				Link,
 				children: node.title
 			}), /* @__PURE__ */ jsx("button", {
@@ -149,17 +224,34 @@ function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle }) {
 		}) : null]
 	});
 }
-function NavLink({ href, isExternal, isActive, Link, children }) {
+function NavLink({ href, isExternal, isActive, isNearby = false, Link, children }) {
 	const className = "wave-docs-sidebar__link";
 	if (isExternal) return /* @__PURE__ */ jsxs("a", {
 		className,
 		href,
 		target: "_blank",
 		rel: "noopener noreferrer",
-		children: [children, /* @__PURE__ */ jsx("span", {
-			className: "wave-docs-sr-only",
-			children: " (opens in a new tab)"
-		})]
+		children: [
+			children,
+			/* @__PURE__ */ jsx("svg", {
+				className: "wave-docs-sidebar__external",
+				"aria-hidden": "true",
+				focusable: "false",
+				viewBox: "0 0 24 24",
+				width: "12",
+				height: "12",
+				fill: "none",
+				stroke: "currentColor",
+				strokeWidth: "2",
+				strokeLinecap: "round",
+				strokeLinejoin: "round",
+				children: /* @__PURE__ */ jsx("path", { d: "M14 4h6v6M20 4l-8 8M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5" })
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: "wave-docs-sr-only",
+				children: " (opens in a new tab)"
+			})
+		]
 	});
 	if (Link === void 0) return /* @__PURE__ */ jsx("a", {
 		className,
@@ -170,7 +262,7 @@ function NavLink({ href, isExternal, isActive, Link, children }) {
 	return /* @__PURE__ */ jsx(Link, {
 		className,
 		href,
-		prefetch: false,
+		prefetch: isNearby ? void 0 : false,
 		"aria-current": isActive ? "page" : void 0,
 		children
 	});

package/dist/react/skip-link.d.ts

@@ -1,14 +1,6 @@
+import { DOCS_CONTENT_ID } from "../docs-content-id.js";
 import { ReactNode } from "react";
 //#region src/react/skip-link.d.ts
-/**
- * The `id` this link targets, and the one `createDocsRoute` puts on its
- * `<article>`.
- *
- * One constant for both halves: the two files spelled the string independently,
- * and a skip link pointing at an id nothing carries scrolls nowhere and focuses
- * nothing — a failure with no symptom until a keyboard user hits it.
- */
-declare const DOCS_CONTENT_ID = "docs-content";
 interface SkipLinkProps {
   /** Fragment id of the main content region. */
   href?: string | undefined;

package/dist/react/skip-link.js

@@ -1,14 +1,15 @@
+import { DOCS_CONTENT_ID } from "../docs-content-id.js";
 import { jsx } from "react/jsx-runtime";
 //#region src/react/skip-link.tsx
 /**
 * The `id` this link targets, and the one `createDocsRoute` puts on its
-* `<article>`.
+* `<main>`. Defined in a private module so the two halves cannot spell it
+* differently; re-exported here because this is the documented import path.
 *
-* One constant for both halves: the two files spelled the string independently,
-* and a skip link pointing at an id nothing carries scrolls nowhere and focuses
-* nothing — a failure with no symptom until a keyboard user hits it.
+* (This comment used to call the file a `'use client'` module. It is not one
+* and never was — `SkipLink` is an anchor with no state, so it is a Server
+* Component like everything else here that does not need a browser.)
 */
-const DOCS_CONTENT_ID = "docs-content";
 /**
 * Skip-to-content link: invisible until focused, first in the tab order.
 *

package/dist/react/toc.d.ts

@@ -16,6 +16,8 @@ interface DocsTocProps {
    * other unit, `rem` included.
    */
   rootMargin?: string | undefined;
+  /** Text for the back-to-top link. */
+  topLabel?: string | undefined;
   className?: string | undefined;
 }
 /**
@@ -26,10 +28,16 @@ interface DocsTocProps {
  * out of sync on duplicate headings.
  *
  * Scrolling itself is left to the browser: the links are real anchors, and
- * smooth scrolling is applied in CSS under
- * `@media (prefers-reduced-motion: no-preference)`. Doing it in JavaScript
- * means reimplementing that check, and getting it wrong makes people ill.
+ * nothing here calls `scrollTo`. Doing it in JavaScript means reimplementing
+ * the `prefers-reduced-motion` check, and getting that wrong makes people ill.
+ *
+ * ⚠️ AND THE STYLESHEET SETS NO `scroll-behavior: smooth` EITHER, deliberately
+ * — this comment used to say it did. Next 16 suppresses smooth scrolling
+ * across a route change only when `<html>` carries
+ * `data-scroll-behavior="smooth"`, an attribute only the host can set, so a
+ * package-level rule would smooth-scroll every navigation and no reader could
+ * turn it off. `styles.css` says the same at greater length.
  */
-declare function DocsToc({ entries, label, rootMargin, className }: DocsTocProps): ReactNode;
+declare function DocsToc({ entries, label, rootMargin, className, topLabel }: DocsTocProps): ReactNode;
 //#endregion
 export { DocsToc, DocsTocProps };