snice 4.12.0 → 4.14.0

package/docs/elements.md

@@ -10,7 +10,7 @@ Elements are the core building blocks of Snice components. They define custom HT
 - [Queries](#queries)
 - [Styling](#styling)
 - [Template Events](#template-events)
-- [Advanced Examples](#advanced-examples)
+- [Advanced Examples](#advanced-examples) (Watch, Context, Conditionals)
 
 ## Basic Usage
 
@@ -30,8 +30,10 @@ class MyButton extends HTMLElement {
 
 ### Element Decorator Options
 
-The `@element` decorator accepts a single parameter:
+The `@element` decorator accepts:
 - `tagName: string` - The custom element tag name (must contain a hyphen)
+- `options?: ElementOptions` - Optional configuration
+  - `formAssociated?: boolean` - Enable form association (default: false)
 
 ## Lifecycle Methods
 
@@ -106,7 +108,7 @@ class SimpleList extends HTMLElement {
 - Avoiding differential rendering issues with dynamic attributes
 - Simple components where full re-render is acceptable
 
-**Note:** When `differential: false`, the render method must return a string (not `html\`...\``) and still honors `<if>` and `<switch>/<case>` meta elements.
+**Note:** When `differential: false`, the render method must return a string (not `html\`...\``). Conditional rendering (`<if>`, `<switch>/<case>`) is NOT available — use ternary operators in the string template instead.
 
 ### Imperative Rendering
 
@@ -132,7 +134,7 @@ class UserCard extends HTMLElement {
   }
 
   @watch('name', 'role')
-  update() {
+  update(oldVal: any, newVal: any, prop: string) {
     if (!this.$name) return;
     this.$name.textContent = this.name;
     this.$role.textContent = this.role;
@@ -195,44 +197,39 @@ class StyledCard extends HTMLElement {
 }
 ```
 
-**Multiple Style Methods:**
+**Note:** Only one `@styles()` method is supported per element. If multiple are declared, only the last one is used. Combine all styles in a single method:
+
 ```typescript
 @styles()
-baseStyles() {
+componentStyles() {
   return css`
     :host { display: block; }
-    // ...
-  `;
-}
-
-@styles()
-themeStyles() {
-  return css`
     .card { background: var(--bg-color); }
-    // ...
   `;
 }
 ```
 
 ### Lifecycle Decorators
 
-**@ready()** - Called after shadow DOM is ready and initial render completes:
+**@ready()** - Called after styles are applied and event handlers are set up. The initial render may still be completing in a microtask — use `@query` (which re-queries each access) to safely access rendered DOM:
 
 ```typescript
-import { element, ready, render, html } from 'snice';
+import { element, ready, query, render, html } from 'snice';
+
+@element('auto-resize-textarea')
+class AutoResizeTextarea extends HTMLElement {
+  @query('textarea') textarea?: HTMLTextAreaElement;
 
-@element('data-loader')
-class DataLoader extends HTMLElement {
   @ready()
-  async loadData() {
-    // Called after element is fully initialized
-    const data = await fetch('/api/data').then(r => r.json());
-    this.data = data;
+  adjustHeight() {
+    if (this.textarea) {
+      this.textarea.style.height = `${this.textarea.scrollHeight}px`;
+    }
   }
 
   @render()
   renderContent() {
-    return html`<div>Loading...</div>`;
+    return html`<textarea @input=${this.adjustHeight}></textarea>`;
   }
 }
 ```
@@ -240,27 +237,29 @@ class DataLoader extends HTMLElement {
 **@dispose()** - Called when element is removed from DOM:
 
 ```typescript
-@element('polling-element')
-class PollingElement extends HTMLElement {
-  private intervalId?: number;
+@element('animated-element')
+class AnimatedElement extends HTMLElement {
+  private rafId?: number;
 
   @ready()
-  startPolling() {
-    this.intervalId = setInterval(() => {
-      this.updateData();
-    }, 5000);
+  startAnimation() {
+    const animate = () => {
+      // Update animation frame
+      this.rafId = requestAnimationFrame(animate);
+    };
+    this.rafId = requestAnimationFrame(animate);
   }
 
   @dispose()
-  stopPolling() {
-    if (this.intervalId) {
-      clearInterval(this.intervalId);
+  stopAnimation() {
+    if (this.rafId) {
+      cancelAnimationFrame(this.rafId);
     }
   }
 
   @render()
   renderContent() {
-    return html`<div>Polling...</div>`;
+    return html`<canvas width="300" height="200"></canvas>`;
   }
 }
 ```
@@ -279,20 +278,23 @@ await (el as any).ready; // Wait for element to be ready
 
 All elements automatically use Shadow DOM for style encapsulation.
 
-### Accessing Shadow Root
+### Accessing Shadow DOM Elements
+
+Use `@query` instead of manual `shadowRoot.querySelector`:
 
 ```typescript
 @element('shadow-demo')
 class ShadowDemo extends HTMLElement {
+  @query('#content') content?: HTMLElement;
+
   @render()
   renderContent() {
     return html`<div id="content">Hello</div>`;
   }
 
   updateContent(text: string) {
-    const content = this.shadowRoot?.getElementById('content');
-    if (content) {
-      content.textContent = text;
+    if (this.content) {
+      this.content.textContent = text;
     }
   }
 }
@@ -341,7 +343,7 @@ Usage:
 ```typescript
 interface PropertyOptions {
   type?: String | Number | Boolean | Array | Object | Date | BigInt | SimpleArray;
-  attribute?: string;        // Custom attribute name
+  attribute?: string | boolean;  // Custom attribute name, or false to disable attribute sync
   converter?: PropertyConverter;  // Custom converter
   hasChanged?: (value: any, oldValue: any) => boolean;
 }
@@ -351,10 +353,12 @@ interface PropertyOptions {
 
 All properties automatically:
 - Read from DOM attributes when present
-- Reflect changes to corresponding attributes
+- Reflect property setter changes to corresponding attributes
 - Convert between string attributes and typed properties
 - Trigger re-renders when changed
 
+**Note:** Initial field values (defaults like `name = 'Anonymous'`) are NOT reflected to attributes. Only changes made via the property setter are reflected. Set `attribute: false` to disable attribute sync entirely.
+
 ```typescript
 @element('reflected-props')
 class ReflectedProps extends HTMLElement {
@@ -568,26 +572,28 @@ class ScopedStyles extends HTMLElement {
 
 ### Dynamic Styles
 
+`@styles()` is called **once** during initialization and does not update on property changes. For dynamic styling, use CSS custom properties set in the template:
+
 ```typescript
 @element('theme-component')
 class ThemeComponent extends HTMLElement {
   @property()
-  primaryColor = '#007bff';
-
-  @property({ type: Number })
-  fontSize = 16;
+  accentColor = '#007bff';
 
   @render()
   renderContent() {
-    return html`<div class="themed">Themed content</div>`;
+    return html`
+      <div class="themed" style="--accent: ${this.accentColor}">
+        Themed content
+      </div>
+    `;
   }
 
   @styles()
   themeStyles() {
     return css`
       .themed {
-        color: ${this.primaryColor};
-        font-size: ${this.fontSize}px;
+        color: var(--accent);
       }
     `;
   }
@@ -722,35 +728,38 @@ class FormHandler extends HTMLElement {
 
 ## Advanced Examples
 
-### Complex Form Component
+### Form Component
+
+Elements handle visual behavior — they render the form and emit events. Business logic (API calls, validation) belongs in controllers:
 
 ```typescript
-import { element, property, query, watch, render, styles, html, css } from 'snice';
+import { element, property, query, dispatch, render, styles, html, css } from 'snice';
 
 @element('registration-form')
 class RegistrationForm extends HTMLElement {
   @property({ type: Boolean })
   loading = false;
 
-  @query('form')
-  form?: HTMLFormElement;
+  @query('form') form?: HTMLFormElement;
+
+  @dispatch('register-submit')
+  handleSubmit(event: Event) {
+    event.preventDefault();
+    return Object.fromEntries(new FormData(this.form!));
+  }
 
   @render()
   renderContent() {
     return html`
       <form @submit=${this.handleSubmit}>
-        <h2>Register</h2>
-
         <div class="field">
           <label>Username</label>
           <input type="text" name="username" required>
         </div>
-
         <div class="field">
           <label>Email</label>
           <input type="email" name="email" required>
         </div>
-
         <button type="submit" ?disabled=${this.loading}>
           ${this.loading ? 'Registering...' : 'Register'}
         </button>
@@ -764,78 +773,37 @@ class RegistrationForm extends HTMLElement {
       :host {
         display: block;
         max-width: 400px;
-        margin: 0 auto;
-      }
-
-      form {
-        padding: 20px;
-        background: white;
-        border-radius: 8px;
       }
 
       .field {
-        margin-bottom: 20px;
+        margin-bottom: 1rem;
       }
 
       label {
         display: block;
-        margin-bottom: 5px;
+        margin-bottom: 0.25rem;
         font-weight: bold;
       }
 
       input {
         width: 100%;
-        padding: 8px 12px;
-        border: 1px solid #ddd;
+        padding: 0.5rem;
+        border: 1px solid var(--snice-color-border, #ddd);
         border-radius: 4px;
       }
 
-      button {
-        width: 100%;
-        padding: 10px;
-        background: #007bff;
-        color: white;
-        border: none;
-        border-radius: 4px;
-        cursor: pointer;
-      }
-
       button:disabled {
         opacity: 0.6;
         cursor: not-allowed;
       }
     `;
   }
-
-  async handleSubmit(event: Event) {
-    event.preventDefault();
-
-    this.loading = true;
-
-    try {
-      const formData = new FormData(this.form!);
-
-      // Simulate API call
-      await new Promise(resolve => setTimeout(resolve, 2000));
-
-      this.dispatchEvent(new CustomEvent('registration-success', {
-        detail: Object.fromEntries(formData),
-        bubbles: true
-      }));
-
-      this.form?.reset();
-    } catch (error) {
-      console.error('Registration failed:', error);
-    } finally {
-      this.loading = false;
-    }
-  }
 }
 ```
 
 ### Watch Decorator
 
-Use `@watch` to react to property changes:
+Use `@watch` to react to property changes. Handlers receive three arguments: `(oldValue, newValue, propertyName)`.
 
 ```typescript
 @element('reactive-component')
@@ -847,8 +815,8 @@ class ReactiveComponent extends HTMLElement {
   score = 0;
 
   @watch('userName')
-  onUserNameChange(oldVal: string, newVal: string) {
-    console.log(`Name changed from ${oldVal} to ${newVal}`);
+  onUserNameChange(oldVal: string, newVal: string, prop: string) {
+    console.log(`${prop} changed from ${oldVal} to ${newVal}`);
   }
 
   @watch('score')
@@ -858,6 +826,12 @@ class ReactiveComponent extends HTMLElement {
     }
   }
 
+  // Wildcard watcher — fires on any @property change
+  @watch('*')
+  onAnyChange(oldVal: any, newVal: any, prop: string) {
+    console.log(`${prop}: ${oldVal} → ${newVal}`);
+  }
+
   @render()
   renderContent() {
     return html`
@@ -870,6 +844,60 @@ class ReactiveComponent extends HTMLElement {
 }
 ```
 
+### @context() Decorator
+
+Receive router context updates. The decorated method is called whenever the router context changes (navigation, app context update, etc.):
+
+```typescript
+import { element, context, property, render, html } from 'snice';
+import type { Context, Placard } from 'snice';
+
+@element('nav-bar')
+class NavBar extends HTMLElement {
+  @property({ type: Array })
+  placards: Placard[] = [];
+
+  @property()
+  currentRoute = '';
+
+  @context()
+  onContextUpdate(ctx: Context) {
+    this.placards = ctx.navigation.placards;
+    this.currentRoute = ctx.navigation.route;
+  }
+
+  @render()
+  renderContent() {
+    return html`
+      <nav>
+        ${this.placards
+          .filter(p => p.show !== false)
+          .map(p => html`
+            <a href="#/${p.name}" class="${this.currentRoute === p.name ? 'active' : ''}">
+              ${p.icon} ${p.title}
+            </a>
+          `)}
+      </nav>
+    `;
+  }
+}
+```
+
+**Context Options:**
+
+```typescript
+@context({ debounce: 300 })   // Wait 300ms after last change
+@context({ throttle: 500 })   // At most once per 500ms
+@context({ once: true })       // Only called once, then auto-unregisters
+```
+
+The `Context` object provides:
+- `ctx.application` — App context (theme, auth, config, etc.)
+- `ctx.navigation.route` — Current route path
+- `ctx.navigation.params` — Route parameters
+- `ctx.navigation.placards` — All registered page placards
+- `ctx.fetch` — Fetch with middleware support (see Fetcher docs)
+
 ### Conditional Rendering
 
 ```typescript
@@ -898,18 +926,4 @@ class ConditionalContent extends HTMLElement {
 }
 ```
 
-## Best Practices
-
-1. **Use @render() for templates**: Always return `html\`...\`` tagged templates
-2. **Use @styles() for CSS**: Always return `css\`...\`` tagged templates
-3. **Leverage auto-rendering**: Properties automatically trigger re-renders
-4. **Use template events**: Handle events with `@event=${handler}` in templates
-5. **Clean up resources**: Use @dispose() for cleanup tasks
-6. **Type your queries**: Use proper TypeScript types for queried elements
-7. **Handle errors**: Wrap async operations in try-catch blocks
-
-## Removed in v3.0.0
 
-- **@part decorator**: Removed in favor of differential rendering. Use `@render()` with templates instead.
-- **html() method**: Replaced with `@render()` decorator
-- **css() method**: Replaced with `@styles()` decorator

package/docs/events.md

@@ -1,10 +1,10 @@
 # Events API Documentation
 
-Event handling in Snice provides two powerful approaches: **template event syntax** and the **`@on` decorator** (fully restored from v2.5.4!). The `@on` decorator now works in **both elements AND controllers** with full event delegation, keyboard modifiers, debounce/throttle, and more. Additionally, the `@dispatch` decorator enables automatic custom event dispatching.
+Event handling in Snice provides two powerful approaches: **template event syntax** and the **`@on` decorator**. The `@on` decorator works in **both elements AND controllers** with full event delegation, keyboard modifiers, debounce/throttle, and more. Additionally, the `@dispatch` decorator enables automatic custom event dispatching.
 
 ## Table of Contents
 - [Template Event Syntax](#template-event-syntax)
-- [@on Decorator (v2.5.4 RESTORED!)](#on-decorator-v254-restored)
+- [@on Decorator](#on-decorator)
 - [@dispatch Decorator](#dispatch-decorator)
 - [Custom Events](#custom-events)
 - [Event Delegation](#event-delegation)
@@ -247,15 +247,15 @@ class TaskList extends HTMLElement {
 }
 ```
 
-## @on Decorator (v2.5.4 RESTORED!)
+## @on Decorator
 
-The `@on` decorator is **fully restored from v2.5.4** and now works in **both elements AND controllers**! It provides powerful event delegation, keyboard modifiers, debounce/throttle, and automatic event handling features.
+The `@on` decorator works in **both elements AND controllers**. It provides powerful event delegation, keyboard modifiers, debounce/throttle, and automatic event handling features.
 
 **Use `@on` when you need:**
 - Event delegation with CSS selectors
 - Keyboard modifier matching (`Enter`, `ctrl+s`, etc.)
 - Debounce or throttle
-- Multiple events on one handler
+- Multiple events on one handler (accepts `string[]`: `@on(['mouseenter', 'focus'])`)
 - Automatic preventDefault or stopPropagation
 
 ### Basic Controller Usage
@@ -378,12 +378,9 @@ interface OnOptions {
   preventDefault?: boolean;    // Automatically call preventDefault on the event
   stopPropagation?: boolean;   // Automatically call stopPropagation on the event
 
-  // Timing controls (v3.0.0 enhancements!)
+  // Timing controls
   debounce?: number;           // Debounce the handler by specified milliseconds
   throttle?: number;           // Throttle the handler by specified milliseconds
-
-  // Event delegation
-  target?: string;             // CSS selector to target specific elements within shadow root
 }
 ```
 
@@ -437,8 +434,8 @@ While template syntax is preferred, `@on` can also be used in elements:
 ```typescript
 import { element, on, render, html } from 'snice';
 
-@element('legacy-button')
-class LegacyButton extends HTMLElement {
+@element('my-button')
+class MyButton extends HTMLElement {
   @render()
   renderContent() {
     return html`<button class="btn">Click me</button>`;
@@ -505,6 +502,8 @@ input.addEventListener('value-changed', (e: CustomEvent) => {
 
 ### Event Options
 
+Events dispatched by `@dispatch` default to `bubbles: true` and `composed: true` (crosses shadow DOM boundaries). Override if needed:
+
 ```typescript
 @element('status-indicator')
 class StatusIndicator extends HTMLElement {
@@ -513,7 +512,8 @@ class StatusIndicator extends HTMLElement {
     return html`<div>Status</div>`;
   }
 
-  @dispatch('status-changed', { bubbles: true, composed: true })
+  // Defaults: bubbles: true, composed: true
+  @dispatch('status-changed')
   updateStatus(status: string) {
     return {
       status,
@@ -523,36 +523,77 @@ class StatusIndicator extends HTMLElement {
 }
 ```
 
-### Multiple Dispatches
+### DispatchOptions
 
 ```typescript
-@element('data-manager')
-class DataManager extends HTMLElement {
-  private data: any[] = [];
+interface DispatchOptions extends EventInit {
+  dispatchOnUndefined?: boolean; // Skip dispatch when return is undefined (default: true)
+  debounce?: number;             // Debounce dispatch by ms
+  throttle?: number;             // Throttle dispatch by ms
+}
+```
+
+### Debounce/Throttle
 
+```typescript
+@element('search-box')
+class SearchBox extends HTMLElement {
   @render()
   renderContent() {
-    return html`<div>Data Manager</div>`;
+    return html`<input @input=${this.handleInput}>`;
   }
 
-  @dispatch('item-added')
-  addItem(item: any) {
-    this.data.push(item);
-    return { item, total: this.data.length };
+  handleInput(e: Event) {
+    this.emitSearch((e.target as HTMLInputElement).value);
   }
 
-  @dispatch('item-removed')
-  removeItem(id: string) {
-    const item = this.data.find(i => i.id === id);
-    this.data = this.data.filter(i => i.id !== id);
-    return { id, item, total: this.data.length };
+  @dispatch('search-query', { debounce: 300 })
+  emitSearch(query: string) {
+    return { query };
   }
+}
+```
+
+### Async Methods
+
+`@dispatch` works with async methods — the event dispatches after the promise resolves:
 
-  @dispatch('data-cleared')
-  clearData() {
-    const count = this.data.length;
-    this.data = [];
-    return { clearedCount: count };
+```typescript
+@dispatch('validation-complete')
+async validate() {
+  const result = await this.runValidation();
+  return { valid: result.isValid, errors: result.errors };
+}
+```
+
+### Multiple Events
+
+```typescript
+@element('color-picker')
+class ColorPicker extends HTMLElement {
+  @property() color = '#000000';
+
+  @render()
+  renderContent() {
+    return html`
+      <input type="color" .value=${this.color} @input=${this.handleInput}>
+      <button @click=${this.confirm}>OK</button>
+    `;
+  }
+
+  handleInput(e: Event) {
+    this.changeColor((e.target as HTMLInputElement).value);
+  }
+
+  @dispatch('color-preview')
+  changeColor(color: string) {
+    this.color = color;
+    return { color };
+  }
+
+  @dispatch('color-selected')
+  confirm() {
+    return { color: this.color };
   }
 }
 ```
@@ -615,8 +656,8 @@ class TableController implements IController {
   // Single event listener handles all rows
   @on('click', 'tr')
   handleRowClick(event: MouseEvent) {
-    const row = event.currentTarget as HTMLTableRowElement;
-    console.log('Row clicked:', row.dataset.id);
+    const row = (event.target as HTMLElement).closest('tr');
+    console.log('Row clicked:', row?.dataset.id);
   }
 
   // Handle button clicks in cells
@@ -754,54 +795,4 @@ class KeyboardController implements IController {
 }
 ```
 
-## Best Practices
-
-### For Elements
-
-1. **Prefer template syntax**: Use `@event=${handler}` in templates
-2. **Use arrow functions for parameters**: `@click=${() => this.delete(id)}`
-3. **Handle events at appropriate level**: Use event delegation for dynamic content
-4. **Prevent default when needed**: Call `e.preventDefault()` in handlers
-5. **Use keyboard shortcuts**: Leverage `@keydown.ctrl+s` syntax
-
-### For Controllers
-
-1. **Use @on decorator**: Controllers should use `@on` for event handling
-2. **Leverage event delegation**: Use selectors to handle dynamic content
-3. **Throttle/debounce high-frequency events**: Use `{ throttle }` or `{ debounce }` options
-4. **Clean up automatically**: Event listeners are cleaned up on detach
-5. **Handle keyboard shortcuts**: Use `@on('keydown:Ctrl+S')` syntax
-
-### General
-
-1. **Type your events**: Use TypeScript event types for type safety
-2. **Stop propagation carefully**: Only use `stopPropagation()` when necessary
-3. **Use custom events**: Dispatch custom events for component communication
-4. **Compose events**: Use `{ composed: true }` for cross-shadow-DOM events
-5. **Test event handlers**: Write tests for all event handling logic
-
-## Event Types Reference
-
-**Mouse Events:**
-- `click`, `dblclick`, `mousedown`, `mouseup`
-- `mouseenter`, `mouseleave`, `mousemove`, `mouseover`, `mouseout`
-- `contextmenu`
-
-**Keyboard Events:**
-- `keydown`, `keyup`, `keypress`
-
-**Form Events:**
-- `input`, `change`, `submit`, `reset`
-- `focus`, `blur`, `focusin`, `focusout`
-
-**Drag Events:**
-- `drag`, `dragstart`, `dragend`
-- `dragenter`, `dragover`, `dragleave`, `drop`
-
-**Touch Events:**
-- `touchstart`, `touchmove`, `touchend`, `touchcancel`
 
-**Other Events:**
-- `scroll`, `resize`, `load`, `error`
-- `animationstart`, `animationend`, `animationiteration`
-- `transitionstart`, `transitionend`