@dooboostore/simple-web-component 1.0.42 → 1.0.44

package/src/decorators/applyProperty.ts

@@ -6,6 +6,32 @@ import { SwcQueryOptions, HelperHostSet } from '../types';
 export interface PropertyOptions extends SwcQueryOptions {
   name?: string | symbol;
   filter?: (target: HTMLElement, value: any, meta: {currentThis: any, helper: HelperHostSet}) => boolean;
+  /**
+   * Custom key to extract value from return object.
+   * If not provided, uses PROPERTY_METADATA_KEY by default.
+   * Useful when multiple @setProperty decorators are on the same method.
+   * 
+   * Example:
+   * @setProperty('selector1', { valueKey: 'prop1' })
+   * @setProperty('selector2', { valueKey: 'prop2' })
+   * myMethod() {
+   *   return {
+   *     prop1: 'value1',
+   *     prop2: 'value2'
+   *   };
+   * }
+   * 
+   * Or with symbols:
+   * @setProperty('selector1', { valueKey: Symbol.for('prop1') })
+   * @setProperty('selector2', { valueKey: Symbol.for('prop2') })
+   * myMethod() {
+   *   return {
+   *     [Symbol.for('prop1')]: 'value1',
+   *     [Symbol.for('prop2')]: 'value2'
+   *   };
+   * }
+   */
+  valueKey?: symbol | string;
 }
 
 export interface PropertyMetadata {
@@ -159,10 +185,39 @@ export function applyProperty(selector: string, targetPropertyKeyOrOptions?: str
         ensureInit(this);
         const res = (original as any).apply(this, args);
 
+        /**
+         * Extract value for this decorator from method return value
+         * 
+         * If return value is an object with this decorator's symbol key,
+         * use that value. Otherwise use the entire return value.
+         * 
+         * Example:
+         * @setProperty('selector')
+         * myMethod() {
+         *   return {
+         *     [PROPERTY_METADATA_KEY]: 'property-value',
+         *     [OTHER_DECORATOR_KEY]: 'other-value'
+         *   };
+         * }
+         * 
+         * This decorator will use 'property-value'
+         */
+        const extractValue = (v: any) => {
+          if (v && typeof v === 'object' && PROPERTY_METADATA_KEY in v) {
+            return v[PROPERTY_METADATA_KEY];
+          }
+          return v;
+        };
+
         if (res instanceof Promise) {
-          return res.then((v: any) => { applyValueToTargets(this, v); return v; });
+          return res.then((v: any) => { 
+            const extracted = extractValue(v);
+            applyValueToTargets(this, extracted); 
+            return v; 
+          });
         } else {
-          applyValueToTargets(this, res);
+          const extracted = extractValue(res);
+          applyValueToTargets(this, extracted);
           return res;
         }
       };
@@ -205,81 +260,60 @@ export function applyProperty(selector: string, targetPropertyKeyOrOptions?: str
 // ============================================
 
 /**
- * @property - Alias for @applyProperty
- */
-export function property(selector: string, targetPropertyKey: string | symbol, options?: PropertyOptions): MethodDecorator & PropertyDecorator;
-export function property(selector: string, options?: PropertyOptions): MethodDecorator & PropertyDecorator;
-export function property(selector: string, targetPropertyKeyOrOptions?: string | symbol | PropertyOptions, options?: PropertyOptions): MethodDecorator & PropertyDecorator {
-  return applyProperty(selector, targetPropertyKeyOrOptions as any, options);
-}
-
-/**
- * @propertyThis - Apply property on $this element
- * Can be used as: @propertyThis or @propertyThis('propertyName') or @propertyThis({ name: 'propertyName' })
+ * @property - Field decorator for binding element properties (read/write)
+ * 
+ * Usage:
+ * - @property('selector', 'propertyName') - Bind to specific property
+ * - @property('selector') - Use field name as property name
+ * - @property('selector', options) - Bind with options
+ * - @property - Bare decorator (binds to $this with field name)
+ * 
+ * Note: This decorator is for FIELDS ONLY. For methods, use @setProperty.
  */
-export function propertyThis(target: Object, propertyKey: string | symbol): void;
-export function propertyThis(targetPropertyKey: string | symbol, options?: PropertyOptions): MethodDecorator & PropertyDecorator;
-export function propertyThis(options?: PropertyOptions): MethodDecorator & PropertyDecorator;
-export function propertyThis(targetOrOptions?: any, propertyKeyOrOptions?: any, descriptor?: PropertyDescriptor): any {
-  // Direct decorator usage: @propertyThis
-  if (typeof targetOrOptions === 'object' && targetOrOptions !== null && !Array.isArray(targetOrOptions) && 
-      (typeof propertyKeyOrOptions === 'string' || typeof propertyKeyOrOptions === 'symbol')) {
-    // Called as @propertyThis (target, propertyKey)
-    return applyProperty('$this', undefined as any, {})(targetOrOptions, propertyKeyOrOptions, descriptor);
+export function property(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function property(selector: string, targetPropertyKey: string | symbol, options?: PropertyOptions): PropertyDecorator;
+export function property(selector: string, options?: PropertyOptions): PropertyDecorator;
+export function property(selectorOrTarget?: string | Object, targetPropertyKeyOrOptions?: any, optionsOrDescriptor?: any): any {
+  // Bare decorator: @property
+  if (optionsOrDescriptor !== undefined && (typeof targetPropertyKeyOrOptions === 'string' || typeof targetPropertyKeyOrOptions === 'symbol')) {
+    return applyProperty('$this', undefined as any, {})(selectorOrTarget as Object, targetPropertyKeyOrOptions, optionsOrDescriptor as PropertyDescriptor);
   }
-  
-  // Called with parameters
-  if (typeof targetOrOptions === 'string' || typeof targetOrOptions === 'symbol') {
-    // @propertyThis('propertyName', options?)
-    return applyProperty('$this', targetOrOptions, propertyKeyOrOptions);
-  } else if (targetOrOptions && typeof targetOrOptions === 'object') {
-    // @propertyThis({ name: 'propertyName' })
-    return applyProperty('$this', undefined as any, targetOrOptions);
-  } else {
-    // @propertyThis() or @propertyThis
-    return applyProperty('$this', undefined as any, {});
+  // With selector
+  if (typeof selectorOrTarget === 'string') {
+    return applyProperty(selectorOrTarget, targetPropertyKeyOrOptions as any, optionsOrDescriptor as PropertyOptions);
   }
+  // Without selector (defaults to $this)
+  return applyProperty('$this', undefined as any, selectorOrTarget as PropertyOptions);
 }
 
 /**
- * @setProperty - Alias for @applyProperty (method-decorator semantics)
+ * @setProperty - Method decorator for setting element properties from method return value
+ * 
+ * Usage:
+ * - @setProperty('selector', 'propertyName') - Set specific property
+ * - @setProperty('selector') - Use method name as property name
+ * - @setProperty('selector', options) - Set with options
+ * - @setProperty - Bare decorator (sets on $this with method name)
+ * 
+ * Note: This decorator is for METHODS ONLY. For fields, use @property.
+ * 
+ * Example:
+ * @setProperty('selector', 'disabled')
+ * disableElement() {
+ *   return true;
+ * }
  */
 export function setProperty(selector: string, targetPropertyKey: string | symbol, options?: PropertyOptions): MethodDecorator;
 export function setProperty(selector: string, options?: PropertyOptions): MethodDecorator;
-export function setProperty(selector: string, targetPropertyKeyOrOptions?: string | symbol | PropertyOptions, options?: PropertyOptions): MethodDecorator {
-  return applyProperty(selector, targetPropertyKeyOrOptions as any, options) as MethodDecorator;
-}
-
-/**
- * @setPropertyThis - Set property on $this element
- * Can be used as: @setPropertyThis or @setPropertyThis('propertyName') or @setPropertyThis({ name: 'propertyName' })
- */
-export function setPropertyThis(target: Object, propertyKey: string | symbol): void;
-export function setPropertyThis(targetPropertyKey: string | symbol, options?: PropertyOptions): MethodDecorator;
-export function setPropertyThis(options?: PropertyOptions): MethodDecorator;
-export function setPropertyThis(targetOrOptions?: any, propertyKeyOrOptions?: any, descriptor?: PropertyDescriptor): any {
-  // Direct decorator usage: @setPropertyThis
-  if (typeof targetOrOptions === 'object' && targetOrOptions !== null && !Array.isArray(targetOrOptions) && 
-      (typeof propertyKeyOrOptions === 'string' || typeof propertyKeyOrOptions === 'symbol')) {
-    // Called as @setPropertyThis (target, propertyKey)
-    return applyProperty('$this', undefined as any, {})(targetOrOptions, propertyKeyOrOptions, descriptor);
-  }
-  
-  // Called with parameters
-  if (typeof targetOrOptions === 'string' || typeof targetOrOptions === 'symbol') {
-    // @setPropertyThis('propertyName', options?)
-    return applyProperty('$this', targetOrOptions, propertyKeyOrOptions) as MethodDecorator;
-  } else if (targetOrOptions && typeof targetOrOptions === 'object') {
-    // @setPropertyThis({ name: 'propertyName' })
-    return applyProperty('$this', undefined as any, targetOrOptions) as MethodDecorator;
-  } else {
-    // @setPropertyThis() or @setPropertyThis
-    return applyProperty('$this', undefined as any, {}) as MethodDecorator;
+export function setProperty(selectorOrOptions?: string | PropertyOptions, targetPropertyKeyOrOptions?: any, optionsOrUndefined?: PropertyOptions): MethodDecorator {
+  // With selector
+  if (typeof selectorOrOptions === 'string') {
+    return applyProperty(selectorOrOptions, targetPropertyKeyOrOptions as any, optionsOrUndefined as PropertyOptions) as MethodDecorator;
   }
+  // Without selector (defaults to $this)
+  return applyProperty('$this', undefined as any, selectorOrOptions as PropertyOptions) as MethodDecorator;
 }
 
-
-
 // ============================================
 // Metadata Helpers
 // ============================================

package/src/decorators/applySlot.ts

@@ -17,16 +17,12 @@ export type ApplySlotPosition = 'prepend' | 'prependHtml' | 'prependText' | 'app
 export interface ApplySlotOptions {
   position: ApplySlotPosition;
   fallback?: (helper: HelperHostSet) => string | Node;
-  // root?: SwcRootType;
   /**
-   * Filter function to determine whether to perform DOM operation.
-   * If it returns false, the operation is skipped.
+   * Custom key to extract value from return object.
+   * If not provided, uses APPLY_SLOT_METADATA_KEY by default.
+   * Useful when multiple @applySlot decorators are on the same method.
    */
-  // filter?: (target: HTMLElement | ShadowRoot, newValue: any, meta:{currentThis: any,helper: HelperHostSet}) => boolean;
-  /**
-   * Optional loading content to display while an async method is executing.
-   */
-  // loading?: (helper: HelperHostSet) => any;
+  valueKey?: symbol | string;
 }
 
 export interface ApplySlotMetadata {
@@ -144,15 +140,33 @@ export function applySlot(targetId: string, opt: OptionalType<ApplySlotOptions,
         applyToDom(swcId, targetId, options.position, nodes);
       }
 
+      /**
+       * Extract value for this decorator from method return value
+       * 
+       * If return value is an object with this decorator's key,
+       * use that value. Otherwise use the entire return value.
+       * 
+       * Uses valueKey from options if provided, otherwise uses APPLY_SLOT_METADATA_KEY.
+       */
+      const extractValue = (v: any) => {
+        const keyToUse = options.valueKey ?? APPLY_SLOT_METADATA_KEY;
+        if (v && typeof v === 'object' && keyToUse in v) {
+          return v[keyToUse];
+        }
+        return v;
+      };
+
       let res = original.apply(this, args);
       if (res instanceof Promise) {
         return res.then(asyncRes => {
-          const nodes = resToNodes(asyncRes)
+          const extracted = extractValue(asyncRes);
+          const nodes = resToNodes(extracted)
           fallbackNodes.forEach((it: any) => it.remove());
           applyToDom(swcId, targetId, options.position, nodes);
         })
       } else {
-        const nodes: Node[] = resToNodes(res);
+        const extracted = extractValue(res);
+        const nodes: Node[] = resToNodes(extracted);
         applyToDom(swcId, targetId, options.position, nodes);
       }
     };

package/src/decorators/applyStyle.ts

@@ -7,6 +7,12 @@ export type StyleAction = 'set' | 'update' | 'remove';
 
 export interface StyleApplyOptions extends SwcQueryOptions {
   filter?: (target: HTMLElement, value: any, meta: {currentThis: any, helper: HelperHostSet}) => boolean;
+  /**
+   * Custom key to extract value from return object.
+   * If not provided, uses STYLE_METADATA_KEY by default.
+   * Useful when multiple @applyStyle decorators are on the same method.
+   */
+  valueKey?: symbol | string;
 }
 
 export interface StyleApplyMetadata {
@@ -34,6 +40,22 @@ function createStyleDecorator(action: StyleAction) {
         ensureInit(this);
         const res = (original as any).apply(this, args);
 
+        /**
+         * Extract value for this decorator from method return value
+         * 
+         * If return value is an object with this decorator's key,
+         * use that value. Otherwise use the entire return value.
+         * 
+         * Uses valueKey from options if provided, otherwise uses STYLE_METADATA_KEY.
+         */
+        const extractValue = (v: any) => {
+          const keyToUse = options.valueKey ?? STYLE_METADATA_KEY;
+          if (v && typeof v === 'object' && keyToUse in v) {
+            return v[keyToUse];
+          }
+          return v;
+        };
+
         const handleResult = (resolvedValue: any) => {
           if (resolvedValue !== undefined) {
             const win = (this as any).ownerDocument?.defaultView || window;
@@ -105,9 +127,9 @@ function createStyleDecorator(action: StyleAction) {
         };
 
         if (res instanceof Promise) {
-          return res.then(handleResult);
+          return res.then((v: any) => handleResult(extractValue(v)));
         } else {
-          return handleResult(res);
+          return handleResult(extractValue(res));
         }
       };
       return descriptor;
@@ -115,21 +137,69 @@ function createStyleDecorator(action: StyleAction) {
   };
 }
 
-export function applyStyle(selector: string, action: StyleAction = 'update', options: StyleApplyOptions = {}): MethodDecorator {
-  return createStyleDecorator(action)(selector, options);
+export function applyStyle(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function applyStyle(selector: string, action?: StyleAction, options?: StyleApplyOptions): MethodDecorator;
+export function applyStyle(selectorOrTarget?: any, actionOrPropertyKey?: any, optionsOrDescriptor?: any): any {
+  // Bare decorator: @applyStyle
+  if (optionsOrDescriptor !== undefined && (typeof actionOrPropertyKey === 'string' || typeof actionOrPropertyKey === 'symbol')) {
+    return createStyleDecorator('update')('$this', {})(selectorOrTarget as Object, actionOrPropertyKey, optionsOrDescriptor as PropertyDescriptor);
+  }
+  // With selector
+  if (typeof selectorOrTarget === 'string') {
+    const action = (typeof actionOrPropertyKey === 'string' ? actionOrPropertyKey : 'update') as StyleAction;
+    const options = (typeof actionOrPropertyKey === 'object' ? actionOrPropertyKey : optionsOrDescriptor) as StyleApplyOptions | undefined;
+    return createStyleDecorator(action)(selectorOrTarget, options);
+  }
+  // Without selector (defaults to $this)
+  const action = (typeof selectorOrTarget === 'string' ? selectorOrTarget : 'update') as StyleAction;
+  const options = (typeof selectorOrTarget === 'object' ? selectorOrTarget : actionOrPropertyKey) as StyleApplyOptions | undefined;
+  return createStyleDecorator(action)('$this', options);
+}
+
+export function setStyle(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function setStyle(selector: string, options?: StyleApplyOptions): MethodDecorator;
+export function setStyle(selectorOrTarget?: any, optionsOrPropertyKey?: any, descriptor?: any): any {
+  // Bare decorator: @setStyle
+  if (descriptor !== undefined && (typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol')) {
+    return createStyleDecorator('set')('$this', {})(selectorOrTarget as Object, optionsOrPropertyKey, descriptor as PropertyDescriptor);
+  }
+  // With selector
+  if (typeof selectorOrTarget === 'string') {
+    return createStyleDecorator('set')(selectorOrTarget, optionsOrPropertyKey as StyleApplyOptions);
+  }
+  // Without selector (defaults to $this)
+  return createStyleDecorator('set')('$this', selectorOrTarget as StyleApplyOptions);
 }
 
-export const setStyle = (selector: string, options: StyleApplyOptions = {}) => createStyleDecorator('set')(selector, options);
-export const updateStyle = (selector: string, options: StyleApplyOptions = {}) => createStyleDecorator('update')(selector, options);
-export const removeStyle = (selector: string, options: StyleApplyOptions = {}) => createStyleDecorator('remove')(selector, options);
+export function updateStyle(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function updateStyle(selector: string, options?: StyleApplyOptions): MethodDecorator;
+export function updateStyle(selectorOrTarget?: any, optionsOrPropertyKey?: any, descriptor?: any): any {
+  // Bare decorator: @updateStyle
+  if (descriptor !== undefined && (typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol')) {
+    return createStyleDecorator('update')('$this', {})(selectorOrTarget as Object, optionsOrPropertyKey, descriptor as PropertyDescriptor);
+  }
+  // With selector
+  if (typeof selectorOrTarget === 'string') {
+    return createStyleDecorator('update')(selectorOrTarget, optionsOrPropertyKey as StyleApplyOptions);
+  }
+  // Without selector (defaults to $this)
+  return createStyleDecorator('update')('$this', selectorOrTarget as StyleApplyOptions);
+}
 
-// This versions
-export function applyStyleThis(action: StyleAction = 'update', options: StyleApplyOptions = {}): MethodDecorator {
-  return createStyleDecorator(action)('$this', options);
+export function removeStyle(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function removeStyle(selector: string, options?: StyleApplyOptions): MethodDecorator;
+export function removeStyle(selectorOrTarget?: any, optionsOrPropertyKey?: any, descriptor?: any): any {
+  // Bare decorator: @removeStyle
+  if (descriptor !== undefined && (typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol')) {
+    return createStyleDecorator('remove')('$this', {})(selectorOrTarget as Object, optionsOrPropertyKey, descriptor as PropertyDescriptor);
+  }
+  // With selector
+  if (typeof selectorOrTarget === 'string') {
+    return createStyleDecorator('remove')(selectorOrTarget, optionsOrPropertyKey as StyleApplyOptions);
+  }
+  // Without selector (defaults to $this)
+  return createStyleDecorator('remove')('$this', selectorOrTarget as StyleApplyOptions);
 }
-export const setStyleThis = (options: StyleApplyOptions = {}) => createStyleDecorator('set')('$this', options);
-export const updateStyleThis = (options: StyleApplyOptions = {}) => createStyleDecorator('update')('$this', options);
-export const removeStyleThis = (options: StyleApplyOptions = {}) => createStyleDecorator('remove')('$this', options);
 
 export const findAllStyleMetadata = (target: any): Map<string | symbol, StyleApplyMetadata> => {
   const result = new Map<string | symbol, StyleApplyMetadata>();

package/src/decorators/{changedAttributeThis.ts → changedAttribute.ts}

@@ -23,7 +23,7 @@ const convertValue = (val: any, type: any): any => {
 /**
  * @changedAttributeThis decorator - fires when any attribute on $this changes
  */
-export function changedAttributeThis(attributeName?: string, options: ChangedAttributeThisOptions = {}): MethodDecorator {
+export function changedAttribute(attributeName?: string, options: ChangedAttributeThisOptions = {}): MethodDecorator {
   return (target: Object, propertyKey: string | symbol) => {
     const constructor = target.constructor;
     let metaList = ReflectUtils.getOwnMetadata(ON_ATTRIBUTE_CHANGED_METADATA_KEY, constructor) as ChangedAttributeThisMetadata[];

package/src/decorators/elementDefine.ts

@@ -1,8 +1,10 @@
 import {ActionExpression, FunctionUtils, ReflectUtils} from '@dooboostore/core';
+import {Observable, Subject} from '@dooboostore/core';
+import {debounceTime, throttleTime, distinctUntilChanged} from '@dooboostore/core/message/operators';
 import {getAddEventListenerMetadata} from './addEventListener';
 import {findAllLifecycleMetadata, findAllOnConnectedAfterMetadata, findAllOnConnectedBeforeMetadata, findAllOnConnectedMetadata, ON_AFTER_ADOPTED_METADATA_KEY, ON_AFTER_DISCONNECTED_METADATA_KEY, ON_BEFORE_ADOPTED_METADATA_KEY, ON_BEFORE_DISCONNECTED_METADATA_KEY, ON_CONNECTED_COMPLETED_METADATA_KEY, ON_INITIALIZE_METADATA_KEY} from './lifecycles';
 import {getEmitCustomEventMetadataList} from './emitCustomEvent';
-import {convertAttributeValue, findAllAttributeChangedMetadata} from './changedAttributeThis';
+import {convertAttributeValue, findAllAttributeChangedMetadata} from './changedAttribute';
 import {findAllAttributeApplyMetadata, findAllAttributeMetadata, getAttributeValue} from './applyAttribute';
 import {getQueryMetadata} from './query';
 import {getQueryAllMetadata} from './queryAll';
@@ -588,8 +590,43 @@ export const elementDefine =
                 const args = {event, ...currentHostSet, $el: t, $root: t};
                 await (this as any)[meta.propertyKey](event, {currentHostSet, $$matchedElement: event.currentTarget}, args);
               };
-              t.addEventListener(type, handler, opts);
-              (this as any)._boundListeners.push({target: t, type, handler, options: opts});
+              
+              // Create event stream with Observable-based operators
+              const eventSubject = new Subject<Event>();
+              let eventStream = eventSubject as any;
+              
+              // Apply operators from @dooboostore/core/operators
+              if (options.debounceTime !== undefined && options.debounceTime > 0) {
+                eventStream = eventStream.pipe(debounceTime(options.debounceTime));
+              }
+              
+              if (options.throttleTime !== undefined && options.throttleTime > 0) {
+                eventStream = eventStream.pipe(throttleTime(options.throttleTime));
+              }
+              
+              if (options.distinctUntilChanged !== undefined && options.distinctUntilChanged !== false) {
+                if (typeof options.distinctUntilChanged === 'function') {
+                  eventStream = eventStream.pipe(distinctUntilChanged(options.distinctUntilChanged));
+                } else {
+                  eventStream = eventStream.pipe(distinctUntilChanged());
+                }
+              }
+              
+              // Subscribe to the event stream
+              const subscription = eventStream.subscribe({
+                next: (event: Event) => {
+                  handler(event).catch((err: any) => console.error('Event handler error:', err));
+                },
+                error: (err: any) => console.error('Event stream error:', err)
+              });
+              
+              // Create wrapper handler that emits to the subject
+              const wrappedHandler = (event: Event) => {
+                eventSubject.next(event);
+              };
+              
+              t.addEventListener(type, wrappedHandler, opts);
+              (this as any)._boundListeners.push({target: t, type, handler: wrappedHandler, options: opts, subscription});
             });
           });
 
@@ -640,7 +677,13 @@ export const elementDefine =
         for (const m of bMethods) (this as any)._invokeLifecycleMethod(m.propertyKey, helperHostSet);
 
         if ((this as any)._boundListeners) {
-          (this as any)._boundListeners.forEach((l: any) => l.target.removeEventListener(l.type, l.handler, l.options));
+          (this as any)._boundListeners.forEach((l: any) => {
+            l.target.removeEventListener(l.type, l.handler, l.options);
+            // Cleanup Observable subscription if present
+            if (l.subscription && typeof l.subscription.unsubscribe === 'function') {
+              l.subscription.unsubscribe();
+            }
+          });
           (this as any)._boundListeners = [];
         }
 

package/src/decorators/emitCustomEvent.ts

@@ -8,6 +8,22 @@ export interface EmitCustomEventBaseOptions {
   composed?: boolean;
   cancelable?: boolean;
   filter?: (target: EventTarget, detail: any, meta: { currentThis: any, helper: HelperHostSet }) => boolean;
+  /**
+   * Custom key to extract value from return object.
+   * If not provided, uses EMIT_CUSTOM_EVENT_METADATA_KEY by default.
+   * Useful when multiple @emitCustomEvent decorators are on the same method.
+   * 
+   * Example:
+   * @emitCustomEvent('$appHost', 'event1', { valueKey: 'detail1' })
+   * @emitCustomEvent('$appHost', 'event2', { valueKey: 'detail2' })
+   * myMethod() {
+   *   return {
+   *     detail1: { type: 'event1', data: 'value1' },
+   *     detail2: { type: 'event2', data: 'value2' }
+   *   };
+   * }
+   */
+  valueKey?: symbol | string;
 }
 
 type Options = (EmitCustomEventBaseOptions & SwcQueryOptions) | (EmitCustomEventBaseOptions & SwcQueryOptions & { attributeName?: string });
@@ -21,16 +37,43 @@ export interface EmitCustomEventMetadata {
 
 export const EMIT_CUSTOM_EVENT_METADATA_KEY = Symbol.for('simple-web-component:emit-custom-event');
 
-export function emitCustomEvent(target: SpecialSelector, type: string, options?: Options): MethodDecorator;
+export function emitCustomEvent(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function emitCustomEvent(selector: string, type: string, options?: Options): MethodDecorator;
+export function emitCustomEvent(type: string, options?: Options): MethodDecorator;
 /**
  * @emitCustomEvent decorator to dispatch custom events to a target.
+ * 
+ * Usage:
+ * - @emitCustomEvent('$this', 'event-name', options) - Emit from $this
+ * - @emitCustomEvent('$appHost', 'event-name', options) - Emit from $appHost
+ * - @emitCustomEvent('event-name', options) - Emit from $this (defaults to $this)
+ * - @emitCustomEvent('event-name') - Emit from $this with no options
  */
-export function emitCustomEvent(selectorOrTarget: string, type: string, options: any = {}): MethodDecorator {
+export function emitCustomEvent(selectorOrTarget: any, typeOrPropertyKey?: any, optionsOrDescriptor?: any): any {
+  // Case 1: Bare decorator on property
+  if (typeof selectorOrTarget === 'object' && typeof typeOrPropertyKey === 'string' && typeof optionsOrDescriptor === 'object' && 'value' in optionsOrDescriptor) {
+    throw new Error(`@emitCustomEvent decorator cannot be used on properties. (Property: ${String(typeOrPropertyKey)})`);
+  }
+
+  // Case 2: With selector and type - @emitCustomEvent('selector', 'event-name', options)
+  if (typeof selectorOrTarget === 'string' && typeof typeOrPropertyKey === 'string') {
+    return createEmitDecorator(selectorOrTarget, typeOrPropertyKey, optionsOrDescriptor as Options);
+  }
+
+  // Case 3: Without selector (type only) - @emitCustomEvent('event-name', options)
+  if (typeof selectorOrTarget === 'string' && typeOrPropertyKey !== 'string') {
+    return createEmitDecorator('$this', selectorOrTarget, typeOrPropertyKey as Options);
+  }
+
+  // Fallback
+  throw new Error('Invalid @emitCustomEvent usage');
+}
+
+function createEmitDecorator(selector: string, type: string, options?: Options) {
   return (targetObj: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
     const constructor = targetObj.constructor;
 
-    const fullOptions: any = {...options, type};
+    const fullOptions: any = {...(options || {}), type};
 
     if (fullOptions.bubbles === undefined) fullOptions.bubbles = true;
     if (fullOptions.composed === undefined) fullOptions.composed = true;
@@ -40,7 +83,7 @@ export function emitCustomEvent(selectorOrTarget: string, type: string, options:
       list = [];
       ReflectUtils.defineMetadata(EMIT_CUSTOM_EVENT_METADATA_KEY, list, constructor);
     }
-    list.push({propertyKey, selector: selectorOrTarget, type, options: fullOptions});
+    list.push({propertyKey, selector, type, options: fullOptions});
 
     const original = descriptor.value;
     descriptor.value = function (...args: any[]) {
@@ -60,27 +103,27 @@ export function emitCustomEvent(selectorOrTarget: string, type: string, options:
         const currentWin = (this as any)._resolveWindow?.(conf) || ((typeof window !== 'undefined' ? window : undefined) as Window);
 
         const eventTargets: EventTarget[] = [];
-        if (selectorOrTarget === '$window') eventTargets.push(currentWin);
-        else if (selectorOrTarget === '$document') eventTargets.push(currentWin.document);
-        else if (selectorOrTarget === '$host') {
+        if (selector === '$window') eventTargets.push(currentWin);
+        else if (selector === '$document') eventTargets.push(currentWin.document);
+        else if (selector === '$host') {
           if (hostSet.$host) eventTargets.push(hostSet.$host);
-        } else if (selectorOrTarget === '$parentHost') {
+        } else if (selector === '$parentHost') {
           if (hostSet.$parentHost) eventTargets.push(hostSet.$parentHost);
-        } else if (selectorOrTarget === '$appHost') {
+        } else if (selector === '$appHost') {
           if (hostSet.$appHost) eventTargets.push(hostSet.$appHost);
-        } else if (selectorOrTarget === '$firstHost') {
+        } else if (selector === '$firstHost') {
           if (hostSet.$firstHost) eventTargets.push(hostSet.$firstHost);
-        } else if (selectorOrTarget === '$lastHost') {
+        } else if (selector === '$lastHost') {
           if (hostSet.$lastHost) eventTargets.push(hostSet.$lastHost);
-        } else if (selectorOrTarget === '$firstAppHost') {
+        } else if (selector === '$firstAppHost') {
           if (hostSet.$firstAppHost) eventTargets.push(hostSet.$firstAppHost);
-        } else if (selectorOrTarget === '$lastAppHost') {
+        } else if (selector === '$lastAppHost') {
           if (hostSet.$lastAppHost) eventTargets.push(hostSet.$lastAppHost);
-        } else if (selectorOrTarget === '$hosts') {
+        } else if (selector === '$hosts') {
           hostSet.$hosts.forEach(h => eventTargets.push(h));
-        } else if (selectorOrTarget === '$appHosts') {
+        } else if (selector === '$appHosts') {
           hostSet.$appHosts.forEach(h => eventTargets.push(h));
-        } else if (selectorOrTarget === '$this' || !selectorOrTarget) {
+        } else if (selector === '$this' || !selector) {
           eventTargets.push(this as any);
         } else {
           const r = fullOptions.root || 'auto';
@@ -94,7 +137,7 @@ export function emitCustomEvent(selectorOrTarget: string, type: string, options:
           }
 
           searchRoots.forEach(sr => {
-            sr.querySelectorAll(selectorOrTarget).forEach(el => eventTargets.push(el));
+            sr.querySelectorAll(selector).forEach(el => eventTargets.push(el));
           });
         }
 
@@ -122,21 +165,5 @@ export const getEmitCustomEventMetadataList = (target: any): EmitCustomEventMeta
   return ReflectUtils.getMetadata(EMIT_CUSTOM_EVENT_METADATA_KEY, constructor);
 };
 
-/**
- * @emitCustomEventThis decorator - simplified version of @emitCustomEvent for $this selector
- */
-export function emitCustomEventThis(type: string, options: EmitCustomEventBaseOptions & SwcQueryOptions & { attributeName?: string }): MethodDecorator ;
-export function emitCustomEventThis(type: string, attributeName: string): MethodDecorator ;
-export function emitCustomEventThis(type: string): MethodDecorator;
-export function emitCustomEventThis(type: string, optionsOrAttributeaName?: string | (EmitCustomEventBaseOptions & SwcQueryOptions & { attributeName?: string })): MethodDecorator {
-  if (optionsOrAttributeaName && typeof optionsOrAttributeaName === 'string') {
-    return emitCustomEventThis(type, {attributeName: optionsOrAttributeaName});
-  } else if (optionsOrAttributeaName && typeof optionsOrAttributeaName === 'object') {
-    if (!optionsOrAttributeaName.attributeName) {
-      optionsOrAttributeaName.attributeName = `on-emit-${type}`;
-    }
-    return emitCustomEvent('$this', type, optionsOrAttributeaName);
-  } else {
-    return emitCustomEvent('$this', type, {attributeName: `on-emit-${type}`});
-  }
-}
+// --- Aliases: emit... ---
+export const emit = emitCustomEvent;

package/src/decorators/index.ts

@@ -1,7 +1,7 @@
 export * from './addEventListener';
 export * from './applyAttribute';
 export * from './elementDefine';
-export * from './changedAttributeThis';
+export * from './changedAttribute';
 export * from './emitCustomEvent';
 export * from './applyNode';
 export * from './lifecycles';