react-panel-layout 0.6.0 → 0.6.1

package/src/hooks/gesture/testing/createGestureSimulator.ts

@@ -4,8 +4,83 @@
  * Provides a fluent API for simulating pointer events in tests,
  * making it easier to test swipe and drag gestures.
  */
+import type * as React from "react";
 import { act } from "@testing-library/react";
 
+/**
+ * Creates a complete mock React.PointerEvent with all required properties.
+ */
+function createFullPointerEvent(
+  type: string,
+  x: number,
+  y: number,
+  pointerId: number,
+  pointerType: "touch" | "mouse" | "pen",
+): React.PointerEvent {
+  const noop = (): void => {};
+  const noopBool = (): boolean => false;
+
+  const element = document.createElement("div");
+  const nativeEvent = new PointerEvent(type, {
+    clientX: x,
+    clientY: y,
+    pointerId,
+    pointerType,
+  });
+
+  return {
+    clientX: x,
+    clientY: y,
+    pointerId,
+    pointerType,
+    isPrimary: true,
+    button: 0,
+    preventDefault: noop,
+    stopPropagation: noop,
+    // Event target
+    target: element,
+    currentTarget: element,
+    // Native event
+    nativeEvent,
+    // SyntheticEvent properties
+    bubbles: true,
+    cancelable: true,
+    defaultPrevented: false,
+    eventPhase: 0,
+    isTrusted: true,
+    isDefaultPrevented: noopBool,
+    isPropagationStopped: noopBool,
+    persist: noop,
+    timeStamp: Date.now(),
+    type,
+    // MouseEvent properties
+    altKey: false,
+    buttons: 1,
+    ctrlKey: false,
+    metaKey: false,
+    shiftKey: false,
+    getModifierState: noopBool,
+    movementX: 0,
+    movementY: 0,
+    pageX: x,
+    pageY: y,
+    relatedTarget: null,
+    screenX: x,
+    screenY: y,
+    // PointerEvent properties
+    height: 1,
+    pressure: 0.5,
+    tangentialPressure: 0,
+    tiltX: 0,
+    tiltY: 0,
+    twist: 0,
+    width: 1,
+    // UIEvent properties
+    detail: 0,
+    view: window as unknown as React.AbstractView,
+  };
+}
+
 /**
  * 2D point for gesture coordinates.
  */
@@ -107,10 +182,10 @@ export function createGestureSimulator(options: GestureSimulatorOptions = {}): G
     pointerId = 1,
   } = options;
 
-  let isDown = false;
+  const pointerState = { isDown: false };
 
   const pointerDown = (x: number, y: number): void => {
-    isDown = true;
+    pointerState.isDown = true;
 
     const event = new PointerEvent("pointerdown", {
       clientX: x,
@@ -129,7 +204,7 @@ export function createGestureSimulator(options: GestureSimulatorOptions = {}): G
   };
 
   const pointerMove = (x: number, y: number): void => {
-    if (!isDown) {
+    if (!pointerState.isDown) {
       return;
     }
 
@@ -149,11 +224,11 @@ export function createGestureSimulator(options: GestureSimulatorOptions = {}): G
   };
 
   const pointerUp = (): void => {
-    if (!isDown) {
+    if (!pointerState.isDown) {
       return;
     }
 
-    isDown = false;
+    pointerState.isDown = false;
 
     const event = new PointerEvent("pointerup", {
       pointerId,
@@ -188,28 +263,37 @@ export function createGestureSimulator(options: GestureSimulatorOptions = {}): G
     containerSize = 300,
   ): void => {
     const edgeOffset = 10; // Start 10px from edge
-
-    let from: Point;
-    let to: Point;
-
-    switch (edge) {
-      case "left":
-        from = { x: edgeOffset, y: containerSize / 2 };
-        to = { x: edgeOffset + distance, y: containerSize / 2 };
-        break;
-      case "right":
-        from = { x: containerSize - edgeOffset, y: containerSize / 2 };
-        to = { x: containerSize - edgeOffset - distance, y: containerSize / 2 };
-        break;
-      case "top":
-        from = { x: containerSize / 2, y: edgeOffset };
-        to = { x: containerSize / 2, y: edgeOffset + distance };
-        break;
-      case "bottom":
-        from = { x: containerSize / 2, y: containerSize - edgeOffset };
-        to = { x: containerSize / 2, y: containerSize - edgeOffset - distance };
-        break;
-    }
+    const getEdgeSwipePoints = (
+      direction: "left" | "right" | "top" | "bottom",
+      size: number,
+      travel: number,
+      offset: number,
+    ): { from: Point; to: Point } => {
+      if (direction === "left") {
+        return {
+          from: { x: offset, y: size / 2 },
+          to: { x: offset + travel, y: size / 2 },
+        };
+      }
+      if (direction === "right") {
+        return {
+          from: { x: size - offset, y: size / 2 },
+          to: { x: size - offset - travel, y: size / 2 },
+        };
+      }
+      if (direction === "top") {
+        return {
+          from: { x: size / 2, y: offset },
+          to: { x: size / 2, y: offset + travel },
+        };
+      }
+      return {
+        from: { x: size / 2, y: size - offset },
+        to: { x: size / 2, y: size - offset - travel },
+      };
+    };
+
+    const { from, to } = getEdgeSwipePoints(edge, containerSize, distance, edgeOffset);
 
     swipe(from, to);
   };
@@ -219,16 +303,7 @@ export function createGestureSimulator(options: GestureSimulatorOptions = {}): G
     x: number,
     y: number,
   ): React.PointerEvent => {
-    return {
-      clientX: x,
-      clientY: y,
-      pointerId,
-      pointerType,
-      isPrimary: true,
-      button: 0,
-      preventDefault: () => {},
-      stopPropagation: () => {},
-    } as unknown as React.PointerEvent;
+    return createFullPointerEvent(type, x, y, pointerId, pointerType);
   };
 
   return {

package/src/hooks/gesture/types.ts

@@ -6,7 +6,9 @@
  * - Input: how to command (swipe, click, keyboard)
  * - Presentation: how to show (animation, transition)
  *
- * This file defines types for the Input layer.
+ * This file defines types for the Input layer, including the abstract
+ * ContinuousOperationState that represents any continuous state transition
+ * (whether controlled by human gesture or system animation).
  */
 import type * as React from "react";
 
@@ -15,11 +17,6 @@ import type * as React from "react";
  */
 export type GestureAxis = "horizontal" | "vertical";
 
-/**
- * Phase of swipe input lifecycle.
- */
-export type SwipeInputPhase = "idle" | "tracking" | "swiping" | "ended";
-
 /**
  * 2D vector for displacement and velocity.
  */
@@ -28,6 +25,86 @@ export type Vector2 = {
   y: number;
 };
 
+// ============================================================================
+// Continuous Operation State
+// ============================================================================
+// A continuous operation is any state transition that occurs over time,
+// where progress can be observed incrementally. The controlling agent
+// may be human (gesture) or system (animation).
+
+/**
+ * Phase of a continuous operation lifecycle.
+ * - "idle": No operation in progress
+ * - "operating": Operation is in progress (human or system controlled)
+ * - "ended": Operation has completed
+ */
+export type ContinuousOperationPhase = "idle" | "operating" | "ended";
+
+/**
+ * State of a continuous operation.
+ *
+ * This is the abstract representation of any operation that occurs over time,
+ * whether controlled by human gesture or system animation. Components that
+ * accept this state can respond to both input types uniformly.
+ */
+export type ContinuousOperationState = {
+  /** Current phase of the operation */
+  phase: ContinuousOperationPhase;
+  /** Displacement from start position in pixels */
+  displacement: Vector2;
+  /** Current velocity in pixels per millisecond */
+  velocity: Vector2;
+};
+
+/**
+ * Initial idle state for ContinuousOperationState.
+ */
+export const IDLE_CONTINUOUS_OPERATION_STATE: ContinuousOperationState = {
+  phase: "idle",
+  displacement: { x: 0, y: 0 },
+  velocity: { x: 0, y: 0 },
+};
+
+/**
+ * Convert SwipeInputPhase to ContinuousOperationPhase.
+ * - "idle" → "idle"
+ * - "tracking" | "swiping" → "operating"
+ * - "ended" → "ended"
+ */
+export function toContinuousPhase(phase: SwipeInputPhase): ContinuousOperationPhase {
+  if (phase === "idle") {
+    return "idle";
+  }
+  if (phase === "ended") {
+    return "ended";
+  }
+  return "operating";
+}
+
+/**
+ * Convert SwipeInputState to ContinuousOperationState.
+ */
+export function toContinuousOperationState(state: SwipeInputState): ContinuousOperationState {
+  return {
+    phase: toContinuousPhase(state.phase),
+    displacement: state.displacement,
+    velocity: state.velocity,
+  };
+}
+
+// ============================================================================
+// Swipe Input (concrete implementation of continuous operation)
+// ============================================================================
+
+/**
+ * Phase of swipe input lifecycle.
+ * - "idle": No swipe in progress
+ * - "tracking": Pointer down, tracking movement (direction not yet locked)
+ * - "swiping": Direction locked, actively swiping
+ * - "ended": Swipe gesture completed
+ */
+export type SwipeInputPhase = "idle" | "tracking" | "swiping" | "ended";
+
 /**
  * Point with timestamp for velocity calculation.
  */

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

@@ -1,19 +1,23 @@
 /**
  * @file Tests for useEdgeSwipeInput hook.
  */
-/* eslint-disable no-restricted-globals, no-restricted-properties -- test requires vi for timing control */
 import { renderHook, act } from "@testing-library/react";
 import * as React from "react";
 import { useEdgeSwipeInput } from "./useEdgeSwipeInput.js";
 
 describe("useEdgeSwipeInput", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-  });
+  type CallTracker = {
+    calls: ReadonlyArray<ReadonlyArray<unknown>>;
+    fn: (...args: ReadonlyArray<unknown>) => void;
+  };
 
-  afterEach(() => {
-    vi.useRealTimers();
-  });
+  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");
@@ -28,7 +32,10 @@ describe("useEdgeSwipeInput", () => {
       y: 0,
       toJSON: () => ({}),
     };
-    vi.spyOn(element, "getBoundingClientRect").mockReturnValue({ ...defaultRect, ...rect });
+    const mergedRect = Object.assign({}, defaultRect, rect);
+    Object.defineProperty(element, "getBoundingClientRect", {
+      value: () => mergedRect,
+    });
     return { current: element };
   };
 
@@ -283,7 +290,7 @@ describe("useEdgeSwipeInput", () => {
   describe("swipe completion callback", () => {
     it("calls onSwipeEnd when edge swipe threshold is met", () => {
       const containerRef = createRef({ left: 0, right: 300 });
-      const onSwipeEnd = vi.fn();
+      const onSwipeEnd = createCallTracker();
 
       const { result } = renderHook(() =>
         useEdgeSwipeInput({
@@ -291,7 +298,7 @@ describe("useEdgeSwipeInput", () => {
           edge: "left",
           edgeWidth: 20,
           thresholds: { distanceThreshold: 50, velocityThreshold: 0.3, lockThreshold: 10 },
-          onSwipeEnd,
+          onSwipeEnd: onSwipeEnd.fn,
         }),
       );
 
@@ -327,7 +334,8 @@ describe("useEdgeSwipeInput", () => {
         document.dispatchEvent(upEvent);
       });
 
-      expect(onSwipeEnd).toHaveBeenCalledWith(
+      expect(onSwipeEnd.calls).toHaveLength(1);
+      expect(onSwipeEnd.calls[0]?.[0]).toEqual(
         expect.objectContaining({
           phase: "ended",
           direction: 1,
@@ -337,7 +345,7 @@ describe("useEdgeSwipeInput", () => {
 
     it("does not call onSwipeEnd when gesture starts outside edge", () => {
       const containerRef = createRef({ left: 0, right: 300 });
-      const onSwipeEnd = vi.fn();
+      const onSwipeEnd = createCallTracker();
 
       const { result } = renderHook(() =>
         useEdgeSwipeInput({
@@ -345,7 +353,7 @@ describe("useEdgeSwipeInput", () => {
           edge: "left",
           edgeWidth: 20,
           thresholds: { distanceThreshold: 50, velocityThreshold: 0.3, lockThreshold: 10 },
-          onSwipeEnd,
+          onSwipeEnd: onSwipeEnd.fn,
         }),
       );
 
@@ -365,7 +373,7 @@ describe("useEdgeSwipeInput", () => {
 
       // The gesture should not be tracked, so no callback should be fired
       expect(result.current.isEdgeGesture).toBe(false);
-      expect(onSwipeEnd).not.toHaveBeenCalled();
+      expect(onSwipeEnd.calls).toHaveLength(0);
     });
   });
 

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

@@ -1,11 +1,91 @@
 /**
  * @file Tests for useNativeGestureGuard hook.
  */
-/* eslint-disable custom/no-as-outside-guard -- test requires overrides */
 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");
@@ -25,26 +105,6 @@ describe("useNativeGestureGuard", () => {
     return { current: element };
   };
 
-  /**
-   * Creates a fake pointer event with preventDefault tracking.
-   * Uses an object to track state instead of let variable.
-   */
-  const createFakePointerEvent = (props: {
-    clientX: number;
-    clientY: number;
-    pointerType: string;
-  }) => {
-    const state = { preventDefaultCalled: false };
-    const event = {
-      ...props,
-      preventDefault: () => {
-        state.preventDefaultCalled = true;
-      },
-      wasDefaultPrevented: () => state.preventDefaultCalled,
-    };
-    return event as unknown as React.PointerEvent<HTMLElement> & { wasDefaultPrevented: () => boolean };
-  };
-
   describe("overscroll behavior", () => {
     it("applies overscroll-behavior: contain when active and preventOverscroll is true", () => {
       const containerRef = createRef();
@@ -99,7 +159,7 @@ describe("useNativeGestureGuard", () => {
         }),
       );
 
-      const mockEvent = createFakePointerEvent({
+      const mockEvent = createMockPointerEvent({
         clientX: 10, // Within 20px edge zone
         clientY: 100,
         pointerType: "touch",
@@ -123,7 +183,7 @@ describe("useNativeGestureGuard", () => {
         }),
       );
 
-      const mockEvent = createFakePointerEvent({
+      const mockEvent = createMockPointerEvent({
         clientX: 50, // Outside 20px edge zone
         clientY: 100,
         pointerType: "touch",
@@ -147,7 +207,7 @@ describe("useNativeGestureGuard", () => {
         }),
       );
 
-      const mockEvent = createFakePointerEvent({
+      const mockEvent = createMockPointerEvent({
         clientX: 10, // Within edge zone
         clientY: 100,
         pointerType: "mouse", // Not touch
@@ -173,7 +233,7 @@ describe("useNativeGestureGuard", () => {
         }),
       );
 
-      const mockEvent = createFakePointerEvent({
+      const mockEvent = createMockPointerEvent({
         clientX: 10,
         clientY: 100,
         pointerType: "touch",
@@ -227,7 +287,7 @@ describe("useNativeGestureGuard", () => {
         }),
       );
 
-      const mockEventInCustomEdge = createFakePointerEvent({
+      const mockEventInCustomEdge = createMockPointerEvent({
         clientX: 40, // Within 50px edge, but outside default 20px
         clientY: 100,
         pointerType: "touch",
@@ -266,7 +326,7 @@ describe("useNativeGestureGuard", () => {
         }),
       );
 
-      const mockEvent = createFakePointerEvent({
+      const mockEvent = createMockPointerEvent({
         clientX: 10,
         clientY: 100,
         pointerType: "touch",
@@ -306,7 +366,7 @@ describe("useNativeGestureGuard", () => {
 
       expect(document.documentElement.style.overscrollBehavior).toBe("");
 
-      const mockEvent = createFakePointerEvent({
+      const mockEvent = createMockPointerEvent({
         clientX: 10,
         clientY: 100,
         pointerType: "touch",
@@ -335,7 +395,7 @@ describe("useNativeGestureGuard", () => {
       );
 
       // Simulate pointerdown to apply style
-      const mockEvent = createFakePointerEvent({
+      const mockEvent = createMockPointerEvent({
         clientX: 10,
         clientY: 100,
         pointerType: "touch",
@@ -369,7 +429,7 @@ describe("useNativeGestureGuard", () => {
       );
 
       // Simulate pointerdown to apply style
-      const mockEvent = createFakePointerEvent({
+      const mockEvent = createMockPointerEvent({
         clientX: 10,
         clientY: 100,
         pointerType: "touch",
@@ -397,7 +457,7 @@ describe("useNativeGestureGuard", () => {
         }),
       );
 
-      const mockEvent = createFakePointerEvent({
+      const mockEvent = createMockPointerEvent({
         clientX: 10,
         clientY: 100,
         pointerType: "touch",

package/src/hooks/gesture/useNativeGestureGuard.ts

@@ -57,7 +57,9 @@ export function useNativeGestureGuard(options: UseNativeGestureGuardOptions): Us
 
   // Apply overscroll-behavior to html synchronously (called from onPointerDown)
   const applyHtmlOverscroll = React.useCallback(() => {
-    if (!preventOverscroll) return;
+    if (!preventOverscroll) {
+      return;
+    }
 
     const html = document.documentElement;
     if (previousHtmlOverscrollRef.current === null) {