Expand DSL capabilities of ExpressionArgumentBuilder (#6769)

OdNairy · johnhammerlund · github-actions[bot] · commit a81ebe1fbbf4 · 2025-09-24T08:29:36.000Z
Original PR: - #2355 Resolves MAPSIOS-413 `ExpressionArgumentBuilder` currently only supports the basic `buildBlock(...)` method, but not loop expressions or conditional expressions. There are cases where these can simplify logic, reduce constants, etc. For example, a `SymbolLayer` may have a large matrix of icons: ```swift let iconImageExp = Exp(.match) { "make" "ford" Exp(.match) { "color" "red" "red-ford-icon" "green" "green-ford-icon" } "chevy" Exp(.match) { ... } } ``` We could instead leverage Swift a bit more: ```swift let iconImageExp = Exp(.match) { "make" for make in CarMake.allCases { make.featureValue Exp(.match) { "color" for color in CarColor.allCases { color.featureValue make.iconID(color: color) } } } } ``` The second example is not currently possible. This PR adds support for loops/arrays as well as conditionals. Some feature examples have been updated to leverage this, but happy to revert that if desired. ## Pull request checklist: - [x] Describe the changes in this PR, especially public API changes. - [ ] Include before/after visuals or gifs if this PR includes visual changes.  - [x] Write tests for all new functionality. Put tests in correct [Test Plan](https://github.com/mapbox/mapbox-maps-ios/tree/main/Tests/TestPlans) (Unit, Integration, All) - [ ] If tests were not written, please explain why. - [ ] Add documentation comments for any added or updated public APIs. - [ ] Add any new public, top-level symbols to the DocC custom catatlog (Sources/MapboxMaps/Documentation.docc/API Catalogs) - [ ] Add a changelog entry to to bottom of the relevant section (typically the `## main` heading near the top). - [ ] Update the guides (internal access only), README.md, and DEVELOPING.md if their contents are impacted by these changes. - [ ] If this PR is a `v10.[version]` release branch fix / enhancement, merge it to `main` first and then port to `v10.[version]` release branch. PRs must be submitted under the terms of our Contributor License Agreement [CLA](https://github.com/mapbox/mapbox-maps-ios/blob/main/CONTRIBUTING.md#contributor-license-agreement). cc @mapbox/maps-ios cc @mapbox/sdk-ci --------- Co-authored-by: John Hammerlund <jhammerlund@nextdoor.com> GitOrigin-RevId: 1a2bb8e04b44dadf8e1bd901b8b9e6429865daad
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@ Mapbox welcomes participation and contributions from everyone.
 * Added support for `LandmarkIcons` featureset in Mapbox Standard Style. The `LandmarkIcons` featureset allows querying and configuring landmark building icons that appear on the map. Access landmark properties including landmarkId, name, type, and localized names through the `StandardLandmarkIconsFeature` class.
 * Enhanced `MapStyle.standard()` and `MapStyle.standardSatellite()` with new configuration parameters for color customization, landmark icons visibility, point-of-interest styling, road appearance, and administrative boundaries.
 * Expose `LineLayer.lineCutoutFadeWidth` to control route line cutout fade width.
+* Expanded Expression DSL capabilities with support for control flow constructs in `ExpressionArgumentBuilder`. Now supports `if/else` conditions, `for` loops, optionals, and `#available` checks within expression builders. This allows more natural and readable expression construction, reducing boilerplate code when building complex map styling expressions.
 
 ## 11.15.0 - 11 September, 2025
 
diff --git a/STYLE_README.md b/STYLE_README.md
@@ -118,5 +118,77 @@ Exp(.interpolate) {
 }
 ```
 
+#### Control Flow in Expression DSL
+
+The Expression DSL supports advanced Swift control flow constructs, making it easier to build complex expressions dynamically:
+
+**For loops** - Generate multiple expression arguments from collections:
+```swift
+let zoomLevels: [Double] = [0, 5, 10, 15, 20]
+let colors = [UIColor.red, UIColor.orange, UIColor.yellow, UIColor.green, UIColor.blue]
+
+Exp(.interpolate) {
+    Exp(.linear)
+    Exp(.zoom)
+
+    for (level, color) in zip(zoomLevels, colors) {
+        level
+        color
+    }
+}
+```
+
+**Conditional expressions** - Use if/else to conditionally include arguments:
+```swift
+let isDarkMode = traitCollection.userInterfaceStyle == .dark
+
+Exp(.interpolate) {
+    Exp(.linear)
+    Exp(.zoom)
+
+    if isDarkMode {
+        0
+        UIColor.black
+    } else {
+        0
+        UIColor.white
+    }
+
+    10
+    UIColor.blue
+}
+```
+
+**Optional handling** - Work with optional values seamlessly:
+```swift
+let optionalColor: UIColor? = someCondition ? UIColor.red : nil
+
+Exp(.interpolate) {
+    Exp(.linear)
+    Exp(.zoom)
+
+    if let color = optionalColor {
+        color
+    }
+
+    0
+    UIColor.blue
+}
+```
+
+**Availability checks** - Include platform-specific logic:
+```swift
+Exp(.interpolate) {
+    Exp(.linear)
+    Exp(.zoom)
+
+    if #available(iOS 13.0, *) {
+        UIColor.systemBackground
+    } else {
+        UIColor.white
+    }
+}
+```
+
 #### Other Expression Examples
 - This (example)[Sources/Examples/All%20Examples/DataDrivenSymbolsExample.swift#L74] highlights the use of a match, and a switchcase expression
diff --git a/Sources/Examples/All Examples/DistanceExpressionExample.swift b/Sources/Examples/All Examples/DistanceExpressionExample.swift
@@ -44,43 +44,17 @@ final class DistanceExpressionExample: UIViewController, ExampleProtocol {
         // This expression simulates a `CircleLayer` with a radius of 150 meters. For features that will be
         // visible at lower zoom levels, add more stops at the zoom levels where the feature will be more
         // visible. This keeps the circle's radius more consistent.
+
+        let radii: [Double] = [0, 5, 10, 15, 16, 16.5, 17, 17.5, 18, 18.5, 19, 19.5, 20, 20.5, 21, 21.5, 22]
+
         let circleRadiusExp = Exp(.interpolate) {
             Exp(.linear)
             Exp(.zoom)
-            0
-            circleRadius(forZoom: 0)
-            5
-            circleRadius(forZoom: 5)
-            10
-            circleRadius(forZoom: 10)
-            15
-            circleRadius(forZoom: 15)
-            16
-            circleRadius(forZoom: 16)
-            16.5
-            circleRadius(forZoom: 16.5)
-            17
-            circleRadius(forZoom: 17)
-            17.5
-            circleRadius(forZoom: 17.5)
-            18
-            circleRadius(forZoom: 18)
-            18.5
-            circleRadius(forZoom: 18.5)
-            19
-            circleRadius(forZoom: 19)
-            19.5
-            circleRadius(forZoom: 19.5)
-            20
-            circleRadius(forZoom: 20)
-            20.5
-            circleRadius(forZoom: 20.5)
-            21
-            circleRadius(forZoom: 21)
-            21.5
-            circleRadius(forZoom: 21.5)
-            22
-            circleRadius(forZoom: 22)
+
+            for radius in radii {
+                radius
+                circleRadius(forZoom: radius)
+            }
         }
         circleLayer.circleRadius = .expression(circleRadiusExp)
         circleLayer.circleOpacity = .constant(0.3)
diff --git a/Sources/Examples/All Examples/FeatureStateExample.swift b/Sources/Examples/All Examples/FeatureStateExample.swift
@@ -2,6 +2,12 @@ import UIKit
 import MapboxMaps
 
 final class FeatureStateExample: UIViewController, ExampleProtocol {
+    private struct EarthquakeThreshold {
+        let magnitude: Double
+        let colorHEX: String
+        let radius: Double
+    }
+
     private var mapView: MapView!
     private var descriptionView: EarthquakeDescriptionView!
     private var selectedFeature: FeaturesetFeature?
@@ -16,6 +22,19 @@ final class FeatureStateExample: UIViewController, ExampleProtocol {
         return dateFormatter
     }()
 
+    private let earthquakeThresholds = [
+        EarthquakeThreshold(magnitude: 1, colorHEX: "#fff7ec", radius: 8),
+        EarthquakeThreshold(magnitude: 1.5, colorHEX: "#fee8c8", radius: 10),
+        EarthquakeThreshold(magnitude: 2, colorHEX: "#fdd49e", radius: 12),
+        EarthquakeThreshold(magnitude: 2.5, colorHEX: "#fdbb84", radius: 14),
+        EarthquakeThreshold(magnitude: 3, colorHEX: "#fc8d59", radius: 16),
+        EarthquakeThreshold(magnitude: 3.5, colorHEX: "#ef6548", radius: 18),
+        EarthquakeThreshold(magnitude: 4.5, colorHEX: "#d7301f", radius: 20),
+        EarthquakeThreshold(magnitude: 6.5, colorHEX: "#b30000", radius: 22),
+        EarthquakeThreshold(magnitude: 8.5, colorHEX: "#7f0000", radius: 24),
+        EarthquakeThreshold(magnitude: 10.5, colorHEX: "#000", radius: 26)
+    ]
+
     override func viewDidLoad() {
         super.viewDidLoad()
 
@@ -96,26 +115,11 @@ final class FeatureStateExample: UIViewController, ExampleProtocol {
                 Exp(.interpolate) {
                     Exp(.linear)
                     Exp(.get) { "mag" }
-                    1
-                    8
-                    1.5
-                    10
-                    2
-                    12
-                    2.5
-                    14
-                    3
-                    16
-                    3.5
-                    18
-                    4.5
-                    20
-                    6.5
-                    22
-                    8.5
-                    24
-                    10.5
-                    26
+
+                    for threshold in earthquakeThresholds {
+                        threshold.magnitude
+                        threshold.radius
+                    }
                 }
                 5
             }
@@ -136,26 +140,11 @@ final class FeatureStateExample: UIViewController, ExampleProtocol {
                 Exp(.interpolate) {
                     Exp(.linear)
                     Exp(.get) { "mag" }
-                    1
-                    "#fff7ec"
-                    1.5
-                    "#fee8c8"
-                    2
-                    "#fdd49e"
-                    2.5
-                    "#fdbb84"
-                    3
-                    "#fc8d59"
-                    3.5
-                    "#ef6548"
-                    4.5
-                    "#d7301f"
-                    6.5
-                    "#b30000"
-                    8.5
-                    "#7f0000"
-                    10.5
-                    "#000"
+
+                    for threshold in earthquakeThresholds {
+                        threshold.magnitude
+                        threshold.colorHEX
+                    }
                 }
                 "#000"
             }
diff --git a/Sources/MapboxMaps/Style/Types/ExpressionArgumentBuilder.swift b/Sources/MapboxMaps/Style/Types/ExpressionArgumentBuilder.swift
@@ -10,6 +10,52 @@ public struct ExpressionArgumentBuilder {
     public static func buildBlock(_ arguments: ExpressionArgumentConvertible...) -> [Exp.Argument] {
         return arguments.flatMap { $0.expressionArguments }
     }
+
+    /// Builds an optional expression argument.
+    /// Enables support for optional values in Expression DSL, allowing `if let` and `guard let` constructs.
+    ///
+    /// - Parameter component: An optional expression argument convertible value
+    /// - Returns: Array of expression arguments, empty if component is nil
+    public static func buildOptional(_ component: ExpressionArgumentConvertible?) -> [Exp.Argument] {
+        return component?.expressionArguments ?? []
+    }
+
+    /// Builds expression arguments for the first branch of a conditional.
+    /// Enables support for `if/else` constructs in Expression DSL.
+    ///
+    /// - Parameter argument: Expression argument from the first conditional branch
+    /// - Returns: Array of expression arguments
+    public static func buildEither(first argument: ExpressionArgumentConvertible) -> [Exp.Argument] {
+        return argument.expressionArguments
+    }
+
+    /// Builds expression arguments for the second branch of a conditional.
+    /// Enables support for `if/else` constructs in Expression DSL.
+    ///
+    /// - Parameter argument: Expression argument from the second conditional branch
+    /// - Returns: Array of expression arguments
+    public static func buildEither(second argument: ExpressionArgumentConvertible) -> [Exp.Argument] {
+        return argument.expressionArguments
+    }
+
+    /// Builds expression arguments from an array of convertible values.
+    /// Enables support for `for` loops in Expression DSL, allowing iteration over collections
+    /// to generate multiple expression arguments dynamically.
+    ///
+    /// - Parameter arguments: Array of expression argument convertible values
+    /// - Returns: Flattened array of expression arguments
+    public static func buildArray(_ arguments: [ExpressionArgumentConvertible]) -> [Exp.Argument] {
+        return arguments.flatMap { $0.expressionArguments }
+    }
+
+    /// Builds expression arguments with limited availability checks.
+    /// Enables support for `#available` constructs in Expression DSL.
+    ///
+    /// - Parameter argument: Expression argument from availability-guarded code
+    /// - Returns: Array of expression arguments
+    public static func buildLimitedAvailability(_ argument: ExpressionArgumentConvertible) -> [Exp.Argument] {
+        return argument.expressionArguments
+    }
 }
 
 /// :nodoc:
@@ -67,6 +113,8 @@ extension Array: ExpressionArgumentConvertible {
             return [.stringArray(validStringArray)]
         } else if let validNumberArray = self as? [Double] {
             return [.numberArray(validNumberArray)]
+        } else if let argumentArray = self as? [Exp.Argument] {
+            return argumentArray
         } else {
             Log.warning("Unsupported array provided to Expression. Only [String] and [Double] are supported.", category: "Expressions")
             return []
diff --git a/Tests/MapboxMapsTests/Style/ExpressionTests/ExpressionTests.swift b/Tests/MapboxMapsTests/Style/ExpressionTests/ExpressionTests.swift
@@ -327,6 +327,84 @@ final class ExpressionTests: XCTestCase {
         XCTAssertNotEqual(shortFormExpression, longFormExpression)
     }
 
+    func testExpressionArgumentResultBuilder() throws {
+        let values: [Double] = [1, 2, 3, 4]
+        let eitherFirst: String? = "eitherFirst"
+        let eitherSecond = "eitherSecond"
+        let optional: String? = "optional"
+        let limitedAvailability = "limitedAvailability"
+
+        let writtenOutExpression = Exp(.match) {
+            "foo"
+
+            "eitherFirst"
+            1
+
+            eitherSecond
+            2
+
+            "optional"
+            3
+
+            limitedAvailability
+            4
+
+            "array"
+            Exp(.interpolate) {
+                Exp(.linear)
+                Exp(.zoom)
+                values[0]
+                values[0]
+                values[1]
+                values[1]
+                values[2]
+                values[2]
+                values[3]
+                values[3]
+            }
+        }
+
+        let dslExpression = Exp(.match) {
+            "foo"
+
+            if let eitherFirst {
+                eitherFirst
+            } else {
+                "failure"
+            }
+            1
+
+            if false {
+                "failure"
+            } else {
+                eitherSecond
+            }
+            2
+
+            if let optional {
+                optional
+            }
+            3
+
+            if #available(iOS 13, *) {
+                limitedAvailability
+            }
+            4
+
+            "array"
+            Exp(.interpolate) {
+                Exp(.linear)
+                Exp(.zoom)
+                for value in values {
+                    value
+                    value
+                }
+            }
+        }
+
+        XCTAssertEqual(writtenOutExpression, dslExpression)
+    }
+
     func testEncodeImageOptions() throws {
         let color = StyleColor(UIColor.black)
         let empty = ImageOptions([:])
