@cloudcannon/editable-regions 0.0.17 → 0.0.19

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/browser/process-shim.mjs

@@ -0,0 +1,32 @@
+/**
+ * Stand-ins for the Node globals a config reaches for without importing
+ * anything, so there's no module to stub — `process.env.X` at the top of a
+ * config otherwise kills the bundle with `ReferenceError: process is not
+ * defined`. esbuild's `inject` substitutes these for unbound identifiers.
+ */
+
+/**
+ * `"development"` for the same reason `eleventy.env.runMode` is `"serve"`: a
+ * config gated on `NODE_ENV === "production"` shouldn't drag build-only
+ * plugins into the mirror. Real values belong in `pluginOptions.globals`.
+ *
+ * esbuild defines the exact expression `process.env.NODE_ENV` itself, and that
+ * wins over this object — changing the value here only affects indirect reads
+ * like `const e = process.env`.
+ */
+export const process = {
+	env: { NODE_ENV: "development" },
+	argv: [],
+	platform: "browser",
+	version: "",
+	versions: {},
+	browser: true,
+	cwd: () => "/",
+	nextTick: (/** @type {any} */ fn, /** @type {any[]} */ ...args) =>
+		queueMicrotask(() => fn(...args)),
+};
+
+export const __dirname = "/";
+export const __filename = "/";
+
+export default process;

package/integrations/eleventy/browser/stub-mode.mjs

@@ -0,0 +1,61 @@
+/**
+ * Strictness switch for the stubs `createBrowserStubPlugin` generates. The two
+ * phases want opposite behaviour:
+ *
+ * - **Config replay** — skip and warn. An argument-side call like
+ *   `addPlugin(pluginBookshop({…}))` runs before `addPlugin` is reached, so a
+ *   throw escapes the config function and loses every helper below that line.
+ * - **Render time** — throw. That's the documented signal to add a
+ *   `pluginOptions.liquid.<kind>` override, named by `enhanceLiquidError`.
+ *
+ * `collect-config.mjs` flips it once the mirror finishes, and the bundle awaits
+ * that before publishing components, so the phases can't overlap.
+ */
+
+import { log, warnOnce } from "../../liquid/logger.mjs";
+import { createInertValue } from "./inert.mjs";
+
+/**
+ * This plugin's own Eleventy entry — the one entry in `ALWAYS_STUBBED`. Every
+ * config calls it via `addPlugin`, and the browser bundle registers its helpers
+ * itself, so skipping it is expected and there's nothing to act on.
+ */
+const SELF_SPECIFIER = "@cloudcannon/editable-regions/eleventy";
+
+let strict = false;
+
+/** Called by the mirror once every helper has been registered. */
+export function setStubsStrict() {
+	strict = true;
+}
+
+/**
+ * @param {string} specifier - The stubbed module, e.g. `"node:fs"`
+ * @param {"called" | "constructed"} verb
+ * @returns {any} An inert stand-in, while we're still replaying the config
+ */
+export function onStubInvoked(specifier, verb) {
+	if (strict) {
+		throw new Error(
+			`editable-regions: "${specifier}" was ${verb} in the browser ` +
+				"live-editing bundle. It's a Node/build-time module with no browser " +
+				"equivalent — provide an override via pluginOptions.liquid.<kind>.",
+		);
+	}
+
+	if (specifier === SELF_SPECIFIER) {
+		log(
+			`[editable-regions] "${specifier}" was ${verb} and skipped, as expected.`,
+		);
+	} else {
+		warnOnce(
+			`eleventy-stub:${specifier}`,
+			`[editable-regions] "${specifier}" was ${verb} while replaying your ` +
+				"Eleventy config for live editing. It's a Node/build-time module, so " +
+				"the call was skipped and the rest of the config still mirrored. If a " +
+				"filter or shortcode is missing from the editor, this is the reason.",
+		);
+	}
+
+	return createInertValue();
+}

package/integrations/eleventy/index.cjs

@@ -0,0 +1,28 @@
+// Node can `require()` an ES module from v20.19 / v22.12 onward, so this stays
+// a re-export. Older runtimes throw a bare ERR_REQUIRE_ESM naming neither this
+// package nor a way out — translate it.
+
+/** @type {any} */
+let editableRegionsPlugin;
+
+try {
+	editableRegionsPlugin = require("./index.mjs").default;
+} catch (err) {
+	const code = /** @type {{ code?: string } | undefined} */ (err)?.code;
+	if (code !== "ERR_REQUIRE_ESM") throw err;
+
+	throw new Error(
+		"@cloudcannon/editable-regions/eleventy is an ES module, and Node " +
+			`${process.version} can't \`require()\` one (needs v20.19+ or v22.12+).` +
+			"\n\nEither upgrade Node, or load the plugin with a dynamic import from " +
+			"an async Eleventy config:\n\n" +
+			"  module.exports = async function (eleventyConfig) {\n" +
+			"    const { default: editableRegions } = await import(\n" +
+			'      "@cloudcannon/editable-regions/eleventy"\n' +
+			"    );\n" +
+			"    eleventyConfig.addPlugin(editableRegions);\n" +
+			"  };\n",
+	);
+}
+
+module.exports = editableRegionsPlugin;