@dooboostore/simple-web-component 1.0.47 → 1.0.49

package/src/decorators/applyNode.ts

@@ -1,6 +1,6 @@
 import { ReflectUtils } from '@dooboostore/core';
 import { ensureInit, getElementConfig } from './elementDefine';
-import {SpecialSelector, SwcQueryOptions, HelperHostSet, SwcRootType} from '../types';
+import {SpecialSelector, SwcQueryOptions, SwcFnSelector, SwcSelector, HelperHostSet, SwcRootType} from '../types';
 import { SwcUtils} from "../utils/Utils";
 import {findAllStateMetadata} from "./state";
 import {ElementApply} from "@dooboostore/core-web";
@@ -15,28 +15,26 @@ import {ElementApply} from "@dooboostore/core-web";
  */
 export type ApplyNodePosition = 'beforeBegin' | 'afterBegin' | 'beforeEnd' | 'afterEnd' | 'replace' | 'replaceChildren' | 'innerHtml' | 'innerText' | 'remove' | 'clearChildren';
 
-export type ApplyNodeSelector = string | ((currentThis: any, helper: HelperHostSet) => NodeList | Element | Element[] | null);
+export type ApplyNodeFnSelector = SwcFnSelector;
+export type ApplyNodeSelector = SwcSelector;
 
-export interface ApplyNodeOptions {
+// 공통 옵션 — root 없음
+export interface ApplyNodeBaseOptions {
   position?: ApplyNodePosition;
-  root?: SwcRootType;
-  /**
-   * Filter function to determine whether to perform DOM operation.
-   * If it returns false, the operation is skipped.
-   */
   filter?: (target: HTMLElement | ShadowRoot, newValue: any, meta: { currentThis: any, helper: HelperHostSet }) => boolean;
-  /**
-   * Optional loading content to display while an async method is executing.
-   */
   fallback?: (helper: HelperHostSet) => any;
-  /**
-   * Custom key to extract value from return object.
-   * If not provided, uses APPLY_NODE_METADATA_KEY by default.
-   * Useful when multiple @applyNode decorators are on the same method.
-   */
   valueKey?: symbol | string;
 }
 
+// 문자열 셀렉터 전용 — root 허용
+export type ApplyNodeQueryOptions = ApplyNodeBaseOptions & { root?: SwcRootType };
+// 함수 셀렉터 전용 — root 금지
+export type ApplyNodeNonQueryOptions = ApplyNodeBaseOptions;
+export type ApplyNodeOptions = ApplyNodeQueryOptions;
+
+// 셀렉터 종류에 따라 옵션 타입 분기
+export type ApplyNodeOptionsOf<S extends ApplyNodeSelector> = S extends string ? ApplyNodeQueryOptions : ApplyNodeNonQueryOptions;
+
 export interface ApplyNodeMetadata {
   propertyKey: string | symbol;
   selector: ApplyNodeSelector;
@@ -141,8 +139,9 @@ const applyToDom = (currentThis: any, targetEl: HTMLElement, res: Node | string,
  * - applyNode(selector, options) - Apply to specific selector
  * - applyNode(options) - Apply to $this (current element)
  */
-export function applyNode(selector: ApplyNodeSelector, options?: ApplyNodeOptions): MethodDecorator;
-export function applyNode(options: ApplyNodeOptions): MethodDecorator;
+export function applyNode(selector: string, options?: ApplyNodeQueryOptions): MethodDecorator;
+export function applyNode(selector: ApplyNodeFnSelector, options?: ApplyNodeNonQueryOptions): MethodDecorator;
+export function applyNode(options: ApplyNodeQueryOptions): MethodDecorator;
 export function applyNode(selectorOrOptions: ApplyNodeSelector | ApplyNodeOptions, maybeOptions?: ApplyNodeOptions): MethodDecorator {
   // Determine selector and options based on overload
   let selector: ApplyNodeSelector;
@@ -278,8 +277,13 @@ export function applyNode(selectorOrOptions: ApplyNodeSelector | ApplyNodeOption
  * - replaceChildrenNode(options) - Replace children of $this (current element)
  * - @replaceChildrenNode - Bare decorator, replaces children of $this
  */
-export function replaceChildren(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
-export function replaceChildren(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export type ApplyNodeQueryOptionsNoPos = Omit<ApplyNodeQueryOptions, 'position'>;
+export type ApplyNodeNonQueryOptionsNoPos = Omit<ApplyNodeNonQueryOptions, 'position'>;
+export type ApplyNodeOptionsOfNoPos<S extends ApplyNodeSelector> = S extends string ? ApplyNodeQueryOptionsNoPos : ApplyNodeNonQueryOptionsNoPos;
+
+export function replaceChildren(selector: string, options?: ApplyNodeQueryOptionsNoPos): MethodDecorator;
+export function replaceChildren(selector: ApplyNodeFnSelector, options?: ApplyNodeNonQueryOptionsNoPos): MethodDecorator;
+export function replaceChildren(options: ApplyNodeQueryOptionsNoPos): MethodDecorator;
 export function replaceChildren(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
 export function replaceChildren(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
   // Bare decorator usage: @replaceChildrenNode
@@ -288,7 +292,7 @@ export function replaceChildren(selectorOrOptions?: ApplyNodeSelector | Omit<App
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'replaceChildren'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'replaceChildren'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'replaceChildren'});
 }
@@ -311,7 +315,7 @@ export function clearChildrenNode(selectorOrOptions?: ApplyNodeSelector | Omit<A
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'clearChildren'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'clearChildren'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'clearChildren'});
 }
@@ -337,7 +341,7 @@ export function innerHtml(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNode
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'innerHtml'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'innerHtml'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'innerHtml'});
 }
@@ -363,7 +367,7 @@ export function innerHtmlLight(selectorOrOptions?: ApplyNodeSelector | Omit<Appl
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerHtml', root: 'light'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerHtml', root: 'light'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerHtml', root: 'light'});
 }
@@ -387,7 +391,7 @@ export function innerHtmlShadow(selectorOrOptions?: ApplyNodeSelector | Omit<App
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerHtml', root: 'shadow'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerHtml', root: 'shadow'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerHtml', root: 'shadow'});
 }
@@ -411,7 +415,7 @@ export function innerText(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNode
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'innerText'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'innerText'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'innerText'});
 }
@@ -435,7 +439,7 @@ export function innerTextLight(selectorOrOptions?: ApplyNodeSelector | Omit<Appl
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerText', root: 'light'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerText', root: 'light'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerText', root: 'light'});
 }
@@ -458,7 +462,7 @@ export function innerTextShadow(selectorOrOptions?: ApplyNodeSelector | Omit<App
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerText', root: 'shadow'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerText', root: 'shadow'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerText', root: 'shadow'});
 }
@@ -481,7 +485,7 @@ export function insertBeforeEnd(selectorOrOptions?: ApplyNodeSelector | Omit<App
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'beforeEnd'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'beforeEnd'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'beforeEnd'});
 }
@@ -505,7 +509,7 @@ export function insertBeforeEndLight(selectorOrOptions?: ApplyNodeSelector | Omi
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'beforeEnd', root: 'light'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'beforeEnd', root: 'light'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'beforeEnd', root: 'light'});
 }
@@ -529,7 +533,7 @@ export function insertBeforeEndShadow(selectorOrOptions?: ApplyNodeSelector | Om
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'beforeEnd', root: 'shadow'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'beforeEnd', root: 'shadow'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'beforeEnd', root: 'shadow'});
 }
@@ -553,7 +557,7 @@ export function insertAfterBegin(selectorOrOptions?: ApplyNodeSelector | Omit<Ap
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'afterBegin'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'afterBegin'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'afterBegin'});
 }
@@ -577,7 +581,7 @@ export function insertAfterBeginLight(selectorOrOptions?: ApplyNodeSelector | Om
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'afterBegin', root: 'light'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'afterBegin', root: 'light'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'afterBegin', root: 'light'});
 }
@@ -601,7 +605,7 @@ export function replaceChildrenLight(selectorOrOptions?: ApplyNodeSelector | Omi
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'replaceChildren', root: 'light'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'replaceChildren', root: 'light'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'replaceChildren', root: 'light'});
 }
@@ -624,7 +628,7 @@ export function clearChildrenLight(selectorOrOptions?: ApplyNodeSelector | Omit<
   }
   
   if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
-    return applyNode(selectorOrOptions as ApplyNodeSelector, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'clearChildren', root: 'light'});
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'clearChildren', root: 'light'});
   }
   return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'clearChildren', root: 'light'});
 }
@@ -632,6 +636,28 @@ export function clearChildrenLight(selectorOrOptions?: ApplyNodeSelector | Omit<
 
 
 
+// ─── Aliases ───
+export const apply = applyNode;
+export const node = applyNode;
+
+// ─── 편의 헬퍼 (selector/root 생략) ───
+
+export function applyThis(options?: ApplyNodeQueryOptions): MethodDecorator {
+  return applyNode('$this', options);
+}
+export function applyAppHost(options?: ApplyNodeQueryOptions): MethodDecorator {
+  return applyNode('$appHost', options);
+}
+export function applyLight(selector: string, options?: Omit<ApplyNodeQueryOptions, 'root'>): MethodDecorator {
+  return applyNode(selector, {...options ?? {}, root: 'light'});
+}
+export function applyShadow(selector: string, options?: Omit<ApplyNodeQueryOptions, 'root'>): MethodDecorator {
+  return applyNode(selector, {...options ?? {}, root: 'shadow'});
+}
+export function applyAll(selector: string, options?: Omit<ApplyNodeQueryOptions, 'root'>): MethodDecorator {
+  return applyNode(selector, {...options ?? {}, root: 'all'});
+}
+
 export const findAllApplyNodeMetadata = (target: any): Map<string | symbol, ApplyNodeMetadata> => {
   const result = new Map<string | symbol, ApplyNodeMetadata>();
   const maps = ReflectUtils.findAllMetadata<Map<string | symbol, ApplyNodeMetadata>>(APPLY_NODE_METADATA_KEY, target);
@@ -641,4 +667,56 @@ export const findAllApplyNodeMetadata = (target: any): Map<string | symbol, Appl
     }
   });
   return result;
-};
+};
+// ─── filter 유틸 (applyNode/replace*/innerHtml* options.filter용) ───
+// filter는 true 반환 시 적용, false 반환 시 스킵.
+
+const filterScopeOf = (target: HTMLElement | ShadowRoot): Element | null => {
+  if (target && typeof (target as HTMLElement).querySelector === 'function') {
+    return target as unknown as Element;
+  }
+  const host = (target as ShadowRoot)?.host as unknown as Element | undefined;
+  return host && typeof host.querySelector === 'function' ? host : null;
+};
+
+const tagNameOf = (node: any): string | null => {
+  const tag = node?.tagName;
+  return typeof tag === 'string' ? tag.toLowerCase() : null;
+};
+
+// 새 노드와 같은 태그가 target 안에 이미 있으면 스킵 (SSR adopting용).
+export const skipIfSameTagPresent = (target: HTMLElement | ShadowRoot, newValue: any): boolean => {
+  const nodes = (Array.isArray(newValue) ? newValue : [newValue]).filter((n) => tagNameOf(n) !== null);
+  if (nodes.length === 0) return true;
+  const scope = filterScopeOf(target);
+  if (!scope) return true;
+  return !nodes.some((n) => scope.querySelector(tagNameOf(n)!));
+};
+
+// 지정 selector가 target 안에 이미 있으면 스킵 (같은 path 쿼리 변경 시 페이지 재생성 방지용).
+// 사용: @innerHtmlLight({ filter: skipIfExists('center-math-page') })
+export const skipIfExists = (selector: string) =>
+  (target: HTMLElement | ShadowRoot): boolean => {
+    const scope = filterScopeOf(target);
+    if (!scope) return true;
+    return !scope.querySelector(selector);
+  };
+
+// 새 값이 비어있으면 스킵 (null/''/빈 배열).
+export const skipIfEmpty = (_target: HTMLElement | ShadowRoot, newValue: any): boolean => {
+  if (newValue === null || newValue === undefined || newValue === false) return false;
+  if (typeof newValue === 'string') return newValue.trim().length > 0;
+  if (Array.isArray(newValue)) return newValue.length > 0;
+  return true;
+};
+
+// 텍스트가 달라질 때만 적용 (폴링 갱신용).
+export const applyIfChanged = (target: HTMLElement | ShadowRoot, newValue: any): boolean => {
+  const textOf = (v: any): string => {
+    if (typeof v === 'string') return v;
+    if (Array.isArray(v)) return v.map(textOf).join('');
+    return typeof v?.textContent === 'string' ? v.textContent : '';
+  };
+  const current = typeof (target as HTMLElement)?.textContent === 'string' ? (target as HTMLElement).textContent! : '';
+  return current !== textOf(newValue);
+};

package/src/decorators/applyProperty.ts

@@ -1,40 +1,31 @@
 import { ReflectUtils } from '@dooboostore/core';
 import { ensureInit, getElementConfig } from './elementDefine';
 import { SwcUtils } from '../utils/Utils';
-import { SwcQueryOptions, HelperHostSet } from '../types';
+import { SwcQueryOptions, HelperHostSet, SwcFnSelector, SwcSelector } from '../types';
 
-export interface PropertyOptions extends SwcQueryOptions {
+// 공통 옵션 — root 없음
+export interface PropertyBaseOptions {
   name?: string | symbol;
   filter?: (target: HTMLElement, value: any, meta: {currentThis: any, helper: HelperHostSet}) => boolean;
-  /**
-   * Custom key to extract value from return object.
-   * If not provided, uses PROPERTY_METADATA_KEY by default.
-   * Useful when multiple @setProperty decorators are on the same method.
-   * 
-   * Example:
-   * @setProperty('selector1', { valueKey: 'prop1' })
-   * @setProperty('selector2', { valueKey: 'prop2' })
-   * myMethod() {
-   *   return {
-   *     prop1: 'value1',
-   *     prop2: 'value2'
-   *   };
-   * }
-   * 
-   * Or with symbols:
-   * @setProperty('selector1', { valueKey: Symbol.for('prop1') })
-   * @setProperty('selector2', { valueKey: Symbol.for('prop2') })
-   * myMethod() {
-   *   return {
-   *     [Symbol.for('prop1')]: 'value1',
-   *     [Symbol.for('prop2')]: 'value2'
-   *   };
-   * }
-   */
   valueKey?: symbol | string;
+  /** 읽기 방식: 'get' 타깃 프로퍼티 읽기 (기본), 'call' 타깃 호출 후 리턴 사용 */
+  getType?: 'get' | 'call';
+  /** 쓰기 방식: 'set' 타깃 프로퍼티 대입 (기본), 'call' 타깃 호출 (배열이면 spread) */
+  setType?: 'set' | 'call';
 }
 
-export type PropertySelector = string | ((currentThis: any, helper: HelperHostSet) => NodeList | Element | Element[] | null);
+// 문자열 셀렉터 전용 — root 허용
+export type PropertyQueryOptions = PropertyBaseOptions & SwcQueryOptions;
+// 함수 셀렉터 전용 — root 금지
+export type PropertyNonQueryOptions = PropertyBaseOptions;
+// 내부 저장/해석용 — root optional이라 두 종류 모두 저장 가능
+export type PropertyOptions = PropertyQueryOptions;
+
+export type PropertyFnSelector = SwcFnSelector;
+export type PropertySelector = SwcSelector;
+
+// 셀렉터 종류에 따라 옵션 타입 분기
+export type PropertyOptionsOf<S extends PropertySelector> = S extends string ? PropertyQueryOptions : PropertyNonQueryOptions;
 
 export interface PropertyMetadata {
   propertyKey: string | symbol;
@@ -62,7 +53,7 @@ export const resolvePropertyTargets = (inst: any, selector: PropertySelector, op
   const results: any[] = [];
 
   // Resolve selector if it's a function
-  let resolvedSelector: string | Element | NodeList | Element[] | null = selector as any;
+  let resolvedSelector: string | Node | Element | NodeList | Element[] | null = selector as any;
   if (typeof selector === 'function') {
     const hostSet = SwcUtils.getHelperAndHostSet(currentWin, inst);
     resolvedSelector = selector(inst, hostSet);
@@ -146,9 +137,9 @@ export const resolvePropertyTargets = (inst: any, selector: PropertySelector, op
  * - @applyProperty((this, helper) => 'selector', 'propertyName') - Function-based selector
  * - Return null/undefined to skip setting
  */
-export function applyProperty(selector: PropertySelector, targetPropertyKey: string | symbol, options?: PropertyOptions): MethodDecorator & PropertyDecorator;
-export function applyProperty(selector: PropertySelector, options?: PropertyOptions): MethodDecorator & PropertyDecorator;
-export function applyProperty(selector: PropertySelector, targetPropertyKeyOrOptions?: string | symbol | PropertyOptions, options?: PropertyOptions): MethodDecorator & PropertyDecorator {
+export function applyProperty<S extends PropertySelector>(selector: S, targetPropertyKey: string | symbol, options?: PropertyOptionsOf<S>): MethodDecorator & PropertyDecorator;
+export function applyProperty<S extends PropertySelector>(selector: S, options?: PropertyOptionsOf<S>): MethodDecorator & PropertyDecorator;
+export function applyProperty(selector: PropertySelector, targetPropertyKeyOrOptions?: string | symbol | PropertyOptions, options?: PropertyOptions): MethodDecorator {
   return (target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor) => {
     // ensureInit(target as any);
     
@@ -186,7 +177,7 @@ export function applyProperty(selector: PropertySelector, targetPropertyKeyOrOpt
       type: metaType
     });
 
-    // Helper: apply resolved value to targets
+    // Helper: apply resolved value to targets (setType 'call'이면 타깃 호출 — 배열은 spread)
     const applyValueToTargets = (inst: any, resolvedValue: any) => {
       if (resolvedValue === undefined) return resolvedValue;
 
@@ -202,6 +193,12 @@ export function applyProperty(selector: PropertySelector, targetPropertyKeyOrOpt
         }
 
         const resolvedRes = typeof resolvedValue === 'function' ? (resolvedValue as any)(targetEl, hostSet) : resolvedValue;
+        if (finalOptions.setType === 'call') {
+          if (typeof (targetEl as any)[targetPropertyKey] !== 'function') return;
+          if (Array.isArray(resolvedRes)) (targetEl as any)[targetPropertyKey].apply(targetEl, resolvedRes);
+          else (targetEl as any)[targetPropertyKey].call(targetEl, resolvedRes);
+          return;
+        }
         (targetEl as any)[targetPropertyKey] = resolvedRes;
       });
 
@@ -274,7 +271,12 @@ export function applyProperty(selector: PropertySelector, targetPropertyKeyOrOpt
           return true;
         });
 
-        const values = filtered.map(el => (el as any)[targetPropertyKey]);
+        const values = filtered.map(el => {
+          const raw = (el as any)[targetPropertyKey];
+          // getType 'call'이면 타깃 호출 후 리턴 사용
+          if (finalOptions.getType === 'call' && typeof raw === 'function') return raw.call(el);
+          return raw;
+        });
         return values.length === 1 ? values[0] : values;
       },
       set(this: any, value: any) {
@@ -301,19 +303,28 @@ export function applyProperty(selector: PropertySelector, targetPropertyKeyOrOpt
  * 
  * Note: This decorator is for FIELDS ONLY. For methods, use @setProperty.
  */
+export function property(selector: string, targetPropertyKey: string | symbol, options?: PropertyQueryOptions): PropertyDecorator;
+export function property(selector: PropertyFnSelector, targetPropertyKey: string | symbol, options?: PropertyNonQueryOptions): PropertyDecorator;
+export function property(selector: string, options?: PropertyQueryOptions): PropertyDecorator;
+export function property(selector: PropertyFnSelector, options?: PropertyNonQueryOptions): PropertyDecorator;
 export function property(target: Object, propertyKey: string | symbol): void;
 export function property(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
-export function property(selector: PropertySelector, targetPropertyKey: string | symbol, options?: PropertyOptions): PropertyDecorator;
-export function property(selector: PropertySelector, options?: PropertyOptions): PropertyDecorator;
 export function property(selectorOrTarget?: PropertySelector | Object, targetPropertyKeyOrOptions?: any, optionsOrDescriptor?: any): any {
-  // Bare decorator: @property
-  if (optionsOrDescriptor !== undefined && (typeof targetPropertyKeyOrOptions === 'string' || typeof targetPropertyKeyOrOptions === 'symbol')) {
+  // Bare decorator direct invocation: @property on field/method passes (target, key[, descriptor]).
+  // NOTE: (selector-string, key, options) factory form must NOT enter here — target is never string/function.
+  if (optionsOrDescriptor !== undefined
+    && typeof selectorOrTarget !== 'string' && typeof selectorOrTarget !== 'function'
+    && (typeof targetPropertyKeyOrOptions === 'string' || typeof targetPropertyKeyOrOptions === 'symbol')) {
     return applyProperty('$this', undefined as any, {})(selectorOrTarget as Object, targetPropertyKeyOrOptions, optionsOrDescriptor as PropertyDescriptor);
   }
   // With selector
   if (typeof selectorOrTarget === 'string') {
     return applyProperty(selectorOrTarget, targetPropertyKeyOrOptions as any, optionsOrDescriptor as PropertyOptions);
   }
+  // Function selector
+  if (typeof selectorOrTarget === 'function') {
+    return applyProperty(selectorOrTarget as PropertyFnSelector, targetPropertyKeyOrOptions as any, optionsOrDescriptor as PropertyOptions);
+  }
   // Without selector (defaults to $this)
   return applyProperty('$this', undefined as any, selectorOrTarget as PropertyOptions);
 }
@@ -336,17 +347,69 @@ export function property(selectorOrTarget?: PropertySelector | Object, targetPro
  *   return true;
  * }
  */
-export function setProperty(selector: PropertySelector, targetPropertyKey: string | symbol, options?: PropertyOptions): MethodDecorator;
-export function setProperty(selector: PropertySelector, options?: PropertyOptions): MethodDecorator;
+export function setProperty(selector: string, targetPropertyKey: string | symbol, options?: PropertyQueryOptions): MethodDecorator;
+export function setProperty(selector: PropertyFnSelector, targetPropertyKey: string | symbol, options?: PropertyNonQueryOptions): MethodDecorator;
+export function setProperty(selector: string, options?: PropertyQueryOptions): MethodDecorator;
+export function setProperty(selector: PropertyFnSelector, options?: PropertyNonQueryOptions): MethodDecorator;
 export function setProperty(selectorOrOptions?: PropertySelector | PropertyOptions, targetPropertyKeyOrOptions?: any, optionsOrUndefined?: PropertyOptions): MethodDecorator {
   // With selector
   if (typeof selectorOrOptions === 'string') {
     return applyProperty(selectorOrOptions, targetPropertyKeyOrOptions as any, optionsOrUndefined as PropertyOptions) as MethodDecorator;
   }
+  // Function selector
+  if (typeof selectorOrOptions === 'function') {
+    return applyProperty(selectorOrOptions as PropertyFnSelector, targetPropertyKeyOrOptions as any, optionsOrUndefined as PropertyOptions) as MethodDecorator;
+  }
   // Without selector (defaults to $this)
   return applyProperty('$this', undefined as any, selectorOrOptions as PropertyOptions) as MethodDecorator;
 }
 
+/**
+ * @callProperty - Method decorator for calling a method on matched elements.
+ * - @callProperty('selector', 'methodName') - 메서드 리턴값으로 타깃 메서드 호출
+ * - @callProperty('selector') - 메서드 이름과 같은 타깃 메서드 호출
+ * - 리턴값이 배열이면 spread 인자로 호출, 아니면 단일 인자로 호출
+ *
+ * Example:
+ * @event('#popup', 'open-request')
+ * @callProperty('#popup', 'show')
+ * onPopupOpen() {
+ *   return [this.rows]; // popup.show(this.rows)
+ * }
+ */
+export function callProperty(selector: string, targetMethodKey?: string | symbol, options?: PropertyQueryOptions): MethodDecorator;
+export function callProperty(selector: PropertyFnSelector, targetMethodKey?: string | symbol, options?: PropertyNonQueryOptions): MethodDecorator;
+export function callProperty(selector: string, options?: PropertyQueryOptions): MethodDecorator;
+export function callProperty(selectorOrTarget?: PropertySelector | PropertyOptions, targetMethodKeyOrOptions?: any, optionsOrUndefined?: PropertyOptions): MethodDecorator {
+  // setType 'call' 위임 — 메서드 리턴값을 타깃 메서드 호출로 전달 (배열이면 spread)
+  if (typeof selectorOrTarget === 'string' || typeof selectorOrTarget === 'function') {
+    if (typeof targetMethodKeyOrOptions === 'string' || typeof targetMethodKeyOrOptions === 'symbol') {
+      return applyProperty(selectorOrTarget as any, targetMethodKeyOrOptions, { ...optionsOrUndefined ?? {}, setType: 'call' }) as MethodDecorator;
+    }
+    return applyProperty(selectorOrTarget as any, { ...optionsOrUndefined ?? targetMethodKeyOrOptions ?? {}, setType: 'call' }) as MethodDecorator;
+  }
+  return applyProperty('$this', undefined as any, { ...selectorOrTarget ?? {}, setType: 'call' }) as MethodDecorator;
+}
+export function callPropertyLight(selector: string, targetMethodKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator;
+export function callPropertyLight(selector: string, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator;
+export function callPropertyLight(selector: string, targetMethodKeyOrOptions?: any, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator {
+  if (targetMethodKeyOrOptions != null && typeof targetMethodKeyOrOptions !== 'string' && typeof targetMethodKeyOrOptions !== 'symbol') {
+    return callProperty(selector, undefined, { ...targetMethodKeyOrOptions ?? {}, root: 'light' });
+  }
+  return callProperty(selector, targetMethodKeyOrOptions as any, { ...options ?? {}, root: 'light' });
+}
+export function callPropertyShadow(selector: string, targetMethodKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator;
+export function callPropertyShadow(selector: string, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator;
+export function callPropertyShadow(selector: string, targetMethodKeyOrOptions?: any, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator {
+  if (targetMethodKeyOrOptions != null && typeof targetMethodKeyOrOptions !== 'string' && typeof targetMethodKeyOrOptions !== 'symbol') {
+    return callProperty(selector, undefined, { ...targetMethodKeyOrOptions ?? {}, root: 'shadow' });
+  }
+  return callProperty(selector, targetMethodKeyOrOptions as any, { ...options ?? {}, root: 'shadow' });
+}
+export function callPropertyAll(selector: string, targetMethodKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator {
+  return callProperty(selector, targetMethodKey as any, { ...options ?? {}, root: 'all' });
+}
+
 // ============================================
 // Metadata Helpers
 // ============================================
@@ -365,5 +428,54 @@ export const findAllPropertyApplyMetadata = (target: any): Map<string | symbol,
   return result;
 };
 
+// ─── Aliases ───
+// property(필드) / setProperty(메서드)와 구분되는 일반 데코레이터 단축명
+export const prop = applyProperty;
+
+// ─── 편의 헬퍼 (selector/root 생략) ───
+
+export function propThis(targetPropertyKey?: string | symbol, options?: PropertyQueryOptions): MethodDecorator {
+  return applyProperty('$this', targetPropertyKey, options);
+}
+export function propAppHost(targetPropertyKey?: string | symbol, options?: PropertyQueryOptions): MethodDecorator {
+  return applyProperty('$appHost', targetPropertyKey, options);
+}
+export function propWindow(targetPropertyKey?: string | symbol, options?: PropertyQueryOptions): MethodDecorator {
+  return applyProperty('$window', targetPropertyKey, options);
+}
+export function propDocument(targetPropertyKey?: string | symbol, options?: PropertyQueryOptions): MethodDecorator {
+  return applyProperty('$document', targetPropertyKey, options);
+}
+export function propLight(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator {
+  return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'light'});
+}
+export function propShadow(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator {
+  return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'shadow'});
+}
+export function propAll(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator {
+  return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'all'});
+}
+
+// ─── setProperty root 별칭 (메서드 리턴값 → 타깃 프로퍼티) ───
+export function setPropertyLight(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator {
+  return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'light'});
+}
+export function setPropertyShadow(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator {
+  return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'shadow'});
+}
+export function setPropertyAll(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): MethodDecorator {
+  return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'all'});
+}
+
+// ─── property root 별칭 (필드 프록시) ───
+export function propertyLight(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): PropertyDecorator {
+  return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'light'});
+}
+export function propertyShadow(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): PropertyDecorator {
+  return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'shadow'});
+}
+export function propertyAll(selector: string, targetPropertyKey?: string | symbol, options?: Omit<PropertyQueryOptions, 'root'>): PropertyDecorator {
+  return applyProperty(selector, targetPropertyKey, {...options ?? {}, root: 'all'});
+}
 
 export default applyProperty;