@schukai/monster 4.153.0 → 4.154.0

package/source/dom/customcontrol.mjs

@@ -377,6 +377,7 @@ function getInternal() {
 }
 
 const debounceValueSymbol = Symbol("debounceValue");
+const pendingValueAttributeSymbol = Symbol("pendingValueAttribute");
 
 /**
  *
@@ -388,7 +389,17 @@ const debounceValueSymbol = Symbol("debounceValue");
  */
 function initValueAttributeObserver() {
 	const self = this;
-	this[attributeObserverSymbol]["value"] = () => {
+	this[attributeObserverSymbol]["value"] = (newValue, oldValue) => {
+		if (!self[pendingValueAttributeSymbol]) {
+			self[pendingValueAttributeSymbol] = {
+				oldValue: normalizeAttributeValue(oldValue),
+				newValue: normalizeAttributeValue(newValue),
+			};
+		} else {
+			self[pendingValueAttributeSymbol].newValue =
+				normalizeAttributeValue(newValue);
+		}
+
 		if (self[debounceValueSymbol] instanceof DeadMansSwitch) {
 			try {
 				self[debounceValueSymbol].touch();
@@ -402,18 +413,33 @@ function initValueAttributeObserver() {
 		}
 
 		self[debounceValueSymbol] = new DeadMansSwitch(10, () => {
-			const oldValue = self.getAttribute("value");
-			const newValue = self.value;
-
-			if (oldValue !== newValue) {
-				setTimeout(() => {
-					self.value = self.getAttribute("value") ?? "";
-				}, 0);
-			}
+			const pending = self[pendingValueAttributeSymbol];
+			delete self[pendingValueAttributeSymbol];
+			delete self[debounceValueSymbol];
+			if (!pending) return;
+
+			setTimeout(() => {
+				const currentValue = normalizeAttributeValue(self.value);
+				if (
+					currentValue === pending.oldValue &&
+					currentValue !== pending.newValue
+				) {
+					self.value = pending.newValue;
+				}
+			}, 0);
 		});
 	};
 }
 
+/**
+ * @param {*} value
+ * @return {string}
+ * @private
+ */
+function normalizeAttributeValue(value) {
+	return value === null || value === undefined ? "" : String(value);
+}
+
 const disabledSyncSymbol = Symbol("disabledSync");
 const disabledAttributeSyncSymbol = Symbol("disabledAttributeSync");
 

package/source/dom/customelement.mjs

@@ -36,7 +36,11 @@ import {
 	validateObject,
 } from "../types/validate.mjs";
 import { clone } from "../util/clone.mjs";
-import { getLinkedObjects, hasObjectLink } from "./attributes.mjs";
+import {
+	getLinkedObjects,
+	hasObjectLink,
+	removeObjectLink,
+} from "./attributes.mjs";
 import {
 	ATTRIBUTE_DISABLED,
 	ATTRIBUTE_OPTIONS,
@@ -119,6 +123,8 @@ const updateCloneDataSymbol = Symbol("@schukai/monster/dom/@@updateCloneData");
 const scriptHostElementSymbol = Symbol("scriptHostElement");
 const optionDefaultsSymbol = Symbol("optionDefaults");
 const managedShadowRootSymbol = Symbol("managedShadowRoot");
+const assembledOnceSymbol = Symbol("assembledOnce");
+const teardownCallbacksSymbol = Symbol("teardownCallbacks");
 const visibilityStateSymbol = Symbol("visibilityState");
 let hostVisibilityStyleSheet = null;
 
@@ -358,7 +364,7 @@ class CustomElement extends HTMLElement {
 	 * @property {Function} templateFormatter.marker.open=null Specifies the opening marker for the templates.
 	 * @property {Function} templateFormatter.marker.close=null Specifies the closing marker for the templates.
 	 * @property {Boolean} templateFormatter.i18n=false Specifies whether the templates should be formatted with i18n.
-	 * @property {Boolean} eventProcessing=false Specifies whether the control processes events.
+	 * @property {Boolean} eventProcessing=false Specifies whether the control processes events. A bound input writes its value into the updater snapshot, not into the options. The synchronisation is one way, options to snapshot, so getOption() does not observe user input; read it with getInternalUpdateCloneData().
 	 * @property {Object} updater Specifies updater options.
 	 * @property {Boolean} updater.batchUpdates=false Batches updater content/attribute updates per diff.
 	 * @since 1.8.0
@@ -540,16 +546,9 @@ class CustomElement extends HTMLElement {
 	 * @since 1.10.0
 	 */
 	getOption(path, defaultValue = undefined) {
-		let value;
-
-		try {
-			value = new Pathfinder(
-				this[internalSymbol].getRealSubject()["options"],
-			).getVia(path);
-		} catch (e) {}
-
-		if (value === undefined) return defaultValue;
-		return value;
+		return new Pathfinder(
+			this[internalSymbol].getRealSubject()["options"],
+		).getVia(path, defaultValue);
 	}
 
 	/**
@@ -699,6 +698,7 @@ class CustomElement extends HTMLElement {
 	[assembleMethodSymbol]() {
 		let elements;
 		let nodeList;
+
 		// Extract options from attributes and set them
 		const AttributeOptions = getOptionsFromAttributes.call(this);
 		if (
@@ -734,7 +734,15 @@ class CustomElement extends HTMLElement {
 		// Initialize the custom elements inside the shadow root and the slotted elements
 		initFromCallbackHost.call(this);
 		try {
-			nodeList = new Set([...elements, ...getSlottedElements.call(this)]);
+			nodeList = new Set([
+				...elements,
+				...getSlottedElements.call(
+					this,
+					undefined,
+					undefined,
+					getManagedShadowRoot.call(this),
+				),
+			]);
 		} catch (e) {
 			nodeList = elements;
 		}
@@ -761,13 +769,40 @@ class CustomElement extends HTMLElement {
 		);
 		// Attach a mutation observer to observe changes to the attributes of the element
 		attachAttributeChangeMutationObserver.call(this);
+		attachChildMutationObserver.call(this);
 
 		if (isFunction(this[internalSymbol]?.syncDisabledState)) {
-			this[internalSymbol].syncDisabledState();
+			this[internalSymbol].syncDisabledState(true);
 		}
 
 		syncVisibilityState.call(this);
 
+		this[assembledOnceSymbol] = true;
+
+		return this;
+	}
+
+	/**
+	 * Registers a callback that runs when the element is disconnected.
+	 *
+	 * The registration is consumed by the first teardown, so a callback that is
+	 * needed again after a reconnect has to be registered again. A callback that
+	 * throws does not stop the remaining teardown; the error is reported through
+	 * the error attribute.
+	 *
+	 * @param {function} callback
+	 * @return {CustomElement}
+	 * @throws {TypeError} value is not a function
+	 * @since 4.154.0
+	 */
+	registerTeardown(callback) {
+		validateFunction(callback);
+
+		if (!isArray(this[teardownCallbacksSymbol])) {
+			this[teardownCallbacksSymbol] = [];
+		}
+
+		this[teardownCallbacksSymbol].push(callback);
 		return this;
 	}
 
@@ -775,7 +810,15 @@ class CustomElement extends HTMLElement {
 	 * You know what you are doing? This function is only for advanced users.
 	 * The result is a clone of the internal data.
 	 *
+	 * This snapshot is the object the updaters are bound to. It is the only
+	 * place where values typed into a `data-monster-bind` input end up when
+	 * `eventProcessing` is enabled, because the synchronisation runs one way
+	 * from the options into the snapshot and never back. A reconnect rebinds to
+	 * the same snapshot, so that state survives.
+	 *
 	 * @return {*}
+	 * @see Monster.DOM.CustomElement#getOption
+	 * @since 3.56.0
 	 */
 	getInternalUpdateCloneData() {
 		return clone(this[updateCloneDataSymbol]);
@@ -790,19 +833,31 @@ class CustomElement extends HTMLElement {
 	 * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/connectedCallback
 	 */
 	connectedCallback() {
-		// Check if the object has already been initialized
-		if (!hasObjectLink(this, customElementUpdaterLinkSymbol)) {
-			try {
-				initOptionsFromAttributes(
-					this,
-					this[internalSymbol].getSubject()?.["options"],
-				);
-			} catch (e) {
-				addErrorAttribute(this, e);
-			}
-			// If not, call the assembleMethod to initialize the object
-			this[assembleMethodSymbol]();
+		// Already bound, nothing to do. Moving a connected element inside its own
+		// parent fires disconnect and connect, so this runs often.
+		if (hasObjectLink(this, customElementUpdaterLinkSymbol)) {
+			return;
+		}
+
+		try {
+			initOptionsFromAttributes(
+				this,
+				this[internalSymbol].getSubject()?.["options"],
+			);
+		} catch (e) {
+			addErrorAttribute(this, e);
+		}
+
+		// The assemble method is a one shot: derived classes override it and
+		// rebuild their own state in there, for example state/log.mjs resets its
+		// entries array and its entry maps. After a disconnect the rendered DOM
+		// and that state are still intact, so a reconnect only relinks.
+		if (this[assembledOnceSymbol] === true) {
+			rebindAfterReconnect.call(this);
+			return;
 		}
+
+		this[assembleMethodSymbol]();
 	}
 
 	/**
@@ -811,7 +866,16 @@ class CustomElement extends HTMLElement {
 	 * @return {void}
 	 * @since 1.7.0
 	 */
-	disconnectedCallback() {}
+	disconnectedCallback() {
+		runTeardownCallbacks.call(this);
+		disposeLinkedUpdaters.call(this);
+		detachAttributeChangeMutationObserver.call(this);
+		detachChildMutationObserver.call(this);
+
+		if (isFunction(this[internalSymbol]?.disconnectDisabledObservers)) {
+			this[internalSymbol].disconnectDisabledObservers();
+		}
+	}
 
 	/**
 	 * The custom element has been moved into a new document (e.g. someone called document.adoptNode(el)).
@@ -967,6 +1031,168 @@ function initFromCallbackHost() {
 	callControlCallback.call(this, callBackFunctionName);
 }
 
+/**
+ * Relinks a previously assembled element after it was reconnected.
+ *
+ * Deliberately does not touch the shadow root, the rendered markup, the options
+ * snapshot or anything a derived assemble method built. It only recreates what
+ * the teardown released: the updaters and the observers.
+ *
+ * @private
+ * @this CustomElement
+ */
+function rebindAfterReconnect() {
+	let elements = getManagedShadowRoot.call(this)?.childNodes;
+	if (!(elements instanceof NodeList)) {
+		elements = this.childNodes;
+	}
+
+	let nodeList;
+	try {
+		nodeList = new Set([
+			...elements,
+			...getSlottedElements.call(
+				this,
+				undefined,
+				undefined,
+				getManagedShadowRoot.call(this),
+			),
+		]);
+	} catch {
+		nodeList = elements;
+	}
+
+	const cfg = {};
+	if (this.getOption("eventProcessing") === true) {
+		cfg.eventProcessing = true;
+	}
+	if (this.getOption("updater.batchUpdates") === true) {
+		cfg.batchUpdates = true;
+	}
+
+	// Binds to the same snapshot object on purpose: it carries the runtime state
+	// the updaters produced, including values written back by event processing,
+	// which the component options never receive.
+	addObjectWithUpdaterToElement.call(
+		this,
+		nodeList,
+		customElementUpdaterLinkSymbol,
+		this[updateCloneDataSymbol],
+		cfg,
+	);
+
+	attachAttributeChangeMutationObserver.call(this);
+	attachChildMutationObserver.call(this);
+
+	if (isFunction(this[internalSymbol]?.syncDisabledState)) {
+		this[internalSymbol].syncDisabledState(true);
+	}
+
+	syncVisibilityState.call(this);
+}
+
+/**
+ * @private
+ * @this CustomElement
+ */
+function runTeardownCallbacks() {
+	const callbacks = this[teardownCallbacksSymbol];
+	if (!isArray(callbacks) || callbacks.length === 0) {
+		return;
+	}
+
+	// taken first, so a callback that re-registers during teardown does not run
+	// in the same pass
+	this[teardownCallbacksSymbol] = [];
+
+	for (const callback of callbacks) {
+		try {
+			callback.call(this);
+		} catch (e) {
+			addErrorAttribute(this, e);
+		}
+	}
+}
+
+/**
+ * @private
+ * @this CustomElement
+ */
+function disposeLinkedUpdaters() {
+	if (!hasObjectLink(this, customElementUpdaterLinkSymbol)) {
+		return;
+	}
+
+	try {
+		for (const group of getLinkedObjects(
+			this,
+			customElementUpdaterLinkSymbol,
+		)) {
+			if (!(group instanceof Set)) {
+				continue;
+			}
+
+			for (const updater of group) {
+				if (typeof updater?.dispose !== "function") {
+					continue;
+				}
+
+				try {
+					updater.dispose();
+				} catch (e) {
+					addErrorAttribute(this, e);
+				}
+			}
+		}
+
+		removeObjectLink(this, customElementUpdaterLinkSymbol);
+	} catch (e) {
+		addErrorAttribute(this, e);
+	}
+}
+
+/**
+ * The symbol is deleted, not only disconnected: the attach guard treats a
+ * present symbol as an active observer and would otherwise never replace it.
+ *
+ * @private
+ * @this CustomElement
+ */
+function detachAttributeChangeMutationObserver() {
+	const observer = this[attributeMutationObserverSymbol];
+	if (observer) {
+		try {
+			observer.disconnect();
+		} catch (e) {
+			addErrorAttribute(this, e);
+		}
+	}
+
+	delete this[attributeMutationObserverSymbol];
+}
+
+/**
+ * @private
+ * @this CustomElement
+ */
+function detachChildMutationObserver() {
+	const observer = this[childMutationObserverSymbol];
+	if (observer) {
+		try {
+			observer.disconnect();
+		} catch (e) {
+			addErrorAttribute(this, e);
+		}
+	}
+
+	delete this[childMutationObserverSymbol];
+
+	if (this[childMutationTimerSymbol]) {
+		clearTimeout(this[childMutationTimerSymbol]);
+		this[childMutationTimerSymbol] = null;
+	}
+}
+
 /**
  * This method is called when the element is first created.
  *
@@ -1095,12 +1321,21 @@ function containChildNode(node) {
 		return true;
 	}
 
-	for (const [, e] of Object.entries(this.childNodes)) {
-		if (e.contains(node)) {
+	// Node.contains() already covers the whole light DOM subtree, so the only
+	// thing left to search is the shadow root of nested elements, which no
+	// contains() call can see.
+	for (const child of this.childNodes) {
+		const shadowRoot = child?.shadowRoot;
+		if (
+			shadowRoot instanceof ShadowRoot &&
+			containChildNode.call(shadowRoot, node)
+		) {
 			return true;
 		}
 
-		containChildNode.call(e, node);
+		if (child.childNodes?.length && containChildNode.call(child, node)) {
+			return true;
+		}
 	}
 
 	return false;
@@ -1133,7 +1368,12 @@ function initOptionObserver() {
 					targets.add(element);
 				}
 			}
-			for (const element of getSlottedElements.call(self, disabledQuery)) {
+			for (const element of getSlottedElements.call(
+				self,
+				disabledQuery,
+				undefined,
+				getManagedShadowRoot.call(self),
+			)) {
 				targets.add(element);
 			}
 		} catch (e) {}
@@ -1220,6 +1460,8 @@ function initOptionObserver() {
 	self.attachObserver(new Observer(syncDisabledState));
 
 	self[internalSymbol].syncDisabledState = syncDisabledState;
+	self[internalSymbol].disconnectDisabledObservers =
+		disconnectDisabledObservers;
 
 	let updaterSyncRevision = 0;
 	self.attachObserver(
@@ -1293,6 +1535,17 @@ function syncUpdaterSubject(target, source) {
 		return;
 	}
 
+	// Empty option objects are also used as refresh markers by editable
+	// datasource components. Keep their established merge behavior while
+	// allowing non-empty replacement objects to remove stale keys.
+	if (Object.keys(source).length > 0) {
+		for (const key of Object.keys(target)) {
+			if (!Object.hasOwn(source, key)) {
+				delete target[key];
+			}
+		}
+	}
+
 	for (const [key, value] of Object.entries(source)) {
 		syncUpdaterValue(target, key, value);
 	}
@@ -1679,6 +1932,15 @@ function initShadowRoot() {
 	let template;
 	let html;
 
+	// A rebind keeps the rendered shadow DOM. Calling attachShadow() again would
+	// throw, after which the main template used to be appended into the light
+	// DOM and a second updater set was bound to the same host.
+	const existing = getManagedShadowRoot.call(this);
+	if (existing instanceof ShadowRoot) {
+		this[managedShadowRootSymbol] = existing;
+		return this;
+	}
+
 	try {
 		template = findDocumentTemplate(this.constructor.getTag());
 	} catch (e) {

package/source/dom/slotted.mjs

@@ -27,37 +27,33 @@ export { getSlottedElements, getSlottedNodes };
  * @since 3.33.0
  * @throws {Error} query must be a string
  */
-function getSlottedNodes(query, name) {
+function getSlottedNodes(query, name, managedShadowRoot) {
 	const result = new Set();
+	const shadowRoot = getShadowRoot(this, managedShadowRoot);
 
-	if (!this.shadowRoot) {
+	if (!(shadowRoot instanceof ShadowRoot)) {
 		return result;
 	}
 
-	let selector = "slot";
-	if (name !== undefined) {
-		if (name === null) {
-			selector += ":not([name])";
-		} else {
-			selector += `[name=${validateString(name)}]`;
-		}
-	}
-
-	const slots = this.shadowRoot.querySelectorAll(selector);
+	const slots = getSlotsByName(shadowRoot, name);
 
-	for (const [, slot] of Object.entries(slots)) {
+	for (const slot of slots) {
 		slot.assignedNodes().forEach(function (node) {
 			if (node === null || node === undefined) {
 				return;
 			}
 
 			if (isString(query)) {
-				node.querySelectorAll(query).forEach(function (n) {
-					result.add(n);
-				});
-
-				if (node.matches(query)) {
+				if (query.length === 0) {
 					result.add(node);
+				} else if (node instanceof Element) {
+					node.querySelectorAll(query).forEach(function (n) {
+						result.add(n);
+					});
+
+					if (node.matches(query)) {
+						result.add(node);
+					}
 				}
 			} else if (query !== undefined) {
 				throw new Error("query must be a string");
@@ -80,25 +76,17 @@ function getSlottedNodes(query, name) {
  * @since 1.23.0
  * @throws {Error} query must be a string
  */
-function getSlottedElements(query, name) {
+function getSlottedElements(query, name, managedShadowRoot) {
 	const result = new Set();
+	const shadowRoot = getShadowRoot(this, managedShadowRoot);
 
-	if (!(this.shadowRoot instanceof ShadowRoot)) {
+	if (!(shadowRoot instanceof ShadowRoot)) {
 		return result;
 	}
 
-	let selector = "slot";
-	if (name !== undefined) {
-		if (name === null) {
-			selector += ":not([name])";
-		} else {
-			selector += `[name=${validateString(name)}]`;
-		}
-	}
-
-	const slots = this.shadowRoot.querySelectorAll(selector);
+	const slots = getSlotsByName(shadowRoot, name);
 
-	for (const [, slot] of Object.entries(slots)) {
+	for (const slot of slots) {
 		slot.assignedElements().forEach(function (node) {
 			if (
 				!(node instanceof HTMLElement) &&
@@ -129,3 +117,30 @@ function getSlottedElements(query, name) {
 
 	return result;
 }
+
+/**
+ * @param {*} host
+ * @param {*} managedShadowRoot
+ * @return {ShadowRoot|null}
+ * @private
+ */
+function getShadowRoot(host, managedShadowRoot) {
+	if (managedShadowRoot instanceof ShadowRoot) return managedShadowRoot;
+	return host?.shadowRoot instanceof ShadowRoot ? host.shadowRoot : null;
+}
+
+/**
+ * Filter slots by their DOM name instead of interpolating an unsafe selector.
+ * @param {ShadowRoot} shadowRoot
+ * @param {string|undefined|null} name
+ * @return {HTMLSlotElement[]}
+ * @private
+ */
+function getSlotsByName(shadowRoot, name) {
+	if (name !== undefined && name !== null) validateString(name);
+	return Array.from(shadowRoot.querySelectorAll("slot")).filter((slot) => {
+		if (name === undefined) return true;
+		if (name === null) return slot.name === "";
+		return slot.name === name;
+	});
+}

package/source/dom/template.mjs

@@ -156,7 +156,10 @@ export function findDocumentTemplate(id, currentNode) {
 		)
 	) {
 		if (currentNode instanceof Node) {
-			if (currentNode.hasAttribute(ATTRIBUTE_TEMPLATE_PREFIX)) {
+			if (
+				currentNode instanceof Element &&
+				currentNode.hasAttribute(ATTRIBUTE_TEMPLATE_PREFIX)
+			) {
 				prefixID = currentNode.getAttribute(ATTRIBUTE_TEMPLATE_PREFIX);
 			}