assign-gingerly 0.0.53 → 0.0.55

package/handlers/microDataJoin.js

@@ -0,0 +1,184 @@
+/**
+ * builtIns.microDataJoin handler for assignFrom.
+ *
+ * Renders a template array as semantic microdata-annotated DOM elements.
+ * Each dynamic value gets an HTML element based on its resolved type,
+ * with itemprop set to the property name.
+ *
+ * This handler is auto-loaded by processHandlerCommands when
+ * `do: 'builtIns.microDataJoin'` is encountered.
+ */
+const MARKER_START_PREFIX = '?start name="';
+const MARKER_END = '?end';
+const MARKER_NAME = 'microDataJoin';
+
+function findMarkers(target) {
+    const startText = `${MARKER_START_PREFIX}${MARKER_NAME}"`;
+    let startMarker = null;
+    let endMarker = null;
+    const walker = document.createTreeWalker(target, NodeFilter.SHOW_COMMENT);
+    let node;
+    while ((node = walker.nextNode())) {
+        if (!startMarker && node.data === startText) {
+            startMarker = node;
+        } else if (startMarker && !endMarker && node.data === MARKER_END) {
+            endMarker = node;
+            break;
+        }
+    }
+    return [startMarker, endMarker];
+}
+
+function createMarkers(target) {
+    const startMarker = document.createComment(`${MARKER_START_PREFIX}${MARKER_NAME}"`);
+    const endMarker = document.createComment(MARKER_END);
+    target.appendChild(startMarker);
+    target.appendChild(endMarker);
+    return [startMarker, endMarker];
+}
+
+function getNodesBetweenMarkers(start, end) {
+    const nodes = [];
+    let current = start.nextSibling;
+    while (current && current !== end) {
+        nodes.push(current);
+        current = current.nextSibling;
+    }
+    return nodes;
+}
+
+function formatForDisplay(value) {
+    if (value instanceof Date) {
+        return value.toLocaleDateString();
+    }
+    if (typeof value === 'number') {
+        return value.toLocaleString();
+    }
+    if (typeof value === 'boolean') {
+        return '';
+    }
+    return String(value ?? '');
+}
+
+function formatForAttribute(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return String(value);
+}
+
+function createElementForValue(prop, value) {
+    if (value instanceof Date) {
+        const el = document.createElement('time');
+        el.setAttribute('itemprop', prop);
+        el.setAttribute('datetime', formatForAttribute(value));
+        el.textContent = formatForDisplay(value);
+        return el;
+    }
+    if (typeof value === 'number') {
+        const el = document.createElement('data');
+        el.setAttribute('itemprop', prop);
+        el.setAttribute('value', formatForAttribute(value));
+        el.textContent = formatForDisplay(value);
+        return el;
+    }
+    if (typeof value === 'boolean') {
+        const el = document.createElement('data');
+        el.setAttribute('itemprop', prop);
+        el.setAttribute('value', String(value));
+        return el;
+    }
+    const el = document.createElement('span');
+    el.setAttribute('itemprop', prop);
+    el.textContent = String(value ?? '');
+    return el;
+}
+
+function updateElement(el, prop, value) {
+    if (value instanceof Date) {
+        el.setAttribute('datetime', formatForAttribute(value));
+        el.textContent = formatForDisplay(value);
+    } else if (typeof value === 'number') {
+        el.setAttribute('value', formatForAttribute(value));
+        el.textContent = formatForDisplay(value);
+    } else if (typeof value === 'boolean') {
+        el.setAttribute('value', String(value));
+    } else {
+        el.textContent = String(value ?? '');
+    }
+}
+
+function processTemplate(template) {
+    const result = [];
+    for (const item of template) {
+        if (Array.isArray(item)) {
+            const hasNull = item.some(el =>
+                el && typeof el === 'object' && 'prop' in el && el.val == null
+            );
+            if (hasNull) continue;
+            result.push(...processTemplate(item));
+        } else if (item == null) {
+            continue;
+        } else {
+            result.push(item);
+        }
+    }
+    return result;
+}
+
+export class MicroDataJoinHandler {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async assign(lhsTarget, resolvedParams) {
+        const { template } = resolvedParams;
+        if (!template || !Array.isArray(template)) {
+            throw new Error('builtIns.microDataJoin: resolve.template must be an array');
+        }
+        if (!(lhsTarget instanceof Element)) {
+            throw new Error('builtIns.microDataJoin: lhsTarget must be a DOM Element');
+        }
+        if (!lhsTarget.hasAttribute('itemscope')) {
+            lhsTarget.setAttribute('itemscope', '');
+        }
+        const processed = processTemplate(template);
+        let [startMarker, endMarker] = findMarkers(lhsTarget);
+        const isUpdate = startMarker !== null && endMarker !== null;
+        if (!isUpdate) {
+            [startMarker, endMarker] = createMarkers(lhsTarget);
+        }
+        if (isUpdate) {
+            const existingNodes = getNodesBetweenMarkers(startMarker, endMarker);
+            let nodeIdx = 0;
+            for (const segment of processed) {
+                if (typeof segment === 'string') {
+                    const node = existingNodes[nodeIdx];
+                    if (node && node.nodeType === Node.TEXT_NODE) {
+                        if (node.textContent !== segment) {
+                            node.textContent = segment;
+                        }
+                    }
+                    nodeIdx++;
+                } else {
+                    const node = existingNodes[nodeIdx];
+                    if (node && node instanceof Element && node.getAttribute('itemprop') === segment.prop) {
+                        updateElement(node, segment.prop, segment.val);
+                    }
+                    nodeIdx++;
+                }
+            }
+        } else {
+            const fragment = document.createDocumentFragment();
+            for (const segment of processed) {
+                if (typeof segment === 'string') {
+                    fragment.appendChild(document.createTextNode(segment));
+                } else {
+                    const el = createElementForValue(segment.prop, segment.val);
+                    fragment.appendChild(el);
+                }
+            }
+            endMarker.parentNode.insertBefore(fragment, endMarker);
+        }
+    }
+}

package/handlers/microDataJoin.ts

@@ -0,0 +1,270 @@
+/**
+ * builtIns.microDataJoin handler for assignFrom.
+ * 
+ * Renders a template array as semantic microdata-annotated DOM elements.
+ * Each dynamic value gets an HTML element based on its resolved type,
+ * with itemprop set to the property name.
+ * 
+ * Type → Element mapping:
+ * - string → <span itemprop=name>value</span>
+ * - number → <data itemprop=name value=raw>formatted</data>
+ * - boolean → <data itemprop=name value=true/false></data>
+ * - Date → <time itemprop=name datetime=iso>formatted</time>
+ * - null/undefined → omitted (or sub-array dropped if in optional segment)
+ * 
+ * Uses comment markers for idempotent updates — first call creates elements,
+ * subsequent calls update existing elements in place.
+ * 
+ * This handler is auto-loaded by processHandlerCommands when
+ * `do: 'builtIns.microDataJoin'` is encountered.
+ * 
+ * @example
+ * assignFrom(oSection, {
+ *     '?.querySelector?.div =>': {
+ *         do: 'builtIns.microDataJoin',
+ *         resolve: {
+ *             template: [
+ *                 { prop: 'firstName', val: '?.firstName' },
+ *                 ' ',
+ *                 { prop: 'lastName', val: '?.lastName' }
+ *             ]
+ *         }
+ *     }
+ * }, { from: vm, withMethods: ['querySelector'] });
+ */
+
+import type { AssignFromHandler } from '../assignFrom.js';
+
+const MARKER_START_PREFIX = '?start name="';
+const MARKER_END = '?end';
+const MARKER_NAME = 'microDataJoin';
+
+interface TemplateSegment {
+    prop: string;
+    val: any;
+    format?: string;
+}
+
+/**
+ * Find existing start/end comment markers in a target element.
+ */
+function findMarkers(target: Element): [Comment | null, Comment | null] {
+    const startText = `${MARKER_START_PREFIX}${MARKER_NAME}"`;
+    let startMarker: Comment | null = null;
+    let endMarker: Comment | null = null;
+
+    const walker = document.createTreeWalker(target, NodeFilter.SHOW_COMMENT);
+    let node: Comment | null;
+    while ((node = walker.nextNode() as Comment | null)) {
+        if (!startMarker && node.data === startText) {
+            startMarker = node;
+        } else if (startMarker && !endMarker && node.data === MARKER_END) {
+            endMarker = node;
+            break;
+        }
+    }
+    return [startMarker, endMarker];
+}
+
+/**
+ * Create start/end markers in the target.
+ */
+function createMarkers(target: Element): [Comment, Comment] {
+    const startMarker = document.createComment(`${MARKER_START_PREFIX}${MARKER_NAME}"`);
+    const endMarker = document.createComment(MARKER_END);
+    target.appendChild(startMarker);
+    target.appendChild(endMarker);
+    return [startMarker, endMarker];
+}
+
+/**
+ * Get all nodes between start and end markers.
+ */
+function getNodesBetweenMarkers(start: Comment, end: Comment): Node[] {
+    const nodes: Node[] = [];
+    let current: Node | null = start.nextSibling;
+    while (current && current !== end) {
+        nodes.push(current);
+        current = current.nextSibling;
+    }
+    return nodes;
+}
+
+/**
+ * Format a value for display (textContent) using locale.
+ */
+function formatForDisplay(value: any): string {
+    if (value instanceof Date) {
+        return value.toLocaleDateString();
+    }
+    if (typeof value === 'number') {
+        return value.toLocaleString();
+    }
+    if (typeof value === 'boolean') {
+        return '';  // booleans show nothing by default
+    }
+    return String(value ?? '');
+}
+
+/**
+ * Format a value for the machine-readable attribute (value or datetime).
+ */
+function formatForAttribute(value: any): string {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return String(value);
+}
+
+/**
+ * Create the appropriate DOM element for a resolved value.
+ */
+function createElementForValue(prop: string, value: any): Element {
+    if (value instanceof Date) {
+        const el = document.createElement('time');
+        el.setAttribute('itemprop', prop);
+        el.setAttribute('datetime', formatForAttribute(value));
+        el.textContent = formatForDisplay(value);
+        return el;
+    }
+    if (typeof value === 'number') {
+        const el = document.createElement('data');
+        el.setAttribute('itemprop', prop);
+        el.setAttribute('value', formatForAttribute(value));
+        el.textContent = formatForDisplay(value);
+        return el;
+    }
+    if (typeof value === 'boolean') {
+        const el = document.createElement('data');
+        el.setAttribute('itemprop', prop);
+        el.setAttribute('value', String(value));
+        // empty textContent for booleans
+        return el;
+    }
+    // Default: string → span
+    const el = document.createElement('span');
+    el.setAttribute('itemprop', prop);
+    el.textContent = String(value ?? '');
+    return el;
+}
+
+/**
+ * Update an existing element with a new value (in-place update).
+ */
+function updateElement(el: Element, prop: string, value: any): void {
+    if (value instanceof Date) {
+        el.setAttribute('datetime', formatForAttribute(value));
+        el.textContent = formatForDisplay(value);
+    } else if (typeof value === 'number') {
+        el.setAttribute('value', formatForAttribute(value));
+        el.textContent = formatForDisplay(value);
+    } else if (typeof value === 'boolean') {
+        el.setAttribute('value', String(value));
+    } else {
+        el.textContent = String(value ?? '');
+    }
+}
+
+/**
+ * Process the template array, handling optional (nested) segments.
+ * Returns a flat array of items to render, with null sub-arrays dropped.
+ */
+function processTemplate(template: any[]): (string | TemplateSegment)[] {
+    const result: (string | TemplateSegment)[] = [];
+    for (const item of template) {
+        if (Array.isArray(item)) {
+            // All-or-nothing: if any {prop,val} segment has val === null/undefined, drop entire sub-array
+            const hasNull = item.some(el =>
+                el && typeof el === 'object' && 'prop' in el && el.val == null
+            );
+            if (hasNull) continue;
+            // Sub-array passes — flatten
+            result.push(...processTemplate(item));
+        } else if (item == null) {
+            continue;
+        } else {
+            result.push(item);
+        }
+    }
+    return result;
+}
+
+/**
+ * MicroDataJoinHandler — renders template arrays as semantic microdata DOM.
+ */
+export class MicroDataJoinHandler implements AssignFromHandler {
+    config: any;
+
+    constructor(config: any) {
+        this.config = config;
+    }
+
+    async assign(lhsTarget: any, resolvedParams: Record<string, any>): Promise<void> {
+        const { template } = resolvedParams;
+
+        if (!template || !Array.isArray(template)) {
+            throw new Error('builtIns.microDataJoin: resolve.template must be an array');
+        }
+
+        if (!(lhsTarget instanceof Element)) {
+            throw new Error('builtIns.microDataJoin: lhsTarget must be a DOM Element');
+        }
+
+        // Add itemscope to target if not present
+        if (!lhsTarget.hasAttribute('itemscope')) {
+            lhsTarget.setAttribute('itemscope', '');
+        }
+
+        // Process template (handle optional segments)
+        const processed = processTemplate(template);
+
+        // Find or create markers
+        let [startMarker, endMarker] = findMarkers(lhsTarget);
+        const isUpdate = startMarker !== null && endMarker !== null;
+
+        if (!isUpdate) {
+            [startMarker, endMarker] = createMarkers(lhsTarget);
+        }
+
+        if (isUpdate) {
+            // Update existing nodes in place
+            const existingNodes = getNodesBetweenMarkers(startMarker!, endMarker!);
+            let nodeIdx = 0;
+
+            for (const segment of processed) {
+                if (typeof segment === 'string') {
+                    // Literal text — update or skip text node
+                    const node = existingNodes[nodeIdx];
+                    if (node && node.nodeType === Node.TEXT_NODE) {
+                        if (node.textContent !== segment) {
+                            node.textContent = segment;
+                        }
+                    }
+                    nodeIdx++;
+                } else {
+                    // {prop, val} — update element
+                    const node = existingNodes[nodeIdx];
+                    if (node && node instanceof Element && node.getAttribute('itemprop') === segment.prop) {
+                        updateElement(node, segment.prop, segment.val);
+                    }
+                    nodeIdx++;
+                }
+            }
+        } else {
+            // First render — create all nodes
+            const fragment = document.createDocumentFragment();
+
+            for (const segment of processed) {
+                if (typeof segment === 'string') {
+                    fragment.appendChild(document.createTextNode(segment));
+                } else {
+                    // {prop, val} object
+                    const el = createElementForValue(segment.prop, segment.val);
+                    fragment.appendChild(el);
+                }
+            }
+
+            endMarker!.parentNode!.insertBefore(fragment, endMarker!);
+        }
+    }
+}

package/inferencer/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "types"]
+	path = types
+	url = https://github.com/bahrus/types.git

package/inferencer/.vscode/settings.json

@@ -0,0 +1,2 @@
+{
+}

package/inferencer/InferencedPropagator.js

@@ -0,0 +1,230 @@
+import { inferEventType } from './inferencer.js';
+/**
+ * An inferred propagator that extends EventTarget.
+ * Emits property change events by intelligently hooking into
+ * whatever change detection mechanism is available for the element.
+ *
+ * Property observation is lazy — wiring only happens when
+ * addEventListener is called for a given property name.
+ */
+export class InferencedPropagator extends EventTarget {
+    #infer;
+    #watchedProperties = new Map();
+    constructor(infer) {
+        super();
+        this.#infer = infer;
+    }
+    addEventListener(type, callback, options) {
+        super.addEventListener(type, callback, options);
+        if (!this.#watchedProperties.has(type)) {
+            // Placeholder cleanup until async wiring completes
+            this.#watchedProperties.set(type, () => { });
+            this.#wireProperty(type);
+        }
+    }
+    removeEventListener(type, callback, options) {
+        super.removeEventListener(type, callback, options);
+    }
+    async #wireProperty(propName) {
+        const element = this.#infer.enhancedElement;
+        // Snapshot current value before async setup
+        const initialValue = element[propName];
+        const cleanup = await this.#setupStrategy(element, propName);
+        this.#watchedProperties.set(propName, cleanup);
+        // If value changed during async wiring, dispatch immediately
+        const currentValue = element[propName];
+        if (currentValue !== initialValue) {
+            this.dispatchEvent(new Event(propName));
+        }
+    }
+    /**
+     * Determine and set up the best observation strategy for a property.
+     * Returns a cleanup function.
+     */
+    async #setupStrategy(element, propName) {
+        // Strategy 1: Attribute-reflected properties
+        const attrName = this.#toAttributeName(propName);
+        if (this.#isAttributeReflected(element, propName, attrName)) {
+            return this.#observeAttribute(element, propName, attrName);
+        }
+        // Strategy 2: Native event (user-driven) + setter interception (programmatic)
+        const eventType = this.#getNativeEventType(element, propName);
+        if (eventType) {
+            return this.#observeHybrid(element, propName, eventType);
+        }
+        // Strategy 3: Setter interception (custom elements or known prototypes)
+        const descriptor = this.#getPropertyDescriptor(element, propName);
+        if (descriptor?.set) {
+            return this.#interceptSetter(element, propName, descriptor);
+        }
+        // Strategy 4: Polling fallback
+        return this.#observePolling(element, propName);
+    }
+    // ─── Strategy Implementations ────────────────────────────────────────
+    /**
+     * Strategy 1: Use MutationObserver on the corresponding attribute.
+     */
+    #observeAttribute(element, propName, attrName) {
+        const observer = new MutationObserver(() => {
+            this.dispatchEvent(new Event(propName));
+        });
+        observer.observe(element, {
+            attributes: true,
+            attributeFilter: [attrName],
+        });
+        return () => observer.disconnect();
+    }
+    /**
+     * Strategy 2: Listen for native events AND intercept setter for programmatic changes.
+     */
+    #observeHybrid(element, propName, eventType) {
+        const ac = new AbortController();
+        const { signal } = ac;
+        // Listen for user-driven events
+        element.addEventListener(eventType, () => {
+            this.dispatchEvent(new Event(propName));
+        }, { signal });
+        // Also intercept setter for programmatic changes
+        const descriptor = this.#getPropertyDescriptor(element, propName);
+        let restoreSetter;
+        if (descriptor?.set) {
+            restoreSetter = this.#interceptSetter(element, propName, descriptor);
+        }
+        return () => {
+            ac.abort();
+            restoreSetter?.();
+        };
+    }
+    /**
+     * Strategy 3: Override the property setter on the instance to detect programmatic writes.
+     */
+    #interceptSetter(element, propName, descriptor) {
+        const originalSet = descriptor.set;
+        const originalGet = descriptor.get;
+        const self = this;
+        Object.defineProperty(element, propName, {
+            get: originalGet ? function () { return originalGet.call(this); } : undefined,
+            set(newValue) {
+                const oldValue = originalGet ? originalGet.call(this) : undefined;
+                originalSet.call(this, newValue);
+                if (newValue !== oldValue) {
+                    self.dispatchEvent(new Event(propName));
+                }
+            },
+            configurable: true,
+            enumerable: descriptor.enumerable,
+        });
+        return () => {
+            // Restore by deleting instance property — prototype descriptor takes over again
+            delete element[propName];
+        };
+    }
+    /**
+     * Strategy 4: Polling via requestAnimationFrame.
+     */
+    #observePolling(element, propName) {
+        let active = true;
+        let lastValue = element[propName];
+        const poll = () => {
+            if (!active)
+                return;
+            const currentValue = element[propName];
+            if (currentValue !== lastValue) {
+                lastValue = currentValue;
+                this.dispatchEvent(new Event(propName));
+            }
+            requestAnimationFrame(poll);
+        };
+        requestAnimationFrame(poll);
+        return () => { active = false; };
+    }
+    // ─── Helpers ─────────────────────────────────────────────────────────
+    /**
+     * Convert a camelCase property name to its kebab-case attribute equivalent.
+     * e.g. ariaValueNow -> aria-valuenow
+     */
+    #toAttributeName(propName) {
+        // aria properties have a direct mapping
+        if (propName.startsWith('aria')) {
+            return propName.replace(/([A-Z])/g, '-$1').toLowerCase();
+        }
+        // General camelCase to kebab-case
+        return propName.replace(/([A-Z])/g, '-$1').toLowerCase();
+    }
+    /**
+     * Check if setting a property updates the corresponding attribute.
+     */
+    #isAttributeReflected(element, propName, attrName) {
+        // For form elements, 'value' attribute is only the default — property changes
+        // from user input do NOT update the attribute, so it's not truly reflected.
+        const { localName } = element;
+        if (propName === 'value' && ['input', 'textarea', 'select', 'button'].includes(localName)) {
+            return false;
+        }
+        // For <data>, <meter>, <output>, <progress> the value property reflects to the value attribute
+        if (propName === 'value' && ['data', 'meter', 'output', 'progress'].includes(localName)) {
+            return true;
+        }
+        // Quick check: does the attribute currently exist or is the property known to reflect?
+        if (element.hasAttribute(attrName))
+            return true;
+        // For aria-* properties, they are spec-defined as reflecting
+        if (propName.startsWith('aria'))
+            return true;
+        // For href, src on appropriate elements
+        const reflectedProps = {
+            'href': ['a', 'area', 'link', 'base'],
+            'src': ['img', 'script', 'iframe', 'audio', 'video', 'source', 'embed'],
+            'action': ['form'],
+            'value': ['option', 'param', 'li'],
+        };
+        if (reflectedProps[propName]?.includes(localName))
+            return true;
+        return false;
+    }
+    /**
+     * Determine the native event type that fires when a property changes (user-driven).
+     * Leverages Infer's inferEventType for elements known to have input-like behavior.
+     */
+    #getNativeEventType(element, propName) {
+        const { localName } = element;
+        // Only applicable for form-like elements with value/checked properties
+        if (['input', 'textarea', 'select'].includes(localName)) {
+            if (propName === 'value' || propName === 'valueAsNumber' || propName === 'valueAsDate' || propName === 'checked' || propName === 'selectedIndex') {
+                return inferEventType(element);
+            }
+        }
+        if (localName === 'details' && propName === 'open') {
+            return 'toggle';
+        }
+        // contentEditable elements fire 'input' events on user edits
+        if (element instanceof HTMLElement && element.isContentEditable) {
+            if (propName === 'textContent' || propName === 'innerHTML' || propName === 'innerText') {
+                return 'input';
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Walk the prototype chain to find a property descriptor.
+     */
+    #getPropertyDescriptor(element, propName) {
+        let proto = Object.getPrototypeOf(element);
+        while (proto && proto !== Object.prototype) {
+            const desc = Object.getOwnPropertyDescriptor(proto, propName);
+            if (desc)
+                return desc;
+            proto = Object.getPrototypeOf(proto);
+        }
+        return undefined;
+    }
+    /**
+     * Tear down all watchers and clean up resources.
+     */
+    destroy() {
+        for (const cleanup of this.#watchedProperties.values()) {
+            cleanup();
+        }
+        this.#watchedProperties.clear();
+    }
+}