@neynar/ui 0.1.1

package/src/components/ui/drawer.tsx

@@ -0,0 +1,273 @@
+import * as React from "react";
+import { Drawer as DrawerPrimitive } from "vaul";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Drawer component for mobile-optimized sliding panels
+ *
+ * A flexible drawer component built on Vaul that creates sliding panel interfaces
+ * from screen edges. Designed primarily for mobile experiences with touch gestures,
+ * swipe-to-dismiss functionality, and natural drag interactions. Supports multiple
+ * directions (top, bottom, left, right) and responsive behavior patterns.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with trigger and content
+ * <Drawer>
+ *   <DrawerTrigger asChild>
+ *     <Button>Open Settings</Button>
+ *   </DrawerTrigger>
+ *   <DrawerContent>
+ *     <DrawerHeader>
+ *       <DrawerTitle>Settings</DrawerTitle>
+ *       <DrawerDescription>
+ *         Adjust your preferences below
+ *       </DrawerDescription>
+ *     </DrawerHeader>
+ *     <div className="p-4">
+ *       Content goes here
+ *     </div>
+ *     <DrawerFooter>
+ *       <Button>Save</Button>
+ *       <DrawerClose asChild>
+ *         <Button variant="outline">Cancel</Button>
+ *       </DrawerClose>
+ *     </DrawerFooter>
+ *   </DrawerContent>
+ * </Drawer>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled drawer with state management
+ * const [open, setOpen] = useState(false)
+ *
+ * <Drawer open={open} onOpenChange={setOpen}>
+ *   <DrawerContent>
+ *     <DrawerHeader>
+ *       <DrawerTitle>Controlled Drawer</DrawerTitle>
+ *     </DrawerHeader>
+ *     <div className="p-4">
+ *       <Button onClick={() => setOpen(false)}>Close Programmatically</Button>
+ *     </div>
+ *   </DrawerContent>
+ * </Drawer>
+ * ```
+ *
+ * @accessibility
+ * - Focus management with focus trap when open
+ * - Keyboard navigation with Escape to close
+ * - Screen reader announcements for state changes
+ * - Touch gestures for swipe-to-dismiss
+ * - Backdrop click to close
+ * - ARIA attributes for modal behavior
+ * - Scroll lock on background content
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/drawer} shadcn/ui Drawer documentation
+ * @since 1.0.0
+ * @see {@link Dialog} For modal overlays without slide animation
+ * @see {@link Sheet} For desktop-optimized side panels
+ */
+/**
+ * Root drawer component that manages the drawer state and context
+ *
+ * @param props - All props from Vaul's Drawer.Root component
+ * @param props.open - Whether the drawer is open (controlled mode)
+ * @param props.onOpenChange - Callback when drawer open state changes
+ * @param props.direction - Direction from which drawer slides ("bottom" | "top" | "left" | "right")
+ * @param props.modal - Whether drawer should be modal (default: true)
+ * @param props.dismissible - Whether drawer can be dismissed by dragging (default: true)
+ */
+function Drawer({
+  ...props
+}: React.ComponentProps<typeof DrawerPrimitive.Root>) {
+  return <DrawerPrimitive.Root data-slot="drawer" {...props} />;
+}
+
+/**
+ * Trigger element that opens the drawer when activated
+ *
+ * @param props.asChild - Render as child element instead of button
+ */
+function DrawerTrigger({
+  ...props
+}: React.ComponentProps<typeof DrawerPrimitive.Trigger>) {
+  return <DrawerPrimitive.Trigger data-slot="drawer-trigger" {...props} />;
+}
+
+/**
+ * Portal component for rendering drawer content outside the normal DOM tree
+ *
+ * @param props.container - Container element to render into (default: document.body)
+ */
+function DrawerPortal({
+  ...props
+}: React.ComponentProps<typeof DrawerPrimitive.Portal>) {
+  return <DrawerPrimitive.Portal data-slot="drawer-portal" {...props} />;
+}
+
+/**
+ * Close trigger that dismisses the drawer when activated
+ *
+ * @param props.asChild - Render as child element instead of button
+ */
+function DrawerClose({
+  ...props
+}: React.ComponentProps<typeof DrawerPrimitive.Close>) {
+  return <DrawerPrimitive.Close data-slot="drawer-close" {...props} />;
+}
+
+/**
+ * Overlay backdrop that appears behind the drawer content
+ *
+ * @param props.className - Additional CSS classes to apply
+ */
+function DrawerOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof DrawerPrimitive.Overlay>) {
+  return (
+    <DrawerPrimitive.Overlay
+      data-slot="drawer-overlay"
+      className={cn(
+        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Main content container for the drawer with responsive positioning
+ *
+ * Automatically includes overlay and portal rendering. Supports four directions:
+ * - bottom: Slides up from bottom (default mobile pattern)
+ * - top: Slides down from top
+ * - left: Slides in from left edge
+ * - right: Slides in from right edge
+ *
+ * @param props.className - Additional CSS classes to apply
+ * @param props.children - Content to render inside the drawer
+ */
+function DrawerContent({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof DrawerPrimitive.Content>) {
+  return (
+    <DrawerPortal data-slot="drawer-portal">
+      <DrawerOverlay />
+      <DrawerPrimitive.Content
+        data-slot="drawer-content"
+        className={cn(
+          "group/drawer-content bg-background fixed z-50 flex h-auto flex-col",
+          "data-[vaul-drawer-direction=top]:inset-x-0 data-[vaul-drawer-direction=top]:top-0 data-[vaul-drawer-direction=top]:mb-24 data-[vaul-drawer-direction=top]:max-h-[80vh] data-[vaul-drawer-direction=top]:rounded-b-lg data-[vaul-drawer-direction=top]:border-b",
+          "data-[vaul-drawer-direction=bottom]:inset-x-0 data-[vaul-drawer-direction=bottom]:bottom-0 data-[vaul-drawer-direction=bottom]:mt-24 data-[vaul-drawer-direction=bottom]:max-h-[80vh] data-[vaul-drawer-direction=bottom]:rounded-t-lg data-[vaul-drawer-direction=bottom]:border-t",
+          "data-[vaul-drawer-direction=right]:inset-y-0 data-[vaul-drawer-direction=right]:right-0 data-[vaul-drawer-direction=right]:w-3/4 data-[vaul-drawer-direction=right]:border-l data-[vaul-drawer-direction=right]:sm:max-w-sm",
+          "data-[vaul-drawer-direction=left]:inset-y-0 data-[vaul-drawer-direction=left]:left-0 data-[vaul-drawer-direction=left]:w-3/4 data-[vaul-drawer-direction=left]:border-r data-[vaul-drawer-direction=left]:sm:max-w-sm",
+          className,
+        )}
+        {...props}
+      >
+        <div className="bg-muted mx-auto mt-4 hidden h-2 w-[100px] shrink-0 rounded-full group-data-[vaul-drawer-direction=bottom]/drawer-content:block" />
+        {children}
+      </DrawerPrimitive.Content>
+    </DrawerPortal>
+  );
+}
+
+/**
+ * Header section of the drawer containing title and description
+ *
+ * Automatically centers text for bottom/top drawers and left-aligns for side drawers
+ * on larger screens. Should contain DrawerTitle and optionally DrawerDescription.
+ *
+ * @param props.className - Additional CSS classes to apply
+ */
+function DrawerHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="drawer-header"
+      className={cn(
+        "flex flex-col gap-0.5 p-4 group-data-[vaul-drawer-direction=bottom]/drawer-content:text-center group-data-[vaul-drawer-direction=top]/drawer-content:text-center md:gap-1.5 md:text-left",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Footer section of the drawer containing action buttons
+ *
+ * Positioned at the bottom of the drawer with automatic top margin to push
+ * content to the bottom. Typically contains primary actions and DrawerClose.
+ *
+ * @param props.className - Additional CSS classes to apply
+ */
+function DrawerFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="drawer-footer"
+      className={cn("mt-auto flex flex-col gap-2 p-4", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Accessible title element for the drawer
+ *
+ * Required for accessibility - announces the drawer purpose to screen readers.
+ * Automatically styled with semibold font weight.
+ *
+ * @param props.className - Additional CSS classes to apply
+ */
+function DrawerTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof DrawerPrimitive.Title>) {
+  return (
+    <DrawerPrimitive.Title
+      data-slot="drawer-title"
+      className={cn("text-foreground font-semibold", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Optional description element providing additional context
+ *
+ * Provides supplementary information about the drawer's content or purpose.
+ * Styled with muted foreground color and smaller text size.
+ *
+ * @param props.className - Additional CSS classes to apply
+ */
+function DrawerDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof DrawerPrimitive.Description>) {
+  return (
+    <DrawerPrimitive.Description
+      data-slot="drawer-description"
+      className={cn("text-muted-foreground text-sm", className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Drawer,
+  DrawerPortal,
+  DrawerOverlay,
+  DrawerTrigger,
+  DrawerClose,
+  DrawerContent,
+  DrawerHeader,
+  DrawerFooter,
+  DrawerTitle,
+  DrawerDescription,
+};