feat(web): honor elevation, insetAdjustment, initialDetentAnimated, scrollingExpandsSheet

Author: lodev09

src/TrueSheet.web.tsx

@@ -74,8 +74,12 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     footer,
     footerStyle,
     scrollable = false,
+    scrollableOptions,
     detached = false,
     detachedOffset = DEFAULT_DETACHED_OFFSET,
+    elevation = 4,
+    insetAdjustment = 'automatic',
+    initialDetentAnimated = true,
     onPositionChange,
     onWillPresent,
     onDidPresent,
@@ -568,6 +572,12 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
 
   const effectiveCornerRadius = cornerRadius ?? DEFAULT_CORNER_RADIUS;
 
+  // Shadow cast upward from the sheet's top edge toward the background. Matches
+  // Android's `elevation` semantics roughly — the sheet "lifts" off whatever is
+  // behind it. Scales linearly so higher elevation reads as more separation.
+  const boxShadow =
+    elevation > 0 ? `0 ${-elevation}px ${elevation * 3}px rgba(0, 0, 0, 0.15)` : undefined;
+
   const mergedContentStyle = useMemo<React.CSSProperties>(
     () => ({
       position: 'fixed',
@@ -580,8 +590,11 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
       borderTopLeftRadius: effectiveCornerRadius,
       borderTopRightRadius: effectiveCornerRadius,
       backgroundColor: backgroundColor as string,
+      boxShadow,
+      // Lift content above iOS home indicator / bottom safe area when enabled.
+      paddingBottom: insetAdjustment === 'automatic' ? 'env(safe-area-inset-bottom, 0px)' : 0,
     }),
-    [backgroundColor, effectiveCornerRadius]
+    [backgroundColor, effectiveCornerRadius, boxShadow, insetAdjustment]
   );
 
   const defaultGrabberColor =
@@ -641,13 +654,15 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
       onRelease={handleRelease}
       dismissible={dismissible}
       draggable={draggable}
+      handleOnly={scrollable && scrollableOptions?.scrollingExpandsSheet === false}
       repositionInputs={false}
       modal={dimmed}
       nested={isNested}
       detached={detached}
       detachedOffset={detachedOffset}
       detachedRadius={effectiveCornerRadius}
       maxContentHeight={maxContentHeight}
+      initialAnimated={initialDetentAnimated}
       detachedWrapperStyle={wrapperStyle}
       activeSnapPoint={activeSnapPoint}
       setActiveSnapPoint={handleSetActiveSnapPoint}

src/web/vaul/index.tsx

@@ -177,6 +177,11 @@ export type DialogProps = {
    * respect a user-specified ceiling.
    */
   maxContentHeight?: number;
+  /**
+   * When `false` the first snap on mount is applied without a transition so
+   * the sheet appears at its target detent instantly. Defaults to `true`.
+   */
+  initialAnimated?: boolean;
 } & (WithFadeFromProps | WithoutFadeFromProps);
 
 export function Root({
@@ -216,6 +221,7 @@ export function Root({
   detachedRadius = 0,
   detachedWrapperStyle,
   maxContentHeight,
+  initialAnimated = true,
 }: DialogProps) {
   const [isOpen = false, setIsOpen] = useControllableState({
     defaultProp: defaultOpen,
@@ -295,6 +301,7 @@ export function Root({
     contentHeight,
     detachedOffset: detached ? detachedOffset : 0,
     maxContentHeight,
+    initialAnimated,
   });
 
   usePreventScroll({

src/web/vaul/use-snap-points.ts

@@ -20,6 +20,7 @@ export function useSnapPoints({
   contentHeight,
   detachedOffset = 0,
   maxContentHeight,
+  initialAnimated = true,
 }: {
   activeSnapPointProp?: number | string | null;
   setActiveSnapPointProp?(snapPoint: number | null | string): void;
@@ -35,6 +36,7 @@ export function useSnapPoints({
   contentHeight?: number;
   detachedOffset?: number;
   maxContentHeight?: number;
+  initialAnimated?: boolean;
 }) {
   const [activeSnapPoint, setActiveSnapPoint] = useControllableState<string | number | null>({
     prop: activeSnapPointProp,
@@ -172,21 +174,28 @@ export function useSnapPoints({
     });
   };
 
+  // Skip the transition on the very first snap when the consumer opts out of
+  // the initial presentation animation. All subsequent snaps still animate.
+  const hasSnappedRef = React.useRef(false);
   const snapToPoint = React.useCallback(
     (dimension: number) => {
       const newSnapPointIndex =
         snapPointsOffset?.findIndex((snapPointDim) => snapPointDim === dimension) ?? null;
       onSnapPointChange(newSnapPointIndex);
 
+      const animateThisSnap = hasSnappedRef.current || initialAnimated;
+      hasSnappedRef.current = true;
       set(drawerRef.current, {
-        transition: `transform ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`,
+        transition: animateThisSnap
+          ? `transform ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`
+          : 'none',
         transform: isVertical(direction)
           ? `translate3d(0, ${dimension}px, 0)`
           : `translate3d(${dimension}px, 0, 0)`,
       });
 
       // Snapping implies drag overshoot (if any) should be undone.
-      setDetachedWrapperTransform(0, true);
+      setDetachedWrapperTransform(0, animateThisSnap);
 
       if (
         snapPointsOffset &&