@maptiler/sdk 2.2.2 → 2.4.0

package/dist/src/Map.d.ts

@@ -1,7 +1,7 @@
 import { default as maplibregl, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions } from 'maplibre-gl';
 import { ReferenceMapStyle, MapStyleVariant } from '@maptiler/client';
 import { SdkConfig } from './config';
-import { LanguageString } from './language';
+import { LanguageInfo } from './language';
 import { MinimapOptionsInput } from './Minimap';
 
 export type LoadWithTerrainEvent = {
@@ -32,7 +32,7 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo"> & {
      * or with a built-in shorthand (eg. Language.ENGLISH).
      * Note that this is equivalent to setting the `config.primaryLanguage` and will overwrite it.
      */
-    language?: LanguageString;
+    language?: LanguageInfo;
     /**
      * Define the MapTiler Cloud API key to be used. This is strictly equivalent to setting
      * `config.apiKey` and will overwrite it.
@@ -124,7 +124,15 @@ export declare class Map extends maplibregl.Map {
     private forceLanguageUpdate;
     private languageAlwaysBeenStyle;
     private isReady;
+    private terrainAnimationDuration;
+    private monitoredStyleUrls;
+    private styleInProcess;
     constructor(options: MapOptions);
+    /**
+     * Set the duration (millisec) of the terrain animation for growing or flattening.
+     * Must be positive. (Built-in default: `1000` milliseconds)
+     */
+    setTerrainAnimationDuration(d: number): void;
     /**
      * Awaits for _this_ Map instance to be "loaded" and returns a Promise to the Map.
      * If _this_ Map instance is already loaded, the Promise is resolved directly,
@@ -149,6 +157,7 @@ export declare class Map extends maplibregl.Map {
      * @returns
      */
     onLoadWithTerrainAsync(): Promise<Map>;
+    private monitorStyleUrl;
     /**
      * Update the style of the map.
      * Can be:
@@ -277,7 +286,7 @@ export declare class Map extends maplibregl.Map {
     /**
      * Define the primary language of the map. Note that not all the languages shorthands provided are available.
      */
-    setLanguage(language: LanguageString | string): void;
+    setLanguage(language: LanguageInfo | string): void;
     /**
      * Define the primary language of the map. Note that not all the languages shorthands provided are available.
      */
@@ -286,7 +295,7 @@ export declare class Map extends maplibregl.Map {
      * Get the primary language
      * @returns
      */
-    getPrimaryLanguage(): LanguageString;
+    getPrimaryLanguage(): LanguageInfo;
     /**
      * Get the exaggeration factor applied to the terrain
      * @returns

package/dist/src/MaptilerGeolocateControl.d.ts

@@ -15,7 +15,7 @@ export declare class MaptilerGeolocateControl extends GeolocateControl {
      * @private
      */
     _updateCamera: (position: GeolocationPosition) => void;
-    _setupUI: (supported: boolean) => void;
+    _finishSetupUI: (supported: boolean) => void;
     _updateCircleRadius(): void;
     _onZoom: () => void;
 }

package/dist/src/MaptilerNavigationControl.d.ts

@@ -1,10 +1,11 @@
+import { NavigationControlOptions } from 'maplibre-gl';
 import { NavigationControl } from './MLAdapters/NavigationControl';
 
 type HTMLButtonElementPlus = HTMLButtonElement & {
     clickFunction: (e?: Event) => unknown;
 };
 export declare class MaptilerNavigationControl extends NavigationControl {
-    constructor();
+    constructor(options?: NavigationControlOptions);
     /**
      * Overloading: the button now stores its click callback so that we can later on delete it and replace it
      */

package/dist/src/config.d.ts

@@ -1,5 +1,5 @@
 import { default as EventEmitter } from 'events';
-import { LanguageString } from './language';
+import { LanguageInfo } from './language';
 import { FetchFunction } from '@maptiler/client';
 import { Unit } from './unit';
 
@@ -11,12 +11,12 @@ declare class SdkConfig extends EventEmitter {
     /**
      * The primary language. By default, the language of the web browser is used.
      */
-    primaryLanguage: LanguageString;
+    primaryLanguage: LanguageInfo;
     /**
      * The secondary language, to overwrite the default language defined in the map style.
      * This settings is highly dependant on the style compatibility and may not work in most cases.
      */
-    secondaryLanguage?: LanguageString;
+    secondaryLanguage?: LanguageInfo;
     /**
      * Setting on whether of not the SDK runs with a session logic.
      * A "session" is started at the initialization of the SDK and finished when the browser

package/dist/src/defaults.d.ts

@@ -6,8 +6,8 @@ declare const defaults: {
     maptilerURL: string;
     maptilerApiHost: string;
     rtlPluginURL: string;
-    primaryLanguage: "style";
-    secondaryLanguage: "name";
+    primaryLanguage: import('@maptiler/client').LanguageInfo;
+    secondaryLanguage: import('@maptiler/client').LanguageInfo;
     terrainSourceURL: string;
     terrainSourceId: string;
 };

package/dist/src/helpers/index.d.ts

@@ -1,3 +1,4 @@
+import { takeScreenshot } from './screenshot';
 import { addPolyline, addPolygon, addPoint, addHeatmap } from './vectorlayerhelpers';
 
 export type { ZoomStringValues, ZoomNumberValues, PropertyValues, CommonShapeLayerOptions, PolylineLayerOptions, PolygonLayerOptions, PointLayerOptions, HeatmapLayerOptions, } from './vectorlayerhelpers';
@@ -9,4 +10,5 @@ export declare const helpers: {
     addPolygon: typeof addPolygon;
     addPoint: typeof addPoint;
     addHeatmap: typeof addHeatmap;
+    takeScreenshot: typeof takeScreenshot;
 };

package/dist/src/helpers/screenshot.d.ts

@@ -0,0 +1,19 @@
+import { Map as MapSDK } from '../Map';
+
+/**
+ * Takes a screenshot (PNG file) of the curent map view.
+ * Depending on the options, this function can automatically trigger a download of te file.
+ */
+export declare function takeScreenshot(map: MapSDK, options?: {
+    /**
+     * If `true`, this function will trigger a download in addition to returning a blob.
+     * Default: `false`
+     */
+    download?: boolean;
+    /**
+     * Only if `options.download` is `true`. Indicates the filename under which
+     * the file will be downloaded.
+     * Default: `"maptiler_screenshot.png"`
+     */
+    filename?: string;
+}): Promise<Blob>;

package/dist/src/index.d.ts

@@ -79,7 +79,8 @@ export * from './MaptilerGeolocateControl';
 export * from './MaptilerLogoControl';
 export * from './MaptilerTerrainControl';
 export * from './MaptilerNavigationControl';
-export { type AutomaticStaticMapOptions, type BoundedStaticMapOptions, type BufferToPixelDataFunction, type ByIdGeocodingOptions, type CenteredStaticMapOptions, type CommonForwardAndReverseGeocodingOptions, type CoordinateExport, type CoordinateGrid, type CoordinateId, type CoordinateSearch, type CoordinateSearchResult, type CoordinateTransformResult, type CoordinateTransformation, type Coordinates, type CoordinatesSearchOptions, type CoordinatesTransformOptions, type DefaultTransformation, type ElevationAtOptions, type ElevationBatchOptions, type FeatureHierarchy, type FetchFunction, type GeocodingFeature, type GeocodingOptions, type GeocodingSearchResult, type GeolocationInfoOptions, type GeolocationResult, type GetDataOptions, LanguageGeocoding, type LanguageGeocodingOptions, type LanguageGeocodingString, MapStyle, type MapStylePreset, type MapStyleType, MapStyleVariant, type PixelData, ReferenceMapStyle, type ReverseGeocodingOptions, ServiceError, type StaticMapBaseOptions, type StaticMapMarker, type TileJSON, type XYZ, bufferToPixelDataBrowser, circumferenceAtLatitude, coordinates, data, elevation, expandMapStyle, geocoding, geolocation, getAutoLanguageGeocoding, getBufferToPixelDataParser, getTileCache, mapStylePresetList, math, misc, staticMaps, styleToStyle, } from '@maptiler/client';
+export { type AutomaticStaticMapOptions, type BoundedStaticMapOptions, type BufferToPixelDataFunction, type ByIdGeocodingOptions, type CenteredStaticMapOptions, type CommonForwardAndReverseGeocodingOptions, type CoordinateExport, type CoordinateGrid, type CoordinateId, type CoordinateSearch, type CoordinateSearchResult, type CoordinateTransformResult, type CoordinateTransformation, type Coordinates, type CoordinatesSearchOptions, type CoordinatesTransformOptions, type DefaultTransformation, type ElevationAtOptions, type ElevationBatchOptions, type FeatureHierarchy, type FetchFunction, type GeocodingFeature, type GeocodingOptions, type GeocodingSearchResult, type GeolocationInfoOptions, type GeolocationResult, type GetDataOptions, type LanguageGeocodingOptions, MapStyle, type MapStylePreset, type MapStyleType, MapStyleVariant, type PixelData, ReferenceMapStyle, type ReverseGeocodingOptions, ServiceError, type StaticMapBaseOptions, type StaticMapMarker, type TileJSON, type XYZ, bufferToPixelDataBrowser, circumferenceAtLatitude, coordinates, data, elevation, expandMapStyle, geocoding, geolocation, getBufferToPixelDataParser, getTileCache, mapStylePresetList, math, misc, staticMaps, styleToStyle, type LanguageInfo, areSameLanguages, toLanguageInfo, isLanguageInfo, getAutoLanguage, getLanguageInfoFromFlag, getLanguageInfoFromCode, getLanguageInfoFromKey, } from '@maptiler/client';
+export { getWebGLSupportError } from './tools';
 export { config, SdkConfig } from './config';
 export * from './language';
 export { type Unit } from './unit';

package/dist/src/language.d.ts

@@ -1,142 +1,108 @@
-/**
- * Languages. Note that not all the languages of this list are available but the compatibility list may be expanded in the future.
- */
+import { LanguageInfo } from '@maptiler/client';
+
 declare const Language: {
+    readonly AUTO: LanguageInfo;
+    readonly LATIN: LanguageInfo;
+    readonly NON_LATIN: LanguageInfo;
+    readonly LOCAL: LanguageInfo;
+    readonly AMHARIC: LanguageInfo;
+    readonly ARABIC: LanguageInfo;
+    readonly AZERBAIJANI: LanguageInfo;
+    readonly BELARUSIAN: LanguageInfo;
+    readonly BULGARIAN: LanguageInfo;
+    readonly BENGALI: LanguageInfo;
+    readonly BRETON: LanguageInfo;
+    readonly BOSNIAN: LanguageInfo;
+    readonly CATALAN: LanguageInfo;
+    readonly CHINESE: LanguageInfo;
+    readonly TRADITIONAL_CHINESE: LanguageInfo;
+    readonly SIMPLIFIED_CHINESE: LanguageInfo;
+    readonly CORSICAN: LanguageInfo;
+    readonly CZECH: LanguageInfo;
+    readonly WELSH: LanguageInfo;
+    readonly DANISH: LanguageInfo;
+    readonly GERMAN: LanguageInfo;
+    readonly GREEK: LanguageInfo;
+    readonly ENGLISH: LanguageInfo;
+    readonly ESPERANTO: LanguageInfo;
+    readonly SPANISH: LanguageInfo;
+    readonly ESTONIAN: LanguageInfo;
+    readonly BASQUE: LanguageInfo;
+    readonly FINNISH: LanguageInfo;
+    readonly FRENCH: LanguageInfo;
+    readonly FRISIAN: LanguageInfo;
+    readonly IRISH: LanguageInfo;
+    readonly SCOTTISH_GAELIC: LanguageInfo;
+    readonly HEBREW: LanguageInfo;
+    readonly HINDI: LanguageInfo;
+    readonly CROATIAN: LanguageInfo;
+    readonly HUNGARIAN: LanguageInfo;
+    readonly ARMENIAN: LanguageInfo;
+    readonly INDONESIAN: LanguageInfo;
+    readonly ICELANDIC: LanguageInfo;
+    readonly ITALIAN: LanguageInfo;
+    readonly JAPANESE: LanguageInfo;
+    readonly JAPANESE_HIRAGANA: LanguageInfo;
+    readonly JAPANESE_2018: LanguageInfo;
+    readonly JAPANESE_KANA: LanguageInfo;
+    readonly JAPANESE_LATIN: LanguageInfo;
+    readonly GEORGIAN: LanguageInfo;
+    readonly KAZAKH: LanguageInfo;
+    readonly KANNADA: LanguageInfo;
+    readonly KOREAN: LanguageInfo;
+    readonly KOREAN_LATIN: LanguageInfo;
+    readonly KURDISH: LanguageInfo;
+    readonly CLASSICAL_LATIN: LanguageInfo;
+    readonly LUXEMBOURGISH: LanguageInfo;
+    readonly LITHUANIAN: LanguageInfo;
+    readonly LATVIAN: LanguageInfo;
+    readonly MACEDONIAN: LanguageInfo;
+    readonly MALAYALAM: LanguageInfo;
+    readonly MALTESE: LanguageInfo;
+    readonly DUTCH: LanguageInfo;
+    readonly NORWEGIAN: LanguageInfo;
+    readonly OCCITAN: LanguageInfo;
+    readonly POLISH: LanguageInfo;
+    readonly PERSIAN: LanguageInfo;
+    readonly PUNJABI: LanguageInfo;
+    readonly WESTERN_PUNJABI: LanguageInfo;
+    readonly PORTUGUESE: LanguageInfo;
+    readonly ROMANSH: LanguageInfo;
+    readonly ROMANIAN: LanguageInfo;
+    readonly RUSSIAN: LanguageInfo;
+    readonly SLOVAK: LanguageInfo;
+    readonly SLOVENE: LanguageInfo;
+    readonly ALBANIAN: LanguageInfo;
+    readonly SERBIAN_CYRILLIC: LanguageInfo;
+    readonly SERBIAN_LATIN: LanguageInfo;
+    readonly SWEDISH: LanguageInfo;
+    readonly TAMIL: LanguageInfo;
+    readonly TELUGU: LanguageInfo;
+    readonly THAI: LanguageInfo;
+    readonly TURKISH: LanguageInfo;
+    readonly UKRAINIAN: LanguageInfo;
+    readonly VIETNAMESE: LanguageInfo;
     /**
-     * The visitor language mode concatenates the prefered language from the user settings and the "default name".
-     * Note: The "default name" is equivalent to OSM's `{name}`, which can be the most recognized names a global
-     * scale or the local name.
-     * This mode is helpful in the context where a user needs to access both the local names and the names in their
-     * own language, for instance when traveling abroad, where signs likely to be only available in the local language.
-     */
-    readonly VISITOR: "visitor";
-    /**
-     * The visitor language mode concatenates English and the "default name".
-     * Note: The "default name" is equivalent to OSM's `{name}`, which can be the most recognized names a global
-     * scale or the local name.
-     * This mode is helpful in the context where a user needs to access both the local names and the names in their
-     * own language, for instance when traveling abroad, where signs likely to be only available in the local language.
-     */
-    readonly VISITOR_ENGLISH: "visitor_en";
-    /**
-     * Language as the style is designed. Not that this is the default state and one
-     * the language has been changed to another than `STYLE`, then it cannot be set back to `STYLE`.
-     */
-    readonly STYLE: "style";
-    /**
-     * AUTO mode uses the language of the browser
-     */
-    readonly AUTO: "auto";
-    /**
-     * STYLE is a custom flag to keep the language of the map as defined into the style.
-     * If STYLE is set in the constructor, then further modification of the language
-     * with `.setLanguage()` is not possible.
+     * Language mode to display labels in both the local language and the language of the visitor's device, concatenated.
+     * Note that if those two languages are the same, labels won't be duplicated.
      */
-    readonly STYLE_LOCK: "style_lock";
+    readonly VISITOR: LanguageInfo;
     /**
-     * Default fallback languages that uses latin charaters
+     * Language mode to display labels in both the local language and English, concatenated.
+     * Note that if those two languages are the same, labels won't be duplicated.
      */
-    readonly LATIN: "name:latin";
+    readonly VISITOR_ENGLISH: LanguageInfo;
     /**
-     * Default fallback languages that uses non-latin charaters
+     * Language mode to display labels in a language enforced in the style.
      */
-    readonly NON_LATIN: "name:nonlatin";
+    readonly STYLE: LanguageInfo;
     /**
-     * Labels are in their local language, when available
+     * Language mode to display labels in a language enforced in the style. The language cannot be further modified.
      */
-    readonly LOCAL: "name";
-    /**
-     * International name
-     */
-    readonly INTERNATIONAL: "name_int";
-    readonly ALBANIAN: "name:sq";
-    readonly AMHARIC: "name:am";
-    readonly ARABIC: "name:ar";
-    readonly ARMENIAN: "name:hy";
-    readonly AZERBAIJANI: "name:az";
-    readonly BASQUE: "name:eu";
-    readonly BELORUSSIAN: "name:be";
-    readonly BENGALI: "name:bn";
-    readonly BOSNIAN: "name:bs";
-    readonly BRETON: "name:br";
-    readonly BULGARIAN: "name:bg";
-    readonly CATALAN: "name:ca";
-    readonly CHINESE: "name:zh";
-    readonly TRADITIONAL_CHINESE: "name:zh-Hant";
-    readonly SIMPLIFIED_CHINESE: "name:zh-Hans";
-    readonly CORSICAN: "name:co";
-    readonly CROATIAN: "name:hr";
-    readonly CZECH: "name:cs";
-    readonly DANISH: "name:da";
-    readonly DUTCH: "name:nl";
-    readonly ENGLISH: "name:en";
-    readonly ESPERANTO: "name:eo";
-    readonly ESTONIAN: "name:et";
-    readonly FINNISH: "name:fi";
-    readonly FRENCH: "name:fr";
-    readonly FRISIAN: "name:fy";
-    readonly GEORGIAN: "name:ka";
-    readonly GERMAN: "name:de";
-    readonly GREEK: "name:el";
-    readonly HEBREW: "name:he";
-    readonly HINDI: "name:hi";
-    readonly HUNGARIAN: "name:hu";
-    readonly ICELANDIC: "name:is";
-    readonly INDONESIAN: "name:id";
-    readonly IRISH: "name:ga";
-    readonly ITALIAN: "name:it";
-    readonly JAPANESE: "name:ja";
-    readonly JAPANESE_HIRAGANA: "name:ja-Hira";
-    readonly JAPANESE_KANA: "name:ja_kana";
-    readonly JAPANESE_LATIN: "name:ja_rm";
-    readonly JAPANESE_2018: "name:ja-Latn";
-    readonly KANNADA: "name:kn";
-    readonly KAZAKH: "name:kk";
-    readonly KOREAN: "name:ko";
-    readonly KOREAN_LATIN: "name:ko-Latn";
-    readonly KURDISH: "name:ku";
-    readonly ROMAN_LATIN: "name:la";
-    readonly LATVIAN: "name:lv";
-    readonly LITHUANIAN: "name:lt";
-    readonly LUXEMBOURGISH: "name:lb";
-    readonly MACEDONIAN: "name:mk";
-    readonly MALAYALAM: "name:ml";
-    readonly MALTESE: "name:mt";
-    readonly NORWEGIAN: "name:no";
-    readonly OCCITAN: "name:oc";
-    readonly PERSIAN: "name:fa";
-    readonly POLISH: "name:pl";
-    readonly PORTUGUESE: "name:pt";
-    readonly PUNJABI: "name:pa";
-    readonly WESTERN_PUNJABI: "name:pnb";
-    readonly ROMANIAN: "name:ro";
-    readonly ROMANSH: "name:rm";
-    readonly RUSSIAN: "name:ru";
-    readonly SCOTTISH_GAELIC: "name:gd";
-    readonly SERBIAN_CYRILLIC: "name:sr";
-    readonly SERBIAN_LATIN: "name:sr-Latn";
-    readonly SLOVAK: "name:sk";
-    readonly SLOVENE: "name:sl";
-    readonly SPANISH: "name:es";
-    readonly SWEDISH: "name:sv";
-    readonly TAMIL: "name:ta";
-    readonly TELUGU: "name:te";
-    readonly THAI: "name:th";
-    readonly TURKISH: "name:tr";
-    readonly UKRAINIAN: "name:uk";
-    readonly URDU: "name:ur";
-    readonly VIETNAMIAN_LATIN: "name:vi";
-    readonly WELSH: "name:cy";
+    readonly STYLE_LOCK: LanguageInfo;
 };
-declare function isLanguageSupported(lang: string): boolean;
-/**
- * Type representing the key of the Language object
- */
-type LanguageKey = keyof typeof Language;
-type Values<T> = T[keyof T];
 /**
- * Built-in languages values as strings
+ * Get the browser language
  */
-type LanguageString = Values<typeof Language>;
-declare function getBrowserLanguage(): LanguageString;
-export { Language, type LanguageString, type LanguageKey, getBrowserLanguage, isLanguageSupported };
+export declare function getBrowserLanguage(): LanguageInfo;
+export { Language, type LanguageInfo };

package/dist/src/mapstyle.d.ts

@@ -1,3 +1,18 @@
 import { ReferenceMapStyle, MapStyleVariant } from '@maptiler/client';
 
-export declare function styleToStyle(style: string | ReferenceMapStyle | MapStyleVariant | maplibregl.StyleSpecification | null | undefined): string | maplibregl.StyleSpecification;
+export declare function styleToStyle(style: string | ReferenceMapStyle | MapStyleVariant | maplibregl.StyleSpecification | null | undefined): {
+    style: string | maplibregl.StyleSpecification;
+    requiresUrlMonitoring: boolean;
+    isFallback: boolean;
+};
+/**
+ * makes sure a URL is absolute
+ */
+export declare function urlToAbsoluteUrl(url: string): string;
+type StyleValidationReport = {
+    isValidJSON: boolean;
+    isValidStyle: boolean;
+    styleObject: maplibregl.StyleSpecification | null;
+};
+export declare function convertToStyleSpecificationString(str: string): StyleValidationReport;
+export {};

package/dist/src/tools.d.ts

@@ -44,3 +44,7 @@ export declare function getWebGLSupportError(): string | null;
  * Display an error message in the Map div if WebGL2 is not supported
  */
 export declare function displayNoWebGlWarning(container: HTMLElement | string): void;
+/**
+ * Display an error message in the Map div if WebGL2 is not supported
+ */
+export declare function displayWebGLContextLostWarning(container: HTMLElement | string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maptiler/sdk",
-  "version": "2.2.2",
+  "version": "2.4.0",
   "description": "The Javascript & TypeScript map SDK tailored for MapTiler Cloud",
   "module": "dist/maptiler-sdk.mjs",
   "types": "dist/maptiler-sdk.d.ts",
@@ -39,30 +39,33 @@
     "doc": "rm -rf docs/* && typedoc --out docs && cp -r images docs/",
     "test": "vitest run",
     "build-css": "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": "NODE_ENV=production tsc && vite build -c vite.config-umd.ts",
-    "build-es": "NODE_ENV=production tsc && 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 biome:fix && npm run build"
+    "make": "npm run biome:fix && npm run build",
+    "dev-umd": "npm run build-css && tsc && NODE_ENV=dev vite build -w -c vite.config-umd.ts",
+    "help": "vite build --help"
   },
   "author": "MapTiler",
   "devDependencies": {
     "@biomejs/biome": "1.8.3",
     "@types/uuid": "^9.0.2",
     "@types/xmldom": "^0.1.31",
+    "@xmldom/xmldom": "^0.8.10",
     "serve": "^14.2.0",
     "terser": "^5.17.1",
     "typedoc": "^0.24.8",
     "typescript": "^5.1.6",
-    "vitest": "^0.34.2",
     "vite": "^5.3.4",
-    "vite-plugin-dts": "^4.0.0-beta.0"
+    "vite-plugin-dts": "^4.0.0-beta.0",
+    "vitest": "^0.34.2"
   },
   "dependencies": {
-    "@maptiler/client": "^1.8.1",
+    "@maplibre/maplibre-gl-style-spec": "^20.3.1",
+    "@maptiler/client": "^2.0.0",
     "events": "^3.3.0",
     "js-base64": "^3.7.4",
-    "maplibre-gl": "4.4.1",
-    "uuid": "^9.0.0",
-    "xmldom": "^0.6.0"
+    "maplibre-gl": "4.7.1",
+    "uuid": "^9.0.0"
   }
 }

package/readme.md

@@ -76,6 +76,37 @@ For example, with a [NextJS](https://nextjs.org/) app, this can take place at th
 import "@maptiler/sdk/dist/maptiler-sdk.css";
 ```
 
+### TypeScript
+The SDK is fully typed, but it may happen that types defined in Maplibre GL JS are not visible in your project. This is a known issue that comes from Maplibre being a CommonJS bundle.
+
+There are mainly two ways to addess this issue and access to the complete type definition.
+
+1. **With `esModuleInterop`**  
+
+Set the following in your `tsconfig.json`:
+```js
+{
+  "compilerOptions": {
+    // ...
+    "esModuleInterop": true,
+  }
+}
+``` 
+
+2. **With `moduleResolution`**  
+
+Set the following in your `tsconfig.json`:
+```js
+{
+  "compilerOptions": {
+    // ...
+    "moduleResolution": "Bundler",
+  }
+}
+``` 
+Note that this second option is not always possible as some frameworks and other dependencies won't let you use the "Bundler" mode.
+
+
 
 ## With CDN
 The SDK hosted on our CDN is bundled as *[Universal Module Definition](https://github.com/umdjs/umd)* (UMD) to make it standalone and contain all its dependencies. The CDN also serves the style sheet (CSS).
@@ -340,6 +371,55 @@ map.disableTerrain()
 
 > 📣 *__Note 2:__* please be aware that due to the volume and elevation of the map floor in 3D space, the navigation with the terrain enabled is slightly different than without.
 
+By default, enabling, disabling or even just updating the terrain exaggeration will result in a 1-second animation. This is possible to modify with the following `Map` method:
+
+```ts
+// Duration in milliseconds
+map.setTerrainAnimationDuration(500);
+```
+
+## Terrain events
+- `"terrain"` event  
+
+As an extension of Maplibre GL JS, MapTiler SDK is also exposing the terrain event `"terrain"`. This event is triggered when a terrain source is added or removed:
+
+```ts
+map.on("terrain", (e) => {
+  // your logic here
+})
+```
+
+Since MapTiler SDK adds animation and the terrain data is necessary all along, the `"terrain"` event will be called at the very begining of the terrain animation when enabling and at the very end when disabling.
+
+- `"terrainAnimationStart"` and `"terrainAnimationStop"` events  
+
+With the animation of the terrain, it can sometimes be convenient to know when the animation starts and ends. These two events are made just for that, here are how they work:
+
+```ts
+map.on("terrainAnimationStart", (event) => {
+  console.log("Terrain animation is starting...");
+});
+
+map.on("terrainAnimationStop", (event) => {
+  console.log("Terrain animation is finished");
+});
+```
+
+The `event` argument is an object that contains (amond other things) a `terrain` attribute. In the case of `"terrainAnimationStop"`, this terrain attribute is `null` if the animation was about disabling the terrain, otherwise, this is just a propagation of `map.terrain`.
+
+In the following example, we decide to associate the terrain animation with a change of camera, e.g. from clicking on the terrain control:
+- when the terrain is enabled, it pops up with an animation and only **then** the camera is animated to take a lower point of view
+- when the terrain is disabled, it is flattened with an animation and only **then** the camera is animated to a top view
+
+```ts
+map.on("terrainAnimationStop", (e) => {
+  map.easeTo({
+    pitch: e.terrain ? 60 : 0,
+    duration: 500,
+  });
+});
+```
+
 
 # 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.
@@ -565,6 +645,27 @@ We believe that the *promise* approach is better because it does not nest scopes
 
 > 📣 *__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`, `ready` and `loadWithTerrain` events but not for events that may be called multiple time such as interaction events.
 
+### The `webglContextLost` event
+The maps is rendered with WebGL, that leverages the GPU to provide high-performance graphics. In some cases, the host machine, operating system or the graphics driver, can decide that continuing to run such high performance graphics is unsustainable, and will abort the process. This is called a "WebGL context loss". Such situation happens when the ressources are running low or when multiple browser tabs are competing to access graphics memory.  
+
+The best course of action in such situation varies from an app to another. Sometimes a page refresh is the best thing to do, in other cases, instantiating a new Map dynmicaly at application level is more appropriate because it hides a technical failure to the end user. The event `webglContextLost` is exposed so that the most appropriate scenario can be implemented at application level.   
+
+Here is how to respond to a WebGL context loss with a simple page refresh:
+```ts
+
+// Init the map
+const map = new maptilersdk.Map({
+  container: "map-container",
+  hash: true,
+})
+
+// Refresh the page if context is lost.
+// Since `hash` is true, the location will be the same as before
+map.on("webglContextLost", (e) => {
+  location.reload();
+})
+```
+
 # Color Ramps
 A color ramp is a color gradient defined in a specific interval, for instance in [0, 1], and for any value within this interval will retrieve a color. They are defined by at least a color at each bound and usually additional colors within the range.  
 
@@ -862,6 +963,37 @@ 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 helper
+## Take Screenshots, programmatically
+There are two different ways to create screenshot, corresponding to two very different usecases. Note that screenshots will not contain *DOM elements* such as `Marker` and `Popup`, since those are not part of the rendering context.
+
+**1. Get a `blob` of a screenshot, PNG encoded:**
+```ts
+import { Map, helpers } from "@maptiler/sdk";
+
+// ... initialize a Map instance, wait for the "load" or "ready" event ...
+
+// Inside an async function, or with using .then()
+const blob = await helpers.takeScreenshot(map);
+```
+The returned `Blob` of a PNG image file can be very handy if the goal is to programmatically further manipulate the screenshot, such as sending it to some feedback endpoint with a POST request.
+
+**2. Download a PNG file:**
+```ts
+import { Map, helpers } from "@maptiler/sdk";
+
+// ... initialize a Map instance, wait for the "load" or "ready" event ...
+
+// No need to be inside an async function, the download will be triggered when the file is ready
+maptilersdk.helpers.takeScreenshot(map, {
+  download: true, 
+  filename: "map_screenshot.png"
+});
+```
+Getting a file directly is a nice option that can be useful to share some debugging context with colleagues, compare multiple styles, or share your creation on social media.
+
+> 📣 *__Note:__* Keep in mind that MapTiler Cloud data are copyrighted and their usage is restricted. This include MapTiler built-in styles and tilesets, among others. In case of doubt, do not hesitate to read our [terms](https://www.maptiler.com/terms/) or to ask our [support team](https://www.maptiler.com/contacts/).
+
 # Caching
 Starting from v2, MapTiler SDK introduced the **caching** of tiles and fonts served by MapTiler Cloud, which can represent a large chunk of the data being fetched when browsing a map. This caching leverages modern browsers caching API so it's well-managed and there is no risk of bloating! When we update **MapTiler Planet** or our **official styles**, the caching logic will detect it and automatically invalidate older versions of the tiles that were previously cached.
 

package/vite.config-es.ts

@@ -12,6 +12,7 @@ export default defineConfig({
   mode: isProduction ? "production" : "development",
   build: {
     minify: isProduction,
+    emptyOutDir: isProduction,
     outDir: "dist",
     sourcemap: true,
     lib: {
@@ -35,7 +36,6 @@ export default defineConfig({
         "events", 
         "js-base64", 
         "geojson-validation",
-        "xmldom",
       ],
       output: {
         // Provide global variables to use in the UMD build