m038andClaude Opus 5
8202d2a257
Five weeks of undocumented evolution left the docs describing a site that
partly no longer exists, with nothing marking which documents were historical.
The code is treated as the source of truth throughout; every claim below was
verified against code, config or the Makefile rather than inferred.
Two mechanisms, following patterns the repo already used:
- docs/reference/superseded-decisions.md (new) — one authoritative table of all
14 reversals: what was planned, where, what is true now, when, and why. Plus
a short list of decisions that were NOT reversed, since their planning docs
are old enough to look suspect.
- Inline "> **Superseded ...**" notes at each stale claim, so a claim can never
be read un-corrected. This mirrors the existing "> History:" notes in
architecture.md and "> **Changed 2026-07:**" in trip-switching.md.
Scope split by tense: present-tense docs (CLAUDE.md, reference/, guides/,
README.md, CONCEPTS.md) are corrected; past-tense records (plans/, specs/,
milestones/, summary.md, pm-analysis.md) are annotated only, never rewritten —
their staleness is what makes them records.
Present-tense corrections:
- CLAUDE.md asserted css-compiled/ is generated from css/style.css and
css/tokens.css. That source relationship does not exist: css/ is hand-authored
and served directly via assets.addCss in partials/base.html.twig, while
css-compiled/ is esbuild output from the CSS imports inside js/src/*.js.
Highest-severity finding — an always-loaded file inviting a hand-edit of a
generated bundle.
- README.md documented every remote-* target without the -test/-prod suffix
guard-env requires, so its entire server runbook was unrunnable, and listed
7 of ~20 targets while CLAUDE.md designates it authoritative for the full
list. Rewritten with all targets, grouped, and the suffix rule stated.
- README.md told readers to "git clone" into user/, which is a submodule.
- architecture.md: nav is Home + Trips + (authenticated) New Post, not
"Home + Past Trips only"; template tree omitted trips.html.twig,
post-form.html.twig and forms/, and placed base.html.twig at templates/ root
rather than in partials/; entry-actions has three API routes, not just delete;
added the undocumented css-compiled/maplibre-gl.css output and a section on
the /post pin editor as the one sanctioned non-entry-map map.
- design-system.md: documented 13 colour tokens against 19 in tokens.css
(missing --color-error, --color-draft-accent and four glass overlays); claimed
"all 3 map templates"; and described --color-canvas as "white".
- design-system-light.md documented a light palette in present tense. No light
mode exists — tokens.css has a single :root block, no prefers-color-scheme or
data-theme switch, and no light hex appears in css/. Banner added.
- posting.md said photos were optional; they are required, 1-6. It documented
hero_image, which was removed for entries (stories keep it). It had no mention
of the frontend edit flow or photo editor, both shipped 2026-07-08. Photo
files are photo-01..NN, zero-padded.
- working/README.md advertised summary.md as the project's "current state" while
summary.md describes Leaflet, /tracker, /map and /stats. Most misleading line
in the tree.
- CLAUDE.md: recorded js/src/location-map.js as the one sanctioned exception to
the single-map-path rule, and documented that make start/setup fail on a clean
checkout because docker-compose.yml still builds a travel-memories service
whose source moved out in a80b0a9.
Also: 2026-07-23-post-form-location-override.md read "Not started" while merged
in user/ as dd19995; status corrected.
Findings that are not documentation problems — the compose breakage, a
repeatable drift check, the unused shortcode-gallery-plusplus, and demo fixtures
for retired views — are collected in
docs/working/2026-07-25-doc-drift-recommendations.md and deliberately not acted
on. Design and verification method: docs/working/specs/2026-07-25-docs-reconciliation-design.md
The submodule gitlink is deliberately not bumped.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
182 lines
6.5 KiB
Markdown
182 lines
6.5 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.
|
|
|
|
> **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.
|