@twobirds/microcomponents

![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`) 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="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`, `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>  <test-component></test-component>  </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>  <test-component></test-component>  (...) ``` ### 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.