@dooboostore/simple-web-component 1.0.21 → 1.0.23

package/README.md

@@ -30,67 +30,1037 @@ 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('my-el')
-class MyEl extends HTMLElement {
+@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('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>
+    `;
+  }
+}
+```
+
+**Options:**
+- `useShadow: true` - Render to Shadow DOM (style encapsulation)
+- `useShadow: false` - Render to Light DOM (default)
+
+---
+
+### Attribute & Property Decorators
+
+#### 10. `@attributeHost(name, options?)`
+Bidirectional attribute binding with automatic type conversion.
+
+```typescript
+@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(selector, name, options?)`
+Reflect method's return value to a target element's DOM attribute. One-way binding (class → DOM).
+
+```typescript
+@elementDefine('status-badge')
+class StatusBadge extends HTMLElement {
+  private status: 'active' | 'inactive' | 'pending' = 'pending';
+  private items: any[] = [];
+
+  // Reflect status to host element's data-status attribute
+  @setAttribute(':host', 'data-status')
+  getStatus() {
+    return this.status;
+  }
+
+  // Reflect computed data to specific element
+  @setAttribute('#count-display', 'data-count')
+  getItemCount() {
+    return this.items.length.toString();
+  }
+
+  // Reflect to Shadow DOM element's aria-label
+  @setAttribute('.badge-label', 'aria-label', { root: 'shadow' })
+  getAriaLabel() {
+    return `Status is ${this.status}`;
+  }
+
+  @onConnectedInnerHtml
+  render() {
+    return `
+      <div data-status="${this.status}">
+        <span class="badge-label">Status: ${this.status}</span>
+        <span id="count-display" data-count="${this.items.length}">Items: ${this.items.length}</span>
+      </div>
+    `;
+  }
+
+  // Change status and update DOM attributes
+  setStatus(newStatus: typeof this.status) {
+    this.status = newStatus;
+    this.getStatus();        // Updates :host[data-status]
+    this.getItemCount();     // Updates #count-display[data-count]
+    this.getAriaLabel();     // Updates .badge-label[aria-label]
+  }
+}
+```
+
+**Signature:**
+- `@setAttribute(selector, attributeName, options?)`
+- Returns method's value → reflects to target's attribute
+
+**Selectors:**
+- `':host'` - The component itself
+- `'#element-id'` - Element by ID
+- `'.class-name'` - Element by class
+- `selector` - Any CSS selector
+
+#### 12b. `@setAttributeHost(name, options?)` - Shorthand for `:host`
+Simplified version of `@setAttribute` that always targets `:host`.
+
+```typescript
+@elementDefine('counter')
+class Counter extends HTMLElement {
+  private count = 0;
+
+  // Equivalent to @setAttribute(':host', 'aria-label')
+  @setAttributeHost('aria-label')
+  getAriaLabel() {
+    return `Count is ${this.count}`;
+  }
+
+  @setAttributeHost('data-count')
+  getCountValue() {
+    return this.count.toString();
+  }
+
+  @setAttributeHost('aria-disabled')
+  getDisabledState() {
+    return (this.count >= 10).toString();
+  }
+
+  @onConnectedInnerHtml
+  render() {
+    return `
+      <div>
+        <p>Count: ${this.count}</p>
+        <button swc-on-click="$host.increment()">+</button>
+      </div>
+    `;
+  }
+
+  increment() {
+    this.count++;
+    this.getAriaLabel();      // Updates :host[aria-label]
+    this.getCountValue();     // Updates :host[data-count]
+    this.getDisabledState();  // Updates :host[aria-disabled]
+  }
+}
+```
+
+**Usage:**
+```typescript
+// Full form
+@setAttribute(':host', 'data-status')
+// vs
+// Shorthand for :host
+@setAttributeHost('data-status')
+```
+
+**Key Differences:**
+- **`@attributeHost`** - Two-way binding: DOM ↔ Class (Bidirectional)
+- **`@setAttribute`** - One-way binding: Class → DOM (Any selector)
+- **`@setAttributeHost`** - One-way binding: Class → DOM (`:host` only)
+- **`@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;
+  }
+}
+```
+
+#### 14b. Removing Elements via `null` or `undefined`
+Both `@query` and `@queryAll` support element removal by setting the property to `null` or `undefined`. This triggers automatic removal of the matching element(s).
+
+```typescript
+@elementDefine('todo-list')
+class TodoList extends HTMLElement {
+  @query('.notification') notification?: HTMLElement;
+  @queryAll('.todo-item') todoItems?: HTMLElement[];
+
+  removeNotification() {
+    // Setting to null triggers automatic removal
+    this.notification = null;
+  }
+
+  removeTodoItem(id: string) {
+    // Find and remove a specific todo item
+    const item = this.querySelector(`[data-id="${id}"]`);
+    if (item) {
+      // Setting @query to null removes the element from DOM
+      this.notification = null;
+    }
+  }
+
+  clearAllTodos() {
+    // Setting @queryAll to null/undefined removes all matching elements
+    this.todoItems = null;  // Removes all .todo-item elements
+  }
+
+  @onConnectedInnerHtml
+  render() {
+    return `
+      <div class="notification">New todos available!</div>
+      <ul>
+        <li class="todo-item" data-id="1">Task 1</li>
+        <li class="todo-item" data-id="2">Task 2</li>
+        <li class="todo-item" data-id="3">Task 3</li>
+      </ul>
+      <button swc-on-click="$host.removeNotification()">Clear Notification</button>
+      <button swc-on-click="$host.clearAllTodos()">Clear All Tasks</button>
+    `;
+  }
+}
+```
+
+**Removal Rules:**
+- `@query`: Setting to `null` or `undefined` removes the single element
+- `@queryAll`: Setting to `null` or `undefined` removes all matching elements
+- Special selectors (`:host`, `:window`, `:document`, etc.) are **NOT removed** (protected)
+- Only affects Light DOM by default; use `{ root: 'shadow' }` to remove from Shadow DOM
+
+**Use Cases:**
+- Close notification banners
+- Clear dynamic list items
+- Remove temporary overlays
+- Clean up modal dialogs
+
+---
+
+### 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>`;
   }
 }
 ```
 
-### 3. Modern Attribute Management
-SWC uses a **Method-Based Reflection** approach. You control exactly how data flows.
+**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
+
+---
 
-**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.
+### DOM Manipulation 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.
+#### 17. `@applyNode(selector, options?)`
+Surgically add, update, or replace DOM nodes at specific positions.
 
 ```typescript
-@elementDefine('my-counter')
-class MyCounter extends HTMLElement {
+@elementDefine('counter-display')
+class CounterDisplay extends HTMLElement {
   private count = 0;
-  @query('#display') displayEl?: HTMLElement;
-  @query('#shadow-input', { root: 'shadow' }) shadowInput?: HTMLInputElement;
+  private errorMessage = '';
+
+  // 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>`;
+  }
 
-  @setAttribute('count')
-  updateCount(val: number) { return val; } // Sets 'count' attribute in DOM
+  // Set HTML content
+  @applyNode('#status', { position: 'innerHtml' })
+  setStatus() {
+    return `<strong>Status: Active</strong>`;
+  }
 
-  @setAttribute('shadow-value', { root: 'shadow' })
-  updateShadowValue(val: string) { return val; } // Sets attribute on shadow DOM element
+  // Set text content
+  @applyNode('#counter', { position: 'innerText' })
+  updateCounter() {
+    return this.count.toString();
+  }
 
-  @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;
+  // Remove element if condition is truthy
+  @applyNode('#error-banner', { position: 'remove' })
+  dismissError() {
+    return this.errorMessage === '';  // Remove if no error
+  }
+
+  @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>
+      <div id="error-banner" style="display: ${this.errorMessage ? 'block' : 'none'};"></div>
+    `;
   }
 }
 ```
 
-### 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.
+**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`
+- `'remove'` - Remove element if returned value is truthy
+
+**Root Option:**
+Control which DOM tree is searched with the `root` option:
+- `'auto'` (default) - Search shadow DOM first, then light DOM
+- `'shadow'` - Search only shadow DOM
+- `'light'` - Search only light DOM
+- `'all'` - Search all ancestors
+
+#### Convenience Decorators
+
+Shorthand decorators for common position-specific operations:
+
+**Position-Specific Variants:**
+```typescript
+@applyBeforeBeginNode('#target') prependTarget() { return `<div>Before</div>`; }
+@applyAfterBeginNode('#target') afterBeginTarget() { return `<div>After Begin</div>`; }
+@applyBeforeEndNode('#target') beforeEndTarget() { return `<div>Before End</div>`; }
+@applyAfterEndNode('#target') afterEndTarget() { return `<div>After</div>`; }
+@applyReplaceNode('#target') replaceTarget() { return `<div>Replaced</div>`; }
+@applyReplaceChildrenNode('#target') replaceChildrenTarget() { return `<div>New Children</div>`; }
+@applyInnerHtmlNode('#target') setInnerHtml() { return `<b>Bold</b>`; }
+@applyInnerTextNode('#target') setInnerText() { return 'Plain text'; }
+@applyRemoveNode('#target') removeTarget() { return true; }
+```
+
+**Host-Targeted Variants (`:host` selector):**
+```typescript
+@applyBeforeBeginNodeHost() prependHost() { return `<div>Before Host</div>`; }
+@applyAfterBeginNodeHost() afterBeginHost() { return `<div>After Begin</div>`; }
+@applyBeforeEndNodeHost() beforeEndHost() { return `<div>Before End</div>`; }
+@applyAfterEndNodeHost({ root: 'shadow' }) afterEndHost() { return `<div>After Host</div>`; }
+@applyReplaceNodeHost() replaceHost() { return `<div>Replaced Host</div>`; }
+@applyReplaceChildrenNodeHost() replaceChildrenHost() { return `<div>Shadow Children</div>`; }
+@applyInnerHtmlNodeHost() setHostInnerHtml() { return `<b>Host Content</b>`; }
+@applyInnerTextNodeHost() setHostInnerText() { return 'Host text'; }
+@applyRemoveNodeHost() removeHost() { return this.shouldRemove; }
+```
+
+---
+
+#### 18. `@setStyle(selector, options?)` / `@updateStyle(selector, options?)` / `@removeStyle(selector, options?)`
+
+Manipulate CSS styles on elements with full Shadow DOM support.
+
+**Core Features:**
+- `@setStyle` - Set inline style (replaces all)
+- `@updateStyle` - Merge with existing styles
+- `@removeStyle` - Remove specific properties
+- `root` option for Shadow DOM / Light DOM targeting
+- Support for multiple elements with `querySelectorAll`
+
+```typescript
+@elementDefine('styled-component')
+class StyledComponent extends HTMLElement {
+  private isActive = false;
+
+  @setStyle('.button', { root: 'shadow' })
+  setPrimaryButtonStyle() {
+    return {
+      backgroundColor: '#0066cc',
+      color: 'white',
+      padding: '10px 20px',
+      border: 'none',
+      borderRadius: '4px'
+    };
+  }
+
+  @updateStyle('.button', { root: 'shadow' })
+  highlightButton() {
+    return {
+      boxShadow: '0 0 10px rgba(0, 102, 204, 0.5)',
+      transform: 'scale(1.05)'
+    };
+  }
+
+  @removeStyle('.button', { root: 'shadow' })
+  clearHighlight() {
+    return ['boxShadow', 'transform'];
+  }
+
+  @onConnectedInnerHtml({ useShadow: true })
+  render() {
+    return `
+      <style>
+        .button { cursor: pointer; transition: all 0.2s; }
+      </style>
+      <button class="button">Styled</button>
+    `;
+  }
+}
+```
+
+**Host-Targeted Variants:**
+```typescript
+@setStyleHost({ root: 'shadow' })
+setHostStyle() {
+  return { display: 'flex', gap: '10px' };
+}
+
+@updateStyleHost({ root: 'shadow' })
+updateHostStyle() {
+  return { backgroundColor: '#f0f0f0' };
+}
+
+@removeStyleHost({ root: 'shadow' })
+clearHostStyle() {
+  return ['backgroundColor'];
+}
+```
+
+---
+
+#### 19. `@setClassList(selector, options?)` / `@addClassList(selector, options?)` / `@removeClassList(selector, options?)` / `@toggleClassList(selector, options?)` / `@updateClassList(selector, options?)`
+
+Manipulate CSS classes on elements declaratively with Shadow DOM support.
+
+**Core Features:**
+- `@addClassList` - Add classes
+- `@removeClassList` - Remove classes
+- `@toggleClassList` - Toggle classes (returns boolean or bool array)
+- `@setClassList` - Replace all classes
+- `@updateClassList` - Merge with existing classes
+- `root` option for DOM layer targeting
+- Support for multiple elements
+
+```typescript
+@elementDefine('tab-component')
+class TabComponent extends HTMLElement {
+  activeTab = 'home';
+
+  @addClassList('.tab', { root: 'shadow' })
+  addTabClasses() {
+    return ['interactive', 'focusable'];
+  }
+
+  @toggleClassList('.tab', { root: 'shadow' })
+  toggleActiveTab() {
+    return this.activeTab === 'home';  // Returns boolean for all matched elements
+  }
+
+  @removeClassList('.tab-inactive', { root: 'shadow' })
+  removeInactiveClass() {
+    return ['disabled'];
+  }
+
+  @setClassList('.tab-pane', { root: 'shadow' })
+  updateTabPane() {
+    return [`pane-${this.activeTab}`, 'content'];
+  }
+
+  @onConnectedInnerHtml({ useShadow: true })
+  render() {
+    return `
+      <style>
+        .tab { cursor: pointer; padding: 10px; }
+        .tab.active { border-bottom: 2px solid blue; }
+      </style>
+      <div class="tabs">
+        <div class="tab" swc-on-click="$host.activeTab='home'; $host.toggleActiveTab?.();">Home</div>
+        <div class="tab" swc-on-click="$host.activeTab='about'; $host.toggleActiveTab?.();">About</div>
+      </div>
+      <div class="tab-pane">Content here</div>
+    `;
+  }
+}
+```
+
+**Host-Targeted Variants:**
+```typescript
+@addClassListHost({ root: 'shadow' })
+addHostClasses() {
+  return ['component', 'interactive'];
+}
+
+@removeClassListHost({ root: 'shadow' })
+removeHostClasses() {
+  return ['loading'];
+}
+
+@toggleClassListHost({ root: 'shadow' })
+toggleHostClass() {
+  return this.isOpen;  // Apply 'open' class if true
+}
+
+@setClassListHost({ root: 'shadow' })
+setHostClasses() {
+  return this.isOpen ? ['open', 'expanded'] : ['closed'];
+}
+
+@updateClassListHost({ root: 'shadow' })
+updateHostClasses() {
+  return ['visible'];
+}
+```
+
+---
+
+### Dependency Injection & Singleton
+
+#### 20. `@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 +1087,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 +1098,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 +1264,11 @@ class ResponsiveLayout extends HTMLElement {
 }
 ```
 
-### 6. `@replaceChildren(selector)`
+### 7. Dynamic Content Updates with `@applyNode`
 
-Surgically replaces the children of a target element. Perfect for dynamic content updates without full-page re-renders.
-
-**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 +1327,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 +1385,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.
 
@@ -577,6 +1592,26 @@ class TextRenderer extends HTMLElement {
 }
 ```
 
+### 2b. `commentNode` - HTML Comments
+
+Create HTML comment nodes (useful for debugging, markers, or template documentation).
+
+```typescript
+@elementDefine('debug-component')
+class DebugComponent extends HTMLElement {
+  @appendChild('#debug-area')
+  addDebugComment(message: string) {
+    // Create HTML comment node
+    return commentNode`DEBUG: ${message} at ${new Date().toISOString()}`;
+  }
+
+  @onConnectedInnerHtml
+  render() {
+    return `<div id="debug-area"></div>`;
+  }
+}
+```
+
 ### 3. Element Factories (`html***Element`)
 
 Specific factories for common tags. Each returns a **typed element instance**.
@@ -767,66 +1802,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
 // ============================================