@maplibre/maplibre-react-native 8.6.0-beta.0

package/javascript/modules/offline/offlineManager.js

@@ -0,0 +1,378 @@
+import {isUndefined, isFunction, isAndroid} from '../../utils';
+
+import OfflineCreatePackOptions from './OfflineCreatePackOptions';
+import OfflinePack from './OfflinePack';
+
+import {NativeModules, NativeEventEmitter} from 'react-native';
+
+const MapboxGL = NativeModules.MGLModule;
+const MapboxGLOfflineManager = NativeModules.MGLOfflineModule;
+export const OfflineModuleEventEmitter = new NativeEventEmitter(
+  MapboxGLOfflineManager,
+);
+
+/**
+ * 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 {
+  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 MapboxGL.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  {Callback=} progressListener Callback that listens for status events while downloading the offline resource.
+   * @param  {Callback=} errorListener Callback that listens for status events while downloading the offline resource.
+   * @return {void}
+   */
+  async createPack(options, progressListener, errorListener) {
+    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 MapboxGLOfflineManager.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 MapboxGL.offlineManager.invalidatePack('packName')
+   *
+   * @param  {String}  name  Name of the offline pack.
+   * @return {void}
+   */
+  async invalidatePack(name) {
+    if (!name) {
+      return;
+    }
+
+    await this._initialize();
+
+    const offlinePack = this._offlinePacks[name];
+    if (offlinePack) {
+      await MapboxGLOfflineManager.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 MapboxGL.offlineManager.deletePack('packName')
+   *
+   * @param  {String}  name  Name of the offline pack.
+   * @return {void}
+   */
+  async deletePack(name) {
+    if (!name) {
+      return;
+    }
+
+    await this._initialize();
+
+    const offlinePack = this._offlinePacks[name];
+    if (offlinePack) {
+      await MapboxGLOfflineManager.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 MapboxGL.offlineManager.invalidateAmbientCache();
+   *
+   * @return {void}
+   */
+  async invalidateAmbientCache() {
+    await this._initialize();
+    await MapboxGLOfflineManager.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 MapboxGL.offlineManager.clearAmbientCache();
+   *
+   * @return {void}
+   */
+  async clearAmbientCache() {
+    await this._initialize();
+    await MapboxGLOfflineManager.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 MapboxGL.offlineManager.setMaximumAmbientCacheSize(5000000);
+   *
+   * @param  {Number}  size  Size of ambient cache.
+   * @return {void}
+   */
+  async setMaximumAmbientCacheSize(size) {
+    await this._initialize();
+    await MapboxGLOfflineManager.setMaximumAmbientCacheSize(size);
+  }
+
+  /**
+   * Deletes the existing database, which includes both the ambient cache and offline packs, then reinitializes it.
+   *
+   * @example
+   * await MapboxGL.offlineManager.resetDatabase();
+   *
+   * @return {void}
+   */
+  async resetDatabase() {
+    await this._initialize();
+    await MapboxGLOfflineManager.resetDatabase();
+  }
+
+  /**
+   * Retrieves all the current offline packs that are stored in the database.
+   *
+   * @example
+   * const offlinePacks = await MapboxGL.offlineManager.getPacks();
+   *
+   * @return {Array<OfflinePack>}
+   */
+  async getPacks() {
+    await this._initialize();
+    return Object.keys(this._offlinePacks).map(
+      name => this._offlinePacks[name],
+    );
+  }
+
+  /**
+   * Retrieves an offline pack that is stored in the database by name.
+   *
+   * @example
+   * const offlinePack = await MapboxGL.offlineManager.getPack();
+   *
+   * @param  {String}  name  Name of the offline pack.
+   * @return {OfflinePack}
+   */
+  async getPack(name) {
+    await this._initialize();
+    return this._offlinePacks[name];
+  }
+
+  /**
+   * Sideloads offline db
+   *
+   * @example
+   * await MapboxGL.offlineManager.mergeOfflineRegions(path);
+   *
+   * @param {String} path Path to offline tile db on file system.
+   * @return {void}
+   */
+  async mergeOfflineRegions(path) {
+    await this._initialize();
+    return MapboxGLOfflineManager.mergeOfflineRegions(path);
+  }
+
+  /**
+   * Sets the maximum number of Mapbox-hosted tiles that may be downloaded and stored on the current device.
+   * The Mapbox Terms of Service prohibit changing or bypassing this limit without permission from Mapbox.
+   *
+   * @example
+   * MapboxGL.offlineManager.setTileCountLimit(1000);
+   *
+   * @param {Number} limit Map tile limit count.
+   * @return {void}
+   */
+  setTileCountLimit(limit) {
+    MapboxGLOfflineManager.setTileCountLimit(limit);
+  }
+
+  /**
+   * Sets the period at which download status events will be sent over the React Native bridge.
+   * The default is 500ms.
+   *
+   * @example
+   * MapboxGL.offlineManager.setProgressEventThrottle(500);
+   *
+   * @param {Number} throttleValue event throttle value in ms.
+   * @return {void}
+   */
+  setProgressEventThrottle(throttleValue) {
+    MapboxGLOfflineManager.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)
+   * MapboxGL.offlineManager.subscribe('packName', progressListener, errorListener)
+   *
+   * @param  {String} packName           Name of the offline pack.
+   * @param  {Callback} progressListener Callback that listens for status events while downloading the offline resource.
+   * @param  {Callback} errorListener      Callback that listens for status events while downloading the offline resource.
+   * @return {void}
+   */
+  async subscribe(packName, progressListener, errorListener) {
+    const totalProgressListeners = Object.keys(this._progressListeners).length;
+    if (isFunction(progressListener)) {
+      if (totalProgressListeners === 0) {
+        this.subscriptionProgress = OfflineModuleEventEmitter.addListener(
+          MapboxGL.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(
+          MapboxGL.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 MapboxGLOfflineManager.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
+   * MapboxGL.offlineManager.unsubscribe('packName')
+   *
+   * @param  {String} packName Name of the offline pack.
+   * @return {void}
+   */
+  unsubscribe(packName) {
+    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() {
+    if (this._hasInitialized) {
+      return true;
+    }
+
+    const nativeOfflinePacks = await MapboxGLOfflineManager.getPacks();
+
+    for (const nativeOfflinePack of nativeOfflinePacks) {
+      const offlinePack = new OfflinePack(nativeOfflinePack);
+      this._offlinePacks[offlinePack.name] = offlinePack;
+    }
+
+    this._hasInitialized = true;
+    return true;
+  }
+
+  _onProgress(e) {
+    const {name, state} = e.payload;
+
+    if (!this._hasListeners(name, this._progressListeners)) {
+      return;
+    }
+
+    const pack = this._offlinePacks[name];
+    this._progressListeners[name](pack, e.payload);
+
+    // cleanup listeners now that they are no longer needed
+    if (state === MapboxGL.OfflinePackDownloadState.Complete) {
+      this.unsubscribe(name);
+    }
+  }
+
+  _onError(e) {
+    const {name} = e.payload;
+
+    if (!this._hasListeners(name, this._errorListeners)) {
+      return;
+    }
+
+    const pack = this._offlinePacks[name];
+    this._errorListeners[name](pack, e.payload);
+  }
+
+  _hasListeners(name, listenerMap) {
+    return (
+      !isUndefined(this._offlinePacks[name]) && isFunction(listenerMap[name])
+    );
+  }
+}
+
+const offlineManager = new OfflineManager();
+export default offlineManager;

package/javascript/modules/snapshot/SnapshotOptions.js

@@ -0,0 +1,67 @@
+import {toJSONString} from '../../utils';
+import {makePoint, makeFeatureCollection} from '../../utils/geoUtils';
+
+import {NativeModules} from 'react-native';
+
+const MapboxGL = NativeModules.MGLModule;
+
+class SnapshotOptions {
+  constructor(options = {}) {
+    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 || MapboxGL.StyleURL.Street;
+    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() {
+    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) {
+    const point = makePoint(centerCoordinate);
+    return toJSONString(point);
+  }
+
+  _createBoundsCollection(bounds) {
+    const features = [];
+
+    for (const bound of bounds) {
+      features.push(makePoint(bound));
+    }
+
+    return toJSONString(makeFeatureCollection(features));
+  }
+}
+
+export default SnapshotOptions;

package/javascript/modules/snapshot/snapshotManager.js

@@ -0,0 +1,62 @@
+import SnapshotOptions from './SnapshotOptions';
+
+import {NativeModules} from 'react-native';
+
+const MapboxGLSnapshotManger = NativeModules.MGLSnapshotModule;
+
+/**
+ * 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 MapboxGL.snapshotManager.takeSnap({
+   *   centerCoordinate: [-74.126410, 40.797968],
+   *   width: width,
+   *   height: height,
+   *   zoomLevel: 12,
+   *   pitch: 30,
+   *   heading: 20,
+   *   styleURL: MapboxGL.StyleURL.Dark,
+   *   writeToDisk: true, // Create a temporary file
+   * });
+   *
+   * // creates base64 png of base map without logo
+   * const uri = await MapboxGL.snapshotManager.takeSnap({
+   *   centerCoordinate: [-74.126410, 40.797968],
+   *   width: width,
+   *   height: height,
+   *   zoomLevel: 12,
+   *   pitch: 30,
+   *   heading: 20,
+   *   styleURL: MapboxGL.StyleURL.Dark,
+   *   withLogo: false, // Disable Mapbox logo (Android only)
+   * });
+   *
+   * // creates snapshot with bounds
+   * const uri = await MapboxGL.snapshotManager.takeSnap({
+   *   bounds: [[-74.126410, 40.797968], [-74.143727, 40.772177]],
+   *   width: width,
+   *   height: height,
+   *   styleURL: MapboxGL.StyleURL.Dark,
+   * });
+   *
+   * @param  {SnapshotOptions}  options Snapshot options for create a static image of the base map
+   * @return {Promise}
+   */
+  async takeSnap(options = {}) {
+    const snapshotOptions = new SnapshotOptions(options);
+
+    const uri = await MapboxGLSnapshotManger.takeSnap(snapshotOptions);
+    return uri;
+  }
+}
+
+const snapshotManager = new SnapshotManager();
+export default snapshotManager;

package/javascript/utils/BridgeValue.js

@@ -0,0 +1,81 @@
+import {isBoolean, isNumber, isString} from './index';
+
+const Types = {
+  Array: 'array',
+  Bool: 'boolean',
+  Number: 'number',
+  String: 'string',
+  HashMap: 'hashmap',
+};
+
+export default class BridgeValue {
+  constructor(rawValue) {
+    this.rawValue = rawValue;
+  }
+
+  get type() {
+    if (Array.isArray(this.rawValue)) {
+      return Types.Array;
+    }
+    if (isBoolean(this.rawValue)) {
+      return Types.Bool;
+    }
+    if (isNumber(this.rawValue)) {
+      return Types.Number;
+    }
+    if (isString(this.rawValue)) {
+      return Types.String;
+    }
+    if (this.rawValue && typeof this.rawValue === 'object') {
+      return Types.HashMap;
+    }
+    throw new Error(
+      `[type - ${this.rawValue}] BridgeValue must be a primitive/array/object`,
+    );
+  }
+
+  get value() {
+    const {type} = this;
+
+    let value;
+
+    if (type === Types.Array) {
+      value = [];
+
+      for (const innerRawValue of this.rawValue) {
+        const bridgeValue = new BridgeValue(innerRawValue);
+        value.push(bridgeValue.toJSON());
+      }
+    } else if (type === Types.HashMap) {
+      value = [];
+
+      const stringKeys = Object.keys(this.rawValue);
+      for (const stringKey of stringKeys) {
+        value.push([
+          new BridgeValue(stringKey).toJSON(),
+          new BridgeValue(this.rawValue[stringKey]).toJSON(),
+        ]);
+      }
+    } else if (
+      type === Types.Bool ||
+      type === Types.Number ||
+      type === Types.String
+    ) {
+      value = this.rawValue;
+    } else {
+      throw new Error(
+        `[value - ${this.rawValue}] BridgeValue must be a primitive/array/object`,
+      );
+    }
+
+    return value;
+  }
+
+  toJSON(formatter) {
+    return {
+      type: this.type,
+      value:
+        typeof formatter === 'function' ? formatter(this.value) : this.value,
+    };
+  }
+}

package/javascript/utils/Logger.js

@@ -0,0 +1,114 @@
+import {NativeEventEmitter, NativeModules} from 'react-native';
+const {MGLLogging} = NativeModules;
+
+class Logger {
+  static instance = null;
+
+  static sharedInstance() {
+    if (this.instance === null) {
+      this.instance = new Logger();
+    }
+    return this.instance;
+  }
+
+  constructor() {
+    this.loggerEmitter = new NativeEventEmitter(MGLLogging);
+    this.startedCount = 0;
+    this.logCallback = null;
+  }
+
+  /**
+   * Set custom logger function.
+   * @param {Logger~logCallback} logCallback - callback taking a log object as param. If callback return falsy value then
+   * default logging will take place.
+   */
+  static setLogCallback(logCallback) {
+    this.sharedInstance().setLogCallback(logCallback);
+  }
+
+  /**
+   * Set custom logger function.
+   * @param {Logger~logCallback} logCallback - callback taking a log object as param. If callback return falsy value then
+   * default logging will take place.
+   */
+  setLogCallback(logCallback) {
+    this.logCallback = logCallback;
+  }
+
+  /**
+   * This callback is displayed as part of the Requester class.
+   * @callback Logger~logCallback
+   * @param {object} log
+   * @param {string} log.message - the message of the log
+   * @param {string} log.level - log level
+   * @param {string} log.tag - optional tag used on android
+   */
+
+  /**
+   * setLogLevel
+   * @param {LogLevel} level
+   */
+  static setLogLevel(level) {
+    MGLLogging.setLogLevel(level);
+  }
+
+  /**
+   * @type {('error'|'warning'|'info'|'debug'|'verbose')} LogLevel - Supported log levels
+   */
+
+  start() {
+    if (this.startedCount === 0) {
+      this.subscribe();
+    }
+    this.startedCount += 1;
+  }
+
+  stop() {
+    this.startedCount -= 1;
+    if (this.startedCount === 0) {
+      this.unsubscribe();
+    }
+  }
+
+  subscribe() {
+    this.subscription = this.loggerEmitter.addListener('LogEvent', log => {
+      this.onLog(log);
+    });
+  }
+
+  unsubscribe() {
+    this.subscription.remove();
+    this.subscription = null;
+  }
+
+  effectiveLevel(log) {
+    let {level, message, tag} = log;
+
+    if (level === 'warning') {
+      if (
+        tag === 'Mbgl-HttpRequest' &&
+        message.startsWith('Request failed due to a permanent error: Canceled')
+      ) {
+        // this seems to happening too much to show a warning every time
+        return 'info';
+      }
+    }
+    return level;
+  }
+
+  onLog(log) {
+    if (!this.logCallback || !this.logCallback(log)) {
+      let {message} = log;
+      let level = this.effectiveLevel(log);
+      if (level === 'error') {
+        console.error('Mapbox error', message, log);
+      } else if (level === 'warning') {
+        console.warn('Mapbox warning', message, log);
+      } else {
+        console.log(`Mapbox [${level}]`, message, log);
+      }
+    }
+  }
+}
+
+export default Logger;