@waveso/docs 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,164 @@
 # @waveso/docs
 
+## 0.10.0
+
+### Minor Changes
+
+- f52cb99: **Every page links to the ones either side of it.** `docs.Page` renders a pager
+  under the prose. Nothing is authored: a page gets one by being in the
+  navigation.
+
+  ⚠️ THE ORDER IS THE SIDEBAR'S, NOT THE SLUG LIST'S. `generateStaticParams` has
+  every route in it and no opinion about their order; `meta.json` is where the
+  author said what comes next, and it is what the reader is looking at. Two
+  orderings of the same pages is two answers to one question, and they drift the
+  first time a `meta.json` moves — so the pager reads the same tree `DocsSidebar`
+  renders and flattens it. A pager that disagrees with the column beside it is
+  impossible by construction.
+
+  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 group with an `index.md` contributes its own page
+  before its children, which is the order its rows appear in.
+
+  ⚠️ A PAGE OUTSIDE THE TREE GETS NO PAGER, RATHER THAN THE FIRST ONE. `-1` from
+  `findIndex` reads as "just before the beginning", so an unguarded lookup hands
+  every draft and every route rendered outside the navigation the same first page
+  as its "next" — confidently wrong on exactly the pages nobody checks.
+
+  ⚠️ AND AN EMPTY CELL AT EACH END, NOT A MISSING ONE. The two links share a grid
+  row; drop the absent side and the survivor slides into the first track, so the
+  first page of a site puts "Next" on the left and every other page puts it on
+  the right. The one page where the position moves is the one a reader sees
+  first.
+
+  Nothing renders at all when there is no neighbour either side — a one-page site
+  would otherwise get a navigation landmark containing nothing.
+
+  A chevron on the outer edge of each link points the way it goes.
+
+  ⚠️ AND "OUTWARD" MIRRORS. Under `dir="rtl"` the grid's first track is on the
+  right, so the _previous_ link moves there and its arrow has to point right —
+  the reverse of the rule that draws it. Same trap as the sidebar's chevron, in a
+  component built after it, and `[dir='rtl']` again rather than `:dir(rtl)`.
+
+  No client JavaScript: two links, two captions and two glyphs, rendered on the
+  server. Each
+  link is named by direction _and_ destination — "Previous: Installation" — since
+  a link announced as a bare title says nothing about which way it goes. The
+  landmark is named too, because a page now carries three of them.
+
+  New: `DocsPager` at `@waveso/docs/react/pager`, `pager: false` on
+  `createDocsRoute` to omit it, and `previousPage`, `nextPage` and `pagination`
+  in `labels`.
+
+### Patch Changes
+
+- 09a9369: The sidebar grip says whether it has anything to do.
+
+  Blue when the navigation is hidden or the pointer is on it; grey when the
+  sidebar is open and untouched. One rule at every width — a closed sidebar is
+  the same request for attention on a phone as on a desktop.
+
+  ⚠️ `:not([data-state='open'])`, NOT `[data-state='closed']`. The attribute is
+  absent until the reader chooses, and a server-rendered page has none — so
+  matching only the explicit value leaves every first paint below 64rem showing a
+  grey grip in front of hidden navigation, which is the one moment the cue is
+  for. Above 64rem the default inverts, and a second rule says so.
+
+  ⚠️ AND THE COLOUR IS A CUSTOM PROPERTY, NOT A SELECTOR FIGHT. Three things want
+  to set it — the resting style, the pointer, and the sidebar's state — and the
+  state lives on an _ancestor_, so `.sidebar[data-state] .trigger::before`
+  outranks `.trigger:hover::before` by a whole class. Written as backgrounds that
+  is a rule which silently kills hover on the one state that still needs it.
+  Properties settle it by inheritance: the state sets them on the sidebar, the
+  trigger sets them on itself under `:hover`, and a value on the element always
+  beats one it inherited. No specificity ladder, no `!important`.
+
+  The grip is also a full pill now rather than a rounded rectangle.
+
+  ⚠️ TESTED AS MARKUP, BECAUSE A MOUNTED COMPONENT CANNOT SHOW THE UNTOUCHED
+  STATE. `DocsNav` resolves the mode on mount and writes `data-state`
+  immediately, so every React fixture is already explicit. Two wrong versions
+  passed the whole suite against that — matching the explicit value, and dropping
+  the wide-layout reset — and both are caught now by a server-shaped fixture with
+  no attribute at all.
+
+  Also fixed here: the focus-indicator guard looked up one rule per selector, and
+  a selector may legitimately appear in several. The trigger now has one rule
+  setting properties on focus and another drawing the ring; taking "the first" or
+  "the last" is a coin flip on file order, so it reads every rule and asks for
+  one to declare an outline.
+
+## 0.9.2
+
+### Patch Changes
+
+- 6b84354: A separator now rules off the block above it.
+
+  It ends one section as much as it names the next, and 1rem of margin was not
+  saying so — the gap read as "these two lists are a bit far apart" rather than as
+  a division.
+
+  ⚠️ THE RULE AND THE LABEL SHARE THE LIST'S OWN EDGE, WHICH IS ALSO THE ROWS'. A
+  row is full-bleed — its hover surface spans the whole column, and so does the
+  search field above it — so a rule on that edge divides the column, while an
+  inset one floats inside it. The label sits on the same line, because a heading
+  and the rule above it reading as one object is the whole reason the rule exists.
+
+  The label keeps the rows' own content edge — the marker column when there is
+  one, the words when `icons={false}` removes it. Those are the same number: a
+  row's `padding-inline` is what both modes have in common, so matching it lands
+  on whichever is there, with no query and nothing threaded to the stylesheet.
+
+  ⚠️ AND NOT ABOVE THE FIRST CHILD. A `meta.json` may open with
+  `"---Reference---"`, and on that tree the very first thing in the navigation
+  would otherwise be a hairline above nothing.
+
+  The label also drops from `font-weight: 650` to `500`. At 650 it was heavier
+  than the group titles it sits under — a divider out-shouting the navigation it
+  divides. Weight rather than colour, because there is no lighter colour to
+  reach for: `--wave-docs-fg-subtle` is already the lightest text token at 5.05:1
+  against WCAG 1.4.3's 4.5:1 floor, and `--wave-docs-border` — the rule's own
+  colour — measures 1.31:1 and is a line colour, not a text one.
+
+- 7e67c5a: The table of contents marks the last section when you reach it.
+
+  Scroll to the foot of a page whose final section is short and nothing happened:
+  the entry stayed on the section _above_, and the last one could only be
+  highlighted by clicking its own link.
+
+  ⚠️ NO `rootMargin` FIXES THIS, WHICH IS WHY IT LOOKED LIKE A TUNING PROBLEM.
+  The default makes the top 40% of the viewport the region that counts as
+  current, and that is right while there is document left to scroll — a heading
+  rises into the band and takes the highlight. At the end there is none. A short
+  trailing section sits on screen, fully readable, below a band it can never
+  enter, while the heading above it is still _inside_ that band. The observer was
+  giving a correct answer to the wrong question. Any band smaller than the
+  viewport has this hole; a bigger one only trades it for a highlight that jumps
+  early.
+
+  So the end of the document is handled as what it is — a place where scrolling
+  stops answering — and the last heading takes the highlight there. Scroll up and
+  the band has it straight back, without waiting for a heading to cross.
+
+  ⚠️ AND BOTH INPUTS GO THROUGH ONE RESOLVER, WHICH IS THE HALF THAT IS EASY TO
+  MISS. Left as two `setActiveId` calls they race, and the observer wins — it
+  fires last and it still likes the heading above. The first version of this fix
+  was measured doing exactly nothing for that reason.
+
+  ⚠️ ONLY WHEN THE DOCUMENT ACTUALLY SCROLLS. On a page that fits, "scrolled to
+  the bottom" is true at rest, and the last section would be current before the
+  reader had read a word of the first.
+
+  The listener is `passive` and reads two numbers — no `getBoundingClientRect`,
+  no layout flush. Like every other scroll reader here it watches the document; a
+  host that scrolls an inner pane keeps the observer's behaviour and loses only
+  this tail case.
+
+  `toc` grows 0.88 → 1 KB, and the published total 14.5 → 14.6 KB. It is still
+  the smallest client component in the package.
+
 ## 0.9.1
 
 ### Patch Changes

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,7 @@ 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) |
+| `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 +215,24 @@ 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.
 
+### 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.

package/dist/nav-order.d.ts

@@ -0,0 +1,30 @@
+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;
+};
+//#endregion
+export { NavStop, neighbours, readingOrder };

package/dist/nav-order.js

@@ -0,0 +1,58 @@
+//#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 }
+	};
+}
+//#endregion
+export { neighbours, readingOrder };

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,12 @@ 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 { 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 { DocsToc } from "./react/toc.js";
 import { wrapNextLink } from "./react/link-adapter.js";
 import { createDocsRenderer } from "./render.js";
@@ -448,6 +450,12 @@ function createDocsRoute(options) {
 				...options.components
 			},
 			...copyLabels === void 0 ? {} : { labels: copyLabels }
+		}), 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/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,23 @@ 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.
+   */
+  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 +154,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", "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,9 @@ const DOCS_LABEL_KEYS = [
 	"youtubeHide",
 	"copyCode",
 	"copyCodeFrom",
+	"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,

package/dist/styles.css

@@ -382,12 +382,19 @@
    * Declared at all because inheriting means a host that never set a family
    * renders its documentation in the UA serif. `--wave-docs-font-sans: inherit`
    * gives the host's typeface back in one line.
+   *
+   * ⚠️ EVERY NEW ROOT HAS TO BE ADDED HERE, AND ONE ALREADY WAS NOT. The pager
+   * sits inside `<main>` but outside `.wave-docs-prose` — `DocContent` owns
+   * that class — so it matched nothing in this list and shipped its page titles
+   * in Times. Caught in a screenshot, not by a test: nothing here fails when a
+   * root is missing, it just renders wrong.
    */
   .wave-docs-prose,
   .wave-docs-sidebar,
   .wave-docs-toc,
   .wave-docs-skip-link,
   .wave-docs-hero,
+  .wave-docs-pager,
   .wave-docs-layout__sidebar,
   .wave-docs-search-trigger,
   .wave-docs-search-dialog {
@@ -1764,10 +1771,37 @@
     rotate: 90deg;
   }
 
+  /*
+   * A separator ends the block above it as much as it names the block below,
+   * and a rule says that in a way whitespace alone cannot: at 1rem of margin
+   * the gap read as "these two lists are a bit far apart" rather than as a
+   * division.
+   *
+   * ⚠️ THE RULE AND THE LABEL SHARE THE LIST'S OWN EDGE, WHICH IS ALSO THE
+   * ROWS'. A row is full-bleed — its hover surface spans the whole column, and
+   * so does the search field above it — so a rule on that edge divides the
+   * column, while an inset one floats inside it. The label sits on the same
+   * line, because a heading and the rule above it reading as one object is the
+   * whole reason the rule is there.
+   *
+   * Measured before this: the label sat at 24px, the rows' *icon* column. It
+   * headed a column of decoration, a step in from the words it names and a step
+   * out from the edge — aligned with neither.
+   *
+   * ⚠️ AND NO RULE ON THE FIRST CHILD, which would draw a line above nothing. A
+   * `meta.json` may open with `"---Reference---"`, and on that tree the very
+   * first thing in the navigation would be a hairline.
+   */
   .wave-docs-sidebar__separator-item {
     margin-block: 1rem 0.25rem;
   }
 
+  .wave-docs-sidebar__separator-item:not(:first-child) {
+    margin-block-start: 1rem;
+    padding-block-start: 1rem;
+    border-block-start: 1px solid var(--wave-docs-border);
+  }
+
   /*
    * ⚠️ NO `text-transform: uppercase`, AND IT USED TO HAVE ONE.
    *
@@ -1784,12 +1818,38 @@
    * single character. `letter-spacing` went with them: it exists to make caps
    * legible, and on sentence case it only reads as loose.
    */
+  /*
+   * The label starts where a row's content starts — the marker column when
+   * there is one, the words when there is not.
+   *
+   * ⚠️ THAT IS ONE NUMBER, NOT TWO, AND CHASING IT WITH `:has()` WAS THE WRONG
+   * SHAPE. A row's own `padding-inline` is what both modes have in common: with
+   * markers the icon sits on it, with `icons={false}` the text does. Matching
+   * the row's padding lands on whichever is there, in both modes, with no
+   * query and nothing threaded.
+   *
+   * The *rule* keeps the column's edge instead — it divides the column rather
+   * than naming anything. See `__separator-item`.
+   */
   .wave-docs-sidebar__separator {
     display: block;
-    padding-inline: 0.5rem;
+    padding-inline-start: 0.5rem;
     color: var(--wave-docs-fg-subtle);
     font-size: 0.75rem;
-    font-weight: 650;
+    /*
+     * ⚠️ THE WEIGHT IS THE LEVER HERE, NOT THE COLOUR. At 650 this label was
+     * heavier than the group titles it sits under and read as the loudest thing
+     * in the column — a divider out-shouting the navigation it divides.
+     *
+     * The obvious fix is a lighter colour, and there is none to reach for:
+     * `--wave-docs-fg-subtle` is already the lightest text token at 5.05:1 on
+     * the page, against WCAG 1.4.3's 4.5:1 floor for text this size — 0.55 of
+     * slack. `--wave-docs-border`, which is what the rule above it is painted
+     * with, measures 1.31:1 and is a line colour, not a text one.
+     *
+     * 500 drops it below the rows without touching the contrast at all.
+     */
+    font-weight: 500;
   }
 
   @media (prefers-reduced-motion: no-preference) {
@@ -1828,6 +1888,133 @@
   }
 }
 
+/* ---------------------------------------------------------------------------
+ * Pager
+ *
+ * Links to the pages either side of this one, emitted by `docs.Page` at the
+ * foot of the article.
+ * ------------------------------------------------------------------------ */
+
+@layer components {
+  /*
+   * ⚠️ TWO TRACKS, ALWAYS — WHICH IS WHY THE COMPONENT RENDERS AN EMPTY CELL
+   * RATHER THAN NOTHING AT EACH END OF THE SEQUENCE. With `auto-fit` or a
+   * plain flex row, the first page of a site puts its only link — `Next` — on
+   * the left, and every other page puts it on the right. The reader learns the
+   * position, and the one page where it moves is the one they see first.
+   *
+   * ⚠️ THE MEASURE *AND* THE CENTRING, WHICH IS TWO DECLARATIONS AND I SHIPPED
+   * ONE. `.wave-docs-prose` is capped and centred inside `__main`, so a
+   * `max-width` alone left this the right width in the wrong place: the
+   * paragraphs began at 440px and the pager at 304px, a 136px step directly
+   * under them. It belongs to the prose, so it takes both halves of what puts
+   * the prose where it is.
+   */
+  .wave-docs-pager {
+    display: grid;
+    margin-inline: auto;
+    /* `minmax(0, 1fr)`, never a bare `1fr`: that floors each track at its
+     * content's min-content width, so a long page title pushes the pair past
+     * the measure instead of wrapping inside it. */
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+    gap: 0.75rem;
+    max-width: var(--wave-docs-measure);
+    margin-block-start: 3rem;
+  }
+
+  .wave-docs-pager__link {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    padding: 0.75rem 1rem;
+    border: 1px solid var(--wave-docs-border);
+    border-radius: var(--wave-docs-radius);
+    color: var(--wave-docs-fg);
+    text-decoration: none;
+  }
+
+  /*
+   * The next page is set to its own edge, so the pair reads outward from the
+   * middle — the direction each one takes you. `text-align` and not
+   * `align-items`, so a title that wraps to two lines stays aligned with
+   * itself rather than ragging against the box.
+   */
+  .wave-docs-pager__link[data-direction='next'] {
+    text-align: end;
+  }
+
+  /*
+   * ⚠️ THE ARROW POINTS OUTWARD, AND "OUTWARD" MIRRORS. Under `dir="rtl"` the
+   * grid's first track is on the right, so the *previous* link moves there and
+   * its arrow has to point right — the reverse of both rules above it. Same
+   * shape as the sidebar's chevron, and the same reason it is `[dir='rtl']`
+   * rather than `:dir(rtl)`: lightningcss rewrites the latter into a list of
+   * right-to-left *languages*, which is not the same question.
+   *
+   * Source order is load-bearing in the middle pair: `[dir='rtl'] .chevron` and
+   * `[data-direction='next'] .chevron` have the same specificity, so the
+   * mirror only wins by being written second.
+   */
+  .wave-docs-pager__chevron {
+    flex: none;
+    /* Sized down from the 16 it is drawn at: beside 12px type a full-size
+     * chevron is the loudest thing in the card. */
+    inline-size: 0.875rem;
+    block-size: 0.875rem;
+    rotate: 180deg;
+  }
+
+  .wave-docs-pager__link[data-direction='next'] .wave-docs-pager__chevron {
+    rotate: 0deg;
+  }
+
+  [dir='rtl'] .wave-docs-pager__chevron {
+    rotate: 0deg;
+  }
+
+  [dir='rtl']
+    .wave-docs-pager__link[data-direction='next']
+    .wave-docs-pager__chevron {
+    rotate: 180deg;
+  }
+
+  /* The arrow shares the caption's line, so the two read as one label and the
+   * title below starts at the card's own edge. */
+  .wave-docs-pager__caption {
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+    color: var(--wave-docs-fg-subtle);
+    font-size: 0.75rem;
+  }
+
+  .wave-docs-pager__link[data-direction='next'] .wave-docs-pager__caption {
+    justify-content: flex-end;
+  }
+
+  .wave-docs-pager__title {
+    font-weight: 600;
+  }
+
+  .wave-docs-pager__link:hover {
+    border-color: var(--wave-docs-border-strong);
+    background: var(--wave-docs-bg-subtle);
+  }
+
+  .wave-docs-pager__link:focus-visible {
+    outline: 2px solid var(--wave-docs-accent);
+    outline-offset: 2px;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .wave-docs-pager__link {
+      transition:
+        background-color 150ms ease-out,
+        border-color 150ms ease-out;
+    }
+  }
+}
+
 /* ---------------------------------------------------------------------------
  * Table of contents
  * ------------------------------------------------------------------------ */
@@ -2574,6 +2761,47 @@
    * 20px transparent border for a while to answer to 44 while painting 24, and
    * a box the eye cannot see is a box the next person deletes.
    */
+  /*
+   * ⚠️ THE GRIP'S COLOUR IS A CUSTOM PROPERTY, NOT A SELECTOR FIGHT.
+   *
+   * Three things want to set it: the resting style, the reader's pointer, and
+   * the sidebar's own state — and the state lives on an *ancestor*, so
+   * `.sidebar[data-state] .trigger::before` outranks `.trigger:hover::before`
+   * by a whole class. Written as backgrounds that is a rule that silently kills
+   * hover on the one state that still needs it.
+   *
+   * Custom properties settle it by inheritance instead: the state sets them on
+   * the sidebar, the trigger sets them on itself under `:hover`, and a value on
+   * the element always beats one it inherited. No specificity, no `!important`,
+   * and the hover rule stays two lines long.
+   */
+  .wave-docs-layout__sidebar {
+    --wave-docs-trigger-fill: var(--wave-docs-border-strong);
+    --wave-docs-trigger-ink: var(--wave-docs-fg-muted);
+    --wave-docs-trigger-opacity: 0.4;
+  }
+
+  /*
+   * Blue means the grip is the thing to press; grey means it is at rest.
+   *
+   * The navigation is hidden and this is the way back to it — so a closed
+   * sidebar lights the grip, exactly as the pointer does. Open, the grip has
+   * nothing to offer that the visible column does not, and it goes quiet.
+   *
+   * ⚠️ `:not([data-state='open'])`, NOT `[data-state='closed']`. Below 64rem
+   * the sidebar starts closed and the attribute is absent until the reader
+   * chooses — a server-rendered page has no state at all. Matching only the
+   * explicit value leaves every first paint on a phone showing a grey grip in
+   * front of hidden navigation, which is the one moment the cue is for.
+   *
+   * The wide layout inverts the default, and overrides this below.
+   */
+  .wave-docs-layout__sidebar:not([data-state='open']) {
+    --wave-docs-trigger-fill: var(--wave-docs-accent);
+    --wave-docs-trigger-ink: var(--wave-docs-accent-fg);
+    --wave-docs-trigger-opacity: 1;
+  }
+
   .wave-docs-layout__sidebar-trigger {
     flex: none;
     /*
@@ -2603,7 +2831,7 @@
     padding: 4px;
     border: 0;
     background: none;
-    color: var(--wave-docs-fg-muted);
+    color: var(--wave-docs-trigger-ink);
     cursor: pointer;
   }
 
@@ -2627,8 +2855,10 @@
      * of the three dots, and nothing here scales with the pill: see `::after`.
      */
     height: 3.5rem;
-    border-radius: var(--wave-docs-radius-sm);
-    background-color: var(--wave-docs-border-strong);
+    /* A full pill: the radius is half the *short* side, so `9999px` clamps to
+     * exactly that whatever the two dimensions become. */
+    border-radius: 9999px;
+    background-color: var(--wave-docs-trigger-fill);
   }
 
   /*
@@ -2680,14 +2910,17 @@
    */
   .wave-docs-layout__sidebar-trigger::before,
   .wave-docs-layout__sidebar-trigger::after {
-    opacity: 0.4;
+    opacity: var(--wave-docs-trigger-opacity);
   }
 
-  .wave-docs-layout__sidebar-trigger:hover::before,
-  .wave-docs-layout__sidebar-trigger:hover::after,
-  .wave-docs-layout__sidebar-trigger:focus-visible::before,
-  .wave-docs-layout__sidebar-trigger:focus-visible::after {
-    opacity: 1;
+  /* On the element, not on the pseudo-elements: a custom property set here is
+   * inherited by both, and beats the sidebar's regardless of how specific the
+   * state selector that set it was. */
+  .wave-docs-layout__sidebar-trigger:hover,
+  .wave-docs-layout__sidebar-trigger:focus-visible {
+    --wave-docs-trigger-fill: var(--wave-docs-accent);
+    --wave-docs-trigger-ink: var(--wave-docs-accent-fg);
+    --wave-docs-trigger-opacity: 1;
   }
 
   /*
@@ -2702,11 +2935,6 @@
       var(--wave-docs-accent) 30%,
       transparent
     );
-    color: var(--wave-docs-accent-fg);
-  }
-
-  .wave-docs-layout__sidebar-trigger:hover::before {
-    background-color: var(--wave-docs-accent);
   }
 
   @media (prefers-reduced-motion: no-preference) {
@@ -2830,6 +3058,18 @@
       margin-inline-end: 0;
     }
 
+    /*
+     * Unchosen means *open* up here, so the grip is at rest by default — the
+     * mirror of the rule above, and the reason that one is written as
+     * "not open" rather than "closed". A closed sidebar keeps the blue it
+     * inherits from there; nothing needs restating.
+     */
+    .wave-docs-layout__sidebar:not([data-state='closed']) {
+      --wave-docs-trigger-fill: var(--wave-docs-border-strong);
+      --wave-docs-trigger-ink: var(--wave-docs-fg-muted);
+      --wave-docs-trigger-opacity: 0.4;
+    }
+
     /* Nothing is covered, so nothing is scrimmed. */
     .wave-docs-layout__sidebar-scrim {
       display: none;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waveso/docs",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Zero parser bytes in the browser: markdown docs for Next.js, built to hast in Node and rendered as your components",
   "type": "module",
   "sideEffects": [
@@ -107,6 +107,10 @@
     "./react/youtube": {
       "types": "./dist/react/youtube.d.ts",
       "default": "./dist/react/youtube.js"
+    },
+    "./react/pager": {
+      "types": "./dist/react/pager.d.ts",
+      "default": "./dist/react/pager.js"
     }
   },
   "files": [