fix(ui): no button drops the keyboard focus when its own action disables it

A focused button that turns natively disabled loses the focus to <body> in
Chrome. The app disables the very button that was pressed on ~60 sites — a
mutation pending, a pager at its last page, undo with nothing left, a player
at the end of its queue, a form gone clean — so a keyboard user was thrown
out of the page on every such press.

One primitive instead of a fix per site: ui/FocusSafeButton renders a
focused-and-disabled (or busy) button as aria-disabled with a click guard,
and applies the native attribute again once the focus is elsewhere. It asks
the document at render time as well as listening for focus events, because
a window without focus fires none (measured). ui/Button and ui/form's Switch
are built on it; 57 hand-rolled buttons swapped their tag for it keeping
their classes, and three hand-copies of the rule (the channel page's Block
and Hide, ChannelDiscovery's Subscribe) now pass `busy`. The soft state's
dim look is one rule in index.css.

`local/focus-safe-disabled` refuses a new raw <button disabled>, pinned by
focusSafe.contract.test.ts. lib/plexDetailUi moved to components/: it is
components, and lib may not import the primitive.

Measured on localdev in Chrome: the audit log's Next button keeps the focus
on reaching the last page, reads aria-disabled, and the guarded click does
nothing.
This commit is contained in:
2026-09-19 08:07:25 +02:00
parent bc138e3b37
commit 7a47223a58
39 changed files with 368 additions and 159 deletions
+49 -1
View File
@@ -5,7 +5,7 @@
// dropped), the loading state (disabled + spinner + aria-busy), and the type="button" default that
// stops an action button from submitting a surrounding form.
import { afterEach, describe, expect, it, vi } from "vitest";
import { render, screen, cleanup, fireEvent } from "@testing-library/react";
import { act, render, screen, cleanup, fireEvent } from "@testing-library/react";
import { Button } from "./Button";
afterEach(cleanup);
@@ -153,6 +153,54 @@ describe("Button primitive (S5)", () => {
// so weakening the union turns the whole typecheck lane red.
//
// Rendered, not just declared, so eslint sees them used and the file stays one test suite.
describe("Button · disabled while it holds the focus", () => {
// A focused button that turns natively disabled loses the focus to <body> in Chrome (measured, E11
// S2) — and ~60 call sites disable the very button that was just pressed while its mutation runs.
// jsdom does not move the focus, so the CONTRACT is what is pinned: while focused, the button is
// unavailable by aria-disabled + a click guard, never by the native attribute.
it("keeps the native attribute off while focused, and blocks activation", () => {
const onClick = vi.fn();
const { rerender } = render(<Button onClick={onClick}>Save</Button>);
const btn = screen.getByRole("button", { name: "Save" });
act(() => btn.focus());
rerender(
<Button onClick={onClick} disabled>
Save
</Button>,
);
expect(btn.hasAttribute("disabled")).toBe(false);
expect(btn.getAttribute("aria-disabled")).toBe("true");
fireEvent.click(btn);
expect(onClick).not.toHaveBeenCalled();
});
it("also holds when the window has no focus and no focus event ever fired", () => {
// Chrome, with another app in front: `.focus()` moves activeElement and fires nothing. The
// button asks the document at render time, so it does not rely on the event (measured).
const { rerender } = render(<Button onClick={() => {}}>Next</Button>);
const btn = screen.getByRole("button", { name: "Next" });
const active = vi.spyOn(document, "activeElement", "get").mockReturnValue(btn);
rerender(
<Button onClick={() => {}} disabled>
Next
</Button>,
);
expect(btn.hasAttribute("disabled")).toBe(false);
expect(btn.getAttribute("aria-disabled")).toBe("true");
active.mockRestore();
});
it("is natively disabled again once the focus is elsewhere", () => {
render(
<Button onClick={() => {}} disabled>
Save
</Button>,
);
const btn = screen.getByRole("button", { name: "Save" });
expect(btn.hasAttribute("disabled")).toBe(true);
});
});
describe("Button accessible-name contract (type level)", () => {
it("rejects a text-less button with no name, and accepts every named spelling", () => {
render(