snice 1.2.0 → 1.4.0

package/README.md

@@ -2,6 +2,16 @@
 
 A lightweight TypeScript framework for building web components with decorators and routing.
 
+## Quick Start
+
+Create a new Snice app with one command:
+
+```bash
+npx snice create-app my-app
+cd my-app
+npm run dev
+```
+
 ## Core Philosophy: Imperative, Not Reactive
 
 Snice takes an **imperative approach** to web components. Unlike reactive frameworks that automatically re-render when data changes, Snice components:
@@ -26,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
@@ -145,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`:
@@ -315,13 +421,16 @@ class AboutPage extends HTMLElement {
   }
 }
 
-// Page with URL parameter
-@page({ tag: 'user-page', routes: ['/users/:id'] })
+// Page with URL parameter  
+import { property } from 'snice';
+
+@page({ tag: 'user-page', routes: ['/users/:userId'] })
 class UserPage extends HTMLElement {
-  id = '';  // Automatically set from URL
+  @property()
+  userId = '';
   
   html() {
-    return `<h1>User ${this.id}</h1>`;
+    return `<h1>User ${this.userId}</h1>`;
   }
 }
 
@@ -565,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/bin/snice.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve, basename } from 'path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, cpSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === 'create-app') {
+  const projectPath = args[1] || '.';
+  createApp(projectPath);
+} else {
+  console.log(`
+Snice CLI
+
+Usage:
+  snice create-app <project-name>  Create a new Snice application
+  snice create-app .               Initialize in current directory
+
+Examples:
+  snice create-app my-app
+  npx snice create-app my-app
+`);
+}
+
+function createApp(projectPath) {
+  const targetDir = resolve(process.cwd(), projectPath);
+  const projectName = projectPath === '.' ? basename(process.cwd()) : basename(targetDir);
+  
+  console.log(`\n🚀 Creating Snice app in ${targetDir}...\n`);
+
+  // Check if directory exists and is empty
+  if (projectPath !== '.') {
+    if (existsSync(targetDir)) {
+      const files = readdirSync(targetDir);
+      if (files.length > 0 && !files.every(f => f.startsWith('.'))) {
+        console.error(`❌ Directory ${targetDir} is not empty!`);
+        process.exit(1);
+      }
+    } else {
+      mkdirSync(targetDir, { recursive: true });
+    }
+  } else {
+    // Check current directory
+    const files = readdirSync(targetDir);
+    const hasNonDotFiles = files.some(f => !f.startsWith('.') && f !== 'node_modules');
+    if (hasNonDotFiles) {
+      console.error(`❌ Current directory is not empty!`);
+      process.exit(1);
+    }
+  }
+
+  // Path to templates
+  const templateDir = join(__dirname, 'templates', 'base');
+  
+  // Copy template files
+  copyTemplateFiles(templateDir, targetDir, projectName);
+
+  console.log(`\n✨ Project created successfully!\n`);
+  console.log('Next steps:');
+  
+  if (projectPath !== '.') {
+    console.log(`  cd ${projectPath}`);
+  }
+  
+  console.log('  npm install');
+  console.log('  npm run dev\n');
+  console.log('Happy coding! 🎉\n');
+}
+
+function copyTemplateFiles(sourceDir, targetDir, projectName) {
+  const files = readdirSync(sourceDir, { withFileTypes: true });
+  
+  for (const file of files) {
+    const sourcePath = join(sourceDir, file.name);
+    const targetPath = join(targetDir, file.name);
+    
+    if (file.isDirectory()) {
+      // Create directory and recursively copy contents
+      if (!existsSync(targetPath)) {
+        mkdirSync(targetPath, { recursive: true });
+      }
+      copyTemplateFiles(sourcePath, targetPath, projectName);
+    } else {
+      // Read file, replace placeholders, and write to target
+      console.log(`  Creating ${file.name}...`);
+      
+      let content = readFileSync(sourcePath, 'utf8');
+      
+      // Replace {{projectName}} placeholders
+      content = content.replace(/\{\{projectName\}\}/g, projectName);
+      
+      writeFileSync(targetPath, content);
+    }
+  }
+}

package/bin/templates/base/README.md

@@ -0,0 +1,33 @@
+# {{projectName}}
+
+A Snice application
+
+## Development
+
+```bash
+npm run dev
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Preview Production Build
+
+```bash
+npm run preview
+```
+
+## Project Structure
+
+- `src/pages/` - Application pages/routes
+- `src/components/` - Reusable components
+- `src/controllers/` - Business logic controllers
+- `src/styles/` - Global styles and shared styles
+- `src/types/` - TypeScript interfaces and types
+- `src/router.ts` - Router configuration
+- `src/main.ts` - Application entry point
+
+Built with [Snice](https://github.com/yourusername/snice)

package/bin/templates/base/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{projectName}}</title>
+  <link rel="icon" type="image/svg+xml" href="/vite.svg">
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/main.ts"></script>
+</body>
+</html>

package/bin/templates/base/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "snice": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "terser": "^5.24.0",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.10"
+  }
+}

package/bin/templates/base/public/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

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

@@ -0,0 +1,101 @@
+import { element, property, query, on, dispatch } from 'snice';
+import type { ICounterButton } from '../types/counter-button';
+
+@element('counter-button')
+export class CounterButton extends HTMLElement implements ICounterButton {
+  @property({ type: Number })
+  count = 0;
+
+  @query('.count')
+  countDisplay?: HTMLElement;
+
+  html() {
+    return /*html*/`
+      <div class="counter">
+        <button class="btn minus">-</button>
+        <span class="count">${this.count}</span>
+        <button class="btn plus">+</button>
+      </div>
+    `;
+  }
+
+  css() {
+    return /*css*/`
+      .counter {
+        display: inline-flex;
+        align-items: center;
+        gap: 1rem;
+        padding: 1rem;
+        background: white;
+        border-radius: 8px;
+        box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+      }
+      
+      .count {
+        font-size: 1.5rem;
+        font-weight: bold;
+        min-width: 3rem;
+        text-align: center;
+      }
+      
+      .btn {
+        width: 2rem;
+        height: 2rem;
+        border: 2px solid var(--primary-color);
+        background: white;
+        color: var(--primary-color);
+        border-radius: 4px;
+        cursor: pointer;
+        font-size: 1.2rem;
+      }
+      
+      .btn:hover {
+        background: var(--primary-color);
+        color: white;
+      }
+    `;
+  }
+
+  // Imperative methods that controller can call
+  setCount(value: number) {
+    this.count = value;
+    this.updateDisplay();
+  }
+
+  @dispatch('count-changed')
+  increment() {
+    this.count++;
+    this.updateDisplay();
+    return { count: this.count };
+  }
+
+  @dispatch('count-changed')
+  decrement() {
+    this.count--;
+    this.updateDisplay();
+    return { count: this.count };
+  }
+
+  @dispatch('count-changed')
+  reset() {
+    this.count = 0;
+    this.updateDisplay();
+    return { count: this.count };
+  }
+
+  private updateDisplay() {
+    if (this.countDisplay) {
+      this.countDisplay.textContent = String(this.count);
+    }
+  }
+
+  @on('click', '.plus')
+  handlePlus() {
+    this.increment();
+  }
+
+  @on('click', '.minus')
+  handleMinus() {
+    this.decrement();
+  }
+}

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

@@ -0,0 +1,24 @@
+import { controller, on } from 'snice';
+import type { ICounterButton } from '../types/counter-button';
+
+@controller('counter')
+export class CounterController {
+  element!: ICounterButton;
+  
+  async attach() {
+    // Load saved count from localStorage
+    const saved = localStorage.getItem('counter-value');
+    if (saved) {
+      this.element.setCount(parseInt(saved));
+    }
+  }
+
+  async detach() {
+    // any clean up you need
+  }
+  
+  @on('count-changed')
+  handleCountChanged(e: CustomEvent) {
+    localStorage.setItem('counter-value', String(e.detail.count));
+  }
+}

package/bin/templates/base/src/main.ts

@@ -0,0 +1,16 @@
+import { initialize } from './router';
+import './styles/global.css';
+
+// Import components
+import './components/counter-button';
+
+// Import controllers
+import './controllers/counter-controller';
+
+// Import pages
+import './pages/home-page';
+import './pages/about-page';
+import './pages/not-found-page';
+
+// Initialize router
+initialize();

package/bin/templates/base/src/pages/about-page.ts

@@ -0,0 +1,56 @@
+import { page } from '../router';
+
+@page({ tag: 'about-page', routes: ['/about'] })
+export class AboutPage extends HTMLElement {
+  html() {
+    return /*html*/`
+      <div class="container">
+        <h1>About</h1>
+        <p>This app was built with Snice, a modern web components framework.</p>
+        <p>Version 1.0.0</p>
+        
+        <div class="nav">
+          <a href="#/" class="btn">Back to Home</a>
+        </div>
+      </div>
+    `;
+  }
+
+  css() {
+    return /*css*/`
+      .container {
+        padding: 3rem;
+        max-width: 800px;
+        margin: 0 auto;
+        text-align: center;
+      }
+      
+      h1 {
+        color: var(--primary-color);
+        margin-bottom: 1rem;
+      }
+      
+      p {
+        color: var(--text-light);
+        margin-bottom: 1rem;
+      }
+      
+      .nav {
+        margin-top: 3rem;
+      }
+      
+      .btn {
+        display: inline-block;
+        padding: 0.75rem 1.5rem;
+        background: var(--primary-color);
+        color: white;
+        text-decoration: none;
+        border-radius: 6px;
+      }
+      
+      .btn:hover {
+        background: var(--secondary-color);
+      }
+    `;
+  }
+}

package/bin/templates/base/src/pages/home-page.ts

@@ -0,0 +1,77 @@
+import { page } from '../router';
+
+@page({ tag: 'home-page', routes: ['/'] })
+export class HomePage extends HTMLElement {
+  html() {
+    return /*html*/`
+      <div class="container">
+        <h1>Welcome to {{projectName}}</h1>
+        <p>Built with Snice</p>
+        
+        <div class="demo-section">
+          <h2>Interactive Counter Demo</h2>
+          <p>This counter persists its state using a controller:</p>
+          <counter-button controller="counter"></counter-button>
+        </div>
+        
+        <div class="nav">
+          <a href="#/about" class="btn">About</a>
+        </div>
+      </div>
+    `;
+  }
+
+  css() {
+    return /*css*/`
+      .container {
+        padding: 3rem;
+        text-align: center;
+        max-width: 800px;
+        margin: 0 auto;
+      }
+      
+      h1 {
+        color: var(--primary-color);
+        margin-bottom: 1rem;
+        font-size: 2.5rem;
+      }
+      
+      h2 {
+        color: var(--primary-color);
+        margin-bottom: 1rem;
+        font-size: 1.5rem;
+      }
+      
+      p {
+        color: var(--text-light);
+        margin-bottom: 2rem;
+      }
+      
+      .demo-section {
+        margin: 3rem 0;
+        padding: 2rem;
+        background: rgba(255, 255, 255, 0.5);
+        border-radius: 12px;
+        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.05);
+      }
+      
+      .nav {
+        margin-top: 3rem;
+      }
+      
+      .btn {
+        display: inline-block;
+        padding: 0.75rem 1.5rem;
+        background: var(--primary-color);
+        color: white;
+        text-decoration: none;
+        border-radius: 6px;
+        transition: background 0.3s ease;
+      }
+      
+      .btn:hover {
+        background: var(--secondary-color);
+      }
+    `;
+  }
+}

package/bin/templates/base/src/pages/not-found-page.ts

@@ -0,0 +1,52 @@
+import { page } from '../router';
+
+@page({ tag: 'not-found-page', routes: ['/404'] })
+export class NotFoundPage extends HTMLElement {
+  html() {
+    return /*html*/`
+      <div class="container">
+        <h1>404</h1>
+        <p>Page not found</p>
+        <a href="#/" class="btn">Go Home</a>
+      </div>
+    `;
+  }
+
+  css() {
+    return /*css*/`
+      .container {
+        padding: 3rem;
+        text-align: center;
+        min-height: 100vh;
+        display: flex;
+        flex-direction: column;
+        justify-content: center;
+        align-items: center;
+      }
+      
+      h1 {
+        font-size: 4rem;
+        color: var(--primary-color);
+        margin-bottom: 1rem;
+      }
+      
+      p {
+        color: var(--text-light);
+        margin-bottom: 2rem;
+      }
+      
+      .btn {
+        display: inline-block;
+        padding: 0.75rem 1.5rem;
+        background: var(--primary-color);
+        color: white;
+        text-decoration: none;
+        border-radius: 6px;
+      }
+      
+      .btn:hover {
+        background: var(--secondary-color);
+      }
+    `;
+  }
+}

package/bin/templates/base/src/router.ts

@@ -0,0 +1,15 @@
+import { Router } from 'snice';
+
+const { page, initialize, navigate } = Router({ 
+  target: '#app', 
+  routing_type: 'hash',
+  transition: {
+    mode: 'simultaneous',
+    outDuration: 200,
+    inDuration: 200,
+    out: 'opacity: 0; transform: translateX(-10px);',
+    in: 'opacity: 1; transform: translateX(0);'
+  }
+});
+
+export { page, initialize, navigate };

package/bin/templates/base/src/styles/global.css

@@ -0,0 +1,27 @@
+:root {
+  --primary-color: #667eea;
+  --secondary-color: #764ba2;
+  --text-color: #333;
+  --text-light: #666;
+  --bg-color: #f7f7f7;
+  --white: #ffffff;
+  --shadow: 0 2px 4px rgba(0,0,0,0.1);
+  --shadow-lg: 0 10px 30px rgba(0,0,0,0.15);
+}
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+  color: var(--text-color);
+  background: var(--bg-color);
+  line-height: 1.6;
+}
+
+#app {
+  min-height: 100vh;
+}

package/bin/templates/base/src/styles/shared.ts

@@ -0,0 +1,82 @@
+export const containerStyles = `
+  .container {
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 2rem;
+  }
+  
+  .btn {
+    padding: 0.75rem 1.5rem;
+    border-radius: 6px;
+    text-decoration: none;
+    font-weight: 600;
+    transition: all 0.3s ease;
+    cursor: pointer;
+    border: none;
+    display: inline-block;
+  }
+  
+  .btn-primary {
+    background: var(--primary-color);
+    color: white;
+  }
+  
+  .btn-primary:hover {
+    background: var(--secondary-color);
+    transform: translateY(-2px);
+  }
+  
+  .btn-secondary {
+    background: transparent;
+    color: var(--primary-color);
+    border: 2px solid var(--primary-color);
+  }
+  
+  .btn-secondary:hover {
+    background: var(--primary-color);
+    color: white;
+  }
+`;
+
+export const navbarStyles = `
+  .navbar {
+    background: var(--white);
+    box-shadow: var(--shadow);
+    position: sticky;
+    top: 0;
+    z-index: 100;
+  }
+  
+  .nav-container {
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 1rem 2rem;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+  }
+  
+  .nav-brand {
+    font-size: 1.5rem;
+    font-weight: 700;
+    color: var(--primary-color);
+  }
+  
+  .nav-menu {
+    display: flex;
+    list-style: none;
+    gap: 2rem;
+  }
+  
+  .nav-link {
+    color: var(--text-light);
+    text-decoration: none;
+    font-weight: 500;
+    transition: color 0.3s;
+  }
+  
+  .nav-link:hover,
+  .nav-link.active {
+    color: var(--primary-color);
+  }
+`;

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

@@ -0,0 +1,7 @@
+export interface ICounterButton extends HTMLElement {
+  count: number;
+  setCount(count: number): void;
+  increment(): void;
+  decrement(): void;
+  reset(): void;
+}

package/bin/templates/base/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src"]
+}

package/bin/templates/base/vite.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  build: {
+    target: 'es2015',
+    minify: 'terser',
+    cssMinify: true,
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['snice']
+        }
+      }
+    },
+    sourcemap: true,
+    chunkSizeWarningLimit: 500
+  },
+  esbuild: {
+    drop: process.env.NODE_ENV === 'production' ? ['debugger'] : []
+  }
+});

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "snice",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "A TypeScript library",
   "main": "src/index.ts",
   "module": "src/index.ts",
   "types": "src/index.ts",
+  "bin": {
+    "snice": "./bin/snice.js"
+  },
   "files": [
     "src",
+    "bin",
+    "templates",
     "!src/**/*.test.ts",
     "!src/**/*.spec.ts"
   ],
@@ -40,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');