@cloudcannon/editable-regions 0.0.2

package/nodes/editable-text.ts

@@ -0,0 +1,163 @@
+import { CloudCannon } from "../helpers/cloudcannon.js";
+import Editable from "./editable.js";
+
+type EditableFocusEvent = CustomEvent<number>;
+
+export default class EditableText extends Editable {
+	editor?: any;
+	focused = false;
+	focusIndex = 0;
+	value: string | null | undefined;
+
+	validateConfiguration(): boolean {
+		const prop = this.element.dataset.prop;
+		if (typeof prop !== "string") {
+			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");
+			this.element.replaceChildren(error);
+			return false;
+		}
+
+		const elementType = this.element.dataset.type;
+		if (
+			typeof elementType === "string" &&
+			!["span", "text", "block"].includes(elementType)
+		) {
+			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",
+				`Unsupported element type: "${elementType}". Supported element types are span, text, and block.`,
+			);
+			this.element.replaceChildren(error);
+			return false;
+		}
+		return true;
+	}
+
+	validateValue(value: unknown): string | null | undefined {
+		if (typeof value !== "string" && value !== null) {
+			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",
+				`Illegal value type: ${typeof value}. Supported types are string.`,
+			);
+			this.element.replaceChildren(error);
+			return;
+		}
+		return value;
+	}
+
+	shouldUpdate(value: string) {
+		return (
+			!this.focused &&
+			value !== this.value &&
+			(typeof value === "string" || value === null)
+		);
+	}
+
+	update(): void {
+		this.editor?.setContent(this.value);
+	}
+
+	mount(): void {
+		this.element.addEventListener("blur", () => {
+			this.focused = false;
+			this.element.dispatchEvent(
+				new CustomEvent("editable:blur", {
+					bubbles: true,
+					detail: this.focusIndex,
+				}),
+			);
+		});
+
+		this.element.addEventListener("focus", () => {
+			this.focusIndex += 1;
+			this.element.dispatchEvent(
+				new CustomEvent("editable:focus", {
+					bubbles: true,
+					detail: this.focusIndex,
+				}),
+			);
+		});
+
+		this.element.addEventListener("editable:focus", (e: EditableFocusEvent) => {
+			this.focused = true;
+			this.focusIndex = e.detail;
+		});
+
+		this.element.addEventListener("editable:blur", (e: EditableFocusEvent) => {
+			if (e.detail >= this.focusIndex) {
+				this.focused = false;
+			}
+		});
+
+		if (typeof this.element.dataset.deferMount === "string") {
+			this.element.onclick = () => {
+				this.focused = true;
+				this.mountEditor().then(() => {
+					this.element.focus();
+				});
+			};
+			return;
+		}
+
+		if (!this.editor) {
+			this.mountEditor();
+		}
+	}
+
+	async mountEditor(): Promise<any> {
+		if (this.editor) {
+			return this.editor;
+		}
+
+		const source = this.resolveSource();
+
+		if (!source) {
+			throw new Error("Source not found");
+		}
+
+		const inputConfig = source.endsWith("@content")
+			? { type: "markdown" }
+			: await this.dispatchGetInputConfig(this.element.dataset.prop);
+
+		this.editor = await CloudCannon.createTextEditableRegion(
+			this.element,
+			this.onChange.bind(this),
+			{
+				elementType: this.element.dataset.type,
+				editableType: source.endsWith("@content") ? "content" : undefined,
+				inputConfig,
+			},
+		);
+
+		if (typeof this.value === "string") {
+			this.update();
+		}
+
+		return this.editor;
+	}
+
+	onChange(value?: string | null) {
+		const source = this.element.dataset.prop;
+		if (typeof source !== "string") {
+			throw new Error("Source not found");
+		}
+
+		this.value = value;
+		this.dispatchSet(source, value);
+	}
+}
+
+declare global {
+	interface HTMLElementEventMap {
+		"editable:focus": EditableFocusEvent;
+		"editable:blur": EditableFocusEvent;
+	}
+}

package/nodes/editable.ts

@@ -0,0 +1,471 @@
+import type {
+	CloudCannonJavaScriptV1APICollection,
+	CloudCannonJavaScriptV1APIDataset,
+	CloudCannonJavaScriptV1APIFile,
+} from "@cloudcannon/javascript-api";
+import { hasEditable } from "../helpers/checks";
+import { CloudCannon, loadedPromise } from "../helpers/cloudcannon";
+
+export interface EditableListener {
+	editable: Editable;
+	key?: string;
+	path?: string;
+}
+
+export interface APIListener {
+	obj:
+		| CloudCannonJavaScriptV1APIFile
+		| CloudCannonJavaScriptV1APICollection
+		| CloudCannonJavaScriptV1APIDataset;
+	fn: () => void;
+	event: "change" | "delete";
+}
+
+export default class Editable {
+	APIListeners: APIListener[] = [];
+	listeners: EditableListener[] = [];
+	value: unknown = undefined;
+	parent: Editable | null = null;
+	element: HTMLElement;
+	mounted = false;
+	connected = false;
+
+	propsBase: unknown;
+	props: Record<string, unknown> = {};
+
+	constructor(element: HTMLElement) {
+		this.element = element;
+		(element as any).editable = this;
+	}
+
+	async lookupPath(path: string, obj: unknown): Promise<any> {
+		if (!path) {
+			return obj;
+		}
+		return path.split(".").reduce(async (acc, key) => {
+			acc = await acc;
+
+			if (CloudCannon.isAPICollection(acc)) {
+				acc = await acc.items();
+			} else if (CloudCannon.isAPIFile(acc)) {
+				if (key === "@content") {
+					return acc.content.get();
+				}
+				acc = await acc.data.get();
+			} else if (CloudCannon.isAPIDataset(acc)) {
+				const items = await acc.items();
+				if (Array.isArray(items)) {
+					acc = items;
+				} else {
+					acc = await items.data.get();
+				}
+			}
+
+			if (acc && typeof acc === "object" && key in acc) {
+				return (acc as any)[key];
+			}
+		}, obj);
+	}
+
+	shouldUpdate(_value: unknown) {
+		return true;
+	}
+
+	async getNewValue(
+		value: unknown,
+		listener?: EditableListener,
+	): Promise<unknown> {
+		const { key, path } = listener ?? {};
+		const resolvedValue = path ? await this.lookupPath(path, value) : value;
+		if (!key) {
+			this.propsBase = resolvedValue;
+		} else {
+			this.props[key] = resolvedValue;
+		}
+
+		if (Object.entries(this.props).length === 0) {
+			return this.validateValue(this.propsBase);
+		}
+
+		const newValue = Object.entries(this.props).reduce(
+			(acc, [key, val]) => {
+				(acc as any)[key] = structuredClone(val);
+				return acc;
+			},
+			structuredClone(this.propsBase ?? {}),
+		);
+
+		return this.validateValue(newValue);
+	}
+
+	async pushValue(value: unknown, listener?: EditableListener): Promise<void> {
+		const newValue = await this.getNewValue(value, listener);
+
+		if (typeof newValue === "undefined" || !this.shouldUpdate(newValue)) {
+			return;
+		}
+
+		this.value = newValue;
+		if (this.connected && !this.mounted) {
+			this.mounted = true;
+			this.mount();
+			return this.update();
+		}
+
+		if (this.mounted) {
+			return this.update();
+		}
+	}
+
+	update(): void {
+		this.listeners.forEach((listener) =>
+			listener.editable.pushValue(this.value, listener),
+		);
+	}
+
+	validateValue(value: unknown): unknown {
+		return value;
+	}
+
+	registerListener(listener: EditableListener): void {
+		if (
+			this.listeners.find(
+				({ editable: other, key }) =>
+					listener.editable.element === other.element && listener.key === key,
+			)
+		) {
+			return;
+		}
+
+		if (this.value !== undefined) {
+			listener.editable.pushValue(this.value, listener);
+		}
+
+		this.listeners.push(listener);
+	}
+
+	deregisterListener(target: Editable): void {
+		this.listeners = this.listeners.filter(
+			({ editable }) => editable.element !== target.element,
+		);
+	}
+
+	disconnect(): void {
+		this.parent?.deregisterListener(this);
+		this.parent = null;
+		this.APIListeners.forEach(({ obj, fn, event }) =>
+			obj.removeEventListener(event, fn),
+		);
+	}
+
+	resolveSource(source?: string): string | undefined {
+		if (typeof source !== "string") {
+			return this.parent
+				? this.parent.resolveSource(this.element.dataset.prop)
+				: this.element.dataset.prop;
+		}
+
+		const [part, ...rest] = source.split(".");
+		const propKey = part.charAt(0).toUpperCase() + part.slice(1);
+		const propPath = this.element.dataset[`prop${propKey}`];
+
+		if (propPath) {
+			rest.unshift(propPath);
+			return this.parent
+				? this.parent.resolveSource(rest.join("."))
+				: rest.join(".");
+		}
+
+		if (typeof this.element.dataset.prop !== "string") {
+			throw new Error(`Failed to resolve source "${source}"`);
+		}
+
+		if (this.element.dataset.prop) {
+			source = `${this.element.dataset.prop}.${source}`;
+		}
+
+		return this.parent && !source.startsWith("@")
+			? this.parent.resolveSource(source)
+			: source;
+	}
+
+	connect(): void {
+		loadedPromise.then(() => {
+			this.setupListeners();
+			if (this.validateConfiguration()) {
+				this.connected = true;
+				if (this.value !== undefined && !this.mounted) {
+					this.mounted = true;
+					this.mount();
+					this.update();
+				}
+			}
+		});
+	}
+
+	setupListeners(): void {
+		let parentEditable: Editable | undefined;
+		let parent = this.element.parentElement;
+		while (parent) {
+			if (hasEditable(parent)) {
+				parentEditable = parent.editable;
+				break;
+			}
+			parent = parent.parentElement;
+		}
+
+		this.parent = parentEditable || null;
+
+		let hasProps = false;
+		Object.entries(this.element.dataset).forEach(
+			async ([propName, propPath]) => {
+				if (!propName.startsWith("prop") || typeof propPath !== "string") {
+					return;
+				}
+
+				hasProps = true;
+
+				const { collection, file, dataset, source, absolute } =
+					this.parseSource(propPath);
+
+				const listener = {
+					editable: this,
+					key:
+						propName === "prop"
+							? undefined
+							: propName.substring(4).toLowerCase(),
+					path: source,
+				};
+
+				if (!absolute && parentEditable) {
+					parentEditable.registerListener(listener);
+					return;
+				}
+
+				// Any single data path should only be able to refer to a single absolute API object
+				const obj = collection || dataset || file;
+				if (obj) {
+					const handleAPIChange = () => {
+						this.pushValue(obj, listener);
+					};
+					this.APIListeners.push({
+						obj,
+						fn: handleAPIChange,
+						event: "change",
+					});
+					obj.addEventListener("change", handleAPIChange);
+					handleAPIChange();
+				}
+			},
+		);
+
+		this.element.addEventListener("cloudcannon-api", async (e: any) => {
+			if (e.target !== this.element) {
+				if (!e.detail.source) {
+					e.detail.source = this.element.dataset.prop;
+				} else {
+					const source = e.detail.source;
+					const [part, ...rest] = source.split(".");
+					const propKey = part.charAt(0).toUpperCase() + part.slice(1);
+					const propPath = this.element.dataset[`prop${propKey}`];
+
+					if (propPath) {
+						rest.unshift(propPath);
+						e.detail.source = rest.join(".");
+					} else if (this.element.dataset.prop) {
+						e.detail.source = `${this.element.dataset.prop}.${source}`;
+					}
+				}
+			}
+
+			const { absolute } = this.parseSource(e.detail.source);
+			if (!this.parent || absolute) {
+				if (this.executeApiCall(e.detail)) {
+					e.stopPropagation();
+				}
+			}
+		});
+
+		if (!hasProps) {
+			this.mount();
+		}
+	}
+
+	executeApiCall(options: any): boolean {
+		let { file, collection, source, dataset } = this.parseSource(
+			options.source,
+		);
+
+		let filePromise: Promise<CloudCannonJavaScriptV1APIFile | undefined>;
+		if (!file) {
+			if (collection && source) {
+				const parts = source.split(".");
+				const first = Number(parts.shift());
+				filePromise = collection.items().then((items) => items[first]);
+				source = parts.join(".");
+			} else if (dataset) {
+				filePromise = dataset.items().then((items) => {
+					if (Array.isArray(items) && source) {
+						const parts = source.split(".");
+						const first = Number(parts.shift());
+						source = parts.join(".");
+						return items[first];
+					}
+
+					if (CloudCannon.isAPIFile(items)) {
+						return items;
+					}
+				});
+			} else {
+				filePromise = Promise.resolve(undefined);
+			}
+		} else {
+			filePromise = Promise.resolve(file);
+		}
+
+		filePromise.then((file) => {
+			if (typeof source !== "string") {
+				if (options.action === "get-input-config") {
+					options.callback({
+						options: {
+							disable_reorder: true,
+							disable_remove: true,
+						},
+					});
+					return true;
+				}
+				throw new Error(
+					`Failed to resolve source for API call: ${options.source}`,
+				);
+			}
+			switch (options.action) {
+				case "edit":
+					file?.data.edit({ slug: source });
+					break;
+				case "set":
+					if (source?.endsWith("@content")) {
+						file?.content.set(options.value);
+					} else if (source) {
+						file?.data.set({ slug: source, value: options.value });
+					}
+					break;
+				case "add-array-item":
+					file?.data.addArrayItem({
+						slug: source,
+						index: options.newIndex,
+						value: options.value,
+					});
+					break;
+				case "remove-array-item":
+					file?.data.removeArrayItem({
+						slug: source,
+						index: options.fromIndex,
+					});
+					break;
+				case "move-array-item":
+					file?.data.moveArrayItem({
+						slug: source,
+						index: options.fromIndex,
+						toIndex: options.toIndex,
+					});
+					break;
+				case "get-input-config":
+					file?.getInputConfig({ slug: source }).then(options.callback);
+					break;
+			}
+		});
+
+		return true;
+	}
+
+	mount(): void {}
+
+	validateConfiguration(): boolean {
+		return true;
+	}
+
+	dispatchSet(source: string, value: unknown) {
+		this.element.dispatchEvent(
+			new CustomEvent("cloudcannon-api", {
+				bubbles: true,
+				detail: {
+					action: "set",
+					source,
+					value,
+				},
+			}),
+		);
+	}
+
+	async dispatchGetInputConfig(source?: string): Promise<any> {
+		return new Promise((resolve) => {
+			this.element.dispatchEvent(
+				new CustomEvent("cloudcannon-api", {
+					bubbles: true,
+					detail: {
+						action: "get-input-config",
+						source,
+						callback: resolve,
+					},
+				}),
+			);
+		});
+	}
+
+	parseSource(source?: string) {
+		let collection: CloudCannonJavaScriptV1APICollection | undefined;
+		let file: CloudCannonJavaScriptV1APIFile | undefined;
+		let dataset: CloudCannonJavaScriptV1APIDataset | undefined;
+		let absolute = false;
+
+		const collectionMatch = source?.match(
+			/^@collections\[(?<key>[^\]]+)\](\.(?<rest>.+))?$/,
+		);
+		if (collectionMatch?.groups) {
+			const { key, rest } = collectionMatch.groups;
+			collection = CloudCannon.collection(key);
+			source = rest;
+			absolute = true;
+		} else {
+			const fileMatch = source?.match(
+				/^@file\[(?<path>[^\]]+)\]\.(?<rest>.+)$/,
+			);
+			if (fileMatch?.groups) {
+				const { path, rest } = fileMatch.groups;
+				file = CloudCannon.file(path);
+				source = rest;
+				absolute = true;
+			} else {
+				const dataMatch = source?.match(
+					/^@data\[(?<key>[^\]]+)\](\.(?<rest>.+))?$/,
+				);
+				if (dataMatch?.groups) {
+					const { key, rest } = dataMatch.groups;
+					dataset = CloudCannon.dataset(key);
+					source = rest;
+					absolute = true;
+				} else {
+					file = CloudCannon.currentFile();
+				}
+			}
+		}
+
+		const snippets = [];
+		let snippetMatch = source?.match(/@snippet\[(?<id>[^\]]+)\]\.(?<rest>.+)$/);
+		while (snippetMatch?.groups) {
+			const { id, rest } = snippetMatch.groups;
+			snippets.push(id);
+			source = rest;
+			snippetMatch = source.match(/@snippet\[(?<id>[^\]]+)\]\.(?<rest>.+)$/);
+		}
+
+		return {
+			collection,
+			file,
+			source,
+			absolute,
+			snippets,
+			dataset,
+		};
+	}
+}

package/nodes/index.ts

@@ -0,0 +1,8 @@
+export { default as Editable } from "./editable.js";
+export { default as EditableArray } from "./editable-array.js";
+export { default as EditableArrayItem } from "./editable-array-item.js";
+export { default as EditableText } from "./editable-text.js";
+export { default as EditableComponent } from "./editable-component.js";
+export { default as EditableImage } from "./editable-image.js";
+export { default as EditableSource } from "./editable-source.js";
+export { default as EditableSnippet } from "./editable-snippet.js";

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@cloudcannon/editable-regions",
+	"version": "0.0.2",
+	"type": "module",
+	"description": "Visual Editing for the CloudCannon CMS.",
+	"keywords": [
+		"cloudcannon"
+	],
+	"license": "MIT",
+	"author": "CloudCannon <support@cloudcannon.com>",
+	"homepage": "https://github.com/CloudCannon/editable-regions#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/CloudCannon/editable-regions.git"
+	},
+	"bugs": {
+		"url": "https://github.com/CloudCannon/editable-regions/issues",
+		"email": "support@cloudcannon.com"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"typecheck:watch": "tsc --noEmit --watch",
+		"lint-autofix": "biome check --fix",
+		"lint": "biome check"
+	},
+	"files": [
+		"components",
+		"helpers",
+		"integrations",
+		"nodes",
+		"styles",
+		"types"
+	],
+	"exports": {
+		"./*": null,
+		"./astro": {
+			"default": "./integrations/astro/index.mjs",
+			"types": "./types/astro.d.ts"
+		},
+		"./astro-react-renderer": {
+			"default": "./integrations/astro/react-renderer.mjs",
+			"types": "./types/astro.d.ts"
+		},
+		"./astro-integration": {
+			"default": "./integrations/astro/astro-integration.mjs",
+			"types": "./types/astro.d.ts"
+		},
+		"./react": {
+			"default": "./integrations/react.mjs",
+			"types": "./types/react.d.ts"
+		},
+		"./internal/components": "./components/index.js",
+		"./internal/styles": "./styles/index.js"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "1.9.4",
+		"@cloudcannon/javascript-api": "0.0.9",
+		"@types/js-beautify": "1.14.3",
+		"@types/react": "18.3.12",
+		"@types/react-dom": "18.3.1",
+		"astro": "^5.14.1",
+		"typescript": "5.9.3"
+	}
+}

package/styles/editable-array-item.css

@@ -0,0 +1,8 @@
+editable-array-item {
+	display: block;
+}
+
+editable-array-item,
+[data-editable="array-item"] {
+	position: relative;
+}