main 🧊 v0.3.13

Author: debabin

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siberiacancode/reactuse",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "The ultimate collection of react hooks",
   "author": {
     "name": "SIBERIA CAN CODE 🧊",

packages/core/src/bundle/hooks/time.js

@@ -1,5 +1,6 @@
 // timing
 export * from './useInterval/useInterval';
+export * from './useProgress/useProgress';
 export * from './useStopwatch/useStopwatch';
 export * from './useTime/useTime';
 export * from './useTimeout/useTimeout';

packages/core/src/bundle/hooks/useProgress/useProgress.js

@@ -0,0 +1,66 @@
+import { useEffect, useRef, useState } from 'react';
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+const resolveAutoIncrement = (progress, trickleRate) => {
+  if (progress < 0.25) return 0.12 + trickleRate * Math.random();
+  if (progress < 0.5) return 0.08 + trickleRate * Math.random();
+  if (progress < 0.8) return 0.03 + trickleRate * Math.random();
+  if (progress < 0.95) return 0.01 + (trickleRate / 2) * Math.random();
+  if (progress < 0.99) return 0.005 * Math.random();
+  return 0;
+};
+/**
+ * @name useProgress
+ * @description - Hook that creates a lightweight progress bar state with NProgress-like behavior
+ * @category Time
+ * @usage medium
+ *
+ * @param {number} [initialProgress] Initial progress value in range 0..1
+ * @param {boolean} [options.active] Controls progress externally (true -> start, false -> done)
+ * @param {number} [options.maximum=0.95] Maximum value when progress starts
+ * @param {number} [options.speed=250] Auto increment interval in milliseconds
+ * @param {number} [options.rate=0.02] Additional random increment amount on each tick
+ * @param {number} [options.doneResetDelay=250] Delay before reset to null after done
+ * @returns {UseProgressReturn} Current progress state and control methods
+ *
+ * @example
+ * const { value, active, start, done, inc, set, remove } = useProgress(0.2);
+ */
+export const useProgress = (initialValue = 0, options = {}) => {
+  const speed = Math.max(options.speed ?? 250, 16);
+  const rate = clamp(options.rate ?? 0.02, 0, 0.3);
+  const maximum = options.maximum ?? 0.98;
+  const [value, setValue] = useState(initialValue);
+  const [active, setActive] = useState(!!options.immediately);
+  const [internalActive, setInternalActive] = useState(active);
+  const intervalIdRef = useRef(undefined);
+  const done = () => {
+    setValue(1);
+    setInternalActive(false);
+    setTimeout(() => setActive(false), 250);
+  };
+  const inc = (amount = resolveAutoIncrement(value, rate)) =>
+    setValue((currentValue) => clamp(currentValue + amount, initialValue, maximum));
+  const start = (from = initialValue) => {
+    setActive(true);
+    setInternalActive(true);
+    setValue(from);
+  };
+  const remove = () => {
+    setActive(false);
+    setInternalActive(false);
+    setValue(0);
+  };
+  useEffect(() => {
+    if (!internalActive) return;
+    intervalIdRef.current = setInterval(inc, speed);
+    return () => clearInterval(intervalIdRef.current);
+  }, [internalActive, speed, rate]);
+  return {
+    value,
+    active,
+    start,
+    done,
+    inc,
+    remove
+  };
+};

packages/core/src/hooks/time.ts

@@ -1,5 +1,6 @@
 // timing
 export * from './useInterval/useInterval';
+export * from './useProgress/useProgress';
 export * from './useStopwatch/useStopwatch';
 export * from './useTime/useTime';
 export * from './useTimeout/useTimeout';

packages/core/src/hooks/useProgress/useProgress.demo.tsx

@@ -0,0 +1,37 @@
+import { useProgress } from './useProgress';
+
+const Demo = () => {
+  const progress = useProgress(0, {
+    speed: 250
+  });
+
+  const percent = Math.round(progress.value * 100);
+
+  return (
+    <div>
+      {!!progress.active && (
+        <div className='fixed top-0 left-0 z-[9999] h-1.5 w-full bg-sky-400/25'>
+          <div
+            className='h-full bg-sky-400 transition-[width] duration-200 ease-out'
+            style={{ width: `${percent}%` }}
+          />
+        </div>
+      )}
+
+      <div>
+        <p>Click to change progress status</p>
+        <div className='flex items-center gap-2'>
+          <button
+            type='button'
+            onClick={() => (progress.active ? progress.done() : progress.start())}
+          >
+            {progress.active ? 'Done' : 'Start'}
+          </button>
+          {!!progress.active && <span>{percent}%</span>}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default Demo;

packages/core/src/hooks/useProgress/useProgress.test.ts

@@ -0,0 +1,103 @@
+import { act, renderHook } from '@testing-library/react';
+
+import { renderHookServer } from '@/tests';
+
+import { useProgress } from './useProgress';
+
+beforeEach(vi.useFakeTimers);
+afterEach(vi.clearAllTimers);
+
+it('Should use progress', () => {
+  const { result } = renderHook(useProgress);
+
+  expect(result.current.value).toBe(0);
+  expect(result.current.active).toBeFalsy();
+  expect(result.current.start).toBeTypeOf('function');
+  expect(result.current.done).toBeTypeOf('function');
+  expect(result.current.inc).toBeTypeOf('function');
+  expect(result.current.remove).toBeTypeOf('function');
+});
+
+it('Should use progress on server side', () => {
+  const { result } = renderHookServer(useProgress);
+
+  expect(result.current.value).toBe(0);
+  expect(result.current.active).toBeFalsy();
+});
+
+it('Should auto increment and never complete without done', () => {
+  const { result } = renderHook(useProgress);
+
+  act(result.current.start);
+
+  expect(result.current.active).toBeTruthy();
+  expect(result.current.value).toBe(0);
+
+  act(() => vi.advanceTimersByTime(60_000));
+
+  expect(result.current.value).toBeLessThan(1);
+  expect(result.current.value).toBeGreaterThan(0.9);
+});
+
+it('Should complete and reset after done', () => {
+  const { result } = renderHook(() => useProgress(undefined, { speed: 200 }));
+
+  act(result.current.start);
+
+  expect(result.current.value).toBe(0);
+  expect(result.current.active).toBeTruthy();
+
+  act(result.current.done);
+
+  expect(result.current.value).toBe(1);
+  expect(result.current.active).toBeTruthy();
+
+  act(() => vi.advanceTimersByTime(250));
+
+  expect(result.current.active).toBeFalsy();
+});
+
+it('Should respect maximum option', () => {
+  const { result } = renderHook(() => useProgress(0, { maximum: 0.7 }));
+
+  act(result.current.start);
+
+  act(() => vi.advanceTimersByTime(10_000));
+
+  expect(result.current.value).toBeLessThanOrEqual(0.7);
+});
+
+it('Should respect speed option', () => {
+  const { result } = renderHook(() => useProgress(0, { speed: 1000 }));
+
+  act(result.current.start);
+
+  act(() => vi.advanceTimersByTime(999));
+  expect(result.current.value).toBe(0);
+
+  act(() => vi.advanceTimersByTime(1));
+  expect(result.current.value).toBeCloseTo(0.12, 0.13);
+});
+
+it('Should clamp rate option', () => {
+  const randomMock = vi.spyOn(Math, 'random').mockReturnValue(1);
+  const { result } = renderHook(() => useProgress(0, { rate: 100, speed: 700 }));
+
+  act(result.current.start);
+
+  act(() => vi.advanceTimersByTime(700));
+
+  expect(result.current.value).toBeCloseTo(0.42, 0.43);
+
+  randomMock.mockRestore();
+});
+
+it('Should start on mount when immediately enabled', () => {
+  const { result } = renderHook(() => useProgress(0, { immediately: true }));
+
+  expect(result.current.active).toBeTruthy();
+
+  act(() => vi.advanceTimersByTime(1000));
+
+  expect(result.current.value).toBeCloseTo(0.51, 0.53);
+});

packages/core/src/hooks/useProgress/useProgress.ts

@@ -0,0 +1,105 @@
+import { useEffect, useRef, useState } from 'react';
+
+const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max);
+
+const resolveAutoIncrement = (progress: number, trickleRate: number) => {
+  if (progress < 0.25) return 0.12 + trickleRate * Math.random();
+  if (progress < 0.5) return 0.08 + trickleRate * Math.random();
+  if (progress < 0.8) return 0.03 + trickleRate * Math.random();
+  if (progress < 0.95) return 0.01 + (trickleRate / 2) * Math.random();
+  if (progress < 0.99) return 0.005 * Math.random();
+  return 0;
+};
+
+/** The use progress options type */
+export interface UseProgressOptions {
+  /** Start progress immediately */
+  immediately?: boolean;
+  /** Maximum progress value */
+  maximum?: number;
+  /** Additional random amount for each auto increment */
+  rate?: number;
+  /** Auto-increment frequency in milliseconds */
+  speed?: number;
+}
+
+/** The use progress return type */
+export interface UseProgressReturn {
+  /** Whether progress is currently active */
+  active: boolean;
+  /** Current progress value in range 0..1, null means hidden */
+  value: number;
+  /** Complete progress to 100% */
+  done: (force?: boolean) => number | null;
+  /** Increment progress with easing behavior */
+  inc: (amount?: number) => number | null;
+  /** Remove progress and stop timers */
+  remove: () => void;
+  /** Start progress and auto incrementing */
+  start: (from?: number | null) => number;
+}
+
+/**
+ * @name useProgress
+ * @description - Hook that creates a lightweight progress bar state with NProgress-like behavior
+ * @category Time
+ * @usage medium
+ *
+ * @param {number} [initialProgress] Initial progress value in range 0..1
+ * @param {boolean} [options.active] Controls progress externally (true -> start, false -> done)
+ * @param {number} [options.maximum=0.95] Maximum value when progress starts
+ * @param {number} [options.speed=250] Auto increment interval in milliseconds
+ * @param {number} [options.rate=0.02] Additional random increment amount on each tick
+ * @param {number} [options.doneResetDelay=250] Delay before reset to null after done
+ * @returns {UseProgressReturn} Current progress state and control methods
+ *
+ * @example
+ * const { value, active, start, done, inc, set, remove } = useProgress(0.2);
+ */
+export const useProgress = (initialValue: number = 0, options: UseProgressOptions = {}) => {
+  const speed = Math.max(options.speed ?? 250, 16);
+  const rate = clamp(options.rate ?? 0.02, 0, 0.3);
+  const maximum = options.maximum ?? 0.98;
+
+  const [value, setValue] = useState(initialValue);
+  const [active, setActive] = useState(!!options.immediately);
+  const [internalActive, setInternalActive] = useState(active);
+
+  const intervalIdRef = useRef<ReturnType<typeof setInterval>>(undefined);
+
+  const done = () => {
+    setValue(1);
+    setInternalActive(false);
+    setTimeout(() => setActive(false), 250);
+  };
+
+  const inc = (amount: number = resolveAutoIncrement(value, rate)) =>
+    setValue((currentValue) => clamp(currentValue + amount, initialValue, maximum));
+
+  const start = (from: number = initialValue) => {
+    setActive(true);
+    setInternalActive(true);
+    setValue(from);
+  };
+
+  const remove = () => {
+    setActive(false);
+    setInternalActive(false);
+    setValue(0);
+  };
+
+  useEffect(() => {
+    if (!internalActive) return;
+    intervalIdRef.current = setInterval(inc, speed);
+    return () => clearInterval(intervalIdRef.current);
+  }, [internalActive, speed, rate]);
+
+  return {
+    value,
+    active,
+    start,
+    done,
+    inc,
+    remove
+  };
+};