@bquery/bquery 1.8.1 → 1.9.0

package/src/media/observers.ts

@@ -0,0 +1,421 @@
+/**
+ * Reactive wrappers for browser Observer APIs.
+ *
+ * Provides composables for IntersectionObserver, ResizeObserver, and
+ * MutationObserver that expose reactive signals updated on every callback.
+ *
+ * @module bquery/media
+ */
+
+import { readonly, signal } from '../reactive/index';
+import type {
+  IntersectionObserverOptions,
+  IntersectionObserverSignal,
+  IntersectionObserverState,
+  MutationObserverOptions,
+  MutationObserverSignal,
+  MutationObserverState,
+  ResizeObserverOptions,
+  ResizeObserverSignal,
+  ResizeObserverState,
+} from './types';
+
+type ResizeObserverBoxSizeLike = {
+  inlineSize: number;
+  blockSize: number;
+};
+
+const getResizeDimensions = (
+  entry: ResizeObserverEntry,
+  box: ResizeObserverBoxOptions
+): Pick<ResizeObserverState, 'width' | 'height'> => {
+  let boxSize:
+    | ResizeObserverBoxSizeLike
+    | readonly ResizeObserverBoxSizeLike[]
+    | undefined;
+
+  if (box === 'border-box') {
+    boxSize = entry.borderBoxSize;
+  } else if (box === 'device-pixel-content-box') {
+    boxSize = (
+      entry as ResizeObserverEntry & {
+        devicePixelContentBoxSize?:
+          | ResizeObserverBoxSizeLike
+          | readonly ResizeObserverBoxSizeLike[];
+      }
+    ).devicePixelContentBoxSize;
+  } else {
+    boxSize = entry.contentBoxSize;
+  }
+
+  const resolvedBoxSize = Array.isArray(boxSize) ? boxSize[0] : boxSize;
+  if (
+    resolvedBoxSize &&
+    typeof resolvedBoxSize.inlineSize === 'number' &&
+    typeof resolvedBoxSize.blockSize === 'number'
+  ) {
+    return {
+      width: resolvedBoxSize.inlineSize,
+      height: resolvedBoxSize.blockSize,
+    };
+  }
+
+  return {
+    width: entry.contentRect.width,
+    height: entry.contentRect.height,
+  };
+};
+
+// ─── useIntersectionObserver ────────────────────────────────────────────────
+
+/**
+ * Returns a reactive signal tracking element intersection with a root viewport.
+ *
+ * The returned handle exposes `observe()` / `unobserve()` methods so you can
+ * control which elements are watched. If an initial `target` is provided it is
+ * observed immediately.
+ *
+ * @param target  - Optional element or array of elements to observe immediately.
+ * @param options - Standard `IntersectionObserver` init options.
+ * @returns A readonly reactive signal with intersection state, plus `observe`,
+ * `unobserve`, and `destroy` methods.
+ *
+ * @example
+ * ```ts
+ * import { useIntersectionObserver } from '@bquery/bquery/media';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const el = document.querySelector('#lazy-image')!;
+ * const io = useIntersectionObserver(el, { threshold: 0.5 });
+ *
+ * effect(() => {
+ *   if (io.value.isIntersecting) {
+ *     console.log('Element is 50% visible');
+ *   }
+ * });
+ *
+ * // Cleanup when done
+ * io.destroy();
+ * ```
+ */
+export const useIntersectionObserver = (
+  target?: Element | Element[] | null,
+  options?: IntersectionObserverOptions,
+): IntersectionObserverSignal => {
+  const initial: IntersectionObserverState = {
+    isIntersecting: false,
+    intersectionRatio: 0,
+    entry: null,
+  };
+
+  const s = signal<IntersectionObserverState>(initial);
+  let observer: IntersectionObserver | undefined;
+  let destroyed = false;
+
+  if (typeof window !== 'undefined' && typeof IntersectionObserver !== 'undefined') {
+    try {
+      observer = new IntersectionObserver(
+        (entries: IntersectionObserverEntry[]) => {
+          if (destroyed) return;
+          const last = entries[entries.length - 1];
+          if (last) {
+            s.value = {
+              isIntersecting: last.isIntersecting,
+              intersectionRatio: last.intersectionRatio,
+              entry: last,
+            };
+          }
+        },
+        {
+          root: options?.root ?? null,
+          rootMargin: options?.rootMargin ?? '0px',
+          threshold: options?.threshold ?? 0,
+        },
+      );
+
+      // Observe initial targets
+      if (target) {
+        const targets = Array.isArray(target) ? target : [target];
+        for (const el of targets) {
+          observer.observe(el);
+        }
+      }
+    } catch {
+      if (observer) observer.disconnect();
+      observer = undefined;
+    }
+  }
+
+  const ro = readonly(s) as IntersectionObserverSignal;
+
+  Object.defineProperties(ro, {
+    observe: {
+      enumerable: false,
+      configurable: true,
+      value(el: Element): void {
+        if (!destroyed) {
+          try {
+            observer?.observe(el);
+          } catch {}
+        }
+      },
+    },
+    unobserve: {
+      enumerable: false,
+      configurable: true,
+      value(el: Element): void {
+        if (!destroyed) observer?.unobserve(el);
+      },
+    },
+    destroy: {
+      enumerable: false,
+      configurable: true,
+      value(): void {
+        if (destroyed) return;
+        destroyed = true;
+        observer?.disconnect();
+        observer = undefined;
+        s.dispose();
+      },
+    },
+  });
+
+  return ro;
+};
+
+// ─── useResizeObserver ──────────────────────────────────────────────────────
+
+/**
+ * Returns a reactive signal tracking the size of observed elements.
+ *
+ * By default it uses the `content-box`, but you can configure the observed box
+ * via the underlying `ResizeObserver` options (e.g. `{ box: 'border-box' }`).
+ *
+ * The returned handle exposes `observe()` / `unobserve()` methods. If an
+ * initial `target` is provided it is observed immediately.
+ *
+ * @param target  - Optional element or array of elements to observe immediately.
+ * @param options - ResizeObserver options (e.g. `{ box: 'border-box' }`).
+ * @returns A readonly reactive signal with `{ width, height, entry }` derived
+ * from the configured box, plus `observe`, `unobserve`, and `destroy` methods.
+ *
+ * @example
+ * ```ts
+ * import { useResizeObserver } from '@bquery/bquery/media';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const el = document.querySelector('#panel')!;
+ * const size = useResizeObserver(el);
+ *
+ * effect(() => {
+ *   console.log(`Panel size: ${size.value.width}x${size.value.height}`);
+ * });
+ *
+ * size.destroy();
+ * ```
+ */
+export const useResizeObserver = (
+  target?: Element | Element[] | null,
+  options?: ResizeObserverOptions,
+): ResizeObserverSignal => {
+  const initial: ResizeObserverState = {
+    width: 0,
+    height: 0,
+    entry: null,
+  };
+
+  const s = signal<ResizeObserverState>(initial);
+  let observer: ResizeObserver | undefined;
+  let destroyed = false;
+  const box = options?.box ?? 'content-box';
+  const observeOptions = options?.box ? { box: options.box } : undefined;
+
+  if (typeof window !== 'undefined' && typeof ResizeObserver !== 'undefined') {
+    try {
+      observer = new ResizeObserver((entries: ResizeObserverEntry[]) => {
+        if (destroyed) return;
+        const last = entries[entries.length - 1];
+        if (last) {
+          const { width, height } = getResizeDimensions(last, box);
+          s.value = {
+            width,
+            height,
+            entry: last,
+          };
+        }
+      });
+
+      // Observe initial targets
+      if (target) {
+        const targets = Array.isArray(target) ? target : [target];
+        for (const el of targets) {
+          observer.observe(el, observeOptions);
+        }
+      }
+    } catch {
+      if (observer) observer.disconnect();
+      observer = undefined;
+    }
+  }
+
+  const ro = readonly(s) as ResizeObserverSignal;
+
+  Object.defineProperties(ro, {
+    observe: {
+      enumerable: false,
+      configurable: true,
+      value(el: Element): void {
+        if (!destroyed) {
+          try {
+            observer?.observe(el, observeOptions);
+          } catch {}
+        }
+      },
+    },
+    unobserve: {
+      enumerable: false,
+      configurable: true,
+      value(el: Element): void {
+        if (!destroyed) observer?.unobserve(el);
+      },
+    },
+    destroy: {
+      enumerable: false,
+      configurable: true,
+      value(): void {
+        if (destroyed) return;
+        destroyed = true;
+        observer?.disconnect();
+        observer = undefined;
+        s.dispose();
+      },
+    },
+  });
+
+  return ro;
+};
+
+// ─── useMutationObserver ────────────────────────────────────────────────────
+
+/**
+ * Returns a reactive signal tracking DOM mutations on observed nodes.
+ *
+ * The returned handle exposes `observe()` and `takeRecords()` for manual
+ * lifecycle control. If an initial `target` is provided it is observed
+ * immediately.
+ *
+ * @param target  - Optional node to observe immediately.
+ * @param options - MutationObserver init options. Defaults to `{ attributes: true }`.
+ * @returns A readonly reactive signal with `{ mutations, count }`, plus
+ * `observe`, `takeRecords`, and `destroy` methods.
+ *
+ * @example
+ * ```ts
+ * import { useMutationObserver } from '@bquery/bquery/media';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const el = document.querySelector('#dynamic-content')!;
+ * const mo = useMutationObserver(el, { childList: true, subtree: true });
+ *
+ * effect(() => {
+ *   console.log(`${mo.value.count} mutation batches observed`);
+ * });
+ *
+ * mo.destroy();
+ * ```
+ */
+export const useMutationObserver = (
+  target?: Node | null,
+  options?: MutationObserverOptions,
+): MutationObserverSignal => {
+  const initial: MutationObserverState = {
+    mutations: [],
+    count: 0,
+  };
+
+  const s = signal<MutationObserverState>(initial);
+  let observer: MutationObserver | undefined;
+  let destroyed = false;
+  let totalCount = 0;
+
+  const resolvedOptions: MutationObserverInit = {
+    attributes: options?.attributes ?? true,
+    childList: options?.childList ?? false,
+    characterData: options?.characterData ?? false,
+    subtree: options?.subtree ?? false,
+    attributeOldValue: options?.attributeOldValue ?? false,
+    characterDataOldValue: options?.characterDataOldValue ?? false,
+    ...(options && options.attributeFilter !== undefined
+      ? { attributeFilter: options.attributeFilter }
+      : {}),
+  };
+
+  if (!resolvedOptions.attributes && !resolvedOptions.childList && !resolvedOptions.characterData) {
+    resolvedOptions.attributes = true;
+  }
+
+  if (!resolvedOptions.attributes) {
+    resolvedOptions.attributeOldValue = false;
+    delete resolvedOptions.attributeFilter;
+  }
+
+  if (!resolvedOptions.characterData) {
+    resolvedOptions.characterDataOldValue = false;
+  }
+
+  if (typeof window !== 'undefined' && typeof MutationObserver !== 'undefined') {
+    try {
+      observer = new MutationObserver((mutations: MutationRecord[]) => {
+        if (destroyed) return;
+        totalCount += 1;
+        s.value = {
+          mutations,
+          count: totalCount,
+        };
+      });
+
+      if (target) {
+        observer.observe(target, resolvedOptions);
+      }
+    } catch {
+      if (observer) observer.disconnect();
+      observer = undefined;
+    }
+  }
+
+  const ro = readonly(s) as MutationObserverSignal;
+
+  Object.defineProperties(ro, {
+    observe: {
+      enumerable: false,
+      configurable: true,
+      value(node: Node): void {
+        if (!destroyed) {
+          try {
+            observer?.observe(node, resolvedOptions);
+          } catch {}
+        }
+      },
+    },
+    takeRecords: {
+      enumerable: false,
+      configurable: true,
+      value(): MutationRecord[] {
+        return observer?.takeRecords() ?? [];
+      },
+    },
+    destroy: {
+      enumerable: false,
+      configurable: true,
+      value(): void {
+        if (destroyed) return;
+        destroyed = true;
+        observer?.disconnect();
+        observer = undefined;
+        s.dispose();
+      },
+    },
+  });
+
+  return ro;
+};

package/src/media/types.ts

@@ -175,3 +175,139 @@ export interface ClipboardAPI {
   /** Write text to the clipboard. */
   write: (text: string) => Promise<void>;
 }
+
+// ─── Observer Composable Types ───────────────────────────────────────────────
+
+/**
+ * Options for {@link useIntersectionObserver}.
+ */
+export interface IntersectionObserverOptions {
+  /**
+   * Root element or document to use as the viewport.
+   * Defaults to the browser viewport when `null` or omitted.
+   */
+  root?: Element | Document | null;
+  /** Margin around the root, using CSS margin syntax (e.g. `'10px 20px'`). */
+  rootMargin?: string;
+  /**
+   * Thresholds at which the callback fires.
+   * A single number or an array of numbers between 0 and 1.
+   */
+  threshold?: number | number[];
+}
+
+/**
+ * State tracked by {@link useIntersectionObserver}.
+ *
+ * Reflects the most recent {@link IntersectionObserverEntry} reported by the
+ * underlying `IntersectionObserver` callback, not an aggregate across all
+ * observed targets.
+ */
+export interface IntersectionObserverState {
+  /**
+   * Whether the most recently reported entry is intersecting.
+   *
+   * This is equivalent to `entry?.isIntersecting ?? false` and does not
+   * represent an aggregate across all observed targets.
+   */
+  isIntersecting: boolean;
+  /**
+   * The intersection ratio (0–1) from the most recent entry.
+   *
+   * This is equivalent to `entry?.intersectionRatio ?? 0`.
+   */
+  intersectionRatio: number;
+  /** The most recent `IntersectionObserverEntry`, or `null` before the first callback. */
+  entry: IntersectionObserverEntry | null;
+}
+
+/**
+ * Extended handle returned by {@link useIntersectionObserver}.
+ *
+ * In addition to the reactive signal, exposes `observe()` and `unobserve()`
+ * so elements can be added or removed after creation.
+ */
+export interface IntersectionObserverSignal extends MediaSignalHandle<IntersectionObserverState> {
+  /** Start observing the given element. */
+  observe(target: Element): void;
+  /** Stop observing the given element. */
+  unobserve(target: Element): void;
+}
+
+/**
+ * Options for {@link useResizeObserver}.
+ */
+export interface ResizeObserverOptions {
+  /**
+   * Which CSS box model to observe.
+   * @default 'content-box'
+   */
+  box?: ResizeObserverBoxOptions;
+}
+
+/**
+ * State tracked by {@link useResizeObserver}.
+ */
+export interface ResizeObserverState {
+  /** Observed box width of the element in pixels (based on the configured `box`). */
+  width: number;
+  /** Observed box height of the element in pixels (based on the configured `box`). */
+  height: number;
+  /** The most recent `ResizeObserverEntry`, or `null` before the first callback. */
+  entry: ResizeObserverEntry | null;
+}
+
+/**
+ * Extended handle returned by {@link useResizeObserver}.
+ *
+ * Exposes `observe()` and `unobserve()` so elements can be added or removed
+ * after creation.
+ */
+export interface ResizeObserverSignal extends MediaSignalHandle<ResizeObserverState> {
+  /** Start observing the given element. */
+  observe(target: Element): void;
+  /** Stop observing the given element. */
+  unobserve(target: Element): void;
+}
+
+/**
+ * Options for {@link useMutationObserver}.
+ */
+export interface MutationObserverOptions {
+  /** Observe attribute changes. @default true */
+  attributes?: boolean;
+  /** Observe child list changes. @default false */
+  childList?: boolean;
+  /** Observe character data changes. @default false */
+  characterData?: boolean;
+  /** Observe the entire subtree. @default false */
+  subtree?: boolean;
+  /** Record previous attribute values. @default false */
+  attributeOldValue?: boolean;
+  /** Record previous character data values. @default false */
+  characterDataOldValue?: boolean;
+  /** Filter observed attributes to this list. */
+  attributeFilter?: string[];
+}
+
+/**
+ * State tracked by {@link useMutationObserver}.
+ */
+export interface MutationObserverState {
+  /** The list of mutations from the most recent callback. */
+  mutations: MutationRecord[];
+  /** Total number of mutation callbacks received. */
+  count: number;
+}
+
+/**
+ * Extended handle returned by {@link useMutationObserver}.
+ *
+ * Exposes `observe()`, `takeRecords()`, and `destroy()` for manual lifecycle control.
+ */
+export interface MutationObserverSignal extends MediaSignalHandle<MutationObserverState> {
+  /** Start observing mutations on the given target. Uses the options from construction time. */
+  observe(target: Node): void;
+  /** Take and clear any pending mutation records. */
+  takeRecords(): MutationRecord[];
+}

package/src/reactive/index.ts

@@ -40,6 +40,8 @@ export {
   useWebSocketChannel,
   untrack,
   watch,
+  watchDebounce,
+  watchThrottle,
 } from './signal';
 
 export type {
@@ -90,6 +92,7 @@ export type {
   UseWebSocketChannelReturn,
   UseWebSocketOptions,
   UseWebSocketReturn,
+  WatchOptions,
   WebSocketHeartbeatConfig,
   WebSocketReconnectConfig,
   WebSocketSerializer,

package/src/reactive/signal.ts

@@ -26,7 +26,7 @@ export { effectScope, getCurrentScope, onScopeDispose } from './scope';
 export { isComputed, isSignal } from './type-guards';
 export { toValue } from './to-value';
 export { untrack } from './untrack';
-export { watch } from './watch';
+export { watch, watchDebounce, watchThrottle } from './watch';
 export { useEventSource, useWebSocket, useWebSocketChannel } from './websocket';
 
 export type { CleanupFn, Observer } from './internals';
@@ -57,6 +57,7 @@ export type {
   UsePaginatedFetchOptions,
 } from './pagination';
 export type { PollingState, UsePollingOptions } from './polling';
+export type { WatchOptions } from './watch';
 export type {
   IdExtractor,
   ResourceListActions,