zero-query 0.6.3 → 0.8.6

package/index.js

@@ -11,11 +11,11 @@
 
 import { query, queryAll, ZQueryCollection } from './src/core.js';
 import { reactive, Signal, signal, computed, effect } from './src/reactive.js';
-import { component, mount, mountAll, getInstance, destroy, getRegistry, style } from './src/component.js';
+import { component, mount, mountAll, getInstance, destroy, getRegistry, prefetch, style } from './src/component.js';
 import { createRouter, getRouter } from './src/router.js';
 import { createStore, getStore } from './src/store.js';
 import { http } from './src/http.js';
-import { morph } from './src/diff.js';
+import { morph, morphElement } from './src/diff.js';
 import { safeEval } from './src/expression.js';
 import {
   debounce, throttle, pipe, once, sleep,
@@ -23,7 +23,7 @@ import {
   deepClone, deepMerge, isEqual, param, parseQuery,
   storage, session, bus,
 } from './src/utils.js';
-import { ZQueryError, ErrorCode, onError, reportError } from './src/errors.js';
+import { ZQueryError, ErrorCode, onError, reportError, guardCallback, validate } from './src/errors.js';
 
 
 // ---------------------------------------------------------------------------
@@ -100,8 +100,10 @@ $.mountAll    = mountAll;
 $.getInstance = getInstance;
 $.destroy     = destroy;
 $.components  = getRegistry;
+$.prefetch    = prefetch;
 $.style       = style;
-$.morph       = morph;
+$.morph        = morph;
+$.morphElement = morphElement;
 $.safeEval    = safeEval;
 
 // --- Router ----------------------------------------------------------------
@@ -142,12 +144,15 @@ $.session    = session;
 $.bus        = bus;
 
 // --- Error handling --------------------------------------------------------
-$.onError     = onError;
-$.ZQueryError = ZQueryError;
-$.ErrorCode   = ErrorCode;
+$.onError        = onError;
+$.ZQueryError    = ZQueryError;
+$.ErrorCode      = ErrorCode;
+$.guardCallback  = guardCallback;
+$.validate       = validate;
 
 // --- Meta ------------------------------------------------------------------
 $.version = '__VERSION__';
+$.libSize = '__LIB_SIZE__';
 $.meta    = {};                // populated at build time by CLI bundler
 
 $.noConflict = () => {
@@ -176,13 +181,13 @@ export {
   ZQueryCollection,
   queryAll,
   reactive, Signal, signal, computed, effect,
-  component, mount, mountAll, getInstance, destroy, getRegistry, style,
-  morph,
+  component, mount, mountAll, getInstance, destroy, getRegistry, prefetch, style,
+  morph, morphElement,
   safeEval,
   createRouter, getRouter,
   createStore, getStore,
   http,
-  ZQueryError, ErrorCode, onError, reportError,
+  ZQueryError, ErrorCode, onError, reportError, guardCallback, validate,
   debounce, throttle, pipe, once, sleep,
   escapeHtml, html, trust, uuid, camelCase, kebabCase,
   deepClone, deepMerge, isEqual, param, parseQuery,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-query",
-  "version": "0.6.3",
+  "version": "0.8.6",
   "description": "Lightweight modern frontend library — jQuery-like selectors, reactive components, SPA router, and state management with zero dependencies.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -9,8 +9,10 @@
   },
   "files": [
     "src",
+    "tests",
     "dist",
     "cli",
+    "types",
     "index.js",
     "index.d.ts",
     "LICENSE",
@@ -19,9 +21,10 @@
   "scripts": {
     "build": "node cli/index.js build",
     "dev": "node cli/index.js dev zquery-website",
+    "dev:bundle": "node cli/index.js dev zquery-website --bundle",
     "dev-lib": "node cli/index.js build --watch",
     "bundle": "node cli/index.js bundle",
-    "bundle:app": "node cli/index.js bundle zquery-website --minimal",
+    "bundle:app": "node cli/index.js bundle zquery-website",
     "test": "vitest run",
     "test:watch": "vitest"
   },
@@ -52,11 +55,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "zero-http": "^0.2.3"
-  },
   "devDependencies": {
     "jsdom": "^28.1.0",
-    "vitest": "^4.0.18"
+    "vitest": "^4.0.18",
+    "zero-http": "^0.2.3"
   }
 }

package/src/component.js

@@ -339,7 +339,7 @@ class Component {
       // Normalize items → [{id, label}, …]
       def._pages = (p.items || []).map(item => {
         if (typeof item === 'string') return { id: item, label: _titleCase(item) };
-        return { id: item.id, label: item.label || _titleCase(item.id) };
+        return { ...item, label: item.label || _titleCase(item.id) };
       });
 
       // Build URL map for lazy per-page loading.
@@ -381,11 +381,14 @@ class Component {
     if (def.styleUrl && !def._styleLoaded) {
       const su = def.styleUrl;
       if (typeof su === 'string') {
-        def._externalStyles = await _fetchResource(_resolveUrl(su, base));
+        const resolved = _resolveUrl(su, base);
+        def._externalStyles = await _fetchResource(resolved);
+        def._resolvedStyleUrls = [resolved];
       } else if (Array.isArray(su)) {
         const urls = su.map(u => _resolveUrl(u, base));
         const results = await Promise.all(urls.map(u => _fetchResource(u)));
         def._externalStyles = results.join('\n');
+        def._resolvedStyleUrls = urls;
       }
       def._styleLoaded = true;
     }
@@ -469,6 +472,11 @@ class Component {
       html = '';
     }
 
+    // Pre-expand z-html and z-text at string level so the morph engine
+    // can diff their content properly (instead of clearing + re-injecting
+    // on every re-render). Same pattern as z-for: parse → evaluate → serialize.
+    html = this._expandContentDirectives(html);
+
     // -- Slot distribution ----------------------------------------
     // Replace <slot> elements with captured slot content from parent.
     // <slot> → default slot content
@@ -512,6 +520,13 @@ class Component {
       const styleEl = document.createElement('style');
       styleEl.textContent = scoped;
       styleEl.setAttribute('data-zq-component', this._def._name || '');
+      styleEl.setAttribute('data-zq-scope', scopeAttr);
+      if (this._def._resolvedStyleUrls) {
+        styleEl.setAttribute('data-zq-style-urls', this._def._resolvedStyleUrls.join(' '));
+        if (this._def.styles) {
+          styleEl.setAttribute('data-zq-inline', this._def.styles);
+        }
+      }
       document.head.appendChild(styleEl);
       this._styleEl = styleEl;
     }
@@ -551,8 +566,10 @@ class Component {
 
     // Update DOM via morphing (diffing) — preserves unchanged nodes
     // First render uses innerHTML for speed; subsequent renders morph.
+    const _renderStart = typeof window !== 'undefined' && (window.__zqMorphHook || window.__zqRenderHook) ? performance.now() : 0;
     if (!this._mounted) {
       this._el.innerHTML = html;
+      if (_renderStart && window.__zqRenderHook) window.__zqRenderHook(this._el, performance.now() - _renderStart, 'mount', this._def._name);
     } else {
       morph(this._el, html);
     }
@@ -595,31 +612,31 @@ class Component {
     }
   }
 
-  // Bind @event="method" and z-on:event="method" handlers via delegation
+  // Bind @event="method" and z-on:event="method" handlers via delegation.
+  //
+  // Optimization: on the FIRST render, we scan for event attributes, build
+  // a delegated handler map, and attach one listener per event type to the
+  // component root. On subsequent renders (re-bind), we only rebuild the
+  // internal binding map — existing DOM listeners are reused since they
+  // delegate to event.target.closest(selector) at fire time.
   _bindEvents() {
-    // Clean up old delegated listeners
-    this._listeners.forEach(({ event, handler }) => {
-      this._el.removeEventListener(event, handler);
-    });
-    this._listeners = [];
+    // Always rebuild the binding map from current DOM
+    const eventMap = new Map(); // event → [{ selector, methodExpr, modifiers, el }]
 
-    // Find all elements with @event or z-on:event attributes
     const allEls = this._el.querySelectorAll('*');
-    const eventMap = new Map(); // event → [{ selector, method, modifiers }]
-
     allEls.forEach(child => {
-      // Skip elements inside z-pre subtrees
       if (child.closest('[z-pre]')) return;
 
-      [...child.attributes].forEach(attr => {
-        // Support both @event and z-on:event syntax
+      const attrs = child.attributes;
+      for (let a = 0; a < attrs.length; a++) {
+        const attr = attrs[a];
         let raw;
-        if (attr.name.startsWith('@')) {
-          raw = attr.name.slice(1); // @click.prevent → click.prevent
+        if (attr.name.charCodeAt(0) === 64) { // '@'
+          raw = attr.name.slice(1);
         } else if (attr.name.startsWith('z-on:')) {
-          raw = attr.name.slice(5); // z-on:click.prevent → click.prevent
+          raw = attr.name.slice(5);
         } else {
-          return;
+          continue;
         }
 
         const parts = raw.split('.');
@@ -635,12 +652,45 @@ class Component {
 
         if (!eventMap.has(event)) eventMap.set(event, []);
         eventMap.get(event).push({ selector, methodExpr, modifiers, el: child });
-      });
+      }
     });
 
+    // Store binding map for the delegated handlers to reference
+    this._eventBindings = eventMap;
+
+    // Only attach DOM listeners once — reuse on subsequent renders.
+    // The handlers close over `this` and read `this._eventBindings`
+    // at fire time, so they always use the latest binding map.
+    if (this._delegatedEvents) {
+      // Already attached — just make sure new event types are covered
+      for (const event of eventMap.keys()) {
+        if (!this._delegatedEvents.has(event)) {
+          this._attachDelegatedEvent(event, eventMap.get(event));
+        }
+      }
+      // Remove listeners for event types no longer in the template
+      for (const event of this._delegatedEvents.keys()) {
+        if (!eventMap.has(event)) {
+          const { handler, opts } = this._delegatedEvents.get(event);
+          this._el.removeEventListener(event, handler, opts);
+          this._delegatedEvents.delete(event);
+          // Also remove from _listeners array
+          this._listeners = this._listeners.filter(l => l.event !== event);
+        }
+      }
+      return;
+    }
+
+    this._delegatedEvents = new Map();
+
     // Register delegated listeners on the component root
     for (const [event, bindings] of eventMap) {
-      // Determine listener options from modifiers
+      this._attachDelegatedEvent(event, bindings);
+    }
+  }
+
+  // Attach a single delegated listener for an event type
+  _attachDelegatedEvent(event, bindings) {
       const needsCapture = bindings.some(b => b.modifiers.includes('capture'));
       const needsPassive = bindings.some(b => b.modifiers.includes('passive'));
       const listenerOpts = (needsCapture || needsPassive)
@@ -648,7 +698,9 @@ class Component {
         : false;
 
       const handler = (e) => {
-        for (const { selector, methodExpr, modifiers, el } of bindings) {
+        // Read bindings from live map — always up to date after re-renders
+        const currentBindings = this._eventBindings?.get(event) || [];
+        for (const { selector, methodExpr, modifiers, el } of currentBindings) {
           if (!e.target.closest(selector)) continue;
 
           // .self — only fire if target is the element itself
@@ -718,7 +770,7 @@ class Component {
       };
       this._el.addEventListener(event, handler, listenerOpts);
       this._listeners.push({ event, handler });
-    }
+      this._delegatedEvents.set(event, { handler, opts: listenerOpts });
   }
 
   // Bind z-ref="name" → this.refs.name
@@ -757,7 +809,7 @@ class Component {
       // Read current state value (supports dot-path keys)
       const currentVal = _getPath(this.state, key);
 
-      // -- Set initial DOM value from state ------------------------
+      // -- Set initial DOM value from state (always sync) ----------
       if (tag === 'input' && type === 'checkbox') {
         el.checked = !!currentVal;
       } else if (tag === 'input' && type === 'radio') {
@@ -779,6 +831,11 @@ class Component {
         : isEditable ? 'input' : 'input';
 
       // -- Handler: read DOM → write to reactive state -------------
+      // Skip if already bound (morph preserves existing elements,
+      // so re-binding would stack duplicate listeners)
+      if (el._zqModelBound) return;
+      el._zqModelBound = true;
+
       const handler = () => {
         let val;
         if (type === 'checkbox')           val = el.checked;
@@ -898,6 +955,41 @@ class Component {
     return temp.innerHTML;
   }
 
+  // ---------------------------------------------------------------------------
+  // _expandContentDirectives — Pre-morph z-html & z-text expansion
+  //
+  // Evaluates z-html and z-text directives at the string level so the morph
+  // engine receives HTML with the actual content inline. This lets the diff
+  // algorithm properly compare old vs new content (text nodes, child elements)
+  // instead of clearing + re-injecting on every re-render.
+  //
+  // Same parse → evaluate → serialize pattern as _expandZFor.
+  // ---------------------------------------------------------------------------
+  _expandContentDirectives(html) {
+    if (!html.includes('z-html') && !html.includes('z-text')) return html;
+
+    const temp = document.createElement('div');
+    temp.innerHTML = html;
+
+    // z-html: evaluate expression → inject as innerHTML
+    temp.querySelectorAll('[z-html]').forEach(el => {
+      if (el.closest('[z-pre]')) return;
+      const val = this._evalExpr(el.getAttribute('z-html'));
+      el.innerHTML = val != null ? String(val) : '';
+      el.removeAttribute('z-html');
+    });
+
+    // z-text: evaluate expression → inject as textContent (HTML-safe)
+    temp.querySelectorAll('[z-text]').forEach(el => {
+      if (el.closest('[z-pre]')) return;
+      const val = this._evalExpr(el.getAttribute('z-text'));
+      el.textContent = val != null ? String(val) : '';
+      el.removeAttribute('z-text');
+    });
+
+    return temp.innerHTML;
+  }
+
   // ---------------------------------------------------------------------------
   // _processDirectives — Post-innerHTML DOM-level directive processing
   // ---------------------------------------------------------------------------
@@ -950,25 +1042,36 @@ class Component {
     });
 
     // -- z-bind:attr / :attr (dynamic attribute binding) -----------
-    this._el.querySelectorAll('*').forEach(el => {
-      if (el.closest('[z-pre]')) return;
-      [...el.attributes].forEach(attr => {
+    // Use TreeWalker instead of querySelectorAll('*') — avoids
+    // creating a flat array of every single descendant element.
+    // TreeWalker visits nodes lazily; FILTER_REJECT skips z-pre subtrees
+    // at the walker level (faster than per-node closest('[z-pre]') checks).
+    const walker = document.createTreeWalker(this._el, NodeFilter.SHOW_ELEMENT, {
+      acceptNode(n) {
+        return n.hasAttribute('z-pre') ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT;
+      }
+    });
+    let node;
+    while ((node = walker.nextNode())) {
+      const attrs = node.attributes;
+      for (let i = attrs.length - 1; i >= 0; i--) {
+        const attr = attrs[i];
         let attrName;
         if (attr.name.startsWith('z-bind:')) attrName = attr.name.slice(7);
-        else if (attr.name.startsWith(':') && !attr.name.startsWith('::')) attrName = attr.name.slice(1);
-        else return;
+        else if (attr.name.charCodeAt(0) === 58 && attr.name.charCodeAt(1) !== 58) attrName = attr.name.slice(1); // ':' but not '::'
+        else continue;
 
         const val = this._evalExpr(attr.value);
-        el.removeAttribute(attr.name);
+        node.removeAttribute(attr.name);
         if (val === false || val === null || val === undefined) {
-          el.removeAttribute(attrName);
+          node.removeAttribute(attrName);
         } else if (val === true) {
-          el.setAttribute(attrName, '');
+          node.setAttribute(attrName, '');
         } else {
-          el.setAttribute(attrName, String(val));
+          node.setAttribute(attrName, String(val));
         }
-      });
-    });
+      }
+    }
 
     // -- z-class (dynamic class binding) ---------------------------
     this._el.querySelectorAll('[z-class]').forEach(el => {
@@ -1000,21 +1103,9 @@ class Component {
       el.removeAttribute('z-style');
     });
 
-    // -- z-html (innerHTML injection) ------------------------------
-    this._el.querySelectorAll('[z-html]').forEach(el => {
-      if (el.closest('[z-pre]')) return;
-      const val = this._evalExpr(el.getAttribute('z-html'));
-      el.innerHTML = val != null ? String(val) : '';
-      el.removeAttribute('z-html');
-    });
-
-    // -- z-text (safe textContent binding) -------------------------
-    this._el.querySelectorAll('[z-text]').forEach(el => {
-      if (el.closest('[z-pre]')) return;
-      const val = this._evalExpr(el.getAttribute('z-text'));
-      el.textContent = val != null ? String(val) : '';
-      el.removeAttribute('z-text');
-    });
+    // z-html and z-text are now pre-expanded at string level (before
+    // morph) via _expandContentDirectives(), so the diff engine can
+    // properly diff their content instead of clearing + re-injecting.
 
     // -- z-cloak (remove after render) -----------------------------
     this._el.querySelectorAll('[z-cloak]').forEach(el => {
@@ -1047,6 +1138,8 @@ class Component {
     }
     this._listeners.forEach(({ event, handler }) => this._el.removeEventListener(event, handler));
     this._listeners = [];
+    this._delegatedEvents = null;
+    this._eventBindings = null;
     if (this._styleEl) this._styleEl.remove();
     _instances.delete(this._el);
     this._el.innerHTML = '';
@@ -1197,6 +1290,36 @@ export function getRegistry() {
   return Object.fromEntries(_registry);
 }
 
+/**
+ * Pre-load a component's external templates and styles so the next mount
+ * renders synchronously (no blank flash while fetching).
+ * Safe to call multiple times — skips if already loaded.
+ * @param {string} name — registered component name
+ * @returns {Promise<void>}
+ */
+export async function prefetch(name) {
+  const def = _registry.get(name);
+  if (!def) return;
+
+  // Load templateUrl, styleUrl, and normalize pages config
+  if ((def.templateUrl && !def._templateLoaded) ||
+      (def.styleUrl && !def._styleLoaded) ||
+      (def.pages && !def._pagesNormalized)) {
+    await Component.prototype._loadExternals.call({ _def: def });
+  }
+
+  // For pages-based components, prefetch ALL page templates so any
+  // active page renders instantly on mount.
+  if (def._pageUrls && def._externalTemplates) {
+    const missing = Object.entries(def._pageUrls)
+      .filter(([id]) => !(id in def._externalTemplates));
+    if (missing.length) {
+      const results = await Promise.all(missing.map(([, url]) => _fetchResource(url)));
+      missing.forEach(([id], i) => { def._externalTemplates[id] = results[i]; });
+    }
+  }
+}
+
 
 // ---------------------------------------------------------------------------
 // Global stylesheet loader