@twobirds/microcomponents 0.0.1 → 0.0.3

package/.gitlab-ci.yml

@@ -0,0 +1,16 @@
+# The Docker image that will be used to build your app
+image: node:lts
+# Functions that should be executed before the build script is run
+before_script:
+  - npm i
+pages:
+  script:
+    - npm run build
+  artifacts:
+    paths:
+      # The folder that contains the files to be exposed at the Page URL
+      - public
+  rules:
+    # This ensures that only pushes to the default branch will trigger
+    # a pages deploy
+    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

package/MicroComponentProposal_draft.md

@@ -13,15 +13,18 @@ Microcomponents provide a way to encapsulate functionality and state within a ta
 **Proposed API:**
 
 - **Static Methods:**
-  - `MC.add(target, key, element)`: Attach a micro component.
-  - `MC.remove(target, key)`: Detach a micro component.
+  - `MC.add( taarget, key, element)`: Attach a top level micro component to an HTMLElement.
+  - `MC.remove( target, key )`: Detach a top level micro component from an HTMLElement.
+  - `MC.siblings( target )`: get top level micro components from an HTMLElement.
 
 - **Instance Methods:**
-  - `siblings(search)`: Retrieve sibling micro components.
-  - `parent(search)`: Get parent micro components.
-  - `parents(search)`: Get all ancestor micro components.
-  - `children(search)`: Retrieve child micro components.
-  - `descendants(search)`: Get all descendant micro components.
+  - `add( key, element )`: Attach a private Micro Component to a Micro Component.
+  - `remove( key )`: Detach a private Micro Component from a Micro Component.
+  - `siblings(search?)`: Retrieve sibling micro components.
+  - `parent(search?)`: Get parent top level micro components.
+  - `parents(search?)`: Get all ancestor top level micro components.
+  - `children(search?)`: Retrieve child top level micro components.
+  - `descendants(search?)`: Get all descendant top level micro components.
 
 **Use Cases:**
 1. Modular web applications.

package/README.md

@@ -1,16 +1,16 @@
 ## MICRO COMPONENTS
 
-![Micro Components Logo](./MicroComponents.svg)
+![Micro Components Logo](https://gitlab.com/twoBirds/microcomponents/-/raw/main/MicroComponents.svg)
 
 This code aims at **improving Javascript modularity**. It does not describe a specific Micro Component itself but rather describes they way they are **organized**. A typical example of a **Micro Component** can be found in "additional concepts" below.
 
-Using micro components enforces **DRY, KISS and SOLID** principles in Javascript programming. Read this [RFC](./MicroComponentProposal_draft.md?ref_type=heads) for the shortest info.
+Using micro components enforces **DRY, KISS and SOLID** principles in Javascript programming. Read this [RFC](https://gitlab.com/twoBirds/microcomponents/-/blob/main/MicroComponentProposal_draft.md?ref_type=heads) for the shortest info.
 
-This is a low-level approach. It consists of a single class with 2 static methods and 5 selector methods, and weights less than 2 kB. Also there is an ES3 version to help e.g. [hbbtv](https://en.wikipedia.org/wiki/Hybrid_Broadcast_Broadband_TV) modular JS coding, or any other device that relies on ES3.
+This is a low-level approach. It consists of a single class with 3 static methods and 5 selector methods, and weights in at ~2 kB. Also there is an ES3 version to help e.g. [hbbtv](https://en.wikipedia.org/wiki/Hybrid_Broadcast_Broadband_TV) modular JS coding, or any other device that relies on ES3.
 
 For an overview, continue reading.
 
-For a detailed functional description goto [Micro Component Usage](https://gitlab.com/twoBirds/microcomponents/-/blob/main/microcomponents_usage.md?ref_type=heads).
+For a detailed functional description goto [Micro Component Usage](https://gitlab.com/twoBirds/microcomponents/-/blob/main/microcomponents_usage.md?ref_type=heads) and check the [typedoc API documentation](http://twobirds.gitlab.io/microcomponents/docs/modules.html).
 
 To see what can be done, go to [additional concepts](https://gitlab.com/twoBirds/microcomponents/-/blob/main/microcomponents_magic.md?ref_type=heads) which delve a little deeper into how to use it, and what it already has been used for.
 
@@ -59,7 +59,7 @@ before:
 
 code: (assume "Button" is some class in a library)
 ```javascript
-import 'MC' from 'twobirds/microcomponents';
+import 'MC' from '@twobirds/microcomponents';
 import 'Button' from 'tb/ui'; // made-up example library
 
 // select first button element in DOM
@@ -93,7 +93,11 @@ This functionality has been used in very big and complicated data processing pro
 - to represent business processes and their tasks
 - and lately to compose very complex native web components from distinct modular functionality.
 
-I decided extract this from the [twoBirds framework](https://www.npmjs.com/package/twobirds-core), since it is framework agnostic and relies solely on the standard DOM and native javascript or typescript.
+I decided to extract this functionality from the [twoBirds framework](https://www.npmjs.com/package/twobirds-core), since it is framework agnostic, and relies solely on the standard DOM and native javascript or typescript, and is a useful tool in itself.
+
+## Useful Links
+
+[API documentation](http://twobirds.gitlab.io/microcomponents/docs/modules.html)
 
 ## Contact
 Feel free to contact me for any questions or inquiries:

package/assets/fiddle/MicroComponents.svg

@@ -0,0 +1,15 @@
+<svg width="200" height="200" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg">
+ <!-- Created with SVG-edit - http://svg-edit.googlecode.com/ -->
+ <title>test</title>
+ <rect fill="transparent" x="0" y="0" width="200" height="200" fill-opacity="1"/>
+ <g style="fill:transparent">
+  <title>first bird</title>
+  <path fill="#18829c" d="
+    m15,160
+    a30,75 45 1 0 160,-150
+    a20,50 225 1 1 -110,100
+    a12,25 45 1 1 60,-50
+    a20,50 225 1 0 -110,100
+    " />
+ </g>
+</svg>

package/assets/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Micro Components</title>
+</head>
+<body>
+    <a href="http://twobirds.gitlab.io/microcomponents/docs/modules.html" target="_blank">API</a>
+</body>
+</html>

package/dist/microcomponents.d.ts

@@ -1,14 +1,19 @@
 export declare class MC {
     private target;
     private privateMCs;
+    _mc?: {
+        [key: string]: any;
+    };
     static debug: boolean;
     constructor(target?: HTMLElement | null);
-    static add(element?: any, key?: string, target?: HTMLElement): any;
-    add(element?: any, key?: string, target?: HTMLElement): any;
+    static siblings(target: HTMLElement, search?: string): any[];
+    static add(target: HTMLElement, key: string, element?: any): any[];
     static remove(target: HTMLElement, key: string): void;
-    remove(key: string): void;
     private getMicroComponents;
     private traverseNodes;
+    private isDOM;
+    add(key?: string, element?: any): any;
+    remove(key: string): void;
     siblings(search?: string): any[];
     parent(search?: string): any[];
     parents(search?: string): any[];

package/dist/microcomponents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"microcomponents.d.ts","sourceRoot":"","sources":["../src/microcomponents.ts"],"names":[],"mappings":"AACA,qBAAa,EAAE;IAEd,OAAO,CAAC,MAAM,CAAqB;IAEnC,OAAO,CAAC,UAAU,CAA8B;IAEhD,MAAM,CAAC,KAAK,EAAE,OAAO,CAAS;gBAElB,MAAM,GAAE,WAAW,GAAG,IAAW;IAM7C,MAAM,CAAC,GAAG,CAAE,OAAO,GAAE,GAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAI,GAAG;IAuBxE,GAAG,CAAE,OAAO,GAAE,GAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAI,GAAG;IAcjE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAkBrD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAiBzB,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,aAAa;IAwBrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAKhC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAQ9B,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAQ/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAUhC,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;CAInC;AAED,MAAM,WAAW,aAAc,SAAQ,WAAW;IACjD,GAAG,EAAE,EAAE,CAAC;CACR"}
+{"version":3,"file":"microcomponents.d.ts","sourceRoot":"","sources":["../src/microcomponents.ts"],"names":[],"mappings":"AACA,qBAAa,EAAE;IAEd,OAAO,CAAC,MAAM,CAAqB;IAEnC,OAAO,CAAC,UAAU,CAA8B;IAEhD,GAAG,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAM;IAElC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAS;gBAElB,MAAM,GAAE,WAAW,GAAG,IAAW;IAS7C,MAAM,CAAC,QAAQ,CAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,GAAI,GAAG,EAAE;IAQ9D,MAAM,CAAC,GAAG,CAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,GAAQ,GAAI,GAAG,EAAE;IAqBxE,MAAM,CAAC,MAAM,CAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAI,IAAI;IA8BvD,OAAO,CAAC,kBAAkB;IA0B1B,OAAO,CAAC,aAAa;IAmBrB,OAAO,CAAC,KAAK;IASb,GAAG,CAAE,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,GAAQ,GAAI,GAAG;IAU3C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAczB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAchC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAQ9B,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAQ/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAahC,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;CAOnC;AAED,MAAM,WAAW,aAAc,SAAQ,WAAW;IACjD,GAAG,EAAE,EAAE,CAAC;CACR"}

package/dist/microcomponents.js

@@ -2,46 +2,52 @@
 export class MC {
     target;
     privateMCs = {};
+    _mc = {};
     static debug = false;
     constructor(target = null) {
         this.target = target;
         this.privateMCs = {};
+        if (MC?.debug) {
+            this._mc = this.privateMCs;
+        }
+        ;
+    }
+    // return all top-level micro components from an HTMLElement
+    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)];
     }
     // add a microcomponent to a target DOM node
-    static add(element = {}, key, target) {
+    static add(target, key, element = {}) {
         const mc = target;
-        if (key && 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) {
-                    target.setAttribute('_mc', '');
-                }
-            }
-        }
-        return element;
-    }
-    // add a microcomponent to the DOM or to the private microcomponent collection
-    add(element = {}, key, target) {
-        // add the element
-        if (target && key) {
-            // ...to the DOM
-            MC.add(element, key, target);
+        // create the _mc property if necessary
+        if (!mc._mc) {
+            mc._mc = new MC();
         }
-        else if (key) {
-            // ... to the private element collection
-            this.privateMCs[key] = element;
+        // 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 DOM
+    // 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) {
+            return;
+        }
+        ;
         const mc = target;
-        // delete the property from the DOM
+        // delete the property from the HTMLElement _mc collection
         if (mc._mc && mc._mc[key]) {
             delete mc._mc[key];
         }
@@ -51,16 +57,6 @@ export class MC {
         }
         return;
     }
-    // remove a micro component from the DOM or the private microcomponent collection
-    remove(key) {
-        // remove the component from the private collection
-        if (key in this.privateMCs) {
-            delete this.privateMCs[key];
-        }
-        if (MC.debug && this.target) {
-            MC.remove(this.target, key);
-        }
-    }
     /*
     helper methods
     */
@@ -69,11 +65,21 @@ export class MC {
         let mcValues = [];
         elements.forEach(e => {
             if (e) {
-                if (!search && e._mc) {
-                    mcValues = mcValues.concat(Object.values(e._mc));
+                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 (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]);
+                    }
                 }
             }
         });
@@ -97,27 +103,59 @@ export class MC {
         }
         return mcValues;
     }
+    isDOM(element) {
+        return element && element instanceof HTMLElement;
+    }
+    /*
+    Methods to handle private MCs
+    */
+    // add a microcomponent to the private microcomponent collection
+    add(key, element = {}) {
+        // 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) {
+        // remove the component from the private collection
+        if (key in this.privateMCs) {
+            delete this.privateMCs[key];
+        }
+    }
     /*
     selector methods, non-chainable
     */
-    // all public _mc members and private collection members
+    // all private collection members
     siblings(search) {
-        return this.getMicroComponents([this.target], search).concat(Object.entries(this.privateMCs));
+        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 puclic MCs
+    // first anchestor DOM node, all public MCs
     parent(search) {
-        if (!this.target)
+        if (!this.isDOM(this.target))
             return [];
         return this.traverseNodes(this.target.parentNode, search, true);
     }
-    // all anchestor DOM nodes, beginning with the closest, all puclic MCs
+    // all anchestor DOM nodes, beginning with the closest, all public MCs
     parents(search) {
-        if (!this.target)
+        if (!this.isDOM(this.target))
             return [];
         return this.traverseNodes(this.target.parentNode, search, false);
     }
     // nearest child DOM nodes, all puclic MCs
     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])`);
@@ -127,6 +165,8 @@ export class MC {
     }
     // all descendant DOM nodes, all puclic MCs
     descendants(search) {
+        if (!this.isDOM(this.target))
+            return [];
         const myDomElements = this.target.querySelectorAll('*[_mc]');
         return this.getMicroComponents([...myDomElements], search);
     }

package/dist/microcomponents.min.js

@@ -1,27 +1,34 @@
-'use strict';export class MC{target;privateMCs={};static debug=false;constructor(target=null){this.target=target;this.privateMCs={};}
-static add(element={},key,target){const mc=target;if(key&&target){if(!mc._mc){mc._mc=new MC();}
-if(key&&!mc._mc[key]){mc._mc[key]=element;if(target){target.setAttribute('_mc','');}}}
+'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;};}
+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;}
-add(element={},key,target){if(target&&key){MC.add(element,key,target);}
-else if(key){this.privateMCs[key]=element;}
-return element;}
-static remove(target,key){const mc=target;if(mc._mc&&mc._mc[key]){delete mc._mc[key];}
+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;}
-remove(key){if(key in this.privateMCs){delete this.privateMCs[key];}
-if(MC.debug&&this.target){MC.remove(this.target,key);}}
-getMicroComponents(elements,search){let mcValues=[];elements.forEach(e=>{if(e){if(!search&&e._mc){mcValues=mcValues.concat(Object.values(e._mc));}
-else if(search&&e._mc&&e._mc[search]){mcValues.push(e._mc[search]);}}});return mcValues;}
+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));}
 else if(search&&node._mc[search]){mcValues.push(node._mc[search]);}
 if(firstonly)
 return mcValues;}
 node=node.parentNode;}
 return mcValues;}
-siblings(search){return this.getMicroComponents([this.target],search).concat(Object.entries(this.privateMCs));}
-parent(search){if(!this.target)
+isDOM(element){return element&&element instanceof HTMLElement;}
+add(key,element={}){if(key){this.privateMCs[key]=element;}
+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.target)
+parents(search){if(!this.isDOM(this.target))
 return[];return this.traverseNodes(this.target.parentNode,search,false);}
-children(search){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;}
-descendants(search){const myDomElements=this.target.querySelectorAll('*[_mc]');return this.getMicroComponents([...myDomElements],search);}}
+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;}
+descendants(search){if(!this.isDOM(this.target))
+return[];const myDomElements=this.target.querySelectorAll('*[_mc]');return this.getMicroComponents([...myDomElements],search);}}

package/dist/microcomponents.ts

@@ -0,0 +1,212 @@
+'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) {
+		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[] {
+
+		if ( !this.isDOM( this.target) ) return [];
+
+		const myDomElements = (this.target as HTMLElement).querySelectorAll('*[_mc]');
+		return this.getMicroComponents( [ ...myDomElements ], search);
+	}
+}
+
+export interface HTMLElementMc extends HTMLElement {
+	_mc: MC;
+}

package/package.json

@@ -1,19 +1,40 @@
 {
   "name": "@twobirds/microcomponents",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Micro Components Organization Class",
   "main": "microcomponents.js",
   "sideEffects": false,
   "scripts": {
-    "build": "tsc; npm run minify; npm run copyToDist; typedoc;",
+    "typedoc": "typedoc",
+    "clean": "rm -rf build/*; rm -rf docs/*; rm -rf dist/*;",
+    "prep": "cp -R assets/* public || true; cp src/* build || true;",
+    "build": "npm run clean; npm run prep; tsc; npm run minify; npm run copyToDist;",
     "minify": "jsmin -o build/microcomponents.es3.min.js ./src/microcomponents.es3.js;jsmin -o build/microcomponents.min.js build/microcomponents.js;",
-    "copyToDist": "cp build/* dist; cp MicroComponents.svg dist"
+    "copyToDist": "cp build/* dist; cp MicroComponents.svg dist; cp MicroComponents.svg public/fiddle;"
   },
   "author": "",
   "license": "ISC",
   "devDependencies": {
     "jsmin": "^1.0.1",
-    "typedoc": "^0.23.24",
-    "typescript": "^5.6.2"
-  }
+    "typedoc": "^0.26.10",
+    "typescript": "^5.6.3"
+  },
+  "keywords": [
+    "javascript",
+    "library",
+    "native",
+    "DOM manipulation",
+    "lightweight",
+    "standalone",
+    "SPA",
+    "PWA",
+    "ES3",
+    "ES5",
+    "ES6",
+    "ES7",
+    "ES2015",
+    "ES2016",
+    "client",
+    "API"
+  ]
 }