From 1ac5c8e27fd7ce3c275c095b71dd15b6ccaf11d7 Mon Sep 17 00:00:00 2001 From: Chris Portscheller Date: Sat, 14 Nov 2026 08:59:23 -0600 Subject: [PATCH] fix(client): make the checkbox widget accessible to keyboard and screen-reader users Give the checkbox an accessible name, announce verifying/verified/failure through a polite status region, mark it busy while verifying, add a visible focus ring, and keep a failure message on screen until the next attempt instead of clearing it after three seconds. --- CHANGELOG.md | 5 ++ packages/client/src/widget.test.ts | 91 ++++++++++++++++++++++++++++++ packages/client/src/widget.ts | 40 +++++++++---- 3 files changed, 126 insertions(+), 10 deletions(-) create mode 100644 packages/client/src/widget.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 1985716..0e889a8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed + +- **The checkbox widget works with screen readers.** The checkbox now has an accessible name ("I'm not a robot"). "Verifying", "Verified" and failure messages are announced through a polite status region, and the checkbox reports busy while it verifies. It shows a visible focus ring for keyboard users. +- **A failure message stays on screen until the next attempt.** It used to disappear after three seconds, which could be before a person had read it. + ## [0.24.0] - 2026-11-13 ### Changed diff --git a/packages/client/src/widget.test.ts b/packages/client/src/widget.test.ts new file mode 100644 index 0000000..4d958e8 --- /dev/null +++ b/packages/client/src/widget.test.ts @@ -0,0 +1,91 @@ +/** + * @jest-environment jsdom + * + * Accessibility contract for the checkbox widget: a named control, keyboard + * operation, and status changes a screen reader announces. + */ + +import { CaptchaWidget } from './widget'; + +let warn: jest.SpyInstance; +let error: jest.SpyInstance; +beforeEach(() => { + warn = jest.spyOn(console, 'warn').mockImplementation(() => {}); + error = jest.spyOn(console, 'error').mockImplementation(() => {}); +}); +afterEach(() => { + warn.mockRestore(); + error.mockRestore(); + document.body.innerHTML = ''; +}); + +function render(): { el: HTMLElement; widget: CaptchaWidget } { + const el = document.createElement('div'); + document.body.appendChild(el); + return { el, widget: new CaptchaWidget(el, { siteKey: 'pk_test_a11y' }) }; +} + +const parts = (el: HTMLElement) => ({ + checkbox: el.querySelector('[role="checkbox"]') as HTMLElement, + status: el.querySelector('[role="status"]') as HTMLElement, + label: el.querySelector('.webdecoy-label') as HTMLElement, +}); + +describe('CaptchaWidget accessibility', () => { + it('gives the checkbox an accessible name and keeps it focusable', () => { + const { checkbox, status, label } = parts(render().el); + expect(checkbox.getAttribute('aria-label')).toBe("I'm not a robot"); + expect(checkbox.getAttribute('aria-checked')).toBe('false'); + expect(checkbox.tabIndex).toBe(0); + expect(status.getAttribute('aria-live')).toBe('polite'); + // The visible text duplicates the name, so it is hidden from the a11y tree. + expect(label.getAttribute('aria-hidden')).toBe('true'); + }); + + it.each([' ', 'Enter'])('starts verification from the keyboard (%p) and announces it', key => { + const { checkbox, status } = parts(render().el); + checkbox.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true })); + expect(checkbox.getAttribute('aria-busy')).toBe('true'); + expect(checkbox.getAttribute('aria-disabled')).toBe('true'); + expect(status.textContent).toMatch(/Verifying/); + }); + + it('announces a failure, keeps the message on screen and allows a retry', async () => { + jest.useFakeTimers(); + try { + const { el, widget } = render(); + const { checkbox, status, label } = parts(el); + (widget as unknown as { _showFailure(m?: string): void })._showFailure('Verification failed'); + expect(status.textContent).toMatch(/Verification failed.*try again/); + expect(checkbox.hasAttribute('aria-busy')).toBe(false); + expect(checkbox.hasAttribute('aria-disabled')).toBe(false); + jest.advanceTimersByTime(10_000); + // The red mark clears, the message does not vanish on a timer. + expect(checkbox.classList.contains('failed')).toBe(false); + expect(label.textContent).toBe('Verification failed'); + } finally { + jest.useRealTimers(); + } + }); + + it('announces success and reports the checked state', () => { + const { el, widget } = render(); + const { checkbox, status } = parts(el); + (widget as unknown as { _showSuccess(t: string): void })._showSuccess('tok'); + expect(checkbox.getAttribute('aria-checked')).toBe('true'); + expect(checkbox.hasAttribute('aria-busy')).toBe(false); + expect(status.textContent).toBe('Verified.'); + }); + + it('reset returns to an idle, operable control with nothing announced', () => { + const { el, widget } = render(); + const { checkbox, status, label } = parts(el); + checkbox.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true })); + widget.reset(); + expect(checkbox.getAttribute('aria-checked')).toBe('false'); + expect(checkbox.hasAttribute('aria-busy')).toBe(false); + expect(checkbox.hasAttribute('aria-disabled')).toBe(false); + expect(status.textContent).toBe(''); + expect(label.textContent).toBe("I'm not a robot"); + }); +}); diff --git a/packages/client/src/widget.ts b/packages/client/src/widget.ts index e7d0c5b..272757b 100644 --- a/packages/client/src/widget.ts +++ b/packages/client/src/widget.ts @@ -31,6 +31,7 @@ export class CaptchaWidget { private checkbox!: HTMLElement; private spinner!: HTMLElement; private label!: HTMLElement; + private status!: HTMLElement; constructor(container: string | HTMLElement, options?: WidgetOptions) { const el = typeof container === 'string' ? document.getElementById(container) : container; @@ -102,6 +103,11 @@ export class CaptchaWidget { transition: all 0.15s ease; flex-shrink: 0; } .webdecoy-checkbox:hover { border-color: #00bcd4; } + .webdecoy-checkbox:focus-visible { outline: 2px solid #00bcd4; outline-offset: 2px; } + .webdecoy-sr-only { + position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; + overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; + } .webdecoy-checkbox.loading { border-color: #00bcd4; } .webdecoy-checkbox.verified { background: #4caf50; border-color: #4caf50; } .webdecoy-checkbox.failed { background: #f44336; border-color: #f44336; } @@ -120,12 +126,13 @@ export class CaptchaWidget { .webdecoy-branding { display: flex; flex-direction: column; align-items: flex-end; gap: 2px; flex-shrink: 0; } .webdecoy-brand { font-size: 11px; font-weight: 600; color: #ff2a6d; letter-spacing: 0.5px; } -