snice 4.13.0 → 4.14.0

package/docs/controllers.md

@@ -62,18 +62,23 @@ interface IController<T extends HTMLElement = HTMLElement> {
 
 1. Controller instance is created
 2. `element` property is set
-3. Element's `ready` promise is awaited
-4. `attach()` method is called
-5. Event and channel handlers are set up
-6. `@snice/controller-attached` event is dispatched
+3. Router context is passed (if available)
+4. Element's `ready` promise is awaited
+5. `attach()` method is called
+6. Observers are set up
+7. Channel/response handlers are set up
+8. Event handlers are set up
+9. `@snice/controller-attached` event is dispatched
 
 ### Detachment Flow
 
 1. `detach()` method is called
 2. `element` property is set to null
-3. Event and channel handlers are cleaned up
-4. Controller scope is cleaned up
-5. `@snice/controller-detached` event is dispatched
+3. Observers are cleaned up
+4. Channel/response handlers are cleaned up
+5. Event handlers are cleaned up
+6. Controller scope is cleaned up
+7. `@snice/controller-detached` event is dispatched
 
 ### Example with Lifecycle Logging
 
@@ -154,53 +159,29 @@ This allows you to attach controllers to any HTML element:
 
 ### Example: Table Controller
 
+Controllers provide specific behaviors (data fetching, sorting, filtering) to generic visual components. The component handles rendering — the controller handles data:
+
 ```typescript
 @controller('table-controller')
 class TableController implements IController<HTMLTableElement> {
   element: HTMLTableElement | null = null;
-  private data: any[] = [];
 
   async attach(element: HTMLTableElement) {
-    // Fetch data
-    this.data = await this.fetchData();
-
-    // Render table
-    this.renderTable();
-  }
+    const data = await fetch('/api/data').then(r => r.json());
 
-  async detach(element: HTMLTableElement) {
-    // Clear table
-    const tbody = element.querySelector('tbody');
-    if (tbody) {
-      tbody.innerHTML = '';
+    // Pass data to the element — if it's a custom element, call its API
+    if ('setData' in element && typeof (element as any).setData === 'function') {
+      (element as any).setData(data);
     }
   }
 
-  private async fetchData() {
-    const response = await fetch('/api/data');
-    return response.json();
-  }
-
-  private renderTable() {
-    if (!this.element) return;
-
-    const tbody = this.element.querySelector('tbody');
-    if (!tbody) return;
-
-    tbody.innerHTML = this.data.map(row => `
-      <tr>
-        <td>${row.id}</td>
-        <td>${row.name}</td>
-        <td>${row.status}</td>
-      </tr>
-    `).join('');
-  }
+  async detach() {}
 }
 ```
 
 ## Resource Cleanup
 
-Controllers should clean up resources in the `detach` method:
+The framework auto-cleans `@on`, `@observe`, and `@respond` handlers. Clean up your own resources (WebSockets, timers, manual listeners) in `detach`:
 
 ```typescript
 import { controller, IController } from 'snice';
@@ -287,63 +268,37 @@ class FormController implements IController<HTMLFormElement> {
 
 ## Query Selectors in Controllers
 
-Controllers can use `@query` and `@queryAll` to access elements:
+Controllers can use `@query` and `@queryAll` to access elements. **Important:** By default, `@query` searches the shadow DOM. When attached to native elements (no shadow root), use `{ light: true }`:
 
 ```typescript
 import { controller, query, queryAll, IController } from 'snice';
 
-@controller('dashboard-controller')
-class DashboardController implements IController {
-  element: HTMLElement | null = null;
-
-  @query('.status-indicator')
-  statusIndicator?: HTMLElement;
-
-  @query('#refresh-button')
-  refreshButton?: HTMLButtonElement;
-
-  @queryAll('.data-card')
-  dataCards?: NodeListOf<HTMLElement>;
+@controller('form-validation-controller')
+class FormValidationController implements IController<HTMLFormElement> {
+  element: HTMLFormElement | null = null;
 
-  async attach(element: HTMLElement) {
-    // Queries work on the attached element
-    this.updateStatus('Loading...');
+  // light: true is required — native elements have no shadow root
+  @query('.error-message', { light: true })
+  errorEl?: HTMLElement;
 
-    // Fetch and display data
-    await this.loadDashboardData();
+  @queryAll('input[required]', { light: true })
+  requiredInputs?: NodeListOf<HTMLInputElement>;
 
-    this.updateStatus('Ready');
-  }
+  async attach() {}
+  async detach() {}
 
-  async detach(element: HTMLElement) {
-    this.updateStatus('Offline');
-  }
+  @on('submit')
+  handleSubmit(event: Event) {
+    const invalid = Array.from(this.requiredInputs || []).filter(i => !i.value.trim());
 
-  private updateStatus(status: string) {
-    if (this.statusIndicator) {
-      this.statusIndicator.textContent = status;
+    if (invalid.length > 0) {
+      event.preventDefault();
+      invalid[0].focus();
+      if (this.errorEl) {
+        this.errorEl.textContent = `${invalid.length} required field(s) missing`;
+      }
     }
   }
-
-  private async loadDashboardData() {
-    // Load data for each card
-    this.dataCards?.forEach(async (card, index) => {
-      const data = await this.fetchCardData(index);
-      card.innerHTML = this.renderCard(data);
-    });
-  }
-
-  private async fetchCardData(index: number) {
-    // Simulate API call
-    return { title: `Card ${index + 1}`, value: Math.random() * 100 };
-  }
-
-  private renderCard(data: any) {
-    return `
-      <h3>${data.title}</h3>
-      <p>${data.value.toFixed(2)}</p>
-    `;
-  }
 }
 ```
 
@@ -351,6 +306,8 @@ class DashboardController implements IController {
 
 ### Data Fetching Controller
 
+Controllers own data fetching. Pass results to the element via its API or dispatch events — don't manipulate DOM directly:
+
 ```typescript
 @controller('data-fetcher')
 class DataFetcherController implements IController {
@@ -359,219 +316,66 @@ class DataFetcherController implements IController {
   private pollingInterval?: number;
 
   async attach(element: HTMLElement) {
-    // Initial data load
-    await this.fetchAndRender();
+    await this.fetchData();
 
-    // Set up polling
-    this.pollingInterval = setInterval(() => {
-      this.fetchAndRender();
-    }, 30000); // Poll every 30 seconds
+    // Poll every 30 seconds
+    this.pollingInterval = setInterval(() => this.fetchData(), 30000);
   }
 
-  async detach(element: HTMLElement) {
-    // Cancel any pending requests
+  async detach() {
     this.abortController?.abort();
-
-    // Stop polling
     if (this.pollingInterval) {
       clearInterval(this.pollingInterval);
     }
   }
 
-  private async fetchAndRender() {
-    try {
-      // Cancel previous request if still pending
-      this.abortController?.abort();
-      this.abortController = new AbortController();
-
-      // Show loading state
-      this.setLoadingState(true);
+  private async fetchData() {
+    this.abortController?.abort();
+    this.abortController = new AbortController();
 
-      // Fetch data with timeout
+    try {
       const response = await fetch('/api/data', {
         signal: this.abortController.signal
       });
-
-      if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
-      }
-
       const data = await response.json();
 
-      // Render data
-      this.renderData(data);
-
+      // Pass data to element — let the element handle rendering
+      this.element?.dispatchEvent(new CustomEvent('data-loaded', {
+        detail: data,
+        bubbles: true
+      }));
     } catch (error: any) {
       if (error.name !== 'AbortError') {
-        this.renderError(error.message);
+        this.element?.dispatchEvent(new CustomEvent('data-error', {
+          detail: { message: error.message },
+          bubbles: true
+        }));
       }
-    } finally {
-      this.setLoadingState(false);
     }
   }
-
-  private setLoadingState(loading: boolean) {
-    if (!this.element) return;
-
-    if (loading) {
-      this.element.classList.add('loading');
-      this.element.setAttribute('aria-busy', 'true');
-    } else {
-      this.element.classList.remove('loading');
-      this.element.setAttribute('aria-busy', 'false');
-    }
-  }
-
-  private renderData(data: any) {
-    if (!this.element) return;
-
-    // Type guard for custom element
-    if ('setData' in this.element && typeof this.element.setData === 'function') {
-      this.element.setData(data);
-    } else {
-      // Fallback for native elements
-      this.element.innerHTML = JSON.stringify(data, null, 2);
-    }
-  }
-
-  private renderError(message: string) {
-    if (!this.element) return;
-
-    const errorDiv = document.createElement('div');
-    errorDiv.className = 'error';
-    errorDiv.textContent = `Error: ${message}`;
-
-    this.element.innerHTML = '';
-    this.element.appendChild(errorDiv);
-  }
 }
 ```
 
-### State Management Controller
+### Theme Controller
 
 ```typescript
-interface AppState {
-  user: { id: string; name: string } | null;
-  theme: 'light' | 'dark';
-  notifications: Notification[];
-}
-
-interface Notification {
-  id: string;
-  message: string;
-  type: 'info' | 'warning' | 'error';
-}
-
-@controller('state-controller')
-class StateController implements IController {
+@controller('theme-controller')
+class ThemeController implements IController {
   element: HTMLElement | null = null;
-  private state: AppState = {
-    user: null,
-    theme: 'light',
-    notifications: []
-  };
-
-  private stateListeners = new Set<(state: AppState) => void>();
 
   async attach(element: HTMLElement) {
-    // Load initial state
-    await this.loadState();
-
-    // Subscribe element to state changes
-    const updateElement = (state: AppState) => {
-      this.updateElementWithState(element, state);
-    };
-
-    this.stateListeners.add(updateElement);
-
-    // Initial render
-    updateElement(this.state);
+    const saved = localStorage.getItem('theme') || 'light';
+    element.setAttribute('data-theme', saved);
   }
 
-  async detach(element: HTMLElement) {
-    // Clean up listeners
-    this.stateListeners.clear();
-
-    // Save state
-    await this.saveState();
-  }
-
-  // Public methods for state management
-  setUser(user: AppState['user']) {
-    this.updateState({ ...this.state, user });
-  }
-
-  setTheme(theme: AppState['theme']) {
-    this.updateState({ ...this.state, theme });
-  }
-
-  addNotification(notification: Omit<Notification, 'id'>) {
-    const newNotification: Notification = {
-      ...notification,
-      id: Date.now().toString()
-    };
-
-    this.updateState({
-      ...this.state,
-      notifications: [...this.state.notifications, newNotification]
-    });
-
-    // Auto-remove after 5 seconds
-    setTimeout(() => {
-      this.removeNotification(newNotification.id);
-    }, 5000);
-  }
-
-  removeNotification(id: string) {
-    this.updateState({
-      ...this.state,
-      notifications: this.state.notifications.filter(n => n.id !== id)
-    });
-  }
-
-  private updateState(newState: AppState) {
-    this.state = newState;
-
-    // Notify all listeners
-    this.stateListeners.forEach(listener => listener(this.state));
+  async detach(element: HTMLElement) {}
 
-    // Persist state
-    this.saveState();
-  }
-
-  private updateElementWithState(element: HTMLElement, state: AppState) {
-    // Update element based on state
-    element.setAttribute('data-theme', state.theme);
-
-    // If element has state methods, call them
-    if ('setState' in element && typeof element.setState === 'function') {
-      (element as any).setState(state);
-    }
-
-    // Dispatch state change event
-    element.dispatchEvent(new CustomEvent('state-changed', {
-      detail: state,
-      bubbles: true
-    }));
-  }
-
-  private async loadState() {
-    try {
-      const saved = localStorage.getItem('app-state');
-      if (saved) {
-        this.state = JSON.parse(saved);
-      }
-    } catch (error) {
-      console.error('Failed to load state:', error);
-    }
-  }
-
-  private async saveState() {
-    try {
-      localStorage.setItem('app-state', JSON.stringify(this.state));
-    } catch (error) {
-      console.error('Failed to save state:', error);
-    }
+  @on('click', '[data-set-theme]')
+  handleThemeToggle(event: MouseEvent) {
+    const target = event.target as HTMLElement;
+    const theme = target.dataset.setTheme!;
+    this.element?.setAttribute('data-theme', theme);
+    localStorage.setItem('theme', theme);
   }
 }
 ```
@@ -579,166 +383,69 @@ class StateController implements IController {
 ### WebSocket Controller
 
 ```typescript
-@controller('websocket-controller')
+@controller('ws-controller')
 class WebSocketController implements IController {
   element: HTMLElement | null = null;
   private ws?: WebSocket;
   private reconnectTimer?: number;
-  private reconnectAttempts = 0;
-  private maxReconnectAttempts = 5;
-  private reconnectDelay = 1000; // Start with 1 second
 
   async attach(element: HTMLElement) {
     this.connect();
   }
 
   async detach(element: HTMLElement) {
-    this.disconnect();
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.ws?.close();
   }
 
   private connect() {
-    try {
-      this.ws = new WebSocket('ws://localhost:8080');
-
-      this.ws.onopen = () => {
-        console.log('WebSocket connected');
-        this.reconnectAttempts = 0;
-        this.reconnectDelay = 1000;
-        this.onConnected();
-      };
-
-      this.ws.onmessage = (event) => {
-        this.handleMessage(event.data);
-      };
-
-      this.ws.onerror = (error) => {
-        console.error('WebSocket error:', error);
-        this.onError(error);
-      };
-
-      this.ws.onclose = () => {
-        console.log('WebSocket disconnected');
-        this.onDisconnected();
-        this.scheduleReconnect();
-      };
-
-    } catch (error) {
-      console.error('Failed to create WebSocket:', error);
-      this.scheduleReconnect();
-    }
-  }
-
-  private disconnect() {
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = undefined;
-    }
-
-    if (this.ws) {
-      this.ws.close();
-      this.ws = undefined;
-    }
-  }
-
-  private scheduleReconnect() {
-    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
-      console.error('Max reconnection attempts reached');
-      this.onReconnectFailed();
-      return;
-    }
-
-    this.reconnectAttempts++;
-
-    console.log(`Reconnecting in ${this.reconnectDelay}ms (attempt ${this.reconnectAttempts})`);
-
-    this.reconnectTimer = setTimeout(() => {
-      this.connect();
-    }, this.reconnectDelay);
-
-    // Exponential backoff
-    this.reconnectDelay = Math.min(this.reconnectDelay * 2, 30000);
-  }
-
-  private handleMessage(data: string) {
-    try {
-      const message = JSON.parse(data);
-
-      // Update element with message
-      if (this.element && 'onMessage' in this.element) {
-        (this.element as any).onMessage(message);
-      }
+    this.ws = new WebSocket('wss://api.example.com/ws');
 
-      // Dispatch event
+    this.ws.onmessage = (event) => {
       this.element?.dispatchEvent(new CustomEvent('ws-message', {
-        detail: message,
+        detail: JSON.parse(event.data),
         bubbles: true
       }));
+    };
 
-    } catch (error) {
-      console.error('Failed to parse message:', error);
-    }
+    this.ws.onclose = () => {
+      this.reconnectTimer = setTimeout(() => this.connect(), 3000);
+    };
   }
 
   send(data: any) {
     if (this.ws?.readyState === WebSocket.OPEN) {
       this.ws.send(JSON.stringify(data));
-    } else {
-      console.warn('WebSocket not connected, queuing message');
-      // Could implement message queue here
     }
   }
+}
+```
 
-  private onConnected() {
-    this.element?.classList.remove('disconnected');
-    this.element?.classList.add('connected');
-  }
-
-  private onDisconnected() {
-    this.element?.classList.remove('connected');
-    this.element?.classList.add('disconnected');
-  }
+## Accessing Controllers
 
-  private onError(error: Event) {
-    this.element?.classList.add('error');
-  }
+### Via Event
 
-  private onReconnectFailed() {
-    this.element?.classList.add('reconnect-failed');
+Listen for attachment on the element itself (the event does **not** bubble):
 
-    // Show user notification
-    if (this.element) {
-      const notification = document.createElement('div');
-      notification.className = 'connection-error';
-      notification.textContent = 'Connection lost. Please refresh the page.';
-      this.element.appendChild(notification);
-    }
-  }
-}
+```typescript
+element.addEventListener('@snice/controller-attached', (e: CustomEvent) => {
+  console.log('Name:', e.detail.name);           // controller name string
+  console.log('Instance:', e.detail.controller);  // IController instance
+});
 ```
 
-## Controller Registry
-
-Controllers are automatically registered when decorated with `@controller`:
+### Via getController()
 
 ```typescript
 import { getController } from 'snice';
 
-// Get controller instance from an element
-const element = document.querySelector('#my-element');
-const controller = getController(element);
-
-if (controller) {
-  console.log('Controller found:', controller);
+const ctrl = getController<MyController>(element);
+if (ctrl) {
+  ctrl.doSomething();
 }
 ```
 
-## Best Practices
+### Auto-Cleanup
+
+The framework automatically cleans up `@on` handlers, observers, and `@respond` handlers during detach. Manual cleanup in `detach()` is only needed for resources you manage yourself (WebSockets, intervals, manual event listeners).
 
-1. **Separation of Concerns**: Keep controllers focused on data and business logic
-2. **Cleanup Resources**: Always clean up timers, listeners, and connections
-3. **Error Handling**: Handle errors gracefully in async operations
-4. **Type Safety**: Use TypeScript generics for element types
-5. **State Management**: Consider using a state controller for complex state
-6. **Abort Requests**: Cancel pending requests when detaching
-7. **Memory Management**: Clear references to prevent memory leaks
-8. **Event Delegation**: Use event delegation for dynamic content