167 lines
5.7 KiB
Markdown
167 lines
5.7 KiB
Markdown
# 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:
|
|
|
|
```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.
|