MAPSIOS-1861 Add ability to force style reload (#7449)

## Summary

Adds `StyleReloadPolicy` to control whether a style should reload when
the URI or JSON matches the currently loaded style. This enables
developers to force style reload events even when the style hasn't
changed,
which is useful for implementations that rely on style load events
triggering consistently.

  ## Changes

  ### New
  - **`StyleReloadPolicy`**: A struct with two options:
- `. onlyIfChanged ` (default): Only reloads if URI/JSON differs from
currently loaded style
- `.always`: Always reload even when URI/JSON matches the currently
loaded style

  ### Modified
- **`MapStyle.init(uri:configuration:reloadPolicy:)`**: Added optional
`reloadPolicy` parameter
- **`MapStyle.init(json:configuration:reloadPolicy:)`**: Added optional
`reloadPolicy` parameter
- **`MapboxMap.loadStyle(_:transition:reloadPolicy:completion:)`**:
Added optional `reloadPolicy` parameter (both URI and JSON variants)

  ### Implementation
- Updated `MapStyleReconciler` to check reload policy when determining
if reload is needed
- Added comprehensive test coverage with 6 new tests covering all
scenarios

Co-authored-by: Claude <[email protected]>
GitOrigin-RevId: ad38bae56d573e3e84cc449e1100c5f09932551d

Author: 2 people

CHANGELOG.md

@@ -18,7 +18,7 @@ mapView.mapboxMap.setStyleImportConfigProperties(for: "basemap", configs: ["ligh
 let options = MapInitOptions(mapStyle: .standardSatellite(lightPreset: .dusk))
 let mapView = MapView(frame: view.bounds, mapInitOptions: options)
 ```
-
+* Add `StyleReloadPolicy` to control style reload behavior. Use `reloadPolicy: .always` parameter in `loadStyle()` methods or `MapStyle` initializers to always reload the style even when the URI or JSON matches the currently loaded style. Defaults to `.onlyIfChanged` for optimal performance.
 
 ## 11.16.0 - 21 October, 2025
 

Sources/MapboxMaps/ContentBuilders/MapContent/MapStyleReconciler.swift

@@ -36,7 +36,10 @@ final class MapStyleReconciler {
     ) {
         let oldMapStyle = _mapStyle
 
-        if _mapStyle?.data != style.data {
+        // Determine if reload is needed based on data change or reload policy
+        let shouldReload = _mapStyle?.data != style.data || style.reloadPolicy == .always
+
+        if shouldReload {
             _mapStyle = style
 
             let callbacks = RuntimeStylingCallbacks(

Sources/MapboxMaps/Documentation.docc/API Catalogs/Style.md

@@ -6,6 +6,7 @@
 
 - ``StyleManager-46yjd``
 - ``StyleURI``
+- ``StyleReloadPolicy``
 - ``LayerPosition-swift.enum``
 - ``AmbientLight``
 - ``DirectionalLight``

Sources/MapboxMaps/Foundation/MapboxMap.swift

@@ -234,12 +234,14 @@ public final class MapboxMap: StyleManager {
     /// - Parameters:
     ///   - styleURI: StyleURI to load
     ///   - transition: Options for the style transition.
+    ///   - reloadPolicy: Controls whether the style should reload if the URI matches the currently loaded style. When `nil`, behaves as `.onlyIfChanged`. Defaults to `nil`.
     ///   - completion: Closure called when the style has been fully loaded.
     ///     If style has failed to load a `MapLoadingError` is provided to the closure.
     public func loadStyle(_ styleURI: StyleURI,
                           transition: TransitionOptions? = nil,
+                          reloadPolicy: StyleReloadPolicy? = nil,
                           completion: ((Error?) -> Void)? = nil) {
-        load(mapStyle: MapStyle(uri: styleURI),
+        load(mapStyle: MapStyle(uri: styleURI, reloadPolicy: reloadPolicy),
              transition: transition,
              completion: completion)
     }
@@ -265,12 +267,14 @@ public final class MapboxMap: StyleManager {
     /// - Parameters:
     ///   - JSON: Style JSON string
     ///   - transition: Options for the style transition.
+    ///   - reloadPolicy: Controls whether the style should reload if the JSON matches the currently loaded style. When `nil`, behaves as `.onlyIfChanged`. Defaults to `nil`.
     ///   - completion: Closure called when the style has been fully loaded.
     ///     If style has failed to load a `MapLoadingError` is provided to the closure.
     public func loadStyle(_ JSON: String,
                           transition: TransitionOptions? = nil,
+                          reloadPolicy: StyleReloadPolicy? = nil,
                           completion: ((Error?) -> Void)? = nil) {
-        load(mapStyle: MapStyle(json: JSON),
+        load(mapStyle: MapStyle(json: JSON, reloadPolicy: reloadPolicy),
              transition: transition,
              completion: completion)
     }

Sources/MapboxMaps/Style/MapStyle.swift

@@ -55,7 +55,8 @@ import MapboxCoreMaps
 /// mapView.mapboxMap.mapStyle = .standard(stylePreset: .dusk)
 /// ```
 ///
-/// The style reloads only when the actual ``StyleURI`` or JSON (when loaded with ``MapStyle/init(json:configuration:)`` is changed. To observe the result of the style load you can subscribe to ``MapboxMap/onStyleLoaded`` or ``Snapshotter/onStyleLoaded`` events, or use use ``StyleManager/load(mapStyle:transition:completion:)`` method.
+/// By default, the style reloads only when the actual ``StyleURI`` or JSON (when loaded with ``MapStyle/init(json:configuration:reloadPolicy:)``) is changed. Use ``StyleReloadPolicy/always`` to always reload even when the URI or JSON hasn't changed.
+/// To observe the result of the style load you can subscribe to ``MapboxMap/onStyleLoaded`` or ``Snapshotter/onStyleLoaded`` events, or use ``StyleManager/load(mapStyle:transition:completion:)`` method.
 public struct MapStyle: Equatable, Sendable {
     enum Data: Equatable, Sendable {
         case uri(StyleURI)
@@ -75,20 +76,23 @@ public struct MapStyle: Equatable, Sendable {
     }
     var data: Data
     var configuration: JSONObject?
+    var reloadPolicy: StyleReloadPolicy?
 
     /// Creates a map style using a Mapbox Style JSON.
     ///
     /// Please consult [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/) describing the JSON format.
     ///
-    /// - Important: For the better performance with large local Style JSON please consider loading style from the file system via the ``MapStyle/init(uri:configuration:)`` initializer.
+    /// - Important: For the better performance with large local Style JSON please consider loading style from the file system via the ``MapStyle/init(uri:configuration:reloadPolicy:)`` initializer.
     ///
     /// - Parameters:
     ///   - json: A Mapbox Style JSON string.
     ///   - configuration: Style import configuration to be applied on style load.
     ///                    Providing `nil` configuration will make no effect and previous configuration will stay in place.  In order to change previous value, you should explicitly override it with the new value.
-    public init(json: String, configuration: JSONObject? = nil) {
+    ///   - reloadPolicy: Controls whether the style should reload if the JSON matches the currently loaded style. When `nil`, behaves as `.onlyIfChanged`. Defaults to `nil`.
+    public init(json: String, configuration: JSONObject? = nil, reloadPolicy: StyleReloadPolicy? = nil) {
         self.data = .json(json)
         self.configuration = configuration
+        self.reloadPolicy = reloadPolicy
     }
 
     /// Creates a map style using a Style URI.
@@ -99,19 +103,21 @@ public struct MapStyle: Equatable, Sendable {
     ///   - uri: An instance of ``StyleURI`` pointing to a Mapbox Style URI (mapbox://styles/{user}/{style}), a full HTTPS URI, or a path to a local file.
     ///   - configuration: Style import configuration to be applied on style load.
     ///                    Providing `nil` configuration will make no effect and previous configuration will stay in place. In order to change previous value, you should explicitly override it with the new value.
-    public init(uri: StyleURI, configuration: JSONObject? = nil) {
+    ///   - reloadPolicy: Controls whether the style should reload if the URI matches the currently loaded style. When `nil`, behaves as `.onlyIfChanged`. Defaults to `nil`.
+    public init(uri: StyleURI, configuration: JSONObject? = nil, reloadPolicy: StyleReloadPolicy? = nil) {
         if let override = Self._overrides[uri] {
             self.data = override.data
             self.configuration = override.configuration
-            
+            self.reloadPolicy = reloadPolicy
             if let configuration, !configuration.isEmpty {
                 self.configuration = (self.configuration ?? [:]).merging(configuration, uniquingKeysWith: {_, new in new })
             }
             return
         }
-        
+
         self.data = .uri(uri)
         self.configuration = configuration
+        self.reloadPolicy = reloadPolicy
     }
 
     /// [Mapbox Streets](https://www.mapbox.com/maps/streets) is a general-purpose style with detailed road and transit networks.

Sources/MapboxMaps/Style/StyleReloadPolicy.swift

@@ -0,0 +1,31 @@
+import Foundation
+
+/// Defines the reload policy for map styles.
+///
+/// Use this policy to control whether a style should reload when the URI or JSON
+/// matches the currently loaded style.
+///
+/// ```swift
+/// // Default behavior: only reload if style URI/JSON changes
+/// mapboxMap.loadStyle(.standard)
+///
+/// // Always reload even if style URI/JSON is the same
+/// mapboxMap.loadStyle(.standard, reloadPolicy: .always) { error in
+///     // Style reloaded, events triggered
+/// }
+/// ```
+public struct StyleReloadPolicy: Equatable, Sendable {
+    let rawValue: String
+
+    /// Reload the style only if the URI or JSON differs from the currently loaded style.
+    ///
+    /// This is the default and provides optimal performance.
+    public static let onlyIfChanged = StyleReloadPolicy(rawValue: "onlyIfChanged")
+
+    /// Always reload the style even if the URI or JSON matches the currently loaded style.
+    ///
+    /// Use this when you need style load events to trigger for the same style.
+    ///
+    /// - Note: Pending style loads will be cancelled when reloading.
+    public static let always = StyleReloadPolicy(rawValue: "always")
+}

Tests/MapboxMapsTests/Foundation/Style/MapStyleReconcilerTests.swift

@@ -298,4 +298,118 @@ final class MapStyleReconcilerTests: XCTestCase {
 
         token.cancel()
     }
+
+    // MARK: - Always Reload Tests
+
+    func testAlwaysReloadWithSameURI() throws {
+        styleManager.setStyleURIStub.defaultSideEffect = { _ in
+            self.styleManager.isStyleLoadedStub.defaultReturnValue = false
+        }
+
+        // Load initial style
+        me.mapStyle = MapStyle(uri: .standard)
+        XCTAssertEqual(styleManager.setStyleURIStub.invocations.count, 1)
+
+        // Load same URI with default policy (should skip)
+        me.mapStyle = MapStyle(uri: .standard)
+        XCTAssertEqual(styleManager.setStyleURIStub.invocations.count, 1, "Should not reload with same URI")
+
+        // Always reload with same URI
+        me.mapStyle = MapStyle(uri: .standard, reloadPolicy: .always)
+        XCTAssertEqual(styleManager.setStyleURIStub.invocations.count, 2, "Should reload with .always policy")
+    }
+
+    func testAlwaysReloadWithSameJSON() throws {
+        let json = "{\"layers\": [], \"sources\": {}}"
+        styleManager.setStyleJSONStub.defaultSideEffect = { _ in
+            self.styleManager.isStyleLoadedStub.defaultReturnValue = false
+        }
+
+        // Load initial style
+        me.mapStyle = MapStyle(json: json)
+        XCTAssertEqual(styleManager.setStyleJSONStub.invocations.count, 1)
+
+        // Load same JSON with default policy (should skip)
+        me.mapStyle = MapStyle(json: json)
+        XCTAssertEqual(styleManager.setStyleJSONStub.invocations.count, 1, "Should not reload with same JSON")
+
+        // Always reload with same JSON
+        me.mapStyle = MapStyle(json: json, reloadPolicy: .always)
+        XCTAssertEqual(styleManager.setStyleJSONStub.invocations.count, 2, "Should reload with .always policy")
+    }
+
+    func testAlwaysReloadCancelsPendingLoads() throws {
+        var callbacks: RuntimeStylingCallbacks?
+        styleManager.setStyleURIStub.defaultSideEffect = { invoc in
+            self.styleManager.isStyleLoadedStub.defaultReturnValue = false
+            // Cancel previous load when new load starts
+            if let callbacks {
+                self.simulateLoad(callbacks: callbacks, result: .cancel)
+            }
+            callbacks = invoc.parameters.callbacks
+        }
+
+        // Start loading a style
+        var firstCallbackReceived = false
+        me.loadStyle(MapStyle(uri: .standard)) { error in
+            XCTAssertTrue(error is CancelError, "First load should be cancelled")
+            firstCallbackReceived = true
+        }
+
+        // Always reload should cancel the first load
+        me.loadStyle(MapStyle(uri: .standard, reloadPolicy: .always)) { error in
+            XCTAssertNil(error)
+        }
+
+        // Simulate the second load completing
+        simulateLoad(callbacks: try XCTUnwrap(callbacks), result: .success)
+
+        XCTAssertTrue(firstCallbackReceived, "First completion should have been called with CancelError")
+    }
+
+    func testOnlyIfChangedPolicyDoesNotReloadSameStyle() {
+        styleManager.setStyleURIStub.defaultSideEffect = { _ in
+            self.styleManager.isStyleLoadedStub.defaultReturnValue = false
+        }
+
+        me.mapStyle = MapStyle(uri: .standard, reloadPolicy: .onlyIfChanged)
+        XCTAssertEqual(styleManager.setStyleURIStub.invocations.count, 1)
+
+        me.mapStyle = MapStyle(uri: .standard, reloadPolicy: .onlyIfChanged)
+        XCTAssertEqual(styleManager.setStyleURIStub.invocations.count, 1, ".onlyIfChanged should not reload same style")
+    }
+
+    func testNilPolicyBehavesLikeOnlyIfChanged() {
+        styleManager.setStyleURIStub.defaultSideEffect = { _ in
+            self.styleManager.isStyleLoadedStub.defaultReturnValue = false
+        }
+
+        me.mapStyle = MapStyle(uri: .standard, reloadPolicy: nil)
+        XCTAssertEqual(styleManager.setStyleURIStub.invocations.count, 1)
+
+        me.mapStyle = MapStyle(uri: .standard, reloadPolicy: nil)
+        XCTAssertEqual(styleManager.setStyleURIStub.invocations.count, 1, "nil policy should behave like .onlyIfChanged")
+    }
+
+    func testAlwaysReloadTriggersStyleLoadedEvent() throws {
+        var callbacks: RuntimeStylingCallbacks?
+        styleManager.setStyleURIStub.defaultSideEffect = { invoc in
+            self.styleManager.isStyleLoadedStub.defaultReturnValue = false
+            callbacks = invoc.parameters.callbacks
+        }
+
+        // Load and complete initial style
+        me.mapStyle = MapStyle(uri: .standard)
+        simulateLoad(callbacks: try XCTUnwrap(callbacks), result: .success)
+
+        // Always reload should trigger another load
+        var reloadCompleted = false
+        me.loadStyle(MapStyle(uri: .standard, reloadPolicy: .always)) { error in
+            XCTAssertNil(error)
+            reloadCompleted = true
+        }
+
+        simulateLoad(callbacks: try XCTUnwrap(callbacks), result: .success)
+        XCTAssertTrue(reloadCompleted, "Always reload completion should be called")
+    }
 }

scripts/api-compatibility-check/breakage_allowlist.txt

@@ -2205,4 +2205,10 @@ Func MapStyle.standard(theme:lightPreset:font:showPointOfInterestLabels:showTran
 Func MapStyle.standard(theme:lightPreset:font:showPointOfInterestLabels:showTransitLabels:showPlaceLabels:showRoadLabels:showPedestrianRoads:show3dObjects:backgroundPointOfInterestLabels:colorAdminBoundaries:colorBuildingHighlight:colorBuildingSelect:colorGreenspace:colorModePointOfInterestLabels:colorMotorways:colorPlaceLabelHighlight:colorPlaceLabels:colorPlaceLabelSelect:colorPointOfInterestLabels:colorRoadLabels:colorRoads:colorTrunks:colorWater:densityPointOfInterestLabels:roadsBrightness:showAdminBoundaries:showLandmarkIconLabels:showLandmarkIcons:themeData:) has parameter 26 type change from Swift.Bool? to Swift.Double?
 Func MapStyle.standard(theme:lightPreset:font:showPointOfInterestLabels:showTransitLabels:showPlaceLabels:showRoadLabels:showPedestrianRoads:show3dObjects:backgroundPointOfInterestLabels:colorAdminBoundaries:colorBuildingHighlight:colorBuildingSelect:colorGreenspace:colorModePointOfInterestLabels:colorMotorways:colorPlaceLabelHighlight:colorPlaceLabels:colorPlaceLabelSelect:colorPointOfInterestLabels:colorRoadLabels:colorRoads:colorTrunks:colorWater:densityPointOfInterestLabels:roadsBrightness:showAdminBoundaries:showLandmarkIconLabels:showLandmarkIcons:themeData:) has parameter 29 type change from Swift.String? to Swift.Bool?
 Func MapStyle.standardSatellite(lightPreset:font:showPointOfInterestLabels:showTransitLabels:showPlaceLabels:showRoadLabels:showRoadsAndTransit:showPedestrianRoads:backgroundPointOfInterestLabels:colorAdminBoundaries:colorModePointOfInterestLabels:colorMotorways:colorPlaceLabelHighlight:colorPlaceLabels:colorPlaceLabelSelect:colorPointOfInterestLabels:colorRoadLabels:colorRoads:colorTrunks:densityPointOfInterestLabels:roadsBrightness:showAdminBoundaries:) has parameter 20 type change from Swift.Double? to MapboxMaps.StandardFuelingStationModePointOfInterestLabels?
-Func MapStyle.standardSatellite(lightPreset:font:showPointOfInterestLabels:showTransitLabels:showPlaceLabels:showRoadLabels:showRoadsAndTransit:showPedestrianRoads:backgroundPointOfInterestLabels:colorAdminBoundaries:colorModePointOfInterestLabels:colorMotorways:colorPlaceLabelHighlight:colorPlaceLabels:colorPlaceLabelSelect:colorPointOfInterestLabels:colorRoadLabels:colorRoads:colorTrunks:densityPointOfInterestLabels:roadsBrightness:showAdminBoundaries:) has parameter 21 type change from Swift.Bool? to Swift.Double?
+Func MapStyle.standardSatellite(lightPreset:font:showPointOfInterestLabels:showTransitLabels:showPlaceLabels:showRoadLabels:showRoadsAndTransit:showPedestrianRoads:backgroundPointOfInterestLabels:colorAdminBoundaries:colorModePointOfInterestLabels:colorMotorways:colorPlaceLabelHighlight:colorPlaceLabels:colorPlaceLabelSelect:colorPointOfInterestLabels:colorRoadLabels:colorRoads:colorTrunks:densityPointOfInterestLabels:roadsBrightness:showAdminBoundaries:) has parameter 21 type change from Swift.Bool? to Swift.Double?
+
+// Add StyleReloadPolicy to control style reload behavior
+Constructor MapStyle.init(json:configuration:) has been removed
+Constructor MapStyle.init(uri:configuration:) has been removed
+Func MapboxMap.loadStyle(_:transition:completion:) has been renamed to Func loadStyle(_:transition:reloadPolicy:completion:)
+Func MapboxMap.loadStyle(_:transition:completion:) has parameter 2 type change from (((any Swift.Error)?) -> ())? to MapboxMaps.StyleReloadPolicy?