10d4eb738a
Two-plan wave structure for PREV-01: preview API route + modal (Plan 01, Wave 1) then PreparePanel/FieldPlacer wiring + human verification (Plan 02, Wave 2). Send button gated on previewToken staleness detection. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
15 KiB
15 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 12-filled-document-preview | 02 | execute | 2 |
|
|
false |
|
|
Purpose: Plan 01 created the API route and modal. Plan 02 connects them to the UI and enforces PREV-01's gating requirement — Send is unavailable until at least one fresh preview is generated.
Output:
- PreparePanel updated with previewToken state, handlePreview fetch, PreviewModal rendering, Send button gated on token
- FieldPlacer updated with onFieldsChanged prop — calls it after every persistFields() invocation
- Human checkpoint verifying the full Preview-gate-Send flow
<execution_context> @/Users/ccopeland/.claude/get-shit-done/workflows/execute-plan.md @/Users/ccopeland/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/12-filled-document-preview/12-01-SUMMARY.mdCurrent PreparePanel.tsx props interface (do not remove existing props):
interface PreparePanelProps {
docId: string;
defaultEmail: string;
clientName: string;
currentStatus: string;
agentDownloadUrl?: string | null;
signedAt?: Date | null;
clientPropertyAddress?: string | null;
}
Current PreparePanel.tsx Send button (line ~160-167):
<button
onClick={handlePrepare}
disabled={loading || parseEmails(recipients).length === 0}
className="w-full py-2 px-4 bg-blue-600 text-white rounded hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed text-sm font-medium"
type="button"
>
{loading ? 'Preparing...' : 'Prepare and Send'}
</button>
Current FieldPlacerProps interface (add onFieldsChanged to this):
interface FieldPlacerProps {
docId: string;
pageInfo: PageInfo | null;
currentPage: number;
children: React.ReactNode;
readOnly?: boolean;
// ADD: onFieldsChanged?: () => void;
}
persistFields() call sites in FieldPlacer.tsx (must call onFieldsChanged?.() after each):
- Inside handleDragEnd callback: after
persistFields(docId, next) - Inside handleZonePointerUp / pointer move handlers: after
persistFields(docId, next) - Delete button onClick handler: after
persistFields(docId, next)(Search for allpersistFields(docIdoccurrences and addonFieldsChanged?.()immediately after each)
PreviewModal export from Plan 01:
// src/app/portal/(protected)/documents/[docId]/_components/PreviewModal.tsx
export function PreviewModal({ pdfBytes, onClose }: { pdfBytes: ArrayBuffer; onClose: () => void })
1. Add three new state variables after existing state declarations:
```typescript
const [previewToken, setPreviewToken] = useState<string | null>(null);
const [previewBytes, setPreviewBytes] = useState<ArrayBuffer | null>(null);
const [showPreview, setShowPreview] = useState(false);
```
2. Add a `handlePreview` async function (alongside `handlePrepare`):
```typescript
async function handlePreview() {
setLoading(true);
setResult(null);
try {
const res = await fetch(`/api/documents/${docId}/preview`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ textFillData }),
});
if (res.ok) {
const bytes = await res.arrayBuffer();
setPreviewBytes(bytes);
setPreviewToken(Date.now().toString());
setShowPreview(true);
} else {
const err = await res.json().catch(() => ({ error: 'Preview failed' }));
setResult({ ok: false, message: err.message ?? err.error ?? 'Preview failed' });
}
} catch (e) {
setResult({ ok: false, message: String(e) });
} finally {
setLoading(false);
}
}
```
3. Update `setTextFillData` usage: wherever `setTextFillData` is called (currently via `TextFillForm onChange`), also reset the stale token. The TextFillForm onChange prop currently calls `setTextFillData` directly. Change it to a wrapper:
```typescript
function handleTextFillChange(data: Record<string, string>) {
setTextFillData(data);
setPreviewToken(null);
}
```
Then pass `onChange={handleTextFillChange}` to `<TextFillForm>`.
4. Add a `handleFieldsChanged` callback to be passed to FieldPlacer (used in Task 2):
```typescript
function handleFieldsChanged() {
setPreviewToken(null);
}
```
5. Update the Send button's disabled condition to include `previewToken === null`:
```tsx
disabled={loading || previewToken === null || parseEmails(recipients).length === 0}
```
6. Add the Preview button immediately BEFORE the Send button:
```tsx
<button
onClick={handlePreview}
disabled={loading}
className="w-full py-2 px-4 bg-gray-700 text-white rounded hover:bg-gray-800 disabled:opacity-50 disabled:cursor-not-allowed text-sm font-medium"
type="button"
>
{loading ? 'Generating preview...' : previewToken ? 'Preview again' : 'Preview'}
</button>
```
7. Render PreviewModal conditionally after the Send button:
```tsx
{showPreview && previewBytes && (
<PreviewModal pdfBytes={previewBytes} onClose={() => setShowPreview(false)} />
)}
```
8. Add import for PreviewModal at the top: `import { PreviewModal } from './PreviewModal';`
9. Export `handleFieldsChanged` is for internal use only — it will be passed as a prop to FieldPlacer which is a sibling component rendered in the document page, not within PreparePanel itself. Check the document page file (`page.tsx` in `[docId]/`) to see how FieldPlacer and PreparePanel are composed together. If they are rendered at the same level in a server component, you may need to create a small client wrapper or pass the callback via a prop. If PreparePanel and FieldPlacer are already siblings in a client component, handle the wiring there. If they are co-located in the same client component, expose `onFieldsChanged` as a prop to PreparePanel. Use whichever composition pattern already exists — do not over-engineer.
Note: If FieldPlacer is rendered inside PreparePanel or alongside it in the same client component, the simplest approach is to pass `onFieldsChanged={handleFieldsChanged}` to FieldPlacer directly from wherever FieldPlacer is currently rendered.
1. Update the interface:
```typescript
interface FieldPlacerProps {
docId: string;
pageInfo: PageInfo | null;
currentPage: number;
children: React.ReactNode;
readOnly?: boolean;
onFieldsChanged?: () => void; // NEW
}
```
2. Destructure in the function signature:
```typescript
export function FieldPlacer({ docId, pageInfo, currentPage, children, readOnly = false, onFieldsChanged }: FieldPlacerProps)
```
3. Find every call to `persistFields(docId, ...)` in the file (there are multiple — in handleDragEnd, in pointer event handlers, and in the delete button onClick). After EACH one, add:
```typescript
onFieldsChanged?.();
```
4. Do not call `onFieldsChanged` in `loadFields()` (the initial load) — only after user-initiated mutations.
Then wire the prop in the document page: find where FieldPlacer is rendered (likely in the document [docId] page.tsx or a layout component). Pass `onFieldsChanged` from wherever PreparePanel's `handleFieldsChanged` can be reached. If FieldPlacer and PreparePanel are rendered at the same level in a server component and cannot share state directly, create a minimal `DocumentPageClient.tsx` wrapper component that holds the `previewToken` reset callback and passes it down to both FieldPlacer and PreparePanel — but only if necessary. Prefer the simplest wiring that makes the staleness detection work.
Manual check: Search for all `persistFields(docId` occurrences in FieldPlacer.tsx and confirm `onFieldsChanged?.()` follows each one.
```bash
grep -n "persistFields\|onFieldsChanged" /Users/ccopeland/temp/red/teressa-copeland-homes/src/app/portal/\(protected\)/documents/\[docId\]/_components/FieldPlacer.tsx
```
Every `persistFields` line should have a corresponding `onFieldsChanged` immediately after.
grep -n "previewToken\|handlePreview\|PreviewModal" /Users/ccopeland/temp/red/teressa-copeland-homes/src/app/portal/\(protected\)/documents/\[docId\]/_components/PreparePanel.tsx
All three appear in PreparePanel.
grep -n "onFieldsChanged" /Users/ccopeland/temp/red/teressa-copeland-homes/src/app/portal/\(protected\)/documents/\[docId\]/_components/FieldPlacer.tsx
Appears in interface, destructure, and at least 2 call sites.
<success_criteria>
- Preview button visible in PreparePanel on Draft documents
- Send button disabled until at least one preview generated
- Text fill changes re-disable Send button
- Field changes (drag/drop/delete) re-disable Send button
- Preview modal opens with correct fully-embedded PDF content
- Page navigation works in modal
- No preview*.pdf files linger in uploads/ after preview
- Human approves all 12 verification steps
- PREV-01 requirement complete </success_criteria>