docs: fix all internal cross-references after restructure

2026-06-21 12:48:04 +02:00
parent 93aa6d9b42
commit 65597de00d
29 changed files with 4738 additions and 85 deletions
@@ -0,0 +1,551 @@
+# Design Spec: Story Mode + MapLibre Migration
+
+*Date: 2026-06-19*
+*Inspired by: [Sabdia](https://github.com/m-cluitmans/Sabdia) — a friend's sabbatical blog built on Astro + Keystatic + MapLibre*
+
+---
+
+## Scope
+
+Two parallel features:
+
+1. **Story Mode** — a rich long-form post type alongside journal dailies, with cinematic
+   storytelling blocks (hero, chapter breaks, scrollytelling, pull quotes, snap gallery)
+2. **MapLibre GL migration** — replace Leaflet across all three maps (full map, mini-map,
+   home map) with MapLibre GL JS; add animated journey line; improve CSS integration
+
+---
+
+## Decisions Log
+
+### Why MapLibre GL instead of Leaflet
+
+Leaflet renders raster PNG tiles. MapLibre GL renders vector tiles in WebGL. Key gains:
+
+- **Animated journey line** — MapLibre's GeoJSON source model makes RAF-loop animation
+  trivial (`source.setData()` per frame). On Leaflet you'd call `polyline.setLatLngs()`
+  which also works, but MapLibre gives us everything below for free too.
+- **Smooth zoom** — continuous sub-pixel zoom vs Leaflet's tile-snap zoom levels
+- **Retina crisp** — vector geometry scales perfectly on HiDPI screens
+- **Future-proof** — 3D terrain, tilt/pitch, per-feature click events, style control,
+  outdoor/topo/satellite styles for GPX track maps all become straightforward
+- **GPX styling** — switching from `leaflet-gpx` to `@mapbox/togeojson` + GeoJSON layer
+  gives per-point colour control (speed, elevation gradients) later
+
+Cost: ~280KB (vs ~40KB Leaflet). Acceptable — cached after first visit.
+
+Tile source stays the same: CARTO dark vector style — free, no API key.
+
+### Why shortcodes for story blocks (not modular pages or blueprint lists)
+
+Evaluated three approaches for in-prose storytelling blocks:
+
+| Approach | What it is | Verdict |
+|---|---|---|
+| **Shortcodes** | `[chapter-break ...]` inline in Markdown | ✅ Chosen |
+| Modular pages | Each block = a child page in Admin | ✗ Ruled out |
+| Blueprint list + elements | `sections:` YAML list with type selector | ✗ Ruled out |
+
+**Modular pages** are how most Grav storytelling themes work (Quark, Oxygen, all
+HTML5UP ports). Each block gets proper Admin form fields. But a 1,500-word story with
+two chapter breaks requires five child pages — navigating between them on mobile while
+traveling is painful. Prose ends up fragmented across "text" module pages.
+
+**Blueprint list with elements field** (Grav's conditional field groups) could render
+blocks as a structured "Add section" list in Admin. But prose still has to go in a
+"text" type section, so a story becomes a long list of `text/chapter-break/text/scrolly/
+text/gallery` entries rather than a flowing document.
+
+**Shortcodes** keep everything in one Markdown editor — prose flows naturally, blocks are
+inserted inline. The `shortcode-gallery-plusplus` plugin already in our stack brings
+`shortcode-core` as a dependency, so no new plugin is needed.
+
+Grav Admin2 has no rich block-editor like Keystatic/Markdoc. Shortcodes are the
+closest practical equivalent for mixed prose+blocks authoring on mobile.
+
+*Future option:* If Admin2 ever gains inline block components (or we add a Flex Object
+definition), the shortcode content can be migrated — the block semantics are identical.
+
+### Why gallery stays as lightbox on journal entries
+
+Journal entries are short daily posts — a grid of 3–8 photos suits them.
+The snap gallery is a deliberate slow storytelling device (one photo fills the screen,
+reader swipes through). That pacing fits stories, not a daily feed card.
+
+### Weather not added to story frontmatter
+
+Weather is a journal-entry concept (captured at the moment of a daily post via
+Open-Meteo). Stories are retrospective long-form narratives — weather would be referenced
+in prose if relevant, not as a metadata badge.
+
+---
+
+## Part 1 — Story Mode
+
+### 1.1 Page structure
+
+Stories live as child pages under `04.stories/`:
+
+```
+user/pages/01.trips/<trip-slug>/04.stories/
+  stories.md                          ← listing page, template: stories
+  01.<story-slug>/
+    story.md                          ← individual story, template: story
+    hero.jpg
+    photo-a.jpg
+    photo-b.jpg
+```
+
+`stories.md` frontmatter:
+```yaml
+title: Stories
+template: stories
+published: true
+```
+
+### 1.2 Story frontmatter schema
+
+```yaml
+title: Into the Hills of Kyoto
+date: 2026-03-28           # start date — shown in hero header
+end_date: 2026-03-29       # optional; shown as "28–29 Mar 2026"
+location_name: Kyoto        # city/region; shown in hero header
+location_country: Japan     # used for stats de-duplication
+lat: 34.967                 # main GPS coordinate — shows pin on /map
+lng: 135.773
+hero_image: hero.jpg        # filename in page media; required for hero section
+hero_alt: The vermillion gate at Fushimi Inari at dawn
+published: true
+```
+
+Fields deliberately excluded: `weather_*` (not meaningful for stories).
+
+### 1.3 Shortcode blocks
+
+Four blocks implemented as ShortcodeCore shortcodes.
+All image paths are **filenames only** (e.g. `shrine.jpg`) — resolved against the story's
+own page media folder, same convention as `hero_image`.
+
+#### ChapterBreak
+
+Full-bleed atmospheric photo with a frosted-glass title panel. Reveals on scroll via
+IntersectionObserver (blur + translateY → clear).
+
+```
+[chapter-break image="shrine-gate.jpg" title="The Long Walk Up" number="II" /]
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `image` | yes | Page media filename |
+| `title` | yes | Chapter title, displayed in frosted panel |
+| `number` | no | Roman numeral or label shown above title |
+| `alt` | no | Alt text (defaults to `title`) |
+
+Renders as `60vh` full-bleed block with dark gradient tint over the image and a
+`backdrop-filter: blur(18px)` panel containing the chapter number + title + teal rule.
+
+#### ScrollySection
+
+NYT-style sticky image (55% left column) with text panels that scroll past on the right.
+Steps are separated by `---` inside the shortcode body. Powered by **Scrollama** (CDN).
+
+```
+[scrolly-section image="torii-path.jpg" alt="Thousands of torii gates"]
+The path stretched further than I could see.
+
+---
+
+Each gate was donated by a business or family, a prayer made physical.
+
+---
+
+By the tenth minute of walking, the city had disappeared entirely.
+[/scrolly-section]
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `image` | yes | Page media filename — sticky background |
+| `alt` | no | Image alt text |
+| `caption` | no | Small caption shown bottom-left of image |
+
+On mobile: full-screen sticky image with text panels scrolling over it (same layout,
+single column — image behind, text on top with semi-transparent card).
+
+Image starts blurred (`blur(8px) scale(1.04)`), unblurs when section enters viewport.
+Between steps: subtle pan (object-position cycles through 5 offsets) + slight overlay
+darkening for depth.
+
+#### PullQuote
+
+Frosted-glass quote block with optional atmospheric background image. Reveals on scroll.
+
+```
+[pull-quote image="lanterns.jpg"]
+The torii gates never seemed to end — and I didn't want them to.
+[/pull-quote]
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `image` | no | Page media filename — background photo |
+| `alt` | no | Alt text for background image |
+
+Without `image`: renders on `--color-canvas` (warm dark surface, solid).
+With `image`: full-bleed image behind frosted glass panel.
+
+Large decorative `"` marks above and below the quote text (DM Serif Display, 5rem).
+
+#### SnapGallery
+
+Full-screen snap-scroll photo sequence. One photo per swipe. Snap physics are pure CSS
+(`scroll-snap-type: y mandatory` + `scroll-snap-stop: always` on the scroll container).
+Dot indicator active state updated via a small IntersectionObserver on each slide.
+
+```
+[snap-gallery images="photo-a.jpg,photo-b.jpg,photo-c.jpg" captions="The approach,Summit view,Descent" alts="Hikers on trail,Mountain panorama,Forest path" /]
+```
+
+| Attribute | Required | Description |
+|---|---|---|
+| `images` | yes | Comma-separated page media filenames |
+| `captions` | no | Comma-separated captions (positional) |
+| `alts` | no | Comma-separated alt texts (positional) |
+
+Each slide: blurred cover-crop background + contain-fit foreground image + caption fades
+in at bottom. Dot indicator on the right edge. Page-level `scroll-snap-align: start`
+with `proximity` (not mandatory) so normal page scroll is unaffected.
+
+### 1.4 Template: `story.html.twig`
+
+Extends `partials/base.html.twig` but overrides the nav block to show only a floating
+escape link. Full layout:
+
+```
+┌────────────────────────────────────────┐
+│  ← Back  (position: fixed, top-left)   │
+│                                        │
+│  HERO — 100vh                          │
+│    sticky image, Ken Burns zoom-out    │
+│    title blurs up from bottom          │
+│    date · location beneath title       │
+│    ↓ bounce scroll indicator           │
+│    40vh spacer (scroll trigger zone)   │
+│                                        │
+├────────────────────────────────────────┤
+│  STORY BODY                            │
+│    max-width: 680px, centred           │
+│    font: DM Serif Display (headings)   │
+│         DM Sans (prose)                │
+│    {{ page.content|raw }}              │
+│    (Markdown + shortcode blocks)       │
+│                                        │
+│  ← Back to stories  (footer)           │
+└────────────────────────────────────────┘
+```
+
+**Hero scroll behaviour (vanilla JS, no library):**
+
+- `window.scroll` listener (passive, rAF-throttled)
+- `progress = scrollY / innerHeight` (0→1 as hero scrolls away)
+- At progress > 0: dark overlay fades in (`rgba(0,0,0, progress * 0.6)`)
+- Scroll indicator hides after `scrollY > 80px`
+- At progress ≥ 1: overlay removed from DOM
+
+**Ken Burns animation:** CSS `@keyframes` — `scale(1.06) → scale(1)` over 12s,
+`ease-out`, `forwards`. Respects `prefers-reduced-motion: reduce`.
+
+**Text reveal:** Title and date animate in with `filter: blur(10px) + translateY(22px)
+→ clear` at 0.2s / 0.55s delay. Respects `prefers-reduced-motion`.
+
+### 1.5 Template: `stories.html.twig`
+
+Listing of published stories for the active trip. Grid of story cards:
+
+```
+┌──────────────┐  ┌──────────────┐
+│ hero thumb   │  │ hero thumb   │
+│              │  │              │
+│ Kyoto Hills  │  │ Seoul Rain   │
+│ 28–29 Mar    │  │ 1 Apr        │
+│ Kyoto        │  │ Seoul        │
+└──────────────┘  └──────────────┘
+```
+
+2-column grid on desktop, single column on mobile. Each card links to the story.
+Empty state: "No stories yet — check back soon."
+
+Stories are also listed as cards in `dailies.html.twig`'s combined feed (already
+implemented — the template merges journal entries and stories by date).
+
+### 1.6 JS dependencies
+
+| Library | How loaded | Size | Purpose |
+|---|---|---|---|
+| **Scrollama** | CDN (`jsdelivr`) | ~4KB | ScrollySection step detection |
+| IntersectionObserver | Native browser API | — | ChapterBreak + PullQuote reveal, SnapGallery dots |
+
+Scrollama is only loaded on story pages (inline `<script src>` in `story.html.twig`).
+
+### 1.7 CSS additions (story-specific)
+
+New CSS block added to `style.css` under a `/* ── Story pages ──` section:
+
+**Story layout:**
+- `.story-hero` — `position: relative; height: 100vh; overflow: hidden`
+- `.story-hero__img` — `position: sticky; top: 0; width: 100%; height: 100vh; object-fit: cover`
+- `.story-hero__overlay` — `position: fixed; inset: 0; pointer-events: none` (JS-driven opacity)
+- `.story-hero__content` — `position: absolute; bottom: 18%; text-align: center; color: #fff`
+- `.story-escape` — `position: fixed; top: 1rem; left: 1rem; z-index: 100; color: var(--color-ink); background: var(--color-canvas); ...`
+- `.story-body` — `max-width: 680px; margin: 0 auto; padding: var(--space-16) var(--space-6)`
+- `.story-body p` — `font-family: var(--font-ui); font-size: 1.0625rem; line-height: 1.85; color: var(--color-ink-2)`
+
+**ChapterBreak:**
+- `.chapter-break` — full-bleed breakout, `60vh`, overflow hidden
+- `.chapter-break__panel` — `backdrop-filter: blur(18px); background: rgba(26,24,20,0.25); border: 1px solid rgba(255,255,255,0.12); border-radius: var(--radius-sm)`
+- Initial state: `opacity: 0; filter: blur(12px); transform: translateY(28px)` → `.is-revealed` clears all
+- `.chapter-break__rule` — `40px × 2px` teal (`var(--color-accent)`) rule below title
+
+**ScrollySection:**
+- `.scrolly` — `display: grid; grid-template-columns: 55% 45%; width: 100vw` (full-bleed breakout)
+- `.scrolly__media` — `position: sticky; top: var(--site-header-height); height: calc(100vh - var(--site-header-height))`
+- `.scrolly-step__inner` — `background: rgba(26,24,20,0.92); backdrop-filter: blur(4px); border-radius: var(--radius-sm); border: 1px solid var(--color-border)`
+- Mobile (`max-width: 768px`): single column, steps overlay the sticky image with `margin-top: calc(-(100vh - var(--site-header-height)))`
+
+**PullQuote:**
+- `.pull-quote` — bleeds `1.5rem` each side beyond prose column
+- `.pull-quote__inner` — `backdrop-filter: blur(14px); background: rgba(26,24,20,0.12)` (with image) or `var(--color-canvas)` (without)
+- Large `"` marks: `font-family: var(--font-display); font-size: 5rem; color: var(--color-accent); opacity: 0.4`
+
+**SnapGallery:**
+- `.pgallery__frame` — `height: 100vh; scroll-snap-type: y mandatory; overflow-y: scroll`
+- `.pgallery__bg` — `object-fit: cover; filter: blur(20px) brightness(0.4)` (blurred backdrop)
+- `.pgallery__fg` — `object-fit: contain` (full foreground image)
+- `.pgallery__dot.is-active` — `background: var(--color-accent)`
+
+All animations respect `prefers-reduced-motion: reduce` — transitions set to `none`,
+initial states set to final states immediately.
+
+### 1.8 Demo story content
+
+One sample story added to `user/docs/demo/trips/japan-korea-2026/` following existing
+demo conventions. Story covers 28–29 March (Kyoto days already in journal demo):
+
+```
+user/docs/demo/trips/japan-korea-2026/04.stories/01.the-thousand-gates/
+  story.md
+```
+
+Frontmatter mirrors the schema. Body uses all four shortcode types so they can be QA'd
+in one pass. No binary image assets — `make demo-load` copies the folder; tester drops
+a few JPEGs in to exercise hero + photo blocks.
+
+---
+
+## Part 2 — MapLibre GL Migration
+
+### 2.1 Scope
+
+Three files change. No new page routes. GPX file storage and delivery unchanged.
+
+| File | Change |
+|---|---|
+| `map.html.twig` | Full rewrite of JS + CDN refs; CSS class renames |
+| `dailies.html.twig` | Mini-map JS + CDN refs rewritten |
+| `home.html.twig` | Home map JS + CDN refs rewritten |
+| `style.css` | Leaflet overrides removed; MapLibre overrides added |
+
+CDN changes (all three map templates):
+
+```html
+<!-- Remove -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.min.css">
+<script src="https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/leaflet-gpx@2.1.2/gpx.min.js"></script>
+
+<!-- Add -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@4/dist/maplibre-gl.css">
+<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@4/dist/maplibre-gl.js"></script>
+<!-- GPX maps only: -->
+<script src="https://cdn.jsdelivr.net/npm/@mapbox/togeojson@0.16.2/togeojson.min.js"></script>
+```
+
+Tile style URL (same CARTO dark, now as vector style):
+```
+https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json
+```
+
+### 2.2 Animated journey line
+
+Port of Sabdia's `animateJourneyLine` to vanilla JS against MapLibre's GeoJSON source API:
+
+```js
+map.on('load', () => {
+  // Add an empty source
+  map.addSource('journey', {
+    type: 'geojson',
+    data: { type: 'Feature', properties: {}, geometry: { type: 'LineString', coordinates: [] } }
+  });
+
+  // Glow layer (wide, low opacity)
+  map.addLayer({ id: 'journey-glow', type: 'line', source: 'journey',
+    paint: { 'line-color': '#2A8C73', 'line-width': 6, 'line-opacity': 0.18 }
+  });
+
+  // Main line
+  map.addLayer({ id: 'journey-line', type: 'line', source: 'journey',
+    paint: { 'line-color': '#2A8C73', 'line-width': 2.5, 'line-opacity': 0.85 }
+  });
+
+  animateJourneyLine(map, coords); // RAF loop, ease-out cubic, 5000ms
+});
+```
+
+RAF loop builds coordinate array incrementally using cumulative Euclidean distance +
+ease-out cubic easing. On `prefers-reduced-motion: reduce`: skip animation, set full
+coordinates immediately.
+
+Teal values use `var(--color-accent)` equivalent (`#2A8C73`) — matches our design tokens.
+
+### 2.3 GPX rendering
+
+Replace `leaflet-gpx` with `@mapbox/togeojson` + MapLibre GeoJSON source:
+
+```js
+fetch(gpxUrl)
+  .then(r => r.text())
+  .then(text => {
+    const gpx = new DOMParser().parseFromString(text, 'text/xml');
+    const geojson = toGeoJSON.gpx(gpx);
+    map.addSource('gpx-track', { type: 'geojson', data: geojson });
+    map.addLayer({
+      id: 'gpx-track-line', type: 'line', source: 'gpx-track',
+      paint: { 'line-color': '#2A8C73', 'line-width': 2, 'line-opacity': 0.7 }
+    });
+  });
+```
+
+Multiple GPX files (trip has several tracks): each gets its own numbered source/layer pair.
+
+### 2.4 Markers and popups
+
+MapLibre uses `maplibregl.Marker` (custom DOM element) + `maplibregl.Popup`.
+Existing popup HTML content (hero thumbnail, date, title, link) is unchanged.
+
+Marker style (same visual as current):
+- Regular entries: `12px` teal dot with white border
+- Latest/current entry: `18px` teal dot with outer ring (`box-shadow: 0 0 0 4px rgba(42,140,115,0.25)`)
+
+Popup styled via CSS (see §2.5).
+
+### 2.5 CSS improvements over Leaflet
+
+**Remove (Leaflet-specific):**
+```css
+/* DELETE — no longer needed */
+.leaflet-container { background: #282828 !important; }
+```
+
+MapLibre sets its canvas background from the style JSON (`background-color` in the style's
+`background` layer). CARTO dark-matter style uses `#1a1a1a` — no flash on load.
+
+**Add (MapLibre):**
+```css
+/* ── MapLibre GL overrides ───────────────────────────────────────────────────── */
+
+/* Navigation controls (zoom +/−, compass) */
+.maplibregl-ctrl-group {
+    background: var(--color-canvas);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-sm);
+    box-shadow: var(--shadow-sm);
+}
+.maplibregl-ctrl-group button {
+    color: var(--color-ink-2);
+}
+.maplibregl-ctrl-group button:hover {
+    background: var(--color-surface-raised);
+    color: var(--color-ink);
+}
+.maplibregl-ctrl-group button + button {
+    border-top: 1px solid var(--color-border);
+}
+
+/* Attribution bar */
+.maplibregl-ctrl-attrib {
+    background: rgba(26,24,20,0.75) !important;
+    color: var(--color-ink-muted) !important;
+    font-family: var(--font-ui);
+    font-size: 0.7rem;
+    backdrop-filter: blur(4px);
+}
+.maplibregl-ctrl-attrib a {
+    color: var(--color-accent) !important;
+}
+
+/* Popup */
+.maplibregl-popup-content {
+    background: var(--color-canvas);
+    color: var(--color-ink);
+    font-family: var(--font-ui);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+    box-shadow: var(--shadow-md);
+    padding: var(--space-4);
+}
+.maplibregl-popup-tip {
+    border-top-color: var(--color-canvas) !important;
+}
+.maplibregl-popup-close-button {
+    color: var(--color-ink-muted);
+    font-size: 1.1rem;
+    padding: var(--space-1) var(--space-2);
+}
+.maplibregl-popup-close-button:hover {
+    color: var(--color-ink);
+    background: transparent;
+}
+
+/* Cursor — pointer hand over clickable markers */
+.maplibregl-canvas-container.maplibregl-interactive {
+    cursor: grab;
+}
+.maplibregl-canvas-container.maplibregl-interactive:active {
+    cursor: grabbing;
+}
+```
+
+**Mobile scroll-trap prevention:** For embedded maps (mini-map on dailies, home map),
+initialize with `cooperativeGestures: true` — requires two fingers to pan on touch.
+The full-page `/map` uses normal gestures (`cooperativeGestures: false`, the default).
+*Note: verify `cooperativeGestures` is available in the chosen MapLibre GL 4.x version
+during implementation; if absent, use `dragPan: false` on touch-only + a two-finger
+hint overlay as fallback.*
+
+### 2.6 What is NOT migrated now
+
+Features from Sabdia's map that were explicitly deferred:
+
+| Feature | Decision |
+|---|---|
+| Ghost pins for upcoming/planned stops | Documented; deferred — requires `show_preview` frontmatter field + Twig logic |
+| Pulsing amber dot for current location | Documented; deferred — requires "current entry" detection logic |
+| `flyTo()` on marker click | Deferred — nice UX upgrade, implement after migration stabilises |
+| 3D terrain | Deferred — requires DEM tile source (MapTiler key) |
+| Per-story inline MapBlock shortcode | Deferred — implement as part of story mode v2 |
+| MapTiler outdoor/satellite/topo styles for GPX | Deferred — requires MapTiler API key |
+
+These are preserved here so they can be picked up in a later milestone without needing
+to re-research the Sabdia implementation.
+
+---
+
+## Out of scope
+
+- Story-specific inline MapBlock shortcode (deferred, see §2.6)
+- Animated hero video (requires server-side FFmpeg, not available in Grav)
+- Push notifications for new stories
+- Story-level statistics (word count, reading time)
+- Co-authoring / Travel Buddy equivalent
+- 3D flyover video