@gramps-connect/story 0.3.0 → 0.5.0

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

package/src/mapEdit/model.ts

@@ -0,0 +1,250 @@
+// Turning a map file's features into what the map editor's terra-draw
+// canvas can edit, and back into features to save (as GeoJSON, see
+// mapItemToGeoJson), with nothing dropped on the way. terra-draw only
+// knows single Points, LineStrings and Polygons with 2D, at-most-9-decimal
+// coordinates, and only keeps the few properties the editor itself sets
+// (name/color/opacity) --
+// while a KML, GeoJSON or GPX file can hold multi-part shapes, arbitrary
+// properties and a GPS track's per-point times. So:
+//
+//   - a multi-part shape is split into single parts that share a group,
+//     and rejoined on save (parts whose name/colour/opacity were changed
+//     apart become separate shapes, since one KML Placemark has one style);
+//   - every other property is set aside per part and put back on save;
+//   - a track's times are kept only while its points are unchanged --
+//     reshaped, it no longer matches the recording, so it saves as a plain
+//     line;
+//   - elevations are dropped (nothing here uses them);
+//   - anything terra-draw still can't take (a polygon with holes, one that
+//     crosses itself) is "locked": shown but not editable, and saved back
+//     exactly as it was, rather than silently left out of the save.
+import type { Feature, Geometry, LineString, Point, Polygon, Position } from "geojson";
+
+/** What the editor reads and writes on each terra-draw feature itself. */
+const EDITOR_OWNED = new Set(["name", "color", "opacity"]);
+/** Parser bookkeeping with nothing worth saving: the per-point data that's
+ * carried separately (coordinateProperties), @tmcw/togeojson's GPX type tag,
+ * and a KML style reference whose <Style> doesn't come along. */
+const DROPPED = new Set(["coordinateProperties", "_gpxType", "styleUrl", "@geometry-type"]);
+
+export type EditableGeometry = Point | LineString | Polygon;
+export type EditMode = "point" | "linestring" | "polygon";
+
+/** One single-geometry part, ready for terra-draw. `sourceKey` rides on the
+ * terra-draw feature as a property so save can find what was set aside. */
+export interface EditablePart {
+  sourceKey: string;
+  mode: EditMode;
+  geometry: EditableGeometry;
+  name?: string;
+  color?: string;
+  opacity?: number;
+}
+
+interface PartSource {
+  group: string;
+  /** Position within its group, so rejoined parts keep their order. */
+  index: number;
+  extra: Record<string, unknown>;
+  /** A track part's per-point times, and the (2D, rounded) points they
+   * belong to -- kept only while the saved points still match. */
+  times?: string[];
+  coords?: Position[];
+}
+
+export interface EditSession {
+  parts: EditablePart[];
+  sources: Map<string, PartSource>;
+  /** Parts terra-draw wouldn't accept -- see lockPart. */
+  locked: Map<string, EditablePart>;
+}
+
+/** terra-draw rejects coordinates with more than 9 decimal places (its
+ * coordinatePrecision) -- well under a millimetre, so rounding loses
+ * nothing real. Also drops a third (elevation) value. */
+function round2d(position: Position): Position {
+  return [Number(position[0].toFixed(9)), Number(position[1].toFixed(9))];
+}
+
+function singleParts(geometry: Geometry): EditableGeometry[] {
+  switch (geometry.type) {
+    case "Point":
+      return [{ type: "Point", coordinates: round2d(geometry.coordinates) }];
+    case "LineString":
+      return [{ type: "LineString", coordinates: geometry.coordinates.map(round2d) }];
+    case "Polygon":
+      return [{ type: "Polygon", coordinates: geometry.coordinates.map((ring) => ring.map(round2d)) }];
+    case "MultiPoint":
+      return geometry.coordinates.map((c) => ({ type: "Point", coordinates: round2d(c) }));
+    case "MultiLineString":
+      return geometry.coordinates.map((line) => ({ type: "LineString", coordinates: line.map(round2d) }));
+    case "MultiPolygon":
+      return geometry.coordinates.map((poly) => ({ type: "Polygon", coordinates: poly.map((ring) => ring.map(round2d)) }));
+    case "GeometryCollection":
+      return geometry.geometries.flatMap(singleParts);
+  }
+}
+
+const modeOf = (geometry: EditableGeometry): EditMode =>
+  geometry.type === "Point" ? "point" : geometry.type === "LineString" ? "linestring" : "polygon";
+
+/** A feature's properties minus the editor's own and the parser's
+ * bookkeeping -- kept as they are, nested values included. */
+function extraProperties(properties: Record<string, unknown>): Record<string, unknown> {
+  const extra: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(properties)) {
+    if (EDITOR_OWNED.has(key) || DROPPED.has(key) || value === undefined || value === null) continue;
+    extra[key] = value;
+  }
+  return extra;
+}
+
+/** Each part's times, if the feature has them in @tmcw/togeojson's own
+ * shape: string[] for a LineString, string[][] for a MultiLineString. */
+function partTimes(feature: Feature, partCount: number): (string[] | undefined)[] {
+  const times = (feature.properties?.coordinateProperties as { times?: unknown } | undefined)?.times;
+  if (!Array.isArray(times) || times.length === 0) return [];
+  if (feature.geometry?.type === "LineString" && times.every((t) => typeof t === "string")) {
+    return [times as string[]];
+  }
+  if (feature.geometry?.type === "MultiLineString" && times.length === partCount && times.every(Array.isArray)) {
+    return times as string[][];
+  }
+  return [];
+}
+
+/** Splits a file's features (e.g. parseMapFile's) into
+ * editable single parts. A polygon with holes is locked from the start:
+ * terra-draw's polygon editing only knows an outer ring. */
+export function prepareForEditing(features: Feature[], firstIndex = 0): EditSession {
+  const session: EditSession = { parts: [], sources: new Map(), locked: new Map() };
+  features.forEach((feature, i) => {
+    const f = firstIndex + i;
+    if (!feature.geometry) return;
+    const properties = (feature.properties ?? {}) as Record<string, unknown>;
+    const extra = extraProperties(properties);
+    const geometries = singleParts(feature.geometry);
+    const times = partTimes(feature, geometries.length);
+    const opacityRaw = Number(properties.opacity);
+    const opacity = Number.isFinite(opacityRaw) && opacityRaw >= 0 && opacityRaw <= 1 ? opacityRaw : undefined;
+    geometries.forEach((geometry, index) => {
+      const sourceKey = `f${f}p${index}`;
+      const partTimesHere = times[index];
+      const keepTimes = geometry.type === "LineString" && partTimesHere?.length === geometry.coordinates.length;
+      session.sources.set(sourceKey, {
+        group: `f${f}`, index, extra,
+        ...(keepTimes ? { times: partTimesHere, coords: geometry.coordinates } : {}),
+      });
+      const part: EditablePart = {
+        sourceKey, mode: modeOf(geometry), geometry,
+        name: typeof properties.name === "string" ? properties.name : undefined,
+        color: typeof properties.color === "string" ? properties.color : undefined,
+        ...(geometry.type === "Polygon" ? { opacity } : {}),
+      };
+      if (geometry.type === "Polygon" && geometry.coordinates.length > 1) session.locked.set(sourceKey, part);
+      else session.parts.push(part);
+    });
+  });
+  return session;
+}
+
+/** Adds more features (a file imported while editing) after the session's
+ * own, so they save after them too. Returns the session of just the new
+ * ones, whose parts the canvas still has to take. */
+export function addToSession(session: EditSession, features: Feature[]): EditSession {
+  let next = 0;
+  for (const source of session.sources.values()) next = Math.max(next, Number(source.group.slice(1)) + 1);
+  const added = prepareForEditing(features, next);
+  session.parts.push(...added.parts);
+  for (const [key, source] of added.sources) session.sources.set(key, source);
+  for (const [key, part] of added.locked) session.locked.set(key, part);
+  return added;
+}
+
+/** Marks a part terra-draw refused to load (addFeatures' validation): it's
+ * no longer editable, and assembleForSaving writes it back unchanged. */
+export function lockPart(session: EditSession, sourceKey: string): void {
+  const index = session.parts.findIndex((part) => part.sourceKey === sourceKey);
+  if (index < 0) return;
+  session.locked.set(sourceKey, session.parts[index]);
+  session.parts.splice(index, 1);
+}
+
+/** A part as saved from the canvas: its (possibly edited) geometry and the
+ * editor's own properties, plus the sourceKey it was loaded with -- absent
+ * for a shape drawn new in this session. */
+export interface SavedPart {
+  sourceKey?: string;
+  geometry: EditableGeometry;
+  name?: string;
+  color?: string;
+  opacity?: number;
+}
+
+const samePositions = (a: Position[], b: Position[]) =>
+  a.length === b.length && a.every((p, i) => p[0] === b[i][0] && p[1] === b[i][1]);
+
+/** Joins single geometries back into one -- Multi* when they're all one
+ * kind, a GeometryCollection when mixed (what a KML MultiGeometry is). */
+function joinGeometries(geometries: EditableGeometry[]): Geometry {
+  if (geometries.length === 1) return geometries[0];
+  const kinds = new Set(geometries.map((g) => g.type));
+  if (kinds.size === 1) {
+    if (kinds.has("Point")) return { type: "MultiPoint", coordinates: geometries.map((g) => (g as Point).coordinates) };
+    if (kinds.has("LineString")) return { type: "MultiLineString", coordinates: geometries.map((g) => (g as LineString).coordinates) };
+    return { type: "MultiPolygon", coordinates: geometries.map((g) => (g as Polygon).coordinates) };
+  }
+  return { type: "GeometryCollection", geometries };
+}
+
+/** Everything to save: the canvas's parts with their set-aside data put
+ * back, multi-part shapes rejoined, and locked parts as they were loaded.
+ * Features come out in their original file order, new shapes last. */
+export function assembleForSaving(session: EditSession, saved: SavedPart[]): Feature[] {
+  interface Entry { part: SavedPart; source?: PartSource }
+  const entries: Entry[] = [
+    ...saved.map((part) => ({ part, source: part.sourceKey ? session.sources.get(part.sourceKey) : undefined })),
+    ...[...session.locked.values()].map((part) => ({ part, source: session.sources.get(part.sourceKey) })),
+  ];
+  // One bucket per original feature and style (a part restyled apart from
+  // its siblings becomes its own shape), and one per new shape.
+  const buckets = new Map<string, Entry[]>();
+  let newCount = 0;
+  for (const entry of entries) {
+    const { part, source } = entry;
+    const key = source
+      ? `${source.group}|${part.name ?? ""}|${part.color ?? ""}|${part.opacity ?? ""}`
+      : `new${newCount++}`;
+    const bucket = buckets.get(key);
+    if (bucket) bucket.push(entry);
+    else buckets.set(key, [entry]);
+  }
+  const groupOrder = (key: string) => (key.startsWith("new") ? Infinity : Number(key.slice(1, key.indexOf("|"))));
+  return [...buckets.entries()]
+    .sort(([a], [b]) => groupOrder(a) - groupOrder(b))
+    .map(([, bucket]) => {
+      bucket.sort((a, b) => (a.source?.index ?? 0) - (b.source?.index ?? 0));
+      const first = bucket[0];
+      const geometry = joinGeometries(bucket.map((e) => e.part.geometry));
+      // Times only when every line in the shape still has its own, on
+      // unchanged points -- @tmcw/togeojson's own shape for them is all of
+      // a track's segments timed or none.
+      const times = bucket.map(({ part, source }) =>
+        part.geometry.type === "LineString" && source?.times && source.coords
+          && samePositions(part.geometry.coordinates, source.coords)
+          ? source.times
+          : undefined);
+      const allTimed = bucket.every((e) => e.part.geometry.type === "LineString") && times.every(Boolean);
+      return {
+        type: "Feature",
+        geometry,
+        properties: {
+          ...(first.source?.extra ?? {}),
+          ...(first.part.color !== undefined ? { color: first.part.color } : {}),
+          ...(first.part.name ? { name: first.part.name } : {}),
+          ...(first.part.opacity !== undefined ? { opacity: first.part.opacity } : {}),
+          ...(allTimed ? { coordinateProperties: { times: bucket.length === 1 ? times[0] : times } } : {}),
+        },
+      } as Feature;
+    });
+}

package/src/player/MapBackground.tsx

@@ -182,7 +182,9 @@ export function MapBackground({ initialCenter, current, dark, colors, panelFract
     map.addLayer({
       id: FILL_LAYER, type: "fill", source: SHAPE_SOURCE,
       filter: ["==", ["geometry-type"], "Polygon"],
-      paint: { "fill-color": color, "fill-opacity": 0.25 },
+      // And its own `opacity` (what the map editor sets on an area) over
+      // a light default.
+      paint: { "fill-color": color, "fill-opacity": ["coalesce", ["to-number", ["get", "opacity"], 0.25], 0.25] },
     });
     map.addLayer({
       id: LINE_LAYER, type: "line", source: SHAPE_SOURCE,