@usefy/use-on-click-outside 0.0.1

package/README.md

@@ -0,0 +1,536 @@
+<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-on-click-outside</h1>
+
+<p align="center">
+  <strong>A React hook for detecting clicks outside of specified elements</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@usefy/use-on-click-outside">
+    <img src="https://img.shields.io/npm/v/@usefy/use-on-click-outside.svg?style=flat-square&color=007acc" alt="npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/@usefy/use-on-click-outside">
+    <img src="https://img.shields.io/npm/dm/@usefy/use-on-click-outside.svg?style=flat-square&color=007acc" alt="npm downloads" />
+  </a>
+  <a href="https://bundlephobia.com/package/@usefy/use-on-click-outside">
+    <img src="https://img.shields.io/bundlephobia/minzip/@usefy/use-on-click-outside?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-on-click-outside.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-on-click-outside` detects clicks outside of specified element(s) and calls your handler. Perfect for closing modals, dropdowns, popovers, tooltips, and any UI component that should dismiss when clicking elsewhere.
+
+**Part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem** — a collection of production-ready React hooks designed for modern applications.
+
+### Why use-on-click-outside?
+
+- **Zero Dependencies** — Pure React implementation with no external dependencies
+- **TypeScript First** — Full type safety with exported interfaces
+- **Multiple Refs Support** — Pass a single ref or an array of refs (e.g., button + dropdown)
+- **Exclude Elements** — Exclude specific elements from triggering the handler via `excludeRefs` or `shouldExclude`
+- **Mouse + Touch Support** — Handles both `mousedown` and `touchstart` events for mobile compatibility
+- **Capture Phase** — Uses capture phase by default to avoid `stopPropagation` issues
+- **Conditional Activation** — Enable/disable via the `enabled` option
+- **Handler Stability** — No re-registration when handler changes
+- **SSR Compatible** — Works seamlessly with Next.js, Remix, and other SSR frameworks
+- **Well Tested** — 97.61% test coverage with Vitest
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @usefy/use-on-click-outside
+
+# yarn
+yarn add @usefy/use-on-click-outside
+
+# pnpm
+pnpm add @usefy/use-on-click-outside
+```
+
+### Peer Dependencies
+
+This package requires React 18 or 19:
+
+```json
+{
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { useOnClickOutside } from "@usefy/use-on-click-outside";
+import { useRef, useState } from "react";
+
+function Modal({ onClose }: { onClose: () => void }) {
+  const modalRef = useRef<HTMLDivElement>(null);
+
+  useOnClickOutside(modalRef, () => onClose());
+
+  return (
+    <div className="overlay">
+      <div ref={modalRef} className="modal">
+        Click outside to close
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### `useOnClickOutside(ref, handler, options?)`
+
+A hook that detects clicks outside of specified element(s).
+
+#### Parameters
+
+| Parameter | Type                     | Description                                        |
+| --------- | ------------------------ | -------------------------------------------------- |
+| `ref`     | `RefTarget<T>`           | Single ref or array of refs to detect outside clicks for |
+| `handler` | `OnClickOutsideHandler`  | Callback function called when a click outside is detected |
+| `options` | `UseOnClickOutsideOptions` | Configuration options                            |
+
+#### Options
+
+| Option           | Type                        | Default        | Description                                           |
+| ---------------- | --------------------------- | -------------- | ----------------------------------------------------- |
+| `enabled`        | `boolean`                   | `true`         | Whether the event listener is active                  |
+| `capture`        | `boolean`                   | `true`         | Use event capture phase (immune to stopPropagation)   |
+| `eventType`      | `MouseEventType`            | `"mousedown"`  | Mouse event type to listen for                        |
+| `touchEventType` | `TouchEventType`            | `"touchstart"` | Touch event type to listen for                        |
+| `detectTouch`    | `boolean`                   | `true`         | Whether to detect touch events (mobile support)       |
+| `excludeRefs`    | `RefObject<HTMLElement>[]`  | `[]`           | Refs to exclude from outside click detection          |
+| `shouldExclude`  | `(target: Node) => boolean` | `undefined`    | Custom function to determine if target should be excluded |
+| `eventTarget`    | `Document \| HTMLElement \| Window` | `document` | The event target to attach listeners to          |
+
+#### Types
+
+```typescript
+type ClickOutsideEvent = MouseEvent | TouchEvent;
+type OnClickOutsideHandler = (event: ClickOutsideEvent) => void;
+type MouseEventType = "mousedown" | "mouseup" | "click" | "pointerdown" | "pointerup";
+type TouchEventType = "touchstart" | "touchend";
+type RefTarget<T extends HTMLElement> =
+  | React.RefObject<T | null>
+  | Array<React.RefObject<HTMLElement | null>>;
+```
+
+#### Returns
+
+`void`
+
+---
+
+## Examples
+
+### Basic Modal
+
+```tsx
+import { useOnClickOutside } from "@usefy/use-on-click-outside";
+import { useRef, useState } from "react";
+
+function Modal({ isOpen, onClose, children }: ModalProps) {
+  const modalRef = useRef<HTMLDivElement>(null);
+
+  useOnClickOutside(modalRef, onClose, { enabled: isOpen });
+
+  if (!isOpen) return null;
+
+  return (
+    <div className="overlay">
+      <div ref={modalRef} className="modal">
+        {children}
+      </div>
+    </div>
+  );
+}
+```
+
+### Dropdown with Multiple Refs
+
+When you have a button that toggles a dropdown, you want clicks on both the button and dropdown to be considered "inside":
+
+```tsx
+import { useOnClickOutside } from "@usefy/use-on-click-outside";
+import { useRef, useState } from "react";
+
+function Dropdown() {
+  const [isOpen, setIsOpen] = useState(false);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  // Both button and menu are considered "inside"
+  useOnClickOutside(
+    [buttonRef, menuRef],
+    () => setIsOpen(false),
+    { enabled: isOpen }
+  );
+
+  return (
+    <>
+      <button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
+        Toggle Menu
+      </button>
+      {isOpen && (
+        <div ref={menuRef} className="dropdown-menu">
+          <button>Option 1</button>
+          <button>Option 2</button>
+          <button>Option 3</button>
+        </div>
+      )}
+    </>
+  );
+}
+```
+
+### Exclude Specific Elements
+
+Use `excludeRefs` to prevent certain elements from triggering the outside click handler:
+
+```tsx
+import { useOnClickOutside } from "@usefy/use-on-click-outside";
+import { useRef, useState } from "react";
+
+function ModalWithToast() {
+  const [isOpen, setIsOpen] = useState(false);
+  const modalRef = useRef<HTMLDivElement>(null);
+  const toastRef = useRef<HTMLDivElement>(null);
+
+  useOnClickOutside(modalRef, () => setIsOpen(false), {
+    enabled: isOpen,
+    excludeRefs: [toastRef], // Clicks on toast won't close modal
+  });
+
+  return (
+    <>
+      {isOpen && (
+        <div className="overlay">
+          <div ref={modalRef} className="modal">
+            Modal Content
+          </div>
+        </div>
+      )}
+      <div ref={toastRef} className="toast">
+        This toast won't close the modal when clicked
+      </div>
+    </>
+  );
+}
+```
+
+### Custom Exclude Logic with shouldExclude
+
+Use `shouldExclude` for dynamic exclusion based on element properties:
+
+```tsx
+import { useOnClickOutside } from "@usefy/use-on-click-outside";
+import { useRef, useState } from "react";
+
+function MenuWithIgnoredElements() {
+  const [isOpen, setIsOpen] = useState(false);
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  useOnClickOutside(menuRef, () => setIsOpen(false), {
+    enabled: isOpen,
+    shouldExclude: (target) => {
+      // Ignore clicks on elements with specific class
+      return (target as Element).closest?.(".ignore-outside-click") !== null;
+    },
+  });
+
+  return (
+    <>
+      {isOpen && (
+        <div ref={menuRef} className="menu">
+          Menu Content
+        </div>
+      )}
+      <button className="ignore-outside-click">
+        This button won't close the menu
+      </button>
+    </>
+  );
+}
+```
+
+### Popover with Touch Support
+
+Touch events are enabled by default for mobile compatibility:
+
+```tsx
+import { useOnClickOutside } from "@usefy/use-on-click-outside";
+import { useRef, useState } from "react";
+
+function Popover({ trigger, content }: PopoverProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const popoverRef = useRef<HTMLDivElement>(null);
+
+  // Handles both mouse and touch events
+  useOnClickOutside(popoverRef, () => setIsOpen(false), {
+    enabled: isOpen,
+    detectTouch: true, // default
+  });
+
+  return (
+    <div ref={popoverRef}>
+      <button onClick={() => setIsOpen(!isOpen)}>{trigger}</button>
+      {isOpen && <div className="popover-content">{content}</div>}
+    </div>
+  );
+}
+```
+
+### Context Menu
+
+```tsx
+import { useOnClickOutside } from "@usefy/use-on-click-outside";
+import { useRef, useState } from "react";
+
+function ContextMenu() {
+  const [menu, setMenu] = useState<{ x: number; y: number } | null>(null);
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  useOnClickOutside(menuRef, () => setMenu(null), {
+    enabled: menu !== null,
+  });
+
+  const handleContextMenu = (e: React.MouseEvent) => {
+    e.preventDefault();
+    setMenu({ x: e.clientX, y: e.clientY });
+  };
+
+  return (
+    <div onContextMenu={handleContextMenu} className="context-area">
+      Right-click anywhere
+      {menu && (
+        <div
+          ref={menuRef}
+          className="context-menu"
+          style={{ position: "fixed", left: menu.x, top: menu.y }}
+        >
+          <button>Cut</button>
+          <button>Copy</button>
+          <button>Paste</button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Different Event Types
+
+You can customize which mouse/touch events trigger the handler:
+
+```tsx
+import { useOnClickOutside } from "@usefy/use-on-click-outside";
+
+// Use 'click' instead of 'mousedown' (fires after full click completes)
+useOnClickOutside(ref, handler, {
+  eventType: "click",
+});
+
+// Use 'touchend' instead of 'touchstart'
+useOnClickOutside(ref, handler, {
+  touchEventType: "touchend",
+});
+
+// Disable touch detection entirely
+useOnClickOutside(ref, handler, {
+  detectTouch: false,
+});
+```
+
+---
+
+## TypeScript
+
+This hook is written in TypeScript with exported types.
+
+```tsx
+import {
+  useOnClickOutside,
+  type UseOnClickOutsideOptions,
+  type OnClickOutsideHandler,
+  type ClickOutsideEvent,
+  type RefTarget,
+  type MouseEventType,
+  type TouchEventType,
+} from "@usefy/use-on-click-outside";
+
+// Handler type
+const handleOutsideClick: OnClickOutsideHandler = (event) => {
+  console.log("Clicked outside at:", event.clientX, event.clientY);
+};
+
+// Options type
+const options: UseOnClickOutsideOptions = {
+  enabled: true,
+  capture: true,
+  eventType: "mousedown",
+  detectTouch: true,
+};
+
+useOnClickOutside(ref, handleOutsideClick, options);
+```
+
+---
+
+## Testing
+
+This package maintains comprehensive test coverage to ensure reliability and stability.
+
+### Test Coverage
+
+| Category   | Coverage           |
+| ---------- | ------------------ |
+| Statements | 97.61% (41/42)     |
+| Branches   | 93.93% (31/33)     |
+| Functions  | 100% (7/7)         |
+| Lines      | 97.61% (41/42)     |
+
+### Test Categories
+
+<details>
+<summary><strong>Basic Functionality Tests</strong></summary>
+
+- Call handler when clicked outside the element
+- Not call handler when clicked inside the element
+- Not call handler when target is not connected to DOM
+- Handle events with correct type (MouseEvent/TouchEvent)
+
+</details>
+
+<details>
+<summary><strong>Multiple Refs Tests</strong></summary>
+
+- Support array of refs
+- Not call handler when clicking inside any of the refs
+- Call handler only when clicking outside all refs
+
+</details>
+
+<details>
+<summary><strong>Enabled Option Tests</strong></summary>
+
+- Not call handler when enabled is false
+- Not register event listener when disabled
+- Toggle listener when enabled changes
+- Default enabled to true
+
+</details>
+
+<details>
+<summary><strong>Exclude Refs Tests</strong></summary>
+
+- Not call handler when clicking on excluded element
+- Support multiple exclude refs
+- Handle dynamically added exclude refs
+
+</details>
+
+<details>
+<summary><strong>shouldExclude Function Tests</strong></summary>
+
+- Not call handler when shouldExclude returns true
+- Pass correct target to shouldExclude function
+
+</details>
+
+<details>
+<summary><strong>Touch Events Tests</strong></summary>
+
+- Call handler on touchstart when detectTouch is true
+- Not listen for touch events when detectTouch is false
+
+</details>
+
+<details>
+<summary><strong>Handler Stability Tests</strong></summary>
+
+- Not re-register listener when handler changes
+- Call the latest handler after update
+
+</details>
+
+<details>
+<summary><strong>Cleanup Tests</strong></summary>
+
+- Remove event listeners on unmount
+- Not call handler after unmount
+
+</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-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-debounce-callback](https://www.npmjs.com/package/@usefy/use-debounce-callback) | Debounced callbacks                 |
+| [@usefy/use-throttle](https://www.npmjs.com/package/@usefy/use-throttle)                   | Value throttling                    |
+| [@usefy/use-throttle-callback](https://www.npmjs.com/package/@usefy/use-throttle-callback) | Throttled callbacks                 |
+| [@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,160 @@
+/**
+ * Event types for click outside detection (mouse + touch)
+ */
+type ClickOutsideEvent = MouseEvent | TouchEvent;
+/**
+ * Handler function type for click outside events
+ */
+type OnClickOutsideHandler = (event: ClickOutsideEvent) => void;
+/**
+ * Mouse event type options
+ */
+type MouseEventType = "mousedown" | "mouseup" | "click" | "pointerdown" | "pointerup";
+/**
+ * Touch event type options
+ */
+type TouchEventType = "touchstart" | "touchend";
+/**
+ * Ref target type - supports single ref or array of refs
+ * Array accepts mixed element types (e.g., [buttonRef, divRef])
+ */
+type RefTarget<T extends HTMLElement = HTMLElement> = React.RefObject<T | null> | Array<React.RefObject<HTMLElement | null>>;
+/**
+ * Options for useOnClickOutside hook
+ */
+interface UseOnClickOutsideOptions {
+    /**
+     * Whether the event listener is enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Whether to use event capture phase.
+     * When true, the handler is called before the event reaches the target element,
+     * making it immune to stopPropagation calls.
+     * @default true
+     */
+    capture?: boolean;
+    /**
+     * Mouse event type to listen for
+     * @default 'mousedown'
+     */
+    eventType?: MouseEventType;
+    /**
+     * Touch event type to listen for
+     * @default 'touchstart'
+     */
+    touchEventType?: TouchEventType;
+    /**
+     * Whether to detect touch events (for mobile support)
+     * @default true
+     */
+    detectTouch?: boolean;
+    /**
+     * Array of refs to exclude from outside click detection.
+     * Clicks on these elements will not trigger the handler.
+     */
+    excludeRefs?: Array<React.RefObject<HTMLElement | null>>;
+    /**
+     * Custom function to determine if a target should be excluded.
+     * Return true to ignore clicks on the target element.
+     * @param target - The clicked element
+     * @returns Whether to exclude this element from triggering the handler
+     */
+    shouldExclude?: (target: Node) => boolean;
+    /**
+     * The event target to attach listeners to
+     * @default document
+     */
+    eventTarget?: Document | HTMLElement | Window | null;
+}
+/**
+ * Detects clicks outside of specified element(s) and calls the provided handler.
+ * Useful for closing modals, dropdowns, popovers, and similar UI components.
+ *
+ * @param ref - Single ref or array of refs to detect outside clicks for
+ * @param handler - Callback function called when a click outside is detected
+ * @param options - Configuration options for the event listener
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - close modal on outside click
+ * function Modal({ isOpen, onClose }) {
+ *   const modalRef = useRef<HTMLDivElement>(null);
+ *
+ *   useOnClickOutside(modalRef, () => onClose(), { enabled: isOpen });
+ *
+ *   if (!isOpen) return null;
+ *
+ *   return (
+ *     <div className="overlay">
+ *       <div ref={modalRef} className="modal">
+ *         Modal content
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple refs - button and dropdown menu
+ * function Dropdown() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *   const buttonRef = useRef<HTMLButtonElement>(null);
+ *   const menuRef = useRef<HTMLDivElement>(null);
+ *
+ *   useOnClickOutside(
+ *     [buttonRef, menuRef],
+ *     () => setIsOpen(false),
+ *     { enabled: isOpen }
+ *   );
+ *
+ *   return (
+ *     <>
+ *       <button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
+ *         Toggle
+ *       </button>
+ *       {isOpen && (
+ *         <div ref={menuRef}>Dropdown content</div>
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With exclude refs - ignore specific elements
+ * function ModalWithPortal({ isOpen, onClose }) {
+ *   const modalRef = useRef<HTMLDivElement>(null);
+ *   const toastRef = useRef<HTMLDivElement>(null);
+ *
+ *   useOnClickOutside(modalRef, onClose, {
+ *     enabled: isOpen,
+ *     excludeRefs: [toastRef], // Clicks on toast won't close modal
+ *   });
+ *
+ *   return (
+ *     <>
+ *       {isOpen && <div ref={modalRef}>Modal</div>}
+ *       <div ref={toastRef}>Toast notification</div>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom exclude function
+ * useOnClickOutside(ref, handleClose, {
+ *   shouldExclude: (target) => {
+ *     // Ignore clicks on elements with specific class
+ *     return (target as Element).closest?.('.ignore-outside-click') !== null;
+ *   },
+ * });
+ * ```
+ */
+declare function useOnClickOutside<T extends HTMLElement = HTMLElement>(ref: RefTarget<T>, handler: OnClickOutsideHandler, options?: UseOnClickOutsideOptions): void;
+
+export { type ClickOutsideEvent, type MouseEventType, type OnClickOutsideHandler, type RefTarget, type TouchEventType, type UseOnClickOutsideOptions, useOnClickOutside };

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Event types for click outside detection (mouse + touch)
+ */
+type ClickOutsideEvent = MouseEvent | TouchEvent;
+/**
+ * Handler function type for click outside events
+ */
+type OnClickOutsideHandler = (event: ClickOutsideEvent) => void;
+/**
+ * Mouse event type options
+ */
+type MouseEventType = "mousedown" | "mouseup" | "click" | "pointerdown" | "pointerup";
+/**
+ * Touch event type options
+ */
+type TouchEventType = "touchstart" | "touchend";
+/**
+ * Ref target type - supports single ref or array of refs
+ * Array accepts mixed element types (e.g., [buttonRef, divRef])
+ */
+type RefTarget<T extends HTMLElement = HTMLElement> = React.RefObject<T | null> | Array<React.RefObject<HTMLElement | null>>;
+/**
+ * Options for useOnClickOutside hook
+ */
+interface UseOnClickOutsideOptions {
+    /**
+     * Whether the event listener is enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Whether to use event capture phase.
+     * When true, the handler is called before the event reaches the target element,
+     * making it immune to stopPropagation calls.
+     * @default true
+     */
+    capture?: boolean;
+    /**
+     * Mouse event type to listen for
+     * @default 'mousedown'
+     */
+    eventType?: MouseEventType;
+    /**
+     * Touch event type to listen for
+     * @default 'touchstart'
+     */
+    touchEventType?: TouchEventType;
+    /**
+     * Whether to detect touch events (for mobile support)
+     * @default true
+     */
+    detectTouch?: boolean;
+    /**
+     * Array of refs to exclude from outside click detection.
+     * Clicks on these elements will not trigger the handler.
+     */
+    excludeRefs?: Array<React.RefObject<HTMLElement | null>>;
+    /**
+     * Custom function to determine if a target should be excluded.
+     * Return true to ignore clicks on the target element.
+     * @param target - The clicked element
+     * @returns Whether to exclude this element from triggering the handler
+     */
+    shouldExclude?: (target: Node) => boolean;
+    /**
+     * The event target to attach listeners to
+     * @default document
+     */
+    eventTarget?: Document | HTMLElement | Window | null;
+}
+/**
+ * Detects clicks outside of specified element(s) and calls the provided handler.
+ * Useful for closing modals, dropdowns, popovers, and similar UI components.
+ *
+ * @param ref - Single ref or array of refs to detect outside clicks for
+ * @param handler - Callback function called when a click outside is detected
+ * @param options - Configuration options for the event listener
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - close modal on outside click
+ * function Modal({ isOpen, onClose }) {
+ *   const modalRef = useRef<HTMLDivElement>(null);
+ *
+ *   useOnClickOutside(modalRef, () => onClose(), { enabled: isOpen });
+ *
+ *   if (!isOpen) return null;
+ *
+ *   return (
+ *     <div className="overlay">
+ *       <div ref={modalRef} className="modal">
+ *         Modal content
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple refs - button and dropdown menu
+ * function Dropdown() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *   const buttonRef = useRef<HTMLButtonElement>(null);
+ *   const menuRef = useRef<HTMLDivElement>(null);
+ *
+ *   useOnClickOutside(
+ *     [buttonRef, menuRef],
+ *     () => setIsOpen(false),
+ *     { enabled: isOpen }
+ *   );
+ *
+ *   return (
+ *     <>
+ *       <button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
+ *         Toggle
+ *       </button>
+ *       {isOpen && (
+ *         <div ref={menuRef}>Dropdown content</div>
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With exclude refs - ignore specific elements
+ * function ModalWithPortal({ isOpen, onClose }) {
+ *   const modalRef = useRef<HTMLDivElement>(null);
+ *   const toastRef = useRef<HTMLDivElement>(null);
+ *
+ *   useOnClickOutside(modalRef, onClose, {
+ *     enabled: isOpen,
+ *     excludeRefs: [toastRef], // Clicks on toast won't close modal
+ *   });
+ *
+ *   return (
+ *     <>
+ *       {isOpen && <div ref={modalRef}>Modal</div>}
+ *       <div ref={toastRef}>Toast notification</div>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom exclude function
+ * useOnClickOutside(ref, handleClose, {
+ *   shouldExclude: (target) => {
+ *     // Ignore clicks on elements with specific class
+ *     return (target as Element).closest?.('.ignore-outside-click') !== null;
+ *   },
+ * });
+ * ```
+ */
+declare function useOnClickOutside<T extends HTMLElement = HTMLElement>(ref: RefTarget<T>, handler: OnClickOutsideHandler, options?: UseOnClickOutsideOptions): void;
+
+export { type ClickOutsideEvent, type MouseEventType, type OnClickOutsideHandler, type RefTarget, type TouchEventType, type UseOnClickOutsideOptions, useOnClickOutside };

package/dist/index.js

@@ -0,0 +1,118 @@
+"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, {
+  useOnClickOutside: () => useOnClickOutside
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useOnClickOutside.ts
+var import_react = require("react");
+function normalizeRefs(ref) {
+  return Array.isArray(ref) ? ref : [ref];
+}
+function isClickOutside(event, refs, excludeRefs, shouldExclude) {
+  const target = event.target;
+  if (!target || !target.isConnected) {
+    return false;
+  }
+  if (shouldExclude?.(target)) {
+    return false;
+  }
+  for (const excludeRef of excludeRefs) {
+    if (excludeRef.current?.contains(target)) {
+      return false;
+    }
+  }
+  for (const ref of refs) {
+    if (ref.current?.contains(target)) {
+      return false;
+    }
+  }
+  return true;
+}
+function useOnClickOutside(ref, handler, options = {}) {
+  const {
+    enabled = true,
+    capture = true,
+    eventType = "mousedown",
+    touchEventType = "touchstart",
+    detectTouch = true,
+    excludeRefs = [],
+    shouldExclude,
+    eventTarget
+  } = options;
+  const handlerRef = (0, import_react.useRef)(handler);
+  const shouldExcludeRef = (0, import_react.useRef)(shouldExclude);
+  const excludeRefsRef = (0, import_react.useRef)(excludeRefs);
+  const refRef = (0, import_react.useRef)(ref);
+  handlerRef.current = handler;
+  shouldExcludeRef.current = shouldExclude;
+  excludeRefsRef.current = excludeRefs;
+  refRef.current = ref;
+  (0, import_react.useEffect)(() => {
+    if (typeof document === "undefined") {
+      return;
+    }
+    if (!enabled) {
+      return;
+    }
+    const normalizedRefs = normalizeRefs(refRef.current);
+    const target = eventTarget ?? document;
+    const handleMouseEvent = (event) => {
+      if (isClickOutside(
+        event,
+        normalizedRefs,
+        excludeRefsRef.current,
+        shouldExcludeRef.current
+      )) {
+        handlerRef.current(event);
+      }
+    };
+    const handleTouchEvent = (event) => {
+      if (isClickOutside(
+        event,
+        normalizedRefs,
+        excludeRefsRef.current,
+        shouldExcludeRef.current
+      )) {
+        handlerRef.current(event);
+      }
+    };
+    target.addEventListener(eventType, handleMouseEvent, { capture });
+    if (detectTouch) {
+      target.addEventListener(touchEventType, handleTouchEvent, { capture });
+    }
+    return () => {
+      target.removeEventListener(eventType, handleMouseEvent, { capture });
+      if (detectTouch) {
+        target.removeEventListener(touchEventType, handleTouchEvent, {
+          capture
+        });
+      }
+    };
+  }, [enabled, capture, eventType, touchEventType, detectTouch, eventTarget]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useOnClickOutside
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useOnClickOutside.ts"],"sourcesContent":["export { useOnClickOutside } from \"./useOnClickOutside\";\nexport type {\n  UseOnClickOutsideOptions,\n  OnClickOutsideHandler,\n  ClickOutsideEvent,\n  RefTarget,\n  MouseEventType,\n  TouchEventType,\n} from \"./useOnClickOutside\";\n","import { useEffect, useRef } from \"react\";\n\n/**\n * Event types for click outside detection (mouse + touch)\n */\nexport type ClickOutsideEvent = MouseEvent | TouchEvent;\n\n/**\n * Handler function type for click outside events\n */\nexport type OnClickOutsideHandler = (event: ClickOutsideEvent) => void;\n\n/**\n * Mouse event type options\n */\nexport type MouseEventType =\n  | \"mousedown\"\n  | \"mouseup\"\n  | \"click\"\n  | \"pointerdown\"\n  | \"pointerup\";\n\n/**\n * Touch event type options\n */\nexport type TouchEventType = \"touchstart\" | \"touchend\";\n\n/**\n * Ref target type - supports single ref or array of refs\n * Array accepts mixed element types (e.g., [buttonRef, divRef])\n */\nexport type RefTarget<T extends HTMLElement = HTMLElement> =\n  | React.RefObject<T | null>\n  | Array<React.RefObject<HTMLElement | null>>;\n\n/**\n * Options for useOnClickOutside hook\n */\nexport interface UseOnClickOutsideOptions {\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   * When true, the handler is called before the event reaches the target element,\n   * making it immune to stopPropagation calls.\n   * @default true\n   */\n  capture?: boolean;\n\n  /**\n   * Mouse event type to listen for\n   * @default 'mousedown'\n   */\n  eventType?: MouseEventType;\n\n  /**\n   * Touch event type to listen for\n   * @default 'touchstart'\n   */\n  touchEventType?: TouchEventType;\n\n  /**\n   * Whether to detect touch events (for mobile support)\n   * @default true\n   */\n  detectTouch?: boolean;\n\n  /**\n   * Array of refs to exclude from outside click detection.\n   * Clicks on these elements will not trigger the handler.\n   */\n  excludeRefs?: Array<React.RefObject<HTMLElement | null>>;\n\n  /**\n   * Custom function to determine if a target should be excluded.\n   * Return true to ignore clicks on the target element.\n   * @param target - The clicked element\n   * @returns Whether to exclude this element from triggering the handler\n   */\n  shouldExclude?: (target: Node) => boolean;\n\n  /**\n   * The event target to attach listeners to\n   * @default document\n   */\n  eventTarget?: Document | HTMLElement | Window | null;\n}\n\n/**\n * Normalizes ref input to always return an array of refs\n */\nfunction normalizeRefs<T extends HTMLElement>(\n  ref: RefTarget<T>\n): Array<React.RefObject<HTMLElement | null>> {\n  return Array.isArray(ref) ? ref : [ref];\n}\n\n/**\n * Checks if a click event occurred outside of all specified elements\n */\nfunction isClickOutside(\n  event: ClickOutsideEvent,\n  refs: Array<React.RefObject<HTMLElement | null>>,\n  excludeRefs: Array<React.RefObject<HTMLElement | null>>,\n  shouldExclude?: (target: Node) => boolean\n): boolean {\n  const target = event.target as Node;\n\n  // Check if target exists in DOM\n  if (!target || !target.isConnected) {\n    return false;\n  }\n\n  // Check custom exclude function\n  if (shouldExclude?.(target)) {\n    return false;\n  }\n\n  // Check exclude refs\n  for (const excludeRef of excludeRefs) {\n    if (excludeRef.current?.contains(target)) {\n      return false;\n    }\n  }\n\n  // Check target refs - if clicked inside any of them, it's not an outside click\n  for (const ref of refs) {\n    if (ref.current?.contains(target)) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n/**\n * Detects clicks outside of specified element(s) and calls the provided handler.\n * Useful for closing modals, dropdowns, popovers, and similar UI components.\n *\n * @param ref - Single ref or array of refs to detect outside clicks for\n * @param handler - Callback function called when a click outside is detected\n * @param options - Configuration options for the event listener\n *\n * @example\n * ```tsx\n * // Basic usage - close modal on outside click\n * function Modal({ isOpen, onClose }) {\n *   const modalRef = useRef<HTMLDivElement>(null);\n *\n *   useOnClickOutside(modalRef, () => onClose(), { enabled: isOpen });\n *\n *   if (!isOpen) return null;\n *\n *   return (\n *     <div className=\"overlay\">\n *       <div ref={modalRef} className=\"modal\">\n *         Modal content\n *       </div>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Multiple refs - button and dropdown menu\n * function Dropdown() {\n *   const [isOpen, setIsOpen] = useState(false);\n *   const buttonRef = useRef<HTMLButtonElement>(null);\n *   const menuRef = useRef<HTMLDivElement>(null);\n *\n *   useOnClickOutside(\n *     [buttonRef, menuRef],\n *     () => setIsOpen(false),\n *     { enabled: isOpen }\n *   );\n *\n *   return (\n *     <>\n *       <button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>\n *         Toggle\n *       </button>\n *       {isOpen && (\n *         <div ref={menuRef}>Dropdown content</div>\n *       )}\n *     </>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With exclude refs - ignore specific elements\n * function ModalWithPortal({ isOpen, onClose }) {\n *   const modalRef = useRef<HTMLDivElement>(null);\n *   const toastRef = useRef<HTMLDivElement>(null);\n *\n *   useOnClickOutside(modalRef, onClose, {\n *     enabled: isOpen,\n *     excludeRefs: [toastRef], // Clicks on toast won't close modal\n *   });\n *\n *   return (\n *     <>\n *       {isOpen && <div ref={modalRef}>Modal</div>}\n *       <div ref={toastRef}>Toast notification</div>\n *     </>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With custom exclude function\n * useOnClickOutside(ref, handleClose, {\n *   shouldExclude: (target) => {\n *     // Ignore clicks on elements with specific class\n *     return (target as Element).closest?.('.ignore-outside-click') !== null;\n *   },\n * });\n * ```\n */\nexport function useOnClickOutside<T extends HTMLElement = HTMLElement>(\n  ref: RefTarget<T>,\n  handler: OnClickOutsideHandler,\n  options: UseOnClickOutsideOptions = {}\n): void {\n  const {\n    enabled = true,\n    capture = true,\n    eventType = \"mousedown\",\n    touchEventType = \"touchstart\",\n    detectTouch = true,\n    excludeRefs = [],\n    shouldExclude,\n    eventTarget,\n  } = options;\n\n  // Store handler in ref to avoid re-registering event listeners\n  const handlerRef = useRef<OnClickOutsideHandler>(handler);\n\n  // Store shouldExclude in ref to avoid re-registering event listeners\n  const shouldExcludeRef = useRef(shouldExclude);\n\n  // Store excludeRefs in ref to avoid re-registering event listeners\n  const excludeRefsRef = useRef(excludeRefs);\n\n  // Store ref in a ref to avoid re-registering when array is passed inline\n  const refRef = useRef(ref);\n\n  // Update refs when values change\n  handlerRef.current = handler;\n  shouldExcludeRef.current = shouldExclude;\n  excludeRefsRef.current = excludeRefs;\n  refRef.current = ref;\n\n  useEffect(() => {\n    // SSR check\n    if (typeof document === \"undefined\") {\n      return;\n    }\n\n    // Don't add listener if disabled\n    if (!enabled) {\n      return;\n    }\n\n    // Normalize refs to array (use refRef.current to get latest value)\n    const normalizedRefs = normalizeRefs(refRef.current);\n\n    // Get the event target (default to document)\n    const target = eventTarget ?? document;\n\n    // Internal handler for mouse events\n    const handleMouseEvent = (event: Event) => {\n      if (\n        isClickOutside(\n          event as MouseEvent,\n          normalizedRefs,\n          excludeRefsRef.current,\n          shouldExcludeRef.current\n        )\n      ) {\n        handlerRef.current(event as MouseEvent);\n      }\n    };\n\n    // Internal handler for touch events\n    const handleTouchEvent = (event: Event) => {\n      if (\n        isClickOutside(\n          event as TouchEvent,\n          normalizedRefs,\n          excludeRefsRef.current,\n          shouldExcludeRef.current\n        )\n      ) {\n        handlerRef.current(event as TouchEvent);\n      }\n    };\n\n    // Add event listeners\n    target.addEventListener(eventType, handleMouseEvent, { capture });\n\n    if (detectTouch) {\n      target.addEventListener(touchEventType, handleTouchEvent, { capture });\n    }\n\n    // Cleanup\n    return () => {\n      target.removeEventListener(eventType, handleMouseEvent, { capture });\n\n      if (detectTouch) {\n        target.removeEventListener(touchEventType, handleTouchEvent, {\n          capture,\n        });\n      }\n    };\n  }, [enabled, capture, eventType, touchEventType, detectTouch, eventTarget]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAAkC;AA+FlC,SAAS,cACP,KAC4C;AAC5C,SAAO,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,GAAG;AACxC;AAKA,SAAS,eACP,OACA,MACA,aACA,eACS;AACT,QAAM,SAAS,MAAM;AAGrB,MAAI,CAAC,UAAU,CAAC,OAAO,aAAa;AAClC,WAAO;AAAA,EACT;AAGA,MAAI,gBAAgB,MAAM,GAAG;AAC3B,WAAO;AAAA,EACT;AAGA,aAAW,cAAc,aAAa;AACpC,QAAI,WAAW,SAAS,SAAS,MAAM,GAAG;AACxC,aAAO;AAAA,IACT;AAAA,EACF;AAGA,aAAW,OAAO,MAAM;AACtB,QAAI,IAAI,SAAS,SAAS,MAAM,GAAG;AACjC,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;AAyFO,SAAS,kBACd,KACA,SACA,UAAoC,CAAC,GAC/B;AACN,QAAM;AAAA,IACJ,UAAU;AAAA,IACV,UAAU;AAAA,IACV,YAAY;AAAA,IACZ,iBAAiB;AAAA,IACjB,cAAc;AAAA,IACd,cAAc,CAAC;AAAA,IACf;AAAA,IACA;AAAA,EACF,IAAI;AAGJ,QAAM,iBAAa,qBAA8B,OAAO;AAGxD,QAAM,uBAAmB,qBAAO,aAAa;AAG7C,QAAM,qBAAiB,qBAAO,WAAW;AAGzC,QAAM,aAAS,qBAAO,GAAG;AAGzB,aAAW,UAAU;AACrB,mBAAiB,UAAU;AAC3B,iBAAe,UAAU;AACzB,SAAO,UAAU;AAEjB,8BAAU,MAAM;AAEd,QAAI,OAAO,aAAa,aAAa;AACnC;AAAA,IACF;AAGA,QAAI,CAAC,SAAS;AACZ;AAAA,IACF;AAGA,UAAM,iBAAiB,cAAc,OAAO,OAAO;AAGnD,UAAM,SAAS,eAAe;AAG9B,UAAM,mBAAmB,CAAC,UAAiB;AACzC,UACE;AAAA,QACE;AAAA,QACA;AAAA,QACA,eAAe;AAAA,QACf,iBAAiB;AAAA,MACnB,GACA;AACA,mBAAW,QAAQ,KAAmB;AAAA,MACxC;AAAA,IACF;AAGA,UAAM,mBAAmB,CAAC,UAAiB;AACzC,UACE;AAAA,QACE;AAAA,QACA;AAAA,QACA,eAAe;AAAA,QACf,iBAAiB;AAAA,MACnB,GACA;AACA,mBAAW,QAAQ,KAAmB;AAAA,MACxC;AAAA,IACF;AAGA,WAAO,iBAAiB,WAAW,kBAAkB,EAAE,QAAQ,CAAC;AAEhE,QAAI,aAAa;AACf,aAAO,iBAAiB,gBAAgB,kBAAkB,EAAE,QAAQ,CAAC;AAAA,IACvE;AAGA,WAAO,MAAM;AACX,aAAO,oBAAoB,WAAW,kBAAkB,EAAE,QAAQ,CAAC;AAEnE,UAAI,aAAa;AACf,eAAO,oBAAoB,gBAAgB,kBAAkB;AAAA,UAC3D;AAAA,QACF,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF,GAAG,CAAC,SAAS,SAAS,WAAW,gBAAgB,aAAa,WAAW,CAAC;AAC5E;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,91 @@
+// src/useOnClickOutside.ts
+import { useEffect, useRef } from "react";
+function normalizeRefs(ref) {
+  return Array.isArray(ref) ? ref : [ref];
+}
+function isClickOutside(event, refs, excludeRefs, shouldExclude) {
+  const target = event.target;
+  if (!target || !target.isConnected) {
+    return false;
+  }
+  if (shouldExclude?.(target)) {
+    return false;
+  }
+  for (const excludeRef of excludeRefs) {
+    if (excludeRef.current?.contains(target)) {
+      return false;
+    }
+  }
+  for (const ref of refs) {
+    if (ref.current?.contains(target)) {
+      return false;
+    }
+  }
+  return true;
+}
+function useOnClickOutside(ref, handler, options = {}) {
+  const {
+    enabled = true,
+    capture = true,
+    eventType = "mousedown",
+    touchEventType = "touchstart",
+    detectTouch = true,
+    excludeRefs = [],
+    shouldExclude,
+    eventTarget
+  } = options;
+  const handlerRef = useRef(handler);
+  const shouldExcludeRef = useRef(shouldExclude);
+  const excludeRefsRef = useRef(excludeRefs);
+  const refRef = useRef(ref);
+  handlerRef.current = handler;
+  shouldExcludeRef.current = shouldExclude;
+  excludeRefsRef.current = excludeRefs;
+  refRef.current = ref;
+  useEffect(() => {
+    if (typeof document === "undefined") {
+      return;
+    }
+    if (!enabled) {
+      return;
+    }
+    const normalizedRefs = normalizeRefs(refRef.current);
+    const target = eventTarget ?? document;
+    const handleMouseEvent = (event) => {
+      if (isClickOutside(
+        event,
+        normalizedRefs,
+        excludeRefsRef.current,
+        shouldExcludeRef.current
+      )) {
+        handlerRef.current(event);
+      }
+    };
+    const handleTouchEvent = (event) => {
+      if (isClickOutside(
+        event,
+        normalizedRefs,
+        excludeRefsRef.current,
+        shouldExcludeRef.current
+      )) {
+        handlerRef.current(event);
+      }
+    };
+    target.addEventListener(eventType, handleMouseEvent, { capture });
+    if (detectTouch) {
+      target.addEventListener(touchEventType, handleTouchEvent, { capture });
+    }
+    return () => {
+      target.removeEventListener(eventType, handleMouseEvent, { capture });
+      if (detectTouch) {
+        target.removeEventListener(touchEventType, handleTouchEvent, {
+          capture
+        });
+      }
+    };
+  }, [enabled, capture, eventType, touchEventType, detectTouch, eventTarget]);
+}
+export {
+  useOnClickOutside
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useOnClickOutside.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\n/**\n * Event types for click outside detection (mouse + touch)\n */\nexport type ClickOutsideEvent = MouseEvent | TouchEvent;\n\n/**\n * Handler function type for click outside events\n */\nexport type OnClickOutsideHandler = (event: ClickOutsideEvent) => void;\n\n/**\n * Mouse event type options\n */\nexport type MouseEventType =\n  | \"mousedown\"\n  | \"mouseup\"\n  | \"click\"\n  | \"pointerdown\"\n  | \"pointerup\";\n\n/**\n * Touch event type options\n */\nexport type TouchEventType = \"touchstart\" | \"touchend\";\n\n/**\n * Ref target type - supports single ref or array of refs\n * Array accepts mixed element types (e.g., [buttonRef, divRef])\n */\nexport type RefTarget<T extends HTMLElement = HTMLElement> =\n  | React.RefObject<T | null>\n  | Array<React.RefObject<HTMLElement | null>>;\n\n/**\n * Options for useOnClickOutside hook\n */\nexport interface UseOnClickOutsideOptions {\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   * When true, the handler is called before the event reaches the target element,\n   * making it immune to stopPropagation calls.\n   * @default true\n   */\n  capture?: boolean;\n\n  /**\n   * Mouse event type to listen for\n   * @default 'mousedown'\n   */\n  eventType?: MouseEventType;\n\n  /**\n   * Touch event type to listen for\n   * @default 'touchstart'\n   */\n  touchEventType?: TouchEventType;\n\n  /**\n   * Whether to detect touch events (for mobile support)\n   * @default true\n   */\n  detectTouch?: boolean;\n\n  /**\n   * Array of refs to exclude from outside click detection.\n   * Clicks on these elements will not trigger the handler.\n   */\n  excludeRefs?: Array<React.RefObject<HTMLElement | null>>;\n\n  /**\n   * Custom function to determine if a target should be excluded.\n   * Return true to ignore clicks on the target element.\n   * @param target - The clicked element\n   * @returns Whether to exclude this element from triggering the handler\n   */\n  shouldExclude?: (target: Node) => boolean;\n\n  /**\n   * The event target to attach listeners to\n   * @default document\n   */\n  eventTarget?: Document | HTMLElement | Window | null;\n}\n\n/**\n * Normalizes ref input to always return an array of refs\n */\nfunction normalizeRefs<T extends HTMLElement>(\n  ref: RefTarget<T>\n): Array<React.RefObject<HTMLElement | null>> {\n  return Array.isArray(ref) ? ref : [ref];\n}\n\n/**\n * Checks if a click event occurred outside of all specified elements\n */\nfunction isClickOutside(\n  event: ClickOutsideEvent,\n  refs: Array<React.RefObject<HTMLElement | null>>,\n  excludeRefs: Array<React.RefObject<HTMLElement | null>>,\n  shouldExclude?: (target: Node) => boolean\n): boolean {\n  const target = event.target as Node;\n\n  // Check if target exists in DOM\n  if (!target || !target.isConnected) {\n    return false;\n  }\n\n  // Check custom exclude function\n  if (shouldExclude?.(target)) {\n    return false;\n  }\n\n  // Check exclude refs\n  for (const excludeRef of excludeRefs) {\n    if (excludeRef.current?.contains(target)) {\n      return false;\n    }\n  }\n\n  // Check target refs - if clicked inside any of them, it's not an outside click\n  for (const ref of refs) {\n    if (ref.current?.contains(target)) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n/**\n * Detects clicks outside of specified element(s) and calls the provided handler.\n * Useful for closing modals, dropdowns, popovers, and similar UI components.\n *\n * @param ref - Single ref or array of refs to detect outside clicks for\n * @param handler - Callback function called when a click outside is detected\n * @param options - Configuration options for the event listener\n *\n * @example\n * ```tsx\n * // Basic usage - close modal on outside click\n * function Modal({ isOpen, onClose }) {\n *   const modalRef = useRef<HTMLDivElement>(null);\n *\n *   useOnClickOutside(modalRef, () => onClose(), { enabled: isOpen });\n *\n *   if (!isOpen) return null;\n *\n *   return (\n *     <div className=\"overlay\">\n *       <div ref={modalRef} className=\"modal\">\n *         Modal content\n *       </div>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Multiple refs - button and dropdown menu\n * function Dropdown() {\n *   const [isOpen, setIsOpen] = useState(false);\n *   const buttonRef = useRef<HTMLButtonElement>(null);\n *   const menuRef = useRef<HTMLDivElement>(null);\n *\n *   useOnClickOutside(\n *     [buttonRef, menuRef],\n *     () => setIsOpen(false),\n *     { enabled: isOpen }\n *   );\n *\n *   return (\n *     <>\n *       <button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>\n *         Toggle\n *       </button>\n *       {isOpen && (\n *         <div ref={menuRef}>Dropdown content</div>\n *       )}\n *     </>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With exclude refs - ignore specific elements\n * function ModalWithPortal({ isOpen, onClose }) {\n *   const modalRef = useRef<HTMLDivElement>(null);\n *   const toastRef = useRef<HTMLDivElement>(null);\n *\n *   useOnClickOutside(modalRef, onClose, {\n *     enabled: isOpen,\n *     excludeRefs: [toastRef], // Clicks on toast won't close modal\n *   });\n *\n *   return (\n *     <>\n *       {isOpen && <div ref={modalRef}>Modal</div>}\n *       <div ref={toastRef}>Toast notification</div>\n *     </>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With custom exclude function\n * useOnClickOutside(ref, handleClose, {\n *   shouldExclude: (target) => {\n *     // Ignore clicks on elements with specific class\n *     return (target as Element).closest?.('.ignore-outside-click') !== null;\n *   },\n * });\n * ```\n */\nexport function useOnClickOutside<T extends HTMLElement = HTMLElement>(\n  ref: RefTarget<T>,\n  handler: OnClickOutsideHandler,\n  options: UseOnClickOutsideOptions = {}\n): void {\n  const {\n    enabled = true,\n    capture = true,\n    eventType = \"mousedown\",\n    touchEventType = \"touchstart\",\n    detectTouch = true,\n    excludeRefs = [],\n    shouldExclude,\n    eventTarget,\n  } = options;\n\n  // Store handler in ref to avoid re-registering event listeners\n  const handlerRef = useRef<OnClickOutsideHandler>(handler);\n\n  // Store shouldExclude in ref to avoid re-registering event listeners\n  const shouldExcludeRef = useRef(shouldExclude);\n\n  // Store excludeRefs in ref to avoid re-registering event listeners\n  const excludeRefsRef = useRef(excludeRefs);\n\n  // Store ref in a ref to avoid re-registering when array is passed inline\n  const refRef = useRef(ref);\n\n  // Update refs when values change\n  handlerRef.current = handler;\n  shouldExcludeRef.current = shouldExclude;\n  excludeRefsRef.current = excludeRefs;\n  refRef.current = ref;\n\n  useEffect(() => {\n    // SSR check\n    if (typeof document === \"undefined\") {\n      return;\n    }\n\n    // Don't add listener if disabled\n    if (!enabled) {\n      return;\n    }\n\n    // Normalize refs to array (use refRef.current to get latest value)\n    const normalizedRefs = normalizeRefs(refRef.current);\n\n    // Get the event target (default to document)\n    const target = eventTarget ?? document;\n\n    // Internal handler for mouse events\n    const handleMouseEvent = (event: Event) => {\n      if (\n        isClickOutside(\n          event as MouseEvent,\n          normalizedRefs,\n          excludeRefsRef.current,\n          shouldExcludeRef.current\n        )\n      ) {\n        handlerRef.current(event as MouseEvent);\n      }\n    };\n\n    // Internal handler for touch events\n    const handleTouchEvent = (event: Event) => {\n      if (\n        isClickOutside(\n          event as TouchEvent,\n          normalizedRefs,\n          excludeRefsRef.current,\n          shouldExcludeRef.current\n        )\n      ) {\n        handlerRef.current(event as TouchEvent);\n      }\n    };\n\n    // Add event listeners\n    target.addEventListener(eventType, handleMouseEvent, { capture });\n\n    if (detectTouch) {\n      target.addEventListener(touchEventType, handleTouchEvent, { capture });\n    }\n\n    // Cleanup\n    return () => {\n      target.removeEventListener(eventType, handleMouseEvent, { capture });\n\n      if (detectTouch) {\n        target.removeEventListener(touchEventType, handleTouchEvent, {\n          capture,\n        });\n      }\n    };\n  }, [enabled, capture, eventType, touchEventType, detectTouch, eventTarget]);\n}\n"],"mappings":";AAAA,SAAS,WAAW,cAAc;AA+FlC,SAAS,cACP,KAC4C;AAC5C,SAAO,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,GAAG;AACxC;AAKA,SAAS,eACP,OACA,MACA,aACA,eACS;AACT,QAAM,SAAS,MAAM;AAGrB,MAAI,CAAC,UAAU,CAAC,OAAO,aAAa;AAClC,WAAO;AAAA,EACT;AAGA,MAAI,gBAAgB,MAAM,GAAG;AAC3B,WAAO;AAAA,EACT;AAGA,aAAW,cAAc,aAAa;AACpC,QAAI,WAAW,SAAS,SAAS,MAAM,GAAG;AACxC,aAAO;AAAA,IACT;AAAA,EACF;AAGA,aAAW,OAAO,MAAM;AACtB,QAAI,IAAI,SAAS,SAAS,MAAM,GAAG;AACjC,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;AAyFO,SAAS,kBACd,KACA,SACA,UAAoC,CAAC,GAC/B;AACN,QAAM;AAAA,IACJ,UAAU;AAAA,IACV,UAAU;AAAA,IACV,YAAY;AAAA,IACZ,iBAAiB;AAAA,IACjB,cAAc;AAAA,IACd,cAAc,CAAC;AAAA,IACf;AAAA,IACA;AAAA,EACF,IAAI;AAGJ,QAAM,aAAa,OAA8B,OAAO;AAGxD,QAAM,mBAAmB,OAAO,aAAa;AAG7C,QAAM,iBAAiB,OAAO,WAAW;AAGzC,QAAM,SAAS,OAAO,GAAG;AAGzB,aAAW,UAAU;AACrB,mBAAiB,UAAU;AAC3B,iBAAe,UAAU;AACzB,SAAO,UAAU;AAEjB,YAAU,MAAM;AAEd,QAAI,OAAO,aAAa,aAAa;AACnC;AAAA,IACF;AAGA,QAAI,CAAC,SAAS;AACZ;AAAA,IACF;AAGA,UAAM,iBAAiB,cAAc,OAAO,OAAO;AAGnD,UAAM,SAAS,eAAe;AAG9B,UAAM,mBAAmB,CAAC,UAAiB;AACzC,UACE;AAAA,QACE;AAAA,QACA;AAAA,QACA,eAAe;AAAA,QACf,iBAAiB;AAAA,MACnB,GACA;AACA,mBAAW,QAAQ,KAAmB;AAAA,MACxC;AAAA,IACF;AAGA,UAAM,mBAAmB,CAAC,UAAiB;AACzC,UACE;AAAA,QACE;AAAA,QACA;AAAA,QACA,eAAe;AAAA,QACf,iBAAiB;AAAA,MACnB,GACA;AACA,mBAAW,QAAQ,KAAmB;AAAA,MACxC;AAAA,IACF;AAGA,WAAO,iBAAiB,WAAW,kBAAkB,EAAE,QAAQ,CAAC;AAEhE,QAAI,aAAa;AACf,aAAO,iBAAiB,gBAAgB,kBAAkB,EAAE,QAAQ,CAAC;AAAA,IACvE;AAGA,WAAO,MAAM;AACX,aAAO,oBAAoB,WAAW,kBAAkB,EAAE,QAAQ,CAAC;AAEnE,UAAI,aAAa;AACf,eAAO,oBAAoB,gBAAgB,kBAAkB;AAAA,UAC3D;AAAA,QACF,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF,GAAG,CAAC,SAAS,SAAS,WAAW,gBAAgB,aAAa,WAAW,CAAC;AAC5E;","names":[]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@usefy/use-on-click-outside",
+  "version": "0.0.1",
+  "description": "A React hook for detecting clicks outside of specified elements",
+  "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-on-click-outside"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "click-outside",
+    "outside-click",
+    "modal",
+    "dropdown",
+    "event-listener",
+    "useOnClickOutside"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}