react-panel-layout 0.5.1 → 0.6.0

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

@@ -0,0 +1,310 @@
+/**
+ * @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 { act } from "@testing-library/react";
+
+/**
+ * 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;
+
+  let isDown = false;
+
+  const pointerDown = (x: number, y: number): void => {
+    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 (!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 (!isDown) {
+      return;
+    }
+
+    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
+
+    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;
+    }
+
+    swipe(from, to);
+  };
+
+  const createReactPointerEvent = (
+    type: "pointerdown" | "pointermove" | "pointerup",
+    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 {
+    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;
+}