@waveso/docs 0.1.0 → 0.3.0

package/dist/react/layout.d.ts

@@ -0,0 +1,44 @@
+import { DocNavNode } from "../types.js";
+import { DocsSearchProps } from "./next-search.js";
+import { DocsLabels } from "./shell-labels.js";
+import { ReactNode } from "react";
+//#region src/react/layout.d.ts
+/**
+ * What a host may say about the search trigger, minus the URL.
+ *
+ * `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`.
+ */
+type DocsLayoutSearchProps = Omit<DocsSearchProps, 'indexUrl'>;
+interface DocsLayoutShellProps {
+  children: ReactNode;
+  nav: DocNavNode[];
+  searchIndexUrl: string;
+  title?: ReactNode;
+  actions?: ReactNode;
+  /**
+   * `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.
+   */
+  search?: boolean | DocsLayoutSearchProps | undefined;
+  /**
+   * The four strings the chrome renders, for a site that is not in English.
+   *
+   * `DocsNav` declared `label` and `closeLabel`, documented them and defaulted
+   * them — and this component, the only thing that renders `DocsNav`, never
+   * passed either. Configuration that could not be configured.
+   */
+  labels?: DocsLabels | undefined;
+}
+declare function DocsLayoutShell({ children, nav, searchIndexUrl, title, actions, search, labels }: DocsLayoutShellProps): ReactNode;
+//#endregion
+export { DocsLayoutSearchProps, DocsLayoutShell, DocsLayoutShellProps };

package/dist/react/layout.js

@@ -0,0 +1,65 @@
+import { DocsSearch } from "./next-search.js";
+import { resolveLabels } from "./shell-labels.js";
+import { DOCS_NAV_ID } from "./nav.js";
+import { DocsNextNav } from "./next-nav.js";
+import { SkipLink } from "./skip-link.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/layout.tsx
+function DocsLayoutShell({ children, nav, searchIndexUrl, title, actions, search = true, labels }) {
+	const text = resolveLabels(labels);
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		/* @__PURE__ */ jsx(SkipLink, { children: text.skipToContent }),
+		/* @__PURE__ */ jsx("header", {
+			className: "wave-docs-layout__header",
+			children: /* @__PURE__ */ jsxs("div", {
+				className: "wave-docs-layout__header-inner",
+				children: [
+					/* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: "wave-docs-layout__nav-trigger",
+						"aria-label": text.openNav,
+						command: "show-modal",
+						commandfor: DOCS_NAV_ID,
+						children: /* @__PURE__ */ jsx("svg", {
+							"aria-hidden": "true",
+							viewBox: "0 0 16 16",
+							width: "18",
+							height: "18",
+							fill: "none",
+							stroke: "currentColor",
+							strokeWidth: "1.5",
+							strokeLinecap: "round",
+							children: /* @__PURE__ */ jsx("path", { d: "M2.5 4h11M2.5 8h11M2.5 12h11" })
+						})
+					}),
+					title === void 0 ? null : /* @__PURE__ */ jsx("div", {
+						className: "wave-docs-layout__title",
+						children: title
+					}),
+					search === false ? null : /* @__PURE__ */ jsx(DocsSearch, {
+						indexUrl: searchIndexUrl,
+						className: "wave-docs-layout__search",
+						...search === true ? {} : search
+					}),
+					actions === void 0 ? null : /* @__PURE__ */ jsx("div", {
+						className: "wave-docs-layout__actions",
+						children: actions
+					})
+				]
+			})
+		}),
+		/* @__PURE__ */ jsxs("div", {
+			className: "wave-docs-layout",
+			children: [/* @__PURE__ */ jsx("div", {
+				className: "wave-docs-layout__sidebar",
+				children: /* @__PURE__ */ jsx(DocsNextNav, {
+					nav,
+					label: text.nav,
+					closeLabel: text.closeNav
+				})
+			}), children]
+		})
+	] });
+}
+//#endregion
+export { DocsLayoutShell };

package/dist/react/markdown-components.js

@@ -6,6 +6,62 @@ import { jsx, jsxs } from "react/jsx-runtime";
 const HTTP_SCHEME = /^https?:\/\//i;
 /** Any URL with a scheme, or protocol-relative. */
 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();
+/**
+* Say something when a link is dropped.
+*
+* A destination that vanishes with the text left behind is the quietest
+* possible failure — the page looks fine and the link is simply gone. Every
+* other rejection in this package names a file and a fix; this one cannot see
+* the file, so it names the href and stays out of production noise.
+*/
+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);
+}
 function joinClassNames(...values) {
 	const joined = values.filter(Boolean).join(" ");
 	return joined === "" ? void 0 : joined;
@@ -23,6 +79,10 @@ function createAnchor(Link) {
 			...rest,
 			children
 		});
+		if (!isSafeHref(href)) {
+			warnDroppedHref(href);
+			return /* @__PURE__ */ jsx("span", { children });
+		}
 		if (HTTP_SCHEME.test(href) || href.startsWith("//")) return /* @__PURE__ */ jsxs("a", {
 			...rest,
 			href,
@@ -46,28 +106,33 @@ function createAnchor(Link) {
 	};
 }
 function createImage(Image) {
-	return function MarkdownImage({ src, alt, width, height, title, className, ...rest }) {
+	return function MarkdownImage({ src, alt, width, height, title, className, sizes, loading, ...rest }) {
 		const resolvedWidth = toDimension(width);
 		const resolvedHeight = toDimension(height);
+		const resolvedLoading = loading ?? "lazy";
+		const resolvedClassName = joinClassNames("wave-docs-image", className);
 		if (Image !== void 0 && typeof src === "string" && resolvedWidth !== void 0 && resolvedHeight !== void 0) return /* @__PURE__ */ jsx(Image, {
+			...rest,
 			src,
 			alt: alt ?? "",
 			width: resolvedWidth,
 			height: resolvedHeight,
 			title,
-			className: joinClassNames("wave-docs-image", className),
-			loading: "lazy"
+			className: resolvedClassName,
+			sizes,
+			loading: resolvedLoading
 		});
 		return /* @__PURE__ */ jsx("img", {
+			decoding: "async",
 			...rest,
 			src,
 			alt: alt ?? "",
 			width,
 			height,
 			title,
-			className: joinClassNames("wave-docs-image", className),
-			loading: "lazy",
-			decoding: "async"
+			className: resolvedClassName,
+			sizes,
+			loading: resolvedLoading
 		});
 	};
 }

package/dist/react/nav.d.ts

@@ -0,0 +1,28 @@
+import { DocNavNode } from "../types.js";
+import { DocsLinkComponent } from "./markdown-components.js";
+import { ReactNode } from "react";
+//#region src/react/nav.d.ts
+/**
+ * The drawer's `id`, and the header trigger's `commandfor`.
+ *
+ * A constant rather than a `useId`, for two reasons that both matter: the
+ * trigger is rendered on the server in a different subtree and cannot see a
+ * hook's value, and `command`/`commandfor` must agree before React hydrates or
+ * the button does nothing on the first tap.
+ */
+declare const DOCS_NAV_ID = "wave-docs-nav";
+interface DocsNavProps {
+  /** The tree from `docs.source.nav()`. */
+  nav: DocNavNode[];
+  /** Current route. Injected, so this stays testable without a router. */
+  pathname: string;
+  /** Client-side router link, e.g. `next/link`. Falls back to `<a>`. */
+  Link?: DocsLinkComponent | undefined;
+  /** Accessible name for the nav landmark and the drawer. */
+  label?: string | undefined;
+  /** Accessible name for the close button. */
+  closeLabel?: string | undefined;
+}
+declare function DocsNav({ nav, pathname, Link, label, closeLabel }: DocsNavProps): ReactNode;
+//#endregion
+export { DOCS_NAV_ID, DocsNav, DocsNavProps };

package/dist/react/nav.js

@@ -0,0 +1,70 @@
+"use client";
+import { DocsSidebar } from "./sidebar.js";
+import { useEffect, useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/nav.tsx
+/**
+* The drawer's `id`, and the header trigger's `commandfor`.
+*
+* A constant rather than a `useId`, for two reasons that both matter: the
+* trigger is rendered on the server in a different subtree and cannot see a
+* hook's value, and `command`/`commandfor` must agree before React hydrates or
+* 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" }) {
+	const ref = useRef(null);
+	useEffect(() => {
+		ref.current?.close?.();
+	}, [pathname]);
+	useEffect(() => {
+		if ("command" in HTMLButtonElement.prototype) return;
+		const onClick = (event) => {
+			const target = event.target;
+			if (!(target instanceof Element)) return;
+			const button = target.closest("button[commandfor]");
+			if (button === null) return;
+			if (button.getAttribute("commandfor") !== "wave-docs-nav") return;
+			const dialog = ref.current;
+			if (dialog === null) return;
+			if (button.getAttribute("command") === "close") dialog.close();
+			else dialog.showModal();
+		};
+		document.addEventListener("click", onClick);
+		return () => {
+			document.removeEventListener("click", onClick);
+		};
+	}, []);
+	return /* @__PURE__ */ jsxs("dialog", {
+		ref,
+		id: DOCS_NAV_ID,
+		className: "wave-docs-layout__drawer",
+		closedby: "any",
+		"aria-label": label,
+		children: [/* @__PURE__ */ jsx("button", {
+			type: "button",
+			className: "wave-docs-layout__drawer-close",
+			"aria-label": closeLabel,
+			command: "close",
+			commandfor: DOCS_NAV_ID,
+			children: /* @__PURE__ */ jsx("svg", {
+				"aria-hidden": "true",
+				viewBox: "0 0 16 16",
+				width: "16",
+				height: "16",
+				fill: "none",
+				stroke: "currentColor",
+				strokeWidth: "1.5",
+				strokeLinecap: "round",
+				children: /* @__PURE__ */ jsx("path", { d: "M4 4l8 8M12 4l-8 8" })
+			})
+		}), /* @__PURE__ */ jsx(DocsSidebar, {
+			nav,
+			pathname,
+			label,
+			Link
+		})]
+	});
+}
+//#endregion
+export { DOCS_NAV_ID, DocsNav };

package/dist/react/nearest-scroll-top.d.ts

@@ -0,0 +1,45 @@
+//#region src/react/nearest-scroll-top.d.ts
+/**
+ * Where a scrollport should be scrolled to so an item inside it is visible,
+ * or `undefined` when it already is.
+ *
+ * Private, and pure, and separate from the component for one reason: this is
+ * the whole of the geometry, and geometry is the half that can be tested
+ * exhaustively. jsdom reports every rectangle as zero, so a test that drove
+ * the effect would assert nothing about the arithmetic.
+ *
+ * ## Why not `scrollIntoView`
+ *
+ * ⚠️ `element.scrollIntoView({ block: 'nearest' })` LOOKS LIKE THE ANSWER AND
+ * IS A TRAP. It scrolls **every** scrollable ancestor, the document included.
+ * On a docs page that means opening a deep link scrolls the sidebar *and*
+ * jumps the article the reader came to read — a page that silently moves under
+ * them, on the one navigation where they know exactly what they asked for.
+ *
+ * So the caller finds the nearest scrollable ancestor and assigns `scrollTop`
+ * itself. `sidebar.test.tsx` spies on `scrollIntoView` and asserts it is never
+ * called: a test for the API deliberately not used, which is the only thing
+ * that stops the page-jump being reintroduced by someone simplifying the code.
+ */
+interface NearestScrollTopInput {
+  /** The item's offset from the top of the scrollport's content. */
+  itemTop: number;
+  itemHeight: number;
+  /** The scrollport's visible height. */
+  viewHeight: number;
+  /** Where the scrollport is scrolled to now. */
+  scrollTop: number;
+  /** Total scrollable content height, used to clamp. */
+  scrollHeight: number;
+}
+/**
+ * The new `scrollTop`, or `undefined` when nothing should move.
+ *
+ * `undefined` for the already-visible case is not an optimisation: it is the
+ * common case — most navigations are to a page already on screen — and
+ * assigning `scrollTop` to its current value still cancels a smooth scroll in
+ * progress and still fires a `scroll` event.
+ */
+declare function nearestScrollTop({ itemTop, itemHeight, viewHeight, scrollTop, scrollHeight }: NearestScrollTopInput): number | undefined;
+//#endregion
+export { NearestScrollTopInput, nearestScrollTop };

package/dist/react/nearest-scroll-top.js

@@ -0,0 +1,44 @@
+//#region src/react/nearest-scroll-top.ts
+/**
+* Where a scrollport should be scrolled to so an item inside it is visible,
+* or `undefined` when it already is.
+*
+* Private, and pure, and separate from the component for one reason: this is
+* the whole of the geometry, and geometry is the half that can be tested
+* exhaustively. jsdom reports every rectangle as zero, so a test that drove
+* the effect would assert nothing about the arithmetic.
+*
+* ## Why not `scrollIntoView`
+*
+* ⚠️ `element.scrollIntoView({ block: 'nearest' })` LOOKS LIKE THE ANSWER AND
+* IS A TRAP. It scrolls **every** scrollable ancestor, the document included.
+* On a docs page that means opening a deep link scrolls the sidebar *and*
+* jumps the article the reader came to read — a page that silently moves under
+* them, on the one navigation where they know exactly what they asked for.
+*
+* So the caller finds the nearest scrollable ancestor and assigns `scrollTop`
+* itself. `sidebar.test.tsx` spies on `scrollIntoView` and asserts it is never
+* called: a test for the API deliberately not used, which is the only thing
+* that stops the page-jump being reintroduced by someone simplifying the code.
+*/
+/** Breathing room above or below the item, so it is not flush against the edge. */
+const MARGIN = 16;
+/**
+* The new `scrollTop`, or `undefined` when nothing should move.
+*
+* `undefined` for the already-visible case is not an optimisation: it is the
+* common case — most navigations are to a page already on screen — and
+* assigning `scrollTop` to its current value still cancels a smooth scroll in
+* progress and still fires a `scroll` event.
+*/
+function nearestScrollTop({ itemTop, itemHeight, viewHeight, scrollTop, scrollHeight }) {
+	if (viewHeight <= 0 || scrollHeight <= viewHeight) return void 0;
+	const itemBottom = itemTop + itemHeight;
+	const viewBottom = scrollTop + viewHeight;
+	const target = itemTop < scrollTop ? itemTop - MARGIN : itemBottom > viewBottom ? itemBottom - viewHeight + MARGIN : void 0;
+	if (target === void 0) return void 0;
+	const clamped = Math.max(0, Math.min(target, scrollHeight - viewHeight));
+	return itemHeight > viewHeight ? Math.max(0, Math.min(itemTop - MARGIN, scrollHeight - viewHeight)) : clamped;
+}
+//#endregion
+export { nearestScrollTop };

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

@@ -0,0 +1,34 @@
+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.
+ *
+ * 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/next-link.js

@@ -0,0 +1,30 @@
+import { createElement } from "react";
+//#region src/react/next-link.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/next-nav.d.ts

@@ -0,0 +1,11 @@
+import { DocNavNode } from "../types.js";
+import { ReactNode } from "react";
+//#region src/react/next-nav.d.ts
+interface DocsNextNavProps {
+  nav: DocNavNode[];
+  label?: string | undefined;
+  closeLabel?: string | undefined;
+}
+declare function DocsNextNav({ nav, label, closeLabel }: DocsNextNavProps): ReactNode;
+//#endregion
+export { DocsNextNav, DocsNextNavProps };

package/dist/react/next-nav.js

@@ -0,0 +1,32 @@
+"use client";
+import { wrapNextLink } from "./next-link.js";
+import { DocsNav } from "./nav.js";
+import { jsx } from "react/jsx-runtime";
+import NextLink from "next/link";
+import { usePathname } from "next/navigation";
+//#region src/react/next-nav.tsx
+/**
+* {@link DocsNav}, wired to Next's router.
+*
+* Private, and the **only** module in `src/react/` that imports
+* `next/navigation` — named so that is obvious from the file list. Everything
+* else in here takes `pathname` and `Link` as props, which is what lets the
+* components be tested without mounting a router and reused outside Next.
+*
+* The split is not ceremony: `usePathname` is why the consumer used to have to
+* hand-write a `'use client'` wrapper of their own, and deleting that file from
+* the README is most of what `docs.Layout` is for.
+*/
+/** Module scope: a fresh identity here remounts every nav link on every render. */
+const Link = wrapNextLink(NextLink);
+function DocsNextNav({ nav, label, closeLabel }) {
+	return /* @__PURE__ */ jsx(DocsNav, {
+		nav,
+		pathname: usePathname(),
+		Link,
+		...label === void 0 ? {} : { label },
+		...closeLabel === void 0 ? {} : { closeLabel }
+	});
+}
+//#endregion
+export { DocsNextNav };

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

@@ -0,0 +1,22 @@
+import { SearchDialogProps } from "./search-dialog.js";
+import { ReactNode } from "react";
+//#region src/react/next-search.d.ts
+/**
+ * Everything `SearchDialog` takes except the two things Next answers for you.
+ *
+ * `indexUrl` stays required, and `docs.searchIndexUrl` is the only value
+ * anyone should pass: defaulting it to `/search-index.json` would be wrong
+ * under every non-root `basePath`, and wrong as a 404 the reader hits and the
+ * author never sees.
+ */
+type DocsSearchProps = Omit<SearchDialogProps, 'navigate' | 'Link'>;
+/**
+ * Search trigger and dialog for a Next application.
+ *
+ * `next/link` is passed through rather than left to the plain-anchor fallback,
+ * so hovering a result prefetches the page it points at — which is most of why
+ * a hit feels instant when you press Enter.
+ */
+declare function DocsSearch(props: DocsSearchProps): ReactNode;
+//#endregion
+export { DocsSearch, DocsSearchProps };

package/dist/react/next-search.js

@@ -0,0 +1,52 @@
+"use client";
+import { wrapNextLink } from "./next-link.js";
+import { SearchDialog } from "./search-dialog.js";
+import { useCallback } from "react";
+import { jsx } from "react/jsx-runtime";
+import NextLink from "next/link";
+import { useRouter } from "next/navigation";
+//#region src/react/next-search.tsx
+/**
+* {@link SearchDialog}, wired to Next's router and `next/link`.
+*
+* `SearchDialog` takes `navigate` and `Link` as props so it stays
+* host-agnostic, and that seam is why its own tests are worth having — they
+* assert behaviour against a stub router rather than mounting Next. But this
+* package is a Next adapter, so in practice every consumer wrote the same
+* fifteen-line `'use client'` wrapper around `useRouter().push` and
+* `next/link`, and the ones who skipped `Link` lost hover prefetching on
+* every result without anything telling them.
+*
+* So it ships. The same bargain `createDocsRoute` already strikes on the
+* server, where `next/link` and `next/image` are wired by default and
+* overridable through `components`.
+*
+* ```tsx
+* // app/docs/layout.tsx — a Server Component; this file carries the boundary
+* import { DocsSearch } from '@waveso/docs/react/next-search';
+* import { docs } from '@/lib/docs';
+*
+* <DocsSearch indexUrl={docs.searchIndexUrl} />
+* ```
+*/
+const Link = wrapNextLink(NextLink);
+/**
+* Search trigger and dialog for a Next application.
+*
+* `next/link` is passed through rather than left to the plain-anchor fallback,
+* so hovering a result prefetches the page it points at — which is most of why
+* a hit feels instant when you press Enter.
+*/
+function DocsSearch(props) {
+	const router = useRouter();
+	const navigate = useCallback((href) => {
+		router.push(href);
+	}, [router]);
+	return /* @__PURE__ */ jsx(SearchDialog, {
+		...props,
+		navigate,
+		Link
+	});
+}
+//#endregion
+export { DocsSearch };

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

@@ -1,5 +1,7 @@
+import { SearchRecord } from "../types.js";
 import { DocsLinkComponent } from "./markdown-components.js";
 import { ReactNode } from "react";
+import { Options } from "minisearch";
 //#region src/react/search-dialog.d.ts
 interface SearchDialogProps {
   /**
@@ -17,17 +19,43 @@ interface SearchDialogProps {
    * Optional link component for results, e.g. `next/link`, so hovering a hit
    * prefetches the page. Results fall back to a plain anchor.
    */
-  Link?: DocsLinkComponent;
+  Link?: DocsLinkComponent | undefined;
   /** Trigger button label. Defaults to `'Search'`. */
-  triggerLabel?: string;
+  triggerLabel?: string | undefined;
   /** Input placeholder. Defaults to `'Search documentation'`. */
-  placeholder?: string;
+  placeholder?: string | undefined;
   /** Accessible name for the dialog. Defaults to `'Search documentation'`. */
-  dialogLabel?: string;
+  dialogLabel?: string | undefined;
   /** Maximum results rendered. Defaults to 8. */
-  maxResults?: number;
+  maxResults?: number | undefined;
   /** Input debounce in milliseconds. Defaults to 120. */
-  debounceMs?: number;
+  debounceMs?: number | undefined;
+  /** Extra class names for the trigger button, e.g. a navbar's own layout. */
+  className?: string | undefined;
+  /**
+   * Overrides applied through `mergeSearchOptions` when the index is
+   * deserialised — the escape hatch for tokenisation, `processTerm` and the
+   * query defaults, without waiting on a release of this package.
+   *
+   * MiniSearch's own name for the query defaults is `searchOptions`, so they
+   * nest one level down:
+   *
+   * ```tsx
+   * <DocsSearch miniSearchOptions={{ searchOptions: { fuzzy: 0.1 } }} />
+   * ```
+   *
+   * That stutter is why this prop is not called `searchOptions` too. It was,
+   * and `searchOptions={{ fuzzy: 0.1 }}` reads so naturally that both README
+   * examples were written that way — neither compiled, and the flat form is
+   * not a runtime error either. It is a `fuzzy` MiniSearch never reads.
+   *
+   * ⚠️ HAND THE IDENTICAL OVERRIDES TO THE BUILD — `createDocsRoute`'s
+   * `miniSearchOptions`, or `buildSearchIndex`'s second argument. `tokenize`
+   * and `processTerm` decide how terms were written into the index; a client
+   * that splits differently from the build looks up terms that were never
+   * written and finds nothing, silently.
+   */
+  miniSearchOptions?: Partial<Options<SearchRecord>> | undefined;
 }
 /**
  * Search trigger plus its dialog.
@@ -36,6 +64,6 @@ interface SearchDialogProps {
  * portalled to `document.body`, so a navbar's stacking context cannot trap
  * it behind the page.
  */
-declare function SearchDialog({ indexUrl, navigate, Link, triggerLabel, placeholder, dialogLabel, maxResults, debounceMs }: SearchDialogProps): ReactNode;
+declare function SearchDialog({ indexUrl, navigate, Link, triggerLabel, placeholder, dialogLabel, maxResults, debounceMs, className, miniSearchOptions }: SearchDialogProps): ReactNode;
 //#endregion
 export { SearchDialog, SearchDialogProps };