Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Table): a resize handle never adds to its column header's name (#9736)

Cindy Zhang6246298b4863
diff --git a/.changeset/table-resize-handle-header-name.md b/.changeset/table-resize-handle-header-name.md
new file mode 100644
index 0000000000..f063a9ab2f
--- /dev/null
+++ b/.changeset/table-resize-handle-header-name.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] In a `Table` with resizable columns, the resize handle's name and width value no longer join the column header's name. Before, screen readers read "Name 60" with every cell in the column.
+
+@duytbp
diff --git a/docs/specs/components/Table/Table.spec.md b/docs/specs/components/Table/Table.spec.md
index e919e9a4fb..bf4c2f9f1f 100644
--- a/docs/specs/components/Table/Table.spec.md
+++ b/docs/specs/components/Table/Table.spec.md
@@ -209,7 +209,7 @@ Consumer data, columns, props, module signatures and usage remain documented in
| FR8 | Empty data renders the default compact EmptyState unless the caller supplies replacement content or disables it, with FR22 suppressing only the default during admitted initial loading. | Current source, docs, and tests | Legacy delegation verified; FR22 loading exception requires implementation evidence |
| FR9 | Table converts the caller's named plugin record into one ordered array after its built-in styling plugin. Known names use the current canonical sequence `columnSettings → sort → tree → selection → pagination`; every other name follows that known set while preserving its record insertion order. | Current source and docs | Current shared ordering; canonical-name coverage is source-inspected |
| FR10 | Every applicable non-context transform runs sequentially in the resolved plugin-array order, so a later plugin receives the value returned by every earlier successful plugin. A throwing transform reports a development error and leaves the prior accumulated value in the pipeline. | Current source and tests | Sequential composition is tested; failure isolation is source-inspected |
-| FR11 | `transformColumns` completes before element transforms. Table then applies table, header-cell/header-row, body-cell/body-row, scroll-wrapper, and context phases at their render points. Header-cell contributions use `before`, `content`, `after`, `overlay`, and `below` slots. Context transforms run in reverse so the first plugin becomes the outermost provider. | Current source, types, and tests | Transform application is tested; complete cross-phase order is source-inspected |
+| FR11 | `transformColumns` completes before element transforms. Table then applies table, header-cell/header-row, body-cell/body-row, scroll-wrapper, and context phases at their render points. Header-cell contributions use `before`, `content`, `after`, `overlay`, and `below` slots. Content in a header cell's `overlay` slot never joins the header's accessible name. Context transforms run in reverse so the first plugin becomes the outermost provider. | Current source, types, and tests | Transform application is tested; complete cross-phase order is source-inspected |
| FR12 | When built-in and named plugin references are unchanged, Table reuses the resolved plugin array; unknown/custom plugin value identity and insertion order remain stable inputs to memoization. | Current source and performance tests | Current performance contract; focused named-order coverage is partial |
| FR13 | In data-driven mode, each explicit column whose `width` is omitted keeps one equal flexible share and a 60px readability floor. A column sets its own floor with `proportional(value, {minWidth})`, which replaces the 60px floor for that column; Table has no table-wide floor setting. Resolution is a pure function of the final column definitions: row values, rendered header/body measurement, locale, sorting, filtering, virtualization, and loading state do not change any floor. Explicit pixel and proportional widths retain their authored floors. When the resolved floors exceed available inline space, the existing Scroll region provides horizontal overflow. | `component:Table/DEC-2`; current source and tests | Verified by width-resolution unit coverage and the ResponsiveScroll real-browser geometry fixture |
| FR14 | Wherever Table shows a row divider, including while rows glide and in pinned columns, the divider has the width, style and colour the row's border would have: the theme's tokens and any app override on `tr`, `tbody` or `td` borders, so customizations still show. | `component:Table/DEC-3` | Verified by row-expansion glide unit coverage and real-browser divider checks, pinned cells and an open panel included; a transient 1 px WebKit pinned-cell step is a recorded gap |
@@ -439,7 +439,7 @@ for this aggregate ownership.
| FR6 | `plugins/selection/useTableSelection.test.tsx` | Select all, individual, disabled, and non-selectable | Removing header/body Selection controls or row selection state fails existing structure, label, interaction, and ARIA assertions; delegated CheckboxInput target placement remains source-inspected. | `audit:Table/anatomy` |
| FR7 | `plugins/rowExpansion/useTableRowExpansion.test.tsx` plus source inspection | Collapsed, expanded, and non-expandable rows | Removing the Expansion control, conditional detail panel, captured-count `colSpan`, or ARIA state fails existing assertions in the covered plugin order; later column transforms, delegated Icon target placement, and untargeted panel wrappers remain source-inspected. | `audit:Table/anatomy` |
| FR8 | `Table.test.tsx` empty-state suite plus EmptyState public target metadata | Default, custom, disabled, and non-empty | Removing conditional empty behavior fails existing assertions; default EmptyState delegation remains source-inspected. | `audit:Table/anatomy` |
-| FR9-FR11 | `Table.test.tsx`, `types.ts`, `BaseTable.tsx`, and `useBaseTablePlugins.ts` | Built-in plus known and custom named plugins; every transform phase | Sequential composition, base-before-user behavior, transform application, and slot output have focused coverage; complete known-name sorting, phase order, exception continuation, and context nesting remain source-inspected. | `audit:Table/plugins` |
+| FR9-FR11 | `Table.test.tsx`, `types.ts`, `BaseTable.tsx`, and `useBaseTablePlugins.ts`; `useTableColumnResize.test.tsx` "the handle never adds to its column header\'s name (AR1)" and `TableColumnResizeName.a11y.chromium.spec.ts` for the `overlay` slot\'s name | Built-in plus known and custom named plugins; every transform phase | Sequential composition, base-before-user behavior, transform application, and slot output have focused coverage; complete known-name sorting, phase order, exception continuation, and context nesting remain source-inspected. | `audit:Table/plugins` |
| FR12, PR1 | `Table.perf.test.tsx` plus `useBaseTablePlugins.ts` source inspection | Same plugin references, recreated record, and changed plugin value | Unchanged plugin values must preserve the resolved array and representative no-op row-update budgets; focused named-record identity coverage remains partial. | `audit:Table/performance` |
| FR13, PR3 | `Table.test.tsx`, `plugins/columnResize/useTableColumnResize.test.tsx`, `plugins/stickyColumns/useTableStickyColumns.test.tsx`, and `Table.stories.tsx` ResponsiveScroll play assertions | Width-less columns with empty, short, and long-token rows; mixed explicit widths; pinned columns; narrow and fitting containers | Removing the 60px floor, deriving it from row content, changing explicit width semantics, desynchronizing resize bounds or sticky offsets, or preventing the existing Scroll region from activating fails focused unit or real-browser geometry assertions. | `audit:Table/layout` |
| FR14 | `__tests__/TableRowGlide.a11y.browser.spec.ts` screenshot checks of the divider mid-glide, in pinned columns, and under an open detail panel; `plugins/rowExpansion/useTableRowExpansion.glide.test.tsx` for the divider an open panel carries | a theme with a custom divider colour; an app override of a row's border; both mid-glide and on a pinned cell; an open detail panel's divider under the same theme and override | a divider whose width, style or colour differs from the row's border, or that drops a theme or app override, fails | `audit:Table/theming` |
diff --git a/docs/specs/components/Table/plugins/columnResize/useTableColumnResize.spec.md b/docs/specs/components/Table/plugins/columnResize/useTableColumnResize.spec.md
index 95b467b750..01bfbf422f 100644
--- a/docs/specs/components/Table/plugins/columnResize/useTableColumnResize.spec.md
+++ b/docs/specs/components/Table/plugins/columnResize/useTableColumnResize.spec.md
@@ -13,6 +13,7 @@ review_triggers: [behavior, layout, visual, accessibility]
verified_by:
[
packages/core/src/Table/plugins/columnResize/useTableColumnResize.test.tsx,
+ packages/core/src/Table/__tests__/TableColumnResizeName.a11y.chromium.spec.ts,
scripts/check-knowledge.mjs,
]
parent_component: component:Table
@@ -159,7 +160,9 @@ remain in `useTableColumnResize.doc.mjs`.
## Accessibility contract
- **AR1 — Unchanged semantics.** Each boundary keeps its separator role, vertical
- orientation, accessible name naming its column, and current value bounds.
+ orientation, accessible name naming its column, and current value bounds. Its
+ resize handle sits in the `overlay` slot, so it doesn't join the header's
+ name (`component:Table` FR11).
- **AR2 — Decorative disclosure.** `hinted` is presentation only. It changes no ARIA
state, announces nothing, and does not enter or reorder tab order.
- **AR3 — Parity without hover.** Keyboard focus draws the same boundary at accent,
@@ -227,17 +230,17 @@ without a target of its own.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1, FR6 | `useTableColumnResize.test.tsx` boundary-presence cases plus hover-capability and coarse-primary cases | Resizable, opted-out, and generated columns; hover-capable, coarse-primary with keyboard, and coarse-only inputs | A boundary appears on a non-resizable column, disappears from a resizable one, the hover reveal fires where no pointer can hover, or the control is absent where an input can operate it. |
-| FR2 | Browser measurement of scroll-region vertical overflow with the plugin enabled | Short and tall tables, wrapped and single-line headers, dense and default | The indicator ends below the last row or the scroll region gains vertical scroll that the same table lacks without resize. |
-| FR3-FR5, FR9, ORD1 | New focused tests for resting, header-hovered, pointer-on-boundary, focused, and dragging states | Rest, header hover, hover plus pointer on one boundary, keyboard focus with no pointer in the row, drag | A resting header draws boundaries, header hover misses a boundary, the pointed/focused boundary fails to outrank the hint, or focus alone draws a neighbor. |
-| FR10, ORD0 | Scroll-gate test driving the scroll region with a stationary pointer over the header | Pointer resting over a header while the region scrolls and after it settles | Boundaries reveal mid-scroll, an existing hint survives the scroll, or disclosure fails to resume once scrolling stops. |
-| FR7 | Snapshot or assertion that header hover changes no other header or row treatment | Header hover over a sortable and a selectable header | Header hover changes background, label, cursor, width, or another control's state. |
-| FR8, AR1-AR3, AR6 | Existing keyboard and ARIA suites and a coarse-primary keyboard case; an assistive-technology spot check is recommended follow-up | Tab to boundary, arrow resize, screen-reader navigation of the header, coarse-primary device with a keyboard | The boundary leaves tab order on any input that can operate it, loses its name or values, or the hint reaches the accessibility tree. |
-| PR1, PR2 | Render-count assertion around header pointer enter/leave and during a scroll; listener and observer inspection | Pointer enters and leaves the header repeatedly; the region scrolls under a resting pointer | Disclosure rerenders the Table, the scroll gate sets React state, more than one scroll listener or any timer is added, or the extent measurement observes what it resizes. |
-| Plugin composition | Test mounting the resize and sticky-columns plugins together in both insertion orders | Pinned start column with resize enabled, before and after a drag | A pinned column loses `position: sticky` in either order, or the composition depends on caller insertion order. |
-| Record shape | `scripts/check-knowledge.mjs` | Colocated module record, canonical id and filename, parent backlink | A missing, misnamed, mis-parented, or unlinked record passes validation. |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1, FR6 | `useTableColumnResize.test.tsx` boundary-presence cases plus hover-capability and coarse-primary cases | Resizable, opted-out, and generated columns; hover-capable, coarse-primary with keyboard, and coarse-only inputs | A boundary appears on a non-resizable column, disappears from a resizable one, the hover reveal fires where no pointer can hover, or the control is absent where an input can operate it. |
+| FR2 | Browser measurement of scroll-region vertical overflow with the plugin enabled | Short and tall tables, wrapped and single-line headers, dense and default | The indicator ends below the last row or the scroll region gains vertical scroll that the same table lacks without resize. |
+| FR3-FR5, FR9, ORD1 | New focused tests for resting, header-hovered, pointer-on-boundary, focused, and dragging states | Rest, header hover, hover plus pointer on one boundary, keyboard focus with no pointer in the row, drag | A resting header draws boundaries, header hover misses a boundary, the pointed/focused boundary fails to outrank the hint, or focus alone draws a neighbor. |
+| FR10, ORD0 | Scroll-gate test driving the scroll region with a stationary pointer over the header | Pointer resting over a header while the region scrolls and after it settles | Boundaries reveal mid-scroll, an existing hint survives the scroll, or disclosure fails to resume once scrolling stops. |
+| FR7 | Snapshot or assertion that header hover changes no other header or row treatment | Header hover over a sortable and a selectable header | Header hover changes background, label, cursor, width, or another control's state. |
+| FR8, AR1-AR3, AR6 | Existing keyboard and ARIA suites and a coarse-primary keyboard case; `useTableColumnResize.test.tsx` "the handle never adds to its column header's name (AR1)" and `TableColumnResizeName.a11y.chromium.spec.ts` "a resize handle never adds to its column header name"; an assistive-technology spot check is recommended follow-up | Tab to boundary, arrow resize, screen-reader navigation of the header, coarse-primary device with a keyboard | The boundary leaves tab order on any input that can operate it, loses its name or values, or the hint reaches the accessibility tree. |
+| PR1, PR2 | Render-count assertion around header pointer enter/leave and during a scroll; listener and observer inspection | Pointer enters and leaves the header repeatedly; the region scrolls under a resting pointer | Disclosure rerenders the Table, the scroll gate sets React state, more than one scroll listener or any timer is added, or the extent measurement observes what it resizes. |
+| Plugin composition | Test mounting the resize and sticky-columns plugins together in both insertion orders | Pinned start column with resize enabled, before and after a drag | A pinned column loses `position: sticky` in either order, or the composition depends on caller insertion order. |
+| Record shape | `scripts/check-knowledge.mjs` | Colocated module record, canonical id and filename, parent backlink | A missing, misnamed, mis-parented, or unlinked record passes validation. |
Browser, render-count, and assistive-technology evidence are pending. Passing this
specification pull request proves record integrity only.
diff --git a/packages/core/src/Table/BaseTable.tsx b/packages/core/src/Table/BaseTable.tsx
index 0152c40dfa..6ebdae6959 100644
--- a/packages/core/src/Table/BaseTable.tsx
+++ b/packages/core/src/Table/BaseTable.tsx
@@ -14,7 +14,14 @@
* - /packages/cli/assets/templates/blocks/components/Table/ (showcase blocks)
*/
-import {memo, useRef, type ReactElement, type ReactNode, type Ref} from 'react';
+import {
+ memo,
+ useId,
+ useRef,
+ type ReactElement,
+ type ReactNode,
+ type Ref,
+} from 'react';
import {isRenderable} from '../utils/isRenderable';
import * as stylex from '@stylexjs/stylex';
import {spacingVars} from '../theme/tokens.stylex';
@@ -423,6 +430,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
} satisfies TableRenderProps);
// --- Plugin pipeline: header cells ---
+ const headerLabelIdBase = useId();
const headerCells = resolvedColumns.map((col, columnIndex) => {
const headerContent = col.header ?? col.key;
@@ -477,28 +485,54 @@ function BaseTableInner<T extends Record<string, unknown>>({
const hasSlots =
before != null || after != null || overlay != null || below != null;
- const headerInner = hasSlots ? (
+ const labelRow = isRenderable(after) ? (
+ <div {...stylex.props(styles.headerLabelRow)}>
+ {resolvedContent}
+ {after}
+ </div>
+ ) : (
+ resolvedContent
+ );
+
+ // The overlay is a control of its own. Keep its name and value out of the
+ // header's name.
+ const namesOwnHeader =
+ isRenderable(overlay) &&
+ mergedHtmlProps['aria-label'] == null &&
+ mergedHtmlProps['aria-labelledby'] == null;
+ const labelId = `${headerLabelIdBase}-label-${columnIndex}`;
+ const belowId = `${headerLabelIdBase}-below-${columnIndex}`;
+ const hasBelow = isRenderable(below);
+
+ const headerInner = !hasSlots ? (
+ resolvedContent
+ ) : namesOwnHeader ? (
+ <>
+ {/* Inline, so the cell's text-overflow still reaches the label. */}
+ <span id={labelId}>
+ {before}
+ {labelRow}
+ </span>
+ {overlay}
+ {hasBelow && <div id={belowId}>{below}</div>}
+ </>
+ ) : (
<>
{before}
- {isRenderable(after) ? (
- <div {...stylex.props(styles.headerLabelRow)}>
- {resolvedContent}
- {after}
- </div>
- ) : (
- resolvedContent
- )}
+ {labelRow}
{overlay}
{below}
</>
- ) : (
- resolvedContent
);
+ const headerNameProps = namesOwnHeader
+ ? {'aria-labelledby': hasBelow ? `${labelId} ${belowId}` : labelId}
+ : {};
return (
<HeaderCellComponent
key={col.key}
{...mergedHtmlProps}
+ {...headerNameProps}
{...headerTitleProp}
contextMenuActions={cellRenderProps.contextMenuActions}
xstyle={cellRenderProps.xstyle}>
diff --git a/packages/core/src/Table/__tests__/TableColumnResizeName.a11y.chromium.spec.ts b/packages/core/src/Table/__tests__/TableColumnResizeName.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..785a04d74b
--- /dev/null
+++ b/packages/core/src/Table/__tests__/TableColumnResizeName.a11y.chromium.spec.ts
@@ -0,0 +1,55 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(packages/core/src/Table/|apps/storybook/stories/TableColumnResize\.stories)
+
+/**
+ * @file TableColumnResizeName.a11y.chromium.spec.ts
+ * @input Storybook story core-tablecolumnresize--default
+ * @output Chromium's own accessibility tree for each column header in a table
+ * with resize handles: the header is named by its text, and the handle's
+ * name and width value never join it.
+ * @position Real-browser check: name-from-content of a focusable separator
+ * differs between engines and jsdom.
+ */
+
+import {expect, test} from '@playwright/test';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+test('a resize handle never adds to its column header name', async ({page}) => {
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=core-tablecolumnresize--default&viewMode=story`,
+ {waitUntil: 'load'},
+ );
+ await expect(page.getByRole('separator').first()).toBeAttached();
+
+ const cdp = await page.context().newCDPSession(page);
+ const {nodes} = (await cdp.send('Accessibility.getFullAXTree')) as {
+ nodes: {role?: {value?: string}; name?: {value?: string}}[];
+ };
+ const headerNames = nodes
+ .filter(node => node.role?.value === 'columnheader')
+ .map(node => node.name?.value ?? '');
+ const visibleTexts = await page
+ .getByRole('columnheader')
+ .evaluateAll(cells =>
+ cells.map(cell => (cell as HTMLElement).innerText.trim()),
+ );
+
+ expect(headerNames.length).toBeGreaterThan(0);
+ expect(headerNames).toEqual(visibleTexts);
+});
diff --git a/packages/core/src/Table/plugins/columnResize/useTableColumnResize.test.tsx b/packages/core/src/Table/plugins/columnResize/useTableColumnResize.test.tsx
index 8df9312c00..694bfa4af4 100644
--- a/packages/core/src/Table/plugins/columnResize/useTableColumnResize.test.tsx
+++ b/packages/core/src/Table/plugins/columnResize/useTableColumnResize.test.tsx
@@ -596,6 +596,21 @@ describe('useTableColumnResize', () => {
expect(role).toHaveAttribute('aria-label', 'Resize column role');
});
+ it("the handle never adds to its column header's name (AR1)", () => {
+ render(<ResizeTable />);
+ const headers = screen.getAllByRole('columnheader');
+ // Named by its text alone: no handle name, no width value.
+ expect(headers[0]).toHaveAccessibleName('Name');
+ for (const header of headers) {
+ expect(header.textContent).not.toBe('');
+ expect(header).not.toHaveAccessibleName(/Resize column|\d{2,}/);
+ }
+ // The label stays inline, so the cell's ellipsis still reaches it.
+ const labelId = headers[0].getAttribute('aria-labelledby')?.split(' ')[0];
+ expect(labelId).toBeDefined();
+ expect(document.getElementById(labelId ?? '')?.tagName).toBe('SPAN');
+ });
+
it('handle has aria-valuemin', () => {
render(<ResizeTable minWidth={80} />);
const handle = getResizeHandles()[0];