@react-aria/test-utils 1.0.0-beta.1 → 1.0.0-beta.3

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

@@ -0,0 +1,51 @@
+import { GridListTesterOpts, GridRowActionOpts, ToggleGridRowOpts, UserOpts } from './types';
+interface GridListToggleRowOpts extends ToggleGridRowOpts {
+}
+interface GridListRowActionOpts extends GridRowActionOpts {
+}
+export declare class GridListTester {
+    private user;
+    private _interactionType;
+    private _advanceTimer;
+    private _gridlist;
+    constructor(opts: GridListTesterOpts);
+    /**
+     * Set the interaction type used by the gridlist tester.
+     */
+    setInteractionType(type: UserOpts['interactionType']): void;
+    /**
+     * Returns a row matching the specified index or text content.
+     */
+    findRow(opts: {
+        rowIndexOrText: number | string;
+    }): HTMLElement;
+    private keyboardNavigateToRow;
+    /**
+     * 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.
+     */
+    toggleRowSelection(opts: GridListToggleRowOpts): Promise<void>;
+    /**
+     * Triggers the action for the specified gridlist row. Defaults to using the interaction type set on the gridlist tester.
+     */
+    triggerRowAction(opts: GridListRowActionOpts): Promise<void>;
+    /**
+     * Returns the gridlist.
+     */
+    get gridlist(): HTMLElement;
+    /**
+     * Returns the gridlist's rows if any.
+     */
+    get rows(): HTMLElement[];
+    /**
+     * Returns the gridlist's selected rows if any.
+     */
+    get selectedRows(): HTMLElement[];
+    /**
+     * Returns the gridlist's cells if any. Can be filtered against a specific row if provided via `element`.
+     */
+    cells(opts?: {
+        element?: HTMLElement;
+    }): HTMLElement[];
+}
+export {};

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

@@ -0,0 +1,16 @@
+export { triggerLongPress } from './events';
+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/dist/types/src/listbox.d.ts

@@ -0,0 +1,80 @@
+import { ListBoxTesterOpts, UserOpts } from './types';
+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 declare class ListBoxTester {
+    private user;
+    private _interactionType;
+    private _advanceTimer;
+    private _listbox;
+    constructor(opts: ListBoxTesterOpts);
+    /**
+     * Set the interaction type used by the listbox tester.
+     */
+    setInteractionType(type: UserOpts['interactionType']): void;
+    /**
+     * Returns a option matching the specified index or text content.
+     */
+    findOption(opts: {
+        optionIndexOrText: number | string;
+    }): HTMLElement;
+    private keyboardNavigateToOption;
+    /**
+     * Toggles the selection for the specified listbox option. Defaults to using the interaction type set on the listbox tester.
+     */
+    toggleOptionSelection(opts: ListBoxToggleOptionOpts): Promise<void>;
+    /**
+     * Triggers the action for the specified listbox option. Defaults to using the interaction type set on the listbox tester.
+     */
+    triggerOptionAction(opts: ListBoxOptionActionOpts): Promise<void>;
+    /**
+     * Returns the listbox.
+     */
+    get listbox(): HTMLElement;
+    /**
+     * Returns the listbox options. Can be filtered to a subsection of the listbox if provided via `element`.
+     */
+    options(opts?: {
+        element?: HTMLElement;
+    }): HTMLElement[];
+    /**
+     * Returns the listbox's selected options if any.
+     */
+    get selectedOptions(): HTMLElement[];
+    /**
+     * Returns the listbox's sections if any.
+     */
+    get sections(): HTMLElement[];
+}
+export {};

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

@@ -0,0 +1,102 @@
+import { MenuTesterOpts, UserOpts } from './types';
+interface MenuOpenOpts {
+    /**
+     * Whether the menu needs to be long pressed to open.
+     */
+    needsLongPress?: boolean;
+    /**
+     * What interaction type to use when opening the menu. Defaults to the interaction type set on the tester.
+     */
+    interactionType?: UserOpts['interactionType'];
+    /**
+     * Whether to open the menu via ArrowUp or ArrowDown if in keyboard modality.
+     */
+    direction?: 'up' | 'down';
+}
+interface MenuSelectOpts extends MenuOpenOpts {
+    /**
+     * The index, text, or node of the option to select. Option nodes can be sourced via `options()`.
+     */
+    option: number | string | HTMLElement;
+    /**
+     * The menu's selection mode. Will affect whether or not the menu is expected to be closed upon option selection.
+     * @default 'single'
+     */
+    menuSelectionMode?: 'single' | 'multiple';
+    /**
+     * Whether or not the menu closes on select. Depends on menu implementation and configuration.
+     * @default true
+     */
+    closesOnSelect?: boolean;
+    /**
+     * Whether the option should be triggered by Space or Enter in keyboard modality.
+     * @default 'Enter'
+     */
+    keyboardActivation?: 'Space' | 'Enter';
+}
+interface MenuOpenSubmenuOpts extends MenuOpenOpts {
+    /**
+     * The text or node of the submenu trigger to open. Available submenu trigger nodes can be sourced via `submenuTriggers`.
+     */
+    submenuTrigger: string | HTMLElement;
+}
+export declare class MenuTester {
+    private user;
+    private _interactionType;
+    private _advanceTimer;
+    private _trigger;
+    private _isSubmenu;
+    private _rootMenu;
+    constructor(opts: MenuTesterOpts);
+    /**
+     * Set the interaction type used by the menu tester.
+     */
+    setInteractionType(type: UserOpts['interactionType']): void;
+    /**
+     * Opens the menu. Defaults to using the interaction type set on the menu tester.
+     */
+    open(opts?: MenuOpenOpts): Promise<void>;
+    /**
+     * Returns a option matching the specified index or text content.
+     */
+    findOption(opts: {
+        optionIndexOrText: number | string;
+    }): HTMLElement;
+    /**
+     * Selects the desired menu option. Defaults to using the interaction type set on the menu tester. If necessary, will open the menu dropdown beforehand.
+     * The desired option can be targeted via the option's node, the option's text, or the option's index.
+     */
+    selectOption(opts: MenuSelectOpts): Promise<void>;
+    /**
+     * Opens the submenu. Defaults to using the interaction type set on the menu tester. The submenu trigger can be targeted via the trigger's node or the trigger's text.
+     */
+    openSubmenu(opts: MenuOpenSubmenuOpts): Promise<MenuTester | null>;
+    private keyboardNavigateToOption;
+    /**
+     * Closes the menu.
+     */
+    close(): Promise<void>;
+    /**
+     * Returns the menu's trigger.
+     */
+    get trigger(): HTMLElement;
+    /**
+     * Returns the menu if present.
+     */
+    get menu(): HTMLElement | null;
+    /**
+     * Returns the menu's sections if any.
+     */
+    get sections(): HTMLElement[];
+    /**
+     * Returns the menu's options if present. Can be filtered to a subsection of the menu if provided via `element`.
+     */
+    options(opts?: {
+        element?: HTMLElement;
+    }): HTMLElement[];
+    /**
+     * Returns the menu's submenu triggers if any.
+     */
+    get submenuTriggers(): HTMLElement[];
+}
+export {};

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

@@ -0,0 +1,46 @@
+import { RadioGroupTesterOpts, UserOpts } from './types';
+interface TriggerRadioOptions {
+    /**
+     * What interaction type to use when triggering a radio. Defaults to the interaction type set on the tester.
+     */
+    interactionType?: UserOpts['interactionType'];
+    /**
+     * The index, text, or node of the radio to toggle selection for.
+     */
+    radio: number | string | HTMLElement;
+}
+export declare class RadioGroupTester {
+    private user;
+    private _interactionType;
+    private _radiogroup;
+    private _direction;
+    constructor(opts: RadioGroupTesterOpts);
+    /**
+     * Set the interaction type used by the radio tester.
+     */
+    setInteractionType(type: UserOpts['interactionType']): void;
+    /**
+     * Returns a radio matching the specified index or text content.
+     */
+    findRadio(opts: {
+        radioIndexOrText: number | string;
+    }): HTMLElement;
+    private keyboardNavigateToRadio;
+    /**
+     * Triggers the specified radio. Defaults to using the interaction type set on the radio tester.
+     */
+    triggerRadio(opts: TriggerRadioOptions): Promise<void>;
+    /**
+     * Returns the radiogroup.
+     */
+    get radiogroup(): HTMLElement;
+    /**
+     * Returns the radios.
+     */
+    get radios(): HTMLElement[];
+    /**
+     * Returns the currently selected radio in the radiogroup if any.
+     */
+    get selectedRadio(): HTMLElement | null;
+}
+export {};

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

@@ -0,0 +1,67 @@
+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 `options()`.
+     */
+    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: {
+        optionIndexOrText: number | string;
+    }): HTMLElement;
+    private keyboardNavigateToOption;
+    /**
+     * Selects the desired select option. 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.
+     */
+    selectOption(opts: SelectTriggerOptionOpts): Promise<void>;
+    /**
+     * Returns the select's options if present. Can be filtered to a subsection of the listbox if provided via `element`.
+     */
+    options(opts?: {
+        element?: HTMLElement;
+    }): HTMLElement[];
+    /**
+     * Returns the select's trigger.
+     */
+    get trigger(): HTMLElement;
+    /**
+     * Returns the select's listbox if present.
+     */
+    get listbox(): HTMLElement | null;
+    /**
+     * Returns the select's sections if present.
+     */
+    get sections(): HTMLElement[];
+}
+export {};

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

@@ -0,0 +1,104 @@
+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 _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: {
+        rowIndexOrText: number | string;
+    }): HTMLElement;
+    /**
+     * Returns a cell matching the specified text content.
+     */
+    findCell(opts: {
+        text: string;
+    }): HTMLElement;
+    /**
+     * Returns the table.
+     */
+    get table(): HTMLElement;
+    /**
+     * Returns the row groups within the table.
+     */
+    get rowGroups(): HTMLElement[];
+    /**
+     * Returns the columns within the table.
+     */
+    get columns(): HTMLElement[];
+    /**
+     * Returns the rows within the table if any.
+     */
+    get rows(): HTMLElement[];
+    /**
+     * Returns the currently selected rows within the table if any.
+     */
+    get selectedRows(): HTMLElement[];
+    /**
+     * Returns the row headers within the table if any.
+     */
+    get rowHeaders(): HTMLElement[];
+    /**
+     * Returns the cells within the table if any. Can be filtered against a specific row if provided via `element`.
+     */
+    cells(opts?: {
+        element?: HTMLElement;
+    }): HTMLElement[];
+}
+export {};

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

@@ -0,0 +1,58 @@
+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: {
+        tabIndexOrText: 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.
+     */
+    get tablist(): HTMLElement;
+    /**
+     * Returns the tabpanels.
+     */
+    get tabpanels(): HTMLElement[];
+    /**
+     * Returns the tabs in the tablist.
+     */
+    get tabs(): HTMLElement[];
+    /**
+     * Returns the currently selected tab in the tablist if any.
+     */
+    get selectedTab(): HTMLElement | null;
+    /**
+     * Returns the currently active tabpanel if any.
+     */
+    get activeTabpanel(): 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,57 @@
+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 _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: {
+        rowIndexOrText: 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.
+     */
+    get tree(): HTMLElement;
+    /**
+     * Returns the tree's rows if any.
+     */
+    get rows(): HTMLElement[];
+    /**
+     * Returns the tree's selected rows if any.
+     */
+    get selectedRows(): HTMLElement[];
+    /**
+     * Returns the tree's cells if any. Can be filtered against a specific row if provided via `element`.
+     */
+    cells(opts?: {
+        element?: HTMLElement;
+    }): HTMLElement[];
+}
+export {};