@rnmapbox/maps 10.3.0-rc.0 → 10.3.0

package/src/components/MapView.tsx

@@ -37,11 +37,6 @@ if (RNMBXModule == null) {
     'Native part of Mapbox React Native libraries were not registered properly, double check our native installation guides.',
   );
 }
-if (!RNMBXModule.MapboxV10) {
-  console.warn(
-    '@rnmapbox/maps: Non v10 implementations are deprecated and will be removed in next version - see https://github.com/rnmapbox/maps/wiki/Deprecated-RNMapboxImpl-Maplibre',
-  );
-}
 
 const styles = StyleSheet.create({
   matchParent: { flex: 1 },
@@ -65,6 +60,11 @@ export type RegionPayload = {
   pitch: number;
 };
 
+export type ScreenPointPayload = {
+  readonly screenPointX: number;
+  readonly screenPointY: number;
+};
+
 export type GestureSettings = {
   /**
    * Whether double tapping the map with one touch results in a zoom-in animation.
@@ -312,14 +312,18 @@ type Props = ViewProps & {
   gestureSettings?: GestureSettings;
 
   /**
-   * Map press listener, gets called when a user presses the map
+   * Map press listener, called when a user presses the map.
    */
-  onPress?: (feature: GeoJSON.Feature) => void;
+  onPress?: (
+    feature: GeoJSON.Feature<GeoJSON.Point, ScreenPointPayload>,
+  ) => void;
 
   /**
-   * Map long press listener, gets called when a user long presses the map
+   * Map long press listener, called when a user long presses the map.
    */
-  onLongPress?: (feature: GeoJSON.Feature) => void;
+  onLongPress?: (
+    feature: GeoJSON.Feature<GeoJSON.Point, ScreenPointPayload>,
+  ) => void;
 
   /**
    * <v10 only
@@ -470,7 +474,7 @@ const CallbablePropKeys = [
   'onCameraChanged',
 ] as const;
 
-type CallbablePropKeys = (typeof CallbablePropKeys)[number];
+type CallbablePropKeys = typeof CallbablePropKeys[number];
 
 type CallbablePropKeysWithoutOn = CallbablePropKeys extends `on${infer C}`
   ? C
@@ -494,7 +498,7 @@ class MapView extends NativeBridgeComponent(
     compassFadeWhenNorth: false,
     logoEnabled: true,
     scaleBarEnabled: true,
-    surfaceView: RNMBXModule.MapboxV10 ? true : false,
+    surfaceView: true,
     requestDisallowInterceptTouchEvent: false,
     regionWillChangeDebounceTime: 10,
     regionDidChangeDebounceTime: 500,
@@ -591,93 +595,93 @@ class MapView extends NativeBridgeComponent(
   }
 
   _setHandledMapChangedEvents(props: Props) {
-    if (isAndroid() || RNMBXModule.MapboxV10) {
-      const events: string[] = [];
-
-      function addIfHasHandler(name: CallbablePropKeysWithoutOn) {
-        if (props[`on${name}`] != null) {
-          if (EventTypes[name] == null) {
-            if (name === 'DidFailLoadingMap') {
-              console.warn(
-                `rnmapbox maps: on${name} is deprecated, please use onMapLoadingError`,
-              );
-            } else {
-              console.warn(`rnmapbox maps: ${name} is not supported`);
-            }
+    const events: string[] = [];
+
+    function addIfHasHandler(name: CallbablePropKeysWithoutOn) {
+      if (props[`on${name}`] != null) {
+        if (EventTypes[name] == null) {
+          if (name === 'DidFailLoadingMap') {
+            console.warn(
+              `rnmapbox maps: on${name} is deprecated, please use onMapLoadingError`,
+            );
           } else {
-            events.push(EventTypes[name]);
-            return true;
+            console.warn(`rnmapbox maps: ${name} is not supported`);
           }
+        } else {
+          events.push(EventTypes[name]);
+          return true;
         }
-        return false;
       }
+      return false;
+    }
 
-      addIfHasHandler('RegionWillChange');
-      addIfHasHandler('RegionIsChanging');
-      addIfHasHandler('RegionDidChange');
-      addIfHasHandler('UserLocationUpdate');
-      addIfHasHandler('WillStartLoadingMap');
-      addIfHasHandler('DidFinishLoadingMap');
-      addIfHasHandler('MapLoadingError');
-      addIfHasHandler('DidFailLoadingMap');
-      addIfHasHandler('WillStartRenderingFrame');
-      addIfHasHandler('DidFinishRenderingFrame');
-      addIfHasHandler('DidFinishRenderingFrameFully');
-      addIfHasHandler('WillStartRenderingMap');
-      addIfHasHandler('DidFinishRenderingMap');
-      addIfHasHandler('DidFinishRenderingMapFully');
-      addIfHasHandler('DidFinishLoadingStyle');
-
-      addIfHasHandler('CameraChanged');
-      addIfHasHandler('MapIdle');
-
-      if (addIfHasHandler('RegionDidChange')) {
-        if (!this.deprecationLogged.regionDidChange) {
-          console.warn(
-            'onRegionDidChange is deprecated and will be removed in next release - please use onMapIdle. https://github.com/rnmapbox/maps/wiki/Deprecated-RegionIsDidChange',
-          );
-          this.deprecationLogged.regionDidChange = true;
-        }
-        if (props.onMapIdle) {
-          console.warn(
-            'rnmapbox/maps: only one of MapView.onRegionDidChange or onMapIdle is supported',
-          );
-        }
+    addIfHasHandler('RegionWillChange');
+    addIfHasHandler('RegionIsChanging');
+    addIfHasHandler('RegionDidChange');
+    addIfHasHandler('UserLocationUpdate');
+    addIfHasHandler('WillStartLoadingMap');
+    addIfHasHandler('DidFinishLoadingMap');
+    addIfHasHandler('MapLoadingError');
+    addIfHasHandler('DidFailLoadingMap');
+    addIfHasHandler('WillStartRenderingFrame');
+    addIfHasHandler('DidFinishRenderingFrame');
+    addIfHasHandler('DidFinishRenderingFrameFully');
+    addIfHasHandler('WillStartRenderingMap');
+    addIfHasHandler('DidFinishRenderingMap');
+    addIfHasHandler('DidFinishRenderingMapFully');
+    addIfHasHandler('DidFinishLoadingStyle');
+
+    addIfHasHandler('CameraChanged');
+    addIfHasHandler('MapIdle');
+
+    if (addIfHasHandler('RegionDidChange')) {
+      if (!this.deprecationLogged.regionDidChange) {
+        console.warn(
+          'onRegionDidChange is deprecated and will be removed in next release - please use onMapIdle. https://github.com/rnmapbox/maps/wiki/Deprecated-RegionIsDidChange',
+        );
+        this.deprecationLogged.regionDidChange = true;
       }
-      if (addIfHasHandler('RegionIsChanging')) {
-        if (!this.deprecationLogged.regionIsChanging) {
-          console.warn(
-            'onRegionIsChanging is deprecated and will be removed in next release - please use onCameraChanged. https://github.com/rnmapbox/maps/wiki/Deprecated-RegionIsDidChange',
-          );
-          this.deprecationLogged.regionIsChanging = true;
-        }
-        if (props.onCameraChanged) {
-          console.warn(
-            'rnmapbox/maps: only one of MapView.onRegionIsChanging or onCameraChanged is supported',
-          );
-        }
+      if (props.onMapIdle) {
+        console.warn(
+          'rnmapbox/maps: only one of MapView.onRegionDidChange or onMapIdle is supported',
+        );
       }
-
-      if (props.onRegionWillChange) {
+    }
+    if (addIfHasHandler('RegionIsChanging')) {
+      if (!this.deprecationLogged.regionIsChanging) {
+        console.warn(
+          'onRegionIsChanging is deprecated and will be removed in next release - please use onCameraChanged. https://github.com/rnmapbox/maps/wiki/Deprecated-RegionIsDidChange',
+        );
+        this.deprecationLogged.regionIsChanging = true;
+      }
+      if (props.onCameraChanged) {
         console.warn(
-          'onRegionWillChange is deprecated and will be removed in v10 - please use onRegionIsChanging',
+          'rnmapbox/maps: only one of MapView.onRegionIsChanging or onCameraChanged is supported',
         );
       }
+    }
 
-      this._runNativeMethod('setHandledMapChangedEvents', this._nativeRef, [
-        events,
-      ]);
+    if (props.onRegionWillChange) {
+      console.warn(
+        'onRegionWillChange is deprecated and will be removed in v10 - please use onRegionIsChanging',
+      );
     }
+
+    this._runNativeMethod('setHandledMapChangedEvents', this._nativeRef, [
+      events,
+    ]);
   }
 
   /**
-   * Converts a geographic coordinate to a point in the given view’s coordinate system.
+   * Converts a geographic coordinate to a screen coordinate relative to the map view.
    *
    * @example
-   * const pointInView = await this._map.getPointInView([-37.817070, 144.949901]);
+   * const longitude = 144.949901;
+   * const latitude = -37.817070;
+   * const [x, y] = await this._map.getPointInView([longitude, latitude]);
    *
-   * @param {Array<number>} coordinate - A point expressed in the map view's coordinate system.
-   * @return {Array}
+   * @param {Position} coordinate - A point expressed in the map view's coordinate system `[longitude, latitude]`.
+   * @return {Position} A point expressed in screen coordinates relative to the map view `[x, y]`.
    */
   async getPointInView(coordinate: Position): Promise<Position> {
     const res = await this._runNative<{ pointInView: Position }>(
@@ -688,13 +692,14 @@ class MapView extends NativeBridgeComponent(
   }
 
   /**
-   * Converts a point in the given view’s coordinate system to a geographic coordinate.
+   * Converts a screen coordinate relative to the map view to a geographic coordinate.
    *
    * @example
-   * const coordinate = await this._map.getCoordinateFromView([100, 100]);
+   * const x = 100; const y = 100;
+   * const [longitude, latitude] = await this._map.getCoordinateFromView([x, y]);
    *
-   * @param {Array<number>} point - A point expressed in the given view’s coordinate system.
-   * @return {Array}
+   * @param {Position} point - A point expressed in screen coordinates relative to the map view `[x, y]`.
+   * @return {Position} A point expressed in the map view's coordinate system `[longitude, latitude]`.
    */
   async getCoordinateFromView(point: Position): Promise<Position> {
     const res = await this._runNative<{ coordinateFromView: Position }>(
@@ -705,12 +710,12 @@ class MapView extends NativeBridgeComponent(
   }
 
   /**
-   * The coordinate bounds (ne, sw) visible in the user’s viewport.
+   * The coordinate bounds of the map viewport.
    *
    * @example
-   * const visibleBounds = await this._map.getVisibleBounds();
+   * const [[rightLon, topLat], [leftLon, bottomLat]] = await this._map.getVisibleBounds();
    *
-   * @return {Array}
+   * @return {[Position, Position]} The geographic coordinate bounds of the map viewport `[[rightLon, topLat], [leftLon, bottomLat]]`.
    */
   async getVisibleBounds(): Promise<[Position, Position]> {
     const res = await this._runNative<{ visibleBounds: [Position, Position] }>(
@@ -723,12 +728,13 @@ class MapView extends NativeBridgeComponent(
    * Returns an array of rendered map features that intersect with a given point.
    *
    * @example
-   * this._map.queryRenderedFeaturesAtPoint([30, 40], ['==', 'type', 'Point'], ['id1', 'id2'])
+   * const x = 30; const y = 40;
+   * this._map.queryRenderedFeaturesAtPoint([x, y], ['==', 'type', 'Point'], ['id1', 'id2'])
    *
-   * @param  {Array<Number>} coordinate - A point expressed in the map view’s coordinate system.
-   * @param  {Array=} filter - A set of strings that correspond to the names of layers defined in the current style. Only the features contained in these layers are included in the returned array.
-   * @param  {Array=} layerIDs - A array of layer id's to filter the features by
-   * @return {FeatureCollection}
+   * @param  {Position} coordinate - A point expressed in the map view’s coordinate system `[x, y]`;
+   * @param  {FilterExpression | []} filter - A set of strings that correspond to the names of layers defined in the current style. Only the features contained in these layers are included in the returned array.
+   * @param  {string[]} layerIDs - A array of layer IDs by which to filter the features.
+   * @return {FeatureCollection}  A GeoJSON feature collection containing the query results.
    */
 
   async queryRenderedFeaturesAtPoint(
@@ -758,22 +764,21 @@ class MapView extends NativeBridgeComponent(
    * passing an empty array will query the entire visible bounds of the map.
    *
    * @example
-   * this._map.queryRenderedFeaturesInRect([30, 40, 20, 10], ['==', 'type', 'Point'], ['id1', 'id2'])
+   * const left = 40; const top = 30;
+   * const right = 10; const bottom = 20;
+   * this._map.queryRenderedFeaturesInRect([top, left, bottom, right], ['==', 'type', 'Point'], ['id1', 'id2'])
    *
-   * @param  {Array<Number>} bbox - A rectangle expressed in the map view’s coordinate system, density independent pixels and not map coordinates. This can be an empty array to query the visible map area.
-   * @param  {Array=} filter - A set of strings that correspond to the names of layers defined in the current style. Only the features contained in these layers are included in the returned array.
-   * @param  {Array=} layerIDs -  A array of layer id's to filter the features by
-   * @return {FeatureCollection}
+   * @param  {BBox | []} bbox - A rectangle expressed in density-independent screen coordinates relative to the map view `[top, left, bottom, right]` or `[minY, minX, maxY, maxX]` (not geographic coordinates). An empty array queries the visible map area.
+   * @param  {FilterExpression} filter - An array of strings that correspond to the names of layers defined in the current style. Only the features contained in these layers are included in the returned array.
+   * @param  {string[] | null} layerIDs -  A array of layer IDs by which to filter the features.
+   * @return {FeatureCollection} A GeoJSON feature collection containing the query results.
    */
   async queryRenderedFeaturesInRect(
     bbox: BBox | [],
     filter: FilterExpression | [] = [],
     layerIDs: string[] | null = null,
   ): Promise<GeoJSON.FeatureCollection | undefined> {
-    if (
-      bbox != null &&
-      (bbox.length === 4 || (RNMBXModule.MapboxV10 && bbox.length === 0))
-    ) {
+    if (bbox != null && (bbox.length === 4 || bbox.length === 0)) {
       const res = await this._runNative<{ data: GeoJSON.FeatureCollection }>(
         'queryRenderedFeaturesInRect',
         [bbox, getFilter(filter), layerIDs],
@@ -786,7 +791,7 @@ class MapView extends NativeBridgeComponent(
       return res.data;
     } else {
       throw new Error(
-        'Must pass in a valid bounding box: [top, right, bottom, left]. An empty array [] is also acceptable in v10.',
+        'Must pass in a valid bounding box: [top, left, bottom, right]. An empty array [] is also acceptable in v10.',
       );
     }
   }
@@ -798,9 +803,9 @@ class MapView extends NativeBridgeComponent(
    * this._map.querySourceFeatures('your-source-id', [], ['your-source-layer'])
    *
    * @param  {String} sourceId - Style source identifier used to query for source features.
-   * @param  {Array=} filter - A filter to limit query results.
-   * @param  {Array=} sourceLayerIDs - The name of the source layers to query. For vector tile sources, this parameter is required. For GeoJSON sources, it is ignored.
-   * @return {FeatureCollection}
+   * @param  {FilterExpression | []} filter - A filter to limit query results.
+   * @param  {string[]} sourceLayerIDs - The name of the source layers to query. For vector tile sources, this parameter is required. For GeoJSON sources, it is ignored.
+   * @return {FeatureCollection} A GeoJSON feature collection.
    */
   async querySourceFeatures(
     sourceId: string,
@@ -844,9 +849,11 @@ class MapView extends NativeBridgeComponent(
   }
 
   /**
-   * Takes snapshot of map with current tiles and returns a URI to the image
-   * @param  {Boolean} writeToDisk If true will create a temp file, otherwise it is in base64
-   * @return {String}
+   * Takes snapshot of map with current tiles and returns a Base64-encoded PNG image,
+   * or an file-system URI to a temporary PNG file if `writeToDisk` is `true`.
+   *
+   * @param  {boolean} writeToDisk If `true`, creates a temporary PNG file and returns a file-system URI, otherwise returns a Base64-encoded PNG image. (Defaults to `false`)
+   * @return {string} A a Base64-encoded PNG image or a file-system URI to a temporary PNG file.
    */
   async takeSnap(writeToDisk = false): Promise<string> {
     const res = await this._runNative<{ uri: string }>('takeSnap', [
@@ -861,7 +868,7 @@ class MapView extends NativeBridgeComponent(
    * @example
    * const zoom = await this._map.getZoom();
    *
-   * @return {Number}
+   * @return {number} The current zoom of the map view.
    */
 
   async getZoom(): Promise<number> {
@@ -870,12 +877,12 @@ class MapView extends NativeBridgeComponent(
   }
 
   /**
-   * Returns the map's geographical centerpoint
+   * Returns the map's center point expressed as geographic coordinates `[longitude, latitude]`.
    *
    * @example
    * const center = await this._map.getCenter();
    *
-   * @return {Array<Number>} Coordinates
+   * @return {Position} The map's center point expressed as geographic coordinates `[longitude, latitude]`.
    */
   async getCenter(): Promise<Position> {
     const res = await this._runNative<{ center: Position }>('getCenter');
@@ -891,12 +898,6 @@ class MapView extends NativeBridgeComponent(
    * v10 only
    */
   async clearData(): Promise<void> {
-    if (!RNMBXModule.MapboxV10) {
-      console.warn(
-        'RNMapbox: clearData is only implemented in v10 implementation or later',
-      );
-      return;
-    }
     await this._runNative<void>('clearData');
   }
 
@@ -905,8 +906,8 @@ class MapView extends NativeBridgeComponent(
    * The elevation is returned in meters relative to mean sea-level.
    * Returns null if terrain is disabled or if terrain data for the location hasn't been loaded yet.
    *
-   * @param {Array<Number>} coordinate - the coordinates to query elevation at
-   * @return {Number}
+   * @param {Position} coordinate - The geographic coordinates `[longitude, latitude]` at which to query elevation.
+   * @return {number} Elevation in meters relative to mean sea-level.
    */
   async queryTerrainElevation(coordinate: Position): Promise<number> {
     const res = await this._runNative<{ data: number }>(
@@ -923,8 +924,8 @@ class MapView extends NativeBridgeComponent(
    * await this._map.setSourceVisibility(false, 'composite', 'building')
    *
    * @param {boolean} visible - Visibility of the layers
-   * @param {String} sourceId - Identifier of the target source (e.g. 'composite')
-   * @param {String=} sourceLayerId - Identifier of the target source-layer (e.g. 'building')
+   * @param {string} sourceId - Target source identifier (e.g. 'composite')
+   * @param {string | null} sourceLayerId - Target source-layer identifier (e.g. 'building'). If `null`, the change affects all layers in the target source.
    */
   setSourceVisibility(
     visible: boolean,
@@ -956,13 +957,6 @@ class MapView extends NativeBridgeComponent(
     sourceId: string,
     sourceLayerId: string | null = null,
   ): Promise<void> {
-    if (!RNMBXModule.MapboxV10) {
-      console.warn(
-        'RNMapbox: setFeatureState is only implemented in v10 implementation or later',
-      );
-      return;
-    }
-
     await this._runNative<void>('setFeatureState', [
       featureId,
       state,
@@ -983,13 +977,6 @@ class MapView extends NativeBridgeComponent(
     sourceId: string,
     sourceLayerId: string | null = null,
   ): Promise<Readonly<Record<string, unknown>>> {
-    if (!RNMBXModule.MapboxV10) {
-      console.warn(
-        'RNMapbox: setFeatureState is only implemented in v10 implementation or later',
-      );
-      return {};
-    }
-
     const res = await this._runNative<{
       featureState: Readonly<Record<string, unknown>>;
     }>('getFeatureState', [featureId, sourceId, sourceLayerId]);
@@ -1013,13 +1000,6 @@ class MapView extends NativeBridgeComponent(
     sourceId: string,
     sourceLayerId: string | null = null,
   ): Promise<void> {
-    if (!RNMBXModule.MapboxV10) {
-      console.warn(
-        'RNMapbox: removeFeatureState is only implemented in v10 implementation or later',
-      );
-      return;
-    }
-
     await this._runNative<void>('removeFeatureState', [
       featureId,
       stateKey,
@@ -1036,13 +1016,21 @@ class MapView extends NativeBridgeComponent(
     }
   }
 
-  _onPress(e: NativeSyntheticEvent<{ payload: GeoJSON.Feature | string }>) {
+  _onPress(
+    e: NativeSyntheticEvent<{
+      payload: GeoJSON.Feature<GeoJSON.Point, ScreenPointPayload> | string;
+    }>,
+  ) {
     if (isFunction(this.props.onPress)) {
       this.props.onPress(this._decodePayload(e.nativeEvent.payload));
     }
   }
 
-  _onLongPress(e: NativeSyntheticEvent<{ payload: GeoJSON.Feature | string }>) {
+  _onLongPress(
+    e: NativeSyntheticEvent<{
+      payload: GeoJSON.Feature<GeoJSON.Point, ScreenPointPayload> | string;
+    }>,
+  ) {
     if (isFunction(this.props.onLongPress)) {
       this.props.onLongPress(this._decodePayload(e.nativeEvent.payload));
     }
@@ -1187,13 +1175,11 @@ class MapView extends NativeBridgeComponent(
       return;
     }
 
-    if (RNMBXModule.MapboxV10) {
-      if (!this.deprecationLogged.contentInset) {
-        console.warn(
-          '@rnmapbox/maps: contentInset is deprecated, use Camera padding instead.',
-        );
-        this.deprecationLogged.contentInset = true;
-      }
+    if (!this.deprecationLogged.contentInset) {
+      console.warn(
+        '@rnmapbox/maps: contentInset is deprecated, use Camera padding instead.',
+      );
+      this.deprecationLogged.contentInset = true;
     }
 
     if (!Array.isArray(this.props.contentInset)) {
@@ -1235,9 +1221,6 @@ class MapView extends NativeBridgeComponent(
   }
 
   _setLocalizeLabels(props: Props) {
-    if (!RNMBXModule.MapboxV10) {
-      return;
-    }
     if (typeof props.localizeLabels === 'boolean') {
       props.localizeLabels = {
         locale: 'current',