@twobirds/microcomponents 0.0.64 → 0.0.66

package/assets/documentation/proposal_draft.md

@@ -1,37 +0,0 @@
-### RFC Proposal to WHATWG
-
-**Title:** Proposal for a **Micro Component Interface** in the DOM
-
-**Abstract:**
-
-This proposal introduces a standardized interface for managing micro components within HTML elements, enhancing modularity and reusability in web development.
-
-**Introduction:**
-
-Microcomponents provide a way to encapsulate functionality and state within a target DOM element. This proposal outlines methods for adding, removing, and querying micro components.
-
-**Proposed API:**
-
-- **Static Methods:**
-  - `MC.add( target, key, element)`: Attach a top level micro component to an HTMLElement.
-  - `MC.remove( target, key )`: Detach a top level micro component from an HTMLElement.
-  - `MC.siblings( target )`: get top level micro components from an HTMLElement.
-
-- **Instance Methods:**
-  - `add( key, element )`: Attach a private Micro Component to a Micro Component.
-  - `remove( key )`: Detach a private Micro Component from a Micro Component.
-  - `siblings(search?)`: Retrieve sibling micro components.
-  - `parent(search?)`: Get parent top level micro components.
-  - `parents(search?)`: Get all ancestor top level micro components.
-  - `children(search?)`: Retrieve child top level micro components.
-  - `descendants(search?)`: Get all descendant top level micro components.
-
-**Use Cases:**
-1. Modular web applications.
-2. Enhancing component-based architecture.
-
-**Conclusion:**
-Implementing this interface will streamline microcomponent management, fostering cleaner code and improved performance.
-
-**References:**
-- [Microcomponents Repository](https://gitlab.com/twoBirds/microcomponents) for a polyfill implementation and usage examples.

package/public/3d.html

@@ -1,42 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>3D Positioned Image with CSS</title>
-    <style>
-        body {
-            display: flex;
-            justify-content: center;
-            align-items: center;
-            height: 100vh;
-            background-color: #222;
-            perspective: 800px; /* Depth effect */
-        }
-
-        .container {
-            width: 300px;
-            height: 200px;
-            transform-style: preserve-3d; /* Needed for 3D transformations */
-        }
-
-        .image3d {
-            width: 100%;
-            height: 100%;
-            transform: rotateY(20deg) rotateX(10deg) translateZ(50px);
-            transition: transform 0.5s ease-in-out;
-            box-shadow: 5px 5px 15px rgba(0, 0, 0, 0.5);
-        }
-
-        /* Hover effect */
-        .container:hover .image3d {
-            transform: rotateY(-20deg) rotateX(-10deg) translateZ(100px);
-        }
-    </style>
-</head>
-<body>
-    <div class="container">
-        <img class="image3d" src="https://via.placeholder.com/300x200" alt="3D Image">
-    </div>
-</body>
-</html>

package/public/documentation/MC.md

@@ -1,470 +0,0 @@
-# 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)
-
-## 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.**
-
-## Framework 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.
-	}
-}
-```
-
-#### 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.