Skip to content

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

TypeScript

fix(scroll): keyboard-focusable scroll regions + CodeBlock copy/nesting (complex-6/7/8/18) (#3369)

Cindy Zhang77996c0c3057
diff --git a/.changeset/scrollable-region-focusable.md b/.changeset/scrollable-region-focusable.md
new file mode 100644
index 0000000000..35ed28dcd5
--- /dev/null
+++ b/.changeset/scrollable-region-focusable.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] CodeBlock/Table/Markdown: overflowing scroll regions are now keyboard-focusable (`tabIndex`, `role="region"`) so keyboard users can scroll long code and wide tables. CodeBlock's Copy button no longer collapses the block when clicked, and is no longer nested inside the collapsible header's `role="button"` (#3343).
+@cixzhang
diff --git a/packages/core/src/CodeBlock/CodeBlock.test.tsx b/packages/core/src/CodeBlock/CodeBlock.test.tsx
new file mode 100644
index 0000000000..8308285d78
--- /dev/null
+++ b/packages/core/src/CodeBlock/CodeBlock.test.tsx
@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CodeBlock.test.tsx
+ * @input Uses vitest, @testing-library/react, CodeBlock component
+ * @output Unit tests for CodeBlock (copy button, collapse, scroll region a11y)
+ * @position Testing; validates CodeBlock implementation
+ *
+ * SYNC: When CodeBlock.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {CodeBlock} from './CodeBlock';
+
+// A code sample long enough to exceed the default collapsible threshold (10).
+const LONG_CODE = Array.from(
+ {length: 15},
+ (_, i) => `const line${i} = ${i};`,
+).join('\n');
+
+describe('CodeBlock', () => {
+ beforeEach(() => {
+ // jsdom does not implement the async Clipboard API.
+ Object.assign(navigator, {
+ clipboard: {writeText: vi.fn().mockResolvedValue(undefined)},
+ });
+ });
+
+ it('renders the code', () => {
+ render(<CodeBlock code="const x = 1;" language="javascript" />);
+ expect(screen.getByText(/const/)).toBeInTheDocument();
+ });
+
+ it('makes the scroll container keyboard-focusable', () => {
+ render(<CodeBlock code="const x = 1;" language="javascript" />);
+ const region = screen.getByRole('region');
+ expect(region).toHaveAttribute('tabindex', '0');
+ expect(region).toHaveAttribute('aria-label', 'javascript');
+ });
+
+ it('labels the scroll region "Code" when no language label is shown', () => {
+ render(<CodeBlock code="hello" hasLanguageLabel={false} />);
+ const region = screen.getByRole('region');
+ expect(region).toHaveAttribute('tabindex', '0');
+ expect(region).toHaveAttribute('aria-label', 'Code');
+ });
+
+ it('copies code when the copy button is clicked', () => {
+ render(<CodeBlock code="const x = 1;" language="javascript" />);
+ const copyButton = screen.getByRole('button', {name: 'Copy code'});
+ fireEvent.click(copyButton);
+ expect(navigator.clipboard.writeText).toHaveBeenCalledWith('const x = 1;');
+ });
+
+ it('does NOT collapse the block when the copy button is clicked', () => {
+ render(
+ <CodeBlock
+ code={LONG_CODE}
+ language="javascript"
+ title="example"
+ isCollapsible
+ />,
+ );
+ // The collapsible header exposes aria-expanded.
+ const header = screen
+ .getAllByRole('button')
+ .find(el => el.hasAttribute('aria-expanded'));
+ expect(header).toBeTruthy();
+ expect(header).toHaveAttribute('aria-expanded', 'true');
+
+ const copyButton = screen.getByRole('button', {name: 'Copy code'});
+ fireEvent.click(copyButton);
+
+ // Clicking Copy must not toggle the collapsible header.
+ expect(header).toHaveAttribute('aria-expanded', 'true');
+ expect(navigator.clipboard.writeText).toHaveBeenCalled();
+ });
+
+ it('does not nest the copy button inside the collapsible header role="button"', () => {
+ render(
+ <CodeBlock
+ code={LONG_CODE}
+ language="javascript"
+ title="example"
+ isCollapsible
+ />,
+ );
+ const header = screen
+ .getAllByRole('button')
+ .find(el => el.hasAttribute('aria-expanded'));
+ const copyButton = screen.getByRole('button', {name: 'Copy code'});
+ expect(header).toBeTruthy();
+ // The copy button must be a sibling, not a descendant of the interactive
+ // header — nested interactive controls are invalid ARIA.
+ expect(header!.contains(copyButton)).toBe(false);
+ });
+
+ it('still toggles collapse when the header itself is clicked', () => {
+ render(
+ <CodeBlock
+ code={LONG_CODE}
+ language="javascript"
+ title="example"
+ isCollapsible
+ />,
+ );
+ const header = screen
+ .getAllByRole('button')
+ .find(el => el.hasAttribute('aria-expanded'))!;
+ expect(header).toHaveAttribute('aria-expanded', 'true');
+ fireEvent.click(header);
+ expect(header).toHaveAttribute('aria-expanded', 'false');
+ });
+});
diff --git a/packages/core/src/CodeBlock/CodeBlock.tsx b/packages/core/src/CodeBlock/CodeBlock.tsx
index 150ce1184f..5310380aef 100644
--- a/packages/core/src/CodeBlock/CodeBlock.tsx
+++ b/packages/core/src/CodeBlock/CodeBlock.tsx
@@ -87,7 +87,7 @@ const styles = stylex.create({
backgroundColor: 'var(--color-syntax-background)',
overflow: 'hidden',
},
- header: {
+ headerRow: {
display: 'flex',
alignItems: 'center',
justifyContent: 'space-between',
@@ -97,6 +97,19 @@ const styles = stylex.create({
top: 0,
zIndex: 1,
},
+ header: {
+ display: 'flex',
+ alignItems: 'center',
+ flex: 1,
+ minWidth: 0,
+ // Reset default <button> appearance for the collapsible title control.
+ padding: 0,
+ border: 'none',
+ backgroundColor: 'transparent',
+ color: 'inherit',
+ font: 'inherit',
+ textAlign: 'start',
+ },
headerWithDivider: {
paddingBlock: spacingVars['--spacing-2'],
borderBottomWidth: borderVars['--border-width'],
@@ -469,7 +482,10 @@ function useTokenLines(
// Span-mode code element
// ---------------------------------------------------------------------------
-function buildSpanLine(lineText: string, tokens: SyntaxToken[]): React.ReactNode {
+function buildSpanLine(
+ lineText: string,
+ tokens: SyntaxToken[],
+): React.ReactNode {
if (tokens.length === 0) {
return lineText || '\u200b';
}
@@ -677,7 +693,9 @@ export function CodeBlock({
const copyButtonEl = hasCopyButton ? (
<button
type="button"
- onClick={() => {
+ onClick={e => {
+ // Stop propagation so copying does not toggle the collapsible header.
+ e.stopPropagation();
void handleCopy();
}}
aria-label={copied ? 'Copied' : 'Copy code'}
@@ -691,39 +709,44 @@ export function CodeBlock({
const headerEl = showHeader ? (
<div
- role={canCollapse ? 'button' : undefined}
- tabIndex={canCollapse ? 0 : undefined}
- aria-expanded={canCollapse ? !isCollapsed : undefined}
- onClick={canCollapse ? () => setIsCollapsed(prev => !prev) : undefined}
- onKeyDown={
- canCollapse
- ? (e: React.KeyboardEvent) => {
- if (e.key === 'Enter' || e.key === ' ') {
- e.preventDefault();
- setIsCollapsed(prev => !prev);
- }
- }
- : undefined
- }
{...stylex.props(
- styles.header,
+ styles.headerRow,
hasLineNumbers ? styles.headerWithDivider : styles.headerCompact,
- canCollapse && styles.headerCollapsible,
)}>
- <span {...stylex.props(styles.headerTitle)}>
- {title}
- {title && languageLabel ? ' — ' : ''}
- {languageLabel}
- {canCollapse && (
- <span
- {...stylex.props(
- styles.collapseChevron,
- isCollapsed && styles.collapseChevronCollapsed,
- )}>
- <Icon icon="chevronDown" size="xsm" color="inherit" />
- </span>
- )}
- </span>
+ <div
+ role={canCollapse ? 'button' : undefined}
+ tabIndex={canCollapse ? 0 : undefined}
+ aria-expanded={canCollapse ? !isCollapsed : undefined}
+ onClick={canCollapse ? () => setIsCollapsed(prev => !prev) : undefined}
+ onKeyDown={
+ canCollapse
+ ? (e: React.KeyboardEvent) => {
+ if (e.key === 'Enter' || e.key === ' ') {
+ e.preventDefault();
+ setIsCollapsed(prev => !prev);
+ }
+ }
+ : undefined
+ }
+ {...stylex.props(
+ styles.header,
+ canCollapse && styles.headerCollapsible,
+ )}>
+ <span {...stylex.props(styles.headerTitle)}>
+ {title}
+ {title && languageLabel ? ' — ' : ''}
+ {languageLabel}
+ {canCollapse && (
+ <span
+ {...stylex.props(
+ styles.collapseChevron,
+ isCollapsed && styles.collapseChevronCollapsed,
+ )}>
+ <Icon icon="chevronDown" size="xsm" color="inherit" />
+ </span>
+ )}
+ </span>
+ </div>
{copyButtonEl}
</div>
) : null;
@@ -731,6 +754,11 @@ export function CodeBlock({
const codeBody = (
<div
ref={scrollContainerRef}
+ // The scroll container is keyboard-focusable so keyboard users can
+ // scroll long or wide code that overflows the viewport.
+ tabIndex={0}
+ role="region"
+ aria-label={languageLabel ?? 'Code'}
{...mergeProps(stylex.props(styles.scrollContainer), {
style: scrollStyle,
})}>
diff --git a/packages/core/src/Markdown/Markdown.test.tsx b/packages/core/src/Markdown/Markdown.test.tsx
index cff51c13a3..7d543ed9bf 100644
--- a/packages/core/src/Markdown/Markdown.test.tsx
+++ b/packages/core/src/Markdown/Markdown.test.tsx
@@ -189,6 +189,17 @@ describe('Markdown', () => {
expect(document.querySelectorAll('td')).toHaveLength(2);
});
+ it('makes the table scroll wrapper keyboard-focusable', () => {
+ render(<Markdown>{'| A | B |\n| --- | --- |\n| 1 | 2 |'}</Markdown>);
+ const table = document.querySelector('table');
+ expect(table).toBeInTheDocument();
+ // The GFM table's outer overflow wrapper is keyboard-focusable so keyboard
+ // users can horizontally scroll a wide table.
+ const wrapper = table!.closest('[role="region"][tabindex="0"]');
+ expect(wrapper).toBeTruthy();
+ expect(wrapper).toHaveAttribute('aria-label', 'Table');
+ });
+
it('renders horizontal rules', () => {
render(<Markdown>{'---'}</Markdown>);
expect(document.querySelector('hr')).toBeInTheDocument();
diff --git a/packages/core/src/Markdown/Markdown.tsx b/packages/core/src/Markdown/Markdown.tsx
index 0cf7382333..c709e0813c 100644
--- a/packages/core/src/Markdown/Markdown.tsx
+++ b/packages/core/src/Markdown/Markdown.tsx
@@ -1399,6 +1399,11 @@ function renderBlock(
return (
<div
key={index}
+ // Keyboard-focusable so keyboard users can scroll a horizontally
+ // overflowing GFM table.
+ tabIndex={0}
+ role="region"
+ aria-label="Table"
{...stylex.props(
styles.tableWrapper,
spacing,
diff --git a/packages/core/src/Table/Table.test.tsx b/packages/core/src/Table/Table.test.tsx
index 409d86e615..c6931754b5 100644
--- a/packages/core/src/Table/Table.test.tsx
+++ b/packages/core/src/Table/Table.test.tsx
@@ -633,6 +633,16 @@ describe('Table', () => {
expect(wrapper!.className).toContain('astryx-table-scroll-wrapper');
});
+ it('makes the scroll container keyboard-focusable', () => {
+ render(<Table data={users} columns={columns} />);
+ const table = screen.getByRole('table');
+ const wrapper = table.parentElement;
+ expect(wrapper).toBeTruthy();
+ expect(wrapper!).toHaveAttribute('tabindex', '0');
+ expect(wrapper!).toHaveAttribute('role', 'region');
+ expect(wrapper!).toHaveAttribute('aria-label', 'Table');
+ });
+
it('uses table-layout: auto in children mode', () => {
const {container} = render(
<Table dividers="rows">
diff --git a/packages/core/src/Table/Table.tsx b/packages/core/src/Table/Table.tsx
index b8f94fc700..d131b22c37 100644
--- a/packages/core/src/Table/Table.tsx
+++ b/packages/core/src/Table/Table.tsx
@@ -151,6 +151,11 @@ function TableScrollWrapper({
return (
<div
ref={ref}
+ // Keyboard-focusable so keyboard users can scroll a horizontally
+ // overflowing table. Callers may override role/aria-label via htmlProps.
+ tabIndex={0}
+ role="region"
+ aria-label="Table"
{...restHtmlProps}
{...mergeProps(
themeProps('table-scroll-wrapper'),