@react-aria/test-utils 1.0.0-alpha.3 → 1.0.0-alpha.4

package/src/gridlist.ts

@@ -11,106 +11,193 @@
  */
 
 import {act, within} from '@testing-library/react';
-import {BaseTesterOpts, UserOpts} from './user';
-import {pressElement} from './events';
+import {GridListTesterOpts, GridRowActionOpts, ToggleGridRowOpts, UserOpts} from './types';
+import {pressElement, triggerLongPress} from './events';
+
+interface GridListToggleRowOpts extends ToggleGridRowOpts {}
+interface GridListRowActionOpts extends GridRowActionOpts {}
 
-export interface GridListOptions extends UserOpts, BaseTesterOpts {
-  user?: any
-}
 export class GridListTester {
   private user;
   private _interactionType: UserOpts['interactionType'];
+  private _advanceTimer: UserOpts['advanceTimer'];
   private _gridlist: HTMLElement;
 
-
-  constructor(opts: GridListOptions) {
-    let {root, user, interactionType} = opts;
+  constructor(opts: GridListTesterOpts) {
+    let {root, user, interactionType, advanceTimer} = opts;
     this.user = user;
     this._interactionType = interactionType || 'mouse';
+    this._advanceTimer = advanceTimer;
     this._gridlist = root;
   }
 
-  setInteractionType = (type: UserOpts['interactionType']) => {
+  /**
+   * Set the interaction type used by the gridlist tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']) {
     this._interactionType = type;
+  }
+
+  /**
+   * Returns a row matching the specified index or text content.
+   */
+  findRow(opts: {rowIndexOrText: number | string}): HTMLElement {
+    let {
+      rowIndexOrText
+    } = opts;
+
+    let row;
+    if (typeof rowIndexOrText === 'number') {
+      row = this.rows[rowIndexOrText];
+    } else if (typeof rowIndexOrText === 'string') {
+      row = (within(this.gridlist!).getByText(rowIndexOrText).closest('[role=row]'))! as HTMLElement;
+    }
+
+    return row;
+  }
+
+  // TODO: RTL
+  private async keyboardNavigateToRow(opts: {row: HTMLElement}) {
+    let {row} = opts;
+    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) {
+      await this.user.keyboard('[ArrowDown]');
+    } else if (this._gridlist.contains(document.activeElement) && document.activeElement!.getAttribute('role') !== 'row') {
+      do {
+        await this.user.keyboard('[ArrowLeft]');
+      } 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');
+    }
+    let direction = targetIndex > currIndex ? 'down' : 'up';
+
+    for (let i = 0; i < Math.abs(targetIndex - currIndex); i++) {
+      await this.user.keyboard(`[${direction === 'down' ? 'ArrowDown' : 'ArrowUp'}]`);
+    }
   };
 
-  // TODO: support long press? This is also pretty much the same as table's toggleRowSelection so maybe can share
-  // For now, don't include long press, see if people need it or if we should just expose long press as a separate util if it isn't very common
-  // If the current way of passing in the user specified advance timers is ok, then I'd be find including long press
-  // Maybe also support an option to force the click to happen on a specific part of the element (checkbox or row). That way
-  // the user can test a specific type of interaction?
-  toggleRowSelection = async (opts: {index?: number, text?: string, interactionType?: UserOpts['interactionType']} = {}) => {
-    let {index, text, interactionType = this._interactionType} = opts;
+  /**
+   * Toggles the selection for the specified gridlist row. Defaults to using the interaction type set on the gridlist tester.
+   */
+  async toggleRowSelection(opts: GridListToggleRowOpts) {
+    let {
+      row,
+      needsLongPress,
+      checkboxSelection = true,
+      interactionType = this._interactionType
+    } = opts;
+
+    if (typeof row === 'string' || typeof row === 'number') {
+      row = this.findRow({rowIndexOrText: row});
+    }
+
+    if (!row) {
+      throw new Error('Target row not found in the gridlist.');
+    }
 
-    let row = this.findRow({index, text});
     let rowCheckbox = within(row).queryByRole('checkbox');
-    if (rowCheckbox) {
+
+    // TODO: we early return here because the checkbox/row can't be keyboard navigated to if the row is disabled usually
+    // but we may to check for disabledBehavior (aka if the disable row gets skipped when keyboard navigating or not)
+    if (interactionType === 'keyboard' && (rowCheckbox?.getAttribute('disabled') === '' || row?.getAttribute('aria-disabled') === 'true')) {
+      return;
+    }
+
+    // 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}');
+      return;
+    }
+    if (rowCheckbox && checkboxSelection) {
       await pressElement(this.user, rowCheckbox, interactionType);
     } else {
       let cell = within(row).getAllByRole('gridcell')[0];
-      await pressElement(this.user, cell, interactionType);
-    }
-  };
+      if (needsLongPress && interactionType === 'touch') {
+        if (this._advanceTimer == null) {
+          throw new Error('No advanceTimers provided for long press.');
+        }
 
-  // TODO: pretty much the same as table except it uses this.gridlist. Make common between the two by accepting an option for
-  // an element?
-  findRow = (opts: {index?: number, text?: string}) => {
-    let {
-      index,
-      text
-    } = opts;
+        // Note that long press interactions with rows is strictly touch only for grid rows
+        await triggerLongPress({element: cell, advanceTimer: this._advanceTimer, pointerOpts: {pointerType: 'touch'}});
 
-    let row;
-    if (index != null) {
-      row = this.rows[index];
-    } else if (text != null) {
-      row = within(this?.gridlist).getByText(text);
-      while (row && row.getAttribute('role') !== 'row') {
-        row = row.parentElement;
+      } else {
+        await pressElement(this.user, cell, interactionType);
       }
     }
-
-    return row;
-  };
+  }
 
   // TODO: There is a more difficult use case where the row has/behaves as link, don't think we have a good way to determine that unless the
   // user specificlly tells us
-  triggerRowAction = async (opts: {index?: number, text?: string, needsDoubleClick?: boolean, interactionType?: UserOpts['interactionType']}) => {
+  /**
+   * Triggers the action for the specified gridlist row. Defaults to using the interaction type set on the gridlist tester.
+   */
+  async triggerRowAction(opts: GridListRowActionOpts) {
     let {
-      index,
-      text,
+      row,
       needsDoubleClick,
       interactionType = this._interactionType
     } = opts;
 
-    let row = this.findRow({index, text});
-    if (row) {
-      if (needsDoubleClick) {
-        await this.user.dblClick(row);
-      } else if (interactionType === 'keyboard') {
-        act(() => row.focus());
-        await this.user.keyboard('[Enter]');
-      } else {
-        await pressElement(this.user, row, interactionType);
+    if (typeof row === 'string' || typeof row === 'number') {
+      row = this.findRow({rowIndexOrText: row});
+    }
+
+    if (!row) {
+      throw new Error('Target row not found in the gridlist.');
+    }
+
+    if (needsDoubleClick) {
+      await this.user.dblClick(row);
+    } else if (interactionType === 'keyboard') {
+      if (row?.getAttribute('aria-disabled') === 'true') {
+        return;
+      }
+
+      if (document.activeElement !== this._gridlist || !this._gridlist.contains(document.activeElement)) {
+        act(() => this._gridlist.focus());
       }
+
+      await this.keyboardNavigateToRow({row});
+      await this.user.keyboard('[Enter]');
+    } else {
+      await pressElement(this.user, row, interactionType);
     }
-  };
+  }
 
-  // TODO: do we really need this getter? Theoretically the user already has the reference to the gridlist
-  get gridlist() {
+  /**
+   * Returns the gridlist.
+   */
+  get gridlist(): HTMLElement {
     return this._gridlist;
   }
 
-  get rows() {
+  /**
+   * Returns the gridlist's rows if any.
+   */
+  get rows(): HTMLElement[] {
     return within(this?.gridlist).queryAllByRole('row');
   }
 
-  get selectedRows() {
+  /**
+   * Returns the gridlist's selected rows if any.
+   */
+  get selectedRows(): HTMLElement[] {
     return this.rows.filter(row => row.getAttribute('aria-selected') === 'true');
   }
 
-  cells = (opts: {element?: HTMLElement} = {}) => {
-    let {element} = opts;
-    return within(element || this.gridlist).queryAllByRole('gridcell');
-  };
+  /**
+   * Returns the gridlist's cells if any. Can be filtered against a specific row if provided via `element`.
+   */
+  cells(opts: {element?: HTMLElement} = {}): HTMLElement[] {
+    let {element = this.gridlist} = opts;
+    return within(element).queryAllByRole('gridcell');
+  }
 }

package/src/index.ts

@@ -15,4 +15,4 @@ export {installMouseEvent, installPointerEvent} from './testSetup';
 export {pointerMap} from './userEventMaps';
 export {User} from './user';
 
-export type {UserOpts} from './user';
+export type {UserOpts} from './types';

package/src/listbox.ts

@@ -0,0 +1,226 @@
+/*
+ * 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, within} from '@testing-library/react';
+import {ListBoxTesterOpts, UserOpts} from './types';
+import {pressElement, triggerLongPress} from './events';
+
+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
+}
+
+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;
+
+  constructor(opts: ListBoxTesterOpts) {
+    let {root, user, interactionType, advanceTimer} = opts;
+    this.user = user;
+    this._interactionType = interactionType || 'mouse';
+    this._listbox = root;
+    this._advanceTimer = advanceTimer;
+  }
+
+  /**
+   * Set the interaction type used by the listbox tester.
+   */
+  setInteractionType(type: UserOpts['interactionType']) {
+    this._interactionType = type;
+  }
+
+  // TODO: now that we have listbox, perhaps select can make use of this tester internally
+  /**
+   * Returns a option matching the specified index or text content.
+   */
+  findOption(opts: {optionIndexOrText: number | string}): HTMLElement {
+    let {
+      optionIndexOrText
+    } = opts;
+
+    let option;
+    let options = this.options();
+
+    if (typeof optionIndexOrText === 'number') {
+      option = options[optionIndexOrText];
+    } else if (typeof optionIndexOrText === 'string') {
+      option = (within(this.listbox!).getByText(optionIndexOrText).closest('[role=option]'))! as HTMLElement;
+    }
+
+    return option;
+  }
+
+  // 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;
+    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) {
+      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();
+      });
+    }
+
+    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';
+
+    for (let i = 0; i < Math.abs(targetIndex - currIndex); i++) {
+      await this.user.keyboard(`[${direction === 'down' ? 'ArrowDown' : 'ArrowUp'}]`);
+    }
+  };
+
+  /**
+   * Toggles the selection for the specified listbox option. Defaults to using the interaction type set on the listbox tester.
+   */
+  async toggleOptionSelection(opts: ListBoxToggleOptionOpts) {
+    let {option, needsLongPress, keyboardActivation = 'Enter', interactionType = this._interactionType} = opts;
+
+    if (typeof option === 'string' || typeof option === 'number') {
+      option = this.findOption({optionIndexOrText: option});
+    }
+
+    if (!option) {
+      throw new Error('Target option not found in the listbox.');
+    }
+
+    if (interactionType === 'keyboard') {
+      if (option?.getAttribute('aria-disabled') === 'true') {
+        return;
+      }
+
+      if (document.activeElement !== this._listbox || !this._listbox.contains(document.activeElement)) {
+        act(() => this._listbox.focus());
+      }
+
+      await this.keyboardNavigateToOption({option});
+      await this.user.keyboard(`[${keyboardActivation}]`);
+    } else {
+      if (needsLongPress && interactionType === 'touch') {
+        if (this._advanceTimer == null) {
+          throw new Error('No advanceTimers provided for long press.');
+        }
+
+        await triggerLongPress({element: option, advanceTimer: this._advanceTimer, pointerOpts: {pointerType: 'touch'}});
+      } else {
+        await pressElement(this.user, option, interactionType);
+      }
+    }
+  }
+
+  /**
+   * Triggers the action for the specified listbox option. Defaults to using the interaction type set on the listbox tester.
+   */
+  async triggerOptionAction(opts: ListBoxOptionActionOpts) {
+    let {
+      option,
+      needsDoubleClick,
+      interactionType = this._interactionType
+    } = opts;
+
+    if (typeof option === 'string' || typeof option === 'number') {
+      option = this.findOption({optionIndexOrText: option});
+    }
+
+    if (!option) {
+      throw new Error('Target option not found in the listbox.');
+    }
+
+    if (needsDoubleClick) {
+      await this.user.dblClick(option);
+    } else if (interactionType === 'keyboard') {
+      if (option?.getAttribute('aria-disabled') === 'true') {
+        return;
+      }
+
+      if (document.activeElement !== this._listbox || !this._listbox.contains(document.activeElement)) {
+        act(() => this._listbox.focus());
+      }
+
+      await this.keyboardNavigateToOption({option});
+      await this.user.keyboard('[Enter]');
+    } else {
+      await pressElement(this.user, option, interactionType);
+    }
+  }
+
+  /**
+   * Returns the listbox.
+   */
+  get listbox(): HTMLElement {
+    return this._listbox;
+  }
+
+  /**
+   * Returns the listbox options. Can be filtered to a subsection of the listbox if provided via `element`.
+   */
+  options(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.
+   */
+  get selectedOptions(): HTMLElement[] {
+    return this.options().filter(row => row.getAttribute('aria-selected') === 'true');
+  }
+
+  /**
+   * Returns the listbox's sections if any.
+   */
+  get sections(): HTMLElement[] {
+    return within(this._listbox).queryAllByRole('group');
+  }
+}