@mintjamsinc/ichigojs 0.1.74 → 0.1.75

package/README.md

@@ -15,6 +15,7 @@ A simple and intuitive reactive framework. Lightweight, fast, and user-friendly
 - 🔌 **Lifecycle Hooks** - `@mount`, `@mounted`, `@update`, `@updated`, `@unmount`, `@unmounted` with context (`$ctx`)
 - 💾 **userData Storage** - Proxy-free storage for third-party library instances with auto-cleanup
 - 🧩 **Components** - Reusable Web Components via `defineComponent` with `props`, `slot`, and `$emit`
+- 🔗 **Template refs** - Direct access to DOM elements and component hosts via `ref` and `$refs`
 - 📦 **Lightweight** - Minimal bundle size
 - 🚀 **High Performance** - Efficient batched updates via microtask queue
 - 💪 **TypeScript** - Written in TypeScript with full type support
@@ -823,6 +824,102 @@ methods: {
 }
 ```
 
+### Template refs (`$refs`)
+
+Use the `ref` attribute to obtain a direct reference to a DOM element (or a
+component's host element). Referenced elements are collected into the `$refs`
+object, available on `this` in methods and as `$refs` in template expressions —
+the same mechanism as Vue's `$refs`.
+
+```html
+<input ref="search">
+<button @click="focusSearch">Focus</button>
+```
+
+```javascript
+methods: {
+  focusSearch() {
+    // this.$refs.search is the <input> element
+    this.$refs.search.focus();
+  }
+}
+```
+
+**When refs are available:**
+
+A ref is registered during the element's mount phase and removed during its
+unmount phase, so it is already populated by the time a `@mounted` hook runs.
+After changing data, wait for `$nextTick` before reading refs for elements that
+were just rendered (e.g. by `v-if` / `v-for`).
+
+```javascript
+methods: {
+  async showAndFocus() {
+    this.editing = true;            // reveals <input v-if="editing" ref="field">
+    this.$nextTick(() => this.$refs.field.focus());
+  }
+}
+```
+
+**Refs on components:**
+
+A `ref` on a component resolves to the component's **host custom element**, so
+you can call DOM methods on it (focus, scroll, `getBoundingClientRect`,
+`dispatchEvent`, etc.).
+
+```html
+<my-card ref="card"></my-card>
+```
+
+```javascript
+this.$refs.card; // the <my-card> element
+```
+
+**Refs inside `v-for` (arrays):**
+
+When `ref` is used on (or inside) a `v-for`, the matching elements are collected
+into an **array** under that name.
+
+```html
+<ul>
+  <li v-for="item in items" :key="item.id" ref="rows">{{ item.name }}</li>
+</ul>
+```
+
+```javascript
+this.$refs.rows; // [<li>, <li>, <li>, ...] — one entry per rendered row
+```
+
+Entries are stored in registration order. Because reused rows are not
+re-registered, the array order is not guaranteed to match DOM order after a
+reorder — the same caveat Vue documents.
+
+**Dynamic and function refs (`:ref`):**
+
+Bind `ref` with `:ref` to compute it from an expression. If the expression
+evaluates to a **string**, it is used as the ref name; if it evaluates to a
+**function**, the function is called with the element on mount and with `null`
+on unmount (a function ref). Function refs are convenient for `v-for` or dynamic
+scenarios where you want full control over storage.
+
+```html
+<!-- Dynamic name -->
+<input :ref="fieldName">
+
+<!-- Function ref -->
+<li v-for="item in items" :key="item.id" :ref="el => registerRow(item.id, el)">
+  {{ item.name }}
+</li>
+```
+
+`:ref` is evaluated once at mount (it does not reactively re-run when the bound
+value changes).
+
+> **Note:** `$refs` is **not reactive**. Registering or clearing a ref never
+> triggers a re-render, and `$refs` should not be used to drive reactive
+> template output — read it from event handlers and lifecycle hooks instead.
+> This matches Vue's behavior.
+
 ## Components
 
 ichigo.js components are real [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)
@@ -996,6 +1093,7 @@ Creates a new application instance.
 - `$markRaw(obj)`: Marks an object as non-reactive (see [Marking Objects as Non-Reactive](#marking-objects-as-non-reactive))
 - `$nextTick(callback)`: Runs a callback after the next DOM update
 - `$emit(name, detail?, options?)`: Dispatches a custom event (see [Events](#events-emit))
+- `$refs`: Object of template references registered via the `ref` attribute (see [Template refs](#template-refs-refs)). Non-reactive.
 - `$ctx`: Lifecycle/handler context with `element`, `vnode`, and `userData`
 
 ### defineComponent(tagName, options)

package/dist/ichigo.cjs

@@ -179,6 +179,8 @@
         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!
@@ -13347,6 +13349,240 @@
         }
     }
 
+    // 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.
@@ -13391,15 +13627,33 @@
                 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);
             }
@@ -13836,6 +14090,17 @@
          * 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.
          */
@@ -13936,6 +14201,13 @@
         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.
@@ -14064,6 +14336,56 @@
             }
             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.
@@ -14084,6 +14406,10 @@
             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)) {