Skip to content

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

TypeScript

fix(lab): add tab stops to scrollable regions (#4691)

AKea9983363399
diff --git a/.github/a11y-baseline.json b/.github/a11y-baseline.json
index cf7c81b031..bb75e38b8f 100644
--- a/.github/a11y-baseline.json
+++ b/.github/a11y-baseline.json
@@ -293,11 +293,6 @@
"impact": "serious",
"helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
},
- {
- "key": "CodeEditor::With Max Height::scrollable-region-focusable",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/scrollable-region-focusable?application=playwright"
- },
{
"key": "CodeEditor::With Placeholder::color-contrast",
"impact": "serious",
@@ -308,21 +303,11 @@
"impact": "serious",
"helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
},
- {
- "key": "CodeEditorPerf::Stress Test::scrollable-region-focusable",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/scrollable-region-focusable?application=playwright"
- },
{
"key": "CodeEditorPerf::Typing Latency::color-contrast",
"impact": "serious",
"helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
},
- {
- "key": "CodeEditorPerf::Typing Latency::scrollable-region-focusable",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/scrollable-region-focusable?application=playwright"
- },
{
"key": "CodeEditorTheme::All Themes Gallery::color-contrast",
"impact": "serious",
@@ -673,11 +658,6 @@
"impact": "serious",
"helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
},
- {
- "key": "Outline::Scroll Spy::scrollable-region-focusable",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/scrollable-region-focusable?application=playwright"
- },
{
"key": "OverflowList::With Badges::color-contrast",
"impact": "serious",
@@ -818,11 +798,6 @@
"impact": "serious",
"helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
},
- {
- "key": "Schedule::Monthly::scrollable-region-focusable",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/scrollable-region-focusable?application=playwright"
- },
{
"key": "Schedule::View Selector Plugin::color-contrast",
"impact": "serious",
@@ -873,11 +848,6 @@
"impact": "serious",
"helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
},
- {
- "key": "Stack::Scrollable::scrollable-region-focusable",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/scrollable-region-focusable?application=playwright"
- },
{
"key": "Stepper::Edge — Disabled Steps::color-contrast",
"impact": "serious",
diff --git a/apps/storybook/stories/Outline.stories.tsx b/apps/storybook/stories/Outline.stories.tsx
index 30a7cb2d52..1ad3acce78 100644
--- a/apps/storybook/stories/Outline.stories.tsx
+++ b/apps/storybook/stories/Outline.stories.tsx
@@ -312,6 +312,12 @@ export const ScrollSpy: Story = {
}}>
<div
ref={scrollContainerRef}
+ // The pane scrolls but contains nothing focusable, so it needs a
+ // tab stop and a name for keyboard scrolling (axe:
+ // scrollable-region-focusable).
+ tabIndex={0}
+ role="region"
+ aria-label="Article content"
style={{
overflowY: 'auto',
height: 360,
diff --git a/apps/storybook/stories/Stack.stories.tsx b/apps/storybook/stories/Stack.stories.tsx
index ba038cb7c6..fe478d3f0b 100644
--- a/apps/storybook/stories/Stack.stories.tsx
+++ b/apps/storybook/stories/Stack.stories.tsx
@@ -752,6 +752,12 @@ export const Scrollable: Story = {
padding: 2,
isScrollable: true,
height: 160,
+ // A scrollable stack of non-interactive content needs a tab stop and an
+ // accessible name so keyboard users can scroll it (axe:
+ // scrollable-region-focusable). Stack forwards these through BaseProps.
+ tabIndex: 0,
+ role: 'region',
+ 'aria-label': 'Scrollable stack',
},
render: args => (
<Stack {...args} xstyle={styles.container}>
diff --git a/packages/lab/src/CodeEditor/CodeEditor.test.tsx b/packages/lab/src/CodeEditor/CodeEditor.test.tsx
index 5423798c0e..90845669d3 100644
--- a/packages/lab/src/CodeEditor/CodeEditor.test.tsx
+++ b/packages/lab/src/CodeEditor/CodeEditor.test.tsx
@@ -188,4 +188,40 @@ describe('CodeEditor', () => {
expect(onChange).toHaveBeenCalledWith(' a;\nb;');
});
+
+ it('exposes an explicit tabindex so scrollable editors count as focusable content', () => {
+ // contenteditable is not on axe's natively-focusable whitelist, and axe
+ // reads the tabindex ATTRIBUTE (not the browser's effective tabIndex),
+ // so the scrollable editorContainer only passes scrollable-region-focusable
+ // when the <code> editor materializes tabindex="0" explicitly.
+ render(
+ <CodeEditor
+ value={Array.from({length: 30}, (_, i) => `line ${i + 1};`).join('\n')}
+ onChange={() => {}}
+ language="typescript"
+ label="Edit snippet"
+ maxHeight={200}
+ />,
+ );
+ expect(screen.getByRole('textbox', {name: 'Edit snippet'})).toHaveAttribute(
+ 'tabindex',
+ '0',
+ );
+ });
+
+ it('keeps read-only editors keyboard-focusable, like a readonly textarea', () => {
+ render(
+ <CodeEditor
+ value="const x = 1;"
+ onChange={() => {}}
+ language="typescript"
+ label="Edit snippet"
+ isReadOnly
+ />,
+ );
+ expect(screen.getByRole('textbox', {name: 'Edit snippet'})).toHaveAttribute(
+ 'tabindex',
+ '0',
+ );
+ });
});
diff --git a/packages/lab/src/CodeEditor/CodeEditor.tsx b/packages/lab/src/CodeEditor/CodeEditor.tsx
index bf37eb7fe0..02d1f8aebb 100644
--- a/packages/lab/src/CodeEditor/CodeEditor.tsx
+++ b/packages/lab/src/CodeEditor/CodeEditor.tsx
@@ -242,6 +242,9 @@ let editorInstanceCounter = 0;
* The escape is advertised to assistive technology via a visually hidden
* aria-describedby hint (see `escapeHint`).
*
+ * The editor carries an explicit tabindex="0" (including when read-only) so
+ * the scrollable container passes axe's scrollable-region-focusable check.
+ *
* @example
* ```
* const [code, setCode] = useState('');
@@ -575,6 +578,12 @@ export function CodeEditor({
ref={editorRef}
// eslint-disable-next-line @typescript-eslint/no-explicit-any
contentEditable={isReadOnly ? false : ('plaintext-only' as any)}
+ // Explicit tabindex: editing hosts have an effective tabIndex of 0
+ // already, but axe reads the attribute, and contenteditable is not
+ // on its natively-focusable whitelist — without it a maxHeight
+ // editor fails scrollable-region-focusable. Also keeps read-only
+ // editors keyboard-focusable, like a readonly textarea.
+ tabIndex={0}
role="textbox"
aria-multiline="true"
aria-label={label}
diff --git a/packages/lab/src/Schedule/MonthlyView.tsx b/packages/lab/src/Schedule/MonthlyView.tsx
index 4b586c55a3..d702e898ac 100644
--- a/packages/lab/src/Schedule/MonthlyView.tsx
+++ b/packages/lab/src/Schedule/MonthlyView.tsx
@@ -57,8 +57,16 @@ export interface ScheduleMonthlyViewOptions {
function ScheduleMonthlyView(
_props: ScheduleViewComponentProps<ScheduleMonthlyViewOptions>,
) {
- const {events, categories, date, focusDate, timezoneID, range, isLoading, headingLevel} =
- useScheduleContext();
+ const {
+ events,
+ categories,
+ date,
+ focusDate,
+ timezoneID,
+ range,
+ isLoading,
+ headingLevel,
+ } = useScheduleContext();
const rangeDate = date.toPlainDate();
const highlightedDate = focusDate.toPlainDate();
const currentTime = useCurrentTime();
@@ -76,6 +84,10 @@ function ScheduleMonthlyView(
role="grid"
aria-label={formatMonthTitle(rangeDate, timezoneID)}
aria-readonly
+ // The grid scrolls horizontally at narrow viewports and contains no
+ // focusable descendants, so it must be focusable itself for keyboard
+ // scrolling (axe: scrollable-region-focusable).
+ tabIndex={0}
{...stylex.props(styles.monthGrid)}>
<div role="row" {...stylex.props(styles.weekHeader)}>
{days.slice(0, 7).map((day, index) => (
diff --git a/packages/lab/src/Schedule/Schedule.test.tsx b/packages/lab/src/Schedule/Schedule.test.tsx
index b5646ab164..39c1c39e1b 100644
--- a/packages/lab/src/Schedule/Schedule.test.tsx
+++ b/packages/lab/src/Schedule/Schedule.test.tsx
@@ -114,9 +114,9 @@ describe('Schedule', () => {
await waitFor(() => {
expect(screen.getByText('Visible sync')).toBeInTheDocument();
});
- expect(
- screen.getAllByRole('heading', {level: 3}).length,
- ).toBeGreaterThan(0);
+ expect(screen.getAllByRole('heading', {level: 3}).length).toBeGreaterThan(
+ 0,
+ );
});
it('renders list day headings at the configured headingLevel (default 3)', async () => {
@@ -133,9 +133,9 @@ describe('Schedule', () => {
await waitFor(() => {
expect(screen.getByText('Visible sync')).toBeInTheDocument();
});
- expect(
- screen.getAllByRole('heading', {level: 3}).length,
- ).toBeGreaterThan(0);
+ expect(screen.getAllByRole('heading', {level: 3}).length).toBeGreaterThan(
+ 0,
+ );
});
it('loads async events with Instant range boundaries', async () => {
@@ -249,6 +249,27 @@ describe('Schedule', () => {
).toBeInTheDocument();
});
+ it('makes the scrollable monthly grid keyboard-focusable', () => {
+ // The month grid is a horizontal scroll container with no focusable
+ // descendants, so it needs tabindex="0" itself for
+ // scrollable-region-focusable to pass and for keyboard scrolling.
+ render(
+ <Schedule
+ view={createScheduleMonthlyView()}
+ events={events}
+ categories={categories}
+ date={Date.UTC(2026, 4, 13)}
+ focusDate={Date.UTC(2026, 4, 13)}
+ timezoneID="UTC"
+ />,
+ );
+
+ expect(screen.getByRole('grid', {name: 'May 2026'})).toHaveAttribute(
+ 'tabindex',
+ '0',
+ );
+ });
+
it('exposes time grid views as ARIA grids', () => {
render(
<Schedule