react-hook-toolkit 3.0.5 → 5.0.0

package/dist/chunk1516/chunk1718.d.ts

@@ -0,0 +1,324 @@
+import { useEffect, MutableRefObject } from 'react';
+/**
+ * A drop-in replacement for useLayoutEffect that falls back to useEffect on
+ * the server (SSR), preventing the "useLayoutEffect does nothing on the server"
+ * warning in Next.js / Remix environments.
+ */
+export declare const useIsomorphicEffect: typeof useEffect;
+interface UseBooleanReturn {
+    value: boolean;
+    setTrue: () => void;
+    setFalse: () => void;
+    toggle: () => void;
+    set: (v: boolean) => void;
+}
+/**
+ * Manages a boolean state with explicit setTrue, setFalse, toggle, and set helpers.
+ */
+export declare function useBoolean(initialValue?: boolean): UseBooleanReturn;
+/**
+ * Returns a function that, when called, forces the component to re-render.
+ * Useful when external mutable data changes outside of React state.
+ */
+export declare function useForceUpdate(): () => void;
+/**
+ * Returns a Date that updates every `intervalMs` milliseconds (default 1000).
+ * Useful for displaying a live clock.
+ */
+export declare function useClock(intervalMs?: number): Date;
+/**
+ * Like useState but the exposed value only updates after the setter hasn't
+ * been called for `delay` milliseconds.
+ * Returns [debouncedValue, setter, immediateValue].
+ */
+export declare function useDebouncedState<T>(initialValue: T, delay: number): [T, (value: T) => void, T];
+interface UseAnimationFrameReturn {
+    start: () => void;
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Calls `callback` on every animation frame while running.
+ * The callback receives the elapsed time in milliseconds since start.
+ * Returns start/stop controls and an isRunning flag.
+ */
+export declare function useAnimationFrame(callback: (elapsedMs: number) => void): UseAnimationFrameReturn;
+interface UseAsyncCallbackReturn<T> {
+    execute: (...args: any[]) => Promise<void>;
+    data: T | null;
+    error: Error | null;
+    isPending: boolean;
+    reset: () => void;
+}
+/**
+ * Wraps an async function with loading (isPending), data, and error states.
+ * Unlike useAsync, this is imperative — it does NOT run on mount.
+ */
+export declare function useAsyncCallback<T>(asyncFn: (...args: any[]) => Promise<T>): UseAsyncCallbackReturn<T>;
+interface UseAudioAnalyserOptions {
+    fftSize?: number;
+    smoothingTimeConstant?: number;
+}
+interface UseAudioAnalyserReturn {
+    analyser: AnalyserNode | null;
+    frequencyData: Uint8Array;
+    timeDomainData: Uint8Array;
+    audioLevel: number;
+    isListening: boolean;
+    start: () => Promise<void>;
+    stop: () => void;
+    error: Error | null;
+}
+/**
+ * Uses the AnalyserNode API to capture and expose real-time audio frequency
+ * and time-domain data from the user's microphone.
+ */
+export declare function useAudioAnalyser(options?: UseAudioAnalyserOptions): UseAudioAnalyserReturn;
+interface DragAndDropState {
+    isDragging: boolean;
+    isOver: boolean;
+}
+interface UseDragAndDropReturn {
+    containerProps: {
+        onDragOver: (e: React.DragEvent) => void;
+        onDragLeave: (e: React.DragEvent) => void;
+        onDrop: (e: React.DragEvent) => void;
+    };
+    draggableProps: (index: number) => {
+        draggable: boolean;
+        onDragStart: (e: React.DragEvent) => void;
+        onDragEnd: (e: React.DragEvent) => void;
+    };
+    state: DragAndDropState;
+    dragIndex: number | null;
+    dropIndex: number | null;
+}
+/**
+ * Handles drag-and-drop interactions on a container element.
+ * Provides props for both the container and each draggable item.
+ * Calls onDrop(fromIndex, toIndex) when a drop completes.
+ */
+export declare function useDragAndDrop(onDrop?: (fromIndex: number, toIndex: number) => void): UseDragAndDropReturn;
+interface UseFileDropAreaOptions {
+    accept?: string[];
+    maxSize?: number;
+    multiple?: boolean;
+    onDrop?: (files: File[]) => void;
+    onError?: (error: Error) => void;
+}
+interface UseFileDropAreaReturn {
+    dropProps: {
+        onDragOver: (e: React.DragEvent) => void;
+        onDragLeave: (e: React.DragEvent) => void;
+        onDrop: (e: React.DragEvent) => void;
+    };
+    inputProps: {
+        type: 'file';
+        accept: string;
+        multiple: boolean;
+        onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+        style: React.CSSProperties;
+    };
+    files: File[];
+    isOver: boolean;
+    clear: () => void;
+}
+/**
+ * Handles file drag-drop and file-input selection on a drop area element.
+ * Validates file type and size before calling onDrop.
+ */
+export declare function useFileDropArea(options?: UseFileDropAreaOptions): UseFileDropAreaReturn;
+interface GamepadState {
+    gamepads: (Gamepad | null)[];
+    isConnected: boolean;
+}
+/**
+ * Handles Gamepad API connections, disconnections, and button/axis state.
+ * Polls gamepad state via requestAnimationFrame.
+ */
+export declare function useGamepad(): GamepadState;
+interface GridLayoutInfo {
+    columns: number;
+    rows: number;
+}
+/**
+ * Tracks the number of CSS grid columns and rows of a ref'd element.
+ * Updates whenever the element resizes.
+ */
+export declare function useGridLayout(ref: MutableRefObject<HTMLElement | null>): GridLayoutInfo;
+interface UseInViewOptions extends IntersectionObserverInit {
+    once?: boolean;
+}
+interface UseInViewReturn {
+    ref: MutableRefObject<Element | null>;
+    inView: boolean;
+    entry: IntersectionObserverEntry | undefined;
+}
+/**
+ * Convenience wrapper over IntersectionObserver that returns a [ref, inView] pair.
+ * When once is true, stops observing after the element enters the viewport.
+ */
+export declare function useInView(options?: UseInViewOptions): UseInViewReturn;
+type KeyboardHandler = (event: KeyboardEvent) => void;
+type KeyboardBindings = Record<string, KeyboardHandler>;
+/**
+ * Binds keyboard hotkeys to handler functions.
+ * Key format: 'ctrl+s', 'alt+shift+k', 'Escape', 'ArrowUp', etc.
+ */
+export declare function useKeyboard(bindings: KeyboardBindings, element?: MutableRefObject<HTMLElement | null>): void;
+interface MediaDevicesState {
+    stream: MediaStream | null;
+    devices: MediaDeviceInfo[];
+    isLoading: boolean;
+    error: Error | null;
+    hasCamera: boolean;
+    hasMicrophone: boolean;
+}
+interface UseMediaDevicesReturn extends MediaDevicesState {
+    requestAccess: (constraints?: MediaStreamConstraints) => Promise<void>;
+    stopStream: () => void;
+}
+/**
+ * Provides access to the user's camera and microphone via getUserMedia.
+ * Enumerates available devices and exposes the active MediaStream.
+ */
+export declare function useMediaDevices(): UseMediaDevicesReturn;
+/**
+ * Observes DOM mutations on a ref'd element via MutationObserver.
+ * Calls the callback whenever the observed mutations are recorded.
+ */
+export declare function useMutationObserver(ref: MutableRefObject<Element | null>, callback: MutationCallback, options?: MutationObserverInit): void;
+interface NetworkStateInfo {
+    isOnline: boolean;
+    effectiveType: '2g' | '3g' | '4g' | 'slow-2g' | null;
+    downlink: number | null;
+    downlinkMax: number | null;
+    rtt: number | null;
+    saveData: boolean | null;
+    type: string | null;
+    since: Date | null;
+}
+/**
+ * Full NetworkInformation API integration.
+ * Returns online status plus detailed connection metadata when available.
+ * Tracks when the online status last changed via `since`.
+ */
+export declare function useNetworkState(): NetworkStateInfo;
+interface OrientationState {
+    type: OrientationType | null;
+    angle: number;
+    isPortrait: boolean;
+    isLandscape: boolean;
+}
+/**
+ * Tracks the device screen orientation type and angle.
+ * Uses the ScreenOrientation API with a matchMedia fallback.
+ */
+export declare function useOrientation(): OrientationState;
+/**
+ * Returns true when the current browser tab is visible to the user.
+ * Wraps the Page Visibility API (document.visibilityState).
+ */
+export declare function usePageVisibility(): boolean;
+interface PointerInfo {
+    pointerId: number;
+    x: number;
+    y: number;
+    pressure: number;
+    type: string;
+}
+interface UsePointersReturn {
+    pointers: Map<number, PointerInfo>;
+    activeCount: number;
+    containerProps: {
+        onPointerDown: (e: React.PointerEvent) => void;
+        onPointerMove: (e: React.PointerEvent) => void;
+        onPointerUp: (e: React.PointerEvent) => void;
+        onPointerCancel: (e: React.PointerEvent) => void;
+        onPointerLeave: (e: React.PointerEvent) => void;
+    };
+}
+/**
+ * Handles all pointer events at once (mouse, touch, stylus).
+ * Tracks every active pointer by its pointerId.
+ */
+export declare function usePointers(): UsePointersReturn;
+/**
+ * Tracks the full bounding DOMRect of a ref'd element reactively.
+ * Re-measures on scroll and resize using a ResizeObserver.
+ */
+export declare function useRect<T extends Element = Element>(): [MutableRefObject<T | null>, DOMRect | null];
+interface UseScreenCaptureReturn {
+    stream: MediaStream | null;
+    isCapturing: boolean;
+    error: Error | null;
+    start: (options?: DisplayMediaStreamOptions) => Promise<void>;
+    stop: () => void;
+}
+/**
+ * Uses the Screen Capture API (getDisplayMedia) to capture the screen,
+ * a specific window, or the current browser tab.
+ */
+export declare function useScreenCapture(): UseScreenCaptureReturn;
+interface UseScrollThresholdOptions {
+    threshold?: number;
+    element?: MutableRefObject<HTMLElement | null>;
+}
+/**
+ * Returns true when the window (or a given element) has been scrolled
+ * past the specified pixel threshold.
+ */
+export declare function useScrollThreshold(options?: UseScrollThresholdOptions): boolean;
+interface SelectionInfo {
+    text: string;
+    rect: DOMRect | null;
+    isCollapsed: boolean;
+}
+/**
+ * Returns the currently selected text along with its bounding DOMRect.
+ * Updates whenever the user changes their text selection.
+ */
+export declare function useSelection(element?: MutableRefObject<HTMLElement | null>): SelectionInfo;
+type SwipeDirection = 'left' | 'right' | 'up' | 'down' | null;
+interface SwipeState {
+    isSwiping: boolean;
+    direction: SwipeDirection;
+    deltaX: number;
+    deltaY: number;
+    distance: number;
+}
+interface UseSwipingOptions {
+    threshold?: number;
+    onSwipeLeft?: () => void;
+    onSwipeRight?: () => void;
+    onSwipeUp?: () => void;
+    onSwipeDown?: () => void;
+}
+interface UseSwipingReturn {
+    state: SwipeState;
+    handlers: {
+        onTouchStart: (e: React.TouchEvent) => void;
+        onTouchMove: (e: React.TouchEvent) => void;
+        onTouchEnd: (e: React.TouchEvent) => void;
+    };
+}
+/**
+ * Detects swipe gestures (left/right/up/down) on a touch surface.
+ * Fires directional callbacks when the swipe exceeds the pixel threshold.
+ */
+export declare function useSwiping(options?: UseSwipingOptions): UseSwipingReturn;
+interface UseWorkerReturn<T> {
+    postMessage: (data: any) => void;
+    lastMessage: T | null;
+    error: ErrorEvent | null;
+    isReady: boolean;
+    terminate: () => void;
+}
+/**
+ * Runs a function in a Web Worker. The workerFn is serialized and executed
+ * in a background thread. Pass data via postMessage; receive results via lastMessage.
+ *
+ * The workerFn receives a MessageEvent and should call postMessage() to send results back.
+ */
+export declare function useWorker<T = any>(workerFn: (event: MessageEvent) => void): UseWorkerReturn<T>;
+export {};