docs: flesh out mkdocs pages (#94)

build.gradle.kts

@@ -30,10 +30,12 @@ mkdocs {
 }
 
 tasks.withType<MkdocsTask>().configureEach {
+  val releaseVersion = ext["base_tag"].toString().replace("v", "")
+  val snapshotVersion = "${ext["next_patch_version"]}-SNAPSHOT"
   extras.set(
     mapOf(
-      "next_patch_version" to ext["next_patch_version"].toString(),
-      "base_version" to ext["base_tag"].toString().replace("v", ""),
+      "release_version" to releaseVersion,
+      "snapshot_version" to snapshotVersion,
       "maplibre_ios_version" to libs.versions.maplibre.ios.get(),
     )
   )

demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/demos/AnimatedLayerDemo.kt

@@ -14,6 +14,8 @@ import dev.sargunv.maplibrecompose.compose.layer.LineLayer
 import dev.sargunv.maplibrecompose.compose.rememberCameraState
 import dev.sargunv.maplibrecompose.compose.source.rememberGeoJsonSource
 import dev.sargunv.maplibrecompose.core.CameraPosition
+import dev.sargunv.maplibrecompose.core.expression.LineCap
+import dev.sargunv.maplibrecompose.core.expression.LineJoin
 import dev.sargunv.maplibrecompose.demoapp.DEFAULT_STYLE
 import dev.sargunv.maplibrecompose.demoapp.Demo
 import dev.sargunv.maplibrecompose.demoapp.DemoScaffold
@@ -60,7 +62,15 @@ object AnimatedLayerDemo : Demo {
             id = "amtrak-routes",
             source = routeSource,
             color = const(animatedColor),
-            width = const(4.dp),
+            cap = const(LineCap.Round),
+            join = const(LineJoin.Round),
+            width =
+              interpolate(
+                type = exponential(const(1.2f)),
+                input = zoom(),
+                7 to const(1.75.dp),
+                20 to const(22.dp),
+              ),
           )
         }
       }

demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Interaction.kt

@@ -0,0 +1,85 @@
+@file:Suppress("unused", "UNUSED_ANONYMOUS_PARAMETER")
+
+package dev.sargunv.maplibrecompose.demoapp.docs
+
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.unit.dp
+import dev.sargunv.maplibrecompose.compose.ClickResult
+import dev.sargunv.maplibrecompose.compose.MaplibreMap
+import dev.sargunv.maplibrecompose.compose.rememberCameraState
+import dev.sargunv.maplibrecompose.core.CameraPosition
+import dev.sargunv.maplibrecompose.core.GestureSettings
+import dev.sargunv.maplibrecompose.core.OrnamentSettings
+import io.github.dellisd.spatialk.geojson.Position
+import kotlin.time.Duration.Companion.seconds
+
+@Composable
+fun Interaction() {
+  // -8<- [start:gesture-settings]
+  MaplibreMap(
+    gestureSettings =
+      GestureSettings(
+        isTiltGesturesEnabled = true,
+        isZoomGesturesEnabled = true, // (1)!
+        isRotateGesturesEnabled = true,
+        isScrollGesturesEnabled = true,
+      )
+  )
+  // -8<- [end:gesture-settings]
+
+  // -8<- [start:ornament-settings]
+  MaplibreMap(
+    ornamentSettings =
+      OrnamentSettings(
+        padding = PaddingValues(0.dp), // (1)!
+        isLogoEnabled = true, // (2)!
+        logoAlignment = Alignment.BottomStart, // (3)!
+        isAttributionEnabled = true, // (4)!
+        attributionAlignment = Alignment.BottomEnd,
+        isCompassEnabled = true, // (5)!
+        compassAlignment = Alignment.TopEnd,
+      )
+  )
+  // -8<- [end:ornament-settings]
+
+  // -8<- [start:camera]
+  val camera =
+    rememberCameraState(
+      firstPosition =
+        CameraPosition(target = Position(latitude = 45.521, longitude = -122.675), zoom = 13.0)
+    )
+  MaplibreMap(cameraState = camera)
+  // -8<- [end:camera]
+
+  // -8<- [start:camera-animate]
+  LaunchedEffect(Unit) {
+    camera.animateTo(
+      finalPosition =
+        camera.position.copy(target = Position(latitude = 47.607, longitude = -122.342)),
+      duration = 3.seconds,
+    )
+  }
+  // -8<- [end:camera-animate]
+
+  // -8<- [start:click-listeners]
+  MaplibreMap(
+    cameraState = camera,
+    onMapClick = { pos, offset ->
+      val features = camera.queryRenderedFeatures(offset)
+      if (features.isNotEmpty()) {
+        println("Clicked on ${features[0].json()}")
+        ClickResult.Consume // (1)!
+      } else {
+        ClickResult.Pass
+      }
+    },
+    onMapLongClick = { pos, offset ->
+      println("Long click at $pos")
+      ClickResult.Pass
+    },
+  )
+  // -8<- [end:click-listeners]
+}

demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Layers.kt

@@ -0,0 +1,91 @@
+@file:Suppress("unused")
+
+package dev.sargunv.maplibrecompose.demoapp.docs
+
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.unit.dp
+import dev.sargunv.maplibrecompose.compose.ClickResult
+import dev.sargunv.maplibrecompose.compose.MaplibreMap
+import dev.sargunv.maplibrecompose.compose.layer.Anchor
+import dev.sargunv.maplibrecompose.compose.layer.CircleLayer
+import dev.sargunv.maplibrecompose.compose.layer.LineLayer
+import dev.sargunv.maplibrecompose.compose.source.getBaseSource
+import dev.sargunv.maplibrecompose.compose.source.rememberGeoJsonSource
+import dev.sargunv.maplibrecompose.core.expression.LineCap
+import dev.sargunv.maplibrecompose.core.expression.LineJoin
+import dev.sargunv.maplibrecompose.demoapp.generated.Res
+import org.jetbrains.compose.resources.ExperimentalResourceApi
+
+@Composable
+@OptIn(ExperimentalResourceApi::class)
+fun Layers() {
+  // -8<- [start:simple]
+  MaplibreMap(styleUrl = "https://tiles.openfreemap.org/styles/liberty") {
+    val tiles = getBaseSource(id = "openmaptiles")
+    CircleLayer(id = "example", source = tiles, sourceLayer = "poi")
+  }
+  // -8<- [end:simple]
+
+  MaplibreMap {
+    val amtrakStations =
+      rememberGeoJsonSource(
+        id = "amtrak-stations",
+        dataUrl = Res.getUri("files/data/amtrak_stations.geojson"),
+      )
+
+    // -8<- [start:amtrak-1]
+    val amtrakRoutes =
+      rememberGeoJsonSource(
+        id = "amtrak-routes",
+        dataUrl = Res.getUri("files/data/amtrak_routes.geojson"),
+      )
+    LineLayer(
+      id = "amtrak-routes-casing",
+      source = amtrakRoutes,
+      color = const(Color.White),
+      width = const(6.dp),
+    )
+    LineLayer(
+      id = "amtrak-routes",
+      source = amtrakRoutes,
+      color = const(Color.Blue),
+      width = const(4.dp),
+    )
+    // -8<- [end:amtrak-1]
+
+    // -8<- [start:amtrak-2]
+    LineLayer(
+      id = "amtrak-routes",
+      source = amtrakRoutes,
+      cap = const(LineCap.Round),
+      join = const(LineJoin.Round),
+      color = const(Color.Blue),
+      width =
+        interpolate(
+          type = exponential(const(1.2f)),
+          input = zoom(),
+          5 to const(0.4.dp),
+          6 to const(0.7.dp),
+          7 to const(1.75.dp),
+          20 to const(22.dp),
+        ),
+    )
+    // -8<- [end:amtrak-2]
+
+    // -8<- [start:anchors]
+    Anchor.Above("road_motorway") { LineLayer(id = "amtrak-routes", source = amtrakRoutes) }
+    // -8<- [end:anchors]
+
+    // -8<- [start:interaction]
+    CircleLayer(
+      id = "amtrak-stations",
+      source = amtrakStations,
+      onClick = { features ->
+        println("Clicked on ${features[0].json()}")
+        ClickResult.Consume
+      },
+    )
+    // -8<- [end:interaction]
+  }
+}

demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Styling.kt

@@ -8,8 +8,8 @@ import dev.sargunv.maplibrecompose.compose.MaplibreMap
 import dev.sargunv.maplibrecompose.demoapp.generated.Res
 import org.jetbrains.compose.resources.ExperimentalResourceApi
 
-@OptIn(ExperimentalResourceApi::class)
 @Composable
+@OptIn(ExperimentalResourceApi::class)
 fun Styling() {
   // -8<- [start:simple]
   MaplibreMap(styleUrl = "https://tiles.openfreemap.org/styles/liberty")

docs/docs/getting-started.md

@@ -1,4 +1,4 @@
-# Getting Started
+# Getting started
 
 This documentation assumes you already have a Compose Multiplatform project set
 up. If you haven't already, follow [the official JetBrains
@@ -11,11 +11,11 @@ This library is published via [Maven Central][maven], and snapshot builds of
 
 === "Releases (Maven Central)"
 
-    The latest release is **v{{ gradle.base_version }}**. In your Gradle version catalog, add:
+    The latest release is **v{{ gradle.release_version }}**. In your Gradle version catalog, add:
 
     ```toml title="libs.versions.toml"
     [libraries]
-    maplibre-compose = { module = "dev.sargunv.maplibre-compose:maplibre-compose", version = "{{ gradle.base_version }}" }
+    maplibre-compose = { module = "dev.sargunv.maplibre-compose:maplibre-compose", version = "{{ gradle.release_version }}" }
     ```
 
 === "Snapshots (GitHub Packages)"
@@ -41,11 +41,11 @@ This library is published via [Maven Central][maven], and snapshot builds of
     }
     ```
 
-    The latest snapshot is **v{{ gradle.next_patch_version }}-SNAPSHOT**. In your Gradle version catalog, add:
+    The latest snapshot is **v{{ gradle.snapshot_version }}**. In your Gradle version catalog, add:
 
     ```toml title="libs.versions.toml"
     [libraries]
-    maplibre-compose = { module = "dev.sargunv.maplibre-compose:maplibre-compose", version = "{{ gradle.next_patch_version }}-SNAPSHOT" }
+    maplibre-compose = { module = "dev.sargunv.maplibre-compose:maplibre-compose", version = "{{ gradle.snapshot_version }}" }
     ```
 
 In your Gradle build script, add:

docs/docs/interaction.md

@@ -0,0 +1,60 @@
+# Interacting with the map
+
+## Gestures
+
+The map supports pan, zoom, rotate, and tilt gestures. Each of these can be
+enabled or disabled individually:
+
+```kotlin
+-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Interaction.kt:gesture-settings"
+```
+
+1. Includes pinch, double-tap, and double-tap-and-drag.
+
+## Ornaments
+
+Ornaments are UI elements that are displayed on the map, such as a compass or
+attribution button. They're implemented by the underlying MapLibre SDK, so may
+render differently on different platforms. You can control the visibility and
+position of these ornaments:
+
+```kotlin
+-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Interaction.kt:ornament-settings"
+```
+
+1. Insets the ornaments; useful if you have an edge-to-edge map or some UI
+   elements that cover part of the map.
+2. Displays a MapLibre logo
+3. Possible alignments are constrained by the underlying SDK. The four corners
+   are supported across platforms.
+4. Displays attribution defined in the map style.
+5. Displays a compass control when the map is rotated away from north.
+
+## Camera
+
+If you want to read or mutate the camera state, use `rememberCameraState()`. You
+can use this to set the start position of the map:
+
+```kotlin
+-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Interaction.kt:camera"
+```
+
+You can now use the `camera` reference to move the camera. For example,
+`CameraState` exposes a `suspend fun animateTo` to animate the camera to a new
+position:
+
+```kotlin
+-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Interaction.kt:camera-animate"
+```
+
+## Click listeners
+
+You can listen for clicks on the map. Given a click location, you can use camera
+state to query which features are present at that location:
+
+```kotlin
+-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Interaction.kt:click-listeners"
+```
+
+1. Consumes the click event, preventing it from propagating to the individual
+   layers' click listeners.