@cloudcannon/editable-regions 0.0.18 → 0.0.20-rc.1

package/integrations/liquid/globals.mjs

@@ -1,6 +1,7 @@
 // Builders for the `page` and `collections` globals on the shared Liquid
-// engine. Both return Promises that LiquidJS awaits at the globals level;
-// property access in templates is then synchronous on the resolved objects.
+// 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";
@@ -135,7 +136,13 @@ async function materialiseFile(file) {
  */
 export async function buildPageData() {
 	await apiLoadedPromise;
-	const file = CloudCannon?.currentFile?.();
+	let file;
+	try {
+		file = CloudCannon?.currentFile?.();
+	} catch {
+		// No current file (page with no associated source).
+		return {};
+	}
 	if (!file) return {};
 	const inputPath = file.path;
 	const data = (await file.data.get()) ?? {};
@@ -150,27 +157,74 @@ export async function buildPageData() {
 	};
 }
 
-/** @type {Promise<Record<string, Array<any>>> | null} */
+/**
+ * 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 = [];
 
 /**
- * Builds (or returns cached) the `collections` object, keyed by collection
- * name. Subscribes to `change`/`delete` on each collection and drops the cache
- * when either fires, so edits during a session are picked up on the next render.
+ * 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<Record<string, Array<any>>>}
+ * @returns {Promise<Map<string, any>>}
  */
-export function buildCollectionsData() {
-	if (!collectionsCache) {
-		collectionsCache = (async () => {
+function loadCollectionIndex() {
+	if (!collectionIndexCache) {
+		collectionIndexCache = (async () => {
 			await apiLoadedPromise;
 			const allCollections = await CloudCannon?.collections?.();
-			if (!allCollections?.length) return {};
+
+			/** @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);
@@ -179,31 +233,82 @@ export function buildCollectionsData() {
 					{ 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 [];
 
-			const entries = await Promise.all(
-				allCollections.map(async (collection) => {
-					const key = collection.collectionKey;
-					let files;
-					try {
-						files = await collection.items();
-					} catch {
-						return /** @type {[string, any[]]} */ ([key, []]);
-					}
-					const items = await Promise.all(files.map(materialiseFile));
-					return /** @type {[string, any[]]} */ ([key, items]);
-				}),
+			let files;
+			try {
+				files = await collection.items();
+			} catch {
+				return [];
+			}
+			return mapWithConcurrency(
+				files,
+				materialiseFile,
+				MATERIALISE_CONCURRENCY,
 			);
-			return Object.fromEntries(entries);
+		})();
+		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 the collections cache and tears down its invalidation listeners. */
+/** 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/index.mjs

@@ -73,8 +73,11 @@ export function registerLiquidComponent(key, contents) {
 /**
  * Wraps `window.cc_components` in a Proxy that resolves any component name on
  * demand via `{% include %}` — the primary resolution path. Names registered
- * via `registerLiquidComponent` take precedence. Call after
- * `createSharedLiquidEngine()`.
+ * via `registerLiquidComponent` take precedence.
+ *
+ * Call after `createSharedLiquidEngine()` and last of the `register*` calls:
+ * publishing `cc_components` is what tells the editor every helper is in
+ * place, and an empty one reads as a missing registration script.
  *
  * @returns {void}
  */

package/integrations/vue.mjs

@@ -0,0 +1,28 @@
+import { createApp, h } from "vue";
+import { addEditableComponentRenderer } from "../helpers/cloudcannon.mjs";
+
+/**
+ * Registers a Vue component with the CloudCannon component system.
+ * Creates a wrapper that renders the Vue component to an HTMLElement.
+ *
+ * @param {string} key - Unique identifier for the component
+ * @param {any} component - The Vue component to register
+ * @returns {void}
+ */
+export const registerVueComponent = (key, component) => {
+	/**
+	 * Wrapper function that renders the Vue component to an HTMLElement.
+	 *
+	 * @param {any} props - Props to pass to the Vue component
+	 * @returns {HTMLElement} The rendered component as an HTMLElement
+	 */
+	const wrappedComponent = (props) => {
+		const rootEl = document.createElement("div");
+		const app = createApp({ render: () => h(component, props) });
+		app.mount(rootEl);
+
+		return rootEl;
+	};
+
+	addEditableComponentRenderer(key, wrappedComponent);
+};

package/nodes/editable-array-item.ts

@@ -1,7 +1,6 @@
 import "../components/ui/editable-array-item-controls.js";
 import type EditableArrayItemControls from "../components/ui/editable-array-item-controls.js";
 import {
-	hasEditableArrayItem,
 	isEditableArray,
 	isEditableArrayItem,
 	isEditableElement,
@@ -10,6 +9,12 @@ import { CloudCannon, realizeAPIValue } from "../helpers/cloudcannon.mjs";
 import type EditableArray from "./editable-array.js";
 import EditableComponent from "./editable-component.js";
 
+export const hasEditableArrayItem = <T extends object>(
+	el: T,
+): el is T & { editable: EditableArrayItem } => {
+	return "editable" in el && el.editable instanceof EditableArrayItem;
+};
+
 export default class EditableArrayItem extends EditableComponent {
 	parent: EditableArray | null = null;
 

package/nodes/editable-component.ts

@@ -1,11 +1,10 @@
 import {
 	areEqualEditables,
-	hasEditable,
-	hasEditableText,
 	isEditableElement,
 	isEditableText,
 } from "../helpers/checks.js";
-import Editable from "./editable.js";
+import Editable, { hasEditable } from "./editable.js";
+import { hasEditableText } from "./editable-text.js";
 import "../components/ui/editable-region-error-card.js";
 import "../components/ui/editable-component-controls.js";
 import type EditableComponentControls from "../components/ui/editable-component-controls.js";

package/nodes/editable-text.ts

@@ -3,6 +3,12 @@ import Editable from "./editable.js";
 
 type EditableFocusEvent = CustomEvent<number>;
 
+export const hasEditableText = <T extends object>(
+	el: T,
+): el is T & { editable: EditableText } => {
+	return "editable" in el && el.editable instanceof EditableText;
+};
+
 export default class EditableText extends Editable {
 	editor?: any;
 	focused = false;

package/nodes/editable.ts

@@ -3,9 +3,14 @@ import type {
 	CloudCannonVisualEditorAPIV1Dataset,
 	CloudCannonVisualEditorAPIV1File,
 } from "@cloudcannon/visual-editor-api";
-import { hasEditable } from "../helpers/checks";
 import { apiLoadedPromise, CloudCannon } from "../helpers/cloudcannon.mjs";
 
+export const hasEditable = <T extends object>(
+	el: T,
+): el is T & { editable: Editable } => {
+	return "editable" in el && el.editable instanceof Editable;
+};
+
 declare global {
 	interface HTMLElement {
 		__pendingEditableListeners?: EditableListener[];

package/package.json

@@ -1,92 +1,134 @@
 {
-	"name": "@cloudcannon/editable-regions",
-	"version": "0.0.18",
-	"type": "module",
-	"description": "Visual Editing for the CloudCannon CMS.",
-	"keywords": [
-		"cloudcannon"
-	],
-	"license": "MIT",
-	"author": "CloudCannon <support@cloudcannon.com>",
-	"homepage": "https://github.com/CloudCannon/editable-regions#readme",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/CloudCannon/editable-regions.git"
-	},
-	"bugs": {
-		"url": "https://github.com/CloudCannon/editable-regions/issues",
-		"email": "support@cloudcannon.com"
-	},
-	"scripts": {
-		"typecheck": "tsc --noEmit",
-		"typecheck:watch": "tsc --noEmit --watch",
-		"lint-autofix": "biome check --fix",
-		"lint": "biome check"
-	},
-	"files": [
-		"components",
-		"helpers",
-		"integrations",
-		"nodes",
-		"styles",
-		"types"
-	],
-	"exports": {
-		"./*": null,
-		"./astro": {
-			"types": "./types/astro.d.ts",
-			"default": "./integrations/astro/index.mjs"
-		},
-		"./astro-react-renderer": {
-			"types": "./types/astro.d.ts",
-			"default": "./integrations/astro/react-renderer.mjs"
-		},
-		"./astro-integration": {
-			"types": "./types/astro.d.ts",
-			"default": "./integrations/astro/astro-integration.mjs"
-		},
-		"./react": {
-			"types": "./types/react.d.ts",
-			"default": "./integrations/react.mjs"
-		},
-		"./svelte": {
-			"types": "./types/svelte.d.ts",
-			"default": "./integrations/svelte.mjs"
-		},
-		"./astro-svelte-renderer": {
-			"types": "./types/astro.d.ts",
-			"default": "./integrations/astro/svelte-renderer.mjs"
-		},
-		"./liquid": "./integrations/liquid/index.mjs",
-		"./eleventy": {
-			"require": {
-				"types": "./types/eleventy.d.cts",
-				"default": "./integrations/eleventy/index.cjs"
-			},
-			"import": {
-				"types": "./types/eleventy.d.ts",
-				"default": "./integrations/eleventy/index.mjs"
-			}
-		},
-		"./eleventy/browser": "./integrations/eleventy/browser/index.mjs",
-		"./internal/components": "./components/index.js",
-		"./internal/styles": "./styles/index.js"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "2.5.3",
-		"@cloudcannon/visual-editor-api": "0.0.19",
-		"@sindresorhus/slugify": "3.0.0",
-		"@types/js-beautify": "1.14.3",
-		"@types/node": "26.1.1",
-		"@types/react": "19.2.17",
-		"@types/react-dom": "19.2.3",
-		"astro": "7.0.7",
-		"js-beautify": "2.0.3",
-		"liquidjs": "10.27.2",
-		"slugify": "1.6.9",
-		"typescript": "6.0.3"
-	},
-	"dependencies": {
-		"esbuild": "0.28.1"
-	}
+  "name": "@cloudcannon/editable-regions",
+  "version": "0.0.20-rc.1",
+  "type": "module",
+  "description": "Visual Editing for the CloudCannon CMS.",
+  "keywords": [
+    "cloudcannon"
+  ],
+  "license": "MIT",
+  "author": "CloudCannon <support@cloudcannon.com>",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "homepage": "https://github.com/CloudCannon/editable-regions#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CloudCannon/editable-regions.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CloudCannon/editable-regions/issues",
+    "email": "support@cloudcannon.com"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "typecheck:watch": "tsc --noEmit --watch",
+    "lint-autofix": "biome check --fix",
+    "lint": "biome check",
+    "build:hugo": "bash integrations/hugo/renderer/build.sh",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:update-snapshots": "vitest run -u",
+    "test:build-fixtures": "npm run test:build-astro-fixture && npm run test:build-eleventy-fixture && npm run test:build-eleventy-plugin-config && npm run test:build-hugo-fixture && npm run test:build-hugo-custom-dirs && npm run test:build-hugo-config-options && npm run test:build-hugo-templates-overrides",
+    "test:build-hugo-custom-dirs": "npm --prefix test/unit/_fixtures/hugo-custom-dirs run build",
+    "test:build-hugo-config-options": "npm --prefix test/unit/_fixtures/hugo-config-options run build",
+    "test:build-hugo-templates-overrides": "npm --prefix test/unit/_fixtures/hugo-templates-overrides run build",
+    "test:build-hugo-fixtures": "npm run test:build-hugo-fixture && npm run test:build-hugo-custom-dirs && npm run test:build-hugo-config-options && npm run test:build-hugo-templates-overrides",
+    "test:build-astro-fixture": "npm --prefix test/unit/_fixtures/astro install --silent && npm --prefix test/unit/_fixtures/astro run build",
+    "test:build-eleventy-fixture": "npm --prefix test/unit/_fixtures/eleventy install --silent && npm --prefix test/unit/_fixtures/eleventy run build",
+    "test:build-eleventy-plugin-config": "npm --prefix test/unit/_fixtures/eleventy-plugin-config install --silent && npm --prefix test/unit/_fixtures/eleventy-plugin-config run build",
+    "test:build-hugo-fixture": "npm --prefix test/unit/_fixtures/hugo run build"
+  },
+  "files": [
+    "components",
+    "helpers",
+    "integrations",
+    "nodes",
+    "styles",
+    "types",
+    "!integrations/hugo/renderer/hugo_renderer.wasm",
+    "!integrations/hugo/hugo-module/assets/_cloudcannon"
+  ],
+  "exports": {
+    "./*": null,
+    "./astro": {
+      "types": "./types/astro.d.ts",
+      "default": "./integrations/astro/index.mjs"
+    },
+    "./astro-react-renderer": {
+      "types": "./types/astro.d.ts",
+      "default": "./integrations/astro/react-renderer.mjs"
+    },
+    "./astro-svelte-renderer": {
+      "types": "./types/astro.d.ts",
+      "default": "./integrations/astro/svelte-renderer.mjs"
+    },
+    "./astro-vue-renderer": {
+      "types": "./types/astro.d.ts",
+      "default": "./integrations/astro/vue-renderer.mjs"
+    },
+    "./astro-integration": {
+      "types": "./types/astro.d.ts",
+      "default": "./integrations/astro/astro-integration.mjs"
+    },
+    "./react": {
+      "types": "./types/react.d.ts",
+      "default": "./integrations/react.mjs"
+    },
+    "./svelte": {
+      "types": "./types/svelte.d.ts",
+      "default": "./integrations/svelte.mjs"
+    },
+    "./vue": {
+      "types": "./types/vue.d.ts",
+      "default": "./integrations/vue.mjs"
+    },
+    "./liquid": "./integrations/liquid/index.mjs",
+    "./eleventy": {
+      "require": {
+        "types": "./types/eleventy.d.cts",
+        "default": "./integrations/eleventy/index.cjs"
+      },
+      "import": {
+        "types": "./types/eleventy.d.ts",
+        "default": "./integrations/eleventy/index.mjs"
+      }
+    },
+    "./eleventy/browser": "./integrations/eleventy/browser/index.mjs",
+    "./hugo/browser": {
+      "types": "./types/hugo.d.ts",
+      "default": "./integrations/hugo/browser/index.ts"
+    },
+    "./internal/components": "./components/index.js",
+    "./internal/styles": "./styles/index.js"
+  },
+  "devDependencies": {
+    "@astrojs/react": "6.0.2",
+    "@astrojs/svelte": "9.0.1",
+    "@astrojs/vue": "7.0.2",
+    "@biomejs/biome": "2.5.8",
+    "@cloudcannon/visual-editor-api": "0.0.20",
+    "@sindresorhus/slugify": "3.0.0",
+    "@sveltejs/vite-plugin-svelte": "7.3.0",
+    "@types/js-beautify": "1.14.3",
+    "@types/node": "26.2.0",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "@vitejs/plugin-vue": "6.0.8",
+    "astro": "7.2.2",
+    "happy-dom": "20.11.2",
+    "js-beautify": "2.0.3",
+    "liquidjs": "10.29.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "slugify": "1.6.9",
+    "svelte": "5.56.9",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10",
+    "vue": "3.5.41",
+    "vue-tsc": "3.3.10"
+  },
+  "dependencies": {
+    "esbuild": "0.28.2"
+  }
 }

package/types/astro.d.ts

@@ -21,3 +21,7 @@ declare module "@cloudcannon/editable-regions/astro-react-renderer" {
 declare module "@cloudcannon/editable-regions/astro-svelte-renderer" {
 	// Side-effect only module that registers Svelte renderer
 }
+
+declare module "@cloudcannon/editable-regions/astro-vue-renderer" {
+	// Side-effect only module that registers Vue renderer
+}

package/types/eleventy.d.ts

@@ -17,10 +17,17 @@ export interface LiquidOptions {
 	configPath?: string;
 	/**
 	 * Extra bare module specifiers to stub out of the browser bundle, on top of
-	 * the 11ty toolchain and Node built-ins (always stubbed). Use this when the
-	 * config imports a native/Node-only package (e.g. `sharp`) that no
-	 * browser-bound helper actually calls at render time but that would
-	 * otherwise break bundling.
+	 * the 11ty toolchain and Node built-ins (always stubbed). Two uses:
+	 *
+	 * - a native/Node-only package (e.g. `sharp`) that would otherwise break
+	 *   bundling;
+	 * - a Node-only package the config *calls* at config time, such as a
+	 *   plugin factory in `addPlugin(pluginFoo({ … }))`. The argument is
+	 *   evaluated before `addPlugin` is reached, so stubbing the module is the
+	 *   only way to stop it aborting the auto-mirror replay.
+	 *
+	 * A stubbed module called during the replay is skipped with a warning; the
+	 * same call from a rendered helper still throws.
 	 */
 	browserStub?: string[];
 	/**

package/types/hugo.d.ts

@@ -0,0 +1,69 @@
+import type {
+	CloudCannonVisualEditorAPIRouter,
+	CloudCannonVisualEditorAPIV0,
+	CloudCannonVisualEditorAPIV1,
+} from "@cloudcannon/visual-editor-api";
+
+declare module "@cloudcannon/editable-regions/hugo/browser" {
+	/**
+	 * Boots Hugo live editing from the `window.cc_hugo*` globals emitted by
+	 * the Hugo module's snapshot prelude. Installs the component proxy
+	 * immediately; the WASM renderer loads once the CloudCannon Visual Editor
+	 * API appears.
+	 */
+	export function initHugoLiveEditing(): void;
+
+	/** Starts (or returns the in-flight start of) the WASM renderer. */
+	export function ensureEngine(): Promise<void>;
+
+	/**
+	 * Wraps `window.cc_components` in a Proxy manufacturing a renderer for
+	 * any component name on demand; partial existence is decided by the Hugo
+	 * renderer at render time. Called by `initHugoLiveEditing`.
+	 */
+	export function initComponentProxy(): void;
+}
+
+declare global {
+	/** Snapshot metadata emitted onto `window.cc_hugo` by the module's prelude. */
+	interface HugoRuntimeMeta {
+		generator?: string;
+		wasmUrl?: string;
+		verbose?: boolean;
+		env?: string;
+	}
+
+	/** Result from the editor-site mutation entry points. */
+	interface HugoEditorResult {
+		error?: string;
+	}
+
+	/** Result from `renderHugoPartials`. */
+	interface HugoRenderResult {
+		html?: string;
+		error?: string;
+	}
+
+	/**
+	 * The Hugo runtime's `window` doubles as the CloudCannon Visual Editor
+	 * window and carries the snapshot globals emitted by the module's prelude.
+	 */
+	interface Window {
+		/** CloudCannon's versioned API router (present inside the Visual Editor). */
+		CloudCannonAPI?: CloudCannonVisualEditorAPIRouter;
+		/** The installed v0/v1 CloudCannon API for this page. */
+		CloudCannon?: CloudCannonVisualEditorAPIV0 | CloudCannonVisualEditorAPIV1;
+		/** Emitter metadata: generator, wasmUrl, verbose, env. */
+		cc_hugo?: HugoRuntimeMeta;
+		/** Template/config snapshot keyed by physical path. */
+		cc_hugo_files?: Record<string, string>;
+	}
+
+	// The Hugo WASM renderer exposes these functions on `globalThis` once it
+	// boots; the runtime calls them directly after the engine is ready.
+	function writeHugoFiles(json: string): HugoEditorResult | null;
+	function removeHugoFiles(json: string): HugoEditorResult | null;
+	function readHugoFiles(json: string): Record<string, string>;
+	function initHugoEditorSite(): HugoEditorResult | null;
+	function renderHugoPartials(json: string): HugoRenderResult | null;
+}

package/types/liquid.d.ts

@@ -31,7 +31,6 @@ declare module "@cloudcannon/editable-regions/liquid" {
 		name: string,
 		factory: (liquidEngine: Liquid) => any,
 	): void;
-	export function registerProcessEnv(env: Record<string, string>): void;
 	export function registerEleventyData(data: {
 		version: string;
 		generator: string;