@maptiler/sdk 1.0.5 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maptiler/sdk",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "The Javascript & TypeScript map SDK tailored for MapTiler Cloud",
   "module": "dist/maptiler-sdk.mjs",
   "types": "dist/maptiler-sdk.d.ts",

package/readme.md

@@ -50,6 +50,21 @@ const map = new maptilersdk.Map({
   container: mapContainer,
 });
 ```
+
+Alternativelly, the `apiKey` can be set as Map option intead of in the `config` object. Yet, this will still internally propagate to the `config` obejct:
+```ts
+import * as maptilersdk from '@maptiler/sdk';
+
+// Let's say you have a DIV ready to receive a map
+const mapContainer = document.getElementById('my-container-div');
+
+// Instanciate the map
+const map = new maptilersdk.Map({
+  container: mapContainer,
+  apiKey: 'YOUR_API_KEY';
+});
+```
+
 By default, the map will be initialized with the style [streets-v2](https://www.maptiler.com/maps/#style=streets-v2).
 
 Depending on the framework and environment your are using for your application, you will have to also include the CSS file. 
@@ -320,19 +335,47 @@ map.disableTerrain()
 
 
 # Easy language switching
-The language generally depends on the style but we made it possible to easily update it with a single function and from a built-in list of languages:
+The language generally depends on the style but we made it possible to easily set and update from a built-in list of languages.
+
+The builtin list of supported languages is accessible from the `Language` object:
+```ts
+import { Language } from "@maptiler/sdk";
+```
+In the UMD bundle, it will be directly at `maptilersdk.Language`.
+
+There three distinct ways to set the language of a map:
+
+1. **Global way, using the config object:**
+```ts
+import { config } from "@maptiler/sdk";
+
+config.primaryLanguage = Language.ENGLISH;
+```
+Then, the if any further language is setting is applied, all the map instances created afterward will use this language. 
 
+2. **Set the language at instanciation time:**
 ```ts
-map.setLanguage(maptilersdk.Language.ENGLISH);
+const map = new Map({
+  // some options...
+  language: Language.ENGLISH, // the ISO codes can also be used (eg. "en")
+})
 ```
+It will only apply `ENGLISH` as the language of this specific map instance (and will not alter the global `config`).
+
+3. **Set the language after the map has been instanciated:**
+```ts
+map.setLanguage(Language.ENGLISH);
+```
+Again, it will only apply `ENGLISH` as the language of this specific map instance (and will not alter the global `config`).
+
 
 The list of supported languages is built-in and can be found [here](src/language.ts). In addition, there are spacial language *flags*:
-- `maptilersdk.Language.AUTO` **[DEFAULT]** uses the language defined in the web browser
-- `maptilersdk.Language.LOCAL` uses the language local to each country
-- `maptilersdk.Language.LATIN` uses a default with latin characters
-- `maptilersdk.Language.NON_LATIN` uses a default with non-latin characters
+- `Language.AUTO` **[DEFAULT]** uses the language defined in the web browser
+- `Language.LOCAL` uses the language local to each country
+- `Language.LATIN` uses a default with latin characters
+- `Language.NON_LATIN` uses a default with non-latin characters
 
-Whenever a label is not supported in the defined language, it falls back to `maptilersdk.Language.LATIN`.
+Whenever a label is not supported in the defined language, it falls back to `Language.LATIN`.
 
 Here is a sample of some compatible languages:
 ![](images/screenshots/multilang.gif)

package/src/Map.ts

@@ -8,9 +8,9 @@ import type {
 } from "maplibre-gl";
 import { v4 as uuidv4 } from "uuid";
 import { ReferenceMapStyle, MapStyleVariant } from "@maptiler/client";
-import { config } from "./config";
+import { config, SdkConfig } from "./config";
 import { defaults } from "./defaults";
-import { CustomLogoControl } from "./CustomLogoControl";
+import { MaptilerLogoControl } from "./MaptilerLogoControl";
 import { enableRTL } from "./tools";
 import {
   getBrowserLanguage,
@@ -19,10 +19,10 @@ import {
   LanguageString,
 } from "./language";
 import { styleToStyle } from "./mapstyle";
-import { TerrainControl } from "./TerrainControl";
+import { MaptilerTerrainControl } from "./MaptilerTerrainControl";
 import { MaptilerNavigationControl } from "./MaptilerNavigationControl";
 import { geolocation } from "@maptiler/client";
-import { CustomGeolocateControl } from "./CustomGeolocateControl";
+import { MaptilerGeolocateControl } from "./MaptilerGeolocateControl";
 
 // StyleSwapOptions is not exported by Maplibre, but we can redefine it (used for setStyle)
 export type TransformStyleFunction = (
@@ -57,6 +57,19 @@ 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")
+   * 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;
+
+  /**
+   * Define the MapTiler Cloud API key to be used. This is strictly equivalent to setting
+   * `config.apiKey` and will overwrite it.
+   */
+  apiKey?: string;
+
   /**
    * Shows the MapTiler logo if `true`. Note that the logo is always displayed on free plan.
    */
@@ -129,6 +142,14 @@ export class Map extends maplibregl.Map {
   private terrainExaggeration = 1;
 
   constructor(options: MapOptions) {
+    // if (options.language) {
+    //   config.primaryLanguage = options.language;
+    // }
+
+    if (options.apiKey) {
+      config.apiKey = options.apiKey;
+    }
+
     const style = styleToStyle(options.style);
     const hashPreConstructor = location.hash;
 
@@ -256,9 +277,18 @@ export class Map extends maplibregl.Map {
         !!config.primaryLanguage || !!config.secondaryLanguage;
     });
 
+    // To flag if the language was already initialized at build time
+    // so that the language optionnaly passed in constructor is
+    // considered only once and at instanciation time.
+    let initLanguageFromConstructor = true;
+
     // If the config includes language changing, we must update the map language
     this.on("styledata", () => {
-      if (
+      // If the language is set as a constructor options,
+      // This prevails on the language from the config.
+      if (options.language && initLanguageFromConstructor) {
+        this.setPrimaryLanguage(options.language);
+      } else if (
         config.primaryLanguage &&
         (this.languageShouldUpdate || !this.isStyleInitialized)
       ) {
@@ -274,6 +304,7 @@ export class Map extends maplibregl.Map {
 
       this.languageShouldUpdate = false;
       this.isStyleInitialized = true;
+      initLanguageFromConstructor = false;
     });
 
     // this even is in charge of reaplying the terrain elevation after the
@@ -323,7 +354,7 @@ export class Map extends maplibregl.Map {
         const logoURL: string = tileJsonContent.logo;
 
         this.addControl(
-          new CustomLogoControl({ logoURL }),
+          new MaptilerLogoControl({ logoURL }),
           options.logoPosition
         );
 
@@ -332,7 +363,7 @@ export class Map extends maplibregl.Map {
           this.addControl(new maplibregl.AttributionControl(options));
         }
       } else if (options.maptilerLogo) {
-        this.addControl(new CustomLogoControl(), options.logoPosition);
+        this.addControl(new MaptilerLogoControl(), options.logoPosition);
       }
 
       // the other controls at init time but be after
@@ -376,7 +407,7 @@ export class Map extends maplibregl.Map {
 
         this.addControl(
           // new maplibregl.GeolocateControl({
-          new CustomGeolocateControl({
+          new MaptilerGeolocateControl({
             positionOptions: {
               enableHighAccuracy: true,
               maximumAge: 0,
@@ -401,7 +432,7 @@ export class Map extends maplibregl.Map {
             ? "top-right"
             : options.terrainControl
         ) as ControlPosition;
-        this.addControl(new TerrainControl(), position);
+        this.addControl(new MaptilerTerrainControl(), position);
       }
 
       // By default, no fullscreen control
@@ -469,9 +500,6 @@ export class Map extends maplibregl.Map {
         return this.setPrimaryLanguage(getBrowserLanguage());
       }
 
-      // We want to keep track of it to apply the language again when changing the style
-      config.primaryLanguage = language;
-
       const layers = this.getStyle().layers;
 
       // detects pattern like "{name:somelanguage}" with loose spacing
@@ -635,9 +663,6 @@ export class Map extends maplibregl.Map {
         return this.setSecondaryLanguage(getBrowserLanguage());
       }
 
-      // We want to keep track of it to apply the language again when changing the style
-      config.secondaryLanguage = language;
-
       const layers = this.getStyle().layers;
 
       // detects pattern like "{name:somelanguage}" with loose spacing
@@ -904,4 +929,23 @@ export class Map extends maplibregl.Map {
     hashBin[4] = this.getBearing();
     return Base64.fromUint8Array(new Uint8Array(hashBin.buffer));
   }
+
+  /**
+   * Get the SDK config object.
+   * This is convenient to dispatch the SDK configuration to externally built layers
+   * that do not directly have access to the SDK configuration but do have access to a Map instance.
+   * @returns
+   */
+  getSdkConfig(): SdkConfig {
+    return config;
+  }
+
+  /**
+   * Get the MapTiler session ID. Convenient to dispatch to externaly built component
+   * that do not directly have access to the SDK configuration but do have access to a Map instance.
+   * @returns
+   */
+  getMaptilerSessionId(): string {
+    return MAPTILER_SESSION_ID;
+  }
 }

package/src/{CustomGeolocateControl.ts → MaptilerGeolocateControl.ts}

@@ -6,7 +6,13 @@ const GeolocateControl = maplibregl.GeolocateControl;
 const Marker = maplibregl.Marker;
 const LngLat = maplibregl.LngLat;
 
-export class CustomGeolocateControl extends GeolocateControl {
+/**
+ * The MaptilerGeolocateControl is an extension of the original GeolocateControl
+ * with a few changes. In this version, the active mode persists as long as the
+ * location is still centered. This means it's robust to rotation, pitch and zoom.
+ *
+ */
+export class MaptilerGeolocateControl extends GeolocateControl {
   private lastUpdatedCenter = new LngLat(0, 0);
 
   /**

package/src/{CustomLogoControl.ts → MaptilerLogoControl.ts}

@@ -1,8 +1,9 @@
 import maplibregl from "maplibre-gl";
+import type { LogoOptions as LogoOptionsML } from "maplibre-gl";
 import { defaults } from "./defaults";
 import { Map } from "./Map";
 
-type LogoOptions = maplibregl.LogoOptions & {
+type LogoOptions = LogoOptionsML & {
   logoURL?: string;
   linkURL?: string;
 };
@@ -11,7 +12,7 @@ type LogoOptions = maplibregl.LogoOptions & {
  * This LogoControl extends the MapLibre LogoControl but instead can use any image URL and
  * any link URL. By default this is using MapTiler logo and URL.
  */
-export class CustomLogoControl extends maplibregl.LogoControl {
+export class MaptilerLogoControl extends maplibregl.LogoControl {
   private logoURL = "";
   private linkURL = "";
 

package/src/{TerrainControl.ts → MaptilerTerrainControl.ts}

@@ -4,20 +4,10 @@ import { Map } from "./Map";
 import maplibregl from "maplibre-gl";
 
 /**
- * An `TerrainControl` control adds a button to turn terrain on and off.
- *
- * @implements {IControl}
- * @param {Object} [options]
- * @param {string} [options.id] The ID of the raster-dem source to use.
- * @param {Object} [options.options]
- * @param {number} [options.options.exaggeration]
- * @example
- * var map = new maplibregl.Map({TerrainControl: false})
- *     .addControl(new maplibregl.TerrainControl({
- *         source: "terrain"
- *     }));
+ * A `MaptilerTerrainControl` control adds a button to turn terrain on and off
+ * by triggering the terrain logic that is already deployed in the Map object.
  */
-export class TerrainControl implements maplibregl.IControl {
+export class MaptilerTerrainControl implements maplibregl.IControl {
   _map: Map;
   _container: HTMLElement;
   _terrainButton: HTMLButtonElement;

package/src/index.ts

@@ -97,6 +97,10 @@ export {
 import { Map, GeolocationType } from "./Map";
 import type { MapOptions } from "./Map";
 
+import { MaptilerGeolocateControl } from "./MaptilerGeolocateControl";
+import { MaptilerLogoControl } from "./MaptilerLogoControl";
+import { MaptilerTerrainControl } from "./MaptilerTerrainControl";
+
 // importing client functions to expose them as part of the SDK
 import type {
   BBox,
@@ -168,4 +172,7 @@ export {
   Point,
   ReferenceMapStyle,
   MapStyleVariant,
+  MaptilerGeolocateControl,
+  MaptilerLogoControl,
+  MaptilerTerrainControl,
 };