@mintjamsinc/ichigojs 0.1.74 → 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!
@@ -13341,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.
@@ -13385,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);
         }
@@ -13830,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.
      */
@@ -13930,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.
@@ -14058,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.
@@ -14078,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)) {