From af7a5719c2d5bf431a4b9ab53e4feccebb5e9366 Mon Sep 17 00:00:00 2001
From: XOP <evgeny.khoroshilov@clickhouse.com>
Date: Fri, 2 Oct 2026 12:42:34 +0200
Subject: [PATCH] fix(a11y): Table sortable keyboard operable

---
 .changeset/fix-cui-307-table-headers-a11y.md |   5 +
 eslint-suppressions.json                     |  14 --
 src/components/Table/Table.module.css        |  16 ++
 src/components/Table/Table.test.tsx          | 139 ++++++++++++++++-
 src/components/Table/Table.tsx               | 151 +++++++++++++------
 5 files changed, 265 insertions(+), 60 deletions(-)
 create mode 100644 .changeset/fix-cui-307-table-headers-a11y.md

diff --git a/.changeset/fix-cui-307-table-headers-a11y.md b/.changeset/fix-cui-307-table-headers-a11y.md
new file mode 100644
index 000000000..6ee8abeb2
--- /dev/null
+++ b/.changeset/fix-cui-307-table-headers-a11y.md
@@ -0,0 +1,5 @@
+---
+'@clickhouse/click-ui': patch
+---
+
+`Table` header content for sortable columns, and for columns with an `onClick`, now renders as a `<button>`: keyboard users reach it with Tab and sort with Enter or Space, and the sorted column exposes `aria-sort`. A sorted header's accessible name no longer ends in "arrow-down"; the direction is in `aria-sort`. Column resizers report their width and range to assistive technology. Header labels of sortable or clickable columns must not contain interactive content. Headers marked `isSortable` on a table without `onSort` no longer show a pointer cursor. Visual: unchanged, except a focus ring on a focused sortable header.
diff --git a/eslint-suppressions.json b/eslint-suppressions.json
index de9ddb697..c415fd44b 100644
--- a/eslint-suppressions.json
+++ b/eslint-suppressions.json
@@ -40,19 +40,5 @@
     "jsx-a11y/no-static-element-interactions": {
       "count": 1
     }
-  },
-  "src/components/Table/Table.tsx": {
-    "jsx-a11y/click-events-have-key-events": {
-      "count": 1
-    },
-    "jsx-a11y/no-noninteractive-element-interactions": {
-      "count": 1
-    },
-    "jsx-a11y/no-noninteractive-tabindex": {
-      "count": 1
-    },
-    "jsx-a11y/no-static-element-interactions": {
-      "count": 1
-    }
   }
 }
\ No newline at end of file
diff --git a/src/components/Table/Table.module.css b/src/components/Table/Table.module.css
index 00e5fd0ac..b6bf10860 100644
--- a/src/components/Table/Table.module.css
+++ b/src/components/Table/Table.module.css
@@ -82,7 +82,23 @@
 }
 
 .table__header-content_interactive {
+  width: 100%;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: inherit;
+  font: inherit;
+  letter-spacing: inherit;
+  text-align: inherit;
+  text-transform: inherit;
   cursor: pointer;
+  word-spacing: inherit;
+}
+
+.table__header-content_interactive:focus-visible {
+  outline: 2px solid var(--click-global-color-outline-default);
+  outline-offset: 2px;
 }
 
 .table__resizer {
diff --git a/src/components/Table/Table.test.tsx b/src/components/Table/Table.test.tsx
index a28cd9e14..02d1724d5 100644
--- a/src/components/Table/Table.test.tsx
+++ b/src/components/Table/Table.test.tsx
@@ -1,4 +1,5 @@
-import { fireEvent } from '@testing-library/react';
+import { fireEvent, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { Table, TableProps } from '@/components/Table';
 import { renderCUI } from '@/utils/test-utils';
 
@@ -245,4 +246,140 @@ describe('Table', () => {
     expect(resizers[0]).toHaveAttribute('tabIndex', '0');
     expect(resizers[1]).toHaveAttribute('tabIndex', '0');
   });
+
+  describe('sortable headers', () => {
+    const sortableHeaders = [
+      { label: 'Company', isSortable: true, sortDir: 'asc' as const },
+      { label: 'Contact', isSortable: true },
+      { label: 'Country' },
+    ];
+
+    it('renders sortable headers as buttons named after the label', () => {
+      const { getByRole } = renderCUI(
+        <Table
+          headers={sortableHeaders}
+          rows={rows}
+          onSort={vi.fn()}
+        />
+      );
+
+      expect(getByRole('button', { name: 'Company' })).toBeInTheDocument();
+      expect(getByRole('button', { name: 'Contact' })).toBeInTheDocument();
+      const country = getByRole('columnheader', { name: 'Country' });
+      expect(within(country).queryByRole('button')).toBeNull();
+    });
+
+    it('renders no header button when onSort is missing', () => {
+      const { getAllByRole } = renderCUI(
+        <Table
+          headers={sortableHeaders}
+          rows={rows}
+        />
+      );
+
+      getAllByRole('columnheader').forEach(header => {
+        expect(within(header).queryByRole('button')).toBeNull();
+      });
+    });
+
+    it('is reachable with Tab and sorts with Enter and Space', async () => {
+      const user = userEvent.setup();
+      const onSort = vi.fn();
+      const { getByRole } = renderCUI(
+        <Table
+          headers={sortableHeaders}
+          rows={rows}
+          onSort={onSort}
+        />
+      );
+
+      await user.tab();
+      expect(getByRole('button', { name: 'Company' })).toHaveFocus();
+
+      await user.keyboard('{Enter}');
+      expect(onSort).toHaveBeenCalledTimes(1);
+      expect(onSort).toHaveBeenLastCalledWith('desc', sortableHeaders[0], 0);
+
+      await user.tab();
+      expect(getByRole('button', { name: 'Contact' })).toHaveFocus();
+
+      await user.keyboard(' ');
+      expect(onSort).toHaveBeenCalledTimes(2);
+      expect(onSort).toHaveBeenLastCalledWith('asc', sortableHeaders[1], 1);
+    });
+
+    it('exposes aria-sort on the sorted column only', () => {
+      const { getByRole } = renderCUI(
+        <Table
+          headers={sortableHeaders}
+          rows={rows}
+          onSort={vi.fn()}
+        />
+      );
+
+      expect(getByRole('columnheader', { name: 'Company' })).toHaveAttribute(
+        'aria-sort',
+        'ascending'
+      );
+      expect(getByRole('columnheader', { name: 'Contact' })).not.toHaveAttribute(
+        'aria-sort'
+      );
+      expect(getByRole('columnheader', { name: 'Country' })).not.toHaveAttribute(
+        'aria-sort'
+      );
+    });
+
+    it('maps a descending sortDir to aria-sort="descending"', () => {
+      const { getByRole } = renderCUI(
+        <Table
+          headers={[{ label: 'Company', isSortable: true, sortDir: 'desc' }]}
+          rows={[]}
+          onSort={vi.fn()}
+        />
+      );
+
+      expect(getByRole('columnheader', { name: 'Company' })).toHaveAttribute(
+        'aria-sort',
+        'descending'
+      );
+    });
+  });
+
+  it('names the header button with a consumer aria-label', () => {
+    const { getByRole } = renderCUI(
+      <Table
+        headers={[{ label: 'Company', isSortable: true, 'aria-label': 'Company name' }]}
+        rows={[]}
+        onSort={vi.fn()}
+      />
+    );
+
+    expect(getByRole('button', { name: 'Company name' })).toBeInTheDocument();
+    expect(getByRole('columnheader', { name: 'Company name' })).toBeInTheDocument();
+  });
+
+  it('reports the column width and range on the resizer and updates it on ArrowRight', () => {
+    const rect = vi
+      .spyOn(HTMLElement.prototype, 'getBoundingClientRect')
+      .mockReturnValue({ width: 200 } as DOMRect);
+
+    try {
+      const { getAllByRole } = renderTable({ resizableColumns: true });
+      const resizer = getAllByRole('separator')[0];
+
+      expect(resizer).toHaveAttribute('tabIndex', '0');
+      expect(resizer).toHaveAttribute('aria-valuenow', '200');
+      expect(resizer).toHaveAttribute('aria-valuemin', '120');
+      expect(resizer).toHaveAttribute('aria-valuemax', '280');
+      expect(resizer).toHaveAttribute('aria-valuetext', '200 pixels');
+
+      fireEvent.keyDown(resizer, { key: 'ArrowRight' });
+
+      expect(resizer).toHaveAttribute('aria-valuenow', '202');
+      expect(resizer).toHaveAttribute('aria-valuetext', '202 pixels');
+      expect(resizer).toHaveAttribute('aria-valuemax', '280');
+    } finally {
+      rect.mockRestore();
+    }
+  });
 });
diff --git a/src/components/Table/Table.tsx b/src/components/Table/Table.tsx
index 7882bd1c9..018543c0a 100644
--- a/src/components/Table/Table.tsx
+++ b/src/components/Table/Table.tsx
@@ -35,7 +35,10 @@ type TableSize = 'sm' | 'md';
 // truncate-middle: text cuts in middle, shows start and end
 type OverflowMode = 'truncated' | 'truncate-middle' | 'wrap';
 
+const MIN_COLUMN_WIDTH = 120;
+
 export interface TableColumnConfigProps extends HTMLAttributes<HTMLTableCellElement> {
+  /** Rendered inside a `<button>` when the column is sortable or has `onClick`, so it must not contain interactive content. */
   label: ReactNode;
   isSortable?: boolean;
   sortDir?: SortDir;
@@ -85,6 +88,8 @@ interface TableHeaderProps extends Omit<TableColumnConfigProps, 'width'> {
     e: React.KeyboardEvent,
     direction: OnKeyboardResizerDirection
   ) => void;
+  columnWidth?: number;
+  nextColumnWidth?: number;
 }
 
 const TableHeader = ({
@@ -99,8 +104,12 @@ const TableHeader = ({
   showResizer,
   onResizeStart,
   onKeyboardResize,
+  columnWidth,
+  nextColumnWidth,
   overflowMode,
   className,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
   ...props
 }: TableHeaderProps) => {
   if (overflowMode === 'wrap' && resizable) {
@@ -115,7 +124,9 @@ const TableHeader = ({
   );
   const resizerRef = useRef<HTMLDivElement>(null);
 
-  const onHeaderClick = (e: MouseEvent<HTMLTableCellElement>): void => {
+  const onHeaderClick = (
+    e: MouseEvent<HTMLButtonElement & HTMLTableCellElement>
+  ): void => {
     if (typeof onClick === 'function') {
       onClick(e);
     }
@@ -146,42 +157,74 @@ const TableHeader = ({
     }
   };
 
+  const ariaSort =
+    isSorted && isSortable ? (sortDir === 'asc' ? 'ascending' : 'descending') : undefined;
+  const isMeasured = columnWidth !== undefined;
+  const maxColumnWidth =
+    isMeasured && nextColumnWidth !== undefined
+      ? Math.round(columnWidth + nextColumnWidth - MIN_COLUMN_WIDTH)
+      : undefined;
+  const headerContentClassName = cn(
+    styles['table__header-content'],
+    isInteractive && styles['table__header-content_interactive']
+  );
+  const headerContent = (
+    <>
+      {isSorted && isSortable && sortPosition == 'start' && (
+        <Icon
+          name="arrow-down"
+          size="sm"
+          aria-hidden="true"
+          className={cn(sortIconVariants({ dir: sortDir }))}
+        />
+      )}
+      {label}
+      {isSorted && isSortable && sortPosition == 'end' && (
+        <Icon
+          name="arrow-down"
+          size="sm"
+          aria-hidden="true"
+          className={cn(sortIconVariants({ dir: sortDir }))}
+        />
+      )}
+    </>
+  );
+
   return (
     <th
+      aria-sort={ariaSort}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
       {...props}
       className={cn(headerVariants({ size, resizable }), className)}
     >
-      <div
-        onClick={onHeaderClick}
-        className={cn(
-          styles['table__header-content'],
-          isInteractive && styles['table__header-content_interactive']
-        )}
-      >
-        {isSorted && isSortable && sortPosition == 'start' && (
-          <Icon
-            name="arrow-down"
-            size="sm"
-            className={cn(sortIconVariants({ dir: sortDir }))}
-          />
-        )}
-        {label}
-        {isSorted && isSortable && sortPosition == 'end' && (
-          <Icon
-            name="arrow-down"
-            size="sm"
-            className={cn(sortIconVariants({ dir: sortDir }))}
-          />
-        )}
-      </div>
+      {isInteractive ? (
+        <button
+          type="button"
+          onClick={onHeaderClick}
+          aria-label={ariaLabel}
+          aria-labelledby={ariaLabelledBy}
+          className={headerContentClassName}
+        >
+          {headerContent}
+        </button>
+      ) : (
+        <div className={headerContentClassName}>{headerContent}</div>
+      )}
       {showResizer && (
+        // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- a focusable separator is a widget (WAI-ARIA 1.2 window splitter); jsx-a11y models it as static
         <div
           ref={resizerRef}
           onMouseDown={onResizeStart}
           role="separator"
           aria-orientation="vertical"
           aria-label={`Resize ${typeof label === 'string' ? label : 'column'}`}
-          tabIndex={0}
+          aria-valuenow={isMeasured ? Math.round(columnWidth) : undefined}
+          aria-valuemin={MIN_COLUMN_WIDTH}
+          aria-valuemax={maxColumnWidth}
+          aria-valuetext={isMeasured ? `${Math.round(columnWidth)} pixels` : undefined}
+          // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex -- focusable separator, see above
+          tabIndex={isMeasured ? 0 : undefined}
           onKeyDown={onResizerKeyDown}
           className={cn(styles.table__resizer)}
         />
@@ -204,6 +247,7 @@ interface TheadProps {
     columnIndex: number
   ) => (e: React.KeyboardEvent, direction: OnKeyboardResizerDirection) => void;
   theadRef?: RefObject<HTMLTableSectionElement>;
+  columnWidths?: Map<string, number> | null;
 }
 
 const Thead = ({
@@ -219,12 +263,16 @@ const Thead = ({
   onResizeStart,
   theadRef,
   onKeyboardResize,
+  columnWidths,
 }: TheadProps) => {
-  const onSort = (header: TableColumnConfigProps, headerIndex: number) => () => {
-    if (typeof onSortProp === 'function' && header.isSortable) {
-      onSortProp(header.sortDir === 'asc' ? 'desc' : 'asc', header, headerIndex);
-    }
-  };
+  const onSort =
+    typeof onSortProp === 'function'
+      ? (header: TableColumnConfigProps, headerIndex: number) => () => {
+          if (header.isSortable) {
+            onSortProp(header.sortDir === 'asc' ? 'desc' : 'asc', header, headerIndex);
+          }
+        }
+      : undefined;
   return (
     <thead
       ref={theadRef}
@@ -243,18 +291,33 @@ const Thead = ({
             />
           </th>
         )}
-        {headers.map((headerProps, index) => (
-          <TableHeader
-            key={`table-header-${index}`}
-            onSort={onSort(headerProps, index)}
-            size={size}
-            resizable={resizableColumns}
-            showResizer={resizableColumns && index < headers.length - 1}
-            onResizeStart={onResizeStart?.(index)}
-            onKeyboardResize={onKeyboardResize?.(index)}
-            {...headerProps}
-          />
-        ))}
+        {headers.map((headerProps, index) => {
+          const headerLabel =
+            typeof headerProps.label === 'string'
+              ? headerProps.label
+              : `__index_${index}`;
+          const nextHeader = headers[index + 1];
+          const nextHeaderLabel =
+            typeof nextHeader?.label === 'string'
+              ? nextHeader.label
+              : `__index_${index + 1}`;
+          return (
+            <TableHeader
+              key={`table-header-${index}`}
+              onSort={onSort?.(headerProps, index)}
+              size={size}
+              resizable={resizableColumns}
+              showResizer={resizableColumns && index < headers.length - 1}
+              onResizeStart={onResizeStart?.(index)}
+              onKeyboardResize={onKeyboardResize?.(index)}
+              columnWidth={columnWidths?.get(headerLabel)}
+              nextColumnWidth={
+                nextHeader ? columnWidths?.get(nextHeaderLabel) : undefined
+              }
+              {...headerProps}
+            />
+          );
+        })}
         {actionsList.length > 0 && (
           <th
             aria-label="Actions"
@@ -575,9 +638,6 @@ interface ResizeState {
   nextStartWidth: number;
 }
 
-// TODO: What is an acceptable minimum column width?
-const MIN_COLUMN_WIDTH = 120;
-
 const Table = forwardRef<HTMLTableElement, TableProps>(
   (
     {
@@ -882,6 +942,7 @@ const Table = forwardRef<HTMLTableElement, TableProps>(
                 onResizeStart={resizableColumns ? handleResizeStart : undefined}
                 theadRef={theadRef}
                 onKeyboardResize={resizableColumns ? onKeyboardResize : undefined}
+                columnWidths={resizableColumns ? columnWidths : undefined}
               />
             )}
             <tbody className={cn(styles.table__tbody)}>