@nativescript-community/ui-mapbox 6.2.15 → 6.2.20

package/index.ios.js

@@ -1,5 +1,5 @@
 import { Color, File, Http, ImageSource, Trace, Utils, knownFolders, path } from '@nativescript/core';
-import { CLog, CLogTypes, MapStyle, MapboxCommon, MapboxViewBase, telemetryProperty } from './common';
+import { CLog, CLogTypes, MapStyle, MapboxCommon, MapboxTraceCategory, MapboxViewBase, telemetryProperty } from './common';
 import { Layer, LayerFactory } from './layers/layer-factory';
 import { ExpressionParser } from './expression/expression-parser';
 var MGLMapViewDelegateImpl = /** @class */ (function (_super) {
@@ -42,7 +42,7 @@ var MGLMapViewDelegateImpl = /** @class */ (function (_super) {
      * set user location marker modes
      */
     MGLMapViewDelegateImpl.prototype.changeUserLocationRenderMode = function (userLocationRenderMode) {
-        this.userLocationAnnotationView.changeUserLocationRenderMode(userLocationRenderMode);
+        // nothing to do here
     };
     /**
      * set the camera changd listener callback
@@ -234,19 +234,6 @@ var MGLMapViewDelegateImpl = /** @class */ (function (_super) {
             }
         }
     };
-    /**
-     * override the standard location marker
-     */
-    MGLMapViewDelegateImpl.prototype.mapViewViewForAnnotation = function (mapView, annotation) {
-        if (Trace.isEnabled()) {
-            CLog(CLogTypes.info, 'MGLMapViewDelegateImpl::mapViewViewForAnnotation() top');
-        }
-        if (annotation.isKindOfClass(MGLUserLocation.class())) {
-            this.userLocationAnnotationView = CustomUserLocationAnnotationView.alloc().init();
-            return this.userLocationAnnotationView;
-        }
-        return null;
-    };
     MGLMapViewDelegateImpl.prototype.mapViewRegionIsChangingWithReason = function (mapView, reason) {
         if (Trace.isEnabled()) {
             CLog(CLogTypes.info, 'MGLMapViewDelegateImpl::mapViewRegionIsChanging()');
@@ -410,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 = [];
@@ -429,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://')) {
@@ -481,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);
@@ -506,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);
@@ -524,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()) {
@@ -541,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');
@@ -555,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);
@@ -586,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({
@@ -601,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,
@@ -608,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');
@@ -645,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) {
@@ -658,228 +710,38 @@ export class MapboxView extends MapboxViewBase {
         NSUserDefaults.standardUserDefaults.setBoolForKey(false, 'MGLMapboxMetricsEnabled');
     }
 }
-var CustomUserLocationAnnotationView = /** @class */ (function (_super) {
-    __extends(CustomUserLocationAnnotationView, _super);
-    function CustomUserLocationAnnotationView() {
-        return _super !== null && _super.apply(this, arguments) || this;
-    }
-    /**
-     * init
-     *
-     * @link https://docs.nativescript.org/core-concepts/ios-runtime/HelloWorld
-     */
-    CustomUserLocationAnnotationView.prototype.init = function () {
-        this.size = 48;
-        _super.prototype.initWithFrame.call(this, CGRectMake(0, 0, this.size, this.size));
-        this.renderModeChanged = true;
-        this.userLocationRenderMode = 'NORMAL';
-        return this;
-    };
-    /**
-     * update
-     *
-     * The note from the Objective-C sample indicates this method may be called quite
-     * often so it needs to be kept lightweight.
-     */
-    CustomUserLocationAnnotationView.prototype.update = function () {
-        if (CLLocationCoordinate2DIsValid(this.userLocation.coordinate)) {
-            // if it's the first time here, setup the layers that make up the
-            // location marker.
-            if (!this.dot) {
-                this.drawNonTrackingLocationMarker();
-            }
-            if (this.userLocationRenderMode === 'GPS') {
-                this.updateHeading();
-            }
-        }
-    };
-    /**
-     * Draw the GPS tracking arrow.
-     *
-     * @link https://docs.nativescript.org/ns-framework-modules/color
-     */
-    CustomUserLocationAnnotationView.prototype.drawTrackingLocationMarker = function () {
-        if (Trace.isEnabled()) {
-            CLog(CLogTypes.info, 'CustomerUserLocationAnnotatinView::drawTrackingLocationMarker()');
-        }
-        this.drawTrackingDot();
-        this.drawArrow();
-    }; // end of setupLayers()
-    /**
-     * draw the non-tracking marker
-     */
-    CustomUserLocationAnnotationView.prototype.drawNonTrackingLocationMarker = function () {
-        if (Trace.isEnabled()) {
-            CLog(CLogTypes.info, 'CustomerUserLocationAnnotatinView::drawNonTrackingLocationMarker()');
-        }
-        this.drawNonTrackingDot();
-        if (this.arrow) {
-            this.arrow.removeFromSuperlayer();
-            this.arrow = null;
-        }
-    };
-    /**
-     * draw the tracking dot.
-     */
-    CustomUserLocationAnnotationView.prototype.drawTrackingDot = function () {
-        this.size = 48;
-        // we need to adjust the size of the bounds of the marker. The Tracking marker
-        // is larger than the non tracking marker.
-        this.bounds = CGRectMake(0, 0, this.size, this.size);
-        var dot = CALayer.layer();
-        dot.frame = this.bounds;
-        // user corner radius to turn the layer into a circle
-        dot.cornerRadius = this.size / 2;
-        dot.backgroundColor = this.tintColor.CGColor;
-        dot.borderWidth = 4;
-        var whiteColor = new Color('#FFFFFF');
-        dot.borderColor = whiteColor.ios.CGColor;
-        if (!this.dot) {
-            this.layer.addSublayer(dot);
-        }
-        else {
-            this.layer.replaceSublayerWith(this.dot, dot);
-        }
-        // QUESTION: does GC catch this?
-        this.dot = dot;
-    };
-    /**
-     * draw the non-tracking dot.
-     */
-    CustomUserLocationAnnotationView.prototype.drawNonTrackingDot = function () {
-        this.size = 24;
-        this.bounds = CGRectMake(0, 0, this.size, this.size);
-        var dot = CALayer.layer();
-        dot.frame = this.bounds;
-        // user corner radius to turn the layer into a circle
-        dot.cornerRadius = this.size / 2;
-        dot.backgroundColor = this.tintColor.CGColor;
-        dot.borderWidth = 1;
-        var whiteColor = new Color('#FFFFFF');
-        dot.borderColor = whiteColor.ios.CGColor;
-        if (!this.dot) {
-            this.layer.addSublayer(dot);
-        }
-        else {
-            this.layer.replaceSublayerWith(this.dot, dot);
-        }
-        // QUESTION: does GC catch this?
-        this.dot = dot;
-    };
-    /**
-     * draw an arrow
-     */
-    CustomUserLocationAnnotationView.prototype.drawArrow = function () {
-        var arrow = CAShapeLayer.layer();
-        arrow.path = this.arrowPath();
-        arrow.frame = CGRectMake(0, 0, this.size / 2, this.size / 2);
-        arrow.position = CGPointMake(CGRectGetMidX(this.dot.frame), CGRectGetMidY(this.dot.frame));
-        arrow.fillColor = this.dot.borderColor;
-        if (!this.arrow) {
-            this.layer.addSublayer(arrow);
-        }
-        else {
-            this.layer.replaceSublayerWith(this.arrow, arrow);
-        }
-        // QUESTION: Does GC catch this?
-        this.arrow = arrow;
-    };
-    /**
-     * update arrow heading
-     *
-     * @link https://docs.nativescript.org/core-concepts/ios-runtime/types/C-Functions
-     */
-    CustomUserLocationAnnotationView.prototype.updateHeading = function () {
-        // just to avoid a possible race condition where the arrow isnt' drawn yet
-        if (!this.arrow) {
-            return;
-        }
-        if (typeof this.userLocation == 'undefined') {
-            return;
-        }
-        if (typeof this.userLocation.heading == 'undefined' || this.userLocation.heading === null) {
-            return;
-        }
-        if (typeof this.userLocation.heading.trueHeading == 'undefined' || this.userLocation.heading.trueHeading === null) {
-            return;
-        }
-        if (this.userLocation.heading.trueHeading > 0) {
-            this.arrow.hidden = false;
-            // get the difference between the map's current direction and the
-            // user's heading, then convert it from degrees to radians
-            //
-            // The original Objective-C example uses the inline C function MGLRadiansFromDegrees but because
-            // it's declared as inline it is not available for NativeScript. See linked article above.
-            // let rotation : number = MGLRadiansFromDegrees( this.mapView.direction - this.userLocation.heading.trueHeading );
-            var degrees = this.mapView.direction - this.userLocation.heading.trueHeading;
-            // in radians
-            var rotation = (degrees * Math.PI) / 180;
-            rotation = -rotation;
-            // if the difference would be perceptible, rotate the arrow.
-            if (fabs(rotation) > 0.01) {
-                // Disable implicit animations of this rotation, which reduces lag between updates
-                CATransaction.begin();
-                CATransaction.setDisableActions(true);
-                this.arrow.setAffineTransform(CGAffineTransformRotate(CGAffineTransformIdentity, rotation));
-                CATransaction.commit();
-            }
-        }
-        else {
-            this.arrow.hidden = true;
-        }
-    };
-    /**
-     * Calculate the vector path for an arrow
-     */
-    CustomUserLocationAnnotationView.prototype.arrowPath = function () {
-        var max = this.size / 2;
-        var pad = 3;
-        var top = CGPointMake(max * 0.5, 0);
-        var left = CGPointMake(0 + pad, max - pad);
-        var right = CGPointMake(max - pad, max - pad);
-        var center = CGPointMake(max * 0.5, max * 0.6);
-        var bezierPath = UIBezierPath.bezierPath();
-        bezierPath.moveToPoint(top);
-        bezierPath.addLineToPoint(left);
-        bezierPath.addLineToPoint(center);
-        bezierPath.addLineToPoint(right);
-        bezierPath.addLineToPoint(top);
-        bezierPath.closePath();
-        return bezierPath.CGPath;
-    };
-    /**
-     * change Render mode
-     *
-     * @param {string} renderMode
-     */
-    CustomUserLocationAnnotationView.prototype.changeUserLocationRenderMode = function (renderMode) {
-        if (Trace.isEnabled()) {
-            CLog(CLogTypes.info, "CustomUserLocationAnnotatinView::changeUserLocationRenderMode(): changing mode to '" + renderMode + "'");
-        }
-        this.userLocationRenderMode = renderMode;
-        if (renderMode === 'GPS') {
-            this.drawTrackingLocationMarker();
-        }
-        else {
-            this.drawNonTrackingLocationMarker();
-        }
-    };
-    return CustomUserLocationAnnotationView;
-}(MGLUserLocationAnnotationView));
 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] = [];
@@ -895,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);
@@ -936,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) {
@@ -971,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);
@@ -978,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();
                 }
@@ -996,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);
@@ -1054,6 +930,9 @@ export class Mapbox extends MapboxCommon {
             resolve();
         });
     }
+    // ----------------------------------------
+    // Life Cycle Hooks - Required on Android
+    // ----------------------------------------
     onStart(nativeMap) {
         return Promise.resolve();
     }
@@ -1072,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()) {
@@ -1184,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);
                 }
@@ -1328,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;
@@ -1364,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 {
@@ -1382,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);
@@ -1397,6 +1309,11 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * hide the user location marker
+     *
+     * @todo unfinished
+     */
     hideUserLocationMarker(nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1410,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 {
@@ -1430,6 +1356,9 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * ignored on iOS
+     */
     forceUserLocationUpdate(location, nativeMap) { }
     queryRenderedFeatures(options, nativeMap) {
         return new Promise((resolve, reject) => {
@@ -1504,6 +1433,9 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * @deprecated
+     */
     addPolygon(options, nativeMap) {
         return new Promise((resolve, reject) => {
             const theMap = nativeMap || this._mapboxViewInstance;
@@ -1566,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;
@@ -1591,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);
@@ -1620,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,
@@ -1667,6 +1602,10 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * sets a map level click listener
+     *
+     */
     setOnMapClickListener(listener, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -1680,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);
@@ -1702,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) {
@@ -1729,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) {
@@ -1752,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 {
@@ -1760,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) {
@@ -1792,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) {
@@ -1815,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) {
@@ -1879,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();
@@ -1905,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;
@@ -1938,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();
                     }
                 });
@@ -2010,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) {
@@ -2048,6 +2011,10 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * update a geojson source
+     *
+     */
     updateSource(id, options, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -2082,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 {
@@ -2111,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.');
@@ -2158,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];
@@ -2183,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.');
@@ -2224,6 +2200,9 @@ export class Mapbox extends MapboxCommon {
             }
         });
     }
+    /**
+     * remove source by id
+     */
     removeSource(id, nativeMap) {
         return new Promise((resolve, reject) => {
             try {
@@ -2248,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;
@@ -2268,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()) {
@@ -2285,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';
@@ -2310,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) => {
@@ -2343,7 +2428,7 @@ export class Mapbox extends MapboxCommon {
                     return;
                 }
                 const layer = theMap.style.layerWithIdentifier(name);
-                resolve(new Layer(layer));
+                resolve(layer ? new Layer(layer) : null);
             }
             catch (ex) {
                 if (Trace.isEnabled()) {
@@ -2394,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);
     }
@@ -2407,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()) {
@@ -2415,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;