Sportstime/docs/plans/2026-01-12-progress-tracking-enhancements-design.md

Progress Tracking Enhancements Design

Date: 2026-01-12 Status: Draft Scope: High-level overview for scoping/prioritization

Goal

Enhance the stadium bucket list experience with richer visit tracking, a dedicated games history view, and an interactive map.

Features

1. Multiple visits per stadium - Track and display each visit separately
2. View all games attended - New screen with chronological list, filterable by year/sport
3. Zoomable map - Enable pinch-to-zoom and pan on the progress map

Current State

• StadiumVisit model already supports multiple visits per stadium (data is there)
• UI shows most recent visit, doesn't surface visit history well
• ProgressMapView has interactions disabled (interactionModes: [])
• No dedicated "all games attended" view exists

Feature Details

1. Multiple Visits Per Stadium

The StadiumVisit model already stores multiple visits. UI changes needed:

Component	Change
VisitDetailView	Show list of all visits for that stadium, not just most recent
StadiumVisitSheet	"Add Another Visit" button when stadium already has visits
Stadium cards	Show visit count badge ("3 visits")

UI Flow:

• Tapping a visited stadium shows a list of visit cards
• Each visit card is expandable to show game details, photos, notes
• "Add Visit" button at bottom of visit list

2. View All Games Attended (GamesHistoryView)

New screen accessible from Progress tab:

Header: "X Games Attended" with sport filter chips

Layout:

• Grouped by year (2026, 2025, 2024...) with sticky section headers
• Each row: Date, teams (vs format), stadium, score, sport icon
• Tapping a row opens the visit detail

Filters:

• Sport: Multi-select chips at top (MLB, NBA, NHL, NFL)
• Year: Scroll-based (no separate picker needed)

Empty State: "No games recorded yet. Add your first visit!"

Access Points:

• Button in Progress tab header
• "See All" link in recent visits section

3. Zoomable Map

Current	New
interactionModes: []	interactionModes: [.zoom, .pan]
Fixed US region	Remembers last position
Tap shows name label only	Tap zooms to stadium + shows detail card

Additional UI:

• "Reset View" floating button (bottom-right corner)
• Appears after user pans or zooms away from default view
• Tapping resets to full continental US view

Zoom-to-Stadium Behavior:

• Tapping a pin animates map to that stadium
• Uses ~0.01 lat/lon span (city level zoom)
• Shows stadium detail card below map

File Structure

Features/Progress/Views/
├── ProgressMapView.swift         # MODIFY - enable interactions, add reset button
├── VisitDetailView.swift         # MODIFY - show all visits as list
├── StadiumVisitSheet.swift       # MODIFY - "Add Another Visit" flow
├── GamesHistoryView.swift        # NEW - all games attended screen
├── GamesHistoryRow.swift         # NEW - single game row component
└── VisitListCard.swift           # NEW - compact visit card for lists

Key Decisions

Decision	Choice	Rationale
Games history access	Header button + "See All" link	Multiple entry points for discoverability
Year grouping	Sticky section headers	Standard iOS pattern, easy to scan
Map zoom on tap	Animate to 0.01 span	City-level detail without losing context
Reset button visibility	Show only after pan/zoom	Don't clutter UI when at default view
Visit count badge	Orange circle with number	Consistent with app theme
Default sort	Most recent first	Users care about recent visits

Data Changes

No model changes needed:

• StadiumVisit already supports multiple visits per stadium
• ProgressViewModel already has visits array

Add computed property to ProgressViewModel:

var allVisitsByYear: [Int: [VisitSummary]] {
    Dictionary(grouping: allVisits) { Calendar.current.component(.year, from: $0.visitDate) }
}

Not Included (YAGNI)

• Export games history to CSV
• Share individual visit cards to social media
• Map clustering for dense stadium areas (revisit if performance issues)
• Search within games history (filter chips should suffice)

Dependencies

• None - uses existing models and data providers

Testing Considerations

• Test multiple visits for same stadium (add, view, edit)
• Test games history with various filter combinations
• Test map zoom/pan performance with all stadiums loaded
• Test reset button appears/disappears correctly
• Test empty states for new users