Skip to content

Commit 940b7a4

Browse files
fix(web): screen readers can browse and Tab through the settings sections again (pingdotgg#30841)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent ee21337 commit 940b7a4

7 files changed

Lines changed: 125 additions & 104 deletions

‎apps/web/src/components/settings/SettingsSidebarNav.composition.browser.test.tsx‎

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import { page, userEvent } from "vite-plus/test/browser";
44
import { act, render } from "../../../test/render";
55
import { SidebarProvider } from "../ui/sidebar";
66
import { SettingsSidebarNav } from "./SettingsSidebarNav";
7+
import { SETTINGS_NAV_GROUPS, SETTINGS_SECTION_LABELS } from "./settingsSearch";
78

89
vi.mock("./useAvailableSettingsSearchItems", () => ({
910
useAvailableSettingsSearchItems: () => [
@@ -43,13 +44,17 @@ it("ignores composing keys in the search", async () => {
4344
);
4445
});
4546

46-
it("opens search from the physical Slash and F keys on non-US layouts", async () => {
47-
await using _screen = await render(
47+
function renderNav() {
48+
return render(
4849
<SidebarProvider defaultOpen>
4950
<SettingsSidebarNav pathname="/settings/general" />
5051
</SidebarProvider>,
5152
{ router: "/settings/general" },
5253
);
54+
}
55+
56+
it("opens search from the physical Slash and F keys on non-US layouts", async () => {
57+
await using _screen = await renderNav();
5358
const search = page.getByRole("combobox", { name: "Search settings" });
5459

5560
for (const { init, opens } of [
@@ -65,3 +70,37 @@ it("opens search from the physical Slash and F keys on non-US layouts", async ()
6570
if (opens) await expect.element(search).toHaveFocus();
6671
}
6772
});
73+
74+
it("moves Tab through every settings section", async () => {
75+
await page.viewport(1280, 800);
76+
await using _screen = await renderNav();
77+
await userEvent.click(page.getByRole("combobox", { name: "Search settings" }));
78+
79+
const sections = SETTINGS_NAV_GROUPS.flatMap((group) => group.paths).map(
80+
(to) => SETTINGS_SECTION_LABELS[to],
81+
);
82+
const tabbed: string[] = [];
83+
for (let step = 0; step < sections.length; step += 1) {
84+
await userEvent.tab();
85+
const section = document.activeElement?.closest("[data-settings-section]");
86+
if (!section) break;
87+
tabbed.push(section.textContent ?? "");
88+
}
89+
expect(tabbed).toEqual(sections);
90+
});
91+
92+
it.each([1280, 390])("names each group by a heading outside it at %ipx wide", async (width) => {
93+
await page.viewport(width, 800);
94+
await using _screen = await renderNav();
95+
96+
for (const name of ["Agents", "Code", "Connections"]) {
97+
const heading = page.getByRole("heading", { name, level: 3 });
98+
await expect.element(heading).toBeInTheDocument();
99+
const group = page.getByRole("group", { name }).element();
100+
expect(group.getAttribute("aria-labelledby")).toBe(heading.element().id);
101+
expect(group.contains(heading.element()), `the ${name} heading is inside its group`).toBe(
102+
false,
103+
);
104+
}
105+
expect(page.getByRole("tree").query()).toBeNull();
106+
});

‎apps/web/src/components/settings/SettingsSidebarNav.tsx‎

Lines changed: 35 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ import {
5858
type SettingsSearchItem,
5959
} from "./settingsSearch";
6060
import { useAvailableSettingsSearchItems } from "./useAvailableSettingsSearchItems";
61-
import { useSettingsSectionNavigation } from "./useSettingsSectionNavigation";
61+
import { handleSettingsSectionKeyDown } from "./settingsSectionNavigation";
6262
import { workspaceAreaProps } from "../../lib/workspaceFocus";
6363

6464
const SnapShotIcon = createLucideIcon("snap-shot", [
@@ -133,12 +133,6 @@ export function SettingsSidebarNav({ pathname }: { pathname: string }) {
133133
const navigate = useNavigate();
134134
const currentHash = useLocation({ select: (location) => location.hash });
135135
const activePath = SETTINGS_DETAIL_PAGE_PARENTS[pathname] ?? pathname;
136-
const navPaths = SETTINGS_NAV_GROUPS.flatMap((group) => group.paths);
137-
const sectionNavigation = useSettingsSectionNavigation(
138-
navPaths.find((to) => activePath === to || activePath.startsWith(`${to}/`)) ??
139-
navPaths[0] ??
140-
"",
141-
);
142136
const searchInputRef = useRef<HTMLInputElement>(null);
143137
const [query, setQuery] = useState("");
144138
// Below md the nav is an icon rail; searching expands it over the page.
@@ -380,57 +374,55 @@ export function SettingsSidebarNav({ pathname }: { pathname: string }) {
380374
</SidebarMenuItem>
381375
</SidebarMenu>
382376
)}
383-
<div
384-
{...sectionNavigation.containerProps}
385-
role="tree"
386-
aria-label="Settings sections"
387-
className="flex flex-col gap-4"
388-
>
377+
<div onKeyDown={handleSettingsSectionKeyDown} className="flex flex-col gap-4">
389378
{SETTINGS_NAV_GROUPS.map((group, index) => (
390379
<div
391380
key={group.heading ?? index}
392-
role="group"
393-
aria-label={group.heading ?? undefined}
394381
className="flex flex-col gap-1 max-md:border-t max-md:border-sidebar-border max-md:pt-4 max-md:first:border-t-0 max-md:first:pt-0"
395382
>
396383
{group.heading ? (
397-
// The group carries this label; a heading is not a valid tree child.
398384
<h3
399-
aria-hidden="true"
385+
id={`settings-nav-group-${index}`}
400386
className={cn(
401387
"px-2 text-xs font-medium text-sidebar-muted-foreground/80",
402-
!compactSearchOpen && "max-md:hidden",
388+
!compactSearchOpen && "max-md:sr-only",
403389
)}
404390
>
405391
{group.heading}
406392
</h3>
407393
) : null}
408-
<SidebarMenu role="presentation">
409-
{group.paths.map((to) => {
410-
const Icon = SETTINGS_SECTION_ICONS[to];
411-
const isActive = activePath === to || activePath.startsWith(`${to}/`);
412-
return (
413-
<SidebarMenuItem key={to} role="presentation">
414-
<SidebarMenuButton
415-
data-settings-section={to}
416-
role="treeitem"
417-
tabIndex={sectionNavigation.tabIndexFor(to)}
418-
aria-selected={isActive}
419-
aria-current={isActive ? "page" : undefined}
420-
isActive={isActive}
421-
onClick={() => handleSectionClick(to)}
422-
>
423-
<Icon />
424-
<span
425-
className={cn("truncate", !compactSearchOpen && "max-md:sr-only")}
394+
{/* The heading stays outside the group it names so NVDA does not read the name twice. */}
395+
<div
396+
role="group"
397+
aria-labelledby={group.heading ? `settings-nav-group-${index}` : undefined}
398+
>
399+
<SidebarMenu>
400+
{group.paths.map((to) => {
401+
const Icon = SETTINGS_SECTION_ICONS[to];
402+
const isActive = activePath === to || activePath.startsWith(`${to}/`);
403+
return (
404+
<SidebarMenuItem key={to}>
405+
<SidebarMenuButton
406+
data-settings-section={to}
407+
aria-current={isActive ? "page" : undefined}
408+
isActive={isActive}
409+
onClick={() => handleSectionClick(to)}
426410
>
427-
{SETTINGS_SECTION_LABELS[to]}
428-
</span>
429-
</SidebarMenuButton>
430-
</SidebarMenuItem>
431-
);
432-
})}
433-
</SidebarMenu>
411+
<Icon />
412+
<span
413+
className={cn(
414+
"truncate",
415+
!compactSearchOpen && "max-md:sr-only",
416+
)}
417+
>
418+
{SETTINGS_SECTION_LABELS[to]}
419+
</span>
420+
</SidebarMenuButton>
421+
</SidebarMenuItem>
422+
);
423+
})}
424+
</SidebarMenu>
425+
</div>
434426
</div>
435427
))}
436428
</div>
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
import type { KeyboardEvent } from "react";
2+
3+
const SECTION = "[data-settings-section]";
4+
5+
/** Arrow keys move focus between settings sections without opening them. */
6+
export function handleSettingsSectionKeyDown(event: KeyboardEvent<HTMLElement>) {
7+
if (
8+
event.defaultPrevented ||
9+
event.altKey ||
10+
event.ctrlKey ||
11+
event.metaKey ||
12+
!(event.target instanceof HTMLElement) ||
13+
!event.target.matches(SECTION)
14+
)
15+
return;
16+
const items = Array.from(event.currentTarget.querySelectorAll<HTMLElement>(SECTION));
17+
const index = items.indexOf(event.target);
18+
const next =
19+
event.key === "ArrowDown"
20+
? Math.min(index + 1, items.length - 1)
21+
: event.key === "ArrowUp"
22+
? Math.max(index - 1, 0)
23+
: event.key === "Home"
24+
? 0
25+
: event.key === "End"
26+
? items.length - 1
27+
: undefined;
28+
const target = next === undefined ? undefined : items[next];
29+
if (!target) return;
30+
event.preventDefault();
31+
target.scrollIntoView({ block: "nearest" });
32+
target.focus({ preventScroll: true });
33+
}

‎apps/web/src/components/settings/useSettingsSectionNavigation.ts‎

Lines changed: 0 additions & 56 deletions
This file was deleted.

‎apps/web/src/lib/workspaceFocus.browser.test.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,19 @@ describe("workspace area focus", () => {
132132
expect(document.activeElement).toBe(nav.button);
133133
});
134134

135+
it("enters the Settings sections on the open section", () => {
136+
using fixture = setup();
137+
const nav = fixture.area("settings-nav", 0);
138+
const content = fixture.area("settings", 1);
139+
nav.element.insertAdjacentHTML(
140+
"beforeend",
141+
'<button data-settings-section="/settings/general">General</button><button data-settings-section="/settings/chat" aria-current="page">Chat</button>',
142+
);
143+
content.button.focus();
144+
fixture.controller.move(-1);
145+
expect(document.activeElement).toBe(nav.element.querySelector('[aria-current="page"]'));
146+
});
147+
135148
it("keeps moving while a shortcut recorder is on the page but not focused", () => {
136149
using fixture = setup();
137150
const nav = fixture.area("settings-nav", 0);

‎apps/web/src/lib/workspaceFocus.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ export function createWorkspaceFocusController(doc: Document) {
143143
// panel focuses it, but F6 visits that area on its own, so it moves past it here.
144144
const preferred = Array.from(
145145
area.querySelectorAll<HTMLElement>(
146-
'[data-workspace-focus-default], [data-sidebar-row][aria-current="page"], [data-settings-section][tabindex="0"], .xterm-helper-textarea, [contenteditable="true"]',
146+
'[data-workspace-focus-default], [data-sidebar-row][aria-current="page"], [data-settings-section][aria-current="page"], .xterm-helper-textarea, [contenteditable="true"]',
147147
),
148148
).find(nested ? usable : belongs);
149149
const fallback = Array.from(area.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).find(

‎docs/user/keyboard-focus.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,5 +33,5 @@ expand and collapse groups. `F2` renames the focused thread.
3333
Press `Shift+F10` or the Context Menu key to open the focused thread's menu. Use the arrow
3434
keys to move through it, Enter to choose, and Escape to close it.
3535

36-
The Settings section list works the same way: Up and Down move between sections, and Enter
37-
opens one.
36+
The Settings section list works the same way: Tab moves through each section, Up and Down
37+
also move between sections without opening them, and Enter opens one.

0 commit comments

Comments
 (0)