feat(hooks): add 'useDoubleClick' (#201)

Co-authored-by: seungrodotlee <seungrodotlee@gmail.com>

Author: sukvvon

src/hooks/useDoubleClick/index.ts

@@ -0,0 +1 @@
+export { useDoubleClick } from './useDoubleClick.ts';

src/hooks/useDoubleClick/useDoubleClick.spec.tsx

@@ -0,0 +1,148 @@
+import { MouseEvent } from 'react';
+import { fireEvent, render } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, Mock, vi } from 'vitest';
+
+import { useDoubleClick } from './useDoubleClick.ts';
+
+function TestComponent({
+  delay = 250,
+  onClick,
+  onDoubleClick,
+}: {
+  delay?: number;
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  onDoubleClick: (event: MouseEvent<HTMLElement>) => void;
+}) {
+  const handleEvent = useDoubleClick({
+    delay,
+    click: onClick,
+    doubleClick: onDoubleClick,
+  });
+
+  return <button onClick={handleEvent}>Test Button</button>;
+}
+
+describe('useDoubleClick', () => {
+  let clickSpy: Mock;
+  let doubleClickSpy: Mock;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    clickSpy = vi.fn();
+    doubleClickSpy = vi.fn();
+  });
+
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+  });
+
+  it('calls single click handler after delay if no double click', async () => {
+    const { getByText } = render(<TestComponent onClick={clickSpy} onDoubleClick={doubleClickSpy} />);
+    const button = getByText('Test Button');
+
+    fireEvent.click(button, { detail: 1 });
+
+    expect(clickSpy).not.toHaveBeenCalled();
+    expect(doubleClickSpy).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(250);
+
+    expect(clickSpy).toHaveBeenCalledTimes(1);
+    expect(doubleClickSpy).not.toHaveBeenCalled();
+  });
+
+  it('calls double click handler instead of single click when clicked twice quickly', () => {
+    const { getByText } = render(<TestComponent onClick={clickSpy} onDoubleClick={doubleClickSpy} />);
+    const button = getByText('Test Button');
+
+    fireEvent.click(button, { detail: 1 });
+    fireEvent.click(button, { detail: 2 });
+
+    vi.advanceTimersByTime(250);
+
+    expect(clickSpy).not.toHaveBeenCalled();
+    expect(doubleClickSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not throw if click is not provided', () => {
+    const { getByText } = render(<TestComponent onDoubleClick={doubleClickSpy} />);
+    const button = getByText('Test Button');
+
+    fireEvent.click(button, { detail: 1 });
+
+    vi.advanceTimersByTime(250);
+
+    expect(doubleClickSpy).not.toHaveBeenCalled();
+  });
+
+  it('calls double click handler only once on double click', () => {
+    const { getByText } = render(<TestComponent onClick={clickSpy} onDoubleClick={doubleClickSpy} />);
+    const button = getByText('Test Button');
+
+    fireEvent.click(button, { detail: 1 });
+    fireEvent.click(button, { detail: 2 });
+
+    vi.advanceTimersByTime(250);
+
+    expect(clickSpy).not.toHaveBeenCalled();
+    expect(doubleClickSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('resets timeout if component unmounts early', () => {
+    const { unmount, getByText } = render(<TestComponent onClick={clickSpy} onDoubleClick={doubleClickSpy} />);
+    const button = getByText('Test Button');
+
+    fireEvent.click(button, { detail: 1 });
+    unmount();
+
+    vi.advanceTimersByTime(250);
+
+    expect(clickSpy).not.toHaveBeenCalled();
+    expect(doubleClickSpy).not.toHaveBeenCalled();
+  });
+
+  it('respects custom delay time', () => {
+    const { getByText } = render(<TestComponent delay={500} onClick={clickSpy} onDoubleClick={doubleClickSpy} />);
+    const button = getByText('Test Button');
+
+    fireEvent.click(button, { detail: 1 });
+
+    vi.advanceTimersByTime(250);
+
+    expect(clickSpy).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(250);
+
+    expect(clickSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not call click if doubleClick is triggered before delay', () => {
+    const { getByText } = render(<TestComponent delay={300} onClick={clickSpy} onDoubleClick={doubleClickSpy} />);
+    const button = getByText('Test Button');
+
+    fireEvent.click(button, { detail: 1 });
+
+    vi.advanceTimersByTime(150);
+
+    fireEvent.click(button, { detail: 2 });
+
+    vi.advanceTimersByTime(150);
+
+    expect(clickSpy).not.toHaveBeenCalled();
+    expect(doubleClickSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('cleans up timers on unmount to prevent memory leaks', () => {
+    const clearTimeoutSpy = vi.spyOn(window, 'clearTimeout');
+    const { unmount, getByText } = render(<TestComponent onClick={clickSpy} onDoubleClick={doubleClickSpy} />);
+    const button = getByText('Test Button');
+
+    fireEvent.click(button, { detail: 1 });
+    unmount();
+
+    vi.advanceTimersByTime(250);
+
+    expect(clearTimeoutSpy).toHaveBeenCalled();
+  });
+});

src/hooks/useDoubleClick/useDoubleClick.ts

@@ -0,0 +1,77 @@
+import { MouseEvent, useCallback, useEffect, useRef } from 'react';
+
+import { usePreservedCallback } from '../usePreservedCallback/index.ts';
+
+type UseDoubleClickProps<E extends HTMLElement> = {
+  delay?: number;
+  click?: (event: MouseEvent<E>) => void;
+  doubleClick: (event: MouseEvent<E>) => void;
+};
+
+/**
+ * @description
+ * `useDoubleClick` is a React hook that differentiates between single and double click events.
+ * It delays the single click callback execution for a specified time, and cancels it if a second click (i.e. a double click) occurs within that time.
+ *
+ * @template {HTMLElement} E - The specific type of HTMLElement to be used with this hook (e.g., HTMLButtonElement, HTMLDivElement).
+ * @param {Object} params - Configuration options for click handling.
+ * @param {number} [params.delay=250] - The number of milliseconds to wait before triggering the single click callback. Defaults to 250ms.
+ * @param {(event: MouseEvent<E>) => void} [params.click] - The callback function to be executed on a single click.
+ * @param {(event: MouseEvent<E>) => void} params.doubleClick - The callback function to be executed on a double click. Required.
+ *
+ * @returns {(event: MouseEvent<E>) => void} A click handler function to attach to an element's `onClick` event.
+ *
+ * @example
+ * function GalleryCard() {
+ *   const [selected, setSelected] = useState(false);
+ *
+ *   const handleClick = () => setSelected((prev) => !prev);
+ *   const handleDoubleClick = () => alert('Zoom in!');
+ *
+ *   const handleEvent = useDoubleClick({
+ *     click: handleClick,
+ *     doubleClick: handleDoubleClick,
+ *   });
+ *
+ *   return (
+ *     <div onClick={handleEvent}>
+ *       {selected ? 'Selected' : 'Not selected'}
+ *     </div>
+ *   );
+ * }
+ */
+export function useDoubleClick<E extends HTMLElement = HTMLElement>({
+  delay = 250,
+  click,
+  doubleClick,
+}: UseDoubleClickProps<E>) {
+  const clickTimeout = useRef<number>(null);
+
+  const clearClickTimeout = usePreservedCallback(() => {
+    if (clickTimeout.current != null) {
+      window.clearTimeout(clickTimeout.current);
+      clickTimeout.current = null;
+    }
+  });
+
+  useEffect(() => () => clearClickTimeout(), [clearClickTimeout]);
+
+  const handleEvent = useCallback(
+    (event: MouseEvent<E>) => {
+      clearClickTimeout();
+
+      if (click && event.detail === 1) {
+        clickTimeout.current = window.setTimeout(() => {
+          click(event);
+        }, delay);
+      }
+
+      if (event.detail === 2) {
+        doubleClick(event);
+      }
+    },
+    [click, doubleClick, delay, clearClickTimeout]
+  );
+
+  return handleEvent;
+}