Add docs

docs/HeatmapCameraController.kt.md

@@ -0,0 +1,69 @@
+# HeatmapCameraController
+
+A lightweight controller that links map camera movements to a `HeatmapTileRenderer`. It listens
+for camera position changes and forwards the current zoom level to the renderer, allowing the
+heatmap's appearance to adapt dynamically as the user zooms.
+
+This controller implements `OverlayControllerInterface` but is focused solely on camera event
+handling. It does not manage data points, state, or click events.
+
+## Signature
+
+```kotlin
+class HeatmapCameraController(
+    private val renderer: HeatmapTileRenderer,
+) : OverlayControllerInterface<Unit, Unit, Unit>
+```
+
+## Constructor
+
+### `HeatmapCameraController(renderer)`
+
+Creates an instance of `HeatmapCameraController`.
+
+**Parameters**
+
+- `renderer`
+    - Type: `HeatmapTileRenderer`
+    - Description: **Required.** The heatmap renderer to update with camera zoom changes.
+
+## Methods
+
+### `onCameraChanged`
+
+Called by the map framework whenever the camera position changes. Extracts the zoom level from
+the new camera position and passes it to the `HeatmapTileRenderer`.
+
+**Signature**
+
+```kotlin
+override suspend fun onCameraChanged(mapCameraPosition: MapCameraPosition)
+```
+
+**Parameters**
+
+- `mapCameraPosition`
+    - Type: `MapCameraPosition`
+    - Description: The new position and zoom level of the map camera.
+
+## Interface Methods (no-op)
+
+The following methods from `OverlayControllerInterface` are implemented as no-ops. This
+controller's scope is limited to camera handling.
+
+- `add(data: List<Unit>)` — Does not add data to the overlay.
+- `update(state: Unit)` — Does not update any state.
+- `clear()` — Does not clear any data.
+- `find(position: GeoPointInterface)` — Always returns `null`.
+- `destroy()` — No native resources to clean up.
+
+## Example
+
+```kotlin
+val renderer = HeatmapTileRenderer()
+val cameraController = HeatmapCameraController(renderer)
+
+// The controller is registered with the map internally by HeatmapOverlay.
+// When the user zooms or pans, onCameraChanged is called automatically,
+// updating the renderer with the new zoom level.
+```

docs/HeatmapGradient.kt.md

@@ -0,0 +1,154 @@
+# HeatmapGradientStop
+
+A data class that represents a single color stop within a `HeatmapGradient`. Each stop pairs a
+relative position with a color.
+
+## Signature
+
+```kotlin
+data class HeatmapGradientStop(
+    val position: Double,
+    val color: Int,
+)
+```
+
+## Parameters
+
+- `position`
+    - Type: `Double`
+    - Description: The relative position of the color stop. `0.0` is the start and `1.0` is the
+      end of the gradient.
+- `color`
+    - Type: `Int`
+    - Description: The ARGB color integer for this stop. Use `android.graphics.Color` to create
+      this value.
+
+## Example
+
+```kotlin
+import android.graphics.Color
+
+// A stop at 50% of the gradient with a yellow color
+val yellowStop = HeatmapGradientStop(position = 0.5, color = Color.YELLOW)
+
+// A stop at the beginning with a semi-transparent blue color
+val blueStop = HeatmapGradientStop(position = 0.0, color = Color.argb(128, 0, 0, 255))
+```
+
+---
+
+# HeatmapGradient
+
+A class that defines the color gradient used to render the heatmap. Constructed from a list of
+`HeatmapGradientStop` objects.
+
+## Signature
+
+```kotlin
+class HeatmapGradient(stops: List<HeatmapGradientStop>)
+```
+
+## Description
+
+Upon creation, the gradient validates and sorts the provided stops by `position`.
+
+**Constructor validation:**
+- The list of stops must not be empty.
+- The `position` of each stop must be within the inclusive range `[0.0, 1.0]`.
+
+An `IllegalArgumentException` is thrown if these conditions are not met.
+
+## Parameters
+
+- `stops`
+    - Type: `List<HeatmapGradientStop>`
+    - Description: **Required.** One or more `HeatmapGradientStop` objects that define the
+      gradient. The list is sorted by `position` internally.
+
+## Properties
+
+- `stops`
+    - Type: `List<HeatmapGradientStop>`
+    - Description: The validated and sorted list of gradient stops.
+
+## Methods
+
+### `colors()`
+
+Returns an array of color integers from the gradient stops, sorted by position.
+
+**Signature**
+
+```kotlin
+fun colors(): IntArray
+```
+
+**Returns**
+
+- Type: `IntArray`
+- Description: An array of ARGB color integers sorted by stop position. Useful for APIs that
+  require a simple array of colors.
+
+## Companion Object
+
+### `DEFAULT`
+
+A predefined gradient that transitions from green (at position `0.2`) to red (at position `1.0`).
+
+**Signature**
+
+```kotlin
+val DEFAULT: HeatmapGradient
+```
+
+## Example
+
+```kotlin
+import android.graphics.Color
+
+// Create a custom three-color gradient (blue → yellow → red)
+val customGradient = HeatmapGradient(
+    stops = listOf(
+        HeatmapGradientStop(position = 0.0, color = Color.BLUE),
+        HeatmapGradientStop(position = 0.5, color = Color.YELLOW),
+        HeatmapGradientStop(position = 1.0, color = Color.RED),
+    )
+)
+
+// Use the predefined default gradient
+val defaultGradient = HeatmapGradient.DEFAULT
+```
+
+---
+
+# HeatmapDefaults
+
+A singleton object that provides default constant values for heatmap properties.
+
+## Signature
+
+```kotlin
+object HeatmapDefaults
+```
+
+## Properties
+
+- `DEFAULT_RADIUS_PX`
+    - Type: `Int`
+    - Value: `20`
+    - Description: The default radius in pixels for each data point on the heatmap.
+- `DEFAULT_OPACITY`
+    - Type: `Double`
+    - Value: `0.7`
+    - Description: The default opacity of the heatmap layer (`0.0` = transparent, `1.0` = opaque).
+- `DEFAULT_MAX_ZOOM`
+    - Type: `Int`
+    - Value: `22`
+    - Description: The default maximum map zoom level at which the heatmap is rendered.
+
+## Example
+
+```kotlin
+val radiusPx = userProvidedRadius ?: HeatmapDefaults.DEFAULT_RADIUS_PX
+val opacity = userProvidedOpacity ?: HeatmapDefaults.DEFAULT_OPACITY
+```

docs/HeatmapOverlay.kt.md

@@ -0,0 +1,145 @@
+# HeatmapOverlay (State-based)
+
+A convenience overload that uses a `HeatmapOverlayState` object to configure the heatmap. This is
+the recommended approach when you need to manage the heatmap's properties as a single observable
+state object.
+
+## Signature
+
+```kotlin
+@Composable
+fun MapViewScope.HeatmapOverlay(
+    state: HeatmapOverlayState,
+    content: @Composable () -> Unit,
+)
+```
+
+## Description
+
+Renders a heatmap layer configured by the provided `state` object. Data points are defined by
+`HeatmapPoint` composables placed inside the `content` block.
+
+## Parameters
+
+- `state`
+    - Type: `HeatmapOverlayState`
+    - Description: **Required.** The state object holding the heatmap configuration, including
+      `radiusPx`, `opacity`, `gradient`, `maxIntensity`, and `weightProvider`.
+- `content`
+    - Type: `@Composable () -> Unit`
+    - Description: **Required.** A composable lambda where `HeatmapPoint` children are placed.
+
+## Example
+
+```kotlin
+@Composable
+fun HeatmapWithStateExample() {
+    val heatmapState = remember {
+        HeatmapOverlayState(
+            radiusPx = 35,
+            opacity = 0.75,
+        )
+    }
+
+    GoogleMapView(state = mapViewState) {
+        HeatmapOverlay(state = heatmapState) {
+            HeatmapPoint(position = GeoPoint(34.0522, -118.2437), weight = 0.8)
+            HeatmapPoint(position = GeoPoint(40.7128, -74.0060))
+        }
+    }
+}
+```
+
+---
+
+# HeatmapOverlay (Detailed)
+
+An overload that provides fine-grained control over all heatmap properties directly as parameters.
+Useful for static configurations or when you prefer to manage individual properties.
+
+## Signature
+
+```kotlin
+@Composable
+fun MapViewScope.HeatmapOverlay(
+    radiusPx: Int = HeatmapDefaults.DEFAULT_RADIUS_PX,
+    opacity: Double = HeatmapDefaults.DEFAULT_OPACITY,
+    gradient: HeatmapGradient = HeatmapGradient.DEFAULT,
+    maxIntensity: Double? = null,
+    weightProvider: (HeatmapPointState) -> Double = { state -> state.weight },
+    tileSize: Int = HeatmapTileRenderer.DEFAULT_TILE_SIZE,
+    trackPointUpdates: Boolean = false,
+    disableTileServerCache: Boolean = false,
+    content: @Composable () -> Unit,
+)
+```
+
+## Description
+
+Creates a heatmap layer by rendering data points onto tiles and displaying them as a raster
+overlay. Offers detailed configuration options for appearance and performance.
+
+## Parameters
+
+- `radiusPx`
+    - Type: `Int`
+    - Default: `HeatmapDefaults.DEFAULT_RADIUS_PX` (`20`)
+    - Description: The radius of influence for each data point in pixels. Larger values create a
+      smoother, more blurry heatmap.
+- `opacity`
+    - Type: `Double`
+    - Default: `HeatmapDefaults.DEFAULT_OPACITY` (`0.7`)
+    - Description: The opacity of the heatmap layer (`0.0` = fully transparent, `1.0` = opaque).
+- `gradient`
+    - Type: `HeatmapGradient`
+    - Default: `HeatmapGradient.DEFAULT`
+    - Description: The color gradient used to render the heatmap based on data intensity.
+- `maxIntensity`
+    - Type: `Double?`
+    - Default: `null`
+    - Description: The intensity value that maps to the hottest color in the gradient. If `null`,
+      the maximum is calculated from the data. Set a fixed value for a consistent color scale
+      across different datasets.
+- `weightProvider`
+    - Type: `(HeatmapPointState) -> Double`
+    - Default: `{ state -> state.weight }`
+    - Description: A function to extract a numerical weight from a `HeatmapPointState`. Allows
+      custom logic to determine the influence of each point.
+- `tileSize`
+    - Type: `Int`
+    - Default: `HeatmapTileRenderer.DEFAULT_TILE_SIZE` (`512`)
+    - Description: The size of the underlying raster tiles in pixels.
+- `trackPointUpdates`
+    - Type: `Boolean`
+    - Default: `false`
+    - Description: If `true`, re-renders the heatmap when properties of existing `HeatmapPoint`s
+      (e.g., `weight`) change. If `false`, only updates when points are added or removed.
+      Enabling this may impact performance with large datasets.
+- `disableTileServerCache`
+    - Type: `Boolean`
+    - Default: `false`
+    - Description: If `true`, disables the internal tile server's in-memory cache. Primarily for
+      debugging; can degrade rendering performance.
+- `content`
+    - Type: `@Composable () -> Unit`
+    - Description: **Required.** A composable lambda where `HeatmapPoint` children are placed.
+
+## Example
+
+```kotlin
+@Composable
+fun DetailedHeatmapExample() {
+    // Replace "MapView" with semantic SDK mapview such as "GoogleMapView"
+    MapView(state = mapViewState) {
+        HeatmapOverlay(
+            radiusPx = 50,
+            opacity = 0.8,
+            gradient = HeatmapGradient.DEFAULT,
+            trackPointUpdates = false,
+        ) {
+            HeatmapPoint(position = GeoPoint(40.7128, -74.0060), weight = 1.0)
+            HeatmapPoint(position = GeoPoint(34.0522, -118.2437), weight = 0.7)
+        }
+    }
+}
+```