@baeckerherz/expo-mapbox-navigation 0.1.0

package/README.md

@@ -0,0 +1,176 @@
+# @baeckerherz/expo-mapbox-navigation
+
+> **WARNING: This is a prototype and actively under development.** APIs may change without notice. Not recommended for production use yet. Contributions and feedback are welcome.
+
+Expo module wrapping [Mapbox Navigation SDK v3](https://docs.mapbox.com/ios/navigation/guides/) for iOS and Android. A clean, maintainable alternative to existing community wrappers.
+
+## Why this exists
+
+Existing React Native / Expo wrappers for Mapbox Navigation have significant issues:
+
+- **@badatgil/expo-mapbox-navigation**: Bundles vendored `.xcframework` files for iOS (fragile, requires manual rebuild for every Mapbox SDK update). Android assembles the navigation UI from ~30 individual components in ~1100 lines of Kotlin instead of using Mapbox's drop-in view.
+- **@homee/react-native-mapbox-navigation**: Abandoned (no activity since 2022), locked to Nav SDK v2.1.1, no Expo support, crashes on Android 13+.
+
+## Architecture
+
+### iOS: SPM via Config Plugin (not vendored xcframeworks)
+
+Mapbox Navigation SDK v3 for iOS dropped CocoaPods and only supports Swift Package Manager. Since Expo uses CocoaPods, we use an **Expo config plugin** that injects SPM package references into the Xcode project's `.pbxproj` at prebuild time. Version bumps are a single string change -- no manual xcframework rebuilding.
+
+### Android: Drop-in NavigationView
+
+Android Nav SDK v3 provides a `NavigationView` drop-in component. We wrap it directly instead of rebuilding the UI from scratch.
+
+### Both platforms: Expo Module API
+
+Uses `expo-modules-core` for native bridging, giving us:
+- Fabric / New Architecture compatibility
+- Type-safe props and events in Swift/Kotlin
+- Clean `EventDispatcher` pattern
+- Works in Expo and bare RN projects
+
+## API
+
+```tsx
+import { MapboxNavigation } from '@baeckerherz/expo-mapbox-navigation';
+
+<MapboxNavigation
+  coordinates={[
+    { latitude: 47.2692, longitude: 11.4041 },
+    { latitude: 48.2082, longitude: 16.3738 },
+  ]}
+  locale="de"
+  onRouteProgressChanged={(e) => {
+    console.log(e.nativeEvent.distanceRemaining);
+  }}
+  onCancelNavigation={() => navigation.goBack()}
+  onFinalDestinationArrival={() => console.log('Arrived!')}
+  style={{ flex: 1 }}
+/>
+```
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `coordinates` | `Array<{ latitude, longitude }>` | Route waypoints (min 2). First = origin, last = destination. |
+| `waypointIndices` | `number[]` | Which coordinates are full waypoints vs. via-points. |
+| `locale` | `string` | Language for voice guidance and UI. Default: device locale. |
+| `routeProfile` | `string` | Routing profile. Default: `"mapbox/driving-traffic"`. |
+| `mute` | `boolean` | Mute voice guidance. |
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onRouteProgressChanged` | `{ distanceRemaining, durationRemaining, distanceTraveled, fractionTraveled }` | Fires as the user progresses along the route. |
+| `onCancelNavigation` | — | User tapped cancel / back. |
+| `onWaypointArrival` | `{ waypointIndex }` | Arrived at an intermediate waypoint. |
+| `onFinalDestinationArrival` | — | Arrived at the final destination. |
+| `onRouteChanged` | — | Route was recalculated (reroute). |
+| `onUserOffRoute` | — | User went off the planned route. |
+| `onError` | `{ message }` | Navigation error occurred. |
+
+## Installation (for consumers)
+
+```bash
+npx expo install @baeckerherz/expo-mapbox-navigation
+```
+
+Add the plugin to `app.config.ts`:
+
+```ts
+plugins: [
+  ["@baeckerherz/expo-mapbox-navigation/plugin", {
+    mapboxAccessToken: "pk.eyJ1...",
+    mapboxSecretToken: "sk.eyJ1...",  // for SPM download auth
+    navigationSdkVersion: "3.5.0",
+  }],
+]
+```
+
+Rebuild native:
+
+```bash
+npx expo prebuild --clean
+npx expo run:ios
+```
+
+## Development
+
+```bash
+cd @baeckerherz/expo-mapbox-navigation
+yarn install
+cd example && npx expo run:ios
+```
+
+## Project Structure
+
+```
+src/            TypeScript API (component, types, exports)
+ios/            Swift native module + podspec
+android/        Kotlin native module + build.gradle
+plugin/         Expo config plugins (SPM injection, Gradle setup)
+example/        Test app
+```
+
+## Prerequisites
+
+1. A [Mapbox account](https://account.mapbox.com/) with Navigation SDK access
+2. A public access token (`pk.xxx`) and a secret/download token (`sk.xxx`)
+3. For iOS: `~/.netrc` must contain Mapbox credentials for SPM package resolution:
+
+```
+machine api.mapbox.com
+  login mapbox
+  password sk.eyJ1...YOUR_SECRET_TOKEN
+```
+
+## How to test the example app
+
+```bash
+cd @baeckerherz/expo-mapbox-navigation/example
+yarn install
+npx expo prebuild --clean
+npx expo run:ios --device
+```
+
+The example app navigates from your current location to Innsbruck Hauptbahnhof with German voice guidance.
+
+## Publishing to npm
+
+```bash
+npm login
+npm publish --access public
+```
+
+Consumers install with:
+
+```bash
+npx expo install @baeckerherz/expo-mapbox-navigation
+```
+
+## Key differences from existing wrappers
+
+| | This module | @badatgil/expo-mapbox-navigation | @homee/react-native-mapbox-navigation |
+|---|---|---|---|
+| iOS SDK integration | SPM via config plugin (clean version bumps) | Vendored .xcframeworks (manual rebuild per update) | CocoaPods pinned to Nav SDK v2 |
+| Android approach | Drop-in NavigationView | Custom UI from ~30 components (~1100 LOC) | Custom UI (~500 LOC) |
+| Nav SDK version | v3 (current) | v3 | v2 (legacy) |
+| Expo Module API | Yes (Fabric-ready) | Yes | No (legacy bridge) |
+| Multi-waypoint | Yes | Yes | No (origin + destination only) |
+| Maintenance | Active | Semi-active | Abandoned |
+
+## Status
+
+**Prototype** — not production-ready. This is a proof of concept to validate:
+
+1. SPM injection via config plugin works reliably with Xcode + CocoaPods
+2. Drop-in NavigationView/NavigationViewController integration is sufficient
+3. Event bridging covers the required use cases
+
+### Known risks
+
+- **SPM + CocoaPods coexistence**: Xcode may have trouble resolving both dependency managers. If this fails, fallback is to vendor `.xcframework` files (Approach A from the plan).
+- **Android NavigationView completeness**: The drop-in `NavigationView` in Android Nav SDK v3 may require additional configuration for full feature parity with iOS.
+- **Mapbox licensing**: The Navigation SDK requires a commercial Mapbox license for production use. This wrapper does not change that requirement.

package/android/build.gradle

@@ -0,0 +1,74 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+apply plugin: 'maven-publish'
+
+group = 'expo.modules.mapboxnavigation'
+version = '0.1.0'
+
+def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+if (expoModulesCorePlugin.exists()) {
+  apply from: expoModulesCorePlugin
+  applyKotlinExpoModulesCorePlugin()
+}
+
+buildscript {
+  def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+  if (expoModulesCorePlugin.exists()) {
+    apply from: expoModulesCorePlugin
+    applyKotlinExpoModulesCorePlugin()
+  }
+}
+
+android {
+  namespace "expo.modules.mapboxnavigation"
+
+  compileSdkVersion safeExtGet("compileSdkVersion", 34)
+
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 23)
+    targetSdkVersion safeExtGet("targetSdkVersion", 34)
+  }
+
+  publishing {
+    singleVariant("release") {
+      withSourcesJar()
+    }
+  }
+
+  lintOptions {
+    abortOnError false
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = JavaVersion.VERSION_17.majorVersion
+  }
+}
+
+repositories {
+  mavenCentral()
+  maven {
+    url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
+    authentication {
+      basic(BasicAuthentication)
+    }
+    credentials {
+      username = "mapbox"
+      password = project.findProperty('MAPBOX_DOWNLOADS_TOKEN') ?: System.getenv('MAPBOX_DOWNLOADS_TOKEN') ?: ""
+    }
+  }
+}
+
+dependencies {
+  implementation project(':expo-modules-core')
+  implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:${getKotlinVersion()}"
+
+  // Mapbox Navigation SDK v3 - drop-in UI
+  implementation "com.mapbox.navigationcore:android:3.5.0"
+  implementation "com.mapbox.navigationcore:dropin:3.5.0"
+  implementation "com.mapbox.navigationcore:ui-maps:3.5.0"
+}

package/android/src/main/java/expo/modules/mapboxnavigation/ExpoMapboxNavigationModule.kt

@@ -0,0 +1,66 @@
+package expo.modules.mapboxnavigation
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class ExpoMapboxNavigationModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("ExpoMapboxNavigation")
+
+    View(ExpoMapboxNavigationView::class) {
+      Events(
+        "onRouteProgressChanged",
+        "onCancelNavigation",
+        "onWaypointArrival",
+        "onFinalDestinationArrival",
+        "onRouteChanged",
+        "onUserOffRoute",
+        "onError"
+      )
+
+      Prop("coordinates") { view: ExpoMapboxNavigationView, coordinates: List<Map<String, Double>> ->
+        view.setCoordinates(coordinates)
+      }
+
+      Prop("waypointIndices") { view: ExpoMapboxNavigationView, indices: List<Int> ->
+        view.waypointIndices = indices
+      }
+
+      Prop("locale") { view: ExpoMapboxNavigationView, locale: String ->
+        view.navigationLocale = locale
+      }
+
+      Prop("routeProfile") { view: ExpoMapboxNavigationView, profile: String ->
+        view.routeProfile = profile
+      }
+
+      Prop("mute") { view: ExpoMapboxNavigationView, mute: Boolean ->
+        view.isMuted = mute
+      }
+
+      Prop("mapStyle") { view: ExpoMapboxNavigationView, style: String ->
+        view.mapStyleURL = style
+      }
+
+      Prop("themeMode") { view: ExpoMapboxNavigationView, mode: String ->
+        view.themeMode = mode
+      }
+
+      Prop("accentColor") { view: ExpoMapboxNavigationView, color: String ->
+        view.accentColorHex = color
+      }
+
+      Prop("routeColor") { view: ExpoMapboxNavigationView, color: String ->
+        view.routeColorHex = color
+      }
+
+      Prop("bannerBackgroundColor") { view: ExpoMapboxNavigationView, color: String ->
+        view.bannerBackgroundColorHex = color
+      }
+
+      Prop("bannerTextColor") { view: ExpoMapboxNavigationView, color: String ->
+        view.bannerTextColorHex = color
+      }
+    }
+  }
+}

package/android/src/main/java/expo/modules/mapboxnavigation/ExpoMapboxNavigationView.kt

@@ -0,0 +1,164 @@
+package expo.modules.mapboxnavigation
+
+import android.content.Context
+import android.widget.FrameLayout
+import expo.modules.kotlin.AppContext
+import expo.modules.kotlin.viewevent.EventDispatcher
+import expo.modules.kotlin.views.ExpoView
+import com.mapbox.geojson.Point
+import com.mapbox.navigation.base.route.NavigationRoute
+import com.mapbox.navigation.core.MapboxNavigation
+import com.mapbox.navigation.core.lifecycle.MapboxNavigationApp
+import com.mapbox.navigation.core.trip.session.RouteProgressObserver
+import com.mapbox.navigation.core.trip.session.OffRouteObserver
+import com.mapbox.navigation.core.directions.session.RoutesObserver
+import com.mapbox.navigation.dropin.NavigationView
+import com.mapbox.api.directions.v5.DirectionsCriteria
+import com.mapbox.api.directions.v5.models.RouteOptions
+
+class ExpoMapboxNavigationView(
+  context: Context,
+  appContext: AppContext
+) : ExpoView(context, appContext) {
+
+  private val onRouteProgressChanged by EventDispatcher()
+  private val onCancelNavigation by EventDispatcher()
+  private val onWaypointArrival by EventDispatcher()
+  private val onFinalDestinationArrival by EventDispatcher()
+  private val onRouteChanged by EventDispatcher()
+  private val onUserOffRoute by EventDispatcher()
+  private val onError by EventDispatcher()
+
+  private var coordinates: List<Point> = emptyList()
+  var waypointIndices: List<Int>? = null
+  var navigationLocale: String? = null
+  var routeProfile: String? = null
+  var isMuted: Boolean = false
+  var mapStyleURL: String? = null
+  var themeMode: String? = null
+  var accentColorHex: String? = null
+  var routeColorHex: String? = null
+  var bannerBackgroundColorHex: String? = null
+  var bannerTextColorHex: String? = null
+
+  private var navigationView: NavigationView? = null
+  private var hasStartedNavigation = false
+
+  fun setCoordinates(raw: List<Map<String, Double>>) {
+    coordinates = raw.mapNotNull { map ->
+      val lat = map["latitude"] ?: return@mapNotNull null
+      val lng = map["longitude"] ?: return@mapNotNull null
+      Point.fromLngLat(lng, lat)
+    }
+    startNavigationIfReady()
+  }
+
+  private fun startNavigationIfReady() {
+    if (coordinates.size < 2 || hasStartedNavigation) return
+    hasStartedNavigation = true
+
+    try {
+      val navView = NavigationView(context)
+      navView.layoutParams = FrameLayout.LayoutParams(
+        FrameLayout.LayoutParams.MATCH_PARENT,
+        FrameLayout.LayoutParams.MATCH_PARENT
+      )
+      addView(navView)
+      navigationView = navView
+
+      val profile = routeProfile ?: DirectionsCriteria.PROFILE_DRIVING_TRAFFIC
+      val routeOptions = RouteOptions.builder()
+        .coordinatesList(coordinates)
+        .profile(profile)
+        .alternatives(true)
+        .continueStraight(true)
+        .overview(DirectionsCriteria.OVERVIEW_FULL)
+        .steps(true)
+        .voiceInstructions(true)
+        .bannerInstructions(true)
+        .apply {
+          waypointIndices?.let { indices ->
+            waypointIndices(indices.joinToString(separator = ";"))
+          }
+          navigationLocale?.let { locale ->
+            language(locale)
+          }
+        }
+        .build()
+
+      MapboxNavigationApp.current()?.let { navigation ->
+        registerObservers(navigation)
+
+        navigation.requestRoutes(routeOptions, object :
+          com.mapbox.navigation.core.directions.session.RoutesRequestCallback {
+          override fun onRoutesReady(routes: List<NavigationRoute>) {
+            if (routes.isNotEmpty()) {
+              navigation.setNavigationRoutes(routes)
+            } else {
+              onError(mapOf("message" to "No routes found"))
+            }
+          }
+
+          override fun onRoutesRequestFailure(
+            throwable: Throwable,
+            routeOptions: RouteOptions
+          ) {
+            onError(mapOf("message" to "Route request failed: ${throwable.message}"))
+          }
+
+          override fun onRoutesRequestCanceled(routeOptions: RouteOptions) {
+            onError(mapOf("message" to "Route request cancelled"))
+          }
+        })
+      } ?: run {
+        onError(mapOf("message" to "MapboxNavigation not initialized"))
+      }
+    } catch (e: Exception) {
+      onError(mapOf("message" to "Navigation setup failed: ${e.message}"))
+    }
+  }
+
+  private fun registerObservers(navigation: MapboxNavigation) {
+    navigation.registerRouteProgressObserver(RouteProgressObserver { routeProgress ->
+      onRouteProgressChanged(mapOf(
+        "distanceRemaining" to routeProgress.distanceRemaining,
+        "durationRemaining" to routeProgress.durationRemaining,
+        "distanceTraveled" to routeProgress.distanceTraveled,
+        "fractionTraveled" to routeProgress.fractionTraveled
+      ))
+
+      val currentLegProgress = routeProgress.currentLegProgress
+      if (currentLegProgress != null) {
+        val distanceToEnd = currentLegProgress.distanceRemaining
+        if (distanceToEnd <= 30.0) {
+          val legIndex = routeProgress.currentLegProgress?.legIndex ?: 0
+          val totalLegs = routeProgress.route.legs()?.size ?: 1
+
+          if (legIndex == totalLegs - 1) {
+            onFinalDestinationArrival(emptyMap<String, Any>())
+          } else {
+            onWaypointArrival(mapOf("waypointIndex" to legIndex))
+          }
+        }
+      }
+    })
+
+    navigation.registerOffRouteObserver(OffRouteObserver { isOffRoute ->
+      if (isOffRoute) {
+        onUserOffRoute(emptyMap<String, Any>())
+      }
+    })
+
+    navigation.registerRoutesObserver(RoutesObserver { result ->
+      if (result.navigationRoutes.isNotEmpty()) {
+        onRouteChanged(emptyMap<String, Any>())
+      }
+    })
+  }
+
+  override fun onDetachedFromWindow() {
+    super.onDetachedFromWindow()
+    navigationView?.let { removeView(it) }
+    navigationView = null
+  }
+}

package/expo-module.config.json

@@ -0,0 +1,9 @@
+{
+  "platforms": ["ios", "android"],
+  "ios": {
+    "modules": ["ExpoMapboxNavigationModule"]
+  },
+  "android": {
+    "modules": ["expo.modules.mapboxnavigation.ExpoMapboxNavigationModule"]
+  }
+}

package/ios/ExpoMapboxNavigation.podspec

@@ -0,0 +1,26 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'ExpoMapboxNavigation'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.description    = package['description']
+  s.license        = package['license']
+  s.author         = 'Bäckerherz'
+  s.homepage       = 'https://github.com/baeckerherz/expo-mapbox-navigation'
+  s.platforms      = { ios: '15.0' }
+  s.source         = { git: '' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  s.source_files = '**/*.{h,m,mm,swift}'
+  s.exclude_files = 'Tests/'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'SWIFT_COMPILATION_MODE' => 'wholemodule',
+  }
+end

package/ios/ExpoMapboxNavigationModule.swift

@@ -0,0 +1,66 @@
+import ExpoModulesCore
+
+public class ExpoMapboxNavigationModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("ExpoMapboxNavigation")
+
+    View(ExpoMapboxNavigationView.self) {
+      Events(
+        "onRouteProgressChanged",
+        "onCancelNavigation",
+        "onWaypointArrival",
+        "onFinalDestinationArrival",
+        "onRouteChanged",
+        "onUserOffRoute",
+        "onError"
+      )
+
+      // Route
+      Prop("coordinates") { (view, coordinates: [[String: Double]]) in
+        view.setCoordinates(coordinates)
+      }
+
+      Prop("waypointIndices") { (view, indices: [Int]) in
+        view.waypointIndices = indices
+      }
+
+      Prop("routeProfile") { (view, profile: String) in
+        view.routeProfile = profile
+      }
+
+      // Localization
+      Prop("locale") { (view, locale: String) in
+        view.navigationLocale = locale
+      }
+
+      Prop("mute") { (view, mute: Bool) in
+        view.isMuted = mute
+      }
+
+      // Appearance
+      Prop("mapStyle") { (view, style: String) in
+        view.mapStyleURL = style
+      }
+
+      Prop("themeMode") { (view, mode: String) in
+        view.themeMode = mode
+      }
+
+      Prop("accentColor") { (view, color: String) in
+        view.accentColorHex = color
+      }
+
+      Prop("routeColor") { (view, color: String) in
+        view.routeColorHex = color
+      }
+
+      Prop("bannerBackgroundColor") { (view, color: String) in
+        view.bannerBackgroundColorHex = color
+      }
+
+      Prop("bannerTextColor") { (view, color: String) in
+        view.bannerTextColorHex = color
+      }
+    }
+  }
+}