@apleasantview/eleventy-plugin-baseline 0.1.0-next.33 → 0.1.0-next.40

package/modules/assets/processors/esbuild-process.js

@@ -0,0 +1,68 @@
+import * as esbuild from 'esbuild';
+import { createLogger } from '../../../core/logging.js';
+
+/**
+ * esbuild processor (processor)
+ *
+ * Bundles a single JS entrypoint with esbuild and returns the text. Used
+ * both by the `js` template format compile guard and by the
+ * `inlineESbuild` filter in the assets module.
+ *
+ * Architecture layer:
+ *   module
+ *
+ * System role:
+ *   Stateless bundler called by `modules/assets/index.js`. The compile
+ *   guard decides which files reach this processor; this file owns the
+ *   esbuild call itself.
+ *
+ * Lifecycle:
+ *   build-time → invoked per matching entrypoint during template compile,
+ *                or per-call from the inline filter
+ *
+ * Why this exists:
+ *   Eleventy treats every `.js` file as a template. A dedicated processor
+ *   keeps esbuild configuration out of the template format wiring and lets
+ *   the inline filter reuse the same defaults.
+ *
+ * Scope:
+ *   Owns esbuild option defaults and the bundle call. Does not own the
+ *   compile guard, the watch target, or markup wrapping; the assets
+ *   module owns those.
+ *
+ * Data flow:
+ *   entrypoint path + options → esbuild.build → bundled JS text
+ */
+
+const log = createLogger('assets-esbuild');
+const defaultOptions = { minify: true, target: 'es2020' };
+
+/**
+ * Bundle a JS file with esbuild.
+ *
+ * @param {string} jsFilePath - Absolute path to the entry file.
+ * @param {Object} [options] - esbuild options (merged with defaults).
+ * @param {boolean} [options.minify=true] - Minify output.
+ * @param {string} [options.target='es2020'] - esbuild target.
+ * @returns {Promise<string>} Bundled JS text, or an error comment on failure.
+ */
+export default async function assetsESbuild(jsFilePath, options = {}) {
+	const userOptions = { ...defaultOptions, ...options };
+
+	try {
+		let result = await esbuild.build({
+			entryPoints: [jsFilePath],
+			bundle: true,
+			minify: userOptions.minify,
+			target: userOptions.target,
+			write: false
+		});
+
+		// Return raw JS; markup wrapping is handled by the plugin registration.
+		return result.outputFiles[0].text;
+	} catch (error) {
+		log.error('esbuild failed:', error);
+		// Surface a safe JS comment so the caller can decide how to wrap it.
+		return '/* Error processing JS */';
+	}
+}

package/modules/{assets-postcss/process.js → assets/processors/postcss-process.js}

@@ -1,7 +1,44 @@
 import fs from 'fs/promises';
 import postcss from 'postcss';
 import loadPostCSSConfig from 'postcss-load-config';
-import fallbackPostCSSConfig from './fallback/postcss.config.js';
+import fallbackPostCSSConfig from '../configs/postcss.config.js';
+import { createLogger } from '../../../core/logging.js';
+
+/**
+ * PostCSS processor (processor)
+ *
+ * Processes a single CSS entrypoint through PostCSS and returns the text.
+ * Used both by the `css` template format compile guard and by the
+ * `inlinePostCSS` filter in the assets module.
+ *
+ * Architecture layer:
+ *   module
+ *
+ * System role:
+ *   Stateless processor called by `modules/assets/index.js`. Resolves the
+ *   user's PostCSS config from the project root, falling back to the
+ *   bundled Baseline config when none is found. Cached for the lifetime
+ *   of the process.
+ *
+ * Lifecycle:
+ *   build-time → invoked per matching entrypoint during template compile,
+ *                or per-call from the inline filter
+ *
+ * Why this exists:
+ *   Eleventy has no PostCSS hook of its own. A dedicated processor lets
+ *   user configs win when present and keeps the bundled fallback out of
+ *   the consumer's `node_modules` resolution path.
+ *
+ * Scope:
+ *   Owns config resolution, caching, and the PostCSS call. Does not own
+ *   the compile guard, the watch target, or markup wrapping; the assets
+ *   module owns those.
+ *
+ * Data flow:
+ *   entrypoint path → PostCSS pipeline → processed CSS text
+ */
+
+const log = createLogger('assets-postcss');
 
 // Resolve user PostCSS config from the project root (cwd), not the Eleventy input dir.
 const configRoot = process.cwd();
@@ -42,7 +79,7 @@ export default async function assetsPostCSS(cssFilePath) {
 		// Return raw CSS; markup wrapping is handled in the plugin registration.
 		return result.css;
 	} catch (error) {
-		console.error(error);
+		log.error('PostCSS failed:', error);
 		// Surface a safe CSS string so the caller can decide how to wrap it.
 		return '/* Error processing CSS */';
 	}

package/modules/assets/schema.js

@@ -0,0 +1,14 @@
+import * as z from 'zod';
+
+// Structural schema for the `options.assets` slice. Permissive on unknown
+// keys (esbuild accepts many options we don't touch); strict on the keys the
+// plugin itself reads.
+
+export const esbuildOptionsSchema = z.looseObject({
+	minify: z.boolean().optional(),
+	target: z.string().optional()
+});
+
+export const optionsSchema = z.looseObject({
+	esbuild: esbuildOptionsSchema.optional()
+});

package/modules/head/drivers/capo-adapter.js

@@ -0,0 +1,94 @@
+/**
+ * Capo PostHTML adapter (driver)
+ *
+ * Implements the `HTMLAdapter` interface capo.js v2 expects, against
+ * PostHTML's `{ tag, attrs, content }` node shape. Only `getWeight` is
+ * exercised downstream; the rest are shimmed to satisfy the contract.
+ *
+ * Architecture layer:
+ *   module
+ *
+ * System role:
+ *   Translation shim between the head driver's PostHTML tree and the
+ *   capo.js sort. Used by `posthtml-head-elements.js` when ordering the
+ *   composed `<head>` element list.
+ *
+ * Lifecycle:
+ *   transform-time → invoked per node while capo.js scores element weights
+ *
+ * Why this exists:
+ *   capo.js is DOM-shaped; PostHTML is not. Without an adapter the driver
+ *   would have to walk the tree twice or hand-roll element weighting.
+ *
+ * Scope:
+ *   Owns attribute lookup, tag name resolution, and text extraction over
+ *   PostHTML nodes. Does not own weighting logic; capo.js owns that.
+ *
+ * Data flow:
+ *   PostHTML node → adapter accessor → capo.js getWeight
+ *
+ * A PostHTML element node looks like `{ tag, attrs, content }` where attrs
+ * is either undefined or a plain object. Boolean attributes appear with an
+ * empty-string value (`{ async: '' }`) or as `true`.
+ */
+
+const hasAttr = (node, name) => {
+	if (!node || !node.attrs) return false;
+	const key = name.toLowerCase();
+	for (const k of Object.keys(node.attrs)) {
+		if (k.toLowerCase() === key) return true;
+	}
+	return false;
+};
+
+const getAttr = (node, name) => {
+	if (!node || !node.attrs) return null;
+	const key = name.toLowerCase();
+	for (const k of Object.keys(node.attrs)) {
+		if (k.toLowerCase() === key) {
+			const v = node.attrs[k];
+			return v === true ? '' : v == null ? null : String(v);
+		}
+	}
+	return null;
+};
+
+const getText = (node) => {
+	if (!node || node.content == null) return '';
+	if (typeof node.content === 'string') return node.content;
+	if (Array.isArray(node.content)) return node.content.filter((c) => typeof c === 'string').join('');
+	return '';
+};
+
+export const capoPosthtmlAdapter = {
+	isElement(node) {
+		return !!(node && typeof node === 'object' && typeof node.tag === 'string');
+	},
+	getTagName(node) {
+		return node && typeof node.tag === 'string' ? node.tag.toLowerCase() : '';
+	},
+	getAttribute(node, name) {
+		return getAttr(node, name);
+	},
+	hasAttribute(node, name) {
+		return hasAttr(node, name);
+	},
+	getAttributeNames(node) {
+		return node && node.attrs ? Object.keys(node.attrs) : [];
+	},
+	getTextContent(node) {
+		return getText(node);
+	},
+	getChildren() {
+		return [];
+	},
+	getParent() {
+		return null;
+	},
+	getSiblings() {
+		return [];
+	},
+	stringify(node) {
+		return node && node.tag ? `<${node.tag}>` : '';
+	}
+};

package/modules/head/drivers/posthtml-head-elements.js

@@ -0,0 +1,140 @@
+import { getWeight, ElementWeights } from '@rviscomi/capo.js';
+import { capoPosthtmlAdapter as adapter } from './capo-adapter.js';
+import { dedupeMeta, dedupeLink } from '../utils/dedupe.js';
+
+/**
+ * PostHTML head driver (driver)
+ *
+ * Default head renderer. Emits standard meta tags, layers user extras and
+ * hreflang alternates on top, dedupes, capo-sorts, and replaces the
+ * <baseline-head> placeholder with the result.
+ *
+ * Architecture layer:
+ *   module
+ *
+ * System role:
+ *   The seam between head's pipeline and the renderer choice. Alternate
+ *   drivers can be substituted at the import site without changing the
+ *   cascade-time seed builder.
+ *
+ * Lifecycle:
+ *   transform-time → emit, dedupe, sort, mutate the PostHTML tree
+ *
+ * Why this exists:
+ *   Splitting the renderer from the seed builder lets head swap rendering
+ *   strategies (e.g. a future direct-DOM driver) without touching cascade
+ *   wiring or the page-context shape.
+ *
+ * Scope:
+ *   Owns node emission, dedupe orchestration, capo sort, and placeholder
+ *   replacement.
+ *   Does not own seed shape (page context), hreflang building
+ *   (head/utils/alternates.js), or capo's element weights (capo.js).
+ *
+ * Data flow:
+ *   seeds + alternates + options → emit → dedupe → capo-sort → PostHTML
+ *   tree mutation
+ *
+ * @param {Object} args
+ * @param {Object} args.seeds - Page context for the current page.
+ * @param {Array<Object>} args.alternates - hreflang link descriptors.
+ * @param {Object} args.options - Head options (titleSeparator, showGenerator).
+ * @param {string} args.placeholderTag - Placeholder element to replace.
+ * @param {string} args.eol - End-of-line separator interleaved between nodes.
+ * @param {Object} args.log - Scoped logger.
+ * @returns {(tree: Object) => Object} PostHTML plugin function.
+ */
+export function renderHead({ seeds, alternates, options, placeholderTag, eol, log }) {
+	const defaults = emitMeta(seeds.meta, seeds.render, options);
+	const extras = emitExtras(seeds.head, alternates);
+
+	const deduped = dedupeAll([...defaults, ...extras]);
+	const sorted = capoSort(deduped);
+
+	return function rendererPlugin(tree) {
+		// log.info('injecting head for', seeds.page.inputPath || seeds.page.url);
+		tree.match({ tag: placeholderTag }, () => ({
+			tag: 'head',
+			content: interleaveEOL(sorted, eol)
+		}));
+		return tree;
+	};
+}
+
+function emitMeta(meta, render, options) {
+	const nodes = [];
+	nodes.push(mkMeta({ charset: 'UTF-8' }));
+	nodes.push(mkMeta({ name: 'viewport', content: 'width=device-width, initial-scale=1.0' }));
+	if (meta.title) nodes.push({ tag: 'title', content: [meta.title] });
+	if (meta.description) nodes.push(mkMeta({ name: 'description', content: meta.description }));
+	nodes.push(mkMeta({ name: 'robots', content: meta.robots }));
+	if (meta.canonical) nodes.push(mkLink({ rel: 'canonical', href: meta.canonical }));
+	if (options.showGenerator && render.generator) {
+		nodes.push(mkMeta({ name: 'generator', content: render.generator }));
+	}
+
+	return nodes;
+}
+
+function emitExtras(head, alternates = []) {
+	const nodes = [];
+	for (const m of asArray(head?.meta)) nodes.push(mkMeta(m));
+	for (const l of asArray(head?.link)) {
+		if (l?.rel === 'canonical') continue; // 🚨 remove duplication source
+		nodes.push(mkLink(l));
+	}
+	for (const s of asArray(head?.script)) nodes.push(mkScript(s));
+	for (const s of asArray(head?.style)) nodes.push(mkStyle(s));
+	for (const a of alternates) nodes.push(mkLink(a));
+
+	return nodes;
+}
+
+function dedupeAll(nodes) {
+	const metas = [];
+	const links = [];
+	const others = [];
+	for (const n of nodes) {
+		if (n.tag === 'meta') metas.push(n.attrs || {});
+		else if (n.tag === 'link') links.push(n.attrs || {});
+		else others.push(n);
+	}
+	const dedupedMetas = dedupeMeta(metas).map(mkMeta);
+	const dedupedLinks = dedupeLink(links).map(mkLink);
+
+	return [...dedupedMetas, ...dedupedLinks, ...others];
+}
+
+function capoSort(nodes) {
+	const weighted = nodes.map((node, i) => ({
+		node,
+		i,
+		weight: adapter.isElement(node) ? getWeight(node, adapter) : ElementWeights.OTHER
+	}));
+	weighted.sort((a, b) => b.weight - a.weight || a.i - b.i);
+
+	return weighted.map((w) => w.node);
+}
+
+function mkMeta(attrs) {
+	return { tag: 'meta', attrs };
+}
+function mkLink(attrs) {
+	return { tag: 'link', attrs };
+}
+function mkScript(entry) {
+	const { content, ...attrs } = entry || {};
+	return content !== undefined ? { tag: 'script', attrs, content: [content] } : { tag: 'script', attrs };
+}
+function mkStyle(entry) {
+	const { content, ...attrs } = entry || {};
+	return content !== undefined ? { tag: 'style', attrs, content: [content] } : { tag: 'style', attrs };
+}
+function asArray(v) {
+	return Array.isArray(v) ? v : [];
+}
+function interleaveEOL(nodes, eol) {
+	const out = [];
+	for (const n of nodes) out.push(n, eol);
+	return out;
+}

package/modules/head/index.js

@@ -0,0 +1,106 @@
+import { renderHead } from './drivers/posthtml-head-elements.js';
+import { buildAlternates } from './utils/alternates.js';
+import { optionsSchema } from './schema.js';
+
+// Internal constants — not user-facing.
+const PLACEHOLDER_TAG = 'baseline-head';
+const EOL = '\n';
+
+/**
+ * Head (module)
+ *
+ * Render-time <head> composer. Turns the normalised page context into a
+ * sorted, deduped element list and replaces <baseline-head> in the output.
+ *
+ * Architecture layer:
+ *   module
+ *
+ * System role:
+ *   Consumes the page context (built at cascade-time) and the translation
+ *   map (written at cascade-time) to produce the final <head> at
+ *   transform-time.
+ *
+ * Lifecycle:
+ *   cascade-time   → upstream page-context registry builds the per-page seeds
+ *   transform-time → PostHTML plugin reads seeds, emits nodes, capo-sorts,
+ *                    replaces <baseline-head>
+ *
+ * Why this exists:
+ *   Eleventy's htmlTransformer context exposes only page metadata, not the
+ *   full data cascade. Pre-built seeds in the page-context registry carry
+ *   every field the composer needs from cascade-time into transform-time.
+ *
+ * Scope:
+ *   Owns transform-time composition and placeholder replacement.
+ *   Pass 1 covers bucket 1 only: charset, viewport, title, description,
+ *   robots, canonical, optional generator, plus user extras from
+ *   settings.head and hreflang alternates. SEO and JSON-LD are later passes.
+ *   Does not own seed shape (page context) or driver internals.
+ *
+ * Data flow:
+ *   page context + translation-map store + settings.head → driver →
+ *   PostHTML tree mutation (replaces <baseline-head>)
+ *
+ * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
+ * @param {Object} moduleContext
+ */
+export function headCore(eleventyConfig, moduleContext) {
+	const { state, runtime, log } = moduleContext;
+	const { settings, options } = state;
+
+	// Structural-only options check: log on mismatch, do not throw.
+	const parsed = optionsSchema.safeParse(options.head);
+	if (!parsed.success) {
+		for (const issue of parsed.error.issues) {
+			log.info('options:', `${issue.path.join('.')} — ${issue.message}`);
+		}
+	}
+
+	const pageContextRegistry = moduleContext.resolvePageContext;
+
+	// Resolved plugin options with defaults.
+	const headOptions = {
+		titleSeparator: options.head?.titleSeparator ?? ' – ',
+		showGenerator: options.head?.showGenerator ?? false
+	};
+
+	// Per-build stats (cleared on eleventy.after for watch-mode reruns).
+	const headStats = { pages: new Set() };
+
+	eleventyConfig.on('eleventy.after', () => {
+		log.info({
+			message: 'Head injection summary',
+			totalPages: headStats.pages.size,
+			sample: Array.from(headStats.pages).slice(0, 10)
+		});
+		headStats.pages.clear();
+	});
+
+	// --- Transform-time: compose and inject. ---
+	log.info('Injecting heads to pages');
+	eleventyConfig.htmlTransformer.addPosthtmlPlugin('html', function (context) {
+		headStats.pages.add(context?.page?.inputPath || context?.outputPath);
+
+		const key = context?.page?.url ?? context?.page?.inputPath;
+		const seeds = pageContextRegistry?.getByKey(key);
+		if (!seeds) {
+			log.warn('no head seeds for', context?.page?.inputPath || context?.outputPath);
+			return (tree) => tree;
+		}
+
+		const translationKey = seeds.page?.locale?.translationKey;
+
+		const alternates = translationKey
+			? buildAlternates(seeds.page?.locale?.translationKey, runtime.translationMap.get(), seeds.site?.url)
+			: [];
+
+		return renderHead({
+			seeds,
+			alternates,
+			options: headOptions,
+			placeholderTag: PLACEHOLDER_TAG,
+			eol: EOL,
+			log
+		});
+	});
+}

package/modules/head/schema.js

@@ -0,0 +1,42 @@
+import * as z from 'zod';
+
+// Structural schemas for head-core. Permissive on unknown keys, typed on
+// keys the driver reads. Non-throwing at the call site — safeParse only.
+
+// `options.head` slice: render-behaviour knobs.
+export const optionsSchema = z.looseObject({
+	titleSeparator: z.string().optional(),
+	showGenerator: z.boolean().optional()
+});
+
+// `settings.head` extras slot: additive link/script/meta/style arrays.
+export const settingsHeadSchema = z.looseObject({
+	link: z.array(z.looseObject({})).optional(),
+	script: z.array(z.looseObject({})).optional(),
+	meta: z.array(z.looseObject({})).optional(),
+	style: z.array(z.looseObject({})).optional()
+});
+
+// `settings.seo` site-default SEO scalars, page-overridable.
+export const settingsSeoSchema = z.looseObject({
+	ogImage: z.string().optional(),
+	twitterSite: z.string().optional()
+});
+
+// Page-level `seo:` block. Same scalar set as bare front matter, namespaced.
+// `seo.foo` wins over bare `foo`.
+export const pageSeoSchema = z.looseObject({
+	title: z.string().optional(),
+	description: z.string().optional(),
+	noindex: z.boolean().optional(),
+	canonical: z.string().optional(),
+	ogTitle: z.string().optional(),
+	ogDescription: z.string().optional(),
+	ogType: z.string().optional(),
+	ogImage: z.string().optional(),
+	twitterCard: z.string().optional(),
+	twitterSite: z.string().optional(),
+	twitterTitle: z.string().optional(),
+	twitterDescription: z.string().optional(),
+	twitterImage: z.string().optional()
+});

package/modules/head/utils/alternates.js

@@ -0,0 +1,11 @@
+export function buildAlternates(translationKey, translationsMap, siteUrl) {
+	if (!translationKey || !translationsMap) return [];
+	const variants = translationsMap[translationKey];
+	if (!variants) return [];
+	return Object.values(variants).flatMap((entry) => {
+		if (!entry?.url) return [];
+		const href = siteUrl ? new URL(entry.url, siteUrl).href : entry.url;
+		const link = { rel: 'alternate', hreflang: entry.lang, href };
+		return entry.isDefaultLang ? [link, { ...link, hreflang: 'x-default' }] : [link];
+	});
+}

package/modules/head/utils/dedupe.js

@@ -0,0 +1,47 @@
+/**
+ * Deduplicate meta tags. Last-wins by key (charset, name, property, http-equiv).
+ * Preserves insertion order after dedup.
+ * @param {Array<Object>} [arr=[]] - Array of meta tag objects.
+ * @returns {Array<Object>}
+ */
+function metaKey(meta) {
+	if (meta.charset) return 'charset';
+	if (meta.name) return `name:${meta.name}`;
+	if (meta.property) return `prop:${meta.property}`;
+	if (meta['http-equiv']) return `http:${meta['http-equiv']}`;
+	return null;
+}
+
+export const dedupeMeta = (arr = []) => {
+	const seen = new Set();
+	const out = [];
+
+	for (let i = arr.length - 1; i >= 0; i--) {
+		const key = metaKey(arr[i]);
+		if (!key || seen.has(key)) continue;
+		seen.add(key);
+		out.push(arr[i]);
+	}
+
+	return out.reverse();
+};
+
+/**
+ * Deduplicate link tags by rel+hreflang+href. Last-wins, preserves insertion order.
+ * @param {Array<Object>} [links=[]] - Array of link tag objects.
+ * @returns {Array<Object>}
+ */
+export const dedupeLink = (links = []) => {
+	const seen = new Set();
+	const out = [];
+
+	for (let i = links.length - 1; i >= 0; i--) {
+		const link = links[i];
+		const key = link.rel && link.href ? `rel:${link.rel}|hreflang:${link.hreflang ?? ''}|${link.href}` : null;
+		if (!key || seen.has(key)) continue;
+		seen.add(key);
+		out.push(link);
+	}
+
+	return out.reverse();
+};