react-panel-layout 0.5.1 → 0.6.0

package/src/modules/stack/SwipeStackOutlet.tsx

@@ -0,0 +1,221 @@
+/**
+ * @file SwipeStackOutlet component for rendering stack with swipe support.
+ *
+ * Uses SwipeStackContent for direct DOM manipulation during swipe gestures,
+ * providing iOS-style smooth swipe-to-go-back behavior.
+ */
+import * as React from "react";
+import { SwipeStackContent } from "./SwipeStackContent.js";
+import type { SwipeInputState } from "../../hooks/gesture/types.js";
+import type { StackPanel, StackNavigationState } from "./types.js";
+
+const DEFAULT_ANIMATION_DURATION = 300;
+
+/**
+ * Props for SwipeStackOutlet component.
+ */
+export type SwipeStackOutletProps = {
+  /** Array of panel definitions */
+  panels: ReadonlyArray<StackPanel>;
+  /** Current navigation state */
+  navigationState: StackNavigationState;
+  /** Swipe input state from useStackSwipeInput */
+  inputState: SwipeInputState;
+  /** Container size in pixels (width for horizontal swipe) */
+  containerSize: number;
+  /** Function to get cached content for a panel */
+  getCachedContent?: (panelId: string) => React.ReactNode | null;
+  /** Behind panel offset ratio. @default -0.3 */
+  behindOffset?: number;
+  /**
+   * Whether to animate new panels on mount.
+   * @default false
+   */
+  animateOnMount?: boolean;
+  /**
+   * Animation duration in ms.
+   * @default 300
+   */
+  animationDuration?: number;
+  /**
+   * Whether to show iOS-style edge shadow on active panels.
+   * @default true
+   */
+  showShadow?: boolean;
+  /**
+   * Display mode for visual styling.
+   * - "overlay": panels overlay, no scale (iOS style)
+   * - "slide": panels slide with parallax
+   * - "stack": panels scale down and offset (stacked cards style)
+   * @default "overlay"
+   */
+  displayMode?: "overlay" | "slide" | "stack";
+  /**
+   * Whether to show dimming overlay on behind panels.
+   * @default true
+   */
+  showDimming?: boolean;
+};
+
+/**
+ * Get visible panels for rendering during swipe.
+ *
+ * Only renders active panel and immediate behind panel for performance.
+ * Also includes exiting panel when navigating back.
+ */
+function getVisiblePanels(
+  panels: ReadonlyArray<StackPanel>,
+  navigationState: StackNavigationState,
+  exitingPanelId: string | null,
+): Array<{ panel: StackPanel; depth: number; isExiting: boolean }> {
+  const { stack, depth } = navigationState;
+
+  // During swipe, we only need active and behind panels
+  const visibleDepths = [depth];
+  if (depth > 0) {
+    visibleDepths.push(depth - 1);
+  }
+
+  const result: Array<{ panel: StackPanel; depth: number; isExiting: boolean }> = [];
+
+  // Add panels at visible depths
+  for (const d of visibleDepths) {
+    const id = stack[d];
+    const panel = panels.find((p) => p.id === id);
+    if (panel) {
+      result.push({ panel, depth: d, isExiting: false });
+    }
+  }
+
+  // Add exiting panel if it's not already included
+  if (exitingPanelId != null) {
+    const alreadyIncluded = result.some((r) => r.panel.id === exitingPanelId);
+    if (!alreadyIncluded) {
+      const exitingPanel = panels.find((p) => p.id === exitingPanelId);
+      if (exitingPanel) {
+        // Exiting panel is at depth + 1 (was previously active)
+        result.push({ panel: exitingPanel, depth: depth + 1, isExiting: true });
+      }
+    }
+  }
+
+  // Render in order: behind first, then active, then exiting
+  return result.sort((a, b) => a.depth - b.depth);
+}
+
+/**
+ * SwipeStackOutlet renders stack panels with swipe gesture support.
+ *
+ * Unlike the default StackOutlet, this component:
+ * - Uses SwipeStackContent for direct DOM manipulation
+ * - Only renders active and behind panels for performance
+ * - Supports iOS-style parallax reveal animation
+ *
+ * @example
+ * ```tsx
+ * const navigation = useStackNavigation({ panels, displayMode: 'overlay' });
+ * const swipeInput = useStackSwipeInput({ containerRef, navigation });
+ *
+ * return (
+ *   <div ref={containerRef} {...swipeInput.containerProps}>
+ *     <SwipeStackOutlet
+ *       panels={navigation.panels}
+ *       navigationState={navigation.state}
+ *       inputState={swipeInput.inputState}
+ *       containerSize={containerWidth}
+ *     />
+ *   </div>
+ * );
+ * ```
+ */
+export const SwipeStackOutlet: React.FC<SwipeStackOutletProps> = React.memo(
+  ({
+    panels,
+    navigationState,
+    inputState,
+    containerSize,
+    getCachedContent,
+    behindOffset,
+    animateOnMount = false,
+    animationDuration = DEFAULT_ANIMATION_DURATION,
+    showShadow,
+    displayMode,
+    showDimming,
+  }) => {
+    // Track the exiting panel ID when navigating back
+    const [exitingPanelId, setExitingPanelId] = React.useState<string | null>(null);
+    const prevDepthRef = React.useRef(navigationState.depth);
+    const prevStackRef = React.useRef<ReadonlyArray<string>>(navigationState.stack);
+
+    // Detect when we navigate back and need to animate out
+    React.useLayoutEffect(() => {
+      const prevDepth = prevDepthRef.current;
+      const prevStack = prevStackRef.current;
+      const { depth, stack } = navigationState;
+
+      // Update refs
+      prevDepthRef.current = depth;
+      prevStackRef.current = stack;
+
+      // Check if we went back (depth decreased)
+      if (depth < prevDepth) {
+        // The panel at prevDepth is exiting
+        const exitingId = prevStack[prevDepth];
+        if (exitingId != null) {
+          setExitingPanelId(exitingId);
+
+          // Clear exiting panel after animation completes
+          const timeoutId = setTimeout(() => {
+            setExitingPanelId(null);
+          }, animationDuration);
+
+          return () => clearTimeout(timeoutId);
+        }
+      }
+    }, [navigationState.depth, navigationState.stack, animationDuration]);
+
+    const visiblePanels = React.useMemo(
+      () => getVisiblePanels(panels, navigationState, exitingPanelId),
+      [panels, navigationState, exitingPanelId],
+    );
+
+    const containerStyle: React.CSSProperties = React.useMemo(
+      () => ({
+        position: "relative",
+        width: "100%",
+        height: "100%",
+        overflow: "hidden",
+      }),
+      [],
+    );
+
+    return (
+      <div style={containerStyle} data-swipe-stack-container>
+        {visiblePanels.map(({ panel, depth, isExiting }) => {
+          const isActive = depth === navigationState.depth && !isExiting;
+          const content = getCachedContent?.(panel.id) ?? panel.content;
+
+          return (
+            <SwipeStackContent
+              key={panel.id}
+              id={panel.id}
+              depth={depth}
+              navigationDepth={navigationState.depth}
+              isActive={isActive}
+              inputState={inputState}
+              containerSize={containerSize}
+              behindOffset={behindOffset}
+              animateOnMount={animateOnMount}
+              animationDuration={animationDuration}
+              showShadow={showShadow}
+              displayMode={displayMode}
+              showDimming={showDimming}
+            >
+              {content}
+            </SwipeStackContent>
+          );
+        })}
+      </div>
+    );
+  },
+);

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

@@ -0,0 +1,281 @@
+/**
+ * @file Unit tests for computeStackContentState pure function.
+ *
+ * Tests the state computation logic for StackContent separated from React/CSS concerns.
+ */
+import {
+  computeAnimationType,
+  computeVisibility,
+  computeStackContentState,
+  type StackContentStateInput,
+} from "./computeStackContentState.js";
+
+describe("computeAnimationType", () => {
+  describe("when transitionMode is 'none'", () => {
+    it("returns null regardless of active state change", () => {
+      expect(computeAnimationType({ wasActive: false, isActive: true, transitionMode: "none" })).toBe(null);
+      expect(computeAnimationType({ wasActive: true, isActive: false, transitionMode: "none" })).toBe(null);
+    });
+  });
+
+  describe("when transitionMode is 'css'", () => {
+    it("returns 'push' when becoming active", () => {
+      const result = computeAnimationType({ wasActive: false, isActive: true, transitionMode: "css" });
+      expect(result).toBe("push");
+    });
+
+    it("returns 'pop' when becoming inactive", () => {
+      const result = computeAnimationType({ wasActive: true, isActive: false, transitionMode: "css" });
+      expect(result).toBe("pop");
+    });
+
+    it("returns null when active state has not changed", () => {
+      expect(computeAnimationType({ wasActive: true, isActive: true, transitionMode: "css" })).toBe(null);
+      expect(computeAnimationType({ wasActive: false, isActive: false, transitionMode: "css" })).toBe(null);
+    });
+  });
+});
+
+describe("computeVisibility", () => {
+  describe("overlay displayMode", () => {
+    const baseInput = {
+      displayMode: "overlay" as const,
+      depth: 1,
+      navigationDepth: 2,
+      isActive: false,
+      isAnimatingOut: false,
+      isRevealing: false,
+      revealDepth: null as number | null,
+    };
+
+    it("returns 'visible' when panel is active", () => {
+      const result = computeVisibility({ ...baseInput, isActive: true });
+      expect(result).toBe("visible");
+    });
+
+    it("returns 'visible' when panel is animating out (pop)", () => {
+      const result = computeVisibility({ ...baseInput, isAnimatingOut: true });
+      expect(result).toBe("visible");
+    });
+
+    it("returns 'visible' when revealing and depth matches revealDepth", () => {
+      const result = computeVisibility({
+        ...baseInput,
+        isRevealing: true,
+        revealDepth: 1,
+        depth: 1,
+      });
+      expect(result).toBe("visible");
+    });
+
+    it("returns 'hidden' when not active, not animating, not revealing", () => {
+      const result = computeVisibility(baseInput);
+      expect(result).toBe("hidden");
+    });
+
+    it("returns 'hidden' when revealing but depth does not match revealDepth", () => {
+      const result = computeVisibility({
+        ...baseInput,
+        isRevealing: true,
+        revealDepth: 0,
+        depth: 1,
+      });
+      expect(result).toBe("hidden");
+    });
+  });
+
+  describe("slide/stack displayMode", () => {
+    const baseInput = {
+      displayMode: "slide" as const,
+      depth: 1,
+      navigationDepth: 2,
+      isActive: false,
+      isAnimatingOut: false,
+      isRevealing: false,
+      revealDepth: null as number | null,
+    };
+
+    it("returns 'visible' when depth <= navigationDepth", () => {
+      expect(computeVisibility({ ...baseInput, depth: 0, navigationDepth: 2 })).toBe("visible");
+      expect(computeVisibility({ ...baseInput, depth: 1, navigationDepth: 2 })).toBe("visible");
+      expect(computeVisibility({ ...baseInput, depth: 2, navigationDepth: 2 })).toBe("visible");
+    });
+
+    it("returns 'hidden' when depth > navigationDepth", () => {
+      const result = computeVisibility({ ...baseInput, depth: 3, navigationDepth: 2 });
+      expect(result).toBe("hidden");
+    });
+
+    it("returns 'visible' when animating out even if depth > navigationDepth", () => {
+      const result = computeVisibility({
+        ...baseInput,
+        depth: 3,
+        navigationDepth: 2,
+        isAnimatingOut: true,
+      });
+      expect(result).toBe("visible");
+    });
+
+    it("works the same for 'stack' displayMode", () => {
+      const stackInput = { ...baseInput, displayMode: "stack" as const };
+      expect(computeVisibility({ ...stackInput, depth: 1, navigationDepth: 2 })).toBe("visible");
+      expect(computeVisibility({ ...stackInput, depth: 3, navigationDepth: 2 })).toBe("hidden");
+    });
+  });
+});
+
+describe("computeStackContentState", () => {
+  const baseInput: StackContentStateInput = {
+    depth: 1,
+    isActive: true,
+    wasActive: true,
+    currentAnimationType: null,
+    displayMode: "overlay",
+    transitionMode: "css",
+    navigationState: {
+      depth: 1,
+      isRevealing: false,
+      revealDepth: null,
+    },
+    swipeProgress: undefined,
+  };
+
+  describe("nextAnimationType computation", () => {
+    it("computes push animation when becoming active", () => {
+      const result = computeStackContentState({
+        ...baseInput,
+        wasActive: false,
+        isActive: true,
+      });
+      expect(result.nextAnimationType).toBe("push");
+    });
+
+    it("computes pop animation when becoming inactive", () => {
+      const result = computeStackContentState({
+        ...baseInput,
+        wasActive: true,
+        isActive: false,
+      });
+      expect(result.nextAnimationType).toBe("pop");
+    });
+
+    it("preserves current animation type when no state change", () => {
+      const result = computeStackContentState({
+        ...baseInput,
+        currentAnimationType: "push",
+      });
+      expect(result.nextAnimationType).toBe("push");
+    });
+  });
+
+  describe("visibility computation", () => {
+    it("sets visibility based on display mode and state", () => {
+      const result = computeStackContentState({
+        ...baseInput,
+        isActive: false,
+        wasActive: false,
+        displayMode: "overlay",
+      });
+      expect(result.visibility).toBe("hidden");
+    });
+
+    it("keeps panel visible during pop animation", () => {
+      const result = computeStackContentState({
+        ...baseInput,
+        isActive: false,
+        wasActive: true,
+        displayMode: "overlay",
+      });
+      // wasActive=true, isActive=false means pop animation is starting
+      expect(result.nextAnimationType).toBe("pop");
+      expect(result.visibility).toBe("visible");
+    });
+  });
+
+  describe("transform computation", () => {
+    it("returns translateX(0) for active panel", () => {
+      const result = computeStackContentState(baseInput);
+      expect(result.transform).toBe("translateX(0)");
+    });
+
+    it("applies swipe progress transform when swiping", () => {
+      const result = computeStackContentState({
+        ...baseInput,
+        swipeProgress: 0.5,
+      });
+      expect(result.transform).toBe("translateX(50%)");
+    });
+
+    it("does not apply swipe progress to non-active panels", () => {
+      const result = computeStackContentState({
+        ...baseInput,
+        isActive: false,
+        wasActive: false,
+        depth: 0,
+        navigationState: { depth: 1, isRevealing: false, revealDepth: null },
+        displayMode: "slide",
+        swipeProgress: 0.5,
+      });
+      // Previous panel in slide mode has fixed transform
+      expect(result.transform).toBe("translateX(-30%)");
+    });
+  });
+
+  describe("animation and transition", () => {
+    it("returns animation for push when becoming active", () => {
+      const result = computeStackContentState({
+        ...baseInput,
+        wasActive: false,
+        isActive: true,
+      });
+      expect(result.animation).toBeDefined();
+      expect(result.animation).toContain("var(--rpl-stack-animation-push");
+    });
+
+    it("returns animation for pop when becoming inactive", () => {
+      const result = computeStackContentState({
+        ...baseInput,
+        wasActive: true,
+        isActive: false,
+      });
+      expect(result.animation).toBeDefined();
+      expect(result.animation).toContain("var(--rpl-stack-animation-pop");
+    });
+
+    it("returns undefined animation when no animation type", () => {
+      const result = computeStackContentState(baseInput);
+      expect(result.animation).toBeUndefined();
+    });
+
+    it("returns transition when transitionMode is css", () => {
+      const result = computeStackContentState(baseInput);
+      expect(result.transition).toBeDefined();
+      expect(result.transition).toContain("transform");
+    });
+
+    it("returns undefined transition when transitionMode is none", () => {
+      const result = computeStackContentState({
+        ...baseInput,
+        transitionMode: "none",
+      });
+      expect(result.transition).toBeUndefined();
+    });
+  });
+
+  describe("static properties", () => {
+    it("sets zIndex to depth", () => {
+      const result = computeStackContentState({ ...baseInput, depth: 5 });
+      expect(result.zIndex).toBe(5);
+    });
+
+    it("sets pointerEvents to 'auto' when active", () => {
+      const result = computeStackContentState({ ...baseInput, isActive: true });
+      expect(result.pointerEvents).toBe("auto");
+    });
+
+    it("sets pointerEvents to 'none' when not active", () => {
+      const result = computeStackContentState({ ...baseInput, isActive: false, wasActive: false });
+      expect(result.pointerEvents).toBe("none");
+    });
+  });
+});