@nativescript-community/ui-mapbox 6.2.15 → 6.2.20

package/common.d.ts

@@ -41,12 +41,28 @@ export interface Feature {
     properties: Object;
 }
 export interface AddPolygonOptions {
+    /**
+     * Set this in case you want to later pass it to 'removePolygons'. TODO doesn't exist yet ;)
+     */
     id?: any;
     points: LatLng[];
     fillColor?: string | Color;
+    /**
+     * Transparency / alpha, ranging from 0 to 1.
+     * Default fully opaque (1).
+     */
     fillOpacity?: number;
+    /**
+     * The line around the polygon. Barely visible on Android.
+     */
     strokeColor?: string | Color;
+    /**
+     * iOS only.
+     */
     strokeWidth?: number;
+    /**
+     * iOS only.
+     */
     strokeOpacity?: number;
 }
 export interface UserLocation {
@@ -57,20 +73,56 @@ export interface SetCenterOptions extends LatLng {
     animated?: boolean;
 }
 export interface AddPolylineOptions {
+    /**
+     * Set this in case you want to later pass it to 'removePolylines'.
+     */
     id?: any;
+    /**
+     * Width of the line, default 5.
+     */
     width?: number;
+    /**
+     * Color of the line, default black.
+     */
     color?: string | Color;
+    /**
+     * Transparency / alpha, ranging from 0 to 1.
+     * Default fully opaque (1).
+     */
     opacity?: number;
     points: LatLng[];
 }
 export interface MapboxMarker extends LatLng {
+    /**
+     * Set this in case you want to later pass it to 'removeMarker'.
+     */
     id?: any;
     title?: string;
     subtitle?: string;
+    /**
+     * Prefix with 'res://' and load a file from the resources folder.
+     * Details on how 'res://' is used can be found here: https://docs.nativescript.org/ui/images#load-images-from-resource
+     * Example: "res://icon.file"
+     */
     icon?: string;
+    /**
+     * The preferred way is using the 'icon' property, but you can still reference a local file directly.
+     * Example: "~/assets/markers/green_pin_marker.png"
+     */
     iconPath?: string;
+    /**
+     * A callback function to invoke when the marker is tapped.
+     */
     onTap?: Function;
+    /**
+     * A callback function to invoke when the callout (popup) of this marker is tapped.
+     */
     onCalloutTap?: Function;
+    /**
+     * Set to true to select the marker when rendered - effectively showing any configured callout.
+     * Note that only 1 callout will be shown at any time on a Mapbox map.
+     * Default false.
+     */
     selected?: boolean;
     update?: (newSettings: MapboxMarker) => void;
     ios?: any;
@@ -81,7 +133,13 @@ export interface SetZoomLevelOptions {
     animated: boolean;
 }
 export interface SetTiltOptions {
+    /**
+     * default 30 (degrees)
+     */
     tilt: number;
+    /**
+     * default 5000 (milliseconds)
+     */
     duration: number;
 }
 export interface ShowOptionsMargins {
@@ -102,11 +160,24 @@ export interface Viewport {
 }
 export interface SetViewportOptions {
     bounds: Bounds;
+    /**
+     * Add an animation of about 1 second.
+     * Default true.
+     */
     animated?: boolean;
+    /**
+     * Optional padding.
+     */
     padding?: number;
 }
 export interface DeleteOfflineRegionOptions {
+    /**
+     * The id of the offline region to delete.
+     */
     id?: string;
+    /**
+     * The name of the offline region to delete.
+     */
     name?: string;
 }
 export interface MapboxCluster {
@@ -114,7 +185,13 @@ export interface MapboxCluster {
     color: string;
 }
 export interface AddGeoJsonClusteredOptions {
+    /**
+     * A unique identifier, like: "earthquakes"
+     */
     name: string;
+    /**
+     * URL, like: "https://www.mapbox.com/mapbox-gl-js/assets/earthquakes.geojson"
+     */
     data: string;
     clusterMaxZoom?: number;
     clusterRadius?: number;
@@ -127,15 +204,27 @@ export interface AddLayerOptions {
     source: string;
     sourceLayer: string;
     type: SupportedLayerType;
+    /**
+     * 'circle' paint properties
+     */
     circleColor?: string | Color;
     circleOpacity?: number;
     circleRadius?: number;
     circleStrokeColor?: string | Color;
     circleStrokeWidth?: number;
+    /**
+     * 'fill' paint properties
+     */
     fillColor?: string | Color;
     fillOpacity?: number;
+    /**
+     * 'line' layout properties
+     */
     lineCap?: string;
     lineJoin?: string;
+    /**
+     * 'line' paint properties
+     */
     lineColor?: string | Color;
     lineOpacity?: number;
     lineWidth?: number;
@@ -182,6 +271,9 @@ export declare type UserLocationCameraMode = 'NONE' | 'NONE_COMPASS' | 'NONE_GPS
 export interface TrackUserOptions {
     cameraMode: UserLocationCameraMode;
     renderMode?: string;
+    /**
+     * iOS only, as Android is always animated. Default true (because of Android).
+     */
     animated?: boolean;
 }
 export interface AddExtrusionOptions {
@@ -202,36 +294,108 @@ export interface DownloadProgress {
     expected: number;
     percentage: number;
     complete: boolean;
+    /**
+     * Android only, the size in bytes of the download so far.
+     */
     completedSize?: number;
 }
 export interface DownloadOfflineRegionOptions extends OfflineRegion {
     onProgress?: (data: DownloadProgress) => void;
+    /**
+     * Optional, used on Android only.
+     * Set this, in case no map has been show yet (and thus, no accessToken has been passed in yet).
+     */
     accessToken?: string;
 }
 export interface ListOfflineRegionsOptions {
+    /**
+     * Optional, used on Android only.
+     * Set this, in case no map has been show yet (and thus, no accessToken has been passed in yet).
+     */
     accessToken?: string;
 }
+/**
+ * The options object passed into the show function.
+ */
 export interface ShowOptions {
     accessToken: string;
+    /**
+     * default 'streets'
+     */
     style?: MapStyle;
     margins?: ShowOptionsMargins;
     center?: LatLng;
+    /**
+     * default 0 (which is almost the entire planet)
+     */
     zoomLevel?: number;
+    /**
+     * default false (true requires adding `NSLocationWhenInUseUsageDescription` or `NSLocationAlwaysUsageDescription` to the .plist)
+     */
     showUserLocation?: boolean;
+    /**
+     * default false (required for the 'starter' plan)
+     */
     hideLogo?: boolean;
+    /**
+     * default true
+     */
     hideAttribution?: boolean;
+    /**
+     * default false
+     */
     hideCompass?: boolean;
+    /**
+     * default false
+     */
     disableRotation?: boolean;
+    /**
+     * default false
+     */
     disableScroll?: boolean;
+    /**
+     * default false
+     */
     disableZoom?: boolean;
+    /**
+     * default false
+     */
     disableTilt?: boolean;
+    /**
+     * Immediately add markers to the map
+     */
     markers?: MapboxMarker[];
+    /**
+     * callback on location permission granted
+     *
+     * Android Only
+     */
     onLocationPermissionGranted?: any;
+    /**
+     * callback on location permission denied
+     *
+     * Android Only
+     */
     onLocationPermissionDenied?: any;
+    /**
+     * callback on Map Ready
+     */
     onMapReady?: any;
+    /**
+     * callback on scroll event
+     */
     onScrollEvent?: any;
+    /**
+     * callback on move begin event
+     */
     onMoveBeginEvent?: any;
+    /**
+     * Android context
+     */
     context?: any;
+    /**
+     * Android parent View
+     */
     parentView?: any;
 }
 export interface ShowResult {
@@ -243,6 +407,9 @@ export interface AnimateCameraOptions {
     bounds?: Bounds;
     padding?: number;
     zoomLevel?: number;
+    /**
+     * For iOS, in meters from the ground
+     */
     altitude?: number;
     bearing?: number;
     tilt?: number;
@@ -368,6 +535,9 @@ export declare abstract class MapboxCommon implements MapboxCommonApi {
     requestFineLocationPermission(): Promise<any>;
     hasFineLocationPermission(): Promise<boolean>;
 }
+/**
+ * Interface definition for a View of a mapbox map.
+ */
 export interface MapboxViewApi {
     addMarkers(markers: MapboxMarker[]): Promise<any>;
     onMapEvent(eventName: any, id: any, callback: any): void;
@@ -431,10 +601,24 @@ export interface MapboxViewApi {
         y: number;
     }): LatLng;
 }
+/**
+ * common base for views created in XML.
+ *
+ * Instead of returning a reference to the Mapbox API instance (class Mapbox) from the view
+ * the author decided to implement shim methods for a subset of the API. I'm not sure what the
+ * reasoning was.
+ *
+ * @see Mapbox
+ */
 export declare abstract class MapboxViewCommonBase extends ContentView implements MapboxViewApi {
     protected mapbox: MapboxApi;
     telemetry: boolean;
     abstract getNativeMapView(): any;
+    /**
+     * map event
+     *
+     * The base NativeScript ContentView class has on() and off() methods.
+     */
     onMapEvent(eventName: any, id: any, callback: any): void;
     offMapEvent(eventName: any, id: any): void;
     addMarkers(markers: MapboxMarker[]): Promise<any>;
@@ -498,6 +682,11 @@ export declare abstract class MapboxViewCommonBase extends ContentView implement
         y: number;
     }): LatLng;
 }
+/**
+ * Properties definitions for the Mapbox XML tag.
+ *
+ * @link https://docs.nativescript.org/plugins/ui-plugin-custom
+ */
 export declare const mapReadyProperty: Property<MapboxViewCommonBase, string>;
 export declare const zoomLevelProperty: Property<MapboxViewCommonBase, number>;
 export declare const accessTokenProperty: Property<MapboxViewCommonBase, string>;
@@ -515,6 +704,16 @@ export declare const disableRotationProperty: Property<MapboxViewCommonBase, boo
 export declare const disableScrollProperty: Property<MapboxViewCommonBase, boolean>;
 export declare const disableTiltProperty: Property<MapboxViewCommonBase, boolean>;
 export declare const delayProperty: Property<MapboxViewCommonBase, number>;
+/**
+ * base class for views created in XML
+ *
+ * This is the glue that creates a config object based on the XML attributes passed to
+ * the Mapbox XML tag.
+ *
+ * @see MapboxView
+ *
+ * @link https://docs.nativescript.org/plugins/ui-plugin-custom
+ */
 export declare abstract class MapboxViewBase extends MapboxViewCommonBase {
     static mapReadyEvent: string;
     static scrollEvent: string;

package/common.js

@@ -1,4 +1,4 @@
-import { ContentView, Property, Trace, booleanConverter } from '@nativescript/core';
+import { Color, ContentView, ImageSource, Property, Trace, booleanConverter } from '@nativescript/core';
 export * from './geo.utils';
 export * from './expression/expression-parser';
 export * from './layers/layer-factory';
@@ -14,6 +14,7 @@ export var CLogTypes;
 export const CLog = (type, ...args) => {
     Trace.write(args.map((a) => (a && typeof a === 'object' ? JSON.stringify(a) : a)).join(' '), MapboxTraceCategory, type);
 };
+// ------------------------------------------------------------
 export var MapStyle;
 (function (MapStyle) {
     MapStyle["DARK"] = "dark";
@@ -25,22 +26,27 @@ export var MapStyle;
     MapStyle["TRAFFIC_DAY"] = "traffic_day";
     MapStyle["TRAFFIC_NIGHT"] = "traffic_night";
 })(MapStyle || (MapStyle = {}));
+// ------------------------------------------------------------
 export class MapboxCommon {
     constructor(view) {
         this.view = view;
     }
     static merge(obj1, obj2) {
-        const result = {};
+        // Our merge function
+        const result = {}; // return result
         for (const i in obj1) {
+            // for every property in obj1
             if (i in obj2 && typeof obj1[i] === 'object' && i !== null) {
-                result[i] = this.merge(obj1[i], obj2[i]);
+                result[i] = this.merge(obj1[i], obj2[i]); // if it's an object, merge
             }
             else {
-                result[i] = obj1[i];
+                result[i] = obj1[i]; // add it to result
             }
         }
         for (const i in obj2) {
+            // add the remaining properties from object 2
             if (i in result) {
+                // conflict
                 continue;
             }
             result[i] = obj2[i];
@@ -73,7 +79,22 @@ MapboxCommon.defaults = {
     disableTilt: false,
     delay: 0
 };
+// ----------------------------------------------------------------------------------------
+/**
+ * common base for views created in XML.
+ *
+ * Instead of returning a reference to the Mapbox API instance (class Mapbox) from the view
+ * the author decided to implement shim methods for a subset of the API. I'm not sure what the
+ * reasoning was.
+ *
+ * @see Mapbox
+ */
 export class MapboxViewCommonBase extends ContentView {
+    /**
+     * map event
+     *
+     * The base NativeScript ContentView class has on() and off() methods.
+     */
     onMapEvent(eventName, id, callback) {
         return this.mapbox.onMapEvent(eventName, id, callback, this.getNativeMapView());
     }
@@ -243,6 +264,12 @@ export class MapboxViewCommonBase extends ContentView {
         return this.mapbox && this.mapbox.projectBack(screenCoordinate);
     }
 }
+// -----------------------------------------------------------------
+/**
+ * Properties definitions for the Mapbox XML tag.
+ *
+ * @link https://docs.nativescript.org/plugins/ui-plugin-custom
+ */
 export const mapReadyProperty = new Property({ name: 'mapReady' });
 mapReadyProperty.register(MapboxViewCommonBase);
 export const zoomLevelProperty = new Property({ name: 'zoomLevel' });
@@ -316,8 +343,21 @@ export const disableTiltProperty = new Property({
 disableTiltProperty.register(MapboxViewCommonBase);
 export const delayProperty = new Property({ name: 'delay', valueConverter: (v) => parseInt(v, 10) });
 delayProperty.register(MapboxViewCommonBase);
+// -------------------------------------------------------------------------------------
+/**
+ * base class for views created in XML
+ *
+ * This is the glue that creates a config object based on the XML attributes passed to
+ * the Mapbox XML tag.
+ *
+ * @see MapboxView
+ *
+ * @link https://docs.nativescript.org/plugins/ui-plugin-custom
+ */
 export class MapboxViewBase extends MapboxViewCommonBase {
     constructor() {
+        // this took forever to find. The component-builder module apparently
+        // looks for static members to find events on controls.
         super(...arguments);
         this.config = {};
     }

package/expression/expression-parser.ios.js

@@ -2,7 +2,7 @@ export class ExpressionParser {
     static parseJson(json) {
         const filterStr = NSString.stringWithString(JSON.stringify(json));
         const filterData = filterStr.dataUsingEncoding(NSUTF8StringEncoding);
-        const filterJson = NSJSONSerialization.JSONObjectWithDataOptionsError(filterData, 1);
+        const filterJson = NSJSONSerialization.JSONObjectWithDataOptionsError(filterData, 1 /* NSJSONReadingOptions.MutableContainers */);
         const predicateFilter = NSPredicate.predicateWithMGLJSONObject(filterJson);
         return predicateFilter;
     }

package/geo.utils.d.ts

@@ -1,3 +1,16 @@
 export declare class GeoUtils {
+    /**
+     * Is the current location within the given circle?
+     *
+     * @param {number} longitude to check
+     * @param {number} latitude to check
+     * @param {number} longitude center of circle
+     * @param {number} latitude center of circle
+     * @param {number} radius of circle in meters
+     *
+     * @return {boolean} true if the point is within the given geofence.
+     *
+     * @link https://stackoverflow.com/questions/24680247/check-if-a-latitude-and-longitude-is-within-a-circle-google-maps
+     */
     static isLocationInCircle(lng: any, lat: any, circleLng: any, circleLat: any, circleRadius: any): boolean;
 }

package/geo.utils.js

@@ -1,4 +1,17 @@
 export class GeoUtils {
+    /**
+     * Is the current location within the given circle?
+     *
+     * @param {number} longitude to check
+     * @param {number} latitude to check
+     * @param {number} longitude center of circle
+     * @param {number} latitude center of circle
+     * @param {number} radius of circle in meters
+     *
+     * @return {boolean} true if the point is within the given geofence.
+     *
+     * @link https://stackoverflow.com/questions/24680247/check-if-a-latitude-and-longitude-is-within-a-circle-google-maps
+     */
     static isLocationInCircle(lng, lat, circleLng, circleLat, circleRadius) {
         const ky = 40000 / 360;
         const kx = Math.cos((Math.PI * circleLat) / 180.0) * ky;
@@ -10,5 +23,5 @@ export class GeoUtils {
         }
         return false;
     }
-}
+} // END
 //# sourceMappingURL=geo.utils.js.map