Skip to content

Commit b9ad8df

Browse files
author
Carl
committed
Preserve keyboard focus when retry remounts navigation
Signed-off-by: Carl <32a2e2c9d428ee08902cab75d956da2c1d235a22d4766b0dd4138bf6e2e5db1d@buzz.block.builderlab.xyz>
1 parent b3f8f8d commit b9ad8df

4 files changed

Lines changed: 110 additions & 30 deletions

File tree

‎docs/shell-design.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,10 @@ semantic tokens, UI authoring rules and the local component reference.
7272
tab. Each opening carries focus intent: topbar activation suppresses destination
7373
autofocus, while explicit New conversation, sidebar and deep-link openings keep
7474
their content focus. This intent is not saved in addresses or history; retry
75-
preserves it for the same opening. The selected page is a separately focusable,
75+
preserves it for the same opening. A focused Retry navigation control hands
76+
focus to main before retry removes it, restoring that focus if reconnect
77+
temporarily remounts the shell. A new opening or focus elsewhere cancels this
78+
handoff. The selected page is a separately focusable,
7679
labelled tabpanel. Toolbar
7780
and overflow destinations remain native buttons using `aria-current` and
7881
focus main content on selection. Header pages never become companion launchers.

‎src/app/App.tsx‎

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,12 @@ import { AgentWakeNotice } from "../features/agents/AgentWakeNotice";
99
import { AgentUpdateReview } from "../bundled/agents/AgentUpdateReview";
1010
import { SnapshotPreview } from "../bundled/agents/SnapshotPreview";
1111
import { UpdateNotice } from "../features/updates/UpdateNotice";
12-
import { useEffect, useSyncExternalStore } from "react";
12+
import {
13+
useEffect,
14+
useLayoutEffect,
15+
useRef,
16+
useSyncExternalStore,
17+
} from "react";
1318
import { registerAppShortcuts } from "./shortcuts";
1419
import type { AppServices } from "./services";
1520
import { Settings } from "./Settings";
@@ -82,6 +87,18 @@ function ConnectedApp({ services }: { services: AppServices }) {
8287
);
8388
const restoring = client.status === "loading" || !!connection.restoring;
8489
const settings = route.target.kind === "settings";
90+
const retryFocus = useRef<string | undefined>(undefined);
91+
useLayoutEffect(() => {
92+
if (!retryFocus.current) return;
93+
if (retryFocus.current === route.state.attempt.id && !settings && restoring)
94+
return;
95+
if (
96+
retryFocus.current === route.state.attempt.id &&
97+
document.activeElement === document.body
98+
)
99+
document.getElementById("main-content")?.focus({ preventScroll: true });
100+
retryFocus.current = undefined;
101+
}, [restoring, settings, route.state.attempt]);
85102
const terminal =
86103
startup === "recovery" ||
87104
route.state.status === "failed" ||
@@ -262,7 +279,22 @@ function ConnectedApp({ services }: { services: AppServices }) {
262279
: "The destination is unavailable or isn’t supported yet. Your target has been kept for retry."}
263280
</p>
264281
{(!route.state.ingress || route.state.retryable) && (
265-
<Button type="button" onClick={route.retry}>
282+
<Button
283+
type="button"
284+
onClick={(event) => {
285+
const focused =
286+
event.currentTarget === document.activeElement;
287+
// Retry removes the control and can briefly unmount the shell.
288+
if (focused)
289+
document
290+
.getElementById("main-content")
291+
?.focus({ preventScroll: true });
292+
route.retry();
293+
retryFocus.current = focused
294+
? services.navigation.snapshot().attempt.id
295+
: undefined;
296+
}}
297+
>
266298
Retry navigation
267299
</Button>
268300
)}

‎src/app/navigation.test.tsx‎

Lines changed: 32 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -283,30 +283,40 @@ it("fails a completed ordinary-member read without exposing Membership", async (
283283
expect(screen.queryByRole("button", { name: "Membership" })).toBeNull();
284284
expect(screen.queryByRole("heading", { name: "Membership" })).toBeNull();
285285
});
286-
it("Retry navigation starts a fresh permission read after a failed roster", async () => {
287-
const fixture = membershipFixture();
288-
fixture.fail();
289-
const current = restoreMembership();
290-
await screen.findByRole("button", { name: "Retry navigation" });
291-
const before = fixture.rosterReads.length;
292-
expect(before).toBeGreaterThan(0);
293-
const release = fixture.hold();
294-
try {
295-
fireEvent.click(screen.getByRole("button", { name: "Retry navigation" }));
286+
it.each([true, false])(
287+
"Retry navigation refreshes permission and hands off only its own focus (focused: %s)",
288+
async (focused) => {
289+
const fixture = membershipFixture();
290+
fixture.fail();
291+
const current = restoreMembership();
292+
const retry = await screen.findByRole("button", {
293+
name: "Retry navigation",
294+
});
295+
const main = screen.getByRole("main");
296+
const elsewhere = screen.getByRole("link", { name: "Skip to content" });
297+
(focused ? retry : elsewhere).focus();
298+
const before = fixture.rosterReads.length;
299+
expect(before).toBeGreaterThan(0);
300+
const release = fixture.hold();
301+
try {
302+
fireEvent.click(retry);
303+
expect(focused ? main : elsewhere).toHaveFocus();
304+
await waitFor(() =>
305+
expect(fixture.rosterReads.length).toBeGreaterThan(before),
306+
);
307+
expectPending(current);
308+
expect(focused ? main : elsewhere).toHaveFocus();
309+
} finally {
310+
await act(async () => release());
311+
}
312+
expect(
313+
await screen.findByRole("heading", { name: "Membership" }),
314+
).toBeVisible();
296315
await waitFor(() =>
297-
expect(fixture.rosterReads.length).toBeGreaterThan(before),
316+
expect(current.navigation.snapshot().status).toBe("opened"),
298317
);
299-
expectPending(current);
300-
} finally {
301-
await act(async () => release());
302-
}
303-
expect(
304-
await screen.findByRole("heading", { name: "Membership" }),
305-
).toBeVisible();
306-
await waitFor(() =>
307-
expect(current.navigation.snapshot().status).toBe("opened"),
308-
);
309-
});
318+
},
319+
);
310320

311321
it("reconnects the selected Membership community after its transport fails", async () => {
312322
const fixture = membershipFixture();

‎tests/browser/navigation-repairs.spec.mjs‎

Lines changed: 40 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,26 +37,61 @@ test("Back restores Personal space without inheriting the active community", asy
3737
).toBeVisible();
3838
});
3939

40-
test("Retry navigation reconnects the failed target session", async ({
40+
test("keyboard Retry hands off focus while reconnecting a failed Messages tab opening", async ({
4141
page,
4242
app,
4343
}) => {
4444
let requests = 0;
45+
let release;
46+
const held = new Promise((resolve) => {
47+
release = resolve;
48+
});
4549
await page.route("**/api/relay/primary/session", async (route) => {
4650
requests++;
4751
if (requests === 1) return route.fulfill({ json: {} });
52+
await held;
4853
return route.continue();
4954
});
50-
await page.goto(app.origin);
51-
await openPage(page, "Messages", { connected: false });
55+
// Start outside Messages so its header activation owns preserve-focus intent.
56+
await page.goto(
57+
`${app.origin}/#buzz=${encodeURIComponent(JSON.stringify({ version: 1, kind: "settings" }))}`,
58+
);
59+
const messages = page.getByRole("tab", { name: "Messages", exact: true });
60+
await messages.focus();
61+
await messages.press("Enter");
5262
await expect(
5363
page.getByRole("heading", { name: "This destination couldn’t open" }),
5464
).toBeVisible();
55-
await button(page, "Retry navigation").click();
56-
await expect.poll(() => requests, { timeout: 1500 }).toBe(2);
65+
const visit = await entry(page);
66+
const retry = button(page, "Retry navigation");
67+
const main = page.getByRole("main");
68+
try {
69+
await retry.focus();
70+
await retry.press("Enter");
71+
await expect.poll(() => requests, { timeout: 1500 }).toBe(2);
72+
await expect(retry).toHaveCount(0);
73+
await expect(main).toBeFocused();
74+
} finally {
75+
release();
76+
}
5777
await expect(
5878
page.getByRole("textbox", { name: "Message #Alpha", exact: true }),
5979
).toBeVisible();
80+
await expect(main).toBeFocused();
81+
// Resolving Messages chooses its conversation in the same visit.
82+
expect(await entry(page)).toEqual({
83+
id: visit.id,
84+
target: {
85+
version: 1,
86+
kind: "conversation",
87+
channelId: "alpha",
88+
scope: visit.target.scope,
89+
},
90+
});
91+
await page.keyboard.press("Tab");
92+
await expect(
93+
page.getByRole("tabpanel", { name: "Messages", exact: true }),
94+
).toBeFocused();
6095
});
6196

6297
test("Skip to content focuses main without adding a visit or dropping Back", async ({

0 commit comments

Comments
 (0)