@gramps-connect/story 0.4.0 → 0.5.0

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";

package/src/mapEdit/mapFile.ts

@@ -0,0 +1,199 @@
+// Reading and writing map files: KML, GPX and GeoJSON in (read into GeoJSON
+// features, with each format's own colours where they're reliable), and
+// GeoJSON out, with image overlays as Polygon features marked
+// IMAGE_OVERLAY_PROPERTY. A GeoJSON overlay's `image` names its picture;
+// read back, it becomes the same feature @tmcw/togeojson makes of a KML
+// GroundOverlay, with the picture behind MEDIA_HANDLE_PREFIX. Moved here
+// from Gramps Connect (kmlMedia.ts and mapFileWrite.ts), which shares it
+// with the Story Editor. GPX and KML need a DOMParser (a browser, or jsdom).
+//
+// GeoJSON keeps every property as JSON and multi-part shapes as they are,
+// with no format translation to lose anything in; a GPS track's per-point
+// times ride along in `coordinateProperties.times`, the same place
+// @tmcw/togeojson's GPX/KML readers put them.
+import type { Feature, FeatureCollection, GeoJsonObject, Geometry, Position } from "geojson";
+import { gpx, kml } from "@tmcw/togeojson";
+import type { OverlayCorners } from "./geometry";
+
+/** An image overlay's picture, as a Media handle behind this marker (not a
+ * real URL: an app-internal reference, since a resolvable link would need
+ * an expiring auth token baked in) -- in a KML GroundOverlay's href, and
+ * what asGroundOverlay makes of a GeoJSON one's `image`. */
+export const MEDIA_HANDLE_PREFIX = "media-handle:";
+
+/** A GeoJSON or GPX file's own colours, in the simplestyle convention
+ * (`stroke`/`fill`/`fill-opacity`/`marker-color`, which both GeoJSON tools
+ * and @tmcw/togeojson's gpx() use), copied onto the `color`/`opacity`
+ * properties every map layer actually reads (see MapCanvas.tsx's
+ * KML_FILL_LAYER). Fills only what's missing, so an explicit `color` wins.
+ * Not applied to KML: Gramps Connect's own KML carries `color` already, and
+ * leaving foreign KML alone keeps every existing overlay looking the same. */
+function applySimplestyle(feature: Feature): Feature {
+  const props = feature.properties ?? {};
+  const isRegion = feature.geometry?.type === "Polygon" || feature.geometry?.type === "MultiPolygon";
+  const color = props.color ?? (isRegion ? props.fill ?? props.stroke : props.stroke ?? props["marker-color"]);
+  const opacity = props.opacity ?? (isRegion ? props["fill-opacity"] : undefined);
+  if (color === props.color && opacity === props.opacity) return feature;
+  return { ...feature, properties: { ...props, color, opacity } };
+}
+
+/** A GeoJSON file's features: a FeatureCollection, a single Feature or a
+ * bare Geometry are all valid GeoJSON documents. */
+function geoJsonFeatures(doc: GeoJsonObject): Feature<Geometry | null>[] {
+  if (doc.type === "FeatureCollection") return (doc as { features?: Feature<Geometry | null>[] }).features ?? [];
+  if (doc.type === "Feature") return [doc as Feature<Geometry | null>];
+  return [{ type: "Feature", geometry: doc as Geometry, properties: {} }];
+}
+
+/** Gramps Connect's GeoJSON image overlay (see mapItemToGeoJson), turned into
+ * the same feature @tmcw/togeojson makes of a KML <gx:LatLonQuad>
+ * GroundOverlay -- so fetchAllKmlImageOverlays and everything that skips
+ * overlays read both formats the same way. */
+function asGroundOverlay(feature: Feature): Feature {
+  const props = feature.properties ?? {};
+  if (props[IMAGE_OVERLAY_PROPERTY] !== true || typeof props.image !== "string") return feature;
+  const { [IMAGE_OVERLAY_PROPERTY]: _marker, image, ...rest } = props;
+  return {
+    ...feature,
+    properties: { ...rest, "@geometry-type": "groundoverlay", icon: `${MEDIA_HANDLE_PREFIX}${image}` },
+  };
+}
+
+/** A map file's text, as GeoJSON features. The format is read off the
+ * content (GeoJSON is JSON; GPX and KML differ by root element) rather
+ * than the media object's stored mime, which a file attached by another
+ * client may not have set to anything Gramps Connect recognizes. Throws on
+ * unparseable text; features with no geometry are dropped -- a KML
+ * Placemark without Point/LineString/Polygon (see @tmcw/togeojson's
+ * KMLOptions.skipNullGeometry), or a GeoJSON Feature with `geometry: null`,
+ * is of no use to a caller here, so dropped rather than threaded through
+ * as `Feature<Geometry | null>` everywhere downstream. */
+export function parseMapFile(text: string): Feature[] {
+  const hasGeometry = (f: Feature<Geometry | null>): f is Feature => f.geometry != null;
+  if (text.trimStart().startsWith("{")) {
+    return geoJsonFeatures(JSON.parse(text) as GeoJsonObject).filter(hasGeometry).map(asGroundOverlay).map(applySimplestyle);
+  }
+  const dom = new DOMParser().parseFromString(text, "text/xml");
+  if (dom.documentElement.localName === "gpx") {
+    return gpx(dom).features.filter(hasGeometry).map(applySimplestyle);
+  }
+  return kml(dom).features.filter(hasGeometry);
+}
+
+/** An overlay file's SOURCE_PROPERTY, if it's GeoJSON that has one. */
+export function overlaySourceOfText(text: string): string | undefined {
+  if (!text.trimStart().startsWith("{")) return undefined;
+  try {
+    const source = (JSON.parse(text) as Record<string, unknown>)[SOURCE_PROPERTY];
+    return typeof source === "string" ? source : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Every Polygon ring inside `feature` -- itself (a plain Polygon), or each
+ * Polygon sub-geometry of a GeometryCollection. A country-level Wikidata/
+ * Commons outline (e.g. the United States) is often a disjoint shape --
+ * islands/territories a single Polygon ring can't express -- unlike a
+ * state's simpler single-ring Polygon. A KML file stores one as a
+ * <MultiGeometry> of several <Polygon>s, and @tmcw/togeojson reads *any* multi-child
+ * Placemark geometry back as a GeometryCollection (never reconstituting
+ * MultiPolygon) -- so that's the shape that actually reaches here, not
+ * "MultiPolygon" itself (confirmed live, 2026-09-09, round-tripping a
+ * synthetic MultiPolygon through both libraries). A non-Polygon sub-geometry
+ * (there shouldn't be one -- Gramps Connect never writes anything else into a
+ * region's own Placemark) is simply skipped rather than failing the whole
+ * feature. `[]` for anything else (a Point, a bare LineString route, ...),
+ * meaning "not a region" to every caller below. */
+export function polygonRingsOf(feature: Feature): Position[][] {
+  if (feature.geometry?.type === "Polygon") return [feature.geometry.coordinates[0]];
+  if (feature.geometry?.type === "GeometryCollection") {
+    return feature.geometry.geometries.filter((g) => g.type === "Polygon").map((g) => g.coordinates[0]);
+  }
+  return [];
+}
+
+/** True for a feature fetchAllKmlRegions/MapCanvas.tsx's own shapes effect
+ * both treat as one drawable/controllable region -- see polygonRingsOf.
+ * Exported so MapCanvas.tsx's key/hidden/opacity stamping can use the exact
+ * same test fetchAllKmlRegions does: the two must never drift, or a row's
+ * key stops matching the feature it's meant to control -- found live as a
+ * place whose outline drew on the map (MapLibre's GeoJSON source splits a
+ * GeometryCollection into one sub-feature per geometry before rendering,
+ * each individually typed "Polygon") but never showed up in
+ * OverlayLayersPanel.tsx's list. */
+export function isKmlRegion(feature: Feature): boolean {
+  return polygonRingsOf(feature).length > 0;
+}
+
+/** Every vertex of `feature` if it's a line: a LineString, a MultiLineString
+ * (a GPX track with several segments) or a GeometryCollection of only
+ * LineStrings (how @tmcw/togeojson reads a KML MultiGeometry -- see
+ * polygonRingsOf). `[]` for anything else, meaning "not a line". */
+export function lineCoordsOf(feature: Feature): Position[] {
+  const geometry = feature.geometry;
+  if (geometry?.type === "LineString") return geometry.coordinates;
+  if (geometry?.type === "MultiLineString") return geometry.coordinates.flat();
+  if (geometry?.type === "GeometryCollection" && geometry.geometries.length > 0
+    && geometry.geometries.every((g) => g.type === "LineString")) {
+    return geometry.geometries.flatMap((g) => (g.type === "LineString" ? g.coordinates : []));
+  }
+  return [];
+}
+
+/** True for a feature fetchAllKmlLines lists and MapCanvas.tsx's shapes
+ * effect lets the panel hide/dim -- shared for the same reason as
+ * isKmlRegion: the two must never drift apart. A region is never a line. */
+export function isKmlLine(feature: Feature): boolean {
+  return !isKmlRegion(feature) && lineCoordsOf(feature).length > 0;
+}
+
+/** An image overlay, as MapItemEditorDialog.tsx tracks one -- always 4
+ * explicit world corners; see kmlMedia.ts's KmlImageOverlay, which this
+ * mirrors on the write side. */
+export interface ImageOverlay {
+  handle: string;
+  corners: OverlayCorners;
+  name?: string;
+  opacity?: number;
+  order?: number;
+}
+
+/** The property marking a feature as an image overlay rather than a shape:
+ * its Polygon is the image's 4 corners (top-left, top-right, bottom-right,
+ * bottom-left, closed), and `image` is the picture's Media handle. This
+ * app's own convention -- plain GeoJSON has no image overlays -- read back
+ * by parseMapFile. */
+export const IMAGE_OVERLAY_PROPERTY = "gramps:image-overlay";
+
+function overlayFeature(overlay: ImageOverlay): Feature {
+  const ring = [...overlay.corners, overlay.corners[0]];
+  return {
+    type: "Feature",
+    geometry: { type: "Polygon", coordinates: [ring] },
+    properties: {
+      [IMAGE_OVERLAY_PROPERTY]: true,
+      image: overlay.handle,
+      ...(overlay.name ? { name: overlay.name } : {}),
+      ...(overlay.opacity !== undefined && overlay.opacity !== 1 ? { opacity: overlay.opacity } : {}),
+      ...(overlay.order !== undefined ? { order: overlay.order } : {}),
+    },
+  };
+}
+
+/** Records which Media object an overlay was made from (mapOverlays.ts) --
+ * a "foreign member" of the FeatureCollection, which GeoJSON allows. */
+export const SOURCE_PROPERTY = "gramps:source";
+
+/** Every shape plus every image overlay, as one GeoJSON FeatureCollection.
+ * Overlays go last: kmlMedia.ts's region/line row indexes count every
+ * feature in the file but MapCanvas.tsx's leave overlays out, and the two
+ * only agree while no overlay comes before a shape. */
+export function mapItemToGeoJson(features: Feature[], overlays: ImageOverlay[] = [], source?: string): string {
+  const collection: FeatureCollection & { [SOURCE_PROPERTY]?: string } = {
+    type: "FeatureCollection",
+    ...(source ? { [SOURCE_PROPERTY]: source } : {}),
+    features: [...features, ...overlays.map(overlayFeature)],
+  };
+  return JSON.stringify(collection);
+}