goodchuck-utils 1.4.2 → 1.5.0

package/dist/hooks/useIntersectionObserver.js

@@ -0,0 +1,128 @@
+import { useEffect, useState } from 'react';
+/**
+ * Intersection Observer를 사용하여 요소의 가시성을 감지하는 hook
+ *
+ * @param ref - 관찰할 요소의 ref
+ * @param options - Intersection Observer 옵션
+ * @returns IntersectionObserverEntry 또는 undefined
+ *
+ * @example
+ * // 기본 사용 - 요소가 화면에 보이는지 감지
+ * function LazyImage({ src }: { src: string }) {
+ *   const imageRef = useRef<HTMLImageElement>(null);
+ *   const entry = useIntersectionObserver(imageRef, {
+ *     threshold: 0.1,
+ *     freezeOnceVisible: true
+ *   });
+ *   const isVisible = entry?.isIntersecting;
+ *
+ *   return (
+ *     <img
+ *       ref={imageRef}
+ *       src={isVisible ? src : undefined}
+ *       alt="lazy loaded"
+ *     />
+ *   );
+ * }
+ *
+ * @example
+ * // 무한 스크롤
+ * function InfiniteScrollList() {
+ *   const loadMoreRef = useRef<HTMLDivElement>(null);
+ *   const entry = useIntersectionObserver(loadMoreRef, {
+ *     threshold: 1.0
+ *   });
+ *
+ *   useEffect(() => {
+ *     if (entry?.isIntersecting) {
+ *       loadMoreItems();
+ *     }
+ *   }, [entry?.isIntersecting]);
+ *
+ *   return (
+ *     <div>
+ *       {items.map(item => <Item key={item.id} {...item} />)}
+ *       <div ref={loadMoreRef}>Loading...</div>
+ *     </div>
+ *   );
+ * }
+ *
+ * @example
+ * // 애니메이션 트리거
+ * function AnimatedSection() {
+ *   const sectionRef = useRef<HTMLElement>(null);
+ *   const entry = useIntersectionObserver(sectionRef, {
+ *     threshold: 0.5,
+ *     freezeOnceVisible: true
+ *   });
+ *
+ *   return (
+ *     <section
+ *       ref={sectionRef}
+ *       className={entry?.isIntersecting ? 'fade-in' : 'fade-out'}
+ *     >
+ *       Content
+ *     </section>
+ *   );
+ * }
+ *
+ * @example
+ * // rootMargin 사용 (요소가 화면에 들어오기 전에 미리 감지)
+ * function PreloadImage({ src }: { src: string }) {
+ *   const imageRef = useRef<HTMLImageElement>(null);
+ *   const entry = useIntersectionObserver(imageRef, {
+ *     rootMargin: '200px', // 화면 기준 200px 전에 감지
+ *     freezeOnceVisible: true
+ *   });
+ *
+ *   return <img ref={imageRef} src={entry?.isIntersecting ? src : undefined} />;
+ * }
+ */
+export function useIntersectionObserver(ref, options = {}) {
+    const { threshold = 0, root = null, rootMargin = '0%', freezeOnceVisible = false } = options;
+    const [entry, setEntry] = useState();
+    const frozen = entry?.isIntersecting && freezeOnceVisible;
+    useEffect(() => {
+        const element = ref.current;
+        // 요소가 없거나, 이미 frozen 상태면 observer 생성하지 않음
+        if (!element || frozen) {
+            return;
+        }
+        // Intersection Observer가 지원되지 않는 환경 체크
+        if (!window.IntersectionObserver) {
+            console.warn('IntersectionObserver is not supported in this browser');
+            return;
+        }
+        const observer = new IntersectionObserver(([entry]) => {
+            setEntry(entry);
+        }, { threshold, root, rootMargin });
+        observer.observe(element);
+        return () => {
+            observer.disconnect();
+        };
+    }, [ref, threshold, root, rootMargin, frozen]);
+    return entry;
+}
+/**
+ * 요소가 화면에 보이는지 여부만 반환하는 간단한 버전
+ *
+ * @param ref - 관찰할 요소의 ref
+ * @param options - Intersection Observer 옵션
+ * @returns 요소가 화면에 보이는지 여부
+ *
+ * @example
+ * function Section() {
+ *   const ref = useRef<HTMLDivElement>(null);
+ *   const isVisible = useIsVisible(ref);
+ *
+ *   return (
+ *     <div ref={ref}>
+ *       {isVisible ? 'I am visible!' : 'I am hidden'}
+ *     </div>
+ *   );
+ * }
+ */
+export function useIsVisible(ref, options) {
+    const entry = useIntersectionObserver(ref, options);
+    return entry?.isIntersecting ?? false;
+}

package/dist/hooks/usePrevious.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 이전 렌더링의 값을 저장하는 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 declare function usePrevious<T>(value: T): T | undefined;
+//# sourceMappingURL=usePrevious.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePrevious.d.ts","sourceRoot":"","sources":["../../src/hooks/usePrevious.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAWtD"}

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;
+}