@sohanemon/utils 6.3.8 → 6.4.0

package/dist/hooks/index.d.cts

@@ -1,13 +1,51 @@
-import { n as Task, t as ScheduleOpts } from "../schedule-CRsY0oqG.cjs";
+import { n as Task, t as ScheduleOpts } from "../schedule-BqFAJlSO.cjs";
 import * as React from "react";
 
 //#region src/hooks/action.d.ts
+/**
+ * Type definition for an action function that takes input and returns a promise.
+ */
 type ActionType<Input, Result> = (input: Input) => Promise<Result>;
+/**
+ * Options for configuring the useAction hook behavior.
+ */
 interface UseActionOptions<_Input, Result> {
+  /** Callback executed when the action succeeds. */
   onSuccess?: (data: Result) => void;
+  /** Callback executed when the action fails. */
   onError?: (error: Error) => void;
+  /** Callback executed when the action completes (success or failure). */
   onSettled?: () => void;
 }
+/**
+ * Hook for managing async actions with loading states and callbacks.
+ *
+ * Provides a clean API for executing async operations with built-in state management,
+ * error handling, and lifecycle callbacks. Supports both synchronous and asynchronous consumption.
+ *
+ * @template Input - The type of input the action accepts
+ * @template Result - The type of result the action returns
+ * @param action - The async function to execute
+ * @param options - Configuration options for callbacks
+ * @returns Object with execution methods, state, and data
+ *
+ * @example
+ * ```tsx
+ * const { execute, isLoading, data, error } = useAction(
+ *   async (userId: string) => {
+ *     const user = await fetchUser(userId);
+ *     return user;
+ *   },
+ *   {
+ *     onSuccess: (user) => console.log('User loaded:', user),
+ *     onError: (err) => console.error('Failed to load user:', err),
+ *   }
+ * );
+ *
+ * // Execute the action
+ * const handleClick = () => execute('user123');
+ * ```
+ */
 declare const useAction: <Input, Result>(action: ActionType<Input, Result>, options?: UseActionOptions<Input, Result>) => {
   execute: (input: Input) => void;
   executeAsync: (input: Input) => Promise<Result>;
@@ -88,14 +126,46 @@ declare function useSchedule(options?: ScheduleOpts): (task: Task) => void;
 declare function useScheduledEffect(effect: () => void | (() => void), deps?: React.DependencyList, options?: ScheduleOpts): void;
 //#endregion
 //#region src/hooks/scroll-tracker.d.ts
+/**
+ * Options for the useScrollTracker hook.
+ */
 interface UseScrollTrackerOptions {
+  /** The scroll distance threshold to consider as "scrolled past". Defaults to 300. */
   threshold?: number;
-  container?: React.RefObject<HTMLElement | null>;
+  /** CSS selector or ref to the scrollable container. Defaults to window. */
+  container?: string | React.RefObject<HTMLElement | null>;
 }
+/**
+ * State returned by the useScrollTracker hook.
+ */
 interface ScrollTrackerState {
+  /** Whether the scroll position has exceeded the threshold. */
   scrolledPast: boolean;
+  /** The current scroll direction. */
   direction: 'forward' | 'backward';
 }
+/**
+ * Hook to track scroll position and direction relative to a threshold.
+ *
+ * Monitors scroll events on a specified container (or window) and provides
+ * information about whether the user has scrolled past a threshold and the scroll direction.
+ *
+ * @param options - Configuration options for scroll tracking
+ * @returns Object containing scroll state: scrolledPast and direction
+ *
+ * @example
+ * ```tsx
+ * const { scrolledPast, direction } = useScrollTracker({ threshold: 200 });
+ *
+ * if (scrolledPast) {
+ *   // Show sticky header or hide elements
+ * }
+ *
+ * if (direction === 'forward') {
+ *   // User is scrolling down
+ * }
+ * ```
+ */
 declare const useScrollTracker: ({
   threshold,
   container
@@ -106,23 +176,63 @@ declare const useScrollTracker: ({
  * 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.
+ *
+ * @example
+ * ```tsx
+ * const ref = useClickOutside(() => {
+ *   console.log('Clicked outside!');
+ *   setIsOpen(false);
+ * });
+ *
+ * return <div ref={ref}>Click outside me</div>;
+ * ```
  */
 declare const useClickOutside: (callback?: () => void) => React.RefObject<HTMLDivElement | null>;
 /**
  * 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.
+ *
+ * @example
+ * ```tsx
+ * const isMobile = useMediaQuery('md'); // false on screens >= 768px
+ * const isLarge = useMediaQuery('lg'); // true on screens >= 1024px
+ * const isDark = useMediaQuery('(prefers-color-scheme: dark)');
+ *
+ * return (
+ *   <div className={isMobile ? 'mobile-layout' : 'desktop-layout'}>
+ *     Content
+ *   </div>
+ * );
+ * ```
  */
 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.
+ *
+ * @example
+ * ```tsx
+ * useEffectOnce(() => {
+ *   console.log('Component mounted');
+ *   // Initialize something once
+ * });
+ * ```
  */
 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.
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount] = useState(0);
+ *
+ * useUpdateEffect(() => {
+ *   console.log('Count updated:', count);
+ * }, [count]); // Runs only when count changes, not on mount
+ * ```
  */
 declare function useUpdateEffect(effect: React.EffectCallback, deps: React.DependencyList): void;
 /**
@@ -130,16 +240,45 @@ declare function useUpdateEffect(effect: React.EffectCallback, deps: React.Depen
  * @param state - The state value to debounce.
  * @param delay - The debounce delay in milliseconds (default: 500ms).
  * @returns The debounced state value.
+ *
+ * @example
+ * ```tsx
+ * const [searchTerm, setSearchTerm] = useState('');
+ * const debouncedSearchTerm = useDebounce(searchTerm, 300);
+ *
+ * useEffect(() => {
+ *   if (debouncedSearchTerm) {
+ *     performSearch(debouncedSearchTerm);
+ *   }
+ * }, [debouncedSearchTerm]);
+ * ```
  */
 declare function useDebounce<T>(state: T, delay?: number): T;
 /**
  * Hook to handle effects with layout synchronization in the browser.
+ * Uses useLayoutEffect on client, useEffect on server.
+ *
+ * @example
+ * ```tsx
+ * useIsomorphicEffect(() => {
+ *   // This runs after DOM mutations on client, during render on server
+ *   measureElement();
+ * }, [dependencies]);
+ * ```
  */
 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).
+ *
+ * @example
+ * ```tsx
+ * useTimeout(() => {
+ *   console.log('Timeout triggered');
+ *   setShowMessage(false);
+ * }, 2000);
+ * ```
  */
 declare function useTimeout(callback: () => void, delay?: number | null): void;
 /**
@@ -147,6 +286,15 @@ declare function useTimeout(callback: () => void, delay?: number | null): void;
  * @param type - The type of the event to listen for.
  * @param listener - The event listener callback.
  * @param options - Options for the event listener.
+ *
+ * @example
+ * ```tsx
+ * useWindowEvent('resize', () => {
+ *   console.log('Window resized');
+ * });
+ *
+ * useWindowEvent('scroll', handleScroll, { passive: true });
+ * ```
  */
 declare function useWindowEvent<K extends keyof WindowEventMap>(type: K, listener: (this: Window, ev: WindowEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
 /**
@@ -158,6 +306,15 @@ type SessionStorageValue<T> = [T, React.Dispatch<React.SetStateAction<T>>];
  * @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.
+ *
+ * @example
+ * ```tsx
+ * const [user, setUser] = useSessionStorage('user', { name: '', email: '' });
+ *
+ * const handleLogin = (userData) => {
+ *   setUser(userData); // Persists to sessionStorage
+ * };
+ * ```
  */
 declare const useSessionStorage: <T extends Record<string, any>>(key: string, defaultValue: T) => SessionStorageValue<T>;
 /**
@@ -169,6 +326,15 @@ type LocalStorageValue<T> = [T, React.Dispatch<React.SetStateAction<T>>];
  * @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.
+ *
+ * @example
+ * ```tsx
+ * const [theme, setTheme] = useLocalStorage('theme', 'light');
+ *
+ * const toggleTheme = () => {
+ *   setTheme(prev => prev === 'light' ? 'dark' : 'light');
+ * };
+ * ```
  */
 declare const useLocalStorage: <T extends Record<string, any>>(key: string, defaultValue: T) => LocalStorageValue<T>;
 /**
@@ -176,27 +342,84 @@ declare const useLocalStorage: <T extends Record<string, any>>(key: string, defa
  * @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.
+ *
+ * @example
+ * ```tsx
+ * const [page, setPage] = useUrlParams('page', 1);
+ *
+ * const nextPage = () => {
+ *   setPage(prev => prev + 1); // Updates URL: ?page=2
+ * };
+ * ```
  */
 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.
+ * Hook to select a DOM element by CSS selector or ref.
+ * @param selector - The CSS selector string or React ref object.
  * @returns The selected DOM element or null if not found.
+ *
+ * @example
+ * ```tsx
+ * // Using CSS selector
+ * const headerElement = useQuerySelector('.header');
+ *
+ * // Using ref
+ * const ref = useRef<HTMLDivElement>(null);
+ * const element = useQuerySelector(ref);
+ *
+ * useEffect(() => {
+ *   if (headerElement) {
+ *     headerElement.style.backgroundColor = 'blue';
+ *   }
+ * }, [headerElement]);
+ * ```
  */
-declare const useQuerySelector: <T extends Element>(selector: string) => T | null;
+declare const useQuerySelector: <T extends Element>(selector: string | React.RefObject<T | null>) => 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.
+ *
+ * @example
+ * ```tsx
+ * const isClient = useIsClient();
+ *
+ * if (isClient) {
+ *   // Client-side only code
+ *   window.addEventListener('resize', handleResize);
+ * }
+ * ```
  */
 declare function useIsClient(): boolean;
 /**
  * Hook to lock scroll by disabling body overflow.
+ *
+ * @example
+ * ```tsx
+ * const [isModalOpen, setIsModalOpen] = useState(false);
+ *
+ * if (isModalOpen) {
+ *   useLockScroll(); // Prevents background scrolling
+ * }
+ *
+ * return <Modal open={isModalOpen} />;
+ * ```
  */
 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.
+ *
+ * @example
+ * ```tsx
+ * const { isCopied, copy } = useCopyToClipboard();
+ *
+ * return (
+ *   <button onClick={() => copy('Hello World!')}>
+ *     {isCopied ? 'Copied!' : 'Copy Text'}
+ *   </button>
+ * );
+ * ```
  */
 declare function useCopyToClipboard({
   timeout
@@ -207,19 +430,37 @@ declare function useCopyToClipboard({
   copy: (value: string) => void;
 };
 /**
- * Properties for height calculation.
+ * Configuration options for height calculation.
  */
 type CalculationProps2 = {
+  /** Array of element IDs whose heights should be considered in calculation. */
   blockIds: string[];
+  /** Whether to recalculate on resize. If string, specifies ID of element to observe for changes. */
   dynamic?: boolean | string;
+  /** Additional margin to add/subtract from calculation. */
   margin?: number;
+  /** Whether to subtract block heights from viewport (true) or add them (false). */
   substract?: boolean;
 };
 /**
+ * Hook to calculate available height for an element based on viewport and other element heights.
+ *
+ * Useful for creating full-height layouts where you need to account for fixed headers,
+ * footers, or other elements that take up vertical space.
  *
- * 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.
+ * @returns The calculated height in pixels.
+ *
+ * @example
+ * ```tsx
+ * const contentHeight = useHeightCalculation({
+ *   blockIds: ['header', 'footer'],
+ *   margin: 20,
+ *   dynamic: true
+ * });
+ *
+ * return <div style={{ height: contentHeight }}>Content</div>;
+ * ```
  */
 declare const useHeightCalculation: ({
   blockIds,
@@ -228,13 +469,18 @@ declare const useHeightCalculation: ({
   dynamic
 }: CalculationProps2) => number;
 /**
- * Properties for DOM calculation.
+ * Configuration options for DOM dimension calculation.
  */
 type CalculationProps = {
+  /** Array of element IDs whose dimensions should be considered. */
   blockIds: string[];
+  /** Whether to recalculate on resize. If string, specifies ID of element to observe. */
   dynamic?: boolean | string;
+  /** Additional margin to add/subtract from calculations. */
   margin?: number;
+  /** Whether to subtract block dimensions from viewport (true) or add them (false). */
   substract?: boolean;
+  /** Callback fired whenever dimensions change with detailed results. */
   onChange?: (results: {
     blocksHeight: number;
     blocksWidth: number;
@@ -243,9 +489,27 @@ type CalculationProps = {
   }) => void;
 };
 /**
- * Hook to calculate dimensions (height and width) of an element based on viewport and other block dimensions.
+ * Hook to calculate available dimensions for an element based on viewport and other element dimensions.
+ *
+ * Provides both height and width calculations with optional change callbacks.
+ * Useful for responsive layouts that need to adapt to dynamic content or viewport changes.
+ *
  * @param params - Configuration object for dimension calculation.
- * @returns An object containing the calculated height and width.
+ * @returns An object containing the calculated height and width in pixels.
+ *
+ * @example
+ * ```tsx
+ * const { height, width } = useDomCalculation({
+ *   blockIds: ['sidebar', 'header'],
+ *   margin: 10,
+ *   dynamic: true,
+ *   onChange: ({ remainingWidth, remainingHeight }) => {
+ *     console.log(`Available: ${remainingWidth}x${remainingHeight}`);
+ *   }
+ * });
+ *
+ * return <div style={{ height, width }}>Responsive content</div>;
+ * ```
  */
 declare const useDomCalculation: ({
   blockIds,
@@ -258,16 +522,55 @@ declare const useDomCalculation: ({
   width: number;
 };
 /**
- * Hook to detect if the user is scrolling.
- * @returns An object containing the isScrolling state and a ref to the scrollable container.
+ * Hook to detect if the user is currently scrolling within a container.
+ *
+ * Tracks scroll events and provides a debounced "is scrolling" state that
+ * becomes false 150ms after the last scroll event. Useful for showing/hiding
+ * scroll indicators, triggering animations, or optimizing performance during scroll.
+ *
+ * @returns An object containing:
+ * - `isScrolling`: Boolean indicating if scrolling is currently active
+ * - `scrollableContainerRef`: Ref to attach to the scrollable element
+ *
+ * @example
+ * ```tsx
+ * const { isScrolling, scrollableContainerRef } = useIsScrolling();
+ *
+ * return (
+ *   <div ref={scrollableContainerRef}>
+ *     {isScrolling && <ScrollIndicator />}
+ *     <Content />
+ *   </div>
+ * );
+ * ```
  */
 declare const useIsScrolling: () => {
   isScrolling: boolean;
   scrollableContainerRef: React.RefObject<HTMLElement | null>;
 };
 /**
- * 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.
+ * Hook to detect if the scroll position is at the top of a container.
+ *
+ * Monitors scroll position and determines if the user has scrolled past
+ * a threshold from the top. Useful for sticky headers, navigation states,
+ * or triggering actions when reaching the top of content.
+ *
+ * @param offset - Optional offset in pixels from the top to consider as "at top" (default: 10).
+ * @returns An object containing:
+ * - `isAtTop`: Boolean indicating if scroll position is at the top
+ * - `scrollableContainerRef`: Ref to attach to the scrollable element
+ *
+ * @example
+ * ```tsx
+ * const { isAtTop, scrollableContainerRef } = useIsAtTop({ offset: 50 });
+ *
+ * return (
+ *   <div ref={scrollableContainerRef}>
+ *     <Header className={isAtTop ? 'transparent' : 'solid'} />
+ *     <Content />
+ *   </div>
+ * );
+ * ```
  */
 declare const useIsAtTop: ({
   offset
@@ -282,8 +585,20 @@ interface UseIntersectionOptions extends IntersectionObserverInit {
   onInteractionEnd?: () => void;
 }
 /**
- * React hook that tracks when an element enters or leaves the viewport
- * using the Intersection Observer API.
+ * React hook that tracks when an element enters or leaves the viewport using the Intersection Observer API.
+ *
+ * Provides efficient viewport detection for lazy loading, animations, analytics,
+ * and other effects that should trigger based on element visibility.
+ *
+ * @param options - Configuration for the intersection observer.
+ * @param options.threshold - How much of the element must be visible (0-1) to trigger intersection.
+ * @param options.root - The element to use as the viewport for checking visibility.
+ * @param options.rootMargin - Margin around the root element for intersection calculation.
+ * @param options.onInteractionStart - Callback when element enters viewport.
+ * @param options.onInteractionEnd - Callback when element leaves viewport.
+ * @returns Object containing:
+ * - `ref`: React ref to attach to the observed element.
+ * - `isIntersecting`: Whether the element is currently visible in the viewport.
  *
  * @example
  * ```tsx
@@ -293,13 +608,12 @@ interface UseIntersectionOptions extends IntersectionObserverInit {
  *   onInteractionEnd: () => console.log('🙈 Element left viewport'),
  * });
  *
- * return <div ref={ref}>Watch me</div>;
+ * return (
+ *   <div ref={ref} className={isIntersecting ? 'visible' : 'hidden'}>
+ *     Watch me fade in/out
+ *   </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.
  */
 declare const useIntersection: ({
   threshold,