feat(web): cycle linked reviews with held shortcut (#2099)

This commit is contained in:
José Almeida
2026-07-31 16:15:32 +01:00
committed by GitHub
parent 441c8a34ac
commit abf21f52a6
16 changed files with 1427 additions and 117 deletions
@@ -5,6 +5,7 @@ import {
hasHoldModifier,
isCommitReleaseEvent,
isCycleShortcutEvent,
isHeldCycleKeyEvent,
} from "./recent-task-switcher-keys";
function event(overrides: Partial<KeyboardEvent>): KeyboardEvent {
@@ -63,6 +64,20 @@ describe("recent task switcher key helpers", () => {
).toBe(false);
});
it("continues cycling with only the primary hold modifier", () => {
const shortcut: KeyboardShortcut = {
key: KEYS.G,
modifiers: { ctrlOrCmd: true, shift: true },
};
expect(
isHeldCycleKeyEvent(event({ key: KEYS.G, ctrlKey: true }), shortcut, platform("linux")),
).toBe(true);
expect(
isHeldCycleKeyEvent(event({ key: KEYS.G, shiftKey: true }), shortcut, platform("linux")),
).toBe(false);
});
it("matches custom multi-modifier cycle shortcuts", () => {
const shortcut: KeyboardShortcut = {
key: KEYS.Y,
@@ -35,6 +35,46 @@ export function isCycleShortcutEvent(event: KeyboardEvent, shortcut: KeyboardSho
return matchesShortcut(event, shortcut);
}
/**
* Make ctrlOrCmd's hold modifier match the key that opened this interaction.
* Browsers accept either Control or Meta for ctrlOrCmd, including off-platform
* variants such as Control on macOS.
*/
export function snapshotHeldShortcut(
event: KeyboardEvent,
shortcut: KeyboardShortcut,
): KeyboardShortcut {
if (!shortcut.modifiers?.ctrlOrCmd || event.ctrlKey === event.metaKey) return shortcut;
const { ctrlOrCmd: _ctrlOrCmd, ...modifiers } = shortcut.modifiers;
return {
...shortcut,
modifiers: { ...modifiers, ...(event.ctrlKey ? { ctrl: true } : { cmd: true }) },
};
}
function isHoldModifierPressed(event: KeyboardEvent, modifier: HoldModifier): boolean {
if (modifier === MODIFIER_KEYS.CMD) return event.metaKey;
if (modifier === MODIFIER_KEYS.CTRL) return event.ctrlKey;
if (modifier === MODIFIER_KEYS.ALT) return event.altKey;
return event.shiftKey;
}
/**
* Match a deliberate switcher continuation key press. Once a picker is open,
* its primary hold modifier is sufficient; secondary modifiers may be released.
*/
export function isHeldCycleKeyEvent(
event: KeyboardEvent,
shortcut: KeyboardShortcut,
platform?: Platform,
): boolean {
if (event.repeat || event.key.toLowerCase() !== shortcut.key.toLowerCase()) return false;
const holdModifier = getHoldModifier(shortcut, platform);
return holdModifier
? isHoldModifierPressed(event, holdModifier)
: matchesShortcut(event, shortcut);
}
export function isCommitReleaseEvent(
event: KeyboardEvent,
shortcut: KeyboardShortcut,
@@ -58,12 +58,19 @@ describe("resolveTaskReviewOpenAction", () => {
expect(resolveTaskReviewOpenAction([], [mr])).toEqual({
kind: "open",
url: mr.mr_url,
target: { type: "mr", key: "mr:mr-1", url: mr.mr_url, review: mr },
});
});
it("uses the provider-aware picker for mixed linked reviews", () => {
const pr = makePR({ id: "pr" });
const mr = { id: "mr", mr_url: "https://gitlab.com/a/b/-/merge_requests/2" } as TaskMR;
expect(resolveTaskReviewOpenAction([pr], [mr])).toEqual({ kind: "pick" });
expect(resolveTaskReviewOpenAction([pr], [mr])).toMatchObject({
kind: "pick",
targets: [
{ type: "pr", key: "pr:pr", url: pr.pr_url, review: pr },
{ type: "mr", key: "mr:mr", url: mr.mr_url, review: mr },
],
});
});
});
+17 -6
View File
@@ -19,12 +19,23 @@ export function resolveTaskPROpenAction(prs: TaskPR[]): TaskPROpenAction {
export type TaskReviewOpenAction =
| { kind: "none" }
| { kind: "open"; url: string }
| { kind: "pick" };
| { kind: "open"; url: string; target: TaskReviewTarget }
| { kind: "pick"; targets: TaskReviewTarget[] };
export type TaskReviewTarget =
| { type: "pr"; key: string; url: string; review: TaskPR }
| { type: "mr"; key: string; url: string; review: TaskMR };
export function buildTaskReviewTargets(prs: TaskPR[], mrs: TaskMR[]): TaskReviewTarget[] {
return [
...prs.map((pr) => ({ type: "pr" as const, key: `pr:${pr.id}`, url: pr.pr_url, review: pr })),
...mrs.map((mr) => ({ type: "mr" as const, key: `mr:${mr.id}`, url: mr.mr_url, review: mr })),
];
}
export function resolveTaskReviewOpenAction(prs: TaskPR[], mrs: TaskMR[]): TaskReviewOpenAction {
const urls = [...prs.map((pr) => pr.pr_url), ...mrs.map((mr) => mr.mr_url)];
if (urls.length === 0) return { kind: "none" };
if (urls.length === 1) return { kind: "open", url: urls[0] };
return { kind: "pick" };
const targets = buildTaskReviewTargets(prs, mrs);
if (targets.length === 0) return { kind: "none" };
if (targets.length === 1) return { kind: "open", url: targets[0].url, target: targets[0] };
return { kind: "pick", targets };
}
@@ -0,0 +1,107 @@
import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
import { useState } from "react";
import { afterEach, describe, expect, it, vi } from "vitest";
import type { TaskPR } from "@/lib/types/github";
import type { TaskMR } from "@/lib/types/gitlab";
import type { TaskReviewTarget } from "./task-pr-open";
import { TaskPRPickerDialog } from "./task-pr-picker-dialog";
const targets: TaskReviewTarget[] = [
{
type: "pr",
key: "pr:1",
url: "https://github.com/acme/kandev/pull/1",
review: {
id: "pr-1",
repo: "kandev",
pr_number: 1,
pr_title: "GitHub review",
state: "open",
checks_state: "",
checks_total: 0,
checks_passing: 0,
review_state: "",
mergeable_state: "",
review_count: 0,
pending_review_count: 0,
} as TaskPR,
},
{
type: "mr",
key: "mr:2",
url: "https://gitlab.example/acme/kandev/-/merge_requests/2",
review: {
id: "mr-2",
project_path: "acme/kandev",
mr_iid: 2,
mr_title: "GitLab review",
mr_url: "https://gitlab.example/acme/kandev/-/merge_requests/2",
state: "opened",
} as TaskMR,
},
];
const selectedAttribute = "data-selected";
function ControlledPicker({ onActivateIndex }: { onActivateIndex: (index: number) => void }) {
const [selectedIndex, setSelectedIndex] = useState(0);
return (
<TaskPRPickerDialog
open
onOpenChange={() => undefined}
targets={targets}
selectedIndex={selectedIndex}
onSelectedIndexChange={setSelectedIndex}
onActivateIndex={onActivateIndex}
/>
);
}
describe("TaskPRPickerDialog", () => {
afterEach(() => cleanup());
it("keeps controlled selection, focus, arrow keys, Enter, and click in sync", async () => {
const onActivateIndex = vi.fn();
render(<ControlledPicker onActivateIndex={onActivateIndex} />);
const prRow = screen.getByTestId("task-pr-picker-row-pr-1");
const mrRow = screen.getByTestId("task-mr-picker-row-mr-2");
expect(prRow.compareDocumentPosition(mrRow)).toBe(Node.DOCUMENT_POSITION_FOLLOWING);
await waitFor(() => expect(document.activeElement).toBe(prRow));
expect(prRow.getAttribute(selectedAttribute)).toBe("true");
fireEvent.keyDown(prRow, { key: "ArrowDown" });
await waitFor(() => expect(document.activeElement).toBe(mrRow));
expect(mrRow.getAttribute(selectedAttribute)).toBe("true");
fireEvent.keyDown(mrRow, { key: "ArrowDown" });
await waitFor(() => expect(document.activeElement).toBe(prRow));
expect(prRow.getAttribute(selectedAttribute)).toBe("true");
fireEvent.keyDown(prRow, { key: "ArrowUp" });
await waitFor(() => expect(document.activeElement).toBe(mrRow));
fireEvent.keyDown(mrRow, { key: "Enter" });
fireEvent.click(prRow);
expect(onActivateIndex).toHaveBeenNthCalledWith(1, 1);
expect(onActivateIndex).toHaveBeenNthCalledWith(2, 0);
});
it("activates the row focused with Tab when Enter is pressed", async () => {
const onActivateIndex = vi.fn();
render(<ControlledPicker onActivateIndex={onActivateIndex} />);
const prRow = screen.getByTestId("task-pr-picker-row-pr-1");
const mrRow = screen.getByTestId("task-mr-picker-row-mr-2");
await waitFor(() => expect(document.activeElement).toBe(prRow));
mrRow.focus();
expect(document.activeElement).toBe(mrRow);
await waitFor(() => expect(mrRow.getAttribute(selectedAttribute)).toBe("true"));
fireEvent.keyDown(mrRow, { key: "Enter" });
expect(onActivateIndex).toHaveBeenCalledWith(1);
});
});
@@ -1,6 +1,6 @@
"use client";
import { useRef, type KeyboardEvent } from "react";
import { useCallback, useEffect, useRef, type KeyboardEvent } from "react";
import { IconGitPullRequest } from "@tabler/icons-react";
import {
Dialog,
@@ -11,67 +11,124 @@ import {
} from "@kandev/ui/dialog";
import { cn } from "@/lib/utils";
import { getPRStatusColor } from "@/components/github/pr-task-icon";
import { openExternalLink } from "@/lib/desktop/external-links";
import type { TaskPR } from "@/lib/types/github";
import type { TaskMR } from "@/lib/types/gitlab";
import type { TaskReviewTarget } from "./task-pr-open";
type TaskPRPickerDialogProps = {
open: boolean;
onOpenChange: (open: boolean) => void;
prs: TaskPR[];
mrs?: TaskMR[];
targets: TaskReviewTarget[];
selectedIndex: number;
onSelectedIndexChange: (index: number) => void;
onActivateIndex: (index: number) => void;
};
type TaskReviewRowProps = {
target: TaskReviewTarget;
index: number;
selected: boolean;
onActivate: (index: number) => void;
onFocus: (index: number) => void;
};
function TaskReviewRow({ target, index, selected, onActivate, onFocus }: TaskReviewRowProps) {
const isMergeRequest = target.type === "mr";
const testId = isMergeRequest
? `task-mr-picker-row-${target.review.id}`
: `task-pr-picker-row-${target.review.id}`;
const iconClass = target.type === "pr" ? getPRStatusColor(target.review) : "text-orange-500";
const reviewLabel =
target.type === "pr"
? `${target.review.repo} #${target.review.pr_number}`
: `${target.review.project_path} !${target.review.mr_iid}`;
const reviewTitle = target.type === "pr" ? target.review.pr_title : target.review.mr_title;
return (
<button
key={target.key}
type="button"
data-pr-row
data-row-index={index}
data-selected={selected ? "true" : undefined}
data-testid={testId}
aria-current={selected ? "true" : undefined}
onClick={() => onActivate(index)}
onFocus={() => onFocus(index)}
className={cn(
"flex cursor-pointer items-center gap-2 rounded-md border border-transparent px-2 py-2 text-left text-sm transition-colors hover:border-border hover:bg-muted/40 focus:border-primary/70 focus:outline-none",
isMergeRequest && "min-h-11",
selected && "border-primary/70 bg-muted/40",
)}
>
<IconGitPullRequest className={cn("h-4 w-4 shrink-0", iconClass)} />
<span className="min-w-0 flex-1 truncate">
<span className="font-medium">{reviewLabel}</span>{" "}
<span className="text-muted-foreground">{reviewTitle}</span>
</span>
<span className="shrink-0 text-xs capitalize text-muted-foreground">
{target.review.state}
</span>
</button>
);
}
/**
* Picker shown by the open-task-PR shortcut when a task has several linked
* PRs. A scrollable list of rows; ArrowUp/ArrowDown move focus (wrapping),
* Enter or click opens the focused PR on GitHub and closes the dialog.
* reviews. A scrollable list of rows; ArrowUp/ArrowDown move the selected row
* (wrapping), Enter or click opens it and closes the dialog.
*/
export function TaskPRPickerDialog({ open, onOpenChange, prs, mrs = [] }: TaskPRPickerDialogProps) {
export function TaskPRPickerDialog({
open,
onOpenChange,
targets,
selectedIndex,
onSelectedIndexChange,
onActivateIndex,
}: TaskPRPickerDialogProps) {
const listRef = useRef<HTMLDivElement>(null);
const hasMergeRequests = targets.some((target) => target.type === "mr");
const openPR = (pr: TaskPR) => {
void openExternalLink(pr.pr_url).catch(() => undefined);
onOpenChange(false);
};
const openMR = (mr: TaskMR) => {
void openExternalLink(mr.mr_url).catch(() => undefined);
onOpenChange(false);
};
const focusRow = useCallback((index: number) => {
listRef.current
?.querySelector<HTMLButtonElement>(`button[data-pr-row][data-row-index="${index}"]`)
?.focus();
}, []);
useEffect(() => {
if (open) focusRow(selectedIndex);
}, [focusRow, open, selectedIndex]);
const onListKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return;
e.preventDefault();
const rows = Array.from(
listRef.current?.querySelectorAll<HTMLButtonElement>("button[data-pr-row]") ?? [],
);
if (rows.length === 0) return;
const idx = rows.findIndex((row) => row === document.activeElement);
const delta = e.key === "ArrowDown" ? 1 : -1;
if (idx === -1) {
rows[delta === 1 ? 0 : rows.length - 1].focus();
if (e.key === "Enter") {
e.preventDefault();
onActivateIndex(selectedIndex);
return;
}
rows[(idx + delta + rows.length) % rows.length].focus();
if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return;
e.preventDefault();
if (targets.length === 0) return;
const delta = e.key === "ArrowDown" ? 1 : -1;
onSelectedIndexChange((selectedIndex + delta + targets.length) % targets.length);
};
// Focus the first PR row explicitly on open instead of relying on Radix's
// implicit first-focusable ordering, so keyboard flow (ArrowDown/Enter)
// stays stable if the dialog template's DOM order changes.
const focusFirstRow = (e: Event) => {
// Explicit focus keeps keyboard arrows and held-shortcut selection in sync.
const focusSelectedRow = (e: Event) => {
e.preventDefault();
listRef.current?.querySelector<HTMLButtonElement>("button[data-pr-row]")?.focus();
focusRow(selectedIndex);
};
return (
<Dialog open={open} onOpenChange={onOpenChange}>
<DialogContent className="w-[calc(100vw-2rem)] sm:max-w-lg" onOpenAutoFocus={focusFirstRow}>
<DialogContent
className="w-[calc(100vw-2rem)] sm:max-w-lg"
enterConfirms={false}
onOpenAutoFocus={focusSelectedRow}
>
<DialogHeader>
<DialogTitle>{mrs.length ? "Open code review" : "Open pull request"}</DialogTitle>
<DialogTitle>{hasMergeRequests ? "Open code review" : "Open pull request"}</DialogTitle>
<DialogDescription>
{mrs.length
{hasMergeRequests
? "Choose a linked pull request or merge request to open at its provider."
: `This task has ${prs.length} linked pull requests. Choose one to open on GitHub.`}
: `This task has ${targets.length} linked pull requests. Choose one to open on GitHub.`}
</DialogDescription>
</DialogHeader>
<div
@@ -80,43 +137,15 @@ export function TaskPRPickerDialog({ open, onOpenChange, prs, mrs = [] }: TaskPR
className="-mx-2 flex max-h-[50vh] flex-col gap-1 overflow-y-auto px-2"
onKeyDown={onListKeyDown}
>
{prs.map((pr) => (
<button
key={pr.id}
type="button"
data-pr-row
data-testid={`task-pr-picker-row-${pr.id}`}
onClick={() => openPR(pr)}
className="flex cursor-pointer items-center gap-2 rounded-md border border-transparent px-2 py-2 text-left text-sm transition-colors hover:border-border hover:bg-muted/40 focus:border-primary/70 focus:outline-none"
>
<IconGitPullRequest className={cn("h-4 w-4 shrink-0", getPRStatusColor(pr))} />
<span className="min-w-0 flex-1 truncate">
<span className="font-medium">
{pr.repo} #{pr.pr_number}
</span>{" "}
<span className="text-muted-foreground">{pr.pr_title}</span>
</span>
<span className="shrink-0 text-xs capitalize text-muted-foreground">{pr.state}</span>
</button>
))}
{mrs.map((mr) => (
<button
key={mr.id}
type="button"
data-pr-row
data-testid={`task-mr-picker-row-${mr.id}`}
onClick={() => openMR(mr)}
className="flex min-h-11 cursor-pointer items-center gap-2 rounded-md border border-transparent px-2 py-2 text-left text-sm transition-colors hover:border-border hover:bg-muted/40 focus:border-primary/70 focus:outline-none"
>
<IconGitPullRequest className="h-4 w-4 shrink-0 text-orange-500" />
<span className="min-w-0 flex-1 truncate">
<span className="font-medium">
{mr.project_path} !{mr.mr_iid}
</span>{" "}
<span className="text-muted-foreground">{mr.mr_title}</span>
</span>
<span className="shrink-0 text-xs capitalize text-muted-foreground">{mr.state}</span>
</button>
{targets.map((target, index) => (
<TaskReviewRow
key={target.key}
target={target}
index={index}
selected={index === selectedIndex}
onActivate={onActivateIndex}
onFocus={onSelectedIndexChange}
/>
))}
</div>
</DialogContent>
@@ -0,0 +1,100 @@
import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { TaskPR } from "@/lib/types/github";
const { mockOpenExternalLink, mockToast } = vi.hoisted(() => ({
mockOpenExternalLink: vi.fn(),
mockToast: vi.fn(),
}));
let mockPRs: TaskPR[] = [];
vi.mock("@/components/state-provider", () => ({
useAppStore: (
selector: (state: { userSettings: { keyboardShortcuts: Record<string, unknown> } }) => unknown,
) => selector({ userSettings: { keyboardShortcuts: {} } }),
}));
vi.mock("@/components/toast-provider", () => ({
useToast: () => ({ toast: mockToast }),
}));
vi.mock("@/hooks/domains/github/use-task-pr", () => ({
useTaskPR: () => ({ prs: mockPRs }),
}));
vi.mock("@/hooks/domains/gitlab/use-task-mr", () => ({
useTaskMRs: () => [],
}));
vi.mock("@/lib/desktop/external-links", () => ({
openExternalLink: mockOpenExternalLink,
}));
import { TaskPRShortcut } from "./task-pr-shortcut";
function makePR(id: string, number: number): TaskPR {
return {
id,
task_id: "task-1",
owner: "acme",
repo: "kandev",
pr_number: number,
pr_url: `https://github.com/acme/kandev/pull/${number}`,
pr_title: `PR ${number}`,
head_branch: `feature/${number}`,
base_branch: "main",
author_login: "alice",
state: "open",
review_state: "",
checks_state: "",
mergeable_state: "",
review_count: 0,
pending_review_count: 0,
comment_count: 0,
unresolved_review_threads: 0,
checks_total: 0,
checks_passing: 0,
additions: 0,
deletions: 0,
created_at: "2026-07-31T00:00:00Z",
merged_at: null,
closed_at: null,
last_synced_at: null,
updated_at: "2026-07-31T00:00:00Z",
};
}
function dispatchKey(type: "keydown" | "keyup", key: string, init: KeyboardEventInit = {}) {
act(() => {
window.dispatchEvent(
new KeyboardEvent(type, { key, bubbles: true, cancelable: true, ...init }),
);
});
}
describe("TaskPRShortcut", () => {
beforeEach(() => {
mockPRs = [makePR("pr-1", 1), makePR("pr-2", 2)];
mockOpenExternalLink.mockReset().mockResolvedValue(undefined);
mockToast.mockReset();
});
afterEach(() => cleanup());
it("opens the cycled review when the primary modifier is released", async () => {
render(<TaskPRShortcut taskId="task-1" />);
dispatchKey("keydown", "g", { ctrlKey: true, shiftKey: true });
dispatchKey("keydown", "g", { ctrlKey: true });
await waitFor(() =>
expect(screen.getByTestId("task-pr-picker-row-pr-2").getAttribute("data-selected")).toBe(
"true",
),
);
dispatchKey("keyup", "Control");
await waitFor(() => expect(mockOpenExternalLink).toHaveBeenCalledWith(mockPRs[1].pr_url));
});
});
+30 -17
View File
@@ -1,15 +1,16 @@
"use client";
import { useState } from "react";
import { useCallback, useMemo } from "react";
import { useToast } from "@/components/toast-provider";
import { useAppStore } from "@/components/state-provider";
import { useTaskPR } from "@/hooks/domains/github/use-task-pr";
import { useKeyboardShortcut } from "@/hooks/use-keyboard-shortcut";
import { getShortcut } from "@/lib/keyboard/shortcut-overrides";
import { openExternalLink } from "@/lib/desktop/external-links";
import { resolveTaskReviewOpenAction } from "./task-pr-open";
import { buildTaskReviewTargets, type TaskReviewTarget } from "./task-pr-open";
import { TaskPRPickerDialog } from "./task-pr-picker-dialog";
import { useTaskMRs } from "@/hooks/domains/gitlab/use-task-mr";
import { useTaskReviewShortcut } from "./use-task-review-shortcut";
/**
* Task-screen keybinding (default Cmd/Ctrl+Shift+G) that jumps straight to the
@@ -20,28 +21,40 @@ export function TaskPRShortcut({ taskId }: { taskId: string | null }) {
const { toast } = useToast();
const { prs } = useTaskPR(taskId);
const mrs = useTaskMRs(taskId);
const [pickerOpen, setPickerOpen] = useState(false);
const overrides = useAppStore((s) => s.userSettings.keyboardShortcuts);
const shortcut = getShortcut("OPEN_TASK_PR", overrides);
const targets = useMemo(() => buildTaskReviewTargets(prs, mrs), [mrs, prs]);
const onNoTargets = useCallback(
() => toast({ description: "No pull request or merge request linked to this task" }),
[toast],
);
const onOpenTarget = useCallback((target: TaskReviewTarget) => {
void openExternalLink(target.url).catch(() => undefined);
}, []);
const reviewShortcut = useTaskReviewShortcut({
targets,
shortcut,
onNoTargets,
onOpenTarget,
});
useKeyboardShortcut(
getShortcut("OPEN_TASK_PR", overrides),
() => {
const action = resolveTaskReviewOpenAction(prs, mrs);
if (action.kind === "none") {
toast({ description: "No pull request or merge request linked to this task" });
return;
}
if (action.kind === "open") {
void openExternalLink(action.url).catch(() => undefined);
return;
}
setPickerOpen(true);
},
shortcut,
reviewShortcut.handleShortcut,
// Capture + stopPropagation so the binding wins over focus-trapped
// surfaces (xterm.js, editors) — mirrors useEditorKeybinds. Disabled
// until the task id resolves so a transient null doesn't toast.
{ capture: true, stopPropagation: true, enabled: !!taskId },
);
return <TaskPRPickerDialog open={pickerOpen} onOpenChange={setPickerOpen} prs={prs} mrs={mrs} />;
return (
<TaskPRPickerDialog
open={reviewShortcut.pickerOpen}
onOpenChange={reviewShortcut.setPickerOpen}
targets={targets}
selectedIndex={reviewShortcut.selectedIndex}
onSelectedIndexChange={reviewShortcut.setSelectedIndex}
onActivateIndex={reviewShortcut.openTargetAtIndex}
/>
);
}
@@ -0,0 +1,244 @@
import { act, cleanup, renderHook } from "@testing-library/react";
import { afterEach, describe, expect, it, vi } from "vitest";
import { KEYS, type KeyboardShortcut } from "@/lib/keyboard/constants";
import type { TaskReviewTarget } from "./task-pr-open";
import { useTaskReviewShortcut } from "./use-task-review-shortcut";
const defaultShortcut: KeyboardShortcut = {
key: KEYS.G,
modifiers: { ctrlOrCmd: true, shift: true },
};
const controlShortcut: KeyboardShortcut = {
key: KEYS.G,
modifiers: { ctrl: true, shift: true },
};
const targets: TaskReviewTarget[] = [
{ type: "pr", key: "pr:1", url: "https://github.com/acme/kandev/pull/1", review: {} as never },
{
type: "mr",
key: "mr:2",
url: "https://gitlab.example/acme/kandev/-/merge_requests/2",
review: {} as never,
},
];
function keydown(key: string, init: KeyboardEventInit = {}) {
return new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true, ...init });
}
function keyup(key: string) {
act(() => window.dispatchEvent(new KeyboardEvent("keyup", { key, bubbles: true })));
}
function invokeShortcut(
handleShortcut: (event: KeyboardEvent) => void,
key = "g",
init: KeyboardEventInit = { ctrlKey: true, shiftKey: true },
) {
act(() => handleShortcut(keydown(key, init)));
}
function useShortcut(
reviewTargets = targets,
shortcut = defaultShortcut,
onOpenTarget = vi.fn(),
onNoTargets = vi.fn(),
) {
return renderHook(() =>
useTaskReviewShortcut({
targets: reviewTargets,
shortcut,
onNoTargets,
onOpenTarget,
}),
);
}
afterEach(() => cleanup());
describe("useTaskReviewShortcut held selection", () => {
it("ignores OS key repeat for a direct-open review", () => {
const onOpenTarget = vi.fn();
const { result } = useShortcut([targets[0]], defaultShortcut, onOpenTarget);
act(() => {
result.current.handleShortcut(keydown("g", { ctrlKey: true, shiftKey: true }));
result.current.handleShortcut(keydown("g", { ctrlKey: true, shiftKey: true, repeat: true }));
});
expect(onOpenTarget).toHaveBeenCalledTimes(1);
});
it("cycles in displayed provider order, wraps, and commits on primary release", () => {
const onOpenTarget = vi.fn();
const { result } = useShortcut(targets, controlShortcut, onOpenTarget);
invokeShortcut(result.current.handleShortcut);
expect(result.current).toMatchObject({ pickerOpen: true, selectedIndex: 0 });
invokeShortcut(result.current.handleShortcut);
expect(result.current.selectedIndex).toBe(1);
invokeShortcut(result.current.handleShortcut);
expect(result.current.selectedIndex).toBe(0);
keyup("Control");
expect(onOpenTarget).toHaveBeenCalledWith(targets[0]);
expect(result.current.pickerOpen).toBe(false);
});
it("does not commit when Shift is released before the primary modifier", () => {
const onOpenTarget = vi.fn();
const { result } = useShortcut(targets, controlShortcut, onOpenTarget);
invokeShortcut(result.current.handleShortcut);
keyup("Shift");
expect(result.current.pickerOpen).toBe(true);
expect(onOpenTarget).not.toHaveBeenCalled();
invokeShortcut(result.current.handleShortcut, "g", { ctrlKey: true });
expect(result.current.selectedIndex).toBe(1);
keyup("Control");
expect(onOpenTarget).toHaveBeenCalledWith(targets[1]);
});
it("uses Control when it opened a ctrlOrCmd shortcut on macOS", () => {
const platformDescriptor = Object.getOwnPropertyDescriptor(navigator, "platform");
Object.defineProperty(navigator, "platform", { configurable: true, value: "MacIntel" });
try {
const onOpenTarget = vi.fn();
const { result } = useShortcut(targets, defaultShortcut, onOpenTarget);
invokeShortcut(result.current.handleShortcut, "g", { ctrlKey: true, shiftKey: true });
invokeShortcut(result.current.handleShortcut, "g", { ctrlKey: true });
expect(result.current.selectedIndex).toBe(1);
keyup("Control");
expect(onOpenTarget).toHaveBeenCalledWith(targets[1]);
} finally {
if (platformDescriptor) Object.defineProperty(navigator, "platform", platformDescriptor);
else delete (navigator as { platform?: string }).platform;
}
});
});
describe("useTaskReviewShortcut cancellation", () => {
it("cancels on Escape and does not commit after primary release", () => {
const onOpenTarget = vi.fn();
const { result } = useShortcut(targets, controlShortcut, onOpenTarget);
invokeShortcut(result.current.handleShortcut);
act(() => window.dispatchEvent(keydown("Escape")));
keyup("Control");
expect(result.current.pickerOpen).toBe(false);
expect(onOpenTarget).not.toHaveBeenCalled();
});
});
describe("useTaskReviewShortcut binding variants", () => {
it("cancels on application blur and document hiding", () => {
const onOpenTarget = vi.fn();
const { result } = useShortcut(targets, controlShortcut, onOpenTarget);
const visibilityDescriptor = Object.getOwnPropertyDescriptor(document, "visibilityState");
invokeShortcut(result.current.handleShortcut);
act(() => window.dispatchEvent(new Event("blur")));
keyup("Control");
expect(onOpenTarget).not.toHaveBeenCalled();
invokeShortcut(result.current.handleShortcut);
Object.defineProperty(document, "visibilityState", { configurable: true, value: "hidden" });
act(() => document.dispatchEvent(new Event("visibilitychange")));
keyup("Control");
if (visibilityDescriptor)
Object.defineProperty(document, "visibilityState", visibilityDescriptor);
else delete (document as { visibilityState?: DocumentVisibilityState }).visibilityState;
expect(onOpenTarget).not.toHaveBeenCalled();
});
it("commits custom modified shortcuts with their configured primary modifier", () => {
const onOpenTarget = vi.fn();
const shortcut: KeyboardShortcut = { key: KEYS.Y, modifiers: { alt: true, shift: true } };
const { result } = useShortcut(targets, shortcut, onOpenTarget);
invokeShortcut(result.current.handleShortcut, "y", { altKey: true, shiftKey: true });
invokeShortcut(result.current.handleShortcut, "y", { altKey: true });
keyup("Alt");
expect(onOpenTarget).toHaveBeenCalledWith(targets[1]);
});
it("keeps a modifierless picker open until explicit activation", () => {
const onOpenTarget = vi.fn();
const shortcut: KeyboardShortcut = { key: KEYS.G };
const { result } = useShortcut(targets, shortcut, onOpenTarget);
invokeShortcut(result.current.handleShortcut, "g", {});
invokeShortcut(result.current.handleShortcut, "g", {});
keyup("Control");
expect(result.current).toMatchObject({ pickerOpen: true, selectedIndex: 1 });
expect(onOpenTarget).not.toHaveBeenCalled();
act(() => result.current.openSelectedTarget());
expect(onOpenTarget).toHaveBeenCalledWith(targets[1]);
expect(result.current.pickerOpen).toBe(false);
});
it("uses the current target list if reviews update while the picker is open", () => {
const onOpenTarget = vi.fn();
const { result, rerender } = renderHook(
({ reviewTargets }) =>
useTaskReviewShortcut({
targets: reviewTargets,
shortcut: controlShortcut,
onNoTargets: vi.fn(),
onOpenTarget,
}),
{ initialProps: { reviewTargets: targets } },
);
invokeShortcut(result.current.handleShortcut);
invokeShortcut(result.current.handleShortcut);
rerender({ reviewTargets: [targets[0]] });
expect(result.current.selectedIndex).toBe(0);
keyup("Control");
expect(onOpenTarget).toHaveBeenCalledWith(targets[0]);
});
it("does not open directly when targets shrink while the picker is held open", () => {
const onOpenTarget = vi.fn();
const { result, rerender } = renderHook(
({ reviewTargets }) =>
useTaskReviewShortcut({
targets: reviewTargets,
shortcut: controlShortcut,
onNoTargets: vi.fn(),
onOpenTarget,
}),
{ initialProps: { reviewTargets: targets } },
);
invokeShortcut(result.current.handleShortcut);
rerender({ reviewTargets: [targets[0]] });
invokeShortcut(result.current.handleShortcut, "g", { ctrlKey: true });
expect(result.current.pickerOpen).toBe(true);
expect(onOpenTarget).not.toHaveBeenCalled();
keyup("Control");
expect(onOpenTarget).toHaveBeenCalledOnce();
expect(onOpenTarget).toHaveBeenCalledWith(targets[0]);
expect(result.current.pickerOpen).toBe(false);
});
});
@@ -0,0 +1,271 @@
"use client";
import { useCallback, useEffect, useRef, useState, type RefObject } from "react";
import type { KeyboardShortcut } from "@/lib/keyboard/constants";
import {
hasHoldModifier,
isCommitReleaseEvent,
isCycleShortcutEvent,
isHeldCycleKeyEvent,
snapshotHeldShortcut,
} from "./recent-task-switcher-keys";
import type { TaskReviewTarget } from "./task-pr-open";
type UseTaskReviewShortcutOptions = {
targets: TaskReviewTarget[];
shortcut: KeyboardShortcut;
onNoTargets: () => void;
onOpenTarget: (target: TaskReviewTarget) => void;
};
function clampIndex(index: number, count: number): number {
if (count === 0) return -1;
return Math.min(Math.max(index, 0), count - 1);
}
function useLatestRef<T>(value: T) {
const ref = useRef(value);
ref.current = value;
return ref;
}
type ReviewShortcutLifecycleOptions = {
activeShortcutRef: RefObject<KeyboardShortcut | null>;
cancelledRef: RefObject<boolean>;
commitOnReleaseRef: RefObject<boolean>;
openRef: RefObject<boolean>;
advanceSelection: () => void;
cancelPicker: () => void;
openSelectedTarget: () => void;
};
function useReviewShortcutLifecycle({
activeShortcutRef,
cancelledRef,
commitOnReleaseRef,
openRef,
advanceSelection,
cancelPicker,
openSelectedTarget,
}: ReviewShortcutLifecycleOptions) {
useEffect(() => {
const handleKeyDown = (event: KeyboardEvent) => {
if (event.key === "Escape" && openRef.current) {
event.preventDefault();
event.stopPropagation();
cancelPicker();
return;
}
if (event.defaultPrevented || !openRef.current) return;
const activeShortcut = activeShortcutRef.current;
if (!activeShortcut || !isHeldCycleKeyEvent(event, activeShortcut)) return;
event.preventDefault();
event.stopPropagation();
advanceSelection();
};
const handleKeyUp = (event: KeyboardEvent) => {
if (!openRef.current || !commitOnReleaseRef.current) return;
const activeShortcut = activeShortcutRef.current;
if (!activeShortcut || !isCommitReleaseEvent(event, activeShortcut)) return;
event.preventDefault();
event.stopPropagation();
if (cancelledRef.current) {
cancelPicker();
return;
}
openSelectedTarget();
};
const handleBlur = () => {
if (openRef.current) cancelPicker();
};
const handleVisibilityChange = () => {
if (document.visibilityState === "hidden" && openRef.current) cancelPicker();
};
window.addEventListener("keydown", handleKeyDown, true);
window.addEventListener("keyup", handleKeyUp, true);
window.addEventListener("blur", handleBlur);
document.addEventListener("visibilitychange", handleVisibilityChange);
return () => {
window.removeEventListener("keydown", handleKeyDown, true);
window.removeEventListener("keyup", handleKeyUp, true);
window.removeEventListener("blur", handleBlur);
document.removeEventListener("visibilitychange", handleVisibilityChange);
};
}, [
activeShortcutRef,
advanceSelection,
cancelledRef,
cancelPicker,
commitOnReleaseRef,
openRef,
openSelectedTarget,
]);
}
function useReviewSelection(
targets: TaskReviewTarget[],
targetsRef: RefObject<TaskReviewTarget[]>,
) {
const [selectedIndex, setSelectedIndexState] = useState(0);
const selectedIndexRef = useRef(0);
useEffect(() => {
const nextIndex = clampIndex(selectedIndexRef.current, targets.length);
if (nextIndex === selectedIndexRef.current) return;
selectedIndexRef.current = nextIndex;
setSelectedIndexState(nextIndex);
}, [targets]);
const setSelectedIndex = useCallback(
(index: number) => {
const nextIndex = clampIndex(index, targetsRef.current.length);
selectedIndexRef.current = nextIndex;
setSelectedIndexState(nextIndex);
},
[targetsRef],
);
return { selectedIndex, selectedIndexRef, setSelectedIndex };
}
type ReviewTargetActivationOptions = {
targetsRef: RefObject<TaskReviewTarget[]>;
selectedIndexRef: RefObject<number>;
onOpenTargetRef: RefObject<(target: TaskReviewTarget) => void>;
closePicker: () => void;
};
function useReviewTargetActivation({
targetsRef,
selectedIndexRef,
onOpenTargetRef,
closePicker,
}: ReviewTargetActivationOptions) {
const openTargetAtIndex = useCallback(
(index: number) => {
const targets = targetsRef.current;
const target = targets[clampIndex(index, targets.length)];
closePicker();
if (target) onOpenTargetRef.current(target);
},
[closePicker, onOpenTargetRef, targetsRef],
);
const openSelectedTarget = useCallback(
() => openTargetAtIndex(selectedIndexRef.current),
[openTargetAtIndex, selectedIndexRef],
);
return { openTargetAtIndex, openSelectedTarget };
}
export function useTaskReviewShortcut({
targets,
shortcut,
onNoTargets,
onOpenTarget,
}: UseTaskReviewShortcutOptions) {
const [pickerOpen, setPickerOpenState] = useState(false);
const activeShortcutRef = useRef<KeyboardShortcut | null>(null);
const cancelledRef = useRef(false);
const commitOnReleaseRef = useRef(false);
const openRef = useRef(false);
const onNoTargetsRef = useLatestRef(onNoTargets);
const onOpenTargetRef = useLatestRef(onOpenTarget);
const shortcutRef = useLatestRef(shortcut);
const targetsRef = useLatestRef(targets);
const { selectedIndex, selectedIndexRef, setSelectedIndex } = useReviewSelection(
targets,
targetsRef,
);
const closePicker = useCallback(() => {
activeShortcutRef.current = null;
commitOnReleaseRef.current = false;
openRef.current = false;
setPickerOpenState(false);
}, []);
const cancelPicker = useCallback(() => {
cancelledRef.current = true;
closePicker();
}, [closePicker]);
const setPickerOpen = useCallback(
(nextOpen: boolean) => {
if (!nextOpen) {
cancelPicker();
return;
}
cancelledRef.current = false;
openRef.current = true;
setPickerOpenState(true);
},
[cancelPicker],
);
const { openTargetAtIndex, openSelectedTarget } = useReviewTargetActivation({
targetsRef,
selectedIndexRef,
onOpenTargetRef,
closePicker,
});
const advanceSelection = useCallback(() => {
const targetCount = targetsRef.current.length;
if (targetCount < 2) return;
setSelectedIndex((selectedIndexRef.current + 1) % targetCount);
}, [setSelectedIndex, targetsRef]);
const handleShortcut = useCallback(
(event: KeyboardEvent) => {
if (event.repeat) return;
const reviewTargets = targetsRef.current;
if (!openRef.current && reviewTargets.length === 0) {
onNoTargetsRef.current();
return;
}
if (!openRef.current && reviewTargets.length === 1) {
onOpenTargetRef.current(reviewTargets[0]);
return;
}
const activeShortcut = shortcutRef.current;
if (!openRef.current) {
if (!isCycleShortcutEvent(event, activeShortcut)) return;
activeShortcutRef.current = snapshotHeldShortcut(event, activeShortcut);
commitOnReleaseRef.current = hasHoldModifier(activeShortcut);
cancelledRef.current = false;
openRef.current = true;
setSelectedIndex(0);
setPickerOpenState(true);
return;
}
const heldShortcut = activeShortcutRef.current ?? activeShortcut;
if (isHeldCycleKeyEvent(event, heldShortcut)) advanceSelection();
},
[advanceSelection, onNoTargetsRef, onOpenTargetRef, setSelectedIndex, shortcutRef, targetsRef],
);
useReviewShortcutLifecycle({
activeShortcutRef,
cancelledRef,
commitOnReleaseRef,
openRef,
advanceSelection,
cancelPicker,
openSelectedTarget,
});
return {
pickerOpen,
selectedIndex,
setPickerOpen,
setSelectedIndex,
handleShortcut,
openTargetAtIndex,
openSelectedTarget,
};
}
+140 -19
View File
@@ -2,6 +2,8 @@ import { test, expect } from "../../fixtures/test-base";
import { KanbanPage } from "../../pages/kanban-page";
import { SessionPage } from "../../pages/session-page";
import type { ApiClient } from "../../helpers/api-client";
import { GITLAB_HOST, GITLAB_PROJECT, seedGitLabReview } from "../../helpers/gitlab";
import type { Page } from "@playwright/test";
const OWNER = "acme";
const SHORTCUT = "ControlOrMeta+Shift+G";
@@ -13,6 +15,64 @@ type SeedResult = {
taskId: string;
};
type AssociateMRArgs = {
apiClient: ApiClient;
workspaceId: string;
taskId: string;
repositoryId: string;
iid: number;
title: string;
};
function taskReviewModifier() {
return process.platform === "darwin" ? "Meta" : "Control";
}
async function associateMR({
apiClient,
workspaceId,
taskId,
repositoryId,
iid,
title,
}: AssociateMRArgs): Promise<string> {
await seedGitLabReview(apiClient, workspaceId, iid, title);
await apiClient.updateRepository(repositoryId, {
provider: "gitlab",
provider_host: GITLAB_HOST,
provider_owner: "platform",
provider_name: "kandev",
});
const mrURL = `${GITLAB_HOST}/${GITLAB_PROJECT}/-/merge_requests/${iid}`;
await apiClient.linkTaskGitLabMR(workspaceId, {
task_id: taskId,
repository_id: repositoryId,
mr_url: mrURL,
});
return mrURL;
}
async function stubExternalProviders(page: Page) {
await page
.context()
.route("https://github.com/**", (route) =>
route.fulfill({ contentType: "text/html", body: "<html>github stub</html>" }),
);
await page
.context()
.route(`${GITLAB_HOST}/**`, (route) =>
route.fulfill({ contentType: "text/html", body: "<html>gitlab stub</html>" }),
);
}
async function holdTaskReviewShortcut(page: Page): Promise<string> {
const modifier = taskReviewModifier();
await page.keyboard.down(modifier);
await page.keyboard.down("Shift");
await page.keyboard.press("g");
return modifier;
}
/**
* Stand up a workspace + workflow + task that reaches the Done column
* immediately (auto-start + on_turn_complete moves it), mirroring
@@ -107,7 +167,7 @@ async function openTaskAndWait(
}
test.describe("Open-task-PR keyboard shortcut", () => {
test("Cmd+Shift+G with several linked PRs opens the picker; Enter opens the focused PR", async ({
test("Cmd+Shift+G cycles linked PRs and MRs until primary modifier release", async ({
testPage,
apiClient,
seedData,
@@ -124,34 +184,99 @@ test.describe("Open-task-PR keyboard shortcut", () => {
);
await associatePR(apiClient, seed.taskId, "web", 42, "Web feature PR");
await associatePR(apiClient, seed.taskId, "api", 77, "API feature PR");
const mrURL = await associateMR({
apiClient,
workspaceId: seedData.workspaceId,
taskId: seed.taskId,
repositoryId: seedData.repositoryId,
iid: 88,
title: "GitLab linked review",
});
const session = await openTaskAndWait(testPage, apiClient, seed, title);
await expect(session.prTopbarButton()).toHaveAttribute("data-pr-count", "2");
// Keep the picked PR's navigation offline-deterministic.
await testPage
.context()
.route("https://github.com/**", (route) =>
route.fulfill({ contentType: "text/html", body: "<html>github stub</html>" }),
);
await stubExternalProviders(testPage);
await testPage.keyboard.press(SHORTCUT);
const modifier = await holdTaskReviewShortcut(testPage);
const list = testPage.getByTestId("task-pr-picker-list");
await expect(list).toBeVisible();
await expect(list.locator("button[data-pr-row]")).toHaveCount(2);
const rows = list.locator("button[data-pr-row]");
const firstPR = rows.nth(0);
const secondPR = rows.nth(1);
const mergeRequest = rows.nth(2);
await expect(rows).toHaveCount(3);
await expect(firstPR).toHaveAttribute("data-selected", "true");
await expect(mergeRequest).toContainText("GitLab linked review");
await prCapture.screenshot("pr-picker-modal", {
caption: "Cmd+Shift+G on a task with two linked PRs opens the picker modal",
caption: "Cmd+Shift+G opens a held shortcut picker for linked code reviews",
});
if (process.env.CAPTURE_PR_ASSETS) {
await testPage.setViewportSize({ width: 390, height: 844 });
await prCapture.screenshot("mobile-pr-picker-modal", {
caption: "Linked code review picker on a mobile viewport",
});
await testPage.setViewportSize({ width: 1280, height: 720 });
}
// Shift release alone does not commit; Ctrl/Cmd remains held for raw G cycling.
const pageCountBeforeRelease = testPage.context().pages().length;
await testPage.keyboard.up("Shift");
await expect(list).toBeVisible();
await expect(firstPR).toHaveAttribute("data-selected", "true");
expect(testPage.context().pages()).toHaveLength(pageCountBeforeRelease);
await testPage.keyboard.press("g");
await expect(secondPR).toHaveAttribute("data-selected", "true");
await testPage.keyboard.press("g");
await expect(mergeRequest).toHaveAttribute("data-selected", "true");
await testPage.keyboard.press("g");
await expect(firstPR).toHaveAttribute("data-selected", "true");
await testPage.keyboard.press("g");
await expect(secondPR).toHaveAttribute("data-selected", "true");
await testPage.keyboard.press("g");
await expect(mergeRequest).toHaveAttribute("data-selected", "true");
// First row (web#42) is auto-focused; ArrowDown moves to api#77, Enter opens it.
await testPage.keyboard.press("ArrowDown");
const popupPromise = testPage.context().waitForEvent("page");
await testPage.keyboard.press("Enter");
await testPage.keyboard.up(modifier);
const popup = await popupPromise;
await popup.waitForURL(`https://github.com/${OWNER}/api/pull/77`, { timeout: 10_000 });
await popup.waitForURL(mrURL, { timeout: 10_000 });
await expect(list).not.toBeVisible();
await popup.close();
});
test("Escape cancels a held picker without opening a review on release", async ({
testPage,
apiClient,
seedData,
}) => {
test.setTimeout(120_000);
const title = "PR Shortcut Cancel";
const seed = await seedTask(
apiClient,
seedData.workspaceId,
seedData.agentProfileId,
seedData.repositoryId,
title,
);
await associatePR(apiClient, seed.taskId, "web", 42, "Web feature PR");
await associatePR(apiClient, seed.taskId, "api", 77, "API feature PR");
await openTaskAndWait(testPage, apiClient, seed, title);
await stubExternalProviders(testPage);
const modifier = await holdTaskReviewShortcut(testPage);
const list = testPage.getByTestId("task-pr-picker-list");
await expect(list).toBeVisible();
await testPage.keyboard.press("Escape");
await expect(list).not.toBeVisible();
const pageCountBeforeRelease = testPage.context().pages().length;
await testPage.keyboard.up("Shift");
await testPage.keyboard.up(modifier);
expect(testPage.context().pages()).toHaveLength(pageCountBeforeRelease);
await expect(testPage).toHaveURL(new RegExp(`/[st]/${seed.taskId}`));
});
test("Cmd+Shift+G with one linked PR opens it directly without a modal", async ({
testPage,
apiClient,
@@ -169,11 +294,7 @@ test.describe("Open-task-PR keyboard shortcut", () => {
await associatePR(apiClient, seed.taskId, "web", 42, "Web feature PR");
await openTaskAndWait(testPage, apiClient, seed, title);
await testPage
.context()
.route("https://github.com/**", (route) =>
route.fulfill({ contentType: "text/html", body: "<html>github stub</html>" }),
);
await stubExternalProviders(testPage);
const popupPromise = testPage.context().waitForEvent("page");
await testPage.keyboard.press(SHORTCUT);
@@ -0,0 +1,139 @@
---
spec: docs/specs/ui/task-review-shortcut.md
created: 2026-07-31
status: completed
---
# Implementation Plan: Task Review Shortcut Switcher
## Overview
Turn the existing multi-review shortcut picker into a controlled, held-chord
switcher. Reuse the recent-task switcher's tested shortcut-key helpers for
platform-aware hold-modifier detection, deliberate key presses, and release
commit; keep provider lookup, ordering, and external-link behavior unchanged.
## Backend
No backend or protocol changes. Existing task PR and MR collections already
contain every target and provider URL needed by the switcher.
## Frontend
### Provider-neutral review targets
- Update `apps/web/components/task/task-pr-open.ts` to expose an ordered,
discriminated review-target shape built from GitHub PRs followed by GitLab
MRs. Keep the existing `none` / single direct-open / multiple pick decision,
but let the controller and picker share one target list and URL source.
- Extend `apps/web/components/task/task-pr-open.test.ts` to prove mixed-provider
order, direct-open resolution, and target identity.
### Held shortcut controller
- Add `apps/web/components/task/use-task-review-shortcut.ts` and its focused
test. The hook owns open state, selected target index, synchronous refs for
key-event ordering, and cancel/commit lifecycle.
- Reuse `hasHoldModifier`, `isCycleShortcutEvent`, and
`isCommitReleaseEvent` from
`apps/web/components/task/recent-task-switcher-keys.ts`; do not create another
modifier parser.
- On a multi-target keydown, open on index 0 or advance one row with wrap.
After the initial chord, keeping the primary hold modifier alone is enough to
continue cycling; ignore `KeyboardEvent.repeat`. Commit only on release of
the configured primary hold modifier. A modifierless binding stays open for
Enter/click.
- Cancel on Escape, window blur, document hiding, or dialog dismissal so a
later keyup cannot open a review. Use latest target/index refs so release
never opens a stale row.
- Update `apps/web/components/task/task-pr-shortcut.tsx` to supply the current
configurable binding, toast/direct-open callbacks, and controlled picker
props while preserving capture-phase shortcut precedence.
### Controlled picker selection
- Update `apps/web/components/task/task-pr-picker-dialog.tsx` to render the
provider-neutral target list and accept controlled selected-index and
activation callbacks.
- Keep focused-row behavior synchronized with selection. Preserve ArrowUp,
ArrowDown, Enter, click, Escape, wrapping, scroll containment, and accessible
focus. Expose stable selected state for E2E without changing row order or
visual composition.
- Add `apps/web/components/task/task-pr-picker-dialog.test.tsx` for controlled
focus, arrow wrapping, Enter/click activation, and mixed PR/MR row order.
## Mobile design contract
- Desktop outcome: hold and repeat the configured shortcut, then release its
primary modifier to open the selected linked review.
- Mobile/coarse-pointer entry points remain the shipped PR/CI drawer and Review
selector patterns covered by
`apps/web/e2e/tests/pr/mobile-pr-ci-chip.spec.ts` and
`apps/web/e2e/tests/review/mobile-review-multi-pr.spec.ts`.
- Picker hierarchy, dialog surface, scroll owner, touch targets, viewport
sizing, and safe-area behavior do not change. Review data and open actions
stay shared; only hardware-keyboard event handling changes.
- No new mobile composition or mobile-only test is required because rendered
layout and touch behavior are unchanged. Existing mobile specs remain the
parity evidence and run with the focused E2E task.
## Tests
- **What:** provider-neutral PR/MR target ordering and direct/pick resolution.
**File:** `apps/web/components/task/task-pr-open.test.ts`.
**How:** table-driven Vitest cases.
- **What:** first press, deliberate repeat, wrap, primary-modifier release,
Shift-only release, Escape/blur/visibility cancellation, custom modified
binding, modifierless binding, OS-repeat suppression, and current-target
commit.
**File:** `apps/web/components/task/use-task-review-shortcut.test.ts`.
**How:** `renderHook` with synthetic keydown/keyup and mocked open/toast
callbacks.
- **What:** controlled focus and legacy Arrow/Enter/click interaction across
mixed PR/MR rows.
**File:** `apps/web/components/task/task-pr-picker-dialog.test.tsx`.
**How:** Testing Library component interaction.
## E2E tests
- **Scenario:** first default chord opens on the first row; deliberate repeated
G presses advance through GitHub PR and GitLab MR rows and wrap; releasing
Shift alone keeps the picker open; releasing Command/Control opens the
selected provider URL.
**File:** `apps/web/e2e/tests/pr/pr-open-shortcut.spec.ts`.
**What to verify:** `data-selected` movement, picker visibility, no popup on
Shift release, final popup URL, and picker close.
- **Scenario:** Escape cancels a held switcher and later primary-modifier
release opens no provider page.
**File:** `apps/web/e2e/tests/pr/pr-open-shortcut.spec.ts`.
**What to verify:** picker closes, page count stays unchanged, and task route
remains active.
- **Scenario:** one linked review still opens directly and the shortcut remains
visible in keyboard settings.
**File:** `apps/web/e2e/tests/pr/pr-open-shortcut.spec.ts`.
**What to verify:** retain the existing direct-open and settings assertions.
## Implementation waves
Wave 1:
- [x] [Task 01 — held review switcher](task-01-held-review-switcher.md)
Wave 2:
- [x] [Task 02 — shortcut switcher E2E](task-02-shortcut-switcher-e2e.md) —
depends on Task 01
Execute sequentially in the primary conversation. Waves do not authorize
subagents.
## Risks
- React state can lag a rapid keydown/keyup sequence; synchronous refs must own
the event-time selected index and open state.
- Releasing Shift must not commit the default `Cmd/Ctrl+Shift+G` binding; only
the helper-selected primary hold modifier commits.
- Provider lists can update while the picker is open; selection must clamp to
a current target and never open a removed URL.
- Browser and Tauri external-link paths differ, so unit tests mock the opener
while Playwright verifies the browser popup URL.
@@ -0,0 +1,67 @@
---
id: "01-held-review-switcher"
title: "Implement held review shortcut switcher"
status: done
wave: 1
depends_on: []
plan: "plan.md"
spec: "../../specs/ui/task-review-shortcut.md"
---
# Task 01: Implement held review shortcut switcher
## Acceptance
- Multi-review shortcut presses open on row 1, advance deliberately with wrap,
and open the selected PR or MR only when the configured primary hold modifier
is released.
- Escape, blur, visibility loss, dismissal, OS key repeat, Shift-only release,
custom modified bindings, and modifierless bindings follow the spec.
- Picker keeps ArrowUp/Down, Enter, click, mixed-provider order, focus, and
accessible selected-state behavior without changing touch layout.
## Verification
- `cd apps && pnpm --filter @kandev/web test -- --run components/task/task-pr-open.test.ts components/task/use-task-review-shortcut.test.ts components/task/task-pr-picker-dialog.test.tsx components/task/recent-task-switcher-keys.test.ts`
- `cd apps/web && pnpm run typecheck`
## Files likely touched
- `apps/web/components/task/task-pr-open.ts`
- `apps/web/components/task/task-pr-open.test.ts`
- `apps/web/components/task/use-task-review-shortcut.ts`
- `apps/web/components/task/use-task-review-shortcut.test.ts`
- `apps/web/components/task/task-pr-shortcut.tsx`
- `apps/web/components/task/task-pr-picker-dialog.tsx`
- `apps/web/components/task/task-pr-picker-dialog.test.tsx`
- `apps/web/components/task/recent-task-switcher-keys.ts` (reuse only unless a
narrowly required helper correction is proven by its test)
## Dependencies
None.
## Parallelism
Sequential. Task 02 requires this behavior and its stable selected-state
selector.
## Inputs
- Spec: `What` and all keyboard scenarios.
- Plan: `Provider-neutral review targets`, `Held shortcut controller`,
`Controlled picker selection`, and `Mobile design contract`.
- Pattern: `apps/web/components/task/recent-task-switcher-hooks.ts` and
`apps/web/components/task/recent-task-switcher-keys.ts`.
## Risks
- Stale React closures during rapid modifier release.
- Accidental activation after Escape or focus loss.
- Mixed PR/MR indices drifting from rendered order.
## Output contract
Report RED and GREEN results, changed files, responsive impact, blockers, and
remaining risks. Mark this task `done` and its plan checkbox complete only after
both verification commands pass.
@@ -0,0 +1,63 @@
---
id: "02-shortcut-switcher-e2e"
title: "Prove review shortcut switching end to end"
status: done
wave: 2
depends_on: ["01-held-review-switcher"]
plan: "plan.md"
spec: "../../specs/ui/task-review-shortcut.md"
---
# Task 02: Prove review shortcut switching end to end
## Acceptance
- Playwright proves held default-chord cycling, PR/MR order, wrap, Shift-only
release, primary-modifier activation, and final provider URL.
- Playwright proves Escape prevents activation on later modifier release while
retaining existing single-review and settings behavior.
- Existing mobile linked-review drawer and multi-PR Review selector specs still
pass as parity evidence; no touch or viewport composition changes.
## Verification
- `cd apps/web && pnpm e2e:run tests/pr/pr-open-shortcut.spec.ts`
- `cd apps/web && pnpm e2e:run -- --project=mobile-chrome tests/pr/mobile-pr-ci-chip.spec.ts tests/review/mobile-review-multi-pr.spec.ts`
## Files likely touched
- `apps/web/e2e/tests/pr/pr-open-shortcut.spec.ts`
- `apps/web/e2e/helpers/gitlab.ts` only if existing exported seeds cannot express
the linked-MR fixture cleanly
- `apps/web/e2e/pages/session-page.ts` only if a reusable selected-row locator is
warranted
## Dependencies
- Task 01 complete.
## Parallelism
Sequential; depends on Task 01 production behavior.
## Inputs
- Spec scenarios.
- Plan `E2E tests` and `Mobile design contract`.
- Existing `apps/web/e2e/tests/pr/pr-open-shortcut.spec.ts` seed and popup
interception pattern.
- Existing `apps/web/e2e/helpers/gitlab.ts` and
`ApiClient.linkTaskGitLabMR` for a deterministic MR target.
## Risks
- Popup timing can race modifier release; register popup waits before keyup.
- Test must use separate `keyboard.down` / `press` / `up` calls so Playwright
preserves held-modifier state.
- Provider routes must remain offline-deterministic.
## Output contract
Report RED and GREEN E2E results, exact commands, changed files, mobile parity
evidence, blockers, and remaining risks. Mark this task `done` and its plan
checkbox complete only after both verification commands pass.
+1
View File
@@ -144,6 +144,7 @@ Subscription quota tracking and per-agent cheap-model profile routing.
| [external-vcs-file-links](ui/external-vcs-file-links.md) | shipped |
| [task-listing-display-preferences](ui/task-listing-display-preferences.md) | shipped |
| [task-workspace-content-search](ui/task-workspace-content-search.md) | shipped |
| [task-review-shortcut](ui/task-review-shortcut.md) | approved |
| [embedded-vscode-executor-availability](ui/embedded-vscode-executor-availability.md) | approved |
| [embedded-vscode-windows-availability](ui/embedded-vscode-windows-availability.md) | archived; superseded by embedded-vscode-executor-availability |
| [ws-connectivity-warning](ui/ws-connectivity-warning.md) | approved |
+82
View File
@@ -0,0 +1,82 @@
---
status: approved
created: 2026-07-31
owner: Kandev frontend
---
# Task Review Shortcut Switcher
## Why
Keyboard users opening one of several reviews linked to a task must leave the
shortcut chord and use arrow keys before choosing a review. A hold-and-repeat
switcher keeps selection inside the original shortcut flow.
## What
- The configurable **Open Task Pull Request** shortcut keeps its existing
no-review toast and single-review direct-open behavior.
- When a task has multiple linked reviews, the first shortcut press opens the
review picker with its first displayed row selected.
- While the shortcut's primary modifier remains held, each additional deliberate
press of the configured shortcut key advances selection by one displayed row
and wraps from the last row to the first. Secondary modifiers such as Shift
may be released after the first chord. Operating-system key repeat does not
advance selection.
- Cycling includes every row already shown by the picker: GitHub pull requests
followed by GitLab merge requests, preserving their displayed order.
- Releasing the shortcut's primary hold modifier opens the selected review at
its provider and closes the picker. For the default binding, this is Command
on macOS and Control on Windows or Linux; releasing Shift alone does not open
the review.
- Custom shortcut bindings use their configured key and primary hold modifier.
A modifierless binding can open and cycle the picker, but requires Enter or a
click to activate the selection because it has no modifier-release signal.
- ArrowUp, ArrowDown, Enter, click, and Escape remain supported. Escape,
application-window blur, or document hiding cancels the switcher, and a later
modifier release does not open a review.
- The selected row remains visibly and programmatically identifiable while the
picker is open.
- The existing touch and coarse-pointer review entry points and picker layout do
not change.
## Scenarios
- **GIVEN** a task has two linked reviews, **WHEN** the user holds the default
primary modifier and Shift and presses G once, **THEN** the picker opens with
the first displayed review selected.
- **GIVEN** the held shortcut picker is open on the first of three linked
reviews, **WHEN** the user presses G three more times while keeping the primary
modifier held, **THEN** selection advances through the second and third rows
and wraps to the first row.
- **GIVEN** the held shortcut picker has a GitLab merge-request row selected,
**WHEN** the user releases the primary modifier, **THEN** that merge request
opens at GitLab and the picker closes.
- **GIVEN** the default shortcut picker is open, **WHEN** the user releases Shift
while continuing to hold the primary modifier, **THEN** the picker stays open
and no review opens.
- **GIVEN** the held shortcut picker is open, **WHEN** the user presses Escape
and later releases the primary modifier, **THEN** the picker closes without
opening a review.
- **GIVEN** the shortcut is rebound to a modified key chord, **WHEN** the user
repeats that configured key and releases its primary modifier, **THEN** the
configured chord cycles and opens the selected review exactly like the
default chord.
- **GIVEN** the shortcut is rebound without a modifier, **WHEN** the user repeats
its key, **THEN** the picker cycles and stays open until the user presses Enter,
clicks a row, or cancels it.
- **GIVEN** a task has exactly one linked review, **WHEN** the user invokes the
shortcut, **THEN** that review opens directly without showing the picker.
- **GIVEN** a task has no linked reviews, **WHEN** the user invokes the shortcut,
**THEN** Kandev shows the existing no-linked-review message.
## Out of scope
- Changing review ordering, linked-review discovery, or provider data.
- Adding reverse cycling or another shortcut.
- Changing the in-app Review dialog's separate PR selector.
- Changing touch, mobile, or coarse-pointer presentation.
## Implementation plan
[Task Review Shortcut Switcher implementation plan](../../plans/task-review-shortcut-switcher/plan.md)