@maplibre/maplibre-react-native 11.0.0-alpha.15 → 11.0.0-alpha.17

package/src/components/user-location/NativeUserLocation.tsx

@@ -1,32 +1,28 @@
-import { requireNativeComponent } from "react-native";
+import UserLocationNativeComponent from "./UserLocationNativeComponent";
+import type { BaseProps } from "../../types/BaseProps";
 
-const NATIVE_MODULE_NAME = "MLRNNativeUserLocation";
-
-interface NativeUserLocationProps {
+interface NativeUserLocationProps extends BaseProps {
   /**
-   * Android render mode.
+   * Rendering mode
    *
-   *  - normal: just a circle
-   *  - compass: triangle with heading
-   *  - gps: large arrow
+   *  - "default": Renders only a puck
+   *  - "heading": Renders a puck with triangle indicating device heading based on compass
+   *  - "course": Android renders an arrow indicating device heading based on GPS course, iOS behaves like mode="heading"
    *
-   * @platform android
+   * @default "default"
    */
-  androidRenderMode?: "normal" | "compass" | "gps";
+  mode?: "default" | "heading" | "course";
+
   /**
-   * iOS only. A Boolean value indicating whether the user location annotation may display a permanent heading indicator.
+   * Limit the maximum frames per second for location updates on Android
    *
-   * @platform ios
-   */
-  iosShowsUserHeadingIndicator?: boolean;
-  /**
-   * Android only. Set max FPS at which location animators can output updates. Use this setting to limit animation rate of the location puck on higher zoom levels to decrease the stress on the device's CPU which can directly improve battery life, without sacrificing UX.
+   * Use this setting to limit animation rate of the location puck to decrease the stress on the device's CPU which could improve battery life.
+   *
+   * @platform android
    */
   androidPreferredFramesPerSecond?: number;
 }
 
 export const NativeUserLocation = (props: NativeUserLocationProps) => {
-  return <MLRNNativeUserLocation {...props} />;
+  return <UserLocationNativeComponent {...props} />;
 };
-
-const MLRNNativeUserLocation = requireNativeComponent(NATIVE_MODULE_NAME);

package/src/components/user-location/UserLocation.tsx

@@ -1,270 +1,86 @@
-import {
-  forwardRef,
-  memo,
-  type ReactNode,
-  useEffect,
-  useImperativeHandle,
-  useRef,
-  useState,
-} from "react";
+import { memo, type ReactNode, useMemo } from "react";
 
-import { NativeUserLocation } from "./NativeUserLocation";
 import { UserLocationPuck } from "./UserLocationPuck";
-import {
-  type GeolocationPosition,
-  LocationManager,
-} from "../../modules/location/LocationManager";
+import { useCurrentPosition } from "../../hooks/useCurrentPosition";
 import { Annotation } from "../annotations/Annotation";
 
-const USER_LOCATION_SOURCE_ID = "mlrn-user-location";
-
-interface UserLocationProps {
-  /**
-   * Whether location icon is animated between updates
-   */
-  animated?: boolean;
-  /**
-   * Which render mode to use.
-   * Can either be `normal` or `native`
-   */
-  renderMode?: "normal" | "native";
+export interface UserLocationProps {
   /**
-   * native/android only render mode
-   *
-   *  - normal: just a circle
-   *  - compass: triangle with heading
-   *  - gps: large arrow
-   *
-   * @platform android
+   * Children to render inside the UserLocation Annotation, e.g. CircleLayer, SymbolLayer
    */
-  androidRenderMode?: "normal" | "compass" | "gps";
-  /**
-   * Whether location icon is visible
-   */
-  visible?: boolean;
+  children?: ReactNode;
+
   /**
-   * Callback that is triggered on location icon press
+   * Whether the UserLocation Annotation is animated between updates
    */
-  onPress?: () => void;
+  animated?: boolean;
+
   /**
-   * Callback that is triggered on location update
+   * Render a circle which indicates the accuracy of the location
    */
-  onUpdate?: (location: GeolocationPosition) => void;
+  accuracy?: boolean;
+
   /**
-   * Show or hide small arrow which indicates direction the device is pointing relative to north.
+   * Render an arrow which indicates direction the device is pointing relative to north
    */
-  showsUserHeadingIndicator?: boolean;
+  heading?: boolean;
+
   /**
-   * Minimum amount of movement before GPS location is updated in meters
+   * Minimum delta in meters for location updates
    */
   minDisplacement?: number;
+
   /**
-   * Android only. Set max FPS at which location animators can output updates. Use this setting to limit animation rate of the location puck on higher zoom levels to decrease the stress on the device's CPU which can directly improve battery life, without sacrificing UX.
-   *
-   * @platform android
-   */
-  androidPreferredFramesPerSecond?: number;
-  /**
-   * Custom location icon of type mapbox-gl-native components
-   *
-   * NOTE: Forking maintainer does not understand the above comment.
+   * Event triggered on pressing the UserLocation Annotation
    */
-  children?: ReactNode;
-}
-
-interface UserLocationState {
-  shouldShowUserLocation: boolean;
-  coordinates?: number[];
-  heading?: number;
-}
-
-export enum UserLocationRenderMode {
-  Native = "native",
-  Normal = "normal",
-}
-
-export interface UserLocationRef {
-  setLocationManager: (props: { running: boolean }) => Promise<void>;
-  needsLocationManagerRunning: () => boolean;
-  _onLocationUpdate: (location: GeolocationPosition | undefined) => void;
+  onPress?: () => void;
 }
 
 export const UserLocation = memo(
-  forwardRef<UserLocationRef, UserLocationProps>(
-    (
-      {
-        animated = true,
-        visible = true,
-        showsUserHeadingIndicator = false,
-        minDisplacement = 0,
-        renderMode = "normal",
-        androidRenderMode,
-        androidPreferredFramesPerSecond,
-        children,
-        onUpdate,
-        onPress,
-      }: UserLocationProps,
-      ref,
-    ) => {
-      const _isMounted = useRef<boolean | null>(null);
-      const locationManagerRunning = useRef<boolean>(false);
-
-      const [userLocationState, setUserLocationState] =
-        useState<UserLocationState>({
-          shouldShowUserLocation: false,
-        });
-
-      useImperativeHandle(
-        ref,
-        (): UserLocationRef => ({
-          /**
-           * Whether to start or stop listening to the LocationManager
-           *
-           * Notice, that listening will start automatically when
-           * either `onUpdate` or `visible` are set
-           *
-           * @async
-           * @param {{running: boolean}} running - Object with key `running` and `boolean` value
-           * @return {Promise<void>}
-           */
-          setLocationManager,
-          /**
-           *
-           * If LocationManager should be running
-           *
-           * @return {boolean}
-           */
-          needsLocationManagerRunning,
-          _onLocationUpdate,
-        }),
-      );
-
-      useEffect(() => {
-        _isMounted.current = true;
-
-        setLocationManager({
-          running: needsLocationManagerRunning(),
-        }).then(() => {
-          if (renderMode === UserLocationRenderMode.Native) {
-            return;
-          }
-
-          LocationManager.setMinDisplacement(minDisplacement);
-        });
-
-        return (): void => {
-          _isMounted.current = false;
-          setLocationManager({ running: false });
-        };
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-      }, []);
-
-      useEffect(() => {
-        LocationManager.setMinDisplacement(minDisplacement);
-      }, [minDisplacement]);
-
-      useEffect(() => {
-        if (!_isMounted.current) {
-          return;
-        }
-
-        setLocationManager({
-          running: needsLocationManagerRunning(),
-        });
-      });
-
-      async function setLocationManager({
-        running,
-      }: {
-        running: boolean;
-      }): Promise<void> {
-        if (locationManagerRunning.current !== running) {
-          locationManagerRunning.current = running;
-
-          if (running) {
-            LocationManager.addListener(_onLocationUpdate);
-            const location = await LocationManager.getCurrentPosition();
-            _onLocationUpdate(location);
-          } else {
-            LocationManager.removeListener(_onLocationUpdate);
-          }
-        }
-      }
-
-      function needsLocationManagerRunning(): boolean {
-        return !!(
-          !!onUpdate ||
-          (renderMode === UserLocationRenderMode.Normal && visible)
-        );
-      }
-
-      function _onLocationUpdate(
-        location: GeolocationPosition | undefined,
-      ): void {
-        if (!_isMounted.current || !location) {
-          return;
-        }
-
-        let coordinates;
-        let heading;
-
-        if (location && location.coords) {
-          const { longitude, latitude } = location.coords;
-          heading = location.coords.heading;
-          coordinates = [longitude, latitude];
-        }
-
-        setUserLocationState({
-          ...userLocationState,
-          coordinates,
-          heading,
-        });
-
-        if (onUpdate) {
-          onUpdate(location);
-        }
-      }
-
-      if (!visible) {
-        return null;
-      }
-
-      if (renderMode === UserLocationRenderMode.Native) {
-        const props = {
-          androidRenderMode,
-          iosShowsUserHeadingIndicator: showsUserHeadingIndicator,
-          androidPreferredFramesPerSecond,
-        };
-
-        return <NativeUserLocation {...props} />;
-      }
-
-      if (!userLocationState.coordinates) {
-        return null;
-      }
-
-      return (
-        <Annotation
-          animated={animated}
-          id={USER_LOCATION_SOURCE_ID}
-          onPress={onPress}
-          coordinates={userLocationState.coordinates}
-          style={{
-            iconRotate: userLocationState.heading,
-          }}
-        >
-          {children || (
-            <UserLocationPuck
-              sourceID={USER_LOCATION_SOURCE_ID}
-              heading={
-                showsUserHeadingIndicator
-                  ? userLocationState.heading
-                  : undefined
-              }
-            />
-          )}
-        </Annotation>
-      );
-    },
-  ),
+  ({
+    animated = true,
+    accuracy = false,
+    heading = false,
+    minDisplacement,
+    children,
+    onPress,
+  }: UserLocationProps) => {
+    const currentPosition = useCurrentPosition({ minDisplacement });
+
+    const coordinates = useMemo(() => {
+      return currentPosition?.coords
+        ? [currentPosition.coords.longitude, currentPosition.coords.latitude]
+        : undefined;
+    }, [currentPosition?.coords]);
+
+    if (!coordinates || !currentPosition) {
+      return null;
+    }
+
+    return (
+      <Annotation
+        animated={animated}
+        id="mlrn-user-location"
+        testID="mlrn-user-location"
+        onPress={onPress}
+        coordinates={coordinates}
+        style={{
+          iconRotate: currentPosition.coords.heading ?? undefined,
+        }}
+      >
+        {children || (
+          <UserLocationPuck
+            testID="mlrn-user-location-puck"
+            sourceID="mlrn-user-location"
+            accuracy={accuracy ? currentPosition.coords.accuracy : undefined}
+            heading={
+              heading
+                ? (currentPosition.coords.heading ?? undefined)
+                : undefined
+            }
+          />
+        )}
+      </Annotation>
+    );
+  },
 );

package/src/components/user-location/UserLocationNativeComponent.ts

@@ -0,0 +1,19 @@
+import {
+  codegenNativeComponent,
+  type CodegenTypes,
+  type HostComponent,
+  type ViewProps,
+} from "react-native";
+
+export interface NativeProps extends ViewProps {
+  mode?: CodegenTypes.WithDefault<"default" | "heading" | "course", "default">;
+
+  androidPreferredFramesPerSecond?: CodegenTypes.WithDefault<
+    CodegenTypes.Int32,
+    -1
+  >;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  "MLRNNativeUserLocation",
+) as HostComponent<NativeProps>;

package/src/components/user-location/UserLocationPuck.tsx

@@ -7,12 +7,12 @@ import { CircleLayer } from "../layers/CircleLayer";
 
 const blue = "#33B5E5";
 
-const layerStyles: Record<"pulse" | "white" | "blue", CircleLayerStyle> = {
-  pulse: {
-    circleRadius: 15,
+const layerStyles = {
+  accuracy: {
     circleColor: blue,
     circleOpacity: 0.2,
     circlePitchAlignment: "map",
+    circleRadiusTransition: { duration: 300, delay: 0 },
   },
   white: {
     circleRadius: 9,
@@ -24,39 +24,58 @@ const layerStyles: Record<"pulse" | "white" | "blue", CircleLayerStyle> = {
     circleColor: blue,
     circlePitchAlignment: "map",
   },
-};
+} satisfies Record<"accuracy" | "white" | "blue", CircleLayerStyle>;
 
 interface UserLocationPuckProps extends BaseProps {
   sourceID: string;
+  accuracy?: number;
   heading?: number;
   belowLayerID?: string;
 }
 
 export const UserLocationPuck = memo(
-  ({ sourceID, heading }: UserLocationPuckProps) => (
-    <>
-      <CircleLayer
-        id="mlrn-user-location-puck-pulse"
-        sourceID={sourceID}
-        style={layerStyles.pulse}
-      />
-      <CircleLayer
-        id="mlrn-user-location-puck-white"
-        sourceID={sourceID}
-        style={layerStyles.white}
-      />
-      <CircleLayer
-        id="mlrn-user-location-puck-blue"
-        sourceID={sourceID}
-        style={layerStyles.blue}
-      />
-      {typeof heading === "number" && (
-        <UserLocationPuckHeading
+  ({ sourceID, accuracy, heading }: UserLocationPuckProps) => {
+    return (
+      <>
+        {typeof accuracy === "number" && (
+          <CircleLayer
+            id="mlrn-user-location-puck-accuracy"
+            testID="mlrn-user-location-puck-accuracy"
+            sourceID={sourceID}
+            style={{
+              ...layerStyles.accuracy,
+              circleRadius: [
+                "interpolate",
+                ["exponential", 2],
+                ["zoom"],
+                0,
+                layerStyles.white.circleRadius,
+                22,
+                layerStyles.white.circleRadius + accuracy * 100,
+              ],
+            }}
+          />
+        )}
+        <CircleLayer
+          id="mlrn-user-location-puck-white"
+          testID="mlrn-user-location-puck-white"
           sourceID={sourceID}
-          belowLayerID="mlrn-user-location-puck-white"
-          heading={heading}
+          style={layerStyles.white}
         />
-      )}
-    </>
-  ),
+        <CircleLayer
+          id="mlrn-user-location-puck-blue"
+          testID="mlrn-user-location-puck-blue"
+          sourceID={sourceID}
+          style={layerStyles.blue}
+        />
+        {typeof heading === "number" && (
+          <UserLocationPuckHeading
+            sourceID={sourceID}
+            belowLayerID="mlrn-user-location-puck-white"
+            heading={heading}
+          />
+        )}
+      </>
+    );
+  },
 );

package/src/components/user-location/UserLocationPuckHeading.tsx

@@ -22,11 +22,12 @@ export const UserLocationPuckHeading = memo(
   ({ sourceID, belowLayerID, heading }: UserLocationPuckHeadingProps) => (
     <SymbolLayer
       id="mlrn-user-location-puck-heading"
+      testID="mlrn-user-location-puck-heading"
       sourceID={sourceID}
       belowLayerID={belowLayerID}
       style={{
-        iconRotate: heading,
         ...layerStyle,
+        iconRotate: heading,
       }}
     />
   ),

package/src/hooks/useCurrentPosition.ts

@@ -0,0 +1,53 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+  type GeolocationPosition,
+  LocationManager,
+} from "../modules/location/LocationManager";
+
+interface UseCurrentPositionOptions {
+  /**
+   * Enable or disable position updates
+   *
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Minimum displacement in meters to trigger position update
+   *
+   * @default 0
+   */
+  minDisplacement?: number;
+}
+
+export function useCurrentPosition({
+  enabled = true,
+  minDisplacement,
+}: UseCurrentPositionOptions = {}) {
+  const [currentPosition, setCurrentPosition] = useState<GeolocationPosition>();
+
+  useEffect(() => {
+    if (minDisplacement !== undefined) {
+      LocationManager.setMinDisplacement(minDisplacement);
+    }
+  }, [minDisplacement]);
+
+  const handleUpdate = useCallback((position: GeolocationPosition) => {
+    setCurrentPosition(position);
+  }, []);
+
+  useEffect(() => {
+    if (enabled) {
+      LocationManager.addListener(handleUpdate);
+    }
+
+    return () => {
+      if (enabled) {
+        LocationManager.removeListener(handleUpdate);
+      }
+    };
+  }, [enabled, handleUpdate]);
+
+  return currentPosition;
+}

package/src/index.ts

@@ -28,11 +28,11 @@ export { PointAnnotation } from "./components/annotations/PointAnnotation";
 export type { PointAnnotationRef } from "./components/annotations/PointAnnotation";
 export { Annotation } from "./components/annotations/Annotation";
 export { Callout } from "./components/annotations/Callout";
-export {
-  UserLocation,
-  UserLocationRenderMode,
-} from "./components/user-location/UserLocation";
-export type { UserLocationRef } from "./components/user-location/UserLocation";
+
+export { UserLocation } from "./components/user-location/UserLocation";
+export { NativeUserLocation } from "./components/user-location/NativeUserLocation";
+export { useCurrentPosition } from "./hooks/useCurrentPosition";
+
 export { VectorSource } from "./components/sources/VectorSource";
 export { ShapeSource } from "./components/sources/ShapeSource";
 export type { ShapeSourceRef } from "./components/sources/ShapeSource";
@@ -53,7 +53,6 @@ export {
   LocationManager,
   type GeolocationPosition,
 } from "./modules/location/LocationManager";
-export { requestAndroidLocationPermissions } from "./modules/location/requestAndroidLocationPermissions";
 
 export { OfflineManager } from "./modules/offline/OfflineManager";
 export type { OfflinePackError } from "./modules/offline/OfflineManager";

package/src/modules/location/LocationManager.ts

@@ -26,7 +26,7 @@ interface GeolocationCoordinates {
   /**
    * Altitude in meters
    */
-  altitude: number;
+  altitude: number | null;
 
   /**
    * Accuracy for altitude in meters
@@ -36,12 +36,12 @@ interface GeolocationCoordinates {
   /**
    * Direction in which the device is traveling in degrees, relative to north
    */
-  heading: number;
+  heading: number | null;
 
   /**
    * Instantaneous speed of the device in meters per second
    */
-  speed: number;
+  speed: number | null;
 }
 
 export interface GeolocationPosition {

package/src/modules/location/NativeLocationModule.ts

@@ -5,10 +5,10 @@ type NativeGeolocationCoordinates = {
   longitude: CodegenTypes.Double;
   latitude: CodegenTypes.Double;
   accuracy: CodegenTypes.Double;
-  altitude: CodegenTypes.Double;
+  altitude: CodegenTypes.Double | null;
   altitudeAccuracy: CodegenTypes.Double | null;
-  heading: CodegenTypes.Double;
-  speed: CodegenTypes.Double;
+  heading: CodegenTypes.Double | null;
+  speed: CodegenTypes.Double | null;
 };
 
 type NativeGeolocationPosition = {

package/src/utils/animated/Animated.ts

@@ -1,8 +1,3 @@
-import {
-  type ForwardRefExoticComponent,
-  type MemoExoticComponent,
-  type RefAttributes,
-} from "react";
 import { Animated as RNAnimated } from "react-native";
 
 import { AnimatedCoordinatesArray } from "./AnimatedCoordinatesArray";
@@ -17,11 +12,7 @@ import { LineLayer } from "../../components/layers/LineLayer";
 import { RasterLayer } from "../../components/layers/RasterLayer";
 import { SymbolLayer } from "../../components/layers/SymbolLayer";
 import { ImageSource } from "../../components/sources/ImageSource";
-import {
-  ShapeSource,
-  type ShapeSourceProps,
-  type ShapeSourceRef,
-} from "../../components/sources/ShapeSource";
+import { ShapeSource } from "../../components/sources/ShapeSource";
 
 export const Animated = {
   // sources
@@ -43,21 +34,3 @@ export const Animated = {
   Shape: AnimatedShape,
   ExtractCoordinateFromArray: AnimatedExtractCoordinateFromArray,
 };
-
-type ShapeSourcePropsWithRef = ShapeSourceProps & RefAttributes<ShapeSourceRef>;
-
-type BaseShapeSourceComponent =
-  ForwardRefExoticComponent<ShapeSourcePropsWithRef>;
-
-type AnimatedShapeSourceType =
-  RNAnimated.AnimatedComponent<BaseShapeSourceComponent> &
-    MemoExoticComponent<BaseShapeSourceComponent>;
-
-/**
- * Manual typing is required for AnimatedShapeSource because the
- * following error:
- * `Type instantiation is excessively deep and possibly infinite.ts(2589)`
- */
-export const AnimatedShapeSource = RNAnimated.createAnimatedComponent(
-  ShapeSource,
-) as AnimatedShapeSourceType;