@projektemacher/storymapjs 0.10.7 → 0.11.0

package/src/map/Map.ts

@@ -4,8 +4,11 @@ import Dom from "../dom/Dom";
 import { Browser } from "../core/Browser";
 import type { Map as OlMap } from "ol";
 import type { Tile as TileLayer, Vector as VectorLayer } from "ol/layer";
+import type Layer from "ol/layer/Layer";
 import type OverviewMap from "ol/control/OverviewMap";
 import type MapMarker from "./MapMarker";
+import type { MarkerEventPayload } from "./MapMarker";
+import type { ImagereadyPayload } from "./openlayers/Map.OpenLayers";
 import type { LinePoint, ViewToOptions } from "./types";
 import type {
     AnimationHandle,
@@ -25,6 +28,21 @@ import type {
 
 ================================================ */
 
+export interface MapEvents {
+    change: { current_marker: number };
+    loaded: StorymapData;
+    added: StorymapData;
+    removed: StorymapData;
+    markerAdded: MapMarker;
+    markerRemoved: MapMarker;
+    markerclick: MarkerEventPayload;
+    popupopen: MarkerEventPayload;
+    popupclose: MarkerEventPayload;
+    imageready: ImagereadyPayload;
+    /** Deferred tile layers attached after a tile consent grant. */
+    tilesallowed: undefined;
+}
+
 /** Wheel/scroll zoom bookkeeping (handles cleared via clearTimeout). */
 interface ScrollState {
     start_time: number | null;
@@ -38,13 +56,21 @@ class MapBase {
     declare "_map": OlMap | null;
     declare "_mini_map": OverviewMap | null;
     declare "_markers": MapMarker[];
+    /**
+     * Zooms computed by the engine's `_calculateMarkerZooms`, keyed by
+     * marker index. Kept off `marker.data` so navigating never mutates the
+     * author's storymap document (`StoryMap.data` is that same object graph).
+     */
+    declare "_marker_zooms": (number | undefined)[];
     declare "zoom_min_max": { min: number | null; max: number | null };
     declare "_line": VectorLayer | null;
     declare "_line_active": VectorLayer | null;
     declare "current_marker": number;
+    /** The wheel handler on the map element, stored for dispose(). */
+    declare "_onWheelBound": ((e: WheelEvent) => void) | null;
     declare "bounds_array": number[][] | null;
-    declare "_tile_layer": TileLayer | null;
-    declare "_tile_layer_mini": TileLayer | null;
+    declare "_tile_layer": Layer | null;
+    declare "_tile_layer_mini": Layer | null;
     declare "_image_layer": TileLayer | null;
     declare "data": StorymapData;
     declare "options": StorymapOptions;
@@ -53,7 +79,7 @@ class MapBase {
     declare "timer": ReturnType<typeof setTimeout> | null;
     declare "touch_scale": number;
     declare "scroll": ScrollState;
-    declare "fire": EventedInstance["fire"];
+    declare "fire": EventedInstance<MapEvents>["fire"];
     constructor(
         elem: string | HTMLElement,
         data?: Partial<StorymapData>,
@@ -69,7 +95,11 @@ class MapBase {
         if (typeof elem === "object") {
             this._el.container = elem;
         } else {
-            this._el.container = Dom.get(elem);
+            const found = Dom.get(elem);
+            if (!found) {
+                throw new Error("StoryMapJS: no element with id " + elem);
+            }
+            this._el.container = found;
         }
 
         // LOADED
@@ -86,6 +116,7 @@ class MapBase {
 
         // Markers
         this._markers = [];
+        this._marker_zooms = [];
 
         // Marker Zoom Miniumum and Maximum
         this.zoom_min_max = {
@@ -118,13 +149,15 @@ class MapBase {
             slides: [{ test: "yes" }, { test: "yes" }, { test: "yes" }],
         };
 
-        //Options
+        // Options — the map-owned subset only. StoryMap passes its own full
+        // options object in (see the constructor), so `this.options` is a
+        // complete StorymapOptions by the time anything reads it; these are
+        // just the fallbacks for a standalone Map.
         this.options = {
             map_type: "osm:standard",
             map_as_image: false,
             map_mini: false,
             map_background_color: "#d9d9d9",
-            map_subdomains: "",
             map_access_token: "",
             overlays: [],
             overview_extent: null,
@@ -133,11 +166,7 @@ class MapBase {
                 attribution: "",
             },
             skinny_size: 650,
-            less_bounce: true,
-            path_gfx: "gfx",
             start_at_slide: 0,
-            map_popup: false,
-            zoom_distance: 100,
             calculate_zoom: true, // Allow map to determine best zoom level between markers (recommended)
             line_follows_path: true, // Map history path follows default line, if false it will connect previous and current only
             line_color: "#333",
@@ -149,7 +178,7 @@ class MapBase {
             show_lines: true,
             show_history_line: true,
             map_center_offset: null, // takes object {top:0,left:0}
-        } as StorymapOptions;
+        } as unknown as StorymapOptions;
 
         // Animation
         this.animator = null;
@@ -204,32 +233,34 @@ class MapBase {
             // Check to see if it's an overview
             if (marker.data.type && marker.data.type === "overview") {
                 this._markerOverview();
-                if (!change) {
-                    this._onMarkerChange();
-                }
+                // overview stops are navigable like any other: report the
+                // change exactly as the branches below do, or a click on an
+                // overview pin moves the map without ever moving the story
+                this._onMarkerChange();
             } else {
                 // Make marker active
                 marker.active(true);
 
+                const target_location = marker.data.location ?? undefined;
                 if (change) {
                     // Set Map View
-                    if (marker.data.location) {
-                        this._viewTo(marker.data.location, {
+                    if (target_location) {
+                        this._viewTo(target_location, {
                             duration: this._transition_duration,
                         });
                     } else {
                         // nothing to show
                     }
-                } else {
-                    if (this._hasLocation(marker.data)) {
+                } else if (target_location) {
+                    if (this._hasLocation(marker.data) || this._hasRegion(marker.data)) {
                         // Calculate Zoom
-                        zoom = this._calculateZoomChange(
-                            this._getMapCenter(true),
-                            marker.location(),
-                        );
+                        const here = marker.location();
+                        zoom = here
+                            ? this._calculateZoomChange(this._getMapCenter(true), here)
+                            : undefined;
 
                         // Set Map View
-                        this._viewTo(marker.data.location, {
+                        this._viewTo(target_location, {
                             calculate_zoom: this.options.calculate_zoom,
                             zoom: zoom,
                             duration: this._transition_duration,
@@ -252,32 +283,19 @@ class MapBase {
                                 // the already-traveled prefix 0..previous,
                                 // which stays drawn while [prev..current]
                                 // traces progressively (see _replaceLines).
-                                let line_num = 0,
-                                    point;
+                                let line_num = 0;
                                 let retract_path_source: LinePoint[] | null = null;
                                 let grow_path_source: LinePoint[] | null = null;
                                 if (previous_marker < this.current_marker) {
                                     while (line_num < this.current_marker) {
-                                        if (this._hasLocation(this._markers[line_num].data)) {
-                                            point = {
-                                                lat: this._markers[line_num].data.location.lat,
-                                                lon: this._markers[line_num].data.location.lon,
-                                            };
-                                            lines_array.push(point);
+                                        const loc = this._locationOf(this._markers[line_num].data);
+                                        if (loc) {
+                                            lines_array.push(loc);
                                         }
 
                                         line_num++;
                                     }
-                                    const grow_path: LinePoint[] = [];
-                                    for (let idx = 0; idx <= previous_marker; idx++) {
-                                        if (this._hasLocation(this._markers[idx].data)) {
-                                            grow_path.push({
-                                                lat: this._markers[idx].data.location.lat,
-                                                lon: this._markers[idx].data.location.lon,
-                                            });
-                                        }
-                                    }
-                                    grow_path_source = grow_path;
+                                    grow_path_source = this._locationsUpTo(previous_marker);
                                 } else if (previous_marker > this.current_marker) {
                                     // Backward navigation: the line retracts —
                                     // the end state is the traveled path from
@@ -285,33 +303,13 @@ class MapBase {
                                     // the far end pulls back from the old
                                     // marker to the new one (handled by the
                                     // map's retract animation).
-                                    const traveled = [];
-                                    for (let idx = 0; idx <= this.current_marker; idx++) {
-                                        if (this._hasLocation(this._markers[idx].data)) {
-                                            traveled.push({
-                                                lat: this._markers[idx].data.location.lat,
-                                                lon: this._markers[idx].data.location.lon,
-                                            });
-                                        }
-                                    }
-                                    const retract_path = [];
-                                    for (let idx = 0; idx <= previous_marker; idx++) {
-                                        if (this._hasLocation(this._markers[idx].data)) {
-                                            retract_path.push({
-                                                lat: this._markers[idx].data.location.lat,
-                                                lon: this._markers[idx].data.location.lon,
-                                            });
-                                        }
-                                    }
-                                    lines_array = traveled;
-                                    retract_path_source = retract_path;
+                                    lines_array = this._locationsUpTo(this.current_marker);
+                                    retract_path_source = this._locationsUpTo(previous_marker);
                                 }
 
-                                if (!retract_path_source) {
-                                    lines_array.push({
-                                        lat: marker.data.location.lat,
-                                        lon: marker.data.location.lon,
-                                    });
+                                const marker_loc = this._locationOf(marker.data);
+                                if (!retract_path_source && marker_loc) {
+                                    lines_array.push(marker_loc);
                                 }
 
                                 this._replaceLines(this._line_active, lines_array, {
@@ -321,66 +319,80 @@ class MapBase {
                                 });
                             }
                         } else {
-                            // Show Line
-                            if (
-                                this.options.show_history_line &&
-                                marker.data.real_marker &&
-                                this._markers[previous_marker].data.real_marker
-                            ) {
-                                this._replaceLines(
-                                    this._line_active,
-                                    [
-                                        {
-                                            lat: marker.data.location.lat,
-                                            lon: marker.data.location.lon,
-                                        },
-                                        {
-                                            lat: this._markers[previous_marker].data.location.lat,
-                                            lon: this._markers[previous_marker].data.location.lon,
-                                        },
-                                    ],
-                                    { duration: this._transition_duration },
-                                );
+                            // Show Line — both endpoints need a real location.
+                            // The path branch above guards every access with
+                            // _hasLocation(); `real_marker` alone is not enough
+                            // because a slide can carry a region only.
+                            const from = this._locationOf(marker.data);
+                            const to = this._locationOf(this._markers[previous_marker].data);
+                            if (this.options.show_history_line && from && to) {
+                                this._replaceLines(this._line_active, [from, to], {
+                                    duration: this._transition_duration,
+                                });
                             }
                         }
                     } else {
                         this._markerOverview();
-                        if (!change) {
-                            this._onMarkerChange();
-                        }
                     }
 
-                    // Fire Event
+                    // Fire Event — once per goTo(), for every branch above
                     this._onMarkerChange();
                 }
             }
         }
     }
 
+    /**
+     * Alias over the OpenLayers view: `storymap.map.getView().animate({center})`
+     * (remember `ol/proj` does not apply in image mode — see `isImageSpace()`).
+     */
     panTo(loc: LatLngLiteral, animate?: boolean): void {
         this._panTo(loc, animate);
     }
 
+    /** Alias over the OpenLayers view: `storymap.map.getView().animate({zoom})`. */
     zoomTo(z: number, animate?: boolean): void {
         this._zoomTo(z, animate);
     }
 
+    /**
+     * Alias over the OpenLayers view: `storymap.map.getView().animate(...)`,
+     * or `.fit(extent, {size})` for a region stop (`location.region`).
+     */
     viewTo(loc: StorymapSlideLocation, opts?: ViewToOptions): void {
         this._viewTo(loc, opts);
     }
 
-    getBoundsZoom(m1: LatLngLiteral, m2: LatLngLiteral, inside?: boolean, padding?: unknown): void {
-        this._getBoundsZoom(m1, m2, inside, padding); // (LatLngBounds[, Boolean, Point]) -> Number
+    /** Alias over the OpenLayers view: `view.getZoomForResolution(resolution)`. */
+    getBoundsZoom(
+        m1: LatLngLiteral,
+        m2: LatLngLiteral,
+        inside?: boolean,
+        padding?: unknown,
+    ): number | undefined {
+        return this._getBoundsZoom(m1, m2, inside, padding);
     }
 
+    /**
+     * Alias over the OpenLayers view: `view.fit(extent, {size})` over all
+     * marker positions. Also reachable from the menubar's overview button.
+     */
     markerOverview(): void {
         this._markerOverview();
     }
 
+    /**
+     * The viewer's own marker zoom ladder — no OpenLayers equivalent (it also
+     * writes the computed zoom onto the current markers).
+     */
     calculateMarkerZooms(): void {
         this._calculateMarkerZooms();
     }
 
+    /**
+     * The minimap is built with the constructor; reach it with `getMinimap()`
+     * (an OpenLayers `OverviewMap` control) rather than re-creating it.
+     */
     createMiniMap(): void {
         this._createMiniMap();
     }
@@ -397,18 +409,32 @@ class MapBase {
 
     calculateMinMaxZoom(): void {
         for (let i = 0; i < this._markers.length; i++) {
-            if (this._markers[i].data.location && this._markers[i].data.location.zoom) {
-                this.updateMinMaxZoom(this._markers[i].data.location.zoom);
+            const zoom = this._markerZoom(i);
+            if (typeof zoom === "number") {
+                this.updateMinMaxZoom(zoom);
             }
         }
     }
 
+    /**
+     * The zoom to use for min/max bounds at marker `index`: the value
+     * computed by the engine when there is one, else the zoom authored on
+     * the slide. The engine overrides this to serve its computed-zoom store
+     * so `StoryMap.data` is never written to.
+     */
+    _markerZoom(index: number): number | undefined {
+        return this._markers[index]?.data.location?.zoom;
+    }
+
     updateMinMaxZoom(zoom: number): void {
-        if (!this.zoom_min_max.max) {
+        // `!x` treated a legitimate zoom level of 0 as "not measured yet" and
+        // then re-ran the min/max comparison against null, which coerces to 0.
+        // Test for null explicitly so zoom 0 is a real bound.
+        if (this.zoom_min_max.max === null) {
             this.zoom_min_max.max = zoom;
         }
 
-        if (!this.zoom_min_max.min) {
+        if (this.zoom_min_max.min === null) {
             this.zoom_min_max.min = zoom;
         }
 
@@ -432,8 +458,19 @@ class MapBase {
 
     /*	Adding, Hiding, Showing etc
 	================================================== */
+
+    /**
+     * @deprecated No-op since 0.9.x upstream (the original Leaflet engine
+     * defined an empty body too) and shadowed by the `DomMixed` mixin. To
+     * hide the map, toggle the OpenLayers target:
+     * `storymap.map.getTargetElement().style.display = "none"`.
+     */
     show(): void {}
 
+    /**
+     * @deprecated See {@link show} — no-op since 0.9.x upstream. Use
+     * `storymap.map.getTargetElement().style.display = "none"`.
+     */
     hide(): void {}
 
     /*	Adding and Removing Markers
@@ -448,10 +485,16 @@ class MapBase {
 
     _destroyMarker(marker: MapMarker): void {
         this._removeMarker(marker);
-        for (let i = 0; i < this._markers.length; i++) {
-            if (this._markers[i] === marker) {
-                this._markers.splice(i, 1);
-            }
+        const index = this._markers.indexOf(marker);
+        if (index === -1) {
+            return;
+        }
+        this._markers.splice(index, 1);
+        // `marker_number` is the marker's index into this array and is what
+        // _onMarkerClick hands to goTo(), so every marker after the removed
+        // one has to shift down or clicks navigate to the wrong slide
+        for (let i = index; i < this._markers.length; i++) {
+            this._markers[i].marker_number = i;
         }
         this.fire("markerRemoved", marker);
     }
@@ -470,9 +513,48 @@ class MapBase {
      * lon 0 are valid coordinates and must not be treated as missing.
      */
     _hasLocation(d: StorymapSlide): boolean {
-        return (
-            !!d.location && typeof d.location.lat == "number" && typeof d.location.lon == "number"
-        );
+        return this._locationOf(d) !== null;
+    }
+
+    /**
+     * The {lat, lon} points of every marker from the first up to and
+     * including `n`, skipping the ones without a real location. This was four
+     * near-identical loops building the same thing.
+     */
+    private _locationsUpTo(n: number): LinePoint[] {
+        const points: LinePoint[] = [];
+        for (let idx = 0; idx <= n && idx < this._markers.length; idx++) {
+            const loc = this._locationOf(this._markers[idx].data);
+            if (loc) {
+                points.push(loc);
+            }
+        }
+        return points;
+    }
+
+    /**
+     * The slide's {lat, lon} point, or null when it has no real location.
+     *
+     * Preferred over testing `_hasLocation()` and then reading
+     * `data.location.lat`: a boolean guard does not narrow the property for
+     * the type checker, so the old form had to be trusted and re-checked by
+     * hand at every one of its dozen call sites.
+     */
+    _locationOf(d: StorymapSlide): LatLngLiteral | null {
+        const loc = d.location;
+        if (!loc || typeof loc.lat !== "number" || typeof loc.lon !== "number") {
+            return null;
+        }
+        return { lat: loc.lat, lon: loc.lon };
+    }
+
+    /**
+     * Image region stop: the slide carries an xywh region ([x, y, w, h]
+     * image pixels). Only the OpenLayers engine applies it (image mode);
+     * the region never contributes to route lines.
+     */
+    _hasRegion(d: StorymapSlide): boolean {
+        return !!d.location && Array.isArray(d.location.region) && d.location.region.length === 4;
     }
 
     /*	Map Specific
@@ -520,7 +602,9 @@ class MapBase {
         return { data: d };
     }
 
-    _addToLine(line: VectorLayer | null, d: LinePoint): void {}
+    /** Append a slide's location to a route line. Takes the *slide*, not a
+     *  point — the engine reads `d.location`. */
+    _addToLine(line: VectorLayer | null, d: StorymapSlide): void {}
 
     _replaceLines(
         line: VectorLayer | null,
@@ -552,15 +636,31 @@ class MapBase {
     }
 
     _getMapCenter(correct_for_center?: boolean): LatLngLiteral {
-        return { lat: 0, lng: 0 };
+        return { lat: 0, lon: 0 };
+    }
+
+    /**
+     * The `ease` option as an OpenLayers easing function.
+     *
+     * `ease` is documented as either a function or a name, so the cast to
+     * OpenLayers' expected shape was repeated at all ten `view.animate()` call
+     * sites.
+     */
+    protected get _easing(): ((t: number) => number) | undefined {
+        return this.options.ease as ((t: number) => number) | undefined;
     }
 
+    /**
+     * Zoom that fits the two given points, or `undefined` when the engine
+     * cannot compute one. Mirrors `getRouteDistance`: the base class is the
+     * no-op template, the OpenLayers subclass returns a real value.
+     */
     _getBoundsZoom(
         m1: LatLngLiteral,
         m2: LatLngLiteral,
         inside?: boolean,
         padding?: unknown,
-    ): number {
+    ): number | undefined {
         return undefined;
     }
 
@@ -585,6 +685,18 @@ class MapBase {
         if (this.current_marker !== e.marker_number) {
             this.goTo(e.marker_number, false);
         }
+        // Re-fired (after navigation) so hosts can tell a marker click
+        // apart from programmatic navigation: `change` alone does not say
+        // *how* the story moved.
+        this.fire("markerclick", { marker_number: e.marker_number });
+    }
+
+    _onMarkerPopupOpen(e: { marker_number: number }): void {
+        this.fire("popupopen", { marker_number: e.marker_number });
+    }
+
+    _onMarkerPopupClose(e: { marker_number: number }): void {
+        this.fire("popupclose", { marker_number: e.marker_number });
     }
 
     _onMapLoaded(e?: unknown): void {
@@ -657,7 +769,7 @@ class MapBase {
         origin: LatLngLiteral,
         destination: LatLngLiteral,
         correct_for_center?: boolean,
-    ): number {
+    ): number | undefined {
         return this._getBoundsZoom(origin, destination, correct_for_center);
     }
 
@@ -700,15 +812,18 @@ class MapBase {
     _afterCreateMarkers(): void {}
 
     _initEvents(): void {
-        this._el.map.addEventListener("wheel", (e) => {
+        // stored so the engine's dispose() can detach it (an inline arrow
+        // would have no other handle)
+        this._onWheelBound = (e: WheelEvent) => {
             this._onWheel(e);
-        });
-
-        //this.on("wheel", this._onWheel, this);
+        };
+        this._el.map.addEventListener("wheel", this._onWheelBound);
     }
 }
 
-export default class Map extends DomMixed(Evented(MapBase)) {
+const EventedMapBase = Evented<MapEvents, typeof MapBase>(MapBase);
+
+export default class Map extends DomMixed<MapEvents, typeof EventedMapBase>(EventedMapBase) {
     constructor(...args: ConstructorParameters<typeof MapBase>) {
         super(...args);
     }