docs(13-03): complete AI Auto-place UI wire-up plan — violet button, aiPlacementKey, handleAiAutoPlace
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Chandler Copeland
@@ -0,0 +1,116 @@
|
||||
---
|
||||
phase: 13-ai-field-placement-and-pre-fill
|
||||
plan: "03"
|
||||
subsystem: ui
|
||||
tags: [react, nextjs, typescript, ai, field-placement]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 13-01
|
||||
provides: AI field placement utilities (aiCoordsToPagePdfSpace, classifyFieldsWithAI, extractPdfText)
|
||||
- phase: 13-02
|
||||
provides: POST /api/documents/[id]/ai-prepare route that writes AI-placed fields to DB and returns textFillData
|
||||
|
||||
provides:
|
||||
- "AI Auto-place Fields" violet button in PreparePanel for Draft documents
|
||||
- aiPlacementKey prop on FieldPlacer that triggers loadFields re-fetch when incremented
|
||||
- aiPlacementKey threaded through PdfViewerWrapper and PdfViewer
|
||||
- handleAiAutoPlace in DocumentPageClient that calls ai-prepare route, merges textFillData, increments key, resets preview
|
||||
affects:
|
||||
- 13-04
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- aiPlacementKey integer state as a cache-busting trigger for FieldPlacer re-fetch
|
||||
- Merge pattern for AI textFillData (AI values take precedence over existing manual values)
|
||||
- Callback-prop pattern for async operations from child to parent (onAiAutoPlace)
|
||||
|
||||
key-files:
|
||||
created: []
|
||||
modified:
|
||||
- teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/FieldPlacer.tsx
|
||||
- teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewer.tsx
|
||||
- teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewerWrapper.tsx
|
||||
- teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx
|
||||
- teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx
|
||||
|
||||
key-decisions:
|
||||
- "aiPlacementKey integer incremented via setAiPlacementKey(k => k + 1) — functional update prevents stale closure issues"
|
||||
- "textFillData is MERGED not replaced — {...prev, ...aiTextFill} preserves manually typed values while AI values take precedence"
|
||||
- "previewToken reset to null after AI placement — agent must re-preview after AI changes fields"
|
||||
- "AI button uses violet (#7c3aed / bg-violet-600) to visually distinguish from gray Preview and blue Prepare-and-Send"
|
||||
- "Error from ai-prepare route is thrown in handleAiAutoPlace and caught by PreparePanel's handleAiAutoPlaceClick — surfaced via existing result state"
|
||||
|
||||
patterns-established:
|
||||
- "aiPlacementKey pattern: integer state in parent (DocumentPageClient), threaded as prop down through PdfViewerWrapper -> PdfViewer -> FieldPlacer, added to useEffect dependency array for re-fetch"
|
||||
|
||||
requirements-completed: [AI-01, AI-02]
|
||||
|
||||
# Metrics
|
||||
duration: 2min
|
||||
completed: 2026-03-21
|
||||
---
|
||||
|
||||
# Phase 13 Plan 03: AI Field Placement UI Wire-up Summary
|
||||
|
||||
**Violet "AI Auto-place Fields" button in PreparePanel triggers POST /api/documents/[id]/ai-prepare, merges pre-fill data, and re-fetches DB fields via aiPlacementKey cache-busting prop threaded through PdfViewerWrapper to FieldPlacer**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 2 min
|
||||
- **Started:** 2026-03-21T23:06:18Z
|
||||
- **Completed:** 2026-03-21T23:08:27Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 5
|
||||
|
||||
## Accomplishments
|
||||
- FieldPlacer accepts `aiPlacementKey` prop and includes it in the loadFields useEffect dependency array, triggering a re-fetch whenever AI places fields
|
||||
- PdfViewer and PdfViewerWrapper thread `aiPlacementKey` through the component chain from DocumentPageClient to FieldPlacer
|
||||
- PreparePanel has "AI Auto-place Fields" violet button with dedicated aiLoading state, error display via existing result state, and disabled during any loading
|
||||
- DocumentPageClient orchestrates handleAiAutoPlace: calls ai-prepare route, merges AI pre-fills into textFillData, increments aiPlacementKey, resets previewToken
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Add aiPlacementKey prop to FieldPlacer and thread through PdfViewerWrapper** - `3e11eef` (feat)
|
||||
2. **Task 2: Add AI Auto-place button to PreparePanel and wire DocumentPageClient handler** - `bfdaee1` (feat)
|
||||
|
||||
**Plan metadata:** (docs commit — see below)
|
||||
|
||||
## Files Created/Modified
|
||||
- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/FieldPlacer.tsx` - Added aiPlacementKey prop, added to loadFields useEffect deps
|
||||
- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewer.tsx` - Added aiPlacementKey prop, passes to FieldPlacer
|
||||
- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewerWrapper.tsx` - Added aiPlacementKey prop, passes to PdfViewer
|
||||
- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx` - Added onAiAutoPlace prop, aiLoading state, handleAiAutoPlaceClick, violet AI button above Preview
|
||||
- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx` - Added aiPlacementKey state, handleAiAutoPlace callback, wired both to PdfViewerWrapper and PreparePanel
|
||||
|
||||
## Decisions Made
|
||||
- aiPlacementKey uses functional update `setAiPlacementKey(k => k + 1)` to avoid stale closure issues
|
||||
- textFillData merges via `{...prev, ...aiTextFill}` — AI values take precedence; manual edits for other fields are preserved
|
||||
- AI button is violet (#7c3aed / bg-violet-600) to visually distinguish from gray Preview button and blue Prepare-and-Send
|
||||
- Error thrown by handleAiAutoPlace is caught in PreparePanel's handleAiAutoPlaceClick and displayed via the existing `result` state
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- All client-side AI wiring complete: button, loading state, error display, field re-fetch, textFillData merge, preview reset
|
||||
- Phase 13 Plan 04 (E2E human verification) is ready — agent can now test the full AI placement flow in the browser
|
||||
- Existing functionality unchanged: drag-and-drop, click-to-edit, quick-fill, preview, prepare-and-send all unaffected
|
||||
|
||||
---
|
||||
*Phase: 13-ai-field-placement-and-pre-fill*
|
||||
*Completed: 2026-03-21*
|
||||
Reference in New Issue
Block a user