@cloudcannon/editable-regions 0.0.2

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright 2025 CloudCannon
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# Editable Regions
+
+Visual Editing for the [CloudCannon](https://cloudcannon.com/) CMS.
+
+[<img src="https://img.shields.io/npm/v/@cloudcannon%2Feditable-regions?logo=npm" alt="version badge">](https://www.npmjs.com/package/@cloudcannon%2Feditable-regions)

package/components/editable-array-component.ts

@@ -0,0 +1,26 @@
+import EditableArray from "../nodes/editable-array.js";
+
+export default class EditableArrayComponent extends HTMLElement {
+	editable: EditableArray;
+
+	constructor() {
+		super();
+		this.editable = new EditableArray(this);
+	}
+
+	connectedCallback(): void {
+		this.editable.connect();
+	}
+
+	disconnectedCallback(): void {
+		this.editable.disconnect();
+	}
+}
+
+customElements.define("editable-array", EditableArrayComponent);
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"editable-array": EditableArrayComponent;
+	}
+}

package/components/editable-array-item-component.ts

@@ -0,0 +1,26 @@
+import EditableArrayItem from "../nodes/editable-array-item.js";
+
+export default class EditableArrayItemComponent extends HTMLElement {
+	editable: EditableArrayItem;
+
+	constructor() {
+		super();
+		this.editable = new EditableArrayItem(this);
+	}
+
+	connectedCallback(): void {
+		this.editable.connect();
+	}
+
+	disconnectedCallback(): void {
+		this.editable.disconnect();
+	}
+}
+
+customElements.define("editable-array-item", EditableArrayItemComponent);
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"editable-array-item": EditableArrayItemComponent;
+	}
+}

package/components/editable-component-component.ts

@@ -0,0 +1,26 @@
+import EditableComponent from "../nodes/editable-component.js";
+
+export default class EditableComponentComponent extends HTMLElement {
+	editable: EditableComponent;
+
+	constructor() {
+		super();
+		this.editable = new EditableComponent(this);
+	}
+
+	connectedCallback(): void {
+		this.editable.connect();
+	}
+
+	disconnectedCallback(): void {
+		this.editable.disconnect();
+	}
+}
+
+customElements.define("editable-component", EditableComponentComponent);
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"editable-component": EditableComponentComponent;
+	}
+}

package/components/editable-image-component.ts

@@ -0,0 +1,26 @@
+import EditableImage from "../nodes/editable-image.js";
+
+export default class EditableImageComponent extends HTMLElement {
+	editable: EditableImage;
+
+	constructor() {
+		super();
+		this.editable = new EditableImage(this);
+	}
+
+	connectedCallback(): void {
+		this.editable.connect();
+	}
+
+	disconnectedCallback(): void {
+		this.editable.disconnect();
+	}
+}
+
+customElements.define("editable-image", EditableImageComponent);
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"editable-image": EditableImageComponent;
+	}
+}

package/components/editable-snippet-component.ts

@@ -0,0 +1,30 @@
+import EditableSnippet from "../nodes/editable-snippet.js";
+
+export default class EditableSnippetComponent extends HTMLElement {
+	editable: EditableSnippet;
+
+	constructor() {
+		super();
+		this.editable = new EditableSnippet(this);
+	}
+
+	set snippetData(value: unknown) {
+		this.editable.pushValue(value);
+	}
+
+	connectedCallback(): void {
+		this.editable.connect();
+	}
+
+	disconnectedCallback(): void {
+		this.editable.disconnect();
+	}
+}
+
+customElements.define("editable-snippet", EditableSnippetComponent);
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"editable-snippet": EditableSnippetComponent;
+	}
+}

package/components/editable-source-component.ts

@@ -0,0 +1,26 @@
+import EditableSource from "../nodes/editable-source.js";
+
+export default class EditableComponentSource extends HTMLElement {
+	editable: EditableSource;
+
+	constructor() {
+		super();
+		this.editable = new EditableSource(this);
+	}
+
+	connectedCallback(): void {
+		this.editable.connect();
+	}
+
+	disconnectedCallback(): void {
+		this.editable.disconnect();
+	}
+}
+
+customElements.define("editable-source", EditableComponentSource);
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"editable-source": EditableComponentSource;
+	}
+}

package/components/editable-text-component.ts

@@ -0,0 +1,26 @@
+import EditableText from "../nodes/editable-text.js";
+
+export default class EditableTextComponent extends HTMLElement {
+	editable: EditableText;
+
+	constructor() {
+		super();
+		this.editable = new EditableText(this);
+	}
+
+	connectedCallback(): void {
+		this.editable.connect();
+	}
+
+	disconnectedCallback(): void {
+		this.editable.disconnect();
+	}
+}
+
+customElements.define("editable-text", EditableTextComponent);
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"editable-text": EditableTextComponent;
+	}
+}

package/components/index.ts

@@ -0,0 +1,35 @@
+export { default as EditableArrayComponent } from "./editable-array-component.js";
+export { default as EditableArrayItemComponent } from "./editable-array-item-component.js";
+export { default as EditableTextComponent } from "./editable-text-component.js";
+export { default as EditableComponentComponent } from "./editable-component-component.js";
+export { default as EditableImageComponent } from "./editable-image-component.js";
+export { default as EditableSourceComponent } from "./editable-source-component.js";
+export { default as EditableSnippetComponent } from "./editable-snippet-component.js";
+
+import { loadedPromise } from "../helpers/cloudcannon.js";
+import {
+	dehydrateDataEditableRegions,
+	hydrateDataEditableRegions,
+} from "../helpers/hydrate-editable-regions";
+
+const observer = new MutationObserver((mutations) => {
+	mutations.forEach((mutation) => {
+		mutation.removedNodes.forEach((el) => {
+			if (el instanceof HTMLElement) {
+				dehydrateDataEditableRegions(el);
+			}
+		});
+
+		mutation.addedNodes.forEach((el) => {
+			if (el instanceof HTMLElement) {
+				hydrateDataEditableRegions(el);
+			}
+		});
+	});
+});
+
+observer.observe(document, { childList: true, subtree: true });
+
+loadedPromise.then(() => {
+	hydrateDataEditableRegions(document.body);
+});

package/components/ui/editable-array-item-controls.ts

@@ -0,0 +1,123 @@
+import type { ArrayDirection } from "../../nodes/editable-array";
+import EditableComponentControls from "./editable-component-controls";
+
+export default class EditableArrayItemControls extends EditableComponentControls {
+	arrayDirection: ArrayDirection = "column";
+
+	moveBackwardText: "up" | "left" = "up";
+	moveForwardText: "down" | "right" = "down";
+
+	private _disableMoveForward = false;
+	private _disableMoveBackward = false;
+	private _disableRemove = false;
+	private _disableReorder = false;
+
+	private moveForwardButton?: HTMLButtonElement;
+	private moveBackwardButton?: HTMLButtonElement;
+	private deleteButton?: HTMLButtonElement;
+	private dragHandle?: HTMLButtonElement;
+
+	set disableMoveForward(value: boolean) {
+		this._disableMoveForward = value;
+		this.update();
+	}
+
+	set disableMoveBackward(value: boolean) {
+		this._disableMoveBackward = value;
+		this.update();
+	}
+
+	set disableRemove(value: boolean) {
+		this._disableRemove = value;
+		this.update();
+	}
+
+	set disableReorder(value: boolean) {
+		this._disableReorder = value;
+		this.update();
+	}
+
+	update() {
+		if (this.dragHandle) {
+			this.dragHandle.draggable = !this._disableReorder;
+			this.dragHandle.innerHTML = `<cc-icon name="${this.dragHandle.draggable ? "drag_indicator" : "more_vert"}"></cc-icon>`;
+		}
+
+		if (this.moveForwardButton) {
+			this.moveForwardButton.disabled =
+				this._disableMoveForward || this._disableReorder;
+		}
+
+		if (this.moveBackwardButton) {
+			this.moveBackwardButton.disabled =
+				this._disableMoveBackward || this._disableReorder;
+		}
+
+		if (this.deleteButton) {
+			this.deleteButton.disabled = this._disableRemove;
+		}
+	}
+
+	render(shadow: ShadowRoot): void {
+		super.render(shadow);
+
+		this.dragHandle = document.createElement("button");
+		this.dragHandle.onclick = (e) => {
+			e.stopPropagation();
+			if (this.contextMenu?.classList.contains("open")) {
+				this.contextMenu?.classList.remove("open");
+				this.removeAttribute("open");
+			} else if (this.contextMenu && this.contextMenu.childElementCount > 0) {
+				this.contextMenu?.classList.add("open");
+				this.setAttribute("open", "true");
+			}
+		};
+		this.dragHandle.ondragstart = () => {
+			this.contextMenu?.classList.remove("open");
+			this.removeAttribute("open");
+		};
+		this.buttonRow?.append(this.dragHandle);
+
+		const backwardIconName = this.moveBackwardText === "up" ? "north" : "west";
+		this.moveBackwardButton = document.createElement("button");
+		this.moveBackwardButton.innerHTML = `<cc-icon name="${backwardIconName}"></cc-icon> Move ${this.moveBackwardText}`;
+		this.moveBackwardButton.onclick = () => {
+			this.dispatchEvent(new CustomEvent("move-backward", { detail: this }));
+		};
+		const moveBackwardContainer = document.createElement("li");
+		moveBackwardContainer.append(this.moveBackwardButton);
+		this.contextMenu?.append(moveBackwardContainer);
+
+		const forwardIconName = this.moveForwardText === "down" ? "south" : "east";
+		this.moveForwardButton = document.createElement("button");
+		this.moveForwardButton.innerHTML = `<cc-icon name="${forwardIconName}"></cc-icon> Move ${this.moveForwardText}`;
+		this.moveForwardButton.onclick = (): void => {
+			this.dispatchEvent(new CustomEvent("move-forward", { detail: this }));
+		};
+		const moveForwardContainer = document.createElement("li");
+		moveForwardContainer.append(this.moveForwardButton);
+		this.contextMenu?.append(moveForwardContainer);
+
+		this.deleteButton = document.createElement("button");
+		this.deleteButton.innerHTML = '<cc-icon name="delete"></cc-icon> Delete';
+		this.deleteButton.onclick = () => {
+			this.dispatchEvent(new CustomEvent("delete", { detail: this }));
+		};
+		const deleteContainer = document.createElement("li");
+		deleteContainer.append(this.deleteButton);
+		this.contextMenu?.append(deleteContainer);
+
+		this.update();
+	}
+}
+
+customElements.define(
+	"editable-array-item-controls",
+	EditableArrayItemControls,
+);
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"editable-array-item-controls": EditableArrayItemControls;
+	}
+}

package/components/ui/editable-component-controls.ts

@@ -0,0 +1,57 @@
+import styleContent from "../../styles/ui/editable-component-controls.css?inline";
+
+export default class EditableComponentControls extends HTMLElement {
+	protected shadow?: ShadowRoot;
+	protected contextMenu?: HTMLUListElement;
+	protected buttonRow?: HTMLDivElement;
+
+	private editButton?: HTMLButtonElement;
+
+	render(shadow: ShadowRoot): void {
+		const style = document.createElement("style");
+		style.textContent = styleContent;
+		shadow.appendChild(style);
+
+		this.buttonRow = document.createElement("div");
+		this.buttonRow.classList.add("button-row");
+		shadow.appendChild(this.buttonRow);
+
+		this.contextMenu = document.createElement("ul");
+		this.contextMenu.classList.add("context-menu");
+		shadow.appendChild(this.contextMenu);
+
+		this.editButton = document.createElement("button");
+		this.editButton.innerHTML = '<cc-icon name="edit"></cc-icon>';
+		this.editButton.onclick = () => {
+			this.dispatchEvent(new CustomEvent("edit", { detail: this }));
+		};
+		this.buttonRow.append(this.editButton);
+
+		this.onclick = () => {
+			this.contextMenu?.classList.remove("open");
+			this.removeAttribute("open");
+		};
+
+		this.onblur = () => {
+			this.contextMenu?.classList.remove("open");
+			this.removeAttribute("open");
+		};
+	}
+
+	connectedCallback() {
+		if (this.shadow) {
+			return;
+		}
+
+		this.shadow = this.attachShadow({ mode: "open" });
+		this.render(this.shadow);
+	}
+}
+
+customElements.define("editable-component-controls", EditableComponentControls);
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"editable-component-controls": EditableComponentControls;
+	}
+}

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

@@ -0,0 +1,77 @@
+import styleContent from "../../styles/ui/editable-region-error-card.css?inline";
+
+export default class EditableRegionErrorCard extends HTMLElement {
+	private _error?: unknown;
+	private shadow?: ShadowRoot;
+
+	set error(err: unknown) {
+		this._error = err;
+		if (this.shadow) {
+			this.render(this.shadow, this._error);
+		}
+	}
+
+	connectedCallback() {
+		if (this.shadow) {
+			return;
+		}
+
+		this.shadow = this.attachShadow({ mode: "open" });
+
+		this.render(this.shadow, this._error);
+	}
+
+	render(shadow: ShadowRoot, error: unknown) {
+		const style = document.createElement("style");
+		style.textContent = styleContent;
+		shadow.appendChild(style);
+
+		const container = document.createElement("div");
+		container.className = "container";
+		shadow.appendChild(container);
+
+		const icon = document.createElement("cc-icon");
+		icon.setAttribute("name", "warning");
+		container.appendChild(icon);
+
+		const body = document.createElement("div");
+		container.appendChild(body);
+
+		const heading = document.createElement("p");
+		heading.className = "heading";
+		heading.innerHTML = this.getAttribute("heading") ?? "Error";
+
+		body.appendChild(heading);
+
+		if (this.hasAttribute("message")) {
+			const message = document.createElement("p");
+			message.innerHTML = this.getAttribute("message") ?? "";
+
+			body.appendChild(message);
+		} else if (error instanceof Error) {
+			const message = document.createElement("p");
+			message.innerHTML = error.message;
+
+			body.appendChild(message);
+
+			if (error.stack) {
+				const stack = document.createElement("pre");
+				stack.innerHTML = error.stack
+					.replace(new RegExp(window.location.origin, "g"), "")
+					.split("\n")
+					.slice(0, 5)
+					.join("\n");
+
+				body.appendChild(stack);
+			}
+		}
+	}
+}
+
+customElements.define("editable-region-error-card", EditableRegionErrorCard);
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"editable-region-error-card": EditableRegionErrorCard;
+	}
+}

package/helpers/checks.ts

@@ -0,0 +1,126 @@
+import EditableArrayItem from "../nodes/editable-array-item.js";
+import EditableText from "../nodes/editable-text.js";
+import Editable from "../nodes/editable.js";
+
+const TAG_NAMES = [
+	"EDITABLE-TEXT",
+	"EDITABLE-COMPONENT",
+	"EDITABLE-ARRAY-ITEM",
+	"EDITABLE-ARRAY",
+	"EDITABLE-IMAGE",
+	"EDITABLE-SOURCE",
+	"EDITABLE-SNIPPET",
+];
+
+const EDITABLE_REGION_TYPES = [
+	"text",
+	"component",
+	"array",
+	"array-item",
+	"image",
+	"source",
+];
+
+const CORRESPONDING_NAME: Record<string, string> = {
+	"EDITABLE-TEXT": "text",
+	"EDITABLE-COMPONENT": "component",
+	"EDITABLE-ARRAY-ITEM": "array-item",
+	"EDITABLE-ARRAY": "array",
+	"EDITABLE-IMAGE": "image",
+	"EDITABLE-SOURCE": "source",
+};
+
+export const hasEditable = <T extends object>(
+	el: T,
+): el is T & { editable: Editable } => {
+	return "editable" in el && el.editable instanceof Editable;
+};
+
+export const hasEditableText = <T extends object>(
+	el: T,
+): el is T & { editable: EditableText } => {
+	return "editable" in el && el.editable instanceof EditableText;
+};
+
+export const hasEditableArrayItem = <T extends object>(
+	el: T,
+): el is T & { editable: EditableArrayItem } => {
+	return "editable" in el && el.editable instanceof EditableArrayItem;
+};
+
+export const isEditableElement = (el: unknown): boolean => {
+	if (!(el instanceof HTMLElement)) {
+		return false;
+	}
+
+	return (
+		TAG_NAMES.includes(el.tagName) ||
+		(!!el.dataset.editable &&
+			EDITABLE_REGION_TYPES.includes(el.dataset.editable))
+	);
+};
+
+export const areEqualEditables = (a: HTMLElement, b: HTMLElement) => {
+	if (
+		a.tagName !== b.tagName &&
+		a.dataset.editable !== b.dataset.editable &&
+		CORRESPONDING_NAME[a.tagName] !== b.dataset.editable &&
+		CORRESPONDING_NAME[b.tagName] !== a.dataset.editable
+	) {
+		return false;
+	}
+
+	if (Object.keys(a.dataset).length !== Object.keys(b.dataset).length) {
+		return false;
+	}
+
+	return Object.keys(a.dataset).every(
+		(key) => a.dataset[key] === b.dataset[key],
+	);
+};
+
+export const isEditableText = (el?: Element | null): boolean => {
+	return (
+		el?.tagName === "EDITABLE-TEXT" ||
+		(el instanceof HTMLElement && el.dataset.editable === "text")
+	);
+};
+
+export const isEditableArrayItem = (el?: Element | null): boolean => {
+	return (
+		el?.tagName === "EDITABLE-ARRAY-ITEM" ||
+		(el instanceof HTMLElement && el.dataset.editable === "array-item")
+	);
+};
+
+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);
+};

package/helpers/cloudcannon.ts

@@ -0,0 +1,67 @@
+import type {
+	CloudCannonEditorWindow,
+	CloudCannonJavaScriptV1API,
+} from "@cloudcannon/javascript-api";
+
+export type ComponentRenderer = (
+	props: any,
+) => HTMLElement | Promise<HTMLElement>;
+
+declare const window: CloudCannonEditorWindow & {
+	cc_components?: Record<string, ComponentRenderer>;
+	cc_snippets?: Record<string, ComponentRenderer>;
+};
+
+let _cloudcannon: CloudCannonJavaScriptV1API;
+
+const apiLoadedPromise = new Promise<void>((resolve) => {
+	if (window.CloudCannonAPI) {
+		_cloudcannon = window.CloudCannonAPI.useVersion("v1") as any;
+		resolve();
+	} else {
+		document.addEventListener(
+			"cloudcannon:load",
+			() => {
+				if (window.CloudCannonAPI) {
+					_cloudcannon = window.CloudCannonAPI.useVersion("v1") as any;
+				}
+				return resolve();
+			},
+			{ once: true },
+		);
+	}
+});
+
+export const loadedPromise = Promise.all([
+	apiLoadedPromise,
+	customElements.whenDefined("editable-array-item"),
+	customElements.whenDefined("editable-array"),
+	customElements.whenDefined("editable-text"),
+	customElements.whenDefined("editable-component"),
+	customElements.whenDefined("editable-image"),
+	customElements.whenDefined("editable-source"),
+	customElements.whenDefined("editable-snippet"),
+]);
+
+export const addEditableComponentRenderer = (
+	key: string,
+	renderer: ComponentRenderer,
+) => {
+	window.cc_components = window.cc_components || {};
+	window.cc_components[key] = renderer;
+	document.dispatchEvent(new CustomEvent(`editable-regions:registered-${key}`));
+};
+
+export const addEditableSnippetRenderer = (
+	key: string,
+	renderer: ComponentRenderer,
+) => {
+	window.cc_snippets = window.cc_snippets || {};
+	window.cc_snippets[key] = renderer;
+	document.dispatchEvent(new CustomEvent(`editable-regions:registered-${key}`));
+};
+
+export const getEditableComponentRenderers = () => window.cc_components ?? {};
+export const getEditableSnippetRenderers = () => window.cc_snippets ?? {};
+
+export { _cloudcannon as CloudCannon };