react-panel-layout 0.6.1 → 0.7.1

package/src/hooks/gesture/useNativeGestureGuard.spec.ts

@@ -12,13 +12,21 @@ type TestPointerEvent = React.PointerEvent<HTMLElement> & {
   wasDefaultPrevented: () => boolean;
 };
 
+/**
+ * Create a mock view for test events.
+ */
+function createMockView(): React.PointerEvent<HTMLElement>["view"] {
+  // eslint-disable-next-line custom/no-as-outside-guard -- test helper for view casting
+  return window as unknown as React.PointerEvent<HTMLElement>["view"];
+}
+
 /**
  * Creates a mock PointerEvent that satisfies the React.PointerEvent interface.
  */
 function createMockPointerEvent(props: {
   clientX: number;
   clientY: number;
-  pointerType: string;
+  pointerType: "mouse" | "touch" | "pen";
 }): TestPointerEvent {
   const noop = (): void => {};
   const noopBool = (): boolean => false;
@@ -82,7 +90,7 @@ function createMockPointerEvent(props: {
     width: 1,
     // UIEvent properties
     detail: 0,
-    view: window,
+    view: createMockView(),
   };
 }
 

package/src/hooks/gesture/useSwipeInput.spec.ts

@@ -426,6 +426,75 @@ describe("useSwipeInput", () => {
     });
   });
 
+  describe("touch event cleanup on unmount", () => {
+    it("removes touchmove listener when unmounted during active touch", () => {
+      const containerRef = createRef();
+      const removeSpy = vi.spyOn(document, "removeEventListener");
+
+      const { unmount } = renderHook(() =>
+        useSwipeInput({ containerRef, axis: "horizontal" }),
+      );
+
+      // Simulate touchstart to add the touchmove listener
+      const touchStartEvent = new TouchEvent("touchstart", {
+        touches: [{ clientX: 100, clientY: 100, identifier: 1 } as Touch],
+        bubbles: true,
+        cancelable: true,
+      });
+      containerRef.current!.dispatchEvent(touchStartEvent);
+
+      // Unmount WITHOUT triggering touchend
+      unmount();
+
+      // Verify touchmove listener was removed during cleanup
+      const touchMoveRemoveCalls = removeSpy.mock.calls.filter(
+        (call) => call[0] === "touchmove",
+      );
+      expect(touchMoveRemoveCalls.length).toBeGreaterThanOrEqual(1);
+
+      removeSpy.mockRestore();
+    });
+
+    it("touch scroll should work after component unmount", () => {
+      const containerRef = createRef();
+
+      const { unmount } = renderHook(() =>
+        useSwipeInput({ containerRef, axis: "horizontal" }),
+      );
+
+      // Simulate touchstart
+      const touchStartEvent = new TouchEvent("touchstart", {
+        touches: [{ clientX: 100, clientY: 100, identifier: 1 } as Touch],
+        bubbles: true,
+        cancelable: true,
+      });
+      containerRef.current!.dispatchEvent(touchStartEvent);
+
+      // Unmount without touchend (simulates navigation during touch)
+      unmount();
+
+      // After unmount, touchmove should NOT be prevented
+      // Create a new touchmove event and verify it's not prevented
+      let wasDefaultPrevented = false;
+      const touchMoveEvent = new TouchEvent("touchmove", {
+        touches: [{ clientX: 150, clientY: 100, identifier: 1 } as Touch],
+        bubbles: true,
+        cancelable: true,
+      });
+
+      // Add a listener to check if default was prevented
+      const checkListener = (e: Event) => {
+        wasDefaultPrevented = e.defaultPrevented;
+      };
+      document.addEventListener("touchmove", checkListener);
+      document.dispatchEvent(touchMoveEvent);
+      document.removeEventListener("touchmove", checkListener);
+
+      // The touchmove should NOT be prevented after unmount
+      expect(wasDefaultPrevented).toBe(false);
+    });
+  });
+
   describe("wheel swipe (trackpad two-finger swipe)", () => {
     const createContainerRef = (): React.RefObject<HTMLDivElement> => {
       const element = document.createElement("div");

package/src/hooks/gesture/useSwipeInput.ts

@@ -139,6 +139,8 @@ export function useSwipeInput(options: UseSwipeInputOptions): UseSwipeInputResul
       container.removeEventListener("touchstart", handleTouchStart);
       document.removeEventListener("touchend", handleTouchEnd);
       document.removeEventListener("touchcancel", handleTouchEnd);
+      // Must also remove disableTouchMove in case unmount happens during active touch
+      document.removeEventListener("touchmove", disableTouchMove);
     };
   }, [containerRef, enabled]);
 

package/src/hooks/gesture/utils.ts

@@ -90,6 +90,16 @@ export const mergeGestureContainerProps = (
 // Scroll Detection Utilities
 // ============================================================================
 
+/**
+ * Compute scroll size for an element based on axis.
+ */
+function computeScrollSize(element: HTMLElement, isHorizontal: boolean): number {
+  if (isHorizontal) {
+    return element.scrollWidth - element.clientWidth;
+  }
+  return element.scrollHeight - element.clientHeight;
+}
+
 /**
  * Check if an element is scrollable in any direction.
  */
@@ -104,7 +114,10 @@ export function isScrollableElement(element: HTMLElement): boolean {
     (style.overflowY === "scroll" || style.overflowY === "auto") &&
     element.scrollHeight > element.clientHeight;
 
-  return isScrollableX || isScrollableY;
+  if (isScrollableX) {
+    return true;
+  }
+  return isScrollableY;
 }
 
 /**
@@ -154,9 +167,7 @@ export function isScrollableInDirection(
     const isScrollable = overflow === "scroll" || overflow === "auto";
 
     if (isScrollable) {
-      const scrollSize = isHorizontal
-        ? current.scrollWidth - current.clientWidth
-        : current.scrollHeight - current.clientHeight;
+      const scrollSize = computeScrollSize(current, isHorizontal);
 
       if (scrollSize > 0) {
         const scrollPos = isHorizontal ? current.scrollLeft : current.scrollTop;

package/src/hooks/useAnimatedVisibility.spec.ts

@@ -13,9 +13,9 @@ import { useAnimatedVisibility } from "./useAnimatedVisibility.js";
  * Create a mock AnimationEvent for testing.
  */
 function createMockAnimationEvent(
-  target: EventTarget,
-  currentTarget: EventTarget,
-): React.AnimationEvent {
+  target: Element,
+  currentTarget: Element,
+): React.AnimationEvent<Element> {
   const noop = (): void => {};
   const noopBool = (): boolean => false;
   const nativeEvent = {

package/src/hooks/useOperationContinuity.spec.ts

@@ -5,6 +5,8 @@ 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);
 };
@@ -157,8 +159,9 @@ describe("useOperationContinuity", () => {
      */
     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 } },
+        ({ role, displacement }: { role: TestRole; displacement: number }) =>
+          useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "active" as TestRole, displacement: 500 } },
       );
 
       // During swipe: role="active", retaining
@@ -198,8 +201,9 @@ describe("useOperationContinuity", () => {
       // 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 } },
+        ({ role, displacement }: { role: TestRole; displacement: number }) =>
+          useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "active" as TestRole, displacement: 0 } },
       );
 
       expect(result.current.value).toBe("active");
@@ -220,8 +224,9 @@ describe("useOperationContinuity", () => {
       // 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 } },
+        ({ role, displacement }: { role: TestRole; displacement: number }) =>
+          useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "behind" as TestRole, displacement: 100 } },
       );
 
       expect(result.current.value).toBe("behind");
@@ -241,8 +246,9 @@ describe("useOperationContinuity", () => {
     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 } },
+        ({ role, displacement }: { role: TestRole; displacement: number }) =>
+          useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "active" as TestRole, displacement: 400 } },
       );
 
       expect(result.current.value).toBe("active");
@@ -262,8 +268,9 @@ describe("useOperationContinuity", () => {
       // 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 } },
+        ({ role, displacement }: { role: TestRole; displacement: number }) =>
+          useOperationContinuity(role, displacement > 0),
+        { initialProps: { role: "behind" as TestRole, displacement: 100 } },
       );
 
       // Simulate role change during swipe

package/src/hooks/useOperationContinuity.ts

@@ -90,21 +90,21 @@ export function useOperationContinuity<T>(
   // Derive operationJustEnded from transition: true → false
   // This is idempotent - safe for StrictMode double-render
   const wasRetaining = prevShouldRetainRef.current;
-  const operationJustEnded = wasRetaining && !shouldRetainPrevious;
+  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;
+  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 || currentlyDiverged;
-  const changedAtExit = operationJustEnded && valueDiverged;
-  const changedDuringOperation = changedDuringRetention || changedAtExit;
+  const changedDuringRetention = changedDuringRetentionRef.current ? true : currentlyDiverged;
+  const changedAtExit = operationJustEnded ? valueDiverged : false;
+  const changedDuringOperation = changedDuringRetention ? true : changedAtExit;
 
   // Determine effective value
   // During retention: use retained value

package/src/hooks/useSharedElementTransition.ts

@@ -12,7 +12,10 @@ import { flushSync } from "react-dom";
  * Check if View Transitions API is supported.
  */
 export function supportsViewTransitions(): boolean {
-  return typeof document !== "undefined" && "startViewTransition" in document;
+  if (typeof document === "undefined") {
+    return false;
+  }
+  return "startViewTransition" in document;
 }
 
 type ViewTransitionHandle = {
@@ -36,6 +39,25 @@ export function startViewTransition(callback: () => void): ViewTransitionHandle
 /** Default dismiss threshold (30% of viewport height) */
 const DEFAULT_DISMISS_THRESHOLD = 0.3;
 
+/**
+ * Compute transform string for swipe displacement.
+ */
+function computeSwipeTransform(
+  isSwiping: boolean,
+  displacement: { x: number; y: number },
+): string | undefined {
+  if (isSwiping) {
+    return `translate(${displacement.x}px, ${displacement.y}px)`;
+  }
+  if (displacement.x !== 0) {
+    return `translate(${displacement.x}px, ${displacement.y}px)`;
+  }
+  if (displacement.y !== 0) {
+    return `translate(${displacement.x}px, ${displacement.y}px)`;
+  }
+  return undefined;
+}
+
 /** Velocity threshold for quick flick dismissal (px/ms) */
 const VELOCITY_THRESHOLD = 0.5;
 
@@ -174,7 +196,7 @@ export function useSharedElementTransition<T>(
   }, []);
 
   const collapse = React.useCallback(() => {
-    if (!expandedItem) return;
+    if (!expandedItem) {return;}
 
     setIsSwiping(false);
 
@@ -222,7 +244,8 @@ export function useSharedElementTransition<T>(
     setDisplacement({ x: dx, y: dy });
   }, [isSwiping]);
 
-  const handlePointerUp = React.useCallback((event: React.PointerEvent) => {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- event parameter required by React handler signature
+  const handlePointerUp = React.useCallback((_event: React.PointerEvent) => {
     if (!isSwiping || !startPointRef.current) {
       return;
     }
@@ -267,7 +290,7 @@ export function useSharedElementTransition<T>(
       // - The pending item (clicked card, for old state capture during expand)
       // - The collapsing item (card returning to, for new state capture during collapse)
       // - Never to other cards (they don't participate in the transition)
-      const shouldHaveTransitionName = isThisItemPending || isThisItemCollapsing;
+      const shouldHaveTransitionName = isThisItemPending ? true : isThisItemCollapsing;
 
       return {
         style: {
@@ -291,9 +314,7 @@ export function useSharedElementTransition<T>(
       const name = nameArray[nameIndex];
 
       // Apply transform during swipe
-      const transform = isSwiping || displacement.x !== 0 || displacement.y !== 0
-        ? `translate(${displacement.x}px, ${displacement.y}px)`
-        : undefined;
+      const transform = computeSwipeTransform(isSwiping, displacement);
 
       return {
         style: {

package/src/modules/dialog/DialogContainer.tsx

@@ -2,7 +2,7 @@
  * @file Base dialog container component using native <dialog> element
  */
 import * as React from "react";
-import type { DialogContainerProps } from "./types.js";
+import type { DialogContainerProps, DialogContainerHandle } from "./types.js";
 import { useDialogContainer } from "./useDialogContainer.js";
 import { SwipeDialogContainer } from "./SwipeDialogContainer.js";
 import {
@@ -35,9 +35,12 @@ const contentStyle: React.CSSProperties = {
 
 const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
 
-type DialogContainerImplProps = DialogContainerProps;
+type DialogContainerImplProps = DialogContainerProps & {
+  ref?: React.Ref<DialogContainerHandle>;
+};
 
 const DialogContainerImpl: React.FC<DialogContainerImplProps> = ({
+  ref,
   visible,
   onClose,
   children,
@@ -62,6 +65,17 @@ const DialogContainerImpl: React.FC<DialogContainerImplProps> = ({
     preventBodyScroll,
   });
 
+  // For CSS mode, triggerClose just calls onClose immediately
+  // (CSS transitions handle the animation via visibility state)
+  const triggerClose = React.useCallback(async (): Promise<void> => {
+    onClose();
+  }, [onClose]);
+
+  // Expose triggerClose via ref for API consistency
+  React.useImperativeHandle(ref, () => ({
+    triggerClose,
+  }), [triggerClose]);
+
   const backdropStyle = React.useMemo((): string => {
     if (transitionMode === "none") {
       return `
@@ -171,18 +185,38 @@ const DialogContainerImpl: React.FC<DialogContainerImplProps> = ({
  *   <div>Swipe down to close</div>
  * </DialogContainer>
  * ```
+ *
+ * @example Using ref to trigger close animation
+ * ```tsx
+ * const dialogRef = useRef<DialogContainerHandle>(null);
+ *
+ * <DialogContainer
+ *   ref={dialogRef}
+ *   visible={isOpen}
+ *   onClose={() => setIsOpen(false)}
+ *   transitionMode="swipe"
+ * >
+ *   <button onClick={() => dialogRef.current?.triggerClose()}>
+ *     Close with animation
+ *   </button>
+ * </DialogContainer>
+ * ```
  */
-export const DialogContainer: React.FC<DialogContainerProps> = (props) => {
+type DialogContainerComponentProps = DialogContainerProps & {
+  ref?: React.Ref<DialogContainerHandle>;
+};
+
+export const DialogContainer: React.FC<DialogContainerComponentProps> = ({ ref, ...props }) => {
   if (!isBrowser) {
     return null;
   }
 
   // Use SwipeDialogContainer for swipe mode
   if (props.transitionMode === "swipe") {
-    return <SwipeDialogContainer {...props} />;
+    return <SwipeDialogContainer ref={ref} {...props} />;
   }
 
-  return <DialogContainerImpl {...props} />;
+  return <DialogContainerImpl ref={ref} {...props} />;
 };
 
 DialogContainer.displayName = "DialogContainer";

package/src/modules/dialog/Modal.tsx

@@ -2,7 +2,7 @@
  * @file Modal component - Centered modal dialog with optional chrome
  */
 import * as React from "react";
-import type { ModalProps } from "./types";
+import type { ModalProps, ModalHandle, DialogContainerHandle } from "./types";
 import { DialogContainer } from "./DialogContainer";
 import {
   FloatingPanelFrame,
@@ -59,7 +59,11 @@ const ModalContentWithChrome: React.FC<ModalContentProps> = ({
         >
           <FloatingPanelTitle>{header?.title}</FloatingPanelTitle>
           <React.Activity mode={shouldShowClose ? "visible" : "hidden"}>
-            <FloatingPanelCloseButton onClick={onClose} aria-label="Close modal" style={{ marginLeft: "auto" }} />
+            <FloatingPanelCloseButton
+              onClick={onClose}
+              aria-label="Close modal"
+              style={{ marginLeft: "auto" }}
+            />
           </React.Activity>
         </FloatingPanelHeader>
       </React.Activity>
@@ -79,6 +83,10 @@ const ModalContentRenderer: React.FC<ModalContentRendererProps> = ({ chrome, chi
   return <>{children}</>;
 };
 
+type ModalComponentProps = ModalProps & {
+  ref?: React.Ref<ModalHandle>;
+};
+
 /**
  * Modal component for displaying centered dialogs.
  * Uses native <dialog> element for proper accessibility and top-layer rendering.
@@ -98,8 +106,26 @@ const ModalContentRenderer: React.FC<ModalContentRendererProps> = ({ chrome, chi
  *   </form>
  * </Modal>
  * ```
+ *
+ * @example Using ref to trigger close animation
+ * ```tsx
+ * const modalRef = useRef<ModalHandle>(null);
+ *
+ * <Modal
+ *   ref={modalRef}
+ *   visible={isOpen}
+ *   onClose={() => setIsOpen(false)}
+ *   transitionMode="swipe"
+ *   header={{ title: "Settings" }}
+ * >
+ *   <button onClick={() => modalRef.current?.triggerClose()}>
+ *     Close with animation
+ *   </button>
+ * </Modal>
+ * ```
  */
-export const Modal: React.FC<ModalProps> = ({
+export const Modal: React.FC<ModalComponentProps> = ({
+  ref: externalRef,
   visible,
   onClose,
   children,
@@ -124,6 +150,21 @@ export const Modal: React.FC<ModalProps> = ({
   openDirection = "center",
   useViewTransition = false,
 }) => {
+  // Internal ref to DialogContainer for close button
+  const internalRef = React.useRef<DialogContainerHandle>(null);
+
+  // Merge refs - expose the same handle to external ref
+  React.useImperativeHandle(externalRef, () => ({
+    triggerClose: async () => {
+      await internalRef.current?.triggerClose();
+    },
+  }), []);
+
+  // Handler for close button that triggers animation
+  const handleCloseButtonClick = React.useCallback(() => {
+    // Use triggerClose to animate, which will call onClose when complete
+    internalRef.current?.triggerClose();
+  }, []);
   const computedStyle = React.useMemo((): React.CSSProperties => {
     const style: React.CSSProperties = { ...modalContentStyle };
 
@@ -147,6 +188,7 @@ export const Modal: React.FC<ModalProps> = ({
 
   return (
     <DialogContainer
+      ref={internalRef}
       visible={visible}
       onClose={onClose}
       position="center"
@@ -169,7 +211,7 @@ export const Modal: React.FC<ModalProps> = ({
           chrome={chrome}
           header={header}
           dismissible={dismissible}
-          onClose={onClose}
+          onClose={handleCloseButtonClick}
           contentStyle={propContentStyle}
         >
           {children}

package/src/modules/dialog/SwipeDialogContainer.tsx

@@ -6,7 +6,7 @@
  * positioning and custom transform animations.
  */
 import * as React from "react";
-import type { DialogContainerProps } from "./types.js";
+import type { DialogContainerProps, DialogContainerHandle } from "./types.js";
 import { useDialogContainer } from "./useDialogContainer.js";
 import { useDialogSwipeInput } from "./useDialogSwipeInput.js";
 import { useDialogTransform } from "./useDialogTransform.js";
@@ -43,13 +43,18 @@ const backdropStyle: React.CSSProperties = {
   willChange: "opacity",
 };
 
+type SwipeDialogContainerProps = DialogContainerProps & {
+  ref?: React.Ref<DialogContainerHandle>;
+};
+
 /**
  * Swipeable dialog container with multi-phase animation.
  *
  * Uses native <dialog> for top layer positioning and custom JS animations
  * for swipe-to-dismiss functionality.
  */
-export const SwipeDialogContainer: React.FC<DialogContainerProps> = ({
+export const SwipeDialogContainer: React.FC<SwipeDialogContainerProps> = ({
+  ref,
   visible,
   onClose,
   children,
@@ -106,6 +111,11 @@ export const SwipeDialogContainer: React.FC<DialogContainerProps> = ({
     onCloseComplete: onClose,
   });
 
+  // Expose triggerClose via ref
+  React.useImperativeHandle(ref, () => ({
+    triggerClose,
+  }), [triggerClose]);
+
   // Handle backdrop click
   const handleBackdropClick = React.useCallback(() => {
     if (!dismissible) {

package/src/modules/dialog/dialogAnimationUtils.spec.ts

@@ -1,7 +1,6 @@
 /**
  * @file Tests for dialog animation utilities
  */
-import { describe, expect, it } from "vitest";
 import {
   computeCloseTransform,
   computeOpenTransform,

package/src/modules/dialog/types.ts

@@ -4,6 +4,15 @@
 import type * as React from "react";
 import type { Position } from "../../types";
 
+/**
+ * Handle exposed by DialogContainer via ref.
+ * Allows programmatic control of dialog animations.
+ */
+export type DialogContainerHandle = {
+  /** Trigger the close animation. Returns a promise that resolves when animation completes. */
+  triggerClose: () => Promise<void>;
+};
+
 /**
  * Transition mode for dialog animations
  * - "none": No animation
@@ -68,6 +77,11 @@ export type ModalHeader = {
   showCloseButton?: boolean;
 };
 
+/**
+ * Alias for DialogContainerHandle (used by Modal)
+ */
+export type ModalHandle = DialogContainerHandle;
+
 /**
  * Props for Modal component
  */

package/src/modules/dialog/useDialogContainer.spec.ts

@@ -18,6 +18,14 @@ const createCallTracker = (): CallTracker => {
   return { calls, fn };
 };
 
+/**
+ * Create a mock view for test events.
+ */
+function createMockView(): React.MouseEvent<HTMLDialogElement>["view"] {
+  // eslint-disable-next-line custom/no-as-outside-guard -- test helper for view casting
+  return window as unknown as React.MouseEvent<HTMLDialogElement>["view"];
+}
+
 /**
  * Mock SyntheticEvent with call tracking.
  */
@@ -61,8 +69,8 @@ function createMockSyntheticEvent(): MockSyntheticEvent {
  * Creates a mock React.MouseEvent for dialog interactions.
  */
 function createMockMouseEvent(
-  target: EventTarget,
-  currentTarget: EventTarget,
+  target: HTMLElement,
+  currentTarget: HTMLDialogElement,
 ): React.MouseEvent<HTMLDialogElement> {
   const noop = (): void => {};
   const noopBool = (): boolean => false;
@@ -103,7 +111,7 @@ function createMockMouseEvent(
     screenY: 0,
     // UIEvent properties
     detail: 0,
-    view: window,
+    view: createMockView(),
   };
 }