@react-aria/selection 3.6.0 → 3.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-aria/selection",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Spectrum UI components in React",
   "license": "Apache-2.0",
   "main": "dist/main.js",
@@ -19,12 +19,12 @@
   "dependencies": {
     "@babel/runtime": "^7.6.2",
     "@react-aria/focus": "^3.5.0",
-    "@react-aria/i18n": "^3.3.2",
-    "@react-aria/interactions": "^3.6.0",
-    "@react-aria/utils": "^3.9.0",
+    "@react-aria/i18n": "^3.3.3",
+    "@react-aria/interactions": "^3.7.0",
+    "@react-aria/utils": "^3.10.0",
     "@react-stately/collections": "^3.3.3",
-    "@react-stately/selection": "^3.7.0",
-    "@react-types/shared": "^3.9.0"
+    "@react-stately/selection": "^3.8.0",
+    "@react-types/shared": "^3.10.0"
   },
   "peerDependencies": {
     "react": "^16.8.0 || ^17.0.0-rc.1"
@@ -32,5 +32,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "eb6c352a42ca230774b923cc0bde692d206e0999"
+  "gitHead": "896eabe5521a0349a675c4773ed7629addd4b8c4"
 }

package/src/useSelectableCollection.ts

@@ -13,19 +13,12 @@
 import {FocusEvent, HTMLAttributes, Key, KeyboardEvent, RefObject, useEffect, useRef} from 'react';
 import {focusSafely, getFocusableTreeWalker} from '@react-aria/focus';
 import {FocusStrategy, KeyboardDelegate} from '@react-types/shared';
-import {focusWithoutScrolling, isMac, mergeProps, useEvent} from '@react-aria/utils';
+import {focusWithoutScrolling, mergeProps, useEvent} from '@react-aria/utils';
+import {isCtrlKeyPressed, isNonContiguousSelectionModifier} from './utils';
 import {MultipleSelectionManager} from '@react-stately/selection';
 import {useLocale} from '@react-aria/i18n';
 import {useTypeSelect} from './useTypeSelect';
 
-function isCtrlKeyPressed(e: KeyboardEvent) {
-  if (isMac()) {
-    return e.metaKey;
-  }
-
-  return e.ctrlKey;
-}
-
 interface SelectableCollectionOptions {
   /**
    * An interface for reading and updating multiple selection state.
@@ -105,7 +98,7 @@ export function useSelectableCollection(options: SelectableCollectionOptions): S
     shouldFocusWrap = false,
     disallowEmptySelection = false,
     disallowSelectAll = false,
-    selectOnFocus = false,
+    selectOnFocus = manager.selectionBehavior === 'replace',
     disallowTypeAhead = false,
     shouldUseVirtualFocus,
     allowsTabNavigation = false,
@@ -115,16 +108,16 @@ export function useSelectableCollection(options: SelectableCollectionOptions): S
   } = options;
   let {direction} = useLocale();
 
+
   let onKeyDown = (e: KeyboardEvent) => {
     // Prevent option + tab from doing anything since it doesn't move focus to the cells, only buttons/checkboxes
     if (e.altKey && e.key === 'Tab') {
       e.preventDefault();
     }
 
-    // Let child element (e.g. menu button) handle the event if the Alt key is pressed.
     // Keyboard events bubble through portals. Don't handle keyboard events
     // for elements outside the collection (e.g. menus).
-    if (e.altKey || !ref.current.contains(e.target as HTMLElement)) {
+    if (!ref.current.contains(e.target as HTMLElement)) {
       return;
     }
 
@@ -134,7 +127,7 @@ export function useSelectableCollection(options: SelectableCollectionOptions): S
 
         if (e.shiftKey && manager.selectionMode === 'multiple') {
           manager.extendSelection(key);
-        } else if (selectOnFocus) {
+        } else if (selectOnFocus && !isNonContiguousSelectionModifier(e)) {
           manager.replaceSelection(key);
         }
       }
@@ -291,14 +284,22 @@ export function useSelectableCollection(options: SelectableCollectionOptions): S
     manager.setFocused(true);
 
     if (manager.focusedKey == null) {
+      let navigateToFirstKey = (key: Key | undefined) => {
+        if (key != null) {
+          manager.setFocusedKey(key);
+          if (selectOnFocus) {
+            manager.replaceSelection(key);
+          }
+        }
+      };
       // If the user hasn't yet interacted with the collection, there will be no focusedKey set.
       // Attempt to detect whether the user is tabbing forward or backward into the collection
       // and either focus the first or last item accordingly.
       let relatedTarget = e.relatedTarget as Element;
       if (relatedTarget && (e.currentTarget.compareDocumentPosition(relatedTarget) & Node.DOCUMENT_POSITION_FOLLOWING)) {
-        manager.setFocusedKey(manager.lastSelectedKey ?? delegate.getLastKey());
+        navigateToFirstKey(manager.lastSelectedKey ?? delegate.getLastKey());
       } else {
-        manager.setFocusedKey(manager.firstSelectedKey ?? delegate.getFirstKey());
+        navigateToFirstKey(manager.firstSelectedKey ?? delegate.getFirstKey());
       }
     } else if (!isVirtualized) {
       // Restore the scroll position to what it was before.

package/src/useSelectableItem.ts

@@ -11,10 +11,12 @@
  */
 
 import {focusSafely} from '@react-aria/focus';
-import {HTMLAttributes, Key, RefObject, useEffect} from 'react';
+import {HTMLAttributes, Key, RefObject, useEffect, useRef} from 'react';
+import {isCtrlKeyPressed, isNonContiguousSelectionModifier} from './utils';
+import {LongPressEvent, PressEvent} from '@react-types/shared';
+import {mergeProps} from '@react-aria/utils';
 import {MultipleSelectionManager} from '@react-stately/selection';
-import {PressEvent} from '@react-types/shared';
-import {PressProps} from '@react-aria/interactions';
+import {PressProps, useLongPress, usePress} from '@react-aria/interactions';
 
 interface SelectableItemOptions {
   /**
@@ -45,14 +47,23 @@ interface SelectableItemOptions {
   /**
    * Whether the option should use virtual focus instead of being focused directly.
    */
-  shouldUseVirtualFocus?: boolean
+  shouldUseVirtualFocus?: boolean,
+  /** Whether the item is disabled. */
+  isDisabled?: boolean,
+  /**
+   * Handler that is called when a user performs an action on the cell. The exact user event depends on
+   * the collection's `selectionBehavior` prop and the interaction modality.
+   */
+  onAction?: () => void
 }
 
 interface SelectableItemAria {
   /**
    * Props to be spread on the item root node.
    */
-  itemProps: HTMLAttributes<HTMLElement> & PressProps
+  itemProps: HTMLAttributes<HTMLElement>,
+  /** Whether the item is currently in a pressed state. */
+  isPressed: boolean
 }
 
 /**
@@ -66,10 +77,35 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
     shouldSelectOnPressUp,
     isVirtualized,
     shouldUseVirtualFocus,
-    focus
+    focus,
+    isDisabled,
+    onAction
   } = options;
 
-  let onSelect = (e: PressEvent | PointerEvent) => manager.select(key, e);
+  let onSelect = (e: PressEvent | LongPressEvent | PointerEvent) => {
+    if (e.pointerType === 'keyboard' && isNonContiguousSelectionModifier(e)) {
+      manager.toggleSelection(key);
+    } else {
+      if (manager.selectionMode === 'none') {
+        return;
+      }
+
+      if (manager.selectionMode === 'single') {
+        if (manager.isSelected(key) && !manager.disallowEmptySelection) {
+          manager.toggleSelection(key);
+        } else {
+          manager.replaceSelection(key);
+        }
+      } else if (e && e.shiftKey) {
+        manager.extendSelection(key);
+      } else if (manager.selectionBehavior === 'toggle' || (e && (isCtrlKeyPressed(e) || e.pointerType === 'touch' || e.pointerType === 'virtual'))) {
+        // if touch or virtual (VO) then we just want to toggle, otherwise it's impossible to multi select because they don't have modifier keys
+        manager.toggleSelection(key);
+      } else {
+        manager.replaceSelection(key);
+      }
+    }
+  };
 
   // Focus the associated DOM node when this item becomes the focusedKey
   let isFocused = key === manager.focusedKey;
@@ -98,6 +134,11 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
     };
   }
 
+  let modality = useRef(null);
+  let hasPrimaryAction = onAction && manager.selectionMode === 'none';
+  let hasSecondaryAction = onAction && manager.selectionMode !== 'none' && manager.selectionBehavior === 'replace';
+  let allowsSelection = !isDisabled && manager.canSelectItem(key);
+
   // By default, selection occurs on pointer down. This can be strange if selecting an
   // item causes the UI to disappear immediately (e.g. menus).
   // If shouldSelectOnPressUp is true, we use onPressUp instead of onPressStart.
@@ -105,29 +146,40 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
   // we want to be able to have the pointer down on the trigger that opens the menu and
   // the pointer up on the menu item rather than requiring a separate press.
   // For keyboard events, selection still occurs on key down.
+  let itemPressProps: PressProps = {};
   if (shouldSelectOnPressUp) {
-    itemProps.onPressStart = (e) => {
+    itemPressProps.onPressStart = (e) => {
+      modality.current = e.pointerType;
       if (e.pointerType === 'keyboard') {
         onSelect(e);
       }
     };
 
-    itemProps.onPressUp = (e) => {
+    itemPressProps.onPressUp = (e) => {
       if (e.pointerType !== 'keyboard') {
         onSelect(e);
       }
     };
+
+    itemPressProps.onPress = hasPrimaryAction ? () => onAction() : null;
   } else {
     // On touch, it feels strange to select on touch down, so we special case this.
-    itemProps.onPressStart = (e) => {
-      if (e.pointerType !== 'touch') {
+    itemPressProps.onPressStart = (e) => {
+      modality.current = e.pointerType;
+      if (e.pointerType !== 'touch' && e.pointerType !== 'virtual') {
         onSelect(e);
       }
     };
 
-    itemProps.onPress = (e) => {
-      if (e.pointerType === 'touch') {
-        onSelect(e);
+    itemPressProps.onPress = (e) => {
+      if (e.pointerType === 'touch' || e.pointerType === 'virtual' || hasPrimaryAction) {
+        // Single tap on touch with selectionBehavior = 'replace' performs an action, i.e. navigation.
+        // Also perform action on press up when selectionMode = 'none'.
+        if (hasPrimaryAction || hasSecondaryAction) {
+          onAction();
+        } else {
+          onSelect(e);
+        }
       }
     };
   }
@@ -136,7 +188,46 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
     itemProps['data-key'] = key;
   }
 
+  itemPressProps.preventFocusOnPress = shouldUseVirtualFocus;
+  let {pressProps, isPressed} = usePress(itemPressProps);
+
+  // Double clicking with a mouse with selectionBehavior = 'replace' performs an action.
+  let onDoubleClick = hasSecondaryAction ? (e) => {
+    if (modality.current === 'mouse') {
+      e.stopPropagation();
+      e.preventDefault();
+      onAction();
+    }
+  } : undefined;
+
+  // Long pressing an item with touch when selectionBehavior = 'replace' switches the selection behavior
+  // to 'toggle'. This changes the single tap behavior from performing an action (i.e. navigating) to
+  // selecting, and may toggle the appearance of a UI affordance like checkboxes on each item.
+  // TODO: what about when drag and drop is also enabled??
+  let {longPressProps} = useLongPress({
+    isDisabled: !hasSecondaryAction,
+    onLongPress(e) {
+      if (e.pointerType === 'touch') {
+        onSelect(e);
+        manager.setSelectionBehavior('toggle');
+      }
+    }
+  });
+
+  // Pressing the Enter key with selectionBehavior = 'replace' performs an action (i.e. navigation).
+  let onKeyUp = hasSecondaryAction ? (e: KeyboardEvent) => {
+    if (e.key === 'Enter') {
+      onAction();
+    }
+  } : undefined;
+
   return {
-    itemProps
+    itemProps: mergeProps(
+      itemProps,
+      allowsSelection || hasPrimaryAction ? pressProps : {},
+      hasSecondaryAction ? longPressProps : {},
+      {onKeyUp, onDoubleClick}
+    ),
+    isPressed
   };
 }

package/src/utils.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2020 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 {isAppleDevice} from '@react-aria/utils';
+import {isMac} from '@react-aria/utils';
+
+interface Event {
+  altKey: boolean,
+  ctrlKey: boolean,
+  metaKey: boolean
+}
+
+export function isNonContiguousSelectionModifier(e: Event) {
+  // Ctrl + Arrow Up/Arrow Down has a system wide meaning on macOS, so use Alt instead.
+  // On Windows and Ubuntu, Alt + Space has a system wide meaning.
+  return isAppleDevice() ? e.altKey : e.ctrlKey;
+}
+
+export function isCtrlKeyPressed(e: Event) {
+  if (isMac()) {
+    return e.metaKey;
+  }
+
+  return e.ctrlKey;
+}