Support onAction and drag and drop in listbox (#3421)

Author: devongovett

packages/@react-aria/dnd/intl/en-US.json

@@ -2,8 +2,13 @@
   "dragItem": "Drag {itemText}",
   "dragSelectedItems": "Drag {count, plural, one {# selected item} other {# selected items}}",
   "dragDescriptionKeyboard": "Press Enter to start dragging.",
+  "dragDescriptionKeyboardAlt": "Press Alt + Enter to start dragging.",
   "dragDescriptionTouch": "Double tap to start dragging.",
   "dragDescriptionVirtual": "Click to start dragging.",
+  "dragDescriptionLongPress": "Long press to start dragging.",
+  "dragSelectedKeyboard": "Press Enter to drag {count, plural, one {# selected item} other {# selected items}}.",
+  "dragSelectedKeyboardAlt": "Press Alt + Enter to drag {count, plural, one {# selected item} other {# selected items}}.",
+  "dragSelectedLongPress": "Long press to drag {count, plural, one {# selected item} other {# selected items}}.",
   "dragStartedKeyboard": "Started dragging. Press Tab to navigate to a drop target, then press Enter to drop, or press Escape to cancel.",
   "dragStartedTouch": "Started dragging. Navigate to a drop target, then double tap to drop.",
   "dragStartedVirtual": "Started dragging. Navigate to a drop target, then click or press Enter to drop.",

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

@@ -28,7 +28,8 @@ export interface DragOptions {
   onDragEnd?: (e: DragEndEvent) => void,
   getItems: () => DragItem[],
   preview?: RefObject<DragPreviewRenderer>,
-  getAllowedDropOperations?: () => DropOperation[]
+  getAllowedDropOperations?: () => DropOperation[],
+  hasDragButton?: boolean
 }
 
 export interface DragResult {
@@ -53,6 +54,7 @@ const MESSAGES = {
 };
 
 export function useDrag(options: DragOptions): DragResult {
+  let {hasDragButton} = options;
   let stringFormatter = useLocalizedStringFormatter(intlMessages);
   let state = useRef({
     options,
@@ -62,12 +64,21 @@ export function useDrag(options: DragOptions): DragResult {
   state.options = options;
   let [isDragging, setDragging] = useState(false);
   let {addGlobalListener, removeAllGlobalListeners} = useGlobalListeners();
+  let modalityOnPointerDown = useRef<string>(null);
 
   let onDragStart = (e: DragEvent) => {
     if (e.defaultPrevented) {
       return;
     }
 
+    // If this drag was initiated by a mobile screen reader (e.g. VoiceOver or TalkBack), enter virtual dragging mode.
+    if (modalityOnPointerDown.current === 'virtual') {
+      e.preventDefault();
+      startDragging(e.target as HTMLElement);
+      modalityOnPointerDown.current = null;
+      return;
+    }
+
     if (typeof options.onDragStart === 'function') {
       options.onDragStart({
         type: 'dragstart',
@@ -171,8 +182,12 @@ export function useDrag(options: DragOptions): DragResult {
       return;
     }
 
+    startDragging(e.target as HTMLElement);
+  };
+
+  let startDragging = (target: HTMLElement) => {
     if (typeof state.options.onDragStart === 'function') {
-      let rect = (e.target as HTMLElement).getBoundingClientRect();
+      let rect = target.getBoundingClientRect();
       state.options.onDragStart({
         type: 'dragstart',
         x: rect.x + (rect.width / 2),
@@ -181,7 +196,7 @@ export function useDrag(options: DragOptions): DragResult {
     }
 
     DragManager.beginDragging({
-      element: e.target as HTMLElement,
+      element: target,
       items: state.options.getItems(),
       allowedDropOperations: typeof state.options.getAllowedDropOperations === 'function'
         ? state.options.getAllowedDropOperations()
@@ -198,12 +213,67 @@ export function useDrag(options: DragOptions): DragResult {
   };
 
   let modality = useDragModality();
-  let descriptionProps = useDescription(
-    stringFormatter.format(!isDragging ? MESSAGES[modality].start : MESSAGES[modality].end)
-  );
+  let message: string;
+  if (!isDragging) {
+    if (modality === 'touch' && !hasDragButton) {
+      message = 'dragDescriptionLongPress';
+    } else {
+      message = MESSAGES[modality].start;
+    }
+  } else {
+    message = MESSAGES[modality].end;
+  }
+
+  let descriptionProps = useDescription(stringFormatter.format(message));
+
+  let interactions: HTMLAttributes<HTMLElement>;
+  if (!hasDragButton) {
+    // If there's no separate button to trigger accessible drag and drop mode,
+    // then add event handlers to the draggable element itself to start dragging.
+    // For keyboard, we use the Enter key in a capturing listener to prevent other
+    // events such as selection from also occurring. We attempt to infer whether a
+    // pointer event (e.g. long press) came from a touch screen reader, and then initiate
+    // dragging in the native onDragStart listener above.
+
+    interactions = {
+      ...descriptionProps,
+      onPointerDown({nativeEvent: e}) {
+        // Try to detect virtual drags.
+        if (e.width < 1 && e.height < 1) {
+          // iOS VoiceOver.
+          modalityOnPointerDown.current = 'virtual';
+        } else {
+          let rect = (e.target as HTMLElement).getBoundingClientRect();
+          let centerX = rect.width / 2;
+          let centerY = rect.height / 2;
+
+          if (Math.abs(e.offsetX - centerX) < 0.5 && Math.abs(e.offsetY - centerY) < 0.5) {
+            // Android TalkBack.
+            modalityOnPointerDown.current = 'virtual';
+          } else {
+            modalityOnPointerDown.current = e.pointerType;
+          }
+        }
+      },
+      onKeyDownCapture(e) {
+        if (e.target === e.currentTarget && e.key === 'Enter') {
+          e.preventDefault();
+          e.stopPropagation();
+        }
+      },
+      onKeyUpCapture(e) {
+        if (e.target === e.currentTarget && e.key === 'Enter') {
+          e.preventDefault();
+          e.stopPropagation();
+          startDragging(e.target as HTMLElement);
+        }
+      }
+    };
+  }
 
   return {
     dragProps: {
+      ...interactions,
       draggable: 'true',
       onDragStart,
       onDrag,

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

@@ -15,26 +15,58 @@ import {DraggableCollectionState} from '@react-stately/dnd';
 import {HTMLAttributes, Key} from 'react';
 // @ts-ignore
 import intlMessages from '../intl/*.json';
+import {useDescription} from '@react-aria/utils';
 import {useDrag} from './useDrag';
+import {useDragModality} from './utils';
 import {useLocalizedStringFormatter} from '@react-aria/i18n';
 
 export interface DraggableItemProps {
-  key: Key
+  /** The key of the draggable item within the collection. */
+  key: Key,
+  /**
+   * Whether the item has an explicit focusable drag affordance to initiate accessible drag and drop mode.
+   * If true, the dragProps will omit these event handlers, and they will be applied to dragButtonProps instead.
+   */
+  hasDragButton?: boolean,
+  /**
+   * Whether the item has a primary action (e.g. Enter key or long press) that would
+   * conflict with initiating accessible drag and drop. If true, the Alt key must be held to
+   * start dragging with a keyboard, and long press is disabled until selection mode is entered.
+   * This should be passed from the associated collection item hook (e.g. useOption, useGridListItem, etc.).
+   */
+  hasAction?: boolean
 }
 
 export interface DraggableItemResult {
   dragProps: HTMLAttributes<HTMLElement>,
   dragButtonProps: AriaButtonProps
 }
 
+const MESSAGES = {
+  keyboard: {
+    selected: 'dragSelectedKeyboard',
+    notSelected: 'dragDescriptionKeyboard'
+  },
+  touch: {
+    selected: 'dragSelectedLongPress',
+    notSelected: 'dragDescriptionLongPress'
+  },
+  virtual: {
+    selected: 'dragDescriptionVirtual',
+    notSelected: 'dragDescriptionVirtual'
+  }
+};
+
 export function useDraggableItem(props: DraggableItemProps, state: DraggableCollectionState): DraggableItemResult {
   let stringFormatter = useLocalizedStringFormatter(intlMessages);
+  let isDisabled = state.selectionManager.isDisabled(props.key);
   let {dragProps, dragButtonProps} = useDrag({
     getItems() {
       return state.getItems(props.key);
     },
     preview: state.preview,
     getAllowedDropOperations: state.getAllowedDropOperations,
+    hasDragButton: props.hasDragButton,
     onDragStart(e) {
       state.startDrag(props.key, e);
     },
@@ -48,19 +80,63 @@ export function useDraggableItem(props: DraggableItemProps, state: DraggableColl
 
   let item = state.collection.getItem(props.key);
   let numKeysForDrag = state.getKeysForDrag(props.key).size;
-  let isSelected = state.selectionManager.isSelected(props.key);
-  let message: string;
-  if (isSelected && numKeysForDrag > 1) {
-    message = stringFormatter.format('dragSelectedItems', {count: numKeysForDrag});
+  let isSelected = numKeysForDrag > 1 && state.selectionManager.isSelected(props.key);
+  let dragButtonLabel: string;
+  let description: string;
+
+  // Override description to include selected item count.
+  let modality = useDragModality();
+  if (!props.hasDragButton) {
+    let msg = MESSAGES[modality][isSelected ? 'selected' : 'notSelected'];
+    if (props.hasAction && modality === 'keyboard') {
+      msg += 'Alt';
+    }
+
+    if (isSelected) {
+      description = stringFormatter.format(msg, {count: numKeysForDrag});
+    } else {
+      description = stringFormatter.format(msg);
+    }
   } else {
-    message = stringFormatter.format('dragItem', {itemText: item?.textValue ?? ''});
+    if (isSelected) {
+      dragButtonLabel = stringFormatter.format('dragSelectedItems', {count: numKeysForDrag});
+    } else {
+      dragButtonLabel = stringFormatter.format('dragItem', {itemText: item?.textValue ?? ''});
+    }
+  }
+
+  let descriptionProps = useDescription(description);
+  if (description) {
+    Object.assign(dragProps, descriptionProps);
+  }
+
+  if (!props.hasDragButton && props.hasAction) {
+    let {onKeyDownCapture, onKeyUpCapture} = dragProps;
+    if (modality === 'touch') {
+      // Remove long press description if an action is present, because in that case long pressing selects the item.
+      delete dragProps['aria-describedby'];
+    }
+
+    // Require Alt key if there is a conflicting action.
+    dragProps.onKeyDownCapture = e => {
+      if (e.altKey) {
+        onKeyDownCapture(e);
+      }
+    };
+
+    dragProps.onKeyUpCapture = e => {
+      if (e.altKey) {
+        onKeyUpCapture(e);
+      }
+    };
   }
 
   return {
-    dragProps,
+    dragProps: isDisabled ? {} : dragProps,
     dragButtonProps: {
       ...dragButtonProps,
-      'aria-label': message
+      isDisabled,
+      'aria-label': dragButtonLabel
     }
   };
 }

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

@@ -153,7 +153,7 @@ function DraggableCollectionItem({item, state, dragState}) {
     shouldSelectOnPressUp: true
   }, state, cellRef);
 
-  let {dragProps, dragButtonProps} = useDraggableItem({key: item.key}, dragState);
+  let {dragProps, dragButtonProps} = useDraggableItem({key: item.key, hasDragButton: true}, dragState);
 
   let buttonRef = React.useRef();
   let {buttonProps} = useButton({

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

@@ -0,0 +1,73 @@
+import {classNames} from '@react-spectrum/utils';
+import dndStyles from './dnd.css';
+import {mergeProps} from '@react-aria/utils';
+import React from 'react';
+import {useDraggableCollectionState} from '@react-stately/dnd';
+import {useDraggableItem} from '@react-aria/dnd';
+import {useFocusRing} from '@react-aria/focus';
+import {useListBox, useOption} from '@react-aria/listbox';
+import {useListState} from '@react-stately/list';
+
+export function DraggableListBox(props) {
+  let state = useListState(props);
+  let ref = React.useRef();
+  let {listBoxProps} = useListBox(
+    {
+      ...props,
+      shouldSelectOnPressUp: true
+    },
+    state,
+    ref
+  );
+
+  let dragState = useDraggableCollectionState({
+    ...props,
+    collection: state.collection,
+    selectionManager: state.selectionManager,
+    getItems: props.getItems || ((keys) => (
+      [...keys].map((key) => {
+        let item = state.collection.getItem(key);
+
+        return {
+          'text/plain': item.textValue
+        };
+      })
+    ))
+  });
+
+  return (
+    <ul {...listBoxProps} ref={ref} className={dndStyles['draggable-listbox']}>
+      {[...state.collection].map((item) => (
+        <Option
+          key={item.key}
+          item={item}
+          state={state}
+          dragState={dragState} />
+      ))}
+    </ul>
+  );
+}
+
+function Option({item, state, dragState}) {
+  let ref = React.useRef();
+  let {optionProps, isPressed, hasAction} = useOption(
+    {key: item.key},
+    state,
+    ref
+  );
+  let {isFocusVisible, focusProps} = useFocusRing();
+
+  let {dragProps} = useDraggableItem({
+    key: item.key,
+    hasAction
+  }, dragState);
+
+  return (
+    <li
+      {...mergeProps(dragProps, optionProps, focusProps)}
+      ref={ref}
+      className={classNames(dndStyles, 'option', {'focus-visible': isFocusVisible, 'pressed': isPressed})}>
+      {item.rendered}
+    </li>
+  );
+}

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

@@ -223,7 +223,7 @@ function CollectionItem({item, state, dragState, dropState}) {
     shouldSelectOnPressUp: true
   }, state, cellRef);
 
-  let {dragProps, dragButtonProps} = useDraggableItem({key: item.key}, dragState);
+  let {dragProps, dragButtonProps} = useDraggableItem({key: item.key, hasDragButton: true}, dragState);
 
   let dragButtonRef = React.useRef();
   let {buttonProps} = useButton({
@@ -239,10 +239,10 @@ function CollectionItem({item, state, dragState, dropState}) {
   let id = useId();
 
   return (
-    <div {...rowProps} ref={rowRef} style={{outline: 'none'}} aria-labelledby={id}>
+    <div {...mergeProps(rowProps, dragProps)} ref={rowRef} style={{outline: 'none'}} aria-labelledby={id}>
       <FocusRing focusRingClass={classNames(dndStyles, 'focus-ring')}>
         <div
-          {...mergeProps(gridCellProps, dragProps)}
+          {...gridCellProps}
           aria-labelledby={id}
           ref={cellRef}
           className={classNames(dndStyles, 'draggable', 'droppable', {