@twobirds/microcomponents 0.1.20 → 0.1.23

package/dist/state/observables.js

@@ -0,0 +1,382 @@
+/**
+@module Observables
+
+
+This module provides reactive data binding capabilities using observables,
+enabling automatic DOM updates when underlying data changes.
+
+## Overview
+
+The observable system allows you to make object properties "observable" so that
+registered callbacks are automatically invoked whenever those properties change.
+It's particularly designed for reactive templating and binding data to HTML elements.
+It can also handle simple object properties like strings, boolean and numbers.
+
+## How `observe()` Works
+
+The main function is {@link observe}, which takes an object and makes its properties
+or a specific property observable.
+
+### Simple properties
+
+javascript
+```js
+let person = { name: "John", count: 0 };
+
+observe( person ); // all properties inside are now observables
+
+person.name.subscribe( (name) => {
+  console.log("Name changed:", name);
+});
+
+person.count.subscribe( (count) => {
+  console.log("Count changed:", count);
+});
+
+person.name = "Jane";  // > Name changed: Jane
+person.count += 10;    // > Count changed: 10
+```
+
+### Deep Change Detection
+
+This means that if you modify any of the properties inside an observed object -> all callbacks are triggered.
+
+javascript
+```js
+let obj = { data: { name: "John", count: 0 } };
+
+observe( obj, 'data' ); // make the data property observable
+
+obj.data.subscribe( (data) => {
+  console.log("Data changed:", data);
+});
+
+obj.data.name = "Jane"; // > { data: { name: "Jane", count: 0 } }
+obj.data.count += 10;   // > { data: { name: "Jane", count: 10 } }
+```
+
+### Debounced Notifications
+
+To prevent excessive updates, notifications are debounced briefly:
+
+javascript
+```js
+let obj = observe({ value: 1 });
+for (let i = 0; i < 100; i++) {
+  obj.value++; // Only triggers one callback after all changes complete
+}
+```
+
+## DOM Binding with Placeholders
+
+The observables integrate tightly with placeholder-based templating:
+
+- Elements with `{placeholder}` syntax are scanned for observable data.
+- When observed data changes, matching placeholders in the DOM are updated automatically.
+
+@example
+
+HTML
+```html
+<div class="model {visibility}">
+  Hello {name}! You have {count} messages.
+</div>
+```
+
+Javascript
+```js
+const div = document.querySelector('.model');
+
+const model = observe({
+  data: { name: "Alice", count: 0 },
+  visibility: ''
+});
+
+if (div) {
+  model.data.bind( div );
+}
+
+model.data.count++; // Automatically updates the DOM with new count value
+model.visibility = 'hidden'; // adds the hidden class to the DOM element
+```
+*/
+import { flattenObject, deepEqual, copyGettersSetters, isBrowser } from '../utils/helpers.js';
+import { makePlaceholders } from './placeholders.js';
+import { trigger } from '../core/events.js';
+/**
+Determines if a value is an observable object.
+
+@param value - The value to check.
+@returns `true` if the value is a non-null object, otherwise `false`.
+*/
+function isObservableObject(value) {
+    return value != null && typeof value === 'object';
+}
+// repository for observable class wrappers
+const classRepo = {};
+/**
+Creates a new observable wrapper class for the given value's constructor.
+
+Returns a subclass of the original constructor that implements the Observable interface,
+allowing observation and notification of changes. The new class is cached in `classRepo`.
+
+@param val - The value whose constructor should be wrapped with observable behavior.
+@returns A new Observable class that wraps the original constructor.
+*/
+function makeObservable(val) {
+    const Constructor = val.constructor, ConstructorName = Constructor.name;
+    const ObservableClass = class extends Constructor {
+        #notify = true;
+        #callbacks = [];
+        constructor(valArg) {
+            super(valArg);
+            const ctor = this.constructor;
+            ctor.callbacks = [];
+            if (isObservableObject(valArg)) {
+                // you cannot bind native values to the dom
+                Object.getOwnPropertyNames(valArg).forEach((key) => {
+                    this[key] = valArg[key];
+                });
+            }
+        }
+        get callbacks() {
+            return this.#callbacks;
+        }
+        set callbacks(callbacks) {
+            this.#callbacks = callbacks;
+        }
+        /**
+        Coerces the observable to its underlying primitive value when used in
+        arithmetic, string interpolation, or other contexts requiring a primitive.
+        
+        This allows `observable + 1` or `` `${observable}` `` to work naturally
+        while still exposing `.subscribe()`, `.notify()`, etc. as methods on the object.
+        
+        @param hint - The coercion context: 'number', 'string', or 'default'.
+        @returns The underlying primitive value coerced to the requested type.
+        
+        @example
+        ```ts
+        const state = observe({ count: 42 });
+        console.log(state.count + 10); // 52 (hint === 'number')
+        console.log(`${state.count}`); // "42" (hint === 'string')
+        state.count.subscribe(v => console.log('changed to', v)); // still callable
+        ```
+        */
+        [Symbol.toPrimitive](hint) {
+            const value = this.valueOf();
+            if (hint === 'string')
+                return String(value);
+            if (hint === 'number')
+                return Number(value);
+            return value;
+        }
+        /**
+        Registers a callback function to be invoked when the observable object is notified.
+        
+        @param callback - The function to invoke on notification.
+        @returns This instance for chaining.
+
+        @example
+        ```ts
+        const state = observe({ count: 0 });
+        state.count.subscribe((v) => console.log('count changed to', v));
+        state.count++; // logs: count changed to 1
+        ```
+        */
+        subscribe(callback) {
+            this.#callbacks.push(callback);
+            return this;
+        }
+        /**
+        Removes a previously registered callback so it no longer fires on notify.
+        
+        Detaching by the same function reference that was passed to `subscribe()` —
+        unknown callbacks are a silent no-op. Long-lived subscribers should call
+        this when they are done to avoid leaking callbacks.
+        
+        @param callback - The exact callback reference to remove.
+        @returns This instance for chaining.
+
+        @example
+        ```ts
+        const state = observe({ count: 0 });
+        const log = (v) => console.log(v);
+        state.count.subscribe(log);
+        state.count.unsubscribe(log); // will no longer fire on changes
+        ```
+        */
+        unsubscribe(callback) {
+            this.#callbacks = this.#callbacks.filter((registered) => registered !== callback);
+            return this;
+        }
+        /**
+        Binds the observable to a DOM target, setting up placeholder updates and
+        triggering initial callbacks.
+        
+        Scans the target and its descendants for placeholders and registers handlers
+        to update them with flattened data on notification. Only works in browser environments.
+
+        @param target - The HTMLElement, DocumentFragment, or ShadowRoot to bind.
+        @returns This instance for chaining.
+
+        @example
+        ```ts
+        const state = observe({ name: 'Alice', count: 0 });
+        state.name.bind(document.querySelector('.model')); // updates {name} placeholders in DOM
+        ```
+        */
+        bind(target) {
+            if (!isBrowser())
+                return; // DOM does not exist on the server side
+            const iso = isObservableObject(this.valueOf());
+            if (iso) {
+                makePlaceholders(target);
+                const placeholders = [target, ...target.querySelectorAll('[data-mc]')].filter((e) => {
+                    // _placeholders is only present on already-decorated Mc host nodes.
+                    const node = e;
+                    return !!node?._mc?._placeholders;
+                });
+                const func = function callback(data) {
+                    // avoid bubbling for speed
+                    const flattenedData = flattenObject(data);
+                    placeholders.forEach((node) => {
+                        /* v8 ignore next */
+                        if (!node)
+                            return;
+                        trigger(node, 'data', flattenedData);
+                    });
+                };
+                this.#callbacks.push(func);
+                this.notify();
+            }
+            else {
+                console.warn('IGNORED - cannot bind a non-Object to the dom, IS:', typeof this.valueOf(), this);
+            }
+            return this;
+        }
+        /**
+        Notifies registered callbacks with the current observable data.
+        
+        Clones the internal value (if it's an object and not an array) before passing
+        to callbacks. Respects the internal `#notify` flag that can suppress notifications.
+        
+        @param notify - Optional boolean override for the notification state.
+        @returns This instance for chaining.
+
+        @example
+        ```ts
+        const state = observe({ count: 0 });
+        state.count.subscribe((v) => console.log('notified:', v));
+        state.count.notify(); // logs: notified: 0
+        ```
+        */
+        notify(notify) {
+            const data = isObservableObject(this.valueOf()) && this.valueOf() instanceof Array === false
+                ? structuredClone(Object.assign({}, this))
+                : this.valueOf();
+            if (notify !== undefined) {
+                this.#notify = notify;
+                // return;
+            }
+            if (this.#notify) {
+                this.#callbacks.forEach((f) => {
+                    f(data);
+                });
+            }
+            return this;
+        }
+    };
+    classRepo[ConstructorName] = ObservableClass;
+    return ObservableClass;
+}
+/**
+Retrieves or creates an observable wrapper class for the given value.
+
+@param val - The value whose constructor should be wrapped with observable behavior.
+@returns A class that wraps the original constructor and implements observable functionality.
+*/
+function getConstructor(val) {
+    const key = val.constructor.name;
+    return classRepo[key] || makeObservable(val);
+}
+/**
+Whether a value is already an observable wrapper — `subscribe` is reachable on its prototype chain.
+Used by {@link observe} to skip re-wrapping and to detect the "not yet observed" state on reassignment.
+
+@example
+```ts
+const state = observe({ count: 0 });
+isAlreadyObserved(state.count); // true
+isAlreadyObserved(42);          // false
+```
+*/
+export function isAlreadyObserved(value) {
+    return ((typeof value === 'object' || typeof value === 'function') &&
+        value !== null &&
+        'subscribe' in value);
+}
+export function observe(target, propertyName) {
+    const source = target;
+    const keys = propertyName ? [propertyName] : [...Object.getOwnPropertyNames(target)];
+    keys.forEach((key) => {
+        const current = source[key];
+        if (Object.prototype.hasOwnProperty.call(target, key) &&
+            typeof current !== 'function' &&
+            !isAlreadyObserved(current)) {
+            if (key[0] === '_' || current === undefined)
+                return;
+            const wrappedVal = current;
+            let o = new (getConstructor(wrappedVal))(wrappedVal);
+            const debouncedNotify = function () {
+                queueMicrotask(function () {
+                    o.notify();
+                });
+            };
+            Object.defineProperty(target, key, {
+                enumerable: true,
+                get() {
+                    if (isObservableObject(o.valueOf())) {
+                        const snapshot = structuredClone(Object.assign({}, o));
+                        queueMicrotask(function checkChanges() {
+                            const currentState = structuredClone(Object.assign({}, o));
+                            if (!deepEqual(currentState, snapshot)) {
+                                debouncedNotify();
+                            }
+                        });
+                    }
+                    return o;
+                },
+                set(val) {
+                    if (typeof val === typeof o.valueOf()) {
+                        const iso = isObservableObject(o.valueOf()) && o.valueOf() instanceof Array === false;
+                        if (iso) {
+                            /* v8 ignore next */
+                            if (!isAlreadyObserved(o)) {
+                                /* v8 ignore next */
+                                o = new (getConstructor(val))(structuredClone(Object.assign({}, val)));
+                                /* v8 ignore next */
+                                copyGettersSetters(val, o);
+                            }
+                            Object.assign(o, val); // mixin set object into observable object
+                            o.notify(); // dont test, just assume "changed" status
+                        }
+                        else {
+                            const old = o.valueOf(), callbacks = o.callbacks;
+                            if (val !== old) {
+                                o = new (getConstructor(val))(val);
+                                o.callbacks = callbacks;
+                                debouncedNotify();
+                            }
+                        }
+                    }
+                    else {
+                        console.warn('IGNORED - cannot change observable types, IS:', typeof o.valueOf(), o, '- CANNOT BECOME:', typeof val);
+                    }
+                },
+            });
+            source[key] = wrappedVal; // replace old property with proxy (observable)
+        }
+    });
+    return target;
+}

package/dist/state/placeholders.d.ts

@@ -0,0 +1,62 @@
+/**
+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, type McDetail, type McHost } from '../core/MC.js';
+import { type Observable } from './observables.js';
+/**
+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.
+*/
+declare class Placeholders extends DC {
+    #private;
+    data: Observable<Record<string, unknown>>;
+    oldDisplay?: string;
+    /**
+    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: HTMLElement);
+    /**
+    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: CustomEvent<McDetail<Record<string, unknown>>>): void;
+}
+/**
+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 declare function makePlaceholders(element: HTMLElement | DocumentFragment | ShadowRoot): void;
+/**
+A host element whose `_mc` registry may carry the `_placeholders` entry that
+{@link makePlaceholders} registers. The entry is optional: candidates are tested
+through this type before being decorated.
+*/
+export type PlaceholdersHost = McHost<HTMLElement, {
+    _placeholders?: Placeholders;
+}>;
+export {};
+//# sourceMappingURL=placeholders.d.ts.map

package/dist/state/placeholders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholders.d.ts","sourceRoot":"","sources":["../../src/state/placeholders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;EASE;AAEF,OAAO,EAAE,EAAE,EAAE,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAoD5D;;;;;;EAME;AACF,cAAM,YAAa,SAAQ,EAAE;;IAE5B,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAwD;IACjG,UAAU,CAAC,EAAE,MAAM,CAAM;IAEzB;;;;;;;;MAQE;gBACU,MAAM,EAAE,WAAW;IAkF/B;;;;;;;MAOE;IACF,MAAM,CAAC,EAAE,EAAE,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAOzD;AAmBD;;;;;;;EAOE;AACF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,gBAAgB,GAAG,UAAU,GAAG,IAAI,CAK3F;AAED;;;;EAIE;AACF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,WAAW,EAAE;IAAE,aAAa,CAAC,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC"}

package/dist/state/placeholders.js

@@ -0,0 +1,181 @@
+/**
+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.
+*/
+/* v8 ignore start */
+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) => {
+        const textContent = childNode?.nodeValue || '';
+        const contentPlaceholders = textContent.match(regEx);
+        contentPlaceholders.forEach((textNodePlaceholder) => placeholders.add(textNodePlaceholder.replace(/[\{\}]/g, '')));
+    });
+    return [...placeholders];
+}
+/* v8 ignore end */
+// 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
+        (target.getAttributeNames ? target.getAttributeNames() : [])
+            .filter((attr) => target.getAttribute(attr)?.match(/\{[^\{\}]*\}/g)) // extract placeholder(s)
+            .forEach((attr) => {
+            const placeholders = new Set(target.getAttribute(attr)?.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, '')]));
+                });
+                target.setAttribute(attr, result);
+            })(target.getAttribute(attr) ?? ''));
+        });
+        // 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;
+            const placeholders = new Set((childNode.nodeValue ?? '').match(/\{[^\{\}]*\}/g));
+            // attach callback
+            this.data.subscribe(
+            /* v8 ignore start */
+            ((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;
+            })(childNode.nodeValue ?? '')
+            /* v8 ignore end */
+            );
+            // 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));
+    });
+}