feat: Add UserInterfaceOverridingElement (#545)

Adds a `UserInterfaceStyleOverridingElement` and a
`overrideUserInterfaceStyle()` extension on `Element` so that subtrees
of views can have their `userInterfaceStyle` (i.e. light/dark)
overridden a la SwiftUI's `colorScheme` environment variable.

Author: nsillik

BlueprintUICommonControls/Sources/UserInterfaceOverridingElement.swift

@@ -0,0 +1,72 @@
+import BlueprintUI
+import UIKit
+
+/// An element that allows overriding the user interface style (light/dark mode) for its wrapped content.
+///
+/// Use this element to force a specific appearance for a portion of your UI, regardless of the system-wide
+/// settings. This can be useful when you need to ensure certain UI elements maintain a consistent appearance
+/// across different user interface styles.
+///
+/// Example:
+/// ```swift
+/// let content = Label(text: "Hello, World!")
+/// let forcedLightMode = UserInterfaceStyleOverridingElement(
+///     userInterfaceStyle: .light,
+///     wrapping: content
+/// )
+/// ```
+public struct UserInterfaceStyleOverridingElement: Element {
+
+    /// The element being wrapped with the overridden interface style.
+    public var wrappedElement: Element
+
+    /// The user interface style to apply to the wrapped content.
+    /// This can be `.light`, `.dark`, or `.unspecified`.
+    public var userInterfaceStyle: UIUserInterfaceStyle
+
+    /// Creates a new element that overrides the user interface style for its wrapped content.
+    ///
+    /// - Parameters:
+    ///   - userInterfaceStyle: The desired interface style to apply (`.light`, `.dark`, or `.unspecified`).
+    ///   - wrapping: The content whose interface style should be overridden.
+    public init(
+        userInterfaceStyle: UIUserInterfaceStyle,
+        wrapping content: () -> (Element)
+    ) {
+        self.userInterfaceStyle = userInterfaceStyle
+        wrappedElement = content()
+    }
+
+    public var content: ElementContent {
+        ElementContent(child: wrappedElement)
+    }
+
+    public func backingViewDescription(with context: ViewDescriptionContext) -> ViewDescription? {
+        UIView.describe { config in
+            config[\.overrideUserInterfaceStyle] = userInterfaceStyle
+        }
+    }
+}
+
+extension Element {
+    /// Wraps this element in a `UserInterfaceStyleOverridingElement` to override its interface style.
+    ///
+    /// This method provides a convenient way to override the user interface style (light/dark mode)
+    /// for any element.
+    ///
+    /// Example:
+    /// ```swift
+    /// Label(text: "Always Light Mode")
+    ///   .overrideUserInterfaceStyle(.light)
+    /// ```
+    ///
+    /// - Parameter override: The desired interface style to apply. Defaults to `.unspecified`.
+    /// - Returns: A new element wrapped with the specified interface style override.
+    public func overrideUserInterfaceStyle(
+        _ override: UIUserInterfaceStyle = .unspecified
+    ) -> UserInterfaceStyleOverridingElement {
+        UserInterfaceStyleOverridingElement(userInterfaceStyle: override) {
+            self
+        }
+    }
+}

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 ### Added
+- Added `UserInterfaceStyleOverridingElement` which allows child elements to have their `userInterfaceStyle` to be forced to light/dark. Additionally added a `overrideUserInterfaceStyle` convenience to `Element`.
 
 ### Removed
 - `AccessibilityElement.deprecated_accessibility(…)`. This was deprecated in September 2021, and renamed from .accessibility(…) to .deprecated_accessibility(…) in Oct 2024.