@maydon_tech/react-native-nitro-maps 0.1.0

package/src/specs/NitroMap.nitro.ts

@@ -0,0 +1,292 @@
+import type {
+  HybridView,
+  HybridViewMethods,
+  HybridViewProps,
+} from 'react-native-nitro-modules';
+import type {
+  Camera,
+  Coordinate,
+  EdgePadding,
+  MapBoundaries,
+  MapError,
+  MapPressEvent,
+  MapProvider,
+  MapStyle,
+  MapType,
+  Region,
+  RegionChangeEvent,
+} from '../types/map';
+import type {
+  ClusterConfig,
+  ClusterPressEvent,
+  MarkerData,
+  MarkerDragEvent,
+  MarkerPressEvent,
+} from '../types/marker';
+
+/**
+ * Props for the NitroMap component
+ */
+export interface NitroMapProps extends HybridViewProps {
+  /**
+   * Map provider to use for rendering.
+   * Currently only `'google'` is supported.
+   * @default 'google'
+   */
+  provider?: MapProvider;
+
+  /**
+   * Initial region to display when the map loads
+   * @example
+   * ```tsx
+   * initialRegion={{
+   *   latitude: 41.299496,
+   *   longitude: 69.240073,
+   *   latitudeDelta: 0.0922,
+   *   longitudeDelta: 0.0421,
+   * }}
+   * ```
+   */
+  initialRegion?: Region;
+
+  /**
+   * Show the user's current location on the map
+   * Requires location permissions
+   * @default false
+   */
+  showsUserLocation?: boolean;
+
+  /**
+   * Enable pinch-to-zoom gesture
+   * @default true
+   */
+  zoomEnabled?: boolean;
+
+  /**
+   * Enable pan/scroll gesture
+   * @default true
+   */
+  scrollEnabled?: boolean;
+
+  /**
+   * Enable rotation gesture (two-finger rotate)
+   * @default true
+   */
+  rotateEnabled?: boolean;
+
+  /**
+   * Enable 3D tilt gesture (two-finger vertical pan)
+   * @default true
+   */
+  pitchEnabled?: boolean;
+
+  /**
+   * Map display type
+   * - `'standard'` - Normal map with roads and labels
+   * - `'satellite'` - Satellite imagery
+   * - `'hybrid'` - Satellite with roads/labels overlay
+   * @default 'standard'
+   */
+  mapType?: MapType;
+
+  /**
+   * Custom JSON styling for the map
+   * @see https://mapstyle.withgoogle.com/
+   */
+  customMapStyle?: MapStyle;
+
+  /**
+   * Show the "my location" button on the map
+   * @default true
+   */
+  showsMyLocationButton?: boolean;
+
+  /**
+   * Configuration for marker clustering behavior
+   */
+  clusterConfig?: ClusterConfig;
+
+  /**
+   * Enable dark mode styling for the map
+   * @default false
+   */
+  darkMode?: boolean;
+
+  /**
+   * Called when the user taps on the map (not on a marker)
+   * @param event - Contains the coordinate and screen position of the tap
+   */
+  onPress?: (event: MapPressEvent) => void;
+
+  /**
+   * Called when the user long-presses on the map
+   * @param event - Contains the coordinate and screen position of the press
+   */
+  onLongPress?: (event: MapPressEvent) => void;
+
+  /**
+   * Called when the map has finished loading and is ready to use
+   */
+  onMapReady?: () => void;
+
+  /**
+   * Called continuously during region/camera changes
+   * Use for live updates while user is panning/zooming
+   * @param region - Current region information
+   */
+  onRegionChange?: (region: RegionChangeEvent) => void;
+
+  /**
+   * Called after region/camera change has completed
+   * Use for final updates after user finishes panning/zooming
+   * @param region - Final region information
+   */
+  onRegionChangeComplete?: (region: RegionChangeEvent) => void;
+
+  /**
+   * Called when any marker on the map is pressed
+   * @param event - Contains the marker ID and coordinate
+   */
+  onMarkerPress?: (event: MarkerPressEvent) => void;
+
+  /**
+   * Called when a draggable marker starts being dragged
+   * @param event - Contains the marker ID and starting coordinate
+   */
+  onMarkerDragStart?: (event: MarkerDragEvent) => void;
+
+  /**
+   * Called continuously while a marker is being dragged
+   * @param event - Contains the marker ID and current coordinate
+   */
+  onMarkerDrag?: (event: MarkerDragEvent) => void;
+
+  /**
+   * Called when a draggable marker is dropped (drag ends)
+   * @param event - Contains the marker ID and final coordinate
+   */
+  onMarkerDragEnd?: (event: MarkerDragEvent) => void;
+
+  /**
+   * Called when a cluster of markers is tapped
+   * @param event - Contains the cluster coordinate, marker IDs, and count
+   */
+  onClusterPress?: (event: ClusterPressEvent) => void;
+
+  /**
+   * Called when an error occurs in the map or marker operations
+   * @param error - Error information with code and message
+   */
+  onError?: (error: MapError) => void;
+}
+
+/**
+ * Methods available on the NitroMap ref
+ * Access via `mapRef.current?.methodName()`
+ */
+export interface NitroMapMethods extends HybridViewMethods {
+  /**
+   * Animate the map to a new region
+   * @param region - Target region to animate to
+   * @param duration - Animation duration in milliseconds (default: 500)
+   */
+  animateToRegion(region: Region, duration?: number): void;
+
+  /**
+   * Fit the map to show all provided coordinates
+   * @param coordinates - Array of coordinates to fit
+   * @param edgePadding - Optional padding from edges
+   * @param animated - Whether to animate the transition (default: true)
+   */
+  fitToCoordinates(
+    coordinates: Coordinate[],
+    edgePadding?: EdgePadding,
+    animated?: boolean
+  ): void;
+
+  /**
+   * Animate the camera to a specific position
+   * @param camera - Target camera configuration
+   * @param duration - Animation duration in milliseconds (default: 500)
+   */
+  animateCamera(camera: Camera, duration?: number): void;
+
+  /**
+   * Get the current camera position and configuration
+   * @returns Promise resolving to current Camera state
+   */
+  getCamera(): Promise<Camera>;
+
+  /**
+   * Set the camera position instantly (no animation)
+   * @param camera - Camera configuration to apply
+   */
+  setCamera(camera: Camera): void;
+
+  /**
+   * Apply a custom style to the map
+   * @param style - Map style array (pass undefined to reset to default)
+   */
+  setMapStyle(style?: MapStyle): void;
+
+  /**
+   * Get the current visible map boundaries
+   * @returns Promise resolving to northeast/southwest corners
+   */
+  getMapBoundaries(): Promise<MapBoundaries>;
+
+  /**
+   * Enable or disable dark mode styling
+   * @param enabled - Whether dark mode should be enabled
+   */
+  setIsDarkMode(enabled: boolean): void;
+
+  /**
+   * Add a single marker to the map
+   * @param marker - Full marker data configuration
+   */
+  addMarker(marker: MarkerData): void;
+
+  /**
+   * Add multiple markers at once (more efficient than multiple addMarker calls)
+   * @param markers - Array of marker data configurations
+   */
+  addMarkers(markers: MarkerData[]): void;
+
+  /**
+   * Update an existing marker's properties
+   * @param marker - Updated marker data (must include existing ID)
+   */
+  updateMarker(marker: MarkerData): void;
+
+  /**
+   * Remove a marker from the map
+   * @param id - ID of the marker to remove
+   */
+  removeMarker(id: string): void;
+
+  /**
+   * Select/highlight a marker (shows info window if available)
+   * @param id - ID of the marker to select
+   */
+  selectMarker(id: string): void;
+
+  /**
+   * Remove all markers from the map
+   */
+  clearMarkers(): void;
+
+  /**
+   * Enable or disable marker clustering
+   * @param enabled - Whether clustering should be enabled
+   */
+  setClusteringEnabled(enabled: boolean): void;
+
+  /**
+   * Force recalculation of clusters
+   * Call after dynamically adding/removing markers
+   */
+  refreshClusters(): void;
+}
+
+export type NitroMap = HybridView<NitroMapProps, NitroMapMethods>;

package/src/specs/NitroMapConfig.nitro.ts

@@ -0,0 +1,8 @@
+import { type HybridObject } from 'react-native-nitro-modules';
+import type { MapProvider } from '../types/map';
+
+export interface NitroMapConfig
+  extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  NitroMapInitialize(apiKey: string, provider: MapProvider): void;
+  IsNitroMapInitialized(): boolean;
+}

package/src/types/map.ts

@@ -0,0 +1,166 @@
+/**
+ * Geographic region definition
+ * Defines a rectangular region on the map using center point and deltas
+ */
+export type Region = {
+  /** Center latitude of the region */
+  latitude: number;
+  /** Center longitude of the region */
+  longitude: number;
+  /** Latitude span (height of visible region) */
+  latitudeDelta: number;
+  /** Longitude span (width of visible region) */
+  longitudeDelta: number;
+};
+
+/**
+ * Geographic coordinate (latitude/longitude pair)
+ */
+export type Coordinate = {
+  /** Latitude in degrees (-90 to 90) */
+  latitude: number;
+  /** Longitude in degrees (-180 to 180) */
+  longitude: number;
+};
+
+/**
+ * Map display type
+ * - `'standard'` - Normal map with roads and labels
+ * - `'satellite'` - Satellite imagery
+ * - `'hybrid'` - Satellite with roads/labels overlay
+ */
+export type MapType = 'standard' | 'satellite' | 'hybrid';
+
+/**
+ * Map provider to use for rendering.
+ * Currently only `'google'` is implemented. Apple and Yandex will be
+ * added once Google Maps is solid on both platforms.
+ * - `'google'` - Google Maps (iOS & Android) ✅
+ * - `'apple'` - Apple Maps (not yet implemented)
+ * - `'yandex'` - Yandex Maps (not yet implemented)
+ */
+export type MapProvider = 'google' | 'apple' | 'yandex';
+
+/**
+ * Screen point (x/y coordinates in pixels)
+ */
+export type Point = {
+  /** X coordinate in pixels */
+  x: number;
+  /** Y coordinate in pixels */
+  y: number;
+};
+
+/**
+ * Event data when map is pressed
+ */
+export type MapPressEvent = {
+  /** Geographic coordinates of the press location */
+  coordinate: Coordinate;
+  /** Screen position of the press in pixels */
+  position: Point;
+};
+
+/**
+ * Event data during map region changes
+ */
+export type RegionChangeEvent = {
+  /** The new/current region */
+  region: Region;
+  /** Whether the change was caused by user gesture */
+  isGesture: boolean;
+};
+
+/**
+ * Padding values for map edges (in pixels)
+ */
+export type EdgePadding = {
+  /** Top padding in pixels */
+  top: number;
+  /** Right padding in pixels */
+  right: number;
+  /** Bottom padding in pixels */
+  bottom: number;
+  /** Left padding in pixels */
+  left: number;
+};
+
+/**
+ * Camera position and orientation
+ */
+export type Camera = {
+  /** Center point the camera is looking at */
+  center: Coordinate;
+  /** Tilt angle in degrees (0 = looking straight down, 90 = looking at horizon) */
+  pitch: number;
+  /** Rotation/bearing in degrees (0 = north up) */
+  heading: number;
+  /** Altitude/elevation in meters */
+  altitude: number;
+  /** Zoom level (higher = closer) */
+  zoom: number;
+};
+
+/**
+ * Visible map boundaries (bounding box)
+ */
+export type MapBoundaries = {
+  /** Northeast corner of visible area */
+  northEast: Coordinate;
+  /** Southwest corner of visible area */
+  southWest: Coordinate;
+};
+
+/**
+ * Individual style element for Google Maps styling
+ */
+export type MapStyler = {
+  /** Color in hex format (e.g., "#FF0000") */
+  color?: string;
+  /** Visibility: "on", "off", or "simplified" */
+  visibility?: string;
+  /** Stroke/line weight in pixels */
+  weight?: number;
+  /** Color saturation adjustment (-100 to 100) */
+  saturation?: number;
+  /** Lightness adjustment (-100 to 100) */
+  lightness?: number;
+  /** Gamma adjustment (0.01 to 10.0) */
+  gamma?: number;
+};
+
+/**
+ * Map style element targeting specific features
+ * @see https://developers.google.com/maps/documentation/javascript/style-reference
+ */
+export type MapStyleElement = {
+  /** Feature type to style (e.g., "road", "water", "poi") */
+  featureType?: string;
+  /** Element type to style (e.g., "geometry", "labels") */
+  elementType?: string;
+  /** Style modifications to apply */
+  stylers: MapStyler[];
+};
+
+/**
+ * Complete map style definition
+ * Array of style elements to customize map appearance
+ * @example
+ * ```ts
+ * const darkStyle: MapStyle = [
+ *   { featureType: "all", stylers: [{ saturation: -100 }] },
+ *   { featureType: "water", stylers: [{ color: "#0e171d" }] }
+ * ];
+ * ```
+ */
+export type MapStyle = MapStyleElement[];
+
+/**
+ * Error reported from native map operations
+ */
+export type MapError = {
+  /** Error code identifying the type of error */
+  code: string;
+  /** Human-readable error description */
+  message: string;
+};