@mintjamsinc/ichigojs 0.1.58 → 0.1.60

package/dist/ichigo.cjs

@@ -177,6 +177,8 @@
         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!
@@ -8969,6 +8971,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.
@@ -9204,6 +9213,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,
@@ -9549,6 +9569,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.
@@ -9749,19 +9865,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;
@@ -9782,19 +9886,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;
             }
@@ -10060,6 +10156,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);
                 }
@@ -10133,22 +10235,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
@@ -10188,26 +10280,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
@@ -10227,22 +10307,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;
@@ -12301,6 +12387,235 @@
         }
     }
 
+    // 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.
@@ -12342,7 +12657,10 @@
                 // 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;
@@ -12406,6 +12724,11 @@
             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}.`);
         }
     }