@mintjamsinc/ichigojs 0.1.54 → 0.1.55

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 {
     /**
@@ -7468,6 +7470,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 +7561,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 +8981,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 +9247,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 +9306,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 +9689,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 +9701,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 +9738,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 +10089,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 +10144,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 +10183,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 +10196,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 +10377,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);
     }
     /**
@@ -13020,6 +13193,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 +13237,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