support {checked: true} for checkbox / radio

[idanen]

Closes #691

What:

Allow querying checkboxes and radios that are checked using the selected option in ByRole queries.

Why:

Better experience than filtering for them

How:

Checking for both aria-selected and checked property.

Checklist:

• Documentation added to the
  docs site
• Tests
• Typescript definitions updated
• Ready to be merged
  

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 0bfd8e1:

Sandbox	Source
kentcdodds/react-testing-library-examples	Configuration

[codecov]

Codecov Report

Merging #692 into master will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff            @@
##            master      #692   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           24        24           
  Lines          603       614   +11     
  Branches       151       156    +5     
=========================================
+ Hits           603       614   +11     

Impacted Files	Coverage Δ
src/queries/role.js	100.00% <100.00%> (ø)
src/role-helpers.js	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2215770...0bfd8e1. Read the comment docs.

[kentcdodds]

This is fine with me, though I'd like to hear other's opinions.

[eps1lon]

Referencing #691 (comment) to make it clear that it we haven't decided whether the problem in the linked issue is something we should solve.

[eps1lon]

Now that I think about it: How is mixed treated? Right now we're treating it like selected but selected only has two states while checked has three: true, false and mixed (or indeterminated): https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role

[idanen]

Good point.
According to the spec:

The control is never a true tri-state control, even if the element's indeterminate IDL attribute is set to true. The indeterminate IDL attribute only gives the appearance of a third state.

Also from the spec:

If the element's indeterminate IDL attribute is set to true, then the control's selection should be obscured as if the control was in a third, indeterminate, state.

So I don't really know how to move forward..
Any suggestions?

[idanen]

Another point: the spec uses "positive selection" and "negative selection" when describing checkedness state, so maybe that's not such a bad idea to use the same API (selected)?

[eps1lon]

So I don't really know how to move forward..

How is aria-checked mapped from and to <input type="checkbox" />?

[idanen]

From what I went over (checked spec, and WAI-ARIA for aria-checked), it's implied that:
The WAI-ARIA spec describes it like this:

• When checked, the checkbox element has state aria-checked set to true.
• When not checked, it has state aria-checked set to false.
• When partially checked, it has state aria-checked set to mixed.

There's no direct "mapping", but from how I understand it should map like so:

• When checked, the checkbox element's checked property is set to true.
• When not checked, the checkbox element's checked property is set to false.
• When partially checked, the checkbox element's checked property is set to false and indeterminate property is set to true.

So when using ByRole with {checked: true} or {checked: false} it's pretty obvious, non should include mixed.
Do we want to add also {indeterminate: true}? Make the checked option tri-state?

This discussion makes me lean more towards {selected: true}, since it really helps users find controls by state, without diving too deep into the HTML spec.
If a label like "Please select one or more of these" is semantically correct, than querying with "selected" should also be correct.
WDYT?

[eps1lon]

checkbox role, with the aria-checked state set to "mixed" if the element's indeterminate IDL attribute is true, or "true" if the element's checkedness is true, or "false" otherwise

-- https://www.w3.org/TR/html-aam-1.0/#details-id-56

So indeterminate=true takes presedence.

[kentcdodds]

@all-contributors please add @idanen for code and tests

[allcontributors]

@kentcdodds

I've put up a pull request to add @idanen! 🎉

[kentcdodds]

Thanks so much for your help! I've added you as a collaborator on the project. Please make sure that you review the other/MAINTAINING.md and CONTRIBUTING.md files (specifically the bit about the commit messages and the git hooks) and familiarize yourself with the code of conduct (we're using the contributor covenant). You might also want to watch the repo to be notified when someone files an issue/PR. Please continue to make PRs as you feel the need (you can make your branches directly on the repo rather than your fork if you want). Thanks! And welcome to the team :)

[kentcdodds]

🎉 This PR is included in version 7.21.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀