@maydon_tech/react-native-nitro-maps 0.1.4 → 0.2.0

package/android/src/main/kotlin/com/margelo/nitro/nitromap/markers/MarkerIconFactory.kt

@@ -0,0 +1,303 @@
+package com.margelo.nitro.nitromap.markers
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.Paint
+import android.graphics.PorterDuff
+import android.graphics.PorterDuffXfermode
+import android.graphics.Rect
+import android.graphics.RectF
+import android.util.Base64
+import android.util.Log
+import android.util.LruCache
+import com.google.android.gms.maps.model.BitmapDescriptor
+import com.google.android.gms.maps.model.BitmapDescriptorFactory
+import com.margelo.nitro.nitromap.ImageMarkerConfig
+import com.margelo.nitro.nitromap.MarkerData
+import com.margelo.nitro.nitromap.MarkerStyle
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+import kotlinx.coroutines.Dispatchers
+import java.net.HttpURLConnection
+import java.net.URL
+
+/**
+ * Android equivalent of iOS MarkerIconFactory + MarkerIconCache.
+ *
+ * - Maps MarkerData → BitmapDescriptor (Google Maps icon).
+ * - LruCache for bitmap reuse (avoids texture exhaustion on large datasets).
+ * - Price markers: delegated to PriceMarkerRenderer (Canvas drawing).
+ * - Image markers: base64 inline or async URL loading.
+ */
+// C-3: Accept a CoroutineScope from the provider to avoid unstructured coroutine leaks
+class MarkerIconFactory(private val context: Context, private val scope: CoroutineScope) {
+
+    companion object {
+        private const val TAG = "MarkerIconFactory"
+        private const val MAX_CACHE_ENTRIES = 500
+        private const val URL_CACHE_ENTRIES = 200
+
+        // Cache key helpers (deterministic, stable across launches)
+        fun priceMarkerKey(price: String, currency: String, selected: Boolean, config: com.margelo.nitro.nitromap.PriceMarkerStyle? = null): String {
+            // Include color hash to prevent cross-color cache collisions
+            val colorHash = if (config != null) {
+                stableHash(buildString {
+                    config.backgroundColor?.let { append(it.hashCode()) }
+                    config.selectedBackgroundColor?.let { append(it.hashCode()) }
+                    config.textColor?.let { append(it.hashCode()) }
+                    config.selectedTextColor?.let { append(it.hashCode()) }
+                    append(config.fontSize ?: 0.0)
+                })
+            } else 0
+            return "price_${price}_${currency}_${selected}_$colorHash"
+        }
+
+        fun imageMarkerKey(source: String, width: Double, height: Double, cornerRadius: Double): String {
+            val w = (width / 5).toInt() * 5  // round to nearest 5
+            val h = (height / 5).toInt() * 5
+            val r = (cornerRadius / 5).toInt() * 5
+            val sourceHash = stableHash(source)
+            return "image_${sourceHash}_${w}_${h}_${r}"
+        }
+
+        // L-5: Math.abs(hash) returns negative for Integer.MIN_VALUE.
+        // Use bitwise AND to ensure non-negative result.
+        private fun stableHash(s: String): Int {
+            var hash = 5381
+            for (c in s.toByteArray()) {
+                hash = (hash shl 5) + hash + c.toInt()
+            }
+            return hash and Int.MAX_VALUE
+        }
+    }
+
+    // Lock object for thread-safe cache access.
+    // LruCache is not thread-safe — all get/put/evict calls must be synchronized.
+    private val cacheLock = Any()
+
+    // Icon bitmap cache (BitmapDescriptor wraps Bitmap — cache the Bitmap separately)
+    // L-2/L-3: Override entryRemoved to recycle evicted bitmaps and prevent memory leaks
+    private val bitmapCache = object : LruCache<String, Bitmap>(MAX_CACHE_ENTRIES) {
+        override fun entryRemoved(evicted: Boolean, key: String?, oldValue: Bitmap?, newValue: Bitmap?) {
+            if (evicted && oldValue != null && !oldValue.isRecycled) {
+                oldValue.recycle()
+            }
+        }
+    }
+    // Separate URL image cache (source bitmaps before rendering)
+    private val urlBitmapCache = object : LruCache<String, Bitmap>(URL_CACHE_ENTRIES) {
+        override fun entryRemoved(evicted: Boolean, key: String?, oldValue: Bitmap?, newValue: Bitmap?) {
+            if (evicted && oldValue != null && !oldValue.isRecycled) {
+                oldValue.recycle()
+            }
+        }
+    }
+
+    /**
+     * Callback invoked when an async URL image finishes loading.
+     * Passes the marker id and updated BitmapDescriptor.
+     */
+    var onIconLoaded: ((markerId: String, icon: BitmapDescriptor) -> Unit)? = null
+
+    // MARK: - Public API
+
+    fun createIcon(markerData: MarkerData): BitmapDescriptor? {
+        return when (markerData.config.style) {
+            MarkerStyle.PRICEMARKER -> createPriceMarkerIcon(markerData)
+            MarkerStyle.IMAGE -> createImageMarkerIcon(markerData)
+            MarkerStyle.DEFAULT -> null
+        }
+    }
+
+    fun clearCache() {
+        synchronized(cacheLock) {
+            bitmapCache.evictAll()
+            urlBitmapCache.evictAll()
+        }
+        Log.d(TAG, "Icon cache cleared")
+    }
+
+    // MARK: - Price Marker
+
+    private fun createPriceMarkerIcon(markerData: MarkerData): BitmapDescriptor? {
+        val config = markerData.config.priceMarker ?: return null
+        val cacheKey = priceMarkerKey(config.price, config.currency, config.selected, config)
+
+        synchronized(cacheLock) {
+            bitmapCache.get(cacheKey)?.let {
+                return BitmapDescriptorFactory.fromBitmap(it)
+            }
+        }
+
+        val bitmap = PriceMarkerRenderer.render(config, context.resources.displayMetrics)
+        synchronized(cacheLock) { bitmapCache.put(cacheKey, bitmap) }
+        return BitmapDescriptorFactory.fromBitmap(bitmap)
+    }
+
+    // MARK: - Image Marker
+
+    private fun createImageMarkerIcon(markerData: MarkerData): BitmapDescriptor? {
+        val config = markerData.config.image ?: return null
+        val imageSource = config.imageBase64 ?: config.imageUrl ?: return null
+        val cacheKey = imageMarkerKey(imageSource, config.width, config.height, config.cornerRadius)
+
+        // Cache hit
+        synchronized(cacheLock) {
+            bitmapCache.get(cacheKey)?.let {
+                return BitmapDescriptorFactory.fromBitmap(it)
+            }
+        }
+
+        // Base64 inline — decode synchronously
+        if (config.imageBase64 != null) {
+            val sourceBitmap = decodeBase64(config.imageBase64) ?: return null
+            val rendered = renderImageMarker(sourceBitmap, config)
+            synchronized(cacheLock) { bitmapCache.put(cacheKey, rendered) }
+            return BitmapDescriptorFactory.fromBitmap(rendered)
+        }
+
+        // URL — check URL bitmap cache first
+        val urlString = config.imageUrl ?: return null
+        val cachedUrlBitmap = synchronized(cacheLock) { urlBitmapCache.get(urlString) }
+        if (cachedUrlBitmap != null) {
+            val rendered = renderImageMarker(cachedUrlBitmap, config)
+            synchronized(cacheLock) { bitmapCache.put(cacheKey, rendered) }
+            return BitmapDescriptorFactory.fromBitmap(rendered)
+        }
+
+        // Async URL load — return placeholder, callback when done
+        loadUrlImageAsync(markerData.id, urlString, cacheKey, config)
+        val placeholder = createPlaceholder(config)
+        synchronized(cacheLock) { bitmapCache.put(cacheKey, placeholder) }
+        return BitmapDescriptorFactory.fromBitmap(placeholder)
+    }
+
+    // MARK: - Async URL Loading
+
+    private fun loadUrlImageAsync(
+        markerId: String,
+        urlString: String,
+        cacheKey: String,
+        config: ImageMarkerConfig
+    ) {
+        scope.launch {
+            val sourceBitmap = withContext(Dispatchers.IO) {
+                var connection: HttpURLConnection? = null
+                try {
+                    val url = URL(urlString)
+                    connection = url.openConnection() as HttpURLConnection
+                    connection.connectTimeout = 10_000
+                    connection.readTimeout = 10_000
+                    connection.useCaches = true
+                    connection.connect()
+                    if (connection.responseCode !in 200..299) {
+                        Log.w(TAG, "HTTP ${connection.responseCode} loading $urlString")
+                        return@withContext null
+                    }
+                    BitmapFactory.decodeStream(connection.inputStream)
+                } catch (e: Exception) {
+                    Log.w(TAG, "Failed to load image from $urlString: ${e.message}")
+                    null
+                } finally {
+                    // H-6: Always disconnect HttpURLConnection
+                    connection?.disconnect()
+                }
+            } ?: return@launch
+
+            // Back on main thread — cache and notify
+            val rendered = renderImageMarker(sourceBitmap, config)
+            synchronized(cacheLock) {
+                urlBitmapCache.put(urlString, sourceBitmap)
+                bitmapCache.put(cacheKey, rendered)
+            }
+            onIconLoaded?.invoke(markerId, BitmapDescriptorFactory.fromBitmap(rendered))
+            Log.d(TAG, "Icon loaded for marker $markerId from $urlString")
+        }
+    }
+
+    // MARK: - Rendering
+
+    private fun renderImageMarker(sourceBitmap: Bitmap, config: ImageMarkerConfig): Bitmap {
+        val density = context.resources.displayMetrics.density
+        val widthPx = (config.width * density).toInt().coerceAtLeast(1)
+        val heightPx = (config.height * density).toInt().coerceAtLeast(1)
+        val radiusPx = (config.cornerRadius * density).toFloat()
+        val borderWidthPx = (config.borderWidth * density).toFloat()
+
+        val borderColor = PriceMarkerRenderer.resolveColorValue(
+            config.borderColor,
+            Color.rgb(200, 200, 200)
+        )
+
+        val output = Bitmap.createBitmap(widthPx, heightPx, Bitmap.Config.ARGB_8888)
+        val canvas = Canvas(output)
+
+        // Clip path for rounded corners
+        val rect = RectF(0f, 0f, widthPx.toFloat(), heightPx.toFloat())
+        val paint = Paint(Paint.ANTI_ALIAS_FLAG)
+
+        // Draw rounded rect shape as clip mask
+        paint.color = Color.WHITE
+        canvas.drawRoundRect(rect, radiusPx, radiusPx, paint)
+
+        // Draw source image using SRC_IN (clips to rounded rect)
+        paint.xfermode = PorterDuffXfermode(PorterDuff.Mode.SRC_IN)
+        val scaled = Bitmap.createScaledBitmap(sourceBitmap, widthPx, heightPx, true)
+        canvas.drawBitmap(scaled, 0f, 0f, paint)
+        paint.xfermode = null
+        // L-7: Recycle the scaled intermediate bitmap if it's not the source
+        if (scaled !== sourceBitmap) {
+            scaled.recycle()
+        }
+
+        // Draw border
+        if (borderWidthPx > 0) {
+            val borderPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+                style = Paint.Style.STROKE
+                color = borderColor
+                strokeWidth = borderWidthPx
+            }
+            // Inset border rect by half stroke width so it stays inside clip
+            val inset = borderWidthPx / 2f
+            val borderRect = RectF(inset, inset, widthPx.toFloat() - inset, heightPx.toFloat() - inset)
+            canvas.drawRoundRect(borderRect, radiusPx, radiusPx, borderPaint)
+        }
+
+        return output
+    }
+
+    private fun createPlaceholder(config: ImageMarkerConfig): Bitmap {
+        val density = context.resources.displayMetrics.density
+        val widthPx = (config.width * density).toInt().coerceAtLeast(1)
+        val heightPx = (config.height * density).toInt().coerceAtLeast(1)
+        val radiusPx = (config.cornerRadius * density)
+
+        val bitmap = Bitmap.createBitmap(widthPx, heightPx, Bitmap.Config.ARGB_8888)
+        val canvas = Canvas(bitmap)
+        val paint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            color = Color.argb((0.3f * 255).toInt(), 200, 200, 200)
+        }
+        canvas.drawRoundRect(
+            RectF(0f, 0f, widthPx.toFloat(), heightPx.toFloat()),
+            radiusPx.toFloat(), radiusPx.toFloat(),
+            paint
+        )
+        return bitmap
+    }
+
+    // MARK: - Utilities
+
+    private fun decodeBase64(base64: String): Bitmap? {
+        return try {
+            val bytes = Base64.decode(base64, Base64.DEFAULT)
+            BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
+        } catch (e: Exception) {
+            Log.w(TAG, "Failed to decode base64 image: ${e.message}")
+            null
+        }
+    }
+}

package/android/src/main/kotlin/com/margelo/nitro/nitromap/markers/MarkerSelectionHandler.kt

@@ -0,0 +1,72 @@
+package com.margelo.nitro.nitromap.markers
+
+import com.margelo.nitro.nitromap.MarkerAnimation
+import com.margelo.nitro.nitromap.MarkerConfig
+import com.margelo.nitro.nitromap.MarkerData
+import com.margelo.nitro.nitromap.MarkerStyle
+import com.margelo.nitro.nitromap.PriceMarkerStyle
+
+/**
+ * Handles marker selection state changes in a pure, immutable fashion.
+ *
+ * Mirrors iOS MarkerSelectionHandler.swift — only PriceMarker style supports
+ * visual selection state. All other marker types return null (no change).
+ *
+ * Thread-safe: stateless, can be called from any thread.
+ */
+object MarkerSelectionHandler {
+
+    /**
+     * Creates an updated MarkerData with the new selection state applied.
+     *
+     * @return Updated marker data with the new selection state, or null if the marker
+     *         type doesn't support visual selection state OR if the state has not changed.
+     */
+    fun updateSelectionState(markerData: MarkerData, selected: Boolean): MarkerData? {
+        // Only pricemarker style supports visual selection state
+        if (markerData.config.style != MarkerStyle.PRICEMARKER) return null
+        val priceConfig = markerData.config.priceMarker ?: return null
+
+        // Early exit if state hasn't changed
+        if (priceConfig.selected == selected) return null
+
+        // Create updated price config with new selection state (immutable copy)
+        val updatedPriceConfig = PriceMarkerStyle(
+            price = priceConfig.price,
+            currency = priceConfig.currency,
+            selected = selected,
+            backgroundColor = priceConfig.backgroundColor,
+            selectedBackgroundColor = priceConfig.selectedBackgroundColor,
+            textColor = priceConfig.textColor,
+            selectedTextColor = priceConfig.selectedTextColor,
+            fontSize = priceConfig.fontSize,
+            paddingHorizontal = priceConfig.paddingHorizontal,
+            paddingVertical = priceConfig.paddingVertical,
+            shadowOpacity = priceConfig.shadowOpacity
+        )
+
+        val updatedConfig = MarkerConfig(
+            style = markerData.config.style,
+            image = markerData.config.image,
+            priceMarker = updatedPriceConfig
+        )
+
+        return MarkerData(
+            id = markerData.id,
+            coordinate = markerData.coordinate,
+            title = markerData.title,
+            description = markerData.description,
+            draggable = markerData.draggable,
+            opacity = markerData.opacity,
+            rotation = markerData.rotation,
+            zIndex = markerData.zIndex,
+            anchor = markerData.anchor,
+            config = updatedConfig,
+            accessibilityLabel = markerData.accessibilityLabel,
+            clusteringEnabled = markerData.clusteringEnabled,
+            animation = markerData.animation,
+            animationDuration = markerData.animationDuration,
+            animateOnReappear = markerData.animateOnReappear
+        )
+    }
+}

package/android/src/main/kotlin/com/margelo/nitro/nitromap/markers/PriceMarkerRenderer.kt

@@ -0,0 +1,159 @@
+package com.margelo.nitro.nitromap.markers
+
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.Paint
+import android.graphics.RectF
+import android.graphics.Typeface
+import android.util.DisplayMetrics
+import android.util.TypedValue
+import com.margelo.nitro.nitromap.MarkerColor
+import com.margelo.nitro.nitromap.PriceMarkerStyle
+import com.margelo.nitro.nitromap.Variant_String_MarkerColor
+
+/**
+ * Android equivalent of iOS PriceMarkerRenderer.swift.
+ *
+ * Renders a pill-shaped label with price text.
+ * Uses Canvas + Paint for density-aware drawing.
+ * Mirrors the iOS shadow, padding, and typography.
+ */
+object PriceMarkerRenderer {
+
+    // Default style values (match iOS defaults)
+    private val DEFAULT_BG_COLOR = Color.WHITE
+    private val DEFAULT_SELECTED_BG_COLOR = Color.rgb(255, 59, 48)   // iOS red
+    private val DEFAULT_TEXT_COLOR = Color.rgb(51, 51, 51)
+    private val DEFAULT_TEXT_COLOR_SELECTED = Color.WHITE
+    private const val DEFAULT_FONT_SIZE_SP = 10f
+    private const val DEFAULT_PADDING_H_DP = 8f
+    private const val DEFAULT_PADDING_V_DP = 6f
+    private const val DEFAULT_SHADOW_OPACITY = 0.12f
+
+    // Shadow constants (match iOS: blur=8, offset=2)
+    private const val SHADOW_BLUR_DP = 8f
+    private const val SHADOW_OFFSET_DP = 2f
+
+    fun render(config: PriceMarkerStyle?, displayMetrics: DisplayMetrics): Bitmap {
+        val selected = config?.selected ?: false
+        val price = config?.price ?: "0"
+        val currency = config?.currency ?: ""
+        val text = "$price $currency"
+
+        // Colors
+        val bgColor = resolveColor(config?.backgroundColor, DEFAULT_BG_COLOR)
+        val selectedBgColor = resolveColor(config?.selectedBackgroundColor, DEFAULT_SELECTED_BG_COLOR)
+        val textColor = resolveColor(config?.textColor, DEFAULT_TEXT_COLOR)
+        val selectedTextColor = resolveColor(config?.selectedTextColor, DEFAULT_TEXT_COLOR_SELECTED)
+
+        val activeBg = if (selected) selectedBgColor else bgColor
+        val activeText = if (selected) selectedTextColor else textColor
+
+        // Dimensions
+        val density = displayMetrics.density
+        val fontSizePx = TypedValue.applyDimension(
+            TypedValue.COMPLEX_UNIT_SP,
+            (config?.fontSize ?: DEFAULT_FONT_SIZE_SP.toDouble()).toFloat(),
+            displayMetrics
+        )
+        val paddingHPx = dp2px((config?.paddingHorizontal ?: DEFAULT_PADDING_H_DP.toDouble()).toFloat(), density)
+        val paddingVPx = dp2px((config?.paddingVertical ?: DEFAULT_PADDING_V_DP.toDouble()).toFloat(), density)
+        val shadowBlurPx = dp2px(SHADOW_BLUR_DP, density)
+        val shadowOffsetPx = dp2px(SHADOW_OFFSET_DP, density)
+        val shadowOpacity = (config?.shadowOpacity ?: DEFAULT_SHADOW_OPACITY.toDouble()).toFloat()
+
+        // Measure text
+        val textPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            this.textSize = fontSizePx
+            typeface = Typeface.create(Typeface.DEFAULT, Typeface.NORMAL)
+        }
+        val textWidth = textPaint.measureText(text)
+        val fontMetrics = textPaint.fontMetrics
+        val textHeight = fontMetrics.descent - fontMetrics.ascent
+
+        // Pill dimensions
+        val pillWidth = textWidth + paddingHPx * 2
+        val pillHeight = textHeight + paddingVPx * 2
+        val cornerRadius = pillHeight / 2f
+
+        // Canvas size — add room for shadow (match iOS: blur*2 wide, blur+offset+blur/2 tall)
+        val canvasWidth = (pillWidth + shadowBlurPx * 2).toInt() + 1
+        val canvasHeight = (pillHeight + shadowBlurPx + shadowOffsetPx + shadowBlurPx / 2).toInt() + 1
+
+        val bitmap = Bitmap.createBitmap(canvasWidth, canvasHeight, Bitmap.Config.ARGB_8888)
+        val canvas = Canvas(bitmap)
+
+        // Pill rect (offset inward to leave room for shadow)
+        val left = shadowBlurPx
+        val top = shadowBlurPx / 2
+        val pillRect = RectF(left, top, left + pillWidth, top + pillHeight)
+
+        // Shadow paint
+        val shadowPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            color = activeBg
+            setShadowLayer(
+                shadowBlurPx,
+                0f,
+                shadowOffsetPx,
+                applyAlpha(Color.BLACK, shadowOpacity)
+            )
+        }
+        canvas.drawRoundRect(pillRect, cornerRadius, cornerRadius, shadowPaint)
+
+        // Background paint (overdraw without shadow so shape is crisp)
+        val bgPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            color = activeBg
+        }
+        canvas.drawRoundRect(pillRect, cornerRadius, cornerRadius, bgPaint)
+
+        // Text
+        textPaint.color = activeText
+        val textX = pillRect.left + paddingHPx
+        val textY = pillRect.top + paddingVPx - fontMetrics.ascent
+        canvas.drawText(text, textX, textY, textPaint)
+
+        return bitmap
+    }
+
+    // MARK: - Helpers
+
+    private fun dp2px(dp: Float, density: Float) = dp * density
+
+    private fun applyAlpha(color: Int, alpha: Float): Int {
+        val a = (alpha * 255).toInt().coerceIn(0, 255)
+        return Color.argb(a, Color.red(color), Color.green(color), Color.blue(color))
+    }
+
+    /**
+     * Resolves a Variant_String_MarkerColor to an Android Color int.
+     * Supports hex strings (#RRGGBB / #AARRGGBB) and MarkerColor structs.
+     */
+    internal fun resolveColor(variant: Variant_String_MarkerColor?, default: Int): Int {
+        variant ?: return default
+        return variant.match(
+            first = { hex -> parseHexColor(hex) ?: default },
+            second = { mc -> markerColorToInt(mc) }
+        )
+    }
+
+    internal fun resolveColorValue(variant: com.margelo.nitro.nitromap.ColorValue?, default: Int): Int {
+        variant ?: return default
+        return variant.match(
+            first = { hex -> parseHexColor(hex) ?: default },
+            second = { mc -> markerColorToInt(mc) }
+        )
+    }
+
+    private fun parseHexColor(hex: String): Int? {
+        return try {
+            Color.parseColor(hex)
+        } catch (e: IllegalArgumentException) {
+            null
+        }
+    }
+
+    internal fun markerColorToInt(mc: MarkerColor): Int {
+        return Color.argb(mc.a.toInt(), mc.r.toInt(), mc.g.toInt(), mc.b.toInt())
+    }
+}

package/android/src/main/kotlin/com/margelo/nitro/nitromap/providers/MapProviderFactory.kt

@@ -0,0 +1,24 @@
+package com.margelo.nitro.nitromap.providers
+
+import android.content.Context
+import com.margelo.nitro.nitromap.MapProvider
+import com.margelo.nitro.nitromap.providers.google.GoogleMapProvider
+
+/**
+ * Factory for creating map provider instances.
+ * Mirrors iOS MapProviderFactory.swift.
+ */
+object MapProviderFactory {
+
+    fun create(provider: MapProvider, context: Context): MapProviderInterface {
+        return when (provider) {
+            MapProvider.GOOGLE -> GoogleMapProvider(context)
+            MapProvider.APPLE -> throw UnsupportedOperationException(
+                "Apple Maps provider is not available on Android"
+            )
+            MapProvider.YANDEX -> throw UnsupportedOperationException(
+                "Yandex Maps provider is not yet implemented"
+            )
+        }
+    }
+}

package/android/src/main/kotlin/com/margelo/nitro/nitromap/providers/MapProviderInterface.kt

@@ -0,0 +1,128 @@
+package com.margelo.nitro.nitromap.providers
+
+import android.content.Context
+import android.view.View
+import com.margelo.nitro.nitromap.*
+
+/**
+ * Interface that all map providers must implement.
+ * Mirrors iOS MapProviderProtocol.swift.
+ *
+ * Allows the library to support multiple map backends (Google, Apple, Yandex).
+ * Implementation details (command queues, async map init, native view subclasses)
+ * stay internal to each provider.
+ */
+interface MapProviderInterface {
+
+    // MARK: - View Lifecycle
+
+    /** Create the underlying map view. Provider manages its own saved state. */
+    fun createMapView(context: Context): View
+
+    /** Called after the map view is added to the container. Provider starts async map init here. */
+    fun onViewAttached(view: View)
+
+    /** Called when the view is detached. Provider should pause and save state, but keep data. */
+    fun onViewDetaching()
+
+    /** Called on dispose. Provider should perform full cleanup. */
+    fun onViewDestroying()
+
+    // MARK: - Properties
+
+    var initialRegion: Region?
+    var region: Region?
+    var showsUserLocation: Boolean?
+    var zoomEnabled: Boolean?
+    var scrollEnabled: Boolean?
+    var rotateEnabled: Boolean?
+    var pitchEnabled: Boolean?
+    var mapType: MapType?
+    /** Currently uses Google Maps JSON format. Will need provider-specific handling for Apple/Yandex. */
+    var customMapStyle: Array<MapStyleElement>?
+    var clusterConfig: ClusterConfig?
+    var mapPadding: EdgePadding
+    var showsTraffic: Boolean?
+    var showsBuildings: Boolean?
+    var showsCompass: Boolean?
+    var minZoom: Double
+    var maxZoom: Double
+    var darkMode: Boolean?
+    var userTrackingMode: UserTrackingMode?
+    var userLocationImage: String
+    var userLocationSize: Double
+    var userLocationAnchor: Point?
+
+    // MARK: - Callbacks
+
+    var onPress: ((MapPressEvent) -> Unit)?
+    var onLongPress: ((MapPressEvent) -> Unit)?
+    var onMapReadyCallback: (() -> Unit)?
+    var onRegionChange: ((RegionChangeEvent) -> Unit)?
+    var onRegionChangeComplete: ((RegionChangeEvent) -> Unit)?
+    var onMarkerPress: ((MarkerPressEvent) -> Unit)?
+    var onMarkerDragStart: ((MarkerDragEvent) -> Unit)?
+    var onMarkerDrag: ((MarkerDragEvent) -> Unit)?
+    var onMarkerDragEnd: ((MarkerDragEvent) -> Unit)?
+    var onClusterPress: ((ClusterPressEvent) -> Unit)?
+    var onPolylinePress: ((String) -> Unit)?
+    var onPolygonPress: ((String) -> Unit)?
+    var onCirclePress: ((String) -> Unit)?
+    var onError: ((MapError) -> Unit)?
+    var onMapIdle: (() -> Unit)?
+    var onUserLocationChange: ((UserLocationChangeEvent) -> Unit)?
+    var onUserTrackingModeChange: ((UserTrackingMode) -> Unit)?
+    var onUserLocationError: ((MapError) -> Unit)?
+
+    // MARK: - User Location
+
+    fun updateUserLocation(location: android.location.Location, heading: Float?)
+    fun setupCustomUserLocationMarker(context: Context)
+    /** Disable user location display and clean up location-related resources. */
+    fun disableUserLocation()
+
+    // MARK: - Camera
+
+    fun animateToRegion(region: Region, duration: Double?)
+    fun fitToCoordinates(coordinates: Array<Coordinate>, edgePadding: EdgePadding?, animated: Boolean?)
+    fun fitToSuppliedMarkers(markerIds: Array<String>, edgePadding: EdgePadding?, animated: Boolean?)
+    fun animateCamera(camera: Camera, duration: Double?)
+    fun setCamera(camera: Camera)
+    fun getCamera(): Camera
+    fun getMapBoundaries(): MapBoundaries?
+    fun pointForCoordinate(coordinate: Coordinate): Point
+    fun coordinateForPoint(point: Point): Coordinate
+    fun centerOnUserLocation()
+
+    // MARK: - Markers
+
+    fun addMarker(marker: MarkerData)
+    fun addMarkers(markers: Array<MarkerData>)
+    fun updateMarker(marker: MarkerData)
+    fun removeMarker(id: String)
+    fun clearMarkers()
+    fun selectMarker(id: String)
+    fun deselectMarker()
+
+    // MARK: - Clustering
+
+    fun setClusteringEnabled(enabled: Boolean)
+    fun refreshClusters()
+
+    // MARK: - Overlays
+
+    fun addPolyline(polyline: PolylineData)
+    fun updatePolyline(polyline: PolylineData)
+    fun removePolyline(id: String)
+    fun clearPolylines()
+
+    fun addPolygon(polygon: PolygonData)
+    fun updatePolygon(polygon: PolygonData)
+    fun removePolygon(id: String)
+    fun clearPolygons()
+
+    fun addCircle(circle: CircleData)
+    fun updateCircle(circle: CircleData)
+    fun removeCircle(id: String)
+    fun clearCircles()
+}