intotheeast-com/docs/working/milestones/milestone-1.md

# Milestone 1 Spec — Entry Enrichment

**Goal:** Every entry is richer out of the box — location name shown, weather auto-captured, photos in a proper gallery, hero image visible on the feed.

---

## User Stories

- As a traveler (Mischa), when I submit the post form, I want my current weather conditions auto-filled so I don't have to look them up manually.
- As a traveler, I want to type my city and country once and have it appear on the entry and in the feed card, so readers know where I am without reading the whole post.
- As a reader, when I scan the feed, I want to see a thumbnail photo and location for each entry so I can quickly get a sense of where Mischa is and whether to read the full entry.
- As a reader, when I open an entry, I want to see all uploaded photos in a gallery I can browse, not a wall of raw images.
- As a traveler, when I submit a form without photos, the entry should still display cleanly with no broken image placeholders.

---

## Feature Details

### 1.1 — Location Name Field on Post Form

**What:** Add two text fields to the post form: `location_city` and `location_country`.

**Behavior:**
- Both are optional (GPS coordinates are also optional)
- Placeholder text: "e.g. Kyoto" and "e.g. Japan"
- Displayed below the lat/lng fields
- On submit, stored in entry frontmatter as `location_city` and `location_country`
- On the form, shown as a single labeled group "Location Name" with two side-by-side inputs on desktop, stacked on mobile

**Edge cases:**
- If left blank: entry shows no location badge. No error, no broken UI.
- Long city names (e.g. "Ulaanbaatar") must not overflow card layout.
- Special characters (accents, non-Latin) must render correctly.

**Mobile behavior:** Both fields full-width, stacked, 44px min touch targets.

---

### 1.2 — Weather Auto-Fetch on Post Form

**What:** A "Get Weather" button on the post form that calls the Open-Meteo free API (no API key) using the lat/lng already entered, and fills hidden weather fields.

**Fields to fetch and store:**
- `weather_temp_c` — temperature in Celsius (integer)
- `weather_desc` — short description: one of: Sunny, Partly cloudy, Cloudy, Foggy, Drizzle, Rain, Snow, Thunderstorm (derived from WMO weather code)

**WMO code mapping (Open-Meteo uses WMO codes):**
- 0 → Sunny
- 1,2 → Partly cloudy
- 3 → Cloudy
- 45,48 → Foggy
- 51,53,55,56,57 → Drizzle
- 61,63,65,66,67,80,81,82 → Rain
- 71,73,75,77,85,86 → Snow
- 95,96,99 → Thunderstorm

**API call:**
```
https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lng}&current=temperature_2m,weather_code&temperature_unit=celsius
```

**UX flow:**
1. User fills in lat/lng (manually or via "Get Location" button)
2. User taps "Get Weather" button
3. Button shows "Fetching…" while loading
4. On success: fills temp and desc fields (visible, editable text inputs)
5. On failure (no network, no lat/lng): shows inline error "Could not fetch weather — enter manually"

**Edge cases:**
- If lat/lng not filled when button tapped: show inline error "Enter coordinates first"
- Weather fields are always editable manually (auto-fill is a convenience, not mandatory)
- If weather fields left blank: entry shows no weather badge. No broken UI.
- Open-Meteo returns current conditions, not historical — this is fine for posting in real time

**Mobile behavior:** "Get Weather" button is full-width, 44px height, placed immediately below the lat/lng + location name fields.

---

### 1.3 — Weather Display on Entry Page

**What:** If `weather_temp_c` or `weather_desc` is present in frontmatter, display a weather badge on the entry page.

**Display format:** `☀️ Sunny · 28°C` (icon + description + temperature)
- Icon chosen from a small set based on `weather_desc`:
  - Sunny → ☀️
  - Partly cloudy → ⛅
  - Cloudy → ☁️
  - Foggy → 🌫️
  - Drizzle → 🌦️
  - Rain → 🌧️
  - Snow → ❄️
  - Thunderstorm → ⛈️

**Placement:** In the entry header, between the date and the body text. Same line as GPS coordinates if those are shown.

**Edge cases:**
- Only temp, no desc → show temp only
- Only desc, no temp → show desc only
- Neither → hide weather section entirely
- Temperature should always be integer (round if float)

---

### 1.4 — Location Badge on Feed Cards and Entry Page

**What:** Display `location_city, location_country` as a small badge on tracker feed cards and at the top of entry pages.

**Feed card:** Below the date, above the excerpt. Format: `📍 Kyoto, Japan`

**Entry page:** In the header below the date, above the content. Format: `📍 Kyoto, Japan`

**Edge cases:**
- Only city, no country → `📍 Kyoto`
- Only country, no city → `📍 Japan`
- Neither → location badge hidden entirely
- Long location names: truncate with ellipsis at 30 chars on cards (full text on entry page)

---

### 1.5 — Photo Gallery on Entry Page

**What:** Photos uploaded to an entry should display in a responsive grid gallery with lightbox (click to enlarge).

**Implementation approach:** Use Grav's native media collection for the entry page. Each `.entry` folder contains its photos. Render them in a grid in `entry.html.twig`. Use a minimal vanilla JS lightbox — no external framework.

**Gallery behavior:**
- Photos displayed in a 2-column grid on mobile, 3-column on desktop
- Each thumbnail is square-cropped, 150px on mobile
- Clicking/tapping a thumbnail opens a lightbox overlay
- Lightbox: dark overlay, full-size image centered, tap/click outside or press Escape to close
- Left/right navigation arrows in lightbox (swipe on mobile)
- No captions needed for v1

**Edge cases:**
- 0 photos: gallery section hidden entirely
- 1 photo: still uses grid (single item), lightbox works
- Many photos (>10): gallery still renders (no hard limit on display)
- Non-image files in the media folder: skip them (only render jpg, jpeg, png, webp, gif)

---

### 1.6 — Hero Image on Tracker Feed Cards

**What:** If an entry has photos, the first photo (or the one named in `hero_image` frontmatter) appears as a thumbnail on the tracker feed card.

**Implementation:** In `tracker.html.twig`, for each entry:
1. If `entry.header.hero_image` is set, use `entry.media[entry.header.hero_image]`
2. Else, use the first image in `entry.media` sorted by name
3. Render as a 16:9 aspect-ratio thumbnail, full width of card, above the title

**Edge cases:**
- No photos: card shows no image, just text. No broken `<img>` tag.
- `hero_image` set but file missing: fall back to first media file, or no image
- Very tall/wide images: CSS `object-fit: cover` maintains card aspect ratio

---

## Out of Scope (Milestone 1)

- Map features (Milestone 2)
- Statistics page (Milestone 3)
- Video support
- Comments or reactions
- Automated reverse geocoding (city name comes from form input, not auto-detected)
- Altitude display (data may not be present)
- Historical weather (Open-Meteo current endpoint only)

---

## Acceptance Criteria

1. Post form has `location_city` and `location_country` fields that save to entry frontmatter
2. Post form has "Get Weather" button that fills `weather_temp_c` and `weather_desc` via Open-Meteo when lat/lng are provided
3. Entry page shows weather badge when weather fields are present; hidden when absent
4. Entry page shows location badge `📍 City, Country` when location fields are present; hidden when absent
5. Tracker feed card shows location badge when present
6. Tracker feed card shows a hero image when photos exist for an entry
7. Entry page shows a 2-col (mobile) / 3-col (desktop) photo grid
8. Clicking any photo opens a full-screen lightbox with prev/next navigation
9. Pressing Escape or clicking outside lightbox closes it
10. All fields are optional — empty values produce no broken UI elements
11. All interactive elements meet 44px minimum touch target on mobile
12. Form submits correctly with all new fields populated or all blank

---

## Design Notes

- Weather and location badges should be subtle — small text, muted color, not the visual focus
- Use emoji icons for weather — universal, no icon font dependency
- Gallery grid: `gap: 4px` between thumbs, no borders, square crops
- Lightbox: `background: rgba(0,0,0,0.92)`, image centered with `max-height: 90vh`
- Feed card image: `aspect-ratio: 16/9`, `object-fit: cover`, rounded top corners matching card