react-panel-layout 0.5.2 → 0.6.0

package/src/modules/stack/computeStackContentState.ts

@@ -0,0 +1,304 @@
+/**
+ * @file Pure functions for computing StackContent state.
+ *
+ * Separates state computation logic from React/CSS concerns for testability.
+ * All functions are pure and deterministic.
+ */
+import {
+  STACK_ANIMATION_PUSH,
+  STACK_ANIMATION_POP,
+  STACK_TRANSITION_DURATION,
+  STACK_TRANSITION_EASING,
+} from "../../constants/styles.js";
+
+/**
+ * Animation type for stack panel transitions.
+ */
+export type StackAnimationType = "push" | "pop" | null;
+
+/**
+ * Display mode for stack panels.
+ */
+export type StackDisplayMode = "overlay" | "slide" | "stack";
+
+/**
+ * Transition mode for animations.
+ */
+export type StackTransitionMode = "css" | "none";
+
+/**
+ * Input for computing animation type.
+ */
+export type ComputeAnimationTypeInput = {
+  wasActive: boolean;
+  isActive: boolean;
+  transitionMode: StackTransitionMode;
+};
+
+/**
+ * Compute the animation type based on active state change.
+ *
+ * @returns The animation type to apply, or null if no animation needed.
+ */
+export function computeAnimationType(input: ComputeAnimationTypeInput): StackAnimationType {
+  const { wasActive, isActive, transitionMode } = input;
+
+  if (transitionMode !== "css") {
+    return null;
+  }
+
+  if (wasActive === isActive) {
+    return null;
+  }
+
+  return isActive ? "push" : "pop";
+}
+
+/**
+ * Input for computing visibility.
+ */
+export type ComputeVisibilityInput = {
+  displayMode: StackDisplayMode;
+  depth: number;
+  navigationDepth: number;
+  isActive: boolean;
+  isAnimatingOut: boolean;
+  isRevealing: boolean;
+  revealDepth: number | null;
+};
+
+/**
+ * Compute panel visibility based on display mode and state.
+ *
+ * @returns "visible" or "hidden"
+ */
+export function computeVisibility(input: ComputeVisibilityInput): "visible" | "hidden" {
+  const {
+    displayMode,
+    depth,
+    navigationDepth,
+    isActive,
+    isAnimatingOut,
+    isRevealing,
+    revealDepth,
+  } = input;
+
+  if (displayMode === "overlay") {
+    // In overlay mode, only show active, animating out, or revealing panel
+    if (isActive) {
+      return "visible";
+    }
+    if (isAnimatingOut) {
+      return "visible";
+    }
+    if (isRevealing && depth === revealDepth) {
+      return "visible";
+    }
+    return "hidden";
+  }
+
+  // In slide/stack mode, show all panels in stack or animating out
+  if (depth <= navigationDepth) {
+    return "visible";
+  }
+  if (isAnimatingOut) {
+    return "visible";
+  }
+  return "hidden";
+}
+
+/**
+ * Input for computing transform.
+ */
+export type ComputeTransformInput = {
+  depth: number;
+  activeDepth: number;
+  displayMode: StackDisplayMode;
+  isRevealing: boolean;
+  revealDepth: number | null;
+};
+
+/**
+ * Compute the transform value for a stack panel.
+ *
+ * @returns CSS transform string
+ */
+export function computeTransform(input: ComputeTransformInput): string {
+  const { depth, activeDepth, displayMode, isRevealing, revealDepth } = input;
+
+  const isActive = depth === activeDepth;
+  const isPrevious = depth < activeDepth;
+
+  // During reveal, shift active panel to show parent
+  if (isRevealing && isActive) {
+    if (revealDepth !== null) {
+      const revealProgress = 0.3;
+      return `translateX(${revealProgress * 100}%)`;
+    }
+  }
+
+  if (isActive) {
+    return "translateX(0)";
+  }
+
+  if (isPrevious) {
+    switch (displayMode) {
+      case "overlay":
+        return "translateX(0)";
+      case "slide":
+        return "translateX(-30%)";
+      case "stack": {
+        const offset = (activeDepth - depth) * -5;
+        const scale = 1 - (activeDepth - depth) * 0.05;
+        return `translateX(${offset}%) scale(${scale})`;
+      }
+    }
+  }
+
+  // Future panels stay off-screen
+  return "translateX(100%)";
+}
+
+/**
+ * Compute the transform value considering swipe progress.
+ */
+function computeSwipeTransform(
+  baseTransform: string,
+  swipeProgress: number | undefined,
+  isActive: boolean,
+): string {
+  if (swipeProgress === undefined) {
+    return baseTransform;
+  }
+  if (swipeProgress <= 0) {
+    return baseTransform;
+  }
+  if (!isActive) {
+    return baseTransform;
+  }
+  return `translateX(${swipeProgress * 100}%)`;
+}
+
+/**
+ * Compute the transition CSS value.
+ */
+function computeTransitionCss(transitionMode: StackTransitionMode): string | undefined {
+  if (transitionMode !== "css") {
+    return undefined;
+  }
+  return `transform ${STACK_TRANSITION_DURATION} ${STACK_TRANSITION_EASING}`;
+}
+
+/**
+ * Full input for computing stack content state.
+ */
+export type StackContentStateInput = {
+  depth: number;
+  isActive: boolean;
+  wasActive: boolean;
+  currentAnimationType: StackAnimationType;
+  displayMode: StackDisplayMode;
+  transitionMode: StackTransitionMode;
+  navigationState: {
+    depth: number;
+    isRevealing: boolean;
+    revealDepth: number | null;
+  };
+  swipeProgress: number | undefined;
+};
+
+/**
+ * Computed state output for stack content.
+ */
+export type StackContentStateOutput = {
+  nextAnimationType: StackAnimationType;
+  visibility: "visible" | "hidden";
+  transform: string;
+  animation: string | undefined;
+  transition: string | undefined;
+  zIndex: number;
+  pointerEvents: "auto" | "none";
+};
+
+/**
+ * Compute the complete state for a stack content panel.
+ *
+ * This is the main entry point that combines all state computation.
+ * Pure function with no side effects.
+ *
+ * @param input - All inputs needed to compute state
+ * @returns Computed state for rendering
+ */
+export function computeStackContentState(input: StackContentStateInput): StackContentStateOutput {
+  const {
+    depth,
+    isActive,
+    wasActive,
+    currentAnimationType,
+    displayMode,
+    transitionMode,
+    navigationState,
+    swipeProgress,
+  } = input;
+
+  // 1. Compute animation type
+  const stateChangeAnimationType = computeAnimationType({
+    wasActive,
+    isActive,
+    transitionMode,
+  });
+
+  // Use new animation type if state changed, otherwise preserve current
+  const nextAnimationType = stateChangeAnimationType ?? currentAnimationType;
+
+  // 2. Compute visibility
+  const isAnimatingOut = nextAnimationType === "pop";
+  const visibility = computeVisibility({
+    displayMode,
+    depth,
+    navigationDepth: navigationState.depth,
+    isActive,
+    isAnimatingOut,
+    isRevealing: navigationState.isRevealing,
+    revealDepth: navigationState.revealDepth,
+  });
+
+  // 3. Compute transform
+  const baseTransform = computeTransform({
+    depth,
+    activeDepth: navigationState.depth,
+    displayMode,
+    isRevealing: navigationState.isRevealing,
+    revealDepth: navigationState.revealDepth,
+  });
+
+  // Apply swipe progress transform if swiping on active panel
+  const transform = computeSwipeTransform(baseTransform, swipeProgress, isActive);
+
+  // 4. Compute animation CSS
+  const animation = (() => {
+    if (transitionMode !== "css") {
+      return undefined;
+    }
+    if (nextAnimationType === "push") {
+      return STACK_ANIMATION_PUSH;
+    }
+    if (nextAnimationType === "pop") {
+      return STACK_ANIMATION_POP;
+    }
+    return undefined;
+  })();
+
+  // 5. Compute transition CSS
+  const transition = computeTransitionCss(transitionMode);
+
+  return {
+    nextAnimationType,
+    visibility,
+    transform,
+    animation,
+    transition,
+    zIndex: depth,
+    pointerEvents: isActive ? "auto" : "none",
+  };
+}

package/src/modules/stack/computeSwipeStackTransform.spec.ts

@@ -0,0 +1,186 @@
+/**
+ * @file Tests for computeSwipeStackTransform pure functions.
+ */
+import {
+  computeActiveTargetPx,
+  computeBehindTargetPx,
+  computeSwipeProgress,
+  computeSwipeVisibility,
+  determineSwipePanelRole,
+  DEFAULT_BEHIND_OFFSET,
+} from "./computeSwipeStackTransform.js";
+
+describe("computeActiveTargetPx", () => {
+  it("returns 0 for no displacement", () => {
+    expect(computeActiveTargetPx(0)).toBe(0);
+  });
+
+  it("returns positive displacement directly", () => {
+    expect(computeActiveTargetPx(100)).toBe(100);
+    expect(computeActiveTargetPx(250)).toBe(250);
+  });
+
+  it("clamps negative displacement to 0", () => {
+    expect(computeActiveTargetPx(-50)).toBe(0);
+    expect(computeActiveTargetPx(-100)).toBe(0);
+  });
+});
+
+describe("computeBehindTargetPx", () => {
+  const containerSize = 400;
+
+  it("returns base offset position with no displacement", () => {
+    const result = computeBehindTargetPx(0, containerSize);
+    // Default offset is -0.3, so -0.3 * 400 = -120
+    expect(result).toBe(-120);
+  });
+
+  it("moves towards 0 as displacement increases", () => {
+    // At 50% progress (200px displacement)
+    const halfProgress = computeBehindTargetPx(200, containerSize);
+    // Should be at -60 (halfway from -120 to 0)
+    expect(halfProgress).toBe(-60);
+
+    // At 100% progress (400px displacement)
+    const fullProgress = computeBehindTargetPx(400, containerSize);
+    // Should be at 0
+    expect(fullProgress).toBe(0);
+  });
+
+  it("clamps at 0 for large displacement", () => {
+    const result = computeBehindTargetPx(800, containerSize);
+    expect(result).toBe(0);
+  });
+
+  it("handles negative displacement", () => {
+    const result = computeBehindTargetPx(-50, containerSize);
+    // Negative displacement is treated as 0
+    expect(result).toBe(-120);
+  });
+
+  it("handles zero container size", () => {
+    expect(computeBehindTargetPx(100, 0)).toBe(0);
+  });
+
+  it("uses custom behind offset", () => {
+    const customOffset = -0.5; // -50%
+    const result = computeBehindTargetPx(0, containerSize, customOffset);
+    expect(result).toBe(-200); // -0.5 * 400
+
+    // At full progress
+    const fullProgress = computeBehindTargetPx(400, containerSize, customOffset);
+    expect(fullProgress).toBe(0);
+  });
+});
+
+describe("computeSwipeProgress", () => {
+  const containerSize = 400;
+
+  it("returns 0 for no displacement", () => {
+    expect(computeSwipeProgress(0, containerSize)).toBe(0);
+  });
+
+  it("returns correct progress for partial swipe", () => {
+    expect(computeSwipeProgress(100, containerSize)).toBe(0.25);
+    expect(computeSwipeProgress(200, containerSize)).toBe(0.5);
+  });
+
+  it("clamps at 1 for full swipe", () => {
+    expect(computeSwipeProgress(400, containerSize)).toBe(1);
+    expect(computeSwipeProgress(600, containerSize)).toBe(1);
+  });
+
+  it("handles negative displacement as 0", () => {
+    expect(computeSwipeProgress(-50, containerSize)).toBe(0);
+  });
+
+  it("handles zero container size", () => {
+    expect(computeSwipeProgress(100, 0)).toBe(0);
+  });
+});
+
+describe("computeSwipeVisibility", () => {
+  it("active panel is always visible", () => {
+    expect(
+      computeSwipeVisibility({
+        depth: 2,
+        navigationDepth: 2,
+        isActive: true,
+        isSwiping: false,
+        isAnimating: false,
+      }),
+    ).toBe(true);
+  });
+
+  it("behind panel is visible when swiping", () => {
+    expect(
+      computeSwipeVisibility({
+        depth: 1,
+        navigationDepth: 2,
+        isActive: false,
+        isSwiping: true,
+        isAnimating: false,
+      }),
+    ).toBe(true);
+  });
+
+  it("behind panel is visible when animating", () => {
+    expect(
+      computeSwipeVisibility({
+        depth: 1,
+        navigationDepth: 2,
+        isActive: false,
+        isSwiping: false,
+        isAnimating: true,
+      }),
+    ).toBe(true);
+  });
+
+  it("behind panel is hidden when idle", () => {
+    expect(
+      computeSwipeVisibility({
+        depth: 1,
+        navigationDepth: 2,
+        isActive: false,
+        isSwiping: false,
+        isAnimating: false,
+      }),
+    ).toBe(false);
+  });
+
+  it("deeper panels are hidden during swipe", () => {
+    expect(
+      computeSwipeVisibility({
+        depth: 0,
+        navigationDepth: 2,
+        isActive: false,
+        isSwiping: true,
+        isAnimating: false,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("determineSwipePanelRole", () => {
+  it("returns active for current depth", () => {
+    expect(determineSwipePanelRole(2, 2)).toBe("active");
+  });
+
+  it("returns behind for previous depth", () => {
+    expect(determineSwipePanelRole(1, 2)).toBe("behind");
+  });
+
+  it("returns hidden for deeper levels", () => {
+    expect(determineSwipePanelRole(0, 2)).toBe("hidden");
+  });
+
+  it("returns hidden for future levels", () => {
+    expect(determineSwipePanelRole(3, 2)).toBe("hidden");
+  });
+});
+
+describe("DEFAULT_BEHIND_OFFSET", () => {
+  it("is -0.3 (30% offset)", () => {
+    expect(DEFAULT_BEHIND_OFFSET).toBe(-0.3);
+  });
+});

package/src/modules/stack/computeSwipeStackTransform.ts

@@ -0,0 +1,145 @@
+/**
+ * @file Pure functions for computing Stack panel transforms during swipe.
+ *
+ * These functions calculate positions for iOS-style "swipe to go back" behavior
+ * where the active panel follows the finger and the behind panel reveals from -30%.
+ */
+
+/**
+ * Default offset for behind panel (-30% of container width).
+ */
+export const DEFAULT_BEHIND_OFFSET = -0.3;
+
+/**
+ * Compute the target position for the active panel.
+ *
+ * Active panel starts at 0 and moves right as the user swipes.
+ *
+ * @param displacement - Current swipe displacement in pixels
+ * @returns Target position in pixels
+ */
+export function computeActiveTargetPx(displacement: number): number {
+  // Active panel follows the finger directly
+  // Only move right (positive displacement) for left-edge swipe
+  return Math.max(0, displacement);
+}
+
+/**
+ * Compute the target position for the behind panel.
+ *
+ * Behind panel starts at -30% and moves to 0% as swipe progresses.
+ * Uses parallax effect: moves slower than the active panel.
+ *
+ * @param displacement - Current swipe displacement in pixels
+ * @param containerSize - Container width/height in pixels
+ * @param behindOffset - Starting offset ratio (default -0.3 for -30%)
+ * @returns Target position in pixels
+ */
+export function computeBehindTargetPx(
+  displacement: number,
+  containerSize: number,
+  behindOffset: number = DEFAULT_BEHIND_OFFSET,
+): number {
+  if (containerSize <= 0) {
+    return 0;
+  }
+
+  // Only respond to positive displacement (swipe right)
+  const clampedDisplacement = Math.max(0, displacement);
+
+  // Calculate progress (0 to 1)
+  const progress = Math.min(clampedDisplacement / containerSize, 1);
+
+  // Behind panel starts at behindOffset * containerSize and moves to 0
+  // Parallax: moves |behindOffset| * progress * containerSize
+  const basePosition = behindOffset * containerSize;
+  const parallaxOffset = Math.abs(behindOffset) * progress * containerSize;
+
+  return basePosition + parallaxOffset;
+}
+
+/**
+ * Compute swipe progress as a ratio (0 to 1).
+ *
+ * @param displacement - Current swipe displacement in pixels
+ * @param containerSize - Container width/height in pixels
+ * @returns Progress ratio from 0 to 1
+ */
+export function computeSwipeProgress(displacement: number, containerSize: number): number {
+  if (containerSize <= 0) {
+    return 0;
+  }
+
+  const clampedDisplacement = Math.max(0, displacement);
+  return Math.min(clampedDisplacement / containerSize, 1);
+}
+
+/**
+ * Input for computing swipe visibility.
+ */
+export type ComputeSwipeVisibilityInput = {
+  /** Panel depth in the stack */
+  depth: number;
+  /** Current navigation depth (active panel) */
+  navigationDepth: number;
+  /** Whether this panel is currently active */
+  isActive: boolean;
+  /** Whether swipe gesture is active */
+  isSwiping: boolean;
+  /** Whether snap-back animation is running */
+  isAnimating: boolean;
+};
+
+/**
+ * Compute whether a panel should be visible during swipe.
+ *
+ * During swipe:
+ * - Active panel is always visible
+ * - Behind panel (depth = navigationDepth - 1) is visible when swiping/animating
+ *
+ * @returns true if panel should be visible
+ */
+export function computeSwipeVisibility(input: ComputeSwipeVisibilityInput): boolean {
+  const { depth, navigationDepth, isActive, isSwiping, isAnimating } = input;
+
+  // Active panel is always visible
+  if (isActive) {
+    return true;
+  }
+
+  // Behind panel (one level back) is visible during swipe or animation
+  const isBehindPanel = depth === navigationDepth - 1;
+  if (isBehindPanel) {
+    if (isSwiping) {
+      return true;
+    }
+    if (isAnimating) {
+      return true;
+    }
+  }
+
+  // Other panels are hidden during swipe
+  return false;
+}
+
+/**
+ * Determine the role of a panel during swipe gesture.
+ */
+export type SwipePanelRole = "active" | "behind" | "hidden";
+
+/**
+ * Determine the role of a panel during swipe.
+ *
+ * @param depth - Panel depth in the stack
+ * @param navigationDepth - Current navigation depth (active panel)
+ * @returns Panel role for swipe handling
+ */
+export function determineSwipePanelRole(depth: number, navigationDepth: number): SwipePanelRole {
+  if (depth === navigationDepth) {
+    return "active";
+  }
+  if (depth === navigationDepth - 1) {
+    return "behind";
+  }
+  return "hidden";
+}