@jbpark/use-hooks 1.1.1 → 1.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ko.md +170 -0
- package/README.md +85 -77
- package/package.json +1 -1
package/README.ko.md
ADDED
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# use-hooks
|
|
2
|
+
|
|
3
|
+
[English](./README.md) | [한국어](./README.ko.md)
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@jbpark/use-hooks)
|
|
6
|
+
[](https://www.npmjs.com/package/@jbpark/use-hooks)
|
|
7
|
+
[](https://github.com/pjb0811/use-hooks/issues)
|
|
8
|
+
[](https://opensource.org/licenses/MIT)
|
|
9
|
+
|
|
10
|
+
일반적인 UI 및 상호작용 패턴을 위한 재사용 가능한 React 19 훅 모음입니다. TypeScript와 Vite로 빌드되었으며, 서버 사이드 렌더링과 클라이언트 사이드 애플리케이션 모두에 최적화되어 있습니다.
|
|
11
|
+
|
|
12
|
+
## 기능
|
|
13
|
+
|
|
14
|
+
- 📦 **10개 프로덕션 레디 훅** - 스크롤, 뷰포트, 스토리지 등 다양한 유틸리티
|
|
15
|
+
- 🎯 **TypeScript 지원** - 완전한 타입 지원으로 더 나은 개발 경험
|
|
16
|
+
- ⚡ **트리 셰이킹 지원** - 필요한 것만 임포트하세요
|
|
17
|
+
- 🔒 **SSR 안전** - window/document 전역 변수에 대한 보호
|
|
18
|
+
- 📱 **iOS 최적화** - 모바일 뷰포트 특성에 대한 특별 처리
|
|
19
|
+
- 🧹 **완벽한 정리** - 모든 리스너와 옵저버가 정리됩니다
|
|
20
|
+
|
|
21
|
+
## 설치
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm install @jbpark/use-hooks
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
또는 pnpm 사용:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
pnpm add @jbpark/use-hooks
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## 사용 방법
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
import {
|
|
37
|
+
useElementSize,
|
|
38
|
+
useLocalStorage,
|
|
39
|
+
useWindowScroll,
|
|
40
|
+
} from '@jbpark/use-hooks';
|
|
41
|
+
|
|
42
|
+
function MyComponent() {
|
|
43
|
+
// localStorage를 사용한 영속적 상태
|
|
44
|
+
const [count, setCount] = useLocalStorage('count', 0);
|
|
45
|
+
|
|
46
|
+
// 윈도우 스크롤 위치 추적
|
|
47
|
+
const { y, percent } = useWindowScroll();
|
|
48
|
+
|
|
49
|
+
// 브레이크포인트를 포함한 요소 크기 모니터링
|
|
50
|
+
const { size, breakpoint, ref } = useElementSize();
|
|
51
|
+
|
|
52
|
+
return (
|
|
53
|
+
<div ref={ref}>
|
|
54
|
+
<p>Count: {count}</p>
|
|
55
|
+
<p>Scroll: {percent.y}%</p>
|
|
56
|
+
<p>Breakpoint: {breakpoint.current}</p>
|
|
57
|
+
<button onClick={() => setCount(count + 1)}>증가</button>
|
|
58
|
+
</div>
|
|
59
|
+
);
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## 사용 가능한 훅
|
|
64
|
+
|
|
65
|
+
| 훅 | 설명 |
|
|
66
|
+
| --------------------- | --------------------------------------------------------------- |
|
|
67
|
+
| `useLocalStorage` | 에러 핸들링이 포함된 JSON 기반 영속 상태 (SSR 안전) |
|
|
68
|
+
| `useWindowScroll` | 윈도우 스크롤 위치 및 백분율 추적 (iOS visualViewport 대응) |
|
|
69
|
+
| `useScrollPosition` | ResizeObserver를 사용한 특정 요소의 스크롤 상태 추적 |
|
|
70
|
+
| `useElementPosition` | 스크롤/리사이즈 시 요소의 바운딩 렉트 모니터링 (요소 참조 지원) |
|
|
71
|
+
| `useElementSize` | Tailwind 유사 브레이크포인트를 포함한 요소 크기 추적 (debounce) |
|
|
72
|
+
| `useBodyScrollLock` | 스타일 보존을 포함한 바디 스크롤 잠금/해제 (iOS 특별 처리) |
|
|
73
|
+
| `useScrollToElements` | 인덱스별로 특정 요소로 스크롤 (오프셋 조절 가능) |
|
|
74
|
+
| `useImage` | 이미지 사전로드 및 로딩/에러 상태 노출 |
|
|
75
|
+
| `useRecursiveTimeout` | 비동기/동기 콜백을 재귀적으로 스케줄링 |
|
|
76
|
+
| `useViewport` | visualViewport 지원, 인앱 모드 옵션, debounce 포함 |
|
|
77
|
+
|
|
78
|
+
## 개발
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
# HMR이 포함된 개발 서버 시작
|
|
82
|
+
pnpm dev
|
|
83
|
+
|
|
84
|
+
# 라이브러리 빌드 (tsc + vite)
|
|
85
|
+
pnpm build
|
|
86
|
+
|
|
87
|
+
# 빌드된 라이브러리 미리보기
|
|
88
|
+
pnpm preview
|
|
89
|
+
|
|
90
|
+
# 린트 및 타입 체크
|
|
91
|
+
pnpm lint
|
|
92
|
+
|
|
93
|
+
# prettier로 포맷팅
|
|
94
|
+
pnpm exec prettier --write .
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## 프로젝트 구조
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
src/
|
|
101
|
+
├── hooks/ # 개별 훅 구현
|
|
102
|
+
│ ├── useBodyScrollLock/
|
|
103
|
+
│ ├── useElementPosition/
|
|
104
|
+
│ ├── useElementScroll/
|
|
105
|
+
│ ├── useImage/
|
|
106
|
+
│ ├── useLocalStorage/
|
|
107
|
+
│ ├── useRecursiveTimeout/
|
|
108
|
+
│ ├── useResponsiveSize/
|
|
109
|
+
│ ├── useScrollToElements/
|
|
110
|
+
│ ├── useViewport/
|
|
111
|
+
│ ├── useWindowScroll/
|
|
112
|
+
│ └── index.ts # 배럴 익스포트
|
|
113
|
+
└── index.ts # 패키지 진입점
|
|
114
|
+
|
|
115
|
+
dist/ # 빌드된 라이브러리 (ES + CJS + types)
|
|
116
|
+
.changeset/ # 버저닝을 위한 Changesets
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## 빌드 및 배포
|
|
120
|
+
|
|
121
|
+
이 프로젝트는 버전 관리를 위해 Changesets를 사용합니다:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
# 변경사항 기록
|
|
125
|
+
pnpm changeset add
|
|
126
|
+
|
|
127
|
+
# 버전 업데이트 및 CHANGELOG 생성
|
|
128
|
+
pnpm changeset version
|
|
129
|
+
|
|
130
|
+
# npm에 배포
|
|
131
|
+
pnpm changeset publish
|
|
132
|
+
|
|
133
|
+
# 태그 푸시
|
|
134
|
+
git push --follow-tags
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
라이브러리는 다음과 같이 빌드됩니다:
|
|
138
|
+
|
|
139
|
+
- **ES Module**: `dist/index.js`
|
|
140
|
+
- **CommonJS**: `dist/index.cjs`
|
|
141
|
+
- **타입 정의**: `dist/index.d.ts`
|
|
142
|
+
|
|
143
|
+
## 주요 패턴
|
|
144
|
+
|
|
145
|
+
- **Window 보호**: `window`/`document`에 접근하는 훅은 SSR 안전성을 위해 `typeof window` 체크 (예: `useLocalStorage`)
|
|
146
|
+
- **이벤트 리스너**: 모든 스크롤/리사이즈 리스너는 가능한 한 passive 플래그 사용
|
|
147
|
+
- **ResizeObserver**: `useElementSize`와 `useElementPosition`에서 사용하여 성능 최적화
|
|
148
|
+
- **requestAnimationFrame**: 스크롤/리사이즈 콜백에서 레이아웃 스래싱 방지
|
|
149
|
+
- **iOS 대응**: `useBodyScrollLock`, `useWindowScroll`, `useViewport`에서 iOS의 visualViewport 특성 처리
|
|
150
|
+
- **Debounce**: `useElementSize`와 `useViewport`에서 리사이즈 이벤트 디바운싱 지원
|
|
151
|
+
|
|
152
|
+
## 브라우저 지원
|
|
153
|
+
|
|
154
|
+
- 최신 브라우저 (Chrome, Firefox, Safari, Edge)
|
|
155
|
+
- iOS 12+ (특수한 `visualViewport` 처리 포함)
|
|
156
|
+
- SSR 준비 완료 (적절한 보호 포함)
|
|
157
|
+
|
|
158
|
+
## 기여하기
|
|
159
|
+
|
|
160
|
+
버그 리포트, 기능 제안, 또는 코드 기여를 환영합니다!
|
|
161
|
+
|
|
162
|
+
- 🐛 **버그 리포트**: [Issues](https://github.com/pjb0811/use-hooks/issues)에서 버그를 리포트해주세요
|
|
163
|
+
- 💡 **기능 제안**: 새로운 기능 아이디어가 있으시면 [Issues](https://github.com/pjb0811/use-hooks/issues)에 제안해주세요
|
|
164
|
+
- 🔧 **코드 기여**: Pull Request를 보내주시면 검토 후 반영하겠습니다
|
|
165
|
+
|
|
166
|
+
이슈를 생성하기 전에 기존 이슈를 확인해주시면 중복을 방지할 수 있습니다.
|
|
167
|
+
|
|
168
|
+
## 라이선스
|
|
169
|
+
|
|
170
|
+
MIT
|
package/README.md
CHANGED
|
@@ -1,28 +1,36 @@
|
|
|
1
1
|
# use-hooks
|
|
2
2
|
|
|
3
|
+
[English](./README.md) | [한국어](./README.ko.md)
|
|
4
|
+
|
|
3
5
|
[](https://www.npmjs.com/package/@jbpark/use-hooks)
|
|
4
6
|
[](https://www.npmjs.com/package/@jbpark/use-hooks)
|
|
5
7
|
[](https://github.com/pjb0811/use-hooks/issues)
|
|
6
8
|
[](https://opensource.org/licenses/MIT)
|
|
7
9
|
|
|
8
|
-
|
|
10
|
+
A collection of reusable React 19 hooks for common UI and interaction patterns. Built with TypeScript and Vite, optimized for both server-side rendering and client-side applications.
|
|
9
11
|
|
|
10
|
-
##
|
|
12
|
+
## Features
|
|
11
13
|
|
|
12
|
-
- 📦 **10
|
|
13
|
-
- 🎯 **TypeScript
|
|
14
|
-
- ⚡
|
|
15
|
-
- 🔒 **SSR
|
|
16
|
-
- 📱 **iOS
|
|
17
|
-
- 🧹
|
|
14
|
+
- 📦 **10 Production-Ready Hooks** - Utilities for scrolling, viewport, storage, and more
|
|
15
|
+
- 🎯 **Full TypeScript Support** - Complete type definitions for better development experience
|
|
16
|
+
- ⚡ **Tree-Shakeable** - Import only what you need
|
|
17
|
+
- 🔒 **SSR-Safe** - Built-in protection for window/document globals
|
|
18
|
+
- 📱 **iOS Optimized** - Special handling for mobile viewport characteristics
|
|
19
|
+
- 🧹 **Proper Cleanup** - All listeners and observers are properly cleaned up
|
|
18
20
|
|
|
19
|
-
##
|
|
21
|
+
## Installation
|
|
20
22
|
|
|
21
23
|
```bash
|
|
22
24
|
npm install @jbpark/use-hooks
|
|
23
25
|
```
|
|
24
26
|
|
|
25
|
-
|
|
27
|
+
Or with pnpm:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
pnpm add @jbpark/use-hooks
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Usage
|
|
26
34
|
|
|
27
35
|
```tsx
|
|
28
36
|
import {
|
|
@@ -32,13 +40,13 @@ import {
|
|
|
32
40
|
} from '@jbpark/use-hooks';
|
|
33
41
|
|
|
34
42
|
function MyComponent() {
|
|
35
|
-
//
|
|
43
|
+
// Persistent state using localStorage
|
|
36
44
|
const [count, setCount] = useLocalStorage('count', 0);
|
|
37
45
|
|
|
38
|
-
//
|
|
46
|
+
// Track window scroll position
|
|
39
47
|
const { y, percent } = useWindowScroll();
|
|
40
48
|
|
|
41
|
-
//
|
|
49
|
+
// Monitor element size with breakpoints
|
|
42
50
|
const { size, breakpoint, ref } = useElementSize();
|
|
43
51
|
|
|
44
52
|
return (
|
|
@@ -46,117 +54,117 @@ function MyComponent() {
|
|
|
46
54
|
<p>Count: {count}</p>
|
|
47
55
|
<p>Scroll: {percent.y}%</p>
|
|
48
56
|
<p>Breakpoint: {breakpoint.current}</p>
|
|
49
|
-
<button onClick={() => setCount(count + 1)}
|
|
57
|
+
<button onClick={() => setCount(count + 1)}>Increment</button>
|
|
50
58
|
</div>
|
|
51
59
|
);
|
|
52
60
|
}
|
|
53
61
|
```
|
|
54
62
|
|
|
55
|
-
##
|
|
63
|
+
## Available Hooks
|
|
56
64
|
|
|
57
|
-
|
|
|
58
|
-
| --------------------- |
|
|
59
|
-
| `useLocalStorage` |
|
|
60
|
-
| `useWindowScroll` |
|
|
61
|
-
| `useScrollPosition` |
|
|
62
|
-
| `
|
|
63
|
-
| `useElementSize` |
|
|
64
|
-
| `useBodyScrollLock` |
|
|
65
|
-
| `useScrollToElements` |
|
|
66
|
-
| `
|
|
67
|
-
| `useRecursiveTimeout` |
|
|
68
|
-
| `useViewport` | visualViewport
|
|
65
|
+
| Hook | Description |
|
|
66
|
+
| --------------------- | --------------------------------------------------------------------------- |
|
|
67
|
+
| `useLocalStorage` | JSON-based persistent state with error handling (SSR-safe) |
|
|
68
|
+
| `useWindowScroll` | Track window scroll position and percentage (iOS visualViewport compatible) |
|
|
69
|
+
| `useScrollPosition` | Monitor scroll state of specific elements using ResizeObserver |
|
|
70
|
+
| `useElementPosition` | Monitor element bounding rect on scroll/resize (element ref support) |
|
|
71
|
+
| `useElementSize` | Track element size with Tailwind-like breakpoints (debounced) |
|
|
72
|
+
| `useBodyScrollLock` | Lock/unlock body scroll with style preservation (iOS-specific handling) |
|
|
73
|
+
| `useScrollToElements` | Scroll to specific elements by index (adjustable offset) |
|
|
74
|
+
| `useImage` | Preload images and expose loading/error states |
|
|
75
|
+
| `useRecursiveTimeout` | Recursively schedule async/sync callbacks |
|
|
76
|
+
| `useViewport` | visualViewport support with in-app mode option and debounce |
|
|
69
77
|
|
|
70
|
-
##
|
|
78
|
+
## Development
|
|
71
79
|
|
|
72
80
|
```bash
|
|
73
|
-
#
|
|
74
|
-
|
|
81
|
+
# Start development server with HMR
|
|
82
|
+
pnpm dev
|
|
75
83
|
|
|
76
|
-
#
|
|
77
|
-
|
|
84
|
+
# Build library (tsc + vite)
|
|
85
|
+
pnpm build
|
|
78
86
|
|
|
79
|
-
#
|
|
80
|
-
|
|
87
|
+
# Preview built library
|
|
88
|
+
pnpm preview
|
|
81
89
|
|
|
82
|
-
#
|
|
83
|
-
|
|
90
|
+
# Run lint and type check
|
|
91
|
+
pnpm lint
|
|
84
92
|
|
|
85
|
-
# prettier
|
|
86
|
-
|
|
93
|
+
# Format code with prettier
|
|
94
|
+
pnpm exec prettier --write .
|
|
87
95
|
```
|
|
88
96
|
|
|
89
|
-
##
|
|
97
|
+
## Project Structure
|
|
90
98
|
|
|
91
99
|
```
|
|
92
100
|
src/
|
|
93
|
-
├── hooks/ #
|
|
101
|
+
├── hooks/ # Individual hook implementations
|
|
94
102
|
│ ├── useBodyScrollLock/
|
|
95
|
-
│ ├──
|
|
96
|
-
│ ├──
|
|
97
|
-
│ ├──
|
|
103
|
+
│ ├── useElementPosition/
|
|
104
|
+
│ ├── useElementScroll/
|
|
105
|
+
│ ├── useImage/
|
|
98
106
|
│ ├── useLocalStorage/
|
|
99
107
|
│ ├── useRecursiveTimeout/
|
|
100
|
-
│ ├──
|
|
108
|
+
│ ├── useResponsiveSize/
|
|
101
109
|
│ ├── useScrollToElements/
|
|
102
110
|
│ ├── useViewport/
|
|
103
111
|
│ ├── useWindowScroll/
|
|
104
|
-
│ └── index.ts #
|
|
105
|
-
└── index.ts #
|
|
112
|
+
│ └── index.ts # Barrel export
|
|
113
|
+
└── index.ts # Package entry point
|
|
106
114
|
|
|
107
|
-
dist/ #
|
|
108
|
-
.changeset/ #
|
|
115
|
+
dist/ # Built library (ES + CJS + types)
|
|
116
|
+
.changeset/ # Changesets for versioning
|
|
109
117
|
```
|
|
110
118
|
|
|
111
|
-
##
|
|
119
|
+
## Build & Deployment
|
|
112
120
|
|
|
113
|
-
|
|
121
|
+
This project uses Changesets for version management:
|
|
114
122
|
|
|
115
123
|
```bash
|
|
116
|
-
#
|
|
117
|
-
|
|
124
|
+
# Record changes
|
|
125
|
+
pnpm changeset add
|
|
118
126
|
|
|
119
|
-
#
|
|
120
|
-
|
|
127
|
+
# Update versions and generate CHANGELOG
|
|
128
|
+
pnpm changeset version
|
|
121
129
|
|
|
122
|
-
# npm
|
|
123
|
-
|
|
130
|
+
# Publish to npm
|
|
131
|
+
pnpm changeset publish
|
|
124
132
|
|
|
125
|
-
#
|
|
133
|
+
# Push tags
|
|
126
134
|
git push --follow-tags
|
|
127
135
|
```
|
|
128
136
|
|
|
129
|
-
|
|
137
|
+
The library is built as:
|
|
130
138
|
|
|
131
139
|
- **ES Module**: `dist/index.js`
|
|
132
140
|
- **CommonJS**: `dist/index.cjs`
|
|
133
|
-
-
|
|
141
|
+
- **Type Definitions**: `dist/index.d.ts`
|
|
134
142
|
|
|
135
|
-
##
|
|
143
|
+
## Key Patterns
|
|
136
144
|
|
|
137
|
-
- **Window
|
|
138
|
-
-
|
|
139
|
-
- **ResizeObserver**: `useElementSize
|
|
140
|
-
- **requestAnimationFrame**:
|
|
141
|
-
- **iOS
|
|
142
|
-
- **Debounce**: `useElementSize
|
|
145
|
+
- **Window Protection**: Hooks accessing `window`/`document` check `typeof window` for SSR safety (e.g., `useLocalStorage`)
|
|
146
|
+
- **Event Listeners**: All scroll/resize listeners use passive flag when possible
|
|
147
|
+
- **ResizeObserver**: Used in `useElementSize` and `useElementPosition` for performance
|
|
148
|
+
- **requestAnimationFrame**: Prevents layout thrashing in scroll/resize callbacks
|
|
149
|
+
- **iOS Compatibility**: Special handling of iOS visualViewport in `useBodyScrollLock`, `useWindowScroll`, and `useViewport`
|
|
150
|
+
- **Debounce**: Optional debouncing for resize events in `useElementSize` and `useViewport`
|
|
143
151
|
|
|
144
|
-
##
|
|
152
|
+
## Browser Support
|
|
145
153
|
|
|
146
|
-
-
|
|
147
|
-
- iOS 12+ (
|
|
148
|
-
- SSR
|
|
154
|
+
- Modern browsers (Chrome, Firefox, Safari, Edge)
|
|
155
|
+
- iOS 12+ (with special visualViewport handling)
|
|
156
|
+
- SSR-ready (with proper guards)
|
|
149
157
|
|
|
150
|
-
##
|
|
158
|
+
## Contributing
|
|
151
159
|
|
|
152
|
-
|
|
160
|
+
Bug reports, feature suggestions, and code contributions are welcome!
|
|
153
161
|
|
|
154
|
-
- 🐛
|
|
155
|
-
- 💡
|
|
156
|
-
- 🔧
|
|
162
|
+
- 🐛 **Bug Reports**: Report bugs in [Issues](https://github.com/pjb0811/use-hooks/issues)
|
|
163
|
+
- 💡 **Feature Requests**: Suggest new features in [Issues](https://github.com/pjb0811/use-hooks/issues)
|
|
164
|
+
- 🔧 **Code Contributions**: Send Pull Requests for review
|
|
157
165
|
|
|
158
|
-
|
|
166
|
+
Please check existing issues before creating a new one to avoid duplicates.
|
|
159
167
|
|
|
160
|
-
##
|
|
168
|
+
## License
|
|
161
169
|
|
|
162
170
|
MIT
|