@exyconn/common 2.1.0 → 2.3.3

package/dist/client/hooks/index.d.ts

@@ -0,0 +1,1042 @@
+import { RefObject } from 'react';
+
+interface UseToggleReturn {
+    /** Current boolean value */
+    value: boolean;
+    /** Toggle the value */
+    toggle: () => void;
+    /** Set to true */
+    setTrue: () => void;
+    /** Set to false */
+    setFalse: () => void;
+    /** Set to specific value */
+    setValue: (value: boolean) => void;
+}
+/**
+ * Hook to manage boolean state with toggle functionality
+ * @param initialValue - Initial boolean value (default: false)
+ */
+declare function useToggle(initialValue?: boolean): UseToggleReturn;
+
+interface UseCounterOptions {
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Step value for increment/decrement */
+    step?: number;
+}
+interface UseCounterReturn {
+    /** Current count value */
+    count: number;
+    /** Increment by step */
+    increment: () => void;
+    /** Decrement by step */
+    decrement: () => void;
+    /** Set to specific value */
+    set: (value: number) => void;
+    /** Reset to initial value */
+    reset: () => void;
+}
+/**
+ * Hook to manage numeric counter with min/max bounds
+ * @param initialValue - Initial counter value (default: 0)
+ * @param options - Configuration options
+ */
+declare function useCounter(initialValue?: number, options?: UseCounterOptions): UseCounterReturn;
+
+/**
+ * Hook that returns a default value when state is null or undefined
+ * @param initialValue - Initial value (can be null/undefined)
+ * @param defaultValue - Default value to use when state is null/undefined
+ */
+declare function useDefault<T>(initialValue: T | null | undefined, defaultValue: T): [T, (value: T | null | undefined) => void];
+
+/**
+ * Hook to get the previous value of a state or prop
+ * @param value - Current value to track
+ * @param initialValue - Optional initial previous value
+ */
+declare function usePrevious<T>(value: T, initialValue?: T): T | undefined;
+
+type ObjectStateUpdate<T> = Partial<T> | ((prevState: T) => Partial<T>);
+interface UseObjectStateReturn<T extends object> {
+    /** Current state object */
+    state: T;
+    /** Update state with partial object (merges with existing) */
+    setState: (update: ObjectStateUpdate<T>) => void;
+    /** Reset to initial state */
+    resetState: () => void;
+    /** Set a single property */
+    setProperty: <K extends keyof T>(key: K, value: T[K]) => void;
+    /** Remove a property (sets to undefined) */
+    removeProperty: <K extends keyof T>(key: K) => void;
+}
+/**
+ * Hook to manage object state with partial updates
+ * @param initialState - Initial state object
+ */
+declare function useObjectState<T extends object>(initialState: T): UseObjectStateReturn<T>;
+
+interface UseHistoryStateReturn<T> {
+    /** Current state value */
+    state: T;
+    /** Set new state (adds to history) */
+    setState: (value: T | ((prev: T) => T)) => void;
+    /** Undo to previous state */
+    undo: () => void;
+    /** Redo to next state */
+    redo: () => void;
+    /** Clear all history and reset to current or initial */
+    clear: (value?: T) => void;
+    /** Can undo? */
+    canUndo: boolean;
+    /** Can redo? */
+    canRedo: boolean;
+    /** Full history array */
+    history: T[];
+    /** Current position in history */
+    pointer: number;
+    /** Go to specific position in history */
+    go: (index: number) => void;
+}
+interface UseHistoryStateOptions {
+    /** Maximum history length (default: 100) */
+    maxLength?: number;
+}
+/**
+ * Hook to manage state with undo/redo functionality
+ * @param initialValue - Initial state value
+ * @param options - Configuration options
+ */
+declare function useHistoryState<T>(initialValue: T, options?: UseHistoryStateOptions): UseHistoryStateReturn<T>;
+
+interface UseQueueReturn<T> {
+    /** Current queue items */
+    queue: T[];
+    /** Add item to end of queue */
+    enqueue: (item: T) => void;
+    /** Add multiple items to end of queue */
+    enqueueAll: (items: T[]) => void;
+    /** Remove and return first item */
+    dequeue: () => T | undefined;
+    /** Peek at first item without removing */
+    peek: () => T | undefined;
+    /** Clear the queue */
+    clear: () => void;
+    /** Queue size */
+    size: number;
+    /** Is queue empty? */
+    isEmpty: boolean;
+    /** First item in queue */
+    first: T | undefined;
+    /** Last item in queue */
+    last: T | undefined;
+}
+/**
+ * Hook to manage a FIFO queue
+ * @param initialValue - Initial queue items (default: [])
+ */
+declare function useQueue<T>(initialValue?: T[]): UseQueueReturn<T>;
+
+interface UseListReturn<T> {
+    /** Current list items */
+    list: T[];
+    /** Set entire list */
+    set: (newList: T[]) => void;
+    /** Add item to end */
+    push: (item: T) => void;
+    /** Add item to beginning */
+    unshift: (item: T) => void;
+    /** Remove item at index */
+    removeAt: (index: number) => void;
+    /** Remove first matching item */
+    remove: (item: T) => 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 function */
+    updateWhere: (predicate: (item: T) => boolean, updater: (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;
+    /** Clear the list */
+    clear: () => void;
+    /** Reset to initial value */
+    reset: () => void;
+    /** Filter items */
+    filter: (predicate: (item: T) => boolean) => void;
+    /** Sort items */
+    sort: (compareFn?: (a: T, b: T) => number) => void;
+    /** Reverse items */
+    reverse: () => void;
+    /** List size */
+    size: number;
+    /** Is list empty? */
+    isEmpty: boolean;
+    /** First item */
+    first: T | undefined;
+    /** Last item */
+    last: T | undefined;
+}
+/**
+ * Hook to manage array/list with utility methods
+ * @param initialValue - Initial list items (default: [])
+ */
+declare function useList<T>(initialValue?: T[]): UseListReturn<T>;
+
+interface UseMapReturn<K, V> {
+    /** Current map */
+    map: Map<K, V>;
+    /** Get value by key */
+    get: (key: K) => V | undefined;
+    /** Set key-value pair */
+    set: (key: K, value: V) => void;
+    /** Set multiple entries */
+    setAll: (entries: Iterable<[K, V]>) => void;
+    /** Check if key exists */
+    has: (key: K) => boolean;
+    /** Delete by key */
+    remove: (key: K) => void;
+    /** Delete multiple keys */
+    removeAll: (keys: K[]) => void;
+    /** Clear the map */
+    clear: () => void;
+    /** Reset to initial value */
+    reset: () => void;
+    /** Map size */
+    size: number;
+    /** All keys */
+    keys: K[];
+    /** All values */
+    values: V[];
+    /** All entries */
+    entries: [K, V][];
+    /** Is map empty? */
+    isEmpty: boolean;
+}
+/**
+ * Hook to manage Map state with utility methods
+ * @param initialValue - Initial entries (default: [])
+ */
+declare function useMap<K, V>(initialValue?: Iterable<[K, V]>): UseMapReturn<K, V>;
+
+interface UseSetReturn<T> {
+    /** Current set */
+    set: Set<T>;
+    /** Add item to set */
+    add: (item: T) => void;
+    /** Add multiple items */
+    addAll: (items: Iterable<T>) => void;
+    /** Check if item exists */
+    has: (item: T) => boolean;
+    /** Remove item from set */
+    remove: (item: T) => void;
+    /** Remove multiple items */
+    removeAll: (items: Iterable<T>) => void;
+    /** Toggle item (add if not exists, remove if exists) */
+    toggle: (item: T) => void;
+    /** Clear the set */
+    clear: () => void;
+    /** Reset to initial value */
+    reset: () => void;
+    /** Set size */
+    size: number;
+    /** All values as array */
+    values: T[];
+    /** Is set empty? */
+    isEmpty: boolean;
+}
+/**
+ * Hook to manage Set state with utility methods
+ * @param initialValue - Initial items (default: [])
+ */
+declare function useSet<T>(initialValue?: Iterable<T>): UseSetReturn<T>;
+
+/**
+ * Debounce a value with configurable delay
+ * @param value - Value to debounce
+ * @param delay - Delay in milliseconds (default: 500)
+ */
+declare function useDebounce<T>(value: T, delay?: number): T;
+
+/**
+ * Throttle a value with configurable interval
+ * @param value - Value to throttle
+ * @param interval - Minimum interval between updates in milliseconds (default: 500)
+ */
+declare function useThrottle<T>(value: T, interval?: number): T;
+
+interface UseTimeoutReturn {
+    /** Reset the timeout */
+    reset: () => void;
+    /** Clear/cancel the timeout */
+    clear: () => void;
+}
+/**
+ * Hook to manage setTimeout declaratively
+ * @param callback - Function to call after timeout
+ * @param delay - Delay in milliseconds (null to disable)
+ */
+declare function useTimeout(callback: () => void, delay: number | null): UseTimeoutReturn;
+
+/**
+ * Run a callback on an interval
+ * @param callback - Function to call on each interval
+ * @param delay - Interval delay in ms (null to pause)
+ */
+declare function useInterval(callback: () => void, delay: number | null): void;
+
+/**
+ * Hook to run interval conditionally
+ * @param callback - Function to call on each interval
+ * @param delay - Interval delay in milliseconds
+ * @param when - Condition to run the interval
+ * @param immediate - Run callback immediately when condition becomes true
+ */
+declare function useIntervalWhen(callback: () => void, delay: number, when: boolean, immediate?: boolean): void;
+
+/**
+ * Hook to run callback at random intervals
+ * @param callback - Function to call on each interval
+ * @param minDelay - Minimum delay in milliseconds
+ * @param maxDelay - Maximum delay in milliseconds
+ * @param enabled - Whether the interval is enabled (default: true)
+ */
+declare function useRandomInterval(callback: () => void, minDelay: number, maxDelay: number, enabled?: boolean): void;
+
+interface UseCountdownOptions {
+    /** Interval in milliseconds (default: 1000) */
+    interval?: number;
+    /** Callback when countdown reaches zero */
+    onComplete?: () => void;
+    /** Auto-start the countdown (default: false) */
+    autoStart?: boolean;
+}
+interface UseCountdownReturn {
+    /** Current countdown value in milliseconds */
+    count: number;
+    /** Start the countdown */
+    start: () => void;
+    /** Pause the countdown */
+    pause: () => void;
+    /** Resume the countdown */
+    resume: () => void;
+    /** Reset to initial value */
+    reset: (newCount?: number) => void;
+    /** Is countdown running? */
+    isRunning: boolean;
+    /** Is countdown complete? */
+    isComplete: boolean;
+    /** Formatted time { days, hours, minutes, seconds } */
+    formatted: {
+        days: number;
+        hours: number;
+        minutes: number;
+        seconds: number;
+    };
+}
+/**
+ * Hook to manage countdown timer
+ * @param initialCount - Initial countdown value in milliseconds
+ * @param options - Configuration options
+ */
+declare function useCountdown(initialCount: number, options?: UseCountdownOptions): UseCountdownReturn;
+
+interface UseContinuousRetryOptions {
+    /** Maximum number of retry attempts (default: Infinity) */
+    maxAttempts?: number;
+    /** Delay between retries in milliseconds (default: 1000) */
+    delay?: number;
+    /** Whether to use exponential backoff (default: false) */
+    exponentialBackoff?: boolean;
+    /** Maximum delay when using exponential backoff (default: 30000) */
+    maxDelay?: number;
+    /** Auto-start retrying (default: true) */
+    autoStart?: boolean;
+}
+interface UseContinuousRetryReturn {
+    /** Number of attempts made */
+    attempts: number;
+    /** Last error encountered */
+    error: Error | null;
+    /** Is currently retrying? */
+    isRetrying: boolean;
+    /** Has succeeded? */
+    isSuccess: boolean;
+    /** Has reached max attempts? */
+    isMaxAttempts: boolean;
+    /** Start/restart retrying */
+    start: () => void;
+    /** Stop retrying */
+    stop: () => void;
+    /** Reset state */
+    reset: () => void;
+}
+/**
+ * Hook to continuously retry a function until success
+ * @param callback - Async function to retry (return true for success, false for retry)
+ * @param options - Configuration options
+ */
+declare function useContinuousRetry(callback: () => Promise<boolean> | boolean, options?: UseContinuousRetryOptions): UseContinuousRetryReturn;
+
+interface WindowSize {
+    width: number;
+    height: number;
+}
+/**
+ * Track window dimensions with resize updates
+ * @param debounceMs - Debounce resize events (default: 100ms)
+ */
+declare function useWindowSize(debounceMs?: number): WindowSize;
+
+interface WindowScrollPosition {
+    /** Horizontal scroll position */
+    x: number;
+    /** Vertical scroll position */
+    y: number;
+    /** Scroll direction (up, down, left, right, or null) */
+    direction: 'up' | 'down' | 'left' | 'right' | null;
+    /** Is scrolling? */
+    isScrolling: boolean;
+}
+interface UseWindowScrollReturn extends WindowScrollPosition {
+    /** Scroll to position */
+    scrollTo: (options: ScrollToOptions) => void;
+    /** Scroll to top */
+    scrollToTop: (behavior?: ScrollBehavior) => void;
+    /** Scroll to bottom */
+    scrollToBottom: (behavior?: ScrollBehavior) => void;
+}
+/**
+ * Hook to track and control window scroll position
+ */
+declare function useWindowScroll(): UseWindowScrollReturn;
+
+interface UseDocumentTitleOptions {
+    /** Restore previous title on unmount (default: true) */
+    restoreOnUnmount?: boolean;
+    /** Title template, use %s for title placeholder */
+    template?: string;
+}
+/**
+ * Hook to set document title
+ * @param title - Document title
+ * @param options - Configuration options
+ */
+declare function useDocumentTitle(title: string, options?: UseDocumentTitleOptions): void;
+
+interface UsePageTitleOptions {
+    /** Suffix to append to the title (e.g., organization name) */
+    suffix?: string;
+    /** Separator between title and suffix (default: ' | ') */
+    separator?: string;
+    /** Whether to restore original title on unmount (default: true) */
+    restoreOnUnmount?: boolean;
+}
+/**
+ * Set the document title with optional suffix
+ * @param title - Page title
+ * @param options - Configuration options
+ */
+declare function usePageTitle(title: string, options?: UsePageTitleOptions): void;
+
+/**
+ * Hook to dynamically change favicon
+ * @param href - URL of the favicon image
+ * @param restoreOnUnmount - Whether to restore original favicon on unmount (default: true)
+ */
+declare function useFavicon(href: string, restoreOnUnmount?: boolean): void;
+
+interface UseVisibilityChangeReturn {
+    /** Is document visible? */
+    isVisible: boolean;
+    /** Visibility state ('visible', 'hidden', 'prerender') */
+    visibilityState: DocumentVisibilityState;
+    /** Time when visibility last changed */
+    lastChanged: Date | null;
+}
+/**
+ * Hook to track document visibility state
+ * @param onVisibilityChange - Optional callback when visibility changes
+ */
+declare function useVisibilityChange(onVisibilityChange?: (isVisible: boolean) => void): UseVisibilityChangeReturn;
+
+interface UsePageLeaveOptions {
+    /** Show confirmation dialog on page leave (default: false) */
+    showConfirmation?: boolean;
+    /** Custom confirmation message (browser may override) */
+    confirmationMessage?: string;
+}
+/**
+ * Hook to detect when user is leaving the page
+ * @param onLeave - Callback when user attempts to leave
+ * @param options - Configuration options
+ */
+declare function usePageLeave(onLeave?: () => void, options?: UsePageLeaveOptions): void;
+
+/**
+ * Hook to lock body scroll
+ * @param locked - Whether scroll should be locked (default: true)
+ */
+declare function useLockBodyScroll(locked?: boolean): void;
+
+/**
+ * Hook to check if rendering on client side
+ * Useful for SSR/SSG environments
+ */
+declare function useIsClient(): boolean;
+
+/**
+ * Hook to check if it's the first render
+ */
+declare function useIsFirstRender(): boolean;
+
+type EventMap = WindowEventMap & DocumentEventMap & HTMLElementEventMap;
+/**
+ * Hook to attach event listeners declaratively
+ * @param eventName - Name of the event to listen for
+ * @param handler - Event handler function
+ * @param element - Target element (default: window)
+ * @param options - AddEventListener options
+ */
+declare function useEventListener<K extends keyof EventMap>(eventName: K, handler: (event: EventMap[K]) => void, element?: HTMLElement | Window | Document | null, options?: boolean | AddEventListenerOptions): void;
+
+interface UseKeyPressOptions {
+    /** Target element (default: document) */
+    target?: HTMLElement | Document | Window | null;
+    /** Event type: 'keydown' | 'keyup' | 'keypress' */
+    event?: 'keydown' | 'keyup' | 'keypress';
+    /** Prevent default behavior */
+    preventDefault?: boolean;
+    /** Stop event propagation */
+    stopPropagation?: boolean;
+}
+interface UseKeyPressReturn {
+    /** Is the key currently pressed? */
+    pressed: boolean;
+    /** Event object from last press */
+    event: KeyboardEvent | null;
+}
+/**
+ * Hook to detect key press
+ * @param targetKey - Key to detect (e.g., 'Enter', 'Escape', 'a')
+ * @param callback - Optional callback when key is pressed
+ * @param options - Configuration options
+ */
+declare function useKeyPress(targetKey: string | string[], callback?: (event: KeyboardEvent) => void, options?: UseKeyPressOptions): UseKeyPressReturn;
+
+interface UseHoverReturn<T extends HTMLElement = HTMLElement> {
+    /** Ref to attach to the target element */
+    ref: React.RefObject<T | null>;
+    /** Is element being hovered? */
+    isHovered: boolean;
+    /** Bind props to spread on element */
+    bind: {
+        onMouseEnter: () => void;
+        onMouseLeave: () => void;
+    };
+}
+/**
+ * Hook to detect hover state
+ * @param onHoverChange - Optional callback when hover state changes
+ */
+declare function useHover<T extends HTMLElement = HTMLElement>(onHoverChange?: (isHovered: boolean) => void): UseHoverReturn<T>;
+
+type EventType = 'mousedown' | 'mouseup' | 'touchstart' | 'touchend';
+/**
+ * Hook to detect clicks outside of an element
+ * @param callback - Function to call when click outside occurs
+ * @param events - Event types to listen for (default: ['mousedown', 'touchstart'])
+ */
+declare function useClickAway<T extends HTMLElement = HTMLElement>(callback: (event: MouseEvent | TouchEvent) => void, events?: EventType[]): React.RefObject<T | null>;
+
+/**
+ * useOnClickOutside Hook
+ * Detect clicks outside of a referenced element
+ */
+
+type Handler = (event: MouseEvent | TouchEvent) => void;
+/**
+ * Detect clicks outside of a referenced element
+ * @param ref - React ref to the element
+ * @param handler - Callback when click outside occurs
+ * @param enabled - Whether the hook is enabled (default: true)
+ */
+declare function useOnClickOutside<T extends HTMLElement = HTMLElement>(ref: RefObject<T>, handler: Handler, enabled?: boolean): void;
+
+interface UseLongPressOptions {
+    /** Threshold in milliseconds (default: 400) */
+    threshold?: number;
+    /** Callback on long press */
+    onLongPress?: (event: React.MouseEvent | React.TouchEvent) => void;
+    /** Callback on regular click */
+    onClick?: (event: React.MouseEvent | React.TouchEvent) => void;
+    /** Callback when press starts */
+    onStart?: (event: React.MouseEvent | React.TouchEvent) => void;
+    /** Callback when press ends */
+    onFinish?: (event: React.MouseEvent | React.TouchEvent) => void;
+    /** Callback when press is cancelled */
+    onCancel?: (event: React.MouseEvent | React.TouchEvent) => void;
+}
+interface UseLongPressReturn {
+    /** Is currently pressing? */
+    isPressed: boolean;
+    /** Is long press achieved? */
+    isLongPress: boolean;
+    /** Bind props to spread on element */
+    bind: {
+        onMouseDown: (e: React.MouseEvent) => void;
+        onMouseUp: (e: React.MouseEvent) => void;
+        onMouseLeave: (e: React.MouseEvent) => void;
+        onTouchStart: (e: React.TouchEvent) => void;
+        onTouchEnd: (e: React.TouchEvent) => void;
+    };
+}
+/**
+ * Hook to detect long press gesture
+ * @param options - Configuration options
+ */
+declare function useLongPress(options?: UseLongPressOptions): UseLongPressReturn;
+
+interface MousePosition {
+    /** X position relative to viewport */
+    x: number;
+    /** Y position relative to viewport */
+    y: number;
+    /** X position relative to page */
+    pageX: number;
+    /** Y position relative to page */
+    pageY: number;
+    /** X position relative to element (if ref provided) */
+    elementX: number;
+    /** Y position relative to element (if ref provided) */
+    elementY: number;
+    /** Is mouse within element bounds? */
+    isInElement: boolean;
+}
+interface UseMouseOptions {
+    /** Whether to track (default: true) */
+    enabled?: boolean;
+}
+interface UseMouseReturn<T extends HTMLElement = HTMLElement> extends MousePosition {
+    /** Ref to attach to element for relative positioning */
+    ref: React.RefObject<T | null>;
+}
+/**
+ * Hook to track mouse position
+ * @param options - Configuration options
+ */
+declare function useMouse<T extends HTMLElement = HTMLElement>(options?: UseMouseOptions): UseMouseReturn<T>;
+
+interface UseCopyToClipboardReturn {
+    /** Copy text to clipboard */
+    copy: (text: string) => Promise<boolean>;
+    /** Whether copy was successful (resets after timeout) */
+    copied: boolean;
+    /** Error message if copy failed */
+    error: string | null;
+    /** Reset state */
+    reset: () => void;
+}
+/**
+ * Copy text to clipboard with feedback
+ * @param resetDelay - Time in ms before copied state resets (default: 2000)
+ */
+declare function useCopyToClipboard(resetDelay?: number): UseCopyToClipboardReturn;
+
+/**
+ * Track a media query match
+ * @param query - CSS media query string (e.g., '(min-width: 768px)')
+ */
+declare function useMediaQuery(query: string): boolean;
+declare const useIsMobile: () => boolean;
+declare const useIsTablet: () => boolean;
+declare const useIsDesktop: () => boolean;
+declare const useIsMobileOrTablet: () => boolean;
+
+interface OrientationState {
+    /** Device orientation angle */
+    angle: number;
+    /** Orientation type */
+    type: OrientationType;
+    /** Is portrait? */
+    isPortrait: boolean;
+    /** Is landscape? */
+    isLandscape: boolean;
+}
+/**
+ * Hook to track device/screen orientation
+ */
+declare function useOrientation(): OrientationState;
+
+interface BatteryState {
+    /** Is battery API supported? */
+    isSupported: boolean;
+    /** Is device charging? */
+    charging: boolean;
+    /** Time until fully charged (seconds), Infinity if not charging */
+    chargingTime: number;
+    /** Time until discharged (seconds), Infinity if charging */
+    dischargingTime: number;
+    /** Battery level (0 to 1) */
+    level: number;
+    /** Battery percentage (0 to 100) */
+    percentage: number;
+}
+/**
+ * Hook to track battery status
+ */
+declare function useBattery(): BatteryState;
+
+interface NetworkState {
+    /** Is online? */
+    online: boolean;
+    /** Is offline? */
+    offline: boolean;
+    /** Connection downlink speed (Mbps) */
+    downlink?: number;
+    /** Effective connection type */
+    effectiveType?: 'slow-2g' | '2g' | '3g' | '4g';
+    /** Round-trip time (ms) */
+    rtt?: number;
+    /** Is data saver enabled? */
+    saveData?: boolean;
+    /** Connection type */
+    type?: string;
+    /** Time when status last changed */
+    since?: Date;
+}
+/**
+ * Hook to track network status
+ */
+declare function useNetworkState(): NetworkState;
+
+interface UseIdleOptions {
+    /** Idle timeout in milliseconds (default: 60000 = 1 minute) */
+    timeout?: number;
+    /** Events to consider as activity */
+    events?: string[];
+    /** Initial idle state */
+    initialState?: boolean;
+    /** Callback when user becomes idle */
+    onIdle?: () => void;
+    /** Callback when user becomes active */
+    onActive?: () => void;
+}
+interface UseIdleReturn {
+    /** Is user idle? */
+    isIdle: boolean;
+    /** Last active timestamp */
+    lastActive: Date;
+    /** Reset idle timer */
+    reset: () => void;
+    /** Start tracking */
+    start: () => void;
+    /** Stop tracking */
+    stop: () => void;
+}
+/**
+ * Hook to detect user idle state
+ * @param options - Configuration options
+ */
+declare function useIdle(options?: UseIdleOptions): UseIdleReturn;
+
+interface GeolocationState {
+    /** Is loading? */
+    loading: boolean;
+    /** Error message */
+    error: string | null;
+    /** Latitude */
+    latitude: number | null;
+    /** Longitude */
+    longitude: number | null;
+    /** Accuracy in meters */
+    accuracy: number | null;
+    /** Altitude in meters */
+    altitude: number | null;
+    /** Altitude accuracy in meters */
+    altitudeAccuracy: number | null;
+    /** Heading in degrees */
+    heading: number | null;
+    /** Speed in m/s */
+    speed: number | null;
+    /** Timestamp */
+    timestamp: number | null;
+}
+interface UseGeolocationOptions {
+    /** Enable high accuracy mode */
+    enableHighAccuracy?: boolean;
+    /** Maximum age of cached position (ms) */
+    maximumAge?: number;
+    /** Timeout for getting position (ms) */
+    timeout?: number;
+    /** Watch position continuously */
+    watch?: boolean;
+}
+interface UseGeolocationReturn extends GeolocationState {
+    /** Refresh position */
+    refresh: () => void;
+    /** Is geolocation supported? */
+    isSupported: boolean;
+}
+/**
+ * Hook to track geolocation
+ * @param options - Configuration options
+ */
+declare function useGeolocation(options?: UseGeolocationOptions): UseGeolocationReturn;
+
+interface UsePreferredLanguageReturn {
+    /** Primary preferred language */
+    language: string;
+    /** All preferred languages */
+    languages: readonly string[];
+}
+/**
+ * Hook to get user's preferred language
+ */
+declare function usePreferredLanguage(): UsePreferredLanguageReturn;
+
+type ThemeMode = 'light' | 'dark';
+/**
+ * Detect and track system color scheme preference
+ * @returns Current theme mode based on system preference
+ */
+declare function useThemeDetector(): ThemeMode;
+
+type SetValue<T> = T | ((prevValue: T) => T);
+interface UseLocalStorageOptions<T> {
+    /** Serialize function (default: JSON.stringify) */
+    serializer?: (value: T) => string;
+    /** Deserialize function (default: JSON.parse) */
+    deserializer?: (value: string) => T;
+    /** Enable cross-tab synchronization (default: true) */
+    syncTabs?: boolean;
+    /** Enable logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * Hook to persist state in localStorage with cross-tab sync
+ * @param key - localStorage key
+ * @param initialValue - initial/fallback value
+ * @param options - configuration options
+ */
+declare function useLocalStorage<T>(key: string, initialValue: T, options?: UseLocalStorageOptions<T>): [T, (value: SetValue<T>) => void, () => void];
+
+interface UseSessionStorageOptions<T> {
+    /** Serialize function (default: JSON.stringify) */
+    serializer?: (value: T) => string;
+    /** Deserialize function (default: JSON.parse) */
+    deserializer?: (value: string) => T;
+    /** Enable logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * Hook to persist state in sessionStorage
+ * @param key - sessionStorage key
+ * @param initialValue - initial/fallback value
+ * @param options - configuration options
+ */
+declare function useSessionStorage<T>(key: string, initialValue: T, options?: UseSessionStorageOptions<T>): [T, (value: SetValue<T>) => void, () => void];
+
+interface UseFetchOptions<T> extends Omit<RequestInit, 'body'> {
+    /** Request body (will be JSON.stringify'd if object) */
+    body?: BodyInit | object | null;
+    /** Skip initial fetch */
+    skip?: boolean;
+    /** Transform response data */
+    transform?: (data: unknown) => T;
+    /** Retry count on failure */
+    retries?: number;
+    /** Retry delay in ms */
+    retryDelay?: number;
+    /** Cache key (default: url) */
+    cacheKey?: string;
+    /** Cache time in ms */
+    cacheTime?: number;
+    /** Callback on success */
+    onSuccess?: (data: T) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+interface UseFetchReturn<T> {
+    /** Response data */
+    data: T | null;
+    /** Is loading? */
+    loading: boolean;
+    /** Error */
+    error: Error | null;
+    /** Refetch data */
+    refetch: () => Promise<T | null>;
+    /** Abort current request */
+    abort: () => void;
+    /** Is fetching? (includes refetch) */
+    isFetching: boolean;
+    /** HTTP status code */
+    status: number | null;
+}
+/**
+ * Hook for data fetching with caching and retry support
+ * @param url - URL to fetch
+ * @param options - Fetch options
+ */
+declare function useFetch<T = unknown>(url: string | null, options?: UseFetchOptions<T>): UseFetchReturn<T>;
+
+type ScriptStatus = 'idle' | 'loading' | 'ready' | 'error';
+interface UseScriptOptions {
+    /** Should load script immediately (default: true) */
+    shouldLoad?: boolean;
+    /** Remove script on unmount (default: false) */
+    removeOnUnmount?: boolean;
+    /** Script attributes */
+    attributes?: Record<string, string>;
+}
+interface UseScriptReturn {
+    /** Script loading status */
+    status: ScriptStatus;
+    /** Is script ready? */
+    ready: boolean;
+    /** Is loading? */
+    loading: boolean;
+    /** Has error? */
+    error: boolean;
+    /** Load script manually */
+    load: () => void;
+    /** Remove script */
+    remove: () => void;
+}
+/**
+ * Hook to dynamically load external scripts
+ * @param src - Script source URL
+ * @param options - Configuration options
+ */
+declare function useScript(src: string, options?: UseScriptOptions): UseScriptReturn;
+
+interface RenderInfo {
+    /** Component name (if provided) */
+    name: string;
+    /** Total render count */
+    renders: number;
+    /** Time since last render (ms) */
+    sinceLastRender: number;
+    /** Timestamp of last render */
+    timestamp: number;
+}
+/**
+ * Hook to track render information for debugging
+ * @param componentName - Optional component name for identification
+ */
+declare function useRenderInfo(componentName?: string): RenderInfo;
+
+/**
+ * Hook to count component renders
+ */
+declare function useRenderCount(): number;
+
+interface UseLoggerOptions {
+    /** Log props changes */
+    logProps?: boolean;
+    /** Log lifecycle events */
+    logLifecycle?: boolean;
+    /** Custom logger function */
+    logger?: (...args: unknown[]) => void;
+}
+/**
+ * Hook to log component lifecycle and changes
+ * @param componentName - Name of the component
+ * @param props - Props to track changes
+ * @param options - Configuration options
+ */
+declare function useLogger(componentName: string, props?: Record<string, unknown>, options?: UseLoggerOptions): void;
+
+interface Dimensions {
+    /** Element width */
+    width: number;
+    /** Element height */
+    height: number;
+    /** Top position relative to viewport */
+    top: number;
+    /** Left position relative to viewport */
+    left: number;
+    /** Bottom position relative to viewport */
+    bottom: number;
+    /** Right position relative to viewport */
+    right: number;
+    /** X position (same as left) */
+    x: number;
+    /** Y position (same as top) */
+    y: number;
+}
+interface UseMeasureReturn<T extends HTMLElement = HTMLElement> {
+    /** Ref to attach to element */
+    ref: React.RefCallback<T>;
+    /** Element dimensions */
+    dimensions: Dimensions;
+    /** Manually trigger measurement */
+    measure: () => void;
+}
+/**
+ * Hook to measure element dimensions
+ */
+declare function useMeasure<T extends HTMLElement = HTMLElement>(): UseMeasureReturn<T>;
+
+interface UseIntersectionObserverOptions {
+    /** Root element (default: viewport) */
+    root?: Element | null;
+    /** Root margin (default: '0px') */
+    rootMargin?: string;
+    /** Intersection threshold(s) (default: 0) */
+    threshold?: number | number[];
+    /** Freeze after first intersection */
+    freezeOnceVisible?: boolean;
+    /** Initial visibility state */
+    initialIsIntersecting?: boolean;
+    /** Callback when intersection changes */
+    onChange?: (isIntersecting: boolean, entry: IntersectionObserverEntry) => void;
+}
+interface UseIntersectionObserverReturn<T extends Element = Element> {
+    /** Ref to attach to element */
+    ref: React.RefCallback<T>;
+    /** Is element intersecting? */
+    isIntersecting: boolean;
+    /** Full intersection entry */
+    entry: IntersectionObserverEntry | null;
+}
+/**
+ * Hook to observe element intersection with viewport
+ * @param options - IntersectionObserver options
+ */
+declare function useIntersectionObserver<T extends Element = Element>(options?: UseIntersectionObserverOptions): UseIntersectionObserverReturn<T>;
+
+type SnackbarSeverity = 'success' | 'error' | 'warning' | 'info';
+interface SnackbarState {
+    open: boolean;
+    message: string;
+    severity: SnackbarSeverity;
+    autoHideDuration?: number;
+}
+interface UseSnackbarReturn {
+    /** Current snackbar state */
+    state: SnackbarState;
+    /** Show snackbar with message */
+    show: (message: string, severity?: SnackbarSeverity, duration?: number) => void;
+    /** Show success snackbar */
+    success: (message: string, duration?: number) => void;
+    /** Show error snackbar */
+    error: (message: string, duration?: number) => void;
+    /** Show warning snackbar */
+    warning: (message: string, duration?: number) => void;
+    /** Show info snackbar */
+    info: (message: string, duration?: number) => void;
+    /** Close snackbar */
+    close: () => void;
+}
+/**
+ * Manage snackbar/toast notification state
+ * @param defaultDuration - Default auto-hide duration in ms
+ */
+declare function useSnackbar(defaultDuration?: number): UseSnackbarReturn;
+
+export { type BatteryState, type Dimensions, type GeolocationState, type MousePosition, type NetworkState, type ObjectStateUpdate, type OrientationState, type RenderInfo, type ScriptStatus, type SetValue, type SnackbarSeverity, type SnackbarState, type ThemeMode, type UseContinuousRetryOptions, type UseContinuousRetryReturn, type UseCopyToClipboardReturn, type UseCountdownOptions, type UseCountdownReturn, type UseCounterOptions, type UseCounterReturn, type UseDocumentTitleOptions, type UseFetchOptions, type UseFetchReturn, type UseGeolocationOptions, type UseGeolocationReturn, type UseHistoryStateOptions, type UseHistoryStateReturn, type UseHoverReturn, type UseIdleOptions, type UseIdleReturn, type UseIntersectionObserverOptions, type UseIntersectionObserverReturn, type UseKeyPressOptions, type UseKeyPressReturn, type UseListReturn, type UseLocalStorageOptions, type UseLoggerOptions, type UseLongPressOptions, type UseLongPressReturn, type UseMapReturn, type UseMeasureReturn, type UseMouseOptions, type UseMouseReturn, type UseObjectStateReturn, type UsePageLeaveOptions, type UsePageTitleOptions, type UsePreferredLanguageReturn, type UseQueueReturn, type UseScriptOptions, type UseScriptReturn, type UseSessionStorageOptions, type UseSetReturn, type UseSnackbarReturn, type UseTimeoutReturn, type UseToggleReturn, type UseVisibilityChangeReturn, type UseWindowScrollReturn, type WindowScrollPosition, type WindowSize, useBattery, useClickAway, useContinuousRetry, useCopyToClipboard, useCountdown, useCounter, useDebounce, useDefault, useDocumentTitle, useEventListener, useFavicon, useFetch, useGeolocation, useHistoryState, useHover, useIdle, useIntersectionObserver, useInterval, useIntervalWhen, useIsClient, useIsDesktop, useIsFirstRender, useIsMobile, useIsMobileOrTablet, useIsTablet, useKeyPress, useList, useLocalStorage, useLockBodyScroll, useLogger, useLongPress, useMap, useMeasure, useMediaQuery, useMouse, useNetworkState, useObjectState, useOnClickOutside, useOrientation, usePageLeave, usePageTitle, usePreferredLanguage, usePrevious, useQueue, useRandomInterval, useRenderCount, useRenderInfo, useScript, useSessionStorage, useSet, useSnackbar, useThemeDetector, useThrottle, useTimeout, useToggle, useVisibilityChange, useWindowScroll, useWindowSize };