intotheeast-com-content/docs/milestone-1-spec.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