@dooboostore/simple-web-component 1.0.21 → 1.0.22

package/README.md

@@ -30,67 +30,715 @@ For **Safari** support of the `is` attribute, add this to your `<head>`:
 
 ---
 
-## 💡 Core Decorators
+## 💡 Complete Decorator Reference
 
-### 1. `@elementDefine(config)`
-Registers the class as a custom element.
+### Lifecycle Decorators
 
-| Option | Type | Description |
-|---|---|---|
-| `name` | `string` | The custom element tag name (e.g., `'my-el'`). |
-| `extends` | `string` | (Optional) The native tag to extend. |
-| `observedAttributes` | `string[]` | (Optional) Extra attributes to observe. |
-| `window` | `Window` | (Optional) Custom window object (useful for SSR). |
+#### 1. `@onConstructor()`
+Called during component construction (in `constructor`). Perfect for dependency injection setup.
 
-### 2. `@onConnectedInnerHtml(options?)`
-Defines the template for the component. Executed when the component is connected to the DOM.
+```typescript
+@elementDefine('my-component')
+class MyComponent extends HTMLElement {
+  private dataService: DataService;
+
+  @onConstructor
+  setupDI(dataService: DataService) {
+    this.dataService = dataService;
+    console.log('Component constructed with DI');
+  }
+}
+```
+
+**Execution Order**: First - during `new MyComponent()`
+
+#### 2. `@onBeforeConnected()`
+**Dependency Injection & Pre-connection Setup**
+
+Called before the component connects to the DOM. Perfect for initializing services via DI.
+
+**⚠️ Important**: Lifecycle DI works **WITHOUT `@Sim`** - regular `@elementDefine` components can receive services here!
+
+```typescript
+@elementDefine('my-component')  // ← NO @Sim needed for lifecycle DI
+class MyComponent extends HTMLElement {
+  #cartService: CartService;
+  #subscription?: Subscription;
+
+  // Lifecycle DI injection - works even without @Sim
+  @onBeforeConnected
+  async setupComponent(cartService: CartService) {
+    this.#cartService = cartService;
+    
+    // Can be async - waits before rendering
+    await this.#cartService.load();
+    
+    // Subscribe to reactive updates
+    this.#subscription = this.#cartService.store.subscribe(state => {
+      this.updateUI();
+    });
+  }
+
+  disconnectedCallback() {
+    this.#subscription?.unsubscribe();
+  }
+
+  @onConnectedInnerHtml
+  render() {
+    return `<div>Component ready</div>`;
+  }
+}
+```
+
+**Key Features:**
+- ✅ Services automatically injected via lifecycle decorators
+- ✅ **NO `@Sim` required** for lifecycle DI injection
+- ✅ Can be async - waits before rendering
+- ✅ Called once, before `connectedCallback`
+- ✅ Perfect for initialization and subscriptions
+
+**DI Injection Methods:**
+
+| Method | Requires `@Sim`? | Location |
+|--------|-----------------|----------|
+| Lifecycle (`@onBeforeConnected`) | ❌ NO | Lifecycle decorators |
+| Constructor Injection | ✅ YES | Inside `<swc-app>` only |
+| Static Registration | ✅ YES | `<swc-app>` DI container |
+
+**Execution Order**: Before `connectedCallback()`
+
+#### 3. `@onAfterConnected()` / `@onConnected()`
+Called after the component connects to the DOM. For post-render operations.
+
+```typescript
+@elementDefine('my-element')
+class MyElement extends HTMLElement {
+  @onAfterConnected  // or @onConnected (alias)
+  initializeAfterConnect() {
+    console.log('Element fully connected to DOM');
+    this.focus();  // Can interact with DOM now
+    
+    // Measure element size after render
+    const rect = this.getBoundingClientRect();
+    console.log('Size:', rect.width, rect.height);
+  }
+}
+```
+
+**Execution Order**: After `connectedCallback()`
+
+#### 4. `@onBeforeDisconnected()`
+Called before the component disconnects from the DOM. For cleanup preparation.
+
+```typescript
+@elementDefine('event-listener-component')
+class EventListenerComponent extends HTMLElement {
+  private resizeObserver: ResizeObserver;
+
+  @onBeforeDisconnected
+  prepareForDisconnect() {
+    console.log('About to disconnect, saving state...');
+    // Save state, cancel pending requests, etc.
+    const state = {
+      scrollPosition: window.scrollY,
+      formData: this.getFormData()
+    };
+    localStorage.setItem('component-state', JSON.stringify(state));
+  }
+
+  @onAfterDisconnected
+  cleanup() {
+    this.resizeObserver?.disconnect();
+    console.log('Cleanup completed');
+  }
+}
+```
+
+**Execution Order**: Before `disconnectedCallback()`
+
+#### 5. `@onAfterDisconnected()` / `@onDisconnected()`
+Called after the component disconnects from the DOM. Final cleanup.
+
+```typescript
+@elementDefine('resource-component')
+class ResourceComponent extends HTMLElement {
+  private timerId: number;
+  private subscription: Subscription;
+
+  @onAfterDisconnected  // or @onDisconnected (alias)
+  cleanup() {
+    // Cancel timers
+    clearTimeout(this.timerId);
+    
+    // Unsubscribe from observables
+    this.subscription?.unsubscribe();
+    
+    console.log('Resources cleaned up');
+  }
+}
+```
+
+**Execution Order**: After `disconnectedCallback()`
+
+#### 6. `@onBeforeAdopted()`
+Called before the element is adopted by a new document (useful for SSR/iframe scenarios).
+
+```typescript
+@elementDefine('document-aware')
+class DocumentAware extends HTMLElement {
+  @onBeforeAdopted
+  prepareForAdoption() {
+    console.log('Adopting to new document...');
+    // Prepare for document change
+  }
+}
+```
+
+#### 7. `@onAfterAdopted()` / `@onAdopted()`
+Called after the element is adopted by a new document.
+
+```typescript
+@elementDefine('iframe-component')
+class IframeComponent extends HTMLElement {
+  @onAfterAdopted  // or @onAdopted (alias)
+  onDocumentAdopted() {
+    console.log('Now in new document context');
+    // Re-attach to new document's resources
+    this.initializeInNewDocument();
+  }
+
+  private initializeInNewDocument() {
+    // Setup for new document
+  }
+}
+```
+
+#### 8. `@onAddEventListener()`
+Called when an event listener is added to the element. For event tracking/analytics.
+
+```typescript
+@elementDefine('event-tracked')
+class EventTracked extends HTMLElement {
+  @onAddEventListener
+  onListenerAdded(type: string, listener: EventListener, options?: AddEventListenerOptions) {
+    console.log(`Event listener added: ${type}`);
+    // Track event listeners for debugging
+  }
+}
+```
+
+#### 9. `@onConnectedInnerHtml(options?)`
+Defines the component's template. Renders to Shadow DOM or Light DOM based on `useShadow` option.
 
 ```typescript
-@elementDefine('my-el')
-class MyEl extends HTMLElement {
+@elementDefine('styled-card')
+class StyledCard extends HTMLElement {
   @onConnectedInnerHtml({ useShadow: true })
   render() {
-    return `<style>:host { color: blue; }</style><div>Hello World</div>`;
+    return `
+      <style>
+        :host {
+          display: block;
+          padding: 20px;
+          border-radius: 8px;
+          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        }
+      </style>
+      <div class="card-content">
+        <slot></slot>
+      </div>
+    `;
   }
 }
 ```
 
-### 3. Modern Attribute Management
-SWC uses a **Method-Based Reflection** approach. You control exactly how data flows.
+**Options:**
+- `useShadow: true` - Render to Shadow DOM (style encapsulation)
+- `useShadow: false` - Render to Light DOM (default)
+
+---
 
-**Attribute sync rules**
-- Initial sync honors DOM-first semantics: if a markup attribute already exists (e.g., `<my-el count="11">`), the first write keeps that DOM value even when the class defines `count = 0`.
-- `connectedInitialize: true` flips the direction for that property so the in-memory value is pushed to the DOM during `connectedCallback`.
-- Type conversion is automatic through `convertValue` so `Boolean`, `Number`, and `String` fields always expose typed values while still storing the serialized attribute on the element.
-- Getters return `null` when the resolved target exists but the attribute is absent, giving you an explicit signal that the DOM is missing that state.
+### Attribute & Property Decorators
 
-- **`@setAttribute(name?, options?)`**: Reflects the method's **return value** to the DOM attribute. Supports `SwcQueryOptions` for root-aware target resolution (light DOM, shadow DOM, or auto-detect).
-- **`@changedAttribute(name?)`**: A handler triggered when the attribute changes.
+#### 10. `@attributeHost(name, options?)`
+Bidirectional attribute binding with automatic type conversion.
 
 ```typescript
-@elementDefine('my-counter')
-class MyCounter extends HTMLElement {
-  private count = 0;
-  @query('#display') displayEl?: HTMLElement;
-  @query('#shadow-input', { root: 'shadow' }) shadowInput?: HTMLInputElement;
+@elementDefine('input-field')
+class InputField extends HTMLElement {
+  @attributeHost('value', { connectedInitialize: true })
+  value: string = '';
+
+  @attributeHost('disabled')
+  disabled: boolean = false;
 
+  @attributeHost('count')
+  count: number = 0;
+
+  @onConnectedInnerHtml
+  render() {
+    return `
+      <input type="text" value="${this.value}" ${this.disabled ? 'disabled' : ''}>
+      <p>Count: ${this.count}</p>
+    `;
+  }
+}
+```
+
+**Options:**
+- `connectedInitialize: true` - Push class value to DOM on connect
+- `connectedInitialize: false` - Pull DOM value on connect (default)
+- Auto-converts: `String`, `Number`, `Boolean`
+
+#### 11. `@changedAttributeHost(name)`
+Reactive handler triggered when attribute changes.
+
+```typescript
+@elementDefine('reactive-input')
+class ReactiveInput extends HTMLElement {
+  private internalValue = '';
+
+  @changedAttributeHost('value')
+  onValueChange(newVal: string, oldVal: string) {
+    console.log(`Value changed: ${oldVal} → ${newVal}`);
+    this.internalValue = newVal;
+    this.updateDisplay();
+  }
+
+  updateDisplay() {
+    const input = this.querySelector('input') as HTMLInputElement;
+    if (input) input.value = this.internalValue;
+  }
+}
+```
+
+#### 12. `@setAttribute(name, options?)`
+Reflect method's return value to a DOM attribute. One-way binding (class → DOM).
+
+```typescript
+@elementDefine('status-badge')
+class StatusBadge extends HTMLElement {
+  private status: 'active' | 'inactive' | 'pending' = 'pending';
+
+  // Reflect status to DOM attribute
+  @setAttribute('data-status')
+  getStatus() {
+    return this.status;
+  }
+
+  // Reflect computed data to attribute
   @setAttribute('count')
-  updateCount(val: number) { return val; } // Sets 'count' attribute in DOM
+  getItemCount() {
+    return this.getItems().length.toString();
+  }
 
-  @setAttribute('shadow-value', { root: 'shadow' })
-  updateShadowValue(val: string) { return val; } // Sets attribute on shadow DOM element
+  // Reflect to Shadow DOM element
+  @setAttribute('aria-label', { root: 'shadow' })
+  getAriaLabel() {
+    return `Status is ${this.status}`;
+  }
+
+  private getItems() {
+    return [];
+  }
+
+  @onConnectedInnerHtml
+  render() {
+    return `
+      <div class="badge" data-status="${this.status}">
+        Status: ${this.status}
+      </div>
+    `;
+  }
 
-  @changedAttribute('count')
-  onCountChange(newVal: string, oldVal: string, name: string) {
-    this.count = Number(newVal);
-    // Surgical Update: Only update the specific node
-    if (this.displayEl) this.displayEl.textContent = newVal;
+  // Change status and update DOM
+  setStatus(newStatus: typeof this.status) {
+    this.status = newStatus;
+    this.getStatus(); // Triggers @setAttribute update
   }
 }
 ```
 
-### 4. Powerful Queries (`@query`, `@queryAll`)
-Inject internal elements or host instances directly into properties. Assigning `null` or `[]` to these properties will surgically remove the target elements from the DOM.
+**Key Differences:**
+- **`@attributeHost`** - Two-way binding: DOM ↔ Class (Bidirectional)
+- **`@setAttribute`** - One-way binding: Class → DOM (Method return reflects to attribute)
+- **`@changedAttributeHost`** - Watch DOM attribute changes (Reactive handler)
+
+**Options:**
+- `root: 'light'` - Set attribute on light DOM element
+- `root: 'shadow'` - Set attribute on shadow DOM element
+- `root: 'auto'` - Auto-detect (default)
+
+---
+
+### Query & DOM Selection Decorators
+
+#### 13. `@query(selector, options?)`
+Inject a single element into a property.
+
+```typescript
+@elementDefine('form-handler')
+class FormHandler extends HTMLElement {
+  @query('#submit-btn') submitBtn?: HTMLButtonElement;
+  @query('.form-field', { root: 'shadow' }) formField?: HTMLElement;
+  @query(':host') self?: HTMLElement;
+
+  @onConnectedInnerHtml({ useShadow: true })
+  render() {
+    return `
+      <div class="form-field">
+        <input type="text" placeholder="Enter name">
+        <button id="submit-btn">Submit</button>
+      </div>
+    `;
+  }
+}
+```
+
+**Root Options:**
+- `'auto'` (default) - Search shadow DOM first, then light DOM
+- `'light'` - Search only light DOM
+- `'shadow'` - Search only shadow DOM
+- `'all'` - Search both, return `[lightElements, shadowElements]`
+
+**Special Targets:**
+```typescript
+@query(':host') self?: HTMLElement;           // Element itself
+@query(':parentHost') parent?: HTMLElement;   // Parent SWC component
+@query(':appHost') app?: SwcAppInterface;     // Nearest <swc-app>
+@query(':window') win?: Window;               // Global window
+@query(':document') doc?: Document;           // Global document
+```
+
+#### 14. `@queryAll(selector, options?)`
+Inject multiple elements as an array.
+
+```typescript
+@elementDefine('list-renderer')
+class ListRenderer extends HTMLElement {
+  @queryAll('.item') items?: HTMLElement[];
+  @queryAll('button', { root: 'shadow' }) buttons?: HTMLButtonElement[];
+
+  getItemCount() {
+    return this.items?.length ?? 0;
+  }
+}
+```
+
+---
+
+### Event & Messaging Decorators
+
+#### 15. `@addEventListener(selector, event, options?)`
+Declarative event binding with automatic delegation.
+
+```typescript
+@elementDefine('todo-app')
+class TodoApp extends HTMLElement {
+  private todos: any[] = [];
+
+  // Direct binding to specific element
+  @addEventListener('#add-btn', 'click')
+  onAddTodo(event: MouseEvent) {
+    console.log('Add button clicked');
+  }
+
+  // Event delegation for dynamic elements
+  @addEventListener('.todo-item', 'click', { delegate: true })
+  onTodoClick(event: MouseEvent, hostSet: any, target: HTMLElement) {
+    const itemId = target.getAttribute('data-id');
+    console.log('Clicked todo:', itemId);
+  }
+
+  // Global window events
+  @addEventListener(':window', 'resize', { removeOnDisconnected: true })
+  onWindowResize(event: Event) {
+    console.log('Window resized');
+  }
+
+  // Parent app events
+  @addEventListener(':appHost', 'custom-event')
+  onCustomEvent(event: CustomEvent) {
+    console.log('Event received:', event.detail);
+  }
+
+  @onConnectedInnerHtml
+  render() {
+    return `
+      <div>
+        <input type="text" id="todo-input" placeholder="Add todo...">
+        <button id="add-btn">Add</button>
+        <ul class="todo-list">
+          ${this.todos.map(t => `
+            <li class="todo-item" data-id="${t.id}">${t.text}</li>
+          `).join('')}
+        </ul>
+      </div>
+    `;
+  }
+}
+```
+
+**Features:**
+- ✅ Direct binding to static selectors
+- ✅ Event delegation for dynamic elements
+- ✅ Global events (`:window`, `:document`)
+- ✅ Parent communication (`:parentHost`, `:appHost`)
+- ✅ Auto-cleanup on `disconnectedCallback`
+
+#### 16. `@emitCustomEvent(target, type, options?)`
+Emit custom events to component hierarchy or global targets.
+
+```typescript
+@elementDefine('auth-panel')
+class AuthPanel extends HTMLElement {
+  constructor(private authService: AuthService) { super(); }
+
+  // Emit to parent app when user logs in
+  @emitCustomEvent(':appHost', 'user-logged-in')
+  async onLogin() {
+    const user = await this.authService.login();
+    return { user, timestamp: Date.now() };
+  }
+
+  // Emit globally when logout happens
+  @emitCustomEvent(':window', 'user-logged-out')
+  async onLogout() {
+    await this.authService.logout();
+    return { timestamp: Date.now() };
+  }
+
+  // Emit to direct parent
+  @emitCustomEvent(':parentHost', 'child-ready')
+  notifyParent() {
+    return { childElement: this };
+  }
+
+  @onConnectedInnerHtml
+  render() {
+    return `
+      <div>
+        <button swc-on-click="$host.onLogin()">Login</button>
+        <button swc-on-click="$host.onLogout()">Logout</button>
+      </div>
+    `;
+  }
+}
+
+// Listen to the emitted event
+@elementDefine('user-widget')
+class UserWidget extends HTMLElement {
+  private user: any = null;
+
+  @addEventListener(':appHost', 'user-logged-in')
+  onUserLoggedIn(event: CustomEvent) {
+    this.user = event.detail.user;
+    this.render();
+  }
+
+  @onConnectedInnerHtml
+  render() {
+    return `<p>User: ${this.user?.name ?? 'Anonymous'}</p>`;
+  }
+}
+```
+
+**Emission Targets:**
+- `':appHost'` - Nearest parent `<swc-app>` (contained within app)
+- `':parentHost'` - Direct parent SWC component
+- `':firstHost'` / `':lastHost'` - First/last component in hierarchy
+- `':firstAppHost'` / `':lastAppHost'` - First/last `<swc-app>` in hierarchy
+- `':hosts'` - All SWC ancestors
+- `':appHosts'` - All `<swc-app>` ancestors
+- `':window'` - Global window (all apps can listen)
+- `':document'` - Global document
+- `selector` - CSS selector (emit to matching elements)
+
+**Options:**
+- `bubbles: true` (default) - Event bubbles up
+- `composed: true` (default) - Event crosses Shadow DOM boundary
+- `cancelable: true` - Event can be canceled
+- `root: 'auto' | 'light' | 'shadow'` - Where to find target elements
+
+---
+
+### DOM Manipulation Decorators
+
+#### 17. `@applyNode(selector, options?)`
+Surgically add, update, or replace DOM nodes at specific positions.
+
+```typescript
+@elementDefine('counter-display')
+class CounterDisplay extends HTMLElement {
+  private count = 0;
+
+  // Replace all children with new content
+  @applyNode('#display', { position: 'replaceChildren' })
+  updateDisplayCount() {
+    return `<span>${this.count}</span>`;
+  }
+
+  // Append to container
+  @applyNode('#history', { position: 'beforeEnd' })
+  addHistoryEntry() {
+    return `<p>Count was: ${this.count}</p>`;
+  }
+
+  // Set HTML content
+  @applyNode('#status', { position: 'innerHtml' })
+  setStatus() {
+    return `<strong>Status: Active</strong>`;
+  }
+
+  // Set text content
+  @applyNode('#counter', { position: 'innerText' })
+  updateCounter() {
+    return this.count.toString();
+  }
+
+  @onConnectedInnerHtml
+  render() {
+    return `
+      <div id="display">0</div>
+      <div id="counter">0</div>
+      <div id="status"></div>
+      <button swc-on-click="$host.count++; $host.updateDisplayCount?.()">+</button>
+      <div id="history"></div>
+    `;
+  }
+}
+```
+
+**Position Options:**
+- `'beforeEnd'` (default) - Append to end
+- `'afterBegin'` - Prepend to start
+- `'beforeBegin'` - Insert before element
+- `'afterEnd'` - Insert after element
+- `'replace'` - Replace entire element
+- `'replaceChildren'` - Replace all children
+- `'innerHtml'` - Set `innerHTML`
+- `'innerText'` - Set `innerText`
+
+---
+
+### Dependency Injection & Singleton
+
+#### 18. `@Sim`
+Marks a class as a **Singleton** in the `<swc-app>` DI container for **constructor injection**.
+
+**Two DI Mechanisms:**
+
+1. **Lifecycle DI** (`@onBeforeConnected`, etc.) - ❌ NO `@Sim` needed
+   - Works on any `@elementDefine` component
+   - Services injected via method parameters
+   - Can be used outside `<swc-app>`
+
+2. **Constructor DI** - ✅ `@Sim` REQUIRED
+   - Only works inside `<swc-app>` boundary
+   - Both provider AND consumer need `@Sim`
+   - Singleton pattern within the app
+
+**Example: Both Approaches**
+
+```typescript
+// ============ SERVICE ============
+@Sim
+class CartService {
+  private items: any[] = [];
+  
+  addItem(item: any) {
+    this.items.push(item);
+  }
+  
+  getItems() {
+    return this.items;
+  }
+}
+
+// ============ APPROACH 1: Lifecycle DI (NO @Sim needed) ============
+@elementDefine('cart-header')  // ← NO @Sim
+class CartHeader extends HTMLElement {
+  #cartService: CartService;
+
+  @onBeforeConnected
+  async setup(cartService: CartService) {  // ← Injected here
+    this.#cartService = cartService;
+    await this.#cartService.load?.();
+  }
+
+  @onConnectedInnerHtml
+  render() {
+    return `<div>Cart: ${this.#cartService?.getItems().length}</div>`;
+  }
+}
+
+// ============ APPROACH 2: Constructor DI (NEEDS @Sim) ============
+@Sim  // ← Required for constructor injection
+@elementDefine('cart-component')
+class CartComponent extends HTMLElement {
+  // Constructor injection - CartService is auto-injected
+  constructor(private cartService: CartService) { super(); }
+
+  @onConnectedInnerHtml
+  render() {
+    const itemCount = this.cartService.getItems().length;
+    return `<div>Items: ${itemCount}</div>`;
+  }
+}
+
+// ============ ROUTING & BOOTSTRAP ============
+@Sim
+@Router({
+  path: '/',
+  route: {
+    '/home': HomePage,
+    '/cart': CartComponent  // Constructor DI works here
+  }
+})
+@elementDefine('app-router')
+class AppRouter extends HTMLElement {
+  @onConnectedInnerHtml
+  render() {
+    return `<div><slot></slot></div>`;
+  }
+}
+
+// ============ HTML ============
+<!-- Lifecycle DI works OUTSIDE <swc-app> -->
+<cart-header></cart-header>
+
+<!-- Constructor DI works INSIDE <swc-app> -->
+<swc-app swc-get-application-config="appConfig()">
+  <app-router></app-router>
+</swc-app>
+
+<script>
+  window.appConfig = () => ({
+    rootRouter: AppRouter,
+    routeType: 'element',
+    path: '/'
+  });
+</script>
+```
+
+**When to Use Each:**
+
+| Scenario | Use | Mark |
+|----------|-----|------|
+| Component needs services anywhere | Lifecycle DI in `@onBeforeConnected` | NO `@Sim` |
+| Component inside `<swc-app>` route | Constructor DI | YES `@Sim` |
+| Service/Singleton registration | Register in DI container | YES `@Sim` |
+| Standalone component | Lifecycle DI | NO `@Sim` |
+
+**Key Points:**
+- `@Sim` = Mark as singleton for **constructor injection inside `<swc-app>`**
+- Lifecycle DI = Inject via method parameters (works everywhere, no `@Sim`)
+- Each `<swc-app>` has its own isolated DI container
+- Services are local to their `<swc-app>` instance (for constructor DI)
+
+---
+
+## Core Decorators
 
 #### Root Options
 The `root` option controls which DOM tree is searched:
@@ -117,7 +765,7 @@ Standard CSS selectors support precise root control.
 @query('.btn', { root: 'shadow' }) shadowBtn!: HTMLButtonElement;
 ```
 
-### 5. Smart Event Binding (`@addEventListener`)
+### 5. Event Binding (`@addEventListener`)
 
 Bind events declaratively with built-in **Event Delegation**, **Auto-Cleanup**, and **Context Injection**. Events flow through the component hierarchy with full access to parent scopes.
 
@@ -128,6 +776,43 @@ Bind events declaratively with built-in **Event Delegation**, **Auto-Cleanup**,
 - **Context Injection**: Receive `$host`, `$parentHost`, `$appHost` automatically
 - **Special Targets**: `:window`, `:document`, `:parentHost`, `:appHost`
 
+#### 6. Surgical DOM Manipulation (`@applyNode`)
+
+Surgically add, prepend, insert, or replace nodes with a single decorator. Perfect for dynami content updates without imperatively manipulating the DOM.
+
+```typescript
+@elementDefine('list-manager')
+class ListManager extends HTMLElement {
+  @applyNode('#list') addItem() { 
+    return '<li>New Item</li>'; 
+  }
+
+  @applyNode('#header', { position: 'afterBegin' }) prependTitle() { 
+    return '<h1>Title</h1>'; 
+  }
+
+  @applyNode('#item', { position: 'replace' }) replaceItem() { 
+    return '<div>Replaced Content</div>'; 
+  }
+}
+```
+
+**Positions:**
+- `'beforeEnd'` (default): Append to end of target
+- `'afterBegin'`: Prepend to start of target
+- `'beforeBegin'`: Insert before target
+- `'afterEnd'`: Insert after target
+- `'replace'`: Replace entire target element
+- `'replaceChildren'`: Replace all children of target element
+- `'innerHtml'`: Set target's `innerHTML` with string content
+- `'innerText'`: Set target's `innerText` with string content
+
+---
+
+### 6. DOM Manipulation (`@applyNode`)
+
+Surgically add, prepend, insert, or replace nodes. Perfect for reactive updates without full re-renders.
+
 #### Pattern 1: Direct Binding & Static Selectors
 
 ```typescript
@@ -257,17 +942,11 @@ class ResponsiveLayout extends HTMLElement {
 }
 ```
 
-### 6. `@replaceChildren(selector)`
-
-Surgically replaces the children of a target element. Perfect for dynamic content updates without full-page re-renders.
+### 7. Dynamic Content Updates with `@applyNode`
 
-**Use Cases:**
-- Search results updating without page reload
-- Filtering product lists
-- Content swaps in tabbed interfaces
-- Live data refreshes
+#### Advanced Patterns
 
-#### Pattern 1: Simple Content Replacement
+**Pattern 1: Simple Content Replacement with `replaceChildren`**
 
 ```typescript
 @Sim
@@ -326,7 +1005,21 @@ class SearchResults extends HTMLElement {
 }
 ```
 
-#### Pattern 2: Tab Content Switching
+**Pattern 2: Setting HTML Content**
+
+```typescript
+@applyNode('#message', { position: 'innerHtml' })
+displayMessage(text: string) {
+  return `<p style="color: blue;">${text}</p>`;
+}
+
+@applyNode('#count', { position: 'innerText' })
+updateCounter() {
+  return this.count.toString();
+}
+```
+
+**Pattern 3: Tab Content Switching
 
 ```typescript
 @Sim
@@ -370,7 +1063,7 @@ class TabbedPanel extends HTMLElement {
 }
 ```
 
-### 7. `@appendChild(selector, options?)`
+### 8. `@appendChild(selector, options?)`
 
 Appends or inserts the method's return value relative to a target element. Perfect for dynamically building lists, stacking notifications, or adding children without replacing existing content.
 
@@ -767,66 +1460,49 @@ Unlike traditional SPAs that force a global router and monolithic state tree, SW
 - **Decentralized DI**: Service dependencies are resolved within app scope, enabling natural code splitting and lazy loading
 - **Island Architecture**: Apps boot only when needed, reducing initial JavaScript payload
 
+### ✨ Complete Commerce App Example
+
+See the **[Commerce Example](examples/commerce/)** for a production-ready SPA implementation featuring:
+
+- **Multi-page routing** (Home, Product Detail, Cart, Orders)
+- **Service layer** (ProductService, CartService, OrderService) with localStorage persistence
+- **Reactive state management** using BehaviorSubject
+- **Modern UI design** with gradient backgrounds, responsive layouts, and sticky header
+- **Product images** from dynamic CDN (picsum.photos)
+- **DI integration** with `@onBeforeConnected` lifecycle hooks
+- **Shadow DOM** for style encapsulation
+- **Real-time updates** with cart count synchronization
+
+```bash
+cd packages/@dooboostore/simple-web-component/examples/commerce
+pnpm install
+pnpm build
+```
+
+This example demonstrates all decorators working together in a real-world e-commerce scenario.
+
 ---
 
-### 1. Isolated App Scopes & Micro-Frontend Pattern
+### Advanced Patterns
+
+#### Isolated App Scopes & Micro-Frontend Pattern
 
-Create a self-contained universe with `<swc-app>`. The tag acts as a **boundary** where routing, DI, and state are completely isolated from sibling apps.
+Create self-contained apps with `<swc-app>` where routing and DI are completely isolated:
 
 ```html
-<!-- Example: Multi-tenant dashboard with independent feature modules -->
 <div class="dashboard">
-  <!-- User Management Module -->
   <swc-app swc-get-application-config="createUserModule()"></swc-app>
-  
-  <!-- Reports Module -->
   <swc-app swc-get-application-config="createReportsModule()"></swc-app>
-  
-  <!-- Settings Module -->  
-  <swc-app swc-get-application-config="createSettingsModule()"></swc-app>
 </div>
-
-<script>
-  // Each module is bootstrapped independently
-  window.createUserModule = (host) => ({
-    rootRouter: UserManagementRouter,  // Entry point router
-    routeType: 'element',              // 'element' (in-memory), 'hash', or 'path'
-    path: '/dashboard',                // Initial route
-    window: window                     // Optional: SSR virtual window
-  });
-
-  window.createReportsModule = (host) => ({
-    rootRouter: ReportsRouter,
-    routeType: 'element',
-    path: '/overview',
-    window: window
-  });
-
-  // External programmatic navigation (from parent scope)
-  function switchUserModule(userId) {
-    const userApp = document.querySelectorAll('swc-app')[0];
-    userApp.routing(`/user/${userId}`); // Navigate within the isolated app
-  }
-
-  // Inter-app communication (if needed)
-  function notifyModules(eventName, data) {
-    document.querySelectorAll('swc-app').forEach(app => {
-      app.dispatchEvent(new CustomEvent(eventName, { detail: data }));
-    });
-  }
-</script>
 ```
 
-**Key Insights:**
-- Each `<swc-app>` is **completely isolated**: one app's router state doesn't affect another
-- No global namespace pollution: services, routes, and components live within app scope
-- Perfect for **dashboard layouts, plugin architectures, and federated frontends**
+Each app is independent: state, services, and routes don't cross boundaries.
 
 ---
 
-### 2. Advanced DI-Powered Routing with Lifecycle Hooks
+#### DI-Powered Routing with Lifecycle Hooks
 
-SWC routing leverages **Dependency Injection** to inject services directly into components, enabling dynamic route guards, permission checks, and data preloading.
+SWC routing injects services directly into components using `canActivate` lifecycle hook for permission checks and data preloading:
 
 ```typescript
 // ============================================