@twobirds/microcomponents 0.0.10 → 0.0.14

package/src/microcomponents.ts

@@ -1,402 +1,216 @@
 'use strict';
 
-/**
- * @module microcomponenents
- */
-
-/**
- * A static flag to enable or disable debugging mode.
- * @name debug
- * @memberOf MC
- * @static
- * @type {boolean} A static flag to enable or disable debugging mode.
- */
-
-/**
- * Retrieves all top-level microcomponents from a target HTMLElement.
- * @name siblings
- * @memberOf MC
- * @static
- * @function
- * @param {HTMLElement} target - The target DOM element.
- * @param {string} [search] - The key of the specific microcomponent to find.
- * @returns {Array<any>} An array of microcomponents or an empty array if none found.
- * @example
- * const siblings = MC.siblings(
- * &nbsp;document.getElementById('myElement'),
- * &nbsp;'myComponent'
- * );
- */
-
-/**
- * Adds a top level microcomponent to a target DOM node.
- * @name add
- * @memberOf MC
- * @static
- * @function
- * @param {HTMLElement} target - The target DOM element.
- * @param {string} key - The key to identify the microcomponent.
- * @param {any} [element={}] - The microcomponent to add.
- * @returns {any} The added microcomponent.
- * @example
- * const component = MC.add(
- * &nbsp;document.getElementById('myElement'),
- * &nbsp;'myComponent',
- * &nbsp;{}
- * );
- */
-
-/**
- * Removes a top level microcomponent from the target DOM node.
- * @name remove
- * @memberOf MC
- * @static
- * @function
- * @param {HTMLElement} target - The target DOM element.
- * @param {string} key - The key identifying the microcomponent.
- * @example
- * MC.remove(
- * &nbsp;document.getElementById('myElement'),
- * &nbsp;'myComponent'
- * );
- */
-
-/**
- * Manages microcomponents (MCs) attached to DOM elements, allowing for the
- * addition, removal, and traversal of microcomponents across siblings, parents,
- * children, and descendants.
- *
- * This class provides an API for interacting with microcomponents on DOM elements.
- * Public microcomponents are stored on the `_mc` attribute of the DOM element, while
- * private microcomponents are managed internally.
- *
- * @example
- * ```javascript
- *
- * // create the micro component class
- * class MyMC extends MC{
- *
- * &nbsp;constructor( target ){
- * &nbsp;&nbsp;super( target );
- * &nbsp;&nbsp;this.target = target;
- * &nbsp;}
- * }
- *
- * const element = document.querySelector('div')
- *
- * // Add the top level microcomponent to the target element
- * let mcc = MC.add(
- * &nbsp;element,
- * &nbsp;'myMC',
- * &nbsp;new MyMC( element )
- * );
- *
- * // Add an inner (private) microcomponent to mcc
- * let mcc.add(
- * &nbsp;'myInnerMC',
- * &nbsp;new MyMC( element )
- * );
- *
- * console.log( element._mc );
- * // { 'myMC': { target: (element) } }
- *
- * console.log( element._mc.myMC );
- * // { target: (element) }
- *
- * console.log( mcc.siblings() );
- * // [ { target: (element) } ]
- *
- * ```
- * @class
- * @name MC
- */
-class MC {
-
-	private target: HTMLElement | { [key: string]: any } | undefined;
-
-    private privateMCs: { [key: string]: any } = {};
-
-    public _mc?: { [key: string]: any } = {};
-
-    static debug: boolean = false;
-
-    /**
-     * Constructs an MC instance with a target DOM element.
-	 * @constructor
-     * @param {HTMLElement | { [key: string]: any }} - The target DOM element or any object.
-     */
-    constructor( target: HTMLElement | { [key: string]: any } | undefined = undefined ) {
-
-		/**
-         * target is a DOM element or a parent MC
-         * @type {object}
-         * @public
-         */
-		this.target = target;
-
-		/**
-         * The collection of private microcomponents.
-         * @private
-		 * @type {Object.<string, any>}
-		 */
-		this.privateMCs = {};
-
-        if (MC.debug) {
-			/**
-			 * exposes private microcomponents in debug mode.
-			 * @public
-			 * @type {Object.<string, any>}
-			 */
-            this._mc = this.privateMCs;
-        }
-    }
-
-    static siblings(target: HTMLElement, search?: string): any[] {
-        let t = target as HTMLElementMc;
-        if (!t?._mc) return [];
-        let mc: { [key: string]: any } = t._mc;
-        return search ? mc[search] ? [mc[search]] : [] : [...Object.entries(t._mc)];
-    }
-
-    static add(target: HTMLElement, key: string, element: any = {}): any[] {
-        const mc = target as any;
-
-        if (!mc._mc) {
-            mc._mc = new MC();
-        }
-
-        if (key && !mc._mc[key]) {
-            mc._mc[key] = element;
-            if (target) {
-                target.setAttribute('_mc', '');
-            }
-        }
-
-        return element;
-    }
-
-    static remove(target: HTMLElement, key: string): void {
-        if (!key || typeof key !== 'string' || !target || !(target instanceof HTMLElement)) return;
-
-        const mc = target as any;
-
-        if (mc._mc && mc._mc[key]) {
-            delete mc._mc[key];
-        }
-
-        if (!Object.keys(mc._mc).length && target.hasAttribute('_mc')) {
-            target.removeAttribute('_mc');
-        }
-    }
-
-    /**
-	 * returns top level microcomponents from a list of HTMLElements.
-	 * @name getMicroComponents
-	 * @instance
-	 * @function
-	 * @private
-     * @param {Array<any>} elements - The elements to search for microcomponents.
-     * @param {string} [search] - The key of the specific microcomponent.
-     * @returns {Array<any>} An array of microcomponents.
-     */
-    private getMicroComponents(elements: any[], search?: string): any[] {
-        let mcValues: any[] = [];
-
-        elements.forEach(e => {
-            if (e) {
-                if (e instanceof HTMLElement) {
-                    if (!search && (e as HTMLElementMc)._mc) {
-                        mcValues = mcValues.concat(Object.values((e as any)._mc));
-                    } else if (search && (e as HTMLElementMc)._mc && (e as any)._mc[search]) {
-                        mcValues.push((e as any)._mc[search]);
-                    }
-                } else if (e instanceof MC) {
-                    if (!search) {
-                        mcValues = mcValues.concat(Object.values(this.privateMCs));
-                    } else if (search && this.privateMCs[search]) {
-                        mcValues.push((e as any)._mc[search]);
-                    }
-                }
-            }
-        });
-
-        return mcValues;
-    }
-
-    /**
-     * returns ancestor MCs
-	 * @name traverseNodes
-	 * @instance
-	 * @function
-	 * @private
-     * @param {Node | null} node - The starting DOM node.
-     * @param {string} [search] - The key of the specific microcomponent.
-     * @param {boolean} [firstonly=true] - If true, returns the first match only.
-     * @returns {Array<any>} An array of matching microcomponents.
-     */
-    private traverseNodes(node: Node | null, search?: string, firstonly: boolean = true): any[] {
-        let mcValues: any[] = [];
-
-        while (node) {
-            if ((node as HTMLElementMc)._mc) {
-                if (!search) {
-                    mcValues = mcValues.concat(Object.values((node as any)._mc));
-                } else if (search && (node as any)._mc[search]) {
-                    mcValues.push((node as any)._mc[search]);
-                }
-                if (firstonly) return mcValues;
-            }
-            node = node.parentNode;
-        }
-
-        return mcValues;
-    }
-
-    /**
-     * returns true if the element is an instance of HTMLElement.
-	 * @instance
-	 * @function
-	 * @name isDOM
-	 * @private
-	 * @type {Function}
-     * @param {any} element - The element to check.
-     * @returns {boolean}
-     */
-    private isDOM(element: any): boolean {
-        return element && element instanceof HTMLElement;
-    }
-
-	/**
-	 * adds a microcomponent to the private collection.
-	 * @name add
-	 * @instance
-	 * @function
-	 * @param {string} [key] - The key to identify the microcomponent.
-	 * @param {any} [element={}] - The microcomponent to add.
-	 * @returns {any} The added microcomponent.
-	 * @example
-	 * const privateComp = this.add('privateComponent', {});
-	 */
-    add(key?: string, element: any = {}): any {
-        if (key) {
-            this.privateMCs[key] = element;
-        }
-        return element;
-    }
-
-	/**
-	 * removes a microcomponent from the private collection.
-	 * @name remove
-	 * @instance
-	 * @function
-	 * @param {string} [key] - The key to identify the microcomponent.
-	 * @example
-	 * this.remove('privateComponent');
-	 */
-    remove(key: string): void {
-        if (key in this.privateMCs) {
-            delete this.privateMCs[key];
-        }
-    }
-
-	/**
-	 * removes a microcomponent from the private collection.
-	 * @name siblings
-	 * @instance
-	 * @function
-     * @param {string} [search] - The key of the specific microcomponent.
-     * @returns {Array<any>} An array of matching sibling microcomponents.
-     * @example
-     * const siblings = this.siblings('siblingComponent');
-	 */
-    siblings(search?: string): any[] {
-        if (this.target) {
-            if (this.target instanceof HTMLElement === true) {
-                return this.getMicroComponents([this.target], search);
-            } else {
-                const result = this.privateMCs[search || ''];
-                return search && result ? [result] : Object.entries(this.privateMCs);
-            }
-        }
-        return [];
-    }
-
-	/**
-     * retrieves the first ancestor DOM node with a matching microcomponent.
-	 * @name parent
-	 * @instance
-	 * @function
-     * @param {string} [search] - The key of the specific microcomponent.
-     * @returns {Array<any>} An array with the matching microcomponent.
-     * @example
-     * const parent = mcInstance.parent('parentComponent');
-	 */
-    /**
-     */
-    parent(search?: string): any[] {
-        if (!this.isDOM(this.target)) return [];
-        return this.traverseNodes((this.target as HTMLElement).parentNode, search, true);
-    }
-
-    /**
-     * retrieves the first ancestor DOM node with a matching microcomponent.
-	 * @name parents
-	 * @instance
-	 * @function
-     * @param {string} [search] - The key of the specific microcomponent.
-     * @returns {Array<any>} An array of matching ancestor microcomponents.
-     * @example
-     * const parents = mcInstance.parents('ancestorComponent');
-     */
-    parents(search?: string): any[] {
-        if (!this.isDOM(this.target)) return [];
-        return this.traverseNodes((this.target as HTMLElement).parentNode, search, false);
-    }
-
-    /**
-     * retrieves nearest child _mc DOM nodes, gets their matching microcomponents, and stops there.
-	 * @name children
-	 * @instance
-	 * @function
-     * @param {string} [search] - The key of the specific microcomponent.
-     * @returns {Array<any>} An array of matching child microcomponents.
-     * @example
-     * const children = mcInstance.children('childComponent');
-     */
-    children(search?: string): any[] {
-        if (!this.isDOM(this.target)) return [];
-
-        const id = crypto.randomUUID();
-        (this.target as HTMLElement).setAttribute('temp-id', id);
-        const myDomElements = (this.target as HTMLElement).querySelectorAll(`*[_mc]:not([temp-id="${id}"] [_mc] [_mc])`);
-        const mcValues = this.getMicroComponents(Array.from(myDomElements), search);
-
-        return mcValues;
-    }
-
-    /**
-     * retrieves all decendant _mc DOM nodes and gets their matching microcomponents.
-	 * @name children
-	 * @instance
-	 * @function
-     * @param {string} [search] - The key of the specific microcomponent.
-     * @returns {Array<any>} An array of matching descendant microcomponents.
-     * @example
-     * const descendants = mcInstance.descendants('descendantComponent');
-     */
-    descendants(search?: string): any[] {
-        if (!this.isDOM(this.target)) return [];
-
-        const myDomElements = (this.target as HTMLElement).querySelectorAll('*[_mc]');
-        const mcValues = this.getMicroComponents(Array.from(myDomElements), search);
-
-        return mcValues;
-    }
+/*
+helper methods
+*/
+
+// get all microcomponents from a list of HTMLElements
+function getMicroComponents( elements: any[], search: string): any[] {
+	let mcValues: any[] = [];
+
+	elements.forEach( e => {
+		if (e) {
+			if (e instanceof HTMLElement) {
+				const _mc = ( e as any )?._mc;
+				if ( !search && _mc ) {
+					mcValues = mcValues.concat(Object.values(( e as any )._mc));
+				}
+				else if ( search && _mc && _mc[search] ) {
+					mcValues.push( _mc[search] );
+				}
+			}
+		}
+	});
+	return mcValues;
+}
 
+// get all ancestor DOM nodes up to the document
+function traverseNodes(node: { [key:string]: any }, search: string, firstonly = true): any[] {
+	let mcValues: any[] = [];
+	while (node) {
+		if (node._mc) {
+			if (!search) {
+				mcValues = mcValues.concat(Object.values(node._mc));
+			}
+			else if (search && node._mc[search]) {
+				mcValues.push(node._mc[search]);
+			}
+			if (firstonly)
+				return mcValues;
+		}
+		node = node.parentNode;
+	}
+	return mcValues;
 }
 
-export interface HTMLElementMc extends HTMLElement {
-	_mc: MC;
+function isDOM(element: { [key:string]: any } ) {
+	return element && element instanceof HTMLElement;
 }
 
-export { MC };
+type HTMLElementMC = HTMLElement & { _mc: { [key:string]: any } }
+
+export class MC {
+
+	#target: { [key:string]: any } = {};
+
+	#_mc: { [key:string]: any } = {};
+
+	static debug: boolean = false;
+
+	constructor( target: { [key:string]: any } ) {
+		this.#target = target;
+		this.#_mc = {};
+	}
+
+	get _mc(): undefined | any {
+		if ( !MC.debug ) return undefined;
+		return this.#_mc;
+	}
+
+	get target(): any {
+		return this.#target;
+	}
+
+	// return all top-level micro components from an HTMLElement, or the searched one
+	static siblings( target: HTMLElementMC, search: string = '' ): any[] {
+		const mc = target as any;
+
+		if (!mc._mc) {
+			return [];
+		}
+
+		const _mc = mc._mc;
+
+		if ( search.length ){
+			return _mc?.[search] || [];
+		}
+
+		return [ ...Object.values(_mc) ];
+	}
+
+	// add a microcomponent to a target DOM node
+	static add( target: HTMLElement, key: string, element = {} ): any {
+
+		let node = target as HTMLElementMC;
+
+		// create the _mc property if necessary
+		if (!node._mc) {
+			node._mc = new MC( target );
+		}
+
+		const _mc = node._mc;
+
+		// add the element with the given property key to the _mc property
+		if ( key.length && !_mc[key]) {
+			_mc[key] = element;
+			// add attribute if HTMLElement
+			if ( target instanceof HTMLElement ) {
+				target.setAttribute('_mc', '');
+			}
+		}
+		return element;
+	}
+
+	// remove a micro component from the DOM
+	static remove( target: HTMLElementMC, key: string) {
+		if ( !key ) return; // silent fail
+
+		const _mc = target?._mc || {};
+
+		// delete the property from the HTMLElement _mc collection
+		if ( _mc && _mc[key] ) {
+			delete _mc[key];
+		}
+
+		// remove the _mc attribute if the DOM collection is empty
+		if ( !Object.keys(_mc).length && target instanceof HTMLElement && target.hasAttribute('_mc') ) {
+			target.removeAttribute('_mc');
+		}
+		return;
+	}
+
+	// add a microcomponent to the collection
+	add( key: string, element: any, target?: HTMLElement ): any {
+		if ( this.#_mc[key] ) return;
+
+		// if target parameter exists ( a DOM node )
+		// you want a top level (public) MC
+		if ( target ){
+			// ... add the new micro component to the DOM node _mc
+			MC.add( target, key, element );
+		}
+		// add the new micro component to the private collection anyway
+		this.#_mc[key] = element;
+
+		return element;
+	}
+
+	// remove a micro component from the collection
+	remove( key: string, target?: HTMLElement ): void {
+		const _mc = this.#_mc;
+		const t = target as HTMLElementMC;
+
+		// if target parameter exists ( a DOM node )
+		// you want to remove a top level (public) MC
+		if ( target ){
+			// ... remove the new micro component from the DOM node _mc
+			MC.remove( t, key );
+		}
+		// remove the new micro component from the private collection anyway
+		delete _mc?.[key];
+	}
+
+	// return all micro components from the collection, or the searched one
+	// in a top level DOM MC, this refers to the inner collection always
+	// use MC.siblings() to get the public MCs
+	siblings( search: string = '' ): any[] {
+		const _mc = this.#_mc;
+
+		if ( !_mc ) return [];
+
+		const result = _mc[search || ''];
+
+		return search && result ? [result] : [ ...Object.values(_mc) ];
+	}
+
+	/*
+	the following selectors will only work for the DOM top level MCs and return [] otherwise
+	*/
+
+	// first anchestor DOM node, all public MCs
+	parent( search: string = '' ): any[] {
+		if ( !isDOM(this.#target) ) return [];
+
+		return traverseNodes( (this as any).#target.parentNode, search, true);
+	}
+
+	// all anchestor DOM nodes, beginning with the closest, all public MCs
+	parents( search: string = '' ): any[] {
+		if ( !isDOM(this.#target) ) return [];
+
+		return traverseNodes( (this as any).#target.parentNode, search, false);
+	}
+
+	// nearest child DOM nodes, all puclic MCs
+	children( search: string = '' ): any[] {
+		if ( !isDOM(this.#target) ) return [];
+
+		const id = Math.random().toString().replace('.','');
+		const selector = '[_mc]:not([temp_id="' + id +'"] [_mc] [_mc])'; // HOTFIX: minifier or tsc compiler error, dont use backtick string, cuts out blanks
+		this.#target.setAttribute('temp_id', id);
+		const myDomElements = this.#target.querySelectorAll(selector);
+		const mcValues = getMicroComponents([...myDomElements], search);
+		this.#target.removeAttribute('temp-id');
+
+		return mcValues;
+	}
+
+	// all descendant DOM nodes, all puclic MCs
+	descendants( search: string = '' ): any[] {
+		if ( !isDOM(this.#target) ) return [];
+
+		const myDomElements = this.#target.querySelectorAll('*[_mc]');
+
+		return getMicroComponents([...myDomElements], search);
+	}
+}