From abf21f52a64cc52ac99ddae5963040e7dcb9f2be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Almeida?= <57680069+zeval@users.noreply.github.com> Date: Fri, 31 Jul 2026 16:15:32 +0100 Subject: [PATCH] feat(web): cycle linked reviews with held shortcut (#2099) --- .../task/recent-task-switcher-keys.test.ts | 15 + .../task/recent-task-switcher-keys.ts | 40 +++ apps/web/components/task/task-pr-open.test.ts | 9 +- apps/web/components/task/task-pr-open.ts | 23 +- .../task/task-pr-picker-dialog.test.tsx | 107 +++++++ .../components/task/task-pr-picker-dialog.tsx | 177 +++++++----- .../components/task/task-pr-shortcut.test.tsx | 100 +++++++ apps/web/components/task/task-pr-shortcut.tsx | 47 +-- .../task/use-task-review-shortcut.test.ts | 244 ++++++++++++++++ .../task/use-task-review-shortcut.ts | 271 ++++++++++++++++++ .../web/e2e/tests/pr/pr-open-shortcut.spec.ts | 159 ++++++++-- .../task-review-shortcut-switcher/plan.md | 139 +++++++++ .../task-01-held-review-switcher.md | 67 +++++ .../task-02-shortcut-switcher-e2e.md | 63 ++++ docs/specs/INDEX.md | 1 + docs/specs/ui/task-review-shortcut.md | 82 ++++++ 16 files changed, 1427 insertions(+), 117 deletions(-) create mode 100644 apps/web/components/task/task-pr-picker-dialog.test.tsx create mode 100644 apps/web/components/task/task-pr-shortcut.test.tsx create mode 100644 apps/web/components/task/use-task-review-shortcut.test.ts create mode 100644 apps/web/components/task/use-task-review-shortcut.ts create mode 100644 docs/plans/task-review-shortcut-switcher/plan.md create mode 100644 docs/plans/task-review-shortcut-switcher/task-01-held-review-switcher.md create mode 100644 docs/plans/task-review-shortcut-switcher/task-02-shortcut-switcher-e2e.md create mode 100644 docs/specs/ui/task-review-shortcut.md diff --git a/apps/web/components/task/recent-task-switcher-keys.test.ts b/apps/web/components/task/recent-task-switcher-keys.test.ts index 37fe3c6d7a..b605afa67c 100644 --- a/apps/web/components/task/recent-task-switcher-keys.test.ts +++ b/apps/web/components/task/recent-task-switcher-keys.test.ts @@ -5,6 +5,7 @@ import { hasHoldModifier, isCommitReleaseEvent, isCycleShortcutEvent, + isHeldCycleKeyEvent, } from "./recent-task-switcher-keys"; function event(overrides: Partial): 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, diff --git a/apps/web/components/task/recent-task-switcher-keys.ts b/apps/web/components/task/recent-task-switcher-keys.ts index 0af9238f3a..de7b2fcef9 100644 --- a/apps/web/components/task/recent-task-switcher-keys.ts +++ b/apps/web/components/task/recent-task-switcher-keys.ts @@ -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, diff --git a/apps/web/components/task/task-pr-open.test.ts b/apps/web/components/task/task-pr-open.test.ts index 605913e9ff..dc1eeb9355 100644 --- a/apps/web/components/task/task-pr-open.test.ts +++ b/apps/web/components/task/task-pr-open.test.ts @@ -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 }, + ], + }); }); }); diff --git a/apps/web/components/task/task-pr-open.ts b/apps/web/components/task/task-pr-open.ts index 1e1c658773..7783e017bf 100644 --- a/apps/web/components/task/task-pr-open.ts +++ b/apps/web/components/task/task-pr-open.ts @@ -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 }; } diff --git a/apps/web/components/task/task-pr-picker-dialog.test.tsx b/apps/web/components/task/task-pr-picker-dialog.test.tsx new file mode 100644 index 0000000000..5686659a72 --- /dev/null +++ b/apps/web/components/task/task-pr-picker-dialog.test.tsx @@ -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 ( + 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(); + + 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(); + + 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); + }); +}); diff --git a/apps/web/components/task/task-pr-picker-dialog.tsx b/apps/web/components/task/task-pr-picker-dialog.tsx index da8bf339c8..396c26ebd3 100644 --- a/apps/web/components/task/task-pr-picker-dialog.tsx +++ b/apps/web/components/task/task-pr-picker-dialog.tsx @@ -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 ( + + ); +} + /** * 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(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(`button[data-pr-row][data-row-index="${index}"]`) + ?.focus(); + }, []); + + useEffect(() => { + if (open) focusRow(selectedIndex); + }, [focusRow, open, selectedIndex]); const onListKeyDown = (e: KeyboardEvent) => { - if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return; - e.preventDefault(); - const rows = Array.from( - listRef.current?.querySelectorAll("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("button[data-pr-row]")?.focus(); + focusRow(selectedIndex); }; return ( - + - {mrs.length ? "Open code review" : "Open pull request"} + {hasMergeRequests ? "Open code review" : "Open pull request"} - {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.`}
- {prs.map((pr) => ( - - ))} - {mrs.map((mr) => ( - + {targets.map((target, index) => ( + ))}
diff --git a/apps/web/components/task/task-pr-shortcut.test.tsx b/apps/web/components/task/task-pr-shortcut.test.tsx new file mode 100644 index 0000000000..3d7927b937 --- /dev/null +++ b/apps/web/components/task/task-pr-shortcut.test.tsx @@ -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 } }) => 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(); + + 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)); + }); +}); diff --git a/apps/web/components/task/task-pr-shortcut.tsx b/apps/web/components/task/task-pr-shortcut.tsx index 0b3ef5eb8b..e6184e69a7 100644 --- a/apps/web/components/task/task-pr-shortcut.tsx +++ b/apps/web/components/task/task-pr-shortcut.tsx @@ -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 ; + return ( + + ); } diff --git a/apps/web/components/task/use-task-review-shortcut.test.ts b/apps/web/components/task/use-task-review-shortcut.test.ts new file mode 100644 index 0000000000..c468e2442e --- /dev/null +++ b/apps/web/components/task/use-task-review-shortcut.test.ts @@ -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); + }); +}); diff --git a/apps/web/components/task/use-task-review-shortcut.ts b/apps/web/components/task/use-task-review-shortcut.ts new file mode 100644 index 0000000000..70805580b2 --- /dev/null +++ b/apps/web/components/task/use-task-review-shortcut.ts @@ -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(value: T) { + const ref = useRef(value); + ref.current = value; + return ref; +} + +type ReviewShortcutLifecycleOptions = { + activeShortcutRef: RefObject; + cancelledRef: RefObject; + commitOnReleaseRef: RefObject; + openRef: RefObject; + 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, +) { + 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; + selectedIndexRef: RefObject; + 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(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, + }; +} diff --git a/apps/web/e2e/tests/pr/pr-open-shortcut.spec.ts b/apps/web/e2e/tests/pr/pr-open-shortcut.spec.ts index efe9597aee..da2997ab6c 100644 --- a/apps/web/e2e/tests/pr/pr-open-shortcut.spec.ts +++ b/apps/web/e2e/tests/pr/pr-open-shortcut.spec.ts @@ -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 { + 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: "github stub" }), + ); + await page + .context() + .route(`${GITLAB_HOST}/**`, (route) => + route.fulfill({ contentType: "text/html", body: "gitlab stub" }), + ); +} + +async function holdTaskReviewShortcut(page: Page): Promise { + 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: "github stub" }), - ); + 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: "github stub" }), - ); + await stubExternalProviders(testPage); const popupPromise = testPage.context().waitForEvent("page"); await testPage.keyboard.press(SHORTCUT); diff --git a/docs/plans/task-review-shortcut-switcher/plan.md b/docs/plans/task-review-shortcut-switcher/plan.md new file mode 100644 index 0000000000..75ee616205 --- /dev/null +++ b/docs/plans/task-review-shortcut-switcher/plan.md @@ -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. diff --git a/docs/plans/task-review-shortcut-switcher/task-01-held-review-switcher.md b/docs/plans/task-review-shortcut-switcher/task-01-held-review-switcher.md new file mode 100644 index 0000000000..1764b7a1cb --- /dev/null +++ b/docs/plans/task-review-shortcut-switcher/task-01-held-review-switcher.md @@ -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. diff --git a/docs/plans/task-review-shortcut-switcher/task-02-shortcut-switcher-e2e.md b/docs/plans/task-review-shortcut-switcher/task-02-shortcut-switcher-e2e.md new file mode 100644 index 0000000000..c44e681020 --- /dev/null +++ b/docs/plans/task-review-shortcut-switcher/task-02-shortcut-switcher-e2e.md @@ -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. diff --git a/docs/specs/INDEX.md b/docs/specs/INDEX.md index 49aae3cd85..4c41d48f8a 100644 --- a/docs/specs/INDEX.md +++ b/docs/specs/INDEX.md @@ -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 | diff --git a/docs/specs/ui/task-review-shortcut.md b/docs/specs/ui/task-review-shortcut.md new file mode 100644 index 0000000000..555e85fdea --- /dev/null +++ b/docs/specs/ui/task-review-shortcut.md @@ -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)