@cloudcannon/editable-regions 0.0.16 → 0.0.18

package/helpers/cloudcannon.mjs

@@ -20,10 +20,7 @@ const extendedWindow = /** @type {any} */ (window);
 /** @type {CloudCannonVisualEditorAPIV1} */
 let _cloudcannon;
 
-/**
- * Promise that resolves when the CloudCannon API is loaded
- * @type {Promise<void>}
- */
+/** @type {Promise<void>} */
 export const apiLoadedPromise = new Promise((resolve) => {
 	if (extendedWindow.CloudCannonAPI) {
 		_cloudcannon = /** @type {any} */ (
@@ -47,10 +44,8 @@ export const apiLoadedPromise = new Promise((resolve) => {
 });
 
 /**
- * Add a renderer for editable components
- * @param {string} key - The component key
- * @param {ComponentRenderer} renderer - The component renderer function
- * @returns {void}
+ * @param {string} key
+ * @param {ComponentRenderer} renderer
  */
 export const addEditableComponentRenderer = (key, renderer) => {
 	extendedWindow.cc_components = extendedWindow.cc_components || {};
@@ -58,33 +53,23 @@ export const addEditableComponentRenderer = (key, renderer) => {
 };
 
 /**
- * Add a renderer for editable snippets
- * @param {string} key - The snippet key
- * @param {ComponentRenderer} renderer - The snippet renderer function
- * @returns {void}
+ * @param {string} key
+ * @param {ComponentRenderer} renderer
  */
 export const addEditableSnippetRenderer = (key, renderer) => {
 	extendedWindow.cc_snippets = extendedWindow.cc_snippets || {};
 	extendedWindow.cc_snippets[key] = renderer;
 };
 
-/**
- * Get all registered editable component renderers
- * @returns {Record<string, ComponentRenderer>}
- */
 export const getEditableComponentRenderers = () =>
 	extendedWindow.cc_components ?? {};
 
-/**
- * Get all registered editable snippet renderers
- * @returns {Record<string, ComponentRenderer>}
- */
 export const getEditableSnippetRenderers = () =>
 	extendedWindow.cc_snippets ?? {};
 
 /**
- * Realize API values by converting CloudCannon API objects to their data representations
- * @param {unknown} value - The value to realize
+ * Resolves CloudCannon API objects (collections, files, datasets) to plain data.
+ * @param {unknown} value
  * @returns {Promise<unknown>}
  */
 export const realizeAPIValue = async (value) => {

package/integrations/astro/astro-integration.mjs

@@ -4,10 +4,7 @@ import { fileURLToPath } from "node:url";
 /** @type{string[]} */
 const SUPPORTED_VIRTUAL_MODULES = ["assets", "content"];
 
-/**
- * @param {*} original
- * @returns
- */
+/** @param {*} original */
 function wrapTransform(original) {
 	/**
 	 * @this {*}

package/integrations/astro/index.mjs

@@ -4,30 +4,21 @@ import {
 } from "astro/runtime/server/index.js";
 import { addEditableComponentRenderer } from "../../helpers/cloudcannon.mjs";
 
-/**
- * Queue of React components waiting to be rendered
- * @type {((node: Element) => void)[]}
- */
+/** @type {((node: Element) => void)[]} */
 const renderRoots = [];
 
 const renderers = [
 	{
 		name: "dynamic-tags",
 		ssr: {
-			/**
-			 * Checks if the component is a string (HTML tag name).
-			 * @param {any} Component - The component to check
-			 * @returns {boolean} True if component is a string tag name
-			 */
+			/** @param {any} Component */
 			check: (Component) => {
 				return typeof Component === "string";
 			},
 			/**
-			 * Renders a dynamic HTML tag with props and slots.
-			 * @param {string} Component - The HTML tag name
-			 * @param {Record<string, any>} props - Props to render as attributes
-			 * @param {Record<string, string>} slots - Slot content
-			 * @returns {Promise<string>} The rendered HTML string
+			 * @param {string} Component - HTML tag name
+			 * @param {Record<string, any>} props
+			 * @param {Record<string, string>} slots
 			 */
 			renderToStaticMarkup: async (Component, props, slots) => {
 				const propsString = Object.entries(props)
@@ -57,25 +48,19 @@ export const queueForClientSideRender = (renderFunction) => {
 };
 
 /**
- * Registers an Astro component with the CloudCannon component system.
- * Creates a wrapper that handles Astro SSR rendering with React hydration support.
+ * Registers an Astro component, wrapping it to render via Astro SSR with
+ * React hydration support.
  *
- * @param {string} key - Unique identifier for the component
- * @param {unknown} component - The Astro component function to register
- * @returns {void}
+ * @param {string} key
+ * @param {unknown} component
  */
 export const registerAstroComponent = (key, component) => {
 	/**
-	 * Wrapper function that renders the Astro component with SSR and client-side hydration.
-	 *
-	 * @param {any} props - Props to pass to the Astro component
-	 * @returns {Promise<HTMLElement>} The rendered component as an HTMLElement
+	 * @param {any} props
+	 * @returns {Promise<HTMLElement>}
 	 */
 	const wrappedComponent = async (props) => {
-		/**
-		 * Encryption key for Astro server islands
-		 * @type {CryptoKey | undefined}
-		 */
+		/** @type {CryptoKey | undefined} Encryption key for Astro server islands */
 		let encryptionKey;
 		try {
 			encryptionKey = await window.crypto.subtle.generateKey(
@@ -130,9 +115,7 @@ export const registerAstroComponent = (key, component) => {
 			slots: {},
 			props,
 			resolve: () => "editable-region-placeholder",
-			/**
-			 * @param {*} args
-			 */
+			/** @param {*} args */
 			createAstro(...args) {
 				if (args.length < 2 || args.length > 3) {
 					console.warn(
@@ -150,18 +133,12 @@ export const registerAstroComponent = (key, component) => {
 				}
 
 				const astroSlots = {
-					/**
-					 * @param {string} name
-					 * @returns boolean
-					 */
+					/** @param {string} name */
 					has: (name) => {
 						if (!componentSlots) return false;
 						return Boolean(componentSlots[name]);
 					},
-					/**
-					 * @param {string} name
-					 * @returns string
-					 */
+					/** @param {string} name */
 					render: (name) => {
 						return renderSlotToString(SSRResult, componentSlots[name]);
 					},
@@ -174,7 +151,6 @@ export const registerAstroComponent = (key, component) => {
 				};
 			},
 		};
-		// Render the Astro component to HTML string
 		const result = await renderToString(SSRResult, component, props, {});
 		const doc = document.implementation.createHTMLDocument();
 		doc.body.innerHTML = result;
@@ -184,7 +160,6 @@ export const registerAstroComponent = (key, component) => {
 			renderRoots[csrId]?.(node);
 		});
 
-		// Clear the React roots queue
 		renderRoots.length = 0;
 
 		doc.querySelectorAll("link, [data-island-id]").forEach((node) => {
@@ -201,6 +176,5 @@ export const registerAstroComponent = (key, component) => {
 		return doc.body;
 	};
 
-	// Register the wrapped component in the global registry
 	addEditableComponentRenderer(key, wrappedComponent);
 };

package/integrations/astro/modules/assets.js

@@ -4,10 +4,7 @@ import PictureInternal from "./picture.astro";
 export const Image = ImageInternal;
 export const Picture = PictureInternal;
 
-/**
- * @param {{src: any }} options
- * @returns
- */
+/** @param {{src: any }} options */
 export const getImage = async (options) => {
 	const resolvedSrc =
 		typeof options.src === "object" && "then" in options.src

package/integrations/astro/modules/content.js

@@ -47,10 +47,8 @@ export const getCollection = async (collectionKey, filter) => {
 };
 
 /**
- *
  * @param {string | {collection: string, slug?: string, id?: string}} objOrString
  * @param {string} [maybeString]
- * @returns
  */
 export const getEntry = async (objOrString, maybeString) => {
 	if (typeof objOrString === "object") {
@@ -85,10 +83,7 @@ export const getEntry = async (objOrString, maybeString) => {
 	);
 };
 
-/**
- * @param {{collection: string, slug?: string, id?: string}[]} entries
- * @returns
- */
+/** @param {{collection: string, slug?: string, id?: string}[]} entries */
 export const getEntries = (entries) => {
 	return Promise.all(entries.map((entry) => getEntry(entry)));
 };
@@ -96,16 +91,12 @@ export const getEntries = (entries) => {
 /**
  * @param {string} collection
  * @param {string} slug
- * @returns
  */
 export const getEntryBySlug = (collection, slug) => {
 	return getEntry({ collection, slug });
 };
 
-/**
- * @param {any} entry
- * @returns
- */
+/** @param {any} entry */
 export const render = async (entry) => ({
 	Content: () => entry?.body ?? "Content is not available when live editing",
 	headings: [],

package/integrations/astro/react-renderer.mjs

@@ -30,10 +30,10 @@ addFrameworkRenderer({
 			}
 		},
 		/**
-		 * Renders a React component to static markup or queues for client-side rendering.
-		 * @param {any} Component - The React component function
-		 * @param {any} props - Props to pass to the component
-		 * @returns {Promise<{ html: string }>} Object containing the rendered HTML
+		 * Renders to static markup, falling back to a client-side render queue.
+		 * @param {any} Component
+		 * @param {any} props
+		 * @returns {Promise<{ html: string }>}
 		 */
 		renderToStaticMarkup: async (Component, props) => {
 			try {
@@ -45,7 +45,6 @@ addFrameworkRenderer({
 					const root = createRoot(node);
 					flushSync(() => root.render(reactNode));
 				});
-				// Queue for client-side rendering if SSR fails
 				return {
 					html: `<div data-editable-region-csr-id=${id}></div>`,
 				};

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

@@ -0,0 +1,188 @@
+/**
+ * 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 {
+	builtinFilterNames,
+	builtinShortcodeNames,
+} from "./liquid-builtins.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) => void) | null}
+ */
+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(),
+	};
+}
+
+/**
+ * Replays `configFn` against a recording stand-in and registers every
+ * collected helper that isn't skipped.
+ *
+ * @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.
+ */
+export function collectAndRegisterEleventyHelpers(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 methods are no-ops so running the real config (which calls
+	// `addPassthroughCopy`, `on`, sets `dir`, ...) doesn't throw.
+	const configRecorder = new Proxy(recorder, {
+		get(target, prop, receiver) {
+			if (prop in target) return Reflect.get(target, prop, receiver);
+			return () => {};
+		},
+	});
+
+	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 {
+			pluginFn(configRecorder, opts);
+		} catch {
+			// Node-only plugins are stubbed at bundle time and throw when called.
+			// Helpers registered before the throw are kept; the config continues.
+		}
+	};
+
+	try {
+		configFn(configRecorder);
+	} catch (err) {
+		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.",
+		);
+	}
+
+	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]]);
+
+		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}.`,
+				);
+			}
+		}
+	}
+}

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";