@waveso/docs 0.9.1 → 0.11.0

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/pager.d.ts

@@ -0,0 +1,42 @@
+import { NavStop } from "../nav-order.js";
+import { DocsLinkComponent } from "./markdown-components.js";
+import { ReactNode } from "react";
+//#region src/react/pager.d.ts
+interface DocsPagerProps {
+  /** The stop before this page in the reading order. Omit at the beginning. */
+  previous?: NavStop | undefined;
+  /** The stop after it. Omit at the end. */
+  next?: NavStop | undefined;
+  /** Client-side router link, e.g. `next/link`. Falls back to `<a>`. */
+  Link?: DocsLinkComponent | undefined;
+  /** Above the previous page's title. Defaults to `'Previous'`. */
+  previousLabel?: string | undefined;
+  /** Above the next page's title. Defaults to `'Next'`. */
+  nextLabel?: string | undefined;
+  /**
+   * Accessible name for the landmark. Defaults to `'Pagination'`.
+   *
+   * Named because a page can hold more than one navigation landmark — this,
+   * the sidebar and the table of contents — and "navigation" three times is
+   * not a list anyone can steer by.
+   */
+  label?: string | undefined;
+  className?: string | undefined;
+}
+/**
+ * Links to the pages either side of this one in the reading order.
+ *
+ * Derived from the same tree `DocsSidebar` renders, so it cannot disagree with
+ * the column beside it — see `nav-order.ts`. Nothing here is authored: a page
+ * gets a pager by being in the navigation.
+ *
+ * ⚠️ NOTHING RENDERS AT ALL WHEN THERE IS NO NEIGHBOUR EITHER SIDE. A single
+ * page site, or a route outside the tree, would otherwise get an empty
+ * landmark — announced by a screen reader as a navigation region containing
+ * nothing, which is worse than the absence it is standing in for.
+ *
+ * No client JavaScript: two links and a heading, rendered on the server.
+ */
+declare function DocsPager({ previous, next, Link, previousLabel, nextLabel, label, className }: DocsPagerProps): ReactNode;
+//#endregion
+export { DocsPager, DocsPagerProps };

package/dist/react/pager.js

@@ -0,0 +1,91 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/pager.tsx
+/**
+* Links to the pages either side of this one in the reading order.
+*
+* Derived from the same tree `DocsSidebar` renders, so it cannot disagree with
+* the column beside it — see `nav-order.ts`. Nothing here is authored: a page
+* gets a pager by being in the navigation.
+*
+* ⚠️ NOTHING RENDERS AT ALL WHEN THERE IS NO NEIGHBOUR EITHER SIDE. A single
+* page site, or a route outside the tree, would otherwise get an empty
+* landmark — announced by a screen reader as a navigation region containing
+* nothing, which is worse than the absence it is standing in for.
+*
+* No client JavaScript: two links and a heading, rendered on the server.
+*/
+function DocsPager({ previous, next, Link, previousLabel = "Previous", nextLabel = "Next", label = "Pagination", className }) {
+	if (previous === void 0 && next === void 0) return null;
+	return /* @__PURE__ */ jsxs("nav", {
+		"aria-label": label,
+		className: ["wave-docs-pager", className].filter(Boolean).join(" "),
+		children: [/* @__PURE__ */ jsx(PagerLink, {
+			stop: previous,
+			direction: "previous",
+			caption: previousLabel,
+			Link
+		}), /* @__PURE__ */ jsx(PagerLink, {
+			stop: next,
+			direction: "next",
+			caption: nextLabel,
+			Link
+		})]
+	});
+}
+function PagerLink({ stop, direction, caption, Link }) {
+	if (stop === void 0) return /* @__PURE__ */ jsx("div", { className: "wave-docs-pager__gap" });
+	const body = /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("span", {
+		className: "wave-docs-pager__caption",
+		children: [
+			direction === "previous" ? /* @__PURE__ */ jsx(PagerChevron, {}) : null,
+			caption,
+			direction === "next" ? /* @__PURE__ */ jsx(PagerChevron, {}) : null
+		]
+	}), /* @__PURE__ */ jsx("span", {
+		className: "wave-docs-pager__title",
+		children: stop.title
+	})] });
+	const props = {
+		className: "wave-docs-pager__link",
+		href: stop.href,
+		"data-direction": direction,
+		"aria-label": `${caption}: ${stop.title}`
+	};
+	return Link === void 0 ? /* @__PURE__ */ jsx("a", {
+		...props,
+		children: body
+	}) : /* @__PURE__ */ jsx(Link, {
+		...props,
+		children: body
+	});
+}
+/**
+* The arrow on the outer edge of each link, pointing the way it goes.
+*
+* Decorative: the link is named "Previous: Installation" by `aria-label`, so
+* this would only repeat a word already in the name — and `⌘`-style symbols
+* read badly when they reach a screen reader at all.
+*
+* Which way it points is the stylesheet's, not this component's: it is a
+* physical direction, and it mirrors under `dir="rtl"` where "previous" is on
+* the right. Rotating it here would put that decision somewhere CSS cannot
+* correct it.
+*/
+function PagerChevron() {
+	return /* @__PURE__ */ jsx("svg", {
+		className: "wave-docs-pager__chevron",
+		"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: /* @__PURE__ */ jsx("path", { d: "m9 18 6-6-6-6" })
+	});
+}
+//#endregion
+export { DocsPager };

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

@@ -70,6 +70,30 @@ interface DocsLabels {
   toc?: string | undefined;
   /** The link at the end of the TOC. Default `'Back to top'`. */
   backToTop?: string | undefined;
+  /**
+   * Above the previous page's title in the pager. Defaults to `'Previous'`.
+   *
+   * 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;
+  /**
+   * Accessible name for the pager landmark. Defaults to `'Pagination'`.
+   *
+   * A page carries three navigation landmarks — the sidebar, the table of
+   * contents and this — and "navigation" three times is not a list anyone can
+   * steer by.
+   */
+  pagination?: string | undefined;
   /**
    * Screen-reader suffix on a link that opens a new tab.
    * Default `'(opens in a new tab)'`.
@@ -137,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", "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,10 @@ const DOCS_LABEL_KEYS = [
 	"youtubeHide",
 	"copyCode",
 	"copyCodeFrom",
+	"explore",
+	"previousPage",
+	"nextPage",
+	"pagination",
 	"copied",
 	"copyFailed"
 ];

package/dist/react/toc.js

@@ -1,6 +1,6 @@
 "use client";
 import { DOCS_CONTENT_ID } from "../docs-content-id.js";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/toc.tsx
 const DEFAULT_ROOT_MARGIN = "0px 0px -60% 0px";
@@ -48,14 +48,26 @@ function DocsToc({ entries, label = "On this page", rootMargin = DEFAULT_ROOT_MA
 		lastIds.current = ids;
 		setActiveId(void 0);
 	}
+	const inBand = useRef(/* @__PURE__ */ new Set());
+	const atBottom = useRef(false);
+	const resolveActive = useCallback(() => {
+		if (atBottom.current) {
+			const last = ids[ids.length - 1];
+			if (last !== void 0) {
+				setActiveId(last);
+				return;
+			}
+		}
+		const next = ids.find((id) => inBand.current.has(id));
+		if (next !== void 0) setActiveId(next);
+	}, [ids]);
 	useEffect(() => {
 		if (ids.length === 0 || typeof IntersectionObserver === "undefined") return;
-		const visible = /* @__PURE__ */ new Set();
+		const visible = inBand.current;
 		const observer = new IntersectionObserver((records) => {
 			for (const record of records) if (record.isIntersecting) visible.add(record.target.id);
 			else visible.delete(record.target.id);
-			const next = ids.find((id) => visible.has(id));
-			if (next !== void 0) setActiveId(next);
+			resolveActive();
 		}, {
 			rootMargin,
 			threshold: 0
@@ -81,7 +93,24 @@ function DocsToc({ entries, label = "On this page", rootMargin = DEFAULT_ROOT_MA
 			if (frame !== void 0) cancelAnimationFrame(frame);
 			observer.disconnect();
 		};
-	}, [ids, rootMargin]);
+	}, [
+		ids,
+		rootMargin,
+		resolveActive
+	]);
+	useEffect(() => {
+		if (ids[ids.length - 1] === void 0 || typeof window === "undefined") return;
+		const onScroll = () => {
+			const scrollable = document.documentElement.scrollHeight - window.innerHeight;
+			const bottom = scrollable > 2 && window.scrollY >= scrollable - 2;
+			if (bottom === atBottom.current) return;
+			atBottom.current = bottom;
+			resolveActive();
+		};
+		window.addEventListener("scroll", onScroll, { passive: true });
+		onScroll();
+		return () => window.removeEventListener("scroll", onScroll);
+	}, [ids, resolveActive]);
 	if (entries.length === 0) return null;
 	return /* @__PURE__ */ jsxs("nav", {
 		"aria-label": label,