react-panel-layout 0.6.0 → 0.7.0

package/src/hooks/useOperationContinuity.spec.ts

@@ -0,0 +1,394 @@
+/**
+ * @file Tests for useOperationContinuity hook.
+ */
+import * as React from "react";
+import { renderHook } from "@testing-library/react";
+import { useOperationContinuity } from "./useOperationContinuity.js";
+
+type TestRole = "active" | "behind" | "hidden";
+
+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 }: { role: TestRole; displacement: number }) =>
+          useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "active" as TestRole, 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 }: { role: TestRole; displacement: number }) =>
+          useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "active" as TestRole, 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 }: { role: TestRole; displacement: number }) =>
+          useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "behind" as TestRole, 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 }: { role: TestRole; displacement: number }) =>
+          useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "active" as TestRole, 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 }: { role: TestRole; displacement: number }) =>
+          useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "behind" as TestRole, 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);
+    });
+  });
+});

package/src/hooks/useOperationContinuity.ts

@@ -0,0 +1,135 @@
+/**
+ * @file Hook for maintaining value continuity during continuous operations.
+ *
+ * During operations like swipe gestures, external state (navigation depth, panel roles)
+ * may change before the gesture ends. This hook provides a pattern to:
+ * - Retain the previous value during the operation for visual continuity
+ * - Accept the new value when the operation ends
+ * - Track whether the value changed during the operation
+ *
+ * This is a core primitive for the "operation continuity" pattern used throughout
+ * the swipe gesture system.
+ */
+import * as React from "react";
+
+/**
+ * Result from useOperationContinuity hook.
+ */
+export type UseOperationContinuityResult<T> = {
+  /** The effective value (retained during operation, current after) */
+  value: T;
+  /**
+   * True if the value changed during the operation.
+   *
+   * This is useful for determining how to handle the transition when the
+   * operation ends. For example, if the role changed during a swipe,
+   * the target position change at operation end should snap rather than animate.
+   *
+   * This flag is true on the render where shouldRetainPrevious becomes false
+   * (operation end), allowing consumers to handle the transition appropriately.
+   * It resets to false on subsequent renders.
+   */
+  changedDuringOperation: boolean;
+  /**
+   * True on the render where the operation just ended.
+   *
+   * This is true when shouldRetainPrevious transitions from true to false,
+   * regardless of whether the value changed. Use this to detect the moment
+   * when an operation completes and delay any immediate animations.
+   *
+   * In the over-swipe case, this helps prevent unwanted snap-back animation
+   * in the intermediate render before navigation changes.
+   */
+  operationJustEnded: boolean;
+};
+
+/**
+ * Hook for maintaining value continuity during continuous operations.
+ *
+ * When an operation is in progress, this hook retains the previous value
+ * to prevent sudden visual changes from state updates. Once the operation
+ * ends (shouldRetainPrevious becomes false), the new value is accepted.
+ *
+ * Additionally, this hook tracks whether the value changed during the operation,
+ * which is useful for determining animation behavior at operation end.
+ *
+ * IMPORTANT: This hook is designed to be idempotent during render to work
+ * correctly with React StrictMode, which calls the render function twice.
+ * All ref mutations happen in useLayoutEffect, not during render.
+ *
+ * @param value - The current value from external state
+ * @param shouldRetainPrevious - Whether to retain the previous value (true during operation)
+ * @returns Object with effective value and whether it changed during operation
+ *
+ * @example
+ * ```tsx
+ * // Maintain role continuity during swipe
+ * const { value: effectiveRole, changedDuringOperation } = useOperationContinuity(
+ *   role,
+ *   displacement > 0,
+ * );
+ *
+ * // Use changedDuringOperation to skip animation on operation end
+ * useSwipeContentTransform({
+ *   // ...
+ *   skipTargetChangeAnimation: changedDuringOperation,
+ * });
+ * ```
+ */
+export function useOperationContinuity<T>(
+  value: T,
+  shouldRetainPrevious: boolean,
+): UseOperationContinuityResult<T> {
+  // Store previous shouldRetainPrevious to detect transitions
+  const prevShouldRetainRef = React.useRef(shouldRetainPrevious);
+  // Store retained value (the value at the start of retention)
+  const retainedValueRef = React.useRef(value);
+  // Track if value changed during retention
+  const changedDuringRetentionRef = React.useRef(false);
+
+  // Derive operationJustEnded from transition: true → false
+  // This is idempotent - safe for StrictMode double-render
+  const wasRetaining = prevShouldRetainRef.current;
+  const operationJustEnded = wasRetaining ? !shouldRetainPrevious : false;
+
+  // Check if value diverged from retained value
+  // This includes both current-render divergence and previously-tracked divergence
+  const valueDiverged = value !== retainedValueRef.current;
+  const currentlyDiverged = shouldRetainPrevious ? valueDiverged : false;
+
+  // Derive changedDuringOperation
+  // True if:
+  // 1. Value diverged during retention (tracked from previous renders via ref)
+  // 2. Value diverges right now during retention (immediate comparison)
+  // 3. Value diverged at the moment retention ends
+  const changedDuringRetention = changedDuringRetentionRef.current ? true : currentlyDiverged;
+  const changedAtExit = operationJustEnded ? valueDiverged : false;
+  const changedDuringOperation = changedDuringRetention ? true : changedAtExit;
+
+  // Determine effective value
+  // During retention: use retained value
+  // After retention ends: use current value
+  const effectiveValue = shouldRetainPrevious ? retainedValueRef.current : value;
+
+  // Update refs in useLayoutEffect to ensure idempotency during render.
+  // This runs once per commit, not per render in StrictMode.
+  React.useLayoutEffect(() => {
+    if (!shouldRetainPrevious) {
+      // Retention ended or never started - reset state
+      changedDuringRetentionRef.current = false;
+      retainedValueRef.current = value;
+    } else {
+      // During retention - track if value diverged
+      if (currentlyDiverged) {
+        changedDuringRetentionRef.current = true;
+      }
+    }
+    prevShouldRetainRef.current = shouldRetainPrevious;
+  });
+
+  return {
+    value: effectiveValue,
+    changedDuringOperation,
+    operationJustEnded,
+  };
+}