Update Spectrum DnD docs and rename Spectrum DnD hook (#3548)

* updating ListView drag and drop examples with updated api

* updating dnd.mdx

* fixing lint and adding example with getDropOperation

* fixing DragHooks type in docs

The DragHooks type looks really weird in the types popover without this change

* fixing typos and stuff

* collapsing similar code and highlighting changes in ListView dnd stories

* adding images from aria/dnd.mdx

* adding low level api example and fixing other sections

* fixing merge

* fix merge conflict

* adding description for spectrum dnd hook

* pulling out ListView dnd docs changes

* trying to fix links for build

* forgot two links

* Rename useDnDHooks and ListView dndHooks prop (#3577)

* updating useDnDHooks and dndHooks ListView prop name

* fix merge

Author: LFDanLu

packages/@react-spectrum/dnd/docs/dnd.mdx

@@ -12,6 +12,6 @@
 
 /// <reference types="css-module-types" />
 
-export type {DnDOptions, DnDHooks} from './useDnDHooks';
-export {useDnDHooks} from './useDnDHooks';
+export type {DragAndDropOptions, DragAndDropHooks} from './useDragAndDrop';
+export {useDragAndDrop} from './useDragAndDrop';
 export {DIRECTORY_DRAG_TYPE} from '@react-aria/dnd';

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

@@ -37,12 +37,13 @@ import {
   useDraggableCollectionState,
   useDroppableCollectionState
 } from '@react-stately/dnd';
-
 import {DroppableCollectionProps} from '@react-types/shared';
 import {Key, RefObject, useMemo} from 'react';
 
+interface DraggableCollectionStateOpts extends Omit<DraggableCollectionStateOptions, 'getItems'> {}
+
 interface DragHooks {
-  useDraggableCollectionState?: (props: Omit<DraggableCollectionStateOptions, 'getItems'>) => DraggableCollectionState,
+  useDraggableCollectionState?: (props: DraggableCollectionStateOpts) => DraggableCollectionState,
   useDraggableCollection?: (props: DraggableCollectionOptions, state: DraggableCollectionState, ref: RefObject<HTMLElement>) => void,
   useDraggableItem?: (props: DraggableItemProps, state: DraggableCollectionState) => DraggableItemResult,
   DragPreview?: typeof DragPreview
@@ -55,20 +56,24 @@ interface DropHooks {
   useDropIndicator?: (props: DropIndicatorProps, state: DroppableCollectionState, ref: RefObject<HTMLElement>) => DropIndicatorAria
 }
 
-export interface DnDHooks {
-  dndHooks: DragHooks & DropHooks & {isVirtualDragging?: () => boolean}
+export interface DragAndDropHooks {
+  /** Drag and drop hooks for the collection element.  */
+  dragAndDropHooks: DragHooks & DropHooks & {isVirtualDragging?: () => boolean}
 }
 
-export interface DnDOptions extends Omit<DraggableCollectionProps, 'preview' | 'getItems'>, DroppableCollectionProps {
+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[]
 }
 
-export function useDnDHooks(options: DnDOptions): DnDHooks {
-  let dndHooks = useMemo(() => {
+/**
+ * Provides the hooks required to enable drag and drop behavior for a drag and drop compatible React Spectrum component.
+ */
+export function useDragAndDrop(options: DragAndDropOptions): DragAndDropHooks {
+  let dragAndDropHooks = useMemo(() => {
     let {
       onDrop,
       onInsert,
@@ -110,6 +115,6 @@ export function useDnDHooks(options: DnDOptions): DnDHooks {
   }, [options]);
 
   return {
-    dndHooks: dndHooks
+    dragAndDropHooks: dragAndDropHooks
   };
 }

packages/@react-spectrum/dnd/src/useDnDHooks.ts renamed to packages/@react-spectrum/dnd/src/useDragAndDrop.ts

@@ -11,11 +11,11 @@ interface InsertionIndicatorProps {
 }
 
 export default function InsertionIndicator(props: InsertionIndicatorProps) {
-  let {dropState, dndHooks} = useContext(ListViewContext);
+  let {dropState, dragAndDropHooks} = useContext(ListViewContext);
   const {target, isPresentationOnly} = props;
 
   let ref = useRef();
-  let {dropIndicatorProps} = dndHooks.useDropIndicator(props, dropState, ref);
+  let {dropIndicatorProps} = dragAndDropHooks.useDropIndicator(props, dropState, ref);
   let {visuallyHiddenProps} = useVisuallyHidden();
 
   let isDropTarget = dropState.isDropTarget(target);

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

@@ -13,7 +13,7 @@
 import {AriaGridListProps, useGridList} from '@react-aria/gridlist';
 import {AsyncLoadable, DOMRef, LoadingState, SpectrumSelectionProps, StyleProps} from '@react-types/shared';
 import {classNames, useDOMRef, useStyleProps} from '@react-spectrum/utils';
-import type {DnDHooks} from '@react-spectrum/dnd';
+import type {DragAndDropHooks} from '@react-spectrum/dnd';
 import type {DraggableCollectionState, DroppableCollectionState} from '@react-stately/dnd';
 import type {DroppableCollectionResult} from '@react-aria/dnd';
 import {filterDOMProps, mergeProps, useLayoutEffect} from '@react-aria/utils';
@@ -56,17 +56,16 @@ export interface SpectrumListViewProps<T> extends AriaGridListProps<T>, StylePro
    */
   onAction?: (key: Key) => void,
   /**
-   * The drag and drop hooks returned by `useDnDHooks` used to enable drag and drop behavior for the ListView.
-   * @private
+   * The drag and drop hooks returned by `useDragAndDrop` used to enable drag and drop behavior for the ListView.
    */
-  dndHooks?: DnDHooks['dndHooks']
+  dragAndDropHooks?: DragAndDropHooks['dragAndDropHooks']
 }
 
 interface ListViewContextValue<T> {
   state: ListState<T>,
   dragState: DraggableCollectionState,
   dropState: DroppableCollectionState,
-  dndHooks: DnDHooks['dndHooks'],
+  dragAndDropHooks: DragAndDropHooks['dragAndDropHooks'],
   onAction:(key: Key) => void,
   isListDraggable: boolean,
   isListDroppable: boolean,
@@ -118,11 +117,11 @@ function ListView<T extends object>(props: SpectrumListViewProps<T>, ref: DOMRef
     isQuiet,
     overflowMode = 'truncate',
     onAction,
-    dndHooks,
+    dragAndDropHooks,
     ...otherProps
   } = props;
-  let isListDraggable = !!dndHooks?.useDraggableCollectionState;
-  let isListDroppable = !!dndHooks?.useDroppableCollectionState;
+  let isListDraggable = !!dragAndDropHooks?.useDraggableCollectionState;
+  let isListDroppable = !!dragAndDropHooks?.useDroppableCollectionState;
   let dragHooksProvided = useRef(isListDraggable);
   let dropHooksProvided = useRef(isListDroppable);
   if (dragHooksProvided.current !== isListDraggable) {
@@ -144,12 +143,12 @@ function ListView<T extends object>(props: SpectrumListViewProps<T>, ref: DOMRef
   let dragState: DraggableCollectionState;
   let preview = useRef(null);
   if (isListDraggable) {
-    dragState = dndHooks.useDraggableCollectionState({
+    dragState = dragAndDropHooks.useDraggableCollectionState({
       collection,
       selectionManager,
       preview
     });
-    dndHooks.useDraggableCollection({}, dragState, domRef);
+    dragAndDropHooks.useDraggableCollection({}, dragState, domRef);
   }
   let layout = useListLayout(
     state,
@@ -160,16 +159,16 @@ function ListView<T extends object>(props: SpectrumListViewProps<T>, ref: DOMRef
   layout.allowDisabledKeyFocus = state.selectionManager.disabledBehavior === 'selection' || !!dragState?.draggingKeys.size;
 
 
-  let DragPreview = dndHooks?.DragPreview;
+  let DragPreview = dragAndDropHooks?.DragPreview;
   let dropState: DroppableCollectionState;
   let droppableCollection: DroppableCollectionResult;
   let isRootDropTarget: boolean;
   if (isListDroppable) {
-    dropState = dndHooks.useDroppableCollectionState({
+    dropState = dragAndDropHooks.useDroppableCollectionState({
       collection,
       selectionManager
     });
-    droppableCollection = dndHooks.useDroppableCollection({
+    droppableCollection = dragAndDropHooks.useDroppableCollection({
       keyboardDelegate: layout,
       dropTargetDelegate: layout
     }, dropState, domRef);
@@ -206,7 +205,7 @@ function ListView<T extends object>(props: SpectrumListViewProps<T>, ref: DOMRef
   let hasAnyChildren = useMemo(() => [...collection].some(item => item.hasChildNodes), [collection]);
 
   return (
-    <ListViewContext.Provider value={{state, dragState, dropState, dndHooks, onAction, isListDraggable, isListDroppable, layout, loadingState}}>
+    <ListViewContext.Provider value={{state, dragState, dropState, dragAndDropHooks, onAction, isListDraggable, isListDroppable, layout, loadingState}}>
       <FocusScope>
         <FocusRing focusRingClass={classNames(listStyles, 'focus-ring')}>
           <Virtualizer

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

@@ -49,7 +49,7 @@ export function ListViewItem<T>(props: ListViewItemProps<T>) {
     isListDraggable,
     isListDroppable,
     layout,
-    dndHooks,
+    dragAndDropHooks,
     loadingState
   } = useContext(ListViewContext);
   let {direction} = useLocale();
@@ -82,7 +82,7 @@ export function ListViewItem<T>(props: ListViewItemProps<T>) {
   let draggableItem: DraggableItemResult;
   if (isListDraggable) {
     // eslint-disable-next-line react-hooks/rules-of-hooks
-    draggableItem = dndHooks.useDraggableItem({key: item.key, hasDragButton: true}, dragState);
+    draggableItem = dragAndDropHooks.useDraggableItem({key: item.key, hasDragButton: true}, dragState);
     if (isDisabled) {
       draggableItem = null;
     }
@@ -95,7 +95,7 @@ export function ListViewItem<T>(props: ListViewItemProps<T>) {
     let target = {type: 'item', key: item.key, dropPosition: 'on'} as DropTarget;
     isDropTarget = dropState.isDropTarget(target);
     // eslint-disable-next-line react-hooks/rules-of-hooks
-    dropIndicator = dndHooks.useDropIndicator({target}, dropState, dropIndicatorRef);
+    dropIndicator = dragAndDropHooks.useDropIndicator({target}, dropState, dropIndicatorRef);
   }
 
   let dragButtonRef = React.useRef();
@@ -147,7 +147,7 @@ export function ListViewItem<T>(props: ListViewItemProps<T>) {
     focusProps,
     // Remove tab index from list row if performing a screenreader drag. This prevents TalkBack from focusing the row,
     // allowing for single swipe navigation between row drop indicator
-    dndHooks?.isVirtualDragging() && {tabIndex: null}
+    dragAndDropHooks?.isVirtualDragging() && {tabIndex: null}
   );
 
   let isFirstRow = item.prevKey == null;

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

@@ -3,9 +3,9 @@ import React, {useContext, useRef} from 'react';
 import {useVisuallyHidden} from '@react-aria/visually-hidden';
 
 export default function RootDropIndicator() {
-  let {dropState, dndHooks} = useContext(ListViewContext);
+  let {dropState, dragAndDropHooks} = useContext(ListViewContext);
   let ref = useRef();
-  let {dropIndicatorProps} = dndHooks.useDropIndicator({
+  let {dropIndicatorProps} = dragAndDropHooks.useDropIndicator({
     target: {type: 'root'}
   }, dropState, ref);
   let isDropTarget = dropState.isDropTarget({type: 'root'});