An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file useFocusTrap.test.tsx
* @input Uses vitest, @testing-library/react, useFocusTrap hook
* @output Unit tests for useFocusTrap tabbable-element model + Escape/IME guard
* @position Testing; validates useFocusTrap.ts focusable detection + dismissal coordination
*
* SYNC: When useFocusTrap.ts changes, update tests to match new behavior
*/
import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
import {
render,
screen,
fireEvent,
within,
cleanup,
} from '@testing-library/react';
import {createPortal} from 'react-dom';
import {FOCUSABLE_SELECTOR} from './focusableSelector';
import {useFocusTrap} from './useFocusTrap';
function Trap({children}: {children: React.ReactNode}) {
const {containerRef, focusFirst} = useFocusTrap<HTMLDivElement>({
isActive: true,
});
return (
<div>
<button type="button" data-testid="outside">
Outside
</button>
<div ref={containerRef} data-testid="trap">
{children}
</div>
<button type="button" onClick={focusFirst} data-testid="focus-first">
Focus first
</button>
</div>
);
}
function InnerRegion() {
const {containerRef} = useFocusTrap<HTMLDivElement>({isActive: true});
return (
<div ref={containerRef} data-testid="inner-region">
<button type="button" data-testid="inner-first">
Inner first
</button>
<button type="button" data-testid="inner-last">
Inner last
</button>
</div>
);
}
function OuterRegion({showInner}: {showInner: boolean}) {
const {containerRef} = useFocusTrap<HTMLDivElement>({isActive: true});
return (
<div ref={containerRef} data-testid="outer-region">
<button type="button" data-testid="outer-first">
Outer first
</button>
{showInner && <InnerRegion />}
</div>
);
}
function EscapeTrap({
isActive,
onEscape,
label,
}: {
isActive: boolean;
onEscape: () => void;
label: string;
}) {
const {containerRef} = useFocusTrap<HTMLDivElement>({isActive, onEscape});
return (
<div ref={containerRef} data-testid={label}>
<button type="button">{label}-btn</button>
</div>
);
}
function NestedInnerTrap({onEscape}: {onEscape: () => void}) {
const {containerRef} = useFocusTrap<HTMLDivElement>({
isActive: true,
onEscape,
});
return (
<div ref={containerRef} data-testid="nested-inner">
<button type="button">inner-btn</button>
</div>
);
}
function NestedTraps({
onOuterEscape,
onInnerEscape,
showInner = true,
}: {
onOuterEscape: () => void;
onInnerEscape: () => void;
showInner?: boolean;
}) {
const {containerRef} = useFocusTrap<HTMLDivElement>({
isActive: true,
onEscape: onOuterEscape,
});
return (
<div ref={containerRef} data-testid="nested-outer">
<button type="button">outer-btn</button>
{showInner && <NestedInnerTrap onEscape={onInnerEscape} />}
</div>
);
}
function RestoreTrap({isActive}: {isActive: boolean}) {
const {containerRef} = useFocusTrap<HTMLDivElement>({isActive});
return (
<div ref={containerRef} data-testid="restore-trap">
<button type="button" data-testid="inside">
Inside trap
</button>
</div>
);
}
function RestoreFixture({
isActive,
showPrev = true,
showTrap = true,
}: {
isActive: boolean;
showPrev?: boolean;
showTrap?: boolean;
}) {
return (
<div>
{showPrev && (
<button type="button" data-testid="prev">
Previously focused
</button>
)}
<button type="button" data-testid="other">
Other outside
</button>
{showTrap && <RestoreTrap isActive={isActive} />}
</div>
);
}
describe('useFocusTrap tabbable model (infra-8)', () => {
it('treats a contenteditable as focusable (focusFirst lands on it)', () => {
render(
<Trap>
<div
contentEditable
data-testid="editor"
suppressContentEditableWarning>
Type here
</div>
</Trap>,
);
fireEvent.click(screen.getByTestId('focus-first'));
expect(screen.getByTestId('editor')).toHaveFocus();
});
it('ignores an inert subtree when finding focusables', () => {
render(
<Trap>
<div inert>
<button type="button" data-testid="inert-btn">
Inert
</button>
</div>
<button type="button" data-testid="real-btn">
Real
</button>
</Trap>,
);
fireEvent.click(screen.getByTestId('focus-first'));
// Focus skips the inert button and lands on the real one.
expect(screen.getByTestId('real-btn')).toHaveFocus();
});
it('ignores an aria-hidden subtree when finding focusables', () => {
render(
<Trap>
<div aria-hidden="true">
<button type="button" data-testid="aria-hidden-btn">
Hidden from AT
</button>
</div>
<button type="button" data-testid="real-btn">
Real
</button>
</Trap>,
);
fireEvent.click(screen.getByTestId('focus-first'));
// An element AT cannot perceive must not be a trap tab stop (WCAG 4.1.2).
expect(screen.getByTestId('real-btn')).toHaveFocus();
});
it('excludes an aria-hidden focusable from the Tab wrap boundary', () => {
render(
<Trap>
<button type="button" data-testid="first">
First
</button>
<button type="button" data-testid="visible-last">
Visible last
</button>
<div aria-hidden="true">
<button type="button" data-testid="aria-hidden-btn">
Hidden from AT
</button>
</div>
</Trap>,
);
// The last VISIBLE-to-AT element is the wrap boundary: Tab from it wraps
// to the first element instead of landing on the aria-hidden button.
screen.getByTestId('visible-last').focus();
fireEvent.keyDown(document, {key: 'Tab'});
expect(screen.getByTestId('first')).toHaveFocus();
});
it('moves from a programmatic container focus target into the tabbable cycle', () => {
render(
<Trap>
<button type="button" data-testid="first">
First
</button>
<button type="button" data-testid="last">
Last
</button>
</Trap>,
);
const trap = screen.getByTestId('trap');
trap.tabIndex = -1;
trap.focus();
fireEvent.keyDown(document, {key: 'Tab'});
expect(screen.getByTestId('first')).toHaveFocus();
});
it('moves backward from a programmatic container focus target to the last tabbable control', () => {
render(
<Trap>
<button type="button" data-testid="first">
First
</button>
<button type="button" data-testid="last">
Last
</button>
</Trap>,
);
const trap = screen.getByTestId('trap');
trap.tabIndex = -1;
trap.focus();
fireEvent.keyDown(document, {key: 'Tab', shiftKey: true});
expect(screen.getByTestId('last')).toHaveFocus();
});
it('keeps a programmatic focus target when the trap has no tabbable controls', () => {
render(
<Trap>
<div tabIndex={-1} data-testid="programmatic-target">
Read-only dialog content
</div>
</Trap>,
);
const target = screen.getByTestId('programmatic-target');
target.focus();
expect(fireEvent.keyDown(target, {key: 'Tab'})).toBe(false);
expect(target).toHaveFocus();
expect(screen.getByTestId('outside')).not.toHaveFocus();
});
it('leaves Tab alone when focus is outside a trap with tabbable controls', () => {
render(
<Trap>
<button type="button" data-testid="inside">
Inside
</button>
</Trap>,
);
const outside = screen.getByTestId('outside');
const next = screen.getByTestId('focus-first');
outside.focus();
// The browser moves focus on to the next page control after an unhandled
// Tab; the trap must not pull that focus into itself.
expect(fireEvent.keyDown(outside, {key: 'Tab'})).toBe(true);
next.focus();
expect(next).toHaveFocus();
expect(screen.getByTestId('inside')).not.toHaveFocus();
});
it('wraps Tab from an SVG control that is the last tabbable inside the trap', () => {
render(
<Trap>
<button type="button" data-testid="first">
First
</button>
<svg tabIndex={0} data-testid="svg-control" aria-label="Chart point">
<circle r={4} />
</svg>
</Trap>,
);
const svgControl = screen.getByTestId('svg-control');
(svgControl as unknown as SVGElement).focus();
expect(svgControl).toHaveFocus();
expect(fireEvent.keyDown(svgControl, {key: 'Tab'})).toBe(false);
expect(screen.getByTestId('first')).toHaveFocus();
});
it('leaves controls inside a closed dialog out of the Tab cycle', () => {
render(
<Trap>
<button type="button" data-testid="first">
First
</button>
<button type="button" data-testid="last">
Last
</button>
<dialog>
<button type="button" data-testid="hidden">
In a closed sheet
</button>
</dialog>
</Trap>,
);
const last = screen.getByTestId('last');
last.focus();
expect(fireEvent.keyDown(last, {key: 'Tab'})).toBe(false);
expect(screen.getByTestId('first')).toHaveFocus();
});
it('keeps controls inside a popover-open dialog in the Tab cycle', () => {
// A Popover opened inside a non-modal sheet: the sheet's <dialog> is shown
// with showPopover(), which never sets `open`.
render(
<dialog data-testid="sheet">
<Trap>
<button type="button" data-testid="first">
First
</button>
<button type="button" data-testid="second">
Second
</button>
</Trap>
</dialog>,
);
const sheet = screen.getByTestId('sheet');
const matches = vi
.spyOn(sheet, 'matches')
.mockImplementation((selector: string) => selector === ':popover-open');
const first = screen.getByTestId('first');
first.focus();
// First is not the last Tab stop, so the trap leaves the press to the
// browser instead of cancelling it for want of tabbable controls.
expect(fireEvent.keyDown(first, {key: 'Tab'})).toBe(true);
const second = screen.getByTestId('second');
second.focus();
expect(fireEvent.keyDown(second, {key: 'Tab'})).toBe(false);
expect(first).toHaveFocus();
matches.mockRestore();
});
it('lets the innermost region answer Tab when regions nest at the end', () => {
// A region (a Popover, say) opened at the end of an active region (an open
// Dialog): its last control is also the outer region's last Tab stop.
const {rerender} = render(<OuterRegion showInner={false} />);
rerender(<OuterRegion showInner />);
const innerLast = screen.getByTestId('inner-last');
innerLast.focus();
expect(fireEvent.keyDown(innerLast, {key: 'Tab'})).toBe(false);
expect(screen.getByTestId('inner-first')).toHaveFocus();
});
it('leaves Tab to an open dialog nested inside the trap', () => {
render(
<Trap>
<button type="button" data-testid="outer">
Outer
</button>
<dialog open>
<button type="button" data-testid="inner-last">
Continue
</button>
</dialog>
</Trap>,
);
const innerLast = screen.getByTestId('inner-last');
innerLast.focus();
// The nested dialog is its own focus context; the outer region does not
// cancel the press or pull focus to its own first control.
expect(fireEvent.keyDown(innerLast, {key: 'Tab'})).toBe(true);
expect(innerLast).toHaveFocus();
});
it('pulls focus back in when a Tab from inside leaves the trap', () => {
render(
<Trap>
<button type="button" data-testid="first">
First
</button>
<button type="button" data-testid="inside">
Inside
</button>
</Trap>,
);
const first = screen.getByTestId('first');
first.focus();
// A Tab the trap does not wrap itself, where focus still leaves the
// container: the escaped focus is redirected back inside.
fireEvent.keyDown(first, {key: 'Tab'});
screen.getByTestId('focus-first').focus();
expect(screen.getByTestId('trap')).toContainElement(
document.activeElement as HTMLElement,
);
});
it('leaves Tab alone when focus is outside a trap with no tabbable controls', () => {
render(
<Trap>
<div role="option" tabIndex={-1} data-testid="option">
Option
</div>
</Trap>,
);
const outside = screen.getByTestId('outside');
outside.focus();
expect(fireEvent.keyDown(outside, {key: 'Tab'})).toBe(true);
});
describe('a Tab that content inside has already handled', () => {
// Content that walks its own Tab stops, such as a menu with a footer,
// moves focus and cancels the default. When the React root is the
// document (a Next.js App Router app), React's listener and the trap's
// listener share that node, so stopPropagation does not keep the press
// from the trap. A document listener added before the trap stands in for
// React's root listener here.
let removeContentHandler: (() => void) | null = null;
function handleTabInContent(move: (event: KeyboardEvent) => void) {
const listener = (event: KeyboardEvent) => {
if (event.key === 'Tab') {
event.preventDefault();
event.stopPropagation();
move(event);
}
};
document.addEventListener('keydown', listener);
removeContentHandler = () =>
document.removeEventListener('keydown', listener);
}
afterEach(() => {
removeContentHandler?.();
removeContentHandler = null;
});
function renderThreeControls() {
render(
<Trap>
<button type="button" data-testid="first">
First
</button>
<button type="button" data-testid="middle">
Middle
</button>
<button type="button" data-testid="last">
Last
</button>
</Trap>,
);
return {
first: screen.getByTestId('first'),
middle: screen.getByTestId('middle'),
last: screen.getByTestId('last'),
};
}
it('still wraps a Tab nothing handled, at either end', () => {
const {first, last} = renderThreeControls();
last.focus();
expect(fireEvent.keyDown(last, {key: 'Tab'})).toBe(false);
expect(first).toHaveFocus();
expect(fireEvent.keyDown(first, {key: 'Tab', shiftKey: true})).toBe(
false,
);
expect(last).toHaveFocus();
});
it('keeps focus where the content moved it on the last control', () => {
handleTabInContent(() => screen.getByTestId('last').focus());
const {middle, last} = renderThreeControls();
middle.focus();
fireEvent.keyDown(middle, {key: 'Tab'});
expect(last).toHaveFocus();
});
it('keeps focus where the content moved it on the first control by Shift+Tab', () => {
handleTabInContent(() => screen.getByTestId('first').focus());
const {first, middle} = renderThreeControls();
middle.focus();
fireEvent.keyDown(middle, {key: 'Tab', shiftKey: true});
expect(first).toHaveFocus();
});
it('does not pull in focus that moves outside after the handled press', () => {
handleTabInContent(() => screen.getByTestId('middle').focus());
const {first, middle} = renderThreeControls();
first.focus();
fireEvent.keyDown(first, {key: 'Tab'});
expect(middle).toHaveFocus();
// No Tab carried focus out, so a later move outside (a click on the
// page) is not an escape to redirect.
const outside = screen.getByTestId('outside');
outside.focus();
expect(outside).toHaveFocus();
});
});
});
describe('FOCUSABLE_SELECTOR href matching', () => {
// Only real links (<a href>/<area href>) are focusable via href. A bare
// [href] term also matched non-focusable elements carrying href (e.g. a
// <link> in the head, or a custom element), which useFocusTrap would then
// treat as tab stops when computing trap boundaries.
it('matches real links but not other elements carrying href', () => {
const container = document.createElement('div');
container.innerHTML =
'<a href="#a" data-testid="anchor">Anchor</a>' +
'<map name="m">' +
'<area href="#area" shape="rect" coords="0,0,1,1" data-testid="area" />' +
'</map>' +
'<span href="#span" data-testid="span">Span</span>' +
'<link href="#link" data-testid="link" />';
const matches = Array.from(
container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
);
const byTestId = (id: string) =>
container.querySelector(`[data-testid="${id}"]`);
// Real links are focusable via href.
expect(matches).toContain(byTestId('anchor'));
expect(matches).toContain(byTestId('area'));
// Non-link elements carrying href are not focusable and must be excluded.
expect(matches).not.toContain(byTestId('span'));
expect(matches).not.toContain(byTestId('link'));
});
it('treats an <a href> inside a trap as focusable (focusFirst lands on it)', () => {
render(
<Trap>
<a href="#link" data-testid="anchor">
Link
</a>
</Trap>,
);
fireEvent.click(screen.getByTestId('focus-first'));
expect(screen.getByTestId('anchor')).toHaveFocus();
});
});
describe('useFocusTrap Escape coordination', () => {
it('calls onEscape for a single active trap', () => {
const onEscape = vi.fn();
render(<EscapeTrap isActive onEscape={onEscape} label="only" />);
fireEvent.keyDown(document, {key: 'Escape'});
expect(onEscape).toHaveBeenCalledTimes(1);
});
it('only the top-most trap responds to Escape when nested', () => {
const outer = vi.fn();
const inner = vi.fn();
render(
<>
<EscapeTrap isActive onEscape={outer} label="outer" />
<EscapeTrap isActive onEscape={inner} label="inner" />
</>,
);
// The most recently activated trap (inner) is on top.
fireEvent.keyDown(document, {key: 'Escape'});
expect(inner).toHaveBeenCalledTimes(1);
expect(outer).not.toHaveBeenCalled();
});
it('ignores Escape during IME composition', () => {
const onEscape = vi.fn();
render(<EscapeTrap isActive onEscape={onEscape} label="ime" />);
fireEvent.keyDown(document, {key: 'Escape', isComposing: true});
expect(onEscape).not.toHaveBeenCalled();
// keyCode 229 (composition) is also ignored
fireEvent.keyDown(document, {key: 'Escape', keyCode: 229});
expect(onEscape).not.toHaveBeenCalled();
// a normal Escape still works
fireEvent.keyDown(document, {key: 'Escape'});
expect(onEscape).toHaveBeenCalledTimes(1);
});
it('resolves Escape to the DOM-nested inner trap when both mount in one commit', () => {
const outer = vi.fn();
const inner = vi.fn();
// Outer and inner mount in the SAME React commit. React runs child
// effects before parent effects, so the inner trap is PUSHED first —
// DOM containment, not push order, must decide who answers Escape.
render(<NestedTraps onOuterEscape={outer} onInnerEscape={inner} />);
fireEvent.keyDown(document, {key: 'Escape'});
expect(inner).toHaveBeenCalledTimes(1);
expect(outer).not.toHaveBeenCalled();
});
it('falls back to the outer trap once the nested inner trap unmounts', () => {
const outer = vi.fn();
const inner = vi.fn();
const {rerender} = render(
<NestedTraps onOuterEscape={outer} onInnerEscape={inner} />,
);
rerender(
<NestedTraps
onOuterEscape={outer}
onInnerEscape={inner}
showInner={false}
/>,
);
fireEvent.keyDown(document, {key: 'Escape'});
expect(outer).toHaveBeenCalledTimes(1);
expect(inner).not.toHaveBeenCalled();
});
it('does not respond after the trap is deactivated', () => {
const onEscape = vi.fn();
const {rerender} = render(
<EscapeTrap isActive onEscape={onEscape} label="toggle" />,
);
rerender(
<EscapeTrap isActive={false} onEscape={onEscape} label="toggle" />,
);
fireEvent.keyDown(document, {key: 'Escape'});
expect(onEscape).not.toHaveBeenCalled();
});
});
describe('useFocusTrap focus restoration', () => {
it('restores focus to the previously-focused element when deactivated', () => {
const {rerender} = render(<RestoreFixture isActive={false} />);
const prev = screen.getByTestId('prev');
prev.focus();
expect(prev).toHaveFocus();
// Activate the trap (captures `prev` as the restore target) and move focus
// inside it, as auto-focus or a keyboard user would.
rerender(<RestoreFixture isActive={true} />);
screen.getByTestId('inside').focus();
expect(screen.getByTestId('inside')).toHaveFocus();
// Deactivating returns focus to where it was before the trap opened.
rerender(<RestoreFixture isActive={false} />);
expect(prev).toHaveFocus();
});
it('does not steal focus when it was moved elsewhere outside the trap', () => {
const {rerender} = render(<RestoreFixture isActive={false} />);
const prev = screen.getByTestId('prev');
prev.focus();
rerender(<RestoreFixture isActive={true} />);
// The user (or a consumer that self-restores) moves focus to a different
// outside control while the trap is open.
const other = screen.getByTestId('other');
other.focus();
rerender(<RestoreFixture isActive={false} />);
// Focus is left where the user put it — not yanked back to `prev`.
expect(other).toHaveFocus();
expect(prev).not.toHaveFocus();
});
it('does not crash or restore when the captured element was removed', () => {
const {rerender} = render(<RestoreFixture isActive={false} />);
const prev = screen.getByTestId('prev');
prev.focus();
rerender(<RestoreFixture isActive={true} />);
screen.getByTestId('inside').focus();
// Remove the captured element from the DOM before the trap deactivates.
rerender(<RestoreFixture isActive={true} showPrev={false} />);
expect(() =>
rerender(<RestoreFixture isActive={false} showPrev={false} />),
).not.toThrow();
});
it('restores focus when the trap unmounts while active', () => {
const {rerender} = render(
<RestoreFixture isActive={true} showTrap={false} />,
);
const prev = screen.getByTestId('prev');
prev.focus();
// Mounting the trap active captures `prev`; then focus moves inside it.
rerender(<RestoreFixture isActive={true} showTrap={true} />);
screen.getByTestId('inside').focus();
expect(screen.getByTestId('inside')).toHaveFocus();
// Unmounting the trap (cleanup path, not an isActive flip) still restores.
rerender(<RestoreFixture isActive={true} showTrap={false} />);
expect(prev).toHaveFocus();
});
it('does not restore focus when focus never entered the trap', () => {
// Reproduces the Typeahead/PowerSearch scenario from #5651: a popup that
// opens with role="none" and hasAutoFocus={false} keeps DOM focus on its
// anchor input. The trap is active but focus never enters the container.
const {rerender} = render(<RestoreFixture isActive={false} />);
const prev = screen.getByTestId('prev');
prev.focus();
expect(prev).toHaveFocus();
// Activate the trap — focus stays on prev (outside the container).
rerender(<RestoreFixture isActive={true} />);
// Simulate an outside click: the browser blurs the input and focus falls
// to <body> before the layer's light dismiss hides it.
(document.activeElement as HTMLElement).blur();
expect(document.body).toHaveFocus();
// Deactivating should NOT restore focus to prev — focus never entered the
// trap, so restoring would cancel the blur the user asked for.
rerender(<RestoreFixture isActive={false} />);
expect(prev).not.toHaveFocus();
expect(document.body).toHaveFocus();
});
it('still restores focus when focus entered the trap and was then lost', () => {
// Complement to the test above: focus DID enter the trap (Dialog,
// DropdownMenu, a Typeahead option click), then the element was blurred
// so activeElement falls to <body>. The restore should still fire.
const {rerender} = render(<RestoreFixture isActive={false} />);
const prev = screen.getByTestId('prev');
prev.focus();
rerender(<RestoreFixture isActive={true} />);
// Focus enters the trap, as auto-focus or a keyboard user would.
screen.getByTestId('inside').focus();
expect(screen.getByTestId('inside')).toHaveFocus();
// Focus is lost from inside the trap — e.g. the trap content was removed
// or the user tabbed away — so activeElement falls to <body>.
(document.activeElement as HTMLElement).blur();
expect(document.body).toHaveFocus();
// Because focus was inside the trap at some point, the restore fires and
// returns focus to the element that was focused before activation.
rerender(<RestoreFixture isActive={false} />);
expect(prev).toHaveFocus();
});
});
describe('useFocusTrap in a second document', () => {
// A same-origin iframe stands in for any second document an app renders a
// trap into through a portal, Document Picture-in-Picture included. Its
// elements belong to the iframe's own window, and its key presses and focus
// changes never reach this document.
let frame: HTMLIFrameElement;
let secondDocument: Document;
beforeEach(() => {
frame = document.createElement('iframe');
document.body.appendChild(frame);
secondDocument = frame.contentDocument!;
});
afterEach(() => {
// Unmount before the frame goes, or React removes nodes from a document
// that no longer exists.
cleanup();
frame.remove();
});
it('keeps Tab on a programmatic focus target when nothing inside is tabbable', () => {
render(
createPortal(
<Trap>
<div tabIndex={-1} data-testid="programmatic-target">
Read-only dialog content
</div>
</Trap>,
secondDocument.body,
),
);
const target = within(secondDocument.body).getByTestId(
'programmatic-target',
);
target.focus();
expect(fireEvent.keyDown(target, {key: 'Tab'})).toBe(false);
expect(target).toHaveFocus();
});
it('returns focus to the element focused before it in that document', () => {
const {rerender} = render(
createPortal(<RestoreFixture isActive={false} />, secondDocument.body),
);
const view = within(secondDocument.body);
const prev = view.getByTestId('prev');
prev.focus();
rerender(
createPortal(<RestoreFixture isActive={true} />, secondDocument.body),
);
view.getByTestId('inside').focus();
(secondDocument.activeElement as HTMLElement).blur();
rerender(
createPortal(<RestoreFixture isActive={false} />, secondDocument.body),
);
expect(prev).toHaveFocus();
});
});
// A same-name native radio group is one Tab stop: its checked radio, or its
// first when none is checked. Medium is checked and is neither first nor last.
function SizeRadios({name}: {name: string}) {
return (
<fieldset>
<legend>Size</legend>
<input type="radio" name={name} value="s" aria-label="Small" />
<input
type="radio"
name={name}
value="m"
aria-label="Medium"
defaultChecked
/>
<input type="radio" name={name} value="l" aria-label="Large" />
</fieldset>
);
}
function expectRadioGroupEndsTheCycle() {
const medium = screen.getByRole('radio', {name: 'Medium', hidden: true});
const first = screen.getByRole('button', {name: 'First', hidden: true});
medium.focus();
expect(fireEvent.keyDown(medium, {key: 'Tab'})).toBe(false);
expect(first).toHaveFocus();
expect(fireEvent.keyDown(first, {key: 'Tab', shiftKey: true})).toBe(false);
expect(medium).toHaveFocus();
}
function expectRadioGroupStartsTheCycle() {
const medium = screen.getByRole('radio', {name: 'Medium', hidden: true});
const last = screen.getByRole('button', {name: 'Last', hidden: true});
medium.focus();
expect(fireEvent.keyDown(medium, {key: 'Tab', shiftKey: true})).toBe(false);
expect(last).toHaveFocus();
expect(fireEvent.keyDown(last, {key: 'Tab'})).toBe(false);
expect(medium).toHaveFocus();
}
describe('useFocusTrap radio-group Tab stops', () => {
it("ends the cycle at a trailing group's checked radio", () => {
render(
<Trap>
<button type="button">First</button>
<SizeRadios name="size" />
</Trap>,
);
expectRadioGroupEndsTheCycle();
});
it("starts the cycle at a leading group's checked radio", () => {
render(
<Trap>
<SizeRadios name="size" />
<button type="button">Last</button>
</Trap>,
);
expectRadioGroupStartsTheCycle();
});
it("uses a group's first radio when none is checked", () => {
render(
<Trap>
<button type="button">First</button>
<fieldset>
<legend>Plan</legend>
<input type="radio" name="plan" value="a" aria-label="Basic" />
<input type="radio" name="plan" value="b" aria-label="Pro" />
</fieldset>
</Trap>,
);
const basic = screen.getByRole('radio', {name: 'Basic'});
basic.focus();
expect(fireEvent.keyDown(basic, {key: 'Tab'})).toBe(false);
expect(screen.getByRole('button', {name: 'First'})).toHaveFocus();
});
it("wraps Shift+Tab onto an unchecked trailing group's last radio", () => {
render(
<Trap>
<button type="button">First</button>
<fieldset>
<legend>Plan</legend>
<input type="radio" name="plan" value="a" aria-label="Basic" />
<input type="radio" name="plan" value="b" aria-label="Pro" />
</fieldset>
</Trap>,
);
const first = screen.getByRole('button', {name: 'First'});
first.focus();
// Entering a group with nothing checked backward lands on its last radio,
// as the browser does.
expect(fireEvent.keyDown(first, {key: 'Tab', shiftKey: true})).toBe(false);
expect(screen.getByRole('radio', {name: 'Pro'})).toHaveFocus();
});
it('keeps a checked radio at its own place when a control sits between the radios', () => {
// A RadioList whose first option's description holds a link builds this
// shape: the checked radio, not the link, is the region's last stop.
render(
<Trap>
<button type="button">First</button>
<input type="radio" name="tier" aria-label="Basic" />
<button type="button">Basic details</button>
<input type="radio" name="tier" aria-label="Pro" defaultChecked />
</Trap>,
);
const pro = screen.getByRole('radio', {name: 'Pro'});
const details = screen.getByRole('button', {name: 'Basic details'});
pro.focus();
expect(fireEvent.keyDown(pro, {key: 'Tab'})).toBe(false);
expect(screen.getByRole('button', {name: 'First'})).toHaveFocus();
// From the control between the radios, Tab goes on to the checked radio.
details.focus();
expect(fireEvent.keyDown(details, {key: 'Tab'})).toBe(true);
});
it('keeps every radio of an unchecked group split by a control a stop', () => {
render(
<Trap>
<button type="button">First</button>
<input type="radio" name="tier" aria-label="Basic" />
<button type="button">Basic details</button>
<input type="radio" name="tier" aria-label="Pro" />
</Trap>,
);
const details = screen.getByRole('button', {name: 'Basic details'});
details.focus();
// Pro is still ahead of the control, so Tab is left to the browser.
expect(fireEvent.keyDown(details, {key: 'Tab'})).toBe(true);
const pro = screen.getByRole('radio', {name: 'Pro'});
pro.focus();
expect(fireEvent.keyDown(pro, {key: 'Tab'})).toBe(false);
expect(screen.getByRole('button', {name: 'First'})).toHaveFocus();
});
it('keeps each unnamed radio its own Tab stop', () => {
render(
<Trap>
<button type="button">First</button>
<input type="radio" aria-label="One" defaultChecked />
<input type="radio" aria-label="Two" />
</Trap>,
);
const one = screen.getByRole('radio', {name: 'One'});
one.focus();
// "Two" is still ahead, so Tab is left to the browser.
expect(fireEvent.keyDown(one, {key: 'Tab'})).toBe(true);
});
it('treats same-name radios in different forms as different groups', () => {
render(
<Trap>
<button type="button">First</button>
<form aria-label="A">
<input type="radio" name="x" aria-label="A1" defaultChecked />
</form>
<form aria-label="B">
<input type="radio" name="x" aria-label="B1" defaultChecked />
</form>
</Trap>,
);
const a1 = screen.getByRole('radio', {name: 'A1'});
a1.focus();
expect(fireEvent.keyDown(a1, {key: 'Tab'})).toBe(true);
});
});