zero-query 0.6.3 → 0.7.5

package/dist/zquery.js

@@ -1,13 +1,13 @@
 /**
- * zQuery (zeroQuery) v0.6.3
+ * zQuery (zeroQuery) v0.7.5
  * Lightweight Frontend Library
  * https://github.com/tonywied17/zero-query
- * (c) 2026 Anthony Wiedman — MIT License
+ * (c) 2026 Anthony Wiedman - MIT License
  */
 (function(global) {
   'use strict';
 
-// --- src/errors.js ———————————————————————————————————————————————
+// --- src/errors.js -----------------------------------------------
 /**
  * zQuery Errors — Structured error handling system
  *
@@ -164,7 +164,7 @@ function validate(value, name, expectedType) {
   }
 }
 
-// --- src/reactive.js —————————————————————————————————————————————
+// --- src/reactive.js ---------------------------------------------
 /**
  * zQuery Reactive — Proxy-based deep reactivity system
  * 
@@ -315,7 +315,7 @@ function effect(fn) {
   };
 }
 
-// --- src/core.js —————————————————————————————————————————————————
+// --- src/core.js -------------------------------------------------
 /**
  * zQuery Core — Selector engine & chainable DOM collection
  * 
@@ -393,8 +393,96 @@ class ZQueryCollection {
     return new ZQueryCollection(sibs);
   }
 
-  next()  { return new ZQueryCollection(this.elements.map(el => el.nextElementSibling).filter(Boolean)); }
-  prev()  { return new ZQueryCollection(this.elements.map(el => el.previousElementSibling).filter(Boolean)); }
+  next(selector)  {
+    const els = this.elements.map(el => el.nextElementSibling).filter(Boolean);
+    return new ZQueryCollection(selector ? els.filter(el => el.matches(selector)) : els);
+  }
+
+  prev(selector)  {
+    const els = this.elements.map(el => el.previousElementSibling).filter(Boolean);
+    return new ZQueryCollection(selector ? els.filter(el => el.matches(selector)) : els);
+  }
+
+  nextAll(selector) {
+    const result = [];
+    this.elements.forEach(el => {
+      let sib = el.nextElementSibling;
+      while (sib) {
+        if (!selector || sib.matches(selector)) result.push(sib);
+        sib = sib.nextElementSibling;
+      }
+    });
+    return new ZQueryCollection(result);
+  }
+
+  nextUntil(selector, filter) {
+    const result = [];
+    this.elements.forEach(el => {
+      let sib = el.nextElementSibling;
+      while (sib) {
+        if (selector && sib.matches(selector)) break;
+        if (!filter || sib.matches(filter)) result.push(sib);
+        sib = sib.nextElementSibling;
+      }
+    });
+    return new ZQueryCollection(result);
+  }
+
+  prevAll(selector) {
+    const result = [];
+    this.elements.forEach(el => {
+      let sib = el.previousElementSibling;
+      while (sib) {
+        if (!selector || sib.matches(selector)) result.push(sib);
+        sib = sib.previousElementSibling;
+      }
+    });
+    return new ZQueryCollection(result);
+  }
+
+  prevUntil(selector, filter) {
+    const result = [];
+    this.elements.forEach(el => {
+      let sib = el.previousElementSibling;
+      while (sib) {
+        if (selector && sib.matches(selector)) break;
+        if (!filter || sib.matches(filter)) result.push(sib);
+        sib = sib.previousElementSibling;
+      }
+    });
+    return new ZQueryCollection(result);
+  }
+
+  parents(selector) {
+    const result = [];
+    this.elements.forEach(el => {
+      let parent = el.parentElement;
+      while (parent) {
+        if (!selector || parent.matches(selector)) result.push(parent);
+        parent = parent.parentElement;
+      }
+    });
+    return new ZQueryCollection([...new Set(result)]);
+  }
+
+  parentsUntil(selector, filter) {
+    const result = [];
+    this.elements.forEach(el => {
+      let parent = el.parentElement;
+      while (parent) {
+        if (selector && parent.matches(selector)) break;
+        if (!filter || parent.matches(filter)) result.push(parent);
+        parent = parent.parentElement;
+      }
+    });
+    return new ZQueryCollection([...new Set(result)]);
+  }
+
+  contents() {
+    const result = [];
+    this.elements.forEach(el => result.push(...el.childNodes));
+    return new ZQueryCollection(result);
+  }
 
   filter(selector) {
     if (typeof selector === 'function') {
@@ -414,6 +502,42 @@ class ZQueryCollection {
     return new ZQueryCollection(this.elements.filter(el => el.querySelector(selector)));
   }
 
+  is(selector) {
+    if (typeof selector === 'function') {
+      return this.elements.some((el, i) => selector.call(el, i, el));
+    }
+    return this.elements.some(el => el.matches(selector));
+  }
+
+  slice(start, end) {
+    return new ZQueryCollection(this.elements.slice(start, end));
+  }
+
+  add(selector, context) {
+    const toAdd = (selector instanceof ZQueryCollection)
+      ? selector.elements
+      : (selector instanceof Node)
+        ? [selector]
+        : Array.from((context || document).querySelectorAll(selector));
+    return new ZQueryCollection([...this.elements, ...toAdd]);
+  }
+
+  get(index) {
+    if (index === undefined) return [...this.elements];
+    return index < 0 ? this.elements[this.length + index] : this.elements[index];
+  }
+
+  index(selector) {
+    if (selector === undefined) {
+      const el = this.first();
+      return el ? Array.from(el.parentElement.children).indexOf(el) : -1;
+    }
+    const target = (typeof selector === 'string')
+      ? document.querySelector(selector)
+      : selector;
+    return this.elements.indexOf(target);
+  }
+
   // --- Classes -------------------------------------------------------------
 
   addClass(...names) {
@@ -426,8 +550,12 @@ class ZQueryCollection {
     return this.each((_, el) => el.classList.remove(...classes));
   }
 
-  toggleClass(name, force) {
-    return this.each((_, el) => el.classList.toggle(name, force));
+  toggleClass(...args) {
+    const force = typeof args[args.length - 1] === 'boolean' ? args.pop() : undefined;
+    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));
+    });
   }
 
   hasClass(name) {
@@ -481,6 +609,60 @@ class ZQueryCollection {
     return el ? { top: el.offsetTop, left: el.offsetLeft } : null;
   }
 
+  scrollTop(value) {
+    if (value === undefined) {
+      const el = this.first();
+      return el === window ? window.scrollY : el?.scrollTop;
+    }
+    return this.each((_, el) => {
+      if (el === window) window.scrollTo(window.scrollX, value);
+      else el.scrollTop = value;
+    });
+  }
+
+  scrollLeft(value) {
+    if (value === undefined) {
+      const el = this.first();
+      return el === window ? window.scrollX : el?.scrollLeft;
+    }
+    return this.each((_, el) => {
+      if (el === window) window.scrollTo(value, window.scrollY);
+      else el.scrollLeft = value;
+    });
+  }
+
+  innerWidth() {
+    const el = this.first();
+    return el?.clientWidth;
+  }
+
+  innerHeight() {
+    const el = this.first();
+    return el?.clientHeight;
+  }
+
+  outerWidth(includeMargin = false) {
+    const el = this.first();
+    if (!el) return undefined;
+    let w = el.offsetWidth;
+    if (includeMargin) {
+      const style = getComputedStyle(el);
+      w += parseFloat(style.marginLeft) + parseFloat(style.marginRight);
+    }
+    return w;
+  }
+
+  outerHeight(includeMargin = false) {
+    const el = this.first();
+    if (!el) return undefined;
+    let h = el.offsetHeight;
+    if (includeMargin) {
+      const style = getComputedStyle(el);
+      h += parseFloat(style.marginTop) + parseFloat(style.marginBottom);
+    }
+    return h;
+  }
+
   // --- Content -------------------------------------------------------------
 
   html(content) {
@@ -560,6 +742,73 @@ class ZQueryCollection {
     });
   }
 
+  appendTo(target) {
+    const dest = typeof target === 'string' ? document.querySelector(target) : target instanceof ZQueryCollection ? target.first() : target;
+    if (dest) this.each((_, el) => dest.appendChild(el));
+    return this;
+  }
+
+  prependTo(target) {
+    const dest = typeof target === 'string' ? document.querySelector(target) : target instanceof ZQueryCollection ? target.first() : target;
+    if (dest) this.each((_, el) => dest.insertBefore(el, dest.firstChild));
+    return this;
+  }
+
+  insertAfter(target) {
+    const ref = typeof target === 'string' ? document.querySelector(target) : target instanceof ZQueryCollection ? target.first() : target;
+    if (ref && ref.parentNode) this.each((_, el) => ref.parentNode.insertBefore(el, ref.nextSibling));
+    return this;
+  }
+
+  insertBefore(target) {
+    const ref = typeof target === 'string' ? document.querySelector(target) : target instanceof ZQueryCollection ? target.first() : target;
+    if (ref && ref.parentNode) this.each((_, el) => ref.parentNode.insertBefore(el, ref));
+    return this;
+  }
+
+  replaceAll(target) {
+    const targets = typeof target === 'string'
+      ? Array.from(document.querySelectorAll(target))
+      : target instanceof ZQueryCollection ? target.elements : [target];
+    targets.forEach((t, i) => {
+      const nodes = i === 0 ? this.elements : this.elements.map(el => el.cloneNode(true));
+      nodes.forEach(el => t.parentNode.insertBefore(el, t));
+      t.remove();
+    });
+    return this;
+  }
+
+  unwrap(selector) {
+    this.elements.forEach(el => {
+      const parent = el.parentElement;
+      if (!parent || parent === document.body) return;
+      if (selector && !parent.matches(selector)) return;
+      parent.replaceWith(...parent.childNodes);
+    });
+    return this;
+  }
+
+  wrapAll(wrapper) {
+    const w = typeof wrapper === 'string' ? createFragment(wrapper).firstElementChild : wrapper.cloneNode(true);
+    const first = this.first();
+    if (!first) return this;
+    first.parentNode.insertBefore(w, first);
+    this.each((_, el) => w.appendChild(el));
+    return this;
+  }
+
+  wrapInner(wrapper) {
+    return this.each((_, el) => {
+      const w = typeof wrapper === 'string' ? createFragment(wrapper).firstElementChild : wrapper.cloneNode(true);
+      while (el.firstChild) w.appendChild(el.firstChild);
+      el.appendChild(w);
+    });
+  }
+
+  detach() {
+    return this.each((_, el) => el.remove());
+  }
+
   // --- Visibility ----------------------------------------------------------
 
   show(display = '') {
@@ -585,9 +834,10 @@ class ZQueryCollection {
       events.forEach(evt => {
         if (typeof selectorOrHandler === 'function') {
           el.addEventListener(evt, selectorOrHandler);
-        } else {
-          // Delegated event
+        } else if (typeof selectorOrHandler === 'string') {
+          // Delegated event — only works on elements that support closest()
           el.addEventListener(evt, (e) => {
+            if (!e.target || typeof e.target.closest !== 'function') return;
             const target = e.target.closest(selectorOrHandler);
             if (target && el.contains(target)) handler.call(target, e);
           });
@@ -620,6 +870,10 @@ class ZQueryCollection {
   submit(fn)  { return fn ? this.on('submit', fn) : this.trigger('submit'); }
   focus()     { this.first()?.focus(); return this; }
   blur()      { this.first()?.blur(); return this; }
+  hover(enterFn, leaveFn) {
+    this.on('mouseenter', enterFn);
+    return this.on('mouseleave', leaveFn || enterFn);
+  }
 
   // --- Animation -----------------------------------------------------------
 
@@ -651,6 +905,40 @@ class ZQueryCollection {
     return this.animate({ opacity: '0' }, duration).then(col => col.hide());
   }
 
+  fadeToggle(duration = 300) {
+    return Promise.all(this.elements.map(el => {
+      const visible = getComputedStyle(el).opacity !== '0' && getComputedStyle(el).display !== 'none';
+      const col = new ZQueryCollection([el]);
+      return visible ? col.fadeOut(duration) : col.fadeIn(duration);
+    })).then(() => this);
+  }
+
+  fadeTo(duration, opacity) {
+    return this.animate({ opacity: String(opacity) }, duration);
+  }
+
+  slideDown(duration = 300) {
+    return this.each((_, el) => {
+      el.style.display = '';
+      el.style.overflow = 'hidden';
+      const h = el.scrollHeight + 'px';
+      el.style.maxHeight = '0';
+      el.style.transition = `max-height ${duration}ms ease`;
+      requestAnimationFrame(() => { el.style.maxHeight = h; });
+      setTimeout(() => { el.style.maxHeight = ''; el.style.overflow = ''; el.style.transition = ''; }, duration);
+    });
+  }
+
+  slideUp(duration = 300) {
+    return this.each((_, el) => {
+      el.style.overflow = 'hidden';
+      el.style.maxHeight = el.scrollHeight + 'px';
+      el.style.transition = `max-height ${duration}ms ease`;
+      requestAnimationFrame(() => { el.style.maxHeight = '0'; });
+      setTimeout(() => { el.style.display = 'none'; el.style.maxHeight = ''; el.style.overflow = ''; el.style.transition = ''; }, duration);
+    });
+  }
+
   slideToggle(duration = 300) {
     return this.each((_, el) => {
       if (el.style.display === 'none' || getComputedStyle(el).display === 'none') {
@@ -798,7 +1086,7 @@ query.children = (parentId) => {
   return new ZQueryCollection(p ? Array.from(p.children) : []);
 };
 
-// Create element shorthand
+// Create element shorthand — returns ZQueryCollection for chaining
 query.create = (tag, attrs = {}, ...children) => {
   const el = document.createElement(tag);
   for (const [k, v] of Object.entries(attrs)) {
@@ -812,7 +1100,7 @@ query.create = (tag, attrs = {}, ...children) => {
     if (typeof child === 'string') el.appendChild(document.createTextNode(child));
     else if (child instanceof Node) el.appendChild(child);
   });
-  return el;
+  return new ZQueryCollection(el);
 };
 
 // DOM ready
@@ -821,17 +1109,24 @@ query.ready = (fn) => {
   else document.addEventListener('DOMContentLoaded', fn);
 };
 
-// Global event listeners — supports direct and delegated forms
+// Global event listeners — supports direct, delegated, and target-bound forms
 //   $.on('keydown', handler)           → direct listener on document
 //   $.on('click', '.btn', handler)     → delegated via closest()
+//   $.on('scroll', window, handler)    → direct listener on target
 query.on = (event, selectorOrHandler, handler) => {
   if (typeof selectorOrHandler === 'function') {
     // 2-arg: direct document listener (keydown, resize, etc.)
     document.addEventListener(event, selectorOrHandler);
     return;
   }
-  // 3-arg: delegated
+  // EventTarget (window, element, etc.) — direct listener on target
+  if (typeof selectorOrHandler === 'object' && typeof selectorOrHandler.addEventListener === 'function') {
+    selectorOrHandler.addEventListener(event, handler);
+    return;
+  }
+  // 3-arg string: delegated
   document.addEventListener(event, (e) => {
+    if (!e.target || typeof e.target.closest !== 'function') return;
     const target = e.target.closest(selectorOrHandler);
     if (target) handler.call(target, e);
   });
@@ -845,7 +1140,7 @@ query.off = (event, handler) => {
 // Extend collection prototype (like $.fn in jQuery)
 query.fn = ZQueryCollection.prototype;
 
-// --- src/expression.js ———————————————————————————————————————————
+// --- src/expression.js -------------------------------------------
 /**
  * zQuery Expression Parser — CSP-safe expression evaluator
  *
@@ -1653,7 +1948,7 @@ function safeEval(expr, scope) {
   }
 }
 
-// --- src/diff.js —————————————————————————————————————————————————
+// --- src/diff.js -------------------------------------------------
 /**
  * zQuery Diff — Lightweight DOM morphing engine
  *
@@ -1935,7 +2230,7 @@ function _getKey(node) {
   return node.getAttribute('z-key') || null;
 }
 
-// --- src/component.js ————————————————————————————————————————————
+// --- src/component.js --------------------------------------------
 /**
  * zQuery Component — Lightweight reactive component system
  * 
@@ -2318,11 +2613,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;
     }
@@ -2449,6 +2747,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;
     }
@@ -3235,7 +3540,7 @@ function style(urls, opts = {}) {
   };
 }
 
-// --- src/router.js ———————————————————————————————————————————————
+// --- src/router.js -----------------------------------------------
 /**
  * zQuery Router — Client-side SPA router
  * 
@@ -3315,7 +3620,21 @@ class Router {
       if (!link) return;
       if (link.getAttribute('target') === '_blank') return;
       e.preventDefault();
-      this.navigate(link.getAttribute('z-link'));
+      let href = link.getAttribute('z-link');
+      // 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 */ }
+      }
+      this.navigate(href);
+      // z-to-top modifier: scroll to top after navigation
+      if (link.hasAttribute('z-to-top')) {
+        const scrollBehavior = link.getAttribute('z-to-top') || 'instant';
+        window.scrollTo({ top: 0, behavior: scrollBehavior });
+      }
     });
 
     // Initial resolve
@@ -3359,7 +3678,23 @@ class Router {
 
   // --- Navigation ----------------------------------------------------------
 
+  /**
+   * 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 }
+   * @returns {string}
+   */
+  _interpolateParams(path, params) {
+    if (!params || typeof params !== 'object') return path;
+    return path.replace(/:([\w]+)/g, (_, key) => {
+      const val = params[key];
+      return val != null ? encodeURIComponent(String(val)) : ':' + key;
+    });
+  }
+
   navigate(path, options = {}) {
+    // Interpolate :param placeholders if options.params is provided
+    if (options.params) path = this._interpolateParams(path, options.params);
     // Separate hash fragment (e.g. /docs/getting-started#cli-bundler)
     const [cleanPath, fragment] = (path || '').split('#');
     let normalized = this._normalizePath(cleanPath);
@@ -3377,6 +3712,8 @@ class Router {
   }
 
   replace(path, options = {}) {
+    // Interpolate :param placeholders if options.params is provided
+    if (options.params) path = this._interpolateParams(path, options.params);
     const [cleanPath, fragment] = (path || '').split('#');
     let normalized = this._normalizePath(cleanPath);
     const hash = fragment ? '#' + fragment : '';
@@ -3490,6 +3827,7 @@ class Router {
     // Prevent re-entrant calls (e.g. listener triggering navigation)
     if (this._resolving) return;
     this._resolving = true;
+    this._redirectCount = 0;
     try {
       await this.__resolve();
     } finally {
@@ -3531,7 +3869,21 @@ class Router {
         const result = await guard(to, from);
         if (result === false) return;                    // Cancel
         if (typeof result === 'string') {                // Redirect
-          return this.navigate(result);
+          if (++this._redirectCount > 10) {
+            reportError(ErrorCode.ROUTER_GUARD, 'Too many guard redirects (possible loop)', { to }, null);
+            return;
+          }
+          // Update URL directly and re-resolve (avoids re-entrancy block)
+          const [rPath, rFrag] = result.split('#');
+          const rNorm = this._normalizePath(rPath || '/');
+          const rHash = rFrag ? '#' + rFrag : '';
+          if (this._mode === 'hash') {
+            if (rFrag) window.__zqScrollTarget = rFrag;
+            window.location.replace('#' + rNorm);
+          } else {
+            window.history.replaceState({}, '', this._base + rNorm + rHash);
+          }
+          return this.__resolve();
         }
       } catch (err) {
         reportError(ErrorCode.ROUTER_GUARD, 'Before-guard threw', { to, from }, err);
@@ -3610,7 +3962,7 @@ function getRouter() {
   return _activeRouter;
 }
 
-// --- src/store.js ————————————————————————————————————————————————
+// --- src/store.js ------------------------------------------------
 /**
  * zQuery Store — Global reactive state management
  * 
@@ -3796,7 +4148,7 @@ function getStore(name = 'default') {
   return _stores.get(name) || null;
 }
 
-// --- src/http.js —————————————————————————————————————————————————
+// --- src/http.js -------------------------------------------------
 /**
  * zQuery HTTP — Lightweight fetch wrapper
  * 
@@ -3983,7 +4335,7 @@ const http = {
   raw: (url, opts) => fetch(url, opts),
 };
 
-// --- src/utils.js ————————————————————————————————————————————————
+// --- src/utils.js ------------------------------------------------
 /**
  * zQuery Utils — Common utility functions
  * 
@@ -4256,7 +4608,7 @@ class EventBus {
 
 const bus = new EventBus();
 
-// --- index.js (assembly) ——————————————————————————————————————————
+// --- index.js (assembly) ------------------------------------------
 /**
  * ┌---------------------------------------------------------┐
  * │  zQuery (zeroQuery) — Lightweight Frontend Library     │
@@ -4399,7 +4751,7 @@ $.ZQueryError = ZQueryError;
 $.ErrorCode   = ErrorCode;
 
 // --- Meta ------------------------------------------------------------------
-$.version = '0.6.3';
+$.version = '0.7.5';
 $.meta    = {};                // populated at build time by CLI bundler
 
 $.noConflict = () => {