@mintjamsinc/ichigojs 0.1.73 → 0.1.75

package/dist/ichigo.esm.js

@@ -173,6 +173,8 @@ var StandardDirectiveName;
     StandardDirectiveName["V_TEXT"] = "v-text";
     /** Focus management directive. */
     StandardDirectiveName["V_FOCUS"] = "v-focus";
+    /** Template reference directive (Vue's `ref` / `$refs`). */
+    StandardDirectiveName["REF"] = "ref";
 })(StandardDirectiveName || (StandardDirectiveName = {}));
 
 // This file was generated. Do not modify manually!
@@ -8434,6 +8436,13 @@ class VBindings {
      * Flag to suppress onChange callbacks temporarily.
      */
     #suppressOnChange = false;
+    /**
+     * Flag forcing the next write through the `set` trap to stay in THIS scope's own
+     * local store instead of walking up to an inherited binding of the same name.
+     * Set only by {@link setLocal} for scope-local variables (e.g. v-for loop items),
+     * which must shadow — never overwrite — a parent binding with the same key.
+     */
+    #localWrite = false;
     /**
      * Per-instance path aliases. Maps local variable names to their reactive source paths.
      * Scoped here instead of the global ReactiveProxy map so that v-for items each maintain
@@ -8512,8 +8521,13 @@ class VBindings {
                     setter(value);
                     return true;
                 }
+                // For a key that is not local to this scope, an assignment normally
+                // retargets to the nearest parent that owns it, so reassignments
+                // (e.g. `count = count + 1` in a handler) mutate the original binding.
+                // A scope-local write (setLocal — used for v-for loop variables) skips
+                // this walk so the variable shadows, never clobbers, an inherited key.
                 let target = obj;
-                if (!Reflect.has(target, key)) {
+                if (!this.#localWrite && !Reflect.has(target, key)) {
                     for (let parent = this.#parent; parent; parent = parent.#parent) {
                         if (Reflect.has(parent.#local, key)) {
                             target = parent.#local;
@@ -8688,6 +8702,25 @@ class VBindings {
     set(key, value) {
         this.#local[key] = value;
     }
+    /**
+     * Sets a binding value in THIS scope's own local store, without walking up to a
+     * parent scope. Used for scope-local variables (e.g. v-for loop items) that must
+     * shadow — never overwrite — an inherited binding of the same name. Contrast with
+     * {@link set}, which retargets a write of an inherited key to the owning parent so
+     * that reassignments mutate the original; a loop variable named like a root data /
+     * method / computed key (e.g. `t`) would otherwise clobber it.
+     * @param key The binding name.
+     * @param value The binding value.
+     */
+    setLocal(key, value) {
+        this.#localWrite = true;
+        try {
+            this.#local[key] = value;
+        }
+        finally {
+            this.#localWrite = false;
+        }
+    }
     /**
      * Gets a binding value.
      * @param key The binding name.
@@ -10783,26 +10816,30 @@ class VForDirective {
      * Sets item bindings for a VNode, handling nested destructuring if needed.
      */
     #setItemBindings(bindings, context) {
+        // Loop variables are scope-local: they must shadow, never overwrite, an
+        // inherited binding of the same name (a data / method / computed key on a
+        // parent scope). setLocal writes to this iteration's own store so a loop
+        // variable named like e.g. the i18n helper `t` cannot clobber it.
         if (this.#itemDestructure && Array.isArray(context.item)) {
             // Nested destructuring: spread array items to individual bindings
             // e.g., item = ['alice', 1] with itemDestructure = ['k', 'v']
-            // bindings.set('k', 'alice')
-            // bindings.set('v', 1)
+            // bindings.setLocal('k', 'alice')
+            // bindings.setLocal('v', 1)
             this.#itemDestructure.forEach((name, i) => {
-                bindings.set(name, context.item[i]);
+                bindings.setLocal(name, context.item[i]);
             });
         }
         else if (this.#itemName) {
             // Simple item binding
-            bindings.set(this.#itemName, context.item);
+            bindings.setLocal(this.#itemName, context.item);
         }
         if (this.#indexName) {
             // For objects, use objectKey if available; otherwise use numeric index
-            bindings.set(this.#indexName, context.objectKey ?? context.index);
+            bindings.setLocal(this.#indexName, context.objectKey ?? context.index);
         }
         if (this.#thirdName) {
             // Third argument is always the numeric index
-            bindings.set(this.#thirdName, context.index);
+            bindings.setLocal(this.#thirdName, context.index);
         }
     }
     /**
@@ -13306,6 +13343,240 @@ class VFocusDirective {
     }
 }
 
+// Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+/**
+ * Directive for registering template references (Vue's `ref` / `$refs`).
+ *
+ * Usage:
+ *     <input ref="search">                     Static name. $refs.search === the element.
+ *     <my-card ref="card"></my-card>           On a component: $refs.card === the host element.
+ *     <li v-for="i in items" ref="rows">       Inside v-for: $refs.rows === array of elements.
+ *     <input :ref="dynamicName">               Dynamic name from an expression (evaluated at mount).
+ *     <input :ref="el => collect(el)">          Function ref: called with the element on mount,
+ *                                              and with null on unmount (great for v-for / dynamic).
+ *
+ * Behavior notes:
+ * - The reference is registered during the mount phase (before any `@mounted` hook fires) and
+ *   removed during the unmount phase, mirroring Vue's lifecycle for `$refs`.
+ * - `$refs` is intentionally NON-reactive: registering or clearing a ref never schedules a render
+ *   and must not be used to drive reactive template output (this matches Vue).
+ * - When the same `ref` name appears inside a `v-for` (i.e. one of the element's ancestors is a
+ *   `v-for` template), the entries are collected into an array, in registration order. Reused
+ *   v-for rows are not re-registered, so the array order is not guaranteed to match DOM order after
+ *   reordering — the same caveat Vue documents.
+ * - Cleanup is identity-safe: a ref slot (or array entry) is only cleared when it still points at
+ *   THIS element, so a freshly mounted element that reused the name is never clobbered by the
+ *   teardown of the element it replaced.
+ *
+ * The directive is purely lifecycle-driven: it has no DOM updater and never templatizes the node.
+ */
+class VRefDirective {
+    /**
+     * The virtual node to which this directive is applied.
+     */
+    #vNode;
+    /**
+     * The static ref name parsed from `ref="name"`. Undefined for the dynamic `:ref` form.
+     */
+    #staticName;
+    /**
+     * Expression evaluator for the dynamic `:ref` / `v-bind:ref` form. Undefined for static refs.
+     */
+    #evaluator;
+    /**
+     * The name under which this element was actually registered, retained so unmount removes the
+     * exact same slot it created (the dynamic name is evaluated once at mount and may differ from
+     * the source expression). Undefined when nothing was registered (function ref, or empty value).
+     */
+    #registeredName;
+    /**
+     * The function supplied by a function ref (`:ref="el => ..."`), retained so it can be invoked
+     * with null on unmount. Undefined unless a function ref was used.
+     */
+    #functionRef;
+    /**
+     * Whether this ref is registered in array mode (collected because it lives inside a v-for).
+     * Resolved lazily at mount time via {@link #isInsideForLoop}.
+     */
+    #asArray = false;
+    /**
+     * @param context The context for parsing the directive.
+     */
+    constructor(context) {
+        this.#vNode = context.vNode;
+        const attrName = context.attribute.name;
+        const isDynamic = attrName !== StandardDirectiveName.REF; // ":ref" or "v-bind:ref"
+        if (isDynamic) {
+            // Dynamic / function ref: the value is an expression.
+            const expression = context.attribute.value;
+            if (expression && context.vNode.bindings) {
+                this.#evaluator = ExpressionEvaluator.create(expression, context.vNode.bindings, context.vNode.vApplication.functionDependencies);
+            }
+        }
+        else {
+            // Static ref: the value is the literal name.
+            const name = context.attribute.value.trim();
+            this.#staticName = name.length > 0 ? name : undefined;
+        }
+        // Remove the directive attribute from the element so it does not linger in the DOM.
+        this.#vNode.node.removeAttribute(attrName);
+    }
+    /**
+     * @inheritdoc
+     */
+    get name() {
+        return StandardDirectiveName.REF;
+    }
+    /**
+     * @inheritdoc
+     */
+    get vNode() {
+        return this.#vNode;
+    }
+    /**
+     * @inheritdoc
+     */
+    get needsAnchor() {
+        return false;
+    }
+    /**
+     * @inheritdoc
+     */
+    get bindingsPreparer() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get domUpdater() {
+        // Refs are resolved once at mount; they are deliberately not reactive (see class docs).
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get templatize() {
+        return false;
+    }
+    /**
+     * @inheritdoc
+     */
+    get dependentIdentifiers() {
+        // This directive never drives reactive updates, so it contributes no dependencies.
+        return [];
+    }
+    /**
+     * @inheritdoc
+     */
+    get onMount() {
+        // Register during the mount phase so the reference is available before any `@mounted`
+        // hook runs (those fire a frame later via requestAnimationFrame).
+        return () => this.#register();
+    }
+    /**
+     * @inheritdoc
+     */
+    get onMounted() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUpdate() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUpdated() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUnmount() {
+        return undefined;
+    }
+    /**
+     * @inheritdoc
+     */
+    get onUnmounted() {
+        // Clear during the unmount phase. The element reference is still valid here.
+        return () => this.#unregister();
+    }
+    /**
+     * @inheritdoc
+     */
+    destroy() {
+        // No additional cleanup beyond onUnmounted; kept for interface completeness.
+    }
+    /**
+     * Registers this element under its resolved ref name (or invokes its function ref).
+     */
+    #register() {
+        const element = this.#vNode.node;
+        if (this.#evaluator) {
+            // Dynamic / function ref.
+            let value;
+            try {
+                value = this.#evaluator.evaluate();
+            }
+            catch {
+                // Evaluation errors are already logged by ExpressionEvaluator; nothing to register.
+                return;
+            }
+            if (typeof value === 'function') {
+                this.#functionRef = value;
+                this.#functionRef(element);
+                return;
+            }
+            if (value === null || value === undefined || value === '') {
+                return; // Nothing to register under an empty dynamic name.
+            }
+            this.#registeredName = String(value);
+        }
+        else if (this.#staticName) {
+            this.#registeredName = this.#staticName;
+        }
+        if (!this.#registeredName) {
+            return;
+        }
+        this.#asArray = this.#isInsideForLoop();
+        this.#vNode.vApplication.registerRef(this.#registeredName, element, this.#asArray);
+    }
+    /**
+     * Removes this element's reference (or invokes its function ref with null).
+     */
+    #unregister() {
+        if (this.#functionRef) {
+            this.#functionRef(null);
+            this.#functionRef = undefined;
+            return;
+        }
+        if (this.#registeredName) {
+            this.#vNode.vApplication.unregisterRef(this.#registeredName, this.#vNode.node);
+            this.#registeredName = undefined;
+        }
+    }
+    /**
+     * Determines whether this element is rendered inside a `v-for` by walking up the VNode tree.
+     * A `v-for` multiplies its template into N rows, so a static ref name on (or within) a row is
+     * shared by N elements and must be collected into an array — matching Vue's documented
+     * "ref inside v-for yields an array" behavior. The walk inspects ancestors only: the directive
+     * lives on a cloned row (or a descendant of one), and the clone's parent chain leads back to the
+     * `v-for` template node, which still carries the `v-for` directive.
+     */
+    #isInsideForLoop() {
+        for (let ancestor = this.#vNode.parentVNode; ancestor; ancestor = ancestor.parentVNode) {
+            const hasFor = ancestor.directiveManager?.directives?.some(d => d.name === StandardDirectiveName.V_FOR);
+            if (hasFor) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+
 // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
 /**
  * The directive parser for standard directives.
@@ -13350,15 +13621,33 @@ class VStandardDirectiveParser {
             context.attribute.name === StandardDirectiveName.V_TEXT ||
             // v-focus, v-focus.<modifier>
             context.attribute.name === StandardDirectiveName.V_FOCUS ||
-            context.attribute.name.startsWith(StandardDirectiveName.V_FOCUS + ".")) {
+            context.attribute.name.startsWith(StandardDirectiveName.V_FOCUS + ".") ||
+            // ref, :ref, v-bind:ref
+            this.#isRefAttribute(context.attribute.name)) {
             return true;
         }
         return false;
     }
+    /**
+     * Determines whether the attribute is a template reference (`ref`, `:ref`, or `v-bind:ref`).
+     * The dynamic forms also match the generic v-bind shorthand, so {@link parse} dispatches them
+     * to VRefDirective explicitly before the v-bind branch is reached.
+     */
+    #isRefAttribute(name) {
+        return name === StandardDirectiveName.REF ||
+            name === ":" + StandardDirectiveName.REF ||
+            name === StandardDirectiveName.V_BIND + ":" + StandardDirectiveName.REF;
+    }
     /**
      * @inheritdoc
      */
     parse(context) {
+        // ref, :ref, v-bind:ref
+        // Checked before the v-bind branch below, since ":ref" / "v-bind:ref" also match the
+        // generic v-bind shorthand but must be handled as template references, not attribute binds.
+        if (this.#isRefAttribute(context.attribute.name)) {
+            return new VRefDirective(context);
+        }
         if (context.attribute.name === StandardDirectiveName.V_IF) {
             return new VIfDirective(context);
         }
@@ -13795,6 +14084,17 @@ class VApplication {
      * The watcher manager for this application.
      */
     #watcher;
+    /**
+     * Template references registered by the `ref` directive, exposed to data(), methods, and
+     * expressions as `$refs` (Vue's `$refs`). Each entry is either a single Element or, for a
+     * `ref` used inside `v-for`, an array of Elements.
+     *
+     * This object is intentionally marked raw (non-reactive): mutating it when an element mounts or
+     * unmounts must never schedule a render, and it must not be used to drive reactive template
+     * output — matching Vue's semantics for `$refs`. It is held as a direct field (in addition to
+     * being injected as the `$refs` binding) so registration is a plain property write.
+     */
+    #refs = {};
     /**
      * Flag to indicate if an update is already scheduled.
      */
@@ -13895,6 +14195,13 @@ class VApplication {
     get functionDependencies() {
         return this.#functionDependencies;
     }
+    /**
+     * Gets the template references registered via the `ref` directive (Vue's `$refs`). The same
+     * object is exposed to data(), methods, and expressions as `$refs`. Non-reactive by design.
+     */
+    get refs() {
+        return this.#refs;
+    }
     /**
      * Mounts the application.
      * @param target The CSS selector string or HTMLElement to mount the application to.
@@ -14023,6 +14330,56 @@ class VApplication {
         }
         return identifiers;
     }
+    /**
+     * Registers a template reference under the given name. Called by the `ref` directive during the
+     * mount phase. When {@param asArray} is true (the element lives inside a `v-for`), references
+     * accumulate into an array in registration order; otherwise the name holds a single element.
+     *
+     * Mutates the raw (non-reactive) `$refs` object directly, so this never schedules a render.
+     *
+     * @param name The ref name.
+     * @param element The element (or component host element) to register.
+     * @param asArray Whether to collect into an array (refs used inside a v-for).
+     */
+    registerRef(name, element, asArray) {
+        if (asArray) {
+            const current = this.#refs[name];
+            if (Array.isArray(current)) {
+                if (!current.includes(element)) {
+                    current.push(element);
+                }
+            }
+            else {
+                this.#refs[name] = [element];
+            }
+            return;
+        }
+        this.#refs[name] = element;
+    }
+    /**
+     * Removes a template reference registered under the given name. Called by the `ref` directive
+     * during the unmount phase. The removal is identity-safe: an entry is only cleared when it still
+     * points at {@param element}, so a newly mounted element that reused the name is never clobbered
+     * by the teardown of the element it replaced.
+     *
+     * @param name The ref name.
+     * @param element The element whose registration should be removed.
+     */
+    unregisterRef(name, element) {
+        const current = this.#refs[name];
+        if (Array.isArray(current)) {
+            const index = current.indexOf(element);
+            if (index !== -1) {
+                current.splice(index, 1);
+            }
+            if (current.length === 0) {
+                delete this.#refs[name];
+            }
+        }
+        else if (current === element) {
+            delete this.#refs[name];
+        }
+    }
     /**
      * Initializes bindings from data, computed properties, and methods.
      * @returns The initialized bindings object.
@@ -14043,6 +14400,10 @@ class VApplication {
         this.#bindings.set('$nextTick', (callback) => this.#nextTick(callback));
         this.#bindings.set('$markRaw', (obj) => ReactiveProxy.markRaw(obj));
         this.#bindings.set('$emit', (name, detail, options) => this.#emit(name, detail, options));
+        // Inject the (non-reactive) $refs container. Marking it raw prevents VBindings from wrapping
+        // it in a reactive proxy, so populating it from the ref directive never schedules a render.
+        ReactiveProxy.markRaw(this.#refs);
+        this.#bindings.set('$refs', this.#refs);
         // Add methods
         if (this.#options.methods) {
             for (const [key, method] of Object.entries(this.#options.methods)) {