@twobirds/microcomponents 0.0.6 → 0.0.8

package/README.md

@@ -2,12 +2,37 @@
 
 ![Micro Components Logo](https://gitlab.com/twoBirds/microcomponents/-/raw/main/MicroComponents.svg)
 
+**This code aims at improving Javascript modularity and encapsulation**.
+
+Importing a custom MC in your client side code:
+```javascript
+import MyButton from '@mySampleLib/Button';
+```
+... is equivalent to:
+```javascript
+npm i @mySampleLib/Button;
+```
+... on the server side.
+
+Imagine mc_modules to like a "node_modules" directory attached to a DOM node (instanceof HTMLElement).
+
+**On the client side** MCs reside inside DOM nodes in a "_mc" property, or inside each other recursively. Usually they provide a direct interface to their inner code.
+
+**On the server side** MCs can be used to organize your code, too.
+
 ## Status
-WIP. Should be tested and done soon.
+WIP. Micro components should be done soon, as in days.
 
-## General
+## Disclaimer
+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. Later this will be backported into twoBirds as a dependency, and twoBirds will become completely modularized on the base of MCs.
+
+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**, in comparision, **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, and MCs in it. But you will want to migrate it ASAP, since MCs work with any FW.
 
-This code aims at improving Javascript modularity. It does not describe a specific Micro Component itself but rather describes they way they are **organized**.
+## General
 
 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).
 
@@ -21,69 +46,75 @@ Or read the more detailed [jsdoc API documentation](http://twobirds.gitlab.io/mi
 
 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
-
-- 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**.
-
-
 ## Simple Usage:
 
 **Micro Components** can be added to to a DOM element like this:
 
 before:
 ```HTML
-<button></button>
+<div></div>
 ```
 
-code: (assume "Button" is some class in a library)
-```javascript
-// create the micro component class
+code:
+```typescript
+// create an inner micro component class
+class MyInnerMC extends MC{
+
+	constructor( target ){
+		super( target );
+	}
+
+	doSomething(){
+		console.log( this, 'something done' )
+	}
+}
+
+// create a custom micro component class
 class MyMC extends MC{
 
+	private myInner: MyInnerMC;
+
 	constructor( target ){
 		super( target );
 		this.target = target;
+
+		//add a private inner micro component
+		this.myInner = new MyInnerMC( target );
+
+		//add a public micro component
+		this.add(
+			'myPublicInnerMC',
+			new MyInnerMC( target )
+		);
 	}
 }
 
+// get some element from the DOM
 const element = document.querySelector('div')
 
-// Add the top level microcomponent to the target element
-let mcc = MC.add(
+// Add the custom micro component instance to the target element
+let topLevelMC = 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) } }
+// { 'myMC': { target: (element), _mc: { myPublicInnerMC: {...} } } }
 
 console.log( element._mc.myMC );
-// { target: (element) }
+// { target: (element), _mc: { myPublicInnerMC: {...} } }
 
-console.log( mcc.siblings() );
-// [ { target: (element) } ]
+console.log( topLevelMC.siblings() );
+// [ { target: (element), _mc: { myPublicInnerMC: {...} } } ]
 ```
 
 after:
 ```HTML
-<button _mc></button>
+<div _mc></button>
 ```
 _mc indicates that this HTML element contains at least one micro component. This is needed for the **selectors**.
 
-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/microcomponents_functional_requirements.md

@@ -0,0 +1,8 @@
+## Functional Requirements
+
+- I want to **enrich a standard HTMLElement instance or any object 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**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twobirds/microcomponents",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Micro Components Organization Class",
   "main": "microcomponents.js",
   "sideEffects": false,