zero-query 0.9.9 → 1.0.0

package/src/reactive.js

@@ -1,5 +1,5 @@
 /**
- * zQuery Reactive — Proxy-based deep reactivity system
+ * zQuery Reactive - Proxy-based deep reactivity system
  * 
  * Creates observable objects that trigger callbacks on mutation.
  * Used internally by components and store for auto-updates.
@@ -67,7 +67,7 @@ export function reactive(target, onChange, _path = '') {
 
 
 // ---------------------------------------------------------------------------
-// Signal — lightweight reactive primitive (inspired by Solid/Preact signals)
+// Signal - lightweight reactive primitive (inspired by Solid/Preact signals)
 // ---------------------------------------------------------------------------
 export class Signal {
   constructor(value) {
@@ -96,7 +96,11 @@ export class Signal {
   peek() { return this._value; }
 
   _notify() {
-    // Snapshot subscribers before iterating — a subscriber might modify
+    if (Signal._batching) {
+      Signal._batchQueue.add(this);
+      return;
+    }
+    // Snapshot subscribers before iterating - a subscriber might modify
     // the set (e.g., an effect re-running, adding itself back)
     const subs = [...this._subscribers];
     for (let i = 0; i < subs.length; i++) {
@@ -117,10 +121,13 @@ export class Signal {
 
 // Active effect tracking
 Signal._activeEffect = null;
+// Batch state
+Signal._batching = false;
+Signal._batchQueue = new Set();
 
 /**
  * Create a signal
- * @param {*} initial — initial value
+ * @param {*} initial - initial value
  * @returns {Signal}
  */
 export function signal(initial) {
@@ -129,7 +136,7 @@ export function signal(initial) {
 
 /**
  * Create a computed signal (derived from other signals)
- * @param {Function} fn — computation function
+ * @param {Function} fn - computation function
  * @returns {Signal}
  */
 export function computed(fn) {
@@ -147,10 +154,10 @@ export function computed(fn) {
 /**
  * Create a side-effect that auto-tracks signal dependencies.
  * Returns a dispose function that removes the effect from all
- * signals it subscribed to — prevents memory leaks.
+ * signals it subscribed to - prevents memory leaks.
  *
- * @param {Function} fn — effect function
- * @returns {Function} — dispose function
+ * @param {Function} fn - effect function
+ * @returns {Function} - dispose function
  */
 export function effect(fn) {
   const execute = () => {
@@ -183,6 +190,65 @@ export function effect(fn) {
       }
       execute._deps.clear();
     }
-    // Don't clobber _activeEffect — another effect may be running
+    // Don't clobber _activeEffect - another effect may be running
   };
 }
+
+
+// ---------------------------------------------------------------------------
+// batch() - defer signal notifications until the batch completes
+// ---------------------------------------------------------------------------
+
+/**
+ * Batch multiple signal writes - subscribers and effects fire once at the end.
+ * @param {Function} fn - function that performs signal writes
+ */
+export function batch(fn) {
+  if (Signal._batching) {
+    // Already inside a batch, just run
+    fn();
+    return;
+  }
+  Signal._batching = true;
+  Signal._batchQueue.clear();
+  try {
+    fn();
+  } finally {
+    Signal._batching = false;
+    // Collect all unique subscribers across all queued signals
+    // so each subscriber/effect runs exactly once
+    const subs = new Set();
+    for (const sig of Signal._batchQueue) {
+      for (const sub of sig._subscribers) {
+        subs.add(sub);
+      }
+    }
+    Signal._batchQueue.clear();
+    for (const sub of subs) {
+      try { sub(); }
+      catch (err) {
+        reportError(ErrorCode.SIGNAL_CALLBACK, 'Signal subscriber threw', {}, err);
+      }
+    }
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// untracked() - read signals without creating dependencies
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a function without tracking signal reads as dependencies.
+ * @param {Function} fn - function to run
+ * @returns {*} the return value of fn
+ */
+export function untracked(fn) {
+  const prev = Signal._activeEffect;
+  Signal._activeEffect = null;
+  try {
+    return fn();
+  } finally {
+    Signal._activeEffect = prev;
+  }
+}

package/src/router.js

@@ -1,14 +1,13 @@
 /**
- * zQuery Router — Client-side SPA router
+ * zQuery Router - Client-side SPA router
  * 
  * Supports hash mode (#/path) and history mode (/path).
  * Route params, query strings, navigation guards, and lazy loading.
  * Sub-route history substates for in-page UI changes (modals, tabs, etc.).
  * 
  * Usage:
+ *   // HTML: <z-outlet></z-outlet>
  *   $.router({
- *     el: '#app',
- *     mode: 'hash',
  *     routes: [
  *       { path: '/', component: 'home-page' },
  *       { path: '/user/:id', component: 'user-profile' },
@@ -44,7 +43,7 @@ function _shallowEqual(a, b) {
 class Router {
   constructor(config = {}) {
     this._el = null;
-    // file:// protocol can't use pushState — always force hash mode
+    // file:// protocol can't use pushState - always force hash mode
     const isFile = typeof location !== 'undefined' && location.protocol === 'file:';
     this._mode = isFile ? 'hash' : (config.mode || 'history');
 
@@ -79,8 +78,30 @@ class Router {
     this._inSubstate = false;                       // true while substate entries are in the history stack
 
     // Set outlet element
+    // Priority: explicit config.el → <z-outlet> tag in the DOM
     if (config.el) {
       this._el = typeof config.el === 'string' ? document.querySelector(config.el) : config.el;
+    } else if (typeof document !== 'undefined') {
+      const outlet = document.querySelector('z-outlet');
+      if (outlet) {
+        this._el = outlet;
+        // Read inline attribute overrides from <z-outlet> (config takes priority)
+        if (!config.fallback && outlet.getAttribute('fallback')) {
+          this._fallback = outlet.getAttribute('fallback');
+        }
+        if (!config.mode && outlet.getAttribute('mode')) {
+          const attrMode = outlet.getAttribute('mode');
+          if (attrMode === 'hash' || attrMode === 'history') {
+            this._mode = isFile ? 'hash' : attrMode;
+          }
+        }
+        if (config.base == null && outlet.getAttribute('base')) {
+          let ob = outlet.getAttribute('base');
+          ob = String(ob).replace(/\/+$/, '');
+          if (ob && !ob.startsWith('/')) ob = '/' + ob;
+          this._base = ob;
+        }
+      }
     }
 
     // Register routes
@@ -88,21 +109,43 @@ class Router {
       config.routes.forEach(r => this.add(r));
     }
 
-    // Listen for navigation — store handler references for cleanup in destroy()
+    // Listen for navigation - store handler references for cleanup in destroy()
     if (this._mode === 'hash') {
       this._onNavEvent = () => this._resolve();
       window.addEventListener('hashchange', this._onNavEvent);
+      // Hash mode also needs popstate for substates (pushSubstate uses pushState)
+      this._onPopState = (e) => {
+        const st = e.state;
+        if (st && st[_ZQ_STATE_KEY] === 'substate') {
+          const handled = this._fireSubstate(st.key, st.data, 'pop');
+          if (handled) return;
+          this._resolve().then(() => {
+            this._fireSubstate(st.key, st.data, 'pop');
+          });
+          return;
+        } else if (this._inSubstate) {
+          this._inSubstate = false;
+          this._fireSubstate(null, null, 'reset');
+        }
+      };
+      window.addEventListener('popstate', this._onPopState);
     } else {
       this._onNavEvent = (e) => {
-        // Check for substate pop first — if a listener handles it, don't route
+        // Check for substate pop first - if a listener handles it, don't route
         const st = e.state;
         if (st && st[_ZQ_STATE_KEY] === 'substate') {
           const handled = this._fireSubstate(st.key, st.data, 'pop');
           if (handled) return;
-          // Unhandled substate — fall through to route resolve
-          // _inSubstate stays true so the next non-substate pop triggers reset
+          // Unhandled substate — the owning component was likely destroyed
+          // (e.g. user navigated away then pressed back).  Resolve the route
+          // first (which may mount a fresh component that registers a listener),
+          // then retry the substate so the new listener can restore the UI.
+          this._resolve().then(() => {
+            this._fireSubstate(st.key, st.data, 'pop');
+          });
+          return;
         } else if (this._inSubstate) {
-          // Popped past all substates — notify listeners to reset to defaults
+          // Popped past all substates - notify listeners to reset to defaults
           this._inSubstate = false;
           this._fireSubstate(null, null, 'reset');
         }
@@ -120,13 +163,17 @@ class Router {
       if (link.getAttribute('target') === '_blank') return;
       e.preventDefault();
       let href = link.getAttribute('z-link');
+      // Reject absolute URLs and dangerous protocols — z-link is for internal routes only
+      if (href && /^[a-z][a-z0-9+.-]*:/i.test(href)) return;
       // Support z-link-params for dynamic :param interpolation
       const paramsAttr = link.getAttribute('z-link-params');
       if (paramsAttr) {
         try {
           const params = JSON.parse(paramsAttr);
           href = this._interpolateParams(href, params);
-        } catch { /* ignore malformed JSON */ }
+        } catch (err) {
+          reportError(ErrorCode.ROUTER_RESOLVE, 'Malformed JSON in z-link-params', { href, paramsAttr }, err);
+        }
       }
       this.navigate(href);
       // z-to-top modifier: scroll to top after navigation
@@ -180,8 +227,8 @@ class Router {
 
   /**
    * Interpolate :param placeholders in a path with the given values.
-   * @param {string} path — e.g. '/user/:id/posts/:pid'
-   * @param {Object} params — e.g. { id: 42, pid: 7 }
+   * @param {string} path - e.g. '/user/:id/posts/:pid'
+   * @param {Object} params - e.g. { id: 42, pid: 7 }
    * @returns {string}
    */
   _interpolateParams(path, params) {
@@ -225,7 +272,7 @@ class Router {
       const currentURL = (window.location.pathname || '/') + (window.location.hash || '');
 
       if (targetURL === currentURL && !options.force) {
-        // Same full URL (path + hash) — don't push duplicate entry.
+        // Same full URL (path + hash) - don't push duplicate entry.
         // If only the hash changed to a fragment target, scroll to it.
         if (fragment) {
           const el = document.getElementById(fragment);
@@ -234,7 +281,7 @@ class Router {
         return this;
       }
 
-      // Same route path but different hash fragment — use replaceState
+      // Same route path but different hash fragment - use replaceState
       // so back goes to the previous *route*, not the previous scroll position.
       const targetPathOnly = this._base + normalized;
       const currentPathOnly = window.location.pathname || '/';
@@ -249,7 +296,7 @@ class Router {
           const el = document.getElementById(fragment);
           if (el) el.scrollIntoView({ behavior: 'smooth', block: 'start' });
         }
-        // Don't re-resolve — same route, just a hash change
+        // Don't re-resolve - same route, just a hash change
         return this;
       }
 
@@ -285,8 +332,8 @@ class Router {
 
   /**
    * Normalize an app-relative path and guard against double base-prefixing.
-   * @param {string} path — e.g. '/docs', 'docs', or '/app/docs' when base is '/app'
-   * @returns {string} — always starts with '/'
+   * @param {string} path - e.g. '/docs', 'docs', or '/app/docs' when base is '/app'
+   * @returns {string} - always starts with '/'
    */
   _normalizePath(path) {
     let p = path && path.startsWith('/') ? path : (path ? `/${path}` : '/');
@@ -336,12 +383,12 @@ class Router {
 
   /**
    * Push a lightweight history entry for in-component UI state.
-   * The URL path does NOT change — only a history entry is added so the
+   * The URL path does NOT change - only a history entry is added so the
    * back button can undo the UI change (close modal, revert tab, etc.)
    * before navigating away.
    *
-   * @param {string} key   — identifier (e.g. 'modal', 'tab', 'panel')
-   * @param {*}      data  — arbitrary state (serializable)
+   * @param {string} key   - identifier (e.g. 'modal', 'tab', 'panel')
+   * @param {*}      data  - arbitrary state (serializable)
    * @returns {Router}
    *
    * @example
@@ -352,7 +399,7 @@ class Router {
   pushSubstate(key, data) {
     this._inSubstate = true;
     if (this._mode === 'hash') {
-      // Hash mode: stash the substate in a global — hashchange will check.
+      // Hash mode: stash the substate in a global - hashchange will check.
       // We still push a history entry via a sentinel hash suffix.
       const current = window.location.hash || '#/';
       window.history.pushState(
@@ -468,12 +515,12 @@ class Router {
   async __resolve() {
     // Check if we're landing on a substate entry (e.g. page refresh on a
     // substate bookmark, or hash-mode popstate). Fire listeners and bail
-    // if handled — the URL hasn't changed so there's no route to resolve.
+    // if handled - the URL hasn't changed so there's no route to resolve.
     const histState = window.history.state;
     if (histState && histState[_ZQ_STATE_KEY] === 'substate') {
       const handled = this._fireSubstate(histState.key, histState.data, 'resolve');
       if (handled) return;
-      // No listener handled it — fall through to normal routing
+      // No listener handled it - fall through to normal routing
     }
 
     const fullPath = this.path;
@@ -510,7 +557,7 @@ class Router {
       const sameParams = _shallowEqual(params, from.params);
       const sameQuery = _shallowEqual(query, from.query);
       if (sameParams && sameQuery) {
-        // Identical navigation — nothing to do
+        // Identical navigation - nothing to do
         return;
       }
     }
@@ -598,6 +645,9 @@ class Router {
       }
     }
 
+    // Update z-active-route elements
+    this._updateActiveRoutes(path);
+
     // Run after guards
     for (const guard of this._guards.after) {
       await guard(to, from);
@@ -607,6 +657,32 @@ class Router {
     this._listeners.forEach(fn => fn(to, from));
   }
 
+  // --- Active route class management ----------------------------------------
+
+  /**
+   * Update all elements with z-active-route to toggle their active class
+   * based on the current path.
+   *
+   * Usage:
+   *   <a z-link="/docs" z-active-route="/docs">Docs</a>
+   *   <a z-link="/about" z-active-route="/about" z-active-class="selected">About</a>
+   *   <a z-link="/" z-active-route="/" z-active-exact>Home</a>
+   */
+  _updateActiveRoutes(currentPath) {
+    if (typeof document === 'undefined') return;
+    const els = document.querySelectorAll('[z-active-route]');
+    for (let i = 0; i < els.length; i++) {
+      const el = els[i];
+      const route = el.getAttribute('z-active-route');
+      const cls = el.getAttribute('z-active-class') || 'active';
+      const exact = el.hasAttribute('z-active-exact');
+      const isActive = exact
+        ? currentPath === route
+        : (route === '/' ? currentPath === '/' : currentPath.startsWith(route));
+      el.classList.toggle(cls, isActive);
+    }
+  }
+
   // --- Destroy -------------------------------------------------------------
 
   destroy() {
@@ -615,6 +691,10 @@ class Router {
       window.removeEventListener(this._mode === 'hash' ? 'hashchange' : 'popstate', this._onNavEvent);
       this._onNavEvent = null;
     }
+    if (this._onPopState) {
+      window.removeEventListener('popstate', this._onPopState);
+      this._onPopState = null;
+    }
     if (this._onLinkClick) {
       document.removeEventListener('click', this._onLinkClick);
       this._onLinkClick = null;

package/src/ssr.js

@@ -1,10 +1,10 @@
 /**
- * zQuery SSR — Server-side rendering to HTML string
+ * zQuery SSR - Server-side rendering to HTML string
  *
  * Renders registered components to static HTML strings for SEO,
  * initial page load performance, and static site generation.
  *
- * Works in Node.js — no DOM required for basic rendering.
+ * Works in Node.js - no DOM required for basic rendering.
  * Supports hydration markers for client-side takeover.
  *
  * Usage (Node.js):
@@ -67,7 +67,7 @@ class SSRComponent {
       }
     }
 
-    // Init lifecycle — guarded so a broken init doesn't crash the whole render
+    // Init lifecycle - guarded so a broken init doesn't crash the whole render
     if (definition.init) {
       try {
         definition.init.call(this);
@@ -85,7 +85,7 @@ class SSRComponent {
         return html;
       } catch (err) {
         reportError(ErrorCode.SSR_RENDER, 'Component render() threw during SSR', {}, err);
-        return `<!-- SSR render error: ${_escapeHtml(err.message)} -->`;
+        return `<!-- SSR render error -->`;
       }
     }
     return '';
@@ -123,7 +123,7 @@ function _escapeHtml(str) {
 }
 
 // ---------------------------------------------------------------------------
-// SSR App — component registry + renderer
+// SSR App - component registry + renderer
 // ---------------------------------------------------------------------------
 class SSRApp {
   constructor() {
@@ -158,12 +158,12 @@ class SSRApp {
   /**
    * Render a component to an HTML string.
    *
-   * @param {string} componentName — registered component name
-   * @param {object} [props] — props to pass
-   * @param {object} [options] — rendering options
-   * @param {boolean} [options.hydrate=true] — add hydration marker
-   * @param {string} [options.mode='html'] — 'html' (default) or 'fragment' (no wrapper tag)
-   * @returns {Promise<string>} — rendered HTML
+   * @param {string} componentName - registered component name
+   * @param {object} [props] - props to pass
+   * @param {object} [options] - rendering options
+   * @param {boolean} [options.hydrate=true] - add hydration marker
+   * @param {string} [options.mode='html'] - 'html' (default) or 'fragment' (no wrapper tag)
+   * @returns {Promise<string>} - rendered HTML
    */
   async renderToString(componentName, props = {}, options = {}) {
     const def = this._registry.get(componentName);
@@ -185,7 +185,7 @@ class SSRApp {
     html = html.replace(/\s*@[\w.]+="[^"]*"/g, ''); // Remove event bindings
     html = html.replace(/\s*z-on:[\w.]+="[^"]*"/g, '');
 
-    // Fragment mode — return inner HTML without wrapper tag
+    // Fragment mode - return inner HTML without wrapper tag
     if (options.mode === 'fragment') return html;
 
     const hydrate = options.hydrate !== false;
@@ -198,7 +198,7 @@ class SSRApp {
    * Render multiple components as a batch.
    *
    * @param {Array<{ name: string, props?: object, options?: object }>} entries
-   * @returns {Promise<string[]>} — array of rendered HTML strings
+   * @returns {Promise<string[]>} - array of rendered HTML strings
    */
   async renderBatch(entries) {
     return Promise.all(
@@ -210,18 +210,18 @@ class SSRApp {
    * Render a full HTML page with a component mounted in a shell.
    *
    * @param {object} options
-   * @param {string} options.component — component name to render
-   * @param {object} [options.props] — props
-   * @param {string} [options.title] — page title
-   * @param {string} [options.description] — meta description for SEO
-   * @param {string[]} [options.styles] — CSS file paths
-   * @param {string[]} [options.scripts] — JS file paths
-   * @param {string} [options.lang] — html lang attribute
-   * @param {string} [options.meta] — additional head content
-   * @param {string} [options.bodyAttrs] — extra body attributes
-   * @param {object} [options.head] — structured head options
-   * @param {string} [options.head.canonical] — canonical URL
-   * @param {object} [options.head.og] — Open Graph tags
+   * @param {string} options.component - component name to render
+   * @param {object} [options.props] - props
+   * @param {string} [options.title] - page title
+   * @param {string} [options.description] - meta description for SEO
+   * @param {string[]} [options.styles] - CSS file paths
+   * @param {string[]} [options.scripts] - JS file paths
+   * @param {string} [options.lang] - html lang attribute
+   * @param {string} [options.meta] - additional head content
+   * @param {string} [options.bodyAttrs] - extra body attributes
+   * @param {object} [options.head] - structured head options
+   * @param {string} [options.head.canonical] - canonical URL
+   * @param {object} [options.head.og] - Open Graph tags
    * @returns {Promise<string>}
    */
   async renderPage(options = {}) {
@@ -296,8 +296,8 @@ export function createSSRApp() {
 
 /**
  * Quick one-shot render of a component definition to string.
- * @param {object} definition — component definition
- * @param {object} [props] — props
+ * @param {object} definition - component definition
+ * @param {object} [props] - props
  * @returns {string}
  */
 export function renderToString(definition, props = {}) {
@@ -309,7 +309,7 @@ export function renderToString(definition, props = {}) {
 }
 
 /**
- * Escape HTML entities — exposed for use in SSR templates.
+ * Escape HTML entities - exposed for use in SSR templates.
  * @param {string} str
  * @returns {string}
  */