@maptiler/sdk 1.0.9 → 1.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maptiler/sdk",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "The Javascript & TypeScript map SDK tailored for MapTiler Cloud",
   "module": "dist/maptiler-sdk.mjs",
   "types": "dist/maptiler-sdk.d.ts",
@@ -20,52 +20,50 @@
     "sdk",
     "webmap",
     "cloud",
-    "webGL"
+    "webGL",
+    "maplibre"
   ],
-  "homepage": "https://www.maptiler.com/cloud/",
+  "homepage": "https://docs.maptiler.com/sdk-js/",
   "license": "BSD-3-Clause",
   "repository": {
     "type": "git",
     "url": "https://github.com/maptiler/maptiler-sdk-js.git"
   },
   "scripts": {
-    "build": "rm -rf dist/* ; NODE_ENV=production rollup -c",
-    "dev": "rm -rf dist/* ; NODE_ENV=development rollup -c -w",
+    "build": "rm -rf dist/* && NODE_ENV=production rollup -c",
+    "dev": "rm -rf dist/* && NODE_ENV=development rollup -c -w",
     "format": "prettier --write \"src/**/*.{js,ts,tsx}\"",
     "lint": "eslint --fix \"src/**/*.{js,ts}\"",
-    "docmd": "rm -rf docsmd/*; typedoc --readme none --plugin typedoc-plugin-markdown --out docsmd src/index.ts; cp -r images docsmd/",
-    "dochtml": "rm -rf docs/*; typedoc --plugin none --out docs; cp -r images docs/",
-    "doc": "npm run docmd; npm run dochtml",
-    "prepare": "npm run format; npm run lint; npm run build; npm run doc; cp -r demos docs/"
+    "doc": "rm -rf docs/* && typedoc --out docs && cp -r images docs/",
+    "prepare": "npm run format && npm run lint && npm run build && npm run doc && cp -r demos docs/"
   },
   "author": "MapTiler",
   "devDependencies": {
-    "@rollup/plugin-commonjs": "^22.0.2",
-    "@rollup/plugin-json": "^5.0.1",
-    "@rollup/plugin-node-resolve": "^14.1.0",
-    "@typescript-eslint/eslint-plugin": "^5.41.0",
-    "@typescript-eslint/parser": "^5.41.0",
-    "eslint": "^8.26.0",
-    "prettier": "^2.7.1",
-    "rollup": "^2.79.0",
-    "rollup-plugin-copy-merge": "^0.3.5",
-    "rollup-plugin-dts": "^4.2.2",
-    "rollup-plugin-esbuild": "^4.10.1",
+    "@rollup/plugin-commonjs": "^24.1.0",
+    "@rollup/plugin-json": "^6.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.2",
+    "@typescript-eslint/eslint-plugin": "^5.59.0",
+    "@typescript-eslint/parser": "^5.59.0",
+    "eslint": "^8.38.0",
+    "prettier": "^2.8.7",
+    "rollup": "^3.20.6",
+    "rollup-plugin-copy-merge": "^1.0.0",
+    "rollup-plugin-dts": "^5.3.0",
+    "rollup-plugin-esbuild": "^5.0.0",
     "rollup-plugin-node-globals": "^1.4.0",
     "rollup-plugin-shell": "^1.0.9",
     "rollup-plugin-string": "^3.0.0",
     "rollup-plugin-swc": "^0.2.1",
-    "serve": "^14.0.1",
-    "terser": "^5.15.0",
-    "typedoc": "^0.23.21",
-    "typedoc-plugin-markdown": "^3.13.6",
-    "typescript": "^4.8.4"
+    "serve": "^14.2.0",
+    "terser": "^5.17.1",
+    "typedoc": "^0.24.4",
+    "typescript": "^5.0.4"
   },
   "dependencies": {
     "@maptiler/client": "^1.3.0",
     "events": "^3.3.0",
     "js-base64": "^3.7.4",
-    "maplibre-gl": "^3.0.0-pre.3",
+    "maplibre-gl": "3.0.0-pre.4",
     "uuid": "^9.0.0"
   }
 }

package/readme.md

@@ -389,6 +389,114 @@ Languages that are written right-to-left such as arabic and hebrew are fully sup
   <img src="images/screenshots/lang-hebrew.jpeg" width="48%"></img>
 </p>
 
+# Custom Events and Map Lifecycle
+## Events
+Since the SDK is fully compatible with MapLibre, [all these events](https://maplibre.org/maplibre-gl-js-docs/api/map/#map-events) are available, yet we have added one more: `loadWithTerrain`.  
+
+The `loadWithTerrain` event is triggered only *once* in a `Map` instance lifecycle, when both the `load` event and the `terrain` event **with non-null terrain** are fired. 
+
+**Why a new event?**
+When a map is instanciated with the option `terrain: true`, then MapTiler terrain is directly added to it and some animation functions such as `.flyTo()` or `.easeTo()` if started straight after the map initialization will actually need to wait a few milliseconds that the terrain is properly initialized before running.  
+Relying on the `load` event to run an animation with a map with terrain may fail in some cases for this reason, and this is why waiting for `loadWithTerrain` is safer in this particular situation.
+
+## Lifecycle Methods
+The events `load` and `loadWithTerrain` are both called *at most once* and require a callback function to add more elements such as markers, layers, popups and data sources. Even though MapTiler SDK fully supports this logic, we have also included a *promise* logic to provide a more linear and less nested way to wait for a Map instance to be ready. Let's compare the two ways:
+
+- Classic: with a callback on the `load` event:
+```ts
+function init() {
+
+  const map = new Map({
+    container,
+    center: [2.34804, 48.85439], // Paris, France
+    zoom: 14,
+  });
+
+  // We wait for the event.
+  // Once triggered, the callback is ranin it's own scope.
+  map.on("load", (evt) => {
+    // Adding a data source
+    map.addSource('my-gps-track-source', {
+      type: "geojson",
+      data: "https://example.com/some-gps-track.geojson",
+    });
+  })
+}
+```
+
+- Modern: with a promise returned by the method `.onLoadAsync()`, used in an `async` function:
+```ts
+async function init() {
+
+  const map = new Map({
+    container,
+    center: [2.34804, 48.85439], // Paris, France
+    zoom: 14,
+  });
+
+  // We wait for the promise to resolve.
+  // Once triggered, the rest of the init function runs
+  await map.onLoadAsync();
+
+  // Adding a data source
+  map.addSource('my-gps-track-source', {
+    type: "geojson",
+    data: "https://example.com/some-gps-track.geojson",
+  });
+}
+```
+
+We deployed exactely the same logic for the `loadWithTerrain` event. Let's see how they two ways compares.
+- Classic: with a callback on the `loadWithTerrain` event:
+```ts
+function init() {
+
+  const map = new Map({
+    container,
+    center: [2.34804, 48.85439], // Paris, France
+    zoom: 14,
+    terrain: true,
+  });
+
+  // We wait for the event.
+  // Once triggered, the callback is ran in its own scope.
+  map.on("loadWithTerrain", (evt) => {
+    // make an animation
+    map.flyTo({
+      center: [-0.09956, 51.50509], // London, UK
+      zoom: 12.5,
+    })
+  })
+}
+```
+
+- Modern: with a promise returned by the method `.onLoadWithTerrainAsync()`, used in an `async` function:
+```ts
+async function init() {
+
+  const map = new Map({
+    container,
+    center: [2.34804, 48.85439], // Paris, France
+    zoom: 14,
+    terrain: true,
+  });
+
+  // We wait for the promise to resolve.
+  // Once triggered, the rest of the init function runs
+  await map.onLoadWithTerrainAsync();
+
+  // make an animation
+  map.flyTo({
+    center: [-0.09956, 51.50509], // London, UK
+    zoom: 12.5,
+  })
+}
+```
+
+We believe that the *promise* approach is better because it does not nest scopes and will allow for a linear non-nested stream of execution. It also corresponds to more modern development standards.
+
+> 📣 *__Note:__* Generally speaking, *promises* are not a go to replacement for all event+callback and are suitable only for events that are called only once in the lifecycle of a Map instance. This is the reason why we have decided to provide a *promise* equivalent only for the `load` and `loadWithTerrain` events.
+
 # Easy access to MapTiler Cloud API
 Our map SDK is not only about maps! We also provide plenty of wrapper to our API calls!
 

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";
@@ -27,6 +32,19 @@ 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 = (
   previous: StyleSpecification,
@@ -48,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
  */
@@ -74,7 +99,14 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo"> & {
   apiKey?: string;
 
   /**
-   * Shows the MapTiler logo if `true`. Note that the logo is always displayed on free plan.
+   * Shows or hides the MapTiler logo in the bottom left corner.
+   *
+   * For paid plans:
+   * - `true` shows MapTiler logo
+   * - `false` hodes MapTiler logo
+   * - default: `false` (hide)
+   *
+   * For free plans: MapTiler logo always shows, regardless of the value.
    */
   maptilerLogo?: boolean;
 
@@ -132,7 +164,7 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo"> & {
    *
    * Default: `false`
    */
-  geolocate?: typeof GeolocationType[keyof typeof GeolocationType] | boolean;
+  geolocate?: (typeof GeolocationType)[keyof typeof GeolocationType] | boolean;
 };
 
 /**
@@ -143,6 +175,8 @@ export class Map extends maplibregl.Map {
   private terrainExaggeration = 1;
   private primaryLanguage: LanguageString | null = null;
   private secondaryLanguage: LanguageString | null = null;
+  private terrainGrowing = false;
+  private terrainFlattening = false;
 
   constructor(options: MapOptions) {
     if (options.apiKey) {
@@ -198,6 +232,8 @@ 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 () => {
@@ -239,6 +275,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({
@@ -254,11 +295,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
@@ -422,6 +473,40 @@ export class Map extends maplibregl.Map {
       }
     });
 
+    // 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(
@@ -430,6 +515,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:
@@ -789,6 +911,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
@@ -800,27 +970,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;
     }
 
@@ -840,44 +1055,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.