@maplibre/maplibre-react-native 11.0.0-beta.8 → 11.0.0

package/src/components/map/Map.tsx

@@ -6,10 +6,9 @@ import type {
 import {
   Component,
   type ComponentProps,
-  forwardRef,
   memo,
   type ReactElement,
-  type ReactNode,
+  type Ref,
   useImperativeHandle,
   useLayoutEffect,
   useMemo,
@@ -29,7 +28,7 @@ import AndroidTextureMapViewNativeComponent from "./AndroidTextureMapViewNativeC
 import MapViewNativeComponent from "./MapViewNativeComponent";
 import NativeMapViewModule from "./NativeMapViewModule";
 import { LogManager } from "../../modules/log/LogManager";
-import { type BaseProps } from "../../types/BaseProps";
+import type { BaseProps } from "../../types/BaseProps";
 import type { LngLat } from "../../types/LngLat";
 import type { LngLatBounds } from "../../types/LngLatBounds";
 import type { PixelPoint } from "../../types/PixelPoint";
@@ -46,12 +45,19 @@ const styles = StyleSheet.create({
   flex1: { flex: 1 },
 });
 
+/**
+ * Screen position for map ornaments (logo, compass, scale bar). Exactly one of
+ * `top` / `bottom` and one of `left` / `right` must be provided.
+ */
 export type OrnamentViewPosition =
   | { top: number; left: number }
   | { top: number; right: number }
   | { bottom: number; right: number }
   | { bottom: number; left: number };
 
+/**
+ * Current viewport state of the map.
+ */
 export type ViewState = {
   center: LngLat;
   zoom: number;
@@ -60,11 +66,18 @@ export type ViewState = {
   bounds: LngLatBounds;
 };
 
+/**
+ * Event emitted when the map viewport changes (pan, zoom, rotate, pitch).
+ */
 export type ViewStateChangeEvent = ViewState & {
   animated: boolean;
   userInteraction: boolean;
 };
 
+/**
+ * Options for querying rendered features at a screen point or within a bounding
+ * box.
+ */
 export type QueryRenderedFeaturesOptions = {
   /**
    * Filter expression to filter the queried features
@@ -81,98 +94,113 @@ export interface MapRef {
   /**
    * Returns the current center coordinates of the map
    *
+   * @returns Current center coordinates of the map
+   *
    * @example
+   * ```ts
    * await mapRef.current?.getCenter();
-   *
-   * @return Current center coordinates of the map
+   * ```
    */
   getCenter(): Promise<LngLat>;
 
   /**
    * Returns the current zoom level of the map
    *
+   * @returns Current zoom level of the map
+   *
    * @example
+   * ```ts
    * await mapRef.current?.getZoom();
-   *
-   * @return Current zoom level of the map
+   * ```
    */
   getZoom(): Promise<number>;
 
   /**
    * Returns the current bearing of the map
    *
+   * @returns Current bearing of the map
+   *
    * @example
+   * ```ts
    * await mapRef.current?.getBearing();
-   *
-   * @return Current bearing of the map
+   * ```
    */
   getBearing(): Promise<number>;
 
   /**
    * Returns the current pitch of the map
    *
+   * @returns Current pitch of the map
+   *
    * @example
+   * ```ts
    * await mapRef.current?.getPitch();
-   *
-   * @return Current pitch of the map
+   * ```
    */
   getPitch(): Promise<number>;
 
   /**
    * Returns the current bounds of the map
    *
+   * @returns Current bounds of the map
+   *
    * @example
+   * ```ts
    * await mapRef.current?.getBounds();
-   *
-   * @return Current bounds of the map
+   * ```
    */
   getBounds(): Promise<LngLatBounds>;
 
   /**
    * Returns the current view state of the map
    *
+   * @returns Current view state of the map
+   *
    * @example
+   * ```ts
    * await mapRef.current?.getViewState();
-   *
-   * @return Current view state of the map
+   * ```
    */
   getViewState(): Promise<ViewState>;
 
   /**
    * Converts geographic coordinates to pixel point of the view
    *
+   * @param lngLat - Geographic coordinate
+   * @returns Pixel point
+   *
    * @example
+   * ```ts
    * await mapRef.current?.project([13.04214014753952, 47.80554907882145]);
-   *
-   * @param lngLat Geographic coordinate
-   * @return Pixel point
+   * ```
    */
   project(lngLat: LngLat): Promise<PixelPoint>;
 
   /**
    * Converts a pixel point of the view to geographic coordinates.
    *
+   * @param point - Pixel point
+   * @returns Geographic coordinate
+   *
    * @example
+   * ```ts
    * await mapRef.current?.unproject([280, 640]);
-   *
-   * @param point Pixel point
-   * @return Geographic coordinate
+   * ```
    */
   unproject(point: PixelPoint): Promise<LngLat>;
 
   /**
    * Query rendered features at a point
    *
-   * @example
-   * await mapRef.current?.queryRenderedFeatures(
-   *   [240, 640],
-   *   {
-   *     filter: ["==", "type", "Point"],
-   *     layers: ["restaurants", "shops"],
-   *   },
-   * );
+   * @returns Queried features
    *
-   * @return Queried features
+   * @example
+   * ```ts
+   * await mapRef.current?.queryRenderedFeatures([240, 640], {
+   *   filter: ["==", "type", "Point"],
+   *   layers: ["restaurants", "shops"],
+   * });
+   * ```
    */
   queryRenderedFeatures(
     pixelPoint: PixelPoint,
@@ -182,16 +210,15 @@ export interface MapRef {
   /**
    * Query rendered features within pixel bounds
    *
-   * @example
-   * await mapRef.current?.queryRenderedFeatures(
-   *   [100, 100, 400, 400],
-   *   {
-   *     filter: ["==", "type", "Point"],
-   *     layers: ["restaurants", "shops"],
-   *   },
-   * );
+   * @returns Queried features
    *
-   * @return Queried features
+   * @example
+   * ```ts
+   * await mapRef.current?.queryRenderedFeatures([100, 100, 400, 400], {
+   *   filter: ["==", "type", "Point"],
+   *   layers: ["restaurants", "shops"],
+   * });
+   * ```
    */
   queryRenderedFeatures(
     pixelPointBounds: PixelPointBounds,
@@ -201,15 +228,15 @@ export interface MapRef {
   /**
    * Query rendered features within the current viewport
    *
-   * @example
-   * await mapRef.current?.queryRenderedFeatures(
-   *   {
-   *     filter: ["==", "type", "Point"],
-   *     layers: ["restaurants", "shops"],
-   *   },
-   * );
+   * @returns Queried features
    *
-   * @return Queried features
+   * @example
+   * ```ts
+   * await mapRef.current?.queryRenderedFeatures({
+   *   filter: ["==", "type", "Point"],
+   *   layers: ["restaurants", "shops"],
+   * });
+   * ```
    */
   queryRenderedFeatures(
     options?: QueryRenderedFeaturesOptions,
@@ -218,21 +245,22 @@ export interface MapRef {
   /**
    * Takes static-map image of the currently displayed map
    *
-   * @param options.output Use "base64" to get a Base64 encoded string, or "file" to get a URI to an image file saved on disk
-   *
-   * @return Base64 encoded image or URI of image file
+   * @returns Base64 encoded image or URI of image file
    */
   createStaticMapImage(options: { output: "base64" | "file" }): Promise<string>;
 
   /**
-   * Sets the visibility of all the layers referencing the specified `source` and optionally `sourceLayer`
-   *
-   * @example
-   * await mapRef.current?.setSourceVisibility(false, 'composite', 'building')
+   * Sets the visibility of all the layers referencing the specified `source` and
+   * optionally `sourceLayer`
    *
    * @param visible - Visibility of the layers
    * @param source - Identifier of the target source (e.g. 'composite')
    * @param sourceLayer - Identifier of the target source-layer (e.g. 'building')
+   *
+   * @example
+   * ```ts
+   * await mapRef.current?.setSourceVisibility(false, "composite", "building");
+   * ```
    */
   setSourceVisibility(
     visible: boolean,
@@ -248,20 +276,18 @@ export interface MapRef {
   showAttribution(): Promise<void>;
 }
 
-export interface MapProps extends BaseProps {
-  children?: ReactNode;
-
+export interface MapProps extends BaseProps, ViewProps {
   /**
    * Style for wrapping React Native View
    *
-   * @default { flex: 1 }
+   * @defaultValue { flex: 1 }
    */
   style?: ViewProps["style"];
 
   /**
    * Maplibre style - either a URL or a Style JSON.
    *
-   * @see https://maplibre.org/maplibre-style-spec/
+   * @see {@link https://maplibre.org/maplibre-style-spec/}
    */
   mapStyle: string | StyleSpecification;
 
@@ -270,51 +296,73 @@ export interface MapProps extends BaseProps {
    * Controls the light source for extruded geometries.
    *
    * @example
+   * ```tsx
    * light={{ position: [1.5, 90, 80], color: "#ffffff", intensity: 0.5 }}
+   * ```
    */
   light?: LightSpecification;
 
   /**
-   * The distance from the edges of the map view's frame to the edges of the map view's logical viewport.
+   * The distance from the edges of the map view's frame to the edges of the map
+   * view's logical viewport.
    */
   contentInset?: ViewPadding;
 
   /**
-   * iOS: The preferred frame rate at which the map view is rendered.
-   * The default value for this property is MLNMapViewPreferredFramesPerSecondDefault,
+   * **iOS**: The preferred frame rate at which the map view is rendered. The
+   * default value for this property is MLNMapViewPreferredFramesPerSecondDefault,
    * which will adaptively set the preferred frame rate based on the capability of
-   * the user’s device to maintain a smooth experience. This property can be set to arbitrary integer values.
+   * the user’s device to maintain a smooth experience. This property can be set
+   * to arbitrary integer values.
    *
-   * Android: The maximum frame rate at which the map view is rendered, but it can't excess the ability of device hardware.
-   * This property can be set to arbitrary integer values.
+   * **Android**: The maximum frame rate at which the map view is rendered, but it
+   * can't exceed the ability of device hardware. This property can be set to
+   * arbitrary integer values.
    */
   preferredFramesPerSecond?: number;
 
   /**
    * Toggle pan interaction of the map
    *
-   * @default true
+   * @defaultValue true
    */
   dragPan?: boolean;
 
   /**
-   * Toggle zoom interaction of the map
+   * Toggle pinch/scroll zoom interaction of the map.
+   *
+   * On Android this also disables {@link doubleTapZoom} and {@link doubleTapHoldZoom}.
    *
-   * @default true
+   * @defaultValue true
    */
-  touchAndDoubleTapZoom?: boolean;
+  touchZoom?: boolean;
+
+  /**
+   * Toggle double-tap zoom interaction of the map.
+   *
+   * @defaultValue true
+   */
+  doubleTapZoom?: boolean;
+
+  /**
+   * Toggle double-tap-and-hold zoom interaction of the map (also known as quick
+   * zoom and one finger zoom).
+   *
+   * @defaultValue true
+   */
+  doubleTapHoldZoom?: boolean;
 
   /**
    * Toggle rotate interaction of the map
    *
-   * @default true
+   * @defaultValue true
    */
   touchRotate?: boolean;
 
   /**
    * Toggle pitch interaction of the map
    *
-   * @default true
+   * @defaultValue true
    */
   touchPitch?: boolean;
 
@@ -332,7 +380,9 @@ export interface MapProps extends BaseProps {
    * Positions the attribution button
    *
    * @example Position in the top-left corner
+   * ```ts
    * { top: 8, left: 8 }
+   * ```
    */
   attributionPosition?: OrnamentViewPosition;
 
@@ -345,7 +395,9 @@ export interface MapProps extends BaseProps {
    * Positions the logo
    *
    * @example Position in the top-left corner
+   * ```ts
    * { top: 8, left: 8 }
+   * ```
    */
   logoPosition?: OrnamentViewPosition;
 
@@ -358,22 +410,39 @@ export interface MapProps extends BaseProps {
    * Positions the compass
    *
    * @example Position in the top-left corner
+   * ```ts
    * { top: 8, left: 8 }
+   * ```
    */
   compassPosition?: OrnamentViewPosition;
 
   /**
    * Toggle the compass from hiding when facing north
    *
-   * @default true
+   * @defaultValue true
    */
   compassHiddenFacingNorth?: boolean;
 
+  /**
+   * Toggle the scale bar on the map
+   */
+  scaleBar?: boolean;
+
+  /**
+   * Positions the scale bar. Android only supports top-left corner.
+   *
+   * @example Position in the bottom-left corner
+   * ```ts
+   * { bottom: 8, left: 8 }
+   * ```
+   */
+  scaleBarPosition?: OrnamentViewPosition;
+
   /**
    * Android only: Switch between TextureView (default) and GLSurfaceView for
    * rendering the map
    *
-   * @default "surface"
+   * @defaultValue "surface"
    */
   androidView?: "surface" | "texture";
 
@@ -381,8 +450,8 @@ export interface MapProps extends BaseProps {
    * Called when a user presses the map
    *
    * If the event bubbles up from a child `Source` with an `onPress` handler the
-   * `features` will be included. The event will emit on `Map` and `Source`.
-   * To prevent this use `event.stopPropagation()` in the `Source` handler.
+   * `features` will be included. The event will emit on `Map` and `Source` . To
+   * prevent this use `event.stopPropagation()` in the `Source` handler.
    */
   onPress?: (
     event:
@@ -465,166 +534,164 @@ export interface MapProps extends BaseProps {
    * Triggered when a style has finished loading
    */
   onDidFinishLoadingStyle?: (event: NativeSyntheticEvent<null>) => void;
+
+  /**
+   * Ref to access Map methods.
+   */
+  ref?: Ref<MapRef>;
 }
 
 /**
- * MapLibre Native Map
+ * A view of a MapLibre Native Map.
+ *
+ * @example Rendering a basic Map
+ * ```tsx
+ * <Map mapStyle="https://demotiles.maplibre.org/style.json" />;
+ * ```
  */
 export const Map = memo(
-  forwardRef<MapRef, MapProps>(
-    ({ androidView = "surface", style, ...props }, ref) => {
-      const [isReady, setIsReady] = useState(false);
-
-      const nativeRef = useRef<
-        Component<ComponentProps<typeof MapViewNativeComponent>> &
-          ReactNativeElement
-      >(null);
-
-      useImperativeHandle(ref, () => ({
-        getCenter: () =>
-          NativeMapViewModule.getCenter(findNodeHandle(nativeRef.current)),
-
-        getZoom: () =>
-          NativeMapViewModule.getZoom(findNodeHandle(nativeRef.current)),
-
-        getBearing: () =>
-          NativeMapViewModule.getBearing(findNodeHandle(nativeRef.current)),
-
-        getPitch: () =>
-          NativeMapViewModule.getPitch(findNodeHandle(nativeRef.current)),
-
-        getBounds: () =>
-          NativeMapViewModule.getBounds(findNodeHandle(nativeRef.current)),
-
-        getViewState: () =>
-          NativeMapViewModule.getViewState(
-            findNodeHandle(nativeRef.current),
-          ) as Promise<ViewState>,
-
-        project: (lngLat) =>
-          NativeMapViewModule.project(
-            findNodeHandle(nativeRef.current),
-            lngLat,
-          ),
-
-        unproject: (point) =>
-          NativeMapViewModule.unproject(
-            findNodeHandle(nativeRef.current),
-            point,
-          ),
-
-        queryRenderedFeatures: async (
-          pixelPointOrPixelPointBoundsOrOptions?:
-            | PixelPoint
-            | PixelPointBounds
-            | QueryRenderedFeaturesOptions,
-          options?: QueryRenderedFeaturesOptions,
-        ) => {
-          if (
-            pixelPointOrPixelPointBoundsOrOptions &&
-            Array.isArray(pixelPointOrPixelPointBoundsOrOptions) &&
-            ((value: PixelPoint | PixelPointBounds): value is PixelPoint =>
-              typeof value[0] === "number" && typeof value[1] === "number")(
-              pixelPointOrPixelPointBoundsOrOptions,
-            )
-          ) {
-            return await NativeMapViewModule.queryRenderedFeaturesWithPoint(
-              findNodeHandle(nativeRef.current),
-              pixelPointOrPixelPointBoundsOrOptions,
-              options?.layers ?? [],
-              getNativeFilter(options?.filter) as string[],
-            );
-          } else if (
-            pixelPointOrPixelPointBoundsOrOptions &&
-            Array.isArray(pixelPointOrPixelPointBoundsOrOptions) &&
-            ((
-              value: PixelPoint | PixelPointBounds,
-            ): value is PixelPointBounds =>
-              Array.isArray(value[0]) && Array.isArray(value[1]))(
-              pixelPointOrPixelPointBoundsOrOptions,
-            )
-          ) {
-            return await NativeMapViewModule.queryRenderedFeaturesWithBounds(
-              findNodeHandle(nativeRef.current),
-              pixelPointOrPixelPointBoundsOrOptions,
-              options?.layers ?? [],
-              getNativeFilter(options?.filter) as string[],
-            );
-          } else {
-            return await NativeMapViewModule.queryRenderedFeaturesWithBounds(
-              findNodeHandle(nativeRef.current),
-              null,
-              pixelPointOrPixelPointBoundsOrOptions?.layers ?? [],
-              getNativeFilter(
-                pixelPointOrPixelPointBoundsOrOptions?.filter,
-              ) as string[],
-            );
-          }
-        },
-
-        createStaticMapImage: (options) =>
-          NativeMapViewModule.createStaticMapImage(
+  ({ androidView = "surface", style, ref, ...props }: MapProps) => {
+    const [isReady, setIsReady] = useState(false);
+
+    const nativeRef = useRef<
+      Component<ComponentProps<typeof MapViewNativeComponent>> &
+        ReactNativeElement
+    >(null);
+
+    useImperativeHandle(ref, () => ({
+      getCenter: () =>
+        NativeMapViewModule.getCenter(findNodeHandle(nativeRef.current)),
+
+      getZoom: () =>
+        NativeMapViewModule.getZoom(findNodeHandle(nativeRef.current)),
+
+      getBearing: () =>
+        NativeMapViewModule.getBearing(findNodeHandle(nativeRef.current)),
+
+      getPitch: () =>
+        NativeMapViewModule.getPitch(findNodeHandle(nativeRef.current)),
+
+      getBounds: () =>
+        NativeMapViewModule.getBounds(findNodeHandle(nativeRef.current)),
+
+      getViewState: () =>
+        NativeMapViewModule.getViewState(
+          findNodeHandle(nativeRef.current),
+        ) as Promise<ViewState>,
+
+      project: (lngLat) =>
+        NativeMapViewModule.project(findNodeHandle(nativeRef.current), lngLat),
+
+      unproject: (point) =>
+        NativeMapViewModule.unproject(findNodeHandle(nativeRef.current), point),
+
+      queryRenderedFeatures: async (
+        pixelPointOrPixelPointBoundsOrOptions?:
+          | PixelPoint
+          | PixelPointBounds
+          | QueryRenderedFeaturesOptions,
+        options?: QueryRenderedFeaturesOptions,
+      ) => {
+        if (
+          pixelPointOrPixelPointBoundsOrOptions &&
+          Array.isArray(pixelPointOrPixelPointBoundsOrOptions) &&
+          ((value: PixelPoint | PixelPointBounds): value is PixelPoint =>
+            typeof value[0] === "number" && typeof value[1] === "number")(
+            pixelPointOrPixelPointBoundsOrOptions,
+          )
+        ) {
+          return await NativeMapViewModule.queryRenderedFeaturesWithPoint(
             findNodeHandle(nativeRef.current),
-            options.output,
-          ),
-
-        setSourceVisibility: (visible, source, sourceLayer) =>
-          NativeMapViewModule.setSourceVisibility(
+            pixelPointOrPixelPointBoundsOrOptions,
+            options?.layers ?? [],
+            getNativeFilter(options?.filter) as string[],
+          );
+        } else if (
+          pixelPointOrPixelPointBoundsOrOptions &&
+          Array.isArray(pixelPointOrPixelPointBoundsOrOptions) &&
+          ((value: PixelPoint | PixelPointBounds): value is PixelPointBounds =>
+            Array.isArray(value[0]) && Array.isArray(value[1]))(
+            pixelPointOrPixelPointBoundsOrOptions,
+          )
+        ) {
+          return await NativeMapViewModule.queryRenderedFeaturesWithBounds(
             findNodeHandle(nativeRef.current),
-            visible,
-            source,
-            sourceLayer ?? null,
-          ),
-
-        showAttribution: () =>
-          NativeMapViewModule.showAttribution(
+            pixelPointOrPixelPointBoundsOrOptions,
+            options?.layers ?? [],
+            getNativeFilter(options?.filter) as string[],
+          );
+        } else {
+          return await NativeMapViewModule.queryRenderedFeaturesWithBounds(
             findNodeHandle(nativeRef.current),
-          ),
-      }));
-
-      // Start before rendering
-      useLayoutEffect(() => {
-        LogManager.start();
-
-        return () => {
-          LogManager.stop();
-        };
-      }, []);
-
-      const nativeProps = useMemo(() => {
-        const { mapStyle, light, ...otherProps } = props;
-
-        return {
-          ...otherProps,
-          ref: nativeRef,
-          style: styles.flex1,
-          mapStyle:
-            typeof mapStyle === "object" ? JSON.stringify(mapStyle) : mapStyle,
-          light: props.light
-            ? transformStyle(convertToInternalStyle(props.light))
-            : undefined,
-        };
-      }, [props]);
-
-      let map: ReactElement | null = null;
-      if (isReady) {
-        const NativeMapView =
-          Platform.OS === "android" && androidView === "texture"
-            ? AndroidTextureMapViewNativeComponent
-            : MapViewNativeComponent;
-
-        map = <NativeMapView {...nativeProps} />;
-      }
-
-      return (
-        <View
-          onLayout={() => setIsReady(true)}
-          style={style ?? styles.flex1}
-          testID={nativeProps.testID ? `${nativeProps.testID}-view` : undefined}
-        >
-          {map}
-        </View>
-      );
-    },
-  ),
+            null,
+            pixelPointOrPixelPointBoundsOrOptions?.layers ?? [],
+            getNativeFilter(
+              pixelPointOrPixelPointBoundsOrOptions?.filter,
+            ) as string[],
+          );
+        }
+      },
+
+      createStaticMapImage: (options) =>
+        NativeMapViewModule.createStaticMapImage(
+          findNodeHandle(nativeRef.current),
+          options.output,
+        ),
+
+      setSourceVisibility: (visible, source, sourceLayer) =>
+        NativeMapViewModule.setSourceVisibility(
+          findNodeHandle(nativeRef.current),
+          visible,
+          source,
+          sourceLayer ?? null,
+        ),
+
+      showAttribution: () =>
+        NativeMapViewModule.showAttribution(findNodeHandle(nativeRef.current)),
+    }));
+
+    // Start before rendering
+    useLayoutEffect(() => {
+      LogManager.start();
+
+      return () => {
+        LogManager.stop();
+      };
+    }, []);
+
+    const nativeProps = useMemo(() => {
+      const { mapStyle, light, ...otherProps } = props;
+
+      return {
+        ...otherProps,
+        ref: nativeRef,
+        style: styles.flex1,
+        mapStyle:
+          typeof mapStyle === "object" ? JSON.stringify(mapStyle) : mapStyle,
+        light: props.light
+          ? transformStyle(convertToInternalStyle(props.light))
+          : undefined,
+      };
+    }, [props]);
+
+    let map: ReactElement | null = null;
+    if (isReady) {
+      const NativeMapView =
+        Platform.OS === "android" && androidView === "texture"
+          ? AndroidTextureMapViewNativeComponent
+          : MapViewNativeComponent;
+
+      map = <NativeMapView {...nativeProps} />;
+    }
+
+    return (
+      <View
+        onLayout={() => setIsReady(true)}
+        style={style ?? styles.flex1}
+        testID={nativeProps.testID ? `${nativeProps.testID}-view` : undefined}
+      >
+        {map}
+      </View>
+    );
+  },
 );