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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/docs/specs/components/CodeBlock/CodeBlock.spec.md b/docs/specs/components/CodeBlock/CodeBlock.spec.mdindex 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 relationshipsdiff --git a/packages/core/src/CodeBlock/CodeBlock.test.tsx b/packages/core/src/CodeBlock/CodeBlock.test.tsxindex 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.tsxindex 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.tsindex 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;