react-hook-toolkit 4.0.0 → 5.0.0

package/dist/chunk1516/chunk1920.js

@@ -0,0 +1,274 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+/**
+ * Manages client-side pagination state: current page, page size, total pages,
+ * and navigation helpers.
+ */
+export function usePagination(options) {
+    const { total, pageSize: initialSize = 10, initialPage = 1 } = options;
+    const [page, setPage] = useState(initialPage);
+    const [pageSize, setPageSizeState] = useState(initialSize);
+    const totalPages = Math.max(1, Math.ceil(total / pageSize));
+    const clamp = (p) => Math.min(Math.max(p, 1), totalPages);
+    const next = useCallback(() => setPage(p => clamp(p + 1)), [totalPages]);
+    const prev = useCallback(() => setPage(p => clamp(p - 1)), [totalPages]);
+    const goTo = useCallback((p) => setPage(clamp(p)), [totalPages]);
+    const setPageSize = useCallback((size) => {
+        setPageSizeState(size);
+        setPage(1);
+    }, []);
+    // Clamp page when total changes
+    useEffect(() => {
+        setPage(p => clamp(p));
+    }, [total, pageSize]);
+    return {
+        page,
+        pageSize,
+        totalPages,
+        offset: (page - 1) * pageSize,
+        isFirstPage: page === 1,
+        isLastPage: page >= totalPages,
+        next,
+        prev,
+        goTo,
+        setPageSize,
+    };
+}
+/**
+ * Repeatedly calls an async function on a fixed interval.
+ * Returns the latest data/error and start/stop controls.
+ */
+export function usePolling(fetcher, options = {}) {
+    const { interval = 3000, immediate = true, enabled = true } = options;
+    const [data, setData] = useState(null);
+    const [error, setError] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [isPolling, setIsPolling] = useState(false);
+    const timerRef = useRef(null);
+    const fetcherRef = useRef(fetcher);
+    const isMounted = useRef(true);
+    useEffect(() => { fetcherRef.current = fetcher; });
+    useEffect(() => { isMounted.current = true; return () => { isMounted.current = false; }; }, []);
+    const run = useCallback(async () => {
+        setLoading(true);
+        try {
+            const result = await fetcherRef.current();
+            if (isMounted.current) {
+                setData(result);
+                setError(null);
+            }
+        }
+        catch (err) {
+            if (isMounted.current)
+                setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            if (isMounted.current)
+                setLoading(false);
+        }
+    }, []);
+    const start = useCallback(() => {
+        if (timerRef.current)
+            return;
+        setIsPolling(true);
+        if (immediate)
+            run();
+        timerRef.current = setInterval(run, interval);
+    }, [interval, immediate, run]);
+    const stop = useCallback(() => {
+        if (timerRef.current)
+            clearInterval(timerRef.current);
+        timerRef.current = null;
+        setIsPolling(false);
+    }, []);
+    useEffect(() => {
+        if (enabled)
+            start();
+        else
+            stop();
+        return stop;
+    }, [enabled]);
+    return { data, error, loading, start, stop, isPolling };
+}
+/**
+ * Fetches a URL with an AbortController so in-flight requests are automatically
+ * cancelled on unmount or when the URL changes.
+ */
+export function useAbortFetch(url, options) {
+    const [data, setData] = useState(null);
+    const [error, setError] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [tick, setTick] = useState(0);
+    const controllerRef = useRef(null);
+    const abort = useCallback(() => {
+        var _a;
+        (_a = controllerRef.current) === null || _a === void 0 ? void 0 : _a.abort();
+        setLoading(false);
+    }, []);
+    const refetch = useCallback(() => setTick(n => n + 1), []);
+    useEffect(() => {
+        const controller = new AbortController();
+        controllerRef.current = controller;
+        setLoading(true);
+        fetch(url, Object.assign(Object.assign({}, options), { signal: controller.signal }))
+            .then(r => { if (!r.ok)
+            throw new Error(`HTTP ${r.status}`); return r.json(); })
+            .then(d => { setData(d); setError(null); })
+            .catch(err => { if (err.name !== 'AbortError')
+            setError(err instanceof Error ? err : new Error(String(err))); })
+            .finally(() => setLoading(false));
+        return () => controller.abort();
+    }, [url, tick]);
+    return { data, error, loading, abort, refetch };
+}
+/**
+ * A fetch hook that does NOT run on mount. Call the returned fetch() function
+ * to trigger a request imperatively (e.g. on button click).
+ */
+export function useLazyFetch() {
+    const [data, setData] = useState(null);
+    const [error, setError] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const isMounted = useRef(true);
+    useEffect(() => {
+        isMounted.current = true;
+        return () => { isMounted.current = false; };
+    }, []);
+    const doFetch = useCallback(async (url, options) => {
+        if (isMounted.current) {
+            setLoading(true);
+            setError(null);
+        }
+        try {
+            const res = await fetch(url, options);
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const result = await res.json();
+            if (isMounted.current)
+                setData(result);
+        }
+        catch (err) {
+            if (isMounted.current)
+                setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            if (isMounted.current)
+                setLoading(false);
+        }
+    }, []);
+    const reset = useCallback(() => { setData(null); setError(null); setLoading(false); }, []);
+    return { data, error, loading, fetch: doFetch, reset };
+}
+/**
+ * Applies an optimistic value immediately while an async action runs.
+ * Rolls back to the previous value on error.
+ */
+export function useOptimisticUpdate(initialData) {
+    const [data, setData] = useState(initialData);
+    const [isPending, setIsPending] = useState(false);
+    const [error, setError] = useState(null);
+    const previousRef = useRef(initialData);
+    const update = useCallback(async (optimisticValue, action) => {
+        previousRef.current = data;
+        setData(optimisticValue);
+        setIsPending(true);
+        setError(null);
+        try {
+            const confirmed = await action();
+            setData(confirmed);
+        }
+        catch (err) {
+            setData(previousRef.current);
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsPending(false);
+        }
+    }, [data]);
+    const rollback = useCallback(() => {
+        setData(previousRef.current);
+        setError(null);
+    }, []);
+    return { data, isPending, error, update, rollback };
+}
+/**
+ * A stopwatch that tracks elapsed milliseconds with start/stop/reset/lap controls.
+ */
+export function useStopwatch() {
+    const [elapsedMs, setElapsedMs] = useState(0);
+    const [isRunning, setIsRunning] = useState(false);
+    const [laps, setLaps] = useState([]);
+    const startTimeRef = useRef(0);
+    const frameRef = useRef(0);
+    const accumulatedRef = useRef(0);
+    const tick = useCallback(() => {
+        setElapsedMs(accumulatedRef.current + (performance.now() - startTimeRef.current));
+        frameRef.current = requestAnimationFrame(tick);
+    }, []);
+    const start = useCallback(() => {
+        if (isRunning)
+            return;
+        startTimeRef.current = performance.now();
+        setIsRunning(true);
+        frameRef.current = requestAnimationFrame(tick);
+    }, [isRunning, tick]);
+    const stop = useCallback(() => {
+        cancelAnimationFrame(frameRef.current);
+        accumulatedRef.current += performance.now() - startTimeRef.current;
+        setIsRunning(false);
+    }, []);
+    const reset = useCallback(() => {
+        cancelAnimationFrame(frameRef.current);
+        accumulatedRef.current = 0;
+        setElapsedMs(0);
+        setIsRunning(false);
+        setLaps([]);
+    }, []);
+    const lap = useCallback(() => {
+        const current = accumulatedRef.current + (isRunning ? performance.now() - startTimeRef.current : 0);
+        setLaps(prev => [...prev, current]);
+        return current;
+    }, [isRunning]);
+    useEffect(() => () => cancelAnimationFrame(frameRef.current), []);
+    return { elapsedMs, isRunning, start, stop, reset, lap, laps };
+}
+/**
+ * Schedules a callback with requestIdleCallback, falling back to setTimeout
+ * in environments that don't support it (e.g. Safari).
+ */
+export function useIdleCallback(callback, options = {}) {
+    const { timeout = 2000, immediate = true } = options;
+    const callbackRef = useRef(callback);
+    useEffect(() => { callbackRef.current = callback; });
+    useEffect(() => {
+        if (!immediate)
+            return;
+        let id;
+        if (typeof requestIdleCallback !== 'undefined') {
+            id = requestIdleCallback(() => callbackRef.current(), { timeout });
+            return () => cancelIdleCallback(id);
+        }
+        else {
+            const tid = setTimeout(() => callbackRef.current(), timeout);
+            return () => clearTimeout(tid);
+        }
+    }, [immediate, timeout]);
+}
+// ─── useAsyncEffect ───────────────────────────────────────────────────────────
+/**
+ * useEffect wrapper that accepts an async function and handles cleanup safely.
+ * The async function receives an isCancelled() check to guard async operations.
+ */
+export function useAsyncEffect(effect, deps) {
+    useEffect(() => {
+        let cancelled = false;
+        let cleanup;
+        effect(() => cancelled).then(fn => {
+            cleanup = fn;
+        });
+        return () => {
+            cancelled = true;
+            cleanup === null || cleanup === void 0 ? void 0 : cleanup();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, deps);
+}

package/dist/chunk1516/chunk2021.d.ts

@@ -0,0 +1,219 @@
+import { MutableRefObject } from 'react';
+interface UseScrollToTopOptions {
+    behavior?: ScrollBehavior;
+    element?: MutableRefObject<HTMLElement | null>;
+}
+/**
+ * Returns a function that scrolls the window (or a given element) to the top.
+ * Also returns a boolean indicating whether the user has scrolled down enough
+ * that a "back to top" button should be shown (default threshold: 300px).
+ */
+export declare function useScrollToTop(threshold?: number, options?: UseScrollToTopOptions): [boolean, () => void];
+interface UseScrollIntoViewReturn {
+    ref: MutableRefObject<HTMLElement | null>;
+    scrollIntoView: (options?: ScrollIntoViewOptions) => void;
+}
+/**
+ * Returns a ref and a function that scrolls the ref'd element into the viewport.
+ */
+export declare function useScrollIntoView(defaultOptions?: ScrollIntoViewOptions): UseScrollIntoViewReturn;
+interface UseFocusTrapReturn {
+    ref: MutableRefObject<HTMLElement | null>;
+    activate: () => void;
+    deactivate: () => void;
+    isActive: boolean;
+}
+/**
+ * Traps keyboard focus within a container element. Tab/Shift+Tab cycle only
+ * through focusable elements inside the container while the trap is active.
+ * Essential for accessible modals, drawers, and dialogs.
+ */
+export declare function useFocusTrap(initiallyActive?: boolean): UseFocusTrapReturn;
+interface UseVirtualListOptions {
+    itemHeight: number;
+    overscan?: number;
+}
+interface UseVirtualListReturn<T> {
+    containerRef: MutableRefObject<HTMLElement | null>;
+    virtualItems: {
+        item: T;
+        index: number;
+        offsetTop: number;
+    }[];
+    totalHeight: number;
+}
+/**
+ * Windowed (virtual) list rendering. Only renders items visible in the
+ * scroll container plus an overscan buffer. Dramatically reduces DOM nodes for
+ * large lists. Requires a fixed itemHeight.
+ */
+export declare function useVirtualList<T>(items: T[], options: UseVirtualListOptions): UseVirtualListReturn<T>;
+type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/**
+ * Returns the current named breakpoint based on window width.
+ * Uses Tailwind-compatible breakpoints by default.
+ */
+export declare function useBreakpoint(): Breakpoint;
+type ThemeMode = 'light' | 'dark' | 'system';
+interface UseThemeReturn {
+    theme: ThemeMode;
+    resolvedTheme: 'light' | 'dark';
+    setTheme: (theme: ThemeMode) => void;
+    toggleTheme: () => void;
+}
+/**
+ * Manages a light/dark/system theme with persistence to localStorage.
+ * Applies a `data-theme` attribute to `<html>` and resolves the system preference.
+ */
+export declare function useTheme(): UseThemeReturn;
+interface RippleEntry {
+    id: number;
+    x: number;
+    y: number;
+    size: number;
+}
+interface UseRippleReturn {
+    ripples: RippleEntry[];
+    onMouseDown: (e: React.MouseEvent<HTMLElement>) => void;
+}
+/**
+ * Material-style ripple effect. Spread the returned props onto a button/div.
+ * Render each ripple as an absolutely-positioned circular element using the
+ * provided x/y/size values.
+ */
+export declare function useRipple(duration?: number): UseRippleReturn;
+type ToastType = 'info' | 'success' | 'warning' | 'error';
+interface Toast {
+    id: number;
+    message: string;
+    type: ToastType;
+    duration: number;
+}
+interface UseToastReturn {
+    toasts: Toast[];
+    show: (message: string, type?: ToastType, duration?: number) => void;
+    dismiss: (id: number) => void;
+    clear: () => void;
+}
+/**
+ * Manages a list of toast notifications with automatic dismissal after a duration.
+ */
+export declare function useToast(): UseToastReturn;
+interface UseModalReturn {
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+}
+/**
+ * Manages modal open/close state. Automatically restores body scroll on close.
+ */
+export declare function useModal(initialOpen?: boolean): UseModalReturn;
+interface ContextMenuState {
+    isVisible: boolean;
+    x: number;
+    y: number;
+}
+interface UseContextMenuReturn {
+    state: ContextMenuState;
+    targetProps: {
+        onContextMenu: (e: React.MouseEvent) => void;
+    };
+    close: () => void;
+}
+/**
+ * Captures right-click position to display a custom context menu at the cursor.
+ * Closes on outside click or Escape.
+ */
+export declare function useContextMenu(): UseContextMenuReturn;
+interface UseInputReturn<T = string> {
+    value: T;
+    onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+    reset: () => void;
+    set: (value: T) => void;
+    bind: {
+        value: T;
+        onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+    };
+}
+/**
+ * Controlled input hook. Spread `bind` onto any input/textarea/select element.
+ * Returns value, reset, and direct setter.
+ */
+export declare function useInput<T extends string | number | boolean = string>(initialValue: T): UseInputReturn<T>;
+type Validator<T> = (value: T) => string | null;
+interface UseValidationReturn<T> {
+    error: string | null;
+    validate: (value: T) => boolean;
+    reset: () => void;
+}
+/**
+ * Standalone field validation hook. Pass an array of validator functions;
+ * returns the first error message or null.
+ */
+export declare function useValidation<T>(validators: Validator<T>[]): UseValidationReturn<T>;
+interface UseCheckboxReturn {
+    checked: boolean;
+    toggle: () => void;
+    setChecked: (v: boolean) => void;
+    bind: {
+        checked: boolean;
+        onChange: () => void;
+    };
+}
+/**
+ * Controlled checkbox state with a toggle function and spread-ready bind props.
+ */
+export declare function useCheckbox(initialChecked?: boolean): UseCheckboxReturn;
+interface UseSearchReturn<T> {
+    query: string;
+    setQuery: (q: string) => void;
+    results: T[];
+    clear: () => void;
+}
+/**
+ * Filters an array of items using a search query and a key extractor function.
+ * Returns the query state and the filtered results.
+ */
+export declare function useSearch<T>(items: T[], getSearchableText: (item: T) => string, debounceMs?: number): UseSearchReturn<T>;
+interface UseFilterReturn<T> {
+    filtered: T[];
+    setFilter: (fn: (item: T) => boolean) => void;
+    clearFilter: () => void;
+    isFiltered: boolean;
+}
+/**
+ * Filters an array with a predicate function. Returns the filtered list,
+ * a setter for the predicate, and a clear function.
+ */
+export declare function useFilter<T>(items: T[]): UseFilterReturn<T>;
+type SortDirection = 'asc' | 'desc';
+interface UseSortReturn<T> {
+    sorted: T[];
+    sortKey: keyof T | null;
+    direction: SortDirection;
+    setSort: (key: keyof T) => void;
+    clearSort: () => void;
+}
+/**
+ * Sorts an array by a key, toggling direction on repeated calls with the same key.
+ */
+export declare function useSort<T extends Record<string, any>>(items: T[]): UseSortReturn<T>;
+interface UseAutocompleteReturn<T> {
+    query: string;
+    suggestions: T[];
+    selectedIndex: number;
+    isOpen: boolean;
+    inputProps: {
+        value: string;
+        onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+        onKeyDown: (e: React.KeyboardEvent) => void;
+    };
+    select: (item: T) => void;
+    clear: () => void;
+}
+/**
+ * Autocomplete suggestions list with keyboard navigation (Up/Down/Enter/Escape).
+ */
+export declare function useAutocomplete<T>(getSuggestions: (query: string) => T[], onSelect?: (item: T) => void, getLabel?: (item: T) => string): UseAutocompleteReturn<T>;
+export {};