react-panel-layout 0.6.0 → 0.6.1

package/src/hooks/gesture/utils.ts

@@ -85,3 +85,94 @@ export const mergeGestureContainerProps = (
     style: mergedStyle,
   };
 };
+
+// ============================================================================
+// Scroll Detection Utilities
+// ============================================================================
+
+/**
+ * Check if an element is scrollable in any direction.
+ */
+export function isScrollableElement(element: HTMLElement): boolean {
+  const style = getComputedStyle(element);
+
+  const isScrollableX =
+    (style.overflowX === "scroll" || style.overflowX === "auto") &&
+    element.scrollWidth > element.clientWidth;
+
+  const isScrollableY =
+    (style.overflowY === "scroll" || style.overflowY === "auto") &&
+    element.scrollHeight > element.clientHeight;
+
+  return isScrollableX || isScrollableY;
+}
+
+/**
+ * Check if we should start drag based on scroll state.
+ * Returns false if the target is inside a scrollable element.
+ */
+export function shouldStartDrag(
+  event: React.PointerEvent,
+  container: HTMLElement,
+): boolean {
+  // eslint-disable-next-line no-restricted-syntax -- loop variable requires let
+  let current = event.target as HTMLElement | null;
+
+  while (current !== null && current !== container) {
+    if (isScrollableElement(current)) {
+      return false;
+    }
+    current = current.parentElement;
+  }
+
+  return true;
+}
+
+/**
+ * Check if an element or its ancestors are scrollable in the specified direction.
+ * Returns true if scrolling is possible and would block the swipe gesture.
+ *
+ * @param element - The target element to check
+ * @param container - The container boundary
+ * @param axis - The axis to check ("x" or "y")
+ * @param direction - The swipe direction (1 = right/down, -1 = left/up)
+ */
+export function isScrollableInDirection(
+  element: HTMLElement,
+  container: HTMLElement,
+  axis: "x" | "y",
+  direction: 1 | -1,
+): boolean {
+  // eslint-disable-next-line no-restricted-syntax -- loop variable requires let
+  let current: HTMLElement | null = element;
+
+  while (current !== null && current !== container) {
+    const style = getComputedStyle(current);
+    const isHorizontal = axis === "x";
+
+    const overflow = isHorizontal ? style.overflowX : style.overflowY;
+    const isScrollable = overflow === "scroll" || overflow === "auto";
+
+    if (isScrollable) {
+      const scrollSize = isHorizontal
+        ? current.scrollWidth - current.clientWidth
+        : current.scrollHeight - current.clientHeight;
+
+      if (scrollSize > 0) {
+        const scrollPos = isHorizontal ? current.scrollLeft : current.scrollTop;
+
+        // If swiping in close direction and not at boundary, block swipe
+        if (direction === -1 && scrollPos > 1) {
+          return true; // Can scroll left/up, block swipe
+        }
+        if (direction === 1 && scrollPos < scrollSize - 1) {
+          return true; // Can scroll right/down, block swipe
+        }
+      }
+    }
+
+    current = current.parentElement;
+  }
+
+  return false;
+}

package/src/hooks/useAnimatedVisibility.spec.ts

@@ -5,9 +5,46 @@
  * 1. アニメーションなし → 即座にdisplay:none
  * 2. アニメーションあり → 完了待ってdisplay:none
  */
+import type * as React from "react";
 import { renderHook, act } from "@testing-library/react";
 import { useAnimatedVisibility } from "./useAnimatedVisibility.js";
 
+/**
+ * Create a mock AnimationEvent for testing.
+ */
+function createMockAnimationEvent(
+  target: EventTarget,
+  currentTarget: EventTarget,
+): React.AnimationEvent {
+  const noop = (): void => {};
+  const noopBool = (): boolean => false;
+  const nativeEvent = {
+    animationName: "test",
+    elapsedTime: 0,
+    pseudoElement: "",
+  } as AnimationEvent;
+  return {
+    target,
+    currentTarget,
+    nativeEvent,
+    bubbles: true,
+    cancelable: false,
+    defaultPrevented: false,
+    eventPhase: 0,
+    isTrusted: true,
+    preventDefault: noop,
+    isDefaultPrevented: noopBool,
+    stopPropagation: noop,
+    isPropagationStopped: noopBool,
+    persist: noop,
+    timeStamp: Date.now(),
+    type: "animationend",
+    animationName: "test",
+    elapsedTime: 0,
+    pseudoElement: "",
+  };
+}
+
 describe("useAnimatedVisibility", () => {
   describe("initial state", () => {
     it("displays when initially visible", () => {
@@ -120,10 +157,7 @@ describe("useAnimatedVisibility", () => {
 
       // Simulate animationend event
       const sharedElement = document.createElement("div");
-      const mockEvent = {
-        target: sharedElement,
-        currentTarget: sharedElement,
-      } as unknown as React.AnimationEvent;
+      const mockEvent = createMockAnimationEvent(sharedElement, sharedElement);
 
       act(() => {
         result.current.props.onAnimationEnd(mockEvent);
@@ -149,10 +183,7 @@ describe("useAnimatedVisibility", () => {
       // Simulate animationend from a child element (target !== currentTarget)
       const parent = document.createElement("div");
       const child = document.createElement("div");
-      const mockEvent = {
-        target: child,
-        currentTarget: parent,
-      } as unknown as React.AnimationEvent;
+      const mockEvent = createMockAnimationEvent(child, parent);
 
       act(() => {
         result.current.props.onAnimationEnd(mockEvent);
@@ -188,14 +219,12 @@ describe("useAnimatedVisibility", () => {
 
   describe("timeout fallback", () => {
     it("hides after timeout if animationEnd never fires", async () => {
-      vi.useFakeTimers();
-
       const { result, rerender } = renderHook(
         ({ isVisible }) =>
           useAnimatedVisibility({
             isVisible,
             leaveAnimation: "fadeOut 200ms ease-out",
-            animationTimeout: 500,
+            animationTimeout: 10,
           }),
         { initialProps: { isVisible: true } },
       );
@@ -206,25 +235,21 @@ describe("useAnimatedVisibility", () => {
 
       // Advance time past timeout
       await act(async () => {
-        vi.advanceTimersByTime(600);
+        await new Promise((resolve) => setTimeout(resolve, 20));
       });
 
       // Should be hidden now (fallback triggered)
       expect(result.current.style.display).toBe("none");
       expect(result.current.state.isAnimatingOut).toBe(false);
-
-      vi.useRealTimers();
     });
 
     it("clears timeout when animationEnd fires before timeout", async () => {
-      vi.useFakeTimers();
-
       const { result, rerender } = renderHook(
         ({ isVisible }) =>
           useAnimatedVisibility({
             isVisible,
             leaveAnimation: "fadeOut 200ms ease-out",
-            animationTimeout: 500,
+            animationTimeout: 10,
           }),
         { initialProps: { isVisible: true } },
       );
@@ -233,10 +258,7 @@ describe("useAnimatedVisibility", () => {
 
       // Fire animationEnd before timeout
       const sharedElement = document.createElement("div");
-      const mockEvent = {
-        target: sharedElement,
-        currentTarget: sharedElement,
-      } as unknown as React.AnimationEvent;
+      const mockEvent = createMockAnimationEvent(sharedElement, sharedElement);
 
       act(() => {
         result.current.props.onAnimationEnd(mockEvent);
@@ -246,12 +268,10 @@ describe("useAnimatedVisibility", () => {
 
       // Advance past timeout - should not affect state
       await act(async () => {
-        vi.advanceTimersByTime(600);
+        await new Promise((resolve) => setTimeout(resolve, 20));
       });
 
       expect(result.current.style.display).toBe("none");
-
-      vi.useRealTimers();
     });
   });
 });

package/src/hooks/useAnimatedVisibility.ts

@@ -72,6 +72,32 @@ export function useAnimatedVisibility({
   const timeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
 
   // Clear timeout on unmount
+  const shouldSkipLeaveAnimation = (
+    isSkipped: boolean,
+    animation: string | undefined,
+  ): boolean => {
+    if (isSkipped) {
+      return true;
+    }
+    if (!animation) {
+      return true;
+    }
+    if (animation === "none") {
+      return true;
+    }
+    return false;
+  };
+
+  const getShouldDisplay = (visible: boolean, animatingOut: boolean): boolean => {
+    if (visible) {
+      return true;
+    }
+    if (animatingOut) {
+      return true;
+    }
+    return false;
+  };
+
   React.useEffect(() => {
     return () => {
       if (timeoutRef.current) {
@@ -92,7 +118,7 @@ export function useAnimatedVisibility({
 
     if (wasVisible && !isVisible) {
       // Transitioning from visible to hidden
-      if (skipAnimation || !leaveAnimation || leaveAnimation === "none") {
+      if (shouldSkipLeaveAnimation(skipAnimation, leaveAnimation)) {
         // No animation, hide immediately
         setIsAnimatingOut(false);
       } else {
@@ -129,7 +155,7 @@ export function useAnimatedVisibility({
   // Element should be displayed if:
   // - It's visible, OR
   // - It's animating out (leave animation in progress)
-  const shouldDisplay = isVisible || isAnimatingOut;
+  const shouldDisplay = getShouldDisplay(isVisible, isAnimatingOut);
 
   return {
     state: {

package/src/hooks/useAnimationFrame.ts

@@ -40,6 +40,14 @@ export const easings = {
     }
     return 1 - Math.pow(-2 * t + 2, 3) / 2;
   },
+
+  /** Ease in expo (accelerating, for "suck in" effect) */
+  easeInExpo: (t: number): number => {
+    if (t === 0) {
+      return 0;
+    }
+    return Math.pow(2, 10 * t - 10);
+  },
 } as const;
 
 /**

package/src/hooks/useOperationContinuity.spec.ts

@@ -0,0 +1,387 @@
+/**
+ * @file Tests for useOperationContinuity hook.
+ */
+import * as React from "react";
+import { renderHook } from "@testing-library/react";
+import { useOperationContinuity } from "./useOperationContinuity.js";
+
+const StrictModeWrapper = ({ children }: { children: React.ReactNode }): React.ReactNode => {
+  return React.createElement(React.StrictMode, null, children);
+};
+
+describe("useOperationContinuity", () => {
+  describe("value continuity", () => {
+    it("returns current value when not retaining", () => {
+      const { result } = renderHook(() => useOperationContinuity("active", false));
+      expect(result.current.value).toBe("active");
+    });
+
+    it("returns current value when retaining but value unchanged", () => {
+      const { result } = renderHook(() => useOperationContinuity("active", true));
+      expect(result.current.value).toBe("active");
+    });
+
+    it("retains previous value when shouldRetainPrevious is true", () => {
+      const { result, rerender } = renderHook(
+        ({ value, shouldRetainPrevious }) => useOperationContinuity(value, shouldRetainPrevious),
+        { initialProps: { value: "behind", shouldRetainPrevious: true } },
+      );
+
+      expect(result.current.value).toBe("behind");
+
+      // Value changes but we're still retaining
+      rerender({ value: "active", shouldRetainPrevious: true });
+      expect(result.current.value).toBe("behind");
+    });
+
+    it("accepts new value when shouldRetainPrevious becomes false", () => {
+      const { result, rerender } = renderHook(
+        ({ value, shouldRetainPrevious }) => useOperationContinuity(value, shouldRetainPrevious),
+        { initialProps: { value: "behind", shouldRetainPrevious: true } },
+      );
+
+      // Value changes while retaining
+      rerender({ value: "active", shouldRetainPrevious: true });
+      expect(result.current.value).toBe("behind");
+
+      // Stop retaining - should accept new value
+      rerender({ value: "active", shouldRetainPrevious: false });
+      expect(result.current.value).toBe("active");
+    });
+
+    it("updates stored value when not retaining", () => {
+      const { result, rerender } = renderHook(
+        ({ value, shouldRetainPrevious }) => useOperationContinuity(value, shouldRetainPrevious),
+        { initialProps: { value: "behind", shouldRetainPrevious: false } },
+      );
+
+      rerender({ value: "active", shouldRetainPrevious: false });
+      expect(result.current.value).toBe("active");
+
+      // Start retaining - should keep "active"
+      rerender({ value: "hidden", shouldRetainPrevious: true });
+      expect(result.current.value).toBe("active");
+    });
+  });
+
+  describe("changedDuringOperation tracking", () => {
+    it("returns false when value never changed", () => {
+      const { result, rerender } = renderHook(
+        ({ value, retain }) => useOperationContinuity(value, retain),
+        { initialProps: { value: "active", retain: true } },
+      );
+
+      expect(result.current.changedDuringOperation).toBe(false);
+
+      // End retention without value change
+      rerender({ value: "active", retain: false });
+      expect(result.current.changedDuringOperation).toBe(false);
+    });
+
+    it("returns true when value changed during retention", () => {
+      const { result, rerender } = renderHook(
+        ({ value, retain }) => useOperationContinuity(value, retain),
+        { initialProps: { value: "behind", retain: true } },
+      );
+
+      expect(result.current.changedDuringOperation).toBe(false);
+
+      // Value changes while retaining
+      rerender({ value: "active", retain: true });
+      expect(result.current.changedDuringOperation).toBe(true);
+
+      // End retention - should still be true (for this render)
+      rerender({ value: "active", retain: false });
+      expect(result.current.changedDuringOperation).toBe(true);
+    });
+
+    it("resets changedDuringOperation after operation ends", () => {
+      const { result, rerender } = renderHook(
+        ({ value, retain }) => useOperationContinuity(value, retain),
+        { initialProps: { value: "behind", retain: true } },
+      );
+
+      // Value changes while retaining
+      rerender({ value: "active", retain: true });
+      expect(result.current.changedDuringOperation).toBe(true);
+
+      // End retention
+      rerender({ value: "active", retain: false });
+      expect(result.current.changedDuringOperation).toBe(true);
+
+      // Next render - should be reset
+      rerender({ value: "active", retain: false });
+      expect(result.current.changedDuringOperation).toBe(false);
+    });
+
+    it("tracks changes across multiple operations", () => {
+      const { result, rerender } = renderHook(
+        ({ value, retain }) => useOperationContinuity(value, retain),
+        { initialProps: { value: "behind", retain: true } },
+      );
+
+      // First operation: value changes
+      rerender({ value: "active", retain: true });
+      rerender({ value: "active", retain: false });
+      expect(result.current.changedDuringOperation).toBe(true);
+
+      // Reset
+      rerender({ value: "active", retain: false });
+      expect(result.current.changedDuringOperation).toBe(false);
+
+      // Second operation: no value change
+      rerender({ value: "active", retain: true });
+      rerender({ value: "active", retain: false });
+      expect(result.current.changedDuringOperation).toBe(false);
+
+      // Third operation: value changes again
+      rerender({ value: "active", retain: true });
+      rerender({ value: "hidden", retain: true });
+      expect(result.current.changedDuringOperation).toBe(true);
+      rerender({ value: "hidden", retain: false });
+      expect(result.current.changedDuringOperation).toBe(true);
+    });
+  });
+
+  describe("simultaneous value and retention change", () => {
+    /**
+     * CRITICAL: This tests the over-swipe bug scenario.
+     *
+     * In the real app, when user releases after over-swipe:
+     * - displacement becomes 0 (shouldRetainPrevious becomes false)
+     * - role changes from "active" to "hidden"
+     * Both happen in the same render!
+     *
+     * The hook should detect that the value changed even though
+     * the change happened at the exact moment retention ended.
+     */
+    it("detects value change when it happens simultaneously with retention ending", () => {
+      const { result, rerender } = renderHook(
+        ({ role, displacement }) => useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "active" as const, displacement: 500 } },
+      );
+
+      // During swipe: role="active", retaining
+      expect(result.current.value).toBe("active");
+      expect(result.current.changedDuringOperation).toBe(false);
+
+      // Simulate release: BOTH displacement becomes 0 AND role changes to "hidden"
+      // This is what happens in the real app during over-swipe
+      rerender({ role: "hidden" as const, displacement: 0 });
+
+      // value should now be "hidden" (retention ended)
+      expect(result.current.value).toBe("hidden");
+      // CRITICAL: changedDuringOperation should be TRUE because the value
+      // changed from "active" to "hidden" at the moment retention ended
+      expect(result.current.changedDuringOperation).toBe(true);
+    });
+
+    it("does not report change when value stays the same at retention end", () => {
+      const { result, rerender } = renderHook(
+        ({ role, displacement }) => useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "active" as const, displacement: 500 } },
+      );
+
+      expect(result.current.value).toBe("active");
+      expect(result.current.changedDuringOperation).toBe(false);
+
+      // Release but role stays "active" (e.g., partial swipe that didn't trigger navigation)
+      rerender({ role: "active" as const, displacement: 0 });
+
+      expect(result.current.value).toBe("active");
+      // No change occurred
+      expect(result.current.changedDuringOperation).toBe(false);
+    });
+
+    it("does NOT report change during button navigation (no operation)", () => {
+      // This is the button navigation case: value changes but there was never
+      // any retention (no swipe operation). We should NOT report changedDuringOperation
+      // because this is normal navigation, not an operation-related change.
+      const { result, rerender } = renderHook(
+        ({ role, displacement }) => useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "active" as const, displacement: 0 } },
+      );
+
+      expect(result.current.value).toBe("active");
+      expect(result.current.changedDuringOperation).toBe(false);
+
+      // Button navigation: role changes but there's no operation (displacement is always 0)
+      rerender({ role: "behind" as const, displacement: 0 });
+
+      expect(result.current.value).toBe("behind");
+      // CRITICAL: changedDuringOperation should be FALSE because there was no operation
+      // This allows the animation to happen normally for button navigation
+      expect(result.current.changedDuringOperation).toBe(false);
+    });
+  });
+
+  describe("role transition scenarios", () => {
+    it("maintains role continuity during swipe (behind -> active)", () => {
+      // Simulates: behind panel becomes active during swipe
+      // displacement > 0, so we should retain the previous role
+      const { result, rerender } = renderHook(
+        ({ role, displacement }) => useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "behind" as const, displacement: 100 } },
+      );
+
+      expect(result.current.value).toBe("behind");
+      expect(result.current.changedDuringOperation).toBe(false);
+
+      // Navigation changes role to "active" but displacement is still positive
+      rerender({ role: "active" as const, displacement: 100 });
+      expect(result.current.value).toBe("behind");
+      expect(result.current.changedDuringOperation).toBe(true);
+
+      // Swipe ends (displacement becomes 0)
+      rerender({ role: "active" as const, displacement: 0 });
+      expect(result.current.value).toBe("active");
+      expect(result.current.changedDuringOperation).toBe(true);
+    });
+
+    it("maintains role continuity during swipe (active -> hidden)", () => {
+      // Simulates: over-swipe where active panel becomes hidden
+      const { result, rerender } = renderHook(
+        ({ role, displacement }) => useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "active" as const, displacement: 400 } },
+      );
+
+      expect(result.current.value).toBe("active");
+
+      // Over-swipe triggers navigation change
+      rerender({ role: "hidden" as const, displacement: 500 });
+      expect(result.current.value).toBe("active");
+      expect(result.current.changedDuringOperation).toBe(true);
+
+      // Swipe ends
+      rerender({ role: "hidden" as const, displacement: 0 });
+      expect(result.current.value).toBe("hidden");
+      expect(result.current.changedDuringOperation).toBe(true);
+    });
+
+    it("provides changedDuringOperation for animation decision", () => {
+      // This test demonstrates the intended use case:
+      // Use changedDuringOperation to decide whether to animate on operation end
+      const { result, rerender } = renderHook(
+        ({ role, displacement }) => useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "behind" as const, displacement: 100 } },
+      );
+
+      // Simulate role change during swipe
+      rerender({ role: "active" as const, displacement: 100 });
+
+      // When swipe ends, changedDuringOperation tells us to skip animation
+      rerender({ role: "active" as const, displacement: 0 });
+      expect(result.current.changedDuringOperation).toBe(true);
+      // Consumer would use this to skip target change animation
+    });
+  });
+
+  describe("works with different value types", () => {
+    it("works with numbers", () => {
+      const { result, rerender } = renderHook(
+        ({ value, retain }) => useOperationContinuity(value, retain),
+        { initialProps: { value: 0, retain: true } },
+      );
+
+      rerender({ value: 1, retain: true });
+      expect(result.current.value).toBe(0);
+
+      rerender({ value: 1, retain: false });
+      expect(result.current.value).toBe(1);
+    });
+
+    it("works with objects (by reference)", () => {
+      const obj1 = { id: 1 };
+      const obj2 = { id: 2 };
+
+      const { result, rerender } = renderHook(
+        ({ value, retain }) => useOperationContinuity(value, retain),
+        { initialProps: { value: obj1, retain: true } },
+      );
+
+      rerender({ value: obj2, retain: true });
+      expect(result.current.value).toBe(obj1);
+
+      rerender({ value: obj2, retain: false });
+      expect(result.current.value).toBe(obj2);
+    });
+  });
+
+  describe("React StrictMode compatibility", () => {
+    /**
+     * CRITICAL: These tests verify the hook works correctly in StrictMode.
+     *
+     * In StrictMode, React calls the render function twice. Hooks that mutate
+     * refs during render will see the mutated value on the second call, which
+     * can cause bugs.
+     *
+     * This hook uses useLayoutEffect for ref mutations to avoid this issue.
+     */
+    it("operationJustEnded is correct in StrictMode", () => {
+      const { result, rerender } = renderHook(
+        ({ value, retain }) => useOperationContinuity(value, retain),
+        {
+          initialProps: { value: "active", retain: true },
+          wrapper: StrictModeWrapper,
+        },
+      );
+
+      // During retention
+      expect(result.current.operationJustEnded).toBe(false);
+
+      // End retention - operationJustEnded should be true
+      rerender({ value: "active", retain: false });
+      expect(result.current.operationJustEnded).toBe(true);
+
+      // Next render - should be false again
+      rerender({ value: "active", retain: false });
+      expect(result.current.operationJustEnded).toBe(false);
+    });
+
+    it("over-swipe scenario works in StrictMode", () => {
+      // This is the exact scenario that was broken before the fix:
+      // User swipes beyond 100%, releases, and we need operationJustEnded=true
+      // to prevent the visual jump.
+      const { result, rerender } = renderHook(
+        ({ role, displacement }) => useOperationContinuity(role, displacement > 0),
+        {
+          initialProps: { role: "active" as const, displacement: 500 },
+          wrapper: StrictModeWrapper,
+        },
+      );
+
+      // During over-swipe
+      expect(result.current.value).toBe("active");
+      expect(result.current.operationJustEnded).toBe(false);
+
+      // Release (displacement becomes 0)
+      rerender({ role: "active" as const, displacement: 0 });
+
+      // CRITICAL: operationJustEnded must be true even in StrictMode
+      // This is what was broken before the fix
+      expect(result.current.operationJustEnded).toBe(true);
+      expect(result.current.value).toBe("active");
+    });
+
+    it("changedDuringOperation is tracked correctly in StrictMode", () => {
+      const { result, rerender } = renderHook(
+        ({ value, retain }) => useOperationContinuity(value, retain),
+        {
+          initialProps: { value: "behind", retain: true },
+          wrapper: StrictModeWrapper,
+        },
+      );
+
+      expect(result.current.changedDuringOperation).toBe(false);
+
+      // Value changes during retention
+      rerender({ value: "active", retain: true });
+      expect(result.current.changedDuringOperation).toBe(true);
+
+      // End retention
+      rerender({ value: "active", retain: false });
+      expect(result.current.changedDuringOperation).toBe(true);
+      expect(result.current.operationJustEnded).toBe(true);
+    });
+  });
+});