goodchuck-utils 1.4.2 → 1.6.0

package/dist/hooks/usePrevious.js

@@ -0,0 +1,67 @@
+import { useRef, useEffect } from 'react';
+/**
+ * 이전 렌더링의 값을 저장하는 hook
+ *
+ * @param value - 추적할 값
+ * @returns 이전 렌더링의 값 (첫 렌더링에서는 undefined)
+ *
+ * @example
+ * // 값 변경 감지
+ * function Counter() {
+ *   const [count, setCount] = useState(0);
+ *   const prevCount = usePrevious(count);
+ *
+ *   return (
+ *     <div>
+ *       <p>Current: {count}</p>
+ *       <p>Previous: {prevCount}</p>
+ *       <p>Changed: {count !== prevCount ? 'Yes' : 'No'}</p>
+ *       <button onClick={() => setCount(count + 1)}>Increment</button>
+ *     </div>
+ *   );
+ * }
+ *
+ * @example
+ * // 증가/감소 방향 표시
+ * function PriceDisplay({ price }: { price: number }) {
+ *   const prevPrice = usePrevious(price);
+ *
+ *   const trend = prevPrice === undefined
+ *     ? null
+ *     : price > prevPrice
+ *     ? '📈 Up'
+ *     : price < prevPrice
+ *     ? '📉 Down'
+ *     : '➡️ Same';
+ *
+ *   return (
+ *     <div>
+ *       <span>${price}</span>
+ *       {trend && <span>{trend}</span>}
+ *     </div>
+ *   );
+ * }
+ *
+ * @example
+ * // 애니메이션 방향 결정
+ * function AnimatedList({ items }: { items: string[] }) {
+ *   const prevItems = usePrevious(items);
+ *   const isAdding = prevItems && items.length > prevItems.length;
+ *
+ *   return (
+ *     <ul className={isAdding ? 'slide-in' : 'slide-out'}>
+ *       {items.map(item => <li key={item}>{item}</li>)}
+ *     </ul>
+ *   );
+ * }
+ */
+export function usePrevious(value) {
+    // ref는 리렌더링 간에 값을 유지
+    const ref = useRef(undefined);
+    // 렌더링 후에 현재 값을 ref에 저장
+    useEffect(() => {
+        ref.current = value;
+    }, [value]);
+    // 현재 렌더링에서는 이전 값을 반환
+    return ref.current;
+}

package/dist/hooks/useThrottle.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 값의 업데이트를 일정 시간 간격으로 제한하는 hook
+ * debounce와 달리 일정 간격마다 최신 값을 업데이트합니다.
+ *
+ * @param value - throttle할 값
+ * @param interval - 업데이트 간격 (밀리초, 기본값: 500ms)
+ * @returns throttle된 값
+ *
+ * @example
+ * // 스크롤 위치 추적 최적화
+ * function ScrollTracker() {
+ *   const [scrollY, setScrollY] = useState(0);
+ *   const throttledScrollY = useThrottle(scrollY, 200);
+ *
+ *   useEffect(() => {
+ *     const handleScroll = () => setScrollY(window.scrollY);
+ *     window.addEventListener('scroll', handleScroll);
+ *     return () => window.removeEventListener('scroll', handleScroll);
+ *   }, []);
+ *
+ *   return <div>Scroll position: {throttledScrollY}px</div>;
+ * }
+ *
+ * @example
+ * // 무한 스크롤
+ * function InfiniteScroll() {
+ *   const [scrollY, setScrollY] = useState(0);
+ *   const throttledScrollY = useThrottle(scrollY, 300);
+ *
+ *   useEffect(() => {
+ *     const bottom = document.documentElement.scrollHeight - window.innerHeight;
+ *     if (throttledScrollY >= bottom - 100) {
+ *       loadMoreData();
+ *     }
+ *   }, [throttledScrollY]);
+ *
+ *   return <div>...</div>;
+ * }
+ *
+ * @example
+ * // 검색 입력 (실시간 검색에 적합)
+ * function LiveSearch() {
+ *   const [query, setQuery] = useState('');
+ *   const throttledQuery = useThrottle(query, 500);
+ *
+ *   useEffect(() => {
+ *     // 500ms마다 최대 한 번씩만 API 호출
+ *     if (throttledQuery) {
+ *       searchAPI(throttledQuery);
+ *     }
+ *   }, [throttledQuery]);
+ *
+ *   return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
+ * }
+ */
+export declare function useThrottle<T>(value: T, interval?: number): T;
+//# sourceMappingURL=useThrottle.d.ts.map

package/dist/hooks/useThrottle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThrottle.d.ts","sourceRoot":"","sources":["../../src/hooks/useThrottle.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,GAAE,MAAY,GAAG,CAAC,CA0BlE"}

package/dist/hooks/useThrottle.js

@@ -0,0 +1,80 @@
+import { useState, useEffect, useRef } from 'react';
+/**
+ * 값의 업데이트를 일정 시간 간격으로 제한하는 hook
+ * debounce와 달리 일정 간격마다 최신 값을 업데이트합니다.
+ *
+ * @param value - throttle할 값
+ * @param interval - 업데이트 간격 (밀리초, 기본값: 500ms)
+ * @returns throttle된 값
+ *
+ * @example
+ * // 스크롤 위치 추적 최적화
+ * function ScrollTracker() {
+ *   const [scrollY, setScrollY] = useState(0);
+ *   const throttledScrollY = useThrottle(scrollY, 200);
+ *
+ *   useEffect(() => {
+ *     const handleScroll = () => setScrollY(window.scrollY);
+ *     window.addEventListener('scroll', handleScroll);
+ *     return () => window.removeEventListener('scroll', handleScroll);
+ *   }, []);
+ *
+ *   return <div>Scroll position: {throttledScrollY}px</div>;
+ * }
+ *
+ * @example
+ * // 무한 스크롤
+ * function InfiniteScroll() {
+ *   const [scrollY, setScrollY] = useState(0);
+ *   const throttledScrollY = useThrottle(scrollY, 300);
+ *
+ *   useEffect(() => {
+ *     const bottom = document.documentElement.scrollHeight - window.innerHeight;
+ *     if (throttledScrollY >= bottom - 100) {
+ *       loadMoreData();
+ *     }
+ *   }, [throttledScrollY]);
+ *
+ *   return <div>...</div>;
+ * }
+ *
+ * @example
+ * // 검색 입력 (실시간 검색에 적합)
+ * function LiveSearch() {
+ *   const [query, setQuery] = useState('');
+ *   const throttledQuery = useThrottle(query, 500);
+ *
+ *   useEffect(() => {
+ *     // 500ms마다 최대 한 번씩만 API 호출
+ *     if (throttledQuery) {
+ *       searchAPI(throttledQuery);
+ *     }
+ *   }, [throttledQuery]);
+ *
+ *   return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
+ * }
+ */
+export function useThrottle(value, interval = 500) {
+    const [throttledValue, setThrottledValue] = useState(value);
+    const lastExecuted = useRef(Date.now());
+    useEffect(() => {
+        // 마지막 실행으로부터 경과된 시간
+        const timeSinceLastExecution = Date.now() - lastExecuted.current;
+        if (timeSinceLastExecution >= interval) {
+            // 간격이 지났으면 즉시 업데이트
+            setThrottledValue(value);
+            lastExecuted.current = Date.now();
+        }
+        else {
+            // 아직 간격이 안 지났으면 남은 시간 후에 업데이트
+            const timer = setTimeout(() => {
+                setThrottledValue(value);
+                lastExecuted.current = Date.now();
+            }, interval - timeSinceLastExecution);
+            return () => {
+                clearTimeout(timer);
+            };
+        }
+    }, [value, interval]);
+    return throttledValue;
+}

package/dist/hooks/useToggle.d.ts

@@ -0,0 +1,49 @@
+/**
+ * boolean 상태를 쉽게 토글할 수 있는 hook
+ *
+ * @param initialValue - 초기값 (기본값: false)
+ * @returns [현재 값, 토글 함수, 값 설정 함수]
+ *
+ * @example
+ * // 기본 사용
+ * function Modal() {
+ *   const [isOpen, toggleOpen, setIsOpen] = useToggle(false);
+ *
+ *   return (
+ *     <>
+ *       <button onClick={toggleOpen}>Toggle Modal</button>
+ *       <button onClick={() => setIsOpen(true)}>Open Modal</button>
+ *       <button onClick={() => setIsOpen(false)}>Close Modal</button>
+ *       {isOpen && <div>Modal Content</div>}
+ *     </>
+ *   );
+ * }
+ *
+ * @example
+ * // 다크모드 토글
+ * function ThemeToggle() {
+ *   const [isDark, toggleTheme] = useToggle(false);
+ *
+ *   return (
+ *     <button onClick={toggleTheme}>
+ *       {isDark ? '🌙 Dark' : '☀️ Light'}
+ *     </button>
+ *   );
+ * }
+ *
+ * @example
+ * // 메뉴 열기/닫기
+ * function Sidebar() {
+ *   const [isExpanded, toggleExpanded] = useToggle(true);
+ *
+ *   return (
+ *     <aside className={isExpanded ? 'expanded' : 'collapsed'}>
+ *       <button onClick={toggleExpanded}>
+ *         {isExpanded ? '◀' : '▶'}
+ *       </button>
+ *     </aside>
+ *   );
+ * }
+ */
+export declare function useToggle(initialValue?: boolean): [boolean, () => void, (value: boolean) => void];
+//# sourceMappingURL=useToggle.d.ts.map

package/dist/hooks/useToggle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useToggle.d.ts","sourceRoot":"","sources":["../../src/hooks/useToggle.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,SAAS,CACvB,YAAY,GAAE,OAAe,GAC5B,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,CASjD"}

package/dist/hooks/useToggle.js

@@ -0,0 +1,56 @@
+import { useState, useCallback } from 'react';
+/**
+ * boolean 상태를 쉽게 토글할 수 있는 hook
+ *
+ * @param initialValue - 초기값 (기본값: false)
+ * @returns [현재 값, 토글 함수, 값 설정 함수]
+ *
+ * @example
+ * // 기본 사용
+ * function Modal() {
+ *   const [isOpen, toggleOpen, setIsOpen] = useToggle(false);
+ *
+ *   return (
+ *     <>
+ *       <button onClick={toggleOpen}>Toggle Modal</button>
+ *       <button onClick={() => setIsOpen(true)}>Open Modal</button>
+ *       <button onClick={() => setIsOpen(false)}>Close Modal</button>
+ *       {isOpen && <div>Modal Content</div>}
+ *     </>
+ *   );
+ * }
+ *
+ * @example
+ * // 다크모드 토글
+ * function ThemeToggle() {
+ *   const [isDark, toggleTheme] = useToggle(false);
+ *
+ *   return (
+ *     <button onClick={toggleTheme}>
+ *       {isDark ? '🌙 Dark' : '☀️ Light'}
+ *     </button>
+ *   );
+ * }
+ *
+ * @example
+ * // 메뉴 열기/닫기
+ * function Sidebar() {
+ *   const [isExpanded, toggleExpanded] = useToggle(true);
+ *
+ *   return (
+ *     <aside className={isExpanded ? 'expanded' : 'collapsed'}>
+ *       <button onClick={toggleExpanded}>
+ *         {isExpanded ? '◀' : '▶'}
+ *       </button>
+ *     </aside>
+ *   );
+ * }
+ */
+export function useToggle(initialValue = false) {
+    const [value, setValue] = useState(initialValue);
+    // 토글 함수는 리렌더링 시에도 동일한 참조를 유지
+    const toggle = useCallback(() => {
+        setValue((prev) => !prev);
+    }, []);
+    return [value, toggle, setValue];
+}

package/dist/hooks/useWindowSize.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 윈도우 크기 정보
+ */
+export interface WindowSize {
+    /** 윈도우 너비 (픽셀) */
+    width: number;
+    /** 윈도우 높이 (픽셀) */
+    height: number;
+}
+/**
+ * 윈도우 크기를 추적하는 hook
+ *
+ * @returns 윈도우의 현재 너비와 높이
+ *
+ * @example
+ * // 기본 사용
+ * function ResponsiveComponent() {
+ *   const { width, height } = useWindowSize();
+ *
+ *   return (
+ *     <div>
+ *       Window size: {width} x {height}
+ *     </div>
+ *   );
+ * }
+ *
+ * @example
+ * // 반응형 레이아웃
+ * function AdaptiveLayout() {
+ *   const { width } = useWindowSize();
+ *
+ *   if (width < 768) {
+ *     return <MobileLayout />;
+ *   } else if (width < 1024) {
+ *     return <TabletLayout />;
+ *   } else {
+ *     return <DesktopLayout />;
+ *   }
+ * }
+ *
+ * @example
+ * // 캔버스 크기 조정
+ * function Canvas() {
+ *   const { width, height } = useWindowSize();
+ *   const canvasRef = useRef<HTMLCanvasElement>(null);
+ *
+ *   useEffect(() => {
+ *     if (canvasRef.current) {
+ *       canvasRef.current.width = width;
+ *       canvasRef.current.height = height;
+ *     }
+ *   }, [width, height]);
+ *
+ *   return <canvas ref={canvasRef} />;
+ * }
+ */
+export declare function useWindowSize(): WindowSize;
+//# sourceMappingURL=useWindowSize.d.ts.map

package/dist/hooks/useWindowSize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWindowSize.d.ts","sourceRoot":"","sources":["../../src/hooks/useWindowSize.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAoC1C"}

package/dist/hooks/useWindowSize.js

@@ -0,0 +1,79 @@
+import { useState, useEffect } from 'react';
+/**
+ * 윈도우 크기를 추적하는 hook
+ *
+ * @returns 윈도우의 현재 너비와 높이
+ *
+ * @example
+ * // 기본 사용
+ * function ResponsiveComponent() {
+ *   const { width, height } = useWindowSize();
+ *
+ *   return (
+ *     <div>
+ *       Window size: {width} x {height}
+ *     </div>
+ *   );
+ * }
+ *
+ * @example
+ * // 반응형 레이아웃
+ * function AdaptiveLayout() {
+ *   const { width } = useWindowSize();
+ *
+ *   if (width < 768) {
+ *     return <MobileLayout />;
+ *   } else if (width < 1024) {
+ *     return <TabletLayout />;
+ *   } else {
+ *     return <DesktopLayout />;
+ *   }
+ * }
+ *
+ * @example
+ * // 캔버스 크기 조정
+ * function Canvas() {
+ *   const { width, height } = useWindowSize();
+ *   const canvasRef = useRef<HTMLCanvasElement>(null);
+ *
+ *   useEffect(() => {
+ *     if (canvasRef.current) {
+ *       canvasRef.current.width = width;
+ *       canvasRef.current.height = height;
+ *     }
+ *   }, [width, height]);
+ *
+ *   return <canvas ref={canvasRef} />;
+ * }
+ */
+export function useWindowSize() {
+    // SSR 환경에서는 기본값 사용
+    const [windowSize, setWindowSize] = useState(() => {
+        if (typeof window === 'undefined') {
+            return { width: 0, height: 0 };
+        }
+        return {
+            width: window.innerWidth,
+            height: window.innerHeight,
+        };
+    });
+    useEffect(() => {
+        // SSR 환경에서는 이벤트 리스너 추가하지 않음
+        if (typeof window === 'undefined') {
+            return;
+        }
+        const handleResize = () => {
+            setWindowSize({
+                width: window.innerWidth,
+                height: window.innerHeight,
+            });
+        };
+        // 초기 크기 설정
+        handleResize();
+        window.addEventListener('resize', handleResize);
+        return () => {
+            window.removeEventListener('resize', handleResize);
+        };
+    }, []);
+    return windowSize;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goodchuck-utils",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,6 +12,7 @@
     "prepublishOnly": "npm run test:run && npm run build:tsc",
     "build": "npm run build",
     "build:tsc": "tsc",
+    "dev": "tsc --watch",
     "test": "vitest",
     "test:ui": "vitest --ui",
     "test:run": "vitest run",
@@ -27,12 +28,28 @@
       "types": "./dist/hooks/index.d.ts",
       "import": "./dist/hooks/index.js",
       "default": "./dist/hooks/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js",
+      "default": "./dist/components/index.js"
+    },
+    "./components/dev": {
+      "types": "./dist/components/dev/index.d.ts",
+      "import": "./dist/components/dev/index.js",
+      "default": "./dist/components/dev/index.js"
     }
   },
   "typesVersions": {
     "*": {
       "hooks": [
         "./dist/hooks/index.d.ts"
+      ],
+      "components": [
+        "./dist/components/index.d.ts"
+      ],
+      "components/dev": [
+        "./dist/components/dev/index.d.ts"
       ]
     }
   },
@@ -51,11 +68,15 @@
     "vitest": "^4.0.16"
   },
   "peerDependencies": {
-    "react": ">=16.8.0"
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   }
 }