docs: improve docs

Author: benoit-ctrl

CONTRIBUTING.md

@@ -11,8 +11,8 @@
 ## Example app
 The recommended way to develop is building the example app. Example app links in `@rnmapbox/maps` from parent directory. JavaScript changes for example in `src/components/MapView.tsx`, will be applied automatically.
 Some notes about example app:
-- example app are both for demonstrating how to use differenc components, so examples should be simple (and not all of them should be typescript)
-- example app can contains screens designed from through testing of a component, but it should be separate for simple components demonstrating the use of components
+- example app are both for demonstrating how to use different components, so examples should be simple (and not all of them should be typescript)
+- example app can contain screens designed for thorough testing of a component, but it should be separate from simple examples demonstrating the use of components
 
 ### Example app configurations:
 
@@ -74,7 +74,7 @@ The full documentation generation process looks like this:
 
   The source is `style-spec/v8.json` and documentation at `src/*.ts`
 
-  This step runs by `yarn generate` and checked if up-todate by CI.
+  This step runs by `yarn generate` and checked if up-to-date by CI.
 
 2.) `docs/examples.json`  generated by `jest __tests__/dumpExamplesJson.ts`.
 
@@ -83,9 +83,9 @@ The full documentation generation process looks like this:
   npx jest __tests__/dumpExamplesJson.ts
   ```
 
-  This step runs by `yarn generate` and checked if up-todate by CI.
+  This step runs by `yarn generate` and checked if up-to-date by CI.
 
-3.) `<doc-site>/screenhsots`. Grab screenshots from examples (needs `docs/examples.json`)
+3.) `<doc-site>/screenshots`. Grab screenshots from examples (needs `docs/examples.json`)
 
   We use detox tests to capture screenshots of examples
   ```
@@ -96,15 +96,15 @@ The full documentation generation process looks like this:
 
   This step is run manually for now
 
-4.) `<doc-site>/docs/components` Generate component/api documentation (into the docosaurus site)
+4.) `<doc-site>/docs/components` Generate component/api documentation (into the Docusaurus site)
 
   ```
   node scripts/doc-generate.mjs
   ```
 
   Runs when `main` is changed by `update-docs` gh action workflow
 
-5.) `<doc-site>/docs/exmaples` Generate example docs (into the docosaurus site)
+5.) `<doc-site>/docs/examples` Generate example docs (into the Docusaurus site)
 
   ```
   bun scripts/example-docs.ts

docs/Camera.md

@@ -125,7 +125,9 @@ The easing or path the camera uses to animate to a new configuration.
 ```tsx
 boolean
 ```
-Whether the map orientation follows the user location.
+Whether the map camera follows the user's location. When enabled, the camera centers
+on the user's position and `centerCoordinate` is ignored.
+For more advanced location tracking, consider using {@link Viewport} with `followPuck` state instead.
 
 
   
@@ -134,7 +136,10 @@ Whether the map orientation follows the user location.
 ```tsx
 UserTrackingMode
 ```
-The mode used to track the user location on the map.
+The mode used to track the user location on the map. Only takes effect when `followUserLocation` is true.
+ - `normal`: the camera follows the user's position without rotating the map
+ - `compass`: the camera rotates to match the device's compass heading (direction the device is facing)
+ - `course`: the camera rotates to match the user's direction of travel
 
 
   
@@ -143,7 +148,8 @@ The mode used to track the user location on the map.
 ```tsx
 number
 ```
-The zoom level used when following the user location.
+The zoom level used when following the user location. If not specified,
+the current zoom level is preserved.
 
 [Show Map](../examples/Map/ShowMap)
   
@@ -152,7 +158,8 @@ The zoom level used when following the user location.
 ```tsx
 number
 ```
-The pitch used when following the user location.
+The pitch (tilt) used when following the user location, in degrees. If not specified,
+the current pitch is preserved.
 
 
   
@@ -161,7 +168,8 @@ The pitch used when following the user location.
 ```tsx
 number
 ```
-The heading used when following the user location.
+The heading (bearing) used when following the user location, in degrees. If not specified,
+the heading is determined by `followUserMode`.
 
 
   
@@ -170,7 +178,8 @@ The heading used when following the user location.
 ```tsx
 Partial
 ```
-The padding used to position the user location when following.
+Padding in points that offsets the user's centered position from the edges of the map view.
+Useful for keeping the user location visible when UI elements overlap the map.
 
 
   

docs/CustomLocationProvider.md

@@ -8,7 +8,17 @@ import { CustomLocationProvider } from '@rnmapbox/maps';
 CustomLocationProvider
 
 ```
+Overrides the native location provider with custom coordinates and heading.
 
+Useful for simulating locations during development, integrating an external
+positioning sensor, or writing tests. Must be a child of `MapView`.
+Use together with `LocationPuck` to display the custom position on the map.
+
+@example
+<MapView>
+  <CustomLocationProvider coordinate={[-73.9857, 40.7484]} heading={90} />
+  <LocationPuck puckBearingEnabled={true} puckBearing="heading" />
+</MapView>
 
 ## props
 
@@ -18,7 +28,7 @@ CustomLocationProvider
 ```tsx
 Position
 ```
-longitude and latitude to use for the custom location provider that gets applied to the NativeUserLocation
+The position as a `[longitude, latitude]` pair, transmitted to the native puck as the current location.
 
 
 
@@ -27,7 +37,8 @@ longitude and latitude to use for the custom location provider that gets applied
 ```tsx
 number
 ```
-heading/bearing to use for custom location provider that gets applied to the NativeUserLocation
+Heading in degrees (0 = north, 90 = east, 180 = south, 270 = west).
+Controls the rotation of the location puck when `puckBearingEnabled` is true on the `LocationPuck`.
 
 
 

docs/LocationPuck.md

@@ -8,7 +8,11 @@ import { LocationPuck } from '@rnmapbox/maps';
 LocationPuck
 
 ```
-Renders a puck on the map that shows the device's current location.
+Renders the native Mapbox location puck on the map to show the device's current location.
+
+This is the recommended way to display user location, as it leverages the native
+Mapbox location indicator with smooth animations and built-in bearing tracking.
+Must be a child of `MapView`.
 
 ## props
 
@@ -108,7 +112,7 @@ The size of the images, as a scale factor applied to the size of the specified i
 ```tsx
 | {
     /**
-     * Flag determining whether the pulsing circle animation.
+     * Flag determining whether the pulsing circle animation is enabled.
      */
     isEnabled?: boolean;
 
@@ -119,14 +123,17 @@ The size of the images, as a scale factor applied to the size of the specified i
 
     /**
      * Circle radius configuration for the pulsing circle animation.
-     *  - accuracy:  Pulsing circle animates with the `horizontalAccuracy` form the latest puck location.
-     *  - number: Pulsing circle should animate with the constant radius.
+     *  - `'accuracy'`: Pulsing circle radius is based on the `horizontalAccuracy` from the latest
+     *    location, providing a visual representation of GPS precision.
+     *  - `number`: Pulsing circle uses a constant radius in screen points.
      */
     radius?: 'accuracy' | number;
   }
 | 'default'
 ```
-The configration parameters for sonar-like pulsing circle animation shown around the 2D puck.
+The configuration parameters for sonar-like pulsing circle animation shown around the 2D puck.
+Set to `'default'` to enable pulsing with platform default settings. Pass an object to customize.
+Omit or set to `undefined` to disable pulsing.
 
 
 

docs/UserLocation.md

@@ -8,7 +8,13 @@ import { UserLocation } from '@rnmapbox/maps';
 UserLocation
 
 ```
+Displays the user's current location on the map with a customizable appearance.
 
+By default, renders a blue circle indicator. Provide children (layer components) to
+customize the appearance. Uses `locationManager` internally to subscribe to location
+updates, with automatic start/stop on mount/unmount and background/foreground transitions.
+
+For a simpler native-rendered location indicator, consider using {@link LocationPuck} directly.
 
 ## props
 
@@ -52,7 +58,8 @@ Custom location icon of type mapbox-gl-native components
 ```tsx
 number
 ```
-Minimum amount of movement before GPS location is updated in meters
+Minimum distance in meters the device must move before a location update is generated.
+Maps to `distanceFilter` on iOS and `displacement` on Android. Defaults to 0.
 
   _defaults to:_ `0`
 [Set Displacement](../examples/UserLocation/SetDisplacement)
@@ -72,7 +79,9 @@ Callback that is triggered on location icon press
 ```tsx
 func
 ```
-Callback that is triggered on location update
+Callback that is triggered on each location update. Receives a {@link Location} object
+containing `coords` (latitude, longitude, altitude, accuracy, heading, course, speed)
+and `timestamp`.
 *signature:*`(location:Location) => void`
 
 [User Location Updates](../examples/UserLocation/UserLocationUpdates)
@@ -93,7 +102,10 @@ Which render mode to use.
 ```tsx
 boolean
 ```
-Request the always location permission, and listen to the location even when the app is in background
+Request the always location permission, and listen to the location even when the app is in background.
+
+**Note:** This is not implemented in Mapbox Maps SDK v11 and is currently a no-op
+on both iOS and Android.
 
 @platform ios
 

docs/Viewport.md

@@ -8,15 +8,20 @@ import { Viewport } from '@rnmapbox/maps';
 Viewport
 
 ```
-provides a structured approach to organizing camera management logic into states and transitions between them.
+Provides a structured approach to organizing camera management logic into states and transitions between them.
+
+Viewport is the modern alternative to Camera's `followUserLocation` for tracking the user's position.
+It supports two built-in states:
+ - `followPuck`: tracks the user's location with configurable zoom, pitch, and bearing
+ - `overview`: frames a given geometry with configurable padding, bearing, and pitch
 
 At any given time, the viewport is either:
- - idle
- - in a state (camera is being managed by a ViewportState)
+ - idle (not managing the camera)
+ - in a state (camera is actively managed by a ViewportState)
  - transitioning between states
 
-See [android](https://docs.mapbox.com/android/maps/api/${ANDROID_SDK_VERSION}/mapbox-maps-android/com.mapbox.maps.plugin.viewport/viewport.html),
-[ios](https://docs.mapbox.com/ios/maps/api/${IOS_SDK_VERSION}/Viewport.html#/s:10MapboxMaps8ViewportC)
+See [Android Viewport](https://docs.mapbox.com/android/maps/api/11.0.0/mapbox-maps-android/com.mapbox.maps.plugin.viewport/viewport.html),
+[iOS Viewport](https://docs.mapbox.com/ios/maps/api/11.0.0/Viewport.html)
 
 ## props
 
@@ -57,7 +62,7 @@ delivery of status changed notifications.
 ## methods
 ### getState()
 
-
+Returns the current state of the viewport as a JSON string.
 
 #### arguments
 | Name | Type | Required | Description  |
@@ -67,7 +72,7 @@ delivery of status changed notifications.
 
 ### idle()
 
-
+Sets the viewport to idle, stopping any active state or transition.
 
 #### arguments
 | Name | Type | Required | Description  |
@@ -77,13 +82,13 @@ delivery of status changed notifications.
 
 ### transitionTo(state, transition)
 
-
+Transitions the viewport to a new state with an optional transition animation.
 
 #### arguments
 | Name | Type | Required | Description  |
 | ---- | :--: | :------: | :----------: |
-| `state` | `n/a` | `Yes` | undefined |
-| `transition` | `n/a` | `Yes` | undefined |
+| `state` | `ViewportState` | `Yes` | The target state (followPuck or overview). |
+| `transition` | `ViewportTransition` | `Yes` | The transition to use (immediate or default). |
 
 
 

docs/coordinates.md

@@ -8,7 +8,8 @@ import { coordinates } from '@rnmapbox/maps';
 coordinates
 
 ```
-Coorinates sent by locationManager
+Geographic coordinates sent by locationManager.Fields:Note: heading (compass direction the device is facing) and course (direction of travel) are distinct values.
+On Android, both currently return the same value (see related issues above).