@waveso/docs 0.4.0 → 0.6.0

package/dist/plugins/remark-doc-links.js

@@ -20,6 +20,10 @@ const FILE_EXTENSION = /\.[^./]+$/;
 function isRelativeLink(href) {
 	return href !== "" && !href.startsWith("#") && !href.startsWith("?") && !href.startsWith("/") && !HAS_SCHEME.test(href);
 }
+/** No prefix at all — the docs own the whole origin. */
+function isRootMount(basePath) {
+	return basePath.replace(/\/+$/, "") === "";
+}
 /**
 * Is this already-absolute href one of OUR routes?
 *
@@ -28,9 +32,11 @@ function isRelativeLink(href) {
 * A typo in a hand-written absolute link is exactly as likely as one in a
 * relative link; only the rewriting differs.
 *
-* Requires a non-empty base path. Docs mounted at the site root cannot be told
-* apart from the rest of the site, and asserting `/login` against the set of
-* documentation routes would fail builds over links that are perfectly good.
+* Answers `false` at a root mount, where there is no prefix to test against.
+* That is not the end of the matter: the caller records those links anyway,
+* marked, because at a root mount the *common* case is an origin that serves
+* documentation and nothing else — so they are checked, and a site with other
+* routes names them through `externalRoutes`.
 */
 function isInternalAbsoluteLink(href, basePath) {
 	const base = basePath.replace(/\/+$/, "");
@@ -107,11 +113,31 @@ function decodeSegment(segment, href) {
 * Decode BEFORE folding, never after: `%2E%2E%2F` is `../` in disguise, and
 * `foldSegments` is the only thing that refuses a chain climbing out of the
 * content root.
+*
+* Exported for `route-path.ts`, which needs the decode without the split:
+* an alias may carry a literal `#` or `?` — `c# guide` is a page name — and
+* {@link splitHref} would cut the string there and throw the rest away.
 */
 function decodePath(path, href) {
 	return path.split("/").map((segment) => decodeSegment(segment, href)).join("/");
 }
 /**
+* Split an href into its path, query and fragment; decode only the path.
+*
+* Throws a {@link URIError} if the path is not valid percent-encoding, with the
+* whole href in the message — see {@link decodeSegment}.
+*/
+function splitHref(href) {
+	const parts = HREF_PARTS.exec(href);
+	const rawPath = parts?.[1] ?? "";
+	return {
+		path: decodePath(rawPath, href),
+		rawPath,
+		query: parts?.[2] ?? "",
+		hash: parts?.[3] ?? ""
+	};
+}
+/**
 * The built-in {@link LinkResolver}: markdown file path in, route out.
 *
 * Exported for reuse by hosts that want to wrap rather than replace it. Throws
@@ -119,12 +145,9 @@ function decodePath(path, href) {
 * reported as `undefined`.
 */
 function resolveMarkdownLink(href, fromDir, basePath) {
-	const parts = HREF_PARTS.exec(href);
-	const path = parts?.[1] ?? "";
-	const query = parts?.[2] ?? "";
-	const hash = parts?.[3] ?? "";
+	const { path, query, hash } = splitHref(href);
 	if (path === "") return;
-	const segments = foldSegments(fromDir, decodePath(path, href));
+	const segments = foldSegments(fromDir, path);
 	if (segments === void 0) return;
 	const last = segments.at(-1);
 	if (last !== void 0) {
@@ -149,12 +172,9 @@ function resolveMarkdownLink(href, fromDir, basePath) {
 * browser resolves happily and `knownRoutes` has never heard of.
 */
 function normalizeInternalRoute(href, basePath) {
-	const parts = HREF_PARTS.exec(href);
-	const path = parts?.[1] ?? "";
-	const query = parts?.[2] ?? "";
-	const hash = parts?.[3] ?? "";
+	const { rawPath, query, hash } = splitHref(href);
 	const base = basePath.replace(/\/+$/, "");
-	const segments = foldSegments([], decodePath(path.slice(base.length), href));
+	const segments = foldSegments([], decodePath(rawPath.slice(base.length), href));
 	if (segments === void 0) return;
 	return `${toRoute(basePath, segments)}${query}${hash}`;
 }
@@ -183,11 +203,8 @@ function isAssetLink(href) {
 * the exception.
 */
 function resolveAssetLink(href, fromDir, basePath) {
-	const parts = HREF_PARTS.exec(href);
-	const path = parts?.[1] ?? "";
-	const query = parts?.[2] ?? "";
-	const hash = parts?.[3] ?? "";
-	const segments = foldSegments(fromDir, decodePath(path, href));
+	const { path, query, hash } = splitHref(href);
+	const segments = foldSegments(fromDir, path);
 	if (segments === void 0) return;
 	return `${toRoute(basePath, segments)}${query}${hash}`;
 }
@@ -213,23 +230,33 @@ const remarkDocLinks = (options) => {
 			const raw = node.url;
 			if (node.type === "definition" && imageIdentifiers.has(node.identifier)) continue;
 			const line = node.position?.start.line;
-			const record = (href, asset) => {
+			const record = (href, flags = {}) => {
 				const ref = {
 					raw,
 					href
 				};
 				if (line !== void 0) ref.line = line;
-				if (asset !== void 0) ref.asset = asset;
+				if (flags.asset !== void 0) ref.asset = flags.asset;
+				if (flags.unverifiable !== void 0) ref.unverifiable = flags.unverifiable;
+				if (flags.anchorOnly !== void 0) ref.anchorOnly = flags.anchorOnly;
 				refs.push(ref);
 				if (href !== void 0) node.url = href;
 			};
 			try {
+				if (raw.startsWith("#")) {
+					record(raw, { anchorOnly: true });
+					continue;
+				}
 				if (!isRelativeLink(raw)) {
-					if (isInternalAbsoluteLink(raw, basePath) && !isAssetLink(raw)) record(normalizeInternalRoute(raw, basePath));
+					if (isInternalAbsoluteLink(raw, basePath) && !isAssetLink(raw)) {
+						record(normalizeInternalRoute(raw, basePath));
+						continue;
+					}
+					if (isRootMount(basePath) && raw.startsWith("/") && !raw.startsWith("//") && !isAssetLink(raw)) record(normalizeInternalRoute(raw, basePath), { unverifiable: true });
 					continue;
 				}
 				if (resolve === void 0 && isAssetLink(raw)) {
-					record(resolveAssetLink(raw, context.dirSegments, basePath), true);
+					record(resolveAssetLink(raw, context.dirSegments, basePath), { asset: true });
 					continue;
 				}
 				if (resolve) {
@@ -246,4 +273,4 @@ const remarkDocLinks = (options) => {
 	};
 };
 //#endregion
-export { foldSegments, remarkDocLinks, resolveMarkdownLink };
+export { decodePath, foldSegments, isRootMount, remarkDocLinks, resolveMarkdownLink, splitHref };

package/dist/plugins/remark-youtube.d.ts

@@ -1,13 +1,28 @@
 import { Plugin } from "unified";
 import { Root } from "mdast";
 //#region src/plugins/remark-youtube.d.ts
+/** What a YouTube URL says, beyond which video it is. */
+interface YouTubeRef {
+  id: string;
+  /** Seconds to start at, from `t` or `start`. */
+  start?: number | undefined;
+  /** Playlist the video was linked inside, from `list`. */
+  list?: string | undefined;
+}
 /**
- * Extract a video id from a YouTube watch/short/embed URL.
+ * Extract a video reference from a YouTube watch/short/embed URL.
  *
  * Returns `undefined` for anything else, including YouTube URLs that are not a
  * single video (channels, playlists) — those stay ordinary links.
+ *
+ * ⚠️ THE TIMESTAMP AND THE PLAYLIST ARE PART OF THE LINK, AND WERE DROPPED. Only
+ * the id survived, so `https://youtu.be/x?t=754` — a link to one specific moment
+ * in a two-hour talk, which is most of why anyone deep-links a video — opened at
+ * zero. And because the facade passes `autoplay=1`, it did not merely start in
+ * the wrong place: it started *playing* in the wrong place, so the reader had to
+ * work out that the author had meant somewhere else.
  */
-declare function parseYouTubeId(href: string): string | undefined;
+declare function parseYouTubeRef(href: string): YouTubeRef | undefined;
 /**
  * remark plugin. Replaces the whole PARAGRAPH, not the link inside it — which
  * is the point: leaving the paragraph is what nested a block element in
@@ -19,4 +34,4 @@ declare function parseYouTubeId(href: string): string | undefined;
  */
 declare const remarkYouTube: Plugin<[], Root>;
 //#endregion
-export { parseYouTubeId, remarkYouTube };
+export { YouTubeRef, parseYouTubeRef, remarkYouTube };

package/dist/plugins/remark-youtube.js

@@ -4,13 +4,40 @@ import { SKIP, visit } from "unist-util-visit";
 const VIDEO_ID = /^[A-Za-z0-9_-]{11}$/;
 /** `https://` or `http://`, for comparing a label against its own href. */
 const HTTP_SCHEME = /^https?:\/\//i;
+/** A playlist id, conservatively: what YouTube uses and nothing else. */
+const PLAYLIST_ID = /^[A-Za-z0-9_-]{2,64}$/;
 /**
-* Extract a video id from a YouTube watch/short/embed URL.
+* `1h2m3s`, `90s`, `90` — every spelling YouTube's own `t` parameter takes.
+*/
+const TIMESTAMP = /^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s?)?$/;
+/**
+* Seconds from a `t`/`start` value, or `undefined` if it is not one.
+*
+* YouTube accepts `t=90`, `t=90s` and `t=1m30s`, and an author linking to a
+* moment in a talk pastes whichever the share dialog gave them.
+*/
+function parseTimestamp(value) {
+	if (value === null || value === "") return void 0;
+	const match = TIMESTAMP.exec(value);
+	if (match === null) return void 0;
+	const [, hours, minutes, seconds] = match;
+	const total = Number(hours ?? 0) * 3600 + Number(minutes ?? 0) * 60 + Number(seconds ?? 0);
+	return Number.isFinite(total) && total > 0 ? total : void 0;
+}
+/**
+* Extract a video reference from a YouTube watch/short/embed URL.
 *
 * Returns `undefined` for anything else, including YouTube URLs that are not a
 * single video (channels, playlists) — those stay ordinary links.
+*
+* ⚠️ THE TIMESTAMP AND THE PLAYLIST ARE PART OF THE LINK, AND WERE DROPPED. Only
+* the id survived, so `https://youtu.be/x?t=754` — a link to one specific moment
+* in a two-hour talk, which is most of why anyone deep-links a video — opened at
+* zero. And because the facade passes `autoplay=1`, it did not merely start in
+* the wrong place: it started *playing* in the wrong place, so the reader had to
+* work out that the author had meant somewhere else.
 */
-function parseYouTubeId(href) {
+function parseYouTubeRef(href) {
 	let url;
 	try {
 		url = new URL(href, "https://example.invalid");
@@ -19,17 +46,34 @@ function parseYouTubeId(href) {
 	}
 	const host = url.hostname.replace(/^(www|m)\./, "");
 	const segments = url.pathname.split("/").filter(Boolean);
+	const extras = () => {
+		const start = parseTimestamp(url.searchParams.get("t")) ?? parseTimestamp(url.searchParams.get("start")) ?? parseTimestamp(url.hash.replace(/^#t=/, "") || null);
+		const list = url.searchParams.get("list");
+		return {
+			...start === void 0 ? {} : { start },
+			...list !== null && PLAYLIST_ID.test(list) ? { list } : {}
+		};
+	};
 	if (host === "youtu.be") {
 		const [id] = segments;
-		return id !== void 0 && VIDEO_ID.test(id) ? id : void 0;
+		return id !== void 0 && VIDEO_ID.test(id) ? {
+			id,
+			...extras()
+		} : void 0;
 	}
 	if (host !== "youtube.com" && host !== "youtube-nocookie.com") return;
 	if (url.pathname === "/watch") {
 		const id = url.searchParams.get("v");
-		return id !== null && VIDEO_ID.test(id) ? id : void 0;
+		return id !== null && VIDEO_ID.test(id) ? {
+			id,
+			...extras()
+		} : void 0;
 	}
 	const [prefix, id] = segments;
-	if ((prefix === "embed" || prefix === "shorts") && id !== void 0) return VIDEO_ID.test(id) ? id : void 0;
+	if ((prefix === "embed" || prefix === "shorts") && id !== void 0) return VIDEO_ID.test(id) ? {
+		id,
+		...extras()
+	} : void 0;
 }
 /** Whitespace-only text is what separates two links on consecutive lines. */
 function isIgnorable(node) {
@@ -66,14 +110,18 @@ const remarkYouTube = () => {
 			const meaningful = node.children.filter((child) => !isIgnorable(child));
 			const only = meaningful[0];
 			if (meaningful.length !== 1 || only === void 0 || !isBareUrl(only)) return;
-			const id = only.type === "link" ? parseYouTubeId(only.url) : void 0;
-			if (id === void 0) return;
+			const ref = only.type === "link" ? parseYouTubeRef(only.url) : void 0;
+			if (ref === void 0) return;
 			parent.children[index] = {
 				type: "paragraph",
 				children: [],
 				data: {
 					hName: "youtube",
-					hProperties: { id }
+					hProperties: {
+						id: ref.id,
+						...ref.start === void 0 ? {} : { start: ref.start },
+						...ref.list === void 0 ? {} : { list: ref.list }
+					}
 				}
 			};
 			return [SKIP, index + 1];
@@ -81,4 +129,4 @@ const remarkYouTube = () => {
 	};
 };
 //#endregion
-export { parseYouTubeId, remarkYouTube };
+export { parseYouTubeRef, remarkYouTube };

package/dist/react/callout.d.ts

@@ -16,6 +16,18 @@ interface CalloutProps {
   type?: string | undefined;
   /** Overrides the default label ("Note", "Warning", …). */
   title?: string | undefined;
+  /**
+   * Default headings per type, for a site that is not in English.
+   *
+   * `title` still wins — it is what a single callout in the markdown asked for,
+   * and this is what every callout on the site is called otherwise.
+   *
+   * Here rather than resolved by the caller so that {@link normalizeCalloutType}
+   * stays the one place that decides what an unrecognised type falls back to. A
+   * caller picking the heading itself would need that rule too, and a second
+   * copy of it is a second thing to keep in step.
+   */
+  labels?: Partial<Record<CalloutType, string>> | undefined;
   className?: string | undefined;
   children?: ReactNode;
 }
@@ -32,6 +44,6 @@ interface CalloutProps {
  * All styling lives in `@waveso/docs/styles.css` under `.wave-docs-callout`,
  * so consumers can restyle it without forking the component.
  */
-declare function Callout({ type, title, className, children }: CalloutProps): ReactNode;
+declare function Callout({ type, title, labels, className, children }: CalloutProps): ReactNode;
 //#endregion
 export { CALLOUT_TYPES, Callout, CalloutProps, CalloutType };

package/dist/react/callout.js

@@ -69,9 +69,9 @@ function normalizeCalloutType(value) {
 * All styling lives in `@waveso/docs/styles.css` under `.wave-docs-callout`,
 * so consumers can restyle it without forking the component.
 */
-function Callout({ type, title, className, children }) {
+function Callout({ type, title, labels, className, children }) {
 	const kind = normalizeCalloutType(type);
-	const label = title?.trim() || CALLOUT_LABELS[kind];
+	const label = title?.trim() || labels?.[kind] || CALLOUT_LABELS[kind];
 	return /* @__PURE__ */ jsxs("aside", {
 		role: "note",
 		"aria-label": label,

package/dist/react/code-runtime.d.ts

@@ -1,5 +1,15 @@
 import { ReactNode } from "react";
 //#region src/react/code-runtime.d.ts
+/** The two announcements, for a site that is not in English. */
+interface CodeRuntimeLabels {
+  /** 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.'`
+   */
+  copyFailed?: string | undefined;
+}
 /**
  * Mount the copy runtime. Renders nothing.
  *
@@ -9,6 +19,6 @@ import { ReactNode } from "react";
  * re-renders and there is no state to get out of step with a page that was
  * server-rendered.
  */
-declare function DocsCodeRuntime(): ReactNode;
+declare function DocsCodeRuntime({ copied, copyFailed }?: CodeRuntimeLabels): ReactNode;
 //#endregion
-export { DocsCodeRuntime };
+export { CodeRuntimeLabels, DocsCodeRuntime };

package/dist/react/code-runtime.js

@@ -40,6 +40,24 @@ const SKIP_LINE_CLASSES = [];
 const TRIMMED_LINE_CLASSES = [];
 let refCount = 0;
 let detach;
+const DEFAULT_COPIED = "Copied to the clipboard.";
+const DEFAULT_COPY_FAILED = "Copy failed. Select the code and press Control or Command + C.";
+/**
+* Module scope, beside `refCount`, because the listener is a singleton too.
+*
+* The runtime installs once per page however many `DocContent`s mount it, so
+* the messages belong to the installation rather than to a component — and two
+* mounts with different labels would be a page with two languages in it, which
+* is not a case worth code. First one in wins, and `refCount` says which.
+*
+* Spelled out rather than `Required<CodeRuntimeLabels>`: the props are declared
+* `string | undefined` for `exactOptionalPropertyTypes`, and `Required` strips
+* the `?` while leaving the `undefined` in the value type.
+*/
+let messages = {
+	copied: DEFAULT_COPIED,
+	copyFailed: DEFAULT_COPY_FAILED
+};
 /**
 * Mount the copy runtime. Renders nothing.
 *
@@ -49,10 +67,16 @@ let detach;
 * re-renders and there is no state to get out of step with a page that was
 * server-rendered.
 */
-function DocsCodeRuntime() {
+function DocsCodeRuntime({ copied, copyFailed } = {}) {
 	useEffect(() => {
 		refCount += 1;
-		if (refCount === 1) detach = install();
+		if (refCount === 1) {
+			messages = {
+				copied: copied ?? DEFAULT_COPIED,
+				copyFailed: copyFailed ?? DEFAULT_COPY_FAILED
+			};
+			detach = install();
+		}
 		return () => {
 			refCount -= 1;
 			if (refCount === 0) {
@@ -60,7 +84,7 @@ function DocsCodeRuntime() {
 				detach = void 0;
 			}
 		};
-	}, []);
+	}, [copied, copyFailed]);
 	return null;
 }
 function install() {
@@ -110,7 +134,7 @@ function readCode(pre) {
 async function copy(text, button, status) {
 	const copied = await writeClipboard(text) ? "true" : "false";
 	button.dataset.copied = copied;
-	status.textContent = copied === "true" ? "Copied to the clipboard." : "Copy failed. Select the code and press Control or Command + C.";
+	status.textContent = copied === "true" ? messages.copied : messages.copyFailed;
 	const existing = timers.get(button);
 	if (existing !== void 0) window.clearTimeout(existing);
 	timers.set(button, window.setTimeout(() => {

package/dist/react/doc-content.d.ts

@@ -1,4 +1,5 @@
 import { MarkdownComponents } from "./markdown-components.js";
+import { CodeRuntimeLabels } from "./code-runtime.js";
 import { ReactNode } from "react";
 import { Root } from "hast";
 //#region src/react/doc-content.d.ts
@@ -20,6 +21,16 @@ interface DocContentProps {
    * choice rather than as a mistake.
    */
   className?: string | undefined;
+  /**
+   * The two things the copy runtime announces, for a site that is not in
+   * English.
+   *
+   * Here rather than on `docs.Layout` because this is the component that mounts
+   * the runtime, and it is the one no consumer can avoid — the hand-rolled route
+   * in the README renders it directly. Forwarded only when set, so a site that
+   * overrides nothing sends no extra props across the boundary.
+   */
+  labels?: CodeRuntimeLabels | undefined;
 }
 /**
  * Render a hast tree as React elements, inside the prose wrapper.
@@ -61,6 +72,6 @@ interface DocContentProps {
  * you, because `node` is a legal prop on the component and an unknown attribute
  * on the element.
  */
-declare function DocContent({ hast, components, className }: DocContentProps): ReactNode;
+declare function DocContent({ hast, components, className, labels }: DocContentProps): ReactNode;
 //#endregion
 export { DocContent, DocContentProps };

package/dist/react/doc-content.js

@@ -44,10 +44,10 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 * you, because `node` is a legal prop on the component and an unknown attribute
 * on the element.
 */
-function DocContent({ hast, components, className }) {
+function DocContent({ hast, components, className, labels }) {
 	return /* @__PURE__ */ jsxs("div", {
 		className: className === void 0 || className === "" ? "wave-docs-prose" : `wave-docs-prose ${className}`,
-		children: [hasCodeFrame(hast) ? /* @__PURE__ */ jsx(DocsCodeRuntime, {}) : null, toJsxRuntime(hast, {
+		children: [hasCodeFrame(hast) ? /* @__PURE__ */ jsx(DocsCodeRuntime, { ...labels }) : null, toJsxRuntime(hast, {
 			Fragment,
 			jsx,
 			jsxs,

package/dist/react/layout.d.ts

@@ -1,6 +1,7 @@
 import { DocNavNode } from "../types.js";
-import { DocsSearchProps } from "./next-search.js";
+import { SerializableSearchOptions } from "../search-options.js";
 import { DocsLabels } from "./shell-labels.js";
+import { DocsSearchProps } from "./next-search.js";
 import { ReactNode } from "react";
 //#region src/react/layout.d.ts
 /**
@@ -9,8 +10,19 @@ import { ReactNode } from "react";
  * `indexUrl` is derived from `basePath` and is not negotiable here: the whole
  * reason `docs.Layout` exists is that nobody should have to know the index's
  * address, and a hand-passed one is wrong under every non-root `basePath`.
+ *
+ * `miniSearchOptions` is narrower than the one `DocsSearch` itself takes, and
+ * has to be. `docs.Layout` is a Server Component and `DocsSearch` is a Client
+ * Component, so everything here is serialised on its way across — a `tokenize`
+ * or a `processTerm` passed at this seam fails `next build` with *"Functions
+ * cannot be passed directly to Client Components"*. {@link
+ * SerializableSearchOptions} documents the escape hatch: a `'use client'`
+ * wrapper of your own, where the function is a module import on both sides
+ * rather than a prop between them.
  */
-type DocsLayoutSearchProps = Omit<DocsSearchProps, 'indexUrl'>;
+type DocsLayoutSearchProps = Omit<DocsSearchProps, 'indexUrl' | 'miniSearchOptions'> & {
+  miniSearchOptions?: SerializableSearchOptions | undefined;
+};
 interface DocsLayoutShellProps {
   children: ReactNode;
   nav: DocNavNode[];
@@ -20,14 +32,19 @@ interface DocsLayoutShellProps {
   /**
    * `false` to omit the trigger; an object to configure it.
    *
-   * ⚠️ AN OBJECT IS WHAT MAKES `miniSearchOptions` REACHABLE. MiniSearch reads
-   * `tokenize` and `processTerm` both when indexing and when querying, so the
-   * object `createDocsRoute` built the index with has to be the object the
-   * dialog queries it with — and while this was a bare boolean there was no
-   * channel for it at all. Configuring the route and rendering `docs.Layout`
-   * produced an index whose terms no query could spell: zero results, no error,
-   * nothing in the console, and the option's own docstring warning about
-   * exactly that.
+   * ⚠️ AN OBJECT IS WHAT MAKES `miniSearchOptions` REACHABLE, AND ONLY THE
+   * SERIALISABLE PART OF IT. MiniSearch reads `tokenize` and `processTerm` both
+   * when indexing and when querying, so the object `createDocsRoute` built the
+   * index with has to be the object the dialog queries it with — and while this
+   * was a bare boolean there was no channel for it at all. Configuring the
+   * route and rendering `docs.Layout` produced an index whose terms no query
+   * could spell: zero results, no error, nothing in the console.
+   *
+   * Widening it to a boolean-or-object fixed that for data overrides and broke
+   * the function ones, which is the harder half: this prop is serialised on its
+   * way from a Server Component to a Client one, so a function in it is a build
+   * failure rather than a silent miss. `createDocsRoute` refuses to forward one
+   * and says so; {@link DocsLayoutSearchProps} carries the remedy.
    */
   search?: boolean | DocsLayoutSearchProps | undefined;
   /**

package/dist/react/layout.js

@@ -38,8 +38,8 @@ function DocsLayoutShell({ children, nav, searchIndexUrl, title, actions, search
 					}),
 					search === false ? null : /* @__PURE__ */ jsx(DocsSearch, {
 						indexUrl: searchIndexUrl,
-						className: "wave-docs-layout__search",
-						...search === true ? {} : search
+						...search === true ? {} : search,
+						className: ["wave-docs-layout__search", search === true ? void 0 : search?.className].filter(Boolean).join(" ")
 					}),
 					actions === void 0 ? null : /* @__PURE__ */ jsx("div", {
 						className: "wave-docs-layout__actions",
@@ -55,7 +55,10 @@ function DocsLayoutShell({ children, nav, searchIndexUrl, title, actions, search
 				children: /* @__PURE__ */ jsx(DocsNextNav, {
 					nav,
 					label: text.nav,
-					closeLabel: text.closeNav
+					closeLabel: text.closeNav,
+					...labels?.expandGroup === void 0 ? {} : { expandGroup: labels.expandGroup },
+					...labels?.collapseGroup === void 0 ? {} : { collapseGroup: labels.collapseGroup },
+					...labels?.externalLink === void 0 ? {} : { externalLink: labels.externalLink }
 				})
 			}), children]
 		})

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

@@ -0,0 +1,34 @@
+import { DocsLinkComponent } from "./markdown-components.js";
+import { ComponentProps, ComponentType } from "react";
+//#region src/react/link-adapter.d.ts
+/**
+ * The part of `next/link` this package uses.
+ *
+ * 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`.
+ */
+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;
+//#endregion
+export { NextLinkComponent, wrapNextLink };

package/dist/react/link-adapter.js

@@ -0,0 +1,30 @@
+import { createElement } from "react";
+//#region src/react/link-adapter.ts
+/**
+* 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.
+*/
+function wrapNextLink(NextLink) {
+	return function DocsNextLink({ href, prefetch, children, ...rest }) {
+		return createElement(NextLink, {
+			...rest,
+			href,
+			...prefetch === void 0 ? {} : { prefetch }
+		}, children);
+	};
+}
+//#endregion
+export { wrapNextLink };

package/dist/react/markdown-components.d.ts

@@ -1,4 +1,5 @@
 import { CalloutProps } from "./callout.js";
+import { DocsLabels } from "./shell-labels.js";
 import { YouTubeProps } from "./youtube.js";
 import { ComponentProps, ComponentType, JSX, ReactNode } from "react";
 //#region src/react/markdown-components.d.ts
@@ -53,6 +54,20 @@ interface DocsImageProps {
   className?: string | undefined;
   sizes?: string | undefined;
   loading?: 'eager' | 'lazy' | undefined;
+  /**
+   * Passed through to the image. Defaults to `'async'` on the plain `<img>`.
+   *
+   * ⚠️ DECLARED BECAUSE THE COMMENT BELOW PROMISED IT AND THE CODE DROPPED IT.
+   * `createImage` spreads the tree's own attributes into whichever component it
+   * was given, with a comment saying `decoding` and `fetchPriority` survive into
+   * the optimising branch — and `wrapNextImage` destructures a fixed list, so
+   * they did not. A closed props interface is the right shape for this seam, so
+   * the two the comment named are members of it now rather than a promise it
+   * could not keep.
+   */
+  decoding?: 'async' | 'auto' | 'sync' | undefined;
+  /** Passed through to the image. `'high'` on a hero image is the usual reason. */
+  fetchPriority?: 'high' | 'low' | 'auto' | undefined;
 }
 /** A `next/image`-compatible component. */
 type DocsImageComponent = ComponentType<DocsImageProps>;
@@ -61,7 +76,20 @@ interface MarkdownComponentsOptions {
   Link?: DocsLinkComponent | undefined;
   /** Optimising image component, e.g. `next/image`. Falls back to `<img>`. */
   Image?: DocsImageComponent | undefined;
+  /**
+   * Overrides for the strings this map renders itself.
+   *
+   * Five callout headings, the external-link suffix, a wide table's region
+   * name and the YouTube facade's three — every one of them hardcoded English
+   * until this existed, on a shell whose `labels` prop claimed to be the whole
+   * of a site's translatable chrome.
+   *
+   * All server-rendered, so overriding them costs no client bytes.
+   */
+  labels?: MarkdownLabels | undefined;
 }
+/** The subset of `DocsLabels` this map is responsible for. */
+type MarkdownLabels = Pick<DocsLabels, 'externalLink' | 'table' | 'calloutNote' | 'calloutTip' | 'calloutImportant' | 'calloutWarning' | 'calloutCaution' | 'youtubeTitle' | 'youtubePlay' | 'youtubeHide'>;
 /**
  * Build the default component map, optionally injecting host-specific link and
  * image components.
@@ -81,4 +109,4 @@ declare function createMarkdownComponents(options?: MarkdownComponentsOptions):
 /** The map used when a caller supplies none. Plain `<a>` and `<img>`. */
 declare const defaultMarkdownComponents: MarkdownComponents;
 //#endregion
-export { DocsImageComponent, DocsImageProps, DocsLinkComponent, DocsLinkProps, MarkdownComponents, MarkdownComponentsOptions, createMarkdownComponents, defaultMarkdownComponents };
+export { DocsImageComponent, DocsImageProps, DocsLinkComponent, DocsLinkProps, MarkdownComponents, MarkdownComponentsOptions, MarkdownLabels, createMarkdownComponents, defaultMarkdownComponents };