expo-arcgis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# expo-arcgis
+
+Native **ArcGIS Maps SDK** for React Native, as an [Expo module](https://docs.expo.dev/modules/overview/).
+It wraps the ArcGIS Maps SDK for **Kotlin** (Android) and **Swift** (iOS) and exposes a declarative,
+SDK-faithful component API to JS/TS — `<MapView>` / `<SceneView>` with layers, graphics, geometry,
+editing, query, analysis, geocoding, routing, geoprocessing, utility networks, offline, real-time and
+authentication.
+
+> **Status — early / pre-1.0.** The full surface below is implemented and **compile-verified** on both
+> platforms (TypeScript · Android `compileDebugKotlin` · iOS pod build). On-device **runtime** validation
+> (rendering, network calls, device sensors) should be done in your own app. The API may still change
+> before 1.0. Pulls ArcGIS Maps SDK **300.0.0**.
+
+## Features
+
+| Area | What's covered |
+|---|---|
+| **2D / 3D** | `<MapView>` + `<Map>`; `<SceneView>` + `<Scene>` (surface, camera, web scenes, light/shadows) |
+| **Layers** | Feature, Tile, MapImage, Vector-tile, Raster, WMS, WMTS, KML, Scene, IntegratedMesh, PointCloud, OGC 3D Tiles, WebTiled, OpenStreetMap, **WFS**, **OGC API Features**, **DynamicEntity** (stream) |
+| **Graphics** | `<GraphicsOverlay>` + `<Graphic>`, symbols (simple marker/line/fill, text, 3D scene symbol, picture-marker), renderers (simple / unique-value / class-breaks), labels, clustering |
+| **Geometry** | `geometryEngine` (buffer, project, distance, intersect, …), `coordinateFormatter`, codec for all geometry types |
+| **Query** | feature query / count / extent / statistics on a `<FeatureLayer>` ref; `identify` on a view ref |
+| **Editing** | add / update / delete features, `<GeometryEditor>` (tools), feature templates |
+| **Location** | device location, simulated location data source, `onLocationChange` |
+| **Geocoding** | `geocoder.geocode` / `reverseGeocode` / `suggest`, offline `.loc` locators |
+| **Routing** | `router.solveRoute` / directions, travel modes, point barriers, curb approach |
+| **Analysis (3D)** | `<AnalysisOverlay>` + `<Viewshed>` / `<LineOfSight>` / `<DistanceMeasurement>` |
+| **Geoprocessing** | `geoprocessor.execute` → `JobRef` (progress + cancel), typed parameters |
+| **Utility network** | `<UtilityNetwork>` load + trace, named configs, associations, `describeNetwork` |
+| **Offline** | `offline.*` generate offline map, preplanned areas, geodatabase, tile / vector-tile export, sync — all as a cancellable `JobRef`; mobile map / scene packages |
+| **Real-time** | `<DynamicEntityLayer>` (stream service), query, custom data source, stream filter |
+| **Auth** | API key, token (challenge handler), OAuth user sign-in, app credential |
+
+## Requirements
+
+ArcGIS Maps SDK 300.0 sets the floor for any app using this module:
+
+| | Minimum |
+|---|---|
+| iOS | **17.0**, built with **Xcode 26** |
+| Android | **API 28** (Android 9), compileSdk **36** |
+| Expo | SDK **54+** (New Architecture). Verified on Expo **56** / RN **0.82** / React **19** |
+| Auth | An [ArcGIS API key](https://developers.arcgis.com/documentation/security-and-authentication/api-key-authentication/) (or token / OAuth) |
+
+This is a native module — it does **not** run in Expo Go. Use a development build (`expo prebuild` + `run:ios`/`run:android`).
+
+## Install
+
+```sh
+npx expo install expo-arcgis
+```
+
+Add the config plugin to your app config. It wires the Esri Maven repository (Android), raises
+`minSdk` / `compileSdk` and the iOS deployment target, and (optionally) injects your API key.
+
+```js
+// app.config.js
+module.exports = {
+  expo: {
+    plugins: [
+      ['expo-arcgis', { apiKey: process.env.ARCGIS_API_KEY }],
+    ],
+  },
+};
+```
+
+Then regenerate the native projects:
+
+```sh
+npx expo prebuild --clean
+```
+
+### Config plugin options
+
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `apiKey` | `string` | – | Written to `strings.xml` (`arcgis_api_key`) / `Info.plist` (`ArcGISAPIKey`) and read at init. |
+| `androidMavenUrl` | `string` | Esri artifactory | Override the ArcGIS Maven repository. |
+| `androidMinSdkVersion` | `number` | `28` | Minimum Android SDK. |
+| `androidCompileSdkVersion` | `number` | `36` | Android compileSdk. |
+| `iosDeploymentTarget` | `string` | `17.0` | Minimum iOS deployment target. |
+| `locationWhenInUseUsageDescription` | `string` | – | Opt into location permissions for showing device position. |
+
+## Quick start
+
+The API is declarative and mirrors the ArcGIS SDK object model — a `<Map>` model inside a `<MapView>`
+host, wrapped in `<MapSettings>`:
+
+```tsx
+import { MapSettings, Map, MapView, FeatureLayer } from 'expo-arcgis';
+
+export function Screen() {
+  return (
+    <MapSettings config={{ apiKey: process.env.EXPO_PUBLIC_ARCGIS_API_KEY }}>
+      <Map
+        basemap="arcGISTopographic"
+        initialViewpoint={{ latitude: 34.027, longitude: -118.805, scale: 72_000 }}
+      >
+        <FeatureLayer url="https://services.arcgis.com/.../FeatureServer/0" />
+        <MapView
+          style={{ flex: 1 }}
+          onMapLoaded={() => console.log('loaded')}
+          onMapLoadError={(e) => console.warn(e.nativeEvent.message)}
+        />
+      </Map>
+    </MapSettings>
+  );
+}
+```
+
+3D works the same way with `<Scene>` + `<SceneView>`. Imperative namespaces don't need a view:
+
+```ts
+import { geometryEngine, geocoder } from 'expo-arcgis';
+
+const buffered = geometryEngine.buffer(point, 500, 'meters');
+const [hit] = await geocoder.geocode('Los Angeles');
+```
+
+## API overview
+
+- **Views & models** — `MapSettings`, `Map`, `Scene`, `MapView`, `SceneView`
+- **Layers** — `FeatureLayer`, `TileLayer`, `MapImageLayer`, `SceneLayer`, `VectorTileLayer`,
+  `IntegratedMeshLayer`, `PointCloudLayer`, `Ogc3DTilesLayer`, `WebTiledLayer`, `OpenStreetMapLayer`,
+  `WmsLayer`, `WmtsLayer`, `RasterLayer`, `KmlLayer`, `WfsLayer`, `OgcFeatureLayer`, `DynamicEntityLayer`
+- **Graphics & analysis** — `GraphicsOverlay`, `Graphic`, `AnalysisOverlay`, `Viewshed`, `LineOfSight`,
+  `DistanceMeasurement`, `GeometryEditor`, `UtilityNetwork`
+- **Namespaces** — `geometryEngine`, `coordinateFormatter`, `geocoder`, `router`, `geoprocessor`, `offline`
+- **Auth** — `setTokenCredential`, `signInWithOAuth`, `setAppCredential`, `signOut`
+- **Hooks** — `useMapSettings`, `useGeoModel`, `useGeoView`, `useGraphicsOverlay`
+
+You can also set the key imperatively: `import ExpoArcgis from 'expo-arcgis'; ExpoArcgis.setApiKey('KEY')`.
+
+## Example app
+
+```sh
+cd example
+npm install
+ARCGIS_API_KEY=your_key npx expo run:android   # or run:ios (needs Xcode 26)
+```
+
+## License
+
+MIT © krassavin. See [LICENSE](./LICENSE).

package/android/build.gradle

@@ -0,0 +1,39 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'expo.modules.arcgis'
+version = '0.1.0'
+
+// ArcGIS Maps SDK for Kotlin (300.0.0) is published to Esri's Maven repository.
+// The consuming app must expose this repository as well — the config plugin adds it to
+// the app's allprojects.repositories so dependency resolution succeeds during the app build.
+repositories {
+  maven {
+    url = uri('https://esri.jfrog.io/artifactory/arcgis')
+  }
+}
+
+android {
+  namespace "expo.modules.arcgis"
+  defaultConfig {
+    versionCode 1
+    versionName "0.1.0"
+  }
+  lintOptions {
+    abortOnError false
+  }
+
+  kotlinOptions {
+    // ArcGIS Maps SDK 300.0 is built with Kotlin 2.3.0. Allow this module to read its newer
+    // metadata even when the app's Kotlin compiler is older (Expo SDK 56 ships Kotlin 2.1.0).
+    freeCompilerArgs += ["-Xskip-metadata-version-check"]
+  }
+}
+
+dependencies {
+  // ArcGIS Maps SDK for Kotlin — core MapView/GeoView, basemaps, layers, graphics.
+  // Requires the consuming app to set minSdk >= 28 and compileSdk >= 36 (config plugin).
+  implementation 'com.esri:arcgis-maps-kotlin:300.0.0'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest>
+</manifest>

package/android/src/main/java/expo/modules/arcgis/AnalysisOverlayRef.kt

@@ -0,0 +1,165 @@
+package expo.modules.arcgis
+
+import com.arcgismaps.analysis.interactive.Analysis
+import com.arcgismaps.analysis.interactive.ExploratoryLineOfSightTargetVisibility
+import com.arcgismaps.analysis.interactive.ExploratoryLocationDistanceMeasurement
+import com.arcgismaps.analysis.interactive.ExploratoryLocationLineOfSight
+import com.arcgismaps.analysis.interactive.ExploratoryLocationViewshed
+import com.arcgismaps.geometry.Point
+import com.arcgismaps.geometry.SpatialReference
+import com.arcgismaps.mapping.view.AnalysisOverlay
+import expo.modules.kotlin.AppContext
+import expo.modules.kotlin.sharedobjects.SharedObject
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.launch
+
+/**
+ * SharedObject wrapping a native [AnalysisOverlay] owned by a SceneView. Holds the visual analyses
+ * (`<Viewshed>` / `<LineOfSight>`) declared as children of `<AnalysisOverlay>`.
+ */
+class AnalysisOverlayRef(appContext: AppContext) : SharedObject(appContext) {
+  val overlay = AnalysisOverlay(emptyList())
+
+  fun addAnalysis(ref: AnalysisRef) {
+    overlay.analyses.add(ref.analysis)
+  }
+
+  fun removeAnalysis(ref: AnalysisRef) {
+    overlay.analyses.remove(ref.analysis)
+  }
+
+  fun setVisible(visible: Boolean) {
+    overlay.isVisible = visible
+  }
+}
+
+/** Base SharedObject wrapping an exploratory [Analysis] (viewshed / line-of-sight). */
+abstract class AnalysisRef(appContext: AppContext) : SharedObject(appContext) {
+  abstract val analysis: Analysis
+}
+
+/** SharedObject wrapping an [ExploratoryLocationViewshed] — the area visible from an observer. */
+class ViewshedRef(appContext: AppContext, props: Map<String, Any?>) : AnalysisRef(appContext) {
+  private val viewshed = ExploratoryLocationViewshed(
+    analysisPoint(props["location"]) ?: Point(0.0, 0.0, SpatialReference.wgs84()),
+    numOr(props["heading"], 0.0),
+    numOr(props["pitch"], 90.0),
+    numOr(props["horizontalAngle"], 45.0),
+    numOr(props["verticalAngle"], 45.0),
+    (props["minDistance"] as? Number)?.toDouble(),
+    (props["maxDistance"] as? Number)?.toDouble(),
+  )
+
+  override val analysis: Analysis get() = viewshed
+
+  init {
+    applyProps(props)
+  }
+
+  fun applyProps(changed: Map<String, Any?>) {
+    changed.forEach { (key, value) ->
+      when (key) {
+        "location" -> analysisPoint(value)?.let { viewshed.location = it }
+        "heading" -> (value as? Number)?.toDouble()?.let { viewshed.heading = it }
+        "pitch" -> (value as? Number)?.toDouble()?.let { viewshed.pitch = it }
+        "horizontalAngle" -> (value as? Number)?.toDouble()?.let { viewshed.horizontalAngle = it }
+        "verticalAngle" -> (value as? Number)?.toDouble()?.let { viewshed.verticalAngle = it }
+        "minDistance" -> viewshed.minDistance = (value as? Number)?.toDouble()
+        "maxDistance" -> viewshed.maxDistance = (value as? Number)?.toDouble()
+        "frustumOutlineVisible" -> (value as? Boolean)?.let { viewshed.frustumOutlineVisible = it }
+      }
+    }
+  }
+}
+
+/** SharedObject wrapping an [ExploratoryLocationLineOfSight] — streams target visibility to JS. */
+class LineOfSightRef(appContext: AppContext, props: Map<String, Any?>) : AnalysisRef(appContext) {
+  private val lineOfSight = ExploratoryLocationLineOfSight(
+    analysisPoint(props["observer"]) ?: Point(0.0, 0.0, SpatialReference.wgs84()),
+    analysisPoint(props["target"]) ?: Point(0.0, 0.0, SpatialReference.wgs84()),
+  )
+  private val scope = CoroutineScope(Dispatchers.Main + SupervisorJob())
+
+  override val analysis: Analysis get() = lineOfSight
+
+  init {
+    scope.launch {
+      lineOfSight.targetVisibility.collect { visibility ->
+        emit("onTargetVisibilityChange", mapOf("visibility" to visibilityString(visibility)))
+      }
+    }
+  }
+
+  override fun deallocate() {
+    scope.cancel()
+    super.deallocate()
+  }
+
+  fun applyProps(changed: Map<String, Any?>) {
+    changed.forEach { (key, value) ->
+      when (key) {
+        "observer" -> analysisPoint(value)?.let { lineOfSight.observerLocation = it }
+        "target" -> analysisPoint(value)?.let { lineOfSight.targetLocation = it }
+      }
+    }
+  }
+}
+
+/**
+ * SharedObject wrapping an [ExploratoryLocationDistanceMeasurement] — direct/horizontal/vertical
+ * distance between two 3D points. Streams the measurements to JS via `onMeasurementChange`.
+ */
+class DistanceMeasurementRef(appContext: AppContext, props: Map<String, Any?>) : AnalysisRef(appContext) {
+  private val measurement = ExploratoryLocationDistanceMeasurement(
+    analysisPoint(props["startLocation"]) ?: Point(0.0, 0.0, SpatialReference.wgs84()),
+    analysisPoint(props["endLocation"]) ?: Point(0.0, 0.0, SpatialReference.wgs84()),
+  )
+  private val scope = CoroutineScope(Dispatchers.Main + SupervisorJob())
+
+  override val analysis: Analysis get() = measurement
+
+  init {
+    scope.launch {
+      measurement.measurementChanged.collect { m ->
+        emit(
+          "onMeasurementChange",
+          mapOf(
+            "directDistance" to m.directDistance.value,
+            "horizontalDistance" to m.horizontalDistance.value,
+            "verticalDistance" to m.verticalDistance.value,
+          ),
+        )
+      }
+    }
+  }
+
+  override fun deallocate() {
+    scope.cancel()
+    super.deallocate()
+  }
+
+  fun applyProps(changed: Map<String, Any?>) {
+    changed.forEach { (key, value) ->
+      when (key) {
+        "startLocation" -> analysisPoint(value)?.let { measurement.startLocation = it }
+        "endLocation" -> analysisPoint(value)?.let { measurement.endLocation = it }
+      }
+    }
+  }
+}
+
+/** Decodes a JS point dict into a [Point] (returns null if the value is not a point geometry). */
+internal fun analysisPoint(value: Any?): Point? =
+  (value as? Map<*, *>)?.let { geometryFromDict(it) } as? Point
+
+private fun numOr(value: Any?, default: Double): Double = (value as? Number)?.toDouble() ?: default
+
+/** Maps the native line-of-sight visibility to the JS `TargetVisibility` union. */
+private fun visibilityString(v: ExploratoryLineOfSightTargetVisibility): String = when (v) {
+  is ExploratoryLineOfSightTargetVisibility.Visible -> "visible"
+  is ExploratoryLineOfSightTargetVisibility.Obstructed -> "obstructed"
+  else -> "unknown"
+}

package/android/src/main/java/expo/modules/arcgis/AuthChallengeHandler.kt

@@ -0,0 +1,78 @@
+package expo.modules.arcgis
+
+import com.arcgismaps.ArcGISEnvironment
+import com.arcgismaps.httpcore.authentication.ArcGISAuthenticationChallenge
+import com.arcgismaps.httpcore.authentication.ArcGISAuthenticationChallengeHandler
+import com.arcgismaps.httpcore.authentication.ArcGISAuthenticationChallengeResponse
+import com.arcgismaps.httpcore.authentication.OAuthUserConfiguration
+import com.arcgismaps.httpcore.authentication.OAuthUserCredential
+import com.arcgismaps.httpcore.authentication.OAuthUserSignIn
+import com.arcgismaps.httpcore.authentication.TokenCredential
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.launch
+
+/**
+ * Reactive token-auth handler — the pattern the docs recommend over pre-adding credentials by hand.
+ * The SDK calls this whenever a secured resource needs credentials, passing the exact [challenge]
+ * (URL / referer), so the right token is minted for the right resource at the right time.
+ */
+object AuthChallengeHandler : ArcGISAuthenticationChallengeHandler {
+  private var username: String? = null
+  private var password: String? = null
+
+  /** Stores (or clears, when null) the login the handler uses to mint token credentials on demand. */
+  fun setCredentials(username: String?, password: String?) {
+    this.username = username
+    this.password = password
+  }
+
+  override suspend fun handleArcGISAuthenticationChallenge(
+    challenge: ArcGISAuthenticationChallenge,
+  ): ArcGISAuthenticationChallengeResponse {
+    val user = username ?: return ArcGISAuthenticationChallengeResponse.ContinueAndFail
+    val pass = password ?: return ArcGISAuthenticationChallengeResponse.ContinueAndFail
+    return TokenCredential.create(challenge.requestUrl, user, pass)
+      .map { ArcGISAuthenticationChallengeResponse.ContinueWithCredential(it) }
+      .getOrElse { ArcGISAuthenticationChallengeResponse.ContinueAndFail }
+  }
+}
+
+/**
+ * Drives an OAuth user sign-in across two JS calls (the SDK can't present a browser itself on
+ * Android): `start` kicks off the flow and returns the authorize URL for JS to open in a browser;
+ * `complete` finishes it with the redirect URL and caches the credential.
+ */
+object OAuthController {
+  private val scope = CoroutineScope(Dispatchers.Main + SupervisorJob())
+  private var signIn: OAuthUserSignIn? = null
+  private var completion: CompletableDeferred<Unit>? = null
+
+  /** Starts the flow; resolves with the authorize URL once the SDK produces the sign-in request. */
+  suspend fun start(portalUrl: String, clientId: String, redirectUrl: String): String {
+    val configuration = OAuthUserConfiguration(portalUrl, clientId, redirectUrl)
+    val authorizeUrl = CompletableDeferred<String>()
+    scope.launch {
+      OAuthUserCredential.create(configuration) { request ->
+        signIn = request
+        authorizeUrl.complete(request.authorizeUrl)
+      }.onSuccess { credential ->
+        ArcGISEnvironment.authenticationManager.arcGISCredentialStore.add(credential)
+        completion?.complete(Unit)
+      }.onFailure { error ->
+        completion?.completeExceptionally(error)
+      }
+    }
+    return authorizeUrl.await()
+  }
+
+  /** Completes the flow with the browser redirect URL; suspends until the credential is cached. */
+  suspend fun complete(redirectUrl: String) {
+    val done = CompletableDeferred<Unit>()
+    completion = done
+    signIn?.complete(redirectUrl)
+    done.await()
+  }
+}

package/android/src/main/java/expo/modules/arcgis/CoordinateFormatterFunctions.kt

@@ -0,0 +1,44 @@
+package expo.modules.arcgis
+
+import com.arcgismaps.geometry.CoordinateFormatter
+import com.arcgismaps.geometry.Point
+
+/**
+ * Free functions backing the JS `coordinateFormatter` namespace. They convert a `point`
+ * geometry to/from latitude-longitude, MGRS, USNG and UTM notation strings via
+ * [CoordinateFormatter] (a Kotlin object). Registered as module `Function`s in `ExpoArcgisModule`.
+ */
+
+private fun cfPoint(dict: Map<String, Any?>?): Point? = dict?.let { geometryFromDict(it) } as? Point
+
+// region Latitude-longitude
+
+internal fun cfToLatLong(p: Map<String, Any?>, format: String?, decimalPlaces: Int): String? =
+  cfPoint(p)?.let { CoordinateFormatter.toLatitudeLongitudeOrNull(it, latitudeLongitudeFormat(format), decimalPlaces) }
+
+internal fun cfFromLatLong(coordinates: String, wkid: Int): Map<String, Any?>? =
+  CoordinateFormatter.fromLatitudeLongitudeOrNull(coordinates, spatialReference(wkid))?.let { dictFromGeometry(it) }
+
+// region MGRS
+
+internal fun cfToMgrs(p: Map<String, Any?>, mode: String?, precision: Int, addSpaces: Boolean): String? =
+  cfPoint(p)?.let { CoordinateFormatter.toMgrsOrNull(it, mgrsConversionMode(mode), precision, addSpaces) }
+
+internal fun cfFromMgrs(coordinates: String, wkid: Int, mode: String?): Map<String, Any?>? =
+  CoordinateFormatter.fromMgrsOrNull(coordinates, spatialReference(wkid), mgrsConversionMode(mode))?.let { dictFromGeometry(it) }
+
+// region USNG
+
+internal fun cfToUsng(p: Map<String, Any?>, precision: Int, addSpaces: Boolean): String? =
+  cfPoint(p)?.let { CoordinateFormatter.toUsngOrNull(it, precision, addSpaces) }
+
+internal fun cfFromUsng(coordinates: String, wkid: Int): Map<String, Any?>? =
+  CoordinateFormatter.fromUsngOrNull(coordinates, spatialReference(wkid))?.let { dictFromGeometry(it) }
+
+// region UTM
+
+internal fun cfToUtm(p: Map<String, Any?>, mode: String?, addSpaces: Boolean): String? =
+  cfPoint(p)?.let { CoordinateFormatter.toUtmOrNull(it, utmConversionMode(mode), addSpaces) }
+
+internal fun cfFromUtm(coordinates: String, wkid: Int, mode: String?): Map<String, Any?>? =
+  CoordinateFormatter.fromUtmOrNull(coordinates, spatialReference(wkid), utmConversionMode(mode))?.let { dictFromGeometry(it) }

package/android/src/main/java/expo/modules/arcgis/DynamicEntityLayerRef.kt

@@ -0,0 +1,133 @@
+package expo.modules.arcgis
+
+import com.arcgismaps.data.Field
+import com.arcgismaps.data.FieldType
+import com.arcgismaps.mapping.layers.DynamicEntityLayer
+import com.arcgismaps.mapping.layers.Layer
+import com.arcgismaps.realtime.ArcGISStreamService
+import com.arcgismaps.realtime.ArcGISStreamServiceFilter
+import com.arcgismaps.realtime.ConnectionStatus
+import com.arcgismaps.realtime.CustomDynamicEntityDataSource
+import com.arcgismaps.realtime.DynamicEntityDataSource
+import com.arcgismaps.realtime.DynamicEntityDataSourceInfo
+import com.arcgismaps.realtime.DynamicEntityQueryParameters
+import expo.modules.kotlin.AppContext
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.flow.SharedFlow
+import kotlinx.coroutines.flow.asSharedFlow
+import kotlinx.coroutines.launch
+
+/**
+ * Operational [DynamicEntityLayer] backed by a real-time data source (a stream service — moving
+ * entities that update live). Emits `onConnectionStatusChange` as the data source connects.
+ */
+class DynamicEntityLayerRef(appContext: AppContext, props: Map<String, Any?>) : LayerRef(appContext) {
+  // Non-null only in custom-source mode — observations pushed from JS are emitted into this flow.
+  private val pushFlow: MutableSharedFlow<CustomDynamicEntityDataSource.FeedEvent>? =
+    if (props["customSource"] != null) MutableSharedFlow(extraBufferCapacity = 64) else null
+  val dataSource: DynamicEntityDataSource = buildDataSource(props, pushFlow)
+  override val layer: Layer = DynamicEntityLayer(dataSource)
+  private val scope = CoroutineScope(Dispatchers.Main + SupervisorJob())
+
+  init {
+    scope.launch {
+      dataSource.connectionStatus.collect { status ->
+        emit("onConnectionStatusChange", mapOf("status" to connectionStatusString(status)))
+      }
+    }
+  }
+
+  /** Pushes an observation into a custom data source (no-op for a stream service). */
+  fun pushObservation(attributes: Map<String, Any?>, geometry: Map<String, Any?>) {
+    val flow = pushFlow ?: return
+    val geom = geometryFromDict(geometry) ?: return
+    flow.tryEmit(CustomDynamicEntityDataSource.FeedEvent.NewObservation(geom, attributes))
+  }
+
+  /** Returns the data source's currently-tracked dynamic entities (attributes + geometry). */
+  suspend fun queryDynamicEntities(): Map<String, Any?> {
+    val result = dataSource.queryDynamicEntities(DynamicEntityQueryParameters()).getOrThrow()
+    val entities = result.toList()
+    return mapOf(
+      "count" to entities.size,
+      "entities" to entities.map { entity ->
+        mapOf(
+          "attributes" to entity.attributes,
+          "geometry" to entity.geometry?.let { dictFromGeometry(it) },
+        )
+      },
+    )
+  }
+
+  override fun applyProps(changed: Map<String, Any?>) {
+    applyCommonProps(changed)
+    val entityLayer = layer as? DynamicEntityLayer ?: return
+    (changed["trackDisplay"] as? Map<*, *>)?.let { track ->
+      (track["maximumObservations"] as? Number)?.toInt()?.let {
+        entityLayer.trackDisplayProperties.maximumObservations = it
+      }
+      (track["showsPreviousObservations"] as? Boolean)?.let {
+        entityLayer.trackDisplayProperties.showPreviousObservations = it
+      }
+    }
+    (changed["filter"] as? Map<*, *>)?.let { filterDict ->
+      val filter = ArcGISStreamServiceFilter().apply {
+        (filterDict["whereClause"] as? String)?.let { whereClause = it }
+        (filterDict["geometry"] as? Map<*, *>)?.let { g -> geometryFromDict(g)?.let { geometry = it } }
+      }
+      (dataSource as? ArcGISStreamService)?.filter = filter
+    }
+  }
+
+  override fun deallocate() {
+    scope.cancel()
+    super.deallocate()
+  }
+}
+
+/** Maps [ConnectionStatus] to the JS string union. */
+fun connectionStatusString(status: ConnectionStatus): String = when (status) {
+  is ConnectionStatus.Disconnected -> "disconnected"
+  is ConnectionStatus.Connecting -> "connecting"
+  is ConnectionStatus.Connected -> "connected"
+  is ConnectionStatus.Failed -> "failed"
+}
+
+/** Builds the real-time data source: a custom feed (push from JS) or a stream service. */
+private fun buildDataSource(
+  props: Map<String, Any?>,
+  pushFlow: MutableSharedFlow<CustomDynamicEntityDataSource.FeedEvent>?,
+): DynamicEntityDataSource {
+  val custom = props["customSource"] as? Map<*, *>
+  if (custom != null && pushFlow != null) {
+    val info = DynamicEntityDataSourceInfo(
+      custom["entityIdField"] as? String ?: "id",
+      buildDynamicEntityFields(custom["fields"] as? List<*>),
+    )
+    return CustomDynamicEntityDataSource(object : CustomDynamicEntityDataSource.EntityFeedProvider {
+      override val feed: SharedFlow<CustomDynamicEntityDataSource.FeedEvent> = pushFlow.asSharedFlow()
+      override suspend fun onLoad(): DynamicEntityDataSourceInfo = info
+      override suspend fun onConnect() {}
+      override suspend fun onDisconnect() {}
+    })
+  }
+  return ArcGISStreamService(props["streamServiceUrl"] as? String ?: "")
+}
+
+/** Builds [Field]s from JS `{ name, type }` defs for a custom data source. */
+private fun buildDynamicEntityFields(defs: List<*>?): List<Field> =
+  (defs ?: emptyList<Any?>()).filterIsInstance<Map<*, *>>().map { def ->
+    Field(dynamicEntityFieldType(def["type"] as? String), def["name"] as? String ?: "", "", 0, null, true, true)
+  }
+
+private fun dynamicEntityFieldType(type: String?): FieldType = when (type) {
+  "int32" -> FieldType.Int32
+  "int64" -> FieldType.Int64
+  "float64" -> FieldType.Float64
+  "date" -> FieldType.Date
+  else -> FieldType.Text
+}