@waveso/docs 0.3.0 → 0.5.0

package/dist/react/shell-labels.js

@@ -1,11 +1,42 @@
 //#region src/react/shell-labels.ts
 /**
-* The defaults, in one place.
+* Every key of {@link DocsLabels}, for the test that proves each one is wired.
 *
-* A `Required<DocsLabels>` rather than four `=` defaults spread across three
-* components: the previous arrangement is how `DocsSidebar` came to default its
-* landmark to `'Docs'` while `DocsNav` defaulted the same landmark to
-* `'Documentation'` — two names for one region, depending on the viewport.
+* A list rather than a type-level trick because the assertion has to run: the
+* failure being guarded against is a key that is declared, documented and never
+* read, which type-checks perfectly.
+*/
+const DOCS_LABEL_KEYS = [
+	"nav",
+	"openNav",
+	"closeNav",
+	"skipToContent",
+	"expandGroup",
+	"collapseGroup",
+	"toc",
+	"backToTop",
+	"externalLink",
+	"table",
+	"calloutNote",
+	"calloutTip",
+	"calloutImportant",
+	"calloutWarning",
+	"calloutCaution",
+	"youtubeTitle",
+	"youtubePlay",
+	"youtubeHide",
+	"copyCode",
+	"copyCodeFrom",
+	"copied",
+	"copyFailed"
+];
+/**
+* Defaults for the shell's four, in one place.
+*
+* A `Required<…>` rather than four `=` defaults spread across three components:
+* the previous arrangement is how `DocsSidebar` came to default its landmark to
+* `'Docs'` while `DocsNav` defaulted the same landmark to `'Documentation'` —
+* two names for one region, depending on the viewport.
 */
 const DEFAULT_DOCS_LABELS = {
 	nav: "Documentation",
@@ -23,5 +54,15 @@ function resolveLabels(labels) {
 		skipToContent: labels.skipToContent ?? DEFAULT_DOCS_LABELS.skipToContent
 	};
 }
+/**
+* `template` with `{title}` replaced.
+*
+* A placeholder, because these strings cross a Server → Client boundary where a
+* function cannot go — and because a translator needs to move the name within
+* the sentence, which string concatenation does not allow.
+*/
+function fillTitle(template, title) {
+	return template.replace("{title}", title);
+}
 //#endregion
-export { DEFAULT_DOCS_LABELS, resolveLabels };
+export { DEFAULT_DOCS_LABELS, DOCS_LABEL_KEYS, fillTitle, resolveLabels };

package/dist/react/sidebar.d.ts

@@ -15,6 +15,23 @@ interface DocsSidebarProps {
   Link?: DocsLinkComponent | undefined;
   /** Accessible name for the landmark. Distinguish multiple navs on a page. */
   label?: string | undefined;
+  /**
+   * A collapsed group's toggle. Default `'Expand {title}'`.
+   *
+   * `{title}` is replaced with the group's own name. A placeholder rather than
+   * a function, because `docs.Layout` sets this from a Server Component and a
+   * function cannot cross that boundary — and because a translator has to be
+   * able to move the name within the sentence.
+   */
+  expandGroup?: string | undefined;
+  /** The same toggle when open. Default `'Collapse {title}'`. */
+  collapseGroup?: string | undefined;
+  /**
+   * Screen-reader suffix on an external link. Default `'(opens in a new tab)'`.
+   *
+   * The separating space is markup, so this is the sentence and nothing else.
+   */
+  externalLink?: string | undefined;
   className?: string | undefined;
 }
 /**
@@ -59,6 +76,6 @@ interface DocsSidebarProps {
  * nothing prefetches locally whatever this says. Do not "fix" it back because
  * the network tab looks the same.
  */
-declare function DocsSidebar({ nav, pathname, Link, label, className }: DocsSidebarProps): ReactNode;
+declare function DocsSidebar({ nav, pathname, Link, label, expandGroup, collapseGroup, externalLink, className }: DocsSidebarProps): ReactNode;
 //#endregion
 export { DocsSidebar, DocsSidebarProps };

package/dist/react/sidebar.js

@@ -1,8 +1,13 @@
 "use client";
 import { nearestScrollTop } from "./nearest-scroll-top.js";
-import { useId, useLayoutEffect, useRef, useState } from "react";
+import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/sidebar.tsx
+const DEFAULT_SIDEBAR_LABELS = {
+	expandGroup: "Expand {title}",
+	collapseGroup: "Collapse {title}",
+	externalLink: "(opens in a new tab)"
+};
 /** Trailing slashes are a routing detail, not a difference in identity. */
 function normalizeHref(href) {
 	return href.length > 1 ? href.replace(/\/+$/, "") : href;
@@ -61,7 +66,12 @@ function containsActive(node, pathname) {
 * nothing prefetches locally whatever this says. Do not "fix" it back because
 * the network tab looks the same.
 */
-function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
+function DocsSidebar({ nav, pathname, Link, label = "Docs", expandGroup, collapseGroup, externalLink, className }) {
+	const text = {
+		expandGroup: expandGroup ?? DEFAULT_SIDEBAR_LABELS.expandGroup,
+		collapseGroup: collapseGroup ?? DEFAULT_SIDEBAR_LABELS.collapseGroup,
+		externalLink: externalLink ?? DEFAULT_SIDEBAR_LABELS.externalLink
+	};
 	const baseId = useId();
 	const [toggled, setToggled] = useState({});
 	const lastPathname = useRef(pathname);
@@ -77,19 +87,19 @@ function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
 	};
 	const navRef = useRef(null);
 	useLayoutEffect(() => {
-		const active = navRef.current?.querySelector("[aria-current=\"page\"]");
-		if (!(active instanceof HTMLElement)) return;
-		const port = scrollableAncestor(active);
-		if (port === null) return;
-		const next = nearestScrollTop({
-			itemTop: active.getBoundingClientRect().top - port.getBoundingClientRect().top + port.scrollTop,
-			itemHeight: active.offsetHeight,
-			viewHeight: port.clientHeight,
-			scrollTop: port.scrollTop,
-			scrollHeight: port.scrollHeight
-		});
-		if (next !== void 0) port.scrollTop = next;
+		revealActive(navRef.current);
 	}, [pathname]);
+	useEffect(() => {
+		const dialog = navRef.current?.closest("dialog");
+		if (!(dialog instanceof HTMLDialogElement)) return;
+		const onToggle = () => {
+			if (dialog.open) revealActive(navRef.current);
+		};
+		dialog.addEventListener("toggle", onToggle);
+		return () => {
+			dialog.removeEventListener("toggle", onToggle);
+		};
+	}, []);
 	return /* @__PURE__ */ jsx("nav", {
 		ref: navRef,
 		"aria-label": label,
@@ -101,7 +111,8 @@ function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
 			pathname,
 			Link,
 			toggled,
-			onToggle: handleToggle
+			onToggle: handleToggle,
+			text
 		})
 	});
 }
@@ -115,6 +126,28 @@ function DocsSidebar({ nav, pathname, Link, label = "Docs", className }) {
 * one navigation where they know precisely what they asked for.
 * `sidebar.test.tsx` spies on it and asserts it is never called.
 */
+/**
+* Scroll the item marked `aria-current="page"` into view, if it is not already.
+*
+* A no-op wherever there is nothing to measure — no nav, no active item, no
+* scrollport — which is every server render, every jsdom render, and every
+* layout where the column is shorter than its content. Nothing to do, and
+* nothing to do wrongly.
+*/
+function revealActive(nav) {
+	const active = nav?.querySelector("[aria-current=\"page\"]");
+	if (!(active instanceof HTMLElement)) return;
+	const port = scrollableAncestor(active);
+	if (port === null) return;
+	const next = nearestScrollTop({
+		itemTop: active.getBoundingClientRect().top - port.getBoundingClientRect().top + port.scrollTop,
+		itemHeight: active.offsetHeight,
+		viewHeight: port.clientHeight,
+		scrollTop: port.scrollTop,
+		scrollHeight: port.scrollHeight
+	});
+	if (next !== void 0) port.scrollTop = next;
+}
 function scrollableAncestor(element) {
 	let current = element.parentElement;
 	while (current !== null) {
@@ -124,7 +157,7 @@ function scrollableAncestor(element) {
 	}
 	return null;
 }
-function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, id }) {
+function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, text, id }) {
 	const holdsActive = nodes.some((node) => (node.type === "page" || node.type === "link" && !node.external) && isActiveHref(pathname, node.href));
 	return /* @__PURE__ */ jsx("ul", {
 		id,
@@ -148,6 +181,7 @@ function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, i
 						isActive: !node.external && isActiveHref(pathname, node.href),
 						isNearby: holdsActive,
 						Link,
+						externalLink: text.externalLink,
 						children: node.title
 					})
 				}, key);
@@ -169,14 +203,15 @@ function NavList({ nodes, depth, keyPrefix, pathname, Link, toggled, onToggle, i
 					pathname,
 					Link,
 					toggled,
-					onToggle
+					onToggle,
+					text
 				}, key);
 				default: return null;
 			}
 		})
 	});
 }
-function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle }) {
+function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle, text }) {
 	const listId = `${itemKey}-list`;
 	const hasActive = containsActive(node, pathname);
 	const isOpen = toggled[itemKey] ?? hasActive;
@@ -208,7 +243,7 @@ function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle }) {
 				className: "wave-docs-sidebar__group-toggle",
 				"aria-expanded": isOpen,
 				"aria-controls": isOpen ? listId : void 0,
-				"aria-label": `${isOpen ? "Collapse" : "Expand"} ${node.title}`,
+				"aria-label": (isOpen ? text.collapseGroup : text.expandGroup).replace("{title}", node.title),
 				onClick: () => onToggle(itemKey, !isOpen),
 				children: /* @__PURE__ */ jsx(Chevron, { isOpen })
 			})] })
@@ -220,11 +255,12 @@ function NavGroup({ node, itemKey, depth, pathname, Link, toggled, onToggle }) {
 			pathname,
 			Link,
 			toggled,
-			onToggle
+			onToggle,
+			text
 		}) : null]
 	});
 }
-function NavLink({ href, isExternal, isActive, isNearby = false, Link, children }) {
+function NavLink({ href, isExternal, isActive, isNearby = false, Link, externalLink = DEFAULT_SIDEBAR_LABELS.externalLink, children }) {
 	const className = "wave-docs-sidebar__link";
 	if (isExternal) return /* @__PURE__ */ jsxs("a", {
 		className,
@@ -247,9 +283,9 @@ function NavLink({ href, isExternal, isActive, isNearby = false, Link, children
 				strokeLinejoin: "round",
 				children: /* @__PURE__ */ jsx("path", { d: "M14 4h6v6M20 4l-8 8M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5" })
 			}),
-			/* @__PURE__ */ jsx("span", {
+			/* @__PURE__ */ jsxs("span", {
 				className: "wave-docs-sr-only",
-				children: " (opens in a new tab)"
+				children: [" ", externalLink]
 			})
 		]
 	});

package/dist/react/youtube.d.ts

@@ -3,11 +3,32 @@ import { ReactNode } from "react";
 interface YouTubeProps {
   /** The 11-character video id, e.g. `dQw4w9WgXcQ`. */
   id?: string | undefined;
+  /**
+   * Seconds to start at, from the link's `t` or `start`.
+   *
+   * ⚠️ IT USED TO BE DROPPED, AND THE FACADE AUTOPLAYS. `https://youtu.be/x?t=754`
+   * is a link to one moment in a two-hour talk — most of why anyone deep-links a
+   * video at all — and it opened at zero and started playing there, leaving the
+   * reader to work out that the author had meant somewhere else.
+   */
+  start?: number | undefined;
+  /** Playlist the video was linked inside, from the link's `list`. */
+  list?: 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;
+  /**
+   * The closed facade's control. Default `'Play video: {title}'`.
+   *
+   * `{title}` is replaced with {@link YouTubeProps.title}. A placeholder rather
+   * than concatenation because a translator has to be able to move the name
+   * within the sentence — several languages put it first.
+   */
+  playLabel?: string | undefined;
+  /** The open facade's control. Default `'Hide video: {title}'`. */
+  hideLabel?: string | undefined;
   className?: string | undefined;
 }
 /**
@@ -48,6 +69,6 @@ interface YouTubeProps {
  * `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;
+declare function YouTube({ id, start, list, title, playLabel, hideLabel, className }: YouTubeProps): ReactNode;
 //#endregion
 export { YouTube, YouTubeProps };

package/dist/react/youtube.js

@@ -1,6 +1,24 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/youtube.tsx
+/**
+* The embed URL, with whatever the author's link carried.
+*
+* `URLSearchParams` rather than string concatenation: `list` comes out of a
+* document and goes into a URL, and building this by hand is how a crafted
+* "playlist id" adds parameters of its own. `start` is already a number.
+*/
+function embedUrl(id, start, list) {
+	const params = new URLSearchParams({
+		rel: "0",
+		autoplay: "1"
+	});
+	if (start !== void 0 && Number.isFinite(start) && start > 0) params.set("start", String(Math.floor(start)));
+	if (list !== void 0 && list !== "") params.set("list", list);
+	return `https://www.youtube-nocookie.com/embed/${id}?${params.toString()}`;
+}
 const DEFAULT_TITLE = "YouTube video player";
+const DEFAULT_PLAY_LABEL = "Play video: {title}";
+const DEFAULT_HIDE_LABEL = "Hide video: {title}";
 /**
 * Click-to-load YouTube embed, with **no client JavaScript at all**.
 *
@@ -39,7 +57,7 @@ const DEFAULT_TITLE = "YouTube video player";
 * `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 }) {
+function YouTube({ id, start, list, title, playLabel, hideLabel, className }) {
 	if (!id) return null;
 	const safeId = encodeURIComponent(id);
 	const label = title?.trim() || DEFAULT_TITLE;
@@ -78,17 +96,17 @@ function YouTube({ id, title, className }) {
 				}),
 				/* @__PURE__ */ jsx("span", {
 					className: "wave-docs-sr-only wave-docs-youtube__label-play",
-					children: `Play video: ${label}`
+					children: (playLabel ?? DEFAULT_PLAY_LABEL).replace("{title}", label)
 				}),
 				/* @__PURE__ */ jsx("span", {
 					className: "wave-docs-youtube__label-hide",
-					children: `Hide video: ${label}`
+					children: (hideLabel ?? DEFAULT_HIDE_LABEL).replace("{title}", label)
 				})
 			]
 		}), /* @__PURE__ */ jsx("iframe", {
 			className: "wave-docs-youtube__frame",
 			loading: "lazy",
-			src: `https://www.youtube-nocookie.com/embed/${safeId}?rel=0&autoplay=1`,
+			src: embedUrl(safeId, start, list),
 			title: label,
 			allow: "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share",
 			allowFullScreen: true

package/dist/render.d.ts

@@ -1,5 +1,6 @@
 import { DocFile, DocFrontmatter, ImageResolver, LinkResolver, RenderedDoc, ResolvedDocsConfig } from "./types.js";
 import { DocsHighlighter, DocsLang, DocsThemes } from "./highlighter.js";
+import { RehypeCodeFrameOptions } from "./plugins/rehype-code-frame.js";
 import { resolveMarkdownLink } from "./plugins/remark-doc-links.js";
 import { PluggableList } from "unified";
 //#region src/render.d.ts
@@ -115,6 +116,16 @@ interface DocsRendererOptions {
    * than a monochrome block of DSL.
    */
   excludeLangs?: readonly string[] | undefined;
+  /**
+   * Accessible names for the copy button, for a site that is not in English.
+   *
+   * ⚠️ `rehypeCodeFrame` HAS TAKEN A `copyLabel` SINCE IT WAS WRITTEN AND
+   * NOTHING EVER PASSED ONE. The plugin is private, so the option was
+   * unreachable from every entry point — the README said the label was
+   * configurable and it was not. Baked into the HTML at build time, so
+   * overriding it costs no client bytes.
+   */
+  codeLabels?: RehypeCodeFrameOptions | undefined;
 }
 /**
  * Renders {@link DocFile}s. Build one per process and reuse it.

package/dist/render.js

@@ -5,7 +5,7 @@ import { rehypeCodeFrame } from "./plugins/rehype-code-frame.js";
 import { rehypeNormalizeCodeLanguage, rehypeRestoreExcludedCode } from "./plugins/rehype-code-language.js";
 import { rehypeFallbackHeadingIds } from "./plugins/rehype-fallback-heading-ids.js";
 import { rehypeFlattenRoots } from "./plugins/rehype-flatten-roots.js";
-import { foldSegments, remarkDocLinks, resolveMarkdownLink } from "./plugins/remark-doc-links.js";
+import { foldSegments, remarkDocLinks, resolveMarkdownLink, splitHref } from "./plugins/remark-doc-links.js";
 import { remarkUnwrapImages } from "./plugins/remark-unwrap-images.js";
 import { remarkYouTube } from "./plugins/remark-youtube.js";
 import rehypeShikiFromHighlighter from "@shikijs/rehype/core";
@@ -96,9 +96,29 @@ function assertResolvedImage(value, src, relativePath) {
 * author means by `![](./diagram.png)` and what the link path has always done.
 */
 function foldImageSrc(src, dirSegments) {
-	if (isPublicImageSrc(src)) return src;
-	const segments = foldSegments(dirSegments, src);
-	return segments === void 0 ? void 0 : segments.join("/");
+	if (isPublicImageSrc(src)) return {
+		path: src,
+		suffix: ""
+	};
+	const { path, query, hash } = splitHref(src);
+	if (path === "") return;
+	const segments = foldSegments(dirSegments, path);
+	return segments === void 0 ? void 0 : {
+		path: segments.join("/"),
+		suffix: `${query}${hash}`
+	};
+}
+/**
+* Put the authored `?query#hash` back, unless the resolver wrote its own.
+*
+* A resolver returning `/img/diagram.a1b2c3.png?w=800` has said something more
+* specific than the author's `?v=2` — and concatenating the two would produce
+* two `?` in one URL, which is not a URL. Same rule the rest of this package
+* uses when a host and a default disagree: the more specific one wins.
+*/
+function withSuffix(src, suffix) {
+	if (suffix === "" || /[?#]/.test(src)) return src;
+	return `${src}${suffix}`;
 }
 /** Route without its `?query` / `#anchor`, for existence checks. */
 function toRouteKey(href) {
@@ -238,7 +258,7 @@ async function buildProcessor(options, themes, highlighterPromise) {
 			ariaHidden: "true",
 			tabIndex: -1
 		}
-	}).use(options.rehypePlugins ?? []).use(rehypeNormalizeCodeLanguage, { ...options.excludeLangs === void 0 ? {} : { exclude: options.excludeLangs } }).use(rehypeCodeFrame).use(rehypeShikiFromHighlighter, highlighter, {
+	}).use(options.rehypePlugins ?? []).use(rehypeNormalizeCodeLanguage, { ...options.excludeLangs === void 0 ? {} : { exclude: options.excludeLangs } }).use(rehypeCodeFrame, options.codeLabels ?? {}).use(rehypeShikiFromHighlighter, highlighter, {
 		themes,
 		defaultColor: false,
 		fallbackLanguage: "text",
@@ -294,7 +314,13 @@ function createDocsRenderer(options) {
 		await Promise.all(images.map(async (node) => {
 			const src = node.properties.src;
 			if (typeof src !== "string" || src === "") return;
-			const folded = foldImageSrc(src, context.dirSegments);
+			let folded;
+			try {
+				folded = foldImageSrc(src, context.dirSegments);
+			} catch (error) {
+				if (!(error instanceof URIError)) throw error;
+				throw docsError("invalid-image", `@waveso/docs: image "${src}" in ${file.relativePath} is not valid percent-encoding. Write %25 for a literal percent sign, or name the file as it is on disk.`, { cause: error });
+			}
 			if (folded === void 0) throw docsError("invalid-image", `@waveso/docs: image "${src}" in ${file.relativePath} climbs above the content root.`);
 			if (resolve === void 0) {
 				if (isPublicImageSrc(src)) return;
@@ -302,16 +328,16 @@ function createDocsRenderer(options) {
 			}
 			let resolved;
 			try {
-				resolved = await resolve(folded, context);
+				resolved = await resolve(folded.path, context);
 			} catch (error) {
 				throw docsError("invalid-image", `@waveso/docs: the imageResolver threw on image "${src}" in ${file.relativePath}.`, { cause: error });
 			}
 			if (resolved === void 0) {
-				node.properties.src = folded;
-				return;
+				if (isPublicImageSrc(src)) return;
+				throw docsError("invalid-image", `@waveso/docs: the imageResolver returned nothing for image "${src}" in ${file.relativePath}, which is relative to the markdown file — so nothing can serve it: the browser would resolve it against the page route, and the same markdown would request a different file from every page. Return a src for it, or move the image under \`public/\` and write an absolute one such as "/diagram.png".`);
 			}
 			assertResolvedImage(resolved, src, file.relativePath);
-			node.properties.src = resolved.src;
+			node.properties.src = withSuffix(resolved.src, folded.suffix);
 			if (resolved.width !== void 0) node.properties.width = resolved.width;
 			if (resolved.height !== void 0) node.properties.height = resolved.height;
 		}));
@@ -336,8 +362,9 @@ function createDocsRenderer(options) {
 	}
 	return { async render(file) {
 		const processor = await processorPromise;
+		const lead = "\n".repeat(file.frontmatterLines ?? 0);
 		const vfile = new VFile({
-			value: file.content,
+			value: lead + file.content,
 			path: file.filePath
 		});
 		vfile.data.docLinkContext = {

package/dist/route-path.js

@@ -1,5 +1,5 @@
 import { docsError } from "./docs-error.js";
-import { foldSegments } from "./plugins/remark-doc-links.js";
+import { decodePath, foldSegments } from "./plugins/remark-doc-links.js";
 //#region src/route-path.ts
 /**
 * Turning route segments into a URL path.
@@ -39,7 +39,12 @@ const ALIAS_PATTERN_CHARS = /[:()+*?{}]/;
 * every rejection below names the markdown file at the moment it is read.
 */
 function toAliasRoute(alias, basePath, sourceLabel) {
-	const trimmed = alias.trim();
+	let trimmed;
+	try {
+		trimmed = decodePath(alias.trim(), alias);
+	} catch (error) {
+		throw docsError("invalid-alias", `@waveso/docs: the alias '${alias}' in ${sourceLabel} is not valid percent-encoding. Write %25 for a literal percent sign, or write the former URL as its readable form.`, { cause: error });
+	}
 	if (trimmed.split("/").some((part) => part === "." || part === "..")) throw docsError("invalid-alias", `@waveso/docs: the alias '${alias}' in ${sourceLabel} has a '.' or '..' segment. An alias is a former URL relative to the docs base path, not a path on disk: write \`aliases: [legacy/old-name]\`.`);
 	const pattern = ALIAS_PATTERN_CHARS.exec(trimmed);
 	if (pattern !== null) throw docsError("invalid-alias", `@waveso/docs: the alias '${alias}' in ${sourceLabel} contains '${pattern[0]}', which Next compiles as redirect pattern syntax rather than as part of the URL — the redirect then swallows every page whose route the pattern happens to match, or fails the build. Remove the character; an alias is a literal former URL.`);

package/dist/safe-href.d.ts

@@ -0,0 +1,47 @@
+//#region src/safe-href.d.ts
+/**
+ * The one allowlist of schemes this package will put in an `href`.
+ *
+ * Private — deliberately not an entry point.
+ *
+ * ⚠️ IT WAS THE MARKDOWN PATH'S ALONE, AND `meta.json` WENT ROUND IT. A hand
+ * written nav entry — `{ "title": "Status", "href": "javascript:…" }` — reached
+ * `<a href>` through `DocsSidebar` with nothing checking it, while the markdown
+ * beside it was filtered by a comment calling the check load-bearing. Both paths
+ * end at the same anchor, so both need the same rule, and a rule with two copies
+ * is a rule with one that is out of date.
+ *
+ * Node-safe and browser-safe: two regular expressions and two functions, no
+ * imports at all.
+ */
+/**
+ * Strip the characters a browser ignores inside a URL.
+ *
+ * `java\nscript:` and `java&#09;script:` are `javascript:` to a parser and not
+ * to a naive regular expression, so the test has to run on the string the
+ * browser will see rather than on the one that was written.
+ */
+declare function normaliseUrl(href: string): string;
+/**
+ * Would this href navigate somewhere we are willing to send a reader?
+ *
+ * Nothing upstream filters it on the markdown side: `remarkDocLinks` skips every
+ * href with a scheme, so `assertLinks` never sees one either, and `remarkRehype`
+ * runs with `allowDangerousHtml` off but passes a link's own url through
+ * untouched. Verified against React 19: it neutralises `javascript:` in every
+ * obfuscated form, silently — but it lets `vbscript:` and
+ * `data:text/html;base64,…` reach the DOM verbatim. So the allowlist is ours.
+ */
+declare function isSafeHref(href: string): boolean;
+/**
+ * Does following this href leave the site in a new tab?
+ *
+ * ⚠️ NOT "HAS A SCHEME". `meta.json` used that test, so a `mailto:` sidebar
+ * entry was given `target="_blank"` and announced as "(opens in a new tab)" — a
+ * tab that never opens, described to precisely the reader who cannot see that it
+ * did not. Only http(s) and protocol-relative navigate; `mailto:` and `tel:`
+ * hand off to the OS and leave the page where it is.
+ */
+declare function opensInNewTab(href: string): boolean;
+//#endregion
+export { isSafeHref, normaliseUrl, opensInNewTab };

package/dist/safe-href.js

@@ -0,0 +1,73 @@
+//#region src/safe-href.ts
+/**
+* The one allowlist of schemes this package will put in an `href`.
+*
+* Private — deliberately not an entry point.
+*
+* ⚠️ IT WAS THE MARKDOWN PATH'S ALONE, AND `meta.json` WENT ROUND IT. A hand
+* written nav entry — `{ "title": "Status", "href": "javascript:…" }` — reached
+* `<a href>` through `DocsSidebar` with nothing checking it, while the markdown
+* beside it was filtered by a comment calling the check load-bearing. Both paths
+* end at the same anchor, so both need the same rule, and a rule with two copies
+* is a rule with one that is out of date.
+*
+* Node-safe and browser-safe: two regular expressions and two functions, no
+* imports at all.
+*/
+/**
+* Any URL with a scheme, or protocol-relative.
+*/
+const ABSOLUTE_URL = /^([a-z][a-z0-9+.-]*:|\/\/)/i;
+/**
+* The schemes a link may carry.
+*
+* GitHub's own allowlist, which is the bar to match: documentation links to
+* `sms:`, `ftp:` and `irc:` are ordinary, and an allowlist of three silently
+* deleted them. The point of the check is to stop `javascript:`, `data:` and
+* `vbscript:` reaching an `href`, not to have an opinion about protocols.
+*
+* A scheme not listed here — `vscode:`, `obsidian:`, `slack:` — is refused
+* rather than rendered. That is deliberate: an allowlist that grows on request
+* is safe, one that guesses is not.
+*/
+const SAFE_SCHEME = /^(https?|mailto|tel|sms|ftp|ftps|irc|ircs|xmpp|news|nntp|feed|git|matrix):/i;
+/**
+* Strip the characters a browser ignores inside a URL.
+*
+* `java\nscript:` and `java&#09;script:` are `javascript:` to a parser and not
+* to a naive regular expression, so the test has to run on the string the
+* browser will see rather than on the one that was written.
+*/
+function normaliseUrl(href) {
+	return [...href].filter((char) => (char.codePointAt(0) ?? 0) > 32).join("");
+}
+/**
+* Would this href navigate somewhere we are willing to send a reader?
+*
+* Nothing upstream filters it on the markdown side: `remarkDocLinks` skips every
+* href with a scheme, so `assertLinks` never sees one either, and `remarkRehype`
+* runs with `allowDangerousHtml` off but passes a link's own url through
+* untouched. Verified against React 19: it neutralises `javascript:` in every
+* obfuscated form, silently — but it lets `vbscript:` and
+* `data:text/html;base64,…` reach the DOM verbatim. So the allowlist is ours.
+*/
+function isSafeHref(href) {
+	const normalised = normaliseUrl(href);
+	if (!ABSOLUTE_URL.test(normalised)) return true;
+	return normalised.startsWith("//") || SAFE_SCHEME.test(normalised);
+}
+/**
+* Does following this href leave the site in a new tab?
+*
+* ⚠️ NOT "HAS A SCHEME". `meta.json` used that test, so a `mailto:` sidebar
+* entry was given `target="_blank"` and announced as "(opens in a new tab)" — a
+* tab that never opens, described to precisely the reader who cannot see that it
+* did not. Only http(s) and protocol-relative navigate; `mailto:` and `tel:`
+* hand off to the OS and leave the page where it is.
+*/
+function opensInNewTab(href) {
+	const normalised = normaliseUrl(href);
+	return /^https?:\/\//i.test(normalised) || normalised.startsWith("//");
+}
+//#endregion
+export { isSafeHref, normaliseUrl, opensInNewTab };

package/dist/search-index.js

@@ -1,5 +1,5 @@
-import { isFootnotes, isTransparentContainer } from "./section-boundary.js";
 import { mergeSearchOptions } from "./search-options.js";
+import { isFootnotes, isTransparentContainer } from "./section-boundary.js";
 import MiniSearch from "minisearch";
 //#region src/search-index.ts
 /** `<h1>`…`<h6>` to their numeric depth. */