@mintjamsinc/ichigojs 0.1.54 → 0.1.56

package/dist/ichigo.cjs

@@ -7,6 +7,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 {
         /**
@@ -44,6 +45,7 @@
     // 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 {
         /**
@@ -6735,11 +6737,18 @@
          * 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') {
@@ -6971,10 +6980,10 @@
          * @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',
@@ -6986,7 +6995,7 @@
             // 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);
@@ -7008,7 +7017,26 @@
             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) => {
@@ -7019,6 +7047,10 @@
                     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) {
@@ -7030,10 +7062,10 @@
                             }
                         }
                     }
-                    // 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
                     });
                 });
@@ -7474,6 +7506,14 @@
             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);
             }
@@ -7557,6 +7597,46 @@
         #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.
          */
@@ -8937,6 +9017,18 @@
                     });
                 }
             }
+            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);
         }
@@ -9191,6 +9283,16 @@
                     });
                 }
             }
+            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.
@@ -9240,6 +9342,12 @@
                     });
                 }
             }
+            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.
@@ -9617,9 +9725,11 @@
             }
             // 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,
@@ -9627,6 +9737,29 @@
                 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();
         }
@@ -9641,17 +9774,40 @@
             }
             // 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);
         }
         /**
@@ -9969,10 +10125,28 @@
                     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
@@ -10006,6 +10180,28 @@
                         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
@@ -10023,8 +10219,9 @@
                     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) {
@@ -10035,8 +10232,9 @@
                         }
                     }
                 }
-                // 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;
@@ -10215,12 +10413,17 @@
         }
         /**
          * 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);
         }
         /**
@@ -11061,10 +11264,12 @@
                 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)) {
@@ -11278,10 +11483,11 @@
                     // 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);
             };
@@ -11311,12 +11517,15 @@
                     // 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);
             };
         }
         /**
@@ -11327,8 +11536,8 @@
          * @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);
         }
     }
 
@@ -13026,6 +13235,7 @@
         /**
          * 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;
@@ -13069,11 +13279,268 @@
         }
     }
 
+    // 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);
+    }
+
     exports.ExpressionUtils = ExpressionUtils;
+    exports.IchigoElement = IchigoElement;
     exports.ReactiveProxy = ReactiveProxy;
     exports.VComponent = VComponent;
     exports.VComponentRegistry = VComponentRegistry;
     exports.VDOM = VDOM;
+    exports.defineComponent = defineComponent;
 
 }));
 //# sourceMappingURL=ichigo.cjs.map