@bquery/bquery 1.6.0 → 1.8.1

package/src/core/collection.ts

@@ -5,7 +5,7 @@ import {
   type InsertableContent,
 } from './dom';
 import { BQueryElement } from './element';
-import { applyAll, toElementList } from './shared';
+import { applyAll, getInnerSize, getOuterSize, isHTMLElement, toElementList } from './shared';
 
 /** Handler signature for delegated events */
 type DelegatedHandler = (event: Event, target: Element) => void;
@@ -381,6 +381,103 @@ export class BQueryCollection {
     return new BQueryCollection(replacements);
   }
 
+  /**
+   * Removes all elements from the DOM while keeping the wrapped nodes available
+   * for later reuse.
+   *
+   * @returns The instance for method chaining
+   */
+  detach(): this {
+    return this.remove();
+  }
+
+  /**
+   * Gets the zero-based sibling index of the first element in the collection.
+   *
+   * @returns Index of the first element, or -1 when unavailable
+   */
+  index(): number {
+    const first = this.first();
+    if (!first?.parentElement) {
+      return -1;
+    }
+    return Array.from(first.parentElement.children).indexOf(first);
+  }
+
+  /**
+   * Returns the child nodes of the first element, including text nodes and comments.
+   *
+   * @returns Array of child nodes from the first element
+   */
+  contents(): ChildNode[] {
+    return Array.from(this.first()?.childNodes ?? []);
+  }
+
+  /**
+   * Gets the offset parent of the first element in the collection.
+   *
+   * @returns Offset parent element, or null when unavailable
+   */
+  offsetParent(): Element | null {
+    const first = this.first();
+    return isHTMLElement(first) ? first.offsetParent : null;
+  }
+
+  /**
+   * Gets the position of the first element relative to its offset parent.
+   *
+   * @returns Position object with top and left coordinates
+   */
+  position(): { top: number; left: number } {
+    const first = this.first();
+    if (!isHTMLElement(first)) {
+      return { top: 0, left: 0 };
+    }
+
+    return {
+      top: first.offsetTop,
+      left: first.offsetLeft,
+    };
+  }
+
+  /**
+   * Gets the inner width of the first element (content + padding, excluding border).
+   *
+   * @returns Inner width in pixels, or 0 when the collection is empty
+   */
+  innerWidth(): number {
+    return getInnerSize(this.first(), 'width');
+  }
+
+  /**
+   * Gets the inner height of the first element (content + padding, excluding border).
+   *
+   * @returns Inner height in pixels, or 0 when the collection is empty
+   */
+  innerHeight(): number {
+    return getInnerSize(this.first(), 'height');
+  }
+
+  /**
+   * Gets the outer width of the first element, optionally including margins.
+   *
+   * @param includeMargin - When true, include horizontal margins
+   * @returns Outer width in pixels
+   */
+  outerWidth(includeMargin: boolean = false): number {
+    return getOuterSize(this.first(), 'width', includeMargin);
+  }
+
+  /**
+   * Gets the outer height of the first element, optionally including margins.
+   *
+   * @param includeMargin - When true, include vertical margins
+   * @returns Outer height in pixels
+   */
+  outerHeight(includeMargin: boolean = false): number {
+    return getOuterSize(this.first(), 'height', includeMargin);
+  }
+
   /**
    * Shows all elements.
    *
@@ -585,6 +682,157 @@ export class BQueryCollection {
     return new BQueryCollection(results);
   }
 
+  /**
+   * Gets the closest element or ancestor matching a selector for each element in
+   * the collection, including the element itself. Duplicates are removed from the
+   * result.
+   *
+   * @param selector - CSS selector to match
+   * @returns A new BQueryCollection with matching elements or ancestors
+   *
+   * @example
+   * ```ts
+   * $$('.item').closest('.container');
+   * ```
+   */
+  closest(selector: string): BQueryCollection {
+    const seen = new Set<Element>();
+    const results: Element[] = [];
+    for (const el of this.elements) {
+      const match = el.closest(selector);
+      if (match && !seen.has(match)) {
+        seen.add(match);
+        results.push(match);
+      }
+    }
+    return new BQueryCollection(results);
+  }
+
+  /**
+   * Gets the parent element of each element in the collection.
+   * Duplicates are removed (e.g. siblings sharing a parent).
+   *
+   * @returns A new BQueryCollection with unique parent elements
+   *
+   * @example
+   * ```ts
+   * $$('.item').parent().addClass('has-items');
+   * ```
+   */
+  parent(): BQueryCollection {
+    const seen = new Set<Element>();
+    const results: Element[] = [];
+    for (const el of this.elements) {
+      const p = el.parentElement;
+      if (p && !seen.has(p)) {
+        seen.add(p);
+        results.push(p);
+      }
+    }
+    return new BQueryCollection(results);
+  }
+
+  /**
+   * Gets the direct children of every element in the collection.
+   * Duplicates are removed from the result.
+   *
+   * @returns A new BQueryCollection with child elements
+   *
+   * @example
+   * ```ts
+   * $$('.list').children().addClass('child');
+   * ```
+   */
+  children(): BQueryCollection {
+    const seen = new Set<Element>();
+    const results: Element[] = [];
+    for (const el of this.elements) {
+      for (const child of Array.from(el.children)) {
+        if (!seen.has(child)) {
+          seen.add(child);
+          results.push(child);
+        }
+      }
+    }
+    return new BQueryCollection(results);
+  }
+
+  /**
+   * Gets all siblings of every element in the collection (excluding the
+   * elements themselves). Duplicates are removed.
+   *
+   * @returns A new BQueryCollection with sibling elements
+   *
+   * @example
+   * ```ts
+   * $$('.active').siblings().removeClass('active');
+   * ```
+   */
+  siblings(): BQueryCollection {
+    const selfSet = new Set(this.elements);
+    const seen = new Set<Element>();
+    const results: Element[] = [];
+    for (const el of this.elements) {
+      const parent = el.parentElement;
+      if (!parent) continue;
+      for (const sibling of Array.from(parent.children)) {
+        if (!selfSet.has(sibling) && !seen.has(sibling)) {
+          seen.add(sibling);
+          results.push(sibling);
+        }
+      }
+    }
+    return new BQueryCollection(results);
+  }
+
+  /**
+   * Gets the next sibling element of each element in the collection.
+   * Elements without a next sibling are skipped.
+   *
+   * @returns A new BQueryCollection with next sibling elements
+   *
+   * @example
+   * ```ts
+   * $$('.current').next().addClass('upcoming');
+   * ```
+   */
+  next(): BQueryCollection {
+    const seen = new Set<Element>();
+    const results: Element[] = [];
+    for (const el of this.elements) {
+      const n = el.nextElementSibling;
+      if (n && !seen.has(n)) {
+        seen.add(n);
+        results.push(n);
+      }
+    }
+    return new BQueryCollection(results);
+  }
+
+  /**
+   * Gets the previous sibling element of each element in the collection.
+   * Elements without a previous sibling are skipped.
+   *
+   * @returns A new BQueryCollection with previous sibling elements
+   *
+   * @example
+   * ```ts
+   * $$('.current').prev().addClass('previous');
+   * ```
+   */
+  prev(): BQueryCollection {
+    const seen = new Set<Element>();
+    const results: Element[] = [];
+    for (const el of this.elements) {
+      const p = el.previousElementSibling;
+      if (p && !seen.has(p)) {
+        seen.add(p);
+        results.push(p);
+      }
+    }
+    return new BQueryCollection(results);
+  }
+
   /**
    * Removes all elements from the DOM.
    *

package/src/core/element.ts

@@ -1,4 +1,6 @@
 import { createElementFromHtml, insertContent, setHtml } from './dom';
+import { getInnerSize, getOuterSize, isHTMLElement } from './shared';
+import { isPrototypePollutionKey } from './utils/object';
 
 /**
  * Wrapper for a single DOM element.
@@ -25,6 +27,95 @@ import { createElementFromHtml, insertContent, setHtml } from './dom';
 /** Handler signature for delegated events */
 type DelegatedHandler = (event: Event, target: Element) => void;
 
+type SerializableFormControl = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+
+const isSerializableFormControl = (element: Element): element is SerializableFormControl => {
+  const tagName = element.tagName.toLowerCase();
+  return tagName === 'input' || tagName === 'textarea' || tagName === 'select';
+};
+
+const collectFormEntries = (form: HTMLFormElement): Array<[string, string]> => {
+  const entries: Array<[string, string]> = [];
+  const elementCtor = form.ownerDocument.defaultView?.Element ?? Element;
+
+  for (const control of Array.from(form.elements)) {
+    if (!(control instanceof elementCtor) || !isSerializableFormControl(control)) {
+      continue;
+    }
+
+    const name = control.name;
+    if (!name || control.disabled || isPrototypePollutionKey(name)) {
+      continue;
+    }
+
+    if (control.tagName.toLowerCase() === 'input') {
+      const input = control as HTMLInputElement;
+      const type = input.type.toLowerCase();
+
+      if (type === 'checkbox' || type === 'radio') {
+        if (input.checked) {
+          entries.push([name, input.value]);
+        }
+        continue;
+      }
+
+      if (
+        type === 'file' ||
+        type === 'submit' ||
+        type === 'button' ||
+        type === 'reset' ||
+        type === 'image'
+      ) {
+        continue;
+      }
+
+      entries.push([name, input.value]);
+      continue;
+    }
+
+    if (control.tagName.toLowerCase() === 'select') {
+      const select = control as HTMLSelectElement;
+
+      if (select.multiple) {
+        for (const option of Array.from(select.selectedOptions)) {
+          entries.push([name, option.value]);
+        }
+      } else {
+        entries.push([name, select.value]);
+      }
+      continue;
+    }
+
+    entries.push([name, (control as HTMLTextAreaElement).value]);
+  }
+
+  return entries;
+};
+
+const getFormEntries = (form: HTMLFormElement): Array<[string, string]> => {
+  if (typeof FormData === 'function') {
+    try {
+      const entries: Array<[string, string]> = [];
+
+      for (const [key, value] of new FormData(form).entries()) {
+        if (isPrototypePollutionKey(key) || typeof value !== 'string') {
+          continue;
+        }
+        entries.push([key, value]);
+      }
+
+      // Some environments expose FormData(form) but fail to populate entries for
+      // successful controls. Fall back to manual collection only in that zero-entry case.
+      return entries.length > 0 ? entries : collectFormEntries(form);
+    } catch {
+      // Fall back to manual collection when FormData is unavailable for this form
+      // or the environment does not fully support constructing it.
+    }
+  }
+
+  return collectFormEntries(form);
+};
+
 export class BQueryElement {
   /**
    * Stores delegated event handlers for cleanup via undelegate().
@@ -307,6 +398,156 @@ export class BQueryElement {
     return new BQueryElement(newEl);
   }
 
+  /**
+   * Removes the element from the DOM while keeping the wrapped node available
+   * for later reuse.
+   *
+   * @returns The instance for method chaining
+   *
+   * @example
+   * ```ts
+   * const item = $('#item').detach();
+   * document.body.appendChild(item.raw);
+   * ```
+   */
+  detach(): this {
+    return this.remove();
+  }
+
+  /**
+   * Gets the zero-based index of the element among its element siblings.
+   *
+   * @returns Index within the parent element, or -1 when detached
+   *
+   * @example
+   * ```ts
+   * const index = $('#item').index();
+   * ```
+   */
+  index(): number {
+    const parent = this.element.parentElement;
+    if (!parent) {
+      return -1;
+    }
+    return Array.from(parent.children).indexOf(this.element);
+  }
+
+  /**
+   * Returns all child nodes, including text nodes and comments.
+   *
+   * @returns Array of child nodes
+   *
+   * @example
+   * ```ts
+   * const nodes = $('#content').contents();
+   * ```
+   */
+  contents(): ChildNode[] {
+    return Array.from(this.element.childNodes);
+  }
+
+  /**
+   * Gets the nearest positioned ancestor used for offset calculations.
+   *
+   * @returns The offset parent element, or null when unavailable
+   *
+   * @example
+   * ```ts
+   * const parent = $('#item').offsetParent();
+   * ```
+   */
+  offsetParent(): Element | null {
+    return isHTMLElement(this.element) ? this.element.offsetParent : null;
+  }
+
+  /**
+   * Gets the current position relative to the offset parent.
+   *
+   * @returns Position object with top and left coordinates
+   *
+   * @example
+   * ```ts
+   * const { top, left } = $('#item').position();
+   * ```
+   */
+  position(): { top: number; left: number } {
+    if (!isHTMLElement(this.element)) {
+      return { top: 0, left: 0 };
+    }
+
+    const el = this.element;
+    return {
+      top: el.offsetTop,
+      left: el.offsetLeft,
+    };
+  }
+
+  /**
+   * Gets the inner width of the element (content + padding, excluding border).
+   *
+   * This corresponds to the element's `clientWidth` and mirrors jQuery's
+   * `innerWidth()` method.
+   *
+   * @returns Inner width in pixels, or 0 for non-HTML elements
+   *
+   * @example
+   * ```ts
+   * const innerW = $('#panel').innerWidth();
+   * ```
+   */
+  innerWidth(): number {
+    return getInnerSize(this.element, 'width');
+  }
+
+  /**
+   * Gets the inner height of the element (content + padding, excluding border).
+   *
+   * This corresponds to the element's `clientHeight` and mirrors jQuery's
+   * `innerHeight()` method.
+   *
+   * @returns Inner height in pixels, or 0 for non-HTML elements
+   *
+   * @example
+   * ```ts
+   * const innerH = $('#panel').innerHeight();
+   * ```
+   */
+  innerHeight(): number {
+    return getInnerSize(this.element, 'height');
+  }
+
+  /**
+   * Gets the outer width of the element, optionally including margins.
+   *
+   * @param includeMargin - When true, include horizontal margins
+   * @returns Outer width in pixels
+   *
+   * @example
+   * ```ts
+   * const width = $('#panel').outerWidth();
+   * const widthWithMargin = $('#panel').outerWidth(true);
+   * ```
+   */
+  outerWidth(includeMargin: boolean = false): number {
+    return getOuterSize(this.element, 'width', includeMargin);
+  }
+
+  /**
+   * Gets the outer height of the element, optionally including margins.
+   *
+   * @param includeMargin - When true, include vertical margins
+   * @returns Outer height in pixels
+   *
+   * @example
+   * ```ts
+   * const height = $('#panel').outerHeight();
+   * const heightWithMargin = $('#panel').outerHeight(true);
+   * ```
+   */
+  outerHeight(includeMargin: boolean = false): number {
+    return getOuterSize(this.element, 'height', includeMargin);
+  }
+
   /**
    * Scrolls the element into view with configurable behavior.
    *
@@ -674,6 +915,11 @@ export class BQueryElement {
    * Serializes form data to a plain object.
    * Only works on form elements; returns empty object for non-forms.
    *
+   * For security hardening, the returned object uses a null prototype,
+   * so inherited members like `hasOwnProperty` are not available directly.
+   * Prefer `Object.keys()` or `Object.prototype.hasOwnProperty.call(...)`
+   * when checking for fields on the serialized result.
+   *
    * @returns Object with form field names as keys and values
    *
    * @example
@@ -681,6 +927,7 @@ export class BQueryElement {
    * // For a form with <input name="email" value="test@example.com">
    * const data = $('#myForm').serialize();
    * // { email: 'test@example.com' }
+   * Object.prototype.hasOwnProperty.call(data, 'email'); // true
    * ```
    */
   serialize(): Record<string, string | string[]> {
@@ -689,13 +936,10 @@ export class BQueryElement {
       return {};
     }
 
-    const result: Record<string, string | string[]> = {};
-    const formData = new FormData(form);
-
-    for (const [key, value] of formData.entries()) {
-      if (typeof value !== 'string') continue; // Skip File objects
+    const result = Object.create(null) as Record<string, string | string[]>;
 
-      if (key in result) {
+    for (const [key, value] of getFormEntries(form)) {
+      if (Object.prototype.hasOwnProperty.call(result, key)) {
         // Handle multiple values (e.g., checkboxes)
         const existing = result[key];
         if (Array.isArray(existing)) {
@@ -728,13 +972,10 @@ export class BQueryElement {
       return '';
     }
 
-    const formData = new FormData(form);
     const params = new URLSearchParams();
 
-    for (const [key, value] of formData.entries()) {
-      if (typeof value === 'string') {
-        params.append(key, value);
-      }
+    for (const [key, value] of getFormEntries(form)) {
+      params.append(key, value);
     }
 
     return params.toString();

package/src/core/env.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared environment detection helpers.
+ *
+ * @internal
+ */
+
+type BQueryEnvGlobal = typeof globalThis & {
+  __BQUERY_DEV__?: boolean;
+  process?: {
+    env?: {
+      NODE_ENV?: string;
+    };
+    release?: {
+      name?: string;
+    };
+    versions?: {
+      node?: string;
+    };
+  };
+};
+
+/**
+ * Returns whether development-only diagnostics should be enabled.
+ *
+ * Priority:
+ * 1. Explicit global override via `globalThis.__BQUERY_DEV__`
+ * 2. `process.env.NODE_ENV`
+ * 3. Actual Node-like runtimes without `NODE_ENV` default to development
+ * 4. Production-safe fallback (`false`)
+ *
+ * @internal
+ */
+export const detectDevEnvironment = (): boolean => {
+  try {
+    const globalObject = globalThis as BQueryEnvGlobal;
+
+    if (typeof globalObject.__BQUERY_DEV__ === 'boolean') {
+      return globalObject.__BQUERY_DEV__;
+    }
+
+    const nodeEnv = globalObject.process?.env?.NODE_ENV;
+    if (typeof nodeEnv === 'string') {
+      return nodeEnv !== 'production';
+    }
+
+    const nodeVersion = globalObject.process?.versions?.node;
+    if (typeof nodeVersion === 'string' && nodeVersion.length > 0) {
+      return true;
+    }
+
+    const releaseName = globalObject.process?.release?.name;
+    if (releaseName === 'node' || releaseName === 'io.js') {
+      return true;
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+};

package/src/core/index.ts

@@ -3,6 +3,7 @@ export { BQueryElement } from './element';
 export { $, $$ } from './selector';
 // Re-export the utils namespace for backward compatibility
 export { utils } from './utils';
+export type { BQueryUtils } from './utils';
 // Export individual utilities (except internal helpers)
 export {
   chunk,

package/src/core/shared.ts

@@ -11,3 +11,67 @@ export const applyAll = (elements: ElementList, action: (el: Element) => void) =
     action(el);
   }
 };
+
+/** @internal */
+export const isHTMLElement = (element: Element | null | undefined): element is HTMLElement => {
+  if (!element) {
+    return false;
+  }
+
+  const view = element.ownerDocument?.defaultView;
+  const HTMLElementCtor = view?.HTMLElement ?? globalThis.HTMLElement;
+  return typeof HTMLElementCtor === 'function' && element instanceof HTMLElementCtor;
+};
+
+/**
+ * Gets an element's inner size (content + padding, excluding border and margin).
+ *
+ * @internal
+ */
+export const getInnerSize = (
+  element: Element | null | undefined,
+  dimension: 'width' | 'height'
+): number => {
+  if (!isHTMLElement(element)) {
+    return 0;
+  }
+  return dimension === 'width' ? element.clientWidth : element.clientHeight;
+};
+
+/**
+ * Gets an element's outer size, optionally including margins.
+ *
+ * @internal
+ */
+export const getOuterSize = (
+  element: Element | null | undefined,
+  dimension: 'width' | 'height',
+  includeMargin: boolean
+): number => {
+  if (!isHTMLElement(element)) {
+    return 0;
+  }
+
+  const size = dimension === 'width' ? element.offsetWidth : element.offsetHeight;
+  if (!includeMargin) {
+    return size;
+  }
+
+  const view = element.ownerDocument?.defaultView;
+  if (!view || typeof view.getComputedStyle !== 'function') {
+    return size;
+  }
+
+  const computedStyle = view.getComputedStyle(element);
+  const startMargin = Number.parseFloat(
+    computedStyle.getPropertyValue(dimension === 'width' ? 'margin-left' : 'margin-top')
+  );
+  const endMargin = Number.parseFloat(
+    computedStyle.getPropertyValue(dimension === 'width' ? 'margin-right' : 'margin-bottom')
+  );
+
+  const safeStartMargin = Number.isNaN(startMargin) ? 0 : startMargin;
+  const safeEndMargin = Number.isNaN(endMargin) ? 0 : endMargin;
+
+  return size + safeStartMargin + safeEndMargin;
+};