@twobirds/microcomponents 0.0.21 → 0.0.23

package/.gitlab-ci.yml

@@ -5,6 +5,7 @@ before_script:
   - npm i
 pages:
   script:
+    - npm run typedoc
     - npm run build
   artifacts:
     paths:

package/README.md

@@ -4,25 +4,44 @@
 
 **This code aims at improving Javascript modularity and encapsulation**.
 
-The MC() class acts as a **Javascript repository on a DOM node** and as a **selector and communication tool across the DOM**.
-
-Using micro components enforces **DRY, KISS and SOLID** principles in Javascript programming. Read this [RFC](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/proposal_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/assets/documentation/why.md?ref_type=heads).
+Using micro components enforces **DRY, KISS and SOLID** principles in Javascript programming.
 
 ## Status
-WIP. Should be done soon. In [manual testing](http://twobirds.gitlab.io/microcomponents/test.html), also working a lot on the documentation.
 
-## 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.
+**WIP**. Should be done soon. In [manual testing](http://twobirds.gitlab.io/microcomponents/test.html), also working a lot on the documentation.
+
+## Skippable Disclaimer
+I decided to extract this functionality from the [twoBirds framework](https://www.npmjs.com/package/twobirds-core), because it is a useful tool in itself and it is framework agnostic. It relies solely on the standard DOM and native javascript or typescript.
+
+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/assets/documentation/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://www.gofundme.com/f/nachhaltige-programmierung). 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 open source 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.
 
 ## 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. The latter is WIP, backporting is currently last on my list.
+**This is a low-level OOP approach to Javascript programming.**
+
+It aims at proving that strict OOP is a valid alternative to other frameworks functional approaches.
+
+You can use it in vanilla JS or Typescript coding environments. It has been used to create very complex single page applications.
+
+Also you can use it in any other framework to enhance it with missing functionality.
+
+This functionality is **portable**, so you can **reuse your MCs** - e.g. originally written in the context of an **Angular** project - in your next **react** project right away.
+
+In its core it consists of a two classes named **MC** and **DC**. Your class code extends from one of these classes.
+
+This repository exports 5 independent functionalities:
+
+1. **[Micro Components](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/MicroComponents.md?ref_type=heads)** contains the **MC** and **DC** classes you can use as super classes.
+2. **Custom Elements** lets you define and retrieve your own custom elements based on your DC instance code. Uses and re-exports (1).
+3. **Convenience Observables** adds observability and run time type safety to object properties.
+4. **Form Values** gives you 2-way binding between a HTML form and an observable.
+5. (tbd) **Convenience Selectors** provide jQuery like selectors for both the DOM and micro components.
 
-For a short usage description goto [Micro Component Usage](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/usage.md?ref_type=heads).
+Also there is a bundle file that contains all of the above.
 
-Check the [typedoc API reference](http://twobirds.gitlab.io/microcomponents/classes/microcomponents.MC.html) if you want to drill into the source code.
+Check the [typedoc API reference](https://twobirds.gitlab.io/microcomponents/modules.html) if you want to drill into the source code.
 
 To see what can be done, go to [additional concepts](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/magic.md?ref_type=heads) which shows what it already has been used for.
 
@@ -38,7 +57,7 @@ before:
 code:
 ```typescript
 // create a custom micro component class
-class MyMC extends MC{
+class MyMC extends DC{
 
 	constructor( target ){
 		super( target );
@@ -54,7 +73,7 @@ class MyMC extends MC{
 const element = document.querySelector('div')
 
 // Add the custom micro component instance to the target element
-MC.add(
+DC.add(
 	element,
 	'myMC',
 	new MyMC( element )
@@ -73,7 +92,7 @@ after:
 ```
 _mc indicates that this HTML element contains at least one micro component. This is needed for the selectors.
 
-the _mc attribute and properties are the only interference with the DOM, so every other system should be happy to work with this.
+The _mc attribute and properties are the only interference with the DOM, so every other system should be happy to work with this.
 
 ## Contact
 Feel free to contact me for any questions or inquiries:

package/assets/documentation/MicroComponents.md

@@ -0,0 +1,228 @@
+# Micro Components
+
+This system allows you to to define **Micro Components** and attach them to DOM elements or other Micro Components.
+
+The module exports 2 classes:
+- **MC**: Micro Component ( not DOM related, works on the server also )
+- **DC**: Dom Component ( extends MC and adds DOM related methods, client only )
+
+## tldr;
+
+In general when coding with this system, you create classes that extend either the **DC** or **MC** class provided here.
+
+**If your functionality needs to access the DOM**, e.g. to find other DC instances, **your class extends DC**.
+
+**Otherwise** - and always on the server - **your class extends MC**.
+
+In any case, your class instances will contain a property **"_mc"** where you can put in other MCs.
+
+Also your class instances will have a readonly **"target"** property that is back reference to the instance they are contained in.
+
+- if your class extends **DC: "target"** will refer the **DOM HTMLElement your instance resides in**.
+- if your class extends **MC: "target"** will refer the **parent MC your instance resides in**.
+
+As an application programmer you should understand **MC** and **DC** methods and the structure they provide:
+- **MC** encapsule functionality in a reusable way. Think DRY, and SOLID because we talk about objects.
+- **MC** can use observables to provide data driven workflow between multiple MCs.
+- **DC** use observables and formValues to provide 1-way and 2-way binding to the DOM.
+- **DC** have selectors to find other DCs in the DOM.
+
+## MC() Class overview
+
+  **Instance Properties**
+  - `.target`: readonly, a getter returning the DOM element or parent MC instance your instance resides in
+  - `._mc`: a hash object that contains inner micro components
+
+- **Instance Methods:**
+  - `.trigger( eventName, data )`: trigger an event on this instance
+
+## DC() Class Overview
+
+- **Static Methods:**
+  - `DC.add( DomElement, key, mc)`: Add a DC to an HTMLElement.
+  - `DC.remove( DomElement, key )`: Remove a DC from an HTMLElement.
+  - `DC.trigger( eventName, DomElement, data, bubble )`: trigger an event, handles directional traversal in the DOM.
+
+  **Instance Properties**
+
+    ( inherited from MC )
+  - `.target`: readonly, a getter returning the DOM element the instance resides in
+  - `._mc`: a hash object that contains inner MCs
+
+- **Instance Methods:**
+  - `.parent(search?)`: Get parent DCs.
+  - `.ancestors(search?)`: Get ancestor DCs.
+  - `.children(search?)`: Get child DCs.
+  - `.descendants(search?)`: Get descendant DCs.
+  - `.autoAttachListeners()`: methods in your MC that start with "on[A-Z]" or "one[A-Z]" and describe native DOM events (e.g. "onClick") will be added to the DOM Element as listeners.
+
+    (inherited from MC )
+  - `.trigger( eventName, data, bubble )`: trigger an event on "this", handles directional bubbling in the DOM.
+
+### Typical Workflow
+
+1. **Attach DCs** to HTMLElements using `DC.add()`.
+2. **Access** other DCs by their property key or navigating through DOM (e.g., `ancestors()`, `children()`, etc.) **and use their inner functionality**.
+
+# Attaching Micro Components to a DOM element
+
+To attach a micro component to an HTML element, use the `DC.add()` static function.
+
+```javascript
+const myElement = document.getElementById('myDiv');
+
+/*
+usage with classes, both PUBLIC and PRIVATE
+*/
+
+// internal MC class
+MyInnerClass = class extends MC{
+  constructor(target){
+  }
+}
+
+// external DC class
+MyPublicClass = class extends DC{
+  constructor(target){
+    // add a internal inner MC
+    this._mc.myInnerComponent = new MyInnerClass( this );
+  }
+}
+
+// attach a DC
+DC.add( myElement, 'myDcComponent', new MyClass( myElement ) );
+```
+
+- After you added a micro component using this function, the **HTMLElement will contain a property `_mc`** which contains the external MC instances.
+- Also the **HTMLElement then has an attribute '_mc'** which will indicate that at least one micro component is attached to this dom element.
+
+# Removing a top level Micro Component from a DOM element
+
+Micro components can be removed using the `DC.remove()` static method.
+
+```javascript
+DC.remove( myDomElement, 'myComponent');
+```
+
+**When all micro components are removed** (the _mc object has no more properties), the **`_mc` attribute is also removed** from the HTML element.
+
+# Retrieve all top level Micro Components from a DOM element
+
+```javascript
+const target = document.querySelector( 'div' );
+console.log(target._mc);
+```
+
+To retrieve a specific micro component by its key:
+```javascript
+const target = document.querySelector( 'div' );
+const specificInstance = target._mc?.myPublicComponent;
+console.log(specificInstance);
+```
+
+### Trigger an Event on all DCs
+
+```javascript
+const target = document.querySelector( 'div' );
+DC.trigger( target, '<eventName>', data | null, bubble );
+
+// bubble is any combination of 'lud', meaning [local|up|down]
+// local is only "this", "up" traverses towards root, "down" traverses the inner DOM.
+```
+
+# Methods you can use in your Micro Component Instances
+
+## Retrieving Inner Micro Components
+
+You can retrieve an inner micro component by using the ._mc property.
+
+```javascript
+const innerComponent = this._mc.myInnerComponent;
+console.log(innerComponent);
+```
+
+**The following methods hop over HTMLElements that DO NOT contain micro components.**
+
+
+## Navigating Parent and Ancestor Micro Components
+
+The `.parent()` and `.ancestors()` methods allow you to retrieve micro components attached to parent elements.
+
+```javascript
+const parentMcs = this.parent();
+console.log(parentMcs);  // all micro components of the closest ancestor that has an _mc attribute
+
+const allAncestorsMcs = this.ancestors();
+console.log(allAncestorsMcs);  // all ancestor micro components up to document root.
+```
+
+To retrieve specific micro component(s) attached to ancestors:
+```javascript
+const specificAncestorMc = this.ancestors('myComponent');
+```
+
+## Retrieving Child and Descendant Micro Components
+
+The `.children()` and `.descendants()` methods retrieve micro components attached to child elements or any descendants.
+```javascript
+const childComponents = this.children();
+console.log(childComponents);  // an array of nearest micro components in the inner DOM
+
+const descendantComponents = this.descendants();
+console.log(descendantComponents);  // an array of all descendant micro components in the inner DOM
+
+//To search for a specific micro component by key:
+const specificMcs = this.descenants('specificMc');
+```
+
+### Trigger Events on MCs
+```javascript
+// trigger an event on yourself
+this
+  .trigger('myEvent', data); // calls the "onMyEvent" callback
+
+// trigger an event on your external siblings
+DC
+  .trigger( this.target, 'myEvent', data); // calls the "onMyEvent" callback on all externalh MCs that listen to it
+
+// trigger an event on some remote DOM instance(s)
+DC
+  .trigger(
+    this.target, // the DOM node your are in
+    'myEvent', // event name
+    null, // no data
+    'd' // into descendants
+  ); // calls the "onMyEvent" callback
+
+// trigger an event on some remote DC instance that you know the name of
+this
+  .descendants('myRemoteInstance') // into my inner HTML
+  ?.[0] // hopefully we found one
+  .trigger(
+    'myEvent', // event name
+    null, // no data
+  );
+```
+
+## Automatically attach Listener Methods to the DOM
+
+On any **DC** instance, you can call **.autoAttachListeners()** in the constructor.
+
+Any methods you define in your code that start with **"on"** or **"one"**, and also match DOM event names, will be called accordingly:
+
+```javascript
+class MyEventTarget extends MC {
+	constructor(target) {
+		super(target);
+		this.autoAttachListeners();
+	}
+
+	onClick(ev) {
+		console.log("onClick", ev);
+	}
+}
+
+let myFirstDiv = document.querySelector('div');
+DC.add( myFirstDiv, 'myEventTarget', new MyEventTarget( myFirstDiv ) );
+// now wait for somebody to click on that <div>
+```

package/assets/my-tag.css

@@ -0,0 +1,4 @@
+my-tag {
+	border: 2px solid gray;
+	padding: 2px 5px;
+}

package/assets/test.html

@@ -4,8 +4,12 @@
             <meta charset="UTF-8">
             <meta name="viewport" content="width=device-width, initial-scale=1.0">
             <title>Micro Components Manual Test</title>
+            <link rel="icon" type="image/svg+xml" sizes="any" href="MicroComponents.svg" />
+            <link href="./my-tag.css" rel="stylesheet" />
+            <script type="module" src="./test.js"></script>
+            <script src="./customSelectors.min.js"></script>
         </head>
     <body>
-        <script  type="module" src="./test.js"></script>
+        Open the debugger, read console, then:&nbsp;
     </body>
 </html>

package/dist/MC.d.ts

@@ -0,0 +1,32 @@
+import { LooseObject } from './helpers.js';
+import { McEvent } from './McEvent.js';
+export interface HTMLMcElement extends HTMLElement {
+    _mc: LooseObject;
+}
+declare function addListener(domNode: Node, eventName: string, handler: EventListenerOrEventListenerObject | null, capture?: boolean, once?: boolean): void;
+declare function removeListener(domNode: Node, eventName: string, handler: EventListenerOrEventListenerObject | null): void;
+declare class McBase {
+    #private;
+    constructor(target: {
+        [key: string]: any;
+    });
+    get target(): any;
+}
+declare class MC extends McBase {
+    constructor(target: any);
+    trigger(ev: McEvent | string, data?: any, bubble?: string): this | undefined;
+}
+declare class DC extends MC {
+    constructor(target: HTMLElement);
+    static debug: boolean;
+    static add: Function;
+    static remove: Function;
+    static trigger: Function;
+    parent(search?: string): any[];
+    ancestors(search?: string): any[];
+    children(search?: string): any[];
+    descendants(search?: string): any[];
+    autoAttachListeners(): void;
+}
+export { addListener, removeListener, McBase, MC, DC, McEvent };
+//# sourceMappingURL=MC.d.ts.map

package/dist/MC.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MC.d.ts","sourceRoot":"","sources":["../src/MC.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAWvC,MAAM,WAAW,aAAc,SAAQ,WAAW;IACjD,GAAG,EAAE,WAAW,CAAC;CACjB;AA6CD,iBAAS,WAAW,CAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,kCAAkC,GAAG,IAAI,EAAE,OAAO,GAAE,OAAe,EAAE,IAAI,GAAE,OAAe,QAe1J;AAED,iBAAS,cAAc,CAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,kCAAkC,GAAG,IAAI,QAE5G;AA2DD,cAAM,MAAM;;gBAME,MAAM,EAAE;QAAE,CAAC,GAAG,EAAC,MAAM,GAAG,GAAG,CAAA;KAAE;IAc1C,IAAI,MAAM,IAAI,GAAG,CAEhB;CAED;AAED,cAAM,EAAG,SAAQ,MAAM;gBACV,MAAM,EAAE,GAAG;IAYvB,OAAO,CAAE,EAAE,EAAE,OAAO,GAAG,MAAM,EAAE,IAAI,GAAE,GAAQ,EAAE,MAAM,CAAC,EAAE,MAAM;CAgF9D;AAED,cAAM,EAAG,SAAQ,EAAE;gBACN,MAAM,EAAE,WAAW;IAI/B,MAAM,CAAC,KAAK,EAAE,OAAO,CAAS;IAE9B,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAO;IAC3B,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAU;IACjC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAW;IAEnC,MAAM,CAAC,MAAM,GAAE,MAAW,GAAG,GAAG,EAAE;IAMlC,SAAS,CAAC,MAAM,GAAE,MAAW,GAAG,GAAG,EAAE;IAMrC,QAAQ,CAAC,MAAM,GAAE,MAAW,GAAG,GAAG,EAAE;IAYpC,WAAW,CAAC,MAAM,GAAE,MAAW,GAAG,GAAG,EAAE;IAOvC,mBAAmB;CA6CnB;AAED,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC"}