react-hook-granth/dist/index.d.ts

A collection of custom React hooks for efficient state management and UI logic.

import { RefObject } from 'react';

declare const useCounter: (initialValue?: number | null) => {
    count: number;
    increment: () => void;
    decrement: () => void;
    reset: () => void;
};

/**
 * Custom hook to sync state with localStorage.
 * @param key - localStorage key
 * @param initialValue - Initial value or function returning initial value
 * @returns Tuple of [storedValue, setStoredValue]
 */
declare function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T) => void];

/**
 * Sync state with sessionStorage.
 * @param key - sessionStorage key
 * @param initialValue - Initial value
 * @returns Tuple of [value, setValue]
 */
declare function useSessionStorage<T>(key: string, initialValue: T): [T, (value: T) => void];

/**
 * Store the previous value of a state or prop.
 * @param value - The current value
 * @returns The previous value
 */
declare function usePrevious<T>(value: T): T | undefined;

interface UseDebounceOptions {
    leading?: boolean;
    trailing?: boolean;
    maxWait?: number;
    onDebounce?: (value: any) => void;
    onCancel?: () => void;
}
interface UseDebounceReturn<T> {
    debouncedValue: T;
    cancel: () => void;
    flush: () => void;
    isPending: boolean;
}
declare function useDebounce<T>(value: T, delay?: number, options?: UseDebounceOptions): UseDebounceReturn<T>;

/**
 * Throttle a function to only run once every specified delay.
 * @param callback - The function to throttle
 * @param delay - Delay in milliseconds
 * @returns Throttled version of the callback
 */
declare function useThrottle<T extends (...args: any[]) => any>(callback: T, delay: number): (...args: Parameters<T>) => void;

interface UseTimeoutReturn {
    clear: () => void;
    reset: () => void;
}
/**
 * Run a function after a delay. Supports cancel and reset.
 * @param callback - Function to run after delay
 * @param delay - Delay in milliseconds
 * @returns Object with clear and reset functions
 */
declare function useTimeout(callback: () => void, delay: number): UseTimeoutReturn;

/**
 * Detect if user is idle after a given timeout.
 * @param timeout - Timeout in milliseconds (default: 3000)
 * @returns True if user is idle
 */
declare function useIdle(timeout?: number): boolean;

/**
 * Hook to detect clicks outside of a specified element.
 * @param handler - Callback to run on outside click.
 * @returns Ref to attach to your target element.
 */
declare function useClickOutside<T extends HTMLElement = HTMLElement>(handler: (event: Event) => void): React.RefObject<T>;

interface UseCopyToClipboardOptions {
    resetTime?: number;
    onSuccess?: () => void;
    onError?: (error: Error) => void;
}
interface UseCopyToClipboardReturn {
    isCopied: boolean;
    copy: (text: string) => Promise<boolean>;
    reset: () => void;
}
/**
 * Custom hook to copy text to clipboard with enhanced features.
 * @param options - Configuration options for the hook
 * @returns Object with isCopied state, copy function, and reset function
 */
declare function useCopyToClipboard(options?: UseCopyToClipboardOptions): UseCopyToClipboardReturn;

interface WindowSize {
    width: number;
    height: number;
}
/**
 * Track the current window size.
 * @returns The current window dimensions
 */
declare function useWindowSize(): WindowSize;

/**
 * Custom hook to match a CSS media query.
 * @param query - The media query string
 * @returns Whether the query currently matches
 */
declare function useMediaQuery(query: string): boolean;

/**
 * Custom hook to track online/offline status.
 * @returns True if online, false if offline
 */
declare function useOnlineStatus(): boolean;

interface NetworkSpeed {
    connectionType: string;
    downlink: number;
}
/**
 * Track the network speed and connection type.
 * @returns Network connection details
 */
declare function useNetworkSpeed(): NetworkSpeed;

interface ScrollPosition {
    x: number;
    y: number;
}
/**
 * Track the scroll position of the window.
 * @returns The current scroll position (x, y)
 */
declare function useScrollPosition(): ScrollPosition;

interface ScrollIntoViewOptions {
    behavior?: ScrollBehavior;
    block?: ScrollLogicalPosition;
    inline?: ScrollLogicalPosition;
}
interface ScrollError {
    message: string;
}
interface UseScrollIntoViewReturn {
    hasScrolled: boolean;
    error: ScrollError | null;
    scrollToElement: () => void;
}
/**
 * useScrollIntoView Hook
 *
 * This hook automatically scrolls an element into view when any specified trigger in an array changes.
 * It also provides manual control, improved error handling, and optimizations.
 *
 * @param ref - The React ref object pointing to the target element.
 * @param triggers - An array of state variables that trigger the scroll effect when any of them change.
 * @param delay - The delay (in milliseconds) before scrolling occurs.
 * @param options - ScrollIntoView options.
 * @param onScrollComplete - A callback function executed after scrolling is completed.
 *
 * @returns An object containing:
 *   - hasScrolled: Indicates whether the scrolling has completed.
 *   - error: An error object if the ref is invalid.
 *   - scrollToElement: A function to manually trigger scrolling.
 */
declare const useScrollIntoView: <T extends HTMLElement = HTMLElement>(ref: RefObject<T>, triggers?: unknown[], delay?: number, options?: ScrollIntoViewOptions, onScrollComplete?: () => void) => UseScrollIntoViewReturn;

/**
 * Set the document title dynamically.
 * @param title - The title to set for the document.
 */
declare function useDocumentTitle(title: string): void;

interface Bounds {
    width: number;
    height: number;
}
/**
 * Measure the size of a DOM element.
 * @returns Tuple of [ref, bounds]
 */
declare function useMeasure(): [React.RefObject<HTMLElement>, Bounds];

export { useClickOutside, useCopyToClipboard, useCounter, useDebounce, useDocumentTitle, useIdle, useLocalStorage, useMeasure, useMediaQuery, useNetworkSpeed, useOnlineStatus, usePrevious, useScrollIntoView, useScrollPosition, useSessionStorage, useThrottle, useTimeout, useWindowSize };