Document formSheet props and limitiations

Author: kligarski

versioned_docs/version-7.x/native-stack-navigator.md

@@ -869,6 +869,142 @@ Supported values:
    <source src="/assets/7.x/native-stack/presentation-formSheet.mp4" />
   </video>
 
+:::warning
+
+Due to architectural problems (lack of support of synchronous layout on UI thread by RN), `presentation: 'formSheet'` on Android has limited support for `flex: 1`. The tradeoff is necessary to prevent "sheet flickering" problem. There are also some problems with getting nested ScrollViews to work properly.
+
+Currently, you should avoid using `flex: 1` on top level content container you pass to the sheet.
+
+When there is less content than max screen height, you might end up with "truncated sheet" problem. The workaround is to set `backgroundColor` in the `contentStyle` prop of the given screen.
+:::
+
+#### `sheetAllowedDetents`
+
+:::note
+
+Works only when `presentation` is set to `formSheet`.
+
+:::
+
+Describes heights where a sheet can rest.
+
+Supported values:
+
+- `fitToContents` - intents to set the sheet height to the height of its contents.
+- Array of fractions, e.g. `[0.25, 0.5, 0.75]`:
+  - Heights should be described as fraction (a number from `[0, 1]` interval) of screen height / maximum detent height.
+  - The array **must** be sorted in ascending order. This invariant is verified only in developement mode, where violation results in error.
+  - iOS accepts any number of detents, while **Android is limited to three** - any surplus values, beside first three are ignored.
+
+Defaults to `[1.0]`.
+
+Only supported on Android and iOS.
+
+#### `sheetElevation`
+
+:::note
+
+Works only when `presentation` is set to `formSheet`.
+
+:::
+
+Integer value describing elevation of the sheet, impacting shadow on the top edge of the sheet.
+
+Not dynamic - changing it after the component is rendered won't have an effect.
+
+Defaults to `24`.
+
+Only supported on Android.
+
+#### `sheetExpandsWhenScrolledToEdge`
+
+:::note
+
+Works only when `presentation` is set to `formSheet`.
+
+:::
+
+Whether the sheet should expand to larger detent when scrolling.
+
+Defaults to `true`.
+
+Only supported on iOS.
+
+:::warning
+
+Please note that for this interaction to work, the ScrollView must be "first-child-chain" descendant of the Screen component. This is a platform defined behaviour.
+
+:::
+
+#### `sheetCornerRadius`
+
+:::note
+
+Works only when `presentation` is set to `formSheet`.
+
+:::
+
+The corner radius that the sheet will try to render with.
+
+If set to non-negative value it will try to render sheet with provided radius, else it will apply system default.
+
+If left unset, system default is used.
+
+Only supported on Android and iOS.
+
+#### `sheetInitialDetentIndex`
+
+:::note
+
+Works only when `presentation` is set to `formSheet`.
+
+:::
+
+**Index** of the detent the sheet should expand to after being opened.
+
+If the specified index is out of bounds of `sheetAllowedDetents` array, in dev environment more errors will be thrown, in production the value will be reset to default value.
+
+Additionaly there is `last` value available, when set the sheet will expand initially to last (largest) detent.
+
+Defaults to `0` - which represents first detent in the detents array.
+
+Only supported on Android and iOS.
+
+#### `sheetGrabberVisible`
+
+:::note
+
+Works only when `presentation` is set to `formSheet`.
+
+:::
+
+Boolean indicating whether the sheet shows a grabber at the top.
+
+Defaults to `false`.
+
+Only supported on iOS.
+
+#### `sheetLargestUndimmedDetentIndex`
+
+:::note
+
+Works only when `presentation` is set to `formSheet`.
+
+:::
+
+The largest sheet detent for which a view underneath won't be dimmed.
+
+This prop can be set to an number, which indicates index of detent in `sheetAllowedDetents` array for which there won't be a dimming view beneath the sheet.
+
+Additionaly there are following options available:
+
+- `none` - there will be dimming view for all detents levels,
+- `last` - there won't be a dimming view for any detent level.
+
+Defaults to `none`, indicating that the dimming view should be always present.
+
+Only supported on Android and iOS.
+
 #### `orientation`
 
 The display orientation to use for the screen.