add backButtonUseModernImplementation prop to keep backward compatibility

Author: kligarski

guides/GUIDE_FOR_LIBRARY_AUTHORS.md

@@ -523,7 +523,7 @@ Controls the color of the navigation header.
 
 ### `backTitle` (iOS only)
 
-Allows for controlling the string to be rendered next to back button. For iOS versions prior to 26, the title of the previous screen is used as default.
+Allows for controlling the string to be rendered next to back button. The title of the previous screen is used as default if `backButtonUseModernImplementation` is set to `false` or if `backButtonUseModernImplementation` is set to `true` and iOS version prior to 26 is used.
 
 ### `backTitleFontFamily` (iOS only)
 
@@ -535,7 +535,7 @@ Allows for customizing font size to be used for back button title on iOS.
 
 ### `backTitleVisible` (iOS only)
 
-This prop has been **deprecated**. Setting it has no effect as native code related to this prop has been removed. Kept only for backward compatibility. Will be removed in next major release.
+This prop has been **deprecated**. Kept only for backward compatibility, is respected only if `backButtonUseModernImplementation` is set to `false`.
 
 Whether the back button title should be visible. Defaults to `true`.
 
@@ -577,6 +577,17 @@ On iOS versions prior to 26, using `generic` display mode with `backTitleFontFam
 or `disableBackButtonMenu` property set is not supported due to limitations in the native platform.
 In such cases, display mode will fallback to `default`.
 
+If `backButtonUseModernImplementation` is set to `false`, this prop is used only when none of: `backTitleFontFamily`,
+`backTitleFontSize`, `disableBackButtonMenu` and `backTitleVisible=false` is set.
+
+### `backButtonUseModernImplementation` (iOS only)
+
+Used for backward compatibility only. Setting this prop to `false` is recommended.
+
+Uses previous implementation of native back button configuration.
+
+Default is `true`.
+
 ### `headerLeftBarButtonItems` / `headerRightBarButtonsItems` (iOS only)
 
 An array of objects describing native bar button items to display on the left or right side of the header. Each item can be:

ios/RNSScreenStackHeaderConfig.h

@@ -58,6 +58,7 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic) BOOL backButtonInCustomView;
 @property (nonatomic) UISemanticContentAttribute direction;
 @property (nonatomic) UINavigationItemBackButtonDisplayMode backButtonDisplayMode;
+@property (nonatomic) BOOL backButtonUseModernImplementation;
 @property (nonatomic) RNSBlurEffectStyle blurEffect;
 @property (nonatomic, copy, nullable) NSArray<NSDictionary<NSString *, id> *> *headerRightBarButtonItems;
 @property (nonatomic, copy, nullable) NSArray<NSDictionary<NSString *, id> *> *headerLeftBarButtonItems;

ios/RNSScreenStackHeaderConfig.mm

@@ -747,6 +747,18 @@ + (void)updateViewController:(UIViewController *)vc
 
 - (void)configureBackItem:(nullable UINavigationItem *)prevItem
                withPrevVC:(nullable UIViewController *)prevVC API_UNAVAILABLE(tvos)
+{
+  const auto *config = self;
+
+  if (config.backButtonUseModernImplementation) {
+    [self configureModernBackItem:prevItem withPrevVC:prevVC];
+  } else {
+    [self configureLegacyBackItem:prevItem withPrevVC:prevVC];
+  }
+}
+
+- (void)configureModernBackItem:(nullable UINavigationItem *)prevItem
+                     withPrevVC:(nullable UIViewController *)prevVC API_UNAVAILABLE(tvos)
 {
 #if !TARGET_OS_TV
   if (prevItem == nil) {
@@ -898,6 +910,79 @@ - (void)configureNativeBackItem:(nonnull UINavigationItem *)prevItem API_UNAVAIL
   prevItem.backBarButtonItem = nil;
 }
 
+- (void)configureLegacyBackItem:(nullable UINavigationItem *)prevItem
+                     withPrevVC:(nullable UIViewController *)prevVC API_UNAVAILABLE(tvos)
+{
+#if !TARGET_OS_TV
+  if (prevItem == nil) {
+    return;
+  }
+
+  const auto *config = self;
+
+  const auto isBackTitleBlank = [NSString rnscreens_isBlankOrNull:config.backTitle] == YES;
+  NSString *resolvedBackTitle = isBackTitleBlank ? prevItem.title : config.backTitle;
+
+  // If previous screen controller was recreated (e.g. when you go back to tab with stack that has multiple screens),
+  // its navigationItem may not have any information from screen's headerConfig, including the title.
+  // If this is the case, we attempt to extract the title from previous screen's config directly.
+  if (resolvedBackTitle == nil && [prevVC isKindOfClass:[RNSScreen class]]) {
+    RNSScreen *prevScreen = static_cast<RNSScreen *>(prevVC);
+    resolvedBackTitle = prevScreen.screenView.findHeaderConfig.title;
+  }
+
+  prevItem.backButtonTitle = resolvedBackTitle;
+  // 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) {
+    RNSBackBarButtonItem *backBarButtonItem = [[RNSBackBarButtonItem alloc] initWithTitle:resolvedBackTitle
+                                                                                    style:UIBarButtonItemStylePlain
+                                                                                   target:nil
+                                                                                   action:nil];
+    auto shouldUseCustomBackBarButtonItem = config.disableBackButtonMenu;
+    [backBarButtonItem setMenuHidden:config.disableBackButtonMenu];
+
+    if ((config.backTitleFontFamily &&
+         // While being used by react-navigation, the `backTitleFontFamily` will
+         // be set to "System" by default - which is the system default font.
+         // To avoid always considering the font as customized, we need to have an additional check.
+         // See: https://github.com/software-mansion/react-native-screens/pull/2105#discussion_r1565222738
+         ![config.backTitleFontFamily isEqual:@"System"]) ||
+        config.backTitleFontSize) {
+      shouldUseCustomBackBarButtonItem = YES;
+      NSMutableDictionary *attrs = [NSMutableDictionary new];
+      NSNumber *size = config.backTitleFontSize ?: @17;
+      if (config.backTitleFontFamily) {
+        attrs[NSFontAttributeName] = [RCTFont updateFont:nil
+                                              withFamily:config.backTitleFontFamily
+                                                    size:size
+                                                  weight:nil
+                                                   style:nil
+                                                 variant:nil
+                                         scaleMultiplier:1.0];
+      } else {
+        attrs[NSFontAttributeName] = [UIFont boldSystemFontOfSize:[size floatValue]];
+      }
+      [RNSScreenStackHeaderConfig setTitleAttibutes:attrs forButton:backBarButtonItem];
+    }
+
+    // Prevent unnecessary assignment of backBarButtonItem if it is not customized,
+    // as assigning one will override the native behavior of automatically shortening
+    // the title to "Back" or hide the back title if there's not enough space.
+    // See: https://github.com/software-mansion/react-native-screens/issues/1589
+    if (shouldUseCustomBackBarButtonItem) {
+      prevItem.backBarButtonItem = backBarButtonItem;
+    }
+  } else {
+    // back button title should be not visible next to back button,
+    // but it should still appear in back menu
+    prevItem.backButtonDisplayMode = UINavigationItemBackButtonDisplayModeMinimal;
+  }
+#endif
+}
+
 - (void)applySemanticContentAttributeIfNeededToNavCtrl:(UINavigationController *)navCtrl
 {
   if ((self.direction == UISemanticContentAttributeForceLeftToRight ||
@@ -1216,6 +1301,7 @@ - (void)updateProps:(react::Props::Shared const &)props oldProps:(react::Props::
   }
 
   _backTitleVisible = newScreenProps.backTitleVisible;
+  _backButtonUseModernImplementation = newScreenProps.backButtonUseModernImplementation;
 
   // We cannot compare SharedColor because it is shared value.
   // We could compare color value, but it is more performant to just assign new value
@@ -1357,6 +1443,7 @@ - (RCTShadowView *)shadowView
 RCT_EXPORT_VIEW_PROPERTY(backButtonInCustomView, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(disableBackButtonMenu, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(backButtonDisplayMode, UINavigationItemBackButtonDisplayMode)
+RCT_EXPORT_VIEW_PROPERTY(backButtonUseModernImplementation, BOOL)
 RCT_REMAP_VIEW_PROPERTY(hidden, hide, BOOL) // `hidden` is an UIView property, we need to use different name internally
 RCT_EXPORT_VIEW_PROPERTY(translucent, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(headerLeftBarButtonItems, NSArray)

src/fabric/ScreenStackHeaderConfigNativeComponent.ts

@@ -72,6 +72,7 @@ export interface NativeProps extends ViewProps {
   titleColor?: ColorValue;
   disableBackButtonMenu?: boolean;
   backButtonDisplayMode?: WithDefault<BackButtonDisplayMode, 'default'>;
+  backButtonUseModernImplementation?: WithDefault<boolean, false>;
   hideBackButton?: boolean;
   backButtonInCustomView?: boolean;
   blurEffect?: WithDefault<BlurEffect, 'none'>;

src/types.tsx

@@ -603,7 +603,12 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
    */
   backTitleFontSize?: number;
   /**
-   * @deprecated Setting this prop has no effect. Retained only for backward compatibility.
+   * @deprecated This prop is respected only if `backButtonUseModernImplementation` is set to `false`.
+   *
+   * 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
    */
@@ -648,9 +653,22 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
    * or `disableBackButtonMenu` property set is not supported due to limitations in the native platform.
    * In such cases, display mode will fallback to `default`.
    *
+   * If `backButtonUseModernImplementation` is set to `false`, this prop is used only when none of: `backTitleFontFamily`,
+   * `backTitleFontSize`, `disableBackButtonMenu` and `backTitleVisible=false` is set.
+   *
    * @platform ios
    */
   backButtonDisplayMode?: BackButtonDisplayMode;
+  /**
+   * Setting this prop to `true` is recommended. Prop available for backward compatibility.
+   *
+   * Uses new implementation for native back button configuration.
+   *
+   * @default false
+   *
+   * @platform ios
+   */
+  backButtonUseModernImplementation?: boolean;
   /**
    * Array of UIBarButtomItems to the left side of the header.
    *