@gramps-connect/story 0.3.0 → 0.4.0

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

@@ -0,0 +1,21 @@
+import type { Place } from "../types";
+import type { Bounds } from "../player/geo";
+import type { PlaceSearch } from "./placeSearch";
+import type { EditorStrings } from "./strings";
+export type PlaceUpdate = (place: Place | undefined) => Place | undefined;
+export interface PlaceFieldProps {
+    place: Place | undefined;
+    /** The story's other places, to reuse. */
+    choices: Place[];
+    /** Where the map looks while this place has no point. */
+    around?: Bounds | null;
+    /** The story's language: search results are named in it. */
+    language?: string;
+    /** Null hides the search. */
+    search: PlaceSearch | null;
+    dark?: boolean;
+    strings: EditorStrings;
+    /** A change, as a function of the place as it is by then. */
+    onChange: (update: PlaceUpdate, key: string) => void;
+}
+export declare function PlaceField({ place, choices, around, language, search, dark, strings, onChange }: PlaceFieldProps): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+import "maplibre-gl/dist/maplibre-gl.css";
+import type { LonLat } from "../types";
+import type { Bounds } from "../player/geo";
+export interface PlaceMapProps {
+    point: LonLat | null;
+    /** Where to look when there's no point yet. */
+    around?: Bounds | null;
+    dark?: boolean;
+    label: string;
+    onPick: (point: LonLat) => void;
+}
+export declare function PlaceMap({ point, around, dark, label, onPick }: PlaceMapProps): import("react").JSX.Element;

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 PlaceSearch } from "./placeSearch";
 import { type EditorStrings } from "./strings";
 export interface StoryEditorProps {
     /** The story to start from, and its files (paths as in media `src`).
@@ -27,7 +28,10 @@ export interface StoryEditorProps {
     playerStrings?: Partial<PlayerStrings>;
     /** Date text -> EDTF. By default gramps-date, in the story's language. */
     parseDateText?: DateTextParser;
+    /** Finding a place by name. By default Wikidata, and only when the
+     * person asks; null leaves the search out. */
+    placeSearch?: PlaceSearch | null;
 }
 /** 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, }: StoryEditorProps): import("react").JSX.Element;
+export declare function StoryEditor({ initialStory, initialFiles, onChange, prepareImage: prepare, toolbar, brand, dark, strings: stringOverrides, playerStrings, parseDateText, placeSearch, }: StoryEditorProps): import("react").JSX.Element;

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

@@ -1,8 +1,10 @@
 export { prepareImage, StoryEditor, type StoryEditorProps } from "./StoryEditor";
 export { PhotosField, type PhotosFieldProps } from "./PhotosField";
+export { PlaceField, type PlaceFieldProps, type PlaceUpdate } from "./PlaceField";
+export { searchWikidataPlaces, wikidataPoint, WIKIDATA_PLACE_SEARCH, type PlaceSearch, type PlaceSearchResult } from "./placeSearch";
 export { StoryTextField, type StoryTextFieldProps } from "./StoryTextField";
 export { SlideList, type SlideListProps } from "./SlideList";
 export { DateField, type DateFieldProps } from "./DateField";
 export { suggestEdtf, type DateTextParser } from "./dates";
 export { EDITOR_ENGLISH, type EditorStrings } from "./strings";
-export { addImage, addSlide, blankStory, COALESCE_MS, deleteSlide, duplicateSlide, findMedia, moveSlide, nextSlideId, pruneMedia, record, redo, setSlidePhotos, slideDate, startHistory, storyFileName, undo, updateMedia, updateSlide, updateStory, usedMedia, type History, type NewImage, } from "./model";
+export { addImage, addSlide, blankStory, COALESCE_MS, deleteSlide, duplicateSlide, findMedia, formatLatLon, moveSlide, nextSlideId, parseLatLon, patchPlace, pruneMedia, record, redo, roundDegrees, setSlidePhotos, slideDate, startHistory, storyFileName, storyPlaceChoices, undo, updateMedia, updateSlide, updateStory, usedMedia, type History, type NewImage, } from "./model";

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

@@ -1,4 +1,4 @@
-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 declare function blankStory(title: string, language?: string): StoryDoc;
 /** "s<n>" past every id already of that form, so it's unique however the
@@ -27,6 +27,22 @@ export declare function updateStory(doc: StoryDoc, patch: Partial<Omit<StoryDoc,
  * date at all. A new precise form drops a `sortYear` it would contradict
  * (the timeline reads sortYear first); the date's other fields stay. */
 export declare function slideDate(previous: StoryDate | undefined, text: string, edtf: string | undefined): StoryDate | undefined;
+/** 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 declare function patchPlace(place: Place | undefined, patch: Partial<Place>): Place | undefined;
+/** Degrees to 5 decimals: about a metre, and no float noise. */
+export declare const roundDegrees: (value: number) => number;
+/** "47.3769, 8.5417" (or with a space or semicolon between) -> a point;
+ * null when that's not two numbers in range. */
+export declare function parseLatLon(text: string): {
+    lat: number;
+    lon: number;
+} | null;
+export declare function formatLatLon(lat: number, lon: number): string;
+/** 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 declare function storyPlaceChoices(doc: StoryDoc, exceptIndex?: number): Place[];
 /** A prepared image to add to a story (see optimizeImage). */
 export interface NewImage {
     data: Uint8Array;

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

@@ -0,0 +1,22 @@
+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>;
+}
+export declare function searchWikidataPlaces(term: string, language?: string, signal?: AbortSignal): Promise<PlaceSearchResult[]>;
+export declare function wikidataPoint(result: PlaceSearchResult, signal?: AbortSignal): Promise<{
+    lat: number;
+    lon: number;
+} | null>;
+export declare const WIKIDATA_PLACE_SEARCH: PlaceSearch;

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

@@ -29,6 +29,21 @@ 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;
     photos: string;
     photosHint: string;
     addPhoto: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gramps-connect/story",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Read, write, validate and present .story.zip files: portable, versioned family-history stories.",
   "license": "AGPL-3.0-or-later",
   "type": "module",

package/src/editor/PlaceField.tsx

@@ -0,0 +1,160 @@
+// A slide's place: a name and a point. The point comes from clicking the
+// map, dragging the pin, typing coordinates, or a search by name (opt-in:
+// the one thing the editor sends anywhere). Picking one of the story's
+// other places gives this slide the very same place, overlays and all.
+// A place's shape and overlays aren't edited here, but are always kept.
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Autocomplete, Button, Group, Loader, Stack, Text, TextInput, Tooltip, UnstyledButton } from "@mantine/core";
+import type { Place } from "../types";
+import type { Bounds } from "../player/geo";
+import { formatLatLon, parseLatLon, patchPlace, roundDegrees } from "./model";
+import { PlaceMap } from "./PlaceMap";
+import type { PlaceSearch, PlaceSearchResult } from "./placeSearch";
+import type { EditorStrings } from "./strings";
+
+export type PlaceUpdate = (place: Place | undefined) => Place | undefined;
+
+export interface PlaceFieldProps {
+  place: Place | undefined;
+  /** The story's other places, to reuse. */
+  choices: Place[];
+  /** Where the map looks while this place has no point. */
+  around?: Bounds | null;
+  /** The story's language: search results are named in it. */
+  language?: string;
+  /** Null hides the search. */
+  search: PlaceSearch | null;
+  dark?: boolean;
+  strings: EditorStrings;
+  /** A change, as a function of the place as it is by then. */
+  onChange: (update: PlaceUpdate, key: string) => void;
+}
+
+type Found =
+  | { state: "idle" }
+  | { state: "searching" }
+  | { state: "results"; results: PlaceSearchResult[] }
+  | { state: "message"; message: string };
+
+export function PlaceField({ place, choices, around, language, search, dark, strings, onChange }: PlaceFieldProps) {
+  const lat = place?.lat;
+  const lon = place?.lon;
+  const point = lat !== undefined && lon !== undefined ? ([lon, lat] as [number, number]) : null;
+  const name = place?.name ?? "";
+
+  // The coordinates as typed, until they're a point; then as the point is.
+  const [coords, setCoords] = useState(point ? formatLatLon(point[1], point[0]) : "");
+  useEffect(() => {
+    setCoords((typed) => {
+      const parsed = parseLatLon(typed);
+      if (lat === undefined || lon === undefined) return parsed ? "" : typed;
+      return parsed && parsed.lat === lat && parsed.lon === lon ? typed : formatLatLon(lat, lon);
+    });
+  }, [lat, lon]);
+  const coordsInvalid = coords.trim() !== "" && !parseLatLon(coords);
+
+  const [found, setFound] = useState<Found>({ state: "idle" });
+  const searching = useRef<AbortController | null>(null);
+  useEffect(() => () => searching.current?.abort(), []);
+  const find = async () => {
+    if (!search || !name.trim()) return;
+    searching.current?.abort();
+    const controller = new AbortController();
+    searching.current = controller;
+    setFound({ state: "searching" });
+    try {
+      const results = await search.search(name.trim(), language, controller.signal);
+      setFound(results.length ? { state: "results", results } : { state: "message", message: strings.findPlaceNone });
+    } catch {
+      if (!controller.signal.aborted) setFound({ state: "message", message: strings.findPlaceFailed });
+    }
+  };
+  const choose = async (result: PlaceSearchResult) => {
+    if (!search) return;
+    searching.current?.abort();
+    const controller = new AbortController();
+    searching.current = controller;
+    setFound({ state: "searching" });
+    try {
+      const at = await search.point(result, controller.signal);
+      if (!at) {
+        setFound({ state: "message", message: strings.findPlaceNoPoint(result.label) });
+        return;
+      }
+      setFound({ state: "idle" });
+      onChange((p) => patchPlace(p, { name: result.label, lat: roundDegrees(at.lat), lon: roundDegrees(at.lon) }), "place");
+    } catch {
+      if (!controller.signal.aborted) setFound({ state: "message", message: strings.findPlaceFailed });
+    }
+  };
+
+  const byName = useMemo(() => new Map(choices.map((c) => [c.name!.trim(), c])), [choices]);
+  const keeps = [
+    place?.geometry ? strings.placeShape : null,
+    place?.overlays?.length ? strings.placeOverlays(place.overlays.length) : null,
+  ].filter(Boolean);
+
+  return (
+    <Stack gap="xs">
+      <Group justify="space-between">
+        <Text size="sm" fw={500}>{strings.place}</Text>
+        {place && (
+          <Button variant="subtle" size="compact-xs" color="red" onClick={() => { setFound({ state: "idle" }); onChange(() => undefined, "place"); }}>
+            {strings.removePlace}
+          </Button>
+        )}
+      </Group>
+      <Group gap="xs" align="flex-end" wrap="nowrap">
+        <Autocomplete
+          size="xs" label={strings.placeName} style={{ flex: 1 }} value={name}
+          data={[...byName.keys()]}
+          comboboxProps={{ withinPortal: true }}
+          onChange={(value) => onChange((p) => patchPlace(p, { name: value || undefined }), "place:name")}
+          onOptionSubmit={(value) => {
+            const chosen = byName.get(value);
+            if (chosen) onChange(() => structuredClone(chosen), "place");
+          }}
+        />
+        {search && (
+          <Tooltip label={strings.findPlaceHint} multiline w={260}>
+            <Button variant="default" size="xs" disabled={!name.trim() || found.state === "searching"} onClick={() => void find()}>
+              {strings.findPlace}
+            </Button>
+          </Tooltip>
+        )}
+      </Group>
+      {found.state === "searching" && <Loader size="xs" />}
+      {found.state === "message" && <Text size="xs" c="dimmed" role="status">{found.message}</Text>}
+      {found.state === "results" && (
+        <Stack gap={2} role="list" aria-label={strings.findPlace}>
+          {found.results.map((result) => (
+            <UnstyledButton
+              key={result.id} role="listitem" onClick={() => void choose(result)}
+              style={{ padding: "4px 8px", borderRadius: 4, border: "1px solid var(--mantine-color-default-border)" }}
+            >
+              <Text size="sm">{result.label}</Text>
+              {result.description && <Text size="xs" c="dimmed">{result.description}</Text>}
+            </UnstyledButton>
+          ))}
+        </Stack>
+      )}
+      <TextInput
+        size="xs" label={strings.coordinates} placeholder={strings.coordinatesHint} w={260} value={coords}
+        error={coordsInvalid ? strings.coordinatesInvalid : undefined}
+        onChange={(e) => {
+          const text = e.currentTarget.value;
+          setCoords(text);
+          const parsed = parseLatLon(text);
+          if (!text.trim()) onChange((p) => patchPlace(p, { lat: undefined, lon: undefined }), "place:point");
+          else if (parsed) onChange((p) => patchPlace(p, parsed), "place:point");
+        }}
+      />
+      <PlaceMap
+        point={point} around={around} dark={dark} label={strings.placeMap}
+        onPick={([pickedLon, pickedLat]) => onChange((p) => patchPlace(p, { lat: pickedLat, lon: pickedLon }), "place:point")}
+      />
+      <Text size="xs" c="dimmed">{strings.placeMapHint}</Text>
+      {keeps.length > 0 && <Text size="xs" c="dimmed">{strings.placeKeeps(keeps.join(", "))}</Text>}
+    </Stack>
+  );
+}

package/src/editor/PlaceMap.tsx

@@ -0,0 +1,88 @@
+// A small map for setting a place's point: click to put the pin there,
+// drag the pin to move it. It starts at the point, or (with none yet) at
+// the story's other places, or the whole world.
+import { useEffect, useRef } from "react";
+import * as maplibregl from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import type { Map as MapLibreMap, Marker as MapLibreMarker } from "maplibre-gl";
+import type { LonLat } from "../types";
+import type { Bounds } from "../player/geo";
+import { mapStyleUrl } from "../player/mapStyles";
+import { defaultColors, PIN_PATH_D } from "../player/theme";
+import { roundDegrees } from "./model";
+
+export interface PlaceMapProps {
+  point: LonLat | null;
+  /** Where to look when there's no point yet. */
+  around?: Bounds | null;
+  dark?: boolean;
+  label: string;
+  onPick: (point: LonLat) => void;
+}
+
+export function PlaceMap({ point, around, dark = false, label, onPick }: PlaceMapProps) {
+  const container = useRef<HTMLDivElement>(null);
+  const mapRef = useRef<MapLibreMap | null>(null);
+  const markerRef = useRef<MapLibreMarker | null>(null);
+  const onPickRef = useRef(onPick);
+  onPickRef.current = onPick;
+  const pick = (lngLat: { lng: number; lat: number }) => onPickRef.current([roundDegrees(lngLat.lng), roundDegrees(lngLat.lat)]);
+  // The first point and surroundings only: moving is the effect below.
+  const start = useRef({ point, around });
+
+  useEffect(() => {
+    if (!container.current) return;
+    const { point: first, around: box } = start.current;
+    const map = new maplibregl.Map({
+      container: container.current,
+      style: mapStyleUrl(dark, null),
+      ...(first ? { center: first, zoom: 9 } : box ? { bounds: box, fitBoundsOptions: { padding: 30, maxZoom: 9 } } : { center: [10, 30], zoom: 0.5 }),
+      attributionControl: { compact: true },
+      // Scrolling the form past the map shouldn't zoom it.
+      cooperativeGestures: true,
+    });
+    map.addControl(new maplibregl.NavigationControl({ showCompass: false }), "top-right");
+    map.getCanvas().style.cursor = "crosshair";
+    map.on("click", (e) => pick(e.lngLat));
+    mapRef.current = map;
+    return () => {
+      markerRef.current?.remove();
+      markerRef.current = null;
+      map.remove();
+      mapRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [dark]);
+
+  // The pin follows the point, however it changed; the view follows only
+  // when the pin would be out of sight.
+  useEffect(() => {
+    const map = mapRef.current;
+    if (!map) return;
+    if (!point) {
+      markerRef.current?.remove();
+      markerRef.current = null;
+      return;
+    }
+    if (!markerRef.current) {
+      const el = document.createElement("div");
+      const c = defaultColors(dark);
+      el.innerHTML = `<svg viewBox="0 0 24 24" width="28" height="28" style="display:block;cursor:grab">`
+        + `<path d="${PIN_PATH_D}" fill="${c.mark}" stroke="${c.surface}" stroke-width="1.5" /></svg>`;
+      const marker = new maplibregl.Marker({ element: el, anchor: "bottom", draggable: true }).setLngLat(point).addTo(map);
+      marker.on("dragend", () => pick(marker.getLngLat()));
+      markerRef.current = marker;
+    } else {
+      markerRef.current.setLngLat(point);
+    }
+    if (!map.getBounds().contains(point)) map.easeTo({ center: point, zoom: Math.max(map.getZoom(), 8) });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [point?.[0], point?.[1], dark]);
+
+  return (
+    <div
+      ref={container} role="application" aria-label={label}
+      style={{ height: 240, borderRadius: 6, overflow: "hidden", border: "1px solid var(--mantine-color-default-border)" }}
+    />
+  );
+}

package/src/editor/StoryEditor.tsx

@@ -14,15 +14,18 @@ import { useMediaQuery } from "@mantine/hooks";
 import type { MediaItem, Slide, SlideMedia, StoryDoc } from "../types";
 import { optimizeImage } from "../image";
 import { validate, type StoryIssue } from "../validate";
+import { storyPlaces } from "../player/geo";
 import { StoryPlayer } from "../player/StoryPlayer";
 import type { PlayerStrings } from "../player/strings";
 import { suggestEdtf, type DateTextParser } from "./dates";
 import { DateField } from "./DateField";
 import {
-  addImage, addSlide, deleteSlide, findMedia, duplicateSlide, moveSlide, record, redo, setSlidePhotos, startHistory, undo, updateMedia,
-  updateSlide, updateStory, type History, type NewImage,
+  addImage, addSlide, deleteSlide, findMedia, duplicateSlide, moveSlide, record, redo, setSlidePhotos, startHistory, storyPlaceChoices,
+  undo, updateMedia, updateSlide, updateStory, type History, type NewImage,
 } from "./model";
 import { PhotosField } from "./PhotosField";
+import { PlaceField, type PlaceUpdate } from "./PlaceField";
+import { WIKIDATA_PLACE_SEARCH, type PlaceSearch } from "./placeSearch";
 import { SlideList } from "./SlideList";
 import { StoryTextField } from "./StoryTextField";
 import { EDITOR_ENGLISH, type EditorStrings } from "./strings";
@@ -54,6 +57,9 @@ export interface StoryEditorProps {
   playerStrings?: Partial<PlayerStrings>;
   /** Date text -> EDTF. By default gramps-date, in the story's language. */
   parseDateText?: DateTextParser;
+  /** Finding a place by name. By default Wikidata, and only when the
+   * person asks; null leaves the search out. */
+  placeSearch?: PlaceSearch | null;
 }
 
 /** The slide an issue's JSON Pointer is about, or STORY. */
@@ -92,7 +98,7 @@ function Thumb({ doc, slide, resolveMedia }: { doc: StoryDoc; slide: Slide; reso
 
 export function StoryEditor({
   initialStory, initialFiles, onChange, prepareImage: prepare = prepareImage, toolbar, brand, dark = false,
-  strings: stringOverrides, playerStrings, parseDateText = suggestEdtf,
+  strings: stringOverrides, playerStrings, parseDateText = suggestEdtf, placeSearch = WIKIDATA_PLACE_SEARCH,
 }: StoryEditorProps) {
   const strings = useMemo(() => ({ ...EDITOR_ENGLISH, ...stringOverrides }), [stringOverrides]);
   const [history, setHistory] = useState<History>(() => startHistory(initialStory));
@@ -141,6 +147,20 @@ export function StoryEditor({
     if (index !== STORY) apply(updateSlide(history.present, index, patch), `${slide!.id}:${key}`);
   };
 
+  // A place change applies to the slide as it is by then: a name typed and
+  // a place picked in the same moment both land.
+  const setPlace = (slideId: string, update: PlaceUpdate, key: string) => {
+    setHistory((h) => {
+      const at = h.present.slides.findIndex((s) => s.id === slideId);
+      if (at < 0) return h;
+      const before = h.present.slides[at].place;
+      const after = update(before);
+      return after === before ? h : record(h, updateSlide(h.present, at, { place: after }), `${slideId}:${key}`);
+    });
+  };
+  const placeChoices = useMemo(() => storyPlaceChoices(doc, index), [doc, index]);
+  const around = useMemo(() => storyPlaces(doc.slides.map((s) => s.place))?.bounds ?? null, [doc.slides]);
+
   const issues = useMemo(() => validate(doc, files).errors, [doc, files]);
 
   /** Prepares image files and puts them on a slide: added at the end, or
@@ -277,17 +297,10 @@ export function StoryEditor({
         label={strings.text} value={slide.text ?? ""} boldLabel={strings.bold} italicLabel={strings.italic} minRows={5}
         onChange={(text) => setSlide({ text: text || undefined }, "text")}
       />
-      {slide.place && (
-        <Stack gap={2}>
-          <Text size="sm" fw={500}>{strings.place}</Text>
-          <Text size="sm">
-            {slide.place.name ?? ""}
-            {slide.place.lat !== undefined && slide.place.lon !== undefined && (
-              <Text span c="dimmed" size="sm"> {slide.place.lat.toFixed(4)}, {slide.place.lon.toFixed(4)}</Text>
-            )}
-          </Text>
-        </Stack>
-      )}
+      <PlaceField
+        place={slide.place} choices={placeChoices} around={around} language={doc.language} search={placeSearch} dark={dark} strings={strings}
+        onChange={(update, key) => setPlace(slide.id, update, key)}
+      />
       <PhotosField
         photos={slide.media ?? []} media={doc.media} urlFor={urlFor} strings={strings} busy={busy}
         onChange={(photos, key) => apply(setSlidePhotos(doc, index, photos), `${slide.id}:${key}`)}

package/src/editor/index.ts

@@ -1,12 +1,15 @@
 export { prepareImage, StoryEditor, type StoryEditorProps } from "./StoryEditor";
 export { PhotosField, type PhotosFieldProps } from "./PhotosField";
+export { PlaceField, type PlaceFieldProps, type PlaceUpdate } from "./PlaceField";
+export { searchWikidataPlaces, wikidataPoint, WIKIDATA_PLACE_SEARCH, type PlaceSearch, type PlaceSearchResult } from "./placeSearch";
 export { StoryTextField, type StoryTextFieldProps } from "./StoryTextField";
 export { SlideList, type SlideListProps } from "./SlideList";
 export { DateField, type DateFieldProps } from "./DateField";
 export { suggestEdtf, type DateTextParser } from "./dates";
 export { EDITOR_ENGLISH, type EditorStrings } from "./strings";
 export {
-  addImage, addSlide, blankStory, COALESCE_MS, deleteSlide, duplicateSlide, findMedia, moveSlide, nextSlideId, pruneMedia, record, redo,
-  setSlidePhotos, slideDate, startHistory, storyFileName, undo, updateMedia, updateSlide, updateStory, usedMedia,
+  addImage, addSlide, blankStory, COALESCE_MS, deleteSlide, duplicateSlide, findMedia, formatLatLon, moveSlide, nextSlideId, parseLatLon,
+  patchPlace, pruneMedia, record, redo, roundDegrees, setSlidePhotos, slideDate, startHistory, storyFileName, storyPlaceChoices, undo,
+  updateMedia, updateSlide, updateStory, usedMedia,
   type History, type NewImage,
 } from "./model";

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