@dooboostore/simple-web-component 1.0.14 → 1.0.16

package/README.md

@@ -1,918 +1,282 @@
-# @dooboostore/simple-web-component
+# @dooboostore/simple-web-component (SWC)
 
-> **Web Standards. Zero Virtual DOM. Surgical Updates.**
+> **"Pure, Standards-Compliant, and Blazing Fast Web Components Framework."**
 
-Build reactive UIs using nothing but the browser's own APIs — Custom Elements, Shadow DOM, Proxy, and MutationObserver.  
-No diffing. No runtime overhead. Just the DOM, done right.
+`simple-web-component` (SWC) is a minimalist library designed for building high-performance Web Components and Single Page Applications (SPA). It strips away heavy "magic" features like Proxy-based reactivity and continuous `MutationObserver` scans in favor of a **Pure Architecture** that stays out of your way while offering professional-grade Dependency Injection (DI) and Routing.
 
 ---
 
-## Why SWC?
+## 🚀 Why SWC?
 
-Most UI libraries bring their own runtime, their own DOM, their own rules.  
-SWC doesn't. It enhances what the browser already gives you.
-
-- **`{{expression}}`** — binds directly to text nodes and attributes. Only that node updates when data changes.
-- **`<template is="swc-for-of">`** — loop over a list using a real `<template>` tag. No custom syntax, no compiler.
-- **`swc-on-click="$host.save()"`** — call your component's method from any nested element. No event bubbling gymnastics.
-- **TypeScript decorators** — `@state`, `@attribute`, `@addEventListener` feel like Angular but weigh almost nothing.
+- **Zero Magic**: No Proxy traps, no Virtual DOM diffing. Predictive and standard-compliant.
+- **Native Inheritance**: Inherit directly from `HTMLElement`, `HTMLDivElement`, etc.
+- **Extreme Performance**: Ideal for high-load UIs (1,000+ nodes) with minimal memory overhead.
+- **Micro-Frontend Ready**: Independent routing and DI containers for every component scope.
+- **Standard-First**: Works directly with native Custom Elements, Shadow DOM, and Slots.
 
 ---
 
-## Installation
+## 📦 Installation & Setup
 
 ```bash
-pnpm add @dooboostore/simple-web-component reflect-metadata
-```
-
-```typescript
-// Entry point — must be first
-import 'reflect-metadata';
-```
-
-> **Safari** requires a polyfill for the `is` attribute:
-> ```bash
-> pnpm add @ungap/custom-elements
-> ```
-> ```html
-> <script src="https://unpkg.com/@ungap/custom-elements"></script>
-> ```
-
----
-
-## 30-Second Example
-
-```typescript
-import 'reflect-metadata';
-import { elementDefine, innerHtml, state, addEventListener } from '@dooboostore/simple-web-component';
-
-@elementDefine('my-counter')
-class MyCounter extends HTMLElement {
-  @state count = 0;
-
-  @innerHtml({ useShadow: true })
-  render() {
-    return `
-      <button id="btn">Clicked {{count}} times</button>
-      <p>{{count > 5 ? '🔥 On fire!' : 'Keep going...'}}</p>
-    `;
-  }
-
-  @addEventListener({ type: 'click', query: '#btn' })
-  onClick() { this.count++; }
-}
+npm install @dooboostore/simple-web-component reflect-metadata
 ```
 
+### Browser Support
+For **Safari** support of the `is` attribute, add this to your `<head>`:
 ```html
-<my-counter></my-counter>
+<script src="https://unpkg.com/@ungap/custom-elements"></script>
 ```
 
-That's it. No build config changes. No JSX. No virtual DOM.
-
 ---
 
-## The `<template>` Pattern — HTML-First Logic
-
-The most powerful feature of SWC is using the native `<template>` tag as a logic container.  
-Your HTML stays semantic. Your logic lives in the markup. No JS required to wire it up.
-
-### Loop — `<template is="swc-for-of">`
+## 💡 Core Decorators
 
-```html
-<ul class="user-list">
-  <template is="swc-for-of" id="user-loop" as-item="user" as-index="i">
-    <li>
-      <strong>#{{i}}</strong>: {{user.name}}
-      <span class="{{user.active ? 'badge-green' : 'badge-red'}}">
-        {{user.active ? 'Active' : 'Offline'}}
-      </span>
-    </li>
-  </template>
-</ul>
-```
-
-```typescript
-const loop = document.querySelector('#user-loop') as SwcForOf;
-loop.value = [
-  { name: 'Alice', active: true },
-  { name: 'Bob',   active: false },
-];
-
-// Reactive — push/splice trigger surgical DOM updates
-loop.value.push({ name: 'Carol', active: true });
-```
-
-The `<template>` tag is invisible by default. SWC uses it as a blueprint and stamps out clones for each item. The wrapper `<ul>` is untouched — it stays in the DOM exactly as you wrote it.
+### 1. `@elementDefine(config)`
+Registers the class as a custom element.
 
-### Conditional — `<template is="swc-if">`
-
-```html
-<template is="swc-if" id="alert-box">
-  <div class="alert">⚠️ Something went wrong!</div>
-</template>
-```
-
-```typescript
-const box = document.querySelector('#alert-box') as SwcIf;
-box.value = true;   // content appears in DOM
-box.value = false;  // content is physically removed
-```
-
-### Switch/Case — `<template is="swc-choose">`
-
-```html
-<template is="swc-choose" id="status-panel">
-  <template is="swc-when" test="loading">
-    <div class="spinner">⏳ Loading...</div>
-  </template>
-  <template is="swc-when" test="error">
-    <div class="error">❌ Something went wrong</div>
-  </template>
-  <template is="swc-when" test="success">
-    <div class="success">✅ Done!</div>
-  </template>
-  <template is="swc-other">
-    <div class="idle">⚪ Waiting...</div>
-  </template>
-</template>
-```
-
-```typescript
-const panel = document.querySelector('#status-panel') as SwcChoose;
-panel.value = 'loading';  // shows spinner
-panel.value = 'success';  // shows ✅
-panel.value = 'unknown';  // shows ⚪ (swc-other)
-```
-
-### Object Binding — `<template is="swc-object">`
-
-```html
-<template is="swc-object" id="user-card" as="u">
-  <div class="card">
-    <h2>{{u.name}}</h2>
-    <p>Age: {{u.age}}</p>
-    <p>Role: {{u.role.toUpperCase()}}</p>
-  </div>
-</template>
-```
-
-```typescript
-const card = document.querySelector('#user-card') as SwcObject;
-card.value = { name: 'Alice', age: 28, role: 'admin' };
-
-// Proxy-based — nested changes are reactive
-card.value.name = 'Bob';  // DOM updates instantly
-```
-
----
-
-## Decorator API
-
-### `@elementDefine(config)`
-
-```typescript
-@elementDefine('my-button')                          // simple
-@elementDefine({ name: 'my-button', window: w })     // with options
-@elementDefine({ name: 'my-button', extends: 'button', autoRemoveEventListeners: true })
-```
-
-| Option | Default | Description |
+| Option | Type | Description |
 |---|---|---|
-| `name` | required | Custom element tag name |
-| `extends` | auto-detected | Extend a built-in HTML element |
-| `autoRemoveEventListeners` | `true` | Clean up listeners on disconnect |
-| `window` | global `window` | Inject a custom window (SSR, multi-window) |
+| `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). |
 
----
-
-### `@innerHtml(options?)`
-
-Defines the component's template. Supports async, Shadow DOM, and multiple render methods.
+### 2. `@innerHtml(options?)`
+Defines the template for the component.
 
 ```typescript
-// Light DOM (default)
-@innerHtml
-render() { return `<p>Hello {{name}}</p>`; }
-
-// Shadow DOM with encapsulated styles
-@innerHtml({ useShadow: true })
-render() {
-  return `
-    <style>p { color: blue; }</style>
-    <p>Hello {{name}}</p>
-  `;
-}
-
-// Async — fetch data before rendering
-@innerHtml
-async render() {
-  const { title } = await fetch('/api/config').then(r => r.json());
-  return `<h1>${title}</h1>`;
-}
-
-// Both Shadow and Light DOM simultaneously
-@innerHtml({ useShadow: true })
-shadow() { return `<style>:host{display:block}</style><slot></slot>`; }
-
-@innerHtml
-light() { return `<p>{{description}}</p>`; }
-```
-
----
-
-### `@state(alias?)`
-
-Reactive property. Changes trigger surgical DOM updates — only the bound nodes are touched.
-
-```typescript
-@state name = 'Alice';
-@state count = 0;
-@state('userName') displayName = 'Alice';  // template uses {{userName}}
-
-// Objects and arrays — nested changes are reactive via Proxy
-@state user = { name: 'Alice', scores: [10, 20, 30] };
-@state items: string[] = [];
-
-// These all trigger DOM updates:
-this.name = 'Bob';
-this.user.name = 'Bob';
-this.items.push('new item');
-this.user.scores[0] = 99;
-```
-
-Template expressions — full JS expressions work:
-
-```html
-<p>{{count + 1}} of {{total}}</p>
-<p class="{{score > 90 ? 'gold' : 'silver'}}">{{score}}</p>
-<p>{{items.length === 0 ? 'Empty' : items.join(', ')}}</p>
-```
-
----
-
-### `@attribute(options?)`
-
-Syncs an HTML attribute ↔ JS property. Supports type coercion.
-
-```typescript
-@attribute() label = '';                          // attr: label
-@attribute('data-id') itemId = '';                // attr: data-id
-@attribute({ type: Number }) count = 0;           // auto-converts "5" → 5
-@attribute({ type: Boolean }) disabled = false;   // presence → true
-@attribute({ type: Object }) config = {};         // JSON.parse/stringify
-@attribute({ disableReflect: true }) secret = ''; // JS-only, not reflected to HTML
-
-// Combine with @state for reactive attributes
-@state @attribute({ type: Number }) count = 0;
-```
-
-```html
-<!-- Set initial values from HTML -->
-<my-input label="Email" data-id="42" disabled></my-input>
-```
-
----
-
-### `@query(selector?)` / `@queryAll(selector?)`
-
-```typescript
-// Property getter — lazy, always fresh
-@query('input[name="email"]') emailInput!: HTMLInputElement;
-@queryAll('li.item') items!: NodeListOf<HTMLLIElement>;
-
-// No selector = the host element itself
-@query hostEl!: HTMLElement;
-
-// Scoped search
-@query({ selector: 'button', root: 'shadow' }) shadowBtn!: HTMLButtonElement;
-@query({ selector: 'slot',   root: 'light'  }) slot!: HTMLSlotElement;
-
-// Method form — called once after connectedCallback
-@query('canvas')
-onCanvasReady(canvas: HTMLCanvasElement) {
-  const ctx = canvas.getContext('2d');
-  // initialize...
-}
-```
-
----
-
-### `@addEventListener(options)`
-
-Declarative event binding. Auto-removed on disconnect.
-
-```typescript
-// Basic
-@addEventListener({ type: 'click', query: '#save-btn' })
-onSave() { this.save(); }
-
-// With modifiers
-@addEventListener({ type: 'submit', query: 'form', preventDefault: true, stopPropagation: true })
-onSubmit(event: SubmitEvent) { /* ... */ }
-
-// Host element (no query)
-@addEventListener({ type: 'keydown' })
-onKeyDown(event: KeyboardEvent) {
-  if (event.key === 'Escape') this.close();
-}
-
-// Shadow DOM scope
-@addEventListener({ type: 'click', query: '.tab', root: 'shadow' })
-onTabClick(event: MouseEvent, target: Element) {
-  this.activeTab = target.dataset.tab!;
+@elementDefine('my-el')
+class MyEl extends HTMLElement {
+  @innerHtml({ useShadow: true })
+  render() {
+    return `<style>:host { color: blue; }</style><div>Hello World</div>`;
+  }
 }
 ```
 
----
-
-### `@emitCustomEvent(options)`
+### 3. Modern Attribute Management
+SWC uses a **Method-Based Reflection** approach. You control exactly how data flows.
 
-Wraps a method to automatically dispatch a `CustomEvent` with the return value as `detail`.
+- **`@setAttribute(name?)`**: Reflects the method's **return value** to the DOM attribute.
+- **`@changedAttribute(name?)`**: A handler triggered when the attribute changes.
 
 ```typescript
-@emitCustomEvent('user-saved')
-save() {
-  return { id: this.userId, name: this.name };
-  // → dispatches CustomEvent('user-saved', { detail: { id, name }, bubbles: true })
-}
-
-@emitCustomEvent({ type: 'item-select', bubbles: true, composed: true })
-selectItem(id: string) {
-  return { id, timestamp: Date.now() };
-}
-```
-
-```typescript
-// Listen from anywhere in the tree
-document.addEventListener('user-saved', (e: CustomEvent) => {
-  console.log('Saved:', e.detail); // { id: '...', name: '...' }
-});
-```
-
----
+@elementDefine('my-counter')
+class MyCounter extends HTMLElement {
+  private count = 0;
+  @query('#display') displayEl?: HTMLElement;
 
-## Lifecycle Hooks
+  @setAttribute('count')
+  updateCount(val: number) { return val; } // Sets 'count' attribute in DOM
 
-```typescript
-@elementDefine('my-element')
-class MyElement extends HTMLElement {
-  @onBeforeConnected  beforeConnect()  { /* before template injection */ }
-  @onAfterConnected   afterConnect()   { /* after template + binding ready */ }
-  @onBeforeDisconnected beforeDisconnect() { /* cleanup prep */ }
-  @onAfterDisconnected  afterDisconnect()  { /* fully removed */ }
-
-  // Single attribute
-  @onAttributeChanged('name')
-  onNameChange(newVal: string, oldVal: string) { }
-
-  // Multiple attributes
-  @onAttributeChanged(['name', 'age'])
-  onNameOrAge(newVal: string, oldVal: string, attr: string) { }
-
-  // Wildcard — any attribute
-  @onAttributeChanged
-  onAnyAttr(newVal: string, oldVal: string, attr: string) { }
-
-  // MutationObserver lifecycle
-  @onMutationSubscribe({ root: 'all' })
-  onDomChanged(mutations: MutationRecord[], observer: MutationObserver) {
-    console.log('DOM changed:', mutations.length, 'mutations');
+  @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;
   }
-
-  @onMutationSubscribe({ root: 'shadow' })
-  onShadowChanged(mutations: MutationRecord[]) { }
-
-  @onMutationSubscribe({ root: 'light' })
-  onLightChanged(mutations: MutationRecord[]) { }
 }
 ```
 
-### HTML Attribute Hooks (Zero-JS)
+### 4. Powerful Queries (`@query`, `@queryAll`)
+Inject internal elements directly into properties. Supports the **`:host`** selector.
 
-```html
-<my-element
-  swc-on-constructor="console.log('created', this)"
-  swc-on-connected="console.log('connected', $host)"
-  swc-on-disconnected="console.log('removed')"
-  swc-on-attribute-changed="console.log($name, ':', $old, '→', $new)"
-></my-element>
-```
-
----
-
-## Inline Event Scripts & Built-in Variables
-
-Every `swc-on-*` attribute has access to these variables at runtime:
-
-| Variable | Value |
+| Root Option | Description |
 |---|---|
-| `this` | The element the attribute is on |
-| `event` | The native Event object |
-| `$data` | `event.detail` (CustomEvent) |
-| `$host` | Nearest SWC parent component |
-| `$firstHost` | Top-most SWC ancestor |
-| `$lastHost` | Same as `$host` |
-| `$hosts` | All SWC ancestors `[root, ..., parent]` |
-| `$q(sel, root?)` | `querySelector` shorthand |
-| `$qa(sel, root?)` | `querySelectorAll` → Array |
-| `$qi(id, root?)` | `getElementById` shorthand |
-| `$d` | `document` |
-| `$w` | `window` |
-
-```html
-<!-- Call host method directly -->
-<button swc-on-click="$host.save();">Save</button>
-
-<!-- Access top-most ancestor (useful inside swc-for-of) -->
-<button swc-on-click="$firstHost.deleteItem({{i}});">Delete</button>
+| `auto` (default) | Search in `shadowRoot` if exists, otherwise `this` (Light DOM). |
+| `shadow` | **Strictly** search in `shadowRoot`. Returns `null/[]` if no shadow. |
+| `light` | **Strictly** search in Light DOM (`this`). |
+| `all` | Search in **both** Shadow and Light DOM. |
 
-<!-- DOM shortcuts -->
-<button swc-on-click="$qi('modal')?.show();">Open Modal</button>
-<button swc-on-click="$q('.panel', $host.shadowRoot)?.classList.toggle('open');">Toggle</button>
-
-<!-- Two-way binding via inline event -->
-<input swc-on-input="$host.name = event.target.value" value="{{name}}" />
-
-<!-- Run once on connect -->
-<canvas swc-on-connected="$qi('{{id}}')?.getContext('2d')"></canvas>
-```
-
----
-
-## Nested Components & Hierarchical Context
-
-SWC tracks the component tree automatically. From any nested element, you can reach up to any ancestor.
+Inject elements directly into properties. Supports `:host` and scoped root control.
 
 ```typescript
-@elementDefine('user-list')
-class UserList extends HTMLElement {
-  @state users = [
-    { id: 1, name: 'Alice', active: true },
-    { id: 2, name: 'Bob',   active: false },
-  ];
-  @state currentUser = { name: 'Admin', role: 'admin' };
-
-  removeUser(index: number) {
-    this.users.splice(index, 1);
-  }
-
-  @innerHtml({ useShadow: true })
-  render() {
-    return `
-      <p>Logged in as: <strong>{{currentUser.name}}</strong></p>
-
-      <ul is="swc-for-of-ul" value="{{users}}" as="u" as-index="i">
-        <li class="{{u.active ? 'active' : 'inactive'}}">
-          #{{i + 1}} — {{u.name}}
-
-          <!--
-            $host     = swc-for-of-ul (nearest SWC parent)
-            $firstHost = user-list    (top-most SWC ancestor)
-
-            Access parent @state directly in child template:
-            {{currentUser.name}} resolves from user-list's @state
-          -->
-          <small>by {{currentUser.name}}</small>
-          <button swc-on-click="$firstHost.removeUser({{i}});">✕</button>
-        </li>
-      </ul>
-    `;
-  }
+@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;
 }
 ```
 
-### Alias System (`as` / `as-index`)
-
-Give components and loop items readable names for cross-scope access:
-
-```html
-<!-- as="t1" makes this component accessible as {{t1.count}} from children -->
-<t-test id="parent" as="t1">
-  <t-test2 as="t2" slot="content">
-    <div>
-      <p>T1 count: <strong>{{t1.count}}</strong></p>
-      <p>T2 count: <strong>{{t2.count}}</strong></p>
-    </div>
-  </t-test2>
-</t-test>
-```
-
----
-
-## Shadow DOM + Slots
+### 5. Smart Event Binding (`@addEventListener`)
+Bind events declaratively with support for **Event Delegation**.
 
 ```typescript
-@elementDefine('card-layout')
-class CardLayout extends HTMLElement {
-  @state title = '';
-
-  @innerHtml({ useShadow: true })
-  render() {
-    return `
-      <style>
-        :host { display: block; border: 1px solid #ddd; border-radius: 8px; overflow: hidden; }
-        .header { background: #f5f5f5; padding: 12px 16px; font-weight: 600; }
-        .body   { padding: 16px; }
-        .footer { padding: 12px 16px; border-top: 1px solid #eee; }
-      </style>
-      <div class="header">{{title}}</div>
-      <div class="body"><slot></slot></div>
-      <div class="footer"><slot name="footer"></slot></div>
-    `;
+@elementDefine('event-demo')
+class EventDemo extends HTMLElement {
+  // 1. Direct binding (Pure Mode)
+  @addEventListener('.static-btn', 'click')
+  onStaticClick(event: MouseEvent) { ... }
+
+  // 2. Event Delegation (Works for dynamic nodes added LATER)
+  @addEventListener('.item', 'click', { delegate: true })
+  onItemClick(event: MouseEvent, { $host }: HostSet, target: HTMLElement) {
+    console.log('Clicked dynamic item:', target.textContent);
   }
 }
 ```
 
-```html
-<card-layout title="User Profile">
-  <p>Name: Alice</p>
-  <p>Email: alice@example.com</p>
-  <div slot="footer">
-    <button>Edit</button>
-    <button>Delete</button>
-  </div>
-</card-layout>
-```
-
 ---
 
-## File Separation Pattern
+## 🌐 Powerful SPA & Routing
 
-When splitting components into separate files, use `export default (w: Window) => {...}` to inject `window`:
-
-```typescript
-// UserCard.ts
-import { elementDefine, innerHtml, state, attribute, addEventListener } from '@dooboostore/simple-web-component';
-import { Sim } from '@dooboostore/simple-boot/decorators/SimDecorator';
+SWC provides a revolutionary way to build SPAs where **each component scope is an independent application**.
 
-export default (w: Window) => {
-  @Sim
-  @elementDefine({ name: 'user-card', window: w })
-  class UserCard extends HTMLElement {
-    @state @attribute name = 'Guest';
-    @state @attribute({ type: Number }) age = 0;
-
-    @innerHtml({ useShadow: true })
-    render() {
-      return `
-        <div class="card">
-          <h2>{{name}}</h2>
-          <p>Age: {{age}}</p>
-          <button id="edit-btn">Edit</button>
-        </div>
-      `;
-    }
-
-    @addEventListener({ type: 'click', query: '#edit-btn' })
-    onEdit() { console.log('editing', this.name); }
-  }
+### 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.
 
-  return UserCard;
-};
-```
+```html
+<!-- index.html -->
+<swc-app swc-get-application-config="myAppConfig(this)"></swc-app>
 
-```typescript
-// index.ts — inject window at the entry point
-import createUserCard from './UserCard';
+<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)
+      routeType: 'element',   // 'element' (in-memory history), 'hash', or 'path'
+      path: '/users/list',    // Initial route path
+      window: window          // Optional: custom window object
+    };
+  };
+
+  // 4. External Control (Anywhere in your JS)
+  function navigateFromOutside() {
+      const app = document.querySelector('swc-app');
+      // Programmatically trigger routing from outside the component
+      app.routing('/users/detail/2'); 
+  }
+</script>
 
-const UserCard = createUserCard(window);
+<button onclick="navigateFromOutside()">External Link to User 2</button>
 ```
 
-> For browser-only apps, `window` injection is optional.  
-> `@elementDefine('user-card')` works fine — SWC falls back to the global `window` automatically.
-
----
-
-## SPA Routing
-
-SWC integrates with `@dooboostore/simple-boot` for DI-powered routing.
-
-### Option A — `<swc-app>` (HTML-first, zero JS bootstrap)
-
-Drop a single tag in your HTML. No `DOMContentLoaded` wiring needed.
-
-```html
-<!-- index.html -->
-<swc-app swc-get-application-config="applicationConfig(this)"></swc-app>
-```
+### 2. DI-Powered Routing
+Define routes using decorators. Components are automatically instantiated and managed by the DI container.
 
 ```typescript
-// index.ts
-import 'reflect-metadata';
-import {
-  elementDefine, innerHtml, state, query, addEventListener,
-  onMutationSubscribe, SwcApp, SwcAppInterface, SwcAttributeConfigType
-} from '@dooboostore/simple-web-component';
-import { SimpleApplication } from '@dooboostore/simple-boot/SimpleApplication';
-import { Sim } from '@dooboostore/simple-boot/decorators/SimDecorator';
-import { Router as WebRouter } from '@dooboostore/core-web/routers/Router';
 import { Router } from '@dooboostore/simple-boot/decorators/route/Router';
-import { RouterAction } from '@dooboostore/simple-boot/route/RouterAction';
-import { RoutingDataSet } from '@dooboostore/simple-boot/route/RouterManager';
-import createMyComponent from './MyComponent';
-
-const w = window;
-const MyComponent = createMyComponent(w);
-
-// ─── Pages ───────────────────────────────────────────────────────────────────
-
-@Sim
-@elementDefine({ name: 'my-component2', window: w })
-class MyComponent2 extends HTMLElement {
-  say() { console.log('hello from MyComponent2'); }
-
-  @innerHtml
-  render() {
-    return `<div style="padding: 10px; border: 1px solid #ccc;"><h3>Component 2</h3></div>`;
-  }
-}
-
-// ─── Sub Router ──────────────────────────────────────────────────────────────
+import { Sim } from '@dooboostore/simple-boot/decorators/SimDecorator';
 
 @Sim
 @Router({
-  path: '/hello',
+  path: '/users',
   route: {
-    '/good':  MyComponent,
-    '/good2': MyComponent2,
+    '/list': UserList,
+    '/detail/:id': UserDetail
   }
 })
-@elementDefine('my-router')
-class MyRouter extends HTMLElement implements RouterAction.CanActivate {
-  @query('#my-route') myRoute!: HTMLElement;
-
-  @innerHtml
-  render() {
-    return `
-      <div style="padding: 10px; border: 1px solid #ccc;">
-        <h3>My Router</h3>
-        <div id="my-route"></div>
-      </div>
-    `;
+@elementDefine('user-router')
+class UserRouter extends HTMLElement implements RouterAction.CanActivate {
+  @innerHtml({ useShadow: true })
+  render() { 
+    return `<header>User System</header><main><slot></slot></main>`; 
   }
 
-  async canActivate(url: RoutingDataSet, data?: any): Promise<void> {
-    if (data instanceof Node && !this.myRoute.contains(data)) {
-      this.myRoute.replaceChildren(data);  // atomic, flicker-free swap
-    }
+  async canActivate(url: RoutingDataSet, data?: any) {
+    if (data instanceof Node) this.replaceChildren(data);
   }
 }
 
-// ─── Root Router ─────────────────────────────────────────────────────────────
-
+// Pure Service (Business Logic)
 @Sim
-@Router({ routers: [MyRouter] })
-@elementDefine({ name: 'root-router', window: w })
-class RootRouter extends HTMLDivElement implements RouterAction.CanActivate {
-  @state route = '';
-  @state name = 'Root';
-
-  constructor(
-    private router: WebRouter,
-    private sim: SimpleApplication
-  ) { super(); }
-
-  async canActivate(url: RoutingDataSet, data?: any): Promise<void> {
-    this.route = url.intent.pathname;
-    if (data instanceof Node && !this.contains(data)) {
-      this.replaceChildren(data);
-    }
-  }
-
-  @addEventListener({ type: 'click', query: '#route-btn' })
-  onRoute() {
-    this.name = 'Changed ' + new Date().getSeconds();
-    this.router.go('/hello/good');
+class UserService {
+  async getProfile(id: string) {
+    return { id, name: 'Standard User' };
   }
+}
 
-  // React to DOM mutations (Shadow + Light)
-  @onMutationSubscribe({ root: 'all' })
-  onDomChanged(mutations: MutationRecord[]) {
-    console.log('DOM changed:', mutations.length, 'mutations');
-  }
+// Example Page Components
+@Sim
+@elementDefine('user-list')
+class UserList extends HTMLElement {
+  constructor(private router: Router, private userService: UserService) { super(); }
 
-  @innerHtml({ useShadow: true })
-  render() {
+  @innerHtml
+  render() { 
     return `
-      <style>.container { padding: 10px; border: 1px solid #ccc; }</style>
-      <div class="container">
-        <h3>Root Router</h3>
-        <p>Route: <strong>{{route}}</strong></p>
-        <p>Name: <strong>{{name}}</strong></p>
-        <button id="route-btn">Go to /hello/good</button>
-        <slot></slot>
-      </div>
-    `;
+      <ul><li>User A</li><li>User B</li></ul>
+      <button swc-on-click="$host.router.go('/users/detail/1')">Go to Detail</button>
+    `; 
   }
 }
 
-// ─── Bootstrap ───────────────────────────────────────────────────────────────
-
-// Expose config factory on window — <swc-app> calls this via new Function()
-export const applicationConfig = (app: SwcAppInterface): SwcAttributeConfigType => ({
-  rootRouter: RootRouter,
-  path: '/hello/good',
-  window: w,
-});
-(w as any).applicationConfig = applicationConfig;
-```
-
-```typescript
-// MyComponent.ts — decoupled from global window
-import { elementDefine, innerHtml, state, attribute, onAfterConnected, addEventListener } from '@dooboostore/simple-web-component';
-import { Sim } from '@dooboostore/simple-boot/decorators/SimDecorator';
-import { Router as WebRouter } from '@dooboostore/core-web/routers/Router';
-
-export default (w: Window) => {
-  @Sim
-  @elementDefine({ name: 'my-component', window: w })
-  class MyComponent extends HTMLElement {
-    @state route = '';
-    @state @attribute name?: string | null;
-    @state showExtra = false;
-    @state showRealIf = true;
-
-    constructor(private router: WebRouter) { super(); }
-
-    @innerHtml({ useShadow: true })
-    render() {
-      return `
-        <div style="padding: 10px; border: 1px solid #ccc;">
-          <h3>My Component</h3>
-          <p>Name: <strong>{{name}}</strong></p>
-          <button id="change-btn">Change Name</button>
-          <button id="toggle-extra-btn">Toggle IfChildren</button>
-          <button id="toggle-if-btn">Toggle Real If</button>
-
-          <!-- Inline event: $host = my-component -->
-          <input swc-on-input="$host.name = event.target.value" value="{{name}}" />
-
-          <div is="swc-if-children-div" value="{{showExtra}}">
-            <p style="color: blue;">Extra content (wrapper stays in DOM)</p>
-          </div>
-
-          <div is="swc-if-div" value="{{showRealIf}}" style="background: yellow; padding: 5px;"
-            swc-on-click="console.log('clicked', $host, $firstHost)"
-            swc-on-connected="console.log('connected', $host)">
-            <b>Toggle me to disappear from DOM entirely.</b>
-          </div>
-        </div>
-      `;
-    }
-
-    @onAfterConnected
-    init() { console.log('MyComponent ready', this.name); }
-
-    @addEventListener({ type: 'click', query: '#change-btn' })
-    onChangeName() { this.name = 'Changed ' + new Date().getSeconds(); }
-
-    @addEventListener({ type: 'click', query: '#toggle-extra-btn' })
-    onToggleExtra() { this.showExtra = !this.showExtra; }
-
-    @addEventListener({ type: 'click', query: '#toggle-if-btn' })
-    onToggleIf() { this.showRealIf = !this.showRealIf; }
+@Sim
+@elementDefine('user-detail')
+class UserDetail extends HTMLElement {
+  constructor(private router: Router, private userService: UserService) { super(); }
+
+  @onConnected
+  async init() {
+     const id = this.router.getIntent()?.params?.id;
+     const profile = await this.userService.getProfile(id);
+     console.log('Viewing User:', profile.name);
   }
 
-  return MyComponent;
-};
-```
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>swc</title>
-  <script src="..."></script>
-</head>
-<body is="swc-app-body" swc-get-application-config="applicationConfig(this)">
-</body>
-</html>
-```
-
-### Routing Architecture
-
-```
-<swc-app>  or  swc.run()
-  └── RootRouter (extends HTMLDivElement)
-        └── canActivate → replaceChildren(data)   ← Light DOM slot
-              │
-              └── MyRouter  (@Router path: '/hello')
-                    └── canActivate → #my-route.replaceChildren(data)
-                          ├── /good  → MyComponent
-                          └── /good2 → MyComponent2
+  @innerHtml
+  render() { return `<div>User Detail View <button swc-on-click="$host.router.back()">Back</button></div>`; }
+}
 ```
 
-- `canActivate(url, data)` — `data` is the instantiated component node
-- `replaceChildren(data)` — atomic DOM swap, zero flicker
-- `RootRouter` can extend any HTML element (`HTMLDivElement`, `HTMLElement`, etc.)
-- Shadow DOM `<slot>` + Light DOM `replaceChildren` = instant page transitions
-
----
-
-## Complete Component Example
+### 3. Lifecycle @Inject
+Inject services or component context directly into lifecycle methods. This is the ultimate way to handle side effects cleanly.
 
 ```typescript
-import 'reflect-metadata';
-import {
-  elementDefine, innerHtml, state, attribute,
-  query, addEventListener, onAfterConnected,
-  emitCustomEvent, onAttributeChanged, onMutationSubscribe
-} from '@dooboostore/simple-web-component';
-
-@elementDefine({ name: 'user-profile', autoRemoveEventListeners: true })
-class UserProfile extends HTMLElement {
-  @state @attribute name = 'Guest';
-  @state @attribute({ type: Number }) age = 0;
-  @state isEditing = false;
-  @state history: string[] = [];
-
-  @query('input[name="name"]') nameInput!: HTMLInputElement;
-  @query('input[name="age"]')  ageInput!: HTMLInputElement;
-
-  @emitCustomEvent({ type: 'profile-save', bubbles: true })
-  save() {
-    return { name: this.name, age: this.age };
-    // → CustomEvent('profile-save', { detail: { name, age } })
-  }
-
-  @innerHtml({ useShadow: true })
-  render() {
-    return `
-      <style>
-        :host { display: block; font-family: sans-serif; max-width: 400px; }
-        .card { padding: 16px; border: 1px solid #ddd; border-radius: 8px; }
-        .edit { padding: 16px; background: #f9f9f9; border-radius: 8px; margin-top: 8px; }
-        input { padding: 6px 10px; margin: 4px 0; width: 100%; box-sizing: border-box; }
-        button { cursor: pointer; padding: 6px 14px; margin: 4px 2px; }
-        .history { font-size: 0.85rem; color: #666; }
-      </style>
-
-      <div class="card">
-        <h2>{{name}} <small style="color:#999">(age {{age}})</small></h2>
-        <button id="edit-btn">✏️ Edit</button>
-      </div>
-
-      <div is="swc-if-children-div" value="{{isEditing}}">
-        <div class="edit">
-          <input name="name" type="text"   value="{{name}}" placeholder="Name" />
-          <input name="age"  type="number" value="{{age}}"  placeholder="Age"  />
-          <button id="save-btn">💾 Save</button>
-          <button id="cancel-btn">✕ Cancel</button>
-        </div>
-      </div>
-
-      <div is="swc-if-div" value="{{history.length > 0}}">
-        <h4>Change History</h4>
-        <ul is="swc-for-of-ul" value="{{history}}" as-item="log" as-index="i">
-          <li class="history">#{{i + 1}}: {{log}}</li>
-        </ul>
-      </div>
-    `;
+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,
+    @Inject({ type: Router }) router: Router,
+    @Inject({ type: UserService }) api: UserService
+  ) {
+    console.log('App scope:', hostSet.$appHost);
+    const user = await api.getProfile();
+    // Navigate programmatically using injected router
+    if (!user) router.go('/login');
   }
+}
+```
 
-  @addEventListener({ type: 'click', query: '#edit-btn' })
-  onEdit() { this.isEditing = true; }
-
-  @addEventListener({ type: 'click', query: '#cancel-btn' })
-  onCancel() { this.isEditing = false; }
+---
 
-  @addEventListener({ type: 'click', query: '#save-btn' })
-  onSave() {
-    this.name = this.nameInput?.value ?? this.name;
-    this.age  = Number(this.ageInput?.value) || this.age;
-    this.isEditing = false;
-    this.save();
-  }
+## 🏰 Host Hierarchy & Context
+SWC automatically traverses the DOM to provide meaningful context to your scripts and listeners:
 
-  @onAttributeChanged('name')
-  onNameChange(newVal: string, oldVal: string) {
-    if (oldVal && newVal !== oldVal) {
-      this.history = [...this.history, `${oldVal} → ${newVal}`];
-    }
-  }
+- **`$host`**: The current component Handling the event (**Self**).
+- **`$parentHost`**: The direct parent SWC component.
+- **`$appHost`**: The nearest parent `<swc-app>` (the SPA boundary).
+- **`$hosts`**: Array of all SWC ancestors `[Root, ..., Parent, Self]`.
 
-  @onMutationSubscribe({ root: 'shadow' })
-  onShadowChanged(mutations: MutationRecord[]) {
-    console.log('Shadow DOM updated:', mutations.length, 'changes');
-  }
+---
 
-  @onAfterConnected
-  init() { console.log('UserProfile ready'); }
-}
-```
+## 🛠 Lifecycle Hooks
+Executed in **Parent -> Child** order.
+- `@onBeforeConnected` / `@onAfterConnected` (alias: `@onConnected`)
+- `@onBeforeDisconnected` / `@onAfterDisconnected` (alias: `@onDisconnected`)
+- `@onBeforeAdopted` / `@onAfterAdopted` (alias: `@onAdopted`)
+- `@onAddEventListener`
 
-```html
-<user-profile name="Alice" age="28"></user-profile>
+---
 
-<script>
-  document.querySelector('user-profile').addEventListener('profile-save', (e) => {
-    console.log('Saved:', e.detail); // { name: '...', age: ... }
-  });
-</script>
-```
+## ⚡ 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.
 
 ---
 
-## License
-
+## 📜 License
 MIT