@maptiler/sdk 1.0.6 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maptiler/sdk",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "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. 
@@ -150,10 +165,13 @@ Here is the full list:
   - `MapStyle.STREETS.DARK` (variant)
   - `MapStyle.STREETS.LIGHT` (variant)
   - `MapStyle.STREETS.PASTEL` (variant)
-- `MapStyle.OUTDOOR` reference style for adventure
-- `MapStyle.WINTER` reference style for winter adventure
 - `MapStyle.SATELLITE` reference style satellite and airborne imagery (no variants)
 - `MapStyle.HYBRID` reference style satellite and airborne imagery with labels (no variants)
+- `MapStyle.OUTDOOR` reference style for adventure
+- `MapStyle.WINTER` reference style for winter adventure
+- `MapStyle.DATAVIZ`, the perfect style for data visualization, with very little noise
+  - `MapStyle.DATAVIZ.DARK` (variant)
+  - `MapStyle.DATAVIZ.LIGHT` (variant)
 - `MapStyle.BASIC` reference style for minimalist design and general purpose
   - `MapStyle.BASIC.DARK` (variant)
   - `MapStyle.BASIC.LIGHT` (variant)
@@ -174,9 +192,7 @@ Here is the full list:
   - `MapStyle.TONER.LITE` (variant)
   - `MapStyle.TONER.LINES` (variant)
 - `MapStyle.OPENSTREETMAP` (reference style, this one does not have any variants)
-- `MapStyle.DATAVIZ`, the perfect style for data visualization, with very little noise
-  - `MapStyle.DATAVIZ.DARK` (variant)
-  - `MapStyle.DATAVIZ.LIGHT` (variant)
+
 
 All reference styles (instances of `ReferenceMapStyle`) and style variants (instances of `MapStyleVariant`) have methods to know the alternative styles and variant that belong to the same reference style (`.getVariants()`). This is handy to provide a default/dark/light alternative color scheme, yet preserving the same level of details as in the reference style. Read more about about [ReferenceMapStyle](docsmd/classes/ReferenceMapStyle.md) and [MapStyleVariant](docsmd/classes/MapStyleVariant.md).
 </details>  
@@ -320,19 +336,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
-map.setLanguage(maptilersdk.Language.ENGLISH);
+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
+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.
    */
@@ -127,8 +140,18 @@ export class Map extends maplibregl.Map {
   private isStyleInitialized = false;
   private isTerrainEnabled = false;
   private terrainExaggeration = 1;
+  private primaryLanguage: LanguageString | null = null;
+  private secondaryLanguage: LanguageString | null = null;
 
   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;
 
@@ -176,6 +199,9 @@ export class Map extends maplibregl.Map {
       },
     });
 
+    this.primaryLanguage = options.language ?? config.primaryLanguage;
+    this.secondaryLanguage = config.secondaryLanguage;
+
     // Map centering and geolocation
     this.once("styledata", async () => {
       // Not using geolocation centering if...
@@ -250,30 +276,10 @@ export class Map extends maplibregl.Map {
       }
     });
 
-    // Check if language has been modified and. If so, it will be updated during the next lifecycle step
-    this.on("styledataloading", () => {
-      this.languageShouldUpdate =
-        !!config.primaryLanguage || !!config.secondaryLanguage;
-    });
-
     // If the config includes language changing, we must update the map language
     this.on("styledata", () => {
-      if (
-        config.primaryLanguage &&
-        (this.languageShouldUpdate || !this.isStyleInitialized)
-      ) {
-        this.setPrimaryLanguage(config.primaryLanguage);
-      }
-
-      if (
-        config.secondaryLanguage &&
-        (this.languageShouldUpdate || !this.isStyleInitialized)
-      ) {
-        this.setSecondaryLanguage(config.secondaryLanguage);
-      }
-
-      this.languageShouldUpdate = false;
-      this.isStyleInitialized = true;
+      this.setPrimaryLanguage(this.primaryLanguage);
+      this.setSecondaryLanguage(this.secondaryLanguage);
     });
 
     // this even is in charge of reaplying the terrain elevation after the
@@ -464,14 +470,13 @@ export class Map extends maplibregl.Map {
       return;
     }
 
+    this.primaryLanguage = language;
+
     this.onStyleReady(() => {
       if (language === Language.AUTO) {
         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
@@ -621,7 +626,7 @@ export class Map extends maplibregl.Map {
   }
 
   /**
-   * Define the secondary language of the map.
+   * Define the secondary language of the map. Note that this is not supported by all the map styles
    * Note that most styles do not allow a secondary language and this function only works if the style allows (no force adding)
    * @param language
    */
@@ -630,14 +635,13 @@ export class Map extends maplibregl.Map {
       return;
     }
 
+    this.secondaryLanguage = language;
+
     this.onStyleReady(() => {
       if (language === Language.AUTO) {
         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
@@ -755,6 +759,22 @@ export class Map extends maplibregl.Map {
     });
   }
 
+  /**
+   * Get the primary language
+   * @returns
+   */
+  getPrimaryLanguage(): LanguageString {
+    return this.primaryLanguage;
+  }
+
+  /**
+   * Get the secondary language
+   * @returns
+   */
+  getSecondaryLanguage(): LanguageString {
+    return this.secondaryLanguage;
+  }
+
   /**
    * Get the exaggeration factor applied to the terrain
    * @returns
@@ -904,4 +924,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;
+  }
 }