Improve documentation

zoontek · zoontek · commit e4cfad4a74aa · 2024-12-21T11:03:53.000+01:00
diff --git a/README.md b/README.md
@@ -23,19 +23,19 @@ It is supporting the **latest version**, and the **two previous minor series**.
 
 ## Motivations
 
-### Android 15
-
-Recently, Google introduced a significant change: apps targeting SDK 35 will have edge-to-edge display [enforced by default](https://developer.android.com/about/versions/15/behavior-changes-15#edge-to-edge) on Android 15+. Google is _likely_ to mandate that app updates on the Play Store target SDK 35 starting on August 31, 2025. This assumption is based on the [previous years' requirements following a similar timeline](https://support.google.com/googleplay/android-developer/answer/11926878?sjid=11853000253346477363-EU#zippy=%2Care-there-any-exceptions-for-existing-apps-targeting-api-or-below:~:text=App%20update%20requirements).
+### Consistency
 
-Currently, new React Native projects target SDK 34.
+iOS has long used edge-to-edge displays, so adopting this design across all platforms ensures a consistent user experience. It also simplifies managing safe areas, eliminating the need for special cases specific to Android.
 
 ### Immersive mode
 
 [Immersive mode](https://developer.android.com/develop/ui/views/layout/immersive) allows you to hide the status and navigation bars, making it ideal for full-screen experiences. Currently, the built-in [`StatusBar`](https://reactnative.dev/docs/statusbar) component uses [`FLAG_FULLSCREEN`](https://developer.android.com/reference/android/view/WindowManager.LayoutParams#FLAG_FULLSCREEN), a flag that has been deprecated since Android 11.
 
-### Consistency
+### Android 15
 
-iOS has long used edge-to-edge displays, so adopting this design across all platforms ensures a consistent user experience. It also simplifies managing safe areas, eliminating the need for special cases specific to Android.
+Recently, Google introduced a significant change: apps targeting SDK 35 will have edge-to-edge display [enforced by default](https://developer.android.com/about/versions/15/behavior-changes-15#edge-to-edge) on Android 15+. Google is _likely_ to mandate that app updates on the Play Store target SDK 35 starting on August 31, 2025. This assumption is based on the [previous years' requirements following a similar timeline](https://support.google.com/googleplay/android-developer/answer/11926878?sjid=11853000253346477363-EU#zippy=%2Care-there-any-exceptions-for-existing-apps-targeting-api-or-below:~:text=App%20update%20requirements).
+
+Currently, new React Native projects target SDK 34.
 
 ## Installation
 
@@ -87,76 +87,23 @@ Edit your `android/app/src/main/res/values/styles.xml` file to inherit from one
 
 ## Considerations
 
-### Third-party libraries
-
-Many libraries expose options that you can set to account for the transparency of status and navigation bars. For example, the [`useHideAnimation`](https://github.com/zoontek/react-native-bootsplash?tab=readme-ov-file#usehideanimation) hook in `react-native-bootsplash` has `statusBarTranslucent` and `navigationBarTranslucent` options, the [`useAnimatedKeyboard`](https://docs.swmansion.com/react-native-reanimated/docs/device/useAnimatedKeyboard) in `react-native-reanimated` has an `isStatusBarTranslucentAndroid` option, etc.
-
-> [!IMPORTANT]  
-> Until third-party libraries officially add support for `react-native-edge-to-edge` to set these options automatically, you may need to adjust these options to prevent interference with the library.
-
-For library authors, we provide a lightweight package called `react-native-is-edge-to-edge` (note the `-is-`!), which checks whether `react-native-edge-to-edge` is installed, making it easy to update your library accordingly:
-
-```ts
-import {
-  controlEdgeToEdgeValues,
-  isEdgeToEdge,
-} from "react-native-is-edge-to-edge";
-
-const EDGE_TO_EDGE = isEdgeToEdge();
-
-function MyAwesomeLibraryComponent({
-  statusBarTranslucent,
-  navigationBarTranslucent,
-}) {
-  if (__DEV__) {
-    // warn the user once about unnecessary defined values
-    controlEdgeToEdgeValues({
-      statusBarTranslucent,
-      navigationBarTranslucent,
-    });
-  }
-
-  return (
-    <MyAwesomeLibraryNativeComponent
-      statusBarTranslucent={EDGE_TO_EDGE || statusBarTranslucent}
-      navigationBarTranslucent={EDGE_TO_EDGE || navigationBarTranslucent}
-      // …
-    />
-  );
-}
-```
-
-If you want to check for the library's presence on the native side to bypass certain parts of your code, consider using this small utility:
-
-```kotlin
-object EdgeToEdge {
-  // we cannot detect edge-to-edge, but we can detect react-native-edge-to-edge install
-  val ENABLED: Boolean = try {
-      Class.forName("com.zoontek.rnedgetoedge.EdgeToEdgePackage")
-      true
-    } catch (exception: ClassNotFoundException) {
-      false
-    }
-}
-```
-
-### Keyboard management
-
-Enabling edge-to-edge display disrupts basic Android keyboard management (`android:windowSoftInputMode="adjustResize"`), requiring an alternative solution. While [`KeyboardAvoidingView`](https://reactnative.dev/docs/keyboardavoidingview) is a viable option, we recommend using [react-native-keyboard-controller](https://github.com/kirillzyusko/react-native-keyboard-controller) for its enhanced capabilities.
-
 ### Safe area management
 
 Effective safe area management is essential to prevent content from being displayed behind transparent system bars. To achieve this, we highly recommend using [`react-native-safe-area-context`](https://github.com/th3rdwave/react-native-safe-area-context), a well-known and trusted library.
 
 ### Modal component quirks
 
-Status bar management has never worked effectively with the built-in [`Modal`](https://reactnative.dev/docs/modal) component (as it creates a `Dialog` with a `Window` instance distinct from `MainActivity`). A `statusBarTranslucent` prop was introduced, but it is insufficient because there is no equivalent for the navigation bar. Instead, we recommend using the [react-navigation modals](https://reactnavigation.org/docs/modal), which do not suffer from this issue, as they utilize [react-native-screens](https://docs.swmansion.com/react-native-screens) and `Fragment` behind the scenes.
+Edge-to-edge support for the built-in [`Modal`](https://reactnative.dev/docs/modal) component will be available in [React Native 0.77](https://github.com/facebook/react-native/pull/47254). Meanwhile, we recommend using the [react-navigation modals](https://reactnavigation.org/docs/modal), or the [`expo-router` modal screens](https://docs.expo.dev/router/advanced/modals/#modal-screen-using-expo-router).
+
+### Keyboard management
+
+Enabling edge-to-edge display disrupts Android keyboard management (`android:windowSoftInputMode="adjustResize"`), requiring an alternative solution. While [`KeyboardAvoidingView`](https://reactnative.dev/docs/keyboardavoidingview) is a viable option, we recommend using [react-native-keyboard-controller](https://github.com/kirillzyusko/react-native-keyboard-controller) for its enhanced capabilities.
 
 ## API
 
 ### `<SystemBars />`
 
-A component for managing your app's system bars. This replace [`StatusBar`](https://reactnative.dev/docs/statusbar), [`expo-status-bar`](https://docs.expo.dev/versions/latest/sdk/status-bar) and [`expo-navigation-bar`](https://docs.expo.dev/versions/latest/sdk/navigation-bar/) (that uses a lot of now [deprecated APIs](https://developer.android.com/about/versions/15/behavior-changes-15#deprecated-apis)).
+A component for managing your app's system bars. Replace all occurrences of [`StatusBar`](https://reactnative.dev/docs/statusbar), [`expo-status-bar`](https://docs.expo.dev/versions/latest/sdk/status-bar) and [`expo-navigation-bar`](https://docs.expo.dev/versions/latest/sdk/navigation-bar/) with it (they uses a lot of now [deprecated APIs](https://developer.android.com/about/versions/15/behavior-changes-15#deprecated-apis) and interfere with edge-to-edge).
 
 ```tsx
 import { SystemBars } from "react-native-edge-to-edge";
@@ -199,3 +146,56 @@ const entry: SystemBarsEntry = SystemBars.replaceStackEntry(
   props /*: SystemBarsProps */,
 );
 ```
+
+## Third-party
+
+Many libraries expose options that you can set to account for the transparency of status and navigation bars. For example, the [`useHideAnimation`](https://github.com/zoontek/react-native-bootsplash?tab=readme-ov-file#usehideanimation) hook in `react-native-bootsplash` has `statusBarTranslucent` and `navigationBarTranslucent` options, the [`useAnimatedKeyboard`](https://docs.swmansion.com/react-native-reanimated/docs/device/useAnimatedKeyboard) in `react-native-reanimated` has an `isStatusBarTranslucentAndroid` option, etc.
+
+> [!IMPORTANT]  
+> Until third-party libraries officially add support for `react-native-edge-to-edge` to set these options automatically, you may need to adjust these options to prevent interference with the library.
+
+For library authors, we provide a lightweight package called `react-native-is-edge-to-edge` (note the `-is-`!), which checks whether `react-native-edge-to-edge` is installed, making it easy to update your library accordingly:
+
+```ts
+import {
+  controlEdgeToEdgeValues,
+  isEdgeToEdge,
+} from "react-native-is-edge-to-edge";
+
+const EDGE_TO_EDGE = isEdgeToEdge();
+
+function MyAwesomeLibraryComponent({
+  statusBarTranslucent,
+  navigationBarTranslucent,
+}) {
+  if (__DEV__) {
+    // warn the user once about unnecessary defined values
+    controlEdgeToEdgeValues({
+      statusBarTranslucent,
+      navigationBarTranslucent,
+    });
+  }
+
+  return (
+    <MyAwesomeLibraryNativeComponent
+      statusBarTranslucent={EDGE_TO_EDGE || statusBarTranslucent}
+      navigationBarTranslucent={EDGE_TO_EDGE || navigationBarTranslucent}
+      // …
+    />
+  );
+}
+```
+
+If you want to check for the library's presence on the native side to bypass certain parts of your code, consider using this small utility:
+
+```kotlin
+object EdgeToEdge {
+  // we cannot detect edge-to-edge, but we can detect react-native-edge-to-edge install
+  val ENABLED: Boolean = try {
+      Class.forName("com.zoontek.rnedgetoedge.EdgeToEdgePackage")
+      true
+    } catch (exception: ClassNotFoundException) {
+      false
+    }
+}
+```
