@gramps-connect/story 0.1.1 → 0.1.3

package/dist/types/player/geo.d.ts

@@ -6,3 +6,11 @@ export declare function placeBounds(place: Place | undefined): Bounds | null;
 /** Where to put the pin: the place's own point, else the middle of its
  * shape and overlays. Null for a slide with no position at all. */
 export declare function placeCenter(place: Place | undefined): LonLat | null;
+export interface StoryPlaces {
+    points: LonLat[];
+    bounds: Bounds;
+}
+/** Every place in the story at once, for its opening view: one point per
+ * distinct place, and the box around all of them, shapes and overlays
+ * included. Null when no slide has a position. */
+export declare function storyPlaces(places: (Place | undefined)[]): StoryPlaces | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gramps-connect/story",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Read, write, validate and present .story.zip files: portable, versioned family-history stories.",
   "license": "AGPL-3.0-or-later",
   "type": "module",

package/src/player/MapBackground.tsx

@@ -12,7 +12,7 @@ import type { GeoJSONSource, Map as MapLibreMap, Marker as MapLibreMarker } from
 import type { FeatureCollection, GeoJSON } from "geojson";
 import type { Overlay, Place } from "../types";
 import { dateCoversYear } from "./dates";
-import { placeBounds, placeCenter } from "./geo";
+import { placeBounds, placeCenter, type StoryPlaces } from "./geo";
 import { applyOhmYear, crossfadeStyleSwap, mapStyleKey, mapStyleUrl } from "./mapStyles";
 import { PIN_PATH_D, type PlayerColors } from "./theme";
 
@@ -22,6 +22,11 @@ const LINE_LAYER = "story-shape-line";
 const POINT_LAYER = "story-shape-points";
 const LABEL_LAYER = "story-shape-labels";
 const OVERLAY_PREFIX = "story-overlay-";
+const PLACES_SOURCE = "story-places";
+const PLACES_LAYER = "story-places-dots";
+// Room around the outermost dots of the opening view, inside the part of
+// the map the slide panel leaves free.
+const OVERVIEW_PADDING = 60;
 const EMPTY: FeatureCollection = { type: "FeatureCollection", features: [] };
 
 /** The current slide, as far as the map cares. `key` is the slide id:
@@ -29,8 +34,48 @@ const EMPTY: FeatureCollection = { type: "FeatureCollection", features: [] };
 export interface MapSlide {
   key: string;
   place: Place | undefined;
+  /** Every place in the story, on an opening slide with no place of its
+   * own: framed together, a dot each, instead of the pin. */
+  overview: StoryPlaces | null;
 }
 
+/** Frame the story's places for an overview; else the place's shape or
+ * overlays (usually a field, a route or an old map, far tighter than a
+ * town-level zoom); else fly to its point. */
+function moveCamera(map: MapLibreMap, slide: MapSlide, duration: number) {
+  if (slide.overview) {
+    const [west, south, east, north] = slide.overview.bounds;
+    map.fitBounds([[west, south], [east, north]], { maxZoom: 9, padding: OVERVIEW_PADDING, duration });
+    return;
+  }
+  const place = slide.place;
+  const bounds = placeBounds(place);
+  if (bounds) {
+    map.fitBounds([[bounds[0], bounds[1]], [bounds[2], bounds[3]]], { maxZoom: 17, duration });
+    return;
+  }
+  const center = placeCenter(place);
+  if (center) map.flyTo({ center, zoom: 9, essential: true, duration });
+}
+
+/** The pin on the place; hidden for an overview (the dots stand in for
+ * it), else held where it was, dimmed, for a slide with no place. */
+function placeMarker(marker: MapLibreMarker | null, slide: MapSlide) {
+  if (!marker) return;
+  const center = placeCenter(slide.place);
+  if (center) marker.setLngLat(center);
+  // Through the marker, not its element's style: maplibre rewrites that
+  // from the marker's own opacity every frame.
+  marker.setOpacity(slide.overview ? 0 : center ? 1 : 0.4);
+}
+
+const placeDots = (overview: StoryPlaces | null): FeatureCollection => ({
+  type: "FeatureCollection",
+  features: (overview?.points ?? []).map((coordinates) => ({
+    type: "Feature", properties: {}, geometry: { type: "Point", coordinates },
+  })),
+});
+
 export function MapBackground({ initialCenter, current, dark, colors, panelFraction, ohmYear, resolveMedia }: {
   initialCenter: [number, number];
   current: MapSlide;
@@ -64,6 +109,8 @@ export function MapBackground({ initialCenter, current, dark, colors, panelFract
   // What the map was built or last swapped with, so a re-render with the
   // same effective style never triggers a reload.
   const appliedStyleKeyRef = useRef(mapStyleKey(dark, ohmYear));
+  const currentRef = useRef(current);
+  currentRef.current = current;
 
   useEffect(() => {
     if (!containerEl) return;
@@ -81,7 +128,12 @@ export function MapBackground({ initialCenter, current, dark, colors, panelFract
     map.on("style.load", () => setReady(true));
     // Center points in the part of the map the slide panel doesn't cover.
     map.setPadding({ top: 0, bottom: 0, left: 0, right: containerEl.clientWidth * panelFraction });
-    map.jumpTo({ center: initialCenter });
+    // Straight to the opening slide's place, unanimated. The camera effect
+    // below ran for it before this map existed (the container arrives a
+    // render late), so a story opened partway through starts there too.
+    const start = currentRef.current;
+    map.jumpTo({ center: placeCenter(start.place) ?? initialCenter });
+    moveCamera(map, start, 0);
     map.on("load", () => {
       const c = colorsRef.current;
       const el = document.createElement("div");
@@ -93,6 +145,7 @@ export function MapBackground({ initialCenter, current, dark, colors, panelFract
         + `</svg>`;
       // The pin's tip, not its middle, sits on the coordinate.
       markerRef.current = new maplibregl.Marker({ element: el, anchor: "bottom" }).setLngLat(initialCenter).addTo(map);
+      placeMarker(markerRef.current, currentRef.current);
     });
     return () => {
       markerRef.current?.remove();
@@ -158,42 +211,35 @@ export function MapBackground({ initialCenter, current, dark, colors, panelFract
         "text-halo-width": 1.5,
       },
     });
+    map.addSource(PLACES_SOURCE, { type: "geojson", data: EMPTY });
+    map.addLayer({
+      id: PLACES_LAYER, type: "circle", source: PLACES_SOURCE,
+      paint: { "circle-radius": 6, "circle-color": c.mark, "circle-stroke-width": 2, "circle-stroke-color": c.surface },
+    });
   }, [ready]);
 
   const place = current.place;
 
-  // The current slide's shape. Re-supplied after each style load, since a
+  // The current slide's shape, or the overview's dots. Re-supplied after each style load, since a
   // swap empties the source.
   useEffect(() => {
     const map = mapRef.current;
     if (!map || !ready) return;
     const source = map.getSource(SHAPE_SOURCE) as GeoJSONSource | undefined;
     source?.setData((place?.geometry as GeoJSON | undefined) ?? EMPTY);
-  }, [ready, current.key, place]);
+    const dots = map.getSource(PLACES_SOURCE) as GeoJSONSource | undefined;
+    dots?.setData(placeDots(current.overview));
+  }, [ready, current.key, place, current.overview]);
 
-  // Camera: once per slide. A shape or overlay is framed (it's usually a
-  // field, a route or an old map, far tighter than a town-level zoom);
-  // otherwise fly to the point. Keyed to the slide, not to `ready`, so a
+  // Camera: once per slide (see moveCamera). Keyed to the slide, not to `ready`, so a
   // map-mode switch never yanks the view back from wherever the viewer
   // has since panned.
   useEffect(() => {
     const map = mapRef.current;
     if (!map) return;
-    const center = placeCenter(place);
-    const marker = markerRef.current;
-    if (!center) {
-      // No place: the camera stays put and the marker dims.
-      if (marker) marker.getElement().style.opacity = "0.4";
-      return;
-    }
-    marker?.setLngLat(center);
-    if (marker) marker.getElement().style.opacity = "1";
-    const bounds = placeBounds(place);
-    if (bounds) {
-      map.fitBounds([[bounds[0], bounds[1]], [bounds[2], bounds[3]]], { maxZoom: 17, duration: 900 });
-    } else {
-      map.flyTo({ center, zoom: 9, essential: true, duration: 900 });
-    }
+    placeMarker(markerRef.current, current);
+    // No place and no overview: the camera stays put.
+    moveCamera(map, current, 900);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [current.key]);
 

package/src/player/StoryPlayer.tsx

@@ -6,7 +6,7 @@
 import { useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode, type TouchEvent } from "react";
 import type { MediaItem, Slide, StoryDoc } from "../types";
 import { timelineYear } from "./dates";
-import { placeCenter } from "./geo";
+import { placeCenter, storyPlaces } from "./geo";
 import { MapBackground, type MapSlide } from "./MapBackground";
 import { MapModeControl, type MapMode, type MapModeControlProps } from "./MapModeControl";
 import { parseStoryText } from "./text";
@@ -299,7 +299,13 @@ export function StoryPlayer({
 
   // Stable per slide, so a re-render for an unrelated reason (a map-mode
   // click) never looks like a new slide to the map's camera.
-  const mapSlide = useMemo<MapSlide>(() => ({ key: slide?.id ?? String(index), place: slide?.place }), [slide, index]);
+  const places = useMemo(() => storyPlaces(slides.map((s) => s.place)), [slides]);
+  const mapSlide = useMemo<MapSlide>(() => ({
+    key: slide?.id ?? String(index),
+    place: slide?.place,
+    // The opening card, with no place of its own, shows where the story goes.
+    overview: index === 0 && !placeCenter(slide?.place) ? places : null,
+  }), [slide, index, places]);
   const firstCenter = useMemo(() => {
     if (story.presentation?.basemap === "none") return null;
     for (const s of slides) {

package/src/player/geo.ts

@@ -44,3 +44,25 @@ export function placeCenter(place: Place | undefined): LonLat | null {
   const bounds = placeBounds(place);
   return bounds ? [(bounds[0] + bounds[2]) / 2, (bounds[1] + bounds[3]) / 2] : null;
 }
+
+export interface StoryPlaces {
+  points: LonLat[];
+  bounds: Bounds;
+}
+
+/** Every place in the story at once, for its opening view: one point per
+ * distinct place, and the box around all of them, shapes and overlays
+ * included. Null when no slide has a position. */
+export function storyPlaces(places: (Place | undefined)[]): StoryPlaces | null {
+  const bounds: Bounds = [Infinity, Infinity, -Infinity, -Infinity];
+  const points = new Map<string, LonLat>();
+  for (const place of places) {
+    const center = placeCenter(place);
+    if (!center) continue;
+    points.set(`${center[0].toFixed(5)},${center[1].toFixed(5)}`, center);
+    visit(center, bounds);
+    const box = placeBounds(place);
+    if (box) visit([[box[0], box[1]], [box[2], box[3]]], bounds);
+  }
+  return points.size ? { points: [...points.values()], bounds } : null;
+}