@cloudcannon/editable-regions 0.0.4 → 0.0.6

package/components/ui/editable-region-button.ts

@@ -0,0 +1,39 @@
+import styleContent from "../../styles/ui/editable-region-button.css?inline";
+
+export default class EditableRegionButton extends HTMLElement {
+	private shadow?: ShadowRoot;
+
+	connectedCallback() {
+		if (this.shadow) {
+			return;
+		}
+
+		this.shadow = this.attachShadow({ mode: "open" });
+
+		this.render(this.shadow);
+	}
+
+	render(shadow: ShadowRoot) {
+		const style = document.createElement("style");
+		style.textContent = styleContent;
+		shadow.appendChild(style);
+
+		const button = document.createElement("button");
+		button.innerHTML = `<cc-icon name='${this.getAttribute("icon")}'></cc-icon>${this.getAttribute("text")}`;
+		shadow.appendChild(button);
+
+		button.addEventListener("click", (e) => {
+			this.dispatchEvent(
+				new CustomEvent("button-click", { detail: { originalEvent: e } }),
+			);
+		});
+	}
+}
+
+customElements.define("editable-region-button", EditableRegionButton);
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"editable-region-button": EditableRegionButton;
+	}
+}

package/components/ui/editable-region-error-card.ts

@@ -65,6 +65,14 @@ export default class EditableRegionErrorCard extends HTMLElement {
 				body.appendChild(stack);
 			}
 		}
+
+		if (this.hasAttribute("hint")) {
+			const hint = document.createElement("p");
+			hint.className = "hint";
+			hint.innerHTML = this.getAttribute("hint") ?? "";
+
+			body.appendChild(hint);
+		}
 	}
 }
 

package/helpers/checks.ts

@@ -101,34 +101,9 @@ export const isEditableArrayItem = (el?: Element | null): boolean => {
 	);
 };
 
-export const areEqualNodes = (a: ChildNode, b: ChildNode) => {
-	if (a.nodeName !== b.nodeName) {
-		return false;
-	}
-
-	if (a instanceof Element && b instanceof Element) {
-		if (a.className !== b.className) {
-			return false;
-		}
-
-		if (a.id !== b.id) {
-			return false;
-		}
-
-		if (a.attributes.length !== b.attributes.length) {
-			return false;
-		}
-
-		for (let i = 0; i < a.attributes.length; i++) {
-			if (
-				a.attributes[i].name !== b.attributes[i].name ||
-				a.attributes[i].value !== b.attributes[i].value
-			) {
-				return false;
-			}
-		}
-
-		return true;
-	}
-	return a.isEqualNode(b);
+export const isEditableArray = (el?: Element | null): boolean => {
+	return (
+		el?.tagName === "EDITABLE-ARRAY" ||
+		(el instanceof HTMLElement && el.dataset.editable === "array")
+	);
 };

package/helpers/hydrate-editable-regions.ts

@@ -52,7 +52,10 @@ export const hydrateDataEditableRegions = (root: Element) => {
 			return;
 		}
 
-		if (!element.dataset.editable || element.dataset.cloudcannonIgnore) {
+		if (
+			typeof element.dataset.editable !== "string" ||
+			typeof element.dataset.cloudcannonIgnore === "string"
+		) {
 			return;
 		}
 
@@ -62,7 +65,17 @@ export const hydrateDataEditableRegions = (root: Element) => {
 			error.setAttribute("heading", "Failed to render editable region");
 			error.setAttribute(
 				"message",
-				`Unrecognized editable type: "${element.dataset.editable}". The supported types are: ${Object.keys(editableMap).join(", ")}`,
+				`This element has an invalid editable type for the 'data-editable' HTML attribute. The supported editable types are ${Object.keys(
+					editableMap,
+				)
+					.map((type) => `"${type}"`)
+					.join(
+						", ",
+					)} but instead received the type "${element.dataset.editable}". Please make sure that this element has a valid "data-editable" attribute.`,
+			);
+			error.setAttribute(
+				"hint",
+				"If this is intentional you can use the 'data-cloudcannon-ignore' attribute to exclude this element from editable regions.",
 			);
 			element.replaceWith(error);
 			return;

package/nodes/editable-array-item.ts

@@ -2,10 +2,12 @@ import "../components/ui/editable-array-item-controls.js";
 import type EditableArrayItemControls from "../components/ui/editable-array-item-controls.js";
 import {
 	hasEditableArrayItem,
+	isEditableArray,
 	isEditableArrayItem,
+	isEditableElement,
 } from "../helpers/checks.js";
 import { CloudCannon, realizeAPIValue } from "../helpers/cloudcannon.js";
-import EditableArray from "./editable-array.js";
+import type EditableArray from "./editable-array.js";
 import EditableComponent from "./editable-component.js";
 
 export default class EditableArrayItem extends EditableComponent {
@@ -14,32 +16,25 @@ export default class EditableArrayItem extends EditableComponent {
 	protected controlsElement?: EditableArrayItemControls;
 
 	private inputConfig?: any;
+	private structureStrings: string[] = [];
 
 	shouldMount(): boolean {
 		return this.value !== undefined;
 	}
 
 	validateConfiguration(): boolean {
-		const key = this.element.dataset.component;
-		if (key) {
-			const component = this.getComponents()[key];
-			if (!component) {
-				this.element.classList.add("errored");
-				const error = document.createElement("editable-region-error-card");
-				error.setAttribute("heading", "Failed to render component");
-				error.setAttribute("message", `Couldn't find component '${key}'`);
-				this.element.replaceChildren(error);
-				return false;
-			}
+		let parentElement = this.element.parentElement;
+		while (parentElement && !isEditableElement(parentElement)) {
+			parentElement = parentElement.parentElement;
 		}
 
-		if (!this.parent || !(this.parent instanceof EditableArray)) {
+		if (!parentElement || !isEditableArray(parentElement)) {
 			this.element.classList.add("errored");
 			const error = document.createElement("editable-region-error-card");
 			error.setAttribute("heading", "Failed to render array item");
 			error.setAttribute(
 				"message",
-				"Parent array editable not found. Array items must be a descendant of an array editable.",
+				"Array item editable regions must be nested inside an array editable region but this element has no parent editable region. Please check that this element is inside an array editable region.",
 			);
 			this.element.replaceChildren(error);
 			return false;
@@ -54,15 +49,38 @@ export default class EditableArrayItem extends EditableComponent {
 			return false;
 		}
 
+		if (e.dataTransfer?.types.includes(source.toLowerCase())) {
+			return true;
+		}
+
 		const dragType = this.getDragType();
 
-		if (
-			!e.dataTransfer?.types.includes(source.toLowerCase()) &&
-			(!dragType || !e.dataTransfer.types.includes(dragType))
-		) {
+		if (!dragType || !e.dataTransfer.types.includes(dragType)) {
 			return false;
 		}
 
+		if (dragType === "cc:structure") {
+			if (this.structureStrings.length === 0) {
+				return false;
+			}
+
+			const structureString = e.dataTransfer.types
+				.find((type) => type.startsWith("structure:"))
+				?.replace(/^structure:/, "");
+
+			if (!structureString) {
+				return false;
+			}
+
+			const targetStructure = this.structureStrings.find(
+				(targetValue: unknown) => structureString === targetValue,
+			);
+
+			if (!targetStructure) {
+				return false;
+			}
+		}
+
 		return true;
 	}
 
@@ -77,6 +95,47 @@ export default class EditableArrayItem extends EditableComponent {
 		this.element.style.boxShadow = this.getDraggingBoxShadow(e);
 	}
 
+	onDragStart(e: DragEvent): void {
+		const source = this.parent?.contextBase?.filePath;
+		if (!source || !e.dataTransfer || !this.element.dataset.prop) {
+			return;
+		}
+
+		const clientRect = this.element.getBoundingClientRect();
+
+		e.stopPropagation();
+		this.element.classList.add("dragging");
+
+		e.dataTransfer.setDragImage(this.element, clientRect.width - 35, 35);
+		e.dataTransfer.effectAllowed = "move";
+
+		const id = Math.random().toString(36).slice(2);
+		this.element.id = id;
+
+		const data = {
+			index: this.element.dataset.prop,
+			sourceId: id,
+			value: this.value,
+		};
+
+		if (this.inputConfig?.options?.structures?.values?.length > 0) {
+			const structure = CloudCannon.findStructure(
+				this.inputConfig?.options?.structures,
+				this.value,
+			);
+			if (structure) {
+				e.dataTransfer.setData(`structure:${JSON.stringify(structure)}`, "");
+			}
+		}
+
+		const payload = JSON.stringify(data);
+		e.dataTransfer?.setData(source, payload);
+		const dragType = this.getDragType();
+		if (dragType) {
+			e.dataTransfer?.setData(dragType, payload);
+		}
+	}
+
 	getDragType(): string | undefined {
 		if (this.inputConfig?.options?.structures?.values?.length) {
 			return "cc:structure";
@@ -300,43 +359,9 @@ export default class EditableArrayItem extends EditableComponent {
 				this.element.remove();
 			});
 
-			this.controlsElement.addEventListener("dragstart", (e: DragEvent) => {
-				const source = this.parent?.contextBase?.filePath;
-				if (!source || !e.dataTransfer || !this.element.dataset.prop) {
-					return;
-				}
-
-				const clientRect = this.element.getBoundingClientRect();
-
-				e.stopPropagation();
-				this.element.classList.add("dragging");
-
-				e.dataTransfer.setDragImage(this.element, clientRect.width - 35, 35);
-				e.dataTransfer.effectAllowed = "move";
-
-				const id = Math.random().toString(36).slice(2);
-				this.element.id = id;
-
-				const data: Record<string, any> = {
-					index: this.element.dataset.prop,
-					sourceId: id,
-					value: this.value,
-				};
-
-				if (this.inputConfig?.options?.structures?.values?.length > 0) {
-					data.structure = CloudCannon.findStructure(
-						this.inputConfig?.options?.structures,
-						this.value,
-					);
-				}
-
-				const payload = JSON.stringify(data);
-				e.dataTransfer?.setData(source, payload);
-				const dragType = this.getDragType();
-				if (dragType) {
-					e.dataTransfer?.setData(dragType, payload);
-				}
-			});
+			this.controlsElement.addEventListener("dragstart", (e: DragEvent) =>
+				this.onDragStart(e),
+			);
 
 			this.updateControls();
 
@@ -358,6 +383,12 @@ export default class EditableArrayItem extends EditableComponent {
 					(inputConfig as any)?.options?.disable_add ?? false;
 
 				this.inputConfig = inputConfig;
+				if (this.inputConfig?.options?.structures?.values?.length > 0) {
+					this.structureStrings =
+						this.inputConfig.options.structures.values.map((value: unknown) =>
+							JSON.stringify(value).toLowerCase(),
+						);
+				}
 				this.element.append(this.controlsElement);
 			});
 		}
@@ -428,25 +459,7 @@ export default class EditableArrayItem extends EditableComponent {
 					this.dispatchArrayMove(fromIndex, newIndex);
 				}
 			} else if (otherArrayData) {
-				const { index, sourceId, value, structure } =
-					JSON.parse(otherArrayData);
-				if (dragType === "cc:structure") {
-					if (!this.inputConfig?.options?.structures?.values) {
-						return;
-					}
-
-					const targetStructure = CloudCannon.findStructure(
-						this.inputConfig.options.structures,
-						this.value,
-					);
-					if (!targetStructure) {
-						return;
-					}
-
-					if (JSON.stringify(structure) !== JSON.stringify(targetStructure)) {
-						return;
-					}
-				}
+				const { index, sourceId, value } = JSON.parse(otherArrayData);
 
 				const sourceElement = document.getElementById(sourceId);
 				if (sourceElement && hasEditableArrayItem(sourceElement)) {
@@ -478,6 +491,10 @@ export default class EditableArrayItem extends EditableComponent {
 
 	setupListeners(): void {
 		super.setupListeners();
-		this.parent?.registerListener({ editable: this });
+		if (!this.element.dataset.prop) {
+			this.parent?.registerListener({
+				editable: this,
+			});
+		}
 	}
 }

package/nodes/editable-array.ts

@@ -4,10 +4,12 @@ import type {
 	CloudCannonJavaScriptV1APIFile,
 } from "@cloudcannon/javascript-api";
 import type EditableArrayItemComponent from "../components/editable-array-item-component.js";
-import { hasEditableArrayItem, isEditableElement } from "../helpers/checks.js";
+import type EditableRegionButton from "../components/ui/editable-region-button.js";
+import { isEditableElement } from "../helpers/checks.js";
 import { CloudCannon } from "../helpers/cloudcannon.js";
 import type EditableArrayItem from "./editable-array-item.js";
-import Editable from "./editable.js";
+import Editable, { type EditableListener } from "./editable.js";
+import "../components/ui/editable-region-button.js";
 
 const arrayDirectionValues = [
 	"row",
@@ -33,6 +35,61 @@ export default class EditableArray extends Editable {
 
 	private updatePromise: Promise<void> | undefined;
 	private needsReupdate = false;
+	private addButton?: EditableRegionButton;
+
+	async registerListener(listener: EditableListener): Promise<void> {
+		if (!this.value) {
+			return;
+		}
+
+		let value: unknown[] | CloudCannonJavaScriptV1APIFile[];
+		if (CloudCannon.isAPICollection(this.value)) {
+			value = await this.value.items();
+		} else if (CloudCannon.isAPIDataset(this.value)) {
+			const items = await this.value.items();
+			if (Array.isArray(items)) {
+				value = items;
+			} else {
+				const data = await items.data.get();
+				value = Array.isArray(data) ? data : [];
+			}
+		} else if (Array.isArray(this.value)) {
+			value = this.value;
+		} else {
+			value = [];
+		}
+
+		if (!listener.path) {
+			let index = 0;
+			for (const child of this.element.querySelectorAll(
+				"editable-array-item,[data-editable='array-item']",
+			)) {
+				let parent = child.parentElement;
+				while (parent instanceof HTMLElement && !isEditableElement(parent)) {
+					parent = parent.parentElement;
+				}
+
+				if (parent !== this.element) {
+					continue;
+				}
+
+				if (child === listener.editable.element) {
+					listener.path = `${index}`;
+					break;
+				}
+
+				index += 1;
+			}
+		}
+
+		if (listener.path) {
+			listener.editable.pushValue(value, listener, {
+				__base_context: this.contextBase ?? {},
+			});
+		}
+	}
+
+	deregisterListener(_target: Editable): void {}
 
 	validateConfiguration(): boolean {
 		const prop = this.element.dataset.prop;
@@ -40,7 +97,10 @@ export default class EditableArray extends Editable {
 			this.element.classList.add("errored");
 			const error = document.createElement("editable-region-error-card");
 			error.setAttribute("heading", "Failed to render array editable");
-			error.setAttribute("message", "Missing required attribute data-prop");
+			error.setAttribute(
+				"message",
+				"Array editable regions require a 'data-prop' HTML attribute but none was provided. Please check that this element has a valid 'data-prop' attribute.",
+			);
 			this.element.replaceChildren(error);
 			return false;
 		}
@@ -60,8 +120,19 @@ export default class EditableArray extends Editable {
 			error.setAttribute("heading", "Failed to render array editable");
 			error.setAttribute(
 				"message",
-				`Illegal value type: ${typeof value}. Supported types are array.`,
+				`Array editable regions expect to receive a value of type "array" but instead received a value of type '${typeof value}'.`,
 			);
+			if (this.contextBase?.fullPath) {
+				error.setAttribute(
+					"hint",
+					`This may mean that the 'data-prop' attribute is incorrectly set for this element, the full 'data-prop' path was '${this.contextBase?.fullPath}'.`,
+				);
+			} else {
+				error.setAttribute(
+					"hint",
+					`This may mean that the 'data-prop' attribute is incorrectly set for this element.`,
+				);
+			}
 			this.element.replaceChildren(error);
 			return;
 		}
@@ -101,40 +172,69 @@ export default class EditableArray extends Editable {
 			value = [];
 		}
 
-		const children: (HTMLElement & { editable: EditableArrayItem })[] = [];
+		const children: (HTMLElement & { editable?: EditableArrayItem })[] = [];
 
 		for (const child of this.element.querySelectorAll(
-			"editable-array-item,[data-editable='array-item']",
+			"editable-array-item,[data-editable='array-item'],array-placeholder",
 		)) {
-			if (!hasEditableArrayItem(child)) {
-				continue;
-			}
-
 			let parent = child.parentElement;
 			while (parent instanceof HTMLElement && !isEditableElement(parent)) {
 				parent = parent.parentElement;
 			}
 
-			if (!parent || ("editable" in parent && parent.editable !== this)) {
+			if (parent !== this.element) {
 				continue;
 			}
 
 			children.push(child as any);
 		}
 
+		if (
+			children.length === 0 &&
+			!this.element.dataset.component &&
+			!this.element.dataset.componentKey
+		) {
+			const error = document.createElement("editable-region-error-card");
+			error.setAttribute("heading", "Failed to render array editable region");
+			error.setAttribute(
+				"message",
+				"Array editable regions with no child array items must have either a 'data-component' attribute or a 'data-component-key' attribute. Please add an item to this array then save and rebuild to see your changes or add a 'data-component' or 'data-component-key' attribute to this element.",
+			);
+			this.element.replaceChildren(error);
+			return;
+		}
+
 		if (!this.element.dataset.idKey) {
 			while (children.length > value.length) {
 				children.pop()?.remove();
 			}
 
+			if (value.length === 0 && this.addButton) {
+				this.element.appendChild(this.addButton);
+				return;
+			}
+
+			this.addButton?.remove();
+
 			for (let i = 0; i < value.length; i++) {
 				let child = children[i];
 				if (!child) {
-					child = children[0].cloneNode(true) as HTMLElement & {
-						editable: EditableArrayItem;
-					};
+					if (this.element.dataset.component) {
+						child = document.createElement(
+							"editable-array-item",
+						) as EditableArrayItemComponent;
+					} else {
+						// Empty arrays should be caught by the error case above so children[0] should always exist
+						child = children[0].cloneNode(true) as HTMLElement & {
+							editable?: EditableArrayItem;
+						};
+					}
 					this.element.appendChild(child);
 				}
+
+				if (this.element.dataset.component) {
+					child.dataset.component = this.element.dataset.component;
+				}
 				child.dataset.prop = `${i}`;
 				child.dataset.length = `${children.length}`;
 				child.editable?.pushValue(
@@ -163,9 +263,12 @@ export default class EditableArray extends Editable {
 			}
 
 			if (data && typeof data === "object" && componentKey) {
-				componentKeys.push(String((data as any)[componentKey]));
-			} else {
-				componentKeys.push(null);
+				const component = (data as any)[componentKey];
+				if (typeof component !== "undefined" && component !== null) {
+					componentKeys.push(String((data as any)[componentKey]));
+				} else {
+					componentKeys.push(null);
+				}
 			}
 		}
 
@@ -178,12 +281,18 @@ export default class EditableArray extends Editable {
 			children.forEach((child, index) => {
 				child.dataset.prop = `${index}`;
 				child.dataset.length = `${children.length}`;
-				child.editable.pushValue(
+				child.editable?.pushValue(
 					value,
 					{ path: `${index}`, editable: child.editable },
 					{ __base_context: this.contextBase ?? {} },
 				);
 			});
+
+			if (dataKeys.length === 0 && this.addButton) {
+				this.element.appendChild(this.addButton);
+			} else {
+				this.addButton?.remove();
+			}
 			return;
 		}
 
@@ -201,6 +310,8 @@ export default class EditableArray extends Editable {
 			}
 			const placeholder = placeholders[i];
 			const existingElement = children[i];
+			const componentKey = componentKeys[i] || this.element.dataset.component;
+
 			const matchingChildIndex = children.findIndex(
 				(child, i) => child.dataset.id === key && !moved[i],
 			);
@@ -210,15 +321,38 @@ export default class EditableArray extends Editable {
 				const clone = children.find((child) => child.dataset.id === key);
 				if (clone) {
 					matchingChild = clone.cloneNode(true) as any;
-				} else {
+				} else if (componentKey) {
 					matchingChild = document.createElement(
 						"editable-array-item",
 					) as EditableArrayItemComponent;
 					matchingChild.dataset.id = key;
-
-					if (componentKeys[i]) {
-						matchingChild.dataset.component = componentKeys[i];
+					matchingChild.dataset.component = componentKey;
+				} else {
+					const error = document.createElement("editable-region-error-card");
+					error.setAttribute("heading", "Failed to render array item");
+					if (typeof this.element.dataset.componentKey === "string") {
+						error.setAttribute(
+							"message",
+							"Array editable region has no child with a matching 'data-id' value for this element and the value has no key matching the 'data-component-key' attribute. Please check that the 'data-component-key' attribute for this element is correct and that each element has an entry for that key, or provide a fallback 'data-component' attribute.",
+						);
+						error.setAttribute(
+							"hint",
+							`This may mean that the value for 'data-component-key' is incorrect or that your array data is incorrectly formatted.
+							The current value for 'data-component-key' is '${this.element.dataset.componentKey}' and the current value for 'data-id' is '${key}'.
+							`,
+						);
+					} else {
+						error.setAttribute(
+							"message",
+							"Array editable region has no child with a matching 'data-id' value for this element and no 'data-component' or 'data-component-key' attribute. Please save and rebuild to see your changes or add a 'data-component' or 'data-component-key' attribute to this element.",
+						);
+						error.setAttribute(
+							"hint",
+							`The full value of "data-id" for this item is "${key}"`,
+						);
 					}
+					matchingChild = document.createElement("array-placeholder");
+					matchingChild.append(error);
 				}
 			} else {
 				moved[matchingChildIndex] = true;
@@ -235,12 +369,14 @@ export default class EditableArray extends Editable {
 				this.element.appendChild(matchingChild);
 			}
 
-			matchingChild.editable.parent = this;
-			matchingChild.editable.pushValue(
-				value,
-				{ path: `${i}`, editable: matchingChild.editable },
-				{ __base_context: this.contextBase ?? {} },
-			);
+			if (matchingChild.editable) {
+				matchingChild.editable.parent = this;
+				matchingChild.editable.pushValue(
+					value,
+					{ path: `${i}`, editable: matchingChild.editable },
+					{ __base_context: this.contextBase ?? {} },
+				);
+			}
 		});
 
 		children.forEach((child, i) => {
@@ -248,6 +384,12 @@ export default class EditableArray extends Editable {
 				child.remove();
 			}
 		});
+
+		if (dataKeys.length === 0 && this.addButton) {
+			this.element.appendChild(this.addButton);
+		} else {
+			this.addButton?.remove();
+		}
 	}
 
 	calculateArrayDirection(): ArrayDirection {
@@ -268,5 +410,21 @@ export default class EditableArray extends Editable {
 
 	mount(): void {
 		this.arrayDirection = this.calculateArrayDirection();
+
+		this.addButton = document.createElement("editable-region-button");
+		this.addButton.setAttribute("icon", "add");
+		this.addButton.setAttribute("text", "Add Item");
+		this.addButton.addEventListener("button-click", () => {
+			this.element.dispatchEvent(
+				new CustomEvent("cloudcannon-api", {
+					bubbles: true,
+					detail: {
+						source: this.element.dataset.prop,
+						action: "add-array-item",
+						newIndex: 0,
+					},
+				}),
+			);
+		});
 	}
 }

package/nodes/editable-component.ts

@@ -1,6 +1,5 @@
 import {
 	areEqualEditables,
-	areEqualNodes,
 	hasEditable,
 	hasEditableText,
 	isEditableElement,
@@ -43,7 +42,7 @@ export default class EditableComponent extends Editable {
 			error.setAttribute("heading", "Failed to render component");
 			error.setAttribute(
 				"message",
-				"Component key(data-component) not provided",
+				"Component editable regions require a 'data-component' HTML attribute but none was provided. Please check that this element has a valid 'data-component' attribute.",
 			);
 			this.element.replaceChildren(error);
 			return false;
@@ -192,12 +191,13 @@ export default class EditableComponent extends Editable {
 				}
 			} else if (renderChild && targetChild) {
 				if (
-					!areEqualNodes(targetChild, renderChild) ||
+					renderChild.nodeName !== targetChild.nodeName ||
 					isEditableElement(renderChild) ||
 					isEditableElement(targetChild)
 				) {
 					targetChild.replaceWith(renderChild);
 				} else {
+					this.updateNode(targetChild, renderChild);
 					this.updateTree(targetChild, renderChild);
 				}
 			} else if (renderChild) {
@@ -211,6 +211,19 @@ export default class EditableComponent extends Editable {
 		}
 	}
 
+	updateNode(targetChild: ChildNode, renderChild: ChildNode) {
+		if (targetChild instanceof Element && renderChild instanceof Element) {
+			for (const attribute of renderChild.attributes) {
+				targetChild.setAttribute(attribute.name, attribute.value);
+			}
+			for (const attribute of targetChild.attributes) {
+				if (!renderChild.hasAttribute(attribute.name)) {
+					targetChild.removeAttribute(attribute.name);
+				}
+			}
+		}
+	}
+
 	updateEditable(
 		renderChild: HTMLElement,
 		targetChild: HTMLElement & { editable: Editable },

package/nodes/editable-image.ts

@@ -11,11 +11,14 @@ export default class EditableImage extends Editable {
 	configuredAlt = false;
 	configuredTitle = false;
 
-	displayError(heading: string, message: string) {
+	displayError(heading: string, message: string, hint?: string) {
 		this.element.classList.add("errored");
 		const error = document.createElement("editable-region-error-card");
 		error.setAttribute("heading", heading);
 		error.setAttribute("message", message);
+		if (hint) {
+			error.setAttribute("hint", hint);
+		}
 		if (this.imageEl) {
 			this.imageEl?.replaceWith(error);
 		} else {
@@ -32,7 +35,7 @@ export default class EditableImage extends Editable {
 		if (!(child instanceof HTMLImageElement)) {
 			this.displayError(
 				"Failed to render image editable region",
-				"Image editable region requires an image element as its child.",
+				"Image editable regions must contain a child HTML element of type 'img'. Please check that this element has a child 'img' element.",
 			);
 			return false;
 		}
@@ -47,7 +50,7 @@ export default class EditableImage extends Editable {
 		) {
 			this.displayError(
 				"Failed to render image editable region",
-				"Atleast one of data-prop, data-prop-src, data-prop-alt, or data-prop-title is required.",
+				"Image editable regions require atleast one valid 'data-prop-*' HTML attribute. The valid attributes are 'data-prop', 'data-prop-src', 'data-prop-alt', and 'data-prop-title'. Please check that this element has atleast one of these attributes.",
 			);
 			return false;
 		}
@@ -58,7 +61,10 @@ export default class EditableImage extends Editable {
 		if (typeof value !== "object") {
 			this.displayError(
 				"Failed to render image editable region",
-				`Illegal value type: ${typeof value}. Supported types are object.`,
+				`Image editable regions expect to receive a value of type "object" but instead received a value of type '${typeof value}'.`,
+				this.contextBase?.fullPath
+					? `This may mean that the 'data-prop' attribute is incorrectly set for this element, the full 'data-prop' path was '${this.contextBase?.fullPath}'.`
+					: `This may mean that the 'data-prop' attribute is incorrectly set for this element.`,
 			);
 			return;
 		}
@@ -67,32 +73,30 @@ export default class EditableImage extends Editable {
 			return value;
 		}
 
-		if ("src" in value && typeof value.src !== "string" && value.src !== null) {
-			this.displayError(
-				"Failed to render image editable region",
-				`Illegal value type for "src": ${typeof value.src}. Supported types are string.`,
-			);
-			return;
-		}
-
-		if ("alt" in value && typeof value.alt !== "string" && value.alt !== null) {
-			this.displayError(
-				"Failed to render image editable region",
-				`Illegal value type for "alt": ${typeof value.alt}. Supported types are string.`,
-			);
-			return;
-		}
+		for (const key of ["src", "alt", "title"]) {
+			if (
+				key in value &&
+				typeof value[key as keyof typeof value] !== "string" &&
+				value[key as keyof typeof value] !== null
+			) {
+				let hint: string;
+				if (this.contexts[key]?.fullPath) {
+					hint = `This may mean that the 'data-prop-${key}' attribute is incorrectly set for this element, the full 'data-prop-${key}' path was '${this.contexts[key]?.fullPath}'.`;
+				} else if (typeof this.element.dataset[key] === "string") {
+					hint = `This may mean that the 'data-prop-${key}' attribute is incorrectly set for this element.`;
+				} else if (this.contextBase?.fullPath) {
+					hint = `This may mean that the 'data-prop' attribute is incorrectly set for this element, the full 'data-prop' path was '${this.contextBase?.fullPath}'.`;
+				} else {
+					hint = `This may mean that the 'data-prop' attribute is incorrectly set for this element.`;
+				}
 
-		if (
-			"title" in value &&
-			typeof value.title !== "string" &&
-			value.title !== null
-		) {
-			this.displayError(
-				"Failed to render image editable region",
-				`Illegal value type for "title": ${typeof value.title}. Supported types are string.`,
-			);
-			return;
+				this.displayError(
+					"Failed to render image editable region",
+					`Image editable regions expect the "${key}" key to have a value of type "string" but instead it was a value of type '${typeof value[key as keyof typeof value]}'.`,
+					hint,
+				);
+				return;
+			}
 		}
 
 		const unexpectedKey = Object.keys(value).find(
@@ -100,9 +104,21 @@ export default class EditableImage extends Editable {
 		);
 
 		if (unexpectedKey) {
+			let hint: string | undefined;
+			const capitalizedUnexpectedKey =
+				unexpectedKey.charAt(0).toUpperCase() + unexpectedKey.slice(1);
+
+			if (this.element.dataset[`prop${capitalizedUnexpectedKey}`]) {
+				hint = `Try removing the 'data-prop-${unexpectedKey}' HTML attribute from this element.`;
+			} else if (this.contextBase?.fullPath) {
+				hint = `This may mean that the 'data-prop' attribute is incorrectly set for this element, the full 'data-prop' path was '${this.contextBase?.fullPath}'.`;
+			} else {
+				hint = `This may mean that the 'data-prop' attribute is incorrectly set for this element.`;
+			}
 			this.displayError(
 				"Failed to render image editable region",
-				`Unexpected key "${unexpectedKey}" in image editable region. Supported keys are "src", "alt", and "title".`,
+				`Image editable region received an unexpected value key "${unexpectedKey}". The supported values are "src", "alt", and "title". Please check that your data is correctly formatted.`,
+				hint,
 			);
 			return;
 		}

package/nodes/editable-snippet.ts

@@ -51,6 +51,7 @@ export default class EditableSnippet extends EditableComponent {
 		const { snippets, source } = this.parseSource(options.source);
 
 		if (options.action === "get-input-config") {
+			// TODO: This should actually load the input config, including the snippet in the cascade
 			return false;
 		}
 

package/nodes/editable-source.ts

@@ -5,7 +5,7 @@ import EditableText from "./editable-text.js";
 
 const INDENTATION_REGEX = /^([ \t]+)[^\s]/gm;
 const TAG_REGEX =
-	/<\s*(?<closing>\/?)\s*(?<tagname>[-a-z]+)(\s+[^>]+)*?\s*(?<selfclosing>\/?)\s*>/gi;
+	/<\s*(?<closing>\/?)\s*(?<tagname>[-a-z0-9]+)(\s+[^>]+)*?\s*(?<selfclosing>\/?)\s*>/gi;
 
 const HTML_VOID_ELEMENT: Record<string, boolean> = {
 	area: true,
@@ -38,6 +38,11 @@ export default class EditableSource extends EditableText {
 		if (!this.element.dataset.path) {
 			return;
 		}
+
+		if (!this.element.dataset.path.startsWith("/")) {
+			this.element.dataset.path = `/${this.element.dataset.path}`;
+		}
+
 		this.file = CloudCannon.file(this.element.dataset.path);
 		this.file.addEventListener("change", () => {
 			this.file?.get().then(this.pushValue.bind(this));
@@ -51,7 +56,10 @@ export default class EditableSource extends EditableText {
 			this.element.classList.add("errored");
 			const error = document.createElement("editable-region-error-card");
 			error.setAttribute("heading", "Failed to render source editable region");
-			error.setAttribute("message", "Missing required attribute data-path");
+			error.setAttribute(
+				"message",
+				"Source editable regions require a 'data-path' HTML attribute but none was provided. Please check that this element has a valid 'data-path' attribute.",
+			);
 			this.element.replaceChildren(error);
 			return false;
 		}
@@ -61,7 +69,10 @@ export default class EditableSource extends EditableText {
 			this.element.classList.add("errored");
 			const error = document.createElement("editable-region-error-card");
 			error.setAttribute("heading", "Failed to render source editable region");
-			error.setAttribute("message", "Missing required attribute data-key");
+			error.setAttribute(
+				"message",
+				"Source editable regions require a 'data-key' HTML attribute but none was provided. Please check that this element has a valid 'data-key' attribute.",
+			);
 			this.element.replaceChildren(error);
 			return false;
 		}
@@ -75,7 +86,11 @@ export default class EditableSource extends EditableText {
 			error.setAttribute("heading", "Failed to render source editable region");
 			error.setAttribute(
 				"message",
-				`Illegal value type: ${typeof value}. Supported types are string.`,
+				"The provided 'data-path' HTML attribute references a file that does not exist. Please check that the file exists and that the 'data-path' attribute on this element is correct.",
+			);
+			error.setAttribute(
+				"hint",
+				`The current value of the "data-path" attribute is "${this.element.dataset.path}"`,
 			);
 			this.element.replaceChildren(error);
 			return;
@@ -92,7 +107,11 @@ export default class EditableSource extends EditableText {
 				);
 				error.setAttribute(
 					"message",
-					"Failed to find element with matching data-key attribute",
+					"Failed to find an element matching the provided 'data-key' attribute.",
+				);
+				error.setAttribute(
+					"hint",
+					`This might mean that your 'data-path' attribute is incorrect. The current value of the "data-path" attribute is "${this.element.dataset.path}" and the current value of the "data-key" attribute is "${this.element.dataset.key}".`,
 				);
 				this.element.replaceChildren(error);
 				return;
@@ -111,7 +130,11 @@ export default class EditableSource extends EditableText {
 				);
 				error.setAttribute(
 					"message",
-					"Found duplicate data-key attribute. Make sure all source editables have unique data-key attributes",
+					`Source editable regions require that all 'data-key' attributes in the same file have unique values but the current file contains multiple instances of the key '${this.element.dataset.key}'. Please make sure all 'data-key' attributes are unique within the same file.`,
+				);
+				error.setAttribute(
+					"hint",
+					`The current value of the 'data-path' attribute is '${this.element.dataset.path}'"'.`,
 				);
 				this.element.replaceChildren(error);
 				return;

package/nodes/editable-text.ts

@@ -15,7 +15,10 @@ export default class EditableText extends Editable {
 			this.element.classList.add("errored");
 			const error = document.createElement("editable-region-error-card");
 			error.setAttribute("heading", "Failed to render text editable region");
-			error.setAttribute("message", "Missing required attribute data-prop");
+			error.setAttribute(
+				"message",
+				"Text editable regions require a 'data-prop' HTML attribute but none was provided. Please check that this element has a valid 'data-prop' attribute.",
+			);
 			this.element.replaceChildren(error);
 			return false;
 		}
@@ -30,7 +33,7 @@ export default class EditableText extends Editable {
 			error.setAttribute("heading", "Failed to render text editable region");
 			error.setAttribute(
 				"message",
-				`Unsupported element type: "${elementType}". Supported element types are span, text, and block.`,
+				`Text editable region received an invalid type for the 'data-type' HTML attribute. The provided element type was '${elementType}' but the supported element types are 'span', 'text', and 'block'. Please set the 'data-type' attribute to one of the supported types.`,
 			);
 			this.element.replaceChildren(error);
 			return false;
@@ -45,8 +48,19 @@ export default class EditableText extends Editable {
 			error.setAttribute("heading", "Failed to render text editable region");
 			error.setAttribute(
 				"message",
-				`Illegal value type: ${typeof value}. Supported types are string.`,
+				`Text editable regions expect to receive a value of type "string" but instead received a value of type '${typeof value}'.`,
 			);
+			if (this.contextBase?.fullPath) {
+				error.setAttribute(
+					"hint",
+					`This may mean that the 'data-prop' attribute is incorrectly set for this element, the full 'data-prop' path was '${this.contextBase?.fullPath}'.`,
+				);
+			} else {
+				error.setAttribute(
+					"hint",
+					`This may mean that the 'data-prop' attribute is incorrectly set for this element.`,
+				);
+			}
 			this.element.replaceChildren(error);
 			return;
 		}

package/nodes/editable.ts

@@ -27,8 +27,8 @@ export interface DOMListener {
 	event: string;
 }
 
-export interface APIListener extends DOMListener {
-	event: "change" | "delete";
+export interface APIListener {
+	fn: (e: any) => void;
 	obj:
 		| CloudCannonJavaScriptV1APIFile
 		| CloudCannonJavaScriptV1APICollection
@@ -118,10 +118,7 @@ export default class Editable {
 				value = await value.items();
 			} else if (CloudCannon.isAPIFile(value)) {
 				context.file = value;
-				if (key === "@content") {
-					context.isContent = true;
-					value = await value.content.get();
-				} else {
+				if (key !== "@content") {
 					value = await value.data.get();
 				}
 			} else if (CloudCannon.isAPIDataset(value)) {
@@ -135,8 +132,13 @@ export default class Editable {
 				}
 			}
 
-			if (value && typeof value === "object" && key in value) {
+			if (key === "@content" && CloudCannon.isAPIFile(value)) {
+				context.isContent = true;
+				value = await value.content.get();
+			} else if (value && typeof value === "object" && key in value) {
 				value = (value as any)[key];
+			} else {
+				value = undefined;
 			}
 
 			context.fullPath = context.fullPath ? `${context.fullPath}.${key}` : key;
@@ -227,6 +229,13 @@ export default class Editable {
 	}
 
 	registerListener(listener: EditableListener): void {
+		if (this.value !== undefined) {
+			listener.editable.pushValue(this.value, listener, {
+				...this.contexts,
+				__base_context: this.contextBase ?? {},
+			});
+		}
+
 		if (
 			this.listeners.find(
 				({ editable: other, key }) =>
@@ -236,13 +245,6 @@ export default class Editable {
 			return;
 		}
 
-		if (this.value !== undefined) {
-			listener.editable.pushValue(this.value, listener, {
-				...this.contexts,
-				__base_context: this.contextBase ?? {},
-			});
-		}
-
 		this.listeners.push(listener);
 	}
 
@@ -253,6 +255,9 @@ export default class Editable {
 	}
 
 	async disconnect(): Promise<void> {
+		if (this.disconnecting) {
+			return;
+		}
 		this.disconnecting = true;
 
 		if (this.connectPromise) {
@@ -261,9 +266,10 @@ export default class Editable {
 
 		this.parent?.deregisterListener(this);
 		this.parent = null;
-		this.APIListeners.forEach(({ obj, fn, event }) =>
-			obj.removeEventListener(event, fn),
-		);
+		this.APIListeners.forEach(({ obj, fn }) => {
+			obj.removeEventListener("change", fn);
+			obj.removeEventListener("delete", fn);
+		});
 		this.APIListeners = [];
 		this.domListeners.forEach(({ event, fn }) => {
 			this.element.removeEventListener(event, fn);
@@ -280,6 +286,10 @@ export default class Editable {
 	}
 
 	connect(): void {
+		if (!this.validateConfiguration()) {
+			return;
+		}
+
 		if (this.disconnecting) {
 			this.needsReconnect = true;
 			return;
@@ -289,13 +299,11 @@ export default class Editable {
 		}
 		this.connectPromise = loadingPromise.then(() => {
 			this.setupListeners();
-			if (this.validateConfiguration()) {
-				this.connected = true;
-				if (!this.mounted && this.shouldMount()) {
-					this.mounted = true;
-					this.mount();
-					this.update();
-				}
+			this.connected = true;
+			if (!this.mounted && this.shouldMount()) {
+				this.mounted = true;
+				this.mount();
+				this.update();
 			}
 		});
 	}
@@ -347,9 +355,9 @@ export default class Editable {
 				this.APIListeners.push({
 					obj,
 					fn: handleAPIChange,
-					event: "change",
 				});
 				obj.addEventListener("change", handleAPIChange);
+				obj.addEventListener("delete", handleAPIChange);
 				handleAPIChange();
 			}
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cloudcannon/editable-regions",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"type": "module",
 	"description": "Visual Editing for the CloudCannon CMS.",
 	"keywords": [
@@ -59,6 +59,7 @@
 		"@types/react": "18.3.12",
 		"@types/react-dom": "18.3.1",
 		"astro": "^5.14.1",
+		"js-beautify": "^1.15.4",
 		"typescript": "5.9.3"
 	}
 }

package/styles/editable-text.css

@@ -1,3 +1,8 @@
 editable-text {
 	display: inline-block;
 }
+
+editable-text,
+[data-editable="text"] {
+	min-width: 10px;
+}

package/styles/ui/editable-region-button.css

@@ -0,0 +1,36 @@
+button {
+	all: initial;
+	-webkit-appearance: none;
+	-moz-appearance: none;
+	appearance: none;
+	text-decoration: none;
+	text-align: center;
+	box-sizing: border-box;
+
+	font-size: 16px;
+	font-weight: bold;
+	font-family: var(--ccrt-font-family);
+	line-height: 1.4;
+	color: var(--ccrt-color-cc-blue);
+	--cc-icon-fill: var(--ccrt-color-cc-blue);
+
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+
+	border: var(--ccrt-border-width) solid var(--ccrt-color-alto);
+	border-radius: var(--ccrt-border-radius);
+
+	padding: 0 var(--ccrt-gap);
+	height: 48px;
+}
+
+button:hover {
+	background-color: rgba(226, 234, 250);
+	border-color: color-mix(
+		in srgb,
+		var(--ccrt-color-cc-blue) 80%,
+		var(--ccrt-color-carbon)
+	);
+	cursor: pointer;
+}