npm - @waveso/docs - Versions diffs - 0.2.0 → 0.3.0 - Mend

@waveso/docs 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (59) hide show

package/CHANGELOG.md +110 -0
package/README.md +490 -75
package/dist/code-frame.d.ts +29 -0
package/dist/code-frame.js +41 -0
package/dist/code-meta.d.ts +48 -0
package/dist/code-meta.js +72 -0
package/dist/docs-content-id.d.ts +19 -0
package/dist/docs-content-id.js +19 -0
package/dist/docs-error.d.ts +2 -57
package/dist/docs-error.js +3 -15
package/dist/errors.d.ts +94 -0
package/dist/errors.js +45 -0
package/dist/next.d.ts +153 -28
package/dist/next.js +65 -33
package/dist/plugins/rehype-capture-toc.js +26 -5
package/dist/plugins/rehype-code-frame.d.ts +10 -0
package/dist/plugins/rehype-code-frame.js +88 -0
package/dist/plugins/rehype-code-language.js +7 -1
package/dist/react/code-runtime.d.ts +14 -0
package/dist/react/code-runtime.js +161 -0
package/dist/react/doc-content.d.ts +39 -2
package/dist/react/doc-content.js +42 -10
package/dist/react/layout.d.ts +44 -0
package/dist/react/layout.js +65 -0
package/dist/react/nav.d.ts +28 -0
package/dist/react/nav.js +70 -0
package/dist/react/nearest-scroll-top.d.ts +45 -0
package/dist/react/nearest-scroll-top.js +44 -0
package/dist/react/next-link.d.ts +34 -0
package/dist/react/next-link.js +30 -0
package/dist/react/next-nav.d.ts +11 -0
package/dist/react/next-nav.js +32 -0
package/dist/react/next-search.d.ts +22 -0
package/dist/react/next-search.js +52 -0
package/dist/react/search-dialog.d.ts +20 -8
package/dist/react/search-dialog.js +15 -10
package/dist/react/shell-labels.d.ts +43 -0
package/dist/react/shell-labels.js +27 -0
package/dist/react/sidebar.d.ts +38 -3
package/dist/react/sidebar.js +104 -12
package/dist/react/skip-link.d.ts +1 -9
package/dist/react/skip-link.js +6 -5
package/dist/react/toc.d.ts +12 -4
package/dist/react/toc.js +18 -7
package/dist/react/youtube.d.ts +31 -5
package/dist/react/youtube.js +76 -54
package/dist/render.d.ts +35 -1
package/dist/render.js +35 -14
package/dist/route-path.d.ts +46 -0
package/dist/route-path.js +51 -0
package/dist/search-index.d.ts +6 -23
package/dist/search-index.js +6 -51
package/dist/sitemap-limit.d.ts +34 -0
package/dist/sitemap-limit.js +37 -0
package/dist/source.d.ts +1 -23
package/dist/source.js +40 -43
package/dist/styles.css +939 -93
package/dist/types.d.ts +11 -2
package/package.json +58 -23

package/dist/react/code-runtime.js ADDED Viewed

@@ -0,0 +1,161 @@
+"use client";
+import { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE, CODE_READY_ATTRIBUTE } from "../code-frame.js";
+import { useEffect } from "react";
+//#region src/react/code-runtime.tsx
+/**
+* The nine hundred bytes that make every copy button on the page work.
+*
+* Private. `DocContent` mounts it, and only when the tree it was handed
+* actually contains a code frame — so a page with no fences ships none of
+* this rather than a component that mounts and finds nothing to do.
+*
+* ## One listener, not one component per block
+*
+* The buttons are plain server-rendered HTML with no React identity at all.
+* This attaches a single delegated `click` listener to `document` and one live
+* region to `<body>`, both behind a module-level ref count: the first instance
+* installs them, later instances increment and return, and the last one out
+* removes them. Two `DocContent`s on one page therefore copy once and announce
+* once — a bug nothing else would catch, because the second announcement is
+* only audible to a screen-reader user.
+*
+* The alternative every comparable package ships — mapping `pre` to a
+* `'use client'` component — puts one client reference and one hydration root
+* in the flight stream per fence, and drags the highlighted subtree across the
+* client boundary as children.
+*/
+/** How long the button shows its copied state. */
+const COPIED_MS = 2e3;
+/**
+* Line classes whose text is not part of what the reader wanted.
+*
+* Empty today, and deliberately an array rather than an inline condition:
+* `@shikijs/transformers` lands at 0.3, and `'remove'` — the class it puts on
+* a deleted diff line — goes here. Copying deleted lines into somebody's
+* editor is the kind of failure that is discovered at run time, in their
+* project, days later.
+*/
+const SKIP_LINE_CLASSES = [];
+/** Marker classes whose lines carry trailing whitespace worth trimming. */
+const TRIMMED_LINE_CLASSES = [];
+let refCount = 0;
+let detach;
+/**
+* Mount the copy runtime. Renders nothing.
+*
+* Every hook of state lives in the DOM rather than in React: the button's
+* copied state is a `data-copied` attribute the stylesheet reads, and the
+* announcement is a live region. React owns none of these nodes, so nothing
+* re-renders and there is no state to get out of step with a page that was
+* server-rendered.
+*/
+function DocsCodeRuntime() {
+	useEffect(() => {
+		refCount += 1;
+		if (refCount === 1) detach = install();
+		return () => {
+			refCount -= 1;
+			if (refCount === 0) {
+				detach?.();
+				detach = void 0;
+			}
+		};
+	}, []);
+	return null;
+}
+function install() {
+	const status = document.createElement("div");
+	status.setAttribute("role", "status");
+	status.setAttribute("aria-live", "polite");
+	status.className = "wave-docs-code__status";
+	document.body.append(status);
+	const onClick = (event) => {
+		const target = event.target;
+		if (!(target instanceof Element)) return;
+		const button = target.closest(`[${CODE_COPY_ATTRIBUTE}]`);
+		if (!(button instanceof HTMLElement)) return;
+		const pre = button.closest(`[${CODE_FRAME_ATTRIBUTE}]`)?.querySelector("pre");
+		if (pre === null || pre === void 0) return;
+		copy(readCode(pre), button, status);
+	};
+	document.addEventListener("click", onClick);
+	document.documentElement.setAttribute(CODE_READY_ATTRIBUTE, "");
+	return () => {
+		document.removeEventListener("click", onClick);
+		document.documentElement.removeAttribute(CODE_READY_ATTRIBUTE);
+		status.remove();
+	};
+}
+/**
+* The text of a code block, as the author wrote it.
+*
+* ⚠️ NOT `pre.textContent`. Shiki emits one `<span class="line">` per line with
+* a literal `"\n"` text node between them, so `textContent` happens to be
+* right *today* — and stops being right the moment a transformer adds a line
+* that should not be copied, or a gutter of line numbers that should not be
+* either. Walking the lines is the same amount of code and survives both.
+*/
+function readCode(pre) {
+	const lines = pre.querySelectorAll(".line");
+	if (lines.length === 0) return pre.textContent ?? "";
+	const out = [];
+	for (const line of lines) {
+		const classes = line.className.split(/\s+/);
+		if (classes.some((name) => SKIP_LINE_CLASSES.includes(name))) continue;
+		const text = line.textContent ?? "";
+		out.push(classes.some((name) => TRIMMED_LINE_CLASSES.includes(name)) ? text.replace(/\s+$/, "") : text);
+	}
+	return out.join("\n");
+}
+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.";
+	const existing = timers.get(button);
+	if (existing !== void 0) window.clearTimeout(existing);
+	timers.set(button, window.setTimeout(() => {
+		timers.delete(button);
+		button.removeAttribute("data-copied");
+	}, COPIED_MS));
+}
+/**
+* The pending "clear the indicator" timer per button.
+*
+* A `WeakMap`, so a button removed by a client-side navigation takes its entry
+* with it — this module is a page-lifetime singleton and a `Map` here would
+* hold every code block the reader ever copied from.
+*/
+const timers = /* @__PURE__ */ new WeakMap();
+async function writeClipboard(text) {
+	if (window.isSecureContext && navigator.clipboard !== void 0) try {
+		await navigator.clipboard.writeText(text);
+		return true;
+	} catch {}
+	return legacyCopy(text);
+}
+/**
+* `execCommand('copy')`, which is deprecated and still the only thing that
+* works over plain HTTP.
+*
+* When it finally goes, this returns `false` and the reader gets the
+* instruction — which is why that message is written as an instruction rather
+* than as an apology.
+*/
+function legacyCopy(text) {
+	const area = document.createElement("textarea");
+	area.value = text;
+	area.setAttribute("readonly", "");
+	area.setAttribute("aria-hidden", "true");
+	area.style.cssText = "position:fixed;top:-9999px;opacity:0;";
+	document.body.append(area);
+	try {
+		area.select();
+		return document.execCommand("copy");
+	} catch {
+		return false;
+	} finally {
+		area.remove();
+	}
+}
+//#endregion
+export { DocsCodeRuntime };

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

@@ -10,20 +10,57 @@ interface DocContentProps {
   hast: Root;
   /** Overrides, merged over {@link defaultMarkdownComponents}. */
   components?: MarkdownComponents | undefined;
+  /**
+   * Appended to `wave-docs-prose`, never substituted for it.
+   *
+   * Substitution is the failure this whole wrapper exists to prevent, so it is
+   * not offered: almost every rule in the stylesheet is scoped under
+   * `.wave-docs-prose`, and dropping it leaves a page whose code blocks still
+   * carry correct syntax colours and nothing else — which reads as a design
+   * choice rather than as a mistake.
+   */
+  className?: string | undefined;
 }
 /**
- * Render a hast tree as React elements.
+ * Render a hast tree as React elements, inside the prose wrapper.
  *
  * Not a client component, and it must stay that way: the markdown parser and
  * Shiki ran in Node at build time, and this component only walks the resulting
  * tree. Nothing here pulls unified, remark or a highlighter into the browser.
  *
+ * ## Why the wrapper is here and not on your `<article>`
+ *
+ * `.wave-docs-prose` is the scope for nearly every rule in `styles.css` —
+ * including `.wave-docs-prose .shiki`, which is deliberately scoped so the
+ * package never styles a code block it did not render. `createDocsRoute.Page`
+ * always put the class on for you, but the documented hand-rolled path made
+ * the consumer type it, and forgetting it silently unstyled every code block
+ * on the site while leaving the syntax colours intact. One component owning
+ * the class removes the way to get that wrong.
+ *
+ * The rules that care about tree shape are `.wave-docs-prose > * + *` and
+ * `.wave-docs-prose > :is(h2…h6)`, and the tree's own children are this
+ * element's direct children, so nothing moves.
+ *
+ * ## The copy runtime is mounted here
+ *
+ * Because this is the component no consumer can avoid: `createDocsRoute.Page`
+ * renders it, and the documented hand-rolled route renders it directly. Wiring
+ * the listener from `docs.Layout` instead would ship dead buttons to everyone
+ * composing their own shell, and "what about someone not using the layout?"
+ * would be a caveat rather than a non-question.
+ *
+ * It renders only when the tree actually contains a code frame. The server has
+ * the tree in hand, the check is one pass, and the result is that a page
+ * without fences ships zero extra bytes rather than a runtime with nothing to
+ * do.
+ *
  * `passNode` is left off (the default). `react-markdown` hardcodes it *on* with
  * no opt-out, so any mapped component that spreads its props renders
  * `node="[object Object]"` into production HTML — with no type error to warn
  * you, because `node` is a legal prop on the component and an unknown attribute
  * on the element.
  */
-declare function DocContent({ hast, components }: DocContentProps): ReactNode;
+declare function DocContent({ hast, components, className }: DocContentProps): ReactNode;
 //#endregion
 export { DocContent, DocContentProps };

package/dist/react/doc-content.js CHANGED Viewed

@@ -1,29 +1,61 @@
+import { hasCodeFrame } from "../code-frame.js";
+import { DocsCodeRuntime } from "./code-runtime.js";
 import { defaultMarkdownComponents } from "./markdown-components.js";
 import { toJsxRuntime } from "hast-util-to-jsx-runtime";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/doc-content.tsx
 /**
-* Render a hast tree as React elements.
+* Render a hast tree as React elements, inside the prose wrapper.
 *
 * Not a client component, and it must stay that way: the markdown parser and
 * Shiki ran in Node at build time, and this component only walks the resulting
 * tree. Nothing here pulls unified, remark or a highlighter into the browser.
 *
+* ## Why the wrapper is here and not on your `<article>`
+*
+* `.wave-docs-prose` is the scope for nearly every rule in `styles.css` —
+* including `.wave-docs-prose .shiki`, which is deliberately scoped so the
+* package never styles a code block it did not render. `createDocsRoute.Page`
+* always put the class on for you, but the documented hand-rolled path made
+* the consumer type it, and forgetting it silently unstyled every code block
+* on the site while leaving the syntax colours intact. One component owning
+* the class removes the way to get that wrong.
+*
+* The rules that care about tree shape are `.wave-docs-prose > * + *` and
+* `.wave-docs-prose > :is(h2…h6)`, and the tree's own children are this
+* element's direct children, so nothing moves.
+*
+* ## The copy runtime is mounted here
+*
+* Because this is the component no consumer can avoid: `createDocsRoute.Page`
+* renders it, and the documented hand-rolled route renders it directly. Wiring
+* the listener from `docs.Layout` instead would ship dead buttons to everyone
+* composing their own shell, and "what about someone not using the layout?"
+* would be a caveat rather than a non-question.
+*
+* It renders only when the tree actually contains a code frame. The server has
+* the tree in hand, the check is one pass, and the result is that a page
+* without fences ships zero extra bytes rather than a runtime with nothing to
+* do.
+*
 * `passNode` is left off (the default). `react-markdown` hardcodes it *on* with
 * no opt-out, so any mapped component that spreads its props renders
 * `node="[object Object]"` into production HTML — with no type error to warn
 * you, because `node` is a legal prop on the component and an unknown attribute
 * on the element.
 */
-function DocContent({ hast, components }) {
-	return toJsxRuntime(hast, {
-		Fragment,
-		jsx,
-		jsxs,
-		components: {
-			...defaultMarkdownComponents,
-			...components
-		}
+function DocContent({ hast, components, className }) {
+	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, {
+			Fragment,
+			jsx,
+			jsxs,
+			components: {
+				...defaultMarkdownComponents,
+				...components
+			}
+		})]
 	});
 }
 //#endregion

package/dist/react/layout.d.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -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/nav.d.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

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