Phase 3: Product specs for Milestones 1-4
This commit is contained in:
@@ -0,0 +1,166 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user