@blastlabs/utils 1.11.1 → 1.12.0

package/dist/hooks/storage/index.js

@@ -0,0 +1,6 @@
+/**
+ * Storage Hooks
+ */
+export * from './useLocalStorage';
+export * from './useSessionStorage';
+export * from './useCopyToClipboard';

package/dist/hooks/storage/useCopyToClipboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCopyToClipboard.d.ts","sourceRoot":"","sources":["../../../src/hooks/storage/useCopyToClipboard.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,8BAA8B;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oBAAoB;IACpB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,sBAAsB;IACtB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,kBAAkB,IAAI,qBAAqB,CA0B1D"}

package/dist/hooks/storage/useLocalStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLocalStorage.d.ts","sourceRoot":"","sources":["../../../src/hooks/storage/useLocalStorage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAEnF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,GACd,CAAC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,CA0F9C"}

package/dist/hooks/storage/useSessionStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSessionStorage.d.ts","sourceRoot":"","sources":["../../../src/hooks/storage/useSessionStorage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAEnF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,GACd,CAAC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,CAoF9C"}

package/dist/hooks/time/__tests__/useCountdown.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=useCountdown.test.d.ts.map

package/dist/hooks/time/__tests__/useCountdown.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCountdown.test.d.ts","sourceRoot":"","sources":["../../../../src/hooks/time/__tests__/useCountdown.test.ts"],"names":[],"mappings":""}

package/dist/hooks/time/__tests__/useCountdown.test.js

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useCountdown } from '../useCountdown';
+describe('useCountdown', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('should initialize with the given time', () => {
+        const { result } = renderHook(() => useCountdown(60));
+        expect(result.current.timeLeft).toBe(60);
+        expect(result.current.isRunning).toBe(false);
+        expect(result.current.isCompleted).toBe(false);
+    });
+    it('should start countdown when start is called', () => {
+        const { result } = renderHook(() => useCountdown(5));
+        act(() => {
+            result.current.start();
+        });
+        expect(result.current.isRunning).toBe(true);
+        act(() => {
+            vi.advanceTimersByTime(1000);
+        });
+        expect(result.current.timeLeft).toBe(4);
+    });
+    it('should pause countdown', () => {
+        const { result } = renderHook(() => useCountdown(10));
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(3000);
+        });
+        expect(result.current.timeLeft).toBe(7);
+        act(() => {
+            result.current.pause();
+        });
+        expect(result.current.isRunning).toBe(false);
+        act(() => {
+            vi.advanceTimersByTime(2000);
+        });
+        // 일시정지 후에는 시간이 변하지 않아야 함
+        expect(result.current.timeLeft).toBe(7);
+    });
+    it('should resume countdown', () => {
+        const { result } = renderHook(() => useCountdown(10));
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(3000);
+        });
+        act(() => {
+            result.current.pause();
+        });
+        expect(result.current.timeLeft).toBe(7);
+        act(() => {
+            result.current.resume();
+        });
+        expect(result.current.isRunning).toBe(true);
+        act(() => {
+            vi.advanceTimersByTime(2000);
+        });
+        expect(result.current.timeLeft).toBe(5);
+    });
+    it('should reset countdown to initial time', () => {
+        const { result } = renderHook(() => useCountdown(10));
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(5000);
+        });
+        expect(result.current.timeLeft).toBe(5);
+        act(() => {
+            result.current.reset();
+        });
+        expect(result.current.timeLeft).toBe(10);
+        expect(result.current.isRunning).toBe(false);
+        expect(result.current.isCompleted).toBe(false);
+    });
+    it('should reset countdown to new time', () => {
+        const { result } = renderHook(() => useCountdown(10));
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(5000);
+        });
+        act(() => {
+            result.current.reset(20);
+        });
+        expect(result.current.timeLeft).toBe(20);
+    });
+    it('should call onComplete when countdown reaches 0', () => {
+        const onComplete = vi.fn();
+        const { result } = renderHook(() => useCountdown(3, { onComplete }));
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(3000);
+        });
+        expect(result.current.timeLeft).toBe(0);
+        expect(result.current.isCompleted).toBe(true);
+        expect(result.current.isRunning).toBe(false);
+        expect(onComplete).toHaveBeenCalledTimes(1);
+    });
+    it('should auto start when autoStart is true', () => {
+        const { result } = renderHook(() => useCountdown(5, { autoStart: true }));
+        expect(result.current.isRunning).toBe(true);
+        act(() => {
+            vi.advanceTimersByTime(2000);
+        });
+        expect(result.current.timeLeft).toBe(3);
+    });
+    it('should use custom interval', () => {
+        const { result } = renderHook(() => useCountdown(5, { interval: 500 }));
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(500);
+        });
+        expect(result.current.timeLeft).toBe(4);
+        act(() => {
+            vi.advanceTimersByTime(500);
+        });
+        expect(result.current.timeLeft).toBe(3);
+    });
+    it('should restart from initial time when start is called after completion', () => {
+        const { result } = renderHook(() => useCountdown(3));
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(3000);
+        });
+        expect(result.current.isCompleted).toBe(true);
+        expect(result.current.timeLeft).toBe(0);
+        act(() => {
+            result.current.start();
+        });
+        expect(result.current.timeLeft).toBe(3);
+        expect(result.current.isCompleted).toBe(false);
+        expect(result.current.isRunning).toBe(true);
+    });
+});

package/dist/hooks/time/__tests__/useInterval.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=useInterval.test.d.ts.map

package/dist/hooks/time/__tests__/useInterval.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInterval.test.d.ts","sourceRoot":"","sources":["../../../../src/hooks/time/__tests__/useInterval.test.ts"],"names":[],"mappings":""}

package/dist/hooks/time/__tests__/useInterval.test.js

@@ -0,0 +1,39 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useInterval } from "../useInterval";
+describe('useInterval 단위 테스트', () => {
+    const mockAlert = vi.fn();
+    beforeAll(() => {
+        window.alert = mockAlert;
+    });
+    beforeEach(() => {
+        vi.useFakeTimers();
+        mockAlert.mockClear();
+    });
+    afterEach(() => {
+        vi.clearAllTimers();
+        vi.runOnlyPendingTimers();
+        vi.useRealTimers();
+    });
+    it('callback 함수를 설정한 delay 마다 실행시킨다', () => {
+        renderHook(() => useInterval(() => {
+            window.alert('호출!');
+        }, 1000));
+        vi.advanceTimersByTime(200);
+        expect(mockAlert).not.toHaveBeenCalled();
+        vi.advanceTimersByTime(800);
+        expect(mockAlert).toHaveBeenCalledWith('호출!');
+        vi.advanceTimersByTime(1000);
+        expect(mockAlert).toHaveBeenCalledTimes(2);
+    });
+    it('delay가 변경되면 반복 주기를 변경한다', () => {
+        const { rerender } = renderHook(({ delay }) => useInterval(() => {
+            window.alert('호출!');
+        }, delay), { initialProps: { delay: 500 } });
+        vi.advanceTimersByTime(1000);
+        expect(mockAlert).toHaveBeenCalledTimes(2);
+        rerender({ delay: 200 });
+        vi.advanceTimersByTime(1000);
+        expect(mockAlert).toHaveBeenCalledTimes(7);
+    });
+});

package/dist/hooks/time/__tests__/useStopwatch.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=useStopwatch.test.d.ts.map

package/dist/hooks/time/__tests__/useStopwatch.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStopwatch.test.d.ts","sourceRoot":"","sources":["../../../../src/hooks/time/__tests__/useStopwatch.test.ts"],"names":[],"mappings":""}

package/dist/hooks/time/__tests__/useStopwatch.test.js

@@ -0,0 +1,149 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useStopwatch } from '../useStopwatch';
+describe('useStopwatch', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('should initialize with 0 elapsed time', () => {
+        const { result } = renderHook(() => useStopwatch());
+        expect(result.current.elapsed).toBe(0);
+        expect(result.current.elapsedSeconds).toBe(0);
+        expect(result.current.isRunning).toBe(false);
+    });
+    it('should start stopwatch', () => {
+        const { result } = renderHook(() => useStopwatch());
+        act(() => {
+            result.current.start();
+        });
+        expect(result.current.isRunning).toBe(true);
+        act(() => {
+            vi.advanceTimersByTime(1000);
+        });
+        expect(result.current.elapsed).toBeGreaterThan(0);
+    });
+    it('should pause stopwatch', () => {
+        const { result } = renderHook(() => useStopwatch());
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(1000);
+        });
+        const elapsedBeforePause = result.current.elapsed;
+        act(() => {
+            result.current.pause();
+        });
+        expect(result.current.isRunning).toBe(false);
+        act(() => {
+            vi.advanceTimersByTime(1000);
+        });
+        // 일시정지 후에는 시간이 변하지 않아야 함
+        expect(result.current.elapsed).toBe(elapsedBeforePause);
+    });
+    it('should resume stopwatch', () => {
+        const { result } = renderHook(() => useStopwatch());
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(1000);
+        });
+        act(() => {
+            result.current.pause();
+        });
+        const elapsedBeforeResume = result.current.elapsed;
+        act(() => {
+            result.current.resume();
+        });
+        expect(result.current.isRunning).toBe(true);
+        act(() => {
+            vi.advanceTimersByTime(1000);
+        });
+        expect(result.current.elapsed).toBeGreaterThan(elapsedBeforeResume);
+    });
+    it('should reset stopwatch', () => {
+        const { result } = renderHook(() => useStopwatch());
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(2000);
+        });
+        expect(result.current.elapsed).toBeGreaterThan(0);
+        act(() => {
+            result.current.reset();
+        });
+        expect(result.current.elapsed).toBe(0);
+        expect(result.current.isRunning).toBe(false);
+    });
+    it('should auto start when autoStart is true', () => {
+        const { result } = renderHook(() => useStopwatch({ autoStart: true }));
+        expect(result.current.isRunning).toBe(true);
+        act(() => {
+            vi.advanceTimersByTime(1000);
+        });
+        expect(result.current.elapsed).toBeGreaterThan(0);
+    });
+    it('should calculate elapsedSeconds correctly', () => {
+        const { result } = renderHook(() => useStopwatch());
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(2500);
+        });
+        expect(result.current.elapsedSeconds).toBeCloseTo(2.5, 1);
+    });
+    it('should use custom interval', () => {
+        const { result } = renderHook(() => useStopwatch({ interval: 100 }));
+        act(() => {
+            result.current.start();
+        });
+        const initialElapsed = result.current.elapsed;
+        act(() => {
+            vi.advanceTimersByTime(100);
+        });
+        expect(result.current.elapsed).toBeGreaterThan(initialElapsed);
+    });
+    it('should accumulate time across pause and resume', () => {
+        const { result } = renderHook(() => useStopwatch());
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(1000);
+        });
+        act(() => {
+            result.current.pause();
+        });
+        const elapsed1 = result.current.elapsed;
+        act(() => {
+            result.current.resume();
+        });
+        act(() => {
+            vi.advanceTimersByTime(1000);
+        });
+        expect(result.current.elapsed).toBeGreaterThan(elapsed1);
+    });
+    it('should not change elapsed time when paused', () => {
+        const { result } = renderHook(() => useStopwatch());
+        act(() => {
+            result.current.start();
+        });
+        act(() => {
+            vi.advanceTimersByTime(1000);
+        });
+        act(() => {
+            result.current.pause();
+        });
+        const pausedElapsed = result.current.elapsed;
+        act(() => {
+            vi.advanceTimersByTime(5000);
+        });
+        expect(result.current.elapsed).toBe(pausedElapsed);
+    });
+});

package/dist/hooks/time/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Time-related Hooks
+ */
+export * from './useInterval';
+export * from './useCountdown';
+export * from './useStopwatch';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/time/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/time/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/dist/hooks/time/index.js

@@ -0,0 +1,6 @@
+/**
+ * Time-related Hooks
+ */
+export * from './useInterval';
+export * from './useCountdown';
+export * from './useStopwatch';

package/dist/hooks/time/useCountdown.d.ts

@@ -0,0 +1,116 @@
+export interface UseCountdownOptions {
+    /** 카운트다운 완료 시 호출되는 콜백 */
+    onComplete?: () => void;
+    /** 카운트다운 간격 (밀리초, 기본값: 1000ms) */
+    interval?: number;
+    /** 자동 시작 여부 (기본값: false) */
+    autoStart?: boolean;
+}
+export interface UseCountdownReturn {
+    /** 남은 시간 (초) */
+    timeLeft: number;
+    /** 카운트다운 시작 */
+    start: () => void;
+    /** 카운트다운 일시정지 */
+    pause: () => void;
+    /** 카운트다운 재개 */
+    resume: () => void;
+    /** 카운트다운 리셋 */
+    reset: (newTime?: number) => void;
+    /** 카운트다운 실행 중 여부 */
+    isRunning: boolean;
+    /** 카운트다운 완료 여부 */
+    isCompleted: boolean;
+}
+/**
+ * 카운트다운 타이머 hook
+ *
+ * 지정된 시간부터 0까지 카운트다운하는 타이머를 제공합니다.
+ *
+ * @example
+ * ```tsx
+ * // 기본 사용 - 60초 카운트다운
+ * function Timer() {
+ *   const { timeLeft, start, pause, reset, isRunning } = useCountdown(60);
+ *
+ *   return (
+ *     <div>
+ *       <div>남은 시간: {timeLeft}초</div>
+ *       <button onClick={start} disabled={isRunning}>시작</button>
+ *       <button onClick={pause} disabled={!isRunning}>일시정지</button>
+ *       <button onClick={() => reset()}>리셋</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 완료 콜백과 함께 사용
+ * function Timer() {
+ *   const { timeLeft, start, isCompleted } = useCountdown(10, {
+ *     onComplete: () => {
+ *       alert('타이머 종료!');
+ *     },
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {isCompleted ? (
+ *         <div>완료!</div>
+ *       ) : (
+ *         <div>
+ *           <div>{timeLeft}초</div>
+ *           <button onClick={start}>시작</button>
+ *         </div>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 자동 시작
+ * function AutoTimer() {
+ *   const { timeLeft, pause, resume, isRunning } = useCountdown(30, {
+ *     autoStart: true,
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <div>남은 시간: {timeLeft}초</div>
+ *       {isRunning ? (
+ *         <button onClick={pause}>일시정지</button>
+ *       ) : (
+ *         <button onClick={resume}>재개</button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 동적 시간 변경
+ * function DynamicTimer() {
+ *   const [duration, setDuration] = useState(60);
+ *   const { timeLeft, start, reset } = useCountdown(duration);
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         type="number"
+ *         value={duration}
+ *         onChange={(e) => setDuration(Number(e.target.value))}
+ *       />
+ *       <div>남은 시간: {timeLeft}초</div>
+ *       <button onClick={start}>시작</button>
+ *       <button onClick={() => reset(duration)}>리셋</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useCountdown(initialTime: number, options?: UseCountdownOptions): UseCountdownReturn;
+//# sourceMappingURL=useCountdown.d.ts.map

package/dist/hooks/time/useCountdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCountdown.d.ts","sourceRoot":"","sources":["../../../src/hooks/time/useCountdown.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,mBAAmB;IAClC,yBAAyB;IACzB,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe;IACf,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,iBAAiB;IACjB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,eAAe;IACf,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,eAAe;IACf,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,oBAAoB;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,kBAAkB;IAClB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAqEpB"}

package/dist/hooks/time/useCountdown.js

@@ -0,0 +1,152 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+/**
+ * 카운트다운 타이머 hook
+ *
+ * 지정된 시간부터 0까지 카운트다운하는 타이머를 제공합니다.
+ *
+ * @example
+ * ```tsx
+ * // 기본 사용 - 60초 카운트다운
+ * function Timer() {
+ *   const { timeLeft, start, pause, reset, isRunning } = useCountdown(60);
+ *
+ *   return (
+ *     <div>
+ *       <div>남은 시간: {timeLeft}초</div>
+ *       <button onClick={start} disabled={isRunning}>시작</button>
+ *       <button onClick={pause} disabled={!isRunning}>일시정지</button>
+ *       <button onClick={() => reset()}>리셋</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 완료 콜백과 함께 사용
+ * function Timer() {
+ *   const { timeLeft, start, isCompleted } = useCountdown(10, {
+ *     onComplete: () => {
+ *       alert('타이머 종료!');
+ *     },
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {isCompleted ? (
+ *         <div>완료!</div>
+ *       ) : (
+ *         <div>
+ *           <div>{timeLeft}초</div>
+ *           <button onClick={start}>시작</button>
+ *         </div>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 자동 시작
+ * function AutoTimer() {
+ *   const { timeLeft, pause, resume, isRunning } = useCountdown(30, {
+ *     autoStart: true,
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <div>남은 시간: {timeLeft}초</div>
+ *       {isRunning ? (
+ *         <button onClick={pause}>일시정지</button>
+ *       ) : (
+ *         <button onClick={resume}>재개</button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 동적 시간 변경
+ * function DynamicTimer() {
+ *   const [duration, setDuration] = useState(60);
+ *   const { timeLeft, start, reset } = useCountdown(duration);
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         type="number"
+ *         value={duration}
+ *         onChange={(e) => setDuration(Number(e.target.value))}
+ *       />
+ *       <div>남은 시간: {timeLeft}초</div>
+ *       <button onClick={start}>시작</button>
+ *       <button onClick={() => reset(duration)}>리셋</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useCountdown(initialTime, options = {}) {
+    const { onComplete, interval = 1000, autoStart = false } = options;
+    const [timeLeft, setTimeLeft] = useState(initialTime);
+    const [isRunning, setIsRunning] = useState(autoStart);
+    const [isCompleted, setIsCompleted] = useState(false);
+    const intervalRef = useRef(null);
+    const initialTimeRef = useRef(initialTime);
+    const clear = useCallback(() => {
+        if (intervalRef.current) {
+            clearInterval(intervalRef.current);
+            intervalRef.current = null;
+        }
+    }, []);
+    const start = useCallback(() => {
+        if (isCompleted) {
+            setTimeLeft(initialTimeRef.current);
+            setIsCompleted(false);
+        }
+        setIsRunning(true);
+    }, [isCompleted]);
+    const pause = useCallback(() => {
+        clear();
+        setIsRunning(false);
+    }, [clear]);
+    const resume = useCallback(() => {
+        setIsRunning(true);
+    }, []);
+    const reset = useCallback((newTime) => {
+        clear();
+        const resetTime = newTime !== undefined ? newTime : initialTimeRef.current;
+        initialTimeRef.current = resetTime;
+        setTimeLeft(resetTime);
+        setIsRunning(false);
+        setIsCompleted(false);
+    }, [clear]);
+    useEffect(() => {
+        if (isRunning && timeLeft > 0) {
+            intervalRef.current = setInterval(() => {
+                setTimeLeft((prev) => {
+                    if (prev <= 1) {
+                        setIsRunning(false);
+                        setIsCompleted(true);
+                        onComplete?.();
+                        return 0;
+                    }
+                    return prev - 1;
+                });
+            }, interval);
+            return () => clear();
+        }
+    }, [isRunning, timeLeft, interval, onComplete, clear]);
+    return {
+        timeLeft,
+        start,
+        pause,
+        resume,
+        reset,
+        isRunning,
+        isCompleted,
+    };
+}