feat(Android, Stack v4): Add prop for manual opt-out from applying inset to header (#3835)

## Description

Add a prop for ignoring the potential whitespace caused by the status
bar top inset being applied when stack navigators are nested on Android.

`disableTopInsetApplication` prop was introduced
on `ScreenStackHeaderConfigProps` to opt out from applying insets in a
whole subtree, starting from the topmost stack with a visible header.

Closes:
software-mansion/react-native-screens-labs#1096

## Changes

- added `disableTopInsetApplication` prop

## Before & after - visual documentation

| Before | After |
| --- | --- |
| <video
src="https://github.com/user-attachments/assets/b2a81ed6-bbef-4cd2-a093-610db2fe1e8f"
/> | <video
src="https://github.com/user-attachments/assets/4ebe6b30-f42a-4852-a73f-66b38729019e"
/> |

## Test plan

Test3835

requires changes in react-navigation

`native-stack/src/types.tsx`

in `NativeStackNavigationOptions`
```tsx
  /**
   * ...
   */
  disableTopInsetApplication?: boolean;
```

`native-stack/src/views/useHeaderConfigProps.tsx`

```tsx
export function useHeaderConfigProps({
  ...
+  disableTopInsetApplication,
...
return {
    backButtonInCustomView,
...
+ disableTopInsetApplication
...
```

## 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.
- [ ] Ensured that CI passes

Author: t0maboro

apps/src/tests/issue-tests/Test3835.tsx

@@ -0,0 +1,199 @@
+import React, { createContext, ReactNode, useContext, useState } from 'react';
+import { View, Text, Switch, StyleSheet } from 'react-native';
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+import { NavigationContainer } from '@react-navigation/native';
+
+interface HeaderConfigContextType {
+  tabShown: boolean;
+  setTabShown: React.Dispatch<React.SetStateAction<boolean>>;
+  outerShown: boolean;
+  setOuterShown: React.Dispatch<React.SetStateAction<boolean>>;
+  innerShown: boolean;
+  setInnerShown: React.Dispatch<React.SetStateAction<boolean>>;
+  disableInset: boolean;
+  setDisableInset: React.Dispatch<React.SetStateAction<boolean>>;
+}
+
+const HeaderConfigContext = createContext<HeaderConfigContextType | null>(null);
+
+const useHeaderConfig = () => {
+  const context = useContext(HeaderConfigContext);
+  if (!context) {
+    throw new Error(
+      'useHeaderConfig must be used within a HeaderConfigProvider',
+    );
+  }
+  return context;
+};
+
+interface HeaderConfigProviderProps {
+  children: ReactNode;
+}
+
+const HeaderConfigProvider = ({ children }: HeaderConfigProviderProps) => {
+  const [tabShown, setTabShown] = useState(true);
+  const [outerShown, setOuterShown] = useState(true);
+  const [innerShown, setInnerShown] = useState(true);
+  const [disableInset, setDisableInset] = useState(true);
+
+  return (
+    <HeaderConfigContext.Provider
+      value={{
+        tabShown,
+        setTabShown,
+        outerShown,
+        setOuterShown,
+        innerShown,
+        setInnerShown,
+        disableInset,
+        setDisableInset,
+      }}>
+      {children}
+    </HeaderConfigContext.Provider>
+  );
+};
+
+const ControlPanel = () => {
+  const config = useHeaderConfig();
+
+  return (
+    <View style={styles.panel}>
+      <Text style={styles.panelTitle}>Headers Config</Text>
+
+      <View style={styles.row}>
+        <Text style={styles.text}>Tab Navigator</Text>
+        <Switch value={config.tabShown} onValueChange={config.setTabShown} />
+      </View>
+      <View style={styles.divider} />
+
+      <View style={styles.row}>
+        <Text style={styles.text}>Outer Stack</Text>
+        <Switch
+          value={config.outerShown}
+          onValueChange={config.setOuterShown}
+        />
+      </View>
+      <View style={styles.divider} />
+
+      <View style={styles.row}>
+        <Text style={styles.text}>Inner Stack</Text>
+        <Switch
+          value={config.innerShown}
+          onValueChange={config.setInnerShown}
+        />
+      </View>
+      <View style={styles.divider} />
+
+      <View style={styles.row}>
+        <Text style={styles.text}>Disable Top Inset</Text>
+        <Switch
+          value={config.disableInset}
+          onValueChange={config.setDisableInset}
+        />
+      </View>
+    </View>
+  );
+};
+
+const Home = () => (
+  <View style={styles.container}>
+    <Text style={styles.screenTitle}>Home Screen</Text>
+    <ControlPanel />
+  </View>
+);
+
+const OuterStack = createNativeStackNavigator();
+const InnerStack = createNativeStackNavigator();
+const Tab = createBottomTabNavigator();
+
+const NestedStack = () => {
+  const config = useHeaderConfig();
+
+  return (
+    <InnerStack.Navigator
+      screenOptions={{
+        title: 'Inner Stack',
+        headerShown: config.innerShown,
+        disableTopInsetApplication: config.disableInset,
+      }}>
+      <InnerStack.Screen name="Home" component={Home} />
+    </InnerStack.Navigator>
+  );
+};
+
+const MainStack = () => {
+  const config = useHeaderConfig();
+
+  return (
+    <OuterStack.Navigator
+      screenOptions={{
+        title: 'Outer Stack',
+        headerShown: config.outerShown,
+        disableTopInsetApplication: config.disableInset,
+      }}>
+      <OuterStack.Screen name="NestedStack" component={NestedStack} />
+    </OuterStack.Navigator>
+  );
+};
+
+const AppContent = () => {
+  const config = useHeaderConfig();
+
+  return (
+    <NavigationContainer>
+      <Tab.Navigator
+        screenOptions={{
+          title: 'Tab Nav',
+          headerShown: config.tabShown,
+        }}>
+        <Tab.Screen name="Tab" component={MainStack} />
+      </Tab.Navigator>
+    </NavigationContainer>
+  );
+};
+
+export default function App() {
+  return (
+    <HeaderConfigProvider>
+      <AppContent />
+    </HeaderConfigProvider>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  screenTitle: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    marginBottom: 20,
+  },
+  panel: {
+    backgroundColor: '#FFF',
+    padding: 20,
+    width: '100%',
+    maxWidth: 350,
+  },
+  panelTitle: {
+    fontSize: 18,
+    fontWeight: 'bold',
+    marginBottom: 15,
+  },
+  row: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    marginVertical: 5,
+  },
+  text: {
+    fontSize: 16,
+  },
+  divider: {
+    height: 1,
+    marginVertical: 10,
+  },
+});

apps/src/tests/issue-tests/index.ts

@@ -187,6 +187,7 @@ export { default as Test3770 } from './Test3770';
 export { default as Test3793 } from './Test3793';
 export { default as Test3816 } from './Test3816';
 export { default as Test3833 } from './Test3833';
+export { default as Test3835 } from './Test3835';
 export { default as TestScreenAnimation } from './TestScreenAnimation';
 // The following test was meant to demo the "go back" gesture using Reanimated
 // but the associated PR in react-navigation is currently put on hold

guides/GUIDE_FOR_LIBRARY_AUTHORS.md

@@ -811,6 +811,14 @@ This prop has been **deprecated** due to [edge-to-edge enforcement starting from
 
 A flag to that lets you opt out of insetting the header. You may want to set this to `false` if you use an opaque status bar. Defaults to `true`.
 
+### `disableTopInsetApplication` (Android only)
+
+When set to `true` on the outermost stack with a **visible** header, disables top inset handling for that header and the entire subtree.
+
+This prop only takes effect on the outermost visible header in the hierarchy. Setting it on an inner stack has no additional impact because a parent stack has already made the decision (whether inset should be applied or not).
+
+Has no effect when `androidLegacyTopInsetBehavior` feature flag is enabled.
+
 ### `translucent`
 
 When set to true, it makes native navigation bar semi transparent. It adds blur effect on iOS. The default value is false.

src/components/ScreenStackHeaderConfig.tsx

@@ -25,7 +25,7 @@ import ScreenStackHeaderSubviewNativeComponent, {
 } from '../fabric/ScreenStackHeaderSubviewNativeComponent';
 import { prepareHeaderBarButtonItems } from './helpers/prepareHeaderBarButtonItems';
 import { isHeaderBarButtonsAvailableForCurrentPlatform } from '../utils';
-import { useTopInsetConsumption } from './contexts/TopInsetConsumptionContext';
+import { useTopInsetApplication } from './contexts/TopInsetApplicationContext';
 
 export const ScreenStackHeaderSubview: React.ComponentType<ScreenStackHeaderSubviewNativeProps> =
   ScreenStackHeaderSubviewNativeComponent;
@@ -34,8 +34,9 @@ export const ScreenStackHeaderConfig = React.forwardRef<
   View,
   ScreenStackHeaderConfigProps
 >((props, ref) => {
-  const { consumesTopInset, useLegacyBehavior } = useTopInsetConsumption(
+  const { appliesTopInset, useLegacyBehavior } = useTopInsetApplication(
     !props.hidden,
+    props.disableTopInsetApplication ?? false,
   );
 
   const { headerLeftBarButtonItems, headerRightBarButtonItems } = props;
@@ -128,7 +129,7 @@ export const ScreenStackHeaderConfig = React.forwardRef<
       synchronousShadowStateUpdatesEnabled={
         featureFlags.experiment.synchronousHeaderConfigUpdatesEnabled
       }
-      consumeTopInset={consumesTopInset}
+      consumeTopInset={appliesTopInset}
       legacyTopInsetBehavior={useLegacyBehavior}
     />
   );

src/components/ScreenStackItem.tsx

@@ -24,9 +24,9 @@ import { SafeAreaView } from './safe-area/SafeAreaView';
 import { featureFlags } from '../flags';
 import { isIOS26OrHigher } from './helpers/PlatformUtils';
 import {
-  TopInsetConsumptionContext,
-  useTopInsetConsumption,
-} from './contexts/TopInsetConsumptionContext';
+  TopInsetApplicationContext,
+  useTopInsetApplication,
+} from './contexts/TopInsetApplicationContext';
 
 type Props = Omit<
   ScreenProps,
@@ -56,7 +56,13 @@ function ScreenStackItem(
   }: Props,
   ref: React.ForwardedRef<View>,
 ) {
-  const { nextContextValue } = useTopInsetConsumption(!headerConfig?.hidden);
+  const headerVisible = !headerConfig?.hidden;
+  const headerTopInsetDisabled =
+    headerConfig?.disableTopInsetApplication ?? false;
+  const { nextContextValue } = useTopInsetApplication(
+    headerVisible,
+    headerTopInsetDisabled,
+  );
 
   const currentScreenRef = React.useRef<View | null>(null);
   const screenRefs = React.useContext(RNSScreensRefContext);
@@ -121,7 +127,7 @@ function ScreenStackItem(
 
   const content = (
     <>
-      <TopInsetConsumptionContext.Provider value={nextContextValue}>
+      <TopInsetApplicationContext.Provider value={nextContextValue}>
         <DebugContainer
           contentStyle={contentStyle}
           style={debugContainerStyle}
@@ -134,7 +140,7 @@ function ScreenStackItem(
             children
           )}
         </DebugContainer>
-      </TopInsetConsumptionContext.Provider>
+      </TopInsetApplicationContext.Provider>
       {/**
        * `HeaderConfig` needs to be the direct child of `Screen` without any intermediate `View`
        * We don't render it conditionally based on visibility to make it possible to dynamically render a custom `header`

src/components/contexts/TopInsetApplicationContext.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import { featureFlags } from '../../flags';
+
+export const TopInsetApplicationContext = React.createContext(false);
+
+export function useTopInsetApplication(
+  headerVisible: boolean,
+  disableTopInsetApplication: boolean,
+) {
+  const alreadyApplied = React.useContext(TopInsetApplicationContext);
+  const useLegacyBehavior =
+    featureFlags.experiment?.androidLegacyTopInsetBehavior ?? false;
+
+  // We want to apply the inset if:
+  // - legacy mode (androidLegacyTopInsetBehavior)
+  // - or when no ancestor applied it yet and our header is visible
+  const wantsToApplyInset =
+    useLegacyBehavior || (!alreadyApplied && headerVisible);
+
+  // We apply the padding, only if we want to apply the inset and haven't been told to suppress it
+  const appliesTopInset = wantsToApplyInset && !disableTopInsetApplication;
+
+  // Once found header that may apply the padding, mark it as consumed for the subtree
+  const nextContextValue = alreadyApplied || wantsToApplyInset;
+
+  return { appliesTopInset, useLegacyBehavior, nextContextValue };
+}

src/components/contexts/TopInsetConsumptionContext.ts

@@ -811,6 +811,19 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
    * therefore this prop loses its relevance.
    */
   topInsetEnabled?: boolean;
+  /**
+   * When set to `true` on the outermost stack with a **visible** header, disables top inset
+   * handling for that header and the entire subtree.
+   *
+   * This prop only takes effect on the outermost visible header in the hierarchy.
+   * Setting it on an inner stack has no additional impact because a parent stack
+   * has already made the decision (whether inset should be applied or not).
+   *
+   * Has no effect when `androidLegacyTopInsetBehavior` feature flag is enabled.
+   *
+   * @platform android
+   */
+  disableTopInsetApplication?: boolean;
   /**
    * Boolean indicating whether the navigation bar is translucent.
    */