import { RefObject } from 'react';

/**
 * Options for useEventListener hook
 */
interface UseEventListenerOptions {
    /**
     * Whether the event listener is enabled
     * @default true
     */
    enabled?: boolean;
    /**
     * Whether to use event capture phase
     * @default false
     */
    capture?: boolean;
    /**
     * Whether to use passive event listener for performance optimization
     * Useful for scroll/touch events
     * @default undefined (browser default)
     */
    passive?: boolean;
    /**
     * Whether the handler should be invoked only once and then removed
     * @default false
     */
    once?: boolean;
}
/**
 * Supported event target types
 */
type EventTargetType<T extends HTMLElement = HTMLElement> = Window | Document | HTMLElement | RefObject<T | null> | null | undefined;
/**
 * Adds an event listener to the window (default) or specified element.
 *
 * @param eventName - The event type to listen for
 * @param handler - The callback function called when the event fires
 * @param element - The target element (defaults to window)
 * @param options - Configuration options
 *
 * @example
 * ```tsx
 * // Window resize event
 * useEventListener("resize", (e) => {
 *   console.log("Window resized:", window.innerWidth);
 * });
 * ```
 */
declare function useEventListener<K extends keyof WindowEventMap>(eventName: K, handler: (event: WindowEventMap[K]) => void, element?: Window | null, options?: UseEventListenerOptions): void;
/**
 * Adds an event listener to the document.
 *
 * @example
 * ```tsx
 * // Document keydown event
 * useEventListener("keydown", (e) => {
 *   console.log("Key pressed:", e.key);
 * }, document);
 * ```
 */
declare function useEventListener<K extends keyof DocumentEventMap>(eventName: K, handler: (event: DocumentEventMap[K]) => void, element: Document, options?: UseEventListenerOptions): void;
/**
 * Adds an event listener to an HTMLElement.
 *
 * @example
 * ```tsx
 * // HTMLElement click event
 * const button = document.getElementById("myButton");
 * useEventListener("click", (e) => {
 *   console.log("Button clicked");
 * }, button);
 * ```
 */
declare function useEventListener<K extends keyof HTMLElementEventMap>(eventName: K, handler: (event: HTMLElementEventMap[K]) => void, element: HTMLElement | null, options?: UseEventListenerOptions): void;
/**
 * Adds an event listener to an element referenced by a RefObject.
 *
 * @example
 * ```tsx
 * // RefObject event
 * const ref = useRef<HTMLDivElement>(null);
 * useEventListener("scroll", (e) => {
 *   console.log("Element scrolled");
 * }, ref);
 * ```
 */
declare function useEventListener<K extends keyof HTMLElementEventMap, T extends HTMLElement>(eventName: K, handler: (event: HTMLElementEventMap[K]) => void, element: RefObject<T | null>, options?: UseEventListenerOptions): void;
/**
 * Adds an event listener for custom events.
 *
 * @example
 * ```tsx
 * // Custom event
 * useEventListener("myCustomEvent", (e) => {
 *   console.log("Custom event fired");
 * }, document);
 * ```
 */
declare function useEventListener(eventName: string, handler: (event: Event) => void, element?: EventTargetType, options?: UseEventListenerOptions): void;

export { type EventTargetType, type UseEventListenerOptions, useEventListener };