@snowcone-app/ui 0.1.42 → 0.2.0

package/src/primitives/drawer.tsx

@@ -0,0 +1,828 @@
+"use client";
+
+import * as React from "react";
+import { createPortal } from "react-dom";
+import { cn } from "../lib/utils";
+import { Surface } from "./surface";
+
+/**
+ * Drawer Component
+ *
+ * A mobile-optimized drawer component that works correctly on all platforms including iOS Safari.
+ * Uses CSS animations and proper positioning for smooth, native-feeling interactions.
+ *
+ * Key features:
+ * - CSS-based animations for smooth performance
+ * - Backdrop blur overlay for modern iOS 26+ appearance
+ * - Proper safe-area handling via CSS (no explicit color props needed)
+ * - Native swipe-to-dismiss gesture support
+ * - Works with scrollable page content
+ *
+ * @example Basic usage
+ * <Drawer open={isOpen} onOpenChange={setIsOpen}>
+ *   <DrawerTrigger asChild>
+ *     <Button>Open Drawer</Button>
+ *   </DrawerTrigger>
+ *   <DrawerContent>
+ *     <DrawerHeader>
+ *       <DrawerTitle>Title</DrawerTitle>
+ *       <DrawerDescription>Description</DrawerDescription>
+ *     </DrawerHeader>
+ *     <div className="p-4">Content here</div>
+ *     <DrawerFooter>
+ *       <Button>Action</Button>
+ *     </DrawerFooter>
+ *   </DrawerContent>
+ * </Drawer>
+ *
+ * @example Custom colored drawer with blur overlay
+ * <DrawerContent className="bg-emerald-500">
+ *   <DrawerTitle className="sr-only">Sheet</DrawerTitle>
+ *   <div className="p-4 text-white">
+ *     Content with custom background - safe areas handled automatically
+ *   </div>
+ * </DrawerContent>
+ */
+
+interface DrawerContextValue {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+const DrawerContext = React.createContext<DrawerContextValue | null>(null);
+
+function useDrawerContext() {
+  const context = React.useContext(DrawerContext);
+  if (!context) {
+    throw new Error("Drawer components must be used within a Drawer");
+  }
+  return context;
+}
+
+// ============================================================================
+// Drawer (Root)
+// ============================================================================
+
+interface DrawerProps {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  children: React.ReactNode;
+}
+
+function Drawer({
+  open: controlledOpen,
+  defaultOpen = false,
+  onOpenChange,
+  children,
+}: DrawerProps) {
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen);
+
+  const isControlled = controlledOpen !== undefined;
+  const open = isControlled ? controlledOpen : uncontrolledOpen;
+
+  const handleOpenChange = React.useCallback(
+    (newOpen: boolean) => {
+      if (!isControlled) {
+        setUncontrolledOpen(newOpen);
+      }
+      onOpenChange?.(newOpen);
+    },
+    [isControlled, onOpenChange]
+  );
+
+  // Dispatch drawer-open/close events and manage data-drawer-open attribute
+  // Note: drawer-close is also dispatched from DrawerContent.handleClose for animated closes,
+  // but we handle it here too for cases where open prop changes directly (e.g., clicking "Done" button)
+  const headerShiftDelay = 10; // ms - blur appears, then header shifts
+  const wasOpen = React.useRef(false);
+  React.useLayoutEffect(() => {
+    if (open) {
+      wasOpen.current = true;
+      document.documentElement.setAttribute("data-drawer-open", "true");
+      const timer = setTimeout(() => {
+        window.dispatchEvent(new CustomEvent("drawer-open"));
+      }, headerShiftDelay);
+      return () => clearTimeout(timer);
+    } else if (wasOpen.current) {
+      // Only dispatch close if this drawer was actually opened
+      // This prevents dispatching close for drawers that were never opened
+      wasOpen.current = false;
+      // Guard: Only remove attribute and dispatch event if attribute is still present
+      // This prevents double-dispatch when handleClose has already removed it during animated close
+      if (document.documentElement.hasAttribute("data-drawer-open")) {
+        document.documentElement.removeAttribute("data-drawer-open");
+        window.dispatchEvent(new CustomEvent("drawer-close"));
+      }
+    }
+  }, [open]);
+
+  return (
+    <DrawerContext.Provider value={{ open, onOpenChange: handleOpenChange }}>
+      {children}
+    </DrawerContext.Provider>
+  );
+}
+Drawer.displayName = "Drawer";
+
+// ============================================================================
+// DrawerTrigger
+// ============================================================================
+
+interface DrawerTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  asChild?: boolean;
+}
+
+const DrawerTrigger = React.forwardRef<HTMLButtonElement, DrawerTriggerProps>(
+  ({ asChild, onClick, children, ...props }, ref) => {
+    const { onOpenChange } = useDrawerContext();
+
+    const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
+      onClick?.(e);
+      onOpenChange(true);
+    };
+
+    if (asChild && React.isValidElement(children)) {
+      return React.cloneElement(
+        children as React.ReactElement<{ onClick?: React.MouseEventHandler }>,
+        {
+          onClick: handleClick,
+        }
+      );
+    }
+
+    return (
+      <button ref={ref} onClick={handleClick} {...props}>
+        {children}
+      </button>
+    );
+  }
+);
+DrawerTrigger.displayName = "DrawerTrigger";
+
+// ============================================================================
+// DrawerClose
+// ============================================================================
+
+interface DrawerCloseProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  asChild?: boolean;
+}
+
+const DrawerClose = React.forwardRef<HTMLButtonElement, DrawerCloseProps>(
+  ({ asChild, onClick, children, ...props }, ref) => {
+    const { onOpenChange } = useDrawerContext();
+
+    const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
+      onClick?.(e);
+      onOpenChange(false);
+    };
+
+    if (asChild && React.isValidElement(children)) {
+      return React.cloneElement(
+        children as React.ReactElement<{ onClick?: React.MouseEventHandler }>,
+        {
+          onClick: handleClick,
+        }
+      );
+    }
+
+    return (
+      <button ref={ref} onClick={handleClick} {...props}>
+        {children}
+      </button>
+    );
+  }
+);
+DrawerClose.displayName = "DrawerClose";
+
+// ============================================================================
+// DrawerContent
+// ============================================================================
+
+interface DrawerContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Drawer placement. Default: 'bottom' */
+  placement?: "bottom" | "left" | "right";
+  /** Explicit height for bottom drawer. Use this when you want the drawer to always be a specific size. */
+  height?: string;
+  /** Max height for bottom drawer. Default: '80dvh'. Only used if height is not set. */
+  maxHeight?: string;
+  /** Width for side drawers (left/right). Can be CSS value like '400px' or '80vw'. */
+  width?: string;
+  /** Max width for side drawers. Default: '400px' */
+  maxWidth?: string;
+  /** Whether to show the overlay/backdrop. Default: true */
+  showOverlay?: boolean;
+  /** Whether to hide the drag handle. Default: false */
+  hideHandle?: boolean;
+  /** Overlay opacity (0-1). Default: 0.3 */
+  overlayOpacity?: number;
+  /** Whether to lock body scroll when drawer is open. Default: true */
+  lockBodyScroll?: boolean;
+  /** Whether to use dialog ARIA attributes (role="dialog", aria-modal). Default: true */
+  useDialogRole?: boolean;
+  /** Disable swipe gestures for closing the drawer. Default: false. */
+  disableSwipeGestures?: boolean;
+  /** Animation duration in ms. Default: 300 (DEBUG: 2000) */
+  animationDuration?: number;
+  /** Show a gradient fade at the bottom that hides when scrolled to bottom. Default: true */
+  showScrollFade?: boolean;
+  /** Color for the scroll fade gradient. Should match drawer background. Default: uses CSS variable */
+  scrollFadeColor?: string;
+  /** Height ratio for bottom drawer (0-1). Deprecated - use height prop instead. Will set height to heightRatio * 100vh. */
+  heightRatio?: number;
+  /** Whether to add safe area padding at the bottom. Default: false. Deprecated - safe area is handled automatically via CSS. */
+  safeAreaPadding?: boolean;
+}
+
+const DrawerContent = React.forwardRef<HTMLDivElement, DrawerContentProps>(
+  (
+    {
+      className,
+      children,
+      placement = "bottom",
+      height,
+      maxHeight = "80dvh",
+      width,
+      maxWidth = "400px",
+      showOverlay = true,
+      hideHandle = false,
+      overlayOpacity = 0.3,
+      lockBodyScroll = true,
+      useDialogRole = true,
+      disableSwipeGestures = false,
+      animationDuration = 500,
+      showScrollFade = true,
+      scrollFadeColor,
+      heightRatio,
+      safeAreaPadding = false,
+      ...props
+    },
+    ref
+  ) => {
+    const { open, onOpenChange } = useDrawerContext();
+    const [mounted, setMounted] = React.useState(false);
+    const [bodyHeight, setBodyHeight] = React.useState(0);
+    const [isClosing, setIsClosing] = React.useState(false);
+    const [isBlurFading, setIsBlurFading] = React.useState(false);
+    const [isAtBottom, setIsAtBottom] = React.useState(false);
+    const [delayedOpen, setDelayedOpen] = React.useState(false);
+    const drawerRef = React.useRef<HTMLDivElement>(null);
+    const contentRef = React.useRef<HTMLDivElement>(null);
+    const startY = React.useRef(0);
+    const currentY = React.useRef(0);
+
+    // Track nested drawer state - shift down when another drawer opens on top
+    const [isNestedDrawerOpen, setIsNestedDrawerOpen] = React.useState(false);
+    const [showGreenBar, setShowGreenBar] = React.useState(false);
+    const drawerMountedRef = React.useRef(false);
+    const ignoreNextDrawerOpenRef = React.useRef(true); // Ignore our own drawer-open event
+    const greenBarTimeoutRef = React.useRef<ReturnType<
+      typeof setTimeout
+    > | null>(null);
+
+    // Delay drawer opening to allow header shift to complete first
+    const openDelay = 120; // ms - must be after green bar finishes
+    React.useEffect(() => {
+      if (open) {
+        const timer = setTimeout(() => setDelayedOpen(true), openDelay);
+        return () => clearTimeout(timer);
+      } else {
+        setDelayedOpen(false);
+      }
+    }, [open]);
+
+    // Handle scroll to detect when at bottom
+    const handleScroll = React.useCallback(
+      (e: React.UIEvent<HTMLDivElement>) => {
+        const target = e.target as HTMLDivElement;
+        const atBottom =
+          target.scrollHeight - target.scrollTop - target.clientHeight < 20;
+        setIsAtBottom(atBottom);
+      },
+      []
+    );
+
+    // Merge refs
+    React.useImperativeHandle(ref, () => drawerRef.current!);
+
+    // Setup: mount detection and body height tracking
+    React.useEffect(() => {
+      setMounted(true);
+      setBodyHeight(document.body.clientHeight);
+
+      const updateHeight = () => setBodyHeight(document.body.clientHeight);
+      window.addEventListener("resize", updateHeight);
+
+      return () => {
+        window.removeEventListener("resize", updateHeight);
+      };
+    }, []);
+
+    // Lock body scroll when open
+    React.useEffect(() => {
+      if (open && lockBodyScroll) {
+        document.body.style.overflow = "hidden";
+      } else if (lockBodyScroll) {
+        document.body.style.overflow = "";
+      }
+      return () => {
+        if (lockBodyScroll) {
+          document.body.style.overflow = "";
+        }
+      };
+    }, [open, lockBodyScroll]);
+
+    // Track nested drawer state - when another drawer opens on top of this one
+    // Shift the sticky wrapper down to make room for iOS safe area
+    React.useLayoutEffect(() => {
+      if (!open) {
+        // Reset when this drawer closes
+        drawerMountedRef.current = false;
+        ignoreNextDrawerOpenRef.current = true;
+        setIsNestedDrawerOpen(false);
+        return;
+      }
+
+      // After a delay, start listening for nested drawer events
+      // (ignore our own drawer-open event which fires when we open)
+      const mountTimer = setTimeout(() => {
+        drawerMountedRef.current = true;
+        ignoreNextDrawerOpenRef.current = false;
+      }, 200); // Wait for our own drawer's open event to pass
+
+      const handleNestedDrawerOpen = () => {
+        if (!drawerMountedRef.current || ignoreNextDrawerOpenRef.current) {
+          return; // Ignore our own drawer-open event
+        }
+        // A nested drawer opened on top of us - shift down for iOS safe area
+        // Clear any existing green bar timeout to prevent stacking
+        if (greenBarTimeoutRef.current) {
+          clearTimeout(greenBarTimeoutRef.current);
+        }
+        // Flash green bar and shift drawer down
+        setShowGreenBar(true);
+        setIsNestedDrawerOpen(true);
+        // Hide green bar after 60ms (triggers iOS safe area detection)
+        greenBarTimeoutRef.current = setTimeout(() => {
+          setShowGreenBar(false);
+          greenBarTimeoutRef.current = null;
+        }, 60);
+      };
+
+      const handleNestedDrawerClose = () => {
+        if (!drawerMountedRef.current) return;
+        setIsNestedDrawerOpen(false);
+      };
+
+      window.addEventListener("drawer-open", handleNestedDrawerOpen);
+      window.addEventListener("drawer-close", handleNestedDrawerClose);
+
+      return () => {
+        clearTimeout(mountTimer);
+        if (greenBarTimeoutRef.current) {
+          clearTimeout(greenBarTimeoutRef.current);
+          greenBarTimeoutRef.current = null;
+        }
+        window.removeEventListener("drawer-open", handleNestedDrawerOpen);
+        window.removeEventListener("drawer-close", handleNestedDrawerClose);
+      };
+    }, [open]);
+
+    // Calculate sticky wrapper top offset for nested drawer
+    const stickyTopOffset = isNestedDrawerOpen ? 10 : 0;
+
+    // Scroll trick to trigger blur rendering on sticky elements
+    // Some browsers don't apply backdrop-filter until scroll activity occurs
+    const scrollNudgeAmount = 50;
+    const scrollNudgeDuration = 10; // ms
+    const savedScrollY = React.useRef<number | null>(null);
+
+    // Custom smooth scroll with configurable duration
+    const smoothScrollTo = React.useCallback(
+      (target: number, duration: number) => {
+        const start = window.scrollY;
+        const distance = target - start;
+        const startTime = performance.now();
+
+        const animate = (currentTime: number) => {
+          const elapsed = currentTime - startTime;
+          const progress = Math.min(elapsed / duration, 1);
+          const eased = 1 - Math.pow(1 - progress, 3); // ease-out cubic
+          window.scrollTo(0, start + distance * eased);
+          if (progress < 1) requestAnimationFrame(animate);
+        };
+        requestAnimationFrame(animate);
+      },
+      []
+    );
+
+    const scrollNudgeDelay = 10; // ms - let blur appear first
+    React.useEffect(() => {
+      if (open && !isClosing) {
+        // Save position immediately
+        savedScrollY.current = document.documentElement.scrollTop;
+        // Skip scroll nudge if already scrolled past the nudge amount
+        if (savedScrollY.current > scrollNudgeAmount) {
+          return;
+        }
+        // Delay scroll nudge to let blur overlay appear first
+        const timer = setTimeout(() => {
+          smoothScrollTo(
+            savedScrollY.current! + scrollNudgeAmount,
+            scrollNudgeDuration
+          );
+        }, scrollNudgeDelay);
+        return () => clearTimeout(timer);
+      }
+    }, [open, isClosing, smoothScrollTo]);
+
+    // Restore scroll position when drawer closes via prop change (e.g., Done button)
+    // This handles the case where handleClose is not called (prop-driven close vs gesture close)
+    // When handleClose IS called (gesture close), it sets savedScrollY.current = null before
+    // open becomes false, so this effect won't double-restore.
+    React.useEffect(() => {
+      if (!open && !isClosing && savedScrollY.current !== null) {
+        const targetScroll = savedScrollY.current;
+        savedScrollY.current = null;
+        document.body.style.overflow = "";
+        window.scrollTo(0, targetScroll);
+      }
+    }, [open, isClosing]);
+
+    // Handle close with reversed sequence: drawer → header → blur
+    // Close timings (reverse of open)
+    const drawerExitDuration = 300; // ms - drawer slides down
+    const headerShiftDelay = 200; // ms - header shifts after drawer mostly gone
+    const blurFadeDelay = 250; // ms - blur starts fading near end
+    const blurFadeDuration = 150; // ms - blur fade animation
+    const totalCloseDuration = blurFadeDelay + blurFadeDuration;
+
+    // Small delay before drawer starts closing visually
+    const closeStartDelay = 50; // ms - give everything a moment before visual close
+
+    const handleClose = React.useCallback(() => {
+      // Brief pause before starting visual close
+      setTimeout(() => {
+        // Start drawer slide-out
+        setIsClosing(true);
+
+        // STEP 1: Restore scroll position FIRST (at 150ms)
+        // This must happen BEFORE removing data-drawer-open, so that when
+        // CSS scroll-driven animations resume, they calculate with the correct scroll position.
+        // Otherwise, the hero images will be at wrong scale/position (the "breaks half the time" bug).
+        const scrollRestoreDelay = 150;
+        setTimeout(() => {
+          document.body.style.overflow = "";
+          const targetScroll = savedScrollY.current;
+          if (targetScroll !== null) {
+            savedScrollY.current = null;
+            window.scrollTo(0, targetScroll);
+          }
+        }, scrollRestoreDelay);
+
+        // STEP 2: After scroll restored and drawer mostly gone, remove attribute (at 200ms)
+        // CSS animations will now resume with the correct scroll position
+        setTimeout(() => {
+          document.documentElement.removeAttribute("data-drawer-open");
+          window.dispatchEvent(new CustomEvent("drawer-close"));
+        }, headerShiftDelay);
+
+        // STEP 3: Start blur fade near the end (at 250ms)
+        setTimeout(() => {
+          setIsBlurFading(true);
+        }, blurFadeDelay);
+
+        // STEP 4: Finally unmount everything (at 400ms)
+        setTimeout(() => {
+          setIsClosing(false);
+          setIsBlurFading(false);
+          onOpenChange(false);
+        }, totalCloseDuration);
+      }, closeStartDelay);
+    }, [onOpenChange]);
+
+    // Escape key handler
+    React.useEffect(() => {
+      const handleEscape = (e: KeyboardEvent) => {
+        if (e.key === "Escape" && open && !isClosing) {
+          handleClose();
+        }
+      };
+      document.addEventListener("keydown", handleEscape);
+      return () => document.removeEventListener("keydown", handleEscape);
+    }, [open, isClosing, handleClose]);
+
+    // Swipe gesture handlers for bottom drawer
+    const handleTouchStart = React.useCallback(
+      (e: React.TouchEvent) => {
+        if (disableSwipeGestures) return;
+        startY.current = e.touches[0].clientY;
+        currentY.current = 0;
+        if (drawerRef.current) {
+          drawerRef.current.style.transition = "none";
+        }
+      },
+      [disableSwipeGestures]
+    );
+
+    const handleTouchMove = React.useCallback(
+      (e: React.TouchEvent) => {
+        if (disableSwipeGestures) return;
+        const delta = e.touches[0].clientY - startY.current;
+        // Only allow dragging down (positive delta)
+        currentY.current = Math.max(0, delta);
+        if (drawerRef.current) {
+          drawerRef.current.style.transform = `translateY(${currentY.current}px)`;
+        }
+      },
+      [disableSwipeGestures]
+    );
+
+    const handleTouchEnd = React.useCallback(() => {
+      if (disableSwipeGestures) return;
+      if (drawerRef.current) {
+        drawerRef.current.style.transition = `transform ${animationDuration}ms cubic-bezier(0.32, 0.72, 0, 1)`;
+        drawerRef.current.style.transform = "";
+      }
+
+      const threshold = 100;
+      if (currentY.current > threshold) {
+        handleClose();
+      }
+    }, [disableSwipeGestures, handleClose, animationDuration]);
+
+    // Show overlay immediately when open, drawer panel waits for delayedOpen
+    if (!mounted || (!open && !isClosing)) return null;
+
+    const showDrawerPanel = delayedOpen || isClosing;
+
+    const animationStyle = {
+      "--animation-duration": `${animationDuration}ms`,
+    } as React.CSSProperties;
+
+    return createPortal(
+      <div
+        style={{
+          position: "absolute",
+          top: 0,
+          left: 0,
+          width: "100%",
+          height: bodyHeight || "100%",
+          zIndex: 10000000,
+        }}
+        {...(useDialogRole ? { role: "dialog", "aria-modal": true } : {})}
+      >
+        {/* Overlay with blur */}
+        {showOverlay && (
+          <div
+            onClick={handleClose}
+            className={cn(
+              "absolute inset-0 backdrop-blur-lg",
+              isBlurFading && "animate-out fade-out"
+            )}
+            style={{
+              backgroundColor: `rgba(0,0,0,${overlayOpacity})`,
+              animationDuration: isBlurFading
+                ? `${blurFadeDuration}ms`
+                : undefined,
+            }}
+            aria-hidden="true"
+          />
+        )}
+
+        {/* Safe area bar - flashes briefly when nested drawer opens to trigger iOS safe area */}
+        {/* Must be above drawer overlay (z-index 10000000) */}
+        {showGreenBar && (
+          <div
+            className="fixed w-full bg-surface"
+            style={{
+              top: 0,
+              left: 0,
+              height: stickyTopOffset || 10,
+              zIndex: 10000001,
+            }}
+          />
+        )}
+
+        {/* Sticky wrapper to position drawer */}
+        {showDrawerPanel && (
+          <div
+            className={cn(
+              "sticky left-0 w-full flex pointer-events-none",
+              placement === "bottom" && "items-end justify-center",
+              // Side drawers: stretch to full height unless custom height is set (then top-align with padding)
+              placement === "left" && (height ? "items-start justify-start pt-4" : "items-stretch justify-start"),
+              placement === "right" && (height ? "items-start justify-end pt-4" : "items-stretch justify-end")
+            )}
+            style={{
+              height: "100dvh",
+              top: placement === "bottom" ? stickyTopOffset : 0,
+              transition: "top 10ms ease-out",
+            }}
+          >
+            {/* Drawer Panel */}
+            <Surface asChild variant="default">
+              <div
+                ref={drawerRef}
+                className={cn(
+                  "flex flex-col shadow-2xl pointer-events-auto",
+                  // Bottom drawer: rounded top, full width
+                  placement === "bottom" && "rounded-t-3xl w-full",
+                  // Left drawer: rounded right side, full height unless custom height
+                  placement === "left" && cn("rounded-r-2xl", !height && "h-full"),
+                  // Right drawer: rounded left side, full height unless custom height
+                  placement === "right" && cn("rounded-l-2xl", !height && "h-full"),
+                  // Animations based on placement
+                  placement === "bottom" && (isClosing
+                    ? "animate-out slide-out-to-bottom"
+                    : "animate-in slide-in-from-bottom"),
+                  placement === "left" && (isClosing
+                    ? "animate-out slide-out-to-left"
+                    : "animate-in slide-in-from-left"),
+                  placement === "right" && (isClosing
+                    ? "animate-out slide-out-to-right"
+                    : "animate-in slide-in-from-right"),
+                  className
+                )}
+                style={{
+                  // Bottom drawer: use height/maxHeight
+                  ...(placement === "bottom" ? {
+                    height: heightRatio ? `${heightRatio * 100}vh` : height,
+                    maxHeight: (heightRatio || height) ? undefined : maxHeight,
+                  } : {}),
+                  // Side drawers: use width/maxWidth, custom height or full height
+                  ...(placement !== "bottom" ? {
+                    width: width || maxWidth,
+                    maxWidth: maxWidth,
+                    height: height || "100%",
+                  } : {}),
+                  animationDuration: isClosing
+                    ? `${drawerExitDuration}ms`
+                    : `${animationDuration}ms`,
+                  animationTimingFunction: isClosing
+                    ? "ease-in"
+                    : "cubic-bezier(0.32, 0.72, 0, 1)",
+                  animationFillMode: "forwards",
+                  ...animationStyle,
+                }}
+                onClick={(e) => e.stopPropagation()}
+                {...props}
+              >
+                {/* Drag handle zone - only for bottom drawer */}
+                {placement === "bottom" && !disableSwipeGestures && (
+                  <div
+                    onTouchStart={handleTouchStart}
+                    onTouchMove={handleTouchMove}
+                    onTouchEnd={handleTouchEnd}
+                    className={cn(
+                      "cursor-grab active:cursor-grabbing flex-shrink-0",
+                      hideHandle && "absolute top-0 left-0 right-0 h-8 z-10"
+                    )}
+                    style={{ touchAction: "none" }}
+                  >
+                    {!hideHandle && (
+                      <div className="flex justify-center pt-3 pb-2">
+                        <div
+                          className="h-1 w-10 rounded-full bg-muted-foreground/30"
+                          aria-hidden="true"
+                        />
+                      </div>
+                    )}
+                  </div>
+                )}
+
+                {/* Content area with scroll fade */}
+                <div className="flex-1 overflow-hidden flex flex-col relative min-h-0">
+                  <div
+                    ref={contentRef}
+                    className="flex-1 flex flex-col overflow-y-auto min-h-0"
+                    style={{
+                      WebkitOverflowScrolling: "touch",
+                      overscrollBehavior: "contain",
+                    }}
+                    onScroll={handleScroll}
+                  >
+                    {children}
+                  </div>
+
+                  {/* Gradient fade - hides when scrolled to bottom */}
+                  {showScrollFade && (
+                    <div
+                      className={cn(
+                        "absolute bottom-0 left-0 right-0 h-20 pointer-events-none transition-opacity duration-300 z-10",
+                        isAtBottom ? "opacity-0" : "opacity-100"
+                      )}
+                      style={{
+                        background: scrollFadeColor
+                          ? `linear-gradient(to top, ${scrollFadeColor}, transparent)`
+                          : "linear-gradient(to top, var(--color-drawer-bg, var(--surface)), transparent)",
+                      }}
+                      aria-hidden="true"
+                    />
+                  )}
+                </div>
+
+                {/* Bottom safe area padding - inherits drawer background */}
+                <div
+                  className="flex-shrink-0"
+                  style={{ paddingBottom: "env(safe-area-inset-bottom)" }}
+                />
+              </div>
+            </Surface>
+          </div>
+        )}
+      </div>,
+      document.body
+    );
+  }
+);
+DrawerContent.displayName = "DrawerContent";
+
+// ============================================================================
+// DrawerHeader
+// ============================================================================
+
+const DrawerHeader = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("grid gap-1.5 p-4 text-center sm:text-left", className)}
+    {...props}
+  />
+);
+DrawerHeader.displayName = "DrawerHeader";
+
+// ============================================================================
+// DrawerFooter
+// ============================================================================
+
+const DrawerFooter = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("mt-auto flex flex-col gap-2 p-4", className)}
+    {...props}
+  />
+);
+DrawerFooter.displayName = "DrawerFooter";
+
+// ============================================================================
+// DrawerTitle
+// ============================================================================
+
+const DrawerTitle = React.forwardRef<
+  HTMLHeadingElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h2
+    ref={ref}
+    className={cn(
+      "text-lg font-semibold leading-none tracking-tight",
+      className
+    )}
+    {...props}
+  />
+));
+DrawerTitle.displayName = "DrawerTitle";
+
+// ============================================================================
+// DrawerDescription
+// ============================================================================
+
+const DrawerDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={cn("text-sm text-muted-foreground", className)}
+    {...props}
+  />
+));
+DrawerDescription.displayName = "DrawerDescription";
+
+// Primary exports
+export {
+  Drawer,
+  DrawerTrigger,
+  DrawerClose,
+  DrawerContent,
+  DrawerHeader,
+  DrawerFooter,
+  DrawerTitle,
+  DrawerDescription,
+};
+
+// Legacy IOS-prefixed exports (for backwards compatibility during migration)
+export {
+  Drawer as IOSDrawer,
+  DrawerTrigger as IOSDrawerTrigger,
+  DrawerClose as IOSDrawerClose,
+  DrawerContent as IOSDrawerContent,
+  DrawerHeader as IOSDrawerHeader,
+  DrawerFooter as IOSDrawerFooter,
+  DrawerTitle as IOSDrawerTitle,
+  DrawerDescription as IOSDrawerDescription,
+};