chore: update docs

Author: maciekstosio

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. 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). The `backTitleVisible` forces `backButtonDisplayMode: minimal` and omits other values. Read more [#2800](https://github.com/software-mansion/react-native-screens/pull/2800)
+
+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

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. 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). The `backTitleVisible` forces `backButtonDisplayMode: minimal` and omits other values. Read more [#2800](https://github.com/software-mansion/react-native-screens/pull/2800)
+
+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,12 @@ 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: `headerBackTitleStyle`, `disableBackButtonMenu`, `headerBackTitle` and `headerBackTitleVisible=false` is set.
+   *
+   * - `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 +207,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.
+   * To read more see [#2800](https://github.com/software-mansion/react-native-screens/pull/2800) and [#2800](https://github.com/software-mansion/react-native-screens/pull/2800).
+   *
+   * - `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;