@maptiler/sdk 3.2.2 → 3.4.0-rc1

package/.husky/pre-commit

@@ -1,2 +1,3 @@
 npx lint-staged;
-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
 
@@ -1109,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);
+});

package/e2e/tests/expected-results/animatedRouteLayer-1.json

@@ -0,0 +1,202 @@
+[
+  {
+    "frame": 0,
+    "center": [
+      -5.466042011463379,
+      55.4577906319048
+    ],
+    "zoom": 13.598461538461539,
+    "pitch": 31.96923076923077,
+    "bearing": 11.519999999999984
+  },
+  {
+    "frame": 1,
+    "center": [
+      -5.460399670970225,
+      55.4563116595035
+    ],
+    "zoom": 13.696923076923076,
+    "pitch": 33.93846153846154,
+    "bearing": 23.039999999999967
+  },
+  {
+    "frame": 2,
+    "center": [
+      -5.454680854842297,
+      55.454199187343335
+    ],
+    "zoom": 13.795384615384616,
+    "pitch": 35.90769230769231,
+    "bearing": 34.55999999999994
+  },
+  {
+    "frame": 3,
+    "center": [
+      -5.449154714432449,
+      55.45161563359928
+    ],
+    "zoom": 13.893846153846155,
+    "pitch": 37.87692307692308,
+    "bearing": 46.08000000000004
+  },
+  {
+    "frame": 4,
+    "center": [
+      -5.4440854476088205,
+      55.448695922972746
+    ],
+    "zoom": 13.992307692307692,
+    "pitch": 39.84615384615384,
+    "bearing": 57.5999999999999
+  },
+  {
+    "frame": 5,
+    "center": [
+      -5.439747931704942,
+      55.4455842681447
+    ],
+    "zoom": 14.09076923076923,
+    "pitch": 41.8153846153846,
+    "bearing": 69.11999999999988
+  },
+  {
+    "frame": 6,
+    "center": [
+      -5.436381601488342,
+      55.44242356593315
+    ],
+    "zoom": 14.189230769230766,
+    "pitch": 43.78461538461536,
+    "bearing": 80.63999999999987
+  },
+  {
+    "frame": 7,
+    "center": [
+      -5.434285966180362,
+      55.43932695213108
+    ],
+    "zoom": 14.287692307692307,
+    "pitch": 45.753846153846105,
+    "bearing": 92.15999999999974
+  },
+  {
+    "frame": 8,
+    "center": [
+      -5.433268915702869,
+      55.43589535070747
+    ],
+    "zoom": 14.386153846153844,
+    "pitch": 47.723076923076874,
+    "bearing": 103.67999999999961
+  },
+  {
+    "frame": 9,
+    "center": [
+      -5.433177455811488,
+      55.43198983159487
+    ],
+    "zoom": 14.484615384615381,
+    "pitch": 49.69230769230762,
+    "bearing": 115.19999999999958
+  },
+  {
+    "frame": 10,
+    "center": [
+      -5.433880699537133,
+      55.42784291729489
+    ],
+    "zoom": 14.577142857142853,
+    "pitch": 51.54285714285707,
+    "bearing": 126.71999999999957
+  },
+  {
+    "frame": 11,
+    "center": [
+      -5.435326079044055,
+      55.423654806187365
+    ],
+    "zoom": 14.668571428571424,
+    "pitch": 53.37142857142849,
+    "bearing": 138.23999999999944
+  },
+  {
+    "frame": 12,
+    "center": [
+      -5.437416792145254,
+      55.419638086917715
+    ],
+    "zoom": 14.759999999999996,
+    "pitch": 55.1999999999999,
+    "bearing": 149.75999999999942
+  },
+  {
+    "frame": 13,
+    "center": [
+      -5.440072094355931,
+      55.41599788270592
+    ],
+    "zoom": 14.851428571428567,
+    "pitch": 57.028571428571325,
+    "bearing": 161.2799999999993
+  },
+  {
+    "frame": 14,
+    "center": [
+      -5.4432174520051015,
+      55.412956866373364
+    ],
+    "zoom": 14.942857142857138,
+    "pitch": 58.85714285714275,
+    "bearing": 172.79999999999927
+  },
+  {
+    "frame": 15,
+    "center": [
+      -5.446829788111814,
+      55.41064796034502
+    ],
+    "zoom": 14.963076923076928,
+    "pitch": 59.26153846153856,
+    "bearing": -175.5692307692314
+  },
+  {
+    "frame": 16,
+    "center": [
+      -5.451519315760324,
+      55.40879433251729
+    ],
+    "zoom": 14.864615384615387,
+    "pitch": 57.292307692307745,
+    "bearing": -163.75384615384647
+  },
+  {
+    "frame": 17,
+    "center": [
+      -5.457134643435197,
+      55.407280629375585
+    ],
+    "zoom": 14.766153846153847,
+    "pitch": 55.32307692307692,
+    "bearing": -151.9384615384615
+  },
+  {
+    "frame": 18,
+    "center": [
+      -5.463405013806986,
+      55.40615466316898
+    ],
+    "zoom": 14.667692307692304,
+    "pitch": 53.3538461538461,
+    "bearing": -140.1230769230766
+  },
+  {
+    "frame": 19,
+    "center": [
+      -5.469987343492665,
+      55.405428197723374
+    ],
+    "zoom": 14.569230769230764,
+    "pitch": 51.38461538461526,
+    "bearing": -128.30769230769158
+  }
+]

package/e2e/tests/helpers/fetchGeojson.ts

@@ -0,0 +1,21 @@
+import { KeyframeableGeoJSONFeature } from "utils";
+
+type GeoJSON = {
+  type: "FeatureCollection";
+  features: KeyframeableGeoJSONFeature[];
+};
+
+export default async function fetchGeoJSON(assetUrl: string): Promise<GeoJSON> {
+  try {
+    const response = await fetch(assetUrl);
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch GeoJSON: ${response.statusText}`);
+    }
+
+    const geojson = await response.json();
+    return geojson as GeoJSON;
+  } catch (e) {
+    throw e;
+  }
+}