react-panel-layout 0.5.2 → 0.6.1

package/src/hooks/gesture/useSwipeInput.ts

@@ -0,0 +1,310 @@
+/**
+ * @file Hook for detecting swipe gestures on a container element.
+ *
+ * Combines pointer tracking and directional locking to detect swipe gestures.
+ * Also supports trackpad two-finger swipe via wheel events.
+ * Returns swipe state and container props for gesture handling.
+ */
+import * as React from "react";
+import { usePointerTracking } from "./usePointerTracking.js";
+import { useDirectionalLock } from "./useDirectionalLock.js";
+import { useEffectEvent } from "../useEffectEvent.js";
+import { calculateVelocity, determineDirection } from "./utils.js";
+import type {
+  GestureAxis,
+  SwipeInputState,
+  SwipeInputThresholds,
+  UseSwipeInputOptions,
+  UseSwipeInputResult,
+  Vector2,
+} from "./types.js";
+import { DEFAULT_SWIPE_THRESHOLDS, IDLE_SWIPE_INPUT_STATE } from "./types.js";
+
+/** Idle timeout to reset wheel state after swipe stops */
+const WHEEL_RESET_TIMEOUT = 150;
+
+/**
+ * Evaluate swipe end and call callback if threshold is met.
+ */
+const evaluateSwipeEnd = (
+  displacement: Vector2,
+  velocity: Vector2,
+  axis: GestureAxis,
+  thresholds: SwipeInputThresholds,
+  onSwipeEnd: ((state: SwipeInputState) => void) | undefined,
+): void => {
+  const axisDisplacement = axis === "horizontal" ? displacement.x : displacement.y;
+  const axisVelocity = axis === "horizontal" ? velocity.x : velocity.y;
+
+  const absDisplacement = Math.abs(axisDisplacement);
+  const absVelocity = Math.abs(axisVelocity);
+
+  const triggered = absDisplacement >= thresholds.distanceThreshold || absVelocity >= thresholds.velocityThreshold;
+
+  if (triggered) {
+    const direction = determineDirection(axisDisplacement);
+    const endState: SwipeInputState = {
+      phase: "ended",
+      displacement,
+      velocity,
+      direction,
+    };
+    onSwipeEnd?.(endState);
+  }
+};
+
+/**
+ * Hook for detecting swipe gestures on a container element.
+ */
+export function useSwipeInput(options: UseSwipeInputOptions): UseSwipeInputResult {
+  const {
+    containerRef,
+    axis,
+    enabled = true,
+    thresholds: customThresholds,
+    onSwipeEnd,
+    enableWheel = true,
+    pointerStartFilter,
+  } = options;
+
+  const thresholds: SwipeInputThresholds = {
+    ...DEFAULT_SWIPE_THRESHOLDS,
+    ...customThresholds,
+  };
+
+  // Stable callback for swipe end
+  const handleSwipeEnd = useEffectEvent(onSwipeEnd);
+
+  // ===== Pointer-based swipe tracking =====
+  const { state: tracking, onPointerDown: baseOnPointerDown } = usePointerTracking({
+    enabled,
+  });
+
+  // Wrap pointer down handler with optional filter
+  const onPointerDown = React.useCallback(
+    (event: React.PointerEvent) => {
+      if (!enabled) {
+        return;
+      }
+      if (pointerStartFilter) {
+        const container = containerRef.current;
+        if (!container) {
+          return;
+        }
+        if (!pointerStartFilter(event, container)) {
+          return;
+        }
+      }
+      baseOnPointerDown(event);
+    },
+    [enabled, pointerStartFilter, containerRef, baseOnPointerDown],
+  );
+
+  const { lockedAxis, isLocked } = useDirectionalLock({
+    tracking,
+    lockThreshold: thresholds.lockThreshold,
+  });
+
+  const lastActiveStateRef = React.useRef<SwipeInputState | null>(null);
+
+  // Prevent native scroll when swiping on iOS
+  const isLockedToSwipeAxisRef = React.useRef(false);
+
+  React.useEffect(() => {
+    isLockedToSwipeAxisRef.current = isLocked ? lockedAxis === axis : false;
+  }, [isLocked, lockedAxis, axis]);
+
+  React.useEffect(() => {
+    const container = containerRef.current;
+    if (!container || !enabled) {
+      return;
+    }
+    const disableTouchMove = (event: TouchEvent) => {
+      event.preventDefault();
+    };
+    const handleTouchStart = (event: TouchEvent) => {
+      if (isLockedToSwipeAxisRef.current) {
+        event.preventDefault();
+      }
+      document.addEventListener("touchmove", disableTouchMove, { passive: false });
+    };
+    const handleTouchEnd = () => {
+      document.removeEventListener("touchmove", disableTouchMove);
+    };
+    document.addEventListener("touchend", handleTouchEnd);
+    document.addEventListener("touchcancel", handleTouchEnd);
+    container.addEventListener("touchstart", handleTouchStart, { passive: false });
+
+    return () => {
+      container.removeEventListener("touchstart", handleTouchStart);
+      document.removeEventListener("touchend", handleTouchEnd);
+      document.removeEventListener("touchcancel", handleTouchEnd);
+    };
+  }, [containerRef, enabled]);
+
+  // ===== Wheel-based swipe tracking =====
+  const [wheelState, setWheelState] = React.useState<SwipeInputState>(IDLE_SWIPE_INPUT_STATE);
+  const wheelAccumulatedRef = React.useRef({ x: 0, y: 0 });
+  const wheelIdleTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  const wheelLockedRef = React.useRef(false);
+  const wheelLockedAxisRef = React.useRef<GestureAxis | null>(null);
+
+  const resetWheelState = React.useCallback(() => {
+    wheelAccumulatedRef.current = { x: 0, y: 0 };
+    wheelLockedRef.current = false;
+    wheelLockedAxisRef.current = null;
+    setWheelState(IDLE_SWIPE_INPUT_STATE);
+  }, []);
+
+  const endWheelSwipe = React.useCallback(() => {
+    const displacement = { ...wheelAccumulatedRef.current };
+    evaluateSwipeEnd(displacement, { x: 0, y: 0 }, axis, thresholds, handleSwipeEnd);
+    resetWheelState();
+  }, [axis, thresholds, handleSwipeEnd, resetWheelState]);
+
+  const handleWheel = useEffectEvent((event: WheelEvent) => {
+    if (!enabled || !enableWheel || tracking.isDown) {
+      return;
+    }
+
+    const { deltaX, deltaY } = event;
+
+    // Direction lock
+    if (!wheelLockedRef.current) {
+      const absX = Math.abs(deltaX);
+      const absY = Math.abs(deltaY);
+
+      if (absX >= thresholds.lockThreshold || absY >= thresholds.lockThreshold) {
+        wheelLockedRef.current = true;
+        wheelLockedAxisRef.current = absX > absY ? "horizontal" : "vertical";
+      }
+    }
+
+    // If locked to wrong axis, ignore
+    if (wheelLockedRef.current && wheelLockedAxisRef.current !== axis) {
+      return;
+    }
+
+    // Accumulate displacement (negate: wheel delta is scroll direction)
+    wheelAccumulatedRef.current.x -= deltaX;
+    wheelAccumulatedRef.current.y -= deltaY;
+
+    const accumulated = wheelAccumulatedRef.current;
+    const axisDisplacement = axis === "horizontal" ? accumulated.x : accumulated.y;
+
+    setWheelState({
+      phase: "swiping",
+      displacement: { ...accumulated },
+      velocity: { x: 0, y: 0 },
+      direction: determineDirection(axisDisplacement),
+    });
+
+    // When wheel stops, treat as "release"
+    if (wheelIdleTimerRef.current !== null) {
+      clearTimeout(wheelIdleTimerRef.current);
+    }
+    wheelIdleTimerRef.current = setTimeout(endWheelSwipe, WHEEL_RESET_TIMEOUT);
+  });
+
+  // Set up wheel event listener
+  React.useEffect(() => {
+    const container = containerRef.current;
+    if (!container || !enabled || !enableWheel) {
+      return;
+    }
+
+    const listener = (event: WheelEvent) => {
+      event.preventDefault();
+      handleWheel(event);
+    };
+
+    container.addEventListener("wheel", listener, { passive: false });
+
+    return () => {
+      container.removeEventListener("wheel", listener);
+      if (wheelIdleTimerRef.current !== null) {
+        clearTimeout(wheelIdleTimerRef.current);
+      }
+    };
+  }, [containerRef, enabled, enableWheel, handleWheel]);
+
+  React.useEffect(() => {
+    return () => {
+      if (wheelIdleTimerRef.current !== null) {
+        clearTimeout(wheelIdleTimerRef.current);
+      }
+    };
+  }, []);
+
+  // ===== Pointer swipe state =====
+  const pointerState = React.useMemo<SwipeInputState>(() => {
+    if (!tracking.isDown || !tracking.start || !tracking.current) {
+      return IDLE_SWIPE_INPUT_STATE;
+    }
+
+    const deltaX = tracking.current.x - tracking.start.x;
+    const deltaY = tracking.current.y - tracking.start.y;
+    const displacement = { x: deltaX, y: deltaY };
+
+    const velocity = {
+      x: calculateVelocity(deltaX, tracking.start.timestamp, tracking.current.timestamp),
+      y: calculateVelocity(deltaY, tracking.start.timestamp, tracking.current.timestamp),
+    };
+
+    if (!isLocked || lockedAxis !== axis) {
+      return { phase: "tracking", displacement, velocity, direction: 0 };
+    }
+
+    const axisDisplacement = axis === "horizontal" ? deltaX : deltaY;
+    return {
+      phase: "swiping",
+      displacement,
+      velocity,
+      direction: determineDirection(axisDisplacement),
+    };
+  }, [tracking.isDown, tracking.start, tracking.current, isLocked, lockedAxis, axis]);
+
+  React.useEffect(() => {
+    if (pointerState.phase !== "idle") {
+      lastActiveStateRef.current = pointerState;
+    }
+  }, [pointerState]);
+
+  // Handle pointer up (but not cancel)
+  React.useEffect(() => {
+    if (tracking.isDown) {
+      return;
+    }
+
+    const lastState = lastActiveStateRef.current;
+    if (!lastState || (lastState.phase !== "swiping" && lastState.phase !== "tracking")) {
+      return;
+    }
+
+    lastActiveStateRef.current = null;
+
+    // Skip navigation if the gesture was canceled (e.g., browser took over for native scroll)
+    if (tracking.wasCanceled) {
+      return;
+    }
+
+    evaluateSwipeEnd(lastState.displacement, lastState.velocity, axis, thresholds, handleSwipeEnd);
+  }, [tracking.isDown, tracking.wasCanceled, axis, thresholds, handleSwipeEnd]);
+
+  // Merge states
+  const state = pointerState.phase !== "idle" ? pointerState : wheelState;
+
+  const containerProps = React.useMemo(() => {
+    const touchAction = axis === "horizontal" ? "pan-y pinch-zoom" : "pan-x pinch-zoom";
+    return {
+      onPointerDown,
+      style: {
+        touchAction,
+        userSelect: "none" as const,
+        WebkitUserSelect: "none" as const,
+      },
+    };
+  }, [axis, onPointerDown]);
+
+  return { state, containerProps };
+}

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

@@ -0,0 +1,152 @@
+/**
+ * @file Unit tests for gesture utility functions.
+ */
+import { calculateVelocity, determineDirection, mergeGestureContainerProps } from "./utils.js";
+import type { GestureContainerProps } from "./utils.js";
+
+describe("calculateVelocity", () => {
+  it("returns 0 when elapsed time is 0", () => {
+    const result = calculateVelocity(100, 1000, 1000);
+    expect(result).toBe(0);
+  });
+
+  it("returns 0 when elapsed time is negative", () => {
+    const result = calculateVelocity(100, 1000, 900);
+    expect(result).toBe(0);
+  });
+
+  it("calculates positive velocity correctly", () => {
+    // 100px in 50ms = 2 px/ms
+    const result = calculateVelocity(100, 1000, 1050);
+    expect(result).toBe(2);
+  });
+
+  it("calculates negative velocity correctly", () => {
+    // -100px in 50ms = -2 px/ms
+    const result = calculateVelocity(-100, 1000, 1050);
+    expect(result).toBe(-2);
+  });
+});
+
+describe("determineDirection", () => {
+  it("returns 1 for positive displacement", () => {
+    expect(determineDirection(10)).toBe(1);
+    expect(determineDirection(0.1)).toBe(1);
+  });
+
+  it("returns -1 for negative displacement", () => {
+    expect(determineDirection(-10)).toBe(-1);
+    expect(determineDirection(-0.1)).toBe(-1);
+  });
+
+  it("returns 0 for zero displacement", () => {
+    expect(determineDirection(0)).toBe(0);
+  });
+});
+
+/**
+ * Simple fake handler that tracks calls.
+ */
+const createFakeHandler = () => {
+  const calls: Array<React.PointerEvent<HTMLElement>> = [];
+  const handler = (event: React.PointerEvent<HTMLElement>) => {
+    calls.push(event);
+  };
+  return { handler, calls };
+};
+
+describe("mergeGestureContainerProps", () => {
+  it("merges styles from multiple props", () => {
+    const props1: GestureContainerProps = {
+      style: { touchAction: "pan-y" },
+    };
+    const props2: GestureContainerProps = {
+      style: { userSelect: "none" },
+    };
+
+    const result = mergeGestureContainerProps(props1, props2);
+
+    expect(result.style).toEqual({
+      touchAction: "pan-y",
+      userSelect: "none",
+    });
+  });
+
+  it("later styles override earlier styles", () => {
+    const props1: GestureContainerProps = {
+      style: { touchAction: "pan-y" },
+    };
+    const props2: GestureContainerProps = {
+      style: { touchAction: "none" },
+    };
+
+    const result = mergeGestureContainerProps(props1, props2);
+
+    expect(result.style.touchAction).toBe("none");
+  });
+
+  it("chains onPointerDown handlers", () => {
+    const fake1 = createFakeHandler();
+    const fake2 = createFakeHandler();
+
+    const props1: GestureContainerProps = {
+      onPointerDown: fake1.handler,
+      style: {},
+    };
+    const props2: GestureContainerProps = {
+      onPointerDown: fake2.handler,
+      style: {},
+    };
+
+    const result = mergeGestureContainerProps(props1, props2);
+    const mockEvent = {} as React.PointerEvent<HTMLElement>;
+    result.onPointerDown?.(mockEvent);
+
+    expect(fake1.calls).toHaveLength(1);
+    expect(fake1.calls[0]).toBe(mockEvent);
+    expect(fake2.calls).toHaveLength(1);
+    expect(fake2.calls[0]).toBe(mockEvent);
+  });
+
+  it("handles props without onPointerDown", () => {
+    const fake = createFakeHandler();
+
+    const props1: GestureContainerProps = {
+      style: { touchAction: "pan-y" },
+    };
+    const props2: GestureContainerProps = {
+      onPointerDown: fake.handler,
+      style: {},
+    };
+
+    const result = mergeGestureContainerProps(props1, props2);
+    const mockEvent = {} as React.PointerEvent<HTMLElement>;
+    result.onPointerDown?.(mockEvent);
+
+    expect(fake.calls).toHaveLength(1);
+    expect(fake.calls[0]).toBe(mockEvent);
+  });
+
+  it("handles empty props array", () => {
+    const result = mergeGestureContainerProps();
+
+    expect(result.style).toEqual({});
+    expect(result.onPointerDown).toBeDefined();
+  });
+
+  it("handles single props", () => {
+    const fake = createFakeHandler();
+    const props: GestureContainerProps = {
+      onPointerDown: fake.handler,
+      style: { touchAction: "pan-y" },
+    };
+
+    const result = mergeGestureContainerProps(props);
+
+    expect(result.style).toEqual({ touchAction: "pan-y" });
+    const mockEvent = {} as React.PointerEvent<HTMLElement>;
+    result.onPointerDown?.(mockEvent);
+    expect(fake.calls).toHaveLength(1);
+    expect(fake.calls[0]).toBe(mockEvent);
+  });
+});

package/src/hooks/gesture/utils.ts

@@ -0,0 +1,178 @@
+/**
+ * @file Utility functions for gesture detection hooks.
+ *
+ * Contains shared calculations and helper functions used across
+ * gesture-related hooks to avoid code duplication.
+ */
+import type * as React from "react";
+
+/**
+ * Calculate velocity from displacement and time elapsed.
+ *
+ * @param displacement - Distance traveled in pixels
+ * @param startTime - Start timestamp in milliseconds
+ * @param currentTime - Current timestamp in milliseconds
+ * @returns Velocity in pixels per millisecond
+ */
+export const calculateVelocity = (
+  displacement: number,
+  startTime: number,
+  currentTime: number,
+): number => {
+  const elapsed = currentTime - startTime;
+  if (elapsed <= 0) {
+    return 0;
+  }
+  return displacement / elapsed;
+};
+
+/**
+ * Determine direction from displacement.
+ *
+ * @param displacement - Distance from start position
+ * @returns -1 for backward (left/up), 0 for no movement, 1 for forward (right/down)
+ */
+export const determineDirection = (displacement: number): -1 | 0 | 1 => {
+  if (displacement > 0) {
+    return 1;
+  }
+  if (displacement < 0) {
+    return -1;
+  }
+  return 0;
+};
+
+/**
+ * Container props type for gesture handling.
+ */
+export type GestureContainerProps = React.HTMLAttributes<HTMLElement> & {
+  style: React.CSSProperties;
+};
+
+/**
+ * Merge multiple container props objects for gesture handling.
+ *
+ * Combines style objects and chains onPointerDown handlers.
+ * Useful when combining multiple gesture hooks that each provide
+ * their own container props (e.g., swipe input + native gesture guard).
+ *
+ * @param propsArray - Array of container props to merge
+ * @returns Merged container props with combined styles and handlers
+ */
+export const mergeGestureContainerProps = (
+  ...propsArray: GestureContainerProps[]
+): GestureContainerProps => {
+  const mergedStyle: React.CSSProperties = {};
+  const pointerDownHandlers: Array<
+    ((event: React.PointerEvent<HTMLElement>) => void) | undefined
+  > = [];
+
+  for (const props of propsArray) {
+    Object.assign(mergedStyle, props.style);
+    if (props.onPointerDown) {
+      pointerDownHandlers.push(props.onPointerDown);
+    }
+  }
+
+  const handlePointerDown = (event: React.PointerEvent<HTMLElement>) => {
+    for (const handler of pointerDownHandlers) {
+      handler?.(event);
+    }
+  };
+
+  return {
+    onPointerDown: handlePointerDown,
+    style: mergedStyle,
+  };
+};
+
+// ============================================================================
+// Scroll Detection Utilities
+// ============================================================================
+
+/**
+ * Check if an element is scrollable in any direction.
+ */
+export function isScrollableElement(element: HTMLElement): boolean {
+  const style = getComputedStyle(element);
+
+  const isScrollableX =
+    (style.overflowX === "scroll" || style.overflowX === "auto") &&
+    element.scrollWidth > element.clientWidth;
+
+  const isScrollableY =
+    (style.overflowY === "scroll" || style.overflowY === "auto") &&
+    element.scrollHeight > element.clientHeight;
+
+  return isScrollableX || isScrollableY;
+}
+
+/**
+ * Check if we should start drag based on scroll state.
+ * Returns false if the target is inside a scrollable element.
+ */
+export function shouldStartDrag(
+  event: React.PointerEvent,
+  container: HTMLElement,
+): boolean {
+  // eslint-disable-next-line no-restricted-syntax -- loop variable requires let
+  let current = event.target as HTMLElement | null;
+
+  while (current !== null && current !== container) {
+    if (isScrollableElement(current)) {
+      return false;
+    }
+    current = current.parentElement;
+  }
+
+  return true;
+}
+
+/**
+ * Check if an element or its ancestors are scrollable in the specified direction.
+ * Returns true if scrolling is possible and would block the swipe gesture.
+ *
+ * @param element - The target element to check
+ * @param container - The container boundary
+ * @param axis - The axis to check ("x" or "y")
+ * @param direction - The swipe direction (1 = right/down, -1 = left/up)
+ */
+export function isScrollableInDirection(
+  element: HTMLElement,
+  container: HTMLElement,
+  axis: "x" | "y",
+  direction: 1 | -1,
+): boolean {
+  // eslint-disable-next-line no-restricted-syntax -- loop variable requires let
+  let current: HTMLElement | null = element;
+
+  while (current !== null && current !== container) {
+    const style = getComputedStyle(current);
+    const isHorizontal = axis === "x";
+
+    const overflow = isHorizontal ? style.overflowX : style.overflowY;
+    const isScrollable = overflow === "scroll" || overflow === "auto";
+
+    if (isScrollable) {
+      const scrollSize = isHorizontal
+        ? current.scrollWidth - current.clientWidth
+        : current.scrollHeight - current.clientHeight;
+
+      if (scrollSize > 0) {
+        const scrollPos = isHorizontal ? current.scrollLeft : current.scrollTop;
+
+        // If swiping in close direction and not at boundary, block swipe
+        if (direction === -1 && scrollPos > 1) {
+          return true; // Can scroll left/up, block swipe
+        }
+        if (direction === 1 && scrollPos < scrollSize - 1) {
+          return true; // Can scroll right/down, block swipe
+        }
+      }
+    }
+
+    current = current.parentElement;
+  }
+
+  return false;
+}