@dooboostore/simple-web-component 1.0.34 → 1.0.36

package/src/elements/register.ts

@@ -1,4 +1,4 @@
-import { getElementConfig, elementDefine, attributeHost, changedAttributeHost, getAttributeValue } from '../decorators';
+import { getElementConfig, elementDefine, attributeThis, changedAttributeThis, getAttributeValue } from '../decorators';
 import { SwcAppMixin } from './SwcAppMixin';
 import { SwcUtils } from '../utils/Utils';
 import { FunctionUtils,ActionExpression } from '@dooboostore/core';
@@ -148,11 +148,17 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
 
     @elementDefine('swc-if', { extends: 'template', window: w })
   class SwcIf extends HTMLTemplateElement {
-  @attributeHost('value')
+  // id =
+  // @attributeThis('value')
   _value: any;
 
-  @attributeHost('replace-wrap')
-  _replaceWrap: string | null;
+  @attributeThis('replace-wrap-start')
+  _replaceWrapStart: string | null;
+  @attributeThis('replace-wrap-end')
+  _replaceWrapEnd: string | null;
+
+  @attributeThis('skip-if-same')
+  _skipIfSame: string | null;
 
   private _nodes: Node[] = [];
 
@@ -165,14 +171,37 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
     this.refresh(nv);
   }
 
-  private replaceExpressions(html: string, groupArgs: any, context: any, wrap?: string | null): string {
-    const config = wrap ? { wrapExpression: wrap } : undefined;
+  constructor() {
+    super();
+  }
+
+  @changedAttributeThis('value')
+  private setValue(value: any, o: string, n: string) {
+    this._value = value;
+    this.refresh(this._value);
+  }
+
+  // @changedAttributeThis('replace-wrap')
+  // private setReplaceWrap(replaceWrapAttr?: string | null) {
+  //   this.refresh();
+  // }
+
+  private replaceExpressions(html: string, groupArgs: any, context: any, wrap: {start: string, end: string}): string {
+    let config: any = undefined;
+    if (wrap) {
+      config = {
+        expression: {
+          replace: { start: `${wrap.start}`, end: `${wrap.end}` },
+          callReturn: { start: `${wrap.start}=`, end: `${wrap.end}` },
+          call: { start: `${wrap.start}@`, end: `${wrap.end}` }
+        }
+      };
+    }
     const ae = new ActionExpression(html, config);
-    const filterOptions = wrap ? { type: 'replace' as const, wrap } : 'replace';
     const win = this.ownerDocument?.defaultView || window;
-    
+
     // @ts-ignore
-    for (const expr of ae.getExpressions(filterOptions)) {
+    for (const expr of ae.getExpressions('replace')) {
       try {
         const value = FunctionUtils.executeReturn({
           script: ConvertUtils.decodeHtmlEntity(expr.script, win.document),
@@ -187,39 +216,47 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
     return ae.getUnprocessedTemplate();
   }
 
-  @changedAttributeHost('value')
-  private setValue(valueAttr?: string | null) {
-    this.refresh();
-  }
+  refresh(value?: any) {
+    const targetValue = value !== undefined ? value : (getAttributeValue(this, 'value') ?? this._value);
 
-  @changedAttributeHost('replace-wrap')
-  private setReplaceWrap(replaceWrapAttr?: string | null) {
-    this.refresh();
-  }
+    // skip-if-same 속성이 존재하고(true/빈 문자열), 이전 값과 새로운 값이 완전히 동일하면 렌더링 스킵!
+    if (this.hasAttribute('skip-if-same') && this._value === targetValue && this._nodes.length > 0) {
+      return;
+    }
 
-  refresh(value = this._value) {
     this.cleanup();
+    this._value = targetValue;
+
     const portal = this.parentElement;
-    if (!portal || !value) return;
+    if (!portal || !this._value) return;
 
     const win = this.ownerDocument?.defaultView || window;
     const helperSet = SwcUtils.getHelperAndHostSet(win, this);
 
     let htmlString = this.innerHTML;
-    const groupArgs = { ...helperSet, $value: value };
+    const groupArgs = { ...helperSet, $value: this._value, $templateHost: this };
 
-    htmlString = this.replaceExpressions(htmlString, groupArgs, this, this._replaceWrap);
+    htmlString = this.replaceExpressions(htmlString, groupArgs, this, {start:this._replaceWrapStart ?? '{#{', end: this._replaceWrapEnd ?? '}#}'});
 
     const result = this.ownerDocument?.createElement('template') || document.createElement('template');
     result.innerHTML = htmlString;
     const processedFragment = result.content;
 
     this._nodes = Array.from(processedFragment.childNodes);
+    this._nodes.forEach((node: any) => {
+      if (node instanceof HTMLElement) (node as any).__swc_template_host = this;
+    });
+
     portal.insertBefore(processedFragment, this.nextSibling);
   }
 
   private cleanup() {
-    this._nodes.forEach(n => n.parentElement?.removeChild(n));
+    this._nodes.forEach(n => {
+      const realNode = (n as any).__upgraded_instance || n;
+      if (realNode.parentElement) {
+        realNode.parentElement.removeChild(realNode);
+      }
+    });
     this._nodes = [];
   }
 
@@ -230,43 +267,64 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
 
     @elementDefine('swc-loop', { extends: 'template', window: w })
   class SwcLoop extends HTMLTemplateElement {
-  @attributeHost('value')
-  _value: any[];
+  _value: any[] = [];
 
-  @attributeHost('replace-wrap')
-  _replaceWrap: string | null;
+  @attributeThis('replace-wrap-start')
+  _replaceWrapStart: string | null;
+  @attributeThis('replace-wrap-end')
+  _replaceWrapEnd: string | null;
 
   private _nodeGroups: Node[][] = [];
 
   get value(): any[] {
     return this._value;
   }
+
   set value(nv: any[]) {
-    // this._value = Array.isArray(nv) ? [...nv] : [];
+    this._value = nv;
     this.refresh(nv);
   }
 
-  @changedAttributeHost('value')
-  private setValue() {
-    this.refresh();
+  getValue(index: number) {
+    return this._value?.[index];
   }
 
-  @changedAttributeHost('replace-wrap')
-  private setReplaceWrap() {
-    this.refresh();
+  constructor() {
+    super();
+    // console.log('swc SwcLoop constructor called!');
+    // console.log('swc SwcLoop', this.getAttribute('value'));
+  }
+
+  @changedAttributeThis('value')
+  private setValue(value: any, o: string, n: string) {
+    this._value = value;
+    this.refresh(this._value);
   }
 
-  private replaceExpressions(html: string, groupArgs: any, context: any, wrap?: string | null): string {
-    const config = wrap ? { wrapExpression: wrap } : undefined;
+  // @changedAttributeThis('replace-wrap')
+  // private setReplaceWrap(replaceWrapAttr?: string | null) {
+  //   this.refresh();
+  // }
+
+  private replaceExpressions(html: string, groupArgs: any, context: any, wrap: {start: string, end: string}): string {
+    let config: any = undefined;
+    config = {
+      expression: {
+        replace: { start: `${wrap.start}`, end: `${wrap.end}` },
+        callReturn: { start: `${wrap.start}=`, end: `${wrap.end}` },
+        call: { start: `${wrap.start}@`, end: `${wrap.end}` }
+      }
+    };
     const ae = new ActionExpression(html, config);
-    const filterOptions = wrap ? { type: 'replace' as const, wrap } : 'replace';
     const win = this.ownerDocument?.defaultView || window;
 
     // @ts-ignore
-    for (const expr of ae.getExpressions(filterOptions)) {
+    const expressions = ae.getExpressions('replace');
+    for (const expr of expressions) {
+      const script = ConvertUtils.decodeHtmlEntity(expr.script, win.document);
       try {
         const value = FunctionUtils.executeReturn({
-          script: ConvertUtils.decodeHtmlEntity(expr.script, win.document),
+          script: script,
           context,
           args: groupArgs
         });
@@ -278,35 +336,127 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
     return ae.getUnprocessedTemplate();
   }
 
-  refresh(value = this._value) {
-    this.cleanup();
-    if (value?.length<=0) return;
-    const portal = this.parentElement;
-    if (!portal) return;
-
+  private createFragmentAndNodes(items: any[], helperSet: any, startIndex: number = 0): { fragment: DocumentFragment; newNodesGroup: Node[][] } {
     const win = this.ownerDocument?.defaultView || window;
-    const helperSet = SwcUtils.getHelperAndHostSet(win, this);
     const fragment = win.document.createDocumentFragment();
+    const newNodesGroup: Node[][] = [];
 
-    value.forEach((item, index) => {
+    items.forEach((item, i) => {
+      const index = startIndex + i;
       let htmlString = this.innerHTML;
       const groupArgs = { ...helperSet, $item: item, $index: index, $value: this._value };
 
-      htmlString = this.replaceExpressions(htmlString, groupArgs, this, this._replaceWrap);
+      htmlString = this.replaceExpressions(htmlString, groupArgs, this, {start:this._replaceWrapStart ?? '{#{', end: this._replaceWrapEnd ?? '}#}'});
 
       const temp = this.ownerDocument?.createElement('template') || document.createElement('template');
       temp.innerHTML = htmlString;
 
       const content = temp.content;
       const nodes = Array.from(content.childNodes);
-      this._nodeGroups.push(nodes);
+
+      const setTemplateHost = (element: HTMLElement) => {
+        (element as any).__swc_template_host = this;
+        Array.from(element.children).forEach((child: any) => {
+          if (child instanceof HTMLElement) {
+            setTemplateHost(child);
+          }
+        });
+      };
+
+      nodes.forEach((node: any) => {
+        if (node instanceof HTMLElement) {
+          setTemplateHost(node as HTMLElement);
+        }
+      });
+      newNodesGroup.push(nodes);
       fragment.appendChild(content);
     });
 
+    return { fragment, newNodesGroup };
+  }
+
+  appendItem(...items: any[]) {
+    if (!items || items.length <= 0) return;
+    const portal = SwcUtils.getParentContainer(this);
+    if (!portal) return;
+
+    const win = this.ownerDocument?.defaultView || window;
+    const helperSet = SwcUtils.getHelperAndHostSet(win, this);
+
+    const startIndex = this._value ? this._value.length : 0;
+
+    // 내부 상태(value) 업데이트 (기존 배열에 새 아이템 추가)
+    if (this._value !== items) {
+      this._value = [...(this._value || []), ...items];
+    }
+
+    const { fragment, newNodesGroup } = this.createFragmentAndNodes(items, helperSet, startIndex);
+    this._nodeGroups.push(...newNodesGroup);
+
+    console.log('뭐야 씨발');
+    // append 위치 계산: 기존에 그려진 마지막 노드 뒤에 삽입, 없으면 템플릿 바로 뒤에 삽입
+    let insertReference: Node | null = this.nextSibling;
+    if (this._nodeGroups.length > items.length) {
+      const lastExistingGroup = this._nodeGroups[this._nodeGroups.length - items.length - 1];
+      if (lastExistingGroup && lastExistingGroup.length > 0) {
+        const lastNode = lastExistingGroup[lastExistingGroup.length - 1];
+        insertReference = lastNode.nextSibling;
+      }
+    }
+
+    portal.insertBefore(fragment, insertReference);
+  }
+
+  async prependItem(...items: any[]) {
+    if (!items || items.length <= 0) return;
+    const portal = SwcUtils.getParentContainer(this);
+    if (!portal) return;
+
+    const win = this.ownerDocument?.defaultView || window;
+    const helperSet = SwcUtils.getHelperAndHostSet(win, this);
+
+    // 내부 상태(value) 업데이트 (기존 배열의 앞쪽에 새 아이템 추가)
+    if (this._value !== items) {
+      this._value = [...items, ...(this._value || [])];
+    }
+
+    const { fragment, newNodesGroup } = this.createFragmentAndNodes(items, helperSet, 0);
+
+    // 기존의 nodeGroups 배열 맨 앞에 새로운 그룹들을 추가
+    this._nodeGroups = [...newNodesGroup, ...this._nodeGroups];
+
+    // prepend 위치: 이 템플릿(SwcLoop) 노드의 바로 다음 위치 (가장 위)
     portal.insertBefore(fragment, this.nextSibling);
   }
 
+  refresh(value?: any) {
+    // 1. 그릴 대상 확정
+    const targetValue = value !== undefined ? value : (getAttributeValue(this, 'value') ?? this._value ?? []);
+
+    // 2. 화면 정리
+    this.cleanup();
+
+    // 3. 상태 완전 교체 (이어붙이지 않음!)
+    this._value = targetValue;
+
+    if (!this._value || this._value.length <= 0) return;
+
+    // 4. 화면 다시 그리기 (appendItem을 쓰지 않고 바로 그리기)
+    const win = this.ownerDocument?.defaultView || window;
+    const helperSet = SwcUtils.getHelperAndHostSet(win, this);
+    helperSet.$templateHost = this;
+    const { fragment, newNodesGroup } = this.createFragmentAndNodes(this._value, helperSet, 0);
+
+    this._nodeGroups = newNodesGroup;
+    const portal = SwcUtils.getParentContainer(this);
+    if (portal) {
+      // console.log('append????!~~~~~!?',fragment)
+      portal.insertBefore(fragment, this.nextSibling);
+    }
+  }
+
   private cleanup() {
+    console.log('누가 cleanup');
     this._nodeGroups.forEach(nodes => nodes.forEach(n => n.parentElement?.removeChild(n)));
     this._nodeGroups = [];
   }
@@ -318,13 +468,12 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
 
     @elementDefine('swc-choose', { extends: 'template', window: w })
   class SwcChoose extends HTMLTemplateElement {
-  // @attributeHost('value')
-  // fetchValue: any;
-
   _value: any;
 
-  @attributeHost('replace-wrap')
-  _replaceWrap: string | null;
+  @attributeThis('replace-wrap-start')
+  _replaceWrapStart: string | null;
+  @attributeThis('replace-wrap-end')
+  _replaceWrapEnd: string | null;
 
   private _nodes: Node[] = [];
   private _previousTemplate: HTMLTemplateElement | null = null;
@@ -352,26 +501,34 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
     // console.log('-----------------choooooooose attr origin', na, o, n);
   }
 
-  @changedAttributeHost('value')
+  @changedAttributeThis('value')
   private setValue(value: any, o: string, n: string) {
-    // console.log('-----------------choooooooose attr setValue', value, o, n);
+    console.log('chooooooose value', value)
     this._value = value;
     this.refresh(this._value);
   }
 
-  @changedAttributeHost('replace-wrap')
-  private setReplaceWrap(replaceWrapAttr?: string | null) {
-    this.refresh();
-  }
+  // @changedAttributeThis('replace-wrap')
+  // private setReplaceWrap(replaceWrapAttr?: string | null) {
+  //   this.refresh();
+  // }
 
-  private replaceExpressions(html: string, groupArgs: any, context: any, wrap?: string | null): string {
-    const config = wrap ? { wrapExpression: wrap } : undefined;
+  private replaceExpressions(html: string, groupArgs: any, context: any, wrap: {start: string, end: string}): string {
+    let config: any = undefined;
+    if (wrap) {
+      config = {
+        expression: {
+          replace: { start: `${wrap.start}`, end: `${wrap.end}` },
+          callReturn: { start: `${wrap.start}=`, end: `${wrap.end}` },
+          call: { start: `${wrap.start}@`, end: `${wrap.end}` }
+        }
+      };
+    }
     const ae = new ActionExpression(html, config);
-    const filterOptions = wrap ? { type: 'replace' as const, wrap } : 'replace';
     const win = this.ownerDocument?.defaultView || window;
 
     // @ts-ignore
-    for (const expr of ae.getExpressions(filterOptions)) {
+    for (const expr of ae.getExpressions('replace')) {
       try {
         const value = FunctionUtils.executeReturn({
           script: ConvertUtils.decodeHtmlEntity(expr.script, win.document),
@@ -388,37 +545,48 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
 
   refresh(value?: any) {
     value = getAttributeValue(this, 'value') ?? this._value;
-    // console.log('chooooooooo refresh->', value);
-    const portal = this.parentElement;
-    if (!portal) return;
+    console.log('[DEBUG] SwcChoose.refresh called, value:', value);
+    const portal = SwcUtils.getParentContainer(this);
+    if (!portal) {
+      console.log('[DEBUG] SwcChoose portal is null!');
+      return;
+    }
 
     const win = (getElementConfig(this).window ?? this.ownerDocument?.defaultView) || window;
     const helperSet = SwcUtils.getHelperAndHostSet(win, this);
-    const groupArgs = { ...helperSet, $value: value };
+    const groupArgs = { ...helperSet, $value: value, $templateHost: this };
 
     const templates = Array.from(this.content.querySelectorAll('template'));
     let selected: HTMLTemplateElement | null = null;
 
     for (const t of templates) {
       if (t.getAttribute('is') === 'swc-when') {
-        const attrVal = t.getAttribute('value') || '';
+        const attrVal = t.getAttribute('test') || '';
         let matches = false;
 
+
+
+        const result = FunctionUtils.executeReturn({
+          script: attrVal,
+          context: t,
+          args: groupArgs
+        });
+        matches = !!result;
         // Use ActionExpression to parse and extract script from value attribute
-        const ae = new ActionExpression(attrVal);
-        const expr = ae.getFirstExpression('replace');
-
-        if (expr) {
-          const decodedScript = ConvertUtils.decodeHtmlEntity(expr.script, win.document);
-          const result = FunctionUtils.executeReturn({
-            script: decodedScript,
-            context: t,
-            args: groupArgs
-          });
-          matches = !!result;
-        } else {
-          matches = String(attrVal) === String(value);
-        }
+        // const ae = new ActionExpression(attrVal);
+        // const expr = ae.getFirstExpression('replace');
+
+        // if (expr) {
+        //   const decodedScript = ConvertUtils.decodeHtmlEntity(expr.script, win.document);
+        //   const result = FunctionUtils.executeReturn({
+        //     script: decodedScript,
+        //     context: t,
+        //     args: groupArgs
+        //   });
+        //   matches = !!result;
+        // } else {
+        //   matches = String(attrVal) === String(value);
+        // }
 
         if (matches) {
           selected = t;
@@ -443,14 +611,33 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
 
     if (target) {
       let htmlString = target.innerHTML;
-      htmlString = this.replaceExpressions(htmlString, groupArgs, this, this._replaceWrap);
+      htmlString = this.replaceExpressions(htmlString, groupArgs, this, {start:this._replaceWrapStart ?? '{#{', end: this._replaceWrapEnd ?? '}#}'});
 
       const result = this.ownerDocument?.createElement('template') || document.createElement('template');
       result.innerHTML = htmlString;
       const processedFragment = result.content;
 
+      // console.log('[DEBUG] SwcChoose processedFragment children:', processedFragment._childNodesInternal?.length);
       this._nodes = Array.from(processedFragment.childNodes);
+      
+      const setTemplateHost = (element: HTMLElement) => {
+        (element as any).__swc_template_host = this;
+        Array.from(element.children).forEach((child: any) => {
+          if (child instanceof HTMLElement) {
+            setTemplateHost(child);
+          }
+        });
+      };
+      
+      this._nodes.forEach((node: any) => {
+        if (node instanceof HTMLElement) {
+          setTemplateHost(node as HTMLElement);
+        }
+      });
+
+      console.log(`[DEBUG] SwcChoose before insertBefore, portal: ${portal?.tagName}, isConnected: ${(portal as any)?.isConnected}`);
       portal.insertBefore(processedFragment, this.nextSibling);
+      console.log('[DEBUG] SwcChoose after insertBefore');
     }
   }
 
@@ -466,13 +653,12 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
 
     @elementDefine('swc-async', { extends: 'template', window: w })
   class SwcAsync extends HTMLTemplateElement {
-  @attributeHost('value')
+  @attributeThis('value')
   _value: any;
-
-  @attributeHost('replace-wrap')
-  _replaceWrap: string | null;
-
-  resultValue?: any;
+  @attributeThis('replace-wrap-start')
+  _replaceWrapStart: string | null;
+  @attributeThis('replace-wrap-end')
+  _replaceWrapEnd: string | null;  resultValue?: any;
 
   get value(): boolean {
     return this._value;
@@ -484,15 +670,15 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
 
   private _nodes: Node[] = [];
 
-  @changedAttributeHost('value')
+  @changedAttributeThis('value')
   private setValue(valueAttr?: string | null) {
     this.executeAsync(this._value);
   }
 
-  @changedAttributeHost('replace-wrap')
-  private setReplaceWrap() {
-    this.executeAsync(this._value);
-  }
+  // @changedAttributeThis('replace-wrap')
+  // private setReplaceWrap() {
+  //   this.executeAsync(this._value);
+  // }
 
   private executeAsync(result: any = this._value) {
     if (result === undefined || result === null) {
@@ -518,14 +704,22 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
     }
   }
 
-  private replaceExpressions(html: string, groupArgs: any, context: any, wrap?: string | null): string {
-    const config = wrap ? { wrapExpression: wrap } : undefined;
+  private replaceExpressions(html: string, groupArgs: any, context: any, wrap: {start: string, end: string}): string {
+    let config: any = undefined;
+    if (wrap) {
+      config = {
+        expression: {
+          replace: { start: `${wrap.start}`, end: `${wrap.end}` },
+          callReturn: { start: `${wrap.start}=`, end: `${wrap.end}` },
+          call: { start: `${wrap.start}@`, end: `${wrap.end}` }
+        }
+      };
+    }
     const ae = new ActionExpression(html, config);
-    const filterOptions = wrap ? { type: 'replace' as const, wrap } : 'replace';
     const win = this.ownerDocument?.defaultView || window;
 
     // @ts-ignore
-    for (const expr of ae.getExpressions(filterOptions)) {
+    for (const expr of ae.getExpressions('replace')) {
       try {
         const value = FunctionUtils.executeReturn({
           script: ConvertUtils.decodeHtmlEntity(expr.script, win.document),
@@ -541,9 +735,9 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
   }
 
   refresh(state: string = 'default') {
-    console.log('rrrrrrrrrrrrrrrrr', state);
+    // console.log('rrrrrrrrrrrrrrrrr', state);
     this.cleanup();
-    const portal = this.parentElement;
+    const portal = SwcUtils.getParentContainer(this);
     if (!portal) return;
 
     const win = this.ownerDocument?.defaultView || window;
@@ -552,15 +746,19 @@ export const registerAllElements = (w: any): Record<string, Constructor<HTMLElem
     const t = this.content.querySelector(`template[is="swc-${state}"]`) as HTMLTemplateElement;
     if (t) {
       let htmlString = t.innerHTML;
-      const groupArgs = { ...helperSet, $value: this._value, $state: state };
+      const groupArgs = { ...helperSet, $value: this._value, $state: state, $templateHost: this };
 
-      htmlString = this.replaceExpressions(htmlString, groupArgs, this, this._replaceWrap);
+      htmlString = this.replaceExpressions(htmlString, groupArgs, this, {start:this._replaceWrapStart ?? '{#{', end: this._replaceWrapEnd ?? '}#}'});
 
       const temp = this.ownerDocument?.createElement('template') || document.createElement('template');
       temp.innerHTML = htmlString;
       const content = temp.content;
 
       this._nodes = Array.from(content.childNodes);
+      this._nodes.forEach((node: any) => {
+        if (node instanceof HTMLElement)  (node as any).__template_swc_host = this;
+      });
+
       portal.insertBefore(content, this.nextSibling);
     }
   }

package/src/types.ts

@@ -17,7 +17,7 @@ export enum InjectSituationType {
 
 export type SwcRootType = 'light' | 'shadow' | 'all' | 'auto';
 
-export type SpecialSelector = ':host' | ':window' | ':document' | ':parentHost' | ':appHost' | ':firstHost' | ':lastHost' | ':firstAppHost' | ':lastAppHost' | ':hosts' | ':appHosts';
+export type SpecialSelector = '$this' | '$window' | '$document' | '$host' | '$appHost' | '$firstHost' | '$lastHost' | '$firstAppHost' | '$lastAppHost' | '$hosts' | '$appHosts';
 
 export type SwcQueryOptions = { root?: SwcRootType };
 
@@ -30,11 +30,12 @@ export type HelperSet = {
 };
 
 export type HostSet = {
-  $host: HTMLElement; // Current component itself
-  $parentHost: HTMLElement | null; // Nearest parent SWC component
-  $hosts: HTMLElement[]; // [root, ..., parent, self]
+  $host: HTMLElement | null; // Nearest parent SWC component
+  $parentHost: HTMLElement | null; // Grandparent SWC ancestor
+  $hosts: HTMLElement[]; // All SWC ancestors [root, ..., parent]
   $firstHost: HTMLElement | null; // Top-most SWC ancestor
-  $lastHost: HTMLElement | null; // Same as $parentHost (for backward compatibility or clarity)
+  $lastHost: HTMLElement | null; // Same as $host
+  $templateHost: HTMLTemplateElement | null | undefined;
   $appHost: SwcAppInterface | null;
   $appHosts: SwcAppInterface[];
   $firstAppHost: SwcAppInterface | null;