@tenphi/starlight 0.10.2 → 0.11.0

package/dist/index.js

@@ -3,7 +3,7 @@ import { a as resolveNavigationLayout } from "./navigation-CkQXI2Zb.js";
 import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
 import { cp, mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
-import { dirname, extname, join } from "node:path";
+import { dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { COOKBOOK_COMPONENT_NAMES, assertValidDocs, createDocsGraph } from "@tenphi/docs";
 import { configure } from "@tenphi/tasty/core";
@@ -11,6 +11,7 @@ import { tastyIntegration } from "@tenphi/tasty/ssr/astro";
 import { renderMermaidSVG } from "beautiful-mermaid";
 import { apcaContrast, glaze, okhslToLinearSrgb, relativeLuminanceFromLinearRgb, variantToOkhsl } from "@tenphi/glaze";
 import "@tenphi/tasty";
+import sharp from "sharp";
 //#region src/markdown/rehype-mermaid.ts
 const sourceStyleDirective = /^\s*(?:classDef|style|linkStyle)\s+.*$/gim;
 const accessibilityDirective = /^\s*acc(?:Title|Descr):\s*.*$/gim;
@@ -144,6 +145,64 @@ function isScrollContainer(node) {
 	return node.type === "element" && node.tagName === "div" && Array.isArray(className) && className.includes(containerClass);
 }
 //#endregion
+//#region src/markdown/rehype-page-affordances.ts
+/** Add copy controls to rendered Markdown code blocks. */
+function rehypePageAffordances() {
+	return (tree) => addPageAffordances(tree);
+}
+/** Sätteri adapter for Astro's default Markdown processor. */
+const satteriPageAffordances = {
+	name: "cookbook:page-affordances",
+	element: {
+		filter: ["pre"],
+		visit(node, context) {
+			const replacement = pageAffordance(node);
+			if (replacement !== node) context.replaceNode(node, replacement);
+		}
+	}
+};
+function addPageAffordances(parent) {
+	if (!parent.children) return;
+	for (const [index, child] of parent.children.entries()) {
+		const replacement = pageAffordance(child);
+		if (replacement !== child) {
+			parent.children[index] = replacement;
+			continue;
+		}
+		addPageAffordances(child);
+	}
+}
+function pageAffordance(node) {
+	if (isOrdinaryCodeBlock(node)) return codeBlockWithCopy(node);
+	return node;
+}
+function isOrdinaryCodeBlock(node) {
+	if (node.type !== "element" || node.tagName !== "pre") return false;
+	return (node.properties?.dataLanguage ?? node.properties?.["data-language"]) !== "mermaid" && node.children?.[0]?.tagName === "code";
+}
+function codeBlockWithCopy(pre) {
+	return element("cookbook-code-block", {
+		className: ["td-code-block"],
+		dataTastyAnatomy: "MarkdownCodeBlock"
+	}, [pre, element("button", {
+		type: "button",
+		dataCopyCode: "",
+		ariaLabel: "Copy code",
+		title: "Copy code"
+	}, [element("span", {
+		dataCopyIcon: "",
+		ariaHidden: "true"
+	}, [])])]);
+}
+function element(tagName, properties, children) {
+	return {
+		type: "element",
+		tagName,
+		properties,
+		children
+	};
+}
+//#endregion
 //#region src/theme/defaults.ts
 const DEFAULT_THEME_TOKENS = {
 	$gap: "0.5rem",
@@ -868,6 +927,7 @@ const cookbookStates = {
 	"@mobile": "@media(w < 50rem)",
 	"@desktop": "@media(w >= 50rem)",
 	"@small": "@media(w <= 40rem)",
+	"@compact": "@media(w <= 23rem)",
 	"@shell-mobile": "@media(w <= 48rem)",
 	"@shell-desktop": "@media(w > 48rem)",
 	"@narrow-layout": "@media(w < 72rem)",
@@ -875,6 +935,212 @@ const cookbookStates = {
 	"@reduced-motion": "@media(prefers-reduced-motion: reduce)"
 };
 //#endregion
+//#region src/site-icons.ts
+const ICON_DIRECTORY = "_cookbook/icons";
+const DEFAULT_ICON_BACKGROUND = "#315efb";
+const SUPPORTED_SOURCE_FORMATS = /* @__PURE__ */ new Set([
+	"avif",
+	"gif",
+	"heif",
+	"jpeg",
+	"jpg",
+	"png",
+	"svg",
+	"webp"
+]);
+async function createSiteIcons({ base, root, site = {}, themeColors }) {
+	const configured = site.favicon;
+	const source = typeof configured === "string" ? configured : configured?.source;
+	const sourcePath = source ? resolveSourcePath(source, root) : fileURLToPath(new URL("./icons/favicon.svg", import.meta.url));
+	const background = typeof configured === "object" && configured?.background ? configured.background : DEFAULT_ICON_BACKGROUND;
+	const input = await readFile(sourcePath).catch((error) => {
+		throw new Error(`Unable to read site.favicon source at ${sourcePath}: ${errorMessage$1(error)}`);
+	});
+	const format = (await sharp(input, { animated: false }).metadata()).format?.toLowerCase();
+	if (!format || !SUPPORTED_SOURCE_FORMATS.has(format)) throw new Error("site.favicon must point to an SVG, PNG, JPEG, WebP, AVIF, or GIF image.");
+	const definitions = [
+		await pngAsset(input, base, "favicon-32x32.png", 32),
+		await safePngAsset(input, base, "apple-touch-icon.png", 180, background),
+		await pngAsset(input, base, "icon-192x192.png", 192),
+		await pngAsset(input, base, "icon-512x512.png", 512),
+		await safePngAsset(input, base, "icon-192x192-maskable.png", 192, background),
+		await safePngAsset(input, base, "icon-512x512-maskable.png", 512, background)
+	];
+	const scalable = format === "svg" ? asset(base, "favicon.svg", input, "image/svg+xml") : void 0;
+	const faviconPath = `/${ICON_DIRECTORY}/${scalable ? "favicon.svg" : "favicon-32x32.png"}`;
+	const iconEntries = [
+		{
+			src: pathWithBase(base, `/${ICON_DIRECTORY}/icon-192x192.png`),
+			sizes: "192x192",
+			type: "image/png",
+			purpose: "any"
+		},
+		{
+			src: pathWithBase(base, `/${ICON_DIRECTORY}/icon-512x512.png`),
+			sizes: "512x512",
+			type: "image/png",
+			purpose: "any"
+		},
+		{
+			src: pathWithBase(base, `/${ICON_DIRECTORY}/icon-192x192-maskable.png`),
+			sizes: "192x192",
+			type: "image/png",
+			purpose: "maskable"
+		},
+		{
+			src: pathWithBase(base, `/${ICON_DIRECTORY}/icon-512x512-maskable.png`),
+			sizes: "512x512",
+			type: "image/png",
+			purpose: "maskable"
+		},
+		...scalable ? [{
+			src: scalable.publicPath,
+			sizes: "any",
+			type: "image/svg+xml",
+			purpose: "any"
+		}] : []
+	];
+	const manifest = asset(base, "site.webmanifest", Buffer.from(`${JSON.stringify({
+		name: site.title ?? "Documentation",
+		short_name: site.title ?? "Documentation",
+		...site.description ? { description: site.description } : {},
+		id: normalizedBase(base),
+		start_url: normalizedBase(base),
+		scope: normalizedBase(base),
+		display: "standalone",
+		background_color: background,
+		theme_color: themeColors.light,
+		icons: iconEntries
+	}, null, 2)}\n`), "application/manifest+json");
+	const favicon32 = definitions[0];
+	const appleTouchIcon = definitions[1];
+	if (!favicon32 || !appleTouchIcon) throw new Error("Cookbook failed to generate the required site icons.");
+	return {
+		assets: [
+			...definitions,
+			...scalable ? [scalable] : [],
+			manifest
+		],
+		faviconPath,
+		head: [
+			{
+				tag: "link",
+				attrs: {
+					rel: "icon",
+					href: favicon32.publicPath,
+					sizes: "32x32",
+					type: favicon32.contentType
+				}
+			},
+			...scalable ? [{
+				tag: "link",
+				attrs: {
+					rel: "icon",
+					href: scalable.publicPath,
+					sizes: "any",
+					type: scalable.contentType
+				}
+			}] : [],
+			{
+				tag: "link",
+				attrs: {
+					rel: "apple-touch-icon",
+					href: appleTouchIcon.publicPath,
+					sizes: "180x180"
+				}
+			},
+			{
+				tag: "link",
+				attrs: {
+					rel: "manifest",
+					href: manifest.publicPath
+				}
+			},
+			{
+				tag: "meta",
+				attrs: {
+					name: "theme-color",
+					content: themeColors.light,
+					media: "(prefers-color-scheme: light)"
+				}
+			},
+			{
+				tag: "meta",
+				attrs: {
+					name: "theme-color",
+					content: themeColors.dark,
+					media: "(prefers-color-scheme: dark)"
+				}
+			}
+		],
+		sourcePath
+	};
+}
+async function pngAsset(input, base, name, size) {
+	return asset(base, name, await sharp(input, {
+		animated: false,
+		density: 512
+	}).resize(size, size, {
+		fit: "contain",
+		background: {
+			r: 0,
+			g: 0,
+			b: 0,
+			alpha: 0
+		}
+	}).png().toBuffer(), "image/png");
+}
+async function safePngAsset(input, base, name, size, background) {
+	const safeSize = Math.round(size * .8);
+	const foreground = await sharp(input, {
+		animated: false,
+		density: 512
+	}).resize(safeSize, safeSize, {
+		fit: "contain",
+		background: {
+			r: 0,
+			g: 0,
+			b: 0,
+			alpha: 0
+		}
+	}).png().toBuffer();
+	return asset(base, name, await sharp({ create: {
+		width: size,
+		height: size,
+		channels: 4,
+		background
+	} }).composite([{
+		input: foreground,
+		gravity: "center"
+	}]).png().toBuffer().catch((error) => {
+		throw new Error(`Unable to use site.favicon.background ${JSON.stringify(background)}: ${errorMessage$1(error)}`);
+	}), "image/png");
+}
+function asset(base, name, body, contentType) {
+	const outputPath = `${ICON_DIRECTORY}/${name}`;
+	return {
+		body,
+		contentType,
+		outputPath,
+		publicPath: pathWithBase(base, `/${outputPath}`)
+	};
+}
+function resolveSourcePath(source, root) {
+	if (/^[a-z][a-z\d+.-]*:/i.test(source)) throw new Error("site.favicon must reference a local image path.");
+	return isAbsolute(source) ? source : resolve(root, source);
+}
+function pathWithBase(base, pathname) {
+	const prefix = normalizedBase(base);
+	return `${prefix === "/" ? "" : prefix.replace(/\/$/, "")}${pathname}`;
+}
+function normalizedBase(base) {
+	const value = base.replace(/^\/+|\/+$/g, "");
+	return value ? `/${value}/` : "/";
+}
+function errorMessage$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
 //#region src/integration.ts
 const packageRequire = createRequire(import.meta.url);
 const starlightRoot = dirname(packageRequire.resolve("@astrojs/starlight"));
@@ -892,12 +1158,16 @@ function cookbook(options = {}) {
 	const headerPath = fileURLToPath(new URL("./overrides/Header.astro", import.meta.url));
 	const footerPath = fileURLToPath(new URL("./overrides/Footer.astro", import.meta.url));
 	const emptyFooterPath = fileURLToPath(new URL("./overrides/EmptyFooter.astro", import.meta.url));
+	const sidebarPath = fileURLToPath(new URL("./overrides/Sidebar.astro", import.meta.url));
+	const mobileMenuFooterPath = fileURLToPath(new URL("./overrides/MobileMenuFooter.astro", import.meta.url));
+	const mobileMenuTogglePath = fileURLToPath(new URL("./overrides/MobileMenuToggle.astro", import.meta.url));
 	const components = resolveComponentOverrides({
 		Footer: footerPath,
 		Header: headerPath,
-		Sidebar: fileURLToPath(new URL("./overrides/Sidebar.astro", import.meta.url)),
-		MobileMenuFooter: fileURLToPath(new URL("./overrides/MobileMenuFooter.astro", import.meta.url)),
-		MobileMenuToggle: fileURLToPath(new URL("./overrides/MobileMenuToggle.astro", import.meta.url)),
+		MarkdownContent: fileURLToPath(new URL("./overrides/MarkdownContent.astro", import.meta.url)),
+		Sidebar: sidebarPath,
+		MobileMenuFooter: mobileMenuFooterPath,
+		MobileMenuToggle: mobileMenuTogglePath,
 		ThemeSelect: fileURLToPath(new URL("./overrides/ThemeSelect.astro", import.meta.url))
 	}, options.config?.components?.overrides, emptyFooterPath);
 	const navigation = resolveNavigationLayout(options.config?.navigation);
@@ -910,6 +1180,8 @@ function cookbook(options = {}) {
 	let graphConfig = options.config;
 	let graph;
 	let usingContentCollection = false;
+	let siteIconBase = options.config?.build?.base ?? "/";
+	let siteIcons;
 	async function loadGraph(refresh = false) {
 		if (!graph || refresh) {
 			graph = await createDocsGraph({
@@ -920,6 +1192,18 @@ function cookbook(options = {}) {
 		}
 		return graph;
 	}
+	async function loadSiteIcons() {
+		if (!projectRoot) throw new Error("Cookbook cannot generate site icons without a project root.");
+		return createSiteIcons({
+			base: siteIconBase,
+			root: projectRoot,
+			...options.config?.site ? { site: options.config.site } : {},
+			themeColors: {
+				light: docsTheme.colors.surface.light ?? "#ffffff",
+				dark: docsTheme.colors.surface.dark ?? "#20232a"
+			}
+		});
+	}
 	return {
 		name: "cookbook",
 		hooks: {
@@ -928,6 +1212,8 @@ function cookbook(options = {}) {
 				if (context.config.integrations.some((integration) => integration.name === "@astrojs/starlight")) throw new Error("Cookbook already includes Starlight. Remove the direct @astrojs/starlight integration before continuing.");
 				projectRoot ??= fileURLToPath(context.config.root);
 				const base = options.config?.build?.base ?? context.config.base;
+				siteIconBase = base;
+				siteIcons = await loadSiteIcons();
 				graphConfig = {
 					...options.config,
 					build: {
@@ -940,7 +1226,12 @@ function cookbook(options = {}) {
 				const starlightIntegration = starlight({
 					title: options.config?.site?.title ?? "Documentation",
 					expressiveCode: false,
-					...options.config?.head ? { head: options.config.head } : {},
+					favicon: siteIcons.faviconPath,
+					head: [...siteIcons.head, ...options.config?.head ?? []],
+					...options.config?.editLink ? { editLink: options.config.editLink } : {},
+					...options.config?.lastUpdated !== void 0 ? { lastUpdated: options.config.lastUpdated } : {},
+					...options.config?.locales ? { locales: options.config.locales } : {},
+					...options.config?.defaultLocale ? { defaultLocale: options.config.defaultLocale } : {},
 					...options.config?.site?.description ? { description: options.config.site.description } : {},
 					...options.config?.search?.enabled === false ? { pagefind: false } : {},
 					...!usingContentCollection ? { disable404Route: true } : {},
@@ -1072,14 +1363,35 @@ function cookbook(options = {}) {
 			"astro:config:done": async (context) => {
 				await callInner(inner, "astro:config:done", context);
 			},
-			"astro:server:setup": async ({ server }) => {
+			"astro:server:setup": async ({ server, logger }) => {
 				let assets = docsAssetMap(await loadGraph());
+				if (options.config?.site?.favicon && siteIcons) {
+					server.watcher.add(siteIcons.sourcePath);
+					server.watcher.on("change", async (changedPath) => {
+						if (changedPath !== siteIcons?.sourcePath) return;
+						try {
+							siteIcons = await loadSiteIcons();
+							server.ws.send({ type: "full-reload" });
+						} catch (error) {
+							logger.error(errorMessage(error));
+						}
+					});
+				}
 				server.middlewares.use(async (request, response, next) => {
 					if (request.method !== "GET" && request.method !== "HEAD") {
 						next();
 						return;
 					}
 					const pathname = requestPath(request.url);
+					const siteIcon = siteIcons?.assets.find((asset) => asset.publicPath === pathname);
+					if (siteIcon) {
+						response.statusCode = 200;
+						response.setHeader("Content-Type", siteIcon.contentType);
+						response.setHeader("Content-Length", siteIcon.body.byteLength);
+						response.setHeader("Cache-Control", "no-cache");
+						response.end(request.method === "HEAD" ? void 0 : siteIcon.body);
+						return;
+					}
 					if (!pathname.includes("/_tasty-assets/")) {
 						next();
 						return;
@@ -1111,6 +1423,7 @@ function cookbook(options = {}) {
 				});
 			},
 			"astro:build:start": async (context) => {
+				siteIcons = await loadSiteIcons();
 				await loadGraph();
 				await callInner(inner, "astro:build:start", context);
 			},
@@ -1128,6 +1441,11 @@ function cookbook(options = {}) {
 				if (existsSync(pagefindOutput)) {
 					for (const name of await readdir(pagefindOutput)) if (extname(name) === ".css") await unlink(join(pagefindOutput, name));
 				}
+				for (const asset of siteIcons?.assets ?? []) {
+					const target = join(output, asset.outputPath);
+					await mkdir(dirname(target), { recursive: true });
+					await writeFile(target, asset.body);
+				}
 				if (!graph) return;
 				for (const asset of graph.assets) {
 					if (!asset.sourcePath || !asset.publicPath) continue;
@@ -1145,12 +1463,14 @@ function registerCookbookMarkdownPlugins(processor) {
 		const plugins = Array.isArray(options.rehypePlugins) ? options.rehypePlugins : [];
 		if (!plugins.includes(rehypeMermaid)) plugins.push(rehypeMermaid);
 		if (!plugins.includes(rehypeTableScroll)) plugins.push(rehypeTableScroll);
+		if (!plugins.includes(rehypePageAffordances)) plugins.push(rehypePageAffordances);
 		options.rehypePlugins = plugins;
 	} else if (processor.name === "satteri") {
 		const options = processor.options;
 		const plugins = Array.isArray(options.hastPlugins) ? options.hastPlugins : [];
 		if (!plugins.includes(satteriMermaid)) plugins.push(satteriMermaid);
 		if (!plugins.includes(satteriTableScroll)) plugins.push(satteriTableScroll);
+		if (!plugins.includes(satteriPageAffordances)) plugins.push(satteriPageAffordances);
 		options.hastPlugins = plugins;
 	}
 }
@@ -1219,6 +1539,9 @@ function assetContentType(pathname) {
 		default: return "application/octet-stream";
 	}
 }
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 function configureTastyTheme(theme, resolved) {
 	const tokens = tastyTokens(resolved);
 	const globalStyles = resolveLegacyAnatomyStyles(theme?.styles);