zero-query 0.3.1 → 0.5.2

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/images/logo.svg" alt="zQuery logo" width="300" height="300">
+  <img src=".github/images/logo.svg" alt="zQuery logo" width="300" height="300">
 </p>
 
 <h1 align="center">zQuery</h1>
@@ -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 ~45 KB minified browser bundle. Works out of the box with ES modules — no build step required. An optional CLI bundler is available for single-file distribution.**
+> **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.**
 
 ## Features
 
 | Module | Highlights |
 | --- | --- |
 | **Core `$()`** | jQuery-like chainable selectors, traversal, DOM manipulation, events, animation |
-| **Components** | Reactive state, template literals, `@event` delegation, `z-model` two-way binding, scoped styles, lifecycle hooks |
+| **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) |
 | **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 |
@@ -46,11 +46,20 @@ Scaffold a new project and start the server:
 
 ```bash
 npx zquery create my-app
-cd my-app
-npx zquery dev
+npx zquery dev my-app
 ```
 
-The `create` command generates a ready-to-run project with `index.html`, a router, two components, and styles. The dev server watches for file changes, hot-swaps CSS in-place, full-reloads on other changes, and handles SPA fallback routing.
+> **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.
+
+#### Error Overlay
+
+The dev server includes a **full-screen error overlay** that surfaces errors directly in the browser — similar to Vite or Angular:
+
+- **Syntax errors** — JS files are validated on every save *before* the reload is triggered. If a syntax error is found the page stays intact and a dark overlay appears with the error message, file path, line:column, and a code frame pointing to the exact location.
+- **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.
 
 ### Alternative: Manual Setup (No npm)
 
@@ -59,8 +68,8 @@ If you prefer **zero tooling**, download `dist/zQuery.min.js` from the [GitHub r
 ```bash
 git clone https://github.com/tonywied17/zero-query.git
 cd zero-query
-node build.js
-# → dist/zQuery.min.js  (~45 KB)
+npx zquery build
+# → dist/zQuery.min.js  (~54 KB)
 ```
 
 ### Include in HTML
@@ -91,6 +100,7 @@ node build.js
 // scripts/app.js
 import './components/home.js';
 import './components/about.js';
+import './components/contacts/contacts.js';
 import { routes } from './routes.js';
 
 $.router({ el: '#app', routes, fallback: 'not-found' });
@@ -131,25 +141,38 @@ my-app/
     components/
       home.js
       counter.js
+      todos.js
+      api-demo.js
       about.js
+      not-found.js
+      contacts/           ← folder component (templateUrl + styleUrl)
+        contacts.js
+        contacts.html
+        contacts.css
+  styles/
+    styles.css
 ```
 
 - 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.
 
 ---
 
 ## 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 index.html
+# Auto-detect entry from any .html with a module script
 npx zquery bundle
 
-# Or specify an entry point
-npx zquery bundle path/to/scripts/app.js
+# 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`:
@@ -172,11 +195,16 @@ 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
 
-1. Reads `index.html` for the `<script type="module">` entry point
+1. **Entry detection** — a strict precedence order ensures the correct file is chosen:
+   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`.
 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
@@ -216,7 +244,7 @@ location / {
 | `$.all()` | Collection selector → `ZQueryCollection` |
 | `$.id` `$.class` `$.classes` `$.tag` `$.children` | Quick DOM refs |
 | `$.create` | Element factory |
-| `$.ready` `$.on` | DOM ready, global delegation |
+| `$.ready` `$.on` `$.off` | DOM ready, global event delegation & direct listeners |
 | `$.fn` | Collection prototype (extend it) |
 | `$.component` `$.mount` `$.mountAll` `$.getInstance` `$.destroy` `$.components` | Component system |
 | `$.style` | Dynamically load global stylesheet file(s) at runtime |
@@ -231,13 +259,14 @@ location / {
 | `$.storage` `$.session` | Storage wrappers |
 | `$.bus` | Event bus |
 | `$.version` | Library version |
+| `$.meta` | Build metadata (populated by CLI bundler) |
 | `$.noConflict` | Release `$` global |
 
 | CLI Command | Description |
 | --- | --- |
-| `zquery create [dir]` | Scaffold a new project (index.html, scripts, styles) |
-| `zquery dev [root]` | Dev server with live-reload (port 3100) |
-| `zquery bundle [entry]` | Bundle app into a single IIFE file |
+| `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 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 |
 
@@ -247,7 +276,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 55+ 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 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.
 
 ---
 

package/cli/args.js

@@ -0,0 +1,33 @@
+/**
+ * cli/args.js — CLI argument parsing helpers
+ *
+ * Provides the raw args array and two helper functions for reading
+ * named flags (--verbose, -v) and valued options (--port 8080, -p 8080).
+ */
+
+'use strict';
+
+const args = process.argv.slice(2);
+
+/**
+ * Check whether a boolean flag is present.
+ *   flag('verbose', 'v')  →  true if --verbose or -v appears
+ */
+function flag(name, short) {
+  const i = args.indexOf(`--${name}`);
+  const j = short ? args.indexOf(`-${short}`) : -1;
+  return i !== -1 || j !== -1;
+}
+
+/**
+ * Read a string-valued option.
+ *   option('port', 'p', '3100')  →  the value after --port / -p, or '3100'
+ */
+function option(name, short, fallback) {
+  let i = args.indexOf(`--${name}`);
+  if (i === -1 && short) i = args.indexOf(`-${short}`);
+  if (i !== -1 && i + 1 < args.length) return args[i + 1];
+  return fallback;
+}
+
+module.exports = { args, flag, option };

package/cli/commands/build.js

@@ -0,0 +1,58 @@
+/**
+ * cli/commands/build.js — library build command
+ *
+ * Concatenates the zQuery source modules into dist/zquery.js and
+ * dist/zquery.min.js.
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { minify, sizeKB } = require('../utils');
+
+function buildLibrary() {
+  const pkg     = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'));
+  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',
+  ];
+
+  const DIST     = path.join(process.cwd(), 'dist');
+  const OUT_FILE = path.join(DIST, 'zquery.js');
+  const MIN_FILE = path.join(DIST, 'zquery.min.js');
+
+  const start = Date.now();
+  if (!fs.existsSync(DIST)) fs.mkdirSync(DIST, { recursive: true });
+
+  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, '');
+    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()}`;
+  });
+
+  let indexCode = fs.readFileSync(path.join(process.cwd(), 'index.js'), 'utf-8');
+  indexCode = indexCode.replace(/^import\s+[\s\S]*?from\s+['"].*?['"];?\s*$/gm, '');
+  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 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 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`);
+
+  return { DIST, OUT_FILE, MIN_FILE };
+}
+
+module.exports = buildLibrary;