react-hook-toolkit 3.0.5 → 5.0.0

package/dist/chunk1516/chunk1617.d.ts

@@ -0,0 +1,190 @@
+import { MutableRefObject } from 'react';
+interface UseCounterOptions {
+    min?: number;
+    max?: number;
+    step?: number;
+}
+interface UseCounterReturn {
+    count: number;
+    increment: () => void;
+    decrement: () => void;
+    reset: () => void;
+    set: (value: number) => void;
+}
+/**
+ * Manages a numeric counter with optional min/max bounds and a configurable step.
+ */
+export declare function useCounter(initialValue?: number, options?: UseCounterOptions): UseCounterReturn;
+interface UseMapReturn<K, V> {
+    map: Map<K, V>;
+    set: (key: K, value: V) => void;
+    get: (key: K) => V | undefined;
+    has: (key: K) => boolean;
+    delete: (key: K) => void;
+    clear: () => void;
+    size: number;
+}
+/**
+ * Manages a Map data structure as React state with stable action methods.
+ */
+export declare function useMap<K, V>(initialEntries?: Iterable<[K, V]>): UseMapReturn<K, V>;
+interface UseSetReturn<T> {
+    set: Set<T>;
+    add: (value: T) => void;
+    has: (value: T) => boolean;
+    delete: (value: T) => void;
+    toggle: (value: T) => void;
+    clear: () => void;
+    size: number;
+}
+/**
+ * Manages a Set data structure as React state with stable action methods.
+ */
+export declare function useSet<T>(initialValues?: Iterable<T>): UseSetReturn<T>;
+interface UseQueueReturn<T> {
+    queue: T[];
+    enqueue: (item: T) => void;
+    dequeue: () => T | undefined;
+    peek: () => T | undefined;
+    clear: () => void;
+    size: number;
+    isEmpty: boolean;
+}
+/**
+ * Manages a FIFO queue as React state.
+ */
+export declare function useQueue<T>(initialItems?: T[]): UseQueueReturn<T>;
+interface UseStackReturn<T> {
+    stack: T[];
+    push: (item: T) => void;
+    pop: () => T | undefined;
+    peek: () => T | undefined;
+    clear: () => void;
+    size: number;
+    isEmpty: boolean;
+}
+/**
+ * Manages a LIFO stack as React state.
+ */
+export declare function useStack<T>(initialItems?: T[]): UseStackReturn<T>;
+interface UseFocusReturn {
+    ref: MutableRefObject<HTMLElement | null>;
+    isFocused: boolean;
+    focus: () => void;
+    blur: () => void;
+}
+/**
+ * Tracks focus state of a DOM element via a ref.
+ */
+export declare function useFocus(): UseFocusReturn;
+/**
+ * Tracks whether a DOM element is being hovered via a ref.
+ * Returns a [ref, isHovered] tuple.
+ */
+export declare function useHover<T extends HTMLElement = HTMLElement>(): [MutableRefObject<T | null>, boolean];
+interface UseIntersectionObserverOptions extends IntersectionObserverInit {
+    freezeOnceVisible?: boolean;
+}
+/**
+ * Observes whether a ref'd element is intersecting the viewport (or a given root).
+ * When freezeOnceVisible is true the entry is frozen after first intersection.
+ */
+export declare function useIntersectionObserver(elementRef: MutableRefObject<Element | null>, options?: UseIntersectionObserverOptions): IntersectionObserverEntry | undefined;
+interface DOMRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+interface UseMeasureReturn {
+    ref: MutableRefObject<HTMLElement | null>;
+    rect: DOMRect;
+}
+/**
+ * Measures the bounding rect of a DOM element, updating on resize.
+ */
+export declare function useMeasure(): UseMeasureReturn;
+interface NetworkState {
+    isOnline: boolean;
+    effectiveType: string | null;
+    downlink: number | null;
+    rtt: number | null;
+    saveData: boolean | null;
+    type: string | null;
+}
+/**
+ * Returns detailed network connection information including online status,
+ * effective connection type, downlink speed, and RTT.
+ */
+export declare function useNetwork(): NetworkState;
+/**
+ * Reads and writes the URL hash (fragment) as state.
+ * Returns [hash, setHash] where hash does not include the leading '#'.
+ */
+export declare function useHash(): [string, (hash: string) => void];
+/**
+ * Returns a ref that always holds the most recent value.
+ * Useful for reading the latest prop/state inside a callback without
+ * adding it to the dependency array.
+ */
+export declare function useLatest<T>(value: T): MutableRefObject<T>;
+/**
+ * Returns a stable callback reference that always delegates to the latest
+ * version of the provided function. Safe to pass to event listeners without
+ * causing unnecessary re-subscriptions.
+ */
+export declare function useEventCallback<T extends (...args: any[]) => any>(fn: T): T;
+/**
+ * A drop-in replacement for useState that suppresses state updates after the
+ * component has unmounted, preventing "Can't perform a React state update on an
+ * unmounted component" warnings.
+ */
+export declare function useSafeState<T>(initialState: T | (() => T)): [T, React.Dispatch<React.SetStateAction<T>>];
+/**
+ * Identical to useState but batches updates via requestAnimationFrame,
+ * reducing the number of renders for rapidly changing values (e.g. mouse
+ * position, scroll events).
+ */
+export declare function useRafState<T>(initialState: T | (() => T)): [T, React.Dispatch<React.SetStateAction<T>>];
+interface UseTitleOptions {
+    restoreOnUnmount?: boolean;
+}
+/**
+ * Sets the document title reactively. Optionally restores the previous title
+ * on unmount.
+ */
+export declare function useTitle(title: string, options?: UseTitleOptions): void;
+/**
+ * Dynamically updates the page favicon by href. Useful for notifications or
+ * theme changes (e.g. switching between light/dark favicon).
+ */
+export declare function useFavicon(href: string): void;
+/**
+ * Debug hook that logs which prop/state changes triggered the last render.
+ * Only active in development; no-ops in production.
+ * Pass a label and the component's props/state object.
+ */
+export declare function useWhyDidYouUpdate(name: string, props: Record<string, any>): void;
+interface UseFullscreenReturn {
+    ref: MutableRefObject<HTMLElement | null>;
+    isFullscreen: boolean;
+    enter: () => Promise<void>;
+    exit: () => Promise<void>;
+    toggle: () => Promise<void>;
+    isSupported: boolean;
+}
+/**
+ * Manages the Fullscreen API for a specific element (or the whole document when
+ * no ref target is provided). Tracks fullscreen state reactively.
+ */
+export declare function useFullscreen(): UseFullscreenReturn;
+/**
+ * Logs the component name and any values passed on every render.
+ * Only logs in development mode.
+ */
+export declare function useLogger(name: string, ...values: any[]): void;
+export {};

package/dist/chunk1516/chunk1617.js

@@ -0,0 +1,408 @@
+import { useState, useEffect, useCallback, useRef, useLayoutEffect } from 'react';
+/**
+ * Manages a numeric counter with optional min/max bounds and a configurable step.
+ */
+export function useCounter(initialValue = 0, options = {}) {
+    const { min = -Infinity, max = Infinity, step = 1 } = options;
+    const [count, setCount] = useState(() => Math.min(Math.max(initialValue, min), max));
+    const increment = useCallback(() => setCount(prev => Math.min(prev + step, max)), [max, step]);
+    const decrement = useCallback(() => setCount(prev => Math.max(prev - step, min)), [min, step]);
+    const reset = useCallback(() => setCount(Math.min(Math.max(initialValue, min), max)), [initialValue, min, max]);
+    const set = useCallback((value) => setCount(Math.min(Math.max(value, min), max)), [min, max]);
+    return { count, increment, decrement, reset, set };
+}
+/**
+ * Manages a Map data structure as React state with stable action methods.
+ */
+export function useMap(initialEntries = []) {
+    const [map, setMap] = useState(() => new Map(initialEntries));
+    const set = useCallback((key, value) => {
+        setMap(prev => new Map(prev).set(key, value));
+    }, []);
+    const deleteKey = useCallback((key) => {
+        setMap(prev => {
+            const next = new Map(prev);
+            next.delete(key);
+            return next;
+        });
+    }, []);
+    const clear = useCallback(() => setMap(new Map()), []);
+    const get = useCallback((key) => map.get(key), [map]);
+    const has = useCallback((key) => map.has(key), [map]);
+    return { map, set, get, has, delete: deleteKey, clear, size: map.size };
+}
+/**
+ * Manages a Set data structure as React state with stable action methods.
+ */
+export function useSet(initialValues = []) {
+    const [set, setSet] = useState(() => new Set(initialValues));
+    const add = useCallback((value) => {
+        setSet(prev => new Set(prev).add(value));
+    }, []);
+    const deleteValue = useCallback((value) => {
+        setSet(prev => {
+            const next = new Set(prev);
+            next.delete(value);
+            return next;
+        });
+    }, []);
+    const toggle = useCallback((value) => {
+        setSet(prev => {
+            const next = new Set(prev);
+            if (next.has(value))
+                next.delete(value);
+            else
+                next.add(value);
+            return next;
+        });
+    }, []);
+    const clear = useCallback(() => setSet(new Set()), []);
+    const has = useCallback((value) => set.has(value), [set]);
+    return { set, add, has, delete: deleteValue, toggle, clear, size: set.size };
+}
+/**
+ * Manages a FIFO queue as React state.
+ */
+export function useQueue(initialItems = []) {
+    const [queue, setQueue] = useState(initialItems);
+    const enqueue = useCallback((item) => {
+        setQueue(prev => [...prev, item]);
+    }, []);
+    const dequeue = useCallback(() => {
+        let removed;
+        setQueue(prev => {
+            if (prev.length === 0)
+                return prev;
+            [removed] = prev;
+            return prev.slice(1);
+        });
+        return removed;
+    }, []);
+    const peek = useCallback(() => queue[0], [queue]);
+    const clear = useCallback(() => setQueue([]), []);
+    return { queue, enqueue, dequeue, peek, clear, size: queue.length, isEmpty: queue.length === 0 };
+}
+/**
+ * Manages a LIFO stack as React state.
+ */
+export function useStack(initialItems = []) {
+    const [stack, setStack] = useState(initialItems);
+    const push = useCallback((item) => {
+        setStack(prev => [...prev, item]);
+    }, []);
+    const pop = useCallback(() => {
+        let removed;
+        setStack(prev => {
+            if (prev.length === 0)
+                return prev;
+            removed = prev[prev.length - 1];
+            return prev.slice(0, -1);
+        });
+        return removed;
+    }, []);
+    const peek = useCallback(() => stack[stack.length - 1], [stack]);
+    const clear = useCallback(() => setStack([]), []);
+    return { stack, push, pop, peek, clear, size: stack.length, isEmpty: stack.length === 0 };
+}
+/**
+ * Tracks focus state of a DOM element via a ref.
+ */
+export function useFocus() {
+    const ref = useRef(null);
+    const [isFocused, setIsFocused] = useState(false);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const onFocus = () => setIsFocused(true);
+        const onBlur = () => setIsFocused(false);
+        el.addEventListener('focus', onFocus);
+        el.addEventListener('blur', onBlur);
+        return () => {
+            el.removeEventListener('focus', onFocus);
+            el.removeEventListener('blur', onBlur);
+        };
+    });
+    const focus = useCallback(() => { var _a; return (_a = ref.current) === null || _a === void 0 ? void 0 : _a.focus(); }, []);
+    const blur = useCallback(() => { var _a; return (_a = ref.current) === null || _a === void 0 ? void 0 : _a.blur(); }, []);
+    return { ref, isFocused, focus, blur };
+}
+// ─── useHover ─────────────────────────────────────────────────────────────────
+/**
+ * Tracks whether a DOM element is being hovered via a ref.
+ * Returns a [ref, isHovered] tuple.
+ */
+export function useHover() {
+    const ref = useRef(null);
+    const [isHovered, setIsHovered] = useState(false);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const onEnter = () => setIsHovered(true);
+        const onLeave = () => setIsHovered(false);
+        el.addEventListener('mouseenter', onEnter);
+        el.addEventListener('mouseleave', onLeave);
+        return () => {
+            el.removeEventListener('mouseenter', onEnter);
+            el.removeEventListener('mouseleave', onLeave);
+        };
+    });
+    return [ref, isHovered];
+}
+/**
+ * Observes whether a ref'd element is intersecting the viewport (or a given root).
+ * When freezeOnceVisible is true the entry is frozen after first intersection.
+ */
+export function useIntersectionObserver(elementRef, options = {}) {
+    const { threshold = 0, root = null, rootMargin = '0%', freezeOnceVisible = false } = options;
+    const [entry, setEntry] = useState();
+    const frozen = (entry === null || entry === void 0 ? void 0 : entry.isIntersecting) && freezeOnceVisible;
+    useEffect(() => {
+        const el = elementRef === null || elementRef === void 0 ? void 0 : elementRef.current;
+        if (frozen || !el || !('IntersectionObserver' in window))
+            return;
+        const observer = new IntersectionObserver(([newEntry]) => setEntry(newEntry), { threshold, root, rootMargin });
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, [elementRef, threshold, root, rootMargin, frozen]);
+    return entry;
+}
+const defaultRect = { x: 0, y: 0, width: 0, height: 0, top: 0, right: 0, bottom: 0, left: 0 };
+/**
+ * Measures the bounding rect of a DOM element, updating on resize.
+ */
+export function useMeasure() {
+    const ref = useRef(null);
+    const [rect, setRect] = useState(defaultRect);
+    useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const update = () => {
+            const r = el.getBoundingClientRect();
+            setRect({ x: r.x, y: r.y, width: r.width, height: r.height, top: r.top, right: r.right, bottom: r.bottom, left: r.left });
+        };
+        update();
+        const observer = new ResizeObserver(update);
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, []);
+    return { ref, rect };
+}
+/**
+ * Returns detailed network connection information including online status,
+ * effective connection type, downlink speed, and RTT.
+ */
+export function useNetwork() {
+    const getState = () => {
+        var _a, _b, _c, _d, _e;
+        const conn = navigator.connection || navigator.mozConnection || navigator.webkitConnection;
+        return {
+            isOnline: navigator.onLine,
+            effectiveType: (_a = conn === null || conn === void 0 ? void 0 : conn.effectiveType) !== null && _a !== void 0 ? _a : null,
+            downlink: (_b = conn === null || conn === void 0 ? void 0 : conn.downlink) !== null && _b !== void 0 ? _b : null,
+            rtt: (_c = conn === null || conn === void 0 ? void 0 : conn.rtt) !== null && _c !== void 0 ? _c : null,
+            saveData: (_d = conn === null || conn === void 0 ? void 0 : conn.saveData) !== null && _d !== void 0 ? _d : null,
+            type: (_e = conn === null || conn === void 0 ? void 0 : conn.type) !== null && _e !== void 0 ? _e : null,
+        };
+    };
+    const [state, setState] = useState(getState);
+    useEffect(() => {
+        const update = () => setState(getState());
+        window.addEventListener('online', update);
+        window.addEventListener('offline', update);
+        const conn = navigator.connection;
+        conn === null || conn === void 0 ? void 0 : conn.addEventListener('change', update);
+        return () => {
+            window.removeEventListener('online', update);
+            window.removeEventListener('offline', update);
+            conn === null || conn === void 0 ? void 0 : conn.removeEventListener('change', update);
+        };
+    }, []);
+    return state;
+}
+// ─── useHash ──────────────────────────────────────────────────────────────────
+/**
+ * Reads and writes the URL hash (fragment) as state.
+ * Returns [hash, setHash] where hash does not include the leading '#'.
+ */
+export function useHash() {
+    const [hash, setHashState] = useState(() => typeof window !== 'undefined' ? window.location.hash.slice(1) : '');
+    useEffect(() => {
+        const onHashChange = () => setHashState(window.location.hash.slice(1));
+        window.addEventListener('hashchange', onHashChange);
+        return () => window.removeEventListener('hashchange', onHashChange);
+    }, []);
+    const setHash = useCallback((newHash) => {
+        const normalized = newHash.startsWith('#') ? newHash : `#${newHash}`;
+        window.location.hash = normalized;
+    }, []);
+    return [hash, setHash];
+}
+// ─── useLatest ────────────────────────────────────────────────────────────────
+/**
+ * Returns a ref that always holds the most recent value.
+ * Useful for reading the latest prop/state inside a callback without
+ * adding it to the dependency array.
+ */
+export function useLatest(value) {
+    const ref = useRef(value);
+    ref.current = value;
+    return ref;
+}
+// ─── useEventCallback ─────────────────────────────────────────────────────────
+/**
+ * Returns a stable callback reference that always delegates to the latest
+ * version of the provided function. Safe to pass to event listeners without
+ * causing unnecessary re-subscriptions.
+ */
+export function useEventCallback(fn) {
+    const ref = useRef(fn);
+    useLayoutEffect(() => {
+        ref.current = fn;
+    });
+    return useCallback((...args) => ref.current(...args), []);
+}
+// ─── useSafeState ─────────────────────────────────────────────────────────────
+/**
+ * A drop-in replacement for useState that suppresses state updates after the
+ * component has unmounted, preventing "Can't perform a React state update on an
+ * unmounted component" warnings.
+ */
+export function useSafeState(initialState) {
+    const isMounted = useRef(false);
+    const [state, setState] = useState(initialState);
+    useEffect(() => {
+        isMounted.current = true;
+        return () => { isMounted.current = false; };
+    }, []);
+    const safeSetState = useCallback((value) => {
+        if (isMounted.current)
+            setState(value);
+    }, []);
+    return [state, safeSetState];
+}
+// ─── useRafState ──────────────────────────────────────────────────────────────
+/**
+ * Identical to useState but batches updates via requestAnimationFrame,
+ * reducing the number of renders for rapidly changing values (e.g. mouse
+ * position, scroll events).
+ */
+export function useRafState(initialState) {
+    const frameRef = useRef(0);
+    const [state, setState] = useState(initialState);
+    const setRafState = useCallback((value) => {
+        cancelAnimationFrame(frameRef.current);
+        frameRef.current = requestAnimationFrame(() => setState(value));
+    }, []);
+    useEffect(() => () => cancelAnimationFrame(frameRef.current), []);
+    return [state, setRafState];
+}
+/**
+ * Sets the document title reactively. Optionally restores the previous title
+ * on unmount.
+ */
+export function useTitle(title, options = {}) {
+    const { restoreOnUnmount = false } = options;
+    const originalTitle = useRef(typeof document !== 'undefined' ? document.title : '');
+    useEffect(() => {
+        if (typeof document === 'undefined')
+            return;
+        document.title = title;
+        return () => {
+            if (restoreOnUnmount) {
+                document.title = originalTitle.current;
+            }
+        };
+    }, [title, restoreOnUnmount]);
+}
+// ─── useFavicon ───────────────────────────────────────────────────────────────
+/**
+ * Dynamically updates the page favicon by href. Useful for notifications or
+ * theme changes (e.g. switching between light/dark favicon).
+ */
+export function useFavicon(href) {
+    useEffect(() => {
+        if (typeof document === 'undefined' || !href)
+            return;
+        let link = document.querySelector('link[rel~="icon"]');
+        if (!link) {
+            link = document.createElement('link');
+            link.rel = 'icon';
+            document.head.appendChild(link);
+        }
+        link.href = href;
+    }, [href]);
+}
+// ─── useWhyDidYouUpdate ───────────────────────────────────────────────────────
+/**
+ * Debug hook that logs which prop/state changes triggered the last render.
+ * Only active in development; no-ops in production.
+ * Pass a label and the component's props/state object.
+ */
+export function useWhyDidYouUpdate(name, props) {
+    const previousProps = useRef({});
+    useEffect(() => {
+        if (process.env.NODE_ENV !== 'production') {
+            const allKeys = Object.keys(Object.assign(Object.assign({}, previousProps.current), props));
+            const changes = {};
+            allKeys.forEach(key => {
+                if (previousProps.current[key] !== props[key]) {
+                    changes[key] = { from: previousProps.current[key], to: props[key] };
+                }
+            });
+            if (Object.keys(changes).length > 0) {
+                console.log(`[useWhyDidYouUpdate] ${name}`, changes);
+            }
+        }
+        previousProps.current = props;
+    });
+}
+/**
+ * Manages the Fullscreen API for a specific element (or the whole document when
+ * no ref target is provided). Tracks fullscreen state reactively.
+ */
+export function useFullscreen() {
+    const ref = useRef(null);
+    const [isFullscreen, setIsFullscreen] = useState(false);
+    const isSupported = typeof document !== 'undefined' && 'fullscreenEnabled' in document;
+    useEffect(() => {
+        const onChange = () => setIsFullscreen(!!document.fullscreenElement);
+        document.addEventListener('fullscreenchange', onChange);
+        return () => document.removeEventListener('fullscreenchange', onChange);
+    }, []);
+    const enter = useCallback(async () => {
+        var _a, _b;
+        const el = (_a = ref.current) !== null && _a !== void 0 ? _a : document.documentElement;
+        if (!document.fullscreenElement) {
+            await ((_b = el.requestFullscreen) === null || _b === void 0 ? void 0 : _b.call(el));
+        }
+    }, []);
+    const exit = useCallback(async () => {
+        var _a;
+        if (document.fullscreenElement) {
+            await ((_a = document.exitFullscreen) === null || _a === void 0 ? void 0 : _a.call(document));
+        }
+    }, []);
+    const toggle = useCallback(async () => {
+        var _a, _b, _c, _d;
+        if (document.fullscreenElement)
+            await ((_a = document.exitFullscreen) === null || _a === void 0 ? void 0 : _a.call(document));
+        else
+            await ((_d = (_c = ((_b = ref.current) !== null && _b !== void 0 ? _b : document.documentElement)).requestFullscreen) === null || _d === void 0 ? void 0 : _d.call(_c));
+    }, []);
+    return { ref, isFullscreen, enter, exit, toggle, isSupported };
+}
+// ─── useLogger ────────────────────────────────────────────────────────────────
+/**
+ * Logs the component name and any values passed on every render.
+ * Only logs in development mode.
+ */
+export function useLogger(name, ...values) {
+    useEffect(() => {
+        if (process.env.NODE_ENV !== 'production') {
+            console.log(`[${name}]`, ...values);
+        }
+    });
+}