fix(iOS): fix header back button display mode when back title text is custom (#2860)

## Description

Fixes #2809 

⚠️ This change requires
[react-navigation](react-navigation/react-navigation#12543)
changed to merged first and submodule bumped for test to pass.

This PR solves an issue, when using custom backTitle caused usage of the
backButtonItem, which in turn disabled backButtonDisplayMode. This cause
inconsistent behavior with UIKit - the back button label wasn't reduced
to Back or chevron as it is does for
[backButtonDisplayMode](https://developer.apple.com/documentation/uikit/uinavigationitem/backbuttondisplaymode-swift.property?language=objc).

Coresponding [react-navigation
changes](react-navigation/react-navigation#12543).

## Changes

- Remove check if the backTitle is filled from condition that enforces
backButtonItem usage and set backTitle by default.
- Update docs
- Update tests

## Test code and steps to reproduce

see `FabricExample/e2e/issuesTests/Test2809.e2e.ts` and
`apps/src/tests/Test2809/index.tsx`
## Checklist

- [x] Included code example that can be used to test this change
- [x] Updated TS types
- [x] Updated documentation: <!-- For adding new props to native-stack
-->
- [x]
https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
- [x]
https://github.com/software-mansion/react-native-screens/blob/main/native-stack/README.md
- [x]
https://github.com/software-mansion/react-native-screens/blob/main/src/types.tsx
- [x]
https://github.com/software-mansion/react-native-screens/blob/main/src/native-stack/types.tsx
- [ ] Ensured that CI passes

Author: maciekstosio

FabricExample/e2e/issuesTests/Test2809.e2e.ts

@@ -89,11 +89,9 @@ describeIfiOS('Test2809', () => {
             await expectBackButtonMenuWithDifferentLabels('Back', 'First'); // Check if backButtonMenu works
          });
 
-         // TODO: We should be able to fix that
-         // Custom text overrides backButtonDisplayMode
-         it('custom text is NOT truncated by backButtonDisplayMode and is used in back button menu', async () => {
-            await expectInitialPageToExist('EnabledGenericCustomText', by.text('Custom'));
-            await expectBackButtonMenuWithTheSameLabel('Custom'); // Check if backButtonMenu works
+         it('custom text is truncated by backButtonDisplayMode and is used in back button menu', async () => {
+            await expectInitialPageToExist('EnabledGenericCustomText', by.text('Back'));
+            await expectBackButtonMenuWithDifferentLabels('Back', 'Custom'); // Check if backButtonMenu works
          });
 
          // Custom styles override backButtonDisplayMode
@@ -195,17 +193,13 @@ describeIfiOS('Test2809', () => {
       await element(by.text('Pop to top')).tap(); // Go back
    });
 
-   // TODO: We should be able to fix that
-   // Custom text overrides backButtonDisplayMode because of using backButtonItem
-   it.failing('Custom long back label should be truncated to generic by backButtonDisplayMode', async () => {
+   it('Custom long back label should be truncated to generic by backButtonDisplayMode', async () => {
       await expectInitialPageToExist('CustomLongCustomText', by.text('Back'));
       await expectBackButtonMenuWithDifferentLabels('Back', 'LongLongLongLongLong'); // Check if backButtonMenu works
       await element(by.text('Pop to top')).tap(); // Go back
    });
 
-   // TODO: We should be able to fix that
-   // Custom text overrides backButtonDisplayMode because of using backButtonItem
-   it.failing('Custom back label should be truncated to minimal by backButtonDisplayMode when title is long', async () => {
+   it('Custom back label should be truncated to minimal by backButtonDisplayMode when title is long', async () => {
       await expectInitialPageToExist('CustomCustomTextWithLongTitle', by.id('chevron.backward'), by.text('CustomBack'));
       await expectBackButtonMenuIconAndLabel('chevron.backward', 'CustomBack'); // Check if backButtonMenu works
       await element(by.text('Pop to top')).tap(); // Go back

apps/src/tests/Test2809/index.tsx

@@ -153,11 +153,6 @@ function Home({
         title="CustomCustomTextWithLongTitle"
         onPress={() => navigation.navigate('CustomCustomTextWithLongTitle')}
       />
-
-      <Button
-        title="Go back"
-        onPress={() => navigation.goBack()}
-      />
     </View>
   );
 }

guides/GUIDE_FOR_LIBRARY_AUTHORS.md

@@ -532,7 +532,7 @@ Boolean indicating whether to show the menu on longPress of iOS >= 14 back butto
 
 ### `backButtonDisplayMode` (iOS only)
 
-Enum value indicating display mode of back button. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu`, `backTitle` and `backTitleVisible=false` is set. The `backTitleVisible` forces `backButtonDisplayMode: minimal` and omits other values. Read more [#2800](https://github.com/software-mansion/react-native-screens/pull/2800). The other props, under the hood, customize `backButtonItem` which overrides `backButtonDisplayMode`. Read more [#2123](https://github.com/software-mansion/react-native-screens/pull/2123).
+Enum value indicating display mode of back button. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` and `backTitleVisible=false` is set. The `backTitleVisible` forces `backButtonDisplayMode: minimal` and omits other values. Read more [#2800](https://github.com/software-mansion/react-native-screens/pull/2800). The other props, under the hood, customize `backButtonItem` which overrides `backButtonDisplayMode`. Read more [#2123](https://github.com/software-mansion/react-native-screens/pull/2123).
 
 Possible options:
 

ios/RNSScreenStackHeaderConfig.mm

@@ -629,11 +629,12 @@ + (void)updateViewController:(UIViewController *)vc
                                                                              action:nil];
   [backBarButtonItem setMenuHidden:config.disableBackButtonMenu];
 
-  auto shouldUseCustomBackBarButtonItem = !isBackTitleBlank || config.disableBackButtonMenu;
+  auto shouldUseCustomBackBarButtonItem = config.disableBackButtonMenu;
 
   // This has any effect only in case the `backBarButtonItem` is not set.
   // We apply it before we configure the back item, because it might get overriden.
   prevItem.backButtonDisplayMode = config.backButtonDisplayMode;
+  prevItem.backButtonTitle = resolvedBackTitle;
 
   if (config.isBackTitleVisible) {
     if ((config.backTitleFontFamily &&
@@ -661,9 +662,7 @@ + (void)updateViewController:(UIViewController *)vc
     }
   } else {
     // back button title should be not visible next to back button,
-    // but it should still appear in back menu (if one is enabled)
-
-    prevItem.backButtonTitle = resolvedBackTitle;
+    // but it should still appear in back menu
     prevItem.backButtonDisplayMode = UINavigationItemBackButtonDisplayModeMinimal;
     shouldUseCustomBackBarButtonItem = NO;
   }

native-stack/README.md

@@ -82,7 +82,7 @@ Boolean indicating whether to show the menu on longPress of iOS >= 14 back butto
 
 #### `backButtonDisplayMode` (iOS only)
 
-Enum value indicating display mode of back button. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu`, `backTitle` and `backTitleVisible=false` is set. The `backTitleVisible` forces `backButtonDisplayMode: minimal` and omits other values. Read more [#2800](https://github.com/software-mansion/react-native-screens/pull/2800). The other props, under the hood, customize `backButtonItem` which overrides `backButtonDisplayMode`. Read more [#2123](https://github.com/software-mansion/react-native-screens/pull/2123).
+Enum value indicating display mode of back button. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` and `backTitleVisible=false` is set. The `backTitleVisible` forces `backButtonDisplayMode: minimal` and omits other values. Read more [#2800](https://github.com/software-mansion/react-native-screens/pull/2800). The other props, under the hood, customize `backButtonItem` which overrides `backButtonDisplayMode`. Read more [#2123](https://github.com/software-mansion/react-native-screens/pull/2123).
 
 Possible options:
 

src/native-stack/types.tsx

@@ -140,7 +140,7 @@ export type NativeStackNavigationOptions = {
    */
   disableBackButtonMenu?: boolean;
   /**
-   * How the back button behaves. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu`, `backTitle` and `backTitleVisible=false` is set.
+   * How the back button behaves. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` and `backTitleVisible=false` is set.
    * The following values are currently supported (they correspond to [UINavigationItemBackButtonDisplayMode](https://developer.apple.com/documentation/uikit/uinavigationitembackbuttondisplaymode?language=objc)):
    *
    * - `default` – show given back button previous controller title, system generic or just icon based on available space

src/types.tsx

@@ -576,7 +576,7 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
    */
   disableBackButtonMenu?: boolean;
   /**
-   * How the back button behaves. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu`, `backTitle` and `backTitleVisible=false` is set.
+   * How the back button behaves. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` and `backTitleVisible=false` is set.
    * The following values are currently supported (they correspond to [UINavigationItemBackButtonDisplayMode](https://developer.apple.com/documentation/uikit/uinavigationitembackbuttondisplaymode?language=objc)):
    *
    * - `default` – show given back button previous controller title, system generic or just icon based on available space