@twobirds/microcomponents 0.0.46 → 0.0.50

package/public/documentation/MC.md

@@ -1,256 +1,470 @@
-# Micro Components <span style="float:right; height:1em;"><img height="24px" src="./MicroComponents.svg" /></span>
+# Microcomponent Framework Documentation <span style="float:right; height:1em;"><img height="24px" src="./MicroComponents.svg" /></span>
+
+This document details a lightweight JavaScript framework for creating and managing "microcomponents" (MCs) associated with DOM elements or other microcomponents. It allows you to define reusable components and attach them to build complex functionalities.
+
+The framework exports 2 main classes:
+
+- **MC**: Micro Component. The base component class, suitable for logic that doesn't directly interact with the DOM or for use on the server.
+- **DC**: DOM Component. Extends `MC` and adds DOM-specific methods (like traversal). Use this for components that need to interact with the browser's DOM.
+
+## Table of Contents
+
+- [Usage Guidance](#usage-guidance)
+- [Core Concepts](#core-concepts)
+  - [Microcomponents (MCs)](#microcomponents-mcs)
+  - [`_mc` Property](#_mc-property)
+  - [DOM Association & `target`](#dom-association--target)
+  - [Event System](#event-system)
+  - [Observables (Mention)](#observables-mention)
+  - [DOM Traversal](#dom-traversal)
+  - [Autoloading Concept](#autoloading-concept)
+  - [Important Rule](#important-rule)
+- [Framework Classes](#framework-classes)
+  - [Not Exported: `McBase` (Superclass)](#not-exported-mcbase-superclass)
+  - [Exported: `MC` Class](#exported-mc-class)
+  - [Exported: `DC` Class](#exported-dc-class)
+- [Examples](#examples)
+  - [Typical Workflow](#typical-workflow)
+  - [Attach Micro Components (`DC.add`)](#attach-micro-components-dcadd)
+  - [Remove Micro Components (`DC.remove`)](#remove-micro-components-dcremove)
+  - [Retrieve Micro Components](#retrieve-micro-components)
+  - [Triggering Events](#triggering-events)
+  - [Retrieving Inner Micro Components](#retrieving-inner-micro-components)
+  - [Navigating Parent/Ancestor MCs](#navigating-parentancestor-mcs)
+  - [Retrieving Child/Descendant MCs](#retrieving-childdescendant-mcs)
+  - [Auto-attaching DOM Listeners](#auto-attaching-dom-listeners)
+- [Lifecycle Events](#lifecycle-events)
+  - [Init](#init)
+  - [Destroy (TBD)](#destroy-tbd)
+- [Helper Functions (Internal)](#helper-functions-internal)
+  - [`isBrowser()`](#isbrowser)
+  - [`nativeEventNames`](#nativeeventnames)
+  - [`getMicroComponents(...)`](#getmicrocomponents)
+  - [`traverseNodes(...)`](#traversenodes)
+  - [`isDOM(...)`](#isdom)
+  - [`addListener(...)`](#addlistener)
+  - [`removeListener(...)`](#removelistener)
+  - [`add(...)`](#add)
+  - [`remove(...)`](#remove)
+  - [`trigger(...)`](#trigger)
+  - [`init(...)`](#init-helper)
+  - [`autoAttachListeners(...)`](#autoattachlisteners)
+  - [`bubbleEvent(...)`](#bubbleevent)
+- [Autoloading Implementation](#autoloading-implementation)
+  - [`autoload(enable?)`](#autoload)
+  - [`loadit()`](#loadit)
+- [Interfaces and Types](#interfaces-and-types)
+  - [`LooseObject`](#looseobject)
+  - [`McEvent`](#mcevent)
+  - [`HTMLMcElement`](#htmlmcelement)
 
-This system allows you to to define **Micro Components** and attach them to DOM elements or other Micro Components.
+## Usage Guidance
 
-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 )
+- **If your component needs to access or manipulate the DOM** (e.g., find other components in the DOM, attach listeners directly, read element properties), **your class MUST extend `DC`**. This is client-side only.
+- **Otherwise** (e.g., for pure logic, state management, or server-side usage), **your class should extend `MC`**.
+
+Think **DRY** (Don't Repeat Yourself) and **SOLID** principles when designing your components.
 
-# Usage
+## Core Concepts
 
-- **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**.
+Fundamental ideas behind the framework.
 
-In any case, your class instances will contain a property **"_mc"** where you can (but don't have to) put in other MCs.
+### Microcomponents (MCs)
 
-Also your class instances will have a readonly **"target"** property that is back reference to the instance they are contained in.
+Plain JavaScript objects or class instances (extending `MC` or `DC`) that encapsulate behavior and state. They can be attached to DOM elements (via `DC`) or nested within other MCs.
 
-- 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**.
+### `_mc` Property
 
-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.
+A special property attached to `HTMLElement` instances (when using `DC.add`) or parent `MC`/`DC` instances. It acts as an object container (`{ key: mcInstance, ... }`) holding one or more named microcomponent instances.
 
-# Rules
+- On HTMLElements, the presence of attached components is also marked by a `_mc` attribute for CSS selection and discovery. This attribute is added by `DC.add` and removed by `DC.remove` when the `_mc` object becomes empty.
 
-- **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.
+### DOM Association & `target`
 
-# Not Exported
+Each microcomponent instance has a read-only `target` property providing a back-reference:
 
-## **McBase** Superclass
+- 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**.
 
-  **Instance Properties**
-  - `.target`: readonly, a getter returning the DOM element or parent MC instance your instance resides in
+This reference is managed using `WeakRef` internally by `McBase` to prevent circular references and potential memory leaks.
 
-  **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.
+### Event System
 
-- **Instance Methods:**
-  - `.trigger( eventName, data )`: runs callback methods.
+A custom event system using the `McEvent` class allows components to communicate.
 
-# Exported:
+- **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`.
+  - 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:
+  - `'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`.
 
-## **MC** Class, extends McBase
+### Observables (Mention)
 
-  **Instance Properties**
-  - `.target`: (inherited from McBase)
-  - `._mc`: a hash object that contains inner micro components
+- MCs can utilize observables (implementation not detailed here) for data-driven workflows.
+- `DC` components can leverage observables and potentially form values for 1-way or 2-way data binding with the DOM.
+
+### DOM Traversal
 
-- **Instance Methods:**
-  - `.trigger( eventName, data )`: (inherited from McBase)
+The `DC` class provides methods (`parent`, `ancestors`, `children`, `descendants`) to find related `DC` instances attached to elements elsewhere in the DOM hierarchy, skipping over elements without attached microcomponents.
 
-## **DC** Class, extends McBase
+### Autoloading Concept
 
-- **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.
+An optional feature (`autoload()`) that automatically detects specific HTML tags (e.g., `<my-component>`) or elements with an `_mc="MyComponent"` attribute and attempts to dynamically load the corresponding JavaScript module (e.g., `/my/Component.js`).
 
-  **Instance Properties**
-  - `.target`: (inherited from McBase)
-  - `._mc`: a hash object that contains inner micro components
+### Important Rule
 
-- **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.
+**Your own application code MUST NOT overwrite the core properties and methods provided by the `McBase`, `MC`, and `DC` classes (like `_mc`, `target`, `trigger`, `parent`, etc.). Doing so may break framework functionality.**
 
-# Examples
+## Framework Classes
 
-## Typical Workflow
+### Not Exported: `McBase` (Superclass)
 
-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**.
+The internal base class for `MC` and `DC`. You don't extend this directly.
 
-### Attach Micro Components to a DOM element
+- **Instance Properties**:
+  - `.target`: Read-only getter returning the containing DOM element (for DCs added via `DC.add`) or parent MC/DC instance (for nested MCs). Uses `WeakRef`.
+- **Constructor Behavior**:
+  - Initializes the `.target` reference.
+  - Calls `init(this)`: Triggers the 'Init' lifecycle event asynchronously.
+  - Calls `autoAttachListeners(this)`: Sets up automatic event listeners based on method names (`onEventName`, `oneEventName`).
+- **Instance Methods**:
+  - `.trigger(eventName, data)`: Base trigger logic used by `MC` and `DC`.
 
-To attach a micro component to an HTML element, use the `DC.add()` static function.
+### Exported: `MC` Class
+
+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.
+
+### Exported: `DC` Class
+
+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.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'`).
+
+## 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`).
+
+### Attach Micro Components (`DC.add`)
+
+Use the static `DC.add()` method to attach a component (usually a `DC` instance) to an HTMLElement.
 
 ```javascript
 const myElement = document.getElementById('myDiv');
 
-/*
-usage with classes, both PUBLIC and PRIVATE
-*/
-
-// internal MC class
-MyInnerClass = class extends MC{
-  constructor(target){
-  }
+// 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!');
+	}
 }
 
-// external DC class
-MyPublicClass = class extends DC{
-  constructor(target){
-    // add a internal inner MC
-    this._mc.myInnerComponent = new MyInnerClass( this );
-  }
+// 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
+	}
+	doSomethingOuter() {
+		console.log('Outer action!');
+	}
+
+	// Example DOM event handler
+	onClick(event) {
+		console.log('Div clicked!', event);
+		// Access nested MC
+		this._mc.myInner?.doSomethingInner();
+	}
 }
 
-// attach a DC
-DC.add( myElement, 'myDcComponent', new MyPublicClass( myElement ) );
-```
+// Attach the outer DC instance to the DOM element
+// The key 'myComponent' is used to access it later via myElement._mc.myComponent
+DC.add(myElement, 'myComponent', 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.
+// Hint: After adding, myElement now has:
+// 1. A property: myElement._mc = { myComponent: instanceOfMyPublicClass }
+// 2. An attribute: <div id="myDiv" _mc>...</div>
+```
 
-### Remove a top level Micro Component from a DOM element
+### Remove Micro Components (DC.remove)
 
-Micro components can be removed using the `DC.remove()` static method.
+Use the static DC.remove() method to detach a top-level component.
 
 ```javascript
-DC.remove( myDomElement, 'myComponent');
+const myElement = document.getElementById('myDiv');
+
+DC.remove(myElement, 'myComponent');
+
+// If myElement._mc is now empty, the '_mc' attribute is also removed.
 ```
 
-**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
 
-### Retrieve Micro Components from a DOM element
+Access attached components via the \_mc property of the target element or parent component.
 
 ```javascript
-const target = document.querySelector( 'div' );
-console.log(target._mc);
+// Get the container object for all MCs on an element
+const myElement = document.getElementById('myDiv');
+const mcContainer = myElement._mc;
+console.log(mcContainer); // { myComponent: instanceOfMyPublicClass, ... }
+
+// Get a specific instance by its key
+const specificInstance = myElement._mc?.myComponent;
+if (specificInstance) {
+	specificInstance.doSomethingOuter();
+}
 ```
 
-To retrieve a specific micro component by its key:
+### Triggering Events
+
+1. Triggering from outside onto components on an element:
+
 ```javascript
-const target = document.querySelector( 'div' );
-const specificInstance = target._mc?.myPublicComponent;
-console.log(specificInstance);
+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 'customEvent' and bubble up the DOM tree
+DC.trigger(targetElement, 'customEvent', eventData, 'u');
+
+// Trigger 'customEvent' locally, bubble up, and bubble down
+DC.trigger(targetElement, 'customEvent', eventData, 'lud');
 ```
 
-### Trigger an Event
+2. Triggering from inside a component instance:
 
 ```javascript
-const target = document.querySelector( 'div' );
-DC.trigger( target, '<eventName>', data | null, bubble );
+class MyTriggeringComponent extends DC {
+	// ... constructor ...
 
-// bubble is any combination of 'lud', meaning [local|up|down]
-// local is only "this", "up" traverses towards root, "down" traverses the inner DOM.
-```
+	someMethod() {
+		const eventData = { source: 'MyTriggeringComponent' };
 
-# Methods you can use in your Micro Component Instances
+		// Trigger 'internalEvent' only on this instance and its nested _mc components
+		this.trigger('internalEvent', eventData); // Default bubble 'l'
 
-## Retrieve Inner Micro Components
+		// 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
 
-You can retrieve an inner micro component by using the ._mc property.
+		// Trigger 'downwardEvent' on components attached to descendant elements
+		this.trigger('downwardEvent', eventData, 'd'); // Bubbles down from this component's target
+	}
 
-```javascript
-const innerComponent = this._mc.myInnerComponent;
-console.log(innerComponent);
-```
+	// Event handler methods
+	onCustomEvent(event) {
+		console.log(`[${this.constructor.name}] received customEvent:`, event.data);
+	}
 
-**The following methods hop over HTMLElements that DO NOT contain micro components.**
+	onInternalEvent(event) {
+		console.log(
+			`[${this.constructor.name}] received internalEvent:`,
+			event.data
+		);
+	}
 
+	onExternalEvent(event) {
+		console.log(
+			`[${this.constructor.name}] received externalEvent:`,
+			event.data
+		);
+	}
 
-## Navigate Parent and Ancestor Micro Components
+	onDownwardEvent(event) {
+		console.log(
+			`[${this.constructor.name}] received downwardEvent:`,
+			event.data
+		);
+	}
+}
+```
 
-The `.parent()` and `.ancestors()` methods allow you to retrieve micro components attached to parent elements.
+### Retrieving Inner Micro Components
+
+Access nested components directly via the parent's `_mc` property.
 
 ```javascript
-const parentMcs = this.parent();
-console.log(parentMcs);  // all micro components of the closest ancestor that has an _mc attribute
+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);
+	}
 
-const allAncestorsMcs = this.ancestors();
-console.log(allAncestorsMcs);  // all ancestor micro components up to document root.
+	accessInner() {
+		this._mc?.inner.someInnerMethod();
+	}
+}
 ```
 
-To retrieve specific micro component(s) attached to ancestors:
+### Navigating Parent/Ancestor MCs
+
+Use .parent() and .ancestors() (available on DC instances) to find components attached to elements higher up the DOM tree.
+
+These methods skip elements that don't have any MCs attached.
+
 ```javascript
-const specificAncestorMc = this.ancestors('myComponent');
+// Inside a method of a DC instance:
+const parentMcs = this.parent(); // Array of MC instances on the first parent element with MCs
+console.log(parentMcs);
+
+const allAncestorMcs = this.ancestors(); // Array of all MC instances on all ancestor elements with MCs
+console.log(allAncestorMcs);
+
+// Find a specific component type/key among ancestors
+const specificAncestor = this.ancestors('someSpecificKey')?.[0];
+
+if (specificAncestor) {
+	console.log('Found specific ancestor:', specificAncestor);
+}
 ```
 
-## Retrieve Child and Descendant Micro Components
+### Retrieving Child/Descendant MCs
+
+Use .children() and .descendants() (available on DC instances) to find components attached to elements lower down the DOM tree.
 
-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
+// Inside a method of a DC instance:
+const childMcs = this.children(); // Array of MCs on direct child elements with MCs
+console.log(childMcs);
 
-const descendantComponents = this.descendants();
-console.log(descendantComponents);  // an array of all descendant micro components in the inner DOM
+const descendantMcs = this.descendants(); // Array of all MCs on all descendant elements with MCs
+console.log(descendantMcs);
 
-//To search for a specific micro component by key:
-const specificMcs = this.descenants('specificMc');
+// Find specific components among descendants
+const specificDescendants = this.descendants('someSpecificKey');
+console.log(specificDescendants); // Array of matching descendant MCs
 ```
 
-## Trigger an Event
+### Auto-attaching DOM Listeners
+
+Methods defined in your DC class starting with `on` or `one` followed by a capital letter, which also match native DOM event names (case-insensitive check), will automatically have listeners attached to the target DOM element:
+
 ```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
-  );
+class McWithHandlers extends DC {
+	constructor(target) {
+		super(target);
+	}
+
+	// This method name matches the native 'click' event.
+	// A listener will be automatically added to this.target.
+	onClick(domEvent) {
+		console.log('Target element clicked!', domEvent);
+		// 'this' refers to the MyClickHandler instance
+		this.target.style.backgroundColor = 'lightblue';
+	}
+
+	// This method name matches the native 'mouseover' event.
+	// 'one' means the listener will be removed after the first trigger.
+	oneMouseover(domEvent) {
+		console.log('Mouseover detected once!', domEvent);
+		this.target.style.border = '2px solid red';
+	}
+
+	// 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')
+	onCustomAction(mcEvent) {
+		console.log('Custom action triggered!', mcEvent.data);
+	}
+}
+
+const myDiv = document.getElementById('clickableDiv');
+DC.add(myDiv, 'clickHandler', new McWithHandlers(myDiv));
+// Now clicking or mousing over 'clickableDiv' will trigger the methods.
 ```
 
-## Automatically attach Listener Methods to the DOM
+### Lifecycle Events
+
+The framework defines specific methods that are called at certain points in a component's life.
+
+#### Init
+
+Method Name: oneInit(event)
 
-On any **MC** and **DC** instance, the Superclass McBase calls **autoAttachListeners()** in the constructor.
+Triggered: Asynchronously (setTimeout(0)) after the component instance is created (called from McBase constructor via the init helper).
 
-Any methods you define in your code that start with **"on"** or **"one"**, and also match DOM event names, will be called accordingly:
+Execution Order:
+
+The component's oneInit is called first, then it recursively calls oneInit on any components nested within its `_mc` property.
+
+Requirement:
+
+- You must define a method named `oneInit` in your class for it to be called.
+- The `one` prefix implies it's intended to run once during initialization.
 
 ```javascript
-class MyEventTarget extends MC {
+class MyLifecycleComponent extends DC {
 	constructor(target) {
 		super(target);
+		console.log('Constructor finished');
+		this._mc.nested = new NestedComponent(this);
 	}
 
-	onClick(ev) {
-		console.log("onClick", ev);
+	oneInit(event) {
+		// This code runs shortly 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.
 	}
 }
-
-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.
+
+#### Destroy (TBD)
+
+Method Name: oneDestroy(event) (Proposed)
+
+Triggered: When a component is removed (e.g., via DC.remove or potentially parent removal).
+
+Execution Order:
+
+Expected to run synchronously, starting from the deepest nested components upwards, finally calling oneDestroy on the component being removed itself.
+
+Requirement:
+
+- Would require defining a method named `oneDestroy` in your class.