@waveso/docs 0.1.0 → 0.3.0

package/dist/react/search-dialog.js

@@ -1,7 +1,8 @@
 "use client";
-import { SEARCH_INDEX_OPTIONS } from "../search-options.js";
+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
 /**
@@ -25,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 }) {
+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([]);
@@ -37,29 +38,34 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 	const inputRef = useRef(null);
 	const listRef = useRef(null);
 	const returnFocusRef = useRef(null);
-	const indexRef = useRef(null);
+	const indexCacheRef = useRef(/* @__PURE__ */ new Map());
+	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}`;
-	/** Load the index at most once; a failure clears the cache so a retry can. */
+	useEffect(() => {
+		miniSearchOptionsRef.current = miniSearchOptions;
+	}, [miniSearchOptions]);
+	/** Load each URL at most once; a failure evicts that key so a retry can. */
 	const ensureIndex = useCallback(() => {
-		let pending = indexRef.current;
-		if (pending === null) {
-			pending = loadIndex(indexUrl).catch((error) => {
-				indexRef.current = null;
+		const cache = indexCacheRef.current;
+		let pending = cache.get(indexUrl);
+		if (pending === void 0) {
+			pending = loadIndex(indexUrl, miniSearchOptionsRef.current).catch((error) => {
+				cache.delete(indexUrl);
 				throw error;
 			});
-			indexRef.current = pending;
+			cache.set(indexUrl, pending);
 		}
 		return pending;
 	}, [indexUrl]);
 	const warmIndex = useCallback(() => {
-		if (indexRef.current !== null) return;
+		if (indexCacheRef.current.has(indexUrl)) return;
 		setStatus("loading");
 		ensureIndex().then(() => setStatus("ready"), () => setStatus("error"));
-	}, [ensureIndex]);
+	}, [ensureIndex, indexUrl]);
 	const openDialog = useCallback(() => {
 		returnFocusRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
 		setIsOpen(true);
@@ -83,6 +89,20 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 		openDialog,
 		closeDialog
 	]);
+	useEffect(() => {
+		if (!isOpen) return;
+		function handleKeyDown(event) {
+			if (event.key === "Escape") {
+				event.preventDefault();
+				event.stopPropagation();
+				closeDialog();
+				return;
+			}
+			if (event.key === "Tab") trapFocus(dialogRef.current, event);
+		}
+		document.addEventListener("keydown", handleKeyDown, true);
+		return () => document.removeEventListener("keydown", handleKeyDown, true);
+	}, [isOpen, closeDialog]);
 	useEffect(() => {
 		const isApple = /mac|iphone|ipad|ipod/i.test(navigator.userAgent);
 		setShortcutHint(isApple ? "⌘K" : "Ctrl K");
@@ -153,17 +173,8 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 		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;
-		}
+	function handleInputKeyDown(event) {
+		if (event.nativeEvent.isComposing || event.keyCode === 229) return;
 		if (event.key === "ArrowDown" || event.key === "ArrowUp") {
 			if (hits.length === 0) return;
 			event.preventDefault();
@@ -179,10 +190,10 @@ 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: ["wave-docs-search-trigger", className].filter(Boolean).join(" "),
 		"aria-label": triggerLabel,
 		"aria-keyshortcuts": "Meta+K Control+K",
 		onClick: openDialog,
@@ -206,7 +217,6 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 			role: "dialog",
 			"aria-modal": "true",
 			"aria-label": dialogLabel,
-			onKeyDown: handleDialogKeyDown,
 			children: [
 				/* @__PURE__ */ jsxs("div", {
 					className: "wave-docs-search-input-row",
@@ -223,6 +233,7 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 						placeholder,
 						value: query,
 						onChange: (event) => setQuery(event.target.value),
+						onKeyDown: handleInputKeyDown,
 						autoComplete: "off",
 						autoCorrect: "off",
 						spellCheck: false
@@ -265,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", {
@@ -319,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", {
@@ -335,10 +346,15 @@ function SearchStatus({ status, query, hitCount }) {
 * `loadJSONAsync` yields between chunks so deserialising a large index does
 * not freeze the frame the dialog just opened in.
 */
-async function loadIndex(url) {
+async function loadIndex(url, overrides) {
 	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);
+	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));
 }
 /**
 * Narrow one MiniSearch result. Its stored fields are untyped by design, and
@@ -392,10 +408,16 @@ function trapFocus(root, event) {
 		event.preventDefault();
 		return;
 	}
-	if (event.shiftKey && document.activeElement === first) {
+	const active = document.activeElement;
+	if (!(active instanceof HTMLElement) || !root.contains(active)) {
+		event.preventDefault();
+		(event.shiftKey ? last : first).focus();
+		return;
+	}
+	if (event.shiftKey && active === first) {
 		event.preventDefault();
 		last.focus();
-	} else if (!event.shiftKey && document.activeElement === last) {
+	} else if (!event.shiftKey && active === last) {
 		event.preventDefault();
 		first.focus();
 	}

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 };

package/dist/react/toc.js

@@ -1,8 +1,16 @@
 "use client";
+import { DOCS_CONTENT_ID } from "../docs-content-id.js";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/toc.tsx
 const DEFAULT_ROOT_MARGIN = "-80px 0px -60% 0px";
+/**
+* How many frames to keep looking for headings that are not in the document
+* yet. ~1s at 60Hz, which covers a `<Suspense>` boundary resolving or a
+* tabs/accordion wrapper revealing its panel. Bounded because the loop must
+* also terminate on a page whose headings genuinely never arrive.
+*/
+const MAX_ATTACH_FRAMES = 60;
 function flattenTocIds(entries) {
 	const ids = [];
 	const walk = (list) => {
@@ -22,11 +30,17 @@ function flattenTocIds(entries) {
 * 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.
 */
-function DocsToc({ entries, label = "On this page", rootMargin = DEFAULT_ROOT_MARGIN, className }) {
+function DocsToc({ entries, label = "On this page", rootMargin = DEFAULT_ROOT_MARGIN, className, topLabel = "Back to top" }) {
 	const ids = useMemo(() => flattenTocIds(entries), [entries]);
 	const [activeId, setActiveId] = useState(void 0);
 	const lastIds = useRef(ids);
@@ -46,21 +60,41 @@ function DocsToc({ entries, label = "On this page", rootMargin = DEFAULT_ROOT_MA
 			rootMargin,
 			threshold: 0
 		});
-		for (const id of ids) {
-			const element = document.getElementById(id);
-			if (element !== null) observer.observe(element);
-		}
-		return () => observer.disconnect();
+		let frame;
+		let framesLeft = MAX_ATTACH_FRAMES;
+		const attach = () => {
+			let attached = 0;
+			for (const id of ids) {
+				const element = document.getElementById(id);
+				if (element !== null) {
+					observer.observe(element);
+					attached += 1;
+				}
+			}
+			if (attached === 0 && framesLeft > 0 && typeof requestAnimationFrame === "function") {
+				framesLeft -= 1;
+				frame = requestAnimationFrame(attach);
+			}
+		};
+		attach();
+		return () => {
+			if (frame !== void 0) cancelAnimationFrame(frame);
+			observer.disconnect();
+		};
 	}, [ids, rootMargin]);
 	if (entries.length === 0) return null;
-	return /* @__PURE__ */ jsx("nav", {
+	return /* @__PURE__ */ jsxs("nav", {
 		"aria-label": label,
 		className: ["wave-docs-toc", className].filter(Boolean).join(" "),
-		children: /* @__PURE__ */ jsx(TocList, {
+		children: [/* @__PURE__ */ jsx(TocList, {
 			entries,
 			activeId,
 			onSelect: setActiveId
-		})
+		}), /* @__PURE__ */ jsx("a", {
+			className: "wave-docs-toc__top",
+			href: `#${DOCS_CONTENT_ID}`,
+			children: topLabel
+		})]
 	});
 }
 function TocList({ entries, activeId, onSelect }) {