@mintjamsinc/ichigojs 0.1.67 → 0.1.69

package/dist/ichigo.esm.js

@@ -7975,6 +7975,13 @@ class ReactiveProxy {
      * This allows retrieving the source path of an object for computed property mapping.
      */
     static proxyPaths = new WeakMap();
+    /**
+     * Dispatchers per (target, path). Every target reached while walking a proxy
+     * subtree registers an entry pointing at the same dispatcher as the outermost
+     * proxy of that subtree, so callers can look up the dispatcher from any
+     * intermediate proxy when subscribing.
+     */
+    static dispatchers = new WeakMap();
     /**
      * A Map to store path aliases.
      * Key: alias path (e.g., "editingNestedStep.steps")
@@ -7989,9 +7996,10 @@ class ReactiveProxy {
      * @param target The object to make reactive.
      * @param onChange Callback function to call when the object changes. Receives the full path of the changed property.
      * @param path The current path in the object tree (used internally for nested objects).
+     * @param inheritedDispatcher Internal: the dispatcher inherited from an enclosing create() call when wrapping a nested target. External callers must omit this.
      * @returns A reactive proxy of the target object.
      */
-    static create(target, onChange, path = '') {
+    static create(target, onChange, path = '', inheritedDispatcher) {
         // If the target is not an object or is null, return it as-is
         if (typeof target !== 'object' || target === null) {
             return target;
@@ -8011,6 +8019,13 @@ class ReactiveProxy {
         if (this.proxyToTarget.has(target)) {
             return target;
         }
+        // Resolve (and register) the dispatcher for this (target, path).
+        // Nested create() calls inherit the dispatcher from the enclosing call so
+        // that a single dispatcher fans out changes at any depth of the subtree.
+        const dispatcher = this.resolveDispatcher(target, path, inheritedDispatcher);
+        if (onChange) {
+            dispatcher.listeners.add(onChange);
+        }
         // Check if we already have a proxy for this target with this path
         let pathMap = this.proxyCache.get(target);
         if (pathMap) {
@@ -8042,7 +8057,7 @@ class ReactiveProxy {
                     // Build the nested path
                     const keyStr = String(key);
                     const nestedPath = path ? (Array.isArray(obj) ? `${path}[${keyStr}]` : `${path}.${keyStr}`) : keyStr;
-                    return ReactiveProxy.create(value, onChange, nestedPath);
+                    return ReactiveProxy.create(value, undefined, nestedPath, dispatcher);
                 }
                 // If the value is a function, we need to wrap it to ensure that any mutations it performs also trigger onChange
                 if (typeof value === 'function') {
@@ -8054,7 +8069,7 @@ class ReactiveProxy {
                         }
                         return function (...args) {
                             const result = value.apply(this === receiver ? obj : this, args);
-                            onChange(path || undefined);
+                            ReactiveProxy.dispatch(dispatcher, path || undefined);
                             return result;
                         };
                     }
@@ -8064,7 +8079,7 @@ class ReactiveProxy {
                         return function (...args) {
                             const result = value.apply(this === receiver ? obj : this, args);
                             if (mapMutationMethods.includes(key)) {
-                                onChange(path || undefined);
+                                ReactiveProxy.dispatch(dispatcher, path || undefined);
                             }
                             return result;
                         };
@@ -8075,7 +8090,7 @@ class ReactiveProxy {
                         return function (...args) {
                             const result = value.apply(this === receiver ? obj : this, args);
                             if (setMutationMethods.includes(key)) {
-                                onChange(path || undefined);
+                                ReactiveProxy.dispatch(dispatcher, path || undefined);
                             }
                             return result;
                         };
@@ -8090,7 +8105,7 @@ class ReactiveProxy {
                 if (oldValue !== value) {
                     const keyStr = String(key);
                     const fullPath = path ? (Array.isArray(obj) ? `${path}[${keyStr}]` : `${path}.${keyStr}`) : keyStr;
-                    onChange(fullPath);
+                    ReactiveProxy.dispatch(dispatcher, fullPath);
                 }
                 return result;
             },
@@ -8098,7 +8113,7 @@ class ReactiveProxy {
                 const result = Reflect.deleteProperty(obj, key);
                 const keyStr = String(key);
                 const fullPath = path ? (Array.isArray(obj) ? `${path}[${keyStr}]` : `${path}.${keyStr}`) : keyStr;
-                onChange(fullPath);
+                ReactiveProxy.dispatch(dispatcher, fullPath);
                 return result;
             }
         });
@@ -8112,6 +8127,74 @@ class ReactiveProxy {
         }
         return proxy;
     }
+    /**
+     * Looks up the dispatcher associated with (target, path), or installs a new one.
+     * When called for a nested target during proxy walking, the enclosing dispatcher
+     * is reused so a single subtree fans out changes through one notification path.
+     */
+    static resolveDispatcher(target, path, inheritedDispatcher) {
+        let pathMap = this.dispatchers.get(target);
+        if (!pathMap) {
+            pathMap = new Map();
+            this.dispatchers.set(target, pathMap);
+        }
+        const existing = pathMap.get(path);
+        if (existing) {
+            return existing;
+        }
+        const dispatcher = inheritedDispatcher ?? { listeners: new Set() };
+        pathMap.set(path, dispatcher);
+        return dispatcher;
+    }
+    /**
+     * Invokes every listener attached to the dispatcher.
+     * Iterates a snapshot of the listener set so unsubscribing during dispatch is safe.
+     */
+    static dispatch(dispatcher, changedPath) {
+        if (dispatcher.listeners.size === 0) {
+            return;
+        }
+        const snapshot = Array.from(dispatcher.listeners);
+        for (const listener of snapshot) {
+            listener(changedPath);
+        }
+    }
+    /**
+     * Subscribes a listener to changes inside the subtree of an existing reactive proxy.
+     *
+     * The listener is scoped by the proxy's source path: only changes at or below that
+     * path are delivered, which lets a child component receive notifications when the
+     * nested contents of a prop change even though the prop reference itself is unchanged.
+     *
+     * @param proxyOrTarget A proxy returned from create(), or the underlying target object.
+     * @param listener Called with the full source path of every relevant change.
+     * @returns A function that removes the subscription.
+     */
+    static subscribe(proxyOrTarget, listener) {
+        if (typeof proxyOrTarget !== 'object' || proxyOrTarget === null) {
+            return () => { };
+        }
+        const target = (this.proxyToTarget.get(proxyOrTarget) ?? proxyOrTarget);
+        const scopePath = this.proxyPaths.get(proxyOrTarget) ?? '';
+        const pathMap = this.dispatchers.get(target);
+        const dispatcher = pathMap?.get(scopePath);
+        if (!dispatcher) {
+            return () => { };
+        }
+        const wrapper = scopePath
+            ? (changedPath) => {
+                if (changedPath === scopePath ||
+                    (typeof changedPath === 'string' && (changedPath.startsWith(scopePath + '.') ||
+                        changedPath.startsWith(scopePath + '[')))) {
+                    listener(changedPath);
+                }
+            }
+            : listener;
+        dispatcher.listeners.add(wrapper);
+        return () => {
+            dispatcher.listeners.delete(wrapper);
+        };
+    }
     /**
      * Checks if the given object is a reactive proxy.
      *
@@ -8302,6 +8385,14 @@ class VBindings {
      * is updated by the recompute cycle through `setSilent`, which bypasses this routing.
      */
     #writableComputeds = new Map();
+    /**
+     * Unsubscribe handles for external reactive proxies received as binding values
+     * (typically component props). Each entry keeps the child bindings notified when
+     * nested properties of a shared object change even though the prop reference itself
+     * stays the same. The previous subscription is released whenever the binding value
+     * is replaced, the binding is set to null/undefined, or the bindings are destroyed.
+     */
+    #externalSubscriptions = new Map();
     /**
      * Creates a new instance of VBindings.
      * @param parent The parent bindings, if any.
@@ -8339,6 +8430,7 @@ class VBindings {
                     }
                 }
                 let newValue = value;
+                let receivedExternalProxy = false;
                 if (typeof value === 'object' && value !== null) {
                     // Check if the value already has a path (it's an existing reactive proxy reference)
                     const existingPath = ReactiveProxy.getPath(value);
@@ -8348,6 +8440,7 @@ class VBindings {
                         this.#logger?.debug(`Path alias registered: ${key} -> ${existingPath}`);
                         // Keep the existing proxy as-is to preserve reactivity chain
                         newValue = value;
+                        receivedExternalProxy = true;
                     }
                     else {
                         // Before wrapping, check if any properties are existing ReactiveProxies
@@ -8391,6 +8484,34 @@ class VBindings {
                 }
                 const oldValue = Reflect.get(target, key);
                 const result = Reflect.set(target, key, newValue);
+                // Manage external subscription to a reactive proxy received as the value.
+                // When the reference changes, drop the previous subscription. When a new
+                // reactive proxy is installed, subscribe so nested changes propagate to
+                // this bindings instance even though the proxy reference itself is stable.
+                if (oldValue !== newValue) {
+                    const prevUnsubscribe = this.#externalSubscriptions.get(key);
+                    if (prevUnsubscribe) {
+                        prevUnsubscribe();
+                        this.#externalSubscriptions.delete(key);
+                    }
+                }
+                if (receivedExternalProxy && !this.#externalSubscriptions.has(key)) {
+                    const unsubscribe = ReactiveProxy.subscribe(newValue, (changedPath) => {
+                        if (!changedPath) {
+                            return;
+                        }
+                        let path = '';
+                        for (const part of changedPath.split('.')) {
+                            path = path ? `${path}.${part}` : part;
+                            this.#logger?.debug(`Binding changed (external): ${path}`);
+                            this.#changes.add(path);
+                        }
+                        if (!this.#suppressOnChange) {
+                            this.#onChange?.(changedPath);
+                        }
+                    });
+                    this.#externalSubscriptions.set(key, unsubscribe);
+                }
                 // Detect changes
                 let hasChanged = oldValue !== newValue;
                 // Special handling for arrays: check length changes even if same object reference
@@ -8419,6 +8540,11 @@ class VBindings {
             },
             deleteProperty: (obj, key) => {
                 const result = Reflect.deleteProperty(obj, key);
+                const prevUnsubscribe = this.#externalSubscriptions.get(key);
+                if (prevUnsubscribe) {
+                    prevUnsubscribe();
+                    this.#externalSubscriptions.delete(key);
+                }
                 this.#logger?.debug(`Binding deleted: ${key}`);
                 this.#changes.add(key);
                 this.#onChange?.(key);
@@ -8500,6 +8626,18 @@ class VBindings {
     remove(key) {
         delete this.#local[key];
     }
+    /**
+     * Releases all external proxy subscriptions held by these bindings.
+     * Should be called when the owning application is unmounted so the parent
+     * application's reactive objects do not keep references to listener closures
+     * (and through them, this bindings instance) alive.
+     */
+    destroy() {
+        for (const unsubscribe of this.#externalSubscriptions.values()) {
+            unsubscribe();
+        }
+        this.#externalSubscriptions.clear();
+    }
     /**
      * Sets a binding value without triggering onChange callback.
      * This is useful for internal updates that shouldn't trigger reactivity.
@@ -10126,9 +10264,18 @@ class VForDirective {
     #sourceName;
     #useOfSyntax = false; // Track if 'of' syntax was used
     /**
-     * Map to track rendered items by their keys
+     * Ordered list of currently rendered items.
+     *
+     * This is intentionally an ordered array of { key, vNode } entries rather
+     * than a Map<key, VNode>. The :key attribute is a *reconciliation hint*
+     * used to identify and reuse the same logical row across re-renders — it is
+     * not the identity of the rendered set. Keying the rendered set by a Map
+     * would make it structurally impossible to hold two rows that resolve to
+     * the same key, which would silently drop application data. The most
+     * fundamental invariant of a list directive is "N items in => N rows out",
+     * so the rendered set must be a positional list that can carry duplicates.
      */
-    #renderedItems = new Map();
+    #renderedItems = [];
     /**
      * Previous iterations to detect changes
      */
@@ -10251,11 +10398,11 @@ class VForDirective {
     destroy() {
         // Clean up all rendered items
         // First destroy all VNodes (calls @unmount hooks), then remove from DOM
-        for (const vNode of this.#renderedItems.values()) {
+        for (const { vNode } of this.#renderedItems) {
             vNode.destroy();
         }
         // Then remove DOM nodes
-        for (const vNode of this.#renderedItems.values()) {
+        for (const { vNode } of this.#renderedItems) {
             const range = vNode.fragmentRange;
             if (range) {
                 range.remove();
@@ -10266,7 +10413,7 @@ class VForDirective {
                 vNode.node.parentNode.removeChild(vNode.node);
             }
         }
-        this.#renderedItems.clear();
+        this.#renderedItems = [];
         this.#previousIterations = [];
     }
     /**
@@ -10307,7 +10454,24 @@ class VForDirective {
         this.#previousIterations = iterations;
     }
     /**
-     * Key-based diffing for efficient DOM updates
+     * Key-based diffing for efficient DOM updates.
+     *
+     * Reconciliation model
+     * --------------------
+     * The :key attribute is treated as a *hint* for reusing the same logical
+     * row across re-renders, not as the identity of the rendered set. The
+     * previously rendered rows are placed into a pool keyed by :key (a queue
+     * per key, so equal keys can hold more than one row). Each incoming
+     * iteration then claims a row from its key's queue when one is available,
+     * otherwise a fresh row is created. Whatever stays in the pool at the end
+     * is genuinely gone and is destroyed and removed.
+     *
+     * This guarantees the directive's most fundamental invariant — "N items in
+     * => N rows out" — even when the application supplies duplicate keys. We
+     * still warn on duplicates because they make reuse ambiguous (reordering
+     * becomes positional rather than identity-stable), but we never silently
+     * drop the application's data, and no row is ever orphaned: every old row
+     * is either reused or explicitly removed.
      */
     #updateList(newIterations) {
         const parent = this.#vNode.anchorNode?.parentNode;
@@ -10315,22 +10479,38 @@ class VForDirective {
         if (!parent || !anchor) {
             throw new Error('v-for element must have a parent and anchor');
         }
-        const newRenderedItems = new Map();
-        // Track which keys are still needed and detect duplicates
-        const neededKeys = new Set();
+        // Build a reuse pool from the currently rendered rows. A queue per key
+        // (FIFO) lets duplicate keys reuse multiple rows: the first incoming
+        // occurrence claims the first existing row, the second claims the next,
+        // and so on.
+        const pool = new Map();
+        for (const { key, vNode } of this.#renderedItems) {
+            let queue = pool.get(key);
+            if (!queue) {
+                queue = [];
+                pool.set(key, queue);
+            }
+            queue.push(vNode);
+        }
+        // Decide, for each incoming iteration in order, whether it reuses an
+        // existing row or needs a new one. Reused rows are taken out of the
+        // pool so that what remains afterwards is exactly the set to remove.
         const seenKeys = new Set();
-        for (const ctx of newIterations) {
-            if (seenKeys.has(ctx.key)) {
-                console.warn(`[ichigo.js] Duplicate key detected in v-for: "${ctx.key}". This may cause unexpected behavior. Keys should be unique.`);
+        const plan = [];
+        for (const context of newIterations) {
+            if (seenKeys.has(context.key)) {
+                console.warn(`[ichigo.js] Duplicate key detected in v-for: "${context.key}". All entries are still rendered, but reordering may be unstable. Keys should be unique.`);
             }
-            seenKeys.add(ctx.key);
-            neededKeys.add(ctx.key);
+            seenKeys.add(context.key);
+            const queue = pool.get(context.key);
+            const reused = queue && queue.length ? queue.shift() : undefined;
+            plan.push({ context, reused });
         }
-        // Remove items that are no longer needed
+        // Remove rows that were not reused.
         // First destroy VNodes (calls @unmount hooks while DOM is still accessible)
         const nodesToRemove = [];
-        for (const [key, vNode] of this.#renderedItems) {
-            if (!neededKeys.has(key)) {
+        for (const queue of pool.values()) {
+            for (const vNode of queue) {
                 nodesToRemove.push(vNode);
                 vNode.destroy();
             }
@@ -10349,11 +10529,12 @@ class VForDirective {
                 parentOfNode.removeChild(vNode.node);
             }
         }
-        // Add or reorder items
+        // Add or reorder rows, building the new ordered rendered set.
+        const newRenderedItems = [];
         let prevNode = anchor;
-        for (const context of newIterations) {
+        for (const { context, reused } of plan) {
             const { key } = context;
-            let vNode = this.#renderedItems.get(key);
+            let vNode = reused;
             if (!vNode) {
                 // Create new item
                 const clone = this.#cloneNode();
@@ -10385,7 +10566,7 @@ class VForDirective {
                 if (clone.nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
                     const range = VFragmentRange.insert(parent, prevNode.nextSibling, 'vfor-fragment', clone);
                     vNode.fragmentRange = range;
-                    newRenderedItems.set(key, vNode);
+                    newRenderedItems.push({ key, vNode });
                     vNode.forceUpdate();
                     prevNode = range.lastNode;
                     continue;
@@ -10399,12 +10580,12 @@ class VForDirective {
                 else {
                     parent.appendChild(nodeToInsert);
                 }
-                newRenderedItems.set(key, vNode);
+                newRenderedItems.push({ key, vNode });
                 vNode.forceUpdate();
             }
             else {
                 // Reuse existing item
-                newRenderedItems.set(key, vNode);
+                newRenderedItems.push({ key, vNode });
                 // Update bindings
                 this.#updateItemBindings(vNode, context);
                 // For fragment-backed iterations, move the entire range atomically.
@@ -10430,7 +10611,7 @@ class VForDirective {
             // Advance prevNode to this iteration's last DOM node
             prevNode = vNode.fragmentRange?.lastNode ?? vNode.anchorNode ?? vNode.node;
         }
-        // Update rendered items map
+        // Update the ordered rendered set
         this.#renderedItems = newRenderedItems;
     }
     /**
@@ -13574,6 +13755,7 @@ class VApplication {
             this.#vNode.destroy();
             this.#vNode = undefined;
         }
+        this.#bindings?.destroy();
         this.#logger.info('Application unmounted.');
     }
     /**