zero-query 0.9.7 → 0.9.9

package/README.md

@@ -30,6 +30,7 @@
 | **HTTP** | Fetch wrapper with auto-JSON, interceptors (with unsubscribe & clear), HEAD requests, parallel requests (`http.all`), config inspection (`getConfig`), timeout/abort, base URL |
 | **Utils** | debounce, throttle, pipe, once, sleep, memoize, escapeHtml, stripHtml, uuid, capitalize, truncate, range, chunk, groupBy, unique, pick, omit, getPath/setPath, isEmpty, clamp, retry, timeout, deepClone, deepMerge, storage/session wrappers, event bus |
 | **Dev Tools** | CLI dev server with live-reload, CSS hot-swap, full-screen error overlay, floating toolbar, dark-themed inspector panel (Router view, DOM tree, network log, component viewer, performance dashboard), fetch interceptor, render instrumentation, CLI bundler for single-file production builds |
+| **SSR** | Server-side rendering to HTML strings in Node.js — `createSSRApp()`, `renderToString()`, `renderPage()` with SEO/Open Graph support, `renderBatch()` for parallel rendering, fragment mode, hydration markers, graceful error handling, `escapeHtml()` utility |
 
 ---
 
@@ -53,7 +54,7 @@ npx zquery dev my-app
 
 > **Tip:** Stay in the project root (where `node_modules` lives) instead of `cd`-ing into `my-app`. This keeps `index.d.ts` accessible to your IDE for full type/intellisense support.
 
-The `create` command generates a ready-to-run project with a sidebar layout, router, multiple components (including a folder component with external template and styles), and responsive styles. The dev server watches for file changes, hot-swaps CSS in-place, full-reloads on other changes, and handles SPA fallback routing.
+The `create` command generates a ready-to-run project with a sidebar layout, router, multiple components (including folder components with external templates and styles), and responsive styles. Use `--minimal` (or `-m`) to scaffold a lightweight 3-page starter instead. Use `--ssr` (or `-s`) to scaffold a project with a Node.js server-side rendering example. The dev server watches for file changes, hot-swaps CSS in-place, full-reloads on other changes, and handles SPA fallback routing.
 
 #### Error Overlay
 
@@ -136,7 +137,7 @@ That's it — a fully working SPA with the dev server's live-reload.
 ## Recommended Project Structure
 
 ```
-my-app/
+my-app/                          ← default scaffold (npx zquery create my-app)
   index.html
   global.css
   app/
@@ -150,15 +151,62 @@ my-app/
       api-demo.js
       about.js
       not-found.js
+      contact-card.js
       contacts/           ← folder component (templateUrl + styleUrl)
         contacts.js
         contacts.html
         contacts.css
+      playground/          ← folder component
+        playground.js
+        playground.html
+        playground.css
+      toolkit/             ← folder component
+        toolkit.js
+        toolkit.html
+        toolkit.css
   assets/
     scripts/              ← third-party JS (e.g. zquery.min.js for manual setup)
     styles/               ← additional stylesheets, fonts, etc.
 ```
 
+Use `--minimal` for a lighter starting point (3 pages + 404 fallback):
+
+```
+my-app/                          ← minimal scaffold (npx zquery create my-app --minimal)
+  index.html
+  global.css
+  app/
+    app.js
+    routes.js
+    store.js
+    components/
+      home.js
+      counter.js
+      about.js
+      not-found.js               ← 404 fallback
+  assets/
+```
+
+Use `--ssr` for a project with server-side rendering:
+
+```
+my-app/                          ← SSR scaffold (npx zquery create my-app --ssr)
+  index.html                     ← client HTML shell
+  global.css
+  app/
+    app.js                       ← client entry — registers shared components
+    routes.js                    ← shared route definitions
+    components/
+      home.js                    ← shared component (SSR + client)
+      about.js
+      not-found.js
+  server/
+    index.js                     ← SSR HTTP server
+  assets/
+```
+
+Components in `app/components/` export plain definition objects — the client registers them with `$.component()`, the server with `app.component()`. The `--ssr` flag handles everything automatically — installs dependencies, starts the server at `http://localhost:3000`, and opens the browser.
+
 - One component per file inside `components/`.
 - Names **must contain a hyphen** (Web Component convention): `home-page`, `app-counter`, etc.
 - Components with external templates or styles can use a subfolder (e.g. `contacts/contacts.js` + `contacts.html` + `contacts.css`).
@@ -271,13 +319,16 @@ location / {
 | `$.retry` `$.timeout` | Async utils |
 | `$.param` `$.parseQuery` | URL utils |
 | `$.storage` `$.session` | Storage wrappers |
-| `$.EventBus` `$.bus` | Event bus || `$.onError` `$.ZQueryError` `$.ErrorCode` `$.guardCallback` `$.validate` | Error handling || `$.version` | Library version |\n| `$.libSize` | Minified bundle size string (e.g. `\"~100 KB\"`) |
+| `$.EventBus` `$.bus` | Event bus |
+| `$.onError` `$.ZQueryError` `$.ErrorCode` `$.guardCallback` `$.guardAsync` `$.formatError` `$.validate` | Error handling |
+| `$.version` | Library version |\n| `$.libSize` | Minified bundle size string (e.g. `\"~100 KB\"`) |
+| `$.unitTests` | Build-time test results `{ passed, failed, total, suites, duration, ok }` |
 | `$.meta` | Build metadata (populated by CLI bundler) |
 | `$.noConflict` | Release `$` global |
 
 | CLI Command | Description |
 | --- | --- |
-| `zquery create [dir]` | Scaffold a new project (index.html, components, store, styles) |
+| `zquery create [dir]` | Scaffold a new project. Default: full-featured app. `--minimal` / `-m`: lightweight 3-page starter. `--ssr` / `-s`: SSR project with shared components and HTTP server. |
 | `zquery dev [root]` | Dev server with live-reload, CSS hot-swap, error overlay, expandable floating toolbar & five-tab inspector panel (port 3100). Visit `/_devtools` for the standalone panel. `--index` for custom HTML, `--bundle` for bundled mode, `--no-intercept` to skip CDN intercept. |
 | `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`) |

package/cli/commands/build.js

@@ -10,6 +10,7 @@
 const fs   = require('fs');
 const path = require('path');
 const zlib = require('zlib');
+const { execSync } = require('child_process');
 const { minify, sizeKB } = require('../utils');
 
 function buildLibrary() {
@@ -18,7 +19,7 @@ function buildLibrary() {
 
   const modules = [
     'src/errors.js',
-    'src/reactive.js', 'src/core.js', 'src/expression.js', 'src/diff.js',
+    'src/reactive.js', 'src/diff.js', 'src/core.js', 'src/expression.js',
     'src/component.js', 'src/router.js', 'src/store.js', 'src/http.js',
     'src/utils.js',
   ];
@@ -30,6 +31,49 @@ function buildLibrary() {
   const start = Date.now();
   if (!fs.existsSync(DIST)) fs.mkdirSync(DIST, { recursive: true });
 
+  // -----------------------------------------------------------------------
+  // Run unit tests and capture results for $.unitTests
+  // -----------------------------------------------------------------------
+  let testResults = { passed: 0, failed: 0, total: 0, suites: 0, duration: 0, ok: false };
+  try {
+    const json = execSync('npx vitest run --reporter=json', {
+      cwd: process.cwd(),
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 120000,
+    });
+    // vitest --reporter=json outputs JSON to stdout; may include non-JSON lines
+    const jsonStart = json.indexOf('{');
+    if (jsonStart !== -1) {
+      const parsed = JSON.parse(json.slice(jsonStart));
+      const passed  = parsed.numPassedTests  || 0;
+      const failed  = parsed.numFailedTests  || 0;
+      const total   = parsed.numTotalTests   || 0;
+      const suites  = parsed.numTotalTestSuites || 0;
+      const dur     = Math.round((parsed.testResults || []).reduce((s, r) => s + (r.endTime - r.startTime), 0));
+      testResults = { passed, failed, total, suites, duration: dur, ok: parsed.success !== false };
+    }
+    console.log(`  ✓ Tests: ${testResults.passed}/${testResults.total} passed (${testResults.suites} suites)\n`);
+  } catch (err) {
+    // Tests may fail but we still want to capture the numbers
+    const out = (err.stdout || '') + (err.stderr || '');
+    const jsonStart = out.indexOf('{');
+    if (jsonStart !== -1) {
+      try {
+        const parsed = JSON.parse(out.slice(jsonStart));
+        testResults = {
+          passed:   parsed.numPassedTests  || 0,
+          failed:   parsed.numFailedTests  || 0,
+          total:    parsed.numTotalTests   || 0,
+          suites:   parsed.numTotalTestSuites || 0,
+          duration: Math.round((parsed.testResults || []).reduce((s, r) => s + (r.endTime - r.startTime), 0)),
+          ok:       false,
+        };
+      } catch (_) { /* keep defaults */ }
+    }
+    console.log(`  ⚠ Tests: ${testResults.passed}/${testResults.total} passed, ${testResults.failed} failed\n`);
+  }
+
   const parts = modules.map(file => {
     let code = fs.readFileSync(path.join(process.cwd(), file), 'utf-8');
     code = code.replace(/^import\s+[\s\S]*?from\s+['"].*?['"];?\s*$/gm, '');
@@ -54,8 +98,11 @@ function buildLibrary() {
   // Inject actual minified library size into both outputs
   const libSizeKB = Math.round(Buffer.from(minified).length / 1024);
   const libSizeStr = `~${libSizeKB} KB`;
-  const outContent = fs.readFileSync(OUT_FILE, 'utf-8').replace("'__LIB_SIZE__'", `'${libSizeStr}'`);
-  const minContent = minified.replace("'__LIB_SIZE__'", `'${libSizeStr}'`);
+  const testObj = JSON.stringify(testResults);
+  let outContent = fs.readFileSync(OUT_FILE, 'utf-8').replace("'__LIB_SIZE__'", `'${libSizeStr}'`);
+  let minContent = minified.replace("'__LIB_SIZE__'", `'${libSizeStr}'`);
+  outContent = outContent.replace("'__UNIT_TESTS__'", testObj);
+  minContent = minContent.replace("'__UNIT_TESTS__'", testObj);
   fs.writeFileSync(OUT_FILE, outContent, 'utf-8');
   fs.writeFileSync(MIN_FILE, minContent, 'utf-8');
 

package/cli/commands/create.js

@@ -1,9 +1,13 @@
 // cli/commands/create.js — scaffold a new zQuery project
-// Reads template files from cli/scaffold/, replaces {{NAME}} with the project
-// name, and writes them into the target directory.
+//
+// Templates live in cli/scaffold/<variant>/ (default or minimal).
+// Reads template files, replaces {{NAME}} with the project name,
+// and writes them into the target directory.
 
 const fs   = require('fs');
 const path = require('path');
+const { execSync, spawn } = require('child_process');
+const { flag } = require('../args');
 
 /**
  * Recursively collect every file under `dir`, returning paths relative to `dir`.
@@ -22,24 +26,38 @@ function walkDir(dir, prefix = '') {
 }
 
 function createProject(args) {
-  const target = args[1] ? path.resolve(args[1]) : process.cwd();
+  // First positional arg after "create" is the target dir (skip flags)
+  const dirArg = args.slice(1).find(a => !a.startsWith('-'));
+  const target = dirArg ? path.resolve(dirArg) : process.cwd();
   const name   = path.basename(target);
 
+  // Determine scaffold variant: --minimal / -m  or  --ssr / -s  or  default
+  const variant = flag('minimal', 'm') ? 'minimal'
+                : flag('ssr', 's')     ? 'ssr'
+                :                        'default';
+
   // Guard: refuse to overwrite existing files
-  const conflicts = ['index.html', 'global.css', 'app', 'assets'].filter(f =>
+  const checkFiles = ['index.html', 'global.css', 'app', 'assets'];
+  if (variant === 'ssr') checkFiles.push('server');
+  const conflicts = checkFiles.filter(f =>
     fs.existsSync(path.join(target, f))
   );
   if (conflicts.length) {
-    console.error(`\n  \u2717 Directory already contains: ${conflicts.join(', ')}`);
+    console.error(`\n  ✗ Directory already contains: ${conflicts.join(', ')}`);
     console.error(`  Aborting to avoid overwriting existing files.\n`);
     process.exit(1);
   }
 
-  console.log(`\n  zQuery \u2014 Create Project\n`);
+  console.log(`\n  zQuery — Create Project (${variant})\n`);
   console.log(`  Scaffolding into ${target}\n`);
 
-  // Resolve the scaffold template directory
-  const scaffoldDir = path.resolve(__dirname, '..', 'scaffold');
+  // Resolve the scaffold template directory for the chosen variant
+  const scaffoldDir = path.resolve(__dirname, '..', 'scaffold', variant);
+
+  if (!fs.existsSync(scaffoldDir)) {
+    console.error(`\n  ✗ Scaffold variant "${variant}" not found.\n`);
+    process.exit(1);
+  }
 
   // Walk the scaffold directory and copy each file
   const templateFiles = walkDir(scaffoldDir);
@@ -54,14 +72,43 @@ function createProject(args) {
     const dest = path.join(target, rel);
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     fs.writeFileSync(dest, content, 'utf-8');
-    console.log(`  \u2713 ${rel}`);
+    console.log(`  ✓ ${rel}`);
   }
 
-  console.log(`
+  const devCmd = `npx zquery dev${target !== process.cwd() ? ` ${dirArg}` : ''}`;
+
+  if (variant === 'ssr') {
+    console.log(`\n  Installing dependencies...\n`);
+    // Install zero-query from the same package that provides this CLI
+    // (works both in local dev and when installed from npm)
+    const zqRoot = path.resolve(__dirname, '..', '..');
+    try {
+      execSync(`npm install "${zqRoot}"`, { cwd: target, stdio: 'inherit' });
+    } catch {
+      console.error(`\n  ✗ npm install failed. Run it manually:\n\n    cd ${dirArg || '.'}\n    npm install\n    node server/index.js\n`);
+      process.exit(1);
+    }
+
+    console.log(`\n  Starting SSR server...\n`);
+    const child = spawn('node', ['server/index.js'], { cwd: target, stdio: 'inherit' });
+
+    setTimeout(() => {
+      const open = process.platform === 'win32' ? 'start'
+                 : process.platform === 'darwin' ? 'open' : 'xdg-open';
+      try { execSync(`${open} http://localhost:3000`, { stdio: 'ignore' }); } catch {}
+    }, 500);
+
+    process.on('SIGINT',  () => { child.kill(); process.exit(); });
+    process.on('SIGTERM', () => { child.kill(); process.exit(); });
+    child.on('exit', (code) => process.exit(code || 0));
+    return; // keep process alive for the server
+  } else {
+    console.log(`
   Done! Next steps:
 
-    npx zquery dev${target !== process.cwd() ? ` ${args[1]}` : ''}
+    ${devCmd}
 `);
+  }
 }
 
 module.exports = createProject;

package/cli/help.js

@@ -9,6 +9,10 @@ function showHelp() {
     create [dir]               Scaffold a new zQuery project
                                Creates index.html, global.css, app/, assets/ in the target directory
                                (defaults to the current directory)
+      --minimal, -m            Use the minimal template (home, counter, about)
+                               instead of the full-featured default scaffold
+      --ssr, -s                Use the SSR template — includes server/index.js
+                               SSR HTTP server with shared component definitions
 
     dev [root]                 Start a dev server with live-reload
       --port, -p <number>     Port number (default: 3100)

package/cli/scaffold/default/app/app.js

@@ -0,0 +1,211 @@
+// app.js — Application entry point
+//
+// Bootstraps the app: imports components, sets up routing,
+// wires the responsive sidebar, and connects the store.
+//
+// Key APIs used:
+//   $.router     — SPA navigation (history mode)
+//   $.ready      — run after DOM is loaded
+//   $.bus        — event bus (toast notifications, contact card)
+//   $.on         — global delegated event listeners
+//   $.storage    — localStorage wrapper
+//   $.create     — create DOM elements
+
+import './store.js';
+import './components/home.js';
+import './components/counter.js';
+import './components/todos.js';
+import './components/api-demo.js';
+import './components/playground/playground.js';
+import './components/toolkit/toolkit.js';
+import './components/about.js';
+import './components/contact-card.js';
+import './components/contacts/contacts.js';
+import './components/not-found.js';
+import { routes } from './routes.js';
+
+// ---------------------------------------------------------------------------
+// Router — SPA navigation with history mode
+// ---------------------------------------------------------------------------
+const router = $.router({
+  el: '#app',   //@ Mount point (Set in index.html)
+  routes,
+  fallback: 'not-found',
+  mode: 'history'
+});
+
+// Post-navigation hook — track page views on every navigation
+router.afterEach((to) => {
+  const store = $.getStore('main');
+  if (store) store.dispatch('incrementVisits');
+  console.log('📊 Navigated to:', to.path);
+});
+
+// Highlight the active nav link on every route change
+router.onChange((to) => {
+  $.all('.nav-link').removeClass('active');
+  $(`.nav-link[z-link="${to.path}"]`).addClass('active');
+
+  // Close mobile menu on navigate
+  closeMobileMenu();
+});
+
+// ---------------------------------------------------------------------------
+// Responsive sidebar toggle
+// ---------------------------------------------------------------------------
+const $sidebar = $('#sidebar');
+const $overlay = $('#overlay');
+const $toggle  = $('#menu-toggle');
+
+function toggleMobileMenu(open) {
+  $sidebar.toggleClass('open', open);
+  $overlay.toggleClass('visible', open);
+  $toggle.toggleClass('active', open);
+}
+
+function closeMobileMenu() { toggleMobileMenu(false); }
+
+// $.on — global delegated event listeners
+$.on('click', '#menu-toggle', () => toggleMobileMenu(!$sidebar.hasClass('open')));
+$.on('click', '#overlay', closeMobileMenu);
+
+// Close sidebar on Escape key — using $.on direct (no selector needed)
+$.on('keydown', (e) => {
+  if (e.key === 'Escape') closeMobileMenu();
+});
+
+// ---------------------------------------------------------------------------
+// Sidebar stats panel — collapsible, live-updating from $.store
+// Starts expanded by default. Open/closed state saved via $.storage.
+// ---------------------------------------------------------------------------
+$.on('click', '#stats-toggle', () => {
+  const $body  = $('#stats-body');
+  const $arrow = $('#stats-arrow');
+  if (!$body.length) return;
+  const open = $body.css('display') !== 'none';
+  open ? $body.hide() : $body.show();
+  $arrow.toggleClass('open', !open);
+  $.storage.set('statsOpen', !open);
+});
+
+function updateSidebarStats() {
+  const store = $.getStore('main');
+  if (!store) return;
+  $('#ss-visits').text(store.state.visits);
+  $('#ss-todos').text(store.getters.todoCount);
+  $('#ss-pending').text(store.getters.pendingCount);
+  $('#ss-done').text(store.getters.doneCount);
+  $('#ss-contacts').text(store.getters.contactCount);
+  $('#ss-favorites').text(store.getters.favoriteCount);
+}
+
+// ---------------------------------------------------------------------------
+// Sidebar contacts — live status indicators from $.store
+// ---------------------------------------------------------------------------
+function updateSidebarContacts() {
+  const store = $.getStore('main');
+  if (!store) return;
+  const $list = $('#sc-list');
+  if (!$list.length) return;
+
+  const sorted = [...store.state.contacts].sort((a, b) => {
+    const order = { online: 0, away: 1, offline: 2 };
+    return (order[a.status] ?? 3) - (order[b.status] ?? 3);
+  });
+
+  const html = sorted.map(c => {
+    const hue = (c.name.charCodeAt(0) * 7) % 360;
+    const initial = $.escapeHtml(c.name.charAt(0).toUpperCase());
+    const name = $.escapeHtml(c.name);
+    return `<div class="sc-item" data-contact-id="${c.id}">
+      <span class="sc-avatar" style="background:hsl(${hue},55%,42%)">${initial}</span>
+      <span class="sc-dot sc-dot-${c.status}"></span>
+      <span class="sc-name">${name}</span>
+    </div>`;
+  }).join('');
+
+  $list.html(html);
+}
+
+// ---------------------------------------------------------------------------
+// Toast notification system via $.bus (event bus)
+// ---------------------------------------------------------------------------
+// Any component can emit: $.bus.emit('toast', { message, type })
+// Types: 'success', 'error', 'info'
+$.bus.on('toast', ({ message, type = 'info' }) => {
+  const toast = $.create('div')
+    .addClass('toast', `toast-${type}`)
+    .text(message)
+    .appendTo('#toasts');
+  // Auto-remove after 3 seconds
+  setTimeout(() => {
+    toast.addClass('toast-exit');
+    setTimeout(() => toast.remove(), 300);
+  }, 3000);
+});
+
+// ---------------------------------------------------------------------------
+// On DOM ready — final setup
+// ---------------------------------------------------------------------------
+$.ready(() => {
+  // Display version in the sidebar footer
+  $('#nav-version').text('v' + $.version);
+
+  // Theme: restore saved preference or auto-detect from system
+  const saved = $.storage.get('theme'); // 'dark' | 'light' | 'system' | null
+  const preference = saved || 'system';
+  applyTheme(preference);
+
+  // Listen for OS color-scheme changes (only applies when preference is 'system')
+  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
+    const current = $.storage.get('theme') || 'system';
+    if (current === 'system') applyTheme('system');
+  });
+
+  // Set active link on initial load
+  const current = window.location.pathname;
+  $.all(`.nav-link[z-link="${current}"]`).addClass('active');
+
+  // Stats panel: restore open/closed from $.storage (defaults to open)
+  const statsOpen = $.storage.get('statsOpen');
+  if (statsOpen === false) {
+    $('#stats-body').hide();
+    $('#stats-arrow').removeClass('open');
+  }
+
+  // Sidebar contact click — open the global contact card overlay
+  $('#sc-list').on('click', '.sc-item', (e) => {
+    const item = e.target.closest('.sc-item');
+    if (!item) return;
+    const id = Number(item.dataset.contactId);
+    if (id) $.bus.emit('openContact', id);
+  });
+
+  // Initial sidebar stats + contacts + live subscription
+  updateSidebarStats();
+  updateSidebarContacts();
+  const store = $.getStore('main');
+  if (store) {
+    store.subscribe(updateSidebarStats);
+    store.subscribe(updateSidebarContacts);
+  }
+
+  // Mount any components outside the router outlet (e.g. <contact-card>)
+  $.mountAll();
+
+  console.log('⚡ {{NAME}} — powered by zQuery v' + $.version);
+});
+
+// ---------------------------------------------------------------------------
+// Theme helper — resolves 'system' to actual dark/light and applies it
+// ---------------------------------------------------------------------------
+function applyTheme(preference) {
+  let resolved = preference;
+  if (preference === 'system') {
+    resolved = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  }
+  $('html').attr('data-theme', resolved);
+}
+
+// Expose globally so components can call it
+window.__applyTheme = applyTheme;