zero-query 0.7.5 → 0.8.7

package/package.json

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

@@ -15,7 +15,7 @@
  *   - Scoped styles (inline or via styleUrl)
  *   - External templates via templateUrl (with {{expression}} interpolation)
  *   - External styles via styleUrl (fetched & scoped automatically)
- *   - Relative path resolution — templateUrl, styleUrl, and pages.dir
+ *   - Relative path resolution — templateUrl and styleUrl
  *     resolve relative to the component file automatically
  */
 
@@ -86,16 +86,6 @@ function _fetchResource(url) {
   return promise;
 }
 
-/**
- * Convert a kebab-case id to Title Case.
- * 'getting-started' → 'Getting Started'
- * @param {string} id
- * @returns {string}
- */
-function _titleCase(id) {
-  return id.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
-}
-
 /**
  * Resolve a relative URL against a base.
  *
@@ -314,47 +304,10 @@ class Component {
   //   - string              → single stylesheet
   //   - string[]            → array of URLs → all fetched & concatenated
   //
-  // pages config (shorthand for multi-template + route-param page switching):
-  //   pages: {
-  //     dir:     'pages',             // relative to component file (or base)
-  //     param:   'section',           // route param name → this.activePage
-  //     default: 'getting-started',   // fallback when param is absent
-  //     ext:     '.html',             // file extension (default '.html')
-  //     items:   ['page-a', { id: 'page-b', label: 'Page B' }, ...]
-  //   }
-  //   Exposes this.pages (array of {id,label}), this.activePage (current id)
-  //   Pages are lazy-loaded: only the active page is fetched on first render,
-  //   remaining pages are prefetched in the background for instant navigation.
-  //
   async _loadExternals() {
     const def = this._def;
     const base = def._base; // auto-detected or explicit
 
-    // -- Pages config ---------------------------------------------
-    if (def.pages && !def._pagesNormalized) {
-      const p = def.pages;
-      const ext = p.ext || '.html';
-      const dir = _resolveUrl((p.dir || '').replace(/\/+$/, ''), base);
-
-      // 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) };
-      });
-
-      // Build URL map for lazy per-page loading.
-      // Pages are fetched on demand (active page first, rest prefetched in
-      // the background) so the component renders as soon as the visible
-      // page is ready instead of waiting for every page to download.
-      def._pageUrls = {};
-      for (const { id } of def._pages) {
-        def._pageUrls[id] = `${dir}/${id}${ext}`;
-      }
-      if (!def._externalTemplates) def._externalTemplates = {};
-
-      def._pagesNormalized = true;
-    }
-
     // -- External templates --------------------------------------
     if (def.templateUrl && !def._templateLoaded) {
       const tu = def.templateUrl;
@@ -367,9 +320,8 @@ class Component {
         results.forEach((html, i) => { def._externalTemplates[i] = html; });
       } else if (typeof tu === 'object') {
         const entries = Object.entries(tu);
-        // Pages config already resolved; plain objects still need resolving
         const results = await Promise.all(
-          entries.map(([, url]) => _fetchResource(def._pagesNormalized ? url : _resolveUrl(url, base)))
+          entries.map(([, url]) => _fetchResource(_resolveUrl(url, base)))
         );
         def._externalTemplates = {};
         entries.forEach(([key], i) => { def._externalTemplates[key] = results[i]; });
@@ -398,8 +350,7 @@ class Component {
   _render() {
     // If externals haven't loaded yet, trigger async load then re-render
     if ((this._def.templateUrl && !this._def._templateLoaded) ||
-        (this._def.styleUrl && !this._def._styleLoaded) ||
-        (this._def.pages && !this._def._pagesNormalized)) {
+        (this._def.styleUrl && !this._def._styleLoaded)) {
       this._loadExternals().then(() => {
         if (!this._destroyed) this._render();
       });
@@ -411,43 +362,6 @@ class Component {
       this.templates = this._def._externalTemplates;
     }
 
-    // Expose pages metadata and active page (derived from route param)
-    if (this._def._pages) {
-      this.pages = this._def._pages;
-      const pc = this._def.pages;
-      let active = (pc.param && this.props.$params?.[pc.param]) || pc.default || this._def._pages[0]?.id || '';
-
-      // Fall back to default if the param doesn't match any known page
-      if (this._def._pageUrls && !(active in this._def._pageUrls)) {
-        active = pc.default || this._def._pages[0]?.id || '';
-      }
-      this.activePage = active;
-
-      // Lazy-load: fetch only the active page's template on demand
-      if (this._def._pageUrls && !(active in this._def._externalTemplates)) {
-        const url = this._def._pageUrls[active];
-        if (url) {
-          _fetchResource(url).then(html => {
-            this._def._externalTemplates[active] = html;
-            if (!this._destroyed) this._render();
-          });
-          return; // Wait for active page before rendering
-        }
-      }
-
-      // Prefetch remaining pages in background (once, after active page is ready)
-      if (this._def._pageUrls && !this._def._pagesPrefetched) {
-        this._def._pagesPrefetched = true;
-        for (const [id, url] of Object.entries(this._def._pageUrls)) {
-          if (!(id in this._def._externalTemplates)) {
-            _fetchResource(url).then(html => {
-              this._def._externalTemplates[id] = html;
-            });
-          }
-        }
-      }
-    }
-
     // Determine HTML content
     let html;
     if (this._def.render) {
@@ -472,6 +386,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 +480,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 +526,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 +566,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 +612,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 +684,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 +723,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 +745,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 +869,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 +956,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 +1017,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 +1052,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 = '';
@@ -1067,7 +1064,7 @@ class Component {
 // Reserved definition keys (not user methods)
 const _reservedKeys = new Set([
   'state', 'render', 'styles', 'init', 'mounted', 'updated', 'destroyed', 'props',
-  'templateUrl', 'styleUrl', 'templates', 'pages', 'activePage', 'base',
+  'templateUrl', 'styleUrl', 'templates', 'base',
   'computed', 'watch'
 ]);
 
@@ -1090,8 +1087,8 @@ export function component(name, definition) {
   }
   definition._name = name;
 
-  // Auto-detect the calling module's URL so that relative templateUrl,
-  // styleUrl, and pages.dir paths resolve relative to the component file.
+  // Auto-detect the calling module's URL so that relative templateUrl
+  // and styleUrl paths resolve relative to the component file.
   // An explicit `base` string on the definition overrides auto-detection.
   if (definition.base !== undefined) {
     definition._base = definition.base;   // explicit override
@@ -1207,6 +1204,24 @@ 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 and styleUrl if not already loaded.
+  if ((def.templateUrl && !def._templateLoaded) ||
+      (def.styleUrl && !def._styleLoaded)) {
+    await Component.prototype._loadExternals.call({ _def: def });
+  }
+}
+
 
 // ---------------------------------------------------------------------------
 // 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';
     });
   }