@mintjamsinc/ichigojs 0.1.74 → 0.1.76

package/dist/ichigo.umd.js

@@ -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!
@@ -9174,6 +9176,83 @@
         }
     }
 
+    // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+    /**
+     * The default Object.prototype.toString, used to detect plain objects that
+     * have not overridden their string representation.
+     */
+    const objectToString = Object.prototype.toString;
+    /**
+     * Checks if the value is a non-null object.
+     */
+    function isObject(value) {
+        return value !== null && typeof value === 'object';
+    }
+    /**
+     * Checks if the value is a plain object (i.e. `[object Object]`).
+     */
+    function isPlainObject(value) {
+        return objectToString.call(value) === '[object Object]';
+    }
+    /**
+     * Converts a symbol to a readable string, leaving other values untouched.
+     * Used when rendering Map keys and Set entries.
+     */
+    function stringifySymbol(value, index = '') {
+        return typeof value === 'symbol' ? `Symbol(${value.description ?? index})` : value;
+    }
+    /**
+     * JSON.stringify replacer that renders values JSON cannot represent natively
+     * (Map, Set, Symbol, and non-plain objects) in a readable form.
+     */
+    function replacer(_key, value) {
+        if (value instanceof Map) {
+            return {
+                [`Map(${value.size})`]: [...value.entries()].reduce((entries, [key, val], i) => {
+                    entries[`${stringifySymbol(key, i)} =>`] = val;
+                    return entries;
+                }, {}),
+            };
+        }
+        if (value instanceof Set) {
+            return {
+                [`Set(${value.size})`]: [...value.values()].map(v => stringifySymbol(v)),
+            };
+        }
+        if (typeof value === 'symbol') {
+            return stringifySymbol(value);
+        }
+        if (isObject(value) && !Array.isArray(value) && !isPlainObject(value)) {
+            // Non-plain objects (Date, RegExp, DOM nodes, ...) render via their own toString
+            return String(value);
+        }
+        return value;
+    }
+    /**
+     * Converts a value to a string suitable for display in rendered output,
+     * following Vue's `toDisplayString` semantics:
+     * - strings are returned as-is
+     * - null and undefined become an empty string
+     * - arrays and plain objects (without a custom toString) are rendered as
+     *   pretty-printed JSON, with Map/Set/Symbol entries made readable
+     * - everything else is converted with String()
+     * @param value The value to convert.
+     * @returns The display string for the value.
+     */
+    function toDisplayString(value) {
+        if (typeof value === 'string') {
+            return value;
+        }
+        if (value === null || value === undefined) {
+            return '';
+        }
+        if (Array.isArray(value) ||
+            (isObject(value) && (value.toString === objectToString || typeof value.toString !== 'function'))) {
+            return JSON.stringify(value, replacer, 2);
+        }
+        return String(value);
+    }
+
     // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
     /**
      * List of standard JavaScript global objects that should be available in expressions.
@@ -9294,8 +9373,9 @@
                             return GLOBAL_OBJECTS[name];
                         return undefined;
                     });
-                    // Evaluate the expression and replace {{...}} in the text
-                    result = result.replace(matches[i][0], String(evaluator.func(...values)));
+                    // Evaluate the expression and replace {{...}} in the text.
+                    // A function replacement keeps `$`-patterns in the value literal.
+                    result = result.replace(matches[i][0], () => toDisplayString(evaluator.func(...values)));
                 });
                 return result;
             };
@@ -13056,8 +13136,7 @@
                 },
                 applyToDOM() {
                     const element = vNode.node;
-                    const textContent = evaluator.evaluate();
-                    element.textContent = textContent ?? '';
+                    element.textContent = toDisplayString(evaluator.evaluate());
                 }
             };
             return updater;
@@ -13347,6 +13426,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 +13704,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 +14167,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 +14278,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 +14413,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 +14483,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)) {
@@ -14720,6 +15123,7 @@
     exports.VComponentRegistry = VComponentRegistry;
     exports.VDOM = VDOM;
     exports.defineComponent = defineComponent;
+    exports.toDisplayString = toDisplayString;
 
 }));
 //# sourceMappingURL=ichigo.umd.js.map