@waveso/docs 0.4.0 → 0.6.0

package/dist/react/markdown-components.js

@@ -1,24 +1,14 @@
+import { isSafeHref, opensInNewTab } from "../safe-href.js";
 import { Callout } from "./callout.js";
 import { YouTube } from "./youtube.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/markdown-components.tsx
-/** Schemes we send to a new tab. `mailto:`/`tel:` are left to the OS. */
-const HTTP_SCHEME = /^https?:\/\//i;
-/** Any URL with a scheme, or protocol-relative. */
+/** Default, and the only string here a reader sees without a screen reader. */
+const DEFAULT_EXTERNAL_LINK = "(opens in a new tab)";
+/** Default name for a wide table's scroll region. */
+const DEFAULT_TABLE = "Table";
+/** Any URL with a scheme, or protocol-relative. Decides router vs plain `<a>`. */
 const ABSOLUTE_URL = /^([a-z][a-z0-9+.-]*:|\/\/)/i;
-/**
-* The schemes a markdown link may carry.
-*
-* GitHub's own allowlist, which is the bar to match: documentation links to
-* `sms:`, `ftp:` and `irc:` are ordinary, and an allowlist of three silently
-* deleted them. The point of the check is to stop `javascript:`, `data:` and
-* `vbscript:` reaching an `href`, not to have an opinion about protocols.
-*
-* A scheme not listed here — `vscode:`, `obsidian:`, `slack:` — is dropped
-* rather than rendered. That is deliberate: an allowlist that grows on request
-* is safe, one that guesses is not. {@link warnDroppedHref} makes it visible.
-*/
-const SAFE_SCHEME = /^(https?|mailto|tel|sms|ftp|ftps|irc|ircs|xmpp|news|nntp|feed|git|matrix):/i;
 /** Hrefs already reported, so a re-render does not repeat the warning. */
 const warnedHrefs = /* @__PURE__ */ new Set();
 /**
@@ -32,35 +22,7 @@ const warnedHrefs = /* @__PURE__ */ new Set();
 function warnDroppedHref(href) {
 	if (process.env.NODE_ENV === "production" || warnedHrefs.has(href)) return;
 	warnedHrefs.add(href);
-	console.warn(`@waveso/docs: dropped a link to '${href}' — its URL scheme is not in the allowlist, so the text was kept and the destination removed. Use http, https, mailto, tel, sms, ftp, irc, xmpp or matrix, or render the link yourself with a custom \`a\` component.`);
-}
-/**
-* A copy of `href` as a browser will parse it.
-*
-* ASCII control characters and spaces are stripped before parsing, so
-* ` javascript:` and `java<TAB>script:` both navigate where the raw string
-* matches no scheme at all — which is how a scheme check gets walked around.
-*/
-function normaliseUrl(href) {
-	return [...href].filter((char) => (char.codePointAt(0) ?? 0) > 32).join("");
-}
-/**
-* Would this href navigate somewhere we are willing to send a reader?
-*
-* Nothing upstream filters it: `remarkDocLinks` skips every href with a scheme
-* (`isRelativeLink` is false for it), so `assertLinks` never sees one either,
-* and `remarkRehype` runs with `allowDangerousHtml` off but passes a link's own
-* url through untouched. Verified against React 19: it neutralises
-* `javascript:` in every obfuscated form, silently — but it lets `vbscript:`
-* and `data:text/html;base64,…` reach the DOM verbatim. So the allowlist is
-* ours to keep.
-*
-* Tested against {@link normaliseUrl}, not the raw string.
-*/
-function isSafeHref(href) {
-	const normalised = normaliseUrl(href);
-	if (!ABSOLUTE_URL.test(normalised)) return true;
-	return normalised.startsWith("//") || SAFE_SCHEME.test(normalised);
+	console.warn(`@waveso/docs: dropped a link to '${href}' — its scheme is not in the allowlist. Use http(s), mailto, tel or another documented scheme.`);
 }
 function joinClassNames(...values) {
 	const joined = values.filter(Boolean).join(" ");
@@ -73,7 +35,7 @@ function toDimension(value) {
 		return Number.isFinite(parsed) ? parsed : void 0;
 	}
 }
-function createAnchor(Link) {
+function createAnchor(Link, externalLink) {
 	return function MarkdownAnchor({ href, children, ...rest }) {
 		if (href === void 0) return /* @__PURE__ */ jsx("a", {
 			...rest,
@@ -83,14 +45,14 @@ function createAnchor(Link) {
 			warnDroppedHref(href);
 			return /* @__PURE__ */ jsx("span", { children });
 		}
-		if (HTTP_SCHEME.test(href) || href.startsWith("//")) return /* @__PURE__ */ jsxs("a", {
+		if (opensInNewTab(href)) return /* @__PURE__ */ jsxs("a", {
 			...rest,
 			href,
 			target: "_blank",
 			rel: "noopener noreferrer",
-			children: [children, /* @__PURE__ */ jsx("span", {
+			children: [children, /* @__PURE__ */ jsxs("span", {
 				className: "wave-docs-sr-only",
-				children: " (opens in a new tab)"
+				children: [" ", externalLink]
 			})]
 		});
 		if (href.startsWith("#") || ABSOLUTE_URL.test(href) || Link === void 0) return /* @__PURE__ */ jsx("a", {
@@ -106,7 +68,7 @@ function createAnchor(Link) {
 	};
 }
 function createImage(Image) {
-	return function MarkdownImage({ src, alt, width, height, title, className, sizes, loading, ...rest }) {
+	return function MarkdownImage({ src, alt, width, height, title, className, sizes, loading, decoding, fetchPriority, ...rest }) {
 		const resolvedWidth = toDimension(width);
 		const resolvedHeight = toDimension(height);
 		const resolvedLoading = loading ?? "lazy";
@@ -120,10 +82,11 @@ function createImage(Image) {
 			title,
 			className: resolvedClassName,
 			sizes,
-			loading: resolvedLoading
+			loading: resolvedLoading,
+			decoding: decoding ?? "async",
+			fetchPriority
 		});
 		return /* @__PURE__ */ jsx("img", {
-			decoding: "async",
 			...rest,
 			src,
 			alt: alt ?? "",
@@ -132,7 +95,9 @@ function createImage(Image) {
 			title,
 			className: resolvedClassName,
 			sizes,
-			loading: resolvedLoading
+			loading: resolvedLoading,
+			decoding: decoding ?? "async",
+			fetchPriority
 		});
 	};
 }
@@ -146,16 +111,18 @@ function createImage(Image) {
 * `<section>` is a `region` landmark, so the tab stop announces itself instead
 * of being a mystery stop in the tab order.
 */
-function MarkdownTable({ className, ...rest }) {
-	return /* @__PURE__ */ jsx("section", {
-		className: "wave-docs-table-scroll",
-		"aria-label": "Table",
-		tabIndex: 0,
-		children: /* @__PURE__ */ jsx("table", {
-			...rest,
-			className: joinClassNames("wave-docs-table", className)
-		})
-	});
+function createTable(label) {
+	return function MarkdownTable({ className, ...rest }) {
+		return /* @__PURE__ */ jsx("section", {
+			className: "wave-docs-table-scroll",
+			"aria-label": label,
+			tabIndex: 0,
+			children: /* @__PURE__ */ jsx("table", {
+				...rest,
+				className: joinClassNames("wave-docs-table", className)
+			})
+		});
+	};
 }
 /**
 * Build the default component map, optionally injecting host-specific link and
@@ -173,12 +140,47 @@ function MarkdownTable({ className, ...rest }) {
 * ```
 */
 function createMarkdownComponents(options = {}) {
+	const labels = options.labels ?? {};
+	const calloutTitles = calloutTitleMap(labels);
 	return {
-		a: createAnchor(options.Link),
+		a: createAnchor(options.Link, labels.externalLink ?? DEFAULT_EXTERNAL_LINK),
 		img: createImage(options.Image),
-		table: MarkdownTable,
-		callout: Callout,
-		youtube: YouTube
+		table: createTable(labels.table ?? DEFAULT_TABLE),
+		callout: (props) => /* @__PURE__ */ jsx(Callout, {
+			...props,
+			...calloutTitles === void 0 ? {} : { labels: calloutTitles }
+		}),
+		youtube: (props) => /* @__PURE__ */ jsx(YouTube, { ...youtubeDefaults(labels, props) })
+	};
+}
+/** The five headings as `Callout` wants them, or `undefined` if none are set. */
+function calloutTitleMap(labels) {
+	const titles = {};
+	let found = false;
+	for (const [type, key] of Object.entries(CALLOUT_LABEL_KEYS)) {
+		const value = labels[key];
+		if (value !== void 0) {
+			titles[type] = value;
+			found = true;
+		}
+	}
+	return found ? titles : void 0;
+}
+/** Which `DocsLabels` key names a given callout type's heading. */
+const CALLOUT_LABEL_KEYS = {
+	note: "calloutNote",
+	tip: "calloutTip",
+	important: "calloutImportant",
+	warning: "calloutWarning",
+	caution: "calloutCaution"
+};
+/** `props`, with the site's YouTube strings filled in. */
+function youtubeDefaults(labels, props) {
+	return {
+		...props,
+		...props.title === void 0 && labels.youtubeTitle !== void 0 ? { title: labels.youtubeTitle } : {},
+		...labels.youtubePlay === void 0 ? {} : { playLabel: labels.youtubePlay },
+		...labels.youtubeHide === void 0 ? {} : { hideLabel: labels.youtubeHide }
 	};
 }
 /** The map used when a caller supplies none. Plain `<a>` and `<img>`. */

package/dist/react/nav.d.ts

@@ -22,7 +22,11 @@ interface DocsNavProps {
   label?: string | undefined;
   /** Accessible name for the close button. */
   closeLabel?: string | undefined;
+  /** Passed through to the tree. See `DocsSidebarProps.expandGroup`. */
+  expandGroup?: string | undefined;
+  collapseGroup?: string | undefined;
+  externalLink?: string | undefined;
 }
-declare function DocsNav({ nav, pathname, Link, label, closeLabel }: DocsNavProps): ReactNode;
+declare function DocsNav({ nav, pathname, Link, label, closeLabel, expandGroup, collapseGroup, externalLink }: DocsNavProps): ReactNode;
 //#endregion
 export { DOCS_NAV_ID, DocsNav, DocsNavProps };

package/dist/react/nav.js

@@ -12,7 +12,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 * the button does nothing on the first tap.
 */
 const DOCS_NAV_ID = "wave-docs-nav";
-function DocsNav({ nav, pathname, Link, label = "Documentation", closeLabel = "Close navigation" }) {
+function DocsNav({ nav, pathname, Link, label = "Documentation", closeLabel = "Close navigation", expandGroup, collapseGroup, externalLink }) {
 	const ref = useRef(null);
 	useEffect(() => {
 		ref.current?.close?.();
@@ -62,7 +62,10 @@ function DocsNav({ nav, pathname, Link, label = "Documentation", closeLabel = "C
 			nav,
 			pathname,
 			label,
-			Link
+			Link,
+			...expandGroup === void 0 ? {} : { expandGroup },
+			...collapseGroup === void 0 ? {} : { collapseGroup },
+			...externalLink === void 0 ? {} : { externalLink }
 		})]
 	});
 }

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

@@ -1,34 +1,12 @@
 import { DocsLinkComponent } from "./markdown-components.js";
-import { ComponentProps, ComponentType } from "react";
 //#region src/react/next-link.d.ts
 /**
- * The part of `next/link` this package uses.
+ * Module scope, and never inside a render.
  *
- * Declared structurally rather than imported: `next` is an optional peer, and
- * a type-only import of it would still be a hard resolution requirement for
- * anyone type-checking against our `.d.ts`.
+ * A fresh component identity for a link remounts every link in the document on
+ * every render — which is why `next-search.tsx` and `next-nav.tsx` each build
+ * theirs at module scope too, and why this is a constant rather than a factory.
  */
-type NextLinkComponent = ComponentType<Omit<ComponentProps<'a'>, 'href' | 'ref'> & {
-  href: string;
-  prefetch?: boolean | null;
-}>;
-/**
- * Adapt `next/link` to {@link DocsLinkProps}.
- *
- * `next/link` widens `href` to `string | UrlObject` and `prefetch` to
- * `boolean | 'auto' | null`; the React layer promises neither, because it must
- * also run with a plain `<a>`. One wrapper keeps that mismatch in a single
- * place instead of at every call site.
- *
- * `prefetch` is omitted rather than passed as `undefined`, which is not
- * pedantry: under `exactOptionalPropertyTypes` — which this package compiles
- * with, and which any consumer may turn on — `undefined` is not assignable to
- * `boolean | 'auto' | null`, and `<SearchDialog Link={Link} />` written by
- * hand fails to compile for a reason that reads as our bug.
- *
- * Call it once at module scope, never during a render: a fresh component
- * identity for `a` remounts every link in the document on every render.
- */
-declare function wrapNextLink(NextLink: NextLinkComponent): DocsLinkComponent;
+declare const DocsLink: DocsLinkComponent;
 //#endregion
-export { NextLinkComponent, wrapNextLink };
+export { DocsLink };

package/dist/react/next-link.js

@@ -1,30 +1,51 @@
-import { createElement } from "react";
-//#region src/react/next-link.ts
+"use client";
+import { wrapNextLink } from "./link-adapter.js";
+import NextLink from "next/link";
+//#region src/react/next-link.tsx
 /**
-* Adapt `next/link` to {@link DocsLinkProps}.
+* `next/link`, adapted to this package's {@link DocsLinkProps} and ready to pass.
 *
-* `next/link` widens `href` to `string | UrlObject` and `prefetch` to
-* `boolean | 'auto' | null`; the React layer promises neither, because it must
-* also run with a plain `<a>`. One wrapper keeps that mismatch in a single
-* place instead of at every call site.
+* ⚠️ IT EXISTS BECAUSE PASSING `next/link` DIRECTLY DOES NOT TYPE-CHECK. Under
+* `exactOptionalPropertyTypes` — which this package compiles with, and which any
+* consumer may turn on — Next's `LinkProps` re-declares `onClick?`,
+* `onMouseEnter?` and `onTouchStart?` *without* `| undefined` while React's
+* anchor props include it, so `<DocsSidebar Link={Link} />` fails to compile
+* over three handlers `next/link` accepts perfectly well at run time. It is a
+* disagreement between two dependencies' declaration files, true of every
+* `next/link` call site in a project with that flag on, and nothing the shape of
+* `DocsLinkProps` can fix without breaking the plain-`<a>` fallback that makes
+* these components host-agnostic.
 *
-* `prefetch` is omitted rather than passed as `undefined`, which is not
-* pedantry: under `exactOptionalPropertyTypes` — which this package compiles
-* with, and which any consumer may turn on — `undefined` is not assignable to
-* `boolean | 'auto' | null`, and `<SearchDialog Link={Link} />` written by
-* hand fails to compile for a reason that reads as our bug.
+* `docs.Layout` and `DocsSearch` have always absorbed it internally, so it only
+* ever bit someone composing a shell by hand — who was told to write
+* `Link={Link as DocsLinkComponent}` and wait for this module. This is it; the
+* cast is retired.
 *
-* Call it once at module scope, never during a render: a fresh component
-* identity for `a` remounts every link in the document on every render.
+* ```tsx
+* 'use client';
+* import { DocsLink } from '@waveso/docs/react/next-link';
+* import { DocsSidebar } from '@waveso/docs/react/sidebar';
+*
+* <DocsSidebar nav={nav} pathname={pathname} Link={DocsLink} />
+* ```
+*
+* ## Why `'use client'`
+*
+* Not for a hook — there is none. {@link DocsLink} is a *function*, and a
+* function cannot be handed from a Server Component to a Client one: React
+* serialises those props and refuses. Without the directive this module's export
+* would be a server reference, and passing it to `DocsSidebar` — which is itself
+* `'use client'` — would fail `next build` with "Functions cannot be passed
+* directly to Client Components". The directive makes it a client reference,
+* which crosses fine.
+*/
+/**
+* Module scope, and never inside a render.
+*
+* A fresh component identity for a link remounts every link in the document on
+* every render — which is why `next-search.tsx` and `next-nav.tsx` each build
+* theirs at module scope too, and why this is a constant rather than a factory.
 */
-function wrapNextLink(NextLink) {
-	return function DocsNextLink({ href, prefetch, children, ...rest }) {
-		return createElement(NextLink, {
-			...rest,
-			href,
-			...prefetch === void 0 ? {} : { prefetch }
-		}, children);
-	};
-}
+const DocsLink = wrapNextLink(NextLink);
 //#endregion
-export { wrapNextLink };
+export { DocsLink };

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

@@ -5,7 +5,11 @@ interface DocsNextNavProps {
   nav: DocNavNode[];
   label?: string | undefined;
   closeLabel?: string | undefined;
+  /** Passed through to the tree. See `DocsSidebarProps.expandGroup`. */
+  expandGroup?: string | undefined;
+  collapseGroup?: string | undefined;
+  externalLink?: string | undefined;
 }
-declare function DocsNextNav({ nav, label, closeLabel }: DocsNextNavProps): ReactNode;
+declare function DocsNextNav({ nav, label, closeLabel, expandGroup, collapseGroup, externalLink }: DocsNextNavProps): ReactNode;
 //#endregion
 export { DocsNextNav, DocsNextNavProps };

package/dist/react/next-nav.js

@@ -1,5 +1,5 @@
 "use client";
-import { wrapNextLink } from "./next-link.js";
+import { wrapNextLink } from "./link-adapter.js";
 import { DocsNav } from "./nav.js";
 import { jsx } from "react/jsx-runtime";
 import NextLink from "next/link";
@@ -19,13 +19,16 @@ import { usePathname } from "next/navigation";
 */
 /** Module scope: a fresh identity here remounts every nav link on every render. */
 const Link = wrapNextLink(NextLink);
-function DocsNextNav({ nav, label, closeLabel }) {
+function DocsNextNav({ nav, label, closeLabel, expandGroup, collapseGroup, externalLink }) {
 	return /* @__PURE__ */ jsx(DocsNav, {
 		nav,
 		pathname: usePathname(),
 		Link,
 		...label === void 0 ? {} : { label },
-		...closeLabel === void 0 ? {} : { closeLabel }
+		...closeLabel === void 0 ? {} : { closeLabel },
+		...expandGroup === void 0 ? {} : { expandGroup },
+		...collapseGroup === void 0 ? {} : { collapseGroup },
+		...externalLink === void 0 ? {} : { externalLink }
 	});
 }
 //#endregion

package/dist/react/next-search.js

@@ -1,5 +1,5 @@
 "use client";
-import { wrapNextLink } from "./next-link.js";
+import { wrapNextLink } from "./link-adapter.js";
 import { SearchDialog } from "./search-dialog.js";
 import { useCallback } from "react";
 import { jsx } from "react/jsx-runtime";

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;
   /**
@@ -61,6 +68,55 @@ interface SearchDialogProps {
   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;
   /**
@@ -95,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, pageSize, minQueryLength, 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,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", pageSize = 20, minQueryLength = 2, 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([]);
@@ -336,7 +336,16 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 					status,
 					query: query.trim(),
 					hitCount: hits.length,
-					minQueryLength
+					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
 				})
 			]
 		})
@@ -382,24 +391,59 @@ function SearchResultOption({ hit, id, isActive, setSize, posInSet, onActivate,
 		})
 	});
 }
+/**
+* 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, minQueryLength }) {
+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 = `Keep typing — ${minQueryLength} characters or more.`;
+		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", {
@@ -409,7 +453,7 @@ function SearchStatus({ status, query, hitCount, minQueryLength }) {
 		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)
 	})] });
 }
 /**