@maptiler/sdk 3.3.0-rc2 → 3.4.0-rc2

package/.husky/pre-commit

@@ -1,3 +1,3 @@
 npx lint-staged;
-npx ts-typecheck;
-npm run test;
+npm run test;
+npm run docs;

package/README.md

@@ -32,7 +32,12 @@ npm install --save @maptiler/sdk
 ⚠️ Please keep in mind that if you use any additional [MapTiler modules](https://docs.maptiler.com/sdk-js/modules/), you must update them to a version that supports MapTiler SDK JS v3.
 
 # API documentation
-In addition to the details and examples provided in this readme, check out the [complete API documentation](https://docs.maptiler.com/sdk-js/api/)
+For further documentation and examples, check out [docs.maptiler.com](https://docs.maptiler.com/sdk-js/api/). 
+
+Full api typedoc documentation can also be generated via the commands:
+
+`npm run docs:md` to generate markdown in `docs`
+`npm run docs:html` to generate html docs in `docs-html`
 
 # Quick start
 
@@ -40,30 +45,30 @@ In addition to the details and examples provided in this readme, check out the [
 **Recommended for:** advanced applications
 
 ```ts
-import * as maptilersdk from '@maptiler/sdk';
+import { config, Map } from '@maptiler/sdk';
 
 // Add your MapTiler Cloud API key to the config
 // (Go to https://cloud.maptiler.com/account/keys/ to get one for free!)
-maptilersdk.config.apiKey = 'YOUR_API_KEY';
+config.apiKey = 'YOUR_API_KEY';
 
 // Let's say you have a DIV ready to receive a map
 const mapContainer = document.getElementById('my-container-div');
 
 // Instantiate the map
-const map = new maptilersdk.Map({
+const map = new Map({
   container: mapContainer,
 });
 ```
 
 Alternatively, the `apiKey` can be set as Map option instead of in the `config` object. Yet, this will still internally propagate to the `config` object:
 ```ts
-import * as maptilersdk from '@maptiler/sdk';
+import { Map } from '@maptiler/sdk';
 
 // Let's say you have a DIV ready to receive a map
 const mapContainer = document.getElementById('my-container-div');
 
 // Instantiate the map
-const map = new maptilersdk.Map({
+const map = new Map({
   container: mapContainer,
   apiKey: 'YOUR_API_KEY'
 });
@@ -540,125 +545,7 @@ map.on("terrainAnimationStop", (e) => {
   });
 });
 ```
-# Halo and Space Options
-
-The `halo` and `space` options allow for enhanced visual customization of the map, especially for globe projections.  
-
-## `halo` (Atmospheric Glow)  
-The `halo` option adds a gradient-based atmospheric glow around the globe, simulating the visual effect of Earth's atmosphere when viewed from space.  
-
-### Usage:  
-You can enable a simple halo by setting it to `true`:  
-```ts
-const map = new maptilersdk.Map({
-  container: document.getElementById("map"),
-  style: maptilersdk.MapStyle.OUTDOOR,
-  halo: true,
-});
-```
-For more customization, you can define a radial gradient with scale and stops:
-```ts
 
-const map = new maptilersdk.Map({
-  container: document.getElementById("map"),
-  style: maptilersdk.MapStyle.OUTDOOR,
-  halo: {
-    scale: 1.5, // Controls the halo size
-    stops: [
-      [0.2, "transparent"],
-      [0.2, "red"],
-      [0.4, "red"],
-      [0.4, "transparent"],
-      [0.6, "transparent"],
-      [0.6, "red"],
-      [0.8, "red"],
-      [0.8, "transparent"],
-      [1.0, "transparent"],
-    ],
-  },
-});
-```
-You can also set the halo dynamically after the map loads:
-```ts
-map.on("load", () => {
-  map.setHalo({
-    scale: 2,
-    stops: [
-      [0.0, "rgba(135,206,250,1)"],
-      [0.5, "rgba(0,0,250,0.75)"],
-      [0.75, "rgba(250,0,0,0.0)"],
-    ],
-  });
-});
-```
-## `space` (Background Environment)
-
-The space option allows customizing the background environment of the globe, simulating deep space or skybox effects.
-### Usage
-
-You can enable a simple space background with a solid color:
-```ts
-const map = new maptilersdk.Map({
-  container: document.getElementById("map"),
-  style: maptilersdk.MapStyle.OUTDOOR,
-  space: {
-    color: "#111122", // Dark space-like color
-  },
-});
-```
-Alternatively, you can provide a cubemap for a realistic skybox effect using one of the following methods:
-
-    Predefined Presets:
-```ts
-const map = new maptilersdk.Map({
-  container: document.getElementById("map"),
-  style: maptilersdk.MapStyle.OUTDOOR,
-  space: {
-    preset: "universe-dark",
-  },
-});
-```
-Cubemap Images (Custom Skybox):
-```ts
-const map = new maptilersdk.Map({
-  container: document.getElementById("map"),
-  style: maptilersdk.MapStyle.OUTDOOR,
-  space: {
-    faces: {
-      pX: '/path-to-image/pX.png',
-      nX: '/path-to-image/nX.png',
-      pY: '/path-to-image/pY.png',
-      nY: '/path-to-image/nY.png',
-      pZ: '/path-to-image/pZ.png',
-      nZ: '/path-to-image/nZ.png',
-    },
-  },
-});
-```
-Cubemap Path with image format, fetches all images from a path, this assumes all files are named px, nx, py, ny, pz, nz and suffixed with the appropriate extension specified in `format`.
-```ts
-    const map = new maptilersdk.Map({
-      container: document.getElementById("map"),
-      style: maptilersdk.MapStyle.OUTDOOR,
-      space: {
-        path: {
-          baseUrl: "spacebox/transparent",
-          format: "png", // Defaults to PNG
-        },
-      },
-    });
-```
-You can also set the space background dynamically:
-```ts
-map.on("load", () => {
-  map.setSpace({
-    color: "red",
-    path: {
-      baseUrl: "spacebox/transparent",
-    },
-  });
-});
-```
 
 # Easy language switching
 The language generally depends on the style but we made it possible to easily set and update from a built-in list of languages.
@@ -1227,6 +1114,155 @@ Turning off *zoom compensation* allows for more accurate adjustments to the visu
 All the other options are documented on [our reference page](https://docs.maptiler.com/sdk-js/api/helpers/#heatmap) and more examples are available [here](https://docs.maptiler.com/sdk-js/examples/?q=heatmap+helper).
 
 # Other helpers
+
+## Camera routes and animations
+
+The SDK comes with several classes to help with animations, particularly route animations.
+
+See `demos/07-animated-routes.html` for examples.
+
+### 🧩 `MaptilerAnimation`
+
+MaptilerAnimation is a utility class for smoothly animating between keyframes using custom easing and playback control. It supports event-based hooks for frame updates and completion, and works well within rendering loops or UI transitions.
+
+#### 🚀 Usage
+
+```ts
+// linearly animated between values
+const animation = new MaptilerAnimation({
+  keyframes: [
+    // `props` are interpolated across the duration
+    { delta: 0, props: { lon: -7.445, } },
+    // `userData` can hold any type of custom data to pass with the keyframe
+    { delta: 0.5, userData: { mydata: "whoa!" } },
+    { delta: 1, props: { lon: -7.455 } }
+  ],
+  duration: 1000, // 1 second
+  iterations: Infinity // loop forever
+});
+
+const marker = new Marker().setLngLat(
+  new LngLat(
+    -7.449346225791231,
+    39.399728941536836,
+  )
+).addTo(map);
+
+// TimeUpdate is fired every frame
+animation.addEventListener(AnimationEventTypes.TimeUpdate, (e) => {
+  marker.setLngLat(
+    new LngLat(
+      e.props.lon,
+    39.399728941536836,
+    )
+  )
+})
+// fired when the keyframe changes
+animation.addEventListener(AnimationEventTypes.Keyframe, ({ userData }) => {
+  console.log(userData.mydata) // "whoa!"
+});
+
+animation.play();
+```
+![](images/animate-linear-trimmed.gif)
+
+```ts
+// eased between values
+const animation = new MaptilerAnimation({
+  keyframes: [
+    // `props` are interpolated across the duration
+    { delta: 0, easing: EasingFunctionName.ElasticInOut, props: { lon: -7.445, } },
+    { delta: 1, props: { lon: -7.455 } }
+  ],
+  duration: 1000, // 1 second
+  iterations: Infinity // loop forever
+});
+```
+![](images/animate-elastic-trimmed.gif)
+
+### 🗺️ `AnimatedRouteLayer`
+
+`AnimatedRouteLayer` is custom layer that animates a path or route on the map based on keyframes or GeoJSON data. It supports animated line styling and camera following, making it ideal for visualizing routes, playback tracks, or timeline-based geographic events.
+
+Note: At present, to avoid problems arising from the camera being manipulated by two animatioons at any one time, there can only ever be one instance of `AnimatedRouteLayer` on the map at any time. This API may change in the future, but at present you must remove each instance of `AnimatedRouteLayer` from the map before adding another.
+
+#### ✨ Features
+  - Animate a path using keyframes or GeoJSON data
+  - Optional animated stroke styles to indicate progress
+  - Camera movement smoothing, following along the route
+  - Configurable duration, easing, delay, and iterations via geojson properties
+  - Event-based lifecycle hooks for adaptibility.
+  - Optional manual frame advancement (e.g., for scrubbing or syncing with map events, scroll etc etc)
+
+#### 🚀 Basic Usage
+```ts
+const myGeoJSONSource = {
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "LineString",
+        "coordinates": [
+          [-74.0060, 40.7128],
+          [-73.9352, 40.7306],
+          [-73.9851, 40.7580]
+        ]
+      },
+      "properties": {
+        "@duration": 5000, // animation params are prepended with '@'
+        "@iterations": 3,
+        "@delay": 1000,
+        "@autoplay": true,
+        "bearing": [
+          40,
+          30,
+          10,
+          10,
+          20,
+          40,
+        ]
+      }
+    }
+  ]
+}
+
+const animatedRoute = new AnimatedRouteLayer({
+  source: {
+    // assumes that the source is already added to the map with the given layer ID
+    id: "my-geojson-source", // the name of the source
+    layerID: "route-layer", // the name of the layer
+    featureSetIndex: 0, // the index of the featureset within the geojson
+  },
+  // OR
+  keyframes: [], // an array of keyframes
+
+  duration: 5000,
+  pathStrokeAnimation: {
+    // will only be appliued to LineString GeoJSON types
+    activeColor: [0, 128, 0, 1], // color of the line that has already been traversed
+    inactiveColor: [128, 128, 128, 0.5],
+  },
+  cameraAnimation: {
+    follow: true, // should the camera follow the route?
+    pathSmoothing: {
+      resolution: 20, // the resolution of the smoothness 
+      epsilon: 10, // how much the path is simplified before smoothing
+    },
+  },
+  autoplay: true,
+});
+
+// Add to map
+map.addLayer(animatedRoute);
+
+// Playback controls
+animatedRoute.play();
+animatedRoute.pause();
+```
+
+For a full example of how to use this, look at [the example](./demos/07-animated-routes.html)
+
 ## Convert GPX and KML to GeoJSON
 In the [Polyline helper section](#polyline-layer-helper) above, we have seen that one can feed the helper directly with a path to a GPX or KML file, that is then converted under the hood client-side into a GeoJSON `FeatureCollection` object. This conversion feature is also exposed and can be used as such:
 

package/e2e/global.d.ts

@@ -0,0 +1,12 @@
+import { Map } from "@maptiler/sdk";
+
+declare global {
+  interface Window {
+    __map: Map;
+    __pageLoadTimeout: number;
+    notifyScreenshotStateReady: (data: TTestTransferData) => Promise<void>;
+    __pageObjects: Record<string, unknown>;
+  }
+
+  type TTestTransferData = string | number | boolean | string[] | number[] | boolean[] | null | Record<string, unknown> | [number, number];
+}

package/e2e/public/animated-route.geojson

@@ -0,0 +1,82 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "properties": {
+        "pitch": [
+          30,
+          40,
+          50,
+          60,
+          50,
+          40,
+          30
+        ],
+        "bearing": [
+          0,
+          180,
+          360
+        ],
+        "zoom": [
+          13.5,
+          14,
+          14.5,
+          15,
+          14.5,
+          14,
+          13.5
+        ]
+      },
+      "geometry": {
+        "coordinates": [
+          [
+            -5.513465218122661,
+            55.44452556522981
+          ],
+          [
+            -5.498757996681263,
+            55.45488849896259
+          ],
+          [
+            -5.4776627901701715,
+            55.459774141237716
+          ],
+          [
+            -5.450773829757111,
+            55.45446729456921
+          ],
+          [
+            -5.434581030391769,
+            55.44241894502119
+          ],
+          [
+            -5.434433020938883,
+            55.42337006037573
+          ],
+          [
+            -5.447655667245527,
+            55.40895140980018
+          ],
+          [
+            -5.474692405196635,
+            55.40169789075969
+          ],
+          [
+            -5.504997423959253,
+            55.410637475280794
+          ],
+          [
+            -5.520595992154796,
+            55.42809094495976
+          ],
+          [
+            -5.513910891499705,
+            55.44393572290733
+          ]
+        ],
+        "type": "LineString"
+      }
+    }
+  ]
+}

package/e2e/public/animatedRouteLayer.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>MapTiler E2E Animated Route Layer</title>
+  <style>
+    #map {
+      width: 100vw;
+      height: 100vh;
+      border: 1px solid red;
+    }
+
+    body {
+      margin: 0;
+      padding: 0;
+    }
+  </style>
+</head>
+<body>
+  <div id="map"></div>
+  <script type="module" src="/src/animatedRouteLayer.ts"></script>
+</body>
+</html>

package/e2e/public/mapLoad.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>MapTiler E2E Map Load</title>
+  <style>
+    #map {
+      width: 100vw;
+      height: 100vh;
+      border: 1px solid red;
+    }
+
+    body {
+      margin: 0;
+      padding: 0;
+    }
+  </style>
+</head>
+<body>
+  <div id="map"></div>
+  <script type="module" src="/src/mapLoad.ts"></script>
+</body>
+</html>

package/e2e/tests/AnimatedRouteLayer.test.ts

@@ -0,0 +1,45 @@
+import { expect, test } from "@playwright/test";
+import getMapInstanceForFixture from "./helpers/getMapInstanceForFixture";
+import { AnimatedRouteLayer } from "index";
+import { Map } from "@maptiler/sdk";
+import expected from "./expected-results/animatedRouteLayer-1.json" assert { type: "json" };
+
+test("Follows the correct path taking screenshots at each interval", async ({ page }) => {
+  await getMapInstanceForFixture({
+    fixture: "animatedRouteLayer",
+    page,
+    timeout: 10000,
+  });
+
+  expect(await page.title()).toBe("MapTiler E2E Animated Route Layer");
+
+  await page.exposeFunction("notifyScreenshotStateReady", async (data: Record<string, TTestTransferData>) => {
+    await expect(page).toHaveScreenshot(`animated-route-${data.frame}.png`);
+    expect(data).toEqual(expected[data.frame as number]);
+  });
+
+  await page.clock.install();
+
+  await page.evaluate(async () => {
+    const NUM_SCREENSHOTS = 20;
+    const NUM_FRAMES_BETWEEN_SCREENSHOTS = 20;
+
+    const { animatedRouteLayer } = window.__pageObjects as { animatedRouteLayer: AnimatedRouteLayer };
+    const map = window.__map as Map;
+
+    for (let i = 0; i < NUM_SCREENSHOTS; i++) {
+      for (let j = 0; j < NUM_FRAMES_BETWEEN_SCREENSHOTS; j++) {
+        animatedRouteLayer.updateManual();
+      }
+      await window.notifyScreenshotStateReady({
+        frame: i,
+        center: map.getCenter().toArray(),
+        zoom: map.getZoom(),
+        pitch: map.getPitch(),
+        bearing: map.getBearing(),
+      });
+    }
+  });
+
+  await page.clock.runFor(10000);
+});