feat(labels): add support for aria-labelledby (testing-library#121)

Fixes testing-library#120 

<!--
Thanks for your interest in the project. Bugs filed and PRs submitted are appreciated!

Please make sure that you are familiar with and follow the Code of Conduct for
this project (found in the CODE_OF_CONDUCT.md file).

Also, please make sure you're familiar with and follow the instructions in the
contributing guidelines (found in the CONTRIBUTING.md file).

If you're new to contributing to open source projects, you might find this free
video course helpful: http://kcd.im/pull-request

Please fill out the information below to expedite the review and (hopefully)
merge of your pull request!
-->

<!-- What changes are being made? (What feature/bug is being fixed here?) -->

**What**:

<!-- Why are these changes necessary? -->

**Why**:

<!-- How were these changes implemented? -->

**How**:

<!-- Have you done all of these things?  -->

**Checklist**:

<!-- add "N/A" to the end of each line that's irrelevant to your changes -->

<!-- to check an item, place an "x" in the box like so: "- [x] Documentation" -->

- [ ] Documentation
- [ ] Tests
- [ ] Ready to be merged <!-- In your opinion, is this ready to be merged as soon as it's reviewed? -->
- [ ] Added myself to contributors table <!-- this is optional, see the contributing guidelines for instructions -->

<!-- feel free to add additional comments -->

Author: alexkrolick

.size-snapshot.json

@@ -1,7 +1,7 @@
 {
   "dist/dom-testing-library.umd.js": {
-    "bundled": 115443,
-    "minified": 50960,
-    "gzipped": 15294
+    "bundled": 122519,
+    "minified": 52052,
+    "gzipped": 15632
   }
 }

README.md

@@ -211,10 +211,16 @@ const inputNode = getByLabelText(container, 'Username')
 // <label for="username-input">Username</label>
 // <input id="username-input" />
 //
-// The aria-labelledby attribute
+// The aria-labelledby attribute with form elements
 // <label id="username-label">Username</label>
 // <input aria-labelledby="username-label" />
 //
+// The aria-labelledby attribute with other elements
+// <section aria-labelledby="section-one-header">
+//   <h3 id="section-one-header">Section One</h3>
+//   <p>some content...</p>
+// <section>
+//
 // Wrapper labels
 // <label>Username <input /></label>
 //

src/__tests__/element-queries.js

@@ -82,7 +82,7 @@ test('matches case with RegExp matcher', () => {
   expect(queryByText(/Step 1 of 4/)).not.toBeTruthy()
 })
 
-test('get can get form controls by label text', () => {
+test('can get form controls by label text', () => {
   const {getByLabelText} = render(`
     <div>
       <label>
@@ -116,6 +116,27 @@ test('get can get form controls by label text', () => {
   expect(getByLabelText('5th two').id).toBe('fifth-id')
 })
 
+test('can get elements labelled with aria-labelledby attribute', () => {
+  const {getByLabelText, getAllByLabelText} = render(`
+    <div>
+      <h1 id="content-header">The Gettysburg Address</h1>
+      <main id="sibling-of-content-header" aria-labelledby="content-header">
+        <section aria-labelledby="content-header section-one-header" id="section-one">
+          <h2 id="section-one-header">Section One</h2>
+          <p>Four score and seven years ago, ...</p>
+        </section>
+      </main>
+      <p>The Gettysburg Address</p>
+    </div>
+  `)
+  const result = getAllByLabelText('The Gettysburg Address').map(el => el.id)
+  expect(result).toHaveLength(2)
+  expect(result).toEqual(
+    expect.arrayContaining(['sibling-of-content-header', 'section-one']),
+  )
+  expect(getByLabelText('Section One').id).toBe('section-one')
+})
+
 test('get can get form controls by placeholder', () => {
   const {getByPlaceholderText} = render(`
     <input id="username-id" placeholder="username" />,

src/queries.js

@@ -59,7 +59,28 @@ function queryAllByLabelText(
     .filter(label => label !== null)
     .concat(queryAllByAttribute('aria-label', container, text, {exact}))
 
-  return labelledElements
+  const possibleAriaLabelElements = queryAllByText(container, text, {
+    exact,
+    ...matchOpts,
+  }).filter(el => el.tagName !== 'LABEL') // don't reprocess labels
+
+  const ariaLabelledElements = possibleAriaLabelElements.reduce(
+    (allLabelledElements, nextLabelElement) => {
+      const labelId = nextLabelElement.getAttribute('id')
+
+      if (!labelId) return allLabelledElements
+
+      // ARIA labels can label multiple elements
+      const labelledNodes = Array.from(
+        container.querySelectorAll(`[aria-labelledby~="${labelId}"]`),
+      )
+
+      return allLabelledElements.concat(labelledNodes)
+    },
+    [],
+  )
+
+  return Array.from(new Set([...labelledElements, ...ariaLabelledElements]))
 }
 
 function queryByLabelText(...args) {