fix: Make table column announcements less verbose for screen readers

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap

@@ -15805,8 +15805,6 @@ add a meaningful description to the whole selection.
 * \`ariaLabel\` (LabelData => string) - An optional function that's called to provide an \`aria-label\` for the cell header.
   It receives the current sorting state of this column, the direction it's sorted in, and an indication of
   whether the sorting is disabled, as three Boolean values: \`sorted\`, \`descending\` and \`disabled\`.
-  We recommend that you use this for sortable columns to provide more meaningful labels based on the
-  current sorting direction.
 * \`sortingField\` (string) - Enables default column sorting. The value is used in [collection hooks](/get-started/dev-guides/collection-hooks/)
   to reorder the items. Provide the name of the property within each item that should be used for sorting by this column.
   For more complex sorting use \`sortingComparator\` instead.

src/table/__tests__/header-cell.test.tsx

@@ -110,6 +110,27 @@ it('updates based on resize observer if dynamic flag is set', () => {
   expect(updateColumn).toHaveBeenCalledWith('id', 234);
 });
 
+it('is labelled using the column ariaLabel if one is provided', () => {
+  const { container } = render(
+    <TableWrapper>
+      <TestComponent column={{ cell: () => null, header: () => 'Test', ariaLabel: () => 'Programmatic label' }} />
+    </TableWrapper>
+  );
+  expect(container.querySelector('th')).not.toHaveAttribute('aria-labelledby');
+  expect(container.querySelector('th')).toHaveAttribute('aria-label', 'Programmatic label');
+});
+
+it("is labelled using the header cell content if a column ariaLabel isn't provided", () => {
+  const { container } = render(
+    <TableWrapper>
+      <TestComponent column={{ cell: () => null, header: () => 'Test' }} />
+    </TableWrapper>
+  );
+  const ariaLabelledBy = container.querySelector('th')!.getAttribute('aria-labelledby');
+  expect(ariaLabelledBy).toBeTruthy();
+  expect(container.querySelector(`.${styles['header-cell-text']}`)).toHaveAttribute('id', ariaLabelledBy);
+});
+
 describe('i18n', () => {
   it('supports using editIconAriaLabel from i18n provider', () => {
     const { container } = render(

src/table/header-cell/index.tsx

@@ -103,6 +103,11 @@ export function TableHeaderCell<ItemType>({
   };
 
   const headerId = useUniqueId('table-header-');
+  const columnAriaLabel = column.ariaLabel?.({
+    sorted: sorted,
+    descending: sorted && !!sortingDescending,
+    disabled: !!sortingDisabled,
+  });
 
   const clickableHeaderRef = useRef<HTMLDivElement>(null);
   const { tabIndex: clickableHeaderTabIndex } = useSingleTabStopNavigation(clickableHeaderRef, { tabIndex });
@@ -135,6 +140,8 @@ export function TableHeaderCell<ItemType>({
       stickyState={stickyState}
       tableRole={tableRole}
       variant={variant}
+      ariaLabel={columnAriaLabel}
+      ariaLabelledby={headerId}
       {...(sortingDisabled
         ? {}
         : getAnalyticsMetadataAttribute({
@@ -154,21 +161,13 @@ export function TableHeaderCell<ItemType>({
           [styles['header-cell-fake-focus']]: focusedComponent === `sorting-control-${String(columnId)}`,
           [styles['header-cell-content-expandable']]: isExpandable,
         })}
-        aria-label={
-          column.ariaLabel
-            ? column.ariaLabel({
-                sorted: sorted,
-                descending: sorted && !!sortingDescending,
-                disabled: !!sortingDisabled,
-              })
-            : undefined
-        }
         {...(sortingStatus && !sortingDisabled
           ? {
               onKeyPress: handleKeyPress,
               tabIndex: clickableHeaderTabIndex,
               role: 'button',
               onClick: handleClick,
+              'aria-label': columnAriaLabel,
             }
           : {})}
       >

src/table/header-cell/th-element.tsx

@@ -36,6 +36,7 @@ export interface TableThElementProps {
   children: React.ReactNode;
   variant: TableProps.Variant;
   ariaLabel?: string;
+  ariaLabelledby?: string;
 }
 
 export function TableThElement({
@@ -56,6 +57,7 @@ export function TableThElement({
   children,
   variant,
   ariaLabel,
+  ariaLabelledby,
   ...props
 }: TableThElementProps) {
   const isVisualRefresh = useVisualRefresh();
@@ -70,6 +72,9 @@ export function TableThElement({
   const mergedRef = useMergeRefs(stickyStyles.ref, cellRef, cellRefObject);
   const { tabIndex: cellTabIndex } = useSingleTabStopNavigation(cellRefObject);
 
+  // Ensure ariaLabel (if one is provided) overrides ariaLabelledby
+  const labelProps = ariaLabel ? { 'aria-label': ariaLabel } : { 'aria-labelledby': ariaLabelledby };
+
   return (
     <th
       data-focus-id={`header-${String(columnId)}`}
@@ -97,7 +102,7 @@ export function TableThElement({
       {...getTableColHeaderRoleProps({ tableRole, sortingStatus, colIndex })}
       tabIndex={cellTabIndex === -1 ? undefined : cellTabIndex}
       {...copyAnalyticsMetadataAttribute(props)}
-      {...(ariaLabel ? { 'aria-label': ariaLabel } : {})}
+      {...labelProps}
     >
       {children}
     </th>

src/table/interfaces.tsx

@@ -88,8 +88,6 @@ export interface TableProps<T = any> extends BaseComponentProps {
    * * `ariaLabel` (LabelData => string) - An optional function that's called to provide an `aria-label` for the cell header.
    *   It receives the current sorting state of this column, the direction it's sorted in, and an indication of
    *   whether the sorting is disabled, as three Boolean values: `sorted`, `descending` and `disabled`.
-   *   We recommend that you use this for sortable columns to provide more meaningful labels based on the
-   *   current sorting direction.
    * * `sortingField` (string) - Enables default column sorting. The value is used in [collection hooks](/get-started/dev-guides/collection-hooks/)
    *   to reorder the items. Provide the name of the property within each item that should be used for sorting by this column.
    *   For more complex sorting use `sortingComparator` instead.