@usefy/use-event-listener 0.0.16

package/README.md

@@ -0,0 +1,505 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/geon0529/usefy/master/assets/logo.png" alt="usefy logo" width="120" />
+</p>
+
+<h1 align="center">@usefy/use-event-listener</h1>
+
+<p align="center">
+  <strong>A React hook for adding event listeners to DOM elements with automatic cleanup</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@usefy/use-event-listener">
+    <img src="https://img.shields.io/npm/v/@usefy/use-event-listener.svg?style=flat-square&color=007acc" alt="npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/@usefy/use-event-listener">
+    <img src="https://img.shields.io/npm/dm/@usefy/use-event-listener.svg?style=flat-square&color=007acc" alt="npm downloads" />
+  </a>
+  <a href="https://bundlephobia.com/package/@usefy/use-event-listener">
+    <img src="https://img.shields.io/bundlephobia/minzip/@usefy/use-event-listener?style=flat-square&color=007acc" alt="bundle size" />
+  </a>
+  <a href="https://github.com/geon0529/usefy/blob/master/LICENSE">
+    <img src="https://img.shields.io/npm/l/@usefy/use-event-listener.svg?style=flat-square&color=007acc" alt="license" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api-reference">API Reference</a> •
+  <a href="#examples">Examples</a> •
+  <a href="#license">License</a>
+</p>
+
+---
+
+## Overview
+
+`@usefy/use-event-listener` provides a simple way to add event listeners to DOM elements with automatic cleanup on unmount. It supports window, document, HTMLElement, and RefObject targets with full TypeScript type inference.
+
+**Part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem** — a collection of production-ready React hooks designed for modern applications.
+
+### Why use-event-listener?
+
+- **Zero Dependencies** — Pure React implementation with no external dependencies
+- **TypeScript First** — Full type safety with automatic event type inference
+- **Multiple Targets** — Support for window, document, HTMLElement, and RefObject
+- **Automatic Cleanup** — Event listeners are removed on unmount
+- **Handler Stability** — No re-registration when handler changes
+- **Conditional Activation** — Enable/disable via the `enabled` option
+- **Performance Options** — Support for `passive`, `capture`, and `once` options
+- **SSR Compatible** — Works seamlessly with Next.js, Remix, and other SSR frameworks
+- **Well Tested** — Comprehensive test coverage with Vitest
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @usefy/use-event-listener
+
+# yarn
+yarn add @usefy/use-event-listener
+
+# pnpm
+pnpm add @usefy/use-event-listener
+```
+
+### Peer Dependencies
+
+This package requires React 18 or 19:
+
+```json
+{
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { useEventListener } from "@usefy/use-event-listener";
+
+function WindowResizeTracker() {
+  const [size, setSize] = useState({ width: 0, height: 0 });
+
+  useEventListener("resize", () => {
+    setSize({ width: window.innerWidth, height: window.innerHeight });
+  });
+
+  return (
+    <div>
+      Window size: {size.width} × {size.height}
+    </div>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### `useEventListener(eventName, handler, element?, options?)`
+
+A hook that adds an event listener to the specified target.
+
+#### Parameters
+
+| Parameter   | Type                      | Description                                          |
+| ----------- | ------------------------- | ---------------------------------------------------- |
+| `eventName` | `string`                  | The event type to listen for (e.g., "click", "resize") |
+| `handler`   | `(event: Event) => void`  | Callback function called when the event fires        |
+| `element`   | `EventTargetType`         | Target element (defaults to window)                  |
+| `options`   | `UseEventListenerOptions` | Configuration options                                |
+
+#### Options
+
+| Option    | Type      | Default     | Description                                      |
+| --------- | --------- | ----------- | ------------------------------------------------ |
+| `enabled` | `boolean` | `true`      | Whether the event listener is active             |
+| `capture` | `boolean` | `false`     | Use event capture phase instead of bubble        |
+| `passive` | `boolean` | `undefined` | Use passive event listener for performance       |
+| `once`    | `boolean` | `false`     | Handler is invoked once and then removed         |
+
+#### Supported Target Types
+
+```typescript
+type EventTargetType<T extends HTMLElement = HTMLElement> =
+  | Window              // window object
+  | Document            // document object
+  | HTMLElement         // any HTML element
+  | React.RefObject<T>  // React ref
+  | null                // no listener
+  | undefined;          // defaults to window
+```
+
+#### Returns
+
+`void`
+
+---
+
+## Examples
+
+### Window Events (Default)
+
+When no element is provided, events are attached to the window:
+
+```tsx
+import { useEventListener } from "@usefy/use-event-listener";
+
+function ResizeHandler() {
+  useEventListener("resize", (e) => {
+    console.log("Window resized:", window.innerWidth, window.innerHeight);
+  });
+
+  return <div>Resize the window</div>;
+}
+```
+
+### Document Events
+
+```tsx
+import { useEventListener } from "@usefy/use-event-listener";
+
+function KeyboardHandler() {
+  useEventListener(
+    "keydown",
+    (e) => {
+      if (e.key === "Escape") {
+        console.log("Escape pressed");
+      }
+    },
+    document
+  );
+
+  return <div>Press Escape</div>;
+}
+```
+
+### HTMLElement Events
+
+```tsx
+import { useEventListener } from "@usefy/use-event-listener";
+
+function ElementClickHandler() {
+  const button = document.getElementById("myButton");
+
+  useEventListener(
+    "click",
+    (e) => {
+      console.log("Button clicked");
+    },
+    button
+  );
+
+  return <button id="myButton">Click me</button>;
+}
+```
+
+### RefObject Events
+
+```tsx
+import { useEventListener } from "@usefy/use-event-listener";
+import { useRef } from "react";
+
+function ScrollableBox() {
+  const boxRef = useRef<HTMLDivElement>(null);
+  const [scrollTop, setScrollTop] = useState(0);
+
+  useEventListener(
+    "scroll",
+    () => {
+      if (boxRef.current) {
+        setScrollTop(boxRef.current.scrollTop);
+      }
+    },
+    boxRef,
+    { passive: true }
+  );
+
+  return (
+    <div ref={boxRef} style={{ height: 200, overflow: "auto" }}>
+      <div style={{ height: 1000 }}>Scroll position: {scrollTop}px</div>
+    </div>
+  );
+}
+```
+
+### Conditional Activation
+
+```tsx
+import { useEventListener } from "@usefy/use-event-listener";
+
+function ConditionalListener() {
+  const [isListening, setIsListening] = useState(true);
+
+  useEventListener(
+    "click",
+    () => {
+      console.log("Clicked!");
+    },
+    document,
+    { enabled: isListening }
+  );
+
+  return (
+    <button onClick={() => setIsListening(!isListening)}>
+      {isListening ? "Disable" : "Enable"} Listener
+    </button>
+  );
+}
+```
+
+### Passive Scroll Listener
+
+Use `passive: true` for better scroll performance:
+
+```tsx
+import { useEventListener } from "@usefy/use-event-listener";
+
+function OptimizedScrollHandler() {
+  useEventListener(
+    "scroll",
+    (e) => {
+      // Handle scroll without blocking
+      console.log("Scroll position:", window.scrollY);
+    },
+    window,
+    { passive: true }
+  );
+
+  return <div>Scroll the page</div>;
+}
+```
+
+### One-time Event Handler
+
+```tsx
+import { useEventListener } from "@usefy/use-event-listener";
+
+function OneTimeHandler() {
+  useEventListener(
+    "click",
+    () => {
+      console.log("This only fires once!");
+    },
+    document,
+    { once: true }
+  );
+
+  return <div>Click anywhere (only works once)</div>;
+}
+```
+
+### Multiple Event Listeners
+
+```tsx
+import { useEventListener } from "@usefy/use-event-listener";
+
+function MultipleListeners() {
+  const [mousePos, setMousePos] = useState({ x: 0, y: 0 });
+  const [isPressed, setIsPressed] = useState(false);
+
+  useEventListener("mousemove", (e) => {
+    setMousePos({ x: e.clientX, y: e.clientY });
+  });
+
+  useEventListener("mousedown", () => {
+    setIsPressed(true);
+  });
+
+  useEventListener("mouseup", () => {
+    setIsPressed(false);
+  });
+
+  return (
+    <div>
+      Position: ({mousePos.x}, {mousePos.y})
+      <br />
+      {isPressed ? "Mouse down" : "Mouse up"}
+    </div>
+  );
+}
+```
+
+### Network Status
+
+```tsx
+import { useEventListener } from "@usefy/use-event-listener";
+
+function NetworkStatus() {
+  const [isOnline, setIsOnline] = useState(navigator.onLine);
+
+  useEventListener("online", () => setIsOnline(true));
+  useEventListener("offline", () => setIsOnline(false));
+
+  return <div>Network: {isOnline ? "Online" : "Offline"}</div>;
+}
+```
+
+---
+
+## TypeScript
+
+This hook provides full type inference for event types:
+
+```tsx
+import { useEventListener } from "@usefy/use-event-listener";
+import type { UseEventListenerOptions, EventTargetType } from "@usefy/use-event-listener";
+
+// MouseEvent is automatically inferred
+useEventListener("click", (e) => {
+  console.log(e.clientX, e.clientY); // e is MouseEvent
+});
+
+// KeyboardEvent is automatically inferred
+useEventListener("keydown", (e) => {
+  console.log(e.key); // e is KeyboardEvent
+}, document);
+
+// FocusEvent is automatically inferred
+useEventListener("focus", (e) => {
+  console.log(e.relatedTarget); // e is FocusEvent
+}, inputRef);
+
+// Options type
+const options: UseEventListenerOptions = {
+  enabled: true,
+  capture: false,
+  passive: true,
+  once: false,
+};
+```
+
+---
+
+## Testing
+
+This package maintains comprehensive test coverage to ensure reliability and stability.
+
+### Test Coverage
+
+| Category   | Coverage |
+| ---------- | -------- |
+| Statements | 96.29%   |
+| Branches   | 91.66%   |
+| Functions  | 100%     |
+| Lines      | 96.29%   |
+
+### Test Categories
+
+<details>
+<summary><strong>Basic Functionality Tests</strong></summary>
+
+- Add event listener to window by default
+- Call handler when event fires
+- Add event listener to document
+- Add event listener to HTMLElement
+- Add event listener to RefObject
+- Handle multiple events
+
+</details>
+
+<details>
+<summary><strong>Enabled Option Tests</strong></summary>
+
+- Not add listener when enabled is false
+- Add listener when enabled changes to true
+- Remove listener when enabled changes to false
+- Default enabled to true
+
+</details>
+
+<details>
+<summary><strong>Capture Option Tests</strong></summary>
+
+- Use capture phase when capture is true
+- Use bubble phase when capture is false
+- Re-register listener when capture changes
+
+</details>
+
+<details>
+<summary><strong>Passive Option Tests</strong></summary>
+
+- Pass passive: true to addEventListener
+- Pass passive: false to addEventListener
+- Use browser default when passive is undefined
+
+</details>
+
+<details>
+<summary><strong>Once Option Tests</strong></summary>
+
+- Pass once: true to addEventListener
+- Default once to false
+
+</details>
+
+<details>
+<summary><strong>Handler Stability Tests</strong></summary>
+
+- Not re-register listener when handler changes
+- Call updated handler after change
+
+</details>
+
+<details>
+<summary><strong>Cleanup Tests</strong></summary>
+
+- Remove event listener on unmount
+- Not call handler after unmount
+- Remove listener with correct capture option
+
+</details>
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run tests with coverage report
+pnpm test --coverage
+```
+
+---
+
+## Related Packages
+
+Explore other hooks in the **@usefy** collection:
+
+| Package                                                                                    | Description                         |
+| ------------------------------------------------------------------------------------------ | ----------------------------------- |
+| [@usefy/use-click-any-where](https://www.npmjs.com/package/@usefy/use-click-any-where)     | Document-wide click detection       |
+| [@usefy/use-on-click-outside](https://www.npmjs.com/package/@usefy/use-on-click-outside)   | Outside click detection             |
+| [@usefy/use-toggle](https://www.npmjs.com/package/@usefy/use-toggle)                       | Boolean state management            |
+| [@usefy/use-counter](https://www.npmjs.com/package/@usefy/use-counter)                     | Counter state management            |
+| [@usefy/use-debounce](https://www.npmjs.com/package/@usefy/use-debounce)                   | Value debouncing                    |
+| [@usefy/use-throttle](https://www.npmjs.com/package/@usefy/use-throttle)                   | Value throttling                    |
+| [@usefy/use-local-storage](https://www.npmjs.com/package/@usefy/use-local-storage)         | localStorage state synchronization  |
+| [@usefy/use-session-storage](https://www.npmjs.com/package/@usefy/use-session-storage)     | sessionStorage state synchronization|
+| [@usefy/use-copy-to-clipboard](https://www.npmjs.com/package/@usefy/use-copy-to-clipboard) | Clipboard operations                |
+
+---
+
+## License
+
+MIT © [mirunamu](https://github.com/geon0529)
+
+This package is part of the [usefy](https://github.com/geon0529/usefy) monorepo.
+
+---
+
+<p align="center">
+  <sub>Built with care by the usefy team</sub>
+</p>

package/dist/index.d.mts

@@ -0,0 +1,99 @@
+/**
+ * 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 | React.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: React.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 };

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 | React.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: React.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 };

package/dist/index.js

@@ -0,0 +1,81 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useEventListener: () => useEventListener
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useEventListener.ts
+var import_react = require("react");
+function isRefObject(target) {
+  return target !== null && target !== void 0 && typeof target === "object" && "current" in target;
+}
+function getTargetElement(target) {
+  if (target === void 0) {
+    return typeof window !== "undefined" ? window : null;
+  }
+  if (target === null) {
+    return null;
+  }
+  if (isRefObject(target)) {
+    return target.current;
+  }
+  return target;
+}
+function useEventListener(eventName, handler, element, options = {}) {
+  const { enabled = true, capture = false, passive, once = false } = options;
+  const handlerRef = (0, import_react.useRef)(handler);
+  handlerRef.current = handler;
+  (0, import_react.useEffect)(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+    if (!enabled) {
+      return;
+    }
+    const targetElement = getTargetElement(element);
+    if (!targetElement) {
+      return;
+    }
+    const internalHandler = (event) => {
+      handlerRef.current(event);
+    };
+    const eventOptions = {
+      capture,
+      once
+    };
+    if (passive !== void 0) {
+      eventOptions.passive = passive;
+    }
+    targetElement.addEventListener(eventName, internalHandler, eventOptions);
+    return () => {
+      targetElement.removeEventListener(eventName, internalHandler, {
+        capture
+      });
+    };
+  }, [eventName, element, enabled, capture, passive, once]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useEventListener
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useEventListener.ts"],"sourcesContent":["export { useEventListener } from \"./useEventListener\";\nexport type {\n  UseEventListenerOptions,\n  EventTargetType,\n} from \"./useEventListener\";\n","import { useEffect, useRef } from \"react\";\n\n/**\n * Options for useEventListener hook\n */\nexport interface UseEventListenerOptions {\n  /**\n   * Whether the event listener is enabled\n   * @default true\n   */\n  enabled?: boolean;\n\n  /**\n   * Whether to use event capture phase\n   * @default false\n   */\n  capture?: boolean;\n\n  /**\n   * Whether to use passive event listener for performance optimization\n   * Useful for scroll/touch events\n   * @default undefined (browser default)\n   */\n  passive?: boolean;\n\n  /**\n   * Whether the handler should be invoked only once and then removed\n   * @default false\n   */\n  once?: boolean;\n}\n\n/**\n * Supported event target types\n */\nexport type EventTargetType<T extends HTMLElement = HTMLElement> =\n  | Window\n  | Document\n  | HTMLElement\n  | React.RefObject<T | null>\n  | null\n  | undefined;\n\n/**\n * Check if target is a RefObject\n */\nfunction isRefObject<T extends HTMLElement>(\n  target: EventTargetType<T>\n): target is React.RefObject<T | null> {\n  return (\n    target !== null &&\n    target !== undefined &&\n    typeof target === \"object\" &&\n    \"current\" in target\n  );\n}\n\n/**\n * Extract actual DOM element from target\n */\nfunction getTargetElement<T extends HTMLElement>(\n  target: EventTargetType<T>\n): Window | Document | HTMLElement | null {\n  // Default to window if target is undefined (not provided)\n  if (target === undefined) {\n    return typeof window !== \"undefined\" ? window : null;\n  }\n\n  // If null is passed, return null (no listener)\n  if (target === null) {\n    return null;\n  }\n\n  // Extract element from RefObject\n  if (isRefObject(target)) {\n    return target.current;\n  }\n\n  return target;\n}\n\n// Overload 1: Window events (default when element is omitted or Window)\n/**\n * Adds an event listener to the window (default) or specified element.\n *\n * @param eventName - The event type to listen for\n * @param handler - The callback function called when the event fires\n * @param element - The target element (defaults to window)\n * @param options - Configuration options\n *\n * @example\n * ```tsx\n * // Window resize event\n * useEventListener(\"resize\", (e) => {\n *   console.log(\"Window resized:\", window.innerWidth);\n * });\n * ```\n */\nexport function useEventListener<K extends keyof WindowEventMap>(\n  eventName: K,\n  handler: (event: WindowEventMap[K]) => void,\n  element?: Window | null,\n  options?: UseEventListenerOptions\n): void;\n\n// Overload 2: Document events\n/**\n * Adds an event listener to the document.\n *\n * @example\n * ```tsx\n * // Document keydown event\n * useEventListener(\"keydown\", (e) => {\n *   console.log(\"Key pressed:\", e.key);\n * }, document);\n * ```\n */\nexport function useEventListener<K extends keyof DocumentEventMap>(\n  eventName: K,\n  handler: (event: DocumentEventMap[K]) => void,\n  element: Document,\n  options?: UseEventListenerOptions\n): void;\n\n// Overload 3: HTMLElement events\n/**\n * Adds an event listener to an HTMLElement.\n *\n * @example\n * ```tsx\n * // HTMLElement click event\n * const button = document.getElementById(\"myButton\");\n * useEventListener(\"click\", (e) => {\n *   console.log(\"Button clicked\");\n * }, button);\n * ```\n */\nexport function useEventListener<K extends keyof HTMLElementEventMap>(\n  eventName: K,\n  handler: (event: HTMLElementEventMap[K]) => void,\n  element: HTMLElement | null,\n  options?: UseEventListenerOptions\n): void;\n\n// Overload 4: RefObject<HTMLElement>\n/**\n * Adds an event listener to an element referenced by a RefObject.\n *\n * @example\n * ```tsx\n * // RefObject event\n * const ref = useRef<HTMLDivElement>(null);\n * useEventListener(\"scroll\", (e) => {\n *   console.log(\"Element scrolled\");\n * }, ref);\n * ```\n */\nexport function useEventListener<\n  K extends keyof HTMLElementEventMap,\n  T extends HTMLElement\n>(\n  eventName: K,\n  handler: (event: HTMLElementEventMap[K]) => void,\n  element: React.RefObject<T | null>,\n  options?: UseEventListenerOptions\n): void;\n\n// Overload 5: Custom events (fallback for non-standard events)\n/**\n * Adds an event listener for custom events.\n *\n * @example\n * ```tsx\n * // Custom event\n * useEventListener(\"myCustomEvent\", (e) => {\n *   console.log(\"Custom event fired\");\n * }, document);\n * ```\n */\nexport function useEventListener(\n  eventName: string,\n  handler: (event: Event) => void,\n  element?: EventTargetType,\n  options?: UseEventListenerOptions\n): void;\n\n/**\n * A React hook for adding event listeners to DOM elements with automatic cleanup.\n * Supports window, document, HTMLElement, and RefObject targets.\n *\n * Features:\n * - Type-safe event handling with TypeScript inference\n * - Automatic cleanup on unmount\n * - Handler stability (no re-registration on handler change)\n * - SSR compatible\n *\n * @param eventName - The event type to listen for\n * @param handler - The callback function called when the event fires\n * @param element - The target element (defaults to window)\n * @param options - Configuration options\n *\n * @example\n * ```tsx\n * // Window resize event (default target)\n * useEventListener(\"resize\", (e) => {\n *   console.log(\"Window resized:\", window.innerWidth);\n * });\n *\n * // Document keydown event\n * useEventListener(\"keydown\", (e) => {\n *   if (e.key === \"Escape\") closeModal();\n * }, document);\n *\n * // Element click event with ref\n * const buttonRef = useRef<HTMLButtonElement>(null);\n * useEventListener(\"click\", handleClick, buttonRef);\n *\n * // With options\n * useEventListener(\"scroll\", handleScroll, window, {\n *   passive: true,\n *   capture: false,\n * });\n *\n * // Conditional activation\n * useEventListener(\"mousemove\", handleMouseMove, document, {\n *   enabled: isTracking,\n * });\n * ```\n */\nexport function useEventListener(\n  eventName: string,\n  handler: (event: Event) => void,\n  element?: EventTargetType,\n  options: UseEventListenerOptions = {}\n): void {\n  const { enabled = true, capture = false, passive, once = false } = options;\n\n  // Store handler in ref to avoid re-registering event listeners\n  const handlerRef = useRef(handler);\n\n  // Update handler ref on each render to always call the latest handler\n  handlerRef.current = handler;\n\n  useEffect(() => {\n    // SSR check\n    if (typeof window === \"undefined\") {\n      return;\n    }\n\n    // Don't add listener if disabled\n    if (!enabled) {\n      return;\n    }\n\n    // Get the target element\n    const targetElement = getTargetElement(element);\n\n    // Don't add listener if element is null\n    if (!targetElement) {\n      return;\n    }\n\n    // Internal handler that calls the ref (always latest handler)\n    const internalHandler = (event: Event) => {\n      handlerRef.current(event);\n    };\n\n    // Build event listener options\n    const eventOptions: AddEventListenerOptions = {\n      capture,\n      once,\n    };\n\n    // Only set passive if explicitly provided (respect browser defaults)\n    if (passive !== undefined) {\n      eventOptions.passive = passive;\n    }\n\n    // Add event listener\n    targetElement.addEventListener(eventName, internalHandler, eventOptions);\n\n    // Cleanup\n    return () => {\n      targetElement.removeEventListener(eventName, internalHandler, {\n        capture,\n      });\n    };\n  }, [eventName, element, enabled, capture, passive, once]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAAkC;AA8ClC,SAAS,YACP,QACqC;AACrC,SACE,WAAW,QACX,WAAW,UACX,OAAO,WAAW,YAClB,aAAa;AAEjB;AAKA,SAAS,iBACP,QACwC;AAExC,MAAI,WAAW,QAAW;AACxB,WAAO,OAAO,WAAW,cAAc,SAAS;AAAA,EAClD;AAGA,MAAI,WAAW,MAAM;AACnB,WAAO;AAAA,EACT;AAGA,MAAI,YAAY,MAAM,GAAG;AACvB,WAAO,OAAO;AAAA,EAChB;AAEA,SAAO;AACT;AAsJO,SAAS,iBACd,WACA,SACA,SACA,UAAmC,CAAC,GAC9B;AACN,QAAM,EAAE,UAAU,MAAM,UAAU,OAAO,SAAS,OAAO,MAAM,IAAI;AAGnE,QAAM,iBAAa,qBAAO,OAAO;AAGjC,aAAW,UAAU;AAErB,8BAAU,MAAM;AAEd,QAAI,OAAO,WAAW,aAAa;AACjC;AAAA,IACF;AAGA,QAAI,CAAC,SAAS;AACZ;AAAA,IACF;AAGA,UAAM,gBAAgB,iBAAiB,OAAO;AAG9C,QAAI,CAAC,eAAe;AAClB;AAAA,IACF;AAGA,UAAM,kBAAkB,CAAC,UAAiB;AACxC,iBAAW,QAAQ,KAAK;AAAA,IAC1B;AAGA,UAAM,eAAwC;AAAA,MAC5C;AAAA,MACA;AAAA,IACF;AAGA,QAAI,YAAY,QAAW;AACzB,mBAAa,UAAU;AAAA,IACzB;AAGA,kBAAc,iBAAiB,WAAW,iBAAiB,YAAY;AAGvE,WAAO,MAAM;AACX,oBAAc,oBAAoB,WAAW,iBAAiB;AAAA,QAC5D;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF,GAAG,CAAC,WAAW,SAAS,SAAS,SAAS,SAAS,IAAI,CAAC;AAC1D;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,54 @@
+// src/useEventListener.ts
+import { useEffect, useRef } from "react";
+function isRefObject(target) {
+  return target !== null && target !== void 0 && typeof target === "object" && "current" in target;
+}
+function getTargetElement(target) {
+  if (target === void 0) {
+    return typeof window !== "undefined" ? window : null;
+  }
+  if (target === null) {
+    return null;
+  }
+  if (isRefObject(target)) {
+    return target.current;
+  }
+  return target;
+}
+function useEventListener(eventName, handler, element, options = {}) {
+  const { enabled = true, capture = false, passive, once = false } = options;
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+    if (!enabled) {
+      return;
+    }
+    const targetElement = getTargetElement(element);
+    if (!targetElement) {
+      return;
+    }
+    const internalHandler = (event) => {
+      handlerRef.current(event);
+    };
+    const eventOptions = {
+      capture,
+      once
+    };
+    if (passive !== void 0) {
+      eventOptions.passive = passive;
+    }
+    targetElement.addEventListener(eventName, internalHandler, eventOptions);
+    return () => {
+      targetElement.removeEventListener(eventName, internalHandler, {
+        capture
+      });
+    };
+  }, [eventName, element, enabled, capture, passive, once]);
+}
+export {
+  useEventListener
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useEventListener.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\n/**\n * Options for useEventListener hook\n */\nexport interface UseEventListenerOptions {\n  /**\n   * Whether the event listener is enabled\n   * @default true\n   */\n  enabled?: boolean;\n\n  /**\n   * Whether to use event capture phase\n   * @default false\n   */\n  capture?: boolean;\n\n  /**\n   * Whether to use passive event listener for performance optimization\n   * Useful for scroll/touch events\n   * @default undefined (browser default)\n   */\n  passive?: boolean;\n\n  /**\n   * Whether the handler should be invoked only once and then removed\n   * @default false\n   */\n  once?: boolean;\n}\n\n/**\n * Supported event target types\n */\nexport type EventTargetType<T extends HTMLElement = HTMLElement> =\n  | Window\n  | Document\n  | HTMLElement\n  | React.RefObject<T | null>\n  | null\n  | undefined;\n\n/**\n * Check if target is a RefObject\n */\nfunction isRefObject<T extends HTMLElement>(\n  target: EventTargetType<T>\n): target is React.RefObject<T | null> {\n  return (\n    target !== null &&\n    target !== undefined &&\n    typeof target === \"object\" &&\n    \"current\" in target\n  );\n}\n\n/**\n * Extract actual DOM element from target\n */\nfunction getTargetElement<T extends HTMLElement>(\n  target: EventTargetType<T>\n): Window | Document | HTMLElement | null {\n  // Default to window if target is undefined (not provided)\n  if (target === undefined) {\n    return typeof window !== \"undefined\" ? window : null;\n  }\n\n  // If null is passed, return null (no listener)\n  if (target === null) {\n    return null;\n  }\n\n  // Extract element from RefObject\n  if (isRefObject(target)) {\n    return target.current;\n  }\n\n  return target;\n}\n\n// Overload 1: Window events (default when element is omitted or Window)\n/**\n * Adds an event listener to the window (default) or specified element.\n *\n * @param eventName - The event type to listen for\n * @param handler - The callback function called when the event fires\n * @param element - The target element (defaults to window)\n * @param options - Configuration options\n *\n * @example\n * ```tsx\n * // Window resize event\n * useEventListener(\"resize\", (e) => {\n *   console.log(\"Window resized:\", window.innerWidth);\n * });\n * ```\n */\nexport function useEventListener<K extends keyof WindowEventMap>(\n  eventName: K,\n  handler: (event: WindowEventMap[K]) => void,\n  element?: Window | null,\n  options?: UseEventListenerOptions\n): void;\n\n// Overload 2: Document events\n/**\n * Adds an event listener to the document.\n *\n * @example\n * ```tsx\n * // Document keydown event\n * useEventListener(\"keydown\", (e) => {\n *   console.log(\"Key pressed:\", e.key);\n * }, document);\n * ```\n */\nexport function useEventListener<K extends keyof DocumentEventMap>(\n  eventName: K,\n  handler: (event: DocumentEventMap[K]) => void,\n  element: Document,\n  options?: UseEventListenerOptions\n): void;\n\n// Overload 3: HTMLElement events\n/**\n * Adds an event listener to an HTMLElement.\n *\n * @example\n * ```tsx\n * // HTMLElement click event\n * const button = document.getElementById(\"myButton\");\n * useEventListener(\"click\", (e) => {\n *   console.log(\"Button clicked\");\n * }, button);\n * ```\n */\nexport function useEventListener<K extends keyof HTMLElementEventMap>(\n  eventName: K,\n  handler: (event: HTMLElementEventMap[K]) => void,\n  element: HTMLElement | null,\n  options?: UseEventListenerOptions\n): void;\n\n// Overload 4: RefObject<HTMLElement>\n/**\n * Adds an event listener to an element referenced by a RefObject.\n *\n * @example\n * ```tsx\n * // RefObject event\n * const ref = useRef<HTMLDivElement>(null);\n * useEventListener(\"scroll\", (e) => {\n *   console.log(\"Element scrolled\");\n * }, ref);\n * ```\n */\nexport function useEventListener<\n  K extends keyof HTMLElementEventMap,\n  T extends HTMLElement\n>(\n  eventName: K,\n  handler: (event: HTMLElementEventMap[K]) => void,\n  element: React.RefObject<T | null>,\n  options?: UseEventListenerOptions\n): void;\n\n// Overload 5: Custom events (fallback for non-standard events)\n/**\n * Adds an event listener for custom events.\n *\n * @example\n * ```tsx\n * // Custom event\n * useEventListener(\"myCustomEvent\", (e) => {\n *   console.log(\"Custom event fired\");\n * }, document);\n * ```\n */\nexport function useEventListener(\n  eventName: string,\n  handler: (event: Event) => void,\n  element?: EventTargetType,\n  options?: UseEventListenerOptions\n): void;\n\n/**\n * A React hook for adding event listeners to DOM elements with automatic cleanup.\n * Supports window, document, HTMLElement, and RefObject targets.\n *\n * Features:\n * - Type-safe event handling with TypeScript inference\n * - Automatic cleanup on unmount\n * - Handler stability (no re-registration on handler change)\n * - SSR compatible\n *\n * @param eventName - The event type to listen for\n * @param handler - The callback function called when the event fires\n * @param element - The target element (defaults to window)\n * @param options - Configuration options\n *\n * @example\n * ```tsx\n * // Window resize event (default target)\n * useEventListener(\"resize\", (e) => {\n *   console.log(\"Window resized:\", window.innerWidth);\n * });\n *\n * // Document keydown event\n * useEventListener(\"keydown\", (e) => {\n *   if (e.key === \"Escape\") closeModal();\n * }, document);\n *\n * // Element click event with ref\n * const buttonRef = useRef<HTMLButtonElement>(null);\n * useEventListener(\"click\", handleClick, buttonRef);\n *\n * // With options\n * useEventListener(\"scroll\", handleScroll, window, {\n *   passive: true,\n *   capture: false,\n * });\n *\n * // Conditional activation\n * useEventListener(\"mousemove\", handleMouseMove, document, {\n *   enabled: isTracking,\n * });\n * ```\n */\nexport function useEventListener(\n  eventName: string,\n  handler: (event: Event) => void,\n  element?: EventTargetType,\n  options: UseEventListenerOptions = {}\n): void {\n  const { enabled = true, capture = false, passive, once = false } = options;\n\n  // Store handler in ref to avoid re-registering event listeners\n  const handlerRef = useRef(handler);\n\n  // Update handler ref on each render to always call the latest handler\n  handlerRef.current = handler;\n\n  useEffect(() => {\n    // SSR check\n    if (typeof window === \"undefined\") {\n      return;\n    }\n\n    // Don't add listener if disabled\n    if (!enabled) {\n      return;\n    }\n\n    // Get the target element\n    const targetElement = getTargetElement(element);\n\n    // Don't add listener if element is null\n    if (!targetElement) {\n      return;\n    }\n\n    // Internal handler that calls the ref (always latest handler)\n    const internalHandler = (event: Event) => {\n      handlerRef.current(event);\n    };\n\n    // Build event listener options\n    const eventOptions: AddEventListenerOptions = {\n      capture,\n      once,\n    };\n\n    // Only set passive if explicitly provided (respect browser defaults)\n    if (passive !== undefined) {\n      eventOptions.passive = passive;\n    }\n\n    // Add event listener\n    targetElement.addEventListener(eventName, internalHandler, eventOptions);\n\n    // Cleanup\n    return () => {\n      targetElement.removeEventListener(eventName, internalHandler, {\n        capture,\n      });\n    };\n  }, [eventName, element, enabled, capture, passive, once]);\n}\n"],"mappings":";AAAA,SAAS,WAAW,cAAc;AA8ClC,SAAS,YACP,QACqC;AACrC,SACE,WAAW,QACX,WAAW,UACX,OAAO,WAAW,YAClB,aAAa;AAEjB;AAKA,SAAS,iBACP,QACwC;AAExC,MAAI,WAAW,QAAW;AACxB,WAAO,OAAO,WAAW,cAAc,SAAS;AAAA,EAClD;AAGA,MAAI,WAAW,MAAM;AACnB,WAAO;AAAA,EACT;AAGA,MAAI,YAAY,MAAM,GAAG;AACvB,WAAO,OAAO;AAAA,EAChB;AAEA,SAAO;AACT;AAsJO,SAAS,iBACd,WACA,SACA,SACA,UAAmC,CAAC,GAC9B;AACN,QAAM,EAAE,UAAU,MAAM,UAAU,OAAO,SAAS,OAAO,MAAM,IAAI;AAGnE,QAAM,aAAa,OAAO,OAAO;AAGjC,aAAW,UAAU;AAErB,YAAU,MAAM;AAEd,QAAI,OAAO,WAAW,aAAa;AACjC;AAAA,IACF;AAGA,QAAI,CAAC,SAAS;AACZ;AAAA,IACF;AAGA,UAAM,gBAAgB,iBAAiB,OAAO;AAG9C,QAAI,CAAC,eAAe;AAClB;AAAA,IACF;AAGA,UAAM,kBAAkB,CAAC,UAAiB;AACxC,iBAAW,QAAQ,KAAK;AAAA,IAC1B;AAGA,UAAM,eAAwC;AAAA,MAC5C;AAAA,MACA;AAAA,IACF;AAGA,QAAI,YAAY,QAAW;AACzB,mBAAa,UAAU;AAAA,IACzB;AAGA,kBAAc,iBAAiB,WAAW,iBAAiB,YAAY;AAGvE,WAAO,MAAM;AACX,oBAAc,oBAAoB,WAAW,iBAAiB;AAAA,QAC5D;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF,GAAG,CAAC,WAAW,SAAS,SAAS,SAAS,SAAS,IAAI,CAAC;AAC1D;","names":[]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@usefy/use-event-listener",
+  "version": "0.0.16",
+  "description": "A React hook for adding event listeners to DOM elements with automatic cleanup",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "jsdom": "^27.3.0",
+    "react": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geon0529/usefy.git",
+    "directory": "packages/use-event-listener"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "event-listener",
+    "addEventListener",
+    "window",
+    "document",
+    "dom",
+    "useEventListener"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}