@omnitron-dev/prism 0.2.0 → 0.3.0

package/dist/index-nmJ8Muwg.d.ts

@@ -1,2368 +0,0 @@
-import { q as ThemePreset, o as ThemeMode, n as ThemeDirection, f as ComponentDensity } from './theme-B4Q3Bg5o.js';
-import './use-timeout-D7U3EAtH.js';
-import '@mui/material';
-import { RefObject, Dispatch, SetStateAction, SyntheticEvent, MouseEvent, EffectCallback, DependencyList, useEffect } from 'react';
-import './popover-Dmw7SJLR.js';
-
-/**
- * Cookie Utilities
- *
- * Type-safe cookie management with JSON serialization.
- *
- * @module @omnitron-dev/prism/utils
- */
-/**
- * Cookie options for setting cookies.
- */
-interface CookieOptions {
-    /** Enable secure flag (HTTPS only) */
-    secure?: boolean;
-    /** Days until expiration */
-    daysUntilExpiration?: number;
-    /** SameSite policy */
-    sameSite?: 'strict' | 'lax' | 'none';
-    /** Cookie domain */
-    domain?: string;
-    /** Cookie path */
-    path?: string;
-}
-/**
- * Check if cookies are available.
- *
- * @returns {boolean} True if cookies are available
- */
-declare function cookiesAvailable(): boolean;
-/**
- * Get a cookie value with JSON parsing.
- *
- * @template T - Type of the stored value
- * @param {string} key - Cookie name
- * @returns {T | null} Parsed value or null
- *
- * @example
- * ```ts
- * const user = getCookie<User>('user');
- * ```
- */
-declare function getCookie<T>(key: string): T | null;
-/**
- * Set a cookie with JSON serialization.
- *
- * @template T - Type of the value
- * @param {string} key - Cookie name
- * @param {T} value - Value to store
- * @param {CookieOptions} [options] - Cookie options
- *
- * @example
- * ```ts
- * setCookie('user', { name: 'John' }, { daysUntilExpiration: 7 });
- * ```
- */
-declare function setCookie<T>(key: string, value: T, options?: CookieOptions): void;
-/**
- * Remove a cookie.
- *
- * @param {string} key - Cookie name
- * @param {Pick<CookieOptions, 'domain' | 'path'>} [options] - Cookie options
- *
- * @example
- * ```ts
- * removeCookie('user');
- * ```
- */
-declare function removeCookie(key: string, options?: Pick<CookieOptions, 'domain' | 'path'>): void;
-
-/**
- * Async state.
- */
-interface AsyncState<T> {
-    /** Data result */
-    data: T | null;
-    /** Loading state */
-    loading: boolean;
-    /** Error state */
-    error: Error | null;
-}
-/**
- * Return type for useAsync hook.
- */
-interface UseAsyncReturn<T, Args extends unknown[]> extends AsyncState<T> {
-    /** Execute the async function */
-    execute: (...args: Args) => Promise<T>;
-    /** Reset state */
-    reset: () => void;
-    /** Set data manually */
-    setData: (data: T | null) => void;
-    /** Set error manually */
-    setError: (error: Error | null) => void;
-}
-/**
- * Options for useAsync hook.
- */
-interface UseAsyncOptions<T> {
-    /** Initial data */
-    initialData?: T | null;
-    /** Auto-execute on mount */
-    immediate?: boolean;
-    /** On success callback */
-    onSuccess?: (data: T) => void;
-    /** On error callback */
-    onError?: (error: Error) => void;
-}
-/**
- * useAsync - Hook for managing async operations.
- *
- * @example
- * ```tsx
- * // Basic usage
- * const { data, loading, error, execute } = useAsync(fetchUser);
- *
- * // Auto-execute on mount
- * const { data, loading } = useAsync(fetchUsers, { immediate: true });
- *
- * // With callbacks
- * const { execute } = useAsync(createUser, {
- *   onSuccess: (user) => toast.success(`Created ${user.name}`),
- *   onError: (err) => toast.error(err.message),
- * });
- *
- * // In a component
- * const handleSubmit = async () => {
- *   const result = await execute(formData);
- *   if (result) navigate('/success');
- * };
- * ```
- */
-declare function useAsync<T, Args extends unknown[] = []>(asyncFn: (...args: Args) => Promise<T>, options?: UseAsyncOptions<T>): UseAsyncReturn<T, Args>;
-/**
- * Return type for useAsyncFn hook (simpler version).
- */
-interface UseAsyncFnReturn<T, Args extends unknown[]> {
-    /** Execute the async function */
-    execute: (...args: Args) => Promise<T | undefined>;
-    /** Loading state */
-    loading: boolean;
-    /** Error state */
-    error: Error | null;
-}
-/**
- * useAsyncFn - Simpler hook for async functions without data tracking.
- *
- * @example
- * ```tsx
- * const { execute, loading, error } = useAsyncFn(deleteUser);
- *
- * const handleDelete = async (id: string) => {
- *   await execute(id);
- *   refetch(); // Trigger parent refresh
- * };
- * ```
- */
-declare function useAsyncFn<T, Args extends unknown[] = []>(asyncFn: (...args: Args) => Promise<T>): UseAsyncFnReturn<T, Args>;
-
-/**
- * Scroll position data.
- */
-interface ScrollPosition {
-    /** Scroll position from top */
-    x: number;
-    /** Scroll position from left */
-    y: number;
-    /** Scroll direction (1 = down/right, -1 = up/left, 0 = initial) */
-    directionX: -1 | 0 | 1;
-    directionY: -1 | 0 | 1;
-    /** Whether scrolled past threshold */
-    isScrolled: boolean;
-    /** Whether at the top */
-    isAtTop: boolean;
-    /** Whether at the bottom */
-    isAtBottom: boolean;
-}
-/**
- * Options for useScrollPosition hook.
- */
-interface UseScrollPositionOptions {
-    /** Element to track (default: window) */
-    element?: HTMLElement | null;
-    /** Throttle delay in ms (default: 100) */
-    throttle?: number;
-    /** Threshold to consider "scrolled" (default: 0) */
-    threshold?: number;
-    /** Offset from bottom to consider "at bottom" (default: 10) */
-    bottomOffset?: number;
-}
-/**
- * useScrollPosition - Hook for tracking scroll position.
- *
- * @example
- * ```tsx
- * // Track window scroll
- * const { y, isScrolled, directionY } = useScrollPosition();
- *
- * // Show header shadow when scrolled
- * <Header className={isScrolled ? 'shadow' : ''} />
- *
- * // Hide header on scroll down, show on scroll up
- * const showHeader = directionY !== 1 || y < 50;
- *
- * // Track specific element
- * const containerRef = useRef<HTMLDivElement>(null);
- * const { isAtBottom } = useScrollPosition({ element: containerRef.current });
- *
- * // Load more when near bottom
- * useEffect(() => {
- *   if (isAtBottom) loadMore();
- * }, [isAtBottom]);
- * ```
- */
-declare function useScrollPosition(options?: UseScrollPositionOptions): ScrollPosition;
-/**
- * useScrollToTop - Hook for scrolling to top functionality.
- *
- * @example
- * ```tsx
- * const { scrollToTop, showButton } = useScrollToTop({ threshold: 300 });
- *
- * {showButton && (
- *   <Fab onClick={scrollToTop}>
- *     <ArrowUpIcon />
- *   </Fab>
- * )}
- * ```
- */
-declare function useScrollToTop(options?: {
-    threshold?: number;
-}): {
-    scrollToTop: () => void;
-    showButton: boolean;
-};
-/**
- * useScrollLock - Hook for locking body scroll.
- *
- * @example
- * ```tsx
- * const { lock, unlock, isLocked } = useScrollLock();
- *
- * // Lock when modal opens
- * useEffect(() => {
- *   if (isOpen) lock();
- *   else unlock();
- * }, [isOpen]);
- * ```
- */
-declare function useScrollLock(): {
-    lock: () => void;
-    unlock: () => void;
-    isLocked: boolean;
-};
-
-/**
- * Window size data.
- */
-interface WindowSize {
-    /** Window width */
-    width: number;
-    /** Window height */
-    height: number;
-    /** Is mobile (< 600px) */
-    isMobile: boolean;
-    /** Is tablet (600px - 960px) */
-    isTablet: boolean;
-    /** Is desktop (>= 960px) */
-    isDesktop: boolean;
-    /** Is large desktop (>= 1280px) */
-    isLargeDesktop: boolean;
-}
-/**
- * Breakpoint definitions (following MUI defaults).
- */
-interface Breakpoints {
-    xs: number;
-    sm: number;
-    md: number;
-    lg: number;
-    xl: number;
-}
-/**
- * Options for useWindowSize hook.
- */
-interface UseWindowSizeOptions {
-    /** Custom breakpoints */
-    breakpoints?: Partial<Breakpoints>;
-    /** Debounce delay in ms (default: 100) */
-    debounce?: number;
-    /** Initial width for SSR (default: 1200) */
-    initialWidth?: number;
-    /** Initial height for SSR (default: 800) */
-    initialHeight?: number;
-}
-/**
- * useWindowSize - Hook for tracking window dimensions.
- *
- * @example
- * ```tsx
- * // Basic usage
- * const { width, height, isMobile, isDesktop } = useWindowSize();
- *
- * // Responsive rendering
- * if (isMobile) {
- *   return <MobileLayout />;
- * }
- * return <DesktopLayout />;
- *
- * // Responsive columns
- * const columns = isMobile ? 1 : isTablet ? 2 : 4;
- *
- * // Custom breakpoints
- * const { isMobile } = useWindowSize({
- *   breakpoints: { sm: 768 }
- * });
- * ```
- */
-declare function useWindowSize(options?: UseWindowSizeOptions): WindowSize;
-/**
- * Return type for useResponsiveQuery hook.
- */
-type UseResponsiveQueryReturn = boolean;
-/**
- * useResponsiveQuery - Hook for CSS media query matching.
- *
- * Note: For the simpler MUI-style useMediaQuery, see @omnitron-dev/prism/core.
- * This hook provides a standalone implementation without MUI dependency.
- *
- * @example
- * ```tsx
- * // Direct media query
- * const prefersDark = useResponsiveQuery('(prefers-color-scheme: dark)');
- * const isRetina = useResponsiveQuery('(min-resolution: 2dppx)');
- *
- * // Responsive
- * const isLargeScreen = useResponsiveQuery('(min-width: 1200px)');
- * ```
- */
-declare function useResponsiveQuery(query: string): UseResponsiveQueryReturn;
-/**
- * useBreakpoint - Hook for checking current breakpoint.
- *
- * @example
- * ```tsx
- * const breakpoint = useBreakpoint();
- *
- * // Current breakpoint name
- * console.log(breakpoint); // 'md'
- *
- * // Check specific breakpoint
- * const { isUp, isDown, isOnly, isBetween } = useBreakpointChecks();
- *
- * if (isUp('md')) {
- *   // Screen is md or larger
- * }
- * ```
- */
-declare function useBreakpoint(customBreakpoints?: Partial<Breakpoints>): 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-/**
- * Return type for useBreakpointChecks hook.
- */
-interface BreakpointChecks {
-    /** Check if width is >= breakpoint */
-    isUp: (breakpoint: keyof Breakpoints) => boolean;
-    /** Check if width is < breakpoint */
-    isDown: (breakpoint: keyof Breakpoints) => boolean;
-    /** Check if width is within breakpoint range */
-    isOnly: (breakpoint: keyof Breakpoints) => boolean;
-    /** Check if width is between two breakpoints */
-    isBetween: (start: keyof Breakpoints, end: keyof Breakpoints) => boolean;
-}
-/**
- * useBreakpointChecks - Hook for advanced breakpoint checking.
- *
- * @example
- * ```tsx
- * const { isUp, isDown, isOnly, isBetween } = useBreakpointChecks();
- *
- * isUp('md');           // true if >= 900px
- * isDown('lg');         // true if < 1200px
- * isOnly('md');         // true if 900px - 1199px
- * isBetween('sm', 'lg'); // true if 600px - 1199px
- * ```
- */
-declare function useBreakpointChecks(customBreakpoints?: Partial<Breakpoints>): BreakpointChecks;
-
-/**
- * useClientRect Hook
- *
- * Gets bounding client rect and scroll dimensions of a DOM element.
- * SSR-safe with automatic updates on resize/scroll.
- *
- * @module @omnitron-dev/prism/hooks
- */
-
-/**
- * Scroll element dimensions.
- */
-interface ScrollElValue {
-    /** Scrollable width */
-    scrollWidth: number;
-    /** Scrollable height */
-    scrollHeight: number;
-}
-/**
- * DOMRect values (SSR-safe).
- */
-interface DOMRectValue {
-    top: number;
-    right: number;
-    bottom: number;
-    left: number;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/**
- * Return type for useClientRect hook.
- */
-interface UseClientRectReturn<T extends HTMLElement = HTMLElement> extends DOMRectValue, ScrollElValue {
-    /** Ref to attach to the target element */
-    elementRef: RefObject<T | null>;
-    /** Force update measurements */
-    update: () => void;
-}
-/**
- * useClientRect - Hook to get bounding rect and scroll dimensions.
- *
- * @example
- * ```tsx
- * // Basic usage - auto-creates ref
- * const { elementRef, width, height, top, left } = useClientRect();
- *
- * return (
- *   <div ref={elementRef}>
- *     Width: {width}, Height: {height}
- *   </div>
- * );
- *
- * // With existing ref
- * const myRef = useRef<HTMLDivElement>(null);
- * const { width, scrollWidth } = useClientRect(myRef);
- *
- * // Listen to scroll events
- * const { y, scrollHeight } = useClientRect(ref, 'scroll');
- *
- * // Calculate scroll progress
- * const progress = y / (scrollHeight - height);
- * ```
- */
-declare function useClientRect<T extends HTMLElement = HTMLElement>(inputRef?: RefObject<T | null>, eventType?: 'scroll' | 'resize'): UseClientRectReturn<T>;
-
-/**
- * usePopoverHover Hook
- *
- * Manages hover-based popover state with proper enter/leave handling.
- * Different from click-based popovers - opens on mouse enter, closes on leave.
- *
- * @module @omnitron-dev/prism/hooks
- */
-
-/**
- * Return type for usePopoverHover hook.
- */
-interface UsePopoverHoverReturn<T extends HTMLElement = HTMLElement> {
-    /** Whether the popover is open */
-    open: boolean;
-    /** The element the popover is anchored to (for MUI Popover) */
-    anchorEl: T | null;
-    /** Handler for mouse enter - opens the popover */
-    onOpen: () => void;
-    /** Handler for mouse leave - closes the popover */
-    onClose: () => void;
-    /** Ref to attach to the trigger element */
-    elementRef: RefObject<T | null>;
-    /** Manual control of open state */
-    setOpen: Dispatch<SetStateAction<boolean>>;
-}
-/**
- * usePopoverHover - Hook for hover-based popover management.
- *
- * This hook is SSR-safe. It doesn't access browser APIs directly.
- * During SSR, elementRef.current is null and open defaults to false,
- * so anchorEl will always be null on the server.
- *
- * @example
- * ```tsx
- * // Basic usage
- * const { open, anchorEl, onOpen, onClose, elementRef } = usePopoverHover<HTMLButtonElement>();
- *
- * return (
- *   <>
- *     <Button
- *       ref={elementRef}
- *       onMouseEnter={onOpen}
- *       onMouseLeave={onClose}
- *     >
- *       Hover me
- *     </Button>
- *     <Popover
- *       open={open}
- *       anchorEl={anchorEl}
- *       onClose={onClose}
- *       anchorOrigin={{ vertical: 'bottom', horizontal: 'left' }}
- *     >
- *       <Typography sx={{ p: 2 }}>Popover content</Typography>
- *     </Popover>
- *   </>
- * );
- *
- * // With existing ref
- * const myRef = useRef<HTMLDivElement>(null);
- * const { open, onOpen, onClose } = usePopoverHover(myRef);
- *
- * // With delay (using inline)
- * const { open, anchorEl, elementRef, setOpen } = usePopoverHover();
- * const timeoutRef = useRef<NodeJS.Timeout>();
- *
- * const handleOpen = () => {
- *   clearTimeout(timeoutRef.current);
- *   setOpen(true);
- * };
- *
- * const handleClose = () => {
- *   timeoutRef.current = setTimeout(() => setOpen(false), 200);
- * };
- * ```
- */
-declare function usePopoverHover<T extends HTMLElement = HTMLElement>(inputRef?: RefObject<T | null>): UsePopoverHoverReturn<T>;
-
-/**
- * Options for useCookies hook.
- */
-interface UseCookiesOptions extends CookieOptions {
-    /**
-     * If true, initializes the cookie with the initial value if not set.
-     * @default true
-     */
-    initializeWithValue?: boolean;
-}
-/**
- * Return type for useCookies hook.
- */
-interface UseCookiesReturn<T> {
-    /** Current state value */
-    state: T;
-    /** Reset state to initial value and remove cookie */
-    resetState: (defaultState?: T) => void;
-    /** Update the entire state or merge partial state (for objects) */
-    setState: (updateState: T | Partial<T>) => void;
-    /** Update a specific field in an object state */
-    setField: <K extends keyof T>(name: K, updateValue: T[K]) => void;
-}
-/**
- * Hook to manage state with cookies.
- *
- * Automatically syncs state with cookies and supports:
- * - Primitive values (string, number, boolean)
- * - Object values with partial updates
- * - Type-safe field updates
- *
- * @template T - Type of the state value
- * @param key - Cookie name
- * @param initialState - Initial state value
- * @param options - Cookie options
- * @returns State and update functions
- *
- * @example
- * ```tsx
- * // Primitive value
- * const { state, setState, resetState } = useCookies('theme', 'light');
- *
- * // Object value with partial updates
- * const { state, setState, setField, resetState } = useCookies('user', {
- *   name: '',
- *   age: 0,
- *   preferences: { notifications: true },
- * });
- *
- * // Update single field
- * setField('name', 'John');
- *
- * // Partial update
- * setState({ age: 25 });
- *
- * // Reset to initial value
- * resetState();
- * ```
- */
-declare function useCookies<T>(key: string, initialState: T, options?: UseCookiesOptions): UseCookiesReturn<T>;
-
-/**
- * useDoubleClick Hook
- *
- * Differentiates between single and double click events.
- * Single click is delayed to ensure it's not a double click.
- *
- * @module @omnitron-dev/prism/hooks
- */
-
-/**
- * Props for useDoubleClick hook.
- */
-interface UseDoubleClickProps {
-    /**
-     * Timeout in milliseconds to differentiate between single and double clicks.
-     * @default 250
-     */
-    timeout?: number;
-    /** Handler for single click (optional) */
-    click?: (event: SyntheticEvent) => void;
-    /** Handler for double click (required) */
-    doubleClick: (event: SyntheticEvent) => void;
-}
-/**
- * Return type - a click handler function.
- */
-type UseDoubleClickReturn = (event: MouseEvent<HTMLElement>) => void;
-/**
- * Hook to handle single and double click events on an element.
- *
- * Uses event.detail to detect click count:
- * - detail === 1: single click (delayed by timeout)
- * - detail === 2: double click (immediate)
- *
- * The single click handler is called after a timeout, but only if
- * no second click occurs within that time.
- *
- * @param props - Hook configuration
- * @returns Click handler function to attach to element
- *
- * @example
- * ```tsx
- * function FileItem({ file }) {
- *   const handleClick = useDoubleClick({
- *     click: () => selectFile(file),
- *     doubleClick: () => openFile(file),
- *     timeout: 300,
- *   });
- *
- *   return (
- *     <div onClick={handleClick}>
- *       {file.name}
- *     </div>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Double-click only (no single click handler)
- * const handleClick = useDoubleClick({
- *   doubleClick: () => console.log('Double clicked!'),
- * });
- * ```
- */
-declare function useDoubleClick({ click, doubleClick, timeout }: UseDoubleClickProps): UseDoubleClickReturn;
-
-/**
- * useBackToTop Hook
- *
- * Manages visibility of a "Back to Top" button based on scroll position.
- * Supports both percentage-based and pixel-based visibility thresholds.
- *
- * @module @omnitron-dev/prism/hooks
- */
-
-/**
- * Return type for useBackToTop hook.
- */
-interface UseBackToTopReturn {
-    /** Whether the "Back to Top" button should be visible */
-    isVisible: boolean;
-    /** Function to scroll smoothly to top */
-    onBackToTop: () => void;
-    /** Manual visibility control */
-    setIsVisible: Dispatch<SetStateAction<boolean>>;
-}
-/**
- * Hook to manage the visibility of a "Back to Top" button based on scroll position.
- *
- * Two modes are supported:
- * - **Percentage mode**: Button becomes visible when scrolled past N% of the page.
- *   Pass a string like '90%' as the threshold.
- * - **Pixel mode**: Button becomes visible when within N pixels of the bottom.
- *   Pass a number like 80 as the threshold.
- *
- * @param threshold - Visibility threshold
- *   - String with '%' (e.g., '90%'): Show when scroll progress >= this percentage
- *   - Number (e.g., 80): Show when within this many pixels from bottom
- * @param debounce - Whether to debounce the scroll handler (100ms)
- * @returns Visibility state and scroll control functions
- *
- * @example
- * ```tsx
- * // Show when scrolled 90% down the page
- * const { isVisible, onBackToTop } = useBackToTop('90%');
- *
- * // Show when within 80px of the bottom
- * const { isVisible, onBackToTop } = useBackToTop(80);
- *
- * // With debouncing for better performance
- * const { isVisible, onBackToTop } = useBackToTop('85%', true);
- *
- * return (
- *   <Fade in={isVisible}>
- *     <Fab onClick={onBackToTop} sx={{ position: 'fixed', bottom: 16, right: 16 }}>
- *       <KeyboardArrowUpIcon />
- *     </Fab>
- *   </Fade>
- * );
- * ```
- */
-declare function useBackToTop(threshold?: string | number, debounce?: boolean): UseBackToTopReturn;
-
-/**
- * useCountdownSeconds Hook
- *
- * Simple countdown timer in seconds. Ideal for OTP resend timers,
- * session timeouts, and other time-limited operations.
- *
- * @module @omnitron-dev/prism/hooks
- */
-
-/**
- * Return type for useCountdownSeconds hook.
- */
-interface UseCountdownSecondsReturn {
-    /** Current countdown value in seconds */
-    value: number;
-    /** Start the countdown */
-    start: () => void;
-    /** Reset countdown to initial value and stop */
-    reset: () => void;
-    /** Whether countdown is currently active */
-    isCounting: boolean;
-    /** Manually set the countdown value */
-    setValue: Dispatch<SetStateAction<number>>;
-}
-/**
- * Hook to create a simple countdown timer in seconds.
- *
- * Perfect for:
- * - OTP resend timers
- * - Session timeout warnings
- * - Rate limiting UI feedback
- * - Game timers
- *
- * @param initialSeconds - Initial countdown value in seconds
- * @returns Countdown state and control functions
- *
- * @example
- * ```tsx
- * // OTP resend timer
- * function OTPForm() {
- *   const { value, start, reset, isCounting } = useCountdownSeconds(60);
- *
- *   const handleResend = async () => {
- *     await resendOTP();
- *     reset();
- *     start();
- *   };
- *
- *   return (
- *     <div>
- *       <input placeholder="Enter OTP" />
- *       <button onClick={handleResend} disabled={isCounting}>
- *         {isCounting ? `Resend in ${value}s` : 'Resend OTP'}
- *       </button>
- *     </div>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Session timeout warning
- * function SessionWarning() {
- *   const { value, start, isCounting } = useCountdownSeconds(30);
- *
- *   useEffect(() => {
- *     if (showWarning) start();
- *   }, [showWarning]);
- *
- *   useEffect(() => {
- *     if (value === 0) logout();
- *   }, [value]);
- *
- *   return isCounting && (
- *     <Alert severity="warning">
- *       Session expires in {value} seconds
- *     </Alert>
- *   );
- * }
- * ```
- */
-declare function useCountdownSeconds(initialSeconds: number): UseCountdownSecondsReturn;
-
-/**
- * Return type for useCountdownDate hook.
- */
-type UseCountdownDateReturn = {
-    /** Formatted days (with leading zero) */
-    days: string;
-    /** Formatted hours (with leading zero) */
-    hours: string;
-    /** Formatted minutes (with leading zero) */
-    minutes: string;
-    /** Formatted seconds (with leading zero) */
-    seconds: string;
-};
-/**
- * Custom hook to create a countdown timer to a target date.
- *
- * @param targetDate - The target date to count down to
- * @param placeholder - The placeholder value to display before the countdown starts (default: '- -')
- *
- * @returns An object containing the current countdown values in days, hours, minutes, and seconds
- *
- * @example
- * ```tsx
- * function SaleCountdown() {
- *   const { days, hours, minutes, seconds } = useCountdownDate(
- *     new Date('2024-12-31T23:59:59')
- *   );
- *
- *   return (
- *     <div>
- *       <span>{days}d</span>
- *       <span>{hours}h</span>
- *       <span>{minutes}m</span>
- *       <span>{seconds}s</span>
- *     </div>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With custom placeholder
- * const countdown = useCountdownDate(launchDate, '--');
- * ```
- */
-declare function useCountdownDate(targetDate: Date, placeholder?: string): UseCountdownDateReturn;
-
-/**
- * useScrollOffsetTop Hook
- *
- * Manages offset top state based on scroll position.
- * Can track against window or a specific element's offset.
- *
- * This hook is SSR-safe - scroll tracking only runs on the client.
- *
- * Ported from minimal-shared for Prism design system.
- *
- * @module @omnitron-dev/prism/hooks/use-scroll-offset-top
- */
-
-/**
- * Return type for useScrollOffsetTop hook.
- */
-type UseScrollOffsetTopReturn<T extends HTMLElement = HTMLElement> = {
-    /** Whether the scroll position is past the offset threshold */
-    offsetTop: boolean;
-    /** Ref to attach to element for tracking its offset (optional) */
-    elementRef: RefObject<T | null>;
-};
-/**
- * Custom hook to manage the offset top state based on scroll position.
- *
- * Can be used in two ways:
- * 1. Track against a fixed pixel value (window scroll)
- * 2. Track against an element's offset (using returned ref)
- *
- * @param defaultValue - The offset value at which the state changes (default: 0)
- *
- * @returns An object containing offsetTop boolean and elementRef
- *
- * @example
- * ```tsx
- * // Track window scroll against fixed value
- * function StickyHeader() {
- *   const { offsetTop } = useScrollOffsetTop(80);
- *
- *   return (
- *     <AppBar position={offsetTop ? 'fixed' : 'static'}>
- *       <Toolbar>Header</Toolbar>
- *     </AppBar>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Track scroll against element offset
- * function HeaderWithBanner() {
- *   const { offsetTop, elementRef } = useScrollOffsetTop<HTMLDivElement>();
- *
- *   return (
- *     <>
- *       <div ref={elementRef}>Banner Content</div>
- *       <AppBar
- *         position={offsetTop ? 'fixed' : 'static'}
- *         sx={{ top: offsetTop ? 0 : 'auto' }}
- *       >
- *         <Toolbar>Header</Toolbar>
- *       </AppBar>
- *     </>
- *   );
- * }
- * ```
- */
-declare function useScrollOffsetTop<T extends HTMLElement = HTMLElement>(defaultValue?: number): UseScrollOffsetTopReturn<T>;
-
-/**
- * Configuration values that can be controlled via URL params.
- */
-interface UrlConfigValues {
-    /** Theme preset */
-    preset?: ThemePreset;
-    /** Light/dark/system mode */
-    mode?: ThemeMode;
-    /** Primary color (hex) */
-    primary?: string;
-    /** Text direction */
-    direction?: ThemeDirection;
-    /** Component density */
-    density?: ComponentDensity;
-    /** Contrast mode */
-    contrast?: 'default' | 'high';
-}
-/**
- * Options for useConfigFromQuery hook.
- */
-interface UseConfigFromQueryOptions {
-    /** Query parameter names mapping (default: 'preset', 'mode', 'primary', etc.) */
-    paramNames?: {
-        preset?: string;
-        mode?: string;
-        primary?: string;
-        direction?: string;
-        density?: string;
-        contrast?: string;
-    };
-    /** Callback when config changes from URL */
-    onConfigChange?: (config: UrlConfigValues) => void;
-    /** Enable two-way sync (updates URL when config changes) */
-    syncToUrl?: boolean;
-}
-/**
- * Return type for useConfigFromQuery hook.
- */
-interface UseConfigFromQueryReturn {
-    /** Parsed config values from URL */
-    configFromUrl: UrlConfigValues;
-    /** Update URL with new config values */
-    updateUrl: (values: Partial<UrlConfigValues>) => void;
-    /** Clear all config from URL */
-    clearUrl: () => void;
-    /** Generate URL with config values */
-    generateUrl: (values: Partial<UrlConfigValues>, baseUrl?: string) => string;
-    /** Check if URL has any config params */
-    hasUrlConfig: boolean;
-}
-/**
- * Hook to sync theme configuration with URL query parameters.
- *
- * Enables shareable configuration links for demos, previews, and design reviews.
- *
- * @param options - Hook options
- * @returns Object with URL config parsing and manipulation utilities
- *
- * @example
- * ```tsx
- * import { useConfigFromQuery } from '@omnitron-dev/prism/hooks';
- *
- * function ThemeSettings() {
- *   const {
- *     configFromUrl,
- *     updateUrl,
- *     generateUrl,
- *     hasUrlConfig,
- *   } = useConfigFromQuery({
- *     onConfigChange: (config) => {
- *       // Apply config to your theme context
- *       if (config.preset) setPreset(config.preset);
- *       if (config.mode) setMode(config.mode);
- *       if (config.primary) setPrimaryColor(config.primary);
- *     },
- *   });
- *
- *   // Generate shareable link
- *   const shareUrl = generateUrl({
- *     preset: currentPreset,
- *     mode: currentMode,
- *     primary: currentPrimary,
- *   });
- *
- *   return (
- *     <div>
- *       {hasUrlConfig && <Alert>Using config from URL</Alert>}
- *       <Button onClick={() => navigator.clipboard.writeText(shareUrl)}>
- *         Copy Share Link
- *       </Button>
- *     </div>
- *   );
- * }
- * ```
- */
-declare function useConfigFromQuery(options?: UseConfigFromQueryOptions): UseConfigFromQueryReturn;
-
-/**
- * Image dimensions result.
- */
-interface ImageDimensions {
-    /** Natural width of the image in pixels */
-    width: number;
-    /** Natural height of the image in pixels */
-    height: number;
-    /** Aspect ratio (width / height) */
-    aspectRatio: number;
-}
-/**
- * Return type for useImageDimensions hook.
- */
-interface UseImageDimensionsReturn {
-    /** Image dimensions (null if not loaded or error) */
-    dimensions: ImageDimensions | null;
-    /** Loading state */
-    loading: boolean;
-    /** Error if image failed to load */
-    error: Error | null;
-    /** Manually retry loading the image */
-    retry: () => void;
-}
-/**
- * Options for useImageDimensions hook.
- */
-interface UseImageDimensionsOptions {
-    /** Cross-origin setting for image loading */
-    crossOrigin?: 'anonymous' | 'use-credentials';
-    /** Timeout in milliseconds (default: 10000) */
-    timeout?: number;
-    /** Whether to start loading immediately (default: true) */
-    immediate?: boolean;
-}
-/**
- * useImageDimensions - Detects image dimensions from a URL.
- *
- * Loads an image in memory to get its natural width and height.
- *
- * @example
- * ```tsx
- * function ImagePreview({ src }: { src: string }) {
- *   const { dimensions, loading, error } = useImageDimensions(src);
- *
- *   if (loading) return <CircularProgress />;
- *   if (error) return <Alert severity="error">Failed to load image</Alert>;
- *   if (!dimensions) return null;
- *
- *   return (
- *     <Box>
- *       <Typography>
- *         {dimensions.width} x {dimensions.height}
- *       </Typography>
- *       <Typography>
- *         Aspect ratio: {dimensions.aspectRatio.toFixed(2)}
- *       </Typography>
- *       <img
- *         src={src}
- *         alt="preview"
- *         style={{ maxWidth: '100%', aspectRatio: dimensions.aspectRatio }}
- *       />
- *     </Box>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With manual control
- * function LazyImage({ src }: { src: string }) {
- *   const { dimensions, loading, retry } = useImageDimensions(src, {
- *     immediate: false,
- *   });
- *
- *   return (
- *     <Box>
- *       {!dimensions && !loading && (
- *         <Button onClick={retry}>Load dimensions</Button>
- *       )}
- *       {loading && <CircularProgress />}
- *       {dimensions && (
- *         <Typography>{dimensions.width} x {dimensions.height}</Typography>
- *       )}
- *     </Box>
- *   );
- * }
- * ```
- *
- * @param src - Image URL to load
- * @param options - Hook options
- * @returns Dimensions, loading state, error, and retry function
- */
-declare function useImageDimensions(src: string | null | undefined, options?: UseImageDimensionsOptions): UseImageDimensionsReturn;
-/**
- * Get dimensions of multiple images.
- *
- * @example
- * ```tsx
- * function Gallery({ urls }: { urls: string[] }) {
- *   const results = useMultipleImageDimensions(urls);
- *
- *   return (
- *     <Grid container>
- *       {results.map((result, i) => (
- *         <Grid item key={urls[i]}>
- *           {result.loading && <Skeleton />}
- *           {result.dimensions && (
- *             <img
- *               src={urls[i]}
- *               style={{ aspectRatio: result.dimensions.aspectRatio }}
- *             />
- *           )}
- *         </Grid>
- *       ))}
- *     </Grid>
- *   );
- * }
- * ```
- */
-declare function useMultipleImageDimensions(urls: (string | null | undefined)[], options?: UseImageDimensionsOptions): UseImageDimensionsReturn[];
-
-/**
- * Return type for usePasswordVisibility hook.
- */
-interface UsePasswordVisibilityReturn {
-    /** Whether password is visible (text) or hidden (password) */
-    visible: boolean;
-    /** Toggle visibility */
-    toggle: () => void;
-    /** Show password */
-    show: () => void;
-    /** Hide password */
-    hide: () => void;
-    /** Input type based on visibility ('text' | 'password') */
-    type: 'text' | 'password';
-}
-/**
- * Options for usePasswordVisibility hook.
- */
-interface UsePasswordVisibilityOptions {
-    /** Initial visibility state (default: false) */
-    initialVisible?: boolean;
-}
-/**
- * usePasswordVisibility - Manage password field visibility toggle.
- *
- * Returns state and handlers for password visibility toggle,
- * commonly used with InputAdornment in MUI TextField.
- *
- * @example
- * ```tsx
- * function LoginForm() {
- *   const password = usePasswordVisibility();
- *
- *   return (
- *     <TextField
- *       type={password.type}
- *       InputProps={{
- *         endAdornment: (
- *           <InputAdornment position="end">
- *             <IconButton onClick={password.toggle}>
- *               {password.visible ? <VisibilityOff /> : <Visibility />}
- *             </IconButton>
- *           </InputAdornment>
- *         ),
- *       }}
- *     />
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With confirm password field
- * function RegisterForm() {
- *   const password = usePasswordVisibility();
- *   const confirmPassword = usePasswordVisibility();
- *
- *   return (
- *     <Box>
- *       <TextField
- *         label="Password"
- *         type={password.type}
- *         InputProps={{ endAdornment: <PasswordToggle {...password} /> }}
- *       />
- *       <TextField
- *         label="Confirm Password"
- *         type={confirmPassword.type}
- *         InputProps={{ endAdornment: <PasswordToggle {...confirmPassword} /> }}
- *       />
- *     </Box>
- *   );
- * }
- * ```
- *
- * @param options - Hook options
- * @returns Visibility state, toggle handlers, and input type
- */
-declare function usePasswordVisibility(options?: UsePasswordVisibilityOptions): UsePasswordVisibilityReturn;
-
-interface UseThrottleOptions {
-    /** Whether to invoke on the leading edge (default: true) */
-    leading?: boolean;
-    /** Whether to invoke on the trailing edge (default: true) */
-    trailing?: boolean;
-}
-/**
- * useThrottle - Throttle a value.
- *
- * Returns a throttled version of the value that only updates
- * at most once per specified interval.
- *
- * @example
- * ```tsx
- * function SearchComponent() {
- *   const [search, setSearch] = useState('');
- *   const throttledSearch = useThrottle(search, 300);
- *
- *   // API call only triggers when throttledSearch changes
- *   useEffect(() => {
- *     if (throttledSearch) {
- *       searchApi(throttledSearch);
- *     }
- *   }, [throttledSearch]);
- *
- *   return <input value={search} onChange={(e) => setSearch(e.target.value)} />;
- * }
- * ```
- *
- * @param value - Value to throttle
- * @param delay - Throttle delay in milliseconds
- * @param options - Throttle options
- * @returns Throttled value
- */
-declare function useThrottle<T>(value: T, delay: number, options?: UseThrottleOptions): T;
-/**
- * useThrottleCallback - Create a throttled callback function.
- *
- * Returns a memoized throttled version of the callback that only
- * invokes at most once per specified interval.
- *
- * @example
- * ```tsx
- * function ScrollTracker() {
- *   const handleScroll = useThrottleCallback(
- *     (e: Event) => {
- *       console.log('Scroll position:', window.scrollY);
- *     },
- *     100
- *   );
- *
- *   useEffect(() => {
- *     window.addEventListener('scroll', handleScroll);
- *     return () => window.removeEventListener('scroll', handleScroll);
- *   }, [handleScroll]);
- *
- *   return <div>Scroll me!</div>;
- * }
- * ```
- *
- * @param callback - Callback to throttle
- * @param delay - Throttle delay in milliseconds
- * @param options - Throttle options
- * @returns Throttled callback
- */
-declare function useThrottleCallback<T extends (...args: unknown[]) => unknown>(callback: T, delay: number, options?: UseThrottleOptions): T;
-
-interface UseOnlineStatusReturn {
-    /** Whether the browser is online */
-    isOnline: boolean;
-    /** Whether the browser is offline */
-    isOffline: boolean;
-    /** Time when status last changed (timestamp) */
-    lastChanged: number | null;
-}
-/**
- * useOnlineStatus - Track browser online/offline status.
- *
- * Uses navigator.onLine and online/offline events to track network status.
- * SSR-safe with server-side assumption of online status.
- *
- * @example
- * ```tsx
- * function ConnectionIndicator() {
- *   const { isOnline, isOffline } = useOnlineStatus();
- *
- *   if (isOffline) {
- *     return (
- *       <Alert severity="warning">
- *         You are offline. Changes will sync when you reconnect.
- *       </Alert>
- *     );
- *   }
- *
- *   return null;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With timestamp tracking
- * function NetworkStatus() {
- *   const { isOnline, lastChanged } = useOnlineStatus();
- *
- *   return (
- *     <Box>
- *       <Typography>
- *         Status: {isOnline ? 'Online' : 'Offline'}
- *       </Typography>
- *       {lastChanged && (
- *         <Typography variant="caption">
- *           Last changed: {new Date(lastChanged).toLocaleTimeString()}
- *         </Typography>
- *       )}
- *     </Box>
- *   );
- * }
- * ```
- *
- * @returns Online status and metadata
- */
-declare function useOnlineStatus(): UseOnlineStatusReturn;
-
-interface UseIntersectionObserverOptions {
-    /** Root element for intersection (default: viewport) */
-    root?: Element | Document | null;
-    /** Root margin (default: '0px') */
-    rootMargin?: string;
-    /** Threshold(s) at which to trigger (default: 0) */
-    threshold?: number | number[];
-    /** Whether to disconnect after first intersection (default: false) */
-    triggerOnce?: boolean;
-    /** Whether to start observing immediately (default: true) */
-    enabled?: boolean;
-}
-interface UseIntersectionObserverReturn {
-    /** Ref to attach to the target element */
-    ref: (element: Element | null) => void;
-    /** Current intersection entry */
-    entry: IntersectionObserverEntry | null;
-    /** Whether the element is intersecting */
-    isIntersecting: boolean;
-    /** Manually disconnect the observer */
-    disconnect: () => void;
-}
-/**
- * useIntersectionObserver - Observe element visibility.
- *
- * Uses the Intersection Observer API to track when an element
- * enters or exits the viewport (or a custom root element).
- *
- * @example
- * ```tsx
- * // Lazy loading images
- * function LazyImage({ src }: { src: string }) {
- *   const { ref, isIntersecting } = useIntersectionObserver({
- *     triggerOnce: true,
- *   });
- *
- *   return (
- *     <div ref={ref}>
- *       {isIntersecting ? (
- *         <img src={src} alt="" />
- *       ) : (
- *         <Skeleton variant="rectangular" height={200} />
- *       )}
- *     </div>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Infinite scroll
- * function InfiniteList({ items, onLoadMore }) {
- *   const { ref, isIntersecting } = useIntersectionObserver({
- *     threshold: 0.5,
- *   });
- *
- *   useEffect(() => {
- *     if (isIntersecting) {
- *       onLoadMore();
- *     }
- *   }, [isIntersecting, onLoadMore]);
- *
- *   return (
- *     <Box>
- *       {items.map((item) => <Item key={item.id} {...item} />)}
- *       <div ref={ref} style={{ height: 1 }} />
- *     </Box>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Animate on scroll
- * function AnimatedSection({ children }) {
- *   const { ref, isIntersecting } = useIntersectionObserver({
- *     threshold: 0.1,
- *     triggerOnce: true,
- *   });
- *
- *   return (
- *     <Fade in={isIntersecting}>
- *       <Box ref={ref}>{children}</Box>
- *     </Fade>
- *   );
- * }
- * ```
- *
- * @param options - Observer options
- * @returns Ref, entry, intersection state, and disconnect function
- */
-declare function useIntersectionObserver(options?: UseIntersectionObserverOptions): UseIntersectionObserverReturn;
-
-interface KeyboardShortcut {
-    /** Main key (e.g., 'k', 'Enter', 'Escape') */
-    key: string;
-    /** Require Ctrl/Cmd key */
-    ctrl?: boolean;
-    /** Require Shift key */
-    shift?: boolean;
-    /** Require Alt key */
-    alt?: boolean;
-    /** Require Meta key (Cmd on Mac) */
-    meta?: boolean;
-}
-interface UseKeyboardShortcutOptions {
-    /** Whether the shortcut is enabled (default: true) */
-    enabled?: boolean;
-    /** Prevent default browser behavior (default: true) */
-    preventDefault?: boolean;
-    /** Stop event propagation (default: false) */
-    stopPropagation?: boolean;
-    /** Target element (default: document) */
-    target?: EventTarget | null;
-    /** Event type (default: 'keydown') */
-    event?: 'keydown' | 'keyup' | 'keypress';
-    /** Ignore when focus is in input/textarea/contenteditable (default: false) */
-    ignoreInputs?: boolean;
-}
-/**
- * useKeyboardShortcut - Handle keyboard shortcuts.
- *
- * Listens for keyboard events matching the specified shortcut
- * and invokes the callback when matched.
- *
- * @example
- * ```tsx
- * // Simple shortcut
- * function SearchDialog() {
- *   const [open, setOpen] = useState(false);
- *
- *   useKeyboardShortcut({ key: 'k', ctrl: true }, () => {
- *     setOpen(true);
- *   });
- *
- *   return <Dialog open={open} onClose={() => setOpen(false)} />;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Save with Ctrl+S
- * function Editor({ onSave }) {
- *   useKeyboardShortcut(
- *     { key: 's', ctrl: true },
- *     () => onSave(),
- *     { preventDefault: true }
- *   );
- *
- *   return <TextField multiline />;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Escape to close
- * function Modal({ onClose }) {
- *   useKeyboardShortcut({ key: 'Escape' }, onClose);
- *
- *   return <div>Modal content</div>;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Multiple shortcuts
- * function App() {
- *   useKeyboardShortcut({ key: 'k', ctrl: true }, openSearch);
- *   useKeyboardShortcut({ key: 'n', ctrl: true }, createNew);
- *   useKeyboardShortcut({ key: '/', ctrl: true }, toggleHelp);
- *
- *   return <div>...</div>;
- * }
- * ```
- *
- * @param shortcut - Keyboard shortcut definition
- * @param callback - Function to call when shortcut is triggered
- * @param options - Hook options
- */
-declare function useKeyboardShortcut(shortcut: KeyboardShortcut, callback: (event: KeyboardEvent) => void, options?: UseKeyboardShortcutOptions): void;
-/**
- * useEscapeKey - Convenience hook for Escape key handling.
- *
- * @example
- * ```tsx
- * function Modal({ onClose }) {
- *   useEscapeKey(onClose);
- *   return <div>Modal content</div>;
- * }
- * ```
- */
-declare function useEscapeKey(callback: (event: KeyboardEvent) => void, options?: Omit<UseKeyboardShortcutOptions, 'ignoreInputs'>): void;
-/**
- * useEnterKey - Convenience hook for Enter key handling.
- *
- * @example
- * ```tsx
- * function SearchField({ onSearch }) {
- *   useEnterKey(onSearch, { ignoreInputs: false });
- *   return <TextField />;
- * }
- * ```
- */
-declare function useEnterKey(callback: (event: KeyboardEvent) => void, options?: UseKeyboardShortcutOptions): void;
-
-/**
- * Options for useFocusTrap hook.
- */
-interface UseFocusTrapOptions {
-    /**
-     * Whether the focus trap is active.
-     * @default true
-     */
-    enabled?: boolean;
-    /**
-     * Whether to auto-focus the first focusable element when enabled.
-     * @default true
-     */
-    autoFocus?: boolean;
-    /**
-     * Whether to restore focus to the previously focused element when disabled.
-     * @default true
-     */
-    restoreFocus?: boolean;
-    /**
-     * Selector for focusable elements.
-     * @default FOCUSABLE_SELECTOR
-     */
-    focusableSelector?: string;
-}
-/**
- * Return type for useFocusTrap hook.
- */
-interface UseFocusTrapReturn<T extends HTMLElement = HTMLElement> {
-    /**
-     * Ref to attach to the container element.
-     */
-    ref: React.RefCallback<T>;
-    /**
-     * Focus the first focusable element.
-     */
-    focusFirst: () => void;
-    /**
-     * Focus the last focusable element.
-     */
-    focusLast: () => void;
-}
-/**
- * Trap focus within a container element.
- *
- * @param options - Hook options
- * @returns Ref and focus control functions
- *
- * @example
- * ```tsx
- * function Modal({ open, onClose, children }) {
- *   const { ref } = useFocusTrap({ enabled: open });
- *
- *   if (!open) return null;
- *
- *   return (
- *     <div ref={ref} role="dialog" aria-modal="true">
- *       {children}
- *       <button onClick={onClose}>Close</button>
- *     </div>
- *   );
- * }
- * ```
- */
-declare function useFocusTrap<T extends HTMLElement = HTMLElement>(options?: UseFocusTrapOptions): UseFocusTrapReturn<T>;
-
-/**
- * useUpdateEffect Hook
- *
- * Like useEffect, but skips the first render.
- * Useful for running effects only on updates, not on mount.
- *
- * @module @omnitron-dev/prism/hooks
- */
-
-/**
- * Effect hook that only runs on updates, not on initial mount.
- *
- * @param effect - Effect callback function
- * @param deps - Dependency array
- *
- * @example
- * ```tsx
- * function SearchInput({ value, onSearch }) {
- *   // Only search when value changes after initial render
- *   useUpdateEffect(() => {
- *     onSearch(value);
- *   }, [value]);
- *
- *   return <input value={value} />;
- * }
- * ```
- */
-declare function useUpdateEffect(effect: EffectCallback, deps?: DependencyList): void;
-/**
- * Layout effect hook that only runs on updates, not on initial mount.
- * Uses useLayoutEffect for synchronous DOM measurements.
- *
- * @param effect - Effect callback function
- * @param deps - Dependency array
- *
- * @example
- * ```tsx
- * function AnimatedComponent({ size }) {
- *   const ref = useRef<HTMLDivElement>(null);
- *
- *   // Animate size changes, but not initial render
- *   useUpdateLayoutEffect(() => {
- *     if (ref.current) {
- *       animate(ref.current, { width: size });
- *     }
- *   }, [size]);
- *
- *   return <div ref={ref} />;
- * }
- * ```
- */
-declare function useUpdateLayoutEffect(effect: EffectCallback, deps?: DependencyList): void;
-
-/**
- * useIsomorphicLayoutEffect Hook
- *
- * SSR-safe version of useLayoutEffect.
- * Uses useLayoutEffect on client, useEffect on server.
- *
- * @module @omnitron-dev/prism/hooks
- */
-
-/**
- * Isomorphic layout effect that works in both SSR and CSR environments.
- *
- * - On the client: Uses useLayoutEffect for synchronous DOM operations
- * - On the server: Uses useEffect to avoid SSR warnings
- *
- * @example
- * ```tsx
- * function Tooltip({ position }) {
- *   const ref = useRef<HTMLDivElement>(null);
- *
- *   // Synchronously measure and position on client
- *   useIsomorphicLayoutEffect(() => {
- *     if (ref.current) {
- *       const rect = ref.current.getBoundingClientRect();
- *       // Position tooltip based on measurements
- *     }
- *   }, [position]);
- *
- *   return <div ref={ref}>Tooltip</div>;
- * }
- * ```
- */
-declare const useIsomorphicLayoutEffect: typeof useEffect;
-
-/**
- * Return type for useSessionStorage hook.
- */
-interface UseSessionStorageReturn<T> {
-    /** Current state value */
-    state: T;
-    /** Update state and sessionStorage */
-    setState: (value: T | ((prev: T) => T)) => void;
-    /** Remove item from sessionStorage and reset to default */
-    remove: () => void;
-    /** Check if sessionStorage has the key */
-    hasValue: boolean;
-}
-/**
- * Options for useSessionStorage hook.
- */
-interface UseSessionStorageOptions<T> {
-    /** Serializer function (default: JSON.stringify) */
-    serializer?: (value: T) => string;
-    /** Deserializer function (default: JSON.parse) */
-    deserializer?: (value: string) => T;
-}
-/**
- * Hook for persisting state in sessionStorage.
- *
- * @param key - Storage key
- * @param defaultValue - Default value when key is not found
- * @param options - Configuration options
- * @returns State value and control methods
- *
- * @example
- * ```tsx
- * function SearchFilters() {
- *   const { state: filters, setState: setFilters, remove } = useSessionStorage(
- *     'search-filters',
- *     { query: '', category: 'all' }
- *   );
- *
- *   return (
- *     <>
- *       <input
- *         value={filters.query}
- *         onChange={(e) => setFilters({ ...filters, query: e.target.value })}
- *       />
- *       <button onClick={remove}>Clear Filters</button>
- *     </>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With functional updates
- * function Counter() {
- *   const { state: count, setState: setCount } = useSessionStorage('counter', 0);
- *
- *   return (
- *     <button onClick={() => setCount((prev) => prev + 1)}>
- *       Count: {count}
- *     </button>
- *   );
- * }
- * ```
- */
-declare function useSessionStorage<T>(key: string, defaultValue: T, options?: UseSessionStorageOptions<T>): UseSessionStorageReturn<T>;
-
-/**
- * Return type for useArray hook.
- */
-interface UseArrayReturn<T> {
-    /** Current array value */
-    value: T[];
-    /** Set array to new value */
-    setValue: React.Dispatch<React.SetStateAction<T[]>>;
-    /** Add item to end of array */
-    push: (item: T) => void;
-    /** Add items to end of array */
-    pushMany: (items: T[]) => void;
-    /** Remove first occurrence of item (by reference or predicate) */
-    remove: (itemOrPredicate: T | ((item: T) => boolean)) => void;
-    /** Remove item at index */
-    removeAt: (index: number) => void;
-    /** Remove items matching predicate */
-    removeWhere: (predicate: (item: T) => boolean) => void;
-    /** Update item at index */
-    updateAt: (index: number, item: T) => void;
-    /** Update item at index with partial data (merge) */
-    updateAtPartial: (index: number, partial: Partial<T>) => void;
-    /** Update items matching predicate */
-    updateWhere: (predicate: (item: T) => boolean, update: T | ((item: T) => T)) => void;
-    /** Insert item at index */
-    insertAt: (index: number, item: T) => void;
-    /** Move item from one index to another */
-    move: (fromIndex: number, toIndex: number) => void;
-    /** Swap items at two indices */
-    swap: (indexA: number, indexB: number) => void;
-    /** Clear all items */
-    clear: () => void;
-    /** Reset to initial value */
-    reset: () => void;
-    /** Reverse array in place */
-    reverse: () => void;
-    /** Sort array */
-    sort: (compareFn?: (a: T, b: T) => number) => void;
-    /** Filter array (returns new array, does not modify state) */
-    filter: (predicate: (item: T) => boolean) => T[];
-    /** Find item (returns item, does not modify state) */
-    find: (predicate: (item: T) => boolean) => T | undefined;
-    /** Find item index (returns index, does not modify state) */
-    findIndex: (predicate: (item: T) => boolean) => number;
-    /** Check if array includes item */
-    includes: (item: T) => boolean;
-    /** Get array length */
-    length: number;
-    /** Check if array is empty */
-    isEmpty: boolean;
-    /** Get first item */
-    first: T | undefined;
-    /** Get last item */
-    last: T | undefined;
-}
-/**
- * Hook for managing array state with CRUD operations.
- *
- * @param initialValue - Initial array value
- * @returns Array value and manipulation methods
- *
- * @example
- * ```tsx
- * function TodoList() {
- *   const todos = useArray<{ id: number; text: string; done: boolean }>([]);
- *
- *   const addTodo = (text: string) => {
- *     todos.push({ id: Date.now(), text, done: false });
- *   };
- *
- *   const toggleTodo = (id: number) => {
- *     todos.updateWhere(
- *       (todo) => todo.id === id,
- *       (todo) => ({ ...todo, done: !todo.done })
- *     );
- *   };
- *
- *   return (
- *     <ul>
- *       {todos.value.map((todo) => (
- *         <li key={todo.id} onClick={() => toggleTodo(todo.id)}>
- *           {todo.text} {todo.done && '✓'}
- *         </li>
- *       ))}
- *     </ul>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Drag and drop reordering
- * function SortableList() {
- *   const items = useArray(['A', 'B', 'C', 'D']);
- *
- *   const handleDragEnd = (fromIndex: number, toIndex: number) => {
- *     items.move(fromIndex, toIndex);
- *   };
- *
- *   return <DraggableList items={items.value} onReorder={handleDragEnd} />;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With type-safe updates
- * interface User {
- *   id: number;
- *   name: string;
- *   email: string;
- * }
- *
- * function UserList() {
- *   const users = useArray<User>([
- *     { id: 1, name: 'Alice', email: 'alice@example.com' },
- *   ]);
- *
- *   // Partial update (type-safe)
- *   users.updateAtPartial(0, { email: 'alice@newdomain.com' });
- *
- *   return <div>{users.value.map(u => u.name).join(', ')}</div>;
- * }
- * ```
- */
-declare function useArray<T>(initialValue?: T[]): UseArrayReturn<T>;
-
-/**
- * State for a mutation.
- */
-interface MutationState<TData, TError> {
-    /** Mutation result data */
-    data: TData | undefined;
-    /** Error from mutation */
-    error: TError | undefined;
-    /** Whether mutation is currently executing */
-    isLoading: boolean;
-    /** Whether mutation has succeeded at least once */
-    isSuccess: boolean;
-    /** Whether mutation has failed */
-    isError: boolean;
-    /** Whether mutation is idle (never called or reset) */
-    isIdle: boolean;
-    /** Current status */
-    status: 'idle' | 'loading' | 'success' | 'error';
-}
-/**
- * Options for useMutation hook.
- */
-interface UseMutationOptions<TData, TError, TVariables> {
-    /** Called when mutation starts */
-    onMutate?: (variables: TVariables) => void | Promise<void>;
-    /** Called on successful mutation */
-    onSuccess?: (data: TData, variables: TVariables) => void | Promise<void>;
-    /** Called on mutation error */
-    onError?: (error: TError, variables: TVariables) => void | Promise<void>;
-    /** Called after mutation settles (success or error) */
-    onSettled?: (data: TData | undefined, error: TError | undefined, variables: TVariables) => void | Promise<void>;
-    /** Retry count on failure */
-    retry?: number | boolean;
-    /** Delay between retries in ms */
-    retryDelay?: number | ((attempt: number) => number);
-}
-/**
- * Return type for useMutation hook.
- */
-interface UseMutationReturn<TData, TError, TVariables> {
-    /** Current mutation state */
-    data: TData | undefined;
-    error: TError | undefined;
-    isLoading: boolean;
-    isSuccess: boolean;
-    isError: boolean;
-    isIdle: boolean;
-    status: MutationState<TData, TError>['status'];
-    /** Execute the mutation */
-    mutate: (variables: TVariables, options?: {
-        onSuccess?: (data: TData) => void;
-        onError?: (error: TError) => void;
-        onSettled?: (data: TData | undefined, error: TError | undefined) => void;
-    }) => void;
-    /** Execute the mutation and return a promise */
-    mutateAsync: (variables: TVariables) => Promise<TData>;
-    /** Reset mutation state */
-    reset: () => void;
-}
-/**
- * Hook for handling async mutations with loading/error states.
- *
- * @param mutationFn - Async function to execute
- * @param options - Configuration options
- * @returns Mutation state and control methods
- *
- * @example
- * ```tsx
- * function CreateUserForm() {
- *   const createUser = useMutation(
- *     async (data: { name: string; email: string }) => {
- *       const response = await fetch('/api/users', {
- *         method: 'POST',
- *         body: JSON.stringify(data),
- *       });
- *       if (!response.ok) throw new Error('Failed to create user');
- *       return response.json();
- *     },
- *     {
- *       onSuccess: (user) => {
- *         console.log('User created:', user);
- *       },
- *       onError: (error) => {
- *         console.error('Failed:', error);
- *       },
- *     }
- *   );
- *
- *   const handleSubmit = (e: FormEvent) => {
- *     e.preventDefault();
- *     createUser.mutate({ name: 'John', email: 'john@example.com' });
- *   };
- *
- *   return (
- *     <form onSubmit={handleSubmit}>
- *       <button type="submit" disabled={createUser.isLoading}>
- *         {createUser.isLoading ? 'Creating...' : 'Create User'}
- *       </button>
- *       {createUser.isError && <div>Error: {String(createUser.error)}</div>}
- *       {createUser.isSuccess && <div>User created!</div>}
- *     </form>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With async/await
- * async function handleCreate() {
- *   try {
- *     const user = await createUser.mutateAsync({ name: 'Jane' });
- *     navigate(`/users/${user.id}`);
- *   } catch (error) {
- *     // Error already captured in state
- *   }
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With retry
- * const uploadFile = useMutation(
- *   async (file: File) => {
- *     const formData = new FormData();
- *     formData.append('file', file);
- *     const response = await fetch('/api/upload', {
- *       method: 'POST',
- *       body: formData,
- *     });
- *     if (!response.ok) throw new Error('Upload failed');
- *     return response.json();
- *   },
- *   {
- *     retry: 3,
- *     retryDelay: (attempt) => attempt * 1000,
- *   }
- * );
- * ```
- */
-declare function useMutation<TData = unknown, TError = Error, TVariables = void>(mutationFn: (variables: TVariables) => Promise<TData>, options?: UseMutationOptions<TData, TError, TVariables>): UseMutationReturn<TData, TError, TVariables>;
-
-/**
- * State for a lazy query.
- */
-interface LazyQueryState<TData, TError> {
-    /** Query result data */
-    data: TData | undefined;
-    /** Error from query */
-    error: TError | undefined;
-    /** Whether query is currently executing */
-    isLoading: boolean;
-    /** Whether query has succeeded at least once */
-    isSuccess: boolean;
-    /** Whether query has failed */
-    isError: boolean;
-    /** Whether query has been called at least once */
-    isCalled: boolean;
-    /** Whether query is fetching (includes refetch) */
-    isFetching: boolean;
-    /** Whether this is a refetch */
-    isRefetching: boolean;
-}
-/**
- * Options for useLazyQuery hook.
- */
-interface UseLazyQueryOptions<TData, TError, TVariables> {
-    /** Called on successful query */
-    onSuccess?: (data: TData, variables: TVariables) => void | Promise<void>;
-    /** Called on query error */
-    onError?: (error: TError, variables: TVariables) => void | Promise<void>;
-    /** Called after query settles (success or error) */
-    onSettled?: (data: TData | undefined, error: TError | undefined, variables: TVariables) => void | Promise<void>;
-    /** Cache time in ms (0 = no cache) */
-    cacheTime?: number;
-    /** Stale time in ms (data considered fresh for this duration) */
-    staleTime?: number;
-    /** Retry count on failure */
-    retry?: number | boolean;
-    /** Delay between retries in ms */
-    retryDelay?: number | ((attempt: number) => number);
-    /** Initial data */
-    initialData?: TData;
-}
-/**
- * Return type for useLazyQuery hook.
- */
-interface UseLazyQueryReturn<TData, TError, TVariables> {
-    /** Current query state */
-    data: TData | undefined;
-    error: TError | undefined;
-    isLoading: boolean;
-    isSuccess: boolean;
-    isError: boolean;
-    isCalled: boolean;
-    isFetching: boolean;
-    isRefetching: boolean;
-    /** Execute the query */
-    query: (variables: TVariables) => Promise<TData>;
-    /** Refetch with last variables */
-    refetch: () => Promise<TData | undefined>;
-    /** Reset query state */
-    reset: () => void;
-    /** Manually set data */
-    setData: (data: TData | ((prev: TData | undefined) => TData)) => void;
-}
-/**
- * Hook for manual query execution with caching support.
- *
- * @param queryFn - Async function to execute
- * @param options - Configuration options
- * @returns Query state and control methods
- *
- * @example
- * ```tsx
- * function UserSearch() {
- *   const users = useLazyQuery(
- *     async (query: string) => {
- *       const response = await fetch(`/api/users?q=${query}`);
- *       if (!response.ok) throw new Error('Search failed');
- *       return response.json();
- *     },
- *     {
- *       onSuccess: (data) => console.log('Found users:', data.length),
- *       cacheTime: 5 * 60 * 1000, // 5 minutes
- *     }
- *   );
- *
- *   const handleSearch = async (query: string) => {
- *     const results = await users.query(query);
- *     console.log('Results:', results);
- *   };
- *
- *   return (
- *     <div>
- *       <SearchInput onSearch={handleSearch} />
- *       {users.isLoading && <Spinner />}
- *       {users.isError && <div>Error: {String(users.error)}</div>}
- *       {users.data?.map((user) => <UserCard key={user.id} user={user} />)}
- *     </div>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With caching
- * const userDetails = useLazyQuery(
- *   async (id: string) => fetchUser(id),
- *   {
- *     cacheTime: 10 * 60 * 1000, // Keep in cache for 10 min
- *     staleTime: 60 * 1000, // Consider fresh for 1 min
- *   }
- * );
- *
- * // First call fetches, subsequent calls within staleTime return cache
- * await userDetails.query('123');
- * await userDetails.query('123'); // Returns from cache if not stale
- * ```
- *
- * @example
- * ```tsx
- * // Manual data management
- * const { data, setData, reset } = useLazyQuery(fetchData);
- *
- * // Optimistic update
- * setData((prev) => prev ? { ...prev, count: prev.count + 1 } : prev);
- *
- * // Reset to clean state
- * reset();
- * ```
- */
-declare function useLazyQuery<TData = unknown, TError = Error, TVariables = void>(queryFn: (variables: TVariables) => Promise<TData>, options?: UseLazyQueryOptions<TData, TError, TVariables>): UseLazyQueryReturn<TData, TError, TVariables>;
-
-/**
- * Page info returned from fetch function.
- */
-interface PageInfo {
-    /** Whether there are more pages */
-    hasNextPage: boolean;
-    /** Cursor or token for next page */
-    endCursor?: string | number;
-    /** Total count (optional) */
-    totalCount?: number;
-}
-/**
- * Page data structure.
- */
-interface InfinitePage<TData> {
-    /** Items in this page */
-    items: TData[];
-    /** Page information */
-    pageInfo: PageInfo;
-}
-/**
- * State for infinite scroll.
- */
-interface InfiniteScrollState<TData, TError> {
-    /** All loaded items (flattened) */
-    items: TData[];
-    /** All pages */
-    pages: InfinitePage<TData>[];
-    /** Error from last fetch */
-    error: TError | undefined;
-    /** Whether initial load is in progress */
-    isLoading: boolean;
-    /** Whether more data is being fetched */
-    isFetchingMore: boolean;
-    /** Whether there are more pages to fetch */
-    hasNextPage: boolean;
-    /** Whether any data has been loaded */
-    isEmpty: boolean;
-    /** Total count if available */
-    totalCount: number | undefined;
-}
-/**
- * Options for useInfiniteScroll hook.
- */
-interface UseInfiniteScrollOptions<TData, TError> {
-    /** Called on successful fetch */
-    onSuccess?: (page: InfinitePage<TData>) => void | Promise<void>;
-    /** Called on fetch error */
-    onError?: (error: TError) => void | Promise<void>;
-    /** Initial cursor/offset */
-    initialCursor?: string | number;
-    /** Initial page size */
-    pageSize?: number;
-    /** Retry count on failure */
-    retry?: number | boolean;
-    /** Retry delay in ms */
-    retryDelay?: number | ((attempt: number) => number);
-    /** Intersection observer options for auto-loading */
-    observerOptions?: IntersectionObserverInit;
-}
-/**
- * Return type for useInfiniteScroll hook.
- */
-interface UseInfiniteScrollReturn<TData, TError> {
-    /** All loaded items (flattened) */
-    items: TData[];
-    /** All pages */
-    pages: InfinitePage<TData>[];
-    /** Error from last fetch */
-    error: TError | undefined;
-    /** Whether initial load is in progress */
-    isLoading: boolean;
-    /** Whether more data is being fetched */
-    isFetchingMore: boolean;
-    /** Whether there are more pages to fetch */
-    hasNextPage: boolean;
-    /** Whether list is empty */
-    isEmpty: boolean;
-    /** Total count if available */
-    totalCount: number | undefined;
-    /** Fetch the next page */
-    fetchNextPage: () => Promise<void>;
-    /** Fetch first page (refresh) */
-    refresh: () => Promise<void>;
-    /** Reset to initial state */
-    reset: () => void;
-    /** Ref to attach to sentinel element for auto-loading */
-    sentinelRef: React.RefCallback<HTMLElement>;
-    /** Manually prepend items */
-    prependItems: (items: TData[]) => void;
-    /** Manually append items */
-    appendItems: (items: TData[]) => void;
-    /** Remove item by predicate */
-    removeItem: (predicate: (item: TData) => boolean) => void;
-    /** Update item by predicate */
-    updateItem: (predicate: (item: TData) => boolean, update: Partial<TData> | ((item: TData) => TData)) => void;
-}
-/**
- * Fetch function signature.
- */
-type InfiniteFetchFn<TData> = (params: {
-    cursor?: string | number;
-    pageSize: number;
-}) => Promise<InfinitePage<TData>>;
-/**
- * Hook for infinite scrolling with paginated data.
- *
- * @param fetchFn - Function to fetch a page of data
- * @param options - Configuration options
- * @returns Infinite scroll state and controls
- *
- * @example
- * ```tsx
- * function UserList() {
- *   const {
- *     items,
- *     isLoading,
- *     isFetchingMore,
- *     hasNextPage,
- *     fetchNextPage,
- *     sentinelRef,
- *   } = useInfiniteScroll<User>(
- *     async ({ cursor, pageSize }) => {
- *       const response = await fetch(
- *         `/api/users?cursor=${cursor ?? ''}&limit=${pageSize}`
- *       );
- *       const data = await response.json();
- *       return {
- *         items: data.users,
- *         pageInfo: {
- *           hasNextPage: data.hasMore,
- *           endCursor: data.nextCursor,
- *           totalCount: data.total,
- *         },
- *       };
- *     },
- *     { pageSize: 20 }
- *   );
- *
- *   if (isLoading) return <Spinner />;
- *
- *   return (
- *     <div>
- *       {items.map((user) => (
- *         <UserCard key={user.id} user={user} />
- *       ))}
- *       {hasNextPage && (
- *         <div ref={sentinelRef}>
- *           {isFetchingMore ? <Spinner /> : 'Load more'}
- *         </div>
- *       )}
- *     </div>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Manual loading
- * function ProductList() {
- *   const { items, hasNextPage, fetchNextPage, isFetchingMore } = useInfiniteScroll(
- *     fetchProducts,
- *     { pageSize: 10 }
- *   );
- *
- *   return (
- *     <>
- *       <ProductGrid items={items} />
- *       {hasNextPage && (
- *         <Button onClick={fetchNextPage} loading={isFetchingMore}>
- *           Load More
- *         </Button>
- *       )}
- *     </>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With optimistic updates
- * const { items, removeItem, updateItem, prependItems } = useInfiniteScroll(
- *   fetchComments,
- *   { pageSize: 20 }
- * );
- *
- * // Add new comment at top
- * const handleNewComment = (comment: Comment) => {
- *   prependItems([comment]);
- * };
- *
- * // Delete comment
- * const handleDelete = (id: string) => {
- *   removeItem((c) => c.id === id);
- * };
- *
- * // Update comment
- * const handleEdit = (id: string, text: string) => {
- *   updateItem((c) => c.id === id, { text });
- * };
- * ```
- */
-declare function useInfiniteScroll<TData = unknown, TError = Error>(fetchFn: InfiniteFetchFn<TData>, options?: UseInfiniteScrollOptions<TData, TError>): UseInfiniteScrollReturn<TData, TError>;
-
-export { type UseWindowSizeOptions as $, type AsyncState as A, type BreakpointChecks as B, type CookieOptions as C, type DOMRectValue as D, type UseIntersectionObserverReturn as E, type UseKeyboardShortcutOptions as F, type UseLazyQueryOptions as G, type UseLazyQueryReturn as H, type ImageDimensions as I, type UseMutationOptions as J, type KeyboardShortcut as K, type LazyQueryState as L, type MutationState as M, type UseMutationReturn as N, type UseOnlineStatusReturn as O, type PageInfo as P, type UsePasswordVisibilityOptions as Q, type UsePasswordVisibilityReturn as R, type ScrollElValue as S, type UsePopoverHoverReturn as T, type UrlConfigValues as U, type UseResponsiveQueryReturn as V, type UseScrollOffsetTopReturn as W, type UseScrollPositionOptions as X, type UseSessionStorageOptions as Y, type UseSessionStorageReturn as Z, type UseThrottleOptions as _, type Breakpoints as a, type WindowSize as a0, cookiesAvailable as a1, getCookie as a2, removeCookie as a3, setCookie as a4, useArray as a5, useAsync as a6, useAsyncFn as a7, useBackToTop as a8, useBreakpoint as a9, useSessionStorage as aA, useThrottle as aB, useThrottleCallback as aC, useUpdateEffect as aD, useUpdateLayoutEffect as aE, useWindowSize as aF, useBreakpointChecks as aa, useClientRect as ab, useConfigFromQuery as ac, useCookies as ad, useCountdownDate as ae, useCountdownSeconds as af, useDoubleClick as ag, useEnterKey as ah, useEscapeKey as ai, useFocusTrap as aj, useImageDimensions as ak, useInfiniteScroll as al, useIntersectionObserver as am, useIsomorphicLayoutEffect as an, useKeyboardShortcut as ao, useLazyQuery as ap, useMultipleImageDimensions as aq, useMutation as ar, useOnlineStatus as as, usePasswordVisibility as at, usePopoverHover as au, useResponsiveQuery as av, useScrollLock as aw, useScrollOffsetTop as ax, useScrollPosition as ay, useScrollToTop as az, type InfiniteFetchFn as b, type InfinitePage as c, type InfiniteScrollState as d, type ScrollPosition as e, type UseArrayReturn as f, type UseAsyncFnReturn as g, type UseAsyncOptions as h, type UseAsyncReturn as i, type UseBackToTopReturn as j, type UseClientRectReturn as k, type UseConfigFromQueryOptions as l, type UseConfigFromQueryReturn as m, type UseCookiesOptions as n, type UseCookiesReturn as o, type UseCountdownDateReturn as p, type UseCountdownSecondsReturn as q, type UseDoubleClickProps as r, type UseDoubleClickReturn as s, type UseFocusTrapOptions as t, type UseFocusTrapReturn as u, type UseImageDimensionsOptions as v, type UseImageDimensionsReturn as w, type UseInfiniteScrollOptions as x, type UseInfiniteScrollReturn as y, type UseIntersectionObserverOptions as z };