zero-query 0.5.2 → 0.6.3

package/cli/commands/dev/validator.js

@@ -0,0 +1,94 @@
+/**
+ * cli/commands/dev/validator.js — JS syntax validation
+ *
+ * Pre-validates JavaScript files on save using Node's VM module.
+ * Returns structured error descriptors with code frames compatible
+ * with the browser error overlay.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const vm = require('vm');
+
+// ---------------------------------------------------------------------------
+// Code frame generator
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a code frame showing ~4 lines of context around the error
+ * with a caret pointer at the offending column.
+ *
+ * @param {string} source   — full file contents
+ * @param {number} line     — 1-based line number
+ * @param {number} column   — 1-based column number
+ * @returns {string}
+ */
+function generateCodeFrame(source, line, column) {
+  const lines = source.split('\n');
+  const start = Math.max(0, line - 4);
+  const end   = Math.min(lines.length, line + 3);
+  const pad   = String(end).length;
+  const frame = [];
+
+  for (let i = start; i < end; i++) {
+    const num    = String(i + 1).padStart(pad);
+    const marker = i === line - 1 ? '>' : ' ';
+    frame.push(`${marker} ${num} | ${lines[i]}`);
+    if (i === line - 1 && column > 0) {
+      frame.push(`  ${' '.repeat(pad)} | ${' '.repeat(column - 1)}^`);
+    }
+  }
+  return frame.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// JS validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a JavaScript file for syntax errors.
+ *
+ * Strips ESM import/export statements (preserving line numbers) so the
+ * VM can parse module-style code, then compiles via vm.Script.
+ *
+ * @param {string} filePath — absolute path to the file
+ * @param {string} relPath  — display-friendly relative path
+ * @returns {object|null}   — error descriptor, or null if valid
+ */
+function validateJS(filePath, relPath) {
+  let source;
+  try { source = fs.readFileSync(filePath, 'utf-8'); } catch { return null; }
+
+  const normalized = source.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  const stripped = normalized.split('\n').map(line => {
+    if (/^\s*import\s+.*from\s+['"]/.test(line))  return ' '.repeat(line.length);
+    if (/^\s*import\s+['"]/.test(line))            return ' '.repeat(line.length);
+    if (/^\s*export\s*\{/.test(line))              return ' '.repeat(line.length);
+    line = line.replace(/^(\s*)export\s+default\s+/, '$1');
+    line = line.replace(/^(\s*)export\s+(const|let|var|function|class|async\s+function)\s/, '$1$2 ');
+    line = line.replace(/import\.meta\.url/g, "'__meta__'");
+    line = line.replace(/import\.meta/g, '({})');
+    return line;
+  }).join('\n');
+
+  try {
+    new vm.Script(stripped, { filename: relPath });
+    return null;
+  } catch (err) {
+    const line   = err.stack ? parseInt((err.stack.match(/:(\d+)/) || [])[1]) || 0 : 0;
+    const col    = err.stack ? parseInt((err.stack.match(/:(\d+):(\d+)/) || [])[2]) || 0 : 0;
+    const frame  = line > 0 ? generateCodeFrame(source, line, col) : '';
+    return {
+      code:    'ZQ_DEV_SYNTAX',
+      type:    err.constructor.name || 'SyntaxError',
+      message: err.message,
+      file:    relPath,
+      line,
+      column:  col,
+      frame,
+    };
+  }
+}
+
+module.exports = { generateCodeFrame, validateJS };

package/cli/commands/dev/watcher.js

@@ -0,0 +1,114 @@
+/**
+ * cli/commands/dev/watcher.js — File system watcher
+ *
+ * Recursively watches the project root for file changes, validates
+ * JS files for syntax errors, and broadcasts reload / CSS hot-swap /
+ * error events through the SSE pool.
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { validateJS }                      = require('./validator');
+const { logCSS, logReload, logError }     = require('./logger');
+
+const IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', '.cache']);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function shouldWatch(filename) {
+  return !!filename && !filename.startsWith('.');
+}
+
+function isIgnored(filepath) {
+  return filepath.split(path.sep).some(p => IGNORE_DIRS.has(p));
+}
+
+/** Recursively collect every directory under `dir` (excluding ignored). */
+function collectWatchDirs(dir) {
+  const dirs = [dir];
+  try {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || IGNORE_DIRS.has(entry.name)) continue;
+      dirs.push(...collectWatchDirs(path.join(dir, entry.name)));
+    }
+  } catch { /* unreadable dir — skip */ }
+  return dirs;
+}
+
+// ---------------------------------------------------------------------------
+// Watcher factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Start watching `root` for file changes.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.root  — absolute project root
+ * @param {SSEPool} opts.pool  — SSE broadcast pool
+ * @returns {{ dirs: string[], destroy: Function }}
+ */
+function startWatcher({ root, pool }) {
+  const watchDirs = collectWatchDirs(root);
+  const watchers  = [];
+
+  let debounceTimer;
+  let currentError = null;   // track which file has an active error
+
+  for (const dir of watchDirs) {
+    try {
+      const watcher = fs.watch(dir, (_, filename) => {
+        if (!shouldWatch(filename)) return;
+        const fullPath = path.join(dir, filename || '');
+        if (isIgnored(fullPath)) return;
+
+        clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+          const rel = path.relative(root, fullPath).replace(/\\/g, '/');
+          const ext = path.extname(filename).toLowerCase();
+
+          // ---- CSS hot-swap ----
+          if (ext === '.css') {
+            logCSS(rel);
+            pool.broadcast('css', rel);
+            return;
+          }
+
+          // ---- JS syntax check ----
+          if (ext === '.js') {
+            const err = validateJS(fullPath, rel);
+            if (err) {
+              currentError = rel;
+              logError(err);
+              pool.broadcast('error:syntax', JSON.stringify(err));
+              return;
+            }
+            // File was fixed — clear previous overlay
+            if (currentError === rel) {
+              currentError = null;
+              pool.broadcast('error:clear', '');
+            }
+          }
+
+          // ---- Full reload ----
+          logReload(rel);
+          pool.broadcast('reload', rel);
+        }, 100);
+      });
+      watchers.push(watcher);
+    } catch { /* dir became inaccessible — skip */ }
+  }
+
+  function destroy() {
+    clearTimeout(debounceTimer);
+    watchers.forEach(w => w.close());
+  }
+
+  return { dirs: watchDirs, destroy };
+}
+
+module.exports = { startWatcher, collectWatchDirs };

package/cli/scaffold/scripts/components/about.js

@@ -46,6 +46,18 @@ $.component('about-page', {
             <strong>$.component()</strong>
             <span>Reactive components with state, lifecycle hooks, and template rendering</span>
           </div>
+          <div class="feature-item">
+            <strong>computed / watch</strong>
+            <span>Derived state properties and reactive watchers on the counter page</span>
+          </div>
+          <div class="feature-item">
+            <strong>DOM Diffing</strong>
+            <span>Efficient <code>morph()</code> engine patches only changed DOM nodes on re-render</span>
+          </div>
+          <div class="feature-item">
+            <strong>z-key</strong>
+            <span>Keyed list reconciliation in z-for loops (todos, counter history, contacts)</span>
+          </div>
           <div class="feature-item">
             <strong>$.router()</strong>
             <span>SPA routing with history mode, z-link navigation, and fallback pages</span>
@@ -79,8 +91,8 @@ $.component('about-page', {
             <span>Safe rendering of user-generated and API content</span>
           </div>
           <div class="feature-item">
-            <strong>$.uuid()</strong>
-            <span>Unique ID generation for new todo items</span>
+            <strong>CSP-safe expressions</strong>
+            <span>Template expressions evaluated without <code>eval()</code> or <code>new Function()</code></span>
           </div>
           <div class="feature-item">
             <strong>z-model / z-ref</strong>

package/cli/scaffold/scripts/components/contacts/contacts.html

@@ -13,7 +13,7 @@
   <h1>Contacts</h1>
   <p class="subtitle">
     External template &amp; styles via <code>templateUrl</code> / <code>styleUrl</code>.
-    Directives: <code>z-if</code>, <code>z-for</code>, <code>z-show</code>,
+    Directives: <code>z-if</code>, <code>z-for</code> + <code>z-key</code>, <code>z-show</code>,
     <code>z-bind</code>, <code>z-class</code>, <code>z-model</code>, and more.
   </p>
 </div>
@@ -73,6 +73,7 @@
   <ul class="contacts-list">
     <li
       z-for="contact in contacts"
+      z-key="{{contact.id}}"
       class="contacts-item {{contact.id === selectedId ? 'selected' : ''}} {{contact.favorite ? 'is-favorite' : ''}}"
       @click="selectContact({{contact.id}})"
     >
@@ -111,15 +112,15 @@
 <div class="card contact-detail" z-if="selectedId !== null">
   <div class="detail-header">
     <div>
-      <h3 z-text="contacts.find(c => c.id === selectedId)?.name || ''"></h3>
-      <p class="muted" z-text="contacts.find(c => c.id === selectedId)?.email || ''"></p>
+      <h3 z-text="selectedName"></h3>
+      <p class="muted" z-text="selectedEmail"></p>
     </div>
     <div class="detail-actions">
       <button
         class="btn btn-outline btn-sm"
         @click="cycleStatus({{selectedId}})"
       >
-        Status: <span z-text="contacts.find(c => c.id === selectedId)?.status || ''"></span>
+        Status: <span z-text="selectedStatus"></span>
       </button>
 
       <!-- Confirm delete pattern using z-if / z-else -->

package/cli/scaffold/scripts/components/contacts/contacts.js

@@ -23,6 +23,9 @@ $.component('contacts-page', {
     nameError: '',
     emailError: '',
     selectedId: null,
+    selectedName: '',
+    selectedEmail: '',
+    selectedStatus: '',
     confirmDeleteId: null,
     totalAdded: 0,
     favoriteCount: 0,
@@ -42,6 +45,7 @@ $.component('contacts-page', {
     this.state.contacts      = store.state.contacts;
     this.state.totalAdded    = store.state.contactsAdded;
     this.state.favoriteCount = store.getters.favoriteCount;
+    this._syncSelected();
   },
 
   // -- Actions --
@@ -101,8 +105,10 @@ $.component('contacts-page', {
   },
 
   selectContact(id) {
-    this.state.selectedId = this.state.selectedId === Number(id) ? null : Number(id);
+    const numId = Number(id);
+    this.state.selectedId = this.state.selectedId === numId ? null : numId;
     this.state.confirmDeleteId = null;
+    this._syncSelected();
   },
 
   confirmDelete(id) {
@@ -125,6 +131,16 @@ $.component('contacts-page', {
 
   cycleStatus(id) {
     $.getStore('main').dispatch('cycleContactStatus', Number(id));
+    this._syncSelected();
+  },
+
+  _syncSelected() {
+    const c = this.state.selectedId != null
+      ? this.state.contacts.find(c => c.id === this.state.selectedId)
+      : null;
+    this.state.selectedName   = c ? c.name : '';
+    this.state.selectedEmail  = c ? c.email : '';
+    this.state.selectedStatus = c ? c.status : '';
   },
 
   _clearForm() {

package/cli/scaffold/scripts/components/counter.js

@@ -1,8 +1,9 @@
 // scripts/components/counter.js — interactive counter
 //
-// Demonstrates: component state, instance methods, @click event binding,
-//               z-model two-way binding with z-number modifier, z-class,
-//               z-if, z-for, $.bus toast notifications
+// Demonstrates: component state, computed properties, watch callbacks,
+//               @click event binding, z-model two-way binding with
+//               z-number modifier, z-class, z-if, z-for with z-key,
+//               $.bus toast notifications
 
 $.component('counter-page', {
   state: () => ({
@@ -11,16 +12,35 @@ $.component('counter-page', {
     history: [],
   }),
 
+  // Computed properties — derived values that update automatically
+  computed: {
+    isNegative: (state) => state.count < 0,
+    historyCount: (state) => state.history.length,
+    lastAction: (state) => state.history.length ? state.history[state.history.length - 1] : null,
+  },
+
+  // Watch — react to specific state changes
+  watch: {
+    count(val) {
+      if (val === 100) $.bus.emit('toast', { message: 'Century! 🎉', type: 'success' });
+      if (val === -100) $.bus.emit('toast', { message: 'Negative century!', type: 'error' });
+    },
+  },
+
   increment() {
     this.state.count += this.state.step;
-    this.state.history.push({ action: '+', value: this.state.step, result: this.state.count });
-    if (this.state.history.length > 8) this.state.history.shift();
+    this._pushHistory('+', this.state.step, this.state.count);
   },
 
   decrement() {
     this.state.count -= this.state.step;
-    this.state.history.push({ action: '−', value: this.state.step, result: this.state.count });
-    if (this.state.history.length > 8) this.state.history.shift();
+    this._pushHistory('−', this.state.step, this.state.count);
+  },
+
+  _pushHistory(action, value, result) {
+    const raw = this.state.history.__raw || this.state.history;
+    const next = [...raw, { id: Date.now(), action, value, result }];
+    this.state.history = next.length > 8 ? next.slice(-8) : next;
   },
 
   reset() {
@@ -33,7 +53,7 @@ $.component('counter-page', {
     return `
       <div class="page-header">
         <h1>Counter</h1>
-        <p class="subtitle">Component state, <code>@click</code> handlers, <code>z-model</code>, <code>z-class</code>, and <code>z-for</code>.</p>
+        <p class="subtitle"><code>computed</code>, <code>watch</code>, <code>@click</code>, <code>z-model</code>, <code>z-class</code>, and <code>z-for</code> with <code>z-key</code>.</p>
       </div>
 
       <div class="card counter-card">
@@ -55,9 +75,9 @@ $.component('counter-page', {
       </div>
 
       <div class="card card-muted" z-if="history.length > 0">
-        <h3>History</h3>
+        <h3>History <small style="color:var(--text-muted);font-weight:400;">(${this.computed.historyCount} entries)</small></h3>
         <div class="history-list">
-          <span z-for="e in history" class="history-item">{{e.action}}{{e.value}} → <strong>{{e.result}}</strong></span>
+          <span z-for="e in history" z-key="{{e.id}}" class="history-item">{{e.action}}{{e.value}} → <strong>{{e.result}}</strong></span>
         </div>
       </div>
     `;

package/cli/scaffold/scripts/components/home.js

@@ -62,19 +62,19 @@ $.component('home-page', {
 
         <div class="card">
           <h3>🔢 Counter</h3>
-          <p>Component state, two-way binding with <code>z-model</code>, and event handling.</p>
+          <p><code>computed</code> properties, <code>watch</code> callbacks, and <code>z-for</code> with <code>z-key</code> diffing.</p>
           <a z-link="/counter" class="btn btn-outline">Try It →</a>
         </div>
 
         <div class="card">
           <h3>✅ Todos</h3>
-          <p>Global store with actions & getters. <strong>${store.getters.todoCount}</strong> items, <strong>${store.getters.doneCount}</strong> done.</p>
+          <p>Global store, <code>z-key</code> keyed lists, DOM diffing. <strong>${store.getters.todoCount}</strong> items, <strong>${store.getters.doneCount}</strong> done.</p>
           <a z-link="/todos" class="btn btn-outline">Try It →</a>
         </div>
 
         <div class="card">
           <h3>📇 Contacts</h3>
-          <p>External templates &amp; styles via <code>templateUrl</code> / <code>styleUrl</code>. <strong>${store.getters.contactCount}</strong> contacts, <strong>${store.getters.favoriteCount}</strong> ★ favorited.</p>
+          <p>External templates, scoped styles, and <code>z-key</code> keyed lists. <strong>${store.getters.contactCount}</strong> contacts, <strong>${store.getters.favoriteCount}</strong> ★ favorited.</p>
           <a z-link="/contacts" class="btn btn-outline">Try It →</a>
         </div>
 

package/cli/scaffold/scripts/components/todos.js

@@ -1,9 +1,10 @@
 // scripts/components/todos.js — todo list with global store
 //
 // Demonstrates: $.getStore, store.dispatch, store.subscribe,
-//               store getters, z-model, z-ref, z-class, z-for,
-//               z-if, z-show, @click with args, @submit.prevent,
-//               mounted/destroyed lifecycle, $.bus toast, $.debounce
+//               store getters, computed properties, z-model, z-ref,
+//               z-class, z-for with z-key, z-if, z-show, @click
+//               with args, @submit.prevent, mounted/destroyed
+//               lifecycle, $.bus toast, $.debounce
 
 $.component('todos-page', {
   state: () => ({
@@ -83,7 +84,7 @@ $.component('todos-page', {
     return `
       <div class="page-header">
         <h1>Todos</h1>
-        <p class="subtitle">Global store with <code>$.store()</code>, <code>z-for</code>, <code>z-class</code>, <code>z-if</code>, and <code>z-show</code>.</p>
+        <p class="subtitle">Global store with <code>$.store()</code>, <code>z-for</code> + <code>z-key</code>, <code>z-class</code>, <code>z-if</code>, and <code>z-show</code>.</p>
       </div>
 
       <div class="card">
@@ -114,7 +115,7 @@ $.component('todos-page', {
         </div>
 
         <ul z-else class="todo-list">
-          <li z-for="t in filtered" class="todo-item {{t.done ? 'done' : ''}}">
+          <li z-for="t in filtered" z-key="{{t.id}}" class="todo-item {{t.done ? 'done' : ''}}">
             <button class="todo-check" @click="toggleTodo('{{t.id}}')"></button>
             <span class="todo-text">{{$.escapeHtml(t.text)}}</span>
             <button class="todo-remove" @click="removeTodo('{{t.id}}')">✕</button>