@neynar/ui 0.1.1

package/src/components/ui/sheet.tsx

@@ -0,0 +1,495 @@
+import * as React from "react";
+import * as SheetPrimitive from "@radix-ui/react-dialog";
+import { XIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Sheet - A slide-out panel that displays supplementary content
+ *
+ * A versatile sheet component that slides in from any edge of the screen to display
+ * supplementary content without fully blocking the main interface. Built on Radix UI
+ * Dialog primitives with smooth animations and comprehensive accessibility support.
+ *
+ * Sheets are ideal for:
+ * - Mobile navigation menus
+ * - Settings panels and configuration forms
+ * - Contextual information displays
+ * - Secondary actions that don't require full attention
+ * - Filters and search interfaces
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic sheet from right side (default)
+ * <Sheet>
+ *   <SheetTrigger asChild>
+ *     <Button>Open Settings</Button>
+ *   </SheetTrigger>
+ *   <SheetContent>
+ *     <SheetHeader>
+ *       <SheetTitle>Settings</SheetTitle>
+ *       <SheetDescription>
+ *         Configure your application preferences.
+ *       </SheetDescription>
+ *     </SheetHeader>
+ *     <div className="py-4">
+ *       <p>Settings content here</p>
+ *     </div>
+ *     <SheetFooter>
+ *       <Button type="submit">Save Changes</Button>
+ *     </SheetFooter>
+ *   </SheetContent>
+ * </Sheet>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Sheet from different sides with controlled state
+ * function NavigationSheet() {
+ *   const [open, setOpen] = useState(false)
+ *
+ *   return (
+ *     <Sheet open={open} onOpenChange={setOpen}>
+ *       <SheetTrigger asChild>
+ *         <Button variant="outline">Menu</Button>
+ *       </SheetTrigger>
+ *       <SheetContent side="left">
+ *         <SheetHeader>
+ *           <SheetTitle>Navigation</SheetTitle>
+ *         </SheetHeader>
+ *         <nav className="py-4">
+ *           <Button variant="ghost" className="w-full justify-start">
+ *             Dashboard
+ *           </Button>
+ *         </nav>
+ *       </SheetContent>
+ *     </Sheet>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Sheet with form handling
+ * <Sheet>
+ *   <SheetTrigger asChild>
+ *     <Button>Edit Profile</Button>
+ *   </SheetTrigger>
+ *   <SheetContent>
+ *     <form onSubmit={handleSubmit}>
+ *       <SheetHeader>
+ *         <SheetTitle>Edit Profile</SheetTitle>
+ *         <SheetDescription>
+ *           Update your profile information.
+ *         </SheetDescription>
+ *       </SheetHeader>
+ *       <div className="grid gap-4 py-4">
+ *         <Input placeholder="Name" />
+ *         <Input placeholder="Email" type="email" />
+ *       </div>
+ *       <SheetFooter>
+ *         <SheetClose asChild>
+ *           <Button type="button" variant="outline">Cancel</Button>
+ *         </SheetClose>
+ *         <Button type="submit">Save</Button>
+ *       </SheetFooter>
+ *     </form>
+ *   </SheetContent>
+ * </Sheet>
+ * ```
+ *
+ * @accessibility
+ * - Focus is trapped within the sheet when open
+ * - Escape key closes the sheet
+ * - Background scroll is locked when sheet is open
+ * - Proper ARIA labeling for screen readers
+ * - Close button always visible and accessible
+ * - Supports keyboard navigation
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/sheet} shadcn/ui Sheet documentation
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/dialog} Radix UI Dialog primitive
+ * @since 1.0.0
+ */
+function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) {
+  return <SheetPrimitive.Root data-slot="sheet" {...props} />;
+}
+
+/**
+ * SheetTrigger - Button or element that opens the sheet
+ *
+ * The trigger element that users interact with to open the sheet.
+ * Use the `asChild` prop to render as a different element while
+ * maintaining the trigger functionality.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // As a styled button
+ * <SheetTrigger asChild>
+ *   <Button variant="outline">Open Settings</Button>
+ * </SheetTrigger>
+ *
+ * // As a simple button
+ * <SheetTrigger>Click to open</SheetTrigger>
+ *
+ * // As an icon button
+ * <SheetTrigger asChild>
+ *   <Button size="icon" variant="ghost">
+ *     <MenuIcon className="h-4 w-4" />
+ *   </Button>
+ * </SheetTrigger>
+ * ```
+ *
+ * @param asChild - When true, merges props with the child element instead of rendering a button
+ */
+function SheetTrigger({
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Trigger>) {
+  return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />;
+}
+
+/**
+ * SheetClose - Button that closes the sheet
+ *
+ * A button that closes the sheet when clicked. Can be placed anywhere
+ * within the sheet content. Use the `asChild` prop to render as a
+ * different element while maintaining the close functionality.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // In footer with styled button
+ * <SheetFooter>
+ *   <SheetClose asChild>
+ *     <Button variant="outline">Cancel</Button>
+ *   </SheetClose>
+ *   <Button type="submit">Save</Button>
+ * </SheetFooter>
+ *
+ * // As simple text button
+ * <SheetClose>Close</SheetClose>
+ *
+ * // Custom close button in content
+ * <SheetClose asChild>
+ *   <Button variant="ghost" size="sm" className="ml-auto">
+ *     <XIcon className="h-4 w-4" />
+ *   </Button>
+ * </SheetClose>
+ * ```
+ *
+ * @param asChild - When true, merges props with the child element instead of rendering a button
+ */
+function SheetClose({
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Close>) {
+  return <SheetPrimitive.Close data-slot="sheet-close" {...props} />;
+}
+
+/**
+ * SheetPortal - Portal container for sheet content
+ *
+ * Renders the sheet content in a portal at the end of the document body.
+ * This ensures the sheet appears above other content with proper z-index.
+ * Usually not used directly - SheetContent handles this automatically.
+ *
+ * @component
+ * @param container - Optional container element to portal into
+ */
+function SheetPortal({
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Portal>) {
+  return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />;
+}
+
+/**
+ * SheetOverlay - Background overlay behind the sheet
+ *
+ * A semi-transparent overlay that covers the entire viewport behind the sheet.
+ * Clicking the overlay closes the sheet. Includes smooth fade animations.
+ * Usually not used directly - SheetContent handles this automatically.
+ *
+ * @component
+ * @param className - Additional CSS classes for styling customization
+ *
+ * @example
+ * ```tsx
+ * // Custom overlay with different opacity
+ * <SheetOverlay className="bg-black/30" />
+ * ```
+ */
+function SheetOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Overlay>) {
+  return (
+    <SheetPrimitive.Overlay
+      data-slot="sheet-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}
+    />
+  );
+}
+
+/**
+ * SheetContent - Main container for sheet content
+ *
+ * The primary content area of the sheet that slides in from the specified side.
+ * Includes automatic overlay, portal rendering, and close button. Contains smooth
+ * slide animations and responsive sizing.
+ *
+ * @component
+ * @param side - Which side of the screen the sheet slides in from
+ * @param className - Additional CSS classes for styling customization
+ * @param children - Content to display inside the sheet
+ *
+ * @example
+ * ```tsx
+ * // Default right-side sheet
+ * <SheetContent>
+ *   <SheetHeader>
+ *     <SheetTitle>Settings</SheetTitle>
+ *   </SheetHeader>
+ *   <div className="py-4">
+ *     Settings content here
+ *   </div>
+ * </SheetContent>
+ *
+ * // Left-side navigation sheet
+ * <SheetContent side="left">
+ *   <nav>
+ *     <Button variant="ghost">Dashboard</Button>
+ *     <Button variant="ghost">Profile</Button>
+ *   </nav>
+ * </SheetContent>
+ *
+ * // Top sheet with custom height
+ * <SheetContent side="top" className="h-[300px]">
+ *   <SheetHeader>
+ *     <SheetTitle>Notifications</SheetTitle>
+ *   </SheetHeader>
+ * </SheetContent>
+ *
+ * // Bottom sheet for mobile actions
+ * <SheetContent side="bottom" className="h-[400px]">
+ *   <div className="grid grid-cols-2 gap-4">
+ *     <Button>Action 1</Button>
+ *     <Button>Action 2</Button>
+ *   </div>
+ * </SheetContent>
+ * ```
+ *
+ * @accessibility
+ * - Includes built-in close button with proper ARIA labels
+ * - Focus trapped within content when open
+ * - Supports all keyboard interactions
+ */
+function SheetContent({
+  className,
+  children,
+  side = "right",
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Content> & {
+  side?: "top" | "right" | "bottom" | "left";
+}) {
+  return (
+    <SheetPortal>
+      <SheetOverlay />
+      <SheetPrimitive.Content
+        data-slot="sheet-content"
+        className={cn(
+          "bg-background data-[state=open]:animate-in data-[state=closed]:animate-out fixed z-50 flex flex-col gap-4 shadow-lg transition ease-in-out data-[state=closed]:duration-300 data-[state=open]:duration-500",
+          side === "right" &&
+            "data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right inset-y-0 right-0 h-full w-3/4 border-l sm:max-w-sm",
+          side === "left" &&
+            "data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left inset-y-0 left-0 h-full w-3/4 border-r sm:max-w-sm",
+          side === "top" &&
+            "data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top inset-x-0 top-0 h-auto border-b",
+          side === "bottom" &&
+            "data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom inset-x-0 bottom-0 h-auto border-t",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+        <SheetPrimitive.Close className="ring-offset-background focus:ring-ring data-[state=open]:bg-secondary absolute top-4 right-4 rounded-xs opacity-70 transition-opacity hover:opacity-100 focus:ring-2 focus:ring-offset-2 focus:outline-hidden disabled:pointer-events-none">
+          <XIcon className="size-4" />
+          <span className="sr-only">Close</span>
+        </SheetPrimitive.Close>
+      </SheetPrimitive.Content>
+    </SheetPortal>
+  );
+}
+
+/**
+ * SheetHeader - Header section for sheet content
+ *
+ * A container for the sheet's title and description, positioned at the top
+ * of the sheet content. Provides consistent spacing and layout for sheet headers.
+ *
+ * @component
+ * @param className - Additional CSS classes for styling customization
+ *
+ * @example
+ * ```tsx
+ * <SheetHeader>
+ *   <SheetTitle>Edit Profile</SheetTitle>
+ *   <SheetDescription>
+ *     Make changes to your profile information.
+ *   </SheetDescription>
+ * </SheetHeader>
+ *
+ * // With custom styling
+ * <SheetHeader className="border-b pb-4">
+ *   <SheetTitle>Settings</SheetTitle>
+ * </SheetHeader>
+ * ```
+ */
+function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sheet-header"
+      className={cn("flex flex-col gap-1.5 p-4", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * SheetFooter - Footer section for sheet actions
+ *
+ * A container for action buttons positioned at the bottom of the sheet content.
+ * Uses `mt-auto` to stick to the bottom and provides consistent spacing for buttons.
+ *
+ * @component
+ * @param className - Additional CSS classes for styling customization
+ *
+ * @example
+ * ```tsx
+ * <SheetFooter>
+ *   <SheetClose asChild>
+ *     <Button variant="outline">Cancel</Button>
+ *   </SheetClose>
+ *   <Button type="submit">Save Changes</Button>
+ * </SheetFooter>
+ *
+ * // Single action footer
+ * <SheetFooter>
+ *   <SheetClose asChild>
+ *     <Button className="w-full">Done</Button>
+ *   </SheetClose>
+ * </SheetFooter>
+ *
+ * // Custom layout
+ * <SheetFooter className="flex-row justify-between">
+ *   <Button variant="ghost">Reset</Button>
+ *   <div className="flex gap-2">
+ *     <SheetClose asChild>
+ *       <Button variant="outline">Cancel</Button>
+ *     </SheetClose>
+ *     <Button>Save</Button>
+ *   </div>
+ * </SheetFooter>
+ * ```
+ */
+function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sheet-footer"
+      className={cn("mt-auto flex flex-col gap-2 p-4", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * SheetTitle - Title element for the sheet
+ *
+ * The main heading for the sheet content. Provides proper semantic heading
+ * and accessibility labeling for screen readers. Should be used within SheetHeader.
+ *
+ * @component
+ * @param className - Additional CSS classes for styling customization
+ *
+ * @example
+ * ```tsx
+ * <SheetHeader>
+ *   <SheetTitle>Edit Profile</SheetTitle>
+ *   <SheetDescription>Update your profile information.</SheetDescription>
+ * </SheetHeader>
+ *
+ * // With custom styling
+ * <SheetTitle className="text-lg text-blue-600">Settings</SheetTitle>
+ * ```
+ *
+ * @accessibility
+ * - Automatically provides ARIA labeling for the sheet
+ * - Renders as proper heading element
+ */
+function SheetTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Title>) {
+  return (
+    <SheetPrimitive.Title
+      data-slot="sheet-title"
+      className={cn("text-foreground font-semibold", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * SheetDescription - Description text for the sheet
+ *
+ * Provides additional context about the sheet's purpose or instructions.
+ * Appears below the title with muted styling. Should be used within SheetHeader.
+ *
+ * @component
+ * @param className - Additional CSS classes for styling customization
+ *
+ * @example
+ * ```tsx
+ * <SheetHeader>
+ *   <SheetTitle>Edit Profile</SheetTitle>
+ *   <SheetDescription>
+ *     Make changes to your profile here. Click save when you're done.
+ *   </SheetDescription>
+ * </SheetHeader>
+ *
+ * // Optional description
+ * <SheetDescription className="text-orange-600">
+ *   This action cannot be undone.
+ * </SheetDescription>
+ * ```
+ *
+ * @accessibility
+ * - Provides additional context for screen readers
+ * - Linked to the sheet via ARIA attributes
+ */
+function SheetDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Description>) {
+  return (
+    <SheetPrimitive.Description
+      data-slot="sheet-description"
+      className={cn("text-muted-foreground text-sm", className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Sheet,
+  SheetTrigger,
+  SheetClose,
+  SheetContent,
+  SheetHeader,
+  SheetFooter,
+  SheetTitle,
+  SheetDescription,
+};