@react-aria/dnd 3.0.0-alpha.9 → 3.0.0-nightly-4980928d3-240906

package/src/useAutoScroll.ts

@@ -10,16 +10,22 @@
  * governing permissions and limitations under the License.
  */
 
-import {getScrollParent, isIOS, isWebKit} from '@react-aria/utils';
-import {RefObject, useCallback, useEffect, useRef} from 'react';
+import {getScrollParent, isIOS, isScrollable, isWebKit} from '@react-aria/utils';
+import {RefObject} from '@react-types/shared';
+import {useCallback, useEffect, useRef} from 'react';
 
 const AUTOSCROLL_AREA_SIZE = 20;
 
-export function useAutoScroll(ref: RefObject<Element>) {
+export function useAutoScroll(ref: RefObject<Element | null>) {
   let scrollableRef = useRef<Element>(null);
+  let scrollableX = useRef(true);
+  let scrollableY = useRef(true);
   useEffect(() => {
     if (ref.current) {
-      scrollableRef.current = getScrollParent(ref.current);
+      scrollableRef.current = isScrollable(ref.current) ? ref.current : getScrollParent(ref.current);
+      let style = window.getComputedStyle(scrollableRef.current);
+      scrollableX.current = /(auto|scroll)/.test(style.overflowX);
+      scrollableY.current = /(auto|scroll)/.test(style.overflowY);
     }
   }, [ref]);
 
@@ -29,9 +35,23 @@ export function useAutoScroll(ref: RefObject<Element>) {
     dy: 0
   }).current;
 
+  useEffect(() => {
+    return () => {
+      if (state.timer) {
+        cancelAnimationFrame(state.timer);
+        state.timer = null;
+      }
+    };
+  // state will become a new object, so it's ok to use in the dependency array for unmount
+  }, [state]);
+
   let scroll = useCallback(() => {
-    scrollableRef.current.scrollLeft += state.dx;
-    scrollableRef.current.scrollTop += state.dy;
+    if (scrollableX.current) {
+      scrollableRef.current.scrollLeft += state.dx;
+    }
+    if (scrollableY.current) {
+      scrollableRef.current.scrollTop += state.dy;
+    }
 
     if (state.timer) {
       state.timer = requestAnimationFrame(scroll);

package/src/useClipboard.ts

@@ -10,21 +10,28 @@
  * governing permissions and limitations under the License.
  */
 
-import {chain} from '@react-aria/utils';
-import {DragItem, DropItem} from '@react-types/shared';
-import {HTMLAttributes, useEffect, useRef} from 'react';
+import {chain, useEffectEvent} from '@react-aria/utils';
+import {DOMAttributes, DragItem, DropItem} from '@react-types/shared';
 import {readFromDataTransfer, writeToDataTransfer} from './utils';
+import {useEffect, useRef} from 'react';
 import {useFocus} from '@react-aria/interactions';
 
-interface ClipboardProps {
+export interface ClipboardProps {
+  /** A function that returns the items to copy. */
   getItems?: () => DragItem[],
+  /** Handler that is called when the user triggers a copy interaction. */
   onCopy?: () => void,
+  /** Handler that is called when the user triggers a cut interaction. */
   onCut?: () => void,
-  onPaste?: (items: DropItem[]) => void
+  /** Handler that is called when the user triggers a paste interaction. */
+  onPaste?: (items: DropItem[]) => void,
+  /** Whether the clipboard is disabled. */
+  isDisabled?: boolean
 }
 
-interface ClipboardResult {
-  clipboardProps: HTMLAttributes<HTMLElement>
+export interface ClipboardResult {
+  /** Props for the element that will handle clipboard events. */
+  clipboardProps: DOMAttributes
 }
 
 const globalEvents = new Map();
@@ -54,10 +61,12 @@ function addGlobalEventListener(event, fn) {
   };
 }
 
+/**
+ * Handles clipboard interactions for a focusable element. Supports items of multiple
+ * data types, and integrates with the operating system native clipboard.
+ */
 export function useClipboard(options: ClipboardProps): ClipboardResult {
-  let ref = useRef(options);
-  ref.current = options;
-
+  let {isDisabled} = options;
   let isFocusedRef = useRef(false);
   let {focusProps} = useFocus({
     onFocusChange: (isFocused) => {
@@ -65,64 +74,61 @@ export function useClipboard(options: ClipboardProps): ClipboardResult {
     }
   });
 
-  useEffect(() => {
-    let onBeforeCopy = (e: ClipboardEvent) => {
-      // Enable the "Copy" menu item in Safari if this element is focused and copying is supported.
-      let options = ref.current;
-      if (isFocusedRef.current && options.getItems) {
-        e.preventDefault();
-      }
-    };
-
-    let onCopy = (e: ClipboardEvent) => {
-      let options = ref.current;
-      if (!isFocusedRef.current || !options.getItems) {
-        return;
-      }
-
+  let onBeforeCopy = useEffectEvent((e: ClipboardEvent) => {
+    // Enable the "Copy" menu item in Safari if this element is focused and copying is supported.
+    if (isFocusedRef.current && options.getItems) {
       e.preventDefault();
-      writeToDataTransfer(e.clipboardData, options.getItems());
-      options.onCopy?.();
-    };
+    }
+  });
 
-    let onBeforeCut = (e: ClipboardEvent) => {
-      let options = ref.current;
-      if (isFocusedRef.current && options.onCut && options.getItems) {
-        e.preventDefault();
-      }
-    };
+  let onCopy = useEffectEvent((e: ClipboardEvent) => {
+    if (!isFocusedRef.current || !options.getItems) {
+      return;
+    }
 
-    let onCut = (e: ClipboardEvent) => {
-      let options = ref.current;
-      if (!isFocusedRef.current || !options.onCut || !options.getItems) {
-        return;
-      }
+    e.preventDefault();
+    writeToDataTransfer(e.clipboardData, options.getItems());
+    options.onCopy?.();
+  });
 
+  let onBeforeCut = useEffectEvent((e: ClipboardEvent) => {
+    if (isFocusedRef.current && options.onCut && options.getItems) {
       e.preventDefault();
-      writeToDataTransfer(e.clipboardData, options.getItems());
-      options.onCut();
-    };
+    }
+  });
 
-    let onBeforePaste = (e: ClipboardEvent) => {
-      let options = ref.current;
-      // Unfortunately, e.clipboardData.types is not available in this event so we always
-      // have to enable the Paste menu item even if the type of data is unsupported.
-      if (isFocusedRef.current && options.onPaste) {
-        e.preventDefault();
-      }
-    };
+  let onCut = useEffectEvent((e: ClipboardEvent) => {
+    if (!isFocusedRef.current || !options.onCut || !options.getItems) {
+      return;
+    }
 
-    let onPaste = (e: ClipboardEvent) => {
-      let options = ref.current;
-      if (!isFocusedRef.current || !options.onPaste) {
-        return;
-      }
+    e.preventDefault();
+    writeToDataTransfer(e.clipboardData, options.getItems());
+    options.onCut();
+  });
 
+  let onBeforePaste = useEffectEvent((e: ClipboardEvent) => {
+    // Unfortunately, e.clipboardData.types is not available in this event so we always
+    // have to enable the Paste menu item even if the type of data is unsupported.
+    if (isFocusedRef.current && options.onPaste) {
       e.preventDefault();
-      let items = readFromDataTransfer(e.clipboardData);
-      options.onPaste(items);
-    };
+    }
+  });
+
+  let onPaste = useEffectEvent((e: ClipboardEvent) => {
+    if (!isFocusedRef.current || !options.onPaste) {
+      return;
+    }
 
+    e.preventDefault();
+    let items = readFromDataTransfer(e.clipboardData);
+    options.onPaste(items);
+  });
+
+  useEffect(() => {
+    if (isDisabled) {
+      return;
+    }
     return chain(
       addGlobalEventListener('beforecopy', onBeforeCopy),
       addGlobalEventListener('copy', onCopy),
@@ -131,7 +137,7 @@ export function useClipboard(options: ClipboardProps): ClipboardResult {
       addGlobalEventListener('beforepaste', onBeforePaste),
       addGlobalEventListener('paste', onPaste)
     );
-  }, []);
+  }, [isDisabled, onBeforeCopy, onCopy, onBeforeCut, onCut, onBeforePaste, onPaste]);
 
   return {
     clipboardProps: focusProps

package/src/useDrag.ts

@@ -11,29 +11,46 @@
  */
 
 import {AriaButtonProps} from '@react-types/button';
-import {DragEndEvent, DragItem, DragMoveEvent, DragPreviewRenderer, DragStartEvent, DropOperation, PressEvent} from '@react-types/shared';
-import {DragEvent, HTMLAttributes, RefObject, useRef, useState} from 'react';
+import {DragEndEvent, DragItem, DragMoveEvent, DragPreviewRenderer, DragStartEvent, DropOperation, PressEvent, RefObject} from '@react-types/shared';
+import {DragEvent, HTMLAttributes, useRef, useState} from 'react';
 import * as DragManager from './DragManager';
 import {DROP_EFFECT_TO_DROP_OPERATION, DROP_OPERATION, EFFECT_ALLOWED} from './constants';
+import {globalDropEffect, setGlobalAllowedDropOperations, setGlobalDropEffect, useDragModality, writeToDataTransfer} from './utils';
 // @ts-ignore
 import intlMessages from '../intl/*.json';
-import {useDescription, useGlobalListeners} from '@react-aria/utils';
-import {useDragModality} from './utils';
-import {useMessageFormatter} from '@react-aria/i18n';
-import {writeToDataTransfer} from './utils';
+import {isVirtualClick, isVirtualPointerEvent, useDescription, useGlobalListeners, useLayoutEffect} from '@react-aria/utils';
+import {useLocalizedStringFormatter} from '@react-aria/i18n';
 
-interface DragOptions {
+export interface DragOptions {
+  /** Handler that is called when a drag operation is started. */
   onDragStart?: (e: DragStartEvent) => void,
+  /** Handler that is called when the drag is moved. */
   onDragMove?: (e: DragMoveEvent) => void,
+  /** Handler that is called when the drag operation is ended, either as a result of a drop or a cancellation. */
   onDragEnd?: (e: DragEndEvent) => void,
+  /** A function that returns the items being dragged. */
   getItems: () => DragItem[],
-  preview?: RefObject<DragPreviewRenderer>,
-  getAllowedDropOperations?: () => DropOperation[]
+  /** The ref of the element that will be rendered as the drag preview while dragging. */
+  preview?: RefObject<DragPreviewRenderer | null>,
+  /** Function that returns the drop operations that are allowed for the dragged items. If not provided, all drop operations are allowed. */
+  getAllowedDropOperations?: () => DropOperation[],
+  /**
+   * 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 drag operation is disabled. If true, the element will not be draggable.
+   */
+  isDisabled?: boolean
 }
 
-interface DragResult {
+export interface DragResult {
+  /** Props for the draggable element. */
   dragProps: HTMLAttributes<HTMLElement>,
+  /** Props for the explicit drag button affordance, if any. */
   dragButtonProps: AriaButtonProps,
+  /** Whether the element is currently being dragged. */
   isDragging: boolean
 }
 
@@ -52,22 +69,44 @@ const MESSAGES = {
   }
 };
 
+/**
+ * Handles drag interactions for an element, with support for traditional mouse and touch
+ * based drag and drop, in addition to full parity for keyboard and screen reader users.
+ */
 export function useDrag(options: DragOptions): DragResult {
-  let formatMessage = useMessageFormatter(intlMessages);
+  let {hasDragButton, isDisabled} = options;
+  let stringFormatter = useLocalizedStringFormatter(intlMessages, '@react-aria/dnd');
   let state = useRef({
     options,
     x: 0,
     y: 0
   }).current;
   state.options = options;
-  let [isDragging, setDragging] = useState(false);
+  let isDraggingRef = useRef(false);
+  let [isDragging, setDraggingState] = useState(false);
+  let setDragging = (isDragging) => {
+    isDraggingRef.current = isDragging;
+    setDraggingState(isDragging);
+  };
   let {addGlobalListener, removeAllGlobalListeners} = useGlobalListeners();
+  let modalityOnPointerDown = useRef<string>(null);
 
   let onDragStart = (e: DragEvent) => {
     if (e.defaultPrevented) {
       return;
     }
 
+    // Prevent the drag event from propagating to any parent draggables
+    e.stopPropagation();
+
+    // 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',
@@ -79,16 +118,18 @@ export function useDrag(options: DragOptions): DragResult {
     let items = options.getItems();
     writeToDataTransfer(e.dataTransfer, items);
 
+    let allowed = DROP_OPERATION.all;
     if (typeof options.getAllowedDropOperations === 'function') {
       let allowedOperations = options.getAllowedDropOperations();
-      let allowed = DROP_OPERATION.none;
+      allowed = DROP_OPERATION.none;
       for (let operation of allowedOperations) {
         allowed |= DROP_OPERATION[operation] || DROP_OPERATION.none;
       }
-
-      e.dataTransfer.effectAllowed = EFFECT_ALLOWED[allowed] || 'none';
     }
 
+    setGlobalAllowedDropOperations(allowed);
+    e.dataTransfer.effectAllowed = EFFECT_ALLOWED[allowed] || 'none';
+
     // 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') {
@@ -106,7 +147,7 @@ export function useDrag(options: DragOptions): DragResult {
         }
 
         // Rounding height to an even number prevents blurry preview seen on some screens
-        let height = 2 * Math.round(rect.height / 2);
+        let height = 2 * Math.round(size.height / 2);
         node.style.height = `${height}px`;
 
         e.dataTransfer.setDragImage(node, x, y);
@@ -115,13 +156,10 @@ export function useDrag(options: DragOptions): DragResult {
 
     // Enforce that drops are handled by useDrop.
     addGlobalListener(window, 'drop', e => {
-      if (!DragManager.isValidDropTarget(e.target as Element)) {
-        e.preventDefault();
-        e.stopPropagation();
-        throw new Error('Drags initiated from the React Aria useDrag hook may only be dropped on a target created with useDrop. This ensures that a keyboard and screen reader accessible alternative is available.');
-      }
-    }, {capture: true, once: true});
-
+      e.preventDefault();
+      e.stopPropagation();
+      console.warn('Drags initiated from the React Aria useDrag hook may only be dropped on a target created with useDrop. This ensures that a keyboard and screen reader accessible alternative is available.');
+    }, {once: true});
     state.x = e.clientX;
     state.y = e.clientY;
 
@@ -133,6 +171,9 @@ export function useDrag(options: DragOptions): DragResult {
   };
 
   let onDrag = (e: DragEvent) => {
+    // Prevent the drag event from propagating to any parent draggables
+    e.stopPropagation();
+
     if (e.clientX === state.x && e.clientY === state.y) {
       return;
     }
@@ -150,26 +191,65 @@ export function useDrag(options: DragOptions): DragResult {
   };
 
   let onDragEnd = (e: DragEvent) => {
+    // Prevent the drag event from propagating to any parent draggables
+    e.stopPropagation();
+
     if (typeof options.onDragEnd === 'function') {
-      options.onDragEnd({
+      let event: DragEndEvent = {
         type: 'dragend',
         x: e.clientX,
         y: e.clientY,
         dropOperation: DROP_EFFECT_TO_DROP_OPERATION[e.dataTransfer.dropEffect]
-      });
+      };
+
+      // Chrome Android always returns none as its dropEffect so we use the drop effect set in useDrop via
+      // onDragEnter/onDragOver instead. https://bugs.chromium.org/p/chromium/issues/detail?id=1353951
+      if (globalDropEffect) {
+        event.dropOperation = DROP_EFFECT_TO_DROP_OPERATION[globalDropEffect];
+      }
+      options.onDragEnd(event);
     }
 
     setDragging(false);
     removeAllGlobalListeners();
+    setGlobalAllowedDropOperations(DROP_OPERATION.none);
+    setGlobalDropEffect(undefined);
   };
 
+  // If the dragged element is removed from the DOM via onDrop, onDragEnd won't fire: https://bugzilla.mozilla.org/show_bug.cgi?id=460801
+  // In this case, we need to manually call onDragEnd on cleanup
+  // eslint-disable-next-line arrow-body-style
+  useLayoutEffect(() => {
+    return () => {
+      if (isDraggingRef.current) {
+        if (typeof state.options.onDragEnd === 'function') {
+          let event: DragEndEvent = {
+            type: 'dragend',
+            x: 0,
+            y: 0,
+            dropOperation: DROP_EFFECT_TO_DROP_OPERATION[globalDropEffect || 'none']
+          };
+          state.options.onDragEnd(event);
+        }
+
+        setDragging(false);
+        setGlobalAllowedDropOperations(DROP_OPERATION.none);
+        setGlobalDropEffect(undefined);
+      }
+    };
+  }, [state]);
+
   let onPress = (e: PressEvent) => {
     if (e.pointerType !== 'keyboard' && e.pointerType !== 'virtual') {
       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),
@@ -178,7 +258,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()
@@ -189,18 +269,86 @@ export function useDrag(options: DragOptions): DragResult {
           state.options.onDragEnd(e);
         }
       }
-    }, formatMessage);
+    }, stringFormatter);
 
     setDragging(true);
   };
 
   let modality = useDragModality();
-  let descriptionProps = useDescription(
-    formatMessage(!isDragging ? MESSAGES[modality].start : MESSAGES[modality].end)
-  );
+  let message = !isDragging ? MESSAGES[modality].start : 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(e) {
+        modalityOnPointerDown.current = isVirtualPointerEvent(e.nativeEvent) ? 'virtual' : e.pointerType;
+
+        // Try to detect virtual drag passthrough gestures.
+        if (e.width < 1 && e.height < 1) {
+          // iOS VoiceOver.
+          modalityOnPointerDown.current = 'virtual';
+        } else {
+          let rect = e.currentTarget.getBoundingClientRect();
+          let offsetX = e.clientX - rect.x;
+          let offsetY = e.clientY - rect.y;
+          let centerX = rect.width / 2;
+          let centerY = rect.height / 2;
+
+          if (Math.abs(offsetX - centerX) <= 0.5 && Math.abs(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);
+        }
+      },
+      onClick(e) {
+        // Handle NVDA/JAWS in browse mode, and touch screen readers. In this case, no keyboard events are fired.
+        if (isVirtualClick(e.nativeEvent) || modalityOnPointerDown.current === 'virtual') {
+          e.preventDefault();
+          e.stopPropagation();
+          startDragging(e.target as HTMLElement);
+        }
+      }
+    };
+  }
+
+  if (isDisabled) {
+    return {
+      dragProps: {
+        draggable: 'false'
+      },
+      dragButtonProps: {},
+      isDragging: false
+    };
+  }
 
   return {
     dragProps: {
+      ...interactions,
       draggable: 'true',
       onDragStart,
       onDrag,

package/src/useDraggableCollection.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2022 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {DraggableCollectionState} from '@react-stately/dnd';
+import {globalDndState, setDraggingCollectionRef} from './utils';
+import {RefObject} from '@react-types/shared';
+
+export interface DraggableCollectionOptions {}
+
+/**
+ * Handles drag interactions for a collection component, with support for traditional mouse and touch
+ * based drag and drop, in addition to full parity for keyboard and screen reader users.
+ */
+export function useDraggableCollection(props: DraggableCollectionOptions, state: DraggableCollectionState, ref: RefObject<HTMLElement | null>): void {
+  // Update global DnD state if this keys within this collection are dragged
+  let {draggingCollectionRef} = globalDndState;
+  if  (state.draggingKeys.size > 0 && draggingCollectionRef?.current !== ref.current) {
+    setDraggingCollectionRef(ref);
+  }
+}