@maptiler/sdk 1.0.6 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maptiler/sdk",
-  "version": "1.0.6",
+  "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,7 +8,7 @@ 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 { MaptilerLogoControl } from "./MaptilerLogoControl";
 import { enableRTL } from "./tools";
@@ -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
@@ -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;
+  }
 }