@gramps-connect/story 0.4.0 → 0.5.0

package/dist/types/editor/StoryEditor.d.ts

@@ -3,6 +3,7 @@ import type { StoryDoc } from "../types";
 import type { PlayerStrings } from "../player/strings";
 import { type DateTextParser } from "./dates";
 import { type NewImage } from "./model";
+import type { MapEditorStrings } from "./mapEditorStrings";
 import { type PlaceSearch } from "./placeSearch";
 import { type EditorStrings } from "./strings";
 export interface StoryEditorProps {
@@ -31,7 +32,9 @@ export interface StoryEditorProps {
     /** Finding a place by name. By default Wikidata, and only when the
      * person asks; null leaves the search out. */
     placeSearch?: PlaceSearch | null;
+    /** The map editor's words (Edit map), over its English. */
+    mapStrings?: Partial<MapEditorStrings>;
 }
 /** The default prepareImage. */
 export declare function prepareImage(file: Blob): Promise<NewImage>;
-export declare function StoryEditor({ initialStory, initialFiles, onChange, prepareImage: prepare, toolbar, brand, dark, strings: stringOverrides, playerStrings, parseDateText, placeSearch, }: StoryEditorProps): import("react").JSX.Element;
+export declare function StoryEditor({ initialStory, initialFiles, onChange, prepareImage: prepare, toolbar, brand, dark, strings: stringOverrides, playerStrings, parseDateText, placeSearch, mapStrings, }: StoryEditorProps): import("react").JSX.Element;

package/dist/types/editor/index.d.ts

@@ -1,6 +1,10 @@
 export { prepareImage, StoryEditor, type StoryEditorProps } from "./StoryEditor";
+export { MapEditor, MapEditorHelp, type MapEditorHandle, type MapEditorOverlay, type MapEditorProps, type MapEditorResult, type MapEditorStatus, } from "./MapEditor";
+export { MAP_EDITOR_ENGLISH, type MapEditorStrings } from "./mapEditorStrings";
 export { PhotosField, type PhotosFieldProps } from "./PhotosField";
 export { PlaceField, type PlaceFieldProps, type PlaceUpdate } from "./PlaceField";
+export { PlaceMapDialog, type PlaceMapDialogProps } from "./PlaceMapDialog";
+export { editorToPlace, placeFeatures, placeToEditor } from "./placeShapes";
 export { searchWikidataPlaces, wikidataPoint, WIKIDATA_PLACE_SEARCH, type PlaceSearch, type PlaceSearchResult } from "./placeSearch";
 export { StoryTextField, type StoryTextFieldProps } from "./StoryTextField";
 export { SlideList, type SlideListProps } from "./SlideList";

package/dist/types/editor/mapEditorStrings.d.ts

@@ -0,0 +1,50 @@
+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;
+    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 declare const MAP_EDITOR_ENGLISH: MapEditorStrings;

package/dist/types/editor/placeShapes.d.ts

@@ -0,0 +1,13 @@
+import type { Feature } from "geojson";
+import type { Place, StoryDate } from "../types";
+import type { MapEditorOverlay, MapEditorResult } from "./MapEditor";
+/** The features in a place's `geometry`, whichever form it takes. */
+export declare function placeFeatures(place: Place | undefined): Feature[];
+/** What the map editor opens with for a place. */
+export declare function placeToEditor(place: Place | undefined): {
+    features: Feature[];
+    overlays: MapEditorOverlay[];
+};
+/** The place with what the map editor ended with. `dates` holds each
+ * overlay's date by media key, as edited beside the editor. */
+export declare function editorToPlace(place: Place | undefined, result: MapEditorResult, dates: Map<string, StoryDate | undefined>): Place | undefined;

package/dist/types/editor/strings.d.ts

@@ -44,6 +44,19 @@ export interface EditorStrings {
     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;

package/dist/types/mapEdit/geometry.d.ts

@@ -0,0 +1,91 @@
+import type { Feature } 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]];
+/** 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 declare function rotatePoint(point: [number, number], center: [number, number], rotationDeg: number): [number, number];
+/** 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 declare function scalePoint(point: [number, number], center: [number, number], scale: number): [number, number];
+/** 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 declare function mercatorDistance(a: [number, number], b: [number, number]): number;
+/** 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 declare function mercatorBearing(from: [number, number], to: [number, number]): number;
+/** 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 declare function cornersFromBox(box: {
+    north: number;
+    south: number;
+    east: number;
+    west: number;
+    rotation: number;
+}): OverlayCorners;
+/** 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 declare function kmlBounds(features: Feature[]): [west: number, south: number, east: number, north: number] | 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 declare function kmlCenter(features: Feature[]): [lat: number, long: number] | null;
+/** 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 declare function kmlOverlayBounds(overlays: {
+    corners: OverlayCorners;
+}[]): [west: number, south: number, east: number, north: number] | null;
+/** 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 declare 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;
+/** 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 declare function kmlOverlayCenter(overlays: {
+    corners: OverlayCorners;
+}[]): [lat: number, long: number] | null;

package/dist/types/mapEdit/index.d.ts

@@ -0,0 +1,3 @@
+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/dist/types/mapEdit/mapFile.d.ts

@@ -0,0 +1,77 @@
+import type { Feature, Position } from "geojson";
+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 declare const MEDIA_HANDLE_PREFIX = "media-handle:";
+/** 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 declare function parseMapFile(text: string): Feature[];
+/** An overlay file's SOURCE_PROPERTY, if it's GeoJSON that has one. */
+export declare function overlaySourceOfText(text: string): string | 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 declare function polygonRingsOf(feature: Feature): Position[][];
+/** 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 declare function isKmlRegion(feature: Feature): boolean;
+/** 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 declare function lineCoordsOf(feature: Feature): Position[];
+/** 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 declare function isKmlLine(feature: Feature): boolean;
+/** 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 declare const IMAGE_OVERLAY_PROPERTY = "gramps:image-overlay";
+/** Records which Media object an overlay was made from (mapOverlays.ts) --
+ * a "foreign member" of the FeatureCollection, which GeoJSON allows. */
+export declare 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 declare function mapItemToGeoJson(features: Feature[], overlays?: ImageOverlay[], source?: string): string;

package/dist/types/mapEdit/model.d.ts

@@ -0,0 +1,55 @@
+import type { Feature, LineString, Point, Polygon, Position } from "geojson";
+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>;
+}
+/** 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 declare function prepareForEditing(features: Feature[], firstIndex?: number): EditSession;
+/** 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 declare function addToSession(session: EditSession, features: Feature[]): EditSession;
+/** Marks a part terra-draw refused to load (addFeatures' validation): it's
+ * no longer editable, and assembleForSaving writes it back unchanged. */
+export declare function lockPart(session: EditSession, sourceKey: string): void;
+/** 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;
+}
+/** 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 declare function assembleForSaving(session: EditSession, saved: SavedPart[]): Feature[];
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gramps-connect/story",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Read, write, validate and present .story.zip files: portable, versioned family-history stories.",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -36,6 +36,11 @@
       "types": "./dist/types/editor/index.d.ts",
       "default": "./dist/editor.js"
     },
+    "./map-edit": {
+      "source": "./src/mapEdit/index.ts",
+      "types": "./dist/types/mapEdit/index.d.ts",
+      "default": "./dist/map-edit.js"
+    },
     "./embed": "./dist/embed.js",
     "./schema/1.0": "./spec/1.0/story.schema.json",
     "./package.json": "./package.json"
@@ -65,6 +70,7 @@
   "dependencies": {
     "@gramps-connect/gramps-date": "^0.1.0",
     "@openhistoricalmap/maplibre-gl-dates": "^1.4.0",
+    "@tmcw/togeojson": "^7.1.2",
     "fflate": "^0.8.3"
   },
   "devDependencies": {
@@ -80,6 +86,8 @@
     "playwright-core": "^1.64.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "terra-draw": "^1.32.3",
+    "terra-draw-maplibre-gl-adapter": "^1.4.1",
     "tsx": "^4.23.5",
     "typescript": "^7.0.2"
   },
@@ -88,7 +96,9 @@
     "@mantine/hooks": "^8",
     "maplibre-gl": ">=5",
     "react": "^18.2 || ^19",
-    "react-dom": "^18.2 || ^19"
+    "react-dom": "^18.2 || ^19",
+    "terra-draw": "^1.32.3",
+    "terra-draw-maplibre-gl-adapter": "^1.4.1"
   },
   "peerDependenciesMeta": {
     "@mantine/core": {
@@ -105,6 +115,12 @@
     },
     "react-dom": {
       "optional": true
+    },
+    "terra-draw": {
+      "optional": true
+    },
+    "terra-draw-maplibre-gl-adapter": {
+      "optional": true
     }
   }
 }