npm - zero-query - Versions diffs - 0.1.0 - Mend

zero-query 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,1271 @@
+<p align="center">
+  <img src="docs/images/logo.svg" alt="zQuery logo" width="300" height="300">
+</p>
+<h1 align="center">zQuery</h1>
+<p align="center">
+[![npm version](https://img.shields.io/npm/v/@tonywied17/zero-query.svg)](https://www.npmjs.com/package/@tonywied17/zero-query)
+[![npm downloads](https://img.shields.io/npm/dm/@tonywied17/zero-query.svg)](https://www.npmjs.com/package/@tonywied17/zero-query)
+[![GitHub](https://img.shields.io/badge/GitHub-zero--query-blue.svg)](https://github.com/tonywied17/zero-query)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](package.json)
+</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.**
+## 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 |
+| **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 |
+| **Reactive** | Deep proxy reactivity, Signals, computed values, effects |
+| **Utils** | debounce, throttle, pipe, once, sleep, escapeHtml, uuid, deepClone, deepMerge, storage/session wrappers, event bus |
+---
+## Quick Start (Browser Bundle — Recommended)
+The preferred way to use zQuery is with the **pre-built browser bundle** (`zQuery.min.js`). No npm install, no bundler, no transpiler.
+### 1. Build the bundle (one time)
+```bash
+node build.js
+```
+This creates `dist/zQuery.js` and `dist/zQuery.min.js`.
+### 2. Copy into your project
+```
+my-app/
+  index.html
+  scripts/
+    vendor/
+      zQuery.min.js      ← copy here
+    app.js
+    routes.js
+    store.js
+    components/
+      home.js
+      about.js
+```
+### 3. Include in HTML
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>My App</title>
+  <!-- Global styles — <link rel> in the HTML head is the recommended approach
+       for app-wide CSS (resets, layout, themes). Prevents FOUC reliably. -->
+  <link rel="stylesheet" href="styles/styles.css">
+  <!-- Load zQuery (global $ and zQuery are available immediately) -->
+  <script src="scripts/vendor/zQuery.min.js"></script>
+  <!-- Your app code as ES module (components use $ globally) -->
+  <script type="module" src="scripts/app.js"></script>
+</head>
+<body>
+  <nav>
+    <a z-link="/">Home</a>
+    <a z-link="/about">About</a>
+  </nav>
+  <div id="app"></div>
+</body>
+</html>
+```
+### 4. Register components and boot the router
+```js
+// scripts/app.js
+import './components/home.js';
+import './components/about.js';
+import { routes } from './routes.js';
+// Global styles are loaded via <link rel="stylesheet"> in index.html (recommended).
+// $.style() is available for dynamic stylesheets, runtime overrides, or theme switching.
+const router = $.router({
+  el: '#app',
+  routes,
+  fallback: 'not-found',
+});
+```
+That's it — a fully working SPA with zero build tools.
+---
+## Recommended Project Structure
+```
+my-app/
+  index.html                 ← entry point
+  scripts/
+    vendor/
+      zQuery.min.js          ← the built library
+    app.js                   ← boot: imports components, creates router & store
+    app.css                  ← global styles (linked in index.html via <link rel>)
+    routes.js                ← route definitions
+    store.js                 ← global store config
+    components/
+      home.js                ← each page/component in its own file
+      counter.js
+      todos.js
+      about.js
+      not-found.js
+```
+**Conventions:**
+- Place `zQuery.min.js` in a `vendor/` folder.
+- One component per file inside `components/`.
+- Store and routes get their own files at the `scripts/` root.
+- `app.js` is the single entry point — import components, create the store, and boot the router.
+- Component names **must contain a hyphen** (Web Component convention): `home-page`, `app-counter`, etc.
+---
+## Selectors & DOM: `$(selector)` & `$.all(selector)`
+zQuery provides two selector functions:
+- **`$(selector)`** — returns a **single element** (`querySelector`) or `null`
+- **`$.all(selector)`** — returns a **collection** (`querySelectorAll`) as a chainable `ZQueryCollection`
+Both also accept DOM elements, NodeLists, HTML strings, and (for `$` only) a function for DOM-ready.
+```js
+// Single element (querySelector)
+const card = $('.card');           // first .card element (or null)
+card.classList.add('active');      // plain DOM API
+// Collection (querySelectorAll)
+$.all('.card').addClass('active').css({ opacity: '1' });
+// Create element from HTML
+const el = $('<div class="alert">Hello!</div>');
+document.body.appendChild(el);
+// DOM ready shorthand
+$(() => {
+  console.log('DOM is ready');
+});
+// Wrap an existing element
+$(document.getElementById('app'));  // returns the element as-is
+```
+### Quick-Ref Shortcuts
+```js
+$.id('myId')            // document.getElementById('myId')
+$.class('myClass')      // document.querySelector('.myClass')
+$.classes('myClass')    // Array.from(document.getElementsByClassName('myClass'))
+$.tag('div')            // Array.from(document.getElementsByTagName('div'))
+$.children('parentId')  // Array.from of children of #parentId
+```
+### Element Creation
+```js
+const btn = $.create('button', {
+  class: 'primary',
+  style: { padding: '10px' },
+  onclick: () => alert('clicked'),
+  data: { action: 'submit' }
+}, 'Click Me');
+document.body.appendChild(btn);
+```
+### Collection Methods (on `ZQueryCollection` via `$.all()`)
+**Traversal:** `find()`, `parent()`, `closest()`, `children()`, `siblings()`, `next()`, `prev()`, `filter()`, `not()`, `has()`
+**Iteration:** `each()`, `map()`, `first()`, `last()`, `eq(i)`, `toArray()`
+**Classes:** `addClass()`, `removeClass()`, `toggleClass()`, `hasClass()`
+**Attributes:** `attr()`, `removeAttr()`, `prop()`, `data()`
+**Content:** `html()`, `text()`, `val()`
+**DOM Manipulation:** `append()`, `prepend()`, `after()`, `before()`, `wrap()`, `remove()`, `empty()`, `clone()`, `replaceWith()`
+**CSS / Dimensions:** `css()`, `width()`, `height()`, `offset()`, `position()`
+**Visibility:** `show()`, `hide()`, `toggle()`
+**Events:** `on()`, `off()`, `one()`, `trigger()`, `click()`, `submit()`, `focus()`, `blur()`
+**Animation:** `animate()`, `fadeIn()`, `fadeOut()`, `slideToggle()`
+**Forms:** `serialize()`, `serializeObject()`
+### Delegated Events
+```js
+// Direct event on a collection
+$.all('.btn').on('click', (e) => console.log('clicked', e.target));
+// Delegated event (like jQuery's .on with selector)
+$.all('#list').on('click', '.item', function(e) {
+  console.log('Item clicked:', this.textContent);
+});
+// One-time event
+$.all('.btn').one('click', () => console.log('fires once'));
+// Custom event
+$.all('.widget').trigger('custom:update', { value: 42 });
+```
+### Global Delegation
+```js
+// Listen for clicks on any .delete-btn anywhere in the document
+$.on('click', '.delete-btn', function(e) {
+  this.closest('.row').remove();
+});
+```
+### Extend Collection Prototype
+```js
+// Add custom methods to all collections (like $.fn in jQuery)
+$.fn.highlight = function(color = 'yellow') {
+  return this.css({ background: color });
+};
+$.all('.important').highlight('#ff0');
+```
+---
+## Components
+Declarative components with reactive state, template literals, event delegation, two-way binding, scoped styles, and lifecycle hooks. No JSX, no virtual DOM, no build step.
+### Defining a Component
+```js
+$.component('app-counter', {
+  // Initial state (object or function returning object)
+  state: () => ({ count: 0, step: 1 }),
+  // Lifecycle hooks
+  init()      { /* runs before first render */ },
+  mounted()   { /* runs after first render & DOM insert */ },
+  updated()   { /* runs after every re-render */ },
+  destroyed() { /* runs on destroy — clean up subscriptions */ },
+  // Methods (available as this.methodName and in @event bindings)
+  increment() { this.state.count += this.state.step; },
+  decrement() { this.state.count -= this.state.step; },
+  reset()     { this.state.count = 0; },
+  // Template (required) — return an HTML string
+  render() {
+    return `
+      <div class="counter">
+        <h2>Count: ${this.state.count}</h2>
+        <button @click="decrement">−</button>
+        <button @click="reset">Reset</button>
+        <button @click="increment">+</button>
+        <input z-model="step" type="number" min="1">
+      </div>
+    `;
+  },
+  // Scoped styles (optional — auto-prefixed to this component)
+  styles: `
+    .counter { text-align: center; }
+    button { margin: 4px; }
+  `
+});
+```
+### Mounting
+```js
+// Mount into a specific element
+$.mount('#app', 'app-counter');
+// Mount with props
+$.mount('#app', 'app-counter', { initialCount: 10 });
+// Auto-mount: scan DOM for registered custom tags
+$.mountAll();  // finds all <app-counter> tags and mounts them
+```
+### Directives
+| Directive | Purpose | Example |
+| --- | --- | --- |
+| `@event` | Delegated event binding | `@click="save"` or `@click="save(1, 'draft')"` |
+| `@event.prevent` | `preventDefault()` modifier | `@submit.prevent="handleForm"` |
+| `@event.stop` | `stopPropagation()` modifier | `@click.stop="toggle"` |
+| `z-model` | Reactive two-way input binding | `<input z-model="name">` |
+| `z-model` + `z-lazy` | Update on blur instead of every keystroke | `<input z-model="search" z-lazy>` |
+| `z-model` + `z-trim` | Trim whitespace before writing to state | `<input z-model="name" z-trim>` |
+| `z-model` + `z-number` | Force numeric conversion | `<input z-model="qty" z-number>` |
+| `z-ref` | Element reference | `<input z-ref="emailInput">` → `this.refs.emailInput` |
+### Two-Way Binding (`z-model`)
+`z-model` creates a **reactive two-way sync** between a form element and a state property. When the user types, state updates; when state changes, the element updates. Other parts of the template referencing the same state value re-render instantly.
+Focus and cursor position are **automatically preserved** during re-renders.
+```js
+$.component('profile-form', {
+  state: () => ({
+    user: { name: '', email: '' },
+    age: 25,
+    plan: 'free',
+    tags: [],
+  }),
+  render() {
+    const s = this.state;
+    return `
+      <!-- Text input -- live display updates as you type -->
+      <input z-model="user.name" z-trim placeholder="Name">
+      <p>Hello, ${s.user.name || 'stranger'}!</p>
+      <!-- Nested key, email type -->
+      <input z-model="user.email" type="email" placeholder="Email">
+      <!-- Number -- auto-converts to Number -->
+      <input z-model="age" type="number" min="0">
+      <p>Age: ${s.age} (type: ${typeof s.age})</p>
+      <!-- Radio group -->
+      <label><input z-model="plan" type="radio" value="free"> Free</label>
+      <label><input z-model="plan" type="radio" value="pro"> Pro</label>
+      <p>Plan: ${s.plan}</p>
+      <!-- Select multiple -- syncs as array -->
+      <select z-model="tags" multiple>
+        <option>javascript</option>
+        <option>html</option>
+        <option>css</option>
+      </select>
+      <p>Tags: ${s.tags.join(', ')}</p>
+    `;
+  }
+});
+```
+**Supported elements:** text inputs, textarea, number/range, checkbox, radio, select, select-multiple, contenteditable.
+**Nested keys:** `z-model="user.name"` binds to `this.state.user.name`.
+**Modifiers:** `z-lazy` (change event), `z-trim` (strip whitespace), `z-number` (force numeric). Combinable.
+### Event Arguments
+```js
+// Pass arguments to methods from templates
+// Supports: strings, numbers, booleans, null, state references
+`<button @click="remove(${item.id})">Delete</button>`
+`<button @click="setFilter('active')">Active</button>`
+`<button @click="update(state.count)">Update</button>`
+```
+### Props
+Props are passed as attributes on the custom element tag or via `$.mount()`:
+```js
+$.component('user-card', {
+  render() {
+    return `<div class="card"><h3>${this.props.name}</h3></div>`;
+  }
+});
+// Via mount
+$.mount('#target', 'user-card', { name: 'Tony' });
+// Via HTML tag (auto-mounted)
+// <user-card name="Tony"></user-card>
+```
+### Instance API
+```js
+const instance = $.mount('#app', 'my-component');
+instance.state.count = 5;          // trigger re-render
+instance.setState({ count: 5 });   // batch update
+instance.emit('change', { v: 1 }); // dispatch custom event (bubbles)
+instance.refs.myInput.focus();      // access z-ref elements
+instance.destroy();                 // teardown
+```
+### Getting & Destroying Instances
+```js
+const inst = $.getInstance('#app');  // get instance for element
+$.destroy('#app');                   // destroy component at element
+$.components();                      // get registry of all definitions (debug)
+```
+### External Templates & Styles (`templateUrl` / `styleUrl`)
+Components can load their HTML templates and CSS from external files instead of defining them inline. This is useful for large components, maintaining separation of concerns, or organizing components into folder structures.
+**Relative Path Resolution:**
+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
+$.component('my-widget', {
+  templateUrl: 'template.html',        // → scripts/components/widget/template.html
+  styleUrl:    'styles.css',           // → scripts/components/widget/styles.css
+});
+```
+> zQuery auto-detects the calling module's URL at registration time. If you need to override the resolved base, pass a `base` string (e.g. `base: 'scripts/shared/'`). Absolute paths and full URLs are never affected.
+**`styleUrl`** — load styles from a CSS file:
+```js
+$.component('my-widget', {
+  state: { title: 'Hello' },
+  render() {
+    return `<div class="widget"><h2>${this.state.title}</h2></div>`;
+  },
+  styleUrl: 'styles.css'
+});
+```
+**`templateUrl`** — load HTML template from a file:
+```js
+$.component('my-widget', {
+  state: { title: 'Hello', items: ['A', 'B'] },
+  templateUrl: 'template.html',
+  styleUrl:    'styles.css'
+});
+```
+The template file uses `{{expression}}` interpolation to access component state:
+```html
+<!-- components/my-widget/template.html -->
+<div class="widget">
+  <h2>{{title}}</h2>
+  <p>Item count: {{items.length}}</p>
+</div>
+```
+> **Notes:**
+> - If both `render()` and `templateUrl` are defined, `render()` takes priority.
+> - If both `styles` and `styleUrl` are defined, they are merged.
+> - Templates and styles are fetched once per component definition and cached — multiple instances share the same cache.
+> - Relative paths resolve relative to the component file automatically. Absolute paths and full URLs are used as-is.
+> - `{{expression}}` has access to all `state` properties via a `with(state)` context.
+### Multiple Templates — `templateUrl` as object or array
+`templateUrl` also accepts an **object map** or **array** of URLs. When multiple templates are loaded, they are available inside the component via `this.templates` — a keyed map you can reference in your `render()` function.
+```js
+// Object form — keyed by name
+$.component('docs-page', {
+  templateUrl: {
+    'router':     'pages/router.html',
+    'store':      'pages/store.html',
+    'components': 'pages/components.html',
+  },
+  render() {
+    const page = this.props.$params.section || 'router';
+    return `<div>${this.templates[page]}</div>`;
+  }
+});
+// Array form — keyed by index
+$.component('multi-step', {
+  templateUrl: ['pages/step1.html', 'pages/step2.html'],
+  render() {
+    return `<div>${this.templates[this.state.step]}</div>`;
+  }
+});
+```
+### Multiple Stylesheets — `styleUrl` as array
+`styleUrl` can also accept an **array of URLs**. All stylesheets are fetched in parallel, concatenated, and scoped to the component.
+```js
+$.component('my-widget', {
+  styleUrl: [
+    '../shared/base.css',
+    'styles.css',
+  ],
+  render() { return '<div class="widget">Content</div>'; }
+});
+```
+### Global Stylesheets
+**Recommended:** Use a standard `<link rel="stylesheet">` tag in your `index.html` `<head>` for app-wide CSS (resets, layout, themes). This is the most reliable way to prevent FOUC (Flash of Unstyled Content) because the browser loads the stylesheet before first paint — no JavaScript execution needed.
+```html
+<!-- index.html -->
+<head>
+  <link rel="stylesheet" href="styles/styles.css">
+  <script src="scripts/vendor/zQuery.min.js"></script>
+  <script type="module" src="scripts/app.js"></script>
+</head>
+```
+### Additional Stylesheets — `$.style()`
+`$.style()` loads **global** (unscoped) stylesheet files programmatically — useful for **dynamic theme switching**, **loading additional CSS files at runtime**, **conditional styles**, or any case where a static `<link>` tag isn't flexible enough. Paths resolve **relative to the calling file**, just like component paths.
+```js
+// Load a stylesheet file dynamically
+$.style('themes/dark.css');
+// Multiple files
+$.style(['reset.css', 'theme.css']);
+// Returns a handle to remove later (theme switching)
+const dark = $.style('themes/dark.css');
+// ... later
+dark.remove();  // unloads the stylesheet
+// Override global styles by loading an additional file
+$.style('overrides.css');
+```
+> **`<link rel>` vs `$.style()` vs `styleUrl`:**
+> - Use a **`<link rel="stylesheet">`** in `index.html` for global/app-wide styles — best FOUC prevention.
+> - Use **`$.style()`** to dynamically load additional stylesheet files (themes, overrides, conditional styles).
+> - Use **`styleUrl`** on a component definition for styles scoped to that specific component.
+> - Use component **`styles`** (inline string) for scoped inline CSS within a component definition.
+### Pages Config — Multi-Page Components
+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
+$.component('docs-page', {
+  pages: {
+    dir:     'pages',                  // → scripts/components/docs/pages/
+    param:   'section',                // reads :section from the route
+    default: 'getting-started',        // fallback when param absent
+    items: [
+      'getting-started',               // label auto-derived: 'Getting Started'
+      'project-structure',             // label auto-derived: 'Project Structure'
+      { id: 'http', label: 'HTTP Client' },
+      { id: 'utils', label: 'Utilities' },
+    ],
+  },
+  styleUrl: 'docs.css',               // → scripts/components/docs/docs.css
+  render() {
+    return `
+      <nav>
+        ${this.pages.map(p => `
+          <a class="${this.activePage === p.id ? 'active' : ''}"
+             z-link="/docs/${p.id}">${p.label}</a>
+        `).join('')}
+      </nav>
+      <main>${this.templates[this.activePage] || ''}</main>
+    `;
+  }
+});
+```
+The `param` property tells the component **which route parameter to read**. It must match a `:param` segment in your router config. Use `fallback` so one route handles both the bare path and the parameterized path:
+```js
+// routes.js
+$.router({
+  routes: [
+    { path: '/docs/:section', component: 'docs-page', fallback: '/docs' },
+  ]
+});
+// /docs           → activePage = default ('getting-started')
+// /docs/router    → activePage = 'router'
+```
+| Property | Type | Description |
+| --- | --- | --- |
+| `dir` | `string` | Directory path containing the page HTML files (resolved via `base`) |
+| `param` | `string` | Route param name — must match a `:param` segment in your route |
+| `default` | `string` | Page id shown when the route param is absent |
+| `ext` | `string` | File extension (default `'.html'`) |
+| `items` | `Array` | Page ids (strings) and/or `{id, label}` objects |
+> **How it works:** Under the hood, `pages` auto-generates a `templateUrl` object map (`{ id: 'dir/id.html' }`) and normalizes the items into a `{id, label}` array. String ids auto-derive labels by converting kebab-case to Title Case (e.g. `'getting-started'` → `'Getting Started'`). The component then exposes `this.pages`, `this.activePage`, and `this.templates` inside `render()`.
+---
+## Router
+Client-side SPA router supporting both history mode and hash mode, with route params, query strings, navigation guards, and lazy loading.
+### Setup
+```js
+const router = $.router({
+  el: '#app',                         // outlet element
+  mode: 'history',                    // 'history' (default) or 'hash'
+  base: '/my-app',                    // base path for sub-directory deployments
+  routes: [
+    { path: '/',           component: 'home-page' },
+    { path: '/user/:id',   component: 'user-page' },
+    { path: '/settings',   component: 'settings-page' },
+  ],
+  fallback: 'not-found'              // 404 component
+});
+```
+### Route Definitions
+```js
+{
+  path: '/user/:id',       // :param for dynamic segments
+  component: 'user-page',  // registered component name (string)
+  load: () => import('./pages/user.js'),  // lazy load module before mount
+}
+```
+- **`path`** — URL pattern. Use `:param` for named params, `*` for wildcard.
+- **`component`** — registered component name (string) or a render function `(route) => htmlString`.
+- **`load`** — optional async function for lazy loading (called before component mount).
+- **`fallback`** — an additional path that also matches this route. When matched via fallback, missing params are `undefined`. Useful for pages-config components: `{ path: '/docs/:section', fallback: '/docs' }`.
+### Navigation
+```js
+router.navigate('/user/42');            // push + resolve
+router.replace('/login');               // replace current history entry
+router.back();                          // history.back()
+router.forward();                       // history.forward()
+router.go(-2);                          // history.go(n)
+```
+### Navigation Links (HTML)
+```html
+<!-- z-link attribute for SPA navigation (no page reload) -->
+<a z-link="/">Home</a>
+<a z-link="/user/42">Profile</a>
+```
+### Route Params & Query
+Inside a routed component, params and query are available as props:
+```js
+$.component('user-page', {
+  render() {
+    const userId = this.props.$params.id;
+    const tab = this.props.$query.tab || 'overview';
+    return `<h1>User ${userId}</h1><p>Tab: ${tab}</p>`;
+  }
+});
+```
+### Navigation Guards
+```js
+// Before guard — return false to cancel, string to redirect
+router.beforeEach((to, from) => {
+  if (to.path === '/admin' && !isLoggedIn()) {
+    return '/login';  // redirect
+  }
+});
+// After guard — analytics, etc.
+router.afterEach((to, from) => {
+  trackPageView(to.path);
+});
+```
+### Route Change Listener
+```js
+const unsub = router.onChange((to, from) => {
+  console.log(`Navigated: ${from?.path} → ${to.path}`);
+});
+// unsub() to stop listening
+```
+### Current Route
+```js
+router.current   // { route, params, query, path }
+router.path       // current path string
+router.query      // current query as object
+```
+### Dynamic Routes
+```js
+router.add({ path: '/new-page', component: 'new-page' });
+router.remove('/old-page');
+```
+### Sub-Path Deployment & `<base href>`
+When deploying under a sub-directory (e.g. `https://example.com/my-app/`), the router **auto-detects** `<base href>` — no extra code needed.
+**Option 1 — HTML `<base href>` tag (recommended):**
+Add a `<base href>` tag to your `index.html`:
+```html
+<head>
+  <base href="/my-app/">
+  <!-- ... -->
+</head>
+```
+The router reads this automatically. No changes to `app.js` required — just call `$.router()` as usual:
+```js
+$.router({ el: '#app', routes, fallback: 'not-found' });
+```
+**Option 2 — Explicit `base` option:**
+```js
+$.router({ el: '#app', base: '/my-app', routes: [...] });
+```
+> **Tip:** Using `<base href>` is preferred because it also controls how the browser resolves relative URLs for scripts, stylesheets, images, and fetch requests — keeping all path configuration in one place. The router checks `config.base` → `window.__ZQ_BASE` → `<base href>` tag, in that order.
+For history mode, configure your server to rewrite all non-file requests to `index.html`. Example `.htaccess`:
+```
+RewriteEngine On
+RewriteBase /my-app/
+RewriteCond %{REQUEST_FILENAME} -f
+RewriteRule ^ - [L]
+RewriteRule ^ index.html [L]
+```
+---
+## Store
+Lightweight global state management with reactive proxies, named actions, computed getters, middleware, and subscriptions.
+### Setup
+```js
+const store = $.store({
+  state: {
+    count: 0,
+    user: null,
+    todos: [],
+  },
+  actions: {
+    increment(state)       { state.count++; },
+    setUser(state, user)   { state.user = user; },
+    addTodo(state, text)   {
+      const raw = state.todos.__raw || state.todos;
+      state.todos = [...raw, { id: Date.now(), text, done: false }];
+    },
+  },
+  getters: {
+    doubleCount: (state) => state.count * 2,
+    doneCount:   (state) => state.todos.filter(t => t.done).length,
+  },
+  debug: true,  // logs actions to console
+});
+```
+### Dispatching Actions
+```js
+store.dispatch('increment');
+store.dispatch('setUser', { name: 'Tony', role: 'admin' });
+store.dispatch('addTodo', 'Write documentation');
+```
+### Reading State
+```js
+store.state.count          // reactive — triggers subscribers on change
+store.getters.doubleCount  // computed from state
+store.snapshot()           // deep-cloned plain object
+```
+### Subscriptions
+```js
+// Subscribe to a specific key
+const unsub = store.subscribe('count', (newVal, oldVal, key) => {
+  console.log(`count changed: ${oldVal} → ${newVal}`);
+});
+// Wildcard — subscribe to all changes
+store.subscribe((key, newVal, oldVal) => {
+  console.log(`${key} changed`);
+});
+unsub(); // unsubscribe
+```
+### Using Store in Components
+```js
+$.component('my-widget', {
+  mounted() {
+    // Re-render when store key changes
+    this._unsub = store.subscribe('count', () => {
+      this._scheduleUpdate();
+    });
+  },
+  destroyed() {
+    this._unsub?.();
+  },
+  render() {
+    return `<p>Count: ${store.state.count}</p>`;
+  }
+});
+```
+### Middleware
+```js
+store.use((actionName, args, state) => {
+  console.log(`[middleware] ${actionName}`, args);
+  // return false to block the action
+});
+```
+### Named Stores
+```js
+const userStore = $.store('users', { state: { list: [] }, actions: { ... } });
+const appStore  = $.store('app',   { state: { theme: 'dark' }, actions: { ... } });
+// Retrieve later
+$.getStore('users');
+$.getStore('app');
+```
+### State Management
+```js
+store.replaceState({ count: 0, user: null, todos: [] });
+store.reset({ count: 0, user: null, todos: [] });  // also clears history
+store.history;  // array of { action, args, timestamp }
+```
+---
+## HTTP Client
+A lightweight fetch wrapper providing auto-JSON serialization, interceptors, timeout/abort support, and a clean chainable API.
+### Basic Requests
+```js
+// GET with query params
+const res = await $.get('/api/users', { page: 1, limit: 10 });
+console.log(res.data);  // parsed JSON
+// POST with JSON body
+const created = await $.post('/api/users', { name: 'Tony', email: 'tony@example.com' });
+// PUT, PATCH, DELETE
+await $.put('/api/users/1', { name: 'Updated' });
+await $.patch('/api/users/1', { email: 'new@example.com' });
+await $.delete('/api/users/1');
+```
+### Configuration
+```js
+$.http.configure({
+  baseURL: 'https://api.example.com',
+  headers: { Authorization: 'Bearer token123' },
+  timeout: 15000,  // ms (default: 30000)
+});
+```
+### Interceptors
+```js
+// Request interceptor
+$.http.onRequest((fetchOpts, url) => {
+  fetchOpts.headers['X-Request-ID'] = $.uuid();
+  // return false to block | return { url, options } to modify
+});
+// Response interceptor
+$.http.onResponse((result) => {
+  if (result.status === 401) {
+    window.location.href = '/login';
+  }
+});
+```
+### Abort / Cancel
+```js
+const controller = $.http.createAbort();
+$.get('/api/slow', null, { signal: controller.signal })
+  .catch(err => console.log('Aborted:', err.message));
+// Cancel after 2 seconds
+setTimeout(() => controller.abort(), 2000);
+```
+### Response Object
+Every request resolves with:
+```js
+{
+  ok: true,              // response.ok
+  status: 200,           // HTTP status code
+  statusText: 'OK',
+  headers: { ... },      // parsed headers object
+  data: { ... },         // auto-parsed body (JSON, text, or blob)
+  response: Response,    // raw fetch Response object
+}
+```
+### FormData Upload
+```js
+const formData = new FormData();
+formData.append('file', fileInput.files[0]);
+await $.post('/api/upload', formData);
+// Content-Type header is automatically removed so the browser sets multipart boundary
+```
+### Raw Fetch
+```js
+const raw = await $.http.raw('/api/stream', { method: 'GET' });
+const reader = raw.body.getReader();
+```
+---
+## Reactive Primitives
+### Deep Reactive Proxy
+```js
+const data = $.reactive({ user: { name: 'Tony' } }, (key, value, old) => {
+  console.log(`${key} changed: ${old} → ${value}`);
+});
+data.user.name = 'Updated';  // triggers callback
+data.__isReactive;            // true
+data.__raw;                   // original plain object
+```
+### Signals
+Lightweight reactive primitives inspired by Solid/Preact signals:
+```js
+const count = $.signal(0);
+// Auto-tracking effect
+$.effect(() => {
+  console.log('Count is:', count.value);  // runs immediately, re-runs on change
+});
+count.value = 5;  // triggers the effect
+// Computed signal (derived)
+const doubled = $.computed(() => count.value * 2);
+console.log(doubled.value);  // 10
+// Manual subscription
+const unsub = count.subscribe(() => console.log('changed'));
+// Peek without tracking
+count.peek();  // returns value without subscribing
+```
+---
+## Utilities
+All utilities are available on the `$` namespace.
+### Function Utilities
+```js
+// Debounce — delays until ms of inactivity
+const search = $.debounce((query) => fetchResults(query), 300);
+search('hello');
+search.cancel();  // cancel pending call
+// Throttle — max once per ms
+const scroll = $.throttle(() => updatePosition(), 100);
+// Pipe — left-to-right function composition
+const transform = $.pipe(trim, lowercase, capitalize);
+transform('  HELLO  ');  // 'Hello'
+// Once — only runs the first time
+const init = $.once(() => { /* heavy setup */ });
+// Sleep — async delay
+await $.sleep(1000);
+```
+### String Utilities
+```js
+$.escapeHtml('<script>alert("xss")</script>');
+// &lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;
+// Template tag with auto-escaping
+const safe = $.html`<div>${userInput}</div>`;
+// Mark trusted HTML (skips escaping)
+const raw = $.trust('<strong>Bold</strong>');
+const output = $.html`<div>${raw}</div>`;  // <div><strong>Bold</strong></div>
+$.uuid();                    // 'a1b2c3d4-...'
+$.camelCase('my-component'); // 'myComponent'
+$.kebabCase('myComponent');  // 'my-component'
+```
+### Object Utilities
+```js
+const clone = $.deepClone({ nested: { value: 1 } });
+const merged = $.deepMerge({}, defaults, userConfig);
+$.isEqual({ a: 1 }, { a: 1 });  // true
+```
+### URL Utilities
+```js
+$.param({ page: 1, sort: 'name' });  // 'page=1&sort=name'
+$.parseQuery('page=1&sort=name');     // { page: '1', sort: 'name' }
+```
+### Storage Wrappers
+```js
+// localStorage with auto JSON serialization
+$.storage.set('user', { name: 'Tony', prefs: { theme: 'dark' } });
+$.storage.get('user');           // { name: 'Tony', prefs: { theme: 'dark' } }
+$.storage.get('missing', []);    // [] (fallback)
+$.storage.remove('user');
+$.storage.clear();
+// sessionStorage (same API)
+$.session.set('token', 'abc123');
+$.session.get('token');
+```
+### Event Bus
+Global pub/sub for cross-component communication without direct coupling:
+```js
+// Subscribe
+const unsub = $.bus.on('user:login', (user) => {
+  console.log('Logged in:', user.name);
+});
+// Emit
+$.bus.emit('user:login', { name: 'Tony' });
+// One-time listener
+$.bus.once('app:ready', () => { /* runs once */ });
+// Unsubscribe
+unsub();
+$.bus.off('user:login', handler);
+$.bus.clear();  // remove all listeners
+```
+---
+## DOM Ready
+```js
+// Shorthand (pass function to $)
+$(() => {
+  console.log('DOM ready');
+});
+// Explicit
+$.ready(() => {
+  console.log('DOM ready');
+});
+```
+---
+## No-Conflict Mode
+```js
+const mq = $.noConflict();  // removes $ from window, returns the library
+mq('.card').addClass('active');
+```
+---
+## Building from Source
+```bash
+# One-time build
+node build.js
+# → dist/zQuery.js  (development)
+# → dist/zQuery.min.js  (production)
+# Watch mode (rebuilds on file changes)
+node build.js --watch
+```
+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.
+---
+## Running the Starter App
+```bash
+# From the project root
+node build.js                                    # build the bundle
+cp dist/zQuery.min.js examples/starter-app/scripts/vendor/  # copy to app
+# Start the dev server (uses zero-http)
+npm run serve
+# → http://localhost:3000
+# Or use any static server
+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.
+### 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
+npm run serve
+# Custom port
+node examples/starter-app/local-server.js 8080
+# 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.
+### Production Deployment
+For history-mode routing in production, configure your web server to rewrite non-file requests to `index.html`.
+**Apache (.htaccess):**
+```apache
+RewriteEngine On
+RewriteBase /
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule ^ index.html [L]
+```
+**Nginx:**
+```nginx
+location / {
+    try_files $uri $uri/ /index.html;
+}
+```
+**Sub-path deployment** (e.g. hosted at `/my-app/`):
+Set `<base href="/my-app/">` in your HTML `<head>` — the router auto-detects it. Or pass `base` explicitly:
+```js
+$.router({ el: '#app', base: '/my-app', routes });
+```
+```apache
+# Apache — adjust RewriteBase
+RewriteBase /my-app/
+```
+```nginx
+# Nginx — adjust location block
+location /my-app/ {
+    try_files $uri $uri/ /my-app/index.html;
+}
+```
+---
+## Complete API at a Glance
+| Namespace | Methods |
+| --- | --- |
+| `$()` | Single-element selector → `Element \| null` |
+| `$.all()` | Collection selector → `ZQueryCollection` |
+| `$.id` `$.class` `$.classes` `$.tag` `$.children` | Quick DOM refs |
+| `$.create` | Element factory |
+| `$.ready` `$.on` | DOM ready, global delegation |
+| `$.fn` | Collection prototype (extend it) |
+| `$.component` `$.mount` `$.mountAll` `$.getInstance` `$.destroy` `$.components` | Component system |
+| `$.style` | Dynamically load additional global (unscoped) stylesheet file(s) — paths resolve relative to the calling file |
+| `$.router` `$.getRouter` | SPA router |
+| `$.store` `$.getStore` | State management |
+| `$.http` `$.get` `$.post` `$.put` `$.patch` `$.delete` | HTTP client |
+| `$.reactive` `$.signal` `$.computed` `$.effect` | Reactive primitives |
+| `$.debounce` `$.throttle` `$.pipe` `$.once` `$.sleep` | Function utils |
+| `$.escapeHtml` `$.html` `$.trust` `$.uuid` `$.camelCase` `$.kebabCase` | String utils |
+| `$.deepClone` `$.deepMerge` `$.isEqual` | Object utils |
+| `$.param` `$.parseQuery` | URL utils |
+| `$.storage` `$.session` | Storage wrappers |
+| `$.bus` | Event bus |
+| `$.version` | Library version |
+| `$.noConflict` | Release `$` global |
+For full method signatures and options, see [API.md](API.md).
+---
+## License
+MIT — [Anthony Wiedman / Molex](https://github.com/tonywied17)