@twobirds/microcomponents 0.9.0 → 0.10.1

package/dist/core/MC.js

@@ -1,837 +0,0 @@
-'use strict';
-import { loadAssets, processAssets } from '../utils/helpers.js';
-import { trigger, on, one, off } from '../utils/events.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
-    // element — testing the McHost-cast alias would narrow it to never)
-    if (!('_mc' in targetHTMLElement)) {
-        node._mc = new DC(targetHTMLElement);
-    }
-    // the public registry type has no string index signature; the dynamic write
-    // goes through a keyed view of the same object
-    const _mc = node._mc;
-    // add the element with the given property key to the _mc property
-    if (key.length && !_mc[key]) {
-        _mc[key] = element;
-        // add attribute if HTMLElement
-        if (targetHTMLElement instanceof HTMLElement && !targetHTMLElement.getAttribute('data-mc')) {
-            targetHTMLElement.setAttribute('data-mc', '');
-        }
-    }
-    return node;
-}
-/**
-Removes a named microcomponent from the internal `_mc` collection of a target DOM node.
-
-This function deletes the specified key from the element's `_mc` hash object and, if the
-collection becomes empty, removes the `data-mc` attribute from the DOM node.
-
-The bare poisoned value (`el._mc.gone` without member access) is `never`,
-which is assignable to anything — only member/method use of a removed entry is caught.
-
-@template T - A plain or already-enhanced element type.
-@template K - The literal registration key; its entry is poisoned in the registry type.
-@param target - The DOM element whose microcomponent should be removed.
-@param key - The property name/key corresponding to the microcomponent to remove.
-*/
-function remove(target, key) {
-    if (!key)
-        return; // silent fail
-    const node = target;
-    // keyed view: the public registry type has no string index signature
-    const _mc = node._mc;
-    if (!_mc)
-        return;
-    // delete the property from the HTMLElement _mc collection
-    if (_mc[key]) {
-        delete _mc[key];
-    }
-    // remove the _mc attribute if the DOM collection is empty
-    if (!Object.keys(_mc).length && target instanceof HTMLElement && target.hasAttribute('data-mc')) {
-        target.removeAttribute('data-mc');
-    }
-}
-/**
-Runs the "Init" lifecycle event on a DOM microcomponent instance asynchronously.
-
-This function schedules the `trigger('Init')` call in a microtask, ensuring
-that all synchronous initialization is complete before the lifecycle hook
-executes. Only `DC` instances have an Init lifecycle — the `McBase`
-constructor calls this exclusively behind an `instanceof DC` check, so the
-signature encodes that invariant instead of re-checking it at runtime.
-
-@param element - The DOM microcomponent instance on which to trigger the Init event.
-*/
-function init(element) {
-    queueMicrotask(() => {
-        element.trigger('Init', null);
-    });
-}
-/**
-Attaches event listeners to DOM elements based on method naming conventions.
-
-Scans the prototype of the provided element and attaches listeners for methods
-prefixed with `on` or `one`, corresponding to either native HTML events (e.g.,
-'onclick') or microcomponent-prefixed custom events (e.g., '_mcUpdate').
-
-@param element - The instance whose prototype should be scanned for event handlers.
-*/
-function autoAttachListeners(element) {
-    const sourceTarget = element.target;
-    const prototype = Object.getPrototypeOf(element);
-    const sourceElement = element;
-    const definedEventHandlerNames = Object.getOwnPropertyNames(prototype).filter((key) => /^(on[A-Z]|one[A-Z])/.test(key) && typeof prototype[key] === 'function');
-    for (const eventHandlerName of definedEventHandlerNames) {
-        const once = /^one/.test(eventHandlerName);
-        const eventName = eventHandlerName.replace(/^one?/, ''); // preserves upper/lowercase for non-native events
-        const listener = (ev) => sourceElement[eventHandlerName](ev);
-        on(sourceTarget, eventName, listener, once);
-    }
-}
-/**
-Retrieves immediate child microcomponents of a DOM node.
-
-Queries the DOM for descendant elements marked with `data-mc` that are direct
-children of the provided element and returns their associated `_mc` instances.
-
-@param domNode - The DOM element whose child microcomponents to find.
-@returns An array of child microcomponent instances.
-*/
-function getMcChildNodes(domNode) {
-    const selector = '[data-mc]:not(:scope [data-mc] [data-mc])';
-    const childMcElements = Array.from(domNode.querySelectorAll(selector))
-        .filter((e) => e instanceof HTMLElement && '_mc' in e)
-        .map((e) => e._mc);
-    return childMcElements;
-}
-/**
-Walks up the DOM from `from`, returning the `_mc` controller of the nearest
-`data-mc` ancestor — restricted, when `key` is given, to hosts whose registry
-actually carries that key. Hosts marked `data-mc` but not (yet) carrying an
-`_mc` record (e.g. autoload pending) are skipped rather than returned.
-
-@param from - The element whose ancestors to search (exclusive).
-@param key - Optional registry key the ancestor's `_mc` must contain.
-@returns The nearest matching controller, or null.
-*/
-function findMcAncestor(from, key) {
-    let el = from.parentElement?.closest('[data-mc]');
-    while (el instanceof HTMLElement) {
-        /* v8 ignore next */
-        if ('_mc' in el) {
-            const mc = el._mc;
-            if (key === undefined || key in mc)
-                return mc;
-        }
-        el = el.parentElement?.closest('[data-mc]');
-    }
-    return null;
-}
-/**
-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.
-
-### 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);
-formValuePlugin(DC);
-
-class MyForm extends DC {
-    data = { name: '' };
-
-    oneInit() {
-        this
-        .formValues(this.target, 'data')
-        .subscribe('data', (v) => console.log(v))
-        .bind('data', this.target);
-    }
-}
-```
-
-`observePlugin(DC)` adds `notify()`, `subscribe()`, `bind()` to `McBase.prototype`;
-`formValuePlugin(DC)` adds `formValues()` and re-runs `observePlugin`. `oneInit()`
-runs once after the constructor.
-@group Micro Components
-*/
-class McBase {
-    _target; // avoid circular reference
-    /**
-    The constructor for the base `McBase` class.
-    
-    Initializes a weak reference to the target and triggers auto-attachment
-    of listeners and initialization lifecycle events.
-    
-    @param target - The object or element this microcomponent represents.
-    */
-    constructor(target) {
-        this._target = new WeakRef(target || {});
-        if (this instanceof DC && this.constructor !== DC) {
-            autoAttachListeners(this);
-            const tag = this.constructor.tag;
-            if (tag === undefined || tag.toUpperCase() === this.target.tagName) {
-                init(this);
-            }
-        }
-    }
-    /**
-    Returns the current target object (DOM node or other data) referenced by this microcomponent.
-    
-    Uses a `WeakRef` internally to avoid circular references, and safely dereferences it here.
-    
-    The dereference is asserted non-null: the controller is stored on its target
-    (`element._mc`), so any code that can reach the controller through the element is
-    holding the target alive. Only a controller retained independently after its element
-    was garbage-collected could observe a stale reference — do not cache controllers
-    detached from their elements.
-
-    @returns The target object.
-    */
-    get target() {
-        return this._target.deref();
-    }
-}
-/**
-A general-purpose base microcomponent that does not require a DOM target.
-
-Inherits from `McBase`, but is primarily used as a lightweight container or
-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 {
-    /**
-    Constructs an instance of the general-purpose microcomponent.
-    
-    @param target - Target object or data.
-    */
-    constructor(target) {
-        super(target);
-    }
-}
-/**
-@class DC
----
-
-A DOM-centric microcomponent that operates on a specific HTML element.
-
-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.
-
-**One-time global styles**: Assets named `'css'` and `'targetCss'` inject CSS into the
-global document scope via `injectCSS(document, ...)`. Because these are idempotent
-global side effects, they are processed only once — after the first instance loads them,
-the entries are removed from both `static assets` and `static _assets`. Subsequent
-instances skip loading and re-processing them entirely.
-
-**CSS file roles**:
-
-- `.css` — design tokens only (CSS custom-property presets). Injected into the document
-  scope once, like `targetCss`.
-- `.target.css` — layout rules for the light DOM. Also document-scoped and one-time.
-- `.shadow.css` — layout rules for the shadow DOM. Injected per instance into the
-  component's own shadow root, so each instance gets its own copy.
-
-Every declared asset — CSS, HTML, JSON — is inlined into `static _assets` at build time by
-the load-assets plugin, so a bundled build performs no fetches at all.
-
-In a bundled build the plain `.css` files are additionally concatenated into a single
-`bundle.css` by the bundling script. That file is a convenience listing of the available
-variables: copy the ones you want to change into your own stylesheet and override them
-there. It is not required at runtime, and it cannot drift from the inlined presets — both
-are read from the same source files.
-
-The runtime decides whether an asset still needs fetching with `!ctor._assets[key]`, so an
-inlined entry must never be an empty string: that would trigger a re-fetch of a file that
-does not exist in a bundled build.
-
-@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);
-    }
-}
-defineCE('cart-checkout', CartCheckout);
-```
-
-`configJson` arrives already parsed into an object.
-
-### `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) |
-| `oneAssets()` | Constructor finished; all assets loaded and available; ev contains assets object |
-
-@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);
-```
-
-The registered element is then used in HTML as `<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);
-```
-
-Used in HTML as `<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 Typed event map
-
-```ts
-class Cart extends DC<HTMLFormElement, { CartUpdate: { count: number } }> {
-    checkout() {
-        this.trigger('CartUpdate', { count: 2 }, 'u');
-        this.on('CartUpdate', (ev) => ev.detail.data.count);
-    }
-}
-```
-
-`trigger()` checks the payload against the registered `CartUpdate` shape, and the `on()`
-handler receives a fully typed `ev`.
-@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 = [];
-    /**
-     * In-flight asset request, cached per class so that instances constructed while
-     * the first fetch is still pending (e.g. in a loop) share a single request
-     * instead of each triggering their own. Resolves to the freshly loaded assets.
-     */
-    static _assetsPromise;
-    /**
-     * 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 !== '') {
-            const element = document.createElement(ctor.tag);
-            element.classList.add(tagName);
-            ctor._originalTag = tagName;
-            DC.add(element, ctor.name, new ctor(element));
-            delete ctor._originalTag;
-            if (tagName.includes('-') && !this.target.isConnected) {
-                this.on('connected', () => this.target.replaceWith(element));
-            }
-            else {
-                this.target.replaceWith(element);
-            }
-            return;
-        }
-        // 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
-        */
-        // oxlint-disable-next-line typescript/no-this-alias
-        const that = this;
-        // assets not yet present in the class-level cache still need fetching
-        const remainingAssets = ctor.assets.filter((key) => !ctor._assets[key]);
-        // apply any assets already cached (preloaded by the build plugin, or loaded
-        // by an earlier instance) to THIS instance's target
-        if (Object.keys(ctor._assets).length) {
-            processAssets(this, ctor._assets);
-        }
-        if (remainingAssets.length) {
-            // fetch once per class: the first instance starts the request and every
-            // instance created while it is still in flight (e.g. in a loop) reuses the
-            // same promise instead of firing a duplicate fetch
-            if (!ctor._assetsPromise) {
-                const elementName = ctor._originalTag || tagName;
-                ctor._assetsPromise = loadAssets(elementName, remainingAssets).then((res) => {
-                    const loadedAssets = {};
-                    remainingAssets.forEach((key, i) => {
-                        loadedAssets[key] = res[i];
-                    });
-                    ctor._assets = Object.assign({}, ctor._assets, loadedAssets);
-                    // one-time global styles: remove 'css' and 'targetCss' from both assets and _assets
-                    for (const onceKey of ['css', 'targetCss']) {
-                        if (loadedAssets[onceKey] !== undefined) {
-                            delete ctor._assets[onceKey];
-                        }
-                    }
-                    ctor.assets = ctor.assets.filter((key) => key !== 'css' && key !== 'targetCss');
-                    return loadedAssets;
-                });
-            }
-            // each instance applies the freshly loaded assets to its own target,
-            // then fires the assets event with the merged cache
-            ctor._assetsPromise.then((loadedAssets) => {
-                processAssets(this, loadedAssets);
-                that.trigger('assets', ctor._assets);
-            });
-        }
-        else if ([...Object.keys(ctor._assets)].length) {
-            queueMicrotask(() => that.trigger('assets', ctor._assets));
-        }
-        // remove empty tag
-        if (ctor.tag === '') {
-            this.target.remove();
-            return;
-        }
-    }
-    /**
-    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);
-    }
-    /**
-    Static helper to remove a named microcomponent from a DOM element.
-
-    Wrapper around the `remove()` utility function, providing a class-level API
-    for removing child microcomponents.
-
-    @template T - A plain or already-enhanced element type.
-    @template K - The literal registration key; its entry is poisoned in the registry type.
-    @param target - The DOM element from which to remove the microcomponent.
-    @param key - The property name/key corresponding to the microcomponent to remove.
-    */
-    static remove(target, key) {
-        remove(target, key);
-    }
-    /**
-    Class-verified entry lookup: returns the component stored under `key` on the
-    element's `_mc` record — but only if it is an instance of `Klass`.
-
-    This is the *sound* retrieval primitive: presence AND type identity are both
-    proven at runtime (`instanceof`), so it needs no global `McRegistry`
-    declaration and stays correct even when different elements use the same key
-    name for different component types. Accepts any value (including
-    `querySelector` results that may be null) — every failure mode returns
-    `undefined`.
-
-    @template E - The component type, inferred from `Klass`.
-    @param element - The value to look the entry up on; anything non-host yields undefined.
-    @param key - The registry key name to look under.
-    @param elementMcClass - The class the entry must be an instance of.
-    @returns The verified instance, or undefined.
-    @example
-    ```ts
-    const cart = DC.get(document.querySelector('form'), 'cart', Cart);
-    cart?.addItem(item);
-    ```
-
-    `cart` is `Cart | undefined` — presence and type identity are both proven by the
-    `instanceof` check inside `get()`, with no global declaration involved.
-    */
-    static get(element, key, elementMcClass) {
-        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);
-    }
-    /**
-    Triggers a custom event on the DOM node and optionally bubbles it.
-    
-    This is an instance method wrapper for `trigger()`, using the internal `_target` DOM reference.
-    
-    For event names registered in the component's event map `EM` the payload type
-    is enforced; unregistered names accept any payload (typed via inference or an
-    explicit `trigger<Payload>(...)` argument).
-    
-    @param eventName - The name of the event (will be prefixed if needed).
-    @param data - Additional data payload attached to `event.detail.data`.
-    @param bubble - Bubbling direction ('l', 'u', 'd' or combinations).
-    @param controller - Optional controller for managing bubbling behavior.
-    */
-    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);
-        while (current) {
-            result.push(current);
-            current = findMcAncestor(current.target, key);
-        }
-        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
-            .filter((e) => e instanceof HTMLElement && '_mc' in e)
-            .map((e) => e._mc)
-            .filter((mc) => key === undefined || key in mc);
-        return mcArray;
-    }
-}
-export { MC, DC, McBase };