@waveso/docs 0.6.0 → 0.7.0

package/dist/next.js

@@ -6,6 +6,7 @@ import { mapPooled } from "./map-pooled.js";
 import { findFunctionValuedOptions } from "./search-options.js";
 import { createMarkdownComponents } from "./react/markdown-components.js";
 import { DocContent } from "./react/doc-content.js";
+import { DocsHero } from "./react/hero.js";
 import { DocsToc } from "./react/toc.js";
 import { wrapNextLink } from "./react/link-adapter.js";
 import { createDocsRenderer } from "./render.js";
@@ -172,11 +173,15 @@ async function buildNextComponents(labels) {
 	const [linkMod, imageMod] = await Promise.all([importNext(() => import("next/link"), "next/link"), importNext(() => import("next/image"), "next/image")]);
 	const NextLink = readDefaultExport(linkMod, "next/link");
 	const NextImage = readDefaultExport(imageMod, "next/image");
-	return createMarkdownComponents({
-		Link: wrapNextLink(NextLink),
-		Image: wrapNextImage(NextImage),
-		...labels === void 0 ? {} : { labels }
-	});
+	const link = wrapNextLink(NextLink);
+	return {
+		components: createMarkdownComponents({
+			Link: link,
+			Image: wrapNextImage(NextImage),
+			...labels === void 0 ? {} : { labels }
+		}),
+		link
+	};
 }
 /**
 * The named subset of `labels`, or `undefined` when none of it is set.
@@ -220,7 +225,7 @@ function pickLabels(labels, map) {
 */
 function serializableSearchOptions(candidate) {
 	const functions = findFunctionValuedOptions(candidate);
-	if (functions.length > 0) throw docsError("invalid-config", `the search dialog cannot be given MiniSearch functions from a server component: ${functions.map((name) => `\`miniSearchOptions.${name}\``).join(", ")}. \`docs.Layout\` renders the dialog as a client component, so its props are serialised on the way across and React rejects a function with "Functions cannot be passed directly to Client Components" while prerendering. Keep the function on \`createDocsRoute\` so the index is still built with it, pass \`search={false}\` to \`docs.Layout\`, and render the dialog yourself from a \`'use client'\` module that imports the same function — \`<DocsSearch indexUrl={docs.searchIndexUrl} miniSearchOptions={{ processTerm }} />\` — putting that component in \`actions\`. Serialisable overrides (\`storeFields\`, \`boost\`, \`searchOptions.fuzzy\`) need none of this and are forwarded as before.`);
+	if (functions.length > 0) throw docsError("invalid-config", `the search dialog cannot be given MiniSearch functions from a server component: ${functions.map((name) => `\`miniSearchOptions.${name}\``).join(", ")}. \`docs.Layout\` renders the dialog as a client component, so its props are serialised on the way across and React rejects a function with "Functions cannot be passed directly to Client Components" while prerendering. Keep the function on \`createDocsRoute\` so the index is still built with it, pass \`search={false}\` to \`docs.Layout\`, and render the dialog yourself from a \`'use client'\` module that imports the same function — \`<DocsSearch indexUrl={docs.searchIndexUrl} miniSearchOptions={{ processTerm }} />\` in your own layout. Serialisable overrides (\`storeFields\`, \`boost\`, \`searchOptions.fuzzy\`) need none of this and are forwarded as before.`);
 	return candidate;
 }
 /**
@@ -425,12 +430,18 @@ function createDocsRoute(options) {
 	async function renderRoute(segments) {
 		const doc = await getPage(segments);
 		if (doc === void 0) return (await loadNotFound())();
-		const components = await loadComponents();
+		const { components, link } = await loadComponents();
 		return createElement(Fragment, null, createElement("main", {
 			className: "wave-docs-layout__main",
 			id: DOCS_CONTENT_ID,
 			tabIndex: -1
-		}, createElement(DocContent, {
+		}, (doc.frontmatter.actions?.length ?? 0) === 0 ? null : createElement(DocsHero, {
+			title: doc.frontmatter.title,
+			...doc.frontmatter.description === void 0 ? {} : { description: doc.frontmatter.description },
+			...doc.frontmatter.actions === void 0 ? {} : { actions: doc.frontmatter.actions },
+			Link: link,
+			...routeLabels?.externalLink === void 0 ? {} : { externalLabel: routeLabels.externalLink }
+		}), createElement(DocContent, {
 			hast: doc.hast,
 			components: {
 				...components,
@@ -457,7 +468,7 @@ function createDocsRoute(options) {
 		async IndexPage() {
 			return renderRoute([]);
 		},
-		async Layout({ children, title, actions, search, labels }) {
+		async Layout({ children, search, labels }) {
 			const { DocsLayoutShell } = await import("./react/layout.js");
 			const host = search === true || search === void 0 || search === false ? void 0 : search;
 			const requestedOptions = host?.miniSearchOptions ?? options.miniSearchOptions;
@@ -474,8 +485,6 @@ function createDocsRoute(options) {
 				nav: await requestScopedSource.nav(),
 				searchIndexUrl,
 				search: searchProps,
-				...title === void 0 ? {} : { title },
-				...actions === void 0 ? {} : { actions },
 				...shellLabels === void 0 ? {} : { labels: shellLabels }
 			});
 		},

package/dist/react/hero.d.ts

@@ -0,0 +1,19 @@
+import { DocAction } from "../types.js";
+import { DocsLinkComponent } from "./markdown-components.js";
+import { ReactNode } from "react";
+//#region src/react/hero.d.ts
+interface DocsHeroProps {
+  /** `frontmatter.title`, rendered as the page's `<h1>`. */
+  title: string;
+  /** `frontmatter.description`. Omitted rather than rendered empty. */
+  description?: string | undefined;
+  /** `frontmatter.actions`. An empty list renders no `<nav>` at all. */
+  actions?: readonly DocAction[] | undefined;
+  /** Client-side router link, e.g. `next/link`. Falls back to `<a>`. */
+  Link?: DocsLinkComponent | undefined;
+  /** Screen-reader suffix on a link that opens elsewhere. */
+  externalLabel?: string | undefined;
+}
+declare function DocsHero({ title, description, actions, Link, externalLabel }: DocsHeroProps): ReactNode;
+//#endregion
+export { DocsHero, DocsHeroProps };

package/dist/react/hero.js

@@ -0,0 +1,44 @@
+import { opensInNewTab } from "../safe-href.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/hero.tsx
+function DocsHero({ title, description, actions, Link, externalLabel = "(opens in a new tab)" }) {
+	const Anchor = Link ?? "a";
+	return /* @__PURE__ */ jsx("header", {
+		className: "wave-docs-hero",
+		children: /* @__PURE__ */ jsxs("div", {
+			className: "wave-docs-hero__body",
+			children: [
+				/* @__PURE__ */ jsx("h1", {
+					className: "wave-docs-hero__title",
+					children: title
+				}),
+				description === void 0 || description === "" ? null : /* @__PURE__ */ jsx("p", {
+					className: "wave-docs-hero__tagline",
+					children: description
+				}),
+				actions === void 0 || actions.length === 0 ? null : /* @__PURE__ */ jsx("div", {
+					className: "wave-docs-hero__actions",
+					children: actions.map((action, index) => {
+						const external = opensInNewTab(action.href);
+						const variant = action.variant ?? (index === 0 ? "primary" : "secondary");
+						return /* @__PURE__ */ jsxs(external ? "a" : Anchor, {
+							href: action.href,
+							className: "wave-docs-hero__action",
+							"data-variant": variant,
+							...external ? {
+								target: "_blank",
+								rel: "noreferrer"
+							} : {},
+							children: [action.label, external ? /* @__PURE__ */ jsx("span", {
+								className: "wave-docs-sr-only",
+								children: ` ${externalLabel}`
+							}) : null]
+						}, action.href);
+					})
+				})
+			]
+		})
+	});
+}
+//#endregion
+export { DocsHero };

package/dist/react/layout.d.ts

@@ -27,8 +27,6 @@ interface DocsLayoutShellProps {
   children: ReactNode;
   nav: DocNavNode[];
   searchIndexUrl: string;
-  title?: ReactNode;
-  actions?: ReactNode;
   /**
    * `false` to omit the trigger; an object to configure it.
    *
@@ -56,6 +54,6 @@ interface DocsLayoutShellProps {
    */
   labels?: DocsLabels | undefined;
 }
-declare function DocsLayoutShell({ children, nav, searchIndexUrl, title, actions, search, labels }: DocsLayoutShellProps): ReactNode;
+declare function DocsLayoutShell({ children, nav, searchIndexUrl, search, labels }: DocsLayoutShellProps): ReactNode;
 //#endregion
 export { DocsLayoutSearchProps, DocsLayoutShell, DocsLayoutShellProps };

package/dist/react/layout.js

@@ -1,68 +1,31 @@
 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 }) {
+function DocsLayoutShell({ children, nav, searchIndexUrl, 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,
-						...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",
-						children: actions
-					})
-				]
-			})
-		}),
-		/* @__PURE__ */ jsxs("div", {
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(SkipLink, { children: text.skipToContent }), /* @__PURE__ */ jsx("div", {
+		className: "wave-docs-shell",
+		children: /* @__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,
-					...labels?.expandGroup === void 0 ? {} : { expandGroup: labels.expandGroup },
-					...labels?.collapseGroup === void 0 ? {} : { collapseGroup: labels.collapseGroup },
-					...labels?.externalLink === void 0 ? {} : { externalLink: labels.externalLink }
+			children: [/* @__PURE__ */ jsx(DocsNextNav, {
+				nav,
+				label: text.nav,
+				closeLabel: text.closeNav,
+				openLabel: text.openNav,
+				...labels?.expandGroup === void 0 ? {} : { expandGroup: labels.expandGroup },
+				...labels?.collapseGroup === void 0 ? {} : { collapseGroup: labels.collapseGroup },
+				...labels?.externalLink === void 0 ? {} : { externalLink: labels.externalLink },
+				children: search === false ? null : /* @__PURE__ */ jsx(DocsSearch, {
+					indexUrl: searchIndexUrl,
+					...search === true ? {} : search,
+					className: ["wave-docs-layout__search", search === true ? void 0 : search?.className].filter(Boolean).join(" ")
 				})
 			}), children]
 		})
-	] });
+	})] });
 }
 //#endregion
 export { DocsLayoutShell };

package/dist/react/nav.d.ts

@@ -2,14 +2,7 @@ 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.
- */
+/** The navigation's `id`, and the trigger's `aria-controls`. */
 declare const DOCS_NAV_ID = "wave-docs-nav";
 interface DocsNavProps {
   /** The tree from `docs.source.nav()`. */
@@ -18,15 +11,22 @@ interface DocsNavProps {
   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. */
+  /** Accessible name for the nav landmark. */
   label?: string | undefined;
-  /** Accessible name for the close button. */
+  /** Accessible name for the trigger while the sidebar is open. */
   closeLabel?: string | undefined;
+  /** Accessible name for the trigger while the sidebar is closed. */
+  openLabel?: string | undefined;
+  /**
+   * Rendered above the tree. The search trigger goes here — it belongs to the
+   * navigation, so it moves with it and is never a second thing to place.
+   */
+  children?: ReactNode;
   /** 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, expandGroup, collapseGroup, externalLink }: DocsNavProps): ReactNode;
+declare function DocsNav({ nav, pathname, Link, label, children, closeLabel, openLabel, expandGroup, collapseGroup, externalLink }: DocsNavProps): ReactNode;
 //#endregion
 export { DOCS_NAV_ID, DocsNav, DocsNavProps };

package/dist/react/nav.js

@@ -1,73 +1,121 @@
 "use client";
 import { DocsSidebar } from "./sidebar.js";
-import { useEffect, useRef } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Fragment as Fragment$1, 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.
-*/
+/** The navigation's `id`, and the trigger's `aria-controls`. */
 const DOCS_NAV_ID = "wave-docs-nav";
-function DocsNav({ nav, pathname, Link, label = "Documentation", closeLabel = "Close navigation", expandGroup, collapseGroup, externalLink }) {
-	const ref = useRef(null);
+function DocsNav({ nav, pathname, Link, label = "Documentation", children, closeLabel = "Close navigation", openLabel = "Open navigation", expandGroup, collapseGroup, externalLink }) {
+	const shellRef = useRef(null);
+	const navRef = useRef(null);
+	const returnFocusRef = useRef(null);
+	/**
+	* ⚠️ THREE STATES, AND THE THIRD ONE IS WHY THERE IS NO FLASH.
+	*
+	* `null` is "nobody has chosen yet". The server renders it, no `data-state`
+	* reaches the DOM, and the stylesheet decides per mode — closed where the
+	* navigation would cover the article, open where it would sit beside it. So
+	* the first paint is already right at both shapes, with no JavaScript and
+	* nothing to correct afterwards.
+	*
+	* A boolean would have to be picked before the container's width is known,
+	* which is either a flash on a phone or a flash on a desktop.
+	*/
+	const [choice, setChoice] = useState(null);
+	const [mode, setMode] = useState(null);
+	const [ready, setReady] = useState(false);
+	const open = choice ?? mode === "push";
+	const covering = mode === "cover" && open;
 	useEffect(() => {
-		ref.current?.close?.();
+		const shell = shellRef.current;
+		const layout = shell?.parentElement;
+		if (shell == null || layout == null) return;
+		const read = () => {
+			const value = getComputedStyle(shell).getPropertyValue("--wave-docs-sidebar-mode").trim();
+			setMode(value === "push" ? "push" : "cover");
+		};
+		read();
+		const frame = requestAnimationFrame(() => {
+			setReady(true);
+		});
+		const observer = new ResizeObserver(read);
+		observer.observe(layout);
+		return () => {
+			cancelAnimationFrame(frame);
+			observer.disconnect();
+		};
+	}, []);
+	const close = useCallback(() => {
+		setChoice(false);
+	}, []);
+	useEffect(() => {
+		if (covering) setChoice(false);
 	}, [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();
+		if (!covering) return;
+		const onKeyDown = (event) => {
+			if (event.key !== "Escape") return;
+			event.stopPropagation();
+			close();
 		};
-		document.addEventListener("click", onClick);
+		document.addEventListener("keydown", onKeyDown);
 		return () => {
-			document.removeEventListener("click", onClick);
+			document.removeEventListener("keydown", onKeyDown);
 		};
-	}, []);
-	return /* @__PURE__ */ jsxs("dialog", {
-		ref,
-		id: DOCS_NAV_ID,
-		className: "wave-docs-layout__drawer",
-		closedby: "any",
-		"aria-label": label,
-		children: [/* @__PURE__ */ jsx("button", {
+	}, [covering, close]);
+	useEffect(() => {
+		const shell = shellRef.current;
+		const layout = shell?.parentElement;
+		if (shell == null || layout == null) return;
+		const outside = [...layout.children].filter((child) => child !== shell && !child.classList.contains(SCRIM_CLASS));
+		if (!covering) {
+			for (const element of outside) element.removeAttribute("inert");
+			return;
+		}
+		returnFocusRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+		for (const element of outside) element.setAttribute("inert", "");
+		navRef.current?.focus();
+		return () => {
+			for (const element of outside) element.removeAttribute("inert");
+			returnFocusRef.current?.focus({ preventScroll: true });
+		};
+	}, [covering]);
+	const state = choice === null && mode === null ? void 0 : open;
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs("div", {
+		ref: shellRef,
+		className: "wave-docs-layout__sidebar",
+		...state === void 0 ? {} : { "data-state": state ? "open" : "closed" },
+		...ready ? { "data-ready": "" } : {},
+		children: [/* @__PURE__ */ jsxs("div", {
+			ref: navRef,
+			id: DOCS_NAV_ID,
+			className: "wave-docs-layout__sidebar-nav",
+			tabIndex: -1,
+			children: [children, /* @__PURE__ */ jsx(DocsSidebar, {
+				nav,
+				pathname,
+				label,
+				Link,
+				...expandGroup === void 0 ? {} : { expandGroup },
+				...collapseGroup === void 0 ? {} : { collapseGroup },
+				...externalLink === void 0 ? {} : { externalLink }
+			})]
+		}), /* @__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,
-			...expandGroup === void 0 ? {} : { expandGroup },
-			...collapseGroup === void 0 ? {} : { collapseGroup },
-			...externalLink === void 0 ? {} : { externalLink }
+			className: "wave-docs-layout__sidebar-trigger",
+			"aria-controls": DOCS_NAV_ID,
+			"aria-label": open ? closeLabel : openLabel,
+			...state === void 0 ? {} : { "aria-expanded": state },
+			onClick: () => {
+				setChoice(!open);
+			}
 		})]
-	});
+	}), /* @__PURE__ */ jsx("div", {
+		className: SCRIM_CLASS,
+		"aria-hidden": "true",
+		onClick: close
+	})] });
 }
+const SCRIM_CLASS = "wave-docs-layout__sidebar-scrim";
 //#endregion
 export { DOCS_NAV_ID, DocsNav };

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

@@ -5,11 +5,15 @@ interface DocsNextNavProps {
   nav: DocNavNode[];
   label?: string | undefined;
   closeLabel?: string | undefined;
+  /** Accessible name for the trigger while the sidebar is closed. */
+  openLabel?: string | undefined;
+  /** Rendered above the tree. See `DocsNavProps.children`. */
+  children?: ReactNode;
   /** Passed through to the tree. See `DocsSidebarProps.expandGroup`. */
   expandGroup?: string | undefined;
   collapseGroup?: string | undefined;
   externalLink?: string | undefined;
 }
-declare function DocsNextNav({ nav, label, closeLabel, expandGroup, collapseGroup, externalLink }: DocsNextNavProps): ReactNode;
+declare function DocsNextNav({ nav, label, closeLabel, openLabel, children, expandGroup, collapseGroup, externalLink }: DocsNextNavProps): ReactNode;
 //#endregion
 export { DocsNextNav, DocsNextNavProps };

package/dist/react/next-nav.js

@@ -19,16 +19,18 @@ 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, expandGroup, collapseGroup, externalLink }) {
+function DocsNextNav({ nav, label, closeLabel, openLabel, children, expandGroup, collapseGroup, externalLink }) {
 	return /* @__PURE__ */ jsx(DocsNav, {
 		nav,
 		pathname: usePathname(),
 		Link,
 		...label === void 0 ? {} : { label },
 		...closeLabel === void 0 ? {} : { closeLabel },
+		...openLabel === void 0 ? {} : { openLabel },
 		...expandGroup === void 0 ? {} : { expandGroup },
 		...collapseGroup === void 0 ? {} : { collapseGroup },
-		...externalLink === void 0 ? {} : { externalLink }
+		...externalLink === void 0 ? {} : { externalLink },
+		children
 	});
 }
 //#endregion

package/dist/react/shell-labels.d.ts

@@ -44,9 +44,15 @@
 interface DocsLabels {
   /** The navigation landmark's accessible name. Default `'Documentation'`. */
   nav?: string | undefined;
-  /** The header button that opens the drawer. Default `'Open navigation'`. */
+  /**
+   * The sidebar's trigger, named for what pressing it does next. One button
+   * carries both strings: `openNav` while the sidebar is closed, `closeNav`
+   * while it is open.
+   *
+   * Default `'Open navigation'`.
+   */
   openNav?: string | undefined;
-  /** The button that closes the drawer. Default `'Close navigation'`. */
+  /** The same button, while the sidebar is open. Default `'Close navigation'`. */
   closeNav?: string | undefined;
   /** The skip link's visible text. Default `'Skip to content'`. */
   skipToContent?: string | undefined;

package/dist/react/toc.d.ts

@@ -8,9 +8,19 @@ interface DocsTocProps {
   label?: string | undefined;
   /**
    * Region of the viewport that counts as "current", as an
-   * `IntersectionObserver` root margin. The default reserves 80px for a sticky
-   * header and ignores the bottom 60% of the screen, so the active entry
-   * tracks what you are reading rather than what has scrolled into view.
+   * `IntersectionObserver` root margin. The default ignores the bottom 60% of
+   * the screen, so the active entry tracks what you are reading rather than
+   * what has scrolled into view.
+   *
+   * ⚠️ IT USED TO RESERVE 80px FOR A STICKY HEADER, AND TWO THINGS WERE WRONG
+   * WITH THAT. There is no header — above 80rem, where this component
+   * is rendered at all, nothing of ours overlays the content. And 80px never
+   * matched the header anyway: the token was `3.5rem`, which is 56px, so the
+   * figure was never derived from the thing it claimed to reserve for.
+   *
+   * This component is exported standalone, so its default cannot assume our
+   * shell. It assumes nothing overlays the content; a host whose own chrome
+   * does sets this prop, which is what the prop is for.
    *
    * Only `px` and `%` are legal here — `IntersectionObserver` throws on any
    * other unit, `rem` included.

package/dist/react/toc.js

@@ -3,7 +3,7 @@ import { DOCS_CONTENT_ID } from "../docs-content-id.js";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/toc.tsx
-const DEFAULT_ROOT_MARGIN = "-80px 0px -60% 0px";
+const DEFAULT_ROOT_MARGIN = "0px 0px -60% 0px";
 /**
 * How many frames to keep looking for headings that are not in the document
 * yet. ~1s at 60Hz, which covers a `<Suspense>` boundary resolving or a
@@ -86,15 +86,22 @@ function DocsToc({ entries, label = "On this page", rootMargin = DEFAULT_ROOT_MA
 	return /* @__PURE__ */ jsxs("nav", {
 		"aria-label": label,
 		className: ["wave-docs-toc", className].filter(Boolean).join(" "),
-		children: [/* @__PURE__ */ jsx(TocList, {
-			entries,
-			activeId,
-			onSelect: setActiveId
-		}), /* @__PURE__ */ jsx("a", {
-			className: "wave-docs-toc__top",
-			href: `#${DOCS_CONTENT_ID}`,
-			children: topLabel
-		})]
+		children: [
+			/* @__PURE__ */ jsx("p", {
+				className: "wave-docs-toc__title",
+				children: label
+			}),
+			/* @__PURE__ */ jsx(TocList, {
+				entries,
+				activeId,
+				onSelect: setActiveId
+			}),
+			/* @__PURE__ */ jsx("a", {
+				className: "wave-docs-toc__top",
+				href: `#${DOCS_CONTENT_ID}`,
+				children: topLabel
+			})
+		]
 	});
 }
 function TocList({ entries, activeId, onSelect }) {

package/dist/render.js

@@ -431,7 +431,8 @@ function createDocsRenderer(options) {
 			relativePath: file.relativePath
 		};
 		const hast = await processor.run(processor.parse(vfile), vfile);
-		if (titleHeading && !hasHeadingOne(hast)) hast.children.unshift(titleHeadingNode(file.frontmatter.title));
+		const hasHero = (file.frontmatter.actions?.length ?? 0) > 0;
+		if (titleHeading && !hasHero && !hasHeadingOne(hast)) hast.children.unshift(titleHeadingNode(file.frontmatter.title));
 		await resolveImages(hast, file, imageResolver);
 		assertLinks(file, vfile.data.docLinks ?? []);
 		assertOwnAnchors(file, hast, vfile.data.docLinks ?? []);

package/dist/source.js

@@ -18,7 +18,7 @@ const INDEX_NAME = "index";
 * ⚠️ THE SCAN USED TO OPEN EVERY MARKDOWN FILE AT ONCE. `scanDir` recursed into
 * its subdirectories in parallel and read that directory's pages with a bare
 * `Promise.all`, so the number of `readFile` calls in flight equalled the number
-* of markdown files in the entire tree. On a 1,200-page corpus and the common
+* of markdown files in the entire tree. On a 1,201-page corpus and the common
 * 1,024-descriptor soft limit, `next build` died with a bare `EMFILE: too many
 * open files` — no error code, no mention that this was the docs scan, and
 * nothing pointing at the fix. Exactly the large content set this package is