react-panel-layout 0.5.2 → 0.6.1

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

@@ -0,0 +1,473 @@
+/**
+ * @file Tests for useNativeGestureGuard hook.
+ */
+import { renderHook, act } from "@testing-library/react";
+import * as React from "react";
+import { useNativeGestureGuard } from "./useNativeGestureGuard.js";
+
+/**
+ * Extended PointerEvent type with test utility method.
+ */
+type TestPointerEvent = React.PointerEvent<HTMLElement> & {
+  wasDefaultPrevented: () => boolean;
+};
+
+/**
+ * Creates a mock PointerEvent that satisfies the React.PointerEvent interface.
+ */
+function createMockPointerEvent(props: {
+  clientX: number;
+  clientY: number;
+  pointerType: string;
+}): TestPointerEvent {
+  const noop = (): void => {};
+  const noopBool = (): boolean => false;
+  const state = { preventDefaultCalled: false };
+
+  const element = document.createElement("div");
+  const nativeEvent = new PointerEvent("pointerdown", {
+    clientX: props.clientX,
+    clientY: props.clientY,
+    pointerType: props.pointerType,
+  });
+
+  return {
+    ...props,
+    // Test utility
+    wasDefaultPrevented: () => state.preventDefaultCalled,
+    // Event target
+    target: element,
+    currentTarget: element,
+    // Native event
+    nativeEvent,
+    // SyntheticEvent properties
+    bubbles: true,
+    cancelable: true,
+    defaultPrevented: false,
+    eventPhase: 0,
+    isTrusted: true,
+    preventDefault: () => {
+      state.preventDefaultCalled = true;
+    },
+    isDefaultPrevented: () => state.preventDefaultCalled,
+    stopPropagation: noop,
+    isPropagationStopped: noopBool,
+    persist: noop,
+    timeStamp: Date.now(),
+    type: "pointerdown",
+    // MouseEvent properties
+    altKey: false,
+    button: 0,
+    buttons: 1,
+    ctrlKey: false,
+    metaKey: false,
+    shiftKey: false,
+    getModifierState: noopBool,
+    movementX: 0,
+    movementY: 0,
+    pageX: props.clientX,
+    pageY: props.clientY,
+    relatedTarget: null,
+    screenX: props.clientX,
+    screenY: props.clientY,
+    // PointerEvent properties
+    height: 1,
+    isPrimary: true,
+    pointerId: 1,
+    pressure: 0.5,
+    tangentialPressure: 0,
+    tiltX: 0,
+    tiltY: 0,
+    twist: 0,
+    width: 1,
+    // UIEvent properties
+    detail: 0,
+    view: window,
+  };
+}
+
+describe("useNativeGestureGuard", () => {
+  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: () => ({}),
+    };
+    // Override getBoundingClientRect directly instead of using vi.spyOn
+    element.getBoundingClientRect = () => ({ ...defaultRect, ...rect });
+    return { current: element };
+  };
+
+  describe("overscroll behavior", () => {
+    it("applies overscroll-behavior: contain when active and preventOverscroll is true", () => {
+      const containerRef = createRef();
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: true,
+          preventOverscroll: true,
+        }),
+      );
+
+      expect(result.current.containerProps.style.overscrollBehavior).toBe("contain");
+    });
+
+    it("applies overscroll-behavior immediately even when not active", () => {
+      // Styles are applied immediately (not waiting for active) to prevent browser gestures
+      const containerRef = createRef();
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: false,
+          preventOverscroll: true,
+        }),
+      );
+
+      expect(result.current.containerProps.style.overscrollBehavior).toBe("contain");
+    });
+
+    it("does not apply overscroll-behavior when preventOverscroll is false", () => {
+      const containerRef = createRef();
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: true,
+          preventOverscroll: false,
+        }),
+      );
+
+      expect(result.current.containerProps.style.overscrollBehavior).toBeUndefined();
+    });
+  });
+
+  describe("edge back prevention", () => {
+    it("calls preventDefault for touch events in left edge zone", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: true,
+          preventEdgeBack: true,
+          edgeWidth: 20,
+        }),
+      );
+
+      const mockEvent = createMockPointerEvent({
+        clientX: 10, // Within 20px edge zone
+        clientY: 100,
+        pointerType: "touch",
+      });
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(mockEvent.wasDefaultPrevented()).toBe(true);
+    });
+
+    it("does not call preventDefault for touch events outside left edge zone", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: true,
+          preventEdgeBack: true,
+          edgeWidth: 20,
+        }),
+      );
+
+      const mockEvent = createMockPointerEvent({
+        clientX: 50, // Outside 20px edge zone
+        clientY: 100,
+        pointerType: "touch",
+      });
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(mockEvent.wasDefaultPrevented()).toBe(false);
+    });
+
+    it("does not call preventDefault for mouse events in edge zone", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: true,
+          preventEdgeBack: true,
+          edgeWidth: 20,
+        }),
+      );
+
+      const mockEvent = createMockPointerEvent({
+        clientX: 10, // Within edge zone
+        clientY: 100,
+        pointerType: "mouse", // Not touch
+      });
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(mockEvent.wasDefaultPrevented()).toBe(false);
+    });
+
+    it("calls preventDefault even when not active (browser gesture starts immediately)", () => {
+      // Browser gesture recognition starts immediately on pointerdown,
+      // so we must preventDefault before we know if it's "our" gesture
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: false,
+          preventEdgeBack: true,
+          edgeWidth: 20,
+        }),
+      );
+
+      const mockEvent = createMockPointerEvent({
+        clientX: 10,
+        clientY: 100,
+        pointerType: "touch",
+      });
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(mockEvent.wasDefaultPrevented()).toBe(true);
+    });
+
+    it("does not call preventDefault when preventEdgeBack is false", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: true,
+          preventEdgeBack: false,
+          edgeWidth: 20,
+        }),
+      );
+
+      // onPointerDown should be undefined when preventEdgeBack is false
+      expect(result.current.containerProps.onPointerDown).toBeUndefined();
+    });
+
+    it("does not provide onPointerDown when preventEdgeBack is false", () => {
+      const containerRef = createRef();
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: true,
+          preventEdgeBack: false,
+        }),
+      );
+
+      expect(result.current.containerProps.onPointerDown).toBeUndefined();
+    });
+  });
+
+  describe("edge width configuration", () => {
+    it("respects custom edge width", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: true,
+          preventEdgeBack: true,
+          edgeWidth: 50,
+        }),
+      );
+
+      const mockEventInCustomEdge = createMockPointerEvent({
+        clientX: 40, // Within 50px edge, but outside default 20px
+        clientY: 100,
+        pointerType: "touch",
+      });
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEventInCustomEdge);
+      });
+
+      expect(mockEventInCustomEdge.wasDefaultPrevented()).toBe(true);
+    });
+  });
+
+  describe("iOS smooth scrolling", () => {
+    it("always applies WebkitOverflowScrolling: touch", () => {
+      const containerRef = createRef();
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: false,
+        }),
+      );
+
+      expect(result.current.containerProps.style.WebkitOverflowScrolling).toBe("touch");
+    });
+  });
+
+  describe("null container ref", () => {
+    it("handles null container ref gracefully", () => {
+      const containerRef = { current: null };
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: true,
+          preventEdgeBack: true,
+        }),
+      );
+
+      const mockEvent = createMockPointerEvent({
+        clientX: 10,
+        clientY: 100,
+        pointerType: "touch",
+      });
+
+      // Should not throw
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(mockEvent.wasDefaultPrevented()).toBe(false);
+    });
+  });
+
+  describe("html overscroll-behavior", () => {
+    beforeEach(() => {
+      // Reset html style before each test
+      document.documentElement.style.overscrollBehavior = "";
+    });
+
+    afterEach(() => {
+      // Clean up after each test
+      document.documentElement.style.overscrollBehavior = "";
+    });
+
+    it("applies overscroll-behavior: none to html synchronously on pointerdown in edge zone", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: false,
+          preventEdgeBack: true,
+          preventOverscroll: true,
+          edgeWidth: 20,
+        }),
+      );
+
+      expect(document.documentElement.style.overscrollBehavior).toBe("");
+
+      const mockEvent = createMockPointerEvent({
+        clientX: 10,
+        clientY: 100,
+        pointerType: "touch",
+      });
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      // Applied synchronously in onPointerDown, not waiting for useEffect
+      expect(document.documentElement.style.overscrollBehavior).toBe("none");
+    });
+
+    it("removes overscroll-behavior from html when deactivated", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result, rerender } = renderHook(
+        ({ active }) =>
+          useNativeGestureGuard({
+            containerRef,
+            active,
+            preventEdgeBack: true,
+            preventOverscroll: true,
+            edgeWidth: 20,
+          }),
+        { initialProps: { active: false } },
+      );
+
+      // Simulate pointerdown to apply style
+      const mockEvent = createMockPointerEvent({
+        clientX: 10,
+        clientY: 100,
+        pointerType: "touch",
+      });
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(document.documentElement.style.overscrollBehavior).toBe("none");
+
+      // Simulate gesture becoming active then inactive
+      rerender({ active: true });
+      rerender({ active: false });
+
+      expect(document.documentElement.style.overscrollBehavior).toBe("");
+    });
+
+    it("restores previous overscroll-behavior value on cleanup", () => {
+      document.documentElement.style.overscrollBehavior = "contain";
+
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result, unmount } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: false,
+          preventEdgeBack: true,
+          preventOverscroll: true,
+          edgeWidth: 20,
+        }),
+      );
+
+      // Simulate pointerdown to apply style
+      const mockEvent = createMockPointerEvent({
+        clientX: 10,
+        clientY: 100,
+        pointerType: "touch",
+      });
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(document.documentElement.style.overscrollBehavior).toBe("none");
+
+      unmount();
+      expect(document.documentElement.style.overscrollBehavior).toBe("contain");
+    });
+
+    it("does not apply to html when preventOverscroll is false", () => {
+      const containerRef = createRef({ left: 0, right: 300 });
+      const { result } = renderHook(() =>
+        useNativeGestureGuard({
+          containerRef,
+          active: false,
+          preventEdgeBack: true,
+          preventOverscroll: false,
+          edgeWidth: 20,
+        }),
+      );
+
+      const mockEvent = createMockPointerEvent({
+        clientX: 10,
+        clientY: 100,
+        pointerType: "touch",
+      });
+
+      act(() => {
+        result.current.containerProps.onPointerDown?.(mockEvent);
+      });
+
+      expect(document.documentElement.style.overscrollBehavior).toBe("");
+    });
+  });
+});

package/src/hooks/gesture/useNativeGestureGuard.ts

@@ -0,0 +1,135 @@
+/**
+ * @file Hook for preventing conflicts with native OS gestures.
+ *
+ * This hook helps prevent conflicts with:
+ * - iOS/macOS edge swipe back navigation
+ * - Overscroll bounce effects
+ *
+ * It applies appropriate CSS properties and event handlers to the container.
+ */
+import * as React from "react";
+import type {
+  UseNativeGestureGuardOptions,
+  UseNativeGestureGuardResult,
+} from "./types.js";
+import { DEFAULT_EDGE_WIDTH } from "./types.js";
+
+/**
+ * Check if a pointer event is within the left edge zone.
+ */
+const isInLeftEdge = (clientX: number, container: HTMLElement, edgeWidth: number): boolean => {
+  const rect = container.getBoundingClientRect();
+  return clientX >= rect.left && clientX <= rect.left + edgeWidth;
+};
+
+/**
+ * Hook for preventing conflicts with native OS gestures.
+ *
+ * When active, this hook:
+ * - Prevents iOS/macOS edge back gesture by capturing pointerdown events in the edge zone
+ * - Prevents overscroll bounce effect using CSS overscroll-behavior
+ * - Dynamically applies overscroll-behavior: none to html element during gesture
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const { containerProps } = useNativeGestureGuard({
+ *   containerRef,
+ *   active: isSwipeActive,
+ *   preventEdgeBack: true,
+ *   preventOverscroll: true,
+ * });
+ *
+ * return <div ref={containerRef} {...containerProps}>{children}</div>;
+ * ```
+ */
+export function useNativeGestureGuard(options: UseNativeGestureGuardOptions): UseNativeGestureGuardResult {
+  const {
+    containerRef,
+    active,
+    preventEdgeBack = true,
+    preventOverscroll = true,
+    edgeWidth = DEFAULT_EDGE_WIDTH,
+  } = options;
+
+  // Track previous html overscroll-behavior value for restoration
+  const previousHtmlOverscrollRef = React.useRef<string | null>(null);
+
+  // Apply overscroll-behavior to html synchronously (called from onPointerDown)
+  const applyHtmlOverscroll = React.useCallback(() => {
+    if (!preventOverscroll) {
+      return;
+    }
+
+    const html = document.documentElement;
+    if (previousHtmlOverscrollRef.current === null) {
+      previousHtmlOverscrollRef.current = html.style.overscrollBehavior;
+    }
+    html.style.overscrollBehavior = "none";
+  }, [preventOverscroll]);
+
+  // Remove overscroll-behavior from html when gesture ends
+  React.useEffect(() => {
+    if (active || !preventOverscroll) {
+      return;
+    }
+
+    // Cleanup: restore previous value when deactivated
+    if (previousHtmlOverscrollRef.current !== null) {
+      document.documentElement.style.overscrollBehavior = previousHtmlOverscrollRef.current;
+      previousHtmlOverscrollRef.current = null;
+    }
+  }, [active, preventOverscroll]);
+
+  // Cleanup on unmount
+  React.useEffect(() => {
+    return () => {
+      if (previousHtmlOverscrollRef.current !== null) {
+        document.documentElement.style.overscrollBehavior = previousHtmlOverscrollRef.current;
+        previousHtmlOverscrollRef.current = null;
+      }
+    };
+  }, []);
+
+  // Pointer down handler that prevents edge back gesture
+  // Note: This must run on EVERY pointerdown in edge zone, not just when active,
+  // because browser gesture recognition starts immediately on first touch.
+  const onPointerDown = React.useCallback((event: React.PointerEvent) => {
+    if (!preventEdgeBack) {
+      return;
+    }
+
+    const container = containerRef.current;
+    if (!container) {
+      return;
+    }
+
+    // Prevent for touch events in the left edge zone
+    // This must happen immediately, before we know if it's "our" gesture
+    if (event.pointerType === "touch" && isInLeftEdge(event.clientX, container, edgeWidth)) {
+      // Apply html overscroll-behavior synchronously before browser can recognize gesture
+      applyHtmlOverscroll();
+      // Prevent the browser from handling this as a back gesture
+      event.preventDefault();
+    }
+  }, [preventEdgeBack, containerRef, edgeWidth, applyHtmlOverscroll]);
+
+  // Build container props
+  // Styles are applied immediately (not waiting for active) to prevent browser gestures
+  const containerProps = React.useMemo(() => {
+    const style: React.CSSProperties = {
+      // Always apply to prevent browser navigation gestures
+      overscrollBehavior: preventOverscroll ? "contain" : undefined,
+      WebkitOverflowScrolling: "touch",
+    };
+
+    return {
+      onPointerDown: preventEdgeBack ? onPointerDown : undefined,
+      style,
+    };
+  }, [preventOverscroll, preventEdgeBack, onPointerDown]);
+
+  return {
+    containerProps,
+  };
+}