snice 3.3.0 → 3.4.0

package/bin/snice.js

@@ -11,27 +11,57 @@ const args = process.argv.slice(2);
 const command = args[0];
 
 if (command === 'create-app') {
-  const projectPath = args[1] || '.';
-  createApp(projectPath);
+  // Parse arguments - separate flags from positional arguments
+  const flags = {};
+  const positional = [];
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      if (arg.includes('=')) {
+        const [key, value] = arg.split('=');
+        flags[key.slice(2)] = value;
+      } else {
+        flags[arg.slice(2)] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  const projectPath = positional[0] || '.';
+  const template = flags.template || 'base';
+
+  createApp(projectPath, template);
 } else {
   console.log(`
 Snice CLI
 
 Usage:
-  snice create-app <project-name>  Create a new Snice application
-  snice create-app .               Initialize in current directory
+  snice create-app [options] <project-name>
+  snice create-app [options] .                          Initialize in current directory
+
+Options:
+  --template=<name>                                     Template to use (default: base)
+
+Templates:
+  base    - Minimal starter with counter example (default)
+  social  - Social media sample app showcasing components
 
 Examples:
   snice create-app my-app
-  npx snice create-app my-app
+  snice create-app my-app --template=social
+  snice create-app --template=social my-app
+  npx snice create-app my-app --template=social
 `);
 }
 
-function createApp(projectPath) {
+function createApp(projectPath, template = 'base') {
   const targetDir = resolve(process.cwd(), projectPath);
   const projectName = projectPath === '.' ? basename(process.cwd()) : basename(targetDir);
-  
+
   console.log(`\n🚀 Creating Snice app in ${targetDir}...\n`);
+  console.log(`📦 Using template: ${template}\n`);
 
   // Check if directory exists and is empty
   if (projectPath !== '.') {
@@ -55,18 +85,33 @@ function createApp(projectPath) {
   }
 
   // Path to templates
-  const templateDir = join(__dirname, 'templates', 'base');
-  
+  const templateDir = join(__dirname, 'templates', template);
+
+  // Check if template exists
+  if (!existsSync(templateDir)) {
+    console.error(`❌ Template "${template}" not found!`);
+    console.error(`Available templates: base, social`);
+    process.exit(1);
+  }
+
   // Copy template files
   copyTemplateFiles(templateDir, targetDir, projectName);
 
+  // Copy shared CLAUDE.md
+  const claudeMdPath = join(__dirname, 'templates', 'CLAUDE.md');
+  if (existsSync(claudeMdPath)) {
+    console.log(`  Creating CLAUDE.md...`);
+    const claudeMdContent = readFileSync(claudeMdPath, 'utf8');
+    writeFileSync(join(targetDir, 'CLAUDE.md'), claudeMdContent.replace(/\{\{projectName\}\}/g, 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');

package/bin/templates/CLAUDE.md

@@ -0,0 +1,138 @@
+# Snice Project - AI Assistant Guide
+
+## Documentation Location
+
+AI-optimized docs shipped in: `node_modules/snice/docs/ai/`
+
+**Read these files:**
+- `api.md` - Complete API reference
+- `patterns.md` - Usage examples
+- `architecture.md` - System design
+- `components/*.md` - Component docs (read only as needed)
+
+## Project Structure
+
+```
+src/
+  pages/          # @page decorated route components
+  components/     # @element decorated UI components
+  controllers/    # @controller decorated behavior modules
+  styles/         # Global CSS
+```
+
+**Separation of concerns:**
+- **Pages** - Orchestrate elements, handle URLs
+- **Elements** - Pure presentation, no business logic
+- **Controllers** - Behavior, data fetching, swappable
+
+## Decorators
+
+```typescript
+// Class decorators
+@page({ tag, routes, guards?, placard? })
+@element('tag-name')
+@controller('name')
+@layout('name')
+
+// Property/method decorators
+@property() name = 'default'
+@render() fn() { return html`...` }
+@styles() fn() { return css`...` }
+@ready() async fn() { ... }
+@dispose() fn() { ... }
+@watch('name') fn(oldVal, newVal) { ... }
+@query('input') input!: HTMLInputElement
+@queryAll('.item') items!: NodeListOf<HTMLElement>
+@on('click', 'button') fn(e: Event) { ... }
+@dispatch('value-changed') fn(val: string) => Event Detail
+@context() fn(ctx: Context) { ... }
+@request('user') fn(): () => Request
+@respond('user') fn(req) => Response
+@observe(() => this.el, options) fn(mutations) { ... }
+```
+
+## Quick Examples
+
+**Element:**
+```typescript
+@element('my-counter')
+class Counter extends HTMLElement {
+  @property({ type: Number }) count = 0;
+
+  @render()
+  renderContent() {
+    return html`
+      <div>${this.count}</div>
+      <button @click=${() => this.count++}>+</button>
+    `;
+  }
+
+  @styles()
+  componentStyles() {
+    return css`:host { display: block; }`;
+  }
+}
+```
+
+**Page:**
+```typescript
+@page({ tag: 'user-page', routes: ['/users/:id'] })
+class UserPage extends HTMLElement {
+  @property() id = '';
+
+  @ready()
+  async load() {
+    const user = await fetch(`/api/users/${this.id}`).then(r => r.json());
+  }
+}
+```
+
+**Controller:**
+```typescript
+@controller('data-loader')
+class DataLoader implements IController {
+  element: HTMLElement;
+
+  async attach(el: HTMLElement) {
+    this.element = el;
+  }
+
+  async detach() {}
+
+  @on('click', '.item')
+  handleClick(e: Event) {}
+}
+
+// Usage: <my-list controller="data-loader"></my-list>
+```
+
+**Lists:**
+```typescript
+html`
+  ${items.map(item => html`
+    <li key=${item.id}>${item.name}</li>
+  `)}
+`
+```
+
+**Conditionals:**
+```typescript
+html`
+  <if ${condition}>Content</if>
+`
+```
+
+## Communication
+
+- **Parent → Child:** Properties (`.prop=${value}`)
+- **Child → Parent:** Events (`@dispatch`)
+- **Element ↔ Controller:** Request/Response (`@request`, `@respond`)
+- **Global State:** Context (`@context()`)
+
+## Build Commands
+
+```bash
+npm run dev        # Dev server
+npm run build      # Production build
+npm run type-check # TypeScript check
+```

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

@@ -8,7 +8,7 @@ export class CounterButton extends HTMLElement implements ICounterButton {
 
   @render()
   renderContent() {
-    return html`
+    return html/*html*/`
       <div class="counter">
         <button class="btn minus" @click=${this.handleMinus}>-</button>
         <span class="count">${this.count}</span>
@@ -19,7 +19,7 @@ export class CounterButton extends HTMLElement implements ICounterButton {
 
   @styles()
   componentStyles() {
-    return css`
+    return css/*css*/`
       .counter {
         display: inline-flex;
         align-items: center;

package/bin/templates/base/src/components/feature-card.ts

@@ -0,0 +1,59 @@
+import { element, property, render, styles, html, css } from 'snice';
+
+@element('feature-card')
+export class FeatureCard extends HTMLElement {
+  @property() icon = '✨';
+  @property() title = '';
+  @property() description = '';
+
+  @render()
+  renderContent() {
+    return html/*html*/`
+      <div class="card">
+        <div class="card__icon">${this.icon}</div>
+        <h3 class="card__title">${this.title}</h3>
+        <p class="card__description">${this.description}</p>
+      </div>
+    `;
+  }
+
+  @styles()
+  componentStyles() {
+    return css/*css*/`
+      :host {
+        display: block;
+      }
+
+      .card {
+        padding: 2rem;
+        background: white;
+        border-radius: 12px;
+        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+        transition: transform 0.2s, box-shadow 0.2s;
+      }
+
+      .card:hover {
+        transform: translateY(-4px);
+        box-shadow: 0 4px 16px rgba(0, 0, 0, 0.15);
+      }
+
+      .card__icon {
+        font-size: 3rem;
+        margin-bottom: 1rem;
+      }
+
+      .card__title {
+        font-size: 1.25rem;
+        font-weight: 600;
+        margin: 0 0 0.5rem 0;
+        color: var(--text-color, #333);
+      }
+
+      .card__description {
+        margin: 0;
+        color: var(--text-light, #666);
+        line-height: 1.6;
+      }
+    `;
+  }
+}

package/bin/templates/base/src/components/feature-card.types.ts

@@ -0,0 +1,5 @@
+export interface FeatureCardElement extends HTMLElement {
+  icon: string;
+  title: string;
+  description: string;
+}

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

@@ -1,11 +1,16 @@
 import { initialize } from './router';
 import './styles/global.css';
 
-// Import a layout
+// Import snice layout
 import 'snice/components/layout/snice-layout';
 
-// Import components
+// Import snice components
+import 'snice/components/button/snice-button';
+import 'snice/components/card/snice-card';
+
+// Import custom components
 import './components/counter-button';
+import './components/feature-card';
 
 // Import controllers
 import './controllers/counter-controller';

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

@@ -1,4 +1,5 @@
 import { page } from '../router';
+import { render, styles, html, css } from 'snice';
 import type { Placard } from 'snice';
 
 const placard: Placard = {
@@ -11,13 +12,14 @@ const placard: Placard = {
 
 @page({ tag: 'about-page', routes: ['/about'], placard })
 export class AboutPage extends HTMLElement {
-  html() {
-    return /*html*/`
+  @render()
+  renderContent() {
+    return html/*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>
@@ -25,8 +27,9 @@ export class AboutPage extends HTMLElement {
     `;
   }
 
-  css() {
-    return /*css*/`
+  @styles()
+  componentStyles() {
+    return css/*css*/`
       .container {
         padding: 3rem;
         max-width: 800px;

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

@@ -1,4 +1,5 @@
 import { page } from '../router';
+import { render, styles, html, css } from 'snice';
 import type { Placard } from 'snice';
 
 const placard: Placard = {
@@ -11,27 +12,51 @@ const placard: Placard = {
 
 @page({ tag: 'home-page', routes: ['/'], placard })
 export class HomePage extends HTMLElement {
-  html() {
-    return /*html*/`
+  @render()
+  renderContent() {
+    return html/*html*/`
       <div class="container">
         <h1>Welcome to {{projectName}}</h1>
         <p>Built with Snice</p>
-        
-        <div class="demo-section">
+
+        <div class="features">
+          <feature-card
+            icon="⚡"
+            title="Fast & Lightweight"
+            description="No virtual DOM overhead. Direct DOM updates with differential rendering.">
+          </feature-card>
+
+          <feature-card
+            icon="🎨"
+            title="Type-Safe"
+            description="Full TypeScript support with decorators for clean, maintainable code.">
+          </feature-card>
+
+          <feature-card
+            icon="🔧"
+            title="Web Standards"
+            description="Built on native Web Components. Works everywhere, no framework lock-in.">
+          </feature-card>
+        </div>
+
+        <snice-card 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>
-        
+        </snice-card>
+
         <div class="nav">
-          <a href="#/about" class="btn">About</a>
+          <snice-button variant="primary" size="medium">
+            <a href="#/about" style="color: inherit; text-decoration: none;">Learn More</a>
+          </snice-button>
         </div>
       </div>
     `;
   }
 
-  css() {
-    return /*css*/`
+  @styles()
+  componentStyles() {
+    return css/*css*/`
       .container {
         padding: 3rem;
         text-align: center;
@@ -56,31 +81,25 @@ export class HomePage extends HTMLElement {
         margin-bottom: 2rem;
       }
       
+      .features {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+        gap: 2rem;
+        margin: 3rem 0;
+      }
+
       .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);
+        text-align: center;
       }
-      
+
+      .demo-section h2 {
+        margin-top: 0;
+      }
+
       .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

@@ -1,9 +1,11 @@
 import { page } from '../router';
+import { render, styles, html, css } from 'snice';
 
 @page({ tag: 'not-found-page', routes: ['/404'] })
 export class NotFoundPage extends HTMLElement {
-  html() {
-    return /*html*/`
+  @render()
+  renderContent() {
+    return html/*html*/`
       <div class="container">
         <h1>404</h1>
         <p>Page not found</p>
@@ -12,8 +14,9 @@ export class NotFoundPage extends HTMLElement {
     `;
   }
 
-  css() {
-    return /*css*/`
+  @styles()
+  componentStyles() {
+    return css/*css*/`
       .container {
         padding: 3rem;
         text-align: center;

package/bin/templates/base/src/types/api-response.ts

@@ -0,0 +1,5 @@
+export interface ApiResponse<T> {
+  data: T;
+  error?: string;
+  loading: boolean;
+}

package/bin/templates/base/src/types/status.ts

@@ -0,0 +1 @@
+export type Status = 'idle' | 'loading' | 'success' | 'error';

package/bin/templates/base/src/types/theme.ts

@@ -0,0 +1 @@
+export type Theme = 'light' | 'dark' | 'auto';

package/bin/templates/base/src/types/user.ts

@@ -0,0 +1,5 @@
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+}

package/bin/templates/social/README.md

@@ -0,0 +1,42 @@
+# Social Media Sample App
+
+A sample social media application built with Snice showcasing various components.
+
+## Features
+
+This template demonstrates:
+
+### Components Used
+- **snice-card** - Post containers and content cards
+- **snice-avatar** - User profile pictures
+- **snice-button** - Action buttons throughout
+- **snice-badge** - Status indicators and labels
+- **snice-input** - Form inputs in settings
+- **snice-textarea** - Multi-line text input
+- **snice-switch** - Toggle settings
+- **snice-tabs** - Tabbed content on profile
+- **snice-stat** - Statistics display
+- **snice-layout-sidebar** - Sidebar navigation layout
+
+### Pages
+- **Feed** (`/`) - Social feed with posts showing cards, avatars, and badges
+- **Profile** (`/profile`) - User profile with stats and tabs
+- **Messages** (`/messages`) - Message list with avatars
+- **Settings** (`/settings`) - Settings page with forms and switches
+
+## Getting Started
+
+```bash
+npm install
+npm run dev
+```
+
+## Build for Production
+
+```bash
+npm run build
+```
+
+## Customize
+
+Feel free to modify the pages, add new components, or change the styling to fit your needs.

package/bin/templates/social/global.d.ts

@@ -0,0 +1,14 @@
+declare module '*.css' {
+  const content: string;
+  export default content;
+}
+
+declare module '*.css?inline' {
+  const content: string;
+  export default content;
+}
+
+declare module '*.html' {
+  const content: string;
+  export default content;
+}

package/bin/templates/social/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/social/package.json

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

package/bin/templates/social/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/social/src/main.ts

@@ -0,0 +1,33 @@
+import { initialize } from './router';
+import './styles/global.css';
+
+// Import theme
+import 'snice/components/theme/theme.css';
+
+// Import layout
+import 'snice/components/layout/snice-layout-sidebar';
+
+// Import snice components
+import 'snice/components/card/snice-card';
+import 'snice/components/avatar/snice-avatar';
+import 'snice/components/button/snice-button';
+import 'snice/components/badge/snice-badge';
+import 'snice/components/input/snice-input';
+import 'snice/components/textarea/snice-textarea';
+import 'snice/components/switch/snice-switch';
+import 'snice/components/tabs/snice-tabs';
+import 'snice/components/tabs/snice-tab';
+import 'snice/components/tabs/snice-tab-panel';
+import 'snice/components/stat/snice-stat';
+import 'snice/components/list/snice-list';
+import 'snice/components/nav/snice-nav';
+
+// Import pages
+import './pages/feed-page';
+import './pages/profile-page';
+import './pages/messages-page';
+import './pages/settings-page';
+import './pages/not-found-page';
+
+// Initialize router
+initialize();