@mintjamsinc/ichigojs 0.1.67 → 0.1.68

package/dist/ichigo.umd.js

@@ -7981,6 +7981,13 @@
          * 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")
@@ -7995,9 +8002,10 @@
          * @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;
@@ -8017,6 +8025,13 @@
             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) {
@@ -8048,7 +8063,7 @@
                         // 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') {
@@ -8060,7 +8075,7 @@
                             }
                             return function (...args) {
                                 const result = value.apply(this === receiver ? obj : this, args);
-                                onChange(path || undefined);
+                                ReactiveProxy.dispatch(dispatcher, path || undefined);
                                 return result;
                             };
                         }
@@ -8070,7 +8085,7 @@
                             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;
                             };
@@ -8081,7 +8096,7 @@
                             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;
                             };
@@ -8096,7 +8111,7 @@
                     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;
                 },
@@ -8104,7 +8119,7 @@
                     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;
                 }
             });
@@ -8118,6 +8133,74 @@
             }
             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.
          *
@@ -8308,6 +8391,14 @@
          * 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.
@@ -8345,6 +8436,7 @@
                         }
                     }
                     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);
@@ -8354,6 +8446,7 @@
                             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
@@ -8397,6 +8490,34 @@
                     }
                     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
@@ -8425,6 +8546,11 @@
                 },
                 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);
@@ -8506,6 +8632,18 @@
         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.
@@ -13580,6 +13718,7 @@
                 this.#vNode.destroy();
                 this.#vNode = undefined;
             }
+            this.#bindings?.destroy();
             this.#logger.info('Application unmounted.');
         }
         /**