@mintjamsinc/ichigojs 0.1.54 → 0.1.56

package/dist/ichigo.esm.js

@@ -1,6 +1,7 @@
 // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
 /**
  * Represents a reusable component definition.
+ * @deprecated This class is deprecated and will be removed in a future release. Please use the new component registration system instead.
  */
 class VComponent {
     /**
@@ -38,6 +39,7 @@ class VComponent {
 // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
 /**
  * A registry for managing component definitions.
+ * @deprecated This class is deprecated and will be removed in a future release. Please use the new component registration system instead.
  */
 class VComponentRegistry {
     /**
@@ -6729,11 +6731,18 @@ class ExpressionUtils {
      * Extracts variable and function names used in the expression.
      * @param expression The expression string to analyze.
      * @param functionDependencies A dictionary mapping function names to their dependencies.
+     * @param options Optional parsing options.
+     *   - asScript: If true, parse the input as a Script (allows multi-statement source with semicolons,
+     *     declarations, control-flow, etc.). If false/omitted, parse as a single expression (the default,
+     *     for backward compatibility with interpolation and binding directives).
      * @returns An array of identifier names.
      */
-    static extractIdentifiers(expression, functionDependencies) {
+    static extractIdentifiers(expression, functionDependencies, options) {
         const identifiers = new Set();
-        const ast = parse(`(${expression})`, { ecmaVersion: "latest" });
+        // In expression mode we wrap in parens so acorn parses the source as a single expression.
+        // In script mode we parse as a Program so that multi-statement bodies (e.g. "a=1; b=2") work.
+        const source = options?.asScript ? expression : `(${expression})`;
+        const ast = parse(source, { ecmaVersion: "latest" });
         // Use walk.full instead of walk.simple to visit ALL nodes including assignment LHS
         full(ast, (node) => {
             if (node.type === 'Identifier') {
@@ -6965,10 +6974,10 @@ class ExpressionUtils {
      * @param identifiers The list of identifiers that are available in bindings.
      * @returns The rewritten expression.
      */
-    static rewriteExpression(expression, identifiers) {
+    static rewriteExpression(expression, identifiers, options) {
         // Reserved words and built-in objects that should not be prefixed with 'this.'
         const reserved = new Set([
-            'event', '$ctx', '$newValue',
+            'event', '$event', '$ctx', '$newValue',
             'true', 'false', 'null', 'undefined', 'NaN', 'Infinity',
             'Math', 'Date', 'String', 'Number', 'Boolean', 'Array', 'Object',
             'JSON', 'console', 'window', 'document', 'navigator',
@@ -6980,7 +6989,7 @@ class ExpressionUtils {
         // identifiers that are used (right-hand side), not assigned to (left-hand side)
         let allIdentifiersInExpression;
         try {
-            allIdentifiersInExpression = ExpressionUtils.extractIdentifiers(expression, {});
+            allIdentifiersInExpression = ExpressionUtils.extractIdentifiers(expression, {}, options);
         }
         catch (error) {
             console.warn('[ichigo.js] Failed to extract identifiers from expression:', expression, error);
@@ -7002,7 +7011,26 @@ class ExpressionUtils {
         try {
             // Build a map of positions to replace: { start: number, end: number, name: string }[]
             const replacements = [];
-            const parsedAst = parse(`(${expression})`, { ecmaVersion: 'latest' });
+            // In script mode we must not wrap in parens (that would make multi-statement input invalid).
+            // Offsets from the parser therefore refer directly to the original expression, so no shift.
+            const asScript = options?.asScript === true;
+            const source = asScript ? expression : `(${expression})`;
+            const offsetShift = asScript ? 0 : 1;
+            const parsedAst = parse(source, { ecmaVersion: 'latest' });
+            // Track identifiers that are locally declared within the handler body (let/const/var, function
+            // params) so we don't rewrite them to `this.xxx`. Only relevant in script mode, where the user
+            // can write declarations; in expression mode there are no declarations to track.
+            const locallyDeclared = new Set();
+            if (asScript) {
+                full(parsedAst, (node) => {
+                    if (node.type === 'VariableDeclarator' && node.id?.type === 'Identifier') {
+                        locallyDeclared.add(node.id.name);
+                    }
+                    else if (node.type === 'FunctionDeclaration' && node.id?.type === 'Identifier') {
+                        locallyDeclared.add(node.id.name);
+                    }
+                });
+            }
             // Collect all identifier nodes that should be replaced
             // Use walk.fullAncestor to visit ALL nodes (including assignment LHS) while tracking ancestors
             fullAncestor(parsedAst, (node, _state, ancestors) => {
@@ -7013,6 +7041,10 @@ class ExpressionUtils {
                 if (!bindingIdentifiers.has(node.name)) {
                     return;
                 }
+                // Skip identifiers that were declared locally in the handler body
+                if (locallyDeclared.has(node.name)) {
+                    return;
+                }
                 // Check if this identifier is a property of a MemberExpression
                 // (e.g., in 'obj.prop', we should skip 'prop')
                 if (ancestors.length >= 1) {
@@ -7024,10 +7056,10 @@ class ExpressionUtils {
                         }
                     }
                 }
-                // Add to replacements list (adjust for the wrapping parentheses)
+                // Add to replacements list (adjust for the wrapping parentheses in expression mode)
                 replacements.push({
-                    start: node.start - 1,
-                    end: node.end - 1,
+                    start: node.start - offsetShift,
+                    end: node.end - offsetShift,
                     name: node.name
                 });
             });
@@ -7468,6 +7500,14 @@ class VBindDirective {
         else if (attributeName === 'style') {
             this.#updateStyle(element, value);
         }
+        else if (this.#isCustomElementProperty(element, attributeName, value)) {
+            // Custom elements: set objects/arrays (and declared props) as properties
+            // so complex values are not serialized to strings via setAttribute.
+            // HTML attributes are lowercased by the browser, so resolve to the
+            // actual camelCase property name declared on the custom element.
+            const propName = this.#resolveCustomElementPropertyName(element, attributeName);
+            element[propName] = value;
+        }
         else if (this.#isDOMProperty(attributeName)) {
             this.#updateProperty(element, attributeName, value);
         }
@@ -7551,6 +7591,46 @@ class VBindDirective {
     #camelToKebab(str) {
         return str.replace(/([A-Z])/g, '-$1').toLowerCase();
     }
+    /**
+     * Returns true when the target is a custom element and the binding should be
+     * delivered as a property rather than an HTML attribute.
+     *
+     * Two conditions trigger property delivery:
+     *  1. The value is an object or array — serialising these to a string attribute
+     *     would lose type information.
+     *  2. The element exposes a matching property accessor (e.g. a prop declared via
+     *     defineComponent), even when the value is a primitive.
+     */
+    #isCustomElementProperty(element, name, value) {
+        if (!element.tagName.includes('-')) {
+            return false;
+        }
+        const isObjectOrArray = Array.isArray(value) || (typeof value === 'object' && value !== null);
+        return isObjectOrArray || name in element;
+    }
+    /**
+     * Resolves the actual property name on a custom element for a given
+     * (lowercased) HTML attribute name.  HTML attributes are always lowercase,
+     * but custom element props are typically camelCase.  This method checks the
+     * element's declared _props (set by defineComponent) for a case-insensitive
+     * match, falling back to scanning the prototype's own property descriptors.
+     */
+    #resolveCustomElementPropertyName(element, name) {
+        // Fast path: exact match already exists
+        if (name in element) {
+            return name;
+        }
+        // Check declared _props from defineComponent / IchigoElement
+        const props = element.constructor._props;
+        if (Array.isArray(props)) {
+            const lowerName = name.toLowerCase();
+            const match = props.find(p => p.toLowerCase() === lowerName);
+            if (match) {
+                return match;
+            }
+        }
+        return name;
+    }
     /**
      * Checks if the attribute should be set as a DOM property.
      */
@@ -8931,6 +9011,18 @@ class VNode {
                 });
             }
         }
+        else if (this.#nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
+            // If the node is a DocumentFragment, create child VNodes for its children
+            // DocumentFragment is not an Element so it has no directives itself.
+            this.#childVNodes = [];
+            for (const childNode of Array.from(this.#node.childNodes)) {
+                new VNode({
+                    node: childNode,
+                    vApplication: this.#vApplication,
+                    parentVNode: this
+                });
+            }
+        }
         // Register this node as a dependent of the parent node, if any
         this.#closers = this.#parentVNode?.addDependent(this);
     }
@@ -9185,6 +9277,16 @@ class VNode {
                 });
             }
         }
+        else if (this.#nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
+            // For document fragments (e.g. from <template v-if>), propagate updates
+            // to dependent virtual nodes so that child bindings stay reactive.
+            this.#dependents?.forEach(dependentNode => {
+                const changed = dependentNode.dependentIdentifiers.some(id => changes.some(change => dependentNode.bindings.doesChangeMatchIdentifier(change, id)));
+                if (changed) {
+                    dependentNode.update();
+                }
+            });
+        }
     }
     /**
      * Forces an update of the virtual node and its children, regardless of changed identifiers.
@@ -9234,6 +9336,12 @@ class VNode {
                 });
             }
         }
+        else if (this.#nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
+            // For document fragments, recursively force update child VNodes
+            this.#childVNodes?.forEach(childVNode => {
+                childVNode.forceUpdate();
+            });
+        }
     }
     /**
      * Adds a child virtual node to this virtual node.
@@ -9611,9 +9719,11 @@ class VConditionalDirective {
         }
         // Clone the original node and create a new VNode for it
         const clone = this.#cloneNode();
-        // Insert the cloned node after the anchor node, or as a child of the parent if no anchor
-        this.#vNode.anchorNode?.parentNode?.insertBefore(clone, this.#vNode.anchorNode.nextSibling);
-        // Create a new VNode for the cloned element
+        // Create a new VNode for the cloned element BEFORE inserting into DOM.
+        // This prevents custom elements (Web Components) from having their
+        // connectedCallback fire before VNode processes their children, which
+        // would cause the parent VApplication to incorrectly adopt the custom
+        // element's internal template content as its own VNode tree.
         // Pass the current bindings to ensure loop variables from v-for are available
         const vNode = new VNode({
             node: clone,
@@ -9621,6 +9731,29 @@ class VConditionalDirective {
             parentVNode: this.#vNode,
             bindings: this.#vNode.bindings
         });
+        // Insert after the anchor node AFTER VNode creation
+        const anchorParent = this.#vNode.anchorNode?.parentNode;
+        const nextSibling = this.#vNode.anchorNode?.nextSibling ?? null;
+        if (clone.nodeType === Node.DOCUMENT_FRAGMENT_NODE && anchorParent) {
+            const startMarker = document.createComment('#vif-fragment-start');
+            const endMarker = document.createComment('#vif-fragment-end');
+            if (nextSibling) {
+                anchorParent.insertBefore(startMarker, nextSibling);
+            }
+            else {
+                anchorParent.appendChild(startMarker);
+            }
+            anchorParent.insertBefore(endMarker, startMarker.nextSibling);
+            anchorParent.insertBefore(clone, endMarker);
+            // Store markers for later removal
+            vNode.userData.set('vif_fragment_start', startMarker);
+            vNode.userData.set('vif_fragment_end', endMarker);
+            this.#renderedVNode = vNode;
+            this.#renderedVNode.forceUpdate();
+            return;
+        }
+        const nodeToInsert = vNode.anchorNode || clone;
+        anchorParent?.insertBefore(nodeToInsert, nextSibling);
         this.#renderedVNode = vNode;
         this.#renderedVNode.forceUpdate();
     }
@@ -9635,17 +9768,40 @@ class VConditionalDirective {
         }
         // Destroy VNode first (calls @unmount hooks while DOM is still accessible)
         this.#renderedVNode.destroy();
-        // Then remove from DOM
-        this.#renderedVNode.node.parentNode?.removeChild(this.#renderedVNode.node);
+        // Then remove from DOM. Handle fragment markers if present
+        const startMarker = this.#renderedVNode.userData.get?.('vif_fragment_start');
+        const endMarker = this.#renderedVNode.userData.get?.('vif_fragment_end');
+        if (startMarker && endMarker && startMarker.parentNode === endMarker.parentNode && startMarker.parentNode) {
+            const parentNode = startMarker.parentNode;
+            let node = startMarker;
+            while (node) {
+                const next = node.nextSibling;
+                parentNode.removeChild(node);
+                if (node === endMarker)
+                    break;
+                node = next;
+            }
+            this.#renderedVNode = undefined;
+            return;
+        }
+        const parent = this.#renderedVNode.node.parentNode;
+        if (parent) {
+            parent.removeChild(this.#renderedVNode.node);
+        }
         this.#renderedVNode = undefined;
     }
     /**
      * Clones the original node of the directive's virtual node.
-     * This is used to create a new instance of the node for rendering.
-     * @returns The cloned HTMLElement.
+     * When the source element is a <template>, returns a DocumentFragment
+     * cloned from the template's content.
+     * @returns The cloned Node (HTMLElement or DocumentFragment).
      */
     #cloneNode() {
         const element = this.#vNode.node;
+        if (element instanceof HTMLTemplateElement) {
+            // Return a DocumentFragment cloned from the template content
+            return element.content.cloneNode(true);
+        }
         return element.cloneNode(true);
     }
     /**
@@ -9963,10 +10119,28 @@ class VForDirective {
                 vNode.destroy();
             }
         }
-        // Then remove from DOM
+        // Then remove from DOM. Handle both Element nodes and fragment-marked ranges.
         for (const vNode of nodesToRemove) {
-            if (vNode.node.parentNode) {
-                vNode.node.parentNode.removeChild(vNode.node);
+            // If this VNode stored fragment markers, remove the range between them
+            const startMarker = vNode.userData.get?.('vfor_fragment_start');
+            const endMarker = vNode.userData.get?.('vfor_fragment_end');
+            if (startMarker && endMarker && startMarker.parentNode === endMarker.parentNode && startMarker.parentNode) {
+                const parentNode = startMarker.parentNode;
+                let node = startMarker;
+                // Remove nodes from startMarker up to and including endMarker
+                while (node) {
+                    const next = node.nextSibling;
+                    parentNode.removeChild(node);
+                    if (node === endMarker)
+                        break;
+                    node = next;
+                }
+                continue;
+            }
+            // Fallback: remove the node itself if it's attached
+            const parentOfNode = vNode.node.parentNode;
+            if (parentOfNode) {
+                parentOfNode.removeChild(vNode.node);
             }
         }
         // Add or reorder items
@@ -10000,6 +10174,28 @@ class VForDirective {
                     bindings,
                     dependentIdentifiers: depIds,
                 });
+                // If clone is a DocumentFragment, insert it between start/end comment markers
+                if (clone.nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
+                    const startMarker = document.createComment('#vfor-fragment-start');
+                    const endMarker = document.createComment('#vfor-fragment-end');
+                    // Insert start and end markers and the fragment's children between them
+                    if (prevNode.nextSibling) {
+                        parent.insertBefore(startMarker, prevNode.nextSibling);
+                    }
+                    else {
+                        parent.appendChild(startMarker);
+                    }
+                    parent.insertBefore(endMarker, startMarker.nextSibling);
+                    parent.insertBefore(clone, endMarker);
+                    // Store markers on the VNode for later removal/movement
+                    vNode.userData.set('vfor_fragment_start', startMarker);
+                    vNode.userData.set('vfor_fragment_end', endMarker);
+                    newRenderedItems.set(key, vNode);
+                    vNode.forceUpdate();
+                    // Use endMarker as prevNode for subsequent insertions
+                    prevNode = endMarker;
+                    continue;
+                }
                 // Determine what to insert: anchor node (if exists) or the clone itself
                 const nodeToInsert = vNode.anchorNode || clone;
                 // Insert after previous node
@@ -10017,8 +10213,9 @@ class VForDirective {
                 newRenderedItems.set(key, vNode);
                 // Update bindings
                 this.#updateItemBindings(vNode, context);
-                // Determine the actual node in DOM: anchor node (if exists) or vNode.node
-                const actualNode = vNode.anchorNode || vNode.node;
+                // Determine the actual node in DOM: prefer fragment end marker, then anchor node, then vNode.node
+                const fragmentEnd = vNode.userData.get?.('vfor_fragment_end');
+                const actualNode = fragmentEnd || vNode.anchorNode || vNode.node;
                 // Move to correct position if needed
                 if (prevNode.nextSibling !== actualNode) {
                     if (prevNode.nextSibling) {
@@ -10029,8 +10226,9 @@ class VForDirective {
                     }
                 }
             }
-            // Use anchor node as prevNode if it exists, otherwise use vNode.node
-            prevNode = vNode.anchorNode || vNode.node;
+            // Use fragment end marker > anchor node > vNode.node as prevNode
+            const fragmentEndForPrev = vNode.userData.get?.('vfor_fragment_end');
+            prevNode = fragmentEndForPrev || vNode.anchorNode || vNode.node;
         }
         // Update rendered items map
         this.#renderedItems = newRenderedItems;
@@ -10209,12 +10407,17 @@ class VForDirective {
     }
     /**
      * Clones the original node of the directive's virtual node.
-     * This is used to create a new instance of the node for rendering.
-     * @returns The cloned HTMLElement.
+     * When the source element is a <template>, its children (stored in .content)
+     * are cloned into a DocumentFragment so that multiple root nodes can be
+     * managed without adding an extra wrapper element.
+     * @returns The cloned Node (Element or DocumentFragment).
      */
     #cloneNode() {
-        // Clone the original element
         const element = this.#vNode.node;
+        if (element instanceof HTMLTemplateElement) {
+            // Return a cloned DocumentFragment containing the template content
+            return element.content.cloneNode(true);
+        }
         return element.cloneNode(true);
     }
     /**
@@ -11055,10 +11258,12 @@ class VOnDirective {
             this.#eventName = parts[0];
             parts.slice(1).forEach(mod => this.#modifiers.add(mod));
         }
-        // Parse the expression to extract identifiers and create the handler wrapper
+        // Parse the expression to extract identifiers and create the handler wrapper.
+        // Event handlers are parsed in script mode so that users can write multi-statement bodies
+        // (e.g. "a=1; b=2"), declarations, and control-flow constructs — matching Vue semantics.
         const expression = context.attribute.value;
         if (expression) {
-            this.#dependentIdentifiers = ExpressionUtils.extractIdentifiers(expression, context.vNode.vApplication.functionDependencies);
+            this.#dependentIdentifiers = ExpressionUtils.extractIdentifiers(expression, context.vNode.vApplication.functionDependencies, { asScript: true });
         }
         // Check if this is a lifecycle hook or a regular event
         if (this.#eventName && this.#isLifecycleHook(this.#eventName)) {
@@ -11272,10 +11477,11 @@ class VOnDirective {
                 // This allows the method to access the DOM element, VNode, and userData
                 return originalMethod($ctx);
             }
-            // For inline expressions, rewrite to use 'this' context
-            // This allows assignments like "currentTab = 'shop'" to work correctly
-            const rewrittenExpr = this.#rewriteExpression(expression, identifiers);
-            const funcBody = `return (${rewrittenExpr});`;
+            // For inline bodies, rewrite to use 'this' context
+            // This allows assignments like "currentTab = 'shop'" to work correctly.
+            // Script mode allows multi-statement bodies (e.g. "a=1; init()") and control-flow.
+            const rewrittenExpr = this.#rewriteExpression(expression, identifiers, { asScript: true });
+            const funcBody = rewrittenExpr;
             const func = new Function('$ctx', funcBody);
             return func.call(bindings?.raw, $ctx);
         };
@@ -11305,12 +11511,15 @@ class VOnDirective {
                 // Pass event as first argument and $ctx as second argument
                 return originalMethod(event, $ctx);
             }
-            // For inline expressions, rewrite to use 'this' context
-            // This allows assignments like "currentTab = 'shop'" to work correctly
-            const rewrittenExpr = this.#rewriteExpression(expression, identifiers);
-            const funcBody = `return (${rewrittenExpr});`;
-            const func = new Function('event', '$ctx', funcBody);
-            return func.call(bindings?.raw, event, $ctx);
+            // For inline bodies, rewrite to use 'this' context
+            // This allows assignments like "currentTab = 'shop'" to work correctly.
+            // Script mode allows multi-statement bodies (e.g. "a=1; b=2") and control-flow,
+            // so we emit the rewritten source directly as the function body (no `return (...)`).
+            const rewrittenExpr = this.#rewriteExpression(expression, identifiers, { asScript: true });
+            const funcBody = rewrittenExpr;
+            // '$event' is an alias for 'event' for Vue compatibility
+            const func = new Function('event', '$event', '$ctx', funcBody);
+            return func.call(bindings?.raw, event, event, $ctx);
         };
     }
     /**
@@ -11321,8 +11530,8 @@ class VOnDirective {
      * @param identifiers The list of identifiers that are available in bindings.
      * @returns The rewritten expression.
      */
-    #rewriteExpression(expression, identifiers) {
-        return ExpressionUtils.rewriteExpression(expression, identifiers);
+    #rewriteExpression(expression, identifiers, options) {
+        return ExpressionUtils.rewriteExpression(expression, identifiers, options);
     }
 }
 
@@ -13020,6 +13229,7 @@ class VDOM {
     /**
      * Gets the component registry.
      * @return {VComponentRegistry} The component registry.
+     * @deprecated This method is deprecated and will be removed in a future release. Please use the new component registration system instead.
      */
     static get componentRegistry() {
         return this.#componentRegistry;
@@ -13063,5 +13273,260 @@ class VDOM {
     }
 }
 
-export { ExpressionUtils, ReactiveProxy, VComponent, VComponentRegistry, VDOM };
+// Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+/**
+ * Base class for ichigo.js-backed Web Components (Light DOM, no Shadow DOM).
+ *
+ * Mount timing:
+ *  - If the component declares no props, the VApplication is mounted synchronously
+ *    at the end of connectedCallback (the template is known, no props to wait for).
+ *  - If the component declares props, the VApplication is mounted the first time
+ *    _setProp() is called after connectedCallback has prepared the DOM. This
+ *    guarantees that the parent framework (e.g. ichigo.js VBindDirective) has
+ *    already delivered at least one prop value before data() is evaluated.
+ *
+ * Subclasses must set the static fields _template, _props and _buildOptions before
+ * calling customElements.define(). defineComponent() handles this automatically.
+ */
+class IchigoElement extends HTMLElement {
+    /**
+     * The mounted VApplication instance, present only while connected to the DOM.
+     */
+    #app;
+    /**
+     * Stores prop values received at any time (before or after mount).
+     */
+    #propValues = {};
+    /**
+     * The root element cloned from the template, ready for mounting.
+     * Set by connectedCallback; cleared on disconnect.
+     */
+    #mountRoot;
+    /**
+     * Whether a mount microtask is already queued to avoid double-mounting.
+     */
+    #mountScheduled = false;
+    connectedCallback() {
+        // --- 0. Guard: skip if template not yet loaded ---
+        // customElements.define() may run before loadComponent() completes (e.g. when
+        // dynamic imports are inlined by the bundler). The static placeholder element
+        // in the HTML will be removed and replaced by v-for once the template is ready,
+        // so it is safe to do nothing here.
+        const ctor = this.constructor;
+        const templateEl = document.querySelector(ctor._template);
+        if (!templateEl || !(templateEl instanceof HTMLTemplateElement)) {
+            return;
+        }
+        // --- 1. Capture slot content before clearing children ---
+        const defaultSlotNodes = [];
+        const namedSlotNodes = new Map();
+        for (const child of Array.from(this.childNodes)) {
+            if (child.nodeType === Node.ELEMENT_NODE) {
+                const el = child;
+                const slotName = el.getAttribute('slot');
+                if (slotName) {
+                    if (!namedSlotNodes.has(slotName)) {
+                        namedSlotNodes.set(slotName, []);
+                    }
+                    namedSlotNodes.get(slotName).push(el);
+                    // Remove slot attribute so ichigo.js doesn't try to bind it
+                    el.removeAttribute('slot');
+                }
+                else {
+                    defaultSlotNodes.push(el);
+                }
+            }
+            else if (child.nodeType === Node.TEXT_NODE) {
+                if ((child.textContent ?? '').trim()) {
+                    defaultSlotNodes.push(child);
+                }
+            }
+        }
+        // Clear host element so we can append the cloned template
+        while (this.firstChild) {
+            this.removeChild(this.firstChild);
+        }
+        // --- 2. Clone the component template ---
+        const fragment = templateEl.content.cloneNode(true);
+        const root = this.#findRootElement(fragment);
+        // --- 3. Distribute named slot content ---
+        for (const [name, nodes] of namedSlotNodes) {
+            const slot = root.querySelector(`slot[name="${name}"]`);
+            if (slot) {
+                slot.replaceWith(...nodes);
+            }
+        }
+        // --- 4. Distribute default slot content ---
+        const defaultSlot = root.querySelector('slot:not([name])');
+        if (defaultSlot && defaultSlotNodes.length > 0) {
+            defaultSlot.replaceWith(...defaultSlotNodes);
+        }
+        // Attach the populated template to the host element
+        this.appendChild(root);
+        this.#mountRoot = root;
+        // If props were set before connectedCallback, ensure mount is scheduled
+        this.#scheduleMountIfNeeded();
+        // --- 5. Mount strategy ---
+        // If this component has no declared props, mount immediately.
+        // If it has props, mount will be triggered from _setProp() once the parent
+        // delivers the first prop value (via VBindDirective / forceUpdate).
+        if (ctor._props.length === 0) {
+            this.#doMount();
+        }
+        // else: wait for _setProp() to trigger #scheduleMountIfNeeded()
+    }
+    disconnectedCallback() {
+        this.#mountRoot = undefined;
+        this.#mountScheduled = false;
+        if (this.#app) {
+            this.#app.unmount();
+            this.#app = undefined;
+        }
+    }
+    /**
+     * Called by the property setters generated by defineComponent().
+     * Before mount: stores the value and schedules a mount microtask.
+     * After mount: pushes the value directly into the reactive bindings.
+     */
+    _setProp(name, value) {
+        this.#propValues[name] = value;
+        if (this.#app) {
+            this.#app.bindings?.set(name, value);
+        }
+        else {
+            this.#scheduleMountIfNeeded();
+        }
+    }
+    /**
+     * Called by the property getters generated by defineComponent().
+     */
+    _getProp(name) {
+        return this.#propValues[name];
+    }
+    // --- Static fields set by defineComponent() ---
+    /**
+     * CSS selector for the component's <template> element (e.g. '#my-card').
+     */
+    static _template;
+    /**
+     * List of declared prop names. Used to decide whether to defer mounting.
+     */
+    static _props = [];
+    /**
+     * Factory that builds VApplicationOptions from the current prop values.
+     * Implemented by defineComponent() as a closure that captures the user's options.
+     */
+    static _buildOptions;
+    // --- Private helpers ---
+    /**
+     * Schedules a mount microtask if the DOM root is ready and no mount is pending.
+     * Called from _setProp() so the mount happens after the prop value is stored.
+     */
+    #scheduleMountIfNeeded() {
+        if (this.#mountScheduled || this.#app || !this.#mountRoot) {
+            return;
+        }
+        this.#mountScheduled = true;
+        queueMicrotask(() => {
+            this.#mountScheduled = false;
+            this.#doMount();
+        });
+    }
+    #doMount() {
+        if (this.#app || !this.#mountRoot) {
+            return;
+        }
+        const ctor = this.constructor;
+        const options = ctor._buildOptions(this.#propValues);
+        this.#app = VDOM.createApp(options);
+        this.#app.mount(this.#mountRoot);
+    }
+    #findRootElement(fragment) {
+        for (const node of Array.from(fragment.childNodes)) {
+            if (node.nodeType === Node.ELEMENT_NODE) {
+                return node;
+            }
+        }
+        throw new Error(`IchigoElement: no root element found in template '${this.constructor._template}'`);
+    }
+}
+
+// Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+/**
+ * Defines and registers a custom element backed by ichigo.js reactivity.
+ *
+ * Usage:
+ * ```html
+ * <template id="my-list">
+ *   <div>
+ *     <ul v-if="items.length > 0">
+ *       <li v-for="item of items">{{item.name}}</li>
+ *     </ul>
+ *     <slot></slot>
+ *   </div>
+ * </template>
+ * ```
+ * ```typescript
+ * defineComponent('my-list', {
+ *   template: '#my-list',
+ *   props: ['items'],
+ *   data() {
+ *     return { items: this.items ?? [] };
+ *   },
+ * });
+ * ```
+ * ```html
+ * <my-list :items="searchResults">
+ *   <span slot="empty">No results.</span>
+ * </my-list>
+ * ```
+ *
+ * @param tagName  Custom element tag name (must contain a hyphen, e.g. 'my-card').
+ * @param options  Component options including template selector and optional props.
+ */
+function defineComponent(tagName, options) {
+    const { props = [], template, data, computed, methods, watch, logLevel } = options;
+    // Build a subclass of IchigoElement specific to this component
+    class ComponentElement extends IchigoElement {
+        static _template = template;
+        static _props = props;
+        static _buildOptions(propValues) {
+            return {
+                data() {
+                    // 'this' is the $ctx object provided by VApplication ({ $markRaw }).
+                    // We extend it with prop values so the user's data() can reference them
+                    // via 'this.propName' and supply defaults (e.g. `this.items ?? []`).
+                    const ctx = { $markRaw: ReactiveProxy.markRaw.bind(ReactiveProxy), ...propValues };
+                    const userData = data
+                        ? data.call(ctx)
+                        : {};
+                    // Props are always included in data so they are reactive from the start.
+                    // User-returned values take precedence (allow transforming/defaulting props).
+                    return { ...propValues, ...userData };
+                },
+                computed,
+                methods,
+                watch,
+                logLevel,
+            };
+        }
+    }
+    // Generate a property getter/setter for each declared prop.
+    // This enables the parent VApplication to push updates via `element.propName = value`.
+    for (const prop of props) {
+        Object.defineProperty(ComponentElement.prototype, prop, {
+            get() {
+                return this._getProp(prop);
+            },
+            set(value) {
+                this._setProp(prop, value);
+            },
+            configurable: true,
+            enumerable: true,
+        });
+    }
+    customElements.define(tagName, ComponentElement);
+}
+
+export { ExpressionUtils, IchigoElement, ReactiveProxy, VComponent, VComponentRegistry, VDOM, defineComponent };
 //# sourceMappingURL=ichigo.esm.js.map