- regenerate docs for onMapCameraChange

- add onMapCameraChange example under CameraGestureObserver

Author: KijongHan

android/src/main/java/com/rnmapbox/rnmbx/components/mapview/helpers/MapCameraChangeDetector.kt

@@ -33,7 +33,7 @@ class MapCameraChangeDetector(private val mapboxMap: MapboxMap) {
     private val derivedReason: CameraChangeReason
         get() = when {
             isGestureActive -> CameraChangeReason.USER_GESTURE
-//            activeAnimationOwner == MapAnimationOwnerRegistry.GESTURES -> CameraChangeReason.USER_GESTURE
+            activeAnimationOwner == MapAnimationOwnerRegistry.GESTURES -> CameraChangeReason.USER_GESTURE
             activeAnimationOwner == MapAnimationOwnerRegistry.LOCATION -> CameraChangeReason.SDK_ANIMATION
             activeAnimationOwner == MapAnimationOwnerRegistry.COMPASS -> CameraChangeReason.SDK_ANIMATION
             activeAnimationOwner == MapAnimationOwnerRegistry.INTERNAL -> CameraChangeReason.SDK_ANIMATION

docs/CameraGestureObserver.md

@@ -44,6 +44,16 @@ Callback when the map reaches a steady state (no active gestures or animations).
 
 [Camera Gesture Observer](../examples/Map/CameraGestureObserver)
 
+### onMapCameraChange
+
+```tsx
+func
+```
+Callback when the camera changes (due to gestures or animations).
+*signature:*`(event:{nativeEvent: OnMapCameraChangeEvent}) => void`
+
+[Camera Gesture Observer](../examples/Map/CameraGestureObserver)
+  
 
 
 

docs/docs.json

@@ -1054,6 +1054,16 @@
         },
         "default": "none",
         "description": "Callback when the map reaches a steady state (no active gestures or animations).\n*signature:*`(event:{nativeEvent: OnMapSteadyEvent}) => void`"
+      },
+      {
+        "name": "onMapCameraChange",
+        "required": false,
+        "type": {
+          "name": "func",
+          "funcSignature": "(event:{nativeEvent: OnMapCameraChangeEvent}) => void"
+        },
+        "default": "none",
+        "description": "Callback when the camera changes (due to gestures or animations).\n*signature:*`(event:{nativeEvent: OnMapCameraChangeEvent}) => void`"
       }
     ],
     "fileNameWithExt": "CameraGestureObserver.tsx",

docs/examples.json

@@ -267,10 +267,11 @@
           "title": "Camera Gesture Observer",
           "tags": [
             "CameraGestureObserver#onMapSteady",
+            "CameraGestureObserver#onMapCameraChange",
             "CameraGestureObserver#quietPeriodMs",
             "CameraGestureObserver#maxIntervalMs"
           ],
-          "docs": "\nDemonstrates how to detect when the map becomes steady after user gestures (pan, zoom, rotate). The CameraGestureObserver component fires the onMapSteady event after a configurable quiet period, providing information about the last gesture type and idle duration.\n"
+          "docs": "\nDemonstrates how to detect when the map becomes steady after user gestures (pan, zoom, rotate). The CameraGestureObserver component fires the onMapSteady event after a configurable quiet period, providing information about the last gesture type and idle duration. It also fires the onMapCameraChange event on every camera change, reporting the current center, zoom, heading, pitch, and whether the change came from user interaction.\n"
         },
         "fullPath": "example/src/examples/Map/CameraGestureObserver.tsx",
         "relPath": "Map/CameraGestureObserver.tsx",

example/src/examples/Map/CameraGestureObserver.tsx

@@ -1,8 +1,15 @@
-import { useCallback, useState } from 'react';
-import { View, StyleSheet, Text } from 'react-native';
-import { MapView, Camera, CameraGestureObserver, type OnMapSteadyEvent } from '@rnmapbox/maps';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { View, StyleSheet, Text, Button } from 'react-native';
+import {
+  MapView,
+  Camera,
+  CameraGestureObserver,
+  type OnMapSteadyEvent,
+  type OnMapCameraChangeEvent,
+} from '@rnmapbox/maps';
 
 import { type ExampleWithMetadata } from '../common/ExampleMetadata'; // exclude-from-doc
+import type { CameraRef } from '../../../../src/components/Camera';
 
 const styles = StyleSheet.create({
   container: {
@@ -34,6 +41,9 @@ const styles = StyleSheet.create({
     fontSize: 14,
     lineHeight: 20,
   },
+  sectionSpacing: {
+    marginTop: 12,
+  },
   hint: {
     fontSize: 12,
     color: '#666',
@@ -42,49 +52,108 @@ const styles = StyleSheet.create({
   },
 });
 
+const defaultCameraCoordinate = [-74.006, 40.7128]; // New York City
+
 const CameraGestureObserverExample = () => {
+  const mapCameraRef = useRef<CameraRef>(null);
   const [status, setStatus] = useState('Waiting for interaction...');
+  const [cameraStatus, setCameraStatus] = useState('No camera changes yet');
+  const [autoRecenter, setAutoRecenter] = useState(true);
+
+  const onMapCameraChange = useCallback(
+    ({ nativeEvent }: { nativeEvent: OnMapCameraChangeEvent }) => {
+      const { properties, isUserInteraction, timestamp } = nativeEvent;
+      const { center, zoom, heading, pitch } = properties;
+
+      const [longitude = 0, latitude = 0] = center;
+      let message = `Center: ${latitude.toFixed(4)}, ${longitude.toFixed(4)}`;
+      message += `\nZoom: ${zoom.toFixed(2)}`;
+      message += `\nHeading: ${heading.toFixed(1)}°  Pitch: ${pitch.toFixed(
+        1,
+      )}°`;
+      message += `\nUser interaction: ${isUserInteraction ? 'yes' : 'no'}`;
+
+      if (timestamp !== undefined) {
+        message += `\nTime: ${new Date(timestamp).toLocaleTimeString()}`;
+      }
+
+      console.log('[CameraGestureObserver] cameraChange', nativeEvent);
+      setCameraStatus(message);
+    },
+    [],
+  );
+
+  const onMapSteady = useCallback(
+    ({ nativeEvent }: { nativeEvent: OnMapSteadyEvent }) => {
+      const { reason, idleDurationMs, lastGestureType, timestamp } =
+        nativeEvent;
+
+      let message = `✓ Map is steady!\n\nReason: ${reason}`;
 
-  const onMapSteady = useCallback(({ nativeEvent } : { nativeEvent: OnMapSteadyEvent }) => {
-    const { reason, idleDurationMs, lastGestureType, timestamp } = nativeEvent;
+      if (reason === 'steady' && idleDurationMs !== undefined) {
+        message += `\nIdle duration: ${Math.round(idleDurationMs)}ms`;
+      }
 
-    let message = `✓ Map is steady!\n\nReason: ${reason}`;
+      if (lastGestureType) {
+        message += `\nLast gesture: ${lastGestureType}`;
+      }
 
-    if (reason === 'steady' && idleDurationMs !== undefined) {
-      message += `\nIdle duration: ${Math.round(idleDurationMs)}ms`;
-    }
+      message += `\nTime: ${new Date(timestamp).toLocaleTimeString()}`;
 
-    if (lastGestureType) {
-      message += `\nLast gesture: ${lastGestureType}`;
-    }
+      console.log('[CameraGestureObserver]', nativeEvent);
+      setStatus(message);
+    },
+    [],
+  );
+
+  useEffect(() => {
+    // Re-center the map every 5 seconds. When this is done, isUserInteraction should log as false (but it doesn't when locationPuck is true)
+    const interval = setInterval(() => {
+      if (!mapCameraRef.current || !autoRecenter) {
+        return;
+      }
 
-    message += `\nTime: ${new Date(timestamp).toLocaleTimeString()}`;
+      mapCameraRef.current?.setCamera({
+        centerCoordinate: defaultCameraCoordinate,
+        animationDuration: 1000,
+        animationMode: 'linearTo',
+      });
+    }, 5_000);
 
-    console.log('[CameraGestureObserver]', nativeEvent);
-    setStatus(message);
-  }, []);
+    return () => {
+      clearInterval(interval);
+    };
+  }, [autoRecenter]);
 
   return (
     <View style={styles.container}>
       <MapView style={styles.map}>
         <Camera
+          ref={mapCameraRef}
           defaultSettings={{
-            centerCoordinate: [-74.006, 40.7128],
+            centerCoordinate: defaultCameraCoordinate,
             zoomLevel: 12,
           }}
         />
         <CameraGestureObserver
           quietPeriodMs={200}
           maxIntervalMs={5000}
           onMapSteady={onMapSteady}
+          onMapCameraChange={onMapCameraChange}
         />
       </MapView>
       <View style={styles.statusBar}>
         <Text style={styles.title}>Map Steady State</Text>
         <Text style={styles.statusText}>{status}</Text>
+        <Text style={[styles.title, styles.sectionSpacing]}>Camera</Text>
+        <Text style={styles.statusText}>{cameraStatus}</Text>
         <Text style={styles.hint}>
           Pan, zoom, or rotate the map to see the steady state detection
         </Text>
+        <Button
+          title={`Auto recenter: ${autoRecenter ? 'On' : 'Off'}`}
+          onPress={() => setAutoRecenter((prev) => !prev)}
+        />
       </View>
     </View>
   );
@@ -98,11 +167,12 @@ const metadata: ExampleWithMetadata['metadata'] = {
   title: 'Camera Gesture Observer',
   tags: [
     'CameraGestureObserver#onMapSteady',
+    'CameraGestureObserver#onMapCameraChange',
     'CameraGestureObserver#quietPeriodMs',
     'CameraGestureObserver#maxIntervalMs',
   ],
   docs: `
-Demonstrates how to detect when the map becomes steady after user gestures (pan, zoom, rotate). The CameraGestureObserver component fires the onMapSteady event after a configurable quiet period, providing information about the last gesture type and idle duration.
+Demonstrates how to detect when the map becomes steady after user gestures (pan, zoom, rotate). The CameraGestureObserver component fires the onMapSteady event after a configurable quiet period, providing information about the last gesture type and idle duration. It also fires the onMapCameraChange event on every camera change, reporting the current center, zoom, heading, pitch, and whether the change came from user interaction.
 `,
 };
 CameraGestureObserverExample.metadata = metadata;

src/Mapbox.native.ts

@@ -54,6 +54,7 @@ export { default as CustomLocationProvider } from './components/CustomLocationPr
 export { Terrain } from './components/Terrain';
 export { default as CameraGestureObserver } from './components/CameraGestureObserver';
 export { type OnMapSteadyEvent } from './specs/RNMBXCameraGestureObserverNativeComponent';
+export { type OnMapCameraChangeEvent } from './specs/RNMBXCameraGestureObserverNativeComponent';
 export {
   default as locationManager,
   type Location,