feat: expose none & largest values for sheetLargestUndimmedDetent prop

apps/src/tests/Test1649/state.tsx

@@ -6,7 +6,7 @@ export const sheetInitialOptions: SheetOptions = {
   sheetAllowedDetents: [0.4, 0.6, 0.9],
   // sheetAllowedDetents: [0.6],
   // sheetAllowedDetents: 'fitToContents',
-  sheetLargestUndimmedDetent: 2,
+  sheetLargestUndimmedDetent: 'none',
   sheetGrabberVisible: false,
   sheetCornerRadius: 24,
   sheetExpandsWhenScrolledToEdge: true,

guides/GUIDE_FOR_LIBRARY_AUTHORS.md

@@ -191,18 +191,23 @@ Boolean indicating whether the sheet shows a grabber at the top.
 Works only when `stackPresentation` is set to `formSheet`.
 Defaults to `false`.
 
-### `sheetLargestUndimmedDetent` (iOS only)
+### `sheetLargestUndimmedDetent`
 
 The largest sheet detent for which a view underneath won't be dimmed.
-Works only when `presentation` is set to `formSheet`.
+Works only when `stackPresentation` is set to `formSheet`.
 
 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.
 
-There also legacy & **deprecated** prop values available, which work in tandem with
-corresponding legacy proop values for `sheetAllowedDetents` prop.
+Additionaly there are following options available:
+
+* `none` - there will be dimming view for all detents levels,
+* `largest` - there won't be a dimming view for any detent level.
+
+There also legacy & **deprecated** prop values available: `medium`, `large` (don't confuse with `largest`), `all`, which work in tandem with
+corresponding legacy prop values for `sheetAllowedDetents` prop.
 
-Defaults to `-1`, indicating that the dimming view should be always present.
+Defaults to `none`, indicating that the dimming view should be always present.
 
 ### `stackAnimation`
 

native-stack/README.md

@@ -304,10 +304,15 @@ Works only when `stackPresentation` is set to `formSheet`.
 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.
 
-There also legacy & **deprecated** prop values available, which work in tandem with
+Additionaly there are following options available:
+
+* `none` - there will be dimming view for all detents levels,
+* `largest` - there won't be a dimming view for any detent level.
+
+There also legacy & **deprecated** prop values available: `medium`, `large` (don't confuse with `largest`), `all`, which work in tandem with
 corresponding legacy prop values for `sheetAllowedDetents` prop.
 
-Defaults to `-1`, indicating that the dimming view should be always present.
+Defaults to `none`, indicating that the dimming view should be always present.
 
 #### `stackAnimation`
 

src/components/Screen.tsx

@@ -49,6 +49,9 @@ const SHEET_COMPAT_LARGE = [1.0];
 const SHEET_COMPAT_MEDIUM = [0.5];
 const SHEET_COMPAT_ALL = [0.5, 1.0];
 
+const SHEET_DIMMED_ALWAYS = -1;
+// const SHEET_DIMMED_NEVER = 9999;
+
 // 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(
@@ -72,18 +75,21 @@ function resolveSheetAllowedDetents(
 
 function resolveSheetLargestUndimmedDetent(
   lud: ScreenProps['sheetLargestUndimmedDetent'],
+  largestDetentIndex: number,
 ): number {
   if (typeof lud === 'number') {
     return lud;
+  } else if (lud === 'largest') {
+    return largestDetentIndex;
+  } else if (lud === 'none' || lud === 'all') {
+    return SHEET_DIMMED_ALWAYS;
   } else if (lud === 'large') {
     return 1;
   } else if (lud === 'medium') {
     return 0;
-  } else if (lud === 'all') {
-    return -1;
   } else {
     // Safe default, every detent is dimmed
-    return -1;
+    return SHEET_DIMMED_ALWAYS;
   }
 }
 
@@ -112,7 +118,7 @@ export const InnerScreen = React.forwardRef<View, ScreenProps>(
     const {
       // formSheet presentation related props
       sheetAllowedDetents = [1.0],
-      sheetLargestUndimmedDetent = -1,
+      sheetLargestUndimmedDetent = SHEET_DIMMED_ALWAYS,
       sheetGrabberVisible = false,
       sheetCornerRadius = -1.0,
       sheetExpandsWhenScrolledToEdge = true,
@@ -127,7 +133,10 @@ export const InnerScreen = React.forwardRef<View, ScreenProps>(
       const resolvedSheetAllowedDetents =
         resolveSheetAllowedDetents(sheetAllowedDetents);
       const resolvedSheetLargestUndimmedDetent =
-        resolveSheetLargestUndimmedDetent(sheetLargestUndimmedDetent);
+        resolveSheetLargestUndimmedDetent(
+          sheetLargestUndimmedDetent,
+          resolvedSheetAllowedDetents.length - 1,
+        );
       // Due to how Yoga resolves layout, we need to have different components for modal nad non-modal screens
       const AnimatedScreen =
         Platform.OS === 'android' ||

src/index.tsx

@@ -1,6 +1,6 @@
 export * from './types';
 
-/*
+/**
  * Core
  */
 export {
@@ -11,7 +11,7 @@ export {
   shouldUseActivityState,
 } from './core';
 
-/*
+/**
  * RNS Components
  */
 export {
@@ -57,17 +57,17 @@ export {
   NativeScreenContentWrapper,
 } from './components/ScreenContentWrapper';
 
-/*
+/**
  * Modules
  */
 export { default as NativeScreensModule } from './fabric/NativeScreensModule';
 
-/*
+/**
  * Contexts
  */
 export { GHContext } from './native-stack/contexts/GHContext';
 
-/*
+/**
  * Utils
  */
 export {
@@ -76,7 +76,7 @@ export {
   executeNativeBackPress,
 } from './utils';
 
-/*
+/**
  * Hooks
  */
 export { default as useTransitionProgress } from './useTransitionProgress';

src/native-stack/types.tsx

@@ -426,7 +426,15 @@ export type NativeStackNavigationOptions = {
    * 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.
    *
-   * Defaults to `-1`, indicating that the dimming view should be always present.
+   * Additionaly there are following options available:
+   *
+   * * `none` - there will be dimming view for all detents levels,
+   * * `largest` - there won't be a dimming view for any detent level.
+   *
+   * There also legacy & **deprecated** prop values available: `medium`, `large` (don't confuse with `largest`), `all`, which work in tandem with
+   * corresponding legacy prop values for `sheetAllowedDetents` prop.
+   *
+   * Defaults to `none`, indicating that the dimming view should be always present.
    */
   sheetLargestUndimmedDetent?: ScreenProps['sheetLargestUndimmedDetent'];
   /**

src/native-stack/views/NativeStackView.tsx

@@ -195,7 +195,7 @@ const RouteView = ({
     headerShown,
     hideKeyboardOnSwipe,
     homeIndicatorHidden,
-    sheetLargestUndimmedDetent = -1,
+    sheetLargestUndimmedDetent = 'none',
     sheetGrabberVisible = false,
     sheetCornerRadius = -1.0,
     sheetElevation = 24,

src/types.tsx

@@ -351,12 +351,23 @@ export interface ScreenProps extends ViewProps {
    * 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.
    *
-   * There also legacy & **deprecated** prop values available, which work in tandem with
+   * Additionaly there are following options available:
+   *
+   * * `none` - there will be dimming view for all detents levels,
+   * * `largest` - there won't be a dimming view for any detent level.
+   *
+   * There also legacy & **deprecated** prop values available: `medium`, `large` (don't confuse with `largest`), `all`, which work in tandem with
    * corresponding legacy prop values for `sheetAllowedDetents` prop.
    *
-   * Defaults to `-1`, indicating that the dimming view should be always present.
+   * Defaults to `none`, indicating that the dimming view should be always present.
    */
-  sheetLargestUndimmedDetent?: number | 'medium' | 'large' | 'all';
+  sheetLargestUndimmedDetent?:
+    | number
+    | 'none'
+    | 'largest'
+    | 'medium'
+    | 'large'
+    | 'all';
   /**
    * Index of the detent the sheet should expand to after being opened.
    * Works only when `stackPresentation` is set to `formSheet`.