@twobirds/microcomponents 0.0.4 → 0.0.7

package/dist/microcomponents.js

@@ -1,18 +1,141 @@
 'use strict';
-export class MC {
+/**
+ * @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 {
     target;
     privateMCs = {};
     _mc = {};
     static debug = false;
-    constructor(target = null) {
+    /**
+     * Constructs an MC instance with a target DOM element.
+     * @constructor
+     * @param {HTMLElement | { [key: string]: any }} - The target DOM element or any object.
+     */
+    constructor(target = 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) {
+        if (MC.debug) {
+            /**
+             * exposes private microcomponents in debug mode.
+             * @public
+             * @type {Object.<string, any>}
+             */
             this._mc = this.privateMCs;
         }
-        ;
     }
-    // return all top-level micro components from an HTMLElement
     static siblings(target, search) {
         let t = target;
         if (!t?._mc)
@@ -20,14 +143,11 @@ export class MC {
         let mc = t._mc;
         return search ? mc[search] ? [mc[search]] : [] : [...Object.entries(t._mc)];
     }
-    // add a microcomponent to a target DOM node
     static add(target, key, element = {}) {
         const mc = target;
-        // 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) {
@@ -36,31 +156,27 @@ export class MC {
         }
         return element;
     }
-    // remove a micro component from the target DOM node
     static remove(target, key) {
-        if ( //silent fail
-        !key
-            || typeof key !== 'string'
-            || !target
-            || target instanceof HTMLElement === false) {
+        if (!key || typeof key !== 'string' || !target || !(target instanceof HTMLElement))
             return;
-        }
-        ;
         const mc = target;
-        // 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
+    /**
+     * 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.
+     */
     getMicroComponents(elements, search) {
         let mcValues = [];
         elements.forEach(e => {
@@ -85,7 +201,17 @@ export class MC {
         });
         return mcValues;
     }
-    // get all ancestor DOM nodes up to the document
+    /**
+     * 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.
+     */
     traverseNodes(node, search, firstonly = true) {
         let mcValues = [];
         while (node) {
@@ -103,31 +229,60 @@ export class MC {
         }
         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}
+     */
     isDOM(element) {
         return element && element instanceof HTMLElement;
     }
-    /*
-    Methods to handle private MCs
-    */
-    // add a microcomponent to the private microcomponent collection
+    /**
+     * 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, element = {}) {
-        // add the element
         if (key) {
-            this.privateMCs[key] = element; // also the first element in the private MC collection
+            this.privateMCs[key] = element;
         }
         return element;
     }
-    // remove a micro component from the private microcomponent collection
+    /**
+     * 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) {
-        // remove the component from the private collection
         if (key in this.privateMCs) {
             delete this.privateMCs[key];
         }
     }
-    /*
-    selector methods, non-chainable
-    */
-    // all private collection members
+    /**
+     * 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) {
         if (this.target) {
             if (this.target instanceof HTMLElement === true) {
@@ -140,34 +295,73 @@ export class MC {
         }
         return [];
     }
-    // first anchestor DOM node, all public MCs
+    /**
+     * 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) {
         if (!this.isDOM(this.target))
             return [];
         return this.traverseNodes(this.target.parentNode, search, true);
     }
-    // all anchestor DOM nodes, beginning with the closest, all public MCs
+    /**
+     * 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) {
         if (!this.isDOM(this.target))
             return [];
         return this.traverseNodes(this.target.parentNode, search, false);
     }
-    // nearest child DOM nodes, all puclic MCs
+    /**
+     * 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) {
         if (!this.isDOM(this.target))
             return [];
         const id = crypto.randomUUID();
         this.target.setAttribute('temp-id', id);
         const myDomElements = this.target.querySelectorAll(`*[_mc]:not([temp-id="${id}"] [_mc] [_mc])`);
-        const mcValues = this.getMicroComponents([...myDomElements], search);
-        this.target.removeAttribute('temp-id');
+        const mcValues = this.getMicroComponents(Array.from(myDomElements), search);
         return mcValues;
     }
-    // all descendant DOM nodes, all puclic MCs
+    /**
+     * 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) {
         if (!this.isDOM(this.target))
             return [];
         const myDomElements = this.target.querySelectorAll('*[_mc]');
-        return this.getMicroComponents([...myDomElements], search);
+        const mcValues = this.getMicroComponents(Array.from(myDomElements), search);
+        return mcValues;
     }
 }
+export { MC };

package/dist/microcomponents.min.js

@@ -1,12 +1,12 @@
-'use strict';export class MC{target;privateMCs={};_mc={};static debug=false;constructor(target=null){this.target=target;this.privateMCs={};if(MC?.debug){this._mc=this.privateMCs;};}
+'use strict';class MC{target;privateMCs={};_mc={};static debug=false;constructor(target=undefined){this.target=target;this.privateMCs={};if(MC.debug){this._mc=this.privateMCs;}}
 static siblings(target,search){let t=target;if(!t?._mc)
 return[];let mc=t._mc;return search?mc[search]?[mc[search]]:[]:[...Object.entries(t._mc)];}
 static add(target,key,element={}){const mc=target;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,key){if(!key||typeof key!=='string'||!target||target instanceof HTMLElement===false){return;};const mc=target;if(mc._mc&&mc._mc[key]){delete mc._mc[key];}
-if(!Object.keys(mc._mc).length&&target.hasAttribute('_mc')){target.removeAttribute('_mc');}
-return;}
+static remove(target,key){if(!key||typeof key!=='string'||!target||!(target instanceof HTMLElement))
+return;const mc=target;if(mc._mc&&mc._mc[key]){delete mc._mc[key];}
+if(!Object.keys(mc._mc).length&&target.hasAttribute('_mc')){target.removeAttribute('_mc');}}
 getMicroComponents(elements,search){let mcValues=[];elements.forEach(e=>{if(e){if(e instanceof HTMLElement){if(!search&&e._mc){mcValues=mcValues.concat(Object.values(e._mc));}
 else if(search&&e._mc&&e._mc[search]){mcValues.push(e._mc[search]);}}
 else if(e instanceof MC){if(!search){mcValues=mcValues.concat(Object.values(this.privateMCs));}
@@ -29,6 +29,7 @@ return[];return this.traverseNodes(this.target.parentNode,search,true);}
 parents(search){if(!this.isDOM(this.target))
 return[];return this.traverseNodes(this.target.parentNode,search,false);}
 children(search){if(!this.isDOM(this.target))
-return[];const id=crypto.randomUUID();this.target.setAttribute('temp-id',id);const myDomElements=this.target.querySelectorAll(`*[_mc]:not([temp-id="${id}"][_mc][_mc])`);const mcValues=this.getMicroComponents([...myDomElements],search);this.target.removeAttribute('temp-id');return mcValues;}
+return[];const id=crypto.randomUUID();this.target.setAttribute('temp-id',id);const myDomElements=this.target.querySelectorAll(`*[_mc]:not([temp-id="${id}"][_mc][_mc])`);const mcValues=this.getMicroComponents(Array.from(myDomElements),search);return mcValues;}
 descendants(search){if(!this.isDOM(this.target))
-return[];const myDomElements=this.target.querySelectorAll('*[_mc]');return this.getMicroComponents([...myDomElements],search);}}
+return[];const myDomElements=this.target.querySelectorAll('*[_mc]');const mcValues=this.getMicroComponents(Array.from(myDomElements),search);return mcValues;}}
+export{MC};