@maptiler/sdk 3.8.0-rc7 → 3.8.0

package/README.md

@@ -451,7 +451,145 @@ const map = new Map({
 })
 ```
 
+# 🧩 Custom Controls
 
+MapTiler SDK JS supports two flexible ways to add custom controls to your map interface. Whether you're building a dynamic application or integrating with static HTML, there's a matching approach for both.
+
+## Programmatic Controls
+
+Use `map.addControl()` with `MaptilerExternalControl` to register custom UI elements manually. This approach is ideal for dynamic logic, event-driven behavior, or integration with frameworks like React. The control element can be provided either as a reference to the **element itself**, or as its **CSS selector**. Optionally, two callback functions can be provided:
+
+* `onClick` function that is called when the element is clicked, and
+* `onRender` function that is called every time the map renders a new state.
+
+Both callbacks receive the active `Map` instance, the associated control element itself, and an event object associated with the original event (`PointerEvent` and `MapLibreEvent` respectively).
+
+### Example
+
+```ts
+const panControl = new maptilersdk.MaptilerExternalControl(
+  ".pan-control",
+  (map) => map.panBy([10, 10]), // Move southeast on click
+  (map, el) => el.classList.toggle( // Style based on hemisphere
+    "northern-hemisphere", map.getCenter().lat > 0
+  )
+);
+map.addControl(panControl);
+
+const element = document.createElement("button");
+element.textContent = "Pan NW";
+map.addControl(
+  new maptilersdk.MaptilerExternalControl(
+    element,
+    (map) => map.panBy([-10, -10]) // Move northwest
+  ),
+  "top-left"
+);
+```
+
+### Behavior Overview
+
+- On add, control element is moved into the map UI
+- `onClick` binds user interaction
+- `onRender` enables state-based styling or logic
+- Control maintains its own DOM context
+- On removal, element is returned to its original DOM position (if any) to not interfere with DOM handling of frameworks like React
+
+## Declarative Controls
+
+Add controls using HTML attributes – no JavaScript required. This is perfect for simple UI setups.
+
+### Enabling Detection
+
+```ts
+const map = new maptilersdk.Map({
+  container: "map",
+  customControls: true, // or ".custom-ui"
+});
+```
+
+You can pass `true` to enable detection globally, or a CSS selector to scope it.
+
+### Declaring Controls
+
+Use `data-maptiler-control` attribute:
+
+```html
+<button data-maptiler-control="zoom-in">+</button>
+```
+
+Supported values:
+
+| Value               | Description                                      |
+|---------------------|--------------------------------------------------|
+| `zoom-in`           | Zooms in                                         |
+| `zoom-out`          | Zooms out                                        |
+| `toggle-projection` | Switches Mercator ↔ Globe                        |
+| `toggle-terrain`    | Toggles terrain layer                            |
+| `reset-view`        | Resets bearing, pitch, and roll                  |
+| `reset-bearing`     | Resets bearing only                              |
+| `reset-pitch`       | Resets pitch only                                |
+| `reset-roll`        | Resets roll only                                 |
+| *(empty)*           | Registers control without built-in functionality |
+
+> ⚠️ An error is thrown if an unrecognized value is used.
+
+### Grouping Controls
+
+Use `data-maptiler-control-group` to group buttons:
+
+```html
+<div data-maptiler-control-group>
+  <button data-maptiler-control="zoom-in">+</button>
+  <button data-maptiler-control="zoom-out">−</button>
+</div>
+```
+
+Groups are styled and positioned together but don't add functionality themselves. Functional behavior is attached to valid descendant elements.
+
+### Positioning Controls
+
+Use `data-maptiler-position` to set placement:
+
+```html
+<button data-maptiler-control="reset-view" data-maptiler-position="top-left">↻</button>
+<div data-maptiler-control-group data-maptiler-position="bottom-right">
+  <button data-maptiler-control="zoom-in">+</button>
+  <button data-maptiler-control="zoom-out">−</button>
+</div>
+```
+
+Valid positions: `'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'`
+
+## Styling with CSS Variables
+
+When declarative controls are enabled, the map container exposes dynamic CSS variables:
+
+| Variable                         | Description                                      | Type            |
+|----------------------------------|--------------------------------------------------|-----------------|
+| `--maptiler-center-lng`          | Longitude of center                              | unitless number |
+| `--maptiler-center-lat`          | Latitude of center                               | unitless number |
+| `--maptiler-zoom`                | Zoom level                                       | unitless number |
+| `--maptiler-bearing`             | Map rotation                                     | unitless number |
+| `--maptiler-pitch`               | Pitch angle                                      | unitless number |
+| `--maptiler-roll`                | Roll angle                                       | unitless number |
+| `--maptiler-is-globe-projection` | `true` if globe is active<br>`false` otherwise   | string          |
+| `--maptiler-has-terrain`         | `true` if terrain is active<br>`false` otherwise | string          |
+
+### Example
+
+```css
+.compass-icon {
+  transform: rotateX(calc(var(--maptiler-pitch) * 1deg))
+             rotateZ(calc(var(--maptiler-bearing) * -1deg));
+}
+
+@container style(--maptiler-is-globe-projection: true) {
+  .projection-icon {
+    content: "globe";
+  }
+}
+```
 
 # 3D terrain in one call
 <p align="center">
@@ -592,6 +730,13 @@ map.on("load", () => {
   });
 });
 ```
+
+To disable state transitions for halo or space:
+```ts
+map.disableHaloAnimations();
+map.disableSpaceAnimations();
+```
+
 ## `space` (Background Environment)
 
 The space option allows customizing the background environment of the globe, simulating deep space or skybox effects.
@@ -677,7 +822,7 @@ Further code examples can be found in `~/demos/`
 
 # `ImageViewer`
 
-MapTiler's `ImageViewer` component allows you to display tiled, non-georeferenced images but interact with them the same way you would if you were displaying map. These can be handy for zoomable non-georeferenced, geographically "inaccurate" maps such as hotel maps, golf courses, theme parks etc. Think pixels instead of lattitudes and longtidues.
+MapTiler's `ImageViewer` component allows you to display tiled, non-georeferenced images but interact with them in almost the same way you would if you were displaying map. These can be handy for zoomable non-georeferenced, geographically "inaccurate" maps such as hotel maps, golf courses, theme parks etc. Think pixels instead of lattitudes and longtidues.
 
 ```ts
   export type ImageViewerConstructorOptions = {

package/dist/maptiler-sdk.css

@@ -143,6 +143,11 @@
   background-image: url("data:image/svg+xml;charset=utf-8,%3Csvg%20width%3D%2233%22%20height%3D%2233%22%20viewBox%3D%220%200%2033%2033%22%20fill%3D%22none%22%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%3E%0A%3Cpath%20fill-rule%3D%22evenodd%22%20clip-rule%3D%22evenodd%22%20d%3D%22M26.5%209.85H6.5C6.41716%209.85%206.35%209.91716%206.35%2010V23C6.35%2023.0828%206.41716%2023.15%206.5%2023.15H26.5C26.5828%2023.15%2026.65%2023.0828%2026.65%2023V10C26.65%209.91716%2026.5828%209.85%2026.5%209.85ZM6.5%208C5.39543%208%204.5%208.89543%204.5%2010V23C4.5%2024.1046%205.39543%2025%206.5%2025H26.5C27.6046%2025%2028.5%2024.1046%2028.5%2023V10C28.5%208.89543%2027.6046%208%2026.5%208H6.5Z%22%20fill%3D%22%23444952%22%2F%3E%0A%3Cpath%20d%3D%22M5.5%2012.8H28.5V14.65H5.5V12.8Z%22%20fill%3D%22%23444952%22%2F%3E%0A%3Cpath%20d%3D%22M10.0375%2025L10.0375%208L11.8875%208L11.8875%2025H10.0375Z%22%20fill%3D%22%23444952%22%2F%3E%0A%3Cpath%20d%3D%22M15.5751%2025L15.5751%208L17.4251%208L17.4251%2025H15.5751Z%22%20fill%3D%22%23444952%22%2F%3E%0A%3Cpath%20d%3D%22M21.1127%2025V8L22.9627%208L22.9627%2025H21.1127Z%22%20fill%3D%22%23444952%22%2F%3E%0A%3Cpath%20d%3D%22M5.5%2018.35H28.5V20.2H5.5V18.35Z%22%20fill%3D%22%23444952%22%2F%3E%0A%3C%2Fsvg%3E%0A");
 }
 
+/* Center image control icon - globe */
+.maplibregl-ctrl button.maplibregl-ctrl-fit-image-to-bounds .maplibregl-ctrl-icon {
+  background-image: url("data:image/svg+xml;charset=utf-8,%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%0A%3Csvg%0A%20%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%0A%20%20width%3D%2224%22%0A%20%20height%3D%2224%22%0A%20%20viewBox%3D%220%200%2032%2032%22%0A%3E%0A%20%20%3Cpath%0A%20%20%20%20fill%3D%22%23444952%22%0A%20%20%20%20d%3D%22M8%202H2v6h2V4h4zm16%200h6v6h-2V4h-4zM8%2030H2v-6h2v4h4zm16%200h6v-6h-2v4h-4zm0-6H8a2%202%200%200%201-2-2V10a2%202%200%200%201%202-2h16a2%202%200%200%201%202%202v12a2%202%200%200%201-2%202M8%2010v12h16V10z%22%0A%20%20%3E%3C%2Fpath%3E%0A%3C%2Fsvg%3E");
+}
+
 .maplibregl-ctrl-scale {
   background-color: hsla(0,0%,100%,.75);
   border: 1px solid #444952;