Per-screen status bar configuration for native tab screens (statusBarStyle, statusBarHidden, statusBarAnimation)

[SimpleCreations]

Summary

Native stack screens can configure the status bar per screen via statusBarStyle, statusBarHidden and statusBarAnimation. The configuration is resolved natively from the visible screen hierarchy, so when a screen is hidden or unmounted, the next visible screen's configuration applies automatically.

Native tab screens (Tabs.Screen) have no equivalent. I'd like to propose adding the same status bar props to tab screens, with the same resolution semantics.

Motivation

Moving an app from JS tabs nested in a native stack to native tabs (@react-navigation/bottom-tabs/unstable), I lost the ability to set the status bar style per tab. Sometimes tabs need different styles, e.g. a transparent header over dark content on one tab and the default style on others.

Alternatives today aren't great:

• Setting the global status bar style means app code has to track which tab is visible and keep that in sync with native selection changes.
• React Native's StatusBar module (focus-aware StatusBar pattern) can't be combined with screens' status bar props on iOS. Those props require UIViewControllerBasedStatusBarAppearance = YES, while React Native's StatusBar module requires NO.
• Setting the style on a native stack nested inside the tab doesn't work either. The tab subtree is never asked for status bar configuration (details below).

My current workaround: from the focused tab, call navigation.getParent().setOptions({ statusBarStyle }) inside useFocusEffect, so the style is set on the parent native stack screen that hosts the tabs. It works, but every tab has to set the value on focus or it inherits the previous tab's style. It also only works when the tabs are hosted inside a stack screen.

Proposed API

Add to TabsScreen props, mirroring ScreenProps:

• statusBarStyle?: 'auto' | 'inverted' | 'light' | 'dark'
• statusBarHidden?: boolean
• statusBarAnimation?: 'none' | 'fade' | 'slide'

Semantics, matching stack screens:

• The selected tab's value applies.
• A native stack nested inside the tab takes precedence if its visible screen sets the trait.
• Otherwise, resolution falls back to ancestors.
• Platform limitations are the same as for stack screens (e.g. auto / inverted are unsupported on Android).

React Navigation could then expose these as native bottom tab screen options.

Possible implementation path

iOS

• The tab screen component spec could gain the same status bar props, stored on RNSTabsScreenComponentView with "has set" flags, similarly to RNSScreenView.
• RNSTabsScreenViewController may then implement preferredStatusBarStyle, prefersStatusBarHidden and preferredStatusBarUpdateAnimation. Its childViewControllerForStatusBarStyle / childViewControllerForStatusBarHidden could defer to a nested native stack when one provides the trait.
• For resolution to reach the tabs, it seems findChildVCForConfigAndTrait would need to pass through RNSTabBarController, for example by forwarding to selectedViewController. Another option might be a shared "trait provider" abstraction for RNSScreen and RNSTabsScreenViewController. I'm not sure which would fit the existing design better.
• Calling [RNSScreenWindowTraits updateStatusBarAppearance] on prop changes and on tab selection changes would presumably keep the status bar in sync.

Android

• Similarly, TabsScreen could accept the same props.
• From what I can tell, ScreenWindowTraits lookup would need to know about tabs. It could descend from a TabsHost into the selected TabsScreen and its nested containers, and fall back from a TabsScreen to its ancestors. A shared abstraction for Screen and TabsScreen might make this simpler.
• This may also relate to the existing TODO in ScreenContainer.setupFragmentManager() about the missing parent-child relationship for containers nested under a FragmentProviding parent.
• Re-applying window traits on prop changes and on tab selection changes would likely be needed as well.