react-panel-layout 0.5.2 → 0.6.1

package/src/hooks/gesture/usePointerTracking.spec.ts

@@ -0,0 +1,364 @@
+/**
+ * @file Tests for usePointerTracking hook.
+ */
+/* eslint-disable no-restricted-globals -- test requires vi for timing control */
+import { act, renderHook } from "@testing-library/react";
+import { usePointerTracking } from "./usePointerTracking.js";
+
+describe("usePointerTracking", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe("initialization", () => {
+    it("starts with idle state", () => {
+      const { result } = renderHook(() =>
+        usePointerTracking({ enabled: true }),
+      );
+
+      expect(result.current.state).toEqual({
+        isDown: false,
+        start: null,
+        current: null,
+        pointerId: null,
+        wasCanceled: false,
+      });
+    });
+  });
+
+  describe("pointer down handling", () => {
+    it("tracks pointer down with position and timestamp", () => {
+      const { result } = renderHook(() =>
+        usePointerTracking({ enabled: true }),
+      );
+
+      const mockEvent = {
+        clientX: 100,
+        clientY: 200,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent;
+
+      act(() => {
+        result.current.onPointerDown(mockEvent);
+      });
+
+      expect(result.current.state.isDown).toBe(true);
+      expect(result.current.state.start?.x).toBe(100);
+      expect(result.current.state.start?.y).toBe(200);
+      expect(result.current.state.pointerId).toBe(1);
+    });
+
+    it("ignores non-primary pointers when primaryOnly is true", () => {
+      const { result } = renderHook(() =>
+        usePointerTracking({ enabled: true, primaryOnly: true }),
+      );
+
+      const mockEvent = {
+        clientX: 100,
+        clientY: 200,
+        pointerId: 2,
+        isPrimary: false,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent;
+
+      act(() => {
+        result.current.onPointerDown(mockEvent);
+      });
+
+      expect(result.current.state.isDown).toBe(false);
+    });
+
+    it("allows non-primary pointers when primaryOnly is false", () => {
+      const { result } = renderHook(() =>
+        usePointerTracking({ enabled: true, primaryOnly: false }),
+      );
+
+      const mockEvent = {
+        clientX: 100,
+        clientY: 200,
+        pointerId: 2,
+        isPrimary: false,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent;
+
+      act(() => {
+        result.current.onPointerDown(mockEvent);
+      });
+
+      expect(result.current.state.isDown).toBe(true);
+    });
+
+    it("ignores non-left mouse button clicks", () => {
+      const { result } = renderHook(() =>
+        usePointerTracking({ enabled: true }),
+      );
+
+      const mockEvent = {
+        clientX: 100,
+        clientY: 200,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "mouse",
+        button: 2, // Right click
+      } as React.PointerEvent;
+
+      act(() => {
+        result.current.onPointerDown(mockEvent);
+      });
+
+      expect(result.current.state.isDown).toBe(false);
+    });
+
+    it("ignores events when disabled", () => {
+      const { result } = renderHook(() =>
+        usePointerTracking({ enabled: false }),
+      );
+
+      const mockEvent = {
+        clientX: 100,
+        clientY: 200,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent;
+
+      act(() => {
+        result.current.onPointerDown(mockEvent);
+      });
+
+      expect(result.current.state.isDown).toBe(false);
+    });
+  });
+
+  describe("pointer move handling", () => {
+    it("updates current position on pointer move", () => {
+      const { result } = renderHook(() =>
+        usePointerTracking({ enabled: true }),
+      );
+
+      // Pointer down first
+      const downEvent = {
+        clientX: 100,
+        clientY: 200,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent;
+
+      act(() => {
+        result.current.onPointerDown(downEvent);
+      });
+
+      // Simulate pointer move via document event
+      const moveEvent = new PointerEvent("pointermove", {
+        clientX: 150,
+        clientY: 250,
+        pointerId: 1,
+      });
+
+      act(() => {
+        document.dispatchEvent(moveEvent);
+      });
+
+      expect(result.current.state.current?.x).toBe(150);
+      expect(result.current.state.current?.y).toBe(250);
+      // Start position should remain unchanged
+      expect(result.current.state.start?.x).toBe(100);
+      expect(result.current.state.start?.y).toBe(200);
+    });
+
+    it("ignores move events for different pointer ID", () => {
+      const { result } = renderHook(() =>
+        usePointerTracking({ enabled: true }),
+      );
+
+      const downEvent = {
+        clientX: 100,
+        clientY: 200,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent;
+
+      act(() => {
+        result.current.onPointerDown(downEvent);
+      });
+
+      // Move event with different pointer ID
+      const moveEvent = new PointerEvent("pointermove", {
+        clientX: 150,
+        clientY: 250,
+        pointerId: 2, // Different pointer
+      });
+
+      act(() => {
+        document.dispatchEvent(moveEvent);
+      });
+
+      // Current should still be at start position
+      expect(result.current.state.current?.x).toBe(100);
+      expect(result.current.state.current?.y).toBe(200);
+    });
+  });
+
+  describe("pointer end handling", () => {
+    it("resets state on pointer up", () => {
+      const { result } = renderHook(() =>
+        usePointerTracking({ enabled: true }),
+      );
+
+      const downEvent = {
+        clientX: 100,
+        clientY: 200,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent;
+
+      act(() => {
+        result.current.onPointerDown(downEvent);
+      });
+
+      expect(result.current.state.isDown).toBe(true);
+
+      // Pointer up
+      const upEvent = new PointerEvent("pointerup", { pointerId: 1 });
+
+      act(() => {
+        document.dispatchEvent(upEvent);
+      });
+
+      expect(result.current.state.isDown).toBe(false);
+      expect(result.current.state.start).toBe(null);
+      expect(result.current.state.current).toBe(null);
+      expect(result.current.state.pointerId).toBe(null);
+    });
+
+    it("resets state on pointer cancel and sets wasCanceled flag", () => {
+      const { result } = renderHook(() =>
+        usePointerTracking({ enabled: true }),
+      );
+
+      const downEvent = {
+        clientX: 100,
+        clientY: 200,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent;
+
+      act(() => {
+        result.current.onPointerDown(downEvent);
+      });
+
+      const cancelEvent = new PointerEvent("pointercancel", { pointerId: 1 });
+
+      act(() => {
+        document.dispatchEvent(cancelEvent);
+      });
+
+      expect(result.current.state.isDown).toBe(false);
+      expect(result.current.state.wasCanceled).toBe(true);
+    });
+
+    it("does not set wasCanceled on normal pointer up", () => {
+      const { result } = renderHook(() =>
+        usePointerTracking({ enabled: true }),
+      );
+
+      const downEvent = {
+        clientX: 100,
+        clientY: 200,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent;
+
+      act(() => {
+        result.current.onPointerDown(downEvent);
+      });
+
+      const upEvent = new PointerEvent("pointerup", { pointerId: 1 });
+
+      act(() => {
+        document.dispatchEvent(upEvent);
+      });
+
+      expect(result.current.state.isDown).toBe(false);
+      expect(result.current.state.wasCanceled).toBe(false);
+    });
+  });
+
+  describe("reset", () => {
+    it("manually resets state", () => {
+      const { result } = renderHook(() =>
+        usePointerTracking({ enabled: true }),
+      );
+
+      const downEvent = {
+        clientX: 100,
+        clientY: 200,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent;
+
+      act(() => {
+        result.current.onPointerDown(downEvent);
+      });
+
+      expect(result.current.state.isDown).toBe(true);
+
+      act(() => {
+        result.current.reset();
+      });
+
+      expect(result.current.state.isDown).toBe(false);
+    });
+  });
+
+  describe("enabled toggle", () => {
+    it("resets state when disabled while tracking", () => {
+      const { result, rerender } = renderHook(
+        ({ enabled }) => usePointerTracking({ enabled }),
+        { initialProps: { enabled: true } },
+      );
+
+      const downEvent = {
+        clientX: 100,
+        clientY: 200,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent;
+
+      act(() => {
+        result.current.onPointerDown(downEvent);
+      });
+
+      expect(result.current.state.isDown).toBe(true);
+
+      // Disable tracking
+      rerender({ enabled: false });
+
+      expect(result.current.state.isDown).toBe(false);
+    });
+  });
+});

package/src/hooks/gesture/usePointerTracking.ts

@@ -0,0 +1,134 @@
+/**
+ * @file Hook for tracking pointer state during gestures.
+ *
+ * Provides low-level pointer tracking with position, velocity, and timing.
+ * This hook serves as the foundation for higher-level gesture hooks.
+ */
+import * as React from "react";
+import { useDocumentPointerEvents } from "../useDocumentPointerEvents.js";
+import { useEffectEvent } from "../useEffectEvent.js";
+import type {
+  PointerTrackingState,
+  TimestampedPoint,
+  UsePointerTrackingOptions,
+  UsePointerTrackingResult,
+} from "./types.js";
+
+/**
+ * Initial state for pointer tracking.
+ */
+const INITIAL_STATE: PointerTrackingState = {
+  isDown: false,
+  start: null,
+  current: null,
+  pointerId: null,
+  wasCanceled: false,
+};
+
+/**
+ * Creates a timestamped point from pointer event coordinates.
+ */
+const createTimestampedPoint = (clientX: number, clientY: number): TimestampedPoint => ({
+  x: clientX,
+  y: clientY,
+  timestamp: performance.now(),
+});
+
+/**
+ * Hook for tracking pointer state during gestures.
+ *
+ * Tracks pointer down/move/up events and provides position and timing data
+ * that can be used by higher-level gesture detection hooks.
+ *
+ * @example
+ * ```tsx
+ * const { state, onPointerDown, reset } = usePointerTracking({
+ *   enabled: true,
+ *   primaryOnly: true,
+ * });
+ *
+ * return (
+ *   <div onPointerDown={onPointerDown}>
+ *     {state.isDown && <span>Tracking...</span>}
+ *   </div>
+ * );
+ * ```
+ */
+export function usePointerTracking(options: UsePointerTrackingOptions): UsePointerTrackingResult {
+  const { enabled, primaryOnly = true } = options;
+
+  const [state, setState] = React.useState<PointerTrackingState>(INITIAL_STATE);
+
+  const reset = React.useCallback(() => {
+    setState(INITIAL_STATE);
+  }, []);
+
+  const handlePointerDown = useEffectEvent((event: React.PointerEvent) => {
+    if (!enabled) {
+      return;
+    }
+
+    // Filter non-primary pointers if primaryOnly is set
+    if (primaryOnly && !event.isPrimary) {
+      return;
+    }
+
+    // Only track left mouse button or touch/pen
+    if (event.pointerType === "mouse" && event.button !== 0) {
+      return;
+    }
+
+    const point = createTimestampedPoint(event.clientX, event.clientY);
+
+    setState({
+      isDown: true,
+      start: point,
+      current: point,
+      pointerId: event.pointerId,
+      wasCanceled: false,
+    });
+  });
+
+  const handlePointerMove = useEffectEvent((event: PointerEvent) => {
+    // Verify this is the tracked pointer
+    if (state.pointerId !== event.pointerId) {
+      return;
+    }
+
+    const point = createTimestampedPoint(event.clientX, event.clientY);
+
+    setState((prev) => ({
+      ...prev,
+      current: point,
+    }));
+  });
+
+  const handlePointerUp = useEffectEvent(() => {
+    setState(INITIAL_STATE);
+  });
+
+  const handlePointerCancel = useEffectEvent(() => {
+    setState({ ...INITIAL_STATE, wasCanceled: true });
+  });
+
+  // Use document-level pointer events for tracking after pointer down
+  const shouldTrackDocument = state.isDown ? enabled : false;
+  useDocumentPointerEvents(shouldTrackDocument, {
+    onMove: handlePointerMove,
+    onUp: handlePointerUp,
+    onCancel: handlePointerCancel,
+  });
+
+  // Reset state when disabled
+  React.useEffect(() => {
+    if (!enabled && state.isDown) {
+      reset();
+    }
+  }, [enabled, state.isDown, reset]);
+
+  return {
+    state,
+    onPointerDown: handlePointerDown,
+    reset,
+  };
+}