feat(iOS): Add support for UINavigationBackButtonDisplayMode

[maciekstosio]

Description

This PR improves upon #2105. #2105 allowed to use iOS 14 default back button behavior when label is not provided. This PR allows to modify the behavior by allowing to provide UINavigationButtonBackButtonDisplayMode and enables it for custom text (without style modifications). The main problem is that we used to provide backButtonItem in most of the cases which disables backButtonDisplayMode.

This PR adds possibility to customize default behavior of back button using backButtonDisplayMode (UINavigationBackButtonDisplayMode) for iOS.

⚠️ This modifies only default back button, when any customization is added (including headerBackTitle) in native part we create custom RNSUIBarButtonItem and set it as backButtonItem, which disables backButtonDisplayMode behavior.

I tried to make it work together with custom label (headerBackTitle) using prevItem.backButtonTitle, but due to iOS limitations it is not viable option. It influences also back button menu - changes the label of previous screen - which is not the behavior we want.

To sum up, backButtonDisplayMode work when none of:

• headerBackTitleStyle.fontFamily
• headerBackTitleStyle.fontSize
• headerBackTitle
• disableBackButtonMenu

are set.

Screenshots / GIFs

Paper	Fabric
backButtonDisplayMode.Paper.mov	backButtonDisplayMode.Fabric.mov

Example component used in tests:

import * as React from 'react';
import { Button, View, Text, StyleSheet } from 'react-native';
import { NavigationContainer, ParamListBase } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { NativeStackNavigationProp } from '@react-navigation/native-stack';

const Stack = createNativeStackNavigator();

type NavProp = {
  navigation: NativeStackNavigationProp<ParamListBase>;
};

export default function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator>
        <Stack.Screen
          name="screenA"
          component={ScreenA}
          options={{ headerTitle: 'A: Home' }}
        />
        <Stack.Screen
          name="screenB"
          component={ScreenB}
          options={{
            headerTitle: 'B: default',
            backButtonDisplayMode: 'default',
          }}
        />
        <Stack.Screen
          name="screenC"
          component={ScreenC}
          options={{
            headerTitle: 'C: generic',
            backButtonDisplayMode: 'generic',
          }}
        />
        <Stack.Screen
          name="screenD"
          component={ScreenD}
          options={{
            headerTitle: 'D: minimal',
            backButtonDisplayMode: 'minimal',
          }}
        />
        <Stack.Screen
          name="screenE"
          component={ScreenE}
          options={{
            headerTitle: 'E: custom',
            headerBackTitle: 'Back Title',
            backButtonDisplayMode: 'minimal',
          }}
        />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

const ScreenA = ({ navigation }: NavProp) => (
  <View style={styles.container}>
    <Text>Screen A</Text>
    <Button
      onPress={() => navigation.navigate('screenB')}
      title="Go to screen B"
    />
  </View>
);

const ScreenB = ({ navigation }: NavProp) => (
  <View style={styles.container}>
    <Text>Screen B</Text>
    <Text>backButtonDisplayMode: default</Text>
    <Button
      onPress={() => navigation.navigate('screenC')}
      title="Go to screen C"
    />
  </View>
);

const ScreenC = ({ navigation }: NavProp) => (
  <View style={{ flex: 1, paddingTop: 50 }}>
    <Text>Screen C</Text>
    <Text>backButtonDisplayMode: generic</Text>
    <Button
      onPress={() => navigation.navigate('screenD')}
      title="Go to screen D"
    />
  </View>
);

const ScreenD = ({ navigation }: NavProp) => (
  <View style={styles.container}>
    <Text>Screen D</Text>
    <Text>backButtonDisplayMode: minimal</Text>
    <Button
      onPress={() => navigation.navigate('screenE')}
      title="Go to screen E"
    />
  </View>
);

const ScreenE = (_props: NavProp) => (
  <View style={styles.container}>
    <Text>Screen E</Text>
    <Text>backButtonDisplayMode omitted because of the headerBackTitle</Text>
  </View>
);

const styles = StyleSheet.create({
  container: { flex: 1, alignItems: 'center', justifyContent: 'space-around' },
});

Checklist

• Included code example that can be used to test this change
• Updated TS types
• Updated documentation:
  • https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
  • https://github.com/software-mansion/react-native-screens/blob/main/native-stack/README.md
  • https://github.com/software-mansion/react-native-screens/blob/main/src/types.tsx
  • https://github.com/software-mansion/react-native-screens/blob/main/src/native-stack/types.tsx
• Ensured that CI passes

Tested #1864: Paper ✅ Fabric ✅
Tested #1646: Paper ❌ Fabric ❌ - but it does not work on main too, could now be achieved using backButtonDisplayMode: ‘minimal’

[kkafar]

Great job 🎉 I've left few comments, please answer them.

[kkafar]

This is fine, however it would be nice to prepare separate PR with update of podfiles in all examples. Usually we try to not include changes in Podfile.lock & yarn.lock in regular PRs, but this is only a thumb rule.

[maciekstosio]

I'll prepare another PR with bump

[maciekstosio]

And revert this change here.

[maciekstosio]

Bump in #2133

[kkafar]

Does it work fine? Because I do not see RNSScreenStackHeaderConfigManagerInterface<ScreenStackHeaderConfig> being updated.

What we need to do here is run this project on Android Fabric (or just trigger the codegen manually from Android Studio) & copy generated RNSScreenStackHeaderConfigManagerInterface<ScreenStackHeaderConfig> interface from build folders android/build/generate/source/codegen/java/com/facebook/react/viewmanagers/... to android/src/paper/java/com/facebook/react/viewmanagers/ so that the interfaces are up to date.

TODO: We need to automate this somehow.

[kkafar]

Hmm, now we do always set backButtonTitle of prevItem 🤔 We need to test it thoroughly for regressions. We need to prepare list of tests examples to test before we can process further.

[maciekstosio]

I reverted that change, seems like it could have negative impact on back button menu.

[kkafar]

We need to also think through how this property interacts with backTitleVisible prop.
What happens if we set backTitleVisible: false and set this to default or other options? And the other way around.

[kkafar]

At least we should document these interactions between any related props here.

[maciekstosio]

I don't think that the logic changes significantly in this case, pls look at:

This is how it worked before, we set prevItem.backButtonTitle for back button menu, when backTitleVisible was false.

[maciekstosio]

Ok, I actually revert bunch of this changes. We can't use backButtonTitle to set custom label - more details in PR summary.

[tboba]

LGTM! Nice catch with that getDimensionPropValue 🎉

[kkafar]

Looks great overall 🎉

I've left some cosmetic remarks.

[kkafar]

I think we're good to go here 🎉

(wait for CI to pass before merging)