Merge pull request #181 from Nurvive/feat/useVibrate

[feat]: useVibrate

Author: debabin

src/hooks/index.ts

@@ -104,4 +104,4 @@ export * from './useWindowEvent/useWindowEvent';
 export * from './useWindowFocus/useWindowFocus';
 export * from './useWindowScroll/useWindowScroll';
 export * from './useWindowSize/useWindowSize';
-export * from './useWizard/useWizard';
+export * from './useWizard/useWizard';

src/hooks/useVibrate/useVibrate.demo.tsx

@@ -0,0 +1,20 @@
+import { useVibrate } from './useVibrate';
+
+const Demo = () => {
+  const { isSupported, isVibrating, vibrate, stop } = useVibrate({
+    pattern: [300, 100, 200, 100, 1000, 300]
+  });
+
+  return (
+    <div>
+      <button type='button' disabled={!isSupported || isVibrating} onClick={() => vibrate()}>
+        {isSupported ? 'Vibrate' : 'Web vibrate is not supported in your browser'}
+      </button>
+      <button type='button' disabled={!isSupported} onClick={() => stop()}>
+        Stop
+      </button>
+    </div>
+  );
+};
+
+export default Demo;

src/hooks/useVibrate/useVibrate.test.ts

@@ -0,0 +1,84 @@
+import { act, renderHook } from '@testing-library/react';
+
+import { useVibrate } from './useVibrate';
+
+const vibrateMock = vi.fn();
+
+describe('useVibrate', () => {
+  beforeAll(() => {
+    Object.defineProperty(navigator, 'vibrate', {
+      writable: true,
+      value: vibrateMock
+    });
+  });
+
+  it('should indicate support for vibration API', () => {
+    const { result } = renderHook(() => useVibrate(1000));
+
+    expect(result.current.isSupported).toBe(true);
+  });
+
+  it('should start and stop vibration', () => {
+    const { result } = renderHook(() => useVibrate(1000));
+
+    act(() => {
+      result.current.vibrate();
+    });
+
+    expect(vibrateMock).toHaveBeenCalledWith(1000);
+    expect(result.current.isVibrating).toBe(true);
+
+    act(() => {
+      result.current.stop();
+    });
+
+    expect(vibrateMock).toHaveBeenCalledWith(0);
+    expect(result.current.isVibrating).toBe(false);
+  });
+
+  it('should handle looped vibration', () => {
+    vi.useFakeTimers();
+    const { result } = renderHook(() => useVibrate({ pattern: [200, 100, 200], loop: true }));
+
+    act(() => {
+      result.current.vibrate();
+    });
+
+    expect(vibrateMock).toHaveBeenCalledWith([200, 100, 200]);
+    expect(result.current.isVibrating).toBe(true);
+
+    vi.advanceTimersByTime(500);
+
+    expect(vibrateMock).toHaveBeenCalledTimes(2);
+
+    act(() => {
+      result.current.stop();
+    });
+
+    expect(vibrateMock).toHaveBeenCalledWith(0);
+    expect(result.current.isVibrating).toBe(false);
+
+    vi.useRealTimers();
+  });
+
+  it('should respect the enabled parameter', () => {
+    const { result, rerender } = renderHook(
+      ({ enabled }) => useVibrate({ pattern: [200, 100, 200], enabled }),
+      {
+        initialProps: { enabled: false }
+      }
+    );
+
+    expect(result.current.isVibrating).toBe(false);
+
+    rerender({ enabled: true });
+
+    expect(result.current.isVibrating).toBe(true);
+    expect(vibrateMock).toHaveBeenCalledWith([200, 100, 200]);
+
+    rerender({ enabled: false });
+
+    expect(result.current.isVibrating).toBe(false);
+    expect(vibrateMock).toHaveBeenCalledWith(0);
+  });
+});

src/hooks/useVibrate/useVibrate.ts

@@ -0,0 +1,129 @@
+import { useEffect, useState } from 'react';
+
+import { isClient } from '@/utils/helpers';
+
+/** The use vibration params */
+export interface UseVibrateParams {
+  /** Pattern for vibration */
+  pattern: number | number[];
+  /** Alternate way to enable vibration */
+  enabled?: boolean;
+  /** Indicates thar vibration will be endless */
+  loop?: boolean;
+}
+
+/** The use vibration options */
+export interface UseVibrateOptions {
+  /** Alternate way to enable vibration */
+  enabled?: boolean;
+  /** Indicates thar vibration will be endless */
+  loop?: boolean;
+}
+
+/** The use vibration return type */
+export interface UseVibrateReturn {
+  /** Indicates that the device supports Vibration API */
+  isSupported: boolean;
+  /** Indicates that the device is vibrating */
+  isVibrating: boolean;
+  /** Start vibration function */
+  vibrate: (pattern?: number | number[]) => void;
+  /** Stop vibration function */
+  stop: () => void;
+}
+
+export type UseVibrate = {
+  (pattern: number | number[], options?: UseVibrateOptions): UseVibrateReturn;
+  ({ pattern, loop, enabled }: UseVibrateParams, options?: never): UseVibrateReturn;
+};
+
+let interval: NodeJS.Timeout;
+/**
+ * @name useVibrate
+ * @description - Hook that provides Vibrate API
+ * @category Browser
+ *
+ * @overload
+ * @param {(number|number[])} pattern Pattern for vibration
+ * @param {boolean} [options.loop] Indicates thar vibration will be endless
+ * @param {boolean} [options.enabled] Alternate way to enable vibration
+ * @returns {UseVibrateReturn} An object containing support indicator, start vibration and stop vibration functions
+ *
+ * @example
+ * const { isSupported, isVibrating, vibrate, stop } = useVibrate(1000);
+ *
+ * @overload
+ * @param {(number|number[])} params.pattern Pattern for vibration
+ * @param {boolean} [params.loop] Indicates thar vibration will be endless
+ * @param {boolean} [params.enabled] Alternate way to enable vibration
+ * @returns {UseVibrateReturn} An object containing support indicator, vibrating indicator, start vibration and stop vibration functions
+ *
+ * @example
+ * const { isSupported, isVibrating, vibrate, stop } = useVibrate({pattern: [200, 100, 200], loop: true});
+ * */
+export const useVibrate: UseVibrate = (...params) => {
+  const pattern =
+    typeof params[0] === 'number' || Array.isArray(params[0]) ? params[0] : params[0]?.pattern;
+  const { loop, enabled } =
+    typeof params[0] === 'number' || Array.isArray(params[0]) ? params[1] ?? {} : params[0] ?? {};
+
+  const [isSupported, setIsSupported] = useState(false);
+  const [isVibrating, setIsVibrating] = useState(false);
+
+  useEffect(() => {
+    if (isClient && navigator && 'vibrate' in navigator) {
+      setIsSupported(true);
+    }
+  }, []);
+
+  const vibrate = (curPattern = pattern) => {
+    if (!isSupported || isVibrating) return;
+
+    const duration = Array.isArray(curPattern) ? curPattern.reduce((a, b) => a + b) : curPattern;
+
+    setIsVibrating(true);
+    navigator.vibrate(curPattern);
+
+    if (loop) {
+      interval = setInterval(() => {
+        navigator.vibrate(curPattern);
+      }, duration);
+    } else {
+      setTimeout(() => {
+        setIsVibrating(false);
+      }, duration);
+    }
+  };
+
+  const stop = () => {
+    if (!isSupported) return;
+
+    setIsVibrating(false);
+    navigator.vibrate(0);
+
+    if (loop) {
+      clearInterval(interval);
+    }
+  };
+
+  useEffect(() => {
+    if (!isSupported || isVibrating) return;
+
+    if (enabled) {
+      vibrate();
+    }
+
+    return () => {
+      if (enabled) {
+        setIsVibrating(false);
+        navigator.vibrate(0);
+
+        if (loop) {
+          clearInterval(interval);
+        }
+      }
+    };
+  }, [enabled]);
+
+  return { isSupported, vibrate, stop, isVibrating } as const;
+};