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,7 @@ import { coordinates } from '@rnmapbox/maps';
 coordinates
 
 ```
-Coorinates sent by locationManager
+Geographic coordinates sent by locationManager. Includes latitude and longitude in degrees, optional altitude in meters above sea level, optional accuracy as the horizontal radius of uncertainty in meters, heading and course in degrees, and the instantaneous speed in meters per second. Heading is the compass direction the device is facing and course is the direction of travel; these are distinct values, but on Android both currently return the same value because the Mapbox SDK does not expose a public compass engine API (see rnmapbox/maps issues 4063, 3391, and 3041 for context).