@twobirds/microcomponents 0.1.20 → 0.1.21

package/dist/MC.ts

@@ -1,10 +1,41 @@
 'use strict';
 
 import { LooseObject } from './helpers.js';
+import { trigger, on, one, off, BubbleController } from './events.js';
 
+/**
+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 {boolean} `true` if the code is running in a browser environment, `false` otherwise.
+*/
 const isBrowser = new Function('try {return this===window;}catch(e){ return false;}');
 
+/**
+Represents a DOM element that has been enhanced with microcomponent functionality.
+
+@template HTMLElement - The base HTML element type
+*/
 export interface HTMLMcElement extends HTMLElement {
+	/**
+	Hash object containing inner microcomponents, keyed by their unique identifiers (strings).
+	Each value is a reference to the corresponding `MicroComponent` instance or its configuration,
+	depending on the implementation.
+	
+	This property allows direct access to nested microcomponents for programmatic interaction
+	(e.g., invoking methods or accessing state), and supports internal lifecycle management
+	such as mounting/unmounting or updating.
+	
+	@type {LooseObject<MicroComponent>}
+	@readonly
+	*/
 	_mc: LooseObject;
 }
 
@@ -12,7 +43,18 @@ function isDOM(element: { [key: string]: any }) {
 	return element && element instanceof HTMLElement;
 }
 
-// add a microcomponent to a target DOM node
+/**
+Adds a microcomponent instance to a target DOM node under the specified key.
+
+This function initializes or updates the internal `_mc` collection on the target element,
+which stores references to child microcomponents. It also adds the `data-mc` attribute
+if missing, indicating that this DOM node hosts at least one microcomponent.
+
+@param {HTMLElement} target - The DOM element to attach the microcomponent to.
+@param {string} key - The property name/key under which the element will be stored in `_mc`.
+@param {any} [element={}] - The microcomponent instance or configuration object to attach.
+@returns {HTMLMcElement} The target DOM node, now enhanced with the attached microcomponent.
+*/
 function add(target: HTMLElement, key: string, element: any = {}): HTMLMcElement {
 	let node = target as HTMLMcElement;
 
@@ -37,7 +79,15 @@ function add(target: HTMLElement, key: string, element: any = {}): HTMLMcElement
 	return node;
 }
 
-// remove a micro component from the DOM
+/**
+Removes a named microcomponent from the internal `_mc` collection of a target DOM node.
+
+This function deletes the specified key from the element's `_mc` hash object and, if the
+collection becomes empty, removes the `data-mc` attribute from the DOM node.
+
+@param {HTMLElement} target - The DOM element whose microcomponent should be removed.
+@param {string} key - The property name/key corresponding to the microcomponent to remove.
+*/
 function remove(target: HTMLElement, key: string) {
 	if (!key) return; // silent fail
 
@@ -55,7 +105,15 @@ function remove(target: HTMLElement, key: string) {
 	return;
 }
 
-// run the "init" lifecycle event on the complete _mc structure
+/**
+Runs the "Init" lifecycle event on a microcomponent instance asynchronously.
+
+This function schedules the `trigger('Init')` call within a zero-delay timeout,
+ensuring that all synchronous initialization is complete before the lifecycle
+hook executes. It skips execution for the base `DC` class itself.
+
+@param {DC} element - The microcomponent instance on which to trigger the Init event.
+*/
 function init(element: DC) {
 	//console.warn('init(): args', ...arguments);
 	setTimeout(() => {
@@ -64,99 +122,15 @@ function init(element: DC) {
 	}, 0);
 }
 
-// 'eventName' => '_mcEventName'
-function getMcEventName(eventName: string): string {
-	return '_mc' + eventName[0].toUpperCase() + eventName.substring(1);
-}
-
-/*
-CustomEvent Section...
-*/
-function off(domNode: Node, eventName: string, handler: EventListenerOrEventListenerObject) {
-	domNode.removeEventListener(getMcEventName(eventName), handler);
-}
-
-function on(
-	domNode: Node,
-	eventName: string,
-	handler: EventListenerOrEventListenerObject,
-	once: boolean = false
-): EventListenerOrEventListenerObject {
-	domNode.addEventListener(getMcEventName(eventName), handler, { capture: false, once });
-	return handler;
-}
-
-function one(
-	domNode: Node,
-	eventName: string,
-	handler: EventListenerOrEventListenerObject
-): EventListenerOrEventListenerObject {
-	on(domNode, eventName, handler, true);
-	return handler;
-}
-
-class BubbleController {
-	stopped = false;
-	constructor() {}
-	stop() {
-		this.stopped = true;
-	}
-}
-
-// create and dispatch custom event
-function trigger(
-	domNode: HTMLElement,
-	event: string,
-	data: any = {},
-	bubble: string = 'l', // direction of bubbling
-	controller?: BubbleController
-) {
-	//console.warn('trigger args', ...arguments);
-
-	const eventName = /^_mc/.test(event) ? event : getMcEventName(event),
-		bubbleController = controller ? controller : new BubbleController(),
-		ev = new CustomEvent(eventName, {
-			detail: { data, control: bubbleController },
-			bubbles: false,
-		});
-
-	if (bubbleController.stopped) return;
-
-	if (/l/.test(bubble)) {
-		domNode.dispatchEvent(ev);
-		ev.stopImmediatePropagation();
-
-		if (bubbleController.stopped) return;
-	}
-
-	// bubble if up or down is indicated
-	if (/[ud]/.test(bubble)) {
-		// add missing 'l', or else no handlers are executed
-		if (bubble.indexOf('l') === -1) {
-			bubble += 'l';
-		}
-
-		setTimeout(() => {
-			// bubble up towards document.body
-			if (bubble.indexOf('u') > -1) {
-				let parentMc: HTMLMcElement | null | undefined =
-					domNode.parentElement?.closest('[data-mc]');
-				if (parentMc) {
-					parentMc?._mc.trigger(eventName, data, bubble, bubbleController);
-				}
-			}
+/**
+Attaches event listeners to DOM elements based on method naming conventions.
 
-			// bubble down towards DOM children
-			if (bubble.indexOf('d') > -1) {
-				let childNodes: DC[] | null = (domNode as HTMLMcElement)._mc.children();
-				if (childNodes) {
-					childNodes.forEach((_mc: DC) => _mc.trigger(eventName, data, bubble)); // event multiplex - dont carry bubble controller
-				}
-			}
-		}, 0);
-	}
-}
+Scans the prototype of the provided element and attaches listeners for methods
+prefixed with `on` or `one`, corresponding to either native HTML events (e.g.,
+'onclick') or microcomponent-prefixed custom events (e.g., '_mcUpdate').
 
+@param {MC|DC} element - The instance whose prototype should be scanned for event handlers.
+*/
 function autoAttachListeners(element: MC | DC) {
 	if (!isBrowser() || element.constructor === DC) return;
 
@@ -193,6 +167,17 @@ function autoAttachListeners(element: MC | DC) {
 	}
 }
 
+/**
+Retrieves immediate child microcomponents of a DOM node.
+
+Queries the DOM for descendant elements marked with `data-mc` that are direct
+children of the provided element and returns their associated `_mc` instances.
+Temporarily sets an internal attribute on the node to prevent recursive matches
+within nested subtrees.
+
+@param {HTMLElement} domNode - The DOM element whose child microcomponents to find.
+@returns {DC[]|null} An array of child microcomponent instances, or null if none found.
+*/
 function getMcChildNodes(domNode: HTMLElement): DC[] | null {
 	const id = Math.random().toString().replace('.', '');
 	const selector = '[data-mc]:not([temp_id="' + id + '"] [data-mc] [data-mc])';
@@ -204,9 +189,24 @@ function getMcChildNodes(domNode: HTMLElement): DC[] | null {
 	return mcArray.length ? (mcArray as DC[]) : null;
 }
 
+/**
+The base class for all microcomponents.
+
+Implements a `WeakRef` to the target DOM element or other data, avoiding
+circular references. Automatically triggers the "Init" lifecycle event and
+attaches listeners via `autoAttachListeners` upon construction.
+*/
 class McBase {
 	private _target: WeakRef<any>; // avoid circular reference
 
+	/**
+	The constructor for the base `McBase` class.
+	
+	Initializes a weak reference to the target and triggers auto-attachment
+	of listeners and initialization lifecycle events.
+	
+	@param {any} [target={}] - The object or element this microcomponent represents.
+	*/
 	constructor(target?: { [key: string]: any }) {
 		let element = this as unknown as MC | DC;
 
@@ -219,28 +219,73 @@ class McBase {
 		init(element as DC); // async lifecycle event
 	}
 
+	/**
+	Returns the current target object (DOM node or other data) referenced by this microcomponent.
+	
+	Uses a `WeakRef` internally to avoid circular references, and safely dereferences it here.
+	
+	@returns {any} The target object, or undefined if the reference has been garbage collected.
+	*/
 	get target(): any {
 		return this._target.deref();
 	}
 }
 
+/**
+A general-purpose base microcomponent that does not require a DOM target.
+
+Inherits from `McBase`, but is primarily used as a lightweight container or
+for logic not directly tied to DOM elements.
+*/
 class MC extends McBase {
+	/**
+	Constructs an instance of the general-purpose microcomponent.
+	
+	@param {any} [target=undefined] - Optional target object or data.
+	*/
 	constructor(target?: any) {
 		super(target);
 	}
 }
 
+/**
+A DOM-centric microcomponent that operates on a specific HTML element.
+
+Extends `McBase` and associates itself with an actual DOM node via the
+`_target` reference. Provides methods for event handling, DOM traversal,
+and interaction with sibling or ancestor microcomponents.
+*/
 class DC extends McBase {
 	constructor(target: HTMLElement) {
 		super(target);
 		//console.warn('DC constructor:', arguments);
 	}
 
+	/**
+	Static helper to attach a microcomponent instance to a DOM element.
+	
+	Wrapper around the `add()` utility function, providing a class-level API
+	for adding child microcomponents to a target node.
+	
+	@param {HTMLElement} target - The DOM element to which to attach the microcomponent.
+	@param {string} key - The property name/key under which to store the instance in `_mc`.
+	@param {any} [element={}] - The microcomponent instance or config object to attach.
+	@returns {HTMLMcElement} The target DOM element with the attached microcomponent.
+	*/
 	static add(target: HTMLElement, key: string, element: any = {}): HTMLMcElement {
 		//console.warn('static DC.add() args', arguments);
 		return add(target, key, element);
 	}
 
+	/**
+	Static helper to remove a named microcomponent from a DOM element.
+	
+	Wrapper around the `remove()` utility function, providing a class-level API
+	for removing child microcomponents.
+	
+	@param {HTMLElement} target - The DOM element from which to remove the microcomponent.
+	@param {string} key - The property name/key corresponding to the microcomponent to remove.
+	*/
 	static remove(target: HTMLElement, key: string) {
 		remove(target, key);
 	}
@@ -250,6 +295,15 @@ class DC extends McBase {
 		off(this.target, eventName, handler);
 	}
 
+	/**
+	Attaches a persistent event listener to the DOM node.
+	
+	This is an instance method wrapper for `on()`, using the internal `_target` DOM reference.
+	
+	@param {string} eventName - The name of the event (e.g., 'click', 'update').
+	@param {EventListenerOrEventListenerObject} handler - The callback function or object to invoke.
+	@returns {EventListenerOrEventListenerObject} The attached handler reference.
+	*/
 	on(
 		eventName: string,
 		handler: EventListenerOrEventListenerObject
@@ -257,6 +311,15 @@ class DC extends McBase {
 		return on(this.target, eventName, handler);
 	}
 
+	/**
+	Attaches a one-time event listener to the DOM node.
+	
+	This is an instance method wrapper for `one()`, using the internal `_target` DOM reference.
+	
+	@param {string} eventName - The name of the event (e.g., 'click', 'update').
+	@param {EventListenerOrEventListenerObject} handler - The callback function or object to invoke once.
+	@returns {EventListenerOrEventListenerObject} The attached one-time handler reference.
+	*/
 	one(
 		eventName: string,
 		handler: EventListenerOrEventListenerObject
@@ -264,13 +327,30 @@ class DC extends McBase {
 		return one(this.target, eventName, handler);
 	}
 
+	/**
+	Triggers a custom event on the DOM node and optionally bubbles it.
+	
+	This is an instance method wrapper for `trigger()`, using the internal `_target` DOM reference.
+	
+	@param {string} eventName - The name of the event (will be prefixed if needed).
+	@param {any} [data={}] - Additional data payload attached to `event.detail.data`.
+	@param {string} [bubble='l'] - Bubbling direction ('l', 'u', 'd' or combinations).
+	@param {BubbleController} [controller] - Optional controller for managing bubbling behavior.
+	*/
 	trigger(eventName: string, data: any = {}, bubble: string = 'l', controller?: BubbleController) {
 		//console.warn('MC.trigger args', ...arguments, this);
 
 		trigger(this.target, eventName, data, bubble, controller);
 	}
 
-	/* DOM traversal */
+	/**
+	Returns an array of all ancestor microcomponents up the DOM tree.
+	
+	Traverses upward from this element's target, collecting all ancestor
+	elements marked with `data-mc` and returning their `_mc` instances.
+	
+	@returns {DC[]|null} An array of ancestor microcomponent instances, or null if none found.
+	*/
 	ancestors(): DC[] | null {
 		let currentNode: HTMLElement | null = (this as DC)?.target as HTMLMcElement,
 			result: DC[] = [];
@@ -286,18 +366,41 @@ class DC extends McBase {
 		return result.length ? result : null;
 	}
 
+	/**
+	Returns the closest ancestor microcomponent or null if none found.
+	
+	This method is equivalent to calling `ancestors()[0]`, but more concise.
+	
+	@returns {DC|null} The nearest ancestor microcomponent, or null if not found.
+	*/
 	closest(): DC | null {
 		let target: HTMLElement = (this as DC).target;
 		if (!isDOM(target)) return null;
 		return ((target.closest('[data-mc]') as HTMLMcElement)?._mc as DC) || null;
 	}
 
+	/**
+	Returns an array of direct child microcomponents.
+	
+	Calls `getMcChildNodes()` internally to find immediate descendants only,
+	excluding nested grandchildren and deeper levels.
+	
+	@returns {DC[]|null} An array of child microcomponent instances, or null if none found.
+	*/
 	children(): DC[] | null {
 		let target: any = (this as any)?.target;
 		if (!isDOM(target)) return null;
 		return getMcChildNodes(target);
 	}
 
+	/**
+	Returns an array of all descendant microcomponents recursively.
+	
+	Uses a `querySelectorAll` query to collect every nested element marked with
+	`data-mc`, returning their associated `_mc` instances.
+	
+	@returns {DC[]|null} An array of descendant microcomponent instances, or null if none found.
+	*/
 	descendants(): DC[] | null {
 		const target: any = (this as DC)?.target;
 		if (!isDOM(target)) return [];
@@ -314,8 +417,21 @@ Autoload Section...
 
 const loadingDCs = new Set<string>();
 
+/**
+Creates a closure that attaches DOM elements with the specified tag name to
+their corresponding microcomponent instances.
+
+Used internally by `makeLoadScript()` when dynamically loading external
+custom element definitions. The returned function is invoked after the
+element definition becomes available, and performs:
+  - Querying of all matching elements in the DOM
+  - Instantiation of new `DC` instances
+  - Attachment to each DOM node via `DC.add()`
+
+@param {string} element - The tag name (custom element name) of the microcomponent to instantiate.
+@returns {Function} A closure that performs the attachment logic when invoked.
+*/
 function attachDC(element: string): Function {
-	//@ts-ignore
 	return () => {
 		const elements: HTMLElement[] = Array.from(
 			document.querySelectorAll(`[data-mc*="${element}"]`)
@@ -342,7 +458,7 @@ function attachDC(element: string): Function {
 				}
 			}
 
-			//@ts-ignore
+			//@ts-ignore: override - node may be null
 			const new_mc = node
 				.getAttribute('data-mc')
 				.split(' ')
@@ -350,16 +466,21 @@ function attachDC(element: string): Function {
 				.join(' ')
 				.trim();
 
-			//@ts-ignore
-			node.setAttribute(
-				'data-mc',
-				//@ts-ignore
-				new_mc
-			);
+			//@ts-ignore: override - node may be null
+			node.setAttribute('data-mc', new_mc);
 		});
 	};
 }
 
+/**
+Dynamically loads and registers a custom element definition from an external JS file.
+
+Constructs the script URL based on kebab-case naming (e.g., `my-element` → `./my/element.js`).
+Registers a handler to be executed once the element is defined, then appends the
+`<script>` tag to `<head>`. Handles both successful loading and error cases.
+
+@param {string} element - The custom element tag name (e.g., 'mc-button', 'my-widget').
+*/
 function makeLoadScript(element: string) {
 	if (loadingDCs.has(element)) return; // already loading
 
@@ -379,7 +500,7 @@ function makeLoadScript(element: string) {
 
 	const loadedPromise = customElements.whenDefined(element);
 
-	//@ts-ignore
+	//@ts-ignore: attachDC will return correct type
 	loadedPromise.then(attachDC(element));
 
 	se.addEventListener('load', (ev: Event) => {
@@ -395,6 +516,18 @@ function makeLoadScript(element: string) {
 	document.head.append(se);
 }
 
+/**
+Scans the DOM for undefined custom elements and pending microcomponents,
+then loads their definitions if necessary.
+
+This is the main driver function for the autoload mechanism. It performs:
+  1. Finds all undefined custom elements in the document
+  2. Checks whether they are already loading or defined
+  3. Calls `makeLoadScript()` to fetch missing definitions
+  4. Invokes `attachDC()` where element definitions exist but haven't been attached yet
+
+It is called both immediately after enabling autoload and on each DOM mutation.
+*/
 function loadUndefinedMCs() {
 	// load unresolved custom elements
 	[...document.querySelectorAll(':not(:defined)')]
@@ -429,17 +562,34 @@ function loadUndefinedMCs() {
 		});
 }
 
-let autoloadEnabled: boolean = false;
-let observer: MutationObserver | null = null;
+/**
+Enables or disables automatic detection and instantiation of microcomponents.
 
+When enabled, the system uses a `MutationObserver` to watch for newly-added
+DOM nodes. For each such node:
+  - If it contains custom elements that are not yet defined, attempts to load them
+  - If it references undefined microcomponent names in its `data-mc` attribute,
+    those definitions are also loaded and attached.
+
+When disabled, the observer is disconnected and all internal tracking state is reset.
+
+@param {boolean} [enable=true] - Whether to enable or disable auto-loading behavior.
+@returns {boolean} The new autoload state (true if enabled, false otherwise).
+*/
+let observer: MutationObserver | null = null;
 function autoload(enable: boolean = true): boolean {
 	if (!enable) {
-		observer?.disconnect();
-		observer = null;
-		return autoloadEnabled;
+		if (observer) {
+			observer.disconnect();
+			observer = null;
+		}
+		return false;
 	}
 
-	autoloadEnabled = enable;
+	const wasEnabled = !!observer;
+	if (wasEnabled) return true;
+
+	// Initialize observer only once
 	observer = new MutationObserver(loadUndefinedMCs);
 
 	setTimeout(() => {
@@ -449,9 +599,15 @@ function autoload(enable: boolean = true): boolean {
 
 	(window as LooseObject).autoload = (window as LooseObject).autoload || autoload;
 
-	return autoloadEnabled;
+	return true;
 }
 
+/**
+The internal `loadingDCs` set, exposed for external inspection.
+
+This property is attached to the `autoload()` function itself and contains
+the names of microcomponent classes currently being loaded (or queued to load).
+*/
 (autoload as LooseObject).state = loadingDCs;
 
-export { McBase, MC, DC, autoload, on, one, off, trigger };
+export { MC, DC, McBase, autoload };

package/dist/elements.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["elements.ts"],"names":[],"mappings":"AASA,wBAAgB,QAAQ,CACvB,OAAO,EAAE,MAAM,EACf,eAAe,EAAE;IAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,GAAG,CAAA;CAAE,GAAG,QAAQ,EACzD,kBAAkB,GAAE,MAAM,EAAO,QA6EjC;AAED,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,wBAAwB,GAAG,SAAS,CAE3E"}
+{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../src/elements.ts"],"names":[],"mappings":"AAwBA,wBAAgB,QAAQ,CACvB,OAAO,EAAE,MAAM,EACf,eAAe,EAAE;IAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,GAAG,CAAA;CAAE,GAAG,QAAQ,EACzD,kBAAkB,GAAE,MAAM,EAAO,QA6EjC;AAOD,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,wBAAwB,GAAG,SAAS,CAE3E"}

package/dist/elements.js

@@ -1,6 +1,5 @@
-'use strict';
-import { DC, McBase } from './MC.js';
 import { kebabToPascal } from './helpers.js';
+import { McBase, DC } from './MC.js';
 function createNamedClass(name, ClassBody) {
     return Object.defineProperty(ClassBody, 'name', { value: name });
 }

package/dist/elements.min.js

@@ -1 +1 @@
-var t={d:(e,n)=>{for(var r in n)t.o(n,r)&&!t.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:n[r]})},o:(t,e)=>Object.prototype.hasOwnProperty.call(t,e)},e={};t.d(e,{c:()=>l,t:()=>u});const n=new Function("try {return this===window;}catch(e){ return false;}");function r(t){return t&&t instanceof HTMLElement}function c(t){return"_mc"+t[0].toUpperCase()+t.substring(1)}function o(t,e,n,r=!1){return t.addEventListener(c(e),n,{capture:!1,once:r}),n}class s{stopped=!1;constructor(){}stop(){this.stopped=!0}}class a{_target;constructor(t){var e;this._target=new WeakRef(t||{}),function(t){if(!n()||t.constructor===i)return;const e=t.target;if(e instanceof HTMLElement){let n=t;Object.getOwnPropertyNames(n.constructor.prototype).filter((t=>/^(on[A-Z]|one[A-Z])/.test(t)&&"function"==typeof n.constructor.prototype[t])).forEach((t=>{let r=/^one/.test(t),c=t.replace(/^on[e]{0,1}/,""),s=c.toLowerCase();if("on"+s in e){let r=e=>{n[t](e)};e.addEventListener(s,r)}else o(e,c,(e=>{n[t](e)}),r)}))}}(this),e=this,setTimeout((()=>{e.constructor!==i&&e.trigger("Init")}),0)}get target(){return this._target.deref()}}class i extends a{constructor(t){super(t)}static add(t,e,n={}){return function(t,e,n={}){let r=t;r._mc||(r._mc=new i(t));const c=r._mc;return e.length&&!c[e]&&(c[e]=n,t instanceof HTMLElement&&!t.getAttribute("data-mc")&&t.setAttribute("data-mc","")),r}(t,e,n)}static remove(t,e){!function(t,e){if(!e)return;const n=t?._mc||{};n&&n[e]&&delete n[e],!Object.keys(n).length&&t instanceof HTMLElement&&t.hasAttribute("data-mc")&&t.removeAttribute("data-mc")}(t,e)}off(t,e){!function(t,e,n){t.removeEventListener(c(e),n)}(this.target,t,e)}on(t,e){return o(this.target,t,e)}one(t,e){return function(t,e,n){return o(t,e,n,!0),n}(this.target,t,e)}trigger(t,e={},n="l",r){!function(t,e,n={},r="l",o){const a=/^_mc/.test(e)?e:c(e),i=o||new s,l=new CustomEvent(a,{detail:{data:n,control:i},bubbles:!1});i.stopped||/l/.test(r)&&(t.dispatchEvent(l),l.stopImmediatePropagation(),i.stopped)||/[ud]/.test(r)&&(-1===r.indexOf("l")&&(r+="l"),setTimeout((()=>{if(r.indexOf("u")>-1){let e=t.parentElement?.closest("[data-mc]");e&&e?._mc.trigger(a,n,r,i)}if(r.indexOf("d")>-1){let e=t._mc.children();e&&e.forEach((t=>t.trigger(a,n,r)))}}),0))}(this.target,t,e,n,r)}ancestors(){let t=this?.target,e=[];if(!r(t))return[];for(;t=t.closest("[data-mc]");)t?._mc&&e.push(t?._mc);return e.length?e:null}closest(){let t=this.target;return r(t)&&t.closest("[data-mc]")?._mc||null}children(){let t=this?.target;return r(t)?function(t){const e=Math.random().toString().replace(".",""),n='[data-mc]:not([temp_id="'+e+'"] [data-mc] [data-mc])';t.setAttribute("temp_id",e);const r=[...t.querySelectorAll(n)].filter((t=>!!t._mc)).map((t=>t._mc));return t.removeAttribute("temp_id"),r.length?r:null}(t):null}descendants(){const t=this?.target;if(!r(t))return[];const e=[...t.querySelectorAll("[data-mc]")].filter((t=>!!t._mc)).map((t=>t._mc));return e.length?e:null}}function l(t,e,n=[]){if(customElements.get(t))return void console.warn(`IGNORED: Custom element "${t}" is already defined!`);if(!t.includes("-"))throw new Error('createCustomElement: tagName must contain at least one hyphen ("-").');let r=t.split("-").map((t=>t.charAt(0).toUpperCase()+t.slice(1))).join("");e.prototype instanceof a?customElements.define(t,function(t,e){return Object.defineProperty(e,"name",{value:t})}(r,class extends HTMLElement{constructor(t){super(),i.add(this,r,new e(this,t))}connectedCallback(){this.dispatchEvent(new CustomEvent("_mcConnected"))}connectedMoveCallback(){this.dispatchEvent(new CustomEvent("_mcConnectedMove"))}disconnectedCallback(){this.dispatchEvent(new CustomEvent("_mcDisconnected"))}adoptedCallback(){this.dispatchEvent(new CustomEvent("_mcAdopted"))}attributeChangedCallback(t,e,n){this.dispatchEvent(new CustomEvent("_mcAttributeChanged",{detail:{name:t,oldValue:e,newValue:n}}))}formResetCallback(){this.dispatchEvent(new CustomEvent("_mcFormReset"))}static get observedAttributes(){return n}})):customElements.define(t,e)}function u(t){return customElements.get(t)}new Set;var m=e.c,d=e.t;export{m as defineCE,d as getCE};
+var t={d:(e,n)=>{for(var r in n)t.o(n,r)&&!t.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:n[r]})},o:(t,e)=>Object.prototype.hasOwnProperty.call(t,e)},e={};function n(t){return"_mc"+t[0].toUpperCase()+t.substring(1)}function r(t,e,r,c=!1){return t.addEventListener(n(e),r,{capture:!1,once:c}),r}t.d(e,{c:()=>l,t:()=>u});class c{stopped=!1;constructor(){}stop(){this.stopped=!0}}const o=new Function("try {return this===window;}catch(e){ return false;}");function s(t){return t&&t instanceof HTMLElement}class a{_target;constructor(t){var e;this._target=new WeakRef(t||{}),function(t){if(!o()||t.constructor===i)return;const e=t.target;if(e instanceof HTMLElement){let n=t;Object.getOwnPropertyNames(n.constructor.prototype).filter((t=>/^(on[A-Z]|one[A-Z])/.test(t)&&"function"==typeof n.constructor.prototype[t])).forEach((t=>{let c=/^one/.test(t),o=t.replace(/^on[e]{0,1}/,""),s=o.toLowerCase();if("on"+s in e){let r=e=>{n[t](e)};e.addEventListener(s,r)}else r(e,o,(e=>{n[t](e)}),c)}))}}(this),e=this,setTimeout((()=>{e.constructor!==i&&e.trigger("Init")}),0)}get target(){return this._target.deref()}}class i extends a{constructor(t){super(t)}static add(t,e,n={}){return function(t,e,n={}){let r=t;r._mc||(r._mc=new i(t));const c=r._mc;return e.length&&!c[e]&&(c[e]=n,t instanceof HTMLElement&&!t.getAttribute("data-mc")&&t.setAttribute("data-mc","")),r}(t,e,n)}static remove(t,e){!function(t,e){if(!e)return;const n=t?._mc||{};n&&n[e]&&delete n[e],!Object.keys(n).length&&t instanceof HTMLElement&&t.hasAttribute("data-mc")&&t.removeAttribute("data-mc")}(t,e)}off(t,e){!function(t,e,r){t.removeEventListener(n(e),r)}(this.target,t,e)}on(t,e){return r(this.target,t,e)}one(t,e){return function(t,e,n){return r(t,e,n,!0),n}(this.target,t,e)}trigger(t,e={},r="l",o){!function(t,e,r={},o="l",s){const a=/^_mc/.test(e)?e:n(e),i=s||new c,l=new CustomEvent(a,{detail:{data:r,control:i},bubbles:!1});i.stopped||/l/.test(o)&&(t.dispatchEvent(l),l.stopImmediatePropagation(),i.stopped)||/[ud]/.test(o)&&(-1===o.indexOf("l")&&(o+="l"),setTimeout((()=>{if(o.indexOf("u")>-1){let e=t.parentElement?.closest("[data-mc]");e&&e?._mc.trigger(a,r,o,i)}if(o.indexOf("d")>-1){let e=t._mc.children();e&&e.forEach((t=>t.trigger(a,r,o)))}}),0))}(this.target,t,e,r,o)}ancestors(){let t=this?.target,e=[];if(!s(t))return[];for(;t=t.closest("[data-mc]");)t?._mc&&e.push(t?._mc);return e.length?e:null}closest(){let t=this.target;return s(t)&&t.closest("[data-mc]")?._mc||null}children(){let t=this?.target;return s(t)?function(t){const e=Math.random().toString().replace(".",""),n='[data-mc]:not([temp_id="'+e+'"] [data-mc] [data-mc])';t.setAttribute("temp_id",e);const r=[...t.querySelectorAll(n)].filter((t=>!!t._mc)).map((t=>t._mc));return t.removeAttribute("temp_id"),r.length?r:null}(t):null}descendants(){const t=this?.target;if(!s(t))return[];const e=[...t.querySelectorAll("[data-mc]")].filter((t=>!!t._mc)).map((t=>t._mc));return e.length?e:null}}function l(t,e,n=[]){if(customElements.get(t))return void console.warn(`IGNORED: Custom element "${t}" is already defined!`);if(!t.includes("-"))throw new Error('createCustomElement: tagName must contain at least one hyphen ("-").');let r=t.split("-").map((t=>t.charAt(0).toUpperCase()+t.slice(1))).join("");e.prototype instanceof a?customElements.define(t,function(t,e){return Object.defineProperty(e,"name",{value:t})}(r,class extends HTMLElement{constructor(t){super(),i.add(this,r,new e(this,t))}connectedCallback(){this.dispatchEvent(new CustomEvent("_mcConnected"))}connectedMoveCallback(){this.dispatchEvent(new CustomEvent("_mcConnectedMove"))}disconnectedCallback(){this.dispatchEvent(new CustomEvent("_mcDisconnected"))}adoptedCallback(){this.dispatchEvent(new CustomEvent("_mcAdopted"))}attributeChangedCallback(t,e,n){this.dispatchEvent(new CustomEvent("_mcAttributeChanged",{detail:{name:t,oldValue:e,newValue:n}}))}formResetCallback(){this.dispatchEvent(new CustomEvent("_mcFormReset"))}static get observedAttributes(){return n}})):customElements.define(t,e)}function u(t){return customElements.get(t)}new Set;var m=e.c,d=e.t;export{m as defineCE,d as getCE};

package/dist/elements.ts

@@ -1,12 +1,27 @@
-'use strict';
-
-import { DC, McBase } from './MC.js';
 import { kebabToPascal } from './helpers.js';
-
+import { McBase, DC } from './MC.js';
+
+/**
+ * Creates a named class constructor with the specified name.
+ * @param name - The desired name for the class.
+ * @param ClassBody - The class constructor to which the name will be assigned.
+ * @returns The class constructor with the name property set.
+ */
 function createNamedClass(name: string, ClassBody: { new (...args: any[]): any }) {
 	return Object.defineProperty(ClassBody, 'name', { value: name });
 }
 
+/**
+ * Defines a custom HTML element with optional observed attributes and micro component integration.
+ * The class provided in DefinitionClass will be added to the ._mc hash object appended to the custom element instance.
+ * Automatically assigns a "PascalCase" class name derived from the <kebab-case> tagName.
+ * If the provided definition class extends McBase (indicating a DC or MC class extension), it wraps the constructor to register
+ * the element instance with DC (DomComponent).
+ *
+ * @param tagName - The HTML tag name for the custom element (must contain at least one hyphen).
+ * @param DefinitionClass - The constructor function or class that defines the element's behavior.
+ * @param observedAttributes - An optional array of attribute names to observe for changes.
+ */
 export function defineCE(
 	tagName: string,
 	DefinitionClass: { new (...args: any[]): any } | Function,
@@ -30,7 +45,7 @@ export function defineCE(
 		//console.warn('pure class', tagName, DefinitionClass);
 		customElements.define(
 			tagName,
-			// @ts-ignore
+			// @ts-ignore: DefinitionClass exists
 			DefinitionClass
 		);
 		return;
@@ -46,7 +61,7 @@ export function defineCE(
 				constructor(data?: any) {
 					super();
 					// console.log('[named class constructor]', tagName, name, this, data);
-					// @ts-ignore
+					// @ts-ignore: DefinitionClass exists
 					DC.add(this, name, new DefinitionClass(this, data));
 				}
 
@@ -89,6 +104,11 @@ export function defineCE(
 	);
 }
 
+/**
+ * Retrieves a custom element constructor by tag name.
+ * @param tagName - The HTML tag name to look up.
+ * @returns The CustomElementConstructor if defined, or undefined if not found.
+ */
 export function getCE(tagName: string): CustomElementConstructor | undefined {
 	return customElements.get(tagName);
 }

package/dist/events.d.ts

@@ -0,0 +1,11 @@
+export declare function getMcEventName(eventName: string): string;
+export declare function off(domNode: Node, eventName: string, handler: EventListenerOrEventListenerObject): void;
+export declare function on(domNode: Node, eventName: string, handler: EventListenerOrEventListenerObject, once?: boolean): EventListenerOrEventListenerObject;
+export declare function one(domNode: Node, eventName: string, handler: EventListenerOrEventListenerObject): EventListenerOrEventListenerObject;
+export declare class BubbleController {
+    stopped: boolean;
+    constructor();
+    stop(): void;
+}
+export declare function trigger(domNode: HTMLElement, event: string, data?: any, bubble?: string, controller?: BubbleController): void;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAaA,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAUD,wBAAgB,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,kCAAkC,QAEhG;AAWD,wBAAgB,EAAE,CACjB,OAAO,EAAE,IAAI,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,EAC3C,IAAI,GAAE,OAAe,GACnB,kCAAkC,CAGpC;AAYD,wBAAgB,GAAG,CAClB,OAAO,EAAE,IAAI,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,kCAAkC,CAGpC;AAUD,qBAAa,gBAAgB;IAC5B,OAAO,UAAS;;IAQhB,IAAI;CAGJ;AAmBD,wBAAgB,OAAO,CACtB,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,GAAQ,EACd,MAAM,GAAE,MAAY,EACpB,UAAU,CAAC,EAAE,gBAAgB,QA8C7B"}