npm - @waveso/docs - Versions diffs - 0.2.0 → 0.4.0 - Mend

@waveso/docs 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (59) hide show

package/CHANGELOG.md +138 -0
package/README.md +490 -75
package/dist/code-frame.d.ts +29 -0
package/dist/code-frame.js +41 -0
package/dist/code-meta.d.ts +48 -0
package/dist/code-meta.js +72 -0
package/dist/docs-content-id.d.ts +19 -0
package/dist/docs-content-id.js +19 -0
package/dist/docs-error.d.ts +2 -57
package/dist/docs-error.js +3 -15
package/dist/errors.d.ts +94 -0
package/dist/errors.js +45 -0
package/dist/next.d.ts +153 -28
package/dist/next.js +65 -33
package/dist/plugins/rehype-capture-toc.js +26 -5
package/dist/plugins/rehype-code-frame.d.ts +10 -0
package/dist/plugins/rehype-code-frame.js +88 -0
package/dist/plugins/rehype-code-language.js +7 -1
package/dist/react/code-runtime.d.ts +14 -0
package/dist/react/code-runtime.js +161 -0
package/dist/react/doc-content.d.ts +39 -2
package/dist/react/doc-content.js +42 -10
package/dist/react/layout.d.ts +44 -0
package/dist/react/layout.js +65 -0
package/dist/react/nav.d.ts +28 -0
package/dist/react/nav.js +70 -0
package/dist/react/nearest-scroll-top.d.ts +45 -0
package/dist/react/nearest-scroll-top.js +44 -0
package/dist/react/next-link.d.ts +34 -0
package/dist/react/next-link.js +30 -0
package/dist/react/next-nav.d.ts +11 -0
package/dist/react/next-nav.js +32 -0
package/dist/react/next-search.d.ts +22 -0
package/dist/react/next-search.js +52 -0
package/dist/react/search-dialog.d.ts +53 -10
package/dist/react/search-dialog.js +147 -47
package/dist/react/shell-labels.d.ts +43 -0
package/dist/react/shell-labels.js +27 -0
package/dist/react/sidebar.d.ts +38 -3
package/dist/react/sidebar.js +104 -12
package/dist/react/skip-link.d.ts +1 -9
package/dist/react/skip-link.js +6 -5
package/dist/react/toc.d.ts +12 -4
package/dist/react/toc.js +18 -7
package/dist/react/youtube.d.ts +31 -5
package/dist/react/youtube.js +76 -54
package/dist/render.d.ts +35 -1
package/dist/render.js +35 -14
package/dist/route-path.d.ts +46 -0
package/dist/route-path.js +51 -0
package/dist/search-index.d.ts +6 -23
package/dist/search-index.js +6 -51
package/dist/sitemap-limit.d.ts +34 -0
package/dist/sitemap-limit.js +37 -0
package/dist/source.d.ts +1 -23
package/dist/source.js +40 -43
package/dist/styles.css +1001 -106
package/dist/types.d.ts +11 -2
package/package.json +58 -23

package/dist/next.d.ts CHANGED Viewed

@@ -1,8 +1,12 @@
-import { DocFile, DocFrontmatter, DocsConfig, ImageResolver, LinkResolver, RenderedDoc } from "./types.js";
+import { DocFile, DocFrontmatter, DocsConfig, ImageResolver, LinkResolver, RenderedDoc, SearchRecord } from "./types.js";
 import { DocsHighlighter, DocsLang, DocsTheme, DocsThemes } from "./highlighter.js";
 import { MarkdownComponents } from "./react/markdown-components.js";
+import { DocsLabels } from "./react/shell-labels.js";
+import { DocsLayoutSearchProps } from "./react/layout.js";
 import { DocsSource } from "./source.js";
 import { ReactNode } from "react";
+import { PluggableList } from "unified";
+import { Options } from "minisearch";
 //#region src/next.d.ts
 interface DocsRouteOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter> extends DocsConfig<TFrontmatter> {
   /** Overrides merged over the Next-flavoured defaults (`next/link` + `next/image`). */
@@ -27,22 +31,17 @@ interface DocsRouteOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter>
    */
   titleHeading?: boolean | undefined;
   /**
-   * `id` of the rendered `<article>`, which is also what
-   * `@waveso/docs/react/skip-link` targets by default. Defaults to
-   * `'docs-content'`. Pass `false` to render no id at all.
+   * Extra remark plugins, attached after `remarkGfm` and before link
+   * resolution — so anything they emit is folded, contained and asserted like
+   * authored markdown.
    */
-  contentId?: string | false | undefined;
+  remarkPlugins?: PluggableList | undefined;
   /**
-   * Re-read the content directory on every request.
-   *
-   * Defaults to `true` outside `NODE_ENV=production`. Markdown files are not in
-   * Next's module graph, so nothing re-evaluates a route module when one
-   * changes: without this, `next dev` serves whatever it read on the first
-   * request until the server restarts, and a file added afterwards is never
-   * found. A rescan of a few hundred small files costs single-digit
-   * milliseconds; a production build reads the tree once, as it should.
+   * Extra rehype plugins, attached after heading ids and permalinks exist and
+   * before the code steps — so a `<pre>` is still the author's text rather
+   * than Shiki's token spans.
    */
-  rescanPerRequest?: boolean | undefined;
+  rehypePlugins?: PluggableList | undefined;
   /** Replaces the built-in markdown-link resolution. */
   linkResolver?: LinkResolver | undefined;
   /**
@@ -59,6 +58,64 @@ interface DocsRouteOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter>
    * set neither, you ship pages with no usable canonical.
    */
   siteUrl?: string | undefined;
+  /**
+   * MiniSearch overrides for the index {@link DocsRoute.searchIndex} builds.
+   *
+   * ⚠️ THE IDENTICAL OBJECT MUST REACH THE DIALOG — pass it to `DocsSearch`'s
+   * (or `SearchDialog`'s) `miniSearchOptions`. MiniSearch reads `tokenize` and
+   * `processTerm` both when indexing and when querying, so applying one here
+   * and not there produces an index whose terms no query can spell: zero
+   * results, no error, nothing in the console.
+   */
+  miniSearchOptions?: Partial<Options<SearchRecord>> | undefined;
+}
+/**
+ * Props for {@link DocsRoute.Layout}.
+ *
+ * Four, and the fourth is a boolean. Everything else a docs shell is asked for
+ * turned out to be reachable already: an announcement banner renders *above*
+ * `<docs.Layout>` in your own `layout.tsx`, because this does not own `<body>`;
+ * a content footer goes inside `children`; and sidebar links, social icons and
+ * separators are `DocNavNode`s authored in `meta.json`. The header bar is the
+ * one region nothing else can reach, which is what `actions` is for.
+ *
+ * A `slots` map was the alternative, and it can still be added later — two node
+ * props can become a slots map, a slots map cannot become two props.
+ */
+interface DocsLayoutProps {
+  children: ReactNode;
+  /**
+   * Brand at the header start. A string, or your own logo component.
+   *
+   * `ReactNode`, so it cannot also serve as the `<title>` or as the header's
+   * accessible name; the landmark carries a fixed label instead.
+   */
+  title?: ReactNode;
+  /** Header end, after search: a theme toggle, a version switcher, a link. */
+  actions?: ReactNode;
+  /**
+   * The search trigger. Defaults to on, and the URL is always derived.
+   *
+   * `false` omits it. An object configures the dialog — `placeholder`,
+   * `hotkey`, `miniSearchOptions` and the rest of `DocsSearch`'s surface,
+   * minus `indexUrl`.
+   *
+   * You do not need to pass `miniSearchOptions` here to match what
+   * `createDocsRoute` was given: the route's own value is forwarded, so the
+   * object that built the index is the object that queries it. Pass one only
+   * to override that.
+   */
+  search?: boolean | DocsLayoutSearchProps | undefined;
+  /**
+   * The four strings the shell renders itself: the navigation landmark's name,
+   * the drawer's open and close buttons, and the skip link.
+   *
+   * Everything else a reader sees is your markdown or your `title`. This is the
+   * whole of what a non-English site has to say — and it is the fifth prop,
+   * added deliberately: a documentation shell nobody can translate is not a
+   * shell for the whole ecosystem.
+   */
+  labels?: DocsLabels | undefined;
 }
 /** Props Next hands a page in the App Router. */
 interface DocsPageProps {
@@ -175,11 +232,89 @@ interface DocsRoute<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
    */
   getPage: (segments: string[]) => Promise<RenderedDoc<TFrontmatter> | undefined>;
   /**
-   * Every published page, rendered. The input to
-   * `extractSearchRecords`/`writeSearchIndex` — nothing builds the search index
-   * for you.
+   * Every published page, rendered. The escape hatch behind
+   * {@link DocsRoute.searchIndex}, for anyone building their own artifact out
+   * of `extractSearchRecords`.
    */
   renderAll: () => Promise<Array<RenderedDoc<TFrontmatter>>>;
+  /**
+   * `GET` handler for `app/<basePath>/search-index.json/route.ts`, serving the
+   * MiniSearch index the dialog fetches.
+   *
+   * ```ts
+   * // app/docs/search-index.json/route.ts — the whole file
+   * import { docs } from '@/lib/docs';
+   *
+   * export const GET = docs.searchIndex;
+   * export const dynamic = 'force-static'; // a literal, see below
+   * ```
+   *
+   * **`dynamic = 'force-static'` is not optional and must be a literal**, for
+   * the same reason as {@link DocsRoute.dynamicParams}: route segment config is
+   * parsed out of the module before any of it runs. Without it Next marks the
+   * route `ƒ` (Dynamic) and re-renders your entire corpus on every request —
+   * from markdown that output tracing did not put in the deployment bundle, so
+   * on a serverless host it does not merely get slow, it throws, at the reader,
+   * inside the search dialog. The build prints no warning for this, so the
+   * handler detects it at runtime and throws with `code:
+   * 'search-index-dynamic'` instead of failing quietly.
+   *
+   * The index is built from the same `renderAll()` → `extractSearchRecords` →
+   * `buildSearchIndex` pipeline you could write by hand, with the `charset`-free
+   * `application/json` content type, a strong `ETag` and
+   * `cache-control: public, max-age=0, must-revalidate` — Next's default for a
+   * prerendered route is a year of `s-maxage` with no validator, which on a
+   * stable URL means a CDN serving last year's index until someone purges it.
+   */
+  searchIndex: () => Promise<Response>;
+  /**
+   * Default export for `app/<basePath>/layout.tsx` — the entire docs shell.
+   *
+   * ```tsx
+   * // app/docs/layout.tsx — the whole file
+   * import '@waveso/docs/styles.css';
+   * import { docs } from '@/lib/docs';
+   *
+   * export default docs.Layout;
+   * ```
+   *
+   * Or, with your own chrome in the header:
+   *
+   * ```tsx
+   * export default function DocsLayout({ children }: { children: ReactNode }) {
+   *   return (
+   *     <docs.Layout title={<Logo />} actions={<ThemeToggle />}>
+   *       {children}
+   *     </docs.Layout>
+   *   );
+   * }
+   * ```
+   *
+   * It owns the skip link, the header, the sidebar column, the mobile drawer
+   * and the grid, and it reads `source.nav()` and `searchIndexUrl` itself — so
+   * there is no nav to fetch and no URL to pass. It does **not** own the table
+   * of contents: a Next layout receives `{children, params}` and cannot know
+   * which page is rendering, so `docs.Page` emits the TOC as its second child
+   * and the grid places it.
+   *
+   * Your `layout.tsx` stays a Server Component. The two pieces that need a
+   * client — the nav's `usePathname`, the search dialog — carry their own
+   * `'use client'` boundaries inside the package.
+   *
+   * Next passes `{ children, params }`; the extra `params` is ignored, which is
+   * why `export default docs.Layout` type-checks as a layout.
+   */
+  Layout: (props: DocsLayoutProps) => Promise<ReactNode>;
+  /**
+   * `${basePath}/search-index.json` — hand it to `DocsSearch`'s `indexUrl`.
+   *
+   * Derived from the route's own `basePath`, so it is right when the docs are
+   * mounted at `/`, at `/docs`, or under a nested prefix. It is *not* prefixed
+   * with Next's `basePath` config, which Next applies to `<Link>` and to
+   * navigation but never to a client `fetch()` — on a site setting that, prefix
+   * it yourself.
+   */
+  searchIndexUrl: string;
 }
 /**
  * Create the route handlers for a documentation tree.
@@ -214,16 +349,6 @@ interface DocsSitemapOptions<TFrontmatter extends DocFrontmatter = DocFrontmatte
    * noise. Wire this to your git history if the dates are load-bearing.
    */
   lastModified?: (file: DocFile<TFrontmatter>) => Date | undefined | Promise<Date | undefined>;
-  /**
-   * Re-read the content directory before building the sitemap.
-   *
-   * Defaults to `true` outside `NODE_ENV=production`, matching
-   * {@link DocsRouteOptions.rescanPerRequest}. `createDocsSource` memoises by
-   * config, so without this the first scan of the process is the only one —
-   * and `app/sitemap.ts` in `next dev` would keep serving the page set as it
-   * stood when the server booted.
-   */
-  rescanPerRequest?: boolean | undefined;
 }
 /**
  * Sitemap entries for every published page, for `app/sitemap.ts`.
@@ -275,4 +400,4 @@ interface DocsRedirect {
  */
 declare function createDocsRedirects(config: DocsConfig): Promise<DocsRedirect[]>;
 //#endregion
-export { type DocsLang, DocsPageMetadata, DocsPageProps, DocsRedirect, DocsRoute, DocsRouteOptions, DocsSitemapEntry, DocsSitemapOptions, type DocsTheme, type DocsThemes, createDocsRedirects, createDocsRoute, createDocsSitemap };
+export { type DocsLang, DocsLayoutProps, DocsPageMetadata, DocsPageProps, DocsRedirect, DocsRoute, DocsRouteOptions, DocsSitemapEntry, DocsSitemapOptions, type DocsTheme, type DocsThemes, createDocsRedirects, createDocsRoute, createDocsSitemap };

package/dist/next.js CHANGED Viewed

@@ -1,12 +1,17 @@
 import { docsError } from "./docs-error.js";
+import { DOCS_CONTENT_ID } from "./docs-content-id.js";
 import { mapPooled } from "./map-pooled.js";
 import { createMarkdownComponents } from "./react/markdown-components.js";
 import { DocContent } from "./react/doc-content.js";
-import "./react/skip-link.js";
+import { DocsToc } from "./react/toc.js";
+import { wrapNextLink } from "./react/next-link.js";
 import { createDocsRenderer } from "./render.js";
-import { createDocsSource, resolveDocsConfig, toAliasRoute } from "./source.js";
+import { toAliasRoute } from "./route-path.js";
+import { createDocsSource, resolveDocsConfig } from "./source.js";
+import { sitemapLimitWarning } from "./sitemap-limit.js";
 import { stat } from "node:fs/promises";
-import { cache, createElement } from "react";
+import { createHash } from "node:crypto";
+import { Fragment, cache, createElement } from "react";
 //#region src/next.ts
 /**
 * The Next.js App Router adapter.
@@ -61,8 +66,6 @@ import { cache, createElement } from "react";
 * worth of trees and network calls in flight simultaneously.
 */
 const RENDER_CONCURRENCY = 16;
-/** Google's per-sitemap URL cap. */
-const SITEMAP_URL_LIMIT = 5e4;
 function isRecord(value) {
 	return typeof value === "object" && value !== null;
 }
@@ -110,23 +113,6 @@ async function loadNotFound() {
 	return value;
 }
 /**
-* Adapt `next/link` to {@link DocsLinkProps}.
-*
-* `next/link` widens `href` to `string | UrlObject` and `prefetch` to
-* `boolean | null`; the React layer promises neither, because it must also run
-* with a plain `<a>`. One wrapper keeps that mismatch in a single
-* place instead of at every call site.
-*/
-function wrapNextLink(NextLink) {
-	return function DocsNextLink({ href, prefetch, children, ...rest }) {
-		return createElement(NextLink, {
-			...rest,
-			href,
-			...prefetch === void 0 ? {} : { prefetch }
-		}, children);
-	};
-}
-/**
 * Adapt `next/image` to {@link DocsImageProps}.
 *
 * Every prop is named rather than spread. `next/image` types `width`/`height`
@@ -183,8 +169,7 @@ function createDocsRoute(options) {
 	const config = resolveDocsConfig(options);
 	const source = createDocsSource(options);
 	const siteUrl = normalizeSiteUrl(options.siteUrl);
-	const contentId = options.contentId ?? "docs-content";
-	const rescanPerRequest = options.rescanPerRequest ?? process.env.NODE_ENV !== "production";
+	const rescanPerRequest = process.env.NODE_ENV !== "production";
 	let renderer = null;
 	const knownRoutes = /* @__PURE__ */ new Set();
 	const draftRoutes = /* @__PURE__ */ new Set();
@@ -248,6 +233,8 @@ function createDocsRoute(options) {
 		...options.themes === void 0 ? {} : { themes: options.themes },
 		...options.excludeLangs === void 0 ? {} : { excludeLangs: options.excludeLangs },
 		...options.titleHeading === void 0 ? {} : { titleHeading: options.titleHeading },
+		...options.remarkPlugins === void 0 ? {} : { remarkPlugins: options.remarkPlugins },
+		...options.rehypePlugins === void 0 ? {} : { rehypePlugins: options.rehypePlugins },
 		...options.linkResolver === void 0 ? {} : { linkResolver: options.linkResolver },
 		...options.imageResolver === void 0 ? {} : { imageResolver: options.imageResolver }
 	});
@@ -303,28 +290,56 @@ function createDocsRoute(options) {
 		const renderer = loadRenderer();
 		return mapPooled(files, RENDER_CONCURRENCY, (file) => renderer.render(file));
 	};
+	const searchIndexUrl = `${config.basePath}/search-index.json`;
+	/**
+	* Fail loudly when the search-index route was not frozen at build time.
+	*
+	* The signal is `NEXT_PHASE`, which Next sets to `phase-production-build`
+	* while prerendering — verified in both output modes, and `undefined` under
+	* `next start`. It is internal and undocumented, which is why the CI smoke
+	* build asserts the prerendered body exists: if this ever changes meaning it
+	* fails there, in this repository, rather than in a consumer's deploy.
+	*
+	* The alternative was a `console.error`, and it is not one. A warning in a
+	* serverless log is unread, and the observable symptom — a search dialog
+	* stuck on "could not load the index" — arrives days later with nothing
+	* connecting it to a missing line in a route file.
+	*/
+	const assertPrerendered = () => {
+		if (process.env.NODE_ENV === "production" && process.env.NEXT_PHASE !== "phase-production-build") throw docsError("search-index-dynamic", `the search index was requested at runtime instead of being built into your deployment. Add \`export const dynamic = 'force-static'\` to app${searchIndexUrl}/route.ts — it has to be a literal, like \`dynamicParams\`. Without it Next re-renders every page of your corpus per request, from markdown that is not in the deployment bundle. (Building the index somewhere else on purpose? Use \`docs.renderAll()\` with \`extractSearchRecords\` and \`buildSearchIndex\` from \`@waveso/docs/search-index\` instead of calling this handler.)`);
+	};
+	const searchIndex = async () => {
+		assertPrerendered();
+		const { buildSearchIndex, extractSearchRecords } = await import("./search-index.js");
+		const json = buildSearchIndex((await renderAll()).flatMap((doc) => extractSearchRecords(doc)), options.miniSearchOptions ?? {});
+		return new Response(json, { headers: {
+			"content-type": "application/json",
+			"cache-control": "public, max-age=0, must-revalidate",
+			etag: `"${createHash("sha1").update(json).digest("hex")}"`
+		} });
+	};
 	async function renderRoute(segments) {
 		const doc = await getPage(segments);
 		if (doc === void 0) return (await loadNotFound())();
 		const components = await loadNextComponents();
-		return createElement("article", {
-			className: "wave-docs-prose",
-			...contentId === false ? {} : {
-				id: contentId,
-				tabIndex: -1
-			}
+		return createElement(Fragment, null, createElement("main", {
+			className: "wave-docs-layout__main",
+			id: DOCS_CONTENT_ID,
+			tabIndex: -1
 		}, createElement(DocContent, {
 			hast: doc.hast,
 			components: {
 				...components,
 				...options.components
 			}
-		}));
+		})), doc.toc.length === 0 ? null : createElement("aside", { className: "wave-docs-layout__toc" }, createElement(DocsToc, { entries: doc.toc })));
 	}
 	return {
 		source: requestScopedSource,
 		getPage,
 		renderAll,
+		searchIndex,
+		searchIndexUrl,
 		dynamicParams: false,
 		async Page({ params }) {
 			const { slug } = await params;
@@ -333,6 +348,22 @@ function createDocsRoute(options) {
 		async IndexPage() {
 			return renderRoute([]);
 		},
+		async Layout({ children, title, actions, search, labels }) {
+			const { DocsLayoutShell } = await import("./react/layout.js");
+			const searchProps = search === false ? false : {
+				...options.miniSearchOptions === void 0 ? {} : { miniSearchOptions: options.miniSearchOptions },
+				...search === true || search === void 0 ? {} : search
+			};
+			return createElement(DocsLayoutShell, {
+				children,
+				nav: await requestScopedSource.nav(),
+				searchIndexUrl,
+				search: searchProps,
+				...title === void 0 ? {} : { title },
+				...actions === void 0 ? {} : { actions },
+				...labels === void 0 ? {} : { labels }
+			});
+		},
 		async generateStaticParams() {
 			if (rescanPerRequest) invalidate();
 			return (await source.slugs()).filter((segments) => segments.length > 0).map((segments) => ({ slug: segments }));
@@ -378,9 +409,10 @@ function createDocsRoute(options) {
 async function createDocsSitemap(options) {
 	const siteUrl = requireSiteUrl(options.siteUrl);
 	const source = createDocsSource(options);
-	if (options.rescanPerRequest ?? process.env.NODE_ENV !== "production") source.invalidate();
+	if (process.env.NODE_ENV !== "production") source.invalidate();
 	const files = await source.all();
-	if (files.length > SITEMAP_URL_LIMIT) console.warn(`@waveso/docs: this sitemap has ${files.length} URLs, above Google's limit of ${SITEMAP_URL_LIMIT}. Split it with Next's \`generateSitemaps\` and slice the array this returns.`);
+	const oversized = sitemapLimitWarning(files.length);
+	if (oversized !== void 0) console.warn(oversized);
 	const readDate = options.lastModified ?? readMtime;
 	return Promise.all(files.map(async (file) => {
 		const lastModified = await readDate(file);

package/dist/plugins/rehype-capture-toc.js CHANGED Viewed

@@ -1,14 +1,35 @@
 import { isFootnotes, isTransparentContainer } from "../section-boundary.js";
 import { toString } from "hast-util-to-string";
 //#region src/plugins/rehype-capture-toc.ts
-/** `h2`–`h6`. `h1` is the page title and never appears in a TOC. */
-const HEADING = /^h([2-6])$/;
+/**
+* `h2` and `h3`. `h1` is the page title, and h4–h6 are too deep to navigate.
+*
+* Measured on a synthetic API page — 8 methods, 3 overloads each, 3
+* subsections apiece — capturing h2–h6 gave **104 entries and 6,797 bytes** of
+* flight payload against **32 entries and 2,321 bytes** capped at h3. A rail
+* with a hundred entries is not a table of contents; it is the page again, in
+* a narrower column.
+*
+* Stripe, Linear, Mintlify, Fumadocs and Docusaurus all cap at h2+h3 —
+* Docusaurus's defaults are literally 2 and 3.
+*
+* Nothing becomes unreachable by cutting here. `rehype-slug` and
+* `rehype-autolink-headings` still give every h4–h6 an id and a permalink, so
+* they are still linkable and still land in the search index, which opens
+* sections on its own walk. There is deliberately no `maxDepth` option: the
+* escape hatch is `rehypePlugins`, where a plugin writing its own
+* `file.data.toc` is about forty lines.
+*/
+const HEADING = /^h([23])$/;
 /**
 * Drop the permalink anchor `rehype-autolink-headings` appends.
 *
-* This plugin is ordered before that one, so in practice there is nothing to
-* drop — but the check costs nothing and the alternative, if the order ever
-* changes, is every TOC entry silently gaining a trailing `#`.
+* ⚠️ LOAD-BEARING NOW. This used to run *before* autolinking, so there was
+* nothing to drop and this was insurance against an order that might change.
+* The order changed: the capture is dead last, after Shiki and after the
+* consumer's own plugins, so every heading really does carry an appended
+* anchor by the time this walks it. Delete this and every TOC entry gains a
+* trailing `#`.
 */
 function isPermalink(child) {
 	if (child.type !== "element" || child.tagName !== "a") return false;

package/dist/plugins/rehype-code-frame.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+import { Plugin } from "unified";
+import { Root } from "hast";
+//#region src/plugins/rehype-code-frame.d.ts
+interface RehypeCodeFrameOptions {
+  /** Accessible name when a fence has no title. */
+  copyLabel?: string | undefined;
+}
+declare const rehypeCodeFrame: Plugin<[RehypeCodeFrameOptions?], Root>;
+//#endregion
+export { RehypeCodeFrameOptions, rehypeCodeFrame };

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

@@ -0,0 +1,88 @@
+import { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE } 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
+/** `language-ts` on the `<code>`, already folded to lower case by step 12. */
+const LANGUAGE_CLASS = /^language-(.+)$/;
+const rehypeCodeFrame = (options = {}) => {
+	const copyLabel = options.copyLabel ?? "Copy code";
+	return (tree, file) => {
+		const path = file.data.docLinkContext?.relativePath ?? file.path ?? "a document";
+		visit(tree, "element", (node, index, parent) => {
+			if (node.tagName !== "pre") return CONTINUE;
+			if (parent === void 0 || index === void 0) return CONTINUE;
+			const code = node.children[0];
+			if (code === void 0 || code.type !== "element") return CONTINUE;
+			if (code.tagName !== "code") return CONTINUE;
+			const meta = readMeta(code);
+			const { title } = parseCodeMeta(meta, path);
+			const language = readLanguage(code);
+			const children = [];
+			if (title !== void 0) children.push({
+				type: "element",
+				tagName: "figcaption",
+				properties: { className: ["wave-docs-code__title"] },
+				children: [{
+					type: "text",
+					value: title
+				}]
+			});
+			children.push(copyButton(title === void 0 ? copyLabel : `${copyLabel} from ${title}`), node);
+			parent.children[index] = {
+				type: "element",
+				tagName: "figure",
+				properties: {
+					className: ["wave-docs-code"],
+					[CODE_FRAME_ATTRIBUTE]: "",
+					...language === void 0 ? {} : { "data-lang": language }
+				},
+				children
+			};
+			return SKIP;
+		});
+	};
+};
+/**
+* A real `<button type="button">`, so Enter and Space work with no key
+* handling of ours and the control is announced as a button.
+*
+* It sits before the `<pre>`, which is what makes the tab order read "copy
+* this block" → "the scrollable code region" rather than the reverse.
+*/
+function copyButton(label) {
+	return {
+		type: "element",
+		tagName: "button",
+		properties: {
+			type: "button",
+			className: ["wave-docs-code__copy"],
+			[CODE_COPY_ATTRIBUTE]: "",
+			"aria-label": label
+		},
+		children: [{
+			type: "element",
+			tagName: "span",
+			properties: { "aria-hidden": "true" },
+			children: [{
+				type: "text",
+				value: "⧉"
+			}]
+		}]
+	};
+}
+/** `code.data.meta` — read, never written. */
+function readMeta(code) {
+	const meta = code.data?.meta;
+	return typeof meta === "string" ? meta : void 0;
+}
+function readLanguage(code) {
+	const classNames = code.properties.className;
+	if (!Array.isArray(classNames)) return void 0;
+	for (const name of classNames) {
+		if (typeof name !== "string") continue;
+		const found = LANGUAGE_CLASS.exec(name)?.[1];
+		if (found !== void 0) return found;
+	}
+}
+//#endregion
+export { rehypeCodeFrame };

package/dist/plugins/rehype-code-language.js CHANGED Viewed

@@ -40,7 +40,13 @@ const rehypeNormalizeCodeLanguage = (options = {}) => {
 const rehypeRestoreExcludedCode = () => {
 	return (tree) => {
 		visit(tree, "element", (node) => {
-			if (node.tagName === "wave-docs-excluded-pre") node.tagName = "pre";
+			if (node.tagName === "wave-docs-excluded-pre") {
+				node.tagName = "pre";
+				node.properties = {
+					...node.properties,
+					tabIndex: 0
+				};
+			}
 		});
 	};
 };

package/dist/react/code-runtime.d.ts ADDED Viewed

@@ -0,0 +1,14 @@
+import { ReactNode } from "react";
+//#region src/react/code-runtime.d.ts
+/**
+ * Mount the copy runtime. Renders nothing.
+ *
+ * Every hook of state lives in the DOM rather than in React: the button's
+ * copied state is a `data-copied` attribute the stylesheet reads, and the
+ * announcement is a live region. React owns none of these nodes, so nothing
+ * re-renders and there is no state to get out of step with a page that was
+ * server-rendered.
+ */
+declare function DocsCodeRuntime(): ReactNode;
+//#endregion
+export { DocsCodeRuntime };