feat(dnd): useDrag: custom drag preview offset (#8445)

* useDrag: custom offset

* allow passing getPreviewOffset into useDraggableCollectionState and useDragAndDrop

* add stories for using with useDraggableCollectionState and useDragAndDrop

* use renderDragPreview instead of getPreviewOffset

Author: reidbarber

packages/@react-aria/dnd/src/DragPreview.tsx

@@ -15,7 +15,12 @@ import {flushSync} from 'react-dom';
 import React, {ForwardedRef, JSX, useEffect, useImperativeHandle, useRef, useState} from 'react';
 
 export interface DragPreviewProps {
-  children: (items: DragItem[]) => JSX.Element | null
+  /**
+   * A render function which returns a preview element, or an object containing the element
+   * and a custom offset. If an object is returned, the provided `x` and `y` values will be
+   * used as the drag preview offset instead of the default calculation.
+   */
+  children: (items: DragItem[]) => JSX.Element | {element: JSX.Element, x: number, y: number} | null
 }
 
 export const DragPreview:
@@ -26,15 +31,29 @@ React.forwardRef(function DragPreview(props: DragPreviewProps, ref: ForwardedRef
   let domRef = useRef<HTMLDivElement | null>(null);
   let raf = useRef<ReturnType<typeof requestAnimationFrame> | undefined>(undefined);
 
-  useImperativeHandle(ref, () => (items: DragItem[], callback: (node: HTMLElement | null) => void) => {
+  useImperativeHandle(ref, () => (items: DragItem[], callback: (node: HTMLElement | null, x?: number, y?: number) => void) => {
     // This will be called during the onDragStart event by useDrag. We need to render the
     // preview synchronously before this event returns so we can call event.dataTransfer.setDragImage.
+
+    let result = render(items);
+    let element: JSX.Element | null;
+    let offsetX: number | undefined;
+    let offsetY: number | undefined;
+
+    if (result && typeof result === 'object' && 'element' in result) {
+      element = result.element;
+      offsetX = result.x;
+      offsetY = result.y;
+    } else {
+      element = result as JSX.Element | null;
+    }
+
     flushSync(() => {
-      setChildren(render(items));
+      setChildren(element);
     });
 
     // Yield back to useDrag to set the drag image.
-    callback(domRef.current);
+    callback(domRef.current, offsetX, offsetY);
 
     // Remove the preview from the DOM after a frame so the browser has time to paint.
     raf.current = requestAnimationFrame(() => {

packages/@react-aria/dnd/src/useDrag.ts

@@ -134,7 +134,7 @@ export function useDrag(options: DragOptions): DragResult {
     // If there is a preview option, use it to render a custom preview image that will
     // appear under the pointer while dragging. If not, the element itself is dragged by the browser.
     if (typeof options.preview?.current === 'function') {
-      options.preview.current(items, node => {
+      options.preview.current(items, (node, userX, userY) => {
         if (!node) {
           return;
         }
@@ -143,18 +143,35 @@ export function useDrag(options: DragOptions): DragResult {
         // If the preview is much smaller, then just use the center point of the preview.
         let size = node.getBoundingClientRect();
         let rect = e.currentTarget.getBoundingClientRect();
-        let x = e.clientX - rect.x;
-        let y = e.clientY - rect.y;
-        if (x > size.width || y > size.height) {
-          x = size.width / 2;
-          y = size.height / 2;
+        let defaultX = e.clientX - rect.x;
+        let defaultY = e.clientY - rect.y;
+        if (defaultX > size.width || defaultY > size.height) {
+          defaultX = size.width / 2;
+          defaultY = size.height / 2;
         }
 
+        // Start with default offsets.
+        let offsetX = defaultX;
+        let offsetY = defaultY;
+
+        // If the preview renderer supplied explicit offsets, use those.
+        if (typeof userX === 'number' && typeof userY === 'number') {
+          offsetX = userX;
+          offsetY = userY;
+        }
+
+        // Clamp the offset so it stays within the preview bounds. Browsers
+        // automatically clamp out-of-range values, but doing it ourselves
+        // prevents the visible "snap" that can occur when the browser adjusts
+        // them after the first drag update.
+        offsetX = Math.max(0, Math.min(offsetX, size.width));
+        offsetY = Math.max(0, Math.min(offsetY, size.height));
+
         // Rounding height to an even number prevents blurry preview seen on some screens
         let height = 2 * Math.round(size.height / 2);
         node.style.height = `${height}px`;
 
-        e.dataTransfer.setDragImage(node, x, y);
+        e.dataTransfer.setDragImage(node, offsetX, offsetY);
       });
     }
 

packages/@react-aria/dnd/stories/dnd.stories.tsx

@@ -385,7 +385,14 @@ function DraggableCollectionExample(props) {
   };
 
   return (
-    <DraggableCollection items={list.items} selectedKeys={list.selectedKeys} onSelectionChange={list.setSelectedKeys} onDragEnd={onDragEnd} onCut={onCut} isDisabled={props.isDisabled}>
+    <DraggableCollection
+      items={list.items}
+      selectedKeys={list.selectedKeys}
+      onSelectionChange={list.setSelectedKeys}
+      onDragEnd={onDragEnd}
+      onCut={onCut}
+      isDisabled={props.isDisabled}
+      {...props}>
       {item => (
         <Item textValue={item.text}>
           {item.type === 'folder' && <Folder size="S" />}
@@ -397,7 +404,7 @@ function DraggableCollectionExample(props) {
 }
 
 function DraggableCollection(props) {
-  let {isDisabled} = props;
+  let {isDisabled, mode, offsetX, offsetY} = props;
   let ref = React.useRef<HTMLDivElement>(null);
   let state = useListState<ItemValue>(props);
   let gridState = useGridState({
@@ -472,7 +479,7 @@ function DraggableCollection(props) {
           let selectedKeys = dragState.draggingKeys;
           let draggedKey = [...selectedKeys][0];
           let item = state.collection.getItem(draggedKey);
-          return (
+          let element = (
             <div className={classNames(dndStyles, 'draggable', 'is-drag-preview', {'is-dragging-multiple': selectedKeys.size > 1})}>
               <div className={classNames(dndStyles, 'drag-handle')}>
                 <ShowMenu size="XS" />
@@ -483,6 +490,12 @@ function DraggableCollection(props) {
               }
             </div>
           );
+
+          if (mode === 'custom') {
+            return {element, x: offsetX, y: offsetY};
+          }
+
+          return element;
         }}
       </DragPreview>
     </div>
@@ -575,3 +588,129 @@ export const DroppableEnabledDisabledControl: DnDStoryObj = {
     }
   }
 };
+
+interface PreviewOffsetArgs {
+  /** Strategy for positioning the preview. */
+  mode: 'default' | 'custom',
+  /** X offset in pixels (only used when mode = custom). */
+  offsetX: number,
+  /** Y offset in pixels (only used when mode = custom). */
+  offsetY: number
+}
+
+function DraggableWithPreview({mode, offsetX, offsetY}: PreviewOffsetArgs): JSX.Element {
+  const preview = React.useRef(null);
+
+  const {dragProps, isDragging} = useDrag({
+    getItems() {
+      return [{
+        'text/plain': 'preview offset demo'
+      }];
+    },
+    preview,
+    onDragStart: action('onDragStart'),
+    onDragEnd: action('onDragEnd')
+  });
+
+  const {clipboardProps} = useClipboard({
+    getItems() {
+      return [{
+        'text/plain': 'preview offset demo'
+      }];
+    }
+  });
+
+  const ref = React.useRef<HTMLDivElement>(null);
+  const {buttonProps} = useButton({elementType: 'div'}, ref);
+
+  return (
+    <>
+      <div
+        ref={ref}
+        {...mergeProps(dragProps, buttonProps, clipboardProps)}
+        className={classNames(dndStyles, 'draggable', {'is-dragging': isDragging})}
+        style={{cursor: 'grab'}}>
+        <ShowMenu size="XS" />
+        <span>Drag me</span>
+      </div>
+
+      {/* Custom drag preview */}
+      <DragPreview ref={preview}>
+        {() => {
+          const elem = (
+            <div className={classNames(dndStyles, 'draggable', 'is-drag-preview')}>
+              <ShowMenu size="XS" />
+              <span>Preview</span>
+            </div>
+          );
+
+          if (mode === 'custom') {
+            return {element: elem, x: offsetX, y: offsetY};
+          }
+
+          return elem;
+        }}
+      </DragPreview>
+    </>
+  );
+}
+
+export const PreviewOffset: DnDStoryObj = {
+  render: (args) => (
+    <Flex direction="column" gap="size-200" alignItems="center">
+      <DraggableWithPreview {...args} />
+      <Droppable />
+    </Flex>
+  ),
+  name: 'Preview offset',
+  argTypes: {
+    mode: {
+      control: 'select',
+      options: ['default', 'custom'],
+      defaultValue: 'default'
+    },
+    offsetX: {
+      control: 'number',
+      defaultValue: 20
+    },
+    offsetY: {
+      control: 'number',
+      defaultValue: 20
+    }
+  },
+  args: {
+    mode: 'default',
+    offsetX: 20,
+    offsetY: 20
+  }
+};
+
+export const CollectionPreviewOffset: DnDStoryObj = {
+  render: (args) => (
+    <Flex direction="column" gap="size-200" alignItems="center">
+      <DraggableCollectionExample {...args} />
+      <Droppable />
+    </Flex>
+  ),
+  name: 'Collection preview offset',
+  argTypes: {
+    mode: {
+      control: 'select',
+      options: ['default', 'custom'],
+      defaultValue: 'default'
+    },
+    offsetX: {
+      control: 'number',
+      defaultValue: 20
+    },
+    offsetY: {
+      control: 'number',
+      defaultValue: 20
+    }
+  },
+  args: {
+    mode: 'default',
+    offsetX: 20,
+    offsetY: 20
+  }
+};

packages/@react-aria/dnd/test/dnd.test.js

@@ -1350,6 +1350,59 @@ describe('useDrag and useDrop', function () {
         expect(dataTransfer._dragImage.x).toBe(10);
         expect(dataTransfer._dragImage.y).toBe(10);
       });
+
+      it('should use the offset returned from renderPreview', () => {
+        let renderPreview = jest.fn().mockImplementation(() => ({element: <div>Drag preview</div>, x: 12, y: 15}));
+        let tree = render(<Draggable renderPreview={renderPreview} />);
+
+        let draggable = tree.getByText('Drag me');
+
+        // Ensure consistent element sizes between draggable source and preview.
+        jest.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function () {
+          return {
+            left: 0,
+            top: 0,
+            x: 0,
+            y: 0,
+            width: this.style.position === 'absolute' ? 20 : 100,
+            height: this.style.position === 'absolute' ? 20 : 50
+          };
+        });
+
+        let dataTransfer = new DataTransfer();
+        fireEvent(draggable, new DragEvent('dragstart', {dataTransfer, clientX: 10, clientY: 10}));
+
+        // renderPreview should have been called and its offset returned used without modification.
+        expect(renderPreview).toHaveBeenCalledTimes(1);
+        expect(dataTransfer._dragImage.x).toBe(12);
+        expect(dataTransfer._dragImage.y).toBe(15);
+      });
+
+      it('should clamp the offset returned from renderPreview to the preview bounds', () => {
+        let renderPreview = jest.fn().mockImplementation(() => ({element: <div>Drag preview</div>, x: 50, y: -10}));
+        // Return values outside of the preview bounds to verify clamping logic.
+        let tree = render(<Draggable renderPreview={renderPreview} />);
+
+        let draggable = tree.getByText('Drag me');
+
+        jest.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function () {
+          return {
+            left: 0,
+            top: 0,
+            x: 0,
+            y: 0,
+            width: this.style.position === 'absolute' ? 20 : 100,
+            height: this.style.position === 'absolute' ? 20 : 50
+          };
+        });
+
+        let dataTransfer = new DataTransfer();
+        fireEvent(draggable, new DragEvent('dragstart', {dataTransfer, clientX: 0, clientY: 0}));
+
+        // Offsets should be clamped to 0 <= offset <= width/height (20 in this mock).
+        expect(dataTransfer._dragImage.x).toBe(20);
+        expect(dataTransfer._dragImage.y).toBe(0);
+      });
     });
   });
 

packages/@react-types/shared/src/dnd.d.ts

@@ -275,7 +275,7 @@ export interface DraggableCollectionEndEvent extends DragEndEvent {
   isInternal: boolean
 }
 
-export type DragPreviewRenderer = (items: DragItem[], callback: (node: HTMLElement | null) => void) => void;
+export type DragPreviewRenderer = (items: DragItem[], callback: (node: HTMLElement | null, x?: number, y?: number) => void) => void;
 
 export interface DraggableCollectionProps {
   /** Handler that is called when a drag operation is started. */

packages/react-aria-components/src/useDragAndDrop.tsx

@@ -50,7 +50,7 @@ interface DragHooks {
   useDraggableCollection?: (props: DraggableCollectionOptions, state: DraggableCollectionState, ref: RefObject<HTMLElement | null>) => void,
   useDraggableItem?: (props: DraggableItemProps, state: DraggableCollectionState) => DraggableItemResult,
   DragPreview?: typeof DragPreview,
-  renderDragPreview?: (items: DragItem[]) => JSX.Element,
+  renderDragPreview?: (items: DragItem[]) => JSX.Element | {element: JSX.Element, x: number, y: number},
   isVirtualDragging?: () => boolean
 }
 
@@ -81,7 +81,7 @@ export interface DragAndDropOptions extends Omit<DraggableCollectionProps, 'prev
    * A function that renders a drag preview, which is shown under the user's cursor while dragging.
    * By default, a copy of the dragged element is rendered.
    */
-  renderDragPreview?: (items: DragItem[]) => JSX.Element,
+  renderDragPreview?: (items: DragItem[]) => JSX.Element | {element: JSX.Element, x: number, y: number},
   /**
    * A function that renders a drop indicator element between two items in a collection.
    * This should render a `<DropIndicator>` element. If this function is not provided, a