@bquery/bquery 1.6.0 → 1.7.0

package/src/media/geolocation.ts

@@ -0,0 +1,119 @@
+/**
+ * Reactive geolocation.
+ *
+ * Provides a reactive signal tracking the device's geographic position
+ * via the Geolocation API.
+ *
+ * @module bquery/media
+ */
+
+import { signal, readonly } from '../reactive/index';
+import type { GeolocationOptions, GeolocationSignal, GeolocationState } from './types';
+
+/** Default geolocation state. */
+const DEFAULT_GEO_STATE: GeolocationState = {
+  supported: false,
+  loading: false,
+  latitude: null,
+  longitude: null,
+  accuracy: null,
+  altitude: null,
+  altitudeAccuracy: null,
+  heading: null,
+  speed: null,
+  timestamp: null,
+  error: null,
+};
+
+/**
+ * Returns a reactive signal tracking the device's geographic position.
+ *
+ * Uses the Geolocation API (`navigator.geolocation`) where available.
+ * Can operate in one-shot mode (default) or continuous watch mode.
+ *
+ * @param options - Configuration for the geolocation request
+ * @returns A readonly reactive signal with position data and loading/error state,
+ * plus a `destroy()` method to stop an active watcher
+ *
+ * @example
+ * ```ts
+ * import { useGeolocation } from '@bquery/bquery/media';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * // One-shot position
+ * const geo = useGeolocation();
+ * effect(() => {
+ *   if (geo.value.loading) return console.log('Getting position...');
+ *   if (geo.value.error) return console.error(geo.value.error);
+ *   console.log(`Lat: ${geo.value.latitude}, Lng: ${geo.value.longitude}`);
+ * });
+ *
+ * // Continuous watch with high accuracy
+ * const geoWatch = useGeolocation({ watch: true, enableHighAccuracy: true });
+ * ```
+ */
+export const useGeolocation = (options: GeolocationOptions = {}): GeolocationSignal => {
+  const { enableHighAccuracy = false, maximumAge = 0, timeout = Infinity, watch = false } = options;
+
+  const s = signal<GeolocationState>({ ...DEFAULT_GEO_STATE });
+
+  let destroyWatcher: (() => void) | undefined;
+
+  if (typeof navigator !== 'undefined' && 'geolocation' in navigator) {
+    s.value = { ...DEFAULT_GEO_STATE, supported: true, loading: true };
+
+    const posOptions: PositionOptions = {
+      enableHighAccuracy,
+      maximumAge,
+      timeout: timeout === Infinity ? undefined : timeout,
+    };
+
+    const onSuccess = (pos: GeolocationPosition): void => {
+      s.value = {
+        supported: true,
+        loading: false,
+        latitude: pos.coords.latitude,
+        longitude: pos.coords.longitude,
+        accuracy: pos.coords.accuracy,
+        altitude: pos.coords.altitude,
+        altitudeAccuracy: pos.coords.altitudeAccuracy,
+        heading: pos.coords.heading,
+        speed: pos.coords.speed,
+        timestamp: pos.timestamp,
+        error: null,
+      };
+    };
+
+    const onError = (err: GeolocationPositionError): void => {
+      s.value = {
+        ...s.value,
+        loading: false,
+        error: err.message,
+      };
+    };
+
+    if (watch) {
+      const watchId = navigator.geolocation.watchPosition(onSuccess, onError, posOptions);
+      destroyWatcher = () => {
+        navigator.geolocation.clearWatch(watchId);
+      };
+    } else {
+      navigator.geolocation.getCurrentPosition(onSuccess, onError, posOptions);
+    }
+  }
+
+  const ro = readonly(s) as GeolocationSignal;
+  let destroyed = false;
+  Object.defineProperty(ro, 'destroy', {
+    enumerable: false,
+    configurable: true,
+    value(): void {
+      if (destroyed) return;
+      destroyed = true;
+      destroyWatcher?.();
+      s.dispose();
+    },
+  });
+
+  return ro;
+};

package/src/media/index.ts

@@ -0,0 +1,76 @@
+/**
+ * bQuery Media module — reactive browser and device API signals.
+ *
+ * Provides reactive wrappers around browser media queries, viewport,
+ * network status, battery, geolocation, device sensors, and clipboard.
+ *
+ * @module bquery/media
+ *
+ * @example
+ * ```ts
+ * import { mediaQuery, breakpoints, useViewport, useNetworkStatus, clipboard } from '@bquery/bquery/media';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * // Reactive media query
+ * const isDark = mediaQuery('(prefers-color-scheme: dark)');
+ *
+ * // Named breakpoints
+ * const bp = breakpoints({ sm: 640, md: 768, lg: 1024, xl: 1280 });
+ *
+ * // Viewport tracking
+ * const viewport = useViewport();
+ * effect(() => console.log(viewport.value.width));
+ *
+ * // Network status
+ * const net = useNetworkStatus();
+ * effect(() => console.log('Online:', net.value.online));
+ *
+ * // Clipboard
+ * await clipboard.write('Hello!');
+ * const text = await clipboard.read();
+ * ```
+ */
+
+// Media query
+export { mediaQuery } from './media-query';
+
+// Breakpoints
+export { breakpoints } from './breakpoints';
+
+// Viewport
+export { useViewport } from './viewport';
+
+// Network
+export { useNetworkStatus } from './network';
+
+// Battery
+export { useBattery } from './battery';
+
+// Geolocation
+export { useGeolocation } from './geolocation';
+
+// Device sensors
+export { useDeviceMotion, useDeviceOrientation } from './device-sensors';
+
+// Clipboard
+export { clipboard } from './clipboard';
+
+// Types
+export type {
+  BatterySignal,
+  BatteryState,
+  BreakpointMap,
+  ClipboardAPI,
+  DeviceMotionSignal,
+  DeviceMotionState,
+  DeviceOrientationSignal,
+  DeviceOrientationState,
+  GeolocationOptions,
+  GeolocationSignal,
+  GeolocationState,
+  MediaSignalHandle,
+  NetworkSignal,
+  NetworkState,
+  ViewportSignal,
+  ViewportState,
+} from './types';

package/src/media/media-query.ts

@@ -0,0 +1,92 @@
+/**
+ * Reactive media query matching.
+ *
+ * Returns a reactive boolean signal that tracks whether a CSS media query matches.
+ *
+ * @module bquery/media
+ */
+
+import { readonly, signal } from '../reactive/index';
+import type { MediaSignalHandle } from './types';
+
+/**
+ * Creates a reactive signal that tracks whether a CSS media query matches.
+ *
+ * Uses `window.matchMedia()` under the hood and automatically updates
+ * when the match state changes (e.g., on window resize, device orientation change).
+ *
+ * @param query - A valid CSS media query string (e.g., `'(min-width: 768px)'`)
+ * @returns A readonly reactive signal that is `true` when the query matches,
+ * plus a `destroy()` method to remove the media query listener
+ *
+ * @example
+ * ```ts
+ * import { mediaQuery } from '@bquery/bquery/media';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const isDark = mediaQuery('(prefers-color-scheme: dark)');
+ * effect(() => {
+ *   document.body.classList.toggle('dark', isDark.value);
+ * });
+ *
+ * const isWide = mediaQuery('(min-width: 1024px)');
+ * effect(() => {
+ *   console.log('Wide screen:', isWide.value);
+ * });
+ * ```
+ */
+export const mediaQuery = (query: string): MediaSignalHandle<boolean> => {
+  const s = signal(false);
+  let cleanup: (() => void) | undefined;
+
+  if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+    try {
+      const mql = window.matchMedia(query);
+      s.value = mql.matches;
+
+      const handler = (e: MediaQueryListEvent): void => {
+        s.value = e.matches;
+      };
+
+      if (typeof mql.addEventListener === 'function') {
+        mql.addEventListener('change', handler);
+        cleanup = () => {
+          mql.removeEventListener('change', handler);
+        };
+      } else if (
+        typeof (
+          mql as MediaQueryList & {
+            addListener?: (listener: (event: MediaQueryListEvent) => void) => void;
+            removeListener?: (listener: (event: MediaQueryListEvent) => void) => void;
+          }
+        ).addListener === 'function'
+      ) {
+        const legacyMql = mql as MediaQueryList & {
+          addListener: (listener: (event: MediaQueryListEvent) => void) => void;
+          removeListener: (listener: (event: MediaQueryListEvent) => void) => void;
+        };
+        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();
+    },
+  });
+
+  return ro;
+};

package/src/media/network.ts

@@ -0,0 +1,115 @@
+/**
+ * Reactive network status.
+ *
+ * Provides a reactive signal tracking the browser's network connectivity
+ * and connection quality via the Network Information API.
+ *
+ * @module bquery/media
+ */
+
+import { readonly, signal } from '../reactive/index';
+import type { NetworkSignal, NetworkState } from './types';
+
+/**
+ * Navigator connection interface for the Network Information API.
+ * @internal
+ */
+interface NavigatorConnection extends EventTarget {
+  effectiveType?: string;
+  downlink?: number;
+  rtt?: number;
+}
+
+/**
+ * Extended Navigator with connection property.
+ * @internal
+ */
+interface NavigatorWithConnection extends Navigator {
+  connection?: NavigatorConnection;
+}
+
+/**
+ * Reads current network state from browser APIs.
+ * @internal
+ */
+const getNetworkState = (): NetworkState => {
+  const online =
+    typeof navigator !== 'undefined' && navigator.onLine !== undefined ? navigator.onLine : true;
+
+  const nav = typeof navigator !== 'undefined' ? (navigator as NavigatorWithConnection) : undefined;
+  const conn = nav?.connection;
+
+  return {
+    online,
+    effectiveType: conn?.effectiveType ?? 'unknown',
+    downlink: conn?.downlink ?? 0,
+    rtt: conn?.rtt ?? 0,
+  };
+};
+
+/**
+ * Returns a reactive signal tracking network connectivity and quality.
+ *
+ * Tracks whether the browser is online/offline and, where supported,
+ * the effective connection type, downlink speed, and round-trip time
+ * via the Network Information API.
+ *
+ * @returns A readonly reactive signal with `{ online, effectiveType, downlink, rtt }`
+ * and a `destroy()` method to remove attached listeners
+ *
+ * @example
+ * ```ts
+ * import { useNetworkStatus } from '@bquery/bquery/media';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const net = useNetworkStatus();
+ * effect(() => {
+ *   if (!net.value.online) {
+ *     console.warn('You are offline!');
+ *   }
+ *   console.log(`Connection: ${net.value.effectiveType}, RTT: ${net.value.rtt}ms`);
+ * });
+ * ```
+ */
+export const useNetworkStatus = (): NetworkSignal => {
+  const s = signal<NetworkState>(getNetworkState());
+  let cleanup: (() => void) | undefined;
+
+  if (typeof window !== 'undefined') {
+    const update = (): void => {
+      s.value = getNetworkState();
+    };
+
+    window.addEventListener('online', update);
+    window.addEventListener('offline', update);
+
+    const nav =
+      typeof navigator !== 'undefined' ? (navigator as NavigatorWithConnection) : undefined;
+    if (nav?.connection && typeof nav.connection.addEventListener === 'function') {
+      nav.connection.addEventListener('change', update);
+    }
+
+    cleanup = () => {
+      window.removeEventListener('online', update);
+      window.removeEventListener('offline', update);
+      if (nav?.connection && typeof nav.connection.removeEventListener === 'function') {
+        nav.connection.removeEventListener('change', update);
+      }
+    };
+  }
+
+  const ro = readonly(s) as NetworkSignal;
+  let destroyed = false;
+  Object.defineProperty(ro, 'destroy', {
+    value(): void {
+      if (destroyed) return;
+      destroyed = true;
+      cleanup?.();
+      s.dispose();
+    },
+    enumerable: false,
+    configurable: true,
+  });
+
+  return ro;
+};

package/src/media/types.ts

@@ -0,0 +1,177 @@
+/**
+ * Type definitions for the bQuery media module.
+ *
+ * @module bquery/media
+ */
+
+import type { ReadonlySignal } from '../reactive/index';
+
+/**
+ * Readonly media signal with an explicit cleanup hook.
+ *
+ * Some media utilities subscribe to browser APIs such as resize events or
+ * geolocation watchers. Call `destroy()` when the signal is no longer needed
+ * to release those underlying subscriptions.
+ */
+export interface MediaSignalHandle<T> extends ReadonlySignal<T> {
+  /** Releases any underlying browser listeners or observers. Safe to call multiple times. */
+  destroy(): void;
+}
+
+/**
+ * Viewport information returned by {@link useViewport}.
+ */
+export interface ViewportState {
+  /** Current viewport width in pixels. */
+  width: number;
+  /** Current viewport height in pixels. */
+  height: number;
+  /** Current orientation: `'portrait'` or `'landscape'`. */
+  orientation: 'portrait' | 'landscape';
+}
+
+/**
+ * Viewport signal handle returned by {@link useViewport}.
+ */
+export type ViewportSignal = MediaSignalHandle<ViewportState>;
+
+/**
+ * Network connection information returned by {@link useNetworkStatus}.
+ */
+export interface NetworkState {
+  /** Whether the browser is online. */
+  online: boolean;
+  /** Effective connection type (e.g., `'4g'`, `'3g'`, `'2g'`, `'slow-2g'`). */
+  effectiveType: string;
+  /** Estimated downlink speed in megabits per second. */
+  downlink: number;
+  /** Estimated round-trip time in milliseconds. */
+  rtt: number;
+}
+
+/**
+ * Network status signal handle returned by {@link useNetworkStatus}.
+ */
+export type NetworkSignal = MediaSignalHandle<NetworkState>;
+
+/**
+ * Battery status information returned by {@link useBattery}.
+ */
+export interface BatteryState {
+  /** Whether the battery API is supported. */
+  supported: boolean;
+  /** Whether the device is charging. */
+  charging: boolean;
+  /** Time in seconds until the battery is fully charged, or `Infinity`. */
+  chargingTime: number;
+  /** Time in seconds until the battery is discharged, or `Infinity`. */
+  dischargingTime: number;
+  /** Battery level as a value between 0 and 1. */
+  level: number;
+}
+
+/**
+ * Battery signal handle returned by {@link useBattery}.
+ */
+export type BatterySignal = MediaSignalHandle<BatteryState>;
+
+/**
+ * Geolocation state returned by {@link useGeolocation}.
+ */
+export interface GeolocationState {
+  /** Whether the geolocation API is supported. */
+  supported: boolean;
+  /** Whether position data is being loaded. */
+  loading: boolean;
+  /** Current latitude, or `null` if unavailable. */
+  latitude: number | null;
+  /** Current longitude, or `null` if unavailable. */
+  longitude: number | null;
+  /** Position accuracy in meters, or `null`. */
+  accuracy: number | null;
+  /** Altitude in meters, or `null`. */
+  altitude: number | null;
+  /** Altitude accuracy in meters, or `null`. */
+  altitudeAccuracy: number | null;
+  /** Heading in degrees, or `null`. */
+  heading: number | null;
+  /** Speed in meters per second, or `null`. */
+  speed: number | null;
+  /** Timestamp of the position, or `null`. */
+  timestamp: number | null;
+  /** Error message, or `null` if no error. */
+  error: string | null;
+}
+
+/**
+ * Geolocation signal handle returned by {@link useGeolocation}.
+ */
+export type GeolocationSignal = MediaSignalHandle<GeolocationState>;
+
+/**
+ * Options for {@link useGeolocation}.
+ */
+export interface GeolocationOptions {
+  /** Whether to enable high-accuracy mode. */
+  enableHighAccuracy?: boolean;
+  /** Maximum age of cached position in milliseconds. */
+  maximumAge?: number;
+  /** Timeout for position requests in milliseconds. */
+  timeout?: number;
+  /** Whether to watch for continuous position updates. */
+  watch?: boolean;
+}
+
+/**
+ * Device motion state returned by {@link useDeviceMotion}.
+ */
+export interface DeviceMotionState {
+  /** Acceleration including gravity (x, y, z). */
+  acceleration: { x: number | null; y: number | null; z: number | null };
+  /** Acceleration including gravity along each axis. */
+  accelerationIncludingGravity: { x: number | null; y: number | null; z: number | null };
+  /** Rotation rate around each axis in degrees per second. */
+  rotationRate: { alpha: number | null; beta: number | null; gamma: number | null };
+  /** Interval in milliseconds between data updates. */
+  interval: number;
+}
+
+/**
+ * Device motion signal handle returned by {@link useDeviceMotion}.
+ */
+export type DeviceMotionSignal = MediaSignalHandle<DeviceMotionState>;
+
+/**
+ * Device orientation state returned by {@link useDeviceOrientation}.
+ */
+export interface DeviceOrientationState {
+  /** Rotation around the z-axis (0–360). */
+  alpha: number | null;
+  /** Rotation around the x-axis (−180–180). */
+  beta: number | null;
+  /** Rotation around the y-axis (−90–90). */
+  gamma: number | null;
+  /** Whether the orientation is absolute. */
+  absolute: boolean;
+}
+
+/**
+ * Device orientation signal handle returned by {@link useDeviceOrientation}.
+ */
+export type DeviceOrientationSignal = MediaSignalHandle<DeviceOrientationState>;
+
+/**
+ * Breakpoint definition map.
+ * Keys are breakpoint names, values are minimum widths in pixels.
+ */
+export type BreakpointMap = Record<string, number>;
+
+/**
+ * Clipboard API wrapper.
+ */
+export interface ClipboardAPI {
+  /** Read text from the clipboard. */
+  read: () => Promise<string>;
+  /** Write text to the clipboard. */
+  write: (text: string) => Promise<void>;
+}

package/src/media/viewport.ts

@@ -0,0 +1,84 @@
+/**
+ * Reactive viewport dimensions.
+ *
+ * Provides a reactive signal tracking the browser viewport's
+ * width, height, and orientation.
+ *
+ * @module bquery/media
+ */
+
+import { readonly, signal } from '../reactive/index';
+import type { ViewportSignal, ViewportState } from './types';
+
+/**
+ * Computes orientation from width and height.
+ * @internal
+ */
+const getOrientation = (w: number, h: number): 'portrait' | 'landscape' =>
+  h >= w ? 'portrait' : 'landscape';
+
+/**
+ * Returns a reactive signal tracking the current viewport dimensions and orientation.
+ *
+ * Updates automatically when the window is resized. Uses `window.innerWidth`
+ * and `window.innerHeight` under the hood.
+ *
+ * @returns A readonly reactive signal with `{ width, height, orientation }`
+ * and a `destroy()` method to remove the resize listener
+ *
+ * @example
+ * ```ts
+ * import { useViewport } from '@bquery/bquery/media';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const viewport = useViewport();
+ * effect(() => {
+ *   console.log(`Viewport: ${viewport.value.width}x${viewport.value.height}`);
+ *   console.log(`Orientation: ${viewport.value.orientation}`);
+ * });
+ * ```
+ */
+export const useViewport = (): ViewportSignal => {
+  const initial: ViewportState = {
+    width: typeof window !== 'undefined' ? window.innerWidth : 0,
+    height: typeof window !== 'undefined' ? window.innerHeight : 0,
+    orientation:
+      typeof window !== 'undefined'
+        ? getOrientation(window.innerWidth, window.innerHeight)
+        : 'portrait',
+  };
+
+  const s = signal<ViewportState>(initial);
+
+  let cleanup: (() => void) | undefined;
+
+  if (typeof window !== 'undefined') {
+    const handler = (): void => {
+      s.value = {
+        width: window.innerWidth,
+        height: window.innerHeight,
+        orientation: getOrientation(window.innerWidth, window.innerHeight),
+      };
+    };
+
+    window.addEventListener('resize', handler);
+    cleanup = () => {
+      window.removeEventListener('resize', handler);
+    };
+  }
+
+  const ro = readonly(s) as ViewportSignal;
+  let destroyed = false;
+  Object.defineProperty(ro, 'destroy', {
+    enumerable: false,
+    configurable: true,
+    value: (): void => {
+      if (destroyed) return;
+      destroyed = true;
+      cleanup?.();
+      s.dispose();
+    },
+  });
+
+  return ro;
+};