---
phase: 12.1-per-field-text-editing-and-quick-fill
plan: 02
subsystem: document-editor, state-management
tags: [text-fill, quick-fill, state-lifting, ux, react]
dependency_graph:
  requires:
    - 12.1-01 (prop chain PdfViewerWrapper->PdfViewer->FieldPlacer, click-to-select inline input)
  provides:
    - selectedFieldId + textFillData shared state in DocumentPageClient
    - QuickFillPanel in PreparePanel sidebar (Client Name / Property Address / Client Email)
    - previewToken staleness reset on every text value change
  affects:
    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx
    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx
    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/TextFillForm.tsx (deleted)
tech_stack:
  added: []
  patterns:
    - state-lifting (selectedFieldId + textFillData lifted to DocumentPageClient for cross-component sync)
    - callback prop pattern (handleFieldValueChange and handleQuickFill passed down as props)
    - conditional sidebar panel (QuickFillPanel only visible when selectedFieldId non-null)
key_files:
  created: []
  modified:
    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx
    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx
  deleted:
    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/TextFillForm.tsx
decisions:
  - "[Phase 12.1-02]: textFillData starts as {} in DocumentPageClient — NOT seeded from clientPropertyAddress; old label-keyed seeding ({ propertyAddress: clientPropertyAddress }) is removed; quick-fill makes it trivial to insert the value once a field is selected"
  - "[Phase 12.1-02]: handleFieldValueChange and handleQuickFill are separate useCallback functions that both call setPreviewToken(null) — satisfies TXTF-03 staleness reset on every text change"
  - "[Phase 12.1-02]: defaultEmail reused for Client Email quick-fill button — already a PreparePanel prop (used for recipients pre-fill); no new prop needed (per research Pitfall 3)"
metrics:
  duration_minutes: 5
  completed_date: "2026-03-21"
  tasks_completed: 2
  files_modified: 2
  files_deleted: 1
---

# Phase 12.1 Plan 02: Per-Field Text Editing State Bridge Summary

**One-liner:** selectedFieldId and textFillData lifted to DocumentPageClient; TextFillForm replaced with QuickFillPanel (Client Name / Property Address / Client Email) in PreparePanel; previewToken staleness reset wired to both text-change callbacks.

## Tasks Completed

| # | Task | Commit | Files |
|---|------|--------|-------|
| 1 | Extend DocumentPageClient with selectedFieldId + textFillData shared state | f395819 | DocumentPageClient.tsx |
| 2 | Replace TextFillForm with QuickFillPanel in PreparePanel; delete TextFillForm.tsx | d2ebb2c | PreparePanel.tsx, TextFillForm.tsx (deleted) |

## What Was Built

### Task 1: DocumentPageClient shared state bridge

Extended `DocumentPageClient.tsx` from 51 lines to 71 lines:

- **Added** `selectedFieldId` state (`useState<string | null>(null)`) — tracks which text field box is currently selected
- **Added** `textFillData` state (`useState<Record<string, string>>({})`) — UUID-keyed map of text values; starts empty (no legacy label seeding)
- **Added** `handleFieldValueChange(fieldId, value)` callback — updates textFillData and resets previewToken to null (TXTF-03)
- **Added** `handleQuickFill(fieldId, value)` callback — same as handleFieldValueChange but semantically separate for quick-fill button clicks
- **Passed** all 4 new props to `PdfViewerWrapper`: `selectedFieldId`, `textFillData`, `onFieldSelect={setSelectedFieldId}`, `onFieldValueChange={handleFieldValueChange}`
- **Passed** 3 new props to `PreparePanel`: `textFillData`, `selectedFieldId`, `onQuickFill={handleQuickFill}`

### Task 2: PreparePanel QuickFillPanel + TextFillForm deletion

Overhauled `PreparePanel.tsx`:

- **Removed** `textFillData` local state (seeded with `{ propertyAddress: clientPropertyAddress }` — label-keyed broken pattern)
- **Removed** `handleTextFillChange` function
- **Removed** `TextFillForm` import and JSX block
- **Added** 3 new props to `PreparePanelProps`: `textFillData: Record<string, string>`, `selectedFieldId: string | null`, `onQuickFill: (fieldId: string, value: string) => void`
- **Added** QuickFillPanel JSX: conditionally renders when `selectedFieldId` is non-null — shows Client Name, Property Address (if set), and Client Email quick-fill buttons; idle state shows "Click a text field on the document to edit or quick-fill it."
- **Updated** `handlePreview` and `handlePrepare` — both now use `textFillData` from props (not local state); JSON body unchanged
- **Deleted** `TextFillForm.tsx` — generic label/value row form no longer used anywhere

## Deviations from Plan

None — plan executed exactly as written.

## Verification

- `npx tsc --noEmit` passes with zero errors
- No import or reference to `TextFillForm` anywhere in the codebase
- `PreparePanel` has `textFillData`, `selectedFieldId`, `onQuickFill` in props interface
- `DocumentPageClient` has `selectedFieldId` and `textFillData` state variables
- Both `handleFieldValueChange` and `handleQuickFill` call `setPreviewToken(null)`
- `handlePreview` and `handlePrepare` use `textFillData` from props

## Checkpoint: Awaiting Human Verification

Task 3 is a `checkpoint:human-verify` gate. The automated work is complete. Human browser verification of the full per-field text editing and quick-fill flow is required before this plan can be marked complete.

## Self-Check: PASSED

- [x] `DocumentPageClient.tsx` exists and modified — contains `selectedFieldId`, `textFillData`, `handleFieldValueChange`, `handleQuickFill`
- [x] `PreparePanel.tsx` exists and modified — contains `onQuickFill`, `selectedFieldId`, `textFillData` props; no TextFillForm
- [x] `TextFillForm.tsx` deleted — file does not exist
- [x] Commit f395819 exists (Task 1)
- [x] Commit d2ebb2c exists (Task 2)