@dooboostore/simple-web-component 1.0.42 → 1.0.43

package/README.md

@@ -70,18 +70,14 @@ replaceChildren(node: Node) {
 ```
 ### 3.5 **Slot Management with @applySlot**
 
-Manage dynamic content insertion into named slots using the `@applySlot` decorator. Slots are placeholders in templates that can be updated dynamically.
+Manage dynamic content insertion into named slots using slot decorators. Slots are placeholders in templates that can be updated dynamically.
 
 ```typescript
-import {clearSlot} from "./applySlot";
-
 @elementDefine('content-manager')
 class ContentManager extends HTMLElement {
-
-
   // Method: Replace children in slot with HTML
   @addEventListener('.update-btn', 'click')
-  @replaceChildrenSlot('main-content')
+  @replaceChildrenHtmlSlot('main-content')
   updateContent() {
     return '<div>Updated content here</div>';
   }
@@ -105,7 +101,6 @@ class ContentManager extends HTMLElement {
     return true;
   }
 
-
   @onConnectedLight
   render() {
     return `
@@ -130,17 +125,13 @@ class ContentManager extends HTMLElement {
 - `<!--[[ slot-id ]]-->` - Named slot placeholder (HTML comment syntax)
 
 **@applySlot Decorator Variants:**
-- clearSlot
-- prependHtmlSlot
-- prependSlot
-- prependTextSlot
-- appendHtmlSlot
-- appendTextSlot
-- appendSlot
-- replaceChildrenHtmlSlot
-- replaceChildrenSlot
-- replaceChildrenTextSlot
-
+- `clearSlot(slotId)` - Clear all content
+- `prependHtmlSlot(slotId)` - Add HTML at beginning
+- `prependTextSlot(slotId)` - Add text at beginning
+- `appendHtmlSlot(slotId)` - Add HTML at end
+- `appendTextSlot(slotId)` - Add text at end
+- `replaceChildrenHtmlSlot(slotId)` - Replace all with HTML
+- `replaceChildrenTextSlot(slotId)` - Replace all with text
 
 **Position Options:**
 ```typescript
@@ -207,7 +198,7 @@ class CounterApp extends HTMLElement {
 
 **State Syntax in Templates:**
 
-**Reading State Values:**
+**Reading State Values(read only):**
 - `@stateName@` - Read state value as text/attribute
 - `@stateName@()` - Call state property as function (if it's a function)
 - `@expression@` - Evaluate expressions with state variables
@@ -231,6 +222,23 @@ class CounterApp extends HTMLElement {
 - `@expression@` - Evaluate JavaScript expressions
 - All state variables available in template expressions
 
+**Important: State Properties are Read-Only in Templates**
+State values accessed in templates via `@stateName@` syntax are read-only. You cannot assign values to state properties from within template expressions. State must be updated from component methods:
+
+```typescript
+// ✅ CORRECT - Update state from method
+@addEventListener('button', 'click')
+increment() {
+  this.count++;  // Direct property assignment in code
+}
+
+// ❌ WRONG - Cannot assign in template
+<!--[text @count = 5@ ]-->  // This won't work - read-only in templates
+
+// ✅ CORRECT - Call method from template
+<button e:click="@increment@()">Increment</button>
+```
+
 **Advanced Example:**
 ```typescript
 @elementDefine('user-profile')
@@ -288,16 +296,21 @@ onCriticalClick(event: Event) {
 }
 ```
 
-**other Event decorators**
-- addEventListenerDelegateLightDom
-- addEventListenerDelegateShadowDom
-- addEventListenerDelegateAllDom
-- addEventListenerDelegate
-- addEventListenerThis
-- addEventListenerAppHost
-- addEventListenerWindow
-- addEventListenerDocument
-
+**@addEventListener Decorator Variants:**
+- `addEventListener(selector, type, options)` - Full form
+- `event(selector, type, options)` - Short alias
+- `addEventListenerThis(type, options)` - Listen on $this element
+- `addEventListenerAppHost(type, options)` - Listen on $appHost
+- `addEventListenerWindow(type, options)` - Listen on window
+- `addEventListenerDocument(type, options)` - Listen on document
+- `addEventListenerDelegate(selector, type, options)` - Event delegation
+- `eventDelegate(selector, type, options)` - Short alias
+- `addEventListenerDelegateLightDom(selector, type, options)` - Delegate in light DOM
+- `eventDelegateLightDom(selector, type, options)` - Short alias
+- `addEventListenerDelegateShadowDom(selector, type, options)` - Delegate in shadow DOM
+- `eventDelegateShadowDom(selector, type, options)` - Short alias
+- `addEventListenerDelegateAllDom(selector, type, options)` - Delegate in all DOM
+- `eventDelegateAllDom(selector, type, options)` - Short alias
 
 #### @emitCustomEvent
 Emit custom events with data.
@@ -310,6 +323,50 @@ async onLogin() {
 }
 ```
 
+**@emitCustomEvent Decorator Variants:**
+- `emitCustomEvent(target, type, options)` - Full form
+- `emit(target, type, options)` - Short alias
+- `emitCustomEventThis(type, options)` - Emit from $this element
+
+#### @publishSwcAppMessage
+Publish messages through the message bus when method completes.
+
+```typescript
+@publishSwcAppMessage()
+async onLogin() {
+  const user = await this.authService.login();
+  return user;  // Published as message with data: user
+}
+
+@publishSwcAppMessage('user-profile-updated')
+updateProfile() {
+  const profile = { name: this.name, email: this.email };
+  return profile;  // Published as message with type: 'user-profile-updated'
+}
+```
+
+**@publishSwcAppMessage Decorator Variants:**
+- `publishSwcAppMessage()` - Publish without message type
+- `publishSwcAppMessage(messageType)` - Publish with specific message type
+- `publishSwcAppMessage(messageType, { valueKey: 'customKey' })` - Publish with custom value extraction
+- `publishSwcAppMessage({ messageType: 'type', valueKey: 'customKey' })` - Publish with options object
+- `publish()` - Short alias
+- `publish(messageType)` - Short alias with message type
+- `publish(messageType, options)` - Short alias with options
+
+**Using valueKey for Multiple Decorators:**
+
+```typescript
+@publishSwcAppMessage('event1', { valueKey: 'detail1' })
+@publishSwcAppMessage('event2', { valueKey: 'detail2' })
+handleMultipleEvents() {
+  return {
+    detail1: { type: 'event1', data: 'value1' },
+    detail2: { type: 'event2', data: 'value2' }
+  };
+}
+```
+
 #### @emitCustomEventThis
 Emit events from a method with custom event name mapping.
 
@@ -321,7 +378,7 @@ onNavClick(e: any) {
 ```
 
 #### @addEventListenerThis
-Listen to events on the component element itself (`@host` selector).
+Listen to events on the component element itself (`$this` selector).
 
 ```typescript
 @addEventListenerThis('click')
@@ -421,28 +478,204 @@ onconstructor() {
 }
 ```
 
-### 7. **Lifecycle Hooks**
+### 7. **DOM Manipulation with @applyNode**
+
+Surgically add, replace, or remove nodes in the DOM with fine-grained control.
 
 ```typescript
-@onConnected
-onConnected() {
-  // Called when element enters DOM
+@elementDefine('content-updater')
+class ContentUpdater extends HTMLElement {
+  @addEventListener('button', 'click')
+  @replaceChildrenLightNodeThis
+  updateContent() {
+    return `<div>New content</div>`;
+  }
+
+  @addEventListener('.append-btn', 'click')
+  @beforeEndLightNodeThis
+  appendContent() {
+    return `<p>Appended content</p>`;
+  }
+
+  @addEventListener('.prepend-btn', 'click')
+  @afterBeginLightNodeThis
+  prependContent() {
+    return `<p>Prepended content</p>`;
+  }
+
+  @onConnectedLight
+  render() {
+    return `
+      <div>
+        <button class="append-btn">Append</button>
+        <button class="prepend-btn">Prepend</button>
+        <button>Replace</button>
+      </div>
+    `;
+  }
 }
+```
+
+**@applyNode Decorator Variants:**
+- `replaceChildrenNodeThis()` - Replace all children
+- `replaceChildrenLightNodeThis()` - Replace children in light DOM
+- `beforeEndNodeThis()` - Append to end
+- `beforeEndLightNodeThis()` - Append to light DOM end
+- `afterBeginNodeThis()` - Prepend to beginning
+- `afterBeginLightNodeThis()` - Prepend to light DOM beginning
+- `innerHtmlNodeThis()` - Set innerHTML
+- `innerHtmlLightNodeThis()` - Set innerHTML in light DOM
+- `innerTextNodeThis()` - Set innerText
+
+**Position Options:**
+```typescript
+export type ApplyNodePosition = 
+  | 'beforeBegin'      // Before element
+  | 'afterBegin'       // After element opens
+  | 'beforeEnd'        // Before element closes
+  | 'afterEnd'         // After element closes
+  | 'replace'          // Replace element
+  | 'replaceChildren'  // Replace children
+  | 'innerHtml'        // Set innerHTML
+  | 'innerText'        // Set innerText
+  | 'remove';          // Remove element
+```
+
+### 7.5 **Style & Class Management**
+
+Apply styles and classes dynamically with `@applyStyle` and `@applyClass`.
+
+```typescript
+@elementDefine('styled-component')
+class StyledComponent extends HTMLElement {
+  @state('isActive')
+  isActive = false;
+
+  @addEventListener('button', 'click')
+  @updateStyleThis
+  toggleStyle() {
+    return {
+      color: this.isActive ? 'green' : 'red',
+      fontSize: '16px'
+    };
+  }
 
-@onDisconnected
-onDisconnected() {
-  // Called when element leaves DOM
+  @addEventListener('.toggle-btn', 'click')
+  @updateClassThis
+  toggleClass() {
+    return {
+      'active': this.isActive,
+      'disabled': !this.isActive
+    };
+  }
+
+  @onConnectedLight
+  render() {
+    return `
+      <div>
+        <button class="toggle-btn">Toggle</button>
+        <button>Update Style</button>
+      </div>
+    `;
+  }
 }
+```
+
+**@applyStyle Variants:**
+- `setStyleThis()` - Clear and set styles
+- `updateStyleThis()` - Update/merge styles
+- `removeStyleThis()` - Remove specific styles
+
+**@applyClass Variants:**
+- `setClassThis()` - Replace all classes
+- `updateClassThis()` - Toggle classes
+- `addClassThis()` - Add classes
+- `removeClassThis()` - Remove classes
+- `toggleClassThis()` - Toggle classes
+
+### 7.6 **Lifecycle Hooks**
+
+Lifecycle hooks allow you to execute code at specific points in a component's lifecycle. All lifecycle decorators support optional `order` parameter for execution ordering.
+
+```typescript
+@elementDefine('my-component')
+class MyComponent extends HTMLElement {
+  @onInitialize({ order: 0 })
+  onInit() {
+    // Called during component construction
+    console.log('Component initialized');
+  }
 
+  @onConnectedBefore({ order: 0 })
+  beforeConnected() {
+    // Called before element connects to DOM
+  }
+
+  @onConnectedAfter({ order: 1 })
+  afterConnected() {
+    // Called after element connects to DOM
+  }
+
+  @onConnected
+  onConnected() {
+    // Called when element enters DOM
+  }
+
+  @onDisconnectedBefore
+  beforeDisconnected() {
+    // Called before element disconnects from DOM
+  }
+
+  @onDisconnected
+  onDisconnected() {
+    // Called when element leaves DOM
+  }
+
+  @onAdoptedBefore
+  beforeAdopted() {
+    // Called before element is adopted into new document
+  }
+
+  @onAdopted
+  onAdopted() {
+    // Called when element is adopted into new document
+  }
+
+  @onConnectedSwcApp({ order: 0 })
+  onSwcAppConnected() {
+    // Called after SwcApp.connect() completes
+    // Full DI support available through hostSet
+  }
 
-@onConnectedBefore
-onAppReady(router: Router) {
-  // Called after SwcApp.connect() completes on all already-connected components
-  // Full DI support available through hostSet
-  console.log('Application initialization complete!');
+  @onConnectedCompleted({ order: 0 })
+  onConnectedCompleted() {
+    // Called after all connected lifecycle hooks complete
+  }
 }
 ```
 
+**Lifecycle Execution Order:**
+- `@onInitialize` - Component construction
+- `@onConnectedBefore` - Before DOM connection
+- `@onConnectedAfter` - After DOM connection
+- `@onConnected` - DOM connection (with HTML rendering)
+- `@onConnectedSwcApp` - After SwcApp initialization
+- `@onConnectedCompleted` - All connected hooks done
+- `@onDisconnectedBefore` - Before DOM disconnection
+- `@onDisconnected` - DOM disconnection
+- `@onAdoptedBefore` - Before document adoption
+- `@onAdopted` - Document adoption
+
+**Order Parameter:**
+All lifecycle decorators support `order?: number` for controlling execution sequence:
+```typescript
+@onConnectedBefore({ order: 0 })  // Runs first
+onFirst() { }
+
+@onConnectedBefore({ order: 1 })  // Runs second
+onSecond() { }
+```
+
 ### 8. **Structural Directives**
 
 Structural Directives allow declarative conditional rendering, list iteration, async handling, and routing with automatic attribute substitution and dynamic expressions.
@@ -528,6 +761,28 @@ class LoginForm extends HTMLElement {
 }
 ```
 
+**@publishSwcAppMessage Decorator Variants:**
+- `publishSwcAppMessage()` - Publish without message type
+- `publishSwcAppMessage(messageType)` - Publish with specific message type
+- `publishSwcAppMessage(messageType, { valueKey: 'customKey' })` - Publish with custom value extraction
+- `publishSwcAppMessage({ messageType: 'type', valueKey: 'customKey' })` - Publish with options object
+- `publish()` - Short alias
+- `publish(messageType)` - Short alias with message type
+- `publish(messageType, options)` - Short alias with options
+
+**Using valueKey for Multiple Decorators:**
+
+```typescript
+@publishSwcAppMessage('event1', { valueKey: 'detail1' })
+@publishSwcAppMessage('event2', { valueKey: 'detail2' })
+handleMultipleEvents() {
+  return {
+    detail1: { type: 'event1', data: 'value1' },
+    detail2: { type: 'event2', data: 'value2' }
+  };
+}
+```
+
 **SwcAppMessage Structure:**
 ```typescript
 type SwcAppMessage<T = any> = {
@@ -647,17 +902,15 @@ w.document.addEventListener('DOMContentLoaded', async () => {
 
 ```typescript
 // Component factory
-import {defineSwcApp} from "./SwcApp";
-
 export default (w: Window) => {
   const tagName = 'my-component';
   const existing = w.customElements.get(tagName);
   if (existing) return tagName;
 
-  @elementDefine(tagName, {window: w})
+  @elementDefine(tagName, { window: w })
   class MyComponent extends w.HTMLElement {
     @onInitialize
-    onconstructor(service: MyService) {
+    onconstructor(@inject(MyService.SYMBOL) service: MyService) {
       this.service = service;
     }
   }
@@ -672,7 +925,7 @@ export default (w: Window, container: symbol) => {
 
 // Entry point
 const container = Symbol('app');
-await defineSwcAppBody(w)
+await defineSwcAppBody(w);
 const appElement = w.document.querySelector('#app') as SwcAppInterface;
 appElement.connect({
   container,
@@ -684,7 +937,7 @@ appElement.connect({
 });
 ```
 
-### 11. **Routing with @subscribeSwcAppRouteChangeWhileConnected**
+#### 11. **Routing with @subscribeSwcAppRouteChangeWhileConnected**
 
 SWC provides declarative routing with automatic path matching, order-based execution, and optional propagation control.
 
@@ -723,10 +976,11 @@ class RootRouter extends HTMLElement {
 #### Route Handler Features
 
 **1. Path Matching**
-- Exact match: `['', '/']` - matches home route
-- Prefix match: `['/products']` - matches `/products` and `/products/...`
-- Dynamic segments: `['/product/{id}']` - captures `id` parameter
-- Wildcard: `['/{tail:.*}']` - matches any remaining path (use for 404)
+- **No path pattern** (omit path): `@subscribeSwcAppRouteChangeWhileConnected({ order: -1 })` - matches all routes
+- **Exact match**: `['', '/']` - matches home route only
+- **Prefix match**: `['/products']` - matches `/products` and `/products/...`
+- **Dynamic segments**: `['/product/{id}']` - captures `id` parameter
+- **Wildcard**: `['/{tail:.*}']` - matches any remaining path (use for 404)
 
 **2. Order-Based Execution**
 Routes are executed in order of `order` value (lowest first). First matching route with a return value stops propagation:
@@ -750,7 +1004,7 @@ handleAdmin(routerPathSet: RouterEventType) {
 }
 
 // This handler continues propagation (no return value)
-@subscribeSwcAppRouteChangeWhileConnected(['{other:.*}'], { order: -1 })
+@subscribeSwcAppRouteChangeWhileConnected({ order: -1 })
 onRouteChange(routerPathSet: RouterEventType) {
   console.log('Route changed:', routerPathSet.path);
   // No return value → continues to next handler
@@ -762,8 +1016,8 @@ onRouteChange(routerPathSet: RouterEventType) {
 ```typescript
 @elementDefine('accommodation-router')
 class AccommodationRouter extends HTMLElement {
-  // Global route logger (order: -1 runs first, no return value)
-  @subscribeSwcAppRouteChangeWhileConnected(['*'], { order: -1 })
+  // Global route logger (order: -1 runs first, no path pattern = matches all routes)
+  @subscribeSwcAppRouteChangeWhileConnected({ order: -1 })
   onRouteChange(routerPathSet: RouterEventType) {
     console.log('[Route Change]', {
       path: routerPathSet.path,
@@ -851,6 +1105,97 @@ URL: /product/123
 pathData: { id: '123' }
 ```
 
+#### Multiple Decorators with Shared Return Value
+
+When using multiple decorators on the same method, each decorator can extract its own value from the return object using its symbol key or custom `valueKey` option.
+
+**How It Works:**
+1. Each decorator has a default symbol key (e.g., `ATTRIBUTE_METADATA_KEY`, `PROPERTY_METADATA_KEY`)
+2. When a method returns an object, each decorator checks if its key exists in the object
+3. If the key exists, the decorator uses that value; otherwise uses the entire return value
+4. This allows multiple decorators to extract different values from the same return object
+
+**Method 1: Using Default Symbol Keys**
+
+```typescript
+import {
+  ATTRIBUTE_METADATA_KEY,
+  PROPERTY_METADATA_KEY,
+  STYLE_METADATA_KEY,
+  CLASS_METADATA_KEY
+} from '@dooboostore/simple-web-component';
+
+@elementDefine('multi-decorator-example')
+class MultiDecoratorExample extends HTMLElement {
+  @setAttribute('selector')
+  @setProperty('selector')
+  @updateStyleThis
+  @updateClassThis
+  handleUpdate() {
+    return {
+      [ATTRIBUTE_METADATA_KEY]: 'attribute-value',
+      [PROPERTY_METADATA_KEY]: 'property-value',
+      [STYLE_METADATA_KEY]: { color: 'red', fontSize: '16px' },
+      [CLASS_METADATA_KEY]: { 'active': true, 'disabled': false }
+    };
+  }
+}
+```
+
+**Method 2: Using Custom valueKey Option**
+
+For more readable code, use the `valueKey` option to specify custom keys:
+
+```typescript
+@elementDefine('custom-key-example')
+class CustomKeyExample extends HTMLElement {
+  @setAttribute('selector', { valueKey: 'attrValue' })
+  @setProperty('selector', { valueKey: 'propValue' })
+  @updateStyleThis({ valueKey: 'styleValue' })
+  @updateClassThis({ valueKey: 'classValue' })
+  handleUpdate() {
+    return {
+      attrValue: 'attribute-value',
+      propValue: 'property-value',
+      styleValue: { color: 'red', fontSize: '16px' },
+      classValue: { 'active': true, 'disabled': false }
+    };
+  }
+}
+```
+
+**Method 3: Mixing Symbol Keys and Custom Keys**
+
+You can mix both approaches in the same method:
+
+```typescript
+@elementDefine('mixed-keys-example')
+class MixedKeysExample extends HTMLElement {
+  @setAttribute('selector')  // Uses default ATTRIBUTE_METADATA_KEY
+  @setProperty('selector', { valueKey: 'customProp' })  // Uses custom key
+  @updateStyleThis({ valueKey: 'styles' })  // Uses custom key
+  handleUpdate() {
+    return {
+      [ATTRIBUTE_METADATA_KEY]: 'attr-value',
+      customProp: 'prop-value',
+      styles: { color: 'blue' }
+    };
+  }
+}
+```
+
+**Supported Decorators with valueKey:**
+- `@applyAttribute` / `@setAttribute` / `@setAttributeThis`
+- `@applyProperty` / `@setProperty` / `@setPropertyThis`
+- `@applySlot` / `@clearSlot` / `@appendHtmlSlot` / etc.
+- `@applyNode` / `@replaceChildrenNodeThis` / etc.
+- `@applyStyle` / `@updateStyleThis` / etc.
+- `@applyClass` / `@updateClassThis` / etc.
+- `@emitCustomEvent` / `@emit` / `@emitCustomEventThis`
+- `@publishSwcAppMessage` / `@publish`
+
+Each decorator will use only its corresponding value from the return object, preventing conflicts and allowing clean separation of concerns.
+
 ---
 
 ### 12. **Accommodation Pattern**
@@ -858,29 +1203,39 @@ Factory-based component registration with explicit DI.
 
 ```typescript
 // Component factory
-import {SwcUtils, createElement, CreateElementConfig} from '@dooboostore/simple-web-component';
-const tagName = 'my-component';
-export interface MyComponent extends HTMLElement {
-  value: string;
-}
-export const MyComponent = (w: Window|Document, data?: CreateElementConfig) => {
-  return createElement<HTMLElement>(w, tagName, data);
-};
 export default (w: Window) => {
+  const tagName = 'my-component';
   const existing = w.customElements.get(tagName);
-  if (existing) return existing;
+  if (existing) return tagName;
 
   @elementDefine(tagName, { window: w })
-  class MyComponentImp extends w.HTMLElement implements MyComponent{
-    value: string = 'value';
+  class MyComponent extends w.HTMLElement {
     @onInitialize
-    onconstructor(service: MyService) {
+    onconstructor(@inject(MyService.SYMBOL) service: MyService) {
       this.service = service;
     }
   }
-  return w.customElements.whenDefined(swcAppTagName);
+
+  return tagName;
+};
+
+// Boot factory
+export default (w: Window, container: symbol) => {
+  serviceFactories.forEach(s => s(container));
 };
 
+// Entry point
+const container = Symbol('app');
+await defineSwcAppBody(w);
+const appElement = w.document.querySelector('#app') as SwcAppInterface;
+appElement.connect({
+  container,
+  window: w,
+  onStartedLazyDefineComponent: [...pageFactories, ...componentFactories],
+  onEngineStarted: () => {
+    appElement.innerHTML = '<root-router></root-router>';
+  }
+});
 ```
 ---
 

package/dist/cjs/decorators/addEventListener.js

@@ -27,6 +27,11 @@ __export(addEventListener_exports, {
   addEventListenerDocument: () => addEventListenerDocument,
   addEventListenerThis: () => addEventListenerThis,
   addEventListenerWindow: () => addEventListenerWindow,
+  event: () => event,
+  eventDelegate: () => eventDelegate,
+  eventDelegateAllDom: () => eventDelegateAllDom,
+  eventDelegateLightDom: () => eventDelegateLightDom,
+  eventDelegateShadowDom: () => eventDelegateShadowDom,
   getAddEventListenerMetadata: () => getAddEventListenerMetadata
 });
 module.exports = __toCommonJS(addEventListener_exports);
@@ -55,6 +60,11 @@ function addEventListenerDelegateAllDom(selector, type, options) {
 function addEventListenerDelegate(selector, type, options) {
   return addEventListener(selector, type, { ...options ?? {}, root: "auto", delegate: true });
 }
+const event = addEventListener;
+const eventDelegateLightDom = addEventListenerDelegateLightDom;
+const eventDelegateShadowDom = addEventListenerDelegateShadowDom;
+const eventDelegateAllDom = addEventListenerDelegateAllDom;
+const eventDelegate = addEventListenerDelegate;
 function addEventListenerThis(type, options) {
   return addEventListener("$this", type, options);
 }