@waveso/docs 0.3.0 → 0.5.0

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

@@ -5,8 +5,15 @@ import { Options } from "minisearch";
 //#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.
+   * URL of the serialised index, e.g. `/docs/search-index.json`.
+   *
+   * `docs.searchIndexUrl` is the value to pass: it is derived from the route's
+   * `basePath`, so it is right when the docs are mounted anywhere but the root.
+   * `docs.Layout` passes it for you.
+   *
+   * (This used to say "whatever `writeSearchIndex` wrote". That function was
+   * deleted in 0.3.0, along with the build script it needed — the index is a
+   * `force-static` route handler now.)
    */
   indexUrl: string;
   /**
@@ -26,10 +33,90 @@ 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;
+  /**
+   * Shown before anything is typed. Defaults to
+   * `'Start typing to search the documentation.'`
+   */
+  hintLabel?: string | undefined;
+  /**
+   * Shown while a query is below {@link SearchDialogProps.minQueryLength}.
+   * Defaults to `'Keep typing — {min} characters or more.'`
+   *
+   * `{min}` is replaced with that number. Said rather than silently done: a
+   * dialog that answers nothing and explains nothing reads as broken, and this
+   * is the state every reader passes through on the way to their real query.
+   */
+  shortQueryLabel?: string | undefined;
+  /** Shown while the index is being fetched. Defaults to `'Loading the search index…'`. */
+  loadingLabel?: string | undefined;
+  /**
+   * Shown when the index cannot be loaded. Defaults to
+   * `'Search is unavailable right now. Try reloading the page.'`
+   */
+  errorLabel?: string | undefined;
+  /**
+   * Shown when a query matches nothing. Defaults to `'No results for “{query}”.'`
+   *
+   * `{query}` is replaced with what the reader typed.
+   */
+  emptyLabel?: string | undefined;
+  /**
+   * The live region's announcement, by plural category. `{count}` is the total.
+   *
+   * Defaults to `{ one: '{count} result', other: '{count} results' }`.
+   *
+   * ⚠️ KEYED BY CATEGORY RATHER THAN BEING TWO STRINGS, BECAUSE MOST LANGUAGES
+   * ARE NOT ENGLISH. Polish takes four forms and Arabic six;
+   * `Intl.PluralRules(locale).select(count)` picks, and an unlisted category
+   * falls back to `other`. Two props called "singular" and "plural" would have
+   * made this package announce a wrong number of results, correctly, in most of
+   * the world.
+   */
+  resultCountLabels?: Partial<Record<Intl.LDMLPluralRule, string>> | undefined;
+  /**
+   * Language tag for the plural rules above. Defaults to the document's own
+   * `<html lang>`, then to `'en'`.
+   *
+   * Read at announcement time rather than at render, so it costs nothing on a
+   * site that never changes it and needs no prop on a site that sets `lang`
+   * correctly — which is every site that should be setting these labels at all.
+   */
+  locale?: string | undefined;
   /** Extra class names for the trigger button, e.g. a navbar's own layout. */
   className?: string | undefined;
   /**
@@ -64,6 +151,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, miniSearchOptions }: SearchDialogProps): ReactNode;
+declare function SearchDialog({ indexUrl, navigate, Link, triggerLabel, placeholder, dialogLabel, pageSize, minQueryLength, debounceMs, className, miniSearchOptions, hintLabel, shortQueryLabel, loadingLabel, errorLabel, emptyLabel, resultCountLabels, locale }: SearchDialogProps): ReactNode;
 //#endregion
 export { SearchDialog, SearchDialogProps };

package/dist/react/search-dialog.js

@@ -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, miniSearchOptions }) {
+function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", placeholder = "Search documentation", dialogLabel = "Search documentation", pageSize = 20, minQueryLength = 2, debounceMs = 120, className, miniSearchOptions, hintLabel, shortQueryLabel, loadingLabel, errorLabel, emptyLabel, resultCountLabels, locale }) {
 	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("");
@@ -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;
 		}
@@ -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,45 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 				/* @__PURE__ */ jsx(SearchStatus, {
 					status,
 					query: query.trim(),
-					hitCount: hits.length
+					hitCount: hits.length,
+					minQueryLength,
+					labels: {
+						...hintLabel === void 0 ? {} : { hint: hintLabel },
+						...shortQueryLabel === void 0 ? {} : { shortQuery: shortQueryLabel },
+						...loadingLabel === void 0 ? {} : { loading: loadingLabel },
+						...errorLabel === void 0 ? {} : { error: errorLabel },
+						...emptyLabel === void 0 ? {} : { empty: emptyLabel }
+					},
+					resultCountLabels,
+					locale
 				})
 			]
 		})
 	}), 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$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", {
@@ -313,21 +391,59 @@ function SearchResultOption({ hit, id, isActive, onActivate, onSelect, Link }) {
 		})
 	});
 }
+/**
+* The wording, so a caller that overrides none of it costs nothing.
+*
+* `Record<keyof …, string>` rather than `as const`: literal types here make
+* every override a type error, and `Required<StatusLabels>` keeps the
+* `| undefined` that `exactOptionalPropertyTypes` needs on the props.
+*/
+const DEFAULT_STATUS_LABELS = {
+	hint: "Start typing to search the documentation.",
+	shortQuery: "Keep typing — {min} characters or more.",
+	loading: "Loading the search index…",
+	error: "Search is unavailable right now. Try reloading the page.",
+	empty: "No results for “{query}”."
+};
+const DEFAULT_RESULT_COUNT_LABELS = {
+	one: "{count} result",
+	other: "{count} results"
+};
+/**
+* The announcement for `count` hits, in the document's own language.
+*
+* `Intl.PluralRules` rather than an `=== 1` check: Polish takes four plural
+* forms and Arabic six, and a package that ships an English singular/plural pair
+* announces a wrong number of results — correctly, and confidently — in most of
+* the world. An unlisted category falls back to `other`, which is the one every
+* language has.
+*/
+function announceCount(count, labels, locale) {
+	const tag = locale ?? (typeof document === "undefined" ? "" : document.documentElement.lang) ?? "";
+	let category = "other";
+	try {
+		category = new Intl.PluralRules(tag === "" ? "en" : tag).select(count);
+	} catch {}
+	return (labels[category] ?? labels.other ?? "{count}").replace("{count}", String(count));
+}
 /** Loading, failure and empty states, plus a live region for hit counts. */
-function SearchStatus({ status, query, hitCount }) {
+function SearchStatus({ status, query, hitCount, minQueryLength, labels, resultCountLabels, locale }) {
 	let message = null;
 	let modifier = "";
 	if (status === "error") {
-		message = "Search is unavailable right now. Try reloading the page.";
+		message = labels.error ?? DEFAULT_STATUS_LABELS.error;
 		modifier = " wave-docs-search-status-error";
 	} else if (query === "") {
-		message = "Start typing to search the documentation.";
+		message = labels.hint ?? DEFAULT_STATUS_LABELS.hint;
+		modifier = " wave-docs-search-status-hint";
+	} else if (query.length < minQueryLength) {
+		message = (labels.shortQuery ?? DEFAULT_STATUS_LABELS.shortQuery).replace("{min}", String(minQueryLength));
 		modifier = " wave-docs-search-status-hint";
 	} else if (status !== "ready") {
-		message = "Loading the search index…";
+		message = labels.loading ?? DEFAULT_STATUS_LABELS.loading;
 		modifier = " wave-docs-search-status-loading";
 	} else if (hitCount === 0) {
-		message = `No results for “${query}”.`;
+		message = (labels.empty ?? DEFAULT_STATUS_LABELS.empty).replace("{query}", query);
 		modifier = " wave-docs-search-status-empty";
 	}
 	return /* @__PURE__ */ jsxs(Fragment$1, { children: [message === null ? null : /* @__PURE__ */ jsx("p", {
@@ -337,7 +453,7 @@ function SearchStatus({ status, query, hitCount }) {
 		className: "wave-docs-search-announcer",
 		role: "status",
 		"aria-live": "polite",
-		children: query === "" || status !== "ready" ? "" : `${hitCount} ${hitCount === 1 ? "result" : "results"}`
+		children: query === "" || status !== "ready" ? "" : announceCount(hitCount, resultCountLabels ?? DEFAULT_RESULT_COUNT_LABELS, locale)
 	})] });
 }
 /**
@@ -380,24 +496,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.
+*
+* ⚠️ 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.
 *
-* 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.
+* 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

@@ -1,22 +1,45 @@
 //#region src/react/shell-labels.d.ts
 /**
- * Every user-visible string the shell renders that is not the reader's content.
+ * Every user-visible string this package 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.
+ * ⚠️ THERE USED TO BE FOUR, AND THE DOCSTRING CLAIMED THEY WERE ALL OF THEM.
+ * They were the four `docs.Layout` renders directly, and the claim — "the whole
+ * of what a non-English site has to say" — was false by seventeen strings. A
+ * German site built exactly the documented way shipped
+ * `<nav aria-label="On this page">`, a visible `Back to top`, `aria-label="Tip"`
+ * on every callout, `Copy code` on every fence and `(opens in a new tab)` after
+ * every external link. Verified in this repository's own `site/out`, which is
+ * how it was found.
  *
- * 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.
+ * ## Where each one is rendered, because it decides the cost
+ *
+ * Most are emitted by Server Components or baked into the HTML by a rehype
+ * plugin at build time, so overriding them costs nothing at all. Six cross into
+ * a Client Component — the two sidebar disclosure verbs, the two table-of-contents
+ * strings and the two copy-status messages — and those are forwarded ONLY when
+ * set, so a site that overrides nothing carries exactly the payload it did
+ * before.
+ *
+ * ## The defaults do not all live here
+ *
+ * {@link DEFAULT_DOCS_LABELS} covers the four shell strings and no more, on
+ * purpose. The rest default inside the component that renders them, because
+ * this module would otherwise have to be imported by `sidebar.tsx` and
+ * `code-runtime.tsx` — and an object literal of twenty-one strings does not
+ * tree-shake, so every reader would download the German site's English
+ * fallbacks. `next.test.ts` asserts that every key here reaches the output, so
+ * a key that is declared and never wired fails rather than reading as
+ * configuration.
  *
  * 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.
+ * `search={{ … }}` on `docs.Layout` — its trigger, its placeholder, its
+ * accessible name and its five state messages, plus the plural forms of its
+ * live region. They travel with the dialog's own props rather than with these
+ * because that channel already existed and already carries `pageSize` and
+ * `minQueryLength`; a second route to the same component would be two places to
+ * look. `DocsSidebar`'s own `label` is likewise public API, for anyone composing
+ * a shell by hand.
  */
 interface DocsLabels {
   /** The navigation landmark's accessible name. Default `'Documentation'`. */
@@ -27,17 +50,108 @@ interface DocsLabels {
   closeNav?: string | undefined;
   /** The skip link's visible text. Default `'Skip to content'`. */
   skipToContent?: string | undefined;
+  /**
+   * Accessible name of a collapsed group's toggle. Default `'Expand {title}'`.
+   *
+   * `{title}` is replaced with the group's own name. A placeholder rather than a
+   * function because this crosses from a Server Component to a Client one, where
+   * a function cannot go.
+   */
+  expandGroup?: string | undefined;
+  /** The same toggle when open. Default `'Collapse {title}'`. */
+  collapseGroup?: string | undefined;
+  /** The TOC landmark's accessible name. Default `'On this page'`. */
+  toc?: string | undefined;
+  /** The link at the end of the TOC. Default `'Back to top'`. */
+  backToTop?: string | undefined;
+  /**
+   * Screen-reader suffix on a link that opens a new tab.
+   * Default `'(opens in a new tab)'`.
+   */
+  externalLink?: string | undefined;
+  /**
+   * Accessible name of a wide table's scroll region. Default `'Table'`.
+   *
+   * The region exists so a keyboard user can scroll a table that overflows; an
+   * unnamed one is announced as "region", which says nothing about what it
+   * holds.
+   */
+  table?: string | undefined;
+  /** Heading on a `> [!NOTE]` callout. Default `'Note'`. */
+  calloutNote?: string | undefined;
+  /** Heading on a `> [!TIP]` callout. Default `'Tip'`. */
+  calloutTip?: string | undefined;
+  /** Heading on a `> [!IMPORTANT]` callout. Default `'Important'`. */
+  calloutImportant?: string | undefined;
+  /** Heading on a `> [!WARNING]` callout. Default `'Warning'`. */
+  calloutWarning?: string | undefined;
+  /** Heading on a `> [!CAUTION]` callout. Default `'Caution'`. */
+  calloutCaution?: string | undefined;
+  /**
+   * Accessible name of a YouTube embed. Default `'YouTube video player'`.
+   *
+   * Markdown carries no video title, so this is the name every embed on the site
+   * gets unless a `<YouTube title>` overrides it.
+   */
+  youtubeTitle?: string | undefined;
+  /**
+   * The closed facade's control. Default `'Play video: {title}'`.
+   *
+   * `{title}` is the embed's accessible name.
+   */
+  youtubePlay?: string | undefined;
+  /** The open facade's control. Default `'Hide video: {title}'`. */
+  youtubeHide?: string | undefined;
+  /** The copy button on a fence with no title. Default `'Copy code'`. */
+  copyCode?: string | undefined;
+  /**
+   * The copy button on a titled fence. Default `'Copy code from {title}'`.
+   *
+   * `{title}` is the fence's own `title="…"`. Two controls both called "Copy
+   * code" are indistinguishable in a screen reader's element list, which is why
+   * the titled form exists at all.
+   */
+  copyCodeFrom?: string | undefined;
+  /** Announced after a successful copy. Default `'Copied to the clipboard.'` */
+  copied?: string | undefined;
+  /**
+   * Announced after a failed one. Default
+   * `'Copy failed. Select the code and press Control or Command + C.'`
+   *
+   * Says what to do instead, not merely that it failed: the common way to land
+   * here is `next dev` on a phone over plain HTTP, where there is no secure
+   * context and retrying cannot help.
+   */
+  copyFailed?: string | undefined;
 }
 /**
- * The defaults, in one place.
+ * Every key of {@link DocsLabels}, for the test that proves each one is wired.
  *
- * 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.
+ * A list rather than a type-level trick because the assertion has to run: the
+ * failure being guarded against is a key that is declared, documented and never
+ * read, which type-checks perfectly.
  */
-declare const DEFAULT_DOCS_LABELS: Required<DocsLabels>;
+declare const DOCS_LABEL_KEYS: readonly ["nav", "openNav", "closeNav", "skipToContent", "expandGroup", "collapseGroup", "toc", "backToTop", "externalLink", "table", "calloutNote", "calloutTip", "calloutImportant", "calloutWarning", "calloutCaution", "youtubeTitle", "youtubePlay", "youtubeHide", "copyCode", "copyCodeFrom", "copied", "copyFailed"];
+/** The four the shell renders itself, resolved centrally. */
+type ShellLabelKey = 'nav' | 'openNav' | 'closeNav' | 'skipToContent';
+/**
+ * Defaults for the shell's four, in one place.
+ *
+ * A `Required<…>` 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<Pick<DocsLabels, ShellLabelKey>>;
 /** The given labels over the defaults, with `undefined` treated as unset. */
-declare function resolveLabels(labels: DocsLabels | undefined): Required<DocsLabels>;
+declare function resolveLabels(labels: DocsLabels | undefined): Required<Pick<DocsLabels, ShellLabelKey>>;
+/**
+ * `template` with `{title}` replaced.
+ *
+ * A placeholder, because these strings cross a Server → Client boundary where a
+ * function cannot go — and because a translator needs to move the name within
+ * the sentence, which string concatenation does not allow.
+ */
+declare function fillTitle(template: string, title: string): string;
 //#endregion
-export { DEFAULT_DOCS_LABELS, DocsLabels, resolveLabels };
+export { DEFAULT_DOCS_LABELS, DOCS_LABEL_KEYS, DocsLabels, ShellLabelKey, fillTitle, resolveLabels };