feat(16-02): PreparePanel signer list UI, send-block validation, persist signers to DB

teressa-copeland-homes/src/app/api/documents/[id]/prepare/route.ts

@@ -1,6 +1,7 @@
 import { auth } from '@/lib/auth';
 import { db } from '@/lib/db';
 import { documents, users, getFieldType } from '@/lib/db/schema';
+import type { DocumentSigner } from '@/lib/db/schema';
 import { eq } from 'drizzle-orm';
 import { preparePdf } from '@/lib/pdf/prepare-document';
 import { logAuditEvent } from '@/lib/signing/audit';
@@ -21,6 +22,8 @@ export async function POST(
     assignedClientId?: string;
     /** Email addresses to send the document to (client email + any CC addresses). */
     emailAddresses?: string[];
+    /** Multi-signer list with assigned colors. Saved to documents.signers. */
+    signers?: DocumentSigner[];
   };
 
   const doc = await db.query.documents.findFirst({ where: eq(documents.id, id) });
@@ -75,6 +78,8 @@ export async function POST(
       textFillData: body.textFillData ?? null,
       assignedClientId: body.assignedClientId ?? doc.assignedClientId ?? null,
       emailAddresses: body.emailAddresses ?? null,
+      // Persist signer list if provided — required before send route reads documents.signers
+      ...(body.signers !== undefined ? { signers: body.signers } : {}),
       status: 'Sent',
       sentAt: new Date(),
     })

teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx

@@ -2,12 +2,16 @@
 import { useState, useEffect } from 'react';
 import { useRouter } from 'next/navigation';
 import dynamic from 'next/dynamic';
-import type { DocumentSigner } from '@/lib/db/schema';
+import type { DocumentSigner, SignatureFieldData } from '@/lib/db/schema';
+import { isClientVisibleField } from '@/lib/db/schema';
 
 // PreviewModal imports react-pdf which calls new DOMMatrix() at module level —
 // must be loaded client-only to avoid SSR crash, same pattern as PdfViewer.
 const PreviewModal = dynamic(() => import('./PreviewModal').then(m => m.PreviewModal), { ssr: false });
 
+/** Auto-assigned signer color palette (D-01). Cycles if more than 4 signers. */
+const SIGNER_COLORS = ['#6366f1', '#f43f5e', '#10b981', '#f59e0b'];
+
 interface PreparePanelProps {
   docId: string;
   defaultEmail: string;
@@ -22,7 +26,7 @@ interface PreparePanelProps {
   selectedFieldId: string | null;
   onQuickFill: (fieldId: string, value: string) => void;
   onAiAutoPlace: () => Promise<void>;
-  // Multi-signer props — wired in Phase 16, consumed in Wave 2
+  // Multi-signer props — wired in Phase 16 Plan 01, consumed here in Plan 02
   signers?: DocumentSigner[];
   onSignersChange?: (signers: DocumentSigner[]) => void;
   unassignedFieldIds?: Set<string>;
@@ -43,6 +47,9 @@ export function PreparePanel({
   previewToken, onPreviewTokenChange,
   textFillData, selectedFieldId, onQuickFill,
   onAiAutoPlace,
+  signers = [],
+  onSignersChange,
+  onUnassignedFieldIdsChange,
 }: PreparePanelProps) {
   const router = useRouter();
   const [recipients, setRecipients] = useState(defaultEmail ?? '');
@@ -56,6 +63,32 @@ export function PreparePanel({
   const [previewBytes, setPreviewBytes] = useState<ArrayBuffer | null>(null);
   const [showPreview, setShowPreview] = useState(false);
 
+  // Signer list local state
+  const [signerInput, setSignerInput] = useState('');
+  const [signerInputError, setSignerInputError] = useState<string | null>(null);
+
+  function handleAddSigner() {
+    const email = signerInput.trim().toLowerCase();
+    if (!email || !isValidEmail(email)) {
+      setSignerInputError('invalid');
+      return;
+    }
+    if (signers.some(s => s.email === email)) {
+      setSignerInputError('duplicate');
+      return;
+    }
+    const color = SIGNER_COLORS[signers.length % SIGNER_COLORS.length];
+    onSignersChange?.([...signers, { email, color }]);
+    setSignerInput('');
+    setSignerInputError(null);
+  }
+
+  function handleRemoveSigner(email: string) {
+    onSignersChange?.(signers.filter(s => s.email !== email));
+    // Clear validation state since signer count changed
+    onUnassignedFieldIdsChange?.(new Set());
+  }
+
   if (currentStatus === 'Signed') {
     return (
       <div style={{ borderRadius: '0.5rem', border: '1px solid #D1FAE5', padding: '1rem', backgroundColor: '#F0FDF4' }}>
@@ -163,10 +196,32 @@ export function PreparePanel({
     }
 
     try {
+      // Send-block validation: fetch current fields and check for unassigned client-visible fields
+      const fieldsRes = await fetch(`/api/documents/${docId}/fields`);
+      const allFields: SignatureFieldData[] = await fieldsRes.json();
+      const clientFields = allFields.filter(isClientVisibleField);
+
+      if (signers.length === 0 && clientFields.length > 0) {
+        setResult({ ok: false, message: 'Add at least one signer before sending.' });
+        setLoading(false);
+        return;
+      }
+
+      const unassigned = clientFields.filter((f: SignatureFieldData) => !f.signerEmail);
+      if (unassigned.length > 0 && signers.length > 0) {
+        onUnassignedFieldIdsChange?.(new Set(unassigned.map((f: SignatureFieldData) => f.id)));
+        setResult({ ok: false, message: `${unassigned.length} field(s) need a signer assigned before sending.` });
+        setLoading(false);
+        return;
+      }
+
+      // Clear any previous unassigned field highlights
+      onUnassignedFieldIdsChange?.(new Set());
+
       const prepareRes = await fetch(`/api/documents/${docId}/prepare`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ textFillData, emailAddresses }),
+        body: JSON.stringify({ textFillData, emailAddresses, signers }),
       });
       if (!prepareRes.ok) {
         const err = await prepareRes.json().catch(() => ({ error: 'Unknown error' }));
@@ -252,6 +307,52 @@ export function PreparePanel({
         )}
       </div>
 
+      {/* Signer list section — D-02, D-03 */}
+      <div>
+        <label className="block text-sm font-medium text-gray-700 mb-1">Signers</label>
+        <div className="flex gap-2">
+          <input
+            type="email"
+            value={signerInput}
+            onChange={(e) => { setSignerInput(e.target.value); setSignerInputError(null); }}
+            onKeyDown={(e) => { if (e.key === 'Enter') { e.preventDefault(); handleAddSigner(); } }}
+            placeholder="signer@example.com"
+            className={`flex-1 border rounded-md px-2 py-1.5 text-sm ${signerInputError ? 'border-red-400' : 'border-gray-300'}`}
+          />
+          <button
+            type="button"
+            onClick={handleAddSigner}
+            disabled={signerInput.trim() === ''}
+            className="bg-gray-700 text-white px-3 py-1.5 rounded-md text-sm font-medium hover:bg-gray-800 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            Add Signer
+          </button>
+        </div>
+        <p className="text-xs text-gray-400 mt-1">Each signer receives their own signing link.</p>
+        {signerInputError === 'duplicate' && (
+          <p className="text-sm text-red-600 mt-1">That email is already in the signer list.</p>
+        )}
+        {signers.length === 0 ? (
+          <p className="text-sm text-gray-400 italic mt-2">No signers added yet.</p>
+        ) : (
+          <div className="space-y-1.5 mt-2">
+            {signers.map(signer => (
+              <div key={signer.email} className="flex items-center gap-2 bg-white border border-gray-200 rounded-md py-1 px-2">
+                <span className="w-2 h-2 rounded-full flex-shrink-0" style={{ backgroundColor: signer.color }} />
+                <span className="flex-1 text-sm text-gray-700 truncate">{signer.email}</span>
+                <button
+                  type="button"
+                  onClick={() => handleRemoveSigner(signer.email)}
+                  className="w-8 h-8 flex items-center justify-center text-gray-400 hover:text-red-600 cursor-pointer"
+                  style={{ background: 'none', border: 'none', fontSize: '16px', lineHeight: 1 }}
+                  aria-label={`Remove signer ${signer.email}`}
+                >&#xd7;</button>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
       <button
         onClick={handleAiAutoPlaceClick}
         disabled={aiLoading || loading}