@twobirds/microcomponents 0.0.4 → 0.0.7

package/MicroComponentProposal_draft.md

@@ -13,7 +13,7 @@ Microcomponents provide a way to encapsulate functionality and state within a ta
 **Proposed API:**
 
 - **Static Methods:**
-  - `MC.add( taarget, key, element)`: Attach a top level micro component to an HTMLElement.
+  - `MC.add( target, 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.
 

package/README.md

@@ -2,28 +2,49 @@
 
 ![Micro Components Logo](https://gitlab.com/twoBirds/microcomponents/-/raw/main/MicroComponents.svg)
 
-This code aims at [improving Javascript modularity](https://gitlab.com/twoBirds/microcomponents/-/blob/main/microcomponents_why.md?ref_type=heads). 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.
+**This code aims at improving Javascript modularity and encapsulation**.
 
-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.
+Micro Components function similar to node_modules, as MCs can contain other MCs recursivly.
 
-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.
+So importing a custom MC in your client side code like this:
+```javascript
+import MyButton from '@mySampleLib/Button';
+```
+... and is equivalent to:
+```javascript
+npm i @mySampleLib/Button;
+```
+... on the server side.
 
-For an overview, continue reading.
+**On the client side** MCs reside inside DOM nodes (instanceof HTMLElement) in a special "_mc" property, or inside each other. Usually they provide a direct interface to their inner code.
 
-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).
+**On the server side** MCs can be used to organize your code, too.
 
-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.
+## Disclaimer
+This is a massive undertaking. MCs are just the foundation of what I do. I am about to **dump** [20+ years of javascript programming](https://gitlab.com/twoBirds/microcomponents/-/blob/main/microcomponents_magic.md?ref_type=heads#things-i-already-did-with-this-in-my-own-framework-twobirds-or-in-apps-that-i-developed-with-it) **into open source libraries**, so feel free to [fund this](https://gofund.me/076c614c). The better this is funded, the faster it will be done. Given enough resources, I will start a crowdfunded company that will develop a new ecosystem for javascript/typescript programming.
+
+By **"Open Source"** I mean **really free and open**, as **you get all my inner source code with it**. Once you understand the Micro Component principle, you are back in command of your software, no matter what MC functionality you import in your system. Since **Micro Components** are encapsuled, off-shoring and near-shoring is no problem, and reusability is guaranteed. Your external coders do not need to access your code repository or your toolchain. They only need to understand MCs.
+
+Established frameworks provide a documented interface to a hidden layer of closed source inner functionality. MCs can be used to **add an interface to components you developed using other frameworks**. So you can still use your existing code. But you will want to migrate it ASAP, since MCs work with any FW.
+
+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. Also this will be a dependency in twoBirds then.
 
+## Status
+WIP. Micro components should be done soon, as in days.
 
-## Functional Requirements
+## General
 
-- I want to **enrich a standard HTMLElement instance with encapsuled and modular javascript**, without having to resort to web components or big frameworks.
-- I want to have an **interface** into this functionality that I can both tight and loosely couple.
-- I want to **import and use Micro Components in any framework** that allows for direct DOM access.
-- I want **a single location** in an HTMLElement instance where all this functionality is **stored and sufficiently organized**.
-- I want to be able to use **selectors** to find those instances in the DOM.
-- All this must stricly follow **web standards**.
+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, and [click here to see why you may want to use it](https://gitlab.com/twoBirds/microcomponents/-/blob/main/microcomponents_why.md?ref_type=heads).
 
+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. The latter is WIP, backporting is currently last on my list.
+
+For a short usage description goto [Micro Component Usage](https://gitlab.com/twoBirds/microcomponents/-/blob/main/microcomponents_usage.md?ref_type=heads).
+
+Check the [typedoc API reference](http://twobirds.gitlab.io/microcomponents/docs/modules.html) if you want to drill into the source code.
+
+Or read the more detailed [jsdoc API documentation](http://twobirds.gitlab.io/microcomponents/jsdoc/es5+/index.html) which contains **examples**.
+
+To see what can be done, go to [additional concepts](https://gitlab.com/twoBirds/microcomponents/-/blob/main/microcomponents_magic.md?ref_type=heads) which shows what it already has been used for.
 
 ## Simple Usage:
 
@@ -31,40 +52,68 @@ To see what can be done, go to [additional concepts](https://gitlab.com/twoBirds
 
 before:
 ```HTML
-<button></button>
+<div></div>
 ```
 
-code: (assume "Button" is some class in a library)
-```javascript
-import 'MC' from '@twobirds/microcomponents';
-import 'Button' from 'tb/ui'; // made-up example library
+code:
+```typescript
+// create an inner micro component class
+class MyInnerMC extends MC{
 
-// select first button element in DOM
-let myButton = document.querySelector('button');
+	constructor( target ){
+		super( target );
+	}
 
-// this will add the micro component to the myButton._mc property:
-MC.add( myButton, 'tb_ui_button', new Button( myButton, { ...config data } ) );
-```
+	doSomething(){
+		console.log( this, 'something done' )
+	}
+}
 
-after:
-```HTML
-<button _mc></button>
-```
-_mc indicates that this HTML element contains at least one micro component. This is needed for the **selectors**.
+// create a custom micro component class
+class MyMC extends MC{
 
+	private myInner: MyInnerMC;
 
-```javascript
-console.log( myButton._mc );
-// { tb_ui_button: { target: <button>, onClick: <function> } }
-```
+	constructor( target ){
+		super( target );
+		this.target = target;
 
-For detailed information jump to [Micro Component Usage](https://gitlab.com/twoBirds/microcomponents/-/blob/main/microcomponents_usage.md?ref_type=heads);
+		//add a private inner micro component
+		this.myInner = new MyInnerMC( target );
 
-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. Also this will be a dependency in twoBirds then.
+		//add a public micro component
+		this.add(
+			'myPublicInnerMC',
+			new MyInnerMC( target )
+		);
+	}
+}
+
+// get some element from the DOM
+const element = document.querySelector('div')
+
+// Add the custom micro component instance to the target element
+let topLevelMC = MC.add(
+	element,
+	'myMC',
+	new MyMC( element )
+);
 
-## Useful Links
+console.log( element._mc );
+// { 'myMC': { target: (element), _mc: { myPublicInnerMC: {...} } } }
 
-[API documentation](http://twobirds.gitlab.io/microcomponents/docs/modules.html)
+console.log( element._mc.myMC );
+// { target: (element), _mc: { myPublicInnerMC: {...} } }
+
+console.log( topLevelMC.siblings() );
+// [ { target: (element), _mc: { myPublicInnerMC: {...} } } ]
+```
+
+after:
+```HTML
+<div _mc></button>
+```
+_mc indicates that this HTML element contains at least one micro component. This is needed for the **selectors**.
 
 ## Contact
 Feel free to contact me for any questions or inquiries:

package/dist/microcomponents.d.ts

@@ -1,26 +1,242 @@
-export declare 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
+ */
+declare class MC {
     private target;
     private privateMCs;
     _mc?: {
         [key: string]: any;
     };
     static debug: boolean;
-    constructor(target?: HTMLElement | 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?: HTMLElement | {
+        [key: string]: any;
+    } | undefined);
     static siblings(target: HTMLElement, search?: string): any[];
     static add(target: HTMLElement, key: string, element?: any): any[];
     static remove(target: HTMLElement, key: string): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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[];
+    /**
+     * 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[];
+    /**
+     * 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[];
+    /**
+     * 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[];
+    /**
+     * 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[];
 }
 export interface HTMLElementMc extends HTMLElement {
     _mc: MC;
 }
+export { MC };
 //# sourceMappingURL=microcomponents.d.ts.map

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,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"}
+{"version":3,"file":"microcomponents.d.ts","sourceRoot":"","sources":["../src/microcomponents.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,cAAM,EAAE;IAEP,OAAO,CAAC,MAAM,CAAmD;IAE9D,OAAO,CAAC,UAAU,CAA8B;IAEzC,GAAG,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAM;IAEzC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAS;IAE9B;;;;OAIG;gBACU,MAAM,GAAE,WAAW,GAAG;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,GAAG,SAAqB;IA0BjF,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAO5D,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,GAAQ,GAAG,GAAG,EAAE;IAiBtE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAcrD;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IAwB1B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,aAAa;IAkBrB;;;;;;;;;OASG;IACH,OAAO,CAAC,KAAK;IAIhB;;;;;;;;;;OAUG;IACA,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,GAAQ,GAAG,GAAG;IAO5C;;;;;;;;OAQG;IACA,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAM5B;;;;;;;;;OASG;IACA,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAYnC;;;;;;;;;OASG;IACA;OACG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAK9B;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAK/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;IAWhC;;;;;;;;;OASG;IACH,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE;CAStC;AAED,MAAM,WAAW,aAAc,SAAQ,WAAW;IACjD,GAAG,EAAE,EAAE,CAAC;CACR;AAED,OAAO,EAAE,EAAE,EAAE,CAAC"}