@allons-y/webc-patterns 0.1.0-beta.0 → 0.1.0-beta.1

package/lib/icons.js

@@ -0,0 +1,166 @@
+/*
+ * SPDX-License-Identifier: MPL-2.0
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** A lowercase kebab name: `chevron-up`, `x2`. */
+const NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+/** The viewBox of a file that has none, and no numeric width and height. */
+const VIEW_BOX = "0 0 24 24";
+
+/** Presentation attributes of the root `<svg>` that move to a `<g>`, so a file's own paint survives. */
+const PAINT = new Set([
+	"clip-rule",
+	"fill",
+	"fill-opacity",
+	"fill-rule",
+	"opacity",
+	"stroke",
+	"stroke-dasharray",
+	"stroke-dashoffset",
+	"stroke-linecap",
+	"stroke-linejoin",
+	"stroke-miterlimit",
+	"stroke-opacity",
+	"stroke-width",
+]);
+
+const ATTRIBUTE = /([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+const ROOT = /<svg((?:\s+[^\s"'<>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*)\s*(\/?)>/i;
+
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const quoted = (name) => `"${name}"`;
+
+/** The attributes of a tag's attribute text, as `[name, value][]`. */
+const attributes = (text) => [...text.matchAll(ATTRIBUTE)].map(([, name, double, single, bare]) => [name, double ?? single ?? bare ?? ""]);
+
+/**
+ * The parts of one SVG file an icon keeps: its viewBox, and its drawing as markup.
+ * The viewBox is the file's own, else `0 0 width height` from a numeric `width` and `height`, else `0 0 24 24`.
+ * The `<title>` and `<desc>` go, as the drawing is hidden from assistive tech. Scripts, `on*` attributes, and `javascript:` links go too.
+ *
+ * @param {string} text - The file's text
+ * @param {string} file - The file's path, for errors
+ * @returns {{ viewBox: string, body: string }}
+ * @throws {Error} When the file has no `<svg>` element
+ */
+function parse(text, file) {
+	const source = text.replace(/<\?[\s\S]*?\?>|<!--[\s\S]*?-->|<!DOCTYPE[^>]*>/gi, "");
+	const root = ROOT.exec(source);
+	if (!root) throw new Error(`norn: icons: ${file} has no <svg> element.`);
+	const own = attributes(root[1]);
+	const size = (key) => own.find(([name]) => name.toLowerCase() === key)?.[1].trim().replace(/px$/, "");
+	const [width, height] = [size("width"), size("height")];
+	const sized = /^[\d.]+$/.test(width ?? "") && /^[\d.]+$/.test(height ?? "") ? `0 0 ${width} ${height}` : VIEW_BOX;
+	const viewBox = size("viewbox") || sized;
+	if (!/^\s*-?[\d.]+(?:[\s,]+-?[\d.]+){3}\s*$/.test(viewBox)) throw new Error(`norn: icons: ${file} has the viewBox "${viewBox}", which is not four numbers.`);
+	const paint = own.filter(([name]) => PAINT.has(name.toLowerCase())).map(([name, value]) => ` ${name.toLowerCase()}="${value.replaceAll('"', "&quot;")}"`);
+	let inner = "";
+	if (!root[2]) {
+		const start = root.index + root[0].length;
+		const end = source.toLowerCase().lastIndexOf("</svg");
+		inner = end < start ? "" : source.slice(start, end);
+	}
+	inner = inner
+		.replace(/<(title|desc|script)\b[\s\S]*?<\/\1\s*>/gi, "")
+		.replace(/<(?:title|desc|script)\b[^>]*\/>/gi, "")
+		.replace(/\s+on[a-z]+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "")
+		.replace(/\s+((?:xlink:)?href)\s*=\s*(?:"\s*javascript:[^"]*"|'\s*javascript:[^']*')/gi, "")
+		.trim();
+	if (!inner) throw new Error(`norn: icons: ${file} has no drawing.`);
+	return { viewBox, body: paint.length ? `<g${paint.join("")}>${inner}</g>` : inner };
+}
+
+/**
+ * Give every id in an icon's drawing, and each reference to it, a prefix made from the icon's name.
+ * Inlined icons share the page's one id space, so two icons that each define `id="a"`, as SVGO's `cleanupIds` leaves them, would clip, mask, and fill each other:
+ * a reference resolves to the first element with the id, whichever icon it is in. The prefix is the same every time, so an icon used twice repeats its ids only with itself.
+ * References are `url(#id)`, `href` and `xlink:href`, and the `#id` selectors of a `<style>` in the drawing.
+ *
+ * @param {string} markup - The drawing
+ * @param {string} name - The icon's name, a lowercase kebab name
+ * @returns {string}
+ */
+function scopeIds(markup, name) {
+	const ids = [...new Set([...markup.matchAll(/\sid\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].map(([, double, single]) => double ?? single))].filter(Boolean);
+	if (!ids.length) return markup;
+	const prefix = `norn-icon-${name}-`;
+	// The longest first, so an id that starts another is not matched as the shorter one.
+	const any = ids
+		.sort((a, b) => b.length - a.length)
+		.map((id) => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+		.join("|");
+	const scoped = (_, before, id) => `${before}${prefix}${id}`;
+	return markup
+		.replace(new RegExp(`(\\sid\\s*=\\s*["'])(${any})(?=["'])`, "gi"), scoped)
+		.replace(new RegExp(`(url\\(\\s*["']?#)(${any})(?=["']?\\s*\\))`, "gi"), scoped)
+		.replace(new RegExp(`((?:xlink:)?href\\s*=\\s*["']#)(${any})(?=["'])`, "gi"), scoped)
+		.replace(/<style\b[\s\S]*?<\/style\s*>/gi, (style) => style.replace(new RegExp(`(#)(${any})(?![\\w-])`, "g"), scoped));
+}
+
+/** The `{ src, mirror }` of one record entry, or an error naming the icon. */
+function entry(name, value) {
+	if (!NAME.test(name)) throw new Error(`norn: icons: ${quoted(name)} is not a lowercase kebab name, such as "chevron-up".`);
+	const spec = typeof value === "string" ? { src: value } : value;
+	if (!isObject(spec) || typeof spec.src !== "string" || !spec.src) throw new Error(`norn: icons: ${quoted(name)} must be a path to an SVG file, or { src, mirror }.`);
+	const unknown = Object.keys(spec).filter((key) => key !== "src" && key !== "mirror");
+	if (unknown.length) throw new Error(`norn: icons: ${quoted(name)} has an unknown option ${unknown.map(quoted).join(", ")}. Options: src, mirror.`);
+	if (spec.mirror !== undefined && typeof spec.mirror !== "boolean") throw new Error(`norn: icons: the mirror option of ${quoted(name)} must be true or false.`);
+	return { src: spec.src, mirror: spec.mirror === true };
+}
+
+/**
+ * The icons an `icons` option names, read from disk.
+ * A glob, or a list of globs, names each file after its basename without `.svg`. A record names each icon and gives its path, or `{ src, mirror }`.
+ *
+ * @param {unknown} option - The plugin's `icons` option
+ * @param {string} root - The folder paths resolve against
+ * @returns {Record<string, { viewBox: string, body: string, mirror: boolean }>} Icons by name
+ * @throws {Error} On a bad option, a missing or unreadable file, a name that is not lowercase kebab, or two files with one name
+ */
+export function readIcons(option, root = process.cwd()) {
+	if (option === undefined) return {};
+	/** @type {Map<string, { src: string, file: string, mirror: boolean }>} */
+	const found = new Map();
+	const add = (name, src, file, mirror) => {
+		if (found.has(name)) throw new Error(`norn: icons: two files are named ${quoted(name)}: ${found.get(name).src} and ${src}.`);
+		found.set(name, { src, file, mirror });
+	};
+
+	if (typeof option === "string" || Array.isArray(option)) {
+		const globs = [option].flat();
+		if (!globs.length || globs.some((glob) => typeof glob !== "string" || !glob)) throw new Error("norn: `icons` must be a glob, a list of globs, or a record of icon names to SVG files.");
+		for (const glob of globs) {
+			for (const match of fs.globSync(glob, { cwd: root }).sort()) {
+				const file = path.resolve(root, match);
+				if (fs.statSync(file).isDirectory()) continue;
+				if (path.extname(file).toLowerCase() !== ".svg") throw new Error(`norn: icons: ${match} is not an SVG file. Match .svg files only.`);
+				const name = path.basename(file, path.extname(file));
+				if (!NAME.test(name)) throw new Error(`norn: icons: ${match} names the icon ${quoted(name)}, which is not a lowercase kebab name. Rename the file, or use a record.`);
+				add(name, match, file, false);
+			}
+		}
+	} else if (isObject(option)) {
+		for (const [name, value] of Object.entries(option)) {
+			const { src, mirror } = entry(name, value);
+			const file = path.resolve(root, src);
+			if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`norn: icons: ${quoted(name)} points at ${src}, which is not a file.`);
+			add(name, src, file, mirror);
+		}
+	} else {
+		throw new Error("norn: `icons` must be a glob, a list of globs, or a record of icon names to SVG files.");
+	}
+
+	return Object.fromEntries(
+		[...found].map(([name, { src, file, mirror }]) => {
+			const { viewBox, body } = parse(fs.readFileSync(file, "utf8"), src);
+			return [name, { viewBox, body: scopeIds(body, name), mirror }];
+		}),
+	);
+}

package/lib/npm.js

@@ -0,0 +1,49 @@
+/*
+ * SPDX-License-Identifier: MPL-2.0
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import fs from "node:fs";
+
+/** How long a registry answer is reused. */
+const CACHE_MS = 60 * 60 * 1000;
+
+/** Registry answers by package name: `{ at, released }`. */
+const cache = new Map();
+
+/**
+ * Whether the package has a release on npm: a `latest` dist-tag. A missing package, a private one, or no network counts as no release.
+ *
+ * @param {string | null | undefined} packageName
+ * @param {{ fetch?: typeof globalThis.fetch, now?: () => number }} [options] - A fetch to use instead of the global one, and a clock, for tests
+ * @returns {Promise<boolean>}
+ */
+export async function npmRelease(packageName, { fetch = globalThis.fetch, now = Date.now } = {}) {
+	if (!packageName || typeof fetch !== "function") return false;
+	const hit = cache.get(packageName);
+	if (hit && now() - hit.at < CACHE_MS) return hit.released;
+	let released;
+	try {
+		// The abbreviated document still has `dist-tags`, without the metadata of every version.
+		const response = await fetch(`https://registry.npmjs.org/${packageName.replace("/", "%2F")}`, { signal: AbortSignal.timeout(5000), headers: { accept: "application/vnd.npm.install-v1+json" } });
+		released = response.ok && typeof (await response.json())?.["dist-tags"]?.latest === "string";
+	} catch {
+		released = false;
+	}
+	cache.set(packageName, { at: now(), released });
+	return released;
+}
+
+/**
+ * The project accent as six hex digits, for the badge color: the first `--norn-ui-accent: #rrggbb` in a stylesheet.
+ *
+ * @param {string} cssPath
+ * @returns {string | null} Null when the file or the declaration is missing
+ */
+export function accentHex(cssPath) {
+	if (!fs.existsSync(cssPath)) return null;
+	const match = fs.readFileSync(cssPath, "utf8").match(/--norn-ui-accent:\s*#([0-9a-f]{6})\b/i);
+	return match ? match[1].toLowerCase() : null;
+}

package/lib/optional.js

@@ -0,0 +1,25 @@
+/*
+ * SPDX-License-Identifier: MPL-2.0
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+/**
+ * Whether an optional peer package is installed. Only a package that cannot be found counts as absent.
+ * A package that is installed but fails to load, because one of its own dependencies is missing, is not absent: the caller imports it next and that error is thrown.
+ * Matching the error message instead would not tell the two apart, since Node names the importing file in it, and that path holds the peer's name.
+ *
+ * @param {string} specifier - A bare package name, such as `@allons-y/webc-code-sample`
+ * @returns {boolean}
+ * @throws {Error} Any resolution failure other than the package not being found
+ */
+export function isInstalled(specifier) {
+	try {
+		import.meta.resolve(specifier);
+		return true;
+	} catch (error) {
+		if (error?.code === "ERR_MODULE_NOT_FOUND") return false;
+		throw error;
+	}
+}

package/lib/site.js

@@ -0,0 +1,87 @@
+/*
+ * SPDX-License-Identifier: MPL-2.0
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import hostedGitInfo from "hosted-git-info";
+import { minVersion, validRange } from "semver";
+
+/** Where a project may keep its own policy files, in the order they are looked for. */
+const POLICY_DIRS = ["", ".github", "docs"];
+
+/** @param {string} file */
+const readJson = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+
+/** Lowest major in an engines range, as `24+`; null when unbounded. */
+function minimumVersion(range) {
+	if (!validRange(range)) return null;
+	const { major } = minVersion(range);
+	return major ? `${major}+` : null;
+}
+
+/** First sentence, minus the period. */
+const firstSentence = (text) => text.split(/(?<=\.)\s/)[0].replace(/\.$/, "");
+
+/**
+ * The URL of a policy file the project keeps, or null.
+ *
+ * @param {string} root - The project root
+ * @param {(file: string) => string} link - The URL of a file in the repository
+ * @param {string} name - A file name, such as `SECURITY.md`
+ * @returns {string | null}
+ */
+function policyUrl(root, link, name) {
+	const found = POLICY_DIRS.map((dir) => path.posix.join(dir, name)).find((file) => fs.existsSync(path.join(root, ...file.split("/"))));
+	return found ? link(found) : null;
+}
+
+/**
+ * Site facts from the project's `package.json` and `project.json`, for a project's mapping to the layout props.
+ *
+ * @param {{ packagePath: string, projectPath?: string, host?: string }} options - The two files, and a host that serves the site at one path per repository, such as `https://example.github.io`, for the URL when `project.json` sets none
+ * @returns {Record<string, string | null>} The site facts
+ * @throws {Error} When the package has no name, license, description, or repository, or its repository is not a hosted Git URL
+ */
+export function buildSite({ packagePath, projectPath, host }) {
+	const pkg = readJson(packagePath);
+	const project = projectPath && fs.existsSync(projectPath) ? readJson(projectPath) : {};
+	for (const key of ["name", "license", "description"]) {
+		if (typeof pkg[key] !== "string" || !pkg[key]) {
+			throw new Error(`${packagePath} has no \`${key}\`. The site's facts are resolved from it: set it there.`);
+		}
+	}
+	const raw = typeof pkg.repository === "string" ? pkg.repository : pkg.repository?.url;
+	if (!raw) throw new Error(`${packagePath} has no \`repository\`. The site's links are resolved from it.`);
+	const info = hostedGitInfo.fromUrl(raw);
+	if (!info) throw new Error(`${packagePath} has a \`repository\` that is not a hosted Git URL: ${raw}`);
+
+	const repo = info.browse();
+	const repoName = repo.split("/").pop();
+	const root = path.dirname(packagePath);
+	/** A file on the default branch, in the URL form its host uses: GitHub's `blob/main/…` is Bitbucket's `src/main/…`. */
+	const link = (file) => info.browseFile(file, { committish: "main" });
+
+	return {
+		name: pkg.name.split("/").pop(),
+		packageName: pkg.name,
+		tagline: project.tagline ?? firstSentence(pkg.description),
+		description: pkg.description,
+		license: pkg.license,
+		licenseUrl: link("LICENSE"),
+		repo,
+		repoName,
+		npm: pkg.private ? null : `https://www.npmjs.com/package/${pkg.name}`,
+		node: minimumVersion(pkg.engines?.node),
+		url: project.url ? project.url.replace(/\/?$/, "/") : host ? `${host.replace(/\/$/, "")}/${repoName}/` : null,
+		issuesUrl: pkg.bugs?.url ?? `${repo}/issues`,
+		contributingUrl: link(".github/CONTRIBUTING.md"),
+		changelogUrl: link("CHANGELOG.md"),
+		conductUrl: policyUrl(root, link, "CODE_OF_CONDUCT.md"),
+		securityUrl: policyUrl(root, link, "SECURITY.md"),
+	};
+}

package/lib/workspaces.js

@@ -0,0 +1,71 @@
+/*
+ * SPDX-License-Identifier: MPL-2.0
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import markdownIt from "markdown-it";
+
+import { callouts, headingAnchors, scrollTables, webcTags } from "../markdown.js";
+import { isInstalled } from "./optional.js";
+
+/** The code sample's Markdown add-on, when `@allons-y/webc-code-sample` is installed: fences render as `norn-code-block`. Without it they stay `<pre><code>`. */
+const highlightFences = isInstalled("@allons-y/webc-code-sample") ? (await import("@allons-y/webc-code-sample/markdown")).highlightFences : null;
+
+/** @param {string} file */
+const read = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+
+/** Manifests matched by workspace patterns, relative to the root. */
+const manifests = (root, patterns) =>
+	fs.globSync(
+		patterns.map((pattern) => `${pattern}/package.json`),
+		{ cwd: root, exclude: (name) => name === "node_modules" },
+	);
+
+/** Front matter and the first heading come off: the page has its own title. Windows line endings count as the same. */
+const body = (text) => text.replace(/\r\n?/g, "\n").replace(/^---\n[\s\S]*?\n---\n/, "").replace(/^\s*# .*\n/, "");
+
+/**
+ * One entry per workspace of the repository: its package.json and its page,
+ * the workspace's SKILL.md or else its README.md, rendered with the site's Markdown add-ons: anchored headings, callouts, tables, fences, and component tags.
+ * Its raw HTML renders as HTML, as on GitHub. Nothing is sanitized: the README is the project's own, and `norn-workspace` compiles it as WebC.
+ *
+ * @param {{ root: string }} options - The project root, where the `workspaces` field lives
+ * @returns {{ name: string, title: string, description?: string, slug: string, href: string, html: string }[]} Each an item, `href`, `title`, and `description`, with the package `name`, its `slug`, and its page `html`
+ */
+export function buildWorkspaces({ root }) {
+	// HTML on, as on GitHub and in Eleventy: the README is the project's own, as trusted as its pages. `norn-workspace` compiles it as WebC, and nothing is sanitized.
+	const md = markdownIt({ html: true });
+	webcTags(md);
+	highlightFences?.(md);
+	scrollTables(md);
+	callouts(md);
+	headingAnchors(md);
+	const { workspaces = [] } = read(path.join(root, "package.json"));
+	const patterns = Array.isArray(workspaces) ? workspaces : (workspaces.packages ?? []);
+	const excluded = new Set(manifests(root, patterns.filter((pattern) => pattern.startsWith("!")).map((pattern) => pattern.slice(1))));
+	return manifests(
+		root,
+		patterns.filter((pattern) => !pattern.startsWith("!")),
+	)
+		.filter((file) => !excluded.has(file))
+		.sort()
+		.map((file) => {
+			const pkg = read(path.join(root, file));
+			const dir = path.join(root, path.dirname(file));
+			const source = ["SKILL.md", "README.md"].map((name) => path.join(dir, name)).find(fs.existsSync);
+			const slug = pkg.name.split("/").pop();
+			return {
+				name: pkg.name,
+				title: pkg.name,
+				description: pkg.description,
+				slug,
+				href: `/${slug}/`,
+				html: source ? md.render(body(fs.readFileSync(source, "utf8"))) : "",
+			};
+		});
+}