zero-query 0.1.2 → 0.2.2

package/README.md

@@ -14,7 +14,7 @@
 
 </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. No build step required.**
+> **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.**
 
 ## Features
 
@@ -30,18 +30,22 @@
 
 ---
 
-## Quick Start (Browser Bundle — Recommended)
+## Quick Start (Browser Bundle + ES Modules — Recommended)
 
-The preferred way to use zQuery is with the **pre-built browser bundle** (`zQuery.min.js`). No npm install, no bundler, no transpiler.
+The preferred way to use zQuery is with the **pre-built browser bundle** (`zQuery.min.js`) paired with standard **ES module** `<script type="module">` tags for your app code. No npm install, no bundler, no transpiler — just grab the library and start writing components.
 
-### 1. Build the bundle (one time)
+### 1. Get the library
+
+Download `dist/zQuery.min.js` from the [GitHub releases](https://github.com/tonywied17/zero-query/releases/tag/RELEASE), or clone and build:
 
 ```bash
+git clone https://github.com/tonywied17/zero-query.git
+cd zero-query
 node build.js
+# → dist/zQuery.js  (~78 KB, readable)
+# → dist/zQuery.min.js  (~45 KB, production)
 ```
 
-This creates `dist/zQuery.js` and `dist/zQuery.min.js`.
-
 ### 2. Copy into your project
 
 ```
@@ -105,7 +109,9 @@ const router = $.router({
 });
 ```
 
-That's it — a fully working SPA with zero build tools.
+That's it — a fully working SPA with zero build tools. Your files are served as individual ES modules, which means instant browser caching, easy debugging, and native import/export.
+
+> **Want a single-file build instead?** See the [CLI Bundler](#cli-bundler-optional) section below for an optional bundling step that compiles your entire app into one file.
 
 ---
 
@@ -138,6 +144,89 @@ my-app/
 
 ---
 
+## CLI Bundler (Optional)
+
+zQuery includes a zero-dependency CLI that compiles your entire app — ES modules, the library, external templates, and assets — into a **single bundled file** you can open directly from disk. Useful for offline distribution, `file://` deployments, or reducing HTTP requests.
+
+### How It Works
+
+The bundler auto-detects your entry point, embeds the zQuery library, resolves all ES module imports, inlines external templates, rewrites your `index.html`, and copies assets into a `dist/` folder. **No flags needed** — just point it at your app.
+
+### Installation
+
+```bash
+npm install zero-query --save-dev
+```
+
+### Bundling
+
+```bash
+# From inside your project directory (auto-detects entry from index.html)
+npx zquery bundle
+
+# Or point to an entry from anywhere
+npx zquery bundle path/to/scripts/app.js
+```
+
+That's it. The output goes to `dist/` next to your `index.html`, with two sub-folders:
+
+```
+dist/
+  server/                   ← deploy to your web server
+    index.html              ← has <base href="/"> for SPA deep routes
+    z-app.a1b2c3d4.js      ← readable bundle (library + app + templates)
+    z-app.a1b2c3d4.min.js  ← minified bundle
+    styles/                 ← copied CSS
+    scripts/vendor/         ← copied vendor assets
+  local/                    ← open from disk (file://)
+    index.html              ← relative paths, no <base> tag
+    z-app.a1b2c3d4.js      ← same bundle
+    ...                     ← same assets
+```
+
+**`server/`** — includes `<base href="/">` so deep-route refreshes (e.g. `/docs/router`) resolve assets from the site root. Deploy this folder to your web server.
+
+**`local/`** — omits the `<base>` tag so paths resolve relative to the HTML file. Open `local/index.html` directly from disk — no server needed, zero console errors. The router auto-switches to hash mode on `file://`.
+
+### Bundling the Starter App
+
+The zero-query repo includes a starter app you can bundle from the repo root:
+
+```bash
+# npm script (defined in package.json)
+npm run bundle:app
+
+# or equivalently
+npx zquery bundle examples/starter-app/scripts/app.js
+```
+
+### Optional Flags
+
+| Flag | Short | Description |
+| --- | --- | --- |
+| `--out <path>` | `-o` | Custom output directory (default: `dist/` next to `index.html`) |
+| `--html <file>` | — | Use a specific HTML file instead of the auto-detected one |
+| `--watch` | `-w` | Watch source files and rebuild on changes |
+
+### What Happens Under the Hood
+
+1. **Entry detection** — Reads `index.html` for `<script type="module" src="...">`, or falls back to `scripts/app.js`, `app.js`, etc.
+2. **Import graph** — Recursively resolves all `import` statements and topologically sorts them (leaves first).
+3. **Module syntax stripping** — Removes `import`/`export` keywords, keeps declarations. Output is plain browser JS.
+4. **Library embedding** — Finds `zquery.min.js` in your project or the package. Auto-builds from source if not found.
+5. **Template inlining** — Detects `templateUrl`, `styleUrl`, and `pages` configs and inlines the referenced files so `file://` works without CORS issues.
+6. **HTML rewriting** — Replaces `<script type="module">` with the bundle, removes the standalone library tag, and produces two output directories: `dist/server/` (with `<base href="/">` for web servers) and `dist/local/` (relative paths for `file://`). Assets are copied into both.
+7. **Minification** — Produces hashed filenames (`z-app.<hash>.js` / `.min.js`) for cache-busting. Previous builds are cleaned automatically.
+
+### Tips
+
+- **Use relative imports** — `import './components/home.js'` (not bare specifiers)
+- **One component per file** — the import walker resolves each file once
+- **`import.meta.url`** is automatically replaced at bundle time
+- **Hash routing** — on `file://`, the router switches to hash mode automatically
+
+---
+
 ## Selectors & DOM: `$(selector)` & `$.all(selector)`
 
 zQuery provides two selector functions:
@@ -433,7 +522,7 @@ Components can load their HTML templates and CSS from external files instead of
 Relative `templateUrl`, `styleUrl`, and `pages.dir` paths are automatically resolved **relative to the component file** — no extra configuration needed:
 
 ```js
-// File: scripts/components/widget/index.js
+// File: scripts/components/widget/widget.js
 $.component('my-widget', {
   templateUrl: 'template.html',        // → scripts/components/widget/template.html
   styleUrl:    'styles.css',           // → scripts/components/widget/styles.css
@@ -569,7 +658,7 @@ $.style('overrides.css');
 The `pages` option is a high-level shorthand for components that display content from multiple HTML files in a directory (e.g. documentation, wizards, tabbed content). It replaces the need to manually build a `templateUrl` object map and maintain a separate page list.
 
 ```js
-// File: scripts/components/docs/index.js
+// File: scripts/components/docs/docs.js
 $.component('docs-page', {
   pages: {
     dir:     'pages',                  // → scripts/components/docs/pages/
@@ -1146,15 +1235,17 @@ mq('.card').addClass('active');
 ## Building from Source
 
 ```bash
-# One-time build
+# One-time library build
 node build.js
 # → dist/zQuery.js  (development)
 # → dist/zQuery.min.js  (production)
 
-# Watch mode (rebuilds on file changes)
-node build.js --watch
+# Or use the CLI
+npx zquery build
 ```
 
+> **Note:** `npx zquery build` and `node build.js` must be run from the zero-query project root (where `src/` and `index.js` live). If you've added a `build` script to your own `package.json`, `npm run build` handles the working directory for you.
+
 The build script is zero-dependency — just Node.js. It concatenates all ES modules into a single IIFE and strips import/export statements. The minified version strips comments and collapses whitespace. For production builds, pipe through Terser for optimal compression.
 
 ---
@@ -1163,7 +1254,7 @@ The build script is zero-dependency — just Node.js. It concatenates all ES mod
 
 ```bash
 # From the project root
-node build.js                                    # build the bundle
+node build.js                                    # build the library
 cp dist/zQuery.min.js examples/starter-app/scripts/vendor/  # copy to app
 
 # Start the dev server (uses zero-http)
@@ -1176,26 +1267,45 @@ npx serve examples/starter-app
 
 The starter app includes: Home, Counter (reactive state + z-model), Todos (global store + subscriptions), API Docs (full reference), and About pages.
 
+#### Bundled Version (Single-File)
+
+You can also build a fully self-contained bundled version of the starter app:
+
+```bash
+npm run bundle:app
+
+# Deploy the server build
+# → dist/server/index.html (with <base href="/"> for web servers)
+
+# Or open the local build from disk — no server needed
+start examples/starter-app/dist/local/index.html
+```
+
+See [CLI Bundler](#cli-bundler-optional) for details.
+
 ### Local Dev Server
 
 The project ships with a lightweight dev server powered by [zero-http](https://github.com/tonywied17/zero-http). It handles history-mode SPA routing (all non-file requests serve `index.html`).
 
 ```bash
-# Default: port 3000
+# Serve with SPA fallback routing (recommended during development)
 npm run serve
 
 # Custom port
 node examples/starter-app/local-server.js 8080
 
+# Watch mode — auto-rebuild bundle on file changes
+npm run dev
+
 # Or install zero-http yourself for any project
 npm install zero-http --save-dev
 ```
 
-The server source is at `examples/starter-app/local-server.js` — about 30 lines of code.
+`npm run serve` gives the fastest feedback loop — edit your ES module source files and refresh the browser. Use `npm run dev` when you need the bundled output to update automatically as you work.
 
 ### Production Deployment
 
-For history-mode routing in production, configure your web server to rewrite non-file requests to `index.html`.
+For production, use the bundled `dist/server/` output. It includes `<base href="/">` so deep-route refreshes resolve assets correctly. Configure your web server to rewrite non-file requests to `index.html`:
 
 **Apache (.htaccess):**
 
@@ -1262,6 +1372,12 @@ location /my-app/ {
 | `$.version` | Library version |
 | `$.noConflict` | Release `$` global |
 
+| CLI | Description |
+| --- | --- |
+| `zquery build` | Build the zQuery library (`dist/zQuery.min.js`) |
+| `zquery bundle [entry]` | Bundle app ES modules into a single IIFE file |
+| `zquery --help` | Show CLI usage and options |
+
 For full method signatures and options, see [API.md](API.md).
 
 ---