Skip to content

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

TypeScript

fix(Table): an unbounded column's resize handle announces a range that holds its width (#10577)

Cindy Zhang7f04a6c5a92f
diff --git a/.changeset/table-resize-separator-range.md b/.changeset/table-resize-separator-range.md
new file mode 100644
index 0000000000..60066e3b86
--- /dev/null
+++ b/.changeset/table-resize-separator-range.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] A Table column-resize handle on a column with no maximum width now announces a maximum at or above its value, so a screen reader no longer reads the width past ARIA's default maximum of 100. It uses the window's width as the stand-in maximum, as an unbounded Resizable region does, and announces its value in words, for example "133 pixels". Until a column is first resized, that value is still its minimum width. A column with `maxWidth` is unchanged.
+
+@cixzhang
diff --git a/docs/specs/components/Table/plugins/columnResize/useTableColumnResize.spec.md b/docs/specs/components/Table/plugins/columnResize/useTableColumnResize.spec.md
index 01bfbf422f..6124b304a1 100644
--- a/docs/specs/components/Table/plugins/columnResize/useTableColumnResize.spec.md
+++ b/docs/specs/components/Table/plugins/columnResize/useTableColumnResize.spec.md
@@ -14,6 +14,7 @@ verified_by:
[
packages/core/src/Table/plugins/columnResize/useTableColumnResize.test.tsx,
packages/core/src/Table/__tests__/TableColumnResizeName.a11y.chromium.spec.ts,
+ packages/core/src/Table/__tests__/TableColumnResizeRange.a11y.chromium.spec.ts,
scripts/check-knowledge.mjs,
]
parent_component: component:Table
@@ -55,8 +56,11 @@ Both are defects to correct there, not variations this record allows.
pointers, and every width outcome.
- Compatibility class: presentation-only change to one transient state, plus one
accessibility correction that adds a control where keyboard resize was already
- promised. No public API, prop, export, target, or accessibility mapping is added
- or changed.
+ promised. No public API, prop, export, or target is added or changed. One
+ accessibility correction changes the announced range: a column with no
+ maximum width announces a stand-in maximum and its value in words (AR7),
+ where it announced no maximum, so assistive technology fell back to a
+ maximum of 100.
- Migration decision: none. No consumer edit and no codemod.
This specification-only change carries no package Changeset. The implementation
@@ -160,7 +164,7 @@ 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. Its
+ orientation, accessible name naming its column, and value bounds (AR7). 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
@@ -177,6 +181,16 @@ remain in `useTableColumnResize.doc.mjs`.
- **AR6 — Parity across inputs.** The tab stop does not depend on primary pointer
capability. A device whose primary pointer is coarse but which has a keyboard
keeps the boundary control, its name, and its values (FR6, DEC-3).
+- **AR7 — A range that holds the value.** A boundary's announced maximum is
+ never below its value or its minimum (`spec:AST-020` FR1). A column with a
+ maximum width announces that maximum. A column with none announces the
+ window's inline extent, floored at its value and minimum, as an unbounded
+ Resizable region does, from the same shared measurement; the column is never
+ clamped to it. Because that maximum stands in for a missing limit, such a
+ boundary also announces its value in words ("133 pixels"). The server
+ render, which has no window, carries no maximum until hydration reads it.
+ Until a column is first resized, its value is its minimum width (a known
+ gap).
## Design relationships
@@ -238,6 +252,7 @@ without a target of its own.
| 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. |
+| AR7 | `useTableColumnResize.test.tsx` "an unbounded column announces a finite maximum, never below its value, and its width in words" and "handle has aria-valuemax when finite"; `TableColumnResizeRange.a11y.chromium.spec.ts` in Chromium's accessibility tree | A column with no maximum width; one with `maxWidth` | A missing or non-finite maximum, a maximum below the value or the minimum, missing value text on an unbounded column, or value text on a bounded one fails. |
| 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. |
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 96937bc86c..6233d0e778 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -1039,6 +1039,10 @@
"defaultMessage": "Resize column {label}",
"description": "Accessible name for a Table column-resize handle (a vertical separator between header cells). `label` is the column header's visible text, or the column key when the header has no text."
},
+ "@astryx.table.columnResize.widthValue": {
+ "defaultMessage": "{width, number} {width, plural, one {pixel} other {pixels}}",
+ "description": "Value a screen reader announces for a Table column-resize handle when the column has no maximum width. `width` is the column's current value as a whole number of CSS pixels, for example \"133 pixels\"."
+ },
"@astryx.table.filter.allPlaceholder": {
"defaultMessage": "All",
"description": "Placeholder on a per-column filter dropdown when nothing is selected, meaning \"no filter — all rows match\". Determiner form (as in \"all values\"), not the pronoun."
diff --git a/packages/core/src/Resizable/createResizable.ts b/packages/core/src/Resizable/createResizable.ts
index 70284a88be..b138718226 100644
--- a/packages/core/src/Resizable/createResizable.ts
+++ b/packages/core/src/Resizable/createResizable.ts
@@ -15,6 +15,7 @@
import {registerEnglishFallback} from '../i18n/englishFallback';
import english from '../i18n/generated-english/Resizable/createResizable.generated';
import {observeResize} from '../utils/sharedResizeObserver';
+import {readWindowExtent, standInMaximum} from '../utils/windowExtent';
import {createDevWarnings, devWarn} from '../utils/devWarning';
import {project} from '../motion/projection';
import {
@@ -178,14 +179,6 @@ function readViewportBasis(): number {
return typeof window === 'undefined' ? SERVER_BASIS : window.innerWidth;
}
-/** The window's extent along the axis, for an unbounded region's maximum. */
-function readWindowExtent(direction: ResizableDirection): number | null {
- if (typeof window === 'undefined') {
- return null;
- }
- return direction === 'vertical' ? window.innerHeight : window.innerWidth;
-}
-
/** The factory warns. This first-render read does not. */
const QUIET = null;
@@ -279,9 +272,7 @@ export function readInitialResizableState(
effectiveMaxPx:
max !== Infinity
? max
- : windowExtent == null
- ? undefined
- : Math.max(windowExtent, isCollapsed ? min : size),
+ : standInMaximum(windowExtent, isCollapsed ? min : size, min),
};
}
@@ -697,9 +688,7 @@ export function createResizableAs(
const effectiveMax =
max !== Infinity
? max
- : measuredForMax == null
- ? undefined
- : Math.max(measuredForMax, isCollapsed ? min : size);
+ : standInMaximum(measuredForMax, isCollapsed ? min : size, min);
derived = {size, isCollapsed, min, max, effectiveMax, isBasisMeasured};
}
diff --git a/packages/core/src/Table/__tests__/TableColumnResizeRange.a11y.chromium.spec.ts b/packages/core/src/Table/__tests__/TableColumnResizeRange.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..e8be8e32c0
--- /dev/null
+++ b/packages/core/src/Table/__tests__/TableColumnResizeRange.a11y.chromium.spec.ts
@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(packages/core/src/Table/|apps/storybook/stories/TableColumnResize\.stories)
+
+/**
+ * @file TableColumnResizeRange.a11y.chromium.spec.ts
+ * @input Storybook story core-tablecolumnresize--default, whose columns have
+ * no maximum width
+ * @output Chromium's own accessibility tree for each resize handle: a
+ * maximum at or above its value and its minimum, and the width in words.
+ * @position Real-browser check of the separator range assistive technology
+ * reads; jsdom has no accessibility tree.
+ */
+
+import {expect, test} from '@astryxdesign/a11y-spec/playwright';
+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();
+});
+
+type AXValue = {value?: string | number | boolean};
+type AXNode = {
+ role?: AXValue;
+ value?: AXValue;
+ properties?: {name: string; value?: AXValue}[];
+};
+
+function axProperty(node: AXNode, name: string): string | number | undefined {
+ const value = node.properties?.find(entry => entry.name === name)?.value
+ ?.value;
+ return typeof value === 'boolean' ? undefined : value;
+}
+
+test('an unbounded column handle announces a range that holds its value', 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: AXNode[];
+ };
+ const separators = nodes.filter(node => node.role?.value === 'separator');
+ expect(separators.length).toBeGreaterThan(0);
+ for (const node of separators) {
+ const now = Number(node.value?.value);
+ const min = Number(axProperty(node, 'valuemin'));
+ const max = Number(axProperty(node, 'valuemax'));
+ expect(Number.isFinite(max)).toBe(true);
+ expect(max).toBeGreaterThanOrEqual(now);
+ expect(max).toBeGreaterThanOrEqual(min);
+ // The width in words, since the maximum stands in for a missing limit.
+ expect(axProperty(node, 'valuetext')).toBe(`${now} pixels`);
+ }
+});
diff --git a/packages/core/src/Table/plugins/columnResize/useTableColumnResize.test.tsx b/packages/core/src/Table/plugins/columnResize/useTableColumnResize.test.tsx
index 8e567d9b08..e6e7f909a4 100644
--- a/packages/core/src/Table/plugins/columnResize/useTableColumnResize.test.tsx
+++ b/packages/core/src/Table/plugins/columnResize/useTableColumnResize.test.tsx
@@ -621,6 +621,30 @@ describe('useTableColumnResize', () => {
render(<ResizeTable maxWidth={500} />);
const handle = getResizeHandles()[0];
expect(handle).toHaveAttribute('aria-valuemax', '500');
+ // A real maximum needs no stand-in, so no value text either.
+ expect(handle).not.toHaveAttribute('aria-valuetext');
+ });
+
+ it('an unbounded column announces a finite maximum, never below its value, and its width in words', () => {
+ render(<ResizeTable />);
+ for (const handle of getResizeHandles()) {
+ const now = Number(handle.getAttribute('aria-valuenow'));
+ const min = Number(handle.getAttribute('aria-valuemin'));
+ // ARIA's default maximum is 100, which a column wider than 100px
+ // would read past.
+ expect(handle).toHaveAttribute('aria-valuemax');
+ const max = Number(handle.getAttribute('aria-valuemax'));
+ expect(Number.isFinite(max)).toBe(true);
+ expect(max).toBeGreaterThanOrEqual(now);
+ expect(max).toBeGreaterThanOrEqual(min);
+ expect(handle).toHaveAttribute('aria-valuetext', `${now} pixels`);
+ }
+ });
+
+ it('says a fractional width as a whole number of pixels', () => {
+ render(<ResizeTable columnWidths={{name: 202.656}} />);
+ const handle = getResizeHandles()[0];
+ expect(handle).toHaveAttribute('aria-valuetext', '203 pixels');
});
});
diff --git a/packages/core/src/Table/plugins/columnResize/useTableColumnResize.tsx b/packages/core/src/Table/plugins/columnResize/useTableColumnResize.tsx
index 40f92efb91..4999f9e276 100644
--- a/packages/core/src/Table/plugins/columnResize/useTableColumnResize.tsx
+++ b/packages/core/src/Table/plugins/columnResize/useTableColumnResize.tsx
@@ -13,7 +13,14 @@
* - /packages/core/src/Table/index.ts (exports)
*/
-import {useRef, useMemo, useCallback, useEffect, type ReactNode} from 'react';
+import {
+ useRef,
+ useMemo,
+ useCallback,
+ useEffect,
+ useSyncExternalStore,
+ type ReactNode,
+} from 'react';
import {useIsomorphicLayoutEffect} from '../../../hooks/useIsomorphicLayoutEffect';
import * as stylex from '@stylexjs/stylex';
import {colorVars} from '../../../theme/tokens.stylex';
@@ -30,6 +37,12 @@ import {
DEFAULT_MIN_COLUMN_WIDTH,
} from '../../columnUtils';
import {observeResize} from '../../../utils/sharedResizeObserver';
+import {
+ readNoWindowWidth,
+ readWindowWidth,
+ standInMaximum,
+ subscribeToWindowWidth,
+} from '../../../utils/windowExtent';
import {getNodeText} from '../../../utils/getNodeText';
import {
registerEnglishFallback,
@@ -367,6 +380,20 @@ interface DragState {
// Resize Handle Component
// =============================================================================
+/**
+ * The window's inline extent, which a column with no maximum announces as its
+ * maximum, as an unbounded Resizable region does. Every handle shares one
+ * store and one listener, and render reads the stored width. The server has
+ * no window, so it renders none, and hydration then reads it.
+ */
+function useWindowInlineExtent(): number | null {
+ return useSyncExternalStore(
+ subscribeToWindowWidth,
+ readWindowWidth,
+ readNoWindowWidth,
+ );
+}
+
interface ResizeHandleProps {
columnKey: string;
columnHeader: ReactNode;
@@ -759,15 +786,30 @@ function ResizeHandle({
label: getNodeText(columnHeader) || columnKey,
});
+ // A focusable role="separator" requires a numeric aria-valuenow, so fall
+ // back to the column's minWidth before the width has been measured.
+ const valueNow = currentWidth ?? minWidth;
+ // Without a maximum, ARIA's default of 100 applies, below most column
+ // widths. So an unbounded column announces a stand-in maximum that it never
+ // goes below. That range is not a real limit, so the handle also says its
+ // value in words.
+ const isUnbounded = !Number.isFinite(maxWidth);
+ const windowExtent = useWindowInlineExtent();
+ const announcedMax = isUnbounded
+ ? standInMaximum(windowExtent, valueNow, minWidth)
+ : maxWidth;
+ const valueText = isUnbounded
+ ? t('@astryx.table.columnResize.widthValue', {width: Math.round(valueNow)})
+ : undefined;
+
return (
<div
role="separator"
aria-orientation="vertical"
- // A focusable role="separator" requires a numeric aria-valuenow, so fall
- // back to the column's minWidth before the width has been measured.
- aria-valuenow={currentWidth ?? minWidth}
+ aria-valuenow={valueNow}
aria-valuemin={minWidth}
- aria-valuemax={maxWidth === Infinity ? undefined : maxWidth}
+ aria-valuemax={announcedMax}
+ aria-valuetext={valueText}
aria-label={ariaLabel}
tabIndex={0}
// Lets the height observer find its own handles without matching any
diff --git a/packages/core/src/utils/windowExtent.test.ts b/packages/core/src/utils/windowExtent.test.ts
new file mode 100644
index 0000000000..624272320a
--- /dev/null
+++ b/packages/core/src/utils/windowExtent.test.ts
@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file windowExtent.test.ts
+ * @input The shared window-width store and the stand-in maximum
+ * @output One root observation for every subscriber, a stored width that
+ * follows it, and a maximum never below the value or the minimum
+ * @position Colocated verification for utils/windowExtent
+ */
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {
+ readWindowWidth,
+ standInMaximum,
+ subscribeToWindowWidth,
+} from './windowExtent';
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('windowExtent', () => {
+ it('listens to no window resize event, and reads innerWidth once per observation report', () => {
+ const add = vi.spyOn(window, 'addEventListener');
+ const width = vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(640);
+ const stops = [vi.fn(), vi.fn(), vi.fn()].map(listener =>
+ subscribeToWindowWidth(listener),
+ );
+ expect(add.mock.calls.filter(([type]) => type === 'resize')).toHaveLength(
+ 0,
+ );
+ // The shared observation reports once when it starts; every subscriber
+ // shares that one report.
+ expect(width).toHaveBeenCalledTimes(1);
+ expect(readWindowWidth()).toBe(640);
+ window.dispatchEvent(new Event('resize'));
+ readWindowWidth();
+ expect(width).toHaveBeenCalledTimes(1);
+ for (const stop of stops) {
+ stop();
+ }
+ });
+
+ it('never states a maximum below the value or the minimum', () => {
+ expect(standInMaximum(1280, 250, 60)).toBe(1280);
+ expect(standInMaximum(300, 420, 60)).toBe(420);
+ expect(standInMaximum(40, 20, 60)).toBe(60);
+ expect(standInMaximum(null, 250, 60)).toBeUndefined();
+ });
+});
diff --git a/packages/core/src/utils/windowExtent.ts b/packages/core/src/utils/windowExtent.ts
new file mode 100644
index 0000000000..8eb6f747bf
--- /dev/null
+++ b/packages/core/src/utils/windowExtent.ts
@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file windowExtent.ts
+ * @input The window's innerWidth and innerHeight, and the shared resize
+ * observer on the root element
+ * @output readWindowExtent, standInMaximum, and a shared window-width store
+ * (subscribeToWindowWidth, readWindowWidth, readNoWindowWidth) for
+ * useSyncExternalStore
+ * @position Internal shared measurement, not re-exported from the utils
+ * entry. Resizable and Table's column resize read it for the maximum an
+ * unbounded separator announces.
+ */
+
+import {observeResize} from './sharedResizeObserver';
+
+/** The window's extent along an axis, or null where there is no window. */
+export function readWindowExtent(
+ direction: 'horizontal' | 'vertical',
+): number | null {
+ if (typeof window === 'undefined') {
+ return null;
+ }
+ return direction === 'vertical' ? window.innerHeight : window.innerWidth;
+}
+
+/**
+ * The maximum an unbounded separator announces: the measured extent, never
+ * below the value it announces or its minimum. Undefined with no extent, so
+ * the separator renders no maximum.
+ */
+export function standInMaximum(
+ extent: number | null,
+ value: number,
+ min: number,
+): number | undefined {
+ return extent == null ? undefined : Math.max(extent, value, min);
+}
+
+// The window's width, as the shared resize observer on the root element last
+// reported it. A render reads this value, never `innerWidth`: after a
+// commit's DOM writes, that read forces a layout. Every subscriber shares one
+// observation. With none, the value is null, because nothing keeps it current.
+let windowWidth: number | null = null;
+const windowWidthListeners = new Set<() => void>();
+let stopObserving: (() => void) | null = null;
+
+// The observer reports after layout, so reading the width here forces none.
+function handleRootResize(): void {
+ windowWidth = window.innerWidth;
+ for (const listener of windowWidthListeners) {
+ listener();
+ }
+}
+
+/** Subscribes to the window's width, for `useSyncExternalStore`. */
+export function subscribeToWindowWidth(onChange: () => void): () => void {
+ windowWidthListeners.add(onChange);
+ // The observation reports once at once, so a resize between the first
+ // render and this subscription still reaches the store.
+ stopObserving ??= observeResize(document.documentElement, handleRootResize);
+ return () => {
+ windowWidthListeners.delete(onChange);
+ if (windowWidthListeners.size === 0) {
+ stopObserving?.();
+ stopObserving = null;
+ windowWidth = null;
+ }
+ };
+}
+
+/** The window's width from the shared store; one read when none is held. */
+export function readWindowWidth(): number {
+ windowWidth ??= window.innerWidth;
+ return windowWidth;
+}
+
+/** The server's snapshot: no window, so no width. */
+export function readNoWindowWidth(): null {
+ return null;
+}