lean-spec 0.2.5 → 0.2.6-dev.20251125015611

package/templates/examples/api-refactor/src/services/weatherService.js

@@ -0,0 +1,42 @@
+import fetch from 'node-fetch';
+
+/**
+ * Get weather for a city
+ * 
+ * PROBLEM: This function has HTTP logic mixed with business logic
+ * - Manual fetch calls
+ * - Manual error handling
+ * - Manual JSON parsing
+ * - No retry logic
+ * - Hard to test (can't mock HTTP)
+ */
+export async function getWeather(city) {
+  // Mock API endpoint (replace with real API in production)
+  const url = `https://api.weatherapi.com/v1/current.json?key=mock&q=${city}`;
+  
+  try {
+    const response = await fetch(url);
+    
+    if (!response.ok) {
+      throw new Error(`Weather API error: ${response.status}`);
+    }
+    
+    const data = await response.json();
+    
+    // Business logic: Transform API response to our format
+    return {
+      city: data.location?.name || city,
+      temp: data.current?.temp_c || Math.floor(Math.random() * 30),
+      condition: data.current?.condition?.text || 'Sunny',
+      humidity: data.current?.humidity || Math.floor(Math.random() * 100),
+    };
+  } catch (error) {
+    // For demo, return mock data on error
+    return {
+      city,
+      temp: Math.floor(Math.random() * 30),
+      condition: 'Sunny (mock data)',
+      humidity: Math.floor(Math.random() * 100),
+    };
+  }
+}

package/templates/examples/dark-theme/README.md

@@ -0,0 +1,66 @@
+# Dark Theme Demo
+
+> **Tutorial**: [Adding Dark Theme Support](https://leanspec.dev/docs/tutorials/adding-dark-theme)
+
+## Scenario
+
+You're building a professional admin dashboard for a SaaS product. The dashboard looks modern and works great, but users keep requesting a dark mode option for late-night monitoring sessions and to reduce eye strain during extended use. Currently, the dashboard only has a bright light theme.
+
+## What's Here
+
+A professional admin dashboard with:
+- Interactive data visualization with charts (Chart.js)
+- Real-time statistics cards with animations
+- Sidebar navigation and top bar
+- Activity feed with recent events
+- Responsive layout
+- Clean, modern light theme
+- No dark mode support (yet!)
+
+**Files:**
+- `src/server.js` - Express server for static files
+- `src/public/index.html` - Dashboard interface with sidebar, charts, and stats
+- `src/public/style.css` - Current light theme styles (CSS custom properties ready)
+- `src/public/app.js` - Dashboard logic, chart initialization, and animations
+
+## Getting Started
+
+```bash
+# Install dependencies
+npm install
+
+# Start the server
+npm start
+
+# Open in your browser:
+# http://localhost:3000
+```
+
+## Your Mission
+
+Add dark theme support with automatic switching based on system preferences. Follow the tutorial and ask your AI assistant:
+
+> "Help me add dark theme support to this admin dashboard using LeanSpec. It should automatically switch based on the user's system theme preference."
+
+The AI will guide you through:
+1. Creating a spec for dark theme support
+2. Designing CSS custom properties for dark mode colors
+3. Implementing the `@media (prefers-color-scheme: dark)` query
+4. Ensuring charts adapt to the theme
+5. Testing the theme switching
+
+## Current Limitations
+
+- Only light theme available
+- No manual theme toggle
+- Chart colors don't adapt to theme
+- No theme persistence across sessions
+
+These are perfect opportunities to practice spec-driven development!
+
+## Tech Stack
+
+- **Frontend**: Vanilla HTML, CSS, JavaScript
+- **Charts**: Chart.js 4.4.0
+- **Backend**: Express.js (serving static files)
+- **Styling**: CSS Custom Properties (CSS Variables)

package/templates/examples/dark-theme/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "dark-theme-demo",
+  "version": "1.0.0",
+  "description": "Professional admin dashboard for LeanSpec Dark Theme Tutorial",
+  "type": "module",
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch src/server.js"
+  },
+  "keywords": ["leanspec", "tutorial", "demo", "dashboard", "admin"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "express": "^4.18.2"
+  }
+}

package/templates/examples/dark-theme/src/public/app.js

@@ -0,0 +1,277 @@
+// Admin Dashboard - Interactive data visualization
+// This is a starting point for adding dark theme support
+
+// ============================================
+// Initialize Charts
+// ============================================
+
+function initializeCharts() {
+  // Revenue Chart
+  const revenueCtx = document.getElementById('revenueChart');
+  if (revenueCtx) {
+    new Chart(revenueCtx, {
+      type: 'line',
+      data: {
+        labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+        datasets: [{
+          label: 'Revenue',
+          data: [4200, 5100, 4800, 6200, 5800, 7100, 6500],
+          borderColor: '#0066cc',
+          backgroundColor: 'rgba(0, 102, 204, 0.1)',
+          borderWidth: 2,
+          tension: 0.4,
+          fill: true,
+          pointBackgroundColor: '#0066cc',
+          pointBorderColor: '#fff',
+          pointBorderWidth: 2,
+          pointRadius: 4,
+          pointHoverRadius: 6
+        }]
+      },
+      options: {
+        responsive: true,
+        maintainAspectRatio: false,
+        plugins: {
+          legend: {
+            display: false
+          },
+          tooltip: {
+            backgroundColor: 'rgba(0, 0, 0, 0.8)',
+            padding: 12,
+            borderRadius: 8,
+            titleColor: '#fff',
+            bodyColor: '#fff',
+            callbacks: {
+              label: function(context) {
+                return '$' + context.parsed.y.toLocaleString();
+              }
+            }
+          }
+        },
+        scales: {
+          y: {
+            beginAtZero: true,
+            grid: {
+              color: 'rgba(0, 0, 0, 0.05)'
+            },
+            ticks: {
+              callback: function(value) {
+                return '$' + value.toLocaleString();
+              }
+            }
+          },
+          x: {
+            grid: {
+              display: false
+            }
+          }
+        }
+      }
+    });
+  }
+
+  // Traffic Chart
+  const trafficCtx = document.getElementById('trafficChart');
+  if (trafficCtx) {
+    new Chart(trafficCtx, {
+      type: 'doughnut',
+      data: {
+        labels: ['Organic', 'Direct', 'Social', 'Referral'],
+        datasets: [{
+          data: [42, 28, 18, 12],
+          backgroundColor: [
+            '#0066cc',
+            '#00a854',
+            '#7c3aed',
+            '#ff8c00'
+          ],
+          borderWidth: 0,
+          hoverOffset: 8
+        }]
+      },
+      options: {
+        responsive: true,
+        maintainAspectRatio: false,
+        plugins: {
+          legend: {
+            position: 'bottom',
+            labels: {
+              padding: 16,
+              usePointStyle: true,
+              pointStyle: 'circle',
+              font: {
+                size: 12
+              }
+            }
+          },
+          tooltip: {
+            backgroundColor: 'rgba(0, 0, 0, 0.8)',
+            padding: 12,
+            borderRadius: 8,
+            titleColor: '#fff',
+            bodyColor: '#fff',
+            callbacks: {
+              label: function(context) {
+                return context.label + ': ' + context.parsed + '%';
+              }
+            }
+          }
+        }
+      }
+    });
+  }
+}
+
+// ============================================
+// Animate Stats on Load
+// ============================================
+
+function animateValue(element, start, end, duration) {
+  const range = end - start;
+  const increment = range / (duration / 16);
+  let current = start;
+  
+  const timer = setInterval(() => {
+    current += increment;
+    if ((increment > 0 && current >= end) || (increment < 0 && current <= end)) {
+      element.textContent = formatStatValue(end);
+      clearInterval(timer);
+    } else {
+      element.textContent = formatStatValue(Math.floor(current));
+    }
+  }, 16);
+}
+
+function formatStatValue(value) {
+  if (value >= 1000) {
+    return value.toLocaleString();
+  }
+  return value.toString();
+}
+
+function animateStats() {
+  const stats = [
+    { id: 'totalUsers', value: 2847 },
+    { id: 'revenue', value: 45231, prefix: '$' },
+    { id: 'completedTasks', value: 892 },
+    { id: 'activeProjects', value: 24 }
+  ];
+  
+  stats.forEach(stat => {
+    const element = document.getElementById(stat.id);
+    if (element) {
+      if (stat.prefix) {
+        const originalText = element.textContent;
+        element.textContent = stat.prefix + '0';
+        animateValue(element, 0, stat.value, 1000);
+        const timer = setInterval(() => {
+          if (element.textContent !== stat.prefix + '0') {
+            const currentVal = element.textContent.replace(/[^0-9]/g, '');
+            element.textContent = stat.prefix + Number(currentVal).toLocaleString();
+          }
+        }, 16);
+        setTimeout(() => clearInterval(timer), 1000);
+      } else {
+        element.textContent = '0';
+        animateValue(element, 0, stat.value, 1000);
+      }
+    }
+  });
+}
+
+// ============================================
+// Recent Activity
+// ============================================
+
+function loadRecentActivity() {
+  const activities = [
+    {
+      type: 'user',
+      title: 'New user registration',
+      description: 'Sarah Johnson joined the platform',
+      time: '5 minutes ago',
+      icon: `<svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+        <path d="M10 11C12.2091 11 14 9.20914 14 7C14 4.79086 12.2091 3 10 3C7.79086 3 6 4.79086 6 7C6 9.20914 7.79086 11 10 11Z" stroke="currentColor" stroke-width="2"/>
+        <path d="M3 17C3 14.2386 5.23858 12 8 12H12C14.7614 12 17 14.2386 17 17" stroke="currentColor" stroke-width="2"/>
+      </svg>`
+    },
+    {
+      type: 'report',
+      title: 'Monthly report generated',
+      description: 'Q4 2024 performance summary is ready',
+      time: '1 hour ago',
+      icon: `<svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+        <rect x="3" y="3" width="14" height="14" rx="2" stroke="currentColor" stroke-width="2"/>
+        <path d="M7 8H13M7 12H10" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+      </svg>`
+    },
+    {
+      type: 'alert',
+      title: 'Server capacity warning',
+      description: 'CPU usage exceeded 80% threshold',
+      time: '3 hours ago',
+      icon: `<svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+        <path d="M10 6V10M10 14H10.01M10 18C14.4183 18 18 14.4183 18 10C18 5.58172 14.4183 2 10 2C5.58172 2 2 5.58172 2 10C2 14.4183 5.58172 18 10 18Z" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+      </svg>`
+    },
+    {
+      type: 'user',
+      title: 'Team member added',
+      description: 'Michael Chen joined the Development team',
+      time: '5 hours ago',
+      icon: `<svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+        <path d="M10 11C12.2091 11 14 9.20914 14 7C14 4.79086 12.2091 3 10 3C7.79086 3 6 4.79086 6 7C6 9.20914 7.79086 11 10 11Z" stroke="currentColor" stroke-width="2"/>
+        <path d="M3 17C3 14.2386 5.23858 12 8 12H12C14.7614 12 17 14.2386 17 17" stroke="currentColor" stroke-width="2"/>
+      </svg>`
+    },
+    {
+      type: 'report',
+      title: 'Backup completed',
+      description: 'Database backup finished successfully',
+      time: '8 hours ago',
+      icon: `<svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+        <path d="M3 12L9 18L21 6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+      </svg>`
+    }
+  ];
+  
+  const activityList = document.getElementById('activityList');
+  if (activityList) {
+    activityList.innerHTML = activities.map(activity => `
+      <div class="activity-item">
+        <div class="activity-icon ${activity.type}">
+          ${activity.icon}
+        </div>
+        <div class="activity-content">
+          <div class="activity-title">${activity.title}</div>
+          <div class="activity-description">${activity.description}</div>
+          <div class="activity-time">${activity.time}</div>
+        </div>
+      </div>
+    `).join('');
+  }
+}
+
+// ============================================
+// Initialize Dashboard
+// ============================================
+
+document.addEventListener('DOMContentLoaded', () => {
+  // Initialize all components
+  animateStats();
+  initializeCharts();
+  loadRecentActivity();
+  
+  // Add subtle hover effects
+  document.querySelectorAll('.stat-card').forEach(card => {
+    card.addEventListener('mouseenter', (e) => {
+      e.currentTarget.style.transform = 'translateY(-4px)';
+    });
+    card.addEventListener('mouseleave', (e) => {
+      e.currentTarget.style.transform = 'translateY(0)';
+    });
+  });
+  
+  console.log('✓ Dashboard initialized');
+  console.log('💡 Try adding dark theme support with CSS custom properties!');
+});

package/templates/examples/dark-theme/src/public/index.html

@@ -0,0 +1,225 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Admin Dashboard</title>
+  <link rel="stylesheet" href="style.css">
+  <script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0"></script>
+</head>
+<body>
+  <!-- Sidebar Navigation -->
+  <aside class="sidebar">
+    <div class="sidebar-header">
+      <div class="logo">
+        <svg width="32" height="32" viewBox="0 0 32 32" fill="none">
+          <rect width="32" height="32" rx="8" fill="currentColor" opacity="0.2"/>
+          <path d="M16 8L24 12V20L16 24L8 20V12L16 8Z" fill="currentColor"/>
+        </svg>
+        <span class="logo-text">AdminPro</span>
+      </div>
+    </div>
+    
+    <nav class="sidebar-nav">
+      <a href="#" class="nav-item active">
+        <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+          <rect x="3" y="3" width="6" height="6" rx="1" stroke="currentColor" stroke-width="2"/>
+          <rect x="11" y="3" width="6" height="6" rx="1" stroke="currentColor" stroke-width="2"/>
+          <rect x="3" y="11" width="6" height="6" rx="1" stroke="currentColor" stroke-width="2"/>
+          <rect x="11" y="11" width="6" height="6" rx="1" stroke="currentColor" stroke-width="2"/>
+        </svg>
+        <span>Dashboard</span>
+      </a>
+      <a href="#" class="nav-item">
+        <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+          <path d="M10 11C12.2091 11 14 9.20914 14 7C14 4.79086 12.2091 3 10 3C7.79086 3 6 4.79086 6 7C6 9.20914 7.79086 11 10 11Z" stroke="currentColor" stroke-width="2"/>
+          <path d="M3 17C3 14.2386 5.23858 12 8 12H12C14.7614 12 17 14.2386 17 17" stroke="currentColor" stroke-width="2"/>
+        </svg>
+        <span>Users</span>
+      </a>
+      <a href="#" class="nav-item">
+        <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+          <path d="M3 6H17M3 10H17M3 14H17" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+        </svg>
+        <span>Analytics</span>
+      </a>
+      <a href="#" class="nav-item">
+        <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+          <rect x="3" y="3" width="14" height="14" rx="2" stroke="currentColor" stroke-width="2"/>
+          <path d="M7 8H13M7 12H10" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+        </svg>
+        <span>Reports</span>
+      </a>
+      <a href="#" class="nav-item">
+        <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+          <circle cx="10" cy="10" r="3" stroke="currentColor" stroke-width="2"/>
+          <path d="M10 3V5M10 15V17M17 10H15M5 10H3M15.364 4.636L13.95 6.05M6.05 13.95L4.636 15.364M15.364 15.364L13.95 13.95M6.05 6.05L4.636 4.636" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+        </svg>
+        <span>Settings</span>
+      </a>
+    </nav>
+
+    <div class="sidebar-footer">
+      <div class="user-profile">
+        <div class="avatar">JD</div>
+        <div class="user-info">
+          <div class="user-name">John Doe</div>
+          <div class="user-role">Administrator</div>
+        </div>
+      </div>
+    </div>
+  </aside>
+
+  <!-- Main Content -->
+  <main class="main-content">
+    <!-- Top Bar -->
+    <header class="top-bar">
+      <div class="search-bar">
+        <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+          <circle cx="9" cy="9" r="6" stroke="currentColor" stroke-width="2"/>
+          <path d="M13.5 13.5L17 17" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+        </svg>
+        <input type="text" placeholder="Search..." />
+      </div>
+      
+      <div class="top-bar-actions">
+        <button class="icon-button" title="Notifications">
+          <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+            <path d="M10 3C7.79086 3 6 4.79086 6 7V10L4 12V14H16V12L14 10V7C14 4.79086 12.2091 3 10 3Z" stroke="currentColor" stroke-width="2"/>
+            <path d="M8 14V15C8 16.1046 8.89543 17 10 17C11.1046 17 12 16.1046 12 15V14" stroke="currentColor" stroke-width="2"/>
+          </svg>
+          <span class="badge">3</span>
+        </button>
+        <button class="icon-button" title="Messages">
+          <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+            <path d="M17 10C17 13.866 13.866 17 10 17C8.87809 17 7.82343 16.7223 6.89743 16.2334L3 17L3.76661 13.1026C3.27766 12.1766 3 11.1219 3 10C3 6.13401 6.13401 3 10 3C13.866 3 17 6.13401 17 10Z" stroke="currentColor" stroke-width="2"/>
+          </svg>
+        </button>
+      </div>
+    </header>
+
+    <!-- Dashboard Content -->
+    <div class="dashboard-content">
+      <!-- Page Header -->
+      <div class="page-header">
+        <div>
+          <h1>Dashboard Overview</h1>
+          <p class="page-subtitle">Welcome back! Here's what's happening today.</p>
+        </div>
+        <button class="btn-primary">
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
+            <path d="M8 3V13M3 8H13" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+          </svg>
+          New Report
+        </button>
+      </div>
+
+      <!-- Stats Grid -->
+      <div class="stats-grid">
+        <div class="stat-card">
+          <div class="stat-header">
+            <div class="stat-icon blue">
+              <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
+                <path d="M17 21V19C17 17.9391 16.5786 16.9217 15.8284 16.1716C15.0783 15.4214 14.0609 15 13 15H5C3.93913 15 2.92172 15.4214 2.17157 16.1716C1.42143 16.9217 1 17.9391 1 19V21" stroke="currentColor" stroke-width="2"/>
+                <circle cx="9" cy="7" r="4" stroke="currentColor" stroke-width="2"/>
+                <path d="M23 21V19C22.9993 18.1137 22.7044 17.2528 22.1614 16.5523C21.6184 15.8519 20.8581 15.3516 20 15.13" stroke="currentColor" stroke-width="2"/>
+                <path d="M16 3.13C16.8604 3.35031 17.623 3.85071 18.1676 4.55232C18.7122 5.25392 19.0078 6.11683 19.0078 7.005C19.0078 7.89318 18.7122 8.75608 18.1676 9.45769C17.623 10.1593 16.8604 10.6597 16 10.88" stroke="currentColor" stroke-width="2"/>
+              </svg>
+            </div>
+            <span class="stat-change positive">↑ 12%</span>
+          </div>
+          <div class="stat-content">
+            <h3 class="stat-value" id="totalUsers">2,847</h3>
+            <p class="stat-label">Total Users</p>
+          </div>
+        </div>
+
+        <div class="stat-card">
+          <div class="stat-header">
+            <div class="stat-icon green">
+              <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
+                <path d="M12 2V6M12 18V22M4.93 4.93L7.76 7.76M16.24 16.24L19.07 19.07M2 12H6M18 12H22M4.93 19.07L7.76 16.24M16.24 7.76L19.07 4.93" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+                <circle cx="12" cy="12" r="3" stroke="currentColor" stroke-width="2"/>
+              </svg>
+            </div>
+            <span class="stat-change positive">↑ 8%</span>
+          </div>
+          <div class="stat-content">
+            <h3 class="stat-value" id="revenue">$45,231</h3>
+            <p class="stat-label">Revenue</p>
+          </div>
+        </div>
+
+        <div class="stat-card">
+          <div class="stat-header">
+            <div class="stat-icon purple">
+              <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
+                <path d="M3 12L9 18L21 6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+              </svg>
+            </div>
+            <span class="stat-change positive">↑ 23%</span>
+          </div>
+          <div class="stat-content">
+            <h3 class="stat-value" id="completedTasks">892</h3>
+            <p class="stat-label">Completed Tasks</p>
+          </div>
+        </div>
+
+        <div class="stat-card">
+          <div class="stat-header">
+            <div class="stat-icon orange">
+              <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
+                <path d="M13 2L3 14H12L11 22L21 10H12L13 2Z" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+              </svg>
+            </div>
+            <span class="stat-change negative">↓ 4%</span>
+          </div>
+          <div class="stat-content">
+            <h3 class="stat-value" id="activeProjects">24</h3>
+            <p class="stat-label">Active Projects</p>
+          </div>
+        </div>
+      </div>
+
+      <!-- Charts Row -->
+      <div class="charts-row">
+        <div class="chart-card">
+          <div class="chart-header">
+            <h3>Revenue Overview</h3>
+            <select class="chart-period">
+              <option>Last 7 days</option>
+              <option>Last 30 days</option>
+              <option>Last 90 days</option>
+            </select>
+          </div>
+          <canvas id="revenueChart"></canvas>
+        </div>
+
+        <div class="chart-card">
+          <div class="chart-header">
+            <h3>Traffic Sources</h3>
+            <select class="chart-period">
+              <option>This month</option>
+              <option>Last month</option>
+            </select>
+          </div>
+          <canvas id="trafficChart"></canvas>
+        </div>
+      </div>
+
+      <!-- Recent Activity -->
+      <div class="activity-section">
+        <div class="section-header">
+          <h3>Recent Activity</h3>
+          <a href="#" class="view-all">View All →</a>
+        </div>
+        <div class="activity-list" id="activityList">
+          <!-- Activity items will be populated by JavaScript -->
+        </div>
+      </div>
+    </div>
+  </main>
+
+  <script src="app.js"></script>
+</body>
+</html>