@twobirds/microcomponents 0.0.10 → 0.0.14

package/dist/microcomponents.js

@@ -1,367 +1,176 @@
 '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 {
-    target;
-    privateMCs = {};
-    _mc = {};
-    static debug = 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 = 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;
+/*
+helper methods
+*/
+// get all microcomponents from a list of HTMLElements
+function getMicroComponents(elements, search) {
+    let mcValues = [];
+    elements.forEach(e => {
+        if (e) {
+            if (e instanceof HTMLElement) {
+                const _mc = e?._mc;
+                if (!search && _mc) {
+                    mcValues = mcValues.concat(Object.values(e._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, search, firstonly = true) {
+    let mcValues = [];
+    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;
     }
-    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)];
+    return mcValues;
+}
+function isDOM(element) {
+    return element && element instanceof HTMLElement;
+}
+export class MC {
+    #target = {};
+    #_mc = {};
+    static debug = false;
+    constructor(target) {
+        this.#target = target;
+        this.#_mc = {};
     }
-    static add(target, key, element = {}) {
+    get _mc() {
+        if (!MC.debug)
+            return undefined;
+        return this.#_mc;
+    }
+    get target() {
+        return this.#target;
+    }
+    // return all top-level micro components from an HTMLElement, or the searched one
+    static siblings(target, search = '') {
         const mc = target;
         if (!mc._mc) {
-            mc._mc = new 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, key, element = {}) {
+        let node = target;
+        // create the _mc property if necessary
+        if (!node._mc) {
+            node._mc = new MC(target);
         }
-        if (key && !mc._mc[key]) {
-            mc._mc[key] = element;
-            if (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, 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 (!key)
+            return; // silent fail
+        const _mc = target?._mc || {};
+        // delete the property from the HTMLElement _mc collection
+        if (_mc && _mc[key]) {
+            delete _mc[key];
         }
-        if (!Object.keys(mc._mc).length && target.hasAttribute('_mc')) {
+        // 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;
     }
-    /**
-     * 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 => {
-            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));
-                    }
-                    else if (search && this.privateMCs[search]) {
-                        mcValues.push(e._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.
-     */
-    traverseNodes(node, search, firstonly = true) {
-        let mcValues = [];
-        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;
-    }
-    /**
-     * 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;
-    }
-    /**
-     * 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 = {}) {
-        if (key) {
-            this.privateMCs[key] = element;
+    // add a microcomponent to the collection
+    add(key, element, target) {
+        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;
     }
-    /**
-     * 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) {
-        if (key in this.privateMCs) {
-            delete this.privateMCs[key];
+    // remove a micro component from the collection
+    remove(key, target) {
+        const _mc = this.#_mc;
+        const t = target;
+        // 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];
     }
-    /**
-     * 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) {
-                return this.getMicroComponents([this.target], search);
-            }
-            else {
-                const result = this.privateMCs[search || ''];
-                return search && result ? [result] : Object.entries(this.privateMCs);
-            }
-        }
-        return [];
+    // 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 = '') {
+        const _mc = this.#_mc;
+        if (!_mc)
+            return [];
+        const result = _mc[search || ''];
+        return search && result ? [result] : [...Object.values(_mc)];
     }
-    /**
-     * 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))
+    /*
+    the following selectors will only work for the DOM top level MCs and return [] otherwise
+    */
+    // first anchestor DOM node, all public MCs
+    parent(search = '') {
+        if (!isDOM(this.#target))
             return [];
-        return this.traverseNodes(this.target.parentNode, search, true);
+        return traverseNodes(this.#target.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) {
-        if (!this.isDOM(this.target))
+    // all anchestor DOM nodes, beginning with the closest, all public MCs
+    parents(search = '') {
+        if (!isDOM(this.#target))
             return [];
-        return this.traverseNodes(this.target.parentNode, search, false);
+        return traverseNodes(this.#target.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) {
-        if (!this.isDOM(this.target))
+    // nearest child DOM nodes, all puclic MCs
+    children(search = '') {
+        if (!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(Array.from(myDomElements), search);
+        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;
     }
-    /**
-     * 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))
+    // all descendant DOM nodes, all puclic MCs
+    descendants(search = '') {
+        if (!isDOM(this.#target))
             return [];
-        const myDomElements = this.target.querySelectorAll('*[_mc]');
-        const mcValues = this.getMicroComponents(Array.from(myDomElements), search);
-        return mcValues;
+        const myDomElements = this.#target.querySelectorAll('*[_mc]');
+        return getMicroComponents([...myDomElements], search);
     }
 }
-export { MC };

package/dist/microcomponents.min.js

@@ -1,35 +1,38 @@
-'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))
-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));}
-else if(search&&this.privateMCs[search]){mcValues.push(e._mc[search]);}}}});return mcValues;}
-traverseNodes(node,search,firstonly=true){let mcValues=[];while(node){if(node._mc){if(!search){mcValues=mcValues.concat(Object.values(node._mc));}
+'use strict';function getMicroComponents(elements,search){let mcValues=[];elements.forEach(e=>{if(e){if(e instanceof HTMLElement){const _mc=e?._mc;if(!search&&_mc){mcValues=mcValues.concat(Object.values(e._mc));}
+else if(search&&_mc&&_mc[search]){mcValues.push(_mc[search]);}}}});return mcValues;}
+function traverseNodes(node,search,firstonly=true){let mcValues=[];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;}
-isDOM(element){return element&&element instanceof HTMLElement;}
-add(key,element={}){if(key){this.privateMCs[key]=element;}
+function isDOM(element){return element&&element instanceof HTMLElement;}
+export class MC{#target={};#_mc={};static debug=false;constructor(target){this.#target=target;this.#_mc={};}
+get _mc(){if(!MC.debug)
+return undefined;return this.#_mc;}
+get target(){return this.#target;}
+static siblings(target,search=''){const mc=target;if(!mc._mc){return[];}
+const _mc=mc._mc;if(search.length){return _mc?.[search]||[];}
+return[...Object.values(_mc)];}
+static add(target,key,element={}){let node=target;if(!node._mc){node._mc=new MC(target);}
+const _mc=node._mc;if(key.length&&!_mc[key]){_mc[key]=element;if(target instanceof HTMLElement){target.setAttribute('_mc','');}}
 return element;}
-remove(key){if(key in this.privateMCs){delete this.privateMCs[key];}}
-siblings(search){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[];}
-parent(search){if(!this.isDOM(this.target))
-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(Array.from(myDomElements),search);return mcValues;}
-descendants(search){if(!this.isDOM(this.target))
-return[];const myDomElements=this.target.querySelectorAll('*[_mc]');const mcValues=this.getMicroComponents(Array.from(myDomElements),search);return mcValues;}}
-export{MC};
+static remove(target,key){if(!key)
+return;const _mc=target?._mc||{};if(_mc&&_mc[key]){delete _mc[key];}
+if(!Object.keys(_mc).length&&target instanceof HTMLElement&&target.hasAttribute('_mc')){target.removeAttribute('_mc');}
+return;}
+add(key,element,target){if(this.#_mc[key])
+return;if(target){MC.add(target,key,element);}
+this.#_mc[key]=element;return element;}
+remove(key,target){const _mc=this.#_mc;const t=target;if(target){MC.remove(t,key);}
+delete _mc?.[key];}
+siblings(search=''){const _mc=this.#_mc;if(!_mc)
+return[];const result=_mc[search||''];return search&&result?[result]:[...Object.values(_mc)];}
+parent(search=''){if(!isDOM(this.#target))
+return[];return traverseNodes(this.#target.parentNode,search,true);}
+parents(search=''){if(!isDOM(this.#target))
+return[];return traverseNodes(this.#target.parentNode,search,false);}
+children(search=''){if(!isDOM(this.#target))
+return[];const id=Math.random().toString().replace('.','');const selector='[_mc]:not([temp_id="'+id+'"] [_mc] [_mc])';this.#target.setAttribute('temp_id',id);const myDomElements=this.#target.querySelectorAll(selector);const mcValues=getMicroComponents([...myDomElements],search);this.#target.removeAttribute('temp-id');return mcValues;}
+descendants(search=''){if(!isDOM(this.#target))
+return[];const myDomElements=this.#target.querySelectorAll('*[_mc]');return getMicroComponents([...myDomElements],search);}}