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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/docs/specs/components/Table/plugins/columnResize/useTableColumnResize.spec.md b/docs/specs/components/Table/plugins/columnResize/useTableColumnResize.spec.mdindex 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 oneaccessibility 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). Itsresize handle sits in the `overlay` slot, so it doesn't join the header'sname (`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 pointercapability. A device whose primary pointer is coarse but which has a keyboardkeeps 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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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 (<divrole="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 anydiff --git a/packages/core/src/utils/windowExtent.test.ts b/packages/core/src/utils/windowExtent.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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;+}