@mapvina-com/mapvina-react-native 1.0.0

package/src/hooks/useNativeBridge.ts

@@ -0,0 +1,128 @@
+import {
+  Component,
+  type MutableRefObject,
+  type SyntheticEvent,
+  useRef,
+} from "react";
+
+import { runNativeCommand, isAndroid, type NativeArg } from "../utils";
+
+export type RNMLEvent<PayloadType = { [key: string]: string }> = {
+  payload: PayloadType;
+  type: string;
+};
+
+let callbackIncrement = 0;
+
+type UseNativeBridge = {
+  _nativeModuleName: string;
+  _onAndroidCallback: (e: SyntheticEvent<Element, RNMLEvent>) => void;
+  _callbackMap: MutableRefObject<Map<string, any>>;
+  _preRefMapMethodQueue: MutableRefObject<any[]>;
+  _addAddAndroidCallback: <ReturnType>(
+    id: string,
+    resolve: (value: ReturnType) => void,
+    reject: (error: Error) => void,
+  ) => void;
+  _removeAndroidCallback: (id: string) => void;
+  _runPendingNativeCommands: <RefType extends Component>(
+    nativeRef: RefType | null | undefined,
+  ) => Promise<void>;
+  _runNativeCommand: <RefType extends Component, ReturnType = NativeArg>(
+    methodName: string,
+    nativeRef: RefType | undefined | null,
+    args?: NativeArg[],
+  ) => Promise<ReturnType>;
+};
+
+export const useNativeBridge: (moduleName: string) => UseNativeBridge = (
+  _nativeModuleName: string,
+) => {
+  const _callbackMap = useRef<Map<string, any>>(new Map());
+  const _preRefMapMethodQueue = useRef<any[]>([]);
+
+  const _addAddAndroidCallback = <ReturnType>(
+    id: string,
+    resolve: (value: ReturnType) => void,
+    reject: (error: Error) => void,
+  ): void => {
+    _callbackMap.current.set(id, { resolve, reject });
+  };
+
+  const _removeAndroidCallback = (id: string): void => {
+    _callbackMap.current.delete(id);
+  };
+
+  const _onAndroidCallback = (e: SyntheticEvent<Element, RNMLEvent>): void => {
+    const callbackID = e.nativeEvent.type;
+    const callback = _callbackMap.current.get(callbackID);
+
+    if (!callback) {
+      return;
+    }
+
+    _callbackMap.current.delete(callbackID);
+    const { payload } = e.nativeEvent;
+    if (payload.error) {
+      callback.reject.call(null, new Error(payload.error));
+    } else {
+      callback.resolve.call(null, payload);
+    }
+  };
+
+  const _runPendingNativeCommands = async <RefType extends Component>(
+    nativeRef: RefType | null | undefined,
+  ): Promise<void> => {
+    if (nativeRef) {
+      while (_preRefMapMethodQueue.current.length > 0) {
+        const item = _preRefMapMethodQueue.current.pop();
+
+        if (item && item.method && item.resolver) {
+          const res = await _runNativeCommand(
+            item.method.name,
+            nativeRef,
+            item.method.args,
+          );
+          item.resolver(res);
+        }
+      }
+    }
+  };
+
+  const _runNativeCommand = <RefType extends Component, ReturnType = NativeArg>(
+    methodName: string,
+    nativeRef: RefType | undefined | null,
+    args: NativeArg[] = [],
+  ): Promise<ReturnType> => {
+    if (!nativeRef) {
+      return new Promise((resolve) => {
+        _preRefMapMethodQueue.current.push({
+          method: { name: methodName, args },
+          resolver: resolve,
+        });
+      });
+    }
+
+    if (isAndroid()) {
+      return new Promise((resolve, reject) => {
+        callbackIncrement += 1;
+        const callbackID = `${methodName}_${callbackIncrement}`;
+        _addAddAndroidCallback(callbackID, resolve, reject);
+        args.unshift(callbackID);
+        runNativeCommand(_nativeModuleName, methodName, nativeRef, args);
+      });
+    }
+    return runNativeCommand(_nativeModuleName, methodName, nativeRef, args);
+  };
+
+  return {
+    _nativeModuleName,
+    _onAndroidCallback,
+    _callbackMap,
+    _preRefMapMethodQueue,
+    _addAddAndroidCallback,
+    _removeAndroidCallback,
+    _runPendingNativeCommands,
+    _runNativeCommand,
+  };
+};

package/src/index.ts

@@ -0,0 +1,119 @@
+export {
+  Camera, type CameraAnimationOptions, type CameraBoundsOptions, type CameraBoundsStop, type CameraCenterOptions, type CameraCenterStop, type CameraEasing, type CameraOptions, type CameraProps, type CameraRef, type CameraStop,
+  type InitialViewState,
+  type TrackUserLocation,
+  type TrackUserLocationChangeEvent
+} from "./components/camera/Camera";
+
+export {
+  Map, type MapProps, type MapRef, type ViewState,
+  type ViewStateChangeEvent
+} from "./components/map/Map";
+
+export {
+  ViewAnnotation, type NativeViewAnnotationRef, type ViewAnnotationEvent, type ViewAnnotationProps, type ViewAnnotationRef
+} from "./components/annotations/view-annotation/ViewAnnotation";
+
+export {
+  LayerAnnotation, type LayerAnnotationProps
+} from "./components/annotations/LayerAnnotation";
+
+export {
+  Callout, type CalloutProps
+} from "./components/annotations/callout/Callout";
+
+export { NativeUserLocation } from "./components/user-location/NativeUserLocation";
+export { UserLocation } from "./components/user-location/UserLocation";
+export { useCurrentPosition } from "./hooks/useCurrentPosition";
+
+export {
+  ImageSource, type ImageSourceProps
+} from "./components/sources/image-source/ImageSource";
+
+export {
+  GeoJSONSource, type GeoJSONSourceProps, type GeoJSONSourceRef
+} from "./components/sources/geojson-source/GeoJSONSource";
+
+export {
+  RasterDEMSource, type RasterDEMSourceProps
+} from "./components/sources/raster-dem-source/RasterDEMSource";
+export {
+  RasterSource, type RasterSourceProps
+} from "./components/sources/raster-source/RasterSource";
+
+export {
+  VectorSource, type VectorSourceProps, type VectorSourceRef
+} from "./components/sources/vector-source/VectorSource";
+
+export {
+  Layer, type BackgroundLayerProps, type CircleLayerProps, type FillExtrusionLayerProps, type FillLayerProps, type HeatmapLayerProps, type LayerProps, type LineLayerProps, type RasterLayerProps, type SourceLayerProps, type SymbolLayerProps
+} from "./components/layer/Layer";
+
+export type {
+  BackgroundLayerSpecification,
+  CircleLayerSpecification, FillExtrusionLayerSpecification, FillLayerSpecification,
+  // Filter
+  FilterSpecification, GeoJSONSourceSpecification, HeatmapLayerSpecification,
+  HillshadeLayerSpecification, ImageSourceSpecification,
+  // Layers
+  LayerSpecification, LightSpecification, LineLayerSpecification, ProjectionSpecification, RasterDEMSourceSpecification, RasterLayerSpecification, RasterSourceSpecification, SkySpecification,
+  // Sources
+  SourceSpecification,
+  // Style
+  StyleSpecification, SymbolLayerSpecification, TerrainSpecification, VectorSourceSpecification,
+  VideoSourceSpecification
+} from "@mapvina/mapvina-gl-style-spec";
+
+export {
+  Images, type ImageEntry, type ImageSourceWithSdf, type ImagesProps
+} from "./components/images/Images";
+
+export {
+  Marker, type MarkerEvent,
+  type MarkerProps,
+  type MarkerRef, type NativeMarkerRef
+} from "./components/annotations/marker/Marker";
+
+export {
+  LocationManager,
+  type GeolocationPosition
+} from "./modules/location/LocationManager";
+
+export { LogManager, type LogLevel } from "./modules/log/LogManager";
+
+export { NetworkManager } from "./modules/network/NetworkManager";
+
+export {
+  OfflineManager,
+  type OfflinePackCreateOptions,
+  type OfflinePackDownloadState,
+  type OfflinePackError, type OfflinePackErrorListener, type OfflinePackProgressListener
+} from "./modules/offline/OfflineManager";
+export {
+  OfflinePack,
+  type OfflinePackStatus
+} from "./modules/offline/OfflinePack";
+
+export {
+  StaticMapImageManager, type StaticMapBoundsOptions, type StaticMapCenterOptions, type StaticMapCreateOptions, type StaticMapOptions
+} from "./modules/static-map/StaticMapManager";
+
+export {
+  TransformRequestManager, type HeaderOptions, type TransformOptions, type UrlSearchParamOptions, type UrlTransformOptions
+} from "./modules/transform-request/TransformRequestManager";
+
+export type { Anchor } from "./types/Anchor";
+export type { LngLat } from "./types/LngLat";
+export type { LngLatBounds } from "./types/LngLatBounds";
+export type {
+  BackgroundLayerStyle, CircleLayerStyle, Expression, FillExtrusionLayerStyle, FillLayerStyle, HeatmapLayerStyle, HillshadeLayerStyle, LightLayerStyle, LineLayerStyle, RasterLayerStyle, SymbolLayerStyle
+} from "./types/MapVinaRNStyles";
+export type { PixelPoint } from "./types/PixelPoint";
+export type { PixelPointBounds } from "./types/PixelPointBounds";
+export type { PressEvent } from "./types/PressEvent";
+export type { PressEventWithFeatures } from "./types/PressEventWithFeatures";
+export type { ViewPadding } from "./types/ViewPadding";
+
+export { Animated } from "./utils/animated/Animated";
+
+export type { MapVinaPluginProps } from "./plugin/MapVinaPluginProps";

package/src/modules/location/LocationManager.ts

@@ -0,0 +1,174 @@
+import {
+  type EventSubscription,
+  type Permission,
+  PermissionsAndroid,
+  Platform,
+} from "react-native";
+
+import NativeLocationModule from "./NativeLocationModule";
+
+interface GeolocationCoordinates {
+  /**
+   * Longitude in degrees
+   */
+  longitude: number;
+
+  /**
+   * Latitude in degrees
+   */
+  latitude: number;
+
+  /**
+   * Accuracy for longitude/latitude in meters
+   */
+  accuracy: number;
+
+  /**
+   * Altitude in meters
+   */
+  altitude: number | null;
+
+  /**
+   * Accuracy for altitude in meters
+   */
+  altitudeAccuracy: number | null;
+
+  /**
+   * Direction in which the device is traveling in degrees, relative to north
+   */
+  heading: number | null;
+
+  /**
+   * Instantaneous speed of the device in meters per second
+   */
+  speed: number | null;
+}
+
+export interface GeolocationPosition {
+  coords: GeolocationCoordinates;
+
+  timestamp: number;
+}
+
+class LocationManager {
+  private listeners: ((location: GeolocationPosition) => void)[] = [];
+  private currentPosition: GeolocationPosition | undefined = undefined;
+  private isListening: boolean = false;
+
+  private subscription: EventSubscription | undefined = undefined;
+
+  constructor() {
+    this.handleUpdate = this.handleUpdate.bind(this);
+  }
+
+  async getCurrentPosition(): Promise<GeolocationPosition | undefined> {
+    let currentPosition;
+
+    try {
+      currentPosition = await NativeLocationModule.getCurrentPosition();
+    } catch (error) {
+      console.log("LocationManager [error]: ", error);
+    }
+
+    this.currentPosition = currentPosition;
+
+    return this.currentPosition;
+  }
+
+  addListener(newListener: (location: GeolocationPosition) => void): void {
+    if (!this.isListening) {
+      this.start();
+    }
+
+    if (!this.listeners.includes(newListener)) {
+      this.listeners.push(newListener);
+
+      if (this.currentPosition) {
+        newListener(this.currentPosition);
+      }
+    }
+  }
+
+  removeListener(oldListener: (location: GeolocationPosition) => void): void {
+    this.listeners = this.listeners.filter(
+      (listener) => listener !== oldListener,
+    );
+
+    if (this.listeners.length === 0) {
+      this.stop();
+    }
+  }
+
+  removeAllListeners(): void {
+    this.listeners = [];
+
+    this.stop();
+  }
+
+  start(): void {
+    if (!this.isListening) {
+      NativeLocationModule.start();
+
+      this.subscription = NativeLocationModule.onUpdate(this.handleUpdate);
+
+      this.isListening = true;
+    }
+  }
+
+  stop(): void {
+    NativeLocationModule.stop();
+
+    if (this.isListening) {
+      this.subscription?.remove();
+    }
+
+    this.isListening = false;
+  }
+
+  setMinDisplacement(minDisplacement: number): void {
+    NativeLocationModule.setMinDisplacement(minDisplacement);
+  }
+
+  private handleUpdate(location: GeolocationPosition): void {
+    this.currentPosition = location;
+
+    this.listeners.forEach((listener) => listener(location));
+  }
+
+  /**
+   * Request location permissions
+   *
+   * Requests the following:
+   * - Android: `ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION`
+   * - iOS: `requestWhenInUseAuthorization`
+   *
+   * @returns Promise resolves to true if permissions were granted, false otherwise
+   */
+  async requestPermissions(): Promise<boolean> {
+    if (Platform.OS === "android") {
+      const res = await PermissionsAndroid.requestMultiple([
+        PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION as Permission,
+        PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION as Permission,
+      ]);
+
+      return Object.values(res).every(
+        (permission) => permission === PermissionsAndroid.RESULTS.GRANTED,
+      );
+    }
+
+    if (Platform.OS === "ios") {
+      try {
+        await NativeLocationModule.requestPermissions();
+        return true;
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (_error) {
+        return false;
+      }
+    }
+
+    return false;
+  }
+}
+
+const locationManager = new LocationManager();
+export { locationManager as LocationManager };

package/src/modules/location/NativeLocationModule.ts

@@ -0,0 +1,33 @@
+import type { TurboModule, CodegenTypes } from "react-native";
+import { TurboModuleRegistry } from "react-native";
+
+type NativeGeolocationCoordinates = {
+  longitude: CodegenTypes.Double;
+  latitude: CodegenTypes.Double;
+  accuracy: CodegenTypes.Double;
+  altitude: CodegenTypes.Double | null;
+  altitudeAccuracy: CodegenTypes.Double | null;
+  heading: CodegenTypes.Double | null;
+  speed: CodegenTypes.Double | null;
+};
+
+type NativeGeolocationPosition = {
+  coords: NativeGeolocationCoordinates;
+  timestamp: number;
+};
+
+export interface Spec extends TurboModule {
+  start(): void;
+
+  stop(): void;
+
+  getCurrentPosition(): Promise<NativeGeolocationPosition>;
+
+  setMinDisplacement(minDisplacement: number): void;
+
+  requestPermissions(): Promise<void>;
+
+  readonly onUpdate: CodegenTypes.EventEmitter<NativeGeolocationPosition>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>("MLRNLocationModule");

package/src/modules/log/LogManager.ts

@@ -0,0 +1,115 @@
+import { type EventSubscription } from "react-native";
+
+import NativeLogModule from "./NativeLogModule";
+
+/**
+ * Log levels in decreasing order of severity
+ */
+export type LogLevel = "error" | "warn" | "info" | "debug" | "verbose";
+
+interface LogEvent {
+  level: LogLevel;
+  tag: string;
+  message: string;
+}
+
+/**
+ * Handler for `onLog` events
+ *
+ * Called before logging a message, return false to proceed with default
+ * logging.
+ *
+ * @param event -
+ */
+type LogHandler = (event: LogEvent) => boolean;
+
+class LogManager {
+  private logLevel: LogLevel = "warn";
+  private startedCount: number = 0;
+  private logHandler: LogHandler | undefined = undefined;
+  private subscription: EventSubscription | undefined = undefined;
+
+  constructor() {
+    this.handleLog = this.handleLog.bind(this);
+  }
+
+  /**
+   * Override logging behavior
+   *
+   * @param logHandler -
+   */
+  onLog(logHandler: LogHandler): void {
+    this.logHandler = logHandler;
+  }
+
+  /**
+   * Set the minimum log level for a message to be logged
+   *
+   * @param level - Minimum log level
+   */
+  setLogLevel(level: LogLevel): void {
+    this.logLevel = level;
+    NativeLogModule.setLogLevel(level);
+  }
+
+  start(): void {
+    if (this.startedCount === 0) {
+      this.subscribe();
+    }
+
+    this.startedCount += 1;
+  }
+
+  stop(): void {
+    this.startedCount -= 1;
+
+    if (this.startedCount === 0) {
+      this.unsubscribe();
+    }
+  }
+
+  private subscribe(): void {
+    this.subscription = NativeLogModule.onLog(this.handleLog);
+  }
+
+  private unsubscribe(): void {
+    if (this.subscription) {
+      this.subscription.remove();
+      this.subscription = undefined;
+    }
+  }
+
+  private effectiveLevel({ level, message, tag }: LogEvent): LogLevel {
+    // Reduce level of cancelled HTTP requests from warn to info
+    if (
+      level === "warn" &&
+      tag === "Mbgl-HttpRequest" &&
+      message.startsWith("Request failed due to a permanent error: Canceled")
+    ) {
+      return "info";
+    }
+
+    return level;
+  }
+
+  private handleLog(log: LogEvent): void {
+    if (!this.logHandler || !this.logHandler(log)) {
+      const { message, tag } = log;
+      const level = this.effectiveLevel(log);
+
+      const consoleMessage = `MapVina Native [${level.toUpperCase()}] [${tag}] ${message}`;
+
+      if (level === "error") {
+        console.error(consoleMessage);
+      } else if (level === "warn" && this.logLevel !== "error") {
+        console.warn(consoleMessage);
+      } else if (this.logLevel !== "error" && this.logLevel !== "warn") {
+        console.info(consoleMessage);
+      }
+    }
+  }
+}
+
+const logManager = new LogManager();
+
+export { logManager as LogManager };

package/src/modules/log/NativeLogModule.ts

@@ -0,0 +1,16 @@
+import type { TurboModule, CodegenTypes } from "react-native";
+import { TurboModuleRegistry } from "react-native";
+
+type NativeLogLevel = "error" | "warn" | "info" | "debug" | "verbose";
+
+export interface Spec extends TurboModule {
+  setLogLevel(logLevel: NativeLogLevel): void;
+
+  readonly onLog: CodegenTypes.EventEmitter<{
+    level: NativeLogLevel;
+    tag: string;
+    message: string;
+  }>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>("MLRNLogModule");

package/src/modules/network/NativeNetworkModule.ts

@@ -0,0 +1,8 @@
+import type { TurboModule } from "react-native";
+import { TurboModuleRegistry } from "react-native";
+
+export interface Spec extends TurboModule {
+  setConnected(connected: boolean): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>("MLRNNetworkModule");

package/src/modules/network/NetworkManager.ts

@@ -0,0 +1,28 @@
+import NativeNetworkModule from "./NativeNetworkModule";
+
+/**
+ * NetworkManager provides methods for managing and controlling network
+ * connectivity.
+ */
+class NetworkManager {
+  /**
+   * Android only: Sets the connectivity state of the map. When set to false, the
+   * map will not make any network requests and will only use cached tiles. This
+   * is useful for implementing offline mode or reducing data usage.
+   *
+   * @param connected - Whether the map should be connected to the network
+   *
+   * @example
+   * ```ts
+   * // Enable offline mode
+   * NetworkManager.setConnected(false);
+   * // Re-enable network requests
+   * NetworkManager.setConnected(true);
+   * ```
+   */
+  static setConnected(connected: boolean): void {
+    NativeNetworkModule.setConnected(connected);
+  }
+}
+
+export { NetworkManager };

package/src/modules/offline/NativeOfflineModule.ts

@@ -0,0 +1,63 @@
+import type { CodegenTypes, TurboModule } from "react-native";
+import { TurboModuleRegistry } from "react-native";
+
+type NativeOfflinePackDownloadState = "inactive" | "active" | "complete";
+
+export type NativeOfflinePack = {
+  id: string;
+  bounds: CodegenTypes.Double[];
+  metadata: string;
+};
+
+type NativeOfflinePackCreateOptions = {
+  mapStyle: string;
+  bounds: CodegenTypes.Double[];
+  minZoom: CodegenTypes.Double;
+  maxZoom: CodegenTypes.Double;
+  metadata: string;
+};
+
+type NativeOfflinePackStatus = {
+  id: string;
+  state: NativeOfflinePackDownloadState;
+  percentage: CodegenTypes.Double;
+  completedResourceCount: CodegenTypes.Int32;
+  completedResourceSize: CodegenTypes.Int32;
+  completedTileCount: CodegenTypes.Int32;
+  completedTileSize: CodegenTypes.Int32;
+  requiredResourceCount: CodegenTypes.Int32;
+};
+
+type NativeOfflinePackError = {
+  id: string;
+  message: string;
+};
+
+export interface Spec extends TurboModule {
+  createPack(
+    options: NativeOfflinePackCreateOptions,
+  ): Promise<NativeOfflinePack>;
+  getPacks(): Promise<NativeOfflinePack[]>;
+  deletePack(id: string): Promise<void>;
+  invalidatePack(id: string): Promise<void>;
+
+  pausePackDownload(id: string): Promise<void>;
+  resumePackDownload(id: string): Promise<void>;
+  getPackStatus(id: string): Promise<NativeOfflinePackStatus>;
+  setPackObserver(id: string): Promise<boolean>;
+
+  invalidateAmbientCache(): Promise<void>;
+  clearAmbientCache(): Promise<void>;
+  setMaximumAmbientCacheSize(size: number): Promise<void>;
+  resetDatabase(): Promise<void>;
+
+  mergeOfflineRegions(path: string): Promise<void>;
+
+  setTileCountLimit(limit: number): void;
+  setProgressEventThrottle(throttleValue: number): void;
+
+  readonly onProgress: CodegenTypes.EventEmitter<NativeOfflinePackStatus>;
+  readonly onError: CodegenTypes.EventEmitter<NativeOfflinePackError>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>("MLRNOfflineModule");