fix(Modal): add focus ring to initially focused element (#758)

Author: huyenltnguyen

src/modal/modal.test.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { render, screen, within } from "@testing-library/react";
+import { render, screen, within, act } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
 import { Button } from "../button";
@@ -25,6 +25,7 @@ describe("<Modal />", () => {
 
 	afterEach(() => {
 		jest.clearAllMocks();
+		jest.useRealTimers();
 	});
 
 	afterAll(() => {
@@ -201,4 +202,51 @@ describe("<Modal />", () => {
 		const closeButton = within(dialog).getByRole("button", { name: "Close" });
 		expect(closeButton).toHaveFocus();
 	});
+
+	it("should show a focus ring on the initially focused element after the modal opens", async () => {
+		// headlessui only fires afterEnter when `show` transitions false → true (not on
+		// initial mount). Use fake timers so requestAnimationFrame callbacks — which
+		// headlessui uses to detect when the CSS enter transition finishes — are
+		// controlled by jest and fire synchronously via jest.runAllTimers().
+		jest.useFakeTimers();
+
+		const initialFocusRef = React.createRef<HTMLButtonElement>();
+
+		const modal = (open: boolean) => (
+			<Modal open={open} onClose={() => {}} initialFocus={initialFocusRef}>
+				<Modal.Header>Lorem ipsum</Modal.Header>
+				<Modal.Body>
+					<p>Laboriosam autem non et nisi.</p>
+				</Modal.Body>
+				<Modal.Footer>
+					<Button ref={initialFocusRef} block size="large">
+						Submit
+					</Button>
+				</Modal.Footer>
+			</Modal>
+		);
+
+		const { rerender } = render(modal(false));
+
+		// Trigger the enter transition (false → true).
+		rerender(modal(true));
+
+		// headlessui's d.nextFrame() fires afterEnter via two nested RAFs.
+		// Advance fake timers twice to flush both frames.
+		act(() => jest.runAllTimers()); // outer RAF fires, schedules inner RAF
+		act(() => jest.runAllTimers()); // inner RAF fires → afterEnter
+
+		// headlessui's nesting.onStop calls afterEnter via a Promise chain
+		// (.then().then()). Flush the microtask queue so those callbacks run.
+		// eslint-disable-next-line testing-library/no-unnecessary-act
+		await act(async () => {});
+
+		const dialog = screen.getByRole("dialog", { name: "Lorem ipsum" });
+		const submitButton = within(dialog).getByRole("button", { name: "Submit" });
+
+		expect(submitButton).toHaveStyle(
+			"outline: 3px solid var(--focus-outline-color)",
+		);
+		expect(submitButton).toHaveStyle("outline-offset: 0px");
+	});
 });

src/modal/modal.tsx

@@ -117,9 +117,29 @@ const Modal = ({
 		panelClasses = panelClasses.concat(" ", "text-background-danger");
 	}
 
+	const showFocusRingOnInitialFocus = () => {
+		const el = document.activeElement as HTMLElement | null;
+		if (!el) return;
+
+		el.style.outline = "3px solid var(--focus-outline-color)";
+		el.style.outlineOffset = "0px";
+		el.addEventListener(
+			"blur",
+			() => {
+				el.style.outline = "";
+				el.style.outlineOffset = "";
+			},
+			{ once: true },
+		);
+	};
+
 	return (
 		<ModalContext.Provider value={{ onClose, variant }}>
-			<Transition.Root show={open} as={Fragment}>
+			<Transition.Root
+				show={open}
+				as={Fragment}
+				afterEnter={showFocusRingOnInitialFocus}
+			>
 				<Dialog
 					onClose={onClose}
 					className="fixed inset-0 z-1050"