@bquery/bquery 1.2.0 → 1.4.0

package/src/core/collection.ts

@@ -1,6 +1,11 @@
-import { sanitizeHtml } from '../security/sanitize';
+import {
+  createElementFromHtml,
+  insertContent,
+  sanitizeContent,
+  type InsertableContent,
+} from './dom';
 import { BQueryElement } from './element';
-import { applyAll } from './shared';
+import { applyAll, toElementList } from './shared';
 
 /** Handler signature for delegated events */
 type DelegatedHandler = (event: Event, target: Element) => void;
@@ -181,6 +186,20 @@ export class BQueryCollection {
     return this;
   }
 
+  /** Toggle an attribute on all elements. */
+  toggleAttr(name: string, force?: boolean): this {
+    applyAll(this.elements, (el) => {
+      const hasAttr = el.hasAttribute(name);
+      const shouldAdd = force ?? !hasAttr;
+      if (shouldAdd) {
+        el.setAttribute(name, '');
+      } else {
+        el.removeAttribute(name);
+      }
+    });
+    return this;
+  }
+
   /**
    * Sets text content on all elements or gets from first.
    *
@@ -207,7 +226,7 @@ export class BQueryCollection {
     if (value === undefined) {
       return this.first()?.innerHTML ?? '';
     }
-    const sanitized = sanitizeHtml(value);
+    const sanitized = sanitizeContent(value);
     applyAll(this.elements, (el) => {
       el.innerHTML = sanitized;
     });
@@ -228,21 +247,58 @@ export class BQueryCollection {
     return this;
   }
 
+  /** Append content to all elements. */
+  append(content: InsertableContent): this {
+    this.insertAll(content, 'beforeend');
+    return this;
+  }
+
+  /** Prepend content to all elements. */
+  prepend(content: InsertableContent): this {
+    this.insertAll(content, 'afterbegin');
+    return this;
+  }
+
+  /** Insert content before all elements. */
+  before(content: InsertableContent): this {
+    this.insertAll(content, 'beforebegin');
+    return this;
+  }
+
+  /** Insert content after all elements. */
+  after(content: InsertableContent): this {
+    this.insertAll(content, 'afterend');
+    return this;
+  }
+
   /**
-   * Applies CSS styles to all elements.
+   * Gets or sets CSS styles on all elements.
+   * When getting, returns the computed style value from the first element.
    *
    * @param property - Property name or object of properties
    * @param value - Value when setting single property
-   * @returns The instance for method chaining
+   * @returns The computed style value when getting, instance when setting
    */
-  css(property: string | Record<string, string>, value?: string): this {
+  css(property: string): string;
+  css(property: string, value: string): this;
+  css(property: Record<string, string>): this;
+  css(property: string | Record<string, string>, value?: string): string | this {
     if (typeof property === 'string') {
       if (value !== undefined) {
         applyAll(this.elements, (el) => {
           (el as HTMLElement).style.setProperty(property, value);
         });
+        return this;
+      }
+      const first = this.first();
+      if (!first) {
+        return '';
       }
-      return this;
+      const view = first.ownerDocument?.defaultView;
+      if (!view || typeof view.getComputedStyle !== 'function') {
+        return '';
+      }
+      return view.getComputedStyle(first).getPropertyValue(property);
     }
 
     applyAll(this.elements, (el) => {
@@ -253,6 +309,78 @@ export class BQueryCollection {
     return this;
   }
 
+  /** Wrap each element with a wrapper element or tag. */
+  wrap(wrapper: string | Element): this {
+    this.elements.forEach((el, index) => {
+      const wrapperEl =
+        typeof wrapper === 'string'
+          ? document.createElement(wrapper)
+          : index === 0
+            ? wrapper
+            : (wrapper.cloneNode(true) as Element);
+      el.parentNode?.insertBefore(wrapperEl, el);
+      wrapperEl.appendChild(el);
+    });
+    return this;
+  }
+
+  /**
+   * Remove the parent element of each element, keeping the elements in place.
+   *
+   * **Important**: This method unwraps ALL children of each parent element,
+   * not just the elements in the collection. If you call `unwrap()` on a
+   * collection containing only some children of a parent, all siblings will
+   * also be unwrapped. This behavior is consistent with jQuery's `.unwrap()`.
+   *
+   * @returns The collection for chaining
+   *
+   * @example
+   * ```ts
+   * // HTML: <div><section><span>A</span><span>B</span></section></div>
+   * const spans = $$('span');
+   * spans.unwrap(); // Removes <section>, both spans move to <div>
+   * // Result: <div><span>A</span><span>B</span></div>
+   * ```
+   */
+  unwrap(): this {
+    // Collect unique parent elements to avoid removing the same parent multiple times.
+    const parents = new Set<Element>();
+    for (const el of this.elements) {
+      if (el.parentElement) {
+        parents.add(el.parentElement);
+      }
+    }
+
+    // Unwrap each parent once: move all children out, then remove the wrapper.
+    parents.forEach((parent) => {
+      const grandParent = parent.parentNode;
+      if (!grandParent) return;
+
+      while (parent.firstChild) {
+        grandParent.insertBefore(parent.firstChild, parent);
+      }
+
+      parent.remove();
+    });
+    return this;
+  }
+
+  /** Replace each element with provided content. */
+  replaceWith(content: string | Element): BQueryCollection {
+    const replacements: Element[] = [];
+    this.elements.forEach((el, index) => {
+      const replacement =
+        typeof content === 'string'
+          ? createElementFromHtml(content)
+          : index === 0
+            ? content
+            : (content.cloneNode(true) as Element);
+      el.replaceWith(replacement);
+      replacements.push(replacement);
+    });
+    return new BQueryCollection(replacements);
+  }
+
   /**
    * Shows all elements.
    *
@@ -430,6 +558,33 @@ export class BQueryCollection {
     return this;
   }
 
+  /**
+   * Finds all descendant elements matching the selector across all elements
+   * in the collection. Returns a new BQueryCollection with the results.
+   *
+   * @param selector - CSS selector to match
+   * @returns A new BQueryCollection with all matching descendants
+   *
+   * @example
+   * ```ts
+   * $$('.container').find('.item').addClass('highlight');
+   * ```
+   */
+  find(selector: string): BQueryCollection {
+    const seen = new Set<Element>();
+    const results: Element[] = [];
+    for (const el of this.elements) {
+      const found = el.querySelectorAll(selector);
+      for (let i = 0; i < found.length; i++) {
+        if (!seen.has(found[i])) {
+          seen.add(found[i]);
+          results.push(found[i]);
+        }
+      }
+    }
+    return new BQueryCollection(results);
+  }
+
   /**
    * Removes all elements from the DOM.
    *
@@ -451,4 +606,23 @@ export class BQueryCollection {
     });
     return this;
   }
+
+  /** @internal */
+  private insertAll(content: InsertableContent, position: InsertPosition): void {
+    if (typeof content === 'string') {
+      // Sanitize once and reuse for all elements
+      const sanitized = sanitizeContent(content);
+      applyAll(this.elements, (el) => {
+        el.insertAdjacentHTML(position, sanitized);
+      });
+      return;
+    }
+
+    const elements = toElementList(content);
+    this.elements.forEach((el, index) => {
+      const nodes =
+        index === 0 ? elements : elements.map((node) => node.cloneNode(true) as Element);
+      insertContent(el, nodes, position);
+    });
+  }
 }

package/src/core/dom.ts

@@ -0,0 +1,38 @@
+import { sanitizeHtml } from '../security/sanitize';
+import { applyAll, toElementList } from './shared';
+
+export type InsertableContent = string | Element | Element[];
+
+export const sanitizeContent = (html: string): string => sanitizeHtml(html);
+
+export const setHtml = (element: Element, html: string): void => {
+  element.innerHTML = sanitizeHtml(html);
+};
+
+export const createElementFromHtml = (html: string): Element => {
+  const template = document.createElement('template');
+  template.innerHTML = sanitizeHtml(html);
+  return template.content.firstElementChild ?? document.createElement('div');
+};
+
+export const insertContent = (
+  target: Element,
+  content: InsertableContent,
+  position: InsertPosition
+): void => {
+  if (typeof content === 'string') {
+    target.insertAdjacentHTML(position, sanitizeHtml(content));
+    return;
+  }
+
+  const elements = toElementList(content);
+
+  // For positions that insert at the beginning (afterbegin, afterend), reverse
+  // the array to maintain the caller's order. For beforeend/beforebegin, keep order.
+  const needsReverse = position === 'afterbegin' || position === 'afterend';
+  const orderedElements = needsReverse ? elements.slice().reverse() : elements;
+
+  applyAll(orderedElements, (el) => {
+    target.insertAdjacentElement(position, el);
+  });
+};

package/src/core/element.ts

@@ -1,5 +1,4 @@
-import { sanitizeHtml } from '../security/sanitize';
-import { applyAll, toElementList } from './shared';
+import { createElementFromHtml, insertContent, setHtml } from './dom';
 
 /**
  * Wrapper for a single DOM element.
@@ -83,6 +82,24 @@ export class BQueryElement {
     return this;
   }
 
+  /** Remove an attribute. */
+  removeAttr(name: string): this {
+    this.element.removeAttribute(name);
+    return this;
+  }
+
+  /** Toggle an attribute on/off. */
+  toggleAttr(name: string, force?: boolean): this {
+    const hasAttr = this.element.hasAttribute(name);
+    const shouldAdd = force ?? !hasAttr;
+    if (shouldAdd) {
+      this.element.setAttribute(name, '');
+    } else {
+      this.element.removeAttribute(name);
+    }
+    return this;
+  }
+
   /** Get or set a property. */
   prop<T extends keyof Element>(name: T, value?: Element[T]): Element[T] | this {
     if (value === undefined) {
@@ -125,7 +142,7 @@ export class BQueryElement {
    * ```
    */
   html(value: string): this {
-    this.element.innerHTML = sanitizeHtml(value);
+    setHtml(this.element, value);
     return this;
   }
 
@@ -148,23 +165,34 @@ export class BQueryElement {
    *
    * @param property - A CSS property name or an object of property-value pairs
    * @param value - The value when setting a single property
-   * @returns The instance for method chaining
+   * @returns The computed style value when getting a single property, or the instance for method chaining when setting
    *
    * @example
    * ```ts
-   * // Single property
+   * // Get a computed style value
+   * const color = $('#box').css('color');
+   *
+   * // Set a single property
    * $('#box').css('color', 'red');
    *
-   * // Multiple properties
+   * // Set multiple properties
    * $('#box').css({ color: 'red', 'font-size': '16px' });
    * ```
    */
-  css(property: string | Record<string, string>, value?: string): this {
+  css(property: string): string;
+  css(property: string, value: string): this;
+  css(property: Record<string, string>): this;
+  css(property: string | Record<string, string>, value?: string): string | this {
     if (typeof property === 'string') {
       if (value !== undefined) {
         (this.element as HTMLElement).style.setProperty(property, value);
+        return this;
+      }
+      const view = this.element.ownerDocument?.defaultView;
+      if (!view || typeof view.getComputedStyle !== 'function') {
+        return '';
       }
-      return this;
+      return view.getComputedStyle(this.element).getPropertyValue(property);
     }
 
     for (const [key, val] of Object.entries(property)) {
@@ -240,6 +268,10 @@ export class BQueryElement {
    * Removes the parent element, keeping this element in its place.
    * Essentially the opposite of wrap().
    *
+   * **Important**: This method only moves the current element out of its parent
+   * before removing the parent. Any sibling elements will be removed along with
+   * the parent. For unwrapping multiple siblings, use a collection: `$$(siblings).unwrap()`.
+   *
    * @returns The instance for method chaining
    *
    * @example
@@ -270,14 +302,7 @@ export class BQueryElement {
    * ```
    */
   replaceWith(content: string | Element): BQueryElement {
-    let newEl: Element;
-    if (typeof content === 'string') {
-      const template = document.createElement('template');
-      template.innerHTML = sanitizeHtml(content);
-      newEl = template.content.firstElementChild ?? document.createElement('div');
-    } else {
-      newEl = content;
-    }
+    const newEl = typeof content === 'string' ? createElementFromHtml(content) : content;
     this.element.replaceWith(newEl);
     return new BQueryElement(newEl);
   }
@@ -549,6 +574,23 @@ export class BQueryElement {
     return this.element.matches(selector);
   }
 
+  /**
+   * Alias for `matches()`. Checks if the element matches a CSS selector.
+   *
+   * @param selector - CSS selector to match against
+   * @returns True if the element matches the selector
+   *
+   * @example
+   * ```ts
+   * if ($('#el').is('.active')) {
+   *   console.log('Element is active');
+   * }
+   * ```
+   */
+  is(selector: string): boolean {
+    return this.matches(selector);
+  }
+
   /**
    * Checks if the element has a specific class.
    *
@@ -727,14 +769,6 @@ export class BQueryElement {
    * @internal
    */
   private insertContent(content: string | Element | Element[], position: InsertPosition) {
-    if (typeof content === 'string') {
-      this.element.insertAdjacentHTML(position, sanitizeHtml(content));
-      return;
-    }
-
-    const elements = toElementList(content);
-    applyAll(elements, (el) => {
-      this.element.insertAdjacentElement(position, el);
-    });
+    insertContent(this.element, content, position);
   }
 }

package/src/core/index.ts

@@ -1,4 +1,48 @@
-export { BQueryCollection } from './collection';
-export { BQueryElement } from './element';
-export { $, $$ } from './selector';
-export { utils } from './utils';
+export { BQueryCollection } from './collection';
+export { BQueryElement } from './element';
+export { $, $$ } from './selector';
+// Re-export the utils namespace for backward compatibility
+export { utils } from './utils';
+// Export individual utilities (except internal helpers)
+export {
+  chunk,
+  compact,
+  ensureArray,
+  flatten,
+  unique,
+  debounce,
+  noop,
+  once,
+  throttle,
+  isEmpty,
+  parseJson,
+  sleep,
+  uid,
+  clamp,
+  inRange,
+  randomInt,
+  toNumber,
+  clone,
+  hasOwn,
+  isPlainObject,
+  merge,
+  omit,
+  pick,
+  capitalize,
+  escapeRegExp,
+  slugify,
+  toCamelCase,
+  toKebabCase,
+  truncate,
+  isArray,
+  isBoolean,
+  isCollection,
+  isDate,
+  isElement,
+  isFunction,
+  isNumber,
+  isObject,
+  isPromise,
+  isString,
+} from './utils';
+export type { DebouncedFn, ThrottledFn } from './utils';

package/src/core/utils/array.ts

@@ -0,0 +1,102 @@
+/**
+ * Array-focused utility helpers.
+ *
+ * @module bquery/core/utils/array
+ */
+
+/**
+ * Ensures the input is always returned as an array.
+ *
+ * @template T - The item type
+ * @param value - A single value, array, or nullish value
+ * @returns An array (empty if nullish)
+ *
+ * @example
+ * ```ts
+ * ensureArray('a'); // ['a']
+ * ensureArray(['a', 'b']); // ['a', 'b']
+ * ensureArray(null); // []
+ * ```
+ */
+export function ensureArray<T>(value: T | T[] | null | undefined): T[] {
+  if (value == null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Removes duplicate entries from an array.
+ *
+ * @template T - The item type
+ * @param items - The array to deduplicate
+ * @returns A new array with unique items
+ *
+ * @example
+ * ```ts
+ * unique([1, 2, 2, 3]); // [1, 2, 3]
+ * ```
+ */
+export function unique<T>(items: T[]): T[] {
+  return Array.from(new Set(items));
+}
+
+/**
+ * Splits an array into chunks of a given size.
+ *
+ * @template T - The item type
+ * @param items - The array to chunk
+ * @param size - The maximum size of each chunk
+ * @returns An array of chunks
+ *
+ * @example
+ * ```ts
+ * chunk([1, 2, 3, 4, 5], 2); // [[1,2],[3,4],[5]]
+ * ```
+ */
+export function chunk<T>(items: T[], size: number): T[][] {
+  if (size <= 0) return [];
+  const result: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    result.push(items.slice(i, i + size));
+  }
+  return result;
+}
+
+/**
+ * Removes falsy values from an array.
+ *
+ * @template T - The item type
+ * @param items - The array to compact
+ * @returns A new array without falsy values
+ *
+ * @example
+ * ```ts
+ * compact([0, 1, '', 'ok', null]); // [1, 'ok']
+ * ```
+ */
+export function compact<T>(items: Array<T | null | undefined | false | 0 | ''>): T[] {
+  return items.filter(Boolean) as T[];
+}
+
+/**
+ * Flattens a single level of nested arrays.
+ *
+ * @template T - The item type
+ * @param items - The array to flatten
+ * @returns A new flattened array
+ *
+ * @example
+ * ```ts
+ * flatten([1, [2, 3], 4]); // [1, 2, 3, 4]
+ * ```
+ */
+export function flatten<T>(items: Array<T | T[]>): T[] {
+  const result: T[] = [];
+  for (const item of items) {
+    if (Array.isArray(item)) {
+      result.push(...item);
+    } else {
+      result.push(item);
+    }
+  }
+  return result;
+}