fix(data-tables): Add aria label attributes to Data Tables (#4623)

* add captions to base data tables

* add captions to data table in card

* make caption a prop on Table

* add captions to advanced data table

* add captions to fixed header data table

* add captions to hidden header data table

* add captions to advanced data table

* add captions to miscellaneous HTML tables

* add captions to tree grid

* add test for captions

* add aria-labelledby and aria-label to data-table

* add release notes

* change captions to aria-label

* add docs

* update tests

* change captions to labels on raw table examples

* update tree grid

* add/update tree grid tests

Author: Dottenpixel

ui/components/cards/base/example.jsx

@@ -29,7 +29,14 @@ const headerAction = (
 );
 
 const bodyTable = (
-  <Table isFixedLayout isBordered hasNoRowHover hasCellBuffer type="advanced">
+  <Table
+    isFixedLayout
+    isBordered
+    hasNoRowHover
+    hasCellBuffer
+    type="advanced"
+    ariaLabel="Example table in a Card"
+  >
     <THead>
       <THeadTr>
         <ColumnTh>

ui/components/data-tables/RELEASENOTES.md

@@ -4,6 +4,9 @@
 
 <!-- ## [Unreleased] -->
 
+# 2.15.1
+
+- Added `<caption>`, and alternatively, `aria-labelledby` and `aria-label` to allow adding additional table context for screen readers
 # 2.14.0
 
 ### Added

ui/components/data-tables/__tests__/__snapshots__/index.spec.jsx.snap

@@ -1691,15 +1691,15 @@ exports[`AdvancedDataTableHead component should set sort direction 1`] = `
           <input
             aria-labelledby="check-select-all-label column-group-header"
             defaultChecked={null}
-            id="checkbox-unique-id-1"
+            id="checkbox-unique-id-15"
             name="options"
             tabIndex="-1"
             type="checkbox"
-            value="checkbox-unique-id-1"
+            value="checkbox-unique-id-15"
           />
           <label
             className="slds-checkbox__label"
-            htmlFor="checkbox-unique-id-1"
+            htmlFor="checkbox-unique-id-15"
             id="check-select-all-label"
           >
             <span
@@ -1775,7 +1775,7 @@ exports[`AdvancedDataTableHead component should set sort direction 1`] = `
         <input
           aria-label="Name column width"
           className="slds-resizable__input slds-assistive-text"
-          id="cell-resize-handle-1"
+          id="cell-resize-handle-21"
           max="1000"
           min="20"
           tabIndex="-1"
@@ -2226,6 +2226,40 @@ exports[`Data table component should render a base table 1`] = `
 />
 `;
 
+exports[`Data table component should render a table with a caption with aria-label 1`] = `
+<table
+  aria-label="Example caption"
+  aria-multiselectable={null}
+  className="slds-table"
+  role={null}
+/>
+`;
+
+exports[`Data table component should render a table with a caption with aria-labelledby 1`] = `
+Array [
+  <h2
+    id="element-with-table-label"
+  >
+    Example data table of Opportunities
+  </h2>,
+  <h3
+    id="other-element-with-table-label"
+  >
+    Using 
+    <code>
+      aria-labelledby
+    </code>
+    , instead of aria-label
+  </h3>,
+  <table
+    aria-labelledby="element-with-table-label other-element-with-table-label"
+    aria-multiselectable={null}
+    className="slds-table"
+    role={null}
+  />,
+]
+`;
+
 exports[`Data table component should render a table with borders 1`] = `
 <table
   aria-multiselectable={null}
@@ -3310,7 +3344,7 @@ Array [
     <input
       aria-label="Column Name column width"
       className="slds-resizable__input slds-assistive-text"
-      id="cell-resize-handle-1"
+      id="cell-resize-handle-7"
       max="1000"
       min="20"
       tabIndex="-1"

ui/components/data-tables/__tests__/index.spec.jsx

@@ -91,6 +91,25 @@ describe('Data table component', () => {
 
   it('should render a table with passed styles', () =>
     matchesMarkup(<Table style={{ width: '10rem' }} type="base" />));
+
+  it('should render a table with a caption with aria-label', () =>
+    matchesMarkup(<Table type="base" ariaLabel="Example caption" />));
+
+  it('should render a table with a caption with aria-labelledby', () =>
+    matchesMarkup(
+      <>
+        <h2 id="element-with-table-label">
+          Example data table of Opportunities
+        </h2>
+        <h3 id="other-element-with-table-label">
+          Using <code>aria-labelledby</code>, instead of aria-label
+        </h3>
+        <Table
+          type="base"
+          ariaLabelledBy="element-with-table-label other-element-with-table-label"
+        />
+      </>
+    ));
 });
 
 describe('THead Component', () => {

ui/components/data-tables/advanced/example.jsx

@@ -146,6 +146,7 @@ export default (
     isResizable
     selectionType="multiple"
     type="advanced"
+    ariaLabel="Example default advanced table of Opportunities"
   >
     <Thead columns={columns} />
     <TBody>
@@ -172,6 +173,7 @@ export let states = [
         isResizable
         selectionType="multiple"
         type="advanced"
+        ariaLabel="Example advanced table of Opportunities with cell focused"
       >
         <Thead columns={columns} />
         <TBody>
@@ -198,6 +200,7 @@ export let states = [
         isResizable
         selectionType="multiple"
         type="advanced"
+        ariaLabel="Example advanced table of Opportunities in actionable mode"
       >
         <Thead actionableMode columns={columns} />
         <TBody>
@@ -224,6 +227,7 @@ export let states = [
         isResizable
         selectionType="multiple"
         type="advanced"
+        ariaLabel="Example advanced table of Opportunities in actionable mode with row selected"
       >
         <Thead actionableMode columns={columns} />
         <TBody>
@@ -250,6 +254,7 @@ export let states = [
         isResizable
         selectionType="multiple"
         type="advanced"
+        ariaLabel="Example advanced table of Opportunities in actionable mode with all rows selected"
       >
         <Thead actionableMode columns={columns} selectAll />
         <TBody>
@@ -276,6 +281,7 @@ export let states = [
         isResizable
         selectionType="multiple"
         type="advanced"
+        ariaLabel="Example advanced table of Opportunities in actionable mode with ascending column sorting"
       >
         <Thead columns={columns} actionableMode sortDirection="ascending" />
         <TBody>
@@ -302,6 +308,7 @@ export let states = [
         isResizable
         selectionType="multiple"
         type="advanced"
+        ariaLabel="Example advanced table of Opportunities in actionable mode with descending column sorting"
       >
         <Thead columns={columns} actionableMode sortDirection="descending" />
         <TBody>
@@ -328,6 +335,7 @@ export let states = [
         isResizable
         selectionType="multiple"
         type="advanced"
+        ariaLabel="Example advanced table of Opportunities in actionable mode with resized column"
       >
         <Thead columns={columns} actionableMode singleColumnWidth="300px" />
         <TBody>
@@ -357,6 +365,7 @@ export let examples = [
         isResizable
         selectionType="multiple"
         type="advanced"
+        ariaLabel="Example advanced table of Opportunities with header icon and menu button"
       >
         <Thead
           columnHeaderIcons={columnHeaderIcons}
@@ -386,6 +395,7 @@ export let examples = [
         isResizable
         selectionType="multiple"
         type="advanced"
+        ariaLabel="Example advanced table of Opportunities with header menu button"
       >
         <Thead columns={columns} hasMenus />
         <TBody>
@@ -411,6 +421,7 @@ export let examples = [
         isResizable
         selectionType="multiple"
         type="advanced"
+        ariaLabel="Example advanced table of Opportunities with cell icon"
       >
         <Thead columns={columns} />
         <TBody>
@@ -437,6 +448,7 @@ export let examples = [
         isResizable
         selectionType="multiple"
         type="advanced"
+        ariaLabel="Example advanced table as product listing"
       >
         <Thead columns={productColumns} actionableMode hasNoRowSelection />
         <TBody>
@@ -457,7 +469,13 @@ export let examples = [
     id: 'radio-group',
     label: 'Radio Group',
     element: (
-      <Table isBordered isFixedLayout isResizable type="advanced">
+      <Table
+        isBordered
+        isFixedLayout
+        isResizable
+        type="advanced"
+        ariaLabel="Example advanced table as radio group"
+      >
         <Thead columns={columns} hasSingleRowSelect />
         <TBody>
           {rows.map((row, i) => (
@@ -476,7 +494,13 @@ export let examples = [
     id: 'data-table-no-borders',
     label: 'No borders',
     element: (
-      <Table isFixedLayout isResizable selectionType="multiple" type="advanced">
+      <Table
+        isFixedLayout
+        isResizable
+        selectionType="multiple"
+        type="advanced"
+        ariaLabel="Example advanced table with no borders"
+      >
         <Thead columns={columns} />
         <TBody>
           {rows.map((row, i) => (
@@ -500,6 +524,7 @@ export let examples = [
         isBordered
         selectionType="multiple"
         type="advanced"
+        ariaLabel="Example advanced headless table"
       >
         <Thead isHidden columns={columns} />
         <TBody>
@@ -519,7 +544,12 @@ export let examples = [
     id: 'data-table-headless-no-borders',
     label: 'Headless with no borders',
     element: (
-      <Table hasHiddenHeader selectionType="multiple" type="advanced">
+      <Table
+        hasHiddenHeader
+        selectionType="multiple"
+        type="advanced"
+        ariaLabel="Example advanced headless border-less table"
+      >
         <Thead isHidden columns={columns} />
         <TBody>
           {rows.map((row, i) => (