useEventListener — Agrega listeners de eventos declarativamente con limpieza automática

import { useEffect, useRef } from "react";
 
/**
 * useEventListener
 * Agrega un listener de evento a window, document o cualquier ref de elemento.
 * Usa el patrón de ref de callback más reciente para evitar volver a suscribirse en
 * cambios de callback. Se limpia automáticamente en desmontar.
 */
 
// Sobrecarga: eventos de window
function useEventListener<K extends keyof WindowEventMap>(
  eventName: K,
  handler: (event: WindowEventMap[K]) => void,
  element?: undefined,
  options?: boolean | AddEventListenerOptions
): void;
 
// Sobrecarga: eventos de document
function useEventListener<K extends keyof DocumentEventMap>(
  eventName: K,
  handler: (event: DocumentEventMap[K]) => void,
  element: Document,
  options?: boolean | AddEventListenerOptions
): void;
 
// Sobrecarga: eventos de elementos HTML
function useEventListener<
  K extends keyof HTMLElementEventMap,
  T extends HTMLElement = HTMLDivElement
>(
  eventName: K,
  handler: (event: HTMLElementEventMap[K]) => void,
  element: React.RefObject<T | null>,
  options?: boolean | AddEventListenerOptions
): void;
 
// Implementación
function useEventListener(
  eventName: string,
  handler: (event: Event) => void,
  element?: Document | React.RefObject<HTMLElement | null>,
  options?: boolean | AddEventListenerOptions
): void {
  const handlerRef = useRef(handler);
 
  useEffect(() => {
    handlerRef.current = handler;
  }, [handler]);
 
  useEffect(() => {
    // Determina el elemento objetivo
    let targetElement: EventTarget;
 
    if (element === undefined) {
      // Por defecto es window
      if (typeof window === "undefined") return;
      targetElement = window;
    } else if (element instanceof Document) {
      targetElement = element;
    } else {
      // Es una ref
      if (!element.current) return;
      targetElement = element.current;
    }
 
    const listener = (event: Event) => handlerRef.current(event);
 
    targetElement.addEventListener(eventName, listener, options);
 
    return () => {
      targetElement.removeEventListener(eventName, listener, options);
    };
  }, [eventName, element, options]);
}

"use client";
 
import { useState, useRef } from "react";
 
// Rastrear estado en línea/fuera de línea
function OnlineStatus() {
  const [isOnline, setIsOnline] = useState(true);
 
  useEventListener("online", () => setIsOnline(true));
  useEventListener("offline", () => setIsOnline(false));
 
  return (
    <div
      style={{
        padding: 8,
        background: isOnline ? "#dcfce7" : "#fee2e2",
        borderRadius: 4,
      }}
    >
      {isOnline ? "En línea" : "Fuera de línea"}
    </div>
  );
}
 
// Rastrear posición del ratón en un elemento
function MouseTracker() {
  const ref = useRef<HTMLDivElement>(null);
  const [position, setPosition] = useState({ x: 0, y: 0 });
 
  useEventListener(
    "mousemove",
    (event) => {
      const rect = ref.current?.getBoundingClientRect();
      if (rect) {
        setPosition({
          x: event.clientX - rect.left,
          y: event.clientY - rect.top,
        });
      }
    },
    ref
  );
 
  return (
    <div
      ref={ref}
      style={{
        width: 300,
        height: 200,
        background: "#f5f5f5",
        border: "1px solid #ccc",
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
        cursor: "crosshair",
      }}
    >
      x: {position.x}, y: {position.y}
    </div>
  );
}
 
// Eventos de teclado en document
function KeyLogger() {
  const [lastKey, setLastKey] = useState("");
 
  useEventListener(
    "keydown",
    (event) => {
      setLastKey(event.key);
    },
    document
  );
 
  return <p>Última tecla presionada: {lastKey || "ninguna"}</p>;
}
 
// Desplazamiento con opción passive
function ScrollTracker() {
  const [scrollY, setScrollY] = useState(0);
 
  useEventListener(
    "scroll",
    () => setScrollY(window.scrollY),
    undefined,
    { passive: true }
  );
 
  return (
    <div style={{ position: "fixed", top: 0, right: 0, padding: 8 }}>
      Desplazamiento: {scrollY}px
    </div>
  );
}

function useEventListener(eventName, handler, element) {
  // ...misma configuración...
  const removeRef = useRef<(() => void) | null>(null);
 
  useEffect(() => {
    // ...misma lógica...
    removeRef.current = () => {
      targetElement.removeEventListener(eventName, listener, options);
    };
    return removeRef.current;
  }, [eventName, element, options]);
 
  return { remove: () => removeRef.current?.() };
}

// Esto es esencialmente lo que useMediaQuery hace internamente
const mql = window.matchMedia("(max-width: 768px)");
useEventListener("change", (e) => setIsMobile(e.matches), { current: mql } as any);

useEventListener("my-custom-event", (event) => {
  console.log((event as CustomEvent).detail);
});