react-panel-layout 0.5.2 → 0.6.0

package/src/modules/pivot/usePivotSwipeInput.ts

@@ -0,0 +1,136 @@
+/**
+ * @file Hook for binding swipe input to Pivot navigation.
+ *
+ * This hook connects swipe gesture detection to Pivot's navigation API,
+ * translating swipe gestures into go(-1) and go(1) calls.
+ *
+ * Supports both:
+ * - Touch/pointer swipe gestures
+ * - Trackpad two-finger swipe (wheel events)
+ */
+import * as React from "react";
+import { useSwipeInput } from "../../hooks/gesture/useSwipeInput.js";
+import { useNativeGestureGuard } from "../../hooks/gesture/useNativeGestureGuard.js";
+import { mergeGestureContainerProps } from "../../hooks/gesture/utils.js";
+import type { SwipeInputState, SwipeInputThresholds, GestureAxis } from "../../hooks/gesture/types.js";
+import type { UsePivotResult } from "./types.js";
+
+/**
+ * Options for usePivotSwipeInput hook.
+ */
+export type UsePivotSwipeInputOptions = {
+  /** Reference to the swipe container element */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Pivot navigation result from usePivot */
+  pivot: Pick<UsePivotResult, "go" | "canGo">;
+  /** Axis for swipe detection. @default "horizontal" */
+  axis?: GestureAxis;
+  /** Whether swipe input is enabled. @default true */
+  enabled?: boolean;
+  /** Custom swipe thresholds */
+  thresholds?: Partial<SwipeInputThresholds>;
+  /** Whether to enable trackpad wheel swipe. @default true */
+  enableWheelSwipe?: boolean;
+};
+
+/**
+ * Result from usePivotSwipeInput hook.
+ */
+export type UsePivotSwipeInputResult = {
+  /** Current swipe input state */
+  inputState: SwipeInputState;
+  /** Props to spread on the container element */
+  containerProps: React.HTMLAttributes<HTMLElement> & {
+    style: React.CSSProperties;
+  };
+};
+
+/**
+ * Hook for binding swipe input to Pivot navigation.
+ *
+ * Detects horizontal swipe gestures and triggers navigation:
+ * - Swipe left (direction -1) → go(1) (next)
+ * - Swipe right (direction 1) → go(-1) (prev)
+ *
+ * Note: The direction mapping is inverted because swiping left reveals the next item,
+ * similar to how carousel/swipe navigation works in iOS.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const pivot = usePivot({ items });
+ * const { inputState, containerProps } = usePivotSwipeInput({
+ *   containerRef,
+ *   pivot,
+ * });
+ *
+ * return (
+ *   <div ref={containerRef} {...containerProps}>
+ *     <pivot.Outlet />
+ *   </div>
+ * );
+ * ```
+ */
+export function usePivotSwipeInput(options: UsePivotSwipeInputOptions): UsePivotSwipeInputResult {
+  const {
+    containerRef,
+    pivot,
+    axis = "horizontal",
+    enabled = true,
+    thresholds,
+    enableWheelSwipe = true,
+  } = options;
+
+  // Track if swiping is active for native gesture guard
+  const [isSwipeActive, setIsSwipeActive] = React.useState(false);
+
+  // Handle swipe completion
+  const handleSwipeEnd = React.useCallback(
+    (state: SwipeInputState) => {
+      setIsSwipeActive(false);
+
+      // Invert direction: swipe left (-1) → next (go(1)), swipe right (1) → prev (go(-1))
+      const navigationDirection = -state.direction;
+
+      if (navigationDirection !== 0 && pivot.canGo(navigationDirection)) {
+        pivot.go(navigationDirection);
+      }
+    },
+    [pivot],
+  );
+
+  // Use swipe input detection (handles both pointer and wheel)
+  const { state: inputState, containerProps: swipeProps } = useSwipeInput({
+    containerRef,
+    axis,
+    enabled,
+    thresholds,
+    onSwipeEnd: handleSwipeEnd,
+    enableWheel: enableWheelSwipe,
+  });
+
+  // Update swipe active state
+  React.useEffect(() => {
+    const isActive = inputState.phase === "swiping" || inputState.phase === "tracking";
+    setIsSwipeActive(isActive);
+  }, [inputState.phase]);
+
+  // Use native gesture guard when swiping
+  const { containerProps: guardProps } = useNativeGestureGuard({
+    containerRef,
+    active: isSwipeActive,
+    preventEdgeBack: true,
+    preventOverscroll: true,
+  });
+
+  // Merge container props
+  const containerProps = React.useMemo(
+    () => mergeGestureContainerProps(swipeProps, guardProps),
+    [swipeProps, guardProps],
+  );
+
+  return {
+    inputState,
+    containerProps,
+  };
+}

package/src/modules/resizer/useResizeDrag.ts

@@ -0,0 +1,94 @@
+/**
+ * @file Shared logic for draggable resize handles.
+ */
+import * as React from "react";
+import { useDragPointerEvents } from "../../hooks/useDocumentPointerEvents";
+import { useEffectEvent } from "../../hooks/useEffectEvent";
+
+export type ResizeDragAxis = "x" | "y";
+
+export type UseResizeDragOptions = {
+  /** Axis along which the drag should compute deltas */
+  axis: ResizeDragAxis;
+  /** Callback invoked with the delta value when dragging */
+  onResize?: (delta: number) => void;
+};
+
+export type UseResizeDragResult<TElement extends HTMLElement> = {
+  /** Ref to attach to the draggable element */
+  ref: React.RefObject<TElement | null>;
+  /** Pointer down handler to initiate dragging */
+  onPointerDown: (event: React.PointerEvent<TElement>) => void;
+  /** Whether a drag interaction is currently active */
+  isDragging: boolean;
+};
+
+/**
+ * Provides unified pointer handling for resize-capable UI elements.
+ *
+ * @param options - Configuration for the drag interaction.
+ * @returns Handlers and state for wiring into a draggable element.
+ */
+export const useResizeDrag = <TElement extends HTMLElement = HTMLElement>(
+  options: UseResizeDragOptions,
+): UseResizeDragResult<TElement> => {
+  const elementRef = React.useRef<TElement | null>(null);
+  const pointerIdRef = React.useRef<number | null>(null);
+  const previousCoordinateRef = React.useRef<number>(0);
+  const [isDragging, setIsDragging] = React.useState(false);
+
+  const emitResize = useEffectEvent((delta: number) => {
+    options.onResize?.(delta);
+  });
+
+  const getCoordinate = React.useCallback(
+    (event: PointerEvent | React.PointerEvent) => {
+      return options.axis === "x" ? event.clientX : event.clientY;
+    },
+    [options.axis],
+  );
+
+  const handlePointerDown = React.useCallback(
+    (event: React.PointerEvent<TElement>) => {
+      event.preventDefault();
+      elementRef.current = event.currentTarget;
+      pointerIdRef.current = event.pointerId;
+      previousCoordinateRef.current = getCoordinate(event);
+      setIsDragging(true);
+    },
+    [getCoordinate],
+  );
+
+  const handlePointerMove = React.useCallback(
+    (event: PointerEvent) => {
+      const coordinate = getCoordinate(event);
+      const delta = coordinate - previousCoordinateRef.current;
+      if (delta === 0) {
+        return;
+      }
+      previousCoordinateRef.current = coordinate;
+      emitResize(delta);
+    },
+    [getCoordinate, emitResize],
+  );
+
+  const handlePointerUp = React.useCallback(() => {
+    setIsDragging(false);
+    pointerIdRef.current = null;
+  }, []);
+
+  useDragPointerEvents(elementRef as React.RefObject<HTMLElement | null>, isDragging, {
+    onMove: handlePointerMove,
+    onUp: handlePointerUp,
+    pointerId: pointerIdRef.current ?? undefined,
+    capturePointer: true,
+    preventDefaults: false,
+  });
+
+  return {
+    ref: elementRef,
+    onPointerDown: handlePointerDown,
+    isDragging,
+  };
+};
+

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

@@ -0,0 +1,264 @@
+/**
+ * @file Tests for StackContent component - animation behavior.
+ *
+ * TDD: Tests to reproduce and prevent animation restart issues in production builds.
+ */
+import { render, screen } from "@testing-library/react";
+import * as React from "react";
+import { StackContent } from "./StackContent.js";
+import { STACK_ANIMATION_PUSH, STACK_ANIMATION_POP } from "../../constants/styles.js";
+import type { StackNavigationState } from "./types.js";
+
+describe("StackContent", () => {
+  const createNavigationState = (depth: number): StackNavigationState => ({
+    stack: depth === 0 ? ["root"] : depth === 1 ? ["root", "detail"] : ["root", "detail", "edit"],
+    depth,
+    isRevealing: false,
+    revealDepth: null,
+  });
+
+  describe("push animation (becoming active)", () => {
+    it("applies push animation when becoming active", () => {
+      const { rerender } = render(
+        <StackContent
+          id="panel"
+          depth={1}
+          isActive={false}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(0)}
+        >
+          <div data-testid="content">Content</div>
+        </StackContent>,
+      );
+
+      // Panel becomes active (pushed onto stack)
+      rerender(
+        <StackContent
+          id="panel"
+          depth={1}
+          isActive={true}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(1)}
+        >
+          <div data-testid="content">Content</div>
+        </StackContent>,
+      );
+
+      const wrapper = screen.getByTestId("content").parentElement;
+      expect(wrapper?.style?.animation).toBe(STACK_ANIMATION_PUSH);
+    });
+  });
+
+  describe("pop animation (becoming inactive)", () => {
+    it("applies pop animation when becoming inactive", () => {
+      const { rerender } = render(
+        <StackContent
+          id="panel"
+          depth={1}
+          isActive={true}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(1)}
+        >
+          <div data-testid="content">Content</div>
+        </StackContent>,
+      );
+
+      // Panel becomes inactive (popped from stack)
+      rerender(
+        <StackContent
+          id="panel"
+          depth={1}
+          isActive={false}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(0)}
+        >
+          <div data-testid="content">Content</div>
+        </StackContent>,
+      );
+
+      const wrapper = screen.getByTestId("content").parentElement;
+      expect(wrapper?.style?.animation).toBe(STACK_ANIMATION_POP);
+    });
+
+    it("keeps panel visible during pop animation", () => {
+      // Panel must remain visible during pop animation, otherwise animation won't be seen
+      const { rerender } = render(
+        <StackContent
+          id="panel"
+          depth={1}
+          isActive={true}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(1)}
+        >
+          <div data-testid="content">Content</div>
+        </StackContent>,
+      );
+
+      // Panel becomes inactive (pop)
+      rerender(
+        <StackContent
+          id="panel"
+          depth={1}
+          isActive={false}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(0)}
+        >
+          <div data-testid="content">Content</div>
+        </StackContent>,
+      );
+
+      const wrapper = screen.getByTestId("content").parentElement;
+      expect(wrapper?.style?.visibility).toBe("visible");
+    });
+  });
+
+  describe("no animation when transitionMode=none", () => {
+    it("does not apply animation property", () => {
+      render(
+        <StackContent
+          id="panel"
+          depth={0}
+          isActive={true}
+          displayMode="overlay"
+          transitionMode="none"
+          navigationState={createNavigationState(0)}
+        >
+          <div data-testid="content">Content</div>
+        </StackContent>,
+      );
+
+      const wrapper = screen.getByTestId("content").parentElement;
+      expect(wrapper?.style?.animation).toBeFalsy();
+    });
+  });
+
+  describe("initial mount behavior (production animation issue)", () => {
+    it("does NOT apply push animation on initial mount when isActive=true", () => {
+      // No animation should be applied on initial mount
+      render(
+        <StackContent
+          id="panel"
+          depth={0}
+          isActive={true}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(0)}
+        >
+          <div data-testid="content">Content</div>
+        </StackContent>,
+      );
+
+      const wrapper = screen.getByTestId("content").parentElement;
+      expect(wrapper?.style?.animation).toBeFalsy();
+    });
+
+    it("does NOT re-trigger animation when parent re-renders without isActive change", () => {
+      // Animation should not be re-triggered when isActive remains unchanged
+      const { rerender } = render(
+        <StackContent
+          id="panel"
+          depth={0}
+          isActive={true}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(0)}
+        >
+          <div data-testid="content">Content</div>
+        </StackContent>,
+      );
+
+      const wrapper = screen.getByTestId("content").parentElement;
+      expect(wrapper?.style?.animation).toBeFalsy();
+
+      // Parent re-renders (e.g., containerWidth update), isActive unchanged
+      rerender(
+        <StackContent
+          id="panel"
+          depth={0}
+          isActive={true}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(0)}
+        >
+          <div data-testid="content">Updated Content</div>
+        </StackContent>,
+      );
+
+      expect(wrapper?.style?.animation).toBeFalsy();
+    });
+
+    it("does NOT apply animation for inactive panel on initial mount", () => {
+      render(
+        <StackContent
+          id="panel"
+          depth={1}
+          isActive={false}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(0)}
+        >
+          <div data-testid="content">Content</div>
+        </StackContent>,
+      );
+
+      const wrapper = screen.getByTestId("content").parentElement;
+      expect(wrapper?.style?.animation).toBeFalsy();
+    });
+  });
+
+  describe("animation stability during re-renders", () => {
+    it("should maintain animation value during re-renders when animating", () => {
+      const { rerender } = render(
+        <StackContent
+          id="panel"
+          depth={1}
+          isActive={false}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(0)}
+        >
+          <div data-testid="content">Content</div>
+        </StackContent>,
+      );
+
+      // pushでアクティブになる
+      rerender(
+        <StackContent
+          id="panel"
+          depth={1}
+          isActive={true}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(1)}
+        >
+          <div data-testid="content">Content</div>
+        </StackContent>,
+      );
+
+      const wrapper = screen.getByTestId("content").parentElement;
+      expect(wrapper?.style?.animation).toBe(STACK_ANIMATION_PUSH);
+
+      // Animation value should be maintained after re-render
+      rerender(
+        <StackContent
+          id="panel"
+          depth={1}
+          isActive={true}
+          displayMode="overlay"
+          transitionMode="css"
+          navigationState={createNavigationState(1)}
+        >
+          <div data-testid="content">Updated</div>
+        </StackContent>,
+      );
+
+      expect(wrapper?.style?.animation).toBe(STACK_ANIMATION_PUSH);
+    });
+  });
+});

package/src/modules/stack/StackContent.tsx

@@ -0,0 +1,111 @@
+/**
+ * @file StackContent component for rendering stack panels with animations.
+ *
+ * Override via CSS custom properties:
+ * - --rpl-stack-animation-push: Animation when panel is pushed
+ * - --rpl-stack-animation-pop: Animation when panel is popped
+ * - --rpl-stack-transition-duration: Duration of transitions
+ * - --rpl-stack-transition-easing: Easing for transitions
+ */
+import * as React from "react";
+import type { StackContentProps } from "./types.js";
+import { computeStackContentState } from "./computeStackContentState.js";
+import type { StackAnimationType } from "./computeStackContentState.js";
+import { useIsomorphicLayoutEffect } from "../../hooks/useIsomorphicLayoutEffect.js";
+
+const baseStyle: React.CSSProperties = {
+  position: "absolute",
+  inset: 0,
+  width: "100%",
+  height: "100%",
+};
+
+/**
+ * Renders a stack panel with appropriate animation based on display mode.
+ */
+export const StackContent: React.FC<StackContentProps> = React.memo(
+  ({ id, depth, isActive, displayMode, transitionMode, navigationState, swipeProgress, children }) => {
+    const ref = React.useRef<HTMLDivElement>(null);
+    const prevActiveRef = React.useRef(isActive);
+
+    // Track current animation type
+    const [animationType, setAnimationType] = React.useState<StackAnimationType>(null);
+
+    // Compute state using pure function
+    const computedState = computeStackContentState({
+      depth,
+      isActive,
+      wasActive: prevActiveRef.current,
+      currentAnimationType: animationType,
+      displayMode,
+      transitionMode,
+      navigationState,
+      swipeProgress,
+    });
+
+    // Update animation type synchronously before paint
+    useIsomorphicLayoutEffect(() => {
+      const wasActive = prevActiveRef.current;
+      prevActiveRef.current = isActive;
+
+      if (wasActive !== isActive) {
+        setAnimationType(computedState.nextAnimationType);
+      }
+    }, [isActive, computedState.nextAnimationType]);
+
+    // Clear animation type after animation ends
+    // Only handle animation end for this element (not bubbled from children)
+    const handleAnimationEnd = React.useCallback((e: React.AnimationEvent) => {
+      if (e.target === e.currentTarget) {
+        setAnimationType(null);
+      }
+    }, []);
+
+    // Build style from computed state
+    const style = React.useMemo<React.CSSProperties>(() => {
+      const s: React.CSSProperties = {
+        ...baseStyle,
+        transform: computedState.transform,
+        pointerEvents: computedState.pointerEvents,
+        zIndex: computedState.zIndex,
+        visibility: computedState.visibility,
+      };
+
+      if (computedState.animation !== undefined) {
+        s.animation = computedState.animation;
+      }
+
+      if (computedState.transition !== undefined) {
+        s.transition = computedState.transition;
+      }
+
+      return s;
+    }, [
+      computedState.transform,
+      computedState.pointerEvents,
+      computedState.zIndex,
+      computedState.visibility,
+      computedState.animation,
+      computedState.transition,
+    ]);
+
+    const content = (
+      <div
+        ref={ref}
+        data-stack-content={id}
+        data-depth={depth}
+        data-active={isActive ? "true" : "false"}
+        style={style}
+        onAnimationEnd={handleAnimationEnd}
+      >
+        {children}
+      </div>
+    );
+
+    if (transitionMode === "none") {
+      return <React.Activity mode={isActive ? "visible" : "hidden"}>{content}</React.Activity>;
+    }
+
+    return content;
+  },
+);