@dooboostore/simple-web-component 1.0.49 → 1.0.50

package/src/decorators/intersectionObserver.ts

@@ -29,110 +29,126 @@ export interface IntersectionObserverMetadata {
 
 export const INTERSECTION_OBSERVER_METADATA_KEY = Symbol.for('simple-web-component:intersection-observer');
 
+const applyIntersectionObserver = (selector: SwcSelector, options: IntersectionObserverOptions, targetObj: Object, propertyKey: string | symbol): void => {
+  const constructor = targetObj.constructor;
+  let observers = ReflectUtils.getMetadata<IntersectionObserverMetadata[]>(INTERSECTION_OBSERVER_METADATA_KEY, constructor);
+  if (!observers) {
+    observers = [];
+    ReflectUtils.defineMetadata(INTERSECTION_OBSERVER_METADATA_KEY, observers, constructor);
+  }
+  observers.push({ propertyKey, selector, options });
+};
+
+const resolveIntersectionObserverArgs = (
+  selectorOrOptions: SwcSelector | IntersectionObserverOptions | undefined,
+  maybeOptions: IntersectionObserverOptions | undefined,
+  extra: Partial<IntersectionObserverOptions>
+): { selector: SwcSelector; options: IntersectionObserverOptions } => {
+  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
+    return { selector: selectorOrOptions, options: { ...(maybeOptions ?? {}), ...extra } };
+  }
+  return { selector: '$this', options: { ...(selectorOrOptions ?? {}), ...extra } };
+};
+
+/**
+ * bare(@decorator)와 factory(@decorator()/@decorator(...)) 호출을 모두 처리하는 공통 디스패처.
+ * extra는 Light/Shadow/All/Delegate 변형이 강제로 덧씌우는 옵션(root, delegate 등)이다.
+ */
+const dispatchIntersectionObserver = (
+  selectorOrOptionsOrTarget: SwcSelector | IntersectionObserverOptions | Object | undefined,
+  maybeOptionsOrPropertyKey: IntersectionObserverOptions | string | symbol | undefined,
+  descriptor: PropertyDescriptor | undefined,
+  extra: Partial<IntersectionObserverOptions>
+): MethodDecorator | void => {
+  if ((typeof maybeOptionsOrPropertyKey === 'string' || typeof maybeOptionsOrPropertyKey === 'symbol') && descriptor !== undefined) {
+    // 옵션 없이: @decorator
+    applyIntersectionObserver('$this', { ...extra }, selectorOrOptionsOrTarget as Object, maybeOptionsOrPropertyKey);
+    return;
+  }
+  // 옵션과 함께: @decorator() / @decorator(selector, options) / @decorator(options)
+  const { selector, options } = resolveIntersectionObserverArgs(
+    selectorOrOptionsOrTarget as SwcSelector | IntersectionObserverOptions | undefined,
+    maybeOptionsOrPropertyKey as IntersectionObserverOptions | undefined,
+    extra
+  );
+  return (targetObj: Object, propertyKey: string | symbol) => {
+    applyIntersectionObserver(selector, options, targetObj, propertyKey);
+  };
+};
+
 export function intersectionObserver(target: SpecialSelector, options?: IntersectionObserverQueryOptions): MethodDecorator;
 export function intersectionObserver(selector: string, options?: IntersectionObserverQueryOptions): MethodDecorator;
 export function intersectionObserver(selector: SwcFnSelector, options?: IntersectionObserverNonQueryOptions): MethodDecorator;
 export function intersectionObserver(options?: IntersectionObserverQueryOptions): MethodDecorator;
+export function intersectionObserver(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 /**
  * @intersectionObserver decorator to observe element intersection changes.
  *
  * IntersectionObserver 는 생성 시점에 옵션(threshold/rootMargin/root)이 고정되므로,
  * 옵션별로 그룹을 만들어 observer 를 생성한다. 같은 옵션 그룹 안에서 delegate 동적 추적이 가능하다.
+ * 옵션 없이 `@intersectionObserver` 그대로 붙여도 되고, `@intersectionObserver(...)`처럼 셀렉터/옵션을 줄 수도 있다.
  */
-export function intersectionObserver(selectorOrOptions?: SwcSelector | IntersectionObserverOptions, maybeOptions?: IntersectionObserverOptions): MethodDecorator {
-  return (targetObj: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
-    let selector: SwcSelector = '$this';
-    let options: IntersectionObserverOptions = {};
-
-    if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-      selector = selectorOrOptions;
-      options = maybeOptions ?? {};
-    } else {
-      selector = '$this';
-      options = selectorOrOptions ?? {};
-    }
-
-    const constructor = targetObj.constructor;
-
-    let observers = ReflectUtils.getMetadata<IntersectionObserverMetadata[]>(INTERSECTION_OBSERVER_METADATA_KEY, constructor);
-    if (!observers) {
-      observers = [];
-      ReflectUtils.defineMetadata(INTERSECTION_OBSERVER_METADATA_KEY, observers, constructor);
-    }
-
-    observers.push({ propertyKey, selector, options });
-  };
+export function intersectionObserver(selectorOrOptionsOrTarget?: SwcSelector | IntersectionObserverOptions | Object, maybeOptionsOrPropertyKey?: IntersectionObserverOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchIntersectionObserver(selectorOrOptionsOrTarget, maybeOptionsOrPropertyKey, descriptor, {});
 }
 
-export function intersectionObserverThis(options?: IntersectionObserverQueryOptions): MethodDecorator {
-  return intersectionObserver('$this', options);
+export function intersectionObserverThis(options?: IntersectionObserverQueryOptions): MethodDecorator;
+export function intersectionObserverThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function intersectionObserverThis(optionsOrTarget?: IntersectionObserverQueryOptions | Object, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchIntersectionObserver(optionsOrTarget, propertyKey, descriptor, {});
 }
 
 // ─── root별 delegate 헬퍼 (root 주입 → 문자열 셀렉터 전용) ───
 
 export function intersectionObserverDelegateLight(selector: string, options?: Omit<IntersectionObserverQueryOptions, 'delegate'>): MethodDecorator;
 export function intersectionObserverDelegateLight(options?: Omit<IntersectionObserverQueryOptions, 'delegate'>): MethodDecorator;
-export function intersectionObserverDelegateLight(selectorOrOptions?: string | Omit<IntersectionObserverQueryOptions, 'delegate'>, maybeOptions?: Omit<IntersectionObserverQueryOptions, 'delegate'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return intersectionObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'light', delegate: true});
-  }
-  return intersectionObserver({...selectorOrOptions ?? {}, root: 'light', delegate: true});
+export function intersectionObserverDelegateLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function intersectionObserverDelegateLight(selectorOrOptionsOrTarget?: string | Omit<IntersectionObserverQueryOptions, 'delegate'> | Object, maybeOptionsOrPropertyKey?: Omit<IntersectionObserverQueryOptions, 'delegate'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchIntersectionObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'light', delegate: true });
 }
 
 export function intersectionObserverDelegateShadow(selector: string, options?: Omit<IntersectionObserverQueryOptions, 'delegate'>): MethodDecorator;
 export function intersectionObserverDelegateShadow(options?: Omit<IntersectionObserverQueryOptions, 'delegate'>): MethodDecorator;
-export function intersectionObserverDelegateShadow(selectorOrOptions?: string | Omit<IntersectionObserverQueryOptions, 'delegate'>, maybeOptions?: Omit<IntersectionObserverQueryOptions, 'delegate'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return intersectionObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'shadow', delegate: true});
-  }
-  return intersectionObserver({...selectorOrOptions ?? {}, root: 'shadow', delegate: true});
+export function intersectionObserverDelegateShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function intersectionObserverDelegateShadow(selectorOrOptionsOrTarget?: string | Omit<IntersectionObserverQueryOptions, 'delegate'> | Object, maybeOptionsOrPropertyKey?: Omit<IntersectionObserverQueryOptions, 'delegate'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchIntersectionObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'shadow', delegate: true });
 }
 
 export function intersectionObserverDelegateAll(selector: string, options?: Omit<IntersectionObserverQueryOptions, 'delegate'>): MethodDecorator;
 export function intersectionObserverDelegateAll(options?: Omit<IntersectionObserverQueryOptions, 'delegate'>): MethodDecorator;
-export function intersectionObserverDelegateAll(selectorOrOptions?: string | Omit<IntersectionObserverQueryOptions, 'delegate'>, maybeOptions?: Omit<IntersectionObserverQueryOptions, 'delegate'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return intersectionObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'all', delegate: true});
-  }
-  return intersectionObserver({...selectorOrOptions ?? {}, root: 'all', delegate: true});
+export function intersectionObserverDelegateAll(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function intersectionObserverDelegateAll(selectorOrOptionsOrTarget?: string | Omit<IntersectionObserverQueryOptions, 'delegate'> | Object, maybeOptionsOrPropertyKey?: Omit<IntersectionObserverQueryOptions, 'delegate'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchIntersectionObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'all', delegate: true });
 }
 
 export function intersectionObserverDelegate(selector: string, options?: Omit<IntersectionObserverQueryOptions, 'delegate'>): MethodDecorator;
 export function intersectionObserverDelegate(options?: Omit<IntersectionObserverQueryOptions, 'delegate'>): MethodDecorator;
-export function intersectionObserverDelegate(selectorOrOptions?: string | Omit<IntersectionObserverQueryOptions, 'delegate'>, maybeOptions?: Omit<IntersectionObserverQueryOptions, 'delegate'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return intersectionObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'auto', delegate: true});
-  }
-  return intersectionObserver({...selectorOrOptions ?? {}, root: 'auto', delegate: true});
+export function intersectionObserverDelegate(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function intersectionObserverDelegate(selectorOrOptionsOrTarget?: string | Omit<IntersectionObserverQueryOptions, 'delegate'> | Object, maybeOptionsOrPropertyKey?: Omit<IntersectionObserverQueryOptions, 'delegate'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchIntersectionObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'auto', delegate: true });
 }
 
 // ─── root별 일반 헬퍼 (delegate 없이, 셀렉터 생략 시 $this) ───
 
 export function intersectionObserverLight(selector: string, options?: IntersectionObserverQueryOptions): MethodDecorator;
 export function intersectionObserverLight(options?: IntersectionObserverQueryOptions): MethodDecorator;
-export function intersectionObserverLight(selectorOrOptions?: string | IntersectionObserverQueryOptions, maybeOptions?: IntersectionObserverQueryOptions): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return intersectionObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'light'});
-  }
-  return intersectionObserver({...selectorOrOptions ?? {}, root: 'light'});
+export function intersectionObserverLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function intersectionObserverLight(selectorOrOptionsOrTarget?: string | IntersectionObserverQueryOptions | Object, maybeOptionsOrPropertyKey?: IntersectionObserverQueryOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchIntersectionObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'light' });
 }
 
 export function intersectionObserverShadow(selector: string, options?: IntersectionObserverQueryOptions): MethodDecorator;
 export function intersectionObserverShadow(options?: IntersectionObserverQueryOptions): MethodDecorator;
-export function intersectionObserverShadow(selectorOrOptions?: string | IntersectionObserverQueryOptions, maybeOptions?: IntersectionObserverQueryOptions): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return intersectionObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'shadow'});
-  }
-  return intersectionObserver({...selectorOrOptions ?? {}, root: 'shadow'});
+export function intersectionObserverShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function intersectionObserverShadow(selectorOrOptionsOrTarget?: string | IntersectionObserverQueryOptions | Object, maybeOptionsOrPropertyKey?: IntersectionObserverQueryOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchIntersectionObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'shadow' });
 }
 
 export function intersectionObserverAll(selector: string, options?: IntersectionObserverQueryOptions): MethodDecorator;
 export function intersectionObserverAll(options?: IntersectionObserverQueryOptions): MethodDecorator;
-export function intersectionObserverAll(selectorOrOptions?: string | IntersectionObserverQueryOptions, maybeOptions?: IntersectionObserverQueryOptions): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return intersectionObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'all'});
-  }
-  return intersectionObserver({...selectorOrOptions ?? {}, root: 'all'});
+export function intersectionObserverAll(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function intersectionObserverAll(selectorOrOptionsOrTarget?: string | IntersectionObserverQueryOptions | Object, maybeOptionsOrPropertyKey?: IntersectionObserverQueryOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchIntersectionObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'all' });
 }
 
 export function getIntersectionObserverMetadata(target: any): IntersectionObserverMetadata[] | undefined {
@@ -256,4 +272,4 @@ export class IntersectionObserverLifeCycler implements ElementDefineLifeCycler {
     }
     this.removeObserverCallbacksMap.delete(inst);
   }
-}
+}

package/src/decorators/mutationObserver.ts

@@ -24,107 +24,124 @@ export interface MutationObserverMetadata {
 
 export const MUTATION_OBSERVER_METADATA_KEY = Symbol.for('simple-web-component:mutation-observer');
 
+const applyMutationObserver = (selector: SwcSelector, options: MutationObserverQueryOptions, targetObj: Object, propertyKey: string | symbol): void => {
+  const constructor = targetObj.constructor;
+  let observers = ReflectUtils.getMetadata<MutationObserverMetadata[]>(MUTATION_OBSERVER_METADATA_KEY, constructor);
+  if (!observers) {
+    observers = [];
+    ReflectUtils.defineMetadata(MUTATION_OBSERVER_METADATA_KEY, observers, constructor);
+  }
+  observers.push({ propertyKey, selector, options });
+};
+
+const resolveMutationObserverArgs = (
+  selectorOrOptions: SwcSelector | MutationObserverQueryOptions | undefined,
+  maybeOptions: MutationObserverQueryOptions | undefined,
+  extra: Partial<MutationObserverQueryOptions>
+): { selector: SwcSelector; options: MutationObserverQueryOptions } => {
+  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
+    return { selector: selectorOrOptions, options: { ...(maybeOptions ?? {}), ...extra } };
+  }
+  return { selector: '$this', options: { ...(selectorOrOptions ?? {}), ...extra } };
+};
+
+/**
+ * selectorOrOptionsOrTarget/maybeOptionsOrPropertyKey/descriptor을 받아 bare(@decorator)와
+ * factory(@decorator()/@decorator(...)) 호출을 모두 처리하는 공통 디스패처.
+ * extra는 Light/Shadow/All/Delegate 변형이 강제로 덧씌우는 옵션(root, delegate 등)이다.
+ */
+const dispatchMutationObserver = (
+  selectorOrOptionsOrTarget: SwcSelector | MutationObserverQueryOptions | Object | undefined,
+  maybeOptionsOrPropertyKey: MutationObserverQueryOptions | string | symbol | undefined,
+  descriptor: PropertyDescriptor | undefined,
+  extra: Partial<MutationObserverQueryOptions>
+): MethodDecorator | void => {
+  if ((typeof maybeOptionsOrPropertyKey === 'string' || typeof maybeOptionsOrPropertyKey === 'symbol') && descriptor !== undefined) {
+    // 옵션 없이: @decorator
+    applyMutationObserver('$this', { ...extra }, selectorOrOptionsOrTarget as Object, maybeOptionsOrPropertyKey);
+    return;
+  }
+  // 옵션과 함께: @decorator() / @decorator(selector, options) / @decorator(options)
+  const { selector, options } = resolveMutationObserverArgs(
+    selectorOrOptionsOrTarget as SwcSelector | MutationObserverQueryOptions | undefined,
+    maybeOptionsOrPropertyKey as MutationObserverQueryOptions | undefined,
+    extra
+  );
+  return (targetObj: Object, propertyKey: string | symbol) => {
+    applyMutationObserver(selector, options, targetObj, propertyKey);
+  };
+};
+
 export function mutationObserver(target: SpecialSelector, options?: MutationObserverQueryOptions): MethodDecorator;
 export function mutationObserver(selector: string, options?: MutationObserverQueryOptions): MethodDecorator;
 export function mutationObserver(selector: SwcFnSelector, options?: MutationObserverNonQueryOptions): MethodDecorator;
 export function mutationObserver(options?: MutationObserverQueryOptions): MethodDecorator;
+export function mutationObserver(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 /**
  * @mutationObserver decorator to observe DOM mutations.
+ * 옵션 없이 `@mutationObserver` 그대로 붙여도 되고, `@mutationObserver(...)`처럼 셀렉터/옵션을 줄 수도 있다.
  */
-export function mutationObserver(selectorOrOptions?: SwcSelector | MutationObserverQueryOptions, maybeOptions?: MutationObserverQueryOptions): MethodDecorator {
-  return (targetObj: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
-    let selector: SwcSelector = '$this';
-    let options: MutationObserverQueryOptions = {};
-
-    if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-      selector = selectorOrOptions;
-      options = maybeOptions ?? {};
-    } else {
-      selector = '$this';
-      options = selectorOrOptions ?? {};
-    }
-
-    const constructor = targetObj.constructor;
-
-    let observers = ReflectUtils.getMetadata<MutationObserverMetadata[]>(MUTATION_OBSERVER_METADATA_KEY, constructor);
-    if (!observers) {
-      observers = [];
-      ReflectUtils.defineMetadata(MUTATION_OBSERVER_METADATA_KEY, observers, constructor);
-    }
-
-    observers.push({ propertyKey, selector, options });
-  };
+export function mutationObserver(selectorOrOptionsOrTarget?: SwcSelector | MutationObserverQueryOptions | Object, maybeOptionsOrPropertyKey?: MutationObserverQueryOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget, maybeOptionsOrPropertyKey, descriptor, {});
 }
 
-export function mutationObserverThis<TEvent extends Event = Event>(options?: MutationObserverQueryOptions): MethodDecorator {
-  return mutationObserver('$this', options);
+export function mutationObserverThis(options?: MutationObserverQueryOptions): MethodDecorator;
+export function mutationObserverThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverThis(optionsOrTarget?: MutationObserverQueryOptions | Object, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(optionsOrTarget, propertyKey, descriptor, {});
 }
 
 // ─── root별 delegate 헬퍼 (addEventListener와 동일 패턴) ───
 
 export function mutationObserverDelegateLight(selector: string, options?: MutationObserverBaseOptions): MethodDecorator;
 export function mutationObserverDelegateLight(options?: MutationObserverBaseOptions): MethodDecorator;
-export function mutationObserverDelegateLight(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'light', delegate: true});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'light', delegate: true});
+export function mutationObserverDelegateLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverDelegateLight(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'light', delegate: true });
 }
 
 export function mutationObserverDelegateShadow(selector: string, options?: MutationObserverBaseOptions): MethodDecorator;
 export function mutationObserverDelegateShadow(options?: MutationObserverBaseOptions): MethodDecorator;
-export function mutationObserverDelegateShadow(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'shadow', delegate: true});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'shadow', delegate: true});
+export function mutationObserverDelegateShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverDelegateShadow(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'shadow', delegate: true });
 }
 
 export function mutationObserverDelegateAll(selector: string, options?: MutationObserverBaseOptions): MethodDecorator;
 export function mutationObserverDelegateAll(options?: MutationObserverBaseOptions): MethodDecorator;
-export function mutationObserverDelegateAll(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'all', delegate: true});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'all', delegate: true});
+export function mutationObserverDelegateAll(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverDelegateAll(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'all', delegate: true });
 }
 
 export function mutationObserverDelegate(selector: string, options?: MutationObserverBaseOptions): MethodDecorator;
 export function mutationObserverDelegate(options?: MutationObserverBaseOptions): MethodDecorator;
-export function mutationObserverDelegate(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'auto', delegate: true});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'auto', delegate: true});
+export function mutationObserverDelegate(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverDelegate(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'auto', delegate: true });
 }
 
 // ─── root별 일반 헬퍼 (delegate 없이, 셀렉터 생략 시 $this) ───
 
 export function mutationObserverLight(selector: string, options?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
 export function mutationObserverLight(options?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
-export function mutationObserverLight(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'light'});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'light'});
+export function mutationObserverLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverLight(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'light' });
 }
 
 export function mutationObserverShadow(selector: string, options?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
 export function mutationObserverShadow(options?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
-export function mutationObserverShadow(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'shadow'});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'shadow'});
+export function mutationObserverShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverShadow(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'shadow' });
 }
 
 export function mutationObserverAll(selector: string, options?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
 export function mutationObserverAll(options?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator;
-export function mutationObserverAll(selectorOrOptions?: string | Omit<MutationObserverQueryOptions, 'root'>, maybeOptions?: Omit<MutationObserverQueryOptions, 'root'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return mutationObserver(selectorOrOptions, {...maybeOptions ?? {}, root: 'all'});
-  }
-  return mutationObserver({...selectorOrOptions ?? {}, root: 'all'});
+export function mutationObserverAll(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function mutationObserverAll(selectorOrOptionsOrTarget?: string | Omit<MutationObserverQueryOptions, 'root'> | Object, maybeOptionsOrPropertyKey?: Omit<MutationObserverQueryOptions, 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchMutationObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'all' });
 }
 
 export function getMutationObserverMetadata(target: any): MutationObserverMetadata[] | undefined {
@@ -301,4 +318,4 @@ export class MutationObserverLifeCycler implements ElementDefineLifeCycler {
     }
     this.removeObserverCallbacksMap.delete(inst);
   }
-}
+}

package/src/decorators/parameter.ts

@@ -0,0 +1,81 @@
+import { ReflectUtils } from '@dooboostore/core';
+
+/**
+ * @eventObject/@matchedElement/@hostSet/@helperHostSet/@helperSet/@routerEvent/@appMessage —
+ * @addEventListener/lifecycle/subscribeSwcAppRouteChangeWhileConnected/subscribeSwcAppMessageWhileConnected
+ * 계열 핸들러의 파라미터를 순서 무관하게 선언할 수 있게 해주는 파라미터 데코레이터.
+ * @dooboostore/simple-boot의 @Inject와 동일한 인덱스 기반 메타데이터 패턴을 따른다:
+ * 데코레이터가 실행되는 순서가 아니라 실제 parameterIndex로 슬롯을 매칭하므로,
+ * 사용자가 파라미터 선언 순서를 자유롭게 바꿔도 된다.
+ */
+export type SwcParamKind = 'event' | 'matched' | 'hostSet' | 'helperHostSet' | 'helperSet' | 'routerEvent' | 'appMessage';
+
+const SWC_PARAMETER_METADATA_KEY = Symbol.for('simple-web-component:parameter');
+
+type SaveParamConfig = { index: number; kind: SwcParamKind };
+
+const registerParam = (kind: SwcParamKind, target: Object, propertyKey: string | symbol | undefined, parameterIndex: number) => {
+  if (!propertyKey) return;
+  const constructor = target.constructor;
+  const saves = (ReflectUtils.getOwnMetadata(SWC_PARAMETER_METADATA_KEY, constructor, propertyKey) ?? []) as SaveParamConfig[];
+  saves.push({ index: parameterIndex, kind });
+  ReflectUtils.defineMetadata(SWC_PARAMETER_METADATA_KEY, saves, constructor, propertyKey);
+};
+
+/** 이벤트 핸들러의 원본 Event 객체를 주입한다. */
+export function eventObject(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('event', target, propertyKey, parameterIndex);
+}
+
+/** delegate로 매칭된 실제 엘리먼트($matchedElement)를 주입한다. */
+export function matchedElement(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('matched', target, propertyKey, parameterIndex);
+}
+
+/** HostSet(호스트 트리 정보 — $host/$hosts/$firstHost/$appHost 등)을 주입한다. */
+export function hostSet(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('hostSet', target, propertyKey, parameterIndex);
+}
+
+/** HelperHostSet(HelperSet + HostSet + $this 전체 묶음)을 주입한다. */
+export function helperHostSet(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('helperHostSet', target, propertyKey, parameterIndex);
+}
+
+/** HelperSet($d/$w/$q/$qa/$qi 등 순수 DOM/window 헬퍼, 호스트 트리 정보 없음)을 주입한다. */
+export function helperSet(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('helperSet', target, propertyKey, parameterIndex);
+}
+
+/** @subscribeSwcAppRouteChangeWhileConnected 핸들러의 라우트 변경 이벤트({...RouterEventType, pathData})를 주입한다. */
+export function routerEvent(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('routerEvent', target, propertyKey, parameterIndex);
+}
+
+/** @subscribeSwcAppMessageWhileConnected 핸들러의 SwcAppMessage 페이로드를 주입한다. */
+export function appMessage(target: Object, propertyKey: string | symbol, parameterIndex: number): void {
+  registerParam('appMessage', target, propertyKey, parameterIndex);
+}
+
+export const getParameterMetadata = (target: any, propertyKey: string | symbol): SaveParamConfig[] => {
+  const constructor = target instanceof Function ? target : target.constructor;
+  return ReflectUtils.getMetadata(SWC_PARAMETER_METADATA_KEY, constructor, propertyKey) ?? [];
+};
+
+/**
+ * 위 파라미터 데코레이터 메타데이터가 하나라도 있으면 kind별 값을 index 순서에 맞게
+ * 배열로 조립하고, 하나도 없으면 기존 위치 인자(legacyArgs)를 그대로 반환한다 — 완전 하위호환.
+ */
+export const buildSwcParameterArgs = (
+  target: any,
+  propertyKey: string | symbol,
+  kindValues: Partial<Record<SwcParamKind, any>>,
+  legacyArgs: any[]
+): any[] => {
+  const saves = getParameterMetadata(target, propertyKey);
+  if (saves.length === 0) return legacyArgs;
+  const maxIndex = Math.max(...saves.map(s => s.index));
+  const args: any[] = new Array(maxIndex + 1);
+  for (const s of saves) args[s.index] = kindValues[s.kind];
+  return args;
+};