feat: Add CameraGestureObserver - reliable alternative to onMapIdle

[mfazekas]

Problem

onMapIdle has fundamental issues as an upstream Mapbox SDK concept:

1. Never called when LocationPuck pulse animation is running ([Bug]: Adding LocationPuck causes onMapIdle to be called infinitely #3801, [Bug]: (Android only) onMapIdle (etc) does not trigger with a native UserLocation #2902)
2. Called excessively in other scenarios, causing performance issues ([Bug]: Adding LocationPuck causes onMapIdle to be called infinitely #3801)
3. Unreliable for detecting when the map is truly ready/settled ([Bug]: onMapIdle never called #3701)

Since onMapIdle is an upstream concept, we cannot fix these issues directly.

Solution

Introduces CameraGestureObserver - a native component that reliably detects when the map reaches a steady state by tracking both camera gestures AND animations.

How it works

• Monitors camera gesture lifecycle (pan, pinch, rotate, pitch)
• Monitors camera animation lifecycle (including programmatic camera changes)
• Emits onMapSteady event after a configurable quiet period (default 200ms)
• Includes timeout mechanism for long-running activities

Usage

<MapView>
  <CameraGestureObserver
    quietPeriodMs={200}
    maxIntervalMs={5000}
    onMapSteady={({ nativeEvent }) => {
      console.log('Map is ready!', nativeEvent);
      // nativeEvent: { reason, idleDurationMs?, lastGestureType?, timestamp }
    }}
  />
</MapView>

Implementation

• iOS: Uses GestureManagerDelegate + camera animator lifecycle observers
• Android: Uses gesture listeners + CameraAnimationsLifecycleListener
• Both platforms: Sophisticated state machine with quiet period and timeout logic

Related Issues

Fixes #3801
Fixes #2902
Fixes #3701

🤖 Generated with Claude Code

import React, { useCallback, useState } from 'react';
import { View, StyleSheet, Text } from 'react-native';
import { MapView, Camera, CameraGestureObserver } from '@rnmapbox/maps';

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  map: {
    flex: 1,
  },
  statusBar: {
    position: 'absolute',
    top: 50,
    left: 20,
    right: 20,
    backgroundColor: 'rgba(255, 255, 255, 0.95)',
    padding: 16,
    borderRadius: 8,
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 2 },
    shadowOpacity: 0.25,
    shadowRadius: 3.84,
    elevation: 5,
  },
  title: {
    fontSize: 16,
    fontWeight: 'bold',
    marginBottom: 8,
  },
  statusText: {
    fontSize: 14,
    lineHeight: 20,
  },
  hint: {
    fontSize: 12,
    color: '#666',
    marginTop: 8,
    fontStyle: 'italic',
  },
});

const CameraGestureObserverExample = () => {
  const [status, setStatus] = useState('Waiting for interaction...');

  const onMapSteady = useCallback(({ nativeEvent }) => {
    const { reason, idleDurationMs, lastGestureType, timestamp } = nativeEvent;

    let message = `✓ Map is steady!\n\nReason: ${reason}`;

    if (reason === 'steady' && idleDurationMs !== undefined) {
      message += `\nIdle duration: ${Math.round(idleDurationMs)}ms`;
    }

    if (lastGestureType) {
      message += `\nLast gesture: ${lastGestureType}`;
    }

    message += `\nTime: ${new Date(timestamp).toLocaleTimeString()}`;

    console.log('[CameraGestureObserver]', nativeEvent);
    setStatus(message);
  }, []);

  return (
    <View style={styles.container}>
      <MapView style={styles.map}>
        <Camera
          defaultSettings={{
            centerCoordinate: [-74.006, 40.7128],
            zoomLevel: 12,
          }}
        />
        <CameraGestureObserver
          quietPeriodMs={200}
          maxIntervalMs={5000}
          onMapSteady={onMapSteady}
        />
      </MapView>
      <View style={styles.statusBar}>
        <Text style={styles.title}>Map Steady State</Text>
        <Text style={styles.statusText}>{status}</Text>
        <Text style={styles.hint}>
          Pan, zoom, or rotate the map to see the steady state detection
        </Text>
      </View>
    </View>
  );
};

export default CameraGestureObserverExample;

[Alvi24]

is there a way to get MapState onMapSteady?

[Alvi24]

having an issue with this component on Android:
Unsupported top level event type "topOnMapSteady" dispatched
See #4105