@dooboostore/simple-web-component 1.0.42 → 1.0.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dooboostore/simple-web-component",
-  "version": "1.0.42",
+  "version": "1.0.44",
   "license": "MIT",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -67,11 +67,7 @@
   },
   "author": "dooboostore <dooboostore@gmail.com> (https://github.com/dooboostore)",
   "peerDependencies": {
-    "reflect-metadata": "^0.2.2",
-    "@dooboostore/core": "1.0.32",
-    "@dooboostore/simple-boot": "1.0.56",
-    "@dooboostore/core-web": "1.0.12",
-    "@dooboostore/core-node": "1.0.12"
+    "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
     "@babel/core": "^7.24.0",
@@ -95,7 +91,11 @@
     "typescript": "^5.9.2",
     "webpack": "^5.93.0",
     "webpack-cli": "^5.1.4",
-    "webpack-dev-server": "^5.2.0"
+    "webpack-dev-server": "^5.2.0",
+    "@dooboostore/core": "1.0.32",
+    "@dooboostore/core-web": "1.0.12",
+    "@dooboostore/simple-boot": "1.0.56",
+    "@dooboostore/core-node": "1.0.12"
   },
   "scripts": {
     "clean": "rm -rf dist",
@@ -112,8 +112,6 @@
     "publish:npm": "pnpm run build && cp package.json package.json.back && pnpm pack && TARBALL_NAME=$(ls dooboostore-simple-web-component-*.tgz | head -n 1) && tar -xzf \"$TARBALL_NAME\" -C . --strip-components=1 package/package.json && rm \"$TARBALL_NAME\" && (pnpm publish --no-git-checks || true) && cp package.json.back package.json && rm -rf package.json.back  ",
     "ts:clean": "find . -name '*.js' -o -name '*.map' -o -name '*.d.ts' | xargs rm -f",
     "typecheck": "pnpm exec tsc --noEmit",
-    "generate:is": "tsx generate-is.ts",
-    "generate:is:watch": "node --import tsx --watch --watch-path=./src/elements/SwcIf.ts --watch-path=./src/elements/SwcLoop.ts --watch-path=./src/elements/SwcChoose.ts --watch-path=./src/elements/SwcAsync.ts --watch-path=./src/elements/SwcAppMixin.ts --watch-path=./generate-is.ts generate-is.ts",
     "test": "echo test",
     "test:bundle": "pnpm --filter @dooboostore/simple-web-component-bundle-test dev"
   }

package/src/SwcAppEngine.ts

@@ -78,7 +78,9 @@ export class SwcAppEngine {
 
       if (this._config.onStartedLazyDefineComponent) {
         // console.log('-------->', this._config.onStartedLazyDefineComponent)
-        await Promise.all(this._config.onStartedLazyDefineComponent.map(it => it(this._config.window)))
+        await Promise.all(this._config.onStartedLazyDefineComponent.map(it => {
+          it(this._config.window);
+        }))
       }
       if (this._config.onEngineStarted) {
         await this._config.onEngineStarted(this.simpleApplication, this.host as unknown as SwcAppInterface);

package/src/decorators/addEventListener.ts

@@ -1,7 +1,7 @@
 import { ReflectUtils } from '@dooboostore/core';
 import { SpecialSelector, SwcQueryOptions, HelperHostSet } from '../types';
 
-export interface AddEventListenerBaseOptions extends EventListenerOptions {
+export interface AddEventListenerBaseOptions<TEvent extends Event = Event> extends EventListenerOptions {
   capture?: boolean;
   once?: boolean;
   passive?: boolean;
@@ -11,27 +11,31 @@ export interface AddEventListenerBaseOptions extends EventListenerOptions {
   // removeOnDisconnected?: boolean;
   delegate?: boolean;
   filter?: (target: Event | CustomEvent, meta:{currentThis: any, helper: HelperHostSet}) => boolean;
+  // RxJS operator options
+  debounceTime?: number;
+  throttleTime?: number;
+  distinctUntilChanged?: boolean | ((prev: TEvent, curr: TEvent) => boolean);
 }
 
-export interface AddEventListenerMetadata {
+export interface AddEventListenerMetadata<TEvent extends Event = Event> {
   propertyKey: string | symbol;
   selector: string;
   type: string;
-  options: AddEventListenerBaseOptions & SwcQueryOptions & { delegate?: boolean };
+  options: AddEventListenerBaseOptions<TEvent> & SwcQueryOptions & { delegate?: boolean };
 }
 
 export const ADD_EVENT_LISTENER_METADATA_KEY = Symbol.for('simple-web-component:add-event-listener');
 
-export function addEventListener(target: SpecialSelector, type: string, options?: AddEventListenerBaseOptions): MethodDecorator;
-export function addEventListener(selector: string, type: string, options?: AddEventListenerBaseOptions & SwcQueryOptions & { delegate?: boolean }): MethodDecorator;
+export function addEventListener<TEvent extends Event = Event>(target: SpecialSelector, type: string, options?: AddEventListenerBaseOptions<TEvent>): MethodDecorator;
+export function addEventListener<TEvent extends Event = Event>(selector: string, type: string, options?: AddEventListenerBaseOptions<TEvent> & SwcQueryOptions & { delegate?: boolean }): MethodDecorator;
 /**
  * @addEventListener decorator to bind events to elements.
  */
-export function addEventListener(selectorOrTarget: string, type: string, options: any = {}): MethodDecorator {
+export function addEventListener<TEvent extends Event = Event>(selectorOrTarget: string, type: string, options: any = {}): MethodDecorator {
   return (targetObj: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
     const constructor = targetObj.constructor;
 
-    let listeners = ReflectUtils.getMetadata<AddEventListenerMetadata[]>(ADD_EVENT_LISTENER_METADATA_KEY, constructor);
+    let listeners = ReflectUtils.getMetadata<AddEventListenerMetadata<TEvent>[]>(ADD_EVENT_LISTENER_METADATA_KEY, constructor);
     if (!listeners) {
       listeners = [];
       ReflectUtils.defineMetadata(ADD_EVENT_LISTENER_METADATA_KEY, listeners, constructor);
@@ -42,42 +46,49 @@ export function addEventListener(selectorOrTarget: string, type: string, options
 }
 
 
-export function addEventListenerDelegateLightDom(selector: string, type: string, options?: Omit<AddEventListenerBaseOptions, 'delegate'>): MethodDecorator {
-  return addEventListener(selector, type, {...options??{}, root:'light', delegate: true});
+export function addEventListenerDelegateLightDom<TEvent extends Event = Event>(selector: string, type: string, options?: Omit<AddEventListenerBaseOptions<TEvent>, 'delegate'>): MethodDecorator {
+  return addEventListener<TEvent>(selector, type, {...options??{}, root:'light', delegate: true});
 }
 
-export function addEventListenerDelegateShadowDom(selector: string, type: string, options?: Omit<AddEventListenerBaseOptions, 'delegate'>): MethodDecorator {
-  return addEventListener(selector, type, {...options??{}, root:'shadow', delegate: true});
+export function addEventListenerDelegateShadowDom<TEvent extends Event = Event>(selector: string, type: string, options?: Omit<AddEventListenerBaseOptions<TEvent>, 'delegate'>): MethodDecorator {
+  return addEventListener<TEvent>(selector, type, {...options??{}, root:'shadow', delegate: true});
 }
-export function addEventListenerDelegateAllDom(selector: string, type: string, options?: Omit<AddEventListenerBaseOptions, 'delegate'>): MethodDecorator {
-  return addEventListener(selector, type, {...options??{}, root:'all', delegate: true});
+export function addEventListenerDelegateAllDom<TEvent extends Event = Event>(selector: string, type: string, options?: Omit<AddEventListenerBaseOptions<TEvent>, 'delegate'>): MethodDecorator {
+  return addEventListener<TEvent>(selector, type, {...options??{}, root:'all', delegate: true});
 }
-export function addEventListenerDelegate(selector: string, type: string, options?: Omit<AddEventListenerBaseOptions, 'delegate'>): MethodDecorator {
-  return addEventListener(selector, type, {...options??{}, root:'auto', delegate: true});
+export function addEventListenerDelegate<TEvent extends Event = Event>(selector: string, type: string, options?: Omit<AddEventListenerBaseOptions<TEvent>, 'delegate'>): MethodDecorator {
+  return addEventListener<TEvent>(selector, type, {...options??{}, root:'auto', delegate: true});
 }
 
 /**
  * @addEventListenerThis decorator - simplified version of @addEventListener for $this selector
  */
-export function addEventListenerThis(type: string, options?: AddEventListenerBaseOptions & SwcQueryOptions): MethodDecorator {
-  return addEventListener('$this', type, options);
+
+// --- Aliases: event... ---
+export const event = addEventListener;
+export const eventDelegateLightDom = addEventListenerDelegateLightDom;
+export const eventDelegateShadowDom = addEventListenerDelegateShadowDom;
+export const eventDelegateAllDom = addEventListenerDelegateAllDom;
+export const eventDelegate = addEventListenerDelegate;
+export function addEventListenerThis<TEvent extends Event = Event>(type: string, options?: AddEventListenerBaseOptions<TEvent> & SwcQueryOptions): MethodDecorator {
+  return addEventListener<TEvent>('$this', type, options);
 }
 
 /**
  * @addEventListenerAppHost decorator - simplified version of @addEventListener for $appHost selector
  */
-export function addEventListenerAppHost(type: string, options?: AddEventListenerBaseOptions & SwcQueryOptions): MethodDecorator {
-  return addEventListener('$appHost', type, options);
+export function addEventListenerAppHost<TEvent extends Event = Event>(type: string, options?: AddEventListenerBaseOptions<TEvent> & SwcQueryOptions): MethodDecorator {
+  return addEventListener<TEvent>('$appHost', type, options);
 }
 
-export function addEventListenerWindow(type: string, options?: AddEventListenerBaseOptions & SwcQueryOptions): MethodDecorator {
-  return addEventListener('$window', type, options);
+export function addEventListenerWindow<TEvent extends Event = Event>(type: string, options?: AddEventListenerBaseOptions<TEvent> & SwcQueryOptions): MethodDecorator {
+  return addEventListener<TEvent>('$window', type, options);
 }
-export function addEventListenerDocument(type: string, options?: AddEventListenerBaseOptions & SwcQueryOptions): MethodDecorator {
-  return addEventListener('$document', type, options);
+export function addEventListenerDocument<TEvent extends Event = Event>(type: string, options?: AddEventListenerBaseOptions<TEvent> & SwcQueryOptions): MethodDecorator {
+  return addEventListener<TEvent>('$document', type, options);
 }
 
-export const getAddEventListenerMetadata = (target: any): AddEventListenerMetadata[] | undefined => {
+export const getAddEventListenerMetadata = (target: any): AddEventListenerMetadata<Event>[] | undefined => {
   const constructor = target instanceof Function ? target : target.constructor;
   return ReflectUtils.getMetadata(ADD_EVENT_LISTENER_METADATA_KEY, constructor);
 };

package/src/decorators/applyAttribute.ts

@@ -12,6 +12,32 @@ export interface AttributeOptions extends SwcQueryOptions {
   name?: string;
   type?: typeof Number | typeof Boolean | typeof String;
   filter?: (target: HTMLElement, value: any, meta: { currentThis: any, helper: HelperHostSet }) => boolean;
+  /**
+   * Custom key to extract value from return object.
+   * If not provided, uses ATTRIBUTE_METADATA_KEY by default.
+   * Useful when multiple @setAttribute decorators are on the same method.
+   * 
+   * Example:
+   * @setAttribute('selector1', { valueKey: 'attr1' })
+   * @setAttribute('selector2', { valueKey: 'attr2' })
+   * myMethod() {
+   *   return {
+   *     attr1: 'value1',
+   *     attr2: 'value2'
+   *   };
+   * }
+   * 
+   * Or with symbols:
+   * @setAttribute('selector1', { valueKey: Symbol.for('attr1') })
+   * @setAttribute('selector2', { valueKey: Symbol.for('attr2') })
+   * myMethod() {
+   *   return {
+   *     [Symbol.for('attr1')]: 'value1',
+   *     [Symbol.for('attr2')]: 'value2'
+   *   };
+   * }
+   */
+  valueKey?: symbol | string;
 }
 
 export interface AttributeMetadata {
@@ -28,6 +54,36 @@ export const ATTRIBUTE_METADATA_KEY = Symbol.for('simple-web-component:attribute
 // Utilities
 // ============================================
 
+/**
+ * Determine if a string is a CSS selector or an attribute name
+ * 
+ * CSS selectors typically:
+ * - Start with: #, ., [, :, >, +, ~
+ * - Contain special chars: >, +, ~, :, [, ]
+ * - Are special keywords: $this, $host, $parentHost, etc.
+ * 
+ * Attribute names are typically:
+ * - kebab-case (lowercase with hyphens)
+ * - No special selector syntax
+ * 
+ * @param str - String to check
+ * @returns true if it's a CSS selector, false if it's an attribute name
+ */
+const isCssSelector = (str: string): boolean => {
+  if (!str) return false;
+  
+  // Special keywords
+  if (str.startsWith('$')) return true;
+  
+  // CSS selector syntax
+  if (/^[#.\[\:>+~]/.test(str)) return true;
+  
+  // Contains CSS combinator or pseudo-selector syntax
+  if (/[>+~:\[\]]/.test(str)) return true;
+  
+  return false;
+};
+
 const convertValue = (val: string | null, type: any): any => {
   if (val === null || val === undefined) return val;
   if (type === Number) return Number(val);
@@ -210,13 +266,43 @@ export function applyAttribute(selector: string, targetAttributeNameOrOptions?:
         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 ATTRIBUTE_METADATA_KEY.
+         * 
+         * Example:
+         * @setAttribute('selector1', { valueKey: 'attr1' })
+         * @setAttribute('selector2', { valueKey: 'attr2' })
+         * myMethod() {
+         *   return {
+         *     attr1: 'attribute-value1',
+         *     attr2: 'attribute-value2'
+         *   };
+         * }
+         * 
+         * First decorator will use 'attribute-value1', second will use 'attribute-value2'
+         */
+        const extractValue = (v: any) => {
+          const keyToUse = finalOptions.valueKey ?? ATTRIBUTE_METADATA_KEY;
+          if (v && typeof v === 'object' && keyToUse in v) {
+            return v[keyToUse];
+          }
+          return v;
+        };
+
         if (res instanceof Promise) {
           return res.then((v: any) => {
-            applyValueToTargets(this, v);
+            const extracted = extractValue(v);
+            applyValueToTargets(this, extracted);
             return v;
           });
         } else {
-          applyValueToTargets(this, res);
+          const extracted = extractValue(res);
+          applyValueToTargets(this, extracted);
           return res;
         }
       };
@@ -251,77 +337,93 @@ export function applyAttribute(selector: string, targetAttributeNameOrOptions?:
 // ============================================
 
 /**
- * @attribute - Alias for @applyAttribute
+ * @attribute - Field decorator for binding element attributes (read/write)
+ * 
+ * Intelligently distinguishes between attribute names and CSS selectors:
+ * 
+ * Usage patterns:
+ * - @attribute('product-id') - Attribute name on $this (auto-detected)
+ * - @attribute('#user', 'product-id') - Attribute name on selector
+ * - @attribute('product-id', options) - Attribute name on $this with options
+ * - @attribute('#user', 'product-id', options) - Attribute name on selector with options
+ * - @attribute - Bare decorator (uses property name as attribute on $this)
+ * 
+ * Note: This decorator is for FIELDS ONLY. For methods, use @setAttribute.
  */
-export function attribute(selector: string, targetAttributeName: string, options?: AttributeOptions): MethodDecorator & PropertyDecorator;
-export function attribute(selector: string, options?: AttributeOptions): MethodDecorator & PropertyDecorator;
-export function attribute(selector: string, targetAttributeNameOrOptions?: string | AttributeOptions, options?: AttributeOptions): MethodDecorator & PropertyDecorator {
-  return applyAttribute(selector, targetAttributeNameOrOptions as any, options);
-}
-
-/**
- * @attributeThis - Apply attribute on $this element
- * Can be used as: @attributeThis or @attributeThis('attrName') or @attributeThis({ name: 'attrName' })
- */
-export function attributeThis(target: Object, propertyKey: string | symbol): void;
-export function attributeThis(targetAttributeName: string, options?: AttributeOptions): MethodDecorator & PropertyDecorator;
-export function attributeThis(options?: AttributeOptions): MethodDecorator & PropertyDecorator;
-export function attributeThis(targetOrOptions?: any, propertyKeyOrOptions?: any, descriptor?: PropertyDescriptor): any {
-  // Direct decorator usage: @attributeThis
-  if (typeof targetOrOptions === 'object' && targetOrOptions !== null && !Array.isArray(targetOrOptions) &&
-    typeof propertyKeyOrOptions === 'string' || typeof propertyKeyOrOptions === 'symbol') {
-    // Called as @attributeThis (target, propertyKey)
-    return applyAttribute('$this', undefined as any, {})(targetOrOptions, propertyKeyOrOptions, descriptor);
+export function attribute(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function attribute(attributeName: string, options?: AttributeOptions): PropertyDecorator;
+export function attribute(selector: string, attributeName: string, options?: AttributeOptions): PropertyDecorator;
+export function attribute(selectorOrAttributeOrTarget?: string | Object, attributeNameOrOptions?: any, optionsOrDescriptor?: any): any {
+  // Bare decorator: @attribute
+  if (optionsOrDescriptor !== undefined && (typeof attributeNameOrOptions === 'string' || typeof attributeNameOrOptions === 'symbol')) {
+    return applyAttribute('$this', undefined as any, {})(selectorOrAttributeOrTarget as Object, attributeNameOrOptions, optionsOrDescriptor as PropertyDescriptor);
   }
-
-  // Called with parameters
-  if (typeof targetOrOptions === 'string') {
-    // @attributeThis('attrName', options?)
-    return applyAttribute('$this', targetOrOptions, propertyKeyOrOptions);
-  } else if (targetOrOptions && typeof targetOrOptions === 'object') {
-    // @attributeThis({ name: 'attrName' })
-    return applyAttribute('$this', undefined as any, targetOrOptions);
-  } else {
-    // @attributeThis() or @attributeThis
-    return applyAttribute('$this', undefined as any, {});
+  
+  // With string as first parameter
+  if (typeof selectorOrAttributeOrTarget === 'string') {
+    // Check if first parameter is a CSS selector or attribute name
+    const isSelector = isCssSelector(selectorOrAttributeOrTarget);
+    
+    if (isSelector) {
+      // First param is a selector: @attribute('#user', 'product-id', options?)
+      return applyAttribute(selectorOrAttributeOrTarget, attributeNameOrOptions as any, optionsOrDescriptor as AttributeOptions);
+    } else {
+      // First param is an attribute name: @attribute('product-id', options?)
+      // Treat as attribute name on $this
+      const options = (typeof attributeNameOrOptions === 'object' && attributeNameOrOptions !== null) 
+        ? attributeNameOrOptions 
+        : {};
+      return applyAttribute('$this', selectorOrAttributeOrTarget, options);
+    }
   }
+  
+  // Without selector (defaults to $this with options)
+  return applyAttribute('$this', undefined as any, selectorOrAttributeOrTarget as AttributeOptions);
 }
 
 /**
- * @setAttribute - Alias for @applyAttribute (method-decorator semantics)
- */
-export function setAttribute(selector: string, targetAttributeName: string, options?: AttributeOptions): MethodDecorator;
-export function setAttribute(selector: string, options?: AttributeOptions): MethodDecorator;
-export function setAttribute(selector: string, targetAttributeNameOrOptions?: string | AttributeOptions, options?: AttributeOptions): MethodDecorator {
-  return applyAttribute(selector, targetAttributeNameOrOptions as any, options) as MethodDecorator;
-}
-
-/**
- * @setAttributeThis - Set attribute on $this element
- * Can be used as: @setAttributeThis or @setAttributeThis('attrName') or @setAttributeThis({ name: 'attrName' })
+ * @setAttribute - Method decorator for setting element attributes from method return value
+ * 
+ * Intelligently distinguishes between attribute names and CSS selectors:
+ * 
+ * Usage patterns:
+ * - @setAttribute('data-id') - Attribute name on $this (auto-detected)
+ * - @setAttribute('#user', 'data-id') - Attribute name on selector
+ * - @setAttribute('data-id', options) - Attribute name on $this with options
+ * - @setAttribute('#user', 'data-id', options) - Attribute name on selector with options
+ * - @setAttribute - Bare decorator (uses method name as attribute on $this)
+ * 
+ * Note: This decorator is for METHODS ONLY. For fields, use @attribute.
+ * 
+ * Example:
+ * @setAttribute('data-status')
+ * updateStatus() {
+ *   return 'active';
+ * }
  */
-export function setAttributeThis(target: Object, propertyKey: string | symbol): void;
-export function setAttributeThis(targetAttributeName: string, options?: AttributeOptions): MethodDecorator;
-export function setAttributeThis(options?: AttributeOptions): MethodDecorator;
-export function setAttributeThis(targetOrOptions?: any, propertyKeyOrOptions?: any, descriptor?: PropertyDescriptor): any {
-  // Direct decorator usage: @setAttributeThis
-  if (typeof targetOrOptions === 'object' && targetOrOptions !== null && !Array.isArray(targetOrOptions) &&
-    (typeof propertyKeyOrOptions === 'string' || typeof propertyKeyOrOptions === 'symbol')) {
-    // Called as @setAttributeThis (target, propertyKey)
-    return applyAttribute('$this', undefined as any, {})(targetOrOptions, propertyKeyOrOptions, descriptor);
-  }
-
-  // Called with parameters
-  if (typeof targetOrOptions === 'string') {
-    // @setAttributeThis('attrName', options?)
-    return applyAttribute('$this', targetOrOptions, propertyKeyOrOptions) as MethodDecorator;
-  } else if (targetOrOptions && typeof targetOrOptions === 'object') {
-    // @setAttributeThis({ name: 'attrName' })
-    return applyAttribute('$this', undefined as any, targetOrOptions) as MethodDecorator;
-  } else {
-    // @setAttributeThis() or @setAttributeThis
-    return applyAttribute('$this', undefined as any, {}) as MethodDecorator;
+export function setAttribute(selector: string, attributeName: string, options?: AttributeOptions): MethodDecorator;
+export function setAttribute(attributeName: string, options?: AttributeOptions): MethodDecorator;
+export function setAttribute(selectorOrAttributeOrOptions?: string | AttributeOptions, attributeNameOrOptions?: any, optionsOrUndefined?: AttributeOptions): MethodDecorator {
+  // With string as first parameter
+  if (typeof selectorOrAttributeOrOptions === 'string') {
+    // Check if first parameter is a CSS selector or attribute name
+    const isSelector = isCssSelector(selectorOrAttributeOrOptions);
+    
+    if (isSelector) {
+      // First param is a selector: @setAttribute('#user', 'data-id', options?)
+      return applyAttribute(selectorOrAttributeOrOptions, attributeNameOrOptions as any, optionsOrUndefined as AttributeOptions) as MethodDecorator;
+    } else {
+      // First param is an attribute name: @setAttribute('data-id', options?)
+      // Treat as attribute name on $this
+      const options = (typeof attributeNameOrOptions === 'object' && attributeNameOrOptions !== null) 
+        ? attributeNameOrOptions 
+        : {};
+      return applyAttribute('$this', selectorOrAttributeOrOptions, options) as MethodDecorator;
+    }
   }
+  
+  // Without selector (defaults to $this with options)
+  return applyAttribute('$this', undefined as any, selectorOrAttributeOrOptions as AttributeOptions) as MethodDecorator;
 }
 
 // ============================================

package/src/decorators/applyClass.ts

@@ -9,6 +9,12 @@ export type ClassAction = 'set' | 'update' | 'add' | 'remove' | 'toggle';
 
 export interface ClassApplyOptions 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 CLASS_METADATA_KEY by default.
+   * Useful when multiple @applyClass decorators are on the same method.
+   */
+  valueKey?: symbol | string;
 }
 
 export interface ClassApplyMetadata {
@@ -44,6 +50,22 @@ function createClassDecorator(action: ClassAction) {
         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 CLASS_METADATA_KEY.
+         */
+        const extractValue = (v: any) => {
+          const keyToUse = finalOptions.valueKey ?? CLASS_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;
@@ -131,9 +153,9 @@ function createClassDecorator(action: ClassAction) {
         };
 
         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;
@@ -141,25 +163,99 @@ function createClassDecorator(action: ClassAction) {
   };
 }
 
-export function applyClass(selector: string, action: ClassAction = 'update', options: ClassApplyOptions = {}): MethodDecorator {
-  return createClassDecorator(action)(selector, options);
+export function applyClass(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function applyClass(selector: string, action?: ClassAction, options?: ClassApplyOptions): MethodDecorator;
+export function applyClass(selectorOrTarget?: any, actionOrPropertyKey?: any, optionsOrDescriptor?: any): any {
+  // Bare decorator: @applyClass
+  if (optionsOrDescriptor !== undefined && (typeof actionOrPropertyKey === 'string' || typeof actionOrPropertyKey === 'symbol')) {
+    return createClassDecorator('update')('$this', {})(selectorOrTarget as Object, actionOrPropertyKey, optionsOrDescriptor as PropertyDescriptor);
+  }
+  // With selector
+  if (typeof selectorOrTarget === 'string') {
+    const action = (typeof actionOrPropertyKey === 'string' ? actionOrPropertyKey : 'update') as ClassAction;
+    const options = (typeof actionOrPropertyKey === 'object' ? actionOrPropertyKey : optionsOrDescriptor) as ClassApplyOptions | undefined;
+    return createClassDecorator(action)(selectorOrTarget, options);
+  }
+  // Without selector (defaults to $this)
+  const action = (typeof selectorOrTarget === 'string' ? selectorOrTarget : 'update') as ClassAction;
+  const options = (typeof selectorOrTarget === 'object' ? selectorOrTarget : actionOrPropertyKey) as ClassApplyOptions | undefined;
+  return createClassDecorator(action)('$this', options);
 }
 
-export const setClass = (selector: string, classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options: ClassApplyOptions = {}) => createClassDecorator('set')(selector, classMapOrOptions, options);
-export const updateClass = (selector: string, classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options: ClassApplyOptions = {}) => createClassDecorator('update')(selector, classMapOrOptions, options);
-export const addClass = (selector: string, classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options: ClassApplyOptions = {}) => createClassDecorator('add')(selector, classMapOrOptions, options);
-export const removeClass = (selector: string, classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options: ClassApplyOptions = {}) => createClassDecorator('remove')(selector, classMapOrOptions, options);
-export const toggleClass = (selector: string, classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options: ClassApplyOptions = {}) => createClassDecorator('toggle')(selector, classMapOrOptions, options);
+export function setClass(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function setClass(selector: string, classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options?: ClassApplyOptions): MethodDecorator;
+export function setClass(selectorOrTarget?: any, classMapOrOptionsOrPropertyKey?: any, optionsOrDescriptor?: any): any {
+  // Bare decorator: @setClass
+  if (optionsOrDescriptor !== undefined && (typeof classMapOrOptionsOrPropertyKey === 'string' || typeof classMapOrOptionsOrPropertyKey === 'symbol')) {
+    return createClassDecorator('set')('$this', {})(selectorOrTarget as Object, classMapOrOptionsOrPropertyKey, optionsOrDescriptor as PropertyDescriptor);
+  }
+  // With selector
+  if (typeof selectorOrTarget === 'string') {
+    return createClassDecorator('set')(selectorOrTarget, classMapOrOptionsOrPropertyKey, optionsOrDescriptor as ClassApplyOptions);
+  }
+  // Without selector (defaults to $this)
+  return createClassDecorator('set')('$this', selectorOrTarget as ClassApplyOptions);
+}
 
-// This versions
-export function applyClassThis(action: ClassAction = 'update', options: ClassApplyOptions = {}): MethodDecorator {
-  return createClassDecorator(action)('$this', options);
+export function updateClass(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function updateClass(selector: string, classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options?: ClassApplyOptions): MethodDecorator;
+export function updateClass(selectorOrTarget?: any, classMapOrOptionsOrPropertyKey?: any, optionsOrDescriptor?: any): any {
+  // Bare decorator: @updateClass
+  if (optionsOrDescriptor !== undefined && (typeof classMapOrOptionsOrPropertyKey === 'string' || typeof classMapOrOptionsOrPropertyKey === 'symbol')) {
+    return createClassDecorator('update')('$this', {})(selectorOrTarget as Object, classMapOrOptionsOrPropertyKey, optionsOrDescriptor as PropertyDescriptor);
+  }
+  // With selector
+  if (typeof selectorOrTarget === 'string') {
+    return createClassDecorator('update')(selectorOrTarget, classMapOrOptionsOrPropertyKey, optionsOrDescriptor as ClassApplyOptions);
+  }
+  // Without selector (defaults to $this)
+  return createClassDecorator('update')('$this', selectorOrTarget as ClassApplyOptions);
+}
+
+export function addClass(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function addClass(selector: string, classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options?: ClassApplyOptions): MethodDecorator;
+export function addClass(selectorOrTarget?: any, classMapOrOptionsOrPropertyKey?: any, optionsOrDescriptor?: any): any {
+  // Bare decorator: @addClass
+  if (optionsOrDescriptor !== undefined && (typeof classMapOrOptionsOrPropertyKey === 'string' || typeof classMapOrOptionsOrPropertyKey === 'symbol')) {
+    return createClassDecorator('add')('$this', {})(selectorOrTarget as Object, classMapOrOptionsOrPropertyKey, optionsOrDescriptor as PropertyDescriptor);
+  }
+  // With selector
+  if (typeof selectorOrTarget === 'string') {
+    return createClassDecorator('add')(selectorOrTarget, classMapOrOptionsOrPropertyKey, optionsOrDescriptor as ClassApplyOptions);
+  }
+  // Without selector (defaults to $this)
+  return createClassDecorator('add')('$this', selectorOrTarget as ClassApplyOptions);
+}
+
+export function removeClass(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function removeClass(selector: string, classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options?: ClassApplyOptions): MethodDecorator;
+export function removeClass(selectorOrTarget?: any, classMapOrOptionsOrPropertyKey?: any, optionsOrDescriptor?: any): any {
+  // Bare decorator: @removeClass
+  if (optionsOrDescriptor !== undefined && (typeof classMapOrOptionsOrPropertyKey === 'string' || typeof classMapOrOptionsOrPropertyKey === 'symbol')) {
+    return createClassDecorator('remove')('$this', {})(selectorOrTarget as Object, classMapOrOptionsOrPropertyKey, optionsOrDescriptor as PropertyDescriptor);
+  }
+  // With selector
+  if (typeof selectorOrTarget === 'string') {
+    return createClassDecorator('remove')(selectorOrTarget, classMapOrOptionsOrPropertyKey, optionsOrDescriptor as ClassApplyOptions);
+  }
+  // Without selector (defaults to $this)
+  return createClassDecorator('remove')('$this', selectorOrTarget as ClassApplyOptions);
+}
+
+export function toggleClass(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function toggleClass(selector: string, classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options?: ClassApplyOptions): MethodDecorator;
+export function toggleClass(selectorOrTarget?: any, classMapOrOptionsOrPropertyKey?: any, optionsOrDescriptor?: any): any {
+  // Bare decorator: @toggleClass
+  if (optionsOrDescriptor !== undefined && (typeof classMapOrOptionsOrPropertyKey === 'string' || typeof classMapOrOptionsOrPropertyKey === 'symbol')) {
+    return createClassDecorator('toggle')('$this', {})(selectorOrTarget as Object, classMapOrOptionsOrPropertyKey, optionsOrDescriptor as PropertyDescriptor);
+  }
+  // With selector
+  if (typeof selectorOrTarget === 'string') {
+    return createClassDecorator('toggle')(selectorOrTarget, classMapOrOptionsOrPropertyKey, optionsOrDescriptor as ClassApplyOptions);
+  }
+  // Without selector (defaults to $this)
+  return createClassDecorator('toggle')('$this', selectorOrTarget as ClassApplyOptions);
 }
-export const setClassThis = (classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options: ClassApplyOptions = {}) => createClassDecorator('set')('$this', classMapOrOptions, options);
-export const updateClassThis = (classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options: ClassApplyOptions = {}) => createClassDecorator('update')('$this', classMapOrOptions, options);
-export const addClassThis = (classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options: ClassApplyOptions = {}) => createClassDecorator('add')('$this', classMapOrOptions, options);
-export const removeClassThis = (classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options: ClassApplyOptions = {}) => createClassDecorator('remove')('$this', classMapOrOptions, options);
-export const toggleClassThis = (classMapOrOptions?: string | { [className: string]: (el: HTMLElement, value: any, helper: HelperHostSet & { $this: any }) => boolean } | ClassApplyOptions, options: ClassApplyOptions = {}) => createClassDecorator('toggle')('$this', classMapOrOptions, options);
 
 export const findAllClassMetadata = (target: any): Map<string | symbol, ClassApplyMetadata> => {
   const result = new Map<string | symbol, ClassApplyMetadata>();