@dooboostore/simple-web-component 1.0.49 → 1.0.50

package/src/decorators/requestAnimationFrame.ts

@@ -0,0 +1,158 @@
+import { ReflectUtils } from '@dooboostore/core';
+import { ensureInit, getElementConfig } from './elementDefine';
+import { SwcUtils } from '../utils/Utils';
+import { ElementDefineLifeCycler, HelperHostSet } from '../types';
+
+export const REQUEST_ANIMATION_FRAME_METADATA_KEY = Symbol.for('simple-web-component:request-animation-frame');
+
+export type RequestAnimationFrameType = 'onConnected' | 'returnValue';
+
+export interface RequestAnimationFrameOptions {
+  /**
+   * 'onConnected' - connect 시 자동으로 루프 시작 (매 프레임 데코레이트된 메서드를 직접 호출), disconnect 시 자동 정리.
+   * 'returnValue'(기본값) - 자동 시작 없음. 개발자가 이 메서드를 직접 호출해야 시작되고,
+   *   그 호출의 리턴값(또는 valueKey로 뽑은 값)이 실제로 매 프레임 호출될 함수가 된다.
+   */
+  type?: RequestAnimationFrameType;
+  /** 루프 시작 직후 1회 호출 (디버깅/로깅용). id는 첫 requestAnimationFrame 반환값 - cleanup은 자동으로 처리되므로 직접 취소할 필요 없음. */
+  created?: (set: HelperHostSet, id: number) => void;
+  /**
+   * type:'returnValue' 전용 - 리턴값이 함수면 그 자체를, 객체면 이 키의 값이 함수일 때 그 값을
+   * "매 프레임 호출될 함수"로 사용한다. 안 주면 REQUEST_ANIMATION_FRAME_METADATA_KEY로 폴백한다 -
+   * applyAttribute.ts/applyNode.ts의 valueKey와 동일한 컨벤션.
+   */
+  valueKey?: symbol | string;
+}
+
+export interface RequestAnimationFrameMetadata {
+  propertyKey: string | symbol;
+  options: RequestAnimationFrameOptions;
+}
+
+/**
+ * 프레임 콜백 시그니처.
+ * - timestamp: 이번 프레임의 시각 (requestAnimationFrame이 넘겨주는 값)
+ * - prevValue: 직전 호출이 리턴한 값 (첫 호출에서는 undefined)
+ * 리턴값이 undefined/null이면 다음 프레임을 예약하지 않고 루프가 멈춘다 (개발자가 종료를 제어).
+ * undefined/null이 아닌 값을 리턴하면 그 값 그대로 다음 호출의 prevValue로 전달된다.
+ */
+export type FrameCallback = (timestamp: number, prevValue?: any) => any;
+
+const activeMap = new WeakMap<any, number[]>();
+const getActiveEntries = (inst: any): number[] => {
+  let entries = activeMap.get(inst);
+  if (!entries) {
+    entries = [];
+    activeMap.set(inst, entries);
+  }
+  return entries;
+};
+
+const startFrameLoop = (win: Window, entries: number[], frameFn: FrameCallback): number => {
+  let currentId = 0;
+  const step = (timestamp: number, prevValue?: any) => {
+    const idx = entries.indexOf(currentId);
+    if (idx >= 0) entries.splice(idx, 1);
+    let result: any;
+    try {
+      result = frameFn(timestamp, prevValue);
+    } catch (e) {
+      console.error('[SWC] requestAnimationFrame callback error:', e);
+      return;
+    }
+    if (result === undefined || result === null) return; // 개발자가 종료를 신호함 - 다음 프레임 예약 안 함
+    currentId = win.requestAnimationFrame(ts => step(ts, result));
+    entries.push(currentId);
+  };
+  currentId = win.requestAnimationFrame(ts => step(ts, undefined));
+  entries.push(currentId);
+  return currentId;
+};
+
+const applyRequestAnimationFrame = (options: RequestAnimationFrameOptions, target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor): PropertyDescriptor | void => {
+  const constructor = target.constructor;
+  const normalizedOptions: RequestAnimationFrameOptions = { ...options, type: options.type ?? 'returnValue' };
+
+  let metaList = ReflectUtils.getOwnMetadata(REQUEST_ANIMATION_FRAME_METADATA_KEY, constructor) as RequestAnimationFrameMetadata[];
+  if (!metaList) {
+    metaList = [];
+    ReflectUtils.defineMetadata(REQUEST_ANIMATION_FRAME_METADATA_KEY, metaList, constructor);
+  }
+  metaList.push({ propertyKey, options: normalizedOptions });
+
+  if (normalizedOptions.type === 'onConnected' || !descriptor) {
+    return; // LifeCycler가 connect/disconnect를 전담 - wrapping 불필요
+  }
+
+  const original = descriptor.value;
+  descriptor.value = function (this: any, ...args: any[]) {
+    const res = original.apply(this, args);
+    // valueKey를 안 주면 이 데코레이터 전용 METADATA_KEY로 폴백 (applyAttribute.ts/applyNode.ts와 동일한 컨벤션)
+    const vk = normalizedOptions.valueKey ?? REQUEST_ANIMATION_FRAME_METADATA_KEY;
+    const frameFn: FrameCallback | undefined =
+      typeof res === 'function' ? res : res && typeof res === 'object' && typeof res[vk] === 'function' ? res[vk] : undefined;
+
+    if (frameFn) {
+      ensureInit(this);
+      const conf = getElementConfig(this);
+      const win = (this as any)._resolveWindow?.(conf) || ((typeof window !== 'undefined' ? window : undefined) as Window);
+      const id = startFrameLoop(win, getActiveEntries(this), frameFn);
+      normalizedOptions.created?.(SwcUtils.getHelperAndHostSet(win, this), id);
+    }
+    return res;
+  };
+  return descriptor;
+};
+
+/**
+ * type:'onConnected' - connect 시 자동으로 매 프레임 루프를 시작하고, disconnect 시 자동으로 cancelAnimationFrame 한다.
+ * type:'returnValue'(기본값) - 메서드를 감싸지 않는 대신, 호출될 때마다(개발자가 직접 호출) 원본 로직을
+ *   그대로 실행하고 리턴값(또는 valueKey로 뽑은 값)이 함수면 그 함수를 매 프레임 호출되는 루프로 등록한다.
+ *   원본 리턴값은 그대로 통과시키므로 다른 데코레이터와 같은 메서드에 스택해도 순서에 상관없이 안전하다.
+ *
+ * 옵션 없이 `@requestAnimationFrame` 그대로 붙여도 되고, `@requestAnimationFrame({...})`처럼 옵션을 줄 수도 있다.
+ */
+export function requestAnimationFrame(options?: RequestAnimationFrameOptions): MethodDecorator;
+export function requestAnimationFrame(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function requestAnimationFrame(optionsOrTarget?: RequestAnimationFrameOptions | Object, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  if (propertyKey !== undefined) {
+    // 옵션 없이: @requestAnimationFrame
+    applyRequestAnimationFrame({}, optionsOrTarget as Object, propertyKey, descriptor);
+    return;
+  }
+  // 옵션과 함께: @requestAnimationFrame() 또는 @requestAnimationFrame({...})
+  return (target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor) => {
+    return applyRequestAnimationFrame((optionsOrTarget as RequestAnimationFrameOptions) ?? {}, target, propertyKey, descriptor);
+  };
+}
+
+export const findAllRequestAnimationFrameMetadata = (target: any): RequestAnimationFrameMetadata[] => {
+  const constructor = target instanceof Function ? target : target.constructor;
+  return (ReflectUtils.findAllMetadata<RequestAnimationFrameMetadata[]>(REQUEST_ANIMATION_FRAME_METADATA_KEY, constructor) || []).flat();
+};
+
+export class RequestAnimationFrameLifeCycler implements ElementDefineLifeCycler {
+  onConnected(helperHostSet: HelperHostSet): void {
+    const inst = helperHostSet.$this;
+    activeMap.delete(inst); // 재연결 대비 리셋
+    const entries = getActiveEntries(inst);
+    for (const meta of findAllRequestAnimationFrameMetadata(inst)) {
+      if (meta.options.type !== 'onConnected') continue; // returnValue 타입은 수동 호출을 기다림
+      const frameFn: FrameCallback = (timestamp, prevValue) => inst[meta.propertyKey](timestamp, prevValue);
+      const id = startFrameLoop(helperHostSet.$w, entries, frameFn);
+      meta.options.created?.(helperHostSet, id);
+    }
+  }
+
+  onDisconnected(helperHostSet: HelperHostSet): void {
+    const inst = helperHostSet.$this;
+    for (const id of activeMap.get(inst) ?? []) {
+      try {
+        helperHostSet.$w.cancelAnimationFrame(id);
+      } catch (e) {
+        console.error('[SWC] cancelAnimationFrame error:', e);
+      }
+    }
+    activeMap.delete(inst);
+  }
+}

package/src/decorators/resizeObserver.ts

@@ -26,107 +26,123 @@ export interface ResizeObserverMetadata {
 
 export const RESIZE_OBSERVER_METADATA_KEY = Symbol.for('simple-web-component:resize-observer');
 
+const applyResizeObserver = (selector: SwcSelector, options: ResizeObserverOptions, targetObj: Object, propertyKey: string | symbol): void => {
+  const constructor = targetObj.constructor;
+  let observers = ReflectUtils.getMetadata<ResizeObserverMetadata[]>(RESIZE_OBSERVER_METADATA_KEY, constructor);
+  if (!observers) {
+    observers = [];
+    ReflectUtils.defineMetadata(RESIZE_OBSERVER_METADATA_KEY, observers, constructor);
+  }
+  observers.push({ propertyKey, selector, options });
+};
+
+const resolveResizeObserverArgs = (
+  selectorOrOptions: SwcSelector | ResizeObserverOptions | undefined,
+  maybeOptions: ResizeObserverOptions | undefined,
+  extra: Partial<ResizeObserverOptions>
+): { selector: SwcSelector; options: ResizeObserverOptions } => {
+  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 dispatchResizeObserver = (
+  selectorOrOptionsOrTarget: SwcSelector | ResizeObserverOptions | Object | undefined,
+  maybeOptionsOrPropertyKey: ResizeObserverOptions | string | symbol | undefined,
+  descriptor: PropertyDescriptor | undefined,
+  extra: Partial<ResizeObserverOptions>
+): MethodDecorator | void => {
+  if ((typeof maybeOptionsOrPropertyKey === 'string' || typeof maybeOptionsOrPropertyKey === 'symbol') && descriptor !== undefined) {
+    // 옵션 없이: @decorator
+    applyResizeObserver('$this', { ...extra }, selectorOrOptionsOrTarget as Object, maybeOptionsOrPropertyKey);
+    return;
+  }
+  // 옵션과 함께: @decorator() / @decorator(selector, options) / @decorator(options)
+  const { selector, options } = resolveResizeObserverArgs(
+    selectorOrOptionsOrTarget as SwcSelector | ResizeObserverOptions | undefined,
+    maybeOptionsOrPropertyKey as ResizeObserverOptions | undefined,
+    extra
+  );
+  return (targetObj: Object, propertyKey: string | symbol) => {
+    applyResizeObserver(selector, options, targetObj, propertyKey);
+  };
+};
+
 export function resizeObserver(target: SpecialSelector, options?: ResizeObserverQueryOptions): MethodDecorator;
 export function resizeObserver(selector: string, options?: ResizeObserverQueryOptions): MethodDecorator;
 export function resizeObserver(selector: SwcFnSelector, options?: ResizeObserverNonQueryOptions): MethodDecorator;
 export function resizeObserver(options?: ResizeObserverQueryOptions): MethodDecorator;
+export function resizeObserver(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
 /**
  * @resizeObserver decorator to observe element size changes.
+ * 옵션 없이 `@resizeObserver` 그대로 붙여도 되고, `@resizeObserver(...)`처럼 셀렉터/옵션을 줄 수도 있다.
  */
-export function resizeObserver(selectorOrOptions?: SwcSelector | ResizeObserverOptions, maybeOptions?: ResizeObserverOptions): MethodDecorator {
-  return (targetObj: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
-    let selector: SwcSelector = '$this';
-    let options: ResizeObserverOptions = {};
-
-    if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-      selector = selectorOrOptions;
-      options = maybeOptions ?? {};
-    } else {
-      selector = '$this';
-      options = selectorOrOptions ?? {};
-    }
-
-    const constructor = targetObj.constructor;
-
-    let observers = ReflectUtils.getMetadata<ResizeObserverMetadata[]>(RESIZE_OBSERVER_METADATA_KEY, constructor);
-    if (!observers) {
-      observers = [];
-      ReflectUtils.defineMetadata(RESIZE_OBSERVER_METADATA_KEY, observers, constructor);
-    }
-
-    observers.push({ propertyKey, selector, options });
-  };
+export function resizeObserver(selectorOrOptionsOrTarget?: SwcSelector | ResizeObserverOptions | Object, maybeOptionsOrPropertyKey?: ResizeObserverOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchResizeObserver(selectorOrOptionsOrTarget, maybeOptionsOrPropertyKey, descriptor, {});
 }
 
-export function resizeObserverThis(options?: ResizeObserverQueryOptions): MethodDecorator {
-  return resizeObserver('$this', options);
+export function resizeObserverThis(options?: ResizeObserverQueryOptions): MethodDecorator;
+export function resizeObserverThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function resizeObserverThis(optionsOrTarget?: ResizeObserverQueryOptions | Object, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchResizeObserver(optionsOrTarget, propertyKey, descriptor, {});
 }
 
 // ─── root별 delegate 헬퍼 (root 주입 → 문자열 셀렉터 전용) ───
 
 export function resizeObserverDelegateLight(selector: string, options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
 export function resizeObserverDelegateLight(options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
-export function resizeObserverDelegateLight(selectorOrOptions?: string | Omit<ResizeObserverQueryOptions, 'delegate'>, maybeOptions?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return resizeObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'light', delegate: true});
-  }
-  return resizeObserver({...selectorOrOptions ?? {}, root: 'light', delegate: true});
+export function resizeObserverDelegateLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function resizeObserverDelegateLight(selectorOrOptionsOrTarget?: string | Omit<ResizeObserverQueryOptions, 'delegate'> | Object, maybeOptionsOrPropertyKey?: Omit<ResizeObserverQueryOptions, 'delegate'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'light', delegate: true });
 }
 
 export function resizeObserverDelegateShadow(selector: string, options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
 export function resizeObserverDelegateShadow(options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
-export function resizeObserverDelegateShadow(selectorOrOptions?: string | Omit<ResizeObserverQueryOptions, 'delegate'>, maybeOptions?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return resizeObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'shadow', delegate: true});
-  }
-  return resizeObserver({...selectorOrOptions ?? {}, root: 'shadow', delegate: true});
+export function resizeObserverDelegateShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function resizeObserverDelegateShadow(selectorOrOptionsOrTarget?: string | Omit<ResizeObserverQueryOptions, 'delegate'> | Object, maybeOptionsOrPropertyKey?: Omit<ResizeObserverQueryOptions, 'delegate'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'shadow', delegate: true });
 }
 
 export function resizeObserverDelegateAll(selector: string, options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
 export function resizeObserverDelegateAll(options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
-export function resizeObserverDelegateAll(selectorOrOptions?: string | Omit<ResizeObserverQueryOptions, 'delegate'>, maybeOptions?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return resizeObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'all', delegate: true});
-  }
-  return resizeObserver({...selectorOrOptions ?? {}, root: 'all', delegate: true});
+export function resizeObserverDelegateAll(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function resizeObserverDelegateAll(selectorOrOptionsOrTarget?: string | Omit<ResizeObserverQueryOptions, 'delegate'> | Object, maybeOptionsOrPropertyKey?: Omit<ResizeObserverQueryOptions, 'delegate'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'all', delegate: true });
 }
 
 export function resizeObserverDelegate(selector: string, options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
 export function resizeObserverDelegate(options?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator;
-export function resizeObserverDelegate(selectorOrOptions?: string | Omit<ResizeObserverQueryOptions, 'delegate'>, maybeOptions?: Omit<ResizeObserverQueryOptions, 'delegate'>): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return resizeObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'auto', delegate: true});
-  }
-  return resizeObserver({...selectorOrOptions ?? {}, root: 'auto', delegate: true});
+export function resizeObserverDelegate(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function resizeObserverDelegate(selectorOrOptionsOrTarget?: string | Omit<ResizeObserverQueryOptions, 'delegate'> | Object, maybeOptionsOrPropertyKey?: Omit<ResizeObserverQueryOptions, 'delegate'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'auto', delegate: true });
 }
 
 // ─── root별 일반 헬퍼 (delegate 없이, 셀렉터 생략 시 $this) ───
 
 export function resizeObserverLight(selector: string, options?: ResizeObserverQueryOptions): MethodDecorator;
 export function resizeObserverLight(options?: ResizeObserverQueryOptions): MethodDecorator;
-export function resizeObserverLight(selectorOrOptions?: string | ResizeObserverQueryOptions, maybeOptions?: ResizeObserverQueryOptions): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return resizeObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'light'});
-  }
-  return resizeObserver({...selectorOrOptions ?? {}, root: 'light'});
+export function resizeObserverLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function resizeObserverLight(selectorOrOptionsOrTarget?: string | ResizeObserverQueryOptions | Object, maybeOptionsOrPropertyKey?: ResizeObserverQueryOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'light' });
 }
 
 export function resizeObserverShadow(selector: string, options?: ResizeObserverQueryOptions): MethodDecorator;
 export function resizeObserverShadow(options?: ResizeObserverQueryOptions): MethodDecorator;
-export function resizeObserverShadow(selectorOrOptions?: string | ResizeObserverQueryOptions, maybeOptions?: ResizeObserverQueryOptions): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return resizeObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'shadow'});
-  }
-  return resizeObserver({...selectorOrOptions ?? {}, root: 'shadow'});
+export function resizeObserverShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function resizeObserverShadow(selectorOrOptionsOrTarget?: string | ResizeObserverQueryOptions | Object, maybeOptionsOrPropertyKey?: ResizeObserverQueryOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'shadow' });
 }
 
 export function resizeObserverAll(selector: string, options?: ResizeObserverQueryOptions): MethodDecorator;
 export function resizeObserverAll(options?: ResizeObserverQueryOptions): MethodDecorator;
-export function resizeObserverAll(selectorOrOptions?: string | ResizeObserverQueryOptions, maybeOptions?: ResizeObserverQueryOptions): MethodDecorator {
-  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return resizeObserver(selectorOrOptions as any, {...maybeOptions ?? {}, root: 'all'});
-  }
-  return resizeObserver({...selectorOrOptions ?? {}, root: 'all'});
+export function resizeObserverAll(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
+export function resizeObserverAll(selectorOrOptionsOrTarget?: string | ResizeObserverQueryOptions | Object, maybeOptionsOrPropertyKey?: ResizeObserverQueryOptions | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | void {
+  return dispatchResizeObserver(selectorOrOptionsOrTarget as any, maybeOptionsOrPropertyKey as any, descriptor, { root: 'all' });
 }
 
 export function getResizeObserverMetadata(target: any): ResizeObserverMetadata[] | undefined {

package/src/decorators/setInterval.ts

@@ -1,16 +1,28 @@
 import { ReflectUtils } from '@dooboostore/core';
+import { ensureInit, getElementConfig } from './elementDefine';
+import { SwcUtils } from '../utils/Utils';
 import { ElementDefineLifeCycler, HelperHostSet } from '../types';
 
 export const SET_INTERVAL_METADATA_KEY = Symbol.for('simple-web-component:set-interval');
 
+export type SetIntervalType = 'onConnected' | 'returnValue';
+
 export interface SetIntervalOptions {
-  /** 매 tick마다 데코레이트된 메서드에 넘길 인자를 계산. 없으면 인자 없이 호출. */
+  /**
+   * 'onConnected' (connect 시 자동으로 시작, disconnect 시 자동 정리) |
+   * 'returnValue' (기본값 - 자동 시작 없음. 개발자가 이 메서드를 직접 호출해야 시작되고,
+   *   그 호출의 리턴값이 실제로 반복 실행될 함수가 된다 - 아래 설명 참고).
+   */
+  type?: SetIntervalType;
+  /** 매 tick마다 데코레이트된 메서드에 넘길 인자를 계산. type:'onConnected'에서만 의미가 있음 (없으면 인자 없이 호출). */
   parameter?: (set: HelperHostSet) => any[];
   /** 타이머 등록 직후 1회 호출 (디버깅/로깅용). id는 실제 setInterval 반환값 - cleanup은 자동으로 처리되므로 직접 clear할 필요 없음. */
   created?: (set: HelperHostSet, id: number) => void;
   /**
-   * 매 tick마다 데코레이트된 메서드의 리턴값이 객체이고 이 키의 값이 함수이면 (id: number)로 호출한다.
-   * applyAttribute.ts의 valueKey와 동일한 컨벤션 - 리턴 객체에서 이 데코레이터 몫만 뽑아 쓴다.
+   * type:'onConnected' - 매 tick마다 데코레이트된 메서드의 리턴값이 객체이고 이 키의 값이 함수이면 (id: number)로 호출한다.
+   * type:'returnValue' - 리턴값이 함수면 그 자체를, 객체면 이 키의 값이 함수일 때 그 값을 "실제로 반복 실행될 함수"로 사용한다.
+   * 안 주면 SET_INTERVAL_METADATA_KEY로 폴백한다 - applyAttribute.ts/applyNode.ts의 valueKey와 동일한 컨벤션
+   * (리턴 객체에서 이 데코레이터 몫만 뽑아 쓰고, 다른 데코레이터와 스택할 때만 커스텀 키로 구분하면 된다).
    */
   valueKey?: symbol | string;
 }
@@ -21,18 +33,64 @@ export interface SetIntervalMetadata {
   options: SetIntervalOptions;
 }
 
+const activeMap = new WeakMap<any, number[]>();
+const getActiveEntries = (inst: any): number[] => {
+  let entries = activeMap.get(inst);
+  if (!entries) {
+    entries = [];
+    activeMap.set(inst, entries);
+  }
+  return entries;
+};
+
 /**
- * connect 시 자동으로 setInterval을 걸고, disconnect 시 자동으로 clearInterval 한다.
+ * type:'onConnected' - connect 시 자동으로 setInterval을 걸고, disconnect 시 자동으로 clearInterval 한다.
+ * type:'returnValue'(기본값) - 메서드를 감싸지 않는 대신, 호출될 때마다(개발자가 직접 호출) 원본 로직을
+ *   그대로 실행하고 리턴값(또는 valueKey로 뽑은 값)이 함수면 그 함수를 새 setInterval의 반복 콜백으로 등록한다.
+ *   호출할 때마다 별도의 새 타이머가 생기며, disconnect 시 전부 정리된다. 원본 리턴값은 그대로 통과시키므로
+ *   다른 데코레이터와 같은 메서드에 스택해도 순서에 상관없이 안전하다.
  */
 export function setInterval(interval: number, options: SetIntervalOptions = {}): MethodDecorator {
-  return (target: Object, propertyKey: string | symbol) => {
+  return (target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor) => {
     const constructor = target.constructor;
+    const normalizedOptions: SetIntervalOptions = { ...options, type: options.type ?? 'returnValue' };
+
     let metaList = ReflectUtils.getOwnMetadata(SET_INTERVAL_METADATA_KEY, constructor) as SetIntervalMetadata[];
     if (!metaList) {
       metaList = [];
       ReflectUtils.defineMetadata(SET_INTERVAL_METADATA_KEY, metaList, constructor);
     }
-    metaList.push({ propertyKey, interval, options });
+    metaList.push({ propertyKey, interval, options: normalizedOptions });
+
+    if (normalizedOptions.type === 'onConnected' || !descriptor) {
+      return; // LifeCycler가 connect/disconnect를 전담 - wrapping 불필요
+    }
+
+    const original = descriptor.value;
+    descriptor.value = function (this: any, ...args: any[]) {
+      const res = original.apply(this, args);
+      // valueKey를 안 주면 이 데코레이터 전용 METADATA_KEY로 폴백 (applyAttribute.ts/applyNode.ts와 동일한 컨벤션)
+      const vk = normalizedOptions.valueKey ?? SET_INTERVAL_METADATA_KEY;
+      const tickFn: ((id: number) => void) | undefined =
+        typeof res === 'function' ? res : res && typeof res === 'object' && typeof res[vk] === 'function' ? res[vk] : undefined;
+
+      if (tickFn) {
+        ensureInit(this);
+        const conf = getElementConfig(this);
+        const win = (this as any)._resolveWindow?.(conf) || ((typeof window !== 'undefined' ? window : undefined) as Window);
+        const id = win.setInterval(() => {
+          try {
+            tickFn(id);
+          } catch (e) {
+            console.error('[SWC] setInterval tick error:', e);
+          }
+        }, interval);
+        normalizedOptions.created?.(SwcUtils.getHelperAndHostSet(win, this), id);
+        getActiveEntries(this).push(id);
+      }
+      return res;
+    };
+    return descriptor;
   };
 }
 
@@ -42,18 +100,17 @@ export const findAllSetIntervalMetadata = (target: any): SetIntervalMetadata[] =
 };
 
 export class SetIntervalLifeCycler implements ElementDefineLifeCycler {
-  private readonly activeMap = new WeakMap<any, number[]>();
-
   onConnected(helperHostSet: HelperHostSet): void {
     const inst = helperHostSet.$this;
-    const ids: number[] = [];
+    activeMap.delete(inst); // 재연결 대비 리셋
     for (const meta of findAllSetIntervalMetadata(inst)) {
+      if (meta.options.type !== 'onConnected') continue; // returnValue 타입은 수동 호출을 기다림
       const id = helperHostSet.$w.setInterval(() => {
         const args = meta.options.parameter?.(helperHostSet) ?? [];
         try {
           const res = inst[meta.propertyKey](...args);
-          const vk = meta.options.valueKey;
-          if (vk && res && typeof res === 'object' && typeof res[vk] === 'function') {
+          const vk = meta.options.valueKey ?? SET_INTERVAL_METADATA_KEY;
+          if (res && typeof res === 'object' && typeof res[vk] === 'function') {
             res[vk](id);
           }
         } catch (e) {
@@ -61,20 +118,19 @@ export class SetIntervalLifeCycler implements ElementDefineLifeCycler {
         }
       }, meta.interval);
       meta.options.created?.(helperHostSet, id);
-      ids.push(id);
+      getActiveEntries(inst).push(id);
     }
-    this.activeMap.set(inst, ids);
   }
 
   onDisconnected(helperHostSet: HelperHostSet): void {
     const inst = helperHostSet.$this;
-    for (const id of this.activeMap.get(inst) ?? []) {
+    for (const id of activeMap.get(inst) ?? []) {
       try {
         helperHostSet.$w.clearInterval(id);
       } catch (e) {
         console.error('[SWC] clearInterval error:', e);
       }
     }
-    this.activeMap.delete(inst);
+    activeMap.delete(inst);
   }
 }

package/src/decorators/setTimeout.ts

@@ -1,16 +1,28 @@
 import { ReflectUtils } from '@dooboostore/core';
+import { ensureInit, getElementConfig } from './elementDefine';
+import { SwcUtils } from '../utils/Utils';
 import { ElementDefineLifeCycler, HelperHostSet } from '../types';
 
 export const SET_TIMEOUT_METADATA_KEY = Symbol.for('simple-web-component:set-timeout');
 
+export type SetTimeoutType = 'onConnected' | 'returnValue';
+
 export interface SetTimeoutOptions {
-  /** 실행 시 데코레이트된 메서드에 넘길 인자를 계산. 없으면 인자 없이 호출. */
+  /**
+   * 'onConnected' (connect 시 자동으로 예약, disconnect 시 자동 정리) |
+   * 'returnValue' (기본값 - 자동 예약 없음. 개발자가 이 메서드를 직접 호출해야 예약되고,
+   *   그 호출의 리턴값이 실제로 실행될 함수가 된다 - 아래 설명 참고).
+   */
+  type?: SetTimeoutType;
+  /** 실행 시 데코레이트된 메서드에 넘길 인자를 계산. type:'onConnected'에서만 의미가 있음 (없으면 인자 없이 호출). */
   parameter?: (set: HelperHostSet) => any[];
   /** 타이머 등록 직후 1회 호출 (디버깅/로깅용). id는 실제 setTimeout 반환값 - cleanup은 자동으로 처리되므로 직접 clear할 필요 없음. */
   created?: (set: HelperHostSet, id: number) => void;
   /**
-   * fire 시 데코레이트된 메서드의 리턴값이 객체이고 이 키의 값이 함수이면 (id: number)로 호출한다.
-   * applyAttribute.ts의 valueKey와 동일한 컨벤션 - 리턴 객체에서 이 데코레이터 몫만 뽑아 쓴다.
+   * type:'onConnected' - fire 시 데코레이트된 메서드의 리턴값이 객체이고 이 키의 값이 함수이면 (id: number)로 호출한다.
+   * type:'returnValue' - 리턴값이 함수면 그 자체를, 객체면 이 키의 값이 함수일 때 그 값을 "실제로 실행될 함수"로 사용한다.
+   * 안 주면 SET_TIMEOUT_METADATA_KEY로 폴백한다 - applyAttribute.ts/applyNode.ts의 valueKey와 동일한 컨벤션
+   * (리턴 객체에서 이 데코레이터 몫만 뽑아 쓰고, 다른 데코레이터와 스택할 때만 커스텀 키로 구분하면 된다).
    */
   valueKey?: symbol | string;
 }
@@ -21,18 +33,67 @@ export interface SetTimeoutMetadata {
   options: SetTimeoutOptions;
 }
 
+const activeMap = new WeakMap<any, number[]>();
+const getActiveEntries = (inst: any): number[] => {
+  let entries = activeMap.get(inst);
+  if (!entries) {
+    entries = [];
+    activeMap.set(inst, entries);
+  }
+  return entries;
+};
+
 /**
- * connect 시 자동으로 setTimeout을 걸고, disconnect 시 (아직 실행 전이라면) 자동으로 clearTimeout 한다.
+ * type:'onConnected' - connect 시 자동으로 setTimeout을 걸고, disconnect 시 (아직 실행 전이라면) 자동으로 clearTimeout 한다.
+ * type:'returnValue'(기본값) - 메서드를 감싸지 않는 대신, 호출될 때마다(개발자가 직접 호출) 원본 로직을
+ *   그대로 실행하고 리턴값(또는 valueKey로 뽑은 값)이 함수면 그 함수를 새 setTimeout으로 예약한다.
+ *   호출할 때마다 별도의 새 타이머가 생기며, disconnect 시 (아직 실행 전인 것들은) 전부 정리된다.
+ *   원본 리턴값은 그대로 통과시키므로 다른 데코레이터와 같은 메서드에 스택해도 순서에 상관없이 안전하다.
  */
 export function setTimeout(delay: number, options: SetTimeoutOptions = {}): MethodDecorator {
-  return (target: Object, propertyKey: string | symbol) => {
+  return (target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor) => {
     const constructor = target.constructor;
+    const normalizedOptions: SetTimeoutOptions = { ...options, type: options.type ?? 'returnValue' };
+
     let metaList = ReflectUtils.getOwnMetadata(SET_TIMEOUT_METADATA_KEY, constructor) as SetTimeoutMetadata[];
     if (!metaList) {
       metaList = [];
       ReflectUtils.defineMetadata(SET_TIMEOUT_METADATA_KEY, metaList, constructor);
     }
-    metaList.push({ propertyKey, delay, options });
+    metaList.push({ propertyKey, delay, options: normalizedOptions });
+
+    if (normalizedOptions.type === 'onConnected' || !descriptor) {
+      return; // LifeCycler가 connect/disconnect를 전담 - wrapping 불필요
+    }
+
+    const original = descriptor.value;
+    descriptor.value = function (this: any, ...args: any[]) {
+      const res = original.apply(this, args);
+      // valueKey를 안 주면 이 데코레이터 전용 METADATA_KEY로 폴백 (applyAttribute.ts/applyNode.ts와 동일한 컨벤션)
+      const vk = normalizedOptions.valueKey ?? SET_TIMEOUT_METADATA_KEY;
+      const tickFn: ((id: number) => void) | undefined =
+        typeof res === 'function' ? res : res && typeof res === 'object' && typeof res[vk] === 'function' ? res[vk] : undefined;
+
+      if (tickFn) {
+        ensureInit(this);
+        const conf = getElementConfig(this);
+        const win = (this as any)._resolveWindow?.(conf) || ((typeof window !== 'undefined' ? window : undefined) as Window);
+        const id = win.setTimeout(() => {
+          const entries = getActiveEntries(this);
+          const idx = entries.indexOf(id);
+          if (idx >= 0) entries.splice(idx, 1);
+          try {
+            tickFn(id);
+          } catch (e) {
+            console.error('[SWC] setTimeout fire error:', e);
+          }
+        }, delay);
+        normalizedOptions.created?.(SwcUtils.getHelperAndHostSet(win, this), id);
+        getActiveEntries(this).push(id);
+      }
+      return res;
+    };
+    return descriptor;
   };
 }
 
@@ -42,18 +103,17 @@ export const findAllSetTimeoutMetadata = (target: any): SetTimeoutMetadata[] =>
 };
 
 export class SetTimeoutLifeCycler implements ElementDefineLifeCycler {
-  private readonly activeMap = new WeakMap<any, number[]>();
-
   onConnected(helperHostSet: HelperHostSet): void {
     const inst = helperHostSet.$this;
-    const ids: number[] = [];
+    activeMap.delete(inst); // 재연결 대비 리셋
     for (const meta of findAllSetTimeoutMetadata(inst)) {
+      if (meta.options.type !== 'onConnected') continue; // returnValue 타입은 수동 호출을 기다림
       const id = helperHostSet.$w.setTimeout(() => {
         const args = meta.options.parameter?.(helperHostSet) ?? [];
         try {
           const res = inst[meta.propertyKey](...args);
-          const vk = meta.options.valueKey;
-          if (vk && res && typeof res === 'object' && typeof res[vk] === 'function') {
+          const vk = meta.options.valueKey ?? SET_TIMEOUT_METADATA_KEY;
+          if (res && typeof res === 'object' && typeof res[vk] === 'function') {
             res[vk](id);
           }
         } catch (e) {
@@ -61,20 +121,19 @@ export class SetTimeoutLifeCycler implements ElementDefineLifeCycler {
         }
       }, meta.delay);
       meta.options.created?.(helperHostSet, id);
-      ids.push(id);
+      getActiveEntries(inst).push(id);
     }
-    this.activeMap.set(inst, ids);
   }
 
   onDisconnected(helperHostSet: HelperHostSet): void {
     const inst = helperHostSet.$this;
-    for (const id of this.activeMap.get(inst) ?? []) {
+    for (const id of activeMap.get(inst) ?? []) {
       try {
         helperHostSet.$w.clearTimeout(id);
       } catch (e) {
         console.error('[SWC] clearTimeout error:', e);
       }
     }
-    this.activeMap.delete(inst);
+    activeMap.delete(inst);
   }
 }