@maptiler/sdk 4.2.0 → 5.0.0-rc.1

package/README.md

@@ -47,7 +47,72 @@ In addition, the MapTiler SDK JS provides well-documented and easy-to-use wrappe
 npm install --save @maptiler/sdk
 ```
 
-⚠️ Please keep in mind that if you use any additional [MapTiler modules](https://docs.maptiler.com/sdk-js/modules/), you must update them to a version that supports MapTiler SDK JS v3.
+⚠️ Please keep in mind that if you use any additional [MapTiler modules](https://docs.maptiler.com/sdk-js/modules/), you must update them to a version that supports MapTiler SDK JS v5.
+
+### Setting up the map worker with a bundler
+
+Since MapLibre GL JS v6, the map runs its background worker from separate files that most bundlers don't pick up on their own.
+
+By default, the SDK installed from npm loads the worker from the MapTiler CDN (`https://cdn.maptiler.com/maptiler-sdk-js/v<VERSION>/`), which works with any bundler. If your site uses a Content Security Policy, it needs `worker-src 'self' blob: https://cdn.maptiler.com`.
+
+To bundle the worker with your app instead (e.g. for offline or intranet use, or a stricter CSP), import the helper for your bundler once, before creating a map:
+
+**Vite**
+
+```ts
+import "@maptiler/sdk/vite-worker";
+import { Map } from "@maptiler/sdk";
+```
+
+For the Vite dev server, also exclude the helper from dependency pre-bundling:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  optimizeDeps: { exclude: ["@maptiler/sdk/vite-worker"] },
+});
+```
+
+**webpack 5 / rspack**
+
+```ts
+import "@maptiler/sdk/webpack-worker";
+import { Map } from "@maptiler/sdk";
+```
+
+**Next.js** (Turbopack and webpack)
+
+```ts
+// next.config.mjs (or `require("@maptiler/sdk/next")` in next.config.js)
+import { withMaptilerWorker } from "@maptiler/sdk/next";
+
+export default withMaptilerWorker({
+  // your Next.js config
+});
+```
+
+```tsx
+// the client component creating the map
+"use client";
+import "@maptiler/sdk/next-worker";
+import { Map } from "@maptiler/sdk";
+```
+
+`withMaptilerWorker` copies the worker files into `public/_maptiler/` on every `next dev` and `next build`, you may want to add that folder to your `.gitignore`.
+
+**Other setups**
+
+Copy `node_modules/@maptiler/sdk/dist/bundler/maplibre-gl-worker.mjs` into your build output (it is self-contained, and works the same with npm, yarn or pnpm), and set the worker URL before creating a map:
+
+```ts
+import { setWorkerUrl } from "@maptiler/sdk";
+
+setWorkerUrl("/path/to/maplibre-gl-worker.mjs");
+```
+
+### From CDN
 
 From CDN and using the UMD bundle, in the `<head></head>` section of your HTML file:
 
@@ -107,37 +172,20 @@ 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 address this issue and access to the complete type definition.
-
-1. **With `esModuleInterop`**
+The SDK is fully typed, including the types re-exported from MapLibre GL JS.
 
-Set the following in your `tsconfig.json`:
+The SDK is an ES module whose entry points (such as `@maptiler/sdk/next`) are declared with `package.json` `exports`. TypeScript only reads `exports` with a modern module resolution, so set one of the following in your `tsconfig.json`:
 
 ```js
 {
   "compilerOptions": {
     // ...
-    "esModuleInterop": true,
+    "moduleResolution": "Bundler", // or "Node16" / "NodeNext"
   }
 }
 ```
 
-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 the legacy `"moduleResolution": "Node"` (or `"Node10"`), the main `@maptiler/sdk` types still resolve, but the entry points under `@maptiler/sdk/...` don't get types.
 
 ### With CDN
 
@@ -163,13 +211,13 @@ The SDK hosted on our CDN is bundled as _[Universal Module Definition](https://g
     </style>
 
     <!-- Load the SDK CSS -->
-    <link rel="stylesheet" href="dist/maptiler-sdk.css" />
+    <link rel="stylesheet" href="build/maptiler-sdk.css" />
   </head>
 
   <body>
     <div id="map-container"></div>
 
-    <script src="dist/maptiler-sdk.umd.min.js"></script>
+    <script src="build/maptiler-sdk.umd.min.js"></script>
 
     <script>
       // Add your MapTiler API key to the config
@@ -190,6 +238,30 @@ The SDK hosted on our CDN is bundled as _[Universal Module Definition](https://g
 
 Check out the minimalist code samples in the [demos](demos) directory.
 
+#### Map worker files and Content Security Policy (CSP)
+
+Since MapLibre GL JS v6, the map loads its background worker as two separate files, `maplibre-gl-worker.mjs` and `maplibre-gl-shared.mjs`. The UMD bundle looks for them in the same folder as `maptiler-sdk.umd.min.js`. Our CDN serves them there, so when using the CDN without a CSP, there is nothing to set up.
+
+If you **self-host the UMD bundle**, copy both `.mjs` files next to `maptiler-sdk.umd.min.js`. They must be served with a JavaScript content type (e.g. `text/javascript`).
+
+If your site uses a **Content Security Policy**, the worker needs to be allowed:
+
+- **SDK loaded from our CDN**: since the worker comes from another origin, it is started through a `blob:` URL that then loads the worker from the CDN, so both must be allowed. `blob:` alone is not enough:
+
+  ```
+  worker-src 'self' blob: https://cdn.maptiler.com;
+  ```
+
+- **CSP that cannot allow `blob:`**: host `maplibre-gl-worker.mjs` and `maplibre-gl-shared.mjs` on your own origin (in the same folder) and point the SDK to the worker before creating any map. Then `worker-src 'self'` is enough:
+
+  ```html
+  <script>
+    maptilersdk.setWorkerUrl("/path/to/maplibre-gl-worker.mjs");
+  </script>
+  ```
+
+`setWorkerUrl` is also needed if the UMD bundle is not loaded with a regular `<script src="...">` tag (e.g. concatenated into another file or loaded with AMD/RequireJS), since the worker location is then no longer known.
+
 <br>
 
 ## 💡 Related Examples
@@ -1048,12 +1120,9 @@ Here is a sample of some compatible 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!
-
-If you wish to opt of applying the rtl plugin or wish to use a different compatible rtl text plugin, you can pass the `rtlTextPlugin`
-constructor option as either `false` (disable the rtl plugin) or a url to load a different plugin.
+Languages that are written right-to-left such as Arabic and Hebrew, as well as complex scripts such as Devanagari, Khmer or Burmese, are fully supported by default. MapLibre shapes them natively, no need to install any plugins!
 
-**Note: Once the rtlTextPlugin has been installed once, it cannot be unset nor updated on the current instance. Calling `setRTLTextPlugin` without setting `rtlTextPlugin` to false in the constuctor will result in an error.**
+If you still need a custom RTL text plugin, `setRTLTextPlugin` is re-exported from MapLibre. Note that it is deprecated by MapLibre and a plugin *replaces* the built-in shaping.
 
 <p align="center">
   <img src="images/screenshots/lang-arabic.jpeg" width="48%"></img>

package/dist/ImageViewer/ImageViewer.d.ts

@@ -1,9 +1,8 @@
-import { default as MaplibreGL } from 'maplibre-gl';
-import { EaseToOptions, DoubleClickZoomHandler, DragPanHandler, TwoFingersTouchZoomRotateHandler, FlyToOptions, MapOptions, JumpToOptions, ScrollZoomHandler, BoxZoomHandler, KeyboardHandler, CooperativeGesturesHandler, LngLat, MapDataEvent, PointLike } from '..';
+import { EaseToOptions, DoubleClickZoomHandler, DragPanHandler, TwoFingersTouchZoomRotateHandler, FlyToOptions, MapOptions, JumpToOptions, ScrollZoomHandler, BoxZoomHandler, KeyboardHandler, CooperativeGesturesHandler, LngLat, PointLike } from '..';
 import { Map } from '../Map';
+import { Evented } from 'maplibre-gl';
 import { ImageViewerFitImageToBoundsControl } from '../controls/ImageViewerFitImageToBoundsControl';
 import { lngLatToPxInternalSymbolKey, pxToLngLatInternalSymbolKey } from './symbols';
-declare const Evented: typeof MaplibreGL.Evented;
 export type AllowedConstructorOptions = "container" | "apiKey" | "maxZoom" | "minZoom" | "zoom" | "bearing";
 export type ImageViewerFlyToOptions = Omit<FlyToOptions, "pitch"> & {
     center: [number, number];
@@ -305,18 +304,18 @@ export default class ImageViewer extends Evented {
      * Fly to a given center.
      *
      * @param {ImageViewerFlyToOptions} options - The options for the fly to.
-     * @param {MapDataEvent} eventData - The event data.
+     * @param eventData - Additional properties merged into the camera events fired by the map, as in MapLibre.
      * @returns {ImageViewer} The ImageViewer instance.
      */
-    flyTo(options: ImageViewerFlyToOptions, eventData?: MapDataEvent): this;
+    flyTo(options: ImageViewerFlyToOptions, eventData?: Parameters<Map["flyTo"]>[1]): this;
     /**
      * Jump to a given center.
      *
      * @param {ImageViewerJumpToOptions} options - The options for the jump to.
-     * @param {MapDataEvent} eventData - The event data.
+     * @param eventData - Additional properties merged into the camera events fired by the map, as in MapLibre.
      * @returns {ImageViewer} The ImageViewer instance.
      */
-    jumpTo(options: ImageViewerJumpToOptions, eventData?: MapDataEvent): this;
+    jumpTo(options: ImageViewerJumpToOptions, eventData?: Parameters<Map["jumpTo"]>[1]): this;
     /**
      * Set the zoom level.
      *
@@ -405,4 +404,3 @@ export default class ImageViewer extends Evented {
     [lngLatToPxInternalSymbolKey]: (lngLat: LngLat) => [number, number];
     [pxToLngLatInternalSymbolKey]: (px: [number, number]) => LngLat;
 }
-export {};

package/dist/ImageViewer/ImageViewerMarker.d.ts

@@ -1,7 +1,6 @@
 import { Alignment, Subscription, MarkerOptions, PointLike, Popup } from '../index';
-import { default as MapLibreGL } from 'maplibre-gl';
+import { Evented, Event as EventML } from 'maplibre-gl';
 import { default as ImageViewer } from './ImageViewer';
-declare const Evented: typeof MapLibreGL.Evented;
 export type ImageViewerMarkerOptions = MarkerOptions & {};
 export interface ImageViewerMarkerInterface {
     on(event: MarkerEventTypes, listener: (e: ImageViewerMarkerEvent) => void): Subscription;
@@ -28,7 +27,7 @@ export interface ImageViewerMarkerInterface {
     toggleClassName(className: string): void;
     togglePopup(): void;
 }
-export declare class ImageViewerMarker extends Evented {
+export declare class ImageViewerMarker extends Evented<ImageViewerMarkerEventType> {
     private viewer;
     private readonly marker;
     private readonly position;
@@ -67,7 +66,7 @@ export declare class ImageViewerMarker extends Evented {
      * @returns {PointLike} The offset of the ImageViewerMarker.
      * @see  [PointLike](https://docs.maptiler.com/sdk-js/api/geography/#pointlike)
      */
-    getOffset(): MapLibreGL.Point;
+    getOffset(): import('maplibre-gl').Point;
     /**
      * Gets the pitch alignment of the ImageViewerMarker.
      *
@@ -81,7 +80,7 @@ export declare class ImageViewerMarker extends Evented {
      * @returns {Popup} The popup of the ImageViewerMarker.
      * @see [Popup](https://docs.maptiler.com/sdk-js/api/markers/#popup)
      */
-    getPopup(): MapLibreGL.Popup;
+    getPopup(): Popup;
     /**
      * Gets the rotation of the ImageViewerMarker.
      *
@@ -108,7 +107,8 @@ export declare class ImageViewerMarker extends Evented {
      * @param {Record<string, any>} data - The data to fire the event with.
      * @returns {ImageViewerMarker} The ImageViewerMarker instance.
      */
-    fire(event: MarkerEventTypes | Event, data?: Record<string, any>): this;
+    fire(event: ImageViewerMarkerEvent): this;
+    fire(event: MarkerEventTypes, data?: Record<string, any>): this;
     /**
      * Removes an event listener from the ImageViewerMarker.
      *
@@ -227,9 +227,9 @@ export declare class ImageViewerMarker extends Evented {
 }
 declare const MARKER_EVENT_TYPES: readonly ["dragstart", "drag", "dragend"];
 type MarkerEventTypes = (typeof MARKER_EVENT_TYPES)[number];
-export declare class ImageViewerMarkerEvent {
-    readonly type: string;
-    readonly target: ImageViewerMarker;
+export type ImageViewerMarkerEventType = Record<MarkerEventTypes, ImageViewerMarkerEvent>;
+export declare class ImageViewerMarkerEvent extends EventML<MarkerEventTypes> {
+    target: ImageViewerMarker;
     [key: string]: any;
     constructor(type: MarkerEventTypes, marker: ImageViewerMarker, data: Record<string, any>);
 }

package/dist/Map.d.ts

@@ -1,4 +1,4 @@
-import { default as maplibregl, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions, ProjectionSpecification, FlyToOptions, EaseToOptions, FitBoundsOptions, AnimationOptions, LngLatBoundsLike, LngLatLike } from 'maplibre-gl';
+import { Map as MapMLGL, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions, ProjectionSpecification, FlyToOptions, EaseToOptions, FitBoundsOptions, AnimationOptions, LngLatBoundsLike, LngLatLike, AllPaintProperties, AllLayoutProperties, MapEventType, MapLayerEventType, Listener, Subscription, TerrainSpecification, Event as EventML } from 'maplibre-gl';
 import { ReferenceMapStyle, MapStyleVariant } from '@maptiler/client';
 import { SdkConfig } from './config';
 import { LanguageInfo } from './language';
@@ -16,6 +16,45 @@ export type LoadWithTerrainEvent = {
         exaggeration: number;
     };
 };
+/**
+ * Shape of an event fired by the SDK on top of the MapLibre events,
+ * with the properties passed to `fire(type, properties)` merged in.
+ */
+type SDKMapEvent<TType extends string, TProps extends object = object> = EventML<TType> & {
+    target: Map;
+} & TProps;
+/**
+ * Events fired by the MapTiler SDK `Map` in addition to the MapLibre ones.
+ */
+export type MaptilerMapEventType = {
+    /** Fired once the map style and the SDK controls are ready */
+    ready: SDKMapEvent<"ready">;
+    /** Fired once the map is loaded and the terrain (if any) is ready */
+    loadWithTerrain: LoadWithTerrainEvent;
+    /** Fired when the WebGL context is lost unexpectedly (i.e. not after `map.remove()`) */
+    webglContextLost: SDKMapEvent<"webglContextLost">;
+    terrainAnimationStart: SDKMapEvent<"terrainAnimationStart", {
+        terrain: TerrainSpecification | null;
+    }>;
+    terrainAnimationStop: SDKMapEvent<"terrainAnimationStop", {
+        terrain: TerrainSpecification | null;
+    }>;
+    "projection.change": SDKMapEvent<"projection.change", {
+        projection: ProjectionSpecification;
+    }>;
+    "cubemaplayer:animateindone": SDKMapEvent<"cubemaplayer:animateindone", Partial<CubemapLayer>>;
+    "cubemaplayer:animateoutdone": SDKMapEvent<"cubemaplayer:animateoutdone", Partial<CubemapLayer>>;
+    "cubemaplayer:onremove": SDKMapEvent<"cubemaplayer:onremove", Partial<CubemapLayer>>;
+    "radialgradientlayer:animateindone": SDKMapEvent<"radialgradientlayer:animateindone", Partial<RadialGradientLayer>>;
+    "radialgradientlayer:animateoutdone": SDKMapEvent<"radialgradientlayer:animateoutdone", Partial<RadialGradientLayer>>;
+    "radialgradientlayer:onremove": SDKMapEvent<"radialgradientlayer:onremove", Partial<RadialGradientLayer>>;
+};
+/**
+ * All the events that can be listened to on a MapTiler SDK `Map`: the MapLibre ones plus the SDK ones.
+ * Since MapLibre v6.3, `on`/`once`/`off`/`fire` only accept the keys of `MapEventType`,
+ * so the SDK `Map` overrides them to accept its own events as well.
+ */
+export type MapEventTypeSDK = MapEventType & MaptilerMapEventType;
 export declare const GeolocationType: {
     POINT: "POINT";
     COUNTRY: "COUNTRY";
@@ -169,11 +208,6 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo" | "attribut
      * Default: Unless this is set explicitly to false, the SDK version will be logged to the console.
      */
     logSDKVersion?: boolean;
-    /**
-     * Whether to enable the RTL plugin or import a different one.
-     * Default is undefined, which means the plugin is enabled by default.
-     */
-    rtlTextPlugin?: boolean | string;
     /**
      * Whether to enable the experimental tile preloading feature.
      * Default is false.
@@ -202,8 +236,36 @@ export interface ProjectionChangeOptions {
 /**
  * The Map class can be instanciated to display a map in a `<div>`
  */
-export declare class Map extends maplibregl.Map {
+export declare class Map extends MapMLGL {
     readonly telemetry: Telemetry;
+    /**
+     * Adds a listener for events of a specified type, optionally limited to features in one or more layers.
+     * Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
+     */
+    on<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventType[T] & object) => void): Subscription;
+    on<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventTypeSDK[T] & object) => void): Subscription;
+    on(type: keyof MapEventTypeSDK, listener: Listener): Subscription;
+    /**
+     * Adds a listener that will be called only once to a specified event type, optionally limited to features in one or more layers.
+     * Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
+     */
+    once<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventType[T] & object) => void): this;
+    once<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[]): Promise<MapLayerEventType[T] & object>;
+    once<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventTypeSDK[T] & object) => void): this;
+    once<T extends keyof MapEventTypeSDK>(type: T): Promise<MapEventTypeSDK[T] & object>;
+    once(type: keyof MapEventTypeSDK, listener?: Listener): this | Promise<any>;
+    /**
+     * Removes an event listener previously added with {@link Map.on} or {@link Map.once}.
+     * Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
+     */
+    off<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventType[T] & object) => void): this;
+    off<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventTypeSDK[T] & object) => void): this;
+    off(type: keyof MapEventTypeSDK, listener: Listener): this;
+    /**
+     * Fires an event. Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
+     */
+    fire(event: MapEventTypeSDK[keyof MapEventTypeSDK]): this;
+    fire(type: keyof MapEventTypeSDK, properties?: object): this;
     private space?;
     private halo?;
     getSpace(): CubemapLayer | undefined;
@@ -399,7 +461,7 @@ export declare class Map extends maplibregl.Map {
      * map.setPaintProperty('my-layer', 'fill-color', '#faafee');
      * ```
      */
-    setPaintProperty(layerId: string, name: string, value: any, options?: StyleSetterOptions): this;
+    setPaintProperty<K extends keyof AllPaintProperties>(layerId: string, name: K, value: AllPaintProperties[K], options?: StyleSetterOptions): this;
     /**
      * Sets the value of a layout property in the specified style layer.
      * Layout properties define how the layer is styled.
@@ -413,7 +475,7 @@ export declare class Map extends maplibregl.Map {
      * @param options - Options object.
      * @returns `this`
      */
-    setLayoutProperty(layerId: string, name: string, value: any, options?: StyleSetterOptions): this;
+    setLayoutProperty<K extends keyof AllLayoutProperties>(layerId: string, name: K, value: AllLayoutProperties[K], options?: StyleSetterOptions): this;
     /**
      * Sets the value of the style's glyphs property.
      *
@@ -530,7 +592,7 @@ export declare class Map extends maplibregl.Map {
      * Sets the projection to a {@linkcode ProjectionSpecification}.
      * @param projection - the projection specification to set
      */
-    setProjection(projection: maplibregl.ProjectionSpecification): this;
+    setProjection(projection: ProjectionSpecification): this;
     /**
      * Forget the persisted projection - from both constructor option and result of any `map.setProjection(..., { persist: true })` calls.
      */
@@ -684,3 +746,4 @@ export declare class Map extends maplibregl.Map {
      */
     private resolveCameraPosition;
 }
+export {};