feat(iOS, Stack): update back button configuration logic to handle iOS 26 and fix other problems

[kligarski]

Description

Fixes back button configuration logic to handle following problems:

• on iOS 26, by default, the back button does not use the title of the previous screen; prior to this PR, react-native-screens' behavior was different,
• minimal display mode with disableBackButtonMenu: true did not work correctly (back button menu remained enabled) .

The only case that won't be supported after this PR (but it also hasn't been supported prior to this PR) is generic display mode on iOS versions prior to 26 when backTitleFontFamily, backTitleFontSize or disableBackButtonMenu is set. I decided that the appropriate approach is to fallback to default display mode behavior.

Closes https://github.com/software-mansion/react-native-screens-labs/issues/578.
Closes #3551.

Reasoning

Prior to this PR, there were many attempts to fix the back button configuration logic (e.g. #2800, #2860, #2867) but after native behavior change in iOS 26, I decided to have a look at this problem once again.

Here are the most important observations:

• In order to use custom fonts or disable back button menu, we need to use a custom back button. If custom back button is used, native backButtonDisplayMode property is ignored (what, to be fair, makes sense).
• Starting from iOS 26, text in the back button is used only if you set backButtonTitle property (or use custom back button).
• We can't use generic back button text in custom back button (there is no API to get the localized string).

Keeping those observations in mind, this is the configuration flow proposed in this PR:

Here is the comparison between prior and after this PR based on Test2809:

Compatibility with previous versions

In order to maintain compatibility with previous react-native-screens and react-navigation versions, I added backButtonUseModernImplementation prop.

New react-navigation, new react-native-screens

In new react-navigation release, we need to set backButtonUseModernImplementation to true and always pass backButtonDisplayMode. Here is the patch to react-navigation:

diff --git a/packages/native-stack/src/views/useHeaderConfigProps.tsx b/packages/native-stack/src/views/useHeaderConfigProps.tsx
index 74ff388d4..6656946fb 100644
--- a/packages/native-stack/src/views/useHeaderConfigProps.tsx
+++ b/packages/native-stack/src/views/useHeaderConfigProps.tsx
@@ -273,9 +273,8 @@ export function useHeaderConfigProps({
     backTitleVisible: isBackButtonDisplayModeAvailable
       ? undefined
       : headerBackButtonDisplayMode !== 'minimal',
-    backButtonDisplayMode: isBackButtonDisplayModeAvailable
-      ? headerBackButtonDisplayMode
-      : undefined,
+    backButtonDisplayMode: headerBackButtonDisplayMode,
+    backButtonUseModernImplementation: true,
     backTitleFontFamily,
     backTitleFontSize,
     blurEffect: headerBlurEffect,

New version of react-native-screens will use new implementation only if it receives backButtonUseModernImplementation=true. By default, the prop is false.

Old react-navigation, new react-native-screens

No backButtonUseModernImplementation -> backButtonUseModernImplementation=false (default value) -> react-native-screens uses legacy implementation, no changes to the back button logic.

New react-navigation, old react-native-screens

react-native-screens uses old implementation. Passing backButtonDisplayMode always directly, without the logic from react-navigation to pass undefined in some cases will not change anything - undefined was passed only when back button required customization. In such cases, backButtonDisplayMode is ignored by the system already.

Changes

• refactor back button configuration logic
• update docs, deprecate backTitleVisible
• add backButtonUseNewImplementation to switch between legacy and modern implementations
• add new cases to Test2809

Test code and steps to reproduce

Run Test2809. Please note the changes required to react-navigation to see new behavior.

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

[t0maboro]

That's not recommended in every case - imo we should rather recommend migrating to the new implementation; we should be more specific about the versioning here. If we don't know which version of React Navigation it will be in, we should at least create a ticket to revisit it.

[kligarski]

Sorry, I forgot to change values and description here. Previously the prop was useLegacyImplementation. Now it should be correct.

8009f8c

I created a ticket to add info about versions in the future: https://github.com/software-mansion/react-native-screens-labs/issues/513.

[kligarski]

I thought about using compatibilityFlags but it would solve "new react-navigation, old react-native-screens" case but not "old react-navigation, new react-native-screens".

[kligarski]

@kkafar

[kkafar]

Just a status update from my end: this is a complicated PR that requires a lot of testing and at the same time is not of high priority, therefore I can not really find time to review it properly. I've added it to next iteration with higher priority.