@mintjamsinc/ichigojs 0.1.58 → 0.1.60

package/dist/ichigo.esm.js

@@ -171,6 +171,8 @@ var StandardDirectiveName;
     StandardDirectiveName["V_HTML"] = "v-html";
     /** Text content directive. */
     StandardDirectiveName["V_TEXT"] = "v-text";
+    /** Focus management directive. */
+    StandardDirectiveName["V_FOCUS"] = "v-focus";
 })(StandardDirectiveName || (StandardDirectiveName = {}));
 
 // This file was generated. Do not modify manually!
@@ -8963,6 +8965,13 @@ class VNode {
      * 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.
@@ -9198,6 +9207,17 @@ class VNode {
         }
         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,
@@ -9543,6 +9563,102 @@ class VConditionalDirectiveContext {
     }
 }
 
+// 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.
@@ -9743,19 +9859,7 @@ class VConditionalDirective {
         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;
@@ -9776,19 +9880,11 @@ class VConditionalDirective {
         }
         // 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;
         }
@@ -10054,6 +10150,12 @@ class VForDirective {
         }
         // 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);
             }
@@ -10127,22 +10229,12 @@ class VForDirective {
                 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
@@ -10182,26 +10274,14 @@ class VForDirective {
                     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
@@ -10221,22 +10301,28 @@ class VForDirective {
                 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;
@@ -12295,6 +12381,235 @@ class VTextDirective {
     }
 }
 
+// Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+/**
+ * Directive for managing focus on form elements.
+ *
+ * Usage:
+ *     <input v-focus>                           Focus once on mount.
+ *     <input v-focus.select>                    Focus + select all on mount.
+ *     <input v-focus="isOpen">                  Focus when expression transitions from falsy to truthy.
+ *     <input v-focus.select="isOpen">           Conditional focus + select all.
+ *     <input v-focus.cursor-end="isOpen">       Conditional focus + place caret at end.
+ *
+ * Behavior notes:
+ * - Without an expression, the element is focused exactly once after mount.
+ * - With an expression, focus fires only on the falsy -> truthy edge,
+ *   so the user is not repeatedly re-focused on every reactive update.
+ * - If the value is already truthy on mount, the element is focused.
+ * - Focus is deferred via requestAnimationFrame so that elements which
+ *   become visible just before this directive runs (e.g. inside v-if /
+ *   display:none containers) can still receive focus reliably.
+ */
+class VFocusDirective {
+    /**
+     * The virtual node to which this directive is applied.
+     */
+    #vNode;
+    /**
+     * Optional expression evaluator. When absent, the directive focuses once on mount.
+     */
+    #evaluator;
+    /**
+     * Modifiers extracted from the directive name (e.g. "select", "cursor-end").
+     */
+    #modifiers = new Set();
+    /**
+     * Last evaluated boolean value, used for falsy -> truthy edge detection.
+     */
+    #previousValue = false;
+    /**
+     * @param context The context for parsing the directive.
+     */
+    constructor(context) {
+        this.#vNode = context.vNode;
+        // Extract modifiers from the directive name
+        // e.g., "v-focus.select" -> modifiers = {"select"}
+        const attrName = context.attribute.name;
+        if (attrName.startsWith(StandardDirectiveName.V_FOCUS + '.')) {
+            const parts = attrName.split('.');
+            parts.slice(1).forEach(mod => this.#modifiers.add(mod));
+        }
+        // Parse the expression and create the evaluator (optional)
+        const expression = context.attribute.value;
+        if (expression) {
+            if (!context.vNode.bindings) {
+                throw new Error('VFocusDirective requires bindings when an expression is provided');
+            }
+            this.#evaluator = ExpressionEvaluator.create(expression, context.vNode.bindings, context.vNode.vApplication.functionDependencies);
+        }
+        // Remove the directive attribute from the element
+        this.#vNode.node.removeAttribute(context.attribute.name);
+    }
+    /**
+     * @inheritdoc
+     */
+    get name() {
+        return StandardDirectiveName.V_FOCUS;
+    }
+    /**
+     * @inheritdoc
+     */
+    get vNode() {
+        return this.#vNode;
+    }
+    /**
+     * @inheritdoc
+     */
+    get needsAnchor() {
+        return false;
+    }
+    /**
+     * @inheritdoc
+     */
+    get bindingsPreparer() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get domUpdater() {
+        // Without an expression, there is nothing reactive to track.
+        if (!this.#evaluator) {
+            return undefined;
+        }
+        const identifiers = this.#evaluator.dependentIdentifiers;
+        const evaluator = this.#evaluator;
+        const focusElement = () => this.#focus();
+        const updater = {
+            get dependentIdentifiers() {
+                return identifiers;
+            },
+            applyToDOM: () => {
+                const value = evaluator.evaluateAsBoolean();
+                const previous = this.#previousValue;
+                this.#previousValue = value;
+                // Edge: falsy -> truthy
+                if (!previous && value) {
+                    focusElement();
+                }
+            }
+        };
+        return updater;
+    }
+    /**
+     * @inheritdoc
+     */
+    get templatize() {
+        return false;
+    }
+    /**
+     * @inheritdoc
+     */
+    get dependentIdentifiers() {
+        return this.#evaluator?.dependentIdentifiers ?? [];
+    }
+    /**
+     * @inheritdoc
+     */
+    get onMount() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onMounted() {
+        return () => {
+            if (!this.#evaluator) {
+                // Unconditional: focus once on mount.
+                this.#focus();
+                return;
+            }
+            // Conditional: seed previous value and focus if already truthy on mount.
+            const value = this.#evaluator.evaluateAsBoolean();
+            this.#previousValue = value;
+            if (value) {
+                this.#focus();
+            }
+        };
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUpdate() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUpdated() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUnmount() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUnmounted() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    destroy() {
+        // No specific cleanup needed for this directive.
+    }
+    /**
+     * Focuses the element, applying any modifier-driven post-focus behavior.
+     * Deferred via requestAnimationFrame so that elements transitioning out
+     * of display:none (e.g. inside v-if) can receive focus reliably.
+     */
+    #focus() {
+        const element = this.#vNode.node;
+        if (!element || typeof element.focus !== 'function') {
+            return;
+        }
+        const applyModifiers = () => this.#applyModifiers();
+        requestAnimationFrame(() => {
+            // The element may have been unmounted between scheduling and execution.
+            if (!element.isConnected) {
+                return;
+            }
+            element.focus();
+            applyModifiers();
+        });
+    }
+    /**
+     * Applies modifier-driven behavior after focus.
+     */
+    #applyModifiers() {
+        const element = this.#vNode.node;
+        if (this.#modifiers.has('select')) {
+            const inputEl = element;
+            if (typeof inputEl.select === 'function') {
+                try {
+                    inputEl.select();
+                }
+                catch {
+                    // Some input types (e.g. number) reject select(); ignore.
+                }
+            }
+            return;
+        }
+        if (this.#modifiers.has('cursor-end')) {
+            const inputEl = element;
+            if (typeof inputEl.setSelectionRange === 'function') {
+                const len = (inputEl.value ?? '').length;
+                try {
+                    inputEl.setSelectionRange(len, len);
+                }
+                catch {
+                    // Some input types (e.g. number) do not support selection ranges; ignore.
+                }
+            }
+        }
+    }
+}
+
 // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
 /**
  * The directive parser for standard directives.
@@ -12336,7 +12651,10 @@ class VStandardDirectiveParser {
             // v-html
             context.attribute.name === StandardDirectiveName.V_HTML ||
             // v-text
-            context.attribute.name === StandardDirectiveName.V_TEXT) {
+            context.attribute.name === StandardDirectiveName.V_TEXT ||
+            // v-focus, v-focus.<modifier>
+            context.attribute.name === StandardDirectiveName.V_FOCUS ||
+            context.attribute.name.startsWith(StandardDirectiveName.V_FOCUS + ".")) {
             return true;
         }
         return false;
@@ -12400,6 +12718,11 @@ class VStandardDirectiveParser {
         if (context.attribute.name === StandardDirectiveName.V_TEXT) {
             return new VTextDirective(context);
         }
+        // v-focus, v-focus.<modifier>
+        if (context.attribute.name === StandardDirectiveName.V_FOCUS ||
+            context.attribute.name.startsWith(StandardDirectiveName.V_FOCUS + ".")) {
+            return new VFocusDirective(context);
+        }
         throw new Error(`The attribute "${context.attribute.name}" cannot be parsed by ${this.name}.`);
     }
 }