@react-aria/test-utils 1.0.0-nightly.5042 → 1.0.0-rc.0

package/src/gridlist.ts

@@ -0,0 +1,278 @@
+/*
+ * Copyright 2024 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 {act} from './act';
+import {
+  Direction,
+  GridListTesterOpts,
+  GridRowActionOpts,
+  ToggleGridRowOpts,
+  UserOpts
+} from './types';
+import {formatTargetNode, getAltKey, getMetaKey, pressElement, triggerLongPress} from './utils';
+import {within} from '@testing-library/dom';
+
+interface GridListToggleRowOpts extends ToggleGridRowOpts {}
+interface GridListRowActionOpts extends GridRowActionOpts {}
+
+export class GridListTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _advanceTimer: UserOpts['advanceTimer'];
+  private _direction: Direction;
+  private _gridlist: HTMLElement;
+  private _layout: GridListTesterOpts['layout'];
+
+  constructor(opts: GridListTesterOpts) {
+    let {root, user, interactionType, advanceTimer, direction, layout} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+    this._advanceTimer = advanceTimer;
+    this._direction = direction || 'ltr';
+    this._layout = layout || 'stack';
+    this._gridlist = root;
+    if (root.getAttribute('role') !== 'grid') {
+      let gridlist = within(root).queryByRole('grid');
+      if (gridlist) {
+        this._gridlist = gridlist;
+      }
+    }
+  }
+
+  /**
+   * Set the interaction type used by the gridlist tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']): void {
+    this._interactionType = type;
+  }
+
+  /**
+   * Returns a row matching the specified index or text content.
+   */
+  findRow(opts: {indexOrText: number | string}): HTMLElement {
+    let {indexOrText} = opts;
+
+    let row;
+    if (typeof indexOrText === 'number') {
+      row = this.getRows()[indexOrText];
+    } else if (typeof indexOrText === 'string') {
+      row = within(this.getGridlist()!)
+        .getByText(indexOrText)
+        .closest('[role=row]')! as HTMLElement;
+    }
+
+    return row;
+  }
+
+  private async keyboardNavigateToRow(opts: {
+    row: HTMLElement;
+    selectionOnNav?: 'default' | 'none';
+  }) {
+    let {row, selectionOnNav = 'default'} = opts;
+    let altKey = getAltKey();
+    let rows = this.getRows();
+    let targetIndex = rows.indexOf(row);
+    if (targetIndex === -1) {
+      throw new Error('Row provided is not in the gridlist');
+    }
+
+    if (
+      document.activeElement !== this._gridlist &&
+      !this._gridlist.contains(document.activeElement)
+    ) {
+      act(() => this._gridlist.focus());
+    }
+
+    let focusPrevKey = this._direction === 'rtl' ? 'ArrowRight' : 'ArrowLeft';
+    if (document.activeElement === this._gridlist) {
+      await this.user.keyboard(
+        `${selectionOnNav === 'none' ? `[${altKey}>]` : ''}[ArrowDown]${selectionOnNav === 'none' ? `[/${altKey}]` : ''}`
+      );
+    } else if (
+      this._gridlist.contains(document.activeElement) &&
+      document.activeElement!.getAttribute('role') !== 'row'
+    ) {
+      do {
+        await this.user.keyboard(`[${focusPrevKey}]`);
+      } while (document.activeElement!.getAttribute('role') !== 'row');
+    }
+    let currIndex = rows.indexOf(document.activeElement as HTMLElement);
+    if (currIndex === -1) {
+      throw new Error('ActiveElement is not in the gridlist');
+    }
+
+    if (selectionOnNav === 'none') {
+      await this.user.keyboard(`[${altKey}>]`);
+    }
+    if (this._layout === 'grid') {
+      while (document.activeElement !== row) {
+        let curr = (document.activeElement as HTMLElement).getBoundingClientRect();
+        let target = row.getBoundingClientRect();
+        let key: string;
+        // basically compare current position with desired position to determine if we need to go up/down/left/right
+        // use 1 in the comparison here for subpixels since getBoundingClientRect returns subpixels precision
+        if (Math.abs(curr.top - target.top) > 1) {
+          key = curr.top < target.top ? 'ArrowDown' : 'ArrowUp';
+        } else if (Math.abs(curr.left - target.left) > 1) {
+          key = curr.left < target.left ? 'ArrowRight' : 'ArrowLeft';
+        } else {
+          // if the diff in current vs desired is < 1 but it is claiming we arent focused on the target
+          // then we might be in a case where getBoundingClientRect isnt mocked
+          throw new Error(
+            'Could not navigate to target row in grid layout. Did the test mock getBoundingClientRect?'
+          );
+        }
+        await this.user.keyboard(`[${key}]`);
+      }
+    } else {
+      let direction = targetIndex > currIndex ? 'down' : 'up';
+      for (let i = 0; i < Math.abs(targetIndex - currIndex); i++) {
+        await this.user.keyboard(`[${direction === 'down' ? 'ArrowDown' : 'ArrowUp'}]`);
+      }
+    }
+    if (selectionOnNav === 'none') {
+      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,
+      selectionBehavior = 'toggle'
+    } = opts;
+
+    let altKey = getAltKey();
+    let metaKey = getMetaKey();
+
+    if (typeof row === 'string' || typeof row === 'number') {
+      row = this.findRow({indexOrText: row});
+    }
+
+    if (!row) {
+      throw new Error(`Target row "${formatTargetNode(opts.row)}" not found in the gridlist.`);
+    }
+
+    let rowCheckbox = within(row).queryByRole('checkbox');
+
+    if (
+      rowCheckbox?.getAttribute('disabled') === '' ||
+      row?.getAttribute('aria-disabled') === 'true'
+    ) {
+      throw new Error(`Cannot toggle selection on disabled row "${formatTargetNode(opts.row)}".`);
+    }
+
+    // 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 || !rowCheckbox)) {
+      await this.keyboardNavigateToRow({
+        row,
+        selectionOnNav: selectionBehavior === 'replace' ? 'none' : 'default'
+      });
+      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) {
+      await pressElement(this.user, rowCheckbox, interactionType);
+    } else {
+      let cell = within(row).getAllByRole('gridcell')[0];
+      if (needsLongPress && interactionType === 'touch') {
+        // 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 {
+        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}]`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Triggers the action for the specified gridlist row. Defaults to using the interaction type set
+   * on the gridlist tester.
+   */
+  async triggerRowAction(opts: GridListRowActionOpts): Promise<void> {
+    let {row, needsDoubleClick, interactionType = this._interactionType} = opts;
+
+    if (typeof row === 'string' || typeof row === 'number') {
+      row = this.findRow({indexOrText: row});
+    }
+
+    if (!row) {
+      throw new Error(`Target row "${formatTargetNode(opts.row)}" not found in the gridlist.`);
+    }
+
+    if (row.getAttribute('aria-disabled') === 'true') {
+      throw new Error(`Cannot trigger row action on disabled row "${formatTargetNode(opts.row)}".`);
+    }
+
+    if (needsDoubleClick) {
+      await this.user.dblClick(row);
+    } else if (interactionType === 'keyboard') {
+      await this.keyboardNavigateToRow({row, selectionOnNav: 'none'});
+      await this.user.keyboard('[Enter]');
+    } else {
+      await pressElement(this.user, row, interactionType);
+    }
+  }
+
+  /**
+   * Returns the gridlist.
+   */
+  getGridlist(): HTMLElement {
+    return this._gridlist;
+  }
+
+  /**
+   * Returns the gridlist's rows if any.
+   */
+  getRows(): HTMLElement[] {
+    return within(this.getGridlist()).queryAllByRole('row');
+  }
+
+  /**
+   * Returns the gridlist's selected rows if any.
+   */
+  getSelectedRows(): HTMLElement[] {
+    return this.getRows().filter(row => row.getAttribute('aria-selected') === 'true');
+  }
+
+  /**
+   * Returns the gridlist's cells if any. Can be filtered against a specific row if provided via
+   * `element`.
+   */
+  getCells(opts: {element?: HTMLElement} = {}): HTMLElement[] {
+    let {element = this.getGridlist()} = opts;
+    return within(element).queryAllByRole('gridcell');
+  }
+}

package/src/index.ts

@@ -10,6 +10,20 @@
  * governing permissions and limitations under the License.
  */
 
-export * from './events';
-export * from './testSetup';
-export * from './userEventMaps';
+export {triggerLongPress} from './utils';
+export {installMouseEvent, installPointerEvent} from './testSetup';
+export {pointerMap} from './userEventMaps';
+export {User} from './user';
+export type {CheckboxGroupTester} from './checkboxgroup';
+export type {ComboBoxTester} from './combobox';
+export type {DialogTester} from './dialog';
+export type {GridListTester} from './gridlist';
+export type {ListBoxTester} from './listbox';
+export type {MenuTester} from './menu';
+export type {RadioGroupTester} from './radiogroup';
+export type {SelectTester} from './select';
+export type {TableTester} from './table';
+export type {TabsTester} from './tabs';
+export type {TreeTester} from './tree';
+
+export type {UserOpts} from './types';

package/src/listbox.ts

@@ -0,0 +1,300 @@
+/*
+ * Copyright 2024 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 {act} from './act';
+import {formatTargetNode, getAltKey, getMetaKey, pressElement, triggerLongPress} from './utils';
+import {ListBoxTesterOpts, UserOpts} from './types';
+import {within} from '@testing-library/dom';
+
+interface ListBoxToggleOptionOpts {
+  /**
+   * What interaction type to use when toggling selection for an option. Defaults to the interaction
+   * type set on the tester.
+   */
+  interactionType?: UserOpts['interactionType'];
+  /**
+   * The index, text, or node of the option to toggle selection for.
+   */
+  option: number | string | HTMLElement;
+  /**
+   * Whether the option should be triggered by Space or Enter in keyboard modality.
+   *
+   * @default 'Enter'
+   */
+  keyboardActivation?: 'Space' | 'Enter';
+  /**
+   * Whether the option needs to be long pressed to be selected. Depends on the listbox's
+   * implementation.
+   */
+  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'
+> {
+  /**
+   * Whether or not the option needs a double click to trigger the option action. Depends on the
+   * listbox's implementation.
+   */
+  needsDoubleClick?: boolean;
+}
+
+export class ListBoxTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _advanceTimer: UserOpts['advanceTimer'];
+  private _listbox: HTMLElement;
+  private _layout: ListBoxTesterOpts['layout'];
+
+  constructor(opts: ListBoxTesterOpts) {
+    let {root, user, interactionType, advanceTimer, layout} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+    this._advanceTimer = advanceTimer;
+    this._layout = layout || 'stack';
+    this._listbox = root;
+    if (root.getAttribute('role') !== 'listbox') {
+      let listbox = within(root).queryByRole('listbox');
+      if (listbox) {
+        this._listbox = listbox;
+      }
+    }
+  }
+
+  /**
+   * Set the interaction type used by the listbox tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']): void {
+    this._interactionType = type;
+  }
+
+  /**
+   * Returns a option matching the specified index or text content.
+   */
+  findOption(opts: {indexOrText: number | string}): HTMLElement {
+    let {indexOrText} = opts;
+
+    let option;
+    let options = this.getOptions();
+
+    if (typeof indexOrText === 'number') {
+      option = options[indexOrText];
+    } else if (typeof indexOrText === 'string') {
+      option = within(this.getListbox()!)
+        .getByText(indexOrText)
+        .closest('[role=option]')! as HTMLElement;
+    }
+
+    return option;
+  }
+
+  private async keyboardNavigateToOption(opts: {
+    option: HTMLElement;
+    selectionOnNav?: 'default' | 'none';
+  }) {
+    let {option, selectionOnNav = 'default'} = opts;
+    let altKey = getAltKey();
+    let options = this.getOptions();
+    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)
+    ) {
+      act(() => this._listbox.focus());
+      await this.user.keyboard(
+        `${selectionOnNav === 'none' ? `[${altKey}>]` : ''}[ArrowDown]${selectionOnNav === 'none' ? `[/${altKey}]` : ''}`
+      );
+    }
+
+    let currIndex = options.indexOf(document.activeElement as HTMLElement);
+    if (currIndex === -1) {
+      throw new Error('ActiveElement is not in the listbox');
+    }
+
+    if (selectionOnNav === 'none') {
+      await this.user.keyboard(`[${altKey}>]`);
+    }
+    if (this._layout === 'grid') {
+      while (document.activeElement !== option) {
+        let curr = (document.activeElement as HTMLElement).getBoundingClientRect();
+        let target = option.getBoundingClientRect();
+        let key: string;
+        // compare current position with desired position to determine if we need to go up/down/left/right
+        // use 1 in the comparison here for subpixels since getBoundingClientRect returns subpixels precision
+        if (Math.abs(curr.top - target.top) > 1) {
+          key = curr.top < target.top ? 'ArrowDown' : 'ArrowUp';
+        } else if (Math.abs(curr.left - target.left) > 1) {
+          key = curr.left < target.left ? 'ArrowRight' : 'ArrowLeft';
+        } else {
+          // if the diff in current vs desired is < 1 but it is claiming we arent focused on the target
+          // then we might be in a case where getBoundingClientRect isnt mocked
+          throw new Error(
+            'Could not navigate to target option in grid layout. Did the test mock getBoundingClientRect?'
+          );
+        }
+        await this.user.keyboard(`[${key}]`);
+      }
+    } else {
+      let direction = targetIndex > currIndex ? 'down' : 'up';
+      for (let i = 0; i < Math.abs(targetIndex - currIndex); i++) {
+        await this.user.keyboard(`[${direction === 'down' ? 'ArrowDown' : 'ArrowUp'}]`);
+      }
+    }
+    if (selectionOnNav === 'none') {
+      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,
+      selectionBehavior = 'toggle'
+    } = opts;
+
+    let altKey = getAltKey();
+    let metaKey = getMetaKey();
+
+    if (typeof option === 'string' || typeof option === 'number') {
+      option = this.findOption({indexOrText: option});
+    }
+
+    if (!option) {
+      throw new Error(`Target option "${formatTargetNode(opts.option)}" not found in the listbox.`);
+    }
+
+    if (interactionType === 'keyboard') {
+      if (option?.getAttribute('aria-disabled') === 'true') {
+        throw new Error(
+          `Cannot toggle selection on disabled option "${formatTargetNode(opts.option)}".`
+        );
+      }
+
+      await this.keyboardNavigateToOption({
+        option,
+        selectionOnNav: selectionBehavior === 'replace' ? 'none' : 'default'
+      });
+      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') {
+        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}]`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Triggers the action for the specified listbox option. Defaults to using the interaction type
+   * set on the listbox tester.
+   */
+  async triggerOptionAction(opts: ListBoxOptionActionOpts): Promise<void> {
+    let {option, needsDoubleClick, interactionType = this._interactionType} = opts;
+
+    if (typeof option === 'string' || typeof option === 'number') {
+      option = this.findOption({indexOrText: option});
+    }
+
+    if (!option) {
+      throw new Error(`Target option "${formatTargetNode(opts.option)}" not found in the listbox.`);
+    }
+
+    if (needsDoubleClick) {
+      await this.user.dblClick(option);
+    } else if (interactionType === 'keyboard') {
+      if (option?.getAttribute('aria-disabled') === 'true') {
+        throw new Error(
+          `Cannot trigger action on disabled option "${formatTargetNode(opts.option)}".`
+        );
+      }
+
+      await this.keyboardNavigateToOption({option, selectionOnNav: 'none'});
+      await this.user.keyboard('[Enter]');
+    } else {
+      await pressElement(this.user, option, interactionType);
+    }
+  }
+
+  /**
+   * Returns the listbox.
+   */
+  getListbox(): HTMLElement {
+    return this._listbox;
+  }
+
+  /**
+   * Returns the listbox options. Can be filtered to a subsection of the listbox if provided via
+   * `element`.
+   */
+  getOptions(opts: {element?: HTMLElement} = {}): HTMLElement[] {
+    let {element = this._listbox} = opts;
+    let options = [];
+    if (element) {
+      options = within(element).queryAllByRole('option');
+    }
+
+    return options;
+  }
+
+  /**
+   * Returns the listbox's selected options if any.
+   */
+  getSelectedOptions(): HTMLElement[] {
+    return this.getOptions().filter(row => row.getAttribute('aria-selected') === 'true');
+  }
+
+  /**
+   * Returns the listbox's sections if any.
+   */
+  getSections(): HTMLElement[] {
+    return within(this._listbox).queryAllByRole('group');
+  }
+}