zero-query 0.4.9 → 0.6.3

package/cli/commands/{dev.js → dev.old.js}

@@ -321,10 +321,13 @@ function devServer() {
 
   const { createApp, static: serveStatic } = zeroHttp;
 
+  // Custom HTML entry file (default: index.html)
+  const htmlEntry = option('index', 'i', 'index.html');
+
   // Determine the project root to serve
   let root = null;
   for (let i = 1; i < args.length; i++) {
-    if (!args[i].startsWith('-') && args[i - 1] !== '-p' && args[i - 1] !== '--port') {
+    if (!args[i].startsWith('-') && args[i - 1] !== '-p' && args[i - 1] !== '--port' && args[i - 1] !== '--index') {
       root = path.resolve(process.cwd(), args[i]);
       break;
     }
@@ -336,7 +339,7 @@ function devServer() {
       path.join(process.cwd(), 'src'),
     ];
     for (const c of candidates) {
-      if (fs.existsSync(path.join(c, 'index.html'))) { root = c; break; }
+      if (fs.existsSync(path.join(c, htmlEntry))) { root = c; break; }
     }
     if (!root) root = process.cwd();
   }
@@ -389,9 +392,9 @@ function devServer() {
       res.status(404).send('Not Found');
       return;
     }
-    const indexPath = path.join(root, 'index.html');
+    const indexPath = path.join(root, htmlEntry);
     if (!fs.existsSync(indexPath)) {
-      res.status(404).send('index.html not found');
+      res.status(404).send(`${htmlEntry} not found`);
       return;
     }
     let html = fs.readFileSync(indexPath, 'utf-8');
@@ -495,6 +498,7 @@ function devServer() {
     console.log(`  \x1b[2m${'-'.repeat(40)}\x1b[0m`);
     console.log(`  Local:       \x1b[36mhttp://localhost:${PORT}/\x1b[0m`);
     console.log(`  Root:        ${path.relative(process.cwd(), root) || '.'}`);
+    if (htmlEntry !== 'index.html') console.log(`  HTML:        \x1b[36m${htmlEntry}\x1b[0m`);
     console.log(`  Live Reload: \x1b[32menabled\x1b[0m (SSE)`);
     console.log(`  Overlay:     \x1b[32menabled\x1b[0m (syntax + runtime errors)`);
     if (noIntercept) console.log(`  Intercept:   \x1b[33mdisabled\x1b[0m (--no-intercept)`);

package/cli/help.js

@@ -12,6 +12,7 @@ function showHelp() {
 
     dev [root]                 Start a dev server with live-reload
       --port, -p <number>     Port number (default: 3100)
+      --index, -i <file>        Index HTML file (default: index.html)
       --no-intercept           Disable auto-resolution of zquery.min.js
                                (serve the on-disk vendor copy instead)
 
@@ -20,9 +21,10 @@ function showHelp() {
                                overlay in the browser. Runtime errors and
                                unhandled rejections are also captured.
 
-    bundle [dir]              Bundle app ES modules into a single file
-      --out, -o <path>         Output directory (default: dist/ next to index.html)
-      --html <file>            Use a specific HTML file (default: auto-detected)
+    bundle [dir|file]          Bundle app ES modules into a single file
+      --out, -o <path>         Output directory (default: dist/ next to HTML file)
+      --index, -i <file>        Index HTML file (default: auto-detected)
+      --minimal, -m            Only output HTML + bundled JS (skip static assets)
 
     build                      Build the zQuery library \u2192 dist/      --watch, -w              Watch src/ and rebuild on changes                               (must be run from the project root where src/ lives)
 
@@ -34,9 +36,10 @@ function showHelp() {
         2. Within HTML: module script pointing to app.js, else first module script
         3. JS scan: $.router( first (entry point), then $.mount( / $.store(
         4. Convention fallbacks (scripts/app.js, app.js, etc.)
-      \u2022 zquery.min.js is always embedded (auto-built from source if not found)
-      \u2022 index.html is rewritten for both server and local (file://) use
-      \u2022 Output goes to dist/server/ and dist/local/ next to the detected index.html
+      • Passing a directory auto-detects the entry; passing a file uses it directly
+      • zquery.min.js is always embedded (auto-built from source if not found)
+      • HTML file is auto-detected (any .html, not just index.html)
+      • Output goes to dist/server/ and dist/local/ next to the detected HTML file
 
   OUTPUT
 
@@ -79,9 +82,18 @@ function showHelp() {
     # Bundle an app from the project root
     zquery bundle my-app/
 
+    # Pass a direct entry file (skip auto-detection)
+    zquery bundle my-app/scripts/main.js
+
     # Custom output directory
     zquery bundle my-app/ -o build/
 
+    # Minimal build (only HTML + bundled JS, no static assets)
+    zquery bundle my-app/ --minimal
+
+    # Dev server with a custom index page
+    zquery dev my-app/ --index home.html
+
   The bundler walks the ES module import graph starting from the entry
   file, topologically sorts dependencies, strips import/export syntax,
   and concatenates everything into a single IIFE with content-hashed

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>