@dooboostore/simple-web-component 1.0.42 → 1.0.44

package/src/decorators/applyNode.ts

@@ -13,7 +13,7 @@ import {ElementApply} from "@dooboostore/core-web";
 </p>
 <!-- afterend -->
  */
-export type ApplyNodePosition = 'beforeBegin' | 'afterBegin' | 'beforeEnd' | 'afterEnd' | 'replace' | 'replaceChildren' | 'innerHtml' | 'innerText' | 'remove';
+export type ApplyNodePosition = 'beforeBegin' | 'afterBegin' | 'beforeEnd' | 'afterEnd' | 'replace' | 'replaceChildren' | 'innerHtml' | 'innerText' | 'remove' | 'clearChildren';
 
 export interface ApplyNodeOptions {
   position?: ApplyNodePosition;
@@ -27,6 +27,12 @@ export interface ApplyNodeOptions {
    * 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;
 }
 
 export interface ApplyNodeMetadata {
@@ -47,11 +53,17 @@ export const APPLY_NODE_METADATA_KEY = Symbol.for('simple-web-component:apply-no
 
 const applyToDom = (currentThis: any, targetEl: HTMLElement, res: Node | string, pos: ApplyNodePosition, win: Window, host?: any) => {
   if (!targetEl) return;
+  
+  // Handle clearChildren - ignore return value and always clear
+  if (pos === 'clearChildren') {
+    targetEl.replaceChildren();
+    return [];
+  }
+  
   const doc = win.document;
   const hostSet = SwcUtils.getHelperAndHostSet(win, currentThis);
   const id = currentThis._swcId;
 
-
   const nodes: Node[] = [];
 
   if (typeof res === 'string' && pos === 'innerHtml') {
@@ -64,8 +76,6 @@ const applyToDom = (currentThis: any, targetEl: HTMLElement, res: Node | string,
 
   SwcUtils.projectProcessHtml(id, nodes, doc);
 
-
-
   const isShadowRoot = targetEl instanceof win.ShadowRoot;
   // const nodes = normalizeNodes(res, doc);
   if (pos === 'replace') {
@@ -95,8 +105,28 @@ const applyToDom = (currentThis: any, targetEl: HTMLElement, res: Node | string,
 
 /**
  * @applyNode decorator to surgically add/replace nodes to a target element.
+ * 
+ * Overloads:
+ * - applyNode(selector, options) - Apply to specific selector
+ * - applyNode(options) - Apply to $this (current element)
  */
-export function applyNode(selector: string, options: ApplyNodeOptions = {position: 'replaceChildren'}): MethodDecorator {
+export function applyNode(selector: string, options?: ApplyNodeOptions): MethodDecorator;
+export function applyNode(options: ApplyNodeOptions): MethodDecorator;
+export function applyNode(selectorOrOptions: string | ApplyNodeOptions, maybeOptions?: ApplyNodeOptions): MethodDecorator {
+  // Determine selector and options based on overload
+  let selector: string;
+  let options: ApplyNodeOptions;
+
+  if (typeof selectorOrOptions === 'string') {
+    // First overload: applyNode(selector, options)
+    selector = selectorOrOptions;
+    options = maybeOptions || {position: 'replaceChildren'};
+  } else {
+    // Second overload: applyNode(options) - default to $this
+    selector = '$this';
+    options = selectorOrOptions || {position: 'replaceChildren'};
+  }
+
   return (targetObj: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
     const constructor = targetObj.constructor;
     let metaList = ReflectUtils.getOwnMetadata(APPLY_NODE_METADATA_KEY, constructor) as Map<string | symbol, ApplyNodeMetadata>;
@@ -140,6 +170,22 @@ export function applyNode(selector: string, options: ApplyNodeOptions = {positio
       const targetEl = getTarget();
       const res = original.apply(this, args);
 
+      /**
+       * Extract value for this decorator from method return value
+       * 
+       * If return value is an object with this decorator's key,
+       * use that value. Otherwise use the entire return value.
+       * 
+       * Uses valueKey from options if provided, otherwise uses APPLY_NODE_METADATA_KEY.
+       */
+      const extractValue = (v: any) => {
+        const keyToUse = options.valueKey ?? APPLY_NODE_METADATA_KEY;
+        if (v && typeof v === 'object' && keyToUse in v) {
+          return v[keyToUse];
+        }
+        return v;
+      };
+
       const runApply = (target: any, val: any) => {
         const pos = options.position || 'beforeEnd';
         // Delegate HTML/node processing to applyToDom which centralizes
@@ -163,149 +209,384 @@ export function applyNode(selector: string, options: ApplyNodeOptions = {positio
 
       if (res instanceof Promise) {
         return res.then(finalRes => {
+          const extracted = extractValue(finalRes);
           fallbackNodes.forEach((it: any)=>it.remove());
-          if (finalRes !== undefined && targetEl) runApply(targetEl, finalRes);
+          if (extracted !== undefined && targetEl) runApply(targetEl, extracted);
           return finalRes;
         });
       } else {
-        if (res !== undefined && targetEl) runApply(targetEl, res);
+        const extracted = extractValue(res);
+        if (extracted !== undefined && targetEl) runApply(targetEl, extracted);
         return res;
       }
     };
   };
 }
 
-export function applyNodeThis(options: ApplyNodeOptions): MethodDecorator;
-export function applyNodeThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
-export function applyNodeThis(targetOrOptions?: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): any {
-  const option: ApplyNodeOptions = {position: 'replaceChildren'};
-  if (propertyKey !== undefined) return applyNode('$this', option)(targetOrOptions, propertyKey, descriptor);
-  const opt = targetOrOptions || {};
-  return applyNode('$this', {...option, ...opt});
-}
+// --- Overloaded convenience functions for common patterns ---
 
-export function replaceChildrenNodeThis(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
-export function replaceChildrenNodeThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
-export function replaceChildrenNodeThis(targetOrOptions?: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): any {
-  const option: ApplyNodeOptions = {position: 'replaceChildren'};
-  if (propertyKey !== undefined) return applyNode('$this', option)(targetOrOptions, propertyKey, descriptor);
-  const opt = targetOrOptions || {};
-  return applyNode('$this', {...opt, ...option});
+/**
+ * @replaceChildrenNode decorator - replaces children of target element
+ * 
+ * Overloads:
+ * - replaceChildrenNode(selector, options) - Replace children of specific selector
+ * - replaceChildrenNode(options) - Replace children of $this (current element)
+ * - @replaceChildrenNode - Bare decorator, replaces children of $this
+ */
+export function replaceChildren(selector: string, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function replaceChildren(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function replaceChildren(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function replaceChildren(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @replaceChildrenNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'replaceChildren'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'replaceChildren'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'replaceChildren'});
 }
 
+/**
+ * @clearChildrenNode decorator - clears all children of target element
+ * 
+ * Overloads:
+ * - clearChildrenNode(selector, options) - Clear children of specific selector
+ * - clearChildrenNode(options) - Clear children of $this (current element)
+ * - @clearChildrenNode - Bare decorator, clears children of $this
+ */
+export function clearChildrenNode(selector: string, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function clearChildrenNode(options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function clearChildrenNode(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function clearChildrenNode(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @clearChildrenNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'clearChildren'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'clearChildren'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'clearChildren'});
+}
 
+// Alias for clearChildrenNode
+export const clearNode = clearChildrenNode;
 
-export function beforeEndNodeThis(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
-export function beforeEndNodeThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
-export function beforeEndNodeThis(targetOrOptions?: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): any {
-  const options: ApplyNodeOptions = {position: 'beforeEnd'};
-  if (propertyKey !== undefined) return applyNode('$this', options)(targetOrOptions, propertyKey, descriptor);
-  const opt = targetOrOptions || {};
-  return applyNode('$this', {...opt, ...options});
+/**
+ * @innerHtmlNode decorator - sets innerHTML of target element
+ * 
+ * Overloads:
+ * - innerHtmlNode(selector, options) - Set innerHTML of specific selector
+ * - innerHtmlNode(options) - Set innerHTML of $this (current element)
+ * - @innerHtmlNode - Bare decorator, sets innerHTML of $this
+ */
+export function innerHtml(selector: string, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function innerHtml(options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function innerHtml(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function innerHtml(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @innerHtmlNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'innerHtml'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'innerHtml'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'innerHtml'});
 }
 
-export function beforeEndLightNodeThis(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function beforeEndLightNodeThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
-export function beforeEndLightNodeThis(targetOrOptions?: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): any {
-  const option: ApplyNodeOptions = {position: 'beforeEnd', root: 'light'}
-  if (propertyKey !== undefined) return applyNode('$this', option)(targetOrOptions, propertyKey, descriptor);
-  const opt = targetOrOptions || {};
-  return applyNode('$this', {...opt, ...option});
-}
+// Alias for innerHtmlNode
+// export const setHtmlNode = innerHtml;
 
-export function beforeEndShadowNodeThis(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function beforeEndShadowNodeThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
-export function beforeEndShadowNodeThis(targetOrOptions?: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): any {
-  const option: ApplyNodeOptions = {position: 'beforeEnd', root: 'shadow'}
-  if (propertyKey !== undefined) return applyNode('$this', option)(targetOrOptions, propertyKey, descriptor);
-  const opt = targetOrOptions || {};
-  return applyNode('$this', {...opt, ...option});
+/**
+ * @innerHtmlLightNode decorator - sets innerHTML of light DOM element
+ * 
+ * Overloads:
+ * - innerHtmlLightNode(selector, options) - Set innerHTML of specific selector in light DOM
+ * - innerHtmlLightNode(options) - Set innerHTML of $this in light DOM
+ * - @innerHtmlLightNode - Bare decorator, sets innerHTML of $this in light DOM
+ */
+export function innerHtmlLight(selector: string, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function innerHtmlLight(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function innerHtmlLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function innerHtmlLight(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @innerHtmlLightNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'innerHtml', root: 'light'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerHtml', root: 'light'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerHtml', root: 'light'});
 }
 
-export function afterBeginNodeThis(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
-export function afterBeginNodeThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
-export function afterBeginNodeThis(targetOrOptions?: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): any {
-  const option: ApplyNodeOptions = {position: 'afterBegin'};
-  if (propertyKey !== undefined) return applyNode('$this', option)(targetOrOptions, propertyKey, descriptor);
-  const opt = targetOrOptions || {};
-  return applyNode('$this', {...opt, ...option});
-}
 
-export function afterBeginLightNodeThis(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function afterBeginLightNodeThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
-export function afterBeginLightNodeThis(targetOrOptions?: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): any {
-  const option: ApplyNodeOptions = {position: 'afterBegin', root: 'light'}
-  if (propertyKey !== undefined) return applyNode('$this', option)(targetOrOptions, propertyKey, descriptor);
-  const opt = targetOrOptions || {};
-  return applyNode('$this', {...opt, ...option});
+/**
+ * @innerHtmlShadowNode decorator - sets innerHTML of shadow DOM element
+ * 
+ * Overloads:
+ * - innerHtmlShadowNode(selector, options) - Set innerHTML of specific selector in shadow DOM
+ * - innerHtmlShadowNode(options) - Set innerHTML of $this in shadow DOM
+ * - @innerHtmlShadowNode - Bare decorator, sets innerHTML of $this in shadow DOM
+ */
+export function innerHtmlShadow(selector: string, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function innerHtmlShadow(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function innerHtmlShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function innerHtmlShadow(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @innerHtmlShadowNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'innerHtml', root: 'shadow'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerHtml', root: 'shadow'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerHtml', root: 'shadow'});
 }
 
-export function innerHtmlNodeThis(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
-export function innerHtmlNodeThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
-export function innerHtmlNodeThis(targetOrOptions?: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): any {
-  const option: ApplyNodeOptions = {position: 'innerHtml'}
-  if (propertyKey !== undefined) return applyNode('$this', option)(targetOrOptions, propertyKey, descriptor);
-  const opt = targetOrOptions || {};
-  return applyNode('$this', {...opt, ...option});
-}
 
-export function innerTextNodeThis(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
-export function innerTextNodeThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
-export function innerTextNodeThis(targetOrOptions?: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): any {
-  const option: ApplyNodeOptions = {position: 'innerText'}
-  if (propertyKey !== undefined) return applyNode('$this', option)(targetOrOptions, propertyKey, descriptor);
-  const opt = targetOrOptions || {};
-  return applyNode('$this', {...opt, ...option});
+/**
+ * @innerTextNode decorator - sets innerText of target element
+ * 
+ * Overloads:
+ * - innerTextNode(selector, options) - Set innerText of specific selector
+ * - innerTextNode(options) - Set innerText of $this (current element)
+ * - @innerTextNode - Bare decorator, sets innerText of $this
+ */
+export function innerText(selector: string, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function innerText(options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function innerText(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function innerText(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @innerTextNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'innerText'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'innerText'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'innerText'});
 }
 
-export function innerHtmlLightNodeThis(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function innerHtmlLightNodeThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
-export function innerHtmlLightNodeThis(targetOrOptions?: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): any {
-  const option: ApplyNodeOptions = {position: 'innerHtml', root: 'light'};
-  if (propertyKey !== undefined) return applyNode('$this', option)(targetOrOptions, propertyKey, descriptor);
-  const opt = targetOrOptions || {};
-  return applyNode('$this', {...opt, ...option});
+
+/**
+ * @innerTextLightNode decorator - sets innerText of light DOM element
+ * 
+ * Overloads:
+ * - innerTextLightNode(selector, options) - Set innerText of specific selector in light DOM
+ * - innerTextLightNode(options) - Set innerText of $this in light DOM
+ * - @innerTextLightNode - Bare decorator, sets innerText of $this in light DOM
+ */
+export function innerTextLight(selector: string, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function innerTextLight(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function innerTextLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function innerTextLight(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @innerTextLightNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'innerText', root: 'light'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerText', root: 'light'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerText', root: 'light'});
 }
 
-export function replaceChildrenLightNodeThis(options: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
-export function replaceChildrenLightNodeThis(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): void;
-export function replaceChildrenLightNodeThis(targetOrOptions?: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor): any {
-  const option: ApplyNodeOptions = {position: 'replaceChildren', root: 'light'};
-  if (propertyKey !== undefined) return applyNode('$this', option)(targetOrOptions, propertyKey, descriptor);
-  const opt = targetOrOptions || {};
-  return applyNode('$this', {...opt, ...option});
+/**
+ * @innerTextShadowNode decorator - sets innerText of shadow DOM element
+ * 
+ * Overloads:
+ * - innerTextShadowNode(selector, options) - Set innerText of specific selector in shadow DOM
+ * - innerTextShadowNode(options) - Set innerText of $this in shadow DOM
+ * - @innerTextShadowNode - Bare decorator, sets innerText of $this in shadow DOM
+ */
+export function innerTextShadow(selector: string, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function innerTextShadow(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function innerTextShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function innerTextShadow(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @innerTextShadowNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'innerText', root: 'shadow'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerText', root: 'shadow'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'innerText', root: 'shadow'});
 }
 
-export function replaceChildrenNode(selector: string, options: Omit<ApplyNodeOptions, 'position'> = {}): MethodDecorator {
-  return applyNode(selector, {...options, position: 'replaceChildren'});
+/**
+ * @beforeEndNode decorator - appends nodes to target element
+ * 
+ * Overloads:
+ * - beforeEndNode(selector, options) - Append to specific selector
+ * - beforeEndNode(options) - Append to $this (current element)
+ * - @beforeEndNode - Bare decorator, appends to $this
+ */
+export function insertBeforeEnd(selector: string, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function insertBeforeEnd(options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function insertBeforeEnd(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function insertBeforeEnd(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @beforeEndNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'beforeEnd'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'beforeEnd'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'beforeEnd'});
 }
 
-export function innerHtmlNode(selector: string, options: Omit<ApplyNodeOptions, 'position'> = {}): MethodDecorator {
-  return applyNode(selector, {...options, position: 'innerHtml'});
+
+/**
+ * @beforeEndLightNode decorator - appends nodes to light DOM element
+ * 
+ * Overloads:
+ * - beforeEndLightNode(selector, options) - Append to specific selector in light DOM
+ * - beforeEndLightNode(options) - Append to $this in light DOM
+ * - @beforeEndLightNode - Bare decorator, appends to $this in light DOM
+ */
+export function insertBeforeEndLight(selector: string, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function insertBeforeEndLight(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function insertBeforeEndLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function insertBeforeEndLight(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @beforeEndLightNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'beforeEnd', root: 'light'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'beforeEnd', root: 'light'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'beforeEnd', root: 'light'});
 }
 
-export function innerHtmlLightNode(selector: string, options: Omit<ApplyNodeOptions, 'position' | 'root'> = {}): MethodDecorator {
-  return applyNode(selector, {...options, position: 'innerHtml', root: 'light'});
+
+/**
+ * @beforeEndShadowNode decorator - appends nodes to shadow DOM element
+ * 
+ * Overloads:
+ * - beforeEndShadowNode(selector, options) - Append to specific selector in shadow DOM
+ * - beforeEndShadowNode(options) - Append to $this in shadow DOM
+ * - @beforeEndShadowNode - Bare decorator, appends to $this in shadow DOM
+ */
+export function insertBeforeEndShadow(selector: string, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function insertBeforeEndShadow(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function insertBeforeEndShadow(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function insertBeforeEndShadow(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @beforeEndShadowNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'beforeEnd', root: 'shadow'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'beforeEnd', root: 'shadow'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'beforeEnd', root: 'shadow'});
 }
 
-export function innerHtmlShadowNode(selector: string, options: Omit<ApplyNodeOptions, 'position' | 'root'> = {}): MethodDecorator {
-  return applyNode(selector, {...options, position: 'innerHtml', root: 'shadow'});
+
+/**
+ * @afterBeginNode decorator - prepends nodes to target element
+ * 
+ * Overloads:
+ * - afterBeginNode(selector, options) - Prepend to specific selector
+ * - afterBeginNode(options) - Prepend to $this (current element)
+ * - @afterBeginNode - Bare decorator, prepends to $this
+ */
+export function insertAfterBegin(selector: string, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function insertAfterBegin(options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function insertAfterBegin(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function insertAfterBegin(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @afterBeginNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'afterBegin'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'afterBegin'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'afterBegin'});
 }
 
-export function innerTextNode(selector: string, options: Omit<ApplyNodeOptions, 'position'> = {}): MethodDecorator {
-  return applyNode(selector, {...options, position: 'innerText'});
+
+/**
+ * @afterBeginLightNode decorator - prepends nodes to light DOM element
+ * 
+ * Overloads:
+ * - afterBeginLightNode(selector, options) - Prepend to specific selector in light DOM
+ * - afterBeginLightNode(options) - Prepend to $this in light DOM
+ * - @afterBeginLightNode - Bare decorator, prepends to $this in light DOM
+ */
+export function insertAfterBeginLight(selector: string, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function insertAfterBeginLight(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function insertAfterBeginLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function insertAfterBeginLight(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @afterBeginLightNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'afterBegin', root: 'light'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'afterBegin', root: 'light'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'afterBegin', root: 'light'});
 }
 
-export function innerTextLightNode(selector: string, options: Omit<ApplyNodeOptions, 'position' | 'root'> = {}): MethodDecorator {
-  return applyNode(selector, {...options, position: 'innerText', root: 'light'});
+
+/**
+ * @replaceChildrenLightNode decorator - replaces children of light DOM element
+ * 
+ * Overloads:
+ * - replaceChildrenLightNode(selector, options) - Replace children of specific selector in light DOM
+ * - replaceChildrenLightNode(options) - Replace children of $this in light DOM
+ * - @replaceChildrenLightNode - Bare decorator, replaces children of $this in light DOM
+ */
+export function replaceChildrenLight(selector: string, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function replaceChildrenLight(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function replaceChildrenLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function replaceChildrenLight(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @replaceChildrenLightNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'replaceChildren', root: 'light'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'replaceChildren', root: 'light'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'replaceChildren', root: 'light'});
 }
 
-export function innerTextShadowNode(selector: string, options: Omit<ApplyNodeOptions, 'position' | 'root'> = {}): MethodDecorator {
-  return applyNode(selector, {...options, position: 'innerText', root: 'shadow'});
+/**
+ * @clearChildrenLightNode decorator - clears children of light DOM element
+ * 
+ * Overloads:
+ * - clearChildrenLightNode(selector, options) - Clear children of specific selector in light DOM
+ * - clearChildrenLightNode(options) - Clear children of $this in light DOM
+ * - @clearChildrenLightNode - Bare decorator, clears children of $this in light DOM
+ */
+export function clearChildrenLight(selector: string, options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function clearChildrenLight(options?: Omit<ApplyNodeOptions, 'position' | 'root'>): MethodDecorator;
+export function clearChildrenLight(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function clearChildrenLight(selectorOrOptions?: string | Omit<ApplyNodeOptions, 'position' | 'root'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position' | 'root'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  // Bare decorator usage: @clearChildrenLightNode
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'clearChildren', root: 'light'})(selectorOrOptions, maybeOptions, descriptor);
+  }
+  
+  if (typeof selectorOrOptions === 'string') {
+    return applyNode(selectorOrOptions, {...maybeOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'clearChildren', root: 'light'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position' | 'root'>, position: 'clearChildren', root: 'light'});
 }
 
 
 
+
 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);