@waveso/docs 0.5.0 → 0.7.0

package/dist/frontmatter.js

@@ -1,4 +1,5 @@
 import { docsError } from "./docs-error.js";
+import { isSafeHref } from "./safe-href.js";
 import { z } from "zod";
 //#region src/frontmatter.ts
 /**
@@ -30,7 +31,12 @@ const docFrontmatterSchema = z.object({
 	label: z.string().exactOptional(),
 	draft: z.boolean().exactOptional(),
 	aliases: z.array(z.string()).exactOptional(),
-	order: z.number().exactOptional()
+	order: z.number().exactOptional(),
+	actions: z.array(z.object({
+		label: z.string().min(1),
+		href: z.string().min(1).refine(isSafeHref, "must be a safe URL (no javascript: or data:)"),
+		variant: z.enum(["primary", "secondary"]).exactOptional()
+	})).exactOptional()
 });
 /**
 * The package's own fields, every one of them optional, for the overlay pass

package/dist/link-suggestion.d.ts

@@ -0,0 +1,31 @@
+//#region src/link-suggestion.d.ts
+/**
+ * "Did you mean …?" for a link that matched no page.
+ *
+ * Private — deliberately not an entry point.
+ *
+ * A broken link is almost always a typo, and a typo is a near-miss by
+ * construction: `/instalation` is one edit from `/installation`, while `/login`
+ * is six from anything in a docs tree. That gap is what makes a suggestion
+ * safe to offer and safe to withhold — the same reason `git`, `tsc`, `cargo`
+ * and Python 3.12 all do it, and the reason none of them offers one for a word
+ * that is nowhere near a real name.
+ *
+ * ⚠️ A SUGGESTION ONLY, NEVER A DECISION. Nothing here decides whether a link
+ * is an error; `render.ts` has already decided that by the time it asks. Using
+ * an edit distance to pick between failing and staying silent would be a
+ * heuristic holding a build hostage, which is not a thing to do to somebody
+ * whose page happens to be called `/setting`.
+ */
+/**
+ * The closest route to `target`, or `undefined` if nothing is close enough.
+ *
+ * Ties break on the shortest candidate and then alphabetically, so the message
+ * is the same on every machine — a suggestion that changes between runs reads
+ * as a flaky build.
+ */
+declare function suggestRoute(target: string, routes: Iterable<string>): string | undefined;
+/** ` Did you mean '/installation'?`, or `''` when nothing is close. */
+declare function describeSuggestion(target: string, routes: Iterable<string> | undefined): string;
+//#endregion
+export { describeSuggestion, suggestRoute };

package/dist/link-suggestion.js

@@ -0,0 +1,94 @@
+//#region src/link-suggestion.ts
+/**
+* "Did you mean …?" for a link that matched no page.
+*
+* Private — deliberately not an entry point.
+*
+* A broken link is almost always a typo, and a typo is a near-miss by
+* construction: `/instalation` is one edit from `/installation`, while `/login`
+* is six from anything in a docs tree. That gap is what makes a suggestion
+* safe to offer and safe to withhold — the same reason `git`, `tsc`, `cargo`
+* and Python 3.12 all do it, and the reason none of them offers one for a word
+* that is nowhere near a real name.
+*
+* ⚠️ A SUGGESTION ONLY, NEVER A DECISION. Nothing here decides whether a link
+* is an error; `render.ts` has already decided that by the time it asks. Using
+* an edit distance to pick between failing and staying silent would be a
+* heuristic holding a build hostage, which is not a thing to do to somebody
+* whose page happens to be called `/setting`.
+*/
+/**
+* The ceiling on how far apart two routes may be and still be called a typo.
+*
+* Three is roughly one slip per word in a two-word slug — `instalation`,
+* `gettting-started`, `plugns`. It is a *ceiling*, not the whole rule: the
+* budget is also scaled by the length of what was written, so short routes are
+* held tighter and `/api` is not offered as a fix for `/ui`.
+*
+* Between them, `/docs/instructions` gets no suggestion for
+* `/docs/installation` — five edits apart, similar enough to tempt a generous
+* threshold, and a different word. `render.test.ts` pins that case, because
+* without it this constant could be any number at all.
+*/
+const MAX_DISTANCE = 3;
+/**
+* Levenshtein distance, bounded.
+*
+* Two rows rather than a full matrix: the corpus is every route on the site and
+* this runs per broken link, so the allocation is the only part worth caring
+* about. Returns early once every cell in a row exceeds `limit`, which is the
+* common case — most candidates are nowhere near.
+*/
+function distance(a, b, limit) {
+	if (a === b) return 0;
+	if (Math.abs(a.length - b.length) > limit) return limit + 1;
+	let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+	let current = new Array(b.length + 1);
+	for (let i = 1; i <= a.length; i += 1) {
+		current[0] = i;
+		let best = i;
+		for (let j = 1; j <= b.length; j += 1) {
+			const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+			const deletion = previous[j] + 1;
+			const insertion = current[j - 1] + 1;
+			const cell = Math.min(substitution, deletion, insertion);
+			current[j] = cell;
+			if (cell < best) best = cell;
+		}
+		if (best > limit) return limit + 1;
+		const swap = previous;
+		previous = current;
+		current = swap;
+	}
+	return previous[b.length];
+}
+/**
+* The closest route to `target`, or `undefined` if nothing is close enough.
+*
+* Ties break on the shortest candidate and then alphabetically, so the message
+* is the same on every machine — a suggestion that changes between runs reads
+* as a flaky build.
+*/
+function suggestRoute(target, routes) {
+	const limit = Math.min(MAX_DISTANCE, Math.max(1, Math.floor(target.length / 3)));
+	let best;
+	let bestDistance = limit + 1;
+	for (const route of routes) {
+		if (route === target) continue;
+		const measured = distance(target, route, limit);
+		if (measured > limit) continue;
+		if (measured < bestDistance || measured === bestDistance && best !== void 0 && (route.length < best.length || route.length === best.length && route < best)) {
+			best = route;
+			bestDistance = measured;
+		}
+	}
+	return best;
+}
+/** ` Did you mean '/installation'?`, or `''` when nothing is close. */
+function describeSuggestion(target, routes) {
+	if (routes === void 0) return "";
+	const suggestion = suggestRoute(target, routes);
+	return suggestion === void 0 ? "" : ` Did you mean '${suggestion}'?`;
+}
+//#endregion
+export { describeSuggestion, suggestRoute };

package/dist/next.d.ts

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

@@ -1,11 +1,14 @@
+import { assertAnchors } from "./anchors.js";
 import { docsError } from "./docs-error.js";
 import { DOCS_CONTENT_ID } from "./docs-content-id.js";
+import { describeSuggestion } from "./link-suggestion.js";
 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/next-link.js";
+import { wrapNextLink } from "./react/link-adapter.js";
 import { createDocsRenderer } from "./render.js";
 import { toAliasRoute } from "./route-path.js";
 import { createDocsSource, resolveDocsConfig } from "./source.js";
@@ -170,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.
@@ -218,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;
 }
 /**
@@ -374,7 +381,23 @@ function createDocsRoute(options) {
 		const files = await source.all();
 		await loadRoutes();
 		const renderer = loadRenderer();
-		return mapPooled(files, RENDER_CONCURRENCY, (file) => renderer.render(file));
+		const rendered = await mapPooled(files, RENDER_CONCURRENCY, (file) => renderer.render(file));
+		assertAnchors(rendered, (from, link, known) => {
+			reportAnchor(`@waveso/docs: ${from} links to '${link.href}', and '${link.route}' has no '#${link.fragment}'.${describeSuggestion(link.fragment, known)} Heading ids come from the heading text, so renaming a heading renames its anchor.`);
+		});
+		return rendered;
+	};
+	/**
+	* A cross-page anchor failure, at the configured severity.
+	*
+	* No line number, unlike the same-page check: positions are stripped from a
+	* returned tree, so the page and the link are what there is to name. Both
+	* halves share `onBrokenAnchors`, because to an author they are one mistake.
+	*/
+	const reportAnchor = (message) => {
+		if (config.onBrokenAnchors === "ignore") return;
+		if (config.onBrokenAnchors === "throw") throw docsError("broken-anchor", message);
+		console.warn(message);
 	};
 	const searchIndexUrl = `${config.basePath}/search-index.json`;
 	/**
@@ -407,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,
@@ -439,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;
@@ -456,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/plugins/rehype-fallback-heading-ids.js

@@ -1,6 +1,6 @@
+import { visit } from "unist-util-visit";
 import rehypeSlug from "rehype-slug";
 import { unified } from "unified";
-import { visit } from "unist-util-visit";
 //#region src/plugins/rehype-fallback-heading-ids.ts
 const HEADING = /^h[1-6]$/;
 /** `-1`, `-2` … — what `github-slugger` returns for a repeated empty slug. */

package/dist/plugins/remark-doc-links.d.ts

@@ -26,6 +26,36 @@ interface DocLinkRef {
    * never be a member of.
    */
   asset?: true;
+  /**
+   * An absolute link at a root mount, which cannot be proved to be ours.
+   *
+   * ⚠️ RECORDED RATHER THAN SKIPPED, WHICH IS THE CHANGE. Under
+   * `basePath: '/docs'` an absolute link either starts with `/docs` — so it is
+   * a documentation route and is checked — or it does not, and belongs to the
+   * host's application. Under `basePath: '/'` that test cannot be made:
+   * `/setup` may be a page here and `/login` almost certainly is not, and
+   * nothing in the markdown says which.
+   *
+   * So it is collected and marked, and checked like any other link — because a
+   * root mount is what you choose when the origin serves documentation and
+   * nothing else, which makes an unknown absolute link a typo. An origin that
+   * serves something else names what is its own through
+   * `DocsConfig.externalRoutes`.
+   */
+  unverifiable?: true;
+  /**
+   * A bare `#fragment` — a link into the page it is written on.
+   *
+   * ⚠️ RECORDED SO THE ANCHOR CAN BE CHECKED, AND FLAGGED SO THE ROUTE IS NOT.
+   * `isRelativeLink` excludes these and always did, correctly: there is no
+   * route to resolve. But that also meant they were never collected, so nothing
+   * downstream could see `#missing` at all — and a same-page anchor is the one
+   * a writer produces most, every "see below".
+   *
+   * `assertLinks` skips these; `assertOwnAnchors` is what reads them, and the
+   * recorded line is why the message can name one.
+   */
+  anchorOnly?: true;
 }
 declare module 'vfile' {
   interface DataMap {
@@ -41,6 +71,8 @@ interface RemarkDocLinksOptions {
   /** Overrides the built-in resolution entirely, for every relative link. */
   resolve?: LinkResolver;
 }
+/** No prefix at all — the docs own the whole origin. */
+declare function isRootMount(basePath: string): boolean;
 /**
  * Fold `.` and `..` against a starting directory.
  *
@@ -121,4 +153,4 @@ declare function resolveMarkdownLink(href: string, fromDir: readonly string[], b
  */
 declare const remarkDocLinks: Plugin<[RemarkDocLinksOptions], Root>;
 //#endregion
-export { type DocLinkContext, DocLinkRef, HrefParts, RemarkDocLinksOptions, decodePath, foldSegments, remarkDocLinks, resolveMarkdownLink, splitHref };
+export { type DocLinkContext, DocLinkRef, HrefParts, RemarkDocLinksOptions, decodePath, foldSegments, isRootMount, remarkDocLinks, resolveMarkdownLink, splitHref };

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

@@ -20,6 +20,10 @@ const FILE_EXTENSION = /\.[^./]+$/;
 function isRelativeLink(href) {
 	return href !== "" && !href.startsWith("#") && !href.startsWith("?") && !href.startsWith("/") && !HAS_SCHEME.test(href);
 }
+/** No prefix at all — the docs own the whole origin. */
+function isRootMount(basePath) {
+	return basePath.replace(/\/+$/, "") === "";
+}
 /**
 * Is this already-absolute href one of OUR routes?
 *
@@ -28,9 +32,11 @@ function isRelativeLink(href) {
 * A typo in a hand-written absolute link is exactly as likely as one in a
 * relative link; only the rewriting differs.
 *
-* Requires a non-empty base path. Docs mounted at the site root cannot be told
-* apart from the rest of the site, and asserting `/login` against the set of
-* documentation routes would fail builds over links that are perfectly good.
+* Answers `false` at a root mount, where there is no prefix to test against.
+* That is not the end of the matter: the caller records those links anyway,
+* marked, because at a root mount the *common* case is an origin that serves
+* documentation and nothing else — so they are checked, and a site with other
+* routes names them through `externalRoutes`.
 */
 function isInternalAbsoluteLink(href, basePath) {
 	const base = basePath.replace(/\/+$/, "");
@@ -224,23 +230,33 @@ const remarkDocLinks = (options) => {
 			const raw = node.url;
 			if (node.type === "definition" && imageIdentifiers.has(node.identifier)) continue;
 			const line = node.position?.start.line;
-			const record = (href, asset) => {
+			const record = (href, flags = {}) => {
 				const ref = {
 					raw,
 					href
 				};
 				if (line !== void 0) ref.line = line;
-				if (asset !== void 0) ref.asset = asset;
+				if (flags.asset !== void 0) ref.asset = flags.asset;
+				if (flags.unverifiable !== void 0) ref.unverifiable = flags.unverifiable;
+				if (flags.anchorOnly !== void 0) ref.anchorOnly = flags.anchorOnly;
 				refs.push(ref);
 				if (href !== void 0) node.url = href;
 			};
 			try {
+				if (raw.startsWith("#")) {
+					record(raw, { anchorOnly: true });
+					continue;
+				}
 				if (!isRelativeLink(raw)) {
-					if (isInternalAbsoluteLink(raw, basePath) && !isAssetLink(raw)) record(normalizeInternalRoute(raw, basePath));
+					if (isInternalAbsoluteLink(raw, basePath) && !isAssetLink(raw)) {
+						record(normalizeInternalRoute(raw, basePath));
+						continue;
+					}
+					if (isRootMount(basePath) && raw.startsWith("/") && !raw.startsWith("//") && !isAssetLink(raw)) record(normalizeInternalRoute(raw, basePath), { unverifiable: true });
 					continue;
 				}
 				if (resolve === void 0 && isAssetLink(raw)) {
-					record(resolveAssetLink(raw, context.dirSegments, basePath), true);
+					record(resolveAssetLink(raw, context.dirSegments, basePath), { asset: true });
 					continue;
 				}
 				if (resolve) {
@@ -257,4 +273,4 @@ const remarkDocLinks = (options) => {
 	};
 };
 //#endregion
-export { decodePath, foldSegments, remarkDocLinks, resolveMarkdownLink, splitHref };
+export { decodePath, foldSegments, isRootMount, remarkDocLinks, resolveMarkdownLink, splitHref };

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