@maptiler/sdk 1.0.8 → 1.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maptiler/sdk",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "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.1.3",
+    "@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!
 
@@ -509,9 +617,12 @@ In the following static map functions, the `option` object features a `style` pr
 - `MapStyle.STREETS`, reference style for navigation and city exploration
   - `MapStyle.STREETS.DARK` (variant)
   - `MapStyle.STREETS.LIGHT` (variant)
+  - `MapStyle.STREETS.NIGHT` (variant)
   - `MapStyle.STREETS.PASTEL` (variant)
 - `MapStyle.OUTDOOR` reference style for adventure
+  - `MapStyle.OUTDOOR.DARK` (variant)
 - `MapStyle.WINTER` reference style for winter adventure
+  - `MapStyle.WINTER.DARK` (variant)
 - `MapStyle.SATELLITE` reference style satellite and airborne imagery (no variants)
 - `MapStyle.HYBRID` reference style satellite and airborne imagery with labels (no variants)
 - `MapStyle.BASIC` reference style for minimalist design and general purpose

package/src/AttributionControl.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre AttributionControl 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 AttributionControl extends maplibregl.AttributionControl {
+  onAdd(map: Map | MapMLGL) {
+    return super.onAdd(map as MapMLGL);
+  }
+}

package/src/CanvasSource.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre CanvasSource 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 CanvasSource extends maplibregl.CanvasSource {
+  onAdd(map: Map | MapMLGL) {
+    super.onAdd(map as MapMLGL);
+  }
+}

package/src/FullscreenControl.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre FullscreenControl 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 FullscreenControl extends maplibregl.FullscreenControl {
+  onAdd(map: Map | MapMLGL) {
+    return super.onAdd(map as MapMLGL);
+  }
+}

package/src/GeoJSONSource.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre GeoJSONSource 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 GeoJSONSource extends maplibregl.GeoJSONSource {
+  onAdd(map: Map | MapMLGL) {
+    super.onAdd(map as MapMLGL);
+  }
+}

package/src/GeolocateControl.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre GeolocateControl 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 GeolocateControl extends maplibregl.GeolocateControl {
+  onAdd(map: Map | MapMLGL) {
+    return super.onAdd(map as MapMLGL);
+  }
+}

package/src/ImageSource.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre ImageSource 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 ImageSource extends maplibregl.ImageSource {
+  onAdd(map: Map | MapMLGL) {
+    super.onAdd(map as MapMLGL);
+  }
+}

package/src/LogoControl.ts

@@ -0,0 +1,13 @@
+/**
+ * This is an extension of MapLibre LogoControl 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 LogoControl extends maplibregl.LogoControl {
+  onAdd(map: Map | MapMLGL) {
+    return super.onAdd(map as MapMLGL);
+  }
+}