dependencies {
    // Option A — local AAR (you must declare the dependencies below by hand)
    implementation(files("libs/maps-sdk-0.1.0.aar"))

    // MapLibre — exposed via `api`, required on the classpath
    implementation("org.maplibre.gl:android-sdk:11.13.5")

    // AndroidX core (must already be on the host app)
    implementation("androidx.core:core-ktx:1.10.1")
    implementation("androidx.appcompat:appcompat:1.7.0")

    // Networking + coroutines (used internally by the SDK)
    implementation("com.squareup.retrofit2:retrofit:2.9.0")
    implementation("com.squareup.retrofit2:converter-gson:2.9.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")

    // Option B — internal Maven: transitives resolve automatically, nothing to declare
    // implementation("com.gtelmaps:maps-sdk:0.1.0")
}

<uses-permission android:name="android.permission.INTERNET" />
<!-- only needed for My Location -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

GTELMAP_API_KEY=your_gtelmap_api_key
GTELMAP_WEATHER_APP_ID=your_openweather_app_id   # only needed for the Weather service

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        if (!MapSdk.isInitialized) {
            MapSdk.init(MapSdkConfig(
                apiKey = BuildConfig.GTELMAP_API_KEY,
                weatherAppId = BuildConfig.GTELMAP_WEATHER_APP_ID.ifBlank { null },
                enableHttpLogging = BuildConfig.DEBUG,
            ))
        }
    }
}

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.gtelmaps.sdk.core.OtsMapView
        android:id="@+id/mapView"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</FrameLayout>

class MapActivity : AppCompatActivity() {
    private lateinit var map: OtsMapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_map)
        map = findViewById(R.id.mapView)
        map.onCreate(savedInstanceState)
        map.setStyle(MapStyle.STREETS) {
            map.moveCamera(LatLng(21.0278, 105.8342), zoom = 12.0)
        }
    }

    // forwarding the full lifecycle is mandatory
    override fun onStart()   { super.onStart();   map.onStart() }
    override fun onResume()  { super.onResume();  map.onResume() }
    override fun onPause()   { map.onPause();   super.onPause() }
    override fun onStop()    { map.onStop();    super.onStop() }
    override fun onDestroy() { map.onDestroy(); super.onDestroy() }
    override fun onLowMemory() { super.onLowMemory(); map.onLowMemory() }
}

map.moveCamera(LatLng(10.7769, 106.7009), zoom = 14.0)   // instant jump

map.animateCamera(                                       // smooth animation, rotate + tilt
    CameraPosition(LatLng(10.7769, 106.7009), zoom = 15.0, bearing = 30.0, tilt = 45.0),
    durationMs = 800,
)

map.fitBounds(LatLngBounds(LatLng(10.76, 106.69), LatLng(10.79, 106.71)))
map.fitToMarkers(paddingPx = 80)                       // fit every marker

private val geo = GeocodingClient.create()

map.setEventListener(object : MapEventListener {
    override fun onMapTap(point: LatLng) {
        lifecycleScope.launch {
            val r = geo.reverseGeocode(point, size = 1, zoom = 18)
            val place = (r as? Resource.Success)?.data?.firstOrNull() ?: return@launch
            if (place.layer != "poi") return@launch   // a street address, not a venue
            showPoiSheet(place)
        }
    }
})

private suspend fun showPoiSheet(place: Place) {
    place.location?.let { map.addMarker(MarkerOptions(position = it, title = place.name)) }

    val id = place.id ?: return
    val detail = (geo.placeDetail(listOf(id)) as? Resource.Success)?.data?.firstOrNull() ?: place

    sheet.render(
        name     = detail.name,
        address  = detail.address,
        category = detail.category ?: detail.primaryType,
        phone    = detail.phone,
        website  = detail.website,
    )
    detail.viewport?.let { map.fitBounds(it) }   // the venue's suggested camera bounds
}

val r = geo.nearby(location = center, types = "restaurant,cafe", radius = 1500, size = 20)
if (r is Resource.Success) {
    map.setMarkers(r.data.mapNotNull { p ->
        p.location?.let { MarkerOptions(position = it, title = p.name, snippet = p.address) }
    })
    map.fitToMarkers()
}

map.setLayersVisibilityByIdContains("poi", visible = false)   // -> the layer ids it touched
map.currentStyleLayerIds()                                    // inspect what the style actually has

val nav = NavigationClient.create()
val r = nav.route(
    waypoints = listOf(LatLng(21.0278, 105.8342), LatLng(21.0368, 105.8500)),
    profile = "car",   // "car" | "bike" | "foot"
)
if (r is Resource.Success) {
    map.showRoute(r.data)
    println("${r.data.distanceMeters} m, ~${r.data.durationSeconds} s")
}
map.clearRoute()

val r = nav.alternativeRoutes(origin, destination)
if (r is Resource.Success) map.showRouteAlternatives(r.data, selectedIndex = 0)

// tap to pick a different route
map.queryRouteAlternativeAt(point) { i -> i?.let { map.selectRouteAlternative(it) } }

map.showNavRoute(route.geometry, zoom = 17.0, tilt = 50.0)
map.setVehicleAvatar(carBitmap, position = route.geometry.first(), bearingDegrees = 0.0)

// on every location tick — the SDK interpolates position/bearing/camera/vanishing point
map.updateNavProgress(position = cur, bearingDeg = brg, fractionTraveled = 0.35, durationMs = 1000)
map.clearNavRoute()

val r = AdminUnitClient.create().provinceBoundary("01")
(r as? Resource.Success)?.data?.boundaryGeoJson?.let { map.showAdminBoundary(it) }
map.clearAdminBoundary()

map.setEventListener(object : MapEventListener {
    override fun onMapTap(point: LatLng) { }
    override fun onMapLongPress(point: LatLng) { }
    override fun onMarkerClick(marker: MarkerOptions) { }
    override fun onCameraIdle(center: LatLng, zoom: Double) { }
})

map.enableMyLocation(follow = true)   // show the puck + follow with the camera
map.setFollowMode(false)              // stop following, keep the puck
map.disableMyLocation()

val tracker = LocationTracker.create(context) { latLng -> /* new fix */ }
tracker.start()   // emits the last-known fix immediately, then live updates
// …
tracker.stop()    // always stop to release the listener

val geo = GeocodingClient.create()
val r = geo.autocomplete(
    text = "cà phê",
    focus = LatLng(21.0278, 105.8342),   // bias results toward this point
    layers = listOf(PlaceLayer.POI),
    size = 8,
)
if (r is Resource.Success) r.data.forEach { println("${it.name} — ${it.address}") }

// coordinates → address
val addr = (geo.reverseGeocode(LatLng(21.0278, 105.8342)) as? Resource.Success)
    ?.data?.firstOrNull()?.address

// nearby POIs (rich payload: phone, website, distanceMeters, viewport…)
geo.nearby(location = LatLng(21.0278, 105.8342), types = "restaurant,cafe", radius = 1500)

val nav = NavigationClient.create()

// basic route (≥ 2 waypoints)
nav.route(waypoints, profile = "car", overview = "full", steps = true)

// alternative routes (exactly 2 waypoints)
nav.alternativeRoutes(origin, destination)

// raw OSRM JSON to feed your own turn-by-turn engine
nav.rawRoute(waypoints, profile = "car")

when (val r = geo.reverseGeocode(point)) {
    is Resource.Success -> use(r.data)
    is Resource.Error   -> showError(r.message, r.code)
    Resource.Loading    -> Unit
}

// or, more compactly
geo.reverseGeocode(point)
    .onSuccess { places -> /* … */ }
    .onError   { err -> Log.e("Map", err.message) }

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent { MapScreen() }
    }
}

@Composable
fun MapScreen() {
    val map = rememberOtsMapView()
    AndroidView(factory = { map }, modifier = Modifier.fillMaxSize()) {
        it.setStyle(MapStyle.STREETS) {
            // set the camera after the style loads — avoids a first-frame jump
            it.moveCamera(LatLng(21.0278, 105.8342), zoom = 12.0)
        }
    }
}

lifecycleScope.launch {
    when (val r = MapsClient.create().listStyles()) {
        is Resource.Success -> r.data.forEach { println("${it.name} → ${it.id}") }
        is Resource.Error   -> toast(r.message)
        else -> Unit
    }
}

// load by raw style id (including styles not yet in the MapStyle enum)
map.setStyleUrl(MapsClient.create().styleJsonUrl("gtelmaps-dark-vms-v1"))

class SearchViewModel : ViewModel() {

    private val geo = GeocodingClient.create()
    private val query = MutableStateFlow("")
    var focus: LatLng? = null          // current camera centre

    val suggestions: StateFlow<List<Place>> = query
        .debounce(250)
        .map { it.trim() }
        .distinctUntilChanged()
        .flatMapLatest { text ->
            if (text.length < 2) flowOf(emptyList())
            else flow {
                val r = geo.autocomplete(
                    text = text,
                    focus = focus,                    // bias results toward nearby places
                    layers = listOf(PlaceLayer.POI, PlaceLayer.ADDRESS),
                    size = 8,
                )
                emit(if (r is Resource.Success) r.data else emptyList())
            }
        }
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), emptyList())

    fun onQueryChange(text: String) { query.value = text }
}

@Composable
fun SearchBar(vm: SearchViewModel, map: OtsMapView) {
    var text by remember { mutableStateOf("") }
    val items by vm.suggestions.collectAsStateWithLifecycle()

    Column {
        OutlinedTextField(
            value = text,
            onValueChange = { text = it; vm.onQueryChange(it) },
            placeholder = { Text("Search places…") },
            singleLine = true,
            modifier = Modifier.fillMaxWidth(),
        )
        LazyColumn {
            items(items) { place ->
                ListItem(
                    headlineContent = { Text(place.name) },
                    supportingContent = { place.address?.let { Text(it) } },
                    modifier = Modifier.clickable {
                        place.location?.let { map.moveCamera(it, zoom = 16.0) }
                        map.setMarkers(listOf(MarkerOptions(place.location!!, title = place.name)))
                        text = place.name
                    },
                )
            }
        }
    }
}

class DropPinController(
    private val map: OtsMapView,
    private val scope: CoroutineScope,
    private val onAddress: (LatLng, String) -> Unit,
) {
    private val geo = GeocodingClient.create()
    private var job: Job? = null

    fun attach() {
        map.setEventListener(object : MapEventListener {
            override fun onMapLongPress(point: LatLng) {
                map.setMarkers(listOf(MarkerOptions(point, title = "Resolving address…")))
                job?.cancel()
                job = scope.launch {
                    when (val r = geo.reverseGeocode(point)) {
                        is Resource.Success -> {
                            val place = r.data.firstOrNull()
                            val label = place?.address ?: place?.name ?: "Unknown address"
                            map.setMarkers(listOf(MarkerOptions(point, title = label)))
                            onAddress(point, label)
                        }
                        is Resource.Error -> onAddress(point, "Error: ${r.message}")
                        else -> Unit
                    }
                }
            }
        })
    }
}

val map = rememberOtsMapView()
val scope = rememberCoroutineScope()
var address by remember { mutableStateOf<String?>(null) }

LaunchedEffect(map) {
    DropPinController(map, scope) { _, label -> address = label }.attach()
}
address?.let { Text(it, style = MaterialTheme.typography.bodyMedium) }

private val nav = NavigationClient.create()

suspend fun drawRoute(map: OtsMapView, from: LatLng, to: LatLng) {
    when (val r = nav.route(waypoints = listOf(from, to), profile = "car", steps = true)) {
        is Resource.Success -> {
            val route = r.data
            map.showRoute(route)
            map.fitBounds(route.geometry.bounds(), paddingPx = 72)
            println("%.1f km · %d min".format(route.distanceMeters / 1000, (route.durationSeconds / 60).toInt()))
            route.steps.forEach { println("${it.maneuverType} ${it.modifier.orEmpty()} → ${it.roadName}") }
        }
        is Resource.Error -> toast(r.message)
        else -> Unit
    }
}

val r = nav.alternativeRoutes(origin = from, destination = to, profile = "car")
if (r is Resource.Success) {
    map.showRouteAlternatives(r.data, selectedIndex = 0)   // the selected route is bold, the others dimmed

    map.setEventListener(object : MapEventListener {
        override fun onMapTap(point: LatLng) {
            map.queryRouteAlternativeAt(point) { index ->
                index?.let {
                    map.selectRouteAlternative(it)
                    showSummary(r.data[it])
                }
            }
        }
    })
}

map.clearRouteAlternatives()   // clear when leaving the screen

val tracker = LocationTracker.create(context) { here ->
    scope.launch { drawRoute(map, from = here, to = destination) }
}
tracker.start()   // remember tracker.stop() in onDestroy

class NavSession(
    private val map: OtsMapView,
    private val route: RouteResult,
    private val carBitmap: Bitmap,
) {
    private val total = route.distanceMeters

    fun start() {
        map.setStyle(MapStyle.NAVIGATION_DAY) {
            map.showNavRoute(route.geometry, zoom = 17.0, tilt = 50.0)
            map.setVehicleAvatar(
                bitmap = carBitmap,
                position = route.geometry.first(),
                bearingDegrees = 0.0,
            )
        }
    }

    // call this on every new GPS fix
    fun onFix(position: LatLng, bearingDeg: Double, travelledMeters: Double) {
        map.updateNavProgress(
            position = position,
            bearingDeg = bearingDeg,
            fractionTraveled = (travelledMeters / total).coerceIn(0.0, 1.0),
            durationMs = 1000,   // = your update cadence; the SDK interpolates smoothly across it
        )
    }

    fun stop() {
        map.clearNavRoute()
        map.clearVehicleAvatar()
    }
}

val session = NavSession(map, route, carBitmap).also { it.start() }

val tracker = LocationTracker.create(
    context = this,
    minTimeMs = 1000,          // navigation needs a tighter cadence than the default
    minDistanceMeters = 2f,
) { fix ->
    session.onFix(fix, bearingDeg = lastBearing, travelledMeters = travelled)
}
tracker.start()

// when the session ends
tracker.stop(); session.stop()

@Composable
fun MyLocationButton(map: OtsMapView) {
    var following by remember { mutableStateOf(false) }

    val permission = rememberLauncherForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { granted ->
        if (granted) { map.enableMyLocation(follow = true); following = true }
    }

    FloatingActionButton(onClick = {
        if (hasLocationPermission()) {
            following = !following
            if (following) map.enableMyLocation(follow = true) else map.setFollowMode(false)
        } else {
            permission.launch(Manifest.permission.ACCESS_FINE_LOCATION)
        }
    }) {
        Icon(painterResource(R.drawable.ic_my_location), contentDescription = "My location")
    }
}

private fun Context.hasLocationPermission() =
    ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) ==
        PackageManager.PERMISSION_GRANTED

map.setFollowMode(false)    // keep the puck, stop the camera follow
map.disableMyLocation()   // fully off — call this when leaving the map screen

val tracker = LocationTracker.create(context) { latLng ->
    viewModel.onLocation(latLng)
}
tracker.start()   // emits the last-known fix immediately, then live updates
// …
tracker.stop()    // always stop to release the listener

dependencies {
    // Cách A — tích hợp trực tiếp file AAR vào thư mục libs của ứng dụng: phải khai báo thủ công các dependency bên dưới
    implementation(files("libs/maps-sdk-0.1.0.aar"))

    // MapLibre — SDK khai báo bằng cấu hình `api` nên bắt buộc có trên classpath
    implementation("org.maplibre.gl:android-sdk:11.13.5")

    // AndroidX core — ứng dụng tích hợp phải có sẵn
    implementation("androidx.core:core-ktx:1.10.1")
    implementation("androidx.appcompat:appcompat:1.7.0")

    // Networking và coroutine — SDK dùng nội bộ
    implementation("com.squareup.retrofit2:retrofit:2.9.0")
    implementation("com.squareup.retrofit2:converter-gson:2.9.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")

    // Cách B — Maven nội bộ: Gradle tự phân giải dependency, không cần khai báo thủ công
    // implementation("com.gtelmaps:maps-sdk:0.1.0")
}

<uses-permission android:name="android.permission.INTERNET" />
<!-- chỉ cần khi dùng My Location -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

GTELMAP_API_KEY=your_gtelmap_api_key
GTELMAP_WEATHER_APP_ID=your_openweather_app_id   # chỉ cần khi dùng Weather service

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        if (!MapSdk.isInitialized) {
            MapSdk.init(MapSdkConfig(
                apiKey = BuildConfig.GTELMAP_API_KEY,
                weatherAppId = BuildConfig.GTELMAP_WEATHER_APP_ID.ifBlank { null },
                enableHttpLogging = BuildConfig.DEBUG,
            ))
        }
    }
}

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.gtelmaps.sdk.core.OtsMapView
        android:id="@+id/mapView"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</FrameLayout>

class MapActivity : AppCompatActivity() {
    private lateinit var map: OtsMapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_map)
        map = findViewById(R.id.mapView)
        map.onCreate(savedInstanceState)
        map.setStyle(MapStyle.STREETS) {
            map.moveCamera(LatLng(21.0278, 105.8342), zoom = 12.0)
        }
    }

    // bắt buộc chuyển tiếp đầy đủ lifecycle
    override fun onStart()   { super.onStart();   map.onStart() }
    override fun onResume()  { super.onResume();  map.onResume() }
    override fun onPause()   { map.onPause();   super.onPause() }
    override fun onStop()    { map.onStop();    super.onStop() }
    override fun onDestroy() { map.onDestroy(); super.onDestroy() }
    override fun onLowMemory() { super.onLowMemory(); map.onLowMemory() }
}

map.moveCamera(LatLng(10.7769, 106.7009), zoom = 14.0)   // nhảy tức thì, không animation

map.animateCamera(                                       // bay mượt, có xoay và nghiêng
    CameraPosition(LatLng(10.7769, 106.7009), zoom = 15.0, bearing = 30.0, tilt = 45.0),
    durationMs = 800,
)

map.fitBounds(LatLngBounds(LatLng(10.76, 106.69), LatLng(10.79, 106.71)))
map.fitToMarkers(paddingPx = 80)                       // căn chỉnh camera bao trọn toàn bộ marker

private val geo = GeocodingClient.create()

map.setEventListener(object : MapEventListener {
    override fun onMapTap(point: LatLng) {
        lifecycleScope.launch {
            val r = geo.reverseGeocode(point, size = 1, zoom = 18)
            val place = (r as? Resource.Success)?.data?.firstOrNull() ?: return@launch
            if (place.layer != "poi") return@launch   // địa chỉ đường, không phải POI
            showPoiSheet(place)
        }
    }
})

private suspend fun showPoiSheet(place: Place) {
    place.location?.let { map.addMarker(MarkerOptions(position = it, title = place.name)) }

    val id = place.id ?: return
    val detail = (geo.placeDetail(listOf(id)) as? Resource.Success)?.data?.firstOrNull() ?: place

    sheet.render(
        name     = detail.name,
        address  = detail.address,
        category = detail.category ?: detail.primaryType,
        phone    = detail.phone,
        website  = detail.website,
    )
    detail.viewport?.let { map.fitBounds(it) }   // khung nhìn khuyến nghị của địa điểm
}

val r = geo.nearby(location = center, types = "restaurant,cafe", radius = 1500, size = 20)
if (r is Resource.Success) {
    map.setMarkers(r.data.mapNotNull { p ->
        p.location?.let { MarkerOptions(position = it, title = p.name, snippet = p.address) }
    })
    map.fitToMarkers()
}

map.setLayersVisibilityByIdContains("poi", visible = false)   // -> danh sách id layer đã tác động
map.currentStyleLayerIds()                                    // liệt kê layer thực có trong style

val nav = NavigationClient.create()
val r = nav.route(
    waypoints = listOf(LatLng(21.0278, 105.8342), LatLng(21.0368, 105.8500)),
    profile = "car",   // "car" | "bike" | "foot"
)
if (r is Resource.Success) {
    map.showRoute(r.data)
    println("Dài ${r.data.distanceMeters} m, khoảng ${r.data.durationSeconds} s")
}
map.clearRoute()

val r = nav.alternativeRoutes(origin, destination)
if (r is Resource.Success) map.showRouteAlternatives(r.data, selectedIndex = 0)

// chạm để chọn tuyến khác
map.queryRouteAlternativeAt(point) { i -> i?.let { map.selectRouteAlternative(it) } }

map.showNavRoute(route.geometry, zoom = 17.0, tilt = 50.0)
map.setVehicleAvatar(carBitmap, position = route.geometry.first(), bearingDegrees = 0.0)

// mỗi lần có tọa độ mới — SDK tự nội suy vị trí, hướng, camera và điểm mờ
map.updateNavProgress(position = cur, bearingDeg = brg, fractionTraveled = 0.35, durationMs = 1000)
map.clearNavRoute()

val r = AdminUnitClient.create().provinceBoundary("01")
(r as? Resource.Success)?.data?.boundaryGeoJson?.let { map.showAdminBoundary(it) }
map.clearAdminBoundary()

map.setEventListener(object : MapEventListener {
    override fun onMapTap(point: LatLng) { }
    override fun onMapLongPress(point: LatLng) { }
    override fun onMarkerClick(marker: MarkerOptions) { }
    override fun onCameraIdle(center: LatLng, zoom: Double) { }
})

map.enableMyLocation(follow = true)   // hiển thị location puck và cho chế độ theo dõi vị trí người dùng (Follow Mode)
map.setFollowMode(false)              // ngừng bám theo nhưng vẫn giữ location puck
map.disableMyLocation()

val tracker = LocationTracker.create(context) { latLng -> /* có tọa độ mới */ }
tracker.start()   // phát ngay tọa độ gần nhất, sau đó cập nhật liên tục
// …
tracker.stop()    // luôn gọi stop để giải phóng listener

val geo = GeocodingClient.create()
val r = geo.autocomplete(
    text = "cà phê",
    focus = LatLng(21.0278, 105.8342),   // ưu tiên kết quả quanh điểm này
    layers = listOf(PlaceLayer.POI),
    size = 8,
)
if (r is Resource.Success) r.data.forEach { println("${it.name} — ${it.address}") }

// tọa độ → địa chỉ
val addr = (geo.reverseGeocode(LatLng(21.0278, 105.8342)) as? Resource.Success)
    ?.data?.firstOrNull()?.address

// POI lân cận — dữ liệu đầy đủ: phone, website, distanceMeters, viewport…
geo.nearby(location = LatLng(21.0278, 105.8342), types = "restaurant,cafe", radius = 1500)

val nav = NavigationClient.create()

// tuyến cơ bản, từ 2 waypoint trở lên
nav.route(waypoints, profile = "car", overview = "full", steps = true)

// tuyến thay thế, đúng 2 waypoint
nav.alternativeRoutes(origin, destination)

// JSON OSRM nguyên bản, dùng để nạp vào engine turn-by-turn riêng
nav.rawRoute(waypoints, profile = "car")

when (val r = geo.reverseGeocode(point)) {
    is Resource.Success -> use(r.data)
    is Resource.Error   -> showError(r.message, r.code)
    Resource.Loading    -> Unit
}

// hoặc viết gọn hơn
geo.reverseGeocode(point)
    .onSuccess { places -> /* … */ }
    .onError   { err -> Log.e("Map", err.message) }

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent { MapScreen() }
    }
}

@Composable
fun MapScreen() {
    val map = rememberOtsMapView()
    AndroidView(factory = { map }, modifier = Modifier.fillMaxSize()) {
        it.setStyle(MapStyle.STREETS) {
            // đặt camera sau khi style nạp xong để tránh giật khung hình đầu
            it.moveCamera(LatLng(21.0278, 105.8342), zoom = 12.0)
        }
    }
}

lifecycleScope.launch {
    when (val r = MapsClient.create().listStyles()) {
        is Resource.Success -> r.data.forEach { println("${it.name} → ${it.id}") }
        is Resource.Error   -> toast(r.message)
        else -> Unit
    }
}

// nạp theo style id nguyên bản, kể cả style chưa có trong enum MapStyle
map.setStyleUrl(MapsClient.create().styleJsonUrl("gtelmaps-dark-vms-v1"))

class SearchViewModel : ViewModel() {

    private val geo = GeocodingClient.create()
    private val query = MutableStateFlow("")
    var focus: LatLng? = null          // tâm camera hiện tại

    val suggestions: StateFlow<List<Place>> = query
        .debounce(250)
        .map { it.trim() }
        .distinctUntilChanged()
        .flatMapLatest { text ->
            if (text.length < 2) flowOf(emptyList())
            else flow {
                val r = geo.autocomplete(
                    text = text,
                    focus = focus,                    // ưu tiên kết quả ở gần vị trí này
                    layers = listOf(PlaceLayer.POI, PlaceLayer.ADDRESS),
                    size = 8,
                )
                emit(if (r is Resource.Success) r.data else emptyList())
            }
        }
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), emptyList())

    fun onQueryChange(text: String) { query.value = text }
}

@Composable
fun SearchBar(vm: SearchViewModel, map: OtsMapView) {
    var text by remember { mutableStateOf("") }
    val items by vm.suggestions.collectAsStateWithLifecycle()

    Column {
        OutlinedTextField(
            value = text,
            onValueChange = { text = it; vm.onQueryChange(it) },
            placeholder = { Text("Tìm địa điểm…") },
            singleLine = true,
            modifier = Modifier.fillMaxWidth(),
        )
        LazyColumn {
            items(items) { place ->
                ListItem(
                    headlineContent = { Text(place.name) },
                    supportingContent = { place.address?.let { Text(it) } },
                    modifier = Modifier.clickable {
                        place.location?.let { map.moveCamera(it, zoom = 16.0) }
                        map.setMarkers(listOf(MarkerOptions(place.location!!, title = place.name)))
                        text = place.name
                    },
                )
            }
        }
    }
}

class DropPinController(
    private val map: OtsMapView,
    private val scope: CoroutineScope,
    private val onAddress: (LatLng, String) -> Unit,
) {
    private val geo = GeocodingClient.create()
    private var job: Job? = null

    fun attach() {
        map.setEventListener(object : MapEventListener {
            override fun onMapLongPress(point: LatLng) {
                map.setMarkers(listOf(MarkerOptions(point, title = "Đang tra địa chỉ…")))
                job?.cancel()
                job = scope.launch {
                    when (val r = geo.reverseGeocode(point)) {
                        is Resource.Success -> {
                            val place = r.data.firstOrNull()
                            val label = place?.address ?: place?.name ?: "Không rõ địa chỉ"
                            map.setMarkers(listOf(MarkerOptions(point, title = label)))
                            onAddress(point, label)
                        }
                        is Resource.Error -> onAddress(point, "Lỗi: ${r.message}")
                        else -> Unit
                    }
                }
            }
        })
    }
}

val map = rememberOtsMapView()
val scope = rememberCoroutineScope()
var address by remember { mutableStateOf<String?>(null) }

LaunchedEffect(map) {
    DropPinController(map, scope) { _, label -> address = label }.attach()
}
address?.let { Text(it, style = MaterialTheme.typography.bodyMedium) }

private val nav = NavigationClient.create()

suspend fun drawRoute(map: OtsMapView, from: LatLng, to: LatLng) {
    when (val r = nav.route(waypoints = listOf(from, to), profile = "car", steps = true)) {
        is Resource.Success -> {
            val route = r.data
            map.showRoute(route)
            map.fitBounds(route.geometry.bounds(), paddingPx = 72)
            println("%.1f km · %d phút".format(route.distanceMeters / 1000, (route.durationSeconds / 60).toInt()))
            route.steps.forEach { println("${it.maneuverType} ${it.modifier.orEmpty()} → ${it.roadName}") }
        }
        is Resource.Error -> toast(r.message)
        else -> Unit
    }
}

val r = nav.alternativeRoutes(origin = from, destination = to, profile = "car")
if (r is Resource.Success) {
    map.showRouteAlternatives(r.data, selectedIndex = 0)   // tuyến đang chọn vẽ đậm, các tuyến còn lại vẽ mờ

    map.setEventListener(object : MapEventListener {
        override fun onMapTap(point: LatLng) {
            map.queryRouteAlternativeAt(point) { index ->
                index?.let {
                    map.selectRouteAlternative(it)
                    showSummary(r.data[it])
                }
            }
        }
    })
}

map.clearRouteAlternatives()   // dọn dẹp khi rời màn hình

val tracker = LocationTracker.create(context) { here ->
    scope.launch { drawRoute(map, from = here, to = destination) }
}
tracker.start()   // nhớ gọi tracker.stop() trong onDestroy

class NavSession(
    private val map: OtsMapView,
    private val route: RouteResult,
    private val carBitmap: Bitmap,
) {
    private val total = route.distanceMeters

    fun start() {
        map.setStyle(MapStyle.NAVIGATION_DAY) {
            map.showNavRoute(route.geometry, zoom = 17.0, tilt = 50.0)
            map.setVehicleAvatar(
                bitmap = carBitmap,
                position = route.geometry.first(),
                bearingDegrees = 0.0,
            )
        }
    }

    // gọi mỗi khi có tọa độ GPS mới
    fun onFix(position: LatLng, bearingDeg: Double, travelledMeters: Double) {
        map.updateNavProgress(
            position = position,
            bearingDeg = bearingDeg,
            fractionTraveled = (travelledMeters / total).coerceIn(0.0, 1.0),
            durationMs = 1000,   // nhịp cập nhật; SDK nội suy mượt trong khoảng thời gian này
        )
    }

    fun stop() {
        map.clearNavRoute()
        map.clearVehicleAvatar()
    }
}

val session = NavSession(map, route, carBitmap).also { it.start() }

val tracker = LocationTracker.create(
    context = this,
    minTimeMs = 1000,          // dẫn đường cần nhịp cập nhật dày hơn mặc định
    minDistanceMeters = 2f,
) { fix ->
    session.onFix(fix, bearingDeg = lastBearing, travelledMeters = travelled)
}
tracker.start()

// khi kết thúc phiên
tracker.stop(); session.stop()

@Composable
fun MyLocationButton(map: OtsMapView) {
    var following by remember { mutableStateOf(false) }

    val permission = rememberLauncherForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { granted ->
        if (granted) { map.enableMyLocation(follow = true); following = true }
    }

    FloatingActionButton(onClick = {
        if (hasLocationPermission()) {
            following = !following
            if (following) map.enableMyLocation(follow = true) else map.setFollowMode(false)
        } else {
            permission.launch(Manifest.permission.ACCESS_FINE_LOCATION)
        }
    }) {
        Icon(painterResource(R.drawable.ic_my_location), contentDescription = "Vị trí của tôi")
    }
}

private fun Context.hasLocationPermission() =
    ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) ==
        PackageManager.PERMISSION_GRANTED

map.setFollowMode(false)    // vẫn giữ location puck, chỉ tắt chế độ bám theo
map.disableMyLocation()   // tắt hẳn — gọi khi rời màn hình bản đồ

val tracker = LocationTracker.create(context) { latLng ->
    viewModel.onLocation(latLng)
}
tracker.start()   // phát ngay tọa độ gần nhất, sau đó cập nhật liên tục
// …
tracker.stop()    // luôn gọi stop để giải phóng listener