@schukai/monster 4.127.1 → 4.128.1

package/source/dom/updater.mjs

@@ -24,9 +24,13 @@ import {
 	ATTRIBUTE_UPDATER_INSERT,
 	ATTRIBUTE_UPDATER_INSERT_REFERENCE,
 	ATTRIBUTE_UPDATER_PROPERTIES,
+	ATTRIBUTE_UPDATER_PATCH,
+	ATTRIBUTE_UPDATER_PATCH_KEY,
+	ATTRIBUTE_UPDATER_PATCH_RENDER,
 	ATTRIBUTE_UPDATER_REMOVE,
 	ATTRIBUTE_UPDATER_REPLACE,
 	ATTRIBUTE_UPDATER_SELECT_THIS,
+	customElementUpdaterLinkSymbol,
 } from "./constants.mjs";
 
 import { Base } from "../types/base.mjs";
@@ -42,7 +46,13 @@ import { ProxyObserver } from "../types/proxyobserver.mjs";
 import { validateArray, validateInstance } from "../types/validate.mjs";
 import { clone } from "../util/clone.mjs";
 import { trimSpaces } from "../util/trimspaces.mjs";
-import { addAttributeToken, addToObjectLink } from "./attributes.mjs";
+import {
+	addAttributeToken,
+	addToObjectLink,
+	getLinkedObjects,
+	hasObjectLink,
+	removeObjectLink,
+} from "./attributes.mjs";
 import {
 	CustomElement,
 	updaterTransformerMethodsSymbol,
@@ -75,12 +85,16 @@ const processingSymbol = Symbol("processing");
 const processQueueSymbol = Symbol("processQueue");
 const applyChangeSymbol = Symbol("applyChange");
 const updaterRootSymbol = Symbol.for("@schukai/monster/dom/@@updater-root");
+const disposedSymbol = Symbol("disposed");
+const subjectObserverSymbol = Symbol("subjectObserver");
+const patchNodeKeySymbol = Symbol("patchNodeKey");
 
 /**
  * The updater class connects an object with the DOM. In this way, structures and contents in the DOM can be
  * programmatically adapted via attributes.
  *
- * For example, to include a string from an object, the attribute `data-monster-replace` can be used.
+ * For example, to include a string from an object, the attribute `data-monster-replace`
+ * or the lifecycle-safe `data-monster-patch` can be used.
  * a further explanation can be found under [monsterjs.org](https://monsterjs.org/)
  *
  * Changes to attributes are made only when the direct values are changed. If you want to assign changes
@@ -140,19 +154,23 @@ class Updater extends Base {
 
 		this[pendingDiffsSymbol] = [];
 		this[processingSymbol] = false;
+		this[disposedSymbol] = false;
 
-		this[internalSymbol].subject.attachObserver(
-			new Observer(() => {
-				const real = this[internalSymbol].subject.getRealSubject();
-				const diffResult = diff(this[internalSymbol].last, real);
-				this[internalSymbol].last = clone(real);
-				if (diffResult.length === 0) {
-					return Promise.resolve();
-				}
-				this[pendingDiffsSymbol].push(diffResult);
-				return this[processQueueSymbol]();
-			}),
-		);
+		this[subjectObserverSymbol] = new Observer(() => {
+			if (this[disposedSymbol] === true) {
+				return Promise.resolve();
+			}
+
+			const real = this[internalSymbol].subject.getRealSubject();
+			const diffResult = diff(this[internalSymbol].last, real);
+			this[internalSymbol].last = clone(real);
+			if (diffResult.length === 0) {
+				return Promise.resolve();
+			}
+			this[pendingDiffsSymbol].push(diffResult);
+			return this[processQueueSymbol]();
+		});
+		this[internalSymbol].subject.attachObserver(this[subjectObserverSymbol]);
 	}
 
 	/**
@@ -160,6 +178,10 @@ class Updater extends Base {
 	 * @return {Promise}
 	 */
 	async [processQueueSymbol]() {
+		if (this[disposedSymbol] === true) {
+			return Promise.resolve();
+		}
+
 		if (this[processingSymbol]) {
 			return Promise.resolve();
 		}
@@ -167,6 +189,11 @@ class Updater extends Base {
 
 		try {
 			while (this[pendingDiffsSymbol].length) {
+				if (this[disposedSymbol] === true) {
+					this[pendingDiffsSymbol].length = 0;
+					return Promise.resolve();
+				}
+
 				const diffResult = this[pendingDiffsSymbol].shift();
 				if (this[internalSymbol].features.batchUpdates === true) {
 					const updatePaths = new Map();
@@ -208,6 +235,10 @@ class Updater extends Base {
 
 	/** @private **/
 	async [applyChangeSymbol](change) {
+		if (this[disposedSymbol] === true) {
+			return Promise.resolve();
+		}
+
 		removeElement.call(this, change);
 		insertElement.call(this, change);
 		updateContent.call(this, change);
@@ -255,6 +286,10 @@ class Updater extends Base {
 	 * @throws {Error} the bind argument must start as a value with a path
 	 */
 	enableEventProcessing() {
+		if (this[disposedSymbol] === true) {
+			return this;
+		}
+
 		this.disableEventProcessing();
 
 		this[internalSymbol].element[updaterRootSymbol] = true;
@@ -293,6 +328,28 @@ class Updater extends Base {
 		return this;
 	}
 
+	dispose() {
+		if (this[disposedSymbol] === true) {
+			return this;
+		}
+
+		this[disposedSymbol] = true;
+		this.disableEventProcessing();
+		this[pendingDiffsSymbol].length = 0;
+
+		if (this[subjectObserverSymbol] instanceof Observer) {
+			this[internalSymbol].subject.detachObserver(this[subjectObserverSymbol]);
+		}
+
+		delete this[timerElementEventHandlerSymbol];
+
+		return this;
+	}
+
+	isDisposed() {
+		return this[disposedSymbol] === true;
+	}
+
 	/**
 	 * The run method must be called for the update to start working.
 	 * The method ensures that changes are detected.
@@ -307,6 +364,10 @@ class Updater extends Base {
 	 * @return {Promise}
 	 */
 	run() {
+		if (this[disposedSymbol] === true) {
+			return Promise.resolve();
+		}
+
 		// the key __init__has no further meaning and is only
 		// used to create the diff for empty objects.
 		this[internalSymbol].last = { __init__: true };
@@ -320,6 +381,10 @@ class Updater extends Base {
 	 * @return {Monster.DOM.Updater}
 	 */
 	retrieve() {
+		if (this[disposedSymbol] === true) {
+			return this;
+		}
+
 		retrieveFromBindings.call(this);
 		return this;
 	}
@@ -399,6 +464,13 @@ function getControlEventHandler() {
 	 * @param {Event} event
 	 */
 	this[symbol] = (event) => {
+		if (
+			this[disposedSymbol] === true ||
+			!this[internalSymbol].element?.isConnected
+		) {
+			return;
+		}
+
 		const root = findClosestUpdaterRootFromEvent(event);
 		if (root !== this[internalSymbol].element) {
 			return;
@@ -419,6 +491,14 @@ function getControlEventHandler() {
 		}
 
 		this[timerElementEventHandlerSymbol] = new DeadMansSwitch(50, () => {
+			if (
+				this[disposedSymbol] === true ||
+				!this[internalSymbol].element?.isConnected ||
+				!element?.isConnected
+			) {
+				return;
+			}
+
 			try {
 				retrieveAndSetValue.call(this, element);
 			} catch (e) {
@@ -662,6 +742,7 @@ function removeElement(change) {
 	for (const [, element] of this[internalSymbol].element
 		.querySelectorAll(`:scope [${ATTRIBUTE_UPDATER_REMOVE}]`)
 		.entries()) {
+		teardownManagedSubtree(element);
 		element.parentNode.removeChild(element);
 	}
 }
@@ -785,6 +866,7 @@ function insertElement(change) {
 						)
 					) {
 						try {
+							teardownManagedSubtree(node);
 							containerElement.removeChild(node);
 						} catch (e) {
 							addErrorAttribute(containerElement, e);
@@ -850,6 +932,30 @@ function applyRecursive(node, key, path) {
 		);
 	}
 
+	if (node.hasAttribute(ATTRIBUTE_UPDATER_PATCH)) {
+		const value = node.getAttribute(ATTRIBUTE_UPDATER_PATCH);
+		node.setAttribute(
+			ATTRIBUTE_UPDATER_PATCH,
+			value.replaceAll(`path:${key}`, `path:${path}`),
+		);
+	}
+
+	if (node.hasAttribute(ATTRIBUTE_UPDATER_PATCH_KEY)) {
+		const value = node.getAttribute(ATTRIBUTE_UPDATER_PATCH_KEY);
+		node.setAttribute(
+			ATTRIBUTE_UPDATER_PATCH_KEY,
+			value.replaceAll(`path:${key}`, `path:${path}`),
+		);
+	}
+
+	if (node.hasAttribute(ATTRIBUTE_UPDATER_PATCH_RENDER)) {
+		const value = node.getAttribute(ATTRIBUTE_UPDATER_PATCH_RENDER);
+		node.setAttribute(
+			ATTRIBUTE_UPDATER_PATCH_RENDER,
+			value.replaceAll(`path:${key}`, `path:${path}`),
+		);
+	}
+
 	if (node.hasAttribute(ATTRIBUTE_UPDATER_ATTRIBUTES)) {
 		const value = node.getAttribute(ATTRIBUTE_UPDATER_ATTRIBUTES);
 		node.setAttribute(
@@ -902,12 +1008,14 @@ function updateContent(change) {
 
 	const p = clone(change?.["path"]);
 	runUpdateContent.call(this, this[internalSymbol].element, p, subject);
+	runUpdatePatch.call(this, this[internalSymbol].element, p, subject);
 
 	const slots = this[internalSymbol].element.querySelectorAll("slot");
 	if (slots.length > 0) {
 		for (const [, slot] of Object.entries(slots)) {
 			for (const [, element] of Object.entries(slot.assignedNodes())) {
 				runUpdateContent.call(this, element, p, subject);
+				runUpdatePatch.call(this, element, p, subject);
 			}
 		}
 	}
@@ -967,6 +1075,7 @@ function runUpdateContent(container, parts, subject) {
 			}
 
 			if (value instanceof HTMLElement) {
+				teardownChildNodes(element);
 				while (element.firstChild) {
 					element.removeChild(element.firstChild);
 				}
@@ -977,12 +1086,364 @@ function runUpdateContent(container, parts, subject) {
 					addErrorAttribute(element, e);
 				}
 			} else {
+				teardownChildNodes(element);
 				element.innerHTML = value;
 			}
 		}
 	}
 }
 
+function runUpdatePatch(container, parts, subject) {
+	if (!isArray(parts)) return;
+	if (!(container instanceof HTMLElement)) return;
+	parts = clone(parts);
+
+	const mem = new WeakSet();
+
+	while (parts.length > 0) {
+		const current = parts.join(".");
+		parts.pop();
+
+		const query = `[${ATTRIBUTE_UPDATER_PATCH}^="path:${current}"], [${ATTRIBUTE_UPDATER_PATCH}^="static:"], [${ATTRIBUTE_UPDATER_PATCH}^="i18n:"]`;
+		const e = container.querySelectorAll(`${query}`);
+
+		const iterator = new Set([...e]);
+		if (container.matches(query)) {
+			iterator.add(container);
+		}
+
+		for (const [element] of iterator.entries()) {
+			if (mem.has(element)) return;
+			mem.add(element);
+
+			const attributes = element.getAttribute(ATTRIBUTE_UPDATER_PATCH);
+			const cmd = trimSpaces(attributes);
+
+			const pipe = new Pipe(cmd);
+			this[internalSymbol].callbacks.forEach((f, n) => {
+				pipe.setCallback(n, f);
+			});
+
+			let value;
+			try {
+				element.removeAttribute(ATTRIBUTE_ERRORMESSAGE);
+				value = pipe.run(subject);
+			} catch (e) {
+				element.setAttribute(ATTRIBUTE_ERRORMESSAGE, e.message);
+				continue;
+			}
+
+			applyPatchValue.call(this, element, value);
+		}
+	}
+}
+
+function applyPatchValue(element, value) {
+	if (!(element instanceof HTMLElement)) {
+		return;
+	}
+
+	if (isArray(value)) {
+		const keyDefinition = element.getAttribute(ATTRIBUTE_UPDATER_PATCH_KEY);
+		if (isString(keyDefinition) && trimSpaces(keyDefinition) !== "") {
+			replaceKeyedPatchedChildren.call(
+				this,
+				element,
+				value,
+				keyDefinition,
+				element.getAttribute(ATTRIBUTE_UPDATER_PATCH_RENDER),
+			);
+			return;
+		}
+
+		replacePatchedChildren(element, value);
+		return;
+	}
+
+	if (isInstance(value, DocumentFragment)) {
+		replacePatchedChildren(element, value);
+		return;
+	}
+
+	if (value instanceof HTMLElement) {
+		const existingChildren = Array.from(element.children);
+		if (existingChildren.length === 1 && existingChildren[0] === value) {
+			return;
+		}
+
+		teardownChildNodes(element);
+		while (element.firstChild) {
+			element.removeChild(element.firstChild);
+		}
+
+		try {
+			element.appendChild(value);
+		} catch (e) {
+			addErrorAttribute(element, e);
+		}
+		return;
+	}
+
+	const nextValue = value === null || value === undefined ? "" : String(value);
+
+	if (element.children.length > 0) {
+		teardownChildNodes(element);
+	}
+
+	element.textContent = nextValue;
+}
+
+function replaceKeyedPatchedChildren(
+	element,
+	values,
+	keyDefinition,
+	renderDefinition,
+) {
+	if (!(element instanceof HTMLElement) || !isArray(values)) {
+		return;
+	}
+
+	const keyPipe = new Pipe(trimSpaces(keyDefinition));
+	this[internalSymbol].callbacks.forEach((f, n) => {
+		keyPipe.setCallback(n, f);
+	});
+	const renderPipe = createPatchRenderPipe.call(this, renderDefinition);
+
+	const existing = new Map();
+	for (const node of Array.from(element.childNodes)) {
+		const key = node?.[patchNodeKeySymbol];
+		if (key !== undefined && !existing.has(key)) {
+			existing.set(key, node);
+		}
+	}
+
+	const nextNodes = [];
+	for (const value of values) {
+		let key;
+		try {
+			key = keyPipe.run(value);
+		} catch (e) {
+			addErrorAttribute(element, e);
+			return;
+		}
+		let renderedValue;
+		try {
+			renderedValue = resolvePatchRenderValue(value, renderPipe);
+		} catch (e) {
+			addErrorAttribute(element, e);
+			return;
+		}
+
+		const normalizedKey = key === null || key === undefined ? "" : String(key);
+		if (existing.has(normalizedKey)) {
+			const reused = existing.get(normalizedKey);
+			existing.delete(normalizedKey);
+			const nextNode = preparePatchedNode(reused, renderedValue);
+			nextNode[patchNodeKeySymbol] = normalizedKey;
+			if (nextNode !== reused && reused.parentNode === element) {
+				element.replaceChild(nextNode, reused);
+			}
+			nextNodes.push(nextNode);
+			continue;
+		}
+
+		let created;
+		try {
+			created = createSinglePatchedNode(renderedValue);
+		} catch (e) {
+			addErrorAttribute(element, e);
+			return;
+		}
+		created[patchNodeKeySymbol] = normalizedKey;
+		nextNodes.push(created);
+	}
+
+	for (const node of existing.values()) {
+		if (node instanceof HTMLElement) {
+			teardownManagedSubtree(node);
+		}
+		if (node.parentNode === element) {
+			element.removeChild(node);
+		}
+	}
+
+	for (const node of nextNodes) {
+		if (node.parentNode !== element) {
+			element.appendChild(node);
+			continue;
+		}
+
+		if (element.lastChild !== node) {
+			element.appendChild(node);
+		}
+	}
+}
+
+function preparePatchedNode(node, value) {
+	if (node?.nodeType === Node.TEXT_NODE) {
+		if (
+			value === null ||
+			value === undefined ||
+			isString(value) ||
+			typeof value === "number" ||
+			typeof value === "boolean"
+		) {
+			node.textContent =
+				value === null || value === undefined ? "" : String(value);
+			return node;
+		}
+
+		return createSinglePatchedNode(value);
+	}
+
+	if (node instanceof HTMLElement) {
+		if (value === node) {
+			return node;
+		}
+
+		return createSinglePatchedNode(value);
+	}
+
+	return node;
+}
+
+function createPatchRenderPipe(renderDefinition) {
+	if (!isString(renderDefinition) || trimSpaces(renderDefinition) === "") {
+		return null;
+	}
+
+	const renderPipe = new Pipe(trimSpaces(renderDefinition));
+	this[internalSymbol].callbacks.forEach((f, n) => {
+		renderPipe.setCallback(n, f);
+	});
+
+	return renderPipe;
+}
+
+function resolvePatchRenderValue(value, renderPipe) {
+	if (!(renderPipe instanceof Pipe)) {
+		return value;
+	}
+
+	return renderPipe.run(value);
+}
+
+function replacePatchedChildren(element, value) {
+	if (!(element instanceof HTMLElement)) {
+		return;
+	}
+
+	const fragment = document.createDocumentFragment();
+
+	if (isArray(value)) {
+		for (const entry of value) {
+			appendPatchChild(fragment, entry);
+		}
+	} else if (isInstance(value, DocumentFragment)) {
+		fragment.appendChild(value);
+	}
+
+	teardownChildNodes(element);
+	while (element.firstChild) {
+		element.removeChild(element.firstChild);
+	}
+
+	element.appendChild(fragment);
+}
+
+function appendPatchChild(fragment, value) {
+	if (!(fragment instanceof DocumentFragment)) {
+		return;
+	}
+
+	if (value === null || value === undefined) {
+		return;
+	}
+
+	if (isArray(value)) {
+		for (const entry of value) {
+			appendPatchChild(fragment, entry);
+		}
+		return;
+	}
+
+	if (isInstance(value, DocumentFragment) || value instanceof HTMLElement) {
+		fragment.appendChild(value);
+		return;
+	}
+
+	fragment.appendChild(document.createTextNode(String(value)));
+}
+
+function createPatchedNodes(value) {
+	const fragment = document.createDocumentFragment();
+	appendPatchChild(fragment, value);
+	return Array.from(fragment.childNodes);
+}
+
+function createSinglePatchedNode(value) {
+	const nodes = createPatchedNodes(value);
+	if (nodes.length === 0) {
+		return document.createTextNode("");
+	}
+
+	if (nodes.length !== 1) {
+		throw new Error("keyed patch values must resolve to a single node");
+	}
+
+	return nodes[0];
+}
+
+function teardownChildNodes(root) {
+	if (!(root instanceof HTMLElement)) {
+		return;
+	}
+
+	for (const child of Array.from(root.children)) {
+		teardownManagedSubtree(child);
+	}
+}
+
+function teardownManagedSubtree(root) {
+	if (!(root instanceof HTMLElement)) {
+		return;
+	}
+
+	const elements = [root, ...root.querySelectorAll("*")];
+	for (const element of elements) {
+		if (!hasObjectLinkSafe(element, customElementUpdaterLinkSymbol)) {
+			continue;
+		}
+
+		try {
+			const linked = getLinkedObjects(element, customElementUpdaterLinkSymbol);
+			for (const updaterSet of linked) {
+				if (!(updaterSet instanceof Set)) {
+					continue;
+				}
+
+				for (const updater of updaterSet) {
+					if (typeof updater?.dispose === "function") {
+						updater.dispose();
+					}
+				}
+			}
+
+			removeObjectLink(element, customElementUpdaterLinkSymbol);
+		} catch (e) {
+			addErrorAttribute(element, e);
+		}
+	}
+}
+
+function hasObjectLinkSafe(element, symbol) {
+	try {
+		return hasObjectLink(element, symbol);
+	} catch (e) {
+		return false;
+	}
+}
+
 /**
  * @private
  * @since 1.8.0