@boxcustodia/library 2.0.0-alpha.19 → 2.0.0-alpha.20

package/src/hooks/use-hover/use-hover.test.tsx

@@ -1,17 +1,33 @@
-import { fireEvent, render, screen } from "@testing-library/react";
-import { describe, expect, it, vi } from "vitest";
+import {
+  act,
+  fireEvent,
+  render,
+  renderHook,
+  screen,
+} from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { useHover } from "./use-hover";
 
+// ---------------------------------------------------------------------------
+// Test component helpers
+// ---------------------------------------------------------------------------
+
 function HoverTarget({
   onHoverStart,
   onHoverEnd,
+  openDelay,
+  closeDelay,
 }: {
-  onHoverStart?: (event: MouseEvent) => void;
-  onHoverEnd?: (event: MouseEvent) => void;
+  onHoverStart?: (event: PointerEvent) => void;
+  onHoverEnd?: (event: PointerEvent) => void;
+  openDelay?: number;
+  closeDelay?: number;
 }) {
   const { ref, hovered } = useHover<HTMLDivElement>({
     onHoverStart,
     onHoverEnd,
+    openDelay,
+    closeDelay,
   });
   return (
     <div ref={ref} data-testid="target">
@@ -20,73 +36,297 @@ function HoverTarget({
   );
 }
 
-describe("useHover", () => {
-  it("starts in the idle state", () => {
+// ---------------------------------------------------------------------------
+// Pointer Event Subscription (R-PointerEvent)
+// ---------------------------------------------------------------------------
+
+describe("useHover — pointer event subscription", () => {
+  it("1: initial state — hovered is false and ref is a callable RefCallback", () => {
+    const { result } = renderHook(() => useHover());
+    expect(result.current.hovered).toBe(false);
+    expect(typeof result.current.ref).toBe("function");
+  });
+
+  it("2: pointerenter sets hovered to true", () => {
+    render(<HoverTarget />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+
+    expect(target).toHaveTextContent("hovered");
+  });
+
+  it("3: pointerleave sets hovered to false", () => {
     render(<HoverTarget />);
-    expect(screen.getByTestId("target")).toHaveTextContent("idle");
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    expect(target).toHaveTextContent("hovered");
+
+    fireEvent.pointerLeave(target);
+    expect(target).toHaveTextContent("idle");
   });
 
-  it("flips hovered to true on mouseenter and back on mouseleave", () => {
+  it("4: mouseenter does NOT change state (regression guard)", () => {
     render(<HoverTarget />);
     const target = screen.getByTestId("target");
 
     fireEvent.mouseEnter(target);
+
+    expect(target).toHaveTextContent("idle");
+  });
+
+  it("5: mouseleave does NOT change state (regression guard)", () => {
+    render(<HoverTarget />);
+    const target = screen.getByTestId("target");
+
+    // Manually set hovered via pointer first
+    fireEvent.pointerEnter(target);
     expect(target).toHaveTextContent("hovered");
 
     fireEvent.mouseLeave(target);
+
+    expect(target).toHaveTextContent("hovered");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Open Delay (R-OpenDelay)
+// ---------------------------------------------------------------------------
+
+describe("useHover — openDelay", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("6: openDelay=0 — hovered flips immediately on pointerenter (no timer)", () => {
+    render(<HoverTarget openDelay={0} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+
+    expect(target).toHaveTextContent("hovered");
+  });
+
+  it("7: openDelay=300 — hovered stays false until timer fires", () => {
+    render(<HoverTarget openDelay={300} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
     expect(target).toHaveTextContent("idle");
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(target).toHaveTextContent("hovered");
   });
 
-  it("ignores mouseover/mouseout (which bubble from children)", () => {
-    render(<HoverTarget />);
+  it("8: openDelay=300 — leave before timer fires cancels open, hovered never becomes true", () => {
+    render(<HoverTarget openDelay={300} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    expect(target).toHaveTextContent("idle");
+
+    fireEvent.pointerLeave(target);
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(target).toHaveTextContent("idle");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Close Delay (R-CloseDelay)
+// ---------------------------------------------------------------------------
+
+describe("useHover — closeDelay", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("9: closeDelay=0 — hovered flips immediately on pointerleave (no timer)", () => {
+    render(<HoverTarget closeDelay={0} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    expect(target).toHaveTextContent("hovered");
+
+    fireEvent.pointerLeave(target);
+
+    expect(target).toHaveTextContent("idle");
+  });
+
+  it("10: closeDelay=200 — hovered stays true until timer fires", () => {
+    render(<HoverTarget closeDelay={200} />);
     const target = screen.getByTestId("target");
 
-    fireEvent.mouseOver(target);
+    fireEvent.pointerEnter(target);
+    expect(target).toHaveTextContent("hovered");
+
+    fireEvent.pointerLeave(target);
+    expect(target).toHaveTextContent("hovered");
+
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
     expect(target).toHaveTextContent("idle");
   });
 
-  it("invokes onHoverStart with the MouseEvent on enter", () => {
+  it("11: closeDelay=200 — re-enter before close timer fires cancels close, hovered remains true", () => {
+    render(<HoverTarget closeDelay={200} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    fireEvent.pointerLeave(target);
+    expect(target).toHaveTextContent("hovered");
+
+    // Re-enter before close timer fires
+    fireEvent.pointerEnter(target);
+
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(target).toHaveTextContent("hovered");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Callback Invocation (R-Callbacks)
+// ---------------------------------------------------------------------------
+
+describe("useHover — callbacks", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("12: onHoverStart is called on pointer enter (after open delay)", () => {
     const onHoverStart = vi.fn();
-    render(<HoverTarget onHoverStart={onHoverStart} />);
+    render(<HoverTarget onHoverStart={onHoverStart} openDelay={100} />);
     const target = screen.getByTestId("target");
 
-    fireEvent.mouseEnter(target);
+    fireEvent.pointerEnter(target);
+    expect(onHoverStart).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
 
     expect(onHoverStart).toHaveBeenCalledTimes(1);
-    expect(onHoverStart.mock.calls[0][0]).toBeInstanceOf(MouseEvent);
   });
 
-  it("invokes onHoverEnd with the MouseEvent on leave", () => {
+  it("13: onHoverEnd is called on pointer leave (after close delay)", () => {
     const onHoverEnd = vi.fn();
-    render(<HoverTarget onHoverEnd={onHoverEnd} />);
+    render(<HoverTarget onHoverEnd={onHoverEnd} closeDelay={100} />);
     const target = screen.getByTestId("target");
 
-    fireEvent.mouseEnter(target);
-    fireEvent.mouseLeave(target);
+    fireEvent.pointerEnter(target);
+    fireEvent.pointerLeave(target);
+    expect(onHoverEnd).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
 
     expect(onHoverEnd).toHaveBeenCalledTimes(1);
-    expect(onHoverEnd.mock.calls[0][0]).toBeInstanceOf(MouseEvent);
   });
 
-  it("uses the latest callback identity without re-attaching listeners", () => {
+  it("14: callbacks receive the originating PointerEvent (behavioral assertion + guarded instanceof)", () => {
+    const onHoverStart = vi.fn();
+    const onHoverEnd = vi.fn();
+    render(<HoverTarget onHoverStart={onHoverStart} onHoverEnd={onHoverEnd} />);
+    const target = screen.getByTestId("target");
+
+    fireEvent.pointerEnter(target);
+    fireEvent.pointerLeave(target);
+
+    expect(onHoverStart).toHaveBeenCalledTimes(1);
+    expect(onHoverStart.mock.calls[0][0]).toMatchObject({
+      type: "pointerenter",
+    });
+
+    expect(onHoverEnd).toHaveBeenCalledTimes(1);
+    expect(onHoverEnd.mock.calls[0][0]).toMatchObject({ type: "pointerleave" });
+
+    // Guard: jsdom may not expose PointerEvent as a constructor
+    if (typeof window.PointerEvent === "function") {
+      expect(onHoverStart.mock.calls[0][0]).toBeInstanceOf(PointerEvent);
+      expect(onHoverEnd.mock.calls[0][0]).toBeInstanceOf(PointerEvent);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Latest-Ref Callback Pattern (R-LatestRef)
+// ---------------------------------------------------------------------------
+
+describe("useHover — latest-ref callback stability", () => {
+  it("15: callback identity stable — re-render with new function identity calls latest fn without re-attaching", () => {
     const first = vi.fn();
     const second = vi.fn();
     const { rerender } = render(<HoverTarget onHoverStart={first} />);
     const target = screen.getByTestId("target");
 
     rerender(<HoverTarget onHoverStart={second} />);
-    fireEvent.mouseEnter(target);
+    fireEvent.pointerEnter(target);
 
     expect(first).not.toHaveBeenCalled();
     expect(second).toHaveBeenCalledTimes(1);
   });
+});
 
-  it("removes listeners on unmount", () => {
-    const { unmount } = render(<HoverTarget />);
+// ---------------------------------------------------------------------------
+// Timer Cleanup (R-TimerCleanup)
+// ---------------------------------------------------------------------------
+
+describe("useHover — timer cleanup on unmount", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("16: unmount cancels pending open timer — no state update after unmount", () => {
+    const onHoverStart = vi.fn();
+    const { unmount } = render(
+      <HoverTarget openDelay={300} onHoverStart={onHoverStart} />,
+    );
     const target = screen.getByTestId("target");
 
-    fireEvent.mouseEnter(target);
-    expect(target).toHaveTextContent("hovered");
+    fireEvent.pointerEnter(target);
+    expect(target).toHaveTextContent("idle");
+
+    unmount();
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    // onHoverStart must not have been called after unmount
+    expect(onHoverStart).not.toHaveBeenCalled();
+  });
+
+  it("17: unmount with no pending timers — no throw", () => {
+    const { unmount } = render(<HoverTarget />);
 
     expect(() => unmount()).not.toThrow();
   });

package/src/hooks/use-hover/use-hover.tsx

@@ -1,10 +1,21 @@
-import { type RefCallback, useCallback, useRef, useState } from "react";
+import {
+  type RefCallback,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { useLatestRef } from "../internal";
 
 export interface UseHoverInput {
-  /** Fired when the pointer enters the target element. Receives the native MouseEvent. */
-  onHoverStart?: (event: MouseEvent) => void;
-  /** Fired when the pointer leaves the target element. Receives the native MouseEvent. */
-  onHoverEnd?: (event: MouseEvent) => void;
+  /** Delay in ms before `hovered` becomes true after pointer enters. Default 0 (synchronous). */
+  openDelay?: number;
+  /** Delay in ms before `hovered` becomes false after pointer leaves. Default 0 (synchronous). */
+  closeDelay?: number;
+  /** Fired when the pointer enters the target element. Receives the native PointerEvent. */
+  onHoverStart?: (event: PointerEvent) => void;
+  /** Fired when the pointer leaves the target element. Receives the native PointerEvent. */
+  onHoverEnd?: (event: PointerEvent) => void;
 }
 
 export interface UseHoverReturnValue<T extends HTMLElement = HTMLElement> {
@@ -15,31 +26,85 @@ export interface UseHoverReturnValue<T extends HTMLElement = HTMLElement> {
 export function useHover<T extends HTMLElement = HTMLElement>(
   options: UseHoverInput = {},
 ): UseHoverReturnValue<T> {
+  const { openDelay = 0, closeDelay = 0, onHoverStart, onHoverEnd } = options;
+
   const [hovered, setHovered] = useState(false);
-  const callbacksRef = useRef(options);
-  callbacksRef.current = options;
-
-  const ref: RefCallback<T> = useCallback((node) => {
-    if (!node) return;
-
-    const handleEnter = (event: MouseEvent) => {
-      setHovered(true);
-      callbacksRef.current.onHoverStart?.(event);
-    };
-    const handleLeave = (event: MouseEvent) => {
-      setHovered(false);
-      callbacksRef.current.onHoverEnd?.(event);
-    };
-
-    node.addEventListener("mouseenter", handleEnter);
-    node.addEventListener("mouseleave", handleLeave);
-
-    return () => {
-      node.removeEventListener("mouseenter", handleEnter);
-      node.removeEventListener("mouseleave", handleLeave);
-      setHovered(false);
-    };
+
+  const onStartRef = useLatestRef(onHoverStart);
+  const onEndRef = useLatestRef(onHoverEnd);
+
+  const openTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const closeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const clearOpenTimer = useCallback(() => {
+    if (openTimerRef.current !== null) {
+      clearTimeout(openTimerRef.current);
+      openTimerRef.current = null;
+    }
+  }, []);
+
+  const clearCloseTimer = useCallback(() => {
+    if (closeTimerRef.current !== null) {
+      clearTimeout(closeTimerRef.current);
+      closeTimerRef.current = null;
+    }
   }, []);
 
+  const ref: RefCallback<T> = useCallback(
+    (node) => {
+      if (!node) return;
+
+      const handleEnter = (event: PointerEvent) => {
+        clearCloseTimer();
+        if (openDelay > 0) {
+          openTimerRef.current = setTimeout(() => {
+            openTimerRef.current = null;
+            setHovered(true);
+            onStartRef.current?.(event);
+          }, openDelay);
+        } else {
+          setHovered(true);
+          onStartRef.current?.(event);
+        }
+      };
+
+      const handleLeave = (event: PointerEvent) => {
+        clearOpenTimer();
+        if (closeDelay > 0) {
+          closeTimerRef.current = setTimeout(() => {
+            closeTimerRef.current = null;
+            setHovered(false);
+            onEndRef.current?.(event);
+          }, closeDelay);
+        } else {
+          setHovered(false);
+          onEndRef.current?.(event);
+        }
+      };
+
+      node.addEventListener("pointerenter", handleEnter);
+      node.addEventListener("pointerleave", handleLeave);
+
+      return () => {
+        node.removeEventListener("pointerenter", handleEnter);
+        node.removeEventListener("pointerleave", handleLeave);
+        clearOpenTimer();
+        clearCloseTimer();
+        setHovered(false);
+      };
+    },
+    [openDelay, closeDelay, clearOpenTimer, clearCloseTimer],
+  );
+
+  // Unmount safety net: covers Suspense/concurrent remount races where a
+  // delayed timer could fire after the hook lifecycle ends.
+  useEffect(
+    () => () => {
+      clearOpenTimer();
+      clearCloseTimer();
+    },
+    [clearOpenTimer, clearCloseTimer],
+  );
+
   return { hovered, ref };
 }