@maptiler/sdk 5.0.0-rc.3 → 5.0.0-rc.5

package/README.md

@@ -121,6 +121,15 @@ From CDN and using the UMD bundle, in the `<head></head>` section of your HTML f
 <link href="https://cdn.maptiler.com/maptiler-sdk-js/<VERSION>/maptiler-sdk.css" rel="stylesheet" />
 ```
 
+Or from CDN and using the ES module bundle, importing the SDK from a module script:
+
+```html
+<link href="https://cdn.maptiler.com/maptiler-sdk-js/<VERSION>/maptiler-sdk.css" rel="stylesheet" />
+<script type="module">
+  import { config, Map } from "https://cdn.maptiler.com/maptiler-sdk-js/<VERSION>/maptiler-sdk.min.mjs";
+</script>
+```
+
 <br>
 
 ## 🚀 Basic Usage
@@ -189,7 +198,7 @@ With the legacy `"moduleResolution": "Node"` (or `"Node10"`), the main `@maptile
 
 ### With CDN
 
-The SDK hosted on our CDN is bundled as _[Universal Module Definition](https://github.com/umdjs/umd)_ (UMD) to make it standalone and contain all its dependencies. The CDN also serves the style sheet (CSS).
+The SDK hosted on our CDN is bundled both as _[Universal Module Definition](https://github.com/umdjs/umd)_ (UMD), `maptiler-sdk.umd.min.js`, and as an ES module, `maptiler-sdk.min.mjs`. Both are standalone and contain all their dependencies. The CDN also serves the style sheet (CSS).
 
 **Recommended for:** simple map integration example and demos
 
@@ -236,13 +245,29 @@ The SDK hosted on our CDN is bundled as _[Universal Module Definition](https://g
 </html>
 ```
 
+With the ES module bundle, the SDK is imported from a module script instead of being exposed as the `maptilersdk` global:
+
+```html
+<script type="module">
+  import { config, Map, MapStyle } from "https://cdn.maptiler.com/maptiler-sdk-js/<VERSION>/maptiler-sdk.min.mjs";
+
+  config.apiKey = "YOUR_API_KEY";
+
+  const map = new Map({
+    container: "map-container",
+    style: MapStyle.STREETS_DARK,
+    hash: true,
+  });
+</script>
+```
+
 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.
+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 and ES module bundles look for them in the same folder as `maptiler-sdk.umd.min.js` and `maptiler-sdk.min.mjs`. 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 you **self-host the UMD or ES module bundle**, copy both `.mjs` files next to `maptiler-sdk.umd.min.js` or `maptiler-sdk.min.mjs`. 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:
 
@@ -260,6 +285,8 @@ If your site uses a **Content Security Policy**, the worker needs to be allowed:
   </script>
   ```
 
+  With the ES module bundle, import `setWorkerUrl` from it and call it the same way.
+
 `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>
@@ -274,6 +301,110 @@ Check out more than 200 [examples and tutorials](https://docs.maptiler.com/sdk-j
 
 <br>
 
+## 🗂️ In-repo demos
+
+Runnable demos of the SDK features, kept in `demos/`. They're separate from the docs examples linked above.
+
+### Run the demos
+
+1. Create a `.env.local` file at the root of the repo (git ignores it) with your MapTiler API key: `VITE_MAPTILER_API_KEY=YOUR_KEY`.
+2. Run `npm run dev`.
+3. Open the printed URL. It lists every demo.
+
+Instead of `.env.local`, you can add `?key=YOUR_KEY` to a demo URL once, and the browser stores the key for all demos. If several keys are set, the demos use the first of: the key in `.env.local`, the key stored in the browser, the `key` URL parameter.
+
+### Kinds of demos
+
+- **Examples** (`demos/examples/<topic>/<name>/`): short, single-use code with minimal dependencies, e.g. "put a marker on the page and style it".
+- **Showcases** (`demos/showcases/<name>/`): more involved, with more comments and inline docs, closer to a guide. May use external dependencies, e.g. a UI library.
+- **Playgrounds** (`demos/playgrounds/<name>/`): for comparing feature versions, testing or developing features, and recording code "gotchas". May use external dependencies and lots of UI code. Internal: listed on the `npm run dev` page, but not in the list below.
+
+### Add or change a demo
+
+Each demo is a folder with an `index.html`, a `main.ts` and a `meta.json`:
+
+```json
+{
+  "title": "Styled marker",
+  "description": "Puts a marker on the map and sets its shape and colors.",
+  "type": "example",
+  "topics": ["markers"],
+  "createdWith": "5.0.0-rc.4",
+  "lastCheckedWith": "5.0.0-rc.4",
+  "lastCheckedOn": "2026-10-30"
+}
+```
+
+- `type` is `example`, `showcase` or `playground`, matching the folder. An example's first topic matches its `<topic>` folder. Playgrounds stay out of the index below, and their `topics` can be empty.
+- `createdWith` is the SDK version the demo was created with.
+- `lastCheckedWith` and `lastCheckedOn` record the last time someone ran the demo and saw it working. They stay `null` until then.
+
+Values likely to change go in variables right after the imports of `main.ts`, with the same names in every demo, so they can be updated with grep or a script, e.g. `MAP_STYLE`.
+
+Build any controls a demo needs (buttons, dropdowns, sliders, readouts) with [lil-gui](https://lil-gui.georgealways.com), using `createGui()` from `demos/shared/gui.ts`, rather than hand-written HTML. The exception is UI that is the subject of the demo, such as the custom map controls of the controls examples.
+
+Run `npm run demos:index` after adding or changing a demo. It validates the metadata and regenerates the index below. CI fails if the index is out of date.
+
+### Topics
+
+Use only these labels in `topics`. Add a label here before using it.
+
+<!-- demo-topics:start -->
+- `3d`
+- `animation`
+- `color-ramps`
+- `controls`
+- `errors`
+- `events`
+- `getting-started`
+- `halo`
+- `image-viewer`
+- `language`
+- `markers`
+- `performance`
+- `requests`
+- `routes`
+- `sky`
+- `space`
+- `styles`
+<!-- demo-topics:end -->
+
+### Index
+
+<!-- demos-index:start -->
+#### Examples
+
+| Demo | Description | Topics | Created with | Last checked |
+| --- | --- | --- | --- | --- |
+| [Available color ramps](./demos/examples/color-ramps/available-ramps) | Displays every built-in color ramp, plus rescaled and resampled variants. | `color-ramps` | 3.2.4 | Not yet |
+| [Custom controls: declarative](./demos/examples/controls/declarative) | Builds custom map controls from HTML attributes. | `controls` | 3.5.1-rc1 | Not yet |
+| [Custom controls: programmatic](./demos/examples/controls/programmatic) | Builds custom map controls from code. | `controls` | 3.8.0-rc.9 | Not yet |
+| [Handling WebGL errors](./demos/examples/errors/handling-webgl-errors) | Reacts to a lost WebGL context and shows a warning. | `errors` | 3.2.4 | Not yet |
+| [Ready event](./demos/examples/events/ready-event) | Uses the `ready` event to know when the map can be changed safely. | `events` | 3.2.4 | Not yet |
+| [Simple map](./demos/examples/getting-started/simple) | A map with the Streets v2 style. | `getting-started` | 5.0.0-rc.4 | Not yet |
+| [Image viewer](./demos/examples/image-viewer/image-viewer) | Displays a tiled, non-georeferenced image with markers. | `image-viewer` `markers` | 3.8.0-rc.9 | Not yet |
+| [Language changes](./demos/examples/language/language-changes) | Switches the map language at runtime. | `language` | 3.5.1-rc1 | Not yet |
+| [Marker altitude](./demos/examples/markers/altitude) | Raises two draggable markers to 1,300 m above sea level over the terrain, with ground lines (experimental). | `markers` | 5.0.0-beta.m-r.1 | Not yet |
+| [Styled marker](./demos/examples/markers/styled-marker) | Puts a marker on the map and sets its shape and colors. | `markers` | 5.0.0-rc.4 | Not yet |
+| [Marker UI states](./demos/examples/markers/ui-states) | Markers that change their look on hover, focus, press and drag. | `markers` | 5.0.0-beta.m-r.1 | Not yet |
+| [Tile preloading: bounds](./demos/examples/performance/tile-preloading-bounds) | Preloads the tiles of a region with `experimental_preloadTilesForBounds`, then jumps there. Toggle preloading off to compare. | `performance` | 4.1.0 | Not yet |
+| [Tile preloading: flyTo](./demos/examples/performance/tile-preloading-flyto) | Preloads the tiles along a `flyTo` path with `experimental_preload` before the flight starts. Toggle preloading off to compare. | `performance` | 4.1.0 | Not yet |
+| [Transform request](./demos/examples/requests/transform-request) | Changes outgoing map requests with `transformRequest`. | `requests` | 3.2.4 | Not yet |
+| [Sky: day](./demos/examples/sky/day) | Configures the sky on a daytime outdoor style. | `sky` | 3.2.4 | Not yet |
+| [Sky: night](./demos/examples/sky/night) | Configures the sky on a dark outdoor style. | `sky` | 3.2.4 | Not yet |
+| [Space & halo: simple](./demos/examples/space/orbiting-globe) | A globe turning against a starry space background, with the default halo. | `space` `halo` | 5.0.0-rc.4 | Not yet |
+
+#### Showcases
+
+| Demo | Description | Topics | Created with | Last checked |
+| --- | --- | --- | --- | --- |
+| [Animated route around Madeira](./demos/showcases/animated-routes) | Animates the camera along a Madeira route with `AnimatedRouteLayer`, with stops and photos. | `animation` `routes` | 3.11.0 | Not yet |
+| [Marker animation in the Sahara](./demos/showcases/marker-animation) | Drives two rally car markers around the Erg Chebbi dunes with a single `MaptilerAnimation`, with playback controls. | `animation` `markers` | 5.0.0-rc.4 | Not yet |
+| [Space & halo: transitions](./demos/showcases/spacebox-and-halo) | Switches between every space preset, custom cubemap images, space colors and halo gradients on a globe. | `space` `halo` | 3.5.1-rc1 | Not yet |
+<!-- demos-index:end -->
+
+<br>
+
 ## 📘 API Reference
 
 In addition to the details and examples provided in this readme, check out the [complete API documentation](https://docs.maptiler.com/sdk-js/api/)
@@ -998,7 +1129,7 @@ map.on("load", () => {
 
 Note: if `space.color` or `space.<faces | path | preset>` are not explicitly set in the call to `setSpace`, then the previous value will remain for this field.
 
-Further code examples can be found in `~/demos/`
+See [`demos/examples/space/orbiting-globe`](./demos/examples/space/orbiting-globe) for a simple example, and [`demos/showcases/spacebox-and-halo`](./demos/showcases/spacebox-and-halo) for every preset and option.
 
 ### `ImageViewer`
 
@@ -1565,6 +1696,8 @@ 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" })`.
 
+See [`demos/examples/markers/altitude`](./demos/examples/markers/altitude) for an example.
+
 #### The MapLibre marker
 
 Compared with the MapLibre marker:
@@ -1580,14 +1713,13 @@ 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.
+See [`demos/examples/markers/styled-marker`](./demos/examples/markers/styled-marker) for an example, and `demos/playgrounds/markers*` for every option.
 
 ### Camera routes and animations
 
 The SDK comes with several classes to help with animations, particularly route animations.
 
-See `demos/11-animated-routes.html` for examples.
-See `demos/12-maptiler-animation.html` for examples.
+See [`demos/showcases/animated-routes`](./demos/showcases/animated-routes) and [`demos/showcases/marker-animation`](./demos/showcases/marker-animation) for examples.
 
 #### 🧩 `MaptilerAnimation`
 
@@ -1734,7 +1866,7 @@ animatedRoute.play();
 animatedRoute.pause();
 ```
 
-For a full example of how to use this, look at [the example](./demos/11-animated-routes.html)
+For a full example of how to use this, look at [the showcase](./demos/showcases/animated-routes)
 
 ### Vector Layer Helpers
 

package/dist/ImageViewer/ImageViewer.d.ts

@@ -1,5 +1,6 @@
 import { EaseToOptions, DoubleClickZoomHandler, DragPanHandler, TwoFingersTouchZoomRotateHandler, FlyToOptions, MapOptions, JumpToOptions, ScrollZoomHandler, BoxZoomHandler, KeyboardHandler, CooperativeGesturesHandler, LngLat, PointLike } from '..';
 import { Map } from '../Map';
+import { ImageViewerEventType } from './events';
 import { Evented } from 'maplibre-gl';
 import { ImageViewerFitImageToBoundsControl } from '../controls/ImageViewerFitImageToBoundsControl';
 import { lngLatToPxInternalSymbolKey, pxToLngLatInternalSymbolKey } from './symbols';
@@ -49,7 +50,7 @@ export type ImageMetadata = {
     maxzoom: number;
     tileSize: number;
 };
-export default class ImageViewer extends Evented {
+export default class ImageViewer extends Evented<ImageViewerEventType> {
     /**
      * The UUID of the image.
      *

package/dist/ImageViewer/events.d.ts

@@ -1,16 +1,24 @@
 import { Map } from '../Map';
 import { default as ImageViewer } from './ImageViewer';
-import { LngLat } from 'maplibre-gl';
-export declare class ImageViewerEvent {
-    readonly type: string;
-    readonly target: ImageViewer;
-    readonly originalEvent: MouseEvent | TouchEvent | WheelEvent | WebGLContextEvent | null;
+import { Event as EventML, LngLat } from 'maplibre-gl';
+type ImageViewerOriginalEvent = MouseEvent | TouchEvent | WheelEvent | WebGLContextEvent | null;
+export declare class ImageViewerEvent extends EventML<ImageViewerEventTypes> {
+    target: ImageViewer;
+    originalEvent: ImageViewerOriginalEvent;
     [key: string]: any;
     imageX: number;
     imageY: number;
     isOutOfBounds: boolean;
-    constructor(type: string, viewer: ImageViewer, originalEvent?: MouseEvent | TouchEvent | WheelEvent | WebGLContextEvent | null, data?: Record<string, any>);
+    constructor(type: ImageViewerEventTypes, viewer: ImageViewer, originalEvent?: ImageViewerOriginalEvent, data?: Record<string, any>);
 }
+/** Fired when the viewer fails to load its image. */
+export type ImageViewerInitErrorEvent = EventML<"imagevieweriniterror"> & {
+    error: Error;
+};
+/** Event payloads keyed by event type — every event is an {@link ImageViewerEvent}, apart from the init error. */
+export type ImageViewerEventType = Record<Exclude<ImageViewerEventTypes, "imagevieweriniterror">, ImageViewerEvent> & {
+    imagevieweriniterror: ImageViewerInitErrorEvent;
+};
 declare const BASE_MAP_EVENT_TYPES: readonly ["idle", "render", "load", "remove", "idle"];
 declare const ERROR_EVENTS: readonly ["error"];
 declare const RESIZE_EVENTS: readonly ["resize"];

package/dist/ImageViewer/index.d.ts

@@ -1,5 +1,5 @@
 export { default as ImageViewer } from './ImageViewer';
 export { ImageViewerMarker, ImageViewerMarkerEvent, type ImageViewerMarkerOptions } from './ImageViewerMarker';
-export type { ImageViewerEventTypes } from './events';
+export type { ImageViewerEventTypes, ImageViewerEventType, ImageViewerInitErrorEvent } from './events';
 export type { ImageViewerConstructorOptions, ImageViewerFlyToOptions, ImageViewerJumpToOptions, ImageMetadata } from './ImageViewer';
 export { ImageViewerEvent } from './events';

package/dist/Map.d.ts

@@ -56,6 +56,25 @@ export type MaptilerMapEventType = {
  * so the SDK `Map` overrides them to accept its own events as well.
  */
 export type MapEventTypeSDK = MapEventType & MaptilerMapEventType;
+/**
+ * An event as an SDK `Map` listener receives it. MapLibre types its events' target as its
+ * own `Map`, which lacks the SDK members, but the target is always the SDK `Map` that fired it.
+ *
+ * The target is intersected in, rather than remapped over every event, so the SDK `Map`'s
+ * `on`/`once`/`off` stay assignable to MapLibre's — the SDK `Map` is passed to MapLibre controls and layers.
+ * @example
+ * ```ts
+ * const onClick = (e: MapEventSDK<"click">) => console.log(e.lngLat, e.target.getSpace());
+ * map.on("click", onClick);
+ * ```
+ */
+export type MapEventSDK<T extends keyof MapEventTypeSDK> = MapEventTypeSDK[T] & object & {
+    target: Map;
+};
+/** A layer event as an SDK `Map` listener receives it — see {@link MapEventSDK}. */
+export type MapLayerEventSDK<T extends keyof MapLayerEventType> = MapLayerEventType[T] & object & {
+    target: Map;
+};
 export declare const GeolocationType: {
     POINT: "POINT";
     COUNTRY: "COUNTRY";
@@ -268,24 +287,24 @@ export declare class Map extends MapMLGL {
      * 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<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventSDK<T>) => void): Subscription;
+    on<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventSDK<T>) => 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<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventSDK<T>) => void): this;
+    once<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[]): Promise<MapLayerEventSDK<T>>;
+    once<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventSDK<T>) => void): this;
+    once<T extends keyof MapEventTypeSDK>(type: T): Promise<MapEventSDK<T>>;
     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<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventSDK<T>) => void): this;
+    off<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventSDK<T>) => 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}).

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { getVersion as getMapLibreVersion, Map as MapMLGL, Marker as MarkerMLGL,
 export * from './Marker';
 export { Marker } from './Marker';
 export { Popup, Style, CanvasSource, GeoJSONSource, ImageSource, RasterTileSource, RasterDEMTileSource, VectorTileSource, VideoSource, NavigationControl, GeolocateControl, AttributionControl, LogoControl, ScaleControl, FullscreenControl, TerrainControl, BoxZoomHandler, ScrollZoomHandler, CooperativeGesturesHandler, KeyboardHandler, TwoFingersTouchPitchHandler, MapWheelEvent, MapTouchEvent, MapMouseEvent, } from 'maplibre-gl';
-export { Map, GeolocationType, type AttributionControlOptions, type MapOptions, type LoadWithTerrainEvent, type MaptilerMapEventType, type MapEventTypeSDK } from './Map';
+export { Map, GeolocationType, type AttributionControlOptions, type MapOptions, type LoadWithTerrainEvent, type MaptilerMapEventType, type MapEventTypeSDK, type MapEventSDK, type MapLayerEventSDK, } from './Map';
 export type { CameraPosition, TilePreloadOptions, WithTilePreload, PreloadTilesForBoundsOptions, PreloadTilesForCameraPositionsOptions, PreloadTilesOptions, TilePreloadErrorCallback, TilePreloadProgressCallback, } from './tile-preloading';
 export { type BaseGeocodingOptions, type ByIdGeocodingOptions, type CommonForwardAndReverseGeocodingOptions, type GeocodingOptions, type LanguageGeocodingOptions, type ReverseGeocodingOptions, geocoding, } from './geocoding';
 export * from './controls';