zero-query 0.2.0 → 0.2.3

package/README.md

@@ -36,7 +36,7 @@ The preferred way to use zQuery is with the **pre-built browser bundle** (`zQuer
 
 ### 1. Get the library
 
-Download `dist/zQuery.min.js` from the [GitHub releases](https://github.com/tonywied17/zero-query), or clone and build:
+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
@@ -146,147 +146,84 @@ my-app/
 
 ## CLI Bundler (Optional)
 
-> **Beta.** The CLI bundler is functional but still maturing. The ES module setup above is the recommended and most reliable approach. The bundler is provided as a convenience for use cases where a single-file build is preferred.
+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.
 
-zQuery ships with a zero-dependency CLI that can compile your entire app — all ES modules, the library, external templates, and assets — into a **single bundled file**. This is useful for:
+### How It Works
 
-- Distributing an app as one `.html` + one `.js` file
-- Deploying to environments without a web server (open `index.html` from disk via `file://`)
-- Reducing HTTP requests on legacy hosting without HTTP/2
+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
 
-The CLI is included in the `zero-query` npm package. Install it to get the `zquery` command along with the library source and pre-built bundles:
-
 ```bash
-# Add to your project as a dev dependency (recommended)
 npm install zero-query --save-dev
-npx zquery bundle
-
-# Or install globally
-npm install -g zero-query
-zquery bundle
-
-# Or run once without installing (npx fetches it on demand)
-npx zero-query bundle
 ```
 
-The package includes:
-- `dist/zQuery.min.js` — pre-built browser bundle (ready to copy into your project)
-- `cli.js` — the CLI tool (`zquery build` / `zquery bundle`)
-- `src/` — library source modules
-
-### Commands
-
-#### `zquery build` — Build the Library
-
-Compiles the zQuery library source into `dist/zQuery.js` and `dist/zQuery.min.js`. This is the same as running `node build.js`.
+### Bundling
 
 ```bash
-zquery build                # one-time build
-zquery build --watch        # rebuild on source changes
-```
-
-#### `zquery bundle` — Bundle an App
-
-Walks the ES module import graph starting from an entry file, topologically sorts all dependencies, strips `import`/`export` syntax, and concatenates everything into a single IIFE with content-hashed filenames for cache-busting.
-
-```bash
-# Auto-detect entry from index.html's <script type="module">
-zquery bundle
-
-# Specify entry explicitly
-zquery bundle scripts/app.js
+# From inside your project directory (auto-detects entry from index.html)
+npx zquery bundle
 
-# Full example with all options
-zquery bundle scripts/app.js \
-  --out dist/ \
-  --include-lib \
-  --html index.html \
-  --watch
+# Or point to an entry from anywhere
+npx zquery bundle path/to/scripts/app.js
 ```
 
-### Bundle Options
-
-| Flag | Short | Description |
-| --- | --- | --- |
-| `--out <path>` | `-o` | Output directory (or file path — directory is extracted). Default: `dist/` |
-| `--include-lib` | `-L` | Embed `zquery.min.js` directly in the bundle (no separate script tag needed) |
-| `--html <file>` | — | Rewrite the HTML file: replaces `<script type="module">` with the bundle, copies assets into `dist/`, adjusts `<base href>` |
-| `--watch` | `-w` | Watch source files and rebuild automatically on changes |
-
-### What the Bundler Does
-
-1. **Import graph walking** — Starting from the entry file, recursively resolves all `import` statements (including side-effect `import './foo.js'`) and produces a topologically sorted dependency list.
+That's it. The output goes to `dist/` next to your `index.html`, with two sub-folders:
 
-2. **Module syntax stripping** — Removes `import`/`export` keywords while keeping all declarations. The output is plain browser-compatible JavaScript.
-
-3. **IIFE wrapping** — The concatenated code is wrapped in `(function() { 'use strict'; ... })()` to avoid polluting the global scope.
-
-4. **Library embedding** (`--include-lib`) — Finds `zquery.min.js` in common locations (`scripts/vendor/`, `dist/`, etc.) and embeds it at the top of the bundle. The resulting file is fully self-contained.
+```
+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
+```
 
-5. **External resource inlining** — Automatically detects `pages` configs, `templateUrl`, and `styleUrl` references in your components and inlines the referenced HTML/CSS files into the bundle as a `window.__zqInline` map. This enables `file://` support where `fetch()` would otherwise fail due to CORS.
+**`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.
 
-6. **HTML rewriting** (`--html`) — Rewrites the specified HTML file:
-   - Replaces `<script type="module" src="...">` with `<script defer src="bundle.js">`
-   - Removes the standalone zQuery `<script>` tag when `--include-lib` is used
-   - Preserves `<base href="/">` for SPA deep-route support, with an inline `file://` fallback that switches to `./`
-   - Copies all referenced assets (CSS, images, vendor JS) into the `dist/` folder
-   - Scans CSS files for `url()` references and copies those assets too
+**`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://`.
 
-7. **Minification** — Produces both a readable `z-<name>.<hash>.js` and a minified `z-<name>.<hash>.min.js` (comment stripping + whitespace collapsing). The content hash changes only when the bundle changes, enabling long-lived cache headers. Previous hashed builds are automatically cleaned on each rebuild.
+### Bundling the Starter App
 
-### Step-by-Step: Bundling Your Own App
+The zero-query repo includes a starter app you can bundle from the repo root:
 
 ```bash
-# 1. Install zero-query in your project
-cd my-app
-npm init -y                            # if you don't have a package.json yet
-npm install zero-query --save-dev
+# npm script (defined in package.json)
+npm run bundle:app
 
-# 2. Copy the pre-built library into your project
-cp node_modules/zero-query/dist/zQuery.min.js scripts/vendor/
-
-# 3. Bundle the app
-npx zquery bundle scripts/app.js -o dist/ -L --html index.html
-
-# Output (filenames are content-hashed for cache-busting):
-#   dist/index.html              ← rewritten HTML (src updated automatically)
-#   dist/z-app.a1b2c3d4.js      ← hashed bundle (library + app + inlined templates)
-#   dist/z-app.a1b2c3d4.min.js  ← minified version
-#   dist/styles/                 ← copied CSS
-#   dist/scripts/vendor/         ← copied vendor assets
-
-# 4. Open directly in a browser — no server needed
-start dist/index.html    # Windows
-open dist/index.html     # macOS
+# or equivalently
+npx zquery bundle examples/starter-app/scripts/app.js
 ```
 
-#### Bundling the Starter App (from source)
+### Optional Flags
 
-If you cloned the zero-query repository:
-
-```bash
-node build.js
-cp dist/zQuery.min.js examples/starter-app/scripts/vendor/
-cd examples/starter-app
-npx zquery bundle scripts/app.js -o dist/ -L --html index.html
-start dist/index.html
-```
-
-### Hash Routing on `file://`
+| 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 |
 
-When the bundled app is opened via `file://`, the router automatically detects the protocol and switches to **hash-based routing** (`#/about` instead of `/about`). No configuration needed — `z-link` attributes and programmatic navigation work identically.
+### What Happens Under the Hood
 
-### Preparing Your App for Bundling
+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.
 
-The bundler is designed to work with the standard zQuery project structure out of the box. A few things to keep in mind:
+### Tips
 
-- **Use relative imports** — `import './components/home.js'` (not bare specifiers like `import 'home'`)
-- **One component per file** — The import graph walker resolves each file once
-- **`import.meta.url`** — Automatically replaced with a `document.baseURI`-based equivalent
-- **External templates** — `templateUrl`, `styleUrl`, and `pages` configs are automatically detected and inlined. No changes to your component code are needed.
-- **Vendor scripts** — If using `--include-lib`, the bundler finds `zquery.min.js` in `scripts/vendor/`, `vendor/`, `lib/`, or `dist/`
+- **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
 
 ---
 
@@ -1303,14 +1240,12 @@ 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
-npx zquery build --watch
 ```
 
+> **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.
 
 ---
@@ -1337,10 +1272,13 @@ The starter app includes: Home, Counter (reactive state + z-model), Todos (globa
 You can also build a fully self-contained bundled version of the starter app:
 
 ```bash
-cd examples/starter-app
-npx zquery bundle scripts/app.js -o dist/ -L --html index.html
+npm run bundle:app
 
-# Open dist/index.html directly — no server needed
+# 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.
@@ -1350,21 +1288,24 @@ See [CLI Bundler](#cli-bundler-optional) for details.
 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):**