@gramps-connect/story 0.1.2 → 0.2.0

package/src/editor/StoryTextField.tsx

@@ -0,0 +1,61 @@
+// A plain Textarea plus Bold/Italic buttons that wrap the selection in the
+// story format's `**`/`*` markers -- the only formatting a slide's text has
+// (parseStoryText is the matching reader), so no rich-text editor.
+import { useRef } from "react";
+import { Button, Group, Stack, Text, Textarea } from "@mantine/core";
+
+/** Wraps the textarea's selection in `marker` (or unwraps it, if the
+ * selection is already exactly `marker…marker`); with nothing selected,
+ * inserts an empty pair and leaves the cursor between them. */
+function applyMarker(el: HTMLTextAreaElement, marker: string, value: string, onChange: (v: string) => void) {
+  const start = el.selectionStart ?? value.length;
+  const end = el.selectionEnd ?? value.length;
+  if (start === end) {
+    onChange(value.slice(0, start) + marker + marker + value.slice(end));
+    requestAnimationFrame(() => {
+      el.focus();
+      el.setSelectionRange(start + marker.length, start + marker.length);
+    });
+    return;
+  }
+  const selected = value.slice(start, end);
+  const alreadyWrapped = selected.length > marker.length * 2 && selected.startsWith(marker) && selected.endsWith(marker);
+  const replacement = alreadyWrapped ? selected.slice(marker.length, selected.length - marker.length) : `${marker}${selected}${marker}`;
+  onChange(value.slice(0, start) + replacement + value.slice(end));
+}
+
+export interface StoryTextFieldProps {
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+  boldLabel?: string;
+  italicLabel?: string;
+  minRows?: number;
+}
+
+export function StoryTextField({ label, value, onChange, boldLabel = "Bold", italicLabel = "Italic", minRows = 3 }: StoryTextFieldProps) {
+  const ref = useRef<HTMLTextAreaElement>(null);
+  return (
+    <Stack gap={4}>
+      <Group gap="xs">
+        <Text size="sm" fw={500}>{label}</Text>
+        <Button
+          variant="default" size="compact-xs" fw={700} aria-label={boldLabel} title={boldLabel}
+          onClick={() => ref.current && applyMarker(ref.current, "**", value, onChange)}
+        >
+          B
+        </Button>
+        <Button
+          variant="default" size="compact-xs" fs="italic" aria-label={italicLabel} title={italicLabel}
+          onClick={() => ref.current && applyMarker(ref.current, "*", value, onChange)}
+        >
+          i
+        </Button>
+      </Group>
+      <Textarea
+        ref={ref} aria-label={label} autosize minRows={minRows} maxRows={14} value={value}
+        onChange={(e) => onChange(e.currentTarget.value)}
+      />
+    </Stack>
+  );
+}

package/src/editor/dates.ts

@@ -0,0 +1,21 @@
+// A date as typed ("about 1850", "um 1850") to its precise form (EDTF),
+// read the way Gramps reads dates, in the story's language: the player
+// needs the precise form for the timeline and for picking historical maps.
+import { loadLocale, parseDate, resolveLocaleCode, toEdtf } from "@gramps-connect/gramps-date";
+
+/** Turns date text into EDTF, or undefined when the text isn't a date
+ * that has one ("spring 1850", a non-Gregorian date). */
+export type DateTextParser = (text: string, language: string | undefined) => Promise<string | undefined>;
+
+/** The default parser: gramps-date in the story's language (loaded on first
+ * use), English when the story has none or gramps-date doesn't know it. */
+export const suggestEdtf: DateTextParser = async (text, language) => {
+  if (!text.trim()) return undefined;
+  const code = (language && resolveLocaleCode(language.replace(/-/g, "_"))) || "en";
+  if (code !== "en" && !(await loadLocale(code))) return undefined;
+  try {
+    return toEdtf(parseDate(text, { locale: code }));
+  } catch {
+    return undefined;
+  }
+};

package/src/editor/index.ts

@@ -0,0 +1,10 @@
+export { StoryEditor, type StoryEditorProps } from "./StoryEditor";
+export { StoryTextField, type StoryTextFieldProps } from "./StoryTextField";
+export { SlideList, type SlideListProps } from "./SlideList";
+export { DateField, type DateFieldProps } from "./DateField";
+export { suggestEdtf, type DateTextParser } from "./dates";
+export { EDITOR_ENGLISH, type EditorStrings } from "./strings";
+export {
+  addSlide, blankStory, COALESCE_MS, deleteSlide, duplicateSlide, moveSlide, nextSlideId, pruneMedia, record, redo,
+  slideDate, startHistory, storyFileName, undo, updateSlide, updateStory, usedMedia, type History,
+} from "./model";

package/src/editor/model.ts

@@ -0,0 +1,167 @@
+// The editor's changes to a story, as pure functions from one StoryDoc to
+// the next -- never mutating, so undo is just keeping the old ones. Every
+// change spreads the object it touches, so fields this version doesn't
+// know (a newer minor version's, an extension's) ride along untouched:
+// opening and saving a story must never lose anything.
+import { FORMAT_ID, FORMAT_VERSION } from "../version";
+import type { Slide, StoryDate, StoryDoc } from "../types";
+
+/** A story with one empty slide: the smallest valid one. */
+export function blankStory(title: string, language?: string): StoryDoc {
+  return {
+    format: FORMAT_ID,
+    version: FORMAT_VERSION,
+    title,
+    ...(language ? { language } : {}),
+    slides: [{ id: "s0", title }],
+    media: {},
+  };
+}
+
+/** "s<n>" past every id already of that form, so it's unique however the
+ * story's other ids were made. */
+export function nextSlideId(doc: StoryDoc): string {
+  let max = -1;
+  for (const slide of doc.slides) {
+    const match = /^s(\d+)$/.exec(slide.id);
+    if (match) max = Math.max(max, Number(match[1]));
+  }
+  let n = max + 1;
+  const ids = new Set(doc.slides.map((s) => s.id));
+  while (ids.has(`s${n}`)) n += 1;
+  return `s${n}`;
+}
+
+function withSlides(doc: StoryDoc, slides: Slide[]): StoryDoc {
+  return { ...doc, slides };
+}
+
+/** A new empty slide after `index`; returns the story and the new slide's
+ * index. */
+export function addSlide(doc: StoryDoc, index: number): { doc: StoryDoc; index: number } {
+  const slides = [...doc.slides];
+  const at = Math.min(Math.max(index + 1, 0), slides.length);
+  slides.splice(at, 0, { id: nextSlideId(doc) });
+  return { doc: withSlides(doc, slides), index: at };
+}
+
+/** A copy of the slide right after it, with its own id. */
+export function duplicateSlide(doc: StoryDoc, index: number): { doc: StoryDoc; index: number } {
+  const slides = [...doc.slides];
+  const copy = structuredClone(slides[index]);
+  copy.id = nextSlideId(doc);
+  slides.splice(index + 1, 0, copy);
+  return { doc: withSlides(doc, slides), index: index + 1 };
+}
+
+/** Removes a slide, unless it's the only one (a story has at least one). */
+export function deleteSlide(doc: StoryDoc, index: number): { doc: StoryDoc; index: number } {
+  if (doc.slides.length <= 1) return { doc, index };
+  const slides = doc.slides.filter((_, i) => i !== index);
+  return { doc: withSlides(doc, slides), index: Math.min(index, slides.length - 1) };
+}
+
+export function moveSlide(doc: StoryDoc, from: number, to: number): StoryDoc {
+  if (from === to || to < 0 || to >= doc.slides.length) return doc;
+  const slides = [...doc.slides];
+  const [slide] = slides.splice(from, 1);
+  slides.splice(to, 0, slide);
+  return withSlides(doc, slides);
+}
+
+/** Sets fields on an object; an undefined value removes the field, so
+ * cleared text doesn't linger as "". */
+function patched<T extends object>(base: T, patch: Partial<T>): T {
+  const next = { ...base } as Record<string, unknown>;
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) delete next[key];
+    else next[key] = value;
+  }
+  return next as T;
+}
+
+export function updateSlide(doc: StoryDoc, index: number, patch: Partial<Slide>): StoryDoc {
+  const slides = [...doc.slides];
+  slides[index] = patched(slides[index], patch);
+  return withSlides(doc, slides);
+}
+
+export function updateStory(doc: StoryDoc, patch: Partial<Omit<StoryDoc, "slides" | "media">>): StoryDoc {
+  return patched(doc, patch as Partial<StoryDoc>);
+}
+
+/** A slide date from what was typed and its precise form. Empty text is no
+ * date at all. A new precise form drops a `sortYear` it would contradict
+ * (the timeline reads sortYear first); the date's other fields stay. */
+export function slideDate(previous: StoryDate | undefined, text: string, edtf: string | undefined): StoryDate | undefined {
+  if (!text.trim()) return undefined;
+  const next = patched(previous ?? { text }, { text, edtf: edtf || undefined });
+  if (next.edtf !== previous?.edtf) delete next.sortYear;
+  return next;
+}
+
+/** Every media key a slide or overlay refers to. */
+export function usedMedia(doc: StoryDoc): Set<string> {
+  const used = new Set<string>();
+  for (const slide of doc.slides) {
+    for (const m of slide.media ?? []) used.add(m.ref);
+    for (const o of slide.place?.overlays ?? []) used.add(o.media);
+  }
+  return used;
+}
+
+/** The story as it should be saved: media nothing refers to any more left
+ * out, and the files only those that are still used. */
+export function pruneMedia(doc: StoryDoc, files: Map<string, Uint8Array>): { doc: StoryDoc; files: Map<string, Uint8Array> } {
+  const used = usedMedia(doc);
+  const media = Object.fromEntries(Object.entries(doc.media).filter(([key]) => used.has(key)));
+  const srcs = new Set(Object.values(media).map((m) => m.src));
+  return {
+    doc: { ...doc, media },
+    files: new Map([...files].filter(([path]) => srcs.has(path))),
+  };
+}
+
+/** "Josef Meyer" -> "Josef Meyer.story.zip", minus characters some file
+ * systems refuse. */
+export function storyFileName(title: string): string {
+  const safe = title.replace(/[\\/:*?"<>|\u0000-\u001f]+/g, " ").replace(/\s+/g, " ").trim().slice(0, 120);
+  return `${safe || "story"}.story.zip`;
+}
+
+/** Undo and redo over whole documents. Typing in one field makes one step,
+ * not one per keystroke: a change with the same `key` within COALESCE_MS
+ * of the last replaces it. */
+export interface History {
+  past: StoryDoc[];
+  present: StoryDoc;
+  future: StoryDoc[];
+  lastKey?: string;
+  lastAt?: number;
+}
+
+export const COALESCE_MS = 1500;
+const MAX_STEPS = 200;
+
+export function startHistory(doc: StoryDoc): History {
+  return { past: [], present: doc, future: [] };
+}
+
+export function record(history: History, next: StoryDoc, key?: string, now = Date.now()): History {
+  if (next === history.present) return history;
+  const coalesce = key !== undefined && key === history.lastKey && history.lastAt !== undefined && now - history.lastAt < COALESCE_MS;
+  const past = coalesce ? history.past : [...history.past, history.present].slice(-MAX_STEPS);
+  return { past, present: next, future: [], lastKey: key, lastAt: now };
+}
+
+export function undo(history: History): History {
+  const previous = history.past[history.past.length - 1];
+  if (!previous) return history;
+  return { past: history.past.slice(0, -1), present: previous, future: [history.present, ...history.future] };
+}
+
+export function redo(history: History): History {
+  const [next, ...future] = history.future;
+  if (!next) return history;
+  return { past: [...history.past, history.present], present: next, future };
+}

package/src/editor/strings.ts

@@ -0,0 +1,82 @@
+// The editor's own words. English here; a host with its own translations
+// (Gramps Connect) passes StoryEditor's `strings` instead.
+
+export interface EditorStrings {
+  story: string;
+  storySettings: string;
+  title: string;
+  language: string;
+  languageHint: string;
+  map: string;
+  mapStandard: string;
+  mapHistorical: string;
+  mapAuto: string;
+  mapNone: string;
+  slides: string;
+  untitledSlide: string;
+  addSlide: string;
+  duplicateSlide: string;
+  deleteSlide: string;
+  moveUp: string;
+  moveDown: string;
+  slideTitle: string;
+  text: string;
+  bold: string;
+  italic: string;
+  date: string;
+  dateHint: string;
+  preciseDate: string;
+  preciseDateHint: string;
+  preciseDateFollows: string;
+  preciseDateNotUnderstood: string;
+  matchDateAsWritten: string;
+  noPreciseDate: string;
+  place: string;
+  photos: string;
+  undo: string;
+  redo: string;
+  present: string;
+  preview: string;
+  problems: (count: number) => string;
+  openingSlide: string;
+}
+
+export const EDITOR_ENGLISH: EditorStrings = {
+  story: "Story",
+  storySettings: "Title, language and map",
+  title: "Title",
+  language: "Language",
+  languageHint: "The language the story is written in, e.g. en, de or fr-CA. Dates are read in it.",
+  map: "Map",
+  mapStandard: "Today's map",
+  mapHistorical: "Historical maps for each slide's year",
+  mapAuto: "Viewer's choice",
+  mapNone: "No map",
+  slides: "Slides",
+  untitledSlide: "Untitled slide",
+  addSlide: "Add slide",
+  duplicateSlide: "Duplicate",
+  deleteSlide: "Delete",
+  moveUp: "Move up",
+  moveDown: "Move down",
+  slideTitle: "Title",
+  text: "Text",
+  bold: "Bold",
+  italic: "Italic",
+  date: "Date",
+  dateHint: "As readers should see it, e.g. about 1850, 3 May 1850, between 1850 and 1860.",
+  preciseDate: "Precise date (EDTF)",
+  preciseDateHint: "Places the slide on the timeline and picks historical maps.",
+  preciseDateFollows: "Worked out from the date as written.",
+  preciseDateNotUnderstood: "Not a date the timeline can use.",
+  matchDateAsWritten: "Work it out from the date",
+  noPreciseDate: "None: this slide stays off the timeline.",
+  place: "Place",
+  photos: "Photos",
+  undo: "Undo",
+  redo: "Redo",
+  present: "Present",
+  preview: "Preview",
+  problems: (count) => (count === 1 ? "1 problem to fix before saving" : `${count} problems to fix before saving`),
+  openingSlide: "Opening slide",
+};

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,11 +34,21 @@ 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 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, place: Place | undefined, duration: number) {
+/** 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 });
@@ -43,13 +58,24 @@ function moveCamera(map: MapLibreMap, place: Place | undefined, duration: number
   if (center) map.flyTo({ center, zoom: 9, essential: true, duration });
 }
 
-/** The pin on the place; held where it was, dimmed, for a slide with none. */
-function placeMarker(marker: MapLibreMarker | null, center: [number, number] | null) {
+/** 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);
-  marker.getElement().style.opacity = center ? "1" : "0.4";
+  // 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;
@@ -105,10 +131,9 @@ export function MapBackground({ initialCenter, current, dark, colors, panelFract
     // 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.place;
-    const startCenter = placeCenter(start);
-    map.jumpTo({ center: startCenter ?? initialCenter });
-    if (startCenter) moveCamera(map, start, 0);
+    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");
@@ -120,7 +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, placeCenter(currentRef.current.place));
+      placeMarker(markerRef.current, currentRef.current);
     });
     return () => {
       markerRef.current?.remove();
@@ -186,18 +211,25 @@ 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 (see moveCamera). Keyed to the slide, not to `ready`, so a
   // map-mode switch never yanks the view back from wherever the viewer
@@ -205,10 +237,9 @@ export function MapBackground({ initialCenter, current, dark, colors, panelFract
   useEffect(() => {
     const map = mapRef.current;
     if (!map) return;
-    const center = placeCenter(place);
-    placeMarker(markerRef.current, center);
-    // No place: the camera stays put.
-    if (center) moveCamera(map, place, 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";
@@ -44,6 +44,9 @@ export interface StoryPlayerProps {
   renderMapModeControl?: (props: MapModeControlProps) => ReactNode;
   /** Shown before the title, e.g. ViewerBrand on a standalone page. */
   brand?: ReactNode;
+  /** The host's own buttons, at the right of the title bar (before the
+   * close button), e.g. the viewer site's Edit. */
+  actions?: ReactNode;
   initialSlide?: number;
 }
 
@@ -201,7 +204,7 @@ function NavArrows({ index, total, onPrev, onNext, variant, strings, colors }: {
 
 export function StoryPlayer({
   story, resolveMedia, dark = false, colors: colorOverrides, strings: stringOverrides, onClose,
-  keyboard = true, onSlideChange, renderMapModeControl, brand, initialSlide = 0,
+  keyboard = true, onSlideChange, renderMapModeControl, brand, actions, initialSlide = 0,
 }: StoryPlayerProps) {
   const colors = useMemo(() => ({ ...defaultColors(dark), ...colorOverrides }), [dark, colorOverrides]);
   const strings = useMemo(
@@ -299,7 +302,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) {
@@ -365,6 +374,16 @@ export function StoryPlayer({
           </div>
         </div>
       )}
+      {actions && (
+        <div
+          style={{
+            position: "absolute", top: 0, right: onClose ? 60 : 12, height: BAR_HEIGHT, zIndex: 3,
+            display: "flex", alignItems: "center", gap: 8,
+          }}
+        >
+          {actions}
+        </div>
+      )}
       {onClose && (
         <RoundButton
           label={strings.close} size={36} onClick={onClose}

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;
+}