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

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 alisher rakhimov
+Copyright (c) 2025 Maydon Tech LLC
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights

package/NitroMap.podspec

@@ -20,7 +20,7 @@ Pod::Spec.new do |s|
 
   # C++ settings for ClusterEngine
   s.pod_target_xcconfig = {
-    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++17',
+    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++20',
     'CLANG_CXX_LIBRARY' => 'libc++',
     'HEADER_SEARCH_PATHS' => '"${PODS_TARGET_SRCROOT}/cpp"',
     'GCC_PREPROCESSOR_DEFINITIONS' => '$(inherited)'

package/README.md

@@ -50,14 +50,18 @@ import {
   NitroMap,
   NitroMapInitialize,
   PriceMarker,
+  type NitroMapRef,
 } from '@maydon_tech/react-native-nitro-maps';
 
 // Initialize once at app startup
-NitroMapInitialize('YOUR_API_KEY', 'google');
+NitroMapInitialize({ provider: 'google', googleApiKey: 'YOUR_API_KEY' });
 
 export default function App() {
+  const mapRef = useRef<NitroMapRef>(null);
+
   return (
     <NitroMap
+      ref={mapRef}
       provider="google"
       initialRegion={{
         latitude: 41.2995,
@@ -81,11 +85,36 @@ export default function App() {
 }
 ```
 
+### Imperative Methods (via ref)
+
+```tsx
+// Animate to a region
+mapRef.current?.animateToRegion({
+  latitude: 41.31,
+  longitude: 69.28,
+  latitudeDelta: 0.01,
+  longitudeDelta: 0.01,
+}, 500);
+
+// Fit to coordinates
+mapRef.current?.fitToCoordinates([
+  { latitude: 41.29, longitude: 69.24 },
+  { latitude: 41.31, longitude: 69.28 },
+]);
+
+// Get current camera
+const camera = await mapRef.current?.getCamera();
+
+// Center on user's current location
+// (requires showsUserLocation={true} and location permissions)
+mapRef.current?.centerOnUserLocation();
+```
+
 ## Providers
 
 | Provider        | iOS | Android | API Key  | Notes                  |
 |-----------------|-----|---------|----------|------------------------|
-| **Google Maps** | ✅  | 🔜      | Required | Best global coverage   |
+| **Google Maps** | ✅  | ✅      | Required | Best global coverage   |
 | **Apple Maps**  | 🔜  | —       | Free     | iOS only, zero SDK     |
 | **Yandex Maps** | 🔜  | 🔜      | Required | Best for CIS countries |
 
@@ -126,14 +155,57 @@ Best for real estate, hospitality — what Zillow and Airbnb use.
 
 ## Documentation
 
+### Getting Started
+
+| Guide | Description |
+|---|---|
+| [**Installation**](docs-new/getting-started/installation.md) | Package install, peer dependencies, platform setup |
+| [**Google Maps Setup**](docs-new/getting-started/google-maps-setup.md) | API keys, iOS Podfile, Android manifest |
+| [**Quick Start**](docs-new/getting-started/quick-start.md) | Minimal working example in 30 lines |
+
+### Guides
+
+| Guide | Description |
+|---|---|
+| [**Map Configuration**](docs-new/guides/map-configuration.md) | Map type, gestures, traffic, buildings, padding, dark mode |
+| [**Camera & Regions**](docs-new/guides/camera-and-regions.md) | initialRegion vs region, controlled camera, fit to coordinates |
+| [**Markers**](docs-new/guides/markers.md) | Marker, PriceMarker, ImageMarker — all 3 types |
+| [**Marker Selection**](docs-new/guides/marker-selection.md) | Select/deselect, visual states, info windows |
+| [**Clustering**](docs-new/guides/clustering.md) | Supercluster vs hideOnOverlap, config, performance |
+| [**Overlays**](docs-new/guides/overlays.md) | Polylines, polygons, circles |
+| [**User Location**](docs-new/guides/user-location.md) | Blue dot, custom marker, tracking modes, permissions |
+| [**Styling & Themes**](docs-new/guides/styling-and-themes.md) | Provider-aware themes, Google JSON styles, dark mode |
+| [**Colors**](docs-new/guides/colors.md) | ColorValue, hex(), rgb(), color presets |
+
+### API Reference
+
+| Reference | Description |
+|---|---|
+| [**NitroMap**](docs-new/api-reference/nitro-map.md) | All props, events, and ref methods |
+| [**Marker**](docs-new/api-reference/marker.md) | Default pin marker props |
+| [**PriceMarker**](docs-new/api-reference/price-marker.md) | Price tag marker props |
+| [**ImageMarker**](docs-new/api-reference/image-marker.md) | Custom image marker props |
+| [**NitroPolyline**](docs-new/api-reference/polyline.md) | Polyline overlay props |
+| [**NitroPolygon**](docs-new/api-reference/polygon.md) | Polygon overlay props |
+| [**NitroCircle**](docs-new/api-reference/circle.md) | Circle overlay props |
+| [**Initialization**](docs-new/api-reference/initialization.md) | NitroMapInitialize, config |
+| [**Types**](docs-new/api-reference/types.md) | All exported TypeScript types |
+
+### Advanced
+
+| Guide | Description |
+|---|---|
+| [**Imperative API**](docs-new/advanced/imperative-api.md) | Ref methods, declarative vs imperative |
+| [**Performance**](docs-new/advanced/performance.md) | Large datasets, clustering tuning, memo optimization |
+| [**Provider System**](docs-new/advanced/provider-system.md) | Multi-provider architecture, roadmap |
+| [**Accessibility**](docs-new/advanced/accessibility.md) | VoiceOver, TalkBack, best practices |
+
+### Other
+
 | Guide | Description |
 |---|---|
-| [**Setup & Installation**](docs/setup.md) | Per-vendor setup for iOS and Android |
-| [**API Reference**](docs/api.md) | Components, props, methods, types, events |
-| [**Clustering**](docs/clustering.md) | Strategies, live clustering, render buffer, performance |
-| [**Feature Support**](docs/features.md) | What's available on each provider |
-| [**Examples**](docs/examples.md) | Selection, dragging, clustering, overlays |
-| [**Migration**](docs/migration.md) | Breaking changes between versions |
+| [**Migration**](docs-new/migration.md) | Breaking changes, migrating from react-native-maps |
+| [**Troubleshooting**](docs-new/troubleshooting.md) | Common errors, platform gotchas, FAQ |
 
 ## Architecture
 
@@ -157,7 +229,8 @@ Best for real estate, hospitality — what Zillow and Airbnb use.
     ▼          ▼              ▼
   Google    Apple          Yandex
   Provider  Provider       Provider
-  (Swift)   (Swift)        (Swift)
+  (Swift/   (Swift)        (Swift/
+   Kotlin)                  Kotlin)
     │          │              │
     ▼          ▼              ▼
   GMSMapView MKMapView    YMKMapView

package/android/CMakeLists.txt

@@ -9,7 +9,10 @@ set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,max-page-size=16384")
 
 # Define C++ library and add all sources
-add_library(${PACKAGE_NAME} SHARED src/main/cpp/cpp-adapter.cpp)
+add_library(${PACKAGE_NAME} SHARED
+    src/main/cpp/cpp-adapter.cpp
+    src/main/cpp/ClusterEngineJNI.cpp
+)
 
 # Add Nitrogen specs :)
 include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/nitromap+autolinking.cmake)

package/android/gradle.properties

@@ -1,5 +1,5 @@
-NitroMap_kotlinVersion=2.0.21
-NitroMap_minSdkVersion=24
-NitroMap_targetSdkVersion=34
-NitroMap_compileSdkVersion=35
+NitroMap_kotlinVersion=2.1.20
+NitroMap_minSdkVersion=26
+NitroMap_targetSdkVersion=36
+NitroMap_compileSdkVersion=36
 NitroMap_ndkVersion=27.1.12297006

package/android/src/main/cpp/ClusterEngineJNI.cpp

@@ -0,0 +1,198 @@
+/**
+ * JNI bridge for C++ ClusterEngine.
+ * Mirrors iOS ClusterEngineWrapper.mm — same C++ engine, JNI interface.
+ *
+ * L-6: JNI class/method IDs are cached on first use to avoid repeated lookups.
+ */
+
+#include <jni.h>
+#include <string>
+#include <mutex>
+#include "ClusterEngine.hpp"
+
+using namespace nitromap;
+
+// ============================================================================
+// L-6: Cached JNI class/method IDs (populated once, thread-safe)
+// ============================================================================
+
+static struct {
+    jclass resultClass = nullptr;
+    jclass clusterClass = nullptr;
+    jclass singleClass = nullptr;
+    jclass stringClass = nullptr;
+    jmethodID resultCtor = nullptr;
+    jmethodID clusterCtor = nullptr;
+    jmethodID singleCtor = nullptr;
+    std::once_flag initFlag;
+} jniCache;
+
+static void ensureJniCacheInitialized(JNIEnv *env) {
+    std::call_once(jniCache.initFlag, [env]() {
+        // Use global refs so they survive across JNI calls
+        jclass localResult = env->FindClass("com/margelo/nitro/nitromap/clustering/NitroClusterEngine$ClusteringResultJNI");
+        jclass localCluster = env->FindClass("com/margelo/nitro/nitromap/clustering/NitroClusterEngine$ClusterDataJNI");
+        jclass localSingle = env->FindClass("com/margelo/nitro/nitromap/clustering/NitroClusterEngine$SingleMarkerJNI");
+        jclass localString = env->FindClass("java/lang/String");
+
+        jniCache.resultClass = (jclass)env->NewGlobalRef(localResult);
+        jniCache.clusterClass = (jclass)env->NewGlobalRef(localCluster);
+        jniCache.singleClass = (jclass)env->NewGlobalRef(localSingle);
+        jniCache.stringClass = (jclass)env->NewGlobalRef(localString);
+
+        jniCache.resultCtor = env->GetMethodID(jniCache.resultClass, "<init>",
+            "([Lcom/margelo/nitro/nitromap/clustering/NitroClusterEngine$ClusterDataJNI;"
+            "[Lcom/margelo/nitro/nitromap/clustering/NitroClusterEngine$SingleMarkerJNI;)V");
+        jniCache.clusterCtor = env->GetMethodID(jniCache.clusterClass, "<init>", "(DDI[Ljava/lang/String;D)V");
+        jniCache.singleCtor = env->GetMethodID(jniCache.singleClass, "<init>", "(Ljava/lang/String;DD)V");
+
+        env->DeleteLocalRef(localResult);
+        env->DeleteLocalRef(localCluster);
+        env->DeleteLocalRef(localSingle);
+        env->DeleteLocalRef(localString);
+    });
+}
+
+extern "C" {
+
+// ============================================================================
+// Lifecycle
+// ============================================================================
+
+JNIEXPORT jlong JNICALL
+Java_com_margelo_nitro_nitromap_clustering_NitroClusterEngine_nativeCreate(JNIEnv *, jobject) {
+    return reinterpret_cast<jlong>(new ClusterEngine());
+}
+
+JNIEXPORT void JNICALL
+Java_com_margelo_nitro_nitromap_clustering_NitroClusterEngine_nativeDestroy(JNIEnv *, jobject, jlong ptr) {
+    delete reinterpret_cast<ClusterEngine *>(ptr);
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+JNIEXPORT void JNICALL
+Java_com_margelo_nitro_nitromap_clustering_NitroClusterEngine_nativeSetClusterRadius(
+    JNIEnv *, jobject, jlong ptr, jdouble radius) {
+    reinterpret_cast<ClusterEngine *>(ptr)->setClusterRadius(radius);
+}
+
+JNIEXPORT void JNICALL
+Java_com_margelo_nitro_nitromap_clustering_NitroClusterEngine_nativeSetMinClusterSize(
+    JNIEnv *, jobject, jlong ptr, jint size) {
+    reinterpret_cast<ClusterEngine *>(ptr)->setMinClusterSize(size);
+}
+
+JNIEXPORT void JNICALL
+Java_com_margelo_nitro_nitromap_clustering_NitroClusterEngine_nativeSetMaxZoom(
+    JNIEnv *, jobject, jlong ptr, jdouble zoom) {
+    reinterpret_cast<ClusterEngine *>(ptr)->setMaxZoom(zoom);
+}
+
+// ============================================================================
+// Marker Management
+// ============================================================================
+
+JNIEXPORT void JNICALL
+Java_com_margelo_nitro_nitromap_clustering_NitroClusterEngine_nativeAddMarker(
+    JNIEnv *env, jobject, jlong ptr, jstring jId, jdouble lat, jdouble lon) {
+    const char *idChars = env->GetStringUTFChars(jId, nullptr);
+    std::string id(idChars);
+    env->ReleaseStringUTFChars(jId, idChars);
+
+    MarkerPoint marker(id, lat, lon);
+    reinterpret_cast<ClusterEngine *>(ptr)->addMarker(marker);
+}
+
+JNIEXPORT void JNICALL
+Java_com_margelo_nitro_nitromap_clustering_NitroClusterEngine_nativeRemoveMarker(
+    JNIEnv *env, jobject, jlong ptr, jstring jId) {
+    const char *idChars = env->GetStringUTFChars(jId, nullptr);
+    std::string id(idChars);
+    env->ReleaseStringUTFChars(jId, idChars);
+
+    reinterpret_cast<ClusterEngine *>(ptr)->removeMarker(id);
+}
+
+JNIEXPORT void JNICALL
+Java_com_margelo_nitro_nitromap_clustering_NitroClusterEngine_nativeClearMarkers(
+    JNIEnv *, jobject, jlong ptr) {
+    reinterpret_cast<ClusterEngine *>(ptr)->clearMarkers();
+}
+
+JNIEXPORT jint JNICALL
+Java_com_margelo_nitro_nitromap_clustering_NitroClusterEngine_nativeMarkerCount(
+    JNIEnv *, jobject, jlong ptr) {
+    return static_cast<jint>(reinterpret_cast<ClusterEngine *>(ptr)->markerCount());
+}
+
+// ============================================================================
+// Clustering (L-6: uses cached JNI IDs)
+// ============================================================================
+
+JNIEXPORT jobjectArray JNICALL
+Java_com_margelo_nitro_nitromap_clustering_NitroClusterEngine_nativeCluster(
+    JNIEnv *env, jobject, jlong ptr,
+    jdouble minLat, jdouble maxLat, jdouble minLon, jdouble maxLon,
+    jdouble zoom, jdouble mapW, jdouble mapH) {
+
+    auto *engine = reinterpret_cast<ClusterEngine *>(ptr);
+    ClusterResult result = engine->cluster(minLat, maxLat, minLon, maxLon, zoom, mapW, mapH);
+
+    // L-6: Ensure cached IDs are initialized
+    ensureJniCacheInitialized(env);
+
+    // Build cluster array
+    jobjectArray clusterArray = env->NewObjectArray(
+        static_cast<jsize>(result.clusters.size()), jniCache.clusterClass, nullptr);
+
+    for (size_t i = 0; i < result.clusters.size(); i++) {
+        const auto &c = result.clusters[i];
+
+        // Build marker ID string array
+        jobjectArray idArray = env->NewObjectArray(
+            static_cast<jsize>(c.markerIds.size()),
+            jniCache.stringClass, nullptr);
+        for (size_t j = 0; j < c.markerIds.size(); j++) {
+            jstring jStr = env->NewStringUTF(c.markerIds[j].c_str());
+            env->SetObjectArrayElement(idArray, static_cast<jsize>(j), jStr);
+            env->DeleteLocalRef(jStr);
+        }
+
+        jobject clusterObj = env->NewObject(jniCache.clusterClass, jniCache.clusterCtor,
+            c.latitude, c.longitude, c.count, idArray,
+            Cluster::iconSize(c.count));
+        env->SetObjectArrayElement(clusterArray, static_cast<jsize>(i), clusterObj);
+        env->DeleteLocalRef(idArray);
+        env->DeleteLocalRef(clusterObj);
+    }
+
+    // Build single markers array
+    jobjectArray singleArray = env->NewObjectArray(
+        static_cast<jsize>(result.singleMarkers.size()), jniCache.singleClass, nullptr);
+
+    for (size_t i = 0; i < result.singleMarkers.size(); i++) {
+        const auto &s = result.singleMarkers[i];
+        jstring jId = env->NewStringUTF(s.id.c_str());
+        jobject singleObj = env->NewObject(jniCache.singleClass, jniCache.singleCtor,
+            jId, s.latitude, s.longitude);
+        env->SetObjectArrayElement(singleArray, static_cast<jsize>(i), singleObj);
+        env->DeleteLocalRef(jId);
+        env->DeleteLocalRef(singleObj);
+    }
+
+    // Create result
+    jobject resultObj = env->NewObject(jniCache.resultClass, jniCache.resultCtor, clusterArray, singleArray);
+    env->DeleteLocalRef(clusterArray);
+    env->DeleteLocalRef(singleArray);
+
+    // Return as single-element array (workaround for returning object)
+    jobjectArray wrapper = env->NewObjectArray(1, jniCache.resultClass, resultObj);
+    env->DeleteLocalRef(resultObj);
+
+    return wrapper;
+}
+
+} // extern "C"