@twobirds/microcomponents 0.0.4 → 0.0.6

package/dist/microcomponents.ts

@@ -1,212 +1,402 @@
 'use strict';
-export class MC {
 
-	private target: HTMLElement | null;
-
-	private privateMCs: { [key: string]: any } = {};
-
-	_mc?: { [key: string]: any } = {};
-
-	static debug: boolean = false;
-
-	constructor(target: HTMLElement | null = null) {
+/**
+ * @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;
-		this.privateMCs = {};
-		if ( MC?.debug ) {
-			this._mc = this.privateMCs;
-		};
-	}
-
-	// return all top-level micro components from an HTMLElement
-	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 ) ];
-	}
-
-	// add a microcomponent to a target DOM node
-	static add( target: HTMLElement, key: string, element: any = {} ): any[] {
-
-		const mc = target as any;
-
-		// create the _mc property if necessary
-		if ( !mc._mc ){
-			mc._mc = new MC();
-		}
-
-		// add the element with the given property key to the _mc property object
-		if ( key && !mc._mc[ key ] ){
-			mc._mc[ key ] = element;
-			if ( target ) {
-				target.setAttribute('_mc', '' );
-			}
-		}
-
-		return element;
-	}
-
-	// remove a micro component from the target DOM node
-	static remove( target: HTMLElement, key: string ): void {
-
-		if ( //silent fail
-			!key
-			|| typeof key !== 'string'
-			|| !target
-			|| target instanceof HTMLElement === false ) {
-				return;
-		};
-
-		const mc = target as any;
-
-		// delete the property from the HTMLElement _mc collection
-		if (mc._mc && mc._mc[key]) {
-			delete mc._mc[key];
-		}
-
-		// remove the _mc attribute if the DOM collection is empty
-		if ( !Object.keys(mc._mc).length && target.hasAttribute('_mc') ) {
-			target.removeAttribute('_mc');
-		}
-
-		return;
-	}
-
-	/*
-	helper methods
-	*/
-
-	// get all microcomponents from a list of HTMLElements
-	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;
-	}
-
-	// get all ancestor DOM nodes up to the document
-	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;
-	}
-
-	private isDOM( element: any ): boolean {
-		return element && element instanceof HTMLElement;
-	}
-
-	/*
-	Methods to handle private MCs
-	*/
-
-	// add a microcomponent to the private microcomponent collection
-	add( key?: string, element: any = {} ): any {
-
-		// add the element
-		if ( key ){
-			this.privateMCs[key] = element; // also the first element in the private MC collection
-		}
-		return element;
-	}
-
-	// remove a micro component from the private microcomponent collection
-	remove(key: string): void {
-
-		// remove the component from the private collection
-		if (key in this.privateMCs) {
-			delete this.privateMCs[key];
-		}
-
-	}
-
-	/*
-	selector methods, non-chainable
-	*/
-
-	// all private collection members
-	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 []
-	}
-
-
-	// first anchestor DOM node, all public MCs
-	parent(search?: string): any[] {
-
-		if ( !this.isDOM( this.target) ) return [];
-
-		return this.traverseNodes( ( this.target as HTMLElement).parentNode, search, true);
-	}
-
-	// all anchestor DOM nodes, beginning with the closest, all public MCs
-	parents(search?: string): any[] {
-
-		if ( !this.isDOM( this.target) ) return [];
-
-		return this.traverseNodes( (this.target as HTMLElement ).parentNode, search, false);
-	}
-
-	// nearest child DOM nodes, all puclic MCs
-	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( [ ...myDomElements ], search);
-		(this.target as HTMLElement).removeAttribute('temp-id');
-		return mcValues;
-	}
 
-	// all descendant DOM nodes, all puclic MCs
-	descendants(search?: string): any[] {
+		/**
+         * The collection of private microcomponents.
+         * @private
+		 * @type {Object.<string, any>}
+		 */
+		this.privateMCs = {};
 
-		if ( !this.isDOM( this.target) ) return [];
+        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;
+    }
 
-		const myDomElements = (this.target as HTMLElement).querySelectorAll('*[_mc]');
-		return this.getMicroComponents( [ ...myDomElements ], search);
-	}
 }
 
 export interface HTMLElementMc extends HTMLElement {
 	_mc: MC;
 }
+
+export { MC };

package/jsdoc.conf.json

@@ -0,0 +1,19 @@
+{
+  "source": {
+    "include": ["src/microcomponents.js"],
+    "includePattern": ".+\\.js(doc|x)?$",
+    "excludePattern": "(^|\\/|\\\\)_"
+  },
+  "opts": {
+    "destination": "./public/jsdoc/es5+",
+    "recurse": false,
+    "template": "default"
+  },
+  "plugins": [
+    "plugins/markdown"
+  ],
+  "templates": {
+    "cleverLinks": true,
+    "monospaceLinks": true
+  }
+}