@cloudcannon/editable-regions 0.0.17 → 0.0.19

package/integrations/eleventy/browser/collect-config.mjs

@@ -0,0 +1,249 @@
+/**
+ * Auto-mirrors an Eleventy config's helpers into the live-editing engine. The
+ * bundle imports the user's *real* config (so closures and imports survive,
+ * unlike `fn.toString()`) and replays it here against a recording stand-in for
+ * `eleventyConfig`, capturing every `addFilter`/`addShortcode`/etc. call.
+ *
+ * Node/build-time APIs the config imports are stubbed at bundle time (see
+ * `../index.mjs`), so importing them is harmless; only a helper that invokes
+ * one at render time fails.
+ *
+ * @typedef {"filters" | "shortcodes" | "pairedShortcodes" | "tags"} HelperKind
+ */
+
+import {
+	registerCustomTag,
+	registerFilter,
+	registerPairedShortcode,
+	registerShortcode,
+} from "../../liquid/index.mjs";
+import { warnOnce } from "../../liquid/logger.mjs";
+import { createInertValue } from "./inert.mjs";
+import {
+	builtinFilterNames,
+	builtinShortcodeNames,
+} from "./liquid-builtins.mjs";
+import { setStubsStrict } from "./stub-mode.mjs";
+
+/** @type {Record<HelperKind, (name: string, fn: any) => void>} */
+const KIND_REGISTRARS = {
+	filters: registerFilter,
+	shortcodes: registerShortcode,
+	pairedShortcodes: registerPairedShortcode,
+	tags: registerCustomTag,
+};
+
+/**
+ * Maps each 11ty registration method to its `[kind, layer]`. Universal and
+ * Liquid-specific siblings feed the same kind; the Liquid layer wins on a
+ * collision, mirroring 11ty's `{ ...universal, ...liquid }` precedence.
+ * Variants for other engines (JS/Handlebars/Nunjucks) aren't mirrored.
+ *
+ * @type {Record<string, [HelperKind, "universal" | "liquid"]>}
+ */
+const METHOD_TARGETS = {
+	addFilter: ["filters", "universal"],
+	addAsyncFilter: ["filters", "universal"],
+	addLiquidFilter: ["filters", "liquid"],
+	addShortcode: ["shortcodes", "universal"],
+	addAsyncShortcode: ["shortcodes", "universal"],
+	addLiquidShortcode: ["shortcodes", "liquid"],
+	addPairedShortcode: ["pairedShortcodes", "universal"],
+	addPairedAsyncShortcode: ["pairedShortcodes", "universal"],
+	addPairedLiquidShortcode: ["pairedShortcodes", "liquid"],
+	addLiquidTag: ["tags", "liquid"],
+};
+
+/**
+ * Eleventy accepts a plugin as either a config function directly or as a
+ * `{ configFunction, ... }` object. Returns the underlying function, or `null`
+ * if it's neither (so the caller can skip it).
+ *
+ * @param {any} plugin
+ * @returns {((config: any, opts: any) => any) | null} Async plugins return a
+ *   promise the caller must await.
+ */
+function resolvePluginFunction(plugin) {
+	if (typeof plugin === "function") return plugin;
+	if (typeof plugin?.configFunction === "function")
+		return plugin.configFunction;
+	return null;
+}
+
+/** @returns {Record<HelperKind, Map<string, any>>} */
+function createEmptyLayer() {
+	return {
+		filters: new Map(),
+		shortcodes: new Map(),
+		pairedShortcodes: new Map(),
+		tags: new Map(),
+	};
+}
+
+/**
+ * Mirrors the config's helpers into the live-editing engine.
+ *
+ * The mirror is async because configs commonly are — `await
+ * import("@11ty/eleventy")` is how a CommonJS config reaches the ESM-only
+ * exports, and such a config registers nothing until that settles. The bundle
+ * awaits the returned promise before registering anything else.
+ *
+ * @param {unknown} config - The config's default export (a function), or a
+ *   module namespace whose `.default` is that function (ESM/CJS interop).
+ * @param {{ skip?: Partial<Record<HelperKind, string[]>> }} [options] - Per-kind
+ *   override names to skip; builtin browser-port names are skipped automatically.
+ * @returns {Promise<void>} Resolves once every mirrored helper is registered.
+ */
+export function collectAndRegisterEleventyHelpers(config, options = {}) {
+	// `finally` so a mirror that failed still leaves render-time stub calls
+	// throwing; see `stub-mode.mjs`.
+	return mirrorConfig(config, options).finally(setStubsStrict);
+}
+
+/**
+ * Replays `configFn` against a recording stand-in and registers every
+ * collected helper that isn't skipped.
+ *
+ * @param {unknown} config
+ * @param {{ skip?: Partial<Record<HelperKind, string[]>> }} options
+ * @returns {Promise<void>}
+ */
+async function mirrorConfig(config, options) {
+	const configFn =
+		typeof config === "function"
+			? config
+			: /** @type {any} */ (config)?.default;
+
+	if (typeof configFn !== "function") {
+		warnOnce(
+			"eleventy-config-shape",
+			"Could not auto-mirror Eleventy config helpers: the config's default " +
+				"export isn't a function. Filters/shortcodes defined in the config " +
+				"won't be available in live editing.",
+		);
+		return;
+	}
+
+	// Skip builtin browser-port names (derived from `liquid-builtins.mjs`) so a
+	// same-named config helper can't clobber our port, plus caller overrides.
+	/** @type {Record<HelperKind, Set<string>>} */
+	const skip = {
+		filters: new Set([...builtinFilterNames, ...(options.skip?.filters ?? [])]),
+		shortcodes: new Set([
+			...builtinShortcodeNames,
+			...(options.skip?.shortcodes ?? []),
+		]),
+		pairedShortcodes: new Set(options.skip?.pairedShortcodes ?? []),
+		tags: new Set(options.skip?.tags ?? []),
+	};
+
+	const layers = { universal: createEmptyLayer(), liquid: createEmptyLayer() };
+
+	/** @type {Record<string, any>} */
+	const recorder = {};
+	for (const [method, [kind, layer]] of Object.entries(METHOD_TARGETS)) {
+		recorder[method] = (
+			/** @type {string} */ name,
+			/** @type {any} */ helperFn,
+		) => {
+			if (typeof name === "string" && typeof helperFn === "function") {
+				layers[layer][kind].set(name, helperFn);
+			}
+		};
+	}
+
+	// Unrecorded members are inert so the real config (`addPassthroughCopy`,
+	// `on`, `ignores.add(…)`, setting `dir`, ...) doesn't throw. Chainable, so
+	// reaching through a property before calling still works.
+	const unrecorded = createInertValue();
+	const configRecorder = new Proxy(recorder, {
+		get(target, prop, receiver) {
+			if (prop in target) return Reflect.get(target, prop, receiver);
+			// Thenable-looking recorder would hang `pendingPlugins`; see `inert.mjs`.
+			if (prop === "then" || typeof prop === "symbol") return undefined;
+			return unrecorded;
+		},
+	});
+
+	/** Async plugins, drained before the registration pass. @type {Promise<void>[]} */
+	const pendingPlugins = [];
+
+	recorder.addPlugin = (/** @type {any} */ plugin, /** @type {any} */ opts) => {
+		const pluginFn = resolvePluginFunction(plugin);
+		if (!pluginFn) return;
+
+		// A plugin is itself a config function, so replay it against the same
+		// recorder to capture the helpers it registers.
+		try {
+			const result = pluginFn(configRecorder, opts);
+			if (typeof result?.then === "function") {
+				// `Promise.resolve` normalizes: a native promise is returned as-is,
+				// a bare thenable gains `.catch`. Async stubs reject; swallow both.
+				pendingPlugins.push(Promise.resolve(result).catch(() => {}));
+			}
+		} catch {
+			// Node-only plugins are stubbed at bundle time and throw when called.
+			// Helpers registered before the throw are kept; the config continues.
+		}
+	};
+
+	let replayFailed = false;
+
+	try {
+		await configFn(configRecorder);
+		// A plugin can register further plugins, so drain until nothing new lands.
+		while (pendingPlugins.length > 0) {
+			await Promise.all(pendingPlugins.splice(0));
+		}
+	} catch (err) {
+		replayFailed = true;
+		warnOnce(
+			"eleventy-config-replay",
+			"Replaying the Eleventy config to mirror its helpers threw: " +
+				`${err instanceof Error ? err.message : err}. Some filters/` +
+				"shortcodes may be unavailable in live editing — define a browser " +
+				"override via `pluginOptions.liquid.<kind>` for any that are needed.",
+		);
+	}
+
+	let mirroredCount = 0;
+
+	for (const kind of /** @type {HelperKind[]} */ (
+		Object.keys(KIND_REGISTRARS)
+	)) {
+		const register = KIND_REGISTRARS[kind];
+		// Liquid layer spread last so it wins on a name collision.
+		const merged = new Map([...layers.universal[kind], ...layers.liquid[kind]]);
+		mirroredCount += merged.size;
+
+		for (const [name, helperFn] of merged) {
+			if (skip[kind].has(name)) continue;
+			try {
+				register(name, helperFn);
+			} catch (err) {
+				warnOnce(
+					`eleventy-mirror:${kind}:${name}`,
+					`Failed to mirror Eleventy ${kind} "${name}" into live editing: ` +
+						`${err instanceof Error ? err.message : err}.`,
+				);
+			}
+		}
+	}
+
+	// An async config mirroring nothing otherwise surfaces as a `strictFilters`
+	// "unknown filter" error inside an unrelated template. A replay that threw
+	// has already warned, and explains the empty result.
+	if (
+		mirroredCount === 0 &&
+		!replayFailed &&
+		configFn.constructor?.name === "AsyncFunction"
+	) {
+		warnOnce(
+			"eleventy-async-config",
+			"Your Eleventy config is async and registered no helpers when replayed " +
+				"for live editing. If it defines filters/shortcodes they won't be " +
+				"available — define a browser override via " +
+				"`pluginOptions.liquid.<kind>` for any that are needed.",
+		);
+	}
+}

package/integrations/eleventy/browser/index.mjs

@@ -0,0 +1,9 @@
+/**
+ * Browser entry for the 11ty ports (`@cloudcannon/editable-regions/eleventy/browser`).
+ * The generated bundle imports both helpers from here. Kept as a thin barrel
+ * so `collect-config.mjs` can import the builtin name lists from
+ * `liquid-builtins.mjs` without the two forming an import cycle.
+ */
+
+export { collectAndRegisterEleventyHelpers } from "./collect-config.mjs";
+export { registerEleventyBuiltins } from "./liquid-builtins.mjs";

package/integrations/eleventy/browser/inert.mjs

@@ -0,0 +1,35 @@
+/**
+ * A stand-in that survives whatever a config does to it — property access,
+ * calls and `new` all return it again. Used for unrecorded config methods
+ * (`collect-config.mjs`) and stubbed Node modules (`stub-mode.mjs`).
+ *
+ * @returns {any}
+ */
+export function createInertValue() {
+	// `function`, not an arrow: arrows have no [[Construct]], so `new inert()`
+	// would throw before the trap runs.
+	const handler = {
+		/** @param {any} _target @param {string | symbol} prop */
+		get(_target, prop) {
+			// Must not look thenable: `collect-config.mjs` treats a plugin result
+			// with a callable `.then` as a promise, and this one would never
+			// settle — hanging the mirror, so no component is ever published.
+			if (prop === "then") return undefined;
+
+			if (typeof prop === "symbol") {
+				// Else `String(inert)` walks toPrimitive → valueOf → toString,
+				// gets a proxy from each, and throws.
+				if (prop === Symbol.toPrimitive) return () => "";
+				// Else `for…of` / spread over a stubbed call throws.
+				if (prop === Symbol.iterator) return function* () {};
+				return undefined;
+			}
+			return inert;
+		},
+		apply: () => inert,
+		construct: () => inert,
+	};
+
+	const inert = new Proxy(function () {}, handler);
+	return inert;
+}

package/integrations/eleventy/browser/liquid-builtins.mjs

@@ -0,0 +1,306 @@
+// Browser ports of Eleventy's built-in filters and shortcodes. Filters needing
+// build-time internals are warn-once pass-through stubs so templates keep
+// rendering. `registerEleventyBuiltins(engine)` wires everything up.
+
+import sindresorhusSlugify from "@sindresorhus/slugify";
+import simovSlugify from "slugify";
+import { warnOnce } from "../../liquid/logger.mjs";
+import { getPageMap, normalizeInputPath } from "../../liquid/page-map.mjs";
+import { createShortcodeTag } from "../../liquid/shortcodes.mjs";
+import {
+	createRenderContentFilter,
+	createRenderFileShortcode,
+	createRenderTemplateTag,
+} from "./liquid-render.mjs";
+
+/**
+ * @param {any} value
+ * @param {string} [prefix]
+ */
+export function logFilter(value, prefix = "") {
+	if (prefix) {
+		console.log(`[${prefix}]`, value);
+	} else {
+		console.log(value);
+	}
+	return value;
+}
+
+/**
+ * Eleventy's `slug` filter (`Filters/Slug.js`), backed by `simov/slugify`
+ * (permissive: keeps `+`, `@`, `.`; substitutes `&`→`and`, `%`→`percent`).
+ *
+ * @param {unknown} str
+ * @param {Record<string, any>} [options]
+ */
+export function slugFilter(str, options = {}) {
+	return simovSlugify(`${str}`, { replacement: "-", lower: true, ...options });
+}
+
+/**
+ * Eleventy's `slugify` filter (`Filters/Slugify.js`), backed by
+ * `@sindresorhus/slugify` (strict ASCII: non-alphanumerics become separators).
+ *
+ * @param {unknown} str
+ * @param {Record<string, any>} [options]
+ */
+export function slugifyFilter(str, options = {}) {
+	return sindresorhusSlugify(`${str}`, { decamelize: false, ...options });
+}
+
+/**
+ * Eleventy's `url` filter (`Filters/Url.js`). Absolute and protocol-relative
+ * URLs pass through; root-relative URLs get `pathPrefix` prepended when given.
+ * Unlike upstream (which always has a `pathPrefix`), the no-prefix branch
+ * returns the input unchanged rather than throwing.
+ *
+ * @param {string} url
+ * @param {string} [pathPrefix]
+ */
+export function urlFilter(url, pathPrefix = "") {
+	if (!url) return "";
+
+	const urlString = String(url);
+	if (isAbsoluteUrl(urlString)) return urlString;
+	if (urlString.startsWith("//") && urlString !== "//") return urlString;
+	if (!pathPrefix) return urlString;
+
+	const normalizedPrefix = `/${pathPrefix.replace(/^\/+|\/+$/g, "")}`;
+	if (urlString.startsWith("/")) return `${normalizedPrefix}${urlString}`;
+
+	return urlString;
+}
+
+/** Matches Eleventy's `Util/ValidUrl.js`: parseable by `new URL()` → absolute. */
+function isAbsoluteUrl(/** @type {string} */ url) {
+	try {
+		new URL(url);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Coerces an input (Date, ISO string, epoch number) into a Date; `null` for unusable input. */
+function toDate(/** @type {any} */ value) {
+	if (value instanceof Date) {
+		return Number.isNaN(value.getTime()) ? null : value;
+	}
+
+	if (value === null || value === undefined || value === "") return null;
+
+	const d = new Date(value);
+	return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/** ISO 8601 / RFC 3339 (e.g. "2026-04-21T00:00:00.000Z"). */
+export function dateToRfc3339(/** @type {Date | string | number} */ date) {
+	const d = toDate(date);
+
+	return d ? d.toISOString() : "";
+}
+
+/** RFC 822 / RFC 1123 (e.g. "Tue, 21 Apr 2026 00:00:00 GMT"). */
+export function dateToRfc822(/** @type {Date | string | number} */ date) {
+	const d = toDate(date);
+
+	return d ? d.toUTCString() : "";
+}
+
+/** `YYYY-MM-DD` form, used for `<time datetime>` attributes. */
+export function htmlDateString(/** @type {Date | string | number} */ date) {
+	const d = toDate(date);
+
+	return d ? d.toISOString().slice(0, 10) : "";
+}
+
+/**
+ * @param {Array<{date?: any}>} collection
+ * @param {Date | string | number} [emptyFallback]
+ */
+export function getNewestCollectionItemDate(collection, emptyFallback) {
+	if (!Array.isArray(collection) || collection.length === 0) {
+		return toDate(emptyFallback) ?? new Date(0);
+	}
+
+	let newest = 0;
+	for (const item of collection) {
+		const d = toDate(item?.date);
+		if (d && d.getTime() > newest) newest = d.getTime();
+	}
+
+	return newest ? new Date(newest) : (toDate(emptyFallback) ?? new Date(0));
+}
+
+/**
+ * Index of `page` in `collection` by `inputPath`. The editor doesn't model
+ * pagination, so `inputPath` alone is unique (upstream also tie-breaks on
+ * `outputPath || url`). `await page.inputPath` handles both shapes: the `page`
+ * global is a Promise-returning Proxy; a collection item's is already a string.
+ *
+ * @param {Array<{inputPath?: string}>} collection
+ * @param {any} page
+ * @returns {Promise<number>}
+ */
+async function indexInCollection(collection, page) {
+	if (!Array.isArray(collection)) return -1;
+
+	if (!page) {
+		warnOnce(
+			"collection-item-no-page",
+			"Eleventy collection-item filter called without a `page` argument. " +
+				"In live editing, pass the page/item explicitly (e.g. `collections.posts | getCollectionItem: page`).",
+		);
+
+		return -1;
+	}
+
+	const inputPath = await page.inputPath;
+	if (typeof inputPath !== "string" || !inputPath) return -1;
+
+	return collection.findIndex((item) => item?.inputPath === inputPath);
+}
+
+export async function getCollectionItem(
+	/** @type {any[]} */ collection,
+	/** @type {any} */ page,
+) {
+	const i = await indexInCollection(collection, page);
+
+	return i >= 0 ? collection[i] : undefined;
+}
+
+export async function getPreviousCollectionItem(
+	/** @type {any[]} */ collection,
+	/** @type {any} */ page,
+) {
+	const i = await indexInCollection(collection, page);
+
+	return i > 0 ? collection[i - 1] : undefined;
+}
+
+export async function getNextCollectionItem(
+	/** @type {any[]} */ collection,
+	/** @type {any} */ page,
+) {
+	const i = await indexInCollection(collection, page);
+
+	return i >= 0 && i < collection.length - 1 ? collection[i + 1] : undefined;
+}
+
+export async function getCollectionItemIndex(
+	/** @type {any[]} */ collection,
+	/** @type {any} */ page,
+) {
+	return indexInCollection(collection, page);
+}
+
+/**
+ * Pass-through filter that warns once — for Eleventy filters that depend on
+ * build-time internals we don't have in the browser.
+ *
+ * @param {string} filterName
+ * @param {string} reason
+ */
+function passThroughStub(filterName, reason) {
+	return (/** @type {any} */ value) => {
+		warnOnce(
+			`filter-stub:${filterName}`,
+			`Eleventy filter "${filterName}" is not supported in live editing (${reason}). ` +
+				"Returning the input unchanged.",
+		);
+
+		return value;
+	};
+}
+
+/**
+ * Browser port of the `inputPathToUrl` plugin filter, resolving against the
+ * build-time page map. Misses (e.g. a file not in the last build) warn-once
+ * and pass through rather than throwing.
+ *
+ * @param {unknown} inputPath
+ */
+export function inputPathToUrlFilter(inputPath) {
+	if (typeof inputPath !== "string" || !inputPath) {
+		return typeof inputPath === "string" ? inputPath : "";
+	}
+
+	const entry = getPageMap()[normalizeInputPath(inputPath)];
+	if (entry?.url) return entry.url;
+
+	warnOnce(
+		`input-path-to-url-miss:${inputPath}`,
+		`inputPathToUrl: no build-time URL recorded for "${inputPath}". ` +
+			"This usually means the file wasn't in the last build. Returning the " +
+			"input unchanged.",
+	);
+
+	return inputPath;
+}
+
+/** @type {Record<string, any>} */
+export const eleventyFilters = {
+	slug: slugFilter,
+	slugify: slugifyFilter,
+	log: logFilter,
+	url: urlFilter,
+	dateToRfc3339,
+	dateToRfc822,
+	htmlDateString,
+	getNewestCollectionItemDate,
+	getCollectionItem,
+	getPreviousCollectionItem,
+	getNextCollectionItem,
+	getCollectionItemIndex,
+	inputPathToUrl: inputPathToUrlFilter,
+	htmlBaseUrl: passThroughStub(
+		"htmlBaseUrl",
+		"it requires Eleventy's pathPrefix/HTML base config",
+	),
+	serverlessUrl: passThroughStub(
+		"serverlessUrl",
+		"serverless routing is a build-time concept",
+	),
+};
+
+/**
+ * Builtin names the config auto-mirror skips, so a same-named config helper
+ * doesn't clobber our port. Derived from the implementations so they can't
+ * drift; `renderContent`/`renderFile` are the RenderPlugin shims.
+ *
+ * @type {string[]}
+ */
+export const builtinFilterNames = [
+	...Object.keys(eleventyFilters),
+	"renderContent",
+];
+
+/** @type {string[]} */
+export const builtinShortcodeNames = ["renderFile"];
+
+/**
+ * Wires `eleventyFilters` plus the RenderPlugin shims onto the shared engine.
+ *
+ * @param {import("liquidjs").Liquid} liquidEngine
+ */
+export function registerEleventyBuiltins(liquidEngine) {
+	for (const [name, fn] of Object.entries(eleventyFilters)) {
+		liquidEngine.registerFilter(name, fn);
+	}
+
+	liquidEngine.registerTag(
+		"renderTemplate",
+		createRenderTemplateTag(liquidEngine),
+	);
+
+	liquidEngine.registerTag(
+		"renderFile",
+		createShortcodeTag("renderFile", createRenderFileShortcode(liquidEngine)),
+	);
+
+	liquidEngine.registerFilter(
+		"renderContent",
+		createRenderContentFilter(liquidEngine),
+	);
+}