import { t as AriaRole } from "./__aria-role-Cp57GdYZ.js"; import * as DOMTestingLibrary from "@testing-library/dom"; import { ByRoleMatcher, ByRoleOptions, EventType, Matcher, SelectorMatcherOptions, waitForOptions } from "@testing-library/dom"; //#region src/__utils.d.ts type DirtiableElement = Element & { dirty?: boolean; }; //#endregion //#region src/blur.d.ts /** * Removes focus from an element, simulating a real user moving focus away from * it. When no element is passed, the currently focused element * (`document.activeElement`) is used. If typing changed the element's value * since it gained focus, a `change` event is dispatched before it's blurred. * @example * ```ts * await type("hello", q.textbox()); * // Dispatches the pending `change` event, then blurs the textbox. * await blur(); * ``` */ declare function blur(element?: DirtiableElement | null): Promise; //#endregion //#region src/click.d.ts /** * Clicks on an element, simulating the sequence of events a real mouse click * produces — hovering the target, then `pointerdown`, `mousedown`, `focus`, * `pointerup`, `mouseup`, and `click`. * * Hidden and disabled elements are handled the same way a browser would, and * clicks on labels, `option` elements, and form controls behave like native * interactions. Pass `options` to set event properties such as modifier keys * (e.g. `{ shiftKey: true }`). * @example * ```ts * await click(q.button("Submit")); * // With a modifier key held down: * await click(q.option("Item"), { shiftKey: true }); * ``` */ declare function click(element: Element | null, options?: PointerEventInit, tap?: boolean): Promise; //#endregion //#region src/dispatch.d.ts type Target = Document | Window | Node | Element | null; type EventFunction = (element: Target, options?: object) => Promise; type EventsObject = { [K in EventType]: EventFunction; }; declare function baseDispatch(element: Target, event: Event): Promise; /** * Creates and fires a DOM event on an element, then waits for the resulting * microtasks to flush. Call `dispatch.(element, options)` to build and * fire a specific event (e.g. `dispatch.keyDown`, `dispatch.click`, * `dispatch.input`), or call `dispatch(element, event)` directly with an `Event` * instance. * * Unlike higher-level helpers such as `click` and `type`, this fires a single * event without simulating the surrounding interaction sequence. Pointer and * mouse events fired on an element with `pointer-events: none` are re-dispatched * on the nearest ancestor that has pointer events enabled, matching how browsers * route those events. * @returns A promise that resolves to `false` when the event's default action was * prevented with `event.preventDefault()`, and `true` otherwise. * @example * ```ts * await dispatch.keyDown(q.textbox(), { key: "Enter" }); * await dispatch.click(q.button()); * // Fire a custom event instance directly: * await dispatch(q.textbox(), new Event("selectstart", { bubbles: true })); * ``` */ declare const dispatch: typeof baseDispatch & EventsObject; //#endregion //#region src/focus.d.ts /** * Moves focus to an element, simulating a real user focusing it. Elements that * aren't focusable are ignored, and focusing the already focused element is a * no-op. If typing changed another element's value since it gained focus, its * pending `change` event is dispatched before focus moves. * @example * ```ts * await focus(q.textbox()); * expect(q.textbox()).toHaveFocus(); * ``` */ declare function focus(element: Element | null): Promise; //#endregion //#region src/hover.d.ts /** * Moves the pointer over an element, simulating a real user hovering it. Fires * the relevant `pointer`/`mouse` enter, over, and move events, and dispatches the * matching leave events on the previously hovered element. * * Hidden elements and elements with `pointer-events: none` are handled the way a * browser would. Pass `options` to set event properties such as modifier keys. * @example * ```ts * await hover(q.button("More options")); * expect(q.menu()).toBeVisible(); * ``` */ declare function hover(element: Element | null, options?: PointerEventInit): Promise; //#endregion //#region src/mouse-down.d.ts /** * Presses the primary pointer button down on an element, firing `pointerdown` and * `mousedown` and moving focus the way a browser would. Disabled elements still * receive `pointerdown` but not `mousedown`, and focus falls back to the closest * focusable ancestor when the target itself isn't focusable. * * This is one step of a full `click`; use it directly to test press-and-hold * behavior. Pass `options` to set event properties such as modifier keys. * @example * ```ts * await mouseDown(q.button("Resize")); * // ...assert the press state, then release: * await mouseUp(q.button("Resize")); * ``` */ declare function mouseDown(element: Element | null, options?: PointerEventInit): Promise; //#endregion //#region src/mouse-up.d.ts /** * Releases the primary pointer button on an element, firing `pointerup` and * `mouseup`. Disabled elements still receive `pointerup` but not `mouseup`. * * This is the counterpart to `mouseDown` and one step of a full `click`. Pass * `options` to set event properties such as modifier keys. * @example * ```ts * await mouseDown(q.button("Resize")); * await mouseUp(q.button("Resize")); * ``` */ declare function mouseUp(element: Element | null, options?: PointerEventInit): Promise; //#endregion //#region src/press.d.ts /** * Presses a key on an element, simulating a real user keyboard interaction. Fires * `keydown` and `keyup` and applies the browser's default behavior for that key — * moving focus with `Tab`, activating buttons and submitting forms with `Enter`, * clicking buttons, checkboxes, and radios with `Space`, moving the caret with the * arrow and `Home`/`End` keys, and typing printable characters into text fields. * * When no element is passed, the currently focused element is used. Shortcuts such * as `press.Enter()` and `press.Tab()` are provided for common keys, and * `press.ShiftTab()` moves focus backwards. * * Use `press.down` and `press.up` to fire only the keydown or keyup * half of a press. Each defaults to the currently focused element, so a key * released after focus moved away — for example, an element that disables itself * on keydown — lands where a real browser would deliver it. * @example * ```ts * await press.Tab(); * await press.Enter(); * // `press.Enter(element)` is shorthand for `press("Enter", element)`: * await press.Enter(q.button("Submit")); * // Split a press so the keyup lands on whatever is focused at release time: * await press.down.Space(); * await press.up.Space(); * ``` */ declare function press(key: string, element?: Element | null, options?: KeyboardEventInit): Promise; declare namespace press { var Escape: (element?: Element | null, options?: KeyboardEventInit) => Promise; var Backspace: (element?: Element | null, options?: KeyboardEventInit) => Promise; var Delete: (element?: Element | null, options?: KeyboardEventInit) => Promise; var Tab: (element?: Element | null, options?: KeyboardEventInit) => Promise; var ShiftTab: (element?: Element | null, options?: KeyboardEventInit) => Promise; var Enter: (element?: Element | null, options?: KeyboardEventInit) => Promise; var Space: (element?: Element | null, options?: KeyboardEventInit) => Promise; var ArrowUp: (element?: Element | null, options?: KeyboardEventInit) => Promise; var ArrowRight: (element?: Element | null, options?: KeyboardEventInit) => Promise; var ArrowDown: (element?: Element | null, options?: KeyboardEventInit) => Promise; var ArrowLeft: (element?: Element | null, options?: KeyboardEventInit) => Promise; var End: (element?: Element | null, options?: KeyboardEventInit) => Promise; var Home: (element?: Element | null, options?: KeyboardEventInit) => Promise; var PageUp: (element?: Element | null, options?: KeyboardEventInit) => Promise; var PageDown: (element?: Element | null, options?: KeyboardEventInit) => Promise; var down: typeof pressDown & { Escape: PressShortcut; Backspace: PressShortcut; Delete: PressShortcut; Tab: PressShortcut; ShiftTab: PressShortcut; Enter: PressShortcut; Space: PressShortcut; ArrowUp: PressShortcut; ArrowRight: PressShortcut; ArrowDown: PressShortcut; ArrowLeft: PressShortcut; End: PressShortcut; Home: PressShortcut; PageUp: PressShortcut; PageDown: PressShortcut; }; var up: typeof pressUp & { Escape: PressShortcut; Backspace: PressShortcut; Delete: PressShortcut; Tab: PressShortcut; ShiftTab: PressShortcut; Enter: PressShortcut; Space: PressShortcut; ArrowUp: PressShortcut; ArrowRight: PressShortcut; ArrowDown: PressShortcut; ArrowLeft: PressShortcut; End: PressShortcut; Home: PressShortcut; PageUp: PressShortcut; PageDown: PressShortcut; }; } /** * Fires only the `keydown` half of a key press on an element, simulating a real * user pressing a key down without releasing it yet. Focuses the element first * (since a key press always lands on the focused element) and applies the * browser's default keydown behavior for the key, such as moving focus with `Tab` * or the caret with the arrow keys. As a low-level half of a press, it fires a * raw `keydown` and does not type printable characters into text fields the way * the combined `press` does. * * When no element is passed, the currently focused element is used. Pair it with * `press.up` to drive a press in two steps, which matters when the keydown * moves focus — for example, an element that disables itself on keydown blurs to * the body, so the later keyup must land there, not on the original element. * Shortcuts such as `press.down.Space()` are provided for common keys. * @example * ```ts * await press.down.Space(q.button("Mute")); * await press.up.Space(); * ``` */ declare function pressDown(key: string, element?: Element | null, options?: KeyboardEventInit): Promise; /** * Fires only the `keyup` half of a key press, simulating a real user releasing a * key. Unlike `press.down`, it doesn't move focus: the keyup lands on the * passed element or, when none is given, on the currently focused element — which * is where a real browser delivers it after the matching `press.down`. * Applies the browser's default keyup behavior for the key, such as clicking * buttons, checkboxes, and radios with `Space`. Because it runs independently of * the matching `press.down`, it can't suppress that default based on the keydown's * default having been prevented the way the combined `press` does — though it * still respects the keyup event's own cancellation and the Meta key. Use the * combined `press` when that distinction matters. * * Shortcuts such as `press.up.Space()` are provided for common keys. * @example * ```ts * await press.down.Space(); * // The element disabled itself on keydown and blurred to the body, so the * // keyup correctly lands on the body instead of the now-disabled element. * await press.up.Space(); * ``` */ declare function pressUp(key: string, element?: Element | null, options?: KeyboardEventInit): Promise; type PressShortcut = (element?: Element | null, options?: KeyboardEventInit) => Promise; //#endregion //#region src/query.d.ts type Query = ReturnType; type TextQuery = ReturnType; type RoleQueries = Record; type AnyQuery = (...args: any[]) => any; type LazyQuery = (...args: Parameters) => () => ReturnType; type TextKind = "array" | "nullable" | "value" | "waitArray" | "waitValue"; type TextResult = { array: T[]; nullable: T | null; value: T; waitArray: Promise; waitValue: Promise; }[Kind]; interface ElementQueries { queryByRole: RoleNullableMethod; queryAllByRole: RoleArrayMethod; findByRole: RoleWaitValueMethod; findAllByRole: RoleWaitArrayMethod; getByRole: RoleValueMethod; getAllByRole: RoleArrayMethod; queryByText: TextMethod<"nullable", TextQueryArgs>; queryAllByText: TextMethod<"array", TextQueryArgs>; findByText: TextMethod<"waitValue", TextWaitQueryArgs>; findAllByText: TextMethod<"waitArray", TextWaitQueryArgs>; getByText: TextMethod<"value", TextQueryArgs>; getAllByText: TextMethod<"array", TextQueryArgs>; queryByLabelText: TextMethod<"nullable", TextQueryArgs>; queryAllByLabelText: TextMethod<"array", TextQueryArgs>; findByLabelText: TextMethod<"waitValue", TextWaitQueryArgs>; findAllByLabelText: TextMethod<"waitArray", TextWaitQueryArgs>; getByLabelText: TextMethod<"value", TextQueryArgs>; getAllByLabelText: TextMethod<"array", TextQueryArgs>; } interface RoleNullableMethod { (role: ByRoleMatcher, options?: ByRoleOptions): HTMLElement | null; } interface RoleArrayMethod { (role: ByRoleMatcher, options?: ByRoleOptions): HTMLElement[]; } interface RoleValueMethod { (role: ByRoleMatcher, options?: ByRoleOptions): HTMLElement; } interface RoleWaitArrayMethod { (role: ByRoleMatcher, options?: ByRoleOptions, waitForElementOptions?: waitForOptions): Promise; } interface RoleWaitValueMethod { (role: ByRoleMatcher, options?: ByRoleOptions, waitForElementOptions?: waitForOptions): Promise; } interface TextMethod { (...args: Args): TextResult; } interface TextVariant extends TextMethod { lazy(...args: Args): () => TextResult; } interface TextQueryParams { all: TextMethod<"array", TextQueryArgs>; wait: TextMethod<"waitValue", TextWaitQueryArgs>; waitAll: TextMethod<"waitArray", TextWaitQueryArgs>; ensure: TextMethod<"value", TextQueryArgs>; ensureAll: TextMethod<"array", TextQueryArgs>; } interface QueryObject extends RoleQueries { text: TextQuery; labeled: TextQuery; within: (element?: HTMLElement | null) => QueryObject; } type TextQueryArgs = [id: Matcher, options?: SelectorMatcherOptions]; type TextWaitQueryArgs = [id: Matcher, options?: SelectorMatcherOptions, waitForElementOptions?: waitForOptions]; declare function createRoleQuery(role: AriaRole, queries?: ElementQueries): ((name?: string | RegExp, options?: ByRoleOptions) => HTMLElement | null) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => HTMLElement | null>; } & { hidden: ((name?: string | RegExp, options?: ByRoleOptions) => HTMLElement | null) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => HTMLElement | null>; }; all: ((name?: string | RegExp, options?: ByRoleOptions) => HTMLElement[]) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => HTMLElement[]>; } & { hidden: ((name?: string | RegExp, options?: ByRoleOptions) => HTMLElement[]) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => HTMLElement[]>; }; wait: ((name?: string | RegExp, options?: ByRoleOptions) => Promise) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => Promise>; } & { hidden: ((name?: string | RegExp, options?: ByRoleOptions) => Promise) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => Promise>; }; }; ensure: ((name?: string | RegExp, options?: ByRoleOptions) => HTMLElement[]) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => HTMLElement[]>; } & { hidden: ((name?: string | RegExp, options?: ByRoleOptions) => HTMLElement[]) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => HTMLElement[]>; }; }; }; wait: ((name?: string | RegExp, options?: ByRoleOptions) => Promise) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => Promise>; } & { hidden: ((name?: string | RegExp, options?: ByRoleOptions) => Promise) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => Promise>; }; all: ((name?: string | RegExp, options?: ByRoleOptions) => Promise) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => Promise>; } & { hidden: ((name?: string | RegExp, options?: ByRoleOptions) => Promise) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => Promise>; }; }; }; ensure: ((name?: string | RegExp, options?: ByRoleOptions) => HTMLElement) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => HTMLElement>; } & { hidden: ((name?: string | RegExp, options?: ByRoleOptions) => HTMLElement) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => HTMLElement>; }; all: ((name?: string | RegExp, options?: ByRoleOptions) => HTMLElement[]) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => HTMLElement[]>; } & { hidden: ((name?: string | RegExp, options?: ByRoleOptions) => HTMLElement[]) & { lazy: LazyQuery<(name?: string | RegExp, options?: ByRoleOptions) => HTMLElement[]>; }; }; }; }; declare function createTextQuery(defaultQuery: TextMethod<"nullable", TextQueryArgs>, params: TextQueryParams): TextVariant<"nullable", TextQueryArgs> & { all: TextVariant<"array", TextQueryArgs> & { wait: TextVariant<"waitArray", TextWaitQueryArgs>; ensure: TextVariant<"array", TextQueryArgs>; }; wait: TextVariant<"waitValue", TextWaitQueryArgs> & { all: TextVariant<"waitArray", TextWaitQueryArgs>; }; ensure: TextVariant<"value", TextQueryArgs> & { all: TextVariant<"array", TextQueryArgs>; }; }; /** * Queries the DOM by ARIA role, accessible name, text, or label, built on top of * Testing Library. Call a role method such as `query.button(name)` or * `query.dialog()` to get the matching element (or `null`), passing a string or * `RegExp` to match its accessible name. Use `query.text()` and `query.labeled()` * to query by text content or associated label, and `query.within(element)` to * scope queries to a subtree. * * Every query also exposes `.lazy` (return a reusable function that runs the * query when called), `.all` (return all matches), `.wait` (resolve once the * element appears), and `.ensure` (throw when it's missing) variants, and role * queries additionally expose `.hidden` to include otherwise-hidden elements. * @example * ```ts * const dialog = query.dialog.lazy("Settings"); * expect(dialog()).not.toBeInTheDocument(); * await click(query.button("Open settings")); * expect(dialog()).toBeVisible(); * // Wait for an element to appear, or scope a query to a subtree: * await query.alert.wait(); * query.within(dialog()).button("Close"); * ``` */ declare const query: QueryObject; /** * Short alias for `query`. Queries the DOM by ARIA role, accessible name, text, or * label. * @example * ```ts * const dialog = q.dialog.lazy("Settings"); * expect(dialog()).not.toBeInTheDocument(); * await click(q.button("Open settings")); * expect(dialog()).toBeVisible(); * ``` */ declare const q: QueryObject; //#endregion //#region src/right-click.d.ts /** * Right-clicks on an element, simulating the sequence of events a real secondary * mouse click produces — hovering the target, then right-button `pointerdown`, * `mousedown`, `focus`, `contextmenu`, `pointerup`, `mouseup`, and `auxclick`. * * Hidden elements are handled the same way a browser would, and no synthetic * `click` event is fired. Pass `options` to set event properties such as * modifier keys. * @example * ```ts * await rightClick(q.text("Open menu")); * ``` */ declare function rightClick(element: Element | null, options?: PointerEventInit): Promise; //#endregion //#region src/select.d.ts /** * Selects a range of text within an element, simulating a real user dragging * across it. Hovers and presses on the element, finds the given `text` in its * descendant text nodes, sets the document selection to cover it, then releases. * * When no element is passed, `document.body` is used. Pass `options` to set event * properties such as modifier keys. * @example * ```ts * await select("hello world"); * expect(document.getSelection()?.toString()).toBe("hello world"); * ``` */ declare function select(text: string, element?: Element | null, options?: PointerEventInit): Promise; //#endregion //#region src/sleep.d.ts /** * Waits for the DOM to settle between simulated interactions by yielding across * two animation frames and a short timeout. * * The other helpers in this package call it internally, but you can await it * directly to let pending updates, transitions, or effects flush before asserting. * The default delay is small and environment-dependent; pass `ms` to override it. * Outside a real browser it also drains the host scheduler so concurrent React * work that the delay raced past settles before the call resolves. * @example * ```ts * await click(q.button("Open")); * await sleep(); * expect(q.dialog()).toBeVisible(); * ``` */ declare function sleep(ms?: number): Promise; //#endregion //#region src/tap.d.ts /** * Clicks on an element without the brief delay that `click` waits between * pressing and releasing, reproducing the timing of a quick tap. It fires the * same pointer, mouse, and click events as `click`. Pass `options` to set event * properties such as modifier keys. * @example * ```ts * await tap(q.button("Submit")); * ``` */ declare function tap(element: Element | null, options?: PointerEventInit): Promise; //#endregion //#region src/type.d.ts /** * Types text into an element, simulating a real user pressing each key. Focuses * the element, then for each character fires `keydown`, updates the value and * caret position of text fields through an `input` event (preceded by `keypress` * when inserting a printable character), and fires `keyup`. * * Special characters map to their keys: `"\b"` is Backspace, `"\x7f"` is Delete, * `"\n"` is Enter, and `"\t"` is Tab. When no element is passed, the currently * focused element is used. Pass `options` to set event properties such as modifier * keys or composition state. * @example * ```ts * await type("Hello", q.textbox()); * // Delete the last character with a Backspace: * await type("\b"); * ``` */ declare function type(text: string, element?: (DirtiableElement & HTMLElement) | null, options?: InputEventInit | KeyboardEventInit): Promise; //#endregion //#region src/wait-for.d.ts /** * Re-runs a callback until it stops throwing or the timeout is reached, * re-exporting Testing Library's `waitFor` with this package's async batching * applied. Use it to wait for an assertion to pass after an asynchronous update. * Pass `options` to configure the `timeout`, `interval`, and other behavior. * @example * ```ts * await click(q.button("Close")); * await waitFor(() => expect(q.dialog()).not.toBeInTheDocument()); * ``` */ declare function waitFor(callback: () => T, options?: DOMTestingLibrary.waitForOptions): Promise; //#endregion export { select as a, query as c, mouseDown as d, hover as f, blur as g, click as h, sleep as i, press as l, dispatch as m, type as n, rightClick as o, focus as p, tap as r, q as s, waitFor as t, mouseUp as u }; //# sourceMappingURL=index-CYusFHZV.d.ts.map