@lugg/maps 1.0.0-beta.9 → 1.1.0

package/README.md

@@ -2,82 +2,28 @@
 
 Universal maps for your React Native apps 📍
 
-<img alt="@lugg/maps" src="docs/preview.gif" width="720" />
+<img alt="@lugg/maps" src="docs/public/preview.gif" width="720" />
 
-> [!IMPORTANT]
-> This library is currently under heavy development. APIs may change without notice.
+## Documentation
 
-## Installation
+Full documentation lives at **[maps.lodev09.com](https://maps.lodev09.com)**.
 
-```sh
-npm install @lugg/maps
-```
-
-### Expo
-
-Add the plugin to your `app.json`:
-
-```json
-{
-  "expo": {
-    "plugins": [
-      [
-        "@lugg/maps",
-        {
-          "iosGoogleMapsApiKey": "YOUR_IOS_API_KEY",
-          "androidGoogleMapsApiKey": "YOUR_ANDROID_API_KEY"
-        }
-      ]
-    ]
-  }
-}
-```
-
-### Bare React Native
-
-#### iOS
-
-Add your Google Maps API key to `AppDelegate.swift`:
-
-```swift
-import GoogleMaps
-
-// In application(_:didFinishLaunchingWithOptions:)
-GMSServices.provideAPIKey("YOUR_API_KEY")
-```
-
-#### Android
+- [Installation](https://maps.lodev09.com/installation) - Expo, bare React Native, and web setup
+- [Usage](https://maps.lodev09.com/usage) - Render your first map
+- [MapView](https://maps.lodev09.com/components/map-view) - Props, camera methods, events, static maps
+- [Marker](https://maps.lodev09.com/components/marker) - Custom views, callouts, dragging
+- [Polyline](https://maps.lodev09.com/components/polyline), [Polygon](https://maps.lodev09.com/components/polygon), [Circle](https://maps.lodev09.com/components/circle) - Shapes
+- [GeoJson](https://maps.lodev09.com/components/geojson), [GroundOverlay](https://maps.lodev09.com/components/ground-overlay), [TileOverlay](https://maps.lodev09.com/components/tile-overlay) - Data and overlays
+- [Types](https://maps.lodev09.com/types) - `Coordinate`, `Point`, `EdgeInsets`
 
-Add your Google Maps API key to `AndroidManifest.xml`:
+## Quick start
 
-```xml
-<application>
-  <meta-data
-    android:name="com.google.android.geo.API_KEY"
-    android:value="YOUR_API_KEY" />
-</application>
-```
-
-### Web
-
-Wrap your app with `MapProvider` and pass your Google Maps API key:
-
-```tsx
-import { MapProvider } from '@lugg/maps';
-
-function App() {
-  return (
-    <MapProvider apiKey="YOUR_WEB_API_KEY">
-      {/* Your app */}
-    </MapProvider>
-  );
-}
+```sh
+npm install @lugg/maps
 ```
 
-## Usage
-
 ```tsx
-import { MapView, Marker, Polyline, Polygon } from '@lugg/maps';
+import { MapView, Marker } from '@lugg/maps';
 
 <MapView
   style={{ flex: 1 }}
@@ -89,41 +35,10 @@ import { MapView, Marker, Polyline, Polygon } from '@lugg/maps';
     coordinate={{ latitude: 37.7749, longitude: -122.4194 }}
     title="San Francisco"
   />
-  <Polyline
-    coordinates={[
-      { latitude: 37.7749, longitude: -122.4194 },
-      { latitude: 37.8049, longitude: -122.4094 },
-    ]}
-    strokeWidth={3}
-  />
-  <Polygon
-    coordinates={[
-      { latitude: 37.784, longitude: -122.428 },
-      { latitude: 37.784, longitude: -122.422 },
-      { latitude: 37.779, longitude: -122.422 },
-      { latitude: 37.779, longitude: -122.428 },
-    ]}
-    fillColor="rgba(66, 133, 244, 0.3)"
-    strokeColor="#4285F4"
-    strokeWidth={2}
-  />
 </MapView>
 ```
 
-## Components
-
-- [MapView](docs/MAPVIEW.md) - Main map component
-- [Marker](docs/MARKER.md) - Map markers with callout support
-- [Polyline](docs/POLYLINE.md) - Draw lines on the map
-- [Polygon](docs/POLYGON.md) - Draw filled shapes on the map
-- [Circle](docs/CIRCLE.md) - Draw circular overlays on the map
-- [GeoJson](docs/GEOJSON.md) - Render GeoJSON data on the map
-- [GroundOverlay](docs/GROUND_OVERLAY.md) - Display images on the map
-- [TileOverlay](docs/TILE_OVERLAY.md) - Display custom tile layers on the map
-
-## Types
-
-See [Types](docs/TYPES.md) for common type definitions (`Coordinate`, `Point`, `EdgeInsets`).
+Google Maps needs an API key on every platform. See [Installation](https://maps.lodev09.com/installation) for Expo, iOS, Android, and web setup.
 
 ## Contributing
 

package/android/src/main/java/com/luggmaps/LuggCalloutView.kt

@@ -4,6 +4,7 @@ import android.content.Context
 import android.graphics.Bitmap
 import android.graphics.Canvas
 import android.view.View
+import android.view.accessibility.AccessibilityEvent
 import androidx.core.graphics.createBitmap
 import androidx.core.view.isNotEmpty
 import com.facebook.react.uimanager.PointerEvents
@@ -51,6 +52,10 @@ class LuggCalloutView(context: Context) : ReactViewGroup(context) {
 
   override fun getChildAt(index: Int): View? = contentView.getChildAt(index)
 
+  // no-op: avoid accessibility traversal of detached callout children
+  override fun addChildrenForAccessibility(outChildren: ArrayList<View>) {}
+  override fun dispatchPopulateAccessibilityEvent(event: AccessibilityEvent): Boolean = false
+
   fun createContentBitmap(): Bitmap? {
     var maxWidth = 0
     var maxHeight = 0

package/android/src/main/java/com/luggmaps/LuggMapView.kt

@@ -1,6 +1,7 @@
 package com.luggmaps
 
 import android.annotation.SuppressLint
+import android.content.res.Configuration
 import android.view.View
 import android.view.View.VISIBLE
 import com.facebook.react.uimanager.ThemedReactContext
@@ -64,6 +65,8 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
   private var scrollEnabled: Boolean = true
   private var rotateEnabled: Boolean = true
   private var pitchEnabled: Boolean = true
+  private var compassEnabled: Boolean = true
+  private var staticMode: Boolean = false
   private var userLocationEnabled: Boolean = false
   private var userLocationButtonEnabled: Boolean = false
   private var poiEnabled: Boolean = true
@@ -128,17 +131,22 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
 
   // region Provider Initialization
 
-  private fun initializeProvider() {
+  private fun initializeProvider(latitude: Double = initialLatitude, longitude: Double = initialLongitude, zoom: Float = initialZoom) {
     if (provider != null || mapWrapperView == null) return
 
+    if (staticMode) {
+      applyStaticPlaceholder()
+    }
+
     val google = GoogleMapProvider(context)
     google.mapId = mapId
+    google.staticMode = staticMode
     google.delegate = this
     provider = google
 
     applyProps()
 
-    google.initializeMap(mapWrapperView!!, initialLatitude, initialLongitude, initialZoom)
+    google.initializeMap(mapWrapperView!!, latitude, longitude, zoom)
 
     // Flush children mounted before provider was created
     for (i in 0 until childCount) {
@@ -153,6 +161,23 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
     }
   }
 
+  // Shown while the map loads, until the map covers it
+  private fun applyStaticPlaceholder() {
+    // A user-provided background acts as the placeholder
+    if (background != null) return
+
+    val isDark = when (theme) {
+      "dark" -> true
+
+      "light" -> false
+
+      else ->
+        (context.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK) ==
+          Configuration.UI_MODE_NIGHT_YES
+    }
+    mapWrapperView?.setBackgroundColor(if (isDark) COLOR_PLACEHOLDER_DARK else COLOR_PLACEHOLDER_LIGHT)
+  }
+
   // endregion
 
   // region MapProviderDelegate
@@ -186,6 +211,7 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
     provider?.setScrollEnabled(scrollEnabled)
     provider?.setRotateEnabled(rotateEnabled)
     provider?.setPitchEnabled(pitchEnabled)
+    provider?.setCompassEnabled(compassEnabled)
     provider?.setUserLocationEnabled(userLocationEnabled)
     provider?.setUserLocationButtonEnabled(userLocationButtonEnabled)
     provider?.setMapType(mapType)
@@ -243,6 +269,16 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
     provider?.setPitchEnabled(enabled)
   }
 
+  fun setCompassEnabled(enabled: Boolean) {
+    if (compassEnabled == enabled) return
+    compassEnabled = enabled
+    provider?.setCompassEnabled(enabled)
+  }
+
+  fun setStaticMode(enabled: Boolean) {
+    staticMode = enabled
+  }
+
   fun setUserLocationEnabled(enabled: Boolean) {
     if (userLocationEnabled == enabled) return
     userLocationEnabled = enabled
@@ -335,5 +371,23 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
     provider?.fitCoordinates(coordinates, edgeInsetsTop, edgeInsetsLeft, edgeInsetsBottom, edgeInsetsRight, duration)
   }
 
+  fun reload() {
+    val current = provider ?: return
+    val latitude = current.cameraLatitude
+    val longitude = current.cameraLongitude
+    val zoom = current.cameraZoom
+
+    current.destroy()
+    provider = null
+    if (isAttachedToWindow) {
+      initializeProvider(latitude, longitude, zoom)
+    }
+  }
+
   // endregion
+
+  companion object {
+    private const val COLOR_PLACEHOLDER_LIGHT = 0xFFF2F2F7.toInt()
+    private const val COLOR_PLACEHOLDER_DARK = 0xFF2C2C2E.toInt()
+  }
 }

package/android/src/main/java/com/luggmaps/LuggMapViewManager.kt

@@ -132,6 +132,20 @@ class LuggMapViewManager :
     view.setPitchEnabled(value)
   }
 
+  @ReactProp(name = "compassEnabled", defaultBoolean = true)
+  override fun setCompassEnabled(view: LuggMapView, value: Boolean) {
+    view.setCompassEnabled(value)
+  }
+
+  @ReactProp(name = "staticMode", defaultBoolean = false)
+  override fun setStaticMode(view: LuggMapView, value: Boolean) {
+    view.setStaticMode(value)
+  }
+
+  // iOS only - lite mode doesn't need snapshot caching
+  @ReactProp(name = "staticKey")
+  override fun setStaticKey(view: LuggMapView, value: String?) = Unit
+
   @ReactProp(name = "userLocationEnabled", defaultBoolean = false)
   override fun setUserLocationEnabled(view: LuggMapView, value: Boolean) {
     view.setUserLocationEnabled(value)
@@ -259,6 +273,10 @@ class LuggMapViewManager :
     )
   }
 
+  override fun reload(view: LuggMapView) {
+    view.reload()
+  }
+
   companion object {
     const val NAME = "LuggMapView"
   }

package/android/src/main/java/com/luggmaps/LuggMapWrapperView.kt

@@ -2,6 +2,7 @@ package com.luggmaps
 
 import android.annotation.SuppressLint
 import android.view.MotionEvent
+import android.view.View
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.views.view.ReactViewGroup
 
@@ -10,11 +11,38 @@ class LuggMapWrapperView(context: ThemedReactContext) : ReactViewGroup(context)
 
   var touchEventHandler: ((MotionEvent) -> Unit)? = null
 
+  // React Native never runs an Android layout pass on Yoga-managed views, so
+  // a child's requestLayout (e.g. a lite mode MapView displaying its bitmap
+  // once loaded) would otherwise never result in a measure/layout. Live maps
+  // don't need this - their GL surface renders continuously once sized.
+  var relayoutChildOnRequest: Boolean = false
+
+  // Invoked on layout once the view has a non-zero size, so the map
+  // provider can create a map sized to the view
+  var onLayoutReady: (() -> Unit)? = null
+
+  private val measureAndLayoutChild = Runnable { layoutChild(width, height) }
+
   override fun dispatchTouchEvent(event: MotionEvent): Boolean {
     touchEventHandler?.invoke(event)
     return super.dispatchTouchEvent(event)
   }
 
+  override fun requestLayout() {
+    super.requestLayout()
+    if (relayoutChildOnRequest) {
+      post(measureAndLayoutChild)
+    }
+  }
+
+  override fun onViewAdded(child: View) {
+    super.onViewAdded(child)
+    // A replacement map needs sizing even when Yoga's layout is unchanged.
+    if (indexOfChild(child) == 0) {
+      layoutChild(width, height)
+    }
+  }
+
   override fun onLayout(
     changed: Boolean,
     left: Int,
@@ -23,8 +51,14 @@ class LuggMapWrapperView(context: ThemedReactContext) : ReactViewGroup(context)
     bottom: Int
   ) {
     super.onLayout(changed, left, top, right, bottom)
-    val w = right - left
-    val h = bottom - top
+    layoutChild(right - left, bottom - top)
+    if (right - left > 0 && bottom - top > 0) {
+      onLayoutReady?.invoke()
+    }
+  }
+
+  private fun layoutChild(w: Int, h: Int) {
+    if (w <= 0 || h <= 0) return
     getChildAt(0)?.let {
       it.measure(
         MeasureSpec.makeMeasureSpec(w, MeasureSpec.EXACTLY),

package/android/src/main/java/com/luggmaps/LuggMarkerView.kt

@@ -3,12 +3,13 @@ package com.luggmaps
 import android.content.Context
 import android.graphics.Canvas
 import android.view.View
+import android.view.accessibility.AccessibilityEvent
 import androidx.core.graphics.createBitmap
 import androidx.core.view.isNotEmpty
 import com.facebook.react.views.view.ReactViewGroup
-import com.google.android.gms.maps.model.AdvancedMarker
 import com.google.android.gms.maps.model.BitmapDescriptor
 import com.google.android.gms.maps.model.BitmapDescriptorFactory
+import com.google.android.gms.maps.model.Marker
 import com.luggmaps.events.MarkerDragEvent
 import com.luggmaps.events.MarkerPressEvent
 import com.luggmaps.extensions.dispatchEvent
@@ -37,7 +38,7 @@ class LuggMarkerView(context: Context) : ReactViewGroup(context) {
     private set
 
   var delegate: LuggMarkerViewDelegate? = null
-  var marker: AdvancedMarker? = null
+  var marker: Marker? = null
 
   var anchorX: Float = 0.5f
     private set
@@ -218,6 +219,10 @@ class LuggMarkerView(context: Context) : ReactViewGroup(context) {
     return null
   }
 
+  // no-op: avoid accessibility traversal of detached marker children
+  override fun addChildrenForAccessibility(outChildren: ArrayList<View>) {}
+  override fun dispatchPopulateAccessibilityEvent(event: AccessibilityEvent): Boolean = false
+
   override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
     super.onSizeChanged(w, h, oldw, oldh)
     didLayout = false

package/android/src/main/java/com/luggmaps/LuggPolylineView.kt

@@ -8,6 +8,7 @@ import com.google.android.gms.maps.model.Polyline
 
 interface LuggPolylineViewDelegate {
   fun polylineViewDidUpdate(polylineView: LuggPolylineView)
+  fun polylineViewDidDrop(polylineView: LuggPolylineView)
 }
 
 data class AnimatedOptions(val duration: Long = 2150L, val easing: String = "linear", val trailLength: Float = 1f, val delay: Long = 0L)
@@ -67,8 +68,8 @@ class LuggPolylineView(context: Context) : ReactViewGroup(context) {
   }
 
   fun onDropViewInstance() {
+    delegate?.polylineViewDidDrop(this)
     delegate = null
-    polyline?.remove()
     polyline = null
   }
 }