@maptiler/sdk 3.7.0 → 3.8.0-rc.9

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.
@@ -675,6 +820,50 @@ Note: if `space.color` or `space.<faces | path | preset>` are not explicitly set
 
 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 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 = {
+    imageUUID: string; // the unique UUID of the image object you are displaying
+    center?: [number, number]; // the center you want the viewer to init on, defaults to the center of the image.
+    container: string | HTMLElement // the container element you want to mount the viewer on
+    apiKey: string; // your MapTiler API Key
+    zoom?: number;
+    maxZoom?: number; 
+    minZoom?: number;
+    bearing?: number;
+    debug?: boolean; // whether you want to debug the tiles
+  };
+
+  const imageViewer = new ImageViewer({
+    container: document.getElementById("map")!, // the container element you want to use
+    apiKey: "YOUR_MAPTILER_API_KEY", // your api key
+    imageUUID: "11111111-2222-3333-4444-555555555555", // unique UUID of the image object
+    // ...other options, see below
+  }: ImageViewerConstructorOptions);
+
+  await imageViewer.onReadyAsync()
+
+  // OR
+
+  imageViewer.on("imageviewerready", () => { console.log('Ready!') })
+```
+
+## Methods
+`ImageViewer` provides a subset of methods for interaction with the map. A major caveat is that the `ImageViewer` component works in pixels and not in LngLat. Thus, when using methods such as `setCenter` or `flyTo` the pixel values provided refer to the _absolute pixel position_ on the image, not screen pixel position.
+
+Imagine your image is 10,000px x 10,000px, if regardless if your zoom is 2 or 4, calling `.setCenter(500,500)` will always position the viewer over the same part of the image.
+
+For full details on supported methods see the type declaration for `ImageViewer`.
+
+## Events
+In a similar manner, a subset of map events are fired by the image viewer. All UI interaction events that would normally include a `LngLat` in the event data instead receive an `imageX` and `imageY` field, representing an absolute pixel position of the image. This is same for `flyTo`, `jumpTo`, `panTo` etc.
+
+A full list of supported events can be found in the exported type declaration `ImageViewerEventTypes`
+
+
 # Easy language switching
 The language generally depends on the style but we made it possible to easily set and update from a built-in list of languages.
 

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;