@dooboostore/simple-web-component 1.0.22 → 1.0.24

package/README.md

@@ -260,19 +260,26 @@ class StyledCard extends HTMLElement {
 
 ### Attribute & Property Decorators
 
-#### 10. `@attributeHost(name, options?)`
-Bidirectional attribute binding with automatic type conversion.
+#### 10. `@attributeHost`
+Bidirectional attribute binding with automatic type conversion on `:host` element.
+
+All usage patterns support automatic field-name-to-attribute-name conversion:
+- Without parentheses: `@attributeHost` - uses field name as attribute name
+- Empty parentheses: `@attributeHost()` - uses field name as attribute name  
+- Options only: `@attributeHost({ connectedInitialize: true })` - uses field name as attribute name
+- Custom name: `@attributeHost('custom-name')` - explicit attribute name
+- Custom name + options: `@attributeHost('custom-name', { type: Boolean })` - both specified
 
 ```typescript
 @elementDefine('input-field')
 class InputField extends HTMLElement {
-  @attributeHost('value', { connectedInitialize: true })
+  @attributeHost
   value: string = '';
 
   @attributeHost('disabled')
   disabled: boolean = false;
 
-  @attributeHost('count')
+  @attributeHost({ type: Number })
   count: number = 0;
 
   @onConnectedInnerHtml
@@ -312,56 +319,119 @@ class ReactiveInput extends HTMLElement {
 }
 ```
 
-#### 12. `@setAttribute(name, options?)`
-Reflect method's return value to a DOM attribute. One-way binding (class → DOM).
+#### 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 DOM attribute
-  @setAttribute('data-status')
+  // Reflect status to host element's data-status attribute
+  @setAttribute(':host', 'data-status')
   getStatus() {
     return this.status;
   }
 
-  // Reflect computed data to attribute
-  @setAttribute('count')
+  // Reflect computed data to specific element
+  @setAttribute('#count-display', 'data-count')
   getItemCount() {
-    return this.getItems().length.toString();
+    return this.items.length.toString();
   }
 
-  // Reflect to Shadow DOM element
-  @setAttribute('aria-label', { root: 'shadow' })
+  // Reflect to Shadow DOM element's aria-label
+  @setAttribute('.badge-label', 'aria-label', { root: 'shadow' })
   getAriaLabel() {
     return `Status is ${this.status}`;
   }
 
-  private getItems() {
-    return [];
-  }
-
   @onConnectedInnerHtml
   render() {
     return `
-      <div class="badge" data-status="${this.status}">
-        Status: ${this.status}
+      <div 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
+  // Change status and update DOM attributes
   setStatus(newStatus: typeof this.status) {
     this.status = newStatus;
-    this.getStatus(); // Triggers @setAttribute update
+    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 (Method return reflects to attribute)
+- **`@setAttribute`** - One-way binding: Class → DOM (Any selector)
+- **`@setAttributeHost`** - One-way binding: Class → DOM (`:host` only)
 - **`@changedAttributeHost`** - Watch DOM attribute changes (Reactive handler)
 
 **Options:**
@@ -425,11 +495,110 @@ class ListRenderer extends HTMLElement {
 }
 ```
 
+#### 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
+
+#### 15. `@queryHost` - Query :host Element
+Specialized query for the component element itself. Supports automatic or explicit usage.
+
+All usage patterns automatically set the element reference:
+- Without parentheses: `@queryHost` self?: HTMLElement;
+- Empty parentheses: `@queryHost()` self?: HTMLElement;
+- With options: `@queryHost({ root: 'shadow' })` self?: HTMLElement;
+
+```typescript
+@elementDefine('custom-card')
+class CustomCard extends HTMLElement {
+  @queryHost
+  self?: HTMLElement;
+  
+  @queryHost()
+  selfExplicit?: HTMLElement;
+
+  printTag() {
+    console.log(this.self?.tagName); // Logs: CUSTOM-CARD
+  }
+}
+```
+
+#### 16. `@queryAllHost` - Query All :host Children
+Returns all children of the component element. Useful for accessing direct children.
+
+All usage patterns automatically set the children array:
+- Without parentheses: `@queryAllHost` children?: HTMLElement[];
+- Empty parentheses: `@queryAllHost()` children?: HTMLElement[];
+- With options: `@queryAllHost({ root: 'shadow' })` children?: HTMLElement[];
+
+```typescript
+@elementDefine('card-container')
+class CardContainer extends HTMLElement {
+  @queryAllHost
+  allChildren?: HTMLElement[];
+
+  getChildCount() {
+    return this.allChildren?.length ?? 0;
+  }
+}
+```
+
 ---
 
 ### Event & Messaging Decorators
 
-#### 15. `@addEventListener(selector, event, options?)`
+#### 17. `@addEventListener(selector, event, options?)`
 Declarative event binding with automatic delegation.
 
 ```typescript
@@ -486,7 +655,7 @@ class TodoApp extends HTMLElement {
 - ✅ Parent communication (`:parentHost`, `:appHost`)
 - ✅ Auto-cleanup on `disconnectedCallback`
 
-#### 16. `@emitCustomEvent(target, type, options?)`
+#### 18. `@emitCustomEvent(target, type, options?)`
 Emit custom events to component hierarchy or global targets.
 
 ```typescript
@@ -564,38 +733,47 @@ class UserWidget extends HTMLElement {
 
 ### DOM Manipulation Decorators
 
-#### 17. `@applyNode(selector, options?)`
+#### 19. `@applyNode(selector, options?)`
 Surgically add, update, or replace DOM nodes at specific positions.
 
 ```typescript
+import { htmlDivElement, htmlFragment, htmlSpanElement } from '@dooboostore/simple-web-component';
+
 @elementDefine('counter-display')
 class CounterDisplay extends HTMLElement {
   private count = 0;
+  private errorMessage = '';
 
-  // Replace all children with new content
+  // Replace all children with new content (return Node)
   @applyNode('#display', { position: 'replaceChildren' })
   updateDisplayCount() {
-    return `<span>${this.count}</span>`;
+    return htmlSpanElement(`${this.count}`);
   }
 
-  // Append to container
+  // Append to container (return Node)
   @applyNode('#history', { position: 'beforeEnd' })
   addHistoryEntry() {
-    return `<p>Count was: ${this.count}</p>`;
+    return htmlFragment(`<p>Count was: ${this.count}</p>`);
   }
 
-  // Set HTML content
+  // Set HTML content (return string)
   @applyNode('#status', { position: 'innerHtml' })
   setStatus() {
     return `<strong>Status: Active</strong>`;
   }
 
-  // Set text content
+  // Set text content (return string)
   @applyNode('#counter', { position: 'innerText' })
   updateCounter() {
     return this.count.toString();
   }
 
+  // Remove element if condition is truthy (return boolean)
+  @applyNode('#error-banner', { position: 'remove' })
+  dismissError() {
+    return this.errorMessage === '';  // Remove if no error
+  }
+
   @onConnectedInnerHtml
   render() {
     return `
@@ -604,6 +782,7 @@ class CounterDisplay extends HTMLElement {
       <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>
     `;
   }
 }
@@ -618,12 +797,349 @@ class CounterDisplay extends HTMLElement {
 - `'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:**
+
+Return **DOM Nodes** for position-based insertion. Use DOM creation functions:
+
+```typescript
+import { 
+  htmlFragment, htmlDivElement, htmlSpanElement, 
+  createElement, textNode 
+} from '@dooboostore/simple-web-component';
+
+@elementDefine('my-component')
+class MyComponent extends HTMLElement {
+  // Method 1: Using htmlFragment (DocumentFragment)
+  @applyBeforeBeginNode('#target') prependTarget() { 
+    return htmlFragment('<div>Before</div>');
+  }
+
+  // Method 2: Using htmlDivElement (single element)
+  @applyAfterBeginNode('#target') afterBeginTarget() { 
+    return htmlDivElement('After Begin');
+  }
+
+  // Method 3: Manual createElement (full control)
+  @applyBeforeEndNode('#target') beforeEndTarget() { 
+    return htmlDivElement('Before End');
+  }
+
+  @applyAfterEndNode('#target') afterEndTarget() { 
+    const el = htmlDivElement('After');
+    el.classList.add('highlight');
+    return el;
+  }
+
+  @applyReplaceNode('#target') replaceTarget() { 
+    return htmlFragment('<div class="replaced">Replaced</div>');
+  }
+
+  // Multiple nodes: return array
+  @applyReplaceChildrenNode('#target') replaceChildrenTarget() { 
+    return [
+      htmlDivElement('Item 1'),
+      htmlDivElement('Item 2'),
+      htmlDivElement('Item 3')
+    ];
+  }
+
+  // String return for innerHtml
+  @applyInnerHtmlNode('#target') setInnerHtml() { 
+    return `<b>Bold</b> <i>Italic</i>`;
+  }
+
+  // String return for innerText
+  @applyInnerTextNode('#target') setInnerText() { 
+    return 'Plain text';
+  }
+
+  // Boolean return for remove
+  @applyRemoveNode('#target') removeTarget() { 
+    return this.shouldHideTarget;
+  }
+}
+```
+
+**SSR Support (with custom Document):**
+
+```typescript
+// Browser
+return htmlDivElement('Content');  // Uses global document
+
+// SSR (e.g. Node.js with jsdom)
+const ssrDocument = new JSDOM().window.document;
+return htmlDivElement('Content', ssrDocument);  // Pass custom doc
+```
+
+**Host-Targeted Variants (`:host` selector):**
+
+All Host variants support three usage patterns:
+- Without parentheses: `@applyBeforeBeginNodeHost` prependHost() { ... }
+- With empty parentheses: `@applyBeforeBeginNodeHost()` prependHost() { ... }
+- With options: `@applyBeforeBeginNodeHost({ ... })` prependHost() { ... }
+
+```typescript
+@elementDefine('my-component')
+class MyComponent extends HTMLElement {
+  @applyBeforeBeginNodeHost
+  prependHost() { 
+    return htmlFragment('<div>Before Host</div>');
+  }
+
+  @applyAfterBeginNodeHost() afterBeginHost() { 
+    return htmlSpanElement('After Begin');
+  }
+
+  @applyBeforeEndNodeHost beforeEndHost() { 
+    const el = htmlDivElement('Before End');
+    return el;
+  }
+
+  @applyAfterEndNodeHost afterEndHost() { 
+    return htmlFragment('After Host');
+  }
+
+  @applyReplaceNodeHost replaceHost() { 
+    return htmlFragment('<div>Replaced Host</div>');
+  }
+
+  // Multiple children in shadow DOM
+  @applyReplaceChildrenNodeHost() replaceChildrenHost() { 
+    return [
+      htmlDivElement('Shadow Child 1'),
+      htmlDivElement('Shadow Child 2')
+    ];
+  }
+
+  @applyInnerHtmlNodeHost setHostInnerHtml() { 
+    return `<h1>Host Content</h1>`;
+  }
+
+  @applyInnerTextNodeHost() setHostInnerText() { 
+    return 'Host text content';
+  }
+
+  @applyRemoveNodeHost removeHost() { 
+    return this.isRemoved;
+  }
+}
+```
+
+**Return Types by Position:**
+- `beforeBegin`, `afterBegin`, `beforeEnd`, `afterEnd`: **Node | Node[]** 
+- `replace`: **Node**
+- `replaceChildren`: **Node | Node[]**
+- `innerHtml`: **string**
+- `innerText`: **string**
+- `remove`: **boolean** (truthy = remove)
+
+**Available DOM Functions:**
+- `htmlFragment(html, doc?)` - Create DocumentFragment from HTML
+- `textNode(text, doc?)` - Create Text node
+- `commentNode(comment, doc?)` - Create Comment node
+- `createElement(tagName, options?, doc?)` - Create any element with attributes
+- `htmlDivElement(html, doc?)` - Create div element
+- `htmlSpanElement(html, doc?)` - Create span element
+- `htmlButtonElement(html, doc?)` - Create button element
+- `htmlAElement(html, href?, doc?)` - Create anchor element
+- `htmlPElement(html, doc?)` - Create paragraph element
+- `htmlLiElement(html, doc?)` - Create list item element
+- `htmlUlElement(doc?)` - Create unordered list
+- `htmlHeadingElement(level, html, doc?)` - Create h1-h6
+- `htmlSectionElement(doc?)` - Create section
+- `htmlArticleElement(doc?)` - Create article
+
+**All functions accept optional `doc` parameter for SSR support.**
+
+#### 20. `@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:**
+
+Note: `:host` selector targets the component itself (boundary), so `root` option is ignored.
+
+All Host variants support three usage patterns:
+- Without parentheses: `@setStyleHost` setHostStyle() { ... }
+- With empty parentheses: `@setStyleHost()` setHostStyle() { ... }
+- With options: `@setStyleHost({ ... })` setHostStyle() { ... }
+
+```typescript
+@setStyleHost
+setHostStyle() {
+  return { display: 'flex', gap: '10px' };
+}
+
+@updateStyleHost()
+updateHostStyle() {
+  return { backgroundColor: '#f0f0f0' };
+}
+
+@removeStyleHost()
+clearHostStyle() {
+  return ['backgroundColor'];
+}
+```
+
+---
+
+#### 21. `@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:**
+
+Note: `:host` selector targets the component itself (boundary), so `root` option is ignored.
+
+All Host variants support three usage patterns:
+- Without parentheses: `@setClassListHost` setHostClasses() { ... }
+- With empty parentheses: `@setClassListHost()` setHostClasses() { ... }
+- With options: `@setClassListHost({ ... })` setHostClasses() { ... }
+
+```typescript
+@addClassListHost
+addHostClasses() {
+  return ['component', 'interactive'];
+}
+
+@removeClassListHost()
+removeHostClasses() {
+  return ['loading'];
+}
+
+@toggleClassListHost()
+toggleHostClass() {
+  return this.isOpen;  // Apply 'open' class if true
+}
+
+@setClassListHost
+setHostClasses() {
+  return this.isOpen ? ['open', 'expanded'] : ['closed'];
+}
+
+@updateClassListHost()
+updateHostClasses() {
+  return ['visible'];
+}
+```
 
 ---
 
 ### Dependency Injection & Singleton
 
-#### 18. `@Sim`
+#### 22. `@Sim`
 Marks a class as a **Singleton** in the `<swc-app>` DI container for **constructor injection**.
 
 **Two DI Mechanisms:**
@@ -1270,6 +1786,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**.