react-panel-layout 0.6.0 → 0.7.0

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

@@ -1,158 +1,162 @@
 /**
  * @file Tests for gesture simulator utilities.
  */
-/* eslint-disable no-restricted-globals, no-restricted-properties -- test utilities need vi for timing and mocks */
 import {
   createGestureSimulator,
   createMockContainer,
   createMockContainerRef,
 } from "./createGestureSimulator.js";
 
-describe("createGestureSimulator", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-  });
+type EventTracker = {
+  calls: ReadonlyArray<PointerEvent>;
+  handler: (event: Event) => void;
+};
 
-  afterEach(() => {
-    vi.useRealTimers();
-  });
+const createEventTracker = (): EventTracker => {
+  const calls: PointerEvent[] = [];
+  const handler = (event: Event): void => {
+    calls.push(event as PointerEvent);
+  };
+  return { calls, handler };
+};
 
+describe("createGestureSimulator", () => {
   describe("pointerDown", () => {
     it("dispatches pointerdown event", () => {
       const simulator = createGestureSimulator();
-      const handler = vi.fn();
-      document.addEventListener("pointerdown", handler);
+      const tracker = createEventTracker();
+      document.addEventListener("pointerdown", tracker.handler);
 
       simulator.pointerDown(100, 200);
 
-      expect(handler).toHaveBeenCalledTimes(1);
-      const event = handler.mock.calls[0][0] as PointerEvent;
+      expect(tracker.calls).toHaveLength(1);
+      const event = tracker.calls[0] as PointerEvent;
       expect(event.clientX).toBe(100);
       expect(event.clientY).toBe(200);
       expect(event.pointerType).toBe("touch");
       expect(event.pointerId).toBe(1);
 
-      document.removeEventListener("pointerdown", handler);
+      document.removeEventListener("pointerdown", tracker.handler);
     });
   });
 
   describe("pointerMove", () => {
     it("dispatches pointermove event after pointerdown", () => {
       const simulator = createGestureSimulator();
-      const handler = vi.fn();
-      document.addEventListener("pointermove", handler);
+      const tracker = createEventTracker();
+      document.addEventListener("pointermove", tracker.handler);
 
       simulator.pointerDown(100, 100);
       simulator.pointerMove(150, 120);
 
-      expect(handler).toHaveBeenCalledTimes(1);
-      const event = handler.mock.calls[0][0] as PointerEvent;
+      expect(tracker.calls).toHaveLength(1);
+      const event = tracker.calls[0] as PointerEvent;
       expect(event.clientX).toBe(150);
       expect(event.clientY).toBe(120);
 
-      document.removeEventListener("pointermove", handler);
+      document.removeEventListener("pointermove", tracker.handler);
     });
 
     it("does not dispatch pointermove if pointer is not down", () => {
       const simulator = createGestureSimulator();
-      const handler = vi.fn();
-      document.addEventListener("pointermove", handler);
+      const tracker = createEventTracker();
+      document.addEventListener("pointermove", tracker.handler);
 
       simulator.pointerMove(150, 120);
 
-      expect(handler).not.toHaveBeenCalled();
+      expect(tracker.calls).toHaveLength(0);
 
-      document.removeEventListener("pointermove", handler);
+      document.removeEventListener("pointermove", tracker.handler);
     });
   });
 
   describe("pointerUp", () => {
     it("dispatches pointerup event", () => {
       const simulator = createGestureSimulator();
-      const handler = vi.fn();
-      document.addEventListener("pointerup", handler);
+      const tracker = createEventTracker();
+      document.addEventListener("pointerup", tracker.handler);
 
       simulator.pointerDown(100, 100);
       simulator.pointerUp();
 
-      expect(handler).toHaveBeenCalledTimes(1);
+      expect(tracker.calls).toHaveLength(1);
 
-      document.removeEventListener("pointerup", handler);
+      document.removeEventListener("pointerup", tracker.handler);
     });
 
     it("does not dispatch pointerup if pointer is not down", () => {
       const simulator = createGestureSimulator();
-      const handler = vi.fn();
-      document.addEventListener("pointerup", handler);
+      const tracker = createEventTracker();
+      document.addEventListener("pointerup", tracker.handler);
 
       simulator.pointerUp();
 
-      expect(handler).not.toHaveBeenCalled();
+      expect(tracker.calls).toHaveLength(0);
 
-      document.removeEventListener("pointerup", handler);
+      document.removeEventListener("pointerup", tracker.handler);
     });
   });
 
   describe("swipe", () => {
     it("dispatches complete swipe sequence", () => {
       const simulator = createGestureSimulator();
-      const downHandler = vi.fn();
-      const moveHandler = vi.fn();
-      const upHandler = vi.fn();
+      const downTracker = createEventTracker();
+      const moveTracker = createEventTracker();
+      const upTracker = createEventTracker();
 
-      document.addEventListener("pointerdown", downHandler);
-      document.addEventListener("pointermove", moveHandler);
-      document.addEventListener("pointerup", upHandler);
+      document.addEventListener("pointerdown", downTracker.handler);
+      document.addEventListener("pointermove", moveTracker.handler);
+      document.addEventListener("pointerup", upTracker.handler);
 
       simulator.swipe({ x: 100, y: 100 }, { x: 200, y: 100 }, 5);
 
-      expect(downHandler).toHaveBeenCalledTimes(1);
-      expect(moveHandler).toHaveBeenCalledTimes(5); // 5 steps
-      expect(upHandler).toHaveBeenCalledTimes(1);
+      expect(downTracker.calls).toHaveLength(1);
+      expect(moveTracker.calls).toHaveLength(5); // 5 steps
+      expect(upTracker.calls).toHaveLength(1);
 
       // Check intermediate positions
-      const lastMove = moveHandler.mock.calls[4][0] as PointerEvent;
+      const lastMove = moveTracker.calls[4] as PointerEvent;
       expect(lastMove.clientX).toBe(200);
       expect(lastMove.clientY).toBe(100);
 
-      document.removeEventListener("pointerdown", downHandler);
-      document.removeEventListener("pointermove", moveHandler);
-      document.removeEventListener("pointerup", upHandler);
+      document.removeEventListener("pointerdown", downTracker.handler);
+      document.removeEventListener("pointermove", moveTracker.handler);
+      document.removeEventListener("pointerup", upTracker.handler);
     });
   });
 
   describe("edgeSwipe", () => {
     it("simulates left edge swipe", () => {
       const simulator = createGestureSimulator();
-      const downHandler = vi.fn();
-      const upHandler = vi.fn();
+      const downTracker = createEventTracker();
+      const upTracker = createEventTracker();
 
-      document.addEventListener("pointerdown", downHandler);
-      document.addEventListener("pointerup", upHandler);
+      document.addEventListener("pointerdown", downTracker.handler);
+      document.addEventListener("pointerup", upTracker.handler);
 
       simulator.edgeSwipe("left", 100, 300);
 
-      expect(downHandler).toHaveBeenCalledTimes(1);
-      const downEvent = downHandler.mock.calls[0][0] as PointerEvent;
+      expect(downTracker.calls).toHaveLength(1);
+      const downEvent = downTracker.calls[0] as PointerEvent;
       expect(downEvent.clientX).toBe(10); // Edge offset
-      expect(upHandler).toHaveBeenCalledTimes(1);
+      expect(upTracker.calls).toHaveLength(1);
 
-      document.removeEventListener("pointerdown", downHandler);
-      document.removeEventListener("pointerup", upHandler);
+      document.removeEventListener("pointerdown", downTracker.handler);
+      document.removeEventListener("pointerup", upTracker.handler);
     });
 
     it("simulates right edge swipe", () => {
       const simulator = createGestureSimulator();
-      const downHandler = vi.fn();
+      const downTracker = createEventTracker();
 
-      document.addEventListener("pointerdown", downHandler);
+      document.addEventListener("pointerdown", downTracker.handler);
 
       simulator.edgeSwipe("right", 100, 300);
 
-      const downEvent = downHandler.mock.calls[0][0] as PointerEvent;
+      const downEvent = downTracker.calls[0] as PointerEvent;
       expect(downEvent.clientX).toBe(290); // containerSize - edgeOffset
 
-      document.removeEventListener("pointerdown", downHandler);
+      document.removeEventListener("pointerdown", downTracker.handler);
     });
   });
 
@@ -172,28 +176,28 @@ describe("createGestureSimulator", () => {
   describe("options", () => {
     it("respects custom pointer type", () => {
       const simulator = createGestureSimulator({ pointerType: "mouse" });
-      const handler = vi.fn();
-      document.addEventListener("pointerdown", handler);
+      const tracker = createEventTracker();
+      document.addEventListener("pointerdown", tracker.handler);
 
       simulator.pointerDown(100, 100);
 
-      const event = handler.mock.calls[0][0] as PointerEvent;
+      const event = tracker.calls[0] as PointerEvent;
       expect(event.pointerType).toBe("mouse");
 
-      document.removeEventListener("pointerdown", handler);
+      document.removeEventListener("pointerdown", tracker.handler);
     });
 
     it("respects custom pointer ID", () => {
       const simulator = createGestureSimulator({ pointerId: 5 });
-      const handler = vi.fn();
-      document.addEventListener("pointerdown", handler);
+      const tracker = createEventTracker();
+      document.addEventListener("pointerdown", tracker.handler);
 
       simulator.pointerDown(100, 100);
 
-      const event = handler.mock.calls[0][0] as PointerEvent;
+      const event = tracker.calls[0] as PointerEvent;
       expect(event.pointerId).toBe(5);
 
-      document.removeEventListener("pointerdown", handler);
+      document.removeEventListener("pointerdown", tracker.handler);
     });
   });
 });

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

@@ -4,8 +4,84 @@
  * 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,
+    // eslint-disable-next-line custom/no-as-outside-guard -- Required for React types compatibility
+    view: window as unknown as React.AbstractView,
+  };
+}
+
 /**
  * 2D point for gesture coordinates.
  */
@@ -107,10 +183,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 +205,7 @@ export function createGestureSimulator(options: GestureSimulatorOptions = {}): G
   };
 
   const pointerMove = (x: number, y: number): void => {
-    if (!isDown) {
+    if (!pointerState.isDown) {
       return;
     }
 
@@ -149,11 +225,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 +264,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 +304,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);
     });
   });