react-native-google-maps-plus 1.10.2-dev.1 → 1.10.2-dev.2

package/src/RNGoogleMapsPlusView.nitro.ts

@@ -1,30 +1,30 @@
 import type {
   RNCamera,
   RNCameraUpdate,
+  RNCircle,
+  RNHeatmap,
+  RNIndoorBuilding,
+  RNIndoorLevel,
+  RNInitialProps,
+  RNKMLayer,
   RNLatLng,
-  RNMapPadding,
-  RNPolygon,
-  RNPolyline,
-  RNUserInterfaceStyle,
+  RNLatLngBounds,
+  RNLocation,
+  RNLocationConfig,
   RNLocationErrorCode,
-  RNMarker,
   RNLocationPermissionResult,
-  RNRegion,
-  RNLocation,
   RNMapErrorCode,
+  RNMapPadding,
   RNMapType,
-  RNInitialProps,
-  RNCircle,
   RNMapUiSettings,
-  RNLocationConfig,
   RNMapZoomConfig,
-  RNHeatmap,
-  RNKMLayer,
-  RNIndoorBuilding,
-  RNIndoorLevel,
-  RNLatLngBounds,
+  RNMarker,
+  RNPolygon,
+  RNPolyline,
+  RNRegion,
   RNSnapshotOptions,
   RNUrlTileOverlay,
+  RNUserInterfaceStyle,
 } from './types';
 import type {
   HybridView,
@@ -32,58 +32,150 @@ import type {
   HybridViewProps,
 } from 'react-native-nitro-modules';
 
+/**
+ * Native Google Maps view props.
+ * Direct mapping to Google Maps SDK for Android/iOS.
+ * Platform differences remain unless explicitly aligned.
+ */
 export interface RNGoogleMapsPlusViewProps extends HybridViewProps {
   initialProps?: RNInitialProps;
   uiSettings?: RNMapUiSettings;
+
+  /** Enables "My Location" blue dot. */
   myLocationEnabled?: boolean;
+
+  /** Enables 3D buildings. */
   buildingEnabled?: boolean;
+
+  /** Enables traffic layer. */
   trafficEnabled?: boolean;
+
+  /** Enables indoor maps. */
   indoorEnabled?: boolean;
+
+  /**
+   * JSON map style string.
+   * Must be a Google Maps StyleSpec JSON.
+   */
   customMapStyle?: string;
+
+  /** Overrides OS UI mode. See {@link RNUserInterfaceStyle}. */
   userInterfaceStyle?: RNUserInterfaceStyle;
+
+  /** Zoom range. See {@link RNMapZoomConfig}. */
   mapZoomConfig?: RNMapZoomConfig;
+
+  /** Map padding. See {@link RNMapPadding}. */
   mapPadding?: RNMapPadding;
+
+  /** Base map type. See {@link RNMapType}. */
   mapType?: RNMapType;
+
+  /** Markers. See {@link RNMarker}. */
   markers?: RNMarker[];
+
+  /** Polygons. See {@link RNPolygon}. */
   polygons?: RNPolygon[];
+
+  /** Polylines. See {@link RNPolyline}. */
   polylines?: RNPolyline[];
+
+  /** Circles. See {@link RNCircle}. */
   circles?: RNCircle[];
+
+  /** Heatmaps. See {@link RNHeatmap}. */
   heatmaps?: RNHeatmap[];
+
+  /** KML layers. See {@link RNKMLayer}. */
   kmlLayers?: RNKMLayer[];
+
+  /** URL tile overlays. See {@link RNUrlTileOverlay}. */
   urlTileOverlays?: RNUrlTileOverlay[];
+
+  /** Location subsystem config. See {@link RNLocationConfig}. */
   locationConfig?: RNLocationConfig;
+
+  /** Map SDK error. */
   onMapError?: (error: RNMapErrorCode) => void;
+
+  /** Native map instance created. */
   onMapReady?: (ready: boolean) => void;
+
+  /** First frame rendered. */
   onMapLoaded?: (region: RNRegion, camera: RNCamera) => void;
+
+  /** Location update. */
   onLocationUpdate?: (location: RNLocation) => void;
+
+  /** Location subsystem error. */
   onLocationError?: (error: RNLocationErrorCode) => void;
+
+  /** Tap on map. */
   onMapPress?: (coordinate: RNLatLng) => void;
+
+  /** Long-press on map. */
   onMapLongPress?: (coordinate: RNLatLng) => void;
+
+  /** Tap on POI. */
   onPoiPress?: (placeId: string, name: string, coordinate: RNLatLng) => void;
+
+  /** Tap on marker. */
   onMarkerPress?: (id: string) => void;
+
+  /** Tap on polyline. */
   onPolylinePress?: (id: string) => void;
+
+  /** Tap on polygon. */
   onPolygonPress?: (id: string) => void;
+
+  /** Tap on circle. */
   onCirclePress?: (id: string) => void;
+
+  /** Marker drag start. */
   onMarkerDragStart?: (id: string, location: RNLatLng) => void;
+
+  /** Marker drag update. */
   onMarkerDrag?: (id: string, location: RNLatLng) => void;
+
+  /** Marker drag end. */
   onMarkerDragEnd?: (id: string, location: RNLatLng) => void;
-  onIndoorBuildingFocused?: (indoorBuilding: RNIndoorBuilding) => void;
-  onIndoorLevelActivated?: (indoorLevel: RNIndoorLevel) => void;
+
+  /** Indoor building focused. */
+  onIndoorBuildingFocused?: (building: RNIndoorBuilding) => void;
+
+  /** Indoor level activated. */
+  onIndoorLevelActivated?: (level: RNIndoorLevel) => void;
+
+  /** Info window tap. */
   onInfoWindowPress?: (id: string) => void;
+
+  /** Info window closed. */
   onInfoWindowClose?: (id: string) => void;
+
+  /** Info window long-press. */
   onInfoWindowLongPress?: (id: string) => void;
+
+  /** Tap on the blue My-Location indicator. */
   onMyLocationPress?: (location: RNLocation) => void;
+
+  /** Tap on the My-Location button. */
   onMyLocationButtonPress?: (pressed: boolean) => void;
+
+  /** Camera move started. */
   onCameraChangeStart?: (
     region: RNRegion,
     camera: RNCamera,
     isGesture: boolean
   ) => void;
+
+  /** Camera moving. */
   onCameraChange?: (
     region: RNRegion,
     camera: RNCamera,
     isGesture: boolean
   ) => void;
+
+  /** Camera idle. */
   onCameraChangeComplete?: (
     region: RNRegion,
     camera: RNCamera,
@@ -91,17 +183,30 @@ export interface RNGoogleMapsPlusViewProps extends HybridViewProps {
   ) => void;
 }
 
+/**
+ * Imperative Google Maps methods.
+ * Direct calls into native Google Maps SDK.
+ */
 export interface RNGoogleMapsPlusViewMethods extends HybridViewMethods {
   showMarkerInfoWindow(id: string): void;
-
   hideMarkerInfoWindow(id: string): void;
 
+  /**
+   * Sets the camera.
+   * iOS: adds an explicit animation phase for parity.
+   * Android: uses native timing.
+   */
   setCamera(
     camera: RNCameraUpdate,
     animated?: boolean,
     durationMs?: number
   ): void;
 
+  /**
+   * Fits the camera to the given coordinates.
+   * iOS: adds an explicit animation phase for parity.
+   * Android: uses native timing.
+   */
   setCameraToCoordinates(
     coordinates: RNLatLng[],
     padding?: RNMapPadding,
@@ -109,8 +214,14 @@ export interface RNGoogleMapsPlusViewMethods extends HybridViewMethods {
     durationMs?: number
   ): void;
 
+  /** Restricts camera target bounds. */
   setCameraBounds(bounds?: RNLatLngBounds): void;
 
+  /**
+   * Animates camera to bounds.
+   * iOS: adds an explicit animation phase for parity.
+   * Android: uses native timing.
+   */
   animateToBounds(
     bounds: RNLatLngBounds,
     padding?: number,
@@ -118,17 +229,31 @@ export interface RNGoogleMapsPlusViewMethods extends HybridViewMethods {
     lockBounds?: boolean
   ): void;
 
+  /** Snapshot of current frame. */
   snapshot(options: RNSnapshotOptions): Promise<string | undefined>;
 
+  /** Native location-settings dialog. */
   showLocationDialog(): void;
 
+  /**
+   * Opens the OS location settings.
+   * iOS: opens the app settings.
+   * Android: opens system location settings.
+   */
   openLocationSettings(): void;
 
+  /** Requests runtime location permission. */
   requestLocationPermission(): Promise<RNLocationPermissionResult>;
 
+  /**
+   * Checks Google Play Services availability.
+   * iOS: always returns false.
+   * Android: performs a real system check.
+   */
   isGooglePlayServicesAvailable(): boolean;
 }
 
+/** Typed hybrid Google Maps view. */
 export type RNGoogleMapsPlusView = HybridView<
   RNGoogleMapsPlusViewProps,
   RNGoogleMapsPlusViewMethods

package/src/index.tsx

@@ -1,4 +1,93 @@
-import { GoogleMapsView, GoogleMapsModule } from './GoogleMapsPlus';
+/**
+ * @packageDocumentation
+ *
+ * # Installation
+ *
+ * `react-native-nitro-modules` is required as this library relies on Nitro Modules.
+ *
+ * ```sh
+ * yarn add react-native-google-maps-plus react-native-nitro-modules
+ * ```
+ *
+ * ## iOS Setup (Bare RN only)
+ *
+ * Add this to your Podfile:
+ *
+ * ```ruby
+ * post_install do |installer|
+ *   react_native_post_install(
+ *       installer,
+ *       config[:reactNativePath],
+ *       :mac_catalyst_enabled => false,
+ *     )
+ *
+ *   require_relative '../node_modules/react-native-google-maps-plus/scripts/svgkit_patch'
+ *   apply_svgkit_patch(installer)
+ * end
+ * ```
+ *
+ * ## Expo Setup
+ *
+ * Add your keys via the config plugin:
+ *
+ * ```json
+ * {
+ *   "expo": {
+ *     "plugins": [
+ *       [
+ *         "react-native-google-maps-plus",
+ *         {
+ *           "googleMapsAndroidApiKey": "YOUR_ANDROID_MAPS_API_KEY",
+ *           "googleMapsIosApiKey": "YOUR_IOS_MAPS_API_KEY"
+ *         }
+ *       ]
+ *     ]
+ *   }
+ * }
+ * ```
+ *
+ * # API Keys
+ *
+ * You need a valid Google Maps API key.
+ *
+ * Android Guide:
+ * https://developers.google.com/maps/documentation/android-sdk/config
+ *
+ * iOS Guide:
+ * https://developers.google.com/maps/documentation/ios-sdk/config
+ *
+ *
+ * # Native Dependencies
+ *
+ * - iOS Google Maps SDK
+ *   https://developers.google.com/maps/documentation/ios-sdk
+ *
+ * - Android Google Maps SDK
+ *   https://developers.google.com/maps/documentation/android-sdk
+ *
+ * - SVG Rendering
+ *   iOS: SVGKit
+ *   Android: AndroidSVG
+ *
+ *
+ * # Usage Example
+ *
+ * ```tsx
+ * <GoogleMapsView
+ *   style={{ flex: 1 }}
+ *   initialProps={{
+ *     camera: {
+ *       center: { latitude: 37.7749, longitude: -122.4194 },
+ *       zoom: 12,
+ *     },
+ *   }}
+ * />
+ * ```
+ *
+ * Check out the example app in the [example directory](https://github.com/pinpong/react-native-google-maps-plus/tree/main/example).
+ */
+
+import { GoogleMapsModule, GoogleMapsView } from './GoogleMapsPlus';
 
 import type { RNGoogleMapsPlusModule } from './RNGoogleMapsPlusModule.nitro';
 import type {