@nativescript-community/ui-mapbox 6.2.19 → 6.2.21

package/index.ios.js

@@ -397,6 +397,7 @@ var MapSwipeHandlerImpl = /** @class */ (function (_super) {
     };
     return MapSwipeHandlerImpl;
 }(NSObject));
+// Export the enums for devs not using TS
 export * from './common';
 let _markers = [];
 const _markerIconDownloadCache = [];
@@ -416,7 +417,7 @@ const _setMapboxMapOptions = (mapView, settings) => {
         mapView.setZoomLevelAnimated(settings.zoomLevel, false);
     }
     mapView.showsUserLocation = settings.showUserLocation;
-    mapView.autoresizingMask = 2 | 16;
+    mapView.autoresizingMask = 2 /* UIViewAutoresizing.FlexibleWidth */ | 16 /* UIViewAutoresizing.FlexibleHeight */;
 };
 const _getMapStyle = (input) => {
     if (input.startsWith('mapbox://styles') || input.startsWith('http://') || input.startsWith('https://')) {
@@ -468,24 +469,30 @@ export function setLogLevel(level) {
     let loggingLevel;
     switch (level) {
         case 'none':
-            loggingLevel = 0;
+            loggingLevel = 0 /* MGLLoggingLevel.None */;
             break;
         case 'info':
-            loggingLevel = 1;
+            loggingLevel = 1 /* MGLLoggingLevel.Info */;
             break;
         case 'verbose':
         case 'debug':
-            loggingLevel = 2;
+            loggingLevel = 2 /* MGLLoggingLevel.Debug */;
             break;
         case 'error':
-            loggingLevel = 3;
+            loggingLevel = 3 /* MGLLoggingLevel.Error */;
             break;
         case 'fault':
-            loggingLevel = 4;
+            loggingLevel = 4 /* MGLLoggingLevel.Fault */;
             break;
     }
     MGLLoggingConfiguration.sharedConfiguration.loggingLevel = loggingLevel;
 }
+/**
+ * Map View Class instantiated from XML
+ *
+ * This class is created by the NativeScript XML view parsing
+ * code.
+ */
 export class MapboxView extends MapboxViewBase {
     constructor() {
         super(...arguments);
@@ -493,8 +500,13 @@ export class MapboxView extends MapboxViewBase {
         this.delegate = null;
         this.settings = null;
         this.initialized = false;
+        // see initMap. Count of how many times we've
+        // tried to init the map.
         this.initCountHack = 50;
     }
+    /**
+     * programmatically include settings
+     */
     setConfig(settings) {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'setConfig(): settings:', settings);
@@ -511,6 +523,19 @@ export class MapboxView extends MapboxViewBase {
         const v = super.createNativeView();
         return v;
     }
+    /**
+     * init the native view.
+     *
+     * FIXME: It appears that the order of events is different between iOS and Android.
+     * In the demo under Android, the main-page event handler is called first then the one
+     * in the plugin. Under iOS it's the reverse.
+     *
+     * The symptom is that any properties that reference a binding aren't available
+     * at the time this method is called. For example {{access_token}}.
+     *
+     * I'm sure there is something I do not understand about how this is supposed to work
+     * and that the handstands below are not necessary.
+     */
     onLoaded() {
         super.onLoaded();
         if (Trace.isEnabled()) {
@@ -528,6 +553,15 @@ export class MapboxView extends MapboxViewBase {
         super.initNativeView();
         this.nativeView.owner = this;
     }
+    /**
+     * when the view is destroyed.
+     *
+     * This is called by the framework when the view is destroyed (made not visible).
+     *
+     * However, it does not seem to be called when the page is unloaded.
+     *
+     * @link https://docs.nativescript.org/plugins/ui-plugin-custom
+     */
     async disposeNativeView() {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'disposeNativeView(): top');
@@ -542,20 +576,39 @@ export class MapboxView extends MapboxViewBase {
             CLog(CLogTypes.info, 'disposeNativeView(): bottom');
         }
     }
+    /**
+     * returns a reference to the class Mapbox API shim instance
+     *
+     * @see Mapbox
+     */
     getMapboxApi() {
         return this.mapbox;
     }
+    /**
+     * initialize the map
+     *
+     * @see MGLMapViewDelegateImpl
+     *
+     * @todo FIXME: figure out why the accessToken property (which is using a binding in the demo XML) isn't set before we arrive here.
+     */
     initMap() {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'initMap() top with settings:', this.settings);
         }
+        // FIXME: HACK: if we are arriving here because of an XML parse the property evaluations may not have
+        // happened yet. This needs to be redone, but for the moment we'll assume the accessToken is done
+        // via a property eval (since it really shouldn't be hard coded in XML).
+        //
+        // settings will only be set here if we are programmatically showing a map.
         if (!this.settings && !this.config.accessToken) {
             if (Trace.isEnabled()) {
                 CLog(CLogTypes.info, 'initMap() no access token. Race condition on XML property evaluation?');
             }
+            // If the user didn't specify an accessToken we don't want to loop forever
             if (this.initCountHack > 50) {
                 return;
             }
+            // FIXME: super ugly.
             setTimeout(() => {
                 this.initMap();
             }, 50);
@@ -573,13 +626,18 @@ export class MapboxView extends MapboxViewBase {
             if (Trace.isEnabled()) {
                 CLog(CLogTypes.info, 'initMap(): after new Mapbox()');
             }
+            // called in a setTimeout call at the bottom.
             const drawMap = () => {
                 MGLAccountManager.accessToken = this.settings.accessToken;
                 this.nativeMapView = MGLMapView.alloc().initWithFrameStyleURL(CGRectMake(0, 0, this.nativeView.frame.size.width, this.nativeView.frame.size.height), _getMapStyle(this.settings.style));
+                // this delegate class is defined later in this file and is where, in Obj-C land,
+                // callbacks are delivered and handled.
                 this.nativeMapView.delegate = this.delegate = MGLMapViewDelegateImpl.new().initWithCallback(() => {
                     if (Trace.isEnabled()) {
                         CLog(CLogTypes.info, 'initMap(): MLMapViewDeleteImpl onMapReady callback');
                     }
+                    // FIXME: on the Android side the view is created in Mapbox::show(). On the iOS side it's created
+                    // here in MapboxView, however the mapbox api still needs a reference to it.
                     this.mapbox.setMapboxViewInstance(this.nativeMapView);
                     this.mapbox.initEventHandlerShim(this.settings, this.nativeMapView);
                     this.notify({
@@ -588,6 +646,7 @@ export class MapboxView extends MapboxViewBase {
                         map: this,
                         ios: this.nativeMapView
                     });
+                    // no permission required, but to align with Android we fire the event anyway
                     this.notify({
                         eventName: MapboxViewBase.locationPermissionGrantedEvent,
                         object: this,
@@ -595,9 +654,14 @@ export class MapboxView extends MapboxViewBase {
                         ios: this.nativeMapView
                     });
                 });
+                // this.delegate.setStyleLoadedCallback((map, style)=>{
+                //     this.delegate.setStyleLoadedCallback(null);
+                // });
                 _setMapboxMapOptions(this.nativeMapView, this.settings);
                 _markers = [];
                 this.nativeView.addSubview(this.nativeMapView);
+                // this.notify will notify an event listener specified
+                // in the XML, in this case (onMoveBegin)="..."
                 this.mapbox.setOnMoveBeginListener((data) => {
                     if (Trace.isEnabled()) {
                         CLog(CLogTypes.info, 'initMap(): onMoveBegin listener');
@@ -632,9 +696,10 @@ export class MapboxView extends MapboxViewBase {
                     });
                 }, this.nativeMapView);
             };
+            // draw the map after a timeout
             setTimeout(drawMap, this.settings.delay ? this.settings.delay : 0);
         }
-    }
+    } // end of initMap()
     onLayout(left, top, right, bottom) {
         super.onLayout(left, top, right, bottom);
         if (this.nativeMapView) {
@@ -647,18 +712,36 @@ export class MapboxView extends MapboxViewBase {
 }
 export class Mapbox extends MapboxCommon {
     constructor() {
+        // reference to the native mapbox API
         super(...arguments);
         this.eventCallbacks = {};
     }
+    /**
+     * set the mapboxViewInstance
+     *
+     * @see MapboxView::initMap();
+     */
     setMapboxViewInstance(mapboxViewInstance) {
         this._mapboxViewInstance = mapboxViewInstance;
     }
+    /**
+     * event handler shim
+     *
+     * Initialize our event handler shim so that we can intercept events here.
+     *
+     * @param { MapboxView } mapboxView
+     */
     initEventHandlerShim(settings, mapboxNativeViewInstance) {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'Mapbox:initEventHandlerShim(): top');
         }
         this.setOnMapClickListener((point) => this.checkForClickEvent(point), mapboxNativeViewInstance);
     }
+    /**
+     * register a map event handler
+     *
+     * The NativeScript ContentView base class as on() and off() methods.
+     */
     onMapEvent(eventName, id, callback, nativeMapView) {
         if (typeof this.eventCallbacks[eventName] == 'undefined') {
             this.eventCallbacks[eventName] = [];
@@ -674,6 +757,9 @@ export class Mapbox extends MapboxCommon {
         }
         this.eventCallbacks[eventName] = this.eventCallbacks[eventName].filter((entry) => entry.id !== id);
     }
+    /**
+     * If click events registered and a feature found for the event, then fire listener.
+     */
     checkForClickEvent(point, nativeMap) {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'Mapbox:checkForClickEvent(): got click event with point:', point);
@@ -715,6 +801,7 @@ export class Mapbox extends MapboxCommon {
                 point.coordinate = CLLocationCoordinate2DMake(lat, lng);
                 point.title = marker.title;
                 point.subtitle = marker.subtitle;
+                // needs to be done before adding to the map, otherwise the delegate method 'mapViewImageForAnnotation' can't use it
                 _markers.push(marker);
                 theMap.addAnnotation(point);
                 if (marker.selected) {
@@ -750,6 +837,11 @@ export class Mapbox extends MapboxCommon {
             });
         });
     }
+    /**
+     * create an display the map
+     *
+     * @todo FIXME: This method is not called. See MapboxView::initMap().
+     */
     show(options) {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'show(): top with options:', options);
@@ -757,10 +849,14 @@ export class Mapbox extends MapboxCommon {
         return new Promise((resolve, reject) => {
             try {
                 const settings = Mapbox.merge(options, Mapbox.defaults);
+                // let directions = MBDirections.alloc().initWithAccessToken(arg.accessToken);
+                // alert("directions: " + directions);
+                // if no accessToken was set the app may crash
                 if (settings.accessToken === undefined) {
                     reject("Please set the 'accessToken' parameter");
                     return;
                 }
+                // if already added, make sure it's removed first
                 if (this._mapboxViewInstance) {
                     this._mapboxViewInstance.removeFromSuperview();
                 }
@@ -775,6 +871,7 @@ export class Mapbox extends MapboxCommon {
                 });
                 _markers = [];
                 this._addMarkers(settings.markers);
+                // wrapping in a little timeout since the map area tends to flash black a bit initially
                 setTimeout(() => {
                     view.addSubview(this._mapboxViewInstance);
                 }, 500);
@@ -833,6 +930,9 @@ export class Mapbox extends MapboxCommon {
             resolve();
         });
     }
+    // ----------------------------------------
+    // Life Cycle Hooks - Required on Android
+    // ----------------------------------------
     onStart(nativeMap) {
         return Promise.resolve();
     }
@@ -851,10 +951,15 @@ export class Mapbox extends MapboxCommon {
     onDestroy(nativeMap) {
         return Promise.resolve();
     }
+    /**
+     * explicitly set a map style
+     */
     setMapStyle(style, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
                 const theMap = nativeMap || this._mapboxViewInstance;
+                // the style takes some time to load so we have to set a callback
+                // to wait for the style to finish loading
                 const delegate = theMap.delegate;
                 delegate.setStyleLoadedCallback((mapView) => {
                     if (Trace.isEnabled()) {
@@ -963,6 +1068,7 @@ export class Mapbox extends MapboxCommon {
                         markersToRemove.push(marker.ios);
                     }
                 });
+                // remove markers from cache
                 if (ids) {
                     _markers = _markers.filter((marker) => ids.indexOf(marker.id) < 0);
                 }
@@ -1107,28 +1213,36 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * convert string to camera mode constant.
+     *
+     * Supported modes on iOS are different than on Android.
+     *
+     * @todo come up with a reasonable set of cross platform defaults.
+     */
     _stringToCameraMode(mode) {
         switch (mode) {
-            case "NONE":
-                return 0;
-            case "NONE_COMPASS":
-                console.log("MapboxView::_stringToCameraMode(): NONE_COMPASS unsupported on iOS");
-                return 0;
-            case "NONE_GPS":
-                console.log("MapboxView::_stringToCameraMode(): NONE_GPS unsupported on iOS");
-                return 0;
-            case "TRACKING":
-                return 1;
-            case "TRACKING_COMPASS":
-                return 2;
-            case "TRACKING_GPS":
-                return 1;
-            case "TRACKING_GPS_NORTH":
-                return 3;
+            case 'NONE':
+                return 0 /* MGLUserTrackingMode.None */;
+            case 'NONE_COMPASS':
+                console.log('MapboxView::_stringToCameraMode(): NONE_COMPASS unsupported on iOS');
+                return 0 /* MGLUserTrackingMode.None */;
+            case 'NONE_GPS':
+                console.log('MapboxView::_stringToCameraMode(): NONE_GPS unsupported on iOS');
+                return 0 /* MGLUserTrackingMode.None */;
+            case 'TRACKING':
+                return 1 /* MGLUserTrackingMode.Follow */;
+            case 'TRACKING_COMPASS':
+                return 2 /* MGLUserTrackingMode.FollowWithHeading */;
+            case 'TRACKING_GPS':
+                // a reasonable approximation.
+                return 1 /* MGLUserTrackingMode.Follow */;
+            case 'TRACKING_GPS_NORTH':
+                return 3 /* MGLUserTrackingMode.FollowWithCourse */;
             default:
                 console.log(`_stringToCameraMode: invalid cameraMode: ${mode}`);
         }
-        return 0;
+        return 0 /* MGLUserTrackingMode.None */;
     }
     _stringToRenderMode(mode) {
         let renderMode;
@@ -1143,16 +1257,32 @@ export class Mapbox extends MapboxCommon {
     }
     _convertCameraMode(mode) {
         switch (mode) {
-            case 0:
-                return "NONE";
-            case 1:
-                return "TRACKING";
-            case 2:
-                return "TRACKING_COMPASS";
-            case 3:
-                return "TRACKING_GPS_NORTH";
+            case 0 /* MGLUserTrackingMode.None */:
+                return 'NONE';
+            case 1 /* MGLUserTrackingMode.Follow */:
+                return 'TRACKING';
+            case 2 /* MGLUserTrackingMode.FollowWithHeading */:
+                return 'TRACKING_COMPASS';
+            case 3 /* MGLUserTrackingMode.FollowWithCourse */:
+                return 'TRACKING_GPS_NORTH';
         }
     }
+    /**
+     * show a user location marker
+     *
+     * This method must not be called before location permissions have been granted.
+     *
+     * Supported options under iOS are:
+     *
+     * - renderMode
+     * - cameraMode
+     * - clickListener
+     *
+     * Other options are ignored. Compare with the android version that supports a
+     * different set of options.
+     *
+     * @param {object} options
+     */
     showUserLocationMarker(options, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1161,7 +1291,10 @@ export class Mapbox extends MapboxCommon {
                 theMap.userTrackingMode = this._stringToCameraMode(options.cameraMode);
                 theMap.showsUserHeadingIndicator = true;
                 this.userLocationRenderMode = this._stringToRenderMode(options.renderMode);
+                // the "delegate" needs to know the modes
                 const delegate = theMap.delegate;
+                // tell the delegate to tell the CustomerLocationAnnotationView to change the
+                // appearance of the marker.
                 delegate.changeUserLocationRenderMode(this.userLocationRenderMode);
                 if (typeof options.clickListener != 'undefined') {
                     delegate.setUserLocationClickListener(options.clickListener);
@@ -1176,6 +1309,11 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * hide the user location marker
+     *
+     * @todo unfinished
+     */
     hideUserLocationMarker(nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1189,6 +1327,15 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * Change the mode of the user location marker
+     *
+     * Used to change the camera tracking and render modes of an existing
+     * marker.
+     *
+     * The marker must be configured using showUserLocationMarker before this method
+     * can called.
+     */
     changeUserLocationMarkerMode(renderModeString, cameraModeString, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1209,6 +1356,9 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * ignored on iOS
+     */
     forceUserLocationUpdate(location, nativeMap) { }
     queryRenderedFeatures(options, nativeMap) {
         return new Promise((resolve, reject) => {
@@ -1283,6 +1433,9 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * @deprecated
+     */
     addPolygon(options, nativeMap) {
         return new Promise((resolve, reject) => {
             const theMap = nativeMap || this._mapboxViewInstance;
@@ -1345,6 +1498,7 @@ export class Mapbox extends MapboxCommon {
             const coordinateArray = [];
             points.forEach((point) => coordinateArray.push([point.lng, point.lat]));
             const polylineID = 'polyline_' + (options.id || new Date().getTime());
+            // this would otherwise crash the app
             if (theMap.style.sourceWithIdentifier(polylineID)) {
                 reject("Remove the polyline with this id first with 'removePolylines': " + polylineID);
                 return;
@@ -1370,6 +1524,7 @@ export class Mapbox extends MapboxCommon {
         if (layer !== null) {
             theMap.style.removeLayer(layer);
         }
+        // polygons may have a 'stroke' layer
         layer = theMap.style.layerWithIdentifier(id + '_stroke');
         if (layer !== null) {
             theMap.style.removeLayer(layer);
@@ -1399,6 +1554,7 @@ export class Mapbox extends MapboxCommon {
                 let cam;
                 if (options.bounds) {
                     const padding = options.padding || 0;
+                    // support defined padding
                     const insets = {
                         top: padding,
                         left: padding,
@@ -1446,6 +1602,10 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * sets a map level click listener
+     *
+     */
     setOnMapClickListener(listener, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1459,7 +1619,8 @@ export class Mapbox extends MapboxCommon {
                 for (let i = 0; i < theMap.gestureRecognizers.count; i++) {
                     const recognizer = theMap.gestureRecognizers.objectAtIndex(i);
                     if (recognizer instanceof UITapGestureRecognizer) {
-                        tapGestureRecognizer.requireGestureRecognizerToFail(recognizer);
+                        recognizer.addTargetAction(theMap['mapTapHandler'], 'tap');
+                        break;
                     }
                 }
                 theMap.addGestureRecognizer(tapGestureRecognizer);
@@ -1481,8 +1642,10 @@ export class Mapbox extends MapboxCommon {
                     reject('No map has been loaded');
                     return;
                 }
+                // adding the longPress handler to the map oject so it's not GC'd
                 theMap['mapLongPressHandler'] = MapLongPressHandlerImpl.initWithOwnerAndListenerForMap(new WeakRef(this), listener, theMap);
                 const longPressGestureRecognizer = UILongPressGestureRecognizer.alloc().initWithTargetAction(theMap['mapLongPressHandler'], 'longPress');
+                // cancel the default longPress handler
                 for (let i = 0; i < theMap.gestureRecognizers.count; i++) {
                     const recognizer = theMap.gestureRecognizers.objectAtIndex(i);
                     if (recognizer instanceof UILongPressGestureRecognizer) {
@@ -1508,12 +1671,14 @@ export class Mapbox extends MapboxCommon {
                     reject('No map has been loaded');
                     return;
                 }
+                // adding the pan handler to the map oject so it's not GC'd
                 if (theMap['mapPanHandler'] === undefined) {
-                    theMap['mapPanHandler'] = MapPanHandlerImpl.initWithOwnerAndListenerForMap(new WeakRef(this), listener, 2, theMap);
+                    theMap['mapPanHandler'] = MapPanHandlerImpl.initWithOwnerAndListenerForMap(new WeakRef(this), listener, 2 /* UIGestureRecognizerState.Changed */, theMap);
                 }
                 else {
-                    theMap['mapPanHandler'].addListener(2, listener);
+                    theMap['mapPanHandler'].addListener(2 /* UIGestureRecognizerState.Changed */, listener);
                 }
+                // there's already a pan recognizer, so find it and attach a target action
                 for (let i = 0; i < theMap.gestureRecognizers.count; i++) {
                     const recognizer = theMap.gestureRecognizers.objectAtIndex(i);
                     if (recognizer instanceof UIPanGestureRecognizer) {
@@ -1531,6 +1696,12 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * simulates onMoveBegin single event callback
+     *
+     * This will call the listener provided once per pan akin to the way
+     * onMoveBegin on the Android side works.
+     */
     setOnMoveBeginListener(listener, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1539,12 +1710,14 @@ export class Mapbox extends MapboxCommon {
                     reject('No map has been loaded');
                     return;
                 }
+                // adding the pan handler to the map oject so it's not GC'd
                 if (theMap['mapPanHandler'] === undefined) {
-                    theMap['mapPanHandler'] = MapPanHandlerImpl.initWithOwnerAndListenerForMap(new WeakRef(this), listener, 1, theMap);
+                    theMap['mapPanHandler'] = MapPanHandlerImpl.initWithOwnerAndListenerForMap(new WeakRef(this), listener, 1 /* UIGestureRecognizerState.Began */, theMap);
                 }
                 else {
-                    theMap['mapPanHandler'].addListener(1, listener);
+                    theMap['mapPanHandler'].addListener(1 /* UIGestureRecognizerState.Began */, listener);
                 }
+                // there's already a pan recognizer, so find it and attach a target action
                 for (let i = 0; i < theMap.gestureRecognizers.count; i++) {
                     const recognizer = theMap.gestureRecognizers.objectAtIndex(i);
                     if (recognizer instanceof UIPanGestureRecognizer) {
@@ -1571,11 +1744,12 @@ export class Mapbox extends MapboxCommon {
                     return;
                 }
                 if (theMap['mapPanHandler'] === undefined) {
-                    theMap['mapPanHandler'] = MapPanHandlerImpl.initWithOwnerAndListenerForMap(new WeakRef(this), listener, 3, theMap);
+                    theMap['mapPanHandler'] = MapPanHandlerImpl.initWithOwnerAndListenerForMap(new WeakRef(this), listener, 3 /* UIGestureRecognizerState.Ended */, theMap);
                 }
                 else {
-                    theMap['mapPanHandler'].addListener(3, listener);
+                    theMap['mapPanHandler'].addListener(3 /* UIGestureRecognizerState.Ended */, listener);
                 }
+                // there's already a pan recognizer, so find it and attach a target action
                 for (let i = 0; i < theMap.gestureRecognizers.count; i++) {
                     const recognizer = theMap.gestureRecognizers.objectAtIndex(i);
                     if (recognizer instanceof UIPanGestureRecognizer) {
@@ -1594,6 +1768,7 @@ export class Mapbox extends MapboxCommon {
         });
     }
     setOnFlingListener(listener, nativeMap) {
+        // there's no swipe event we can bind to
         return Promise.reject("'setOnFlingListener' is not supported on iOS");
     }
     async setOnCameraMoveListener(listener, nativeMap) {
@@ -1658,6 +1833,7 @@ export class Mapbox extends MapboxCommon {
                     ne: CLLocationCoordinate2DMake(options.bounds.north, options.bounds.east)
                 };
                 const animated = options.animated === undefined || options.animated;
+                // support defined padding
                 const padding = options.padding !== undefined ? { top: options.padding, left: options.padding, bottom: options.padding, right: options.padding } : { top: 25, left: 25, bottom: 25, right: 25 };
                 theMap.setVisibleCoordinateBoundsEdgePaddingAnimated(bounds, padding, animated);
                 resolve();
@@ -1684,6 +1860,7 @@ export class Mapbox extends MapboxCommon {
                 if (options.accessToken) {
                     MGLAccountManager.accessToken = options.accessToken;
                 }
+                // TODO there's more observers, see https://www.mapbox.com/ios-sdk/examples/offline-pack/
                 if (options.onProgress) {
                     _addObserver(MGLOfflinePackProgressChangedNotification, (notification) => {
                         const offlinePack = notification.object;
@@ -1717,13 +1894,17 @@ export class Mapbox extends MapboxCommon {
                     const maximumCount = notification.userInfo[MGLOfflinePackUserInfoKeyMaximumCount];
                     console.log(`Offline region '${userInfo.objectForKey('name')}' reached the tile limit of ${maximumCount}`);
                 });
+                // Store some data for identification purposes alongside the downloaded resources.
                 const userInfo = { name: options.name };
                 const context = NSKeyedArchiver.archivedDataWithRootObject(userInfo);
+                // Create and register an offline pack with the shared offline storage object.
                 MGLOfflineStorage.sharedOfflineStorage.addPackForRegionWithContextCompletionHandler(region, context, (pack, error) => {
                     if (error) {
+                        // The pack couldn’t be created for some reason.
                         reject(error.localizedFailureReason);
                     }
                     else {
+                        // Start downloading.
                         pack.resume();
                     }
                 });
@@ -1789,12 +1970,15 @@ export class Mapbox extends MapboxCommon {
                         found = true;
                         MGLOfflineStorage.sharedOfflineStorage.removePackWithCompletionHandler(pack, (error) => {
                             if (error) {
+                                // The pack couldn’t be deleted for some reason.
                                 reject(error.localizedFailureReason);
                             }
                             else {
                                 resolve();
+                                // don't return, see note below
                             }
                         });
+                        // don't break the loop as there may be multiple packs with the same name
                     }
                 }
                 if (!found) {
@@ -1827,6 +2011,10 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * update a geojson source
+     *
+     */
     updateSource(id, options, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1861,6 +2049,14 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * add a vector or geojson source
+     *
+     * Add a source that can then be referenced in the style specification
+     * passed to addLayer().
+     *
+     * @link https://docs.mapbox.com/mapbox-gl-js/api/#map#addsource
+     */
     addSource(id, options, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1890,10 +2086,10 @@ export class Mapbox extends MapboxCommon {
                             if (options.scheme) {
                                 switch (options.scheme) {
                                     case 'xyz':
-                                        sourceOptions[MGLTileSourceOptionTileCoordinateSystem] = 0;
+                                        sourceOptions[MGLTileSourceOptionTileCoordinateSystem] = 0 /* MGLTileCoordinateSystem.XYZ */;
                                         break;
                                     case 'tms':
-                                        sourceOptions[MGLTileSourceOptionTileCoordinateSystem] = 1;
+                                        sourceOptions[MGLTileSourceOptionTileCoordinateSystem] = 1 /* MGLTileCoordinateSystem.TMS */;
                                         break;
                                     default:
                                         throw new Error('Unknown raster tile scheme.');
@@ -1937,6 +2133,7 @@ export class Mapbox extends MapboxCommon {
                             if (options.cluster.properties) {
                                 const clusterProperties = {};
                                 for (const property of Object.keys(options.cluster.properties)) {
+                                    // eslint-disable-next-line prefer-const
                                     let [operator, operand] = options.cluster.properties[property];
                                     if (!Array.isArray(operator)) {
                                         operator = [operator];
@@ -1962,10 +2159,10 @@ export class Mapbox extends MapboxCommon {
                         if (options.scheme) {
                             switch (options.scheme || 'xyz') {
                                 case 'xyz':
-                                    sourceOptions[MGLTileSourceOptionTileCoordinateSystem] = 0;
+                                    sourceOptions[MGLTileSourceOptionTileCoordinateSystem] = 0 /* MGLTileCoordinateSystem.XYZ */;
                                     break;
                                 case 'tms':
-                                    sourceOptions[MGLTileSourceOptionTileCoordinateSystem] = 1;
+                                    sourceOptions[MGLTileSourceOptionTileCoordinateSystem] = 1 /* MGLTileCoordinateSystem.TMS */;
                                     break;
                                 default:
                                     throw new Error('Unknown raster tile scheme.');
@@ -2003,6 +2200,9 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * remove source by id
+     */
     removeSource(id, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -2027,6 +2227,24 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * a rough analogue to the mapbox-gl-js addLayer() method
+     *
+     * It would be nice if this {N} API matched the mapbox-gl-js API which
+     * would make it much easier to share mapping applications between the web
+     * and {N} apps.
+     *
+     * This method accepts a Mapbox-GL-JS style specification JSON object with some
+     * limitations:
+     *
+     * - the source: must be a GeoJSON object.
+     * - only a subset of paint properties are available.
+     *
+     * @param {object} style - a style following the Mapbox style specification.
+     * @param {any} nativeMapView - native map view (com.mapbox.mapboxsdk.maps.MapView)
+     *
+     * @link https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers
+     */
     async addLayer(style, belowLayerId, nativeMapView) {
         const theMap = nativeMapView || this._mapboxViewInstance;
         let source = null;
@@ -2047,6 +2265,13 @@ export class Mapbox extends MapboxCommon {
         }
         theMap.style.addLayer(layer.getNativeInstance());
     }
+    /**
+     * remove layer by ID
+     *
+     * Removes a layer given a layer id
+     *
+     * @param {string} id
+     */
     async removeLayer(id, nativeMapViewInstance) {
         const theMap = nativeMapViewInstance || this._mapboxViewInstance;
         if (Trace.isEnabled()) {
@@ -2064,6 +2289,21 @@ export class Mapbox extends MapboxCommon {
             CLog(CLogTypes.info, 'Mapbox:removeLayer(): after removing layer ' + id);
         }
     }
+    /**
+     * @deprecated
+     * Add a point to a line
+     *
+     * This method appends a point to a line and is useful for drawing a users track.
+     *
+     * The process for adding a point to a line is different in the iOS sdk than in
+     * the Android java sdk.
+     *
+     * @param {id} id - id of line to add a point to.
+     * @param {array} lnglat - [lng,lat] to append to the line.
+     *
+     * @link https://github.com/mapbox/mapbox-gl-native/issues/13983
+     * @link https://docs.mapbox.com/ios/maps/examples/runtime-animate-line/
+     */
     async addLinePoint(id, lnglat, sourceId, nativeMapView) {
         const theMap = nativeMapView || this._mapboxViewInstance;
         const sId = !!sourceId ? sourceId : id + '_source';
@@ -2089,6 +2329,72 @@ export class Mapbox extends MapboxCommon {
     }
     addGeoJsonClustered(options, nativeMapViewInstance) {
         throw new Error('Method not implemented.');
+        // return new Promise((resolve, reject) => {
+        //     const theMap: MGLMapView = nativeMapViewInstance || this._mapboxViewInstance;
+        //     try {
+        //         const source = MGLShapeSource.alloc().initWithIdentifierURLOptions(options.name, NSURL.URLWithString(options.data), null);
+        //         theMap.style.addSource(source);
+        //         const layers = [];
+        //         if (options.clusters) {
+        //             for (let i = 0; i < options.clusters.length; i++) {
+        //                 // TODO also allow Color object
+        //                 layers.push([options.clusters[i].points, new Color(options.clusters[i].color).ios]);
+        //             }
+        //         } else {
+        //             layers.push([150, new Color('red').ios]);
+        //             layers.push([20, new Color('green').ios]);
+        //             layers.push([0, new Color('blue').ios]);
+        //         }
+        //         const unclustered = MGLCircleStyleLayer.alloc().initWithIdentifierSource(options.name, source);
+        //         unclustered.circleColor = NSExpression.expressionWithFormatArgumentArray('%@', new Color('red').ios);
+        //         unclustered.circleRadius = NSExpression.expressionWithFormatArgumentArray('16', null);
+        //         unclustered.circleBlur = NSExpression.expressionWithFormatArgumentArray('0.2', null);
+        //         // unclustered.setFilter(com.mapbox.mapboxsdk.style.expressions.Expression.neq(com.mapbox.mapboxsdk.style.expressions.Expression.get('cluster'), true));
+        //         // theMap.style.addLayer(unclustered); // , "building");
+        //         for (let i = 0; i < layers.length; i++) {
+        //             // Add some nice circles
+        //             const circles = MGLCircleStyleLayer.alloc().initWithIdentifierSource(options.name, source);
+        //             const circles = new com.mapbox.mapboxsdk.style.layers.CircleLayer('cluster-' + i, options.name);
+        //         //     circles.setProperties([
+        //         //         // com.mapbox.mapboxsdk.style.layers.PropertyFactory.iconImage("icon")
+        //         //         com.mapbox.mapboxsdk.style.layers.PropertyFactory.circleColor(layers[i][1]),
+        //         //         com.mapbox.mapboxsdk.style.layers.PropertyFactory.circleRadius(new java.lang.Float(22.0)),
+        //         //         com.mapbox.mapboxsdk.style.layers.PropertyFactory.circleBlur(new java.lang.Float(0.2)),
+        //         //     ]);
+        //         //     const pointCount = com.mapbox.mapboxsdk.style.expressions.Expression.toNumber(com.mapbox.mapboxsdk.style.expressions.Expression.get('point_count'));
+        //         //     if (i === 0) {
+        //         //         circles.setFilter(
+        //         //             com.mapbox.mapboxsdk.style.expressions.Expression.gte(pointCount, com.mapbox.mapboxsdk.style.expressions.Expression.literal(java.lang.Integer.valueOf(layers[i][0])))
+        //         //         );
+        //         //     } else {
+        //         //         circles.setFilter(
+        //         //             com.mapbox.mapboxsdk.style.expressions.Expression.all([
+        //         //                 com.mapbox.mapboxsdk.style.expressions.Expression.gte(pointCount, com.mapbox.mapboxsdk.style.expressions.Expression.literal(java.lang.Integer.valueOf(layers[i][0]))),
+        //         //                 com.mapbox.mapboxsdk.style.expressions.Expression.lt(
+        //         //                     pointCount,
+        //         //                     com.mapbox.mapboxsdk.style.expressions.Expression.literal(java.lang.Integer.valueOf(layers[i - 1][0]))
+        //         //                 ),
+        //         //             ])
+        //         //         );
+        //         //     }
+        //         //     this._mapboxMapInstance.getStyle().addLayer(circles); // , "building");
+        //         }
+        //         // // Add the count labels (note that this doesn't show.. #sad)
+        //         // const count = new com.mapbox.mapboxsdk.style.layers.SymbolLayer('count', options.name);
+        //         // count.setProperties([
+        //         //     com.mapbox.mapboxsdk.style.layers.PropertyFactory.textField(com.mapbox.mapboxsdk.style.expressions.Expression.get('point_count')),
+        //         //     com.mapbox.mapboxsdk.style.layers.PropertyFactory.textSize(new java.lang.Float(12.0)),
+        //         //     com.mapbox.mapboxsdk.style.layers.PropertyFactory.textColor(new Color('white').android),
+        //         // ]);
+        //         // this._mapboxMapInstance.getStyle().addLayer(count);
+        //         resolve();
+        //     } catch (ex) {
+        //         if (Trace.isEnabled()) {
+        //             CLog(CLogTypes.info, 'Error in mapbox.addGeoJsonClustered: ' + ex);
+        //         }
+        //         reject(ex);
+        //     }
+        // });
     }
     trackUser(options, nativeMap) {
         return new Promise((resolve, reject) => {
@@ -2173,9 +2479,9 @@ export class Mapbox extends MapboxCommon {
         };
     }
     getUserLocationCameraMode(nativeMap) {
-        let theMap = nativeMap || this._mapboxViewInstance;
+        const theMap = nativeMap || this._mapboxViewInstance;
         if (!theMap) {
-            return "NONE";
+            return 'NONE';
         }
         return this._convertCameraMode(theMap.userTrackingMode);
     }
@@ -2186,6 +2492,7 @@ function _downloadImage(marker) {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, '>> _downloadImage');
         }
+        // to cache..
         if (_markerIconDownloadCache[marker.icon]) {
             marker.iconDownloaded = _markerIconDownloadCache[marker.icon];
             if (Trace.isEnabled()) {
@@ -2194,6 +2501,7 @@ function _downloadImage(marker) {
             resolve(marker);
             return;
         }
+        // ..or not to cache
         Http.getImage(marker.icon).then((output) => {
             marker.iconDownloaded = output.ios;
             _markerIconDownloadCache[marker.icon] = marker.iconDownloaded;