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

package/dist/types/src/select.d.ts

@@ -0,0 +1,74 @@
+import { SelectTesterOpts, UserOpts } from './types';
+interface SelectOpenOpts {
+    /**
+     * What interaction type to use when opening the select. Defaults to the interaction type set on
+     * the tester.
+     */
+    interactionType?: UserOpts['interactionType'];
+}
+interface SelectTriggerOptionOpts extends SelectOpenOpts {
+    /**
+     * The index, text, or node of the option to select. Option nodes can be sourced via
+     * `getOptions()`.
+     */
+    option: number | string | HTMLElement;
+    /**
+     * Whether or not the select closes on selection. Depends on select implementation and
+     * configuration.
+     *
+     * @default true
+     */
+    closesOnSelect?: boolean;
+}
+export declare class SelectTester {
+    private user;
+    private _interactionType;
+    private _trigger;
+    constructor(opts: SelectTesterOpts);
+    /**
+     * Set the interaction type used by the select tester.
+     */
+    setInteractionType(type: UserOpts['interactionType']): void;
+    /**
+     * Opens the select. Defaults to using the interaction type set on the select tester.
+     */
+    open(opts?: SelectOpenOpts): Promise<void>;
+    /**
+     * Closes the select.
+     */
+    close(): Promise<void>;
+    /**
+     * Returns a option matching the specified index or text content.
+     */
+    findOption(opts: {
+        indexOrText: number | string;
+    }): HTMLElement;
+    private keyboardNavigateToOption;
+    /**
+     * Toggles the selection of the desired select option if possible. Defaults to using the
+     * interaction type set on the select tester. If necessary, will open the select dropdown
+     * beforehand. The desired option can be targeted via the option's node, the option's text, or the
+     * option's index.
+     */
+    toggleOptionSelection(opts: SelectTriggerOptionOpts): Promise<void>;
+    /**
+     * Returns the select's options if present. Can be filtered to a subsection of the listbox if
+     * provided via `element`.
+     */
+    getOptions(opts?: {
+        element?: HTMLElement;
+    }): HTMLElement[];
+    /**
+     * Returns the select's trigger.
+     */
+    getTrigger(): HTMLElement;
+    /**
+     * Returns the select's listbox if present.
+     */
+    getListbox(): HTMLElement | null;
+    /**
+     * Returns the select's sections if present.
+     */
+    getSections(): HTMLElement[];
+}
+export {};

package/dist/types/src/table.d.ts

@@ -0,0 +1,120 @@
+import { BaseGridRowInteractionOpts, GridRowActionOpts, TableTesterOpts, ToggleGridRowOpts, UserOpts } from './types';
+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 declare class TableTester {
+    private user;
+    private _interactionType;
+    private _advanceTimer;
+    private _direction;
+    private _table;
+    constructor(opts: TableTesterOpts);
+    /**
+     * Set the interaction type used by the table tester.
+     */
+    setInteractionType(type: UserOpts['interactionType']): void;
+    private keyboardNavigateToRow;
+    /**
+     * Toggles the selection for the specified table row. Defaults to using the interaction type set
+     * on the table tester.
+     */
+    toggleRowSelection(opts: TableToggleRowOpts): Promise<void>;
+    /**
+     * Toggles the expansion for the specified tree row. Defaults to using the interaction type set on
+     * the tree tester.
+     */
+    toggleRowExpansion(opts: TableToggleExpansionOpts): Promise<void>;
+    /**
+     * Toggles the sort order for the specified table column. Defaults to using the interaction type
+     * set on the table tester.
+     */
+    toggleSort(opts: TableToggleSortOpts): Promise<void>;
+    /**
+     * Triggers an action for the specified table column menu. Defaults to using the interaction type
+     * set on the table tester.
+     */
+    triggerColumnHeaderAction(opts: TableColumnHeaderActionOpts): Promise<void>;
+    /**
+     * Triggers the action for the specified table row. Defaults to using the interaction type set on
+     * the table tester.
+     */
+    triggerRowAction(opts: TableRowActionOpts): Promise<void>;
+    /**
+     * Toggle selection for all rows in the table. Defaults to using the interaction type set on the
+     * table tester.
+     */
+    toggleSelectAll(opts?: {
+        interactionType?: UserOpts['interactionType'];
+    }): Promise<void>;
+    /**
+     * Returns a row matching the specified index or text content.
+     */
+    findRow(opts: {
+        indexOrText: number | string;
+    }): HTMLElement;
+    /**
+     * Returns a cell matching the specified text content.
+     */
+    findCell(opts: {
+        text: string;
+    }): HTMLElement;
+    /**
+     * Returns the table.
+     */
+    getTable(): HTMLElement;
+    /**
+     * Returns the row groups within the table.
+     */
+    getRowGroups(): HTMLElement[];
+    /**
+     * Returns the columns within the table.
+     */
+    getColumns(): HTMLElement[];
+    /**
+     * 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[];
+    /**
+     * Returns the currently selected rows within the table if any.
+     */
+    getSelectedRows(): HTMLElement[];
+    /**
+     * Returns the footer rows within the table if any.
+     */
+    getFooterRows(): HTMLElement[];
+    /**
+     * Returns the row headers within the table if any.
+     */
+    getRowHeaders(): HTMLElement[];
+    /**
+     * Returns the cells within the table if any. Can be filtered against a specific row if provided
+     * via `element`.
+     */
+    getCells(opts?: {
+        element?: HTMLElement;
+    }): HTMLElement[];
+}
+export {};

package/dist/types/src/tabs.d.ts

@@ -0,0 +1,59 @@
+import { TabsTesterOpts, UserOpts } from './types';
+interface TriggerTabOptions {
+    /**
+     * What interaction type to use when triggering a tab. Defaults to the interaction type set on the
+     * tester.
+     */
+    interactionType?: UserOpts['interactionType'];
+    /**
+     * The index, text, or node of the tab to toggle selection for.
+     */
+    tab: number | string | HTMLElement;
+    /**
+     * Whether the tab needs to be activated manually rather than on focus.
+     */
+    manualActivation?: boolean;
+}
+export declare class TabsTester {
+    private user;
+    private _interactionType;
+    private _tablist;
+    private _direction;
+    constructor(opts: TabsTesterOpts);
+    /**
+     * Set the interaction type used by the tabs tester.
+     */
+    setInteractionType(type: UserOpts['interactionType']): void;
+    /**
+     * Returns a tab matching the specified index or text content.
+     */
+    findTab(opts: {
+        indexOrText: number | string;
+    }): HTMLElement;
+    private keyboardNavigateToTab;
+    /**
+     * Triggers the specified tab. Defaults to using the interaction type set on the tabs tester.
+     */
+    triggerTab(opts: TriggerTabOptions): Promise<void>;
+    /**
+     * Returns the tablist.
+     */
+    getTablist(): HTMLElement;
+    /**
+     * Returns the tabpanels.
+     */
+    getTabpanels(): HTMLElement[];
+    /**
+     * Returns the tabs in the tablist.
+     */
+    getTabs(): HTMLElement[];
+    /**
+     * Returns the currently selected tab in the tablist if any.
+     */
+    getSelectedTab(): HTMLElement | null;
+    /**
+     * Returns the currently active tabpanel if any.
+     */
+    getActiveTabpanel(): HTMLElement | null;
+}
+export {};

package/dist/types/src/testSetup.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Enables reading pageX/pageY from fireEvent.mouse*(..., {pageX: ..., pageY: ...}).
+ */
+export declare function installMouseEvent(): void;
+export declare function definePointerEvent(): void;
+export declare function installPointerEvent(): void;

package/dist/types/src/tree.d.ts

@@ -0,0 +1,62 @@
+import { BaseGridRowInteractionOpts, GridRowActionOpts, ToggleGridRowOpts, TreeTesterOpts, UserOpts } from './types';
+interface TreeToggleExpansionOpts extends BaseGridRowInteractionOpts {
+}
+interface TreeToggleRowOpts extends ToggleGridRowOpts {
+}
+interface TreeRowActionOpts extends GridRowActionOpts {
+}
+export declare class TreeTester {
+    private user;
+    private _interactionType;
+    private _advanceTimer;
+    private _direction;
+    private _tree;
+    constructor(opts: TreeTesterOpts);
+    /**
+     * Set the interaction type used by the tree tester.
+     */
+    setInteractionType(type: UserOpts['interactionType']): void;
+    /**
+     * Returns a row matching the specified index or text content.
+     */
+    findRow(opts: {
+        indexOrText: number | string;
+    }): HTMLElement;
+    private keyboardNavigateToRow;
+    /**
+     * Toggles the selection for the specified tree row. Defaults to using the interaction type set on
+     * the tree tester. Note that this will endevor to always add/remove JUST the provided row to the
+     * set of selected rows.
+     */
+    toggleRowSelection(opts: TreeToggleRowOpts): Promise<void>;
+    /**
+     * Toggles the expansion for the specified tree row. Defaults to using the interaction type set on
+     * the tree tester.
+     */
+    toggleRowExpansion(opts: TreeToggleExpansionOpts): Promise<void>;
+    /**
+     * Triggers the action for the specified tree row. Defaults to using the interaction type set on
+     * the tree tester.
+     */
+    triggerRowAction(opts: TreeRowActionOpts): Promise<void>;
+    /**
+     * Returns the tree.
+     */
+    getTree(): HTMLElement;
+    /**
+     * Returns the tree's rows if any.
+     */
+    getRows(): HTMLElement[];
+    /**
+     * Returns the tree's selected rows if any.
+     */
+    getSelectedRows(): HTMLElement[];
+    /**
+     * Returns the tree's cells if any. Can be filtered against a specific row if provided via
+     * `element`.
+     */
+    getCells(opts?: {
+        element?: HTMLElement;
+    }): HTMLElement[];
+}
+export {};

package/dist/types/src/types.d.ts

@@ -0,0 +1,143 @@
+export type Orientation = 'horizontal' | 'vertical';
+export type Direction = 'ltr' | 'rtl';
+export interface UserOpts {
+    /**
+     * The interaction type (mouse, touch, keyboard) that the test util user will use when interacting
+     * with a component. This can be overridden at the aria pattern tester level if needed.
+     *
+     * @default mouse
+     */
+    interactionType?: 'mouse' | 'touch' | 'keyboard';
+    /**
+     * A function used by the test utils to advance timers during interactions. Required for certain
+     * aria patterns (e.g. table). This can be overridden at the aria pattern tester level if needed.
+     */
+    advanceTimer?: (time: number) => unknown | Promise<unknown>;
+}
+export interface BaseTesterOpts extends UserOpts {
+    /** @private */
+    user?: any;
+    /** The base element for the given tester (e.g. the table, menu trigger button, etc). */
+    root: HTMLElement;
+    /**
+     * The horizontal layout direction, typically affected by locale.
+     *
+     * @default 'ltr'
+     */
+    direction?: Direction;
+}
+export interface CheckboxGroupTesterOpts extends BaseTesterOpts {
+}
+export interface ComboBoxTesterOpts extends BaseTesterOpts {
+    /**
+     * The base element for the combobox. If provided the wrapping element around the target combobox
+     * (as is the the case with a ref provided to RSP ComboBox), will automatically search for the
+     * combobox element within.
+     */
+    root: HTMLElement;
+    /**
+     * The node of the combobox trigger button if any. If not provided, we will try to automatically
+     * use any button within the `root` provided or that the `root` serves as the trigger.
+     */
+    trigger?: HTMLElement;
+}
+export interface DialogTesterOpts extends BaseTesterOpts {
+    /**
+     * The trigger element for the dialog.
+     */
+    root: HTMLElement;
+    /**
+     * The overlay type of the dialog. Used to inform the tester how to find the dialog.
+     */
+    overlayType?: 'modal' | 'popover';
+}
+export interface GridListTesterOpts extends BaseTesterOpts {
+    /**
+     * The layout of the gridlist.
+     *
+     * @default 'stack'
+     */
+    layout?: 'stack' | 'grid';
+}
+export interface ListBoxTesterOpts extends BaseTesterOpts {
+    /**
+     * The layout of the listbox.
+     *
+     * @default 'stack'
+     */
+    layout?: 'stack' | 'grid';
+}
+export interface MenuTesterOpts extends BaseTesterOpts {
+    /**
+     * The trigger element for the menu.
+     */
+    root: HTMLElement;
+    /**
+     * Whether the current menu is a submenu.
+     */
+    isSubmenu?: boolean;
+    /**
+     * The root menu of the menu tree. Only available if the menu is a submenu.
+     */
+    rootMenu?: HTMLElement;
+}
+export interface RadioGroupTesterOpts extends BaseTesterOpts {
+}
+export interface SelectTesterOpts extends BaseTesterOpts {
+    /**
+     * The trigger element for the select. If provided the wrapping element around the target select
+     * (as is the case with a ref provided to RSP Select), will automatically search for the select's
+     * trigger element within.
+     */
+    root: HTMLElement;
+}
+export interface TableTesterOpts extends BaseTesterOpts {
+}
+export interface TabsTesterOpts extends BaseTesterOpts {
+}
+export interface TreeTesterOpts extends BaseTesterOpts {
+}
+export interface BaseGridRowInteractionOpts {
+    /**
+     * The index, text, or node of the row to target.
+     */
+    row: number | string | HTMLElement;
+    /**
+     * What interaction type to use when interacting with the row. Defaults to the interaction type
+     * set on the tester.
+     */
+    interactionType?: UserOpts['interactionType'];
+}
+export interface ToggleGridRowOpts extends BaseGridRowInteractionOpts {
+    /**
+     * Whether the row needs to be long pressed to be selected. Depends on the components
+     * implementation.
+     */
+    needsLongPress?: boolean;
+    /**
+     * Whether the checkbox should be used to select the row. If false, will attempt to select the row
+     * via press.
+     *
+     * @default 'true'
+     */
+    checkboxSelection?: boolean;
+    /**
+     * Whether the grid has a selectionBehavior of "toggle" or "replace" (aka highlight selection).
+     * This affects the user operations required to toggle row selection by adding modifier keys
+     * during user actions, useful when performing multi-row selection in a "selectionBehavior:
+     * 'replace'" grid. If you would like to still simulate user actions (aka press) without these
+     * modifiers keys for a "selectionBehavior: replace" grid, simply omit this option. See the
+     * "Selection Behavior" section of the appropriate React Aria Component docs for more information
+     * (e.g. https://react-aria.adobe.com/Tree#selection-and-actions).
+     *
+     * @default 'toggle'
+     */
+    selectionBehavior?: 'toggle' | 'replace';
+}
+export interface GridRowActionOpts extends BaseGridRowInteractionOpts {
+    /**
+     * Whether or not the row needs a double click to trigger the row action. Depends on the
+     * components implementation.
+     */
+    needsDoubleClick?: boolean;
+}

package/dist/types/src/user.d.ts

@@ -0,0 +1,49 @@
+import { CheckboxGroupTester } from './checkboxgroup';
+import { CheckboxGroupTesterOpts, ComboBoxTesterOpts, DialogTesterOpts, GridListTesterOpts, ListBoxTesterOpts, MenuTesterOpts, RadioGroupTesterOpts, SelectTesterOpts, TableTesterOpts, TabsTesterOpts, TreeTesterOpts, UserOpts } from './types';
+import { ComboBoxTester } from './combobox';
+import { DialogTester } from './dialog';
+import { GridListTester } from './gridlist';
+import { ListBoxTester } from './listbox';
+import { MenuTester } from './menu';
+import { RadioGroupTester } from './radiogroup';
+import { SelectTester } from './select';
+import { TableTester } from './table';
+import { TabsTester } from './tabs';
+import { TreeTester } from './tree';
+declare let keyToUtil: {
+    CheckboxGroup: typeof CheckboxGroupTester;
+    ComboBox: typeof ComboBoxTester;
+    Dialog: typeof DialogTester;
+    GridList: typeof GridListTester;
+    ListBox: typeof ListBoxTester;
+    Menu: typeof MenuTester;
+    RadioGroup: typeof RadioGroupTester;
+    Select: typeof SelectTester;
+    Table: typeof TableTester;
+    Tabs: typeof TabsTester;
+    Tree: typeof TreeTester;
+};
+export type PatternNames = keyof typeof keyToUtil;
+type Tester<T> = T extends 'CheckboxGroup' ? CheckboxGroupTester : T extends 'ComboBox' ? ComboBoxTester : T extends 'Dialog' ? DialogTester : T extends 'GridList' ? GridListTester : T extends 'ListBox' ? ListBoxTester : T extends 'Menu' ? MenuTester : T extends 'RadioGroup' ? RadioGroupTester : T extends 'Select' ? SelectTester : T extends 'Table' ? TableTester : T extends 'Tabs' ? TabsTester : T extends 'Tree' ? TreeTester : never;
+type TesterOpts<T> = T extends 'CheckboxGroup' ? CheckboxGroupTesterOpts : T extends 'ComboBox' ? ComboBoxTesterOpts : T extends 'Dialog' ? DialogTesterOpts : T extends 'GridList' ? GridListTesterOpts : T extends 'ListBox' ? ListBoxTesterOpts : T extends 'Menu' ? MenuTesterOpts : T extends 'RadioGroup' ? RadioGroupTesterOpts : T extends 'Select' ? SelectTesterOpts : T extends 'Table' ? TableTesterOpts : T extends 'Tabs' ? TabsTesterOpts : T extends 'Tree' ? TreeTesterOpts : never;
+export declare class User {
+    private user;
+    /**
+     * The interaction type (mouse, touch, keyboard) that the test util user will use when interacting
+     * with a component. This can be overridden at the aria pattern util level if needed.
+     *
+     * @default mouse
+     */
+    interactionType: UserOpts['interactionType'];
+    /**
+     * A function used by the test utils to advance timers during interactions. Required for certain
+     * aria patterns (e.g. table).
+     */
+    advanceTimer: UserOpts['advanceTimer'];
+    constructor(opts?: UserOpts);
+    /**
+     * Creates an aria pattern tester, inheriting the options provided to the original user.
+     */
+    createTester<T extends PatternNames>(patternName: T, opts: TesterOpts<T>): Tester<T>;
+}
+export {};

package/dist/types/src/userEventMaps.d.ts

@@ -0,0 +1,2 @@
+import { pointerKey } from '@testing-library/user-event';
+export declare let pointerMap: pointerKey[];

package/dist/types/src/utils.d.ts

@@ -0,0 +1,29 @@
+import { UserOpts } from './types';
+export declare const DEFAULT_LONG_PRESS_TIME = 500;
+export declare function getAltKey(): 'Alt' | 'ControlLeft';
+export declare function getMetaKey(): 'MetaLeft' | 'ControlLeft';
+export declare function formatTargetNode(value: number | string | HTMLElement): string;
+/**
+ * Simulates a "long press" event on a element.
+ *
+ * @param opts - Options for the long press.
+ * @param opts.element - Element to long press.
+ * @param opts.advanceTimer - Function that when called advances the timers in your test suite by a
+ *   specific amount of time(ms).
+ * @param opts.pointeropts - Options to pass to the simulated event. Defaults to mouse. See
+ *   https://testing-library.com/docs/dom-testing-library/api-events/#fireevent for more info.
+ */
+export declare function triggerLongPress(opts: {
+    element: HTMLElement;
+    advanceTimer: (time: number) => unknown | Promise<unknown>;
+    pointerOpts?: Record<string, any>;
+}): Promise<void>;
+export declare 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>;

package/package.json

@@ -1,37 +1,45 @@
 {
   "name": "@react-aria/test-utils",
-  "version": "1.0.0-nightly.5042+68403fe55",
+  "version": "1.0.0-rc.0",
   "description": "Testing utils for react-aria patterns",
   "license": "Apache-2.0",
-  "main": "dist/main.js",
-  "module": "dist/module.js",
-  "exports": {
-    "types": "./dist/types.d.ts",
-    "import": "./dist/import.mjs",
-    "require": "./dist/main.js"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adobe/react-spectrum"
   },
-  "types": "dist/types.d.ts",
   "source": "src/index.ts",
   "files": [
     "dist",
     "src"
   ],
   "sideEffects": false,
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/adobe/react-spectrum"
+  "main": "dist/main.js",
+  "module": "dist/module.js",
+  "types": "./dist/types/src/index.d.ts",
+  "exports": {
+    "source": "./src/index.ts",
+    "types": "./dist/types/src/index.d.ts",
+    "import": "./dist/import.mjs",
+    "require": "./dist/main.js"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
     "@swc/helpers": "^0.5.0"
   },
+  "devDependencies": {
+    "react": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1",
+    "react-dom": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1"
+  },
   "peerDependencies": {
-    "@testing-library/react": "^15.0.7",
-    "@testing-library/user-event": "^13.0.0 || ^14.0.0",
-    "jest": "^29.5.0",
-    "react": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0"
+    "@testing-library/dom": "^10.0.0",
+    "@testing-library/user-event": "^14.0.0",
+    "react": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1",
+    "react-dom": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1"
   },
-  "publishConfig": {
-    "access": "public"
+  "targets": {
+    "types": false
   },
-  "gitHead": "68403fe55489dce3de1b3094c957d598ad719861"
+  "gitHead": "3577a20859b9585a000010c720f6ee39c1c588cc"
 }

package/src/act.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2026 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 * as React from 'react';
+import * as ReactDOMTestUtils from 'react-dom/test-utils';
+
+let actImpl: typeof ReactDOMTestUtils.act;
+if (typeof React.act === 'function') {
+  actImpl = React.act;
+} else {
+  actImpl = ReactDOMTestUtils.act;
+}
+
+export const act: typeof actImpl = fn => {
+  // only wrap in act if in test environment, breaks vite browser test if test utils are used otherwise
+  if (
+    // @ts-ignore
+    typeof IS_REACT_ACT_ENVIRONMENT === 'boolean'
+      ? // @ts-ignore
+        IS_REACT_ACT_ENVIRONMENT
+      : typeof jest !== 'undefined'
+  ) {
+    return actImpl(fn);
+  }
+  return fn();
+};