@maptiler/sdk 3.10.2-rc.2 → 3.11.0-rc.1

package/dist/src/custom-layers/AnimatedRouteLayer/AnimatedRouteLayer.d.ts

@@ -0,0 +1,293 @@
+import { AnimationEvent, AnimationEventTypes, EasingFunctionName, Keyframe } from '../../MaptilerAnimation/types';
+import { MaptilerAnimation, MaptilerAnimationOptions } from '../../MaptilerAnimation';
+import { CustomLayerInterface, Map as MapSDK } from '../../';
+export type SourceData = {
+    id: string;
+    layerID: string;
+};
+/**
+ * Options for configuring the animated stroke effect for routes.
+ * When an object is provided, it defines colors for active and inactive parts of the route.
+ * When `false`, the animated stroke effect is disabled.
+ *
+ * @typedef {Object|boolean} AnimatedStrokeOptions
+ * @property {[number, number, number, number]} activeColor - The color of the path that has been progressed, in RGBA format.
+ * @property {[number, number, number, number]} inactiveColor - The base color of the path, in RGBA format.
+ */
+export type AnimatedStrokeOptions = {
+    activeColor: [number, number, number, number];
+    inactiveColor: [number, number, number, number];
+} | false;
+/**
+ * Options for configuring the animated camera movement
+ * along the route.
+ *
+ * @typedef {Object|boolean} AnimatedCameraOptions
+ * @property {boolean} [follow] - Whether the camera should follow the animation.
+ * @property {Object|boolean} [pathSmoothing] - Whether the camera path should be smoothed.
+ * @property {number} [pathSmoothing.resolution] - The resolution of the smoothing, higher resolution means more fidelity to the path.
+ * @property {number} [pathSmoothing.epsilon] - How much to simplify the path beforehand.
+ * @property {false} [pathSmoothing] - Whether the camera path should be smoothed.
+ */
+export type AnimatedCameraOptions = {
+    /** Whether the camera should follow the animation */
+    follow?: boolean;
+    /** Whether the camera path should be smoothed */
+    pathSmoothing?: {
+        /** the resolution of the smoothing, higher resolution means more fidelity to the path */
+        resolution: number;
+        /** How mich to simplify the path beforehand */
+        epsilon: number;
+    } | false;
+} | false;
+/**
+ * Configuration options for the AnimatedRouteLayer.
+ * This type supports either providing keyframes directly OR source data for the animation.
+ *
+ * @typedef AnimatedRouteLayerOptions
+ * @property {number} [duration] - The duration of the animation in milliseconds
+ * @property {number} [iterations] - The number of animation iterations to perform
+ * @property {number} [delay] - The delay in milliseconds before starting the animation
+ * @property {EasingFunctionName} [easing] - The default easing function to use if not provided in the GeoJSON
+ * @property {AnimatedCameraOptions} [cameraAnimation] - Options for camera animation
+ * @property {AnimatedStrokeOptions} [pathStrokeAnimation] - Options for stroke animation, only applicable for LineString geometries
+ * @property {boolean} [autoplay] - Whether the animation should start playing automatically
+ * @property {boolean} [manualUpdate] - Whether the animation should update automatically or require manual frameAdvance calls
+ * @property {Keyframe[]} [keyframes] - The keyframes for the animation (mutually exclusive with source)
+ * @property {SourceData} [source] - The source data for the animation (mutually exclusive with keyframes)
+ */
+export type AnimatedRouteLayerOptions = {
+    /** The Duration in ms */
+    duration?: number;
+    /** The number of iterations */
+    iterations?: number;
+    /** The delay in ms before playing */
+    delay?: number;
+    /** The default easing to use if not provided in teh GeoJSON */
+    easing?: EasingFunctionName;
+    /** The camera animation options */
+    cameraAnimation?: AnimatedCameraOptions;
+    /** The stroke animation options, only viable for LineString geometries */
+    pathStrokeAnimation?: AnimatedStrokeOptions;
+    /** Whether the animation should autoplay */
+    autoplay?: boolean;
+    /** Whether the animation should auto matically animated or whether the frameAdvance method should be called */
+    manualUpdate?: boolean;
+} & ({
+    /** The keyframes for the the animation OR */
+    keyframes: Keyframe[];
+    source?: never;
+} | {
+    /** The source data  */
+    source: SourceData;
+    keyframes?: never;
+});
+/**
+ * A callback function that gets executed for each animation frame. This is simply a utility type.
+ * @param {AnimationEvent} event - The animation event data provided during animation frame updates.
+ */
+export type FrameCallback = (event: AnimationEvent) => void;
+export declare const ANIM_LAYER_PREFIX = "animated-route-layer";
+/**
+ * This layer allows you to create animated paths on a map by providing keyframes or a GeoJSON source
+ * with route data. The animation can control both the visual appearance of the path (using color transitions)
+ * and optionally animate the camera to follow along the route path.
+ * @class AnimatedRouteLayer
+ *
+ * @example
+ * ```typescript
+ * // Create an animated route layer using a GeoJSON source
+ * const animatedRoute = new AnimatedRouteLayer({
+ *   source: {
+ *     id: 'route-source',
+ *     layerID: 'route-layer',
+ *   },
+ *   duration: 5000,
+ *   pathStrokeAnimation: {
+ *     activeColor: [0, 255, 0, 1],
+ *     inactiveColor: [100, 100, 100, 0.5]
+ *   },
+ *   autoplay: true
+ * });
+ *
+ * // Add the layer to the map
+ * map.addLayer(animatedRoute);
+ *
+ * // Control playback
+ * animatedRoute.play();
+ * animatedRoute.pause();
+ * ```
+ *
+ * @remarks
+ * The animation can be configured using either explicit keyframes or a GeoJSON source.
+ * When using a GeoJSON source, the feature can include special properties that control
+ * animation behavior:
+ * - `@duration`: Animation duration in milliseconds
+ * - `@iterations`: Number of times to repeat the animation
+ * - `@delay`: Delay before starting animation in milliseconds
+ * - `@autoplay`: Whether to start the animation automatically
+ *
+ * Only one AnimatedRouteLayer can be active at a time on a map.
+ */
+/**
+ * Creates an animated route layer for MapTiler maps.
+ *
+ * The `AnimatedRouteLayer` allows you to animate paths on a map with visual effects and optional camera following.
+ * You can define animations either through explicit keyframes or by referencing GeoJSON data with animation metadata.
+ *
+ * Features:
+ * - Animate route paths with color transitions (active/inactive segments)
+ * - Optional camera following along the route
+ * - Control animation playback (play, pause)
+ * - Configure animation properties (duration, iterations, delay, easing)
+ * - Support for manual or automatic animation updates
+ * - Event system for animation state changes
+ *
+ * @example
+ * ```typescript
+ * // Create an animated route from GeoJSON source
+ * const animatedRoute = new AnimatedRouteLayer({
+ *   source: {
+ *     id: 'route-source',
+ *     layerID: 'route-layer',
+ *   },
+ *   duration: 5000,
+ *   iterations: 1,
+ *   autoplay: true,
+ *   cameraAnimation: {
+ *     follow: true,
+ *     pathSmoothing: { resolution: 20, epsilon: 5 }
+ *   },
+ *   pathStrokeAnimation: {
+ *     activeColor: [255, 0, 0, 1],
+ *     inactiveColor: [0, 0, 255, 1]
+ *   }
+ * });
+ *
+ * // Add the layer to the map
+ * map.addLayer(animatedRoute);
+ *
+ * // Control playback
+ * animatedRoute.pause();
+ * animatedRoute.play();
+ *
+ * // Listen for animation events
+ * animatedRoute.addEventListener("animationend", () => {
+ *   console.log('Animation completed');
+ * });
+ * ```
+ *
+ * @implements {CustomLayerInterface}
+ */
+export declare class AnimatedRouteLayer implements CustomLayerInterface {
+    /** Unique ID for the layer */
+    readonly id: string;
+    readonly type = "custom";
+    /** The MaptilerAnimation instance that handles the animation */
+    animationInstance: MaptilerAnimation | null;
+    /**
+     * Keyframes for the animation
+     * If keyframes are provided, they will be used for the animation
+     * If a source is provided, the keyframes will be parsed from the GeoJSON feature
+     */
+    private keyframes;
+    /**
+     * Source data for the animation
+     * If a source is provided, it will be used to get the keyframes
+     * If keyframes are provided, this will be ignored
+     */
+    private source;
+    /** The duration of the animation in ms */
+    private duration;
+    /** The number of interations */
+    private iterations;
+    /** The delay before the animation starts in ms */
+    private delay;
+    /** The default easing function for the animation */
+    private easing?;
+    /** The map instance */
+    private map;
+    /** The camera animation options */
+    private cameraMaptilerAnimationOptions?;
+    /**
+     * The path stroke animation options
+     * This controls the color of the path during the animation
+     */
+    private pathStrokeAnimation?;
+    /** Whether the animation will autoplay */
+    private autoplay;
+    /** Whether the animation will be managed manually */
+    private manualUpdate;
+    private enquedEventHandlers;
+    private enquedCommands;
+    constructor({ keyframes, source, duration, iterations, easing, delay, cameraAnimation, pathStrokeAnimation, autoplay, manualUpdate, }: AnimatedRouteLayerOptions);
+    /**
+     * This method is called when the layer is added to the map.
+     * It initializes the animation instance and sets up event listeners.
+     *
+     * @param {MapLibreMap} map - The map instance (maplibre Map, but will be MapSDK at runtime)
+     * @param {WebGLRenderingContext | WebGL2RenderingContext} _gl - The WebGL context (unused in this layer)
+     */
+    onAdd(map: MapSDK): Promise<void>;
+    /**
+     * Initializes the animation instance asynchronously.
+     * This is called from onAdd but runs asynchronously to handle async data loading.
+     */
+    /**
+     * This method is used to manually advance the animation
+     *
+     * @returns {AnimatedRouteLayer} - The current instance of AnimatedRouteLayer
+     */
+    frameAdvance(): this;
+    /**
+     * Adds an event listener to the animation instance.
+     *
+     * @param {AnimationEventTypes} type - The type of event to listen for
+     * @param {FrameCallback} callback - The callback function to execute when the event occurs
+     */
+    addEventListener(type: AnimationEventTypes, callback: FrameCallback): AnimatedRouteLayer;
+    /**
+     * Removes an event listener from the animation instance.
+     *
+     * @param {AnimationEventTypes} type - The type of event to remove
+     * @param {FrameCallback} callback - The callback function to remove
+     */
+    removeEventListener(type: AnimationEventTypes, callback: FrameCallback): AnimatedRouteLayer;
+    updateManual(): void;
+    /**
+     * Updates the layer's properties based on the animation event.
+     * @private
+     * @param {AnimationEvent} event - The animation event
+     */
+    private update;
+    /**
+     * Plays the animation.
+     *
+     * @returns {AnimatedRouteLayer} - The current instance of AnimatedRouteLayer
+     */
+    play(): AnimatedRouteLayer;
+    /**
+     * Stops the animation.
+     *
+     * @returns {AnimatedRouteLayer} - The current instance of AnimatedRouteLayer
+     */
+    pause(): AnimatedRouteLayer;
+    /**
+     * Gets the source GeoJSON data from the map instance, parses it, and returns the animation options.
+     *
+     * @returns {Promise<MaptilerAnimationOptions>} - The MaptilerAnimation constructor options
+     */
+    getMaptilerAnimationOptions(): Promise<MaptilerAnimationOptions & {
+        autoplay: boolean;
+    }>;
+    /**
+     * This method is called when the layer is removed from the map.
+     * It destroys the animation instance.
+     */
+    onRemove(): void;
+    /**
+     * This method is called to render the layer.
+     * It is a no-op for this layer.
+     */
+    render(): void;
+}

package/dist/src/custom-layers/AnimatedRouteLayer/index.d.ts

@@ -0,0 +1 @@
+export * from './AnimatedRouteLayer';

package/dist/src/custom-layers/CubemapLayer/CubemapLayer.d.ts

@@ -235,5 +235,5 @@ declare class CubemapLayer implements CustomLayerInterface {
      */
     hide(): void;
 }
-export declare function validateSpaceSpecification(space?: CubemapDefinition | boolean): boolean;
+export declare function validateSpaceSpecification(space?: CubemapDefinition | boolean): string[];
 export { CubemapLayer };

package/dist/src/index.d.ts

@@ -98,3 +98,5 @@ export * from './custom-layers/index';
 export { ColorRamp, ColorRampCollection } from './ColorRamp';
 export type { RgbaColor, ColorStop, ArrayColor, ArrayColorRampStop, ArrayColorRamp, ColorRampOptions } from './ColorRamp';
 export * from './utils';
+export * from './MaptilerAnimation';
+export * from './custom-layers/AnimatedRouteLayer';

package/dist/src/utils/array.d.ts

@@ -0,0 +1 @@
+export declare function arraysAreTheSameLength(...arrays: unknown[][]): boolean;

package/dist/src/utils/json.d.ts

@@ -0,0 +1 @@
+export declare function jsonParseNoThrow<T>(doc: string): T | null;

package/dist/src/utils/string.d.ts

@@ -0,0 +1 @@
+export declare function isUUID(s: string): boolean;

package/e2e/global.d.ts

@@ -1,12 +1,25 @@
-import { Map } from "../src";
+import { Map, StyleSpecificationWithMetaData, type MapOptions } from "../src";
 
 declare global {
   interface Window {
     __map: Map;
     __pageObjects: Record<string, any>;
+    __pageLoadTimeout: number;
     notifyScreenshotStateReady: (data: TTestTransferData) => Promise<void>;
     notifyTest: (data: TTestTransferData) => Promise<void>;
+    setFixtureWithConfig: (config: { id: string; options: MapOptions; requiresScreenShot?: boolean }) => Promise<void>;
+    setFixtureMapStyle: (style: string | StyleSpecificationWithMetaData) => Promise<void>;
+    __MT_SDK_VERSION__: string;
+    __MT_NODE_ENV__: string | undefined;
+    __testUtils?: {
+      getHaloConfig: () => any;
+      getSpaceConfig: () => any;
+      hasHalo: () => boolean;
+      hasSpace: () => boolean;
+    };
   }
 
   type TTestTransferData = string | number | boolean | string[] | number[] | boolean[] | null | Record<string, unknown> | [number, number];
 }
+
+export {};

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/haloSpace.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>MapTiler E2E Halo Space</title>
+  <style>
+    #map {
+      width: 100vw;
+      height: 100vh;
+      border: 1px solid red;
+      background: repeating-conic-gradient(#eee 0% 25%, #ccc 0% 50%) 0% 0% / 40px 40px;
+    }
+
+    body {
+      margin: 0;
+      padding: 0;
+    }
+  </style>
+</head>
+<body>
+  <div id="map"></div>
+  <script type="module" src="/src/haloSpace.ts"></script>
+</body>
+</html>