chore: update docs for scrollEdgeEffects, blurEffect and scrollEdgeEffects interaction (#3407)

## Description

Describes interaction between `blurEffect` and `scrollEdgeEffects`, adds
possible values for `scrollEdgeEffects` to docs, adds
`scrollEdgeEffects` to guide for library authors. Adds warning in JS
when `blurEffect` and `scrollEdgeEffects` are used on iOS 26+.

Part of
software-mansion/react-native-screens-labs#551.

Author: kligarski

guides/GUIDE_FOR_LIBRARY_AUTHORS.md

@@ -104,6 +104,23 @@ Unfortunately the same behavior is not available on iOS since the behavior of na
 
 Defaults to `false`.
 
+### `scrollEdgeEffects` (>= iOS 26 only)
+
+Configures the scroll edge effect for the _content ScrollView_ (the ScrollView that is present in first descendants chain of the Screen).
+Depending on values set, it will blur the scrolling content below certain UI elements (e.g. header items, search bar) for the specified edge of the ScrollView.
+When set in nested containers, i.e. ScreenStack inside BottomTabs, or the other way around, the ScrollView will use only the innermost one's config.
+
+Edge effects can be configured for each edge separately. The following values are currently supported:
+
+- `automatic` - the automatic scroll edge effect style,
+- `hard` - a scroll edge effect with a hard cutoff and dividing line,
+- `soft` - a soft-edged scroll edge effect,
+- `hidden` - no scroll edge effect.
+
+Defaults to `automatic` for each edge.
+
+**Note:** Using both `blurEffect` and `scrollEdgeEffects` (>= iOS 26) simultaneously may cause overlapping effects.
+
 ### `navigationBarColor` (Android only)
 
 This prop has been **deprecated** due to [edge-to-edge enforcement starting from Android SDK 35](https://developer.android.com/about/versions/15/behavior-changes-15#ux). 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.
@@ -541,6 +558,8 @@ When set to `false` it works as a "kill switch": it enforces `backButtonDisplayM
 
 Blur effect to be applied to the header. Works with `backgroundColor`'s alpha < 1.
 
+**Note:** Using both `blurEffect` and `scrollEdgeEffects` (>= iOS 26) simultaneously may cause overlapping effects.
+
 ### `children`
 
 Pass `ScreenStackHeaderBackButtonImage`, `ScreenStackHeaderRightView`, `ScreenStackHeaderLeftView`, `ScreenStackHeaderCenterView`, `ScreenStackHeaderSearchBarView`.

src/components/ScreenStackItem.tsx

@@ -76,6 +76,23 @@ function ScreenStackItem(
     headerHiddenPreviousRef.current = headerConfigHiddenWithDefault;
   }, [headerConfigHiddenWithDefault, stackPresentationWithDefault]);
 
+  const hasEdgeEffects =
+    rest?.scrollEdgeEffects === undefined ||
+    Object.values(rest.scrollEdgeEffects).some(
+      propValue => propValue !== 'hidden',
+    );
+  const hasBlurEffect =
+    headerConfig?.blurEffect !== undefined &&
+    headerConfig.blurEffect !== 'none';
+
+  warnOnce(
+    hasEdgeEffects &&
+      hasBlurEffect &&
+      Platform.OS === 'ios' &&
+      parseInt(Platform.Version, 10) >= 26,
+    '[RNScreens] Using both `blurEffect` and `scrollEdgeEffects` simultaneously may cause overlapping effects.',
+  );
+
   const debugContainerStyle = getPositioningStyle(
     sheetAllowedDetents,
     stackPresentationWithDefault,

src/components/bottom-tabs/BottomTabsScreen.types.ts

@@ -503,12 +503,26 @@ export interface BottomTabsScreenProps {
   overrideScrollViewContentInsetAdjustmentBehavior?: boolean;
   /**
    * Configures the scroll edge effect for the _content ScrollView_ (the ScrollView that is present in first descendants chain of the Screen).
-   * Depending on values set, it will blur the scrolling content below certain UI elements (Header Items, SearchBar)
-   * for the specifed edge of the ScrollView.
+   * Depending on values set, it will blur the scrolling content below certain UI elements (header items, search bar)
+   * for the specified edge of the ScrollView.
    *
    * When set in nested containers, i.e. ScreenStack inside BottomTabs, or the other way around,
    * the ScrollView will use only the innermost one's config.
    *
+   * Edge effects can be configured for each edge separately. The following values are currently supported:
+   *
+   * - `automatic` - the automatic scroll edge effect style,
+   * - `hard` - a scroll edge effect with a hard cutoff and dividing line,
+   * - `soft` - a soft-edged scroll edge effect,
+   * - `hidden` - no scroll edge effect.
+   *
+   * The supported values correspond to the `UIScrollEdgeEffect`'s `style` and `isHidden` props
+   * in the official UIKit documentation:
+   *
+   * @see {@link https://developer.apple.com/documentation/uikit/uiscrolledgeeffect|UIScrollEdgeEffect}
+   *
+   * @default `automatic` for each edge
+   *
    * @platform ios
    *
    * @supported iOS 26 or higher

src/types.tsx

@@ -235,12 +235,28 @@ export interface ScreenProps extends ViewProps {
   nativeBackButtonDismissalEnabled?: boolean;
   /**
    * Configures the scroll edge effect for the _content ScrollView_ (the ScrollView that is present in first descendants chain of the Screen).
-   * Depending on values set, it will blur the scrolling content below certain UI elements (Header Items, SearchBar)
-   * for the specifed edge of the ScrollView.
+   * Depending on values set, it will blur the scrolling content below certain UI elements (header items, search bar)
+   * for the specified edge of the ScrollView.
    *
    * When set in nested containers, i.e. ScreenStack inside BottomTabs, or the other way around,
    * the ScrollView will use only the innermost one's config.
    *
+   * **Note:** Using both `blurEffect` and `scrollEdgeEffects` (>= iOS 26) simultaneously may cause overlapping effects.
+   *
+   * Edge effects can be configured for each edge separately. The following values are currently supported:
+   *
+   * - `automatic` - the automatic scroll edge effect style,
+   * - `hard` - a scroll edge effect with a hard cutoff and dividing line,
+   * - `soft` - a soft-edged scroll edge effect,
+   * - `hidden` - no scroll edge effect.
+   *
+   * The supported values correspond to the `UIScrollEdgeEffect`'s `style` and `isHidden` props
+   * in the official UIKit documentation:
+   *
+   * @see {@link https://developer.apple.com/documentation/uikit/uiscrolledgeeffect|UIScrollEdgeEffect}
+   *
+   * @default `automatic` for each edge
+   *
    * @platform ios
    *
    * @supported iOS 26 or higher
@@ -627,6 +643,9 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
   backTitleVisible?: boolean;
   /**
    * Blur effect to be applied to the header. Works with backgroundColor's alpha < 1.
+   *
+   * **Note:** Using both `blurEffect` and `scrollEdgeEffects` (>= iOS 26) simultaneously may cause overlapping effects.
+   *
    * @platform ios
    */
   blurEffect?: BlurEffectTypes;