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

package/src/table.ts

@@ -0,0 +1,589 @@
+/*
+ * 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 {
+  BaseGridRowInteractionOpts,
+  Direction,
+  GridRowActionOpts,
+  TableTesterOpts,
+  ToggleGridRowOpts,
+  UserOpts
+} from './types';
+import {formatTargetNode, getAltKey, getMetaKey, pressElement, triggerLongPress} from './utils';
+import {waitFor, within} from '@testing-library/dom';
+
+interface TableToggleRowOpts extends ToggleGridRowOpts {}
+interface TableToggleExpansionOpts extends BaseGridRowInteractionOpts {}
+interface TableToggleSortOpts {
+  /**
+   * The index, text, or node of the column to toggle selection for.
+   */
+  column: number | string | HTMLElement;
+  /**
+   * What interaction type to use when sorting the column. Defaults to the interaction type set on
+   * the tester.
+   */
+  interactionType?: UserOpts['interactionType'];
+}
+interface TableColumnHeaderActionOpts extends TableToggleSortOpts {
+  /**
+   * The index of the column header action to trigger.
+   */
+  action: number;
+}
+interface TableRowActionOpts extends GridRowActionOpts {}
+
+export class TableTester {
+  private user;
+  private _interactionType: UserOpts['interactionType'];
+  private _advanceTimer: UserOpts['advanceTimer'];
+  private _direction: Direction;
+  private _table: HTMLElement;
+
+  constructor(opts: TableTesterOpts) {
+    let {root, user, interactionType, advanceTimer, direction} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+    this._advanceTimer = advanceTimer;
+    this._direction = direction || 'ltr';
+    this._table = root;
+    let role = root.getAttribute('role');
+    if (role !== 'grid' && role !== 'treegrid') {
+      let table = within(root).queryByRole('grid') || within(root).queryByRole('treegrid');
+      if (table) {
+        this._table = table;
+      }
+    }
+  }
+
+  /**
+   * Set the interaction type used by the table tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']): void {
+    this._interactionType = type;
+  }
+
+  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 table');
+    }
+
+    // Move focus into the table
+    if (document.activeElement !== this._table && !this._table.contains(document.activeElement)) {
+      act(() => this._table.focus());
+    }
+
+    if (document.activeElement === this._table) {
+      await this.user.keyboard('[ArrowDown]');
+    }
+
+    let rowGroups = this.getRowGroups();
+    // If focus is currently somewhere in the first row group (aka on a column), we want to keyboard navigate downwards till we reach the rows
+    if (rowGroups[0].contains(document.activeElement)) {
+      do {
+        await this.user.keyboard('[ArrowDown]');
+      } while (!rowGroups[1].contains(document.activeElement));
+    }
+
+    // Move focus onto the row itself
+    let focusPrevKey = this._direction === 'rtl' ? 'ArrowRight' : 'ArrowLeft';
+    if (
+      rowGroups[1].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('Current active element is not on any of the table rows');
+    }
+    let direction = targetIndex > currIndex ? 'down' : 'up';
+
+    if (selectionOnNav === 'none') {
+      await this.user.keyboard(`[${altKey}>]`);
+    }
+    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 table row. Defaults to using the interaction type set
+   * on the table tester.
+   */
+  async toggleRowSelection(opts: TableToggleRowOpts): 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 table.`);
+    }
+
+    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)}".`);
+    }
+
+    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, cell, interactionType);
+        if (selectionBehavior === 'replace' && interactionType !== 'touch') {
+          await this.user.keyboard(`[/${metaKey}]`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Toggles the expansion for the specified tree row. Defaults to using the interaction type set on
+   * the tree tester.
+   */
+  async toggleRowExpansion(opts: TableToggleExpansionOpts): Promise<void> {
+    let {row, interactionType = this._interactionType} = opts;
+    if (!this.getTable().contains(document.activeElement)) {
+      await act(async () => {
+        this.getTable().focus();
+      });
+    }
+
+    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 table.`);
+    } else if (row.getAttribute('aria-expanded') == null) {
+      throw new Error(`Target row "${formatTargetNode(opts.row)}" is not expandable.`);
+    }
+
+    if (row.getAttribute('aria-disabled') === 'true') {
+      throw new Error(`Cannot toggle expansion on disabled row "${formatTargetNode(opts.row)}".`);
+    }
+
+    if (interactionType === 'mouse' || interactionType === 'touch') {
+      let rowExpander = within(row).getAllByRole('button')[0]; // what happens if the button is not first? how can we differentiate?
+      await pressElement(this.user, rowExpander, interactionType);
+    } else if (interactionType === 'keyboard') {
+      // note that our keyboard navigation makes sure selection isn't changes
+      await this.keyboardNavigateToRow({row});
+      let collapseKey = this._direction === 'rtl' ? 'ArrowRight' : 'ArrowLeft';
+      let expandKey = this._direction === 'rtl' ? 'ArrowLeft' : 'ArrowRight';
+      if (row.getAttribute('aria-expanded') === 'true') {
+        await this.user.keyboard(`[${collapseKey}]`);
+      } else {
+        await this.user.keyboard(`[${expandKey}]`);
+      }
+    }
+  }
+
+  /**
+   * Toggles the sort order for the specified table column. Defaults to using the interaction type
+   * set on the table tester.
+   */
+  async toggleSort(opts: TableToggleSortOpts): Promise<void> {
+    let {column, interactionType = this._interactionType} = opts;
+
+    let columnheader;
+    if (typeof column === 'number') {
+      columnheader = this.getColumns()[column];
+    } else if (typeof column === 'string') {
+      columnheader = within(this.getRowGroups()[0]).getByText(column);
+      while (columnheader && !/columnheader/.test(columnheader.getAttribute('role'))) {
+        columnheader = columnheader.parentElement;
+      }
+    } else {
+      columnheader = column;
+    }
+
+    let menuButton = within(columnheader).queryByRole('button');
+    if (menuButton) {
+      let currentSort = columnheader.getAttribute('aria-sort');
+      // TODO: Focus management is all kinda of messed up if I just use .focus and Space to open the sort menu. Seems like
+      // the focused key doesn't get properly set to the desired column header. Have to do this strange flow where I focus the
+      // column header except if the active element is already the menu button within the column header
+      if (interactionType === 'keyboard' && document.activeElement !== menuButton) {
+        await pressElement(this.user, columnheader, interactionType);
+      } else {
+        await pressElement(this.user, menuButton, interactionType);
+      }
+
+      await waitFor(() => {
+        if (menuButton.getAttribute('aria-controls') == null) {
+          throw new Error('No aria-controls found on table column dropdown menu trigger element.');
+        } else {
+          return true;
+        }
+      });
+
+      let menuId = menuButton.getAttribute('aria-controls');
+      await waitFor(() => {
+        if (!menuId || document.getElementById(menuId) == null) {
+          throw new Error(`Table column header menu with id of ${menuId} not found in document.`);
+        } else {
+          return true;
+        }
+      });
+
+      if (menuId) {
+        let menu = document.getElementById(menuId);
+        if (menu) {
+          if (currentSort === 'ascending') {
+            await pressElement(
+              this.user,
+              within(menu).getAllByRole('menuitem')[1],
+              interactionType
+            );
+          } else {
+            await pressElement(
+              this.user,
+              within(menu).getAllByRole('menuitem')[0],
+              interactionType
+            );
+          }
+
+          await waitFor(() => {
+            if (document.contains(menu)) {
+              throw new Error(
+                'Expected table column menu listbox to not be in the document after selecting an option'
+              );
+            } else {
+              return true;
+            }
+          });
+        }
+      }
+
+      // Handle cases where the table may transition in response to the row selection/deselection
+      await act(async () => {
+        await this._advanceTimer!(200);
+      });
+
+      await waitFor(() => {
+        if (document.activeElement !== menuButton) {
+          throw new Error(
+            `Expected the document.activeElement to be the table column menu button but got ${document.activeElement}`
+          );
+        } else {
+          return true;
+        }
+      });
+    } else {
+      await pressElement(this.user, columnheader, interactionType);
+    }
+  }
+
+  /**
+   * Triggers an action for the specified table column menu. Defaults to using the interaction type
+   * set on the table tester.
+   */
+  async triggerColumnHeaderAction(opts: TableColumnHeaderActionOpts): Promise<void> {
+    let {column, interactionType = this._interactionType, action} = opts;
+
+    let columnheader;
+    if (typeof column === 'number') {
+      columnheader = this.getColumns()[column];
+    } else if (typeof column === 'string') {
+      columnheader = within(this.getRowGroups()[0]).getByText(column);
+      while (columnheader && !/columnheader/.test(columnheader.getAttribute('role'))) {
+        columnheader = columnheader.parentElement;
+      }
+    } else {
+      columnheader = column;
+    }
+
+    let menuButton = within(columnheader).queryByRole('button');
+    if (menuButton) {
+      // TODO: Focus management is all kinda of messed up if I just use .focus and Space to open the sort menu. Seems like
+      // the focused key doesn't get properly set to the desired column header. Have to do this strange flow where I focus the
+      // column header except if the active element is already the menu button within the column header
+      if (interactionType === 'keyboard' && document.activeElement !== menuButton) {
+        await pressElement(this.user, columnheader, interactionType);
+      } else {
+        await pressElement(this.user, menuButton, interactionType);
+      }
+
+      await waitFor(() => {
+        if (menuButton.getAttribute('aria-controls') == null) {
+          throw new Error('No aria-controls found on table column dropdown menu trigger element.');
+        } else {
+          return true;
+        }
+      });
+
+      let menuId = menuButton.getAttribute('aria-controls');
+      await waitFor(() => {
+        if (!menuId || document.getElementById(menuId) == null) {
+          throw new Error(`Table column header menu with id of ${menuId} not found in document.`);
+        } else {
+          return true;
+        }
+      });
+
+      if (menuId) {
+        let menu = document.getElementById(menuId);
+        if (menu) {
+          await pressElement(
+            this.user,
+            within(menu).getAllByRole('menuitem')[action],
+            interactionType
+          );
+
+          await waitFor(() => {
+            if (document.contains(menu)) {
+              throw new Error(
+                'Expected table column menu listbox to not be in the document after selecting an option'
+              );
+            } else {
+              return true;
+            }
+          });
+        }
+      }
+
+      // Handle cases where the table may transition in response to the row selection/deselection
+      await act(async () => {
+        await this._advanceTimer!(200);
+      });
+
+      await waitFor(() => {
+        if (document.activeElement !== menuButton) {
+          throw new Error(
+            `Expected the document.activeElement to be the table column menu button but got ${document.activeElement}`
+          );
+        } else {
+          return true;
+        }
+      });
+    } else {
+      throw new Error('No menu button found on table column header.');
+    }
+  }
+
+  /**
+   * Triggers the action for the specified table row. Defaults to using the interaction type set on
+   * the table tester.
+   */
+  async triggerRowAction(opts: TableRowActionOpts): 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 table.`);
+    }
+
+    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);
+    }
+  }
+
+  // Additionally, should we also support keyboard navigation/typeahead? Those felt like they could be very easily replicated by the user via user.keyboard already and don't really
+  // add much value if we provide that to them
+  /**
+   * Toggle selection for all rows in the table. Defaults to using the interaction type set on the
+   * table tester.
+   */
+  async toggleSelectAll(opts: {interactionType?: UserOpts['interactionType']} = {}): Promise<void> {
+    let {interactionType = this._interactionType} = opts;
+    if (interactionType === 'keyboard') {
+      let metaKey = getMetaKey();
+      let table = this.getTable();
+      if (document.activeElement !== table && !table.contains(document.activeElement)) {
+        act(() => table.focus());
+      }
+      await this.user.keyboard(`[${metaKey}>]a[/${metaKey}]`);
+    } else {
+      let checkbox = within(this.getTable()).getByLabelText('Select All');
+      await pressElement(this.user, checkbox, interactionType);
+    }
+  }
+
+  /**
+   * Returns a row matching the specified index or text content.
+   */
+  findRow(opts: {indexOrText: number | string}): HTMLElement {
+    let {indexOrText} = opts;
+
+    let row;
+    let rows = this.getRows();
+    let bodyRowGroup = this.getRowGroups()[1];
+    if (typeof indexOrText === 'number') {
+      row = rows[indexOrText];
+    } else if (typeof indexOrText === 'string') {
+      row = within(bodyRowGroup).getByText(indexOrText);
+      while (row && row.getAttribute('role') !== 'row') {
+        row = row.parentElement;
+      }
+    }
+
+    return row;
+  }
+
+  /**
+   * Returns a cell matching the specified text content.
+   */
+  findCell(opts: {text: string}): HTMLElement {
+    let {text} = opts;
+
+    let cell = within(this.getTable()).getByText(text);
+    if (cell) {
+      while (cell && !/gridcell|rowheader|columnheader/.test(cell.getAttribute('role') || '')) {
+        if (cell.parentElement) {
+          cell = cell.parentElement;
+        } else {
+          break;
+        }
+      }
+    }
+
+    return cell;
+  }
+
+  /**
+   * Returns the table.
+   */
+  getTable(): HTMLElement {
+    return this._table;
+  }
+
+  /**
+   * Returns the row groups within the table.
+   */
+  getRowGroups(): HTMLElement[] {
+    let table = this._table;
+    return table ? within(table).queryAllByRole('rowgroup') : [];
+  }
+
+  /**
+   * Returns the columns within the table.
+   */
+  getColumns(): HTMLElement[] {
+    let headerRowGroup = this.getRowGroups()[0];
+    return headerRowGroup ? within(headerRowGroup).queryAllByRole('columnheader') : [];
+  }
+
+  /**
+   * Returns the rows within the table if any. Can be filtered to a specific row group if provided
+   * via `element`.
+   */
+  getRows(opts: {element?: HTMLElement} = {}): HTMLElement[] {
+    let {element} = opts;
+    if (element != null) {
+      return within(element).queryAllByRole('row');
+    }
+    return this.getRowGroups()
+      .slice(1)
+      .flatMap(rowGroup => within(rowGroup).queryAllByRole('row'));
+  }
+
+  /**
+   * Returns the currently selected rows within the table if any.
+   */
+  getSelectedRows(): HTMLElement[] {
+    return this.getRows().filter(row => row.getAttribute('aria-selected') === 'true');
+  }
+
+  /**
+   * Returns the footer rows within the table if any.
+   */
+  getFooterRows(): HTMLElement[] {
+    let rowGroups = this.getRowGroups();
+    if (rowGroups.length < 3) {
+      return [];
+    }
+    let footerRowGroup = rowGroups.at(-1);
+    return footerRowGroup ? within(footerRowGroup).queryAllByRole('row') : [];
+  }
+
+  /**
+   * Returns the row headers within the table if any.
+   */
+  getRowHeaders(): HTMLElement[] {
+    return within(this.getTable()).queryAllByRole('rowheader');
+  }
+
+  /**
+   * Returns the cells within the table if any. Can be filtered against a specific row if provided
+   * via `element`.
+   */
+  getCells(opts: {element?: HTMLElement} = {}): HTMLElement[] {
+    let {element = this.getTable()} = opts;
+    return within(element).queryAllByRole('gridcell');
+  }
+}