react-panel-layout 0.5.2 → 0.6.1

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

@@ -0,0 +1,385 @@
+/**
+ * @file Test utility for simulating gesture events.
+ *
+ * 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.
+ */
+export type Point = {
+  x: number;
+  y: number;
+};
+
+/**
+ * Options for creating a gesture simulator.
+ */
+export type GestureSimulatorOptions = {
+  /** Container element or ref for coordinate calculations */
+  container?: HTMLElement | null;
+  /** Default pointer type. @default "touch" */
+  pointerType?: "touch" | "mouse" | "pen";
+  /** Default pointer ID. @default 1 */
+  pointerId?: number;
+};
+
+/**
+ * Gesture simulator for testing swipe and drag interactions.
+ */
+export type GestureSimulator = {
+  /**
+   * Simulate pointer down event.
+   * @param x - X coordinate
+   * @param y - Y coordinate
+   */
+  pointerDown: (x: number, y: number) => void;
+
+  /**
+   * Simulate pointer move event.
+   * @param x - X coordinate
+   * @param y - Y coordinate
+   */
+  pointerMove: (x: number, y: number) => void;
+
+  /**
+   * Simulate pointer up event.
+   */
+  pointerUp: () => void;
+
+  /**
+   * Simulate a complete swipe gesture.
+   * @param from - Starting point
+   * @param to - Ending point
+   * @param steps - Number of intermediate move events. @default 10
+   */
+  swipe: (from: Point, to: Point, steps?: number) => void;
+
+  /**
+   * Simulate an edge swipe gesture.
+   * @param edge - Edge to swipe from ("left" | "right" | "top" | "bottom")
+   * @param distance - Distance to swipe in pixels
+   * @param containerSize - Size of the container (width for left/right, height for top/bottom). @default 300
+   */
+  edgeSwipe: (
+    edge: "left" | "right" | "top" | "bottom",
+    distance: number,
+    containerSize?: number,
+  ) => void;
+
+  /**
+   * Create a React pointer event object for use with component handlers.
+   * @param type - Event type (pointerdown, pointermove, pointerup)
+   * @param x - X coordinate
+   * @param y - Y coordinate
+   */
+  createReactPointerEvent: (
+    type: "pointerdown" | "pointermove" | "pointerup",
+    x: number,
+    y: number,
+  ) => React.PointerEvent;
+};
+
+/**
+ * Creates a gesture simulator for testing.
+ *
+ * @example
+ * ```tsx
+ * const simulator = createGestureSimulator();
+ *
+ * // Simple pointer events
+ * simulator.pointerDown(100, 100);
+ * simulator.pointerMove(150, 100);
+ * simulator.pointerUp();
+ *
+ * // Complete swipe
+ * simulator.swipe({ x: 100, y: 100 }, { x: 200, y: 100 });
+ *
+ * // Edge swipe (iOS-style back gesture)
+ * simulator.edgeSwipe("left", 100);
+ * ```
+ */
+export function createGestureSimulator(options: GestureSimulatorOptions = {}): GestureSimulator {
+  const {
+    pointerType = "touch",
+    pointerId = 1,
+  } = options;
+
+  const pointerState = { isDown: false };
+
+  const pointerDown = (x: number, y: number): void => {
+    pointerState.isDown = true;
+
+    const event = new PointerEvent("pointerdown", {
+      clientX: x,
+      clientY: y,
+      pointerId,
+      pointerType,
+      isPrimary: true,
+      bubbles: true,
+      cancelable: true,
+      button: 0,
+    });
+
+    act(() => {
+      document.dispatchEvent(event);
+    });
+  };
+
+  const pointerMove = (x: number, y: number): void => {
+    if (!pointerState.isDown) {
+      return;
+    }
+
+    const event = new PointerEvent("pointermove", {
+      clientX: x,
+      clientY: y,
+      pointerId,
+      pointerType,
+      isPrimary: true,
+      bubbles: true,
+      cancelable: true,
+    });
+
+    act(() => {
+      document.dispatchEvent(event);
+    });
+  };
+
+  const pointerUp = (): void => {
+    if (!pointerState.isDown) {
+      return;
+    }
+
+    pointerState.isDown = false;
+
+    const event = new PointerEvent("pointerup", {
+      pointerId,
+      pointerType,
+      isPrimary: true,
+      bubbles: true,
+      cancelable: true,
+    });
+
+    act(() => {
+      document.dispatchEvent(event);
+    });
+  };
+
+  const swipe = (from: Point, to: Point, steps = 10): void => {
+    pointerDown(from.x, from.y);
+
+    // Generate intermediate points
+    for (let i = 1; i <= steps; i++) {
+      const progress = i / steps;
+      const x = from.x + (to.x - from.x) * progress;
+      const y = from.y + (to.y - from.y) * progress;
+      pointerMove(x, y);
+    }
+
+    pointerUp();
+  };
+
+  const edgeSwipe = (
+    edge: "left" | "right" | "top" | "bottom",
+    distance: number,
+    containerSize = 300,
+  ): void => {
+    const edgeOffset = 10; // Start 10px from edge
+    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);
+  };
+
+  const createReactPointerEvent = (
+    type: "pointerdown" | "pointermove" | "pointerup",
+    x: number,
+    y: number,
+  ): React.PointerEvent => {
+    return createFullPointerEvent(type, x, y, pointerId, pointerType);
+  };
+
+  return {
+    pointerDown,
+    pointerMove,
+    pointerUp,
+    swipe,
+    edgeSwipe,
+    createReactPointerEvent,
+  };
+}
+
+/**
+ * Creates a mock container element with specified dimensions.
+ *
+ * @example
+ * ```tsx
+ * const container = createMockContainer({ width: 300, height: 500 });
+ * const ref = { current: container };
+ * ```
+ */
+export function createMockContainer(options: {
+  width?: number;
+  height?: number;
+  left?: number;
+  top?: number;
+} = {}): HTMLDivElement {
+  const {
+    width = 300,
+    height = 500,
+    left = 0,
+    top = 0,
+  } = options;
+
+  const element = document.createElement("div");
+
+  const rect: DOMRect = {
+    left,
+    right: left + width,
+    top,
+    bottom: top + height,
+    width,
+    height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  };
+
+  Object.defineProperties(element, {
+    clientWidth: { value: width, writable: true },
+    clientHeight: { value: height, writable: true },
+    scrollWidth: { value: width, writable: true },
+    scrollHeight: { value: height, writable: true },
+    scrollLeft: { value: 0, writable: true },
+    scrollTop: { value: 0, writable: true },
+  });
+
+  element.getBoundingClientRect = () => rect;
+
+  return element;
+}
+
+/**
+ * Creates a ref object with a mock container element.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = createMockContainerRef({ width: 300, height: 500 });
+ * const { result } = renderHook(() => useSwipeInput({ containerRef, axis: "horizontal" }));
+ * ```
+ */
+export function createMockContainerRef(options: {
+  width?: number;
+  height?: number;
+  left?: number;
+  top?: number;
+} = {}): React.RefObject<HTMLDivElement> {
+  return { current: createMockContainer(options) };
+}

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

@@ -0,0 +1,103 @@
+/**
+ * @file Tests for ThresholdValue type and parsing utilities.
+ *
+ * ThresholdValue allows specifying thresholds in multiple formats:
+ * - Object: { value: 50, unit: "px" } or { value: 0.25, unit: "ratio" }
+ * - String shorthand: "50px" or "25%"
+ */
+import {
+  parseThresholdValue,
+  resolveThreshold,
+  type ThresholdValue,
+} from "./thresholdValue.js";
+
+describe("parseThresholdValue", () => {
+  describe("object format", () => {
+    it("passes through px object unchanged", () => {
+      const input: ThresholdValue = { value: 50, unit: "px" };
+      expect(parseThresholdValue(input)).toEqual({ value: 50, unit: "px" });
+    });
+
+    it("passes through ratio object unchanged", () => {
+      const input: ThresholdValue = { value: 0.25, unit: "ratio" };
+      expect(parseThresholdValue(input)).toEqual({ value: 0.25, unit: "ratio" });
+    });
+  });
+
+  describe("string format - px", () => {
+    it("parses '50px' to px object", () => {
+      expect(parseThresholdValue("50px")).toEqual({ value: 50, unit: "px" });
+    });
+
+    it("parses '100px' to px object", () => {
+      expect(parseThresholdValue("100px")).toEqual({ value: 100, unit: "px" });
+    });
+
+    it("parses decimal '50.5px' to px object", () => {
+      expect(parseThresholdValue("50.5px")).toEqual({ value: 50.5, unit: "px" });
+    });
+
+    it("handles whitespace '50 px'", () => {
+      expect(parseThresholdValue("50 px")).toEqual({ value: 50, unit: "px" });
+    });
+  });
+
+  describe("string format - percentage/ratio", () => {
+    it("parses '25%' to ratio object (0.25)", () => {
+      expect(parseThresholdValue("25%")).toEqual({ value: 0.25, unit: "ratio" });
+    });
+
+    it("parses '33%' to ratio object (0.33)", () => {
+      expect(parseThresholdValue("33%")).toEqual({ value: 0.33, unit: "ratio" });
+    });
+
+    it("parses '50%' to ratio object (0.5)", () => {
+      expect(parseThresholdValue("50%")).toEqual({ value: 0.5, unit: "ratio" });
+    });
+
+    it("parses decimal '33.33%' to ratio object", () => {
+      expect(parseThresholdValue("33.33%")).toEqual({ value: 0.3333, unit: "ratio" });
+    });
+  });
+
+  describe("invalid input", () => {
+    it("throws on invalid string format", () => {
+      expect(() => parseThresholdValue("invalid")).toThrow();
+    });
+
+    it("throws on empty string", () => {
+      expect(() => parseThresholdValue("")).toThrow();
+    });
+
+    it("throws on number-only string", () => {
+      expect(() => parseThresholdValue("50")).toThrow();
+    });
+  });
+});
+
+describe("resolveThreshold", () => {
+  describe("px values", () => {
+    it("returns px value directly regardless of containerSize", () => {
+      const threshold: ThresholdValue = { value: 100, unit: "px" };
+      expect(resolveThreshold(threshold, 400)).toBe(100);
+      expect(resolveThreshold(threshold, 300)).toBe(100);
+    });
+
+    it("resolves string px format", () => {
+      expect(resolveThreshold("100px", 400)).toBe(100);
+    });
+  });
+
+  describe("ratio values", () => {
+    it("calculates px from ratio and containerSize", () => {
+      const threshold: ThresholdValue = { value: 0.25, unit: "ratio" };
+      expect(resolveThreshold(threshold, 400)).toBe(100); // 400 * 0.25
+      expect(resolveThreshold(threshold, 300)).toBe(75);  // 300 * 0.25
+    });
+
+    it("resolves string percentage format", () => {
+      expect(resolveThreshold("25%", 400)).toBe(100);
+      expect(resolveThreshold("50%", 400)).toBe(200);
+    });
+  });
+});

package/src/hooks/gesture/thresholdValue.ts

@@ -0,0 +1,77 @@
+/**
+ * @file ThresholdValue type and parsing utilities.
+ *
+ * Provides a flexible way to specify threshold values in either:
+ * - Absolute pixels: { value: 50, unit: "px" } or "50px"
+ * - Ratio of container: { value: 0.25, unit: "ratio" } or "25%"
+ */
+
+/**
+ * Parsed threshold value with explicit unit.
+ */
+export type ParsedThresholdValue = {
+  value: number;
+  unit: "px" | "ratio";
+};
+
+/**
+ * Threshold value input format.
+ * Accepts either an object with explicit unit or a string shorthand.
+ *
+ * @example
+ * // Object format
+ * { value: 50, unit: "px" }
+ * { value: 0.25, unit: "ratio" }
+ *
+ * // String shorthand
+ * "50px"   // 50 pixels
+ * "25%"    // 25% of container (ratio 0.25)
+ */
+export type ThresholdValue = ParsedThresholdValue | string;
+
+/**
+ * Parse a ThresholdValue input into a normalized ParsedThresholdValue.
+ *
+ * @param input - The threshold value to parse
+ * @returns Normalized threshold value object
+ * @throws Error if string format is invalid
+ */
+export function parseThresholdValue(input: ThresholdValue): ParsedThresholdValue {
+  if (typeof input === "object") {
+    return input;
+  }
+
+  const trimmed = input.trim();
+
+  // Match "50px" or "50 px"
+  const pxMatch = trimmed.match(/^([\d.]+)\s*px$/i);
+  if (pxMatch) {
+    return { value: parseFloat(pxMatch[1]), unit: "px" };
+  }
+
+  // Match "25%" or "25 %"
+  const percentMatch = trimmed.match(/^([\d.]+)\s*%$/);
+  if (percentMatch) {
+    const percentage = parseFloat(percentMatch[1]);
+    return { value: percentage / 100, unit: "ratio" };
+  }
+
+  throw new Error(`Invalid threshold format: "${input}". Expected "50px" or "25%"`);
+}
+
+/**
+ * Resolve a threshold value to pixels given a container size.
+ *
+ * @param input - The threshold value (object or string)
+ * @param containerSize - The container size in pixels for ratio calculation
+ * @returns The threshold in pixels
+ */
+export function resolveThreshold(input: ThresholdValue, containerSize: number): number {
+  const parsed = parseThresholdValue(input);
+
+  if (parsed.unit === "px") {
+    return parsed.value;
+  }
+
+  return parsed.value * containerSize;
+}