snice 1.3.0 → 1.4.0

package/README.md

@@ -36,6 +36,7 @@ Snice provides a clear separation of concerns through decorators:
 - **`@property`** - Declares properties that can reflect to attributes
 - **`@query`** - Queries a single element from shadow DOM
 - **`@queryAll`** - Queries multiple elements from shadow DOM
+- **`@watch`** - Watches property changes and calls a method when they occur
 
 ### Event Decorators
 - **`@on`** - Listens for events on elements
@@ -155,6 +156,101 @@ Use it with attributes:
 ```
 
 
+## Watching Property Changes
+
+Use `@watch` to imperatively update DOM when properties change:
+
+```typescript
+import { element, property, watch, query } from 'snice';
+
+@element('theme-toggle')
+class ThemeToggle extends HTMLElement {
+  @property({ reflect: true })
+  theme: 'light' | 'dark' = 'light';
+  
+  @property({ type: Boolean })
+  animated = true;
+  
+  @query('.toggle-button')
+  button?: HTMLElement;
+  
+  @query('.theme-icon')
+  icon?: HTMLElement;
+  
+  html() {
+    return `
+      <button class="toggle-button">
+        <span class="theme-icon">🌞</span>
+      </button>
+    `;
+  }
+  
+  @watch('theme')
+  onThemeChange(oldTheme: string, newTheme: string, propertyName: string) {
+    // propertyName will be 'theme'
+    // Update icon when theme changes
+    if (this.icon) {
+      this.icon.textContent = newTheme === 'dark' ? '🌙' : '🌞';
+    }
+    
+    // Update button styling
+    if (this.button) {
+      this.button.classList.remove(`theme--${oldTheme}`);
+      this.button.classList.add(`theme--${newTheme}`);
+    }
+    
+    // Animate if enabled
+    if (this.animated && this.button) {
+      this.button.classList.add('transitioning');
+      setTimeout(() => {
+        this.button?.classList.remove('transitioning');
+      }, 300);
+    }
+  }
+  
+  @watch('animated')
+  onAnimatedChange(oldValue: boolean, newValue: boolean, propertyName: string) {
+    // propertyName will be 'animated'
+    if (this.button) {
+      this.button.classList.toggle('animations-enabled', newValue);
+    }
+  }
+  
+  @on('click', '.toggle-button')
+  toggleTheme() {
+    this.theme = this.theme === 'light' ? 'dark' : 'light';
+  }
+}
+```
+
+**Key Points:**
+- `@watch` methods are called when the property value changes
+- Receives `oldValue`, `newValue`, and `propertyName` as parameters
+- Perfect for imperatively updating DOM elements
+- Can watch multiple properties with multiple decorators
+- Works with both programmatic changes and attribute changes
+
+You can watch multiple properties with a single decorator:
+
+```typescript
+@watch('width', 'height', 'scale')
+updateDimensions(oldValue: number, newValue: number, propertyName: string) {
+  // Called when any of these properties change
+  console.log(`${propertyName} changed from ${oldValue} to ${newValue}`);
+  this.recalculateLayout();
+}
+```
+
+Watch all property changes with the wildcard:
+
+```typescript
+@watch('*')
+handleAnyPropertyChange(oldValue: any, newValue: any, propertyName: string) {
+  console.log(`Property ${propertyName} changed from ${oldValue} to ${newValue}`);
+  // Useful for debugging or when all properties affect the same output
+}
+```
+
 ## Queries
 
 Query single elements with `@query`:
@@ -578,6 +674,7 @@ Use the same card with different controllers:
 | `@property(options)` | Declares a property that can reflect to attributes | `@property({ type: Boolean, reflect: true })` |
 | `@query(selector)` | Queries a single element from shadow DOM | `@query('.button')` |
 | `@queryAll(selector)` | Queries multiple elements from shadow DOM | `@queryAll('input[type="checkbox"]')` |
+| `@watch(...propertyNames)` | Watches properties for changes and calls the method | `@watch('width', 'height')` or `@watch('*')` |
 
 ### Event Decorators
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snice",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "A TypeScript library",
   "main": "src/index.ts",
@@ -45,7 +45,7 @@
     "@vitest/ui": "^1.0.0",
     "happy-dom": "^12.0.0",
     "semantic-release": "^24.2.7",
-    "typescript": "^5.3.3",
+    "typescript": "^5.9.2",
     "vite": "^5.0.10",
     "vitest": "^1.0.0"
   }

package/src/element.ts

@@ -1,6 +1,6 @@
 import { attachController, detachController } from './controller';
 import { setupEventHandlers, cleanupEventHandlers } from './events';
-import { IS_ELEMENT_CLASS, READY_PROMISE, READY_RESOLVE, CONTROLLER, PROPERTIES, PROPERTY_VALUES } from './symbols';
+import { IS_ELEMENT_CLASS, READY_PROMISE, READY_RESOLVE, CONTROLLER, PROPERTIES, PROPERTY_VALUES, PROPERTIES_INITIALIZED, PROPERTY_WATCHERS, EXPLICITLY_SET_PROPERTIES } from './symbols';
 
 export function element(tagName: string) {
   return function (constructor: any) {
@@ -12,11 +12,25 @@ export function element(tagName: string) {
     const originalDisconnectedCallback = constructor.prototype.disconnectedCallback;
     const originalAttributeChangedCallback = constructor.prototype.attributeChangedCallback;
     
-    // Add 'controller' to observed attributes
+    // Add 'controller' and all reflected properties to observed attributes
     const observedAttributes = constructor.observedAttributes || [];
     if (!observedAttributes.includes('controller')) {
       observedAttributes.push('controller');
     }
+    
+    // Add all reflected properties to observed attributes
+    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);
+          }
+        }
+      }
+    }
+    
     Object.defineProperty(constructor, 'observedAttributes', {
       get() { return observedAttributes; },
       configurable: true
@@ -71,6 +85,53 @@ export function element(tagName: string) {
       }
       
       try {
+        // Initialize properties from attributes before rendering
+        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) {
+                  this[propName] = attrValue !== null;
+                } else if (propOptions.type === Number) {
+                  this[propName] = Number(attrValue);
+                } else {
+                  this[propName] = attrValue;
+                }
+              }
+            }
+          }
+        }
+        
+        // Mark that properties have been initialized
+        this[PROPERTIES_INITIALIZED] = true;
+        
+        // Reflect properties that were explicitly set before connection
+        // but skip default values that were never explicitly set
+        if (properties && this[EXPLICITLY_SET_PROPERTIES]) {
+          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;
+              
+              if (value !== null && value !== undefined && value !== false) {
+                this.setAttribute(attributeName, String(value));
+              }
+            }
+          }
+        }
+        
         // Clean up any existing event handlers first (for reconnection)
         cleanupEventHandlers(this);
         
@@ -150,6 +211,47 @@ export function element(tagName: string) {
       originalAttributeChangedCallback?.call(this, name, oldValue, newValue);
       if (name === 'controller') {
         this.controller = newValue;
+      } else {
+        // Handle reflected properties
+        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;
+                } 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 {
+                    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;
+                }
+                break;
+              }
+            }
+          }
+        }
       }
     };
     
@@ -181,18 +283,64 @@ export function property(options?: PropertyOptions) {
         if (!this[PROPERTY_VALUES]) {
           this[PROPERTY_VALUES] = {};
         }
+        if (!this[EXPLICITLY_SET_PROPERTIES]) {
+          this[EXPLICITLY_SET_PROPERTIES] = new Set();
+        }
+        
         const oldValue = this[PROPERTY_VALUES][propertyKey];
         
         // 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) {
+          this[EXPLICITLY_SET_PROPERTIES].add(propertyKey);
+        }
+        
         this[PROPERTY_VALUES][propertyKey] = value;
         
-        if (options?.reflect && this.setAttribute) {
+        // Only reflect to attributes if:
+        // 1. Properties have been initialized from attributes  
+        // 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;
+          
           if (value === null || value === undefined || value === false) {
-            this.removeAttribute(options.attribute || propertyKey);
+            this.removeAttribute(attributeName);
           } else {
-            this.setAttribute(options.attribute || propertyKey, String(value));
+            this.setAttribute(attributeName, String(value));
+          }
+        }
+        
+        // Call watchers for this property
+        const watchers = constructor[PROPERTY_WATCHERS];
+        if (watchers) {
+          // Call specific property watchers
+          if (watchers.has(propertyKey)) {
+            const propertyWatchers = watchers.get(propertyKey);
+            for (const watcher of propertyWatchers) {
+              try {
+                // Always pass oldValue, newValue, and propertyName
+                watcher.method.call(this, oldValue, value, propertyKey);
+              } catch (error) {
+                console.error(`Error in @watch('${propertyKey}') method ${watcher.methodName}:`, error);
+              }
+            }
+          }
+          
+          // Call wildcard watchers (watching "*")
+          if (watchers.has('*')) {
+            const wildcardWatchers = watchers.get('*');
+            for (const watcher of wildcardWatchers) {
+              try {
+                // Same signature for consistency
+                watcher.method.call(this, oldValue, value, propertyKey);
+              } catch (error) {
+                console.error(`Error in @watch('*') method ${watcher.methodName}:`, error);
+              }
+            }
           }
         }
         
@@ -256,4 +404,28 @@ export interface PropertyOptions {
 export interface PropertyConverter {
   fromAttribute?(value: string | null, type?: any): any;
   toAttribute?(value: any, type?: any): string | null;
+}
+
+export function watch(...propertyNames: string[]) {
+  return function (target: any, methodName: string, descriptor: PropertyDescriptor) {
+    const constructor = target.constructor;
+    
+    if (!constructor[PROPERTY_WATCHERS]) {
+      constructor[PROPERTY_WATCHERS] = new Map();
+    }
+    
+    // Store the watcher method for each property
+    for (const propertyName of propertyNames) {
+      if (!constructor[PROPERTY_WATCHERS].has(propertyName)) {
+        constructor[PROPERTY_WATCHERS].set(propertyName, []);
+      }
+      
+      constructor[PROPERTY_WATCHERS].get(propertyName).push({
+        methodName,
+        method: descriptor.value
+      });
+    }
+    
+    return descriptor;
+  };
 }

package/src/index.ts

@@ -1,4 +1,4 @@
-export { element, customElement, property, query, queryAll } from './element';
+export { element, customElement, property, query, queryAll, watch } from './element';
 export { Router } from './router';
 export { controller, attachController, detachController, getController, useNativeElementControllers, cleanupNativeElementControllers } from './controller';
 export { on, dispatch } from './events';

package/src/symbols.ts

@@ -27,4 +27,7 @@ export const CLEANUP = getSymbol('cleanup');
 
 // Property symbols
 export const PROPERTIES = getSymbol('properties');
-export const PROPERTY_VALUES = getSymbol('property-values');
+export const PROPERTY_VALUES = getSymbol('property-values');
+export const PROPERTIES_INITIALIZED = getSymbol('properties-initialized');
+export const PROPERTY_WATCHERS = getSymbol('property-watchers');
+export const EXPLICITLY_SET_PROPERTIES = getSymbol('explicitly-set-properties');

package/src/route-parser.d.ts

@@ -1,8 +0,0 @@
-declare module 'route-parser' {
-  export default class Route {
-    constructor(spec: string);
-    match(path: string): Record<string, string> | false;
-    reverse(params?: Record<string, any>): string;
-    spec: string;
-  }
-}