fix(iOS): prevent back button icon from "jumping" during pop animation when display mode minimal is set (#2800)

## Description

See: react-navigation/react-navigation#12500 
for issue description with videos.

We can use the backbuttondisplaymode to hide the backbuttontitle
avoiding setting the title to `nil`
and therefore preventing the UIKit buggy back button icon animation.


@maciekstosio:
We agreed to leave `backTitleVisible`, so the API doesn't change in a
minor version. The expected behavior is that `backTitleVisible: false`
will work as "kill switch" and ignore other back button properties. When
`backTitleVisible: true` other properties will work (including
backButtonDisplayMode), but note that iOS omits `backButtonDisplayMode`
when custom back button is provided (so when any of `backTitleFontSize`,
`backTitleFontFamily`, `headerBackButtonMenuEnabled`, `headerBackTitle`
is used).

## Changes

:point_up:

## Test code and steps to reproduce

You can use `Test1084`.

1. Simply set the `headerBackButtonDisplayMode: 'minimal'` on the second
push screen.
2. Set `headerLargeTitle: true` on the first push screen.

## How this has been tested

@maciekstosio:

I tested RNScreens properties by modifying props in
`react-navigation/packages/native-stack/src/views/useHeaderConfigProps.tsx`.

I used Test1084, with the first screen having `headerLargeTitle: true`.

**Tests:**

When `backTitleVisible: false`:
- backButtonDisplayMode is ignored
- backTitleFontSize is ignored
- backTitle is ignored (but it changes title in backButtonMenu)
- disableBackButtonMenu is ignored 

When `backTitleVisible: true | undefined`:
- `backButtonDisplayMode: minimal` works
- `backButtonDisplayMode: generic` works
- `backButtonDisplayMode: default` works
- `backTitle` works and overrides `backButtonDisplayMode`
- `headerBackTitleStyle.fontSize` works and overrides
`backButtonDisplayMode`
- `headerBackButtonMenuEnabled` works and overrides
`backButtonDisplayMode`

## Checklist

- [ ] Ensured that CI passes

---------

Co-authored-by: Maciej Stosio <[email protected]>

Author: kkafar

guides/GUIDE_FOR_LIBRARY_AUTHORS.md

@@ -502,6 +502,8 @@ Allows for customizing font size to be used for back button title on iOS.
 
 Whether the back button title should be visible. Defaults to `true`.
 
+When set to `false` it works as a "kill switch": it enforces `backButtonDisplayMode=minimal` and ignores `backButtonDisplayMode`, `backTitleFontSize`, `backTitleFontFamily`, `disableBackButtonMenu`, and `backTitle` works only for back button menu.
+
 ### `blurEffect` (iOS only)
 
 Blur effect to be applied to the header. Works with `backgroundColor`'s alpha < 1.
@@ -520,7 +522,9 @@ Boolean indicating whether to show the menu on longPress of iOS >= 14 back butto
 
 ### `backButtonDisplayMode` (iOS only)
 
-Enum value indicating display mode of **default** back button. It works on iOS >= 14, and is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` or `backTitle` is set. Otherwise, when the button is customized, under the hood we use iOS native `backButtonItem` which overrides `backButtonDisplayMode`. Read more [#2123](https://github.com/software-mansion/react-native-screens/pull/2123). Possible options:
+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).
+
+Possible options:
 
 - `default` – show given back button previous controller title, system generic or just icon based on available space
 - `generic` – show given system generic or just icon based on available space

ios/RNSScreenStackHeaderConfig.mm

@@ -631,12 +631,9 @@ + (void)updateViewController:(UIViewController *)vc
 
   auto shouldUseCustomBackBarButtonItem = !isBackTitleBlank || config.disableBackButtonMenu;
 
-#if defined(__IPHONE_OS_VERSION_MAX_ALLOWED) && defined(__IPHONE_14_0) && \
-    __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_14_0
-  if (@available(iOS 14.0, *)) {
-    prevItem.backButtonDisplayMode = config.backButtonDisplayMode;
-  }
-#endif
+  // 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;
 
   if (config.isBackTitleVisible) {
     if ((config.backTitleFontFamily &&
@@ -666,11 +663,9 @@ + (void)updateViewController:(UIViewController *)vc
     // back button title should be not visible next to back button,
     // but it should still appear in back menu (if one is enabled)
 
-    // When backBarButtonItem's title is null, back menu will use value
-    // of backButtonTitle
-    [backBarButtonItem setTitle:nil];
-    shouldUseCustomBackBarButtonItem = YES;
     prevItem.backButtonTitle = resolvedBackTitle;
+    prevItem.backButtonDisplayMode = UINavigationItemBackButtonDisplayModeMinimal;
+    shouldUseCustomBackBarButtonItem = NO;
   }
 
   // Prevent unnecessary assignment of backBarButtonItem if it is not customized,

native-stack/README.md

@@ -82,7 +82,9 @@ Boolean indicating whether to show the menu on longPress of iOS >= 14 back butto
 
 #### `backButtonDisplayMode` (iOS only)
 
-Enum value indicating display mode of **default** back button. It works on iOS >= 14, and is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` or `backTitle` is set. Otherwise, when the button is customized, under the hood we use iOS native `backButtonItem` which overrides `backButtonDisplayMode`. Read more [#2123](https://github.com/software-mansion/react-native-screens/pull/2123). Possible options:
+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).
+
+Possible options:
 
 - `default` – show given back button previous controller title, system generic or just icon based on available space
 - `generic` – show given system generic or just icon based on available space
@@ -128,7 +130,9 @@ Style object for header back title. Supported properties:
 
 #### `headerBackTitleVisible` (iOS only)
 
-Whether the back button title should be visible or not. Defaults to `true`.
+Whether the back button title should be visible. Defaults to `true`.
+
+When set to `false` it works as a "kill switch": it enforces `backButtonDisplayMode=minimal` and ignores `backButtonDisplayMode`, `backTitleFontSize`, `backTitleFontFamily`, `disableBackButtonMenu`, and `backTitle` works only for back button menu.
 
 #### `headerCenter`
 

src/native-stack/types.tsx

@@ -140,11 +140,13 @@ export type NativeStackNavigationOptions = {
    */
   disableBackButtonMenu?: boolean;
   /**
-   * How the back button behaves by default (when not customized). Available on iOS>=14, and is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` or `backTitle` is set.
-   * The following values are currently supported (they correspond to 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
-   * - "generic" – show given system generic or just icon based on available space
-   * - "minimal" – show just an icon
+   * How the back button behaves. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu`, `backTitle` 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
+   * - `generic` – show given system generic or just icon based on available space
+   * - `minimal` – show just an icon
+   *
    * @platform ios
    */
   backButtonDisplayMode?: ScreenStackHeaderConfigProps['backButtonDisplayMode'];
@@ -206,6 +208,10 @@ export type NativeStackNavigationOptions = {
   };
   /**
    * Whether the back button title should be visible or not. Defaults to `true`.
+   *
+   * When set to `false` it works as a "kill switch": it enforces `backButtonDisplayMode=minimal`, and ignores `backButtonDisplayMode`,
+   * `headerBackTitleStyle`, `disableBackButtonMenu`. For `headerBackTitle` it works only in back button menu.
+   *
    * Only supported on iOS.
    *
    * @platform ios

src/types.tsx

@@ -544,6 +544,10 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
   backTitleFontSize?: number;
   /**
    * Whether the back button title should be visible or not. Defaults to `true`.
+   *
+   * When set to `false` it works as a "kill switch": it enforces `backButtonDisplayMode=minimal` and ignores `backButtonDisplayMode`, `backTitleFontSize`, `backTitleFontFamily`, `disableBackButtonMenu`.
+   * For `backTitle` it works only in back button menu.
+   *
    * @platform ios
    */
   backTitleVisible?: boolean;
@@ -570,11 +574,13 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
    */
   disableBackButtonMenu?: boolean;
   /**
-   * How the back button behaves by default (when not customized). Available on iOS>=14, and is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` or `backTitle` is set.
-   * The following values are currently supported (they correspond to 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
-   * - "generic" – show given system generic or just icon based on available space
-   * - "minimal" – show just an icon
+   * How the back button behaves. It is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu`, `backTitle` 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
+   * - `generic` – show given system generic or just icon based on available space
+   * - `minimal` – show just an icon
+   *
    * @platform ios
    */
   backButtonDisplayMode?: BackButtonDisplayMode;