feat(iOS, Tabs): handle colorScheme (dark mode) (#3716)

## Description

Adds support for `colorScheme` prop for `TabsHost` on iOS. Color scheme
will be propagated down the hierarchy.

In follow-up PR, support for this prop will be also added on Android.

Closes
software-mansion/react-native-screens-labs#982.

Supersedes
#3681.

### `experimental_userInterfaceStyle`

In #3342,
we added experimental prop `userInterfaceStyle` to `TabsScreen`. This
prop allows handling very specific edge-case when app developer wants to
force theme other than system preference for navigation components but
keep system color scheme for e.g. keyboard. After some considerations,
we decided to keep this property in order not to break users' apps but
this property will most likely remain experimental and it will receive
limited support because:
- there isn't clear API to handle this on the native side, especially on
iOS 26+ where we need to rely on internal UIKit view hierarchy to apply
`overrideUserInterfaceStyle` in specific place in order for the prop to
apply
- we think that this is an edge case (if native platform changes
keyboard appearance depending on color scheme of the controller, this is
the intended behavior)
- changing color scheme of keyboard and modals (examples mentioned in
the original issue
#3162) is
possible independently of the container color scheme
(https://reactnative.dev/docs/textinput#keyboardappearance-ios,
https://reactnative.dev/docs/alert#alertoptions for `react-native`'s
`Alert`; we also plan to support overriding color scheme for modals in
screens v5)

## Changes

- add `colorScheme` prop
- handle `colorScheme` for iOS
- add single feature test

## Before & after - visual documentation

### Before
N/A - tabs would use system's or react-native's color scheme.

### After


https://github.com/user-attachments/assets/962b737a-33ae-42d7-8d71-ea753ff49693

## Test plan

Run `single-feature-tests/test-tabs-color-scheme.tsx`.

## Checklist

- [x] Included code example that can be used to test this change.
- [x] For visual changes, included screenshots / GIFs / recordings
documenting the change.
- [x] For API changes, updated relevant public types.
- [x] Ensured that CI passes

---------

Co-authored-by: Ali <ali0fawzish@outlook.com>

Author: kligarski

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/host/TabsHostViewManager.kt

@@ -87,6 +87,11 @@ class TabsHostViewManager :
         value: String?,
     ) = Unit
 
+    override fun setColorScheme(
+        view: TabsHost?,
+        value: String?,
+    ) = Unit
+
     @ReactProp(name = "tabBarHidden")
     override fun setTabBarHidden(
         view: TabsHost,

apps/src/tests/single-feature-tests/tabs/index.ts

@@ -5,13 +5,15 @@ import OverrideScrollViewContentInsetScenario from './override-scroll-view-conte
 import TabBarHiddenScenario from './tab-bar-hidden';
 import TabsScreenOrientationScenario from './tabs-screen-orientation';
 import TabBarAppearanceDefinedBySelectedTabScenario from './test-tabs-appearance-defined-by-selected-tab';
+import TestTabsColorScheme from './test-tabs-color-scheme';
 
 const scenarios = {
   BottomAccessoryScenario,
   OverrideScrollViewContentInsetScenario,
   TabBarAppearanceDefinedBySelectedTabScenario,
   TabBarHiddenScenario,
   TabsScreenOrientationScenario,
+  TestTabsColorScheme,
 };
 
 const TabsScenarioGroup: ScenarioGroup<keyof typeof scenarios> = {

apps/src/tests/single-feature-tests/tabs/test-tabs-color-scheme.tsx

@@ -0,0 +1,131 @@
+import {
+  Appearance,
+  ColorSchemeName,
+  ScrollView,
+  StyleSheet,
+  Text,
+  TextInput,
+  View,
+} from 'react-native';
+import { Scenario } from '../../shared/helpers';
+import { createAutoConfiguredTabs } from '../../shared/tabs';
+import React, { useEffect, useState } from 'react';
+import { SettingsPicker } from '../../../shared';
+import { TabsHostProps } from 'react-native-screens';
+import useTabsConfigState from '../../shared/hooks/tabs-config';
+
+const SCENARIO: Scenario = {
+  name: 'Color Scheme',
+  key: 'test-tabs-color-scheme',
+  details: 'Tests how tabs handle system, React Native and prop color scheme.',
+  platforms: ['ios'],
+  AppComponent: App,
+};
+
+export default SCENARIO;
+
+type TabsParamList = {
+  Config: undefined;
+  Keyboard: undefined;
+};
+
+function ConfigScreen() {
+  const [config, dispatch] = useTabsConfigState<TabsParamList>();
+  const [reactColorScheme, setReactColorScheme] =
+    useState<ColorSchemeName>('unspecified');
+
+  useEffect(() => {
+    Appearance.setColorScheme(reactColorScheme);
+  }, [reactColorScheme]);
+
+  return (
+    <ScrollView style={styles.container} contentContainerStyle={styles.content}>
+      <View style={styles.section}>
+        <Text>
+          There are 3 sources of color scheme, in ascending order of precedence:
+          system, React Native and our property on TabsHost.
+        </Text>
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.heading}>System color scheme</Text>
+        <Text>
+          Switch system color scheme via quick settings in notification drawer
+          (Android/iOS) or Cmd+Shift+A (iOS simulator).
+        </Text>
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.heading}>React Native's color scheme</Text>
+        <SettingsPicker<ColorSchemeName>
+          label={'colorScheme'}
+          value={reactColorScheme}
+          onValueChange={function (value: ColorSchemeName): void {
+            setReactColorScheme(value);
+          }}
+          items={['unspecified', 'light', 'dark']}
+        />
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.heading}>TabsHost color scheme</Text>
+        <SettingsPicker<NonNullable<TabsHostProps['colorScheme']>>
+          label={'colorScheme'}
+          value={config.colorScheme ?? 'inherit'}
+          onValueChange={function (value: TabsHostProps['colorScheme']): void {
+            dispatch({
+              type: 'tabBar',
+              config: {
+                colorScheme: value,
+              },
+            });
+          }}
+          items={['inherit', 'light', 'dark']}
+        />
+      </View>
+    </ScrollView>
+  );
+}
+
+function TestScreen() {
+  return (
+    <View style={styles.containerCenter}>
+      <TextInput placeholder="Type something..." />
+    </View>
+  );
+}
+
+const Tabs = createAutoConfiguredTabs<TabsParamList>({
+  Config: ConfigScreen,
+  Keyboard: TestScreen,
+});
+
+export function App() {
+  return (
+    <Tabs.Provider>
+      <Tabs.Autoconfig />
+    </Tabs.Provider>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  containerCenter: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  content: {
+    padding: 20,
+  },
+  heading: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    marginBottom: 5,
+  },
+  section: {
+    marginBottom: 10,
+  },
+});

ios/conversion/RNSConversions-Tabs.mm

@@ -484,4 +484,20 @@ UIUserInterfaceStyle UIUserInterfaceStyleFromTabsScreenCppEquivalent(
   }
 }
 
+UIUserInterfaceStyle UIUserInterfaceStyleFromHostProp(react::RNSTabsHostColorScheme colorScheme)
+{
+  using enum facebook::react::RNSTabsHostColorScheme;
+  switch (colorScheme) {
+    case Inherit:
+      return UIUserInterfaceStyleUnspecified;
+    case Light:
+      return UIUserInterfaceStyleLight;
+    case Dark:
+      return UIUserInterfaceStyleDark;
+    default:
+      RCTLogError(@"[RNScreens] unsupported color scheme");
+      return UIUserInterfaceStyleUnspecified;
+  }
+}
+
 }; // namespace rnscreens::conversion

ios/conversion/RNSConversions.h

@@ -108,6 +108,8 @@ UIInterfaceOrientationMask UIInterfaceOrientationMaskFromRNSOrientation(RNSOrien
 RNSOrientation RNSOrientationFromUIInterfaceOrientationMask(UIInterfaceOrientationMask orientationMask);
 #endif // !TARGET_OS_TV
 
+UIUserInterfaceStyle UIUserInterfaceStyleFromHostProp(react::RNSTabsHostColorScheme colorScheme);
+
 #pragma mark SplitHost props
 
 UISplitViewControllerSplitBehavior SplitViewPreferredSplitBehaviorFromHostProp(

ios/tabs/host/RNSTabsHostComponentView.h

@@ -54,6 +54,8 @@ NS_ASSUME_NONNULL_BEGIN
 
 @property (nonatomic, strong, readonly, nullable) UIColor *nativeContainerBackgroundColor;
 
+@property (nonatomic, readonly) UIUserInterfaceStyle colorScheme;
+
 @property (nonatomic, readonly) BOOL experimental_controlNavigationStateInJS;
 
 #if RNS_IPHONE_OS_VERSION_AVAILABLE(26_0)

ios/tabs/host/RNSTabsHostComponentView.mm

@@ -113,6 +113,7 @@ - (void)resetProps
   _props = defaultProps;
 #endif
   _tabBarTintColor = nil;
+  _colorScheme = UIUserInterfaceStyleUnspecified;
 #if !TARGET_OS_TV
   _nativeContainerBackgroundColor = [UIColor systemBackgroundColor];
 #else // !TARGET_OS_TV
@@ -352,6 +353,11 @@ - (void)updateProps:(const facebook::react::Props::Shared &)props
       }
   }
 
+  if (newComponentProps.colorScheme != oldComponentProps.colorScheme) {
+    _colorScheme = rnscreens::conversion::UIUserInterfaceStyleFromHostProp(newComponentProps.colorScheme);
+    _controller.overrideUserInterfaceStyle = _colorScheme;
+  }
+
   // Super call updates _props pointer. We should NOT update it before calling super.
   [super updateProps:props oldProps:oldProps];
 }

src/components/tabs/TabsHost.types.ts

@@ -30,6 +30,8 @@ export type TabsHostNativeContainerStyleProps = {
   backgroundColor?: ColorValue;
 };
 
+export type TabsHostColorScheme = 'inherit' | 'light' | 'dark';
+
 export interface TabsHostProps {
   // #region Events
   /**
@@ -151,6 +153,19 @@ export interface TabsHostProps {
    * @supported iOS 18 or higher
    */
   tabBarControllerMode?: TabBarControllerMode;
+  /**
+   * @summary Specifies the color scheme used by the container and any child containers.
+   *
+   * The following values are currently supported:
+   * - `inherit` - the interface style from parent,
+   * - `light` - the light interface style,
+   * - `dark` - the dark interface style.
+   *
+   * @default inherit
+   *
+   * @platform ios
+   */
+  colorScheme?: TabsHostColorScheme;
   // #endregion iOS-only
 
   // #region Experimental support

src/components/tabs/TabsScreen.types.ts

@@ -716,6 +716,7 @@ export interface TabsScreenProps {
    * Does not support dynamic changes to the prop value for the currently visible screen.
    *
    * Please note that this prop is marked as **experimental** and might be subject to breaking changes or even removal.
+   * Consider using `colorScheme` on `TabsHost` instead.
    *
    * The following values are currently supported:
    * - `unspecified` - an unspecified interface style,

src/fabric/tabs/TabsHostNativeComponent.ts

@@ -16,6 +16,8 @@ type TabBarMinimizeBehavior =
 
 type TabBarControllerMode = 'automatic' | 'tabBar' | 'tabSidebar';
 
+type TabsHostColorScheme = 'inherit' | 'light' | 'dark';
+
 export interface NativeProps extends ViewProps {
   // Events
   onNativeFocusChange?: CT.DirectEventHandler<NativeFocusChangeEvent>;
@@ -28,6 +30,7 @@ export interface NativeProps extends ViewProps {
   tabBarTintColor?: ColorValue;
   tabBarMinimizeBehavior?: CT.WithDefault<TabBarMinimizeBehavior, 'automatic'>;
   tabBarControllerMode?: CT.WithDefault<TabBarControllerMode, 'automatic'>;
+  colorScheme?: CT.WithDefault<TabsHostColorScheme, 'inherit'>;
 
   // Control