@jbpark/use-hooks 2.6.0 → 2.8.0

package/README.ko.md

@@ -67,23 +67,25 @@ 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로 요소의 뷰포트 교차 여부 추적                           |
+| 훅                        | 설명                                                                    |
+| ------------------------- | ----------------------------------------------------------------------- |
+| `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 조합을 훅 하나로 제어/비제어 상태 관리 |
 
 ## 개발
 
@@ -118,6 +120,7 @@ src/
 │   ├── use-image.ts
 │   ├── use-intersection-observer.ts
 │   ├── use-local-storage.ts
+│   ├── use-multi-select.ts
 │   ├── use-recursive-timeout.ts
 │   ├── use-responsive-size.ts
 │   ├── use-scroll-to-elements.ts

package/README.md

@@ -67,23 +67,25 @@ 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                 |
+| 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 |
 
 ## Development
 
@@ -118,6 +120,7 @@ src/
 │   ├── use-image.ts
 │   ├── use-intersection-observer.ts
 │   ├── use-local-storage.ts
+│   ├── use-multi-select.ts
 │   ├── use-recursive-timeout.ts
 │   ├── use-responsive-size.ts
 │   ├── use-scroll-to-elements.ts

package/dist/hooks/index.d.mts

@@ -1,6 +1,7 @@
 import { useDebounce } from "./use-debounce.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 { useFileToDataUrl } from "./use-file-to-data-url.mjs";
@@ -9,6 +10,7 @@ import { useIntersectionObserver } from "./use-intersection-observer.mjs";
 import { useResponsiveSize } from "./use-responsive-size.mjs";
 import { useImage } from "./use-image.mjs";
 import { useLocalStorage } from "./use-local-storage.mjs";
+import { useMultiSelect } from "./use-multi-select.mjs";
 import { useRecursiveTimeout } from "./use-recursive-timeout.mjs";
 import { useScrollToElements } from "./use-scroll-to-elements.mjs";
 import { useThrottle } from "./use-throttle.mjs";

package/dist/hooks/index.mjs

@@ -1,6 +1,7 @@
 import useDebounce from "./use-debounce.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 useFileToDataUrl from "./use-file-to-data-url.mjs";
@@ -9,6 +10,7 @@ import useIntersectionObserver from "./use-intersection-observer.mjs";
 import useResponsiveSize from "./use-responsive-size.mjs";
 import useImage from "./use-image.mjs";
 import useLocalStorage from "./use-local-storage.mjs";
+import useMultiSelect from "./use-multi-select.mjs";
 import useRecursiveTimeout from "./use-recursive-timeout.mjs";
 import useScrollToElements from "./use-scroll-to-elements.mjs";
 import useThrottle from "./use-throttle.mjs";

package/dist/hooks/use-controllable-state.d.mts

@@ -0,0 +1,14 @@
+//#region src/hooks/use-controllable-state.d.ts
+interface UseControllableStateProps<T> {
+  value?: T;
+  defaultValue?: T;
+  onChange?: (value: T) => void;
+}
+declare const useControllableState: <T>({
+  value,
+  defaultValue,
+  onChange
+}: UseControllableStateProps<T>) => [T, (next: T) => void];
+//#endregion
+export { useControllableState };
+//# sourceMappingURL=use-controllable-state.d.mts.map

package/dist/hooks/use-controllable-state.mjs

@@ -0,0 +1,15 @@
+import { useCallback, useState } from "react";
+
+//#region src/hooks/use-controllable-state.ts
+const useControllableState = ({ value, defaultValue, onChange }) => {
+	const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
+	const isControlled = value !== void 0;
+	return [isControlled ? value : uncontrolledValue, useCallback((next) => {
+		if (!isControlled) setUncontrolledValue(next);
+		onChange?.(next);
+	}, [isControlled, onChange])];
+};
+
+//#endregion
+export { useControllableState as default };
+//# sourceMappingURL=use-controllable-state.mjs.map

package/dist/hooks/use-controllable-state.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-controllable-state.mjs","names":[],"sources":["../../src/hooks/use-controllable-state.ts"],"sourcesContent":["import { useCallback, useState } from 'react';\n\ninterface UseControllableStateProps<T> {\n  value?: T;\n  defaultValue?: T;\n  onChange?: (value: T) => void;\n}\n\n// Backs a controlled/uncontrolled prop pair (`value`/`defaultValue`/\n// `onChange`) with one hook: falls back to internal state whenever `value`\n// is `undefined`, and always calls `onChange` regardless of which mode is\n// active, so callers don't have to branch on it themselves.\nconst useControllableState = <T>({\n  value,\n  defaultValue,\n  onChange,\n}: UseControllableStateProps<T>): [T, (next: T) => void] => {\n  const [uncontrolledValue, setUncontrolledValue] = useState<T | undefined>(\n    defaultValue,\n  );\n\n  const isControlled = value !== undefined;\n  const currentValue = (isControlled ? value : uncontrolledValue) as T;\n\n  const setValue = useCallback(\n    (next: T) => {\n      if (!isControlled) {\n        setUncontrolledValue(next);\n      }\n      onChange?.(next);\n    },\n    [isControlled, onChange],\n  );\n\n  return [currentValue, setValue];\n};\n\nexport default useControllableState;\n"],"mappings":";;;AAYA,MAAM,wBAA2B,EAC/B,OACA,cACA,eAC0D;CAC1D,MAAM,CAAC,mBAAmB,wBAAwB,SAChD,aACD;CAED,MAAM,eAAe,UAAU;AAa/B,QAAO,CAZe,eAAe,QAAQ,mBAE5B,aACd,SAAY;AACX,MAAI,CAAC,aACH,sBAAqB,KAAK;AAE5B,aAAW,KAAK;IAElB,CAAC,cAAc,SAAS,CACzB,CAE8B"}

package/dist/hooks/use-multi-select.d.mts

@@ -0,0 +1,11 @@
+//#region src/hooks/use-multi-select.d.ts
+declare const useMultiSelect: (count: number) => {
+  readonly selected: Set<number>;
+  readonly isSelected: (index: number) => boolean;
+  readonly toggle: (index: number, shiftKey?: boolean) => void;
+  readonly clear: () => void;
+  readonly replace: (indices: Set<number>) => void;
+};
+//#endregion
+export { useMultiSelect };
+//# sourceMappingURL=use-multi-select.d.mts.map

package/dist/hooks/use-multi-select.mjs

@@ -0,0 +1,43 @@
+import { useCallback, useMemo, useState } from "react";
+
+//#region src/hooks/use-multi-select.ts
+const useMultiSelect = (count) => {
+	const [rawSelected, setRawSelected] = useState(/* @__PURE__ */ new Set());
+	const [anchor, setAnchor] = useState(null);
+	const selected = useMemo(() => {
+		const next = new Set([...rawSelected].filter((index) => index < count));
+		return next.size === rawSelected.size ? rawSelected : next;
+	}, [rawSelected, count]);
+	const toggle = useCallback((index, shiftKey = false) => {
+		setRawSelected((prev) => {
+			const next = new Set(prev);
+			if (shiftKey && anchor !== null) {
+				const [start, end] = anchor < index ? [anchor, index] : [index, anchor];
+				for (let i = start; i <= end; i++) next.add(i);
+				return next;
+			}
+			if (next.has(index)) next.delete(index);
+			else next.add(index);
+			return next;
+		});
+		setAnchor(index);
+	}, [anchor]);
+	const clear = useCallback(() => {
+		setRawSelected(/* @__PURE__ */ new Set());
+		setAnchor(null);
+	}, []);
+	const replace = useCallback((indices) => {
+		setRawSelected(indices);
+	}, []);
+	return {
+		selected,
+		isSelected: useCallback((index) => selected.has(index), [selected]),
+		toggle,
+		clear,
+		replace
+	};
+};
+
+//#endregion
+export { useMultiSelect as default };
+//# sourceMappingURL=use-multi-select.mjs.map

package/dist/hooks/use-multi-select.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-multi-select.mjs","names":[],"sources":["../../src/hooks/use-multi-select.ts"],"sourcesContent":["import { useCallback, useMemo, useState } from 'react';\n\nconst useMultiSelect = (count: number) => {\n  const [rawSelected, setRawSelected] = useState<Set<number>>(new Set());\n  const [anchor, setAnchor] = useState<number | null>(null);\n\n  // Indices can outlive the item they pointed to (e.g. after the backing\n  // list shrinks) — clamp against the current count on every render\n  // instead of syncing state back via an effect.\n  const selected = useMemo(() => {\n    const next = new Set([...rawSelected].filter(index => index < count));\n    return next.size === rawSelected.size ? rawSelected : next;\n  }, [rawSelected, count]);\n\n  const toggle = useCallback(\n    (index: number, shiftKey = false) => {\n      setRawSelected(prev => {\n        const next = new Set(prev);\n\n        if (shiftKey && anchor !== null) {\n          const [start, end] =\n            anchor < index ? [anchor, index] : [index, anchor];\n\n          for (let i = start; i <= end; i++) {\n            next.add(i);\n          }\n          return next;\n        }\n\n        if (next.has(index)) {\n          next.delete(index);\n        } else {\n          next.add(index);\n        }\n        return next;\n      });\n      setAnchor(index);\n    },\n    [anchor],\n  );\n\n  const clear = useCallback(() => {\n    setRawSelected(new Set());\n    setAnchor(null);\n  }, []);\n\n  const replace = useCallback((indices: Set<number>) => {\n    setRawSelected(indices);\n  }, []);\n\n  const isSelected = useCallback(\n    (index: number) => selected.has(index),\n    [selected],\n  );\n\n  return {\n    selected,\n    isSelected,\n    toggle,\n    clear,\n    replace,\n  } as const;\n};\n\nexport default useMultiSelect;\n"],"mappings":";;;AAEA,MAAM,kBAAkB,UAAkB;CACxC,MAAM,CAAC,aAAa,kBAAkB,yBAAsB,IAAI,KAAK,CAAC;CACtE,MAAM,CAAC,QAAQ,aAAa,SAAwB,KAAK;CAKzD,MAAM,WAAW,cAAc;EAC7B,MAAM,OAAO,IAAI,IAAI,CAAC,GAAG,YAAY,CAAC,QAAO,UAAS,QAAQ,MAAM,CAAC;AACrE,SAAO,KAAK,SAAS,YAAY,OAAO,cAAc;IACrD,CAAC,aAAa,MAAM,CAAC;CAExB,MAAM,SAAS,aACZ,OAAe,WAAW,UAAU;AACnC,kBAAe,SAAQ;GACrB,MAAM,OAAO,IAAI,IAAI,KAAK;AAE1B,OAAI,YAAY,WAAW,MAAM;IAC/B,MAAM,CAAC,OAAO,OACZ,SAAS,QAAQ,CAAC,QAAQ,MAAM,GAAG,CAAC,OAAO,OAAO;AAEpD,SAAK,IAAI,IAAI,OAAO,KAAK,KAAK,IAC5B,MAAK,IAAI,EAAE;AAEb,WAAO;;AAGT,OAAI,KAAK,IAAI,MAAM,CACjB,MAAK,OAAO,MAAM;OAElB,MAAK,IAAI,MAAM;AAEjB,UAAO;IACP;AACF,YAAU,MAAM;IAElB,CAAC,OAAO,CACT;CAED,MAAM,QAAQ,kBAAkB;AAC9B,iCAAe,IAAI,KAAK,CAAC;AACzB,YAAU,KAAK;IACd,EAAE,CAAC;CAEN,MAAM,UAAU,aAAa,YAAyB;AACpD,iBAAe,QAAQ;IACtB,EAAE,CAAC;AAON,QAAO;EACL;EACA,YAPiB,aAChB,UAAkB,SAAS,IAAI,MAAM,EACtC,CAAC,SAAS,CACX;EAKC;EACA;EACA;EACD"}

package/dist/hooks/use-window-scroll.d.mts

@@ -1,5 +1,7 @@
+import { RefObject } from "react";
+
 //#region src/hooks/use-window-scroll.d.ts
-declare const useWindowScroll: () => {
+declare const useWindowScroll: (targetRef?: RefObject<Element | null>) => {
   x: number;
   y: number;
   percent: {

package/dist/hooks/use-window-scroll.mjs

@@ -1,7 +1,7 @@
 import { useEffect, useState } from "react";
 
 //#region src/hooks/use-window-scroll.ts
-const useWindowScroll = () => {
+const useWindowScroll = (targetRef) => {
 	const [state, setState] = useState({
 		x: 0,
 		y: 0,
@@ -11,15 +11,17 @@ const useWindowScroll = () => {
 		}
 	});
 	useEffect(() => {
+		const target = targetRef?.current?.ownerDocument.defaultView ?? window;
+		const doc = target.document;
 		const calculate = () => {
-			const x = window.scrollX || 0;
-			const y = window.scrollY || 0;
-			const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
-			const visualViewport = window.visualViewport;
-			const viewportWidth = isIOS && visualViewport ? visualViewport.width : window.innerWidth;
-			const viewportHeight = isIOS && visualViewport ? visualViewport.height : window.innerHeight;
-			const maxScrollX = Math.max(0, document.documentElement.scrollWidth - viewportWidth);
-			const maxScrollY = Math.max(0, document.documentElement.scrollHeight - viewportHeight);
+			const x = target.scrollX || 0;
+			const y = target.scrollY || 0;
+			const isIOS = /iPad|iPhone|iPod/.test(target.navigator.userAgent);
+			const visualViewport = target.visualViewport;
+			const viewportWidth = isIOS && visualViewport ? visualViewport.width : target.innerWidth;
+			const viewportHeight = isIOS && visualViewport ? visualViewport.height : target.innerHeight;
+			const maxScrollX = Math.max(0, doc.documentElement.scrollWidth - viewportWidth);
+			const maxScrollY = Math.max(0, doc.documentElement.scrollHeight - viewportHeight);
 			const percentX = maxScrollX === 0 ? 0 : Math.min(100, x / maxScrollX * 100);
 			const percentY = maxScrollY === 0 ? 0 : Math.min(100, y / maxScrollY * 100);
 			setState({
@@ -41,17 +43,17 @@ const useWindowScroll = () => {
 		const onVisualViewportChange = () => {
 			setTimeout(calculate, 50);
 		};
-		window.addEventListener("scroll", onScroll, { passive: true });
-		window.addEventListener("resize", onResize);
-		window.addEventListener("orientationchange", onResize);
-		if (window.visualViewport) window.visualViewport.addEventListener("resize", onVisualViewportChange);
+		target.addEventListener("scroll", onScroll, { passive: true });
+		target.addEventListener("resize", onResize);
+		target.addEventListener("orientationchange", onResize);
+		if (target.visualViewport) target.visualViewport.addEventListener("resize", onVisualViewportChange);
 		return () => {
-			window.removeEventListener("scroll", onScroll);
-			window.removeEventListener("resize", onResize);
-			window.removeEventListener("orientationchange", onResize);
-			if (window.visualViewport) window.visualViewport.removeEventListener("resize", onVisualViewportChange);
+			target.removeEventListener("scroll", onScroll);
+			target.removeEventListener("resize", onResize);
+			target.removeEventListener("orientationchange", onResize);
+			if (target.visualViewport) target.visualViewport.removeEventListener("resize", onVisualViewportChange);
 		};
-	}, []);
+	}, [targetRef]);
 	return state;
 };
 

package/dist/hooks/use-window-scroll.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-window-scroll.mjs","names":[],"sources":["../../src/hooks/use-window-scroll.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\n\nconst useWindowScroll = () => {\n  const [state, setState] = useState({\n    x: 0,\n    y: 0,\n    percent: {\n      x: 0,\n      y: 0,\n    },\n  });\n\n  useEffect(() => {\n    const calculate = () => {\n      const x = window.scrollX || 0;\n      const y = window.scrollY || 0;\n\n      const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);\n      const visualViewport = window.visualViewport;\n\n      const viewportWidth =\n        isIOS && visualViewport ? visualViewport.width : window.innerWidth;\n\n      const viewportHeight =\n        isIOS && visualViewport ? visualViewport.height : window.innerHeight;\n\n      const maxScrollX = Math.max(\n        0,\n        document.documentElement.scrollWidth - viewportWidth,\n      );\n      const maxScrollY = Math.max(\n        0,\n        document.documentElement.scrollHeight - viewportHeight,\n      );\n\n      const percentX =\n        maxScrollX === 0 ? 0 : Math.min(100, (x / maxScrollX) * 100);\n      const percentY =\n        maxScrollY === 0 ? 0 : Math.min(100, (y / maxScrollY) * 100);\n\n      setState({\n        x,\n        y,\n        percent: {\n          x: Math.floor(Math.max(0, percentX)),\n          y: Math.floor(Math.max(0, percentY)),\n        },\n      });\n    };\n\n    calculate();\n\n    const onScroll = () => {\n      calculate();\n    };\n\n    const onResize = () => {\n      setTimeout(calculate, 100);\n    };\n\n    const onVisualViewportChange = () => {\n      setTimeout(calculate, 50);\n    };\n\n    window.addEventListener('scroll', onScroll, { passive: true });\n    window.addEventListener('resize', onResize);\n    window.addEventListener('orientationchange', onResize);\n\n    if (window.visualViewport) {\n      window.visualViewport.addEventListener('resize', onVisualViewportChange);\n    }\n\n    return () => {\n      window.removeEventListener('scroll', onScroll);\n      window.removeEventListener('resize', onResize);\n      window.removeEventListener('orientationchange', onResize);\n\n      if (window.visualViewport) {\n        window.visualViewport.removeEventListener(\n          'resize',\n          onVisualViewportChange,\n        );\n      }\n    };\n  }, []);\n\n  return state;\n};\n\nexport default useWindowScroll;\n"],"mappings":";;;AAEA,MAAM,wBAAwB;CAC5B,MAAM,CAAC,OAAO,YAAY,SAAS;EACjC,GAAG;EACH,GAAG;EACH,SAAS;GACP,GAAG;GACH,GAAG;GACJ;EACF,CAAC;AAEF,iBAAgB;EACd,MAAM,kBAAkB;GACtB,MAAM,IAAI,OAAO,WAAW;GAC5B,MAAM,IAAI,OAAO,WAAW;GAE5B,MAAM,QAAQ,mBAAmB,KAAK,UAAU,UAAU;GAC1D,MAAM,iBAAiB,OAAO;GAE9B,MAAM,gBACJ,SAAS,iBAAiB,eAAe,QAAQ,OAAO;GAE1D,MAAM,iBACJ,SAAS,iBAAiB,eAAe,SAAS,OAAO;GAE3D,MAAM,aAAa,KAAK,IACtB,GACA,SAAS,gBAAgB,cAAc,cACxC;GACD,MAAM,aAAa,KAAK,IACtB,GACA,SAAS,gBAAgB,eAAe,eACzC;GAED,MAAM,WACJ,eAAe,IAAI,IAAI,KAAK,IAAI,KAAM,IAAI,aAAc,IAAI;GAC9D,MAAM,WACJ,eAAe,IAAI,IAAI,KAAK,IAAI,KAAM,IAAI,aAAc,IAAI;AAE9D,YAAS;IACP;IACA;IACA,SAAS;KACP,GAAG,KAAK,MAAM,KAAK,IAAI,GAAG,SAAS,CAAC;KACpC,GAAG,KAAK,MAAM,KAAK,IAAI,GAAG,SAAS,CAAC;KACrC;IACF,CAAC;;AAGJ,aAAW;EAEX,MAAM,iBAAiB;AACrB,cAAW;;EAGb,MAAM,iBAAiB;AACrB,cAAW,WAAW,IAAI;;EAG5B,MAAM,+BAA+B;AACnC,cAAW,WAAW,GAAG;;AAG3B,SAAO,iBAAiB,UAAU,UAAU,EAAE,SAAS,MAAM,CAAC;AAC9D,SAAO,iBAAiB,UAAU,SAAS;AAC3C,SAAO,iBAAiB,qBAAqB,SAAS;AAEtD,MAAI,OAAO,eACT,QAAO,eAAe,iBAAiB,UAAU,uBAAuB;AAG1E,eAAa;AACX,UAAO,oBAAoB,UAAU,SAAS;AAC9C,UAAO,oBAAoB,UAAU,SAAS;AAC9C,UAAO,oBAAoB,qBAAqB,SAAS;AAEzD,OAAI,OAAO,eACT,QAAO,eAAe,oBACpB,UACA,uBACD;;IAGJ,EAAE,CAAC;AAEN,QAAO"}
+{"version":3,"file":"use-window-scroll.mjs","names":[],"sources":["../../src/hooks/use-window-scroll.ts"],"sourcesContent":["import { type RefObject, useEffect, useState } from 'react';\n\n// Pass a ref to an element rendered inside the window you actually want to\n// track (e.g. a node portaled into an iframe). Without one, this defaults\n// to the host `window`, which is wrong whenever the caller doesn't live in\n// the top-level document. Resolved once per mount from `targetRef.current`.\nconst useWindowScroll = (targetRef?: RefObject<Element | null>) => {\n  const [state, setState] = useState({\n    x: 0,\n    y: 0,\n    percent: {\n      x: 0,\n      y: 0,\n    },\n  });\n\n  useEffect(() => {\n    const target = targetRef?.current?.ownerDocument.defaultView ?? window;\n    const doc = target.document;\n\n    const calculate = () => {\n      const x = target.scrollX || 0;\n      const y = target.scrollY || 0;\n\n      const isIOS = /iPad|iPhone|iPod/.test(target.navigator.userAgent);\n      const visualViewport = target.visualViewport;\n\n      const viewportWidth =\n        isIOS && visualViewport ? visualViewport.width : target.innerWidth;\n\n      const viewportHeight =\n        isIOS && visualViewport ? visualViewport.height : target.innerHeight;\n\n      const maxScrollX = Math.max(\n        0,\n        doc.documentElement.scrollWidth - viewportWidth,\n      );\n      const maxScrollY = Math.max(\n        0,\n        doc.documentElement.scrollHeight - viewportHeight,\n      );\n\n      const percentX =\n        maxScrollX === 0 ? 0 : Math.min(100, (x / maxScrollX) * 100);\n      const percentY =\n        maxScrollY === 0 ? 0 : Math.min(100, (y / maxScrollY) * 100);\n\n      setState({\n        x,\n        y,\n        percent: {\n          x: Math.floor(Math.max(0, percentX)),\n          y: Math.floor(Math.max(0, percentY)),\n        },\n      });\n    };\n\n    calculate();\n\n    const onScroll = () => {\n      calculate();\n    };\n\n    const onResize = () => {\n      setTimeout(calculate, 100);\n    };\n\n    const onVisualViewportChange = () => {\n      setTimeout(calculate, 50);\n    };\n\n    target.addEventListener('scroll', onScroll, { passive: true });\n    target.addEventListener('resize', onResize);\n    target.addEventListener('orientationchange', onResize);\n\n    if (target.visualViewport) {\n      target.visualViewport.addEventListener('resize', onVisualViewportChange);\n    }\n\n    return () => {\n      target.removeEventListener('scroll', onScroll);\n      target.removeEventListener('resize', onResize);\n      target.removeEventListener('orientationchange', onResize);\n\n      if (target.visualViewport) {\n        target.visualViewport.removeEventListener(\n          'resize',\n          onVisualViewportChange,\n        );\n      }\n    };\n  }, [targetRef]);\n\n  return state;\n};\n\nexport default useWindowScroll;\n"],"mappings":";;;AAMA,MAAM,mBAAmB,cAA0C;CACjE,MAAM,CAAC,OAAO,YAAY,SAAS;EACjC,GAAG;EACH,GAAG;EACH,SAAS;GACP,GAAG;GACH,GAAG;GACJ;EACF,CAAC;AAEF,iBAAgB;EACd,MAAM,SAAS,WAAW,SAAS,cAAc,eAAe;EAChE,MAAM,MAAM,OAAO;EAEnB,MAAM,kBAAkB;GACtB,MAAM,IAAI,OAAO,WAAW;GAC5B,MAAM,IAAI,OAAO,WAAW;GAE5B,MAAM,QAAQ,mBAAmB,KAAK,OAAO,UAAU,UAAU;GACjE,MAAM,iBAAiB,OAAO;GAE9B,MAAM,gBACJ,SAAS,iBAAiB,eAAe,QAAQ,OAAO;GAE1D,MAAM,iBACJ,SAAS,iBAAiB,eAAe,SAAS,OAAO;GAE3D,MAAM,aAAa,KAAK,IACtB,GACA,IAAI,gBAAgB,cAAc,cACnC;GACD,MAAM,aAAa,KAAK,IACtB,GACA,IAAI,gBAAgB,eAAe,eACpC;GAED,MAAM,WACJ,eAAe,IAAI,IAAI,KAAK,IAAI,KAAM,IAAI,aAAc,IAAI;GAC9D,MAAM,WACJ,eAAe,IAAI,IAAI,KAAK,IAAI,KAAM,IAAI,aAAc,IAAI;AAE9D,YAAS;IACP;IACA;IACA,SAAS;KACP,GAAG,KAAK,MAAM,KAAK,IAAI,GAAG,SAAS,CAAC;KACpC,GAAG,KAAK,MAAM,KAAK,IAAI,GAAG,SAAS,CAAC;KACrC;IACF,CAAC;;AAGJ,aAAW;EAEX,MAAM,iBAAiB;AACrB,cAAW;;EAGb,MAAM,iBAAiB;AACrB,cAAW,WAAW,IAAI;;EAG5B,MAAM,+BAA+B;AACnC,cAAW,WAAW,GAAG;;AAG3B,SAAO,iBAAiB,UAAU,UAAU,EAAE,SAAS,MAAM,CAAC;AAC9D,SAAO,iBAAiB,UAAU,SAAS;AAC3C,SAAO,iBAAiB,qBAAqB,SAAS;AAEtD,MAAI,OAAO,eACT,QAAO,eAAe,iBAAiB,UAAU,uBAAuB;AAG1E,eAAa;AACX,UAAO,oBAAoB,UAAU,SAAS;AAC9C,UAAO,oBAAoB,UAAU,SAAS;AAC9C,UAAO,oBAAoB,qBAAqB,SAAS;AAEzD,OAAI,OAAO,eACT,QAAO,eAAe,oBACpB,UACA,uBACD;;IAGJ,CAAC,UAAU,CAAC;AAEf,QAAO"}

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { useDebounce } from "./hooks/use-debounce.mjs";
 import { useBodyScrollLock } from "./hooks/use-body-scroll-lock.mjs";
 import { useClickOutside } from "./hooks/use-click-outside.mjs";
+import { useControllableState } from "./hooks/use-controllable-state.mjs";
 import { useElementPosition } from "./hooks/use-element-position.mjs";
 import { useElementScroll } from "./hooks/use-element-scroll.mjs";
 import { useFileToDataUrl } from "./hooks/use-file-to-data-url.mjs";
@@ -9,6 +10,7 @@ import { useIntersectionObserver } from "./hooks/use-intersection-observer.mjs";
 import { useResponsiveSize } from "./hooks/use-responsive-size.mjs";
 import { useImage } from "./hooks/use-image.mjs";
 import { useLocalStorage } from "./hooks/use-local-storage.mjs";
+import { useMultiSelect } from "./hooks/use-multi-select.mjs";
 import { useRecursiveTimeout } from "./hooks/use-recursive-timeout.mjs";
 import { useScrollToElements } from "./hooks/use-scroll-to-elements.mjs";
 import { useThrottle } from "./hooks/use-throttle.mjs";
@@ -16,4 +18,4 @@ import { useTimeline } from "./hooks/use-timeline.mjs";
 import { useWindowScroll } from "./hooks/use-window-scroll.mjs";
 import { useViewport } from "./hooks/use-viewport.mjs";
 import "./hooks/index.mjs";
-export { useBodyScrollLock, useClickOutside, useDebounce, useElementPosition, useElementScroll, useFileToDataUrl, useHistoryState, useImage, useIntersectionObserver, useLocalStorage, useRecursiveTimeout, useResponsiveSize, useScrollToElements, useThrottle, useTimeline, useViewport, useWindowScroll };
+export { useBodyScrollLock, useClickOutside, useControllableState, useDebounce, useElementPosition, useElementScroll, useFileToDataUrl, useHistoryState, useImage, useIntersectionObserver, useLocalStorage, useMultiSelect, useRecursiveTimeout, useResponsiveSize, useScrollToElements, useThrottle, useTimeline, useViewport, useWindowScroll };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import useDebounce from "./hooks/use-debounce.mjs";
 import useBodyScrollLock from "./hooks/use-body-scroll-lock.mjs";
 import useClickOutside from "./hooks/use-click-outside.mjs";
+import useControllableState from "./hooks/use-controllable-state.mjs";
 import useElementPosition from "./hooks/use-element-position.mjs";
 import useElementScroll from "./hooks/use-element-scroll.mjs";
 import useFileToDataUrl from "./hooks/use-file-to-data-url.mjs";
@@ -9,6 +10,7 @@ import useIntersectionObserver from "./hooks/use-intersection-observer.mjs";
 import useResponsiveSize from "./hooks/use-responsive-size.mjs";
 import useImage from "./hooks/use-image.mjs";
 import useLocalStorage from "./hooks/use-local-storage.mjs";
+import useMultiSelect from "./hooks/use-multi-select.mjs";
 import useRecursiveTimeout from "./hooks/use-recursive-timeout.mjs";
 import useScrollToElements from "./hooks/use-scroll-to-elements.mjs";
 import useThrottle from "./hooks/use-throttle.mjs";
@@ -17,4 +19,4 @@ import useWindowScroll from "./hooks/use-window-scroll.mjs";
 import useViewport from "./hooks/use-viewport.mjs";
 import "./hooks/index.mjs";
 
-export { useBodyScrollLock, useClickOutside, useDebounce, useElementPosition, useElementScroll, useFileToDataUrl, useHistoryState, useImage, useIntersectionObserver, useLocalStorage, useRecursiveTimeout, useResponsiveSize, useScrollToElements, useThrottle, useTimeline, useViewport, useWindowScroll };
+export { useBodyScrollLock, useClickOutside, useControllableState, useDebounce, useElementPosition, useElementScroll, useFileToDataUrl, useHistoryState, useImage, useIntersectionObserver, useLocalStorage, useMultiSelect, useRecursiveTimeout, useResponsiveSize, useScrollToElements, useThrottle, useTimeline, useViewport, useWindowScroll };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbpark/use-hooks",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "A collection of reusable React 19 hooks for common UI and interaction patterns",
   "keywords": [
     "react",