@maplibre/maplibre-react-native 10.0.0-alpha.9 → 10.0.0-beta.1

package/src/modules/offline/offlineManager.ts

@@ -0,0 +1,438 @@
+import {
+  NativeModules,
+  NativeEventEmitter,
+  type EventSubscription,
+} from "react-native";
+
+import OfflineCreatePackOptions, {
+  type OfflineCreatePackInputOptions,
+} from "./OfflineCreatePackOptions";
+import OfflinePack from "./OfflinePack";
+import { isUndefined, isFunction, isAndroid } from "../../utils";
+
+const MapLibreRN = NativeModules.MLRNModule;
+const MLRNOfflineModule = NativeModules.MLRNOfflineModule;
+export const OfflineModuleEventEmitter = new NativeEventEmitter(
+  MLRNOfflineModule,
+);
+
+export type OfflineProgressStatus = {
+  name: string;
+  state: number;
+  percentage: number;
+  completedResourceSize: number;
+  completedTileCount: number;
+  completedResourceCount: number;
+  requiredResourceCount: number;
+  completedTileSize: number;
+};
+
+export type OfflinePackError = {
+  name: string;
+  message: string;
+};
+
+type ErrorEvent = {
+  payload: OfflinePackError;
+};
+
+type ProgressEvent = {
+  payload: OfflineProgressStatus;
+};
+
+type ProgressListener = (
+  pack: OfflinePack,
+  status: OfflineProgressStatus,
+) => void;
+type ErrorListener = (pack: OfflinePack, err: OfflinePackError) => void;
+
+/**
+ * OfflineManager implements a singleton (shared object) that manages offline packs.
+ * All of this class’s instance methods are asynchronous, reflecting the fact that offline resources are stored in a database.
+ * The shared object maintains a canonical collection of offline packs.
+ */
+class OfflineManager {
+  _hasInitialized: boolean;
+  _offlinePacks: Record<string, OfflinePack>;
+  _progressListeners: Record<string, ProgressListener>;
+  _errorListeners: Record<string, ErrorListener>;
+  subscriptionProgress: EventSubscription | null;
+  subscriptionError: EventSubscription | null;
+
+  constructor() {
+    this._hasInitialized = false;
+    this._offlinePacks = {};
+
+    this._progressListeners = {};
+    this._errorListeners = {};
+
+    this._onProgress = this._onProgress.bind(this);
+    this._onError = this._onError.bind(this);
+
+    this.subscriptionProgress = null;
+    this.subscriptionError = null;
+  }
+
+  /**
+   * Creates and registers an offline pack that downloads the resources needed to use the given region offline.
+   *
+   * @example
+   *
+   * const progressListener = (offlineRegion, status) => console.log(offlineRegion, status);
+   * const errorListener = (offlineRegion, err) => console.log(offlineRegion, err);
+   *
+   * await MapLibreGL.offlineManager.createPack({
+   *   name: 'offlinePack',
+   *   styleURL: 'mapbox://...',
+   *   minZoom: 14,
+   *   maxZoom: 20,
+   *   bounds: [[neLng, neLat], [swLng, swLat]]
+   * }, progressListener, errorListener)
+   *
+   * @param  {OfflineCreatePackOptions} options Create options for a offline pack that specifices zoom levels, style url, and the region to download.
+   * @param  {ProgressListener} progressListener Callback that listens for status events while downloading the offline resource.
+   * @param  {ErrorListener} errorListener Callback that listens for status events while downloading the offline resource.
+   * @return {void}
+   */
+  async createPack(
+    options: OfflineCreatePackInputOptions,
+    progressListener: ProgressListener,
+    errorListener: ErrorListener,
+  ): Promise<void> {
+    await this._initialize();
+
+    const packOptions = new OfflineCreatePackOptions(options);
+
+    if (this._offlinePacks[packOptions.name]) {
+      throw new Error(
+        `Offline pack with name ${packOptions.name} already exists.`,
+      );
+    }
+
+    this.subscribe(packOptions.name, progressListener, errorListener);
+    const nativeOfflinePack = await MLRNOfflineModule.createPack(packOptions);
+    this._offlinePacks[packOptions.name] = new OfflinePack(nativeOfflinePack);
+  }
+
+  /**
+   * Invalidates the specified offline pack. This method checks that the tiles in the specified offline pack match those from the server. Local tiles that do not match the latest version on the server are updated.
+   *
+   * This is more efficient than deleting the offline pack and downloading it again. If the data stored locally matches that on the server, new data will not be downloaded.
+   *
+   * @example
+   * await MapLibreGL.offlineManager.invalidatePack('packName')
+   *
+   * @param  {String}  name  Name of the offline pack.
+   * @return {void}
+   */
+  async invalidatePack(name: string): Promise<void> {
+    if (!name) {
+      return;
+    }
+
+    await this._initialize();
+
+    const offlinePack = this._offlinePacks[name];
+    if (offlinePack) {
+      await MLRNOfflineModule.invalidatePack(name);
+    }
+  }
+
+  /**
+   * Unregisters the given offline pack and allows resources that are no longer required by any remaining packs to be potentially freed.
+   *
+   * @example
+   * await MapLibreGL.offlineManager.deletePack('packName')
+   *
+   * @param  {String}  name  Name of the offline pack.
+   * @return {void}
+   */
+  async deletePack(name: string): Promise<void> {
+    if (!name) {
+      return;
+    }
+
+    await this._initialize();
+
+    const offlinePack = this._offlinePacks[name];
+    if (offlinePack) {
+      await MLRNOfflineModule.deletePack(name);
+      delete this._offlinePacks[name];
+    }
+  }
+
+  /**
+   * Forces a revalidation of the tiles in the ambient cache and downloads a fresh version of the tiles from the tile server.
+   * This is the recommend method for clearing the cache.
+   * This is the most efficient method because tiles in the ambient cache are re-downloaded to remove outdated data from a device.
+   * It does not erase resources from the ambient cache or delete the database, which can be computationally expensive operations that may carry unintended side effects.
+   *
+   * @example
+   * await MapLibreGL.offlineManager.invalidateAmbientCache();
+   *
+   * @return {void}
+   */
+  async invalidateAmbientCache(): Promise<void> {
+    await this._initialize();
+    await MLRNOfflineModule.invalidateAmbientCache();
+  }
+
+  /**
+   * Erases resources from the ambient cache.
+   * This method clears the cache and decreases the amount of space that map resources take up on the device.
+   *
+   * @example
+   * await MapLibreGL.offlineManager.clearAmbientCache();
+   *
+   * @return {void}
+   */
+  async clearAmbientCache(): Promise<void> {
+    await this._initialize();
+    await MLRNOfflineModule.clearAmbientCache();
+  }
+
+  /**
+   * Sets the maximum size of the ambient cache in bytes. Disables the ambient cache if set to 0.
+   * This method may be computationally expensive because it will erase resources from the ambient cache if its size is decreased.
+   *
+   * @example
+   * await MapLibreGL.offlineManager.setMaximumAmbientCacheSize(5000000);
+   *
+   * @param  {Number}  size  Size of ambient cache.
+   * @return {void}
+   */
+  async setMaximumAmbientCacheSize(size: number): Promise<void> {
+    await this._initialize();
+    await MLRNOfflineModule.setMaximumAmbientCacheSize(size);
+  }
+
+  /**
+   * Deletes the existing database, which includes both the ambient cache and offline packs, then reinitializes it.
+   *
+   * @example
+   * await MapLibreGL.offlineManager.resetDatabase();
+   *
+   * @return {void}
+   */
+  async resetDatabase(): Promise<void> {
+    await this._initialize();
+    await MLRNOfflineModule.resetDatabase();
+  }
+
+  /**
+   * Retrieves all the current offline packs that are stored in the database.
+   *
+   * @example
+   * const offlinePacks = await MapLibreGL.offlineManager.getPacks();
+   *
+   * @return {Array<OfflinePack>}
+   */
+  async getPacks(): Promise<OfflinePack[]> {
+    await this._initialize();
+
+    return Object.keys(this._offlinePacks)
+      .map((name) => this._offlinePacks[name])
+      .filter((pack) => !!pack);
+  }
+
+  /**
+   * Retrieves an offline pack that is stored in the database by name.
+   *
+   * @example
+   * const offlinePack = await MapLibreGL.offlineManager.getPack();
+   *
+   * @param  {String}  name  Name of the offline pack.
+   * @return {OfflinePack}
+   */
+  async getPack(name: string) {
+    await this._initialize();
+    return this._offlinePacks[name];
+  }
+
+  /**
+   * Sideloads offline db
+   *
+   * @example
+   * await MapLibreGL.offlineManager.mergeOfflineRegions(path);
+   *
+   * @param {String} path Path to offline tile db on file system.
+   * @return {void}
+   */
+  async mergeOfflineRegions(path: string): Promise<void> {
+    await this._initialize();
+    return MLRNOfflineModule.mergeOfflineRegions(path);
+  }
+
+  /**
+   * Sets the maximum number of tiles that may be downloaded and stored on the current device.
+   * Consult the Terms of Service for your map tile host before changing this value.
+   *
+   * @example
+   * MapLibreGL.offlineManager.setTileCountLimit(1000);
+   *
+   * @param {Number} limit Map tile limit count.
+   * @return {void}
+   */
+  setTileCountLimit(limit: number): void {
+    MLRNOfflineModule.setTileCountLimit(limit);
+  }
+
+  /**
+   * Sets the period at which download status events will be sent over the React Native bridge.
+   * The default is 500ms.
+   *
+   * @example
+   * MapLibreGL.offlineManager.setProgressEventThrottle(500);
+   *
+   * @param {Number} throttleValue event throttle value in ms.
+   * @return {void}
+   */
+  setProgressEventThrottle(throttleValue: number): void {
+    MLRNOfflineModule.setProgressEventThrottle(throttleValue);
+  }
+
+  /**
+   * Subscribe to download status/error events for the requested offline pack.
+   * Note that createPack calls this internally if listeners are provided.
+   *
+   * @example
+   * const progressListener = (offlinePack, status) => console.log(offlinePack, status)
+   * const errorListener = (offlinePack, err) => console.log(offlinePack, err)
+   * MapLibreGL.offlineManager.subscribe('packName', progressListener, errorListener)
+   *
+   * @param  {string} packName           Name of the offline pack.
+   * @param  {ProgressListener} progressListener Callback that listens for status events while downloading the offline resource.
+   * @param  {ErrorListener} errorListener      Callback that listens for status events while downloading the offline resource.
+   * @return {void}
+   */
+  async subscribe(
+    packName: string,
+    progressListener: ProgressListener,
+    errorListener: ErrorListener,
+  ): Promise<void> {
+    const totalProgressListeners = Object.keys(this._progressListeners).length;
+    if (isFunction(progressListener)) {
+      if (totalProgressListeners === 0) {
+        this.subscriptionProgress = OfflineModuleEventEmitter.addListener(
+          MapLibreRN.OfflineCallbackName.Progress,
+          this._onProgress,
+        );
+      }
+      this._progressListeners[packName] = progressListener;
+    }
+
+    const totalErrorListeners = Object.keys(this._errorListeners).length;
+    if (isFunction(errorListener)) {
+      if (totalErrorListeners === 0) {
+        this.subscriptionError = OfflineModuleEventEmitter.addListener(
+          MapLibreRN.OfflineCallbackName.Error,
+          this._onError,
+        );
+      }
+      this._errorListeners[packName] = errorListener;
+    }
+
+    // we need to manually set the pack observer on Android
+    // if we're resuming a pack download instead of going thru the create flow
+    if (isAndroid() && this._offlinePacks[packName]) {
+      try {
+        // manually set a listener, since listeners are only set on create flow
+        await MLRNOfflineModule.setPackObserver(packName);
+      } catch (e) {
+        console.log("Unable to set pack observer", e);
+      }
+    }
+  }
+
+  /**
+   * Unsubscribes any listeners associated with the offline pack.
+   * It's a good idea to call this on componentWillUnmount.
+   *
+   * @example
+   * MapLibreGL.offlineManager.unsubscribe('packName')
+   *
+   * @param  {String} packName Name of the offline pack.
+   * @return {void}
+   */
+  unsubscribe(packName: string): void {
+    delete this._progressListeners[packName];
+    delete this._errorListeners[packName];
+
+    if (
+      Object.keys(this._progressListeners).length === 0 &&
+      this.subscriptionProgress
+    ) {
+      this.subscriptionProgress.remove();
+    }
+
+    if (
+      Object.keys(this._errorListeners).length === 0 &&
+      this.subscriptionError
+    ) {
+      this.subscriptionError.remove();
+    }
+  }
+
+  async _initialize(): Promise<boolean> {
+    if (this._hasInitialized) {
+      return true;
+    }
+
+    const nativeOfflinePacks = await MLRNOfflineModule.getPacks();
+
+    for (const nativeOfflinePack of nativeOfflinePacks) {
+      const offlinePack = new OfflinePack(nativeOfflinePack);
+      if (offlinePack.name) {
+        this._offlinePacks[offlinePack.name] = offlinePack;
+      }
+    }
+
+    this._hasInitialized = true;
+    return true;
+  }
+
+  _onProgress(e: ProgressEvent): void {
+    const { name, state } = e.payload;
+
+    if (!this._hasListeners(name, this._progressListeners)) {
+      return;
+    }
+
+    const pack = this._offlinePacks[name];
+    if (pack) {
+      this._progressListeners[name]?.(pack, e.payload);
+    }
+
+    // cleanup listeners now that they are no longer needed
+    if (state === MapLibreRN.OfflinePackDownloadState.Complete) {
+      this.unsubscribe(name);
+    }
+  }
+
+  _onError(e: ErrorEvent): void {
+    const { name } = e.payload;
+
+    if (!this._hasListeners(name, this._errorListeners)) {
+      return;
+    }
+
+    const pack = this._offlinePacks[name];
+    if (pack) {
+      this._errorListeners[name]?.(pack, e.payload);
+    }
+  }
+
+  _hasListeners(
+    name: string,
+    listenerMap:
+      | Record<string, ProgressListener>
+      | Record<string, ErrorListener>,
+  ): boolean {
+    return (
+      !isUndefined(this._offlinePacks[name]) && isFunction(listenerMap[name])
+    );
+  }
+}
+
+const offlineManager = new OfflineManager();
+export default offlineManager;

package/src/modules/snapshot/SnapshotOptions.ts

@@ -0,0 +1,103 @@
+import { featureCollection, point } from "@turf/helpers";
+import { NativeModules } from "react-native";
+
+import { toJSONString } from "../../utils";
+
+const MapLibreRN = NativeModules.MLRNModule;
+
+export interface SnapshotInputOptions {
+  centerCoordinate?: GeoJSON.Position;
+  bounds?: GeoJSON.Position[];
+  styleURL?: string;
+  heading?: number;
+  pitch?: number;
+  zoomLevel?: number;
+  width?: number;
+  height?: number;
+  writeToDisk?: boolean;
+  withLogo?: boolean;
+}
+
+interface SnapshotJsonOptions {
+  centerCoordinate?: string;
+  bounds?: string;
+  styleURL: string;
+  heading: number;
+  pitch: number;
+  zoomLevel: number;
+  width: number;
+  height: number;
+  writeToDisk: boolean;
+  withLogo: boolean;
+}
+
+export class SnapshotOptions {
+  centerCoordinate?: string;
+  bounds?: string;
+  styleURL: string;
+  heading: number;
+  pitch: number;
+  zoomLevel: number;
+  width: number;
+  height: number;
+  writeToDisk: boolean;
+  withLogo: boolean;
+
+  constructor(options: SnapshotInputOptions) {
+    if (!options.centerCoordinate && !options.bounds) {
+      throw new Error(
+        "Center coordinate or bounds must be supplied in order to take a snapshot",
+      );
+    }
+
+    this.styleURL = options.styleURL || MapLibreRN.StyleURL.Default;
+    this.heading = options.heading || 0.0;
+    this.pitch = options.pitch || 0.0;
+    this.zoomLevel = options.zoomLevel || 16.0;
+    this.width = options.width || 50.0;
+    this.height = options.height || 50.0;
+    this.writeToDisk = options.writeToDisk || false;
+    this.withLogo = options.withLogo === undefined ? true : options.withLogo;
+
+    if (options.centerCoordinate) {
+      this.centerCoordinate = this._createCenterCoordPoint(
+        options.centerCoordinate,
+      );
+    }
+
+    if (options.bounds) {
+      this.bounds = this._createBoundsCollection(options.bounds);
+    }
+  }
+
+  toJSON(): SnapshotJsonOptions {
+    return {
+      styleURL: this.styleURL,
+      heading: this.heading,
+      pitch: this.pitch,
+      zoomLevel: this.zoomLevel,
+      width: this.width,
+      height: this.height,
+      writeToDisk: this.writeToDisk,
+      centerCoordinate: this.centerCoordinate,
+      bounds: this.bounds,
+      withLogo: this.withLogo,
+    };
+  }
+
+  _createCenterCoordPoint(centerCoordinate: GeoJSON.Position): string {
+    return toJSONString(point(centerCoordinate));
+  }
+
+  _createBoundsCollection(bounds: GeoJSON.Position[]): string {
+    const features = [];
+
+    for (const bound of bounds) {
+      features.push(point(bound));
+    }
+
+    return toJSONString(featureCollection(features));
+  }
+}
+
+export default SnapshotOptions;

package/src/modules/snapshot/snapshotManager.ts

@@ -0,0 +1,62 @@
+import { NativeModules } from "react-native";
+
+import SnapshotOptions, { type SnapshotInputOptions } from "./SnapshotOptions";
+
+const MLRNSnapshotModule = NativeModules.MLRNSnapshotModule;
+
+/**
+ * The snapshotManager generates static raster images of the map.
+ * Each snapshot image depicts a portion of a map defined by an SnapshotOptions object you provide.
+ * The snapshotter generates the snapshot asynchronous.
+ */
+class SnapshotManager {
+  /**
+   * Takes a snapshot of the base map using the provided Snapshot options. NOTE pitch, heading, zoomLevel only works when centerCoordinate is set!
+   *
+   * @example
+   *
+   * // creates a temp file png of base map
+   * const uri = await MapLibreGL.snapshotManager.takeSnap({
+   *   centerCoordinate: [-74.126410, 40.797968],
+   *   width: width,
+   *   height: height,
+   *   zoomLevel: 12,
+   *   pitch: 30,
+   *   heading: 20,
+   *   styleURL: MapLibreGL.StyleURL.Default,
+   *   writeToDisk: true, // Create a temporary file
+   * });
+   *
+   * // creates base64 png of base map without logo
+   * const uri = await MapLibreGL.snapshotManager.takeSnap({
+   *   centerCoordinate: [-74.126410, 40.797968],
+   *   width: width,
+   *   height: height,
+   *   zoomLevel: 12,
+   *   pitch: 30,
+   *   heading: 20,
+   *   styleURL: MapLibreGL.StyleURL.Default,
+   *   withLogo: false, // Disable Mapbox logo (Android only)
+   * });
+   *
+   * // creates snapshot with bounds
+   * const uri = await MapLibreGL.snapshotManager.takeSnap({
+   *   bounds: [[-74.126410, 40.797968], [-74.143727, 40.772177]],
+   *   width: width,
+   *   height: height,
+   *   styleURL: MapLibreGL.StyleURL.Default,
+   * });
+   *
+   * @param  {SnapshotOptions}  options Snapshot options for create a static image of the base map
+   * @return {Promise}
+   */
+  async takeSnap(options: SnapshotInputOptions = {}): Promise<string> {
+    const snapshotOptions = new SnapshotOptions(options);
+
+    const uri = await MLRNSnapshotModule.takeSnap(snapshotOptions);
+    return uri;
+  }
+}
+
+const snapshotManager = new SnapshotManager();
+export default snapshotManager;

package/src/requestAndroidLocationPermissions.ts

@@ -0,0 +1,29 @@
+import { type Permission, PermissionsAndroid } from "react-native";
+
+import { isAndroid } from "./utils";
+
+export async function requestAndroidLocationPermissions(): Promise<boolean> {
+  if (isAndroid()) {
+    const res = await PermissionsAndroid.requestMultiple([
+      PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION as Permission,
+      PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION as Permission,
+    ]);
+
+    if (!res) {
+      return false;
+    }
+
+    const permissions: string[] = Object.keys(res);
+    for (const permission of permissions) {
+      if (
+        res[permission as Permission] === PermissionsAndroid.RESULTS.GRANTED
+      ) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  throw new Error("You should only call this method on Android!");
+}

package/src/types/BaseProps.ts

@@ -0,0 +1,3 @@
+export interface BaseProps {
+  testID?: string;
+}

package/src/types/CameraMode.ts

@@ -0,0 +1,6 @@
+export enum CameraMode {
+  Flight = 1,
+  Ease = 2,
+  Linear = 3,
+  None = 4,
+}

package/src/types/MapLibreRNEvent.ts

@@ -0,0 +1,7 @@
+import { type SyntheticEvent } from "react";
+
+export type MapLibreRNEvent<
+  T extends string,
+  P = GeoJSON.Feature,
+  V = Element,
+> = SyntheticEvent<V, { type: T; payload: P }>;

package/src/types/OnPressEvent.ts

@@ -0,0 +1,11 @@
+export interface OnPressEvent {
+  features: GeoJSON.Feature[];
+  coordinates: {
+    latitude: number;
+    longitude: number;
+  };
+  point: {
+    x: number;
+    y: number;
+  };
+}

package/src/types/StyleURL.ts

@@ -0,0 +1,3 @@
+export enum StyleURL {
+  Default = "https://demotiles.maplibre.org/style.json",
+}