@twobirds/microcomponents 0.10.3 → 0.12.1

package/dist/utils/helpers.js

@@ -0,0 +1,693 @@
+//#region src/utils/events.ts
+/**
+@module Events
+
+This module provides event utilities for interfacing **between microcomponents and external
+frameworks or native DOM/JS environments**. It is not intended for communication between
+frontend microcomponents themselves — for that purpose, use the inherited methods
+( `.on()`, `.one()`, `.off()`, `.trigger()`) that exist when you extend `DC`.
+
+Import this module when you need to exchange information with microcomponents from outside
+the microcomponent system (e.g., vanilla JS, React via `useRef()`, or other frameworks).
+
+The core feature is the ability to explicitly control event flow direction when using {@link trigger}:
+- upward propagation to ancestor components ('u')
+- local dispatch only ('l') [default]
+- downward propagation to descendant components ('d').
+
+@example
+html:
+```html
+<div class="grandparent">
+<div class="parent">
+<div class="child">
+</div>
+</div>
+</div>
+```
+
+javascript:
+```javascript
+import { on, one, trigger, off } from '@twobirds/microcomponents/events';
+
+const grandParent = document.querySelector('.grandparent');
+const parent = document.querySelector('.parent');
+const child = document.querySelector('.child');
+if (!grandParent || !parent || !child) throw new Error('example markup missing');
+
+const grandParentHandler = on(grandParent, 'dataReady', (ev) => console.log(ev.detail.data));
+
+const parentHandler = on(parent, 'dataReady', (ev) => ev.detail.control.stop());
+
+trigger(child, 'dataReady', { value: 42 }, 'u');
+
+off(parent, 'dataReady', parentHandler);
+off(grandParent, 'dataReady', grandParentHandler);
+```
+
+The `dataReady` event bubbles upward from the innermost `div`, but `parentHandler`
+calls `ev.detail.control.stop()`, so the `grandParent` handler is never reached.
+Handlers are detached with `off()` once they are no longer needed.
+*/
+/**
+* Returns the correct event name to listen for on a DOM element.
+*
+* If `eventName` (case-insensitive) matches a native HTML event handler property
+* (`'on' + eventName.toLowerCase()`) on the target, returns the lowercase native
+* name so that standard DOM events like `'click'` are listened to correctly.
+* Otherwise, prefixes with `_mc` for microcomponent custom events.
+*
+* @hidden
+* @param target - The DOM element whose native event support is checked.
+* @param eventName - The event name as provided by the caller (e.g., `'click'`, `'Update'`).
+* @returns The resolved event name: lowercase native or `_mc`-prefixed custom.
+*
+* @example
+* ```ts
+* const btn = document.createElement('button');
+* console.log(trueEventName(btn, 'Click'));
+* console.log(trueEventName(btn, 'Update'));
+* ```
+*
+* `'Click'` resolves to the native `'click'` because the button has an `onclick` handler
+* property; `'Update'` has no native counterpart, so it becomes the `_mc`-prefixed custom
+* event name.
+*/
+function trueEventName(target, eventName) {
+	const lower = eventName.toLowerCase();
+	if ("on" + lower in target) return lower;
+	return "_mc" + eventName[0].toUpperCase() + eventName.substring(1);
+}
+/**
+Attaches a persistent event listener that will fire every time the specified event occurs.
+
+This is primarily used to interface with external frameworks or vanilla JS environments.
+For communication between frontend microcomponents, use the `DC.on()` method instead.
+
+The handler receives a `CustomEvent<McDetail<D>>`: the payload sits under
+`ev.detail.data`, the bubble-control handle under `ev.detail.control`.
+
+@param target - The DOM element to attach the listener to.
+@param eventName - The name of the event (e.g., 'click', 'update').
+@param handler - The callback function or object to invoke on each event.
+@param once - If true, remove the listener after first invocation.
+@returns The attached handler reference. Useful for later deletion with {@link off}.
+
+@example
+```ts
+const handler = on<{ value: number }>(myElement, 'update', (ev) => {
+console.log(ev.detail.data.value);
+});
+off(myElement, 'update', handler);
+```
+@group Events
+*/
+function on(target, eventName, handler, once = false) {
+	/* v8 ignore next */
+	if (!target) return;
+	if (typeof target === "string") {
+		document.querySelectorAll(target).forEach((el) => on(el, eventName, handler));
+		return;
+	}
+	target.addEventListener(trueEventName(target, eventName), handler, {
+		capture: false,
+		once
+	});
+	return handler;
+}
+/**
+* @hidden
+* A controller object used to manage and potentially abort event bubbling.
+*
+* The `trigger()` function internally creates instance of this class,
+* allowing the an eventual handler to call `ev.detail.control.stop()` to
+* prevent further propagation in either direction (up/down).
+*
+* This is only used internally.
+* @example
+* ```ts
+* trigger(myElement, 'update', { value: 42 }, 'u');
+*
+* onUpdate(ev) {
+*     ev.detail.control.stop();
+* }
+* ```
+*/
+var BubbleController = class {
+	stopped = false;
+	constructor() {}
+	/**
+	* Signals that event bubbling should be halted.
+	*
+	* After calling this method, subsequent `trigger()` calls will abort
+	* before dispatching the event to any targets.
+	*
+	* @example
+	* ```ts
+	* trigger(myElement, 'update', { value: 42 }, 'u');
+	*
+	* onUpdate(ev) {
+	*     ev.detail.control.stop();
+	* }
+	* ```
+	*/
+	stop() {
+		this.stopped = true;
+	}
+};
+/**
+* Creates and dispatches a custom event on the specified DOM node.
+*
+* The event is namespaced with an `_mc` prefix by default, unless already prefixed.
+* Supports bidirectional bubbling (up/down the DOM tree) based on the `bubble` parameter:
+* - 'l': local dispatch only
+* - 'u': bubble up towards ancestors
+* - 'd': bubble down to descendants
+*
+* The dispatched event is a `CustomEvent<McDetail<D>>`: handlers find the payload
+* under `ev.detail.data` and can call `ev.detail.control.stop()` to cancel bubbling.
+*
+* Prefer a direct target over bubbling: name the receiving element in `target` and keep the
+* default `'l'`, so one `querySelectorAll` reaches it in a single step. Reserve `'u'`/`'d'`
+* for receivers that cannot be named in advance, since they walk the tree and re-dispatch the
+* event at every level. Pass a typed object as `data` rather than a bare string, so the
+* handler reads named fields from `ev.detail.data` and the flow stays readable as it grows.
+*
+* @param target - The DOM element on which to trigger the event, or a querySelectorAll(selector) selector string.
+* @param event - The name of the event (will be prefixed if needed).
+* @param data - Additional data payload attached to `event.detail.data`.
+* @param bubble - Bubbling direction ('l', 'u', 'd' or combinations).
+* @param controller - Optional controller for managing bubbling behavior.
+*
+* @example
+* ```ts
+* trigger(myElement, 'update', { value: 42 }, 'l');
+* trigger(myElement, 'dataReady', { ready: true }, 'u');
+* ```
+*
+* The first dispatch fires locally only; the second bubbles upward to ancestor components.
+*/
+function trigger(target, event, data = {}, bubble = "l", controller) {
+	/* v8 ignore next */
+	if (!target) return;
+	if (typeof target === "string") {
+		document.querySelectorAll(target).forEach((el) => trigger(el, event, data, bubble));
+		return;
+	}
+	const eventName = /^_mc/.test(event) ? event : trueEventName(target, event), bubbleController = controller ? controller : new BubbleController(), ev = new CustomEvent(eventName, {
+		detail: {
+			data,
+			control: bubbleController
+		},
+		bubbles: false
+	});
+	if (bubbleController.stopped) return;
+	if (/l/.test(bubble)) {
+		target.dispatchEvent(ev);
+		if (bubbleController.stopped) return;
+	}
+	if (/[ud]/.test(bubble)) queueMicrotask(() => {
+		if (bubble.indexOf("u") > -1) trigger(target.parentElement, eventName, data, "lu", bubbleController);
+		if (bubble.indexOf("d") > -1) for (const child of target.children) trigger(child, eventName, data, "ld");
+	});
+}
+//#endregion
+//#region src/utils/helpers.ts
+/**
+* Determines whether the current runtime environment is a web browser.
+*
+* This function works by attempting to access `this` within an anonymous function
+* and checking if it refers to the global `window` object. It returns `true`
+* when executed in a browser context, and `false` otherwise (e.g., Node.js).
+*
+* Note: While modern environments typically provide more reliable detection mechanisms,
+* this fallback remains compatible across older runtimes where other detection techniques
+* may be unreliable.
+*
+* @returns `true` if the code is running in a browser environment, `false` otherwise.
+*
+* @example
+* ```ts
+* if (isBrowser()) {
+*   console.log('Running in a browser');
+* }
+* ```
+*/
+function isBrowser() {
+	return typeof window !== "undefined" && typeof window.document !== "undefined";
+}
+/**
+* Checks if a value is a native JavaScript object (created via {} or new Object()).
+* @param value - The value to check.
+* @returns True if the value is a plain object, false otherwise.
+*
+* @example
+* ```ts
+* console.log(isNativeObject({}));
+* console.log(isNativeObject(new Object()));
+* console.log(isNativeObject([]));
+* console.log(isNativeObject(null));
+* ```
+*/
+function isNativeObject(value) {
+	return typeof value === "object" && value !== null && value.constructor === Object;
+}
+/**
+* Recursively sorts all keys in an object alphabetically, preserving nested structure.
+* @param source - The object to sort.
+* @returns A new object with sorted keys at all levels.
+*
+* @example
+* ```ts
+* const obj = { z: 1, a: { y: 2, b: 3 } };
+* console.log(JSON.stringify(sortObject(obj)));
+* ```
+*/
+function sortObject(source) {
+	const result = {}, keys = Object.keys(source).sort();
+	for (let i = 0; i < keys.length; i++) {
+		const key = keys[i], value = source[key];
+		if (isNativeObject(value)) result[key] = sortObject(value);
+		else result[key] = value;
+	}
+	return result;
+}
+/**
+* Flattens a nested object into a single-level object with dot-separated keys.
+* Optionally sorts the resulting flat keys alphabetically (default: true).
+* @param source - The object to flatten.
+* @param doSort - Whether to sort the resulting keys (default: true).
+* @returns A flattened object with dot-notation keys.
+*
+* @example
+* ```ts
+* const obj = { user: { name: 'Alice', age: 30 } };
+* console.log(JSON.stringify(flattenObject(obj)));
+* ```
+*/
+function flattenObject(source, doSort = true) {
+	const result = {};
+	const record = source;
+	const names = Object.getOwnPropertyNames(source);
+	for (let i = 0; i < names.length; i++) {
+		const propName = names[i], value = record[propName];
+		if (value instanceof Object) {
+			const temp = flattenObject(value, false);
+			for (const j in temp) result[propName + "." + j] = temp[j];
+		} else result[propName] = value;
+	}
+	return doSort ? sortObject(result) : result;
+}
+/**
+* Structural deep-equality using SameValueZero for primitives.
+*
+* See {@link https://tc39.es/ecma262/multipage/abstract-operations.html#sec-samevaluezero}.
+*
+* Note: `Map`/`Set` are not structurally compared.
+*
+* @param a - The first value to compare.
+* @param b - The second value to compare.
+* @returns True if the values are deeply equal, false otherwise.
+*
+* @example
+* ```ts
+* console.log(deepEqual({ a: 1 }, { a: 1 }));
+* console.log(deepEqual({ a: { b: 2 } }, { a: {} }));
+* console.log(deepEqual({ a: NaN }, { a: NaN }));
+* console.log(deepEqual({ a: NaN }, { a: null }));
+* ```
+*/
+function deepEqual(a, b) {
+	if (a === b || a !== a && b !== b) return true;
+	/* v8 ignore start */
+	if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
+	if (a.constructor !== b.constructor) return false;
+	if (a instanceof Date) return a.getTime() === b.getTime();
+	if (a instanceof RegExp) return a.toString() === b.toString();
+	/* v8 ignore end */
+	if (Array.isArray(a)) {
+		const bArr = b;
+		/* v8 ignore next */
+		if (a.length !== bArr.length) return false;
+		for (let i = 0; i < a.length; i++) if (!deepEqual(a[i], bArr[i])) return false;
+		return true;
+	}
+	const aObj = a, bObj = b, keys = Object.keys(aObj);
+	if (keys.length !== Object.keys(bObj).length) return false;
+	for (let i = 0; i < keys.length; i++) {
+		const key = keys[i];
+		if (!Object.prototype.hasOwnProperty.call(bObj, key) || !deepEqual(aObj[key], bObj[key])) return false;
+	}
+	return true;
+}
+/**
+* Retrieves a nested value from an object using a namespace path (dot-separated).
+* A present falsy leaf (`0`, `''`, `false`, `null`) is a real value and is returned;
+* only an absent key yields `undefined`.
+* @param ns - The namespace string or array of keys representing the path.
+* @param obj - The object to traverse.
+* @returns The value at the specified namespace path, or undefined if not found.
+*
+* @example
+* ```ts
+* const data = { user: { profile: { name: 'Alice' } } };
+* console.log(nameSpace('user.profile.name', data));
+* console.log(nameSpace(['user', 'profile'], data));
+* console.log(nameSpace('count', { count: 0 })); // 0, not undefined
+* ```
+*/
+function nameSpace(ns, obj = {}) {
+	const source = obj;
+	const nsa = typeof ns === "string" ? ns.split(".") : ns;
+	if (!source || !nsa[0]) return void 0;
+	if (!(nsa[0] in source)) return void 0;
+	const head = source[nsa[0]];
+	if (nsa.length > 1) {
+		if (isNativeObject(head)) return nameSpace(nsa.slice(1), head);
+		return;
+	}
+	return head;
+}
+/**
+* Parses a template string or object, replacing placeholders in the form of {key.path} with
+* corresponding values from the provided data object using namespace resolution.
+* Also recursively processes objects and arrays within the input.
+* @param template - The string or object to parse (can contain {{placeholder}} expressions).
+* @param parseThis - The object containing values for placeholder substitution.
+* @returns The parsed result, with placeholders replaced by actual values.
+*
+* @example
+* ```ts
+* const data = { user: { name: 'Alice' } };
+* console.log(parse('Hello {user.name}!', data));
+* console.log(parse(['Hi {user.name}', 'Bye {user.name}'], data));
+* ```
+*/
+function parse(template, parseThis, ...rest) {
+	const args = [
+		template,
+		parseThis,
+		...rest
+	];
+	if (args.length > 2) {
+		while (args.length > 1) {
+			args[0] = parse(args[0], args[1]);
+			args.splice(1, 1);
+		}
+		return args[0];
+	}
+	if (typeof template === "string") {
+		let result = template;
+		template.match(/\{[^\{\}]*\}/g)?.forEach((pPropname) => {
+			const value = nameSpace(pPropname.substring(1, pPropname.length - 1), parseThis);
+			if (typeof value !== "undefined") result = result.replace(pPropname, String(value));
+		});
+		return result;
+	} else if (Array.isArray(template)) return template.map((item) => parse(item, parseThis));
+	else if (isNativeObject(template)) {
+		const record = template;
+		Object.keys(record).forEach((pKey) => {
+			/* v8 ignore next */
+			if (Object.prototype.hasOwnProperty.call(record, pKey)) record[pKey] = parse(record[pKey], parseThis);
+		});
+	}
+	return template;
+}
+/**
+* Converts a kebab-case string to PascalCase.
+* Example: 'my-component-name' -> 'MyComponentName'
+* @param str - The kebab-case string to convert.
+* @returns The converted PascalCase string.
+*
+* @example
+* ```ts
+* console.log(kebabToPascal('my-element'));
+* ```
+*/
+function kebabToPascal(str) {
+	return str.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+/**
+* Converts a PascalCase string to kebab-case.
+* Example: 'MyComponentName' -> 'my-component-name'
+* @param str - The PascalCase string to convert.
+* @returns The converted kebab-case string.
+*
+* @example
+* ```ts
+* console.log(pascalToKebab('MyElement'));
+* ```
+*/
+function pascalToKebab(str) {
+	return str.replace(/[A-Z]/g, (m, i) => (i ? "-" : "") + m.toLowerCase());
+}
+/**
+* Creates a debounced version of a function that delays execution until after the specified
+* number of milliseconds have elapsed since the last time this function was invoked.
+* Useful for rate-limiting expensive operations like event handlers or API calls.
+* @param func - The function to debounce.
+* @param milliseconds - The number of milliseconds to delay execution.
+* @returns A debounced version of the input function.
+*
+* @example
+* ```ts
+* const log = debounce(() => console.log('called'), 300);
+* log();
+* log();
+* ```
+*/
+function debounce(func, milliseconds) {
+	let timeout;
+	return (...args) => {
+		clearTimeout(timeout);
+		timeout = setTimeout(() => {
+			func(...args);
+		}, milliseconds);
+	};
+}
+/**
+* Parses an HTML string and returns an array of DOM elements.
+* Handles self-closing tags (XHTML style) by converting them to full closing tags first.
+* @hidden
+* @param html - The HTML string to parse.
+* @returns An array of HTMLElement objects representing the parsed HTML nodes.
+*
+* @example
+* ```ts
+* const elems = htmlToElements('<div>Hello</div><span>World</span>');
+* console.log(elems.map((el) => el.tagName));
+* ```
+*/
+function htmlToElements(html) {
+	const template = document.createElement("template");
+	html = html.replace(/<([A-Za-z0-9\-]*)([^>\/]*)(\/>)/gi, "<$1$2></$1>");
+	template.innerHTML = html;
+	template.content.normalize();
+	return Array.from(template.content.childNodes);
+}
+/**
+* Copies all getter and setter properties from a source object to a target object.
+* Does not copy methods or regular data properties—only accessor properties (get/set).
+* @hidden
+* @param source - The source object with getters and/or setters to copy.
+* @param target - The target object to which the accessors will be copied.
+*
+* @example
+* ```ts
+* const src = { get name() { return 'Alice'; } };
+* const tgt = {};
+* copyGettersSetters(src, tgt);
+* console.log(tgt.name);
+* ```
+*/
+function copyGettersSetters(source, target) {
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	for (const [key, descriptor] of Object.entries(descriptors)) if ("get" in descriptor || "set" in descriptor) Object.defineProperty(target, key, descriptor);
+}
+/**
+* Injects a CSS string into the given scope (document or shadow root) as an adopted stylesheet.
+* Enables css-in-js so that every custom element is self-contained and importable.
+*
+* @hidden
+* @param target - The scope to inject styles into: `document` for global styles, or a `ShadowRoot` for encapsulated component internals.
+* @param css - The CSS string to inject.
+* @returns The created `CSSStyleSheet` instance that was adopted into the target scope.
+*
+* When targeting **document**: selectors like `:host`, `::slotted()`, and shadow-internal classes are **not allowed** — they have no effect outside a shadow root. Use only global selectors, element tags, or layout presets.
+* When targeting **shadowRoot**: use `:host` for the custom element itself, standard selectors (`.inner`, `#id`) for internal structure, and `::slotted()` for projected light-DOM content.
+*
+* @example Inject global styles into the document:
+* ```ts
+* import { injectCSS } from '@twobirds/mc/utils/helpers';
+* injectCSS(document, 'body { display: block; }');
+* ```
+*
+* @example Inject global styles for a micro component into the document:
+* ```ts
+* import { injectCSS } from '@twobirds/mc/utils/helpers';
+* injectCSS(document, 'my-microcomponent { display: block; }');
+* ```
+*
+* @example Inject scoped styles into a shadow root:
+* ```ts
+* const shadow = element.attachShadow({ mode: 'open' });
+* injectCSS(shadow, ':host { color: var(--text); } .inner { padding: 8px; }');
+* ```
+* Styles can also be added using a compound innerHTML statement: `shadow.innerHTML = \`<style>${style}</style>${template}\``
+*/
+var _injectedCSS = /* @__PURE__ */ new WeakMap();
+function injectCSS(target, css) {
+	const injected = _injectedCSS.get(target) ?? /* @__PURE__ */ new Set();
+	if (injected.has(css)) return target.adoptedStyleSheets[0];
+	injected.add(css);
+	_injectedCSS.set(target, injected);
+	const sheet = new CSSStyleSheet();
+	sheet.replaceSync(css);
+	target.adoptedStyleSheets.push(sheet);
+	return sheet;
+}
+/**
+* Processes a record of asset strings and applies them to the given target element.
+* Supports injecting CSS into document or shadow root, and setting innerHTML for
+* both target and shadow DOM. Automatically attaches a shadow root if any key starts
+* with `'shadow'`.
+*
+* Recognized keys: `'css'`, `'targetCss'` (document-level styles), `'shadowCss'`
+* (shadow-root styles), `'shadowHtml'` (shadow innerHTML), `'targetHtml'` (target innerHTML).
+*
+* @param instance - The micro component to apply assets onto.
+* @param assets - A record mapping asset type keys to their string content.
+*
+* @example
+* ```ts
+* processAssets(this, {
+*   css: 'body { margin: 0; }',
+*   shadowCss: ':host { display: block; }',
+*   shadowHtml: '<slot></slot>'
+* });
+* ```
+*/
+function processAssets(instance, assets) {
+	const target = instance.target;
+	let shadow = target.shadowRoot;
+	if (!shadow && Object.keys(assets).some((key) => key.indexOf("shadow") === 0)) shadow = target.attachShadow({ mode: "open" });
+	Object.keys(assets).forEach((key) => {
+		switch (key) {
+			case "css":
+				injectCSS(document, assets[key]);
+				break;
+			case "targetCss":
+				injectCSS(document, assets[key]);
+				break;
+			case "shadowCss":
+				injectCSS(shadow, assets[key]);
+				break;
+			case "shadowHtml":
+				shadow.innerHTML = assets[key];
+				bindTemplateEvents(shadow, instance);
+				break;
+			case "targetHtml":
+				target.innerHTML = assets[key];
+				bindTemplateEvents(target, instance);
+				break;
+		}
+	});
+}
+/**
+* Loads companion asset files (CSS, HTML) for a given component basename from the server.
+*
+* Each entry in `assets` encodes an optional variant and extension in camelCase, e.g. `'shadowCss'` → `{name}.shadow.css`,
+* `'targetHtml'` → `{name}.target.html`. Plain entries like `'css'` or `'html'` resolve to
+* `{name}.css` / `{name}.html`.
+*
+* In bundled mode the Vite plugin replaces this call with an inline array literal, so `.then()`
+* fires synchronously — no async overhead.
+*
+* @hidden
+* @param name - The component basename (e.g. `'shop-catalog'`).
+* @param assets - Array of asset descriptors such as `'shadowCss'`, `'targetHtml'`, `'shadowHtml'`, `'css'`, `'html'`.
+* @returns A promise resolving to an array of file contents in the same order as `assets`. If a file is not found, the corresponding entry is `'file not found: ' + filename`.
+*
+* @example
+* ```ts
+* export const MyComponent = loadAssets('my-component', ['shadowCss', 'shadowHtml']).then(([shadowCss, shadowHtml]) => {
+*   class _MyComponent extends DC { ... }
+*   defineCE('my-component', _MyComponent);
+*   return _MyComponent;
+* });
+* ```
+*/
+function loadAssets(name, assets) {
+	const parseAsset = (asset) => {
+		const m = asset.match(/^([a-z]+)([A-Z][a-z]*)$/);
+		if (m) return `./${name.replace(/-/g, "/")}.${m[1]}.${m[2].toLowerCase()}`;
+		return `./${name.replace(/-/g, "/")}.${asset.toLowerCase()}`;
+	};
+	return Promise.all(assets.map(async (asset) => {
+		const filename = parseAsset(asset);
+		try {
+			const resp = await fetch(filename);
+			if (!resp.ok) return `file not found: ${filename}`;
+			if (filename.endsWith("json")) {
+				const text = await resp.text();
+				try {
+					return JSON.parse(text);
+				} catch {
+					console.error(`could not JSON.parse() asset '${asset}' from ${filename}:\n`, text);
+					return null;
+				}
+			}
+			return resp.text();
+		} catch {
+			return `file not found: ${filename}`;
+		}
+	}));
+}
+/**
+* Binds declarative event attributes in a template fragment to microcomponent triggers.
+*
+* Scans all elements under `root` for attributes whose names correspond to native DOM
+* events (e.g. `click`, `submit`, `change`). The attribute value encodes the target and
+* handler method in the form `target|methodName`:
+*
+* - `this|myHandler` — triggers locally on the component attached to this element.
+* - `other-comp|submit` — resolves elements via `querySelectorAll('other-comp')` and
+*   triggers the event on each matched host's `_mc`.
+*
+* An optional sibling `payload` attribute supplies the data argument for `trigger()`.
+* After binding, both the event attribute and the payload attribute are removed from the DOM.
+*
+* @param rootElement - The container element whose descendants should be scanned for bindings.
+* @param instance - The instance to trigger events on.
+*
+* @example
+* ```html
+* <button click='this|onSubmit|{"action":"go"}'>Submit</button>
+* <input change="|cart-form|refresh">
+* ```
+*/
+function bindTemplateEvents(rootElement, instance) {
+	const allElements = [...rootElement.querySelectorAll("*")];
+	for (const el of allElements) {
+		if (!(el instanceof HTMLElement)) continue;
+		const attrs = [...el.attributes];
+		for (const attr of attrs) {
+			const lowerName = attr.name.toLowerCase();
+			if (!("on" + lowerName in el)) continue;
+			const parts = attr.value.trim().split("|");
+			if (parts.length < 2) continue;
+			const [selector, event, payload] = parts;
+			el.removeAttribute(attr.name);
+			let payloadData;
+			if (payload) try {
+				payloadData = JSON.parse(payload);
+			} catch {
+				payloadData = payload;
+			}
+			if (selector === "this" || selector === "") on(el, lowerName, () => instance.trigger(event, payloadData));
+			else on(el, lowerName, () => trigger(selector, event, payloadData));
+		}
+	}
+}
+//#endregion
+export { bindTemplateEvents, copyGettersSetters, debounce, deepEqual, flattenObject, htmlToElements, injectCSS, isBrowser, isNativeObject, kebabToPascal, loadAssets, nameSpace, parse, pascalToKebab, processAssets, sortObject };

package/dist/utils/index.d.ts

@@ -13,5 +13,5 @@ export { autoload } from './autoload.js';
 /** @hidden */
 export type { Autoload } from './autoload.js';
 /** @group Helpers */
-export { isBrowser, isNativeObject, sortObject, flattenObject, deepEqual, nameSpace, parse, kebabToPascal, debounce, htmlToElements, copyGettersSetters, injectCSS, processAssets, loadAssets, bindTemplateEvents, } from './helpers.js';
+export { isBrowser, isNativeObject, sortObject, flattenObject, deepEqual, nameSpace, parse, kebabToPascal, pascalToKebab, debounce, htmlToElements, copyGettersSetters, injectCSS, processAssets, loadAssets, bindTemplateEvents, } from './helpers.js';
 //# sourceMappingURL=index.d.ts.map