react-panel-layout 0.5.2 → 0.6.0

package/src/hooks/gesture/types.ts

@@ -0,0 +1,290 @@
+/**
+ * @file Type definitions for gesture input detection hooks.
+ *
+ * These types support the separation of concerns:
+ * - Operation: what to do (navigate, push, pop)
+ * - Input: how to command (swipe, click, keyboard)
+ * - Presentation: how to show (animation, transition)
+ *
+ * This file defines types for the Input layer.
+ */
+import type * as React from "react";
+
+/**
+ * Axis for gesture detection.
+ */
+export type GestureAxis = "horizontal" | "vertical";
+
+/**
+ * Phase of swipe input lifecycle.
+ */
+export type SwipeInputPhase = "idle" | "tracking" | "swiping" | "ended";
+
+/**
+ * 2D vector for displacement and velocity.
+ */
+export type Vector2 = {
+  x: number;
+  y: number;
+};
+
+/**
+ * Point with timestamp for velocity calculation.
+ */
+export type TimestampedPoint = {
+  x: number;
+  y: number;
+  timestamp: number;
+};
+
+/**
+ * Swipe input state during gesture.
+ */
+export type SwipeInputState = {
+  /** Current phase of the swipe input */
+  phase: SwipeInputPhase;
+  /** Displacement from start position in pixels */
+  displacement: Vector2;
+  /** Current velocity in pixels per millisecond */
+  velocity: Vector2;
+  /**
+   * Direction of movement as a number.
+   * -1 = backward (left/up), 0 = no movement, 1 = forward (right/down)
+   */
+  direction: -1 | 0 | 1;
+};
+
+/**
+ * Thresholds for swipe input recognition.
+ */
+export type SwipeInputThresholds = {
+  /** Minimum distance in pixels to trigger swipe. @default 50 */
+  distanceThreshold: number;
+  /** Minimum velocity in px/ms to trigger swipe. @default 0.3 */
+  velocityThreshold: number;
+  /** Distance threshold before direction is locked. @default 10 */
+  lockThreshold: number;
+};
+
+/**
+ * Options for usePointerTracking hook.
+ */
+export type UsePointerTrackingOptions = {
+  /** Whether tracking is enabled */
+  enabled: boolean;
+  /** Restrict to primary pointer only (ignore multitouch). @default true */
+  primaryOnly?: boolean;
+};
+
+/**
+ * Result from usePointerTracking hook.
+ */
+export type UsePointerTrackingResult = {
+  /** Current tracking state */
+  state: PointerTrackingState;
+  /** Handler to attach to onPointerDown */
+  onPointerDown: (event: React.PointerEvent) => void;
+  /** Reset tracking state */
+  reset: () => void;
+};
+
+/**
+ * Internal pointer tracking state.
+ */
+export type PointerTrackingState = {
+  /** Whether pointer is currently down */
+  isDown: boolean;
+  /** Start position and timestamp */
+  start: TimestampedPoint | null;
+  /** Current position and timestamp */
+  current: TimestampedPoint | null;
+  /** Active pointer ID */
+  pointerId: number | null;
+  /** Whether tracking ended via pointercancel (not pointerup) */
+  wasCanceled: boolean;
+};
+
+/**
+ * Options for useDirectionalLock hook.
+ */
+export type UseDirectionalLockOptions = {
+  /** Pointer tracking state from usePointerTracking */
+  tracking: PointerTrackingState;
+  /** Lock threshold in pixels. @default 10 */
+  lockThreshold?: number;
+};
+
+/**
+ * Result from useDirectionalLock hook.
+ */
+export type UseDirectionalLockResult = {
+  /** Locked axis, or null if not yet locked */
+  lockedAxis: GestureAxis | null;
+  /** Whether lock has been determined */
+  isLocked: boolean;
+  /** Reset the lock state */
+  reset: () => void;
+};
+
+/**
+ * Options for useScrollBoundary hook.
+ */
+export type UseScrollBoundaryOptions = {
+  /** Scroll container ref. If null, checks document scroll. */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Axis to monitor */
+  axis: GestureAxis;
+  /** Tolerance in pixels for "at boundary" detection. @default 1 */
+  tolerance?: number;
+};
+
+/**
+ * Result from useScrollBoundary hook.
+ */
+export type UseScrollBoundaryResult = {
+  /** Whether at the start boundary (top/left) */
+  atStart: boolean;
+  /** Whether at the end boundary (bottom/right) */
+  atEnd: boolean;
+  /** Current scroll position */
+  scrollPosition: number;
+  /** Maximum scroll position */
+  maxScrollPosition: number;
+};
+
+/**
+ * Filter function to determine if a pointer event should start tracking.
+ * Receives the pointer event and container element.
+ * Return true to allow tracking, false to ignore the event.
+ */
+export type PointerStartFilter = (
+  event: React.PointerEvent,
+  container: HTMLElement,
+) => boolean;
+
+/**
+ * Options for useSwipeInput hook.
+ */
+export type UseSwipeInputOptions = {
+  /** Ref to the container element */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Axis to detect swipes on */
+  axis: GestureAxis;
+  /** Whether swipe detection is enabled. @default true */
+  enabled?: boolean;
+  /** Swipe thresholds configuration */
+  thresholds?: Partial<SwipeInputThresholds>;
+  /** Callback when swipe is completed */
+  onSwipeEnd?: (state: SwipeInputState) => void;
+  /** Whether to enable trackpad two-finger swipe (wheel events). @default true */
+  enableWheel?: boolean;
+  /**
+   * Optional filter to determine if a pointer event should start tracking.
+   * If provided, only events that pass this filter will be tracked.
+   * Useful for edge-based swipe detection.
+   */
+  pointerStartFilter?: PointerStartFilter;
+};
+
+/**
+ * Result from useSwipeInput hook.
+ */
+export type UseSwipeInputResult = {
+  /** Current swipe input state */
+  state: SwipeInputState;
+  /** Props to spread on the container element */
+  containerProps: React.HTMLAttributes<HTMLElement> & {
+    style: React.CSSProperties;
+  };
+};
+
+/**
+ * Edge for edge-originated gestures.
+ */
+export type GestureEdge = "left" | "right" | "top" | "bottom";
+
+/**
+ * Options for useEdgeSwipeInput hook.
+ */
+export type UseEdgeSwipeInputOptions = {
+  /** Ref to the container element */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Which edge to detect swipes from */
+  edge: GestureEdge;
+  /** Width of the edge detection zone in pixels. @default 20 */
+  edgeWidth?: number;
+  /** Whether edge swipe detection is enabled. @default true */
+  enabled?: boolean;
+  /** Swipe thresholds configuration */
+  thresholds?: Partial<SwipeInputThresholds>;
+  /** Callback when edge swipe is completed */
+  onSwipeEnd?: (state: SwipeInputState) => void;
+};
+
+/**
+ * Result from useEdgeSwipeInput hook.
+ */
+export type UseEdgeSwipeInputResult = {
+  /** Whether the current gesture started from the edge */
+  isEdgeGesture: boolean;
+  /** Current swipe input state */
+  state: SwipeInputState;
+  /** Props to spread on the container element */
+  containerProps: React.HTMLAttributes<HTMLElement> & {
+    style: React.CSSProperties;
+  };
+};
+
+/**
+ * Options for useNativeGestureGuard hook.
+ */
+export type UseNativeGestureGuardOptions = {
+  /** Ref to the container element */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Whether the guard is active */
+  active: boolean;
+  /** Prevent iOS/macOS edge back gesture. @default true */
+  preventEdgeBack?: boolean;
+  /** Prevent overscroll bounce effect. @default true */
+  preventOverscroll?: boolean;
+  /** Width of edge zone where back gesture is prevented. @default 20 */
+  edgeWidth?: number;
+};
+
+/**
+ * Result from useNativeGestureGuard hook.
+ */
+export type UseNativeGestureGuardResult = {
+  /** Props to spread on the container element */
+  containerProps: React.HTMLAttributes<HTMLElement> & {
+    style: React.CSSProperties;
+  };
+};
+
+/**
+ * Default swipe input thresholds.
+ *
+ * - distanceThreshold: 100px is ~27% of a 375px mobile screen
+ * - velocityThreshold: 0.5px/ms = 500px/s, a moderate flick speed
+ * - lockThreshold: 10px before direction is locked
+ */
+export const DEFAULT_SWIPE_THRESHOLDS: SwipeInputThresholds = {
+  distanceThreshold: 100,
+  velocityThreshold: 0.5,
+  lockThreshold: 10,
+};
+
+/**
+ * Default edge width for edge gesture detection.
+ */
+export const DEFAULT_EDGE_WIDTH = 20;
+
+/**
+ * Initial idle state for SwipeInputState.
+ */
+export const IDLE_SWIPE_INPUT_STATE: SwipeInputState = {
+  phase: "idle",
+  displacement: { x: 0, y: 0 },
+  velocity: { x: 0, y: 0 },
+  direction: 0,
+};

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

@@ -0,0 +1,271 @@
+/**
+ * @file Tests for useDirectionalLock hook.
+ */
+import { act, renderHook } from "@testing-library/react";
+import { useDirectionalLock } from "./useDirectionalLock.js";
+import type { PointerTrackingState } from "./types.js";
+
+const createTrackingState = (
+  overrides: Partial<PointerTrackingState> = {},
+): PointerTrackingState => ({
+  isDown: false,
+  start: null,
+  current: null,
+  pointerId: null,
+  wasCanceled: false,
+  ...overrides,
+});
+
+describe("useDirectionalLock", () => {
+  describe("initialization", () => {
+    it("starts with no locked axis", () => {
+      const tracking = createTrackingState();
+      const { result } = renderHook(() =>
+        useDirectionalLock({ tracking }),
+      );
+
+      expect(result.current.lockedAxis).toBe(null);
+      expect(result.current.isLocked).toBe(false);
+    });
+  });
+
+  describe("direction detection", () => {
+    it("locks to horizontal when X movement dominates", () => {
+      const tracking = createTrackingState({
+        isDown: true,
+        start: { x: 100, y: 100, timestamp: 0 },
+        current: { x: 130, y: 105, timestamp: 100 }, // 30px horizontal, 5px vertical
+        pointerId: 1,
+      });
+
+      const { result } = renderHook(() =>
+        useDirectionalLock({ tracking, lockThreshold: 10 }),
+      );
+
+      expect(result.current.lockedAxis).toBe("horizontal");
+      expect(result.current.isLocked).toBe(true);
+    });
+
+    it("locks to vertical when Y movement dominates", () => {
+      const tracking = createTrackingState({
+        isDown: true,
+        start: { x: 100, y: 100, timestamp: 0 },
+        current: { x: 105, y: 130, timestamp: 100 }, // 5px horizontal, 30px vertical
+        pointerId: 1,
+      });
+
+      const { result } = renderHook(() =>
+        useDirectionalLock({ tracking, lockThreshold: 10 }),
+      );
+
+      expect(result.current.lockedAxis).toBe("vertical");
+      expect(result.current.isLocked).toBe(true);
+    });
+
+    it("does not lock when movement is below threshold", () => {
+      const tracking = createTrackingState({
+        isDown: true,
+        start: { x: 100, y: 100, timestamp: 0 },
+        current: { x: 105, y: 103, timestamp: 100 }, // 5px horizontal, 3px vertical
+        pointerId: 1,
+      });
+
+      const { result } = renderHook(() =>
+        useDirectionalLock({ tracking, lockThreshold: 10 }),
+      );
+
+      expect(result.current.lockedAxis).toBe(null);
+      expect(result.current.isLocked).toBe(false);
+    });
+
+    it("does not lock when movement is diagonal (ambiguous)", () => {
+      const tracking = createTrackingState({
+        isDown: true,
+        start: { x: 100, y: 100, timestamp: 0 },
+        current: { x: 120, y: 118, timestamp: 100 }, // 20px horizontal, 18px vertical - ratio ~1.1
+        pointerId: 1,
+      });
+
+      const { result } = renderHook(() =>
+        useDirectionalLock({ tracking, lockThreshold: 10 }),
+      );
+
+      // Movement exceeds threshold but direction is ambiguous
+      expect(result.current.lockedAxis).toBe(null);
+      expect(result.current.isLocked).toBe(false);
+    });
+
+    it("locks with negative movement values", () => {
+      const tracking = createTrackingState({
+        isDown: true,
+        start: { x: 100, y: 100, timestamp: 0 },
+        current: { x: 70, y: 95, timestamp: 100 }, // -30px horizontal, -5px vertical
+        pointerId: 1,
+      });
+
+      const { result } = renderHook(() =>
+        useDirectionalLock({ tracking, lockThreshold: 10 }),
+      );
+
+      expect(result.current.lockedAxis).toBe("horizontal");
+      expect(result.current.isLocked).toBe(true);
+    });
+  });
+
+  describe("lock persistence", () => {
+    it("maintains lock once determined", () => {
+      const initialTracking = createTrackingState({
+        isDown: true,
+        start: { x: 100, y: 100, timestamp: 0 },
+        current: { x: 130, y: 105, timestamp: 100 }, // Horizontal
+        pointerId: 1,
+      });
+
+      const { result, rerender } = renderHook(
+        ({ tracking }) => useDirectionalLock({ tracking }),
+        { initialProps: { tracking: initialTracking } },
+      );
+
+      expect(result.current.lockedAxis).toBe("horizontal");
+
+      // Update to more vertical movement
+      const updatedTracking = createTrackingState({
+        isDown: true,
+        start: { x: 100, y: 100, timestamp: 0 },
+        current: { x: 130, y: 200, timestamp: 200 }, // Now more vertical
+        pointerId: 1,
+      });
+
+      rerender({ tracking: updatedTracking });
+
+      // Should still be locked to horizontal
+      expect(result.current.lockedAxis).toBe("horizontal");
+    });
+  });
+
+  describe("reset behavior", () => {
+    it("resets lock when pointer is released", () => {
+      const downTracking = createTrackingState({
+        isDown: true,
+        start: { x: 100, y: 100, timestamp: 0 },
+        current: { x: 130, y: 105, timestamp: 100 },
+        pointerId: 1,
+      });
+
+      const { result, rerender } = renderHook(
+        ({ tracking }) => useDirectionalLock({ tracking }),
+        { initialProps: { tracking: downTracking } },
+      );
+
+      expect(result.current.lockedAxis).toBe("horizontal");
+
+      // Release pointer
+      const upTracking = createTrackingState({
+        isDown: false,
+        start: null,
+        current: null,
+        pointerId: null,
+      });
+
+      rerender({ tracking: upTracking });
+
+      expect(result.current.lockedAxis).toBe(null);
+      expect(result.current.isLocked).toBe(false);
+    });
+
+    it("can manually reset lock and will re-lock based on tracking state", () => {
+      const tracking = createTrackingState({
+        isDown: true,
+        start: { x: 100, y: 100, timestamp: 0 },
+        current: { x: 130, y: 105, timestamp: 100 },
+        pointerId: 1,
+      });
+
+      const { result } = renderHook(() =>
+        useDirectionalLock({ tracking }),
+      );
+
+      expect(result.current.lockedAxis).toBe("horizontal");
+
+      act(() => {
+        result.current.reset();
+      });
+
+      // Note: reset() sets lockedAxis to null, but the effect will
+      // immediately re-evaluate and re-lock based on tracking state.
+      // This is expected behavior - manual reset is primarily useful
+      // when combined with updated tracking state.
+      // The lock will be recalculated on the next effect run.
+      expect(result.current.lockedAxis).toBe("horizontal");
+    });
+  });
+
+  describe("threshold configuration", () => {
+    it("respects custom lock threshold", () => {
+      const tracking = createTrackingState({
+        isDown: true,
+        start: { x: 100, y: 100, timestamp: 0 },
+        current: { x: 115, y: 103, timestamp: 100 }, // 15px horizontal
+        pointerId: 1,
+      });
+
+      const { result: resultLow } = renderHook(() =>
+        useDirectionalLock({ tracking, lockThreshold: 10 }),
+      );
+
+      const { result: resultHigh } = renderHook(() =>
+        useDirectionalLock({ tracking, lockThreshold: 20 }),
+      );
+
+      expect(resultLow.current.isLocked).toBe(true);
+      expect(resultHigh.current.isLocked).toBe(false);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles zero movement", () => {
+      const tracking = createTrackingState({
+        isDown: true,
+        start: { x: 100, y: 100, timestamp: 0 },
+        current: { x: 100, y: 100, timestamp: 100 }, // No movement
+        pointerId: 1,
+      });
+
+      const { result } = renderHook(() =>
+        useDirectionalLock({ tracking }),
+      );
+
+      expect(result.current.lockedAxis).toBe(null);
+    });
+
+    it("handles missing start position", () => {
+      const tracking = createTrackingState({
+        isDown: true,
+        start: null,
+        current: { x: 130, y: 105, timestamp: 100 },
+        pointerId: 1,
+      });
+
+      const { result } = renderHook(() =>
+        useDirectionalLock({ tracking }),
+      );
+
+      expect(result.current.lockedAxis).toBe(null);
+    });
+
+    it("handles missing current position", () => {
+      const tracking = createTrackingState({
+        isDown: true,
+        start: { x: 100, y: 100, timestamp: 0 },
+        current: null,
+        pointerId: 1,
+      });
+
+      const { result } = renderHook(() =>
+        useDirectionalLock({ tracking }),
+      );
+
+      expect(result.current.lockedAxis).toBe(null);
+    });
+  });
+});

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,
+  };
+}