@twobirds/microcomponents 0.0.3 → 0.0.6

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,41 +2,24 @@
 
 ![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.
+## Status
+WIP. Should be tested and done soon.
 
-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.
+## General
 
-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.
+This code aims at improving Javascript modularity. It does not describe a specific Micro Component itself but rather describes they way they are **organized**.
 
-For an overview, continue reading.
+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).
 
-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).
+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.
 
-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.
+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.
 
-## Why would I give this a try in my company?
-
-It is lightweight, proven and can yield positive results immediatly.
-
-
-### **As the CTO**:
-- **Reusability**: this works with every Javascript framework that allows for DOM access, and it will work as long as the DOM exists in browsers. That is, forever.
-- **Scalability**: scales perfectly by design.
-- **Interoperability**: where many teams in different projects should share specific business or UI logic, you want to have something that works in any JS framework you use.
-
-### **As a Project Manager**:
-- **Separation of Concerns**: since this is a modular approach you can **split UI logic from Business logic** and let diffent teams work on each.
-- using this, you can **work with external developers without the need to give them access to your projects code repository**.
-- you will find out that this allows your project to **become independent from the "tools hell"**. You tend to use **DIY** modules where you had tools before.
-
-### **As a Javascript Developer**:
-- The learning curve to use this is more than shallow. 1 hour should be enough.
-- This is based on **plain Javascript/Typescript, HTML and CSS**. There is no abstraction layer.
-- From the very start **it is fun to work with**. You are back in control of your code without bigger frameworks, but you are able to interact with them.
-- You can **work for any customer right away**. **No training on their system required**, just fulfill their micro component requirements.
-- Over time, you can **build your own framework or functional libraries** from scratch.
+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.
 
 ## Functional Requirements
 
@@ -59,14 +42,38 @@ before:
 
 code: (assume "Button" is some class in a library)
 ```javascript
-import 'MC' from '@twobirds/microcomponents';
-import 'Button' from 'tb/ui'; // made-up example library
-
-// select first button element in DOM
-let myButton = document.querySelector('button');
-
-// this will add the micro component to the myButton._mc property:
-MC.add( myButton, 'tb_ui_button', new Button( myButton, { ...config data } ) );
+// create the micro component class
+class MyMC extends MC{
+
+	constructor( target ){
+		super( target );
+		this.target = target;
+	}
+}
+
+const element = document.querySelector('div')
+
+// Add the top level microcomponent to the target element
+let mcc = MC.add(
+	element,
+	'myMC',
+	new MyMC( element )
+);
+
+// Add an inner (private) microcomponent to mcc
+let mcc.add(
+	'myInnerMC',
+	new MyMC( element )
+);
+
+console.log( element._mc );
+// { 'myMC': { target: (element) } }
+
+console.log( element._mc.myMC );
+// { target: (element) }
+
+console.log( mcc.siblings() );
+// [ { target: (element) } ]
 ```
 
 after:
@@ -75,29 +82,7 @@ after:
 ```
 _mc indicates that this HTML element contains at least one micro component. This is needed for the **selectors**.
 
-
-```javascript
-console.log( myButton._mc );
-// { tb_ui_button: { target: <button>, onClick: <function> } }
-```
-
-For detailed information jump to [Micro Component Usage](https://gitlab.com/twoBirds/microcomponents/-/blob/main/microcomponents_usage.md?ref_type=heads);
-
-## History
-
-I have been working with this since 2004. I used this as core principle inside my twoBirds framework.
-
-This functionality has been used in very big and complicated data processing projects:
-- to allow for web component like programming (as early as 2004)
-- to encapsule UI handling
-- to represent business processes and their tasks
-- and lately to compose very complex native web components from distinct modular functionality.
-
-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)
+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.
 
 ## 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"}