[bindgen] Add Kotlin Flow and Cancelable Support for Signals. (#8699)

Fixes https://mapbox.atlassian.net/browse/CORESDK-3520

This PR adds Kotlin Flow support for signals while maintaining and
improving callback-based APIs with `Cancelable` return values for
lifecycle management. Both Java and Kotlin generators now support the
enhanced signal API.

## API Changes

### Kotlin - Dual API (Flow + Callback)

**Flow-based (new):**
```kotlin
// Collect signals as Flow
service.foo.collect {
    // Handle signal
}

// With parameters
service.bar.collect { barValue ->
    println("Received: $barValue")
}

// Tuple signals (multiple parameters)
service.experimentalSignal.collect { (test, ing) ->
    println("Received: $test, $ing")
}
```

**Callback-based (refined):**
```kotlin
val cancelable = service.subscribeFoo(object : FooCallback {
    override fun onFoo() {
        // Handle signal
    }
})
cancelable.cancel()  // Stop receiving signals
```

### Java - Callback API

**Callback-based (refined):**
```java
Cancelable cancelable = service.subscribeFoo(new SampleService.FooCallback() {
    @OverRide
    public void onFoo() {
        // Handle signal
    }
});
cancelable.cancel();  // Stop receiving signals
```

### Breaking Changes

**Method naming:**
- `setFooCallback()` → `subscribeFoo()` (returns `Cancelable`)
- `nativeSetFooCallback()` → `nativeSubscribeFoo()`

**Callback method naming fix:**
- `onOnIndoorUpdated()` → `onIndoorUpdated()` (fixed double-on prefix)

**Rationale:**
- "subscribe" correctly indicates multiple concurrent observers (vs
"set" implying single callback)
- Returns `Cancelable` for explicit lifecycle management
- Smart callback naming avoids double "on" prefix for signals starting
with "on"

## Implementation

### Core Components

**SignalPublisher.kt** (`src/support/java/src/main/kotlin/`)
- Bridges callback-based signals to Kotlin Flow
- Uses `callbackFlow` with automatic cleanup via `awaitClose`
- `.conflate()` strategy - keeps only latest value for state-based
signals
- Error handling during registration and cancellation

**Generator Updates:**

1. **kotlin.js** - Generate dual API:
   - Flow properties (e.g., `val foo: Flow<Unit>`)
   - Subscribe methods (e.g., `subscribeFoo()` returning `Cancelable`)
   - Uses `SignalPublisher.create()` to bridge callback to Flow

2. **java.js** - Generate callback API:
   - Subscribe methods (e.g., `subscribeFoo()` returning `Cancelable`)
   - Callback interfaces with smart naming

3. **jni.js** - JNI layer enhancements:
   - Native subscribe methods returning `Cancelable`
   - Callback handling with proper lifecycle management
   - Includes `<mapbox/common/cancelable.jni.hpp>`

4. **cpp_helpers.js** - Helper utilities:
   - `signalToCallbackMethodName()` - Smart "on" prefix handling
   - Avoids double prefix for signals starting with "on"

### Stub Infrastructure

**Purpose:** Allow bindgen feature tests to compile without depending on
full common SDK

**Java stubs:**
`src/support/mapbox/bindgen/java/stubs/com/mapbox/common/`
- `Cancelable.java` - Interface for lifecycle management
- `CancelableNative.java` - Native implementation wrapper

**JNI stubs:** `src/support/mapbox/bindgen/jni/stubs/mapbox/common/`
- `cancelable.hpp` - C++ interface
- `cancelable.jni.hpp` - JNI bridge header
- `cancelable.jni.cpp` - JNI marshaller implementation

**Path structure:** Production-compatible (`mapbox/common/`) so
generated code works with both stubs and production implementations

## Testing

### Kotlin Feature Tests
`make feature signals kotlin` - 1 scenario (1 passed), 14 steps (14
passed)

**Test coverage:**
- Test 1-8: Callback-based API (basic, multiple subscribers,
cancellation, re-subscription, threading)
- Test 9-13: Flow-based API (collection, parameters, tuples,
cancellation, multiple collectors)

### Java Feature Tests
`make feature signals java` - 1 scenario (1 passed), 14 steps (14
passed)

**Test coverage:**
- Test 1-8: Callback-based API (basic, multiple subscribers,
cancellation, re-subscription, threading, tuple signals)

### Performance Benchmarks
Fixed benchmark failures caused by `SignalPublisher.kt` requiring
`Cancelable` dependency
- Updated `benchmarks/performance/support.js` to copy stubs to support
module

### Android Integration Tests
Fixed build with centralized plugin version management
- Updated `test/android/settings.gradle.kts` with `pluginManagement`
- Support module uses `kotlin("jvm")` without version (inherited from
parent)
- Standalone build still works via
`src/support/java/settings.gradle.kts`

## Build Configuration Updates

### Support Module (`src/support/java/build.gradle.kts`)
```kotlin
// Added Kotlin stdlib and coroutines for Flow support
api("org.jetbrains.kotlin:kotlin-stdlib:1.7.20")
api("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4")

// Include stubs for compilation but exclude from JAR
sourceSets {
    main {
        java {
            srcDir("../mapbox/bindgen/java/stubs")
        }
    }
}

tasks.jar {
    exclude("com/mapbox/common/**")  // Don't publish stubs
}
```

### Feature Test CMakeLists.txt
```cmake
# Both Kotlin and Java signal tests now include stubs
target_include_directories(signals PRIVATE
    ${CMAKE_CURRENT_LIST_DIR}/../../../../src/support/mapbox/bindgen/jni/stubs
)

target_sources(signals PRIVATE
    ${CMAKE_CURRENT_LIST_DIR}/../../../../src/support/mapbox/bindgen/jni/stubs/mapbox/common/cancelable.jni.cpp
)
```

## Dependencies for Integration

Projects integrating this change need to add coroutine dependencies:

**build.gradle.kts:**
```kotlin
api("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4")  // For Android
```

**Common SDK:**
- Add `SignalPublisher.kt` to java/kotlin source directory

cc @mapbox/core-sdk

cc @mapbox/maps-android
cc @mapbox/gl-native

cc @mapbox/sdk-platform

cc @mapbox/nav-core-sdk

---------

Co-authored-by: Aleksei Sapitskii <[email protected]>
GitOrigin-RevId: 3be10f266514eb7118efa6fedea320fb34d88cd4

Author: 2 people

CHANGELOG.md

@@ -30,6 +30,9 @@ Mapbox welcomes participation and contributions from everyone.
 ## Dependencies
 * Update gl-native to [v11.19.0-beta.1](https://github.com/mapbox/mapbox-maps-android/releases/tag/v11.19.0-beta.1), common to [v24.19.0-beta.1](https://github.com/mapbox/mapbox-maps-android/releases/tag/v11.19.0-beta.1).
 
+# 11.19.0-rc.1
+## Features ✨ and improvements 🏁
+* Rename `IndoorManager.setOnIndoorUpdatedCallback` to `IndoorManager.subscribeOnIndoorUpdated` with returned Cancelable support. Add flow-based `val onIndoorUpdated: Flow<IndoorState>` API.
 
 # 11.18.0 January 15, 2026
 

plugin-indoorselector/src/main/java/com/mapbox/maps/plugin/indoorselector/IndoorSelectorPluginImpl.kt

@@ -5,6 +5,7 @@ import android.util.AttributeSet
 import android.view.View
 import android.widget.FrameLayout
 import androidx.annotation.RestrictTo
+import com.mapbox.common.Cancelable
 import com.mapbox.maps.IndoorFloor
 import com.mapbox.maps.IndoorManager
 import com.mapbox.maps.IndoorState
@@ -28,7 +29,7 @@ internal class IndoorSelectorPluginImpl(
 ) : IndoorSelectorPlugin, IndoorSelectorSettingsBase() {
 
   private lateinit var indoorSelectorView: IndoorSelectorView
-  private var indoorManager: IndoorManager? = null
+  private lateinit var indoorManager: IndoorManager
 
   override var internalSettings: IndoorSelectorSettings = IndoorSelectorSettings { }
 
@@ -40,16 +41,18 @@ internal class IndoorSelectorPluginImpl(
   private var selectedFloorId: String? = null
 
   private val onFloorSelectedListener = OnFloorSelectedListener { floorId ->
-    indoorManager?.selectFloor(floorId)
+    indoorManager.selectFloor(floorId)
   }
 
   private val onIndoorUpdatedCallback = object : IndoorManager.OnIndoorUpdatedCallback {
-    override fun onOnIndoorUpdated(indoorState: IndoorState) {
+    override fun onIndoorUpdated(indoorState: IndoorState) {
       if (!internalSettings.enabled) return
       updateFloors(indoorState.floors, indoorState.selectedFloorId)
     }
   }
 
+  private var cancelable: Cancelable? = null
+
   override fun applySettings() {
     indoorSelectorView.apply {
       isIndoorSelectorVisible = internalSettings.enabled
@@ -72,8 +75,10 @@ internal class IndoorSelectorPluginImpl(
       if (value == internalSettings.enabled) return
       internalSettings = internalSettings.toBuilder().setEnabled(value).build()
       if (value) {
+        cancelable = indoorManager.subscribeOnIndoorUpdated(onIndoorUpdatedCallback)
         addOnFloorSelectedListener(onFloorSelectedListener)
       } else {
+        cancelable?.cancel()
         removeOnFloorSelectedListener(onFloorSelectedListener)
       }
       updateIndoorVisibility()
@@ -113,6 +118,7 @@ internal class IndoorSelectorPluginImpl(
   override fun initialize() {
     applySettings()
     if (internalSettings.enabled) {
+      cancelable = indoorManager.subscribeOnIndoorUpdated(onIndoorUpdatedCallback)
       addOnFloorSelectedListener(onFloorSelectedListener)
     }
   }
@@ -122,19 +128,16 @@ internal class IndoorSelectorPluginImpl(
    */
   override fun cleanup() {
     floorSelectedListeners.clear()
+    cancelable?.cancel()
     currentFloors = emptyList()
     selectedFloorId = null
-    indoorManager = null
   }
 
   /**
    * Provides all map delegate instances.
    */
   override fun onDelegateProvider(delegateProvider: MapDelegateProvider) {
     this.indoorManager = delegateProvider.indoorManager
-    // There's no way to remove this callback at the moment
-    // To be fixed with Kotlin Flow implementation
-    delegateProvider.indoorManager.setOnIndoorUpdatedCallback(onIndoorUpdatedCallback)
   }
 
   /**