@jbpark/use-hooks 1.0.0

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

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+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 Props extends ScrollIntoViewOptions {
+    offset?: number;
+}
+
+export declare const useBodyScrollLock: (enabled?: boolean) => void;
+
+export declare const useElementRect: <T>(elementRef: ElementReference<T>) => DOMRect | null;
+
+export declare const useElementSize: <T extends HTMLElement>(delay?: number) => {
+    size: {
+        width: number;
+        height: number;
+    };
+    breakpoint: BreakpointInfo;
+    ref: RefObject<T | null>;
+};
+
+export declare const useImageLoader: (src: string) => {
+    loading: boolean;
+    error: string | Event | undefined;
+};
+
+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 useScrollPosition: () => {
+    element: HTMLElement | null;
+    setRef: (el: HTMLElement | null) => void;
+    scrollY: number;
+    scrollPercentage: number;
+    isAtTop: boolean;
+    isAtBottom: boolean;
+    scrollableHeight: number;
+    clientHeight: number;
+    scrollHeight: number;
+};
+
+export declare function useScrollToElements(options?: Props): {
+    elementRefs: RefObject<HTMLElement[]>;
+    setElementRef: (element: HTMLElement, index: number) => void;
+    scrollToElement: (index: number) => void;
+};
+
+export declare const useViewport: (options?: UseViewportOptions) => ViewportInfo;
+
+declare interface UseViewportOptions {
+    isInApp?: boolean;
+    debounce?: number;
+}
+
+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,415 @@
+import { useEffect as w, useState as h, useRef as p, useCallback as v } from "react";
+const V = (e = !0) => {
+  w(() => {
+    if (!e)
+      return;
+    const t = window.scrollY, c = /iPad|iPhone|iPod/.test(navigator.userAgent), o = {
+      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 = `-${t}px`, document.body.style.left = "0", document.body.style.right = "0", document.body.style.width = "100%", c) {
+      document.body.style.setProperty("-webkit-overflow-scrolling", "touch");
+      const r = (i) => {
+        (i.target === document.body || i.target === document.documentElement || i.target === window) && (i.preventDefault(), i.stopPropagation(), i.stopImmediatePropagation());
+      }, s = () => {
+        window.scrollTo(0, 0), document.body.scrollTop = 0, document.documentElement.scrollTop = 0;
+      }, n = ["scroll", "touchmove", "touchstart", "touchend"];
+      n.forEach((i) => {
+        window.addEventListener(i, r, {
+          passive: !1,
+          capture: !0
+        }), document.addEventListener(i, r, {
+          passive: !1,
+          capture: !0
+        }), document.body.addEventListener(i, r, {
+          passive: !1,
+          capture: !0
+        });
+      });
+      const l = setInterval(s, 16);
+      return () => {
+        clearInterval(l), n.forEach((i) => {
+          window.removeEventListener(i, r, { capture: !0 }), document.removeEventListener(i, r, { capture: !0 }), document.body.removeEventListener(i, r, {
+            capture: !0
+          });
+        }), document.documentElement.style.overflow = o.documentElement.overflow, document.documentElement.style.height = o.documentElement.height, document.documentElement.style.position = o.documentElement.position, document.documentElement.style.width = o.documentElement.width, document.body.style.overflow = o.body.overflow, document.body.style.height = o.body.height, document.body.style.position = o.body.position, document.body.style.top = o.body.top, document.body.style.left = o.body.left, document.body.style.right = o.body.right, document.body.style.width = o.body.width, o.body.webkitOverflowScrolling ? document.body.style.setProperty(
+          "-webkit-overflow-scrolling",
+          o.body.webkitOverflowScrolling
+        ) : document.body.style.removeProperty("-webkit-overflow-scrolling"), window.scrollTo(0, t);
+      };
+    }
+    return () => {
+      document.documentElement.style.overflow = o.documentElement.overflow, document.documentElement.style.height = o.documentElement.height, document.documentElement.style.position = o.documentElement.position, document.documentElement.style.width = o.documentElement.width, document.body.style.overflow = o.body.overflow, document.body.style.height = o.body.height, document.body.style.position = o.body.position, document.body.style.top = o.body.top, document.body.style.left = o.body.left, document.body.style.right = o.body.right, document.body.style.width = o.body.width, window.scrollTo(0, t);
+    };
+  }, [e]);
+}, z = (e) => {
+  const [t, c] = h(null);
+  return w(() => {
+    const o = (n) => typeof n == "string" ? document.querySelector(n) : n.current, r = () => {
+      const n = o(e);
+      c(n ? n.getBoundingClientRect() : null);
+    }, s = () => {
+      requestAnimationFrame(r);
+    };
+    return r(), window.addEventListener("scroll", s, { passive: !0 }), window.addEventListener("resize", s, { passive: !0 }), () => {
+      window.removeEventListener("scroll", s), window.removeEventListener("resize", s);
+    };
+  }, [e]), t;
+};
+function S(e, t) {
+  t === void 0 && (t = 0);
+  var c = p(!1), o = p(), r = p(e), s = v(function() {
+    return c.current;
+  }, []), n = v(function() {
+    c.current = !1, o.current && clearTimeout(o.current), o.current = setTimeout(function() {
+      c.current = !0, r.current();
+    }, t);
+  }, [t]), l = v(function() {
+    c.current = null, o.current && clearTimeout(o.current);
+  }, []);
+  return w(function() {
+    r.current = e;
+  }, [e]), w(function() {
+    return n(), l;
+  }, [t]), [s, l, n];
+}
+function L(e, t, c) {
+  t === void 0 && (t = 0), c === void 0 && (c = []);
+  var o = S(e, t), r = o[0], s = o[1], n = o[2];
+  return w(n, c), [r, s];
+}
+const a = {
+  // < 640px
+  sm: 640,
+  // >= 640px
+  md: 768,
+  // >= 768px
+  lg: 1024,
+  // >= 1024px
+  xl: 1280,
+  // >= 1280px
+  "2xl": 1536
+  // >= 1536px
+}, x = (e) => {
+  let t = "xs";
+  return e >= a["2xl"] ? t = "2xl" : e >= a.xl ? t = "xl" : e >= a.lg ? t = "lg" : e >= a.md ? t = "md" : e >= a.sm ? t = "sm" : t = "xs", {
+    current: t,
+    xs: e < a.sm,
+    sm: e >= a.sm && e < a.md,
+    md: e >= a.md && e < a.lg,
+    lg: e >= a.lg && e < a.xl,
+    xl: e >= a.xl && e < a["2xl"],
+    "2xl": e >= a["2xl"]
+  };
+}, H = (e = 200) => {
+  const [t, c] = h({ width: 0, height: 0 }), [o, r] = h({
+    current: "xs",
+    xs: !0,
+    sm: !1,
+    md: !1,
+    lg: !1,
+    xl: !1,
+    "2xl": !1
+  }), [s, n] = h({ width: 0, height: 0 }), l = p(null), i = p(null);
+  return L(
+    () => {
+      n(t);
+    },
+    e,
+    [t]
+  ), w(() => {
+    const d = () => {
+      const u = l.current ?? document.body;
+      if (!u)
+        return;
+      const { offsetWidth: g, offsetHeight: b } = u;
+      c((y) => y.width !== g || y.height !== b ? { width: g, height: b } : y), r((y) => {
+        const E = x(g);
+        return y.current !== E.current ? E : y;
+      });
+    }, m = () => {
+      const u = l.current ?? document.body;
+      u && (d(), i.current && i.current.disconnect(), i.current = new ResizeObserver(() => {
+        requestAnimationFrame(() => {
+          d();
+        });
+      }), i.current.observe(u));
+    }, f = () => {
+      i.current && (i.current.disconnect(), i.current = null);
+    };
+    return m(), () => {
+      f();
+    };
+  }, []), {
+    size: s,
+    breakpoint: o,
+    ref: l
+  };
+}, P = (e) => {
+  const [t, c] = h(!0), [o, r] = h();
+  return w(() => {
+    if (!e) {
+      c(!1);
+      return;
+    }
+    const s = new Image();
+    s.src = e, s.onload = () => c(!1), s.onerror = (n) => {
+      c(!1), r(n);
+    };
+  }, [e]), {
+    loading: t,
+    error: o
+  };
+}, I = (e, t) => {
+  const c = p(t), [o, r] = h(() => {
+    if (typeof window > "u")
+      return t;
+    try {
+      const n = window.localStorage.getItem(e);
+      return n ? JSON.parse(n) : t;
+    } catch {
+      return t;
+    }
+  });
+  w(() => {
+    if (!(typeof window > "u"))
+      try {
+        const n = window.localStorage.getItem(e);
+        n ? r(JSON.parse(n)) : window.localStorage.setItem(e, JSON.stringify(c.current));
+      } catch (n) {
+        console.error(`Error reading localStorage key "${e}":`, n);
+      }
+  }, [e]);
+  const s = v(
+    (n) => {
+      try {
+        r((l) => {
+          const i = n instanceof Function ? n(l) : n;
+          return localStorage.setItem(e, JSON.stringify(i)), i;
+        });
+      } catch (l) {
+        console.error(`Error setting localStorage key "${e}":`, l);
+      }
+    },
+    [e]
+  );
+  return [o, s];
+}, R = (e, t) => {
+  const c = p(e);
+  w(() => {
+    c.current = e;
+  }, [e]), w(() => {
+    let o;
+    function r() {
+      const s = c.current();
+      s instanceof Promise ? s.then(() => {
+        t && (o = setTimeout(r, t));
+      }) : t && (o = setTimeout(r, t));
+    }
+    if (t)
+      return o = setTimeout(r, t), () => o && clearTimeout(o);
+  }, [t]);
+}, O = () => {
+  const [e, t] = h(null), [c, o] = h({
+    scrollY: 0,
+    scrollPercentage: 0,
+    isAtTop: !0,
+    isAtBottom: !1,
+    scrollableHeight: 0,
+    clientHeight: 0,
+    scrollHeight: 0
+  }), r = v((s) => {
+    t(s);
+  }, []);
+  return w(() => {
+    if (!e)
+      return;
+    const s = () => {
+      const { scrollTop: i, scrollHeight: d, clientHeight: m } = e, f = d - m;
+      if (f <= 0) {
+        o({
+          scrollY: 0,
+          scrollPercentage: 0,
+          isAtTop: !0,
+          isAtBottom: !0,
+          scrollableHeight: 0,
+          clientHeight: m,
+          scrollHeight: d
+        });
+        return;
+      }
+      const u = Math.min(
+        100,
+        Math.max(0, i / f * 100)
+      );
+      o({
+        scrollY: i,
+        scrollPercentage: u,
+        isAtTop: i <= 0,
+        isAtBottom: i >= f - 1,
+        scrollableHeight: f,
+        clientHeight: m,
+        scrollHeight: d
+      });
+    };
+    s();
+    const n = () => {
+      s();
+    };
+    e.addEventListener("scroll", n, { passive: !0 });
+    const l = new ResizeObserver(() => {
+      s();
+    });
+    return l.observe(e), () => {
+      e.removeEventListener("scroll", n), l.unobserve(e);
+    };
+  }, [e]), { ...c, element: e, setRef: r };
+};
+function A(e) {
+  const t = p([]), c = v(
+    (r) => {
+      if (t.current[r] && (t.current[r].scrollIntoView({
+        behavior: "smooth",
+        block: "start",
+        inline: "start",
+        ...e
+      }), e?.offset)) {
+        const s = t.current[r].getBoundingClientRect().top + window.scrollY - e.offset;
+        window.scrollTo({
+          top: s,
+          behavior: e.behavior || "smooth"
+        });
+      }
+    },
+    [e]
+  ), o = v((r, s) => {
+    t.current[s] = r;
+  }, []);
+  return { elementRefs: t, setElementRef: o, scrollToElement: c };
+}
+const M = () => {
+  const [e, t] = h({
+    x: 0,
+    y: 0,
+    percent: {
+      x: 0,
+      y: 0
+    }
+  });
+  return w(() => {
+    const c = () => {
+      const n = window.scrollX || 0, l = window.scrollY || 0, i = /iPad|iPhone|iPod/.test(navigator.userAgent), d = window.visualViewport, m = i && d ? d.width : window.innerWidth, f = i && d ? d.height : window.innerHeight, u = Math.max(
+        0,
+        document.documentElement.scrollWidth - m
+      ), g = Math.max(
+        0,
+        document.documentElement.scrollHeight - f
+      ), b = u === 0 ? 0 : Math.min(100, n / u * 100), y = g === 0 ? 0 : Math.min(100, l / g * 100);
+      t({
+        x: n,
+        y: l,
+        percent: {
+          x: Math.floor(Math.max(0, b)),
+          y: Math.floor(Math.max(0, y))
+        }
+      });
+    };
+    c();
+    const o = () => {
+      c();
+    }, r = () => {
+      setTimeout(c, 100);
+    }, s = () => {
+      setTimeout(c, 50);
+    };
+    return window.addEventListener("scroll", o, { passive: !0 }), window.addEventListener("resize", r), window.addEventListener("orientationchange", r), window.visualViewport && window.visualViewport.addEventListener("resize", s), () => {
+      window.removeEventListener("scroll", o), window.removeEventListener("resize", r), window.removeEventListener("orientationchange", r), window.visualViewport && window.visualViewport.removeEventListener(
+        "resize",
+        s
+      );
+    };
+  }, []), e;
+}, Y = (e = {}) => {
+  const { isInApp: t = !1, debounce: c = 100 } = e, [o, r] = h({
+    width: 0,
+    height: 0,
+    offsetLeft: 0,
+    offsetTop: 0,
+    pageLeft: 0,
+    pageTop: 0,
+    scale: 1
+  }), s = v(() => {
+    const l = window.innerHeight, i = window.visualViewport?.height || l, d = document.documentElement.clientHeight, m = document.body.clientHeight;
+    return window.visualViewport && Math.abs(i - l) > 100 ? i : Math.max(l, d, m);
+  }, []), n = v(() => {
+    if (window.visualViewport && !t)
+      return window.visualViewport;
+    const l = window.visualViewport?.width || window.innerWidth, i = t ? s() : window.visualViewport?.height || window.innerHeight;
+    return {
+      width: l,
+      height: i,
+      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
+    };
+  }, [t, s]);
+  return w(() => {
+    let l;
+    const i = () => {
+      clearTimeout(l), l = setTimeout(() => {
+        r(n());
+      }, c);
+    }, d = () => r(n());
+    d();
+    const m = ["resize", "orientationchange"];
+    t && m.push("focus", "blur", "touchstart", "touchend"), m.forEach((u) => {
+      u === "resize" || u === "orientationchange" ? window.addEventListener(u, i) : window.addEventListener(u, d, { passive: !0 });
+    }), window.visualViewport && (window.visualViewport.addEventListener("resize", d), window.visualViewport.addEventListener("scroll", d));
+    let f;
+    if (t) {
+      let u = n().height;
+      f = setInterval(() => {
+        const g = n().height;
+        Math.abs(g - u) > 50 && (u = g, d());
+      }, 500);
+    }
+    return () => {
+      clearTimeout(l), f && clearInterval(f), m.forEach((u) => {
+        window.removeEventListener(
+          u,
+          u === "resize" || u === "orientationchange" ? i : d
+        );
+      }), window.visualViewport && (window.visualViewport.removeEventListener("resize", d), window.visualViewport.removeEventListener("scroll", d));
+    };
+  }, [n, t, c]), o;
+};
+export {
+  V as useBodyScrollLock,
+  z as useElementRect,
+  H as useElementSize,
+  P as useImageLoader,
+  I as useLocalStorage,
+  R as useRecursiveTimeout,
+  O as useScrollPosition,
+  A as useScrollToElements,
+  Y as useViewport,
+  M 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,85 @@
+{
+  "name": "@jbpark/use-hooks",
+  "version": "1.0.0",
+  "description": "일반적인 UI 및 상호작용 패턴을 위한 재사용 가능한 React 19 훅 모음",
+  "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"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "prepublishOnly": "npm run build",
+    "prepare": "husky install"
+  },
+  "peerDependencies": {
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
+  },
+  "dependencies": {
+    "react-use": "^17.6.0"
+  },
+  "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-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 'npm run lint'",
+      "bash -c 'tsc -b'"
+    ]
+  }
+}