@maptiler/sdk 1.0.8 → 1.0.10

package/src/Map.ts

@@ -5,6 +5,11 @@ import type {
   MapOptions as MapOptionsML,
   ControlPosition,
   StyleOptions,
+  MapDataEvent,
+  Tile,
+  RasterDEMSourceSpecification,
+  TerrainSpecification,
+  MapTerrainEvent,
 } from "maplibre-gl";
 import { v4 as uuidv4 } from "uuid";
 import { ReferenceMapStyle, MapStyleVariant } from "@maptiler/client";
@@ -23,6 +28,22 @@ import { MaptilerTerrainControl } from "./MaptilerTerrainControl";
 import { MaptilerNavigationControl } from "./MaptilerNavigationControl";
 import { geolocation } from "@maptiler/client";
 import { MaptilerGeolocateControl } from "./MaptilerGeolocateControl";
+import { AttributionControl } from "./AttributionControl";
+import { ScaleControl } from "./ScaleControl";
+import { FullscreenControl } from "./FullscreenControl";
+
+function sleepAsync(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export type LoadWithTerrainEvent = {
+  type: "loadWithTerrain";
+  target: Map;
+  terrain: {
+    source: string;
+    exaggeration: number;
+  };
+};
 
 // StyleSwapOptions is not exported by Maplibre, but we can redefine it (used for setStyle)
 export type TransformStyleFunction = (
@@ -45,6 +66,13 @@ export const GeolocationType: {
   COUNTRY: "COUNTRY",
 } as const;
 
+type MapTerrainDataEvent = MapDataEvent & {
+  isSourceLoaded: boolean;
+  tile: Tile;
+  sourceId: string;
+  source: RasterDEMSourceSpecification;
+};
+
 /**
  * Options to provide to the `Map` constructor
  */
@@ -129,25 +157,21 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo"> & {
    *
    * Default: `false`
    */
-  geolocate?: typeof GeolocationType[keyof typeof GeolocationType] | boolean;
+  geolocate?: (typeof GeolocationType)[keyof typeof GeolocationType] | boolean;
 };
 
 /**
  * The Map class can be instanciated to display a map in a `<div>`
  */
 export class Map extends maplibregl.Map {
-  private languageShouldUpdate = false;
-  private isStyleInitialized = false;
   private isTerrainEnabled = false;
   private terrainExaggeration = 1;
   private primaryLanguage: LanguageString | null = null;
   private secondaryLanguage: LanguageString | null = null;
+  private terrainGrowing = false;
+  private terrainFlattening = false;
 
   constructor(options: MapOptions) {
-    // if (options.language) {
-    //   config.primaryLanguage = options.language;
-    // }
-
     if (options.apiKey) {
       config.apiKey = options.apiKey;
     }
@@ -201,12 +225,15 @@ export class Map extends maplibregl.Map {
 
     this.primaryLanguage = options.language ?? config.primaryLanguage;
     this.secondaryLanguage = config.secondaryLanguage;
+    this.terrainExaggeration =
+      options.terrainExaggeration ?? this.terrainExaggeration;
 
     // Map centering and geolocation
     this.once("styledata", async () => {
       // Not using geolocation centering if...
 
-      if (options.geolocate === false) {
+      // the geolcoate option is not provided or is falsy
+      if (!options.geolocate) {
         return;
       }
 
@@ -241,6 +268,11 @@ export class Map extends maplibregl.Map {
         console.warn(e.message);
       }
 
+      // A more precise localization
+
+      // This more advanced localization is commented out because the easeTo animation
+      // triggers an error if the terrain grow is enabled (due to being nable to project the center while moving)
+
       // Then, the get a more precise location, we rely on the browser location, but only if it was already granted
       // before (we don't want to ask wih a popup at launch time)
       const locationResult = await navigator.permissions.query({
@@ -256,11 +288,21 @@ export class Map extends maplibregl.Map {
               return;
             }
 
-            this.easeTo({
-              center: [data.coords.longitude, data.coords.latitude],
-              zoom: options.zoom || 12,
-              duration: 2000,
-            });
+            if (this.terrain) {
+              this.easeTo({
+                center: [data.coords.longitude, data.coords.latitude],
+                zoom: options.zoom || 12,
+                duration: 2000,
+              });
+            } else {
+              this.once("terrain", () => {
+                this.easeTo({
+                  center: [data.coords.longitude, data.coords.latitude],
+                  zoom: options.zoom || 12,
+                  duration: 2000,
+                });
+              });
+            }
           },
 
           // error callback
@@ -335,7 +377,7 @@ export class Map extends maplibregl.Map {
 
         // if attribution in option is `false` but the the logo shows up in the tileJson, then the attribution must show anyways
         if (options.attributionControl === false) {
-          this.addControl(new maplibregl.AttributionControl(options));
+          this.addControl(new AttributionControl(options));
         }
       } else if (options.maptilerLogo) {
         this.addControl(new MaptilerLogoControl(), options.logoPosition);
@@ -353,7 +395,7 @@ export class Map extends maplibregl.Map {
             : options.scaleControl
         ) as ControlPosition;
 
-        const scaleControl = new maplibregl.ScaleControl({ unit: config.unit });
+        const scaleControl = new ScaleControl({ unit: config.unit });
         this.addControl(scaleControl, position);
         config.on("unit", (unit) => {
           scaleControl.setUnit(unit);
@@ -420,10 +462,44 @@ export class Map extends maplibregl.Map {
             : options.fullscreenControl
         ) as ControlPosition;
 
-        this.addControl(new maplibregl.FullscreenControl({}), position);
+        this.addControl(new FullscreenControl({}), position);
+      }
+    });
+
+    // Creating a custom event: "loadWithTerrain"
+    // that fires only once when both:
+    // - the map has full loaded (corresponds to the the "load" event)
+    // - the terrain has loaded (corresponds to the "terrain" event with terrain beion non-null)
+    // This custom event is necessary to wait for when the map is instanciated with `terrain: true`
+    // and some animation (flyTo, easeTo) are running from the begining.
+    let loadEventTriggered = false;
+    let terrainEventTriggered = false;
+    let terrainEventData: LoadWithTerrainEvent = null;
+
+    this.once("load", (_) => {
+      loadEventTriggered = true;
+      if (terrainEventTriggered) {
+        this.fire("loadWithTerrain", terrainEventData);
       }
     });
 
+    const terrainCallback = (evt) => {
+      if (!evt.terrain) return;
+      terrainEventTriggered = true;
+      terrainEventData = {
+        type: "loadWithTerrain",
+        target: this,
+        terrain: evt.terrain,
+      };
+      this.off("terrain", terrainCallback);
+
+      if (loadEventTriggered) {
+        this.fire("loadWithTerrain", terrainEventData as LoadWithTerrainEvent);
+      }
+    };
+
+    this.on("terrain", terrainCallback);
+
     // enable 3D terrain if provided in options
     if (options.terrain) {
       this.enableTerrain(
@@ -432,6 +508,43 @@ export class Map extends maplibregl.Map {
     }
   }
 
+  /**
+   * Awaits for _this_ Map instance to be "loaded" and returns a Promise to the Map.
+   * If _this_ Map instance is already loaded, the Promise is resolved directly,
+   * otherwise, it is resolved as a result of the "load" event.
+   * @returns
+   */
+  async onLoadAsync() {
+    return new Promise<Map>((resolve, reject) => {
+      if (this.loaded()) {
+        return resolve(this);
+      }
+
+      this.once("load", (_) => {
+        resolve(this);
+      });
+    });
+  }
+
+  /**
+   * Awaits for _this_ Map instance to be "loaded" as well as with terrain being non-null for the first time
+   * and returns a Promise to the Map.
+   * If _this_ Map instance is already loaded with terrain, the Promise is resolved directly,
+   * otherwise, it is resolved as a result of the "loadWithTerrain" event.
+   * @returns
+   */
+  async onLoadWithTerrainAsync() {
+    return new Promise<Map>((resolve, reject) => {
+      if (this.loaded() && this.terrain) {
+        return resolve(this);
+      }
+
+      this.once("loadWithTerrain", (_) => {
+        resolve(this);
+      });
+    });
+  }
+
   /**
    * Update the style of the map.
    * Can be:
@@ -791,6 +904,54 @@ export class Map extends maplibregl.Map {
     return this.isTerrainEnabled;
   }
 
+  private growTerrain(exaggeration, durationMs = 1000) {
+    // This method assumes the terrain is already built
+    if (!this.terrain) {
+      return;
+    }
+
+    const startTime = performance.now();
+    // This is supposedly 0, but it could be something else (e.g. already in the middle of growing, or user defined other)
+    const currentExaggeration = this.terrain.exaggeration;
+    const deltaExaggeration = exaggeration - currentExaggeration;
+
+    // This is again called in a requestAnimationFrame ~loop, until the terrain has grown enough
+    // that it has reached the target
+    const updateExaggeration = () => {
+      if (!this.terrain) {
+        return;
+      }
+
+      // If the flattening animation is triggered while the growing animation
+      // is running, then the flattening animation is stopped
+      if (this.terrainFlattening) {
+        return;
+      }
+
+      // normalized value in interval [0, 1] of where we are currently in the animation loop
+      const positionInLoop = (performance.now() - startTime) / durationMs;
+
+      // The animation goes on until we reached 99% of the growing sequence duration
+      if (positionInLoop < 0.99) {
+        const exaggerationFactor = 1 - Math.pow(1 - positionInLoop, 4);
+        const newExaggeration =
+          currentExaggeration + exaggerationFactor * deltaExaggeration;
+        this.terrain.exaggeration = newExaggeration;
+        requestAnimationFrame(updateExaggeration);
+      } else {
+        this.terrainGrowing = false;
+        this.terrainFlattening = false;
+        this.terrain.exaggeration = exaggeration;
+      }
+
+      this.triggerRepaint();
+    };
+
+    this.terrainGrowing = true;
+    this.terrainFlattening = false;
+    requestAnimationFrame(updateExaggeration);
+  }
+
   /**
    * Enables the 3D terrain visualization
    * @param exaggeration
@@ -802,27 +963,72 @@ export class Map extends maplibregl.Map {
       return;
     }
 
-    const terrainInfo = this.getTerrain();
+    // This function is mapped to a map "data" event. It checks that the terrain
+    // tiles are loaded and when so, it starts an animation to make the terrain grow
+    const dataEventTerrainGrow = async (evt: MapTerrainDataEvent) => {
+      if (!this.terrain) {
+        return;
+      }
+
+      if (
+        evt.type !== "data" ||
+        evt.dataType !== "source" ||
+        !("source" in evt)
+      ) {
+        return;
+      }
+
+      if (evt.sourceId !== "maptiler-terrain") {
+        return;
+      }
+
+      const source = evt.source;
 
+      if (source.type !== "raster-dem") {
+        return;
+      }
+
+      if (!evt.isSourceLoaded) {
+        return;
+      }
+
+      // We shut this event off because we want it to happen only once.
+      // Yet, we cannot use the "once" method because only the last event of the series
+      // has `isSourceLoaded` true
+      this.off("data", dataEventTerrainGrow);
+
+      this.growTerrain(exaggeration);
+    };
+
+    // This is put into a function so that it can be called regardless
+    // of the loading state of _this_ the map instance
     const addTerrain = () => {
       // When style is changed,
       this.isTerrainEnabled = true;
       this.terrainExaggeration = exaggeration;
 
+      // Mapping it to the "data" event so that we can check that the terrain
+      // growing starts only when terrain tiles are loaded (to reduce glitching)
+      this.on("data", dataEventTerrainGrow);
+
       this.addSource(defaults.terrainSourceId, {
         type: "raster-dem",
         url: defaults.terrainSourceURL,
       });
+
+      // Setting up the terrain with a 0 exaggeration factor
+      // so it loads ~seamlessly and then can grow from there
       this.setTerrain({
         source: defaults.terrainSourceId,
-        exaggeration: exaggeration,
+        exaggeration: 0,
       });
     };
 
     // The terrain has already been loaded,
     // we just update the exaggeration.
-    if (terrainInfo) {
-      this.setTerrain({ ...terrainInfo, exaggeration });
+    if (this.getTerrain()) {
+      this.isTerrainEnabled = true;
+      this.growTerrain(exaggeration);
       return;
     }
 
@@ -842,44 +1048,80 @@ export class Map extends maplibregl.Map {
    * Disable the 3D terrain visualization
    */
   disableTerrain() {
-    this.isTerrainEnabled = false;
-    this.setTerrain(null);
-    if (this.getSource(defaults.terrainSourceId)) {
-      this.removeSource(defaults.terrainSourceId);
+    // It could be disabled already
+    if (!this.terrain) {
+      return;
     }
+
+    this.isTerrainEnabled = false;
+    // this.stopFlattening = false;
+
+    // Duration of the animation in millisec
+    const animationLoopDuration = 1 * 1000;
+    const startTime = performance.now();
+    // This is supposedly 0, but it could be something else (e.g. already in the middle of growing, or user defined other)
+    const currentExaggeration = this.terrain.exaggeration;
+
+    // This is again called in a requestAnimationFrame ~loop, until the terrain has grown enough
+    // that it has reached the target
+    const updateExaggeration = () => {
+      if (!this.terrain) {
+        return;
+      }
+
+      // If the growing animation is triggered while flattening,
+      // then we exist the flatening
+      if (this.terrainGrowing) {
+        return;
+      }
+
+      // normalized value in interval [0, 1] of where we are currently in the animation loop
+      const positionInLoop =
+        (performance.now() - startTime) / animationLoopDuration;
+
+      // The animation goes on until we reached 99% of the growing sequence duration
+      if (positionInLoop < 0.99) {
+        const exaggerationFactor = Math.pow(1 - positionInLoop, 4);
+        const newExaggeration = currentExaggeration * exaggerationFactor;
+        this.terrain.exaggeration = newExaggeration;
+        requestAnimationFrame(updateExaggeration);
+      } else {
+        this.terrain.exaggeration = 0;
+        this.terrainGrowing = false;
+        this.terrainFlattening = false;
+        this.setTerrain(null);
+        if (this.getSource(defaults.terrainSourceId)) {
+          this.removeSource(defaults.terrainSourceId);
+        }
+      }
+
+      this.triggerRepaint();
+    };
+
+    this.terrainGrowing = false;
+    this.terrainFlattening = true;
+    requestAnimationFrame(updateExaggeration);
   }
 
   /**
    * Sets the 3D terrain exageration factor.
-   * Note: this is only a shortcut to `.enableTerrain()`
+   * If the terrain was not enabled prior to the call of this method,
+   * the method `.enableTerrain()` will be called.
+   * If `animate` is `true`, the terrain transformation will be animated in the span of 1 second.
+   * If `animate` is `false`, no animated transition to the newly defined exaggeration.
    * @param exaggeration
+   * @param animate
    */
-  setTerrainExaggeration(exaggeration: number) {
-    this.enableTerrain(exaggeration);
+  setTerrainExaggeration(exaggeration: number, animate = true) {
+    if (!animate && this.terrain) {
+      this.terrainExaggeration = exaggeration;
+      this.terrain.exaggeration = exaggeration;
+      this.triggerRepaint();
+    } else {
+      this.enableTerrain(exaggeration);
+    }
   }
 
-  // getLanguages() {
-  //   const layers = this.getStyle().layers;
-
-  //   for (let i = 0; i < layers.length; i += 1) {
-  //     const layer = layers[i];
-  //     const layout = layer.layout;
-
-  //     if (!layout) {
-  //       continue;
-  //     }
-
-  //     if (!layout["text-field"]) {
-  //       continue;
-  //     }
-
-  //     const textFieldLayoutProp = this.getLayoutProperty(
-  //       layer.id,
-  //       "text-field"
-  //     );
-  //   }
-  // }
-
   /**
    * Perform an action when the style is ready. It could be at the moment of calling this method
    * or later.

package/src/MaptilerGeolocateControl.ts

@@ -1,8 +1,8 @@
 import type { LngLatLike } from "maplibre-gl";
 import maplibregl from "maplibre-gl";
+import { GeolocateControl } from "./GeolocateControl";
 import { DOMcreate } from "./tools";
 
-const GeolocateControl = maplibregl.GeolocateControl;
 const Marker = maplibregl.Marker;
 const LngLat = maplibregl.LngLat;
 

package/src/MaptilerLogoControl.ts

@@ -2,6 +2,7 @@ import maplibregl from "maplibre-gl";
 import type { LogoOptions as LogoOptionsML } from "maplibre-gl";
 import { defaults } from "./defaults";
 import { Map } from "./Map";
+import { LogoControl } from "./LogoControl";
 
 type LogoOptions = LogoOptionsML & {
   logoURL?: string;
@@ -12,7 +13,7 @@ type LogoOptions = LogoOptionsML & {
  * This LogoControl extends the MapLibre LogoControl but instead can use any image URL and
  * any link URL. By default this is using MapTiler logo and URL.
  */
-export class MaptilerLogoControl extends maplibregl.LogoControl {
+export class MaptilerLogoControl extends LogoControl {
   private logoURL = "";
   private linkURL = "";
 

package/src/MaptilerNavigationControl.ts

@@ -1,10 +1,10 @@
-import maplibregl from "maplibre-gl";
+import { NavigationControl } from "./NavigationControl";
 
 type HTMLButtonElementPlus = HTMLButtonElement & {
   clickFunction: (e?: any) => unknown;
 };
 
-export class MaptilerNavigationControl extends maplibregl.NavigationControl {
+export class MaptilerNavigationControl extends NavigationControl {
   constructor() {
     super({
       showCompass: true,

package/src/Marker.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre Marker to make it fully type compatible with the SDK
+ */
+
+import maplibregl from "maplibre-gl";
+import type { Map as MapMLGL } from "maplibre-gl";
+import { Map } from "./Map";
+
+export class Marker extends maplibregl.Marker {
+  addTo(map: Map | MapMLGL): this {
+    return super.addTo(map as MapMLGL);
+  }
+}

package/src/NavigationControl.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre NavigationControl to make it fully type compatible with the SDK
+ */
+
+import maplibregl from "maplibre-gl";
+import type { Map as MapMLGL } from "maplibre-gl";
+import { Map } from "./Map";
+
+export class NavigationControl extends maplibregl.NavigationControl {
+  onAdd(map: Map | MapMLGL) {
+    return super.onAdd(map as MapMLGL);
+  }
+}

package/src/Popup.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre Popup to make it fully type compatible with the SDK
+ */
+
+import maplibregl from "maplibre-gl";
+import type { Map as MapMLGL } from "maplibre-gl";
+import { Map } from "./Map";
+
+export class Popup extends maplibregl.Popup {
+  addTo(map: Map | MapMLGL): this {
+    return super.addTo(map as MapMLGL);
+  }
+}

package/src/RasterDEMTileSource.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre RasterDEMTileSource to make it fully type compatible with the SDK
+ */
+
+import maplibregl from "maplibre-gl";
+import type { Map as MapMLGL } from "maplibre-gl";
+import { Map } from "./Map";
+
+export class RasterDEMTileSource extends maplibregl.RasterDEMTileSource {
+  onAdd(map: Map | MapMLGL) {
+    super.onAdd(map as MapMLGL);
+  }
+}

package/src/RasterTileSource.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre RasterTileSource to make it fully type compatible with the SDK
+ */
+
+import maplibregl from "maplibre-gl";
+import type { Map as MapMLGL } from "maplibre-gl";
+import { Map } from "./Map";
+
+export class RasterTileSource extends maplibregl.RasterTileSource {
+  onAdd(map: Map | MapMLGL) {
+    super.onAdd(map as MapMLGL);
+  }
+}

package/src/ScaleControl.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre ScaleControl to make it fully type compatible with the SDK
+ */
+
+import maplibregl from "maplibre-gl";
+import type { Map as MapMLGL } from "maplibre-gl";
+import { Map } from "./Map";
+
+export class ScaleControl extends maplibregl.ScaleControl {
+  onAdd(map: Map | MapMLGL) {
+    return super.onAdd(map as MapMLGL);
+  }
+}

package/src/Style.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre Style to make it fully type compatible with the SDK
+ */
+
+import maplibregl from "maplibre-gl";
+import type { Map as MapMLGL, StyleOptions } from "maplibre-gl";
+import { Map } from "./Map";
+
+export class Style extends maplibregl.Style {
+  constructor(map: Map, options: StyleOptions = {}) {
+    super(map as MapMLGL, options);
+  }
+}

package/src/TerrainControl.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre TerrainControl to make it fully type compatible with the SDK
+ */
+
+import maplibregl from "maplibre-gl";
+import type { Map as MapMLGL } from "maplibre-gl";
+import { Map } from "./Map";
+
+export class TerrainControl extends maplibregl.TerrainControl {
+  onAdd(map: Map | MapMLGL) {
+    return super.onAdd(map as MapMLGL);
+  }
+}

package/src/VectorTileSource.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre VectorTileSource to make it fully type compatible with the SDK
+ */
+
+import maplibregl from "maplibre-gl";
+import type { Map as MapMLGL } from "maplibre-gl";
+import { Map } from "./Map";
+
+export class VectorTileSource extends maplibregl.VectorTileSource {
+  onAdd(map: Map | MapMLGL) {
+    super.onAdd(map as MapMLGL);
+  }
+}

package/src/VideoSource.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre VideoSource to make it fully type compatible with the SDK
+ */
+
+import maplibregl from "maplibre-gl";
+import type { Map as MapMLGL } from "maplibre-gl";
+import { Map } from "./Map";
+
+export class VideoSource extends maplibregl.VideoSource {
+  onAdd(map: Map | MapMLGL) {
+    super.onAdd(map as MapMLGL);
+  }
+}