@twobirds/microcomponents 0.0.84 → 0.0.86

package/public/MC.ts

@@ -2,7 +2,7 @@
 
 import { LooseObject } from './helpers.js';
 
-var isBrowser = new Function(
+const isBrowser = new Function(
 	'try {return this===window;}catch(e){ return false;}'
 );
 
@@ -21,61 +21,17 @@ export interface HTMLMcElement extends HTMLElement {
 	_mc: LooseObject;
 }
 
-// get all microcomponents from a list of HTMLElements
-function getMicroComponents(elements: any[], search: string): any[] {
-	let mcValues: any[] = [];
-
-	elements.forEach((e) => {
-		if (e) {
-			if (e instanceof HTMLElement) {
-				const _mc = (e as any)?._mc;
-				if (!search && _mc) {
-					mcValues = mcValues.concat(Object.values((e as any)._mc));
-				} else if (search && _mc && _mc[search]) {
-					mcValues.push(_mc[search]);
-				}
-			}
-		}
-	});
-	return mcValues;
-}
-
-// get all ancestor DOM nodes up to the document root
-function traverseNodes(
-	node: { [key: string]: any },
-	search: string,
-	firstonly = true
-): any[] {
-	let mcValues: any[] = [];
-	while (node) {
-		if (node._mc) {
-			if (!search) {
-				mcValues = mcValues.concat(Object.values(node._mc));
-			} else if (search && node._mc[search]) {
-				mcValues.push(node._mc[search]);
-			}
-			if (firstonly) return mcValues;
-		}
-		node = node.parentNode;
-	}
-	return mcValues;
-}
-
 function isDOM(element: { [key: string]: any }) {
 	return element && element instanceof HTMLElement;
 }
 
 // add a microcomponent to a target DOM node
-function add(target: HTMLElement, key: string, element = {}): any {
+function add( target: HTMLElement, key: string, element: any = {} ): HTMLMcElement {
 	let node = target as HTMLMcElement;
 
 	// create the _mc property if necessary
 	if (!node._mc) {
-		let debug = (DC as any)?.debug;
-		(DC as any).debug = false;
 		node._mc = new (DC as any)(target);
-		(DC as any).debug = debug;
-		delete node._mc._mc; // NOT NEEDED on the top level _mc property of a DOM HTMLElement
 	}
 
 	const _mc = node._mc;
@@ -88,7 +44,8 @@ function add(target: HTMLElement, key: string, element = {}): any {
 			target.setAttribute('data-mc', '');
 		}
 	}
-	return element;
+
+	return node;
 }
 
 // remove a micro component from the DOM
@@ -114,27 +71,14 @@ function remove(target: HTMLMcElement, key: string) {
 }
 
 // run the "init" lifecycle event on the complete _mc structure
-function init(element: MC | DC) {
-	if (element.constructor === DC) return;
-
+function init(element: DC) {
 	setTimeout(() => {
+		if (element.constructor === DC) return;
 		element.trigger('Init');
-		/*
-			let keys = Object.keys( ( element as any)?._mc );
-			if ( keys.length ){
-				//console.log( 'inner Inits on [', mc.constructor.name, ']', keys );
-				keys?.forEach( (key: string) => {
-					let mc = ( element as any)?._mc?.[key];
-					//console.log( key, typeof mc?.oneInit, mc );
-					if ( ( mc as any )['oneInit'] &&  typeof ( mc as any ).oneInit == 'function' ){
-						( mc as any ).oneInit( new McEvent('Init') );
-					}
-				});
-			};
-			*/
 	}, 0);
 }
 
+// 'eventName' => '_mcEventName'
 function getMcEventName( eventName: string ): string {
 	return '_mc' + eventName[0].toUpperCase() + eventName.substring(1);
 }
@@ -156,8 +100,8 @@ function one( domNode: Node, eventName: string, handler: EventListenerOrEventLis
 
 // create and dispatch custom event
 function trigger( 
-	domNode: HTMLElement, 
-	event: CustomEvent | string, 
+	domNode: HTMLElement,
+	event: CustomEvent | string,
 	data: any = {},
 	bubble: string = 'l'
 ){
@@ -199,7 +143,7 @@ function bubbleEvent( domNode: HTMLElement, ev: CustomEvent) {
 					.map((c: unknown) => (c as any)?.target)
 			);
 			targets.forEach((target: HTMLMcElement) => {
-				if (target) DC.trigger(target, ev);
+				if (target) target._mc.trigger(target, ev);
 			});
 		}
 
@@ -224,41 +168,44 @@ function autoAttachListeners(element: MC | DC) {
 					withoutOnOne = key.replace(/^on[e]{0,1}/, ''), // preserves upper/lowercase for non-native events
 					nativeEventName = withoutOnOne.toLowerCase();  // lowercase for native event names
 
-				let listener = (ev: Event | CustomEvent) => {
-					that[key]( ev );
-				}
-					
-				if ( !!( target as any )['on' + nativeEventName] ) {
-					// it is a native HTML event
-					//console.log( 'AAL: attach native event listener', nativeEventName, 'to', target );
-					target.addEventListener( nativeEventName, listener);
-				} else {
-					// it is a customEvent
-					//console.log( 'AAL: attach custom event listener', '_mc' + withoutOnOne , 'to key', key, 'in', element );
-					on( target, withoutOnOne, listener, once );
+				if ( ('on' + nativeEventName) in target ) { // it is a native HTML event
+					let listener = (ev: Event) => {
+						that[key]( ev );
+					}
+					// console.log( 'AAL: attach native event listener', nativeEventName, 'to', target );
+					target.addEventListener( nativeEventName, listener );
+				} else { // it is a customEvent
+					// console.log( 'AAL: attach custom event listener', '_mc' + withoutOnOne , 'to key', key, 'in', element );
+					let listener = (ev: CustomEvent) => {
+						that[key]( ev );
+					}
+					on( target, withoutOnOne, listener as EventListenerOrEventListenerObject, once );
 				}
 			});
 	}
 }
 
-function getMcChildNodes(domNode: HTMLElement): NodeListOf<Element> {
+function getMcChildNodes(domNode: HTMLElement): DC[] | null {
 	const id = Math.random().toString().replace('.', '');
 	const selector = '[data-mc]:not([temp_id="' + id + '"] [data-mc] [data-mc])';
 	domNode.setAttribute('temp_id', id);
-	const myDomElements = domNode.querySelectorAll(selector);
+	const mcArray: unknown[] = 
+		( [ ...domNode.querySelectorAll(selector) ] as HTMLMcElement[])
+			.filter( (e) => !!e._mc )
+			.map( e => e._mc );
 	domNode.removeAttribute('temp_id');
-	return myDomElements;
+	return mcArray.length ? mcArray as DC[] : null;
 }
 
 class McBase {
 	private _target: WeakRef<any>; // avoid circular reference
 
-	constructor(target?: { [key: string]: any }, debug: boolean = false) {
+	constructor(target?: { [key: string]: any } ) {
 		let element = this as unknown as MC | DC;
 
 		this._target = new WeakRef(target || {});
 
-		init(element); // async lifecycle event
+		init(element as DC); // async lifecycle event
 
 		autoAttachListeners(element);
 	}
@@ -273,12 +220,6 @@ class MC extends McBase {
 	constructor(target?: any) {
 		super(target);
 	}
-
-	static trigger = trigger;
-	
-	trigger(ev: string, data: any = {}, bubble: string = 'l') {
-		// TBD
-	}
 }
 
 class DC extends McBase {
@@ -288,8 +229,8 @@ class DC extends McBase {
 
 	static add: Function = add;
 	static remove: Function = remove;
-	static trigger: Function = trigger;
 
+	/* event handling */
 	off( eventName: string, handler: EventListenerOrEventListenerObject ) {
 		off( this.target, eventName, handler );
 	}
@@ -302,45 +243,57 @@ class DC extends McBase {
 		one( this.target, eventName, handler );
 	}
 
-	trigger(ev: CustomEvent | string, data: any = {}, bubble: string = 'l') {
-		if ( typeof ev === 'string' ){
-
-		}
-		//trigger( this.target, ev, data, bubble);
+	trigger( eventName: string, data: any = {}, bubble: string = 'l') {
+		trigger( this.target, eventName, data, bubble);
 	}
 
-	parent(search: string = ''): any[] {
-		let target: HTMLElement = (this as any).target;
-		if (!isDOM(target)) return [];
-		return traverseNodes((target as any).parentNode, search, true);
+	/* DOM traversal */
+	parent(): DC | null {
+		let 
+			target: HTMLElement = (this as DC).target;
+		if (!isDOM(target)) return null;
+		return (target.closest('[data-mc]') as HTMLMcElement)?._mc as DC || null;
 	}
 
-	ancestors(search: string = ''): any[] {
-		let target: any = (this as any)?.target;
-		if (!isDOM(target)) return [];
-		return traverseNodes((this as any).target.parentNode, search, false);
+	ancestors(): DC[] | null {
+		let 
+			currentNode: HTMLElement | null = (this as DC)?.target as HTMLMcElement,
+			result: DC[] = [];
+
+		if (!isDOM( currentNode )) return [];
+
+		while ( currentNode = (currentNode.closest('[data-mc]') ) ){
+			if ( (currentNode as HTMLMcElement)?._mc ){
+				result.push( (currentNode as HTMLMcElement)?._mc as DC );
+			}
+		}
+
+		return result.length ? result : null;
 	}
 
-	children(search: string = ''): any[] {
+	children(): DC[] | null {
 		let target: any = (this as any)?.target;
-		if (!isDOM(target)) return [];
-		const myDomElements = getMcChildNodes(target);
-		const mcValues = getMicroComponents([...myDomElements], search);
-		return mcValues;
+		if (!isDOM(target)) return null;
+		return getMcChildNodes(target);
 	}
 
-	descendants(search: string = ''): any[] {
-		let target: any = (this as any)?.target;
+	descendants(): DC[] | null {
+		const target: any = (this as DC)?.target;
 		if (!isDOM(target)) return [];
-		const myDomElements = target.querySelectorAll('*[data-mc]');
-		return getMicroComponents([...myDomElements], search);
+		const mcArray: unknown[] = 
+			( [ ...target.querySelectorAll( '[data-mc]' ) ] as HTMLMcElement[])
+				.filter( (e) => !!e._mc )
+				.map( e => e._mc );
+		return mcArray.length ? mcArray as DC[] : null;
 	}
 }
 
+/*
+Autoload Section...
+*/
+
 const loadingDCs = new Set<string>();
 
-// this only applies to DCs defined in the data-mc attribute, 
-// since they need to be attached manually
 function attachDC(element: string): Function {
 
 	//@ts-ignore

package/public/documentation/MC.md

@@ -68,27 +68,43 @@ A special property attached to `HTMLElement` instances (when using `DC.add`) or
 
 Each microcomponent instance has a read-only `target` property providing a back-reference:
 
-- If the instance extends **`DC`** and was added via `DC.add`, `target` refers to the **DOM HTMLElement** it's attached to.
-- If the instance extends **`MC`** (or `DC`) and is nested within another component's `_mc` property, `target` refers to the **parent MC/DC instance**.
+- If the instance extends **`DC`** `.target` refers to the **DOM HTMLElement** it's attached to.
+- If the instance extends **`MC`** (or `DC`) and is nested within another component, `.target` refers to the **parent MC/DC instance**.
 
 This reference is managed using `WeakRef` internally by `McBase` to prevent circular references and potential memory leaks.
 
 ### Event System
 
-A custom event system using the `McEvent` class allows components to communicate.
+A CustomEvent system allows components to communicate. These event handlers bubble differently than native events.
+
+Any MC method name starting with `on` or `one` followed by an uppercase character will automatically be registered as a custom event handler in the DOM element. 
+
+The names maps like this: 
+**class method** `onHandlerMethod()` => **custom event handler** `_mcHandlerMethod` 
+
+
+- **Triggering:** 
+
+  Events are dispatched using the `trigger` method:
+  - `myDomElement._mc.trigger('handlerMethod', { ... } )` ... from outside.
+  - `this.trigger( 'handlerMethod', data )` ...inside the current MC instance.
+
+  native:
+  - `myDomElement.dispatchEvent('_mcHandlerMethod', { detail: { ... } } )`;
+
 
-- **Triggering:** Events are dispatched using the `trigger` method:
-  - `DC.trigger(targetElement, ...)`: Dispatches to all MCs on a specific DOM element. Handles bubbling (`u`/`d`).
-  - `this.trigger(...)`: Dispatches within the current MC instance and its potential nested MCs. Can also initiate bubbling if the instance is a `DC`.
 - **Handling:**
   - Components listen for events by defining methods named `onEventName` or `oneEventName` (for once-off handling).
-  - These are automatically detected by `autoAttachListeners`.
+  - These are automatically detected by `autoAttachListeners` internally.
   - Native DOM events matching this pattern on `DC` instances are also automatically bound to the target element.
-- **Bubbling:** Events triggered via `DC.trigger` or `dcInstance.trigger` can bubble:
+
+
+- **Bubbling:** Events triggered via `dcInstance.trigger` can bubble:
   - `'l'`: Local only (default). Handlers on the target element's/instance's MCs are executed.
   - `'u'`: Upwards. Event propagates to MCs on parent elements (DOM tree).
   - `'d'`: Downwards. Event propagates to MCs on descendant elements (DOM tree).
-  - Combinations are possible (e.g., `'lu'`, `'ldu'`). Bubbling (`u`/`d`) occurs asynchronously via `setTimeout`.
+  - Any combination of the characters 'l','u', 'd' are possible (e.g., `'lu'`, `'ldu'`). 
+  - Bubbling (`u`/`d`) occurs asynchronously via `setTimeout`.
 
 ### Observables (Mention)
 
@@ -101,7 +117,7 @@ The `DC` class provides methods (`parent`, `ancestors`, `children`, `descendants
 
 ### Autoloading Concept
 
-An optional feature (`autoload()`) that automatically detects specific HTML tags (e.g., `<my-component>`) or elements with an `_mc="my-component"` attribute and attempts to dynamically load the corresponding JavaScript module (e.g., `/my/component.js`).
+An optional feature (`autoload()`) that automatically detects specific HTML tags (e.g., `<my-component>`) or elements with an `data-mc="my-component"` attribute and attempts to dynamically load the corresponding JavaScript module (e.g., `/my/component.js`).
 
 ### Important Rule
 
@@ -128,7 +144,6 @@ Base class for non-DOM or server-side components. Extends `McBase`.
 
 - **Instance Properties**:
   - `.target`: (Inherited from `McBase`) Refers to the parent MC/DC instance it's nested within.
-  - `._mc`: An object `{}` to hold nested microcomponent instances.
 - **Instance Methods**:
   - `.trigger(eventName, data)`: (Inherited) Triggers events locally within the instance and its nested `_mc` structure. Does not handle DOM bubbling.
 
@@ -138,26 +153,27 @@ Class for DOM-aware components. Extends `McBase`. **Client-side only.**
 
 - **Static Methods**:
   - `DC.add(domElement, key, mcInstance)`: Attaches an `mcInstance` (should be a `DC` or `MC`) to a `domElement` under the specified `key`. Creates `domElement._mc` if needed and sets the `_mc` attribute.
-  - `DC.remove(domElement, key)`: Removes the MC instance associated with `key` from `domElement._mc`. Removes the `_mc` attribute if the collection becomes empty.
+  - `DC.remove(domElement, key)`: Removes the MC instance associated with `key` from `domElement._mc`. Removes the `data-mc` attribute if the collection becomes empty.
   - `DC.trigger(domElement, eventName, data, bubble)`: Triggers an event on all MCs attached to `domElement`. Handles DOM bubbling (`'l'`, `'u'`, `'d'`).
 - **Instance Properties**:
   - `.target`: (Inherited from `McBase`) Refers to the DOM HTMLElement this `DC` instance is attached to (via `DC.add`).
-  - `._mc`: An object `{}` to hold nested microcomponent instances.
 - **Instance Methods**:
-  - `.parent(search?)`: Gets MC instances from the closest parent element that has attached MCs. Optionally filters by `search` key.
-  - `.ancestors(search?)`: Gets MC instances from all ancestor elements with attached MCs. Optionally filters by `search` key.
-  - `.children(search?)`: Gets MC instances from direct child elements with attached MCs. Optionally filters by `search` key.
-  - `.descendants(search?)`: Gets MC instances from all descendant elements with attached MCs. Optionally filters by `search` key.
-  - `.trigger(eventName, data, bubble)`: Triggers an event on this `DC` instance and its nested `_mc` structure. Can initiate DOM bubbling (`'l'`, `'u'`, `'d'`).
+  - `.parent()`: Gets MC instances from the closest parent element that has attached MCs.
+  - `.ancestors()`: Gets MC instances from all ancestor elements with attached MCs.
+  - `.children()`: Gets MC instances from direct child elements with attached MCs.
+  - `.descendants()`: Gets MC instances from all descendant elements with attached MCs.
+  - `.trigger(eventName, data, bubble)`: Triggers an event on this `DC` instance. Can initiate DOM bubbling (`'l'`, `'u'`, `'d'`).
 
 ## Examples
 
 ### Typical Workflow
 
-1.  Define your component classes extending `MC` or `DC`.
-2.  Attach top-level `DC` instances to HTMLElements using `DC.add()`.
-3.  Nest `MC` or `DC` instances within others using the `._mc` property if needed.
-4.  Access other components via the `_mc` property, DOM traversal methods (`ancestors()`, `children()`, etc.), or event communication (`trigger`).
+1.  Define your component classes extending `MC` or `DC`. These contain plain data, observable state, event callbacks and optional internal MCs.
+2.  Attach defined top-level `DC` instances to HTMLElements using `DC.add()`.
+3.  Then...
+  - Select and access other MCs using DOM traversal methods (`ancestors()`, `children()`, etc.)
+  - Dynamically attach event handlers (`on`, `one`, `off`).
+  - Communicate with other components via Events (`trigger`).
 
 ### Attach Micro Components (`DC.add`)
 
@@ -168,34 +184,38 @@ const myElement = document.getElementById('myDiv');
 
 // Define an inner MC (doesn't need DOM access itself)
 class MyInnerClass extends MC {
+
 	constructor(target) {
 		// target will be the parent MyPublicClass instance
 		super(target);
 		console.log('Inner MC target:', this.target);
 	}
+
 	doSomethingInner() {
 		console.log('Inner action!');
 	}
+
 }
 
 // Define an outer DC (needs DOM access or is top-level)
 class MyPublicClass extends DC {
+
 	constructor(target) {
 		// target will be myElement
 		super(target);
 		console.log('Outer DC target:', this.target);
 		// Add an inner MC instance, nested within this DC instance
-		this._mc.myInner = new MyInnerClass(this); // 'this' becomes the target for MyInnerClass
+		this.myInner = new MyInnerClass(this); // 'this' becomes the target for MyInnerClass
 	}
+
 	doSomethingOuter() {
 		console.log('Outer action!');
 	}
 
-	// Example DOM event handler
 	onClick(event) {
 		console.log('Div clicked!', event);
 		// Access nested MC
-		this._mc.myInner?.doSomethingInner();
+		this.myInner.doSomethingInner();
 	}
 }
 
@@ -217,12 +237,13 @@ const myElement = document.getElementById('myDiv');
 
 DC.remove(myElement, 'myComponent');
 
-// If myElement._mc is now empty, the '_mc' attribute is also removed.
+// If myElement._mc is now empty, the 'data-mc' attribute is also removed.
 ```
+Hint: I have yet to find a usage example for this... so far it simply exists as a counterpart to `DC.add()`.
 
 ### Retrieve Micro Components
 
-Access attached components via the \_mc property of the target element or parent component.
+Access attached components via the `_mc` property of the target element or parent component.
 
 ```javascript
 // Get the container object for all MCs on an element
@@ -246,13 +267,13 @@ const targetElement = document.getElementById('myDiv');
 const eventData = { message: 'Hello from outside!' };
 
 // Trigger 'customEvent' locally on MCs attached to targetElement
-DC.trigger(targetElement, 'customEvent', eventData, 'l');
+trigger(targetElement, 'customEvent', eventData, 'l');
 
 // Trigger 'customEvent' and bubble up the DOM tree
-DC.trigger(targetElement, 'customEvent', eventData, 'u');
+trigger(targetElement, 'customEvent', eventData, 'u');
 
 // Trigger 'customEvent' locally, bubble up, and bubble down
-DC.trigger(targetElement, 'customEvent', eventData, 'lud');
+trigger(targetElement, 'customEvent', eventData, 'lud');
 ```
 
 2. Triggering from inside a component instance:
@@ -267,10 +288,6 @@ class MyTriggeringComponent extends DC {
 		// Trigger 'internalEvent' only on this instance and its nested _mc components
 		this.trigger('internalEvent', eventData); // Default bubble 'l'
 
-		// Trigger 'externalEvent' on sibling components attached to the same target element
-		// (and potentially bubble up/down based on the 'bubble' parameter)
-		DC.trigger(this.target, 'externalEvent', eventData, 'l'); // Trigger locally on siblings
-
 		// Trigger 'downwardEvent' on components attached to descendant elements
 		this.trigger('downwardEvent', eventData, 'd'); // Bubbles down from this component's target
 	}
@@ -287,48 +304,15 @@ class MyTriggeringComponent extends DC {
 		);
 	}
 
-	onExternalEvent(event) {
-		console.log(
-			`[${this.constructor.name}] received externalEvent:`,
-			event.data
-		);
-	}
-
 	onDownwardEvent(event) {
 		console.log(
-			`[${this.constructor.name}] received downwardEvent:`,
+			`[${this.constructor.name}] ERROR: received downwardEvent`,
 			event.data
 		);
 	}
 }
 ```
 
-### Retrieving Inner Micro Components
-
-Access nested components directly via the parent's `_mc` property.
-
-```javascript
-class Inner extends MC {
-	constructor(target) {
-		super(target);
-	}
-	someInnerMethod() {
-		console.log('Inner method called!');
-	}
-}
-
-class Outer extends DC {
-	constructor(target) {
-		super(target);
-		this._mc.inner = new Inner(this);
-	}
-
-	accessInner() {
-		this._mc?.inner.someInnerMethod();
-	}
-}
-```
-
 ### Navigating Parent/Ancestor MCs
 
 Use .parent() and .ancestors() (available on DC instances) to find components attached to elements higher up the DOM tree.
@@ -337,7 +321,7 @@ These methods skip elements that don't have any MCs attached.
 
 ```javascript
 // Inside a method of a DC instance:
-const parentMcs = this.parent(); // Array of MC instances on the first parent element with MCs
+const parentMcs = this.parent(); // Array of MC instances on the closest parent element that contains MCs
 console.log(parentMcs);
 
 const allAncestorMcs = this.ancestors(); // Array of all MC instances on all ancestor elements with MCs
@@ -394,9 +378,9 @@ class McWithHandlers extends DC {
 	}
 
 	// This is a custom event handler, not a native DOM event.
-	// It will be triggered by this.trigger('CustomAction') or DC.trigger(this.target, 'CustomAction')
+	// It will be triggered by this.trigger('CustomAction')
 	onCustomAction(mcEvent) {
-		console.log('Custom action triggered!', mcEvent.data);
+		console.log('Custom action triggered!', mcEvent.data, mcEvent.bubble);
 	}
 }
 
@@ -433,7 +417,7 @@ class MyLifecycleComponent extends DC {
 	}
 
 	oneInit(event) {
-		// This code runs shortly after the constructor finishes.
+		// called asynchronous after the constructor finishes.
 		console.log('MyLifecycleComponent oneInit called!', event);
 		// Safe to access this.target or setup things that depend on the instance being fully constructed.
 	}
@@ -475,7 +459,7 @@ The necessary code is fetched and executed only when these components actually a
 **./test/mymc.ts**
 ```typescript
 'use strict';
-import { DC, LooseObject } from '../microcomponents.js';
+import { DC } from '../microcomponents.js';
 
 export default class myMC extends DC {
     constructor(target: HTMLElement) {
@@ -483,7 +467,7 @@ export default class myMC extends DC {
     }
 
     oneInit() {
-        // console.log('testmc connected to DOM');
+        console.log('testmc connected to DOM');
     }
 }
 ```
@@ -502,13 +486,8 @@ defineCE(
 		constructor(target: HTMLElement) {
 			super(target);
 
-			const that = this; // to help minification, you can use 'this' throughout the constructor as well
-
-			delete that._mc; // no inner classes needed
-
-			let shadow = (that as DC).target.attachShadow({ mode: 'open' });
-			shadow.innerHTML = `<style>${that.css}</style>${that.template}`;
-
+			let shadow = (this as DC).target.attachShadow({ mode: 'open' });
+			shadow.innerHTML = `<style>${this.css}</style>${this.template}`;
 		}
 
 		get template() {

package/public/documentation/elements.md

@@ -50,15 +50,15 @@ document.body.append( myTag );
 After:
 ```html
 <body>
-	<my-tag _mc>Hello World</my-tag>
+	<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 `<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.
+- 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.
 
@@ -98,7 +98,7 @@ defineCE(
 	['my-attribute'] // DOM node attributes to observe
 );
 
-let MyTag = getCE("my-tag"), // customElemtentRegistry.get("my-tag")
+let MyTag = getCE("my-tag"), // customElementRegistry.get("my-tag")
 	myTag = new MyTag(); // programmatically create a custom element instance
 
 document.body.append( myTag );
@@ -147,7 +147,7 @@ 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.
+- The event parameter handed over is an CustomEvent instance, that contains the original native event in its `detail` property.
 
 ## Native HTMLElement Event Handlers
 
@@ -182,7 +182,6 @@ 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
 
@@ -216,7 +215,6 @@ 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
 
@@ -255,8 +253,7 @@ Alternatives:
 
 document
 	.querySelector( 'my-tag' )
-	?._mc
-	.trigger('specialEvent'); // ...on all micro components contained in <my-tag>
+	.dispatchEvent('specialEvent'); // ...on all micro components contained in <my-tag>
 
 /*
 traversing the DOM: