Files
PaperClipAI/ui/src/components/ImageGalleryModal.tsx
T
DottaandPaperclip cd5f930558 Add shareable image galleries to task documents (#18157)
<!-- entire-trail-link-start -->
https://entire.com/gh/paperclipai/-/trails/247/changes/paperclip/247
<!-- entire-trail-link-end -->

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Task documents hold plans, reports, and image evidence.
> - Task attachments already have an image gallery.
> - Inline document images had no gallery navigation or image links.
> - This change gives each document a gallery that uses the existing
modal.
> - People can review the image sequence and share a link to one image.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Image review in task documents, including the side panel and Classic
interface.

**Current behavior**

Inline document images do not open a gallery. People cannot move through
them with arrow keys or share a link to one image.

**Proposed behavior**

Select an image to open the gallery. Use arrow keys or Previous and
Next. The URL records its one-based position, for example
`#document-report&image=2`. Reloading that URL opens the selected image.
Revision links keep their exact saved content.

**Reason and benefit**

People can inspect a document's image evidence in reading order and
share the exact view.

No matching issue was found. The latest 300 open PR titles were checked
for related document gallery work.

## What Changed

- Add a document renderer that collects rendered images in reading
order, including reference-style and repeated images.
- Reuse the gallery modal with optional index-change and focus-return
controls.
- Keep the document owner in the saved tab identity when people switch
between local and other-task documents.
- Match explicit current-task document owners with local document tabs.
Keep review and viewer parameters during gallery navigation.
- Treat another Classic review receipt as a new request while image
navigation retains the selected revision.
- Make inline image controls work with a keyboard. Keep focus in the
modal and restore focus on close.
- Keep document, revision, review, and maximized-view link parameters
during image navigation.
- Fix a Classic revision-cache race found by the browser test. Recheck a
pinned revision when the saved document head changes.
- Update the feature and agent access maps. No new server API or
permission is needed.

## Verification

- Passed 119 focused tests for document galleries, the shared gallery,
document rendering, the revision panel, and hash routing.
- Passed all 3 Chromium journeys: desktop, mobile, and Classic. These
use real uploads and saved document revisions.
- The browser journeys also check explicit current-task owners, review
parameters after reopening, other-task links after tab switches, and a
second Classic review link after Return to latest.
- Browser checks cover keyboard and button navigation, wraparound,
shared-link reload, exact historical content, invalid positions, focus
return and containment, scroll locking, and Escape, Close, and backdrop
dismissal.
- UI typecheck, token gates, map checks, and diff whitespace checks
passed.
- The UI production build passed in the browser harness.
- Earlier browser runs found and then verified the Classic
revision-cache fix. A later build exited 137 while the full test suite
ran. The browser run passed after that suite stopped.
- Full repository typecheck and build could not complete because Cargo
is absent. The full repository test run did not complete within this
sandbox. These checks remain subject to CI.

## Risks

- Image positions follow document reading order. Editing an unpinned
document can change those positions. A revision link retains the saved
sequence.
- The shared modal now uses Radix Escape handling. The existing gallery
tests and nested mobile dialog journey pass.
- No schema change or migration.

## Model Used

OpenAI GPT-6 through Codex. The runtime did not expose a more specific
model ID or context window size. Used reasoning, code editing, shell
commands, and browser automation.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-10-30 07:52:15 -05:00

198 lines
7.0 KiB
TypeScript

import { useCallback, useEffect, useRef, useState, type RefObject } from "react";
import { Dialog as DialogPrimitive } from "radix-ui";
import { ChevronLeft, ChevronRight, Download, X } from "lucide-react";
import { attachmentDownloadPath, attachmentFilename } from "@/lib/issue-attachments";
import { isVideoLikeOutput } from "@/lib/issue-output";
export interface GalleryMediaItem {
id: string;
contentPath: string;
openPath?: string;
downloadPath?: string;
contentType: string;
originalFilename: string | null;
}
interface ImageGalleryModalProps {
items: GalleryMediaItem[];
initialIndex: number;
open: boolean;
onOpenChange: (open: boolean) => void;
onIndexChange?: (index: number) => void;
returnFocusRef?: RefObject<HTMLElement | null>;
}
export function ImageGalleryModal({
items,
initialIndex,
open,
onOpenChange,
onIndexChange,
returnFocusRef,
}: ImageGalleryModalProps) {
const [currentIndex, setCurrentIndex] = useState(initialIndex);
const mediaRef = useRef<HTMLImageElement | HTMLVideoElement | null>(null);
const setMediaRef = useCallback((node: HTMLImageElement | HTMLVideoElement | null) => {
mediaRef.current = node;
}, []);
useEffect(() => {
if (open) setCurrentIndex(initialIndex);
}, [open, initialIndex]);
const goNext = useCallback(() => {
const next = (currentIndex + 1) % items.length;
setCurrentIndex(next);
onIndexChange?.(next);
}, [currentIndex, items.length, onIndexChange]);
const goPrev = useCallback(() => {
const next = (currentIndex - 1 + items.length) % items.length;
setCurrentIndex(next);
onIndexChange?.(next);
}, [currentIndex, items.length, onIndexChange]);
useEffect(() => {
if (currentIndex < items.length) return;
setCurrentIndex(0);
}, [currentIndex, items.length]);
useEffect(() => {
if (!open || items.length < 2) return;
const handler = (e: KeyboardEvent) => {
if (e.key !== "ArrowRight" && e.key !== "ArrowLeft") return;
e.preventDefault();
if (e.key === "ArrowRight") goNext();
else goPrev();
};
window.addEventListener("keydown", handler);
return () => window.removeEventListener("keydown", handler);
}, [open, goNext, goPrev, items.length]);
/** Close when clicking empty curtain space (not interactive elements or the image) */
const handleBackdropClick = useCallback(
(e: React.MouseEvent) => {
const target = e.target as HTMLElement;
if (
target.closest("button") ||
target.closest("a") ||
target === mediaRef.current
)
return;
onOpenChange(false);
},
[onOpenChange],
);
if (items.length === 0) return null;
const current = items[currentIndex];
if (!current) return null;
const filename = attachmentFilename(current);
const isVideo = isVideoLikeOutput(current.contentType, current.originalFilename);
return (
<DialogPrimitive.Root open={open} onOpenChange={onOpenChange}>
<DialogPrimitive.Portal>
{/* Full-screen curtain */}
<DialogPrimitive.Overlay className="fixed inset-0 z-50 bg-black/90 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 duration-200" />
<DialogPrimitive.Content
className="fixed inset-0 z-50 flex flex-col outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 duration-200"
onClick={handleBackdropClick}
aria-describedby={undefined}
onCloseAutoFocus={returnFocusRef ? (event) => {
event.preventDefault();
returnFocusRef.current?.focus({ preventScroll: true });
} : undefined}
>
<DialogPrimitive.Title className="sr-only">Image gallery</DialogPrimitive.Title>
{/* Top bar */}
<div className="flex items-center justify-between px-5 py-3 text-white/80 text-sm shrink-0">
<span className="truncate max-w-(--pct-50) font-medium" title={filename}>
{filename}
</span>
<div className="flex items-center gap-4">
<span className="text-white/40 tabular-nums text-xs">
{currentIndex + 1} / {items.length}
</span>
<a
href={attachmentDownloadPath(current)}
download={filename}
className="text-white/50 hover:text-white transition-colors"
title="Download"
aria-label={`Download ${filename}`}
onClick={(e) => e.stopPropagation()}
>
<Download className="h-4.5 w-4.5" />
</a>
<button
type="button"
onClick={() => onOpenChange(false)}
className="text-white/50 hover:text-white transition-colors"
title="Close"
>
<X className="h-5 w-5" />
</button>
</div>
</div>
{/* Main area: nav buttons outside image */}
<div className="flex-1 flex items-center min-h-0">
{/* Left nav zone */}
<div className="w-16 md:w-24 shrink-0 flex items-center justify-center h-full">
{items.length > 1 && (
<button
type="button"
onClick={goPrev}
className="rounded-full bg-white/10 p-3 text-white/60 hover:text-white hover:bg-white/20 transition-colors"
title="Previous"
>
<ChevronLeft className="h-7 w-7" />
</button>
)}
</div>
{/* Media */}
<div className="flex-1 flex items-center justify-center min-w-0 min-h-0 h-full px-2">
{isVideo ? (
<video
ref={setMediaRef}
src={current.contentPath}
className="max-w-full max-h-full rounded-lg"
controls
playsInline
/>
) : (
<img
ref={setMediaRef}
src={current.contentPath}
alt={filename}
className="max-w-full max-h-full object-contain select-none rounded-lg"
draggable={false}
/>
)}
</div>
{/* Right nav zone */}
<div className="w-16 md:w-24 shrink-0 flex items-center justify-center h-full">
{items.length > 1 && (
<button
type="button"
onClick={goNext}
className="rounded-full bg-white/10 p-3 text-white/60 hover:text-white hover:bg-white/20 transition-colors"
title="Next"
>
<ChevronRight className="h-7 w-7" />
</button>
)}
</div>
</div>
{/* Bottom padding for balance */}
<div className="h-6 shrink-0" />
</DialogPrimitive.Content>
</DialogPrimitive.Portal>
</DialogPrimitive.Root>
);
}