Merge branch 'release-ios-v3.4.0' into 1ec5-release-ios-v3.4.1-master

25 files changed, 172 insertions, 57 deletions

diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs
index 3d775c8a89..254a7cf219 100644
--- a/platform/darwin/docs/guides/For Style Authors.md.ejs
+++ b/platform/darwin/docs/guides/For Style Authors.md.ejs
@@ -42,9 +42,10 @@ underneath.
 The user location annotation view, the attribution button, any buttons in
 callout views, and any items in the navigation bar are influenced by your
 application’s tint color, so choose a tint color that constrasts well with your
-map style. If you intend your style to be used in the dark, consider the impact
-that Night Shift may have on your style’s colors.
+map style.
 <% } -%>
+If you intend your style to be used in the dark, consider the impact that Night
+Shift may have on your style’s colors.
 
 ### Typography and graphics
 
@@ -178,7 +179,7 @@ In style JSON | In the SDK
 `raster`      | `MGLRasterSource`
 `vector`      | `MGLVectorSource`
 
-`image` and `video` sources are not supported.
+`canvas`, `image`, and `video` sources are not supported.
 
 ### Tile sources
 
@@ -282,9 +283,15 @@ Array (`-padding`) | `NSValue.edgeInsetsValue` | `NSValue.edgeInsetsValue`
 <% } -%>
 
 For padding attributes, note that the arguments to
-`<%- cocoaPrefix %>EdgeInsetsMake()` in Objective-C and
-`EdgeInsets(top:left:bottom:right:)` in Swift are specified in counterclockwise
-order, in contrast to the clockwise order defined by the style specification.
+<% if (iOS) { -%>
+`UIEdgeInsetsMake()` in Objective-C and `UIEdgeInsets(top:left:bottom:right:)`
+in Swift
+<% } else { -%>
+`NSEdgeInsetsMake()` in Objective-C and `EdgeInsets(top:left:bottom:right:)` in
+Swift
+<% } -%>
+are specified in counterclockwise order, in contrast to the clockwise order
+defined by the style specification.
 
 <% if (macOS) { -%>
 Additionally, on macOS, a screen coordinate of (0, 0) is located at the
diff --git a/platform/darwin/scripts/update-examples.js b/platform/darwin/scripts/update-examples.js
index 6291326068..e6b747a460 100644
--- a/platform/darwin/scripts/update-examples.js
+++ b/platform/darwin/scripts/update-examples.js
@@ -108,10 +108,10 @@ function completeExamples(os) {
         }
         
         // Resolve conditional compilation blocks.
-        example = example.replace(/^(\s*)#if\s+os\((iOS|macOS)\)\n([^]*?)(?:^\1#else\n([^]*?))?^\1#endif\n/gm,
+        example = example.replace(/^(\s*)#if\s+os\((iOS|macOS)\)\n([^]*?)(?:^\1#else\n([^]*?))?^\1#endif\b\n?/gm,
                                   function (m, indentation, ifOs, ifCase, elseCase) {
           return (os === ifOs ? ifCase : elseCase).replace(new RegExp('^    ', 'gm'), '');
-        });
+        }).replace(/\n$/, '');
         
         // Insert the test method contents into the documentation comment just
         // above the substructure.
diff --git a/platform/darwin/src/MGLMapCamera.h b/platform/darwin/src/MGLMapCamera.h
index 3d492656af..584d370e6b 100644
--- a/platform/darwin/src/MGLMapCamera.h
+++ b/platform/darwin/src/MGLMapCamera.h
@@ -32,7 +32,7 @@ MGL_EXPORT
 + (instancetype)camera;
 
 /**
- Returns a new camera using based on information about the camera’s viewpoint
+ Returns a new camera based on information about the camera’s viewpoint
  and focus point.
  
  @param centerCoordinate The geographic coordinate on which the map should be
diff --git a/platform/darwin/src/MGLShapeCollection.h b/platform/darwin/src/MGLShapeCollection.h
index 5d2ce588c9..79b7e9223a 100644
--- a/platform/darwin/src/MGLShapeCollection.h
+++ b/platform/darwin/src/MGLShapeCollection.h
@@ -29,8 +29,8 @@ NS_ASSUME_NONNULL_BEGIN
  convenient to use an `MGLPointCollection`, `MGLMultiPolyline`, or
  `MGLMultiPolygon` object, respectively.
  
- A multipolyline is known as a
- <a href="https://tools.ietf.org/html/rfc7946#section-3.1.8">GeometryCollection</a>
+ A shape collection is known as a 
+ <a href="https://tools.ietf.org/html/rfc7946#section-3.1.8">GeometryCollection</a> 
  geometry in GeoJSON.
  */
 MGL_EXPORT
diff --git a/platform/darwin/src/MGLShapeSource.h b/platform/darwin/src/MGLShapeSource.h
index 34806c548d..54c5668260 100644
--- a/platform/darwin/src/MGLShapeSource.h
+++ b/platform/darwin/src/MGLShapeSource.h
@@ -21,6 +21,8 @@ typedef NSString *MGLShapeSourceOption NS_STRING_ENUM;
  This attribute corresponds to the
  <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson-cluster"><code>cluster</code></a>
  source property in the Mapbox Style Specification.
+ 
+ This option only affects point features within a shape source.
  */
 extern MGL_EXPORT const MGLShapeSourceOption MGLShapeSourceOptionClustered;
 
@@ -118,7 +120,7 @@ MGL_EXPORT
  the source.
  
  @param identifier A string that uniquely identifies the source.
- @param URL An HTTP(S) URL, absolute file URL, or local file URL relative to the
+ @param url An HTTP(S) URL, absolute file URL, or local file URL relative to the
     current application’s resource bundle.
  @param options An `NSDictionary` of options for this source.
  @return An initialized shape source.
diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index 25096748f6..f11810fb65 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -363,7 +363,7 @@ MGL_EXPORT
 /**
  Currently active style classes, represented as an array of string identifiers.
  */
-@property (nonatomic) NS_ARRAY_OF(NSString *) *styleClasses;
+@property (nonatomic) NS_ARRAY_OF(NSString *) *styleClasses __attribute__((deprecated("This property will be removed in a future release.")));
 
 /**
  Returns a Boolean value indicating whether the style class with the given
@@ -372,14 +372,14 @@ MGL_EXPORT
  @param styleClass The style class to query for.
  @return Whether the style class is currently active.
  */
-- (BOOL)hasStyleClass:(NSString *)styleClass;
+- (BOOL)hasStyleClass:(NSString *)styleClass __attribute__((deprecated("This method will be removed in a future release.")));
 
 /**
  Activates the style class with the given identifier.
 
  @param styleClass The style class to activate.
  */
-- (void)addStyleClass:(NSString *)styleClass;
+- (void)addStyleClass:(NSString *)styleClass __attribute__((deprecated("This method will be removed in a future release.")));
 
 /**
  Deactivates the style class with the given identifier.
@@ -394,7 +394,7 @@ MGL_EXPORT
 
  @param styleClass The style class to deactivate.
  */
-- (void)removeStyleClass:(NSString *)styleClass;
+- (void)removeStyleClass:(NSString *)styleClass __attribute__((deprecated("This method will be removed in a future release.")));
 
 #pragma mark Managing a Style’s Images
 
diff --git a/platform/darwin/src/MGLStyleLayer.h b/platform/darwin/src/MGLStyleLayer.h
index ac40545398..d882ced6e6 100644
--- a/platform/darwin/src/MGLStyleLayer.h
+++ b/platform/darwin/src/MGLStyleLayer.h
@@ -29,9 +29,14 @@ MGL_EXPORT
 /**
  Returns a style layer object initialized with the given identifier.
  
+ The default implementation of this initializer in MGLStyleLayer creates an
+ invalid style layer. Call this initializer on `MGLBackgroundStyleLayer` or one of
+ the concrete subclasses of `MGLForegroundStyleLayer` to create a valid style
+ layer.
+ 
  After initializing and configuring the style layer, add it to a map view’s
  style using the `-[MGLStyle addLayer:]` or
- `-[MGLStyle insertLayer:belowLayer:]` method.
+ `-[MGLStyle insertLayer:belowLayer:]` method. 
  
  @param identifier A string that uniquely identifies the layer in the style to
     which it is added.
diff --git a/platform/darwin/test/MGLDocumentationExampleTests.swift b/platform/darwin/test/MGLDocumentationExampleTests.swift
index d796b4e708..9336db7e49 100644
--- a/platform/darwin/test/MGLDocumentationExampleTests.swift
+++ b/platform/darwin/test/MGLDocumentationExampleTests.swift
@@ -217,4 +217,25 @@ class MGLDocumentationExampleTests: XCTestCase, MGLMapViewDelegate {
 
         XCTAssertNotNil(mapView.style?.layer(withIdentifier: "contour"))
     }
+    
+    func testMGLMapView() {
+        //#-example-code
+        #if os(macOS)
+            class MapClickGestureRecognizer: NSClickGestureRecognizer {
+                override func shouldRequireFailure(of otherGestureRecognizer: NSGestureRecognizer) -> Bool {
+                    return otherGestureRecognizer is NSClickGestureRecognizer
+                }
+            }
+        #else
+            let mapTapGestureRecognizer = UITapGestureRecognizer(target: self, action: #selector(myCustomFunction))
+            for recognizer in mapView.gestureRecognizers! where recognizer is UITapGestureRecognizer {
+                mapTapGestureRecognizer.require(toFail: recognizer)
+            }
+            mapView.addGestureRecognizer(mapTapGestureRecognizer)
+        #endif
+        //#-end-example-code
+    }
+    
+    // For testMGLMapView().
+    func myCustomFunction() {}
 }
diff --git a/platform/ios/CHANGELOG.md b/platform/ios/CHANGELOG.md
index b8a17b169a..81e6cf37c4 100644
--- a/platform/ios/CHANGELOG.md
+++ b/platform/ios/CHANGELOG.md
@@ -28,6 +28,13 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
 * Fixed flickering that occurred when panning past the antimeridian. ([#7574](https://github.com/mapbox/mapbox-gl-native/pull/7574))
 * Fixed an issue that could prevent a cached style from appearing while the device is offline. ([#7770](https://github.com/mapbox/mapbox-gl-native/pull/7770))
 
+## 3.4.1 
+
+* Fixed a build error in the static framework flavor of this SDK caused by a missing header. ([#7844](https://github.com/mapbox/mapbox-gl-native/pull/7844))
+* Fixed an issue causing MGLMapView’s `camera`’s `heading` to be set to a negative value, indicating an undefined heading, when the map view faces northwest. The heading is now wrapped to between zero and 360 degrees, for consistency with MGLMapView’s `direction` property. ([#7724](https://github.com/mapbox/mapbox-gl-native/pull/7724))
+* Fixed an issue where MGLMapView could initially flash black before loading. ([#7859](https://github.com/mapbox/mapbox-gl-native/pull/7859))
+* Deprecated the style class methods in MGLStyle. ([#7785](https://github.com/mapbox/mapbox-gl-native/pull/7785))
+
 ## 3.4.0
 
 ### Packaging
@@ -75,7 +82,7 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
 ### Annotations
 
 * Added new methods to MGLMultiPoint for changing the vertices along a polyline annotation or the exterior of a polygon annotation. ([#6565](https://github.com/mapbox/mapbox-gl-native/pull/6565))
-* Added new APIs to MGLMapView to query for visible annotations. Combined with `-[MGLMapView viewForAnnotation:]`, these APIs can be used to access all visible annotation views. ([6061](https://github.com/mapbox/mapbox-gl-native/pull/6061))
+* Added new APIs to MGLMapView to query for visible annotations. Combined with `-[MGLMapView viewForAnnotation:]`, these APIs can be used to access all visible annotation views. ([#6061](https://github.com/mapbox/mapbox-gl-native/pull/6061))
 * Shape, feature, and annotation classes now conform to NSSecureCoding. ([#6559](https://github.com/mapbox/mapbox-gl-native/pull/6559))
 * Fixed an issue causing offscreen annotation views to be updated even when they were in the reuse queue. ([#5987](https://github.com/mapbox/mapbox-gl-native/pull/5987))
 * Fixed an issue preventing MGLAnnotationView from animating when its coordinate changes. ([#6215](https://github.com/mapbox/mapbox-gl-native/pull/6215))
@@ -278,7 +285,7 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
 - Heading or course tracking mode can now be enabled as soon as an MGLMapView is initialized. ([#3680](https://github.com/mapbox/mapbox-gl-native/pull/3680))
 - Zooming and rotation gestures no longer disable user tracking mode. ([#3589](https://github.com/mapbox/mapbox-gl-native/pull/3589))
 - User tracking mode starts out at a lower zoom level by default. ([#3589](https://github.com/mapbox/mapbox-gl-native/pull/3589))
-- Fixed an issue with small map views not properly fitting annotations within bounds. (#[3407](https://github.com/mapbox/mapbox-gl-native/pull/3407))
+- Fixed an issue with small map views not properly fitting annotations within bounds. ([#3407](https://github.com/mapbox/mapbox-gl-native/pull/3407))
 - When the user rotates the map to within 7° of true north, the map view now snaps to true north. ([#3403](https://github.com/mapbox/mapbox-gl-native/pull/3403))
 - The map view’s background can now be transparent or translucent, as long as the style’s background layer is transparent or translucent and `MGLMapView.opaque` is set to `NO`. ([#3096](https://github.com/mapbox/mapbox-gl-native/pull/3096))
 - Documentation is now generated by [jazzy](https://github.com/realm/jazzy) instead of appledoc. ♪♫ ([#3203](https://github.com/mapbox/mapbox-gl-native/pull/3203))
diff --git a/platform/ios/Mapbox-iOS-SDK-symbols.podspec b/platform/ios/Mapbox-iOS-SDK-symbols.podspec
index 1098c5cd10..69b8e804d8 100644
--- a/platform/ios/Mapbox-iOS-SDK-symbols.podspec
+++ b/platform/ios/Mapbox-iOS-SDK-symbols.podspec
@@ -1,6 +1,6 @@
 Pod::Spec.new do |m|
 
-  version = '3.4.0-beta.7'
+  version = '3.4.1'
 
   m.name    = 'Mapbox-iOS-SDK-symbols'
   m.version = "#{version}-symbols"
diff --git a/platform/ios/Mapbox-iOS-SDK.podspec b/platform/ios/Mapbox-iOS-SDK.podspec
index cf3f3afa61..bfe46a7f2c 100644
--- a/platform/ios/Mapbox-iOS-SDK.podspec
+++ b/platform/ios/Mapbox-iOS-SDK.podspec
@@ -1,6 +1,6 @@
 Pod::Spec.new do |m|
 
-  version = '3.4.0-beta.7'
+  version = '3.4.1'
 
   m.name    = 'Mapbox-iOS-SDK'
   m.version = version
diff --git a/platform/ios/docs/guides/For Style Authors.md b/platform/ios/docs/guides/For Style Authors.md
index 753eb7200c..a65d07bdd1 100644
--- a/platform/ios/docs/guides/For Style Authors.md
+++ b/platform/ios/docs/guides/For Style Authors.md
@@ -29,8 +29,9 @@ underneath.
 The user location annotation view, the attribution button, any buttons in
 callout views, and any items in the navigation bar are influenced by your
 application’s tint color, so choose a tint color that constrasts well with your
-map style. If you intend your style to be used in the dark, consider the impact
-that Night Shift may have on your style’s colors.
+map style.
+If you intend your style to be used in the dark, consider the impact that Night
+Shift may have on your style’s colors.
 
 ### Typography and graphics
 
@@ -127,7 +128,7 @@ In style JSON | In the SDK
 `raster`      | `MGLRasterSource`
 `vector`      | `MGLVectorSource`
 
-`image` and `video` sources are not supported.
+`canvas`, `image`, and `video` sources are not supported.
 
 ### Tile sources
 
@@ -275,9 +276,10 @@ Array (`-offset`, `-translate`) | `NSValue.CGVectorValue` | `NSValue.cgVectorVal
 Array (`-padding`) | `NSValue.UIEdgeInsetsValue` | `NSValue.uiEdgeInsetsValue`
 
 For padding attributes, note that the arguments to
-`UIEdgeInsetsMake()` in Objective-C and
-`EdgeInsets(top:left:bottom:right:)` in Swift are specified in counterclockwise
-order, in contrast to the clockwise order defined by the style specification.
+`UIEdgeInsetsMake()` in Objective-C and `UIEdgeInsets(top:left:bottom:right:)`
+in Swift
+are specified in counterclockwise order, in contrast to the clockwise order
+defined by the style specification.
 
 ## Filtering sources
 
diff --git a/platform/ios/ios.xcodeproj/project.pbxproj b/platform/ios/ios.xcodeproj/project.pbxproj
index 42ae50e942..20110727b9 100644
--- a/platform/ios/ios.xcodeproj/project.pbxproj
+++ b/platform/ios/ios.xcodeproj/project.pbxproj
@@ -232,7 +232,7 @@
 		DA6408DD1DA4E7D300908C90 /* MGLVectorStyleLayer.m in Sources */ = {isa = PBXBuildFile; fileRef = DA6408DA1DA4E7D300908C90 /* MGLVectorStyleLayer.m */; };
 		DA6408DE1DA4E7D300908C90 /* MGLVectorStyleLayer.m in Sources */ = {isa = PBXBuildFile; fileRef = DA6408DA1DA4E7D300908C90 /* MGLVectorStyleLayer.m */; };
 		DA72620B1DEEE3480043BB89 /* MGLOpenGLStyleLayer.h in Headers */ = {isa = PBXBuildFile; fileRef = DA7262091DEEE3480043BB89 /* MGLOpenGLStyleLayer.h */; settings = {ATTRIBUTES = (Public, ); }; };
-		DA72620C1DEEE3480043BB89 /* MGLOpenGLStyleLayer.h in Headers */ = {isa = PBXBuildFile; fileRef = DA7262091DEEE3480043BB89 /* MGLOpenGLStyleLayer.h */; };
+		DA72620C1DEEE3480043BB89 /* MGLOpenGLStyleLayer.h in Headers */ = {isa = PBXBuildFile; fileRef = DA7262091DEEE3480043BB89 /* MGLOpenGLStyleLayer.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		DA72620D1DEEE3480043BB89 /* MGLOpenGLStyleLayer.mm in Sources */ = {isa = PBXBuildFile; fileRef = DA72620A1DEEE3480043BB89 /* MGLOpenGLStyleLayer.mm */; };
 		DA72620E1DEEE3480043BB89 /* MGLOpenGLStyleLayer.mm in Sources */ = {isa = PBXBuildFile; fileRef = DA72620A1DEEE3480043BB89 /* MGLOpenGLStyleLayer.mm */; };
 		DA737EE11D056A4E005BDA16 /* MGLMapViewDelegate.h in Headers */ = {isa = PBXBuildFile; fileRef = DA737EE01D056A4E005BDA16 /* MGLMapViewDelegate.h */; settings = {ATTRIBUTES = (Public, ); }; };
diff --git a/platform/ios/src/MGLMapView.h b/platform/ios/src/MGLMapView.h
index 62f053e96b..1f2031e055 100644
--- a/platform/ios/src/MGLMapView.h
+++ b/platform/ios/src/MGLMapView.h
@@ -28,7 +28,7 @@ extern const CGFloat MGLMapViewDecelerationRateNormal;
 /** A fast deceleration rate for a map view. */
 extern const CGFloat MGLMapViewDecelerationRateFast;
 
-/** Disables decleration in a map view. */
+/** Disables deceleration in a map view. */
 extern const CGFloat MGLMapViewDecelerationRateImmediate;
 
 /**
@@ -73,8 +73,23 @@ typedef NS_ENUM(NSUInteger, MGLAnnotationVerticalAlignment) {
  your Mapbox account. They also deter other developers from using your styles
  without your permission.
  
+ Adding your own gesture recognizer to `MGLMapView` will block the corresponding
+ gesture recognizer built into `MGLMapView`. To avoid conflicts, define which
+ gesture takes precedence. For example, you can create your own
+ `UITapGestureRecognizer` that will be invoked only if the default `MGLMapView`
+ tap gesture fails:
+ 
+ ```swift
+ let mapTapGestureRecognizer = UITapGestureRecognizer(target: self, action: #selector(myCustomFunction))
+ for recognizer in mapView.gestureRecognizers! where recognizer is UITapGestureRecognizer {
+     mapTapGestureRecognizer.require(toFail: recognizer)
+ }
+ mapView.addGestureRecognizer(mapTapGestureRecognizer)
+ ```
+ 
  @note You are responsible for getting permission to use the map data and for
  ensuring that your use adheres to the relevant terms of use.
+
  */
 IB_DESIGNABLE
 @interface MGLMapView : UIView
diff --git a/platform/ios/src/MGLMapView.mm b/platform/ios/src/MGLMapView.mm
index e6ebd4492f..04e9e9bb4b 100644
--- a/platform/ios/src/MGLMapView.mm
+++ b/platform/ios/src/MGLMapView.mm
@@ -395,7 +395,7 @@ public:
     MGLinitializeRunLoop();
 
     _isTargetingInterfaceBuilder = NSProcessInfo.processInfo.mgl_isInterfaceBuilderDesignablesAgent;
-    _opaque = YES;
+    _opaque = NO;
 
     BOOL background = [UIApplication sharedApplication].applicationState == UIApplicationStateBackground;
     if (!background)
@@ -652,6 +652,8 @@ public:
 
 - (void)reachabilityChanged:(NSNotification *)notification
 {
+    MGLAssertIsMainThread();
+
     MGLReachability *reachability = [notification object];
     if ( ! _isWaitingForRedundantReachableNotification && [reachability isReachable])
     {
@@ -718,6 +720,8 @@ public:
 
 - (void)didReceiveMemoryWarning
 {
+    MGLAssertIsMainThread();
+
     _mbglMap->onLowMemory();
 }
 
@@ -2634,7 +2638,7 @@ public:
 {
     CLLocationCoordinate2D centerCoordinate = MGLLocationCoordinate2DFromLatLng(cameraOptions.center ? *cameraOptions.center : _mbglMap->getLatLng());
     double zoomLevel = cameraOptions.zoom ? *cameraOptions.zoom : self.zoomLevel;
-    CLLocationDirection direction = cameraOptions.angle ? -MGLDegreesFromRadians(*cameraOptions.angle) : self.direction;
+    CLLocationDirection direction = cameraOptions.angle ? mbgl::util::wrap(-MGLDegreesFromRadians(*cameraOptions.angle), 0., 360.) : self.direction;
     CGFloat pitch = cameraOptions.pitch ? MGLDegreesFromRadians(*cameraOptions.pitch) : _mbglMap->getPitch();
     CLLocationDistance altitude = MGLAltitudeForZoomLevel(zoomLevel, pitch, centerCoordinate.latitude, self.frame.size);
     return [MGLMapCamera cameraLookingAtCenterCoordinate:centerCoordinate fromDistance:altitude pitch:pitch heading:direction];
diff --git a/platform/ios/uitest/MapViewTests.m b/platform/ios/uitest/MapViewTests.m
index 41ea5446ef..21310b47a6 100644
--- a/platform/ios/uitest/MapViewTests.m
+++ b/platform/ios/uitest/MapViewTests.m
@@ -260,7 +260,7 @@
                                @"disabling pan gesture should disallow horizontal panning");
 }
 
-- (void)testRotate {
+- (void)testRotateClockwise {
     CLLocationDirection startAngle = tester.mapView.direction;
 
     XCTAssertNotEqual(startAngle,
@@ -274,6 +274,21 @@
                                 @"rotating map should change angle");
 }
 
+- (void)testRotateCounterclockwise {
+    CLLocationDirection startAngle = tester.mapView.direction;
+    
+    XCTAssertNotEqual(startAngle,
+                      -45,
+                      @"start angle must not be destination angle");
+    
+    [tester.mapView twoFingerRotateAtPoint:tester.mapView.center angle:-45];
+    
+    XCTAssertGreaterThanOrEqual(fabs(startAngle - tester.mapView.direction),
+                                20,
+                                @"rotating map should change angle");
+    XCTAssertGreaterThan(tester.mapView.camera.heading, 0, @"camera should not go negative");
+}
+
 - (void)testRotateDisabled {
     tester.mapView.rotateEnabled = NO;
     CLLocationDirection startAngle = tester.mapView.direction;
diff --git a/platform/macos/CHANGELOG.md b/platform/macos/CHANGELOG.md
index 24c678c6f0..f4a4607c33 100644
--- a/platform/macos/CHANGELOG.md
+++ b/platform/macos/CHANGELOG.md
@@ -25,7 +25,15 @@
 * Fixed an issue where translucent point annotations along tile boundaries would be drawn darker than expected. ([#6832](https://github.com/mapbox/mapbox-gl-native/pull/6832))
 * Fixed flickering that occurred when panning past the antimeridian. ([#7574](https://github.com/mapbox/mapbox-gl-native/pull/7574))
 * Fixed an issue that could prevent a cached style from appearing while the computer is offline. ([#7770](https://github.com/mapbox/mapbox-gl-native/pull/7770))
+
+## 0.3.1
+
+This version of the Mapbox macOS SDK corresponds to version 3.4.1 of the Mapbox iOS SDK. The two SDKs have very similar feature sets. The main differences are the lack of user location tracking and annotation views. Some APIs have been adapted to macOS conventions, particularly the use of NSPopover for callout views.
+
+* Fixed an issue causing MGLMapView’s `camera`’s `heading` to be set to a negative value, indicating an undefined heading, when the map view faces northwest. The heading is now wrapped to between zero and 360 degrees, for consistency with MGLMapView’s `direction` property. ([#7724](https://github.com/mapbox/mapbox-gl-native/pull/7724))
 * Allows use of the integrated GPU on machines that have more than one GPU. Follow [Apple’s Technical QA1734](https://developer.apple.com/library/content/qa/qa1734/_index.html) to enable this in your app. ([#7834](https://github.com/mapbox/mapbox-gl-native/pull/7834))
+* Fixed an issue causing the mouse cursor to jump after shift- or option-dragging a map view if the window opened on a screen with a different size than the screen with keyboard focus. ([#7846](https://github.com/mapbox/mapbox-gl-native/pull/7846))
+* Deprecated the style class methods in MGLStyle. ([#7785](https://github.com/mapbox/mapbox-gl-native/pull/7785))
 
 ## 0.3.0
 
@@ -64,7 +72,8 @@ This version of the Mapbox macOS SDK corresponds to version 3.4.0 of the Mapbox
 
 * Added `showAnnotations:animated:` and `showAnnotations:edgePadding:animated:`, which moves the map viewport to show the specified annotations. ([#5749](https://github.com/mapbox/mapbox-gl-native/pull/5749))
 * Added new methods to MGLMultiPoint for changing the vertices along a polyline annotation or the exterior of a polygon annotation. ([#6565](https://github.com/mapbox/mapbox-gl-native/pull/6565))
-* Added new APIs to MGLMapView to query for visible annotations. ([6061](https://github.com/mapbox/mapbox-gl-native/pull/6061))
+* Fixed an exception raised when adding a custom annotation model object to MGLMapView. ([#7746](https://github.com/mapbox/mapbox-gl-native/pull/7746))
+* Added new APIs to MGLMapView to query for visible annotations. ([#6061](https://github.com/mapbox/mapbox-gl-native/pull/6061))
 * Shape, feature, and annotation classes now conform to NSSecureCoding. ([#6559](https://github.com/mapbox/mapbox-gl-native/pull/6559))
 * Various method arguments that are represented as C arrays of `CLLocationCoordinate2D` instances have been marked `const` to streamline bridging to Swift. ([#7215](https://github.com/mapbox/mapbox-gl-native/pull/7215))
 * To make an MGLPolyline or MGLPolygon span the antimeridian, specify coordinates with longitudes greater than 180° or less than −180°. ([#6088](https://github.com/mapbox/mapbox-gl-native/pull/6088))
diff --git a/platform/macos/INSTALL.md b/platform/macos/INSTALL.md
index f8b4c675de..ef04267c47 100644
--- a/platform/macos/INSTALL.md
+++ b/platform/macos/INSTALL.md
@@ -1,14 +1,14 @@
-# Integrating the Mapbox macOS SDK into your application
+# Integrating a custom build of the Mapbox macOS SDK into your application
 
-This document explains how to build the Mapbox macOS SDK and integrate it into your own Cocoa application.
+This document explains how to build a development version of the Mapbox macOS SDK from source and integrate it into your own Cocoa application. This process is for advanced developers who want to get a glimpse of the SDK’s development between releases. To use a production-ready version of the SDK, see the [Mapbox macOS SDK homepage](https://mapbox.github.io/mapbox-gl-native/macos/).
 
 ### Requirements
 
 The Mapbox macOS SDK requires the macOS 10.10.0 SDK (or above) and Xcode 7.3 (or above).
 
-### Building the SDK
+### Building the SDK from source
 
-Grab a [prebuilt release](https://github.com/mapbox/mapbox-gl-native/releases/) – look for the releases that begin with “macos-” – or build the SDK from source:
+To build the SDK from source:
 
 1. [Install core dependencies](../../INSTALL.md).
 
diff --git a/platform/macos/Mapbox-macOS-SDK-symbols.podspec b/platform/macos/Mapbox-macOS-SDK-symbols.podspec
index 6de7f829a3..0a0875ccb8 100644
--- a/platform/macos/Mapbox-macOS-SDK-symbols.podspec
+++ b/platform/macos/Mapbox-macOS-SDK-symbols.podspec
@@ -1,6 +1,6 @@
 Pod::Spec.new do |m|
 
-  version = '0.3.0-rc.1'
+  version = '0.3.0'
 
   m.name    = 'Mapbox-macOS-SDK-symbols'
   m.version = "#{version}-symbols"
diff --git a/platform/macos/Mapbox-macOS-SDK.podspec b/platform/macos/Mapbox-macOS-SDK.podspec
index 03ef0eabe7..029ab4b3e2 100644
--- a/platform/macos/Mapbox-macOS-SDK.podspec
+++ b/platform/macos/Mapbox-macOS-SDK.podspec
@@ -1,6 +1,6 @@
 Pod::Spec.new do |m|
 
-  version = '0.3.0-rc.1'
+  version = '0.3.0'
 
   m.name    = 'Mapbox-macOS-SDK'
   m.version = version
diff --git a/platform/macos/README.md b/platform/macos/README.md
index aea5ba0d6a..14b3e0cf16 100644
--- a/platform/macos/README.md
+++ b/platform/macos/README.md
@@ -1,10 +1,10 @@
-# Mapbox macOS SDK
+# [Mapbox macOS SDK](https://mapbox.github.io/mapbox-gl-native/macos/)
 
 [![Bitrise](https://www.bitrise.io/app/155ef7da24b38dcd.svg?token=4KSOw_gd6WxTnvGE2rMttg&branch=master)](https://www.bitrise.io/app/155ef7da24b38dcd)
 
 Put interactive, scalable world maps into your native Cocoa application with the Mapbox macOS SDK.
 
-* Mapbox-curated [map styles](https://www.mapbox.com/maps/) and [vector tiles](https://www.mapbox.com/vector-tiles/) make it easy to get started.
+* Mapbox-curated [map styles](https://www.mapbox.com/maps/) and [OpenStreetMap-based](https://www.mapbox.com/vector-tiles/mapbox-streets-v7/) [vector tiles](https://www.mapbox.com/vector-tiles/) make it easy to get started.
 * Customize every aspect of the map’s appearance in code or visually using [Mapbox Studio](https://www.mapbox.com/mapbox-studio/).
 * High-performance OpenGL rendering and multitouch gestures keep your users happy.
 * A well-designed, fully documented API helps you stay productive.
@@ -14,11 +14,17 @@ Put interactive, scalable world maps into your native Cocoa application with the
 
 The Mapbox macOS SDK is compatible with macOS 10.10.0 and above for Cocoa applications developed in Objective-C, Swift, Interface Builder, or AppleScript. For hybrid applications, consider [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js/).
 
-* [Integrate the Mapbox macOS SDK into your application](INSTALL.md)
+Information for Mac developers:
+
+* [Integrate the Mapbox macOS SDK into your application](https://mapbox.github.io/mapbox-gl-native/macos/)
+* [Learn how to use the Mapbox macOS SDK](https://mapbox.github.io/mapbox-gl-native/macos/)
+* [Browse example styles designed in Mapbox Studio](https://www.mapbox.com/gallery/)
+
+Information for contributors:
+
+* [Build the Mapbox macOS SDK from source](INSTALL.md)
 * [Contribute to the Mapbox macOS SDK](DEVELOPING.md)
-* [Mapbox macOS SDK reference documentation](https://mapbox.github.io/mapbox-gl-native/macos/)
-* [See example styles designed in Mapbox Studio](https://www.mapbox.com/gallery/)
-* [Hand-authoring a macOS SDK–compatible style](https://www.mapbox.com/mapbox-gl-style-spec/)
+* [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/)
 * [Mapbox Vector Tile Specification](https://www.mapbox.com/developers/vector-tiles/)
 
 Mapbox does not officially support the Mapbox macOS SDK to the same extent as the Mapbox iOS SDK; however, bug reports and pull requests are certainly welcome.
diff --git a/platform/macos/docs/guides/For Style Authors.md b/platform/macos/docs/guides/For Style Authors.md
index cf25ae09c4..78a3063b06 100644
--- a/platform/macos/docs/guides/For Style Authors.md
+++ b/platform/macos/docs/guides/For Style Authors.md
@@ -26,6 +26,8 @@ style is present. Standard user interface elements such as toolbars, sidebars,
 and sheets often overlap the map view with a translucent, blurred background, so
 make sure the contents of these elements remain legible with the map view
 underneath.
+If you intend your style to be used in the dark, consider the impact that Night
+Shift may have on your style’s colors.
 
 ### Typography and graphics
 
@@ -115,7 +117,7 @@ In style JSON | In the SDK
 `raster`      | `MGLRasterSource`
 `vector`      | `MGLVectorSource`
 
-`image` and `video` sources are not supported.
+`canvas`, `image`, and `video` sources are not supported.
 
 ### Tile sources
 
@@ -263,9 +265,10 @@ Array (`-offset`, `-translate`) | `NSValue` containing `CGVector` | `NSValue` co
 Array (`-padding`) | `NSValue.edgeInsetsValue` | `NSValue.edgeInsetsValue`
 
 For padding attributes, note that the arguments to
-`NSEdgeInsetsMake()` in Objective-C and
-`EdgeInsets(top:left:bottom:right:)` in Swift are specified in counterclockwise
-order, in contrast to the clockwise order defined by the style specification.
+`NSEdgeInsetsMake()` in Objective-C and `EdgeInsets(top:left:bottom:right:)` in
+Swift
+are specified in counterclockwise order, in contrast to the clockwise order
+defined by the style specification.
 
 Additionally, on macOS, a screen coordinate of (0, 0) is located at the
 lower-left corner of the screen. Therefore, a positive `CGVector.dy` means an
diff --git a/platform/macos/docs/pod-README.md b/platform/macos/docs/pod-README.md
index 6d45a68c34..33386340c6 100644
--- a/platform/macos/docs/pod-README.md
+++ b/platform/macos/docs/pod-README.md
@@ -2,7 +2,7 @@
 
 Put interactive, scalable world maps into your native Cocoa application with the open-source Mapbox macOS SDK.
 
-* Mapbox-curated [map styles](https://www.mapbox.com/maps/) and [vector tiles](https://www.mapbox.com/vector-tiles/) make it easy to get started.
+* Mapbox-curated [map styles](https://www.mapbox.com/maps/) and [OpenStreetMap-based](https://www.mapbox.com/vector-tiles/mapbox-streets-v7/) [vector tiles](https://www.mapbox.com/vector-tiles/) make it easy to get started.
 * Customize every aspect of the map’s appearance in code or visually using [Mapbox Studio](https://www.mapbox.com/mapbox-studio/).
 * High-performance OpenGL rendering and multitouch gestures keep your users happy.
 * A well-designed, fully documented API helps you stay productive.
@@ -12,10 +12,10 @@ Put interactive, scalable world maps into your native Cocoa application with the
 
 The Mapbox macOS SDK is compatible with macOS 10.10.0 and above for Cocoa applications developed in Objective-C, Swift, Interface Builder, or AppleScript. For hybrid applications, consider [Mapbox GL JS](https://www.mapbox.com/mapbox-gl-js/).
 
-Mapbox macOS SDK releases are [available on GitHub](https://github.com/mapbox/mapbox-gl-native/releases/) – look for the releases that begin with “macos-”. You can also integrate the Mapbox macOS SDK into your application using CocoaPods.
-
 ## Installation
 
+1. Download the [latest Mapbox macOS SDK release](https://github.com/mapbox/mapbox-gl-native/releases/) from GitHub – look for a release that begins with “macos-”. (Alternatively, you can integrate the Mapbox macOS SDK into your application [using CocoaPods](https://cocoapods.org/pods/Mapbox-macOS-SDK). If you do use CocoaPods, skip the next step.)
+
 1. Open the project editor, select your application target, then go to the General tab. Drag Mapbox.framework into the “Embedded Binaries” section. (Don’t drag it into the “Linked Frameworks and Libraries” section; Xcode will add it there automatically.) In the sheet that appears, make sure “Copy items if needed” is checked, then click Finish.
 
 1. Mapbox vector tiles require a Mapbox account and API access token. In the project editor, select the application target, then go to the Info tab. Under the “Custom macOS Application Target Properties” section, set `MGLMapboxAccessToken` to your access token. You can obtain an access token from the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/).
diff --git a/platform/macos/src/MGLMapView.h b/platform/macos/src/MGLMapView.h
index efe83d1573..7440ffe793 100644
--- a/platform/macos/src/MGLMapView.h
+++ b/platform/macos/src/MGLMapView.h
@@ -45,6 +45,21 @@ NS_ASSUME_NONNULL_BEGIN
  your Mapbox account. They also deter other developers from using your styles
  without your permission.
  
+ Adding your own gesture recognizer to `MGLMapView` will block the corresponding
+ gesture recognizer built into `MGLMapView`. To avoid conflicts, define which
+ gesture recognizer takes precedence. For example, you can subclass
+ `NSClickGestureRecognizer` and override `-[NSGestureRecognizer shouldRequireFailureOfGestureRecognizer:]`,
+ so that your subclass will be invoked only if the default `MGLMapView` click
+ gesture recognizer fails:
+ 
+ ```swift
+ class MapClickGestureRecognizer: NSClickGestureRecognizer {
+     override func shouldRequireFailure(of otherGestureRecognizer: NSGestureRecognizer) -> Bool {
+         return otherGestureRecognizer is NSClickGestureRecognizer
+     }
+ }
+ ```
+ 
  @note You are responsible for getting permission to use the map data and for
     ensuring that your use adheres to the relevant terms of use.
  */
diff --git a/platform/macos/src/MGLMapView.mm b/platform/macos/src/MGLMapView.mm
index e93e4a40c5..6755c5de62 100644
--- a/platform/macos/src/MGLMapView.mm
+++ b/platform/macos/src/MGLMapView.mm
@@ -231,7 +231,11 @@ public:
 - (void)awakeFromNib {
     [super awakeFromNib];
 
-    self.styleURL = nil;
+    // If the Style URL inspectable was not set, make sure to go through
+    // -setStyleURL: to load the default style.
+    if (_mbglMap->getStyleURL().empty()) {
+        self.styleURL = nil;
+    }
 }
 
 + (NSArray *)restorableStateKeyPaths {
@@ -1250,7 +1254,7 @@ public:
 - (MGLMapCamera *)cameraForCameraOptions:(const mbgl::CameraOptions &)cameraOptions {
     CLLocationCoordinate2D centerCoordinate = MGLLocationCoordinate2DFromLatLng(cameraOptions.center ? *cameraOptions.center : _mbglMap->getLatLng());
     double zoomLevel = cameraOptions.zoom ? *cameraOptions.zoom : self.zoomLevel;
-    CLLocationDirection direction = cameraOptions.angle ? -MGLDegreesFromRadians(*cameraOptions.angle) : self.direction;
+    CLLocationDirection direction = cameraOptions.angle ? mbgl::util::wrap(-MGLDegreesFromRadians(*cameraOptions.angle), 0., 360.) : self.direction;
     CGFloat pitch = cameraOptions.pitch ? MGLDegreesFromRadians(*cameraOptions.pitch) : _mbglMap->getPitch();
     CLLocationDistance altitude = MGLAltitudeForZoomLevel(zoomLevel, pitch,
                                                           centerCoordinate.latitude,
@@ -1340,7 +1344,7 @@ public:
             // the illusion that it has stayed in place during the entire gesture.
             CGPoint cursorPoint = [self convertPoint:startPoint toView:nil];
             cursorPoint = [self.window convertRectToScreen:{ startPoint, NSZeroSize }].origin;
-            cursorPoint.y = [NSScreen mainScreen].frame.size.height - cursorPoint.y;
+            cursorPoint.y = self.window.screen.frame.size.height - cursorPoint.y;
             CGDisplayMoveCursorToPoint(kCGDirectMainDisplay, cursorPoint);
             CGDisplayShowCursor(kCGDirectMainDisplay);
         }
@@ -1825,7 +1829,7 @@ public:
             }
 
             // Opt into potentially expensive tooltip tracking areas.
-            if (annotation.toolTip.length) {
+            if ([annotation respondsToSelector:@selector(toolTip)] && annotation.toolTip.length) {
                 _wantsToolTipRects = YES;
             }
         }
@@ -2360,7 +2364,7 @@ public:
         for (MGLAnnotationTag annotationTag : annotationTags) {
             MGLAnnotationImage *annotationImage = [self imageOfAnnotationWithTag:annotationTag];
             id <MGLAnnotation> annotation = [self annotationWithTag:annotationTag];
-            if (annotation.toolTip.length) {
+            if ([annotation respondsToSelector:@selector(toolTip)] && annotation.toolTip.length) {
                 // Add a tooltip tracking area over the annotation image’s
                 // frame, accounting for the image’s alignment rect.
                 NSImage *image = annotationImage.image;