@jbpark/use-hooks 2.11.0 → 4.0.0

package/README.ko.md

@@ -11,7 +11,7 @@
 
 ## 기능
 
-- 📦 **15개 프로덕션 레디 훅** - 스크롤, 뷰포트, 스토리지 등 다양한 유틸리티
+- 📦 **30개 프로덕션 레디 훅** - 스크롤, 뷰포트, 스토리지, 옵저버, 이벤트, 타이밍 등 다양한 유틸리티
 - 🎯 **TypeScript 지원** - 완전한 타입 지원으로 더 나은 개발 경험
 - ⚡ **트리 셰이킹 지원** - 필요한 것만 임포트하세요
 - 🔒 **SSR 안전** - window/document 전역 변수에 대한 보호
@@ -36,7 +36,7 @@ pnpm add @jbpark/use-hooks
 import {
   useLocalStorage,
   useResponsiveSize,
-  useThrottle,
+  useThrottledValue,
   useWindowScroll,
 } from '@jbpark/use-hooks';
 
@@ -51,7 +51,7 @@ function MyComponent() {
   const { size, breakpoint, ref } = useResponsiveSize();
 
   // 너비 업데이트를 스로틀링
-  const throttledWidth = useThrottle(size.width, 200);
+  const throttledWidth = useThrottledValue(size.width, 200);
 
   return (
     <div ref={ref}>
@@ -67,25 +67,43 @@ function MyComponent() {
 
 ## 사용 가능한 훅
 
-| 훅                        | 설명                                                                    |
-| ------------------------- | ----------------------------------------------------------------------- |
-| `useLocalStorage`         | 에러 핸들링이 포함된 JSON 기반 영속 상태 (SSR 안전)                     |
-| `useWindowScroll`         | 윈도우 스크롤 위치 및 백분율 추적 (iOS visualViewport 대응)             |
-| `useElementScroll`        | ResizeObserver를 사용한 특정 요소의 스크롤 상태 추적                    |
-| `useElementPosition`      | 스크롤/리사이즈 시 요소의 바운딩 렉트 모니터링 (요소 참조 지원)         |
-| `useResponsiveSize`       | Tailwind 유사 브레이크포인트를 포함한 요소 크기 추적 (debounce)         |
-| `useBodyScrollLock`       | 스타일 보존을 포함한 바디 스크롤 잠금/해제 (iOS 특별 처리)              |
-| `useClickOutside`         | 참조한 요소 바깥을 클릭/터치하면 콜백 실행                              |
-| `useScrollToElements`     | 인덱스별로 특정 요소로 스크롤 (오프셋 조절 가능)                        |
-| `useImage`                | 이미지 사전로드 및 로딩/에러 상태 노출                                  |
-| `useRecursiveTimeout`     | 비동기/동기 콜백을 재귀적으로 스케줄링                                  |
-| `useViewport`             | visualViewport 지원, 인앱 모드 옵션, debounce 포함                      |
-| `useDebounce`             | 함수 실행을 지연해 과도한 업데이트를 방지 (autoInvoke 지원)             |
-| `useThrottle`             | 값 업데이트를 일정 간격으로 제한                                        |
-| `useHistoryState`         | 히스토리 개수 제한을 설정할 수 있는 실행 취소/다시 실행 상태 관리       |
-| `useIntersectionObserver` | 콜백 ref로 요소의 뷰포트 교차 여부 추적                                 |
-| `useMultiSelect`          | shift-클릭 범위 선택을 지원하는 체크박스 스타일 다중 선택               |
-| `useControllableState`    | value/defaultValue/onChange prop 조합을 훅 하나로 제어/비제어 상태 관리 |
+| 훅                        | 설명                                                                                        |
+| ------------------------- | ------------------------------------------------------------------------------------------- |
+| `useLocalStorage`         | 에러 핸들링이 포함된 JSON 기반 영속 상태 (SSR 안전)                                         |
+| `useHistoryState`         | 히스토리 개수 제한을 설정할 수 있는 실행 취소/다시 실행 상태 관리                           |
+| `useControllableState`    | value/defaultValue/onChange prop 조합을 훅 하나로 제어/비제어 상태 관리                     |
+| `usePrevious`             | 이전 렌더 시점의 값을 반환                                                                  |
+| `useToggle`               | 토글 함수와 명시적 setter를 제공하는 불리언 상태                                            |
+| `useMultiSelect`          | shift-클릭 범위 선택을 지원하는 체크박스 스타일 다중 선택                                   |
+| `useWindowScroll`         | 윈도우 스크롤 위치 및 백분율 추적 (iOS visualViewport 대응)                                 |
+| `useElementScroll`        | ResizeObserver를 사용한 특정 요소의 스크롤 상태 추적                                        |
+| `useElementPosition`      | 스크롤/리사이즈 시 요소의 바운딩 렉트 모니터링 (요소 참조 지원)                             |
+| `useResponsiveSize`       | Tailwind 유사 브레이크포인트를 포함한 요소 크기 추적 (debounce)                             |
+| `useViewport`             | visualViewport 지원, 인앱 모드 옵션, debounce 포함                                          |
+| `useScrollToElements`     | 키로 요소를 등록하고 키로 스크롤 (오프셋 조절, 컨테이너 지정 가능)                          |
+| `useBodyScrollLock`       | 스타일 보존을 포함한 바디 스크롤 잠금/해제 (iOS 특별 처리)                                  |
+| `useIntersectionObserver` | 뷰포트 교차 추적, `[ref, { entry, isIntersecting }]` 반환, `freezeOnceVisible` 옵션         |
+| `useResizeObserver`       | 콜백 ref로 요소 자체의 너비/높이 추적 (content-box/border-box)                              |
+| `useMutationObserver`     | ref 또는 raw 노드(예: `document.head`)의 DOM 변경 관측                                      |
+| `useEventListener`        | `window`, ref, raw 타겟에 이벤트 리스너 등록/해제                                           |
+| `useClickOutside`         | 참조한 요소(들) 바깥 클릭/터치(또는 opt-in `escape`로 `Escape`) 시 콜백 실행, 다중 ref 지원 |
+| `useKeyPress`             | `mod`/`ctrl`/`meta`/`shift`/`alt` 조합과 `space`/`esc` 별칭으로 키 콜백 실행                |
+| `useFileDrop`             | `accept`/`multiple` 필터링을 갖춘 드래그앤드롭 존, `{ dropRef, isDragging }` 반환           |
+| `useFileToDataUrl`        | `File`/`Blob`을 data URL로 변환                                                             |
+| `useDebouncedCallback`    | deps 변경 시 debounce된 콜백 자동 실행 (`leading`/`autoInvoke` 옵션); 별칭: `useDebounce`   |
+| `useDebouncedValue`       | 변하는 값을 일정 지연으로 debounce                                                          |
+| `useThrottledValue`       | 값 업데이트를 일정 간격으로 제한; 별칭: `useThrottle`                                       |
+| `useThrottledCallback`    | 콜백을 일정 간격으로 제한                                                                   |
+| `useTimeout`              | 지연 후 콜백 1회 실행, `{ reset, clear }` 반환 (`null`이면 일시정지)                        |
+| `useInterval`             | 일정 간격으로 콜백 실행 (`null`이면 일시정지)                                               |
+| `useRecursiveTimeout`     | 비동기/동기 콜백을 재귀적으로 스케줄링                                                      |
+| `useMergedRef`            | 여러 객체/콜백 ref를 하나의 콜백 ref로 병합                                                 |
+| `useImage`                | 이미지 사전로드 및 `loading`/`error`(`Error`)/`loaded`/`attemptCount`/`retry` 노출          |
+
+## v2에서 마이그레이션
+
+v3.0.0은 breaking change가 여럿 포함된 메이저 릴리스입니다. 전후 예제는
+[마이그레이션 가이드](./MIGRATION.ko.md)를 참고하세요.
 
 ## 개발
 

package/README.md

@@ -11,7 +11,7 @@ A collection of reusable React 19 hooks for common UI and interaction patterns.
 
 ## Features
 
-- 📦 **15 Production-Ready Hooks** - Utilities for scrolling, viewport, storage, and more
+- 📦 **30 Production-Ready Hooks** - Utilities for scrolling, viewport, storage, observers, events, timing, and more
 - 🎯 **Full TypeScript Support** - Complete type definitions for better development experience
 - ⚡ **Tree-Shakeable** - Import only what you need
 - 🔒 **SSR-Safe** - Built-in protection for window/document globals
@@ -36,7 +36,7 @@ pnpm add @jbpark/use-hooks
 import {
   useLocalStorage,
   useResponsiveSize,
-  useThrottle,
+  useThrottledValue,
   useWindowScroll,
 } from '@jbpark/use-hooks';
 
@@ -51,7 +51,7 @@ function MyComponent() {
   const { size, breakpoint, ref } = useResponsiveSize();
 
   // Throttled width update
-  const throttledWidth = useThrottle(size.width, 200);
+  const throttledWidth = useThrottledValue(size.width, 200);
 
   return (
     <div ref={ref}>
@@ -67,25 +67,43 @@ function MyComponent() {
 
 ## Available Hooks
 
-| Hook                      | Description                                                                              |
-| ------------------------- | ---------------------------------------------------------------------------------------- |
-| `useLocalStorage`         | JSON-based persistent state with error handling (SSR-safe)                               |
-| `useWindowScroll`         | Track window scroll position and percentage (iOS visualViewport compatible)              |
-| `useElementScroll`        | Monitor scroll state of specific elements using ResizeObserver                           |
-| `useElementPosition`      | Monitor element bounding rect on scroll/resize (element ref support)                     |
-| `useResponsiveSize`       | Track element size with Tailwind-like breakpoints (debounced)                            |
-| `useBodyScrollLock`       | Lock/unlock body scroll with style preservation (iOS-specific handling)                  |
-| `useClickOutside`         | Run a callback when a click/touch happens outside a referenced element                   |
-| `useScrollToElements`     | Scroll to specific elements by index (adjustable offset)                                 |
-| `useImage`                | Preload images and expose loading/error states                                           |
-| `useRecursiveTimeout`     | Recursively schedule async/sync callbacks                                                |
-| `useViewport`             | visualViewport support with in-app mode option and debounce                              |
-| `useDebounce`             | Delay function execution to prevent excessive updates (autoInvoke support)               |
-| `useThrottle`             | Throttle value updates to a fixed interval                                               |
-| `useHistoryState`         | Undo/redo state management with a configurable history limit                             |
-| `useIntersectionObserver` | Track an element's viewport intersection via a callback ref                              |
-| `useMultiSelect`          | Checkbox-style multi-select for a list, with shift-click range selection                 |
-| `useControllableState`    | Back a value/defaultValue/onChange prop pair with one controlled/uncontrolled state hook |
+| Hook                      | Description                                                                                                                           |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `useLocalStorage`         | JSON-based persistent state with error handling (SSR-safe)                                                                            |
+| `useHistoryState`         | Undo/redo state management with a configurable history limit                                                                          |
+| `useControllableState`    | Back a value/defaultValue/onChange prop pair with one controlled/uncontrolled state hook                                              |
+| `usePrevious`             | Return a value as it was on the previous render                                                                                       |
+| `useToggle`               | Boolean state with a toggle and an explicit setter                                                                                    |
+| `useMultiSelect`          | Checkbox-style multi-select for a list, with shift-click range selection                                                              |
+| `useWindowScroll`         | Track window scroll position and percentage (iOS visualViewport compatible)                                                           |
+| `useElementScroll`        | Monitor scroll state of specific elements using ResizeObserver                                                                        |
+| `useElementPosition`      | Monitor element bounding rect on scroll/resize (element ref support)                                                                  |
+| `useResponsiveSize`       | Track element size with Tailwind-like breakpoints (debounced)                                                                         |
+| `useViewport`             | visualViewport support with in-app mode option and debounce                                                                           |
+| `useScrollToElements`     | Register elements by key and scroll to them by key (adjustable offset, optional container)                                            |
+| `useBodyScrollLock`       | Lock/unlock body scroll with style preservation (iOS-specific handling)                                                               |
+| `useIntersectionObserver` | Track viewport intersection; returns `[ref, { entry, isIntersecting }]` with optional `freezeOnceVisible`                             |
+| `useResizeObserver`       | Track an element's own width/height via a callback ref (content-box or border-box)                                                    |
+| `useMutationObserver`     | Observe DOM mutations on a ref or a raw node (e.g. `document.head`)                                                                   |
+| `useEventListener`        | Add/remove an event listener on `window`, a ref, or a raw target                                                                      |
+| `useClickOutside`         | Run a callback when a click/touch (or `Escape`, opt-in via `escape`) happens outside the referenced element(s); accepts multiple refs |
+| `useKeyPress`             | Run a callback on key combos with `mod`/`ctrl`/`meta`/`shift`/`alt` and aliases like `space`/`esc`                                    |
+| `useFileDrop`             | Drag-and-drop file zone with `accept`/`multiple` filtering; returns `{ dropRef, isDragging }`                                         |
+| `useFileToDataUrl`        | Read a `File`/`Blob` into a data URL                                                                                                  |
+| `useDebouncedCallback`    | Auto-invoke a debounced callback when deps change (`leading`/`autoInvoke` options); alias: `useDebounce`                              |
+| `useDebouncedValue`       | Debounce a changing value to a fixed delay                                                                                            |
+| `useThrottledValue`       | Throttle value updates to a fixed interval; alias: `useThrottle`                                                                      |
+| `useThrottledCallback`    | Throttle a callback to a fixed interval                                                                                               |
+| `useTimeout`              | Run a callback once after a delay; returns `{ reset, clear }` (`null` pauses)                                                         |
+| `useInterval`             | Run a callback on an interval (`null` pauses)                                                                                         |
+| `useRecursiveTimeout`     | Recursively schedule async/sync callbacks                                                                                             |
+| `useMergedRef`            | Merge multiple object/callback refs into one callback ref                                                                             |
+| `useImage`                | Preload an image and expose `loading`/`error` (an `Error`)/`loaded`/`attemptCount`/`retry`                                            |
+
+## Migrating from v2
+
+v3.0.0 is a major release with several breaking changes. See the
+[Migration Guide](./MIGRATION.md) for before/after examples.
 
 ## Development
 

package/dist/hooks/index.d.mts

@@ -1,19 +1,30 @@
-import { useDebounce } from "./use-debounce.mjs";
+import { useDebouncedCallback } from "./use-debounced-callback.mjs";
+import { useDebouncedValue } from "./use-debounced-value.mjs";
 import { useBodyScrollLock } from "./use-body-scroll-lock.mjs";
 import { useClickOutside } from "./use-click-outside.mjs";
 import { useControllableState } from "./use-controllable-state.mjs";
 import { useElementPosition } from "./use-element-position.mjs";
 import { useElementScroll } from "./use-element-scroll.mjs";
+import { useEventListener } from "./use-event-listener.mjs";
+import { useFileDrop } from "./use-file-drop.mjs";
 import { useFileToDataUrl } from "./use-file-to-data-url.mjs";
 import { useHistoryState } from "./use-history-state.mjs";
 import { useIntersectionObserver } from "./use-intersection-observer.mjs";
+import { useInterval } from "./use-interval.mjs";
 import { useResponsiveSize } from "./use-responsive-size.mjs";
 import { useImage } from "./use-image.mjs";
+import { useKeyPress } from "./use-key-press.mjs";
 import { useLocalStorage } from "./use-local-storage.mjs";
+import { useMergedRef } from "./use-merged-ref.mjs";
 import { useMultiSelect } from "./use-multi-select.mjs";
+import { useMutationObserver } from "./use-mutation-observer.mjs";
+import { usePrevious } from "./use-previous.mjs";
 import { useRecursiveTimeout } from "./use-recursive-timeout.mjs";
+import { useResizeObserver } from "./use-resize-observer.mjs";
 import { useScrollToElements } from "./use-scroll-to-elements.mjs";
-import { useThrottle } from "./use-throttle.mjs";
-import { useTimeline } from "./use-timeline.mjs";
+import { useThrottledValue } from "./use-throttled-value.mjs";
+import { useThrottledCallback } from "./use-throttled-callback.mjs";
+import { useTimeout } from "./use-timeout.mjs";
+import { useToggle } from "./use-toggle.mjs";
 import { useWindowScroll } from "./use-window-scroll.mjs";
 import { useViewport } from "./use-viewport.mjs";

package/dist/hooks/index.mjs

@@ -1,20 +1,31 @@
-import useDebounce from "./use-debounce.mjs";
+import useDebouncedCallback from "./use-debounced-callback.mjs";
+import useDebouncedValue from "./use-debounced-value.mjs";
 import useBodyScrollLock from "./use-body-scroll-lock.mjs";
 import useClickOutside from "./use-click-outside.mjs";
 import useControllableState from "./use-controllable-state.mjs";
 import useElementPosition from "./use-element-position.mjs";
 import useElementScroll from "./use-element-scroll.mjs";
+import useEventListener from "./use-event-listener.mjs";
+import useFileDrop from "./use-file-drop.mjs";
 import useFileToDataUrl from "./use-file-to-data-url.mjs";
 import useHistoryState from "./use-history-state.mjs";
 import useIntersectionObserver from "./use-intersection-observer.mjs";
+import useInterval from "./use-interval.mjs";
 import useResponsiveSize from "./use-responsive-size.mjs";
 import useImage from "./use-image.mjs";
+import useKeyPress from "./use-key-press.mjs";
 import useLocalStorage from "./use-local-storage.mjs";
+import useMergedRef from "./use-merged-ref.mjs";
 import useMultiSelect from "./use-multi-select.mjs";
+import useMutationObserver from "./use-mutation-observer.mjs";
+import usePrevious from "./use-previous.mjs";
 import useRecursiveTimeout from "./use-recursive-timeout.mjs";
+import useResizeObserver from "./use-resize-observer.mjs";
 import useScrollToElements from "./use-scroll-to-elements.mjs";
-import useThrottle from "./use-throttle.mjs";
-import useTimeline from "./use-timeline.mjs";
+import useThrottledCallback from "./use-throttled-callback.mjs";
+import useThrottledValue from "./use-throttled-value.mjs";
+import useTimeout from "./use-timeout.mjs";
+import useToggle from "./use-toggle.mjs";
 import useWindowScroll from "./use-window-scroll.mjs";
 import useViewport from "./use-viewport.mjs";
 

package/dist/hooks/use-click-outside.d.mts

@@ -1,7 +1,14 @@
-import * as react from "react";
+import { RefObject } from "react";
 
 //#region src/hooks/use-click-outside.d.ts
-declare const useClickOutside: <T extends HTMLElement = HTMLElement>(handler: (event: MouseEvent | TouchEvent) => void, enabled?: boolean) => react.RefObject<T | null>;
+type ClickOutsideRef = RefObject<HTMLElement | null> | null | undefined;
+type ClickOutsideEvent = PointerEvent | MouseEvent | TouchEvent | KeyboardEvent;
+interface Options {
+  enabled?: boolean;
+  events?: ('pointerdown' | 'mousedown' | 'touchstart')[];
+  escape?: boolean;
+}
+declare const useClickOutside: (refs: ClickOutsideRef | ClickOutsideRef[], handler: (event: ClickOutsideEvent) => void, options?: Options) => void;
 //#endregion
 export { useClickOutside };
 //# sourceMappingURL=use-click-outside.d.mts.map

package/dist/hooks/use-click-outside.mjs

@@ -1,27 +1,43 @@
 import { useEffect, useRef } from "react";
 
 //#region src/hooks/use-click-outside.ts
-const useClickOutside = (handler, enabled = true) => {
-	const ref = useRef(null);
+const useClickOutside = (refs, handler, options = {}) => {
+	const { enabled = true, events = ["pointerdown"], escape = false } = options;
 	const handlerRef = useRef(handler);
 	useEffect(() => {
 		handlerRef.current = handler;
 	});
+	const refList = Array.isArray(refs) ? refs : [refs];
+	const refListRef = useRef(refList);
+	useEffect(() => {
+		refListRef.current = refList;
+	});
 	useEffect(() => {
 		if (!enabled || typeof document === "undefined") return;
-		const listener = (event) => {
-			const el = ref.current;
-			if (!el || el.contains(event.target)) return;
+		const isInside = (target) => refListRef.current.some((ref) => ref?.current?.contains(target));
+		const onPointerEvent = (event) => {
+			const target = event.target;
+			if (!target || isInside(target)) return;
 			handlerRef.current(event);
 		};
-		document.addEventListener("mousedown", listener);
-		document.addEventListener("touchstart", listener);
+		const onKeyDown = (event) => {
+			if (event.key === "Escape") handlerRef.current(event);
+		};
+		events.forEach((eventName) => {
+			document.addEventListener(eventName, onPointerEvent);
+		});
+		if (escape) document.addEventListener("keydown", onKeyDown);
 		return () => {
-			document.removeEventListener("mousedown", listener);
-			document.removeEventListener("touchstart", listener);
+			events.forEach((eventName) => {
+				document.removeEventListener(eventName, onPointerEvent);
+			});
+			if (escape) document.removeEventListener("keydown", onKeyDown);
 		};
-	}, [enabled]);
-	return ref;
+	}, [
+		enabled,
+		escape,
+		events.join(",")
+	]);
 };
 
 //#endregion

package/dist/hooks/use-click-outside.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-click-outside.mjs","names":[],"sources":["../../src/hooks/use-click-outside.ts"],"sourcesContent":["import { useEffect, useRef } from 'react';\n\nconst useClickOutside = <T extends HTMLElement = HTMLElement>(\n  handler: (event: MouseEvent | TouchEvent) => void,\n  enabled = true,\n) => {\n  const ref = useRef<T>(null);\n  const handlerRef = useRef(handler);\n\n  useEffect(() => {\n    handlerRef.current = handler;\n  });\n\n  useEffect(() => {\n    if (!enabled || typeof document === 'undefined') {\n      return;\n    }\n\n    const listener = (event: MouseEvent | TouchEvent) => {\n      const el = ref.current;\n      if (!el || el.contains(event.target as Node)) {\n        return;\n      }\n      handlerRef.current(event);\n    };\n\n    document.addEventListener('mousedown', listener);\n    document.addEventListener('touchstart', listener);\n\n    return () => {\n      document.removeEventListener('mousedown', listener);\n      document.removeEventListener('touchstart', listener);\n    };\n  }, [enabled]);\n\n  return ref;\n};\n\nexport default useClickOutside;\n"],"mappings":";;;AAEA,MAAM,mBACJ,SACA,UAAU,SACP;CACH,MAAM,MAAM,OAAU,KAAK;CAC3B,MAAM,aAAa,OAAO,QAAQ;AAElC,iBAAgB;AACd,aAAW,UAAU;GACrB;AAEF,iBAAgB;AACd,MAAI,CAAC,WAAW,OAAO,aAAa,YAClC;EAGF,MAAM,YAAY,UAAmC;GACnD,MAAM,KAAK,IAAI;AACf,OAAI,CAAC,MAAM,GAAG,SAAS,MAAM,OAAe,CAC1C;AAEF,cAAW,QAAQ,MAAM;;AAG3B,WAAS,iBAAiB,aAAa,SAAS;AAChD,WAAS,iBAAiB,cAAc,SAAS;AAEjD,eAAa;AACX,YAAS,oBAAoB,aAAa,SAAS;AACnD,YAAS,oBAAoB,cAAc,SAAS;;IAErD,CAAC,QAAQ,CAAC;AAEb,QAAO"}
+{"version":3,"file":"use-click-outside.mjs","names":[],"sources":["../../src/hooks/use-click-outside.ts"],"sourcesContent":["import { type RefObject, useEffect, useRef } from 'react';\n\ntype ClickOutsideRef = RefObject<HTMLElement | null> | null | undefined;\n\ntype ClickOutsideEvent = PointerEvent | MouseEvent | TouchEvent | KeyboardEvent;\n\ninterface Options {\n  enabled?: boolean;\n  events?: ('pointerdown' | 'mousedown' | 'touchstart')[];\n  escape?: boolean;\n}\n\n// Takes the \"inside\" ref(s) as an argument instead of creating and\n// returning one — lets a caller pass multiple exclusion targets (e.g. a\n// dropdown's trigger button *and* its portaled panel, which live in\n// different DOM subtrees) instead of only ever watching one element.\nconst useClickOutside = (\n  refs: ClickOutsideRef | ClickOutsideRef[],\n  handler: (event: ClickOutsideEvent) => void,\n  options: Options = {},\n) => {\n  // `escape` is opt-in (default `false`): the hook is named for clicks, and\n  // an always-on Escape handler both surprises callers who already handle\n  // Escape themselves (double-fire) and closes every layer at once in\n  // nested UI (a dropdown inside a modal). Turn it on where you want it.\n  const { enabled = true, events = ['pointerdown'], escape = false } = options;\n\n  const handlerRef = useRef(handler);\n\n  useEffect(() => {\n    handlerRef.current = handler;\n  });\n\n  const refList = Array.isArray(refs) ? refs : [refs];\n  // `refs` is almost always an inline array literal at the call site, so\n  // depending on it directly would tear down/rebuild the listeners on\n  // every render — read the latest value from a ref instead.\n  const refListRef = useRef(refList);\n\n  useEffect(() => {\n    refListRef.current = refList;\n  });\n\n  const eventsKey = events.join(',');\n\n  useEffect(() => {\n    if (!enabled || typeof document === 'undefined') {\n      return;\n    }\n\n    const isInside = (target: Node) =>\n      refListRef.current.some(ref => ref?.current?.contains(target));\n\n    const onPointerEvent = (event: Event) => {\n      const target = event.target as Node | null;\n\n      if (!target || isInside(target)) {\n        return;\n      }\n\n      handlerRef.current(event as ClickOutsideEvent);\n    };\n\n    const onKeyDown = (event: KeyboardEvent) => {\n      if (event.key === 'Escape') {\n        handlerRef.current(event);\n      }\n    };\n\n    events.forEach(eventName => {\n      document.addEventListener(eventName, onPointerEvent);\n    });\n\n    if (escape) {\n      document.addEventListener('keydown', onKeyDown);\n    }\n\n    return () => {\n      events.forEach(eventName => {\n        document.removeEventListener(eventName, onPointerEvent);\n      });\n\n      if (escape) {\n        document.removeEventListener('keydown', onKeyDown);\n      }\n    };\n    // `events` is covered by `eventsKey` below instead of the array\n    // itself, which (like `refs`) is usually a fresh literal every render.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [enabled, escape, eventsKey]);\n};\n\nexport default useClickOutside;\n"],"mappings":";;;AAgBA,MAAM,mBACJ,MACA,SACA,UAAmB,EAAE,KAClB;CAKH,MAAM,EAAE,UAAU,MAAM,SAAS,CAAC,cAAc,EAAE,SAAS,UAAU;CAErE,MAAM,aAAa,OAAO,QAAQ;AAElC,iBAAgB;AACd,aAAW,UAAU;GACrB;CAEF,MAAM,UAAU,MAAM,QAAQ,KAAK,GAAG,OAAO,CAAC,KAAK;CAInD,MAAM,aAAa,OAAO,QAAQ;AAElC,iBAAgB;AACd,aAAW,UAAU;GACrB;AAIF,iBAAgB;AACd,MAAI,CAAC,WAAW,OAAO,aAAa,YAClC;EAGF,MAAM,YAAY,WAChB,WAAW,QAAQ,MAAK,QAAO,KAAK,SAAS,SAAS,OAAO,CAAC;EAEhE,MAAM,kBAAkB,UAAiB;GACvC,MAAM,SAAS,MAAM;AAErB,OAAI,CAAC,UAAU,SAAS,OAAO,CAC7B;AAGF,cAAW,QAAQ,MAA2B;;EAGhD,MAAM,aAAa,UAAyB;AAC1C,OAAI,MAAM,QAAQ,SAChB,YAAW,QAAQ,MAAM;;AAI7B,SAAO,SAAQ,cAAa;AAC1B,YAAS,iBAAiB,WAAW,eAAe;IACpD;AAEF,MAAI,OACF,UAAS,iBAAiB,WAAW,UAAU;AAGjD,eAAa;AACX,UAAO,SAAQ,cAAa;AAC1B,aAAS,oBAAoB,WAAW,eAAe;KACvD;AAEF,OAAI,OACF,UAAS,oBAAoB,WAAW,UAAU;;IAMrD;EAAC;EAAS;EA9CK,OAAO,KAAK,IAAI;EA8CH,CAAC"}

package/dist/hooks/use-debounced-callback.d.mts

@@ -0,0 +1,14 @@
+//#region src/hooks/use-debounced-callback.d.ts
+interface Options {
+  delay?: number;
+  autoInvoke?: boolean;
+  leading?: boolean;
+}
+declare const useDebouncedCallback: (callback: () => unknown, {
+  delay,
+  autoInvoke,
+  leading
+}: Options, deps?: React.DependencyList) => () => void;
+//#endregion
+export { useDebouncedCallback };
+//# sourceMappingURL=use-debounced-callback.d.mts.map

package/dist/hooks/{use-debounce.mjs → use-debounced-callback.mjs}

@@ -1,7 +1,7 @@
 import { useEffect, useRef } from "react";
 
-//#region src/hooks/use-debounce.ts
-const useDebounce = (callback, { delay = 100, autoInvoke = true, leading = true }, deps = []) => {
+//#region src/hooks/use-debounced-callback.ts
+const useDebouncedCallback = (callback, { delay = 100, autoInvoke = true, leading = true }, deps = []) => {
 	const timeoutRef = useRef(null);
 	const callbackRef = useRef(callback);
 	const delayRef = useRef(delay);
@@ -33,5 +33,5 @@ const useDebounce = (callback, { delay = 100, autoInvoke = true, leading = true
 };
 
 //#endregion
-export { useDebounce as default };
-//# sourceMappingURL=use-debounce.mjs.map
+export { useDebouncedCallback as default };
+//# sourceMappingURL=use-debounced-callback.mjs.map

package/dist/hooks/use-debounced-callback.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-debounced-callback.mjs","names":[],"sources":["../../src/hooks/use-debounced-callback.ts"],"sourcesContent":["import { useEffect, useRef } from 'react';\n\ninterface Options {\n  delay?: number;\n  autoInvoke?: boolean;\n  leading?: boolean;\n}\n\n// Auto-invokes `callback` (debounced by `delay`ms) whenever `deps` change,\n// and also returns a stable debounced version of `callback` for manual use.\n// `callback` intentionally takes no arguments — the deps-triggered\n// auto-invoke has no natural argument to supply, so an arg-taking callback\n// here was a latent type hole (it was always invoked with zero args\n// regardless of what the callback's own signature claimed).\nconst useDebouncedCallback = (\n  callback: () => unknown,\n  { delay = 100, autoInvoke = true, leading = true }: Options,\n  deps: React.DependencyList = [],\n) => {\n  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n  const callbackRef = useRef(callback);\n  // Read the latest `delay` when the timeout actually fires, instead of\n  // baking in whatever `delay` was on the render that created the stable\n  // debounced function (which otherwise never updates again).\n  const delayRef = useRef(delay);\n  const prevDeps = useRef<React.DependencyList | undefined>(undefined);\n\n  useEffect(() => {\n    callbackRef.current = callback;\n    delayRef.current = delay;\n  });\n\n  const stableDebouncedCallback = useRef<(() => void) | null>(null);\n\n  if (!stableDebouncedCallback.current) {\n    stableDebouncedCallback.current = () => {\n      if (timeoutRef.current) {\n        clearTimeout(timeoutRef.current);\n      }\n\n      timeoutRef.current = setTimeout(() => {\n        callbackRef.current();\n      }, delayRef.current);\n    };\n  }\n\n  useEffect(() => {\n    const depsChanged =\n      prevDeps.current === undefined ||\n      prevDeps.current.length !== deps.length ||\n      prevDeps.current.some((dep, i) => dep !== deps[i]);\n\n    if (depsChanged && timeoutRef.current) {\n      clearTimeout(timeoutRef.current);\n    }\n\n    if (autoInvoke && depsChanged) {\n      const isFirstRender = prevDeps.current === undefined;\n\n      // `leading` makes the \"first invocation fires immediately, without\n      // waiting `delay`ms\" behavior explicit and opt-out-able, instead of\n      // an unconditional special case baked into the first render.\n      if (isFirstRender && leading) {\n        callbackRef.current();\n      } else {\n        stableDebouncedCallback.current?.();\n      }\n    }\n\n    prevDeps.current = deps;\n  });\n\n  useEffect(() => {\n    return () => {\n      if (timeoutRef.current) {\n        clearTimeout(timeoutRef.current);\n      }\n    };\n  }, []);\n\n  return stableDebouncedCallback.current;\n};\n\nexport default useDebouncedCallback;\n"],"mappings":";;;AAcA,MAAM,wBACJ,UACA,EAAE,QAAQ,KAAK,aAAa,MAAM,UAAU,QAC5C,OAA6B,EAAE,KAC5B;CACH,MAAM,aAAa,OAA6C,KAAK;CACrE,MAAM,cAAc,OAAO,SAAS;CAIpC,MAAM,WAAW,OAAO,MAAM;CAC9B,MAAM,WAAW,OAAyC,OAAU;AAEpE,iBAAgB;AACd,cAAY,UAAU;AACtB,WAAS,UAAU;GACnB;CAEF,MAAM,0BAA0B,OAA4B,KAAK;AAEjE,KAAI,CAAC,wBAAwB,QAC3B,yBAAwB,gBAAgB;AACtC,MAAI,WAAW,QACb,cAAa,WAAW,QAAQ;AAGlC,aAAW,UAAU,iBAAiB;AACpC,eAAY,SAAS;KACpB,SAAS,QAAQ;;AAIxB,iBAAgB;EACd,MAAM,cACJ,SAAS,YAAY,UACrB,SAAS,QAAQ,WAAW,KAAK,UACjC,SAAS,QAAQ,MAAM,KAAK,MAAM,QAAQ,KAAK,GAAG;AAEpD,MAAI,eAAe,WAAW,QAC5B,cAAa,WAAW,QAAQ;AAGlC,MAAI,cAAc,YAMhB,KALsB,SAAS,YAAY,UAKtB,QACnB,aAAY,SAAS;MAErB,yBAAwB,WAAW;AAIvC,WAAS,UAAU;GACnB;AAEF,iBAAgB;AACd,eAAa;AACX,OAAI,WAAW,QACb,cAAa,WAAW,QAAQ;;IAGnC,EAAE,CAAC;AAEN,QAAO,wBAAwB"}

package/dist/hooks/use-debounced-value.d.mts

@@ -0,0 +1,5 @@
+//#region src/hooks/use-debounced-value.d.ts
+declare const useDebouncedValue: <T>(value: T, delay?: number) => T;
+//#endregion
+export { useDebouncedValue };
+//# sourceMappingURL=use-debounced-value.d.mts.map

package/dist/hooks/use-debounced-value.mjs

@@ -0,0 +1,20 @@
+import { useEffect, useRef, useState } from "react";
+
+//#region src/hooks/use-debounced-value.ts
+const useDebouncedValue = (value, delay = 100) => {
+	const [debouncedValue, setDebouncedValue] = useState(value);
+	const timeoutRef = useRef(null);
+	useEffect(() => {
+		timeoutRef.current = setTimeout(() => {
+			setDebouncedValue(value);
+		}, delay);
+		return () => {
+			if (timeoutRef.current) clearTimeout(timeoutRef.current);
+		};
+	}, [value, delay]);
+	return debouncedValue;
+};
+
+//#endregion
+export { useDebouncedValue as default };
+//# sourceMappingURL=use-debounced-value.mjs.map

package/dist/hooks/use-debounced-value.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-debounced-value.mjs","names":[],"sources":["../../src/hooks/use-debounced-value.ts"],"sourcesContent":["import { useEffect, useRef, useState } from 'react';\n\n// The value-shaped counterpart to useDebounce (which is callback-shaped),\n// symmetric with useThrottle's `(value, delay) => value` signature. The\n// common \"just give me the debounced value\" case otherwise needs two\n// pieces of state and an effect built on useDebounce by hand.\nconst useDebouncedValue = <T>(value: T, delay = 100): T => {\n  const [debouncedValue, setDebouncedValue] = useState(value);\n  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n  useEffect(() => {\n    timeoutRef.current = setTimeout(() => {\n      setDebouncedValue(value);\n    }, delay);\n\n    return () => {\n      if (timeoutRef.current) {\n        clearTimeout(timeoutRef.current);\n      }\n    };\n  }, [value, delay]);\n\n  return debouncedValue;\n};\n\nexport default useDebouncedValue;\n"],"mappings":";;;AAMA,MAAM,qBAAwB,OAAU,QAAQ,QAAW;CACzD,MAAM,CAAC,gBAAgB,qBAAqB,SAAS,MAAM;CAC3D,MAAM,aAAa,OAA6C,KAAK;AAErE,iBAAgB;AACd,aAAW,UAAU,iBAAiB;AACpC,qBAAkB,MAAM;KACvB,MAAM;AAET,eAAa;AACX,OAAI,WAAW,QACb,cAAa,WAAW,QAAQ;;IAGnC,CAAC,OAAO,MAAM,CAAC;AAElB,QAAO"}

package/dist/hooks/use-event-listener.d.mts

@@ -0,0 +1,21 @@
+import { RefObject } from "react";
+
+//#region src/hooks/use-event-listener.d.ts
+interface Options {
+  capture?: boolean;
+  passive?: boolean;
+  once?: boolean;
+  enabled?: boolean;
+}
+declare function useEventListener<K extends keyof WindowEventMap>(type: K, handler: (event: WindowEventMap[K]) => void, options?: Options & {
+  target?: Window | null;
+}): void;
+declare function useEventListener<K extends keyof DocumentEventMap>(type: K, handler: (event: DocumentEventMap[K]) => void, options: Options & {
+  target: Document | RefObject<Document | null>;
+}): void;
+declare function useEventListener<T extends HTMLElement, K extends keyof HTMLElementEventMap>(type: K, handler: (event: HTMLElementEventMap[K]) => void, options: Options & {
+  target: RefObject<T | null>;
+}): void;
+//#endregion
+export { useEventListener };
+//# sourceMappingURL=use-event-listener.d.mts.map

package/dist/hooks/use-event-listener.mjs

@@ -0,0 +1,50 @@
+import { useEffect, useRef } from "react";
+
+//#region src/hooks/use-event-listener.ts
+function useEventListener(type, handler, options = {}) {
+	const { target, capture, passive, once, enabled = true } = options;
+	const handlerRef = useRef(handler);
+	useEffect(() => {
+		handlerRef.current = handler;
+	});
+	useEffect(() => {
+		if (!enabled) return;
+		let cancelled = false;
+		let rafId;
+		let resolvedTarget = null;
+		const listener = (event) => {
+			handlerRef.current(event);
+		};
+		const attach = () => {
+			if (cancelled) return;
+			if (target && "current" in target && !target.current) {
+				rafId = requestAnimationFrame(attach);
+				return;
+			}
+			resolvedTarget = target && "current" in target ? target.current : target ?? (typeof window === "undefined" ? null : window);
+			if (!resolvedTarget) return;
+			resolvedTarget.addEventListener(type, listener, {
+				capture,
+				passive,
+				once
+			});
+		};
+		attach();
+		return () => {
+			cancelled = true;
+			if (rafId !== void 0) cancelAnimationFrame(rafId);
+			resolvedTarget?.removeEventListener(type, listener, { capture });
+		};
+	}, [
+		type,
+		target,
+		capture,
+		passive,
+		once,
+		enabled
+	]);
+}
+
+//#endregion
+export { useEventListener as default };
+//# sourceMappingURL=use-event-listener.mjs.map

package/dist/hooks/use-event-listener.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-event-listener.mjs","names":[],"sources":["../../src/hooks/use-event-listener.ts"],"sourcesContent":["import { type RefObject, useEffect, useRef } from 'react';\n\ninterface Options {\n  capture?: boolean;\n  passive?: boolean;\n  once?: boolean;\n  enabled?: boolean;\n}\n\ntype EventListenerTarget = EventTarget | RefObject<EventTarget | null> | null;\n\nfunction useEventListener<K extends keyof WindowEventMap>(\n  type: K,\n  handler: (event: WindowEventMap[K]) => void,\n  options?: Options & { target?: Window | null },\n): void;\nfunction useEventListener<K extends keyof DocumentEventMap>(\n  type: K,\n  handler: (event: DocumentEventMap[K]) => void,\n  options: Options & { target: Document | RefObject<Document | null> },\n): void;\nfunction useEventListener<\n  T extends HTMLElement,\n  K extends keyof HTMLElementEventMap,\n>(\n  type: K,\n  handler: (event: HTMLElementEventMap[K]) => void,\n  options: Options & { target: RefObject<T | null> },\n): void;\n\n// Resolves `target` (default `window`, or a raw EventTarget, or a\n// RefObject pointing at one) and (de)registers `type` on it — the pair of\n// addEventListener/removeEventListener calls duplicated across ui-kit\n// (marquee item) and live-editor (error handlers). `handler` is read\n// through a ref so a fresh function every render doesn't tear down and\n// re-add the listener.\nfunction useEventListener(\n  type: string,\n  handler: (event: Event) => void,\n  options: Options & { target?: EventListenerTarget } = {},\n) {\n  const { target, capture, passive, once, enabled = true } = options;\n\n  const handlerRef = useRef(handler);\n\n  useEffect(() => {\n    handlerRef.current = handler;\n  });\n\n  useEffect(() => {\n    if (!enabled) {\n      return;\n    }\n\n    let cancelled = false;\n    let rafId: number | undefined;\n    let resolvedTarget: EventTarget | null = null;\n\n    const listener = (event: Event) => {\n      handlerRef.current(event);\n    };\n\n    const attach = () => {\n      if (cancelled) {\n        return;\n      }\n\n      // A RefObject target can still be null right after mount (conditional\n      // render, portal, lazy mount) — retry every frame until it's\n      // populated instead of giving up on the first effect run. A raw\n      // target or the default window has nothing to wait for.\n      if (target && 'current' in target && !target.current) {\n        rafId = requestAnimationFrame(attach);\n        return;\n      }\n\n      resolvedTarget =\n        target && 'current' in target\n          ? target.current\n          : (target ?? (typeof window === 'undefined' ? null : window));\n\n      if (!resolvedTarget) {\n        return;\n      }\n\n      resolvedTarget.addEventListener(type, listener, {\n        capture,\n        passive,\n        once,\n      });\n    };\n\n    attach();\n\n    return () => {\n      cancelled = true;\n      if (rafId !== undefined) {\n        cancelAnimationFrame(rafId);\n      }\n      resolvedTarget?.removeEventListener(type, listener, { capture });\n    };\n  }, [type, target, capture, passive, once, enabled]);\n}\n\nexport default useEventListener;\n"],"mappings":";;;AAoCA,SAAS,iBACP,MACA,SACA,UAAsD,EAAE,EACxD;CACA,MAAM,EAAE,QAAQ,SAAS,SAAS,MAAM,UAAU,SAAS;CAE3D,MAAM,aAAa,OAAO,QAAQ;AAElC,iBAAgB;AACd,aAAW,UAAU;GACrB;AAEF,iBAAgB;AACd,MAAI,CAAC,QACH;EAGF,IAAI,YAAY;EAChB,IAAI;EACJ,IAAI,iBAAqC;EAEzC,MAAM,YAAY,UAAiB;AACjC,cAAW,QAAQ,MAAM;;EAG3B,MAAM,eAAe;AACnB,OAAI,UACF;AAOF,OAAI,UAAU,aAAa,UAAU,CAAC,OAAO,SAAS;AACpD,YAAQ,sBAAsB,OAAO;AACrC;;AAGF,oBACE,UAAU,aAAa,SACnB,OAAO,UACN,WAAW,OAAO,WAAW,cAAc,OAAO;AAEzD,OAAI,CAAC,eACH;AAGF,kBAAe,iBAAiB,MAAM,UAAU;IAC9C;IACA;IACA;IACD,CAAC;;AAGJ,UAAQ;AAER,eAAa;AACX,eAAY;AACZ,OAAI,UAAU,OACZ,sBAAqB,MAAM;AAE7B,mBAAgB,oBAAoB,MAAM,UAAU,EAAE,SAAS,CAAC;;IAEjE;EAAC;EAAM;EAAQ;EAAS;EAAS;EAAM;EAAQ,CAAC"}

package/dist/hooks/use-file-drop.d.mts

@@ -0,0 +1,14 @@
+//#region src/hooks/use-file-drop.d.ts
+interface Options {
+  onDrop?: (files: File[]) => void;
+  accept?: string;
+  multiple?: boolean;
+  disabled?: boolean;
+}
+declare const useFileDrop: <T extends HTMLElement = HTMLElement>(options?: Options) => {
+  dropRef: (node: T | null) => void;
+  isDragging: boolean;
+};
+//#endregion
+export { useFileDrop };
+//# sourceMappingURL=use-file-drop.d.mts.map

package/dist/hooks/use-file-drop.mjs

@@ -0,0 +1,85 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+//#region src/hooks/use-file-drop.ts
+const matchesAccept = (file, accept) => {
+	if (!accept) return true;
+	const patterns = accept.split(",").map((pattern) => pattern.trim()).filter(Boolean);
+	if (patterns.length === 0) return true;
+	return patterns.some((pattern) => {
+		if (pattern.startsWith(".")) return file.name.toLowerCase().endsWith(pattern.toLowerCase());
+		if (pattern.endsWith("/*")) return file.type.startsWith(pattern.slice(0, -1));
+		return file.type === pattern;
+	});
+};
+const useFileDrop = (options = {}) => {
+	const { onDrop, accept, multiple = true, disabled = false } = options;
+	const [isDragging, setIsDragging] = useState(false);
+	const dragCounterRef = useRef(0);
+	const onDropRef = useRef(onDrop);
+	const acceptRef = useRef(accept);
+	const multipleRef = useRef(multiple);
+	const disabledRef = useRef(disabled);
+	useEffect(() => {
+		onDropRef.current = onDrop;
+		acceptRef.current = accept;
+		multipleRef.current = multiple;
+		disabledRef.current = disabled;
+	});
+	useEffect(() => {
+		if (disabled) {
+			dragCounterRef.current = 0;
+			setIsDragging(false);
+		}
+	}, [disabled]);
+	const cleanupRef = useRef(null);
+	return {
+		dropRef: useCallback((node) => {
+			cleanupRef.current?.();
+			cleanupRef.current = null;
+			if (!node) return;
+			const onDragEnter = (event) => {
+				if (disabledRef.current) return;
+				event.preventDefault();
+				dragCounterRef.current += 1;
+				if (dragCounterRef.current === 1) setIsDragging(true);
+			};
+			const onDragLeave = (event) => {
+				if (disabledRef.current) return;
+				event.preventDefault();
+				dragCounterRef.current = Math.max(0, dragCounterRef.current - 1);
+				if (dragCounterRef.current === 0) setIsDragging(false);
+			};
+			const onDragOver = (event) => {
+				if (disabledRef.current) return;
+				event.preventDefault();
+			};
+			const onDrop = (event) => {
+				if (disabledRef.current) return;
+				event.preventDefault();
+				dragCounterRef.current = 0;
+				setIsDragging(false);
+				const fileList = event.dataTransfer?.files;
+				if (!fileList || fileList.length === 0) return;
+				let files = Array.from(fileList).filter((file) => matchesAccept(file, acceptRef.current));
+				if (!multipleRef.current) files = files.slice(0, 1);
+				if (files.length > 0) onDropRef.current?.(files);
+			};
+			node.addEventListener("dragenter", onDragEnter);
+			node.addEventListener("dragleave", onDragLeave);
+			node.addEventListener("dragover", onDragOver);
+			node.addEventListener("drop", onDrop);
+			cleanupRef.current = () => {
+				node.removeEventListener("dragenter", onDragEnter);
+				node.removeEventListener("dragleave", onDragLeave);
+				node.removeEventListener("dragover", onDragOver);
+				node.removeEventListener("drop", onDrop);
+				dragCounterRef.current = 0;
+			};
+		}, []),
+		isDragging
+	};
+};
+
+//#endregion
+export { useFileDrop as default };
+//# sourceMappingURL=use-file-drop.mjs.map