refactor!:NativeUserLocation is deprecated use LocationPuck (#3222)

rnmapbox · Dec 1, 2023 · 9a2b9ac · 9a2b9ac
1 parent c0b52cc
commit 9a2b9ac
Show file tree

Hide file tree

Showing 7 changed files with 102 additions and 98 deletions.
diff --git a/__tests__/interface.test.js b/__tests__/interface.test.js
@@ -14,7 +14,8 @@ describe('Public Interface', () => {
       'Callout',
       'Camera',
       'UserLocation',
-      'NativeUserLocation',
+      'NativeUserLocation', // deprecated
+      'LocationPuck',
       'StyleImport',
       'Viewport',
       'CustomLocationProvider',

diff --git a/docs/docs.json b/docs/docs.json
@@ -3212,6 +3212,86 @@
       }
     ]
   },
+  "LocationPuck": {
+    "description": "Renders a puck on the map that shows the device's current location.",
+    "displayName": "LocationPuck",
+    "methods": [],
+    "props": [
+      {
+        "name": "androidRenderMode",
+        "required": false,
+        "type": "'normal' \\| 'compass' \\| 'gps'",
+        "default": "none",
+        "description": "Android render mode.\n\n - normal: just a circle\n - compass: triangle with heading\n - gps: large arrow\n\n@deprecated use `puckBearing` for source and `bearingImage` for image\n@platform android"
+      },
+      {
+        "name": "puckBearing",
+        "required": false,
+        "type": "'heading' \\| 'course'",
+        "default": "none",
+        "description": "The bearing of the puck.\n\n - heading: Orients the puck to match the direction in which the device is facing.\n - course: Orients the puck to match the direction in which the device is moving."
+      },
+      {
+        "name": "puckBearingEnabled",
+        "required": false,
+        "type": "boolean",
+        "default": "none",
+        "description": "Whether the puck rotates to track the bearing source."
+      },
+      {
+        "name": "iosShowsUserHeadingIndicator",
+        "required": false,
+        "type": "boolean",
+        "default": "none",
+        "description": "iOS only. A Boolean value indicating whether the user location annotation may display a permanent heading indicator.\n\n@platform ios\n@deprecated use `puckBearingEnabled={true} puckBrearing=\"heading\"` instead"
+      },
+      {
+        "name": "topImage",
+        "required": false,
+        "type": "string",
+        "default": "none",
+        "description": "The name of image to use as the top layer for the location indicator. Images component should define this image."
+      },
+      {
+        "name": "bearingImage",
+        "required": false,
+        "type": "string",
+        "default": "none",
+        "description": "The name of image to use as the middle layer for the location indicator. Images component should define this image."
+      },
+      {
+        "name": "shadowImage",
+        "required": false,
+        "type": "string",
+        "default": "none",
+        "description": "The name of image to use as the background for the location indicator. Images component should define this image."
+      },
+      {
+        "name": "scale",
+        "required": false,
+        "type": "T \\| Expression",
+        "default": "none",
+        "description": "The size of the images, as a scale factor applied to the size of the specified image. Supports expressions based on zoom.\n\n@example\n[\"interpolate\",[\"linear\"], [\"zoom\"], 10.0, 1.0, 20.0, 4.0]]\n@example\n2.0"
+      },
+      {
+        "name": "pulsing",
+        "required": false,
+        "type": "\\| {\n    /**\n     * Flag determining whether the pulsing circle animation.\n     */\n    isEnabled?: boolean;\n\n    /**\n     * The color of the pulsing circle.\n     */\n    color?: number \\| ColorValue;\n\n    /**\n     * Circle radius configuration for the pulsing circle animation.\n     *  - accuracy:  Pulsing circle animates with the `horizontalAccuracy` form the latest puck location.\n     *  - number: Pulsing circle should animate with the constant radius.\n     */\n    radius?: 'accuracy' \\| number;\n  }\n\\| 'default'",
+        "default": "none",
+        "description": "The configration parameters for sonar-like pulsing circle animation shown around the 2D puck."
+      },
+      {
+        "name": "visible",
+        "required": false,
+        "type": "boolean",
+        "default": "none",
+        "description": "Whether location icon is visible, defaults to true"
+      }
+    ],
+    "fileNameWithExt": "LocationPuck.tsx",
+    "relPath": "src/components/LocationPuck.tsx",
+    "name": "LocationPuck"
+  },
   "MapView": {
     "description": "MapView backed by Mapbox Native GL",
     "displayName": "MapView",
@@ -4344,86 +4424,6 @@
     "relPath": "src/components/Models.tsx",
     "name": "Models"
   },
-  "NativeUserLocation": {
-    "description": "",
-    "displayName": "NativeUserLocation",
-    "methods": [],
-    "props": [
-      {
-        "name": "androidRenderMode",
-        "required": false,
-        "type": "'normal' \\| 'compass' \\| 'gps'",
-        "default": "none",
-        "description": "Android render mode.\n\n - normal: just a circle\n - compass: triangle with heading\n - gps: large arrow\n\n@deprecated use `puckBearing` for source and `bearingImage` for image\n@platform android"
-      },
-      {
-        "name": "puckBearing",
-        "required": false,
-        "type": "'heading' \\| 'course'",
-        "default": "none",
-        "description": "The bearing of the puck.\n\n - heading: Orients the puck to match the direction in which the device is facing.\n - course: Orients the puck to match the direction in which the device is moving."
-      },
-      {
-        "name": "puckBearingEnabled",
-        "required": false,
-        "type": "boolean",
-        "default": "none",
-        "description": "Whether the puck rotates to track the bearing source."
-      },
-      {
-        "name": "iosShowsUserHeadingIndicator",
-        "required": false,
-        "type": "boolean",
-        "default": "none",
-        "description": "iOS only. A Boolean value indicating whether the user location annotation may display a permanent heading indicator.\n\n@platform ios\n@deprecated use `puckBearingEnabled={true} puckBrearing=\"heading\"` instead"
-      },
-      {
-        "name": "topImage",
-        "required": false,
-        "type": "string",
-        "default": "none",
-        "description": "The name of image to use as the top layer for the location indicator. Images component should define this image."
-      },
-      {
-        "name": "bearingImage",
-        "required": false,
-        "type": "string",
-        "default": "none",
-        "description": "The name of image to use as the middle layer for the location indicator. Images component should define this image."
-      },
-      {
-        "name": "shadowImage",
-        "required": false,
-        "type": "string",
-        "default": "none",
-        "description": "The name of image to use as the background for the location indicator. Images component should define this image."
-      },
-      {
-        "name": "scale",
-        "required": false,
-        "type": "T \\| Expression",
-        "default": "none",
-        "description": "The size of the images, as a scale factor applied to the size of the specified image. Supports expressions based on zoom.\n\n@example\n[\"interpolate\",[\"linear\"], [\"zoom\"], 10.0, 1.0, 20.0, 4.0]]\n@example\n2.0"
-      },
-      {
-        "name": "pulsing",
-        "required": false,
-        "type": "\\| {\n    /**\n     * Flag determining whether the pulsing circle animation.\n     */\n    isEnabled?: boolean;\n\n    /**\n     * The color of the pulsing circle.\n     */\n    color?: number \\| ColorValue;\n\n    /**\n     * Circle radius configuration for the pulsing circle animation.\n     *  - accuracy:  Pulsing circle animates with the `horizontalAccuracy` form the latest puck location.\n     *  - number: Pulsing circle should animate with the constant radius.\n     */\n    radius?: 'accuracy' \\| number;\n  }\n\\| 'default'",
-        "default": "none",
-        "description": "The configration parameters for sonar-like pulsing circle animation shown around the 2D puck."
-      },
-      {
-        "name": "visible",
-        "required": false,
-        "type": "boolean",
-        "default": "none",
-        "description": "Whether location icon is visible, defaults to true"
-      }
-    ],
-    "fileNameWithExt": "NativeUserLocation.tsx",
-    "relPath": "src/components/NativeUserLocation.tsx",
-    "name": "NativeUserLocation"
-  },
   "PointAnnotation": {
     "description": "PointAnnotation represents a one-dimensional shape located at a single geographical coordinate.\n\nConsider using ShapeSource and SymbolLayer instead, if you have many points and static images,\nthey'll offer much better performance.\n\nIf you need interactive views please use MarkerView because PointAnnotation will render children onto a bitmap.\nAlso disable any kind of animations like `fadeDuration` of `Image`.\nOtherwise, the bitmap might be rendered at an unknown state of the animation.",
     "displayName": "PointAnnotation",

diff --git a/docs/examples.json b/docs/examples.json
@@ -113,11 +113,11 @@
         "metadata": {
           "title": "Custom Native UserLocation",
           "tags": [
-            "NativeUserLocation",
-            "NativeUserLocation#topImage",
-            "NativeUserLocation#scale"
+            "LocationPuck",
+            "LocationPuck#topImage",
+            "LocationPuck#scale"
           ],
-          "docs": "\n  Demonstrates use of images to customize NativeUserLocation\n  "
+          "docs": "\n  Demonstrates use of images to customize LocationPuck\n  "
         },
         "fullPath": "example/src/examples/UserLocation/CustomNativeUserLocation.tsx",
         "relPath": "UserLocation/CustomNativeUserLocation.tsx",

diff --git a/example/src/examples/UserLocation/CustomNativeUserLocation.tsx b/example/src/examples/UserLocation/CustomNativeUserLocation.tsx
@@ -4,7 +4,7 @@ import {
   MapView,
   Camera,
   UserTrackingMode,
-  NativeUserLocation,
+  LocationPuck,
   Images,
   Image,
 } from '@rnmapbox/maps';
@@ -40,7 +40,7 @@ const UserLocationNativeAnimated = () => {
           followUserMode={UserTrackingMode.Follow}
           followZoomLevel={14}
         />
-        <NativeUserLocation
+        <LocationPuck
           topImage="topImage"
           visible={true}
           scale={['interpolate', ['linear'], ['zoom'], 10, 1.0, 20, 4.0]}
@@ -59,13 +59,9 @@ export default UserLocationNativeAnimated;
 
 const metadata: ExampleWithMetadata['metadata'] = {
   title: 'Custom Native UserLocation',
-  tags: [
-    'NativeUserLocation',
-    'NativeUserLocation#topImage',
-    'NativeUserLocation#scale',
-  ],
+  tags: ['LocationPuck', 'LocationPuck#topImage', 'LocationPuck#scale'],
   docs: `
-  Demonstrates use of images to customize NativeUserLocation
+  Demonstrates use of images to customize LocationPuck
   `,
 };
 UserLocationNativeAnimated.metadata = metadata;
diff --git a/src/Mapbox.ts b/src/Mapbox.ts
@@ -19,7 +19,7 @@ export {
   default as UserLocation,
   UserLocationRenderMode,
 } from './components/UserLocation';
-export { default as NativeUserLocation } from './components/NativeUserLocation';
+export { default as LocationPuck } from './components/LocationPuck';
 export { default as VectorSource } from './components/VectorSource';
 export { ShapeSource } from './components/ShapeSource';
 export { default as RasterSource } from './components/RasterSource';
@@ -87,6 +87,7 @@ import { deprecatedClass } from './utils/deprecation';
 import { AnimatedPoint } from './classes';
 import { UserTrackingMode } from './components/Camera';
 import MovePointShapeAnimator from './shape_animators/MovePointShapeAnimator';
+import LocationPuck from './components/LocationPuck';
 
 /** @deprecated This will be removed in a future release. Use `AnimatedPoint` instead. */
 
@@ -95,6 +96,9 @@ export const AnimatedMapPoint = deprecatedClass(
   'AnimatedMapPoint is deprecated please use AnimatedPoint',
 );
 
+/** @deprecated NativeUserLocation will be removed in future release. Use `LocationPuck` instead. */
+export const NativeUserLocation = LocationPuck;
+
 // types:
 export enum StyleURL {
   Street = 'mapbox://styles/mapbox/streets-v11',

diff --git a/src/components/NativeUserLocation.tsx → src/components/LocationPuck.tsx b/src/components/NativeUserLocation.tsx → src/components/LocationPuck.tsx
@@ -101,13 +101,16 @@ const defaultProps = {
   visible: true,
 } as const;
 
-const NativeUserLocation = memo((props: Props) => {
+/**
+ * Renders a puck on the map that shows the device's current location.
+ */
+const LocationPuck = memo((props: Props) => {
   const { iosShowsUserHeadingIndicator, pulsing, ...rest } = props;
   const nativePulsing = pulsing ? _pulsingToNative(pulsing) : undefined;
   let baseProps: NativeProps = { ...defaultProps, pulsing: nativePulsing };
   if (iosShowsUserHeadingIndicator) {
     console.warn(
-      'NativeUserLocation: iosShowsUserHeadingIndicator is deprecated, use puckBearingEnabled={true} puckBearing="heading" instead',
+      'LocationPuck: iosShowsUserHeadingIndicator is deprecated, use puckBearingEnabled={true} puckBearing="heading" instead',
     );
 
     baseProps = {
@@ -137,4 +140,4 @@ function _pulsingToNative(
   };
 }
 
-export default NativeUserLocation;
+export default LocationPuck;
diff --git a/src/components/UserLocation.tsx b/src/components/UserLocation.tsx
@@ -7,7 +7,7 @@ import { CircleLayerStyle } from '../Mapbox';
 import Annotation from './Annotation';
 import CircleLayer from './CircleLayer';
 import HeadingIndicator from './HeadingIndicator';
-import NativeUserLocation from './NativeUserLocation';
+import NativeUserLocation from './LocationPuck';
 
 const mapboxBlue = 'rgba(51, 181, 229, 100)';