@jbpark/use-hooks 1.1.1

package/README.md

@@ -0,0 +1,162 @@
+# use-hooks
+
+[![npm version](https://img.shields.io/npm/v/@jbpark/use-hooks.svg)](https://www.npmjs.com/package/@jbpark/use-hooks)
+[![npm downloads](https://img.shields.io/npm/dm/@jbpark/use-hooks.svg)](https://www.npmjs.com/package/@jbpark/use-hooks)
+[![GitHub issues](https://img.shields.io/github/issues/pjb0811/use-hooks)](https://github.com/pjb0811/use-hooks/issues)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+일반적인 UI 및 상호작용 패턴을 위한 재사용 가능한 React 19 훅 모음입니다. TypeScript와 Vite로 빌드되었으며, 서버 사이드 렌더링과 클라이언트 사이드 애플리케이션 모두에 최적화되어 있습니다.
+
+## 기능
+
+- 📦 **10개 프로덕션 레디 훅** - 스크롤, 뷰포트, 스토리지 등 다양한 유틸리티
+- 🎯 **TypeScript 지원** - 완전한 타입 지원으로 더 나은 개발 경험
+- ⚡ **트리 셰이킹 지원** - 필요한 것만 임포트하세요
+- 🔒 **SSR 안전** - window/document 전역 변수에 대한 보호
+- 📱 **iOS 최적화** - 모바일 뷰포트 특성에 대한 특별 처리
+- 🧹 **완벽한 정리** - 모든 리스너와 옵저버가 정리됩니다
+
+## 설치
+
+```bash
+npm install @jbpark/use-hooks
+```
+
+## 사용 방법
+
+```tsx
+import {
+  useElementSize,
+  useLocalStorage,
+  useWindowScroll,
+} from '@jbpark/use-hooks';
+
+function MyComponent() {
+  // localStorage를 사용한 영속적 상태
+  const [count, setCount] = useLocalStorage('count', 0);
+
+  // 윈도우 스크롤 위치 추적
+  const { y, percent } = useWindowScroll();
+
+  // 브레이크포인트를 포함한 요소 크기 모니터링
+  const { size, breakpoint, ref } = useElementSize();
+
+  return (
+    <div ref={ref}>
+      <p>Count: {count}</p>
+      <p>Scroll: {percent.y}%</p>
+      <p>Breakpoint: {breakpoint.current}</p>
+      <button onClick={() => setCount(count + 1)}>+</button>
+    </div>
+  );
+}
+```
+
+## 사용 가능한 훅
+
+| 훅                    | 설명                                                            |
+| --------------------- | --------------------------------------------------------------- |
+| `useLocalStorage`     | 에러 핸들링이 포함된 JSON 기반 영속 상태 (SSR 안전)             |
+| `useWindowScroll`     | 윈도우 스크롤 위치 및 백분율 추적 (iOS visualViewport 대응)     |
+| `useScrollPosition`   | ResizeObserver를 사용한 특정 요소의 스크롤 상태 추적            |
+| `useElementRect`      | 스크롤/리사이즈 시 요소의 바운딩 렉트 모니터링 (요소 참조 지원) |
+| `useElementSize`      | Tailwind 유사 브레이크포인트를 포함한 요소 크기 추적 (debounce) |
+| `useBodyScrollLock`   | 스타일 보존을 포함한 바디 스크롤 잠금/해제 (iOS 특별 처리)      |
+| `useScrollToElements` | 인덱스별로 특정 요소로 스크롤 (오프셋 조절 가능)                |
+| `useImageLoader`      | 이미지 사전로드 및 로딩/에러 상태 노출                          |
+| `useRecursiveTimeout` | 비동기/동기 콜백을 재귀적으로 스케줄링                          |
+| `useViewport`         | visualViewport 지원, 인앱 모드 옵션, debounce 포함              |
+
+## 개발
+
+```bash
+# HMR이 포함된 개발 서버 시작
+npm run dev
+
+# 라이브러리 빌드 (tsc + vite)
+npm run build
+
+# 빌드된 라이브러리 미리보기
+npm run preview
+
+# 린트 및 타입 체크
+npm run lint
+
+# prettier로 포맷팅
+npx prettier --write .
+```
+
+## 프로젝트 구조
+
+```
+src/
+├── hooks/                      # 개별 훅 구현
+│   ├── useBodyScrollLock/
+│   ├── useElementRect/
+│   ├── useElementSize/
+│   ├── useImageLoader/
+│   ├── useLocalStorage/
+│   ├── useRecursiveTimeout/
+│   ├── useScrollPosition/
+│   ├── useScrollToElements/
+│   ├── useViewport/
+│   ├── useWindowScroll/
+│   └── index.ts                # 배럴 익스포트
+└── index.ts                    # 패키지 진입점
+
+dist/                            # 빌드된 라이브러리 (ES + CJS + types)
+.changeset/                      # 버저닝을 위한 Changesets
+```
+
+## 빌드 및 배포
+
+이 프로젝트는 버전 관리를 위해 Changesets를 사용합니다:
+
+```bash
+# 변경사항 기록
+npx changeset
+
+# 버전 업데이트 및 CHANGELOG 생성
+npx changeset version
+
+# npm에 배포
+npx changeset publish
+
+# 태그 푸시
+git push --follow-tags
+```
+
+라이브러리는 다음과 같이 빌드됩니다:
+
+- **ES Module**: `dist/index.js`
+- **CommonJS**: `dist/index.cjs`
+- **타입 정의**: `dist/index.d.ts`
+
+## 주요 패턴
+
+- **Window 보호**: `window`/`document`에 접근하는 훅은 SSR 안전성을 위해 `typeof window` 체크 (예: `useLocalStorage`)
+- **이벤트 리스너**: 모든 스크롤/리사이즈 리스너는 가능한 한 passive 플래그 사용
+- **ResizeObserver**: `useElementSize`와 `useScrollPosition`에서 사용하여 성능 최적화
+- **requestAnimationFrame**: 스크롤/리사이즈 콜백에서 레이아웃 스래싱 방지
+- **iOS 대응**: `useBodyScrollLock`, `useWindowScroll`, `useViewport`에서 iOS의 visualViewport 특성 처리
+- **Debounce**: `useElementSize`와 `useViewport`에서 리사이즈 이벤트 디바운싱 지원
+
+## 브라우저 지원
+
+- 최신 브라우저 (Chrome, Firefox, Safari, Edge)
+- iOS 12+ (특수한 `visualViewport` 처리 포함)
+- SSR 준비 완료 (적절한 보호 포함)
+
+## 기여하기
+
+버그 리포트, 기능 제안, 또는 코드 기여를 환영합니다!
+
+- 🐛 **버그 리포트**: [Issues](https://github.com/pjb0811/use-hooks/issues)에서 버그를 리포트해주세요
+- 💡 **기능 제안**: 새로운 기능 아이디어가 있으시면 [Issues](https://github.com/pjb0811/use-hooks/issues)에 제안해주세요
+- 🔧 **코드 기여**: Pull Request를 보내주시면 검토 후 반영하겠습니다
+
+이슈를 생성하기 전에 기존 이슈를 확인해주시면 중복을 방지할 수 있습니다.
+
+## 라이선스
+
+MIT

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("react"),E=(e,{delay:o,autoInvoke:d=!0},t=[])=>{const r=n.useRef(null),c=n.useRef(e),i=n.useRef(t);n.useEffect(()=>{c.current=e}),n.useEffect(()=>{i.current=t});const l=n.useRef(null);l.current||(l.current=((...u)=>{r.current&&clearTimeout(r.current),r.current=setTimeout(()=>{c.current(...u)},o)}));const s=n.useRef(t);return n.useEffect(()=>{const u=!s.current||s.current.length!==t.length||s.current.some((a,w)=>a!==t[w]);u&&r.current&&clearTimeout(r.current),d&&u&&l.current&&l.current(),s.current=t}),n.useEffect(()=>()=>{r.current&&clearTimeout(r.current)},[]),l.current},S=(e=!0)=>{n.useEffect(()=>{if(!e)return;const o=window.scrollY,d=/iPad|iPhone|iPod/.test(navigator.userAgent),t={documentElement:{overflow:document.documentElement.style.overflow,height:document.documentElement.style.height,position:document.documentElement.style.position,width:document.documentElement.style.width},body:{overflow:document.body.style.overflow,height:document.body.style.height,position:document.body.style.position,top:document.body.style.top,left:document.body.style.left,right:document.body.style.right,width:document.body.style.width,webkitOverflowScrolling:document.body.style.getPropertyValue("-webkit-overflow-scrolling")}};if(document.documentElement.style.overflow="hidden",document.documentElement.style.height="100%",document.documentElement.style.position="fixed",document.documentElement.style.width="100%",document.body.style.overflow="hidden",document.body.style.height="100%",document.body.style.position="fixed",document.body.style.top=`-${o}px`,document.body.style.left="0",document.body.style.right="0",document.body.style.width="100%",d){document.body.style.setProperty("-webkit-overflow-scrolling","touch");const r=s=>{(s.target===document.body||s.target===document.documentElement||s.target===window)&&(s.preventDefault(),s.stopPropagation(),s.stopImmediatePropagation())},c=()=>{window.scrollTo(0,0),document.body.scrollTop=0,document.documentElement.scrollTop=0},i=["scroll","touchmove","touchstart","touchend"];i.forEach(s=>{window.addEventListener(s,r,{passive:!1,capture:!0}),document.addEventListener(s,r,{passive:!1,capture:!0}),document.body.addEventListener(s,r,{passive:!1,capture:!0})});const l=setInterval(c,16);return()=>{clearInterval(l),i.forEach(s=>{window.removeEventListener(s,r,{capture:!0}),document.removeEventListener(s,r,{capture:!0}),document.body.removeEventListener(s,r,{capture:!0})}),document.documentElement.style.overflow=t.documentElement.overflow,document.documentElement.style.height=t.documentElement.height,document.documentElement.style.position=t.documentElement.position,document.documentElement.style.width=t.documentElement.width,document.body.style.overflow=t.body.overflow,document.body.style.height=t.body.height,document.body.style.position=t.body.position,document.body.style.top=t.body.top,document.body.style.left=t.body.left,document.body.style.right=t.body.right,document.body.style.width=t.body.width,t.body.webkitOverflowScrolling?document.body.style.setProperty("-webkit-overflow-scrolling",t.body.webkitOverflowScrolling):document.body.style.removeProperty("-webkit-overflow-scrolling"),window.scrollTo(0,o)}}return()=>{document.documentElement.style.overflow=t.documentElement.overflow,document.documentElement.style.height=t.documentElement.height,document.documentElement.style.position=t.documentElement.position,document.documentElement.style.width=t.documentElement.width,document.body.style.overflow=t.body.overflow,document.body.style.height=t.body.height,document.body.style.position=t.body.position,document.body.style.top=t.body.top,document.body.style.left=t.body.left,document.body.style.right=t.body.right,document.body.style.width=t.body.width,window.scrollTo(0,o)}},[e])},L=e=>{const[o,d]=n.useState(null);return n.useEffect(()=>{const t=i=>typeof i=="string"?document.querySelector(i):i.current,r=()=>{const i=t(e);d(i?i.getBoundingClientRect():null)},c=()=>{requestAnimationFrame(r)};return r(),window.addEventListener("scroll",c,{passive:!0}),window.addEventListener("resize",c,{passive:!0}),()=>{window.removeEventListener("scroll",c),window.removeEventListener("resize",c)}},[e]),o},T=()=>{const[e,o]=n.useState(null),[d,t]=n.useState({scrollY:0,scrollPercentage:0,isAtTop:!0,isAtBottom:!1,scrollableHeight:0,clientHeight:0,scrollHeight:0}),r=n.useCallback(c=>{o(c)},[]);return n.useEffect(()=>{if(!e)return;const c=()=>{const{scrollTop:s,scrollHeight:u,clientHeight:a}=e,w=u-a;if(w<=0){t({scrollY:0,scrollPercentage:0,isAtTop:!0,isAtBottom:!0,scrollableHeight:0,clientHeight:a,scrollHeight:u});return}const m=Math.min(100,Math.max(0,s/w*100));t({scrollY:s,scrollPercentage:m,isAtTop:s<=0,isAtBottom:s>=w-1,scrollableHeight:w,clientHeight:a,scrollHeight:u})};c();const i=()=>{c()};e.addEventListener("scroll",i,{passive:!0});const l=new ResizeObserver(()=>{c()});return l.observe(e),()=>{e.removeEventListener("scroll",i),l.unobserve(e)}},[e]),{...d,element:e,setRef:r}},f={sm:640,md:768,lg:1024,xl:1280,"2xl":1536},x=e=>{let o="xs";return e>=f["2xl"]?o="2xl":e>=f.xl?o="xl":e>=f.lg?o="lg":e>=f.md?o="md":e>=f.sm?o="sm":o="xs",{current:o,xs:e<f.sm,sm:e>=f.sm&&e<f.md,md:e>=f.md&&e<f.lg,lg:e>=f.lg&&e<f.xl,xl:e>=f.xl&&e<f["2xl"],"2xl":e>=f["2xl"]}},V=e=>{const{delay:o=100,container:d}=e||{},[t,r]=n.useState({width:0,height:0}),[c,i]=n.useState({current:"xs",xs:!0,sm:!1,md:!1,lg:!1,xl:!1,"2xl":!1}),[l,s]=n.useState({width:0,height:0}),u=n.useRef(null),a=n.useRef(null);return E(()=>{s(t)},{delay:o},[t]),n.useEffect(()=>{const w=()=>{const h=d??u.current??document.body;if(!h)return;const{offsetWidth:y,offsetHeight:v}=h;r(p=>p.width!==y||p.height!==v?{width:y,height:v}:p),i(p=>{const b=x(y);return p.current!==b.current?b:p})},m=()=>{const h=d??u.current??document.body;h&&(w(),a.current&&a.current.disconnect(),a.current=new ResizeObserver(()=>{requestAnimationFrame(()=>{w()})}),a.current.observe(h))},g=()=>{a.current&&(a.current.disconnect(),a.current=null)};return m(),()=>{g()}},[d]),{size:l,breakpoint:c,ref:u}},R=(e,o={})=>{const{retryCount:d=0,retryDelay:t=1e3}=o,[r,c]=n.useState(!0),[i,l]=n.useState(null),[s,u]=n.useState(!1),[a,w]=n.useState(0),m=n.useCallback(()=>{if(!e){c(!1),u(!1);return}c(!0),l(null);const h=new Image;h.src=e,h.onload=()=>{c(!1),u(!0),l(null),w(0)},h.onerror=y=>{c(!1),u(!1),l(y),a<d&&setTimeout(()=>{w(v=>v+1)},t)}},[e,a,d,t]);n.useEffect(()=>{m()},[m]);const g=n.useCallback(()=>{w(0),m()},[m]);return{loading:r,error:i,loaded:s,retry:g}},z=(e,o)=>{const d=n.useRef(o),[t,r]=n.useState(()=>{if(typeof window>"u")return o;try{const i=window.localStorage.getItem(e);return i?JSON.parse(i):o}catch{return o}});n.useEffect(()=>{if(!(typeof window>"u"))try{const i=window.localStorage.getItem(e);i?r(JSON.parse(i)):window.localStorage.setItem(e,JSON.stringify(d.current))}catch(i){console.error(`Error reading localStorage key "${e}":`,i)}},[e]);const c=n.useCallback(i=>{try{r(l=>{const s=i instanceof Function?i(l):i;return localStorage.setItem(e,JSON.stringify(s)),s})}catch(l){console.error(`Error setting localStorage key "${e}":`,l)}},[e]);return[t,c]},P=(e,o)=>{const d=n.useRef(e);n.useEffect(()=>{d.current=e},[e]),n.useEffect(()=>{let t;function r(){const c=d.current();c instanceof Promise?c.then(()=>{o&&(t=setTimeout(r,o))}):o&&(t=setTimeout(r,o))}if(o)return t=setTimeout(r,o),()=>t&&clearTimeout(t)},[o])},H=e=>{const o=n.useRef([]),d=n.useCallback(r=>{if(o.current[r]&&(o.current[r].scrollIntoView({behavior:"smooth",block:"start",inline:"start",...e}),e?.offset)){const c=o.current[r].getBoundingClientRect().top+window.scrollY-e.offset;window.scrollTo({top:c,behavior:e.behavior||"smooth"})}},[e]),t=n.useCallback((r,c)=>{o.current[c]=r},[]);return{elementRefs:o,setElementRef:t,scrollToElement:d}},I=()=>{const[e,o]=n.useState({x:0,y:0,percent:{x:0,y:0}});return n.useEffect(()=>{const d=()=>{const i=window.scrollX||0,l=window.scrollY||0,s=/iPad|iPhone|iPod/.test(navigator.userAgent),u=window.visualViewport,a=s&&u?u.width:window.innerWidth,w=s&&u?u.height:window.innerHeight,m=Math.max(0,document.documentElement.scrollWidth-a),g=Math.max(0,document.documentElement.scrollHeight-w),h=m===0?0:Math.min(100,i/m*100),y=g===0?0:Math.min(100,l/g*100);o({x:i,y:l,percent:{x:Math.floor(Math.max(0,h)),y:Math.floor(Math.max(0,y))}})};d();const t=()=>{d()},r=()=>{setTimeout(d,100)},c=()=>{setTimeout(d,50)};return window.addEventListener("scroll",t,{passive:!0}),window.addEventListener("resize",r),window.addEventListener("orientationchange",r),window.visualViewport&&window.visualViewport.addEventListener("resize",c),()=>{window.removeEventListener("scroll",t),window.removeEventListener("resize",r),window.removeEventListener("orientationchange",r),window.visualViewport&&window.visualViewport.removeEventListener("resize",c)}},[]),e},k=(e={})=>{const{isInApp:o=!1,debounce:d=100}=e,[t,r]=n.useState({width:0,height:0,offsetLeft:0,offsetTop:0,pageLeft:0,pageTop:0,scale:1}),c=n.useCallback(()=>{const l=window.innerHeight,s=window.visualViewport?.height||l,u=document.documentElement.clientHeight,a=document.body.clientHeight;return window.visualViewport&&Math.abs(s-l)>100?s:Math.max(l,u,a)},[]),i=n.useCallback(()=>{if(window.visualViewport&&!o)return window.visualViewport;const l=window.visualViewport?.width||window.innerWidth,s=o?c():window.visualViewport?.height||window.innerHeight;return{width:l,height:s,offsetLeft:window.visualViewport?.offsetLeft||0,offsetTop:window.visualViewport?.offsetTop||0,pageLeft:window.scrollX??window.pageXOffset??0,pageTop:window.scrollY??window.pageYOffset??0,scale:window.visualViewport?.scale||1}},[o,c]);return n.useEffect(()=>{let l;const s=()=>{clearTimeout(l),l=setTimeout(()=>{r(i())},d)},u=()=>r(i());u();const a=["resize","orientationchange"];o&&a.push("focus","blur","touchstart","touchend"),a.forEach(m=>{m==="resize"||m==="orientationchange"?window.addEventListener(m,s):window.addEventListener(m,u,{passive:!0})}),window.visualViewport&&(window.visualViewport.addEventListener("resize",u),window.visualViewport.addEventListener("scroll",u));let w;if(o){let m=i().height;w=setInterval(()=>{const g=i().height;Math.abs(g-m)>50&&(m=g,u())},500)}return()=>{clearTimeout(l),w&&clearInterval(w),a.forEach(m=>{window.removeEventListener(m,m==="resize"||m==="orientationchange"?s:u)}),window.visualViewport&&(window.visualViewport.removeEventListener("resize",u),window.visualViewport.removeEventListener("scroll",u))}},[i,o,d]),t};exports.useBodyScrollLock=S;exports.useDebounce=E;exports.useElementPosition=L;exports.useElementScroll=T;exports.useImage=R;exports.useLocalStorage=z;exports.useRecursiveTimeout=P;exports.useResponsiveSize=V;exports.useScrollToElements=H;exports.useViewport=k;exports.useWindowScroll=I;

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+import { RefObject } from 'react';
+
+declare type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+declare interface BreakpointInfo {
+    current: Breakpoint;
+    xs: boolean;
+    sm: boolean;
+    md: boolean;
+    lg: boolean;
+    xl: boolean;
+    '2xl': boolean;
+}
+
+declare type ElementReference<T> = string | RefObject<T>;
+
+declare interface Options {
+    delay: number;
+    autoInvoke?: boolean;
+}
+
+declare interface Options_2 {
+    delay?: number;
+    container?: HTMLElement | null;
+}
+
+declare interface Options_3 {
+    retryCount?: number;
+    retryDelay?: number;
+}
+
+declare interface Options_4 extends ScrollIntoViewOptions {
+    offset?: number;
+}
+
+declare interface Options_5 {
+    isInApp?: boolean;
+    debounce?: number;
+}
+
+export declare const useBodyScrollLock: (enabled?: boolean) => void;
+
+export declare const useDebounce: <T extends (...args: unknown[]) => unknown>(callback: T, { delay, autoInvoke }: Options, deps?: React.DependencyList) => T;
+
+export declare const useElementPosition: <T>(elementRef: ElementReference<T>) => DOMRect | null;
+
+export declare const useElementScroll: () => {
+    element: HTMLElement | null;
+    setRef: (el: HTMLElement | null) => void;
+    scrollY: number;
+    scrollPercentage: number;
+    isAtTop: boolean;
+    isAtBottom: boolean;
+    scrollableHeight: number;
+    clientHeight: number;
+    scrollHeight: number;
+};
+
+export declare const useImage: (src: string, options?: Options_3) => {
+    loading: boolean;
+    error: string | Event | null;
+    loaded: boolean;
+    retry: () => void;
+};
+
+export declare const useLocalStorage: <T>(key: string, initialValue: T) => readonly [T, (value: T | ((val: T) => T)) => void];
+
+export declare const useRecursiveTimeout: <T>(callback: () => Promise<T> | (() => void), delay: number | null) => void;
+
+export declare const useResponsiveSize: <T extends HTMLElement>(options?: Options_2) => {
+    size: {
+        width: number;
+        height: number;
+    };
+    breakpoint: BreakpointInfo;
+    ref: RefObject<T | null>;
+};
+
+export declare const useScrollToElements: (options?: Options_4) => {
+    elementRefs: RefObject<HTMLElement[]>;
+    setElementRef: (element: HTMLElement, index: number) => void;
+    scrollToElement: (index: number) => void;
+};
+
+export declare const useViewport: (options?: Options_5) => ViewportInfo;
+
+export declare const useWindowScroll: () => {
+    x: number;
+    y: number;
+    percent: {
+        x: number;
+        y: number;
+    };
+};
+
+declare type ViewportInfo = VisualViewport | {
+    width: number;
+    height: number;
+    offsetLeft: number;
+    offsetTop: number;
+    pageLeft: number;
+    pageTop: number;
+    scale: number;
+};
+
+export { }

package/dist/index.js

@@ -0,0 +1,424 @@
+import { useRef as y, useEffect as f, useState as h, useCallback as v } from "react";
+const x = (e, { delay: o, autoInvoke: u = !0 }, t = []) => {
+  const n = y(null), i = y(e), s = y(t);
+  f(() => {
+    i.current = e;
+  }), f(() => {
+    s.current = t;
+  });
+  const l = y(null);
+  l.current || (l.current = ((...c) => {
+    n.current && clearTimeout(n.current), n.current = setTimeout(() => {
+      i.current(...c);
+    }, o);
+  }));
+  const r = y(t);
+  return f(() => {
+    const c = !r.current || r.current.length !== t.length || r.current.some((d, a) => d !== t[a]);
+    c && n.current && clearTimeout(n.current), u && c && l.current && l.current(), r.current = t;
+  }), f(() => () => {
+    n.current && clearTimeout(n.current);
+  }, []), l.current;
+}, z = (e = !0) => {
+  f(() => {
+    if (!e)
+      return;
+    const o = window.scrollY, u = /iPad|iPhone|iPod/.test(navigator.userAgent), t = {
+      documentElement: {
+        overflow: document.documentElement.style.overflow,
+        height: document.documentElement.style.height,
+        position: document.documentElement.style.position,
+        width: document.documentElement.style.width
+      },
+      body: {
+        overflow: document.body.style.overflow,
+        height: document.body.style.height,
+        position: document.body.style.position,
+        top: document.body.style.top,
+        left: document.body.style.left,
+        right: document.body.style.right,
+        width: document.body.style.width,
+        webkitOverflowScrolling: document.body.style.getPropertyValue(
+          "-webkit-overflow-scrolling"
+        )
+      }
+    };
+    if (document.documentElement.style.overflow = "hidden", document.documentElement.style.height = "100%", document.documentElement.style.position = "fixed", document.documentElement.style.width = "100%", document.body.style.overflow = "hidden", document.body.style.height = "100%", document.body.style.position = "fixed", document.body.style.top = `-${o}px`, document.body.style.left = "0", document.body.style.right = "0", document.body.style.width = "100%", u) {
+      document.body.style.setProperty("-webkit-overflow-scrolling", "touch");
+      const n = (r) => {
+        (r.target === document.body || r.target === document.documentElement || r.target === window) && (r.preventDefault(), r.stopPropagation(), r.stopImmediatePropagation());
+      }, i = () => {
+        window.scrollTo(0, 0), document.body.scrollTop = 0, document.documentElement.scrollTop = 0;
+      }, s = ["scroll", "touchmove", "touchstart", "touchend"];
+      s.forEach((r) => {
+        window.addEventListener(r, n, {
+          passive: !1,
+          capture: !0
+        }), document.addEventListener(r, n, {
+          passive: !1,
+          capture: !0
+        }), document.body.addEventListener(r, n, {
+          passive: !1,
+          capture: !0
+        });
+      });
+      const l = setInterval(i, 16);
+      return () => {
+        clearInterval(l), s.forEach((r) => {
+          window.removeEventListener(r, n, { capture: !0 }), document.removeEventListener(r, n, { capture: !0 }), document.body.removeEventListener(r, n, {
+            capture: !0
+          });
+        }), document.documentElement.style.overflow = t.documentElement.overflow, document.documentElement.style.height = t.documentElement.height, document.documentElement.style.position = t.documentElement.position, document.documentElement.style.width = t.documentElement.width, document.body.style.overflow = t.body.overflow, document.body.style.height = t.body.height, document.body.style.position = t.body.position, document.body.style.top = t.body.top, document.body.style.left = t.body.left, document.body.style.right = t.body.right, document.body.style.width = t.body.width, t.body.webkitOverflowScrolling ? document.body.style.setProperty(
+          "-webkit-overflow-scrolling",
+          t.body.webkitOverflowScrolling
+        ) : document.body.style.removeProperty("-webkit-overflow-scrolling"), window.scrollTo(0, o);
+      };
+    }
+    return () => {
+      document.documentElement.style.overflow = t.documentElement.overflow, document.documentElement.style.height = t.documentElement.height, document.documentElement.style.position = t.documentElement.position, document.documentElement.style.width = t.documentElement.width, document.body.style.overflow = t.body.overflow, document.body.style.height = t.body.height, document.body.style.position = t.body.position, document.body.style.top = t.body.top, document.body.style.left = t.body.left, document.body.style.right = t.body.right, document.body.style.width = t.body.width, window.scrollTo(0, o);
+    };
+  }, [e]);
+}, H = (e) => {
+  const [o, u] = h(null);
+  return f(() => {
+    const t = (s) => typeof s == "string" ? document.querySelector(s) : s.current, n = () => {
+      const s = t(e);
+      u(s ? s.getBoundingClientRect() : null);
+    }, i = () => {
+      requestAnimationFrame(n);
+    };
+    return n(), window.addEventListener("scroll", i, { passive: !0 }), window.addEventListener("resize", i, { passive: !0 }), () => {
+      window.removeEventListener("scroll", i), window.removeEventListener("resize", i);
+    };
+  }, [e]), o;
+}, I = () => {
+  const [e, o] = h(null), [u, t] = h({
+    scrollY: 0,
+    scrollPercentage: 0,
+    isAtTop: !0,
+    isAtBottom: !1,
+    scrollableHeight: 0,
+    clientHeight: 0,
+    scrollHeight: 0
+  }), n = v((i) => {
+    o(i);
+  }, []);
+  return f(() => {
+    if (!e)
+      return;
+    const i = () => {
+      const { scrollTop: r, scrollHeight: c, clientHeight: d } = e, a = c - d;
+      if (a <= 0) {
+        t({
+          scrollY: 0,
+          scrollPercentage: 0,
+          isAtTop: !0,
+          isAtBottom: !0,
+          scrollableHeight: 0,
+          clientHeight: d,
+          scrollHeight: c
+        });
+        return;
+      }
+      const m = Math.min(
+        100,
+        Math.max(0, r / a * 100)
+      );
+      t({
+        scrollY: r,
+        scrollPercentage: m,
+        isAtTop: r <= 0,
+        isAtBottom: r >= a - 1,
+        scrollableHeight: a,
+        clientHeight: d,
+        scrollHeight: c
+      });
+    };
+    i();
+    const s = () => {
+      i();
+    };
+    e.addEventListener("scroll", s, { passive: !0 });
+    const l = new ResizeObserver(() => {
+      i();
+    });
+    return l.observe(e), () => {
+      e.removeEventListener("scroll", s), l.unobserve(e);
+    };
+  }, [e]), { ...u, element: e, setRef: n };
+}, w = {
+  // < 640px
+  sm: 640,
+  // >= 640px
+  md: 768,
+  // >= 768px
+  lg: 1024,
+  // >= 1024px
+  xl: 1280,
+  // >= 1280px
+  "2xl": 1536
+  // >= 1536px
+}, T = (e) => {
+  let o = "xs";
+  return e >= w["2xl"] ? o = "2xl" : e >= w.xl ? o = "xl" : e >= w.lg ? o = "lg" : e >= w.md ? o = "md" : e >= w.sm ? o = "sm" : o = "xs", {
+    current: o,
+    xs: e < w.sm,
+    sm: e >= w.sm && e < w.md,
+    md: e >= w.md && e < w.lg,
+    lg: e >= w.lg && e < w.xl,
+    xl: e >= w.xl && e < w["2xl"],
+    "2xl": e >= w["2xl"]
+  };
+}, P = (e) => {
+  const { delay: o = 100, container: u } = e || {}, [t, n] = h({ width: 0, height: 0 }), [i, s] = h({
+    current: "xs",
+    xs: !0,
+    sm: !1,
+    md: !1,
+    lg: !1,
+    xl: !1,
+    "2xl": !1
+  }), [l, r] = h({ width: 0, height: 0 }), c = y(null), d = y(null);
+  return x(
+    () => {
+      r(t);
+    },
+    { delay: o },
+    [t]
+  ), f(() => {
+    const a = () => {
+      const g = u ?? c.current ?? document.body;
+      if (!g)
+        return;
+      const { offsetWidth: b, offsetHeight: S } = g;
+      n((E) => E.width !== b || E.height !== S ? { width: b, height: S } : E), s((E) => {
+        const L = T(b);
+        return E.current !== L.current ? L : E;
+      });
+    }, m = () => {
+      const g = u ?? c.current ?? document.body;
+      g && (a(), d.current && d.current.disconnect(), d.current = new ResizeObserver(() => {
+        requestAnimationFrame(() => {
+          a();
+        });
+      }), d.current.observe(g));
+    }, p = () => {
+      d.current && (d.current.disconnect(), d.current = null);
+    };
+    return m(), () => {
+      p();
+    };
+  }, [u]), {
+    size: l,
+    breakpoint: i,
+    ref: c
+  };
+}, R = (e, o = {}) => {
+  const { retryCount: u = 0, retryDelay: t = 1e3 } = o, [n, i] = h(!0), [s, l] = h(null), [r, c] = h(!1), [d, a] = h(0), m = v(() => {
+    if (!e) {
+      i(!1), c(!1);
+      return;
+    }
+    i(!0), l(null);
+    const g = new Image();
+    g.src = e, g.onload = () => {
+      i(!1), c(!0), l(null), a(0);
+    }, g.onerror = (b) => {
+      i(!1), c(!1), l(b), d < u && setTimeout(() => {
+        a((S) => S + 1);
+      }, t);
+    };
+  }, [e, d, u, t]);
+  f(() => {
+    m();
+  }, [m]);
+  const p = v(() => {
+    a(0), m();
+  }, [m]);
+  return {
+    loading: n,
+    error: s,
+    loaded: r,
+    retry: p
+  };
+}, A = (e, o) => {
+  const u = y(o), [t, n] = h(() => {
+    if (typeof window > "u")
+      return o;
+    try {
+      const s = window.localStorage.getItem(e);
+      return s ? JSON.parse(s) : o;
+    } catch {
+      return o;
+    }
+  });
+  f(() => {
+    if (!(typeof window > "u"))
+      try {
+        const s = window.localStorage.getItem(e);
+        s ? n(JSON.parse(s)) : window.localStorage.setItem(e, JSON.stringify(u.current));
+      } catch (s) {
+        console.error(`Error reading localStorage key "${e}":`, s);
+      }
+  }, [e]);
+  const i = v(
+    (s) => {
+      try {
+        n((l) => {
+          const r = s instanceof Function ? s(l) : s;
+          return localStorage.setItem(e, JSON.stringify(r)), r;
+        });
+      } catch (l) {
+        console.error(`Error setting localStorage key "${e}":`, l);
+      }
+    },
+    [e]
+  );
+  return [t, i];
+}, O = (e, o) => {
+  const u = y(e);
+  f(() => {
+    u.current = e;
+  }, [e]), f(() => {
+    let t;
+    function n() {
+      const i = u.current();
+      i instanceof Promise ? i.then(() => {
+        o && (t = setTimeout(n, o));
+      }) : o && (t = setTimeout(n, o));
+    }
+    if (o)
+      return t = setTimeout(n, o), () => t && clearTimeout(t);
+  }, [o]);
+}, M = (e) => {
+  const o = y([]), u = v(
+    (n) => {
+      if (o.current[n] && (o.current[n].scrollIntoView({
+        behavior: "smooth",
+        block: "start",
+        inline: "start",
+        ...e
+      }), e?.offset)) {
+        const i = o.current[n].getBoundingClientRect().top + window.scrollY - e.offset;
+        window.scrollTo({
+          top: i,
+          behavior: e.behavior || "smooth"
+        });
+      }
+    },
+    [e]
+  ), t = v((n, i) => {
+    o.current[i] = n;
+  }, []);
+  return { elementRefs: o, setElementRef: t, scrollToElement: u };
+}, Y = () => {
+  const [e, o] = h({
+    x: 0,
+    y: 0,
+    percent: {
+      x: 0,
+      y: 0
+    }
+  });
+  return f(() => {
+    const u = () => {
+      const s = window.scrollX || 0, l = window.scrollY || 0, r = /iPad|iPhone|iPod/.test(navigator.userAgent), c = window.visualViewport, d = r && c ? c.width : window.innerWidth, a = r && c ? c.height : window.innerHeight, m = Math.max(
+        0,
+        document.documentElement.scrollWidth - d
+      ), p = Math.max(
+        0,
+        document.documentElement.scrollHeight - a
+      ), g = m === 0 ? 0 : Math.min(100, s / m * 100), b = p === 0 ? 0 : Math.min(100, l / p * 100);
+      o({
+        x: s,
+        y: l,
+        percent: {
+          x: Math.floor(Math.max(0, g)),
+          y: Math.floor(Math.max(0, b))
+        }
+      });
+    };
+    u();
+    const t = () => {
+      u();
+    }, n = () => {
+      setTimeout(u, 100);
+    }, i = () => {
+      setTimeout(u, 50);
+    };
+    return window.addEventListener("scroll", t, { passive: !0 }), window.addEventListener("resize", n), window.addEventListener("orientationchange", n), window.visualViewport && window.visualViewport.addEventListener("resize", i), () => {
+      window.removeEventListener("scroll", t), window.removeEventListener("resize", n), window.removeEventListener("orientationchange", n), window.visualViewport && window.visualViewport.removeEventListener(
+        "resize",
+        i
+      );
+    };
+  }, []), e;
+}, C = (e = {}) => {
+  const { isInApp: o = !1, debounce: u = 100 } = e, [t, n] = h({
+    width: 0,
+    height: 0,
+    offsetLeft: 0,
+    offsetTop: 0,
+    pageLeft: 0,
+    pageTop: 0,
+    scale: 1
+  }), i = v(() => {
+    const l = window.innerHeight, r = window.visualViewport?.height || l, c = document.documentElement.clientHeight, d = document.body.clientHeight;
+    return window.visualViewport && Math.abs(r - l) > 100 ? r : Math.max(l, c, d);
+  }, []), s = v(() => {
+    if (window.visualViewport && !o)
+      return window.visualViewport;
+    const l = window.visualViewport?.width || window.innerWidth, r = o ? i() : window.visualViewport?.height || window.innerHeight;
+    return {
+      width: l,
+      height: r,
+      offsetLeft: window.visualViewport?.offsetLeft || 0,
+      offsetTop: window.visualViewport?.offsetTop || 0,
+      pageLeft: window.scrollX ?? window.pageXOffset ?? 0,
+      pageTop: window.scrollY ?? window.pageYOffset ?? 0,
+      scale: window.visualViewport?.scale || 1
+    };
+  }, [o, i]);
+  return f(() => {
+    let l;
+    const r = () => {
+      clearTimeout(l), l = setTimeout(() => {
+        n(s());
+      }, u);
+    }, c = () => n(s());
+    c();
+    const d = ["resize", "orientationchange"];
+    o && d.push("focus", "blur", "touchstart", "touchend"), d.forEach((m) => {
+      m === "resize" || m === "orientationchange" ? window.addEventListener(m, r) : window.addEventListener(m, c, { passive: !0 });
+    }), window.visualViewport && (window.visualViewport.addEventListener("resize", c), window.visualViewport.addEventListener("scroll", c));
+    let a;
+    if (o) {
+      let m = s().height;
+      a = setInterval(() => {
+        const p = s().height;
+        Math.abs(p - m) > 50 && (m = p, c());
+      }, 500);
+    }
+    return () => {
+      clearTimeout(l), a && clearInterval(a), d.forEach((m) => {
+        window.removeEventListener(
+          m,
+          m === "resize" || m === "orientationchange" ? r : c
+        );
+      }), window.visualViewport && (window.visualViewport.removeEventListener("resize", c), window.visualViewport.removeEventListener("scroll", c));
+    };
+  }, [s, o, u]), t;
+};
+export {
+  z as useBodyScrollLock,
+  x as useDebounce,
+  H as useElementPosition,
+  I as useElementScroll,
+  R as useImage,
+  A as useLocalStorage,
+  O as useRecursiveTimeout,
+  P as useResponsiveSize,
+  M as useScrollToElements,
+  C as useViewport,
+  Y as useWindowScroll
+};

package/dist/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@jbpark/use-hooks",
+  "version": "1.1.1",
+  "description": "A collection of reusable React 19 hooks for common UI and interaction patterns",
+  "keywords": [
+    "react",
+    "hooks",
+    "typescript",
+    "react-hooks",
+    "utilities",
+    "custom-hooks"
+  ],
+  "author": "jbpark",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pjb0811/use-hooks.git"
+  },
+  "homepage": "https://github.com/pjb0811/use-hooks#readme",
+  "bugs": {
+    "url": "https://github.com/pjb0811/use-hooks/issues"
+  },
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@eslint/js": "^9.33.0",
+    "@trivago/prettier-plugin-sort-imports": "^5.2.2",
+    "@types/node": "^24.5.2",
+    "@types/react": "^19.1.10",
+    "@types/react-dom": "^19.1.7",
+    "@vitejs/plugin-react": "^5.0.0",
+    "eslint": "^9.33.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "globals": "^16.3.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.1.6",
+    "prettier": "^3.8.0",
+    "prettier-plugin-classnames": "^0.8.3",
+    "prettier-plugin-merge": "^0.8.0",
+    "prettier-plugin-tailwindcss": "^0.6.14",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.39.1",
+    "vite": "^7.1.2",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "lint-staged": {
+    "**/*.{js,jsx,ts,tsx,css,scss,md}": "prettier --write",
+    "**/*.{js,jsx,ts,tsx}": [
+      "bash -c 'pnpm lint'",
+      "bash -c 'tsc -b'"
+    ]
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  }
+}