@twobirds/microcomponents 0.0.66 → 0.0.68

package/public/McEvent.ts

@@ -0,0 +1,96 @@
+"use strict";
+
+var isBrowser=new Function("try {return this===window;}catch(e){ return false;}");
+
+let nativeEventNames: Set<string> = new Set();
+
+// HTMLElement native event names
+if ( isBrowser() ){
+	Object.keys( HTMLElement.prototype ).filter( key => /^on/.test(key) ).forEach( eventName => nativeEventNames.add( eventName ) );
+}
+
+function isDOM(element: { [key:string]: any } ) {
+	return element && element instanceof HTMLElement;
+}
+
+interface McEvent {
+	data: any;
+	bubble: string;
+}
+
+class McEvent{
+
+	#type: string;
+	#stopped: boolean = false;
+	#immediateStopped: boolean = false;
+
+	constructor( type: string, data: any = {}, bubble: string = 'l' ){
+		// bubble standard = local only, options = any combination of'uld' characters: up to root, local, down
+		this.#type = type;
+		this.data = data;
+		this.bubble = bubble;
+	}
+
+	get type(): string {
+		return this.#type;
+	}
+
+	get stopped(): boolean {
+		return this.#stopped;
+	}
+
+	get immediateStopped(): boolean {
+		return this.#immediateStopped;
+	}
+
+	stopPropagation(){
+		this.#stopped = true;
+	}
+
+	stopImmediatePropagation(){
+		this.stopPropagation();
+		this.#immediateStopped = true;
+	}
+
+}
+
+// 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;
+}
+
+export { McEvent };

package/public/MicroComponents.svg

@@ -0,0 +1,15 @@
+<svg width="200" height="200" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg">
+ <!-- Created with SVG-edit - http://svg-edit.googlecode.com/ -->
+ <title>test</title>
+ <rect fill="transparent" x="0" y="0" width="200" height="200" fill-opacity="1"/>
+ <g style="fill:transparent">
+  <title>first bird</title>
+  <path fill="#18829c" d="
+    m15,160
+    a30,75 45 1 0 160,-150
+    a20,50 225 1 1 -110,100
+    a12,25 45 1 1 60,-50
+    a20,50 225 1 0 -110,100
+    " />
+ </g>
+</svg>

package/public/documentation/MC.md

@@ -0,0 +1,588 @@
+![logo](./MicroComponents.svg)
+
+# Micro Component Documentation
+
+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)
+- [Classes](#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)
+- [Interfaces and Types](#interfaces-and-types)
+  - [`LooseObject`](#looseobject)
+  - [`McEvent`](#mcevent)
+  - [`HTMLMcElement`](#htmlmcelement)
+- [Autoloading](#auto-loading)
+
+## Usage Guidance
+
+- **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.
+
+## Core Concepts
+
+Fundamental ideas behind the framework.
+
+### Microcomponents (MCs)
+
+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.
+
+### `_mc` Property
+
+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.
+
+- 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.
+
+### DOM Association & `target`
+
+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**.
+
+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.
+
+- **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`.
+
+### Observables (Mention)
+
+- 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
+
+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.
+
+### Autoloading Concept
+
+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`).
+
+### Important Rule
+
+**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.**
+
+## Classes
+
+### Not Exported: `McBase` (Superclass)
+
+The internal base class for `MC` and `DC`. You don't extend this directly.
+
+- **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`.
+
+### 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');
+
+// 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
+	}
+	doSomethingOuter() {
+		console.log('Outer action!');
+	}
+
+	// Example DOM event handler
+	onClick(event) {
+		console.log('Div clicked!', event);
+		// Access nested MC
+		this._mc.myInner?.doSomethingInner();
+	}
+}
+
+// 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 adding, myElement now has:
+// 1. A property: myElement._mc = { myComponent: instanceOfMyPublicClass }
+// 2. An attribute: <div id="myDiv" _mc>...</div>
+```
+
+### Remove Micro Components (DC.remove)
+
+Use the static DC.remove() method to detach a top-level component.
+
+```javascript
+const myElement = document.getElementById('myDiv');
+
+DC.remove(myElement, 'myComponent');
+
+// If myElement._mc is now empty, the '_mc' attribute is also removed.
+```
+
+### Retrieve Micro Components
+
+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
+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();
+}
+```
+
+### Triggering Events
+
+1. Triggering from outside onto components on an element:
+
+```javascript
+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');
+```
+
+2. Triggering from inside a component instance:
+
+```javascript
+class MyTriggeringComponent extends DC {
+	// ... constructor ...
+
+	someMethod() {
+		const eventData = { source: 'MyTriggeringComponent' };
+
+		// 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
+	}
+
+	// Event handler methods
+	onCustomEvent(event) {
+		console.log(`[${this.constructor.name}] received customEvent:`, event.data);
+	}
+
+	onInternalEvent(event) {
+		console.log(
+			`[${this.constructor.name}] received internalEvent:`,
+			event.data
+		);
+	}
+
+	onExternalEvent(event) {
+		console.log(
+			`[${this.constructor.name}] received externalEvent:`,
+			event.data
+		);
+	}
+
+	onDownwardEvent(event) {
+		console.log(
+			`[${this.constructor.name}] 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.
+
+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
+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);
+}
+```
+
+### Retrieving Child/Descendant MCs
+
+Use .children() and .descendants() (available on DC instances) to find components attached to elements lower down the DOM tree.
+
+```javascript
+// Inside a method of a DC instance:
+const childMcs = this.children(); // Array of MCs on direct child elements with MCs
+console.log(childMcs);
+
+const descendantMcs = this.descendants(); // Array of all MCs on all descendant elements with MCs
+console.log(descendantMcs);
+
+// Find specific components among descendants
+const specificDescendants = this.descendants('someSpecificKey');
+console.log(specificDescendants); // Array of matching descendant MCs
+```
+
+### 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
+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.
+```
+
+### Lifecycle Events
+
+The framework defines specific methods that are called at certain points in a component's life.
+
+#### Init
+
+Method Name: oneInit(event)
+
+Triggered: Asynchronously (setTimeout(0)) after the component instance is created (called from McBase constructor via the init helper).
+
+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 MyLifecycleComponent extends DC {
+	constructor(target) {
+		super(target);
+		console.log('Constructor finished');
+		this._mc.nested = new NestedComponent(this);
+	}
+
+	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.
+	}
+}
+```
+## Auto Loading
+
+`autoload()` provides a **progressive enhancement** strategy. It allows you to declare custom elements or special micro components in your HTML without needing to include all their JavaScript code upfront. 
+
+The necessary code is fetched and executed only when these components actually appear in the DOM, potentially improving initial page load time and resource usage.
+
+### Enabling
+
+- If you call **`autoload(true)`** (or just **`autoload()`** as true is the parameter default), it initializes a MutationObserver.
+  This observer watches the document.body for any changes to its child elements or subtree (e.g., when new elements are added to the page).
+
+**./autoload.html**
+```html
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>Humble Beginnings</title>
+		<script src="./microcomponents.min.js"></script>
+		<script>
+			Object.assign(window, microcomponents); // make system global
+			autoload(true); // automatically load web components that are undefined
+		</script>
+	</head>
+	<body>
+		<div _mc="test-mymc"></div> <!--- example of a auto-loading micro component --->
+		<test-component></test-component> <!--- example of a auto-loading custom element --->
+	</body>
+</html>
+
+```
+
+**./test/mymc.ts**
+```typescript
+'use strict';
+import { DC, LooseObject } from '../microcomponents.js';
+
+export default class myMC extends DC {
+    constructor(target: HTMLElement) {
+        super(target);
+        delete this._mc; // not needed
+    }
+
+    oneInit() {
+        // console.log('testmc connected to DOM');
+    }
+}
+```
+
+**./test/component.ts**
+```typescript
+'use strict';
+import { DC, defineCE } from '.././microcomponents.js';
+
+defineCE(
+	'test-component',
+
+	class extends DC {
+		data: unknown;
+
+		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}`;
+
+		}
+
+		get template() {
+			return /*html*/ `
+                <span>Hello World</span>
+            `;
+		}
+
+		get css() {
+			return /*css*/ `
+			div {
+				background-color: cyan;
+			}`;
+		}
+	}
+);
+```
+
+**Page HTML after loading**
+```HTML
+	(...)
+	<div _mc=""></div> <!--- _mc component definition now empty to avoid re-loading --->
+	<test-component></test-component> <!--- the custom element is initialized now --->
+	(...)
+```
+
+### Disabling:
+
+- If you call **`autoload(false)`**, it disconnects the observer, stopping the automatic loading feature:
+
+```typescript
+autoload(false);
+```
+
+### Loading Mechanism:
+
+When enabled and changes are detected in the DOM, the a callback function is triggered. This function scans the DOM for two types of components that might not yet be defined:
+
+- **Undefined Custom Elements:** It looks for HTML elements whose tag names haven't been defined via customElements.define() (e.g., `<my-custom-tag>`). 
+
+  For an element like `<my-custom-tag>`, it will attempt to load a script from a path derived from the tag name, such as **`./my/custom/tag.js`**. The loaded script is expected to then define this custom element.
+
+- **Undefined Micro Components:** It looks for HTML elements that have an **`_mc`** attribute that is not empty, e.g., **`<div _mc="my-component my-other">`**. 
+
+  **For each component name** listed in the **`_mc`** attribute (like **`my-component`**), it will attempt to load a script from a path like **`./my/component.js`**. 
+  
+  **These scripts are expected to `export default class {...}`** (usually extending DC from your code) that defines the behavior of this micro component.
+
+**In general:**
+
+- For each undefined component found, it dynamically creates a **`<script type="module">`** tag in the **`head`** of the document, and sets its src attribute to the appropriate path.
+
+- The src of the script is determined by converting the component name (e.g., **`my-component`**) into a path (e.g., **`./my/component.js`**).
+
+- These script tags are appended to the `<head>` of the document to initiate loading.
+
+### Internal Callbacks and Instantiation:
+
+- **Custom Elements:** 
+  Once the script for a custom element loads and defines the element (using customElements.define()), the browser automatically handles upgrading any existing instances of that tag.
+
+- **Micro Components:** 
+  When a script for an _mc component loads successfully, a another callback is executed. This callback:
+  - Stores the loaded component class in an internal repository to avoid unnecessary reloading.
+  - Finds all HTMLElement in the DOM that declared this _mc component.
+  - Instantiates the component class and adds it to the HTMLElement.
+  - Removes the component's name from the _mc attribute to prevent re-processing.
+
+### State Tracking:
+
+`autoload()` internally uses two Map() objects:
+
+- **`CEs`** (for Custom Elements that are currently loading)
+- **`MCs`** (for Micro Components), to keep track of components that are currently loading or have been loaded. This prevents attempting to load the same component multiple times. 
+
+These maps are exposed for debugging purposes. You can access them via `autoload.state` which returns an object with `CEs` and `MCs` properties.