@twobirds/microcomponents 0.1.1 → 0.1.3

package/public/documentation/MC.md

@@ -1,547 +0,0 @@
-![logo](./MicroComponents.svg)
-
-# Micro Components
-
-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`. 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`** `.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 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: { ... } } )`;
-
-
-- **Handling:**
-  - Components listen for events by defining methods named `onEventName` or `oneEventName` (for once-off handling).
-  - 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 `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 closest elements (DOM tree).
-  - `'d'`: Downwards. Event propagates to MCs on descendant elements (DOM tree).
-  - Any combination of the characters 'l','u', 'd' 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 (`closest`, `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 `data-mc="my-component"` 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`, `closest`, 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.
-- **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 `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`).
-- **Instance Methods**:
-  - `.closest()`: Gets MC instances from the closest HTMLElement that has MCs attached.
-  - `.ancestors()`: Gets MC instances from all ancestor HTMLElements with MCs attached MCs.
-  - `.children()`: Gets MC instances from direct child HTMLElements with MCs attached.
-  - `.descendants()`: Gets MC instances from all descendant HTMLElements with MCs attached.
-  - `.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`. 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()`, `closest()`, `children()`, `descendants()` )
-  - Dynamically attach event handlers (`on()`, `one()`, `off()`).
-  - Communicate with other components via Events (`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 a public DC class
-class MyClass extends DC {
-
-	constructor(target) {
-		// target will be myElement
-		super(target);
-		console.log('Outer DC target:', this.target);
-	}
-
-	doSomething() {
-		console.log('Outer action!');
-	}
-
-	onClick(event) {
-		console.log('Div clicked!', event);
-	}
-}
-
-// Attach the DC instance to the DOM element
-// The key 'MyClass' is used to access it later via myElement._mc.myComponent
-DC.add(myElement, 'MyClass', new MyClass(myElement));
-
-// Hint: After adding, myElement now has:
-// 1. A property: myElement._mc = { MyClass: <instanceOfMyClass> }
-// 2. An attribute: <div id="myDiv" data-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 '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.
-
-```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
-trigger(targetElement, 'customEvent', eventData, 'l');
-
-// Trigger 'customEvent' and bubble up the DOM tree
-trigger(targetElement, 'customEvent', eventData, 'u');
-
-// Trigger 'customEvent' locally, bubble up, and bubble down
-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 '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
-		);
-	}
-
-	onDownwardEvent(event) {
-		console.log(
-			`[${this.constructor.name}] ERROR: received downwardEvent`,
-			event.data
-		);
-	}
-}
-```
-
-### Navigating closest/Ancestor MCs
-
-Use .closest() 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 closestMcs = this.closest(); // Array of MC instances on the closest parent element that contains MCs
-console.log(closestMcs);
-
-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')
-	onCustomAction(mcEvent) {
-		console.log('Custom action triggered!', mcEvent.data, mcEvent.bubble);
-	}
-}
-
-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) {
-		// 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.
-	}
-}
-```
-## 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 } from '../microcomponents.js';
-
-export default class myMC extends DC {
-    constructor(target: HTMLElement) {
-        super(target);
-    }
-
-    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);
-
-			let shadow = (this as DC).target.attachShadow({ mode: 'open' });
-			shadow.innerHTML = `<style>${this.css}</style>${this.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.

package/public/documentation/MicroComponents.svg

@@ -1,15 +0,0 @@
-<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>