react-panel-layout 0.5.2 → 0.6.0

package/src/modules/pivot/scaleInputState.spec.ts

@@ -0,0 +1,210 @@
+/**
+ * @file Tests for scaleInputState utility
+ */
+import { describe, it, expect } from "vitest";
+import { scaleInputState } from "./scaleInputState";
+import type { SwipeInputState } from "../../hooks/gesture/types";
+
+describe("scaleInputState", () => {
+  const createSwipingState = (x: number, vx: number): SwipeInputState => ({
+    phase: "swiping",
+    displacement: { x, y: 0 },
+    velocity: { x: vx, y: 0 },
+    direction: x > 0 ? 1 : x < 0 ? -1 : 0,
+  });
+
+  describe("scaling factor calculation", () => {
+    it("scales displacement proportionally (source larger than target)", () => {
+      const inputState = createSwipingState(100, 0.5);
+      const result = scaleInputState(inputState, 400, 80);
+
+      // 80/400 = 0.2, so 100 * 0.2 = 20
+      expect(result.displacement.x).toBe(20);
+    });
+
+    it("scales displacement proportionally (source smaller than target)", () => {
+      const inputState = createSwipingState(20, 0.1);
+      const result = scaleInputState(inputState, 80, 400);
+
+      // 400/80 = 5, so 20 * 5 = 100
+      expect(result.displacement.x).toBe(100);
+    });
+
+    it("scales velocity proportionally", () => {
+      const inputState = createSwipingState(100, 1.0);
+      const result = scaleInputState(inputState, 400, 80);
+
+      // 80/400 = 0.2, so 1.0 * 0.2 = 0.2
+      expect(result.velocity.x).toBe(0.2);
+    });
+
+    it("scales both x and y components", () => {
+      const inputState: SwipeInputState = {
+        phase: "swiping",
+        displacement: { x: 100, y: 50 },
+        velocity: { x: 1.0, y: 0.5 },
+        direction: 1,
+      };
+      const result = scaleInputState(inputState, 400, 200);
+
+      // 200/400 = 0.5
+      expect(result.displacement.x).toBe(50);
+      expect(result.displacement.y).toBe(25);
+      expect(result.velocity.x).toBe(0.5);
+      expect(result.velocity.y).toBe(0.25);
+    });
+  });
+
+  describe("same-size containers", () => {
+    it("returns identical values when source and target are same size", () => {
+      const inputState = createSwipingState(100, 0.5);
+      const result = scaleInputState(inputState, 400, 400);
+
+      expect(result.displacement.x).toBe(100);
+      expect(result.velocity.x).toBe(0.5);
+    });
+  });
+
+  describe("idle state handling", () => {
+    it("returns unchanged state for idle phase", () => {
+      const inputState: SwipeInputState = {
+        phase: "idle",
+        displacement: { x: 0, y: 0 },
+        velocity: { x: 0, y: 0 },
+        direction: 0,
+      };
+      const result = scaleInputState(inputState, 400, 80);
+
+      expect(result).toBe(inputState); // Same reference
+    });
+  });
+
+  describe("invalid dimension handling", () => {
+    it("returns unchanged state when sourceWidth is 0", () => {
+      const inputState = createSwipingState(100, 0.5);
+      const result = scaleInputState(inputState, 0, 80);
+
+      expect(result).toBe(inputState);
+    });
+
+    it("returns unchanged state when targetWidth is 0", () => {
+      const inputState = createSwipingState(100, 0.5);
+      const result = scaleInputState(inputState, 400, 0);
+
+      expect(result).toBe(inputState);
+    });
+
+    it("returns unchanged state when sourceWidth is negative", () => {
+      const inputState = createSwipingState(100, 0.5);
+      const result = scaleInputState(inputState, -100, 80);
+
+      expect(result).toBe(inputState);
+    });
+
+    it("returns unchanged state when targetWidth is negative", () => {
+      const inputState = createSwipingState(100, 0.5);
+      const result = scaleInputState(inputState, 400, -80);
+
+      expect(result).toBe(inputState);
+    });
+  });
+
+  describe("phase preservation", () => {
+    it("preserves tracking phase", () => {
+      const inputState: SwipeInputState = {
+        phase: "tracking",
+        displacement: { x: 5, y: 0 },
+        velocity: { x: 0.1, y: 0 },
+        direction: 1,
+      };
+      const result = scaleInputState(inputState, 400, 80);
+
+      expect(result.phase).toBe("tracking");
+    });
+
+    it("preserves swiping phase", () => {
+      const inputState = createSwipingState(100, 0.5);
+      const result = scaleInputState(inputState, 400, 80);
+
+      expect(result.phase).toBe("swiping");
+    });
+
+    it("preserves ended phase", () => {
+      const inputState: SwipeInputState = {
+        phase: "ended",
+        displacement: { x: 150, y: 0 },
+        velocity: { x: 0.8, y: 0 },
+        direction: 1,
+      };
+      const result = scaleInputState(inputState, 400, 80);
+
+      expect(result.phase).toBe("ended");
+    });
+  });
+
+  describe("direction preservation", () => {
+    it("preserves positive direction", () => {
+      const inputState = createSwipingState(100, 0.5);
+      const result = scaleInputState(inputState, 400, 80);
+
+      expect(result.direction).toBe(1);
+    });
+
+    it("preserves negative direction", () => {
+      const inputState = createSwipingState(-100, -0.5);
+      const result = scaleInputState(inputState, 400, 80);
+
+      expect(result.direction).toBe(-1);
+    });
+
+    it("preserves zero direction", () => {
+      const inputState: SwipeInputState = {
+        phase: "swiping",
+        displacement: { x: 0, y: 50 },
+        velocity: { x: 0, y: 0.5 },
+        direction: 0,
+      };
+      const result = scaleInputState(inputState, 400, 80);
+
+      expect(result.direction).toBe(0);
+    });
+  });
+
+  describe("negative displacement scaling", () => {
+    it("correctly scales negative displacement", () => {
+      const inputState = createSwipingState(-100, -0.5);
+      const result = scaleInputState(inputState, 400, 80);
+
+      expect(result.displacement.x).toBe(-20);
+      expect(result.velocity.x).toBe(-0.1);
+    });
+  });
+
+  describe("real-world use cases", () => {
+    it("synchronizes 5-tab bar with content (content swipe → tabs)", () => {
+      // 5 tabs in a 400px content area, each tab is 80px
+      const contentWidth = 400;
+      const tabWidth = 80;
+
+      // User swipes 200px on content (half the content width)
+      const inputState = createSwipingState(200, 1.0);
+      const result = scaleInputState(inputState, contentWidth, tabWidth);
+
+      // Tabs should move 40px (half of tab width)
+      expect(result.displacement.x).toBe(40);
+    });
+
+    it("synchronizes 5-tab bar with content (tabs swipe → content)", () => {
+      // Inverse: if swipe started on tabs
+      const contentWidth = 400;
+      const tabWidth = 80;
+
+      // User swipes 40px on tabs (half the tab width)
+      const inputState = createSwipingState(40, 0.2);
+      const result = scaleInputState(inputState, tabWidth, contentWidth);
+
+      // Content should move 200px (half of content width)
+      expect(result.displacement.x).toBe(200);
+    });
+  });
+});

package/src/modules/pivot/scaleInputState.ts

@@ -0,0 +1,66 @@
+/**
+ * @file Utility for scaling SwipeInputState between containers of different sizes.
+ *
+ * This enables synchronized swipe behavior between containers with different widths,
+ * such as a narrow tab bar and a wide content area moving together proportionally.
+ */
+import type { SwipeInputState } from "../../hooks/gesture/types.js";
+
+/**
+ * Scale SwipeInputState displacement and velocity proportionally for different container sizes.
+ *
+ * When swiping in a container of one size, this function transforms the input state
+ * to appear as if the swipe occurred in a container of a different size.
+ * This allows tabs and content to move in sync despite different widths.
+ *
+ * @param inputState - The original swipe input state
+ * @param sourceWidth - Width of the source container (where the swipe originated)
+ * @param targetWidth - Width of the target container (where the scaled state will be applied)
+ * @returns Scaled SwipeInputState with proportionally adjusted displacement and velocity
+ *
+ * @example
+ * ```tsx
+ * // Content area is 400px wide, each tab is 80px wide (5 tabs)
+ * const contentWidth = 400;
+ * const tabWidth = 80;
+ *
+ * // Swipe happens on content area
+ * const { inputState } = usePivotSwipeInput({ containerRef, pivot, axis: "horizontal" });
+ *
+ * // Scale for tabs: 100px content swipe → 20px tab movement
+ * const tabInputState = scaleInputState(inputState, contentWidth, tabWidth);
+ *
+ * // Apply to tabs and content respectively
+ * <SwipePivotContent inputState={tabInputState} containerSize={tabWidth} />
+ * <SwipePivotContent inputState={inputState} containerSize={contentWidth} />
+ * ```
+ */
+export const scaleInputState = (
+  inputState: SwipeInputState,
+  sourceWidth: number,
+  targetWidth: number,
+): SwipeInputState => {
+  // Guard against invalid dimensions
+  if (sourceWidth <= 0 || targetWidth <= 0) {
+    return inputState;
+  }
+
+  // Idle state needs no scaling
+  if (inputState.phase === "idle") {
+    return inputState;
+  }
+
+  const scale = targetWidth / sourceWidth;
+
+  return {
+    ...inputState,
+    displacement: {
+      x: inputState.displacement.x * scale,
+      y: inputState.displacement.y * scale,
+    },
+    velocity: {
+      x: inputState.velocity.x * scale,
+      y: inputState.velocity.y * scale,
+    },
+  };
+};

package/src/modules/pivot/types.ts

@@ -0,0 +1,139 @@
+/**
+ * @file Type definitions for the Pivot headless component system.
+ * Pivot manages content switching within a scope without providing UI.
+ */
+import type * as React from "react";
+
+/**
+ * Navigation mode for pivot.
+ * - "linear": Default. Stops at first/last item.
+ * - "loop": Infinite loop. Navigation wraps around.
+ */
+export type PivotNavigationMode = "linear" | "loop";
+
+/**
+ * A single content item that can be displayed in a Pivot.
+ */
+export type PivotItem<TId extends string = string> = {
+  /** Unique identifier for this content item */
+  id: TId;
+  /** Human-readable label (optional - for tab titles, menu items, etc.) */
+  label?: string;
+  /** The actual content to render when this item is active */
+  content: React.ReactNode;
+  /** Whether this item can be selected (defaults to true) */
+  disabled?: boolean;
+  /**
+   * Enable content caching to preserve React component state across re-renders.
+   * When disabled (default), content is re-created on each render.
+   * @default false
+   */
+  cache?: boolean;
+};
+
+/**
+ * Props for the usePivot hook.
+ */
+export type UsePivotOptions<TId extends string = string> = {
+  /** Array of content items to manage */
+  items: ReadonlyArray<PivotItem<TId>>;
+  /** Currently active item ID (controlled mode) */
+  activeId?: TId;
+  /** Default active item ID (uncontrolled mode) */
+  defaultActiveId?: TId;
+  /** Callback when active item changes */
+  onActiveChange?: (id: TId) => void;
+  /**
+   * Transition mode for content switching.
+   * - "css" (default) uses CSS transitions with design tokens.
+   * - "none" disables transitions (uses React.Activity for memory optimization).
+   */
+  transitionMode?: "css" | "none";
+  /**
+   * Navigation mode for pivot.
+   * - "linear" (default): Stops at first/last item.
+   * - "loop": Navigation wraps around (last→first, first→last).
+   */
+  navigationMode?: PivotNavigationMode;
+};
+
+/**
+ * Props object returned by getItemProps for navigation elements.
+ */
+export type PivotItemProps = {
+  "data-pivot-item": string;
+  "data-active": "true" | "false";
+  "aria-selected": boolean;
+  tabIndex: number;
+  onClick: () => void;
+};
+
+/**
+ * Options for navigation methods (go, setActiveId).
+ */
+export type PivotNavigationOptions = {
+  /**
+   * Whether to animate the transition.
+   * - undefined: use transitionMode setting (default)
+   * - true: force animation
+   * - false: instant transition without animation
+   */
+  animated?: boolean;
+};
+
+/**
+ * Result from usePivot hook.
+ */
+export type UsePivotResult<TId extends string = string> = {
+  /** Current active item ID */
+  activeId: TId;
+  /**
+   * Function to change the active item.
+   * @param id - Target item ID
+   * @param options - Navigation options (animated, etc.)
+   */
+  setActiveId: (id: TId, options?: PivotNavigationOptions) => void;
+  /** Helper to check if an item is active */
+  isActive: (id: TId) => boolean;
+  /** Function to get props for navigation items (buttons, links, etc.) */
+  getItemProps: (id: TId) => PivotItemProps;
+  /** Outlet component that renders the active content (react-router style) */
+  Outlet: React.FC;
+  /**
+   * Navigate in a direction relative to the current item.
+   * @param direction - Number of items to move: -1=prev, 1=next, -2=skip2Back, etc.
+   * @param options - Navigation options (animated, etc.)
+   */
+  go: (direction: number, options?: PivotNavigationOptions) => void;
+  /**
+   * Check if navigation in a direction is possible.
+   * @param direction - Direction to check
+   * @returns true if navigation is possible
+   */
+  canGo: (direction: number) => boolean;
+  /** Current index of active item in the items array */
+  activeIndex: number;
+  /** Total number of enabled items */
+  itemCount: number;
+  /** Whether a transition animation is currently in progress */
+  isAnimating: boolean;
+  /** Call to signal that animation has completed */
+  endAnimation: () => void;
+  /** Current navigation mode */
+  navigationMode: PivotNavigationMode;
+  /**
+   * Get the virtual position for an item relative to active.
+   * In loop mode, this wraps: item at index 0 can have position 1 if active is last.
+   * @param id - Item ID to check
+   * @returns -1 (prev), 0 (active), 1 (next), or null if not adjacent
+   */
+  getVirtualPosition: (id: TId) => -1 | 0 | 1 | null;
+  /**
+   * Get the position for any item relative to active.
+   * Unlike getVirtualPosition, returns positions for all items (not just adjacent).
+   * In loop mode, returns the shortest path position (e.g., last→first is +1, not -(count-1)).
+   * @param id - Item ID to check
+   * @returns Position offset from active, or null if item not found
+   */
+  getItemPosition: (id: TId) => number | null;
+};