@cloudcannon/editable-regions 0.0.17 → 0.0.19

package/integrations/liquid/errors.mjs

@@ -0,0 +1,41 @@
+/**
+ * Rewrites a LiquidJS error into an actionable message for the error card.
+ *
+ * @param {unknown} err
+ * @param {string} componentName
+ * @returns {Error}
+ */
+export function enhanceLiquidError(err, componentName) {
+	const message = err instanceof Error ? err.message : String(err);
+
+	// LiquidJS appends its own position suffix ("undefined filter: foo, line:2,
+	// col:1"), so stop at the comma rather than at whitespace.
+	const unknownFilter = message.match(/undefined filter[:.]?\s*([^\s,]+)/i);
+	if (unknownFilter) {
+		const filterName = unknownFilter[1];
+		return new Error(
+			`Unknown filter "${filterName}" while rendering "${componentName}". ` +
+				`Please check your config and make sure you have registered "${filterName}" in the filters option.`,
+		);
+	}
+
+	const missingTemplate = message.match(/ENOENT.*?"([^"]+)"/);
+	if (missingTemplate) {
+		const filePath = missingTemplate[1];
+		return new Error(
+			`Failed to find included template "${filePath}" while rendering "${componentName}". ` +
+				`Please check that the file exists and is within your configured component directories.`,
+		);
+	}
+
+	const missingTag = message.match(/tag "?(\S+?)"? not found/i);
+	if (missingTag) {
+		const tagName = missingTag[1];
+		return new Error(
+			`Unknown tag "${tagName}" while rendering "${componentName}". ` +
+				`Please check your config and make sure you have registered "${tagName}" in the tags, shortcodes, or pairedShortcodes option.`,
+		);
+	}
+
+	return new Error(`Error rendering "${componentName}": ${message}`);
+}

package/integrations/liquid/fs.mjs

@@ -1,127 +1,88 @@
 import { log, warn } from "./logger.mjs";
 
 /**
- * In-memory filesystem for LiquidJS that reads from window.cc_files.
- *
- * @type {any} LiquidJS-compatible filesystem object
+ * Matches `path.extname`: last dot of the final segment, leading dot excluded.
+ */
+function hasExtension(/** @type {string} */ filePath) {
+	const basename = filePath.slice(filePath.lastIndexOf("/") + 1);
+	return basename.lastIndexOf(".") > 0;
+}
+
+/**
+ * In-memory filesystem for LiquidJS, reading from `window.cc_liquid_files`.
+ * @type {any}
  */
 export const inMemoryFs = {
 	sep: "/",
 
-	/**
-	 * Gets the directory name from a file path.
-	 *
-	 * @param {string} filePath - The file path
-	 * @returns {string} The directory portion of the path
-	 */
-	dirname(filePath) {
+	dirname(/** @type {string} */ filePath) {
 		const parts = filePath.split("/");
 		parts.pop();
 		return parts.join("/") || "/";
 	},
 
-	/**
-	 * Synchronously reads a file from the in-memory store.
-	 *
-	 * @param {string} filePath - The file path to read
-	 * @returns {string | undefined} The file contents or undefined if not found
-	 */
-	readFileSync(filePath) {
-		log("readFileSync:", filePath);
-		const fileContents = window.cc_files?.[filePath];
+	readFileSync(/** @type {string} */ filePath) {
+		const fileContents = window.cc_liquid_files?.[filePath];
 
-		if (fileContents === undefined) {
-			const availableFiles = Object.keys(window.cc_files || {});
+		if (fileContents === undefined || fileContents === null) {
+			const availableFiles = Object.keys(window.cc_liquid_files || {});
 			warn("File not found:", filePath);
 			log("Available files:", availableFiles);
-		} else {
-			log("File found, length:", fileContents?.length || 0);
+			throw new Error(
+				`ENOENT: Failed to find "${filePath}" in the bundled template files. Please check that this file exists and is within your configured component directories.`,
+			);
 		}
 
 		return fileContents;
 	},
 
-	/**
-	 * Asynchronously reads a file from the in-memory store.
-	 *
-	 * @param {string} filePath - The file path to read
-	 * @returns {Promise<string>} The file contents
-	 * @throws {Error} If filePath is empty
-	 */
-	async readFile(filePath) {
-		log("readFile:", filePath);
+	async readFile(/** @type {string} */ filePath) {
 		if (!filePath) {
 			throw new Error("readFile called with empty path");
 		}
 		return this.readFileSync(filePath);
 	},
 
-	/**
-	 * Asynchronously checks if a file exists.
-	 *
-	 * @param {string} filePath - The file path to check
-	 * @returns {Promise<boolean>} True if the file exists
-	 */
-	async exists(filePath) {
+	existsSync(/** @type {string} */ filePath) {
 		if (!filePath || typeof filePath !== "string") {
-			log("exists: invalid path", filePath);
 			return false;
 		}
-		const result = this.existsSync(filePath);
-		log("exists:", filePath, "=", result);
-		return result;
+		const fileContents = window.cc_liquid_files?.[filePath];
+		return fileContents !== null && fileContents !== undefined;
 	},
 
-	/**
-	 * Synchronously checks if a file exists.
-	 *
-	 * @param {string} filePath - The file path to check
-	 * @returns {boolean} True if the file exists
-	 */
-	existsSync(filePath) {
+	async exists(/** @type {string} */ filePath) {
 		if (!filePath || typeof filePath !== "string") {
 			return false;
 		}
-		const fileContents = window.cc_files?.[filePath];
-		const exists = fileContents !== null && fileContents !== undefined;
-		log("existsSync:", filePath, "=", exists);
-		return exists;
+		return this.existsSync(filePath);
 	},
 
 	/**
-	 * Resolves a file path by joining the root with the file name and extension.
-	 * LiquidJS calls this once per root directory and checks exists() on the
+	 * LiquidJS calls this once per root directory and checks `exists()` on the
 	 * result, so no directory searching is needed here.
-	 *
-	 * @param {string} root - The root directory provided by LiquidJS
-	 * @param {string} file - The file name to resolve
-	 * @param {string} [ext] - The file extension (defaults to ".liquid")
-	 * @returns {string} The resolved file path
 	 */
-	resolve(root, file, ext) {
+	resolve(
+		/** @type {string} */ root,
+		/** @type {string} */ file,
+		/** @type {string} */ ext,
+	) {
 		const extension = ext || ".liquid";
-		const fileWithExt = file.endsWith(extension) ? file : `${file}${extension}`;
+		// Only append when the file has none, as LiquidJS's Node fs does —
+		// otherwise `include "card.html"` becomes `card.html.liquid`.
+		const fileWithExt = hasExtension(file) ? file : `${file}${extension}`;
 		const normalizedRoot = root.replace(/^\.\//, "").replace(/\/*$/, "/");
 		const resolved = `${normalizedRoot}${fileWithExt}`;
 		log("resolve:", { root, file, ext }, "->", resolved);
 		return resolved;
 	},
 
-	/**
-	 * Returns file stat (always returns isFile: true for compatibility).
-	 *
-	 * @returns {Promise<{isFile: () => boolean}>}
-	 */
-	async statAsync() {
+	// The store is flat, so anything stat'd is a file.
+	statSync() {
 		return { isFile: () => true };
 	},
 
-	/**
-	 * Returns file stat synchronously (always returns isFile: true for compatibility).
-	 *
-	 * @returns {{isFile: () => boolean}}
-	 */
-	statSync() {
+	async statAsync() {
 		return { isFile: () => true };
 	},
 };

package/integrations/liquid/globals.mjs

@@ -0,0 +1,308 @@
+// Builders for the `page` and `collections` globals on the shared Liquid
+// engine. Both return Promises that LiquidJS awaits at the globals level.
+// `page` resolves to a plain object; `collections` resolves to an object whose
+// keys are lazy getters, so a template only pays for the collections it reads.
+
+import { apiLoadedPromise, CloudCannon } from "../../helpers/cloudcannon.mjs";
+import { getPageMap, normalizeInputPath } from "./page-map.mjs";
+
+/** @type {{ directories?: { output?: string } } | null} */
+let eleventyData = null;
+
+/** @param {{ directories?: { output?: string } } | null} data */
+export function setEleventyData(data) {
+	eleventyData = data;
+}
+
+/** Strips the file extension from a path. */
+function stripExtension(/** @type {string} */ p) {
+	return p.replace(/\.[^./]+$/, "");
+}
+
+/**
+ * 11ty's folder-style permalink: trailing-slash URL, `index` files mapping to
+ * the parent dir. Last-resort fallback when neither a literal front-matter
+ * `permalink` nor the page map resolves a URL.
+ */
+function deriveDefaultUrl(/** @type {string} */ inputPath) {
+	const stem = stripExtension(inputPath).replace(/^\.?\//, "/");
+	const withLeadingSlash = stem.startsWith("/") ? stem : `/${stem}`;
+	const withoutIndex = withLeadingSlash.replace(/\/index$/, "/");
+	return withoutIndex.endsWith("/") ? withoutIndex : `${withoutIndex}/`;
+}
+
+/**
+ * A front-matter `permalink` usable verbatim: a plain string with no Liquid
+ * templating. Templated permalinks (e.g. `"/{{ page.date }}/"`) need the full
+ * build context to render, so we return `undefined` and let the caller fall
+ * back to the page map's already-resolved value.
+ */
+function literalPermalink(
+	/** @type {Record<string, any> | null | undefined} */ data,
+) {
+	const permalink = data?.permalink;
+	if (typeof permalink !== "string") return undefined;
+	if (permalink.includes("{{") || permalink.includes("{%")) return undefined;
+	return permalink;
+}
+
+/**
+ * Resolves the URL for an input file, in priority order: literal front-matter
+ * `permalink` (so editor edits show before a rebuild) → build-time page map →
+ * 11ty's folder-style default.
+ */
+function resolveUrl(
+	/** @type {Record<string, any> | null | undefined} */ data,
+	/** @type {string} */ inputPath,
+) {
+	const permalink = literalPermalink(data);
+	if (permalink) return permalink;
+	const mapped = getPageMap()[normalizeInputPath(inputPath)];
+	if (mapped?.url) return mapped.url;
+	return deriveDefaultUrl(inputPath);
+}
+
+/** Same priority layering as `resolveUrl`, for the output path. */
+function resolveOutputPath(
+	/** @type {Record<string, any> | null | undefined} */ data,
+	/** @type {string} */ inputPath,
+) {
+	const outputDir = eleventyData?.directories?.output;
+	const permalink = literalPermalink(data);
+	if (permalink) {
+		return outputDir ? joinOutputPath(outputDir, permalink) : undefined;
+	}
+	const mapped = getPageMap()[normalizeInputPath(inputPath)];
+	if (mapped?.outputPath) return mapped.outputPath;
+	if (!outputDir) return undefined;
+	return joinOutputPath(outputDir, deriveDefaultUrl(inputPath));
+}
+
+/** Basename minus extension. Matches 11ty's `fileSlug` derivation. */
+function deriveFileSlug(/** @type {string} */ inputPath) {
+	const base = inputPath.split("/").pop() ?? "";
+	return stripExtension(base);
+}
+
+/** Full path minus extension, with a leading slash. */
+function deriveFilePathStem(/** @type {string} */ inputPath) {
+	const stem = stripExtension(inputPath).replace(/^\.?\//, "/");
+	return stem.startsWith("/") ? stem : `/${stem}`;
+}
+
+/** Coerces a front-matter date value into a Date, or `undefined`. */
+function toDate(/** @type {unknown} */ raw) {
+	if (!raw) return undefined;
+	const d = new Date(/** @type {any} */ (raw));
+	return Number.isNaN(d.getTime()) ? undefined : d;
+}
+
+/**
+ * Joins an output dir and URL the way 11ty does: trailing-slash URLs become
+ * `<dir><url>index.html`; others are appended as-is.
+ */
+function joinOutputPath(
+	/** @type {string} */ outputDir,
+	/** @type {string} */ url,
+) {
+	const dir = outputDir.replace(/\/+$/, "");
+	const tail = url.endsWith("/") ? `${url}index.html` : url;
+	return `${dir}${tail}`;
+}
+
+/**
+ * Materialises a CC API file into the 11ty collection-item shape.
+ *
+ * @param {import("@cloudcannon/visual-editor-api").CloudCannonVisualEditorAPIV1File} file
+ */
+async function materialiseFile(file) {
+	const data = (await file.data.get()) ?? {};
+	return {
+		url: resolveUrl(data, file.path),
+		outputPath: resolveOutputPath(data, file.path),
+		inputPath: file.path,
+		fileSlug: deriveFileSlug(file.path),
+		filePathStem: deriveFilePathStem(file.path),
+		date: toDate(/** @type {any} */ (data).date),
+		data,
+	};
+}
+
+/**
+ * Builds the `page` object for the file open in the Visual Editor. Called
+ * before every render so live front-matter edits are reflected immediately.
+ *
+ * @returns {Promise<Record<string, any>>}
+ */
+export async function buildPageData() {
+	await apiLoadedPromise;
+	const file = CloudCannon?.currentFile?.();
+	if (!file) return {};
+	const inputPath = file.path;
+	const data = (await file.data.get()) ?? {};
+	return {
+		inputPath,
+		fileSlug: deriveFileSlug(inputPath),
+		filePathStem: deriveFilePathStem(inputPath),
+		outputFileExtension: "html",
+		url: resolveUrl(data, inputPath),
+		outputPath: resolveOutputPath(data, inputPath),
+		date: toDate(/** @type {any} */ (data).date),
+	};
+}
+
+/**
+ * Ceiling on concurrent `file.data.get()` calls. One call per file over a
+ * collection of thousands fails with `ERR_INSUFFICIENT_RESOURCES` — a net-stack
+ * error, so each resolves to a request somewhere behind the editor API.
+ */
+const MATERIALISE_CONCURRENCY = 24;
+
+/**
+ * `Promise.all(items.map(fn))` with at most `limit` calls in flight. Results
+ * keep their input order.
+ *
+ * @template T, R
+ * @param {T[]} items
+ * @param {(item: T) => Promise<R>} fn
+ * @param {number} limit
+ * @returns {Promise<R[]>}
+ */
+async function mapWithConcurrency(items, fn, limit) {
+	/** @type {R[]} */
+	const results = new Array(items.length);
+	let cursor = 0;
+
+	const worker = async () => {
+		while (cursor < items.length) {
+			const index = cursor++;
+			results[index] = await fn(items[index]);
+		}
+	};
+
+	await Promise.all(
+		Array.from({ length: Math.min(limit, items.length) }, worker),
+	);
+	return results;
+}
+
+/** One `CloudCannon.collections()` call, keyed by name. @type {Promise<Map<string, any>> | null} */
+let collectionIndexCache = null;
+
+/** Materialised items, per collection name. @type {Map<string, Promise<any[]>>} */
+const collectionItemsCache = new Map();
+
+/** @type {Promise<Record<string, any>> | null} */
+let collectionsCache = null;
+
+/** @type {Array<{ target: any, event: "change" | "delete", handler: () => void }>} */
+let collectionsSubscriptions = [];
+
+/**
+ * Enumerates the site's collections — one API call, cached — and subscribes to
+ * `change`/`delete` on each so an edit drops the caches. Never calls
+ * `collection.items()`: knowing the *names* is what lets the getters be
+ * enumerable without fetching behind them.
+ *
+ * @returns {Promise<Map<string, any>>}
+ */
+function loadCollectionIndex() {
+	if (!collectionIndexCache) {
+		collectionIndexCache = (async () => {
+			await apiLoadedPromise;
+			const allCollections = await CloudCannon?.collections?.();
+
+			/** @type {Map<string, any>} */
+			const index = new Map();
+			if (!allCollections?.length) return index;
+
+			for (const collection of allCollections) {
+				index.set(collection.collectionKey, collection);
+
+				const handler = () => resetCollectionsCache();
+				collection.addEventListener("change", handler);
+				collection.addEventListener("delete", handler);
+				collectionsSubscriptions.push(
+					{ target: collection, event: "change", handler },
+					{ target: collection, event: "delete", handler },
+				);
+			}
+			return index;
+		})();
+	}
+	return collectionIndexCache;
+}
+
+/**
+ * Materialises one collection's files, memoised per name — the only place that
+ * issues per-file requests. An unknown name is `[]`, matching 11ty.
+ *
+ * @param {string} key
+ * @returns {Promise<any[]>}
+ */
+function loadCollectionItems(key) {
+	let items = collectionItemsCache.get(key);
+	if (!items) {
+		items = (async () => {
+			const collection = (await loadCollectionIndex()).get(key);
+			if (!collection) return [];
+
+			let files;
+			try {
+				files = await collection.items();
+			} catch {
+				return [];
+			}
+			return mapWithConcurrency(
+				files,
+				materialiseFile,
+				MATERIALISE_CONCURRENCY,
+			);
+		})();
+		collectionItemsCache.set(key, items);
+	}
+	return items;
+}
+
+/**
+ * Builds (or returns cached) the `collections` object. Every key is a lazy
+ * getter returning a `Promise` of its items, which LiquidJS awaits during
+ * expression evaluation — so a component that never mentions `collections`
+ * issues no per-file requests.
+ *
+ * Getters not a Proxy: LiquidJS probes `next` and `toLiquid` on every object
+ * it resolves, and a blanket-getter Proxy answers those with a Promise, which
+ * breaks the lookup entirely.
+ *
+ * @returns {Promise<Record<string, any>>}
+ */
+export function buildCollectionsData() {
+	if (!collectionsCache) {
+		collectionsCache = (async () => {
+			const index = await loadCollectionIndex();
+
+			/** @type {Record<string, any>} */
+			const collections = {};
+			for (const key of index.keys()) {
+				Object.defineProperty(collections, key, {
+					enumerable: true,
+					configurable: true,
+					get: () => loadCollectionItems(key),
+				});
+			}
+			return collections;
+		})();
+	}
+	return collectionsCache;
+}
+
+/** Clears every collections cache and tears down the invalidation listeners. */
+export function resetCollectionsCache() {
+	for (const { target, event, handler } of collectionsSubscriptions) {
+		target.removeEventListener(event, handler);
+	}
+	collectionsSubscriptions = [];
+	collectionIndexCache = null;
+	collectionItemsCache.clear();
+	collectionsCache = null;
+}

package/integrations/liquid/include-with-tag.mjs

@@ -0,0 +1,84 @@
+// `includeWith` tag — spreads an object into a Liquid `{% include %}` the way
+// Astro's `{...props}` does. Kept in its own file so the Node-side Eleventy
+// plugin can import it without pulling in browser-runtime modules.
+
+import { evalToken, Tokenizer, toPromise } from "liquidjs";
+import { enhanceLiquidError } from "./errors.mjs";
+import { group, groupEnd, log } from "./logger.mjs";
+
+/**
+ * Usage: {% includeWith "path/to/partial", objectToSpread %}
+ *
+ * @param {any} _liquidEngine - Unused; engine reached via `this.liquid`
+ * @returns {any}
+ */
+export function createIncludeWithTag(_liquidEngine) {
+	return {
+		parse(/** @type {any} */ tagToken) {
+			const tokenizer = new Tokenizer(
+				tagToken.args,
+				this.liquid.options.operatorsTrie,
+			);
+
+			this.pathToken = tokenizer.readValue();
+			if (!this.pathToken) {
+				throw new Error("includeWith: missing path argument");
+			}
+
+			tokenizer.skipBlank();
+			if (tokenizer.peek() !== ",") {
+				throw new Error("includeWith: expected comma separator");
+			}
+			tokenizer.advance();
+			tokenizer.skipBlank();
+
+			this.objectToken = tokenizer.readValue();
+			if (!this.objectToken) {
+				throw new Error("includeWith: missing object argument");
+			}
+		},
+
+		async render(/** @type {any} */ context) {
+			group("includeWith rendering");
+			const path = await toPromise(evalToken(this.pathToken, context));
+			log("Path resolved to:", path);
+
+			const obj = await toPromise(evalToken(this.objectToken, context));
+			log("Object resolved to:", obj);
+
+			if (!path || typeof path !== "string") {
+				groupEnd();
+				throw new Error(`includeWith: invalid path "${path}"`);
+			}
+			if (!obj || typeof obj !== "object") {
+				groupEnd();
+				return;
+			}
+
+			log(
+				"Including:",
+				path,
+				"with",
+				Object.keys(obj).length,
+				"props:",
+				Object.keys(obj),
+			);
+
+			context.push(obj);
+			try {
+				const templates = await this.liquid.parseFile(path);
+				const result = await this.liquid.render(templates, context);
+				log("Rendered result preview:", result?.substring?.(0, 200) || result);
+				groupEnd();
+				return result;
+			} catch (err) {
+				const error = /** @type {Error} */ (err);
+				log("Error during render:", error.message);
+				groupEnd();
+				throw enhanceLiquidError(err, `includeWith "${path}"`);
+			} finally {
+				context.pop();
+			}
+		},
+	};
+}