chore: Add pointer move tolerance that counts as a press rather than move

Author: Johannes Weber

src/internal/drag-handle/index.tsx

@@ -8,7 +8,7 @@ import {
   InternalDragHandleProps,
 } from "@cloudscape-design/components/internal/do-not-use/drag-handle";
 
-import { HandleActiveState } from "../item-container";
+import { CLICK_DRAG_THRESHOLD, HandleActiveState } from "../item-container";
 
 import styles from "./styles.css.js";
 import testUtilsStyles from "./test-classes/styles.css.js";
@@ -60,6 +60,8 @@ function DragHandle(
       triggerMode="keyboard-activate"
       onDirectionClick={onDirectionClick}
       initialShowButtons={initialShowButtons}
+      hideButtonsOnDrag={true}
+      clickDragThreshold={CLICK_DRAG_THRESHOLD}
     />
   );
 }

src/internal/item-container/__tests__/item-container.test.tsx

@@ -86,6 +86,20 @@ describe("pointer interaction", () => {
     clickHandle(getByTestId("resize-handle"));
     expect(mockDraggable.start).toBeCalledWith("resize", "pointer", expect.any(Coordinates));
   });
+
+  test("does not call updateTransition on pointer down and a mouse movement within the CLICK_DRAG_THRESHOLD", () => {
+    const { getByTestId } = render(<ItemContainer {...defaultProps} />);
+    clickHandle(getByTestId("drag-handle"));
+    expect(mockDraggable.updateTransition).not.toBeCalledWith();
+  });
+
+  test("call updateTransition on pointer down and a mouse movement outside the CLICK_DRAG_THRESHOLD", () => {
+    const { getByTestId } = render(<ItemContainer {...defaultProps} />);
+    const dragHandleEl = getByTestId("drag-handle");
+    fireEvent(dragHandleEl, new MouseEvent("pointerdown", { clientX: 10, clientY: 20, bubbles: true, button: 0 }));
+    fireEvent(dragHandleEl, new MouseEvent("pointermove", { clientX: 15, clientY: 20, bubbles: true }));
+    expect(mockDraggable.updateTransition).toBeCalledWith(expect.any(Coordinates));
+  });
 });
 
 describe("keyboard interaction", () => {

src/internal/item-container/__tests__/utils.test.ts

@@ -4,11 +4,16 @@ import { beforeEach, describe, expect, Mock, test, vi } from "vitest";
 
 import { getLogicalClientX as originalGetLogicalClientX } from "@cloudscape-design/component-toolkit/internal";
 
+import type { Operation } from "../../../../lib/components/internal/dnd-controller/controller";
 import type { Transition } from "../../../../lib/components/internal/item-container";
 import { determineHandleActiveState } from "../../../../lib/components/internal/item-container/utils";
-import type { Operation } from "../../dnd-controller/controller";
-import { Coordinates } from "../../utils/coordinates";
-import { calculateInitialPointerData, DetermineHandleActiveStateArgs, getDndOperationType } from "../utils";
+import {
+  calculateInitialPointerData,
+  DetermineHandleActiveStateArgs,
+  getDndOperationType,
+  hasPointerMovedBeyondThreshold,
+} from "../../../../lib/components/internal/item-container/utils";
+import { Coordinates } from "../../../../lib/components/internal/utils/coordinates";
 
 const mockRect = {
   insetInlineStart: 10,
@@ -173,6 +178,51 @@ describe("calculateInitialPointerData", () => {
   });
 });
 
+describe("hasPointerMovedBeyondThreshold", () => {
+  const threshold = 3;
+
+  test("should return false when initialPosition is undefined", () => {
+    const event = mockPointerEvent(50, 60) as PointerEvent;
+    expect(hasPointerMovedBeyondThreshold(event, undefined)).toBe(false);
+  });
+
+  test("should return false when pointer hasn't moved beyond threshold", () => {
+    const initialPosition = { x: 50, y: 60 };
+    const event = mockPointerEvent(51, 61) as PointerEvent;
+    expect(hasPointerMovedBeyondThreshold(event, initialPosition, threshold)).toBe(false);
+  });
+
+  test("should return true when pointer moved beyond threshold in positive X direction", () => {
+    const initialPosition = { x: 50, y: 60 };
+    const event = mockPointerEvent(54, 60) as PointerEvent;
+    expect(hasPointerMovedBeyondThreshold(event, initialPosition, threshold)).toBe(true);
+  });
+
+  test("should return true when pointer moved beyond threshold in negative X direction", () => {
+    const initialPosition = { x: 50, y: 60 };
+    const event = mockPointerEvent(46, 60) as PointerEvent;
+    expect(hasPointerMovedBeyondThreshold(event, initialPosition, threshold)).toBe(true);
+  });
+
+  test("should return true when pointer moved beyond threshold in positive Y direction", () => {
+    const initialPosition = { x: 50, y: 60 };
+    const event = mockPointerEvent(50, 64) as PointerEvent;
+    expect(hasPointerMovedBeyondThreshold(event, initialPosition, threshold)).toBe(true);
+  });
+
+  test("should return true when pointer moved beyond threshold in negative Y direction", () => {
+    const initialPosition = { x: 50, y: 60 };
+    const event = mockPointerEvent(50, 56) as PointerEvent;
+    expect(hasPointerMovedBeyondThreshold(event, initialPosition, threshold)).toBe(true);
+  });
+
+  test("should use default threshold when not provided", () => {
+    const initialPosition = { x: 50, y: 60 };
+    const event = mockPointerEvent(54, 60) as PointerEvent;
+    expect(hasPointerMovedBeyondThreshold(event, initialPosition)).toBe(true);
+  });
+});
+
 describe("determineHandleActiveState", () => {
   const mockTransition = (operation: Operation): Transition => ({
     itemId: "test-item",

src/internal/item-container/index.tsx

@@ -38,7 +38,12 @@ import { getNormalizedElementRect } from "../utils/screen";
 import { throttle } from "../utils/throttle";
 import { getCollisionRect } from "./get-collision-rect";
 import { getNextDroppable } from "./get-next-droppable";
-import { calculateInitialPointerData, determineHandleActiveState, getDndOperationType } from "./utils";
+import {
+  calculateInitialPointerData,
+  determineHandleActiveState,
+  getDndOperationType,
+  hasPointerMovedBeyondThreshold,
+} from "./utils";
 
 import styles from "./styles.css.js";
 
@@ -163,6 +168,12 @@ export interface ItemContainerProps {
 
 export const ItemContainer = forwardRef(ItemContainerComponent);
 
+// The amount of distance after pointer down that the cursor is allowed to
+// jitter for a subsequent mouseup to still register as a "press" instead of
+// a drag. A little allowance is needed for usability reasons, but this number
+// isn't set in stone.
+export const CLICK_DRAG_THRESHOLD = 3;
+
 function ItemContainerComponent(
   { item, placed, acquired, inTransition, transform, getItemSize, onKeyMove, children, isRtl }: ItemContainerProps,
   ref: Ref<ItemContainerRef>,
@@ -174,6 +185,7 @@ function ItemContainerComponent(
   const [isHidden, setIsHidden] = useState(false);
   const muteEventsRef = useRef(false);
   const itemRef = useRef<HTMLDivElement>(null);
+  const initialPointerDownPosition = useRef<{ x: number; y: number } | undefined>();
   const draggableApi = useDraggable({
     draggableItem: item,
     getCollisionRect: (operation, coordinates, dropTarget) => {
@@ -322,17 +334,21 @@ function ItemContainerComponent(
     // 1. If the last interaction is not "keyboard" (the user clicked on another handle issuing a new transition);
     // 2. If the item is acquired by the board (in that case the focus moves to the board item which is expected, palette item is hidden and all events handlers must be muted).
     selectedHook.current.processBlur();
+    initialPointerDownPosition.current = undefined;
     if (acquired || (transition && transition.interactionType === "keyboard" && !muteEventsRef.current)) {
       draggableApi.submitTransition();
     }
   }
 
   function handleGlobalPointerMove(event: PointerEvent) {
-    selectedHook.current.processPointerMove(event);
+    if (hasPointerMovedBeyondThreshold(event, initialPointerDownPosition.current)) {
+      selectedHook.current.processPointerMove(event);
+    }
   }
 
   function handleGlobalPointerUp(event: PointerEvent) {
     selectedHook.current.processPointerUp(event);
+    initialPointerDownPosition.current = undefined;
     // Clean up global listeners after interaction ends
     window.removeEventListener("pointermove", handleGlobalPointerMove);
     window.removeEventListener("pointerup", handleGlobalPointerUp);
@@ -345,6 +361,7 @@ function ItemContainerComponent(
     if (event.button !== 0) {
       return;
     }
+    initialPointerDownPosition.current = { x: event.clientX, y: event.clientY };
 
     if (operation === "drag") {
       selectedHook.current = dragInteractionHook;

src/internal/item-container/utils.ts

@@ -5,7 +5,7 @@ import { InteractionState } from "@cloudscape-design/components/internal/compone
 
 import { Operation } from "../dnd-controller/controller"; // Adjust this path
 import { Coordinates } from "../utils/coordinates"; // Adjust this path based on your project structure
-import { Transition } from ".";
+import { CLICK_DRAG_THRESHOLD, Transition } from ".";
 
 export type HandleActiveState = null | "pointer" | "uap";
 
@@ -75,6 +75,22 @@ export function calculateInitialPointerData({
   return { pointerOffset, pointerBoundaries };
 }
 
+export function hasPointerMovedBeyondThreshold(
+  event: PointerEvent,
+  initialPosition: { x: number; y: number } | undefined,
+  threshold: number = CLICK_DRAG_THRESHOLD,
+): boolean {
+  if (!initialPosition) {
+    return false;
+  }
+  return (
+    event.clientX > initialPosition.x + threshold ||
+    event.clientX < initialPosition.x - threshold ||
+    event.clientY > initialPosition.y + threshold ||
+    event.clientY < initialPosition.y - threshold
+  );
+}
+
 export function determineHandleActiveState({
   isHandleActive,
   currentTransition,

src/internal/resize-handle/index.tsx

@@ -8,7 +8,7 @@ import {
   InternalDragHandleProps,
 } from "@cloudscape-design/components/internal/do-not-use/drag-handle";
 
-import { HandleActiveState } from "../item-container";
+import { CLICK_DRAG_THRESHOLD, HandleActiveState } from "../item-container";
 
 import styles from "./styles.css.js";
 import testUtilsStyles from "./test-classes/styles.css.js";
@@ -53,6 +53,8 @@ export default function ResizeHandle({
       }}
       triggerMode="keyboard-activate"
       onDirectionClick={onDirectionClick}
+      hideButtonsOnDrag={true}
+      clickDragThreshold={CLICK_DRAG_THRESHOLD}
     />
   );
 }