@bquery/bquery 1.0.2 → 1.1.0

package/dist/core.es.mjs

@@ -1,15 +1,15 @@
-import { sanitize as u } from "./security.es.mjs";
-const a = (r) => Array.isArray(r) ? r : [r], s = (r, e) => {
+import { sanitize as f } from "./security.es.mjs";
+const p = (r) => Array.isArray(r) ? r : [r], o = (r, e) => {
   for (const t of r)
     e(t);
 };
-class o {
+class a {
   /**
    * Creates a new BQueryElement wrapper.
    * @param element - The DOM element to wrap
    */
   constructor(e) {
-    this.element = e;
+    this.element = e, this.delegatedHandlers = /* @__PURE__ */ new Map();
   }
   /**
    * Exposes the raw DOM element when direct access is needed.
@@ -47,7 +47,7 @@ class o {
   }
   /** Read or write data attributes in camelCase. */
   data(e, t) {
-    const n = e.replace(/[A-Z]/g, (i) => `-${i.toLowerCase()}`);
+    const n = e.replace(/[A-Z]/g, (s) => `-${s.toLowerCase()}`);
     return t === void 0 ? this.element.getAttribute(`data-${n}`) ?? "" : (this.element.setAttribute(`data-${n}`, t), this);
   }
   /** Get or set text content. */
@@ -68,7 +68,7 @@ class o {
    * ```
    */
   html(e) {
-    return this.element.innerHTML = u(e), this;
+    return this.element.innerHTML = f(e), this;
   }
   /**
    * Sets HTML content without sanitization.
@@ -101,8 +101,8 @@ class o {
   css(e, t) {
     if (typeof e == "string")
       return t !== void 0 && this.element.style.setProperty(e, t), this;
-    for (const [n, i] of Object.entries(e))
-      this.element.style.setProperty(n, i);
+    for (const [n, s] of Object.entries(e))
+      this.element.style.setProperty(n, s);
     return this;
   }
   /**
@@ -141,6 +141,74 @@ class o {
   after(e) {
     return this.insertContent(e, "afterend"), this;
   }
+  /**
+   * Wraps the element with the specified wrapper element or tag.
+   *
+   * @param wrapper - Tag name string or Element to wrap with
+   * @returns The instance for method chaining
+   *
+   * @example
+   * ```ts
+   * $('#content').wrap('div'); // Wraps with <div>
+   * $('#content').wrap(document.createElement('section'));
+   * ```
+   */
+  wrap(e) {
+    const t = typeof e == "string" ? document.createElement(e) : e;
+    return this.element.parentNode?.insertBefore(t, this.element), t.appendChild(this.element), this;
+  }
+  /**
+   * Removes the parent element, keeping this element in its place.
+   * Essentially the opposite of wrap().
+   *
+   * @returns The instance for method chaining
+   *
+   * @example
+   * ```ts
+   * // Before: <div><span id="text">Hello</span></div>
+   * $('#text').unwrap();
+   * // After: <span id="text">Hello</span>
+   * ```
+   */
+  unwrap() {
+    const e = this.element.parentElement;
+    return e && e.parentNode && (e.parentNode.insertBefore(this.element, e), e.remove()), this;
+  }
+  /**
+   * Replaces this element with new content.
+   *
+   * @param content - HTML string (sanitized) or Element to replace with
+   * @returns A new BQueryElement wrapping the replacement element
+   *
+   * @example
+   * ```ts
+   * const newEl = $('#old').replaceWith('<div id="new">Replaced</div>');
+   * ```
+   */
+  replaceWith(e) {
+    let t;
+    if (typeof e == "string") {
+      const n = document.createElement("template");
+      n.innerHTML = f(e), t = n.content.firstElementChild ?? document.createElement("div");
+    } else
+      t = e;
+    return this.element.replaceWith(t), new a(t);
+  }
+  /**
+   * Scrolls the element into view with configurable behavior.
+   *
+   * @param options - ScrollIntoView options or boolean for legacy behavior
+   * @returns The instance for method chaining
+   *
+   * @example
+   * ```ts
+   * $('#section').scrollTo(); // Smooth scroll
+   * $('#section').scrollTo({ behavior: 'instant', block: 'start' });
+   * ```
+   */
+  scrollTo(e = { behavior: "smooth" }) {
+    return this.element.scrollIntoView(e), this;
+  }
   /**
    * Removes the element from the DOM.
    *
@@ -164,7 +232,7 @@ class o {
    * @returns A new BQueryElement wrapping the cloned element
    */
   clone(e = !0) {
-    return new o(this.element.cloneNode(e));
+    return new a(this.element.cloneNode(e));
   }
   /**
    * Finds all descendant elements matching the selector.
@@ -274,6 +342,59 @@ class o {
   trigger(e, t) {
     return this.element.dispatchEvent(new CustomEvent(e, { detail: t, bubbles: !0, cancelable: !0 })), this;
   }
+  /**
+   * Adds a delegated event listener that only triggers for matching descendants.
+   * More efficient than adding listeners to many elements individually.
+   *
+   * Use `undelegate()` to remove the listener later.
+   *
+   * @param event - Event type to listen for
+   * @param selector - CSS selector to match against event targets
+   * @param handler - Event handler function, receives the matched element as context
+   * @returns The instance for method chaining
+   *
+   * @example
+   * ```ts
+   * // Instead of adding listeners to each button:
+   * const handler = (e, target) => console.log('Clicked:', target.textContent);
+   * $('#list').delegate('click', '.item', handler);
+   *
+   * // Later, remove the delegated listener:
+   * $('#list').undelegate('click', '.item', handler);
+   * ```
+   */
+  delegate(e, t, n) {
+    const s = `${e}:${t}`, i = (l) => {
+      const h = l.target.closest(t);
+      h && this.element.contains(h) && n(l, h);
+    };
+    return this.delegatedHandlers.has(s) || this.delegatedHandlers.set(s, /* @__PURE__ */ new Map()), this.delegatedHandlers.get(s).set(n, i), this.element.addEventListener(e, i), this;
+  }
+  /**
+   * Removes a delegated event listener previously added with `delegate()`.
+   *
+   * @param event - Event type that was registered
+   * @param selector - CSS selector that was used
+   * @param handler - The original handler function passed to delegate()
+   * @returns The instance for method chaining
+   *
+   * @example
+   * ```ts
+   * const handler = (e, target) => console.log('Clicked:', target.textContent);
+   * $('#list').delegate('click', '.item', handler);
+   *
+   * // Remove the delegated listener:
+   * $('#list').undelegate('click', '.item', handler);
+   * ```
+   */
+  undelegate(e, t, n) {
+    const s = `${e}:${t}`, i = this.delegatedHandlers.get(s);
+    if (i) {
+      const l = i.get(n);
+      l && (this.element.removeEventListener(e, l), i.delete(n), i.size === 0 && this.delegatedHandlers.delete(s));
+    }
+    return this;
+  }
   /**
    * Checks if the element matches a CSS selector.
    *
@@ -345,6 +466,53 @@ class o {
     const t = this.element;
     return e === void 0 ? t.value ?? "" : (t.value = e, this);
   }
+  /**
+   * Serializes form data to a plain object.
+   * Only works on form elements; returns empty object for non-forms.
+   *
+   * @returns Object with form field names as keys and values
+   *
+   * @example
+   * ```ts
+   * // For a form with <input name="email" value="test@example.com">
+   * const data = $('#myForm').serialize();
+   * // { email: 'test@example.com' }
+   * ```
+   */
+  serialize() {
+    const e = this.element;
+    if (e.tagName.toLowerCase() !== "form")
+      return {};
+    const t = {}, n = new FormData(e);
+    for (const [s, i] of n.entries())
+      if (typeof i == "string")
+        if (s in t) {
+          const l = t[s];
+          Array.isArray(l) ? l.push(i) : t[s] = [l, i];
+        } else
+          t[s] = i;
+    return t;
+  }
+  /**
+   * Serializes form data to a URL-encoded query string.
+   *
+   * @returns URL-encoded string suitable for form submission
+   *
+   * @example
+   * ```ts
+   * const queryString = $('#myForm').serializeString();
+   * // 'email=test%40example.com&name=John'
+   * ```
+   */
+  serializeString() {
+    const e = this.element;
+    if (e.tagName.toLowerCase() !== "form")
+      return "";
+    const t = new FormData(e), n = new URLSearchParams();
+    for (const [s, i] of t.entries())
+      typeof i == "string" && n.append(s, i);
+    return n.toString();
+  }
   /**
    * Gets the bounding client rectangle of the element.
    *
@@ -373,22 +541,22 @@ class o {
    */
   insertContent(e, t) {
     if (typeof e == "string") {
-      this.element.insertAdjacentHTML(t, u(e));
+      this.element.insertAdjacentHTML(t, f(e));
       return;
     }
-    const n = a(e);
-    s(n, (i) => {
-      this.element.insertAdjacentElement(t, i);
+    const n = p(e);
+    o(n, (s) => {
+      this.element.insertAdjacentElement(t, s);
     });
   }
 }
-class l {
+class m {
   /**
    * Creates a new collection wrapper.
    * @param elements - Array of DOM elements to wrap
    */
   constructor(e) {
-    this.elements = e;
+    this.elements = e, this.delegatedHandlers = /* @__PURE__ */ new WeakMap();
   }
   /**
    * Gets the number of elements in the collection.
@@ -411,7 +579,7 @@ class l {
    */
   eq(e) {
     const t = this.elements[e];
-    return t ? new o(t) : void 0;
+    return t ? new a(t) : void 0;
   }
   /**
    * Gets the first element as a BQueryElement wrapper.
@@ -437,7 +605,7 @@ class l {
    */
   each(e) {
     return this.elements.forEach((t, n) => {
-      e(new o(t), n);
+      e(new a(t), n);
     }), this;
   }
   /**
@@ -456,7 +624,7 @@ class l {
    * @returns New BQueryCollection with matching elements
    */
   filter(e) {
-    return new l(this.elements.filter(e));
+    return new m(this.elements.filter(e));
   }
   /**
    * Reduces the collection to a single value.
@@ -474,19 +642,19 @@ class l {
    * @returns Array of BQueryElement instances
    */
   toArray() {
-    return this.elements.map((e) => new o(e));
+    return this.elements.map((e) => new a(e));
   }
   /** Add one or more classes to all elements. */
   addClass(...e) {
-    return s(this.elements, (t) => t.classList.add(...e)), this;
+    return o(this.elements, (t) => t.classList.add(...e)), this;
   }
   /** Remove one or more classes from all elements. */
   removeClass(...e) {
-    return s(this.elements, (t) => t.classList.remove(...e)), this;
+    return o(this.elements, (t) => t.classList.remove(...e)), this;
   }
   /** Toggle a class on all elements. */
   toggleClass(e, t) {
-    return s(this.elements, (n) => n.classList.toggle(e, t)), this;
+    return o(this.elements, (n) => n.classList.toggle(e, t)), this;
   }
   /**
    * Sets an attribute on all elements or gets from first.
@@ -496,7 +664,7 @@ class l {
    * @returns Attribute value when getting, instance when setting
    */
   attr(e, t) {
-    return t === void 0 ? this.first()?.getAttribute(e) ?? "" : (s(this.elements, (n) => n.setAttribute(e, t)), this);
+    return t === void 0 ? this.first()?.getAttribute(e) ?? "" : (o(this.elements, (n) => n.setAttribute(e, t)), this);
   }
   /**
    * Removes an attribute from all elements.
@@ -505,7 +673,7 @@ class l {
    * @returns The instance for method chaining
    */
   removeAttr(e) {
-    return s(this.elements, (t) => t.removeAttribute(e)), this;
+    return o(this.elements, (t) => t.removeAttribute(e)), this;
   }
   /**
    * Sets text content on all elements or gets from first.
@@ -514,7 +682,7 @@ class l {
    * @returns Text content when getting, instance when setting
    */
   text(e) {
-    return e === void 0 ? this.first()?.textContent ?? "" : (s(this.elements, (t) => {
+    return e === void 0 ? this.first()?.textContent ?? "" : (o(this.elements, (t) => {
       t.textContent = e;
     }), this);
   }
@@ -527,8 +695,8 @@ class l {
   html(e) {
     if (e === void 0)
       return this.first()?.innerHTML ?? "";
-    const t = u(e);
-    return s(this.elements, (n) => {
+    const t = f(e);
+    return o(this.elements, (n) => {
       n.innerHTML = t;
     }), this;
   }
@@ -540,7 +708,7 @@ class l {
    * @warning Bypasses XSS protection
    */
   htmlUnsafe(e) {
-    return s(this.elements, (t) => {
+    return o(this.elements, (t) => {
       t.innerHTML = e;
     }), this;
   }
@@ -552,11 +720,11 @@ class l {
    * @returns The instance for method chaining
    */
   css(e, t) {
-    return typeof e == "string" ? (t !== void 0 && s(this.elements, (n) => {
+    return typeof e == "string" ? (t !== void 0 && o(this.elements, (n) => {
       n.style.setProperty(e, t);
-    }), this) : (s(this.elements, (n) => {
-      for (const [i, m] of Object.entries(e))
-        n.style.setProperty(i, m);
+    }), this) : (o(this.elements, (n) => {
+      for (const [s, i] of Object.entries(e))
+        n.style.setProperty(s, i);
     }), this);
   }
   /**
@@ -566,7 +734,7 @@ class l {
    * @returns The instance for method chaining
    */
   show(e = "") {
-    return s(this.elements, (t) => {
+    return o(this.elements, (t) => {
       t.removeAttribute("hidden"), t.style.display = e;
     }), this;
   }
@@ -576,7 +744,7 @@ class l {
    * @returns The instance for method chaining
    */
   hide() {
-    return s(this.elements, (e) => {
+    return o(this.elements, (e) => {
       e.style.display = "none";
     }), this;
   }
@@ -588,7 +756,7 @@ class l {
    * @returns The instance for method chaining
    */
   on(e, t) {
-    return s(this.elements, (n) => n.addEventListener(e, t)), this;
+    return o(this.elements, (n) => n.addEventListener(e, t)), this;
   }
   /**
    * Adds a one-time event listener to all elements.
@@ -598,7 +766,7 @@ class l {
    * @returns The instance for method chaining
    */
   once(e, t) {
-    return s(this.elements, (n) => n.addEventListener(e, t, { once: !0 })), this;
+    return o(this.elements, (n) => n.addEventListener(e, t, { once: !0 })), this;
   }
   /**
    * Removes an event listener from all elements.
@@ -608,7 +776,7 @@ class l {
    * @returns The instance for method chaining
    */
   off(e, t) {
-    return s(this.elements, (n) => n.removeEventListener(e, t)), this;
+    return o(this.elements, (n) => n.removeEventListener(e, t)), this;
   }
   /**
    * Triggers a custom event on all elements.
@@ -618,17 +786,77 @@ class l {
    * @returns The instance for method chaining
    */
   trigger(e, t) {
-    return s(this.elements, (n) => {
+    return o(this.elements, (n) => {
       n.dispatchEvent(new CustomEvent(e, { detail: t, bubbles: !0, cancelable: !0 }));
     }), this;
   }
+  /**
+   * Adds a delegated event listener to all elements.
+   * Events are delegated to matching descendants.
+   *
+   * Use `undelegate()` to remove the listener later.
+   *
+   * @param event - Event type to listen for
+   * @param selector - CSS selector to match against event targets
+   * @param handler - Event handler function
+   * @returns The instance for method chaining
+   *
+   * @example
+   * ```ts
+   * const handler = (e, target) => console.log('Clicked:', target.textContent);
+   * $$('.container').delegate('click', '.item', handler);
+   *
+   * // Later, remove the delegated listener:
+   * $$('.container').undelegate('click', '.item', handler);
+   * ```
+   */
+  delegate(e, t, n) {
+    const s = `${e}:${t}`;
+    return o(this.elements, (i) => {
+      const l = (u) => {
+        const d = u.target.closest(t);
+        d && i.contains(d) && n(u, d);
+      };
+      this.delegatedHandlers.has(i) || this.delegatedHandlers.set(i, /* @__PURE__ */ new Map());
+      const h = this.delegatedHandlers.get(i);
+      h.has(s) || h.set(s, /* @__PURE__ */ new Map()), h.get(s).set(n, l), i.addEventListener(e, l);
+    }), this;
+  }
+  /**
+   * Removes a delegated event listener previously added with `delegate()`.
+   *
+   * @param event - Event type that was registered
+   * @param selector - CSS selector that was used
+   * @param handler - The original handler function passed to delegate()
+   * @returns The instance for method chaining
+   *
+   * @example
+   * ```ts
+   * const handler = (e, target) => console.log('Clicked:', target.textContent);
+   * $$('.container').delegate('click', '.item', handler);
+   *
+   * // Remove the delegated listener:
+   * $$('.container').undelegate('click', '.item', handler);
+   * ```
+   */
+  undelegate(e, t, n) {
+    const s = `${e}:${t}`;
+    return o(this.elements, (i) => {
+      const l = this.delegatedHandlers.get(i);
+      if (!l) return;
+      const h = l.get(s);
+      if (!h) return;
+      const u = h.get(n);
+      u && (i.removeEventListener(e, u), h.delete(n), h.size === 0 && l.delete(s), l.size === 0 && this.delegatedHandlers.delete(i));
+    }), this;
+  }
   /**
    * Removes all elements from the DOM.
    *
    * @returns The instance for method chaining
    */
   remove() {
-    return s(this.elements, (e) => e.remove()), this;
+    return o(this.elements, (e) => e.remove()), this;
   }
   /**
    * Clears all child nodes from all elements.
@@ -636,19 +864,19 @@ class l {
    * @returns The instance for method chaining
    */
   empty() {
-    return s(this.elements, (e) => {
+    return o(this.elements, (e) => {
       e.innerHTML = "";
     }), this;
   }
 }
-const f = (r) => {
+const y = (r) => {
   if (typeof r != "string")
-    return new o(r);
+    return new a(r);
   const e = document.querySelector(r);
   if (!e)
     throw new Error(`bQuery: element not found for selector "${r}"`);
-  return new o(e);
-}, d = (r) => Array.isArray(r) ? new l(r) : r instanceof NodeList ? new l(Array.from(r)) : new l(Array.from(document.querySelectorAll(r))), h = {
+  return new a(e);
+}, b = (r) => Array.isArray(r) ? new m(r) : r instanceof NodeList ? new m(Array.from(r)) : new m(Array.from(document.querySelectorAll(r))), c = {
   /**
    * Creates a deep clone using structuredClone if available, otherwise fallback to JSON.
    *
@@ -684,17 +912,32 @@ const f = (r) => {
    * );
    * // Result: { a: 1, b: 2, nested: { x: 1, y: 2 } }
    * ```
+   *
+   * @security This method is protected against prototype pollution attacks.
+   * Keys like `__proto__`, `constructor`, and `prototype` are ignored.
    */
   merge(...r) {
     const e = {};
     for (const t of r)
-      for (const [n, i] of Object.entries(t))
-        h.isPlainObject(i) && h.isPlainObject(e[n]) ? e[n] = h.merge(
+      for (const [n, s] of Object.entries(t))
+        c.isPrototypePollutionKey(n) || (c.isPlainObject(s) && c.isPlainObject(e[n]) ? e[n] = c.merge(
           e[n],
-          i
-        ) : e[n] = i;
+          s
+        ) : e[n] = s);
     return e;
   },
+  /**
+   * Checks if a key could cause prototype pollution.
+   * These keys are dangerous when used in object merging operations.
+   *
+   * @param key - The key to check
+   * @returns True if the key is a prototype pollution vector
+   *
+   * @internal
+   */
+  isPrototypePollutionKey(r) {
+    return r === "__proto__" || r === "constructor" || r === "prototype";
+  },
   /**
    * Creates a debounced function that delays execution until after
    * the specified delay has elapsed since the last call.
@@ -741,8 +984,8 @@ const f = (r) => {
   throttle(r, e) {
     let t = 0;
     return (...n) => {
-      const i = Date.now();
-      i - t >= e && (t = i, r(...n));
+      const s = Date.now();
+      s - t >= e && (t = s, r(...n));
     };
   },
   /**
@@ -1006,10 +1249,10 @@ const f = (r) => {
   }
 };
 export {
-  f as $,
-  d as $$,
-  l as BQueryCollection,
-  o as BQueryElement,
-  h as utils
+  y as $,
+  b as $$,
+  m as BQueryCollection,
+  a as BQueryElement,
+  c as utils
 };
 //# sourceMappingURL=core.es.mjs.map