intotheeast-com-content/docs/milestone-2-spec.md

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.

---

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:

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.