@maydon_tech/react-native-nitro-maps 0.1.4 → 0.2.0

package/src/specs/NitroMap.nitro.ts

@@ -13,8 +13,11 @@ import type {
   MapProvider,
   MapStyle,
   MapType,
+  Point,
   Region,
   RegionChangeEvent,
+  UserLocationChangeEvent,
+  UserTrackingMode,
 } from '../types/map';
 import type {
   ClusterConfig,
@@ -23,6 +26,7 @@ import type {
   MarkerDragEvent,
   MarkerPressEvent,
 } from '../types/marker';
+import type { PolylineData, PolygonData, CircleData } from '../types/overlay';
 
 /**
  * Props for the NitroMap component
@@ -49,6 +53,24 @@ export interface NitroMapProps extends HybridViewProps {
    */
   initialRegion?: Region;
 
+  /**
+   * Controlled region prop — moves the camera whenever the value changes.
+   *
+   * Unlike `initialRegion` (set once on mount) or the imperative
+   * `animateToRegion()` (called via ref), this is **declarative**:
+   * updating the state that feeds this prop re-renders and moves the camera.
+   *
+   * Pass `undefined` to stop controlling the region.
+   *
+   * @example
+   * ```tsx
+   * const [region, setRegion] = useState<Region>();
+   * <NitroMap region={region} />
+   * <Button onPress={() => setRegion({ latitude: 40.7, longitude: -74, latitudeDelta: 0.05, longitudeDelta: 0.05 })} />
+   * ```
+   */
+  region?: Region;
+
   /**
    * Show the user's current location on the map
    * Requires location permissions
@@ -90,21 +112,58 @@ export interface NitroMapProps extends HybridViewProps {
   mapType?: MapType;
 
   /**
-   * Custom JSON styling for the map
+   * Custom JSON styling for the map.
+   * Currently uses Google Maps JSON format. Future providers (Apple, Yandex)
+   * will need provider-specific styling approaches.
    * @see https://mapstyle.withgoogle.com/
    */
   customMapStyle?: MapStyle;
 
   /**
-   * Show the "my location" button on the map
+   * Configuration for marker clustering behavior
+   */
+  clusterConfig?: ClusterConfig;
+
+  /**
+   * Padding around the map edges to offset the map center and controls.
+   * Use when UI elements (navigation bars, bottom sheets) cover parts of the map.
+   * Values are in pixels (React Native logical pixels).
+   */
+  mapPadding: EdgePadding;
+
+  /**
+   * Show real-time traffic conditions overlay on the map.
+   * Displays colored road segments indicating traffic flow.
+   * @default false
+   */
+  showsTraffic?: boolean;
+
+  /**
+   * Show 3D building models on the map when zoomed in.
    * @default true
    */
-  showsMyLocationButton?: boolean;
+  showsBuildings?: boolean;
 
   /**
-   * Configuration for marker clustering behavior
+   * Show the compass indicator on the map.
+   * The compass appears when the map is rotated away from north.
+   * @default true
    */
-  clusterConfig?: ClusterConfig;
+  showsCompass?: boolean;
+
+  /**
+   * Minimum zoom level the user can zoom out to.
+   * Google Maps range: 1 (world) to 22 (building).
+   * @default 1
+   */
+  minZoom: number;
+
+  /**
+   * Maximum zoom level the user can zoom in to.
+   * Google Maps range: 1 (world) to 22 (building).
+   * @default 22
+   */
+  maxZoom: number;
 
   /**
    * Enable dark mode styling for the map
@@ -112,6 +171,41 @@ export interface NitroMapProps extends HybridViewProps {
    */
   darkMode?: boolean;
 
+  /**
+   * User tracking mode for automatic camera following.
+   * - `'none'` - No tracking (default)
+   * - `'follow'` - Camera follows the user's position
+   * - `'followWithHeading'` - Camera follows and rotates with heading
+   * Requires `showsUserLocation={true}`.
+   * @default 'none'
+   */
+  userTrackingMode?: UserTrackingMode;
+
+  /**
+   * Custom image URL for the user location marker.
+   * When set to a non-empty string, replaces the default blue dot with a custom marker.
+   * Supports remote URLs (https://) and local asset names.
+   * Set to `''` (empty string) to use the default blue dot.
+   * Requires `showsUserLocation={true}`.
+   * @default ''
+   */
+  userLocationImage: string;
+
+  /**
+   * Size of the custom user location marker in points.
+   * Only applies when `userLocationImage` is set.
+   * @default 40
+   */
+  userLocationSize: number;
+
+  /**
+   * Anchor point for the custom user location marker.
+   * Values are in 0-1 range: {x: 0, y: 0} = top-left, {x: 0.5, y: 0.5} = center.
+   * Only applies when `userLocationImage` is set.
+   * @default { x: 0.5, y: 0.5 }
+   */
+  userLocationAnchor?: Point;
+
   /**
    * Called when the user taps on the map (not on a marker)
    * @param event - Contains the coordinate and screen position of the tap
@@ -173,11 +267,84 @@ export interface NitroMapProps extends HybridViewProps {
    */
   onClusterPress?: (event: ClusterPressEvent) => void;
 
+  /**
+   * Called when a tappable polyline is tapped.
+   * Requires `tappable={true}` on the `<NitroPolyline>`.
+   * @param id - The polyline ID
+   */
+  onPolylinePress?: (id: string) => void;
+
+  /**
+   * Called when a tappable polygon is tapped.
+   * Requires `tappable={true}` on the `<NitroPolygon>`.
+   * @param id - The polygon ID
+   */
+  onPolygonPress?: (id: string) => void;
+
+  /**
+   * Called when a tappable circle is tapped.
+   * Requires `tappable={true}` on the `<NitroCircle>`.
+   * @param id - The circle ID
+   */
+  onCirclePress?: (id: string) => void;
+
   /**
    * Called when an error occurs in the map or marker operations
    * @param error - Error information with code and message
    */
   onError?: (error: MapError) => void;
+
+  /**
+   * Called when the user's location changes.
+   * Requires `showsUserLocation={true}`.
+   * @param event - Contains coordinate, accuracy, and heading
+   */
+  onUserLocationChange?: (event: UserLocationChangeEvent) => void;
+
+  /**
+   * Called when the library changes the tracking mode internally.
+   * For example, when the user pans the map during follow/heading mode,
+   * tracking is automatically disabled. Update your state accordingly:
+   *
+   * @example
+   * ```tsx
+   * onUserTrackingModeChange={(mode) => setTrackingMode(mode)}
+   * ```
+   */
+  onUserTrackingModeChange?: (mode: UserTrackingMode) => void;
+
+  /**
+   * Called when location services fail (e.g. permission denied, location unavailable).
+   * Requires `showsUserLocation={true}`.
+   *
+   * @example
+   * ```tsx
+   * onUserLocationError={(error) => {
+   *   if (error.code === 'LOCATION_PERMISSION_DENIED') {
+   *     showPermissionDialog();
+   *   }
+   * }}
+   * ```
+   */
+  onUserLocationError?: (error: MapError) => void;
+
+  /**
+   * Called when the map becomes fully idle — no pending animations,
+   * no active user gestures, all tiles loaded.
+   *
+   * **How it differs from `onRegionChangeComplete`:**
+   * - `onRegionChangeComplete` fires after each individual gesture or animation ends.
+   * - `onMapIdle` fires once when the map is completely settled.
+   *
+   * **Use case:** Fetch data for the visible region only after the user has
+   * finished navigating (not during every intermediate pan/zoom).
+   *
+   * @example
+   * ```tsx
+   * onMapIdle={() => fetchListingsForRegion(currentRegion)}
+   * ```
+   */
+  onMapIdle?: () => void;
 }
 
 /**
@@ -204,6 +371,19 @@ export interface NitroMapMethods extends HybridViewMethods {
     animated?: boolean
   ): void;
 
+  /**
+   * Fit the map to show markers by their IDs.
+   * Looks up marker coordinates internally.
+   * @param markerIds - Array of marker IDs to fit
+   * @param edgePadding - Optional padding from edges
+   * @param animated - Whether to animate the transition (default: true)
+   */
+  fitToSuppliedMarkers(
+    markerIds: string[],
+    edgePadding?: EdgePadding,
+    animated?: boolean
+  ): void;
+
   /**
    * Animate the camera to a specific position
    * @param camera - Target camera configuration
@@ -235,6 +415,34 @@ export interface NitroMapMethods extends HybridViewMethods {
    */
   getMapBoundaries(): Promise<MapBoundaries>;
 
+  /**
+   * Animate the camera to the user's current location.
+   * Requires `showsUserLocation={true}` and location permissions.
+   * No-op if the user's location is not yet available.
+   *
+   * @example
+   * ```tsx
+   * <TouchableOpacity onPress={() => mapRef.current?.centerOnUserLocation()}>
+   *   <Text>📍 My Location</Text>
+   * </TouchableOpacity>
+   * ```
+   */
+  centerOnUserLocation(): void;
+
+  /**
+   * Convert a geographic coordinate to a screen point.
+   * @param coordinate - Geographic coordinate (latitude/longitude)
+   * @returns Screen point in pixels (React Native logical pixels, not physical)
+   */
+  pointForCoordinate(coordinate: Coordinate): Point;
+
+  /**
+   * Convert a screen point to a geographic coordinate.
+   * @param point - Screen point in pixels (React Native logical pixels)
+   * @returns Geographic coordinate (latitude/longitude)
+   */
+  coordinateForPoint(point: Point): Coordinate;
+
   /**
    * Enable or disable dark mode styling
    * @param enabled - Whether dark mode should be enabled
@@ -271,6 +479,12 @@ export interface NitroMapMethods extends HybridViewMethods {
    */
   selectMarker(id: string): void;
 
+  /**
+   * Deselect the currently selected marker and dismiss its info window.
+   * No-op if no marker is selected.
+   */
+  deselectMarker(): void;
+
   /**
    * Remove all markers from the map
    */
@@ -287,6 +501,81 @@ export interface NitroMapMethods extends HybridViewMethods {
    * Call after dynamically adding/removing markers
    */
   refreshClusters(): void;
+
+  // ============ Polyline Methods ============
+
+  /**
+   * Add a polyline overlay to the map
+   * @param polyline - Polyline data configuration
+   */
+  addPolyline(polyline: PolylineData): void;
+
+  /**
+   * Update an existing polyline's properties
+   * @param polyline - Updated polyline data (must include existing ID)
+   */
+  updatePolyline(polyline: PolylineData): void;
+
+  /**
+   * Remove a polyline from the map
+   * @param id - ID of the polyline to remove
+   */
+  removePolyline(id: string): void;
+
+  /**
+   * Remove all polylines from the map
+   */
+  clearPolylines(): void;
+
+  // ============ Polygon Methods ============
+
+  /**
+   * Add a polygon overlay to the map
+   * @param polygon - Polygon data configuration
+   */
+  addPolygon(polygon: PolygonData): void;
+
+  /**
+   * Update an existing polygon's properties
+   * @param polygon - Updated polygon data (must include existing ID)
+   */
+  updatePolygon(polygon: PolygonData): void;
+
+  /**
+   * Remove a polygon from the map
+   * @param id - ID of the polygon to remove
+   */
+  removePolygon(id: string): void;
+
+  /**
+   * Remove all polygons from the map
+   */
+  clearPolygons(): void;
+
+  // ============ Circle Methods ============
+
+  /**
+   * Add a circle overlay to the map
+   * @param circle - Circle data configuration
+   */
+  addCircle(circle: CircleData): void;
+
+  /**
+   * Update an existing circle's properties
+   * @param circle - Updated circle data (must include existing ID)
+   */
+  updateCircle(circle: CircleData): void;
+
+  /**
+   * Remove a circle from the map
+   * @param id - ID of the circle to remove
+   */
+  removeCircle(id: string): void;
+
+  /**
+   * Remove all circles from the map
+   */
+  clearCircles(): void;
 }
 
 export type NitroMap = HybridView<NitroMapProps, NitroMapMethods>;

package/src/types/map.ts

@@ -112,7 +112,12 @@ export type MapBoundaries = {
 };
 
 /**
- * Individual style element for Google Maps styling
+ * Individual style modifier for map styling.
+ *
+ * **Provider note:** Currently uses Google Maps JSON styling format.
+ * Apple Maps and Yandex Maps use different styling APIs and will require
+ * a provider-specific adapter when implemented.
+ * @see https://developers.google.com/maps/documentation/javascript/style-reference
  */
 export type MapStyler = {
   /** Color in hex format (e.g., "#FF0000") */
@@ -130,7 +135,12 @@ export type MapStyler = {
 };
 
 /**
- * Map style element targeting specific features
+ * Map style element targeting specific map features.
+ *
+ * **Provider note:** Uses Google Maps JSON styling format (featureType/elementType/stylers).
+ * Future providers will need their own styling approach:
+ * - Apple Maps: `MKMapConfiguration` + visual features
+ * - Yandex Maps: Custom style format
  * @see https://developers.google.com/maps/documentation/javascript/style-reference
  */
 export type MapStyleElement = {
@@ -143,8 +153,8 @@ export type MapStyleElement = {
 };
 
 /**
- * Complete map style definition
- * Array of style elements to customize map appearance
+ * Complete map style definition (Google Maps JSON format).
+ * Array of style elements to customize map appearance.
  * @example
  * ```ts
  * const darkStyle: MapStyle = [
@@ -164,3 +174,25 @@ export type MapError = {
   /** Human-readable error description */
   message: string;
 };
+
+/**
+ * Event data when the user's location changes
+ */
+export type UserLocationChangeEvent = {
+  /** The user's updated geographic coordinate */
+  coordinate: Coordinate;
+  /** Accuracy of the location in meters (may be 0 if unavailable) */
+  accuracy: number;
+  /** Heading in degrees (0-360, 0 = north; -1 if unavailable) */
+  heading: number;
+  /** Speed in meters per second (-1 if unavailable) */
+  speed: number;
+};
+
+/**
+ * User tracking mode for the map camera
+ * - `'none'` - No automatic camera tracking
+ * - `'follow'` - Camera follows the user's location
+ * - `'followWithHeading'` - Camera follows and rotates based on heading
+ */
+export type UserTrackingMode = 'none' | 'follow' | 'followWithHeading';

package/src/types/marker.ts

@@ -4,37 +4,18 @@ import type { ColorValue } from '../utils/colors';
 /**
  * Visual style of the marker
  * - `'default'` - Standard Google Maps marker
- * - `'price'` - Simple price tag
  * - `'image'` - Custom image marker
  * - `'priceMarker'` - Full-featured price marker with currency
- * - `'reactView'` - React Native view marker (internal use by NitroCustomMarker)
- *
- * Note: For React Native views as markers, use the NitroCustomMarker component.
  */
 export type MarkerStyle = 'default' | 'image' | 'priceMarker';
 
 /**
- * Animation type for individual markers when they appear
+ * Animation type for markers when they appear on the map.
+ * Uses semantic intents — each provider maps to its best native animation.
  * - `'none'` - No animation
- * - `'pop'` - Pop/bounce effect
- * - `'fadeIn'` - Fade in animation
+ * - `'appear'` - Platform's native appear animation (iOS: pop, Android: drop)
  */
-export type MarkerAnimation = 'none' | 'pop' | 'fadeIn';
-
-/**
- * Animation style for cluster expand/collapse
- * - `'default'` - Standard Google Maps Utils animation
- * - `'bounce'` - Markers bounce when appearing
- * - `'scale'` - Scale up from 0 to full size
- * - `'fade'` - Fade in/out
- * - `'spring'` - Spring effect animation
- */
-export type ClusterAnimationStyle =
-  | 'default'
-  | 'bounce'
-  | 'scale'
-  | 'fade'
-  | 'spring';
+export type MarkerAnimation = 'none' | 'appear';
 
 /**
  * Style configuration for price markers
@@ -80,24 +61,6 @@ export type MarkerColor = {
   a: number;
 };
 
-/**
- * Configuration for price-style markers
- */
-export type PriceMarkerConfig = {
-  /** Price text to display */
-  price: string;
-  /** Background color */
-  backgroundColor: MarkerColor;
-  /** Text color */
-  textColor: MarkerColor;
-  /** Font size in pixels */
-  fontSize: number;
-  /** Corner radius in pixels */
-  cornerRadius: number;
-  /** Whether marker is in selected state */
-  selected: boolean;
-};
-
 /**
  * Configuration for image-style markers
  * Colors can be hex strings ("#FF0000", "#F00") or MarkerColor objects
@@ -129,7 +92,6 @@ export type MarkerConfig = {
   image?: ImageMarkerConfig;
   /** Price marker style config (when style is 'priceMarker') */
   priceMarker?: PriceMarkerStyle;
-  /** React view marker config (when style is 'reactView') */
 };
 
 /**
@@ -156,10 +118,23 @@ export type MarkerData = {
   anchor: Point;
   /** Visual configuration for the marker */
   config: MarkerConfig;
+  /** Accessibility label read by screen readers (VoiceOver / TalkBack) */
+  accessibilityLabel?: string;
   /** Whether this marker should be included in clustering */
   clusteringEnabled: boolean;
   /** Animation when marker appears */
   animation: MarkerAnimation;
+  /**
+   * Animation duration in seconds.
+   * @default 0.3
+   */
+  animationDuration: number;
+  /**
+   * Whether the marker should animate every time it reappears on the map
+   * (e.g., emerging from a cluster, scrolling back into viewport).
+   * When false, the animation only plays on the initial mount.
+   */
+  animateOnReappear: boolean;
 };
 
 /**
@@ -239,10 +214,15 @@ export type ClusterConfig = {
   borderColor?: ColorValue;
   /** Enable cluster animations @default true */
   animatesClusters?: boolean;
+  /**
+   * Whether cluster icons should animate every time they reappear
+   * (e.g., during pan/zoom re-clustering).
+   * When false, clusters only animate on first render.
+   * @default true
+   */
+  animateOnReappear?: boolean;
   /** Animation duration in seconds (e.g., 0.3) @default 0.3 */
   animationDuration?: number;
-  /** Animation style for cluster expand/collapse @default 'default' */
-  animationStyle?: ClusterAnimationStyle;
   /**
    * When true, clusters update live during pan/zoom gestures (throttled).
    * When false, clusters only update after the gesture ends (debounced).

package/src/types/overlay.ts

@@ -0,0 +1,77 @@
+import type { Coordinate } from './map';
+import type { MarkerColor } from './marker';
+
+/**
+ * Data structure for a polyline overlay on the map.
+ * Represents a line connecting multiple geographic points.
+ */
+export type PolylineData = {
+  /** Unique identifier for the polyline */
+  id: string;
+  /** Array of geographic coordinates that form the polyline path */
+  coordinates: Coordinate[];
+  /** Stroke color as RGBA */
+  strokeColor: MarkerColor;
+  /** Stroke width in pixels */
+  strokeWidth: number;
+  /** Whether the line follows Earth's curvature (great circle) */
+  geodesic: boolean;
+  /** Whether the line is dashed */
+  dashed: boolean;
+  /** Z-index for controlling overlay order */
+  zIndex: number;
+  /** Whether this overlay responds to tap events */
+  tappable: boolean;
+  /** Accessibility label read by screen readers (VoiceOver / TalkBack) */
+  accessibilityLabel?: string;
+};
+
+/**
+ * Data structure for a polygon overlay on the map.
+ * Represents a closed shape with fill and stroke.
+ */
+export type PolygonData = {
+  /** Unique identifier for the polygon */
+  id: string;
+  /** Array of geographic coordinates that form the polygon boundary */
+  coordinates: Coordinate[];
+  /** Optional array of holes — each hole is an array of coordinates cut out from the fill */
+  holes: Coordinate[][];
+  /** Fill color as RGBA */
+  fillColor: MarkerColor;
+  /** Stroke color as RGBA */
+  strokeColor: MarkerColor;
+  /** Stroke width in pixels */
+  strokeWidth: number;
+  /** Z-index for controlling overlay order */
+  zIndex: number;
+  /** Whether this overlay responds to tap events */
+  tappable: boolean;
+  /** Accessibility label read by screen readers (VoiceOver / TalkBack) */
+  accessibilityLabel?: string;
+};
+
+/**
+ * Data structure for a circle overlay on the map.
+ * Represents a circle with center, radius, and styling.
+ */
+export type CircleData = {
+  /** Unique identifier for the circle */
+  id: string;
+  /** Center coordinate of the circle */
+  center: Coordinate;
+  /** Radius in meters */
+  radius: number;
+  /** Fill color as RGBA */
+  fillColor: MarkerColor;
+  /** Stroke color as RGBA */
+  strokeColor: MarkerColor;
+  /** Stroke width in pixels */
+  strokeWidth: number;
+  /** Z-index for controlling overlay order */
+  zIndex: number;
+  /** Whether this overlay responds to tap events */
+  tappable: boolean;
+  /** Accessibility label read by screen readers (VoiceOver / TalkBack) */
+  accessibilityLabel?: string;
+};