Skip to content

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

TypeScript

fix(core): collections ARIA minors — Resizable collapsed value, TabMenu radio semantics (#4378)

Baraa Hamodia16b310dcd67
diff --git a/.changeset/a11y-collections-minors.md b/.changeset/a11y-collections-minors.md
new file mode 100644
index 0000000000..c7bfc39bf2
--- /dev/null
+++ b/.changeset/a11y-collections-minors.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Resizable, TabMenu: two collection ARIA minors (WCAG 4.1.2) — Resizable's collapsed handle clamps `aria-valuenow` to `aria-valuemin` and announces a localized "Collapsed" via `aria-valuetext`, and TabMenu overflow options are `menuitemradio` with `aria-checked` (APG menu-button single-select) instead of `menuitem` + `aria-current`.
+@bhamodi
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 31eb1c6bb4..a2d9f2092e 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -655,6 +655,10 @@
"defaultMessage": "Search…",
"description": "Grey placeholder text inside the empty PowerSearch input. Imperative verb; trailing `…` is one character."
},
+ "@astryx.resizable.collapsed": {
+ "defaultMessage": "Collapsed",
+ "description": "aria-valuetext for the Resizable drag handle (role=separator) while its panel is collapsed to zero size. Replaces the numeric value announcement, since the numeric value is clamped to the minimum while collapsed. Adjective describing the panel state, not a verb/command."
+ },
"@astryx.resizable.handle.label": {
"defaultMessage": "Resize handle",
"description": "Screen-reader-only accessible name for the small draggable divider between two Resizable panels (users drag it to change the split ratio)."
diff --git a/packages/core/src/Resizable/ResizeHandle.test.tsx b/packages/core/src/Resizable/ResizeHandle.test.tsx
index a60ee10c22..30d69b7817 100644
--- a/packages/core/src/Resizable/ResizeHandle.test.tsx
+++ b/packages/core/src/Resizable/ResizeHandle.test.tsx
@@ -150,7 +150,55 @@ describe('ResizeHandle', () => {
const separator = getSeparator();
act(() => separator.focus());
fireEvent.keyDown(separator, {key: 'Enter'});
- expect(separator).toHaveAttribute('aria-valuenow', '0');
+ // The panel's real size is 0, but aria-valuenow must never drop below
+ // aria-valuemin (WCAG 4.1.2) — it clamps to the minimum and the state
+ // is announced via aria-valuetext instead.
+ expect(separator).toHaveAttribute('aria-valuenow', '100');
+ expect(separator).toHaveAttribute('aria-valuetext', 'Collapsed');
+ });
+
+ it('keeps aria-valuenow >= aria-valuemin and announces "Collapsed" while collapsed', () => {
+ render(
+ <Harness
+ config={{
+ defaultSize: 200,
+ minSizePx: 100,
+ maxSizePx: 400,
+ collapsible: true,
+ }}
+ />,
+ );
+ const separator = getSeparator();
+ act(() => separator.focus());
+ fireEvent.keyDown(separator, {key: 'Enter'});
+
+ const valueNow = Number(separator.getAttribute('aria-valuenow'));
+ const valueMin = Number(separator.getAttribute('aria-valuemin'));
+ expect(valueNow).toBeGreaterThanOrEqual(valueMin);
+ expect(separator).toHaveAttribute('aria-valuetext', 'Collapsed');
+ });
+
+ it('removes aria-valuetext when the panel is expanded', () => {
+ render(
+ <Harness
+ config={{
+ defaultSize: 200,
+ minSizePx: 100,
+ maxSizePx: 400,
+ collapsible: true,
+ }}
+ />,
+ );
+ const separator = getSeparator();
+ expect(separator).not.toHaveAttribute('aria-valuetext');
+
+ act(() => separator.focus());
+ fireEvent.keyDown(separator, {key: 'Enter'}); // collapse
+ expect(separator).toHaveAttribute('aria-valuetext', 'Collapsed');
+
+ fireEvent.keyDown(separator, {key: 'Enter'}); // expand again
+ expect(separator).not.toHaveAttribute('aria-valuetext');
+ expect(separator).toHaveAttribute('aria-valuenow', '100');
});
// --- Disabled guard ---
diff --git a/packages/core/src/Resizable/ResizeHandle.tsx b/packages/core/src/Resizable/ResizeHandle.tsx
index 9143e5f161..c15cc678cc 100644
--- a/packages/core/src/Resizable/ResizeHandle.tsx
+++ b/packages/core/src/Resizable/ResizeHandle.tsx
@@ -17,6 +17,10 @@
* Pill placement uses a single stylex dynamic style that accepts a direction
* multiplier (-1 or 1). The pill element has its own themeProps
* ('resize-handle-pill') so themes can target size/shape directly.
+ *
+ * While the panel is collapsed, aria-valuenow is clamped to aria-valuemin
+ * (a value below the minimum is invalid per WCAG 4.1.2) and a localized
+ * "Collapsed" aria-valuetext announces the real state.
*/
import {useCallback, useEffect, useRef, useState} from 'react';
@@ -514,12 +518,23 @@ export function ResizeHandle({
}, []);
// --- ARIA ---
- const ariaValueNow = resizable ? resizable._size : undefined;
+ // When collapsed the panel's real size (0) sits below aria-valuemin, which
+ // is invalid per WCAG 4.1.2. Clamp aria-valuenow to the minimum and announce
+ // the true state via aria-valuetext instead; the valuetext is removed as
+ // soon as the panel expands so the numeric value reads again.
+ const isCollapsed = resizable?._isCollapsed ?? false;
+ const ariaValueNow = resizable
+ ? isCollapsed
+ ? Math.max(resizable._size, resizable._minSizePx)
+ : resizable._size
+ : undefined;
const ariaValueMin = resizable ? resizable._minSizePx : undefined;
const ariaValueMax =
resizable && resizable._maxSizePx !== Infinity
? resizable._maxSizePx
: undefined;
+ const ariaValueText =
+ resizable && isCollapsed ? t('@astryx.resizable.collapsed') : undefined;
return (
<div
@@ -529,6 +544,7 @@ export function ResizeHandle({
aria-valuenow={ariaValueNow}
aria-valuemin={ariaValueMin}
aria-valuemax={ariaValueMax}
+ aria-valuetext={ariaValueText}
aria-label={label}
aria-disabled={isDisabled || undefined}
tabIndex={isDisabled ? -1 : 0}
diff --git a/packages/core/src/TabList/TabList.test.tsx b/packages/core/src/TabList/TabList.test.tsx
index 1a06ff3b89..b14bcb1771 100644
--- a/packages/core/src/TabList/TabList.test.tsx
+++ b/packages/core/src/TabList/TabList.test.tsx
@@ -687,10 +687,10 @@ describe('TabMenu', () => {
// Menu items are rendered in DOM (popover controls visibility, hidden from a11y tree)
expect(
- screen.getByRole('menuitem', {name: 'Analytics', hidden: true}),
+ screen.getByRole('menuitemradio', {name: 'Analytics', hidden: true}),
).toBeInTheDocument();
expect(
- screen.getByRole('menuitem', {name: 'Reports', hidden: true}),
+ screen.getByRole('menuitemradio', {name: 'Reports', hidden: true}),
).toBeInTheDocument();
});
@@ -726,7 +726,7 @@ describe('TabMenu', () => {
await user.click(screen.getByRole('button', {name: /More/}));
// Click the menu item (popover content, hidden from a11y tree in jsdom)
- const menuItem = screen.getByRole('menuitem', {
+ const menuItem = screen.getByRole('menuitemradio', {
name: 'Analytics',
hidden: true,
});
@@ -734,7 +734,7 @@ describe('TabMenu', () => {
expect(handleChange).toHaveBeenCalledWith('analytics');
});
- it('marks menu item as selected with aria-current', () => {
+ it('exposes options as menuitemradio and marks the selected tab aria-checked', () => {
render(
<TabList value="analytics" onChange={() => {}}>
<Tab value="home" label="Home" />
@@ -742,18 +742,21 @@ describe('TabMenu', () => {
</TabList>,
);
- // Menu items are in DOM (popover content, hidden from a11y tree in jsdom)
- const analyticsItem = screen.getByRole('menuitem', {
+ // Menu items are in DOM (popover content, hidden from a11y tree in jsdom).
+ // Single-select menu options carry radio semantics (APG menu-button):
+ // role="menuitemradio" + aria-checked, not menuitem + aria-current.
+ const analyticsItem = screen.getByRole('menuitemradio', {
name: 'Analytics',
hidden: true,
});
- expect(analyticsItem).toHaveAttribute('aria-current', 'true');
+ expect(analyticsItem).toHaveAttribute('aria-checked', 'true');
+ expect(analyticsItem).not.toHaveAttribute('aria-current');
- const reportsItem = screen.getByRole('menuitem', {
+ const reportsItem = screen.getByRole('menuitemradio', {
name: 'Reports',
hidden: true,
});
- expect(reportsItem).not.toHaveAttribute('aria-current');
+ expect(reportsItem).toHaveAttribute('aria-checked', 'false');
});
});
@@ -774,11 +777,11 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
await user.click(screen.getByRole('button', {name: /More/}));
- const analytics = screen.getByRole('menuitem', {
+ const analytics = screen.getByRole('menuitemradio', {
name: 'Analytics',
hidden: true,
});
- const reports = screen.getByRole('menuitem', {
+ const reports = screen.getByRole('menuitemradio', {
name: 'Reports',
hidden: true,
});
@@ -804,11 +807,11 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
await user.click(screen.getByRole('button', {name: /More/}));
const menu = screen.getByRole('menu', {hidden: true});
- const analytics = screen.getByRole('menuitem', {
+ const analytics = screen.getByRole('menuitemradio', {
name: 'Analytics',
hidden: true,
});
- const reports = screen.getByRole('menuitem', {
+ const reports = screen.getByRole('menuitemradio', {
name: 'Reports',
hidden: true,
});
@@ -834,11 +837,11 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
await user.click(screen.getByRole('button', {name: /More/}));
const menu = screen.getByRole('menu', {hidden: true});
- const analytics = screen.getByRole('menuitem', {
+ const analytics = screen.getByRole('menuitemradio', {
name: 'Analytics',
hidden: true,
});
- const reports = screen.getByRole('menuitem', {
+ const reports = screen.getByRole('menuitemradio', {
name: 'Reports',
hidden: true,
});
@@ -867,11 +870,11 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
await user.click(screen.getByRole('button', {name: /More/}));
const menu = screen.getByRole('menu', {hidden: true});
- const analytics = screen.getByRole('menuitem', {
+ const analytics = screen.getByRole('menuitemradio', {
name: 'Analytics',
hidden: true,
});
- const exports = screen.getByRole('menuitem', {
+ const exports = screen.getByRole('menuitemradio', {
name: 'Exports',
hidden: true,
});
@@ -894,7 +897,7 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
);
await user.click(screen.getByRole('button', {name: /More/}));
- const analytics = screen.getByRole('menuitem', {
+ const analytics = screen.getByRole('menuitemradio', {
name: 'Analytics',
hidden: true,
});
diff --git a/packages/core/src/TabList/TabMenu.tsx b/packages/core/src/TabList/TabMenu.tsx
index 7ea2ebc598..190c08688e 100644
--- a/packages/core/src/TabList/TabMenu.tsx
+++ b/packages/core/src/TabList/TabMenu.tsx
@@ -31,6 +31,7 @@ import {
typeScaleVars,
} from '../theme/tokens.stylex';
import {usePopover} from '../Popover/usePopover';
+import {MENU_ITEM_SELECTOR} from '../DropdownMenu/menuItemRoles';
import {useListFocus} from '../hooks/useListFocus';
import {useTabListContext} from './TabListContext';
import type {TabListSize} from './TabListContext';
@@ -291,6 +292,9 @@ export function TabMenu({
focusFirst,
} = useListFocus<HTMLDivElement>({
hasRovingTabIndex: true,
+ // Options render as menuitemradio (single-select menu), which the
+ // default '[role="menuitem"]' selector would not match.
+ itemSelector: MENU_ITEM_SELECTOR,
onEscape: () => popover.hide(),
});
@@ -409,9 +413,13 @@ export function TabMenu({
return (
<div
key={option.value}
- role="menuitem"
+ // The menu is single-select: exactly one option can be the
+ // active tab, so options are radio menu items with
+ // aria-checked (APG menu-button), not plain menuitems with
+ // aria-current.
+ role="menuitemradio"
tabIndex={-1}
- aria-current={isSelected ? 'true' : undefined}
+ aria-checked={isSelected}
onClick={() => handleSelect(option.value)}
onKeyDown={e => {
if (e.key === 'Enter' || e.key === ' ') {