@dooboostore/simple-web-component 1.0.43 → 1.0.45

package/src/decorators/applyNode.ts

@@ -13,7 +13,9 @@ 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 type ApplyNodeSelector = string | ((currentThis: any, helper: HelperHostSet) => NodeList | Element | Element[] | null);
 
 export interface ApplyNodeOptions {
   position?: ApplyNodePosition;
@@ -37,12 +39,39 @@ export interface ApplyNodeOptions {
 
 export interface ApplyNodeMetadata {
   propertyKey: string | symbol;
-  selector: string;
+  selector: ApplyNodeSelector;
   options: ApplyNodeOptions;
 }
 
 export const APPLY_NODE_METADATA_KEY = Symbol.for('simple-web-component:apply-node');
 
+/**
+ * Resolve selector to string or elements
+ * Handles function-based selectors and returns elements if applicable
+ */
+const resolveSelector = (selector: ApplyNodeSelector, inst: any, win: Window): string | HTMLElement | null => {
+  if (typeof selector === 'function') {
+    const hostSet = SwcUtils.getHelperAndHostSet(win, inst);
+    const result = selector(inst, hostSet);
+    
+    if (result instanceof win.Element) {
+      return result as HTMLElement;
+    }
+    if (result instanceof win.NodeList) {
+      return result.length > 0 ? (result[0] as HTMLElement) : null;
+    }
+    if (Array.isArray(result)) {
+      return result.length > 0 ? (result[0] as HTMLElement) : null;
+    }
+    if (result === null) {
+      return null;
+    }
+    // result must be a string at this point
+    return result as unknown as string;
+  }
+  return selector as string;
+};
+
 // const normalizeNodes = (res: any, doc: Document): Node[] => {
 //   const items = Array.isArray(res) ? res : [res];
 //   return items.map(it => {
@@ -53,11 +82,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') {
@@ -70,8 +105,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') {
@@ -101,8 +134,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: ApplyNodeSelector, options?: ApplyNodeOptions): MethodDecorator;
+export function applyNode(options: ApplyNodeOptions): MethodDecorator;
+export function applyNode(selectorOrOptions: ApplyNodeSelector | ApplyNodeOptions, maybeOptions?: ApplyNodeOptions): MethodDecorator {
+  // Determine selector and options based on overload
+  let selector: ApplyNodeSelector;
+  let options: ApplyNodeOptions;
+
+  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
+    // 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>;
@@ -132,15 +185,29 @@ export function applyNode(selector: string, options: ApplyNodeOptions = {positio
           return t;
         };
 
-        if (selector === '$this') return applyRoot(this);
-        if (selector === '$host') return applyRoot(hostSet.$host);
-        if (selector === '$parentHost') return applyRoot(hostSet.$parentHost);
-        if (selector === '$appHost') return applyRoot(hostSet.$appHost);
-        if (selector === '$firstHost') return applyRoot(hostSet.$firstHost);
-        if (selector === '$lastHost') return applyRoot(hostSet.$lastHost);
+        // Resolve selector if it's a function
+        const resolved = resolveSelector(selector, this, currentWin);
+        
+        // If selector function returned an element directly, use it
+        if (resolved instanceof currentWin.Element) {
+          return applyRoot(resolved);
+        }
+        if (resolved === null) {
+          return null;
+        }
+
+        // Handle string selector
+        const stringSelector = resolved as string;
+
+        if (stringSelector === '$this') return applyRoot(this);
+        if (stringSelector === '$host') return applyRoot(hostSet.$host);
+        if (stringSelector === '$parentHost') return applyRoot(hostSet.$parentHost);
+        if (stringSelector === '$appHost') return applyRoot(hostSet.$appHost);
+        if (stringSelector === '$firstHost') return applyRoot(hostSet.$firstHost);
+        if (stringSelector === '$lastHost') return applyRoot(hostSet.$lastHost);
 
         const targetRoot = applyRoot(this);
-        return targetRoot ? targetRoot.querySelector(selector) : null;
+        return targetRoot ? targetRoot.querySelector(stringSelector) : null;
       };
 
       const targetEl = getTarget();
@@ -199,137 +266,370 @@ export function applyNode(selector: string, options: ApplyNodeOptions = {positio
   };
 }
 
-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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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: ApplyNodeSelector, 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?: ApplyNodeSelector | 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' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as ApplyNodeSelector, {...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);