zero-query 0.6.3 → 0.8.6

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src=".github/images/logo.svg" alt="zQuery logo" width="300" height="300">
+  <img src=".github/images/logo-animated.svg" alt="zQuery logo" width="300" height="300">
 </p>
 
 <h1 align="center">zQuery</h1>
@@ -15,19 +15,21 @@
 
 </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 ~84 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 ~91 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, 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 |
+| **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`, `z-skip`), DOM morphing engine with LIS-based keyed reconciliation (no innerHTML rebuild), CSP-safe expression evaluation with AST caching, scoped styles, external templates (`templateUrl` / `styleUrl`), lifecycle hooks, auto-injected base styles |
+| **Router** | History & hash mode, route params (`:id`), wildcards, guards (`beforeEach`/`afterEach`), lazy loading, `z-link` navigation, `z-to-top` scroll modifier (`instant`/`smooth`), sub-route history substates (`pushSubstate`/`onSubstate`) |
+| **Directives** | `z-if`, `z-for`, `z-model`, `z-show`, `z-bind`, `z-class`, `z-style`, `z-text`, `z-html`, `z-ref`, `z-cloak`, `z-pre`, `z-key`, `z-skip` &mdash; 17 built-in template directives |
+| **Reactive** | Deep proxy reactivity, Signals (`.value`, `.peek()`), computed values, effects (auto-tracked with dispose) |
+| **Store** | Reactive global state, named actions, computed getters, middleware, subscriptions, time-travel (undo/redo/history) |
+| **Selectors & DOM** | jQuery-like chainable selectors, traversal, DOM manipulation, events, animation |
 | **HTTP** | Fetch wrapper with auto-JSON, interceptors, timeout/abort, base URL |
-| **Reactive** | Deep proxy reactivity, Signals, computed values, effects |
 | **Utils** | debounce, throttle, pipe, once, sleep, escapeHtml, uuid, 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 |
 
 ---
 
@@ -61,15 +63,19 @@ The dev server includes a **full-screen error overlay** that surfaces errors dir
 - **Runtime errors** — uncaught exceptions and unhandled promise rejections are captured and displayed in the same overlay with a cleaned-up stack trace.
 - The overlay **auto-clears** when you fix the error and save. Press `Esc` or click `×` to dismiss manually.
 
+#### Floating Toolbar & Inspector
+
+A compact toolbar appears in the bottom-right corner showing live request/render counters and a DOM button. Click any counter to open a **dark-themed DevTools inspector** as a popup — or visit `http://localhost:<port>/_devtools` for a standalone split-view panel with four tabs: **Elements** (live DOM tree with component badges, source viewer, expand/collapse), **Network** (fetch log with JSON viewer), **Components** (live state cards), and **Performance** (render timeline with timing metrics).
+
 ### Alternative: Manual Setup (No npm)
 
-If you prefer **zero tooling**, download `dist/zQuery.min.js` from the [GitHub releases](https://github.com/tonywied17/zero-query/releases/tag/RELEASE) and drop it into `scripts/vendor/`. Then open `index.html` directly in a browser — no Node.js required.
+If you prefer **zero tooling**, download `dist/zquery.min.js` from the [dist/ folder](https://github.com/tonywied17/zero-query/tree/main/dist) and drop it into your project root or `assets/scripts/`. Then open `index.html` directly in a browser — no Node.js required.
 
 ```bash
 git clone https://github.com/tonywied17/zero-query.git
 cd zero-query
 npx zquery build
-# → dist/zQuery.min.js  (~84 KB)
+# → dist/zquery.min.js  (~91 KB)
 ```
 
 ### Include in HTML
@@ -80,9 +86,9 @@ npx zquery build
 <head>
   <meta charset="UTF-8">
   <title>My App</title>
-  <link rel="stylesheet" href="styles/styles.css">
-  <script src="scripts/vendor/zQuery.min.js"></script>
-  <script type="module" src="scripts/app.js"></script>
+  <link rel="stylesheet" href="global.css">
+  <script src="zquery.min.js"></script>
+  <script type="module" src="app/app.js"></script>
 </head>
 <body>
   <nav>
@@ -97,7 +103,7 @@ npx zquery build
 ### Boot Your App
 
 ```js
-// scripts/app.js
+// app/app.js
 import './components/home.js';
 import './components/about.js';
 import './components/contacts/contacts.js';
@@ -109,7 +115,7 @@ $.router({ el: '#app', routes, fallback: 'not-found' });
 ### Define a Component
 
 ```js
-// scripts/components/home.js
+// app/components/home.js
 $.component('home-page', {
   state: () => ({ count: 0 }),
   increment() { this.state.count++; },
@@ -132,9 +138,8 @@ That's it — a fully working SPA with the dev server's live-reload.
 ```
 my-app/
   index.html
-  scripts/
-    vendor/
-      zQuery.min.js       ← only needed for manual setup; dev server auto-resolves
+  global.css
+  app/
     app.js
     routes.js
     store.js
@@ -149,14 +154,17 @@ my-app/
         contacts.js
         contacts.html
         contacts.css
-  styles/
-    styles.css
+  assets/
+    scripts/              ← third-party JS (e.g. zquery.min.js for manual setup)
+    styles/               ← additional stylesheets, fonts, etc.
 ```
 
 - 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`).
 - `app.js` is the single entry point — import components, create the store, and boot the router.
+- `global.css` lives next to `index.html` for easy access; the bundler hashes it into `global.<hash>.min.css` for production.
+- `assets/` holds static files that get copied to `dist/` as-is.
 
 ---
 
@@ -172,7 +180,7 @@ npx zquery bundle
 npx zquery bundle my-app/
 
 # Or pass a direct entry file (skips auto-detection)
-npx zquery bundle my-app/scripts/main.js
+npx zquery bundle my-app/app/main.js
 ```
 
 Output goes to `dist/` next to your `index.html`:
@@ -183,7 +191,8 @@ dist/
     index.html
     z-app.<hash>.js
     z-app.<hash>.min.js
-    styles/
+    global.<hash>.min.css
+    assets/
   local/                ← open from disk (file://) — no server needed
     index.html
     z-app.<hash>.js
@@ -196,7 +205,8 @@ dist/
 | --- | --- | --- |
 | `--out <path>` | `-o` | Custom output directory |
 | `--index <file>` | `-i` | Index HTML file (default: auto-detected) |
-| `--minimal` | `-m` | Only output HTML + bundled JS (skip static assets) |
+| `--minimal` | `-m` | Only output HTML, bundled JS, and global CSS (skip static assets) |
+| `--global-css <path>` | | Override global CSS input file (default: first `<link>` in HTML) |
 
 ### What the Bundler Does
 
@@ -204,7 +214,7 @@ dist/
    1. **HTML files** — `index.html` is checked first, then other `.html` files (root + one level deep).
    2. **Module scripts within HTML** — within each HTML file, a `<script type="module">` whose `src` resolves to `app.js` wins; otherwise the first module script tag is used.
    3. **JS file scan** — if no HTML match, JS files (up to 2 levels deep) are scanned in two passes: first for `$.router(` (the canonical app entry point), then for `$.mount(`, `$.store(`, or `mountAll(`.
-   4. **Convention fallbacks** — `scripts/app.js`, `src/app.js`, `js/app.js`, `app.js`, `main.js`.
+   4. **Convention fallbacks** — `app/app.js`, `scripts/app.js`, `src/app.js`, `js/app.js`, `app.js`, `main.js`.
 2. Resolves all `import` statements and topologically sorts dependencies
 3. Strips `import`/`export` syntax, wraps in an IIFE
 4. Embeds zQuery library and inlines `templateUrl` / `styleUrl` / `pages` files
@@ -246,8 +256,8 @@ location / {
 | `$.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 |
+| `$.component` `$.mount` `$.mountAll` `$.getInstance` `$.destroy` `$.components` `$.prefetch` | Component system |
+| `$.morph` `$.morphElement` | DOM morphing engine — LIS-based keyed reconciliation, `isEqualNode()` bail-outs, `z-skip` opt-out. Patches existing DOM to match new HTML without destroying unchanged nodes. Auto-key detection (`id`, `data-id`, `data-key`) — no `z-key` required. `$().html()` and `$().replaceWith()` auto-morph existing content; `$().morph()` for explicit morph |
 | `$.safeEval` | CSP-safe expression evaluator (replaces `eval` / `new Function`) |
 | `$.style` | Dynamically load global stylesheet file(s) at runtime |
 | `$.router` `$.getRouter` | SPA router |
@@ -260,16 +270,16 @@ location / {
 | `$.param` `$.parseQuery` | URL utils |
 | `$.storage` `$.session` | Storage wrappers |
 | `$.bus` | Event bus |
-| `$.version` | Library version |
+| `$.version` | Library version |\n| `$.libSize` | Minified bundle size string (e.g. `\"~91 KB\"`) |
 | `$.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 dev [root]` | Dev server with live-reload &amp; error overlay (port 3100). `--index` for custom HTML. |
+| `zquery dev [root]` | Dev server with live-reload, CSS hot-swap, error overlay, floating toolbar &amp; 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`) |
+| `zquery build` | Build the zQuery library (`dist/zquery.min.js`) |
 | `zquery --help` | Show CLI usage |
 
 For full method signatures, options, and examples, see **[API.md](API.md)**.
@@ -278,7 +288,7 @@ For full method signatures, options, and examples, see **[API.md](API.md)**.
 
 ## Editor Support
 
-The official **[zQuery for VS Code](https://marketplace.visualstudio.com/items?itemName=zQuery.zquery-vs-code)** extension provides autocomplete, hover docs, HTML directive support, and 140+ code snippets for every API method and directive. Install it from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=zQuery.zquery-vs-code) or search **"zQuery for VS Code"** in Extensions.
+The official **[zQuery for VS Code](https://marketplace.visualstudio.com/items?itemName=zQuery.zquery-vs-code)** extension provides autocomplete, hover docs, HTML directive support, and 185+ code snippets for every API method and directive. Install it from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=zQuery.zquery-vs-code) or search **"zQuery for VS Code"** in Extensions.
 
 ---
 

package/cli/commands/build.js

@@ -9,6 +9,7 @@
 
 const fs   = require('fs');
 const path = require('path');
+const zlib = require('zlib');
 const { minify, sizeKB } = require('../utils');
 
 function buildLibrary() {
@@ -34,7 +35,7 @@ function buildLibrary() {
     code = code.replace(/^import\s+[\s\S]*?from\s+['"].*?['"];?\s*$/gm, '');
     code = code.replace(/^export\s+(default\s+)?/gm, '');
     code = code.replace(/^export\s*\{[\s\S]*?\};\s*$/gm, '');
-    return `// --- ${file} ${'—'.repeat(60 - file.length)}\n${code.trim()}`;
+    return `// --- ${file} ${'-'.repeat(60 - file.length)}\n${code.trim()}`;
   });
 
   let indexCode = fs.readFileSync(path.join(process.cwd(), 'index.js'), 'utf-8');
@@ -42,18 +43,126 @@ function buildLibrary() {
   indexCode = indexCode.replace(/^export\s*\{[\s\S]*?\};\s*$/gm, '');
   indexCode = indexCode.replace(/^export\s+(default\s+)?/gm, '');
 
-  const banner = `/**\n * zQuery (zeroQuery) v${VERSION}\n * Lightweight Frontend Library\n * https://github.com/tonywied17/zero-query\n * (c) ${new Date().getFullYear()} Anthony Wiedman — MIT License\n */`;
+  const banner = `/**\n * zQuery (zeroQuery) v${VERSION}\n * Lightweight Frontend Library\n * https://github.com/tonywied17/zero-query\n * (c) ${new Date().getFullYear()} Anthony Wiedman - MIT License\n */`;
 
-  const bundle = `${banner}\n(function(global) {\n  'use strict';\n\n${parts.join('\n\n')}\n\n// --- index.js (assembly) ${'—'.repeat(42)}\n${indexCode.trim().replace("'__VERSION__'", `'${VERSION}'`)}\n\n})(typeof window !== 'undefined' ? window : globalThis);\n`;
+  const bundle = `${banner}\n(function(global) {\n  'use strict';\n\n${parts.join('\n\n')}\n\n// --- index.js (assembly) ${'-'.repeat(42)}\n${indexCode.trim().replace("'__VERSION__'", `'${VERSION}'`)}\n\n})(typeof window !== 'undefined' ? window : globalThis);\n`;
 
   fs.writeFileSync(OUT_FILE, bundle, 'utf-8');
-  fs.writeFileSync(MIN_FILE, minify(bundle, banner), 'utf-8');
+  const minified = minify(bundle, banner);
+  fs.writeFileSync(MIN_FILE, minified, 'utf-8');
+
+  // 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}'`);
+  fs.writeFileSync(OUT_FILE, outContent, 'utf-8');
+  fs.writeFileSync(MIN_FILE, minContent, 'utf-8');
 
   const elapsed = Date.now() - start;
   console.log(`  ✓ dist/zquery.js (${sizeKB(fs.readFileSync(OUT_FILE))} KB)`);
   console.log(`  ✓ dist/zquery.min.js (${sizeKB(fs.readFileSync(MIN_FILE))} KB)`);
   console.log(`  Done in ${elapsed}ms\n`);
 
+  // --- Create dist/zquery.dist.zip -----------------------------------------
+  const root = process.cwd();
+  const zipFiles = [
+    { src: OUT_FILE,                        name: 'zquery.js' },
+    { src: MIN_FILE,                        name: 'zquery.min.js' },
+    { src: path.join(root, 'LICENSE'),      name: 'LICENSE' },
+    { src: path.join(root, 'API.md'),       name: 'API.md' },
+    { src: path.join(root, 'README.md'),    name: 'README.md' },
+  ];
+
+  // Minimal ZIP builder (deflate via zlib, no external deps)
+  function buildZip(entries) {
+    const localHeaders = [];
+    const centralHeaders = [];
+    let offset = 0;
+
+    for (const { name, data } of entries) {
+      const nameBytes = Buffer.from(name, 'utf-8');
+      const compressed = zlib.deflateRawSync(data, { level: 9 });
+      const crc = crc32(data);
+      const compLen = compressed.length;
+      const uncompLen = data.length;
+
+      // Local file header
+      const local = Buffer.alloc(30 + nameBytes.length);
+      local.writeUInt32LE(0x04034b50, 0);   // signature
+      local.writeUInt16LE(20, 4);            // version needed
+      local.writeUInt16LE(0, 6);             // flags
+      local.writeUInt16LE(8, 8);             // compression: deflate
+      local.writeUInt16LE(0, 10);            // mod time
+      local.writeUInt16LE(0, 12);            // mod date
+      local.writeUInt32LE(crc, 14);
+      local.writeUInt32LE(compLen, 18);
+      local.writeUInt32LE(uncompLen, 22);
+      local.writeUInt16LE(nameBytes.length, 26);
+      local.writeUInt16LE(0, 28);            // extra field length
+      nameBytes.copy(local, 30);
+
+      localHeaders.push(Buffer.concat([local, compressed]));
+
+      // Central directory header
+      const central = Buffer.alloc(46 + nameBytes.length);
+      central.writeUInt32LE(0x02014b50, 0);
+      central.writeUInt16LE(20, 4);          // version made by
+      central.writeUInt16LE(20, 6);          // version needed
+      central.writeUInt16LE(0, 8);           // flags
+      central.writeUInt16LE(8, 10);          // compression: deflate
+      central.writeUInt16LE(0, 12);          // mod time
+      central.writeUInt16LE(0, 14);          // mod date
+      central.writeUInt32LE(crc, 16);
+      central.writeUInt32LE(compLen, 20);
+      central.writeUInt32LE(uncompLen, 24);
+      central.writeUInt16LE(nameBytes.length, 28);
+      central.writeUInt16LE(0, 30);          // extra field length
+      central.writeUInt16LE(0, 32);          // comment length
+      central.writeUInt16LE(0, 34);          // disk number
+      central.writeUInt16LE(0, 36);          // internal attrs
+      central.writeUInt32LE(0, 38);          // external attrs
+      central.writeUInt32LE(offset, 42);     // local header offset
+      nameBytes.copy(central, 46);
+      centralHeaders.push(central);
+
+      offset += local.length + compressed.length;
+    }
+
+    const centralDir = Buffer.concat(centralHeaders);
+    const eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(0x06054b50, 0);
+    eocd.writeUInt16LE(0, 4);               // disk number
+    eocd.writeUInt16LE(0, 6);               // central dir disk
+    eocd.writeUInt16LE(entries.length, 8);   // entries on disk
+    eocd.writeUInt16LE(entries.length, 10);  // total entries
+    eocd.writeUInt32LE(centralDir.length, 12);
+    eocd.writeUInt32LE(offset, 16);          // central dir offset
+    eocd.writeUInt16LE(0, 20);              // comment length
+
+    return Buffer.concat([...localHeaders, centralDir, eocd]);
+  }
+
+  function crc32(buf) {
+    let crc = 0xFFFFFFFF;
+    for (let i = 0; i < buf.length; i++) {
+      crc ^= buf[i];
+      for (let j = 0; j < 8; j++) {
+        crc = (crc >>> 1) ^ ((crc & 1) ? 0xEDB88320 : 0);
+      }
+    }
+    return (crc ^ 0xFFFFFFFF) >>> 0;
+  }
+
+  const entries = zipFiles
+    .filter(f => fs.existsSync(f.src))
+    .map(f => ({ name: f.name, data: fs.readFileSync(f.src) }));
+
+  const zipBuf = buildZip(entries);
+  const zipPath = path.join(DIST, 'zquery.dist.zip');
+  fs.writeFileSync(zipPath, zipBuf);
+  console.log(`  ✓ dist/zquery.dist.zip (${sizeKB(zipBuf)} KB) — ${entries.length} files`);
+
   return { DIST, OUT_FILE, MIN_FILE };
 }