feat(berth-deal-docs): clickable rows open in-page file preview

The Interest Documents tab on the berth detail page listed deal docs
read-only with only an "Open" link to the interest detail page —
forced reps to navigate away just to see the PDF. Now every row whose
backing PDF exists opens the existing FilePreviewDialog inline.

- Service: listDealDocumentsForBerth now joins files and returns
  fileId (COALESCE(signedFileId, fileId) so completed envelopes
  prefer the signed PDF), fileName, mimeType. Drafts without a blob
  yet still appear, just non-clickable.
- UI: row title area is a button that triggers FilePreviewDialog;
  Eye affordance on hover. Falls back to a "no file yet" hint when
  the document has no backing blob. "Open" link stays as the
  secondary "go to interest" action.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/components/berths/berth-deal-documents-tab.tsx

@@ -1,13 +1,15 @@
 'use client';
 
+import { useState } from 'react';
 import Link from 'next/link';
 import { useParams } from 'next/navigation';
 import { useQuery } from '@tanstack/react-query';
-import { FileText, ExternalLink } from 'lucide-react';
+import { FileText, ExternalLink, Eye } from 'lucide-react';
 
 import { apiFetch } from '@/lib/api/client';
 import { Badge } from '@/components/ui/badge';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { FilePreviewDialog } from '@/components/files/file-preview-dialog';
 
 interface BerthDealDoc {
   id: string;
@@ -16,6 +18,9 @@ interface BerthDealDoc {
   status: string;
   createdAt: string;
   interestId: string;
+  fileId: string | null;
+  fileName: string | null;
+  mimeType: string | null;
 }
 
 const STATUS_TONE: Record<string, 'default' | 'secondary' | 'outline' | 'destructive'> = {
@@ -30,6 +35,7 @@ const STATUS_TONE: Record<string, 'default' | 'secondary' | 'outline' | 'destruc
 export function BerthDealDocumentsTab({ berthId }: { berthId: string }) {
   const params = useParams<{ portSlug: string }>();
   const portSlug = params?.portSlug ?? '';
+  const [previewDoc, setPreviewDoc] = useState<BerthDealDoc | null>(null);
 
   const { data: docs = [], isLoading } = useQuery<BerthDealDoc[]>({
     queryKey: ['berth-interest-documents', berthId],
@@ -59,16 +65,44 @@ export function BerthDealDocumentsTab({ berthId }: { berthId: string }) {
             </p>
           ) : (
             <ul className="divide-y">
-              {docs.map((doc) => (
+              {docs.map((doc) => {
+                const canPreview = Boolean(doc.fileId);
+                return (
                   <li
                     key={doc.id}
                     className="flex flex-wrap items-center justify-between gap-2 py-2.5 text-sm"
                   >
-                  <div className="flex min-w-0 items-center gap-2">
+                    {/* Title area is itself the preview trigger when a
+                        backing file exists. Falls back to a non-clickable
+                        row for drafts whose PDF hasn't landed yet. */}
+                    {canPreview ? (
+                      <button
+                        type="button"
+                        onClick={() => setPreviewDoc(doc)}
+                        className="flex min-w-0 flex-1 items-center gap-2 rounded -mx-1 px-1 py-0.5 text-left hover:bg-muted/60 focus-visible:bg-muted/60 focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
+                        title="Preview document"
+                      >
                         <FileText className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
                         <span className="truncate font-medium">{doc.title}</span>
                         <span className="text-xs text-muted-foreground">{doc.documentType}</span>
+                        <Eye
+                          className="ml-1 h-3 w-3 shrink-0 opacity-40 transition-opacity group-hover:opacity-80"
+                          aria-hidden
+                        />
+                      </button>
+                    ) : (
+                      <div className="flex min-w-0 flex-1 items-center gap-2">
+                        <FileText className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+                        <span className="truncate font-medium">{doc.title}</span>
+                        <span className="text-xs text-muted-foreground">{doc.documentType}</span>
+                        <span
+                          className="text-xs italic text-muted-foreground"
+                          title="No PDF attached yet — open on the interest to generate or upload"
+                        >
+                          no file yet
+                        </span>
                       </div>
+                    )}
                     <div className="flex items-center gap-2">
                       <Badge variant={STATUS_TONE[doc.status] ?? 'outline'}>{doc.status}</Badge>
                       <Link
@@ -80,11 +114,20 @@ export function BerthDealDocumentsTab({ berthId }: { berthId: string }) {
                       </Link>
                     </div>
                   </li>
-              ))}
+                );
+              })}
             </ul>
           )}
         </CardContent>
       </Card>
+
+      <FilePreviewDialog
+        open={!!previewDoc?.fileId}
+        onOpenChange={(open) => !open && setPreviewDoc(null)}
+        fileId={previewDoc?.fileId ?? undefined}
+        fileName={previewDoc?.fileName ?? previewDoc?.title ?? undefined}
+        mimeType={previewDoc?.mimeType ?? undefined}
+      />
     </div>
   );
 }

src/lib/services/documents.service.ts

@@ -348,6 +348,13 @@ export interface BerthDealDoc {
   status: string;
   createdAt: Date;
   interestId: string;
+  /** ID of the file blob backing this document (signed PDF if completed,
+   *  otherwise the source upload). Null when no file is attached yet
+   *  (e.g. a draft envelope before its PDF lands). Drives the in-page
+   *  preview affordance — rows without a fileId render as non-clickable. */
+  fileId: string | null;
+  fileName: string | null;
+  mimeType: string | null;
 }
 
 /**
@@ -365,6 +372,14 @@ export async function listDealDocumentsForBerth(
   portId: string,
   berthId: string,
 ): Promise<BerthDealDoc[]> {
+  // Resolve the preview-worthy file in SQL via COALESCE(signed_file_id,
+  // file_id) so completed envelopes prefer their signed PDF while drafts
+  // fall back to the source upload. LEFT JOIN files so envelopes without
+  // any blob yet (drafts before placement) still appear, just without a
+  // preview affordance.
+  const previewFileId = sql<
+    string | null
+  >`COALESCE(${documents.signedFileId}, ${documents.fileId})`;
   const rows = await db
     .select({
       id: documents.id,
@@ -373,10 +388,14 @@ export async function listDealDocumentsForBerth(
       status: documents.status,
       createdAt: documents.createdAt,
       interestId: documents.interestId,
+      fileId: previewFileId,
+      fileName: files.filename,
+      mimeType: files.mimeType,
     })
     .from(documents)
     .innerJoin(interestBerths, eq(interestBerths.interestId, documents.interestId))
     .innerJoin(interests, eq(interests.id, documents.interestId))
+    .leftJoin(files, and(eq(files.id, previewFileId), eq(files.portId, portId)))
     .where(
       and(
         eq(interestBerths.berthId, berthId),
@@ -395,6 +414,9 @@ export async function listDealDocumentsForBerth(
       status: r.status,
       createdAt: r.createdAt,
       interestId: r.interestId,
+      fileId: r.fileId ?? null,
+      fileName: r.fileName ?? null,
+      mimeType: r.mimeType ?? null,
     }));
 }