Dark Mode style configuration API and Example app toggle (#4509)

## Summary

#### [Commit 1](c0ad249): 

Creates a `Configuration` API for the `FinancialConnectionsSheet`, which
is internal-only (for now). The configuration API allows consumers
specify their preference for styling the sheet, with these options;
- `automatic`: Appearance will reflect the device's theme, and
dynamically switch accordingly.
- `alwaysLight`: Appearance will always use colors appropriate for a
light theme.
- This is the default value for now. The default value is likely to
switch over to `automatic` once we release this API.
- `alwaysDark`: Appearance will always use colors appropriate for a dark
theme.

Usage of this API follows the same approach as the configuration API in
MPE
([docs](https://docs.stripe.com/payments/accept-a-payment?platform=ios&ui=payment-sheet#dark-mode)).
Here's what that looks like:

```swift
var configuration = FinancialConnectionsSheet.Configuration()
configuration.style = .alwaysDark
financialConnectionsSheet.configuration = configuration
```

> [!IMPORTANT]  
>Reminder that the API described here is internal-only until a proper
API review takes places. Anything mentioned here is subject to change
between now and the public release.

#### [Commit
2](c43205f):

Adds a toggle and style picker in the Financial Connections Example app
to test the API mentioned above. Unless the `Use dynamic style` toggle
is enabled, the FC flow should always use a light theme. Otherwise, it
should reflect the value in the style picker

<img width="515" alt="image"
src="https://github.com/user-attachments/assets/fc7a269e-eb12-4350-87e6-b2a857a6e32c"
/>

#### [Commit
3](9bedd68):

Passes along the value set in the MPE
`PaymentSheet.Configuration.UserInterfaceStyle` along to the FC
configuration API, whenever FC is launched from payment sheet. This will
ensure users integrating both MPE and FC won't need to make any
integration changes to get their desired style configuration.

> [!IMPORTANT]  
>Reminder that this will have no functional changes until this API is
released. FC will continue to always present in "light mode" until we
publicize the `Configuration` API, and remove the `ExperimentStore`
guardrails we have in place.

## Motivation


https://docs.google.com/document/d/1bGRPh8J8dvie-JEG4q43DycIBr5zY1GoGF-0RFf0L_Q/edit?usp=sharing

## Testing


https://github.com/user-attachments/assets/960cb29a-161d-4fd5-a2f4-dba9676876ea

## Changelog

N/a

Author: mats-stripe

Example/FinancialConnections Example/FinancialConnections Example/Playground/PlaygroundConfiguration.swift

@@ -6,6 +6,7 @@
 //
 
 import Foundation
+@_spi(STP) import StripeFinancialConnections
 
 /// Provides an interface to customize the playground configuration
 /// (which is stored as a JSON in NSUserDefaults).
@@ -444,12 +445,6 @@ final class PlaygroundConfiguration {
 
     // MARK: - Experimental
 
-    @UserDefault(
-        key: "FINANCIAL_CONNECTIONS_EXAMPLE_USE_ASYNC_API_CLIENT",
-        defaultValue: false
-    )
-    private static var useAsyncAPIClientStorage: Bool
-
     private static let useAsyncAPIClientKey = "use_async_api_client"
     var useAsyncAPIClient: Bool {
         get {
@@ -462,8 +457,59 @@ final class PlaygroundConfiguration {
         set {
             // Save to configuration string
             configurationStore[Self.useAsyncAPIClientKey] = newValue
-            // Save to user defaults
-            Self.useAsyncAPIClientStorage = newValue
+            // Save to experiment store
+            ExperimentStore.shared.useAsyncAPIClient = newValue
+        }
+    }
+
+    private static let useDynamicStyleKey = "use_dynamic_style"
+    var useDynamicStyle: Bool {
+        get {
+            if let useDynamicStyle = configurationStore[Self.useDynamicStyleKey] as? Bool {
+                return useDynamicStyle
+            } else {
+                return false
+            }
+        }
+        set {
+            // Save to configuration string
+            configurationStore[Self.useDynamicStyleKey] = newValue
+            // Save to experiment store
+            ExperimentStore.shared.supportsDynamicStyle = newValue
+        }
+    }
+
+    enum Style: String, CaseIterable, Identifiable, Hashable {
+        case automatic = "automatic"
+        case alwaysLight = "always_light"
+        case alwaysDark = "always_dark"
+
+        var id: String {
+            return rawValue
+        }
+
+        var configurationValue: FinancialConnectionsSheet.Configuration.UserInterfaceStyle {
+            switch self {
+            case .automatic: return .automatic
+            case .alwaysLight: return .alwaysLight
+            case .alwaysDark: return .alwaysDark
+            }
+        }
+    }
+
+    private static let styleKey = "dynamic_style"
+    var style: PlaygroundConfiguration.Style {
+        get {
+            if let styleString = configurationStore[Self.styleKey] as? String,
+               let style = PlaygroundConfiguration.Style(rawValue: styleString) {
+                return style
+            } else {
+                return .alwaysLight
+            }
+        }
+        set {
+            // Save to configuration string
+            configurationStore[Self.styleKey] = newValue.rawValue
         }
     }
 
@@ -579,6 +625,18 @@ final class PlaygroundConfiguration {
         } else {
             self.useAsyncAPIClient = false
         }
+
+        if let useDynamicStyle = dictionary[Self.useDynamicStyleKey] as? Bool {
+            self.useDynamicStyle = useDynamicStyle
+        } else {
+            self.useDynamicStyle = false
+        }
+        if let styleString = dictionary[Self.styleKey] as? String,
+           let style = PlaygroundConfiguration.Style(rawValue: styleString) {
+            self.style = style
+        } else {
+            self.style = .alwaysLight
+        }
     }
 }
 

Example/FinancialConnections Example/FinancialConnections Example/Playground/PlaygroundView.swift

@@ -179,6 +179,17 @@ struct PlaygroundView: View {
 
                     Section(header: Text("Experimental")) {
                         Toggle("Use async API client", isOn: viewModel.useAsyncAPIClient)
+
+                        Toggle("Use dynamic style", isOn: viewModel.useDynamicStyle)
+                        if viewModel.useDynamicStyle.wrappedValue {
+                            Picker("Style", selection: viewModel.style) {
+                                ForEach(PlaygroundConfiguration.Style.allCases) {
+                                    Text($0.rawValue)
+                                        .tag($0)
+                                }
+                            }
+                            .pickerStyle(.segmented)
+                        }
                     }
                 }
 

Example/FinancialConnections Example/FinancialConnections Example/Playground/PlaygroundViewModel.swift

@@ -225,6 +225,30 @@ final class PlaygroundViewModel: ObservableObject {
         )
     }
 
+    var useDynamicStyle: Binding<Bool> {
+        Binding(
+            get: {
+                self.playgroundConfiguration.useDynamicStyle
+            },
+            set: {
+                self.playgroundConfiguration.useDynamicStyle = $0
+                self.objectWillChange.send()
+            }
+        )
+    }
+
+    var style: Binding<PlaygroundConfiguration.Style> {
+        Binding(
+            get: {
+                self.playgroundConfiguration.style
+            },
+            set: {
+                self.playgroundConfiguration.style = $0
+                self.objectWillChange.send()
+            }
+        )
+    }
+
     @Published var showConfigurationView = false
     private(set) lazy var playgroundConfigurationViewModel: PlaygroundManageConfigurationViewModel = {
        return PlaygroundManageConfigurationViewModel(
@@ -323,6 +347,7 @@ final class PlaygroundViewModel: ObservableObject {
                     stripeAccount: self.playgroundConfiguration.merchant.stripeAccount,
                     setupPlaygroundResponseJSON: setupPlaygroundResponse,
                     useAsyncApiClient: self.playgroundConfiguration.useAsyncAPIClient,
+                    style: self.playgroundConfiguration.style,
                     onEvent: { event in
                         if self.liveEvents.wrappedValue == true {
                             let message = "\(event.name.rawValue); \(event.metadata.dictionary)"
@@ -472,6 +497,7 @@ private func PresentFinancialConnectionsSheet(
     stripeAccount: String?,
     setupPlaygroundResponseJSON: [String: String],
     useAsyncApiClient: Bool,
+    style: PlaygroundConfiguration.Style,
     onEvent: @escaping (FinancialConnectionsEvent) -> Void,
     completionHandler: @escaping (FinancialConnectionsSheet.Result) -> Void
 ) {
@@ -518,6 +544,9 @@ private func PresentFinancialConnectionsSheet(
     )
     financialConnectionsSheet.apiClient.stripeAccount = stripeAccount
     financialConnectionsSheet.onEvent = onEvent
+    var configuration = FinancialConnectionsSheet.Configuration()
+    configuration.style = style.configurationValue
+    financialConnectionsSheet.configuration = configuration
     let topMostViewController = UIViewController.topMostViewController()!
     if useCase == .token {
         financialConnectionsSheet.presentForToken(
@@ -619,6 +648,12 @@ private func PresentPaymentSheet(
     configuration.defaultBillingDetails.email = config.email
     configuration.defaultBillingDetails.phone = config.phone
 
+    switch config.style {
+    case .automatic: configuration.style = .automatic
+    case .alwaysLight: configuration.style = .alwaysLight
+    case .alwaysDark: configuration.style = .alwaysDark
+    }
+
     let isUITest = (ProcessInfo.processInfo.environment["UITesting"] != nil)
     // disable app-to-app for UI tests
     configuration.returnURL = isUITest ? nil : "financial-connections-example://redirect"

StripeCore/StripeCore/Source/Connections Bindings/ElementsSessionContext.swift

@@ -44,13 +44,22 @@ import Foundation
         }
     }
 
+    /// Intermediary object between `PaymentSheet.Configuration.UserInterfaceStyle`
+    /// and `FinancialConnectionsSheet.Configuration.UserInterfaceStyle`.
+    @_spi(STP) @frozen public enum StyleConfig {
+        case automatic
+        case alwaysLight
+        case alwaysDark
+    }
+
     @_spi(STP) public let amount: Int?
     @_spi(STP) public let currency: String?
     @_spi(STP) public let prefillDetails: PrefillDetails?
     @_spi(STP) public let intentId: IntentID?
     @_spi(STP) public let linkMode: LinkMode?
     @_spi(STP) public let billingDetails: BillingDetails?
     @_spi(STP) public let eligibleForIncentive: Bool
+    @_spi(STP) public let styleConfig: StyleConfig?
 
     @_spi(STP) public var billingAddress: BillingAddress? {
         BillingAddress(from: billingDetails)
@@ -70,7 +79,8 @@ import Foundation
         intentId: IntentID? = nil,
         linkMode: LinkMode? = nil,
         billingDetails: BillingDetails? = nil,
-        eligibleForIncentive: Bool = false
+        eligibleForIncentive: Bool = false,
+        styleConfig: StyleConfig? = nil
     ) {
         self.amount = amount
         self.currency = currency
@@ -79,6 +89,7 @@ import Foundation
         self.linkMode = linkMode
         self.billingDetails = billingDetails
         self.eligibleForIncentive = eligibleForIncentive
+        self.styleConfig = styleConfig
     }
 }
 

StripeFinancialConnections/StripeFinancialConnections.xcodeproj/project.pbxproj

@@ -76,6 +76,7 @@
 		49F047552C63C2E5006BAD3E /* FinancialConnectionsPaymentDetails.swift in Sources */ = {isa = PBXBuildFile; fileRef = 49F047542C63C2E5006BAD3E /* FinancialConnectionsPaymentDetails.swift */; };
 		49F1B83A2D2DAE7100136303 /* FinancialConnectionsAsyncAPIClient.swift in Sources */ = {isa = PBXBuildFile; fileRef = 49F1B8392D2DAE7100136303 /* FinancialConnectionsAsyncAPIClient.swift */; };
 		49F1B83E2D2EC82300136303 /* FinancialConnectionsAsyncAPIClient+Legacy.swift in Sources */ = {isa = PBXBuildFile; fileRef = 49F1B83D2D2EC82300136303 /* FinancialConnectionsAsyncAPIClient+Legacy.swift */; };
+		49F883F82D496D7A00A104B0 /* ExperimentStore.swift in Sources */ = {isa = PBXBuildFile; fileRef = 49F883F72D496D7A00A104B0 /* ExperimentStore.swift */; };
 		4A0D015C978BD79BBFE6CE57 /* ManualEntryDataSource.swift in Sources */ = {isa = PBXBuildFile; fileRef = BD4C39F5F9AF440B13F51A81 /* ManualEntryDataSource.swift */; };
 		4A537AE0C50CAFF3889EFE28 /* UIViewController+Extensions.swift in Sources */ = {isa = PBXBuildFile; fileRef = BF7E41313B709F87B549D85F /* UIViewController+Extensions.swift */; };
 		4DC8EB63806434ABF4C9CC43 /* [email protected] in Resources */ = {isa = PBXBuildFile; fileRef = 782A419DCF59BE6AB6439D04 /* [email protected] */; };
@@ -342,6 +343,7 @@
 		49F047542C63C2E5006BAD3E /* FinancialConnectionsPaymentDetails.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FinancialConnectionsPaymentDetails.swift; sourceTree = "<group>"; };
 		49F1B8392D2DAE7100136303 /* FinancialConnectionsAsyncAPIClient.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FinancialConnectionsAsyncAPIClient.swift; sourceTree = "<group>"; };
 		49F1B83D2D2EC82300136303 /* FinancialConnectionsAsyncAPIClient+Legacy.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "FinancialConnectionsAsyncAPIClient+Legacy.swift"; sourceTree = "<group>"; };
+		49F883F72D496D7A00A104B0 /* ExperimentStore.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ExperimentStore.swift; sourceTree = "<group>"; };
 		4A7B146AA6BF44921A249DB8 /* EmptyFinancialConnectionsAPIClient.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = EmptyFinancialConnectionsAPIClient.swift; sourceTree = "<group>"; };
 		4AFBF95DAE0783010A17EB58 /* FinancialConnectionsSession_only_accounts.json */ = {isa = PBXFileReference; lastKnownFileType = text.json; path = FinancialConnectionsSession_only_accounts.json; sourceTree = "<group>"; };
 		4BFCD9C339634B71FC8F85E9 /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist; path = Info.plist; sourceTree = "<group>"; };
@@ -1041,6 +1043,7 @@
 				6A6F989B2C4F1BF00035C03D /* CreatePaneParameters.swift */,
 				49F047522C63B430006BAD3E /* StripeSchemeAddress.swift */,
 				49424EAF2D48050A0088F3D9 /* WebPrefillDetails.swift */,
+				49F883F72D496D7A00A104B0 /* ExperimentStore.swift */,
 			);
 			path = Shared;
 			sourceTree = "<group>";
@@ -1373,6 +1376,7 @@
 				4A537AE0C50CAFF3889EFE28 /* UIViewController+Extensions.swift in Sources */,
 				C38BEDD99477C83C91B105DD /* AccountPickerAccountLoadErrorView.swift in Sources */,
 				C1A079E8E76A02EBCB2588DA /* AccountPickerDataSource.swift in Sources */,
+				49F883F82D496D7A00A104B0 /* ExperimentStore.swift in Sources */,
 				BFF222008EEEDC3FACE342D9 /* AccountPickerFooterView.swift in Sources */,
 				C0831318A33A32BF2EAB641A /* AccountPickerHelpers.swift in Sources */,
 				1889ECB24D40EF331974C288 /* AccountPickerNoAccountEligibleErrorView.swift in Sources */,

StripeFinancialConnections/StripeFinancialConnections/Source/Common/HostController.swift

@@ -80,6 +80,7 @@ class HostController {
     private let apiClient: any FinancialConnectionsAPI
     private let clientSecret: String
     private let returnURL: String?
+    private let configuration: FinancialConnectionsSheet.Configuration
     private let elementsSessionContext: ElementsSessionContext?
     private let analyticsClient: FinancialConnectionsAnalyticsClient
     private let analyticsClientV1: STPAnalyticsClientProtocol
@@ -92,7 +93,11 @@ class HostController {
         apiClient: apiClient,
         delegate: self
     )
-    lazy var navigationController = FinancialConnectionsNavigationController(rootViewController: hostViewController)
+    lazy var navigationController: FinancialConnectionsNavigationController = {
+        let navigationController = FinancialConnectionsNavigationController(rootViewController: hostViewController)
+        configuration.style.configure(navigationController)
+        return navigationController
+    }()
 
     weak var delegate: HostControllerDelegate?
 
@@ -102,16 +107,18 @@ class HostController {
         apiClient: any FinancialConnectionsAPI,
         analyticsClientV1: STPAnalyticsClientProtocol,
         clientSecret: String,
-        elementsSessionContext: ElementsSessionContext?,
         returnURL: String?,
+        configuration: FinancialConnectionsSheet.Configuration,
+        elementsSessionContext: ElementsSessionContext?,
         publishableKey: String?,
         stripeAccount: String?
     ) {
         self.apiClient = apiClient
         self.analyticsClientV1 = analyticsClientV1
         self.clientSecret = clientSecret
-        self.elementsSessionContext = elementsSessionContext
         self.returnURL = returnURL
+        self.configuration = configuration
+        self.elementsSessionContext = elementsSessionContext
         self.analyticsClient = FinancialConnectionsAnalyticsClient()
         analyticsClient.setAdditionalParameters(
             linkAccountSessionClientSecret: clientSecret,
@@ -208,6 +215,7 @@ private extension HostController {
 
         let dataManager = NativeFlowAPIDataManager(
             manifest: synchronizePayload.manifest,
+            configuration: configuration,
             visualUpdate: synchronizePayload.visual,
             returnURL: returnURL,
             consentPaneModel: synchronizePayload.text?.consentPane,

StripeFinancialConnections/StripeFinancialConnections/Source/FinancialConnectionsSDK/FinancialConnectionsSDKImplementation.swift

@@ -32,6 +32,16 @@ public class FinancialConnectionsSDKImplementation: FinancialConnectionsSDKInter
         financialConnectionsSheet.apiClient = apiClient
         financialConnectionsSheet.elementsSessionContext = elementsSessionContext
         financialConnectionsSheet.onEvent = onEvent
+
+        var configuration = FinancialConnectionsSheet.Configuration()
+        if let styleConfig = elementsSessionContext?.styleConfig {
+            switch styleConfig {
+            case .automatic: configuration.style = .automatic
+            case .alwaysLight: configuration.style = .alwaysLight
+            case .alwaysDark: configuration.style = .alwaysDark
+            }
+        }
+        financialConnectionsSheet.configuration = configuration
         // Captures self explicitly until the callback is invoked
         financialConnectionsSheet.present(
             from: presentingViewController,