fix(Android): add custom fragment factory & modify library installation steps to prevent on-restoration crashes (#3089)

## Description

<!--
Description and motivation for this PR.
Include Fixes #<number> if this is fixing some issue.

Fixes # .
-->

This PR replaces the current workaround for crashes connected to the
configuration changes on Android. The previous fix required disabling
passing saved instance state in Activity onCreate - `onCreate(null)`.
Such a solution generates a problem with state persistence on the native
side of brownfield applications. Because of that, we decided to replace
it with a custom fragment factory that will limit the scope of the
solution and fix the problem directly only on the React Native side. All
fragments connected to the RN Screens package will be replaced with
self-destructing ones, which will prevent Android from recreating the
Fragment after the configuration change. We will leave this
responsibility for React Native. Thanks to that, there won't be any
conflict between the Android system and React Native, and we will
prevent the app from crashing or any other app appearance-related
issues.

Credits to @bojanlozanovski77 for bringing up the idea in
#2917

Fixes:
#17

## Changes

<!--
Please describe things you've changed here, make a **high level**
overview, if change is simple you can omit this section.

For example:

- Updated `about.md` docs

-->

- Created a custom fragment factory (RNScreensFragmentFactory.kt) that
won't instantiate RN Screens fragments
- Created self-destructing fragments (NoOpFragment.kt) that will be
instanciated by the RNScreensFragmentFactory, to prevent the conflict
that crashes the app
- Updated installation steps in library README
- Applied the fix in `MainActivity` files of `FabricExample` and
`Example` apps

<!--

## Screenshots / GIFs

Here you can add screenshots / GIFs documenting your change.

You can add before / after section if you're changing some behavior.

### Before

### After

-->

## Test code and steps to reproduce

<!--
Please include code that can be used to test this change and short
description how this example should work.
This snippet should be as minimal as possible and ready to be pasted
into editor (don't exclude exports or remove "not important" parts of
reproduction example)
-->
1. Remove ignoring config changes in `AndroidManifest.xml` file 
```diff
<activity
    android:name=".MainActivity"
    android:label="@string/app_name"
-   android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"
    android:launchMode="singleTask"
    ...
```
2. Launch the example app
3. Verify if the app isn't crashing when causing different types of
configuration changes on Android. For example:
	- Orientation change on devices ≥600dp with portrait lock
	- Opening/closing foldables or flip phones  
	- Split/Multi-Window mode  
	- Desktop windowing on tablets  
	- Launching external activities (e.g. system Photo Picker)  
- Changing accessibility settings, permissions, system fonts,
wallpapers, or language

## Checklist

- [X] Included code example that can be used to test this change
- [X] Updated TS types
- [X] Updated documentation: <!-- For adding new props to native-stack
-->
- [X]
https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
- [X]
https://github.com/software-mansion/react-native-screens/blob/main/native-stack/README.md
- [X]
https://github.com/software-mansion/react-native-screens/blob/main/src/types.tsx
- [X]
https://github.com/software-mansion/react-native-screens/blob/main/src/native-stack/types.tsx
- [X] Ensured that CI passes

---------

Co-authored-by: bojanlozanovski77 <[email protected]>
Co-authored-by: Kacper Kafara <[email protected]>

Author: 3 people

Example/android/app/src/main/java/com/swmansion/rnscreens/example/MainActivity.kt

@@ -5,6 +5,7 @@ import com.facebook.react.ReactActivity
 import com.facebook.react.ReactActivityDelegate
 import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
 import com.facebook.react.defaults.DefaultReactActivityDelegate
+import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory
 
 class MainActivity : ReactActivity() {
 
@@ -22,6 +23,7 @@ class MainActivity : ReactActivity() {
       DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
 
   override fun onCreate(savedInstanceState: Bundle?) {
-    super.onCreate(null)
+    supportFragmentManager.fragmentFactory = RNScreensFragmentFactory()
+    super.onCreate(savedInstanceState)
   }
 }

FabricExample/android/app/src/main/java/com/fabricexample/MainActivity.kt

@@ -1,9 +1,11 @@
 package com.fabricexample
 
+import android.os.Bundle
 import com.facebook.react.ReactActivity
 import com.facebook.react.ReactActivityDelegate
 import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
 import com.facebook.react.defaults.DefaultReactActivityDelegate
+import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory
 
 class MainActivity : ReactActivity() {
 
@@ -19,4 +21,9 @@ class MainActivity : ReactActivity() {
    */
   override fun createReactActivityDelegate(): ReactActivityDelegate =
       DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    supportFragmentManager.fragmentFactory = RNScreensFragmentFactory()
+    super.onCreate(savedInstanceState)
+  }
 }

README.md

@@ -35,6 +35,7 @@ Please note that the override code should not be placed inside `MainActivityDele
 
 ```java
 import android.os.Bundle;
+import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory;
 
 public class MainActivity extends ReactActivity {
 
@@ -43,7 +44,8 @@ public class MainActivity extends ReactActivity {
     //react-native-screens override
     @Override
     protected void onCreate(Bundle savedInstanceState) {
-        super.onCreate(null);
+        getSupportFragmentManager().setFragmentFactory(new RNScreensFragmentFactory());
+        super.onCreate(savedInstanceState);
     }
 
     public static class MainActivityDelegate extends ReactActivityDelegate {
@@ -59,13 +61,15 @@ public class MainActivity extends ReactActivity {
 
 ```kotlin
 import android.os.Bundle;
+import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory;
 
 class MainActivity: ReactActivity() {
 
     //...code
 
     //react-native-screens override
     override fun onCreate(savedInstanceState: Bundle?) {
+      supportFragmentManager.fragmentFactory = RNScreensFragmentFactory()
       super.onCreate(null);
     }
 }

android/src/main/java/com/swmansion/rnscreens/fragment/restoration/AutoRemovingFragment.kt

@@ -0,0 +1,38 @@
+package com.swmansion.rnscreens.fragment.restoration
+
+import android.os.Bundle
+import android.view.LayoutInflater
+import android.view.View
+import android.view.ViewGroup
+import androidx.fragment.app.Fragment
+
+/**
+* This class serves as a workaround to https://github.com/software-mansion/react-native-screens/issues/17.
+*
+* This fragment, when attached to the fragment manager & its state is progressed
+* to `ON_CREATED`, attempts to detach itself from the parent fragment manager
+* as soon as possible.
+*
+* Instances of this type should be created in place of regular screen fragments
+* when Android restores fragments after activity / application restart.
+* If done so, it's behaviour can prevent duplicated fragment instances,
+* as React will render new ones on activity restart.
+*/
+class AutoRemovingFragment : Fragment() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        // This is the first moment where we have access to non-null parent fragment manager,
+        // so that we can remove the fragment from the hierarchy.
+        parentFragmentManager
+            .beginTransaction()
+            .remove(this)
+            .commitAllowingStateLoss()
+    }
+
+    override fun onCreateView(
+        inflater: LayoutInflater,
+        container: ViewGroup?,
+        savedInstanceState: Bundle?,
+    ): View? = null
+}

android/src/main/java/com/swmansion/rnscreens/fragment/restoration/RNScreensFragmentFactory.kt

@@ -0,0 +1,13 @@
+package com.swmansion.rnscreens.fragment.restoration
+
+class RNScreensFragmentFactory : androidx.fragment.app.FragmentFactory() {
+    override fun instantiate(
+        classLoader: ClassLoader,
+        className: String,
+    ): androidx.fragment.app.Fragment =
+        if (className.startsWith(com.swmansion.rnscreens.BuildConfig.LIBRARY_PACKAGE_NAME)) {
+            AutoRemovingFragment()
+        } else {
+            super.instantiate(classLoader, className)
+        }
+}