# 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`:
```swift
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