@maplibre/maplibre-react-native 11.0.0-beta.9 → 11.0.1

package/src/components/annotations/view-annotation/PointAnnotationNativeComponent.ts

@@ -38,8 +38,9 @@ export interface NativeProps extends ViewProps {
   anchor?: NativeAnchor;
   offset?: NativeOffset;
 
-  onSelected?: CodegenTypes.DirectEventHandler<NativeAnnotationEvent>;
-  onDeselected?: CodegenTypes.DirectEventHandler<NativeAnnotationEvent>;
+  onPress?: CodegenTypes.BubblingEventHandler<NativeAnnotationEvent>;
+  onSelect?: CodegenTypes.BubblingEventHandler<NativeAnnotationEvent>;
+  onDeselect?: CodegenTypes.BubblingEventHandler<NativeAnnotationEvent>;
   onDragStart?: CodegenTypes.DirectEventHandler<NativeAnnotationEvent>;
   onDrag?: CodegenTypes.DirectEventHandler<NativeAnnotationEvent>;
   onDragEnd?: CodegenTypes.DirectEventHandler<NativeAnnotationEvent>;

package/src/components/annotations/view-annotation/ViewAnnotation.tsx

@@ -40,24 +40,29 @@ export type NativeViewAnnotationRef = Component<
 > &
   ReactNativeElement;
 
+/**
+ * Event emitted by a ViewAnnotation on press.
+ */
 export type ViewAnnotationEvent = PressEvent & {
   id: string;
 };
 
 export interface ViewAnnotationProps {
   /**
-   * A string that uniquely identifies the annotation.
-   * If not provided, a unique ID will be generated automatically.
+   * A string that uniquely identifies the annotation. If not provided, a unique
+   * ID will be generated automatically.
    */
   id?: string;
 
   /**
-   * The string containing the annotation's title. Note this is required to be set if you want to see a callout appear on iOS.
+   * The string containing the annotation's title. Note this is required to be set
+   * if you want to see a callout appear on iOS.
    */
   title?: string;
 
   /**
-   * The string containing the annotation's snippet(subtitle). Not displayed in the default callout.
+   * The string containing the annotation's snippet(subtitle). Not displayed in
+   * the default callout.
    */
   snippet?: string;
 
@@ -69,7 +74,7 @@ export interface ViewAnnotationProps {
   /**
    * Enable or disable dragging.
    *
-   * @default false
+   * @defaultValue false
    */
   draggable?: boolean;
 
@@ -79,34 +84,38 @@ export interface ViewAnnotationProps {
   lngLat: LngLat;
 
   /**
-   * Specifies the anchor being set on a particular point of the annotation.
-   * The anchor indicates which part of the marker should be placed closest to the coordinate.
-   *
-   * @default "center"
+   * Specifies the anchor being set on a particular point of the annotation. The
+   * anchor indicates which part of the marker should be placed closest to the
+   * coordinate.
    *
-   * @see https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/PositionAnchor/
+   * @see {@link https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/PositionAnchor/}
+   * @defaultValue "center"
    */
   anchor?: Anchor;
 
   /**
-   * The offset in pixels to apply relative to the anchor.
-   * Negative values indicate left and up.
+   * The offset in pixels to apply relative to the anchor. Negative values
+   * indicate left and up.
    *
-   * @default [0, 0]
-   *
-   * @see https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MarkerOptions/#offset
+   * @see {@link https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MarkerOptions/#offset}
+   * @defaultValue [0, 0]
    */
   offset?: PixelPoint;
 
+  /**
+   * This callback is fired when the annotation is pressed.
+   */
+  onPress?: (event: NativeSyntheticEvent<ViewAnnotationEvent>) => void;
+
   /**
    * This callback is fired once this annotation is selected.
    */
-  onSelected?: (event: NativeSyntheticEvent<ViewAnnotationEvent>) => void;
+  onSelect?: (event: NativeSyntheticEvent<ViewAnnotationEvent>) => void;
 
   /**
    * This callback is fired once this annotation is deselected.
    */
-  onDeselected?: (event: NativeSyntheticEvent<ViewAnnotationEvent>) => void;
+  onDeselect?: (event: NativeSyntheticEvent<ViewAnnotationEvent>) => void;
 
   /**
    * This callback is fired once this annotation has started being dragged.
@@ -138,30 +147,27 @@ export interface ViewAnnotationProps {
 
 export interface ViewAnnotationRef {
   /**
-   * On android point annotation is rendered offscreen with a canvas into an image.
-   * To rerender the image from the current state of the view call refresh.
+   * On android point annotation is rendered offscreen with a canvas into an
+   * image. To rerender the image from the current state of the view call refresh.
    * Call this for example from Image#onLoad.
    */
   refresh(): void;
-
   /**
-   * Returns a reference to the native component for Reanimated compatibility.
-   * This method is used by Reanimated's createAnimatedComponent to determine
-   * which component should receive animated props.
-   *
-   * @see https://docs.swmansion.com/react-native-reanimated/docs/core/createAnimatedComponent/#component
+   * Returns the native ref for Reanimated v4 compatibility. Uses a Proxy to map
+   * _viewConfig to __viewConfig.
    */
   getAnimatableRef(): NativeViewAnnotationRef | null;
 }
 
 /**
- * ViewAnnotation represents a one-dimensional shape located at a single geographical coordinate.
+ * ViewAnnotation represents a one-dimensional shape located at a single
+ * geographical coordinate.
  *
- * Consider using GeoJSONSource and SymbolLayer instead, if you have many points, and you have static images,
- * they'll offer much better performance.
+ * Consider using GeoJSONSource and SymbolLayer instead, if you have many
+ * points, and you have static images, they'll offer much better performance.
  *
- * If you need interactive views please use Marker,
- * as with ViewAnnotation on Android child views are rendered onto a bitmap for better performance.
+ * If you need interactive views please use Marker, as with ViewAnnotation on
+ * Android child views are rendered onto a bitmap for better performance.
  */
 export const ViewAnnotation = ({
   id,
@@ -176,24 +182,24 @@ export const ViewAnnotation = ({
   const nativeOffset = offset ? { x: offset[0], y: offset[1] } : undefined;
   const nativeRef = useRef<NativeViewAnnotationRef>(null);
 
-  useImperativeHandle(
-    ref,
-    (): ViewAnnotationRef => ({
-      refresh,
-      getAnimatableRef: () => nativeRef.current,
-    }),
-  );
-
-  function refresh(): void {
-    if (Platform.OS === "android" && nativeRef.current) {
-      Commands.refresh(nativeRef.current);
-    }
-  }
+  useImperativeHandle(ref, () => ({
+    refresh: () => {
+      if (Platform.OS === "android" && nativeRef.current) {
+        Commands.refresh(nativeRef.current);
+      }
+    },
+    // Reanimated v4 compatibility: createAnimatedComponent looks for _viewConfig but native has __viewConfig
+    getAnimatableRef: () =>
+      nativeRef.current
+        ? new Proxy(nativeRef.current, {
+            get: (target, prop) =>
+              prop === "_viewConfig"
+                ? (target as unknown as { __viewConfig: unknown }).__viewConfig
+                : target[prop as keyof typeof target],
+          })
+        : null,
+  }));
 
-  // On Android, wrap children in a non-collapsable View to prevent Fabric
-  // from flattening the view hierarchy. Without this, Fabric may flatten
-  // intermediate Views, causing their backgrounds to disappear.
-  // We need to keep Callout separate so native code can identify it.
   const wrappedChildren = (() => {
     if (Platform.OS !== "android") {
       return props.children;

package/src/components/camera/Camera.tsx

@@ -1,8 +1,8 @@
 import {
   type Component,
   type ComponentProps,
-  forwardRef,
   memo,
+  type Ref,
   useImperativeHandle,
   useRef,
 } from "react";
@@ -19,6 +19,9 @@ import type { LngLat } from "../../types/LngLat";
 import type { LngLatBounds } from "../../types/LngLatBounds";
 import type { ViewPadding } from "../../types/ViewPadding";
 
+/**
+ * Camera viewport configuration: zoom, bearing, pitch, and padding.
+ */
 export interface CameraOptions {
   /**
    * The zoom level of the map.
@@ -26,7 +29,7 @@ export interface CameraOptions {
   zoom?: number;
 
   /**
-   *  The bearing (rotation) of the map.
+   * The bearing (rotation) of the map.
    */
   bearing?: number;
 
@@ -41,8 +44,14 @@ export interface CameraOptions {
   padding?: ViewPadding;
 }
 
+/**
+ * Easing function used for camera animations.
+ */
 export type CameraEasing = undefined | "linear" | "ease" | "fly";
 
+/**
+ * Animation timing options for camera transitions.
+ */
 export interface CameraAnimationOptions {
   /**
    * The duration the map takes to animate to a new configuration.
@@ -50,11 +59,14 @@ export interface CameraAnimationOptions {
   duration?: number;
 
   /**
-   *  The easing or path the camera uses to animate to a new configuration.
+   * The easing or path the camera uses to animate to a new configuration.
    */
   easing?: CameraEasing;
 }
 
+/**
+ * Camera center coordinate options.
+ */
 export interface CameraCenterOptions {
   /**
    * Geographic center coordinates of the map
@@ -62,6 +74,9 @@ export interface CameraCenterOptions {
   center: LngLat;
 }
 
+/**
+ * Camera bounds options.
+ */
 export interface CameraBoundsOptions {
   /**
    * The corners of a box around which the map should bound.
@@ -69,14 +84,24 @@ export interface CameraBoundsOptions {
   bounds: LngLatBounds;
 }
 
+/**
+ * Camera animation stop positioned by a center coordinate.
+ */
 export type CameraCenterStop = CameraOptions &
   CameraAnimationOptions &
   CameraCenterOptions;
 
+/**
+ * Camera animation stop positioned by geographic bounds.
+ */
 export type CameraBoundsStop = CameraOptions &
   CameraAnimationOptions &
   CameraBoundsOptions;
 
+/**
+ * A single camera animation stop — optionally positioned by center, bounds, or
+ * neither.
+ */
 export type CameraStop =
   | (CameraOptions &
       CameraAnimationOptions & {
@@ -86,6 +111,9 @@ export type CameraStop =
   | CameraCenterStop
   | CameraBoundsStop;
 
+/**
+ * Initial camera state when the map first loads.
+ */
 export type InitialViewState =
   | (CameraOptions & {
       center?: never;
@@ -94,8 +122,14 @@ export type InitialViewState =
   | (CameraOptions & CameraCenterOptions)
   | (CameraOptions & CameraBoundsOptions);
 
+/**
+ * User location tracking mode.
+ */
 export type TrackUserLocation = "default" | "heading" | "course";
 
+/**
+ * Event emitted when the user location tracking mode changes.
+ */
 export type TrackUserLocationChangeEvent = {
   trackUserLocation: TrackUserLocation | null;
 };
@@ -104,24 +138,20 @@ export interface CameraRef {
   /**
    * Map camera will move to new coordinates at the same zoom level
    *
-   * @example
-   * cameraRef.current?.easeTo([lng, lat], 200) // eases camera to new location based on duration
-   * cameraRef.current?.easeTo([lng, lat]) // snaps camera to new location without any easing
-   *
-   *  @param options.center Coordinates that map camera will move too
-   *  @param options.duration Duration of camera animation
+   * @example Jump to a position
+   * ```ts
+   * cameraRef.current?.jumpTo({ center: [lng, lat] });
+   * ```
    */
   jumpTo(options: CameraCenterOptions & CameraOptions): void;
 
   /**
    * Map camera will move to new coordinates at the same zoom level
    *
-   * @example
-   * cameraRef.current?.easeTo([lng, lat], 200) // eases camera to new location based on duration
-   * cameraRef.current?.easeTo([lng, lat]) // snaps camera to new location without any easing
-   *
-   *  @param options.center Coordinates that map camera will move too
-   *  @param options.duration Duration of camera animation
+   * @example Eases camera to new location based on duration
+   * ```ts
+   * cameraRef.current?.easeTo({ center: [lng, lat], duration: 200 });
+   * ```
    */
   easeTo(
     options: CameraCenterOptions & CameraOptions & CameraAnimationOptions,
@@ -131,11 +161,9 @@ export interface CameraRef {
    * Map camera will fly to new coordinate
    *
    * @example
-   * cameraRef.current?.flyTo([lng, lat])
-   * cameraRef.current?.flyTo([lng, lat], 12000)
-   *
-   *  @param options.center Coordinates that map camera will jump to
-   *  @param options.duration Duration of camera animation
+   * ```ts
+   * cameraRef.current?.flyTo({ center: [lng, lat], duration: 12000 });
+   * ```
    */
   flyTo(
     options: CameraCenterOptions & CameraOptions & CameraAnimationOptions,
@@ -145,13 +173,13 @@ export interface CameraRef {
    * Map camera transitions to fit provided bounds
    *
    * @example
-   * cameraRef.current?.fitBounds([west, south, east, north])
-   * cameraRef.current?.fitBounds([west, south, east, north], { top: 20, right: 20, bottom: 20, left: 20 }, 1000)
-   *
-   * @param bounds
-   * @param options
-   * @param options.padding Padding for the bounds
-   * @param options.duration Duration of camera animation
+   * ```ts
+   * cameraRef.current?.fitBounds(
+   *   [west, south, east, north],
+   *   { top: 20, right: 20, bottom: 20, left: 20 },
+   *   1000,
+   * );
+   * ```
    */
   fitBounds(
     bounds: LngLatBounds,
@@ -161,34 +189,39 @@ export interface CameraRef {
   /**
    * Map camera will zoom to specified level
    *
-   * @example
-   * cameraRef.current?.zoomTo(16)
-   * cameraRef.current?.zoomTo(16, 100)
+   * @param zoom - Zoom level that the map camera will animate too
+   * @param options - Options
    *
-   * @param zoom Zoom level that the map camera will animate too
-   * @param options Options
-   * @param options.duration Duration of camera movement
+   * @example
+   * ```ts
+   * cameraRef.current?.zoomTo(16, { duration: 100 });
+   * ```
    */
   zoomTo(zoom: number, options?: CameraOptions & CameraAnimationOptions): void;
 
   /**
    * Map camera will perform updates based on provided config. Advanced use only!
    *
+   * @param stop - Array of Camera stops
+   *
    * @example
+   * ```ts
    * cameraRef.current?.setStop({
    *   centerCoordinate: [lng, lat],
    *   zoomLevel: 16,
    *   duration: 2000,
-   * })
+   * });
+   * ```
    *
+   * @example
+   * ```ts
    * cameraRef.current?.setStop({
    *   stops: [
    *     { pitch: 45, duration: 200 },
    *     { heading: 180, duration: 300 },
-   *   ]
-   * })
-   *
-   *  @param stop Array of Camera stops
+   *   ],
+   * });
+   * ```
    */
   setStop(stop: CameraStop): Promise<void>;
 }
@@ -218,12 +251,13 @@ export type CameraProps = BaseProps &
     /**
      * The mode used to track the user location on the map:
      *
-     * - undefined: The user's location is not tracked
-     * - "default": Centers the user's location
-     * - "heading": Centers the user's location and uses the compass for bearing
-     * - "course": Centers the user's location and uses the direction of travel for bearing
+     * - `undefined`: The user's location is not tracked
+     * - `"default"`: Centers the user's location
+     * - `"heading"`: Centers the user's location and uses the compass for bearing
+     * - `"course"`: Centers the user's location and uses the direction of travel for
+     *   bearing
      *
-     * @default undefined
+     * @defaultValue undefined
      */
     trackUserLocation?: TrackUserLocation;
 
@@ -233,74 +267,78 @@ export type CameraProps = BaseProps &
     onTrackUserLocationChange?: (
       event: NativeSyntheticEvent<TrackUserLocationChangeEvent>,
     ) => void;
+
+    /**
+     * Ref to access Camera methods.
+     */
+    ref?: Ref<CameraRef>;
   };
 
+/**
+ * Controls the viewport of the Map.
+ */
 export const Camera = memo(
-  forwardRef<CameraRef, CameraProps>(
-    (
-      {
-        testID,
-        initialViewState,
-        minZoom,
-        maxZoom,
-        maxBounds,
-        trackUserLocation,
-        onTrackUserLocationChange,
-        ...stop
-      },
-      ref,
-    ) => {
-      const nativeRef = useRef<
-        Component<ComponentProps<typeof NativeCameraComponent>> &
-          ReactNativeElement
-      >(null);
-
-      const setStop: CameraRef["setStop"] = (stop) => {
-        const nodeHandle = findNodeHandle(nativeRef.current);
-
-        if (!nodeHandle) {
-          throw new Error(
-            "NativeCameraComponent ref is null, wait for the map being initialized",
-          );
-        }
-
-        return NativeCameraModule.setStop(nodeHandle, stop);
-      };
-
-      useImperativeHandle(ref, () => ({
-        setStop,
-
-        jumpTo: ({ center, ...options }) =>
-          setStop({ ...options, center, duration: 0, easing: undefined }),
-
-        easeTo: ({ center, duration = 500, easing = "ease", ...options }) =>
-          setStop({ ...options, center, duration, easing }),
-
-        flyTo: ({ center, duration = 2000, easing = "fly", ...options }) =>
-          setStop({ ...options, center, duration, easing }),
-
-        fitBounds: (
-          bounds,
-          { duration = 2000, easing = "fly", ...options } = {},
-        ) => setStop({ ...options, bounds, duration, easing }),
-
-        zoomTo: (zoom, { duration = 500, easing = "ease", ...options } = {}) =>
-          setStop({ ...options, zoom, duration, easing }),
-      }));
-
-      return (
-        <NativeCameraComponent
-          ref={nativeRef}
-          testID={testID}
-          stop={stop}
-          initialViewState={initialViewState}
-          minZoom={minZoom}
-          maxZoom={maxZoom}
-          maxBounds={maxBounds}
-          trackUserLocation={trackUserLocation}
-          onTrackUserLocationChange={onTrackUserLocationChange}
-        />
-      );
-    },
-  ),
+  ({
+    testID,
+    initialViewState,
+    minZoom,
+    maxZoom,
+    maxBounds,
+    trackUserLocation,
+    onTrackUserLocationChange,
+    ref,
+    ...stop
+  }: CameraProps) => {
+    const nativeRef = useRef<
+      Component<ComponentProps<typeof NativeCameraComponent>> &
+        ReactNativeElement
+    >(null);
+
+    const setStop: CameraRef["setStop"] = (stop) => {
+      const nodeHandle = findNodeHandle(nativeRef.current);
+
+      if (!nodeHandle) {
+        throw new Error(
+          "NativeCameraComponent ref is null, wait for the map being initialized",
+        );
+      }
+
+      return NativeCameraModule.setStop(nodeHandle, stop);
+    };
+
+    useImperativeHandle(ref, () => ({
+      setStop,
+
+      jumpTo: ({ center, ...options }) =>
+        setStop({ ...options, center, duration: 0, easing: undefined }),
+
+      easeTo: ({ center, duration = 500, easing = "ease", ...options }) =>
+        setStop({ ...options, center, duration, easing }),
+
+      flyTo: ({ center, duration = 2000, easing = "fly", ...options }) =>
+        setStop({ ...options, center, duration, easing }),
+
+      fitBounds: (
+        bounds,
+        { duration = 2000, easing = "fly", ...options } = {},
+      ) => setStop({ ...options, bounds, duration, easing }),
+
+      zoomTo: (zoom, { duration = 500, easing = "ease", ...options } = {}) =>
+        setStop({ ...options, zoom, duration, easing }),
+    }));
+
+    return (
+      <NativeCameraComponent
+        ref={nativeRef}
+        testID={testID}
+        stop={stop}
+        initialViewState={initialViewState}
+        minZoom={minZoom}
+        maxZoom={maxZoom}
+        maxBounds={maxBounds}
+        trackUserLocation={trackUserLocation}
+        onTrackUserLocationChange={onTrackUserLocationChange}
+      />
+    );
+  },
 );

package/src/components/images/Images.tsx

@@ -9,19 +9,27 @@ import {
 import ImagesNativeComponent, {
   type NativeImageEntry,
 } from "./ImagesNativeComponent";
+import "./NativeImagesModule";
 import { type BaseProps } from "../../types/BaseProps";
 
+/**
+ * An image source with optional SDF (Signed Distance Field) rendering mode.
+ */
 export type ImageSourceWithSdf = {
   source: ImageSourcePropType;
   sdf?: boolean;
 };
 
+/**
+ * A map image entry: a URL string, a native asset require, or an
+ * {@link ImageSourceWithSdf} object.
+ */
 export type ImageEntry = string | ImageRequireSource | ImageSourceWithSdf;
 
 export interface ImagesProps extends BaseProps {
   /**
-   * Specifies the images in key-value pairs required for the style.
-   * Keys are names used in style expressions (e.g., "customIcon").
+   * Specifies the images in key-value pairs required for the style. Keys are
+   * names used in style expressions (e.g., "customIcon").
    *
    * Values provide a `source`, which can be one of the following types:
    * - A string URL: `"https://example.com/icon.png"`
@@ -35,28 +43,28 @@ export interface ImagesProps extends BaseProps {
    * ```tsx
    * <Images
    *   images={{
-   *     remote: 'https://example.com/marker.png',
-   *     require: require('./marker.png'),
+   *     remote: "https://example.com/marker.png",
+   *     require: require("./marker.png"),
    *     native: "marker",
-   *     sdf: { source: require('./sdf-marker.png'), sdf: true },
+   *     sdf: { source: require("./sdf-marker.png"), sdf: true },
    *   }}
-   * />
+   * />;
    * ```
    */
   images: { [key: string]: ImageEntry };
 
   /**
-   * Called when a layer references an image that is not present in the style.
-   * You can use this to dynamically add images on demand.
+   * Called when a layer references an image that is not present in the style. You
+   * can use this to dynamically add images on demand.
    *
    * @example
    * ```tsx
    * <Images
    *   images={images}
    *   onImageMissing={(event) => {
-   *     setImages(prev => ({ ...prev, [event.nativeEvent.image]: fallbackIcon }));
+   *     setImages((prev) => ({ ...prev, [event.nativeEvent.image]: fallbackIcon }));
    *   }}
-   * />
+   * />;
    * ```
    */
   onImageMissing?: (event: NativeSyntheticEvent<{ image: string }>) => void;
@@ -65,8 +73,8 @@ export interface ImagesProps extends BaseProps {
 /**
  * Images defines the images used in Symbol layers.
  *
- * Use this component to add images to the map style that can be referenced
- * by symbol layers using the `iconImage` property.
+ * Use this component to add images to the map style that can be referenced by
+ * symbol layers using the `iconImage` property.
  */
 export const Images = ({ testID, images, onImageMissing }: ImagesProps) => {
   const nativeImages = useMemo(() => {

package/src/components/images/NativeImagesModule.ts

@@ -0,0 +1,11 @@
+import { Platform, type TurboModule } from "react-native";
+import { TurboModuleRegistry } from "react-native";
+
+export interface Spec extends TurboModule {}
+
+const imagesModule =
+  Platform.OS === "ios"
+    ? TurboModuleRegistry.getEnforcing<Spec>("MLRNImagesModule")
+    : null;
+
+export default imagesModule;