feat: manual control of useSimulatePorgress startup

Author: mintsweet

__test__/use-simulate-progress.test.ts

@@ -6,70 +6,75 @@ import { useSimulateProgress } from '../src';
 jest.useFakeTimers();
 
 describe('useSimulateProgress', () => {
-  it('should update progress periodically and reach 100%', () => {
+  test('should not start progress automatically', () => {
     const mockCallback = jest.fn();
     const { result } = renderHook(() =>
       useSimulateProgress(1000, mockCallback),
     );
 
-    // Initial progress should be 0
-    expect(result.current).toBe(0);
+    // Progress should initially be 0
+    expect(result.current[0]).toBe(0);
+
+    // Progress should not change before startProgress is called
+    act(() => {
+      jest.advanceTimersByTime(500); // Fast-forward 500ms
+    });
+    expect(result.current[0]).toBe(0);
+  });
+
+  test('should update progress when startProgress is called', () => {
+    const mockCallback = jest.fn();
+    const { result } = renderHook(() =>
+      useSimulateProgress(1000, mockCallback),
+    );
+
+    // Call startProgress to trigger the progress
+    act(() => {
+      result.current[1](); // Call startProgress
+    });
 
     // Fast-forward the timer, simulating time passing
     act(() => {
-      jest.advanceTimersByTime(250);
+      jest.advanceTimersByTime(250); // Fast-forward 250ms
     });
 
     // Progress should update to 25%
-    expect(result.current).toBe(25);
+    expect(result.current[0]).toBe(25);
 
     act(() => {
       jest.advanceTimersByTime(500); // Fast-forward another 500ms
     });
 
     // Progress should update to 75%
-    expect(result.current).toBe(75);
+    expect(result.current[0]).toBe(75);
 
     act(() => {
       jest.advanceTimersByTime(250); // Finish the remaining time
     });
 
     // Progress should be 100%, and callback should be called
-    expect(result.current).toBe(100);
+    expect(result.current[0]).toBe(100);
     expect(mockCallback).toHaveBeenCalledTimes(1);
   });
 
-  it('should not call callback if progress is less than 100%', () => {
+  test('should clear interval when unmounted', () => {
     const mockCallback = jest.fn();
-    const { result } = renderHook(() =>
+    const { result, unmount } = renderHook(() =>
       useSimulateProgress(1000, mockCallback),
     );
 
-    // Fast-forward the timer to 50%
+    // Call startProgress to trigger the progress
     act(() => {
-      jest.advanceTimersByTime(500); // Fast-forward 500ms
+      result.current[1](); // Call startProgress
     });
 
-    // Progress should be 50%
-    expect(result.current).toBe(50);
-
-    // Callback should not be called
-    expect(mockCallback).not.toHaveBeenCalled();
-  });
-
-  test('should clear interval when unmounted', () => {
-    const mockCallback = jest.fn();
-    const { result, unmount } = renderHook(() =>
-      useSimulateProgress(1000, mockCallback),
-    );
-
     // Fast-forward the timer halfway
     act(() => {
       jest.advanceTimersByTime(500);
     });
 
     // Progress should be 50%
-    expect(result.current).toBe(50);
+    expect(result.current[0]).toBe(50);
 
     // Unmount the component
     unmount();
@@ -80,7 +85,7 @@ describe('useSimulateProgress', () => {
     });
 
     // Progress should not update further
-    expect(result.current).toBe(50);
+    expect(result.current[0]).toBe(50);
 
     // Callback should not be called
     expect(mockCallback).not.toHaveBeenCalled();

docs/use-simulate-progress.md

@@ -8,7 +8,7 @@
 import { useSimulateProgress } from '@mints/hooks';
 
 const Example = () => {
-  const progress = useSimulateProgress(duration, () => {
+  const [progress, startProgress] = useSimulateProgress(duration, () => {
     console.log('Progress complete!');
   });
 
@@ -17,6 +17,7 @@ const Example = () => {
       className="progress-bar"
       style={{ width: '100%', background: '#e0e0e0', height: '30px' }}
     >
+      <div onClick={startProgress}>Start Progress</div>
       <div
         style={{
           width: `${progress}%`,
@@ -36,8 +37,10 @@ const Example = () => {
 ## API
 
 ```typescript
+type func = (...args: any[]) => void;
+
 useSimulateProgress = (
   duration: number,
-  onComplete: () => void,
-): number
+  onComplete: func,
+): [number, func]
 ```

src/use-simulate-progress.ts

@@ -1,25 +1,39 @@
-import { useState, useEffect } from 'react';
+import { useState, useEffect, useRef } from 'react';
+
+type func = (...args: any[]) => void;
 
 export const useSimulateProgress = (
   duration: number,
-  onComplete: () => void,
-) => {
+  onComplete: func,
+): [number, func] => {
   const [progress, setProgress] = useState(0);
+  const intervalRef = useRef<any>(null);
+
+  const startProgress: func = (...args) => {
+    if (intervalRef.current) return;
 
-  useEffect(() => {
     let progressValue = 0;
-    const interval = setInterval(() => {
+    intervalRef.current = setInterval(() => {
       progressValue += 5;
       setProgress(progressValue);
 
       if (progressValue >= 100) {
-        clearInterval(interval);
-        onComplete();
+        clearInterval(intervalRef.current);
+        intervalRef.current = null;
+        onComplete(...args);
       }
     }, duration / 20);
+  };
 
-    return () => clearInterval(interval);
-  }, [duration, onComplete]);
+  useEffect(() => {
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+      }
+    };
+  }, []);
 
-  return progress;
+  return [progress, startProgress];
 };
+
+export default useSimulateProgress;