@dooboostore/simple-web-component 1.0.48 → 1.0.50

package/src/decorators/query.ts

@@ -1,36 +1,110 @@
 import { ReflectUtils } from '@dooboostore/core';
 import { getElementConfig, ensureInit } from './elementDefine';
 import { SwcUtils } from '../utils/Utils';
-import { SwcQueryOptions, HelperHostSet } from '../types';
+import { SwcQueryOptions, SwcRootType, SwcFnSelector, SwcSelector, HelperHostSet } from '../types';
 
-export interface QueryOptions extends SwcQueryOptions {
-  /**
-   * Filter function to determine whether to include the element.
-   * If it returns false, the element is skipped.
-   */
+export type QueryPick = 'first' | 'last' | 'all' | 'even' | 'odd' | number;
+
+export interface QueryBaseOptions {
+  // 어떤 요소를 고를지 — 기본 'first'(단일). 'all'/'even'/'odd'는 배열, number는 인덱스(단일)
+  pick?: QueryPick;
   filter?: (target: HTMLElement, meta: { currentThis: any, helper: HelperHostSet }) => boolean;
 }
+// 문자열 셀렉터 전용 — root 허용
+export type QueryOptions = QueryBaseOptions & SwcQueryOptions;
+// 함수 셀렉터 전용 — root 금지
+export type QueryNonQueryOptions = QueryBaseOptions;
+
+export type QueryFnSelector = SwcFnSelector;
+export type QuerySelector = SwcSelector;
+
+// 셀렉터 종류에 따라 옵션 타입 분기
+export type QueryOptionsOf<S extends QuerySelector> = S extends string ? QueryOptions : QueryNonQueryOptions;
 
 export interface QueryMetadata {
   propertyKey: string | symbol;
-  selector: string | ((currentThis: any, helper: HelperHostSet) => Node | NodeList | Element | Element[] | null);
-  options: QueryOptions ;
+  selector: QuerySelector;
+  options: QueryOptions;
 }
 
 export const QUERY_METADATA_KEY = Symbol.for('simple-web-component:query');
 
+/**
+ * 셀렉터를 해석해 매칭된 모든 요소를 배열로 반환한다 (query/queryAll 공용).
+ * $window/$document는 요소가 아니므로 여기서 처리하지 않는다.
+ */
+export const resolveQueryElements = (
+  inst: any,
+  selector: QuerySelector,
+  options: QueryOptions,
+  win: Window
+): HTMLElement[] => {
+  const hostSet = SwcUtils.getHelperAndHostSet(win, inst);
+  let all: HTMLElement[] = [];
+
+  if (typeof selector === 'function') {
+    const result = (selector as any)(inst, hostSet);
+    if (result instanceof win.NodeList) all = Array.from(result as NodeList).filter(e => e instanceof win.HTMLElement) as HTMLElement[];
+    else if (Array.isArray(result)) all = (result as any[]).filter(e => e instanceof win.HTMLElement) as HTMLElement[];
+    else if (result instanceof win.HTMLElement) all = [result as HTMLElement];
+  } else if (typeof selector === 'string') {
+    const r = (options as any)?.root || 'auto';
+    if (selector === '$this') all = [inst as HTMLElement];
+    else if (selector === '$host') all = hostSet.$host ? [hostSet.$host] : [];
+    else if (selector === '$parentHost') all = hostSet.$parentHost ? [hostSet.$parentHost] : [];
+    else if (selector === '$appHost') all = hostSet.$appHost ? [hostSet.$appHost as any] : [];
+    else if (selector === '$firstHost') all = hostSet.$firstHost ? [hostSet.$firstHost] : [];
+    else if (selector === '$lastHost') all = hostSet.$lastHost ? [hostSet.$lastHost] : [];
+    else if (selector === '$firstAppHost') all = hostSet.$firstAppHost ? [hostSet.$firstAppHost as any] : [];
+    else if (selector === '$lastAppHost') all = hostSet.$lastAppHost ? [hostSet.$lastAppHost as any] : [];
+    else if (selector === '$hosts') all = hostSet.$hosts.filter(Boolean);
+    else if (selector === '$appHosts') all = hostSet.$appHosts.filter(Boolean) as any[];
+    else {
+      const scopes: any[] = [];
+      if (r === 'auto') scopes.push(inst.shadowRoot || inst);
+      else if (r === 'light') scopes.push(inst);
+      else if (r === 'shadow' && inst.shadowRoot) scopes.push(inst.shadowRoot);
+      else if (r === 'all') { scopes.push(inst); if (inst.shadowRoot) scopes.push(inst.shadowRoot); }
+      for (const scope of scopes) {
+        const found = scope?.querySelectorAll?.(selector) as NodeListOf<HTMLElement> | undefined;
+        if (found?.length) all.push(...Array.from(found).filter(e => e instanceof win.HTMLElement));
+      }
+    }
+  }
+
+  if ((options as any)?.filter) {
+    all = all.filter(el => (options as any).filter(el, { currentThis: inst, helper: hostSet }));
+  }
+  return all;
+};
+
+/**
+ * 매칭된 요소 배열에서 pick 옵션에 따라 요소를 고른다.
+ * - 'first'(기본) / 'last' / number(인덱스) → 단일 요소
+ * - 'all' / 'even'(0,2,4...) / 'odd'(1,3,5...) → 배열
+ */
+export const pickElements = (
+  all: HTMLElement[],
+  pick: QueryPick
+): HTMLElement | HTMLElement[] | null => {
+  if (pick === 'all') return all;
+  if (pick === 'even') return all.filter((_, i) => i % 2 === 0);
+  if (pick === 'odd') return all.filter((_, i) => i % 2 === 1);
+  if (typeof pick === 'number') return all[pick] ?? null;
+  if (pick === 'last') return all.length ? all[all.length - 1] : null;
+  return all.length ? all[0] : null;
+};
+
 export function query(target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor): PropertyDescriptor | void;
-export function query(selector: string | ((currentThis: any, helper: HelperHostSet) => Node | NodeList | Element | Element[] | null), options?: QueryOptions): PropertyDecorator;
+export function query(selector: string, options?: QueryOptions): PropertyDecorator;
+export function query(selector: QueryFnSelector, options?: QueryNonQueryOptions): PropertyDecorator;
 export function query(options?: QueryOptions): PropertyDecorator;
 /**
- * @query decorator to inject a single element into a class property.
- * 
- * Supports both string selectors and function-based selectors:
- * - String selector: @query('#my-element')
- * - Function selector: @query((currentThis, helper) => currentThis.shadowRoot?.querySelector('.item'))
- * 
- * Supports filtering:
- * - @query('#my-element', { filter: (target, meta) => target.hasAttribute('active') })
+ * @query decorator — 클래스 필드에 요소를 주입한다.
+ *
+ * - 문자열 셀렉터: CSS / 특수 셀렉터($this,$host,$window,...), root 옵션으로 탐색 영역 지정
+ * - 함수 셀렉터: (currentThis, helper) => Node | NodeList | Element | Element[] | null (root 금지)
+ * - options.pick: 'first'(기본) | 'last' | 'all' | 'even' | 'odd' | number
  */
 export function query(selectorOrTarget?: string | ((currentThis: any, helper: HelperHostSet) => Node | NodeList | Element | Element[] | null) | Object, optionsOrPropertyKey?: QueryOptions | string | symbol, descriptor?: PropertyDescriptor): any {
   // Bare decorator: @query
@@ -50,118 +124,32 @@ export function query(selectorOrTarget?: string | ((currentThis: any, helper: He
         queries = [];
         ReflectUtils.defineMetadata(QUERY_METADATA_KEY, queries, constructor);
       }
-      queries.push({ propertyKey, selector: selectorOrTarget as any, options: optionsOrPropertyKey as QueryOptions || {} });
+      queries.push({ propertyKey, selector: selectorOrTarget as any, options: (optionsOrPropertyKey as QueryOptions) || {} });
 
       Object.defineProperty(targetObj, propertyKey, {
         get(this: HTMLElement) {
           ensureInit(this);
           const config = getElementConfig(this);
           const win = config?.window || window;
-          const hostSet = SwcUtils.getHelperAndHostSet(win, this);
-          
-          // Resolve selector - can be string or function
-          let resolvedSelector: string;
-          let resolvedElement: HTMLElement | null = null;
-          
-          if (typeof selectorOrTarget === 'function') {
-            const result = (selectorOrTarget as any)(this, hostSet);
-            // If function returns a Node/Element, return it directly
-            if (result instanceof win.Node || result instanceof win.Element) {
-              resolvedElement = result instanceof win.HTMLElement ? (result as HTMLElement) : null;
-            }
-            // If function returns NodeList or Element[], return first element
-            else if (result instanceof win.NodeList || Array.isArray(result)) {
-              resolvedElement = result.length > 0 && result[0] instanceof win.HTMLElement ? (result[0] as HTMLElement) : null;
-            }
-          } else {
-            resolvedSelector = selectorOrTarget;
-
-            const r = (optionsOrPropertyKey as QueryOptions)?.root || 'auto';
-            const applyRoot = (t: any) => {
-              if (!t || !(t instanceof HTMLElement)) return t;
-              if (r === 'auto') return t.shadowRoot || t;
-              if (r === 'shadow') return t.shadowRoot;
-              if (r === 'light') return t;
-              if (r === 'all') return t.shadowRoot || t; 
-              return t;
-            };
-
-            // --- Special Selectors: HostSet ---
-            if (resolvedSelector === '$this') resolvedElement = applyRoot(this);
-            else if (resolvedSelector === '$host') resolvedElement = applyRoot(hostSet.$host);
-            else if (resolvedSelector === '$parentHost') resolvedElement = applyRoot(hostSet.$parentHost);
-            else if (resolvedSelector === '$appHost') resolvedElement = applyRoot(hostSet.$appHost);
-            else if (resolvedSelector === '$firstHost') resolvedElement = applyRoot(hostSet.$firstHost);
-            else if (resolvedSelector === '$lastHost') resolvedElement = applyRoot(hostSet.$lastHost);
-            else if (resolvedSelector === '$firstAppHost') resolvedElement = applyRoot(hostSet.$firstAppHost);
-            else if (resolvedSelector === '$lastAppHost') resolvedElement = applyRoot(hostSet.$lastAppHost);
-            // --- Special Selectors: Env ---
-            else if (resolvedSelector === '$window') return win;
-            else if (resolvedSelector === '$document') return win.document;
-            // --- Standard Selectors ---
-            else {
-              if (r === 'shadow') resolvedElement = this.shadowRoot ? (this.shadowRoot.querySelector(resolvedSelector) as HTMLElement | null) : null;
-              else if (r === 'light') resolvedElement = this.querySelector(resolvedSelector) as HTMLElement | null;
-              else if (r === 'all') {
-                const shadowMatch = this.shadowRoot ? (this.shadowRoot.querySelector(resolvedSelector) as HTMLElement | null) : null;
-                resolvedElement = shadowMatch || (this.querySelector(resolvedSelector) as HTMLElement | null);
-              }
-              else resolvedElement = ((this.shadowRoot || this).querySelector(resolvedSelector) as HTMLElement | null);
-            }
-          }
+          const options = (optionsOrPropertyKey as QueryOptions) || {};
 
-          // Apply filter if provided
-          if (resolvedElement instanceof win.HTMLElement && (optionsOrPropertyKey as QueryOptions)?.filter) {
-            const shouldInclude = (optionsOrPropertyKey as QueryOptions).filter!(resolvedElement, { currentThis: this, helper: hostSet });
-            if (!shouldInclude) {
-              return null;
-            }
-          }
+          // $window/$document는 요소가 아니므로 항상 단일 반환
+          if (typeof selectorOrTarget === 'string' && selectorOrTarget === '$window') return win;
+          if (typeof selectorOrTarget === 'string' && selectorOrTarget === '$document') return win.document;
 
-          return resolvedElement;
+          const all = resolveQueryElements(this, selectorOrTarget as QuerySelector, options, win);
+          return pickElements(all, options.pick ?? 'first');
         },
         set(this: HTMLElement, nv: any) {
           ensureInit(this);
-          if (nv === null || nv === undefined) {
+          if (nv === null || nv === undefined || (Array.isArray(nv) && nv.length === 0)) {
             const config = getElementConfig(this);
             const win = config?.window || window;
-            const hostSet = SwcUtils.getHelperAndHostSet(win, this);
-            
-            // Resolve selector - can be string or function
-            if (typeof selectorOrTarget === 'function') {
-              // Get the element from function and remove it
-              const result = (selectorOrTarget as any)(this, hostSet);
-              if (result instanceof win.Element) {
-                (result as Element).remove();
-              } else if (result instanceof win.NodeList || Array.isArray(result)) {
-                const el = result.length > 0 ? result[0] : null;
-                if (el instanceof win.Element) {
-                  (el as Element).remove();
-                }
-              }
-              return;
-            }
-            
-            const resolvedSelector = selectorOrTarget;
-            
-            if (resolvedSelector.startsWith('$') && resolvedSelector !== '$this') return;
-
-            const r = (optionsOrPropertyKey as QueryOptions)?.root || 'auto';
-            const targets: Element[] = [];
-
-            if (r === 'shadow') {
-              if (this.shadowRoot?.querySelector(resolvedSelector)) targets.push(this.shadowRoot.querySelector(resolvedSelector)!);
-            } else if (r === 'light') {
-              if (this.querySelector(resolvedSelector)) targets.push(this.querySelector(resolvedSelector)!);
-            } else if (r === 'all') {
-              if (this.shadowRoot?.querySelector(resolvedSelector)) targets.push(this.shadowRoot.querySelector(resolvedSelector)!);
-              if (this.querySelector(resolvedSelector)) targets.push(this.querySelector(resolvedSelector)!);
-            } else {
-              const el = (this.shadowRoot || this).querySelector(resolvedSelector);
-              if (el) targets.push(el);
-            }
-
-            targets.forEach(t => t.remove());
+            const options = (optionsOrPropertyKey as QueryOptions) || {};
+            const all = resolveQueryElements(this, selectorOrTarget as QuerySelector, options, win);
+            const picked = pickElements(all, options.pick ?? 'first');
+            if (Array.isArray(picked)) picked.forEach(t => t.remove());
+            else if (picked) picked.remove();
           }
         },
         enumerable: true,
@@ -170,7 +158,7 @@ export function query(selectorOrTarget?: string | ((currentThis: any, helper: He
     };
   }
   // Without selector (defaults to $this)
-  return query('$this', selectorOrTarget as SwcQueryOptions);
+  return query('$this', selectorOrTarget as QueryOptions);
 }
 
 export const getQueryMetadata = (target: any): QueryMetadata[]  => {
@@ -178,25 +166,79 @@ export const getQueryMetadata = (target: any): QueryMetadata[]  => {
   return ReflectUtils.getMetadata(QUERY_METADATA_KEY, constructor) ?? [];
 };
 
+// ─── queryAll (query의 pick:'all' 편의 래퍼 — 호환용) ───
+export const QUERY_ALL_METADATA_KEY = QUERY_METADATA_KEY;
+
+export function queryAll(target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor): PropertyDescriptor | void;
+export function queryAll(selector: string, options?: Omit<QueryOptions, 'pick'>): PropertyDecorator;
+export function queryAll(selector: QueryFnSelector, options?: Omit<QueryNonQueryOptions, 'pick'>): PropertyDecorator;
+export function queryAll(options?: Omit<QueryOptions, 'pick'>): PropertyDecorator;
+export function queryAll(selectorOrTarget?: any, optionsOrPropertyKey?: any, descriptor?: PropertyDescriptor): any {
+  // bare(필드 직접 적용)는 query로 위임
+  if (descriptor !== undefined && (typeof optionsOrPropertyKey === 'string' || typeof optionsOrPropertyKey === 'symbol')) {
+    return query(selectorOrTarget, optionsOrPropertyKey, descriptor);
+  }
+  if (typeof selectorOrTarget === 'string' || typeof selectorOrTarget === 'function') {
+    return query(selectorOrTarget, {...(optionsOrPropertyKey ?? {}), pick: 'all'});
+  }
+  return query({...(selectorOrTarget ?? {}), pick: 'all'});
+}
+
+export const getQueryAllMetadata = getQueryMetadata;
+
 // ─── root별 편의 데코레이터 ───
 
 /**
- * @queryShadow(selector, options?) — shadow DOM에서 단일 요소를 쿼리
+ * @queryShadow(selector, options?) — shadow DOM에서 요소를 쿼리
+ */
+export function queryShadow(selector: string | QueryFnSelector, options?: QueryBaseOptions): PropertyDecorator {
+  return query(selector as any, {...options ?? {}, root: 'shadow'});
+}
+
+/**
+ * @queryLight(selector, options?) — light DOM에서 요소를 쿼리
+ */
+export function queryLight(selector: string | QueryFnSelector, options?: QueryBaseOptions): PropertyDecorator {
+  return query(selector as any, {...options ?? {}, root: 'light'});
+}
+
+/**
+ * @queryAllRoots(selector, options?) — shadow+light 모두에서 요소를 쿼리 (pick 기본 first)
+ */
+export function queryAllRoots(selector: string | QueryFnSelector, options?: QueryBaseOptions): PropertyDecorator {
+  return query(selector as any, {...options ?? {}, root: 'all'});
+}
+
+/**
+ * @queryAllShadow(selector, options?) — shadow DOM에서 모든 매칭 요소를 배열로 쿼리
  */
-export function queryShadow(selector: string | ((currentThis: any, helper: HelperHostSet) => Node | NodeList | Element | Element[] | null), options?: Omit<QueryOptions, 'root'>): PropertyDecorator {
-  return query(selector, {...options ?? {}, root: 'shadow'});
+export function queryAllShadow(selector: string | QueryFnSelector, options?: QueryBaseOptions): PropertyDecorator {
+  return query(selector as any, {...options ?? {}, root: 'shadow', pick: 'all'});
 }
 
 /**
- * @queryLight(selector, options?) — light DOM에서 단일 요소를 쿼리
+ * @queryAllLight(selector, options?) — light DOM에서 모든 매칭 요소를 배열로 쿼리
  */
-export function queryLight(selector: string | ((currentThis: any, helper: HelperHostSet) => Node | NodeList | Element | Element[] | null), options?: Omit<QueryOptions, 'root'>): PropertyDecorator {
-  return query(selector, {...options ?? {}, root: 'light'});
+export function queryAllLight(selector: string | QueryFnSelector, options?: QueryBaseOptions): PropertyDecorator {
+  return query(selector as any, {...options ?? {}, root: 'light', pick: 'all'});
 }
 
 /**
- * @queryAll(selector, options?) — shadow+light 모두에서 요소를 쿼리
+ * @queryAllAll(selector, options?) — shadow+light 모두에서 모든 매칭 요소를 배열로 쿼리
  */
-export function queryAllRoots(selector: string | ((currentThis: any, helper: HelperHostSet) => Node | NodeList | Element | Element[] | null), options?: Omit<QueryOptions, 'root'>): PropertyDecorator {
-  return query(selector, {...options ?? {}, root: 'all'});
+export function queryAllAll(selector: string | QueryFnSelector, options?: QueryBaseOptions): PropertyDecorator {
+  return query(selector as any, {...options ?? {}, root: 'all', pick: 'all'});
 }
+
+/**
+ * @queryIn(root, pick?) — root + pick 조합 팩토리.
+ * first/last/even/odd/all/number를 모두 지원하는 데코레이터를 생성한다.
+ *
+ * @example
+ * @queryIn('shadow', 'even')('.item')   // shadow DOM 짝수 인덱스들
+ * @queryIn('light', 2)('.item')         // light DOM 3번째 요소
+ * @queryIn('all')('.item')              // root all, pick 기본 first
+ */
+export const queryIn = (root: SwcRootType, pick?: QueryPick) =>
+  (selector: string | QueryFnSelector, options?: QueryBaseOptions): PropertyDecorator =>
+    query(selector as any, {...options ?? {}, root, ...(pick !== undefined ? {pick} : {})});

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);
+  }
+}