fix(site/src): make keyboard-inaccessible controls operable by keyboard (#31656)

Makes the controls that the Deque audit flagged as
`keyboard-inaccessible` (WCAG 2.1.1) reachable and operable with the
keyboard alone.

- **Comboboxes without a search input** (`SelectFilter` status, action,
and resource type menus): on open, focus moves to the command listbox
instead of the popover, so the arrow keys and Enter now work. The
listbox does not draw its own outline because the highlighted option
already has a ring.
- **Date range picker**: no longer blocks the popover's auto-focus, so
focus lands on the selected quick-range radio.
- **Notification inbox item**: the mark-as-read button is visually
hidden (not `display: none`) until the item is hovered or contains
focus, so it stays in the tab order.
- **Workspace breadcrumb** (owner, organization, workspace): the popover
triggers are real `<button>`s instead of `<span>`s. This also clears 3
critical `aria-allowed-attr` axe violations on main:
  - Closes DEQ-143 (owner breadcrumb)
  - Closes DEQ-25 (organization breadcrumb)
  - Closes DEQ-552 (workspace breadcrumb)
- **AI Gateway session threads**: the Back button is a real button again
instead of a `span` rendered through `asChild`.
- **Build timeline**: stage info icons use `InfoTooltip` (a focusable
button), and resource bars are focusable like the script bars.

Closes DEQ-198
Closes DEQ-214
Closes DEQ-289
Closes DEQ-338
Closes DEQ-394
Closes DEQ-502
Closes DEQ-542
Closes DEQ-545
Refs DEQ-493

| Ticket | Surface | Change |
| --- | --- | --- |
| DEQ-198 | AI Gateway session threads Back button (el 1) | El 2
(session info/token tooltips) was already fixed on main by
#30403/#30424. |
| DEQ-214 | AI Gateway sessions date range picker (el 1), filter menus
(el 2) | El 3 (header info icon) was already fixed on main by #30403. |
| DEQ-289 | SMTP settings icons | Already fixed on main by #30403. No
change here. |
| DEQ-338 | Audit log filter menus (el 1) | El 2 (row info icon) was
already fixed on main by #30403. |
| DEQ-394 | Users status filter menu (el 1) | El 2 (`+N more` roles) was
already fixed on main by #30342. |
| DEQ-493 | Workspace breadcrumb (el 1), timeline stage info icons (el
4), resource bars (el 5) | Els 2 and 3 are still open; see below. |
| DEQ-502 | Footer items | Already fixed on main by #30403/#30424. No
change here. |
| DEQ-542 | Workspaces status filter menu (el 1) | El 2 (sharing
indicator) was already fixed on main by #30403. |
| DEQ-545 | Notification inbox mark-as-read | See screenshots below. |

### Screenshots

From Storybook, main (before) versus this branch (after).

| Surface | Before | After |
| --- | --- | --- |
| Back button focused (DEQ-198) | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/back-before.png"
alt="back before" width="400"> | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/back-after.png"
alt="back after" width="400"> |
| Date range picker opened with Enter: focus on the selected quick range
(DEQ-214) | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/timerange-before.png"
alt="timerange before" width="400"> | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/timerange-after.png"
alt="timerange after" width="400"> |
| Filter menu opened with Enter: focus on the listbox (DEQ-214, 338,
394, 542) | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/selectfilter-before.png"
alt="selectfilter before" width="400"> | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/selectfilter-after.png"
alt="selectfilter after" width="400"> |
| Unread inbox item focused: mark-as-read visible and tabbable (DEQ-545)
| <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/inbox-before.png"
alt="inbox before" width="400"> | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/inbox-after.png"
alt="inbox after" width="400"> |
| Workspace breadcrumb focused (DEQ-493 el 1) | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/topbar-before.png"
alt="topbar before" width="400"> | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/topbar-after.png"
alt="topbar after" width="400"> |
| Timeline stage info icon focused (DEQ-493 el 4) | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/stageinfo-before.png"
alt="stageinfo before" width="400"> | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/stageinfo-after.png"
alt="stageinfo after" width="400"> |
| Resource bar focused (DEQ-493 el 5) | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/resourcebar-before.png"
alt="resourcebar before" width="400"> | <img
src="https://raw.githubusercontent.com/coder/coder/de81a391f8bd327309e293d0f11aec037b205586/pr-31656/resourcebar-after.png"
alt="resourcebar after" width="400"> |

**Not fixed here (DEQ-493 stays open):**
- El 2, the build-reason info icon in the history sidebar
(`WorkspaceBuildData`): the icon sits inside the build row's `<a>` in
both callers, so a focusable trigger would nest one interactive control
inside another. Fixing it needs a layout change that moves the icon out
of the link, or a different way to show the reason.
- El 3, the log source icons in AgentLogs: they repeat on every line of
a virtualized list, so making each one a tab stop would add one stop per
log line. This needs a design decision, for example showing the source
name as text or as a single legend.

**Review findings not acted on:**
- The ResourcesChart tooltip's "view template" link has a placeholder
`to=""`. This is pre-existing and out of scope.
- The visually hidden mark-as-read button stays in the tab order on
purpose: it becomes visible when focused, like a skip link.
- The breadcrumb buttons reset styles that preflight already resets, to
match the Tooltip trigger pattern.
- Not verified: whether the `InfoTooltip` focus ring is clipped by the
YAxisLabel `overflow-hidden`. The focused-stage story is there for Pixel
to show it.
- Pre-existing axe findings that this PR does not touch:
`aria-dialog-name` (popover), `scrollable-region-focusable`
(SelectFilter list), `list` (timings).

<details>
<summary>Grouping and decision log</summary>

- One PR for the whole `keyboard-inaccessible` label, following the
one-PR-per-axe-rule convention. About 89 non-test lines, all under
`site/`.
- Checked every element on all nine tickets against main first. #30403
(focusable tooltip triggers), #30424 (interactive tooltips), and #30342
already fixed several of them, and the table records those.
- Comboboxes: the fix lives in the shared `ComboboxContent`, so every
search-less combobox gets it. It only takes over auto-focus when no
`[cmdk-input]` is present and the caller has not prevented it.
- Date range picker: the `preventDefault` on `onOpenAutoFocus` dates
from #28392. Without it, Radix focuses the first tabbable element, which
is the selected radio.
- New Vitest tests (`SelectFilter.test.tsx`, plus one in
`DateTimeRangePicker.test.tsx`) fail on main and pass here. New
focus-state stories (`UnreadFocused`, `WorkspaceBreadcrumbFocused`,
`StageInfoFocused`, `ResourceBarFocused`) only set up focus for Pixel
screenshots.
- Inbox stories now scope the mark-as-read query to one item, because
every unread item's button is now in the accessibility tree.
- The breadcrumb buttons measure about 2px narrower than the old spans
because of sub-pixel rounding. Accepted as negligible.
- Ran `pnpm check`, `pnpm lint`, `pnpm format`, the targeted unit tests
(245 passed), Storybook tests for the affected areas (296 passed), the
frontend-review FE1–FE10 audit, and frontend-deep-review. Applied its
fixes: `InfoTooltip` instead of a hand-rolled trigger, a `not-*` variant
instead of `not-sr-only`, focusing the cmdk list, and stories with no
play assertions.

</details>

🤖 Generated by Coder Agents on behalf of @aqandrew.
This commit is contained in:
Andrew Aquino authored and GitHub committed 2026-11-04 14:08:45 -08:00
1 parent 2cab0e8c37
commit 42640dc831
15 files changed
+154 -37

No files matched your search

+20 -3
View File
@@ -1,7 +1,7 @@
import { cn } from "cn";
import { CheckIcon } from "lucide-react";
import type React from "react";
import { createContext, useContext, useState } from "react";
import { createContext, useContext, useRef, useState } from "react";
import { ChevronDownIcon } from "#/components/AnimatedIcons/ChevronDown";
import { Button } from "#/components/Button/Button";
import {
@@ -106,8 +106,11 @@ export const ComboboxContent = ({
className,
ref,
shouldFilter,
onOpenAutoFocus,
...props
}: ComboboxContentProps) => {
const commandRef = useRef<HTMLDivElement>(null);
return (
<PopoverContent
ref={ref}
@@ -115,9 +118,23 @@ export const ComboboxContent = ({
"flex w-auto flex-col overflow-y-hidden border-border text-sm",
className,
)}
onOpenAutoFocus={(event) => {
onOpenAutoFocus?.(event);
// Without a search input, focus would land on the popover itself,
// where the arrow keys never reach the command list.
const root = commandRef.current;
if (!event.defaultPrevented && !root?.querySelector("[cmdk-input]")) {
event.preventDefault();
root?.querySelector<HTMLElement>("[cmdk-list]")?.focus();
}
}}
{...props}
>
<Command shouldFilter={shouldFilter} className="min-h-0 flex-1">
<Command
ref={commandRef}
shouldFilter={shouldFilter}
className="min-h-0 flex-1"
>
{children}
</Command>
</PopoverContent>
@@ -131,7 +148,7 @@ export const ComboboxList: React.FC<
> = ({ className, ...props }) => {
return (
<CommandList
className={cn("max-h-none min-h-0 flex-1 p-2", className)}
className={cn("max-h-none min-h-0 flex-1 p-2 outline-hidden", className)}
{...props}
/>
);
@@ -61,3 +61,30 @@ it("applies a start on the minDate day only once it is past the cutoff", async (
end: new Date(2026, 3, 10, 23, 59, 59),
});
});
it("picks a quick range with the keyboard alone", async () => {
const user = userEvent.setup();
const onChange = vi.fn();
const now = new Date(2026, 3, 16, 10, 30);
render(
<DateTimeRangePicker
now={now}
value={{
start: new Date(2026, 3, 15, 10, 30),
end: now,
preset: "last_24h",
}}
onChange={onChange}
/>,
);
await user.tab();
await user.keyboard("{Enter}");
expect(
await screen.findByRole("radio", { name: "Last 24 hours" }),
).toHaveFocus();
await user.keyboard("{ArrowDown}{Enter}");
expect(onChange).toHaveBeenCalledWith(
expect.objectContaining({ preset: "today" }),
);
});
@@ -275,7 +275,6 @@ export const DateTimeRangePicker: React.FC<DateTimeRangePickerProps> = ({
<PopoverContent
className="w-auto p-0 overflow-x-hidden overflow-y-auto"
align="end"
onOpenAutoFocus={(e) => e.preventDefault()}
>
<div className="flex">
{/* Quick picks. This list is the entire dropdown until the
@@ -0,0 +1,26 @@
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { expect, it, vi } from "vitest";
import { SelectFilter } from "./SelectFilter";
it("selects an option with the keyboard alone", async () => {
const user = userEvent.setup();
const onSelect = vi.fn();
render(
<SelectFilter
label="Select a status"
placeholder="All statuses"
options={[
{ label: "Active", value: "active" },
{ label: "Dormant", value: "dormant" },
]}
onSelect={onSelect}
/>,
);
await user.tab();
await user.keyboard("{Enter}");
await screen.findByRole("option", { name: "Active" });
await user.keyboard("{ArrowDown}{Enter}");
expect(onSelect).toHaveBeenCalledWith({ label: "Dormant", value: "dormant" });
});
@@ -106,3 +106,16 @@ export const OnMarkNotificationAsRead: Story = {
pixel: { exclude: true },
},
};
export const UnreadFocused: Story = {
args: {
notification: {
...MockNotification,
read_at: null,
actions: [],
},
},
play: async () => {
await userEvent.tab();
},
};
@@ -69,13 +69,14 @@ export const InboxItem: React.FC<InboxItemProps> = ({
<div className="w-12 flex flex-col items-end shrink-0">
{notification.read_at === null && (
<>
<div className="group-focus:hidden group-hover:hidden size-2.5 rounded-full bg-highlight-sky">
<div className="group-focus-within:hidden group-hover:hidden size-2.5 rounded-full bg-highlight-sky">
<span className="sr-only">Unread</span>
</div>
{/* Visually hidden instead of display: none so it stays in the tab order. */}
<Button
onClick={() => onMarkNotificationAsRead(notification.id)}
className="hidden group-focus:flex group-hover:flex bg-surface-primary"
className="not-group-hover:not-group-focus-within:sr-only bg-surface-primary"
variant="outline"
size="sm"
>
@@ -109,7 +109,9 @@ export const OnMarkNotificationAsRead: Story = {
).getAllByRole("listitem");
const secondNotification = notifications[1];
await userEvent.click(secondNotification);
const markButton = body.getByRole("button", { name: /mark as read/i });
const markButton = within(secondNotification).getByRole("button", {
name: /mark as read/i,
});
await userEvent.click(markButton);
await expect(args.onMarkNotificationAsRead).toHaveBeenCalledTimes(1);
await expect(args.onMarkNotificationAsRead).toHaveBeenCalledWith(
@@ -153,7 +153,9 @@ export const MarkNotificationAsRead: Story = {
within(secondNotification).getByText(/unread/i);
await userEvent.click(secondNotification);
const markButton = body.getByRole("button", { name: /mark as read/i });
const markButton = within(secondNotification).getByRole("button", {
name: /mark as read/i,
});
await userEvent.click(markButton);
await expect(within(secondNotification).queryByText(/unread/i)).toBeNull();
},
@@ -178,7 +180,9 @@ export const MarkNotificationAsReadFailure: Story = {
).getAllByRole("listitem");
const secondNotification = notifications[1];
await userEvent.click(secondNotification);
const markButton = body.getByRole("button", { name: /mark as read/i });
const markButton = within(secondNotification).getByRole("button", {
name: /mark as read/i,
});
await userEvent.click(markButton);
await body.findByText("Failed to mark notification as read");
},
@@ -36,6 +36,7 @@ export const Bar: React.FC<BarProps> = ({
className={cn(
"relative flex h-[inherit] min-w-6 rounded-lg border border-border bg-surface-primary p-[7px]",
"after:absolute after:inset-y-[-2px] after:left-[-8px] after:right-[-8px] after:content-['']",
"outline-hidden focus-visible:ring-2 focus-visible:ring-content-link",
htmlProps.className,
)}
style={barStyle({ colors, scale, value, offset, style: htmlProps.style })}
@@ -126,6 +126,9 @@ export const ResourcesChart: React.FC<ResourcesChartProps> = ({
<Tooltip>
<TooltipTrigger asChild>
<Bar
role="img"
aria-label={`${label}: ${legend.label}`}
tabIndex={0}
value={duration}
offset={calcOffset(t.range, generalTiming)}
scale={scale}
@@ -1,10 +1,6 @@
import { CircleAlertIcon, InfoIcon } from "lucide-react";
import { CircleAlertIcon } from "lucide-react";
import type { TimingStage } from "#/api/typesGenerated";
import {
Tooltip,
TooltipContent,
TooltipTrigger,
} from "#/components/Tooltip/Tooltip";
import { InfoTooltip } from "#/components/InfoTooltip/InfoTooltip";
import { Bar, ClickableBar } from "./Chart/Bar";
import { Blocks } from "./Chart/Blocks";
import { Chart, ChartContent } from "./Chart/Chart";
@@ -110,20 +106,18 @@ export const StagesChart: React.FC<StagesChartProps> = ({
>
<span className="flex items-center justify-end gap-0.5">
{stage.label}
<Tooltip>
<TooltipTrigger asChild>
<InfoIcon className="size-icon-xs cursor-pointer text-content-secondary" />
</TooltipTrigger>
<TooltipContent
side="bottom"
className="flex flex-col gap-1.5 max-w-xs border-surface-quaternary"
>
<InfoTooltip
ariaLabel={`About ${stage.label}`}
side="bottom"
size="small"
>
<div className="flex flex-col gap-1.5">
<p className="m-0 text-content-primary">
{stage.tooltip.heading}
</p>
<p className="m-0">{stage.tooltip.description}</p>
</TooltipContent>
</Tooltip>
</div>
</InfoTooltip>
</span>
</YAxisLabel>
))}
@@ -228,6 +228,23 @@ export const NavigateToPlanStage: Story = {
},
};
export const StageInfoFocused: Story = {
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
canvas.getByRole("button", { name: "About plan" }).focus();
},
};
export const ResourceBarFocused: Story = {
play: async ({ canvasElement }) => {
const user = userEvent.setup();
const canvas = within(canvasElement);
await user.click(canvas.getByRole("button", { name: "View plan details" }));
const [firstBar] = await canvas.findAllByRole("img");
firstBar.focus();
},
};
// Navigating into a workspace boot stage
export const NavigateToStartStage: Story = {
play: async ({ canvasElement }) => {
@@ -117,16 +117,13 @@ export const SessionThreadsPageView: React.FC<SessionThreadsPageViewProps> = ({
<>
<nav className="mb-6 flex flex-col md:flex-row md:items-start justify-between gap-4">
<Button
asChild
variant="outline"
size="lg"
title="Back to AI Gateway sessions list"
onClick={onBackClicked}
>
<span>
<ArrowLeftIcon />
Back
</span>
<ArrowLeftIcon />
Back
</Button>
{session && (
<div className="flex flex-col items-stretch md:items-end gap-1 md:w-[28rem]">
@@ -320,6 +320,13 @@ export const WithQuotaWithOrgs: Story = {
},
};
export const WorkspaceBreadcrumbFocused: Story = {
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
canvas.getByRole("button", { name: baseWorkspace.name }).focus();
},
};
export const TemplateInfoPopover: Story = {
play: async ({ canvasElement, step }) => {
const canvas = within(canvasElement);
@@ -39,6 +39,8 @@ import { WorkspaceScheduleControls } from "./WorkspaceScheduleControls";
const BREADCRUMB_SEGMENT_CLASS = cn(
"flex items-center flex-row flex-nowrap gap-2",
"max-w-40 whitespace-nowrap cursor-default",
"m-0 p-0 border-0 bg-transparent text-inherit rounded-sm",
"focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-content-link",
);
const BREADCRUMB_TEXT_CLASS = "overflow-x-hidden text-ellipsis";
@@ -266,10 +268,15 @@ const OwnerBreadcrumb: React.FC<OwnerBreadcrumbProps> = ({
return (
<HelpPopover>
<HelpPopoverTrigger asChild>
<span className={BREADCRUMB_SEGMENT_CLASS}>
<Avatar size="sm" fallback={ownerName} src={ownerAvatarUrl} />
<button type="button" className={BREADCRUMB_SEGMENT_CLASS}>
<Avatar
size="sm"
fallback={ownerName}
src={ownerAvatarUrl}
aria-hidden
/>
<span className={BREADCRUMB_TEXT_CLASS}>{ownerName}</span>
</span>
</button>
</HelpPopoverTrigger>
<HelpPopoverContent align="center">
@@ -293,15 +300,16 @@ const OrganizationBreadcrumb: React.FC<OrganizationBreadcrumbProps> = ({
return (
<HelpPopover>
<HelpPopoverTrigger asChild>
<span className={BREADCRUMB_SEGMENT_CLASS}>
<button type="button" className={BREADCRUMB_SEGMENT_CLASS}>
<Avatar
size="sm"
variant="icon"
src={orgIconUrl}
fallback={orgName}
aria-hidden
/>
<span className={BREADCRUMB_TEXT_CLASS}>{orgName}</span>
</span>
</button>
</HelpPopoverTrigger>
<HelpPopoverContent align="center">
@@ -354,16 +362,17 @@ const WorkspaceBreadcrumb: React.FC<WorkspaceBreadcrumbProps> = ({
<div className="flex items-center">
<HelpPopover>
<HelpPopoverTrigger asChild>
<span className={BREADCRUMB_SEGMENT_CLASS}>
<button type="button" className={BREADCRUMB_SEGMENT_CLASS}>
<TopbarAvatar
src={templateIconUrl}
fallback={templateDisplayName}
aria-hidden
/>
<span className={cn(BREADCRUMB_TEXT_CLASS, "font-medium")}>
{workspaceName}
</span>
</span>
</button>
</HelpPopoverTrigger>
<HelpPopoverContent align="center">