vi.fn());
+
+vi.mock("@/api/issues", () => ({
+ issuesApi: {
+ get: mockIssuesApiGet,
+ },
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+function createIssue(overrides: Partial
= {}): Issue {
+ return {
+ id: "issue-1",
+ identifier: "PAP-1",
+ companyId: "company-1",
+ projectId: null,
+ projectWorkspaceId: null,
+ goalId: null,
+ parentId: null,
+ title: "Quicklook title",
+ description: "Quicklook description",
+ status: "todo",
+ priority: "medium",
+ assigneeAgentId: null,
+ assigneeUserId: null,
+ createdByAgentId: null,
+ createdByUserId: null,
+ issueNumber: 1,
+ requestDepth: 0,
+ billingCode: null,
+ assigneeAdapterOverrides: null,
+ executionWorkspaceId: null,
+ executionWorkspacePreference: null,
+ executionWorkspaceSettings: null,
+ checkoutRunId: null,
+ executionRunId: null,
+ executionAgentNameKey: null,
+ executionLockedAt: null,
+ startedAt: null,
+ completedAt: null,
+ cancelledAt: null,
+ hiddenAt: null,
+ createdAt: new Date("2026-05-01T00:00:00.000Z"),
+ updatedAt: new Date("2026-05-01T00:00:00.000Z"),
+ labels: [],
+ labelIds: [],
+ myLastTouchAt: null,
+ lastExternalCommentAt: null,
+ isUnreadForMe: false,
+ workMode: "standard",
+ ...overrides,
+ };
+}
+
+describe("IssueLinkQuicklook", () => {
+ let container: HTMLDivElement;
+ let root: Root;
+ let queryClient: QueryClient;
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+ queryClient = new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ },
+ },
+ });
+ mockIssuesApiGet.mockResolvedValue(createIssue());
+ });
+
+ afterEach(() => {
+ act(() => {
+ root.unmount();
+ });
+ queryClient.clear();
+ container.remove();
+ vi.useRealTimers();
+ vi.clearAllMocks();
+ });
+
+ it("keeps portaled quicklook links mounted until after blur click handling", () => {
+ const issue = createIssue();
+
+ act(() => {
+ root.render(
+
+
+
+ PAP-1
+
+
+ ,
+ );
+ });
+
+ const trigger = container.querySelector("a") as HTMLAnchorElement | null;
+ expect(trigger).not.toBeNull();
+
+ act(() => {
+ trigger?.focus();
+ });
+
+ expect(document.body.textContent).toContain("Quicklook title");
+
+ act(() => {
+ trigger?.blur();
+ });
+
+ expect(document.body.textContent).toContain("Quicklook title");
+
+ act(() => {
+ vi.runOnlyPendingTimers();
+ });
+
+ expect(document.body.textContent).not.toContain("Quicklook title");
+ });
+});
diff --git a/ui/src/components/IssueLinkQuicklook.tsx b/ui/src/components/IssueLinkQuicklook.tsx
index 16b16822..65a07b1f 100644
--- a/ui/src/components/IssueLinkQuicklook.tsx
+++ b/ui/src/components/IssueLinkQuicklook.tsx
@@ -75,6 +75,8 @@ export const IssueLinkQuicklook = React.forwardRef<
issuePathId: string;
disableIssueQuicklook?: boolean;
issuePrefetch?: Issue | null;
+ issueQuicklookSide?: React.ComponentProps["side"];
+ issueQuicklookAlign?: React.ComponentProps["align"];
}
>(function IssueLinkQuicklookImpl(
{
@@ -85,10 +87,13 @@ export const IssueLinkQuicklook = React.forwardRef<
state,
disableIssueQuicklook = false,
issuePrefetch = null,
+ issueQuicklookSide = "top",
+ issueQuicklookAlign = "start",
onClick,
onClickCapture,
onMouseEnter,
onFocus,
+ onBlur,
onTouchStart,
...props
},
@@ -119,8 +124,14 @@ export const IssueLinkQuicklook = React.forwardRef<
}}
onFocus={(event) => {
handlePrefetch();
+ setOpen(true);
onFocus?.(event);
}}
+ onBlur={(event) => {
+ // Let clicks inside the portaled quicklook content finish before closing.
+ setTimeout(() => setOpen(false), 0);
+ onBlur?.(event);
+ }}
onTouchStart={(event) => {
handlePrefetch();
onTouchStart?.(event);
@@ -157,8 +168,8 @@ export const IssueLinkQuicklook = React.forwardRef<
setOpen(true)}
onMouseLeave={() => setOpen(false)}
onOpenAutoFocus={(event) => event.preventDefault()}
diff --git a/ui/src/components/IssueSiblingNavigation.test.tsx b/ui/src/components/IssueSiblingNavigation.test.tsx
new file mode 100644
index 00000000..d356fcfb
--- /dev/null
+++ b/ui/src/components/IssueSiblingNavigation.test.tsx
@@ -0,0 +1,130 @@
+// @vitest-environment jsdom
+
+import { act, type AnchorHTMLAttributes, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import type { Issue } from "@paperclipai/shared";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { IssueSiblingNavigation } from "./IssueSiblingNavigation";
+
+vi.mock("@/lib/router", () => ({
+ Link: ({
+ children,
+ to,
+ issueQuicklookAlign,
+ issueQuicklookSide,
+ issuePrefetch: _issuePrefetch,
+ state: _state,
+ ...props
+ }: AnchorHTMLAttributes & {
+ to: string;
+ issueQuicklookAlign?: string;
+ issueQuicklookSide?: string;
+ issuePrefetch?: unknown;
+ state?: unknown;
+ children?: ReactNode;
+ }) => (
+
+ {children}
+
+ ),
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+function issue(id: string, overrides: Partial = {}): Issue {
+ return {
+ id,
+ identifier: `PAP-${id}`,
+ title: `Sibling ${id}`,
+ status: "todo",
+ blockerAttention: null,
+ createdAt: new Date("2026-05-01T00:00:00.000Z"),
+ updatedAt: new Date("2026-05-01T00:00:00.000Z"),
+ ...overrides,
+ } as Issue;
+}
+
+let root: Root | null = null;
+let container: HTMLDivElement | null = null;
+
+afterEach(() => {
+ if (root) {
+ act(() => root?.unmount());
+ }
+ root = null;
+ container?.remove();
+ container = null;
+});
+
+function render(node: ReactNode) {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+ act(() => root?.render(node));
+ return container;
+}
+
+describe("IssueSiblingNavigation", () => {
+ it("renders the locked card anatomy for previous and next siblings", () => {
+ const node = render(
+ ,
+ );
+
+ const nav = node.querySelector("nav");
+ expect(nav?.getAttribute("aria-label")).toBe("Sub-issue navigation");
+ expect(nav?.className).toContain("sm:grid-cols-2");
+ expect(nav?.className).not.toContain("border-t");
+
+ const links = Array.from(node.querySelectorAll("a"));
+ expect(links).toHaveLength(2);
+ expect(links[0].textContent).toContain("Previous");
+ expect(links[0].textContent).toContain("PAP-1");
+ expect(links[0].textContent).toContain("Previous sibling title");
+ expect(links[0].getAttribute("aria-label")).toBe("Previous sub-issue: PAP-1 - Previous sibling title");
+ expect(links[0].getAttribute("data-quicklook-align")).toBe("start");
+
+ expect(links[1].textContent).toContain("Next");
+ expect(links[1].textContent).toContain("PAP-3");
+ expect(links[1].textContent).toContain("Next sibling title");
+ expect(links[1].getAttribute("aria-label")).toBe("Next sub-issue: PAP-3 - Next sibling title");
+ expect(links[1].getAttribute("data-quicklook-align")).toBe("end");
+ expect(links[1].className).toContain("sm:text-right");
+
+ expect(links[0].className).toContain("rounded-lg");
+ expect(links[0].className).toContain("hover:bg-accent/50");
+ expect(links[0].className).toContain("focus-visible:ring-[3px]");
+ expect(node.querySelector(".truncate")?.textContent).toBe("Previous sibling title");
+ });
+
+ it("keeps a lone next card in the right desktop column", () => {
+ const node = render(
+ ,
+ );
+
+ const links = Array.from(node.querySelectorAll("a"));
+ expect(links).toHaveLength(1);
+ expect(links[0].textContent).toContain("Next");
+ expect(links[0].className).toContain("sm:col-start-2");
+ expect(node.textContent).not.toContain("Previous");
+ });
+});
diff --git a/ui/src/components/IssueSiblingNavigation.tsx b/ui/src/components/IssueSiblingNavigation.tsx
new file mode 100644
index 00000000..213dfe4d
--- /dev/null
+++ b/ui/src/components/IssueSiblingNavigation.tsx
@@ -0,0 +1,90 @@
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import type { Issue } from "@paperclipai/shared";
+import type { IssueSiblingNavigation as IssueSiblingNavigationState } from "@/lib/issue-detail-subissues";
+import { createIssueDetailPath, withIssueDetailHeaderSeed } from "@/lib/issueDetailBreadcrumb";
+import { cn } from "@/lib/utils";
+import { Link } from "@/lib/router";
+import { StatusIcon } from "./StatusIcon";
+
+type IssueSiblingNavigationProps = {
+ navigation: IssueSiblingNavigationState | null;
+ linkState?: unknown;
+};
+
+export function IssueSiblingNavigation({ navigation, linkState }: IssueSiblingNavigationProps) {
+ if (!navigation) return null;
+
+ return (
+
+ );
+}
+
+function SiblingLink({
+ direction,
+ issue,
+ linkState,
+ className,
+}: {
+ direction: "previous" | "next";
+ issue: Issue;
+ linkState?: unknown;
+ className?: string;
+}) {
+ const issuePathId = issue.identifier ?? issue.id;
+ const label = direction === "previous" ? "Previous" : "Next";
+ const ariaDirection = direction === "previous" ? "Previous sub-issue" : "Next sub-issue";
+ const identifier = issue.identifier ?? issue.id.slice(0, 8);
+ const Icon = direction === "previous" ? ChevronLeft : ChevronRight;
+
+ return (
+
+
+
+ {direction === "previous" ? : null}
+ {label}
+ {direction === "next" ? : null}
+
+
+
+ {identifier}
+
+
+ {issue.title}
+
+