@bquery/bquery 1.5.0 → 1.7.0

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

@@ -1,48 +1,49 @@
-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';
+export { BQueryCollection } from './collection';
+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,
+  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/shared.ts

@@ -1,13 +1,62 @@
-/**
- * Shared helpers for element wrappers.
- */
-export type ElementList = Element[];
-
-export const toElementList = (input: Element | ElementList): ElementList =>
-  Array.isArray(input) ? input : [input];
-
-export const applyAll = (elements: ElementList, action: (el: Element) => void) => {
-  for (const el of elements) {
-    action(el);
-  }
-};
+/**
+ * Shared helpers for element wrappers.
+ */
+export type ElementList = Element[];
+
+export const toElementList = (input: Element | ElementList): ElementList =>
+  Array.isArray(input) ? input : [input];
+
+export const applyAll = (elements: ElementList, action: (el: Element) => void) => {
+  for (const el of elements) {
+    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 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;
+};

package/src/core/utils/index.ts

@@ -1,83 +1,148 @@
-/**
- * Utility helpers used across the framework.
- * These are intentionally small and framework-agnostic to keep the core tiny.
- *
- * @module bquery/core/utils
- */
-
-export * from './array';
-export * from './function';
-export * from './misc';
-export * from './number';
-export * from './object';
-export * from './string';
-export * from './type-guards';
-
-import { chunk, compact, ensureArray, flatten, unique } from './array';
-import { debounce, noop, once, throttle } from './function';
-import { isEmpty, parseJson, sleep, uid } from './misc';
-import { clamp, inRange, randomInt, toNumber } from './number';
-import { clone, hasOwn, isPlainObject, merge, omit, pick } from './object';
-import { capitalize, escapeRegExp, slugify, toCamelCase, toKebabCase, truncate } from './string';
-import {
-  isArray,
-  isBoolean,
-  isCollection,
-  isDate,
-  isElement,
-  isFunction,
-  isNumber,
-  isObject,
-  isPromise,
-  isString,
-} from './type-guards';
-
-/**
- * Utility object containing common helper functions.
- * All utilities are designed to be tree-shakeable and have zero dependencies.
- *
- * Note: `isPrototypePollutionKey` is intentionally excluded from this namespace
- * as it is an internal security helper. It remains available as a named export
- * for internal framework use.
- */
-export const utils = {
-  clone,
-  merge,
-  pick,
-  omit,
-  hasOwn,
-  debounce,
-  throttle,
-  once,
-  noop,
-  uid,
-  isElement,
-  isCollection,
-  isEmpty,
-  isPlainObject,
-  isFunction,
-  isString,
-  isNumber,
-  isBoolean,
-  isArray,
-  isDate,
-  isPromise,
-  isObject,
-  parseJson,
-  sleep,
-  randomInt,
-  clamp,
-  inRange,
-  toNumber,
-  capitalize,
-  toKebabCase,
-  toCamelCase,
-  truncate,
-  slugify,
-  escapeRegExp,
-  ensureArray,
-  unique,
-  chunk,
-  compact,
-  flatten,
-};
+/**
+ * Utility helpers used across the framework.
+ * These are intentionally small and framework-agnostic to keep the core tiny.
+ *
+ * @module bquery/core/utils
+ */
+
+export * from './array';
+export * from './function';
+export * from './misc';
+export * from './number';
+export * from './object';
+export * from './string';
+export * from './type-guards';
+
+import { chunk, compact, ensureArray, flatten, unique } from './array';
+import { debounce, noop, once, throttle } from './function';
+import { isEmpty, parseJson, sleep, uid } from './misc';
+import { clamp, inRange, randomInt, toNumber } from './number';
+import { clone, hasOwn, isPlainObject, merge, omit, pick } from './object';
+import { capitalize, escapeRegExp, slugify, toCamelCase, toKebabCase, truncate } from './string';
+import {
+  isArray,
+  isBoolean,
+  isCollection,
+  isDate,
+  isElement,
+  isFunction,
+  isNumber,
+  isObject,
+  isPromise,
+  isString,
+} from './type-guards';
+
+/**
+ * Describes the public shape of the aggregated {@link utils} namespace.
+ *
+ * Every member maps 1-to-1 to a named export from one of the sub-modules
+ * (`array`, `function`, `misc`, `number`, `object`, `string`, `type-guards`).
+ *
+ * `isPrototypePollutionKey` is intentionally excluded as it is an
+ * internal security helper. It remains available as a named export for
+ * internal framework use.
+ */
+export interface BQueryUtils {
+  // ── object ──────────────────────────────────────────────────────────
+  readonly clone: typeof clone;
+  readonly merge: typeof merge;
+  readonly pick: typeof pick;
+  readonly omit: typeof omit;
+  readonly hasOwn: typeof hasOwn;
+  readonly isPlainObject: typeof isPlainObject;
+
+  // ── function ────────────────────────────────────────────────────────
+  readonly debounce: typeof debounce;
+  readonly throttle: typeof throttle;
+  readonly once: typeof once;
+  readonly noop: typeof noop;
+
+  // ── misc ────────────────────────────────────────────────────────────
+  readonly uid: typeof uid;
+  readonly isEmpty: typeof isEmpty;
+  readonly parseJson: typeof parseJson;
+  readonly sleep: typeof sleep;
+
+  // ── type-guards ─────────────────────────────────────────────────────
+  readonly isElement: typeof isElement;
+  readonly isCollection: typeof isCollection;
+  readonly isFunction: typeof isFunction;
+  readonly isString: typeof isString;
+  readonly isNumber: typeof isNumber;
+  readonly isBoolean: typeof isBoolean;
+  readonly isArray: typeof isArray;
+  readonly isDate: typeof isDate;
+  readonly isPromise: typeof isPromise;
+  readonly isObject: typeof isObject;
+
+  // ── number ──────────────────────────────────────────────────────────
+  readonly randomInt: typeof randomInt;
+  readonly clamp: typeof clamp;
+  readonly inRange: typeof inRange;
+  readonly toNumber: typeof toNumber;
+
+  // ── string ──────────────────────────────────────────────────────────
+  readonly capitalize: typeof capitalize;
+  readonly toKebabCase: typeof toKebabCase;
+  readonly toCamelCase: typeof toCamelCase;
+  readonly truncate: typeof truncate;
+  readonly slugify: typeof slugify;
+  readonly escapeRegExp: typeof escapeRegExp;
+
+  // ── array ───────────────────────────────────────────────────────────
+  readonly ensureArray: typeof ensureArray;
+  readonly unique: typeof unique;
+  readonly chunk: typeof chunk;
+  readonly compact: typeof compact;
+  readonly flatten: typeof flatten;
+}
+
+/**
+ * Utility object containing common helper functions.
+ * All utilities are designed to be tree-shakeable and have zero dependencies.
+ *
+ * Note: `isPrototypePollutionKey` is intentionally excluded from this namespace
+ * as it is an internal security helper. It remains available as a named export
+ * for internal framework use.
+ */
+export const utils: BQueryUtils = {
+  clone,
+  merge,
+  pick,
+  omit,
+  hasOwn,
+  debounce,
+  throttle,
+  once,
+  noop,
+  uid,
+  isElement,
+  isCollection,
+  isEmpty,
+  isPlainObject,
+  isFunction,
+  isString,
+  isNumber,
+  isBoolean,
+  isArray,
+  isDate,
+  isPromise,
+  isObject,
+  parseJson,
+  sleep,
+  randomInt,
+  clamp,
+  inRange,
+  toNumber,
+  capitalize,
+  toKebabCase,
+  toCamelCase,
+  truncate,
+  slugify,
+  escapeRegExp,
+  ensureArray,
+  unique,
+  chunk,
+  compact,
+  flatten,
+};