@sohanemon/utils 4.0.26 → 4.0.28

package/dist/hooks/index.d.ts

@@ -1,22 +1,107 @@
-import { type Dispatch, type EffectCallback, type SetStateAction, useLayoutEffect } from 'react';
+import * as React from 'react';
 export * from './action';
-export declare const useClickOutside: (callback?: () => void) => import("react").MutableRefObject<HTMLDivElement>;
+/**
+ * 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 declare const useClickOutside: (callback?: () => void) => React.RefObject<HTMLDivElement>;
+/**
+ * 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 declare function useMediaQuery(tailwindBreakpoint: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | `(${string})`): boolean;
-export declare function useEffectOnce(effect: EffectCallback): void;
-export declare function useUpdateEffect(effect: EffectCallback, deps: any[]): void;
+/**
+ * Runs an effect only once when the component mounts.
+ * @param effect - The effect callback function.
+ */
+export declare function useEffectOnce(effect: React.EffectCallback): void;
+/**
+ * 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 declare function useUpdateEffect(effect: React.EffectCallback, deps: React.DependencyList): void;
+/**
+ * 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 declare function useDebounce<T>(state: T, delay?: number): T;
-export declare const useIsomorphicEffect: typeof useLayoutEffect;
+/**
+ * Hook to handle effects with layout synchronization in the browser.
+ */
+export declare const useIsomorphicEffect: typeof React.useLayoutEffect;
+/**
+ * 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 declare function useTimeout(callback: () => void, delay?: number | null): void;
-export declare function useWindowEvent<K extends string = keyof WindowEventMap>(type: K, listener: K extends keyof WindowEventMap ? (this: Window, ev: WindowEventMap[K]) => void : (this: Window, ev: CustomEvent) => void, options?: boolean | AddEventListenerOptions): void;
-type LocalStorageValue<T> = [T, Dispatch<SetStateAction<T>>];
+/**
+ * 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 declare function useWindowEvent<K extends keyof WindowEventMap>(type: K, listener: (this: Window, ev: WindowEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+/**
+ * Tuple type for local storage value and updater.
+ */
+type LocalStorageValue<T> = [T, React.Dispatch<React.SetStateAction<T>>];
+/**
+ * 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 declare const useLocalStorage: <T extends Record<string, any>>(key: string, defaultValue: T) => LocalStorageValue<T>;
+/**
+ * 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 declare const useUrlParams: <T extends string | number | boolean>(key: string, defaultValue: T) => [T, (value: T) => void];
+/**
+ * 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 declare const useQuerySelector: <T extends Element>(selector: string) => T | null;
+/**
+ * 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 declare function useIsClient(): boolean;
+/**
+ * Hook to lock scroll by disabling body overflow.
+ */
 export declare function useLockScroll(): void;
+/**
+ * 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 declare function useCopyToClipboard({ timeout }: {
     timeout?: number;
 }): {
-    isCopied: Boolean;
+    isCopied: boolean;
     copy: (value: string) => void;
 };
+/**
+ * Properties for height calculation.
+ */
+type CalculationProps = {
+    blockIds: string[];
+    dynamic?: boolean | string;
+    margin?: number;
+};
+/**
+ * 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 declare const useHeightCalculation: ({ blockIds, margin, dynamic, }: CalculationProps) => number;

package/dist/hooks/index.js

@@ -1,15 +1,20 @@
 'use client';
-import { useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { copyToClipboard } from '../functions';
+import * as React from 'react';
 export * from './action';
+/**
+ * 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 = useRef(null);
+    const ref = React.useRef(null);
     const listener = (e) => {
         if (ref.current && !ref.current.contains(e.target)) {
             callback();
         }
     };
-    useEffect(() => {
+    React.useEffect(() => {
         document.addEventListener('mousedown', listener);
         document.addEventListener('touchstart', listener);
         return () => {
@@ -19,8 +24,13 @@ export const useClickOutside = (callback = () => alert('clicked outside')) => {
     });
     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 = useMemo(() => {
+    const parsedQuery = React.useMemo(() => {
         switch (tailwindBreakpoint) {
             case 'sm':
                 return '(min-width: 640px)';
@@ -42,12 +52,11 @@ export function useMediaQuery(tailwindBreakpoint) {
         }
         return false;
     };
-    const [matches, setMatches] = useState(getMatches(parsedQuery));
-    function handleChange() {
+    const [matches, setMatches] = React.useState(getMatches(parsedQuery));
+    const handleChange = () => {
         setMatches(getMatches(parsedQuery));
-    }
-    // biome-ignore lint/correctness/useExhaustiveDependencies: <explanation>
-    useEffect(() => {
+    };
+    useIsomorphicEffect(() => {
         const matchMedia = window.matchMedia(parsedQuery);
         handleChange();
         matchMedia.addEventListener('change', handleChange);
@@ -57,13 +66,22 @@ export function useMediaQuery(tailwindBreakpoint) {
     }, [parsedQuery]);
     return matches;
 }
+/**
+ * Runs an effect only once when the component mounts.
+ * @param effect - The effect callback function.
+ */
 export function useEffectOnce(effect) {
-    useEffect(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 = useRef(true);
-    // biome-ignore lint/correctness/useExhaustiveDependencies: <explanation>
-    useEffect(() => {
+    const isInitialMount = React.useRef(true);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: only update specific
+    React.useEffect(() => {
         if (isInitialMount.current) {
             isInitialMount.current = false;
         }
@@ -72,9 +90,15 @@ export function useUpdateEffect(effect, deps) {
         }
     }, 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] = useState(state);
-    useEffect(() => {
+    const [debouncedState, setDebouncedState] = React.useState(state);
+    React.useEffect(() => {
         const timer = setTimeout(() => setDebouncedState(state), delay);
         return () => {
             clearTimeout(timer);
@@ -82,13 +106,21 @@ export function useDebounce(state, delay = 500) {
     }, [state, delay]);
     return debouncedState;
 }
-export const useIsomorphicEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+/**
+ * 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 = useRef(callback);
+    const savedCallback = React.useRef(callback);
     useIsomorphicEffect(() => {
         savedCallback.current = callback;
     }, [callback]);
-    useEffect(() => {
+    React.useEffect(() => {
         if (!delay && delay !== 0) {
             return;
         }
@@ -96,30 +128,36 @@ export function useTimeout(callback, delay = 1000) {
         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) {
-    // biome-ignore lint/correctness/useExhaustiveDependencies: <explanation>
-    useEffect(() => {
+    React.useEffect(() => {
         window.addEventListener(type, listener, options);
         return () => window.removeEventListener(type, listener, options);
-    }, [type, listener]);
+    }, [type, listener, options]);
 }
-// Custom hook for using local storage with a specified key and default value
+/**
+ * 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] = useState(defaultValue);
-    // Use effect to retrieve the stored value from local storage on component mount
-    useEffect(() => {
+    const [storedValue, setStoredValue] = React.useState(defaultValue);
+    React.useEffect(() => {
         const value = localStorage.getItem(key);
         if (value) {
             setStoredValue(JSON.parse(value));
         }
     }, [key]);
-    // Function to update the stored value in local storage and state
     const updateStoredValue = (valueOrFn) => {
-        // biome-ignore lint/suspicious/noImplicitAnyLet: <explanation>
         let newValue;
         if (typeof valueOrFn === 'function') {
-            const updateFunction = valueOrFn;
-            newValue = updateFunction(storedValue);
+            newValue = valueOrFn(storedValue);
         }
         else {
             newValue = valueOrFn;
@@ -129,18 +167,21 @@ export const useLocalStorage = (key, defaultValue) => {
     };
     return [storedValue, updateStoredValue];
 };
-// Custom hook for using URL parameters with a specified key and default value
+/**
+ * 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] = useState(defaultValue);
-    // Use effect to retrieve the value from URL parameters on component mount
-    useEffect(() => {
+    const [value, setValue] = React.useState(defaultValue);
+    React.useEffect(() => {
         const params = new URLSearchParams(window.location.search);
-        const value = params.get(key);
-        if (value !== null) {
-            setValue(value);
+        const paramValue = params.get(key);
+        if (paramValue !== null) {
+            setValue(paramValue);
         }
     }, [key]);
-    // Function to update the value in URL parameters and state
     const updateValue = (newValue) => {
         const params = new URLSearchParams(window.location.search);
         params.set(key, String(newValue));
@@ -149,10 +190,15 @@ export const useUrlParams = (key, defaultValue) => {
     };
     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] = useState(null);
-    const elementRef = useRef(null);
-    useLayoutEffect(() => {
+    const [element, setElement] = React.useState(null);
+    const elementRef = React.useRef(null);
+    React.useLayoutEffect(() => {
         const referenceElement = document.querySelector(selector);
         if (!referenceElement)
             return;
@@ -161,7 +207,6 @@ export const useQuerySelector = (selector) => {
             setElement(referenceElement);
         }
         const resizeObserver = new ResizeObserver(() => {
-            // Only update state if the element reference changes
             if (elementRef.current !== referenceElement) {
                 elementRef.current = referenceElement;
                 setElement(referenceElement);
@@ -174,15 +219,22 @@ export const useQuerySelector = (selector) => {
     }, [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] = useState(false);
-    useEffect(() => {
+    const [isClient, setIsClient] = React.useState(false);
+    React.useEffect(() => {
         setIsClient(true);
     }, []);
     return isClient;
 }
+/**
+ * Hook to lock scroll by disabling body overflow.
+ */
 export function useLockScroll() {
-    useLayoutEffect(() => {
+    React.useLayoutEffect(() => {
         const originalStyle = window.getComputedStyle(document.body).overflow;
         document.body.style.overflow = 'hidden';
         return () => {
@@ -190,8 +242,13 @@ export function useLockScroll() {
         };
     }, []);
 }
+/**
+ * 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] = useState(false);
+    const [isCopied, setIsCopied] = React.useState(false);
     const copy = (value) => {
         copyToClipboard(value, () => {
             setIsCopied(true);
@@ -202,3 +259,33 @@ export function useCopyToClipboard({ timeout = 2000 }) {
     };
     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, dynamic = false, }) => {
+    const [height, setTableHeight] = React.useState(500);
+    const handleResize = () => {
+        const blockHeight = blockIds.reduce((prevHeight, id) => prevHeight + (document.getElementById(id)?.clientHeight || 0), 0);
+        setTableHeight(window.innerHeight - blockHeight - margin);
+    };
+    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;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sohanemon/utils",
-  "version": "4.0.26",
+  "version": "4.0.28",
   "author": "Sohan Emon <sohanemon@outlook.com>",
   "description": "",
   "type": "module",