# Milestone 2 Spec — Interactive Map

**Goal:** A `/map` page shows all entries as markers on an interactive Leaflet.js map, connected by a chronological route line, with popups linking to entries.

> **Superseded — written 2026-06-21. Neither the `/map` page nor Leaflet exists.**
>
> - **No `/map` route.** The map renders inline on the trip page via the single shared partial
>   `templates/partials/entry-map.html.twig` (R1, retired 2026-07-04). `CLAUDE.md` forbids
>   re-creating it or linking to it.
> - **Leaflet + OpenStreetMap tiles → MapLibre GL JS** with a CartoDB dark-matter basemap (R4,
>   2026-06-20).
> - **§2.6 nav link** is gone with the page (R6).
>
> The *substance* of this spec survived — markers per entry, chronological route line, popups linking
> to entries, bounds fitting, mobile touch handling — it all lives in `MapUtils.initEntryMap()` in
> `user/themes/intotheeast/js/maplibre-utils.js`. Only the page and the library changed.
>
> Details: [`../../reference/superseded-decisions.md`](../../reference/superseded-decisions.md).

---

## User Stories

- As a reader, I want to see a world map showing where Mischa has been so I can understand the journey at a glance without reading every entry.
- As a reader, I want to click a map marker and see the entry date, title, and a thumbnail — and be able to click through to the full entry.
- As a reader on mobile, I want to pan and pinch-zoom the map with my fingers without the page scrolling underneath.
- As a traveler (Mischa), I want the map to automatically include every entry that has lat/lng data — I should not need to do any manual map maintenance.
- As a reader, I want the map to show the route line connecting stops in the order they were visited, so the journey makes narrative sense.

---

## Feature Details

### 2.1 — Map Page

**Route:** `/map`

**Template:** `map.html.twig` — extends `partials/base.html.twig`

**Page file:** `user/pages/03.map/map.md`

**Content:**
- Full-viewport-height map container below the site header
- Leaflet.js loaded from CDN (jsDelivr): `https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.min.js`
- Leaflet CSS from same CDN
- Tile layer: OpenStreetMap (free, no API key): `https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png`
- Attribution: "© OpenStreetMap contributors"

**Map initialization:**
- Default zoom: auto-fit to bounds of all markers (use `map.fitBounds()`)
- If no entries with GPS data: show world view, zoom 2, centered at 0,0 with a message "No locations yet"
- Min zoom: 2, Max zoom: 18

---

### 2.2 — Entry Data Serialization

**How entries reach the map JS:**

In `map.html.twig`, Grav's Twig will iterate all published entries under `/tracker` and serialize them to a JSON array embedded in a `<script>` tag:

```js
var ENTRIES = [
  {
    "lat": 48.8566,
    "lng": 2.3522,
    "title": "Paris morning",
    "date": "2026-06-18",
    "url": "/tracker/2026-06-18",
    "hero": "/path/to/thumb.jpg"  // null if no photo
  },
  ...
];
```

**Only entries with valid lat AND lng are included** (skip entries where either is empty/null).

Entries sorted ascending by date (oldest first) so the route line is drawn in travel order.

---

### 2.3 — Route Polyline

**What:** A colored line drawn between entry markers in chronological order.

**Style:**
- Color: `#0066cc` (brand blue, matches existing CSS)
- Weight: 3px
- Opacity: 0.7
- No arrow heads for v1

**Behavior:**
- Line drawn between consecutive entries (by date) that have valid GPS
- If only 1 entry: no line (just a single marker)
- If two consecutive entries are very far apart (>5000km): line still drawn — it's a flight, expected

---

### 2.4 — Entry Markers

**What:** One circular marker per entry with GPS coordinates.

**Marker design:**
- Custom circular marker (not default Leaflet teardrop)
- Color: `#0066cc` fill, white border, 2px border
- Size: 12px diameter on mobile, 14px on desktop
- Most recent entry: larger (18px) and brighter color to indicate "current location"

**Popup on click/tap:**
```
[thumbnail if available — 120px wide, 80px tall, cover cropped]
📅 18 June 2026
Paris morning
[Read entry →]
```
- Popup width: 180px max
- "Read entry →" links to the entry page
- Tapping outside popup closes it

**Edge cases:**
- Two entries at the same lat/lng: Leaflet clusters or offsets them slightly (use small offset to prevent exact overlap — just add 0.0001° offset per duplicate)
- Entry with GPS but no photo: popup shows no image, just date + title + link

---

### 2.5 — Mobile Map UX

**Problem:** On mobile, a map inside a scrollable page creates a scroll-trap (finger intended for page scroll gets captured by map pan).

**Solution:**
- Map container is `height: calc(100vh - 60px)` (full viewport minus header)
- Map is the primary content of the page — no scroll needed
- `touch-action: none` on the map container prevents page scroll interference
- Leaflet handles touch pan/zoom natively

---

### 2.6 — Navigation Link

**What:** "Map" link added to the site header navigation.

**Where:** `partials/base.html.twig` nav section — add `<a href="{{ base_url_absolute }}/map">Map</a>`

---

## Out of Scope (Milestone 2)

- Filtering markers by date range
- Clustering markers at low zoom levels
- Heatmap or density visualization
- Showing the route on the tracker feed page (Milestone 4)
- Showing elevation profile
- Country highlight/fill on the map
- Offline map tiles

---

## Acceptance Criteria

1. `/map` page exists and returns HTTP 200
2. Page renders a full-height interactive map
3. All published entries with valid lat/lng appear as markers
4. Markers are connected by a route line in date order
5. Clicking/tapping a marker shows a popup with date, title, and link
6. Popup link navigates to the correct entry page
7. Most recent entry marker is visually distinct (larger/brighter)
8. If no entries have GPS: map renders at world zoom with "No locations yet" message
9. Map is pannable and zoomable by touch on mobile
10. "Map" link appears in site navigation and routes to `/map`
11. Map auto-fits to show all markers on page load
12. Entries without lat/lng are silently excluded (no JS errors)

---

## Design Notes

- Map tile layer: OpenStreetMap default tiles. Clean, recognizable, free.
- Keep the Grav site header visible above the map — don't go full-screen (users need the nav)
- Popup design: minimal. White background, slight box-shadow, 8px border-radius
- Do not use any Leaflet plugins beyond the core library — keep the dependency footprint tiny
- The map page should load fast: Leaflet is ~42KB gzipped. Tile images load progressively. No blocking.