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

package/src/components/NitroMap.tsx

@@ -27,9 +27,10 @@ import type {
   MarkerPressEvent,
   MarkerColor,
 } from '../types/marker';
-import type { MapStyle } from '../types/map';
-import { getDefaultProvider } from '../modules';
-import { parseColor, Colors } from '../utils/colors';
+import type { EdgePadding, MapProvider, MapStyle } from '../types/map';
+import type { ThemeForProvider } from '../types/theme';
+import { IsNitroMapInitialized } from '../modules';
+import { parseColor, areColorsEqual, Colors } from '../utils/colors';
 
 // Re-export all types
 export * from '../specs/NitroMap.nitro';
@@ -45,18 +46,118 @@ const NitroMapHostComponent = getHostComponent<
   NitroMapMethods
 >('NitroMap', () => NitroMapConfig);
 
-// Extended props with style and children
-export interface NitroMapProps
-  extends Omit<NitroMapPropsSpec, 'style' | 'hybridRef'> {
+// Sentinel region meaning "not set / cleared".
+// Fabric sends `null` when a previously-set optional prop is removed from JSX,
+// and the Nitro SDK's JSIConverter only handles `undefined`, not `null` — crash.
+// React also strips `undefined` prop values (treats them as absent).
+// Workaround: always pass region/initialRegion and use a sentinel with negative
+// deltas that the native side recognizes as "no-op".
+const REGION_UNSET = {
+  latitude: 0,
+  longitude: 0,
+  latitudeDelta: -1,
+  longitudeDelta: -1,
+};
+
+// Default "disabled" cluster config — always passed to native so the prop is
+// never removed (same Fabric null workaround as REGION_UNSET).
+const CLUSTER_CONFIG_DISABLED = {
+  enabled: false,
+  strategy: 'supercluster' as const,
+  radius: 80,
+  minimumClusterSize: 2,
+  maxZoom: 20,
+  backgroundColor: Colors.blue,
+  textColor: Colors.white,
+  borderWidth: 2,
+  borderColor: Colors.white,
+  animatesClusters: true,
+  animateOnReappear: true,
+  animationDuration: 0.3,
+  realtimeClustering: false,
+  renderBuffer: 0,
+  throttleInterval: 150,
+};
+
+// Extended props with style and children.
+// minZoom, maxZoom, mapPadding are non-optional in the Nitro spec (ADR-009)
+// but optional for consumers — we apply defaults in the component.
+//
+// Generic parameter P narrows the `theme` prop to the correct type for
+// the chosen provider. Defaults to 'google' when provider is omitted.
+export interface NitroMapProps<P extends MapProvider = 'google'>
+  extends Omit<
+    NitroMapPropsSpec,
+    | 'style'
+    | 'hybridRef'
+    | 'minZoom'
+    | 'maxZoom'
+    | 'mapPadding'
+    | 'customMapStyle'
+    | 'provider'
+    | 'userLocationImage'
+    | 'userLocationSize'
+  > {
   style?: StyleProp<ViewStyle>;
   children?: React.ReactNode;
+
+  /**
+   * Map provider to use. Typed as generic `P` so that `theme` narrows
+   * to the correct provider-specific type.
+   * @default 'google'
+   */
+  provider?: P;
+  /** Minimum zoom level (1 = world). @default 1 */
+  minZoom?: number;
+  /** Maximum zoom level (22 = building). @default 22 */
+  maxZoom?: number;
+  /** URL or asset name for custom user location icon. @default '' */
+  userLocationImage?: string;
+  /** Size of the custom user location icon in points. @default 40 */
+  userLocationSize?: number;
+  /**
+   * Padding around map edges to offset center and controls.
+   * Pass a single number for uniform padding on all sides,
+   * or an EdgePadding object for per-side control.
+   * @default {0,0,0,0}
+   */
+  mapPadding?: number | EdgePadding;
+
+  /**
+   * Provider-aware map theme. The accepted type depends on the `provider` prop:
+   * - `'google'` → `GoogleMapTheme` (JSON style array)
+   * - `'apple'` → `AppleMapTheme` (configuration object) — Phase 3
+   * - `'yandex'` → `YandexMapTheme` (style URI / night mode) — Phase 4
+   *
+   * @example
+   * ```tsx
+   * // Google — JSON style array
+   * <NitroMap provider="google" theme={[
+   *   { featureType: 'water', stylers: [{ color: '#0e171d' }] },
+   * ]} />
+   *
+   * // Apple (future) — configuration object
+   * <NitroMap provider="apple" theme={{
+   *   colorScheme: 'dark',
+   *   emphasisStyle: 'muted',
+   * }} />
+   * ```
+   */
+  theme?: ThemeForProvider[P];
+
+  /**
+   * @deprecated Use `theme` instead. `customMapStyle` only supports Google Maps
+   * JSON format and will be removed in a future version.
+   */
+  customMapStyle?: MapStyle;
 }
 
 // Ref type
 export type NitroMapRef = NitroMapMethods;
 
 /**
- * NitroMap - High-performance Google Maps component with native markers
+ * NitroMap - High-performance map component with native markers.
+ * Supports multiple providers (Google, Apple, Yandex) with type-safe theming.
  */
 const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
   (
@@ -65,6 +166,7 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
       children,
       provider,
       initialRegion,
+      region,
       showsUserLocation = false,
       zoomEnabled = true,
       scrollEnabled = true,
@@ -72,8 +174,13 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
       pitchEnabled = true,
       darkMode = false,
       mapType = 'standard',
-      showsMyLocationButton = false,
       clusterConfig,
+      mapPadding,
+      showsTraffic = false,
+      showsBuildings = true,
+      showsCompass = true,
+      minZoom,
+      maxZoom,
       onPress,
       onLongPress,
       onMapReady,
@@ -84,77 +191,96 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
       onMarkerDrag,
       onMarkerDragEnd,
       onClusterPress,
+      onPolylinePress,
+      onPolygonPress,
+      onCirclePress,
+      onUserLocationChange,
+      onUserTrackingModeChange,
+      onUserLocationError,
+      onMapIdle,
       onError,
+      userTrackingMode = 'none',
+      userLocationImage = '',
+      userLocationSize = 40,
+      userLocationAnchor = { x: 0.5, y: 0.5 },
+      theme,
+      customMapStyle,
       ...rest
     },
     ref
   ) => {
+    // Dev-mode warning for unimplemented providers
+    if (__DEV__ && provider && provider !== 'google') {
+      console.warn(
+        `[NitroMap] Provider "${provider}" is not yet implemented. ` +
+          'Falling back to Google Maps. See ROADMAP for provider status.'
+      );
+    }
+
+    // Dev-mode deprecation warning for customMapStyle
+    if (__DEV__ && customMapStyle && !theme) {
+      console.warn(
+        '[NitroMap] `customMapStyle` is deprecated. Use `theme` instead.'
+      );
+    }
+
+    // Resolve theme → native bridge prop.
+    // `theme` takes precedence over deprecated `customMapStyle`.
+    // Currently only Google is implemented — theme is passed as customMapStyle.
+    // When Apple/Yandex are added, this will route to the correct native prop.
+    const resolvedMapStyle: MapStyle | undefined = useMemo(() => {
+      if (theme) {
+        // Google provider: theme is already MapStyleElement[] (GoogleMapTheme)
+        // Apple/Yandex: will be handled by their respective native props
+        const resolvedProvider = provider ?? 'google';
+        if (resolvedProvider === 'google') {
+          return theme as MapStyle;
+        }
+        // Future providers: return undefined here, pass theme via separate native prop
+        return undefined;
+      }
+      return customMapStyle;
+    }, [theme, customMapStyle, provider]);
+
     // Native ref
     const nativeRef = useRef<NitroMapMethods | null>(null);
 
     // Marker handlers registry
     const markerHandlersRef = useRef<Map<string, MarkerHandlers>>(new Map());
 
+    // Active marker ID tracking for duplicate detection (__DEV__ only)
+    const activeMarkerIdsRef = useRef<Set<string>>(new Set());
+
     // Track if map is ready
     const [isReady, setIsReady] = useState(false);
 
-    // Expose methods via ref
-    useImperativeHandle(ref, () => ({
-      animateToRegion: (region, duration) => {
-        nativeRef.current?.animateToRegion(region, duration);
-      },
-      fitToCoordinates: (coordinates, edgePadding, animated) => {
-        nativeRef.current?.fitToCoordinates(coordinates, edgePadding, animated);
-      },
-      animateCamera: (camera, duration) => {
-        nativeRef.current?.animateCamera(camera, duration);
-      },
-      getCamera: () => {
-        if (!nativeRef.current) {
-          return Promise.reject(new Error('Map not ready'));
-        }
-        return nativeRef.current.getCamera();
-      },
-      setCamera: (camera) => {
-        nativeRef.current?.setCamera(camera);
-      },
-      getMapBoundaries: () => {
-        if (!nativeRef.current) {
-          return Promise.reject(new Error('Map not ready'));
-        }
-        return nativeRef.current.getMapBoundaries();
-      },
-      addMarker: (marker) => {
-        nativeRef.current?.addMarker(marker);
-      },
-      addMarkers: (markers) => {
-        nativeRef.current?.addMarkers(markers);
-      },
-      updateMarker: (marker) => {
-        nativeRef.current?.updateMarker(marker);
-      },
-      removeMarker: (id) => {
-        nativeRef.current?.removeMarker(id);
-      },
-      clearMarkers: () => {
-        nativeRef.current?.clearMarkers();
-      },
-      setClusteringEnabled: (enabled) => {
-        nativeRef.current?.setClusteringEnabled(enabled);
-      },
-      refreshClusters: () => {
-        nativeRef.current?.refreshClusters();
-      },
-      selectMarker: (id: string) => {
-        nativeRef.current?.selectMarker(id);
-      },
-      setMapStyle: (mapStyle: MapStyle) => {
-        nativeRef.current?.setMapStyle(mapStyle);
-      },
-      setIsDarkMode: (enabled: boolean) => {
-        nativeRef.current?.setIsDarkMode(enabled);
-      },
-    }));
+    // Expose all NitroMapMethods via ref by forwarding calls to the native ref.
+    // Uses a Proxy to avoid maintaining a 1:1 list of ~25 wrapper methods.
+    useImperativeHandle(ref, () => {
+      const handler: ProxyHandler<NitroMapMethods> = {
+        get(_target, prop: string) {
+          return (...args: unknown[]) => {
+            const native = nativeRef.current;
+            if (!native) {
+              // Methods that return Promises should reject; void methods silently no-op.
+              if (prop === 'getCamera' || prop === 'getMapBoundaries') {
+                return Promise.reject(new Error('Map not ready'));
+              }
+              if (
+                prop === 'pointForCoordinate' ||
+                prop === 'coordinateForPoint'
+              ) {
+                throw new Error('Map not ready');
+              }
+              return undefined;
+            }
+
+            return (native as any)[prop]?.(...args);
+          };
+        },
+      };
+      return new Proxy({} as NitroMapMethods, handler);
+    });
 
     // Handle hybridRef callback
 
@@ -164,9 +290,16 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
       onMapReady?.();
     }, [onMapReady]);
 
+    // Cleanup marker handlers on unmount to prevent memory leaks
+    useEffect(() => {
+      const handlers = markerHandlersRef.current;
+      return () => {
+        handlers.clear();
+      };
+    }, []);
+
     // Safety guard: warn if NitroMapInitialize() was not called before rendering
     useEffect(() => {
-      const { IsNitroMapInitialized } = require('../modules');
       if (!IsNitroMapInitialized()) {
         onError?.({
           code: 'NOT_INITIALIZED',
@@ -175,6 +308,7 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
             'Call it in your app entry point or a useEffect before the map mounts.',
         });
       }
+      // onError is excluded — we only check initialization once on mount.
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
 
@@ -226,7 +360,9 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
       [onClusterPress]
     );
 
-    // Context value - memoized to prevent unnecessary re-renders
+    // Context value — uses useRef to create a stable reference that won't
+    // trigger re-renders on children. mapRef is mutated in the hybridRef
+    // callback, but consumers access it lazily (in effects, not during render).
     const contextValue = useRef({
       mapRef: null as NitroMapMethods | null,
 
@@ -241,6 +377,20 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
       getMarkerHandler: (id: string) => {
         return markerHandlersRef.current.get(id);
       },
+
+      trackMarkerId: (id: string) => {
+        if (__DEV__ && activeMarkerIdsRef.current.has(id)) {
+          console.warn(
+            `[NitroMap] Duplicate marker ID "${id}" detected. ` +
+              'Each marker must have a unique ID. The previous marker with this ID will be replaced.'
+          );
+        }
+        activeMarkerIdsRef.current.add(id);
+      },
+
+      untrackMarkerId: (id: string) => {
+        activeMarkerIdsRef.current.delete(id);
+      },
     }).current;
 
     // Memoize style to prevent new array on every render
@@ -268,8 +418,8 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
         borderColor:
           parseColor(clusterConfig.borderColor) ?? defaultBorderColor,
         animatesClusters: clusterConfig.animatesClusters ?? true,
+        animateOnReappear: clusterConfig.animateOnReappear ?? true,
         animationDuration: clusterConfig.animationDuration ?? 0.3,
-        animationStyle: clusterConfig.animationStyle ?? 'default',
         realtimeClustering: clusterConfig.realtimeClustering ?? false,
         renderBuffer: clusterConfig.renderBuffer ?? 0,
         throttleInterval: clusterConfig.throttleInterval ?? 150,
@@ -299,6 +449,13 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
         onMarkerDrag: callback(handleMarkerDrag),
         onMarkerDragEnd: callback(handleMarkerDragEnd),
         onClusterPress: callback(handleClusterPress),
+        onPolylinePress: callback(onPolylinePress),
+        onPolygonPress: callback(onPolygonPress),
+        onCirclePress: callback(onCirclePress),
+        onUserLocationChange: callback(onUserLocationChange),
+        onUserTrackingModeChange: callback(onUserTrackingModeChange),
+        onUserLocationError: callback(onUserLocationError),
+        onMapIdle: callback(onMapIdle),
         onError: callback(onError),
       }),
       [
@@ -312,6 +469,13 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
         handleMarkerDrag,
         handleMarkerDragEnd,
         handleClusterPress,
+        onPolylinePress,
+        onPolygonPress,
+        onCirclePress,
+        onUserLocationChange,
+        onUserTrackingModeChange,
+        onUserLocationError,
+        onMapIdle,
         onError,
       ]
     );
@@ -321,8 +485,9 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
         <NitroMapHostComponent
           style={combinedStyle}
           hybridRef={hybridRefCallback}
-          provider={provider ?? getDefaultProvider()}
-          initialRegion={initialRegion}
+          provider={provider ?? 'google'}
+          initialRegion={initialRegion ?? REGION_UNSET}
+          region={region ?? REGION_UNSET}
           showsUserLocation={showsUserLocation}
           zoomEnabled={zoomEnabled}
           scrollEnabled={scrollEnabled}
@@ -330,8 +495,27 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
           pitchEnabled={pitchEnabled}
           mapType={mapType}
           darkMode={darkMode}
-          showsMyLocationButton={showsMyLocationButton}
-          clusterConfig={parsedClusterConfig}
+          clusterConfig={parsedClusterConfig ?? CLUSTER_CONFIG_DISABLED}
+          mapPadding={
+            typeof mapPadding === 'number'
+              ? {
+                  top: mapPadding,
+                  right: mapPadding,
+                  bottom: mapPadding,
+                  left: mapPadding,
+                }
+              : mapPadding ?? { top: 0, right: 0, bottom: 0, left: 0 }
+          }
+          showsCompass={showsCompass}
+          showsTraffic={showsTraffic}
+          showsBuildings={showsBuildings}
+          minZoom={minZoom ?? 1}
+          maxZoom={maxZoom ?? 22}
+          userTrackingMode={userTrackingMode}
+          userLocationImage={userLocationImage}
+          userLocationSize={userLocationSize}
+          userLocationAnchor={userLocationAnchor}
+          customMapStyle={resolvedMapStyle ?? []}
           onPress={memoizedCallbacks.onPress}
           onLongPress={memoizedCallbacks.onLongPress}
           onMapReady={memoizedCallbacks.onMapReady}
@@ -342,6 +526,13 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
           onMarkerDrag={memoizedCallbacks.onMarkerDrag}
           onMarkerDragEnd={memoizedCallbacks.onMarkerDragEnd}
           onClusterPress={memoizedCallbacks.onClusterPress}
+          onPolylinePress={memoizedCallbacks.onPolylinePress}
+          onPolygonPress={memoizedCallbacks.onPolygonPress}
+          onCirclePress={memoizedCallbacks.onCirclePress}
+          onUserLocationChange={memoizedCallbacks.onUserLocationChange}
+          onUserTrackingModeChange={memoizedCallbacks.onUserTrackingModeChange}
+          onUserLocationError={memoizedCallbacks.onUserLocationError}
+          onMapIdle={memoizedCallbacks.onMapIdle}
           onError={memoizedCallbacks.onError}
           {...rest}
         />
@@ -352,7 +543,7 @@ const NitroMapInner = forwardRef<NitroMapRef, NitroMapProps>(
   }
 );
 
-NitroMapInner.displayName = 'NitroMap';
+NitroMapInner.displayName = 'NitroMapInner';
 
 // ============ Custom Props Comparison ============
 // Deep compare map props to prevent unnecessary re-renders
@@ -364,17 +555,49 @@ const areMapPropsEqual = (
   if (
     prevProps.provider !== nextProps.provider ||
     prevProps.showsUserLocation !== nextProps.showsUserLocation ||
+    prevProps.userTrackingMode !== nextProps.userTrackingMode ||
+    prevProps.userLocationImage !== nextProps.userLocationImage ||
+    prevProps.userLocationSize !== nextProps.userLocationSize ||
+    prevProps.userLocationAnchor?.x !== nextProps.userLocationAnchor?.x ||
+    prevProps.userLocationAnchor?.y !== nextProps.userLocationAnchor?.y ||
     prevProps.zoomEnabled !== nextProps.zoomEnabled ||
     prevProps.scrollEnabled !== nextProps.scrollEnabled ||
     prevProps.rotateEnabled !== nextProps.rotateEnabled ||
     prevProps.pitchEnabled !== nextProps.pitchEnabled ||
     prevProps.darkMode !== nextProps.darkMode ||
     prevProps.mapType !== nextProps.mapType ||
-    prevProps.showsMyLocationButton !== nextProps.showsMyLocationButton
+    prevProps.showsTraffic !== nextProps.showsTraffic ||
+    prevProps.showsBuildings !== nextProps.showsBuildings ||
+    prevProps.showsCompass !== nextProps.showsCompass ||
+    prevProps.minZoom !== nextProps.minZoom ||
+    prevProps.maxZoom !== nextProps.maxZoom ||
+    prevProps.theme !== nextProps.theme ||
+    prevProps.customMapStyle !== nextProps.customMapStyle
   ) {
     return false;
   }
 
+  // Compare mapPadding (handles number | EdgePadding union)
+  const prevPadding = prevProps.mapPadding;
+  const nextPadding = nextProps.mapPadding;
+  if (typeof prevPadding !== typeof nextPadding) {
+    return false;
+  }
+  if (typeof prevPadding === 'number') {
+    if (prevPadding !== nextPadding) return false;
+  } else if (prevPadding && nextPadding && typeof nextPadding === 'object') {
+    if (
+      prevPadding.top !== nextPadding.top ||
+      prevPadding.right !== nextPadding.right ||
+      prevPadding.bottom !== nextPadding.bottom ||
+      prevPadding.left !== nextPadding.left
+    ) {
+      return false;
+    }
+  } else if (prevPadding !== nextPadding) {
+    return false;
+  }
+
   // Compare initialRegion (deep)
   const prevRegion = prevProps.initialRegion;
   const nextRegion = nextProps.initialRegion;
@@ -402,11 +625,18 @@ const areMapPropsEqual = (
       prevCluster.minimumClusterSize !== nextCluster.minimumClusterSize ||
       prevCluster.maxZoom !== nextCluster.maxZoom ||
       prevCluster.animatesClusters !== nextCluster.animatesClusters ||
+      prevCluster.animateOnReappear !== nextCluster.animateOnReappear ||
       prevCluster.animationDuration !== nextCluster.animationDuration ||
-      prevCluster.animationStyle !== nextCluster.animationStyle ||
+      prevCluster.borderWidth !== nextCluster.borderWidth ||
       prevCluster.realtimeClustering !== nextCluster.realtimeClustering ||
       prevCluster.renderBuffer !== nextCluster.renderBuffer ||
-      prevCluster.throttleInterval !== nextCluster.throttleInterval
+      prevCluster.throttleInterval !== nextCluster.throttleInterval ||
+      !areColorsEqual(
+        prevCluster.backgroundColor,
+        nextCluster.backgroundColor
+      ) ||
+      !areColorsEqual(prevCluster.textColor, nextCluster.textColor) ||
+      !areColorsEqual(prevCluster.borderColor, nextCluster.borderColor)
     ) {
       return false;
     }
@@ -432,8 +662,28 @@ const areMapPropsEqual = (
   return true;
 };
 
+// ============ Generic Component Type ============
+// React's forwardRef + memo erase generics, so we define a generic
+// function signature and cast the memoized component to it.
+// This lets consumers write <NitroMap provider="apple" theme={...} />
+// and get proper type narrowing on the `theme` prop.
+
+/**
+ * Generic NitroMap component type that preserves provider-aware theme typing.
+ */
+interface NitroMapComponent {
+  <P extends MapProvider = 'google'>(
+    props: NitroMapProps<P> & React.RefAttributes<NitroMapRef>
+  ): React.ReactElement | null;
+  displayName?: string;
+}
+
 // Memoized NitroMap to prevent unnecessary re-renders
-const NitroMap = memo(NitroMapInner, areMapPropsEqual);
+const NitroMapMemoized = memo(NitroMapInner, areMapPropsEqual);
+
+// Cast to generic component type so consumers get provider-aware theme narrowing
+const NitroMap = NitroMapMemoized as unknown as NitroMapComponent;
+NitroMap.displayName = 'NitroMap';
 
 const styles = StyleSheet.create({
   default: {
@@ -441,5 +691,5 @@ const styles = StyleSheet.create({
   },
 });
 
-export { NitroMap };
+export { NitroMap, areMapPropsEqual };
 export default NitroMap;