@waveso/docs 0.10.0 → 0.11.0

package/dist/next.js

@@ -3,12 +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 } from "./nav-order.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";
@@ -429,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())();
@@ -450,6 +470,11 @@ 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,

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

package/dist/react/markdown-components.js

@@ -110,6 +110,20 @@ function createImage(Image) {
 * "no tabindex on non-interactive elements", not a violation of it. A labelled
 * `<section>` is a `region` landmark, so the tab stop announces itself instead
 * of being a mystery stop in the tab order.
+*
+* ⚠️ ONE FRAME, AND IT WORE `.wave-docs-panel` FOR A WHILE.
+*
+* The panel — an outer frame, a header band, an inset card — exists to separate
+* *chrome* from *content*. "Where to go next" and a code frame both have chrome
+* to put in that band: a title, a language, a copy button. A table's header row
+* is not chrome, it is data, and setting the body into a card away from its own
+* header cost three vertical rules down each side, stopped the row dividers
+* short of the box, and narrowed the reading width — on the densest element on
+* a page, for nothing gained. Full-width dividers are what let an eye track a
+* row across.
+*
+* It keeps the panel's outer radius, so a table and a code block still read as
+* two of one family without the table pretending to have chrome it has not got.
 */
 function createTable(label) {
 	return function MarkdownTable({ className, ...rest }) {

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

@@ -76,6 +76,13 @@ interface DocsLabels {
    * The direction, not the destination: the page's own title is the name, and
    * these two words are what say which way it lies.
    */
+  /**
+   * The "where to go next" block's heading. Defaults to `'Where to go next'`.
+   *
+   * A page opts into that block with `explore` in its frontmatter; this is the one
+   * string the package supplies for it, and the questions are the author's.
+   */
+  explore?: string | undefined;
   previousPage?: string | undefined;
   /** The same for the next page. Defaults to `'Next'`. */
   nextPage?: string | undefined;
@@ -154,7 +161,7 @@ interface DocsLabels {
  * failure being guarded against is a key that is declared, documented and never
  * read, which type-checks perfectly.
  */
-declare const DOCS_LABEL_KEYS: readonly ["nav", "openNav", "closeNav", "skipToContent", "expandGroup", "collapseGroup", "toc", "backToTop", "externalLink", "table", "calloutNote", "calloutTip", "calloutImportant", "calloutWarning", "calloutCaution", "youtubeTitle", "youtubePlay", "youtubeHide", "copyCode", "copyCodeFrom", "previousPage", "nextPage", "pagination", "copied", "copyFailed"];
+declare const DOCS_LABEL_KEYS: readonly ["nav", "openNav", "closeNav", "skipToContent", "expandGroup", "collapseGroup", "toc", "backToTop", "externalLink", "table", "calloutNote", "calloutTip", "calloutImportant", "calloutWarning", "calloutCaution", "youtubeTitle", "youtubePlay", "youtubeHide", "copyCode", "copyCodeFrom", "explore", "previousPage", "nextPage", "pagination", "copied", "copyFailed"];
 /** The four the shell renders itself, resolved centrally. */
 type ShellLabelKey = 'nav' | 'openNav' | 'closeNav' | 'skipToContent';
 /**

package/dist/react/shell-labels.js

@@ -27,6 +27,7 @@ const DOCS_LABEL_KEYS = [
 	"youtubeHide",
 	"copyCode",
 	"copyCodeFrom",
+	"explore",
 	"previousPage",
 	"nextPage",
 	"pagination",