DataTable accessibility

src/data-table/data-table.styles.tsx

@@ -184,6 +184,7 @@ export const HeaderRow = styled.tr`
 `;
 
 export const HeaderCell = styled.th<HeaderCellProps>`
+    position: relative;
     padding: ${(props) =>
         props.$isCheckbox ? "1.25rem 0.5rem 1.25rem 1.5rem" : "1.25rem 1rem"};
     text-align: left;
@@ -198,6 +199,10 @@ export const HeaderCell = styled.th<HeaderCellProps>`
             `;
         }
     }};
+    &:focus-within {
+        outline: 2px solid ${Colour["focus-ring"]};
+        outline-offset: -3px;
+    }
 `;
 
 export const HeaderCellWrapper = styled.div`

src/data-table/data-table.tsx

@@ -5,7 +5,9 @@ import { useResizeDetector } from "react-resize-detector";
 import { LoadingDotsSpinner } from "../animations";
 import { Checkbox } from "../checkbox";
 import { ErrorDisplay } from "../error-display";
+import { VisuallyHidden, concatIds } from "../shared/accessibility";
 import { Typography } from "../typography";
+import { SimpleIdGenerator } from "../util";
 import { useEventListener } from "../util/use-event-listener";
 import {
     ActionBar,
@@ -59,6 +61,13 @@ export const DataTable = ({
     const headerRef = useRef<HTMLTableSectionElement>(null);
     const actionBarRef = useRef<HTMLDivElement>(null);
     const wrapperRef = useRef<HTMLDivElement>(null);
+    const [internalId] = useState(() => SimpleIdGenerator.generate());
+    const keyColumns = headers.filter(
+        (header): header is Exclude<HeaderProps, string> => {
+            return typeof header !== "string" && !!header.keyColumn;
+        }
+    );
+
     const [scrollable, setScrollable] = useState(false);
     const [scrollEnd, setScrollEnd] = useState(false);
     const [tableEnd, setTableEnd] = useState(false);
@@ -150,6 +159,42 @@ export const DataTable = ({
         return headers.length + (enableMultiSelect ? 1 : 0);
     };
 
+    const getSortDirection = (fieldKey: string) => {
+        return sortIndicators?.[fieldKey];
+    };
+
+    const getHeaderAriaSort = (fieldKey: string) => {
+        const sortDirection = getSortDirection(fieldKey);
+
+        if (!sortDirection) {
+            return undefined;
+        }
+
+        return sortDirection === "asc" ? "ascending" : "descending";
+    };
+
+    const getSortButtonAriaLabel = (fieldKey: string) => {
+        const nextSortDirection =
+            getSortDirection(fieldKey) === "asc" ? "descending" : "ascending";
+
+        return ` by ${nextSortDirection} order`;
+    };
+
+    const getHeaderWrapperId = (fieldKey: string) => {
+        return `${internalId}-header-${fieldKey}`;
+    };
+    const getCellId = (rowId: string, fieldKey: string) => {
+        return `${internalId}-row-${rowId}-${fieldKey}-key-column`;
+    };
+
+    const getRowCheckboxAriaLabelledBy = (rowId: string) => {
+        const keyColumnIds = keyColumns.map((header) =>
+            getCellId(rowId, header.fieldKey)
+        );
+
+        return concatIds(...keyColumnIds);
+    };
+
     const calculateFixedInViewport = () => {
         if (!wrapperRef.current) {
             return;
@@ -228,16 +273,20 @@ export const DataTable = ({
               }
             : header;
 
+        const isSortable = !!getSortDirection(fieldKey);
+        const headerCellWrapperId = getHeaderWrapperId(fieldKey);
+
         return (
             <HeaderCell
                 data-testid={getDataTestId(`header-${fieldKey}`)}
                 key={fieldKey}
                 $clickable={clickable}
-                onClick={() => clickable && onHeaderClick?.(fieldKey)}
+                scope="col"
+                aria-sort={getHeaderAriaSort(fieldKey)}
                 style={style}
                 $isCheckbox={false}
             >
-                <HeaderCellWrapper>
+                <HeaderCellWrapper id={headerCellWrapperId}>
                     {typeof label === "string" ? (
                         <Typography.BodyBL weight="bold">
                             {label}
@@ -247,6 +296,15 @@ export const DataTable = ({
                     )}
                     {renderSortedArrow(fieldKey)}
                 </HeaderCellWrapper>
+                {(clickable || isSortable) && (
+                    <VisuallyHidden>
+                        <button onClick={() => onHeaderClick?.(fieldKey)}>
+                            {isSortable && "Sort "}
+                            <span aria-labelledby={headerCellWrapperId} />
+                            {isSortable && getSortButtonAriaLabel(fieldKey)}
+                        </button>
+                    </VisuallyHidden>
+                )}
             </HeaderCell>
         );
     };
@@ -277,12 +335,15 @@ export const DataTable = ({
                 data-testid={getDataTestId("header-selection")}
                 $clickable={false}
                 $isCheckbox={true}
+                scope="col"
             >
                 <CheckBoxWrapper>
+                    <VisuallyHidden>Row selection</VisuallyHidden>
                     {enableSelectAll && (
                         <Checkbox
                             checked={isAllCheckboxSelected()}
                             indeterminate={isIndeterminateCheckbox()}
+                            aria-label="Select all rows"
                             onClick={() => {
                                 if (onSelectAll) {
                                     onSelectAll(isAllCheckboxSelected());
@@ -314,8 +375,7 @@ export const DataTable = ({
                         $isSelectable={enableMultiSelect}
                         $isSelected={isRowSelected(row.id.toString())}
                     >
-                        {enableMultiSelect &&
-                            renderRowCheckBox(row.id.toString())}
+                        {enableMultiSelect && renderRowCheckBox(row)}
 
                         {headers.map((header) => renderRowCell(header, row))}
                     </BodyRow>
@@ -335,6 +395,7 @@ export const DataTable = ({
             <BodyCell
                 data-testid={getDataTestId(`row-${cellId}`)}
                 key={cellId}
+                id={getCellId(rowId, fieldKey)}
                 style={style}
                 $isCheckbox={false}
             >
@@ -350,7 +411,9 @@ export const DataTable = ({
         );
     };
 
-    const renderRowCheckBox = (rowId: string) => {
+    const renderRowCheckBox = (row: RowProps) => {
+        const rowId = row.id.toString();
+
         return (
             <BodyCell
                 data-testid={getDataTestId(`row-${rowId}-selection`)}
@@ -359,12 +422,14 @@ export const DataTable = ({
                 <CheckBoxWrapper>
                     <Checkbox
                         checked={isRowSelected(rowId)}
+                        aria-labelledby={getRowCheckboxAriaLabelledBy(rowId)}
                         onClick={() => {
                             if (onSelect) {
                                 onSelect(rowId, !isRowSelected(rowId));
                             }
                         }}
                         disabled={isDisabledRow(rowId)}
+                        focusableWhenDisabled={isDisabledRow(rowId)}
                     />
                 </CheckBoxWrapper>
             </BodyCell>
@@ -404,7 +469,11 @@ export const DataTable = ({
         return (
             <tr>
                 <td colSpan={getTotalColumns()}>
-                    <LoaderWrapper>
+                    <LoaderWrapper
+                        role="status"
+                        aria-live="polite"
+                        aria-label="Loading table"
+                    >
                         {loadState === "loading" && <LoadingDotsSpinner />}
                     </LoaderWrapper>
                 </td>
@@ -431,7 +500,13 @@ export const DataTable = ({
                     <Typography.BodyMD weight="semibold">{`${count} item${
                         count > 1 ? "s" : ""
                     } selected`}</Typography.BodyMD>
-                    <TextButton type="button" onClick={onClearSelectionClick}>
+                    <TextButton
+                        type="button"
+                        aria-label={`Clear selection of ${count} item${
+                            count === 1 ? "" : "s"
+                        }`}
+                        onClick={onClearSelectionClick}
+                    >
                         Clear selection
                     </TextButton>
                     {actionBarContent}

src/data-table/types.ts

@@ -56,6 +56,11 @@ interface HeaderItemProps {
     // technically ReactNode also includes string, but this is more explicit
     label: string | ReactNode;
     clickable?: boolean | undefined;
+    /** Used with `enableMultiSelect`. Marks this column as descriptive of the row
+     * (e.g. a name or unique ID). Its value is used to label the row's checkbox
+     * for screen readers.
+     */
+    keyColumn?: boolean | undefined;
     style?: CSSProperties | undefined;
 }
 

stories/data-table/doc-elements.tsx

@@ -37,17 +37,24 @@ export const DataTableWithCustomHeight = ({
     children,
 }: Props) => {
     const [height, setHeight] = useState<Height>("default");
+    const rowCountInputId = "data-table-row-count";
+
     return (
         <Container $height={height} key={height}>
             <div>
                 <Typography.BodyBL>
                     Modify the options to view the scroll behaviour
                 </Typography.BodyBL>
-                <Typography.BodySM weight="semibold">
+                <Typography.BodySM
+                    as="label"
+                    htmlFor={rowCountInputId}
+                    weight="semibold"
+                >
                     Number of rows
                 </Typography.BodySM>
                 <div>
                     <input
+                        id={rowCountInputId}
                         type="range"
                         value={rowCount}
                         min={1}

stories/data-table/props-table.tsx

@@ -163,6 +163,12 @@ const DATA: ApiTableSectionProps[] = [
                     "Specifies custom styles for the column header cell",
                 propTypes: ["CSSProperties"],
             },
+            {
+                name: "keyColumn",
+                description:
+                    "Used with enableMultiSelect. Marks this column as descriptive of the row and uses its value to label the row checkbox for screen readers",
+                propTypes: ["boolean"],
+            },
         ],
     },
     {

stories/data-table/row-data.tsx

@@ -28,10 +28,12 @@ export const DATA_HEADERS = [
     {
         fieldKey: "status",
         label: "Status",
+        keyColumn: true,
     },
     {
         fieldKey: "resource",
         label: "Resource",
+        keyColumn: true,
     },
     {
         fieldKey: "time",