@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/drawer.tsx

@@ -4,16 +4,166 @@ import { Drawer as DrawerPrimitive } from "vaul";
 import { cn } from "@/lib/utils";
 
 /**
- * Drawer component for mobile-optimized sliding panels
+ * Props for the root Drawer component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Vaul inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DrawerDocsProps = {
+  /** Initial open state when not controlling the drawer @default false */
+  defaultOpen?: boolean;
+  /** Controlled open state - when provided, drawer becomes controlled */
+  open?: boolean;
+  /** Callback fired when the drawer open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Whether the drawer should be modal, preventing interaction with background elements @default true */
+  modal?: boolean;
+  /** Container element to portal the drawer into @default document.body */
+  container?: HTMLElement;
+  /** Direction from which the drawer slides in @default "bottom" */
+  direction?: "top" | "bottom" | "left" | "right";
+  /** Callback fired after open or close animation completes */
+  onAnimationEnd?: (open: boolean) => void;
+  /** Whether the drawer can be dismissed via drag gestures or outside clicks @default true */
+  dismissible?: boolean;
+  /** When true, only the handle area can be used for dragging @default false */
+  handleOnly?: boolean;
+  /** Whether to automatically reposition input elements when drawer opens @default true */
+  repositionInputs?: boolean;
+  /** Array of snap points as percentages (0-100) or pixel values for drawer height */
+  snapPoints?: (number | string)[];
+  /** Controlled active snap point index */
+  activeSnapPoint?: number;
+  /** Callback to handle snap point changes */
+  setActiveSnapPoint?: (snapPoint: number) => void;
+  /** Index at which overlay starts fading when using snap points */
+  fadeFromIndex?: number;
+  /** Disables velocity-based snap point skipping, ensuring sequential navigation @default false */
+  snapToSequentialPoint?: boolean;
+  /** Children components to render within the drawer context */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DrawerPrimitive.Root>;
+
+/**
+ * Props for DrawerTrigger component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Vaul inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DrawerTriggerDocsProps = {
+  /** Render as a child element instead of the default button @default false */
+  asChild?: boolean;
+  /** Content to render as the trigger */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DrawerPrimitive.Trigger>;
+
+/**
+ * Props for DrawerPortal component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Vaul inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DrawerPortalDocsProps = {
+  /** Container element to render the portal into @default document.body */
+  container?: HTMLElement;
+  /** Content to render in the portal */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DrawerPrimitive.Portal>;
+
+/**
+ * Props for DrawerClose component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Vaul inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DrawerCloseDocsProps = {
+  /** Render as a child element instead of the default button @default false */
+  asChild?: boolean;
+  /** Content to render as the close trigger */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DrawerPrimitive.Close>;
+
+/**
+ * Props for DrawerOverlay component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Vaul inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DrawerOverlayDocsProps = {
+  /** Additional CSS classes to apply to the overlay */
+  className?: string;
+} & React.ComponentProps<typeof DrawerPrimitive.Overlay>;
+
+/**
+ * Props for DrawerContent component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Vaul inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DrawerContentDocsProps = {
+  /** Additional CSS classes to apply to the content container */
+  className?: string;
+  /** Content to render inside the drawer */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DrawerPrimitive.Content>;
+
+/**
+ * Props for DrawerHeader component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace HTML div attributes
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DrawerHeaderDocsProps = {
+  /** Additional CSS classes to apply to the header */
+  className?: string;
+  /** Header content, typically DrawerTitle and DrawerDescription */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for DrawerFooter component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace HTML div attributes
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DrawerFooterDocsProps = {
+  /** Additional CSS classes to apply to the footer */
+  className?: string;
+  /** Footer content, typically action buttons and DrawerClose */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for DrawerTitle component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Vaul inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DrawerTitleDocsProps = {
+  /** Additional CSS classes to apply to the title */
+  className?: string;
+  /** Title text content */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DrawerPrimitive.Title>;
+
+/**
+ * Props for DrawerDescription component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Vaul inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DrawerDescriptionDocsProps = {
+  /** Additional CSS classes to apply to the description */
+  className?: string;
+  /** Description text content */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof DrawerPrimitive.Description>;
+
+/**
+ * Drawer - Mobile-optimized sliding panel component
  *
  * 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.
+ * directions (top, bottom, left, right) with snap points and responsive behavior.
+ *
+ * Built on Vaul library which provides excellent performance, accessibility, and
+ * natural touch interactions. The drawer automatically handles focus management,
+ * scroll locking, and ARIA attributes for screen readers.
  *
  * @example
  * ```tsx
- * // Basic usage with trigger and content
+ * // Basic drawer with trigger and content
  * <Drawer>
  *   <DrawerTrigger asChild>
  *     <Button>Open Settings</Button>
@@ -26,7 +176,7 @@ import { cn } from "@/lib/utils";
  *       </DrawerDescription>
  *     </DrawerHeader>
  *     <div className="p-4">
- *       Content goes here
+ *       <p>Content goes here</p>
  *     </div>
  *     <DrawerFooter>
  *       <Button>Save</Button>
@@ -55,73 +205,209 @@ import { cn } from "@/lib/utils";
  * </Drawer>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Drawer with snap points for multiple heights
+ * <Drawer snapPoints={[0.4, 0.8]} fadeFromIndex={0}>
+ *   <DrawerTrigger asChild>
+ *     <Button>Open with Snap Points</Button>
+ *   </DrawerTrigger>
+ *   <DrawerContent>
+ *     <DrawerHeader>
+ *       <DrawerTitle>Expandable Drawer</DrawerTitle>
+ *       <DrawerDescription>
+ *         Drag to resize between 40% and 80% heights
+ *       </DrawerDescription>
+ *     </DrawerHeader>
+ *     <div className="flex-1 p-4">
+ *       <p>Content that can be viewed at different heights</p>
+ *     </div>
+ *   </DrawerContent>
+ * </Drawer>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Side drawer from left or right
+ * <Drawer direction="right">
+ *   <DrawerTrigger asChild>
+ *     <Button>Open Side Panel</Button>
+ *   </DrawerTrigger>
+ *   <DrawerContent>
+ *     <DrawerHeader>
+ *       <DrawerTitle>Side Navigation</DrawerTitle>
+ *     </DrawerHeader>
+ *     <div className="flex-1 p-4">
+ *       <nav>Navigation items here</nav>
+ *     </div>
+ *   </DrawerContent>
+ * </Drawer>
+ * ```
+ *
  * @accessibility
- * - Focus management with focus trap when open
- * - Keyboard navigation with Escape to close
+ * - Focus management with focus trap when drawer is open
+ * - Keyboard navigation with Escape key 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
+ * - Touch gestures for intuitive swipe-to-dismiss
+ * - Backdrop click to close (when dismissible)
+ * - ARIA attributes for proper modal behavior
+ * - Scroll lock prevents background scrolling
+ * - DrawerTitle required for accessibility
+ * - Sequential keyboard navigation within drawer content
  *
+ * @see {@link https://vaul.emilkowal.ski} Vaul drawer library documentation
  * @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
+ * @since 1.0.0
  */
-/**
- * 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>) {
+function Drawer(props: React.ComponentProps<typeof DrawerPrimitive.Root>) {
   return <DrawerPrimitive.Root data-slot="drawer" {...props} />;
 }
 
 /**
- * Trigger element that opens the drawer when activated
+ * DrawerTrigger - Interactive element that opens the drawer
+ *
+ * The trigger element that users interact with to open the drawer. By default
+ * renders as a button, but can be composed with other elements using asChild.
+ * Supports all standard button attributes and event handlers.
+ *
+ * @example
+ * ```tsx
+ * // Default button trigger
+ * <DrawerTrigger>Open Drawer</DrawerTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Composed with custom button component
+ * <DrawerTrigger asChild>
+ *   <Button variant="outline">Open Settings</Button>
+ * </DrawerTrigger>
+ * ```
  *
- * @param props.asChild - Render as child element instead of button
+ * @accessibility
+ * - Announces drawer state to screen readers
+ * - Receives keyboard focus
+ * - Activates on Space and Enter keys
+ *
+ * @see {@link https://vaul.emilkowal.ski/api} Vaul Trigger API
  */
-function DrawerTrigger({
-  ...props
-}: React.ComponentProps<typeof DrawerPrimitive.Trigger>) {
+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
+ * DrawerPortal - Portal component for rendering drawer outside DOM hierarchy
+ *
+ * Renders the drawer content into a different part of the DOM tree, typically
+ * document.body, to ensure proper stacking context and avoid z-index issues.
+ * Automatically used by DrawerContent but can be used manually for custom layouts.
+ *
+ * @example
+ * ```tsx
+ * // Custom portal container
+ * const portalContainer = document.getElementById('drawer-root')
+ *
+ * <DrawerPortal container={portalContainer}>
+ *   <DrawerOverlay />
+ *   <DrawerContent>
+ *     Drawer content
+ *   </DrawerContent>
+ * </DrawerPortal>
+ * ```
  *
- * @param props.container - Container element to render into (default: document.body)
+ * @accessibility
+ * - Maintains proper focus management across portal boundaries
+ * - Preserves screen reader navigation context
+ *
+ * @see {@link https://vaul.emilkowal.ski/api} Vaul Portal API
  */
-function DrawerPortal({
-  ...props
-}: React.ComponentProps<typeof DrawerPrimitive.Portal>) {
+function DrawerPortal(
+  props: React.ComponentProps<typeof DrawerPrimitive.Portal>,
+) {
   return <DrawerPrimitive.Portal data-slot="drawer-portal" {...props} />;
 }
 
 /**
- * Close trigger that dismisses the drawer when activated
+ * DrawerClose - Interactive element that closes the drawer
+ *
+ * Trigger element that closes the drawer when activated. Can be placed anywhere
+ * within the drawer content. By default renders as a button but can be composed
+ * with other elements using asChild. Multiple close triggers can exist within
+ * a single drawer.
+ *
+ * @example
+ * ```tsx
+ * // Default close button
+ * <DrawerClose>Close</DrawerClose>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Composed with custom button
+ * <DrawerClose asChild>
+ *   <Button variant="ghost">Cancel</Button>
+ * </DrawerClose>
+ * ```
  *
- * @param props.asChild - Render as child element instead of button
+ * @example
+ * ```tsx
+ * // Icon-only close button
+ * <DrawerClose asChild>
+ *   <Button size="icon" variant="ghost">
+ *     <X className="h-4 w-4" />
+ *   </Button>
+ * </DrawerClose>
+ * ```
+ *
+ * @accessibility
+ * - Receives keyboard focus
+ * - Activates on Space and Enter keys
+ * - Announces close action to screen readers
+ *
+ * @see {@link https://vaul.emilkowal.ski/api} Vaul Close API
  */
-function DrawerClose({
-  ...props
-}: React.ComponentProps<typeof DrawerPrimitive.Close>) {
+function DrawerClose(
+  props: React.ComponentProps<typeof DrawerPrimitive.Close>,
+) {
   return <DrawerPrimitive.Close data-slot="drawer-close" {...props} />;
 }
 
 /**
- * Overlay backdrop that appears behind the drawer content
+ * DrawerOverlay - Semi-transparent backdrop behind the drawer
+ *
+ * Creates a semi-transparent overlay that covers the entire viewport behind
+ * the drawer content. Provides visual separation and can be clicked to close
+ * the drawer (when dismissible is true). Automatically fades in/out with
+ * smooth animations.
+ *
+ * @example
+ * ```tsx
+ * // Default overlay with standard opacity
+ * <DrawerOverlay />
+ * ```
  *
- * @param props.className - Additional CSS classes to apply
+ * @example
+ * ```tsx
+ * // Custom overlay with different opacity
+ * <DrawerOverlay className="bg-black/30" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Overlay with blur effect
+ * <DrawerOverlay className="bg-black/20 backdrop-blur-sm" />
+ * ```
+ *
+ * @accessibility
+ * - Click target for closing drawer (when dismissible)
+ * - Prevents interaction with background content
+ * - Does not interfere with screen reader navigation
+ *
+ * @see {@link https://vaul.emilkowal.ski/api} Vaul Overlay API
  */
 function DrawerOverlay({
   className,
@@ -140,16 +426,52 @@ function DrawerOverlay({
 }
 
 /**
- * Main content container for the drawer with responsive positioning
+ * DrawerContent - Main container for drawer content with responsive positioning
+ *
+ * The primary content container that holds all drawer elements. Automatically
+ * handles portal rendering, overlay display, and responsive positioning based
+ * on the drawer direction. Includes a drag handle for bottom drawers and
+ * responsive styling for all four directions.
  *
- * 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
+ * Supports flexible layouts with proper spacing for headers, content areas,
+ * and footers. Automatically constrains height/width based on direction and
+ * viewport size.
  *
- * @param props.className - Additional CSS classes to apply
- * @param props.children - Content to render inside the drawer
+ * @example
+ * ```tsx
+ * // Basic content structure
+ * <DrawerContent>
+ *   <DrawerHeader>
+ *     <DrawerTitle>Title</DrawerTitle>
+ *     <DrawerDescription>Description</DrawerDescription>
+ *   </DrawerHeader>
+ *   <div className="p-4">
+ *     Main content area
+ *   </div>
+ *   <DrawerFooter>
+ *     <Button>Action</Button>
+ *   </DrawerFooter>
+ * </DrawerContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styled content
+ * <DrawerContent className="max-w-md mx-auto">
+ *   <div className="flex-1 overflow-y-auto p-6">
+ *     <h2>Custom Layout</h2>
+ *     <p>Scrollable content area</p>
+ *   </div>
+ * </DrawerContent>
+ * ```
+ *
+ * @accessibility
+ * - Focus trap keeps focus within drawer content
+ * - Proper ARIA modal attributes
+ * - Sequential keyboard navigation
+ * - Screen reader content announcements
+ *
+ * @see {@link https://vaul.emilkowal.ski/api} Vaul Content API
  */
 function DrawerContent({
   className,
@@ -179,14 +501,56 @@ function DrawerContent({
 }
 
 /**
- * Header section of the drawer containing title and description
+ * DrawerHeader - Header section 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.
+ * Standardized header area for drawer content with proper spacing and responsive
+ * text alignment. Centers text for bottom/top drawers on mobile and left-aligns
+ * on larger screens. Should contain DrawerTitle and optionally DrawerDescription
+ * for accessibility compliance.
+ *
+ * @example
+ * ```tsx
+ * // Standard header with title and description
+ * <DrawerHeader>
+ *   <DrawerTitle>Settings</DrawerTitle>
+ *   <DrawerDescription>
+ *     Manage your account preferences and settings
+ *   </DrawerDescription>
+ * </DrawerHeader>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Title-only header
+ * <DrawerHeader>
+ *   <DrawerTitle>Notifications</DrawerTitle>
+ * </DrawerHeader>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom header with additional content
+ * <DrawerHeader className="border-b">
+ *   <DrawerTitle>Profile</DrawerTitle>
+ *   <DrawerDescription>Update your profile information</DrawerDescription>
+ *   <div className="mt-2">
+ *     <Badge variant="outline">Pro User</Badge>
+ *   </div>
+ * </DrawerHeader>
+ * ```
+ *
+ * @accessibility
+ * - Should contain DrawerTitle for screen reader identification
+ * - Optional DrawerDescription provides additional context
+ * - Proper heading hierarchy maintained
  *
- * @param props.className - Additional CSS classes to apply
+ * @see {@link DrawerTitle} For accessible drawer titles
+ * @see {@link DrawerDescription} For additional context
  */
-function DrawerHeader({ className, ...props }: React.ComponentProps<"div">) {
+function DrawerHeader({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
   return (
     <div
       data-slot="drawer-header"
@@ -200,14 +564,63 @@ function DrawerHeader({ className, ...props }: React.ComponentProps<"div">) {
 }
 
 /**
- * Footer section of the drawer containing action buttons
+ * DrawerFooter - Footer section for action buttons and controls
+ *
+ * Standardized footer area positioned at the bottom of the drawer with automatic
+ * top margin to push content down. Typically contains primary actions, secondary
+ * actions, and DrawerClose triggers. Uses flexbox column layout with consistent
+ * spacing between elements.
+ *
+ * @example
+ * ```tsx
+ * // Standard footer with primary and secondary actions
+ * <DrawerFooter>
+ *   <Button>Save Changes</Button>
+ *   <DrawerClose asChild>
+ *     <Button variant="outline">Cancel</Button>
+ *   </DrawerClose>
+ * </DrawerFooter>
+ * ```
  *
- * Positioned at the bottom of the drawer with automatic top margin to push
- * content to the bottom. Typically contains primary actions and DrawerClose.
+ * @example
+ * ```tsx
+ * // Footer with multiple action groups
+ * <DrawerFooter>
+ *   <div className="flex gap-2">
+ *     <Button className="flex-1">Save</Button>
+ *     <Button variant="outline" className="flex-1">Save as Draft</Button>
+ *   </div>
+ *   <DrawerClose asChild>
+ *     <Button variant="ghost" size="sm">Cancel</Button>
+ *   </DrawerClose>
+ * </DrawerFooter>
+ * ```
  *
- * @param props.className - Additional CSS classes to apply
+ * @example
+ * ```tsx
+ * // Footer with text and actions
+ * <DrawerFooter>
+ *   <p className="text-sm text-muted-foreground text-center">
+ *     Changes will be saved automatically
+ *   </p>
+ *   <DrawerClose asChild>
+ *     <Button>Done</Button>
+ *   </DrawerClose>
+ * </DrawerFooter>
+ * ```
+ *
+ * @accessibility
+ * - Action buttons receive proper focus order
+ * - Primary actions should be visually prominent
+ * - Close actions clearly labeled for screen readers
+ *
+ * @see {@link DrawerClose} For close action triggers
+ * @see {@link Button} For consistent action button styling
  */
-function DrawerFooter({ className, ...props }: React.ComponentProps<"div">) {
+function DrawerFooter({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
   return (
     <div
       data-slot="drawer-footer"
@@ -218,12 +631,44 @@ function DrawerFooter({ className, ...props }: React.ComponentProps<"div">) {
 }
 
 /**
- * Accessible title element for the drawer
+ * DrawerTitle - Accessible title element for the drawer
+ *
+ * Required accessibility element that announces the drawer's purpose to screen
+ * readers and provides a clear heading for the content. Should be included in
+ * every drawer for proper accessibility compliance. Automatically styled with
+ * appropriate font weight and color.
+ *
+ * @example
+ * ```tsx
+ * // Standard drawer title
+ * <DrawerTitle>Account Settings</DrawerTitle>
+ * ```
  *
- * Required for accessibility - announces the drawer purpose to screen readers.
- * Automatically styled with semibold font weight.
+ * @example
+ * ```tsx
+ * // Custom styled title
+ * <DrawerTitle className="text-lg font-bold text-primary">
+ *   Welcome Back!
+ * </DrawerTitle>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Title with dynamic content
+ * <DrawerTitle>
+ *   {isEditing ? "Edit Profile" : "View Profile"}
+ * </DrawerTitle>
+ * ```
+ *
+ * @accessibility
+ * - REQUIRED for screen reader accessibility
+ * - Announces drawer content purpose
+ * - Provides semantic heading structure
+ * - Should be descriptive and concise
+ * - Automatically receives proper ARIA attributes
  *
- * @param props.className - Additional CSS classes to apply
+ * @see {@link https://vaul.emilkowal.ski/api} Vaul Title API
+ * @see {@link DrawerDescription} For additional context
  */
 function DrawerTitle({
   className,
@@ -239,12 +684,46 @@ function DrawerTitle({
 }
 
 /**
- * Optional description element providing additional context
+ * DrawerDescription - Optional description providing additional context
  *
- * Provides supplementary information about the drawer's content or purpose.
- * Styled with muted foreground color and smaller text size.
+ * Supplementary text element that provides additional information about the
+ * drawer's content, purpose, or instructions. Enhances accessibility by giving
+ * users more context about what they'll find in the drawer. Styled with muted
+ * colors and smaller text to maintain visual hierarchy.
+ *
+ * @example
+ * ```tsx
+ * // Basic description
+ * <DrawerDescription>
+ *   Manage your account preferences and privacy settings
+ * </DrawerDescription>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Description with instructions
+ * <DrawerDescription>
+ *   Select the options below to customize your experience.
+ *   Changes will be saved automatically.
+ * </DrawerDescription>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styled description
+ * <DrawerDescription className="text-xs text-orange-600">
+ *   Warning: These changes cannot be undone
+ * </DrawerDescription>
+ * ```
+ *
+ * @accessibility
+ * - Provides additional context for screen readers
+ * - Automatically linked to DrawerTitle via ARIA
+ * - Should be concise and informative
+ * - Enhances understanding of drawer purpose
  *
- * @param props.className - Additional CSS classes to apply
+ * @see {@link https://vaul.emilkowal.ski/api} Vaul Description API
+ * @see {@link DrawerTitle} For primary drawer identification
  */
 function DrawerDescription({
   className,