@lodev09/react-native-true-sheet 4.0.0-beta.24 → 4.0.0-beta.25

package/src/TrueSheet.tsx

@@ -39,6 +39,7 @@ import TrueSheetFooterViewNativeComponent from './fabric/TrueSheetFooterViewNati
 import TrueSheetModule from './specs/NativeTrueSheetModule';
 import { TrueSheetBackground } from './TrueSheetBackground';
 import { normalizeDetentBackground } from './detentBackgrounds';
+import { resolveScrollable } from './scrollable';
 
 import {
   Platform,
@@ -139,9 +140,19 @@ export class TrueSheet
   private static readonly instances: { [name: string]: TrueSheet } = {};
 
   /**
-   * Resolver to be called when mount event is received
+   * All mounted sheets, named or not.
    */
-  private presentationResolver: (() => void) | null = null;
+  private static readonly mountedInstances = new Set<TrueSheet>();
+
+  /**
+   * Resolver to be called when mount event is received, or with `false` when the present is cancelled
+   */
+  private presentationResolver: ((mounted: boolean) => void) | null = null;
+
+  /**
+   * Settles once a scheduled lazy unmount has committed
+   */
+  private nativeViewUnmount: Promise<void> | null = null;
 
   /**
    * Tracks if a present operation is in progress
@@ -198,13 +209,17 @@ export class TrueSheet
     if (scrollableRef?.current) {
       try {
         scrollableHandle = findNodeHandle(
-          scrollableRef.current as Parameters<typeof findNodeHandle>[0]
+          resolveScrollable(scrollableRef.current) as Parameters<typeof findNodeHandle>[0]
         );
       } catch (error) {
-        // A stale ref (e.g. a wrapper that never clears it on unmount) makes
-        // findNodeHandle throw. Treat it as no scrollable instead of crashing.
+        // findNodeHandle throws on a stale ref (e.g. a wrapper that never clears
+        // it on unmount) or a handle with no usable scroll accessor. Treat it as
+        // no scrollable instead of crashing.
         if (__DEV__) {
-          console.warn('TrueSheet: scrollableRef points to an unmounted component.', error);
+          console.warn(
+            'TrueSheet: scrollableRef could not be resolved to a native view. It may be stale or expose no scroll node.',
+            error
+          );
         }
       }
     }
@@ -343,6 +358,7 @@ export class TrueSheet
    * @returns Promise that resolves when all sheets are dismissed
    */
   public static async dismissAll(animated: boolean = true): Promise<void> {
+    TrueSheet.mountedInstances.forEach((sheet) => sheet.cancelPendingPresent());
     return TrueSheetModule?.dismissAll(animated);
   }
 
@@ -396,16 +412,17 @@ export class TrueSheet
 
     // Non-lazy content stays mounted; otherwise clean it up unless another presentation is active.
     if (!this.isPresenting && this.props.lazy !== false) {
-      this.setState({ shouldRenderNativeView: false });
+      this.unmountNativeView();
     }
 
     this.props.onDidDismiss?.(event);
   }
 
   private onMount(event: MountEvent): void {
-    // Resolve the mount promise if waiting
-    if (this.presentationResolver) {
-      this.presentationResolver();
+    // Resolve the mount promise if waiting. While an unmount is pending, the event is from
+    // the outgoing view — present() waits for the remount instead.
+    if (this.presentationResolver && !this.nativeViewUnmount) {
+      this.presentationResolver(true);
       this.presentationResolver = null;
     }
 
@@ -465,7 +482,9 @@ export class TrueSheet
       return onBackPress?.() ?? onDismissAttempt != null;
     }
 
-    TrueSheetModule?.handleBackPress(nodeHandle);
+    // Rejects when the native view is gone but JS hasn't unmounted yet (e.g. the surface
+    // stopped while this back press was queued). Nothing is left to dismiss.
+    TrueSheetModule?.handleBackPress(nodeHandle).catch(() => {});
     return this.props.onBackPress?.() ?? true;
   }
 
@@ -482,20 +501,67 @@ export class TrueSheet
       );
     }
 
+    // Still waiting on the lazy mount — like native, a second present is a no-op
+    if (this.presentationResolver) {
+      console.warn('TrueSheet: sheet is already presented. Use resize() to change detent.');
+      return;
+    }
+
     this.isPresenting = true;
 
     // Lazy load: render native view if not already rendered
-    if (!this.state.shouldRenderNativeView) {
-      await new Promise<void>((resolve) => {
+    const unmount = this.nativeViewUnmount;
+    if (unmount || !this.state.shouldRenderNativeView) {
+      const mounted = await new Promise<boolean>((resolve) => {
         this.presentationResolver = resolve;
-        this.setState({ shouldRenderNativeView: true });
+
+        const mount = () => {
+          if (this.presentationResolver === resolve) {
+            this.setState({ shouldRenderNativeView: true });
+          }
+        };
+
+        // An unmount from the last dismiss may not have committed yet — state still reads
+        // mounted, and presenting now would lose the sheet when it lands. Remount after it.
+        if (unmount) {
+          unmount.then(mount);
+        } else {
+          mount();
+        }
       });
+
+      // Dismissed before the native view mounted
+      if (!mounted) {
+        this.isPresenting = false;
+        return;
+      }
     }
 
     await TrueSheetModule?.presentByRef(this.handle, index, animated);
     this.isPresenting = false;
   }
 
+  /**
+   * Cancels a present still waiting on the lazy mount. Returns whether one was pending.
+   */
+  private cancelPendingPresent(): boolean {
+    if (!this.presentationResolver) return false;
+
+    this.presentationResolver(false);
+    this.presentationResolver = null;
+    this.unmountNativeView();
+    return true;
+  }
+
+  private unmountNativeView(): void {
+    this.nativeViewUnmount = new Promise((resolve) => {
+      this.setState({ shouldRenderNativeView: false }, () => {
+        this.nativeViewUnmount = null;
+        resolve();
+      });
+    });
+  }
+
   /**
    * Resize the sheet to a given detent index.
    * @param index - The detent index to resize to
@@ -509,6 +575,9 @@ export class TrueSheet
    * @param animated - Whether to animate the dismissal (default: true)
    */
   public async dismiss(animated: boolean = true): Promise<void> {
+    // Dismissing before the lazy mount finishes cancels the present — nothing was presented
+    if (this.cancelPendingPresent()) return;
+
     return TrueSheetModule?.dismissByRef(this.handle, animated);
   }
 
@@ -522,6 +591,7 @@ export class TrueSheet
   }
 
   componentDidMount(): void {
+    TrueSheet.mountedInstances.add(this);
     this.registerInstance();
     this.updateScrollableHandle();
   }
@@ -558,9 +628,12 @@ export class TrueSheet
   }
 
   componentWillUnmount(): void {
+    TrueSheet.mountedInstances.delete(this);
     this.unregisterInstance();
     this.backHandlerSubscription?.remove();
     this.backHandlerSubscription = null;
+    // Don't leave a present waiting on the lazy mount hanging
+    this.presentationResolver?.(false);
     this.presentationResolver = null;
   }
 
@@ -578,6 +651,8 @@ export class TrueSheet
       grabberOptions,
       accessibilityOptions,
       dimmed = true,
+      dimColor,
+      dimOpacity,
       initialDetentIndex = -1,
       initialDetentAnimated = true,
       dimmedDetentIndex,
@@ -686,6 +761,8 @@ export class TrueSheet
         grabberOptions={this.resolvedGrabberOptions}
         accessibilityOptions={accessibilityOptions}
         dimmed={dimmed}
+        dimColor={dimColor}
+        dimOpacity={dimOpacity}
         dimmedDetentIndex={dimmedDetentIndex}
         initialDetentIndex={gatedInitialDetentIndex}
         initialDetentAnimated={initialDetentAnimated}

package/src/TrueSheet.types.ts

@@ -439,6 +439,22 @@ export interface TrueSheetProps extends ViewProps {
    */
   dimmed?: boolean;
 
+  /**
+   * The color of the dim overlay behind the sheet.
+   * This is ignored if `dimmed` is set to `false`.
+   *
+   * @default '#000000'
+   */
+  dimColor?: ColorValue;
+
+  /**
+   * The maximum opacity of the dim overlay behind the sheet (0 to 1).
+   * This is ignored if `dimmed` is set to `false`.
+   *
+   * @default 0.5
+   */
+  dimOpacity?: number;
+
   /**
    * Initially present the sheet, after mounting, at a given detent index.
    *
@@ -677,7 +693,9 @@ export interface TrueSheetProps extends ViewProps {
 
   /**
    * A ref to the scrollable component (e.g. `ScrollView`, `FlatList`)
-   * rendered within the sheet content.
+   * rendered within the sheet content. Lists that expose an imperative handle
+   * (e.g. `LegendList`, `FlashList`) work too, through their
+   * `getScrollableNode()` or `getNativeScrollRef()`.
    * Required for scrollable handling — nested scrolling, keyboard insets,
    * and `auto` detent sizing are wired to this scrollable.
    *
@@ -690,7 +708,13 @@ export interface TrueSheetProps extends ViewProps {
    * </TrueSheet>
    * ```
    */
-  scrollableRef?: RefObject<Component<unknown> | HostInstance | null>;
+  scrollableRef?: RefObject<
+    | Component<unknown>
+    | HostInstance
+    | { getScrollableNode(): unknown }
+    | { getNativeScrollRef(): unknown }
+    | null
+  >;
 
   /**
    * Options for scrollable behavior.

package/src/TrueSheet.web.tsx

@@ -10,6 +10,7 @@ import {
   useMemo,
   useRef,
   useState,
+  type RefObject,
 } from 'react';
 import type { DimensionValue, LayoutChangeEvent } from 'react-native';
 import { StyleSheet, useColorScheme, useWindowDimensions, View } from 'react-native';
@@ -41,7 +42,12 @@ import {
   TrueSheetPeekContext,
   type TrueSheetPeekContextValue,
 } from './TrueSheetPeek.web';
-import { usePortalContainer, useRegisterSheet, useSheetStack } from './TrueSheetProvider.web';
+import {
+  usePortalContainer,
+  useRegisterSheet,
+  useSheetStack,
+  type SheetHandle,
+} from './TrueSheetProvider.web';
 import {
   COLOR_SURFACE_CONTAINER_LOW_DARK,
   COLOR_SURFACE_CONTAINER_LOW_LIGHT,
@@ -60,18 +66,16 @@ import {
 import { getDOMElement } from './web/dom';
 import { TrueSheetBackground } from './TrueSheetBackground';
 import { getDetentBackgroundIndex, normalizeDetentBackground } from './detentBackgrounds';
+import { revealFocusedElement, useKeyboardViewport } from './web/keyboard';
 import { observeSheetLayout } from './web/layout';
+import { resolveScrollable } from './scrollable';
 import { Drawer } from './web/vaul';
 import { DEFAULT_PEEK_HEIGHT, DRAG_CLASS, TRANSITIONS } from './web/vaul/constants';
 
-// Resolves the user's `scrollableRef` to its scrollable DOM element — RN-web
-// ScrollView refs expose the scroll node directly (with helpers attached);
-// list refs (e.g. FlatList) expose it via getScrollableNode(). The node's
-// first child is the content container.
+// Resolves the user's `scrollableRef` to its scrollable DOM element. The
+// node's first child is the content container.
 const getScrollableElement = (scrollable: unknown): HTMLElement | null => {
-  if (!scrollable) return null;
-  if (scrollable instanceof HTMLElement) return scrollable;
-  const node = (scrollable as { getScrollableNode?: () => unknown }).getScrollableNode?.();
+  const node = resolveScrollable(scrollable);
   return node instanceof HTMLElement ? node : null;
 };
 
@@ -99,6 +103,8 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     accessibilityOptions,
     detents = [0.5, 1],
     dimmed = true,
+    dimColor,
+    dimOpacity,
     dimmedDetentIndex = 0,
     initialDetentIndex = -1,
     header,
@@ -164,7 +170,19 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   const [isOpen, setIsOpen] = useState(shouldAutoPresent);
   const isOpenRef = useRef(isOpen);
   isOpenRef.current = isOpen;
+  const keyboardViewport = useKeyboardViewport(isOpen);
   const isPresentingRef = useRef(shouldAutoPresent);
+  // Native's lifecycle state — updated synchronously so calls in the same tick see each other
+  const phaseRef = useRef<SheetPhase>(shouldAutoPresent ? 'presenting' : 'dismissed');
+  const resolvePresentRef = useRef<(() => void) | null>(null);
+  const resolveDismissRef = useRef<(() => void) | null>(null);
+  // Whether willPresent fired for the current open cycle — a present undone
+  // before it fires has nothing to pair a dismiss with.
+  const didEmitWillPresentRef = useRef(false);
+  // Whether the current open cycle came from initialDetentIndex. Native mounts those
+  // eagerly, so a dismiss before willPresent lands after the present instead of cancelling it.
+  const isAutoPresentRef = useRef(shouldAutoPresent);
+  const shouldDismissOnPresentRef = useRef(false);
   const [displayedBackgroundIndex, setDisplayedBackgroundIndex] = useState(
     shouldAutoPresent ? initialDetentIndex : 0
   );
@@ -199,13 +217,31 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     );
   }, []);
 
+  // Returns null when there's nothing to dismiss. Resolves on didDismiss.
+  const dismissSheet = useCallback((): Promise<void> | null => {
+    if (phaseRef.current === 'dismissed' || phaseRef.current === 'dismissing') return null;
+    settle(resolvePresentRef);
+    if (didEmitWillPresentRef.current) {
+      setIsOpen(false);
+    } else if (isAutoPresentRef.current) {
+      shouldDismissOnPresentRef.current = true;
+    } else {
+      // Mirror native's lazy-mount cancel: nothing shown yet, nothing to animate out
+      setIsOpen(false);
+      phaseRef.current = 'dismissed';
+      return Promise.resolve();
+    }
+    phaseRef.current = 'dismissing';
+    return new Promise((resolve) => {
+      resolveDismissRef.current = resolve;
+    });
+  }, []);
+
   const handleOpenChange = useCallback(
     (open: boolean) => {
-      if (!open && isOpen) {
-        setIsOpen(false);
-      }
+      if (!open) dismissSheet();
     },
-    [isOpen]
+    [dismissSheet]
   );
 
   const portalContainer = usePortalContainer();
@@ -248,24 +284,38 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   const dismissAboveRef = useRef<(animated?: boolean) => Promise<void>>(async () => {});
   const dismissDescendantsRef = useRef<() => void>(() => {});
 
+  const presentSheet = useCallback(async (index: number, auto: boolean) => {
+    const detent = validDetentsRef.current[index];
+    if (detent === undefined) {
+      throw new Error(
+        `TrueSheet: present index (${index}) is out of bounds. detents array has ${validDetentsRef.current.length} item(s)`
+      );
+    }
+    if (phaseRef.current !== 'dismissed') {
+      console.warn(ALREADY_PRESENTED_WARNING);
+      return;
+    }
+    phaseRef.current = 'presenting';
+    isAutoPresentRef.current = auto;
+    isPresentingRef.current = true;
+    setDisplayedBackgroundIndex(index);
+    setActiveSnapPoint(detent);
+    setIsOpen(true);
+    await new Promise<void>((resolve) => {
+      resolvePresentRef.current = resolve;
+    });
+  }, []);
+
   const methods = useMemo<TrueSheetMethods>(
     () => ({
-      present: async (index = 0) => {
-        const detent = validDetentsRef.current[index];
-        if (detent === undefined) {
-          throw new Error(
-            `TrueSheet: present index (${index}) is out of bounds. detents array has ${validDetentsRef.current.length} item(s)`
-          );
-        }
-        if (!isOpenRef.current) {
-          isPresentingRef.current = true;
-          setDisplayedBackgroundIndex(index);
-        }
-        setActiveSnapPoint(detent);
-        setIsOpen(true);
-      },
+      present: (index = 0) => presentSheet(index, false),
       dismiss: async () => {
-        setIsOpen(false);
+        const dismissal = dismissSheet();
+        if (!dismissal) {
+          console.warn(ALREADY_DISMISSED_WARNING);
+          return;
+        }
+        await dismissal;
       },
       resize: async (index) => {
         const detent = validDetentsRef.current[index];
@@ -277,10 +327,14 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
         setActiveSnapPoint(detent);
       },
       dismissStack: async (animated) => {
+        if (phaseRef.current === 'dismissed' || phaseRef.current === 'dismissing') {
+          console.warn(ALREADY_DISMISSED_WARNING);
+          return;
+        }
         await dismissAboveRef.current(animated);
       },
     }),
-    []
+    [presentSheet, dismissSheet]
   );
 
   useImperativeHandle(ref, () => methods, [methods]);
@@ -288,13 +342,27 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   useEffect(() => {
     if (!shouldAutoPresent || didInitiallyPresentRef.current) return;
     didInitiallyPresentRef.current = true;
-    if (!isOpenRef.current) {
-      methods.present(initialDetentIndex);
+    if (phaseRef.current === 'dismissed') {
+      presentSheet(initialDetentIndex, true);
     }
-  }, [initialDetentIndex, shouldAutoPresent, methods]);
+  }, [initialDetentIndex, shouldAutoPresent, presentSheet]);
+
+  // Unmounted mid-transition: don't leave callers awaiting forever
+  useEffect(
+    () => () => {
+      settle(resolvePresentRef);
+      settle(resolveDismissRef);
+    },
+    []
+  );
 
-  const methodsRef = useRef<TrueSheetMethods | null>(methods);
-  useRegisterSheet(name, methodsRef);
+  const handleRef = useRef<SheetHandle>({
+    methods,
+    dismissQuietly: async () => {
+      await dismissSheet();
+    },
+  });
+  useRegisterSheet(name, handleRef);
 
   const drawerContentRef = useRef<HTMLDivElement | null>(null);
   const [drawerContent, setDrawerContent] = useState<HTMLDivElement | null>(null);
@@ -447,6 +515,22 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     scrollableRef,
   ]);
 
+  // Re-reveal the focused field once the sheet settles above the keyboard
+  useEffect(() => {
+    const drawer = drawerContentRef.current;
+    if (!keyboardViewport || !drawer) return undefined;
+    let canceled = false;
+    // Flush styles so this commit's snap transition shows up in getAnimations()
+    // eslint-disable-next-line no-void
+    void drawer.offsetHeight;
+    Promise.allSettled(drawer.getAnimations().map((a) => a.finished)).then(() => {
+      if (!canceled) revealFocusedElement(drawer);
+    });
+    return () => {
+      canceled = true;
+    };
+  }, [keyboardViewport]);
+
   // Below the last detent a vertical touch pan moves the sheet, not the
   // content — `[data-vaul-scroll-locked]` disables vertical touch panning on
   // the scroll container and everything inside it (see vaul/style.css).
@@ -519,6 +603,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     effectiveMaxContentHeight,
     peekHeight,
     peekContentHeight,
+    keyboardViewport,
   });
   geometryInputsRef.current = {
     effectiveDetached,
@@ -526,14 +611,18 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     effectiveMaxContentHeight,
     peekHeight,
     peekContentHeight,
+    keyboardViewport,
   };
 
   const computeDetentGeometry = useCallback(() => {
     const inputs = geometryInputsRef.current;
-    const windowH = window.innerHeight;
-    const effectiveH = inputs.effectiveDetached
-      ? windowH - inputs.effectiveDetachedOffset
-      : windowH;
+    const windowH = inputs.keyboardViewport?.height ?? window.innerHeight;
+    const bottomGap = inputs.effectiveDetached ? inputs.effectiveDetachedOffset : 0;
+    const effectiveH = windowH - bottomGap;
+    // Above a keyboard, fractions keep their full-height size (see vaul).
+    const fractionH = inputs.keyboardViewport
+      ? inputs.keyboardViewport.layoutHeight - bottomGap
+      : effectiveH;
     // Matches vaul's height ceiling: min(effectiveH, maxContentHeight).
     const ceiling =
       inputs.effectiveMaxContentHeight !== undefined
@@ -569,7 +658,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     for (const d of validDetentsRef.current) {
       const h =
         typeof d === 'number'
-          ? Math.min(d * effectiveH, ceiling)
+          ? Math.min(d * fractionH, ceiling)
           : d === 'peek'
             ? Math.min(livePeekHeight, ceiling)
             : autoHeight;
@@ -706,6 +795,9 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
       // Mirror native: dismissing a sheet takes every sheet stacked above it
       // (iOS dismisses from the presenter; Android runs dismissStack first).
       dismissDescendantsRef.current();
+      // Mirror native's lazy-mount cancel: dismissed before willPresent, no events
+      if (!didEmitWillPresentRef.current) return undefined;
+      didEmitWillPresentRef.current = false;
       // Pair willBlur with willDismiss on dismiss — mirrors native iOS
       // emitWillDismissEvents (blur fires before dismiss). willPresent is
       // deferred to `start()` below (needs the mounted drawer's geometry).
@@ -716,11 +808,20 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     const fireDone = () => {
       if (present) {
         isPresentingRef.current = false;
+        // A dismiss may already be underway (it lands on the next commit)
+        if (phaseRef.current === 'presenting') phaseRef.current = 'presented';
         onDidPresentRef.current?.({ nativeEvent: computeDetentInfo() } as DidPresentEvent);
         onDidFocusRef.current?.({ nativeEvent: null } as DidFocusEvent);
+        settle(resolvePresentRef);
+        if (shouldDismissOnPresentRef.current) {
+          shouldDismissOnPresentRef.current = false;
+          setIsOpen(false);
+        }
       } else {
+        phaseRef.current = 'dismissed';
         onDidBlurRef.current?.({ nativeEvent: null } as DidBlurEvent);
         onDidDismissRef.current?.({ nativeEvent: null } as DidDismissEvent);
+        settle(resolveDismissRef);
       }
     };
 
@@ -746,6 +847,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
         // willPresent mirrors native iOS where viewWillAppear dispatches
         // both; the descendant-stack focus effect handles subsequent
         // transitions.
+        didEmitWillPresentRef.current = true;
         onWillPresentRef.current?.({ nativeEvent: computeDetentInfo() } as WillPresentEvent);
         onWillFocusRef.current?.({ nativeEvent: null } as WillFocusEvent);
       }
@@ -812,7 +914,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   }, [computeDetentInfo]);
 
   const { isNested, dismissAbove, descendants } = useSheetStack(
-    methodsRef,
+    handleRef,
     drawerContentRef,
     isOpen,
     isFormSheet
@@ -822,7 +924,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   // already been popped from the stack, so `dismissAbove` can't find it.
   dismissDescendantsRef.current = () => {
     for (let i = descendants.length - 1; i >= 0; i--) {
-      descendants[i]!.ref.current?.dismiss();
+      descendants[i]!.ref.current?.dismissQuietly();
     }
   };
 
@@ -1057,6 +1159,16 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     transition: isPresentingRef.current ? 'none' : 'background-color 200ms',
   };
 
+  // Vaul fades the overlay through its opacity, so the dim opacity goes into the color
+  const resolvedOverlayStyle = useMemo<React.CSSProperties>(() => {
+    if (dimColor == null && dimOpacity == null) return overlayStyle;
+    const percentage = Math.min(1, Math.max(0, dimOpacity ?? DEFAULT_DIM_OPACITY)) * 100;
+    return {
+      ...overlayStyle,
+      backgroundColor: `color-mix(in srgb, ${String(dimColor ?? 'black')} ${percentage}%, transparent)`,
+    };
+  }, [dimColor, dimOpacity]);
+
   const mergedContentStyle = useMemo<React.CSSProperties>(
     () => ({
       position: 'fixed',
@@ -1225,12 +1337,13 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
         initialAnimated={shouldAutoPresent ? initialDetentAnimated : true}
         detachedWrapperStyle={wrapperStyle}
         contentHeight={measuredContentHeight}
+        keyboardViewport={keyboardViewport}
         activeSnapPoint={activeSnapPoint}
         setActiveSnapPoint={handleSetActiveSnapPoint}
         {...snapPointsProps}
       >
         <Drawer.Portal container={portalContainer ?? undefined}>
-          <Drawer.Overlay style={overlayStyle} />
+          <Drawer.Overlay style={resolvedOverlayStyle} />
           <Drawer.Content
             ref={handleDrawerRef}
             style={mergedContentStyle}
@@ -1281,6 +1394,8 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   );
 });
 
+const DEFAULT_DIM_OPACITY = 0.5;
+
 const overlayStyle: React.CSSProperties = {
   position: 'fixed',
   inset: 0,
@@ -1329,6 +1444,20 @@ const visuallyHiddenStyle: React.CSSProperties = {
   border: 0,
 };
 
+type SheetPhase = 'dismissed' | 'presenting' | 'presented' | 'dismissing';
+
+const settle = (resolveRef: RefObject<(() => void) | null>) => {
+  const resolve = resolveRef.current;
+  resolveRef.current = null;
+  resolve?.();
+};
+
+// Same as native
+const ALREADY_PRESENTED_WARNING =
+  'TrueSheet: sheet is already presented. Use resize() to change detent.';
+const ALREADY_DISMISSED_WARNING =
+  'TrueSheet: sheet is already dismissed. No need to dismiss it again.';
+
 const STATIC_METHOD_ERROR =
   'Static methods are not supported on web. Use the useTrueSheet() hook instead.';