@dooboostore/simple-web-component 1.0.16 → 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,10 +284,58 @@ Executed in **Parent -> Child** order.
 
 ---
 
+## 🔄 Structural Directives (Advanced)
+
+SWC provides 4 core templates: `swc-loop`, `swc-if`, `swc-choose`, and `swc-async`.
+
+### Common Attributes:
+- **`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)
+```html
+<template is="swc-if" on-get-value="isAdmin">
+  <template is="swc-default"><p>Please login.</p></template>
+  <div class="admin-panel">Welcome!</div>
+</template>
+```
+
+### 2. `swc-loop` (High-Performance Iteration)
+```html
+<template is="swc-loop" on-get-value="users" 
+    on-clone-node="if($isElement) $node.querySelector('.name').textContent = $item.name">
+  <template is="swc-default"><p>No users found.</p></template>
+  <div class="user-row"><span class="name"></span></div>
+</template>
+```
+
+### 3. `swc-choose` (Switch-Case Logic)
+```html
+<template is="swc-choose" on-get-value="user.role">
+  <template is="swc-default">Select a role.</template>
+  <template is="swc-when" value="admin">Admin Dashboard</template>
+  <template is="swc-otherwise">Access Denied</template>
+</template>
+```
+
+### 4. `swc-async` (Declarative Promises)
+```html
+<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"><div class="content"></div></template>
+  <template is="swc-success"><div class="content"></div></template>
+</template>
+```
+
+---
+
 ## ⚡ 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.
+- **Smart Delegation**: Host-level delegation with `__swc_handled` duplicate protection.
 
 ---
 

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/decorators/addEventListener.ts"],
-  "sourcesContent": ["import { ReflectUtils } from '@dooboostore/core/reflect/ReflectUtils';\n\nexport interface AddEventListenerOptions extends EventListenerOptions {\n  root?: 'light' | 'shadow' | 'all' | 'auto';\n  capture?: boolean;\n  once?: boolean;\n  passive?: boolean;\n  stopPropagation?: boolean;\n  stopImmediatePropagation?: boolean;\n  preventDefault?: boolean;\n  delegate?: boolean;\n}\n\nexport interface AddEventListenerMetadata {\n  selector: string;\n  type: string;\n  options: AddEventListenerOptions;\n  propertyKey: string | symbol;\n}\n\nexport const ADD_EVENT_LISTENER_METADATA_KEY = Symbol('simple-web-component:add-event-listener');\n\n/**\n * @addEventListener decorator to bind events to elements.\n * Usage: @addEventListener('.btn', 'click') onClick() { ... }\n * Usage: @addEventListener('', 'scroll', { passive: true }) onScroll() { ... }\n */\nexport function addEventListener(selector: string, type: string, options: AddEventListenerOptions = {}): MethodDecorator {\n  return (target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {\n    const constructor = target.constructor;\n\n    let listeners = ReflectUtils.getMetadata<AddEventListenerMetadata[]>(ADD_EVENT_LISTENER_METADATA_KEY, constructor);\n    if (!listeners) {\n      listeners = [];\n      ReflectUtils.defineMetadata(ADD_EVENT_LISTENER_METADATA_KEY, listeners, constructor);\n    }\n    listeners.push({ selector, type, options, propertyKey });\n  };\n}\n\nexport const getAddEventListenerMetadata = (target: any): AddEventListenerMetadata[] | undefined => {\n  const constructor = target instanceof Function ? target : target.constructor;\n  return ReflectUtils.getMetadata(ADD_EVENT_LISTENER_METADATA_KEY, constructor);\n};\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAA6B;AAoBtB,MAAM,kCAAkC,OAAO,yCAAyC;AAOxF,SAAS,iBAAiB,UAAkB,MAAc,UAAmC,CAAC,GAAoB;AACvH,SAAO,CAAC,QAAgB,aAA8B,eAAmC;AACvF,UAAM,cAAc,OAAO;AAE3B,QAAI,YAAY,iCAAa,YAAwC,iCAAiC,WAAW;AACjH,QAAI,CAAC,WAAW;AACd,kBAAY,CAAC;AACb,uCAAa,eAAe,iCAAiC,WAAW,WAAW;AAAA,IACrF;AACA,cAAU,KAAK,EAAE,UAAU,MAAM,SAAS,YAAY,CAAC;AAAA,EACzD;AACF;AAEO,MAAM,8BAA8B,CAAC,WAAwD;AAClG,QAAM,cAAc,kBAAkB,WAAW,SAAS,OAAO;AACjE,SAAO,iCAAa,YAAY,iCAAiC,WAAW;AAC9E;",
+  "sourcesContent": ["import { ReflectUtils } from '@dooboostore/core/reflect/ReflectUtils';\n\nexport interface AddEventListenerOptions extends EventListenerOptions {\n  root?: 'light' | 'shadow' | 'all' | 'auto';\n  capture?: boolean;\n  once?: boolean;\n  passive?: boolean;\n  stopPropagation?: boolean;\n  stopImmediatePropagation?: boolean;\n  preventDefault?: boolean;\n  delegate?: boolean;\n  removeOnDisconnected?: boolean;\n}\n\nexport interface AddEventListenerMetadata {\n  selector: string;\n  type: string;\n  options: AddEventListenerOptions;\n  propertyKey: string | symbol;\n}\n\nexport const ADD_EVENT_LISTENER_METADATA_KEY = Symbol('simple-web-component:add-event-listener');\n\n/**\n * @addEventListener decorator to bind events to elements.\n * Usage: @addEventListener('.btn', 'click') onClick() { ... }\n * Usage: @addEventListener('', 'scroll', { passive: true }) onScroll() { ... }\n */\nexport function addEventListener(selector: string, type: string, options: AddEventListenerOptions = {}): MethodDecorator {\n  return (target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {\n    const constructor = target.constructor;\n\n    let listeners = ReflectUtils.getMetadata<AddEventListenerMetadata[]>(ADD_EVENT_LISTENER_METADATA_KEY, constructor);\n    if (!listeners) {\n      listeners = [];\n      ReflectUtils.defineMetadata(ADD_EVENT_LISTENER_METADATA_KEY, listeners, constructor);\n    }\n    listeners.push({ selector, type, options, propertyKey });\n  };\n}\n\nexport const getAddEventListenerMetadata = (target: any): AddEventListenerMetadata[] | undefined => {\n  const constructor = target instanceof Function ? target : target.constructor;\n  return ReflectUtils.getMetadata(ADD_EVENT_LISTENER_METADATA_KEY, constructor);\n};\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAA6B;AAqBtB,MAAM,kCAAkC,OAAO,yCAAyC;AAOxF,SAAS,iBAAiB,UAAkB,MAAc,UAAmC,CAAC,GAAoB;AACvH,SAAO,CAAC,QAAgB,aAA8B,eAAmC;AACvF,UAAM,cAAc,OAAO;AAE3B,QAAI,YAAY,iCAAa,YAAwC,iCAAiC,WAAW;AACjH,QAAI,CAAC,WAAW;AACd,kBAAY,CAAC;AACb,uCAAa,eAAe,iCAAiC,WAAW,WAAW;AAAA,IACrF;AACA,cAAU,KAAK,EAAE,UAAU,MAAM,SAAS,YAAY,CAAC;AAAA,EACzD;AACF;AAEO,MAAM,8BAA8B,CAAC,WAAwD;AAClG,QAAM,cAAc,kBAAkB,WAAW,SAAS,OAAO;AACjE,SAAO,iCAAa,YAAY,iCAAiC,WAAW;AAC9E;",
   "names": []
 }

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": []
+}