@react-aria/selection 3.5.0 → 3.7.1

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/useSelectableList.ts

@@ -11,7 +11,7 @@
  */
 
 import {Collection, FocusStrategy, KeyboardDelegate, Node} from '@react-types/shared';
-import {HTMLAttributes, Key, RefObject, useEffect, useMemo} from 'react';
+import {HTMLAttributes, Key, RefObject, useMemo} from 'react';
 import {ListKeyboardDelegate} from './ListKeyboardDelegate';
 import {MultipleSelectionManager} from '@react-stately/selection';
 import {useCollator} from '@react-aria/i18n';
@@ -109,17 +109,6 @@ export function useSelectableList(props: SelectableListOptions): SelectableListA
   let collator = useCollator({usage: 'search', sensitivity: 'base'});
   let delegate = useMemo(() => keyboardDelegate || new ListKeyboardDelegate(collection, disabledKeys, ref, collator), [keyboardDelegate, collection, disabledKeys, ref, collator]);
 
-  // If not virtualized, scroll the focused element into view when the focusedKey changes.
-  // When virtualized, Virtualizer handles this internally.
-  useEffect(() => {
-    if (!isVirtualized && selectionManager.focusedKey && ref?.current) {
-      let element = ref.current.querySelector(`[data-key="${selectionManager.focusedKey}"]`) as HTMLElement;
-      if (element) {
-        scrollIntoView(ref.current, element);
-      }
-    }
-  }, [isVirtualized, ref, selectionManager.focusedKey]);
-
   let {collectionProps} = useSelectableCollection({
     ref,
     selectionManager,
@@ -130,64 +119,12 @@ export function useSelectableList(props: SelectableListOptions): SelectableListA
     selectOnFocus,
     disallowTypeAhead,
     shouldUseVirtualFocus,
-    allowsTabNavigation
+    allowsTabNavigation,
+    isVirtualized,
+    scrollRef: ref
   });
 
   return {
     listProps: collectionProps
   };
 }
-
-/**
- * Scrolls `scrollView` so that `element` is visible.
- * Similar to `element.scrollIntoView({block: 'nearest'})` (not supported in Edge),
- * but doesn't affect parents above `scrollView`.
- */
-function scrollIntoView(scrollView: HTMLElement, element: HTMLElement) {
-  let offsetX = relativeOffset(scrollView, element, 'left');
-  let offsetY = relativeOffset(scrollView, element, 'top');
-  let width = element.offsetWidth;
-  let height = element.offsetHeight;
-  let x = scrollView.scrollLeft;
-  let y = scrollView.scrollTop;
-  let maxX = x + scrollView.offsetWidth;
-  let maxY = y + scrollView.offsetHeight;
-
-  if (offsetX <= x) {
-    x = offsetX;
-  } else if (offsetX + width > maxX) {
-    x += offsetX + width - maxX;
-  }
-  if (offsetY <= y) {
-    y = offsetY;
-  } else if (offsetY + height > maxY) {
-    y += offsetY + height - maxY;
-  }
-
-  scrollView.scrollLeft = x;
-  scrollView.scrollTop = y;
-}
-
-/**
- * Computes the offset left or top from child to ancestor by accumulating
- * offsetLeft or offsetTop through intervening offsetParents.
- */
-function relativeOffset(ancestor: HTMLElement, child: HTMLElement, axis: 'left'|'top') {
-  const prop = axis === 'left' ? 'offsetLeft' : 'offsetTop';
-  let sum = 0;
-  while (child.offsetParent) {
-    sum += child[prop];
-    if (child.offsetParent === ancestor) {
-      // Stop once we have found the ancestor we are interested in.
-      break;
-    } else if (child.offsetParent.contains(ancestor)) {
-      // If the ancestor is not `position:relative`, then we stop at 
-      // _its_ offset parent, and we subtract off _its_ offset, so that
-      // we end up with the proper offset from child to ancestor.
-      sum -= ancestor[prop];
-      break;
-    }
-    child = child.offsetParent as HTMLElement;
-  }
-  return sum;
-}

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;
+}