@maptiler/sdk 3.4.0-rc3 → 3.4.0

package/dist/src/utils/webgl-utils.d.ts

@@ -0,0 +1,49 @@
+export type WebGLContext = WebGLRenderingContext | WebGL2RenderingContext;
+/**
+ * Load a shader from a source string
+ */
+export declare function loadShader({ gl, type, source }: {
+    gl: WebGLContext;
+    type: GLenum;
+    source: string;
+}): WebGLShader;
+/**
+ * Create a set of shaders (vertex and fragment) and link them into a program
+ *
+ * @param gl WebGL context
+ * @param vertexShaderSource Vertex shader source code
+ * @param fragmentShaderSource Fragment shader source code
+ *
+ * @returns WebGL program
+ */
+export declare function createShadersSetProgram({ gl, vertexShaderSource, fragmentShaderSource }: {
+    gl: WebGLContext;
+    vertexShaderSource: string;
+    fragmentShaderSource: string;
+}): WebGLProgram;
+/**
+ * null-free version of getUniformLocation
+ */
+export declare function getUniformLocation(gl: WebGLRenderingContext | WebGL2RenderingContext, program: WebGLProgram, name: string): WebGLUniformLocation;
+export type Object3D<Attribute extends string, Uniform extends string> = {
+    shaderProgram: WebGLProgram;
+    programInfo: {
+        attributesLocations: Record<Attribute, number>;
+        uniformsLocations: Record<Uniform, WebGLUniformLocation>;
+    };
+    positionBuffer: WebGLBuffer;
+    indexBuffer?: WebGLBuffer;
+    indexBufferLength?: number;
+};
+export declare function createObject3D<Attribute extends string, Uniform extends string>({ gl, vertexShaderSource, fragmentShaderSource, attributesKeys, uniformsKeys, vertices, indices, }: {
+    gl: WebGLContext;
+    vertexShaderSource: string;
+    fragmentShaderSource: string;
+    attributesKeys: readonly Attribute[];
+    uniformsKeys: readonly Uniform[];
+    vertices: Array<number>;
+    indices?: Array<number>;
+}): Object3D<Attribute, Uniform>;
+export type Vec4 = [number, number, number, number];
+export declare function parseColorStringToVec4(color?: string): Vec4;
+export declare function degreesToRadians(degrees: number): number;

package/eslint.config.mjs

@@ -1,4 +1,4 @@
-// @ts-check
+// @ts-nocheck
 
 import tseslint from "typescript-eslint";
 import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";
@@ -50,6 +50,7 @@ export default tseslint.config(
                           node.specifiers.forEach((specifier) => {
                             if (specifier.type !== "ImportDefaultSpecifier") {
                               context.report({
+                                // @ts-expect-error `message` seems to work with this...
                                 message: config.message ?? `Importing from '${bannedImport}' is banned in '${fp}'`,
                                 node,
                               });
@@ -103,10 +104,10 @@ export default tseslint.config(
       "@typescript-eslint/no-inferrable-types": "off",
       "@typescript-eslint/no-misused-promises": "warn",
       "@typescript-eslint/no-unnecessary-boolean-literal-compare": "off",
-      "@typescript-eslint/no-unnecessary-condition": "off", // we have the potential for a lot of user input that is not validated
+      "@typescript-eslint/no-unnecessary-condition": "warn",
       "@typescript-eslint/no-unnecessary-type-arguments": "off",
       "@typescript-eslint/no-unnecessary-type-assertion": "off",
-      "@typescript-eslint/no-unnecessary-type-parameters": "warn",
+      "@typescript-eslint/no-unnecessary-type-parameters": "off", // as we are a lib, types serve as documentation
       "@typescript-eslint/no-unused-vars": "warn",
       "@typescript-eslint/no-unsafe-argument": "warn",
       "@typescript-eslint/no-unsafe-assignment": "warn",
@@ -115,7 +116,7 @@ export default tseslint.config(
       "@typescript-eslint/no-unsafe-member-access": "warn",
       "@typescript-eslint/no-unsafe-return": "warn",
       "@typescript-eslint/no-non-null-assertion": "warn",
-      "@typescript-eslint/non-nullable-type-assertion-style": "off",
+      "@typescript-eslint/non-nullable-type-assertion-style": "warn",
       "@typescript-eslint/prefer-for-of": "off",
       "@typescript-eslint/prefer-nullish-coalescing": "warn",
       "@typescript-eslint/prefer-optional-chain": "off",
@@ -124,7 +125,6 @@ export default tseslint.config(
       "@typescript-eslint/restrict-plus-operands": "warn",
       "@typescript-eslint/restrict-template-expressions": "warn",
       "@typescript-eslint/related-getter-setter-pairs": "off",
-      "@typescript-restrict-template-expressions": "off",
       "@typescript-eslint/unbound-method": "warn",
       "@typescript-eslint/use-unknown-in-catch-callback-variable": "warn",
     },

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@maptiler/sdk",
-  "version": "3.4.0-rc3",
+  "version": "3.4.0",
   "description": "The Javascript & TypeScript map SDK tailored for MapTiler Cloud",
   "author": "MapTiler",
   "module": "dist/maptiler-sdk.mjs",
   "types": "dist/maptiler-sdk.d.ts",
   "style": "dist/maptiler-sdk.css",
   "type": "module",
+  "main": "dist/maptiler-sdk.mjs",
   "exports": {
     ".": {
       "import": "./dist/maptiler-sdk.mjs",
@@ -36,32 +37,33 @@
   },
   "scripts": {
     "prepare": "husky",
-    "docs:md": "rm -rf docs/* && typedoc --plugin typedoc-plugin-markdown --out docs --readme none",
-    "docs:html": "rm -rf docs-html/* && typedoc --out docs-html",
+    "doc": "rm -rf docs/* && typedoc --out docs && cp -r images docs/",
     "ncu": "npx npm-check-updates",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
+    "lint": "tsc --noEmit && eslint src",
+    "lint:fix": "tsc --noEmit && eslint src --fix",
     "test:watch": "vitest watch -c vite.config-test.ts --dom",
     "test": "vitest run -c vite.config-test.ts --dom",
     "install:clean": "rm -rf build/ dist/ node_modules/ && npm ci",
-    "dev": "concurrently \"vite -c vite.config-dev.ts\" \"npm run dev-umd\"",
+    "dev": "npm run build-css && vite -c vite.config-dev.ts",
     "dev-umd": "npm run build-css && tsc && NODE_ENV=development vite build -w -c vite.config-umd.ts",
     "build-css": "mkdir -p dist build && node scripts/replace-path-with-content.js src/style/style_template.css dist/tmp_maptiler-sdk.css && cat node_modules/maplibre-gl/dist/maplibre-gl.css dist/tmp_maptiler-sdk.css > dist/maptiler-sdk.css && rm dist/tmp_maptiler-sdk.css && cp dist/maptiler-sdk.css build/maptiler-sdk.css",
-    "build-umd": "tsc -b && NODE_ENV=production vite build -c vite.config-umd.ts",
-    "build-es": "tsc -b && NODE_ENV=production vite build -c vite.config-es.ts",
+    "build-umd": "tsc && NODE_ENV=production vite build -c vite.config-umd.ts",
+    "build-es": "tsc && NODE_ENV=production vite build -c vite.config-es.ts",
     "build": "npm run build-es; npm run build-umd; npm run build-css",
-    "make": "npm run install:clean && npm run build",
-    "e2e:serve": "tsc --project ./e2e && NODE_ENV=development vite -c vite.config-e2e.ts",
-    "e2e:local": "npx playwright test --config=playwright.config.ts --ui",
-    "e2e:watch": "concurrently \"npm run e2e:serve\" \"npm run e2e:local\""
+    "make": "npm run install:clean && npm run build"
   },
   "lint-staged": {
     "*.ts": "npm run lint:fix"
   },
+  "ts-typecheck": {
+    "*.ts": "npm tsc --noEmit"
+  },
   "devDependencies": {
     "@canvas/image-data": "^1.0.0",
     "@eslint/js": "^9.21.0",
-    "@playwright/test": "^1.52.0",
+    "@types/color-convert": "^2.0.4",
+    "@types/color-name": "^2.0.0",
+    "@types/stats.js": "^0.17.4",
     "@types/uuid": "^10.0.0",
     "@types/xmldom": "^0.1.31",
     "@vitest/web-worker": "^3.0.9",
@@ -72,11 +74,11 @@
     "eslint-plugin-prettier": "^5.2.3",
     "happy-dom": "^17.4.4",
     "husky": "^8.0.0",
+    "jiti": "^2.4.2",
     "lint-staged": "^15.4.3",
-    "playwright": "^1.52.0",
     "prettier": "3.5.2",
-    "typedoc": "^0.28.3",
-    "typedoc-plugin-markdown": "^4.6.3",
+    "stats.js": "^0.17.0",
+    "typedoc": "^0.27.6",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.25.0",
     "vite": "^6.0.7",
@@ -87,8 +89,9 @@
     "@maplibre/maplibre-gl-style-spec": "^23.0.0",
     "@maptiler/client": "^2.3.2",
     "events": "^3.3.0",
+    "gl-matrix": "^3.4.3",
     "js-base64": "^3.7.7",
-    "maplibre-gl": "^5.3.1",
+    "maplibre-gl": "^5.5.0",
     "uuid": "^11.0.5"
   }
 }

package/tsconfig.json

@@ -23,15 +23,20 @@
     "declaration": true,
     "allowSyntheticDefaultImports": true,
     "allowJs": true,
-    "noEmitOnError": true,
   },
+  "exclude": [
+    "vite.config-*.ts",
+    "vitest-setup-tests.ts",
+    "dist"
+  ],
   "include": [
+    "vite.config-dev.ts",
+    "vite.config-es.ts",
+    "vite.config-umd.ts",
+    "vite.config-test.ts",
+    "vitest-setup-tests.ts",
     "src",
-    "test",
-    "./vite.config-test.ts",
-    "./vite.config-e2e.ts",
-    "./vite.config-umd.ts",
-    "./playwright.config.ts",
-    "./vitest-setup-tests.ts"
+    "demos",
+    "test"
   ],
 }

package/typedoc.json

@@ -1,8 +1,7 @@
 {
-  "entryPoints": [
-    "./src/index.ts",
-  ],
+  "entryPoints": ["./src/index.ts"],
   "name": "MapTiler SDK",
+  "out": "docs",
   "excludePrivate": true,
   "excludeProtected": true,
   "excludeExternals": true,

package/dist/playwright.config.d.ts

@@ -1,9 +0,0 @@
-/**
- * Read environment variables from file.
- * https://github.com/motdotla/dotenv
- */
-/**
- * See https://playwright.dev/docs/test-configuration.
- */
-declare const _default: import('@playwright/test').PlaywrightTestConfig<{}, {}>;
-export default _default;

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

@@ -1,291 +0,0 @@
-import { AnimationEvent, AnimationEventTypes, EasingFunctionName, Keyframe } from '../utils/MaptilerAnimation/types';
-import { default as MaptilerAnimation, MaptilerAnimationOptions } from '../utils/MaptilerAnimation/MaptilerAnimation';
-import { CustomLayerInterface, Map } from '../index';
-export type SourceData = {
-    id: string;
-    featureSetIndex: number;
-    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',
- *     featureSetIndex: 0
- *   },
- *   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',
- *     featureSetIndex: 0
- *   },
- *   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(AnimationEventTypes.Finish, () => {
- *   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;
-    /**
-     * 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 {Map} map - The map instance
-     */
-    onAdd(map: Map): Promise<void>;
-    /**
-     * 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/utils/MaptilerAnimation/AnimationManager.d.ts

@@ -1,41 +0,0 @@
-import { default as MaptilerAnimation } from './MaptilerAnimation';
-/**
- * Manager for handling animation lifecycle and updates.
- *
- * The AnimationManager provides a centralized system for registering and
- * coordinating multiple animations. To avoid individual calls to request animation frame
- * for each animation, it maintains an animation loop
- *
- * This is not a class as it never needs to be instantiated,
- * it's just a singeton object.
- *
- * It's not called directly but used within the MaptilerAnimation class.
- */
-declare const AnimationManager: {
-    animations: MaptilerAnimation[];
-    running: boolean;
-    /**
-     * Adds an animation to the manager. If this is the first animation added,
-     * it starts the animation loop.
-     *
-     * @param {MaptilerAnimation} animation - The animation to add.
-     */
-    add(animation: MaptilerAnimation): void;
-    /**
-     * Removes an animation from the manager. If there are no more animations,
-     * it stops the animation loop.
-     *
-     * @param {MaptilerAnimation} animation - The animation to remove.
-     */
-    remove(animation: MaptilerAnimation): void;
-    /**
-     * Stops the animation loop.
-     */
-    stop(): void;
-    /**
-     * Starts the animation loop. This function is called recursively using
-     * requestAnimationFrame to ensure smooth updates.
-     */
-    start(): void;
-};
-export default AnimationManager;