@dooboostore/simple-web-component 1.0.17 → 1.0.18

package/README.md

@@ -42,13 +42,13 @@ Registers the class as a custom element.
 | `observedAttributes` | `string[]` | (Optional) Extra attributes to observe. |
 | `window` | `Window` | (Optional) Custom window object (useful for SSR). |
 
-### 2. `@innerHtml(options?)`
-Defines the template for the component.
+### 2. `@onConnectedInnerHtml(options?)`
+Defines the template for the component. Executed when the component is connected to the DOM.
 
 ```typescript
 @elementDefine('my-el')
 class MyEl extends HTMLElement {
-  @innerHtml({ useShadow: true })
+  @onConnectedInnerHtml({ useShadow: true })
   render() {
     return `<style>:host { color: blue; }</style><div>Hello World</div>`;
   }
@@ -80,7 +80,7 @@ class MyCounter extends HTMLElement {
 ```
 
 ### 4. Powerful Queries (`@query`, `@queryAll`)
-Inject internal elements directly into properties. Supports the **`:host`** selector.
+Inject internal elements directly into properties. Supports the **`:host`** selector and precise root control. Assigning `null` or `[]` to these properties will surgically remove the target elements from the DOM.
 
 | Root Option | Description |
 |---|---|
@@ -89,24 +89,14 @@ Inject internal elements directly into properties. Supports the **`:host`** sele
 | `light` | **Strictly** search in Light DOM (`this`). |
 | `all` | Search in **both** Shadow and Light DOM. |
 
-Inject elements directly into properties. Supports `:host` and scoped root control.
-
 ```typescript
-@elementDefine('query-demo')
-class QueryDemo extends HTMLElement {
-  @query('.title') titleEl!: HTMLElement;
-  @queryAll('.items') list!: NodeListOf<HTMLElement>;
-  
-  // Reference the component itself
-  @query(':host') self!: HTMLElement;
-
-  // Root options: 'light' | 'shadow' | 'all' | 'auto' (default)
-  @query('.btn', { root: 'shadow' }) shadowBtn!: HTMLButtonElement;
-}
+@query('.title') titleEl!: HTMLElement;
+@query('.btn', { root: 'shadow' }) shadowBtn!: HTMLButtonElement;
+@query(':host') self!: HTMLElement; // References the component itself
 ```
 
 ### 5. Smart Event Binding (`@addEventListener`)
-Bind events declaratively with support for **Event Delegation**.
+Bind events declaratively with support for **Event Delegation** and special targets like `:window` and `:document`.
 
 ```typescript
 @elementDefine('event-demo')
@@ -115,11 +105,55 @@ class EventDemo extends HTMLElement {
   @addEventListener('.static-btn', 'click')
   onStaticClick(event: MouseEvent) { ... }
 
-  // 2. Event Delegation (Works for dynamic nodes added LATER)
+  // 2. Event Delegation (Handles dynamic nodes)
   @addEventListener('.item', 'click', { delegate: true })
   onItemClick(event: MouseEvent, { $host }: HostSet, target: HTMLElement) {
     console.log('Clicked dynamic item:', target.textContent);
   }
+
+  // 3. Global Events with Auto-Cleanup
+  @addEventListener(':window', 'resize', { removeOnDisconnected: true })
+  onResize() { ... }
+}
+```
+
+### 6. `@replaceChildren(selector)`
+Surgically replaces the children of a target element with the method's return value (`string`, `Node`, or `Array<Node|string>`).
+
+```typescript
+@elementDefine('surgical-demo')
+class SurgicalDemo extends HTMLElement {
+  // Replaces all children of #display-area with the new content
+  @replaceChildren('#display-area')
+  updateView(title: string) {
+    return `<h2>${title}</h2><p>Updated successfully.</p>`;
+  }
+}
+```
+
+### 7. `@appendChild(selector, options?)`
+Appends or inserts the method's return value relative to a target element.
+- **position**: `'lastChild'` (default), `'firstChild'`, `'nextSibling'`, `'previousSibling'`.
+
+```typescript
+@elementDefine('list-manager')
+class ListManager extends HTMLElement {
+  // Prepends a new item to the top of the #my-list element
+  @appendChild('#my-list', { position: 'firstChild' })
+  addNewItem(text: string) {
+    return `<li>${text}</li>`;
+  }
+}
+```
+
+```typescript
+@elementDefine('list-manager')
+class ListManager extends HTMLElement {
+  // Prepends a new item to the top of the #my-list element
+  @appendChild('#my-list', { position: 'firstChild' })
+  addNewItem(text: string) {
+    return `<li>${text}</li>`;
+  }
 }
 ```
 
@@ -130,14 +164,13 @@ class EventDemo extends HTMLElement {
 SWC provides a revolutionary way to build SPAs where **each component scope is an independent application**.
 
 ### 1. Isolated App Scopes (Micro-Frontends)
-Use the `<swc-app>` tag to create an isolated universe. Each instance has its own **DI Container** and **Router**. You can run multiple independent SPAs on a single page without URL conflicts.
+Use the `<swc-app>` tag to create an isolated universe. Each instance has its own **DI Container** and **Router**.
 
 ```html
 <!-- index.html -->
 <swc-app swc-get-application-config="myAppConfig(this)"></swc-app>
 
 <script>
-  // This function returns the configuration needed to bootstrap the SWC App
   window.myAppConfig = (host) => {
     return {
       rootRouter: RootRouter, // The entry point class (must be @Sim)
@@ -147,35 +180,24 @@ Use the `<swc-app>` tag to create an isolated universe. Each instance has its ow
     };
   };
 
-  // 4. External Control (Anywhere in your JS)
+  // External Control
   function navigateFromOutside() {
       const app = document.querySelector('swc-app');
-      // Programmatically trigger routing from outside the component
       app.routing('/users/detail/2'); 
   }
 </script>
-
-<button onclick="navigateFromOutside()">External Link to User 2</button>
 ```
 
 ### 2. DI-Powered Routing
-Define routes using decorators. Components are automatically instantiated and managed by the DI container.
-
 ```typescript
-import { Router } from '@dooboostore/simple-boot/decorators/route/Router';
-import { Sim } from '@dooboostore/simple-boot/decorators/SimDecorator';
-
 @Sim
 @Router({
   path: '/users',
-  route: {
-    '/list': UserList,
-    '/detail/:id': UserDetail
-  }
+  route: { '/list': UserList, '/detail/:id': UserDetail }
 })
 @elementDefine('user-router')
 class UserRouter extends HTMLElement implements RouterAction.CanActivate {
-  @innerHtml({ useShadow: true })
+  @onConnectedInnerHtml({ useShadow: true })
   render() { 
     return `<header>User System</header><main><slot></slot></main>`; 
   }
@@ -185,21 +207,17 @@ class UserRouter extends HTMLElement implements RouterAction.CanActivate {
   }
 }
 
-// Pure Service (Business Logic)
 @Sim
 class UserService {
-  async getProfile(id: string) {
-    return { id, name: 'Standard User' };
-  }
+  async getProfile(id: string) { return { id, name: 'Standard User' }; }
 }
 
-// Example Page Components
 @Sim
 @elementDefine('user-list')
 class UserList extends HTMLElement {
   constructor(private router: Router, private userService: UserService) { super(); }
 
-  @innerHtml
+  @onConnectedInnerHtml
   render() { 
     return `
       <ul><li>User A</li><li>User B</li></ul>
@@ -220,22 +238,18 @@ class UserDetail extends HTMLElement {
      console.log('Viewing User:', profile.name);
   }
 
-  @innerHtml
+  @onConnectedInnerHtml
   render() { return `<div>User Detail View <button swc-on-click="$host.router.back()">Back</button></div>`; }
 }
 ```
 
 ### 3. Lifecycle @Inject
-Inject services or component context directly into lifecycle methods. This is the ultimate way to handle side effects cleanly.
-
 ```typescript
 import { Inject } from '@dooboostore/simple-boot/decorators/inject/Inject';
 import { InjectSituationType, onConnected, HostSet } from '@dooboostore/simple-web-component';
-import { Router } from '@dooboostore/core-web/routers/Router';
 
 @elementDefine('profile-page')
 class ProfilePage extends HTMLElement {
-
   @onConnected
   async init(
     @Inject({ situationType: InjectSituationType.HOST_SET }) hostSet: HostSet,
@@ -244,7 +258,6 @@ class ProfilePage extends HTMLElement {
   ) {
     console.log('App scope:', hostSet.$appHost);
     const user = await api.getProfile();
-    // Navigate programmatically using injected router
     if (!user) router.go('/login');
   }
 }
@@ -271,36 +284,25 @@ Executed in **Parent -> Child** order.
 
 ---
 
-## ⚡ Performance
-- **Zero "Deep Scan"**: Listeners are only bound to specific selectors.
-- **Surgical Updates**: Manipulate DOM directly in `@changedAttribute` instead of full re-renders.
-- **Zero Background Overhead**: No polling, no background observers.
-
----
-
----
-
 ## 🔄 Structural Directives (Advanced)
 
-SWC provides 4 core templates that empower your HTML without wrapper elements: `swc-loop`, `swc-if`, `swc-choose`, and `swc-async`. They all share a consistent, high-performance API.
+SWC provides 4 core templates: `swc-loop`, `swc-if`, `swc-choose`, and `swc-async`.
 
 ### Common Attributes:
-- **`on-get-value`**: Script to fetch data (supports return-less expressions).
-- **`on-clone-nodes`**: Callback after a group of nodes is cloned (Args: `$index`, `$item`, `$nodes`, `$elements`, `$firstElement`, `$state`).
-- **`on-clone-node`**: Callback for each individual node (Args: `$node`, `$nodeIndex`, and all group args).
-- **`on-get-portal`**: Script that returns an `Element` or selector string to render content in a different part of the DOM.
+- **`on-get-value`**: Script to fetch data.
+- **`on-clone-nodes`**: Callback after a group of nodes is cloned.
+- **`on-clone-node`**: Callback for each individual node.
+- **`on-get-portal`**: Script that returns an `Element` or selector for portal rendering.
 
 ### 1. `swc-if` (Conditional Rendering)
-Renders content only when the condition is truthy. Supports a fallback `swc-default` state.
 ```html
 <template is="swc-if" on-get-value="isAdmin">
-  <template is="swc-default"><p>Please login as admin.</p></template>
-  <div class="admin-panel">Welcome, Master!</div>
+  <template is="swc-default"><p>Please login.</p></template>
+  <div class="admin-panel">Welcome!</div>
 </template>
 ```
 
 ### 2. `swc-loop` (High-Performance Iteration)
-Efficiently renders lists with surgical updates and index preservation.
 ```html
 <template is="swc-loop" on-get-value="users" 
     on-clone-node="if($isElement) $node.querySelector('.name').textContent = $item.name">
@@ -310,64 +312,30 @@ Efficiently renders lists with surgical updates and index preservation.
 ```
 
 ### 3. `swc-choose` (Switch-Case Logic)
-Selects the first matching `swc-when` or falls back to `swc-otherwise`.
 ```html
 <template is="swc-choose" on-get-value="user.role">
-  <template is="swc-default">Please select a role.</template>
+  <template is="swc-default">Select a role.</template>
   <template is="swc-when" value="admin">Admin Dashboard</template>
-  <template is="swc-when" value="user">User Home</template>
   <template is="swc-otherwise">Access Denied</template>
 </template>
 ```
 
 ### 4. `swc-async` (Declarative Promises)
-Handles Promise states (Loading, Error, Success) without manual state management.
 ```html
-<template is="swc-async" on-get-value="fetchData()">
+<template is="swc-async" on-get-value="fetchData()"
+    on-clone-node="if($isElement && $node.className === 'content') $node.textContent = $value?.title || $error?.message">
   <template is="swc-loading">🌀 Loading...</template>
-  <template is="swc-error">❌ Error: {{$error.message}}</template>
-  <template is="swc-success">✅ Data: {{$value.title}}</template>
-</template>
-```
-
-### Advanced: Integrated Portal Support
-All directives above support the **`on-get-portal`** attribute to render content elsewhere.
-```html
-<template is="swc-if" on-get-value="showModal" on-get-portal="'body'">
-  <div class="modal-overlay">I am rendered at the end of &lt;body&gt;!</div>
+  <template is="swc-error"><div class="content"></div></template>
+  <template is="swc-success"><div class="content"></div></template>
 </template>
 ```
 
 ---
 
-## ⚡ Integrated Event & Query Selectors
-
-Both `@addEventListener` and `@query` support special selectors to navigate the environment and component hierarchy seamlessly.
-
-| Selector | Target Description |
-|---|---|
-| `:host` | The component itself (default for empty selector). |
-| `:parentHost` | The immediate parent SWC component. |
-| `:appHost` | The nearest parent `<swc-app>` instance. |
-| `:window` | The environment-aware global `window` object. |
-| `:document` | The environment-aware global `document` object. |
-| `:hosts` | Array of all SWC ancestors (Root -> Self). |
-
-### Global Event Example
-```typescript
-@elementDefine('auto-cleanup-demo')
-class CleanupDemo extends HTMLElement {
-  // Automatically attaches to window and REMOVES on disconnectedCallback
-  @addEventListener(':window', 'resize', { removeOnDisconnected: true })
-  onResize(event: UIEvent) {
-    console.log('Window resized!', this.id);
-  }
-}
-```
-
-## ⚡ Performance Features
+## ⚡ Performance
+- **Zero "Deep Scan"**: Listeners are only bound to specific selectors.
+- **Surgical Updates**: Manipulate DOM directly in `@changedAttribute` instead of full re-renders.
 - **Smart Delegation**: Host-level delegation with `__swc_handled` duplicate protection.
-- **Index-Preserving Removal**: `SwcLoop` maintains stable indices during item removal for maximum UI consistency.
 
 ---
 

package/dist/cjs/decorators/appendChild.js

@@ -0,0 +1,48 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var appendChild_exports = {};
+__export(appendChild_exports, {
+  APPEND_CHILD_METADATA_KEY: () => APPEND_CHILD_METADATA_KEY,
+  appendChild: () => appendChild,
+  findAllAppendChildMetadata: () => findAllAppendChildMetadata
+});
+module.exports = __toCommonJS(appendChild_exports);
+var import_ReflectUtils = require("@dooboostore/core/reflect/ReflectUtils");
+const APPEND_CHILD_METADATA_KEY = Symbol("simple-web-component:append-child");
+function appendChild(selector, options = { position: "lastChild" }) {
+  return (target, propertyKey) => {
+    const constructor = target.constructor;
+    let meta = import_ReflectUtils.ReflectUtils.getOwnMetadata(APPEND_CHILD_METADATA_KEY, constructor);
+    if (!meta) {
+      meta = /* @__PURE__ */ new Map();
+      import_ReflectUtils.ReflectUtils.defineMetadata(APPEND_CHILD_METADATA_KEY, meta, constructor);
+    }
+    meta.set(propertyKey, { propertyKey, selector, options });
+  };
+}
+const findAllAppendChildMetadata = (target) => {
+  const result = /* @__PURE__ */ new Map();
+  const maps = import_ReflectUtils.ReflectUtils.findAllMetadata(APPEND_CHILD_METADATA_KEY, target);
+  maps.forEach((map) => {
+    if (map instanceof Map) {
+      map.forEach((v, k) => result.set(k, v));
+    }
+  });
+  return result;
+};
+//# sourceMappingURL=appendChild.js.map

package/dist/cjs/decorators/appendChild.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/decorators/appendChild.ts"],
+  "sourcesContent": ["import { ReflectUtils } from '@dooboostore/core/reflect/ReflectUtils';\n\nexport type AppendChildPosition = 'firstChild' | 'lastChild' | 'nextSibling' | 'previousSibling';\n\nexport interface AppendChildOptions {\n  position?: AppendChildPosition;\n}\n\nexport interface AppendChildMetadata {\n  propertyKey: string | symbol;\n  selector: string;\n  options: AppendChildOptions;\n}\n\nexport const APPEND_CHILD_METADATA_KEY = Symbol('simple-web-component:append-child');\n\n/**\n * @appendChild decorator to surgically add nodes to a target element.\n * Usage: @appendChild('#list') addItem() { return '<li>New Item</li>'; }\n */\nexport function appendChild(selector: string, options: AppendChildOptions = { position: 'lastChild' }): MethodDecorator {\n  return (target: Object, propertyKey: string | symbol) => {\n    const constructor = target.constructor;\n    let meta = ReflectUtils.getOwnMetadata(APPEND_CHILD_METADATA_KEY, constructor) as Map<string | symbol, AppendChildMetadata>;\n    if (!meta) {\n      meta = new Map<string | symbol, AppendChildMetadata>();\n      ReflectUtils.defineMetadata(APPEND_CHILD_METADATA_KEY, meta, constructor);\n    }\n    meta.set(propertyKey, { propertyKey, selector, options });\n  };\n}\n\nexport const findAllAppendChildMetadata = (target: any): Map<string | symbol, AppendChildMetadata> => {\n  const result = new Map<string | symbol, AppendChildMetadata>();\n  const maps = ReflectUtils.findAllMetadata<Map<string | symbol, AppendChildMetadata>>(APPEND_CHILD_METADATA_KEY, target);\n  maps.forEach(map => {\n    if (map instanceof Map) {\n      map.forEach((v, k) => result.set(k, v));\n    }\n  });\n  return result;\n};\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAA6B;AActB,MAAM,4BAA4B,OAAO,mCAAmC;AAM5E,SAAS,YAAY,UAAkB,UAA8B,EAAE,UAAU,YAAY,GAAoB;AACtH,SAAO,CAAC,QAAgB,gBAAiC;AACvD,UAAM,cAAc,OAAO;AAC3B,QAAI,OAAO,iCAAa,eAAe,2BAA2B,WAAW;AAC7E,QAAI,CAAC,MAAM;AACT,aAAO,oBAAI,IAA0C;AACrD,uCAAa,eAAe,2BAA2B,MAAM,WAAW;AAAA,IAC1E;AACA,SAAK,IAAI,aAAa,EAAE,aAAa,UAAU,QAAQ,CAAC;AAAA,EAC1D;AACF;AAEO,MAAM,6BAA6B,CAAC,WAA2D;AACpG,QAAM,SAAS,oBAAI,IAA0C;AAC7D,QAAM,OAAO,iCAAa,gBAA2D,2BAA2B,MAAM;AACtH,OAAK,QAAQ,SAAO;AAClB,QAAI,eAAe,KAAK;AACtB,UAAI,QAAQ,CAAC,GAAG,MAAM,OAAO,IAAI,GAAG,CAAC,CAAC;AAAA,IACxC;AAAA,EACF,CAAC;AACD,SAAO;AACT;",
+  "names": []
+}

package/dist/cjs/decorators/elementDefine.js

@@ -24,12 +24,14 @@ __export(elementDefine_exports, {
 module.exports = __toCommonJS(elementDefine_exports);
 var import_ReflectUtils = require("@dooboostore/core/reflect/ReflectUtils");
 var import_FunctionUtils = require("@dooboostore/core/function/FunctionUtils");
-var import_innerHtml = require("./innerHtml");
+var import_onConnectedInnerHtml = require("./onConnectedInnerHtml");
 var import_addEventListener = require("./addEventListener");
 var import_lifecycles = require("./lifecycles");
 var import_emitCustomEvent = require("./emitCustomEvent");
 var import_changedAttribute = require("./changedAttribute");
 var import_setAttribute = require("./setAttribute");
+var import_replaceChildren = require("./replaceChildren");
+var import_appendChild = require("./appendChild");
 var import_Utils = require("../utils/Utils");
 var import_config = require("../config/config");
 var import_Inject = require("@dooboostore/simple-boot/decorators/inject/Inject");
@@ -71,10 +73,12 @@ const elementDefine = (inConfig) => (constructor) => {
   const addEventListenerList = (0, import_addEventListener.getAddEventListenerMetadata)(constructor) || [];
   const attrChangeMap = (0, import_changedAttribute.findAllAttributeChangedMetadata)(constructor);
   const setAttrMap = (0, import_setAttribute.findAllSetAttributeMetadata)(constructor);
+  const replaceChildrenMap = (0, import_replaceChildren.findAllReplaceChildrenMetadata)(constructor);
+  const appendChildMap = (0, import_appendChild.findAllAppendChildMetadata)(constructor);
   const swcLifecycleAttributes = ["swc-on-constructor", "swc-on-connected", "swc-on-disconnected", "swc-on-before-connected", "swc-on-after-connected", "swc-on-before-disconnected", "swc-on-after-disconnected", "swc-on-before-adopted", "swc-on-after-adopted", "swc-on-attribute-changed"];
   const swcOnEvents = import_config.DOM_EVENT_NAMES.map((e) => `swc-on-${e}`);
   const mergedObservedAttributes = [.../* @__PURE__ */ new Set([...config.observedAttributes ?? [], ...attrChangeMap.keys(), ...setAttrMap.keys(), ...emitCustomEventList.map((it) => it.options.attributeName), ...swcLifecycleAttributes, ...swcOnEvents])];
-  const innerHtmlList = (0, import_innerHtml.getInnerHtmlMetadataList)(constructor) || [];
+  const connectedInnerHtmlList = (0, import_onConnectedInnerHtml.getOnConnectedInnerHtmlMetadata)(constructor) || [];
   const NewClass = class extends constructor {
     _executeSwcScript(attrName, hostSet, extraArgs = {}) {
       const script = this.getAttribute(attrName);
@@ -141,7 +145,7 @@ const elementDefine = (inConfig) => (constructor) => {
       this._boundListeners = [];
       const hostSet = import_Utils.SwcUtils.getHostSet(this);
       this._executeSwcScript("swc-on-constructor", hostSet);
-      if (innerHtmlList.some((it) => it.options.useShadow === true) && !this.shadowRoot) {
+      if (connectedInnerHtmlList.some((it) => it.options.useShadow === true) && !this.shadowRoot) {
         this.attachShadow({ mode: "open" });
       }
     }
@@ -161,9 +165,9 @@ const elementDefine = (inConfig) => (constructor) => {
       }
       if (typeof this.initCore === "function")
         this.initCore();
-      if (innerHtmlList.length > 0) {
+      if (connectedInnerHtmlList.length > 0) {
         let sContent = "", lContent = "";
-        for (const meta of innerHtmlList) {
+        for (const meta of connectedInnerHtmlList) {
           const res = await this[meta.propertyKey]();
           if (res !== void 0) {
             if (meta.options.useShadow)
@@ -207,8 +211,9 @@ const elementDefine = (inConfig) => (constructor) => {
         }
       };
       import_config.DOM_EVENT_NAMES.forEach((type) => {
-        this.addEventListener(type, createDelegationHandler(this));
-        this._boundListeners.push({ target: this, type, handler: createDelegationHandler(this) });
+        const handler = createDelegationHandler(this);
+        this.addEventListener(type, handler);
+        this._boundListeners.push({ target: this, type, handler });
       });
       const hasParentHost = import_Utils.SwcUtils.findAllSwcHosts(this).length > 0;
       if (!hasParentHost) {
@@ -410,6 +415,79 @@ const elementDefine = (inConfig) => (constructor) => {
       };
     }
   });
+  replaceChildrenMap.forEach((selector, methodName) => {
+    const original = NewClass.prototype[methodName];
+    if (typeof original === "function") {
+      NewClass.prototype[methodName] = function(...args) {
+        const res = original.apply(this, args);
+        if (res !== void 0) {
+          const conf = getElementConfig(this);
+          const currentWin = conf?.window || window;
+          const currentDoc = currentWin.document;
+          let targetEl = null;
+          if (selector === ":host" || !selector) {
+            targetEl = this;
+          } else {
+            targetEl = (this.shadowRoot || this).querySelector(selector);
+          }
+          if (targetEl) {
+            const nodes = Array.isArray(res) ? res : [res];
+            const normalizedNodes = nodes.map((n) => {
+              if (typeof n === "string") {
+                const t = currentDoc.createElement("template");
+                t.innerHTML = n;
+                return t.content;
+              }
+              return n;
+            });
+            targetEl.replaceChildren(...normalizedNodes);
+          }
+        }
+        return res;
+      };
+    }
+  });
+  appendChildMap.forEach((meta, methodName) => {
+    const { selector, options } = meta;
+    const original = NewClass.prototype[methodName];
+    if (typeof original === "function") {
+      NewClass.prototype[methodName] = function(...args) {
+        const res = original.apply(this, args);
+        if (res !== void 0) {
+          const conf = getElementConfig(this);
+          const currentWin = conf?.window || window;
+          const currentDoc = currentWin.document;
+          let targetEl = null;
+          if (selector === ":host" || !selector) {
+            targetEl = this;
+          } else {
+            targetEl = (this.shadowRoot || this).querySelector(selector);
+          }
+          if (targetEl) {
+            const nodes = Array.isArray(res) ? res : [res];
+            const normalizedNodes = nodes.map((n) => {
+              if (typeof n === "string") {
+                const t = currentDoc.createElement("template");
+                t.innerHTML = n;
+                return t.content;
+              }
+              return n;
+            });
+            const pos = options.position || "lastChild";
+            if (pos === "lastChild")
+              targetEl.append(...normalizedNodes);
+            else if (pos === "firstChild")
+              targetEl.prepend(...normalizedNodes);
+            else if (pos === "nextSibling")
+              targetEl.after(...normalizedNodes);
+            else if (pos === "previousSibling")
+              targetEl.before(...normalizedNodes);
+          }
+        }
+        return res;
+      };
+    }
+  });
   const originalProto = constructor.prototype;
   const newProto = NewClass.prototype;
   Object.getOwnPropertyNames(originalProto).forEach((name) => {