@maptiler/sdk 5.0.0-rc.4 → 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/maptiler-sdk.mjs

@@ -11829,7 +11829,7 @@ class En {
     ne(this, ge, t), ne(this, Pe, xe("div", "maplibregl-ctrl maplibregl-ctrl-group"));
     for (const [e, n] of Object.entries(L(this, oe).containerStyle))
       L(this, Pe).style.setProperty(e, n);
-    return L(this, oe).container = L(this, Pe), L(this, oe).zoom = t.getZoom() + L(this, oe).zoomAdjust, this.map = new Cl(L(this, oe)), this.map.once("style.load", () => {
+    return L(this, oe).container = L(this, Pe), L(this, oe).zoom = t.getZoom() + L(this, oe).zoomAdjust, this.map = new Cl({ ...L(this, oe), space: !1, halo: !1 }), this.map.once("style.load", () => {
       this.map.resize();
     }), this.map.once("load", () => {
       ie(this, K, yl).call(this, L(this, oe).parentRect), ne(this, Zt, ie(this, K, gl).call(this));
@@ -13195,7 +13195,7 @@ function kh() {
   );
 }
 function Th() {
-  return "https://cdn.maptiler.com/maptiler-sdk-js/v5.0.0-rc.4/maplibre-gl-worker.mjs";
+  return "https://cdn.maptiler.com/maptiler-sdk-js/v5.0.0-rc.5/maplibre-gl-worker.mjs";
 }
 function bl() {
   au() || ou(Ih(Th()));
@@ -13664,15 +13664,15 @@ let Cl = class Sl extends su {
     if (this.halo && this.getLayer(this.halo.id) || e.halo === !1) return;
     const a = i;
     if (e.halo && e.halo !== !0) {
-      this.halo = new fr(e.halo), this.removeLayer(this.halo.id), this.addLayer(this.halo, n);
+      this.halo = new fr(e.halo), this.getLayer(this.halo.id) && this.removeLayer(this.halo.id), this.addLayer(this.halo, n);
       return;
     }
     if (a) {
-      this.halo = new fr(a), this.removeLayer(this.halo.id), this.addLayer(this.halo, n);
+      this.halo = new fr(a), this.getLayer(this.halo.id) && this.removeLayer(this.halo.id), this.addLayer(this.halo, n);
       return;
     }
     if (this.options.halo === !0) {
-      this.halo = new fr(!0), this.removeLayer(this.halo.id), this.addLayer(this.halo, n);
+      this.halo = new fr(!0), this.getLayer(this.halo.id) && this.removeLayer(this.halo.id), this.addLayer(this.halo, n);
       return;
     }
   }
@@ -17807,7 +17807,7 @@ class Im {
   }
 }
 function ql() {
-  return "5.0.0-rc.4";
+  return "5.0.0-rc.5";
 }
 export {
   _m as AJAXError,