zero-query 0.9.0 → 0.9.5

package/index.d.ts

@@ -4,7 +4,7 @@
  * Lightweight modern frontend library — jQuery-like selectors, reactive
  * components, SPA router, state management, HTTP client & utilities.
  *
- * @version 0.9.0
+ * @version 0.9.5
  * @license MIT
  * @see https://z-query.com/docs
  */
@@ -74,6 +74,7 @@ export {
   once,
   sleep,
   escapeHtml,
+  stripHtml,
   html,
   TrustedHTML,
   trust,
@@ -90,6 +91,23 @@ export {
   session,
   EventBus,
   bus,
+  range,
+  unique,
+  chunk,
+  groupBy,
+  pick,
+  omit,
+  getPath,
+  setPath,
+  isEmpty,
+  capitalize,
+  truncate,
+  clamp,
+  MemoizedFunction,
+  memoize,
+  RetryOptions,
+  retry,
+  timeout,
 } from './types/utils';
 
 export {
@@ -122,11 +140,15 @@ import type { createStore, getStore } from './types/store';
 import type { HttpClient } from './types/http';
 import type {
   debounce, throttle, pipe, once, sleep,
-  escapeHtml, html, trust, uuid, camelCase, kebabCase,
+  escapeHtml, stripHtml, html, trust, uuid, camelCase, kebabCase,
   deepClone, deepMerge, isEqual, param, parseQuery,
   StorageWrapper, EventBus,
+  range, unique, chunk, groupBy,
+  pick, omit, getPath, setPath, isEmpty,
+  capitalize, truncate, clamp,
+  MemoizedFunction, memoize, RetryOptions, retry, timeout,
 } from './types/utils';
-import type { onError, ZQueryError, ErrorCode } from './types/errors';
+import type { onError, ZQueryError, ErrorCode, guardCallback, validate } from './types/errors';
 import type { morph, morphElement, safeEval } from './types/misc';
 
 /**
@@ -169,6 +191,10 @@ interface ZQueryStatic {
   name(name: string): ZQueryCollection;
   /** Children of `#parentId` as `ZQueryCollection`. */
   children(parentId: string): ZQueryCollection;
+  /** `document.querySelector(selector)` — raw Element or null. */
+  qs(selector: string, context?: Element | Document): Element | null;
+  /** `document.querySelectorAll(selector)` — as a real `Array<Element>`. */
+  qsa(selector: string, context?: Element | Document): Element[];
 
   // -- Static helpers ------------------------------------------------------
   /**
@@ -245,6 +271,10 @@ interface ZQueryStatic {
   ZQueryError: typeof ZQueryError;
   /** Frozen map of all error code constants. */
   ErrorCode: typeof ErrorCode;
+  /** Wrap a callback so thrown errors are caught and reported via the global handler. */
+  guardCallback: typeof guardCallback;
+  /** Validate a required value is defined and of the expected type. */
+  validate: typeof validate;
 
   // -- Utilities -----------------------------------------------------------
   debounce: typeof debounce;
@@ -254,6 +284,7 @@ interface ZQueryStatic {
   sleep: typeof sleep;
 
   escapeHtml: typeof escapeHtml;
+  stripHtml: typeof stripHtml;
   html: typeof html;
   trust: typeof trust;
   uuid: typeof uuid;
@@ -269,8 +300,25 @@ interface ZQueryStatic {
 
   storage: StorageWrapper;
   session: StorageWrapper;
+  EventBus: typeof EventBus;
   bus: EventBus;
 
+  range: typeof range;
+  unique: typeof unique;
+  chunk: typeof chunk;
+  groupBy: typeof groupBy;
+  pick: typeof pick;
+  omit: typeof omit;
+  getPath: typeof getPath;
+  setPath: typeof setPath;
+  isEmpty: typeof isEmpty;
+  capitalize: typeof capitalize;
+  truncate: typeof truncate;
+  clamp: typeof clamp;
+  memoize: typeof memoize;
+  retry: typeof retry;
+  timeout: typeof timeout;
+
   // -- Meta ----------------------------------------------------------------
   /** Library version string. */
   version: string;

package/index.js

@@ -19,9 +19,13 @@ import { morph, morphElement } from './src/diff.js';
 import { safeEval } from './src/expression.js';
 import {
   debounce, throttle, pipe, once, sleep,
-  escapeHtml, html, trust, uuid, camelCase, kebabCase,
+  escapeHtml, stripHtml, html, trust, TrustedHTML, uuid, camelCase, kebabCase,
   deepClone, deepMerge, isEqual, param, parseQuery,
-  storage, session, bus,
+  storage, session, EventBus, bus,
+  range, unique, chunk, groupBy,
+  pick, omit, getPath, setPath, isEmpty,
+  capitalize, truncate, clamp,
+  memoize, retry, timeout,
 } from './src/utils.js';
 import { ZQueryError, ErrorCode, onError, reportError, guardCallback, validate } from './src/errors.js';
 
@@ -61,6 +65,8 @@ Object.defineProperty($, 'name', {
   value: query.name, writable: true, configurable: true
 });
 $.children = query.children;
+$.qs       = query.qs;
+$.qsa      = query.qsa;
 
 // --- Collection selector ---------------------------------------------------
 /**
@@ -129,8 +135,10 @@ $.pipe       = pipe;
 $.once       = once;
 $.sleep      = sleep;
 $.escapeHtml = escapeHtml;
+$.stripHtml  = stripHtml;
 $.html       = html;
 $.trust      = trust;
+$.TrustedHTML = TrustedHTML;
 $.uuid       = uuid;
 $.camelCase  = camelCase;
 $.kebabCase  = kebabCase;
@@ -141,7 +149,23 @@ $.param      = param;
 $.parseQuery = parseQuery;
 $.storage    = storage;
 $.session    = session;
+$.EventBus   = EventBus;
 $.bus        = bus;
+$.range      = range;
+$.unique     = unique;
+$.chunk      = chunk;
+$.groupBy    = groupBy;
+$.pick       = pick;
+$.omit       = omit;
+$.getPath    = getPath;
+$.setPath    = setPath;
+$.isEmpty    = isEmpty;
+$.capitalize = capitalize;
+$.truncate   = truncate;
+$.clamp      = clamp;
+$.memoize    = memoize;
+$.retry      = retry;
+$.timeout    = timeout;
 
 // --- Error handling --------------------------------------------------------
 $.onError        = onError;
@@ -189,9 +213,13 @@ export {
   http,
   ZQueryError, ErrorCode, onError, reportError, guardCallback, validate,
   debounce, throttle, pipe, once, sleep,
-  escapeHtml, html, trust, uuid, camelCase, kebabCase,
+  escapeHtml, stripHtml, html, trust, TrustedHTML, uuid, camelCase, kebabCase,
   deepClone, deepMerge, isEqual, param, parseQuery,
-  storage, session, bus,
+  storage, session, EventBus, bus,
+  range, unique, chunk, groupBy,
+  pick, omit, getPath, setPath, isEmpty,
+  capitalize, truncate, clamp,
+  memoize, retry, timeout,
 };
 
 export default $;

package/package.json

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

package/src/component.js

@@ -264,7 +264,7 @@ class Component {
     if (!watchers) return;
     for (const [key, handler] of Object.entries(watchers)) {
       // Match exact key or parent key (e.g. watcher on 'user' fires when 'user.name' changes)
-      if (changedKey === key || key.startsWith(changedKey + '.') || changedKey.startsWith(key + '.') || changedKey === key) {
+      if (changedKey === key || key.startsWith(changedKey + '.') || changedKey.startsWith(key + '.')) {
         const currentVal = _getPath(this.state.__raw || this.state, key);
         const prevVal = this._prevWatchValues?.[key];
         if (currentVal !== prevVal) {
@@ -413,20 +413,26 @@ class Component {
     if (!this._mounted && combinedStyles) {
       const scopeAttr = `z-s${this._uid}`;
       this._el.setAttribute(scopeAttr, '');
-      let inAtBlock = 0;
+      let noScopeDepth = 0;   // brace depth at which a no-scope @-rule started (0 = none active)
+      let braceDepth = 0;     // overall brace depth
       const scoped = combinedStyles.replace(/([^{}]+)\{|\}/g, (match, selector) => {
         if (match === '}') {
-          if (inAtBlock > 0) inAtBlock--;
+          if (noScopeDepth > 0 && braceDepth <= noScopeDepth) noScopeDepth = 0;
+          braceDepth--;
           return match;
         }
+        braceDepth++;
         const trimmed = selector.trim();
-        // Don't scope @-rules (@media, @keyframes, @supports, @container, @layer, @font-face, etc.)
+        // Don't scope @-rules themselves
         if (trimmed.startsWith('@')) {
-          inAtBlock++;
+          // @keyframes and @font-face contain non-selector content — skip scoping inside them
+          if (/^@(keyframes|font-face)\b/.test(trimmed)) {
+            noScopeDepth = braceDepth;
+          }
           return match;
         }
-        // Don't scope keyframe stops (from, to, 0%, 50%, etc.)
-        if (inAtBlock > 0 && /^[\d%\s,fromto]+$/.test(trimmed.replace(/\s/g, ''))) {
+        // Inside @keyframes or @font-face — don't scope inner rules
+        if (noScopeDepth > 0 && braceDepth > noScopeDepth) {
           return match;
         }
         return selector.split(',').map(s => `[${scopeAttr}] ${s.trim()}`).join(', ') + ' {';
@@ -614,15 +620,44 @@ class Component {
       const handler = (e) => {
         // 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;
+
+        // Collect matching bindings with their matched elements, then sort
+        // deepest-first so .stop correctly prevents ancestor handlers
+        // (mimics real DOM bubbling order within delegated events).
+        const hits = [];
+        for (const binding of currentBindings) {
+          const matched = e.target.closest(binding.selector);
+          if (!matched) continue;
+          hits.push({ ...binding, matched });
+        }
+        hits.sort((a, b) => {
+          if (a.matched === b.matched) return 0;
+          return a.matched.contains(b.matched) ? 1 : -1;
+        });
+
+        let stoppedAt = null; // Track elements that called .stop
+        for (const { selector, methodExpr, modifiers, el, matched } of hits) {
+
+          // In delegated events, .stop should prevent ancestor bindings from
+          // firing — stopPropagation alone only stops real DOM bubbling.
+          if (stoppedAt) {
+            let blocked = false;
+            for (const stopped of stoppedAt) {
+              if (matched.contains(stopped) && matched !== stopped) { blocked = true; break; }
+            }
+            if (blocked) continue;
+          }
 
           // .self — only fire if target is the element itself
           if (modifiers.includes('self') && e.target !== el) continue;
 
           // Handle modifiers
           if (modifiers.includes('prevent')) e.preventDefault();
-          if (modifiers.includes('stop')) e.stopPropagation();
+          if (modifiers.includes('stop')) {
+            e.stopPropagation();
+            if (!stoppedAt) stoppedAt = [];
+            stoppedAt.push(matched);
+          }
 
           // Build the invocation function
           const invoke = (evt) => {
@@ -1054,6 +1089,21 @@ class Component {
     this._listeners = [];
     this._delegatedEvents = null;
     this._eventBindings = null;
+    // Clear any pending debounce/throttle timers to prevent stale closures.
+    // Timers are keyed by individual child elements, so iterate all descendants.
+    const allEls = this._el.querySelectorAll('*');
+    allEls.forEach(child => {
+      const dTimers = _debounceTimers.get(child);
+      if (dTimers) {
+        for (const key in dTimers) clearTimeout(dTimers[key]);
+        _debounceTimers.delete(child);
+      }
+      const tTimers = _throttleTimers.get(child);
+      if (tTimers) {
+        for (const key in tTimers) clearTimeout(tTimers[key]);
+        _throttleTimers.delete(child);
+      }
+    });
     if (this._styleEl) this._styleEl.remove();
     _instances.delete(this._el);
     this._el.innerHTML = '';

package/src/core.js

@@ -12,7 +12,7 @@ import { morph as _morph, morphElement as _morphElement } from './diff.js';
 // ---------------------------------------------------------------------------
 export class ZQueryCollection {
   constructor(elements) {
-    this.elements = Array.isArray(elements) ? elements : [elements];
+    this.elements = Array.isArray(elements) ? elements : (elements ? [elements] : []);
     this.length = this.elements.length;
     this.elements.forEach((el, i) => { this[i] = el; });
   }
@@ -69,10 +69,12 @@ export class ZQueryCollection {
     return new ZQueryCollection([...kids]);
   }
 
-  siblings() {
+  siblings(selector) {
     const sibs = [];
     this.elements.forEach(el => {
-      sibs.push(...[...el.parentElement.children].filter(c => c !== el));
+      if (!el.parentElement) return;
+      const all = [...el.parentElement.children].filter(c => c !== el);
+      sibs.push(...(selector ? all.filter(c => c.matches(selector)) : all));
     });
     return new ZQueryCollection(sibs);
   }
@@ -214,7 +216,8 @@ export class ZQueryCollection {
   index(selector) {
     if (selector === undefined) {
       const el = this.first();
-      return el ? Array.from(el.parentElement.children).indexOf(el) : -1;
+      if (!el || !el.parentElement) return -1;
+      return Array.from(el.parentElement.children).indexOf(el);
     }
     const target = (typeof selector === 'string')
       ? document.querySelector(selector)
@@ -274,6 +277,11 @@ export class ZQueryCollection {
   // --- Attributes ----------------------------------------------------------
 
   attr(name, value) {
+    if (typeof name === 'object' && name !== null) {
+      return this.each((_, el) => {
+        for (const [k, v] of Object.entries(name)) el.setAttribute(k, v);
+      });
+    }
     if (value === undefined) return this.first()?.getAttribute(name);
     return this.each((_, el) => el.setAttribute(name, value));
   }
@@ -298,7 +306,10 @@ export class ZQueryCollection {
 
   // --- CSS / Dimensions ----------------------------------------------------
 
-  css(props) {
+  css(props, value) {
+    if (typeof props === 'string' && value !== undefined) {
+      return this.each((_, el) => { el.style[props] = value; });
+    }
     if (typeof props === 'string') {
       const el = this.first();
       return el ? getComputedStyle(el)[props] : undefined;
@@ -438,6 +449,7 @@ export class ZQueryCollection {
   wrap(wrapper) {
     return this.each((_, el) => {
       const w = typeof wrapper === 'string' ? createFragment(wrapper).firstElementChild : wrapper.cloneNode(true);
+      if (!w || !el.parentNode) return;
       el.parentNode.insertBefore(w, el);
       w.appendChild(el);
     });
@@ -563,12 +575,18 @@ export class ZQueryCollection {
         if (typeof selectorOrHandler === 'function') {
           el.addEventListener(evt, selectorOrHandler);
         } else if (typeof selectorOrHandler === 'string') {
-          // Delegated event — only works on elements that support closest()
-          el.addEventListener(evt, (e) => {
+          // Delegated event — store wrapper so off() can remove it
+          const wrapper = (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);
-          });
+          };
+          wrapper._zqOriginal = handler;
+          wrapper._zqSelector = selectorOrHandler;
+          el.addEventListener(evt, wrapper);
+          // Track delegated handlers for removal
+          if (!el._zqDelegated) el._zqDelegated = [];
+          el._zqDelegated.push({ evt, wrapper });
         }
       });
     });
@@ -577,7 +595,20 @@ export class ZQueryCollection {
   off(event, handler) {
     const events = event.split(/\s+/);
     return this.each((_, el) => {
-      events.forEach(evt => el.removeEventListener(evt, handler));
+      events.forEach(evt => {
+        // Try direct removal first
+        el.removeEventListener(evt, handler);
+        // Also check delegated handlers
+        if (el._zqDelegated) {
+          el._zqDelegated = el._zqDelegated.filter(d => {
+            if (d.evt === evt && d.wrapper._zqOriginal === handler) {
+              el.removeEventListener(evt, d.wrapper);
+              return false;
+            }
+            return true;
+          });
+        }
+      });
     });
   }
 
@@ -606,8 +637,12 @@ export class ZQueryCollection {
   // --- Animation -----------------------------------------------------------
 
   animate(props, duration = 300, easing = 'ease') {
+    // Empty collection — resolve immediately
+    if (this.length === 0) return Promise.resolve(this);
     return new Promise(resolve => {
+      let resolved = false;
       const count = { done: 0 };
+      const listeners = [];
       this.each((_, el) => {
         el.style.transition = `all ${duration}ms ${easing}`;
         requestAnimationFrame(() => {
@@ -615,13 +650,27 @@ export class ZQueryCollection {
           const onEnd = () => {
             el.removeEventListener('transitionend', onEnd);
             el.style.transition = '';
-            if (++count.done >= this.length) resolve(this);
+            if (!resolved && ++count.done >= this.length) {
+              resolved = true;
+              resolve(this);
+            }
           };
           el.addEventListener('transitionend', onEnd);
+          listeners.push({ el, onEnd });
         });
       });
       // Fallback in case transitionend doesn't fire
-      setTimeout(() => resolve(this), duration + 50);
+      setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          // Clean up any remaining transitionend listeners
+          for (const { el, onEnd } of listeners) {
+            el.removeEventListener('transitionend', onEnd);
+            el.style.transition = '';
+          }
+          resolve(this);
+        }
+      }, duration + 50);
     });
   }
 
@@ -635,7 +684,8 @@ export class ZQueryCollection {
 
   fadeToggle(duration = 300) {
     return Promise.all(this.elements.map(el => {
-      const visible = getComputedStyle(el).opacity !== '0' && getComputedStyle(el).display !== 'none';
+      const cs = getComputedStyle(el);
+      const visible = cs.opacity !== '0' && cs.display !== 'none';
       const col = new ZQueryCollection([el]);
       return visible ? col.fadeOut(duration) : col.fadeIn(duration);
     })).then(() => this);
@@ -813,6 +863,8 @@ query.children = (parentId) => {
   const p = document.getElementById(parentId);
   return new ZQueryCollection(p ? Array.from(p.children) : []);
 };
+query.qs  = (sel, ctx = document) => ctx.querySelector(sel);
+query.qsa = (sel, ctx = document) => Array.from(ctx.querySelectorAll(sel));
 
 // Create element shorthand — returns ZQueryCollection for chaining
 query.create = (tag, attrs = {}, ...children) => {
@@ -820,7 +872,7 @@ query.create = (tag, attrs = {}, ...children) => {
   for (const [k, v] of Object.entries(attrs)) {
     if (k === 'class') el.className = v;
     else if (k === 'style' && typeof v === 'object') Object.assign(el.style, v);
-    else if (k.startsWith('on') && typeof v === 'function') el.addEventListener(k.slice(2), v);
+    else if (k.startsWith('on') && typeof v === 'function') el.addEventListener(k.slice(2).toLowerCase(), v);
     else if (k === 'data' && typeof v === 'object') Object.entries(v).forEach(([dk, dv]) => { el.dataset[dk] = dv; });
     else el.setAttribute(k, v);
   }

package/src/diff.js

@@ -239,8 +239,11 @@ function _morphChildrenKeyed(oldParent, oldChildren, newChildren, oldKeyMap, new
       if (!lisSet.has(i)) {
         oldParent.insertBefore(oldNode, cursor);
       }
+      // Capture next sibling BEFORE _morphNode — if _morphNode calls
+      // replaceChild, oldNode is removed and nextSibling becomes stale.
+      const nextSib = oldNode.nextSibling;
       _morphNode(oldParent, oldNode, newNode);
-      cursor = oldNode.nextSibling;
+      cursor = nextSib;
     } else {
       // Insert new node
       const clone = newNode.cloneNode(true);
@@ -418,10 +421,13 @@ function _morphAttributes(oldEl, newEl) {
     }
   }
 
-  // Remove stale attributes
-  for (let i = oldLen - 1; i >= 0; i--) {
-    if (!newNames.has(oldAttrs[i].name)) {
-      oldEl.removeAttribute(oldAttrs[i].name);
+  // Remove stale attributes — snapshot names first because oldAttrs
+  // is a live NamedNodeMap that mutates on removeAttribute().
+  const oldNames = new Array(oldLen);
+  for (let i = 0; i < oldLen; i++) oldNames[i] = oldAttrs[i].name;
+  for (let i = oldNames.length - 1; i >= 0; i--) {
+    if (!newNames.has(oldNames[i])) {
+      oldEl.removeAttribute(oldNames[i]);
     }
   }
 }