Custom drag preview support in TableView/ListView (#4396)

* support custom drag previews

* improve preview styles in story

* improve custom preview example

* add support to listview

* add tests

* improve prop description

* add story

Author: reidbarber

packages/@react-spectrum/dnd/src/useDragAndDrop.ts

@@ -58,15 +58,17 @@ interface DropHooks {
 
 export interface DragAndDropHooks {
   /** Drag and drop hooks for the collection element.  */
-  dragAndDropHooks: DragHooks & DropHooks & {isVirtualDragging?: () => boolean}
+  dragAndDropHooks: DragHooks & DropHooks & {isVirtualDragging?: () => boolean, renderPreview?: (keys: Set<Key>, draggedKey: Key) => JSX.Element}
 }
 
 export interface DragAndDropOptions extends Omit<DraggableCollectionProps, 'preview' | 'getItems'>, DroppableCollectionProps {
   /**
    * A function that returns the items being dragged. If not specified, we assume that the collection is not draggable.
    * @default () => []
    */
-  getItems?: (keys: Set<Key>) => DragItem[]
+  getItems?: (keys: Set<Key>) => DragItem[],
+  /** Provide a custom drag preview. `draggedKey` represents the key of the item the user actually dragged. */
+  renderPreview?: (keys: Set<Key>, draggedKey: Key) => JSX.Element
 }
 
 /**
@@ -80,20 +82,22 @@ export function useDragAndDrop(options: DragAndDropOptions): DragAndDropHooks {
       onItemDrop,
       onReorder,
       onRootDrop,
-      getItems
+      getItems,
+      renderPreview
      } = options;
 
     let isDraggable = !!getItems;
     let isDroppable = !!(onDrop || onInsert || onItemDrop || onReorder || onRootDrop);
 
-    let hooks = {} as DragHooks & DropHooks & {isVirtualDragging?: () => boolean};
+    let hooks = {} as DragHooks & DropHooks & {isVirtualDragging?: () => boolean, renderPreview?: (keys: Set<Key>, draggedKey: Key) => JSX.Element};
     if (isDraggable) {
       hooks.useDraggableCollectionState = function useDraggableCollectionStateOverride(props: DraggableCollectionStateOptions) {
         return useDraggableCollectionState({...props, ...options});
       };
       hooks.useDraggableCollection = useDraggableCollection;
       hooks.useDraggableItem = useDraggableItem;
       hooks.DragPreview = DragPreview;
+      hooks.renderPreview = renderPreview;
     }
 
     if (isDroppable) {

packages/@react-spectrum/list/src/ListView.tsx

@@ -290,6 +290,9 @@ function ListView<T extends object>(props: SpectrumListViewProps<T>, ref: DOMRef
       {DragPreview && isListDraggable &&
         <DragPreview ref={preview}>
           {() => {
+            if (dragAndDropHooks.renderPreview) {
+              return dragAndDropHooks.renderPreview(dragState.draggingKeys, dragState.draggedKey);
+            }
             let item = state.collection.getItem(dragState.draggedKey);
             let itemCount = dragState.draggingKeys.size;
             let itemHeight = layout.getLayoutInfo(dragState.draggedKey).rect.height;

packages/@react-spectrum/list/stories/ListView.stories.tsx

@@ -148,7 +148,7 @@ export default {
 
 export type ListViewStory = ComponentStoryObj<typeof ListView>;
 
-export const DefaultListBox: ListViewStory = {
+export const Default: ListViewStory = {
   render: (args) => (
     <ListView width="250px" aria-label="default ListView" {...args}>
       <Item textValue="Adobe Photoshop">Adobe Photoshop</Item>

packages/@react-spectrum/list/stories/ListViewDnD.stories.tsx

@@ -5,6 +5,7 @@ import {Droppable} from '@react-aria/dnd/stories/dnd.stories';
 import {Flex} from '@react-spectrum/layout';
 import {ListView} from '../';
 import React from 'react';
+import {View} from '@react-spectrum/view';
 
 export default {
   title: 'ListView/Drag and Drop',
@@ -70,6 +71,28 @@ export const DragOut: ListViewStory = {
   name: 'Drag out of list'
 };
 
+export const CustomDragPreview: ListViewStory = {
+  render: (args) => (
+    <Flex direction="row" wrap alignItems="center">
+      <input />
+      <Droppable />
+      <DragExample
+        dragHookOptions={{
+          onDragStart: action('dragStart'),
+          onDragEnd: action('dragEnd'),
+          renderPreview: (keys, draggedKey) => (
+            <View backgroundColor="gray-50" padding="size-100" borderRadius="medium" borderWidth="thin" borderColor="blue-500">
+              <strong>Custom Preview</strong>
+              <div>Keys: [{[...keys].join(', ')}]</div>
+              <div>Dragged: {draggedKey}</div>
+            </View>
+          )}}
+        listViewProps={args} />
+    </Flex>
+  ),
+  name: 'Custom drag preview'
+};
+
 export const DragWithin: ListViewStory = {
   render: (args) => (
     <Flex direction="row" wrap alignItems="center">

packages/@react-spectrum/list/test/ListViewDnd.test.js

@@ -166,6 +166,25 @@ describe('ListView', function () {
         expect(cellText).toHaveLength(1);
       });
 
+      it('should render a custom drag preview', function () {
+        let renderPreview = jest.fn().mockImplementation((keys, draggedKey) => <div>Custom preview for [{[...keys].join(', ')}] , while dragging {draggedKey}.</div>);
+        let {getAllByRole} = render(
+          <DraggableListView dragHookOptions={{renderPreview}} listViewProps={{selectedKeys: ['a', 'b']}} />
+        );
+
+        let row = getAllByRole('row')[0];
+        let cell = within(row).getByRole('gridcell');
+
+        let dataTransfer = new DataTransfer();
+
+        fireEvent.pointerDown(cell, {pointerType: 'mouse', button: 0, pointerId: 1, clientX: 5, clientY: 5});
+        fireEvent(cell, new DragEvent('dragstart', {dataTransfer, clientX: 5, clientY: 5}));
+        expect(dataTransfer._dragImage.node.tagName).toBe('DIV');
+        expect(dataTransfer._dragImage.node.textContent).toBe('Custom preview for [a, b] , while dragging a.');
+        expect(dataTransfer._dragImage.x).toBe(5);
+        expect(dataTransfer._dragImage.y).toBe(5);
+      });
+
       it('should allow drag and drop of a single row', async function () {
         let {getAllByRole, getByText} = render(
           <DraggableListView />

packages/@react-spectrum/table/src/TableView.tsx

@@ -562,6 +562,9 @@ function TableView<T extends object>(props: SpectrumTableProps<T>, ref: DOMRef<H
       {DragPreview && isTableDraggable &&
         <DragPreview ref={preview}>
           {() => {
+            if (dragAndDropHooks.renderPreview) {
+              return dragAndDropHooks.renderPreview(dragState.draggingKeys, dragState.draggedKey);
+            }
             let itemCount = dragState.draggingKeys.size;
             let maxWidth = bodyRef.current.getBoundingClientRect().width;
             let height = ROW_HEIGHTS[density][scale];

packages/@react-spectrum/table/stories/TableDnD.stories.tsx

@@ -13,12 +13,14 @@
 import {action} from '@storybook/addon-actions';
 import {ComponentMeta} from '@storybook/react';
 import defaultConfig from './Table.stories';
+import {Divider} from '@react-spectrum/divider';
 import {DragBetweenTablesExample, DragBetweenTablesRootOnlyExample, DragExample, DragOntoRowExample, ReorderExample} from './TableDnDExamples';
 import {Droppable} from '@react-aria/dnd/stories/dnd.stories';
 import {Flex} from '@react-spectrum/layout';
 import React from 'react';
 import {TableStory} from './Table.stories';
 import {TableView} from '../';
+import {View} from '@react-spectrum/view';
 
 export default {
   ...defaultConfig,
@@ -39,6 +41,30 @@ export const DragOutOfTable: TableStory = {
   ),
   name: 'Drag out of table'
 };
+export const CustomDragPreview: TableStory = {
+  args: {
+    disabledKeys: ['Foo 2']
+  },
+  render: (args) => (
+    <Flex direction="row" wrap alignItems="center" gap="size-200">
+      <Droppable />
+      <DragExample
+        dragHookOptions={{
+          onDragStart: action('dragStart'),
+          onDragEnd: action('dragEnd'),
+          renderPreview: (keys, draggedKey) => (
+            <View backgroundColor="gray-50" padding="size-100" borderRadius="medium" borderWidth="thin" borderColor="blue-500">
+              <strong>Custom Preview</strong>
+              <Divider size="S" />
+              <div>Keys: [{[...keys].join(', ')}]</div>
+              <div>Dragged: {draggedKey}</div>
+            </View>
+          )}}
+        tableViewProps={args} />
+    </Flex>
+  ),
+  storyName: 'Custom drag preview'
+};
 
 export const DragWithinTable: TableStory = {
   args: {

packages/@react-spectrum/table/test/TableDnd.test.js

@@ -168,6 +168,29 @@ describe('TableView', function () {
         expect(cellText).toHaveLength(1);
       });
 
+      it('should render a custom drag preview', function () {
+        let renderPreview = jest.fn().mockImplementation((keys, draggedKey) => <div>Custom preview for [{[...keys].join(', ')}] , while dragging {draggedKey}.</div>);
+        let {getByRole} = render(
+          <DraggableTableView dragHookOptions={{renderPreview}} tableViewProps={{selectedKeys: ['a', 'b']}} />
+        );
+
+        let grid = getByRole('grid');
+        let rowgroups = within(grid).getAllByRole('rowgroup');
+        let rows = within(rowgroups[1]).getAllByRole('row');
+        let row = rows[0];
+        let cell = within(row).getAllByRole('rowheader')[0];
+
+        let dataTransfer = new DataTransfer();
+
+        fireEvent.pointerDown(cell, {pointerType: 'mouse', button: 0, pointerId: 1, clientX: 5, clientY: 5});
+        fireEvent(cell, new DragEvent('dragstart', {dataTransfer, clientX: 5, clientY: 5}));
+        expect(dataTransfer._dragImage.node.tagName).toBe('DIV');
+        expect(dataTransfer._dragImage.node.textContent).toBe('Custom preview for [a, b] , while dragging a.');
+        expect(dataTransfer._dragImage.x).toBe(5);
+        expect(dataTransfer._dragImage.y).toBe(5);
+      });
+
+
       it('should allow drag and drop of a single row', async function () {
         let {getByRole, getByText} = render(
           <DraggableTableView />