@gramps-connect/story 0.3.0 → 0.5.0

package/src/editor/mapEditorStrings.ts

@@ -0,0 +1,109 @@
+// The map editor's words. English here; Gramps Connect passes its own
+// translations (its t() is keyed by these same English texts).
+
+export interface MapEditorStrings {
+  point: string;
+  line: string;
+  polygon: string;
+  rectangle: string;
+  select: string;
+  image: string;
+  editOptions: string;
+  labelText: string;
+  regionName: string;
+  fillOpacity: string;
+  scale: string;
+  transform: string;
+  overlayName: string;
+  opacity: string;
+  stackingOrder: string;
+  removeImage: string;
+  resizeImage: string;
+  rotateImage: string;
+  warpCorner: string;
+  basemapFailed: string;
+  imageFailed: string;
+  lockedOne: string;
+  lockedMany: (count: number) => string;
+  lockedExplain: string;
+  // The help (MapEditorHelp), in the pieces it's put together from.
+  helpTitle: string;
+  helpDrawing: string;
+  helpPoint: string;
+  helpLine: string;
+  helpEnterFinishes: string;
+  helpEscCancels: string;
+  helpRectangle: string;
+  helpImage: string;
+  helpImages: string;
+  helpBelow: string;
+  helpEditing: string;
+  helpSelect: string;
+  helpVertex: string;
+  helpColor: string;
+  helpDelete: string;
+  helpOr: string;
+  helpRotate: string;
+  helpRotateHandle: string;
+  helpImageMove: string;
+  helpImageResize: string;
+  helpImageRotate: string;
+  helpImageTransform: string;
+  helpImageRemove: string;
+}
+
+export const MAP_EDITOR_ENGLISH: MapEditorStrings = {
+  point: "Point",
+  line: "Line",
+  polygon: "Polygon",
+  rectangle: "Rectangle",
+  select: "Select",
+  image: "Image",
+  editOptions: "Edit Options",
+  labelText: "Label text",
+  regionName: "Region name (optional)",
+  fillOpacity: "Fill opacity",
+  scale: "Scale",
+  transform: "Transform",
+  overlayName: "Overlay name (optional)",
+  opacity: "Opacity",
+  stackingOrder: "Stacking order",
+  removeImage: "Remove this image",
+  resizeImage: "Drag to resize (keeps its exact shape, warped or not)",
+  rotateImage: "Drag to rotate",
+  warpCorner: "Drag to warp this corner",
+  basemapFailed: "The basemap could not be loaded.",
+  imageFailed: "The image failed to load.",
+  lockedOne: "1 shape can't be edited here",
+  lockedMany: (count) => `${count} shapes can't be edited here`,
+  lockedExplain: "For example, a region with a hole in it, or one whose outline crosses itself. It's drawn dashed, and saved exactly as it was.",
+  helpTitle: "How to use this editor",
+  helpDrawing: "Drawing",
+  helpPoint: "Point: click once to place it.",
+  helpLine: "Line, Polygon: click to place each point, then click that first point's own marker again to "
+    + "finish -- it's styled differently once there's enough points to close the shape. Pressing",
+  helpEnterFinishes: "finishes it too;",
+  helpEscCancels: "cancels it.",
+  helpRectangle: "Rectangle: click and drag from one corner to the opposite corner.",
+  helpImage: "Image: pick a media object to overlay -- see",
+  helpImages: "Images",
+  helpBelow: "below.",
+  helpEditing: "Editing a shape",
+  helpSelect: "Select: click a shape to select it, then drag it or one of its handles.",
+  helpVertex: "Drag a vertex to move it. To add a new point on a Line, Polygon, or Rectangle, drag the small "
+    + "midpoint marker between two existing vertices outward.",
+  helpColor: "The color swatch sets the next shape's color -- or, with a shape selected, changes its color.",
+  helpDelete: "Delete a selected shape or image with",
+  helpOr: "or",
+  helpRotate: "Rotate a selected Polygon, Rectangle, or Line: hold",
+  helpRotateHandle: "while dragging one of its handles.",
+  helpImageMove: "Drag anywhere on an image to move it.",
+  helpImageResize: "Drag its ↘ handle to resize it -- grows or shrinks from its own center, "
+    + "keeping its exact shape (works the same on a warped image, too).",
+  helpImageRotate: "Drag its ↻ handle to rotate it -- handy for aligning a scanned old map.",
+  helpImageTransform: "Switch to \"Transform\" to also show 4 corner handles you can drag independently "
+    + "(rubber-sheeting) -- for a scanned map that isn't printed at a uniform scale/orientation. "
+    + "Switching back to \"Scale\" just hides those 4 handles again; move/resize/rotate keep "
+    + "working on the image's exact current shape either way.",
+  helpImageRemove: "Click its × handle to remove it.",
+};

package/src/editor/model.ts

@@ -4,7 +4,7 @@
 // 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 { MediaItem, Slide, SlideMedia, StoryDate, StoryDoc } from "../types";
+import type { MediaItem, Place, Slide, SlideMedia, StoryDate, StoryDoc } from "../types";
 
 /** A story with one empty slide: the smallest valid one. */
 export function blankStory(title: string, language?: string): StoryDoc {
@@ -100,6 +100,43 @@ export function slideDate(previous: StoryDate | undefined, text: string, edtf: s
   return next;
 }
 
+/** A place with some fields set or (undefined) removed; one left with
+ * nothing in it is no place at all. Its shape and overlays, and any field
+ * this version doesn't know, stay as they were. */
+export function patchPlace(place: Place | undefined, patch: Partial<Place>): Place | undefined {
+  if (place && Object.entries(patch).every(([key, value]) => place[key as keyof Place] === value)) return place;
+  const next = patched(place ?? {}, patch);
+  return Object.keys(next).length ? next : undefined;
+}
+
+/** Degrees to 5 decimals: about a metre, and no float noise. */
+export const roundDegrees = (value: number) => Math.round(value * 1e5) / 1e5;
+
+/** "47.3769, 8.5417" (or with a space or semicolon between) -> a point;
+ * null when that's not two numbers in range. */
+export function parseLatLon(text: string): { lat: number; lon: number } | null {
+  const parts = text.trim().split(/\s*[,;\s]\s*/);
+  if (parts.length !== 2 || parts.some((p) => !/^[-+]?(\d+\.?\d*|\.\d+)$/.test(p))) return null;
+  const [lat, lon] = parts.map(Number);
+  if (Math.abs(lat) > 90 || Math.abs(lon) > 180) return null;
+  return { lat, lon };
+}
+
+export function formatLatLon(lat: number, lon: number): string {
+  return `${roundDegrees(lat)}, ${roundDegrees(lon)}`;
+}
+
+/** The places of the story's other slides, one per name (the first slide
+ * to use it), for giving another slide the very same place. */
+export function storyPlaceChoices(doc: StoryDoc, exceptIndex?: number): Place[] {
+  const byName = new Map<string, Place>();
+  doc.slides.forEach((slide, i) => {
+    const name = slide.place?.name?.trim();
+    if (i !== exceptIndex && name && !byName.has(name)) byName.set(name, slide.place!);
+  });
+  return [...byName.values()];
+}
+
 /** A prepared image to add to a story (see optimizeImage). */
 export interface NewImage {
   data: Uint8Array;

package/src/editor/placeSearch.ts

@@ -0,0 +1,61 @@
+// Finding a place by name, for the place field's opt-in search: Wikidata's
+// own search, then the chosen item's coordinates (P625). Both endpoints
+// allow any origin and need no key. This is the only thing the editor
+// sends anywhere, and only when asked to: it sends the name typed.
+// (Gramps Connect's place lookup walks the same API further, up the
+// "located in" chain, to build a place hierarchy; a story place is just a
+// name and a point.)
+
+const WIKIDATA_API = "https://www.wikidata.org/w/api.php";
+const WIKIDATA_ENTITY_DATA = "https://www.wikidata.org/wiki/Special:EntityData";
+
+export interface PlaceSearchResult {
+  /** The Wikidata item, e.g. "Q72". */
+  id: string;
+  label: string;
+  /** Usually names the region and country, which tells same-named places
+   * apart. */
+  description?: string;
+}
+
+export interface PlaceSearch {
+  search: (term: string, language: string | undefined, signal?: AbortSignal) => Promise<PlaceSearchResult[]>;
+  /** The result's position, or null when it has none. */
+  point: (result: PlaceSearchResult, signal?: AbortSignal) => Promise<{ lat: number; lon: number } | null>;
+}
+
+/** "fr_CA" or "fr-CA" -> "fr-ca", Wikidata's form. */
+function wikidataLanguage(language: string | undefined): string {
+  return (language ?? "").trim().toLowerCase().replace(/_/g, "-") || "en";
+}
+
+export async function searchWikidataPlaces(term: string, language?: string, signal?: AbortSignal): Promise<PlaceSearchResult[]> {
+  const code = wikidataLanguage(language);
+  const params = new URLSearchParams({
+    action: "wbsearchentities", search: term, language: code, uselang: code, format: "json", limit: "7",
+    origin: "*", // what makes an anonymous api.php GET answer cross-origin
+  });
+  const res = await fetch(`${WIKIDATA_API}?${params}`, { signal });
+  if (!res.ok) throw new Error(`Wikidata search failed (${res.status})`);
+  const data = (await res.json()) as { search?: { id: string; label?: string; description?: string }[] };
+  return (data.search ?? []).map((hit) => ({
+    id: hit.id,
+    label: hit.label ?? hit.id,
+    ...(hit.description ? { description: hit.description } : {}),
+  }));
+}
+
+export async function wikidataPoint(result: PlaceSearchResult, signal?: AbortSignal): Promise<{ lat: number; lon: number } | null> {
+  const res = await fetch(`${WIKIDATA_ENTITY_DATA}/${encodeURIComponent(result.id)}.json`, { signal });
+  if (!res.ok) throw new Error(`Wikidata fetch failed for ${result.id} (${res.status})`);
+  const data = (await res.json()) as {
+    entities?: Record<string, { claims?: Record<string, { mainsnak?: { datavalue?: { value?: unknown } } }[]> }>;
+  };
+  // A redirected item comes back under its new id: take whichever is there.
+  const entity = data.entities?.[result.id] ?? Object.values(data.entities ?? {})[0];
+  const value = entity?.claims?.P625?.[0]?.mainsnak?.datavalue?.value as { latitude?: number; longitude?: number } | undefined;
+  if (typeof value?.latitude !== "number" || typeof value.longitude !== "number") return null;
+  return { lat: value.latitude, lon: value.longitude };
+}
+
+export const WIKIDATA_PLACE_SEARCH: PlaceSearch = { search: searchWikidataPlaces, point: wikidataPoint };

package/src/editor/placeShapes.ts

@@ -0,0 +1,63 @@
+// A slide's place as the map editor sees it, and back: the place's
+// `geometry` (a FeatureCollection, a Feature or a bare geometry) as
+// features, and its `overlays` as image overlays keyed by media. Whatever
+// the editor doesn't edit -- an overlay's date, fields this version
+// doesn't know, a FeatureCollection's own members -- is carried over from
+// the place as it was.
+import type { Feature, FeatureCollection, Geometry } from "geojson";
+import type { Overlay, Place, StoryDate } from "../types";
+import type { MapEditorOverlay, MapEditorResult } from "./MapEditor";
+import { patchPlace } from "./model";
+
+/** The features in a place's `geometry`, whichever form it takes. */
+export function placeFeatures(place: Place | undefined): Feature[] {
+  const geometry = place?.geometry as { type: string; features?: unknown[] } | undefined;
+  if (!geometry) return [];
+  if (geometry.type === "FeatureCollection") {
+    return ((geometry.features ?? []) as Feature[]).filter((f) => f && f.geometry);
+  }
+  if (geometry.type === "Feature") return (geometry as unknown as Feature).geometry ? [geometry as unknown as Feature] : [];
+  return [{ type: "Feature", properties: {}, geometry: geometry as unknown as Geometry }];
+}
+
+/** What the map editor opens with for a place. */
+export function placeToEditor(place: Place | undefined): { features: Feature[]; overlays: MapEditorOverlay[] } {
+  return {
+    features: placeFeatures(place),
+    overlays: (place?.overlays ?? []).map((o) => ({
+      image: o.media, corners: o.corners,
+      ...(o.opacity !== undefined ? { opacity: o.opacity } : {}),
+      ...(o.order !== undefined ? { order: o.order } : {}),
+    })),
+  };
+}
+
+/** The place with what the map editor ended with. `dates` holds each
+ * overlay's date by media key, as edited beside the editor. */
+export function editorToPlace(
+  place: Place | undefined, result: MapEditorResult, dates: Map<string, StoryDate | undefined>,
+): Place | undefined {
+  const before = place?.geometry as (FeatureCollection & Record<string, unknown>) | undefined;
+  const geometry = result.features.length === 0
+    ? undefined
+    // A FeatureCollection keeps its own other members; anything else
+    // becomes one.
+    : { ...(before?.type === "FeatureCollection" ? before : {}), type: "FeatureCollection", features: result.features };
+  const previous = new Map((place?.overlays ?? []).map((o) => [o.media, o]));
+  const overlays = result.overlays.map((o): Overlay => {
+    const { opacity: _o, order: _r, date: _d, ...kept } = previous.get(o.image) ?? ({} as Partial<Overlay>);
+    const date = dates.has(o.image) ? dates.get(o.image) : previous.get(o.image)?.date;
+    return {
+      ...kept,
+      media: o.image,
+      corners: o.corners,
+      ...(o.opacity !== undefined && o.opacity !== 1 ? { opacity: o.opacity } : {}),
+      ...(o.order !== undefined ? { order: Math.round(o.order) } : {}),
+      ...(date ? { date } : {}),
+    };
+  });
+  return patchPlace(place, {
+    geometry: geometry as Place["geometry"],
+    overlays: overlays.length ? overlays : undefined,
+  });
+}

package/src/editor/strings.ts

@@ -32,6 +32,34 @@ export interface EditorStrings {
   matchDateAsWritten: string;
   noPreciseDate: string;
   place: string;
+  placeName: string;
+  removePlace: string;
+  findPlace: string;
+  findPlaceHint: string;
+  findPlaceNone: string;
+  findPlaceFailed: string;
+  findPlaceNoPoint: (name: string) => string;
+  coordinates: string;
+  coordinatesHint: string;
+  coordinatesInvalid: string;
+  placeMap: string;
+  placeMapHint: string;
+  placeShape: string;
+  placeOverlays: (count: number) => string;
+  placeKeeps: (what: string) => string;
+  editMap: string;
+  editMapHint: string;
+  mapDialogTitle: (placeName: string | undefined) => string;
+  mapHelp: string;
+  importShapes: string;
+  importShapesHint: string;
+  importFailed: (fileName: string) => string;
+  importNothing: (fileName: string) => string;
+  overlayAlready: string;
+  overlayDate: string;
+  overlayDateHint: string;
+  cancel: string;
+  done: string;
   photos: string;
   photosHint: string;
   addPhoto: string;
@@ -84,6 +112,34 @@ export const EDITOR_ENGLISH: EditorStrings = {
   matchDateAsWritten: "Work it out from the date",
   noPreciseDate: "None: this slide stays off the timeline.",
   place: "Place",
+  placeName: "Name",
+  removePlace: "Remove place",
+  findPlace: "Find on Wikidata",
+  findPlaceHint: "Looks the name up on Wikidata, to put the pin there. The name is all that's sent, and only when you ask.",
+  findPlaceNone: "Wikidata has no place by that name.",
+  findPlaceFailed: "Couldn't reach Wikidata.",
+  findPlaceNoPoint: (name) => `Wikidata has no map position for ${name}.`,
+  coordinates: "Latitude, longitude",
+  coordinatesHint: "e.g. 47.3769, 8.5417",
+  coordinatesInvalid: "Two numbers: latitude (-90 to 90), then longitude (-180 to 180).",
+  placeMap: "Map: click to put the pin",
+  placeMapHint: "Click the map to put the pin there, or drag the pin.",
+  placeShape: "a shape",
+  placeOverlays: (count) => (count === 1 ? "a map overlay" : `${count} map overlays`),
+  placeKeeps: (what) => `This place also has ${what}.`,
+  editMap: "Edit map",
+  editMapHint: "Shapes under the pin (a parish, a route) and scans of old maps laid over it.",
+  mapDialogTitle: (placeName) => (placeName ? `Map: ${placeName}` : "Map"),
+  mapHelp: "How to use this editor",
+  importShapes: "Import shapes",
+  importShapesHint: "Adds the points, lines and areas in a KML, GPX or GeoJSON file to this map.",
+  importFailed: (fileName) => `Couldn't read ${fileName} as a KML, GPX or GeoJSON file.`,
+  importNothing: (fileName) => `${fileName} has no shapes in it.`,
+  overlayAlready: "That image is already on this map.",
+  overlayDate: "Years it shows",
+  overlayDateHint: "e.g. 1850, or 1850 to 1880. With historical maps, it's hidden on slides outside them.",
+  cancel: "Cancel",
+  done: "Done",
   photos: "Photos",
   photosHint: "Add, drop or paste a photo. It's resized for the screen, and hidden details like camera and location are left out.",
   addPhoto: "Add photo",

package/src/mapEdit/geometry.ts

@@ -0,0 +1,211 @@
+// Map geometry for shapes and image overlays, as plain math (no map
+// library): image overlay corners moved, scaled and rotated in Web Mercator
+// space so a rectangle stays one at any latitude, and bounding boxes over
+// features and overlays. Moved here from Gramps Connect (its kmlMedia.ts),
+// which shares it with the Story Editor; the "kml" in some names is from
+// there, where KML was the first map file format.
+import type { Feature, Position } from "geojson";
+
+/** An overlay's 4 world corners, maplibre's own ImageSource `coordinates`
+ * order (top-left, top-right, bottom-right, bottom-left) and type. */
+export type OverlayCorners = [[number, number], [number, number], [number, number], [number, number]];
+
+const DEG_TO_RAD = Math.PI / 180;
+const RAD_TO_DEG = 180 / Math.PI;
+
+/** [lng,lat] -> normalized Web Mercator x/y (x east-positive, y
+ * *south*-positive) -- the exact projection maplibre's own map.project()
+ * uses internally, reimplemented here as plain math (no maplibre-gl
+ * import) so this module stays free of that ~900KB dependency (see
+ * MapItemEditorDialog.tsx's own doc comment on why maplibre-gl is always
+ * behind a lazy import elsewhere in Gramps Connect). Unlike raw [lng,lat],
+ * Mercator x/y is locally isotropic -- equal scale in both directions at
+ * any given point, which is the whole point of the projection -- making it
+ * the correct space to rotate a box in; see rotatePoint. */
+function mercatorFromLngLat([lng, lat]: [number, number]): [number, number] {
+  const x = (180 + lng) / 360;
+  const y = (180 - RAD_TO_DEG * Math.log(Math.tan(Math.PI / 4 + (lat * DEG_TO_RAD) / 2))) / 360;
+  return [x, y];
+}
+
+/** mercatorFromLngLat's inverse. */
+function lngLatFromMercator([x, y]: [number, number]): [number, number] {
+  const lng = x * 360 - 180;
+  const lat = 90 - 2 * Math.atan(Math.exp((y * 360 - 180) * DEG_TO_RAD)) * RAD_TO_DEG;
+  return [lng, lat];
+}
+
+/** Rotates one point by `rotationDeg` around `center` (positive =
+ * counterclockwise, matching KML's own <LatLonBox><rotation> convention)
+ * -- done in Mercator-projected space (see mercatorFromLngLat), not raw
+ * [lng,lat], so a rectangle stays a rectangle (right angles preserved)
+ * after rotating, regardless of latitude. A naive rotation directly on
+ * [lng,lat] -- this function's original implementation -- shears instead,
+ * since a degree of longitude and a degree of latitude aren't the same
+ * ground (or screen) distance away from the equator (found live: a square
+ * image's corners visibly stopped being 90 degrees once rotated away from
+ * 0). Gramps Connect's own image overlays are never meant to be opened in an
+ * external viewer (their picture is an app-internal Media reference), so diverging here
+ * from what Google Earth's own <LatLonBox><rotation> would render is an
+ * acceptable trade for Gramps Connect always rendering its own files correctly.
+ * Pass a negative `rotationDeg` to go the other way (world -> local). */
+export function rotatePoint(point: [number, number], center: [number, number], rotationDeg: number): [number, number] {
+  const angle = rotationDeg * DEG_TO_RAD;
+  const cos = Math.cos(angle);
+  const sin = Math.sin(angle);
+  const [px, py] = mercatorFromLngLat(point);
+  const [cx, cy] = mercatorFromLngLat(center);
+  // Mercator y increases southward -- negated here so this rotation is
+  // expressed in a conventional north-up, east-right plane (dx
+  // east-positive, dy north-positive), keeping "positive rotationDeg =
+  // counterclockwise" the same sense every caller already expects.
+  const dx = px - cx;
+  const dy = -(py - cy);
+  const rx = dx * cos - dy * sin;
+  const ry = dx * sin + dy * cos;
+  return lngLatFromMercator([cx + rx, cy - ry]);
+}
+
+/** Scales the distance from `center` to `point` by `scale`, in the same
+ * Mercator-projected space rotatePoint rotates in -- so scaling a
+ * rectangle (or an already-warped quad) uniformly from its own center
+ * preserves its exact shape/aspect ratio regardless of latitude, the same
+ * way rotatePoint preserves angles. MapItemEditorDialog.tsx's resize
+ * handle applies this to all 4 corners at once (see mountOverlay). */
+export function scalePoint(point: [number, number], center: [number, number], scale: number): [number, number] {
+  const [px, py] = mercatorFromLngLat(point);
+  const [cx, cy] = mercatorFromLngLat(center);
+  return lngLatFromMercator([cx + (px - cx) * scale, cy + (py - cy) * scale]);
+}
+
+/** The distance between `a` and `b` in the same Mercator-projected space
+ * scalePoint scales in -- not a real-world distance (Mercator distorts
+ * those away from the equator), just a consistent unit for computing a
+ * resize handle's before/after scale ratio, which only ever needs to be
+ * internally consistent with scalePoint's own projection, not physically
+ * meaningful on its own. */
+export function mercatorDistance(a: [number, number], b: [number, number]): number {
+  const [ax, ay] = mercatorFromLngLat(a);
+  const [bx, by] = mercatorFromLngLat(b);
+  return Math.hypot(bx - ax, by - ay);
+}
+
+/** The angle (degrees, positive = counterclockwise, 0 = due east) from
+ * `from` to `to` -- measured in the same Mercator-projected, north-up
+ * plane rotatePoint itself rotates in, so a caller tracking "how far has
+ * the user dragged this handle around the center" gets an angle that
+ * matches how rotatePoint will then actually render it (unlike a plain
+ * atan2 on raw [lng,lat], which suffers the same latitude-dependent skew
+ * rotatePoint's own doc comment describes). */
+export function mercatorBearing(from: [number, number], to: [number, number]): number {
+  const [fx, fy] = mercatorFromLngLat(from);
+  const [tx, ty] = mercatorFromLngLat(to);
+  return Math.atan2(-(ty - fy), tx - fx) * RAD_TO_DEG;
+}
+
+/** An axis-aligned box plus a rotation about its own center's 4 world
+ * corners -- KML's own <LatLonBox><rotation> model. Only ever needed to
+ * interpret an *old* overlay saved before Gramps Connect always wrote
+ * explicit corners (see its fetchAllKmlImageOverlays); the map editor
+ * itself only ever deals with corners directly, never this box shape. */
+export function cornersFromBox(
+  box: { north: number; south: number; east: number; west: number; rotation: number },
+): OverlayCorners {
+  const center: [number, number] = [(box.west + box.east) / 2, (box.north + box.south) / 2];
+  const corners: [number, number][] = [
+    [box.west, box.north], [box.east, box.north], [box.east, box.south], [box.west, box.south],
+  ];
+  return corners.map((p) => rotatePoint(p, center, box.rotation)) as OverlayCorners;
+}
+
+function visitCoordinates(coords: unknown, bounds: [number, number, number, number]): void {
+  if (typeof (coords as Position)[0] === "number") {
+    const [lng, lat] = coords as Position;
+    if (lng < bounds[0]) bounds[0] = lng;
+    if (lat < bounds[1]) bounds[1] = lat;
+    if (lng > bounds[2]) bounds[2] = lng;
+    if (lat > bounds[3]) bounds[3] = lat;
+    return;
+  }
+  for (const c of coords as unknown[]) visitCoordinates(c, bounds);
+}
+
+/** Every coordinate's bounding box across a set of KML features, as
+ * [west, south, east, north] -- maplibre's own LngLatBoundsLike corner
+ * order, so a caller can hand this straight to fitBounds/cameraForBounds to
+ * frame a field boundary or a route at whatever zoom actually fits it,
+ * rather than guessing one. Null when the features carry no coordinates at
+ * all (an empty file, or every fetch above failed). */
+export function kmlBounds(features: Feature[]): [west: number, south: number, east: number, north: number] | null {
+  const bounds: [number, number, number, number] = [Infinity, Infinity, -Infinity, -Infinity];
+  for (const feature of features) {
+    const geometry = feature.geometry;
+    if (!geometry) continue;
+    if (geometry.type === "GeometryCollection") {
+      for (const g of geometry.geometries) if ("coordinates" in g) visitCoordinates(g.coordinates, bounds);
+      continue;
+    }
+    visitCoordinates(geometry.coordinates, bounds);
+  }
+  return Number.isFinite(bounds[0]) ? bounds : null;
+}
+
+/** The center of kmlBounds -- a plain bbox center rather than an
+ * area-weighted centroid, which is all a "roughly where does this file sit"
+ * marker position needs. */
+export function kmlCenter(features: Feature[]): [lat: number, long: number] | null {
+  const bounds = kmlBounds(features);
+  if (!bounds) return null;
+  return [(bounds[1] + bounds[3]) / 2, (bounds[0] + bounds[2]) / 2];
+}
+
+/** Same bbox as kmlBounds, but over a set of image overlays' corners instead
+ * of vector features -- overlays (GroundOverlay/region placemarks) carry no
+ * Point/LineString/Polygon geometry for kmlBounds to find anything in, since
+ * fetchAllKmlFeatures excludes them entirely. Lets a caller fit the camera to
+ * an overlay-only KML attachment the same way it would a vector one. */
+export function kmlOverlayBounds(
+  overlays: { corners: OverlayCorners }[],
+): [west: number, south: number, east: number, north: number] | null {
+  if (overlays.length === 0) return null;
+  const bounds: [number, number, number, number] = [Infinity, Infinity, -Infinity, -Infinity];
+  for (const overlay of overlays) {
+    for (const [lng, lat] of overlay.corners) {
+      if (lng < bounds[0]) bounds[0] = lng;
+      if (lat < bounds[1]) bounds[1] = lat;
+      if (lng > bounds[2]) bounds[2] = lng;
+      if (lat > bounds[3]) bounds[3] = lat;
+    }
+  }
+  return bounds;
+}
+
+/** Combines two nullable bboxes (as returned by kmlBounds/kmlOverlayBounds)
+ * into the box that encloses both -- a place's KML attachment(s) can carry
+ * vector shapes and image overlays side by side, and framing the camera to
+ * just one kind would clip whichever the caller didn't ask for. Either side
+ * missing (no shapes, or no overlays) just passes the other through; both
+ * missing is null, same as either input alone would be. */
+export function unionBounds(
+  a: [west: number, south: number, east: number, north: number] | null,
+  b: [west: number, south: number, east: number, north: number] | null,
+): [west: number, south: number, east: number, north: number] | null {
+  if (!a) return b;
+  if (!b) return a;
+  return [Math.min(a[0], b[0]), Math.min(a[1], b[1]), Math.max(a[2], b[2]), Math.max(a[3], b[3])];
+}
+
+/** Same bbox-center guess as kmlCenter, but over a set of image overlays'
+ * corners instead of vector features -- useVisualData.ts's fallback for a
+ * PendingKmlPlace whose only KML attachment is a GroundOverlay (an
+ * overlay-only file: no Point/LineString/Polygon placemark for kmlCenter to
+ * find anything in, since fetchAllKmlFeatures excludes GroundOverlay
+ * placemarks entirely). Without this, a place with only an image overlay
+ * attached and no lat/long of its own never gets a derived position and so
+ * never renders on the map until someone sets its coordinates by hand
+ * (found live). */
+export function kmlOverlayCenter(overlays: { corners: OverlayCorners }[]): [lat: number, long: number] | null {
+  const bounds = kmlOverlayBounds(overlays);
+  if (!bounds) return null;
+  return [(bounds[1] + bounds[3]) / 2, (bounds[0] + bounds[2]) / 2];
+}

package/src/mapEdit/index.ts

@@ -0,0 +1,15 @@
+// @gramps-connect/story/map-edit: the map editor's model, map files and
+// geometry -- plain functions, no React or map library, shared by the
+// Story Editor and Gramps Connect's own map editor.
+export {
+  addToSession, assembleForSaving, lockPart, prepareForEditing,
+  type EditableGeometry, type EditablePart, type EditMode, type EditSession, type SavedPart,
+} from "./model";
+export {
+  IMAGE_OVERLAY_PROPERTY, isKmlLine, isKmlRegion, lineCoordsOf, mapItemToGeoJson, MEDIA_HANDLE_PREFIX, overlaySourceOfText,
+  parseMapFile, polygonRingsOf, SOURCE_PROPERTY, type ImageOverlay,
+} from "./mapFile";
+export {
+  cornersFromBox, kmlBounds, kmlCenter, kmlOverlayBounds, kmlOverlayCenter, mercatorBearing, mercatorDistance, rotatePoint,
+  scalePoint, unionBounds, type OverlayCorners,
+} from "./geometry";