docs(10_Wiki): Topic_Business/General/Graphic/Programming을 Topics/ 하위로 이동

최상위 10_Wiki/Topic_*였던 4개 카테고리 폴더를 10_Wiki/Topics/Topic_* 로 재배치. 콘텐츠 변경 없음(순수 폴더 이동) — Topics/ 하위 나머지 폴더는 이미 지난 커밋에서 전부 정리된 상태(잔존 항목은 에이전트 운영 상태 및 사용자가 보존을 요청한 업데이트0615/무제 3.canvas 뿐).
2026-07-05 00:44:01 +09:00
parent e9cbf23ab5
commit 9a135bd19d
6127 changed files with 0 additions and 0 deletions
@@ -0,0 +1,218 @@
+---
+id: wiki-2026-0508-custom-hooks-patterns
+title: Custom Hooks Patterns
+category: 10_Wiki/Topics
+status: verified
+canonical_id: self
+aliases: [React Custom Hooks, useXxx Patterns]
+duplicate_of: none
+source_trust_level: A
+confidence_score: 0.9
+verification_status: applied
+tags: [react, hooks, patterns]
+raw_sources: []
+last_reinforced: 2026-05-10
+github_commit: pending
+tech_stack:
+  language: TypeScript
+  framework: React 19
+---
+
+# Custom Hooks Patterns
+
+## 매 한 줄
+> **"매 custom hook = stateful logic 의 재사용 unit, JSX 의 X."**. React 19 (2024) `use()` + Server Components 시대에는 custom hook이 매 client-side state machine + side effect orchestration 의 primary abstraction. 매 naming은 `useXxx` — 매 ESLint react-hooks rule 의 enforce.
+
+## 매 핵심
+
+### 매 규칙 (Rules of Hooks)
+- Top-level 만 호출 — 매 conditional / loop X.
+- React function / 매 다른 hook 안에서 만 — 매 일반 function X.
+- Naming `useXxx` — 매 lint 가 의존.
+
+### 매 composition
+- Hook = 매 다른 hook 의 조합 — `useMutation` ← `useState` + `useCallback` + `useRef`.
+- 매 stateful logic 의 분리 + 매 testable 단위.
+
+### 매 응용
+1. Data fetching — `useQuery`, `useSWR`.
+2. DOM observation — `useIntersectionObserver`, `useResizeObserver`.
+3. State machines — `useToggle`, `useReducer` wrapper.
+4. Browser API — `useLocalStorage`, `useMediaQuery`, `useGeolocation`.
+
+## 💻 패턴
+
+### 1. useToggle (state primitive)
+```typescript
+import { useState, useCallback } from 'react';
+
+export function useToggle(initial = false) {
+  const [on, setOn] = useState(initial);
+  const toggle = useCallback(() => setOn((v) => !v), []);
+  const setOnTrue = useCallback(() => setOn(true), []);
+  const setOnFalse = useCallback(() => setOn(false), []);
+  return { on, toggle, setOnTrue, setOnFalse };
+}
+```
+
+### 2. useDebouncedValue
+```typescript
+import { useEffect, useState } from 'react';
+
+export function useDebouncedValue<T>(value: T, delayMs = 300): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(id);
+  }, [value, delayMs]);
+  return debounced;
+}
+```
+
+### 3. useEventListener (typed)
+```typescript
+import { useEffect, useRef } from 'react';
+
+export function useEventListener<K extends keyof WindowEventMap>(
+  type: K,
+  handler: (e: WindowEventMap[K]) => void,
+  target: Window | HTMLElement = window,
+) {
+  const handlerRef = useRef(handler);
+  useEffect(() => { handlerRef.current = handler; });
+  useEffect(() => {
+    const listener = (e: Event) => handlerRef.current(e as WindowEventMap[K]);
+    target.addEventListener(type, listener);
+    return () => target.removeEventListener(type, listener);
+  }, [type, target]);
+}
+```
+
+### 4. useIntersectionObserver
+```typescript
+import { useEffect, useRef, useState } from 'react';
+
+export function useIntersectionObserver<T extends Element>(
+  options: IntersectionObserverInit = {},
+) {
+  const ref = useRef<T>(null);
+  const [entry, setEntry] = useState<IntersectionObserverEntry | null>(null);
+  useEffect(() => {
+    if (!ref.current) return;
+    const obs = new IntersectionObserver(([e]) => setEntry(e), options);
+    obs.observe(ref.current);
+    return () => obs.disconnect();
+  }, [options.root, options.rootMargin, options.threshold]);
+  return { ref, entry, isVisible: entry?.isIntersecting ?? false };
+}
+```
+
+### 5. useLocalStorage (with sync)
+```typescript
+import { useEffect, useState } from 'react';
+
+export function useLocalStorage<T>(key: string, initial: T) {
+  const [value, setValue] = useState<T>(() => {
+    const raw = localStorage.getItem(key);
+    return raw ? (JSON.parse(raw) as T) : initial;
+  });
+  useEffect(() => {
+    localStorage.setItem(key, JSON.stringify(value));
+  }, [key, value]);
+  useEffect(() => {
+    const onStorage = (e: StorageEvent) => {
+      if (e.key === key && e.newValue) setValue(JSON.parse(e.newValue));
+    };
+    window.addEventListener('storage', onStorage);
+    return () => window.removeEventListener('storage', onStorage);
+  }, [key]);
+  return [value, setValue] as const;
+}
+```
+
+### 6. useFetch (with AbortController)
+```typescript
+import { useEffect, useState } from 'react';
+
+export function useFetch<T>(url: string) {
+  const [state, setState] = useState<{ data?: T; error?: Error; loading: boolean }>({ loading: true });
+  useEffect(() => {
+    const ac = new AbortController();
+    setState({ loading: true });
+    fetch(url, { signal: ac.signal })
+      .then((r) => r.json())
+      .then((data: T) => setState({ data, loading: false }))
+      .catch((error: Error) => {
+        if (error.name !== 'AbortError') setState({ error, loading: false });
+      });
+    return () => ac.abort();
+  }, [url]);
+  return state;
+}
+```
+
+### 7. useReducer composite (state machine)
+```typescript
+import { useReducer } from 'react';
+
+type State = { status: 'idle' | 'loading' | 'success' | 'error'; data?: unknown; error?: Error };
+type Action = { type: 'fetch' } | { type: 'success'; data: unknown } | { type: 'error'; error: Error };
+
+const reducer = (s: State, a: Action): State => {
+  switch (a.type) {
+    case 'fetch': return { status: 'loading' };
+    case 'success': return { status: 'success', data: a.data };
+    case 'error': return { status: 'error', error: a.error };
+  }
+};
+
+export const useAsync = () => useReducer(reducer, { status: 'idle' });
+```
+
+### 8. React 19 `use()` for promises
+```typescript
+import { use, Suspense } from 'react';
+
+function Profile({ promise }: { promise: Promise<User> }) {
+  const user = use(promise); // suspends until resolved
+  return <h1>{user.name}</h1>;
+}
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| Local boolean | `useToggle`. |
+| Server data | `useQuery` (TanStack Query) — 매 wheel 재발명 X. |
+| 매 cross-tab sync | `useLocalStorage` + `storage` event. |
+| Async resource | React 19 `use()` + Suspense. |
+| 복잡 state | `useReducer` 매 state machine. |
+| 매 DOM measurement | `useResizeObserver`, `useIntersectionObserver`. |
+
+**기본값**: 매 TanStack Query / Zustand 의 use — custom hook은 매 truly specific logic 만.
+
+## 🔗 Graph
+- 부모: [[React]]
+- 변형: [[Vue Composables]]
+- 응용: [[Component Library]] · [[Design System]]
+- Adjacent: [[useEffect]] · [[State Management]]
+
+## 🤖 LLM 활용
+**언제**: 매 hook scaffolding, TS generic 작성, 매 cleanup logic.
+**언제 X**: 매 stale-closure / dep array 미세 bug — 매 manual review 필요.
+
+## ❌ 안티패턴
+- **Conditional hook call**: 매 `if (x) useFoo()` — 매 lint error.
+- **Stale closure in setInterval**: 매 ref pattern 또는 functional setState 사용.
+- **Effect for derived state**: 매 `useMemo` 또는 render 중 계산 — `useEffect` X.
+- **No cleanup**: 매 listener / subscription 미해제 — leak.
+
+## 🧪 검증 / 중복
+- Verified (react.dev, React 19 release notes).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — React 19 hook patterns + use() |