@cloudcannon/editable-regions 0.0.20-rc.3 → 0.0.20

package/helpers/cloudcannon.mjs

@@ -14,24 +14,26 @@
  * }} ExtendedWindow
  */
 
-/** @type {ExtendedWindow} */
-const extendedWindow = /** @type {any} */ (window);
+/** @type {ExtendedWindow | undefined} */
+const extendedWindow = /** @type {any} */ (
+	typeof window === "undefined" ? undefined : window
+);
 
-/** @type {CloudCannonVisualEditorAPIV1} */
+/** @type {CloudCannonVisualEditorAPIV1 | undefined} */
 let _cloudcannon;
 
 /** @type {Promise<void>} */
 export const apiLoadedPromise = new Promise((resolve) => {
-	if (extendedWindow.CloudCannonAPI) {
+	if (extendedWindow?.CloudCannonAPI) {
 		_cloudcannon = /** @type {any} */ (
 			extendedWindow.CloudCannonAPI.useVersion("v1", true)
 		);
 		resolve();
-	} else {
+	} else if (typeof document !== "undefined") {
 		document.addEventListener(
 			"cloudcannon:load",
 			() => {
-				if (extendedWindow.CloudCannonAPI) {
+				if (extendedWindow?.CloudCannonAPI) {
 					_cloudcannon = /** @type {any} */ (
 						extendedWindow.CloudCannonAPI.useVersion("v1", true)
 					);
@@ -48,6 +50,9 @@ export const apiLoadedPromise = new Promise((resolve) => {
  * @param {ComponentRenderer} renderer
  */
 export const addEditableComponentRenderer = (key, renderer) => {
+	if (!extendedWindow) {
+		return;
+	}
 	extendedWindow.cc_components = extendedWindow.cc_components || {};
 	extendedWindow.cc_components[key] = renderer;
 };
@@ -57,15 +62,18 @@ export const addEditableComponentRenderer = (key, renderer) => {
  * @param {ComponentRenderer} renderer
  */
 export const addEditableSnippetRenderer = (key, renderer) => {
+	if (!extendedWindow) {
+		return;
+	}
 	extendedWindow.cc_snippets = extendedWindow.cc_snippets || {};
 	extendedWindow.cc_snippets[key] = renderer;
 };
 
 export const getEditableComponentRenderers = () =>
-	extendedWindow.cc_components ?? {};
+	extendedWindow?.cc_components ?? {};
 
 export const getEditableSnippetRenderers = () =>
-	extendedWindow.cc_snippets ?? {};
+	extendedWindow?.cc_snippets ?? {};
 
 /**
  * Resolves CloudCannon API objects (collections, files, datasets) to plain data.
@@ -91,13 +99,16 @@ export const realizeAPIValue = async (value) => {
 };
 
 export const addCustomEditableRegion = (key, region) => {
+	if (!extendedWindow || typeof document === "undefined") {
+		return;
+	}
 	extendedWindow.editableRegionMap ??= {};
 	extendedWindow.editableRegionMap[key] = region;
 	extendedWindow.hydrateDataEditableRegions(document.body);
 };
 
 export const getCustomEditableRegions = () => {
-	return extendedWindow.editableRegionMap ?? {};
+	return extendedWindow?.editableRegionMap ?? {};
 };
 
 export { _cloudcannon as CloudCannon };

package/helpers/hydrate-editable-regions.ts

@@ -10,6 +10,8 @@ import {
 import { hasEditable } from "../nodes/editable.js";
 import { isEditableWebcomponent } from "./checks";
 
+const DYNAMIC_EDITABLE_TYPE = "_dynamic";
+
 const baseEditableMap: Record<string, typeof Editable | undefined> = {
 	array: EditableArray,
 	"array-item": EditableArrayItem,
@@ -20,12 +22,23 @@ const baseEditableMap: Record<string, typeof Editable | undefined> = {
 };
 
 export const dehydrateDataEditableRegions = (root: Element) => {
-	if (root instanceof HTMLElement && hasEditable(root)) {
+	if (
+		root instanceof HTMLElement &&
+		hasEditable(root) &&
+		root.dataset.editable !== DYNAMIC_EDITABLE_TYPE
+	) {
 		root.editable.disconnect();
 	}
 
 	root.querySelectorAll("[data-editable]").forEach((element) => {
-		if (element instanceof HTMLElement && hasEditable(element)) {
+		if (
+			!(element instanceof HTMLElement) ||
+			element.dataset.editable === DYNAMIC_EDITABLE_TYPE
+		) {
+			return;
+		}
+
+		if (hasEditable(element)) {
 			element.editable.disconnect();
 		}
 	});
@@ -39,6 +52,7 @@ export const hydrateDataEditableRegions = (root: Element) => {
 	if (
 		root instanceof HTMLElement &&
 		root.dataset.editable &&
+		root.dataset.editable !== DYNAMIC_EDITABLE_TYPE &&
 		!isEditableWebcomponent(root)
 	) {
 		if ("editable" in root && root.editable instanceof Editable) {
@@ -64,6 +78,10 @@ export const hydrateDataEditableRegions = (root: Element) => {
 			return;
 		}
 
+		if (element.dataset.editable === DYNAMIC_EDITABLE_TYPE) {
+			return;
+		}
+
 		const Editable = editableMap[element.dataset.editable];
 		if (!Editable) {
 			const error = document.createElement("editable-region-error-card");
@@ -95,4 +113,19 @@ export const hydrateDataEditableRegions = (root: Element) => {
 	});
 };
 
-(window as any).hydrateDataEditableRegions = hydrateDataEditableRegions;
+const extendedWindow = /** @type {any} */ (window);
+
+Object.assign(extendedWindow, {
+	editableRegions: {
+		Editable,
+		EditableArray,
+		EditableArrayItem,
+		EditableComponent,
+		EditableImage,
+		EditableSource,
+		EditableText,
+	},
+	hydrateDataEditableRegions,
+});
+
+document.dispatchEvent(new CustomEvent("editable-regions:load"));

package/integrations/hugo/browser/errors.ts

@@ -43,7 +43,13 @@ export function parseHugoTemplateError(raw: string): ParsedHugoError {
 	return { frames, call, message: rest };
 }
 
-export function enhanceHugoError(message: string, componentKey: string): Error {
+/** An error enhanced with an optional editor-context hint. */
+export type HugoError = Error & { hint?: string };
+
+export function enhanceHugoError(
+	message: string,
+	componentKey: string,
+): HugoError {
 	const parsed = parseHugoTemplateError(message);
 
 	let hint = "";
@@ -76,7 +82,7 @@ export function enhanceHugoError(message: string, componentKey: string): Error {
 
 	const error = new Error(
 		`Failed to render Hugo component "${componentKey}": ${sentence}`,
-	) as Error & { hint?: string };
+	) as HugoError;
 
 	if (hint) {
 		error.hint = hint;

package/integrations/react.mjs

@@ -1,4 +1,6 @@
-import { createElement } from "react";
+"use client";
+
+import { createElement, useEffect, useRef } from "react";
 import { flushSync } from "react-dom";
 import { createRoot } from "react-dom/client";
 import { addEditableComponentRenderer } from "../helpers/cloudcannon.mjs";
@@ -26,3 +28,63 @@ export const registerReactComponent = (key, component) => {
 
 	addEditableComponentRenderer(key, wrappedComponent);
 };
+
+/**
+ * Root editable region component for React (e.g. Next.js App Router pages).
+ * Keeps editable regions from mutating the DOM before frameworks like Next.js finish hydrating.
+ *
+ * @param {{ tag?: string } & Record<string, any>} props
+ * All other props and attributes are forwarded to the rendered element.
+ */
+export const EditableRegions = ({ tag: Tag = "div", ...attrs }) => {
+	const elementRef = useRef(null);
+	/** @type {{ current: any | null }} */
+	const editableRef = useRef(null);
+
+	useEffect(() => {
+		/** @param {any} regions */
+		const connectEditable = (regions) => {
+			if (!regions || editableRef.current) {
+				return;
+			}
+
+			editableRef.current = new regions.Editable(elementRef.current);
+			editableRef.current.connect();
+		};
+
+		const onLoad = () => {
+			connectEditable(/** @type {any} */ (window).editableRegions);
+		};
+
+		if (/** @type {any} */ (window).editableRegions) {
+			connectEditable(/** @type {any} */ (window).editableRegions);
+		} else {
+			document.addEventListener("editable-regions:load", onLoad, {
+				once: true,
+			});
+		}
+
+		return () => {
+			document.removeEventListener("editable-regions:load", onLoad);
+			editableRef.current?.disconnect();
+			editableRef.current = null;
+		};
+	}, []);
+
+	/** @type {Record<string, any>} */
+	const forwarded = {};
+	for (const [name, value] of Object.entries(attrs)) {
+		if (/^data-(prop|literal)/i.test(name)) {
+			continue;
+		}
+
+		forwarded[name] = value;
+	}
+
+	return createElement(Tag, {
+		...forwarded,
+		ref: elementRef,
+		"data-editable": "_dynamic",
+		"data-prop": "",
+	});
+};

package/integrations/svelte/EditableRegions.svelte

@@ -0,0 +1,80 @@
+<script>
+	import { onDestroy, onMount } from "svelte";
+
+	// Element type to render. Defaults to "div".
+	/** @type {string | undefined} */
+	export let tag = "div";
+
+	/** @type {any} */
+	let editable = null;
+	/** @type {HTMLElement | undefined} */
+	let element;
+	/** @type {(() => void) | null} */
+	let pendingLoadHandler = null;
+
+	// data-prop and data-literal attributes are controlled by this component
+	// itself; user-supplied ones are ignored.
+	$: restProps = filterProps($$restProps);
+
+	function filterProps(props) {
+		const filtered = {};
+		for (const [name, value] of Object.entries(props)) {
+			if (/^data-(prop|literal)/i.test(name)) {
+				continue;
+			}
+
+			filtered[name] = value;
+		}
+		return filtered;
+	}
+
+	onMount(() => {
+		/**
+		 * @param {any} regions
+		 */
+		const connectEditable = (regions) => {
+			if (!regions || editable) {
+				return;
+			}
+
+			editable = new regions.Editable(element);
+			editable.connect();
+		};
+
+		if (window.editableRegions) {
+			connectEditable(window.editableRegions);
+		} else {
+			pendingLoadHandler = () => {
+			    connectEditable(window.editableRegions);
+		    };
+			document.addEventListener(
+				"editable-regions:load",
+				pendingLoadHandler,
+				{ once: true },
+			);
+		}
+	});
+
+	onDestroy(() => {
+		if (pendingLoadHandler) {
+			document.removeEventListener(
+				"editable-regions:load",
+				pendingLoadHandler,
+			);
+			pendingLoadHandler = null;
+		}
+
+		editable?.disconnect();
+		editable = null;
+	});
+</script>
+
+<svelte:element
+	this={tag}
+	{...restProps}
+	bind:this={element}
+	data-editable="_dynamic"
+	data-prop=""
+>
+	<slot />
+</svelte:element>

package/integrations/{svelte.mjs → svelte/index.mjs}

@@ -1,4 +1,6 @@
-import { addEditableComponentRenderer } from "../helpers/cloudcannon.mjs";
+export { default as EditableRegions } from "./EditableRegions.svelte";
+
+import { addEditableComponentRenderer } from "../../helpers/cloudcannon.mjs";
 
 /** @type{((component: any, args: { target: HTMLElement, props: unknown }) => void) | undefined} */
 let mount;

package/integrations/vue.mjs

@@ -1,4 +1,11 @@
-import { createApp, h } from "vue";
+import {
+	createApp,
+	defineComponent,
+	h,
+	onMounted,
+	onUnmounted,
+	ref,
+} from "vue";
 import { addEditableComponentRenderer } from "../helpers/cloudcannon.mjs";
 
 /**
@@ -26,3 +33,92 @@ export const registerVueComponent = (key, component) => {
 
 	addEditableComponentRenderer(key, wrappedComponent);
 };
+
+/**
+ * Root editable region component for Vue.
+ * Keeps editable regions from mutating the DOM before frameworks like Nuxt finish hydrating.
+ *
+ * @param {string} [props.tag] - Element type to render. Defaults to "div".
+ * All other props and attributes are forwarded to the rendered element.
+ */
+export const EditableRegions = defineComponent({
+	name: "EditableRegions",
+	props: {
+		tag: {
+			type: String,
+			default: "div",
+		},
+	},
+	inheritAttrs: false,
+	/**
+	 * @param {{ tag: string }} props
+	 * @param {{ attrs: any; slots: any }} context
+	 */
+	setup(props, { attrs, slots }) {
+		const element = ref(null);
+		/** @type {any} */
+		let editable = null;
+		/** @type {(() => void) | null} */
+		let pendingLoadHandler = null;
+
+		/** @param {any} regions */
+		const connectEditable = (regions) => {
+			if (!regions || editable) {
+				return;
+			}
+
+			editable = new regions.Editable(element.value);
+			editable.connect();
+		};
+
+		onMounted(() => {
+			const regions = /** @type {any} */ (window).editableRegions;
+			if (regions) {
+				connectEditable(regions);
+				return;
+			}
+
+			pendingLoadHandler = () => {
+				connectEditable(/** @type {any} */ (window).editableRegions);
+			};
+			document.addEventListener("editable-regions:load", pendingLoadHandler, {
+				once: true,
+			});
+		});
+
+		onUnmounted(() => {
+			if (pendingLoadHandler) {
+				document.removeEventListener(
+					"editable-regions:load",
+					pendingLoadHandler,
+				);
+				pendingLoadHandler = null;
+			}
+
+			editable?.disconnect();
+			editable = null;
+		});
+
+		return () => {
+			/** @type {Record<string, any>} */
+			const forwarded = {};
+			for (const [name, value] of Object.entries(attrs)) {
+				if (/^data-(prop|literal)/i.test(name)) {
+					continue;
+				}
+				forwarded[name] = value;
+			}
+
+			return h(
+				props.tag,
+				{
+					...forwarded,
+					ref: element,
+					"data-editable": "_dynamic",
+					"data-prop": "",
+				},
+				/** @type {any} */ (slots.default?.()),
+			);
+		};
+	},
+});

package/nodes/editable-array-item.ts

@@ -18,12 +18,16 @@ export const hasEditableArrayItem = <T extends object>(
 export default class EditableArrayItem extends EditableComponent {
 	parent: EditableArray | null = null;
 
-	protected declare controlsElement?: EditableArrayItemControls;
+	declare protected controlsElement?: EditableArrayItemControls;
 
 	private inputConfig?: any;
 	private structureStrings: string[] = [];
 
 	shouldMount(): boolean {
+		if (this.mounted) {
+			return false;
+		}
+
 		return this.value !== undefined;
 	}
 

package/nodes/editable-component.ts

@@ -25,13 +25,19 @@ export default class EditableComponent extends Editable {
 	}
 
 	shouldMount(): boolean {
-		if (super.shouldMount()) {
-			return true;
+		if (this.mounted) {
+			return false;
 		}
 
-		return !Object.keys(this.element.dataset).some((key) =>
-			key.startsWith("prop"),
+		const hasNoProps = Object.keys(this.element.dataset).every(
+			(key) => !key.startsWith("prop"),
 		);
+
+		if (hasNoProps) {
+			return true;
+		}
+
+		return super.shouldMount();
 	}
 
 	validateConfiguration(): boolean {

package/nodes/editable-image.ts

@@ -185,87 +185,92 @@ export default class EditableImage extends Editable {
 		this.configuredTitle =
 			!!this.element.dataset.propTitle || !!this.element.dataset.prop;
 
-		this.loadInputConfig().then(() => {
-			this.imageEl?.addEventListener("click", async (e) => {
-				e.preventDefault();
+		// Loading the input config costs a round trip per configured prop, so the
+		// listener is attached up front and the click waits for it. Attaching after
+		// the load resolves instead leaves a window where clicks are dropped.
+		const inputConfigLoaded = this.loadInputConfig();
 
-				if (!this.value) {
-					throw new Error("Value is not defined");
-				}
+		this.imageEl?.addEventListener("click", async (e) => {
+			e.preventDefault();
 
-				const data: this["value"] = {};
-				if ("src" in this.value) {
-					data.src = this.value.src;
-				}
-				if ("alt" in this.value) {
-					data.alt = this.value.alt;
-				}
-				if ("title" in this.value) {
-					data.title = this.value.title;
-				}
+			await inputConfigLoaded;
 
-				this.panelId = await CloudCannon.createCustomDataPanel({
-					title: "Edit Image",
-					data,
-					position: this.imageEl?.getBoundingClientRect(),
-					config: {
-						_inputs: {
-							src: {
-								label: "Image",
-								type: "image",
-								...this.inputConfig.src,
-							},
-							alt: {
-								comment:
-									"A description which provides information about this image if for some reason it cannot be viewed.",
-								...this.inputConfig.alt,
-							},
-							title: {
-								comment: "Displayed when hovering over the image.",
-								...this.inputConfig.title,
-							},
+			if (!this.value) {
+				throw new Error("Value is not defined");
+			}
+
+			const data: this["value"] = {};
+			if ("src" in this.value) {
+				data.src = this.value.src;
+			}
+			if ("alt" in this.value) {
+				data.alt = this.value.alt;
+			}
+			if ("title" in this.value) {
+				data.title = this.value.title;
+			}
+
+			this.panelId = await CloudCannon.createCustomDataPanel({
+				title: "Edit Image",
+				data,
+				position: this.imageEl?.getBoundingClientRect(),
+				config: {
+					_inputs: {
+						src: {
+							label: "Image",
+							type: "image",
+							...this.inputConfig.src,
+						},
+						alt: {
+							comment:
+								"A description which provides information about this image if for some reason it cannot be viewed.",
+							...this.inputConfig.alt,
+						},
+						title: {
+							comment: "Displayed when hovering over the image.",
+							...this.inputConfig.title,
 						},
 					},
-					onChange: (value): void => {
-						if (!value || typeof value !== "object") {
-							throw new Error("Invalid image data");
-						}
+				},
+				onChange: (value): void => {
+					if (!value || typeof value !== "object") {
+						throw new Error("Invalid image data");
+					}
 
-						if (
-							"src" in value &&
-							this.configuredSrc &&
-							value.src !== this.value?.src
-						) {
-							this.dispatchSet(
-								this.element.dataset.propSrc ??
-									`${this.element.dataset.prop}.src`,
-								value.src,
-							);
-						}
-						if (
-							"alt" in value &&
-							this.configuredAlt &&
-							value.alt !== this.value?.alt
-						) {
-							this.dispatchSet(
-								this.element.dataset.propAlt ??
-									`${this.element.dataset.prop}.alt`,
-								value.alt,
-							);
-						}
-						if (
-							"title" in value &&
-							this.configuredTitle &&
-							value.title !== this.value?.title
-						) {
-							this.dispatchSet(
-								this.element.dataset.propTitle ??
-									`${this.element.dataset.prop}.title`,
-								value.title,
-							);
-						}
-					},
-				});
+					if (
+						"src" in value &&
+						this.configuredSrc &&
+						value.src !== this.value?.src
+					) {
+						this.dispatchSet(
+							this.element.dataset.propSrc ??
+								`${this.element.dataset.prop}.src`,
+							value.src,
+						);
+					}
+					if (
+						"alt" in value &&
+						this.configuredAlt &&
+						value.alt !== this.value?.alt
+					) {
+						this.dispatchSet(
+							this.element.dataset.propAlt ??
+								`${this.element.dataset.prop}.alt`,
+							value.alt,
+						);
+					}
+					if (
+						"title" in value &&
+						this.configuredTitle &&
+						value.title !== this.value?.title
+					) {
+						this.dispatchSet(
+							this.element.dataset.propTitle ??
+								`${this.element.dataset.prop}.title`,
+							value.title,
+						);
+					}
+				},
 			});
 		});
 	}