react-panel-layout 0.5.2 → 0.6.1

package/src/hooks/gesture/useDirectionalLock.ts

@@ -0,0 +1,115 @@
+/**
+ * @file Hook for locking gesture direction after threshold is exceeded.
+ *
+ * Once the user moves beyond the lock threshold, the direction is locked
+ * to either horizontal or vertical, preventing diagonal gestures from
+ * triggering both scroll and swipe.
+ */
+import * as React from "react";
+import type {
+  GestureAxis,
+  UseDirectionalLockOptions,
+  UseDirectionalLockResult,
+} from "./types.js";
+
+const DEFAULT_LOCK_THRESHOLD = 10;
+
+/**
+ * Determines which axis the gesture is primarily moving along.
+ *
+ * @param deltaX - Horizontal displacement from start
+ * @param deltaY - Vertical displacement from start
+ * @returns The dominant axis, or null if movement is insufficient
+ */
+const determineAxis = (deltaX: number, deltaY: number): GestureAxis | null => {
+  const absX = Math.abs(deltaX);
+  const absY = Math.abs(deltaY);
+
+  // Require at least some movement in one direction
+  if (absX === 0 && absY === 0) {
+    return null;
+  }
+
+  // Use a 1.5x ratio to ensure clear direction before locking
+  // This prevents near-diagonal gestures from locking prematurely
+  if (absX > absY * 1.5) {
+    return "horizontal";
+  }
+
+  if (absY > absX * 1.5) {
+    return "vertical";
+  }
+
+  // Still ambiguous
+  return null;
+};
+
+/**
+ * Hook for locking gesture direction after threshold is exceeded.
+ *
+ * This hook tracks pointer movement and locks to horizontal or vertical
+ * direction once the movement exceeds the configured threshold. This
+ * prevents diagonal gestures from triggering both scroll and swipe behaviors.
+ *
+ * @example
+ * ```tsx
+ * const { state: tracking, onPointerDown } = usePointerTracking({ enabled: true });
+ * const { lockedAxis, isLocked } = useDirectionalLock({
+ *   tracking,
+ *   lockThreshold: 10,
+ * });
+ *
+ * // lockedAxis will be "horizontal" or "vertical" once determined
+ * ```
+ */
+export function useDirectionalLock(options: UseDirectionalLockOptions): UseDirectionalLockResult {
+  const { tracking, lockThreshold = DEFAULT_LOCK_THRESHOLD } = options;
+
+  const [lockedAxis, setLockedAxis] = React.useState<GestureAxis | null>(null);
+
+  const reset = React.useCallback(() => {
+    setLockedAxis(null);
+  }, []);
+
+  // Determine direction when tracking is active
+  React.useEffect(() => {
+    // Reset lock when pointer is released
+    if (!tracking.isDown) {
+      if (lockedAxis !== null) {
+        reset();
+      }
+      return;
+    }
+
+    // Already locked, no need to recalculate
+    if (lockedAxis !== null) {
+      return;
+    }
+
+    // Need start and current positions
+    if (!tracking.start || !tracking.current) {
+      return;
+    }
+
+    const deltaX = tracking.current.x - tracking.start.x;
+    const deltaY = tracking.current.y - tracking.start.y;
+
+    // Check if we've exceeded the lock threshold
+    const distance = Math.max(Math.abs(deltaX), Math.abs(deltaY));
+    if (distance < lockThreshold) {
+      return;
+    }
+
+    // Try to determine axis
+    const axis = determineAxis(deltaX, deltaY);
+    if (axis !== null) {
+      setLockedAxis(axis);
+    }
+  }, [tracking.isDown, tracking.start, tracking.current, lockedAxis, lockThreshold, reset]);
+
+  return {
+    lockedAxis,
+    isLocked: lockedAxis !== null,
+    reset,
+  };
+}

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

@@ -0,0 +1,462 @@
+/**
+ * @file Tests for useEdgeSwipeInput hook.
+ */
+import { renderHook, act } from "@testing-library/react";
+import * as React from "react";
+import { useEdgeSwipeInput } from "./useEdgeSwipeInput.js";
+
+describe("useEdgeSwipeInput", () => {
+  type CallTracker = {
+    calls: ReadonlyArray<ReadonlyArray<unknown>>;
+    fn: (...args: ReadonlyArray<unknown>) => void;
+  };
+
+  const createCallTracker = (): CallTracker => {
+    const calls: Array<ReadonlyArray<unknown>> = [];
+    const fn = (...args: ReadonlyArray<unknown>): void => {
+      calls.push(args);
+    };
+    return { calls, fn };
+  };
+
+  const createRef = (rect: Partial<DOMRect> = {}): React.RefObject<HTMLDivElement> => {
+    const element = document.createElement("div");
+    const defaultRect: DOMRect = {
+      left: 0,
+      right: 300,
+      top: 0,
+      bottom: 500,
+      width: 300,
+      height: 500,
+      x: 0,
+      y: 0,
+      toJSON: () => ({}),
+    };
+    const mergedRect = Object.assign({}, defaultRect, rect);
+    Object.defineProperty(element, "getBoundingClientRect", {
+      value: () => mergedRect,
+    });
+    return { current: element };
+  };
+
+  describe("initialization", () => {
+    it("starts with idle state and isEdgeGesture false", () => {
+      const containerRef = createRef();
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "left" }),
+      );
+
+      expect(result.current.isEdgeGesture).toBe(false);
+      expect(result.current.state).toEqual({
+        phase: "idle",
+        displacement: { x: 0, y: 0 },
+        velocity: { x: 0, y: 0 },
+        direction: 0,
+      });
+    });
+
+    it("provides container props with correct touch-action for left edge", () => {
+      const containerRef = createRef();
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "left" }),
+      );
+
+      expect(result.current.containerProps.style.touchAction).toBe("pan-y pinch-zoom");
+    });
+
+    it("provides container props with correct touch-action for top edge", () => {
+      const containerRef = createRef();
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "top" }),
+      );
+
+      expect(result.current.containerProps.style.touchAction).toBe("pan-x pinch-zoom");
+    });
+  });
+
+  describe("left edge detection", () => {
+    it("activates when pointer down is within left edge zone", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "left", edgeWidth: 20 }),
+      );
+
+      const mockEvent = {
+        clientX: 10, // Within 20px edge zone
+        clientY: 100,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(result.current.isEdgeGesture).toBe(true);
+      expect(result.current.state.phase).toBe("tracking");
+    });
+
+    it("does not activate when pointer down is outside left edge zone", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "left", edgeWidth: 20 }),
+      );
+
+      const mockEvent = {
+        clientX: 50, // Outside 20px edge zone
+        clientY: 100,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(result.current.isEdgeGesture).toBe(false);
+      expect(result.current.state.phase).toBe("idle");
+    });
+  });
+
+  describe("right edge detection", () => {
+    it("activates when pointer down is within right edge zone", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "right", edgeWidth: 20 }),
+      );
+
+      const mockEvent = {
+        clientX: 290, // Within 20px from right edge (300)
+        clientY: 100,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(result.current.isEdgeGesture).toBe(true);
+    });
+
+    it("does not activate when pointer down is outside right edge zone", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "right", edgeWidth: 20 }),
+      );
+
+      const mockEvent = {
+        clientX: 250, // Outside 20px from right edge
+        clientY: 100,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(result.current.isEdgeGesture).toBe(false);
+    });
+  });
+
+  describe("top edge detection", () => {
+    it("activates when pointer down is within top edge zone", () => {
+      const containerRef = createRef({ top: 0, bottom: 500 });
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "top", edgeWidth: 20 }),
+      );
+
+      const mockEvent = {
+        clientX: 100,
+        clientY: 10, // Within 20px from top edge
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(result.current.isEdgeGesture).toBe(true);
+    });
+  });
+
+  describe("bottom edge detection", () => {
+    it("activates when pointer down is within bottom edge zone", () => {
+      const containerRef = createRef({ top: 0, bottom: 500 });
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "bottom", edgeWidth: 20 }),
+      );
+
+      const mockEvent = {
+        clientX: 100,
+        clientY: 490, // Within 20px from bottom edge (500)
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(result.current.isEdgeGesture).toBe(true);
+    });
+  });
+
+  describe("swipe progression", () => {
+    it("transitions to swiping when movement is in correct direction", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "left", edgeWidth: 20 }),
+      );
+
+      // Pointer down at edge
+      const downEvent = {
+        clientX: 10,
+        clientY: 100,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(downEvent);
+      });
+
+      // Move horizontally (past lock threshold)
+      const moveEvent = new PointerEvent("pointermove", {
+        clientX: 50, // 40px horizontal movement
+        clientY: 102,
+        pointerId: 1,
+      });
+
+      act(() => {
+        document.dispatchEvent(moveEvent);
+      });
+
+      expect(result.current.state.phase).toBe("swiping");
+      expect(result.current.state.direction).toBe(1); // Moving right
+    });
+
+    it("stays in tracking when locked to wrong axis", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "left", edgeWidth: 20 }),
+      );
+
+      const downEvent = {
+        clientX: 10,
+        clientY: 100,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(downEvent);
+      });
+
+      // Move vertically (wrong axis for left edge)
+      const moveEvent = new PointerEvent("pointermove", {
+        clientX: 12,
+        clientY: 150, // 50px vertical movement
+        pointerId: 1,
+      });
+
+      act(() => {
+        document.dispatchEvent(moveEvent);
+      });
+
+      expect(result.current.state.phase).toBe("tracking");
+      expect(result.current.state.direction).toBe(0);
+    });
+  });
+
+  describe("swipe completion callback", () => {
+    it("calls onSwipeEnd when edge swipe threshold is met", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const onSwipeEnd = createCallTracker();
+
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({
+          containerRef,
+          edge: "left",
+          edgeWidth: 20,
+          thresholds: { distanceThreshold: 50, velocityThreshold: 0.3, lockThreshold: 10 },
+          onSwipeEnd: onSwipeEnd.fn,
+        }),
+      );
+
+      // Pointer down at edge
+      const downEvent = {
+        clientX: 10,
+        clientY: 100,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(downEvent);
+      });
+
+      // Move past threshold
+      const moveEvent = new PointerEvent("pointermove", {
+        clientX: 70, // 60px movement (past 50px threshold)
+        clientY: 105,
+        pointerId: 1,
+      });
+
+      act(() => {
+        document.dispatchEvent(moveEvent);
+      });
+
+      // Pointer up
+      const upEvent = new PointerEvent("pointerup", { pointerId: 1 });
+
+      act(() => {
+        document.dispatchEvent(upEvent);
+      });
+
+      expect(onSwipeEnd.calls).toHaveLength(1);
+      expect(onSwipeEnd.calls[0]?.[0]).toEqual(
+        expect.objectContaining({
+          phase: "ended",
+          direction: 1,
+        }),
+      );
+    });
+
+    it("does not call onSwipeEnd when gesture starts outside edge", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const onSwipeEnd = createCallTracker();
+
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({
+          containerRef,
+          edge: "left",
+          edgeWidth: 20,
+          thresholds: { distanceThreshold: 50, velocityThreshold: 0.3, lockThreshold: 10 },
+          onSwipeEnd: onSwipeEnd.fn,
+        }),
+      );
+
+      // Pointer down outside edge
+      const downEvent = {
+        clientX: 50, // Outside 20px edge zone
+        clientY: 100,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(downEvent);
+      });
+
+      // The gesture should not be tracked, so no callback should be fired
+      expect(result.current.isEdgeGesture).toBe(false);
+      expect(onSwipeEnd.calls).toHaveLength(0);
+    });
+  });
+
+  describe("disabled state", () => {
+    it("does not track when disabled", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "left", enabled: false }),
+      );
+
+      const mockEvent = {
+        clientX: 10,
+        clientY: 100,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(result.current.isEdgeGesture).toBe(false);
+      expect(result.current.state.phase).toBe("idle");
+    });
+  });
+
+  describe("edge width configuration", () => {
+    it("respects custom edge width", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "left", edgeWidth: 50 }),
+      );
+
+      const mockEvent = {
+        clientX: 40, // Within 50px edge zone, but outside default 20px
+        clientY: 100,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(result.current.isEdgeGesture).toBe(true);
+    });
+  });
+
+  describe("reset behavior", () => {
+    it("resets isEdgeGesture when pointer is released", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useEdgeSwipeInput({ containerRef, edge: "left", edgeWidth: 20 }),
+      );
+
+      // Pointer down at edge
+      const downEvent = {
+        clientX: 10,
+        clientY: 100,
+        pointerId: 1,
+        isPrimary: true,
+        pointerType: "touch",
+        button: 0,
+      } as React.PointerEvent<HTMLElement>;
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(downEvent);
+      });
+
+      expect(result.current.isEdgeGesture).toBe(true);
+
+      // Pointer up
+      const upEvent = new PointerEvent("pointerup", { pointerId: 1 });
+
+      act(() => {
+        document.dispatchEvent(upEvent);
+      });
+
+      expect(result.current.isEdgeGesture).toBe(false);
+    });
+  });
+});

package/src/hooks/gesture/useEdgeSwipeInput.ts

@@ -0,0 +1,131 @@
+/**
+ * @file Hook for detecting swipe gestures that originate from the edge of a container.
+ *
+ * Edge swipes are commonly used for "swipe back" navigation in mobile apps.
+ * This hook detects swipes that start within a configurable edge zone.
+ *
+ * Built on top of useSwipeInput with edge zone filtering.
+ */
+import * as React from "react";
+import { useSwipeInput } from "./useSwipeInput.js";
+import type {
+  GestureAxis,
+  GestureEdge,
+  SwipeInputState,
+  UseEdgeSwipeInputOptions,
+  UseEdgeSwipeInputResult,
+} from "./types.js";
+import { DEFAULT_EDGE_WIDTH, DEFAULT_SWIPE_THRESHOLDS, IDLE_SWIPE_INPUT_STATE } from "./types.js";
+
+/**
+ * Get the axis associated with an edge.
+ */
+const getAxisForEdge = (edge: GestureEdge): GestureAxis => {
+  if (edge === "left" || edge === "right") {
+    return "horizontal";
+  }
+  return "vertical";
+};
+
+/**
+ * Check if a point is within the edge zone of a container.
+ */
+const isInEdgeZone = (
+  clientX: number,
+  clientY: number,
+  container: HTMLElement,
+  edge: GestureEdge,
+  edgeWidth: number,
+): boolean => {
+  const rect = container.getBoundingClientRect();
+
+  switch (edge) {
+    case "left":
+      return clientX >= rect.left && clientX <= rect.left + edgeWidth;
+    case "right":
+      return clientX >= rect.right - edgeWidth && clientX <= rect.right;
+    case "top":
+      return clientY >= rect.top && clientY <= rect.top + edgeWidth;
+    case "bottom":
+      return clientY >= rect.bottom - edgeWidth && clientY <= rect.bottom;
+  }
+};
+
+/**
+ * Hook for detecting swipe gestures that originate from the edge of a container.
+ *
+ * This is useful for implementing "swipe back" navigation patterns where
+ * the user must start their swipe from the edge of the screen.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const { isEdgeGesture, state, containerProps } = useEdgeSwipeInput({
+ *   containerRef,
+ *   edge: "left",
+ *   edgeWidth: 20,
+ *   onSwipeEnd: (state) => {
+ *     if (state.direction === 1) goBack();
+ *   },
+ * });
+ *
+ * return <div ref={containerRef} {...containerProps}>{children}</div>;
+ * ```
+ */
+export function useEdgeSwipeInput(options: UseEdgeSwipeInputOptions): UseEdgeSwipeInputResult {
+  const {
+    containerRef,
+    edge,
+    edgeWidth = DEFAULT_EDGE_WIDTH,
+    enabled = true,
+    thresholds: customThresholds,
+    onSwipeEnd,
+  } = options;
+
+  const thresholds = {
+    ...DEFAULT_SWIPE_THRESHOLDS,
+    ...customThresholds,
+  };
+
+  const axis = getAxisForEdge(edge);
+
+  // Track whether the current gesture started from the edge
+  const [isEdgeGesture, setIsEdgeGesture] = React.useState(false);
+
+  // Create edge zone filter for pointer events
+  const pointerStartFilter = React.useCallback(
+    (event: React.PointerEvent, container: HTMLElement): boolean => {
+      const inEdge = isInEdgeZone(event.clientX, event.clientY, container, edge, edgeWidth);
+      setIsEdgeGesture(inEdge);
+      return inEdge;
+    },
+    [edge, edgeWidth],
+  );
+
+  // Use base swipe input with edge filtering
+  const { state, containerProps } = useSwipeInput({
+    containerRef,
+    axis,
+    enabled,
+    thresholds,
+    onSwipeEnd,
+    enableWheel: false, // Edge swipe doesn't use wheel events
+    pointerStartFilter,
+  });
+
+  // Reset edge gesture state when swipe ends
+  React.useEffect(() => {
+    if (state.phase === "idle") {
+      setIsEdgeGesture(false);
+    }
+  }, [state.phase]);
+
+  // If not an edge gesture, return idle state
+  const effectiveState: SwipeInputState = isEdgeGesture ? state : IDLE_SWIPE_INPUT_STATE;
+
+  return {
+    isEdgeGesture,
+    state: effectiveState,
+    containerProps,
+  };
+}