@cloudcannon/editable-regions 0.0.16 → 0.0.18

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),
+	);
+}

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

@@ -0,0 +1,216 @@
+/**
+ * Browser shims for Eleventy's RenderPlugin
+ * (https://v3.11ty.dev/docs/plugins/render/): `renderTemplate` (paired tag),
+ * `renderContent` (filter), `renderFile` (shortcode). Each compiles a body as
+ * `templateLang` and renders it with `data`. Only LiquidJS runs in the browser,
+ * so: "liquid"/unspecified → real render; "html" → passthrough; else →
+ * warn-once and return the body unchanged.
+ */
+
+import {
+	apiLoadedPromise,
+	CloudCannon,
+} from "../../../helpers/cloudcannon.mjs";
+import { warnOnce } from "../../liquid/logger.mjs";
+import { evaluateArgs, parseArgs } from "../../liquid/shortcodes.mjs";
+
+const supportedEngines = new Set(["liquid", "html"]);
+
+/**
+ * Tag factory for `{% renderTemplate ... %}…{% endrenderTemplate %}`. Captures
+ * the body as raw source (matching upstream — compiled in the requested engine,
+ * not pre-rendered) and renders it against `data`.
+ *
+ * @param {any} _liquidEngine - Unused; reached via `this.liquid`
+ * @returns {any}
+ */
+export function createRenderTemplateTag(_liquidEngine) {
+	return {
+		parse(/** @type {any} */ tagToken, /** @type {any[]} */ remainTokens) {
+			this.name = tagToken.name;
+			this.argTokens = parseArgs(
+				tagToken.args,
+				this.liquid.options.operatorsTrie,
+			);
+			this.bodyTokens = [];
+
+			const endTagName = `end${this.name}`;
+			while (remainTokens.length) {
+				const token = remainTokens.shift();
+				if (token.name === endTagName) return;
+
+				this.bodyTokens.push(token);
+			}
+
+			throw new Error(`tag ${this.name} not closed`);
+		},
+
+		async render(/** @type {any} */ context) {
+			const args = await evaluateArgs(this.argTokens, context);
+			const { templateLang, data } = normalizeRenderArgs([args[0], args[1]]);
+			const body = this.bodyTokens
+				.map((/** @type {any} */ t) => t.getText())
+				.join("");
+
+			if (templateLang && !supportedEngines.has(templateLang)) {
+				warnOnce(
+					`render-template:${templateLang}`,
+					unsupportedEngineMessage(templateLang),
+				);
+				return body;
+			}
+
+			if (templateLang === "html") return body;
+			return await this.liquid.parseAndRender(body, data);
+		},
+	};
+}
+
+/**
+ * Builds the `renderContent` filter, capturing the shared engine.
+ *
+ * @param {any} liquidEngine
+ */
+export function createRenderContentFilter(liquidEngine) {
+	return async function renderContent(
+		/** @type {any} */ content,
+		/** @type {any} */ templateLang,
+		/** @type {any} */ data,
+	) {
+		const normalized = normalizeRenderArgs([templateLang, data]);
+		const body = content == null ? "" : String(content);
+
+		if (
+			normalized.templateLang &&
+			!supportedEngines.has(normalized.templateLang)
+		) {
+			warnOnce(
+				`render-content:${normalized.templateLang}`,
+				unsupportedEngineMessage(normalized.templateLang),
+			);
+
+			return body;
+		}
+
+		if (normalized.templateLang === "html") return body;
+
+		return await liquidEngine.parseAndRender(body, normalized.data);
+	};
+}
+
+/**
+ * Builds the `renderFile` shortcode. Fetches `inputPath` via the CloudCannon
+ * API and renders its body with `data`. Engine comes from `templateLang`, else
+ * inferred from the file extension.
+ *
+ * @param {any} liquidEngine
+ */
+export function createRenderFileShortcode(liquidEngine) {
+	return async function renderFile(
+		/** @type {any} */ inputPath,
+		/** @type {any} */ data,
+		/** @type {any} */ templateLang,
+	) {
+		if (typeof inputPath !== "string" || !inputPath) {
+			warnOnce(
+				"render-file:no-path",
+				"renderFile: missing or non-string path argument. Returning empty.",
+			);
+
+			return "";
+		}
+
+		// Normalise Eleventy-style paths (`./foo`, `/foo`) to the
+		// project-relative shape the CC API expects.
+		const normalizedPath = inputPath.replace(/^\.\/+/, "").replace(/^\/+/, "");
+
+		await apiLoadedPromise;
+
+		const file = CloudCannon?.file?.(normalizedPath);
+		if (!file) {
+			warnOnce(
+				`render-file-missing:${inputPath}`,
+				`renderFile: CloudCannon API not available; cannot load "${inputPath}".`,
+			);
+			return "";
+		}
+
+		// Mirror 11ty's data cascade: the file's own front matter is the base,
+		// the caller's `data` arg overrides on top. `content.get()` strips it.
+		let body;
+		let frontMatter;
+
+		try {
+			[body, frontMatter] = await Promise.all([
+				file.content.get(),
+				file.data.get(),
+			]);
+		} catch (err) {
+			warnOnce(
+				`render-file-missing:${inputPath}`,
+				`renderFile: failed to load "${inputPath}" via the CloudCannon API ` +
+					`(${err instanceof Error ? err.message : String(err)}).`,
+			);
+
+			return "";
+		}
+
+		const engine =
+			(typeof templateLang === "string" && templateLang) ||
+			inferEngineFromPath(inputPath);
+
+		if (engine && !supportedEngines.has(engine)) {
+			warnOnce(`render-file:${engine}`, unsupportedEngineMessage(engine));
+
+			return body;
+		}
+
+		if (engine === "html") return body;
+
+		const mergedData = { ...(frontMatter ?? {}), ...(data ?? {}) };
+
+		return await liquidEngine.parseAndRender(body, mergedData);
+	};
+}
+
+/**
+ * Normalises the `(templateLang, data)` pair, supporting the `(lang, data)`
+ * and lang-omitted `(data)` overloads.
+ *
+ * @param {[any, any]} args
+ * @returns {{templateLang: string | undefined, data: any}}
+ */
+function normalizeRenderArgs([templateLang, data]) {
+	if (templateLang && typeof templateLang !== "string") {
+		data = templateLang;
+		templateLang = undefined;
+	}
+
+	return { templateLang, data: data ?? {} };
+}
+
+/**
+ * Guesses the engine from the extension so the warn-once message can name it;
+ * only "liquid"/"html" actually render, the rest fall through to passthrough.
+ *
+ * @param {string} inputPath
+ */
+function inferEngineFromPath(inputPath) {
+	const dot = inputPath.lastIndexOf(".");
+	if (dot < 0) return undefined;
+
+	const ext = inputPath.slice(dot + 1).toLowerCase();
+	if (ext === "liquid") return "liquid";
+	if (ext === "html" || ext === "htm") return "html";
+	if (ext === "md") return "md";
+	if (ext === "njk") return "njk";
+	return undefined;
+}
+
+function unsupportedEngineMessage(/** @type {string} */ engineName) {
+	return (
+		`Eleventy RenderPlugin: engine "${engineName}" is not supported in ` +
+		`live editing (only "liquid" and "html" run in the browser). ` +
+		"Returning the body unchanged."
+	);
+}

package/integrations/eleventy/index.cjs

@@ -0,0 +1 @@
+module.exports = require("./index.mjs").default;