Skip to content

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

TypeScript
32.7 KB
Raw Blame
// 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);
  });
});