RD-1257: Add Center Clamped to Ground and Center Elevation Getters - Swift SDK (#169)

Co-authored-by: Anka <runner@sjc22-bt143-e517dc39-17f0-454c-9c76-5474b0322da4-268796FFA000.local>

Author: github-actions[bot]

Sources/MapTilerSDK/Commands/Navigation/GetCenterClampedToGround.swift

@@ -0,0 +1,14 @@
+//
+// Copyright (c) 2025, MapTiler
+// All rights reserved.
+// SPDX-License-Identifier: BSD 3-Clause
+//
+//  GetCenterClampedToGround.swift
+//  MapTilerSDK
+//
+
+package struct GetCenterClampedToGround: MTCommand {
+    package func toJS() -> JSString {
+        return "\(MTBridge.mapObject).getCenterClampedToGround();"
+    }
+}

Sources/MapTilerSDK/Commands/Navigation/GetCenterElevation.swift

@@ -0,0 +1,14 @@
+//
+// Copyright (c) 2025, MapTiler
+// All rights reserved.
+// SPDX-License-Identifier: BSD 3-Clause
+//
+//  GetCenterElevation.swift
+//  MapTilerSDK
+//
+
+package struct GetCenterElevation: MTCommand {
+    package func toJS() -> JSString {
+        return "\(MTBridge.mapObject).getCenterElevation();"
+    }
+}

Sources/MapTilerSDK/Helpers/MTBridgeReturnType+BoolValue.swift

@@ -0,0 +1,39 @@
+//
+// Copyright (c) 2025, MapTiler
+// All rights reserved.
+// SPDX-License-Identifier: BSD 3-Clause
+//
+//  MTBridgeReturnType+BoolValue.swift
+//  MapTilerSDK
+//
+
+import Foundation
+
+package extension MTBridgeReturnType {
+    var boolValue: Bool? {
+        switch self {
+        case .bool(let value):
+            return value
+        case .double(let value):
+            return value != 0
+        case .string(let value):
+            let normalizedValue = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+
+            if normalizedValue == "true" {
+                return true
+            }
+
+            if normalizedValue == "false" {
+                return false
+            }
+
+            guard let doubleValue = Double(normalizedValue) else {
+                return nil
+            }
+
+            return doubleValue != 0
+        default:
+            return nil
+        }
+    }
+}

Sources/MapTilerSDK/Map/Extensions/MTNavigable/MTMapView+MTNavigable.swift

@@ -342,6 +342,20 @@ extension MTMapView: MTNavigable {
         runCommandWithCoordinateReturnValue(GetCenter(), completion: completionHandler)
     }
 
+    /// Returns whether the map's center is clamped to the ground.
+    /// - Parameter completionHandler: A handler block to execute when function finishes.
+    @available(iOS, deprecated: 16.0, message: "Prefer the async version for modern concurrency handling")
+    public func getCenterClampedToGround(completionHandler: @escaping (Result<Bool, MTError>) -> Void) {
+        runCommandWithBoolReturnValue(GetCenterClampedToGround(), completion: completionHandler)
+    }
+
+    /// Returns the elevation of the map's center point, in meters above sea level.
+    /// - Parameter completionHandler: A handler block to execute when function finishes.
+    @available(iOS, deprecated: 16.0, message: "Prefer the async version for modern concurrency handling")
+    public func getCenterElevation(completionHandler: @escaping (Result<Double, MTError>) -> Void) {
+        runCommandWithDoubleReturnValue(GetCenterElevation(), completion: completionHandler)
+    }
+
     /// Project coordinates to point on the container.
     /// - Parameters:
     ///   - coordinates: The location to project.
@@ -648,6 +662,34 @@ extension MTMapView {
         }
     }
 
+    /// Returns whether the map's center point is clamped to the ground.
+    public func getCenterClampedToGround() async -> Bool {
+        await withCheckedContinuation { continuation in
+            getCenterClampedToGround { result in
+                switch result {
+                case .success(let result):
+                    continuation.resume(returning: result)
+                case .failure:
+                    continuation.resume(returning: false)
+                }
+            }
+        }
+    }
+
+    /// Returns the elevation of the map's center point, in meters above sea level.
+    public func getCenterElevation() async -> Double {
+        await withCheckedContinuation { continuation in
+            getCenterElevation { result in
+                switch result {
+                case .success(let result):
+                    continuation.resume(returning: result)
+                case .failure:
+                    continuation.resume(returning: .nan)
+                }
+            }
+        }
+    }
+
     /// Project coordinates to point on the container.
     /// - Parameters:
     ///   - coordinates: The location to project.

Sources/MapTilerSDK/Map/Extensions/MTNavigable/MTNavigable.swift

@@ -113,6 +113,12 @@ public protocol MTNavigable {
     /// Returns the map's current center.
     func getCenter() async -> CLLocationCoordinate2D
 
+    /// Returns the state of the center clamped to ground flag.
+    func getCenterClampedToGround() async -> Bool
+
+    /// Returns the elevation of the map's center point in meters above sea level.
+    func getCenterElevation() async -> Double
+
     /// Returns the map's current bearing.
     func getBearing() async -> Double
 

Sources/MapTilerSDK/Map/MTMapView.swift

@@ -374,10 +374,8 @@ extension MTMapView {
             do {
                 let value = try await bridge.execute(command)
 
-                if case .bool(let commandValue) = value {
+                if let commandValue = value.boolValue {
                     completion?(.success(commandValue))
-                } else if case .double(let commandValue) = value {
-                    completion?(.success(commandValue != 0))
                 } else {
                     MTLogger.log("\(command) returned invalid type.", type: .error)
                     completion?(.failure(MTError.unsupportedReturnType(description: "Expected bool, got unknown.")))

Tests/MapTilerSDKTests/MTNavigationTests.swift

@@ -74,6 +74,32 @@ struct MTNavigationTests {
         #expect(GetPitch().toJS() == getPitchJS)
     }
 
+    @Test func getCenterClampedToGroundCommand_shouldMatchJS() async throws {
+        let getCenterClampedToGroundJS = "\(MTBridge.mapObject).getCenterClampedToGround();"
+
+        #expect(GetCenterClampedToGround().toJS() == getCenterClampedToGroundJS)
+    }
+
+    @Test func getCenterElevationCommand_shouldMatchJS() async throws {
+        let getCenterElevationJS = "\(MTBridge.mapObject).getCenterElevation();"
+
+        #expect(GetCenterElevation().toJS() == getCenterElevationJS)
+    }
+
+    @Test func boolValueParsingCoversStringAndNumericValues() async throws {
+        let trueString = try MTBridgeReturnType(from: "true")
+        let falseString = try MTBridgeReturnType(from: "false")
+        let oneString = try MTBridgeReturnType(from: "1")
+        let zeroString = try MTBridgeReturnType(from: "0")
+        let unexpectedString = try MTBridgeReturnType(from: "maybe")
+
+        #expect(trueString.boolValue == true)
+        #expect(falseString.boolValue == false)
+        #expect(oneString.boolValue == true)
+        #expect(zeroString.boolValue == false)
+        #expect(unexpectedString.boolValue == nil)
+    }
+
     @Test func jumpToCommand_shouldMatchJS() async throws {
         let cameraOptions = MTCameraOptions(zoom: zoom, bearing: bearing, pitch: pitch)