@twobirds/microcomponents 0.9.0 → 0.10.1

package/dist/core/index.js

@@ -1,72 +0,0 @@
-/**
-# 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.
-
-- **DC (DOM Component)** – A DOM-centric component that operates wherever a real ( browser ) or simulated ( jsdom, etc. ) DOM exists. It attaches itself to an 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 | DC |
-| Interactive UI elements in the browser | DC |
-| Event-driven components attached to HTML nodes | DC |
-| Pure logic without DOM | MC |
-
----
-
-## 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 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.
-
----
-# DC Class Specific
----
-
-## DOM Integration
-
-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
-
-- DC instances automatically trigger an `"Init"` lifecycle event asynchronously - using queueMicrotask() - after construction. A component with a 'oneInit()' method will catch that lifecycle event, and when it runs it is guaranteed that the constructor() has run.
-- 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.
-- When using the static `assets` property to on-demand load shadow/target templates and css
-  - those are automatically attached to their respective target locations
-  - and all native event handlers in template code (<button click="...">) are automatically attached also
----
-
-@module Core
-@showGroups
-*/
-/** @group MicroComponents */
-export { MC, DC, McBase } from './MC.js';
-/** @group Elements */
-export { defineCE, getCE, listCE } from './elements.js';
-/** @group Helpers */
-export { isMcHost } from './mcGuards.js';

package/dist/state/index.js

@@ -1,5 +0,0 @@
-/**
-@module State
-*/
-export { observe, observePlugin, isAlreadyObserved } from './observables.js';
-export { formValues, formValuePlugin } from './formValues.js';

package/dist/state/placeholders.js

@@ -1,187 +0,0 @@
-/**
-@hidden
-DOM placeholder binding: `{name}` templates in attributes and text nodes,
-kept up to date from observable data.
-
-Split from observables.ts so the pure observable machinery carries no DOM
-scanning/decoration code. The two modules reference each other only inside
-function bodies (`Placeholders` calls `observe(this)`; `bind()` calls
-{@link makePlaceholders}), never during module evaluation, so the circular
-import is benign under ESM live bindings.
-*/
-import { DC } from '../core/MC.js';
-import { observe } from './observables.js';
-/**
-Extracts placeholder names from an HTML element's attributes and text content.
-
-Placeholders are strings enclosed in curly braces `{}`. This function scans
-all attributes and direct child text nodes of the target element for placeholders
-and returns them as an array of unique names (without braces).
-
-@param target - The HTMLElement to scan for placeholders.
-@returns An array of placeholder names found within the element's attributes and text content.
-*/
-function getPlaceholders(target) {
-    const placeholders = new Set(), regEx = /\{[^\{\}]*\}/g;
-    // scan attributes
-    (target.getAttributeNames ? target.getAttributeNames() : [])
-        .filter((attr) => target.getAttribute(attr)?.match(regEx)) // extract placeholder(s)
-        .forEach((attr) => {
-        const attrPlaceholders = new Set(target.getAttribute(attr)?.match(regEx));
-        attrPlaceholders.forEach((attrPlaceholder) => placeholders.add(attrPlaceholder.replace(/[\{\}]/g, '')));
-    });
-    // scan children text nodes
-    [...target.childNodes]
-        .filter((childNode) => {
-        return (
-        // is text node and has placeholders
-        childNode.nodeType === 3 && (childNode.nodeValue || '').match(regEx));
-    })
-        .forEach((childNode) => {
-        /* v8 ignore next -- the filter above matched nodeValue against the placeholder
-           pattern, so it is non-null and non-empty by the time we get here */
-        const textContent = childNode?.nodeValue || '';
-        const contentPlaceholders = textContent.match(regEx);
-        contentPlaceholders.forEach((textNodePlaceholder) => placeholders.add(textNodePlaceholder.replace(/[\{\}]/g, '')));
-    });
-    return [...placeholders];
-}
-// Tag names instead of constructor references (HTMLInputElement etc.):
-// evaluating those globals at module scope crashes any DOM-less import
-// of the package (e.g. server-side use of MC).
-const inputTags = ['INPUT', 'SELECT', 'TEXTAREA'];
-/**
-A class that manages placeholders within an HTML element and updates them dynamically.
-
-This class extends `DC` (Data Controller) and processes the target element to identify
-placeholder patterns in attributes and text nodes. It then observes changes on its internal
-data object and updates the corresponding DOM locations when notified of changes.
-*/
-class Placeholders extends DC {
-    // observe(this) in the constructor swaps this for the live observable wrapper.
-    data = {};
-    oldDisplay = '';
-    /**
-    Creates a new `Placeholders` instance for the given HTML element.
-    
-    Initializes the internal data with empty strings for each placeholder
-    found in the target and starts observing the data object. Attaches
-    callbacks to update placeholders as needed.
-    
-    @param target - The HTMLElement to process for placeholders.
-    */
-    constructor(target) {
-        super(target);
-        getPlaceholders(target).forEach((property) => (this.data[property] = ''));
-        observe(this);
-        this.#attachCallbacks();
-    }
-    #attachCallbacks() {
-        const target = this.target;
-        let hide = false;
-        // scan attributes
-        /* v8 ignore next -- Placeholders is only ever constructed with an HTMLElement
-           (DC's constructor reads target.tagName), so the fragment/shadow-root guard
-           that getPlaceholders needs is dead here. */
-        const attrNames = target.getAttributeNames ? target.getAttributeNames() : [];
-        attrNames
-            .filter((attr) => target.getAttribute(attr)?.match(/\{[^\{\}]*\}/g)) // extract placeholder(s)
-            .forEach((attr) => {
-            const placeholders = new Set(target.getAttribute(attr)?.match(/\{[^\{\}]*\}/g));
-            /* v8 ignore next -- attr passed the filter above, so its value is a non-null string */
-            const attrTemplate = target.getAttribute(attr) ?? '';
-            // attach callback
-            this.data.subscribe(((template) => (data) => {
-                let result = template;
-                placeholders.forEach((placeholder) => {
-                    result = result.replace(placeholder, 
-                    // JSON.stringify(data[placeholder.replace(/[\{\}]/g, '')])
-                    String(data[placeholder.replace(/[\{\}]/g, '')]));
-                });
-                target.setAttribute(attr, result);
-            })(attrTemplate));
-        });
-        // scan children text nodes
-        [...target.childNodes]
-            .filter((childNode) => {
-            return (
-            // is text node and has placeholders
-            childNode.nodeType === 3 && (childNode.nodeValue || '').match(/\{[^\{\}]*\}/g));
-        })
-            .forEach((childNode) => {
-            hide = true;
-            /* v8 ignore next -- the filter above only admits text nodes with a non-empty
-               nodeValue, so the ?? fallback is unreachable */
-            const textTemplate = childNode.nodeValue ?? '';
-            const placeholders = new Set(textTemplate.match(/\{[^\{\}]*\}/g));
-            // attach callback
-            this.data.subscribe(((template) => (data) => {
-                let result = template;
-                placeholders.forEach((placeholder) => {
-                    result = result.replace(placeholder, 
-                    // JSON.stringify(data[placeholder.replace(/[\{\}]/g, '')])
-                    String(data[placeholder.replace(/[\{\}]/g, '')]));
-                });
-                if (this.oldDisplay) {
-                    target.style = this.oldDisplay;
-                }
-                else {
-                    target.removeAttribute('style');
-                }
-                delete this.oldDisplay;
-                childNode.nodeValue = result;
-            })(textTemplate));
-            // hide for now
-            this.oldDisplay = target.getAttribute('style') || ''; // TBD allow null to indicate there was no old style attribute
-            if (hide && !inputTags.includes(target.tagName) && target.tagName !== 'FIELDSET') {
-                target.style.display = 'none';
-            }
-        });
-    }
-    /**
-    Handles a `data` custom event to update the internal placeholder data.
-    
-    Extracts matching keys from the event's detail data and updates only those
-    properties in the internal `data` object that were previously defined as placeholders.
-    
-    @param ev - The CustomEvent containing new data to merge into the placeholders.
-    */
-    onData(ev) {
-        const data = {};
-        Object.keys(ev.detail.data).forEach((key) => {
-            if (this.data.hasOwnProperty(key))
-                data[key] = ev.detail.data[key];
-        });
-        if (JSON.stringify(data) !== JSON.stringify(this.data))
-            Object.assign(this.data, data); // will trigger callbacks
-    }
-}
-/**
-Finds all elements within a given scope that contain placeholders.
-
-@param target - The HTMLElement, DocumentFragment, or ShadowRoot to search.
-@returns An array of HTMLElements containing placeholder patterns.
-*/
-function getPlaceholderElements(target) {
-    const elements = [target]
-        .concat([...target.querySelectorAll('*')])
-        .filter((e) => !!getPlaceholders(e).length)
-        .filter((e) => e?.tagName !== 'STYLE')
-        .reverse(); // to start with inner elements
-    return elements;
-}
-/**
-Applies placeholder support to an element and its descendants.
-
-This function scans the provided target for elements containing placeholders
-and attaches a `Placeholders` controller instance to each one if not already present.
-
-@param element - The HTMLElement, DocumentFragment, or ShadowRoot to process.
-*/
-export function makePlaceholders(element) {
-    getPlaceholderElements(element).forEach((e) => {
-        if (e?._mc?._placeholders)
-            return;
-        DC.add(e, '_placeholders', new Placeholders(e));
-    });
-}

package/dist/types/index.js

@@ -1 +0,0 @@
-export {};

package/dist/types/mcTypes.js

@@ -1,9 +0,0 @@
-/**
-
-Pure type layer of the microcomponent system.
-
-RULE: types only — no runtime exports, no imports. It sits at the bottom of the
-dependency graph so every other module can import from it without cycles.
-@module Types
-*/
-export {};

package/dist/utils/autoload.js

@@ -1,160 +0,0 @@
-/**
-@module Autoload
-
-The {@linkcode autoload} function enables automatic detection and instantiation of microcomponents in the DOM via a `MutationObserver`. When enabled, newly added elements with undefined custom tags or `data-mc` references will trigger dynamic script loading and component attachment.
-
-Kept in its own module so the core controller classes in MC.ts stay free of
-side-effect-bearing DOM machinery (`MutationObserver`, script injection):
-importing `DC`/`MC` never pulls a DOM observer into the bundle unless
-{@link autoload} itself is imported.
-*/
-import { DC } from '../core/MC.js';
-import { isMcHost } from '../core/mcGuards.js';
-import { resolveComponentPath } from './resolveComponentPath.js';
-const loadingDCs = new Set();
-/**
-Creates a closure that attaches DOM elements with the specified tag name to
-their corresponding microcomponent instances.
-
-Used internally by `makeLoadScript()` when dynamically loading external
-custom element definitions. The returned function is invoked after the
-element definition becomes available, and performs:
-  - Querying of all matching elements in the DOM
-  - Instantiation of new `DC` instances
-  - Attachment to each DOM node via `DC.add()`
-
-@param element - The tag name (custom element name) of the microcomponent to instantiate.
-@returns A closure that performs the attachment logic when invoked.
-@group Autoload
-*/
-function attachDC(element) {
-    return () => {
-        const elements = Array.from(document.querySelectorAll(`[data-mc*="${element}"]`)).filter((e) => e instanceof HTMLElement);
-        if (elements.length === 0)
-            return;
-        const customElementClass = customElements.get(element);
-        for (let node of elements) {
-            try {
-                DC.add(node, customElementClass.name, new customElementClass(node));
-            }
-            catch (error) {
-                /* v8 ignore start */
-                if ('create' in customElementClass && typeof customElementClass.create === 'function') {
-                    const customElement = customElementClass.create(node);
-                    if (!isMcHost(customElement))
-                        throw `create() of Class ${customElementClass.name} did not return a McHost.`;
-                    customElement.setAttribute('data-mc', node.getAttribute('data-mc') ?? '');
-                    node.replaceWith(customElement);
-                    node = customElement;
-                }
-                else {
-                    throw `Class ${customElementClass.name} doesn't have a callable constructor AND class doesn't have a static .create() method.`;
-                }
-                /* v8 ignore end */
-            }
-            const newMcName = node
-                .getAttribute('data-mc')
-                .split(' ')
-                .filter((name) => name !== element && name !== '')
-                .join(' ')
-                .trim();
-            node.setAttribute('data-mc', newMcName);
-        }
-    };
-}
-/**
-Dynamically loads and registers a custom element definition from an external JS file.
-
-Constructs the script URL based on kebab-case naming (e.g., `my-element` → `./my/element.js`).
-Registers a handler to be executed once the element is defined, then appends the
-`<script>` tag to `<head>`. Handles both successful loading and error cases.
-
-@param element - The custom element tag name (e.g., 'mc-button', 'my-widget').
-*/
-function makeLoadScript(element) {
-    /* v8 ignore next */
-    if (loadingDCs.has(element))
-        return; // already loading
-    loadingDCs.add(element);
-    const fileName = resolveComponentPath(element);
-    const scriptElement = document.createElement('script');
-    scriptElement.setAttribute('src', fileName);
-    scriptElement.setAttribute('blocking', 'render');
-    scriptElement.async = true;
-    scriptElement.setAttribute('type', 'module');
-    scriptElement.setAttribute('data-name', element);
-    scriptElement.setAttribute('loading', '');
-    const loadedPromise = customElements.whenDefined(element);
-    loadedPromise.then(attachDC(element));
-    scriptElement.addEventListener('load', (ev) => {
-        loadingDCs.delete(element);
-        document.head.querySelector(`script[data-name="${element}"]`)?.remove();
-    });
-    scriptElement.addEventListener('error', (ev) => {
-        console.error('could not load DC code from', fileName);
-    });
-    document.head.append(scriptElement);
-}
-/**
-Scans the DOM for undefined custom elements and pending microcomponents,
-then loads their definitions if necessary.
-
-This is the main driver function for the autoload mechanism. It performs:
-  1. Finds all undefined custom elements in the document
-  2. Checks whether they are already loading or defined
-  3. Calls `makeLoadScript()` to fetch missing definitions
-  4. Invokes `attachDC()` where element definitions exist but haven't been attached yet
-
-It is called both immediately after enabling autoload and on each DOM mutation.
-*/
-function loadUndefinedMCs() {
-    // load unresolved custom elements
-    [...document.querySelectorAll(':not(:defined)')]
-        .filter((element) => !!element &&
-        !customElements.get(element.tagName.toLowerCase()) && // not in CustomElementsRegistry
-        !loadingDCs.has(element.tagName.toLowerCase()) // not in loading list
-    )
-        .forEach((el) => {
-        makeLoadScript(el.tagName.toLowerCase()); // will automatically be instantiated
-    });
-    // if defined in _mc attribute: instantiate DCs, load if necessary
-    [...document.querySelectorAll('[data-mc]:not([data-mc=""]')]
-        .filter((element) => !!element)
-        .forEach((el) => {
-        const _mc = el
-            .getAttribute('data-mc')
-            ?.split(' ')
-            .filter((name) => name !== '');
-        _mc?.forEach((element) => {
-            const isDefined = customElements.get(element);
-            if (!loadingDCs.has(element) && !isDefined) {
-                makeLoadScript(element);
-            }
-            else if (isDefined) {
-                attachDC(element)();
-            }
-        });
-    });
-}
-let observer = null;
-export function autoload(enable = true) {
-    if (!enable) {
-        if (observer) {
-            observer.disconnect();
-            observer = null;
-        }
-        return false;
-    }
-    const wasEnabled = !!observer;
-    if (wasEnabled)
-        return true;
-    // Initialize observer only once
-    observer = new MutationObserver(loadUndefinedMCs);
-    setTimeout(() => {
-        observer.observe(document.body, { childList: true, subtree: true });
-        loadUndefinedMCs();
-    }, 5);
-    window.autoload ??= autoload;
-    return true;
-}
-autoload.state = loadingDCs;