@mintjamsinc/ichigojs 0.1.66 → 0.1.68

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.
@@ -11531,6 +11669,15 @@ class VModelDirective {
  * Mouse button modifiers (MouseEvent): `.left`, `.middle`, `.right`.
  * System modifiers (KeyboardEvent and MouseEvent): `.shift`, `.ctrl`, `.alt`, `.meta`, plus `.exact` to require that no other system modifiers are held.
  *
+ * Listen target and filter modifiers (two orthogonal axes):
+ *   - Listen target (where the listener is attached): `.window`, `.document`. When omitted the listener
+ *     is attached to the bound element. This is useful for global / cross-component events, e.g.
+ *     `@webtop-message.document="onMessage"`, and the listener is removed automatically on unmount.
+ *   - Filter (whether the handler runs): `.self` fires only when `event.target` is the bound element;
+ *     `.outside` fires only when `event.target` is outside the bound element (e.g. click-outside to
+ *     close a popup). `.outside` implies listening on `document` (capture phase) even without `.document`,
+ *     and `.self` / `.outside` are mutually exclusive.
+ *
  * Additionally, this directive supports lifecycle hooks:
  *     @mount="onMount"       - Called before the VNode is mounted to the DOM element
  *     @mounted="onMounted"   - Called after the VNode is mounted to the DOM element
@@ -11569,6 +11716,26 @@ class VOnDirective {
      * The event listener function for DOM events.
      */
     #listener;
+    /**
+     * The resolved target the listener is attached to (element, document, or window).
+     * Stored so destroy() removes the listener from the same target it was added to.
+     */
+    #resolvedTarget;
+    /**
+     * The resolved capture flag. Shared by attach and destroy so they stay in sync,
+     * since `.outside` forces capture phase regardless of the `.capture` modifier.
+     */
+    #useCapture = false;
+    /**
+     * Whether the listener has actually been attached. `.outside` defers attachment by a
+     * microtask, so destroy() must not attempt removal before it is attached.
+     */
+    #attached = false;
+    /**
+     * Whether the directive has been destroyed. Guards the deferred `.outside` attachment
+     * from attaching after the node was already unmounted.
+     */
+    #destroyed = false;
     /**
      * Map of lifecycle hook names to their handler functions.
      */
@@ -11592,6 +11759,12 @@ class VOnDirective {
             this.#eventName = parts[0];
             parts.slice(1).forEach(mod => this.#modifiers.add(mod));
         }
+        // `.self` and `.outside` are mutually exclusive filters; together they can never fire.
+        if (this.#modifiers.has('self') && this.#modifiers.has('outside')) {
+            context.vNode.vApplication.logManager
+                .getLogger('VOnDirective')
+                .warn(`The '.self' and '.outside' modifiers on '${attrName}' are mutually exclusive; the handler will never fire.`);
+        }
         // Parse the expression to extract identifiers and create the handler wrapper.
         // Event handlers are parsed in script mode so that users can write multi-statement bodies
         // (e.g. "a=1; b=2"), declarations, and control-flow constructs — matching Vue semantics.
@@ -11701,11 +11874,10 @@ class VOnDirective {
      * @inheritdoc
      */
     destroy() {
-        // Remove the event listener when the directive is destroyed
-        if (this.#eventName && this.#listener) {
-            const element = this.#vNode.node;
-            const useCapture = this.#modifiers.has('capture');
-            element.removeEventListener(this.#eventName, this.#listener, useCapture);
+        this.#destroyed = true;
+        // Remove the event listener from the same target/phase it was attached to.
+        if (this.#eventName && this.#listener && this.#resolvedTarget && this.#attached) {
+            this.#resolvedTarget.removeEventListener(this.#eventName, this.#listener, this.#useCapture);
         }
     }
     /**
@@ -11721,8 +11893,21 @@ class VOnDirective {
         }
         const element = this.#vNode.node;
         const eventName = this.#eventName;
-        const useCapture = this.#modifiers.has('capture');
         const isOnce = this.#modifiers.has('once');
+        const isOutside = this.#modifiers.has('outside');
+        // Resolve the listen target (orthogonal to filters): `.window` / `.document` attach
+        // the listener globally; `.outside` also requires a global listener to detect events
+        // originating outside the element, so it implies `document`.
+        this.#resolvedTarget = this.#modifiers.has('window')
+            ? window
+            : (this.#modifiers.has('document') || isOutside)
+                ? document
+                : element;
+        // `.outside` listens in capture phase so it is not suppressed by a descendant's
+        // stopPropagation(); otherwise the capture flag follows the `.capture` modifier.
+        this.#useCapture = this.#modifiers.has('capture') || isOutside;
+        const useCapture = this.#useCapture;
+        const target = this.#resolvedTarget;
         // System modifier keys (held during the event) shared by KeyboardEvent and MouseEvent.
         const systemModifiers = ['shift', 'ctrl', 'alt', 'meta'];
         // Create the event listener function
@@ -11808,6 +11993,14 @@ class VOnDirective {
             if (this.#modifiers.has('self') && event.target !== element) {
                 return;
             }
+            // `.outside`: only fire when the event originates outside the bound element.
+            // A non-Node target (e.g. window) is treated as outside.
+            if (isOutside) {
+                const eventTarget = event.target;
+                if (eventTarget instanceof Node && element.contains(eventTarget)) {
+                    return;
+                }
+            }
             // Call the pre-generated handler wrapper (if exists)
             if (this.#handlerWrapper) {
                 this.#handlerWrapper(event);
@@ -11816,11 +12009,26 @@ class VOnDirective {
             // No need to manually call scheduleUpdate() here
             // If 'once' modifier is used, remove the listener after first execution
             if (isOnce && this.#listener) {
-                element.removeEventListener(eventName, this.#listener, useCapture);
+                target.removeEventListener(eventName, this.#listener, useCapture);
+                this.#attached = false;
             }
         };
-        // Attach the event listener
-        element.addEventListener(eventName, this.#listener, useCapture);
+        if (isOutside) {
+            // Defer attachment by one microtask so the listener does not catch the same
+            // interaction that mounted this element (e.g. the click that opened a popup,
+            // which would otherwise immediately close it). Skip if already destroyed.
+            queueMicrotask(() => {
+                if (this.#destroyed || !this.#listener) {
+                    return;
+                }
+                target.addEventListener(eventName, this.#listener, useCapture);
+                this.#attached = true;
+            });
+        }
+        else {
+            target.addEventListener(eventName, this.#listener, useCapture);
+            this.#attached = true;
+        }
     }
     /**
      * Checks if the event name is a lifecycle hook.
@@ -13504,6 +13712,7 @@ class VApplication {
             this.#vNode.destroy();
             this.#vNode = undefined;
         }
+        this.#bindings?.destroy();
         this.#logger.info('Application unmounted.');
     }
     /**
@@ -13604,6 +13813,7 @@ class VApplication {
         // Inject utility methods into bindings
         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));
         // Add methods
         if (this.#options.methods) {
             for (const [key, method] of Object.entries(this.#options.methods)) {
@@ -13849,6 +14059,38 @@ class VApplication {
             compute(key);
         }
     }
+    /**
+     * Dispatches a CustomEvent, providing the framework-level `$emit` available in expressions
+     * and methods. By default the event is dispatched on the application root element with
+     * `bubbles: true`, so a parent component can listen for it via `v-on` / `@` on the component
+     * tag (the root is rendered inside the host custom element, so the event bubbles out of it).
+     *
+     * The dispatch target can be overridden via `options.target` (e.g. `document` / `window`) to
+     * use a global event bus, interoperating with native `addEventListener` listeners.
+     *
+     * @param name The event name (e.g. "selected"). Listened to as `@selected` on the parent side.
+     * @param detail The payload exposed as `event.detail`.
+     * @param options Dispatch options (bubbles, cancelable, composed, target).
+     * @returns The result of dispatchEvent: false if a listener called preventDefault(), otherwise true.
+     */
+    #emit(name, detail, options) {
+        // Documentation/validation only: warn when emitting an event not declared in `emits`.
+        if (this.#options.emits && !this.#options.emits.includes(name)) {
+            this.#logger.warn(`Event '${name}' is emitted but not declared in the 'emits' option.`);
+        }
+        const target = options?.target ?? this.#vNode?.node;
+        if (!target) {
+            this.#logger.warn(`$emit('${name}') was called before the application was mounted; the event was not dispatched.`);
+            return false;
+        }
+        const event = new CustomEvent(name, {
+            detail,
+            bubbles: options?.bubbles ?? true,
+            cancelable: options?.cancelable ?? true,
+            composed: options?.composed ?? false,
+        });
+        return target.dispatchEvent(event);
+    }
     /**
      * Executes a callback after the next DOM update.
      * @param callback The callback to execute.
@@ -14141,7 +14383,7 @@ class IchigoElement extends HTMLElement {
  * @param options  Component options including template selector and optional props.
  */
 function defineComponent(tagName, options) {
-    const { props = [], template, data, computed, methods, watch, logLevel } = options;
+    const { props = [], template, data, computed, methods, watch, emits, logLevel } = options;
     // Build a subclass of IchigoElement specific to this component
     class ComponentElement extends IchigoElement {
         static _template = template;
@@ -14163,6 +14405,7 @@ function defineComponent(tagName, options) {
                 computed,
                 methods,
                 watch,
+                emits,
                 logLevel,
             };
         }