@waveso/docs 0.1.0

package/dist/react/sidebar.js

@@ -0,0 +1,196 @@
+"use client";
+import { useId, useRef, useState } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/sidebar.tsx
+/** Trailing slashes are a routing detail, not a difference in identity. */
+function normalizeHref(href) {
+	return href.length > 1 ? href.replace(/\/+$/, "") : href;
+}
+function isActiveHref(pathname, href) {
+	return normalizeHref(pathname) === normalizeHref(href);
+}
+/** Whether the active page lives anywhere under this node. */
+function containsActive(node, pathname) {
+	switch (node.type) {
+		case "page": return isActiveHref(pathname, node.href);
+		case "group": return node.href !== void 0 && isActiveHref(pathname, node.href) || node.children.some((child) => containsActive(child, pathname));
+		case "link": return !node.external && isActiveHref(pathname, node.href);
+		default: return false;
+	}
+}
+/**
+* The docs navigation tree.
+*
+* Prefetch is off by default on the injected link. A full-tree sidebar on a
+* few hundred pages otherwise asks Next to prefetch every route in it —
+* ~1.8 KB brotli each, all of it wasted on the routes nobody clicks.
+*/
+function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
+	const baseId = useId();
+	const [toggled, setToggled] = useState({});
+	const lastPathname = useRef(pathname);
+	if (lastPathname.current !== pathname) {
+		lastPathname.current = pathname;
+		setToggled({});
+	}
+	const handleToggle = (key, isOpen) => {
+		setToggled((previous) => ({
+			...previous,
+			[key]: isOpen
+		}));
+	};
+	return /* @__PURE__ */ jsx("nav", {
+		"aria-label": label,
+		className: ["wave-docs-sidebar", className].filter(Boolean).join(" "),
+		children: /* @__PURE__ */ jsx(NavList, {
+			nodes: nav,
+			depth: 0,
+			keyPrefix: baseId,
+			pathname,
+			Link,
+			toggled,
+			onToggle: handleToggle
+		})
+	});
+}
+function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, id }) {
+	return /* @__PURE__ */ jsx("ul", {
+		id,
+		className: "wave-docs-sidebar__list",
+		"data-depth": depth,
+		children: nodes.map((node, index) => {
+			const key = `${keyPrefix}-${index}`;
+			switch (node.type) {
+				case "separator": return /* @__PURE__ */ jsx("li", {
+					className: "wave-docs-sidebar__separator-item",
+					children: /* @__PURE__ */ jsx("span", {
+						className: "wave-docs-sidebar__separator",
+						children: node.title
+					})
+				}, key);
+				case "link": return /* @__PURE__ */ jsx("li", {
+					className: "wave-docs-sidebar__item",
+					children: /* @__PURE__ */ jsx(NavLink, {
+						href: node.href,
+						isExternal: node.external,
+						isActive: !node.external && isActiveHref(pathname, node.href),
+						Link,
+						children: node.title
+					})
+				}, key);
+				case "page": return /* @__PURE__ */ jsx("li", {
+					className: "wave-docs-sidebar__item",
+					children: /* @__PURE__ */ jsx(NavLink, {
+						href: node.href,
+						isExternal: false,
+						isActive: isActiveHref(pathname, node.href),
+						Link,
+						children: node.title
+					})
+				}, key);
+				case "group": return /* @__PURE__ */ jsx(NavGroup, {
+					node,
+					itemKey: key,
+					depth,
+					pathname,
+					Link,
+					toggled,
+					onToggle
+				}, key);
+				default: return null;
+			}
+		})
+	});
+}
+function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle }) {
+	const listId = `${itemKey}-list`;
+	const hasActive = containsActive(node, pathname);
+	const isOpen = toggled[itemKey] ?? hasActive;
+	const isGroupActive = node.href !== void 0 && isActiveHref(pathname, node.href);
+	return /* @__PURE__ */ jsxs("li", {
+		className: "wave-docs-sidebar__item",
+		"data-open": isOpen ? "" : void 0,
+		children: [/* @__PURE__ */ jsx("div", {
+			className: "wave-docs-sidebar__group-header",
+			children: node.href === void 0 ? /* @__PURE__ */ jsxs("button", {
+				type: "button",
+				className: "wave-docs-sidebar__group-button",
+				"aria-expanded": isOpen,
+				"aria-controls": isOpen ? listId : void 0,
+				onClick: () => onToggle(itemKey, !isOpen),
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "wave-docs-sidebar__group-title",
+					children: node.title
+				}), /* @__PURE__ */ jsx(Chevron, { isOpen })]
+			}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(NavLink, {
+				href: node.href,
+				isExternal: false,
+				isActive: isGroupActive,
+				Link,
+				children: node.title
+			}), /* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "wave-docs-sidebar__group-toggle",
+				"aria-expanded": isOpen,
+				"aria-controls": isOpen ? listId : void 0,
+				"aria-label": `${isOpen ? "Collapse" : "Expand"} ${node.title}`,
+				onClick: () => onToggle(itemKey, !isOpen),
+				children: /* @__PURE__ */ jsx(Chevron, { isOpen })
+			})] })
+		}), isOpen ? /* @__PURE__ */ jsx(NavList, {
+			id: listId,
+			nodes: node.children,
+			depth: depth + 1,
+			keyPrefix: itemKey,
+			pathname,
+			Link,
+			toggled,
+			onToggle
+		}) : null]
+	});
+}
+function NavLink({ href, isExternal, isActive, Link, children }) {
+	const className = "wave-docs-sidebar__link";
+	if (isExternal) return /* @__PURE__ */ jsxs("a", {
+		className,
+		href,
+		target: "_blank",
+		rel: "noopener noreferrer",
+		children: [children, /* @__PURE__ */ jsx("span", {
+			className: "wave-docs-sr-only",
+			children: " (opens in a new tab)"
+		})]
+	});
+	if (Link === void 0) return /* @__PURE__ */ jsx("a", {
+		className,
+		href,
+		"aria-current": isActive ? "page" : void 0,
+		children
+	});
+	return /* @__PURE__ */ jsx(Link, {
+		className,
+		href,
+		prefetch: false,
+		"aria-current": isActive ? "page" : void 0,
+		children
+	});
+}
+function Chevron({ isOpen }) {
+	return /* @__PURE__ */ jsx("svg", {
+		className: "wave-docs-sidebar__chevron",
+		"data-open": isOpen ? "" : void 0,
+		viewBox: "0 0 24 24",
+		width: "16",
+		height: "16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		focusable: "false",
+		children: /* @__PURE__ */ jsx("path", { d: "m9 18 6-6-6-6" })
+	});
+}
+//#endregion
+export { DocsSidebar };

package/dist/react/skip-link.d.ts

@@ -0,0 +1,37 @@
+import { ReactNode } from "react";
+//#region src/react/skip-link.d.ts
+/**
+ * The `id` this link targets, and the one `createDocsRoute` puts on its
+ * `<article>`.
+ *
+ * One constant for both halves: the two files spelled the string independently,
+ * and a skip link pointing at an id nothing carries scrolls nowhere and focuses
+ * nothing — a failure with no symptom until a keyboard user hits it.
+ */
+declare const DOCS_CONTENT_ID = "docs-content";
+interface SkipLinkProps {
+  /** Fragment id of the main content region. */
+  href?: string | undefined;
+  className?: string | undefined;
+  children?: ReactNode;
+}
+/**
+ * Skip-to-content link: invisible until focused, first in the tab order.
+ *
+ * A docs sidebar can be a hundred links deep, and without this every keyboard
+ * and switch user tabs through all of them on every page to reach the prose.
+ * It is three lines of markup and most docs sites still do not have it.
+ *
+ * Put it first inside `<body>`, and give the target `tabIndex={-1}` — browsers
+ * move the *scroll* position on a fragment link but not always the focus, so
+ * an unfocusable target leaves focus stranded at the top of the document.
+ *
+ * @example
+ * ```tsx
+ * <SkipLink href="#docs-content" />
+ * <main id="docs-content" tabIndex={-1}>{children}</main>
+ * ```
+ */
+declare function SkipLink({ href, className, children }: SkipLinkProps): ReactNode;
+//#endregion
+export { DOCS_CONTENT_ID, SkipLink, SkipLinkProps };

package/dist/react/skip-link.js

@@ -0,0 +1,37 @@
+import { jsx } from "react/jsx-runtime";
+//#region src/react/skip-link.tsx
+/**
+* The `id` this link targets, and the one `createDocsRoute` puts on its
+* `<article>`.
+*
+* One constant for both halves: the two files spelled the string independently,
+* and a skip link pointing at an id nothing carries scrolls nowhere and focuses
+* nothing — a failure with no symptom until a keyboard user hits it.
+*/
+const DOCS_CONTENT_ID = "docs-content";
+/**
+* Skip-to-content link: invisible until focused, first in the tab order.
+*
+* A docs sidebar can be a hundred links deep, and without this every keyboard
+* and switch user tabs through all of them on every page to reach the prose.
+* It is three lines of markup and most docs sites still do not have it.
+*
+* Put it first inside `<body>`, and give the target `tabIndex={-1}` — browsers
+* move the *scroll* position on a fragment link but not always the focus, so
+* an unfocusable target leaves focus stranded at the top of the document.
+*
+* @example
+* ```tsx
+* <SkipLink href="#docs-content" />
+* <main id="docs-content" tabIndex={-1}>{children}</main>
+* ```
+*/
+function SkipLink({ href = `#${DOCS_CONTENT_ID}`, className, children = "Skip to content" }) {
+	return /* @__PURE__ */ jsx("a", {
+		href,
+		className: ["wave-docs-skip-link", className].filter(Boolean).join(" "),
+		children
+	});
+}
+//#endregion
+export { DOCS_CONTENT_ID, SkipLink };

package/dist/react/toc.d.ts

@@ -0,0 +1,35 @@
+import { TocEntry } from "../types.js";
+import { ReactNode } from "react";
+//#region src/react/toc.d.ts
+interface DocsTocProps {
+  /** Headings from `@waveso/docs/render`, already nested by depth. */
+  entries: TocEntry[];
+  /** Accessible name for the landmark. */
+  label?: string | undefined;
+  /**
+   * Region of the viewport that counts as "current", as an
+   * `IntersectionObserver` root margin. The default reserves 80px for a sticky
+   * header and ignores the bottom 60% of the screen, so the active entry
+   * tracks what you are reading rather than what has scrolled into view.
+   *
+   * Only `px` and `%` are legal here — `IntersectionObserver` throws on any
+   * other unit, `rem` included.
+   */
+  rootMargin?: string | undefined;
+  className?: string | undefined;
+}
+/**
+ * On-this-page navigation with scrollspy.
+ *
+ * The ids come from the same `rehype-slug` pass that annotated the document, so
+ * `getElementById` matches by construction — no second slugging pass to drift
+ * out of sync on duplicate headings.
+ *
+ * Scrolling itself is left to the browser: the links are real anchors, and
+ * smooth scrolling is applied in CSS under
+ * `@media (prefers-reduced-motion: no-preference)`. Doing it in JavaScript
+ * means reimplementing that check, and getting it wrong makes people ill.
+ */
+declare function DocsToc({ entries, label, rootMargin, className }: DocsTocProps): ReactNode;
+//#endregion
+export { DocsToc, DocsTocProps };

package/dist/react/toc.js

@@ -0,0 +1,87 @@
+"use client";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/toc.tsx
+const DEFAULT_ROOT_MARGIN = "-80px 0px -60% 0px";
+function flattenTocIds(entries) {
+	const ids = [];
+	const walk = (list) => {
+		for (const entry of list) {
+			ids.push(entry.id);
+			walk(entry.children);
+		}
+	};
+	walk(entries);
+	return ids;
+}
+/**
+* On-this-page navigation with scrollspy.
+*
+* The ids come from the same `rehype-slug` pass that annotated the document, so
+* `getElementById` matches by construction — no second slugging pass to drift
+* out of sync on duplicate headings.
+*
+* Scrolling itself is left to the browser: the links are real anchors, and
+* smooth scrolling is applied in CSS under
+* `@media (prefers-reduced-motion: no-preference)`. Doing it in JavaScript
+* means reimplementing that check, and getting it wrong makes people ill.
+*/
+function DocsToc({ entries, label = "On this page", rootMargin = DEFAULT_ROOT_MARGIN, className }) {
+	const ids = useMemo(() => flattenTocIds(entries), [entries]);
+	const [activeId, setActiveId] = useState(void 0);
+	const lastIds = useRef(ids);
+	if (lastIds.current !== ids) {
+		lastIds.current = ids;
+		setActiveId(void 0);
+	}
+	useEffect(() => {
+		if (ids.length === 0 || typeof IntersectionObserver === "undefined") return;
+		const visible = /* @__PURE__ */ new Set();
+		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);
+		}, {
+			rootMargin,
+			threshold: 0
+		});
+		for (const id of ids) {
+			const element = document.getElementById(id);
+			if (element !== null) observer.observe(element);
+		}
+		return () => observer.disconnect();
+	}, [ids, rootMargin]);
+	if (entries.length === 0) return null;
+	return /* @__PURE__ */ jsx("nav", {
+		"aria-label": label,
+		className: ["wave-docs-toc", className].filter(Boolean).join(" "),
+		children: /* @__PURE__ */ jsx(TocList, {
+			entries,
+			activeId,
+			onSelect: setActiveId
+		})
+	});
+}
+function TocList({ entries, activeId, onSelect }) {
+	return /* @__PURE__ */ jsx("ul", {
+		className: "wave-docs-toc__list",
+		children: entries.map((entry) => /* @__PURE__ */ jsxs("li", {
+			className: "wave-docs-toc__item",
+			children: [/* @__PURE__ */ jsx("a", {
+				className: "wave-docs-toc__link",
+				href: `#${entry.id}`,
+				"data-depth": entry.depth,
+				"aria-current": entry.id === activeId ? "location" : void 0,
+				onClick: () => onSelect(entry.id),
+				children: entry.text
+			}), entry.children.length > 0 ? /* @__PURE__ */ jsx(TocList, {
+				entries: entry.children,
+				activeId,
+				onSelect
+			}) : null]
+		}, entry.id))
+	});
+}
+//#endregion
+export { DocsToc };

package/dist/react/youtube.d.ts

@@ -0,0 +1,27 @@
+import { ReactNode } from "react";
+//#region src/react/youtube.d.ts
+interface YouTubeProps {
+  /** The 11-character video id, e.g. `dQw4w9WgXcQ`. */
+  id?: string | undefined;
+  /**
+   * Accessible name for the player. Markdown carries no video title, so the
+   * fallback is generic — pass a real one where you have it.
+   */
+  title?: string | undefined;
+  className?: string | undefined;
+}
+/**
+ * Click-to-load YouTube embed.
+ *
+ * An eager `<iframe>` costs ~137 KB of embed document plus ~580 KB gzipped of
+ * player JavaScript, on every page view, whether or not anyone presses play.
+ * A facade costs one ~15 KB JPEG and loads the rest on demand. On a docs page
+ * with three videos that is the difference between a good Lighthouse score and
+ * a bad one.
+ *
+ * `hqdefault.jpg` rather than `maxresdefault.jpg` deliberately: maxres does not
+ * exist for uploads below 1280×720 and 404s to a broken image with no fallback.
+ */
+declare function YouTube({ id, title, className }: YouTubeProps): ReactNode;
+//#endregion
+export { YouTube, YouTubeProps };

package/dist/react/youtube.js

@@ -0,0 +1,75 @@
+"use client";
+import { useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/react/youtube.tsx
+const DEFAULT_TITLE = "YouTube video player";
+/**
+* Click-to-load YouTube embed.
+*
+* An eager `<iframe>` costs ~137 KB of embed document plus ~580 KB gzipped of
+* player JavaScript, on every page view, whether or not anyone presses play.
+* A facade costs one ~15 KB JPEG and loads the rest on demand. On a docs page
+* with three videos that is the difference between a good Lighthouse score and
+* a bad one.
+*
+* `hqdefault.jpg` rather than `maxresdefault.jpg` deliberately: maxres does not
+* exist for uploads below 1280×720 and 404s to a broken image with no fallback.
+*/
+function YouTube({ id, title, className }) {
+	const [isPlaying, setIsPlaying] = useState(false);
+	if (!id) return null;
+	const safeId = encodeURIComponent(id);
+	const label = title?.trim() || DEFAULT_TITLE;
+	const rootClassName = ["wave-docs-youtube", className].filter(Boolean).join(" ");
+	if (isPlaying) return /* @__PURE__ */ jsx("div", {
+		className: rootClassName,
+		children: /* @__PURE__ */ jsx("iframe", {
+			className: "wave-docs-youtube__frame",
+			src: `https://www.youtube-nocookie.com/embed/${safeId}?autoplay=1&rel=0`,
+			title: label,
+			loading: "lazy",
+			allow: "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share",
+			allowFullScreen: true,
+			ref: (node) => {
+				node?.focus();
+			}
+		})
+	});
+	return /* @__PURE__ */ jsx("div", {
+		className: rootClassName,
+		children: /* @__PURE__ */ jsxs("button", {
+			type: "button",
+			className: "wave-docs-youtube__facade",
+			onClick: () => setIsPlaying(true),
+			"aria-label": `Play video: ${label}`,
+			children: [/* @__PURE__ */ jsx("img", {
+				className: "wave-docs-youtube__thumbnail",
+				src: `https://i.ytimg.com/vi/${safeId}/hqdefault.jpg`,
+				alt: "",
+				width: 480,
+				height: 360,
+				loading: "lazy",
+				decoding: "async"
+			}), /* @__PURE__ */ jsx("span", {
+				className: "wave-docs-youtube__play",
+				"aria-hidden": "true",
+				children: /* @__PURE__ */ jsxs("svg", {
+					viewBox: "0 0 68 48",
+					width: "68",
+					height: "48",
+					"aria-hidden": "true",
+					focusable: "false",
+					children: [/* @__PURE__ */ jsx("path", {
+						className: "wave-docs-youtube__play-bg",
+						d: "M66.52 7.74a8 8 0 0 0-5.65-5.66C56.1.99 34 .99 34 .99s-22.1 0-26.87 1.09a8 8 0 0 0-5.65 5.66C.39 12.51.39 24 .39 24s0 11.49 1.09 16.26a8 8 0 0 0 5.65 5.66C11.9 47 34 47 34 47s22.1 0 26.87-1.08a8 8 0 0 0 5.65-5.66C67.61 35.49 67.61 24 67.61 24s0-11.49-1.09-16.26"
+					}), /* @__PURE__ */ jsx("path", {
+						className: "wave-docs-youtube__play-arrow",
+						d: "M27 34V14l17 10z"
+					})]
+				})
+			})]
+		})
+	});
+}
+//#endregion
+export { YouTube };

package/dist/render.d.ts

@@ -0,0 +1,72 @@
+import { DocFile, DocFrontmatter, ImageResolver, LinkResolver, RenderedDoc, ResolvedDocsConfig } from "./types.js";
+import { DocsHighlighter, DocsLang, DocsThemes } from "./highlighter.js";
+//#region src/render.d.ts
+/**
+ * The parts of {@link ResolvedDocsConfig} rendering actually depends on.
+ *
+ * Declared as a `Pick` so a full resolved config passes straight through: the
+ * host resolves configuration once, with `resolveDocsConfig`, and hands the
+ * same object to the source walk and to the renderer. Nothing here re-applies
+ * defaults, so the two cannot drift.
+ */
+type DocsRendererConfig = Pick<ResolvedDocsConfig, 'basePath' | 'assertLinks'>;
+interface DocsRendererOptions {
+  config: DocsRendererConfig;
+  /**
+   * Reuse an existing highlighter — the escape hatch for grammars and themes
+   * outside the curated set. Defaults to {@link createDocsHighlighter}.
+   */
+  highlighter?: DocsHighlighter | Promise<DocsHighlighter>;
+  /** Grammars to load, when building the default highlighter. */
+  langs?: readonly DocsLang[];
+  /** Theme pair. Defaults to {@link DEFAULT_DOCS_THEMES}. */
+  themes?: DocsThemes;
+  /**
+   * Prepend an `<h1>` built from `frontmatter.title` when the markdown body
+   * has none. Defaults to `true`.
+   *
+   * Turn it off only if your layout renders the page title itself: a document
+   * with no `h1` fails `page-has-heading-one` and leaves the heading outline
+   * starting at `h2`, and markdown that repeats the frontmatter title as `# `
+   * is a duplication authors forget to keep in step.
+   */
+  titleHeading?: boolean;
+  /** Replaces the built-in markdown-link resolution. */
+  linkResolver?: LinkResolver;
+  /**
+   * Resolves image `src` to a public URL and intrinsic dimensions, so
+   * `next/image` can render without `fill`. Images are left untouched when
+   * omitted, or when the resolver returns `undefined`.
+   */
+  imageResolver?: ImageResolver;
+  /**
+   * Every route the site publishes, used by `assertLinks`. Read at render
+   * time, so a host may pass a set it populates during the source walk.
+   *
+   * Without it only unresolvable links can be caught; with it, links to pages
+   * that simply do not exist are caught too.
+   */
+  knownRoutes?: ReadonlySet<string>;
+}
+/**
+ * Renders {@link DocFile}s. Build one per process and reuse it.
+ *
+ * The frontmatter type parameter sits on `render`, not on the interface: the
+ * renderer reads only `frontmatter.title` and passes the rest through, so one
+ * renderer serves files parsed by any schema — which is what lets a host build
+ * the processor and the highlighter once. A renderer-level parameter would
+ * force a second highlighter per frontmatter shape and buy nothing.
+ */
+interface DocsRenderer {
+  render<TFrontmatter extends DocFrontmatter>(file: DocFile<TFrontmatter>): Promise<RenderedDoc<TFrontmatter>>;
+}
+/**
+ * Create a renderer.
+ *
+ * The processor and the highlighter are built once, eagerly, and shared by
+ * every call to `render`. Constructing them per file is the difference between
+ * a docs build that takes a second and one that takes a minute.
+ */
+declare function createDocsRenderer(options: DocsRendererOptions): DocsRenderer;
+//#endregion
+export { DocsRenderer, DocsRendererConfig, DocsRendererOptions, createDocsRenderer };