react-panel-layout 0.6.0 → 0.6.1

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

package/src/hooks/useResizeObserver.spec.tsx

@@ -0,0 +1,277 @@
+/**
+ * @file Tests for useResizeObserver hook.
+ *
+ * These tests define the contract that useResizeObserver must fulfill.
+ * The key requirement is that consuming components can rely on containerSize
+ * being available when their animation logic runs.
+ */
+/* eslint-disable no-restricted-syntax -- Dynamic imports needed for isolated module testing */
+import { render, act } from "@testing-library/react";
+import * as React from "react";
+
+// We'll import the hook after defining what it should do
+// import { useResizeObserver } from "./useResizeObserver.js";
+
+/**
+ * Mock ResizeObserver
+ */
+class MockResizeObserver implements ResizeObserver {
+  private static instances: MockResizeObserver[] = [];
+  private callback: ResizeObserverCallback;
+  private observed = new Set<Element>();
+
+  static getInstances(): MockResizeObserver[] {
+    return this.instances;
+  }
+
+  static clearInstances(): void {
+    this.instances = [];
+  }
+
+  constructor(callback: ResizeObserverCallback) {
+    this.callback = callback;
+    MockResizeObserver.instances.push(this);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Required for interface compatibility
+  observe(target: Element, options?: ResizeObserverOptions): void {
+    this.observed.add(target);
+    // Real ResizeObserver fires callback asynchronously after observe
+    // We simulate immediate callback for testing
+    const entry = this.createEntry(target, 400, 300);
+    this.callback([entry], this);
+  }
+
+  unobserve(target: Element): void {
+    this.observed.delete(target);
+  }
+
+  disconnect(): void {
+    this.observed.clear();
+  }
+
+  triggerResize(target: Element, width: number, height: number): void {
+    if (this.observed.has(target)) {
+      const entry = this.createEntry(target, width, height);
+      this.callback([entry], this);
+    }
+  }
+
+  private createEntry(target: Element, width: number, height: number): ResizeObserverEntry {
+    return {
+      target,
+      contentRect: new DOMRect(0, 0, width, height),
+      borderBoxSize: [{ inlineSize: width, blockSize: height }],
+      contentBoxSize: [{ inlineSize: width, blockSize: height }],
+      devicePixelContentBoxSize: [],
+    };
+  }
+}
+
+const originalResizeObserver = globalThis.ResizeObserver;
+
+describe("useResizeObserver contract", () => {
+  beforeEach(() => {
+    MockResizeObserver.clearInstances();
+    globalThis.ResizeObserver = MockResizeObserver;
+
+    // Mock getBoundingClientRect
+    Element.prototype.getBoundingClientRect = function () {
+      return new DOMRect(0, 0, 400, 300);
+    };
+  });
+
+  afterEach(() => {
+    globalThis.ResizeObserver = originalResizeObserver;
+  });
+
+  describe("timing requirements", () => {
+    /**
+     * This is the critical test case.
+     *
+     * In the real use case (StackTablet -> SwipeStackContent):
+     * 1. StackTablet renders, calls useResizeObserver
+     * 2. StackTablet passes containerSize to SwipeStackContent
+     * 3. SwipeStackContent uses containerSize in its first useLayoutEffect
+     *
+     * The question: Can containerSize be > 0 when SwipeStackContent's
+     * useLayoutEffect runs for the first time?
+     *
+     * Answer: This depends on React's effect execution order.
+     * - Effects run in order of hook registration
+     * - Parent's effects run before children's effects? NO.
+     * - Actually, React runs effects bottom-up (children first, then parents)
+     *
+     * So when SwipeStackContent's useLayoutEffect runs:
+     * - It's the FIRST effect to run (child before parent)
+     * - useResizeObserver's useLayoutEffect hasn't run yet
+     * - Therefore containerSize is still 0
+     *
+     * This means we MUST handle containerSize=0 in SwipeStackContent.
+     * The question is: how to abstract this properly?
+     */
+    it("documents React effect execution order", () => {
+      const executionOrder: string[] = [];
+
+      const Child: React.FC<{ size: number }> = ({ size }) => {
+        React.useLayoutEffect(() => {
+          executionOrder.push(`child-layout-effect: size=${size}`);
+        }, []);
+
+        return <div>Child: {size}</div>;
+      };
+
+      const Parent: React.FC = () => {
+        const ref = React.useRef<HTMLDivElement>(null);
+        const [size, setSize] = React.useState(0);
+
+        React.useLayoutEffect(() => {
+          executionOrder.push("parent-layout-effect: measuring");
+          if (ref.current) {
+            setSize(ref.current.getBoundingClientRect().width);
+          }
+        }, []);
+
+        executionOrder.push(`parent-render: size=${size}`);
+
+        return (
+          <div ref={ref}>
+            <Child size={size} />
+          </div>
+        );
+      };
+
+      render(<Parent />);
+
+      // This documents the actual execution order
+      // Parent renders first with size=0
+      // Child renders with size=0
+      // Child's useLayoutEffect runs (sees size=0)
+      // Parent's useLayoutEffect runs (sets size=400)
+      // Re-render with size=400
+      expect(executionOrder).toContain("child-layout-effect: size=0");
+    });
+
+    /**
+     * Given the above, the proper abstraction is:
+     *
+     * useResizeObserver should provide a way for consumers to know
+     * when the size is "ready" (first valid measurement complete).
+     *
+     * Consumers that depend on size for animation should:
+     * - Not start animation until size is ready
+     * - OR use a hook that handles this internally
+     */
+    it("should indicate when size is ready", async () => {
+      // Import dynamically to test the implementation
+      const { useResizeObserver } = await import("./useResizeObserver.js");
+
+      const results: Array<{ width: number; isReady: boolean }> = [];
+
+      const TestComponent: React.FC = () => {
+        const ref = React.useRef<HTMLDivElement>(null);
+        const { rect } = useResizeObserver(ref, { box: "border-box" });
+
+        const width = rect?.width ?? 0;
+        const isReady = rect !== null;
+
+        React.useEffect(() => {
+          results.push({ width, isReady });
+        }, [width, isReady]);
+
+        return <div ref={ref} style={{ width: 400, height: 300 }} />;
+      };
+
+      render(<TestComponent />);
+
+      // After effects run, size should be available
+      await act(async () => {});
+
+      const lastResult = results[results.length - 1];
+      expect(lastResult.isReady).toBe(true);
+      expect(lastResult.width).toBe(400);
+    });
+  });
+
+  describe("memory efficiency", () => {
+    it("shares ResizeObserver instances for same box option", async () => {
+      const { useResizeObserver, clearObserverCache } = await import("./useResizeObserver.js");
+      clearObserverCache();
+      MockResizeObserver.clearInstances();
+
+      const TestComponent: React.FC = () => {
+        const ref1 = React.useRef<HTMLDivElement>(null);
+        const ref2 = React.useRef<HTMLDivElement>(null);
+        const ref3 = React.useRef<HTMLDivElement>(null);
+
+        useResizeObserver(ref1, { box: "border-box" });
+        useResizeObserver(ref2, { box: "border-box" });
+        useResizeObserver(ref3, { box: "border-box" });
+
+        return (
+          <>
+            <div ref={ref1} />
+            <div ref={ref2} />
+            <div ref={ref3} />
+          </>
+        );
+      };
+
+      render(<TestComponent />);
+
+      expect(MockResizeObserver.getInstances().length).toBe(1);
+    });
+  });
+
+  describe("resize updates", () => {
+    it("updates when element size changes", async () => {
+      const { useResizeObserver, clearObserverCache } = await import("./useResizeObserver.js");
+      clearObserverCache();
+      MockResizeObserver.clearInstances();
+
+      const widths: number[] = [];
+
+      const TestComponent: React.FC = () => {
+        const ref = React.useRef<HTMLDivElement>(null);
+        const { rect } = useResizeObserver(ref, { box: "border-box" });
+
+        React.useEffect(() => {
+          if (rect) {
+            widths.push(rect.width);
+          }
+        }, [rect]);
+
+        return <div ref={ref} data-testid="target" />;
+      };
+
+      const { getByTestId } = render(<TestComponent />);
+
+      await act(async () => {});
+
+      const element = getByTestId("target");
+      const observer = MockResizeObserver.getInstances()[0];
+
+      act(() => {
+        observer.triggerResize(element, 800, 600);
+      });
+
+      expect(widths).toContain(400); // Initial
+      expect(widths).toContain(800); // After resize
+    });
+  });
+});
+
+/**
+ * Based on the tests above, the conclusion is:
+ *
+ * 1. React's effect execution order means child effects run before parent effects
+ * 2. Therefore, on first render, child components will see containerSize=0
+ * 3. This is a fundamental React constraint, not a bug in useResizeObserver
+ *
+ * The proper abstraction for SwipeStackContent is:
+ * - Check if containerSize > 0 before consuming isFirstMount
+ * - This is NOT a workaround, it's the correct pattern for this React constraint
+ *
+ * Alternatively, create a higher-level hook like useAnimatedStack that
+ * encapsulates both the size observation and the "ready" state.
+ */

package/src/hooks/useResizeObserver.tsx

@@ -1,80 +1,149 @@
 /**
  * @file Shared useResizeObserver hook with cached observer instances.
+ *
+ * Provides element size observation with shared observers for memory efficiency.
+ * Size becomes available after the first useLayoutEffect cycle completes.
+ *
+ * Note: Due to React's effect execution order (children before parents),
+ * child components may see containerSize=0 on their first effect run.
+ * This is a React constraint, not a bug. Consumers should check for
+ * valid size before using it for calculations like animation positions.
  */
 import * as React from "react";
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
 
-type Unobserve = () => void;
-type Callback = (entry: ResizeObserverEntry, observer: ResizeObserver) => void;
+/**
+ * Shared ResizeObserver that can observe multiple elements.
+ */
 type SharedObserver = {
-  observe: (target: Element, callback: Callback) => Unobserve;
+  observe: (target: Element, callback: (entry: ResizeObserverEntry) => void) => () => void;
 };
+
+/** Cache of shared observers per box option */
 const observerCache = new Map<string, SharedObserver>();
-const getSharedObserver = (options: ResizeObserverOptions) => {
-  const { box = "content-box" } = options;
+
+/**
+ * Get or create a shared ResizeObserver for the given box option.
+ */
+const getSharedObserver = (box: ResizeObserverBoxOptions): SharedObserver => {
   const observerKey = `resize-box:${box}`;
   const cached = observerCache.get(observerKey);
   if (cached) {
     return cached;
   }
-  const observer = new (class {
-    #callbackMap = new Map<Element, Callback>();
-    #resizeObserver = new ResizeObserver((entries, observer) => {
-      entries.forEach((entry) => {
-        const callback = this.#callbackMap.get(entry.target);
-        if (callback) {
-          callback(entry, observer);
-        }
-      });
-    });
-    observe(target: Element, callback: Callback) {
-      this.#callbackMap.set(target, callback);
-      this.#resizeObserver.observe(target, options);
+
+  const callbacks = new Map<Element, (entry: ResizeObserverEntry) => void>();
+
+  const resizeObserver = new ResizeObserver((entries) => {
+    for (const entry of entries) {
+      const callback = callbacks.get(entry.target);
+      if (callback) {
+        callback(entry);
+      }
+    }
+  });
+
+  const sharedObserver: SharedObserver = {
+    observe(target, callback) {
+      callbacks.set(target, callback);
+      resizeObserver.observe(target, { box });
+
       return () => {
-        this.#callbackMap.delete(target);
-        this.#resizeObserver.unobserve(target);
+        callbacks.delete(target);
+        resizeObserver.unobserve(target);
       };
-    }
-  })();
-  observerCache.set(observerKey, observer);
+    },
+  };
+
+  observerCache.set(observerKey, sharedObserver);
+  return sharedObserver;
+};
+
+/**
+ * Create a ResizeObserverEntry from getBoundingClientRect.
+ */
+const measureElement = (target: Element): ResizeObserverEntry => {
+  const rect = target.getBoundingClientRect();
+  return {
+    target,
+    contentRect: rect,
+    borderBoxSize: [{ inlineSize: rect.width, blockSize: rect.height }],
+    contentBoxSize: [{ inlineSize: rect.width, blockSize: rect.height }],
+    devicePixelContentBoxSize: [],
+  };
+};
 
-  return observer;
+/**
+ * Extract DOMRect from ResizeObserverEntry.
+ */
+const entryToRect = (entry: ResizeObserverEntry): DOMRect => {
+  if (entry.borderBoxSize?.length > 0) {
+    const size = entry.borderBoxSize[0];
+    return new DOMRect(0, 0, size.inlineSize, size.blockSize);
+  }
+  return entry.contentRect;
 };
+
+/**
+ * Clear observer cache. Exported for testing purposes.
+ */
+export function clearObserverCache(): void {
+  observerCache.clear();
+}
+
 /**
  * Observe size changes for a given element reference using shared resize observers.
  *
  * @param ref - Ref holding the element whose size to monitor.
  * @param options - Resize observer configuration.
  * @returns Latest resize entry and a derived DOMRect snapshot.
+ *
+ * @remarks
+ * The `rect` will be `null` on the first render. After the initial
+ * useLayoutEffect runs and triggers a re-render, `rect` will contain
+ * the measured size.
+ *
+ * Due to React's effect execution order, child components' effects run
+ * before parent effects. If you pass `rect.width` to a child as a prop,
+ * the child's first effect will see `0` (or whatever default you use).
+ * This is expected React behavior.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const { rect } = useResizeObserver(containerRef, { box: "border-box" });
+ * const width = rect?.width ?? 0;
+ *
+ * // Check if size is ready before using for calculations
+ * const isReady = rect !== null;
+ * ```
  */
 export function useResizeObserver<T extends HTMLElement>(
   ref: React.RefObject<T | null>,
-  { box }: ResizeObserverOptions,
+  { box = "content-box" }: ResizeObserverOptions,
 ) {
   const [entry, setEntry] = React.useState<ResizeObserverEntry | null>(null);
-  const target = ref.current;
 
-  React.useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
+    const target = ref.current;
     if (!target) {
+      setEntry(null);
       return;
     }
 
-    const observer = getSharedObserver({ box });
-    return observer.observe(target, (nextEntry) => {
-      setEntry(nextEntry);
-    });
-  }, [box, target]);
+    // Measure immediately
+    setEntry(measureElement(target));
+
+    // Set up ResizeObserver for subsequent updates
+    const observer = getSharedObserver(box);
+    return observer.observe(target, setEntry);
+  }, [ref, box]);
 
   const rect = React.useMemo(() => {
     if (!entry) {
       return null;
     }
-
-    if (entry.borderBoxSize?.length > 0) {
-      const size = entry.borderBoxSize[0];
-      return new DOMRect(0, 0, size.inlineSize, size.blockSize);
-    }
-
-    return entry.contentRect;
+    return entryToRect(entry);
   }, [entry]);
 
   return { entry, rect };

package/src/hooks/useScrollContainer.ts

@@ -5,6 +5,7 @@
  * Returns null if the document is the scroll container.
  */
 import * as React from "react";
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect";
 
 /**
  * Check if an element is a scroll container.
@@ -14,12 +15,7 @@ function isScrollContainer(element: Element): boolean {
   const overflowY = style.overflowY;
   const overflowX = style.overflowX;
 
-  return (
-    overflowY === "scroll" ||
-    overflowY === "auto" ||
-    overflowX === "scroll" ||
-    overflowX === "auto"
-  );
+  return overflowY === "scroll" || overflowY === "auto" || overflowX === "scroll" || overflowX === "auto";
 }
 
 /**
@@ -59,12 +55,10 @@ function findScrollContainer(element: Element | null): HTMLElement | null {
  * // scrollContainer is HTMLElement if in nested scroll, null if document scroll
  * ```
  */
-export function useScrollContainer<T extends HTMLElement>(
-  ref: React.RefObject<T | null>,
-): HTMLElement | null {
+export function useScrollContainer<T extends HTMLElement>(ref: React.RefObject<T | null>): HTMLElement | null {
   const [container, setContainer] = React.useState<HTMLElement | null>(null);
 
-  React.useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     const element = ref.current;
     if (!element) {
       setContainer(null);