[compose] Update readme to reflect recent changes. (#2380)

extension-compose/README.md

@@ -13,16 +13,18 @@ Working examples of the Compose extension can be found in our [compose test appl
 - [Getting Started With Compose Extension](#getting-started-with-compose-extension)
 - [Tutorials](#tutorials)
   - [Place a Mapbox map to your app](#place-a-mapbox-map-to-your-app)
-  - [Setup the Map Style and set the initial camera position](#setup-the-map-style-and-set-the-initial-camera-position)
-  - [Use raw `MapboxMap` methods through `MapEffect`](#use-raw-mapboxmap-methods-through-mapeffect)
+  - [Setup the map style and set the initial camera position](#setup-the-map-style-and-set-the-initial-camera-position)
+  - [Use raw `MapboxMap` methods through `MapEffect` or `DisposableMapEffect`](#use-raw-mapboxmap-methods-through-mapeffect-or-disposablemapeffect)
   - [Use Camera Animation / Viewport APIs](#use-camera-animation--viewport-apis)
   - [Add Annotations to the map](#add-annotations-to-the-map)
     - [Add a single `CircleAnnotation` to the map](#add-a-single-circleannotation-to-the-map)
     - [Add multiple `CircleAnnotations` to the map in a group(more efficent for large number of annotations)](#add-multiple-circleannotations-to-the-map-in-a-groupmore-efficent-for-large-number-of-annotations)
     - [Add multiple `PointAnnotations` to the map as cluster(only supported for `PointAnnotation` and `CircleAnnotation`)](#add-multiple-pointannotations-to-the-map-as-clusteronly-supported-for-pointannotation-and-circleannotation)
     - [Add `ViewAnnotation` to the map](#add-viewannotation-to-the-map)
-  - [Configure plugin settings](#configure-plugin-settings)
-    - [gestures settings](#gestures-settings)
+  - [Configure Map ornaments(Compass, ScaleBar, Attribution, Logo)](#configure-map-ornamentscompass-scalebar-attribution-logo)
+  - [Gestures settings](#gestures-settings)
+  - [Work with runtime styling (work in progress)](#work-with-runtime-styling-work-in-progress)
+    - [Runtime styling with layers and sources](#runtime-styling-with-layers-and-sources)
 - [Compatibility with Maps SDK v11](#compatibility-with-maps-sdk-v11)
 
 ## Getting Started With Compose Extension
@@ -94,32 +96,33 @@ public class SimpleMapActivity : ComponentActivity() {
 }
 ```
 
-### Setup the Map Style and set the initial camera position
+### Setup the map style and set the initial camera position
 
-You can set the initial map style and the initial camera position by constructing the `MapInitOptions` using the context provided by the `MapInitOptionsFactory`. The `MapInitOptions` is the same object you would be using when constructing a `MapView`.
+You can set the initial map style with `MapStyle` composable function and the initial camera position by creating and remember `MapViewportState`.
 
 ```kotlin
   override fun onCreate(savedInstanceState: Bundle?) {
     super.onCreate(savedInstanceState)
     setContent {
       MapboxMap(
-        modifier = Modifier.fillMaxSize(),
-        mapInitOptionsFactory = { context ->
-          MapInitOptions(
-            context = context,
-            styleUri = Style.SATELLITE_STREETS,
-            cameraOptions = CameraOptions.Builder()
-              .center(Point.fromLngLat(24.9384, 60.1699))
-              .zoom(9.0)
-              .build()
-          )
+        Modifier.fillMaxSize(),
+        mapViewportState = remember {
+          MapViewportState().apply {
+            setCameraOptions {
+              center(Point.fromLngLat(24.9384, 60.1699))
+              zoom(9.0)
+            }
+          }
+        },
+        style = {
+          MapStyle(style = Style.SATELLITE_STREETS)
         }
       )
     }
   }
 ```
 
-### Use raw `MapboxMap` methods through `MapEffect`
+### Use raw `MapboxMap` methods through `MapEffect` or `DisposableMapEffect`
 
 Mapbox Compose Extension is built around the `MapView` in the base maps SDK. It's unlikely that we will be able to cover the full API surface in this wrapper, so we expose the reference to the raw `MapView` so that you can use all the API surface inside a `MapEffect`. 
 
@@ -343,11 +346,56 @@ The following example showcases adding `ViewAnnotation` that holds a `Button` to
   }
 ```
 
-### Configure plugin settings
+### Configure Map ornaments(Compass, ScaleBar, Attribution, Logo) 
 
-The plugin settings, e.g. `AttributionSettings`, `CompassSettings`, `GesturesSettings`, `LocationComponentSettings`, `LogoSettings`, `ScaleBarSettings` can be configured as `MutableState` to the `MapboxMap` composable functions.
+The Map ornaments are introduced as composable functions within dedicated scope and can be set to the MapboxMap composable function.
 
-#### gestures settings
+The following example showcases customising map ornaments:
+
+```kotlin
+MapboxMap(
+  modifier = Modifier.fillMaxSize(),
+  compass = {
+    // Original compass
+    Compass()
+    // Add another compass with customised position and image
+    Compass(
+      modifier = Modifier.padding(scaffoldPadding),
+      contentPadding = PaddingValues(0.dp),
+      alignment = Alignment.TopEnd,
+    ) {
+      Image(
+        painter = painterResource(id = R.drawable.my_compass),
+        alpha = 0.9f,
+        modifier = Modifier
+          .height(55.dp)
+          .width(55.dp),
+        contentDescription = "My customised compass"
+      )
+    }
+  },
+  scaleBar = {
+    // Change the ScaleBar primary color
+    ScaleBar(
+      modifier = Modifier.padding(scaffoldPadding),
+      primaryColor = color
+    )
+  },
+  attribution = {
+    // Change the Attribution color
+    Attribution(
+      modifier = Modifier.padding(scaffoldPadding),
+      iconColor = color
+    )
+  },
+  logo = {
+    // Change the Mapbox logo position
+    Logo(modifier = Modifier.padding(scaffoldPadding), alignment = Alignment.BottomEnd)
+  }
+)
+```
+
+### Gestures settings
 
 The following example showcases how to remember a `MutableState` of the `GesturesSettings` and update the settings through user interaction:
 
@@ -377,6 +425,79 @@ The following example showcases how to remember a `MutableState` of the `Gesture
   }
 ```
 
+### Work with runtime styling (work in progress)
+
+The map style can be set through `MapboxStyleComposable`, currently we expose following Style composable functions:
+
+* `GenericStyle` for all the available style features as weakly typed APIs, it has full flexibility to control any style/slot/positioned layers and style import configs, but alternative strongly typed APIs should be preferred for safety and convenience to use. 
+* `MapStyle` for simple loading style use cases if you don't need slots position your layer according to the layerIds defined in the style json.
+* `MapboxStandardStyle` for the default Mapbox Standard Style, it exposes available slots to position runtime-added layers and style import configs as strongly typed API. 
+
+#### Runtime styling with layers and sources
+
+The layers can be added to the style/map as `MapboxMapComposable` functions.
+
+* When added to the `slots` or `layerPositions` within the `MapboxStyleComposable`, the layer will be added to the style after the style is loaded.
+* When added to the content of `MapboxMap` composable function, the layer will be added to the map immediately as persistent layer.
+
+The sources are exposed as source state, which can be hoisted outside of the map and be shared with multiple layers. Please note the source state can not be shared across multiple map instances.
+
+Please also note that the layer id and source id are automatically generated and remembered by default, so that you can reuse the layers in different places without `layerId already exist` error.
+In case if you need the layer/source id later for other purpose, e.g. query rendered features, you can provide your own id and reuse later.  
+
+The following example showcases how to work with runtime styling with composable functions:
+
+```kotlin
+// Create a geoJsonSourceState to be used later with layers.
+val geoJsonSource: GeoJsonSourceState = rememberGeoJsonSourceState {
+  // Set the initial geoJsonData as a Point
+  data = GeoJSONData(Point.fromLngLat(0.0, 0.0))
+}
+MapboxMap(
+  style = {
+    // Load mapbox standard style
+    MapboxStandardStyle(
+      // Add a background layer to the 'top' slot of the standard style
+      topSlot = {
+        BackgroundLayer(
+          backgroundColor = BackgroundColor(Color.Yellow),
+          backgroundOpacity = BackgroundOpacity(0.3)
+        )
+      }
+    )
+  }
+) {
+  // Insert a circle layer with the given geoJsonSource, to display a background circle.
+  CircleLayer(
+    sourceState = geoJsonSource,
+    circleColor = CircleColor(Color.Cyan),
+    circleRadius = CircleRadius(50.0),
+    circleRadiusTransition = Transition(duration = 1000L)
+  )
+  // Insert a symbol layer with the same geoJsonSource, to display a text above the circle.
+  SymbolLayer(
+    sourceState = geoJsonSource,
+    textField = TextField("Hello"),
+    textColor = TextColor(Color.Black),
+    // Use expression to set the text size as data driven property
+    textSize = TextSize(
+      Expression.interpolate {
+        linear()
+        zoom()
+        stop {
+          literal(0.0)
+          literal(10.0)
+        }
+        stop {
+          literal(10.0)
+          literal(20.0)
+        }
+      }
+    )
+  )
+}
+```
+
 ## Compatibility with Maps SDK v11
 
 The Compose extension is released separately from the Android Maps SDK v11 and has a compileOnly dependency. When using the Compose extension you need to include a compatible Maps SDK. The feature compatibility checklist can be found below.
@@ -389,7 +510,11 @@ Basic Map rendering | ✅ | v11.0.0+
 Annotations support | ✅ | v11.0.0+
 ViewAnnotation support | ✅ | v11.0.0+
 MapViewportState support | ✅ | v11.0.0+
-Plugin setting(AttributionSettings, CompassSettings, GesturesSettings, LocationComponentSettings, LogoSettings, ScaleBarSettings) support | ✅ | v11.0.0+
+Gestures settings support | ✅ | v11.0.0+
 Access to raw MapView using MapEffect | ✅ | v11.0.0+
+Map ornament(Compass, ScaleBar, Attribution, Logo) support | ✅ | v11.3.0+
+Style composable function support | ✅ | v11.3.0+
+Style layer/source support | ✅ | v11.3.0+
+Style projection support | ✅ | v11.3.0+
 
 View [LICENSE.md](LICENSE.md) for all dependencies used by this extension.