@bquery/bquery 1.6.0 → 1.7.0

package/src/index.ts

@@ -1,36 +1,108 @@
-/**
- * bQuery.js — The jQuery for the Modern Web Platform
- *
- * A zero-build, TypeScript-first library that bridges vanilla JavaScript
- * and build-step frameworks with modern features.
- *
- * @module bquery
- * @see https://github.com/bquery/bquery
- */
-
-// Core module: selectors, DOM ops, events, utils
-export * from './core/index';
-
-// Reactive module: signals, computed, effects, binding
-export * from './reactive/index';
-
-// Component module: Web Components helper
-export * from './component/index';
-
-// Motion module: view transitions, FLIP, springs
-export * from './motion/index';
-
-// Security module: sanitizer, CSP, Trusted Types
-export * from './security/index';
-
-// Platform module: storage, buckets, notifications, cache
-export * from './platform/index';
-
-// Router module: SPA routing, navigation guards
-export * from './router/index';
-
-// Store module: state management with signals
-export * from './store/index';
-
-// View module: declarative DOM bindings
-export * from './view/index';
+/**
+ * bQuery.js — The jQuery for the Modern Web Platform
+ *
+ * A zero-build, TypeScript-first library that bridges vanilla JavaScript
+ * and build-step frameworks with modern features.
+ *
+ * @module bquery
+ * @see https://github.com/bquery/bquery
+ */
+
+// Core module: selectors, DOM ops, events, utils
+export * from './core/index';
+
+// Reactive module: signals, computed, effects, binding
+export * from './reactive/index';
+
+// Component module: Web Components helper
+export * from './component/index';
+
+// Motion module: view transitions, FLIP, springs
+export * from './motion/index';
+
+// Security module: sanitizer, CSP, Trusted Types
+export * from './security/index';
+
+// Platform module: storage, buckets, notifications, cache
+export * from './platform/index';
+
+// Router module: SPA routing, navigation guards
+export * from './router/index';
+
+// Store module: state management with signals
+export * from './store/index';
+
+// View module: declarative DOM bindings
+export * from './view/index';
+
+// Forms module: reactive form handling and validation
+export * from './forms/index';
+
+// i18n module: internationalization, translations, formatting
+export * from './i18n/index';
+
+// a11y module: accessibility utilities
+// Note: prefersReducedMotion is not re-exported here to avoid naming conflict
+// with the motion module's prefersReducedMotion(). Use @bquery/bquery/a11y for
+// the reactive signal version.
+export {
+  announceToScreenReader,
+  auditA11y,
+  clearAnnouncements,
+  getFocusableElements,
+  prefersColorScheme,
+  prefersContrast,
+  releaseFocus,
+  rovingTabIndex,
+  skipLink,
+  trapFocus,
+} from './a11y/index';
+export type {
+  AnnouncePriority,
+  AuditFinding,
+  AuditResult,
+  AuditSeverity,
+  ColorScheme,
+  ContrastPreference,
+  FocusTrapHandle,
+  RovingTabIndexHandle,
+  RovingTabIndexOptions,
+  SkipLinkHandle,
+  SkipLinkOptions,
+  TrapFocusOptions,
+} from './a11y/index';
+
+// DnD module: drag-and-drop, drop zones, sortable lists
+export * from './dnd/index';
+
+// Media module: reactive browser and device API signals
+export * from './media/index';
+
+// Plugin module: global plugin registration system
+export * from './plugin/index';
+
+// DevTools module: runtime debugging utilities
+export * from './devtools/index';
+
+// Testing module: test helpers for signals, components, router, and events
+export {
+  renderComponent,
+  flushEffects,
+  mockSignal,
+  mockRouter,
+  fireEvent,
+  waitFor,
+} from './testing/index';
+export type {
+  FireEventOptions,
+  MockRouter,
+  MockRouterOptions,
+  MockSignal,
+  RenderComponentOptions,
+  RenderResult,
+  TestRoute,
+  WaitForOptions,
+} from './testing/index';
+
+// SSR module: server-side rendering, hydration, store state serialization
+export * from './ssr/index';

package/src/media/battery.ts

@@ -0,0 +1,116 @@
+/**
+ * Reactive battery status.
+ *
+ * Provides a reactive signal tracking the device's battery status
+ * via the Battery Status API.
+ *
+ * @module bquery/media
+ */
+
+import { signal, readonly } from '../reactive/index';
+import type { BatterySignal, BatteryState } from './types';
+
+/**
+ * BatteryManager interface for the Battery Status API.
+ * @internal
+ */
+interface BatteryManager extends EventTarget {
+  charging: boolean;
+  chargingTime: number;
+  dischargingTime: number;
+  level: number;
+}
+
+/** Default battery state when API is unavailable. */
+const DEFAULT_BATTERY_STATE: BatteryState = {
+  supported: false,
+  charging: false,
+  chargingTime: 0,
+  dischargingTime: 0,
+  level: 1,
+};
+
+/**
+ * Returns a reactive signal tracking the device's battery status.
+ *
+ * Uses the Battery Status API (`navigator.getBattery()`) where available.
+ * Falls back gracefully to a default state with `supported: false` when
+ * the API is not available.
+ *
+ * @returns A readonly reactive signal with battery state and a `destroy()` method
+ * to remove Battery Status API listeners
+ *
+ * @example
+ * ```ts
+ * import { useBattery } from '@bquery/bquery/media';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const battery = useBattery();
+ * effect(() => {
+ *   if (battery.value.supported) {
+ *     console.log(`Battery: ${(battery.value.level * 100).toFixed(0)}%`);
+ *     console.log(`Charging: ${battery.value.charging}`);
+ *   }
+ * });
+ * ```
+ */
+export const useBattery = (): BatterySignal => {
+  const s = signal<BatteryState>({ ...DEFAULT_BATTERY_STATE });
+  let cleanup: (() => void) | undefined;
+  let destroyed = false;
+
+  if (
+    typeof navigator !== 'undefined' &&
+    'getBattery' in navigator &&
+    typeof (navigator as Navigator & { getBattery: () => Promise<BatteryManager> }).getBattery ===
+      'function'
+  ) {
+    const nav = navigator as Navigator & { getBattery: () => Promise<BatteryManager> };
+
+    nav
+      .getBattery()
+      .then((battery) => {
+        if (destroyed) return;
+
+        const update = (): void => {
+          s.value = {
+            supported: true,
+            charging: battery.charging,
+            chargingTime: battery.chargingTime,
+            dischargingTime: battery.dischargingTime,
+            level: battery.level,
+          };
+        };
+
+        update();
+
+        battery.addEventListener('chargingchange', update);
+        battery.addEventListener('chargingtimechange', update);
+        battery.addEventListener('dischargingtimechange', update);
+        battery.addEventListener('levelchange', update);
+        cleanup = () => {
+          battery.removeEventListener('chargingchange', update);
+          battery.removeEventListener('chargingtimechange', update);
+          battery.removeEventListener('dischargingtimechange', update);
+          battery.removeEventListener('levelchange', update);
+        };
+      })
+      .catch(() => {
+        // Battery API rejected — keep default state
+      });
+  }
+
+  const ro = readonly(s) as BatterySignal;
+  Object.defineProperty(ro, 'destroy', {
+    enumerable: false,
+    configurable: true,
+    value(): void {
+      if (destroyed) return;
+      destroyed = true;
+      cleanup?.();
+      s.dispose();
+    },
+  });
+
+  return ro;
+};

package/src/media/breakpoints.ts

@@ -0,0 +1,131 @@
+/**
+ * Named breakpoint signals.
+ *
+ * Defines named breakpoints that return reactive boolean signals,
+ * making it easy to respond to viewport size changes.
+ *
+ * @module bquery/media
+ */
+
+import { readonly, signal } from '../reactive/index';
+import type { BreakpointMap, MediaSignalHandle } from './types';
+
+type BreakpointSignals<T extends BreakpointMap> = { [K in keyof T]: MediaSignalHandle<boolean> } & {
+  destroyAll(): void;
+} & ('destroy' extends keyof T ? Record<never, never> : { destroy(): void });
+
+/**
+ * Defines named breakpoints and returns reactive boolean signals for each.
+ *
+ * Each breakpoint is a minimum-width media query. The returned object maps
+ * each breakpoint name to a `ReadonlySignal<boolean>` that is `true` when
+ * the viewport width is at or above the breakpoint value.
+ *
+ * @param bp - An object mapping breakpoint names to minimum widths in pixels
+ * @returns An object with the same keys, each a reactive boolean signal with
+ * `destroy()`, plus a top-level `destroyAll()` method to clean up all listeners.
+ * When no breakpoint is named `destroy`, a `destroy()` alias is also provided.
+ *
+ * @example
+ * ```ts
+ * import { breakpoints } from '@bquery/bquery/media';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const bp = breakpoints({ sm: 640, md: 768, lg: 1024, xl: 1280 });
+ *
+ * effect(() => {
+ *   if (bp.xl.value) {
+ *     console.log('Extra large viewport');
+ *   } else if (bp.lg.value) {
+ *     console.log('Large viewport');
+ *   } else if (bp.md.value) {
+ *     console.log('Medium viewport');
+ *   } else {
+ *     console.log('Small viewport');
+ *   }
+ * });
+ * ```
+ */
+export const breakpoints = <T extends BreakpointMap>(
+  bp: T
+): BreakpointSignals<T> => {
+  const signals = {} as { [K in keyof T]: MediaSignalHandle<boolean> };
+  const destroyers: Array<() => void> = [];
+
+  type LegacyMediaQueryList = MediaQueryList & {
+    addListener?: (listener: (event: MediaQueryListEvent | MediaQueryList) => void) => void;
+    removeListener?: (listener: (event: MediaQueryListEvent | MediaQueryList) => void) => void;
+  };
+
+  for (const key of Object.keys(bp) as Array<keyof T>) {
+    const width = bp[key];
+    const s = signal(false);
+    let cleanup: (() => void) | undefined;
+
+    if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+      try {
+        const mql = window.matchMedia(`(min-width: ${width}px)`);
+        s.value = mql.matches;
+
+        const handler = (e: MediaQueryListEvent | MediaQueryList): void => {
+          s.value = e.matches;
+        };
+
+        if (typeof mql.addEventListener === 'function') {
+          mql.addEventListener('change', handler);
+          cleanup = () => {
+            mql.removeEventListener('change', handler);
+          };
+        } else {
+          const legacyMql = mql as LegacyMediaQueryList;
+          if (typeof legacyMql.addListener === 'function') {
+            legacyMql.addListener(handler);
+            cleanup = () => {
+              legacyMql.removeListener?.(handler);
+            };
+          }
+        }
+      } catch {
+        // matchMedia may throw in non-browser environments
+      }
+    }
+
+    const ro = readonly(s) as MediaSignalHandle<boolean>;
+    let destroyed = false;
+    Object.defineProperty(ro, 'destroy', {
+      enumerable: false,
+      configurable: true,
+      value(): void {
+        if (destroyed) return;
+        destroyed = true;
+        cleanup?.();
+        s.dispose();
+      },
+    });
+    destroyers.push(ro.destroy);
+    signals[key] = ro;
+  }
+
+  let destroyed = false;
+  const result = Object.defineProperty(signals, 'destroyAll', {
+    enumerable: false,
+    configurable: true,
+    value(): void {
+      if (destroyed) return;
+      destroyed = true;
+      destroyers.forEach((destroy) => {
+        destroy();
+      });
+    },
+  }) as BreakpointSignals<T>;
+
+  if (!Object.prototype.hasOwnProperty.call(signals, 'destroy')) {
+    Object.defineProperty(result, 'destroy', {
+      enumerable: false,
+      configurable: true,
+      value: result.destroyAll,
+    });
+  }
+
+  return result;
+};

package/src/media/clipboard.ts

@@ -0,0 +1,80 @@
+/**
+ * Async clipboard API wrappers.
+ *
+ * Provides simple read/write access to the system clipboard
+ * via the Async Clipboard API.
+ *
+ * @module bquery/media
+ */
+
+import type { ClipboardAPI } from './types';
+
+const CLIPBOARD_UNAVAILABLE_ERROR =
+  'bQuery media: Clipboard API is unavailable. Use a secure context (HTTPS or localhost) and ensure clipboard permissions or user-activation requirements are met.';
+
+/**
+ * Clipboard API wrapper providing simple async read/write access.
+ *
+ * Uses the modern Async Clipboard API (`navigator.clipboard`) under the hood.
+ * Both methods are `Promise`-based and will reject if the API is unavailable
+ * or permission is denied.
+ *
+ * @example
+ * ```ts
+ * import { clipboard } from '@bquery/bquery/media';
+ *
+ * // Write text to clipboard
+ * await clipboard.write('Hello, world!');
+ *
+ * // Read text from clipboard
+ * const text = await clipboard.read();
+ * console.log(text); // "Hello, world!"
+ * ```
+ */
+export const clipboard: ClipboardAPI = {
+  /**
+   * Reads text from the system clipboard.
+   *
+   * @returns A promise that resolves with the clipboard text content
+   * @throws Error if the Clipboard API is not available or permission is denied
+   *
+   * @example
+   * ```ts
+   * const text = await clipboard.read();
+   * console.log('Clipboard contains:', text);
+   * ```
+   */
+  read: async (): Promise<string> => {
+    if (
+      typeof navigator === 'undefined' ||
+      !navigator.clipboard ||
+      typeof navigator.clipboard.readText !== 'function'
+    ) {
+      throw new Error(CLIPBOARD_UNAVAILABLE_ERROR);
+    }
+    return navigator.clipboard.readText();
+  },
+
+  /**
+   * Writes text to the system clipboard.
+   *
+   * @param text - The text to write to the clipboard
+   * @returns A promise that resolves when the text has been written
+   * @throws Error if the Clipboard API is not available or permission is denied
+   *
+   * @example
+   * ```ts
+   * await clipboard.write('Copied!');
+   * ```
+   */
+  write: async (text: string): Promise<void> => {
+    if (
+      typeof navigator === 'undefined' ||
+      !navigator.clipboard ||
+      typeof navigator.clipboard.writeText !== 'function'
+    ) {
+      throw new Error(CLIPBOARD_UNAVAILABLE_ERROR);
+    }
+    return navigator.clipboard.writeText(text);
+  },
+};

package/src/media/device-sensors.ts

@@ -0,0 +1,158 @@
+/**
+ * Reactive device motion and orientation sensors.
+ *
+ * Provides reactive signals for accelerometer, gyroscope, and
+ * compass data via the DeviceMotion and DeviceOrientation APIs.
+ *
+ * @module bquery/media
+ */
+
+import { signal, readonly } from '../reactive/index';
+import type {
+  DeviceMotionSignal,
+  DeviceMotionState,
+  DeviceOrientationSignal,
+  DeviceOrientationState,
+} from './types';
+
+/** Default device motion state. */
+const DEFAULT_MOTION_STATE: DeviceMotionState = {
+  acceleration: { x: null, y: null, z: null },
+  accelerationIncludingGravity: { x: null, y: null, z: null },
+  rotationRate: { alpha: null, beta: null, gamma: null },
+  interval: 0,
+};
+
+/** Default device orientation state. */
+const DEFAULT_ORIENTATION_STATE: DeviceOrientationState = {
+  alpha: null,
+  beta: null,
+  gamma: null,
+  absolute: false,
+};
+
+/**
+ * Returns a reactive signal tracking device motion (accelerometer + gyroscope).
+ *
+ * Uses the `devicemotion` event to provide acceleration, acceleration
+ * including gravity, and rotation rate data.
+ *
+ * @returns A readonly reactive signal with motion sensor data and a `destroy()`
+ * method to remove the underlying event listener
+ *
+ * @example
+ * ```ts
+ * import { useDeviceMotion } from '@bquery/bquery/media';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const motion = useDeviceMotion();
+ * effect(() => {
+ *   const { acceleration } = motion.value;
+ *   console.log(`Acceleration: x=${acceleration.x}, y=${acceleration.y}, z=${acceleration.z}`);
+ * });
+ * ```
+ */
+export const useDeviceMotion = (): DeviceMotionSignal => {
+  const s = signal<DeviceMotionState>({ ...DEFAULT_MOTION_STATE });
+  let cleanup: (() => void) | undefined;
+
+  if (typeof window !== 'undefined') {
+    const handler = (e: DeviceMotionEvent): void => {
+      s.value = {
+        acceleration: {
+          x: e.acceleration?.x ?? null,
+          y: e.acceleration?.y ?? null,
+          z: e.acceleration?.z ?? null,
+        },
+        accelerationIncludingGravity: {
+          x: e.accelerationIncludingGravity?.x ?? null,
+          y: e.accelerationIncludingGravity?.y ?? null,
+          z: e.accelerationIncludingGravity?.z ?? null,
+        },
+        rotationRate: {
+          alpha: e.rotationRate?.alpha ?? null,
+          beta: e.rotationRate?.beta ?? null,
+          gamma: e.rotationRate?.gamma ?? null,
+        },
+        interval: e.interval ?? 0,
+      };
+    };
+
+    window.addEventListener('devicemotion', handler);
+    cleanup = () => {
+      window.removeEventListener('devicemotion', handler);
+    };
+  }
+
+  const ro = readonly(s) as DeviceMotionSignal;
+  let destroyed = false;
+  Object.defineProperty(ro, 'destroy', {
+    enumerable: false,
+    configurable: true,
+    value(): void {
+      if (destroyed) return;
+      destroyed = true;
+      cleanup?.();
+      s.dispose();
+    },
+  });
+
+  return ro;
+};
+
+/**
+ * Returns a reactive signal tracking device orientation (compass/gyroscope).
+ *
+ * Uses the `deviceorientation` event to provide alpha (compass heading),
+ * beta (front-to-back tilt), and gamma (left-to-right tilt) data.
+ *
+ * @returns A readonly reactive signal with orientation data and a `destroy()`
+ * method to remove the underlying event listener
+ *
+ * @example
+ * ```ts
+ * import { useDeviceOrientation } from '@bquery/bquery/media';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const orientation = useDeviceOrientation();
+ * effect(() => {
+ *   console.log(`Compass heading: ${orientation.value.alpha}°`);
+ *   console.log(`Tilt: ${orientation.value.beta}° / ${orientation.value.gamma}°`);
+ * });
+ * ```
+ */
+export const useDeviceOrientation = (): DeviceOrientationSignal => {
+  const s = signal<DeviceOrientationState>({ ...DEFAULT_ORIENTATION_STATE });
+  let cleanup: (() => void) | undefined;
+
+  if (typeof window !== 'undefined') {
+    const handler = (e: DeviceOrientationEvent): void => {
+      s.value = {
+        alpha: e.alpha ?? null,
+        beta: e.beta ?? null,
+        gamma: e.gamma ?? null,
+        absolute: e.absolute ?? false,
+      };
+    };
+
+    window.addEventListener('deviceorientation', handler);
+    cleanup = () => {
+      window.removeEventListener('deviceorientation', handler);
+    };
+  }
+
+  const ro = readonly(s) as DeviceOrientationSignal;
+  let destroyed = false;
+  Object.defineProperty(ro, 'destroy', {
+    enumerable: false,
+    configurable: true,
+    value(): void {
+      if (destroyed) return;
+      destroyed = true;
+      cleanup?.();
+      s.dispose();
+    },
+  });
+
+  return ro;
+};