docs(02-01): complete marketing site shell plan — nav, hero, testimonials, footer

- Create 02-01-SUMMARY.md with execution results and deviation docs - Update STATE.md position and session continuity - Update ROADMAP.md phase 02 progress - Mark MKTG-01, MKTG-02, MKTG-04 requirements complete
2026-03-19 15:04:15 -06:00
parent a33b4c9520
commit ffb1ab629d
4 changed files with 178 additions and 23 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -7,10 +7,10 @@

 ### Marketing Site

- [ ] **MKTG-01**: Visitor sees a hero section with Teressa's professional photo and warm introductory bio
- [ ] **MKTG-02**: Visitor sees a "listings coming soon" placeholder section (full WFRMLS listings integration deferred to v2 pending vendor API enrollment)
- [ ] **MKTG-03**: Visitor can submit a contact form with name, email, phone, and message
- [ ] **MKTG-04**: Visitor sees a testimonials section with client reviews on the homepage
+- [x] **MKTG-01**: Visitor sees a hero section with Teressa's professional photo and warm introductory bio
+- [x] **MKTG-02**: Visitor sees a "listings coming soon" placeholder section (full WFRMLS listings integration deferred to v2 pending vendor API enrollment)
+- [x] **MKTG-03**: Visitor can submit a contact form with name, email, phone, and message
+- [x] **MKTG-04**: Visitor sees a testimonials section with client reviews on the homepage

 ### Authentication

@@ -110,10 +110,10 @@ Which phases cover which requirements. Updated during roadmap creation.
 | AUTH-02 | Phase 1 | Complete |
 | AUTH-03 | Phase 1 | Complete |
 | AUTH-04 | Phase 1 | Complete |
-| MKTG-01 | Phase 2 | Pending |
-| MKTG-02 | Phase 2 | Pending |
-| MKTG-03 | Phase 2 | Pending |
-| MKTG-04 | Phase 2 | Pending |
+| MKTG-01 | Phase 2 | Complete |
+| MKTG-02 | Phase 2 | Complete |
+| MKTG-03 | Phase 2 | Complete |
+| MKTG-04 | Phase 2 | Complete |
 | CLIENT-01 | Phase 3 | Pending |
 | CLIENT-02 | Phase 3 | Pending |
 | CLIENT-03 | Phase 3 | Pending |
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -48,9 +48,12 @@ Plans:
  2. Visitor sees a testimonials section with client reviews on the homepage
  3. Visitor sees a "listings coming soon" placeholder section (full WFRMLS listings deferred to v2)
  4. Visitor can submit a contact form with name, email, phone, and message — and the submission is received
-**Plans**: TBD
+**Plans**: 3 plans

-Plans: none yet
+Plans:
+- [ ] 02-01-PLAN.md — Static page shell: sticky nav, split-panel hero, testimonials carousel, listings placeholder, footer
+- [ ] 02-02-PLAN.md — Contact form: Nodemailer SMTP mailer, server action with Zod + honeypot, ContactSection client component
+- [ ] 02-03-PLAN.md — Human verification checkpoint: full homepage review across all four MKTG requirements

 ### Phase 3: Agent Portal Shell
 **Goal**: Agent can manage clients and see all documents with their current status at a glance
@@ -128,7 +131,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
 | 1. Foundation | 1/3 | Complete    | 2026-03-19 |
-| 2. Marketing Site | 0/? | Not started | - |
+| 2. Marketing Site | 2/3 | In Progress|  |
 | 3. Agent Portal Shell | 0/? | Not started | - |
 | 4. PDF Ingest | 0/? | Not started | - |
 | 5. PDF Fill and Field Mapping | 0/? | Not started | - |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,12 +3,12 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: unknown
-last_updated: "2026-03-19T20:34:50.849Z"
+last_updated: "2026-03-19T21:03:39.146Z"
 progress:
-  total_phases: 1
+  total_phases: 2
  completed_phases: 1
-  total_plans: 3
-  completed_plans: 3
+  total_plans: 6
+  completed_plans: 5
 ---

 # Project State
@@ -18,16 +18,16 @@ progress:
 See: .planning/PROJECT.md (updated 2026-03-19)

 **Core value:** Teressa can prepare and send any real estate form to a client for signing in minutes, from her browser, without leaving her site.
-**Current focus:** Phase 1 - Foundation
+**Current focus:** Phase 2 - Marketing Site

 ## Current Position

-Phase: 1 of 7 (Foundation)
-Plan: 2 of 3 in current phase
+Phase: 2 of 7 (Marketing Site)
+Plan: 2 of 3 in current phase (02-01 and 02-02 complete)
 Status: In progress
-Last activity: 2026-03-19 — Plan 01-02 complete: Branded login page, agent dashboard stub, logout mechanism
+Last activity: 2026-03-19 — Plan 02-01 complete: Marketing site shell — sticky nav, hero, testimonials carousel, listings placeholder, footer

-Progress: [██░░░░░░░░] 8%
+Progress: [███░░░░░░░] 24%

 ## Performance Metrics

@@ -41,12 +41,14 @@ Progress: [██░░░░░░░░] 8%
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
 | 01-foundation | 2/3 | 8 min | 4 min |
+| 02-marketing-site | 2/3 | 8 min | 4 min |

 **Recent Trend:**
- Last 5 plans: 01-01 (6 min), 01-02 (2 min)
- Trend: faster
+- Last 5 plans: 01-01 (6 min), 01-02 (2 min), 02-01 (4 min), 02-02 (4 min)
+- Trend: stable

 *Updated after each plan completion*
+| Phase 02-marketing-site P01 | 5 | 2 tasks | 8 files |

 ## Accumulated Context

@@ -65,6 +67,11 @@ Recent decisions affecting current work:
 - [Phase 01-foundation 01-02]: PasswordField extracted as co-located client sub-component — keeps login page.tsx as pure server component
 - [Phase 01-foundation 01-02]: loginAction re-throws non-AuthError (NEXT_REDIRECT must bubble) — critical Auth.js v5 server action pattern
 - [Phase 01-foundation 01-02]: Brand colors applied via inline style props — Tailwind JIT may miss one-off hex values
+- [Phase 02-marketing-site]: CSS hover classes in server components — onMouseEnter/onMouseLeave not valid in server component props; use className with style blocks instead
+- [Phase 02-marketing-site]: lucide-react installed for marketing site icons (Home, Menu, X, ChevronLeft, ChevronRight)
+- [Phase 02-marketing-site 02-02]: nodemailer pinned to ^7.0.7 — v8 conflicts with next-auth@5.0.0-beta.30 peerOptional dep
+- [Phase 02-marketing-site 02-02]: useActionState imported from 'react' not 'react-dom' — React 19 canonical API (useFormState removed in React 19)
+- [Phase 02-marketing-site 02-02]: Honeypot silent success pattern — bots receive status:success without email sent, preventing bot discovery of rejection

 ### Pending Todos

@@ -81,5 +88,5 @@ None yet.
 ## Session Continuity

 Last session: 2026-03-19
-Stopped at: Completed 01-02-PLAN.md — Branded login UI, agent portal layout, dashboard stub, logout mechanism
+Stopped at: Completed 02-01-PLAN.md — Marketing site shell: sticky nav, hero section with next/image, testimonials carousel, listings placeholder, site footer
 Resume file: None
--- a/.planning/phases/02-marketing-site/02-01-SUMMARY.md
+++ b/.planning/phases/02-marketing-site/02-01-SUMMARY.md
@@ -0,0 +1,145 @@
+---
+phase: 02-marketing-site
+plan: 01
+subsystem: ui
+tags: [react, nextjs, lucide-react, testimonials, carousel, sticky-nav, hero]
+
+# Dependency graph
+requires:
+  - phase: 01-foundation
+    provides: Next.js app router setup, globals.css, layout.tsx, page.tsx scaffold
+provides:
+  - Sticky navy nav with desktop links and mobile hamburger
+  - Split-panel hero section with next/image and brand CTA
+  - Auto-rotating testimonials carousel with arrow/dot controls
+  - Listings Coming Soon placeholder section with brand colors
+  - Site footer with license number and copyright
+  - Public homepage composed from all marketing section components
+affects:
+  - 02-contact-form
+  - 02-listings
+  - future-brand-refinement
+
+# Tech tracking
+tech-stack:
+  added: [lucide-react]
+  patterns:
+    - CSS hover classes in server components (no event handlers — required for server component compatibility)
+    - _components directory convention for route-co-located components
+    - inline <style> blocks in server components for scoped responsive CSS
+
+key-files:
+  created:
+    - teressa-copeland-homes/src/app/_components/SiteNav.tsx
+    - teressa-copeland-homes/src/app/_components/HeroSection.tsx
+    - teressa-copeland-homes/src/app/_components/TestimonialsSection.tsx
+    - teressa-copeland-homes/src/app/_components/ListingsPlaceholder.tsx
+    - teressa-copeland-homes/src/app/_components/SiteFooter.tsx
+  modified:
+    - teressa-copeland-homes/src/app/page.tsx
+    - teressa-copeland-homes/src/app/globals.css
+    - teressa-copeland-homes/package.json
+
+key-decisions:
+  - "CSS hover classes in server components — onMouseEnter/onMouseLeave not valid in server component props; using className + <style> block instead"
+  - "lucide-react installed for icons (Home, Menu, X, ChevronLeft, ChevronRight)"
+  - "TestimonialsSection as 'use client' — requires useState/useEffect/useRef; all other components stay as server components"
+  - "clearInterval returned from useEffect cleanup — prevents memory leak on pause state change"
+  - "ContactSection (from prior commit 39f233d) included in page.tsx section order — already existed with contact-action.ts server action"
+
+patterns-established:
+  - "Server components use CSS classes + inline <style> for hover effects rather than JS event handlers"
+  - "Placeholder copy always wrapped in clearly labelled // PLACEHOLDER comments"
+  - "All brand colors applied via inline style or <style> blocks: navy #1B2B4B, gold #C9A84C, cream #FAF9F7"
+
+requirements-completed: [MKTG-01, MKTG-02, MKTG-04]
+
+# Metrics
+duration: 5min
+completed: 2026-03-19
+---
+
+# Phase 02 Plan 01: Marketing Site Shell Summary
+
+**Sticky nav, split-panel hero with next/image, auto-rotating testimonials carousel, and brand-styled listings placeholder built as Next.js server/client components with lucide-react icons**
+
+## Performance
+
+- **Duration:** ~5 min
+- **Started:** 2026-03-19T20:57:58Z
+- **Completed:** 2026-03-19T21:02:31Z
+- **Tasks:** 2
+- **Files modified:** 8
+
+## Accomplishments
+- SiteNav with sticky positioning, responsive hamburger, and anchor links to all page sections
+- HeroSection split-panel with next/image fill, brand copy, and gold CTA button
+- TestimonialsSection client component — 5 placeholder reviews, 5s auto-rotate, hover-pause, arrow controls, dot indicators, clearInterval cleanup
+- ListingsPlaceholder section with Home icon, navy background, and gold bordered CTA
+- SiteFooter with license number, TODO verify comment, copyright year, and nav links
+- page.tsx composed in correct order: SiteNav → HeroSection → TestimonialsSection → ListingsPlaceholder → ContactSection → SiteFooter
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Scaffold nav, hero, listings, footer** - `c26a0b1` (feat)
+2. **Task 2: Testimonials carousel** - `6d701b7` (feat)
+3. **Fix: Restore TestimonialsSection in page.tsx order** - `a33b4c9` (fix)
+
+## Files Created/Modified
+- `src/app/_components/SiteNav.tsx` - Sticky navy nav, desktop links, mobile hamburger with Menu/X toggle
+- `src/app/_components/HeroSection.tsx` - Split-panel hero, next/image fill, PLACEHOLDER-commented copy
+- `src/app/_components/TestimonialsSection.tsx` - Client carousel, useState/useEffect, clearInterval cleanup, arrow+dot controls
+- `src/app/_components/ListingsPlaceholder.tsx` - Navy section, Home icon, listings CTA
+- `src/app/_components/SiteFooter.tsx` - License with TODO verify comment, copyright, nav links
+- `src/app/page.tsx` - Composing all section components in order
+- `src/app/globals.css` - scroll-behavior: smooth, scroll-margin-top: 72px
+- `package.json` - Added lucide-react dependency
+
+## Decisions Made
+- CSS hover classes used in server components instead of onMouseEnter/onMouseLeave event handlers — event handlers cannot be passed to Client Component props in Next.js 16 server components
+- TestimonialsSection is 'use client' because carousel requires useState, useEffect, and useRef
+- clearInterval called in useEffect cleanup function to prevent memory leak when paused state changes
+- ContactSection (created in prior commit 39f233d from an out-of-plan automated action) was wired into page.tsx since it already existed with its contact-action.ts server action dependency
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Removed event handler props from server components**
+- **Found during:** Task 1 (Build verification)
+- **Issue:** `onMouseEnter` / `onMouseLeave` on HeroSection and ListingsPlaceholder caused Next.js prerender error: "Event handlers cannot be passed to Client Component props"
+- **Fix:** Replaced inline event handler props with CSS class hover rules in inline `<style>` blocks
+- **Files modified:** `src/app/_components/HeroSection.tsx`, `src/app/_components/ListingsPlaceholder.tsx`
+- **Verification:** `npm run build` exits 0 with no TypeScript errors after fix
+- **Committed in:** `c26a0b1` (Task 1 commit)
+
+**2. [Rule 1 - Bug] Restored TestimonialsSection in page.tsx after linter rewrite**
+- **Found during:** Task 2 completion check
+- **Issue:** An automated linter/tool rewrote page.tsx to import ContactSection, omitting TestimonialsSection and removing the section id="contact" stub
+- **Fix:** Rewrote page.tsx with both TestimonialsSection and ContactSection imports in correct order
+- **Files modified:** `src/app/page.tsx`
+- **Verification:** `npm run build` exits 0; all sections present in correct order
+- **Committed in:** `a33b4c9` (fix commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (2x Rule 1 - Bug)
+**Impact on plan:** Both fixes required for correctness — no scope creep.
+
+## Issues Encountered
+- Linter/tool repeatedly rewrote page.tsx mid-execution to include a ContactSection import. The ContactSection component had been created in an earlier out-of-plan commit (39f233d), so the build still passed but TestimonialsSection was lost from the section order. Required an extra fix commit to restore correct ordering.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Public homepage shell is complete and passes build
+- All placeholder copy clearly labelled with PLACEHOLDER comments for future content replacement
+- License number has TODO verify comment for Teressa to confirm before launch
+- Ready for Phase 02-02 contact form integration and Phase 02-03 listings section
+
+---
+*Phase: 02-marketing-site*
+*Completed: 2026-03-19*