react-panel-layout 0.5.2 → 0.6.1

package/src/hooks/useIntersectionObserver.tsx

@@ -0,0 +1,125 @@
+/**
+ * @file Shared useIntersectionObserver hook with cached observer instances.
+ */
+import * as React from "react";
+
+const createIdGenerator = () => {
+  const map = new Map<object, number>();
+  return (ref: object | null | undefined) => {
+    if (!ref) {
+      return undefined;
+    }
+    const existing = map.get(ref);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const nextId = map.size;
+    map.set(ref, nextId);
+    return nextId;
+  };
+};
+
+const getId = createIdGenerator();
+type Unobserve = () => void;
+type Callback = (entry: IntersectionObserverEntry) => void;
+type SharedObserver = {
+  observe: (target: Element, callback: Callback) => Unobserve;
+};
+const observerCache = new Map<string, SharedObserver>();
+const getSharedObserver = (options: IntersectionObserverInit) => {
+  const observerKey = `ovs-threshold:${options.threshold}-rootMargin:${options.rootMargin}-root:${getId(options.root)}`;
+
+  if (observerCache.has(observerKey)) {
+    return observerCache.get(observerKey)!;
+  }
+  const observer = new (class {
+    #callbackMap = new Map<Element, Callback>();
+    #intersectionObserver = new IntersectionObserver((entries) => {
+      entries.forEach((entry) => {
+        const callback = this.#callbackMap.get(entry.target);
+        if (callback) {
+          callback(entry);
+        }
+      });
+    }, options);
+    observe(target: Element, callback: Callback) {
+      this.#callbackMap.set(target, callback);
+      this.#intersectionObserver.observe(target);
+      return () => {
+        this.#callbackMap.delete(target);
+        this.#intersectionObserver.unobserve(target);
+      };
+    }
+  })();
+  observerCache.set(observerKey, observer);
+
+  return observer;
+};
+const voidClientRect = Object.freeze({
+  x: 0,
+  y: 0,
+  width: 0,
+  height: 0,
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+}) as DOMRectReadOnly;
+/**
+ * Observe intersection changes for a given element reference using shared observers.
+ *
+ * @param ref - Ref holding the element to observe.
+ * @param options - Intersection observer configuration.
+ * @returns Latest intersection entry snapshot with sensible defaults.
+ */
+export function useIntersectionObserver<T extends HTMLElement>(
+  ref: React.RefObject<T | null>,
+  { threshold = 0, rootMargin = "0px", root = null }: IntersectionObserverInit,
+): {
+  readonly boundingClientRect: DOMRectReadOnly;
+  readonly intersectionRatio: number;
+  readonly intersectionRect: DOMRectReadOnly;
+  readonly isIntersecting: boolean;
+  readonly rootBounds: DOMRectReadOnly | null;
+  readonly target: Element | null;
+  readonly time: DOMHighResTimeStamp;
+} {
+  const [intersection, setIntersection] = React.useState<IntersectionObserverEntry | null>(null);
+
+  React.useEffect(() => {
+    const target = ref.current;
+    if (!target) {
+      return;
+    }
+
+    const observer = getSharedObserver({
+      threshold,
+      rootMargin,
+      root,
+    });
+
+    return observer.observe(target, (entry) => {
+      setIntersection({
+        isIntersecting: entry.isIntersecting,
+        boundingClientRect: entry.boundingClientRect,
+        intersectionRatio: entry.intersectionRatio,
+        intersectionRect: entry.intersectionRect,
+        rootBounds: entry.rootBounds,
+        target: entry.target,
+        time: entry.time,
+      });
+    });
+  }, [ref, threshold, rootMargin, root]);
+
+  return React.useMemo(() => {
+    return {
+      isIntersecting: intersection?.isIntersecting ?? false,
+      boundingClientRect: intersection?.boundingClientRect ?? voidClientRect,
+      intersectionRatio: intersection?.intersectionRatio ?? 0,
+      intersectionRect: intersection?.intersectionRect ?? voidClientRect,
+      rootBounds: intersection?.rootBounds ?? null,
+      target: intersection?.target ?? ref.current,
+      time: intersection?.time ?? 0,
+    };
+  }, [intersection, ref]);
+}

package/src/hooks/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,29 @@
+/**
+ * @file useIsomorphicLayoutEffect - SSR-safe version of useLayoutEffect
+ *
+ * Uses useLayoutEffect on the client and useEffect on the server to avoid warnings
+ * during server-side rendering (e.g., with Next.js)
+ */
+import * as React from "react";
+
+/**
+ * Check if we're running in a browser environment
+ */
+const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
+
+/**
+ * SSR-safe version of useLayoutEffect
+ *
+ * - Client: Uses useLayoutEffect for synchronous layout updates
+ * - Server: Uses useEffect to avoid SSR warnings
+ *
+ * @example
+ * ```tsx
+ * useIsomorphicLayoutEffect(() => {
+ *   // This runs synchronously after DOM mutations on the client
+ *   // but safely falls back to useEffect on the server
+ *   measureElement();
+ * }, [deps]);
+ * ```
+ */
+export const useIsomorphicLayoutEffect = isBrowser ? React.useLayoutEffect : React.useEffect;

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);
+    });
+  });
+});

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;
+
+  // 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;
+
+  // 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 || currentlyDiverged;
+  const changedAtExit = operationJustEnded && valueDiverged;
+  const changedDuringOperation = changedDuringRetention || 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,
+  };
+}