assign-gingerly 0.0.54 → 0.0.55

package/handlers/lazyLoad.ts

@@ -0,0 +1,307 @@
+/**
+ * builtIns.lazyLoad handler for assignFrom.
+ * 
+ * Conditionally clones a template into a target element, using comment markers
+ * to track the inserted content. Supports show/hide and show/remove modes.
+ * 
+ * This handler is auto-loaded by processHandlerCommands when `do: 'builtIns.lazyLoad'`
+ * is encountered — no explicit import is needed.
+ * 
+ * @example
+ * assignFrom(document.body, {
+ *     '?.querySelector?..mainView =>': {
+ *         do: 'builtIns.lazyLoad',
+ *         resolve: {
+ *             if: '?.isHappy',
+ *             instantiate: 'globalThis://happyMood',
+ *         }
+ *     }
+ * }, { withMethods: ['querySelector'], from: myVM });
+ */
+
+import type { AssignFromHandler } from '../assignFrom.js';
+import { withTransition, ensureHideStyle, DEFAULT_HIDE_CLASS } from '../transitionHelper.js';
+
+const MARKER_START_PREFIX = '?start name="';
+const MARKER_END = '?end';
+
+/**
+ * Context passed to onInstantiated callbacks.
+ */
+export interface LazyLoadInstantiatedContext {
+    /** The inserted child nodes */
+    nodes: Node[];
+    /** The target element containing the markers */
+    target: Element;
+    /** The full handler config */
+    config: any;
+    /** The resolved parameters */
+    resolvedParams: Record<string, any>;
+}
+
+/**
+ * Get the marker name from a template element (uses its id).
+ */
+function getMarkerName(templateEl: any): string {
+    if (templateEl instanceof HTMLTemplateElement) {
+        return templateEl.id || 'anonymous';
+    }
+    if (typeof templateEl === 'string') {
+        return templateEl;
+    }
+    return 'anonymous';
+}
+
+/**
+ * Find existing start/end comment markers in a target element.
+ * Returns [startMarker, endMarker] or [null, null] if not found.
+ */
+function findMarkers(target: Element, name: string): [Comment | null, Comment | null] {
+    const startText = `${MARKER_START_PREFIX}${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 and insert them into the target.
+ */
+function createMarkers(target: Element, name: string, method: string): [Comment, Comment] {
+    const startMarker = document.createComment(`${MARKER_START_PREFIX}${name}"`);
+    const endMarker = document.createComment(MARKER_END);
+
+    if (method === 'prepend') {
+        target.prepend(endMarker);
+        target.prepend(startMarker);
+    } else {
+        // Default: appendChild
+        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;
+}
+
+/**
+ * LazyLoadHandler — built-in handler for conditional template instantiation.
+ * 
+ * Exported so it can be subclassed for custom behavior.
+ */
+export class LazyLoadHandler implements AssignFromHandler {
+    config: any;
+
+    constructor(config: any) {
+        this.config = config;
+    }
+
+    async assign(lhsTarget: any, resolvedParams: Record<string, any>): Promise<void> {
+        const {
+            if: condition,
+            instantiate,
+            method = 'appendChild',
+            forget = false,
+            transitional = false,
+            hideClass = DEFAULT_HIDE_CLASS,
+        } = resolvedParams;
+
+        if (!(lhsTarget instanceof Element)) {
+            throw new Error('builtIns.lazyLoad: lhsTarget must be a DOM Element');
+        }
+
+        const name = getMarkerName(instantiate);
+
+        // Find or create markers
+        let [startMarker, endMarker] = findMarkers(lhsTarget, name);
+
+        if (condition) {
+            // SHOW
+            if (startMarker && endMarker) {
+                // Markers exist — check if content is hidden or removed
+                const nodes = getNodesBetweenMarkers(startMarker, endMarker);
+                if (nodes.length > 0) {
+                    // Content exists — show it
+                    withTransition(startMarker, 'show', transitional, () => {
+                        for (const node of nodes) {
+                            if (node instanceof Element) {
+                                if (transitional) {
+                                    node.classList.remove(hideClass);
+                                } else {
+                                    node.removeAttribute('hidden');
+                                }
+                            }
+                        }
+                    });
+                } else {
+                    // Content was removed (forget mode) — re-clone
+                    if (transitional) {
+                        ensureHideStyle(lhsTarget.getRootNode());
+                        withTransition(startMarker, 'show', true, () => {
+                            // cloneAndInsert is async but the transition callback is sync
+                            // For transitions with clone, we insert synchronously
+                            this.cloneAndInsertSync(instantiate, startMarker!, endMarker!, lhsTarget, resolvedParams);
+                        });
+                    } else {
+                        await this.cloneAndInsert(instantiate, startMarker, endMarker, lhsTarget, resolvedParams);
+                    }
+                }
+            } else {
+                // No markers — first time. Create markers and clone template.
+                [startMarker, endMarker] = createMarkers(lhsTarget, name, method);
+                if (transitional) {
+                    ensureHideStyle(lhsTarget.getRootNode());
+                    withTransition(startMarker, 'show', true, () => {
+                        this.cloneAndInsertSync(instantiate, startMarker!, endMarker!, lhsTarget, resolvedParams);
+                    });
+                } else {
+                    await this.cloneAndInsert(instantiate, startMarker, endMarker, lhsTarget, resolvedParams);
+                }
+            }
+        } else {
+            // HIDE or REMOVE
+            if (startMarker && endMarker) {
+                const nodes = getNodesBetweenMarkers(startMarker, endMarker);
+                if (nodes.length === 0) return;
+
+                if (forget) {
+                    // Remove nodes entirely (markers persist for re-insertion)
+                    withTransition(startMarker, 'hide', transitional, () => {
+                        for (const node of nodes) {
+                            node.parentNode?.removeChild(node);
+                        }
+                    });
+                } else {
+                    // Hide nodes
+                    withTransition(startMarker, 'hide', transitional, () => {
+                        for (const node of nodes) {
+                            if (node instanceof Element) {
+                                if (transitional) {
+                                    ensureHideStyle(lhsTarget.getRootNode(), hideClass);
+                                    node.classList.add(hideClass);
+                                } else {
+                                    node.setAttribute('hidden', '');
+                                }
+                            }
+                        }
+                    });
+                }
+            }
+            // If no markers exist and condition is false, do nothing (never loaded)
+        }
+    }
+
+    /**
+     * Clone a template and insert its content between the markers (synchronous version).
+     * Used inside view transition callbacks which must be synchronous.
+     * Does not call async hooks (onCloneInserted, onInstantiated).
+     */
+    protected cloneAndInsertSync(
+        templateEl: any,
+        startMarker: Comment,
+        endMarker: Comment,
+        lhsTarget: Element,
+        resolvedParams: Record<string, any>
+    ): Node[] {
+        let content: DocumentFragment;
+
+        if (templateEl instanceof HTMLTemplateElement) {
+            content = templateEl.content.cloneNode(true) as DocumentFragment;
+        } else if (templateEl instanceof DocumentFragment) {
+            content = templateEl.cloneNode(true) as DocumentFragment;
+        } else {
+            throw new Error(
+                `builtIns.lazyLoad: instantiate must resolve to an HTMLTemplateElement or DocumentFragment`
+            );
+        }
+
+        const nodes = Array.from(content.childNodes);
+        endMarker.parentNode!.insertBefore(content, endMarker);
+        return nodes;
+    }
+
+    /**
+     * Clone a template and insert its content between the markers.
+     * Calls onCloneInserted hook and onInstantiated callback after insertion.
+     */
+    protected async cloneAndInsert(
+        templateEl: any,
+        startMarker: Comment,
+        endMarker: Comment,
+        lhsTarget: Element,
+        resolvedParams: Record<string, any>
+    ): Promise<Node[]> {
+        let content: DocumentFragment;
+
+        if (templateEl instanceof HTMLTemplateElement) {
+            content = templateEl.content.cloneNode(true) as DocumentFragment;
+        } else if (templateEl instanceof DocumentFragment) {
+            content = templateEl.cloneNode(true) as DocumentFragment;
+        } else {
+            throw new Error(
+                `builtIns.lazyLoad: instantiate must resolve to an HTMLTemplateElement or DocumentFragment`
+            );
+        }
+
+        // Capture nodes before insertion (childNodes empties after insertBefore)
+        const nodes = Array.from(content.childNodes);
+
+        // Insert before endMarker
+        endMarker.parentNode!.insertBefore(content, endMarker);
+
+        // Call protected hook (for subclass overrides)
+        await this.onCloneInserted(nodes, lhsTarget, resolvedParams);
+
+        // Call onInstantiated callback if provided (resolved from VM)
+        if (resolvedParams.onInstantiated && typeof resolvedParams.onInstantiated === 'function') {
+            const ctx: LazyLoadInstantiatedContext = {
+                nodes,
+                target: lhsTarget,
+                config: this.config,
+                resolvedParams
+            };
+            await resolvedParams.onInstantiated(ctx);
+        }
+
+        return nodes;
+    }
+
+    /**
+     * Hook called after template content is cloned and inserted.
+     * Override in subclasses for custom post-clone logic.
+     * 
+     * @param nodes - The inserted child nodes
+     * @param lhsTarget - The target element
+     * @param resolvedParams - The resolved parameters
+     */
+    protected async onCloneInserted(
+        nodes: Node[],
+        lhsTarget: Element,
+        resolvedParams: Record<string, any>
+    ): Promise<void> {
+        // No-op by default. Subclasses override.
+    }
+}

package/handlers/lazyLoadSwitch.js

@@ -0,0 +1,58 @@
+/**
+ * builtIns.lazyLoadSwitch handler for assignFrom.
+ *
+ * Extends LazyLoadHandler with a comparison-based condition instead of a
+ * pre-computed boolean. Evaluates `lhs op rhs` to determine whether to
+ * show or hide the template content.
+ *
+ * This handler is auto-loaded by processHandlerCommands when
+ * `do: 'builtIns.lazyLoadSwitch'` is encountered — no explicit import is needed.
+ *
+ * Useful for routing and multi-way conditional rendering where multiple
+ * handlers in an array represent different "cases."
+ *
+ * @example
+ * assignFrom(el, {
+ *     '?.querySelector?..routerOutlet =>': [
+ *         { do: 'builtIns.lazyLoadSwitch', resolve: { lhs: '?.route', rhs: 'home', instantiate: 'globalThis://homeView' } },
+ *         { do: 'builtIns.lazyLoadSwitch', resolve: { lhs: '?.route', rhs: 'settings', instantiate: 'globalThis://settingsView' } },
+ *     ]
+ * }, { withMethods: ['querySelector'], from: vm, protocols: { globalThis: k => globalThis[k] } });
+ */
+import { LazyLoadHandler } from './lazyLoad.js';
+/**
+ * Evaluate a comparison operation.
+ *
+ * @param lhs - Left-hand side value
+ * @param op - Operator string (default: '===')
+ * @param rhs - Right-hand side value
+ * @returns Boolean result of the comparison
+ */
+function evaluateOp(lhs, op, rhs) {
+    switch (op) {
+        case '===': return lhs === rhs;
+        case '!==': return lhs !== rhs;
+        case '==': return lhs == rhs;
+        case '!=': return lhs != rhs;
+        case '<': return lhs < rhs;
+        case '>': return lhs > rhs;
+        case '<=': return lhs <= rhs;
+        case '>=': return lhs >= rhs;
+        default:
+            throw new Error(`builtIns.lazyLoadSwitch: unsupported operator "${op}"`);
+    }
+}
+/**
+ * LazyLoadSwitchHandler — comparison-based conditional template instantiation.
+ *
+ * Extends LazyLoadHandler by evaluating `lhs op rhs` to compute the condition,
+ * then delegating all DOM logic to the parent class.
+ */
+export class LazyLoadSwitchHandler extends LazyLoadHandler {
+    async assign(lhsTarget, resolvedParams) {
+        const { lhs, op = '===', rhs, ...rest } = resolvedParams;
+        const condition = evaluateOp(lhs, op, rhs);
+        // Delegate to parent with computed condition
+        return super.assign(lhsTarget, { ...rest, if: condition });
+    }
+}

package/handlers/lazyLoadSwitch.ts

@@ -0,0 +1,63 @@
+/**
+ * builtIns.lazyLoadSwitch handler for assignFrom.
+ * 
+ * Extends LazyLoadHandler with a comparison-based condition instead of a
+ * pre-computed boolean. Evaluates `lhs op rhs` to determine whether to
+ * show or hide the template content.
+ * 
+ * This handler is auto-loaded by processHandlerCommands when
+ * `do: 'builtIns.lazyLoadSwitch'` is encountered — no explicit import is needed.
+ * 
+ * Useful for routing and multi-way conditional rendering where multiple
+ * handlers in an array represent different "cases."
+ * 
+ * @example
+ * assignFrom(el, {
+ *     '?.querySelector?..routerOutlet =>': [
+ *         { do: 'builtIns.lazyLoadSwitch', resolve: { lhs: '?.route', rhs: 'home', instantiate: 'globalThis://homeView' } },
+ *         { do: 'builtIns.lazyLoadSwitch', resolve: { lhs: '?.route', rhs: 'settings', instantiate: 'globalThis://settingsView' } },
+ *     ]
+ * }, { withMethods: ['querySelector'], from: vm, protocols: { globalThis: k => globalThis[k] } });
+ */
+
+import { LazyLoadHandler } from './lazyLoad.js';
+import type { AssignFromHandler } from '../assignFrom.js';
+
+/**
+ * Evaluate a comparison operation.
+ * 
+ * @param lhs - Left-hand side value
+ * @param op - Operator string (default: '===')
+ * @param rhs - Right-hand side value
+ * @returns Boolean result of the comparison
+ */
+function evaluateOp(lhs: any, op: string, rhs: any): boolean {
+    switch (op) {
+        case '===': return lhs === rhs;
+        case '!==': return lhs !== rhs;
+        case '==':  return lhs == rhs;
+        case '!=':  return lhs != rhs;
+        case '<':   return lhs < rhs;
+        case '>':   return lhs > rhs;
+        case '<=':  return lhs <= rhs;
+        case '>=':  return lhs >= rhs;
+        default:
+            throw new Error(`builtIns.lazyLoadSwitch: unsupported operator "${op}"`);
+    }
+}
+
+/**
+ * LazyLoadSwitchHandler — comparison-based conditional template instantiation.
+ * 
+ * Extends LazyLoadHandler by evaluating `lhs op rhs` to compute the condition,
+ * then delegating all DOM logic to the parent class.
+ */
+export class LazyLoadSwitchHandler extends LazyLoadHandler implements AssignFromHandler {
+
+    async assign(lhsTarget: any, resolvedParams: Record<string, any>): Promise<void> {
+        const { lhs, op = '===', rhs, ...rest } = resolvedParams;
+        const condition = evaluateOp(lhs, op, rhs);
+        // Delegate to parent with computed condition
+        return super.assign(lhsTarget, { ...rest, if: condition });
+    }
+}

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);
+        }
+    }
+}