snice 1.8.0 → 1.9.0

package/README.md

@@ -43,7 +43,8 @@ Snice provides a clear separation of concerns through decorators:
 ### Event Decorators
 - **`@on`** - Listens for events on elements
 - **`@dispatch`** - Dispatches custom events after method execution
-- **`@channel`** - Enables bidirectional communication between elements and controllers
+- **`@request`** - Makes requests from elements or controllers
+- **`@response`** - Responds to requests in elements or controllers
 
 This separation keeps your components focused: elements handle presentation, controllers manage data, and pages define navigation.
 
@@ -282,13 +283,26 @@ import { element, on } from 'snice';
 @element('my-clicker')
 class MyClicker extends HTMLElement {
   html() {
-    return `<button>Click me</button>`;
+    return `
+      <button>Click me</button>
+      <input type="text" placeholder="Press Enter" />
+    `;
   }
 
   @on('click', 'button')
   handleClick() {
     console.log('Button clicked!');
   }
+
+  @on('keydown:Enter', 'input')  // Only plain Enter (no modifiers)
+  handleEnter() {
+    console.log('Enter pressed!');
+  }
+  
+  @on('keydown:ctrl+Enter', 'input')  // Only Ctrl+Enter
+  handleCtrlEnter() {
+    console.log('Ctrl + Enter pressed!');
+  }
 }
 ```
 
@@ -547,16 +561,16 @@ Use it:
 <user-list controller="user-controller"></user-list>
 ```
 
-## Channels
+## Request/Response
 
 Bidirectional communication between elements and controllers:
 
 ```typescript
-// Element sends request, controller responds
+// Element makes request, controller responds
 @element('user-profile')
 class UserProfile extends HTMLElement {
 
-  @channel('fetch-user')
+  @request('fetch-user')
   async *getUser() {
     const user = await (yield { userId: 123 });
     return user;
@@ -573,7 +587,7 @@ class UserProfile extends HTMLElement {
 @controller('user-controller')
 class UserController {
 
-  @channel('fetch-user')
+  @response('fetch-user')
   async handleFetchUser(request: { userId: number }) {
     const response = await fetch(`/api/users/${request.userId}`);
     return response.json();
@@ -714,13 +728,51 @@ The `@context` decorator:
 
 **Remember:** With great power comes great responsibility. Global state is dangerous - use it wisely and sparingly.
 
+## Observing External Changes
+
+The `@observe` decorator provides lifecycle-managed observation of external changes like viewport intersection, element resize, media queries, and DOM mutations:
+
+```typescript
+import { element, observe } from 'snice';
+
+@element('lazy-image')
+class LazyImage extends HTMLElement {
+  html() {
+    return `
+      <img data-src="photo.jpg" class="lazy" />
+      <div class="loading">Loading...</div>
+    `;
+  }
+
+  // Observe when image enters viewport
+  @observe('intersection', '.lazy', { threshold: 0.1 })
+  loadImage(entry: IntersectionObserverEntry) {
+    if (entry.isIntersecting) {
+      const img = entry.target as HTMLImageElement;
+      img.src = img.dataset.src!;
+      img.classList.add('loaded');
+      return false; // Stop observing after loading
+    }
+  }
+
+  // Respond to viewport size changes
+  @observe('media:(min-width: 768px)')
+  handleDesktop(matches: boolean) {
+    this.classList.toggle('desktop-mode', matches);
+  }
+}
+```
+
+All observers are automatically cleaned up when elements disconnect from the DOM. See the [Observe API documentation](./docs/observe.md) for more examples.
+
 ## Documentation
 
 - [Elements API](./docs/elements.md) - Complete guide to creating elements with properties, queries, and styling
 - [Controllers API](./docs/controllers.md) - Data fetching, business logic, and controller patterns
 - [Events API](./docs/events.md) - Event handling, dispatching, and custom events
-- [Channels API](./docs/channels.md) - Bidirectional communication between elements and controllers
+- [Request/Response API](./docs/request-response.md) - Bidirectional communication between elements and controllers
 - [Routing API](./docs/routing.md) - Single-page application routing with transitions
+- [Observe API](./docs/observe.md) - Lifecycle-managed observers for external changes
 - [Migration Guide](./docs/migration-guide.md) - Migrating from React, Vue, Angular, and other frameworks
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snice",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "type": "module",
   "description": "A TypeScript library",
   "main": "src/index.ts",

package/src/controller.ts

@@ -1,5 +1,6 @@
 import { setupEventHandlers, cleanupEventHandlers } from './events';
-import { setupChannelHandlers, cleanupChannelHandlers } from './channel';
+import { setupObservers, cleanupObservers } from './observe';
+import { setupResponseHandlers, cleanupResponseHandlers } from './request-response';
 import { IS_CONTROLLER_CLASS, IS_CONTROLLER_INSTANCE, CONTROLLER_KEY, CONTROLLER_NAME_KEY, CONTROLLER_ID, CONTROLLER_OPERATIONS, NATIVE_CONTROLLER, IS_ELEMENT_CLASS, ROUTER_CONTEXT } from './symbols';
 import { snice } from './global';
 
@@ -134,8 +135,11 @@ export async function attachController(element: HTMLElement, controllerName: str
   // Setup @on event handlers for controller
   setupEventHandlers(controllerInstance, element);
   
+  // Setup @observe observers for controller
+  setupObservers(controllerInstance, element);
+  
   // Setup @channel handlers for controller
-  setupChannelHandlers(controllerInstance, element);
+  setupResponseHandlers(controllerInstance, element);
   
   element.dispatchEvent(new CustomEvent('controller.attached', {
     detail: { name: controllerName, controller: controllerInstance }
@@ -169,8 +173,11 @@ export async function detachController(element: HTMLElement): Promise<void> {
   // Cleanup @on event handlers for controller
   cleanupEventHandlers(controllerInstance);
   
+  // Cleanup @observe observers for controller
+  cleanupObservers(controllerInstance);
+  
   // Cleanup @channel handlers for controller
-  cleanupChannelHandlers(controllerInstance);
+  cleanupResponseHandlers(controllerInstance);
   
   // Cleanup the controller scope
   if (scope) {

package/src/element.ts

@@ -1,5 +1,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';
 
 /**
@@ -21,15 +23,13 @@ export function applyElementFunctionality(constructor: any) {
       observedAttributes.push('controller');
     }
     
-    // Add all reflected properties to observed attributes
+    // Add all properties to observed attributes (not just reflected ones)
     const properties = constructor[PROPERTIES];
     if (properties) {
       for (const [propName, propOptions] of properties) {
-        if (propOptions.reflect) {
-          const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName;
-          if (!observedAttributes.includes(attributeName)) {
-            observedAttributes.push(attributeName);
-          }
+        const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName;
+        if (!observedAttributes.includes(attributeName)) {
+          observedAttributes.push(attributeName);
         }
       }
     }
@@ -92,26 +92,29 @@ export function applyElementFunctionality(constructor: any) {
         const properties = constructor[PROPERTIES];
         if (properties) {
           for (const [propName, propOptions] of properties) {
-            if (propOptions.reflect) {
-              const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName;
-              // Only read from attribute if property hasn't been set yet
-              if (this.hasAttribute(attributeName) && !(propName in (this[PROPERTY_VALUES] || {}))) {
-                // Attribute exists, parse and set the property value
-                const attrValue = this.getAttribute(attributeName);
-                
-                // Mark as explicitly set since it came from an attribute
-                if (!this[EXPLICITLY_SET_PROPERTIES]) {
-                  this[EXPLICITLY_SET_PROPERTIES] = new Set();
-                }
-                this[EXPLICITLY_SET_PROPERTIES].add(propName);
-                
-                if (propOptions.type === Boolean) {
+            // If attribute exists, it always wins
+            if (this.hasAttribute(propName)) {
+              // Attribute exists, parse and set the property value
+              const attrValue = this.getAttribute(propName);
+              
+              // Mark as explicitly set since it came from an attribute
+              if (!this[EXPLICITLY_SET_PROPERTIES]) {
+                this[EXPLICITLY_SET_PROPERTIES] = new Set();
+              }
+              this[EXPLICITLY_SET_PROPERTIES].add(propName);
+              
+              switch (propOptions.type) {
+                case Boolean:
                   this[propName] = attrValue !== null && attrValue !== 'false';
-                } else if (propOptions.type === Number) {
+                  break;
+                case Number:
                   this[propName] = Number(attrValue);
-                } else {
+                  break;
+                case String:
+                  this[propName] = attrValue;
+                  break;
+                default:
                   this[propName] = attrValue;
-                }
               }
             }
           }
@@ -194,6 +197,16 @@ 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
+        setupResponseHandlers(this, this);
+        
+        // Setup @observe observers
+        try {
+          setupObservers(this, this);
+        } catch (error) {
+          console.error(`Error setting up observers for ${this.tagName}:`, error);
+        }
+        
         // Call @ready handlers after everything is set up
         const readyHandlers = constructor[READY_HANDLERS];
         if (readyHandlers) {
@@ -238,6 +251,10 @@ export function applyElementFunctionality(constructor: any) {
       }
       // Cleanup @on event handlers
       cleanupEventHandlers(this);
+      // Cleanup @response handlers
+      cleanupResponseHandlers(this);
+      // Cleanup @observe observers
+      cleanupObservers(this);
     };
     
     constructor.prototype.attributeChangedCallback = function(name: string, oldValue: string, newValue: string) {
@@ -245,43 +262,41 @@ export function applyElementFunctionality(constructor: any) {
       if (name === 'controller') {
         this.controller = newValue;
       } else {
-        // Handle reflected properties
+        // Handle all properties (not just reflected ones)
         const properties = constructor[PROPERTIES];
         if (properties) {
           for (const [propName, propOptions] of properties) {
-            if (propOptions.reflect) {
-              const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName;
-              if (attributeName === name) {
-                // Check if the current property value already matches to avoid feedback loops
-                const currentValue = this[PROPERTY_VALUES]?.[propName];
-                
-                // Parse the new value based on type
-                let parsedValue: any;
-                if (propOptions.type === Boolean) {
-                  parsedValue = newValue !== null && newValue !== 'false';
-                } else if (propOptions.type === Number) {
+            const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName;
+            if (attributeName === name) {
+              // Check if the current property value already matches to avoid feedback loops
+              const currentValue = this[PROPERTY_VALUES]?.[propName];
+              
+              // Parse the new value based on type
+              let parsedValue: any;
+              if (propOptions.type === Boolean) {
+                parsedValue = newValue !== null && newValue !== 'false';
+              } else if (propOptions.type === Number) {
+                parsedValue = Number(newValue);
+              } else {
+                // If no type specified, try to infer from current value type
+                if (typeof currentValue === 'number' && newValue !== null) {
                   parsedValue = Number(newValue);
                 } else {
-                  // If no type specified, try to infer from current value type
-                  if (typeof currentValue === 'number' && newValue !== null) {
-                    parsedValue = Number(newValue);
-                  } else {
-                    parsedValue = newValue;
-                  }
+                  parsedValue = newValue;
                 }
-                
-                // Only update if the value actually changed
-                if (currentValue !== parsedValue) {
-                  // Mark as explicitly set since it came from an attribute change
-                  if (!this[EXPLICITLY_SET_PROPERTIES]) {
-                    this[EXPLICITLY_SET_PROPERTIES] = new Set();
-                  }
-                  this[EXPLICITLY_SET_PROPERTIES].add(propName);
-                  
-                  this[propName] = parsedValue;
+              }
+              
+              // Only update if the value actually changed
+              if (currentValue !== parsedValue) {
+                // Mark as explicitly set since it came from an attribute change
+                if (!this[EXPLICITLY_SET_PROPERTIES]) {
+                  this[EXPLICITLY_SET_PROPERTIES] = new Set();
                 }
-                break;
+                this[EXPLICITLY_SET_PROPERTIES].add(propName);
+                
+                this[propName] = parsedValue;
               }
+              break;
             }
           }
         }
@@ -522,8 +537,9 @@ export function context() {
         });
         
         // Dispatch event and wait for response
-        // For controllers, use their element. For elements, dispatch on the host
-        let targetElement = this.element || this;
+        // Check if this is a controller using the symbol
+        const isController = this[IS_CONTROLLER_INSTANCE] === true;
+        let targetElement = isController && this.element ? this.element : this;
         
         // If element is null (e.g., controller was detached), can't get context
         if (!targetElement || !targetElement.dispatchEvent) {