useEventListener

1"use client"
2 
3import * as React from "react"
4 
5export interface UseEventListenerOptions {
6  /** Passed straight through as the native addEventListener `passive`. */
7  passive?: boolean
8  /** Passed straight through as the native addEventListener/removeEventListener `capture`. */
9  capture?: boolean
10}
11 
12type TargetRef<T extends HTMLElement> = React.RefObject<T | null>
13 
14// Overload 1: no target, or window passed explicitly — event names map to WindowEventMap.
15export function useEventListener<K extends keyof WindowEventMap>(
16  eventName: K,
17  handler: (event: WindowEventMap[K]) => void,
18  options?: UseEventListenerOptions & { target?: Window },
19): void
20 
21// Overload 2: document as the target — event names map to DocumentEventMap.
22export function useEventListener<K extends keyof DocumentEventMap>(
23  eventName: K,
24  handler: (event: DocumentEventMap[K]) => void,
25  options: UseEventListenerOptions & { target: Document },
26): void
27 
28// Overload 3: an element RefObject as the target — event names map to
29// HTMLElementEventMap, and T is inferred from the ref at the call site (say
30// RefObject<HTMLDivElement>).
31// Note: the effect depends on the ref object itself (stable identity). If .current
32// is null when the effect runs, nothing is bound this round and nothing re-binds
33// later — for a conditionally rendered target, remount the consumer with a key or
34// switch to the callback-ref pattern (see use-hover). This fits targets that live as
35// long as the component: window / document / an element always in the tree.
36export function useEventListener<K extends keyof HTMLElementEventMap, T extends HTMLElement = HTMLElement>(
37  eventName: K,
38  handler: (event: HTMLElementEventMap[K]) => void,
39  options: UseEventListenerOptions & { target: TargetRef<T> },
40): void
41 
42/**
43 * Typed event listening against three kinds of target — window (the default),
44 * document, or any element ref — narrowing `eventName` / `handler` to the native
45 * event map that matches.
46 *
47 * The core is the latest-ref for the handler: `handler` is synced into a ref after
48 * every render, while the effect that actually calls `addEventListener` depends only
49 * on `eventName` / `target` / the primitives pulled out of `options`
50 * (`passive` / `capture`) — never on the `options` object, and never on `handler`.
51 * So a consumer passing a freshly built `handler` on every render (closing over the
52 * latest state, which is the common case) does not thrash the listener; when it
53// … truncated