@sohanemon/utils 6.2.8 → 6.3.0

package/dist/hooks/index.js

@@ -1,533 +0,0 @@
-'use client';
-import * as React from 'react';
-import { copyToClipboard } from '../functions';
-export * from './action';
-export * from './async';
-export * from './schedule';
-/**
- * Hook to detect clicks outside of a referenced element.
- * @param callback - A function to invoke when a click outside is detected.
- * @returns A React ref object to attach to the target element.
- */
-export const useClickOutside = (callback = () => alert('clicked outside')) => {
-    const ref = React.useRef(null);
-    const listener = (e) => {
-        if (ref.current && !ref.current.contains(e.target)) {
-            callback();
-        }
-    };
-    React.useEffect(() => {
-        document.addEventListener('mousedown', listener);
-        document.addEventListener('touchstart', listener);
-        return () => {
-            document.removeEventListener('mousedown', listener);
-            document.removeEventListener('touchstart', listener);
-        };
-    });
-    return ref;
-};
-/**
- * Hook to match a media query based on Tailwind CSS breakpoints or custom queries.
- * @param tailwindBreakpoint - The Tailwind breakpoint or custom query string.
- * @returns A boolean indicating whether the media query matches.
- */
-export function useMediaQuery(tailwindBreakpoint) {
-    const parsedQuery = React.useMemo(() => {
-        switch (tailwindBreakpoint) {
-            case 'sm':
-                return '(min-width: 640px)';
-            case 'md':
-                return '(min-width: 768px)';
-            case 'lg':
-                return '(min-width: 1024px)';
-            case 'xl':
-                return '(min-width: 1280px)';
-            case '2xl':
-                return '(min-width: 1536px)';
-            default:
-                return tailwindBreakpoint;
-        }
-    }, [tailwindBreakpoint]);
-    const getMatches = (parsedQuery) => {
-        if (typeof window !== 'undefined') {
-            return window.matchMedia(parsedQuery).matches;
-        }
-        return false;
-    };
-    const [matches, setMatches] = React.useState(getMatches(parsedQuery));
-    const handleChange = () => {
-        setMatches(getMatches(parsedQuery));
-    };
-    useIsomorphicEffect(() => {
-        const matchMedia = window.matchMedia(parsedQuery);
-        handleChange();
-        matchMedia.addEventListener('change', handleChange);
-        return () => {
-            matchMedia.removeEventListener('change', handleChange);
-        };
-    }, [parsedQuery]);
-    return matches;
-}
-/**
- * Runs an effect only once when the component mounts.
- * @param effect - The effect callback function.
- */
-export function useEffectOnce(effect) {
-    React.useEffect(effect, []);
-}
-/**
- * Runs an effect only when dependencies update, excluding the initial render.
- * @param effect - The effect callback function.
- * @param deps - Dependency array for the effect.
- */
-export function useUpdateEffect(effect, deps) {
-    const isInitialMount = React.useRef(true);
-    // biome-ignore lint/correctness/useExhaustiveDependencies: only update specific
-    React.useEffect(() => {
-        if (isInitialMount.current) {
-            isInitialMount.current = false;
-        }
-        else {
-            return effect();
-        }
-    }, deps);
-}
-/**
- * Debounces a state value with a specified delay.
- * @param state - The state value to debounce.
- * @param delay - The debounce delay in milliseconds (default: 500ms).
- * @returns The debounced state value.
- */
-export function useDebounce(state, delay = 500) {
-    const [debouncedState, setDebouncedState] = React.useState(state);
-    React.useEffect(() => {
-        const timer = setTimeout(() => setDebouncedState(state), delay);
-        return () => {
-            clearTimeout(timer);
-        };
-    }, [state, delay]);
-    return debouncedState;
-}
-/**
- * Hook to handle effects with layout synchronization in the browser.
- */
-export const useIsomorphicEffect = typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;
-/**
- * Hook to invoke a callback after a specified timeout.
- * @param callback - The callback function to invoke.
- * @param delay - The timeout delay in milliseconds (default: 1000ms).
- */
-export function useTimeout(callback, delay = 1000) {
-    const savedCallback = React.useRef(callback);
-    useIsomorphicEffect(() => {
-        savedCallback.current = callback;
-    }, [callback]);
-    React.useEffect(() => {
-        if (!delay && delay !== 0) {
-            return;
-        }
-        const id = setTimeout(() => savedCallback.current(), delay);
-        return () => clearTimeout(id);
-    }, [delay]);
-}
-/**
- * Hook to add and remove a window event listener.
- * @param type - The type of the event to listen for.
- * @param listener - The event listener callback.
- * @param options - Options for the event listener.
- */
-export function useWindowEvent(type, listener, options) {
-    React.useEffect(() => {
-        window.addEventListener(type, listener, options);
-        return () => window.removeEventListener(type, listener, options);
-    }, [type, listener, options]);
-}
-/**
- * Hook to persist state in session storage.
- * @param key - The key for session storage.
- * @param defaultValue - The default value if no value is found in session storage.
- * @returns A tuple of the stored value and an updater function.
- */
-export const useSessionStorage = (key, defaultValue) => {
-    const [storedValue, setStoredValue] = React.useState(defaultValue);
-    React.useEffect(() => {
-        const value = sessionStorage.getItem(key);
-        if (value) {
-            setStoredValue(JSON.parse(value));
-        }
-    }, [key]);
-    const updateStoredValue = React.useCallback((valueOrFn) => {
-        setStoredValue((prev) => {
-            const newValue = typeof valueOrFn === 'function'
-                ? valueOrFn(prev)
-                : valueOrFn;
-            sessionStorage.setItem(key, JSON.stringify(newValue));
-            return newValue;
-        });
-    }, [key]);
-    return [storedValue, updateStoredValue];
-};
-/**
- * Hook to persist state in local storage.
- * @param key - The key for local storage.
- * @param defaultValue - The default value if no value is found in local storage.
- * @returns A tuple of the stored value and an updater function.
- */
-export const useLocalStorage = (key, defaultValue) => {
-    const [storedValue, setStoredValue] = React.useState(defaultValue);
-    React.useEffect(() => {
-        const value = localStorage.getItem(key);
-        if (value) {
-            setStoredValue(JSON.parse(value));
-        }
-    }, [key]);
-    const updateStoredValue = React.useCallback((valueOrFn) => {
-        let newValue;
-        if (typeof valueOrFn === 'function') {
-            newValue = valueOrFn(storedValue);
-        }
-        else {
-            newValue = valueOrFn;
-        }
-        localStorage.setItem(key, JSON.stringify(newValue));
-        setStoredValue(newValue);
-    }, [key]);
-    return [storedValue, updateStoredValue];
-};
-/**
- * Hook to manage URL parameters as state.
- * @param key - The URL parameter key.
- * @param defaultValue - The default value if the parameter is not present.
- * @returns A tuple of the parameter value and a setter function.
- */
-export const useUrlParams = (key, defaultValue) => {
-    const [value, setValue] = React.useState(defaultValue);
-    React.useEffect(() => {
-        const params = new URLSearchParams(window.location.search);
-        const paramValue = params.get(key);
-        if (paramValue !== null) {
-            setValue(paramValue);
-        }
-    }, [key]);
-    const updateValue = (newValue) => {
-        const params = new URLSearchParams(window.location.search);
-        params.set(key, String(newValue));
-        window.history.pushState({}, '', `${window.location.pathname}?${params}`);
-        setValue(newValue);
-    };
-    return [value, updateValue];
-};
-/**
- * Hook to select a DOM element by CSS selector.
- * @param selector - The CSS selector string.
- * @returns The selected DOM element or null if not found.
- */
-export const useQuerySelector = (selector) => {
-    const [element, setElement] = React.useState(null);
-    const elementRef = React.useRef(null);
-    React.useLayoutEffect(() => {
-        const referenceElement = document.querySelector(selector);
-        if (!referenceElement)
-            return;
-        if (elementRef.current !== referenceElement) {
-            elementRef.current = referenceElement;
-            setElement(referenceElement);
-        }
-        const resizeObserver = new ResizeObserver(() => {
-            if (elementRef.current !== referenceElement) {
-                elementRef.current = referenceElement;
-                setElement(referenceElement);
-            }
-        });
-        resizeObserver.observe(referenceElement);
-        return () => {
-            resizeObserver.disconnect();
-        };
-    }, [selector]);
-    return element;
-};
-/**
- * Hook to detect if the code is running on the client side.
- * @returns A boolean indicating whether the code is running on the client.
- */
-export function useIsClient() {
-    const [isClient, setIsClient] = React.useState(false);
-    React.useEffect(() => {
-        setIsClient(true);
-    }, []);
-    return isClient;
-}
-/**
- * Hook to lock scroll by disabling body overflow.
- */
-export function useLockScroll() {
-    React.useLayoutEffect(() => {
-        const originalStyle = window.getComputedStyle(document.body).overflow;
-        document.body.style.overflow = 'hidden';
-        return () => {
-            document.body.style.overflow = originalStyle;
-        };
-    }, []);
-}
-/**
- * Hook to copy text to the clipboard and track the copy status.
- * @param timeout - The timeout duration in milliseconds to reset the copy status (default: 2000ms).
- * @returns An object with the `isCopied` state and `copy` function.
- */
-export function useCopyToClipboard({ timeout = 2000 }) {
-    const [isCopied, setIsCopied] = React.useState(false);
-    const copy = (value) => {
-        copyToClipboard(value, () => {
-            setIsCopied(true);
-            setTimeout(() => {
-                setIsCopied(false);
-            }, timeout);
-        });
-    };
-    return { isCopied, copy };
-}
-/**
- *
- * Hook to calculate the height of an element based on viewport and other block heights.
- * @param params - Configuration object for height calculation.
- * @returns The calculated height.
- */
-export const useHeightCalculation = ({ blockIds = [], margin = 0, substract = true, dynamic = false, }) => {
-    const [height, setTableHeight] = React.useState(500);
-    const handleResize = () => {
-        const blockHeight = blockIds.reduce((prevHeight, id) => prevHeight + (document.getElementById(id)?.clientHeight || 0), 0);
-        const height = substract
-            ? window.innerHeight - blockHeight - margin
-            : blockHeight + margin;
-        setTableHeight(height);
-    };
-    useIsomorphicEffect(() => {
-        handleResize();
-        if (!dynamic)
-            return;
-        if (typeof dynamic === 'string') {
-            const resizableElement = document.getElementById(dynamic);
-            const resizeObserver = new ResizeObserver((entries) => {
-                for (const _ of entries)
-                    handleResize();
-            });
-            if (resizableElement)
-                resizeObserver.observe(resizableElement);
-            return () => resizeObserver?.disconnect();
-        }
-        window.addEventListener('resize', handleResize);
-        return () => window.removeEventListener('resize', handleResize);
-    }, []);
-    return height;
-};
-/**
- * Hook to calculate dimensions (height and width) of an element based on viewport and other block dimensions.
- * @param params - Configuration object for dimension calculation.
- * @returns An object containing the calculated height and width.
- */
-export const useDomCalculation = ({ blockIds = [], margin = 0, substract = true, dynamic = false, onChange, }) => {
-    const [dimensions, setDimensions] = React.useState({
-        height: 500,
-        width: 500,
-    });
-    const handleCalculation = React.useCallback(() => {
-        const blocksHeight = blockIds.reduce((prevHeight, id) => prevHeight + (document.getElementById(id)?.clientHeight || 0), 0);
-        const blocksWidth = blockIds.reduce((prevWidth, id) => prevWidth + (document.getElementById(id)?.clientWidth || 0), 0);
-        const height = substract
-            ? window.innerHeight - blocksHeight - margin
-            : blocksHeight + margin;
-        const width = substract
-            ? window.innerWidth - blocksWidth - margin
-            : blocksWidth + margin;
-        setDimensions((prev) => {
-            // Only update state if dimensions have actually changed
-            if (prev.height === height && prev.width === width) {
-                return prev;
-            }
-            return { height, width };
-        });
-        onChange?.({
-            blocksWidth,
-            blocksHeight,
-            remainingWidth: width,
-            remainingHeight: height,
-        });
-    }, [blockIds, margin, substract, onChange]);
-    useIsomorphicEffect(() => {
-        handleCalculation();
-        const cleanups = [];
-        if (blockIds.length > 0) {
-            const observer = new MutationObserver((mutations) => {
-                let shouldRecalculate = false;
-                for (const mutation of mutations) {
-                    for (const node of mutation.addedNodes) {
-                        if (node instanceof Element) {
-                            if (blockIds.includes(node.id) ||
-                                blockIds.some((id) => node.querySelector(`#${CSS.escape(id)}`))) {
-                                shouldRecalculate = true;
-                                break;
-                            }
-                        }
-                    }
-                    if (shouldRecalculate)
-                        break;
-                    for (const node of mutation.removedNodes) {
-                        if (node instanceof Element) {
-                            if (blockIds.includes(node.id) ||
-                                blockIds.some((id) => node.querySelector(`#${CSS.escape(id)}`))) {
-                                shouldRecalculate = true;
-                                break;
-                            }
-                        }
-                    }
-                    if (shouldRecalculate)
-                        break;
-                }
-                if (shouldRecalculate) {
-                    handleCalculation();
-                }
-            });
-            observer.observe(document.body, {
-                childList: true,
-                subtree: true,
-            });
-            cleanups.push(() => observer.disconnect());
-        }
-        if (dynamic) {
-            if (typeof dynamic === 'string') {
-                const resizableElement = document.getElementById(dynamic);
-                if (resizableElement) {
-                    const resizeObserver = new ResizeObserver(handleCalculation);
-                    resizeObserver.observe(resizableElement);
-                    cleanups.push(() => resizeObserver.unobserve(resizableElement));
-                    cleanups.push(() => resizeObserver.disconnect());
-                }
-            }
-            else {
-                window.addEventListener('resize', handleCalculation);
-                cleanups.push(() => window.removeEventListener('resize', handleCalculation));
-            }
-        }
-        return () => {
-            for (const cleanup of cleanups) {
-                cleanup();
-            }
-        };
-    }, [handleCalculation, dynamic, blockIds.join(',')]);
-    return dimensions;
-};
-/**
- * Hook to detect if the user is scrolling.
- * @returns An object containing the isScrolling state and a ref to the scrollable container.
- */
-export const useIsScrolling = () => {
-    const [isScrolling, setIsScrolling] = React.useState(false);
-    const scrollTimerRef = React.useRef(null);
-    const scrollableContainerRef = React.useRef(null);
-    useEffectOnce(() => {
-        const mainElement = scrollableContainerRef.current;
-        if (!mainElement)
-            return;
-        const handleScroll = () => {
-            setIsScrolling(true);
-            if (scrollTimerRef.current) {
-                clearTimeout(scrollTimerRef.current);
-            }
-            // Set a timeout to mark scrolling as finished after delay
-            scrollTimerRef.current = setTimeout(() => {
-                setIsScrolling(false);
-            }, 150);
-        };
-        handleScroll();
-        mainElement.addEventListener('scroll', handleScroll);
-        return () => {
-            mainElement.removeEventListener('scroll', handleScroll);
-            if (scrollTimerRef.current) {
-                clearTimeout(scrollTimerRef.current);
-            }
-        };
-    });
-    return {
-        isScrolling,
-        scrollableContainerRef,
-    };
-};
-/**
- * Hook to detect if the user is at the top of the page.
- * @returns An object containing the isAtTop state and a ref to the scrollable container.
- */
-export const useIsAtTop = ({ offset } = {}) => {
-    const [isAtTop, setIsAtTop] = React.useState(true);
-    const scrollableContainerRef = React.useRef(null);
-    useEffectOnce(() => {
-        const mainElement = scrollableContainerRef.current;
-        if (!mainElement)
-            return;
-        const handleScroll = () => {
-            const scrolled = mainElement.scrollTop > (offset ?? 10);
-            setIsAtTop(!scrolled);
-        };
-        handleScroll();
-        mainElement.addEventListener('scroll', handleScroll);
-        return () => {
-            mainElement.removeEventListener('scroll', handleScroll);
-        };
-    });
-    return { scrollableContainerRef, isAtTop };
-};
-/**
- * React hook that tracks when an element enters or leaves the viewport
- * using the Intersection Observer API.
- *
- * @example
- * ```tsx
- * const { ref, isIntersecting } = useIntersection({
- *   threshold: 0.1,
- *   onInteractionStart: () => console.log('👀 Element entered viewport'),
- *   onInteractionEnd: () => console.log('🙈 Element left viewport'),
- * });
- *
- * return <div ref={ref}>Watch me</div>;
- * ```
- *
- * @param options - Configuration for the intersection observer.
- * @returns Object containing:
- * - `ref`: React ref to attach to the observed element.
- * - `isIntersecting`: Whether the element is currently visible.
- */
-export const useIntersection = ({ threshold = 0.1, root = null, rootMargin, onInteractionStart, onInteractionEnd, } = {}) => {
-    const [isIntersecting, setIsIntersecting] = React.useState(false);
-    const ref = React.useRef(null);
-    React.useEffect(() => {
-        if (!ref.current)
-            return;
-        const observer = new IntersectionObserver((entries) => {
-            for (const entry of entries) {
-                if (entry.isIntersecting) {
-                    if (!isIntersecting) {
-                        onInteractionStart?.();
-                        setIsIntersecting(true);
-                    }
-                }
-                else {
-                    if (isIntersecting) {
-                        onInteractionEnd?.();
-                        setIsIntersecting(false);
-                    }
-                }
-            }
-        }, { threshold, root, rootMargin });
-        observer.observe(ref.current);
-        return () => {
-            observer.disconnect();
-        };
-    }, [
-        threshold,
-        root,
-        rootMargin,
-        onInteractionStart,
-        onInteractionEnd,
-        isIntersecting,
-    ]);
-    return { ref, isIntersecting };
-};

package/dist/hooks/schedule.d.ts

@@ -1,36 +0,0 @@
-import * as React from 'react';
-import { ScheduleOpts } from '../functions';
-import { Task } from '../functions/schedule';
-/**
- * useSchedule — run non-urgent work later, without blocking UI.
- */
-export declare function useSchedule(options?: ScheduleOpts): (task: Task) => void;
-/**
- * useScheduledEffect — Runs a non-urgent task in a React component without blocking UI rendering.
- *
- * This hook is like `useEffect`, but the provided task is executed
- * with low priority using `requestIdleCallback` (if available)
- * or a fallback scheduler. Useful for heavy computations, logging,
- * analytics, or background work that doesn't need to block render.
- *
- * @param {Function} effect - The function to run later. Can be synchronous or return a Promise.
- * @param {React.DependencyList[]} deps - Dependency array; task will re-run whenever these change.
- * @param {ScheduleOpts} [options] - Optional scheduling options.
- * @param {number} [options.timeout] - Max time (ms) to wait before executing the task. Defaults to 10000.
- *
- * @example
- * ```tsx
- * import React from 'react';
- * import { useScheduledEffect } from './hooks/useScheduledEffect';
- *
- * function MyComponent({ userId }: { userId: string }) {
- *   useScheduledEffect(() => {
- *     // non-blocking analytics or heavy work
- *     console.log('Sending analytics for user:', userId);
- *   }, [userId], { timeout: 5000 });
- *
- *   return <div>Component loaded. Task will run later 😎</div>;
- * }
- * ```
- */
-export declare function useScheduledEffect(effect: () => void | (() => void), deps?: React.DependencyList, options?: ScheduleOpts): void;

package/dist/hooks/schedule.js

@@ -1,68 +0,0 @@
-import * as React from 'react';
-import { schedule as _schedule } from '../functions/schedule';
-/**
- * useSchedule — run non-urgent work later, without blocking UI.
- */
-export function useSchedule(options = {}) {
-    const { timeout = 10000 } = options;
-    const schedule = React.useCallback((task) => {
-        const exec = () => {
-            try {
-                React.startTransition(() => {
-                    task();
-                });
-            }
-            catch (err) {
-                console.log('⚡[schedule.tsx] Failed: ', err);
-            }
-        };
-        if ('requestIdleCallback' in window) {
-            requestIdleCallback(exec, { timeout });
-        }
-        else {
-            _schedule(exec);
-        }
-    }, [timeout]);
-    return schedule;
-}
-/**
- * useScheduledEffect — Runs a non-urgent task in a React component without blocking UI rendering.
- *
- * This hook is like `useEffect`, but the provided task is executed
- * with low priority using `requestIdleCallback` (if available)
- * or a fallback scheduler. Useful for heavy computations, logging,
- * analytics, or background work that doesn't need to block render.
- *
- * @param {Function} effect - The function to run later. Can be synchronous or return a Promise.
- * @param {React.DependencyList[]} deps - Dependency array; task will re-run whenever these change.
- * @param {ScheduleOpts} [options] - Optional scheduling options.
- * @param {number} [options.timeout] - Max time (ms) to wait before executing the task. Defaults to 10000.
- *
- * @example
- * ```tsx
- * import React from 'react';
- * import { useScheduledEffect } from './hooks/useScheduledEffect';
- *
- * function MyComponent({ userId }: { userId: string }) {
- *   useScheduledEffect(() => {
- *     // non-blocking analytics or heavy work
- *     console.log('Sending analytics for user:', userId);
- *   }, [userId], { timeout: 5000 });
- *
- *   return <div>Component loaded. Task will run later 😎</div>;
- * }
- * ```
- */
-export function useScheduledEffect(effect, deps = [], options = {}) {
-    const schedule = useSchedule(options);
-    React.useEffect(() => {
-        let cleanup;
-        schedule(() => {
-            cleanup = effect();
-        });
-        return () => {
-            if (typeof cleanup === 'function')
-                cleanup?.();
-        };
-    }, [schedule, ...deps]);
-}