@maplibre/maplibre-react-native 11.0.0-beta.3 → 11.0.0-beta.31

package/src/components/camera/Camera.tsx

@@ -1,15 +1,15 @@
 import {
   type Component,
   type ComponentProps,
-  forwardRef,
   memo,
+  type Ref,
   useImperativeHandle,
   useRef,
 } from "react";
 import {
   findNodeHandle,
-  type NativeMethods,
   type NativeSyntheticEvent,
+  type ReactNativeElement,
 } from "react-native";
 
 import NativeCameraComponent from "./CameraNativeComponent";
@@ -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>> &
-          Readonly<NativeMethods>
-      >(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;