snice 1.9.0 → 1.10.1

package/README.md

@@ -44,7 +44,7 @@ Snice provides a clear separation of concerns through decorators:
 - **`@on`** - Listens for events on elements
 - **`@dispatch`** - Dispatches custom events after method execution
 - **`@request`** - Makes requests from elements or controllers
-- **`@response`** - Responds to requests in elements or controllers
+- **`@respond`** - Responds to requests in elements or controllers
 
 This separation keeps your components focused: elements handle presentation, controllers manage data, and pages define navigation.
 
@@ -158,6 +158,25 @@ Use it with attributes:
 <user-card name="Jane Doe" user-role="Admin" verified></user-card>
 ```
 
+For arrays of basic types, use `SimpleArray` for safe reflection:
+
+```typescript
+import { element, property, SimpleArray } from 'snice';
+
+@element('tag-list')
+class TagList extends HTMLElement {
+  @property({ type: SimpleArray, reflect: true })
+  tags = ['javascript', 'typescript', 'web'];
+  
+  html() {
+    return `<div>${this.tags.join(', ')}</div>`;
+  }
+}
+```
+
+```html
+<tag-list tags="react，vue，angular"></tag-list>
+```
 
 ## Watching Property Changes
 
@@ -303,6 +322,11 @@ class MyClicker extends HTMLElement {
   handleCtrlEnter() {
     console.log('Ctrl + Enter pressed!');
   }
+  
+  @on('focus')  // Listen on the host element itself (no target)
+  handleFocus() {
+    console.log('Element received focus!');
+  }
 }
 ```
 
@@ -566,12 +590,14 @@ Use it:
 Bidirectional communication between elements and controllers:
 
 ```typescript
+import { element, request, type Response } from 'snice';
+
 // Element makes request, controller responds
-@element('user-profile')
+@element('user-profile')  
 class UserProfile extends HTMLElement {
 
   @request('fetch-user')
-  async *getUser() {
+  async *getUser(): Response<{ name: string; email: string }> {
     const user = await (yield { userId: 123 });
     return user;
   }
@@ -587,7 +613,7 @@ class UserProfile extends HTMLElement {
 @controller('user-controller')
 class UserController {
 
-  @response('fetch-user')
+  @respond('fetch-user')
   async handleFetchUser(request: { userId: number }) {
     const response = await fetch(`/api/users/${request.userId}`);
     return response.json();
@@ -657,7 +683,7 @@ class ProfilePage extends HTMLElement {
 
 ### Context in Nested Elements
 
-Nested elements within pages can also access context through event bubbling:
+Nested elements within pages can also access context:
 
 ```typescript
 // This element can be used inside any page
@@ -765,6 +791,119 @@ class LazyImage extends HTMLElement {
 
 All observers are automatically cleaned up when elements disconnect from the DOM. See the [Observe API documentation](./docs/observe.md) for more examples.
 
+## Parts - Selective Re-rendering
+
+For complex components with frequent updates to specific sections, the `@part` decorator enables selective re-rendering of template parts without rebuilding the entire component:
+
+```typescript
+import { element, part, property, on } from 'snice';
+
+@element('user-dashboard')
+class UserDashboard extends HTMLElement {
+  @property()
+  user = { name: 'Loading...', stats: { views: 0, likes: 0 } };
+  
+  notifications = [];
+  messages = [];
+
+  html() {
+    return `
+      <header part="user-info"></header>
+      <main>
+        <section part="stats"></section>
+        <aside part="notifications"></aside>
+        <div part="messages"></div>
+      </main>
+    `;
+  }
+
+  @part('user-info')
+  renderUserInfo() {
+    return `
+      <h1>${this.user.name}</h1>
+      <button id="refresh-user">Refresh</button>
+    `;
+  }
+
+  @part('stats')
+  renderStats() {
+    return `
+      <div class="stats">
+        <span>Views: ${this.user.stats.views}</span>
+        <span>Likes: ${this.user.stats.likes}</span>
+      </div>
+    `;
+  }
+
+  @part('notifications', { throttle: 300 })
+  renderNotifications() {
+    return `
+      <h3>Notifications (${this.notifications.length})</h3>
+      ${this.notifications.map(n => `<div>${n}</div>`).join('')}
+    `;
+  }
+
+  @part('messages')
+  async renderMessages() {
+    if (this.messages.length === 0) {
+      return '<p>No messages</p>';
+    }
+    return this.messages.map(m => `<div class="message">${m}</div>`).join('');
+  }
+
+  // Update specific parts without re-rendering everything
+  updateUserName(newName) {
+    this.user.name = newName;
+    this.renderUserInfo(); // Only re-renders the header
+  }
+
+  incrementViews() {
+    this.user.stats.views++;
+    this.renderStats(); // Only re-renders the stats section
+  }
+
+  addNotification(notification) {
+    this.notifications.unshift(notification);
+    this.renderNotifications(); // Only re-renders notifications
+  }
+
+  @on('click', '#refresh-user')
+  async handleRefreshUser() {
+    // Simulate API call
+    const userData = await this.fetchUserData();
+    this.user = userData;
+    this.renderUserInfo(); // Update just the user info part
+    this.renderStats();    // Update just the stats part
+  }
+}
+```
+
+**Benefits of `@part`:**
+- **Performance** - Update only what changed instead of re-rendering entire templates
+- **Granular Control** - Target specific sections for updates
+- **Complex UIs** - Perfect for dashboards, lists, or components with independent sections
+- **Async Support** - Part methods can be async for data fetching
+- **Throttle/Debounce** - Control render frequency to optimize performance
+
+### Performance Options
+
+The `@part` decorator supports throttle and debounce options to optimize render performance:
+
+```typescript
+// Throttle: Limit renders to once per 300ms
+@part('notifications', { throttle: 300 })
+renderNotifications() { /* ... */ }
+
+// Debounce: Delay render until 150ms after last call
+@part('search-results', { debounce: 150 })
+renderSearchResults() { /* ... */ }
+```
+
+- **Throttle** - Limits renders to a maximum frequency (e.g., once every 300ms)
+- **Debounce** - Delays renders until after calls stop for the specified time
+
+The `@part` decorator is ideal when you have components with multiple independent sections that update at different frequencies or from different data sources.
+
 ## Documentation
 
 - [Elements API](./docs/elements.md) - Complete guide to creating elements with properties, queries, and styling

package/bin/templates/base/src/components/counter-button.ts

@@ -1,5 +1,5 @@
 import { element, property, query, on, dispatch } from 'snice';
-import type { ICounterButton } from '../types/counter-button';
+import type { ICounterButton } from './counter-button.types';
 
 @element('counter-button')
 export class CounterButton extends HTMLElement implements ICounterButton {

package/bin/templates/base/src/controllers/counter-controller.ts

@@ -1,5 +1,5 @@
 import { controller, on } from 'snice';
-import type { ICounterButton } from '../types/counter-button';
+import type { ICounterButton } from '../components/counter-button.types';
 
 @controller('counter')
 export class CounterController {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "snice",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "type": "module",
-  "description": "A TypeScript library",
+  "description": "Imperative TypeScript framework for building vanilla web components with decorators, routing, and controllers. No virtual DOM, no build complexity.",
   "main": "src/index.ts",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -16,6 +16,40 @@
     "!src/**/*.test.ts",
     "!src/**/*.spec.ts"
   ],
+  "keywords": [
+    "web components",
+    "typescript",
+    "framework",
+    "decorators",
+    "custom elements",
+    "vanilla js",
+    "frontend",
+    "spa",
+    "routing",
+    "imperative",
+    "no virtual dom",
+    "lightweight",
+    "minimal",
+    "controllers",
+    "mvc",
+    "shadow dom",
+    "lit alternative",
+    "stencil alternative",
+    "web standards"
+  ],
+  "author": "hedzer",
+  "license": "MIT",
+  "homepage": "https://gitlab.com/Hedzer/snice#readme",
+  "repository": {
+    "type": "git",
+    "url": "git@gitlab.com:Hedzer/snice.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/Hedzer/snice/-/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/controller.ts

@@ -141,7 +141,7 @@ export async function attachController(element: HTMLElement, controllerName: str
   // Setup @channel handlers for controller
   setupResponseHandlers(controllerInstance, element);
   
-  element.dispatchEvent(new CustomEvent('controller.attached', {
+  element.dispatchEvent(new CustomEvent('@snice/controller-attached', {
     detail: { name: controllerName, controller: controllerInstance }
   }));
 }
@@ -191,7 +191,7 @@ export async function detachController(element: HTMLElement): Promise<void> {
   delete (element as any)[CONTROLLER_NAME_KEY];
   delete (element as any)[CONTROLLER_OPERATIONS];
   
-  element.dispatchEvent(new CustomEvent('controller.detached', {
+  element.dispatchEvent(new CustomEvent('@snice/controller-detached', {
     detail: { name: controllerName, controller: controllerInstance }
   }));
 }

package/src/element.ts

@@ -2,7 +2,7 @@ import { attachController, detachController } from './controller';
 import { setupEventHandlers, cleanupEventHandlers } from './events';
 import { setupObservers, cleanupObservers } from './observe';
 import { setupResponseHandlers, cleanupResponseHandlers } from './request-response';
-import { IS_ELEMENT_CLASS, IS_CONTROLLER_INSTANCE, READY_PROMISE, READY_RESOLVE, CONTROLLER, PROPERTIES, PROPERTY_VALUES, PROPERTIES_INITIALIZED, PROPERTY_WATCHERS, EXPLICITLY_SET_PROPERTIES, ROUTER_CONTEXT, READY_HANDLERS, DISPOSE_HANDLERS } from './symbols';
+import { IS_ELEMENT_CLASS, IS_CONTROLLER_INSTANCE, READY_PROMISE, READY_RESOLVE, CONTROLLER, PROPERTIES, PROPERTY_VALUES, PROPERTIES_INITIALIZED, PROPERTY_WATCHERS, EXPLICITLY_SET_PROPERTIES, ROUTER_CONTEXT, READY_HANDLERS, DISPOSE_HANDLERS, PARTS, PART_TIMERS } from './symbols';
 
 /**
  * Applies core element functionality to a constructor
@@ -27,7 +27,7 @@ export function applyElementFunctionality(constructor: any) {
     const properties = constructor[PROPERTIES];
     if (properties) {
       for (const [propName, propOptions] of properties) {
-        const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName;
+        const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName.toLowerCase();
         if (!observedAttributes.includes(attributeName)) {
           observedAttributes.push(attributeName);
         }
@@ -78,6 +78,7 @@ export function applyElementFunctionality(constructor: any) {
       configurable: true
     });
     
+    
     constructor.prototype.connectedCallback = async function() {
       // If ready promise was already created (controller attached before connected), use existing resolve
       // Otherwise create the ready promise now
@@ -113,6 +114,19 @@ export function applyElementFunctionality(constructor: any) {
                 case String:
                   this[propName] = attrValue;
                   break;
+                case Date:
+                  this[propName] = attrValue ? new Date(attrValue) : null;
+                  break;
+                case BigInt:
+                  if (attrValue && attrValue.endsWith('n')) {
+                    this[propName] = BigInt(attrValue.slice(0, -1));
+                  } else {
+                    this[propName] = attrValue ? BigInt(attrValue) : null;
+                  }
+                  break;
+                case SimpleArray:
+                  this[propName] = SimpleArray.parse(attrValue);
+                  break;
                 default:
                   this[propName] = attrValue;
               }
@@ -129,10 +143,22 @@ export function applyElementFunctionality(constructor: any) {
           for (const [propName, propOptions] of properties) {
             if (propOptions.reflect && this[EXPLICITLY_SET_PROPERTIES].has(propName) && propName in this[PROPERTY_VALUES]) {
               const value = this[PROPERTY_VALUES][propName];
-              const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName;
+              const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName.toLowerCase();
               
-              if (value !== null && value !== undefined && value !== false) {
-                this.setAttribute(attributeName, String(value));
+              if (value !== null && value !== undefined && value !== false && 
+                  !(propOptions.type === SimpleArray && Array.isArray(value) && value.length === 0)) {
+                // Handle special types for reflection
+                let attributeValue: string;
+                if (value instanceof Date) {
+                  attributeValue = value.toISOString();
+                } else if (typeof value === 'bigint') {
+                  attributeValue = value.toString() + 'n';
+                } else if (propOptions.type === SimpleArray && Array.isArray(value)) {
+                  attributeValue = SimpleArray.serialize(value);
+                } else {
+                  attributeValue = String(value);
+                }
+                this.setAttribute(attributeName, attributeValue);
               }
             }
           }
@@ -185,6 +211,25 @@ export function applyElementFunctionality(constructor: any) {
           this.shadowRoot.innerHTML = shadowContent;
         }
         
+        // Render all @part methods into their corresponding elements
+        const parts = constructor[PARTS];
+        if (parts && this.shadowRoot) {
+          for (const [partName, partHandler] of parts) {
+            try {
+              const partElement = this.shadowRoot.querySelector(`[part="${partName}"]`);
+              if (partElement) {
+                const partResult = partHandler.method.call(this);
+                const partContent = partResult instanceof Promise ? await partResult : partResult;
+                if (partContent !== undefined) {
+                  partElement.innerHTML = partContent;
+                }
+              }
+            } catch (error) {
+              console.error(`Error rendering @part('${partName}') in ${this.tagName}:`, error);
+            }
+          }
+        }
+        
         // NOW call the original user-defined connectedCallback after shadow DOM is set up
         if (originalConnectedCallback) {
           originalConnectedCallback.call(this);
@@ -197,7 +242,7 @@ export function applyElementFunctionality(constructor: any) {
         // Setup @on event handlers - use element for host events, shadow root for delegated events
         setupEventHandlers(this, this);
         
-        // Setup @response handlers for elements
+        // Setup @respond handlers for elements
         setupResponseHandlers(this, this);
         
         // Setup @observe observers
@@ -251,7 +296,7 @@ export function applyElementFunctionality(constructor: any) {
       }
       // Cleanup @on event handlers
       cleanupEventHandlers(this);
-      // Cleanup @response handlers
+      // Cleanup @respond handlers
       cleanupResponseHandlers(this);
       // Cleanup @observe observers
       cleanupObservers(this);
@@ -266,7 +311,7 @@ export function applyElementFunctionality(constructor: any) {
         const properties = constructor[PROPERTIES];
         if (properties) {
           for (const [propName, propOptions] of properties) {
-            const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName;
+            const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName.toLowerCase();
             if (attributeName === name) {
               // Check if the current property value already matches to avoid feedback loops
               const currentValue = this[PROPERTY_VALUES]?.[propName];
@@ -277,6 +322,16 @@ export function applyElementFunctionality(constructor: any) {
                 parsedValue = newValue !== null && newValue !== 'false';
               } else if (propOptions.type === Number) {
                 parsedValue = Number(newValue);
+              } else if (propOptions.type === Date) {
+                parsedValue = newValue ? new Date(newValue) : null;
+              } else if (propOptions.type === BigInt) {
+                if (newValue && newValue.endsWith('n')) {
+                  parsedValue = BigInt(newValue.slice(0, -1));
+                } else {
+                  parsedValue = newValue ? BigInt(newValue) : null;
+                }
+              } else if (propOptions.type === SimpleArray) {
+                parsedValue = SimpleArray.parse(newValue);
               } else {
                 // If no type specified, try to infer from current value type
                 if (typeof currentValue === 'number' && newValue !== null) {
@@ -286,7 +341,7 @@ export function applyElementFunctionality(constructor: any) {
                 }
               }
               
-              // Only update if the value actually changed
+              // Only update if the value actually changed and avoid infinite loops
               if (currentValue !== parsedValue) {
                 // Mark as explicitly set since it came from an attribute change
                 if (!this[EXPLICITLY_SET_PROPERTIES]) {
@@ -294,7 +349,39 @@ export function applyElementFunctionality(constructor: any) {
                 }
                 this[EXPLICITLY_SET_PROPERTIES].add(propName);
                 
-                this[propName] = parsedValue;
+                // Set the property value directly in the storage to avoid triggering setter
+                if (!this[PROPERTY_VALUES]) {
+                  this[PROPERTY_VALUES] = {};
+                }
+                this[PROPERTY_VALUES][propName] = parsedValue;
+                
+                // Call watchers manually since we bypassed the setter
+                const watchers = constructor[PROPERTY_WATCHERS];
+                if (watchers) {
+                  // Call specific property watchers
+                  if (watchers.has(propName)) {
+                    const propertyWatchers = watchers.get(propName);
+                    for (const watcher of propertyWatchers) {
+                      try {
+                        watcher.method.call(this, currentValue, parsedValue, propName);
+                      } catch (error) {
+                        console.error(`Error in @watch('${propName}') method ${watcher.methodName}:`, error);
+                      }
+                    }
+                  }
+                  
+                  // Call wildcard watchers (watching "*")
+                  if (watchers.has('*')) {
+                    const wildcardWatchers = watchers.get('*');
+                    for (const watcher of wildcardWatchers) {
+                      try {
+                        watcher.method.call(this, currentValue, parsedValue, propName);
+                      } catch (error) {
+                        console.error(`Error in @watch('*') method ${watcher.methodName}:`, error);
+                      }
+                    }
+                  }
+                }
               }
               break;
             }
@@ -311,13 +398,19 @@ export function element(tagName: string) {
   };
 }
 
-// Alias for backwards compatibility
-export const customElement = element;
-
 export function property(options?: PropertyOptions) {
   return function (target: any, propertyKey: string) {
     const constructor = target.constructor;
     
+    // Warn about problematic reflection usage
+    if (options?.reflect && options?.type === Array) {
+      console.warn(`⚠️  Property '${propertyKey}' uses reflect:true with Array type.`);
+    }
+    
+    if (options?.reflect && options?.type === Object) {
+      console.warn(`⚠️  Property '${propertyKey}' uses reflect:true with Object type.`);
+    }
+    
     if (!constructor[PROPERTIES]) {
       constructor[PROPERTIES] = new Map();
     }
@@ -344,9 +437,12 @@ export function property(options?: PropertyOptions) {
         // Don't update if value hasn't changed
         if (oldValue === value) return;
         
-        // Only mark as explicitly set if there was a previous value
-        // (i.e., this is not the initial default value being set during class initialization)
-        if (oldValue !== undefined) {
+        // Mark as explicitly set in these cases:
+        // 1. There was a previous value (normal property update)
+        // 2. This is during element construction and we have a non-null/non-undefined value
+        //    (this handles default values declared in class properties)
+        const isInitialDefaultValue = oldValue === undefined && !this[PROPERTIES_INITIALIZED];
+        if (oldValue !== undefined || (isInitialDefaultValue && value !== null && value !== undefined)) {
           this[EXPLICITLY_SET_PROPERTIES].add(propertyKey);
         }
         
@@ -357,12 +453,24 @@ export function property(options?: PropertyOptions) {
         // 2. The property was explicitly set (not just default value)
         // This prevents default values from creating attributes
         if (options?.reflect && this.setAttribute && this[PROPERTIES_INITIALIZED] && this[EXPLICITLY_SET_PROPERTIES].has(propertyKey)) {
-          const attributeName = typeof options.attribute === 'string' ? options.attribute : propertyKey;
+          const attributeName = typeof options.attribute === 'string' ? options.attribute : propertyKey.toLowerCase();
           
-          if (value === null || value === undefined || value === false) {
+          if (value === null || value === undefined || value === false || 
+              (options?.type === SimpleArray && Array.isArray(value) && value.length === 0)) {
             this.removeAttribute(attributeName);
           } else {
-            this.setAttribute(attributeName, String(value));
+            // Handle special types for reflection
+            let attributeValue: string;
+            if (value instanceof Date) {
+              attributeValue = value.toISOString();
+            } else if (typeof value === 'bigint') {
+              attributeValue = value.toString() + 'n';
+            } else if (options?.type === SimpleArray && Array.isArray(value)) {
+              attributeValue = SimpleArray.serialize(value);
+            } else {
+              attributeValue = String(value);
+            }
+            this.setAttribute(attributeName, attributeValue);
           }
         }
         
@@ -477,8 +585,64 @@ export function queryAll(selector: string, options: QueryOptions = {}) {
   };
 }
 
+/**
+ * SimpleArray type for arrays that can be safely reflected to attributes
+ * Supports arrays of: string, number, boolean
+ * Uses full-width comma (，) as separator to avoid conflicts
+ * Strings cannot contain the full-width comma character
+ */
+export class SimpleArray {
+  static readonly SEPARATOR = '，'; // U+FF0C Full-width comma
+  
+  /**
+   * Serialize array to string for attribute storage
+   */
+  static serialize(arr: (string | number | boolean)[]): string {
+    if (!Array.isArray(arr)) return '';
+    
+    return arr.map(item => {
+      if (typeof item === 'string') {
+        // Validate string doesn't contain our separator
+        if (item.includes(SimpleArray.SEPARATOR)) {
+          throw new Error(`SimpleArray strings cannot contain the character "${SimpleArray.SEPARATOR}" (U+FF0C)`);
+        }
+        return item;
+      } else if (typeof item === 'number' || typeof item === 'boolean') {
+        return String(item);
+      } else {
+        throw new Error(`SimpleArray only supports string, number, and boolean types. Got: ${typeof item}`);
+      }
+    }).join(SimpleArray.SEPARATOR);
+  }
+  
+  /**
+   * Parse string from attribute back to array
+   */
+  static parse(str: string | null): (string | number | boolean)[] {
+    if (str === null || str === undefined) return [];
+    // Empty string should not be parsed as containing an empty string
+    // since empty arrays don't get reflected (handled by the reflection logic)
+    if (str === '') return [];
+    
+    return str.split(SimpleArray.SEPARATOR).map(item => {
+      // Try to parse as number
+      if (/^-?\d+\.?\d*$/.test(item)) {
+        const num = Number(item);
+        if (!isNaN(num)) return num;
+      }
+      
+      // Parse as boolean
+      if (item === 'true') return true;
+      if (item === 'false') return false;
+      
+      // Default to string
+      return item;
+    });
+  }
+}
+
 export interface PropertyOptions {
-  type?: StringConstructor | NumberConstructor | BooleanConstructor | ArrayConstructor | ObjectConstructor;
+  type?: StringConstructor | NumberConstructor | BooleanConstructor | ArrayConstructor | ObjectConstructor | DateConstructor | BigIntConstructor | typeof SimpleArray;
   reflect?: boolean;
   attribute?: string | boolean;
   converter?: PropertyConverter;
@@ -490,6 +654,20 @@ export interface PropertyConverter {
   toAttribute?(value: any, type?: any): string | null;
 }
 
+/**
+ * Interface for Snice elements with all the framework-provided properties and methods
+ */
+export interface SniceElement extends HTMLElement {
+  ready: Promise<void>;
+  html?(): string | Promise<string>;
+  css?(): string | string[] | Promise<string | string[]>;
+}
+
+export interface PartOptions {
+  throttle?: number; // Throttle in milliseconds - limits calls to once per interval
+  debounce?: number; // Debounce in milliseconds - delays execution until after calls stop
+}
+
 export function watch(...propertyNames: string[]) {
   return function (target: any, methodName: string, descriptor: PropertyDescriptor) {
     const constructor = target.constructor;
@@ -608,6 +786,105 @@ export function dispose() {
       method: descriptor.value
     });
     
+    return descriptor;
+  };
+}
+
+/**
+ * Decorator for methods that render specific parts of the template
+ * Parts are identified by the 'part' attribute in the HTML template
+ * When the decorated method is called, it automatically re-renders its part
+ */
+export function part(partName: string, options: PartOptions = {}) {
+  return function (target: any, methodName: string, descriptor: PropertyDescriptor) {
+    const constructor = target.constructor;
+    const originalMethod = descriptor.value;
+    
+    if (!constructor[PARTS]) {
+      constructor[PARTS] = new Map();
+    }
+    
+    constructor[PARTS].set(partName, {
+      methodName,
+      method: originalMethod
+    });
+    
+    // Wrap the original method to automatically re-render the part when called
+    descriptor.value = async function (this: HTMLElement, ...args: any[]) {
+      // Initialize timers storage if not present
+      if (!(this as any)[PART_TIMERS]) {
+        (this as any)[PART_TIMERS] = new Map();
+      }
+      
+      // Get or create timers for this specific part
+      if (!(this as any)[PART_TIMERS].has(partName)) {
+        (this as any)[PART_TIMERS].set(partName, {
+          throttleTimer: null,
+          debounceTimer: null,
+          lastThrottleCall: 0
+        });
+      }
+      
+      const timers = (this as any)[PART_TIMERS].get(partName);
+      
+      // Create the render function
+      const renderPart = async () => {
+        // Call the original method to get the content
+        const result = originalMethod.apply(this, args);
+        const content = result instanceof Promise ? await result : result;
+        
+        // Re-render the part if shadow DOM exists and content is defined
+        if (this.shadowRoot && content !== undefined) {
+          const partElement = this.shadowRoot.querySelector(`[part="${partName}"]`);
+          if (partElement) {
+            partElement.innerHTML = content;
+          }
+        }
+        
+        return content;
+      };
+      
+      // Handle debounce (only if positive value)
+      if (options.debounce !== undefined && options.debounce > 0) {
+        if (timers.debounceTimer) {
+          clearTimeout(timers.debounceTimer);
+        }
+        
+        return new Promise((resolve) => {
+          timers.debounceTimer = setTimeout(async () => {
+            const result = await renderPart();
+            resolve(result);
+          }, options.debounce);
+        });
+      }
+      
+      // Handle throttle (only if positive value)
+      if (options.throttle !== undefined && options.throttle > 0) {
+        const now = Date.now();
+        
+        if (timers.lastThrottleCall === 0 || now - timers.lastThrottleCall >= options.throttle) {
+          timers.lastThrottleCall = now;
+          return await renderPart();
+        } else {
+          // If throttled, schedule the next call if not already scheduled
+          if (!timers.throttleTimer) {
+            const remainingTime = options.throttle - (now - timers.lastThrottleCall);
+            timers.throttleTimer = setTimeout(async () => {
+              timers.throttleTimer = null;
+              timers.lastThrottleCall = Date.now();
+              await renderPart();
+            }, remainingTime);
+          }
+          // For throttled calls, don't execute the original method, just return undefined
+          // The actual render will happen in the scheduled timeout
+          return undefined;
+        }
+      }
+      
+      // No throttle/debounce - render immediately
+      return await renderPart();
+    };
+    
     return descriptor;
   };
 }

package/src/index.ts

@@ -1,14 +1,14 @@
-export { element, customElement, property, query, queryAll, watch, context, applyElementFunctionality, ready, dispose } from './element';
+export { element, property, query, queryAll, watch, context, applyElementFunctionality, ready, dispose, part, SimpleArray } from './element';
 export { Router } from './router';
 export { controller, attachController, detachController, getController, useNativeElementControllers, cleanupNativeElementControllers } from './controller';
 export { on, dispatch } from './events';
 export { observe } from './observe';
-export { request, response } from './request-response';
+export { request, respond } from './request-response';
 export { IS_CONTROLLER_INSTANCE } from './symbols';
 export type { Transition } from './transitions';
-export type { PropertyOptions, PropertyConverter, QueryOptions } from './element';
+export type { PropertyOptions, PropertyConverter, QueryOptions, SniceElement, PartOptions } from './element';
 export type { RouterOptions, PageOptions, Guard, RouteParams, RouterInstance } from './router';
 export type { IController, ControllerClass } from './controller';
 export type { DispatchOptions } from './events';
 export type { ObserveOptions } from './observe';
-export type { RequestOptions } from './request-response';
+export type { RequestOptions, Response } from './request-response';

package/src/request-response.ts

@@ -1,10 +1,29 @@
 import { CHANNEL_HANDLERS, CLEANUP, IS_CONTROLLER_INSTANCE } from './symbols';
 
+// Pragmatic type for @request decorated methods
+// - Eliminates TypeScript implicit 'any' warnings
+// - Allows property access on returned values (result.data works)
+// - Documents the expected return type T
+// - The @request decorator transforms async generators to return Promise<T> at runtime
+export type Response<T = any> = T | any;
+
 export interface RequestOptions extends EventInit {
   /**
-   * Timeout for waiting for responses (in ms)
+   * Timeout for waiting for responses (in ms) - defaults to 5000ms
    */
   timeout?: number;
+  /**
+   * Timeout for finding a handler (in ms) - defaults to 50ms
+   */
+  discoveryTimeout?: number;
+  /**
+   * Debounce the request by specified milliseconds
+   */
+  debounce?: number;
+  /**
+   * Throttle the request by specified milliseconds
+   */
+  throttle?: number;
 }
 
 /**
@@ -18,11 +37,18 @@ export function request(requestName: string, options?: RequestOptions) {
   return function (_target: any, _propertyKey: string, descriptor: PropertyDescriptor) {
     const originalMethod = descriptor.value;
     
+    // Create timing variables for debounce/throttle
+    let debounceTimeout: any;
+    let throttleLastCall = 0;
+    let throttleTimeout: any;
+    
     descriptor.value = async function (this: any, ...args: any[]) {
-      // @request always acts as requester (client side)
-      const timeout = options?.timeout ?? 100; // Default 100ms timeout
-      
-      // Create the generator
+      const actualRequest = async () => {
+        // @request always acts as requester (client side)
+        const responseTimeout = options?.timeout ?? 120000; // Default 2 minute timeout
+        const discoveryTimeout = options?.discoveryTimeout ?? 50; // Default 50ms discovery timeout
+        
+        // Create the generator
       const generator = originalMethod.apply(this, args);
       
       // Get the first yield (the request payload)
@@ -41,16 +67,16 @@ export function request(requestName: string, options?: RequestOptions) {
         dataReject = reject;
       });
       
-      // Create timeout promise and expose resolve/reject
-      let timeoutResolve: () => void;
-      let timeoutReject: (reason?: any) => void;
-      let timeoutId: NodeJS.Timeout;
-      const timeoutPromise = new Promise<void>((resolve, reject) => {
-        timeoutResolve = resolve;
-        timeoutReject = reject;
-        timeoutId = setTimeout(() => {
-          reject(new Error(`Request timeout after ${timeout}ms`));
-        }, timeout);
+      // Create discovery timeout promise and expose resolve/reject
+      let discoveryResolve: () => void;
+      let discoveryReject: (reason?: any) => void;
+      let discoveryTimeoutId: NodeJS.Timeout;
+      const discoveryPromise = new Promise<void>((resolve, reject) => {
+        discoveryResolve = resolve;
+        discoveryReject = reject;
+        discoveryTimeoutId = setTimeout(() => {
+          reject(new Error(`Request "${requestName}" timed out after ${discoveryTimeout}ms - no handler found`));
+        }, discoveryTimeout);
       });
       
       // Dispatch event with promises
@@ -61,12 +87,12 @@ export function request(requestName: string, options?: RequestOptions) {
         composed: true, // Allow crossing shadow DOM boundaries
         detail: {
           payload,
-          timeout: {
+          discovery: {
             resolve: () => {
-              clearTimeout(timeoutId);
-              timeoutResolve();
+              clearTimeout(discoveryTimeoutId);
+              discoveryResolve();
             },
-            reject: timeoutReject!
+            reject: discoveryReject!
           },
           data: {
             resolve: dataResolve!,
@@ -81,10 +107,17 @@ export function request(requestName: string, options?: RequestOptions) {
       dispatcher.dispatchEvent(event);
       
       try {
-        // Wait for timeout to be resolved or rejected
-        await timeoutPromise;
-        // If we get here, responder responded in time
+        // Wait for discovery timeout to be cleared (handler found) or discovery timeout to reject (no handler)
+        await discoveryPromise;
+        
+        // If we get here, a handler was found and discovery timeout was cleared
+        // Now wait for the actual data response with the full response timeout
+        const responseTimeoutId = setTimeout(() => {
+          dataReject!(new Error(`Request "${requestName}" timed out after ${responseTimeout}ms`));
+        }, responseTimeout);
+        
         const response = await dataPromise;
+        clearTimeout(responseTimeoutId);
         
         // Send response back to generator and get final return value
         const { value: finalValue } = await generator.next(response);
@@ -97,18 +130,76 @@ export function request(requestName: string, options?: RequestOptions) {
           throw generatorError;
         }
       }
+      }; // Close actualRequest function
+      
+      // Apply debounce or throttle if specified
+      if (options?.debounce) {
+        return new Promise((resolve, reject) => {
+          clearTimeout(debounceTimeout);
+          debounceTimeout = setTimeout(async () => {
+            try {
+              const result = await actualRequest();
+              resolve(result);
+            } catch (error) {
+              reject(error);
+            }
+          }, options.debounce);
+        });
+      }
+      
+      if (options?.throttle) {
+        const now = Date.now();
+        const remaining = options.throttle - (now - throttleLastCall);
+        
+        if (remaining <= 0) {
+          clearTimeout(throttleTimeout);
+          throttleLastCall = now;
+          return actualRequest();
+        } else if (!throttleTimeout) {
+          return new Promise((resolve, reject) => {
+            throttleTimeout = setTimeout(async () => {
+              throttleLastCall = Date.now();
+              throttleTimeout = null;
+              try {
+                const result = await actualRequest();
+                resolve(result);
+              } catch (error) {
+                reject(error);
+              }
+            }, remaining);
+          });
+        }
+        
+        // If throttled and timeout already exists, return empty promise
+        return Promise.resolve();
+      }
+      
+      // No timing applied, execute immediately
+      return actualRequest();
     };
     
     return descriptor;
   };
 }
 
+export interface RespondOptions {
+  /**
+   * Debounce the response by specified milliseconds
+   */
+  debounce?: number;
+  /**
+   * Throttle the response by specified milliseconds
+   */
+  throttle?: number;
+}
+
 /**
  * Decorator for responding to requests in elements or controllers.
  * 
  * @param requestName The name of the request to respond to
+ * @param options Optional configuration
  */
-export function response(requestName: string) {
+export function respond(requestName: string, options?: RespondOptions) {
   return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
     const originalMethod = descriptor.value;
     
@@ -121,7 +212,8 @@ export function response(requestName: string) {
     target[CHANNEL_HANDLERS].push({
       channelName: requestName,
       methodName: propertyKey,
-      method: originalMethod
+      method: originalMethod,
+      options: options
     });
     
     return descriptor;
@@ -143,26 +235,82 @@ export function setupResponseHandlers(instance: any, element: HTMLElement) {
     const boundMethod = handler.method.bind(instance);
     const eventName = `@request/${handler.channelName}`;
     
+    // Create timing variables for debounce/throttle per handler
+    let debounceTimeout: any;
+    let throttleLastCall = 0;
+    let throttleTimeout: any;
+    
+    // Create wrapped method with timing if needed
+    const createTimedMethod = (originalMethod: Function) => {
+      if (handler.options?.debounce) {
+        return (...args: any[]) => {
+          return new Promise((resolve, reject) => {
+            clearTimeout(debounceTimeout);
+            debounceTimeout = setTimeout(async () => {
+              try {
+                const result = await originalMethod(...args);
+                resolve(result);
+              } catch (error) {
+                reject(error);
+              }
+            }, handler.options.debounce);
+          });
+        };
+      }
+      
+      if (handler.options?.throttle) {
+        return (...args: any[]) => {
+          const now = Date.now();
+          const remaining = handler.options.throttle! - (now - throttleLastCall);
+          
+          if (remaining <= 0) {
+            clearTimeout(throttleTimeout);
+            throttleLastCall = now;
+            return originalMethod(...args);
+          } else if (!throttleTimeout) {
+            return new Promise((resolve, reject) => {
+              throttleTimeout = setTimeout(async () => {
+                throttleLastCall = Date.now();
+                throttleTimeout = null;
+                try {
+                  const result = await originalMethod(...args);
+                  resolve(result);
+                } catch (error) {
+                  reject(error);
+                }
+              }, remaining);
+            });
+          }
+          
+          // If throttled and timeout already exists, return cached/empty response
+          return Promise.resolve(undefined);
+        };
+      }
+      
+      return originalMethod;
+    };
+    
+    const timedMethod = createTimedMethod(boundMethod);
+    
     // Setup response handler
     const responseHandler = (event: CustomEvent) => {
       // Extract promises and payload
-      const { data, timeout, payload } = event.detail;
+      const { data, discovery, payload } = event.detail;
       
       // Prevent other responders from responding
       event.preventDefault();
       event.stopImmediatePropagation();
       event.stopPropagation();
       
-      // Call the responder method and handle the result
-      Promise.resolve(boundMethod(payload))
+      // Clear the discovery timeout immediately - we found a handler
+      discovery.resolve();
+      
+      // Call the timed responder method and handle the result
+      Promise.resolve(timedMethod(payload))
         .then(result => {
-          // Clear the timeout and resolve the data promise
-          timeout.resolve();
           data.resolve(result);
         })
         .catch(error => {
-          // Clear timeout and reject the data promise on error
-          timeout.resolve();
           data.reject(error);
           console.error(`Error in response handler ${handler.methodName}:`, error);
         });

package/src/symbols.ts

@@ -43,4 +43,8 @@ export const READY_HANDLERS = getSymbol('ready-handlers');
 export const DISPOSE_HANDLERS = getSymbol('dispose-handlers');
 
 // Observer symbols
-export const OBSERVERS = getSymbol('observers');
+export const OBSERVERS = getSymbol('observers');
+
+// Part symbols
+export const PARTS = getSymbol('parts');
+export const PART_TIMERS = getSymbol('part-timers');