feat: support selectionMode="replace" in grid collection test utils

packages/@react-aria/test-utils/package.json

@@ -22,6 +22,7 @@
     "url": "https://github.com/adobe/react-spectrum"
   },
   "dependencies": {
+    "@react-aria/utils": "^3.28.1",
     "@swc/helpers": "^0.5.0"
   },
   "peerDependencies": {

packages/@react-aria/test-utils/src/events.ts

@@ -11,9 +11,17 @@
  */
 
 import {act, fireEvent} from '@testing-library/react';
+import {isMac} from '@react-aria/utils';
 import {UserOpts} from './types';
 
 export const DEFAULT_LONG_PRESS_TIME = 500;
+export function getAltKey(): 'Alt' | 'ControlLeft' {
+  return isMac() ? 'Alt' : 'ControlLeft';
+}
+
+export function getMetaKey(): 'MetaLeft' | 'ControlLeft' {
+  return isMac() ? 'MetaLeft' : 'ControlLeft';
+}
 
 /**
  * Simulates a "long press" event on a element.
@@ -58,9 +66,10 @@ export async function triggerLongPress(opts: {element: HTMLElement, advanceTimer
 }
 
 // Docs cannot handle the types that userEvent actually declares, so hopefully this sub set is okay
-export async function pressElement(user: {click: (element: Element) => Promise<void>, keyboard: (keys: string) => Promise<void>, pointer: (opts: {target: Element, keys: string}) => Promise<void>}, element: HTMLElement, interactionType: UserOpts['interactionType']): Promise<void> {
+export async function pressElement(user: {click: (element: Element) => Promise<void>, keyboard: (keys: string) => Promise<void>, pointer: (opts: {target: Element, keys: string, coords?: any}) => Promise<void>}, element: HTMLElement, interactionType: UserOpts['interactionType']): Promise<void> {
   if (interactionType === 'mouse') {
-    await user.click(element);
+    // Add coords with pressure so this isn't detected as a virtual click
+    await user.pointer({target: element, keys: '[MouseLeft]', coords: {pressure: .5}});
   } else if (interactionType === 'keyboard') {
     // TODO: For the keyboard flow, I wonder if it would be reasonable to just do fireEvent directly on the obtained row node or if we should
     // stick to simulting an actual user's keyboard operations as closely as possible

packages/@react-aria/test-utils/src/gridlist.ts

@@ -11,8 +11,8 @@
  */
 
 import {act, within} from '@testing-library/react';
+import {getAltKey, getMetaKey, pressElement, triggerLongPress} from './events';
 import {GridListTesterOpts, GridRowActionOpts, ToggleGridRowOpts, UserOpts} from './types';
-import {pressElement, triggerLongPress} from './events';
 
 interface GridListToggleRowOpts extends ToggleGridRowOpts {}
 interface GridListRowActionOpts extends GridRowActionOpts {}
@@ -57,20 +57,21 @@ export class GridListTester {
   }
 
   // TODO: RTL
-  private async keyboardNavigateToRow(opts: {row: HTMLElement}) {
-    let {row} = opts;
+  private async keyboardNavigateToRow(opts: {row: HTMLElement, useAltKey?: boolean}) {
+    let {row, useAltKey} = opts;
+    let altKey = getAltKey();
     let rows = this.rows;
     let targetIndex = rows.indexOf(row);
     if (targetIndex === -1) {
       throw new Error('Option provided is not in the gridlist');
     }
 
-    if (document.activeElement !== this._gridlist || !this._gridlist.contains(document.activeElement)) {
+    if (document.activeElement !== this._gridlist && !this._gridlist.contains(document.activeElement)) {
       act(() => this._gridlist.focus());
     }
 
     if (document.activeElement === this._gridlist) {
-      await this.user.keyboard('[ArrowDown]');
+      await this.user.keyboard(`${useAltKey ? `[${altKey}>]` : ''}[ArrowDown]${useAltKey ? `[/${altKey}]` : ''}`);
     } else if (this._gridlist.contains(document.activeElement) && document.activeElement!.getAttribute('role') !== 'row') {
       do {
         await this.user.keyboard('[ArrowLeft]');
@@ -82,22 +83,34 @@ export class GridListTester {
     }
     let direction = targetIndex > currIndex ? 'down' : 'up';
 
+    if (useAltKey) {
+      await this.user.keyboard(`[${altKey}>]`);
+    }
     for (let i = 0; i < Math.abs(targetIndex - currIndex); i++) {
       await this.user.keyboard(`[${direction === 'down' ? 'ArrowDown' : 'ArrowUp'}]`);
     }
+    if (useAltKey) {
+      await this.user.keyboard(`[/${altKey}]`);
+    }
   };
 
   /**
    * Toggles the selection for the specified gridlist row. Defaults to using the interaction type set on the gridlist tester.
+   * Note that this will endevor to always add/remove JUST the provided row to the set of selected rows.
    */
   async toggleRowSelection(opts: GridListToggleRowOpts): Promise<void> {
     let {
       row,
       needsLongPress,
       checkboxSelection = true,
-      interactionType = this._interactionType
+      interactionType = this._interactionType,
+      // TODO: perhaps this should just be shouldUseModifierKeys?
+      selectionBehavior = 'toggle'
     } = opts;
 
+    let altKey = getAltKey();
+    let metaKey = getMetaKey();
+
     if (typeof row === 'string' || typeof row === 'number') {
       row = this.findRow({rowIndexOrText: row});
     }
@@ -116,9 +129,15 @@ export class GridListTester {
 
     // this would be better than the check to do nothing in events.ts
     // also, it'd be good to be able to trigger selection on the row instead of having to go to the checkbox directly
-    if (interactionType === 'keyboard' && !checkboxSelection) {
-      await this.keyboardNavigateToRow({row});
-      await this.user.keyboard('{Space}');
+    if (interactionType === 'keyboard' && (!checkboxSelection || !rowCheckbox)) {
+      await this.keyboardNavigateToRow({row, useAltKey: selectionBehavior === 'replace'});
+      if (selectionBehavior === 'replace') {
+        await this.user.keyboard(`[${altKey}>]`);
+      }
+      await this.user.keyboard('[Space]');
+      if (selectionBehavior === 'replace') {
+        await this.user.keyboard(`[/${altKey}]`);
+      }
       return;
     }
     if (rowCheckbox && checkboxSelection) {
@@ -132,9 +151,14 @@ export class GridListTester {
 
         // Note that long press interactions with rows is strictly touch only for grid rows
         await triggerLongPress({element: cell, advanceTimer: this._advanceTimer, pointerOpts: {pointerType: 'touch'}});
-
       } else {
-        await pressElement(this.user, cell, interactionType);
+        if (selectionBehavior === 'replace' && interactionType !== 'touch') {
+          await this.user.keyboard(`[${metaKey}>]`);
+        }
+        await pressElement(this.user, row, interactionType);
+        if (selectionBehavior === 'replace' && interactionType !== 'touch') {
+          await this.user.keyboard(`[/${metaKey}]`);
+        }
       }
     }
   }
@@ -166,7 +190,7 @@ export class GridListTester {
         return;
       }
 
-      await this.keyboardNavigateToRow({row});
+      await this.keyboardNavigateToRow({row, useAltKey: true});
       await this.user.keyboard('[Enter]');
     } else {
       await pressElement(this.user, row, interactionType);

packages/@react-aria/test-utils/src/listbox.ts

@@ -11,8 +11,8 @@
  */
 
 import {act, within} from '@testing-library/react';
+import {getAltKey, getMetaKey, pressElement, triggerLongPress} from './events';
 import {ListBoxTesterOpts, UserOpts} from './types';
-import {pressElement, triggerLongPress} from './events';
 
 interface ListBoxToggleOptionOpts {
   /**
@@ -31,7 +31,16 @@ interface ListBoxToggleOptionOpts {
   /**
    * Whether the option needs to be long pressed to be selected. Depends on the listbox's implementation.
    */
-  needsLongPress?: boolean
+  needsLongPress?: boolean,
+  /**
+   * Whether the listbox has a selectionBehavior of "toggle" or "replace" (aka highlight selection). This affects the user operations
+   * required to toggle option selection by adding modifier keys during user actions, useful when performing multi-option selection in a "selectionBehavior: 'replace'" listbox.
+   * If you would like to still simulate user actions (aka press) without these modifiers keys for a "selectionBehavior: replace" listbox, simply omit this option.
+   * See the [RAC Listbox docs](https://react-spectrum.adobe.com/react-aria/ListBox.html#selection-behavior) for more info on this behavior.
+   *
+   * @default 'toggle'
+   */
+    selectionBehavior?: 'toggle' | 'replace'
 }
 
 interface ListBoxOptionActionOpts extends Omit<ListBoxToggleOptionOpts, 'keyboardActivation' | 'needsLongPress'> {
@@ -85,44 +94,52 @@ export class ListBoxTester {
 
   // TODO: this is basically the same as menu except for the error message, refactor later so that they share
   // TODO: this also doesn't support grid layout yet
-  private async keyboardNavigateToOption(opts: {option: HTMLElement}) {
-    let {option} = opts;
+  private async keyboardNavigateToOption(opts: {option: HTMLElement, useAltKey?: boolean}) {
+    let {option, useAltKey} = opts;
+    let altKey = getAltKey();
     let options = this.options();
     let targetIndex = options.indexOf(option);
     if (targetIndex === -1) {
       throw new Error('Option provided is not in the listbox');
     }
 
-    if (document.activeElement !== this._listbox || !this._listbox.contains(document.activeElement)) {
+    if (document.activeElement !== this._listbox && !this._listbox.contains(document.activeElement)) {
       act(() => this._listbox.focus());
-    }
-
-    await this.user.keyboard('[ArrowDown]');
-
-    // TODO: not sure about doing same while loop that exists in other implementations of keyboardNavigateToOption,
-    // feels like it could break easily
-    if (document.activeElement?.getAttribute('role') !== 'option') {
-      await act(async () => {
-        option.focus();
-      });
+      await this.user.keyboard(`${useAltKey ? `[${altKey}>]` : ''}[ArrowDown]${useAltKey ? `[/${altKey}]` : ''}`);
     }
 
     let currIndex = options.indexOf(document.activeElement as HTMLElement);
     if (currIndex === -1) {
       throw new Error('ActiveElement is not in the listbox');
     }
-    let direction = targetIndex > currIndex ? 'down' : 'up';
 
+    let direction = targetIndex > currIndex ? 'down' : 'up';
+    if (useAltKey) {
+      await this.user.keyboard(`[${altKey}>]`);
+    }
     for (let i = 0; i < Math.abs(targetIndex - currIndex); i++) {
       await this.user.keyboard(`[${direction === 'down' ? 'ArrowDown' : 'ArrowUp'}]`);
     }
+    if (useAltKey) {
+      await this.user.keyboard(`[/${altKey}]`);
+    }
   };
 
   /**
    * Toggles the selection for the specified listbox option. Defaults to using the interaction type set on the listbox tester.
    */
   async toggleOptionSelection(opts: ListBoxToggleOptionOpts): Promise<void> {
-    let {option, needsLongPress, keyboardActivation = 'Enter', interactionType = this._interactionType} = opts;
+    let {
+      option,
+      needsLongPress,
+      keyboardActivation = 'Enter',
+      interactionType = this._interactionType,
+      // TODO: perhaps this should just be shouldUseModifierKeys?
+      selectionBehavior = 'toggle'
+    } = opts;
+
+    let altKey = getAltKey();
+    let metaKey = getMetaKey();
 
     if (typeof option === 'string' || typeof option === 'number') {
       option = this.findOption({optionIndexOrText: option});
@@ -137,8 +154,14 @@ export class ListBoxTester {
         return;
       }
 
-      await this.keyboardNavigateToOption({option});
+      await this.keyboardNavigateToOption({option, useAltKey: selectionBehavior === 'replace'});
+      if (selectionBehavior === 'replace') {
+        await this.user.keyboard(`[${altKey}>]`);
+      }
       await this.user.keyboard(`[${keyboardActivation}]`);
+      if (selectionBehavior === 'replace') {
+        await this.user.keyboard(`[/${altKey}]`);
+      }
     } else {
       if (needsLongPress && interactionType === 'touch') {
         if (this._advanceTimer == null) {
@@ -147,7 +170,13 @@ export class ListBoxTester {
 
         await triggerLongPress({element: option, advanceTimer: this._advanceTimer, pointerOpts: {pointerType: 'touch'}});
       } else {
+        if (selectionBehavior === 'replace' && interactionType !== 'touch') {
+          await this.user.keyboard(`[${metaKey}>]`);
+        }
         await pressElement(this.user, option, interactionType);
+        if (selectionBehavior === 'replace' && interactionType !== 'touch') {
+          await this.user.keyboard(`[/${metaKey}]`);
+        }
       }
     }
   }
@@ -177,7 +206,7 @@ export class ListBoxTester {
         return;
       }
 
-      await this.keyboardNavigateToOption({option});
+      await this.keyboardNavigateToOption({option, useAltKey: true});
       await this.user.keyboard('[Enter]');
     } else {
       await pressElement(this.user, option, interactionType);

packages/@react-aria/test-utils/src/menu.ts

@@ -215,7 +215,7 @@ export class MenuTester {
           return;
         }
 
-        if (document.activeElement !== menu || !menu.contains(document.activeElement)) {
+        if (document.activeElement !== menu && !menu.contains(document.activeElement)) {
           act(() => menu.focus());
         }
 

packages/@react-aria/test-utils/src/select.ts

@@ -183,7 +183,7 @@ export class SelectTester {
           return;
         }
 
-        if (document.activeElement !== listbox || !listbox.contains(document.activeElement)) {
+        if (document.activeElement !== listbox && !listbox.contains(document.activeElement)) {
           act(() => listbox.focus());
         }
         await this.keyboardNavigateToOption({option});