diff --git a/package.json b/package.json index cc443e6e..7d6dee3d 100644 --- a/package.json +++ b/package.json @@ -39,6 +39,7 @@ ], "dependencies": { "@babel/runtime": "^7.10.3", + "@types/aria-query": "^4.2.0", "aria-query": "^4.2.2", "dom-accessibility-api": "^0.4.5", "pretty-format": "^25.5.0" diff --git a/types/__tests__/type-tests.ts b/types/__tests__/type-tests.ts index 83b6f5f2..32663fd4 100644 --- a/types/__tests__/type-tests.ts +++ b/types/__tests__/type-tests.ts @@ -113,6 +113,9 @@ async function testByRole() { name === 'Login' && element.hasAttribute('disabled'), }) === null, ) + + // allow to query for a role that isn't included in the types + console.assert(queryByRole(element, 'foo') === null) } function testA11yHelper() { diff --git a/types/queries.d.ts b/types/queries.d.ts index 92c1b946..cdee32da 100644 --- a/types/queries.d.ts +++ b/types/queries.d.ts @@ -1,139 +1,205 @@ -import { Matcher, MatcherOptions } from './matches'; -import { SelectorMatcherOptions } from './query-helpers'; -import { waitForOptions } from './wait-for'; +import {Matcher, MatcherOptions} from './matches' +import {SelectorMatcherOptions} from './query-helpers' +import {waitForOptions} from './wait-for' +import {ARIARole} from 'aria-query' export type QueryByBoundAttribute = ( - container: HTMLElement, - id: Matcher, - options?: MatcherOptions, -) => HTMLElement | null; + container: HTMLElement, + id: Matcher, + options?: MatcherOptions, +) => HTMLElement | null -export type AllByBoundAttribute = (container: HTMLElement, id: Matcher, options?: MatcherOptions) => HTMLElement[]; +export type AllByBoundAttribute = ( + container: HTMLElement, + id: Matcher, + options?: MatcherOptions, +) => HTMLElement[] export type FindAllByBoundAttribute = ( - container: HTMLElement, - id: Matcher, - options?: MatcherOptions, - waitForElementOptions?: waitForOptions, -) => Promise; - -export type GetByBoundAttribute = (container: HTMLElement, id: Matcher, options?: MatcherOptions) => HTMLElement; + container: HTMLElement, + id: Matcher, + options?: MatcherOptions, + waitForElementOptions?: waitForOptions, +) => Promise + +export type GetByBoundAttribute = ( + container: HTMLElement, + id: Matcher, + options?: MatcherOptions, +) => HTMLElement export type FindByBoundAttribute = ( - container: HTMLElement, - id: Matcher, - options?: MatcherOptions, - waitForElementOptions?: waitForOptions, -) => Promise; - -export type QueryByText = (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions) => HTMLElement | null; - -export type AllByText = (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions) => HTMLElement[]; + container: HTMLElement, + id: Matcher, + options?: MatcherOptions, + waitForElementOptions?: waitForOptions, +) => Promise + +export type QueryByText = ( + container: HTMLElement, + id: Matcher, + options?: SelectorMatcherOptions, +) => HTMLElement | null + +export type AllByText = ( + container: HTMLElement, + id: Matcher, + options?: SelectorMatcherOptions, +) => HTMLElement[] export type FindAllByText = ( - container: HTMLElement, - id: Matcher, - options?: SelectorMatcherOptions, - waitForElementOptions?: waitForOptions, -) => Promise; - -export type GetByText = (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions) => HTMLElement; + container: HTMLElement, + id: Matcher, + options?: SelectorMatcherOptions, + waitForElementOptions?: waitForOptions, +) => Promise + +export type GetByText = ( + container: HTMLElement, + id: Matcher, + options?: SelectorMatcherOptions, +) => HTMLElement export type FindByText = ( - container: HTMLElement, - id: Matcher, - options?: SelectorMatcherOptions, - waitForElementOptions?: waitForOptions, -) => Promise; + container: HTMLElement, + id: Matcher, + options?: SelectorMatcherOptions, + waitForElementOptions?: waitForOptions, +) => Promise export interface ByRoleOptions extends MatcherOptions { - /** - * If true includes elements in the query set that are usually excluded from - * the accessibility tree. `role="none"` or `role="presentation"` are included - * in either case. - */ - hidden?: boolean; - /** - * If true only includes elements in the query set that are marked as - * selected in the accessibility tree, i.e., `aria-selected="true"` - */ - selected?: boolean; - /** - * Includes every role used in the `role` attribute - * For example *ByRole('progressbar', {queryFallbacks: true})` will find
`. - */ - queryFallbacks?: boolean; - /** - * Only considers elements with the specified accessible name. - */ - name?: string | RegExp | ((accessibleName: string, element: Element) => boolean); + /** + * If true includes elements in the query set that are usually excluded from + * the accessibility tree. `role="none"` or `role="presentation"` are included + * in either case. + */ + hidden?: boolean + /** + * If true only includes elements in the query set that are marked as + * selected in the accessibility tree, i.e., `aria-selected="true"` + */ + selected?: boolean + /** + * Includes every role used in the `role` attribute + * For example *ByRole('progressbar', {queryFallbacks: true})` will find
`. + */ + queryFallbacks?: boolean + /** + * Only considers elements with the specified accessible name. + */ + name?: + | string + | RegExp + | ((accessibleName: string, element: Element) => boolean) } -export type AllByRole = (container: HTMLElement, role: Matcher, options?: ByRoleOptions) => HTMLElement[]; - -export type GetByRole = (container: HTMLElement, role: Matcher, options?: ByRoleOptions) => HTMLElement; - -export type QueryByRole = (container: HTMLElement, role: Matcher, options?: ByRoleOptions) => HTMLElement | null; - -export type FindByRole = ( - container: HTMLElement, - role: Matcher, - options?: ByRoleOptions, - waitForElementOptions?: waitForOptions, -) => Promise; - -export type FindAllByRole = ( - container: HTMLElement, - role: Matcher, - options?: ByRoleOptions, - waitForElementOptions?: waitForOptions, -) => Promise; - -export const getByLabelText: GetByText; -export const getAllByLabelText: AllByText; -export const queryByLabelText: QueryByText; -export const queryAllByLabelText: AllByText; -export const findByLabelText: FindByText; -export const findAllByLabelText: FindAllByText; -export const getByPlaceholderText: GetByBoundAttribute; -export const getAllByPlaceholderText: AllByBoundAttribute; -export const queryByPlaceholderText: QueryByBoundAttribute; -export const queryAllByPlaceholderText: AllByBoundAttribute; -export const findByPlaceholderText: FindByBoundAttribute; -export const findAllByPlaceholderText: FindAllByBoundAttribute; -export const getByText: GetByText; -export const getAllByText: AllByText; -export const queryByText: QueryByText; -export const queryAllByText: AllByText; -export const findByText: FindByText; -export const findAllByText: FindAllByText; -export const getByAltText: GetByBoundAttribute; -export const getAllByAltText: AllByBoundAttribute; -export const queryByAltText: QueryByBoundAttribute; -export const queryAllByAltText: AllByBoundAttribute; -export const findByAltText: FindByBoundAttribute; -export const findAllByAltText: FindAllByBoundAttribute; -export const getByTitle: GetByBoundAttribute; -export const getAllByTitle: AllByBoundAttribute; -export const queryByTitle: QueryByBoundAttribute; -export const queryAllByTitle: AllByBoundAttribute; -export const findByTitle: FindByBoundAttribute; -export const findAllByTitle: FindAllByBoundAttribute; -export const getByDisplayValue: GetByBoundAttribute; -export const getAllByDisplayValue: AllByBoundAttribute; -export const queryByDisplayValue: QueryByBoundAttribute; -export const queryAllByDisplayValue: AllByBoundAttribute; -export const findByDisplayValue: FindByBoundAttribute; -export const findAllByDisplayValue: FindAllByBoundAttribute; -export const getByRole: GetByRole; -export const getAllByRole: AllByRole; -export const queryByRole: QueryByRole; -export const queryAllByRole: AllByRole; -export const findByRole: FindByRole; -export const findAllByRole: FindAllByRole; -export const getByTestId: GetByBoundAttribute; -export const getAllByTestId: AllByBoundAttribute; -export const queryByTestId: QueryByBoundAttribute; -export const queryAllByTestId: AllByBoundAttribute; -export const findByTestId: FindByBoundAttribute; -export const findAllByTestId: FindAllByBoundAttribute; +// disable unified-signatures to have intellisense for aria roles +/* tslint:disable:unified-signatures */ +export function AllByRole( + container: HTMLElement, + role: Matcher, + options?: ByRoleOptions, +): HTMLElement[] +export function AllByRole( + container: HTMLElement, + role: ARIARole, + options?: ByRoleOptions, +): HTMLElement[] + +export function GetByRole( + container: HTMLElement, + role: Matcher, + options?: ByRoleOptions, +): HTMLElement +export function GetByRole( + container: HTMLElement, + role: ARIARole, + options?: ByRoleOptions, +): HTMLElement + +export function QueryByRole( + container: HTMLElement, + role: Matcher | ByRoleOptions, + options?: ByRoleOptions, +): HTMLElement | null +export function QueryByRole( + container: HTMLElement, + role: ARIARole, + options?: ByRoleOptions, +): HTMLElement | null + +export function FindByRole( + container: HTMLElement, + role: Matcher, + options?: ByRoleOptions, + waitForElementOptions?: waitForOptions, +): Promise +export function FindByRole( + container: HTMLElement, + role: ARIARole, + options?: ByRoleOptions, + waitForElementOptions?: waitForOptions, +): Promise + +export function FindAllByRole( + container: HTMLElement, + role: Matcher, + options?: ByRoleOptions, + waitForElementOptions?: waitForOptions, +): Promise +export function FindAllByRole( + container: HTMLElement, + role: Matcher, + options?: ByRoleOptions, + waitForElementOptions?: waitForOptions, +): Promise +/* tslint:enable */ + +export const getByLabelText: GetByText +export const getAllByLabelText: AllByText +export const queryByLabelText: QueryByText +export const queryAllByLabelText: AllByText +export const findByLabelText: FindByText +export const findAllByLabelText: FindAllByText +export const getByPlaceholderText: GetByBoundAttribute +export const getAllByPlaceholderText: AllByBoundAttribute +export const queryByPlaceholderText: QueryByBoundAttribute +export const queryAllByPlaceholderText: AllByBoundAttribute +export const findByPlaceholderText: FindByBoundAttribute +export const findAllByPlaceholderText: FindAllByBoundAttribute +export const getByText: GetByText +export const getAllByText: AllByText +export const queryByText: QueryByText +export const queryAllByText: AllByText +export const findByText: FindByText +export const findAllByText: FindAllByText +export const getByAltText: GetByBoundAttribute +export const getAllByAltText: AllByBoundAttribute +export const queryByAltText: QueryByBoundAttribute +export const queryAllByAltText: AllByBoundAttribute +export const findByAltText: FindByBoundAttribute +export const findAllByAltText: FindAllByBoundAttribute +export const getByTitle: GetByBoundAttribute +export const getAllByTitle: AllByBoundAttribute +export const queryByTitle: QueryByBoundAttribute +export const queryAllByTitle: AllByBoundAttribute +export const findByTitle: FindByBoundAttribute +export const findAllByTitle: FindAllByBoundAttribute +export const getByDisplayValue: GetByBoundAttribute +export const getAllByDisplayValue: AllByBoundAttribute +export const queryByDisplayValue: QueryByBoundAttribute +export const queryAllByDisplayValue: AllByBoundAttribute +export const findByDisplayValue: FindByBoundAttribute +export const findAllByDisplayValue: FindAllByBoundAttribute +export const getByRole: typeof GetByRole +export const getAllByRole: typeof AllByRole +export const queryByRole: typeof QueryByRole +export const queryAllByRole: typeof AllByRole +export const findByRole: typeof FindByRole +export const findAllByRole: typeof FindAllByRole +export const getByTestId: GetByBoundAttribute +export const getAllByTestId: AllByBoundAttribute +export const queryByTestId: QueryByBoundAttribute +export const queryAllByTestId: AllByBoundAttribute +export const findByTestId: FindByBoundAttribute +export const findAllByTestId: FindAllByBoundAttribute diff --git a/types/tslint.json b/types/tslint.json index 5d45232f..cb0fce9f 100644 --- a/types/tslint.json +++ b/types/tslint.json @@ -3,6 +3,7 @@ "rules": { "no-useless-files": false, "no-relative-import-in-test": false, - "semicolon": false + "semicolon": false, + "whitespace": false } }