fix(ui): a dialog keeps the focus it was given, and hands it back where it took it from

Round 5 extracted `ui/dialogFocus` so no shell would hand-roll the focus
contract, then introduced four ways to lose the focus anyway — all four measured
in jsdom against the real components.

**Ownership was narrower than the trap.** `ui/Modal` traps Tab over the whole
dialog on purpose, so a toast's Undo or ✕ stays reachable; ownership was tracked
over the panel alone. Tabbing to that ✕ therefore read as "the user left the
dialog", and since removing a toast fires no `focusin` to re-arm, closing
afterwards skipped the restore and left the focus on <body>. Before this hook
existed the restore was unconditional, so it was a regression.

**A dialog stacked above us is still ours.** A nested `ui/Modal` portals into its
own host, so it is outside the outer dialog's root however wide that scope is
drawn — widening alone could not fix it. Both closing in one commit left the
focus on <body>: the outer skipped its restore, and the child's own target (a
control inside the outer panel) was already detached, because passive cleanups
run parent-first. Ownership now means "inside my dialog, or inside a modal layer
above it", which is what the rule always intended.

**The wizard disagreed with `ui/Modal` on its first line.** `trapTab(e, panel)`,
with neither the dialog-root scope (so its own toast host was outside the cycle
— the connection notice never auto-dismisses, and its ✕ was unreachable from the
keyboard) nor the `container` argument the JSDoc exists for: `panel.contains(
panel)` is true, so focus sitting ON the tabIndex=-1 panel matched no branch and
a Shift+Tab walked into the app behind the scrim. Both call sites now pass the
same three arguments.

**The toast handover was a render-phase read-modify-write.** A `useMemo` read a
module global that the next line overwrote; React re-invokes a component body
and every `useMemo` factory in it on a StrictMode double render, and the LAST
invocation commits — so the second pass re-read what the first had just written,
the takeover host classified its OWN new toast as inherited, and the dev build
behaved exactly like the code round 5 replaced. Snapshotted through a ref keyed
on `isTop`, so a repeated invocation of one render is a no-op.

And the fourth `aria-modal` shell, `Welcome`'s screenshot lightbox, is finally
swept into the same contract: it declared itself a modal dialog while leaving
the focus on the thumbnail behind an 80%-black scrim and letting Tab walk the
landing page underneath.

The headline fix of the previous commit — StrictMode's re-mount taking the focus
off an `autoFocus` field — had no test at all; deleting it left all 1009 green.
It has one now.

9 tests, mutation-checked against 8 mutations, each red on the test that names it.
This commit is contained in:
2026-09-12 05:49:58 +02:00
parent 7f17b17c13
commit f8a31d48cf
10 changed files with 378 additions and 24 deletions
@@ -0,0 +1,54 @@
// @vitest-environment jsdom
//
// The dialog's focus behaviour under React 18 StrictMode — its own file because StrictMode's
// mount→cleanup→mount is what the code under test reacts to, and the module-level layer stack in
// ui/Modal (and the overlay-host registry in ui/Toaster) leaks between tests in one file.
//
// Round 5 fixed this in Chrome and shipped it with NO test: the second mount found the focus
// outside the dialog (its own cleanup had just handed it back to the trigger) and moved it to the
// first focusable — taking it off an `autoFocus` field a beat after the browser had put it there.
// The command palette opened focused on its ✕ in dev and on its search field in prod, from the same
// code. Round 6 measured that deleting the fix left all 1009 tests green, which is why this exists.
//
// Same offsetParent stub as Modal.dom.test.tsx: jsdom never lays out, so every element reports
// offsetParent null and `focusablesIn` would see nothing.
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
import { StrictMode } from "react";
import { render, screen, cleanup } from "@testing-library/react";
vi.mock("react-i18next", async (importOriginal) => {
const actual = await importOriginal<typeof import("react-i18next")>();
return { ...actual, useTranslation: () => ({ t: (key: string) => key }) };
});
vi.mock("../../lib/history", () => ({ useBackToClose: () => {} }));
import Modal from "./Modal";
describe("Modal focus under StrictMode", () => {
let origDesc: PropertyDescriptor | undefined;
beforeEach(() => {
origDesc = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "offsetParent");
Object.defineProperty(HTMLElement.prototype, "offsetParent", {
configurable: true,
get(this: HTMLElement) {
return this.isConnected ? document.body : null;
},
});
});
afterEach(() => {
cleanup();
if (origDesc) Object.defineProperty(HTMLElement.prototype, "offsetParent", origDesc);
});
it("keeps the focus its autoFocus child asked for across the double mount", () => {
render(
<StrictMode>
<Modal title="t" onClose={() => {}}>
<input aria-label="field" autoFocus />
</Modal>
</StrictMode>,
);
// Without the remembered focus the second mount lands on the first focusable — the header ✕.
expect(document.activeElement).toBe(screen.getByLabelText("field"));
});
});