zero-query 0.7.5 → 0.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-query",
-  "version": "0.7.5",
+  "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",
@@ -21,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"
   },

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.
@@ -472,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
@@ -561,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);
     }
@@ -605,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('.');
@@ -645,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)
@@ -658,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
@@ -728,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
@@ -767,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') {
@@ -789,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;
@@ -908,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
   // ---------------------------------------------------------------------------
@@ -960,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 => {
@@ -1010,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 => {
@@ -1057,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 = '';
@@ -1207,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

package/src/core.js

@@ -5,6 +5,8 @@
  * into a full jQuery-like chainable wrapper with modern APIs.
  */
 
+import { morph as _morph, morphElement as _morphElement } from './diff.js';
+
 // ---------------------------------------------------------------------------
 // ZQueryCollection — wraps an array of elements with chainable methods
 // ---------------------------------------------------------------------------
@@ -223,21 +225,46 @@ export class ZQueryCollection {
   // --- Classes -------------------------------------------------------------
 
   addClass(...names) {
+    // Fast path: single class, no spaces — avoids flatMap + regex split allocation
+    if (names.length === 1 && names[0].indexOf(' ') === -1) {
+      const c = names[0];
+      for (let i = 0; i < this.elements.length; i++) this.elements[i].classList.add(c);
+      return this;
+    }
     const classes = names.flatMap(n => n.split(/\s+/));
-    return this.each((_, el) => el.classList.add(...classes));
+    for (let i = 0; i < this.elements.length; i++) this.elements[i].classList.add(...classes);
+    return this;
   }
 
   removeClass(...names) {
+    if (names.length === 1 && names[0].indexOf(' ') === -1) {
+      const c = names[0];
+      for (let i = 0; i < this.elements.length; i++) this.elements[i].classList.remove(c);
+      return this;
+    }
     const classes = names.flatMap(n => n.split(/\s+/));
-    return this.each((_, el) => el.classList.remove(...classes));
+    for (let i = 0; i < this.elements.length; i++) this.elements[i].classList.remove(...classes);
+    return this;
   }
 
   toggleClass(...args) {
     const force = typeof args[args.length - 1] === 'boolean' ? args.pop() : undefined;
+    // Fast path: single class, no spaces
+    if (args.length === 1 && args[0].indexOf(' ') === -1) {
+      const c = args[0];
+      for (let i = 0; i < this.elements.length; i++) {
+        force !== undefined ? this.elements[i].classList.toggle(c, force) : this.elements[i].classList.toggle(c);
+      }
+      return this;
+    }
     const classes = args.flatMap(n => n.split(/\s+/));
-    return this.each((_, el) => {
-      classes.forEach(c => force !== undefined ? el.classList.toggle(c, force) : el.classList.toggle(c));
-    });
+    for (let i = 0; i < this.elements.length; i++) {
+      const el = this.elements[i];
+      for (let j = 0; j < classes.length; j++) {
+        force !== undefined ? el.classList.toggle(classes[j], force) : el.classList.toggle(classes[j]);
+      }
+    }
+    return this;
   }
 
   hasClass(name) {
@@ -273,7 +300,8 @@ export class ZQueryCollection {
 
   css(props) {
     if (typeof props === 'string') {
-      return getComputedStyle(this.first())[props];
+      const el = this.first();
+      return el ? getComputedStyle(el)[props] : undefined;
     }
     return this.each((_, el) => Object.assign(el.style, props));
   }
@@ -349,7 +377,21 @@ export class ZQueryCollection {
 
   html(content) {
     if (content === undefined) return this.first()?.innerHTML;
-    return this.each((_, el) => { el.innerHTML = content; });
+    // Auto-morph: if the element already has children, use the diff engine
+    // to patch the DOM (preserves focus, scroll, state, keyed reorder via LIS).
+    // Empty elements get raw innerHTML for fast first-paint — same strategy
+    // the component system uses (first render = innerHTML, updates = morph).
+    return this.each((_, el) => {
+      if (el.childNodes.length > 0) {
+        _morph(el, content);
+      } else {
+        el.innerHTML = content;
+      }
+    });
+  }
+
+  morph(content) {
+    return this.each((_, el) => { _morph(el, content); });
   }
 
   text(content) {
@@ -406,7 +448,8 @@ export class ZQueryCollection {
   }
 
   empty() {
-    return this.each((_, el) => { el.innerHTML = ''; });
+    // textContent = '' clears all children without invoking the HTML parser
+    return this.each((_, el) => { el.textContent = ''; });
   }
 
   clone(deep = true) {
@@ -416,8 +459,9 @@ export class ZQueryCollection {
   replaceWith(content) {
     return this.each((_, el) => {
       if (typeof content === 'string') {
-        el.insertAdjacentHTML('afterend', content);
-        el.remove();
+        // Auto-morph: diff attributes + children when the tag name matches
+        // instead of destroying and re-creating the element.
+        _morphElement(el, content);
       } else if (content instanceof Node) {
         el.parentNode.replaceChild(content, el);
       }
@@ -503,7 +547,9 @@ export class ZQueryCollection {
 
   toggle(display = '') {
     return this.each((_, el) => {
-      el.style.display = (el.style.display === 'none' || getComputedStyle(el).display === 'none') ? display : 'none';
+      // Check inline style first (cheap) before forcing layout via getComputedStyle
+      const hidden = el.style.display === 'none' || (el.style.display !== '' ? false : getComputedStyle(el).display === 'none');
+      el.style.display = hidden ? display : 'none';
     });
   }