npm - @waveso/docs - Versions diffs - 0.6.0 → 0.7.1 - Mend

@waveso/docs 0.6.0 → 0.7.1

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 (22) hide show

package/CHANGELOG.md +180 -1
package/README.md +115 -38
package/dist/frontmatter.d.ts +8 -0
package/dist/frontmatter.js +7 -1
package/dist/next.d.ts +34 -27
package/dist/next.js +20 -11
package/dist/react/hero.d.ts +19 -0
package/dist/react/hero.js +44 -0
package/dist/react/layout.d.ts +1 -3
package/dist/react/layout.js +17 -54
package/dist/react/nav.d.ts +11 -11
package/dist/react/nav.js +106 -58
package/dist/react/next-nav.d.ts +5 -1
package/dist/react/next-nav.js +4 -2
package/dist/react/shell-labels.d.ts +8 -2
package/dist/react/toc.d.ts +13 -3
package/dist/react/toc.js +17 -10
package/dist/render.js +2 -1
package/dist/source.js +1 -1
package/dist/styles.css +1163 -238
package/dist/types.d.ts +31 -1
package/package.json +5 -1

package/dist/next.d.ts CHANGED Viewed

@@ -96,27 +96,25 @@ interface DocsRouteOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter>
 /**
  * Props for {@link DocsRoute.Layout}.
  *
- * Four, and the fourth is a boolean. Everything else a docs shell is asked for
- * turned out to be reachable already: an announcement banner renders *above*
- * `<docs.Layout>` in your own `layout.tsx`, because this does not own `<body>`;
- * a content footer goes inside `children`; and sidebar links, social icons and
- * separators are `DocNavNode`s authored in `meta.json`. The header bar is the
- * one region nothing else can reach, which is what `actions` is for.
+ * Three, and one of them is `children`. Everything else a docs shell is asked
+ * for turned out to be reachable already: an announcement banner renders
+ * *above* `<docs.Layout>` in your own `layout.tsx`, because this does not own
+ * `<body>`; a content footer goes inside `children`; and sidebar links, social
+ * icons and separators are `DocNavNode`s authored in `meta.json`. A theme
+ * toggle and a repository link go in the layout you write around this one — the
+ * host wraps `docs.Layout` exactly as it already wraps `<html>` and `<body>`,
+ * so there is no region only this package can reach.
  *
- * A `slots` map was the alternative, and it can still be added later — two node
- * props can become a slots map, a slots map cannot become two props.
+ * The one region a host cannot reach through `docs.Layout` is *inside* the
+ * sidebar, and the exported primitives are the answer for that: `DocsSidebar`,
+ * `DocsToc`, `DocContent` and `SkipLink` compose into a layout of your own.
+ *
+ * A `slots` map was the alternative, and shipping none is the reversible half —
+ * a map can be added the day something needs one, a map that shipped cannot be
+ * taken back.
  */
 interface DocsLayoutProps {
   children: ReactNode;
-  /**
-   * Brand at the header start. A string, or your own logo component.
-   *
-   * `ReactNode`, so it cannot also serve as the `<title>` or as the header's
-   * accessible name; the landmark carries a fixed label instead.
-   */
-  title?: ReactNode;
-  /** Header end, after search: a theme toggle, a version switcher, a link. */
-  actions?: ReactNode;
   /**
    * The search trigger. Defaults to on, and the URL is always derived.
    *
@@ -318,24 +316,33 @@ interface DocsRoute<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
    * export default docs.Layout;
    * ```
    *
-   * Or, with your own chrome in the header:
+   * Or, with your own chrome *around* it — the same layout file `<html>` and
+   * `<body>` live in, and `SiteHeader` is yours:
    *
    * ```tsx
    * export default function DocsLayout({ children }: { children: ReactNode }) {
    *   return (
-   *     <docs.Layout title={<Logo />} actions={<ThemeToggle />}>
-   *       {children}
-   *     </docs.Layout>
+   *     <>
+   *       <SiteHeader />
+   *       <docs.Layout search={{ placeholder: 'Search the docs' }}>
+   *         {children}
+   *       </docs.Layout>
+   *     </>
    *   );
    * }
    * ```
    *
-   * It owns the skip link, the header, the sidebar column, the mobile drawer
-   * and the grid, and it reads `source.nav()` and `searchIndexUrl` itself — so
-   * there is no nav to fetch and no URL to pass. It does **not** own the table
-   * of contents: a Next layout receives `{children, params}` and cannot know
-   * which page is rendering, so `docs.Page` emits the TOC as its second child
-   * and the grid places it.
+   * If that header of yours is sticky, say how tall it is once —
+   * `--wave-docs-chrome-offset: 4rem` — and our sticky columns start below it.
+   *
+   * It owns the skip link, the sidebar — one shell at every width, holding the
+   * navigation and the 44px strip that moves it — the search trigger and the
+   * grid.
+   * It reads `source.nav()` and `searchIndexUrl` itself, so there is no nav to
+   * fetch and no URL to pass. It does **not** own the table of contents: a Next
+   * layout receives `{children, params}` and cannot know which page is
+   * rendering, so `docs.Page` emits the TOC as its second child and the grid
+   * places it.
    *
    * Your `layout.tsx` stays a Server Component. The two pieces that need a
    * client — the nav's `usePathname`, the search dialog — carry their own

package/dist/next.js CHANGED Viewed

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

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

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

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

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

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

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

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

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

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

@@ -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.