feat: assert that detents array is sorted in dev mode (software-mansi…

…on#2381)

## Description

Verify the invariant specified in `sheetAllowedDetents` prop
documentation in dev mode.

## Test code and steps to reproduce

`Test1649`

## Checklist

- [x] Included code example that can be used to test this change
- [ ] Ensured that CI passes

src/components/Screen.tsx

@@ -52,12 +52,31 @@ const SHEET_COMPAT_ALL = [0.5, 1.0];
 const SHEET_DIMMED_ALWAYS = -1;
 // const SHEET_DIMMED_NEVER = 9999;
 
+function assertDetentsArrayIsSorted(array: number[]) {
+  for (let i = 1; i < array.length; i++) {
+    if (array[i - 1] > array[i]) {
+      throw new Error(
+        '[RNScreens] The detent array is not sorted in ascending order!',
+      );
+    }
+  }
+}
+
 // These exist to transform old 'legacy' values used by the formsheet API to the new API shape.
 // We can get rid of it, once we get rid of support for legacy values: 'large', 'medium', 'all'.
 function resolveSheetAllowedDetents(
   allowedDetentsCompat: ScreenProps['sheetAllowedDetents'],
 ): number[] {
   if (Array.isArray(allowedDetentsCompat)) {
+    if (__DEV__) {
+      assertDetentsArrayIsSorted(allowedDetentsCompat);
+      if (Platform.OS === 'android' && allowedDetentsCompat.length > 3) {
+        console.warn(
+          '[RNScreens] Sheets API on Android do accept only up to 3 values. Any surplus value are ignored.',
+        );
+        allowedDetentsCompat = allowedDetentsCompat.slice(0, 3);
+      }
+    }
     return allowedDetentsCompat;
   } else if (allowedDetentsCompat === 'fitToContents') {
     return SHEET_FIT_TO_CONTENTS;

src/types.tsx

@@ -295,7 +295,10 @@ export interface ScreenProps extends ViewProps {
    * There is also possibility to specify `[-1]` literal array with single element, which intets to set the sheet height
    * to the height of its contents.
    *
-   * Please note that the array **must** be sorted in ascending order.
+   * Please note that the array **must** be sorted in ascending order. This invariant is verified only in developement mode,
+   * where violation results in error.
+   *
+   * **Android is limited to up 3 values in the array** -- any surplus values, beside first three are ignored.
    *
    * There are also legacy & **deprecated** options available:
    *