react-panel-layout 0.6.0 → 0.6.1

package/src/modules/stack/SwipeStackContent.tsx

@@ -9,7 +9,8 @@
  */
 import * as React from "react";
 import { useSwipeContentTransform } from "../../hooks/useSwipeContentTransform.js";
-import type { SwipeInputState, GestureAxis } from "../../hooks/gesture/types.js";
+import { useOperationContinuity } from "../../hooks/useOperationContinuity.js";
+import type { ContinuousOperationState, GestureAxis } from "../../hooks/gesture/types.js";
 import type { StackDisplayMode } from "./types.js";
 import {
   computeActiveTargetPx,
@@ -27,11 +28,6 @@ const DEFAULT_ANIMATION_DURATION = 300;
  */
 const STACK_SCALE_FACTOR = 0.05;
 
-/**
- * Offset percentage per depth level for "stack" display mode.
- */
-const STACK_OFFSET_PERCENT = 5;
-
 /**
  * Maximum dimming opacity for behind panels in iOS-style navigation.
  */
@@ -39,6 +35,9 @@ const MAX_DIM_OPACITY = 0.1;
 
 /**
  * Props for SwipeStackContent component.
+ *
+ * This component accepts ContinuousOperationState, meaning it responds uniformly
+ * to any continuous operation (whether human gesture or system animation).
  */
 export type SwipeStackContentProps = {
   /** Panel ID */
@@ -49,8 +48,8 @@ export type SwipeStackContentProps = {
   navigationDepth: number;
   /** Whether this panel is currently active */
   isActive: boolean;
-  /** Swipe input state from useStackSwipeInput */
-  inputState: SwipeInputState;
+  /** Continuous operation state (from gesture input or animation system) */
+  operationState: ContinuousOperationState;
   /** Container size in pixels (width for horizontal, height for vertical) */
   containerSize: number;
   /** Gesture axis. @default "horizontal" */
@@ -96,13 +95,13 @@ const BASE_STYLE: React.CSSProperties = {
 };
 
 /**
- * Get displacement from input state for the given axis.
+ * Get displacement from operation state for the given axis.
  */
-const getAxisDisplacement = (inputState: SwipeInputState, axis: GestureAxis): number => {
-  if (inputState.phase === "idle") {
+const getAxisDisplacement = (state: ContinuousOperationState, axis: GestureAxis): number => {
+  if (state.phase === "idle") {
     return 0;
   }
-  return axis === "horizontal" ? inputState.displacement.x : inputState.displacement.y;
+  return axis === "horizontal" ? state.displacement.x : state.displacement.y;
 };
 
 /**
@@ -136,7 +135,7 @@ export const SwipeStackContent: React.FC<SwipeStackContentProps> = React.memo(
     depth,
     navigationDepth,
     isActive,
-    inputState,
+    operationState,
     containerSize,
     axis = "horizontal",
     behindOffset = DEFAULT_BEHIND_OFFSET,
@@ -148,23 +147,27 @@ export const SwipeStackContent: React.FC<SwipeStackContentProps> = React.memo(
     children,
   }) => {
     const elementRef = React.useRef<HTMLDivElement>(null);
-    const isFirstMountRef = React.useRef<boolean>(true);
 
-    const displacement = getAxisDisplacement(inputState, axis);
-    const isSwiping = inputState.phase === "swiping" || inputState.phase === "tracking";
+    const displacement = getAxisDisplacement(operationState, axis);
+    const isOperating = operationState.phase === "operating";
 
     // Determine panel role
     const role = determineSwipePanelRole(depth, navigationDepth);
 
-    // Track first mount for push animation
-    const isFirstMount = isFirstMountRef.current;
-    if (isFirstMountRef.current) {
-      isFirstMountRef.current = false;
-    }
+    // Maintain role continuity during swipe operations.
+    // When navigation changes before the gesture ends (e.g., role changes from
+    // "behind" to "active"), we keep using the previous role for position
+    // calculations to prevent visual jumps.
+    // changedDuringOperation tells us if the role changed during the operation,
+    // which we use to skip backward target change animation (over-swipe case).
+    const { value: effectiveRole, changedDuringOperation } = useOperationContinuity(
+      role,
+      displacement > 0,
+    );
 
-    // Compute target position based on role
+    // Compute target position based on effective role
     const targetPx = React.useMemo(() => {
-      switch (role) {
+      switch (effectiveRole) {
         case "active":
           // Active panel rests at 0
           return 0;
@@ -175,7 +178,7 @@ export const SwipeStackContent: React.FC<SwipeStackContentProps> = React.memo(
           // Hidden panels are off-screen
           return containerSize;
       }
-    }, [role, behindOffset, containerSize]);
+    }, [effectiveRole, behindOffset, containerSize]);
 
     // Compute displacement for this panel
     const panelDisplacement = React.useMemo(() => {
@@ -183,7 +186,7 @@ export const SwipeStackContent: React.FC<SwipeStackContentProps> = React.memo(
         return 0;
       }
 
-      switch (role) {
+      switch (effectiveRole) {
         case "active":
           // Active panel follows finger directly
           return computeActiveTargetPx(displacement);
@@ -196,15 +199,17 @@ export const SwipeStackContent: React.FC<SwipeStackContentProps> = React.memo(
         case "hidden":
           return 0;
       }
-    }, [role, displacement, containerSize, behindOffset]);
+    }, [effectiveRole, displacement, containerSize, behindOffset]);
 
     // Compute initial position for push animation
     // When animateOnMount is true and panel is first mounted as "active",
     // it should animate in from off-screen
     // Root panel (depth=0) should not animate on mount
+    // Note: useSwipeContentTransform handles first-mount tracking internally,
+    // so we just declare the initial position; the hook consumes it only once.
     const initialPx = React.useMemo(() => {
-      if (!isFirstMount || !animateOnMount) {
-        return undefined; // Only relevant on first mount with animateOnMount
+      if (!animateOnMount) {
+        return undefined;
       }
       if (role === "active" && depth > 0) {
         // New active panel (not root): start from off-screen right
@@ -212,14 +217,14 @@ export const SwipeStackContent: React.FC<SwipeStackContentProps> = React.memo(
       }
       // Root panel or other roles: start at their natural position
       return undefined;
-    }, [isFirstMount, animateOnMount, role, depth, containerSize]);
+    }, [animateOnMount, role, depth, containerSize]);
 
     // Use shared transform hook for DOM manipulation
     const { isAnimating } = useSwipeContentTransform({
       elementRef,
       targetPx,
       displacement: panelDisplacement,
-      isSwiping,
+      isOperating,
       axis,
       animationDuration,
       containerSize,
@@ -227,6 +232,11 @@ export const SwipeStackContent: React.FC<SwipeStackContentProps> = React.memo(
       animateOnTargetChange: true,
       // For push animation: start from off-screen
       initialPx,
+      // Skip backward animation if role changed during the operation.
+      // This handles over-swipe where panel moves beyond 100% and needs to snap back.
+      // useSwipeContentTransform allows forward animations (normal swipe-to-complete)
+      // but skips backward animations (over-swipe snap).
+      skipTargetChangeAnimation: changedDuringOperation,
     });
 
     // Compute visibility
@@ -234,7 +244,7 @@ export const SwipeStackContent: React.FC<SwipeStackContentProps> = React.memo(
       depth,
       navigationDepth,
       isActive,
-      isSwiping,
+      isOperating,
       isAnimating,
     });
 
@@ -309,7 +319,7 @@ export const SwipeStackContent: React.FC<SwipeStackContentProps> = React.memo(
 
     // Compute shadow for active panel
     // Shadow is shown on panels at depth > 0 when they're active or animating
-    const shouldShowShadow = showShadow && depth > 0 && role === "active";
+    const shouldShowShadow = showShadow ? depth > 0 && role === "active" : false;
 
     // Static style - transform is handled entirely by useSwipeContentTransform
     // to ensure smooth animations
@@ -349,7 +359,7 @@ export const SwipeStackContent: React.FC<SwipeStackContentProps> = React.memo(
         style={staticStyle}
       >
         {children}
-        {dimmingStyle != null && <div style={dimmingStyle} data-dimming-overlay />}
+        {dimmingStyle != null ? <div style={dimmingStyle} data-dimming-overlay /> : null}
       </div>
     );
   },

package/src/modules/stack/SwipeStackOutlet.spec.tsx

@@ -3,21 +3,19 @@
  */
 import { render } from "@testing-library/react";
 import { SwipeStackOutlet } from "./SwipeStackOutlet.js";
-import type { SwipeInputState } from "../../hooks/gesture/types.js";
+import type { ContinuousOperationState } from "../../hooks/gesture/types.js";
 import type { StackPanel, StackNavigationState } from "./types.js";
 
-const IDLE_STATE: SwipeInputState = {
+const IDLE_STATE: ContinuousOperationState = {
   phase: "idle",
   displacement: { x: 0, y: 0 },
   velocity: { x: 0, y: 0 },
-  direction: 0,
 };
 
-const createSwipingState = (displacementX: number): SwipeInputState => ({
-  phase: "swiping",
+const createOperatingState = (displacementX: number): ContinuousOperationState => ({
+  phase: "operating",
   displacement: { x: displacementX, y: 0 },
   velocity: { x: 0.5, y: 0 },
-  direction: displacementX > 0 ? 1 : displacementX < 0 ? -1 : 0,
 });
 
 const createPanels = (): StackPanel[] => [
@@ -40,7 +38,7 @@ describe("SwipeStackOutlet", () => {
         <SwipeStackOutlet
           panels={createPanels()}
           navigationState={navigationState}
-          inputState={IDLE_STATE}
+          operationState={IDLE_STATE}
           containerSize={400}
         />,
       );
@@ -61,7 +59,7 @@ describe("SwipeStackOutlet", () => {
         <SwipeStackOutlet
           panels={createPanels()}
           navigationState={navigationState}
-          inputState={IDLE_STATE}
+          operationState={IDLE_STATE}
           containerSize={400}
         />,
       );
@@ -85,7 +83,7 @@ describe("SwipeStackOutlet", () => {
         <SwipeStackOutlet
           panels={createPanels()}
           navigationState={navigationState}
-          inputState={IDLE_STATE}
+          operationState={IDLE_STATE}
           containerSize={400}
         />,
       );
@@ -109,7 +107,7 @@ describe("SwipeStackOutlet", () => {
         <SwipeStackOutlet
           panels={createPanels()}
           navigationState={navigationState}
-          inputState={IDLE_STATE}
+          operationState={IDLE_STATE}
           containerSize={400}
         />,
       );
@@ -131,13 +129,13 @@ describe("SwipeStackOutlet", () => {
         revealDepth: null,
       };
 
-      const swipeState = createSwipingState(200);
+      const swipeState = createOperatingState(200);
 
       const { container, rerender } = render(
         <SwipeStackOutlet
           panels={createPanels()}
           navigationState={navigationState}
-          inputState={IDLE_STATE}
+          operationState={IDLE_STATE}
           containerSize={400}
         />,
       );
@@ -147,7 +145,7 @@ describe("SwipeStackOutlet", () => {
         <SwipeStackOutlet
           panels={createPanels()}
           navigationState={navigationState}
-          inputState={swipeState}
+          operationState={swipeState}
           containerSize={400}
         />,
       );
@@ -185,7 +183,7 @@ describe("SwipeStackOutlet", () => {
         <SwipeStackOutlet
           panels={createPanels()}
           navigationState={navigationState}
-          inputState={IDLE_STATE}
+          operationState={IDLE_STATE}
           containerSize={400}
           getCachedContent={getCachedContent}
         />,
@@ -210,7 +208,7 @@ describe("SwipeStackOutlet", () => {
         <SwipeStackOutlet
           panels={createPanels()}
           navigationState={navigationState}
-          inputState={IDLE_STATE}
+          operationState={IDLE_STATE}
           containerSize={400}
           getCachedContent={getCachedContent}
         />,
@@ -233,7 +231,7 @@ describe("SwipeStackOutlet", () => {
         <SwipeStackOutlet
           panels={createPanels()}
           navigationState={navigationState}
-          inputState={IDLE_STATE}
+          operationState={IDLE_STATE}
           containerSize={400}
         />,
       );

package/src/modules/stack/SwipeStackOutlet.tsx

@@ -6,7 +6,7 @@
  */
 import * as React from "react";
 import { SwipeStackContent } from "./SwipeStackContent.js";
-import type { SwipeInputState } from "../../hooks/gesture/types.js";
+import type { ContinuousOperationState } from "../../hooks/gesture/types.js";
 import type { StackPanel, StackNavigationState } from "./types.js";
 
 const DEFAULT_ANIMATION_DURATION = 300;
@@ -19,8 +19,8 @@ export type SwipeStackOutletProps = {
   panels: ReadonlyArray<StackPanel>;
   /** Current navigation state */
   navigationState: StackNavigationState;
-  /** Swipe input state from useStackSwipeInput */
-  inputState: SwipeInputState;
+  /** Continuous operation state (from gesture input or animation system) */
+  operationState: ContinuousOperationState;
   /** Container size in pixels (width for horizontal swipe) */
   containerSize: number;
   /** Function to get cached content for a panel */
@@ -121,7 +121,7 @@ function getVisiblePanels(
  *     <SwipeStackOutlet
  *       panels={navigation.panels}
  *       navigationState={navigation.state}
- *       inputState={swipeInput.inputState}
+ *       operationState={toContinuousOperationState(swipeInput.inputState)}
  *       containerSize={containerWidth}
  *     />
  *   </div>
@@ -132,7 +132,7 @@ export const SwipeStackOutlet: React.FC<SwipeStackOutletProps> = React.memo(
   ({
     panels,
     navigationState,
-    inputState,
+    operationState,
     containerSize,
     getCachedContent,
     behindOffset,
@@ -202,7 +202,7 @@ export const SwipeStackOutlet: React.FC<SwipeStackOutletProps> = React.memo(
               depth={depth}
               navigationDepth={navigationState.depth}
               isActive={isActive}
-              inputState={inputState}
+              operationState={operationState}
               containerSize={containerSize}
               behindOffset={behindOffset}
               animateOnMount={animateOnMount}

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

@@ -106,7 +106,7 @@ describe("computeSwipeVisibility", () => {
         depth: 2,
         navigationDepth: 2,
         isActive: true,
-        isSwiping: false,
+        isOperating: false,
         isAnimating: false,
       }),
     ).toBe(true);
@@ -118,7 +118,7 @@ describe("computeSwipeVisibility", () => {
         depth: 1,
         navigationDepth: 2,
         isActive: false,
-        isSwiping: true,
+        isOperating: true,
         isAnimating: false,
       }),
     ).toBe(true);
@@ -130,7 +130,7 @@ describe("computeSwipeVisibility", () => {
         depth: 1,
         navigationDepth: 2,
         isActive: false,
-        isSwiping: false,
+        isOperating: false,
         isAnimating: true,
       }),
     ).toBe(true);
@@ -142,7 +142,7 @@ describe("computeSwipeVisibility", () => {
         depth: 1,
         navigationDepth: 2,
         isActive: false,
-        isSwiping: false,
+        isOperating: false,
         isAnimating: false,
       }),
     ).toBe(false);
@@ -154,7 +154,7 @@ describe("computeSwipeVisibility", () => {
         depth: 0,
         navigationDepth: 2,
         isActive: false,
-        isSwiping: true,
+        isOperating: true,
         isAnimating: false,
       }),
     ).toBe(false);

package/src/modules/stack/computeSwipeStackTransform.ts

@@ -85,7 +85,7 @@ export type ComputeSwipeVisibilityInput = {
   /** Whether this panel is currently active */
   isActive: boolean;
   /** Whether swipe gesture is active */
-  isSwiping: boolean;
+  isOperating: boolean;
   /** Whether snap-back animation is running */
   isAnimating: boolean;
 };
@@ -100,7 +100,7 @@ export type ComputeSwipeVisibilityInput = {
  * @returns true if panel should be visible
  */
 export function computeSwipeVisibility(input: ComputeSwipeVisibilityInput): boolean {
-  const { depth, navigationDepth, isActive, isSwiping, isAnimating } = input;
+  const { depth, navigationDepth, isActive, isOperating, isAnimating } = input;
 
   // Active panel is always visible
   if (isActive) {
@@ -110,7 +110,7 @@ export function computeSwipeVisibility(input: ComputeSwipeVisibilityInput): bool
   // Behind panel (one level back) is visible during swipe or animation
   const isBehindPanel = depth === navigationDepth - 1;
   if (isBehindPanel) {
-    if (isSwiping) {
+    if (isOperating) {
       return true;
     }
     if (isAnimating) {