docs: expanded filter documentation and examples (testing-library#681)

Co-authored-by: Luis Rodrigues <luis.rodrigues@springernature.com>

Author: goblindegook

docs/dom-testing-library/api-queries.mdx

@@ -169,6 +169,7 @@ The example below will find the input node for the following DOM structures:
 label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
 <TabItem value="native">
 
+
 ```js
 import { screen } from '@testing-library/dom'
 
@@ -178,6 +179,7 @@ const inputNode = screen.getByLabelText('Username')
  </TabItem>
  <TabItem value="react">
 
+
 ```jsx
 import { render, screen } from '@testing-library/react'
 
@@ -189,13 +191,15 @@ const inputNode = screen.getByLabelText('username')
  </TabItem>
  <TabItem value="cypress">
 
+
 ```js
 cy.findByLabelText('username').should('exist')
 ```
 
  </TabItem>
  </Tabs>
 
+
 It will NOT find the input node for label text broken up by elements. You can
 use `getByRole('textbox', { name: 'Username' })` instead which is robust against
 switching to `aria-label` or `aria-labelledby`.
@@ -263,6 +267,7 @@ matches the given [`TextMatch`](#textmatch).
 label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
 <TabItem value="native">
 
+
 ```js
 import { screen } from '@testing-library/dom'
 
@@ -272,6 +277,7 @@ const inputNode = screen.getByPlaceholderText('Username')
  </TabItem>
  <TabItem value="react">
 
+
 ```jsx
 import { render, screen } from '@testing-library/react'
 
@@ -282,13 +288,15 @@ const inputNode = screen.getByPlaceholderText('Username')
  </TabItem>
  <TabItem value="cypress">
 
+
 ```js
 cy.findByPlaceholderText('Username').should('exist')
 ```
 
  </TabItem>
  </Tabs>
 
+
 > **Note**
 >
 > A placeholder is not a good substitute for a label so you should generally use
@@ -322,6 +330,7 @@ matching the given [`TextMatch`](#textmatch).
 label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
 <TabItem value="native">
 
+
 ```js
 import { screen } from '@testing-library/dom'
 
@@ -331,6 +340,7 @@ const aboutAnchorNode = screen.getByText(/about/i)
  </TabItem>
  <TabItem value="react">
 
+
 ```jsx
 import { render, screen } from '@testing-library/react'
 
@@ -341,13 +351,15 @@ const aboutAnchorNode = screen.getByText(/about/i)
  </TabItem>
  <TabItem value="cypress">
 
+
 ```js
 cy.findByText(/about/i).should('exist')
 ```
 
  </TabItem>
  </Tabs>
 
+
 It also works with `input`s whose `type` attribute is either `submit` or
 `button`:
 
@@ -400,6 +412,7 @@ as it's deprecated).
 label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
 <TabItem value="native">
 
+
 ```js
 import { screen } from '@testing-library/dom'
 
@@ -409,6 +422,7 @@ const incrediblesPosterImg = screen.getByAltText(/incredibles.*? poster/i)
  </TabItem>
  <TabItem value="react">
 
+
 ```jsx
 import { render, screen } from '@testing-library/react'
 
@@ -419,13 +433,15 @@ const incrediblesPosterImg = screen.getByAltText(/incredibles.*? poster/i)
  </TabItem>
  <TabItem value="cypress">
 
+
 ```js
 cy.findByAltText(/incredibles.*? poster/i).should('exist')
 ```
 
  </TabItem>
  </Tabs>
 
+
 ### `ByTitle`
 
 > getByTitle, queryByTitle, getAllByTitle, queryAllByTitle, findByTitle,
@@ -457,6 +473,7 @@ Will also find a `title` element within an SVG.
 label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
 <TabItem value="native">
 
+
 ```js
 import { screen } from '@testing-library/dom'
 
@@ -467,6 +484,7 @@ const closeElement = screen.getByTitle('Close')
  </TabItem>
  <TabItem value="react">
 
+
 ```jsx
 import { render, screen } from '@testing-library/react'
 
@@ -478,6 +496,7 @@ const closeElement = screen.getByTitle('Close')
  </TabItem>
  <TabItem value="cypress">
 
+
 ```js
 cy.findByTitle('Delete').should('exist')
 cy.findByTitle('Close').should('exist')
@@ -486,6 +505,7 @@ cy.findByTitle('Close').should('exist')
  </TabItem>
  </Tabs>
 
+
 ### `ByDisplayValue`
 
 > getByDisplayValue, queryByDisplayValue, getAllByDisplayValue,
@@ -518,6 +538,7 @@ document.getElementById('lastName').value = 'Norris'
 label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
 <TabItem value="native">
 
+
 ```js
 import { screen } from '@testing-library/dom'
 
@@ -527,6 +548,7 @@ const lastNameInput = screen.getByDisplayValue('Norris')
  </TabItem>
  <TabItem value="react">
 
+
 ```jsx
 import { render, screen } from '@testing-library/react'
 
@@ -537,13 +559,15 @@ const lastNameInput = screen.getByDisplayValue('Norris')
  </TabItem>
  <TabItem value="cypress">
 
+
 ```js
 cy.findByDisplayValue('Norris').should('exist')
 ```
 
  </TabItem>
  </Tabs>
 
+
 #### `textarea`
 
 ```html
@@ -558,6 +582,7 @@ document.getElementById('messageTextArea').value = 'Hello World'
 label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
 <TabItem value="native">
 
+
 ```js
 import { screen } from '@testing-library/dom'
 
@@ -567,6 +592,7 @@ const messageTextArea = screen.getByDisplayValue('Hello World')
  </TabItem>
  <TabItem value="react">
 
+
 ```jsx
 import { render, screen } from '@testing-library/react'
 
@@ -577,13 +603,15 @@ const messageTextArea = screen.getByDisplayValue('Hello World')
  </TabItem>
  <TabItem value="cypress">
 
+
 ```js
 cy.findByDisplayValue('Hello World').should('exist')
 ```
 
  </TabItem>
  </Tabs>
 
+
 #### `select`
 
 In case of `select`, this will search for a `<select>` whose selected `<option>`
@@ -602,6 +630,7 @@ matches the given [`TextMatch`](#textmatch).
 label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
 <TabItem value="native">
 
+
 ```js
 import { screen } from '@testing-library/dom'
 
@@ -611,6 +640,7 @@ const selectElement = screen.getByDisplayValue('Alaska')
  </TabItem>
  <TabItem value="react">
 
+
 ```jsx
 import { render, screen } from '@testing-library/react'
 
@@ -621,13 +651,15 @@ const selectElement = screen.getByDisplayValue('Alaska')
  </TabItem>
  <TabItem value="cypress">
 
+
 ```js
 cy.findByDisplayValue('Alaska').should('exist')
 ```
 
  </TabItem>
  </Tabs>
 
+
 ### `ByRole`
 
 > getByRole, queryByRole, getAllByRole, queryAllByRole, findByRole,
@@ -645,6 +677,7 @@ getByRole(
  selected?: boolean,
  checked?: boolean,
  pressed?: boolean,
+ expanded?: boolean,
  queryFallbacks?: boolean,
  level?: number,
  }): HTMLElement
@@ -778,6 +811,37 @@ you can get the "👍" button by calling `getByRole('button', { pressed: true })
 To learn more about the pressed state see
 [ARIA `aria-pressed`](https://www.w3.org/TR/wai-aria-1.2/#aria-pressed).
 
+#### `expanded`
+
+You can filter the returned elements by their expanded state by setting
+`expanded: true` or `expanded: false`.
+
+For example in
+
+```html
+<body>
+ <nav>
+ <ul>
+ <li>
+ <a aria-expanded="false" aria-haspopup="true" href="..."
+ >Expandable Menu Item</a
+ >
+ <ul>
+ <li><a href="#">Submenu Item 1</a></li>
+ <li><a href="#">Submenu Item 1</a></li>
+ </ul>
+ </li>
+ <li><a href="#">Regular Menu Item</a></li>
+ </ul>
+ </nav>
+</body>
+```
+
+you can get the "Expandable Menu Item" link by calling
+`getByRole('link', { expanded: false })`. To learn more about the checked state
+and which elements can have this state see
+[ARIA `aria-checked`](https://www.w3.org/TR/wai-aria-1.2/#aria-expanded).
+
 ```html
 <div role="dialog">...</div>
 ```
@@ -786,6 +850,7 @@ To learn more about the pressed state see
 label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
 <TabItem value="native">
 
+
 ```js
 import { screen } from '@testing-library/dom'
 
@@ -795,6 +860,7 @@ const dialogContainer = screen.getByRole('dialog')
  </TabItem>
  <TabItem value="react">
 
+
 ```jsx
 import { render, screen } from '@testing-library/react'
 
@@ -805,13 +871,15 @@ const dialogContainer = screen.getByRole('dialog')
  </TabItem>
  <TabItem value="cypress">
 
+
 ```js
 cy.findByRole('dialog').should('exist')
 ```
 
  </TabItem>
  </Tabs>
 
+
 #### `queryFallbacks`
 
 By default, it's assumed that the first role of each element is supported, so
@@ -903,6 +971,7 @@ also accepts a [`TextMatch`](#textmatch)).
 label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }>
 <TabItem value="native">
 
+
 ```js
 import { screen } from '@testing-library/dom'
 
@@ -912,6 +981,7 @@ const element = screen.getByTestId('custom-element')
  </TabItem>
  <TabItem value="react">
 
+
 ```jsx
 import { render, screen } from '@testing-library/react'
 
@@ -922,13 +992,15 @@ const element = screen.getByTestId('custom-element')
  </TabItem>
  <TabItem value="cypress">
 
+
 ```js
 cy.findByTestId('custom-element').should('exist')
 ```
 
  </TabItem>
  </Tabs>
 
+
 > In the spirit of [the guiding principles](guiding-principles.mdx), it is
 > recommended to use this only after the other queries don't work for your use
 > case. Using data-testid attributes do not resemble how your software is used