@twobirds/microcomponents 0.2.2 → 0.2.4

package/dist/core/MC.js

@@ -1,164 +1,8 @@
-/**
-@module
-## Overview
-
-MicroComponents (MC) is a lightweight pattern for creating self-contained, event-driven, and composable UI components. It provides two core base classes: {@link MC} and {@link DC}, which differ primarily in their target attachment strategy and runtime environment requirements.
-
-In general, your code extends from either of these classes depending on whether you need DOM interaction or pure logic encapsulation.
-
----
-
-## MC vs DC: Server vs Client
-
-The key distinction between the two base classes is their execution context:
-
-- **MC (MicroComponent)** – A general-purpose component that works in **any JavaScript environment**, including server-side runtimes (Node.js, Deno, etc.). It does not require a DOM and can be used for business logic, state management, or as a lightweight container. The `target` parameter is optional.
-
-- **DC (DOM Component)** – A DOM-centric component that operates wherever a real ( browser ) or simulated ( jsdom, etc. ) DOM exists. It attaches itself to an {@link HTMLElement} and provides event handling, DOM traversal, and lifecycle management. The `target` parameter is required and must be an HTMLElement.
-
-**HINT:** DCs can be attached to **any** DOM node ( HTMLElement ). That is you can connect them to <div>, <span> and the like. With a trick you can even define custom elements that convert themselves to e.g. a plain <div>.
-
-### When to use which?
-
-| Scenario | Recommended Class |
-|----------|-------------------|
-| Server-side rendering or logic | MC |
-| Pure data processing without DOM | MC |
-| Interactive UI elements in the browser | DC |
-| Event-driven components attached to HTML nodes | DC |
-
----
-
-## The `target` Property: Backreference Concept
-
-Both MC and DC store a reference to their **host object** via the internal `_target` property (exposed as the `target` getter). This is a *backreference* — it points back to the object that contains or hosts this component instance.
-
-- For **DC instances**, `this.target` refers to the {@link HTMLElement} in the DOM (or testing DOM such as jsdom) to which the component is attached.
-- For **MC instances**, `this.target` can be any arbitrary object, allowing flexible composition patterns.
-
-The reference is held via a `WeakRef` ([MDN WeakRef](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef)) internally to avoid circular references and prevent memory leaks.
-
----
-
-## DOM Integration: The `_mc` Property and `data-mc` Attribute
-
-When a DC is attached to an element via {@linkcode DC.add}, two things happen:
-
-1. The element gains a `_mc` property (of type {@link McHost}) that holds references to all attached microcomponents, keyed by their unique identifiers.
-2. The element receives a `data-mc` attribute, signaling that it hosts at least one microcomponent. This attribute is used internally for DOM queries and selectors.
-
-This `_mc` property is the **only** interference with the native DOM structure, ensuring compatibility with other frameworks or libraries.
-
----
-
-## Lifecycle & Automatic Event Handler Attachment
-
-DC instances automatically trigger an `"Init"` lifecycle event asynchronously after construction. Additionally, methods prefixed with `on` or `one` (e.g., `onClick`, `oneUpdate`) are auto-attached as event listeners on the target element, supporting both native HTML events and custom microcomponent events.
-
----
-
-
-@example Understanding target in DC
-
-javascript:
-```javascript
-import { DC } from '@twobirds/microcomponents';
-
-class MyButton extends DC {
-    constructor(target: HTMLElement) {
-        super(target);
-    }
-
-    logTarget() {
-        // this.target is the <button> element itself
-        console.log(this.target.tagName); // "BUTTON"
-    }
-}
-
-const btn = document.querySelector('button');
-if (btn) {
-    const host = DC.add(btn, 'myButton', new MyButton(btn));
-    host._mc.myButton.logTarget();
-}
-```
-
-@example Understanding target in MC
-
-
-```javascript
-import { MC } from '@twobirds/microcomponents';
-
-class Counter extends MC {
-    private count = 0;
-
-    constructor(target?: object) {
-        super(target);
-    }
-
-    increment() {
-        this.count++;
-    }
-
-    getCount() {
-        return this.count;
-    }
-}
-
-// Works without any DOM — usable on server or client
-const counter = new Counter();
-counter.increment();
-console.log(counter.getCount()); // 1
-```
-
-@example Usage
-
-Below is a complete example demonstrating how to create, attach, and interact with a custom microcomponent:
-
-html before:
-```html
-<div id="container"></div>
-```
-
-javascript:
-```javascript
-import { DC } from '@twobirds/microcomponents';
-
-// 1. Create a custom micro component class extending DC
-class HelloWorld extends DC {
-    constructor(target: HTMLElement) {
-        super(target);
-    }
-
-    greet() {
-        console.log('Hello World');
-    }
-}
-
-// 2. Get an element from the DOM
-const element = document.getElementById('container')!;
-
-// 3. Attach the micro component instance to the target element
-DC.add(element, 'helloWorld', new HelloWorld(element));
-
-// 4. Invoke methods on the attached component
-element._mc.helloWorld.greet(); // "Hello World"
-```
-
-html after:
-```html
-<div id="container" data-mc></div>
-```
-
-The `data-mc` attribute indicates that this element contains at least one microcomponent. The `_mc` property provides direct programmatic access to the attached instances.
-
----
-
-*/
 'use strict';
 import { loadAssets, processAssets } from '../utils/helpers.js';
 import { trigger, on, one, off } from '../utils/events.js';
-import { isMcDOM } from './mcGuards.js';
-export { isMcDOM } from './mcGuards.js';
+import { isMcHost } from './mcGuards.js';
+export { isMcHost } from './mcGuards.js';
 function add(targetHTMLElement, key, element = {}) {
     const node = targetHTMLElement;
     // create the _mc property if necessary ('in' is tested on the unwidened
@@ -287,11 +131,63 @@ function findMcAncestor(from, key) {
     return null;
 }
 /**
-The base class for all microcomponents.
+The base class for all microcomponents — shared root of both {@link MC} and {@link DC}.
+
+Holds a `WeakRef` to the target (a DOM element for `DC`, or any plain object for `MC`)
+to avoid circular references. For `DC` subclasses it also bootstraps two automatic
+behaviours:
+
+1. **Event listener auto-attachment** — methods whose names start with `on` or `one`
+   (e.g. `onClick`, `oneInit`) are wired to the target element via {@link on} / {@link one}.
+2. **"Init" lifecycle event** — dispatched asynchronously in a microtask so that all
+   synchronous constructor work finishes first.
+
+Both mechanisms run only when the instance is a `DC` (checked with `instanceof DC`).
+Plain `MC` instances skip them entirely, keeping server-side usage lightweight.
 
-Implements a `WeakRef` to the target DOM element or other data, avoiding
-circular references. Automatically triggers the "Init" lifecycle event and
-attaches listeners via `autoAttachListeners` upon construction.
+### Plugin extension points
+
+The prototype of `McBase` is the attachment point for optional plugins that curry
+additional instance methods onto every microcomponent. Two built-in plugins modify
+this class at runtime:
+
+- **{@link State.observePlugin}** — adds `notify()`, `subscribe()`, and `bind()` so that
+  observable properties can be controlled directly on the component instance with
+  fluent chaining. Call `observePlugin(DC)` once at module level to activate.
+
+- **{@link State.formValuePlugin}** — adds `formValues()` for two-way binding between DOM
+  form controls and an observable property. Also pulls in all methods from
+  {@link State.observePlugin}, so you can chain `.subscribe()` and `.bind()` after
+  `.formValues()`. Call `formValuePlugin(DC)` once at module level to activate.
+
+Both plugins are idempotent — calling them multiple times has no side effects. They
+work by assigning methods onto `McBase.prototype` (reached via
+`Object.getPrototypeOf(Class.prototype)`) and use TypeScript module augmentation
+(`declare module`) so the added signatures appear in type-checking automatically.
+
+@template TTarget - The concrete type of the wrapped target; preserved by the
+    {@link McBase.target} getter.
+
+@example Extending with plugins at runtime
+
+```ts
+import { DC, observePlugin, formValuePlugin } from '@twobirds/microcomponents';
+
+observePlugin(DC);       // adds notify(), subscribe(), bind() to McBase.prototype
+formValuePlugin(DC);     // adds formValues() (and re-runs observePlugin)
+
+class MyForm extends DC {
+    data = { name: '' };
+
+    oneInit() { // runs once after the constructor
+        this
+        .formValues(this.target, 'data')
+        .subscribe('data', (v) => console.log(v))
+        .bind('data', this.target);
+    }
+}
+```
+@group Micro Components
 */
 class McBase {
     _target; // avoid circular reference
@@ -339,6 +235,7 @@ for logic not directly tied to DOM elements.
 
 @template TTarget - The concrete type of the wrapped target data; preserved by
     the `target` getter, so `new MC({ some: 'data' }).target.some` stays typed.
+@group Micro Components
 */
 class MC extends McBase {
     /**
@@ -351,19 +248,224 @@ class MC extends McBase {
     }
 }
 /**
+@class DC
+---
+
 A DOM-centric microcomponent that operates on a specific HTML element.
 
-Extends `McBase` and associates itself with an actual DOM node via the
+Extends {@link McBase} and associates itself with an actual DOM node via the
 `_target` reference. Provides methods for event handling, DOM traversal,
 and interaction with sibling or ancestor microcomponents.
 
+---
+
+## Static Configuration Properties
+
+DC classes support three static properties that configure custom elements
+before any instance is constructed:
+
+### `static tag?: string`
+
+Replaces the default target element with a semantic HTML element, or removes it entirely.
+
+- **Non-empty string** (e.g., `'header'`) — the original custom element is replaced
+  with the specified built-in element. The original tag name is added as a CSS class.
+- **Empty string `''`** — the target element is removed from the DOM entirely.
+  Useful for components that only inject global styles or act as style containers.
+
+@example static tag — replace with semantic element
+
+```ts
+class ShopHeader extends DC {
+    static tag = 'header';
+}
+defineCE('shop-header', ShopHeader);
+```
+
+Produces `<header class="shop-header">` instead of `<shop-header>`.
+
+@example static tag — remove element entirely
+
+```ts
+class GlobalStyles extends DC {
+    static tag = '';
+}
+defineCE('global-styles', GlobalStyles);
+```
+
+The element self-destructs; only side effects (e.g., injected styles) remain.
+
+### `static assets: string[]`
+
+Declares companion files for auto-loading by convention. Asset names are camelCase
+and translated into file extensions: `'targetHtml'` → `.target.html`, `'json'` → `.json`.
+
+The path is derived from the custom element tag segments, and the basename is the
+last segment. For `<cart-container-checkout>`, assets load from `/cart/container/checkout.*`.
+
+When assets finish loading, an `'assets'` event fires so that `oneAssets(ev)` can
+process them. Everything ending in `Json` arrives parsed; all other files arrive as text.
+
+@example static assets with autoload
+
+```ts
+class CartCheckout extends DC {
+    static assets = ['targetHtml', 'targetCss', 'configJson'];
+
+    oneAssets(ev) {
+        const { configJson } = ev.detail.data;
+        console.log(configJson); // parsed JSON object
+    }
+}
+defineCE('cart-checkout', CartCheckout);
+```
+
+### `static attributes?: object`
+
+Sets HTML attributes on every instance automatically.
+
+@example static attributes
+
+```ts
+class ProductCard extends DC {
+    static attributes = { role: 'listitem' };
+}
+defineCE('product-card', ProductCard);
+```
+
+Every `<product-card>` carries `role="listitem"`.
+
+### Combined usage
+
+All three can be combined in one class:
+
+@example All static properties together
+
+```ts
+class ShopCatalog extends DC {
+    static tag = 'section';
+    static attributes = { role: 'list', 'aria-label': 'products' };
+    static assets = ['targetHtml', 'targetCss'];
+}
+defineCE('shop-catalog', ShopCatalog);
+```
+
+Produces `<section role="list" aria-label="products">`.
+
+---
+
+## Event Handler Conventions
+
+Methods whose names start with `on` or `one` are automatically wired as event listeners
+on the target element. The prefix determines persistence:
+
+- **`on<EventName>`** — persistent listener (fires every time)
+- **`one<EventName>`** — one-time listener (fires once, then detaches)
+
+### Web Component Lifecycle Events
+
+When a DC is registered via {@link defineCE}, the custom element dispatches these
+internal events that can be caught with handler methods:
+
+| Method | When it fires |
+|--------|---------------|
+| `onConnected()` | Element was inserted into the DOM (`connectedCallback`) |
+| `onDisconnected()` | Element was removed from the DOM (`disconnectedCallback`) |
+| `onAdopted()` | Element was moved to a new document (`adoptedCallback`) |
+| `onAttributeChanged()` | An observed attribute changed (`attributeChangedCallback`) |
+| `oneInit()` | Constructor finished; all synchronous setup complete (microtask) |
+
+@example Event handlers in action
+
+```ts
+class MyElement extends DC {
+    onConnected() {
+        console.log('entered the DOM');
+    }
+
+    onDisconnected() {
+        console.log('left the DOM');
+    }
+
+    onClick() {
+        this.trigger('something', 'payload');
+    }
+
+    oneSomething(ev) {
+        console.log('first time only:', ev.detail.data);
+    }
+}
+defineCE('my-element', MyElement);
+```
+
+---
+
+## Construction Patterns
+
+### Template usage (declarative)
+
+```ts
+class MyElement extends DC {}
+defineCE('my-element', MyElement);
+// Use in HTML: <my-element></my-element>
+```
+
+### Programmatic construction with data
+
+When constructing programmatically via {@link getCE}, pass only the `data` payload —
+the target element is created automatically by the custom element constructor.
+
+@example Programmatic construction
+
+```ts
+class MyElement extends DC {
+    data = {};
+
+    constructor(target, data) {
+        super(target);
+        this.data = data;
+    }
+}
+defineCE('my-element', MyElement);
+
+const Ctor = getCE('my-element');
+document.body.append(new Ctor({ name: 'John' }));
+```
+
+### Data from HTML attributes
+
+@example Reading data from an attribute
+
+```ts
+class MyElement extends DC {
+    data = {};
+
+    constructor(target) {
+        super(target);
+        this.data = JSON.parse(target.getAttribute('my-data'));
+    }
+}
+defineCE('my-element', MyElement);
+// Use in HTML: <my-element my-data='{"name":"John"}'></my-element>
+```
+
+---
+
+## Plugin Extension Points
+
+The prototype of `DC` (inherited from {@link McBase}) is extended at runtime by optional
+plugins. See the {@link McBase} documentation for details on {@link State.observePlugin} and
+{@link State.formValuePlugin}.
+
 @template T - The concrete element type of the host element.
 @template EM - The component's custom event map (`event name → payload type`).
     Declaring it registers events on the type level: `trigger()` enforces the
     payload for registered names, and `on()`/`one()` handlers receive
     `CustomEvent<McDetail<Payload>>` with no annotation needed. Unregistered
     names keep the open `unknown`-payload behavior.
-@example
+
+@example Typed event map
+
 ```ts
 class Cart extends DC<HTMLFormElement, { CartUpdate: { count: number } }> {
     checkout() {
@@ -372,14 +474,47 @@ class Cart extends DC<HTMLFormElement, { CartUpdate: { count: number } }> {
     }
 }
 ```
+@group Micro Components
 */
 class DC extends McBase {
+    /**
+     * Replaces the target element with a semantic HTML tag, or removes it entirely.
+     * Set to `'header'` to swap `<my-element>` for `<header>`, or `''` to self-destruct.
+     */
     static tag;
+    /**
+     * Result container for assets (e.g., `['targetHtml', 'json']`).
+     * Asset names (keys) are camelCase and translated into file extensions: `'targetHtml'` → `.target.html`.
+     */
+    static _assets = {};
+    /**
+     * Declares companion files for auto-loading by convention (e.g., `['targetHtml', 'json']`).
+     * Asset names are camelCase and translated into file extensions: `'targetHtml'` → `.target.html`.
+     */
     static assets = [];
+    /**
+     * Sets HTML attributes on every instance automatically.
+     * Example: `{ role: 'listitem', 'aria-label': 'nav' }`.
+     */
     static attributes = {};
+    /**
+     * Constructs a new DC instance and applies static configuration.
+     *
+     * The constructor performs these steps in order:
+     * 1. Calls {@link McBase} to establish the target reference and auto-attach listeners.
+     * 2. If `static tag` is set and differs from the current element, replaces the target
+     *    with a new built-in element (or removes it if `tag === ''`).
+     * 3. If `static assets` has entries, initiates asynchronous loading, fires an `'assets'` event when complete handled by `oneAssets(ev)`.
+     * 4. Applies any `static attributes` to the target element.
+     *
+     * @param target - The host DOM element this component operates on.
+     */
     constructor(target) {
         super(target);
         const ctor = this.constructor;
+        // do not run on '_mc' property
+        if (ctor === DC)
+            return;
         const tagName = this.target.tagName.toLowerCase();
         // work on tag:
         if (ctor['tag'] !== undefined && tagName !== ctor.tag && ctor.tag !== '') {
@@ -394,32 +529,75 @@ class DC extends McBase {
             }
             return;
         }
-        // work on assets:
-        if (ctor.assets.length) {
-            // - initiate loading...
-            loadAssets(tagName, ctor.assets)
-                // - returns a promise, .then( ()=>{ this.trigger('render') } )
+        // work on attributes
+        const attributes = ctor.attributes;
+        if (ctor.attributes) {
+            Object.keys(ctor.attributes).forEach((key) => {
+                this.target.setAttribute(key, attributes[key]);
+            });
+        }
+        /*
+        work on assets
+        */
+        // if predefined assets exist get list of not pre-defined ones
+        const remainingAssets = ctor.assets.filter((key) => !ctor._assets[key]);
+        // oxlint-disable-next-line typescript/no-this-alias
+        const that = this;
+        // process existing assets
+        if (ctor.hasOwnProperty('_assets')) {
+            processAssets(this, ctor._assets);
+        }
+        else if (ctor.assets.length && !ctor.hasOwnProperty('_assets')) {
+            ctor._assets = {};
+        }
+        // autoload and process remaining assets
+        if (remainingAssets.length) {
+            loadAssets(tagName, remainingAssets)
                 .then((res) => {
-                const assets = Object.fromEntries(ctor.assets.map((key, i) => [key, res[i]]));
-                processAssets(this, assets);
-                this.trigger('assets', assets);
+                const loadedAssets = {};
+                remainingAssets.forEach((key, i) => {
+                    loadedAssets[key] = res[i];
+                });
+                processAssets(this, loadedAssets);
+                ctor._assets = Object.assign({}, ctor._assets, loadedAssets);
+                that.trigger('assets', ctor._assets);
             });
-            // - in the component, have a method onRender(){ ... }
-            // - no explicit async needed in component code
         }
+        else if ([...Object.keys(ctor._assets)].length) {
+            queueMicrotask(() => that.trigger('assets', ctor._assets));
+        }
+        // remove empty tag
         if (ctor.tag === '') {
             this.target.remove();
             return;
         }
         ;
-        // work on attributes
-        const attributes = ctor.attributes;
-        if (ctor.attributes) {
-            Object.keys(ctor.attributes).forEach((key) => {
-                this.target.setAttribute(key, attributes[key]);
-            });
-        }
     }
+    /**
+    Returns the loaded assets for this component instance.
+
+    Assets are loaded asynchronously when `static assets` is defined on the class.
+    This method returns the resolved asset map keyed by filename, or `undefined`
+    if assets have not yet been loaded.
+
+    @returns A record mapping asset keys to their content strings, or undefined.
+    */
+    getAssets() {
+        return this.constructor._assets || {};
+    }
+    /**
+    Static helper to attach a microcomponent instance to a DOM element.
+    
+    Wrapper around the `add()` utility function, providing a class-level API
+    for adding child microcomponents to a target node.
+    
+    @template T - The concrete element type of the target; preserved in the return type.
+    @template K - The literal registration key; becomes a known entry of the returned `_mc` registry.
+    @template E - The type of the attached element; retrievable as `result._mc[key]`.
+    @param target - The DOM element to which to attach the microcomponent.
+    @param key - The property name/key under which to store the instance in `_mc`.
+    @returns The target DOM element with the attached microcomponent.
+    */
     static add(target, key, element = {}) {
         return add(target, key, element);
     }
@@ -460,17 +638,50 @@ class DC extends McBase {
     ```
     */
     static get(element, key, elementMcClass) {
-        if (!isMcDOM(element))
+        if (!isMcHost(element))
             return undefined;
         const entry = element._mc[key];
         return entry instanceof elementMcClass ? entry : undefined;
     }
+    /**
+    Detaches an event listener from the DOM node.
+
+    This is an instance method wrapper for `off()`, using the internal `_target` DOM reference.
+
+    @param eventName - The name of the event (e.g., 'click', 'update').
+    @param handler - The previously attached callback function or object to remove.
+    */
     off(eventName, handler) {
         off(this.target, eventName, handler);
     }
+    /**
+    Attaches a persistent event listener to the DOM node.
+    
+    This is an instance method wrapper for `on()`, using the internal `_target` DOM reference.
+    
+    The handler receives a `CustomEvent<McDetail<Payload>>`. For event names
+    registered in the component's event map `EM` the payload is resolved from the
+    map — an unannotated arrow handler is fully typed. For unregistered names the
+    payload defaults to `unknown` and can be pinned via the type argument
+    (`on<Payload>('Name', handler)`) or the handler's own annotation.
+    
+    @param eventName - The name of the event (e.g., 'click', 'update').
+    @param handler - The callback function or object to invoke.
+    @returns The attached handler reference, unchanged — usable directly with {@link off}.
+    */
     on(eventName, handler) {
         return on(this.target, eventName, handler);
     }
+    /**
+    Attaches a one-time event listener to the DOM node.
+    
+    This is an instance method wrapper for `one()`, using the internal `_target` DOM reference.
+    Payload typing follows the same rules as {@link DC.on}.
+    
+    @param eventName - The name of the event (e.g., 'click', 'update').
+    @param handler - The callback function or object to invoke once.
+    @returns The attached one-time handler reference, unchanged — usable directly with {@link off}.
+    */
     one(eventName, handler) {
         return one(this.target, eventName, handler);
     }
@@ -491,6 +702,18 @@ class DC extends McBase {
     trigger(eventName, data = {}, bubble = 'l', controller) {
         trigger(this.target, eventName, data, bubble, controller);
     }
+    /**
+    Returns an array of all ancestor microcomponents up the DOM tree.
+
+    Traverses upward from this element's target, collecting the `_mc` instances
+    of ancestor elements marked with `data-mc`. The keyed form only collects
+    hosts whose registry carries `key`, typed from the global {@link McRegistry}
+    binding — non-optional, since presence is checked during the walk.
+
+    @template R - Known registry entries of the results; pass a record to assert
+        a site-specific shape: `ancestors<{ cart: Cart }>()`. Defaults to none.
+    @returns An array of ancestor microcomponent instances (empty if none found).
+    */
     ancestors(key) {
         const result = [];
         let current = findMcAncestor(this.target, key);
@@ -500,13 +723,46 @@ class DC extends McBase {
         }
         return result;
     }
+    /**
+    Returns the closest ancestor microcomponent or null if none found.
+
+    This method is equivalent to calling `ancestors()[0]`, but more concise.
+    The keyed form walks up to the nearest host whose registry carries `key`,
+    typed from the global {@link McRegistry} binding — non-optional, since
+    presence is checked during the walk.
+
+    @template R - Known registry entries of the result; pass a record to assert
+        a site-specific shape: `closest<{ cart: Cart }>()?.cart.addItem(...)`.
+        Defaults to none.
+    @returns The nearest matching ancestor's `_mc`, or null if not found.
+    */
     closest(key) {
         return findMcAncestor(this.target, key);
     }
+    /**
+    Returns an array of direct child microcomponents.
+
+    Calls `getMcChildNodes()` internally to find immediate descendants only,
+    excluding nested grandchildren and deeper levels. The keyed form filters to
+    hosts whose registry carries `key`; see {@link DC.closest}.
+
+    @template R - Known registry entries of the results; see {@link DC.closest}.
+    @returns An array of child microcomponent instances (empty if none found).
+    */
     children(key) {
         const kids = getMcChildNodes(this.target);
         return key === undefined ? kids : kids.filter((mc) => key in mc);
     }
+    /**
+    Returns an array of all descendant microcomponents recursively.
+
+    Uses a `querySelectorAll` query to collect every nested element marked with
+    `data-mc`, returning their associated `_mc` instances. The keyed form
+    filters to hosts whose registry carries `key`; see {@link DC.closest}.
+
+    @template R - Known registry entries of the results; see {@link DC.closest}.
+    @returns An array of descendant microcomponent instances (empty if none found).
+    */
     descendants(key) {
         const hosts = Array.from(this.target.querySelectorAll('[data-mc]'));
         const mcArray = hosts