@waveso/docs 0.9.1 → 0.11.0

package/README.md

@@ -69,16 +69,16 @@ Every figure below is a **ceiling**, and `pnpm size` fails the build if the meas
 
 | | At most |
 | --- | --- |
-| Everything the quick start ships, gzipped | 14.5 KB |
+| Everything the quick start ships, gzipped | 14.6 KB |
 | Search dialog and router wiring | 9.5 KB |
 | Navigation: one sidebar, open and closed | 3.1 KB |
-| Table of contents | 0.9 KB |
+| Table of contents | 1 KB |
 | Copy-button runtime | 1.1 KB |
 | hast over the wire vs HTML, prose page | 1.20× |
 | hast over the wire vs HTML, code and tables | 1.12× |
 | Highlighting vs no highlighting | 2.00× |
 
-The first row is the honest total: a reader who lands on a page of your documentation downloads under 14.5 KB gzipped of JavaScript from this package, and that is the whole of it. No markdown parser and no syntax highlighter reach the browser at all — those run in Node at build time. Drop the search dialog and it is under 4 KB.
+The first row is the honest total: a reader who lands on a page of your documentation downloads under 14.6 KB gzipped of JavaScript from this package, and that is the whole of it. No markdown parser and no syntax highlighter reach the browser at all — those run in Node at build time. Drop the search dialog and it is under 4 KB.
 
 The one real cost is the middle pair: shipping a tree instead of a string is about 20% more brotli on a prose page, and about 12% on a page with code and tables, where Shiki's token spans dominate both representations equally. That is the price of never handing markup to `dangerouslySetInnerHTML`, and it is the first number a skeptical reviewer should ask for.
 
@@ -203,6 +203,8 @@ Every component takes data as props, and every module that imports from `next/*`
 | `DocContent` | `react/doc-content` | Renders a hast tree, inside `.wave-docs-prose`. Server Component |
 | `DocsHero` | `react/hero` | A landing page's header. `title`, `description`, `actions`, `Link`, `externalLabel`. Server Component |
 | `DocsSidebar` | `react/sidebar` | Takes `pathname` as a prop, not from `next/navigation`. `icons` controls the marker column — see [Sidebar icons](#sidebar-icons) |
+| `DocsExplore` | `react/explore` | "Where to go next": a question per row and the page that answers it. `docs.Page` renders it when a page declares `explore` |
+| `DocsPager` | `react/pager` | Links to the pages either side of this one. `docs.Page` renders it; `pager: false` on the route omits it |
 | `DocsToc` | `react/toc` | Scrollspy via `IntersectionObserver`. `label`, `topLabel`, `rootMargin`, `className` |
 | `DocsSearch` | `react/next-search` | `SearchDialog`, wired to Next's router. What you want |
 | `DocsLink` | `react/next-link` | `next/link`, adapted — pass it as `Link` when composing by hand |
@@ -214,6 +216,58 @@ Every component takes data as props, and every module that imports from `next/*`
 
 `DocsToc`'s `rootMargin` is the `IntersectionObserver` margin that decides how far above the viewport a heading counts as current; the default keeps the highlight on the section you are reading rather than the one about to arrive. `topLabel` is the back-to-top link at the end — it fades in once the reader is about a third of a screen down and fades out again on the way back, on a scroll timeline rather than a scroll listener, so the component ships no extra bytes to do it. Where that timeline cannot run — an engine without scroll-driven animations, a page too short to scroll, or a host that scrolls an inner pane rather than the document — the link is simply always there.
 
+### Where to go next
+
+A sidebar is a structure; this is a router. It says *why* a reader would go somewhere, which no tree of titles can. A page opts in from its frontmatter:
+
+```yaml
+---
+title: How it fits together
+explore:
+  - question: How a person is recognised across servers
+    href: ./identity.md
+  - question: What happens when the network fails
+    href: ./delivery.md
+  - question: Where the source lives
+    href: https://github.com/example/repo
+    title: GitHub
+---
+```
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `question` | `string` | What the reader might want to know. The row's left half |
+| `href` | `string` | Where the answer is. Checked against the same allowlist as every other link |
+| `title` | `string` | The link's text. Defaults to the destination's title **in the navigation** |
+
+**The link text comes from the navigation**, so renaming a page updates every block pointing at it — the same source the sidebar and the pager read. Name a `title` only where the tree cannot answer: an external link, or a page kept out of the navigation. An `href` that resolves to neither stops the build and says which of the two fixes to reach for, rather than rendering a URL where a sentence should be.
+
+It renders above the pager: this is the semantic answer, the pager is the linear one.
+
+It wears **the panel** — a framed block with a header and an inset surface, styled by `.wave-docs-panel`, `.wave-docs-panel__header`, `.wave-docs-panel__title`, `.wave-docs-panel__actions` and `.wave-docs-panel__body`. That is a shared primitive rather than this component's furniture, so a code frame can wear it next without a second copy of the same rules. The two radii are not independent: the inner one is the outer minus the panel's padding, or the corners run at different curvatures and the surface reads as pasted onto the frame instead of set into it. `--wave-docs-radius-lg` is picked so the arithmetic lands on `--wave-docs-radius`.
+
+The panel also exports `--wave-docs-panel-inset` for anything placed inside `__body`: the header's title sits at the frame's padding, but body content sits at that padding *plus the body's own border*, so the two columns miss each other by a pixel per border unless the inset is used.
+
+`DocsExplore` takes `steps` (each with `question`, `href` and a resolved `title`), plus `heading`, `Link`, `externalLabel` and `className`. The heading defaults to `'Where to go next'` and is `explore` in `labels`. Under a 40rem container the question and its answer stack instead of sharing a row.
+
+### The pager
+
+`docs.Page` renders it under every page, so most sites never touch it. The order is the navigation's — flattened from the same tree `DocsSidebar` renders — so a pager that disagrees with the sidebar beside it is impossible. Nothing is authored: a page gets one by being in the tree, and a page outside it (a draft, or a route you render yourself) gets none.
+
+Separators and external links are not stops. A separator is a label with nowhere to go, and a "next page" that lands on npm has ended the sequence rather than continued it. A directory with an `index.md` contributes its own page before its children, which is the order its rows appear in.
+
+| Prop | Type | Default | What it is |
+| --- | --- | --- | --- |
+| `previous` | `NavStop` | — | The stop before this page. Omit at the beginning |
+| `next` | `NavStop` | — | The stop after it. Omit at the end |
+| `Link` | `DocsLinkComponent` | `<a>` | Client-side router link |
+| `previousLabel` | `string` | `'Previous'` | Above the previous page's title |
+| `nextLabel` | `string` | `'Next'` | Above the next page's title |
+| `label` | `string` | `'Pagination'` | Accessible name for the landmark |
+| `className` | `string` | — | Extra classes |
+
+With neither neighbour it renders nothing at all, rather than an empty landmark. Set `pager: false` on `createDocsRoute` to omit it everywhere, and the three strings through `labels` — `previousPage`, `nextPage`, `pagination`.
+
 ### Sidebar icons
 
 Every row in the sidebar carries a marker at its head: a folder on a group, a page on a page, an arrow on a link that leaves your site. Weight and a chevron were the only difference before, and where categories and pages interleave that is not enough to scan.
@@ -667,6 +721,48 @@ your own `:root`, after the import:
 }
 ```
 
+### Corners
+
+Three tiers, all derived from one root, so a box's radius is decided by what
+*kind* of box it is rather than by how big it happens to be.
+
+| Token | What takes it |
+| --- | --- |
+| `--wave-docs-radius-sm` | Inline chips, small controls, and focus rings drawn on those |
+| `--wave-docs-radius` | Controls, overlays, and the panel's inset surface |
+| `--wave-docs-radius-lg` | Every block in the reading flow, and the panel's outer edge |
+
+**Retune all three from one line.** `--wave-docs-radius-base` is the root and
+the other three are `calc()` off it, so a host already running `@waveso/ui`
+points this package at their scale and every corner follows — including any
+theme that moves it:
+
+```css
+:root {
+  --wave-docs-radius-base: var(--radius);
+}
+```
+
+The numbers are `@waveso/ui`'s to begin with. A page running both should not
+show two radius scales a few pixels apart, and taking theirs is how that is
+guaranteed rather than kept in step by hand.
+
+⚠️ **`--wave-docs-radius-step` is not decoration.** The panel's inset surface
+takes the base radius and its frame takes `--wave-docs-radius-lg`, which is the
+base plus one step — so the two corners are concentric only while the frame's
+*padding* is that same step, which is why it is paid out of the token rather
+than written as `4px`. Move the root and both stay true; hard-code the padding
+and they drift the first time anyone retunes the scale.
+
+Where the browser supports `corner-shape`, every corner this package draws
+becomes a squircle and the root moves up, because a squircle reads tighter than
+a circular arc at the same radius. `@waveso/ui` makes the same move to the same
+value. Elsewhere it is an ordinary rounded corner at the original scale — an
+enhancement, never a dependency. The shaping is scoped to elements this package
+owns rather than applied with `*`: this stylesheet is mounted inside somebody
+else's page, and reshaping the host's corners is the same trespass as claiming
+`html`.
+
 That works because **everything this stylesheet declares lives in a `@layer`** —
 `theme` for the tokens, `base` for element resets, `components` for the classes
 — and unlayered CSS outranks every layer regardless of specificity.

package/dist/code-frame.d.ts

@@ -16,6 +16,33 @@ declare const CODE_COPY_ATTRIBUTE = "data-wave-docs-copy";
  * tab stop where a control should be.
  */
 declare const CODE_READY_ATTRIBUTE = "data-wave-docs-code-ready";
+/**
+ * The copy button's three icons, as Lucide paths.
+ *
+ * ⚠️ PATHS FROM THE SAME SET AS EVERY OTHER ICON HERE, AND THEY WERE FONT
+ * GLYPHS. The button rendered `⧉` and swapped in `✓` and `×` through CSS
+ * `content` — three characters drawn by whatever font resolved, at whatever
+ * weight and baseline that font has, beside a sidebar, a pager and a search
+ * dialog that are all Lucide at `stroke-width: 2`. It read as a different
+ * icon set because it was one.
+ *
+ * `copy`, `check` and `x`, on the 24×24 grid the rest of the package uses.
+ * Lucide draws its `copy` as a `<rect>` plus a `<path>`; the rect is written
+ * here as the path it is, so a frame's icons are one shape of node and the
+ * builder stays a list of `d` strings — the same shape `NAV_ICON_PATHS` has.
+ */
+declare const CODE_ICON_PATHS: Record<'copy' | 'check' | 'x', string[]>;
+/**
+ * The three states the button draws, in the order they are emitted.
+ *
+ * `idle` is what a reader sees; the runtime writes `data-copied` on the button
+ * and the stylesheet swaps which of the three is displayed. `display`, not
+ * `visibility`: the button is `visibility: hidden` until the runtime attaches,
+ * and `visibility` inherits — a child setting it back to `visible` would show
+ * an icon inside a button that is meant to be invisible and out of the tab
+ * order.
+ */
+declare const CODE_ICON_STATES: readonly [readonly ["idle", "copy"], readonly ["copied", "check"], readonly ["failed", "x"]];
 /**
  * Whether a tree contains a code frame.
  *
@@ -26,4 +53,4 @@ declare const CODE_READY_ATTRIBUTE = "data-wave-docs-code-ready";
  */
 declare function hasCodeFrame(tree: Root): boolean;
 //#endregion
-export { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE, CODE_READY_ATTRIBUTE, hasCodeFrame };
+export { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE, CODE_ICON_PATHS, CODE_ICON_STATES, CODE_READY_ATTRIBUTE, hasCodeFrame };

package/dist/code-frame.js

@@ -16,6 +16,41 @@ const CODE_COPY_ATTRIBUTE = "data-wave-docs-copy";
 */
 const CODE_READY_ATTRIBUTE = "data-wave-docs-code-ready";
 /**
+* The copy button's three icons, as Lucide paths.
+*
+* ⚠️ PATHS FROM THE SAME SET AS EVERY OTHER ICON HERE, AND THEY WERE FONT
+* GLYPHS. The button rendered `⧉` and swapped in `✓` and `×` through CSS
+* `content` — three characters drawn by whatever font resolved, at whatever
+* weight and baseline that font has, beside a sidebar, a pager and a search
+* dialog that are all Lucide at `stroke-width: 2`. It read as a different
+* icon set because it was one.
+*
+* `copy`, `check` and `x`, on the 24×24 grid the rest of the package uses.
+* Lucide draws its `copy` as a `<rect>` plus a `<path>`; the rect is written
+* here as the path it is, so a frame's icons are one shape of node and the
+* builder stays a list of `d` strings — the same shape `NAV_ICON_PATHS` has.
+*/
+const CODE_ICON_PATHS = {
+	copy: ["M10 8h10a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2H10a2 2 0 0 1-2-2V10a2 2 0 0 1 2-2z", "M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"],
+	check: ["M20 6 9 17l-5-5"],
+	x: ["M18 6 6 18", "m6 6 12 12"]
+};
+/**
+* The three states the button draws, in the order they are emitted.
+*
+* `idle` is what a reader sees; the runtime writes `data-copied` on the button
+* and the stylesheet swaps which of the three is displayed. `display`, not
+* `visibility`: the button is `visibility: hidden` until the runtime attaches,
+* and `visibility` inherits — a child setting it back to `visible` would show
+* an icon inside a button that is meant to be invisible and out of the tab
+* order.
+*/
+const CODE_ICON_STATES = [
+	["idle", "copy"],
+	["copied", "check"],
+	["failed", "x"]
+];
+/**
 * Whether a tree contains a code frame.
 *
 * `DocContent` asks before rendering the runtime, so a page with no fences
@@ -38,4 +73,4 @@ function isCodeFrame(node) {
 	return node.properties[CODE_FRAME_ATTRIBUTE] !== void 0;
 }
 //#endregion
-export { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE, CODE_READY_ATTRIBUTE, hasCodeFrame };
+export { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE, CODE_ICON_PATHS, CODE_ICON_STATES, CODE_READY_ATTRIBUTE, hasCodeFrame };

package/dist/frontmatter.d.ts

@@ -33,6 +33,11 @@ declare const docFrontmatterSchema: z.ZodObject<{
   aliases: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
   order: z.ZodExactOptional<z.ZodNumber>;
   icon: z.ZodExactOptional<z.ZodString>;
+  explore: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+    question: z.ZodString;
+    href: z.ZodString;
+    title: z.ZodExactOptional<z.ZodString>;
+  }, z.core.$strip>>>;
   actions: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
     label: z.ZodString;
     href: z.ZodString;

package/dist/frontmatter.js

@@ -33,6 +33,11 @@ const docFrontmatterSchema = z.object({
 	aliases: z.array(z.string()).exactOptional(),
 	order: z.number().exactOptional(),
 	icon: z.string().min(1).exactOptional(),
+	explore: z.array(z.object({
+		question: z.string().min(1),
+		href: z.string().min(1).refine(isSafeHref, "must be a safe URL (no javascript: or data:)"),
+		title: z.string().min(1).exactOptional()
+	})).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:)"),

package/dist/nav-order.d.ts

@@ -0,0 +1,43 @@
+import { DocNavNode } from "./types.js";
+//#region src/nav-order.d.ts
+/** A destination in the reading order. */
+interface NavStop {
+  title: string;
+  href: string;
+}
+/**
+ * Every page in the tree, in the order a reader meets them.
+ *
+ * ⚠️ SEPARATORS AND EXTERNAL LINKS ARE NOT STOPS. A separator is a label with
+ * nowhere to go, and an external link leaves the documentation entirely — a
+ * "next page" that lands on npm has ended the sequence rather than continued
+ * it. Internal `link` entries *are* stops: they are hand-written entries
+ * pointing at pages of this site, and a reader clicking down the sidebar hits
+ * them like any other row.
+ *
+ * ⚠️ A GROUP CONTRIBUTES ITS OWN PAGE FIRST, WHEN IT HAS ONE. A directory with
+ * an `index.md` renders as a link *and* a disclosure, so the reading order is
+ * the group's page and then its children — which is the order the rows appear
+ * in, and the order someone reading the section would take them.
+ */
+declare function readingOrder(nodes: DocNavNode[], into?: NavStop[]): NavStop[];
+/** The stops either side of `href`, or `undefined` at each end of the sequence. */
+declare function neighbours(nodes: DocNavNode[], href: string): {
+  previous?: NavStop;
+  next?: NavStop;
+};
+/**
+ * A step's link text: the one it named, or the navigation's name for the page.
+ *
+ * ⚠️ A THROW, NOT A FALLBACK TO THE HREF. A row reading "Where this runs and
+ * what that buys → /docs/infrastructure" is a URL where a sentence should be,
+ * and it renders perfectly — nothing else in the pipeline would notice. The
+ * frontmatter is authored and the author is right there, so the build stops and
+ * says which page and which of the two fixes to reach for.
+ */
+declare function stepTitle(stops: NavStop[], step: {
+  href: string;
+  title?: string | undefined;
+}): string | undefined;
+//#endregion
+export { NavStop, neighbours, readingOrder, stepTitle };

package/dist/nav-order.js

@@ -0,0 +1,72 @@
+//#region src/nav-order.ts
+/** Trailing slashes are a routing detail, not a difference in identity. */
+function normalize(href) {
+	return href.length > 1 ? href.replace(/\/+$/, "") : href;
+}
+/**
+* Every page in the tree, in the order a reader meets them.
+*
+* ⚠️ SEPARATORS AND EXTERNAL LINKS ARE NOT STOPS. A separator is a label with
+* nowhere to go, and an external link leaves the documentation entirely — a
+* "next page" that lands on npm has ended the sequence rather than continued
+* it. Internal `link` entries *are* stops: they are hand-written entries
+* pointing at pages of this site, and a reader clicking down the sidebar hits
+* them like any other row.
+*
+* ⚠️ A GROUP CONTRIBUTES ITS OWN PAGE FIRST, WHEN IT HAS ONE. A directory with
+* an `index.md` renders as a link *and* a disclosure, so the reading order is
+* the group's page and then its children — which is the order the rows appear
+* in, and the order someone reading the section would take them.
+*/
+function readingOrder(nodes, into = []) {
+	for (const node of nodes) switch (node.type) {
+		case "page":
+			into.push({
+				title: node.title,
+				href: node.href
+			});
+			break;
+		case "link":
+			if (!node.external) into.push({
+				title: node.title,
+				href: node.href
+			});
+			break;
+		case "group":
+			if (node.href !== void 0) into.push({
+				title: node.title,
+				href: node.href
+			});
+			readingOrder(node.children, into);
+	}
+	return into;
+}
+/** The stops either side of `href`, or `undefined` at each end of the sequence. */
+function neighbours(nodes, href) {
+	const stops = readingOrder(nodes);
+	const here = normalize(href);
+	const at = stops.findIndex((stop) => normalize(stop.href) === here);
+	if (at === -1) return {};
+	const previous = stops[at - 1];
+	const next = stops[at + 1];
+	return {
+		...previous === void 0 ? {} : { previous },
+		...next === void 0 ? {} : { next }
+	};
+}
+/**
+* A step's link text: the one it named, or the navigation's name for the page.
+*
+* ⚠️ A THROW, NOT A FALLBACK TO THE HREF. A row reading "Where this runs and
+* what that buys → /docs/infrastructure" is a URL where a sentence should be,
+* and it renders perfectly — nothing else in the pipeline would notice. The
+* frontmatter is authored and the author is right there, so the build stops and
+* says which page and which of the two fixes to reach for.
+*/
+function stepTitle(stops, step) {
+	if (step.title !== void 0) return step.title;
+	const here = normalize(step.href);
+	return stops.find((stop) => normalize(stop.href) === here)?.title;
+}
+//#endregion
+export { neighbours, readingOrder, stepTitle };

package/dist/next.d.ts

@@ -13,6 +13,16 @@ import { Options } from "minisearch";
 interface DocsRouteOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter> extends DocsConfig<TFrontmatter> {
   /** Overrides merged over the Next-flavoured defaults (`next/link` + `next/image`). */
   components?: MarkdownComponents | undefined;
+  /**
+   * Links to the pages either side of this one, under every page. Default on.
+   *
+   * The order is the navigation's, so it cannot disagree with the sidebar —
+   * see `nav-order.ts`. Nothing is authored: a page gets a pager by being in
+   * the tree, and a page outside it gets none.
+   *
+   * `false` omits it, for a host whose own layout already ends a page.
+   */
+  pager?: boolean | undefined;
   /** Reuse an existing Shiki highlighter. */
   highlighter?: DocsHighlighter | Promise<DocsHighlighter> | undefined;
   /** Grammars to load, when building the default highlighter. */

package/dist/next.js

@@ -3,10 +3,13 @@ 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 { neighbours, readingOrder, stepTitle } from "./nav-order.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 { DocsPager } from "./react/pager.js";
+import { DocsExplore } from "./react/explore.js";
 import { DocsToc } from "./react/toc.js";
 import { wrapNextLink } from "./react/link-adapter.js";
 import { createDocsRenderer } from "./render.js";
@@ -427,6 +430,25 @@ function createDocsRoute(options) {
 			etag: `"${createHash("sha1").update(json).digest("hex")}"`
 		} });
 	};
+	/**
+	* A page's `next` rows with their link text filled in.
+	*
+	* ⚠️ THE ERROR IS THE POINT. Falling back to the href renders a URL where a
+	* sentence should be, on a page that builds cleanly — so an unresolvable row
+	* stops the build and names both fixes.
+	*/
+	async function resolveExplore(doc) {
+		const stops = readingOrder(await requestScopedSource.nav());
+		return (doc.frontmatter.explore ?? []).map((step) => {
+			const title = stepTitle(stops, step);
+			if (title === void 0) throw docsError("invalid-frontmatter", `${doc.href}: the "explore" entry pointing at "${step.href}" has no title, and no page in the navigation owns that route. Point it at a page in the tree, or give the entry its own \`title\` — which is what an external link or a page kept out of the navigation needs.`);
+			return {
+				question: step.question,
+				href: step.href,
+				title
+			};
+		});
+	}
 	async function renderRoute(segments) {
 		const doc = await getPage(segments);
 		if (doc === void 0) return (await loadNotFound())();
@@ -448,6 +470,17 @@ function createDocsRoute(options) {
 				...options.components
 			},
 			...copyLabels === void 0 ? {} : { labels: copyLabels }
+		}), (doc.frontmatter.explore?.length ?? 0) === 0 ? null : createElement(DocsExplore, {
+			links: await resolveExplore(doc),
+			Link: link,
+			...routeLabels?.explore === void 0 ? {} : { heading: routeLabels.explore },
+			...routeLabels?.externalLink === void 0 ? {} : { externalLabel: routeLabels.externalLink }
+		}), options.pager === false ? null : createElement(DocsPager, {
+			...neighbours(await requestScopedSource.nav(), doc.href),
+			Link: link,
+			...routeLabels?.previousPage === void 0 ? {} : { previousLabel: routeLabels.previousPage },
+			...routeLabels?.nextPage === void 0 ? {} : { nextLabel: routeLabels.nextPage },
+			...routeLabels?.pagination === void 0 ? {} : { label: routeLabels.pagination }
 		})), doc.toc.length === 0 ? null : createElement("aside", { className: "wave-docs-layout__toc" }, createElement(DocsToc, {
 			entries: doc.toc,
 			...routeLabels?.toc === void 0 ? {} : { label: routeLabels.toc },

package/dist/plugins/rehype-code-frame.js

@@ -1,4 +1,4 @@
-import { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE } from "../code-frame.js";
+import { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE, CODE_ICON_PATHS, CODE_ICON_STATES } from "../code-frame.js";
 import { parseCodeMeta } from "../code-meta.js";
 import { CONTINUE, SKIP, visit } from "unist-util-visit";
 //#region src/plugins/rehype-code-frame.ts
@@ -28,12 +28,17 @@ const rehypeCodeFrame = (options = {}) => {
 					value: title
 				}]
 			});
-			children.push(copyButton(title === void 0 ? copyLabel : copyFromLabel.replace("{title}", title)), node);
+			children.push(copyButton(title === void 0 ? copyLabel : copyFromLabel.replace("{title}", title)), {
+				type: "element",
+				tagName: "div",
+				properties: { className: ["wave-docs-panel__body", "wave-docs-code__body"] },
+				children: [node]
+			});
 			parent.children[index] = {
 				type: "element",
 				tagName: "figure",
 				properties: {
-					className: ["wave-docs-code"],
+					className: ["wave-docs-panel", "wave-docs-code"],
 					[CODE_FRAME_ATTRIBUTE]: "",
 					...language === void 0 ? {} : { "data-lang": language }
 				},
@@ -60,15 +65,40 @@ function copyButton(label) {
 			[CODE_COPY_ATTRIBUTE]: "",
 			"aria-label": label
 		},
-		children: [{
+		children: CODE_ICON_STATES.map(([state, name]) => stateIcon(state, name))
+	};
+}
+/**
+* One Lucide glyph, as hast.
+*
+* Decoration, so it is out of the accessibility tree — the button reads as its
+* `aria-label` — and out of the search index by the same rule that drops the
+* heading anchor icons.
+*/
+function stateIcon(state, name) {
+	return {
+		type: "element",
+		tagName: "svg",
+		properties: {
+			className: ["wave-docs-code__copy-icon"],
+			"data-state": state,
+			"aria-hidden": "true",
+			focusable: "false",
+			viewBox: "0 0 24 24",
+			width: "16",
+			height: "16",
+			fill: "none",
+			stroke: "currentColor",
+			strokeWidth: "2",
+			strokeLinecap: "round",
+			strokeLinejoin: "round"
+		},
+		children: CODE_ICON_PATHS[name].map((d) => ({
 			type: "element",
-			tagName: "span",
-			properties: { "aria-hidden": "true" },
-			children: [{
-				type: "text",
-				value: "⧉"
-			}]
-		}]
+			tagName: "path",
+			properties: { d },
+			children: []
+		}))
 	};
 }
 /** `code.data.meta` — read, never written. */

package/dist/react/explore.d.ts

@@ -0,0 +1,53 @@
+import { DocsLinkComponent } from "./markdown-components.js";
+import { ReactNode } from "react";
+//#region src/react/explore.d.ts
+/** One row: a question, and the page that answers it. */
+interface DocsExploreLink {
+  question: string;
+  href: string;
+  /** Resolved by the caller — from the navigation, or from the frontmatter. */
+  title: string;
+}
+interface DocsExploreProps {
+  links: DocsExploreLink[];
+  /** The block's heading. Defaults to `'Where to go next'`. */
+  heading?: string | undefined;
+  /** Client-side router link, e.g. `next/link`. Falls back to `<a>`. */
+  Link?: DocsLinkComponent | undefined;
+  /**
+   * Screen-reader suffix on a row whose answer is off-site. Defaults to
+   * `'(opens in a new tab)'`.
+   */
+  externalLabel?: string | undefined;
+  className?: string | undefined;
+}
+/**
+ * "Where to go next" — a question per row, and the page that answers it.
+ *
+ * The sidebar is a structure and this is a router: it says *why* a reader would
+ * go somewhere, which no tree of titles can. A page opts in by declaring
+ * `explore` in its frontmatter, so the same component is a landing page's
+ * onboarding and an ordinary page's footnote.
+ *
+ * ⚠️ `explore`, NOT `next` — AND NOT `steps` EITHER.
+ *
+ * `next` is unusable in this package: `src/next.ts` is the Next.js adapter, so
+ * two files one directory apart would carry the same name for entirely
+ * different things, and `doc.frontmatter.next` would read like a routing hook.
+ *
+ * `steps` is wrong for a second reason: these rows are a *branch*, not a
+ * sequence. A reader picks one and ignores the rest; none of them is first. A
+ * numbered "1 → 2 → 3" component is a real and separate thing worth building,
+ * and `steps` is the name it will need.
+ *
+ * ⚠️ A LIST, NOT A TABLE — which is what the markdown this replaces had to be.
+ * A screen reader announces "table, 2 columns, 7 rows" for what is a list of
+ * links with descriptions, and asks the reader to navigate it by cell. Two
+ * columns of sentence-length questions are also cramped on a phone, where this
+ * stacks instead.
+ *
+ * No client JavaScript: a heading and a list of links, rendered on the server.
+ */
+declare function DocsExplore({ links, heading, Link, externalLabel, className }: DocsExploreProps): ReactNode;
+//#endregion
+export { DocsExplore, DocsExploreLink, DocsExploreProps };

package/dist/react/explore.js

@@ -0,0 +1,86 @@
+import { opensInNewTab } from "../safe-href.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/explore.tsx
+/**
+* "Where to go next" — a question per row, and the page that answers it.
+*
+* The sidebar is a structure and this is a router: it says *why* a reader would
+* go somewhere, which no tree of titles can. A page opts in by declaring
+* `explore` in its frontmatter, so the same component is a landing page's
+* onboarding and an ordinary page's footnote.
+*
+* ⚠️ `explore`, NOT `next` — AND NOT `steps` EITHER.
+*
+* `next` is unusable in this package: `src/next.ts` is the Next.js adapter, so
+* two files one directory apart would carry the same name for entirely
+* different things, and `doc.frontmatter.next` would read like a routing hook.
+*
+* `steps` is wrong for a second reason: these rows are a *branch*, not a
+* sequence. A reader picks one and ignores the rest; none of them is first. A
+* numbered "1 → 2 → 3" component is a real and separate thing worth building,
+* and `steps` is the name it will need.
+*
+* ⚠️ A LIST, NOT A TABLE — which is what the markdown this replaces had to be.
+* A screen reader announces "table, 2 columns, 7 rows" for what is a list of
+* links with descriptions, and asks the reader to navigate it by cell. Two
+* columns of sentence-length questions are also cramped on a phone, where this
+* stacks instead.
+*
+* No client JavaScript: a heading and a list of links, rendered on the server.
+*/
+function DocsExplore({ links, heading = "Where to go next", Link, externalLabel = "(opens in a new tab)", className }) {
+	if (links.length === 0) return null;
+	return /* @__PURE__ */ jsxs("section", {
+		className: [
+			"wave-docs-panel",
+			"wave-docs-explore",
+			className
+		].filter(Boolean).join(" "),
+		"aria-labelledby": "wave-docs-explore-heading",
+		children: [/* @__PURE__ */ jsx("div", {
+			className: "wave-docs-panel__header",
+			children: /* @__PURE__ */ jsx("h2", {
+				className: "wave-docs-panel__title",
+				id: "wave-docs-explore-heading",
+				children: heading
+			})
+		}), /* @__PURE__ */ jsx("ul", {
+			className: "wave-docs-panel__body wave-docs-explore__list",
+			children: links.map((row) => /* @__PURE__ */ jsxs("li", {
+				className: "wave-docs-explore__item",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "wave-docs-explore__question",
+					children: row.question
+				}), /* @__PURE__ */ jsx(ExploreAnswer, {
+					row,
+					Link,
+					externalLabel
+				})]
+			}, row.href))
+		})]
+	});
+}
+function ExploreAnswer({ row, Link, externalLabel }) {
+	const className = "wave-docs-explore__answer";
+	if (opensInNewTab(row.href)) return /* @__PURE__ */ jsxs("a", {
+		className,
+		href: row.href,
+		target: "_blank",
+		rel: "noopener noreferrer",
+		children: [row.title, /* @__PURE__ */ jsxs("span", {
+			className: "wave-docs-sr-only",
+			children: [" ", externalLabel]
+		})]
+	});
+	return Link === void 0 ? /* @__PURE__ */ jsx("a", {
+		className,
+		href: row.href,
+		children: row.title
+	}) : /* @__PURE__ */ jsx(Link, {
+		className,
+		href: row.href,
+		children: row.title
+	});
+}
+//#endregion
+export { DocsExplore };