@twobirds/microcomponents 0.0.48 → 0.0.51

package/public/documentation/MC.md

@@ -1,256 +0,0 @@
-# Micro Components <span style="float:right; height:1em;"><img height="24px" src="./MicroComponents.svg" /></span>
-
-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 )
-
-# Usage
-
-- **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 (but don't have to) 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.
-
-# Rules
-
-- **Your own application code MUST NOT overwrite the properties and methods in the classes below.**
-- If you do it anyway, you do it on your own risk.
-
-# Not Exported
-
-## **McBase** Superclass
-
-  **Instance Properties**
-  - `.target`: readonly, a getter returning the DOM element or parent MC instance your instance resides in
-
-  **Constructor:**
-  - calls `init()`: triggers the 'init' lifecycle event, also recursively into the inner '._mc' structure.
-  - calls `autoAttachListeners()`: methods in your class code 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.
-
-- **Instance Methods:**
-  - `.trigger( eventName, data )`: runs callback methods.
-
-# Exported:
-
-## **MC** Class, extends McBase
-
-  **Instance Properties**
-  - `.target`: (inherited from McBase)
-  - `._mc`: a hash object that contains inner micro components
-
-- **Instance Methods:**
-  - `.trigger( eventName, data )`: (inherited from McBase)
-
-## **DC** Class, extends McBase
-
-- **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**
-  - `.target`: (inherited from McBase)
-  - `._mc`: a hash object that contains inner micro components
-
-- **Instance Methods:**
-  - `.parent(search?)`: Get parent DCs.
-  - `.ancestors(search?)`: Get ancestor DCs.
-  - `.children(search?)`: Get child DCs.
-  - `.descendants(search?)`: Get descendant DCs.
-  - `.trigger( eventName, data, bubble )`: trigger an event on "this", handles directional bubbling in the DOM.
-
-# Examples
-
-## 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**.
-
-### Attach 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 MyPublicClass( myElement ) );
-```
-
-#### **Hint**
-- After you added a micro component using this function, the **HTMLElement will contain a property `_mc`** which contains the MC instances visible in the DOM.
-- Also the **HTMLElement then has an attribute '_mc'** to indicate that at least one micro component is attached to this dom element.
-
-### Remove 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 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
-
-```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
-
-## Retrieve 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.**
-
-
-## Navigate 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');
-```
-
-## Retrieve 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 an Event
-```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 external 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 **MC** and **DC** instance, the Superclass McBase calls **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);
-	}
-
-	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>
-```
-# Lifecycle Events on **MC** and **DC**
-
-## Init
-- "this" first
-- traverses recursively into the _mc structure.
-- callbacks will be executed **asynchronous**.
-- requires **method .oneInit()** to be present in your class definition.
-
-## Destroy ( TBD )
-- deepest nested elements first.
-- callbacks will be executed **synchronous**.
-- then "this"
-- requires **method .oneDestroy()** to be present in your class definition.

package/public/documentation/elements.md

@@ -1,276 +0,0 @@
-# Custom Elements <span style="float:right; height:1em;"><img height="24px" src="https://gitlab.com/twoBirds/microcomponents/-/raw/main/MicroComponents.svg" /></span>
-
-Custom Elements provides two funktions:
-- **defineCE()** lets you define a custom tag and add functionality to it. Internally it uses [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define).
-- **getCE()** retrieves a custom element constructor from the web component registry via [CustomElementRegistry.get()](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/get).
-
-# Prerequisites
-
-You should at least know Micro Components **[DC](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/MicroComponents.md?ref_type=heads#dc-class-extends-mcbase)** superclass usage, since your own class code extends from it and uses its static functions. It is recommended that you have read and understood the **[Micro Component documentation](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/MicroComponents.md?ref_type=heads)**, since custom elements is just an extension that internally uses micro components.
-
-# Usage
-
-## Create a Custom Element
-
-Before:
-
-```html
-<body></body>
-```
-
-```javascript
-defineCE(
-	// equivalent to and internally using customElementRegistry.define()
-	"my-tag",
-	class MyTag extends DC {
-
-		constructor(target, data = {} ) {
-			super(target);
-			this.data = data;
-			target.innerHTML = "Hello World";
-		}
-	}
-);
-
-let MyTag = getCE("my-tag"),
-	data = { a: 1 },
-	myTag = new MyTag( data );
-
-/*
-HINT:
-At this point the web component is not yet attached to the DOM.
-But you can perform any operation on it, e.g. calling methods on its inner micro components.
-*/
-
-document.body.append( myTag );
-```
-
-After:
-```html
-<body>
-	<my-tag _mc>Hello World</my-tag>
-</body>
-```
-
-### **Hints**
-- Your code extends the **[DC](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/MicroComponents.md?ref_type=heads#dc-class-extends-mcbase)** superclass. This superclass provides methods to traverse the DOM and select other micro components contained in HTML elements.
-- it is essential to understand that your web component code is only one of the numerous micro components that can reside inside `<my-tag>`
-- After you created a custom element, the custom element will contain a **property `<my-tag>._mc`** which contains your class instance.
-- Also the custom element then has an **attribute '_mc'** which will indicate that at least one micro component is attached to it.
-- Note that you can hand over data natively via parameters, when handling custom elements in above way.
-- The native way of usage, simply adding the tag to the template, is still possible. You have to use attributes then to hand in data.
-
-
-## Web Component Lifecycle Events
-
-```javascript
-defineCE(
-	"my-tag",
-	class MyTag extends DC {
-
-		constructor(target) {
-			super(target);
-			target.setAttribute('my-attribute', 'change me');
-		}
-
-		/*
-		web component specific event handlers
-		*/
-
-		onConnected(ev) {
-			console.info("MyTag .onConnected() handler", ev);
-		}
-
-		onAttributeChanged(ev) {
-			console.info("MyTag .onAttributeChanged() handler", ev);
-		}
-
-		onAdopted(ev) {
-			console.info("MyTag .onAdopted() handler", ev);
-		}
-
-		onDisconnected(ev) {
-			console.info("MyTag .onDisconnected() handler", ev);
-		}
-	},
-	['my-attribute'] // DOM node attributes to observe
-);
-
-let MyTag = getCE("my-tag"),
-	myTag = new MyTag();
-
-document.body.append( myTag );
-```
-
-You can use your Web Component constructor to add other modules to the `<my-tag>` DOM node:
-
-```javascript
-
-class OtherModule extends DC {
-
-	constructor(target) {
-		super(target);
-	}
-
-	onConnected(ev) {
-		console.info("[OtherModule] .onConnected() handler", ev);
-	}
-}
-
-defineCE(
-	"my-tag",
-	class MyTag extends DC {
-
-		constructor(target) {
-			super(target);
-			DC.add( target, 'otherModule', new OtherModule(target) );
-			// equivalent:
-			// target._mc.otherModule = new OtherModule(target);
-		}
-
-		onConnected(ev) {
-			console.info("[MyTag] .onConnected() handler", ev);
-		}
-	}
-);
-
-
-let MyTag = getCE("my-tag");
-
-document.body.append( new MyTag() );
-```
-
-### **Hints**
-- You can add as many other micro components to the DOM node as you like.
-- The native web component lifecycle events will be triggered on **all** micro components.
-- The event parameter handed over is an internal event instance, that contains the original native event in its `data` property.
-
-## Native Event Handlers
-
-Native event handlers will be auto-attached, when the method name follows one of these two schemes:
-
-- **on[A-Z]...**: e.g. **onClick(){ ... }** will be called when the native event is triggered
-- **one[A-Z]...**: e.g. **oneClick(){ ... }** will be called **once** only when the native event is triggered. Subsequent events will be ignored.
-
-```javascript
-defineCE(
-	"my-tag",
-	class MyTag extends DC {
-
-		constructor(target) {
-			super(target);
-			target.innerHTML = "Click Me";
-		}
-
-		/*
-		native event handlers
-		*/
-		onClick(ev) {
-			console.info("MyTag .onClick() handler", ev);
-		}
-	}
-);
-
-let MyTag = getCE("my-tag");
-
-document.body.append( new MyTag() );
-```
-
-### **Hints**
-- The native web component lifecycle events will be triggered on **all** micro components contained in the custom element, provided the MC contains a matching named handler.
-- The event parameter handed over is an internal event instance, that contains the original native event in its .data property.
-
-## Lifecycle Event Handlers
-
-Currently there is only one lifecycle event handler: the **oneInit(){ ... }** method you provide with your class.
-
-This method is triggered asynchronous via a timeout after you made a new instance of your class.
-
-```javascript
-defineCE(
-	"my-tag",
-	class MyTag extends DC {
-
-		constructor(target) {
-			super(target);
-			target.innerHTML = "Hello World";
-		}
-
-		/*
-		lifecycle event handlers
-		*/
-		oneInit(ev) {
-			console.info("MyTag .onInit() handler", ev);
-		}
-	}
-);
-
-let MyTag = getCE("my-tag");
-
-document.body.append( new MyTag() );
-```
-
-### **Hints**
-- The native web component lifecycle events will be triggered on **all** micro components contained in the custom element, provided the specific micro component contains a matching named handler.
-- The event parameter handed over is an internal event instance that contains no data.
-
-## Custom Events
-
-```javascript
-defineCE(
-	"my-tag",
-	class MyTag extends DC {
-
-		constructor(target) {
-			super(target);
-			target.innerHTML = "Hello World";
-		}
-
-		/*
-		custom event handlers
-		*/
-		onSpecialEvent(ev) {
-			console.log('MyTag .onSpecialEvent() handler', ev);
-		}
-	}
-);
-
-let MyTag = getCE("my-tag");
-
-document.body.append( new MyTag() );
-
-document
-	.querySelector( 'my-tag' )
-	?._mc
-	.MyTag
-	.trigger('specialEvent');
-
-/*
-Alternatives:
-*/
-
-document
-	.querySelector( 'my-tag' )
-	?._mc
-	.trigger('specialEvent'); // ...on all micro components contained in <my-tag>
-
-/*
-traversing the DOM:
-<my-tag>
-	<my-inner-tag />
-</my-tag>
-*/
-
-// <my-tag> method:
-onSpecialEvent(ev){
-	console.log( ev.data );
-}
-
-// <my-inner-tag> method:
-sendSpecialEvent(){
-	this.trigger( 'specialEvent', "Hello World", 'u' ); // 'u' = bubble up.
-}
-```
-
-### **Hints**
-- The event parameter handed over is an internal event instance, that contains the payload in its .data property.

package/public/documentation/functional_requirements.md

@@ -1,8 +0,0 @@
-## 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**.