feat(getByRole): Allow filter by disabled

kemuridama · kemuridama · commit 5ee42573c152 · 2023-05-08T15:21:11.000+09:00
diff --git a/docs/queries/byrole.mdx b/docs/queries/byrole.mdx
@@ -29,6 +29,7 @@ getByRole(
     expanded?: boolean,
     queryFallbacks?: boolean,
     level?: number,
+    disabled?: boolean,
     value?: {
       min?: number,
       max?: number,
@@ -356,7 +357,8 @@ specific value using the `level` option
 `getByRole('spinbutton', { value: { now: 5, min: 0, max: 10, text: 'medium' } })`.
 
 Note that you don't have to specify all properties in `value`. A subset is
-sufficient e.g. `getByRole('spinbutton', { value: { now: 5, text: 'medium' } })`.
+sufficient e.g.
+`getByRole('spinbutton', { value: { now: 5, text: 'medium' } })`.
 
 Given the example below,
 
@@ -399,7 +401,7 @@ getAllByRole('spinbutton', {value: {min: 0}})
 ```
 
 > Every specified property in `value` must match. For example, if you query for
-> `{value: {min: 0, now: 3}}` `aria-valuemin` must be equal to 0 **AND**
+> `{value: {min: 0, now: 3}}` `aria-valuemin` must be equal to 0 **AND** >
 > `aria-valuenow` must be equal to 3
 
 > The `value` option is _only_ applicable to certain roles (check the linked MDN
@@ -444,3 +446,32 @@ You can query a specific element like this
 ```js
 getByRole('alertdialog', {description: 'Your session is about to expire'})
 ```
+
+### `disabled`
+
+You can filter the returned elements by their disabled state by setting
+`disabled: true`, `disabled: false`, `aria-disabled: true` or
+`aria-disabled: false`.
+
+For example in
+
+```html
+<body>
+  <button disabled>disabled</button>
+  <button aria-disabled="true">aria-disabled</button>
+  <button>normal</button>
+</body>
+```
+
+you can query a specific element(s) like this
+
+```js
+getAllByRole('button', {disabled: true})
+// [
+//   <button disabled>disabled</button>,
+//   <button aria-disabled="true">aria-disabled</button>
+// ]
+
+getByRole('button', {disabled: false})
+// <button>normal</button>
+```
