Skip to content

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

TypeScript

fix(useClipboard): a failed copy is announced assertively (#10448)

Cindy Zhang6caeec86c722
diff --git a/.changeset/copy-failure-assertive.md b/.changeset/copy-failure-assertive.md
new file mode 100644
index 0000000000..ea9b8521da
--- /dev/null
+++ b/.changeset/copy-failure-assertive.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] CodeBlock's "Failed to copy value to clipboard." announcement now uses the assertive live region instead of the polite one, as status announcements require for errors, so screen readers report a failed copy right away. A successful copy is still announced politely.
+
+@cixzhang
diff --git a/docs/specs/components/CodeBlock/CodeBlock.spec.md b/docs/specs/components/CodeBlock/CodeBlock.spec.md
index 632ba520d9..59f0fbaa78 100644
--- a/docs/specs/components/CodeBlock/CodeBlock.spec.md
+++ b/docs/specs/components/CodeBlock/CodeBlock.spec.md
@@ -158,7 +158,7 @@ Consumer migration instructions belong in consumer docs and release notes.
- **AR1 — Named controls.** Every rendered copy and disclosure control has a non-empty accessible name, including when title text is empty or whitespace-only.
- **AR2 — Disclosure.** The collapsible header exposes expanded state and its controlled region, toggles with pointer, Enter, and Space, and makes collapsed descendants inert without removing the controlled region.
-- **AR3 — Copy feedback.** Copy success updates the control name and emits one localized polite announcement; the visible purpose remains available through the tooltip.
+- **AR3 — Copy feedback.** Copy success updates the control name and emits one localized polite announcement; a failed write emits one localized assertive announcement, because it is an error (`spec:AST-086` FR5); the visible purpose remains available through the tooltip.
- **AR4 — Scroll access.** A named viewport enters the tab order only for effective overflow and retains native Arrow/Page access, per `spec:AST-025/FR12–FR13`.
## Design relationships
diff --git a/packages/core/src/CodeBlock/CodeBlock.test.tsx b/packages/core/src/CodeBlock/CodeBlock.test.tsx
index 06e6ad64c9..4afd9f2a73 100644
--- a/packages/core/src/CodeBlock/CodeBlock.test.tsx
+++ b/packages/core/src/CodeBlock/CodeBlock.test.tsx
@@ -34,6 +34,10 @@ function politeRegion(): HTMLElement | null {
return document.querySelector('[data-astryx-live-region="polite"]');
}
+function assertiveRegion(): HTMLElement | null {
+ return document.querySelector('[data-astryx-live-region="assertive"]');
+}
+
// A code sample long enough to exceed the default collapsible threshold (10).
const LONG_CODE = Array.from(
{length: 15},
@@ -287,12 +291,16 @@ describe('CodeBlock', () => {
// The tooltip says the same as the name, so Button does not repeat it
// as a description.
expect(failed).not.toHaveAttribute('aria-describedby');
+ // A failure is an error, so it goes to the assertive region.
await waitFor(() => {
- expect(politeRegion()).toHaveTextContent(
+ expect(assertiveRegion()).toHaveTextContent(
'Failed to copy value to clipboard.',
);
});
- expect(politeRegion()).not.toHaveTextContent('permission');
+ expect(assertiveRegion()).not.toHaveTextContent('permission');
+ expect(politeRegion()?.textContent ?? '').not.toContain(
+ 'Failed to copy value to clipboard.',
+ );
});
it('calls onCopyError once with the rejection and never onCopy', async () => {
diff --git a/packages/core/src/hooks/useClipboard.test.tsx b/packages/core/src/hooks/useClipboard.test.tsx
index 9a8b85157d..b74bd96a62 100644
--- a/packages/core/src/hooks/useClipboard.test.tsx
+++ b/packages/core/src/hooks/useClipboard.test.tsx
@@ -18,6 +18,10 @@ function politeRegion(): HTMLElement | null {
return document.querySelector('[data-astryx-live-region="polite"]');
}
+function assertiveRegion(): HTMLElement | null {
+ return document.querySelector('[data-astryx-live-region="assertive"]');
+}
+
describe('useClipboard', () => {
beforeEach(() => {
// jsdom does not implement the async Clipboard API.
@@ -177,8 +181,14 @@ describe('useClipboardCopy (internal)', () => {
expect(result.current.isCopied).toBe(false);
expect(onError).toHaveBeenCalledTimes(1);
expect(onError).toHaveBeenCalledWith(error);
+ // A failure is an error, so it is announced assertively.
+ act(() => {
+ vi.advanceTimersByTime(20);
+ });
+ expect(assertiveRegion()).toHaveTextContent('Failed');
+ expect(politeRegion()?.textContent ?? '').not.toContain('Failed');
act(() => {
- vi.advanceTimersByTime(2000);
+ vi.advanceTimersByTime(1980);
});
expect(result.current.isFailed).toBe(false);
});
diff --git a/packages/core/src/hooks/useClipboard.ts b/packages/core/src/hooks/useClipboard.ts
index 336d7706d8..29fa2d23e7 100644
--- a/packages/core/src/hooks/useClipboard.ts
+++ b/packages/core/src/hooks/useClipboard.ts
@@ -99,7 +99,7 @@ export function useClipboard(
* component needs to report a failed write.
*/
export interface UseClipboardCopyOptions extends UseClipboardOptions {
- /** Message announced to the polite live region when a write fails. */
+ /** Message announced to the assertive live region when a write fails. */
announceFailure?: string;
/**
* Called once with the rejection when a write fails. `copy` still resolves
@@ -165,7 +165,8 @@ export function useClipboardCopy(
setIsFailed(false);
}, resetAfterMs);
if (announceFailure) {
- announce(announceFailure);
+ // A failure is an error, so screen readers hear it at once.
+ announce(announceFailure, 'assertive');
}
onError?.(error);
return false;