@mintjamsinc/ichigojs 0.1.57 → 0.1.59

package/README.md

@@ -219,6 +219,37 @@ List rendering:
 </ul>
 ```
 
+##### Using `<template>` as a fragment
+
+`v-for` and `v-if` can be placed on a `<template>` element to render
+multiple nodes per iteration without introducing a wrapper element:
+
+```html
+<dl>
+  <template v-for="item in items" :key="item.id">
+    <dt>{{ item.term }}</dt>
+    <dd>{{ item.description }}</dd>
+  </template>
+</dl>
+```
+
+`<template>` supports **either** `v-for` **or** `v-if` per element, but
+**not both on the same `<template>`**. If you need both, either:
+
+1. Nest them on separate `<template>` / element levels:
+    ```html
+    <template v-for="item in items" :key="item.id">
+      <div v-if="item.visible">{{ item.name }}</div>
+    </template>
+    ```
+2. Use a regular element instead of `<template>`:
+    ```html
+    <div v-for="item in items" v-if="item.visible" :key="item.id">...</div>
+    ```
+
+Combining `v-for` and `v-if` on the same element works for all
+non-`<template>` tags (v-for is evaluated first, v-if per iteration).
+
 #### v-show
 
 Toggle visibility:

package/dist/ichigo.cjs

@@ -8653,6 +8653,14 @@
             // Other directives (@click, :class, etc.) will be processed on the cloned/rendered elements.
             const attributes = [];
             if (element.hasAttribute(StandardDirectiveName.V_FOR)) {
+                // <template v-for v-if> is not supported: v-for clones .content (a
+                // DocumentFragment), so the v-if attribute on the <template> itself
+                // is lost. Warn the developer so silent failure is avoided.
+                if (element instanceof HTMLTemplateElement && element.hasAttribute(StandardDirectiveName.V_IF)) {
+                    console.warn('[ichigo.js] <template> cannot combine v-for and v-if. ' +
+                        'The v-if will be ignored. Move v-if to an inner element, ' +
+                        'or replace <template> with a regular element.', element);
+                }
                 // For v-for template element: only process v-for and :key
                 // Other attributes will be processed when child VNodes are created for cloned elements
                 attributes.push(element.getAttributeNode(StandardDirectiveName.V_FOR));
@@ -8961,6 +8969,13 @@
          * VNode is destroyed.
          */
         #userData;
+        /**
+         * When this VNode wraps a <template>-derived DocumentFragment that has been
+         * expanded into the DOM, this range tracks the start/end boundary of the
+         * expanded content. Directives such as v-for and v-if use this to move or
+         * remove the entire fragment atomically.
+         */
+        #fragmentRange;
         /**
          * Creates an instance of the virtual node.
          * @param args The initialization arguments for the virtual node.
@@ -9196,6 +9211,17 @@
             }
             return this.#userData;
         }
+        /**
+         * The DOM range that bounds this VNode's expanded fragment content, if any.
+         * Set by directives that expand a <template> into a DocumentFragment
+         * (currently v-for and v-if).
+         */
+        get fragmentRange() {
+            return this.#fragmentRange;
+        }
+        set fragmentRange(range) {
+            this.#fragmentRange = range;
+        }
         /**
          * The DOM path of this virtual node.
          * This is a string representation of the path from the root to this node,
@@ -9541,6 +9567,102 @@
         }
     }
 
+    // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+    /**
+     * Represents a contiguous range of DOM nodes that conceptually belong to a single VNode
+     * whose source is a <template> element (and therefore expands to multiple sibling nodes
+     * when inserted into the DOM).
+     *
+     * The range is bounded by two comment markers (start and end). All nodes between the
+     * markers (inclusive) form the range. Move and remove operations always act on the
+     * entire range atomically via the DOM Range API, which prevents the marker pair from
+     * becoming desynchronized from the content it bounds.
+     *
+     * This abstraction replaces ad-hoc per-marker bookkeeping previously stored in
+     * {@link VNode.userData} by directives such as v-for and v-if.
+     */
+    class VFragmentRange {
+        #start;
+        #end;
+        constructor(start, end) {
+            this.#start = start;
+            this.#end = end;
+        }
+        /**
+         * Inserts content into a parent before the given reference sibling (or as last
+         * child when {@code refSibling} is null), wrapping it with start/end comment
+         * markers. Returns a {@link VFragmentRange} that tracks the inserted region.
+         *
+         * @param parent      The parent node to insert into.
+         * @param refSibling  The sibling to insert before (null = append).
+         * @param label       A short label used for the marker comment text (helps debugging).
+         * @param content     The content to insert. Typically a DocumentFragment cloned
+         *                    from a template's content, but any Node works.
+         */
+        static insert(parent, refSibling, label, content) {
+            const start = document.createComment(`#${label}-start`);
+            const end = document.createComment(`#${label}-end`);
+            parent.insertBefore(start, refSibling);
+            parent.insertBefore(end, refSibling);
+            parent.insertBefore(content, end);
+            return new VFragmentRange(start, end);
+        }
+        /**
+         * The start marker (inclusive boundary).
+         */
+        get firstNode() {
+            return this.#start;
+        }
+        /**
+         * The end marker (inclusive boundary).
+         */
+        get lastNode() {
+            return this.#end;
+        }
+        /**
+         * Move the entire range (start marker through end marker, inclusive) to be
+         * inserted before {@code refSibling} under {@code parent}. If {@code refSibling}
+         * is null the range is appended.
+         *
+         * Implemented via the DOM Range API so that all nodes between the markers move
+         * together as a single contiguous block, regardless of how many or which kinds
+         * of nodes currently sit between them.
+         */
+        moveBefore(parent, refSibling) {
+            // No-op if already in the desired position
+            if (refSibling === this.#start) {
+                return;
+            }
+            const range = this.#asDomRange();
+            const fragment = range.extractContents();
+            parent.insertBefore(fragment, refSibling);
+            range.detach();
+        }
+        /**
+         * Remove the entire range (start marker through end marker, inclusive) from its
+         * current parent. Safe to call even if the markers are already detached.
+         */
+        remove() {
+            if (!this.#start.parentNode) {
+                return;
+            }
+            const range = this.#asDomRange();
+            range.deleteContents();
+            range.detach();
+        }
+        /**
+         * Builds a DOM {@link Range} that spans from immediately before the start marker
+         * to immediately after the end marker, covering both markers and everything
+         * between them.
+         */
+        #asDomRange() {
+            const range = document.createRange();
+            range.setStartBefore(this.#start);
+            range.setEndAfter(this.#end);
+            return range;
+        }
+    }
+
     // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
     /**
      * Base class for conditional directives such as v-if, v-else-if, and v-else.
@@ -9741,19 +9863,7 @@
             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);
+                vNode.fragmentRange = VFragmentRange.insert(anchorParent, nextSibling, 'vif-fragment', clone);
                 this.#renderedVNode = vNode;
                 this.#renderedVNode.forceUpdate();
                 return;
@@ -9774,19 +9884,11 @@
             }
             // Destroy VNode first (calls @unmount hooks while DOM is still accessible)
             this.#renderedVNode.destroy();
-            // 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;
-                }
+            // Then remove from DOM. Handle fragment ranges if present.
+            const range = this.#renderedVNode.fragmentRange;
+            if (range) {
+                range.remove();
+                this.#renderedVNode.fragmentRange = undefined;
                 this.#renderedVNode = undefined;
                 return;
             }
@@ -10052,6 +10154,12 @@
             }
             // Then remove DOM nodes
             for (const vNode of this.#renderedItems.values()) {
+                const range = vNode.fragmentRange;
+                if (range) {
+                    range.remove();
+                    vNode.fragmentRange = undefined;
+                    continue;
+                }
                 if (vNode.node.parentNode) {
                     vNode.node.parentNode.removeChild(vNode.node);
                 }
@@ -10125,22 +10233,12 @@
                     vNode.destroy();
                 }
             }
-            // Then remove from DOM. Handle both Element nodes and fragment-marked ranges.
+            // Then remove from DOM. Handle both Element nodes and fragment ranges.
             for (const vNode of nodesToRemove) {
-                // 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;
-                    }
+                const range = vNode.fragmentRange;
+                if (range) {
+                    range.remove();
+                    vNode.fragmentRange = undefined;
                     continue;
                 }
                 // Fallback: remove the node itself if it's attached
@@ -10180,26 +10278,14 @@
                         bindings,
                         dependentIdentifiers: depIds,
                     });
-                    // If clone is a DocumentFragment, insert it between start/end comment markers
+                    // If clone is a DocumentFragment, wrap it in a VFragmentRange so the
+                    // entire expanded content moves/removes as one atomic unit.
                     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);
+                        const range = VFragmentRange.insert(parent, prevNode.nextSibling, 'vfor-fragment', clone);
+                        vNode.fragmentRange = range;
                         newRenderedItems.set(key, vNode);
                         vNode.forceUpdate();
-                        // Use endMarker as prevNode for subsequent insertions
-                        prevNode = endMarker;
+                        prevNode = range.lastNode;
                         continue;
                     }
                     // Determine what to insert: anchor node (if exists) or the clone itself
@@ -10219,22 +10305,28 @@
                     newRenderedItems.set(key, vNode);
                     // Update bindings
                     this.#updateItemBindings(vNode, context);
-                    // 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) {
-                            parent.insertBefore(actualNode, prevNode.nextSibling);
+                    // For fragment-backed iterations, move the entire range atomically.
+                    // For single-node iterations, move just the node.
+                    const range = vNode.fragmentRange;
+                    if (range) {
+                        if (prevNode.nextSibling !== range.firstNode) {
+                            range.moveBefore(parent, prevNode.nextSibling);
                         }
-                        else {
-                            parent.appendChild(actualNode);
+                    }
+                    else {
+                        const actualNode = vNode.anchorNode || vNode.node;
+                        if (prevNode.nextSibling !== actualNode) {
+                            if (prevNode.nextSibling) {
+                                parent.insertBefore(actualNode, prevNode.nextSibling);
+                            }
+                            else {
+                                parent.appendChild(actualNode);
+                            }
                         }
                     }
                 }
-                // Use fragment end marker > anchor node > vNode.node as prevNode
-                const fragmentEndForPrev = vNode.userData.get?.('vfor_fragment_end');
-                prevNode = fragmentEndForPrev || vNode.anchorNode || vNode.node;
+                // Advance prevNode to this iteration's last DOM node
+                prevNode = vNode.fragmentRange?.lastNode ?? vNode.anchorNode ?? vNode.node;
             }
             // Update rendered items map
             this.#renderedItems = newRenderedItems;