@twobirds/microcomponents 0.1.0 → 0.1.2

package/assets/documentation/elements.md

@@ -1,277 +0,0 @@
-![logo](./MicroComponents.svg)
-
-# Custom Elements
-
-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
-// customElementRegistry.define() wrapper
-defineCE(
-	"my-tag", // tag name
-	class MyTag extends DC { // definition class
-
-		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 data-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 `_mc`** which contains your class instance.
-- Also the custom element then has an **attribute `data-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
-// customElementRegistry.define() wrapper
-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"), // customElementRegistry.get("my-tag")
-	myTag = new MyTag(); // programmatically create a custom element instance
-
-document.body.append( myTag );
-```
-
-## Composition with Micro Components
-
-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 CustomEvent instance, that contains the original native event in its `detail` property.
-
-## Native HTMLElement 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.
-
-# 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.
-
-# 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' )
-	.dispatchEvent('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/assets/documentation/formvalues.md

@@ -1,25 +0,0 @@
-![logo](./MicroComponents.svg)
-
-# Form Values
-
-This module provides a way to bind form input elements (text, radio, checkbox, select, textarea) to a JavaScript object, enabling two-way data binding and change observation.
-
-## formValues Function
-Binds form elements to a target object:
-```ts
-formValues(targetObject: LooseObject, propertyName: string, dom: HTMLElement | ShadowRoot)
-```
-
-Example code in constructor
-```ts
-    constructor(target: HTMLElement) {
-        super(target);
-
-        let shadow = (that as DC).target.attachShadow({ mode: 'open' });
-        shadow.innerHTML = `<style>${this.css}</style>${this.template}`;
-
-        formValues(that, 'data', shadow); // create this.data formdata observable
-
-    }
-```
-Full example [here](https://gitlab.com/twoBirds/microcomponents/-/blob/main/src/test/test/testform.ts?ref_type=heads).

package/assets/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**.