Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
91 changes: 91 additions & 0 deletions packages/client/src/widget.test.ts
Original file line number Diff line number Diff line change
@@ -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");
});
});
40 changes: 30 additions & 10 deletions packages/client/src/widget.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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; }
Expand All @@ -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; }
</style>
<div class="webdecoy-checkbox" role="checkbox" aria-checked="false" tabindex="0">
<div class="webdecoy-checkbox" role="checkbox" aria-checked="false" aria-label="I'm not a robot" tabindex="0">
<div class="webdecoy-spinner" style="display: none;"></div>
<span class="webdecoy-checkmark">✓</span>
<span class="webdecoy-x">✕</span>
</div>
<span class="webdecoy-label">I'm not a robot</span>
<span class="webdecoy-label" aria-hidden="true">I'm not a robot</span>
<span class="webdecoy-status webdecoy-sr-only" role="status" aria-live="polite"></span>
<div class="webdecoy-branding">
<span class="webdecoy-brand">WebDecoy</span>
</div>
Expand All @@ -135,6 +142,13 @@ export class CaptchaWidget {
this.checkbox = this.container.querySelector('.webdecoy-checkbox') as HTMLElement;
this.spinner = this.container.querySelector('.webdecoy-spinner') as HTMLElement;
this.label = this.container.querySelector('.webdecoy-label') as HTMLElement;
this.status = this.container.querySelector('.webdecoy-status') as HTMLElement;
}

/** Visible label plus a polite announcement for screen readers. */
private _setStatus(visible: string, announce: string): void {
this.label.textContent = visible;
this.status.textContent = announce;
}

private _attachListeners(): void {
Expand Down Expand Up @@ -176,7 +190,9 @@ export class CaptchaWidget {

this.checkbox.classList.add('loading');
this.spinner.style.display = 'block';
this.label.textContent = 'Verifying...';
this.checkbox.setAttribute('aria-busy', 'true');
this.checkbox.setAttribute('aria-disabled', 'true');
this._setStatus('Verifying...', 'Verifying, please wait.');

try {
const behavioralData = this.behavioral.analyze();
Expand Down Expand Up @@ -314,8 +330,9 @@ export class CaptchaWidget {
this.checkbox.classList.remove('loading');
this.checkbox.classList.add('verified');
this.checkbox.setAttribute('aria-checked', 'true');
this.checkbox.removeAttribute('aria-busy');
this.spinner.style.display = 'none';
this.label.textContent = 'Verified';
this._setStatus('Verified', 'Verified.');

if (this.options.callback) this.options.callback(token);
this.container.dispatchEvent(new CustomEvent('webdecoy:verified', { detail: { token } }));
Expand All @@ -324,15 +341,16 @@ export class CaptchaWidget {
private _showFailure(message?: string): void {
this.checkbox.classList.remove('loading');
this.checkbox.classList.add('failed');
this.checkbox.removeAttribute('aria-busy');
this.checkbox.removeAttribute('aria-disabled');
this.spinner.style.display = 'none';
this.label.textContent = message || 'Verification failed';
const text = message || 'Verification failed';
// The message stays until the next attempt, so it can't vanish before it is read.
this._setStatus(text, `${text} Press Space or Enter on the checkbox to try again.`);

if (this.options.errorCallback) this.options.errorCallback(message);

setTimeout(() => {
this.checkbox.classList.remove('failed');
this.label.textContent = "I'm not a robot";
}, 3000);
setTimeout(() => this.checkbox.classList.remove('failed'), 3000);
}

getToken(): string | null {
Expand All @@ -350,8 +368,10 @@ export class CaptchaWidget {
this.powManager.reset();
this.checkbox.classList.remove('verified', 'failed', 'loading');
this.checkbox.setAttribute('aria-checked', 'false');
this.checkbox.removeAttribute('aria-busy');
this.checkbox.removeAttribute('aria-disabled');
this.spinner.style.display = 'none';
this.label.textContent = "I'm not a robot";
this._setStatus("I'm not a robot", '');
void this._fetchChallenge();
}
}
Loading