feat: add ScrollViewMarker experimental component (#3674)

## Description

This PR adds a PoC of `ScrollViewMarker` experimental native component.

It is introduced to handle two responsibilities:

1. Configuration of `ScrollView` (in particular edge effects)

I want to move these configuration options off the "screen components",
and have a single component that can be used to configure the
`ScrollView`.

2. Detection of `ScrollView` in native view hierarchy

Currently, both we & UIKit employ very simple "first descendant chain"
heuristics
to detect the presence of `ScrollView` in the view hierarchy & use it as
"content ScrollView". This sometimes works, but it is very easy to break
by
    user code.

Now, user will be required to wrap the `ScrollView` in our component, so
this
is an additional step, but it will allow us to robustly detect the
presence
    of `ScrollView`.

There is open question of what do we do, if there are multiple
`ScrollViews`
a user want to configure. There can be only a single "content
`ScrollView`".
Atm. I think that reasonable approach is to have non-required
`isContentScrollView`
property with `true` as default value, and if there are multiple
`ScrollView` instances,
we can throw an error asking to set this property to `false` for all,
but the
actual "content `ScrollView`". We should decide on default value of
`isContentScrollView`
    based on what we estimate as more frequent use case.

Alternatively, we can expose two components: `ScrollViewMarker` &
`ContentScrollViewMarker`,
which will handle that prop configuration for the user? Let's discuss
below.

Beside adding a component I've also implemented basic support for scroll
edge effects
configuration.

`RNSScrollViewSeeking` protocol is introduced. Other component can
implement it to be
notified when `ScrollViewMarker` is attached to view hierarchy.
Currently it is not
used anywhere & it's shape is not final, but it serves PoC purposes.

Closes
<software-mansion/react-native-screens-labs#981>

## Caveats

*
<a84419e>

    Similarly to iOS, I use UIManagerListener.didMountItems to detect a
    moment when the view hierarchy is assembled.

    > [!caution]
> I've tested & views are created in bottom-up order -> that means the
> `ScrolLViewMarker` will usually be created BEFORE e.g. a `StackHost`,
> therefore its `UIManagerListener` listener will be added first -> it
> will be called before listener of `StackHost`. If for some reason
order
> of view creation changes, e.g. `ScrollViewMarker` will be rendered in
    > consecutive render, the order here will also change.

## Visual documentation

N/A

## Test plan

It's rather hard to test this component in isolation & somehow observe
an effect
in JS. If someone has an idea - let me know.

Right now, I've introduced `test-svm-configures-scroll-view`, which uses
`StackContainer` to make scroll edge effects visible, but mostly this
test is about prepared environment for testing on native side.
Especially on Android, where there are no edge effects.

## Checklist

* [x] Included code example that can be used to test this change.
* [x] Updated / created local changelog entries in relevant test files.
* [x] For visual changes, included screenshots / GIFs / recordings
documenting the change.
* [x] For API changes, updated relevant public types.
* [x] Ensured that CI passes

Author: kkafar

FabricExample/__tests__/App.test.tsx

@@ -2,7 +2,6 @@
  * @format
  */
 
-
 import React from 'react';
 import ReactTestRenderer from 'react-test-renderer';
 import App from '../App';

FabricExample/ios/Podfile.lock

@@ -2192,7 +2192,7 @@ EXTERNAL SOURCES:
 
 SPEC CHECKSUMS:
   FBLazyVector: 974207232af1c5372a56239516ccc450a6420bfd
-  hermes-engine: 83fbd293b074bd63933c39ddfa88ffb390a0f6c4
+  hermes-engine: 83594ce32ee796061eeceb760a80b9dff31adc8f
   RCTDeprecation: 8ae59687fd548d481aa5ce8014ac7cd9b47e7316
   RCTRequired: d711b3887891fab6a77c6b9cdc49a3d8b171e36a
   RCTSwiftUI: 96986e49a4fdc2c2103929dee2641e1b57edf33d
@@ -2263,10 +2263,10 @@ SPEC CHECKSUMS:
   ReactAppDependencyProvider: 625d2f6d9d5ef01acc9dfe2b5385504bbffd2ad0
   ReactCodegen: 7cc1904b7db3c7b68dfd4b5424175a013051874f
   ReactCommon: ac616b2f169c57d56bd4b1a02f8a2dbb0b395722
-  ReactNativeDependencies: a79f93bdc7f0de496dbc2aa051e665dad1763ab0
+  ReactNativeDependencies: 97ee09ffb32e629f30549f67a3ebbf71a4dff077
   RNGestureHandler: f080747d181c86d346827ba389209e1afb528628
   RNReanimated: 72296a949b2e629ed59666d445fa7ac9ab066571
-  RNScreens: 8c846783cda52889bbf9c69e71ff0f2ed1187743
+  RNScreens: 3475d50b4a24a1412586be0d37876f7443ef1730
   RNWorklets: ec060e76f9d7b7786d83a233e310b2ec778fb3eb
   Yoga: b8206e6746bd28c028572774cece66d5348240c1
 

FabricExample/metro.config.js

@@ -9,7 +9,8 @@ const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
 
 const fs = require('fs');
 const path = require('path');
-const exclusionList = require('metro-config/private/defaults/exclusionList').default;
+const exclusionList =
+  require('metro-config/private/defaults/exclusionList').default;
 const escape = require('escape-string-regexp');
 
 const libPackage = require('../package.json');
@@ -21,9 +22,11 @@ const appPackage = require('./package.json');
  * in `react-navigation` submodule & causes runtime issues.
  */
 function reactNavigationOptionalModuleFilter(module) {
-  return module in appPackage.dependencies === true ||
+  return (
+    module in appPackage.dependencies === true ||
     module in libPackage.devDependencies === true ||
-    module in libPackage.dependencies === true;
+    module in libPackage.dependencies === true
+  );
 }
 
 /**
@@ -32,8 +35,7 @@ function reactNavigationOptionalModuleFilter(module) {
  */
 function blockListProvider(modules, nodeModulesDir) {
   return modules.map(
-    m =>
-      new RegExp(`^${escape(path.join(nodeModulesDir, m))}\\/.*$`),
+    m => new RegExp(`^${escape(path.join(nodeModulesDir, m))}\\/.*$`),
   );
 }
 
@@ -55,7 +57,6 @@ const modules = [
   ...Object.keys(libPackage.peerDependencies),
 ];
 
-
 // Currently each `@react-navigation` package has `src/index.tsx`.
 const reactNavigationIndexExts = ['tsx', 'ts', 'js', 'jsx'];
 
@@ -66,14 +67,18 @@ const reactNavigationDuplicatedModules = [
   'react-native',
   'react-native-screens',
   'react-dom', // TODO: Consider whether this won't conflict, especially that RN 78 uses React 19 & react-navigation still uses React 18.
-].concat([
-  'react-native-safe-area-context',
-  'react-native-gesture-handler',
-].filter(reactNavigationOptionalModuleFilter));
+].concat(
+  ['react-native-safe-area-context', 'react-native-gesture-handler'].filter(
+    reactNavigationOptionalModuleFilter,
+  ),
+);
 
 const appNodeModules = path.join(appDir, 'node_modules');
 const libNodeModules = path.join(libRootDir, 'node_modules');
-const reactNavigationNodeModules = path.join(reactNavigationDir, 'node_modules');
+const reactNavigationNodeModules = path.join(
+  reactNavigationDir,
+  'node_modules',
+);
 
 const config = {
   projectRoot: appDir,
@@ -84,7 +89,14 @@ const config = {
   resolver: {
     resolverMainFields: ['react-native', 'browser', 'main'],
 
-    blockList: exclusionList(blockListProvider(modules, libNodeModules).concat(blockListProvider(reactNavigationDuplicatedModules, reactNavigationNodeModules))),
+    blockList: exclusionList(
+      blockListProvider(modules, libNodeModules).concat(
+        blockListProvider(
+          reactNavigationDuplicatedModules,
+          reactNavigationNodeModules,
+        ),
+      ),
+    ),
 
     extraNodeModules: modules.reduce((acc, name) => {
       acc[name] = path.join(__dirname, 'node_modules', name);
@@ -108,15 +120,25 @@ const config = {
     // Project node modules + directory where `react-native-screens` repo lives in + react navigation node modules.
     // These are consulted in order of definition.
     // TODO: make it so this does not depend on whether the user renamed the repo or not...
-    nodeModulesPaths: [appNodeModules, path.join(appDir, '../../'), libNodeModules, reactNavigationNodeModules],
+    nodeModulesPaths: [
+      appNodeModules,
+      path.join(appDir, '../../'),
+      libNodeModules,
+      reactNavigationNodeModules,
+    ],
 
     resolveRequest: (context, moduleName, platform) => {
       // We want to enforce that in case of react navigation the `src` files
       // are transformed & bundled instead of the pretransformed ones in `@react-navigation/xxx/lib` directory.
       if (moduleName.startsWith('@react-navigation/')) {
         for (const fileExt of reactNavigationIndexExts) {
           // App node modules contain symlink to react-navigation submodule.
-          const moduleEntryPoint = path.join(appNodeModules, moduleName, 'src', `index.${fileExt}`);
+          const moduleEntryPoint = path.join(
+            appNodeModules,
+            moduleName,
+            'src',
+            `index.${fileExt}`,
+          );
           if (fs.existsSync(moduleEntryPoint)) {
             return {
               filePath: moduleEntryPoint,
@@ -146,4 +168,3 @@ const config = {
 };
 
 module.exports = mergeConfig(getDefaultConfig(__dirname), config);
-

android/src/main/java/com/swmansion/rnscreens/RNScreensPackage.kt

@@ -7,6 +7,7 @@ import com.facebook.react.module.annotations.ReactModuleList
 import com.facebook.react.module.model.ReactModuleInfo
 import com.facebook.react.module.model.ReactModuleInfoProvider
 import com.facebook.react.uimanager.ViewManager
+import com.swmansion.rnscreens.gamma.scrollviewmarker.ScrollViewMarkerViewManager
 import com.swmansion.rnscreens.gamma.stack.host.StackHostViewManager
 import com.swmansion.rnscreens.gamma.stack.screen.StackScreenViewManager
 import com.swmansion.rnscreens.gamma.tabs.host.TabsHostViewManager
@@ -55,6 +56,7 @@ class RNScreensPackage : BaseReactPackage() {
             SafeAreaViewManager(),
             StackHostViewManager(),
             StackScreenViewManager(),
+            ScrollViewMarkerViewManager(),
         )
     }
 

android/src/main/java/com/swmansion/rnscreens/gamma/helpers/UIManagerHelperExt.kt

@@ -0,0 +1,11 @@
+package com.swmansion.rnscreens.gamma.helpers
+
+import com.facebook.react.bridge.UIManager
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.UIManagerHelper
+import com.facebook.react.uimanager.common.UIManagerType
+
+internal fun UIManagerHelper.getFabricUIManagerNotNull(reactContext: ThemedReactContext): UIManager =
+    checkNotNull(this.getUIManager(reactContext, UIManagerType.FABRIC)) {
+        "[RNScreens] UIManager must not be null"
+    }

android/src/main/java/com/swmansion/rnscreens/gamma/scrollviewmarker/ScrollViewMarker.kt

@@ -0,0 +1,91 @@
+package com.swmansion.rnscreens.gamma.scrollviewmarker
+
+import android.annotation.SuppressLint
+import android.view.ViewGroup
+import android.widget.ScrollView
+import androidx.core.view.children
+import androidx.core.widget.NestedScrollView
+import com.facebook.react.bridge.UIManager
+import com.facebook.react.bridge.UIManagerListener
+import com.facebook.react.common.annotations.UnstableReactNativeAPI
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.UIManagerHelper
+import com.facebook.react.views.view.ReactViewGroup
+import com.swmansion.rnscreens.gamma.helpers.getFabricUIManagerNotNull
+
+@OptIn(UnstableReactNativeAPI::class)
+@SuppressLint("ViewConstructor") // Should never be inflated / restored
+class ScrollViewMarker(
+    private val reactContext: ThemedReactContext,
+) : ReactViewGroup(reactContext),
+    UIManagerListener {
+    init {
+        // We're adding ourselves during a batch, therefore we expect to receive its finalization callbacks
+        UIManagerHelper.getFabricUIManagerNotNull(reactContext).addUIManagerEventListener(this)
+    }
+
+    private var hasAttemptedRegistration: Boolean = false
+
+    /**
+     * Currently we discover only ScrollView or NestedScrollView.
+     * It'll crash in case scroll view detection fails.
+     *
+     * Call it only after the children have been already attached and not yet detached.
+     *
+     * This method intentionally ignores horizontal scroll views - we don't have support for "edge effects"
+     * on Android nor we have any other use for them.
+     */
+    private fun findScrollView(): ViewGroup {
+        val childScrollView =
+            checkNotNull(children.find { childView -> childView is ScrollView || childView is NestedScrollView }) {
+                "[RNScreens] Failed to find supported type of ScrollView in children of ScrollViewMarker"
+            }
+
+        return childScrollView as ViewGroup
+    }
+
+    private fun findFirstSeekingAncestor(): ScrollViewSeeking? {
+        var currentView = parent
+
+        while (currentView != null) {
+            if (currentView is ScrollViewSeeking) {
+                return currentView
+            }
+            currentView = currentView.parent
+        }
+
+        return null
+    }
+
+    private fun registerWithSeekingAncestor() {
+        val scrollView = findScrollView()
+        findFirstSeekingAncestor()?.registerScrollView(this, scrollView)
+    }
+
+    private fun maybeRegisterWithSeekingAncestor() {
+        if (hasAttemptedRegistration) {
+            return
+        }
+
+        registerWithSeekingAncestor()
+        hasAttemptedRegistration = true
+    }
+
+    // UIManagerListener
+
+    override fun didMountItems(uiManager: UIManager) {
+        maybeRegisterWithSeekingAncestor()
+    }
+
+    override fun willDispatchViewUpdates(uiManager: UIManager) = Unit
+
+    override fun willMountItems(uiManager: UIManager) = Unit
+
+    override fun didDispatchMountItems(uiManager: UIManager) = Unit
+
+    override fun didScheduleMountItems(uiManager: UIManager) = Unit
+
+    internal fun onViewManagerDropViewInstance() {
+        UIManagerHelper.getFabricUIManagerNotNull(reactContext).removeUIManagerEventListener(this)
+    }
+}

android/src/main/java/com/swmansion/rnscreens/gamma/scrollviewmarker/ScrollViewMarkerViewManager.kt

@@ -0,0 +1,55 @@
+package com.swmansion.rnscreens.gamma.scrollviewmarker
+
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.ViewGroupManager
+import com.facebook.react.uimanager.ViewManagerDelegate
+import com.facebook.react.viewmanagers.RNSScrollViewMarkerManagerDelegate
+import com.facebook.react.viewmanagers.RNSScrollViewMarkerManagerInterface
+
+@ReactModule(name = ScrollViewMarkerViewManager.REACT_CLASS)
+class ScrollViewMarkerViewManager :
+    ViewGroupManager<ScrollViewMarker>(),
+    RNSScrollViewMarkerManagerInterface<ScrollViewMarker> {
+    private val delegate: ViewManagerDelegate<ScrollViewMarker> =
+        RNSScrollViewMarkerManagerDelegate<ScrollViewMarker, ScrollViewMarkerViewManager>(this)
+
+    override fun getName() = REACT_CLASS
+
+    override fun getDelegate() = delegate
+
+    override fun createViewInstance(reactContext: ThemedReactContext): ScrollViewMarker = ScrollViewMarker(reactContext)
+
+    override fun onDropViewInstance(view: ScrollViewMarker) {
+        super.onDropViewInstance(view)
+        view.onViewManagerDropViewInstance()
+    }
+
+    // iOS only
+    override fun setLeftScrollEdgeEffect(
+        view: ScrollViewMarker?,
+        value: String?,
+    ) = Unit
+
+    // iOS only
+    override fun setTopScrollEdgeEffect(
+        view: ScrollViewMarker?,
+        value: String?,
+    ) = Unit
+
+    // iOS only
+    override fun setRightScrollEdgeEffect(
+        view: ScrollViewMarker?,
+        value: String?,
+    ) = Unit
+
+    // iOS only
+    override fun setBottomScrollEdgeEffect(
+        view: ScrollViewMarker?,
+        value: String?,
+    ) = Unit
+
+    companion object {
+        const val REACT_CLASS = "RNSScrollViewMarker"
+    }
+}

android/src/main/java/com/swmansion/rnscreens/gamma/scrollviewmarker/ScrollViewSeeking.kt

@@ -0,0 +1,13 @@
+package com.swmansion.rnscreens.gamma.scrollviewmarker
+
+import android.view.ViewGroup
+
+internal interface ScrollViewSeeking {
+    // scrollView is a ViewGroup, because there is no universal ScrollView component on Android.
+    // It might a be ScrollView, NestedScrollView (different inheritance hierarchies) or any other
+    // ViewGroup that implements appropriate scrolling interfaces.
+    fun registerScrollView(
+        marker: ScrollViewMarker,
+        scrollView: ViewGroup,
+    )
+}

apps/src/shared/utils/color-generator.ts

@@ -0,0 +1,21 @@
+import Colors from '../styling/Colors';
+
+let GLOBAL_NEXT_COLOR_ID = 0;
+
+export function generateNextColor() {
+  const colors = [
+    Colors.BlueDark100,
+    Colors.GreenDark100,
+    Colors.RedDark100,
+    Colors.YellowDark100,
+    Colors.PurpleDark100,
+    Colors.BlueLight100,
+    Colors.GreenLight100,
+    Colors.RedLight100,
+    Colors.YellowLight100,
+    Colors.PurpleLight100,
+  ];
+  const index = GLOBAL_NEXT_COLOR_ID;
+  GLOBAL_NEXT_COLOR_ID += 1;
+  return colors[index % colors.length];
+}

apps/src/tests/single-feature-tests/scroll-view-marker/index.ts

@@ -0,0 +1,10 @@
+import { ScenarioGroup } from '../../shared/helpers';
+import TestSvmConfiguresScrollView from './test-svm-configures-scroll-view';
+
+const ScrollViewMarkerScenarioGroup: ScenarioGroup = {
+  name: 'ScrollViewMarker scenarios',
+  details: 'Scenarios related to ScrollViewMarker component',
+  scenarios: [TestSvmConfiguresScrollView],
+};
+
+export default ScrollViewMarkerScenarioGroup;