@sohanemon/utils 4.0.27 → 4.0.29

package/dist/hooks/index.d.ts

@@ -1,28 +1,107 @@
 import * as React from 'react';
 export * from './action';
-export declare const useClickOutside: (callback?: () => void) => 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;
+/**
+ * Runs an effect only once when the component mounts.
+ * @param effect - The effect callback function.
+ */
 export declare function useEffectOnce(effect: React.EffectCallback): void;
-export declare function useUpdateEffect(effect: React.EffectCallback, deps: any[]): 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;
+/**
+ * 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;
+/**
+ * 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;
+    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

@@ -2,6 +2,11 @@
 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 = React.useRef(null);
     const listener = (e) => {
@@ -19,6 +24,11 @@ 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 = React.useMemo(() => {
         switch (tailwindBreakpoint) {
@@ -43,11 +53,10 @@ export function useMediaQuery(tailwindBreakpoint) {
         return false;
     };
     const [matches, setMatches] = React.useState(getMatches(parsedQuery));
-    function handleChange() {
+    const handleChange = () => {
         setMatches(getMatches(parsedQuery));
-    }
-    // biome-ignore lint/correctness/useExhaustiveDependencies: <explanation>
-    React.useEffect(() => {
+    };
+    useIsomorphicEffect(() => {
         const matchMedia = window.matchMedia(parsedQuery);
         handleChange();
         matchMedia.addEventListener('change', handleChange);
@@ -57,12 +66,21 @@ 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) {
     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: <explanation>
+    // biome-ignore lint/correctness/useExhaustiveDependencies: only update specific
     React.useEffect(() => {
         if (isInitialMount.current) {
             isInitialMount.current = false;
@@ -72,6 +90,12 @@ 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] = React.useState(state);
     React.useEffect(() => {
@@ -82,7 +106,15 @@ export function useDebounce(state, delay = 500) {
     }, [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(() => {
@@ -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>
     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] = React.useState(defaultValue);
-    // Use effect to retrieve the stored value from local storage on component mount
     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] = React.useState(defaultValue);
-    // Use effect to retrieve the value from URL parameters on component mount
     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,6 +190,11 @@ 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] = React.useState(null);
     const elementRef = React.useRef(null);
@@ -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,6 +219,10 @@ 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] = React.useState(false);
     React.useEffect(() => {
@@ -181,6 +230,9 @@ export function useIsClient() {
     }, []);
     return isClient;
 }
+/**
+ * Hook to lock scroll by disabling body overflow.
+ */
 export function useLockScroll() {
     React.useLayoutEffect(() => {
         const originalStyle = window.getComputedStyle(document.body).overflow;
@@ -190,6 +242,11 @@ 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] = React.useState(false);
     const copy = (value) => {
@@ -202,16 +259,31 @@ 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 blcokHeight = blockIds.reduce((prevHeight, id) => prevHeight + (document.getElementById(id)?.clientHeight || 0), 0);
-        setTableHeight(window.innerHeight - blcokHeight - margin);
+        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);
     }, []);

package/dist/types/guards.d.ts

@@ -0,0 +1,6 @@
+export type Primitive = string | number | bigint | boolean | symbol | null | undefined;
+export type Falsy = false | '' | 0 | null | undefined;
+export type Nullish = null | undefined;
+export declare const isFalsy: (val: unknown) => val is Falsy;
+export declare const isNullish: (val: unknown) => val is Nullish;
+export declare const isPrimitive: (val: unknown) => val is Primitive;

package/dist/types/guards.js

@@ -0,0 +1,18 @@
+export const isFalsy = (val) => !val;
+export const isNullish = (val) => val == null;
+export const isPrimitive = (val) => {
+    if (val === null || val === undefined) {
+        return true;
+    }
+    switch (typeof val) {
+        case 'string':
+        case 'number':
+        case 'bigint':
+        case 'boolean':
+        case 'symbol': {
+            return true;
+        }
+        default:
+            return false;
+    }
+};

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './utilities';
+export * from './guards';

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export * from './utilities';
+export * from './guards';

package/dist/types/utilities.d.ts

@@ -0,0 +1,26 @@
+export type Keys<T extends object> = keyof T;
+export type Values<T extends object> = T[keyof T];
+export type DeepPartial<T> = T extends Function ? T : T extends Array<infer U> ? Array<DeepPartial<U>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+export type SelectivePartial<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+export type DeepRequired<T> = T extends Function ? T : T extends Array<infer U> ? Array<DeepRequired<U>> : T extends object ? {
+    [K in keyof T]-?: DeepRequired<T[K]>;
+} : T;
+export type DeepReadonly<T> = T extends Function ? T : T extends Array<infer U> ? ReadonlyArray<DeepReadonly<U>> : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+export type Mutable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+export type KeysOfType<T, U> = {
+    [K in keyof T]: T[K] extends U ? K : never;
+}[keyof T];
+export type OmitByType<T, U> = {
+    [K in keyof T as T[K] extends U ? never : K]: T[K];
+};
+export type RequiredKeys<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+export type Diff<T, U> = Omit<T, keyof U> & Omit<U, keyof T>;
+export type Intersection<T extends object, U extends object> = Pick<T, Extract<keyof T, keyof U> & Extract<keyof U, keyof T>>;
+export type Merge<T extends object, U extends object, I = Diff<T, U> & Intersection<U, T> & Diff<U, T>> = Pick<I, keyof I>;
+export type Substract<T extends object, U extends object> = Omit<T, keyof U>;

package/dist/types/utilities.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sohanemon/utils",
-  "version": "4.0.27",
+  "version": "4.0.29",
   "author": "Sohan Emon <sohanemon@outlook.com>",
   "description": "",
   "type": "module",
@@ -18,6 +18,9 @@
       "core": [
         "dist/index.d.ts"
       ],
+      "types": [
+        "dist/types/index.d.ts"
+      ],
       "hooks": [
         "dist/hooks/index.d.ts"
       ],