@schukai/monster 4.75.0 → 4.76.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 
 
+## [4.76.0] - 2026-01-05
+
+### Add Features
+
+- Add tab control feature for issue [#362](https://gitlab.schukai.com/oss/libraries/javascript/monster/issues/362)
+
+
+
 ## [4.75.0] - 2026-01-04
 
 ### Add Features

package/package.json

@@ -1 +1 @@
-{"author":"Volker Schukai","dependencies":{"@floating-ui/dom":"^1.7.4","@popperjs/core":"^2.11.8"},"description":"Monster is a simple library for creating fast, robust and lightweight websites.","homepage":"https://monsterjs.org/","keywords":["framework","web","dom","css","sass","mobile-first","app","front-end","templates","schukai","core","shopcloud","alvine","monster","buildmap","stack","observer","observable","uuid","node","nodelist","css-in-js","logger","log","theme"],"license":"AGPL 3.0","main":"source/monster.mjs","module":"source/monster.mjs","name":"@schukai/monster","repository":{"type":"git","url":"https://gitlab.schukai.com/oss/libraries/javascript/monster.git"},"type":"module","version":"4.75.0"}
+{"author":"Volker Schukai","dependencies":{"@floating-ui/dom":"^1.7.4","@popperjs/core":"^2.11.8"},"description":"Monster is a simple library for creating fast, robust and lightweight websites.","homepage":"https://monsterjs.org/","keywords":["framework","web","dom","css","sass","mobile-first","app","front-end","templates","schukai","core","shopcloud","alvine","monster","buildmap","stack","observer","observable","uuid","node","nodelist","css-in-js","logger","log","theme"],"license":"AGPL 3.0","main":"source/monster.mjs","module":"source/monster.mjs","name":"@schukai/monster","repository":{"type":"git","url":"https://gitlab.schukai.com/oss/libraries/javascript/monster.git"},"type":"module","version":"4.76.0"}

package/source/dom/util.mjs

@@ -23,6 +23,7 @@ export {
 	getContainingDocument,
 	getRegisteredCustomElements,
 	findElementWithSelectorUpwards,
+	waitForCustomElement,
 };
 
 /**
@@ -323,3 +324,72 @@ function getRegisteredCustomElements() {
 
 	return Array.from(new Set(customElementTags));
 }
+
+/**
+ * Waits until a specific custom element instance is defined and upgraded.
+ *
+ * @param {HTMLElement} element
+ * @param {Object} [options]
+ * @param {string} [options.method] - Optional method to wait for on the instance.
+ * @param {string} [options.tagName] - Optional tag name override.
+ * @param {number|null} [options.timeout=2000] - Timeout in ms; set null to disable.
+ * @return {Promise<HTMLElement>}
+ * @since 4.1.0
+ */
+function waitForCustomElement(
+	element,
+	{ method = null, tagName = null, timeout = 2000 } = {},
+) {
+	if (!(element instanceof HTMLElement)) {
+		return Promise.reject(
+			new Error("Invalid argument. Expected an HTMLElement."),
+		);
+	}
+
+	const name = (tagName || element.tagName || "").toLowerCase();
+	if (!name.includes("-")) {
+		return Promise.reject(
+			new Error("Invalid argument. Expected a custom element tag name."),
+		);
+	}
+
+	const window = getWindow();
+	const registry = window.customElements;
+	if (!registry) {
+		return Promise.reject(new Error("customElements is not supported."));
+	}
+
+	return registry.whenDefined(name).then(
+		() =>
+			new Promise((resolve, reject) => {
+				if (typeof registry.upgrade === "function") {
+					registry.upgrade(element);
+				}
+
+				const start = Date.now();
+				const check = () => {
+					if (!method || typeof element[method] === "function") {
+						resolve(element);
+						return;
+					}
+
+					if (
+						typeof timeout === "number" &&
+						timeout >= 0 &&
+						Date.now() - start > timeout
+					) {
+						reject(
+							new Error(
+								`Timed out waiting for "${method}" on <${name}>.`,
+							),
+						);
+						return;
+					}
+
+					window.requestAnimationFrame(check);
+				};
+
+				window.requestAnimationFrame(check);
+			}),
+	);
+}

package/test/cases/dom/util.mjs

@@ -1,5 +1,8 @@
 import {
-    getDocument, getWindow, getDocumentFragmentFromString
+    getDocument,
+    getWindow,
+    getDocumentFragmentFromString,
+    waitForCustomElement,
 } from "../../../source/dom/util.mjs";
 
 import {getContainingDocument} from "../../../source/dom/util.mjs";
@@ -111,5 +114,27 @@ describe('DOM', function () {
             expect(containingDocument).to.be.null;
         });
     });    
+
+    describe('waitForCustomElement()', () => {
+        it('should resolve for a specific instance once defined', async () => {
+            const tagName = `test-tabs-${Date.now()}`;
+            const element = document.createElement(tagName);
+            document.body.appendChild(element);
+
+            const promise = waitForCustomElement(element, { method: 'ping' });
+
+            class TestTabs extends HTMLElement {
+                ping() {
+                    return 'pong';
+                }
+            }
+
+            customElements.define(tagName, TestTabs);
+
+            const ready = await promise;
+            expect(ready).to.equal(element);
+            expect(ready.ping()).to.equal('pong');
+        });
+    });
     
-});
+});