@react-aria/selection 3.16.2 → 3.17.0

package/src/useSelectableItem.ts

@@ -14,7 +14,7 @@ import {DOMAttributes, FocusableElement, LongPressEvent, PressEvent} from '@reac
 import {focusSafely} from '@react-aria/focus';
 import {isCtrlKeyPressed, isNonContiguousSelectionModifier} from './utils';
 import {Key, RefObject, useEffect, useRef} from 'react';
-import {mergeProps} from '@react-aria/utils';
+import {mergeProps, openLink, useRouter} from '@react-aria/utils';
 import {MultipleSelectionManager} from '@react-stately/selection';
 import {PressProps, useLongPress, usePress} from '@react-aria/interactions';
 
@@ -59,7 +59,16 @@ export interface SelectableItemOptions {
    * Handler that is called when a user performs an action on the item. The exact user event depends on
    * the collection's `selectionBehavior` prop and the interaction modality.
    */
-  onAction?: () => void
+  onAction?: () => void,
+  /**
+   * The behavior of links in the collection.
+   * - 'action': link behaves like onAction.
+   * - 'selection': link follows selection interactions (e.g. if URL drives selection).
+   * - 'override': links override all other interactions (link items are not selectable).
+   * - 'none': links are disabled for both selection and actions (e.g. handled elsewhere).
+   * @default 'action'
+   */
+  linkBehavior?: 'action' | 'selection' | 'override' | 'none'
 }
 
 export interface SelectableItemStates {
@@ -107,8 +116,10 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
     focus,
     isDisabled,
     onAction,
-    allowsDifferentPressOrigin
+    allowsDifferentPressOrigin,
+    linkBehavior = 'action'
   } = options;
+  let router = useRouter();
 
   let onSelect = (e: PressEvent | LongPressEvent | PointerEvent) => {
     if (e.pointerType === 'keyboard' && isNonContiguousSelectionModifier(e)) {
@@ -118,6 +129,17 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
         return;
       }
 
+      if (manager.isLink(key)) {
+        if (linkBehavior === 'selection') {
+          router.open(ref.current, e);
+          // Always set selected keys back to what they were so that select and combobox close.
+          manager.setSelectedKeys(manager.selectedKeys);
+          return;
+        } else if (linkBehavior === 'override' || linkBehavior === 'none') {
+          return;
+        }
+      }
+
       if (manager.selectionMode === 'single') {
         if (manager.isSelected(key) && !manager.disallowEmptySelection) {
           manager.toggleSelection(key);
@@ -173,12 +195,14 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
   // Clicking the checkbox enters selection mode, after which clicking anywhere on any row toggles selection for that row.
   // With highlight selection, onAction is secondary, and occurs on double click. Single click selects the row.
   // With touch, onAction occurs on single tap, and long press enters selection mode.
-  let allowsSelection = !isDisabled && manager.canSelectItem(key);
-  let allowsActions = onAction && !isDisabled;
+  let isLinkOverride = manager.isLink(key) && linkBehavior === 'override';
+  let hasLinkAction = manager.isLink(key) && linkBehavior !== 'selection' && linkBehavior !== 'none';
+  let allowsSelection = !isDisabled && manager.canSelectItem(key) && !isLinkOverride;
+  let allowsActions = (onAction || hasLinkAction) && !isDisabled;
   let hasPrimaryAction = allowsActions && (
     manager.selectionBehavior === 'replace'
       ? !allowsSelection
-      : manager.isEmpty
+      : !allowsSelection || manager.isEmpty
   );
   let hasSecondaryAction = allowsActions && allowsSelection && manager.selectionBehavior === 'replace';
   let hasAction = hasPrimaryAction || hasSecondaryAction;
@@ -188,6 +212,16 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
   let longPressEnabledOnPressStart = useRef(false);
   let hadPrimaryActionOnPressStart = useRef(false);
 
+  let performAction = (e) => {
+    if (onAction) {
+      onAction();
+    }
+
+    if (hasLinkAction) {
+      router.open(ref.current, e);
+    }
+  };
+
   // 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.
@@ -214,19 +248,19 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
             return;
           }
 
-          onAction();
-        } else if (e.pointerType !== 'keyboard') {
+          performAction(e);
+        } else if (e.pointerType !== 'keyboard' && allowsSelection) {
           onSelect(e);
         }
       };
     } else {
-      itemPressProps.onPressUp = (e) => {
-        if (e.pointerType !== 'keyboard') {
+      itemPressProps.onPressUp = hasPrimaryAction ? null : (e) => {
+        if (e.pointerType !== 'keyboard' && allowsSelection) {
           onSelect(e);
         }
       };
 
-      itemPressProps.onPress = hasPrimaryAction ? () => onAction() : null;
+      itemPressProps.onPress = hasPrimaryAction ? performAction : null;
     }
   } else {
     itemPressProps.onPressStart = (e) => {
@@ -238,8 +272,10 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
       // For keyboard, select on key down. If there is an action, the Space key selects on key down,
       // and the Enter key performs onAction on key up.
       if (
-        (e.pointerType === 'mouse' && !hasPrimaryAction) ||
-        (e.pointerType === 'keyboard' && (!onAction || isSelectionKey()))
+        allowsSelection && (
+          (e.pointerType === 'mouse' && !hasPrimaryAction) ||
+          (e.pointerType === 'keyboard' && (!allowsActions || isSelectionKey()))
+        )
       ) {
         onSelect(e);
       }
@@ -257,8 +293,8 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
         (e.pointerType === 'mouse' && hadPrimaryActionOnPressStart.current)
       ) {
         if (hasAction) {
-          onAction();
-        } else {
+          performAction(e);
+        } else if (allowsSelection) {
           onSelect(e);
         }
       }
@@ -274,7 +310,7 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
     if (modality.current === 'mouse') {
       e.stopPropagation();
       e.preventDefault();
-      onAction();
+      performAction(e);
     }
   } : undefined;
 
@@ -301,12 +337,20 @@ export function useSelectableItem(options: SelectableItemOptions): SelectableIte
     }
   };
 
+  // Prevent default on link clicks so that we control exactly
+  // when they open (to match selection behavior).
+  let onClick = manager.isLink(key) ? e => {
+    if (!openLink.isOpening) {
+      e.preventDefault();
+    }
+  } : undefined;
+
   return {
     itemProps: mergeProps(
       itemProps,
       allowsSelection || hasPrimaryAction ? pressProps : {},
       longPressEnabled ? longPressProps : {},
-      {onDoubleClick, onDragStartCapture}
+      {onDoubleClick, onDragStartCapture, onClick}
     ),
     isPressed,
     isSelected: manager.isSelected(key),

package/src/useSelectableList.ts

@@ -10,71 +10,25 @@
  * governing permissions and limitations under the License.
  */
 
-import {Collection, DOMAttributes, FocusStrategy, KeyboardDelegate, Node} from '@react-types/shared';
-import {Key, RefObject, useMemo} from 'react';
+import {AriaSelectableCollectionOptions, useSelectableCollection} from './useSelectableCollection';
+import {Collection, DOMAttributes, KeyboardDelegate, Node} from '@react-types/shared';
+import {Key, useMemo} from 'react';
 import {ListKeyboardDelegate} from './ListKeyboardDelegate';
-import {MultipleSelectionManager} from '@react-stately/selection';
 import {useCollator} from '@react-aria/i18n';
-import {useSelectableCollection} from './useSelectableCollection';
 
-export interface AriaSelectableListOptions {
-  /**
-   * An interface for reading and updating multiple selection state.
-   */
-  selectionManager: MultipleSelectionManager,
+export interface AriaSelectableListOptions extends Omit<AriaSelectableCollectionOptions, 'keyboardDelegate'> {
   /**
    * State of the collection.
    */
   collection: Collection<Node<unknown>>,
   /**
-   * The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
-   */
-  disabledKeys: Set<Key>,
-  /**
-   * A ref to the item.
-   */
-  ref?: RefObject<HTMLElement>,
-  /**
-   * A delegate that returns collection item keys with respect to visual layout.
+   * A delegate object that implements behavior for keyboard focus movement.
    */
   keyboardDelegate?: KeyboardDelegate,
   /**
-   * Whether the collection or one of its items should be automatically focused upon render.
-   * @default false
-   */
-  autoFocus?: boolean | FocusStrategy,
-  /**
-   * Whether focus should wrap around when the end/start is reached.
-   * @default false
-   */
-  shouldFocusWrap?: boolean,
-  /**
-   * Whether the option is contained in a virtual scroller.
-   */
-  isVirtualized?: boolean,
-  /**
-   * Whether the collection allows empty selection.
-   * @default false
-   */
-  disallowEmptySelection?: boolean,
-  /**
-   * Whether selection should occur automatically on focus.
-   * @default false
-   */
-  selectOnFocus?: boolean,
-  /**
-   * Whether typeahead is disabled.
-   * @default false
-   */
-  disallowTypeAhead?: boolean,
-  /**
-   * Whether the collection items should use virtual focus instead of being focused directly.
-   */
-  shouldUseVirtualFocus?: boolean,
-  /**
-   * Whether navigation through tab key is enabled.
+   * The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
    */
-  allowsTabNavigation?: boolean
+  disabledKeys: Set<Key>
 }
 
 export interface SelectableListAria {
@@ -93,15 +47,7 @@ export function useSelectableList(props: AriaSelectableListOptions): SelectableL
     collection,
     disabledKeys,
     ref,
-    keyboardDelegate,
-    autoFocus,
-    shouldFocusWrap,
-    isVirtualized,
-    disallowEmptySelection,
-    selectOnFocus = selectionManager.selectionBehavior === 'replace',
-    disallowTypeAhead,
-    shouldUseVirtualFocus,
-    allowsTabNavigation
+    keyboardDelegate
   } = props;
 
   // By default, a KeyboardDelegate is provided which uses the DOM to query layout information (e.g. for page up/page down).
@@ -113,18 +59,10 @@ export function useSelectableList(props: AriaSelectableListOptions): SelectableL
   ), [keyboardDelegate, collection, disabledKeys, ref, collator, disabledBehavior]);
 
   let {collectionProps} = useSelectableCollection({
+    ...props,
     ref,
     selectionManager,
-    keyboardDelegate: delegate,
-    autoFocus,
-    shouldFocusWrap,
-    disallowEmptySelection,
-    selectOnFocus,
-    disallowTypeAhead,
-    shouldUseVirtualFocus,
-    allowsTabNavigation,
-    isVirtualized,
-    scrollRef: ref
+    keyboardDelegate: delegate
   });
 
   return {