@maptiler/sdk 2.3.0 → 2.4.1

package/dist/src/Map.d.ts

@@ -28,11 +28,12 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo"> & {
      */
     style?: ReferenceMapStyle | MapStyleVariant | StyleSpecification | string;
     /**
-     * Define the language of the map. This can be done directly with a language ISO code (eg. "en")
+     * Define the language of the map. This can be done directly with a language ISO code (eg. "en"),
+     * the ISO code prepended with the OSM flag (eg. "name:en" or even just "name"),
      * or with a built-in shorthand (eg. Language.ENGLISH).
      * Note that this is equivalent to setting the `config.primaryLanguage` and will overwrite it.
      */
-    language?: LanguageInfo;
+    language?: LanguageInfo | string;
     /**
      * Define the MapTiler Cloud API key to be used. This is strictly equivalent to setting
      * `config.apiKey` and will overwrite it.
@@ -124,7 +125,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 +158,7 @@ export declare class Map extends maplibregl.Map {
      * @returns
      */
     onLoadWithTerrainAsync(): Promise<Map>;
+    private monitorStyleUrl;
     /**
      * Update the style of the map.
      * Can be:

package/dist/src/index.d.ts

@@ -80,6 +80,7 @@ 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, 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/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.3.0",
+  "version": "2.4.1",
   "description": "The Javascript & TypeScript map SDK tailored for MapTiler Cloud",
   "module": "dist/maptiler-sdk.mjs",
   "types": "dist/maptiler-sdk.d.ts",
@@ -61,10 +61,11 @@
     "vitest": "^0.34.2"
   },
   "dependencies": {
+    "@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.7.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.
@@ -388,7 +468,7 @@ Whenever a label is not supported in the defined language, it falls back to `Lan
 Here is a sample of some compatible languages:
 ![](images/screenshots/multilang.gif)
 
-# Built-in support for right-to-left languages
+## Built-in support for right-to-left languages
 Languages that are written right-to-left such as Arabic and Hebrew are fully supported by default. No need to install any plugins!
 
 <p align="center">
@@ -396,6 +476,31 @@ Languages that are written right-to-left such as Arabic and Hebrew are fully sup
   <img src="images/screenshots/lang-hebrew.jpeg" width="48%"></img>
 </p>
 
+## Visitor language modes
+The *visitor* language modes are special built-in modes made to display labels in two different languages, concatenated when available:
+- `Language.VISITOR` concatenates labels in the language of your system and the *local* language
+- `Language.VISITOR_ENGLISH` concatenates labels in English and the *local* language
+
+```ts
+const map = new Map({
+  // some options...
+  language: Language.VISITOR,
+})
+
+// or
+
+const map = new Map({
+  // some options...
+  language: Language.VISITOR_ENGLISH,
+})
+```
+
+We believe these two modes can be very handy to help the end users identify places, especially when the local labels are not using a latin charset. Here is how it looks like:
+
+![](images/screenshots/visitor_athen.png)
+![](images/screenshots/visitor_osaka.png)
+
+
 # Custom Events and Map Lifecycle
 ## Events
 ### The `ready` event
@@ -565,6 +670,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.