feat(dnd): useDrag: custom drag preview offset

[reidbarber]

Closes #5409

Allows providing a getPreviewOffset to specify the x and y offset of the drag preview.

✅ Pull Request Checklist:

• Included link to corresponding React Spectrum GitHub Issue.
• Added/updated unit tests and storybook for this change (for new code or code which already has tests).
• Filled out test instructions.
• Updated documentation (if it already exists for this component).
• Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

Try the new story and adjust the controls.

🧢 Your Project:

[snowystinger]

I've no idea why it approved twice...

[LFDanLu]

This seems to work well in the story and the code seems straight forward enough, but should setting this also be supported in useDragAndDrop as well? The original issue also mentions a use case with multiple drag previews but at the moment this is for useDrag only which only for one draggable element if I remember correctly

[reidbarber]

@LFDanLu Good idea, just added.

[rspbot]

Build successful! 🎉

• View the storybook
• View the S2 storybook
• View the documentation
• View the S2 docs

[LFDanLu]

I know this is just gets passed through, but can you add a story or a test just making sure that providing this to useDragAndDrop works?

[rspbot]

Build successful! 🎉

• View the storybook
• View the S2 storybook
• View the documentation
• View the S2 docs

[rspbot]

Build successful! 🎉

• View the storybook
• View the S2 storybook
• View the documentation
• View the S2 docs

[rspbot]

## API Changes

react-aria-components

/react-aria-components:DragAndDropOptions

 DragAndDropOptions {
   acceptedDragTypes?: 'all' | Array<string | symbol> = 'all'
   dropTargetDelegate?: DropTargetDelegate
   getAllowedDropOperations?: () => Array<DropOperation>
   getDropOperation?: (DropTarget, DragTypes, Array<DropOperation>) => DropOperation
   getItems?: (Set<Key>) => Array<DragItem> = () => []
+  getPreviewOffset?: ({
+    previewRect: DOMRect
+  sourceRect: DOMRect
+  pointerPosition: {
+      x: number
+    y: number
+}
+  defaultOffset: {
+      x: number
+    y: number
+}
+}) => {
+    x: number
+  y: number
+}
   isDisabled?: boolean
   onDragEnd?: (DraggableCollectionEndEvent) => void
   onDragMove?: (DraggableCollectionMoveEvent) => void
   onDragStart?: (DraggableCollectionStartEvent) => void
   onDropActivate?: (DroppableCollectionActivateEvent) => void
   onDropEnter?: (DroppableCollectionEnterEvent) => void
   onDropExit?: (DroppableCollectionExitEvent) => void
   onInsert?: (DroppableCollectionInsertDropEvent) => void
   onItemDrop?: (DroppableCollectionOnItemDropEvent) => void
   onMove?: (DroppableCollectionReorderEvent) => void
   onReorder?: (DroppableCollectionReorderEvent) => void
   onRootDrop?: (DroppableCollectionRootDropEvent) => void
   renderDragPreview?: (Array<DragItem>) => JSX.Element
   renderDropIndicator?: (DropTarget, Set<Key>, Key) => JSX.Element
   shouldAcceptItemDrop?: (ItemDropTarget, DragTypes) => boolean
 }

---

@react-aria/dnd

/@react-aria/dnd:DragOptions

 DragOptions {
   getAllowedDropOperations?: () => Array<DropOperation>
   getItems: () => Array<DragItem>
+  getPreviewOffset?: ({
+    previewRect: DOMRect
+  sourceRect: DOMRect
+  pointerPosition: {
+      x: number
+    y: number
+}
+  defaultOffset: {
+      x: number
+    y: number
+}
+}) => {
+    x: number
+  y: number
+}
   hasDragButton?: boolean
   isDisabled?: boolean
   onDragEnd?: (DragEndEvent) => void
   onDragMove?: (DragMoveEvent) => void
   preview?: RefObject<DragPreviewRenderer | null>
 }

---

@react-spectrum/dnd

/@react-spectrum/dnd:DragAndDropOptions

 DragAndDropOptions {
   acceptedDragTypes?: 'all' | Array<string | symbol> = 'all'
   getAllowedDropOperations?: () => Array<DropOperation>
   getDropOperation?: (DropTarget, DragTypes, Array<DropOperation>) => DropOperation
   getItems?: (Set<Key>) => Array<DragItem> = () => []
+  getPreviewOffset?: ({
+    previewRect: DOMRect
+  sourceRect: DOMRect
+  pointerPosition: {
+      x: number
+    y: number
+}
+  defaultOffset: {
+      x: number
+    y: number
+}
+}) => {
+    x: number
+  y: number
+}
   onDragEnd?: (DraggableCollectionEndEvent) => void
   onDragMove?: (DraggableCollectionMoveEvent) => void
   onDragStart?: (DraggableCollectionStartEvent) => void
   onDrop?: (DroppableCollectionDropEvent) => void
   onDropEnter?: (DroppableCollectionEnterEvent) => void
   onDropExit?: (DroppableCollectionExitEvent) => void
   onInsert?: (DroppableCollectionInsertDropEvent) => void
   onItemDrop?: (DroppableCollectionOnItemDropEvent) => void
   onReorder?: (DroppableCollectionReorderEvent) => void
   onRootDrop?: (DroppableCollectionRootDropEvent) => void
   renderPreview?: (Set<Key>, Key) => JSX.Element
   shouldAcceptItemDrop?: (ItemDropTarget, DragTypes) => boolean
 }

---

@react-stately/dnd

/@react-stately/dnd:DraggableCollectionStateOptions

 DraggableCollectionStateOptions {
   collection: Collection<Node<unknown>>
   getAllowedDropOperations?: () => Array<DropOperation>
   getItems: (Set<Key>) => Array<DragItem>
+  getPreviewOffset?: ({
+    previewRect: DOMRect
+  sourceRect: DOMRect
+  pointerPosition: {
+      x: number
+    y: number
+}
+  defaultOffset: {
+      x: number
+    y: number
+}
+}) => {
+    x: number
+  y: number
+}
   isDisabled?: boolean
   onDragEnd?: (DraggableCollectionEndEvent) => void
   onDragMove?: (DraggableCollectionMoveEvent) => void
   onDragStart?: (DraggableCollectionStartEvent) => void
   selectionManager: MultipleSelectionManager
 }

/@react-stately/dnd:DraggableCollectionState

 DraggableCollectionState {
   collection: Collection<Node<unknown>>
   draggedKey: Key | null
   draggingKeys: Set<Key>
   endDrag: (DraggableCollectionEndEvent) => void
   getAllowedDropOperations?: () => Array<DropOperation>
   getItems: (Key) => Array<DragItem>
   getKeysForDrag: (Key) => Set<Key>
+  getPreviewOffset?: ({
+    previewRect: DOMRect
+  sourceRect: DOMRect
+  pointerPosition: {
+      x: number
+    y: number
+}
+  defaultOffset: {
+      x: number
+    y: number
+}
+}) => {
+    x: number
+  y: number
+}
   isDisabled?: boolean
   isDragging: (Key) => boolean
   moveDrag: (DragMoveEvent) => void
   preview?: RefObject<DragPreviewRenderer | null>
   startDrag: (Key, DragStartEvent) => void
 }

---

[devongovett]

What do you think about the API proposed here #5409 (comment)? Instead of a separate callback, you'd return an object with both the preview element and the position from renderDragPreview.

[reidbarber]

@devongovett I think that would be good so we could support different drag previews based on the data type. Any opinions about keeping the options that were passed into getPreviewOffset, and passing them into renderDragPreview instead? I think those could be useful, but it's also a lot of info