@projektemacher/storymapjs 0.10.7 → 0.10.8

package/src/main.ts

@@ -41,11 +41,103 @@ export { setLanguage } from "./language/Language";
  */
 export { validateStorymap, validateStorymapAndReport } from "./storymap/validate";
 
+/** One problem `validateStorymap()` reports. */
+export type { StorymapError } from "./storymap/validate";
+
+/** `loadCSS()`'s options (currently the abort signal). */
+export type { LoadOptions } from "./core/Load";
+
+/** The shape of a bundled locale file, as `setLanguage()` reads it. */
+export type { LanguageEntry } from "./language/Language";
+
+/**
+ * A IIIF Content State 1.0 target: the canvas a deep link names, and the
+ * region within it when the link carries one.
+ */
+export type { ContentState } from "./storymap/content-state";
+
 /**
  * Public data and options types for constructing a StoryMap.
+ *
+ * The data types are exported rather than only referenced: they are what a host
+ * actually types its document and options with, and TypeDoc warns about a
+ * documented member whose type it cannot link.
  */
 export type {
     StorymapSlide,
+    StorymapSlideText,
+    StorymapSlideMedia,
+    StorymapSlideMarker,
+    StorymapSlideNarration,
+    StorymapSlideBackground,
+    StorymapSlideLocation,
+    StorymapData,
     StorymapDataWrapper,
     StorymapOptions,
+    StorymapOverlayLayer,
+    StorymapTilejson,
+    StorymapGeoreference,
+    StorymapGeoreferenceBody,
+    StorymapGroundControlPoint,
+    StorymapMapOptions,
+    TileSourceFactory,
+    LatLngLiteral,
+    MediaTypeMatch,
+    AnimationHandle,
 } from "./types";
+
+/**
+ * True when a fetched document is an IIIF Presentation 3 manifest (accepted
+ * directly as a StoryMap source).
+ */
+export {
+    isPresentation3Manifest,
+    isPresentation3Collection,
+    manifestToStorymapData,
+} from "./storymap/iiif";
+
+/**
+ * Convert a legacy storymap document into a IIIF Presentation 3 manifest —
+ * the writer counterpart of `manifestToStorymapData()`. Pure, so the same
+ * document always produces the same manifest.
+ */
+export { storymapToManifest } from "./storymap/to-iiif";
+
+/**
+ * The manifest shape `storymapToManifest()` produces, for a host that wants to
+ * consume or further annotate the result.
+ */
+export type {
+    StorymapDocument,
+    StorymapManifest,
+    StorymapManifestCanvas,
+    StorymapManifestService,
+    StorymapLanguageMap,
+    StorymapManifestAnnotation,
+    StorymapManifestBackground,
+    StorymapManifestContentResource,
+    StorymapManifestFeatureCollection,
+    StorymapManifestGeoreferencing,
+    StorymapManifestImageService,
+    StorymapManifestRange,
+    StorymapManifestSpecificResource,
+    StorymapManifestStatement,
+} from "./storymap/to-iiif";
+
+/**
+ * Re-exported OpenLayers types, so consumers can type the map reachable at
+ * `storymap.map` without depending on `ol` themselves.
+ */
+export type { default as OlMap } from "ol/Map";
+export type { default as OlView } from "ol/View";
+export type { default as OlLayer } from "ol/layer/Layer";
+export type { default as OlTileLayer } from "ol/layer/Tile";
+export type { default as OlVectorLayer } from "ol/layer/Vector";
+export type { default as OlSource } from "ol/source/Source";
+export type { default as OlProjection } from "ol/proj/Projection";
+
+/**
+ * Payload of the `imageready` event, fired when an image source is actually
+ * attached — the only outward signal that the imagery is really on the map.
+ */
+export type { ImagereadyKind, ImagereadyPayload } from "./map/openlayers/Map.OpenLayers";

package/src/map/Map.ts

@@ -4,6 +4,7 @@ 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 { LinePoint, ViewToOptions } from "./types";
@@ -38,13 +39,19 @@ 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;
     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;
@@ -69,7 +76,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 +97,7 @@ class MapBase {
 
         // Markers
         this._markers = [];
+        this._marker_zooms = [];
 
         // Marker Zoom Miniumum and Maximum
         this.zoom_min_max = {
@@ -118,13 +130,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 +147,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 +159,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 +214,30 @@ class MapBase {
             // Check to see if it's an overview
             if (marker.data.type && marker.data.type === "overview") {
                 this._markerOverview();
-                if (!change) {
-                    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 +260,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 +280,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 +296,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 +386,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 +435,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 +462,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 +490,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 +579,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 +613,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;
     }
 
@@ -657,7 +734,7 @@ class MapBase {
         origin: LatLngLiteral,
         destination: LatLngLiteral,
         correct_for_center?: boolean,
-    ): number {
+    ): number | undefined {
         return this._getBoundsZoom(origin, destination, correct_for_center);
     }
 

package/src/map/MapMarker.ts

@@ -54,7 +54,7 @@ class MapMarkerBase {
         this.media_icon_class = "";
 
         // Timer
-        this.timer = {} as ReturnType<typeof setTimeout>;
+        this.timer = null;
 
         // Data
         this.data = {};
@@ -66,7 +66,6 @@ class MapMarkerBase {
             ease: easeInSpline,
             width: 600,
             height: 600,
-            map_popup: false,
         } as StorymapOptions;
 
         // Animation Object
@@ -81,10 +80,27 @@ class MapMarkerBase {
 
     /*	Public
 	================================================== */
+
+    /**
+     * @deprecated No-op since 0.9.x upstream (the original marker defined an
+     * empty body too). Markers are never individually hidden; use CSS on
+     * `.vco-mapmarker`, or `active(false)` to dim one.
+     */
     show(): void {}
 
+    /** @deprecated See {@link show} — no-op since 0.9.x upstream. */
     hide(): void {}
 
+    /**
+     * @deprecated Never implemented, in the original viewer either: the base
+     * `MapMarker._createPopup` had an empty body and the Leaflet override's
+     * body was commented out, so the `map_popup` option that called it never
+     * had any effect. Kept as a no-op so pre-0.10 code that calls it keeps
+     * working. Render the slide text yourself, or use CSS on
+     * `.vco-mapmarker` to show a label.
+     */
+    createPopup(_d?: MapMarkerData, _o?: StorymapOptions): void {}
+
     addTo(m: unknown): void {
         this._addTo(m);
     }
@@ -105,7 +121,7 @@ class MapMarkerBase {
         this._active(a);
     }
 
-    location(): LatLngLiteral {
+    location(): LatLngLiteral | null {
         return this._location();
     }
 
@@ -120,8 +136,15 @@ class MapMarkerBase {
 
     _active(a: boolean): void {}
 
-    _location(): LatLngLiteral {
-        return { lat: 0, lng: 0 };
+    /**
+     * The marker's coordinate, or null when it has none (an overview slide, or
+     * a slide carrying only an image region). Every caller treats null as
+     * "nothing to focus", so this is the honest shape — the previous
+     * `{ lat: 0, lng: 0 }` was a real point at Null Island, spelled with a
+     * longitude key nothing in the map read.
+     */
+    _location(): LatLngLiteral | null {
+        return null;
     }
 
     /*	Events