@aapicoits/powermap-web-sdk

v1.0.1

Published

14 days ago

A professional-grade, high-performance Map SDK. Optimized for logistics, real-time tracking, indoor mapping, and 3D vehicle simulations.

0High
0Medium
0Low

aits-dev

PowerMap Web SDK 🚀

A professional-grade, high-performance Map SDK. Optimized for logistics, real-time tracking, indoor mapping, and 3D vehicle simulations.

2. 🏛️ Architecture Overview

The PowerMap Web SDK is built with a Layered Facade Architecture, ensuring that high-performance map rendering is wrapped in an easy-to-use, fluent JS API.

graph TD
    App[Web Application] --> PM[PowerMap Instance]
    
    subgraph "Facade Layer (Fluent API)"
        PM
    end

    subgraph "Manager Layer (Lazy Loading)"
        PM --> Registry[Component Registry]
        Registry --> MarkerMgr[MarkerManager]
        Registry --> SearchMgr[SearchManager]
        Registry --> RouteMgr[RoutingManager]
        Registry --> GeomMgr[GeometryManager]
        Registry --> EditorMgr[EditorManager]
        Registry --> LayerMgr[LayerManager]
    end

    subgraph "Service Layer"
        PM --> AuthMgr[AuthManager]
        PM --> Events[EventBus]
        AuthMgr --> Cache[Token Cache]
    end

    subgraph "Visual Engine"
        PM --> ML[PowerMap Visual Engine]
    end

    Cache -.-> Storage[(Local Storage)]
    AuthMgr -.-> API((PowerMap APIs))

3. 📦 Installation

Install the package via npm or yarn:

npm install @powermap/web-sdk

4. 🚀 Quick Start

Get a map up and running in less than 2 minutes. The PowerMap SDK is designed for chaining and ease of use.

Step A: Prepare your HTML

<div id="map" style="width: 100%; height: 500px; border-radius: 8px; overflow: hidden;"></div>

Step B: Initialize and Style

import { PowerMap } from "@powermap/web-sdk";

// 1. Initialize with dual-auth system
const map = new PowerMap({
  container: "map",
  center: [100.5018, 13.7563], // Bangkok [Longitude, Latitude]
  zoom: 14,
  mapApiKey: "YOUR_MAP_API_KEY", // Public key for tiles and base layers
  auth: {
    clientId: "YOUR_CLIENT_ID",     // Service Credentials for backend APIs
    clientSecret: "YOUR_CLIENT_SECRET"
  },
  previewOnly: true // Optional: Lock all user interactions (Static View)
});

// 2. Chaining for smooth DX
map.onMapLoaded((e) => {
  console.log("PowerMap is ready!", e.map);
  
  // Add a marker as soon as the map loads
  map.addMarker({
    position: [100.5018, 13.7563],
    type: "start",
    popupContent: "<strong>Origin Point</strong>"
  });
})
.setStyle('th') // Options: 'th', 'en', 'dark', 'gray'
.flyTo({ zoom: 16, pitch: 45 });

[!TIP] Performance Note: The PowerMap Web SDK uses a lazy-loading registry pattern. Managers (Routing, Search, etc.) are only initialized once you first call them, keeping your app's initial memory footprint minimal.

5. 🔗 Method Chaining

The PowerMap SDK is built with a fluent interface, allowing you to link multiple configuration steps and event listeners together in a single statement.

Supported Methods

Most methods that perform an action on the map (styling, camera movement, or event registration) return the PowerMap instance to facilitate chaining.

[!NOTE] Methods that return a Promise (like addRoute) or a new Object (like addMarker or getRouteDetails) interrupt the chain.

Chaining Example

map.onMapLoaded(() => console.log("Ready!"))
  .onMarkerClick(data => console.log("Clicked:", data))
  .setStyle('dark')
  .flyTo({ center: [100.5, 13.7], zoom: 12 })
  .setPitch(45);

6. 🛠️ Configuration Reference

When creating a new PowerMap(options), the following options are available:

Core Instance Methods

These methods are available on the PowerMap instance to manage the map state and lifecycle.

7. 📍 Marker Management

Our marker system simplifies standard map markers with built-in presets for logistics and easy event handling.

`addMarker(options)` Options

[!IMPORTANT] High-Accuracy Rendering: Markers with a color property use our new GL Symbol Layer system. These markers are rendered directly on the map canvas, ensuring perfect alignment and zero-lag during zoom or pan. Ordinary preset markers (type) use standard DOM elements for maximum compatibility.

Marker Examples

Standard Presets

map.addMarker({
  position: [100.5, 13.7],
  type: 'start', // 'start', 'destination', 'waypoint'
  popupContent: "Start Point"
});

Premium Colored Markers (No Image Required)

map.addMarker({
  position: [100.52, 13.78],
  color: '#f97316',      // Vibrant Orange
  icon: 'fas fa-store',  // FontAwesome Icon
  draggable: true,      // Enable high-accuracy dragging
  popupContent: {
    title: "Power Shop",
    tag: "Retail",
    body: "Custom colored marker with icon."
  }
});

Draggable Markers & Events

You can enable dragging for any marker. For GL-rendered markers (those with color), dragging is handled with sub-pixel precision.

const marker = map.addMarker({
  position: [100.5, 13.7],
  color: '#3b82f6',
  draggable: true
});

// 1. Listen via Proxy (Recommended)
marker.on('drag', (e) => console.log('Current:', e.lngLat));
marker.on('dragend', (e) => console.log('Final:', e.lngLat));

// 2. Listen via Global Event Bus
map.onMarkerDrag(({ marker, lngLat }) => {
  console.log(`Marker is moving to: ${lngLat.lng}, ${lngLat.lat}`);
});

Structured Popup Content & Actions

Instead of raw HTML, you can pass a structured object to popupContent for a premium, consistent look. You can also define interactive buttons using the action or actions property:

map.addMarker({
  position: [100.5, 13.7],
  popupContent: {
    title: "Siam Paragon",
    tag: "Mall",
    body: "The pride of Bangkok with world-class shopping.",
    footer: "Open: 10:00 - 22:00",
    actions: [
      { label: "View Details", url: "https://example.com/details", target: "_blank" },
      { label: "Navigate Here", url: "https://example.com/nav", color: "#10b981" }
    ]
  }
});

Marker Methods

8. 🎨 CSS Customization

The PowerMap SDK automatically wraps all map elements in a global .powermap-sdk class and provides branded aliases for all internal UI components.

The Global Wrapper

Any HTML element you provide as a container will automatically have the powermap-sdk class applied at runtime. This provides a clean scope for all PowerMap styles.

<!-- Input -->
<div id="map"></div>

<!-- Output at runtime -->
<div id="map" class="powermap-sdk">...</div>

Premium Class Aliases

To make customization even more intuitive, we've provided branded CSS classes that you can target directly:

Premium Overrides

Target your own CSS using the scoped wrapper or branded aliases:

/* Change the header color of structured popups */
.powermap-sdk .pm-popup-header {
  background: linear-gradient(135deg, #000 0%, #333 100%);
}

/* Customize the glassmorphism background of all popups */
.powermap-sdk .pm-popup-content {
  background: rgba(255, 255, 255, 0.95);
  backdrop-filter: blur(20px);
}

/* Custom Marker Scale */
.powermap-sdk .pm-marker {
  transform: scale(1.1);
}

`setNavigationControl(options)` Options

Map Control Examples

// Simple: Enable default branded controls (top-right)
map.setNavigationControl(true);

// Advanced: Custom position and visibility
map.setNavigationControl({
  position: 'bottom-right',
  showZoom: true,
  showCompass: false
});

// Disable controls
map.setNavigationControl(false);

9. 🛣️ Routing & Optimization

Generate high-precision routes with automatic visualization. The SDK automatically fits the map view to the resulting route.

`addRoute(options)` Options

Route Methods

`addRoute(options)` Return Object

The addRoute method returns a Promise that resolves to a RouteResult object containing:

`steps` Object Structure

Each step in the steps array represents a turn or maneuver:

Routing Example

// Simple route from A to B
const route = await map.addRoute({
  start: [100.5018, 13.7563],
  destination: [100.5118, 13.7663],
  language: "en"
});

// Complex optimized route with waypoints
const optimizedRoute = await map.addRoute({
  start: [100.50, 13.75],
  destination: [100.60, 13.85],
  waypoints: [
    [100.55, 13.80],
    [100.52, 13.78]
  ],
  optimize: true, // Will reorder the 2 waypoints for the best efficiency
  language: "th"
});

console.log(`Total Distance: ${optimizedRoute.distance}m`);
console.log(`Total Duration: ${optimizedRoute.duration}s`);

// Custom red route for heavy traffic visualization
const redRoute = await map.addRoute({
  start: [100.5, 13.7],
  destination: [100.6, 13.8],
  routeColor: "#ff0000",
  routeWidth: 10,
  casingColor: "#990000"
});

// Clear all routes from visibility
map.clearRoutes();

📍 Route Summary Helpers

Quickly access formatted summaries (distance in km/m, time in hours/mins) for the total route and individual steps:

// Get enhanced details (Recommended)
const details = map.getRouteDetails();
if (details) {
    console.log(`Total: ${details.distanceStr}, Time: ${details.durationStr}`);
    
    // Each step also contains formatted strings
    details.steps.forEach(step => {
        console.log(`${step.text} (${step.distanceStr})`);
    });
}

// Get just the top-level summary
const summary = map.getRouteSummary(); // { distanceStr, durationStr }

🏗️ 10. Map Layers Management

The LayerManager provides a robust API to toggle built-in map layers (e.g., Roads, Railways, BTS/MRT, City Plans) on and off. The SDK dynamically fetches these layers from the catalog and applies them to your current map style.

Built-in Layer Groups

Map layers are grouped into 3 main categories:

CITY PLAN (city): City plans for various provinces.
TRANSPORT (transport): Roads, Current/Future Railways, Current/Future BTS/MRT.
INSIGHT DATA (insight): Night lights, Satellite imagery.

Layer APIs

| Method | Arguments | Description | | :--- | :--- | :--- | | map.layers.getCatalog() | - | Returns the full list of available layer groups and IDs. | | map.layers.ensure(layerId) | string | Ensures a layer's sources are created (idempotent). | | map.layers.show(layerId) | string | Ensures and shows a specific layer. | | map.layers.hide(layerId) | string | Hides a specific layer. | | map.layers.toggle(layerId) | string | Toggles the visibility of a layer. | | map.layers.getLayerState(id) | string | Returns {loaded, visible} status. | | map.layers.setOpacity(id, val) | string, number | Adjusts the transparency (0.0 - 1.0). | | map.layers.showGroup(key) | string | Shows all layers within a specific group. | | map.layers.hideGroup(key) | string | Hides all layers within a specific group. | | map.layers.hideAll() | - | Hides every active layer from the catalog. |

Usage Example

map.onMapLoaded(async () => {
  // 1. View all available layers
  const catalog = map.layers.getCatalog();
  console.log(catalog);

  // 2. Show the Road layer
  await map.layers.show('pm-road-vt');

  // 3. Toggle the current Railway layer
  await map.layers.toggle('pm-current-railway-th-vt');

  // 4. Adjust opacity
  map.layers.setOpacity('pm-road-vt', 0.5);

  // 5. Hide an entire group
  map.layers.hideGroup('city');
});

You can also use convenience methods directly on the PowerMap instance:

await map.showLayer('pm-road-vt');
map.hideLayer('pm-road-vt');
await map.toggleLayer('pm-road-vt');

[!IMPORTANT] Satellite Layer: High-resolution satellite imagery (pm-maptiler-satellite-layer) requires a maptilerKey provided in the initial PowerMap configuration.

11. 🎥 Camera & Viewport Control

Take full control of the user's perspective with smooth transitions or direct manipulation.

Movement Functions

State Functions

| Method | Arguments | Description | | :--- | :--- | :--- | | setPitch(deg, anim) | number, bool | Set tilt angle (0-85). Smooth by default. | | setBearing(deg, anim) | number, bool | Set direction (0-360). Smooth by default. | | getCenter() | - | Returns {lng, lat} of the current map center. | | getZoom() | - | Returns the current zoom level as a number. | | getPitch() | - | Returns the current pitch (tilt) as a number. | | getBearing() | - | Returns the current bearing (rotation) as a number. |

Camera Examples

// Fly into a specific warehouse view
map.flyTo({
  center: [100.5, 13.8],
  zoom: 17,
  pitch: 60,
  bearing: 45,
  duration: 4000
});

// Fit view to a specific region
map.fitBounds([
  [100.4, 13.7], 
  [100.6, 13.9]
], { padding: 40 });

11. 🔥 Event System

The SDK uses a semantic event system for a modern developer experience. All events can be chained.

Event List & Arguments

| Method | Callback Arguments | Triggered When... | | :--- | :--- | :--- | | onMapLoaded | {map} | The map is fully initialized and layers can be added. | | onClick | {lngLat, point, ...} | The map is clicked. | | onMapLongClick | {lngLat, point, ...} | The map is long-pressed or right-clicked. | | onMarkerClick | {marker, originalEvent, options} | A user clicks on any marker added via SDK. | | onPoiClick | {feature, lngLat, point} | A user clicks on a Point of Interest (POI) on the base map. | | onModeChanged | {mode, options} | The SDK operational mode (standard/indoor) has changed. | | onMarkerDrag | {marker, lngLat, options} | A draggable marker is currently being moved. | | onMarkerDragEnd | {marker, lngLat, options} | A user releases a draggable marker. | | onRouteCalculated | route | A new route has been fetched and drawn. | | onGeometryExported | {data} | GeoJSON data has been exported from the editor. | | layerEnsured | {layerId, group} | A catalog layer has finished initializing sources. | | onError | {source, message} | Any internal error (Auth, Routing, Map) occurs. |

Event Subscription Example

map.onMapLoaded((e) => {
  console.log("Ready!");
})
.onClick((e) => {
  console.log(`Map clicked at: ${e.lngLat}`);
})
.onMarkerClick((data) => {
  alert(`You clicked marker: ${data.options.popupContent}`);
})
.onMarkerDragEnd((data) => {
  console.log(`New Coordinate: ${data.lngLat.lng}, ${data.lngLat.lat}`);
});

12. 🔍 Search & Geocoding

The Web SDK provides built-in search capabilities using the PowerMap Search API.

`search(query, options)`

Available options:

lang: 'th' (default) or 'en'.
location: [latitude, longitude] to prioritize nearby results.

const results = await map.search("Central World", { lang: 'en' });

results.forEach(item => {
  console.log(`${item.name}: ${item.address}`);
  console.log(`Position: ${item.position}`); // [lat, lng]
});

13. 🕹️ Interactive Metadata (POI)

The SDK can detect when a user clicks on a Point of Interest (POI) on the base map (e.g., shopping malls, parks, gas stations).

map.onPoiClick(({ feature, lngLat }) => {
  const name = feature.properties.name_t;
  console.log(`User clicked on: ${name}`);
  
  // Highlighting the POI with a popup
  map.addMarker({
    id: 'poi-temp',
    position: [lngLat.lng, lngLat.lat],
    popupContent: { title: name, tag: 'POI' }
  });
});

14. 🧰 Utility Functions

SDK provides handy formatters for displaying routing data.

15. 📐 Geometry Engine & Editor

The PowerMap SDK includes a professional-grade geometry engine and a built-in UI for creating, editing, and managing spatial data. This is optimized for both simple outdoor measuring and complex indoor mapping.

15.1 The Editor Toolbar

Enable a premium, built-in toolbar that handles the entire drawing lifecycle.

map.editor.enable({
  position: 'bottom-left', // 'top-left', 'top-right', 'bottom-left', 'bottom-right'
  mode: 'standard'         // 'standard' (Logistics) or 'indoor' (Indoor Mapping)
});

Interactive Tools

Standard Mode: Point, Line (Measure), Polygon (Area), Rectangle.
Indoor Mode: Beacon, POI, Walkway, Floor, Obstacle.

15.2 Measurement & Info Panel

When a feature is selected, a real-time measurement panel appears, providing:

Distance: For lines and walkways.
Area: For polygons and floors.
3D Height: For extruded features.
Live Coordinates: For Points (POIs and Beacons), showing relative X/Y metrics dynamically during placement inside buildings, or Latitude/Longitude for outdoor placements.

15.3 Property Editor UI

The PowerMap Editor includes a functional Property Editor panel (available in indoor mode or via the settings icon). It allows you to manage:

Core Metadata: ID and Name.
Classification: Independent feature_type (e.g., level, building, venue), explicit Categories, and Ordinal/Level (for stacking floors).
Visual Styling: Choose colors and icons (for Beacons and POIs).
Custom Properties: Add unlimited key-value pairs for your own business logic.

15.4 3D & Advanced Tools

Take drawing to the next dimension:

Extrude: Transform 2D polygons into 3D buildings or obstacles by setting the height property.
Rotate & Clone: Rapidly duplicate and align features.
Vertical Alignment: Manage ordinal properties to ensure data belongs to the correct floor level.

15.5 Data Lifecycle (Import/Export)

The Editor facilitates easy data exchange via GeoJSON:

Export: Built-in "Download" button in the toolbar, or call map.geometry.export().
Import: Built-in "Upload" button, or call map.geometry.import(geojson).
IMDF Compliance: Indoor fields (feature_type, category, ordinal) are mapped to IMDF format automatically.

15.6 Unified Programmatic CRUD API

For the full reference, see GEOMETRY.md

All operations — whether from draw tool or code — emit the same geometryChanged event.

// CREATE (standard)
const id = map.geometry.create('polygon', {
  coordinates: [[[100.5,13.7],[100.6,13.7],[100.6,13.8],[100.5,13.7]]],
  properties: { fillColor: '#4f46e5', height: 10 }
});

// CREATE (indoor)
const beaconId = map.geometry.create('beacon', {
  lngLat: [100.52, 13.75],
  properties: { ordinal: 1, name: 'BKK-01' }
});

// READ
map.geometry.getById(id);                          // Feature | null
map.geometry.getByKind('beacon');                  // Feature[]
map.geometry.query().byKind('poi').byFloor(1).toArray();  // Feature[]

// UPDATE
map.geometry.update(id, {
  properties: { name: 'Updated Name', color: '#ff0000' }
});

// DELETE
map.geometry.remove(id);
map.geometry.clear();

All CRUD Methods:

15.7 GeometryStore — Placeholder API Bridge

map.geometry.store provides placeholder hooks that fire on every geometry change regardless of origin (draw tool or code). Use this to connect your own backend API.

// Register before the map loads
map.geometry.store.onCreate(async (payload) => {
  console.log('[Placeholder] CREATE', payload);
  // await fetch('/api/features', { method: 'POST', body: JSON.stringify(payload) })
});
map.geometry.store.onUpdate(async (payload) => {
  console.log('[Placeholder] UPDATE', payload);
  // await fetch(`/api/features/${payload.featureId}`, { method: 'PUT', body: JSON.stringify(payload) })
});
map.geometry.store.onDelete(async (payload) => {
  console.log('[Placeholder] DELETE', payload);
  // await fetch(`/api/features/${payload.featureId}`, { method: 'DELETE' })
});

// Used when a developer clicks the "Save" icon on the draw toolbar
map.geometry.store.onSave(async (data) => {
  console.log('[Placeholder] MANUAL SAVE TRIGGERED', data);
  // const success = await saveAllToDatabase(data);
  // if (success) map.geometry.store.setDirty(false); // Clear unsaved warnings
});

Each callback receives a clean payload with user_ prefixes stripped:

{
  operation:  'create' | 'update' | 'delete',
  source:     'draw' | 'programmatic',
  format:     'standard' | 'indoor',
  featureId:  'abc123',
  kind:       'beacon' | 'poi' | ... | null,   // null for standard
  floor:      1 | null,                         // ordinal, null for standard
  timestamp:  '2026-03-27T...',
  geometry:   { type: 'Point', coordinates: [...] },
  properties: { name: 'BKK-01', color: '#fbbf24' }
}

[!NOTE] If no callback is registered, the SDK logs all events to the console automatically with 📦 CREATE / ✏️ UPDATE / 🗑️ DELETE icons.

15.8 SDK Events

// Subscribe to every geometry change (create/update/delete)
map.on('geometryChanged', ({ operation, source, feature }) => {
  // operation: 'create' | 'update' | 'delete'
  // source:    'draw' | 'programmatic'
  // feature:   GeoJSON Feature (null for delete)
});

// Subscribe to live coordinate/property updates from the UI Editor
// Use this to refresh UI panels instantly without waiting for or triggering a backend save.
map.on('geometryLiveUpdate', ({ type, features }) => {
  // type: 'update'
  // features: Array of GeoJSON Features that are currently being edited
});

// Listen to selection changes
map.on('geometrySelectionChanged', ({ features }) => {
  // Array of currently selected feature objects
});

16. 🏠 Indoor Mapping

The PowerMap SDK provides a robust API for managing indoor environments, including floor switching, category filtering, and specialized geometry handling.

16.1 Enabling Indoor Mode

Switch to indoor mode to enable building-specific logic and specialized drawing tools (e.g., Beacons, Walkways).

map.setMode('indoor');

16.2 Floor Management (`map.indoor`)

When in indoor mode, use the map.indoor facade to control the vertical context of the map.

Switching Floors with Animation

// Switch to Floor 2 with a smooth fade transition
map.indoor.setFloor(2, { animate: true });

Building a Dynamic Floor Selector UI

// Get all available floors to populate a dropdown
const floors = map.indoor.getAvailableFloors(); 
// Returns: [1, 2, 3] or [] if no indoor data is found

16.3 Visibility Control

Toggle the visibility of specific indoor data categories. These settings persist across floor changes.

// Toggle individual categories
map.indoor.setCategoryVisible('poi', true);       // Points of Interest
map.indoor.setCategoryVisible('beacon', false);   // Beacons/Sensors
map.indoor.setCategoryVisible('walkway', true);   // Navigation Paths
map.indoor.setCategoryVisible('obstacle', true);  // 3D Obstacles/Buildings

16.4 Indoor Data Kinds

The SDK categorizes indoor features using the user_kind (or kind) property:

floor: The walkable surface area of a floor (Polygon).
obstacle: Non-walkable areas. Can be extruded into 3D.
walkway: Navigable path lines for indoor routing.
poi: Indoor points of interest with custom icons.
beacon: Positioning hardware or logical points.

16.5 Event Synchronization

// Listen for mode changes
map.on('onModeChanged', ({ mode }) => {
  console.log(`Mode switched to: ${mode}`); // 'standard' or 'indoor'
});

// Sync UI when data is added/deleted or imported
map.on('geometryChanged', () => {
   const updatedFloors = map.indoor.getAvailableFloors();
   // Refresh your floor selector here
});

17. ⌨️ Keyboard Shortcuts

The SDK provides built-in productivity shortcuts whenever the geometry engine is active:

Ctrl + C: Copy selected geometry.
Ctrl + V: Paste geometry at the current cursor position.
Delete / Backspace: Remove selected features.

18. 🩺 Debug & Telemetry

Enable the Debug HUD during development to monitor performance and coordinates.

// Enable debug panel
map.debug().enable({ position: 'top-right' });

// Toggle specific metrics
map.debug().showFPS(true);
map.debug().showCoordinate(false);

// Disable
map.debug().disable();

19. 🛠 Build & Development

For contributors to the SDK core:

Contributor Guide

Setup Environment:
```
npm install
```
Local Development:
```
npm run dev
```
Production Build:
```
npm run build
```

Project Structure

/src/core: Map lifecycle and shared managers.
/src/geometry: Drawing engine and coordinate logic.
/src/editor: Toolbar UI and control components.
/src/routing: Navigation and path-finding.
/src/auth: Security and API tokens.

📌 Appendix A: Complete SDK Event List

The SDK emits the following events through its central EventBus. You can subscribe to them via map.on(eventName, callback).

🌍 Core / Global

| Event | Payload | Description | |---|---|---| | mapLoaded | { map } | Fired when PowerMap finishes loading the style and is ready. | | mapStyleChanged | { styleKey } | Fired after switching the base map style. | | modeChanged | { mode, options } | Fired when SDK interactive mode changes (e.g. mode_free → mode_routing). | | error | PowerMapError | Fired globally for SDK internal errors. |

📐 Geometry & Draw

| Event | Payload | Description | |---|---|---| | geometryChanged | { operation/type, source, feature(s) } | Fired upon completion of a CRUD operation or drawing action. | | geometryLiveUpdate | { type: 'update', features } | Fired rapidly during property/coordinate editing for real-time UI mapping. | | geometrySelectionChanged | { features } | Fired when the active selection changes in drawing mode. |

📍 Markers

| Event | Payload | Description | |---|---|---| | markerAdded | { marker, options } | Fired when a new marker is added to the map. | | markerRemoved | { marker\|id } | Fired when a marker is explicitly removed. | | markerClick | { marker, originalEvent, options } | Fired when a marker is clicked. | | markerDrag | { marker, lngLat, options } | Fired continuously while a draggable marker is being dragged. | | markerDragEnd | { marker, lngLat, options } | Fired when a marker is dropped after dragging. | | markersCleared| - | Fired when all markers on the map are cleared. |

🏢 Indoor

| Event | Payload | Description | |---|---|---| | floorChanged | ordinal (number) | Fired when the active indoor floor changes. |

🗺️ Routing & Navigation

| Event | Payload | Description | |---|---|---| | routeRequestStart| options | Fired when a route calculation request is initiated. | | routeCalculated | GeoJSON Feature | Fired upon successful calculation of a MultiLineString route. | | routeCleared | - | Fired when the active route is removed from the map. | | navigationStart | - | Fired when Turn-by-Turn navigation is initiated. | | navigationEnd | - | Fired when Turn-by-Turn navigation stops. | | simulationStart | - | Fired when GPS Route Simulator starts running. | | simulationUpdate| { position, step } | Fired at every tick of the GPS simulator with the interpolated position. | | simulationEnd | - | Fired when GPS simulation halts or reaches the destination. |

🎨 Layers

| Event | Payload | Description | |---|---|---| | layerVisibilityChanged| { layerId, visible } | Fired when a system layer's visibility is toggled. | | layerEnsured | { layerId, group } | Fired when the SDK auto-creates a missing required layer group. |