@apleasantview/eleventy-plugin-baseline 0.1.0-next.32 → 0.1.0-next.39

package/core/schema.js

@@ -0,0 +1,37 @@
+import * as z from 'zod';
+
+export const configSchema = z.object({
+	dir: z.object({
+		input: z.string().min(1),
+		output: z.string().min(1),
+		data: z.string().min(1),
+		includes: z.string().min(1),
+		assets: z.string().min(1),
+		public: z.string().min(1)
+	}),
+	htmlTemplateEngine: z.string().min(1),
+	markdownTemplateEngine: z.string().min(1),
+	templateFormats: z
+		.array(z.string().min(1))
+		.min(1)
+		.refine((templateFormats) => templateFormats.includes('njk'), {
+			error: 'Baseline requires njk in templateFormats'
+		})
+});
+
+export const settingsSchema = z.object({
+	title: z.string().optional(),
+	tagline: z.string().optional(),
+	url: z.string().optional(),
+	noindex: z.boolean().optional(),
+	defaultLanguage: z.string().optional(),
+	languages: z.record(z.string(), z.looseObject({})).optional(),
+	head: z
+		.object({
+			link: z.array(z.looseObject({})).optional(),
+			script: z.array(z.looseObject({})).optional(),
+			meta: z.array(z.looseObject({})).optional(),
+			style: z.array(z.looseObject({})).optional()
+		})
+		.optional()
+});

package/core/shortcodes/image.js

@@ -1,144 +1,167 @@
-import path from 'node:path';
-import Image from '@11ty/eleventy-img';
-
-const DEFAULT_WIDTHS = [320, 640, 960, 1280, 1920, 'auto'];
-const DEFAULT_FORMATS = ['avif', 'webp'];
-const DEFAULT_SIZES = '(max-width: 768px) 100vw, 768px';
-
-function pickRenditions(metadata) {
-	// Use the first available format; first entry is smallest, last is largest.
-	const firstFormat = Object.values(metadata)[0];
-	const lowsrc = firstFormat?.[0];
-	const highsrc = firstFormat?.[firstFormat.length - 1];
-	return { lowsrc, highsrc };
-}
-
-/**
- * Responsive image shortcode using @11ty/eleventy-img.
- *
- * @param {Object} options
- * @param {string} options.src                          Required image source (local or remote).
- * @param {string} options.alt                          Required alt text (empty string allowed for decorative).
- * @param {string} [options.caption=""]                 Optional caption; enables figure wrapper when non-empty.
- * @param {("lazy"|"eager")} [options.loading="lazy"]   Loading behavior.
- * @param {string} [options.containerClass=""]          Class applied to <picture>.
- * @param {string} [options.imageClass=""]              Class applied to <img>.
- * @param {Array<number|string>} [options.widths=DEFAULT_WIDTHS]   Widths passed to eleventy-img.
- * @param {string} [options.sizes=DEFAULT_SIZES]        Sizes attribute used on sources.
- * @param {string[]} [options.formats=DEFAULT_FORMATS]  Output formats (order matters).
- * @param {string} [options.outputDir]                  Output directory for generated assets.
- * @param {string} [options.urlPath="/media/"]          Public URL base for generated assets.
- * @param {Object} [options.attrs={}]                   Extra attributes applied to <img>; `class` merges with imageClass.
- * @param {string} [options.style]                      Inline style applied to <img> (alias for attrs.style).
- * @param {boolean} [options.figure=true]               Wrap in <figure> when caption is provided.
- * @param {boolean} [options.setDimensions=true]        When false, omit width/height on <img>.
- */
-export async function imageShortcode(options = {}) {
-	const outputBase = this?.eleventy?.directories?.output || 'dist';
-	const {
-		src,
-		alt,
-		caption = '',
-		loading = 'lazy',
-		containerClass = '',
-		imageClass = '',
-		style,
-		widths = DEFAULT_WIDTHS,
-		sizes = DEFAULT_SIZES,
-		formats = DEFAULT_FORMATS,
-		outputDir = path.join('.', outputBase, 'media'),
-		urlPath = '/media/',
-		attrs = {},
-		figure = true,
-		setDimensions = true
-	} = options;
-	const hasImageTransformPlugin = this.ctx._baseline.hasImageTransformPlugin;
-
-	if (!src) throw new Error('imageShortcode: src is required');
-	if (alt === undefined) {
-		throw new Error('imageShortcode: alt is required (use empty string for decorative images)');
-	}
-
-	const normalizedCaption = caption == null ? '' : String(caption);
-	const normalizedAlt = alt == null ? '' : String(alt);
-
-	const inputDir = this?.eleventy?.directories?.input;
-	const isRemote = /^https?:\/\//i.test(src);
-	const resolvedSrc = !isRemote && inputDir ? path.join(inputDir, src.replace(/^\//, '')) : src;
-
-	let metadata;
-	try {
-		metadata = await Image(resolvedSrc, {
-			transformOnRequest: process.env.ELEVENTY_RUN_MODE === 'serve',
-			widths: [...widths],
-			formats: [...formats],
-			outputDir,
-			urlPath,
-			filenameFormat(id, srcPath, width, format) {
-				const extension = path.extname(srcPath);
-				const name = path.basename(srcPath, extension);
-				return `${name}-${width}w.${format}`;
-			}
-		});
-	} catch (error) {
-		console.warn(`imageShortcode: transformOnRequest failed for ${src}.\n > ${error?.message || error}`);
-		metadata = await Image(resolvedSrc, {
-			widths: [...widths],
-			formats: [...formats],
-			outputDir,
-			urlPath,
-			filenameFormat(id, srcPath, width, format) {
-				const extension = path.extname(srcPath);
-				const name = path.basename(srcPath, extension);
-				return `${name}-${width}w.${format}`;
-			}
-		});
-	}
-
-	const { lowsrc, highsrc } = pickRenditions(metadata);
-	if (!lowsrc || !highsrc) {
-		throw new Error(`imageShortcode: no renditions produced for ${src}`);
-	}
-
-	const sourceTags = Object.values(metadata)
-		.map((formatEntries) => {
-			const type = formatEntries[0].sourceType;
-			const srcset = formatEntries.map((entry) => entry.srcset).join(', ');
-			return `<source type="${type}" srcset="${srcset}" sizes="${sizes}">`;
-		})
-		.join('\n');
-
-	const { class: attrClass, ...restAttrs } = attrs;
-	const combinedClass = [imageClass, attrClass].filter(Boolean).join(' ').trim() || undefined;
-
-	const imageAttributes = {
-		src: lowsrc.url,
-		alt: normalizedAlt,
-		loading,
-		decoding: loading === 'eager' ? 'sync' : 'async',
-		class: combinedClass,
-		style,
-		...(setDimensions ? { width: highsrc.width, height: highsrc.height } : {}),
-		...restAttrs,
-		...(hasImageTransformPlugin ? { 'eleventy:ignore': true } : {})
-	};
-
-	const imgAttrString = Object.entries(imageAttributes)
-		.filter(([, value]) => value !== undefined && value !== null && value !== '')
-		.map(([key, value]) => (value === true ? key : `${key}="${value}"`))
-		.join(' ');
-
-	const pictureClass = containerClass && containerClass.trim() ? ` class="${containerClass.trim()}"` : '';
-
-	const picture = `<picture${pictureClass}>
-	${sourceTags}
-	<img ${imgAttrString}>
-</picture>`;
-
-	if (!figure || !normalizedCaption) return picture;
-
-	return `<figure>
-	${picture}
-	<figcaption>${normalizedCaption}</figcaption>
-</figure>`;
-}
+import path from 'node:path';
+import Image from '@11ty/eleventy-img';
+import { createLogger } from '../logging.js';
+
+// Module-level logger. Image shortcode only uses `.warn`, which emits regardless
+// of verbose, so we don't thread verbose through the shortcode signature.
+const log = createLogger('image');
+
+const DEFAULT_WIDTHS = [320, 640, 960, 1280, 1920, 'auto'];
+const DEFAULT_FORMATS = ['avif', 'webp'];
+const DEFAULT_SIZES = '(max-width: 768px) 100vw, 768px';
+
+/**
+ * Pick the smallest and largest rendition from eleventy-img metadata.
+ * Uses the first available format; entries are ordered smallest → largest.
+ * @param {Object} metadata - eleventy-img metadata keyed by format.
+ * @returns {{lowsrc: Object, highsrc: Object}} Smallest and largest rendition.
+ */
+function pickRenditions(metadata) {
+	const firstFormat = Object.values(metadata)[0];
+	const lowsrc = firstFormat?.[0];
+	const highsrc = firstFormat?.[firstFormat.length - 1];
+	return { lowsrc, highsrc };
+}
+
+/**
+ * Responsive image shortcode using @11ty/eleventy-img.
+ *
+ * @param {Object} options
+ * @param {string} options.src                          Required image source (local or remote).
+ * @param {string} options.alt                          Required alt text (empty string allowed for decorative).
+ * @param {string} [options.caption=""]                 Optional caption; enables figure wrapper when non-empty.
+ * @param {("lazy"|"eager")} [options.loading="lazy"]   Loading behavior.
+ * @param {string} [options.containerClass=""]          Class applied to <picture>.
+ * @param {string} [options.imageClass=""]              Class applied to <img>.
+ * @param {Array<number|string>} [options.widths=DEFAULT_WIDTHS]   Widths passed to eleventy-img.
+ * @param {string} [options.sizes=DEFAULT_SIZES]        Sizes attribute used on sources.
+ * @param {string[]} [options.formats=DEFAULT_FORMATS]  Output formats (order matters).
+ * @param {string} [options.outputDir]                  Output directory for generated assets.
+ * @param {string} [options.urlPath="/media/"]          Public URL base for generated assets.
+ * @param {Object} [options.attrs={}]                   Extra attributes applied to <img>; `class` merges with imageClass.
+ * @param {string} [options.style]                      Inline style applied to <img>. Separate from attrs.style — if both are passed, attrs.style takes precedence via restAttrs spread.
+ * @param {boolean} [options.figure=true]               Wrap in <figure> when caption is provided.
+ * @param {boolean} [options.setDimensions=true]        When false, omit width/height on <img>.
+ */
+export async function imageShortcode(options = {}) {
+	const outputBase = this?.eleventy?.directories?.output || 'dist';
+	const {
+		src,
+		alt,
+		caption = '',
+		loading = 'lazy',
+		containerClass = '',
+		imageClass = '',
+		style,
+		widths = DEFAULT_WIDTHS,
+		sizes = DEFAULT_SIZES,
+		formats = DEFAULT_FORMATS,
+		outputDir = path.join('.', outputBase, 'media'),
+		urlPath = '/media/',
+		attrs = {},
+		figure = true,
+		setDimensions = true
+	} = options;
+	// Read from global data set during plugin init. When true, `eleventy:ignore`
+	// is added to the <img> (line 140) to prevent double-processing.
+	const hasImageTransformPlugin = this.ctx._baseline.features.hasImageTransformPlugin;
+
+	// --- Validation and normalization ---
+
+	if (!src) throw new Error(`imageShortcode: src is required (received ${JSON.stringify(src)})`);
+	if (alt == null) {
+		log.warn('alt is required (use empty string for decorative images)');
+	}
+
+	const normalizedCaption = String(caption);
+	const normalizedAlt = alt == null ? '' : String(alt);
+
+	const inputDir = this?.eleventy?.directories?.input;
+	const isRemote = /^https?:\/\//i.test(src);
+	// Note: remote URLs rely on eleventy-img's built-in fetch — no timeout/retry control at shortcode level.
+	const resolvedSrc = !isRemote && inputDir ? path.join(inputDir, src.replace(/^\//, '')) : src;
+
+	const imageOptions = {
+		widths: [...widths],
+		formats: [...formats],
+		outputDir,
+		urlPath,
+		filenameFormat(id, srcPath, width, format) {
+			const extension = path.extname(srcPath);
+			const name = path.basename(srcPath, extension);
+			return `${name}-${id.slice(0, 6)}-${width}w.${format}`;
+		}
+	};
+
+	// --- Image processing ---
+	// In serve mode, `transformOnRequest` defers processing to first browser request
+	// for faster dev startup. If it fails, retry without it — this is an edge case
+	// but one that has bitten in practice. In build mode, errors surface immediately.
+
+	let metadata;
+	try {
+		metadata = await Image(resolvedSrc, {
+			transformOnRequest: process.env.ELEVENTY_RUN_MODE === 'serve',
+			...imageOptions
+		});
+	} catch (error) {
+		if (process.env.ELEVENTY_RUN_MODE === 'serve') {
+			log.warn(`transformOnRequest failed for ${src}, retrying.\n > ${error?.message || error}`);
+			metadata = await Image(resolvedSrc, imageOptions);
+		} else {
+			throw error;
+		}
+	}
+
+	const { lowsrc, highsrc } = pickRenditions(metadata);
+	if (!lowsrc || !highsrc) {
+		throw new Error(`imageShortcode: no renditions produced for ${src}`);
+	}
+
+	// --- HTML assembly ---
+	// One <source> per format, each carrying the full srcset for that format.
+	const sourceTags = Object.values(metadata)
+		.map((formatEntries) => {
+			const type = formatEntries[0].sourceType;
+			const srcset = formatEntries.map((entry) => entry.srcset).join(', ');
+			return `<source type="${type}" srcset="${srcset}" sizes="${sizes}">`;
+		})
+		.join('\n');
+
+	// Pull `class` out of attrs so it can merge with imageClass. Remaining attrs
+	// and `eleventy:ignore` (if needed) are spread onto imageAttributes below.
+	const { class: attrClass, ...restAttrs } = attrs;
+	const combinedClass = [imageClass, attrClass].filter(Boolean).join(' ').trim() || undefined;
+
+	const imageAttributes = {
+		src: lowsrc.url,
+		alt: normalizedAlt,
+		loading,
+		decoding: loading === 'eager' ? 'sync' : 'async',
+		class: combinedClass,
+		style,
+		...(setDimensions ? { width: highsrc.width, height: highsrc.height } : {}),
+		...restAttrs,
+		...(hasImageTransformPlugin ? { 'eleventy:ignore': true } : {})
+	};
+
+	// Build the attribute string, dropping any empty/null values to keep output clean.
+	const imgAttrString = Object.entries(imageAttributes)
+		.filter(([, value]) => value !== undefined && value !== null && value !== '')
+		.map(([key, value]) => (value === true ? key : `${key}="${value}"`))
+		.join(' ');
+
+	const pictureClass = containerClass && containerClass.trim() ? ` class="${containerClass.trim()}"` : '';
+
+	const picture = `<picture${pictureClass}>
+${sourceTags}
+<img ${imgAttrString}>
+</picture>`;
+
+	if (!figure || !normalizedCaption) return picture;
+
+	return `<figure>
+${picture}
+<figcaption>${normalizedCaption}</figcaption>
+</figure>`;
+}

package/core/shortcodes/index.js

@@ -0,0 +1,2 @@
+// Shortcodes barrel.
+export { imageShortcode } from './image.js';

package/core/slug-index.js

@@ -0,0 +1,61 @@
+import { getScope, setEntry, getEntry } from './registry.js';
+
+const SCOPE_NAME = 'core:slug-index';
+
+/**
+ * Slug index (runtime substrate)
+ *
+ * Maps wikilink-friendly slugs to canonical page URLs. Populated by the
+ * page-context builder as each page resolves; read by the wikilinks
+ * markdown-it plugin during body render.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Forward-link index for the wikilinks plugin. In multilingual sites
+ *   only defaultLanguage pages register; the wikilinks plugin uses the
+ *   translation map to hop to other languages.
+ *
+ * Lifecycle:
+ *   cascade-time   → page-context registers slugs as templates compute
+ *   transform-time → wikilinks plugin resolves slugs during body render
+ *
+ * Why this exists:
+ *   Eleventy's data cascade resolves all eleventyComputed values before any
+ *   body renders, so the index is complete by the time wikilinks need it.
+ *   A dedicated scope keeps slug→url out of the page-context values map
+ *   (which holds url→pageContext).
+ *
+ * Scope:
+ *   Owns slug registration with collision detection and slug-keyed lookup.
+ *   Does not own slug derivation (page-context) or link rendering (wikilinks).
+ *
+ * Data flow:
+ *   page-context.buildPageContext → set() → registry scope → wikilinks getBySlug()
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @returns {{set: (slug: string, url: string, inputPath?: string) => void, getBySlug: (slug: string) => string | null, snapshot: () => Record<string, {url: string, inputPath?: string}>}}
+ */
+export function createSlugIndex(eleventyConfig) {
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+
+	return {
+		set(slug, url, inputPath) {
+			if (!slug || !url) return;
+			const existing = getEntry(scope, slug);
+			if (existing && existing.url !== url) {
+				throw new Error(
+					`Wikilink slug collision: "${slug}" used by both ${existing.inputPath ?? existing.url} and ${inputPath ?? url}`
+				);
+			}
+			setEntry(scope, slug, { url, inputPath });
+		},
+		getBySlug(slug) {
+			return getEntry(scope, slug)?.url ?? null;
+		},
+		snapshot() {
+			return Object.fromEntries(scope.values);
+		}
+	};
+}

package/core/translation-map-store.js

@@ -0,0 +1,46 @@
+import { getScope, setEntry, getEntry } from './registry.js';
+
+const SCOPE_NAME = 'core:translation-map-store';
+const KEY = 'translationMap';
+
+/**
+ * Translation map store (runtime substrate)
+ *
+ * Hand-off point for the translations map: written by multilang at
+ * cascade-time, read by head at transform-time.
+ *
+ * Architecture layer:
+ *   runtime substrate
+ *
+ * System role:
+ *   Bridge between the multilang module (writer) and the head module (reader).
+ *   The set/get pair lives in a registry scope rather than the data cascade
+ *   because head's PostHTML plugin runs outside the cascade.
+ *
+ * Lifecycle:
+ *   cascade-time   → multilang's translationsMap collection writes via set()
+ *   transform-time → head reads via get() to build hreflang alternates
+ *
+ * Why this exists:
+ *   The translations map is built inside an Eleventy collection, but head
+ *   needs it inside an htmlTransformer plugin where collections aren't
+ *   available.
+ *
+ * Scope:
+ *   Owns set/get on a per-config scope.
+ *   Does not own the map's shape, how it's built, or how head uses it.
+ *
+ * Data flow:
+ *   multilang translationsMap collection → set() → registry scope → head get()
+ *
+ * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
+ * @returns {{set: (map: object) => void, get: () => object | null}}
+ */
+export function createTranslationMapStore(eleventyConfig) {
+	const scope = getScope(eleventyConfig, SCOPE_NAME);
+
+	return {
+		set: (map) => setEntry(scope, KEY, map),
+		get: () => getEntry(scope, KEY) ?? null
+	};
+}

package/core/types.js

@@ -0,0 +1,73 @@
+/**
+ * Baseline shared typedefs.
+ *
+ * Extracted from the composition root so file-level headers stay scannable.
+ * No runtime exports; this file exists for IDE and JSDoc tooling only.
+ */
+
+/**
+ * @typedef {Object} BaselineSettings
+ * Site identity and SEO configuration.
+ *
+ * @property {string} [title]
+ * @property {string} [tagline]
+ * @property {string} [url]
+ * @property {boolean} [noindex]
+ * @property {string} [defaultLanguage]
+ * @property {Record<string, unknown>} [languages]
+ * @property {Object} [head]
+ */
+
+/**
+ * @typedef {Object} BaselineOptions
+ * Runtime feature flags and behaviour configuration.
+ *
+ * User-facing input. Each module reads its own slice from `state.options.<module>`.
+ *
+ * @property {boolean} [verbose]
+ * Enables structured debug logging across modules.
+ *
+ * @property {boolean} [multilingual]
+ * Enables multilingual mode. Requires settings.defaultLanguage and
+ * settings.languages; the multilang module bails with a log otherwise.
+ *
+ * @property {boolean} [sitemap]
+ * Enables sitemap generation module (default: true).
+ *
+ * @property {boolean | { template?: boolean, inspectorDepth?: number }} [navigator]
+ * Controls navigator tooling. Boolean shorthand activates the module and
+ * the virtual debug page. Object form lets the page render flag and the
+ * inspector depth be tuned independently. Defaults to true in dev mode.
+ *
+ * @property {{ titleSeparator?: string, showGenerator?: boolean }} [head]
+ * Head module options.
+ *
+ * @property {{ esbuild?: { minify?: boolean, target?: string } }} [assets]
+ * Assets module options. The esbuild slice is permissive — any esbuild
+ * option is accepted; only `minify` and `target` are typed.
+ */
+
+/**
+ * @typedef {Object} BaselineState
+ * Fully resolved internal plugin state.
+ *
+ * @property {Object} settings
+ * @property {Object} options
+ */
+
+/**
+ * @typedef {Object} BaselineContext
+ * Shared module boundary contract.
+ *
+ * This context is the only supported interface between:
+ * - Eleventy configuration runtime
+ * - baseline core
+ * - feature modules
+ *
+ * @property {BaselineState} state
+ * @property {Object} runtime
+ * @property {Object} runtime.contentMap
+ * @property {Object} runtime.site
+ */
+
+export {};

package/core/utils/helpers.js

@@ -0,0 +1,75 @@
+import { TemplatePath } from '@11ty/eleventy-utils';
+import slugifyLib from 'slugify';
+
+/**
+ * Helper function to add trailing slash to a path
+ * @param {string} path
+ * @returns {string}
+ */
+export function addTrailingSlash(path) {
+	if (path.slice(-1) === '/') {
+		return path;
+	}
+	return path + '/';
+}
+
+/**
+ * Resolve a subdirectory under input and output.
+ * Joins inputDir/outputDir with rawDir, normalises, and adds trailing slashes.
+ * @param {string} inputDir - The input directory (e.g., "./src/").
+ * @param {string} outputDir - The output directory (e.g., "./dist/").
+ * @param {string} rawDir - Raw subdirectory value (e.g., "assets", "static").
+ * @returns {{input: string, output: string}}
+ */
+export function resolveSubdir(inputDir, outputDir, rawDir) {
+	const joinedInput = TemplatePath.join(inputDir, rawDir || '');
+	const joinedOutput = TemplatePath.join(outputDir, rawDir || '');
+
+	return {
+		input: addTrailingSlash(TemplatePath.standardizeFilePath(joinedInput)),
+		output: addTrailingSlash(TemplatePath.standardizeFilePath(joinedOutput))
+	};
+}
+
+/**
+ * Slugify a string into a wikilink-friendly key.
+ * Lowercases, strips diacritics, replaces non-alphanumerics with hyphens,
+ * trims leading/trailing hyphens. Returns null for empty input.
+ *
+ * @param {string|null|undefined} input
+ * @returns {string|null}
+ */
+export function slugify(input) {
+	if (input == null) return null;
+	const slug = slugifyLib(String(input), { lower: true, strict: true, trim: true });
+	return slug || null;
+}
+
+/**
+ * Normalize language input to an object map.
+ * Accepts an array of language codes or an object keyed by language code.
+ * Returns null if input is invalid or empty.
+ *
+ * @param {Object} settings - Options object containing languages.
+ * @param {import('../logging.js').BaselineLogger} [logger] - Logger for dropped-entry notice.
+ * @returns {Record<string, Object>|null} Normalized language map, or null.
+ */
+export function normalizeLanguages(settings, logger) {
+	const normalizedLanguages = Array.isArray(settings.languages)
+		? Object.fromEntries(
+				settings.languages
+					.filter((lang) => typeof lang === 'string' && lang.trim())
+					.map((lang) => [lang.toLowerCase().trim(), {}])
+			)
+		: settings.languages && typeof settings.languages === 'object'
+			? settings.languages
+			: null;
+
+	if (logger && Array.isArray(settings.languages)) {
+		const normalizedCount = normalizedLanguages ? Object.keys(normalizedLanguages).length : 0;
+		if (normalizedCount !== settings.languages.length) {
+			logger.info('Some languages entries were invalid and were dropped.');
+		}
+	}
+	return normalizedLanguages;
+}

package/core/utils/pick.js

@@ -0,0 +1,7 @@
+/**
+ * Return the first value that is neither undefined nor null.
+ * @param {...*} values
+ * @returns {*}
+ */
+const pick = (...values) => values.find((v) => v !== undefined && v !== null);
+export default pick;