@mintjamsinc/ichigojs 0.1.66 → 0.1.67

package/dist/ichigo.cjs

@@ -11537,6 +11537,15 @@
      * 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
@@ -11575,6 +11584,26 @@
          * 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.
          */
@@ -11598,6 +11627,12 @@
                 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.
@@ -11707,11 +11742,10 @@
          * @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);
             }
         }
         /**
@@ -11727,8 +11761,21 @@
             }
             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
@@ -11814,6 +11861,14 @@
                 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);
@@ -11822,11 +11877,26 @@
                 // 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.
@@ -13610,6 +13680,7 @@
             // 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)) {
@@ -13855,6 +13926,38 @@
                 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.
@@ -14147,7 +14250,7 @@
      * @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;
@@ -14169,6 +14272,7 @@
                     computed,
                     methods,
                     watch,
+                    emits,
                     logLevel,
                 };
             }