@mintjamsinc/ichigojs 0.1.65 → 0.1.67

package/dist/ichigo.esm.js

@@ -6859,11 +6859,16 @@ class ExpressionUtils {
                 const ast = parse(source, { ecmaVersion: "latest" });
                 const dependencies = new Set();
                 const declaredVariables = new Set();
+                const thisAliases = new Set();
                 // First, collect all declared variables (const, let, var, function params, etc.)
                 ancestor(ast, {
                     VariableDeclarator(node) {
                         if (node.id.type === 'Identifier') {
                             declaredVariables.add(node.id.name);
+                            // Detect aliases assigned from `this`, e.g. `let vm = this;`
+                            if (node.init && node.init.type === 'ThisExpression') {
+                                thisAliases.add(node.id.name);
+                            }
                         }
                     },
                     FunctionDeclaration(node) {
@@ -6915,9 +6920,14 @@ class ExpressionUtils {
                         }
                     },
                     MemberExpression(node) {
-                        // Handle 'this.propertyName' patterns
-                        if (node.object.type === 'ThisExpression' && node.property.type === 'Identifier') {
-                            dependencies.add(node.property.name);
+                        // Handle 'this.propertyName' patterns and aliases like 'vm.x' when 'vm = this'
+                        if (node.property.type === 'Identifier') {
+                            if (node.object.type === 'ThisExpression') {
+                                dependencies.add(node.property.name);
+                            }
+                            else if (node.object.type === 'Identifier' && thisAliases.has(node.object.name)) {
+                                dependencies.add(node.property.name);
+                            }
                         }
                     }
                 });
@@ -7011,7 +7021,7 @@ class ExpressionUtils {
             return expression;
         }
         try {
-            // Build a map of positions to replace: { start: number, end: number, name: string }[]
+            // Build a map of positions to replace: { start: number, end: number, name: string, asThisAlias?: boolean }[]
             const replacements = [];
             // In script mode we must not wrap in parens (that would make multi-statement input invalid).
             // Offsets from the parser therefore refer directly to the original expression, so no shift.
@@ -7020,13 +7030,17 @@ class ExpressionUtils {
             const offsetShift = asScript ? 0 : 1;
             const parsedAst = parse(source, { ecmaVersion: 'latest' });
             // Track identifiers that are locally declared within the handler body (let/const/var, function
-            // params) so we don't rewrite them to `this.xxx`. Only relevant in script mode, where the user
-            // can write declarations; in expression mode there are no declarations to track.
+            // params) so we don't rewrite them to `this.xxx`. Additionally detect `this` aliases such as
+            // `let vm = this;` so that `vm.x` can be rewritten to `this.x` even though `vm` is locally declared.
             const locallyDeclared = new Set();
+            const thisAliases = new Set();
             if (asScript) {
                 full(parsedAst, (node) => {
                     if (node.type === 'VariableDeclarator' && node.id?.type === 'Identifier') {
                         locallyDeclared.add(node.id.name);
+                        if (node.init && node.init.type === 'ThisExpression') {
+                            thisAliases.add(node.id.name);
+                        }
                     }
                     else if (node.type === 'FunctionDeclaration' && node.id?.type === 'Identifier') {
                         locallyDeclared.add(node.id.name);
@@ -7043,20 +7057,34 @@ class ExpressionUtils {
                 if (!bindingIdentifiers.has(node.name)) {
                     return;
                 }
-                // Skip identifiers that were declared locally in the handler body
+                // Locally declared identifiers must not be rewritten to `this.xxx`. The one
+                // exception is a `this`-alias (e.g. `let vm = this;`): when such an alias is
+                // used as the OBJECT of a MemberExpression (`vm.x`), we replace just the
+                // object with `this` so that `vm.x` becomes `this.x`. In every other position
+                // (the declaration LHS, a bare reference such as `console.log(vm)`, an
+                // argument, etc.) the alias must be left untouched — rewriting it to
+                // `this.vm` would either produce a syntax error (`let this.vm = this;`) or
+                // change the meaning at runtime.
+                // walk.fullAncestor includes the visited node itself as the last entry of
+                // `ancestors`, so the actual parent node is at length - 2.
+                const parentNode = ancestors.length >= 2 ? ancestors[ancestors.length - 2] : undefined;
+                const isAliasAsMemberObject = parentNode?.type === 'MemberExpression' && parentNode.object === node;
                 if (locallyDeclared.has(node.name)) {
+                    if (!thisAliases.has(node.name) || !isAliasAsMemberObject) {
+                        return;
+                    }
+                    replacements.push({
+                        start: node.start - offsetShift,
+                        end: node.end - offsetShift,
+                        name: node.name,
+                        asThisAlias: true
+                    });
                     return;
                 }
-                // Check if this identifier is a property of a MemberExpression
-                // (e.g., in 'obj.prop', we should skip 'prop')
-                if (ancestors.length >= 1) {
-                    const parent = ancestors[ancestors.length - 1];
-                    if (parent.type === 'MemberExpression') {
-                        // Skip if this identifier is the property (not the object) of a non-computed member access
-                        if (!parent.computed && parent.property === node) {
-                            return;
-                        }
-                    }
+                // Skip identifiers that are the property (not the object) of a non-computed
+                // member access (e.g., the `prop` in `obj.prop`).
+                if (parentNode?.type === 'MemberExpression' && !parentNode.computed && parentNode.property === node) {
+                    return;
                 }
                 // Add to replacements list (adjust for the wrapping parentheses in expression mode)
                 replacements.push({
@@ -7070,9 +7098,8 @@ class ExpressionUtils {
             // Apply replacements
             let result = expression;
             for (const replacement of replacements) {
-                result = result.substring(0, replacement.start) +
-                    `this.${replacement.name}` +
-                    result.substring(replacement.end);
+                const insertion = replacement.asThisAlias ? 'this' : `this.${replacement.name}`;
+                result = result.substring(0, replacement.start) + insertion + result.substring(replacement.end);
             }
             return result;
         }
@@ -11164,12 +11191,23 @@ class VModelDirective {
     #collectDependentIdentifiers() {
         const ids = new Set(this.#evaluator?.dependentIdentifiers ?? []);
         const element = this.#vNode.node;
-        if (element instanceof HTMLInputElement && element.type === 'checkbox') {
+        if (element instanceof HTMLInputElement) {
             const manager = this.#vNode.directiveManager;
-            for (const attrName of ['value', 'true-value', 'false-value']) {
-                const bindDirective = manager?.findBindDirective(attrName);
-                if (bindDirective) {
-                    bindDirective.dependentIdentifiers.forEach(id => ids.add(id));
+            // For checkboxes and radios, v-model's rendered state depends on
+            // the element's typed `:value` binding (if present). Checkboxes
+            // additionally depend on `:true-value` / `:false-value` bindings.
+            if (element.type === 'checkbox' || element.type === 'radio') {
+                const valueBind = manager?.findBindDirective('value');
+                if (valueBind) {
+                    valueBind.dependentIdentifiers.forEach(id => ids.add(id));
+                }
+            }
+            if (element.type === 'checkbox') {
+                for (const attrName of ['true-value', 'false-value']) {
+                    const bindDirective = manager?.findBindDirective(attrName);
+                    if (bindDirective) {
+                        bindDirective.dependentIdentifiers.forEach(id => ids.add(id));
+                    }
                 }
             }
         }
@@ -11256,11 +11294,13 @@ class VModelDirective {
                 this.#renderCheckbox(element, value);
             }
             else if (element.type === 'radio') {
-                // Prefer the original typed value stored by VBindDirective (:value binding)
-                // to avoid type coercion issues (e.g., boolean false vs string "false").
-                const radioValue = element._value !== undefined
-                    ? element._value
-                    : element.value;
+                // Prefer the typed value from a sibling :value binding when present,
+                // falling back to any stored `_value` or the raw string `value`.
+                const manager = this.#vNode.directiveManager;
+                const bindDirective = manager?.findBindDirective('value');
+                const radioValue = bindDirective !== undefined
+                    ? bindDirective.evaluate()
+                    : (element._value !== undefined ? element._value : element.value);
                 element.checked = radioValue === value;
             }
             else {
@@ -11289,11 +11329,13 @@ class VModelDirective {
                     newValue = this.#computeCheckboxNewValue(target);
                 }
                 else if (target.type === 'radio') {
-                    // Prefer the original typed value stored by VBindDirective (:value binding)
-                    // to preserve the type on write-back (e.g., boolean false, number 0).
-                    newValue = target._value !== undefined
-                        ? target._value
-                        : target.value;
+                    // Prefer the typed value from a sibling :value binding when present,
+                    // falling back to any stored `_value` or the raw string `value`.
+                    const manager = this.#vNode.directiveManager;
+                    const bindDirective = manager?.findBindDirective('value');
+                    newValue = bindDirective !== undefined
+                        ? bindDirective.evaluate()
+                        : (target._value !== undefined ? target._value : target.value);
                 }
                 else {
                     newValue = target.value;
@@ -11489,6 +11531,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
@@ -11527,6 +11578,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.
      */
@@ -11550,6 +11621,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.
@@ -11659,11 +11736,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);
         }
     }
     /**
@@ -11679,8 +11755,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
@@ -11766,6 +11855,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);
@@ -11774,11 +11871,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.
@@ -13562,6 +13674,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)) {
@@ -13807,6 +13920,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.
@@ -14099,7 +14244,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;
@@ -14121,6 +14266,7 @@ function defineComponent(tagName, options) {
                 computed,
                 methods,
                 watch,
+                emits,
                 logLevel,
             };
         }