zero-query 0.4.9 → 0.6.3

package/README.md

@@ -15,14 +15,14 @@
 
 </p>
 
-> **Lightweight, zero-dependency frontend library that combines jQuery-style DOM manipulation with a modern reactive component system, SPA router, global state management, HTTP client, and utility toolkit — all in a single ~54 KB minified browser bundle. Works out of the box with ES modules. An optional CLI bundler is available for single-file production builds.**
+> **Lightweight, zero-dependency frontend library that combines jQuery-style DOM manipulation with a modern reactive component system, SPA router, global state management, HTTP client, and utility toolkit — all in a single ~84 KB minified browser bundle. Works out of the box with ES modules. An optional CLI bundler is available for single-file production builds.**
 
 ## Features
 
 | Module | Highlights |
 | --- | --- |
 | **Core `$()`** | jQuery-like chainable selectors, traversal, DOM manipulation, events, animation |
-| **Components** | Reactive state, template literals, `@event` delegation (8 modifiers), `z-model` two-way binding, directives (`z-if`/`z-else-if`/`z-else`, `z-for`, `z-show`, `z-bind`/`:attr`, `z-class`, `z-style`, `z-text`, `z-html`, `z-ref`, `z-cloak`, `z-pre`), scoped styles, external templates (`templateUrl` / `styleUrl`), lifecycle hooks, auto-injected base styles (`z-cloak` hiding, mobile tap-highlight suppression) |
+| **Components** | Reactive state, template literals, `@event` delegation (8 modifiers), `z-model` two-way binding, computed properties, watch callbacks, slot-based content projection, directives (`z-if`/`z-else-if`/`z-else`, `z-for`, `z-show`, `z-bind`/`:attr`, `z-class`, `z-style`, `z-text`, `z-html`, `z-ref`, `z-cloak`, `z-pre`, `z-key`), DOM morphing engine (no innerHTML rebuild), CSP-safe expression evaluation, scoped styles, external templates (`templateUrl` / `styleUrl`), lifecycle hooks, auto-injected base styles |
 | **Router** | History & hash mode, route params (`:id`), guards, lazy loading, `z-link` navigation |
 | **Store** | Reactive global state, named actions, computed getters, middleware, subscriptions |
 | **HTTP** | Fetch wrapper with auto-JSON, interceptors, timeout/abort, base URL |
@@ -69,7 +69,7 @@ If you prefer **zero tooling**, download `dist/zQuery.min.js` from the [GitHub r
 git clone https://github.com/tonywied17/zero-query.git
 cd zero-query
 npx zquery build
-# → dist/zQuery.min.js  (~54 KB)
+# → dist/zQuery.min.js  (~84 KB)
 ```
 
 ### Include in HTML
@@ -162,7 +162,7 @@ my-app/
 
 ## CLI Bundler
 
-The CLI can compile your entire app — ES modules, the library, external templates, and assets — into a **single bundled file**.
+The CLI compiles your entire app — ES modules, the library, external templates, and assets — into a **single production-ready bundle**. It outputs two builds in one step: a `server/` build for deploying to any web server, and a `local/` build that works straight from disk. No config, no flags — just point it at your app.
 
 ```bash
 # Auto-detect entry from any .html with a module script
@@ -170,6 +170,9 @@ npx zquery bundle
 
 # Or point to an app directory from anywhere
 npx zquery bundle my-app/
+
+# Or pass a direct entry file (skips auto-detection)
+npx zquery bundle my-app/scripts/main.js
 ```
 
 Output goes to `dist/` next to your `index.html`:
@@ -192,7 +195,8 @@ dist/
 | Flag | Short | Description |
 | --- | --- | --- |
 | `--out <path>` | `-o` | Custom output directory |
-| `--html <file>` | — | Use a specific HTML file |
+| `--index <file>` | `-i` | Index HTML file (default: auto-detected) |
+| `--minimal` | `-m` | Only output HTML + bundled JS (skip static assets) |
 
 ### What the Bundler Does
 
@@ -236,13 +240,15 @@ location / {
 
 | Namespace | Methods |
 | --- | --- |
-| `$()` | Single-element selector → `Element \| null` |
-| `$.all()` | Collection selector → `ZQueryCollection` |
-| `$.id` `$.class` `$.classes` `$.tag` `$.children` | Quick DOM refs |
+| `$()` | Chainable selector → `ZQueryCollection` (CSS selectors, elements, NodeLists, HTML strings) |
+| `$.all()` | Alias for `$()` — identical behavior |
+| `$.id` `$.class` `$.classes` `$.tag` `$.name` `$.children` | Quick DOM refs |
 | `$.create` | Element factory |
 | `$.ready` `$.on` `$.off` | DOM ready, global event delegation & direct listeners |
 | `$.fn` | Collection prototype (extend it) |
 | `$.component` `$.mount` `$.mountAll` `$.getInstance` `$.destroy` `$.components` | Component system |
+| `$.morph` | DOM morphing engine — patch existing DOM to match new HTML without destroying unchanged nodes |
+| `$.safeEval` | CSP-safe expression evaluator (replaces `eval` / `new Function`) |
 | `$.style` | Dynamically load global stylesheet file(s) at runtime |
 | `$.router` `$.getRouter` | SPA router |
 | `$.store` `$.getStore` | State management |
@@ -261,8 +267,8 @@ location / {
 | CLI Command | Description |
 | --- | --- |
 | `zquery create [dir]` | Scaffold a new project (index.html, components, store, styles) |
-| `zquery dev [root]` | Dev server with live-reload &amp; error overlay (port 3100) |
-| `zquery bundle [dir]` | Bundle app into a single IIFE file |
+| `zquery dev [root]` | Dev server with live-reload &amp; error overlay (port 3100). `--index` for custom HTML. |
+| `zquery bundle [dir\|file]` | Bundle app into a single IIFE file. Accepts dir or direct entry file. |
 | `zquery build` | Build the zQuery library (`dist/zQuery.min.js`) |
 | `zquery --help` | Show CLI usage |
 

package/cli/commands/build.js

@@ -16,8 +16,10 @@ function buildLibrary() {
   const VERSION = pkg.version;
 
   const modules = [
-    'src/reactive.js', 'src/core.js', 'src/component.js',
-    'src/router.js',   'src/store.js', 'src/http.js', 'src/utils.js',
+    'src/errors.js',
+    'src/reactive.js', 'src/core.js', 'src/expression.js', 'src/diff.js',
+    'src/component.js', 'src/router.js', 'src/store.js', 'src/http.js',
+    'src/utils.js',
   ];
 
   const DIST     = path.join(process.cwd(), 'dist');

package/cli/commands/bundle.js

@@ -13,7 +13,7 @@ const fs     = require('fs');
 const path   = require('path');
 const crypto = require('crypto');
 
-const { args, option }        = require('../args');
+const { args, flag, option }   = require('../args');
 const { minify, sizeKB }      = require('../utils');
 const buildLibrary             = require('./build');
 
@@ -104,6 +104,8 @@ function rewriteResourceUrls(code, filePath, projectRoot) {
     (match, prefix, quote, url) => {
       if (url.startsWith('/') || url.includes('://')) return match;
       const abs = path.resolve(fileDir, url);
+      // Only rewrite if the file actually exists — avoids mangling code examples
+      if (!fs.existsSync(abs)) return match;
       const rel = path.relative(projectRoot, abs).replace(/\\/g, '/');
       return `${prefix}${quote}${rel}${quote}`;
     }
@@ -379,18 +381,68 @@ function rewriteHtml(projectRoot, htmlRelPath, bundleFile, includeLib, bundledFi
   console.log(`  ✓ Copied ${copiedCount} asset(s) into both dist dirs`);
 }
 
+// ---------------------------------------------------------------------------
+// Static asset copying
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy the entire app directory into both dist/server and dist/local,
+ * skipping only build outputs and tooling dirs.  This ensures all static
+ * assets (icons/, images/, fonts/, styles/, scripts/, manifests, etc.)
+ * are available in the built output without maintaining a fragile whitelist.
+ */
+function copyStaticAssets(appRoot, serverDir, localDir, bundledFiles) {
+  const SKIP_DIRS = new Set(['dist', 'node_modules', '.git', '.vscode', 'scripts']);
+
+  let copiedCount = 0;
+
+  function copyEntry(srcPath, relPath) {
+    const stat = fs.statSync(srcPath);
+    if (stat.isDirectory()) {
+      if (SKIP_DIRS.has(path.basename(srcPath))) return;
+      for (const child of fs.readdirSync(srcPath)) {
+        copyEntry(path.join(srcPath, child), path.join(relPath, child));
+      }
+    } else {
+      if (bundledFiles && bundledFiles.has(path.resolve(srcPath))) return;
+      for (const distDir of [serverDir, localDir]) {
+        const dest = path.join(distDir, relPath);
+        if (fs.existsSync(dest)) continue; // already copied by rewriteHtml
+        const dir = path.dirname(dest);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        fs.copyFileSync(srcPath, dest);
+      }
+      copiedCount++;
+    }
+  }
+
+  for (const entry of fs.readdirSync(appRoot, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      copyEntry(path.join(appRoot, entry.name), entry.name);
+    } else {
+      copyEntry(path.join(appRoot, entry.name), entry.name);
+    }
+  }
+
+  if (copiedCount > 0) {
+    console.log(`  \u2713 Copied ${copiedCount} additional static asset(s) into both dist dirs`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main bundleApp function
 // ---------------------------------------------------------------------------
 
 function bundleApp() {
   const projectRoot = process.cwd();
+  const minimal = flag('minimal', 'm');
 
-  // Entry point — accepts a directory (auto-detects entry inside it) or a file
+  // Entry point — positional arg (directory or file) or auto-detection
   let entry = null;
   let targetDir = null;
   for (let i = 1; i < args.length; i++) {
-    if (!args[i].startsWith('-') && args[i - 1] !== '-o' && args[i - 1] !== '--out' && args[i - 1] !== '--html') {
+    if (!args[i].startsWith('-') && args[i - 1] !== '-o' && args[i - 1] !== '--out' && args[i - 1] !== '--index') {
       const resolved = path.resolve(projectRoot, args[i]);
       if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
         targetDir = resolved;
@@ -405,16 +457,19 @@ function bundleApp() {
 
   if (!entry || !fs.existsSync(entry)) {
     console.error(`\n  \u2717 Could not find entry file.`);
-    console.error(`    Provide an app directory: zquery bundle my-app/\n`);
+    console.error(`    Provide an app directory: zquery bundle my-app/`);
+    console.error(`    Or pass a direct entry file: zquery bundle my-app/scripts/main.js\n`);
     process.exit(1);
   }
 
   const outPath = option('out', 'o', null);
 
-  // Auto-detect index.html
-  let htmlFile = option('html', null, null);
+  // Auto-detect HTML file
+  let htmlFile = option('index', 'i', null);
   let htmlAbs  = htmlFile ? path.resolve(projectRoot, htmlFile) : null;
   if (!htmlFile) {
+    // Strategy: first look for index.html walking up from entry, then
+    // scan for any .html that references the entry via a module script tag.
     const htmlCandidates = [];
     let entryDir = path.dirname(entry);
     while (entryDir.length >= projectRoot.length) {
@@ -432,6 +487,47 @@ function bundleApp() {
         break;
       }
     }
+
+    // If no index.html found, scan for any .html file that references
+    // the entry point (supports home.html, app.html, etc.)
+    if (!htmlAbs) {
+      const searchRoot = targetDir || projectRoot;
+      const htmlScan = [];
+      for (const e of fs.readdirSync(searchRoot, { withFileTypes: true })) {
+        if (e.isFile() && e.name.endsWith('.html')) {
+          htmlScan.push(path.join(searchRoot, e.name));
+        } else if (e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules' && e.name !== 'dist') {
+          try {
+            for (const child of fs.readdirSync(path.join(searchRoot, e.name), { withFileTypes: true })) {
+              if (child.isFile() && child.name.endsWith('.html')) {
+                htmlScan.push(path.join(searchRoot, e.name, child.name));
+              }
+            }
+          } catch { /* skip */ }
+        }
+      }
+      // Prefer the HTML file that references our entry via a module script
+      const moduleScriptRe = /<script[^>]+type\s*=\s*["']module["'][^>]+src\s*=\s*["']([^"']+)["']/g;
+      for (const hp of htmlScan) {
+        const content = fs.readFileSync(hp, 'utf-8');
+        let m;
+        moduleScriptRe.lastIndex = 0;
+        while ((m = moduleScriptRe.exec(content)) !== null) {
+          const resolved = path.resolve(path.dirname(hp), m[1]);
+          if (resolved === path.resolve(entry)) {
+            htmlAbs  = hp;
+            htmlFile = path.relative(projectRoot, hp);
+            break;
+          }
+        }
+        if (htmlAbs) break;
+      }
+      // Last resort: use the first .html found
+      if (!htmlAbs && htmlScan.length > 0) {
+        htmlAbs  = htmlScan[0];
+        htmlFile = path.relative(projectRoot, htmlScan[0]);
+      }
+    }
   }
 
   // Output directory
@@ -459,7 +555,8 @@ function bundleApp() {
   console.log(`  Entry:   ${entryRel}`);
   console.log(`  Output:  ${path.relative(projectRoot, baseDistDir)}/server/ & local/`);
   console.log(`  Library: embedded`);
-  console.log(`  HTML:    ${htmlFile || 'not found (no index.html detected)'}`);
+  console.log(`  HTML:    ${htmlFile || 'not found (no HTML detected)'}`);
+  if (minimal) console.log(`  Mode:    minimal (HTML + bundle only)`);
   console.log('');
 
   // ------ doBuild (inlined) ------
@@ -571,10 +668,16 @@ function bundleApp() {
   console.log(`\n  ✓ ${bundleBase} (${sizeKB(fs.readFileSync(bundleFile))} KB)`);
   console.log(`  ✓ ${minBase} (${sizeKB(fs.readFileSync(minFile))} KB)`);
 
-  // Rewrite HTML
+  // Rewrite HTML (use full bundle — minified version mangles template literal whitespace)
+  const bundledFileSet = new Set(files);
   if (htmlFile) {
-    const bundledFileSet = new Set(files);
-    rewriteHtml(projectRoot, htmlFile, minFile, true, bundledFileSet, serverDir, localDir);
+    rewriteHtml(projectRoot, htmlFile, bundleFile, true, bundledFileSet, serverDir, localDir);
+  }
+
+  // Copy static asset directories (icons/, images/, fonts/, etc.)
+  if (!minimal) {
+    const appRoot = htmlAbs ? path.dirname(htmlAbs) : (targetDir || projectRoot);
+    copyStaticAssets(appRoot, serverDir, localDir, bundledFileSet);
   }
 
   const elapsed = Date.now() - start;

package/cli/commands/dev/index.js

@@ -0,0 +1,82 @@
+/**
+ * cli/commands/dev/index.js — Dev server orchestrator
+ *
+ * Ties together the HTTP server, file watcher, logger, and overlay
+ * to provide a complete development environment with live-reload,
+ * syntax validation, and a full-screen error overlay that surfaces
+ * both build-time and runtime ZQueryErrors.
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { args, flag, option } = require('../../args');
+const { createServer }       = require('./server');
+const { startWatcher }       = require('./watcher');
+const { printBanner }        = require('./logger');
+
+// ---------------------------------------------------------------------------
+// Resolve project root
+// ---------------------------------------------------------------------------
+
+function resolveRoot(htmlEntry) {
+  // Explicit positional argument  →  zquery dev <dir>
+  for (let i = 1; i < args.length; i++) {
+    const prev = args[i - 1];
+    if (!args[i].startsWith('-') && prev !== '-p' && prev !== '--port' && prev !== '--index' && prev !== '-i') {
+      return path.resolve(process.cwd(), args[i]);
+    }
+  }
+
+  // Auto-detect: first candidate that contains the HTML entry file
+  const candidates = [
+    process.cwd(),
+    path.join(process.cwd(), 'public'),
+    path.join(process.cwd(), 'src'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, htmlEntry))) return c;
+  }
+  return process.cwd();
+}
+
+// ---------------------------------------------------------------------------
+// devServer — main entry point (called from cli/index.js)
+// ---------------------------------------------------------------------------
+
+function devServer() {
+  const htmlEntry   = option('index', 'i', 'index.html');
+  const port        = parseInt(option('port', 'p', '3100'), 10);
+  const noIntercept = flag('no-intercept');
+  const root        = resolveRoot(htmlEntry);
+
+  // Start HTTP server + SSE pool
+  const { app, pool, listen } = createServer({ root, htmlEntry, port, noIntercept });
+
+  // Start file watcher
+  const watcher = startWatcher({ root, pool });
+
+  // Boot
+  listen(() => {
+    printBanner({
+      port,
+      root:          path.relative(process.cwd(), root) || '.',
+      htmlEntry,
+      noIntercept,
+      watchDirCount: watcher.dirs.length,
+    });
+  });
+
+  // Graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('\n  Shutting down...');
+    watcher.destroy();
+    pool.closeAll();
+    app.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 1000);
+  });
+}
+
+module.exports = devServer;

package/cli/commands/dev/logger.js

@@ -0,0 +1,70 @@
+/**
+ * cli/commands/dev/logger.js — Terminal output helpers
+ *
+ * Provides styled console output for the dev server: startup banner,
+ * timestamped file-change messages, and error formatting.
+ */
+
+'use strict';
+
+// ANSI colour helpers (works on all modern terminals)
+const c = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  red:     '\x1b[31m',
+  green:   '\x1b[32m',
+  yellow:  '\x1b[33m',
+  cyan:    '\x1b[36m',
+  magenta: '\x1b[35m',
+};
+
+function timestamp() {
+  return new Date().toLocaleTimeString();
+}
+
+// ---------------------------------------------------------------------------
+// Event-level log helpers
+// ---------------------------------------------------------------------------
+
+function logCSS(relPath) {
+  console.log(`  ${timestamp()}  ${c.magenta} css ${c.reset} ${relPath}`);
+}
+
+function logReload(relPath) {
+  console.log(`  ${timestamp()}  ${c.cyan} reload ${c.reset} ${relPath}`);
+}
+
+function logError(descriptor) {
+  const t = timestamp();
+  console.log(`  ${t}  ${c.red} error ${c.reset} ${descriptor.file}`);
+  console.log(`         ${c.red}${descriptor.type}: ${descriptor.message}${c.reset}`);
+  if (descriptor.line) {
+    console.log(`         ${c.dim}at line ${descriptor.line}${descriptor.column ? ':' + descriptor.column : ''}${c.reset}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Startup banner
+// ---------------------------------------------------------------------------
+
+function printBanner({ port, root, htmlEntry, noIntercept, watchDirCount }) {
+  const rule = c.dim + '-'.repeat(40) + c.reset;
+  console.log(`\n  ${c.bold}zQuery Dev Server${c.reset}`);
+  console.log(`  ${rule}`);
+  console.log(`  Local:       ${c.cyan}http://localhost:${port}/${c.reset}`);
+  console.log(`  Root:        ${root}`);
+  if (htmlEntry !== 'index.html') {
+    console.log(`  HTML:        ${c.cyan}${htmlEntry}${c.reset}`);
+  }
+  console.log(`  Live Reload: ${c.green}enabled${c.reset} (SSE)`);
+  console.log(`  Overlay:     ${c.green}enabled${c.reset} (syntax + runtime + ZQueryError)`);
+  if (noIntercept) {
+    console.log(`  Intercept:   ${c.yellow}disabled${c.reset} (--no-intercept)`);
+  }
+  console.log(`  Watching:    all files in ${watchDirCount} director${watchDirCount === 1 ? 'y' : 'ies'}`);
+  console.log(`  ${rule}`);
+  console.log(`  Press Ctrl+C to stop\n`);
+}
+
+module.exports = { logCSS, logReload, logError, printBanner };