@maptiler/sdk 4.2.0-rc.1 → 5.0.0-beta.m-r.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.
+The SDK is fully typed, including the types re-exported from MapLibre GL JS.
 
-There are mainly two ways to address 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`:
+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": {
     // ...
-    "moduleResolution": "Bundler",
+    "moduleResolution": "Bundler", // or "Node16" / "NodeNext"
   }
 }
 ```
 
-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>
@@ -1337,6 +1406,182 @@ When defining a new _ramp_, the colors can be an RGB array (`[number, number, nu
 
 Many methods are available on color ramps, such as getting the `<canvas>` element of it, rescaling it, flipping it or [resampling it in a non-linear way](colorramp.md). Read more on [our reference page](https://docs.maptiler.com/sdk-js/api/color-ramp/) and have a look at our [examples](https://docs.maptiler.com/sdk-js/examples/?q=colorramp) to see how they work.
 
+### Markers
+
+The SDK's `Marker` is designed for MapTiler maps. It is built on the MapLibre marker and adds built-in shapes and sizes, colours that follow the active MapTiler style, collision handling, interaction states, transitions and animations.
+
+#### Adding markers
+
+Create a marker, give it a position, and add it through the map. Markers added this way take part in collision handling and follow the style's colours:
+
+```ts
+import { Map, Marker } from "@maptiler/sdk";
+
+const marker = new Marker({ lngLat: [8.54, 47.37], shape: "bubble-circle", size: "m", content: "A1" });
+map.addMarker(marker);
+
+// or straight from options
+map.addMarker({ lngLat: [8.55, 47.38], shape: "circle" });
+map.addMarkers([
+  { lngLat: [8.53, 47.36], shape: "square" },
+  new Marker({ shape: "circle" }).setLngLat([8.56, 47.39]),
+]);
+
+map.getMarker(marker.id);
+map.getMarkers();
+map.removeMarker(marker.id);
+map.removeMarkers(); // all markers, or pass a list of ids
+```
+
+Removing a marker plays its exit animation first, if it has one (see [Animations](#animations)). Pass `{ immediate: true }` to `removeMarker()` or `removeMarkers()` to remove markers straight away.
+
+> [!WARNING]
+> `marker.addTo(map)` is deprecated. It now delegates to `map.addMarker(marker)` and logs a one-time warning. Use `map.addMarker()` instead.
+
+#### Appearance
+
+```ts
+const marker = new Marker({
+  shape: "maptiler", // "circle" | "square" | "bubble-circle" | "bubble-square" | "maptiler" | "maptiler-full"
+  size: "l", // "xs" | "s" | "m" | "l"
+  shadow: "soft", // "none" | "soft" | "medium" | "strong"
+  content: "42", // text shown inside the marker
+  outline: true,
+  scale: [1.2, 1.2],
+  title: "Zurich", // native tooltip
+});
+```
+
+The appearance options have matching setters and getters, such as `setShape()`, `setSize()` or `getContent()`.
+
+Unless you set them, the marker's colours (`innerColor`, `outerColor`, `contentColor` and `outlineColor`) are picked for the current MapTiler style and update when the style changes. A colour you set explicitly stays fixed, and setting it back to `undefined` returns it to the style's colour:
+
+```ts
+marker.setInnerColor("#ff5a1f");
+marker.setInnerColor(undefined); // back to the style's colour
+```
+
+Instead of text, a marker can show an image, or any HTML or SVG element, for example one managed by React:
+
+```ts
+new Marker({ url: "https://example.com/icon.svg" });
+new Marker({ element: myElement });
+```
+
+With `element`, the shape and size options do not apply. The colour and shadow options are set on the element as CSS custom properties, so its own styles can use them.
+
+#### Collisions
+
+By default, markers are always shown even when they overlap. To declutter the map, choose what happens when markers collide. Where markers overlap, the one with the higher `priority` wins:
+
+```ts
+// default for every marker on the map
+map.setMarkerCollisionOptions({ behaviour: "hide-by-priority" });
+
+// or per marker
+new Marker({ priority: 10, collisionBehaviour: "minimize-by-priority" });
+```
+
+- `always-show`: never hidden (the default)
+- `hide-by-priority`: hidden behind a higher-priority marker
+- `minimize-by-priority`: shrinks to a small dot behind a higher-priority marker. `minimizedOptions` changes how the minimized marker looks.
+
+`setMarkerCollisionOptions()` also sets the `proximityPadding` used for `markerproximity` events and the duration and easing of the hide and show fade. `marker.getCollisionDisplayState()` returns `"visible"`, `"hidden"` or `"minimized"`.
+
+Markers fire `markeroverlap` and `markerproximity` when other markers start or stop colliding with them:
+
+```ts
+marker.on("markeroverlap", ({ entered, exited, current }) => {
+  console.log(`${current.length} markers overlap this one`);
+});
+```
+
+#### Interaction states
+
+Change a marker's look while it is hovered, focused, pressed or dragged. The marker returns to its own values when the state ends:
+
+```ts
+const marker = new Marker({
+  draggable: true,
+  states: {
+    hover: { scale: [1.2, 1.2] },
+    active: { shadow: "strong" },
+    dragging: { opacity: 0.6 },
+  },
+});
+
+marker.setUIState("focus", { outline: 3 });
+```
+
+#### Transitions
+
+Ease a property to its new value instead of jumping to it. `position`, `scale`, `rotation` and the four colours can be transitioned, each with `[duration, easing?, delay?]`:
+
+```ts
+const marker = new Marker({
+  transitions: {
+    position: [600, "QuadraticInOut"],
+    innerColor: [300],
+  },
+});
+
+marker.setLngLat([8.6, 47.4]); // glides to the new position
+marker.setTransitionForProperty("scale", [200, "CubicOut"]);
+```
+
+The `transitionstart` and `transitionend` events report the property being transitioned.
+
+#### Animations
+
+Play an animation when a marker is added, loop one while it is on the map, and play another when it is removed:
+
+```ts
+const marker = new Marker({
+  animations: {
+    enter: { preset: "drop" }, // "grow" | "drop" | "pop" | "bounce" | "fade"
+    idle: { preset: "pulsescale", iterations: 3 }, // "pulsescale" | "pulseopacity" | "ring" | "bounce"
+    exit: { preset: "fade", duration: 300 }, // "shrink" | "fade" | "pop" | "explode"
+  },
+});
+
+map.addMarker(marker); // plays "drop"
+map.removeMarker(marker.id); // plays "fade", then removes the marker
+map.removeMarker(marker.id, { immediate: true }); // removes it without the exit animation
+```
+
+Each animation also accepts `duration`, `delay`, `easing` and `magnitude`. Instead of a preset, `custom` takes a function called every frame with the animation's progress (`0` to `1`) and the marker. Animations fire events such as `enteranimationstart`, `idleanimationiteration` and `exitanimationend`.
+
+#### Altitude (experimental)
+
+Raise a marker above the ground. The marker is placed in 3D, so it stays in the right place as the camera moves, with terrain and under globe projection:
+
+```ts
+marker.setAltitude(500); // 500 m above the terrain under the marker
+marker.setAltitude(1200, { relativeTo: "sea" }); // 1200 m above sea level
+marker.setAltitude(false); // back on the map surface
+
+marker.setGroundLine(true); // dashed line from the marker down to the ground
+```
+
+Style the ground line with your own CSS on the `maptiler-marker-groundline` class, or add a class of your own with `setGroundLine(true, { className: "my-line" })`.
+
+#### The MapLibre marker
+
+Compared with the MapLibre marker:
+- The `color` option is removed. Use `innerColor`, `outerColor`, `contentColor` and `outlineColor`.
+- `scale` is a 2D vector, `[x, y]`.
+- `setRotation()` rotates the marker's shape rather than its container.
+
+The plain MapLibre marker is still available as `MarkerMLGL`:
+
+```ts
+import { MarkerMLGL } from "@maptiler/sdk";
+
+new MarkerMLGL({ color: "#f00" }).setLngLat([8.54, 47.37]).addTo(map);
+```
+
+See `demos/16-maptiler-markers.html` to `demos/20-marker-altitude.html` for examples.
+
 ### Camera routes and animations
 
 The SDK comes with several classes to help with animations, particularly route animations.
@@ -1369,7 +1614,8 @@ const marker = new Marker().setLngLat(
     -7.449346225791231,
     39.399728941536836,
   )
-).addTo(map);
+);
+map.addMarker(marker);
 
 // TimeUpdate is fired every frame
 animation.addEventListener(AnimationEventTypes.TimeUpdate, (e) => {

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/ImageViewer/monkeyPatchML.d.ts

@@ -1,4 +1,4 @@
-import { LngLat, Marker, Point, PositionAnchor, TransformConstrainFunction } from '../index';
+import { LngLat, MarkerMLGL as Marker, Point, PositionAnchor, TransformConstrainFunction } from '../index';
 export declare function unprojectFromWorldCoordinates(worldSize: number, point: Point): LngLat;
 export declare const overpanningUnderzoomingTransformConstrain: TransformConstrainFunction;
 export declare const anchorTranslate: Record<PositionAnchor, string>;