@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/sheet.tsx

@@ -4,6 +4,160 @@ import { XIcon } from "lucide-react";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * Props for Sheet component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SheetDocsProps = {
+  /** Controls the open state of the sheet. Use with onOpenChange for controlled behavior */
+  open?: boolean;
+  /** Callback fired when the open state changes. Use with open for controlled behavior */
+  onOpenChange?: (open: boolean) => void;
+  /** Initial open state for uncontrolled usage @default false */
+  defaultOpen?: boolean;
+  /** Whether the sheet should be modal (blocking interaction with content behind) @default true */
+  modal?: boolean;
+  /** Child elements that make up the sheet (trigger, content, etc.) */
+  children?: React.ReactNode;
+};
+
+/**
+ * Props for SheetTrigger component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SheetTriggerDocsProps = {
+  /** When true, merges props with child element instead of rendering a button @default false */
+  asChild?: boolean;
+  /** Child element to render as the trigger. Required when asChild is true */
+  children?: React.ReactNode;
+};
+
+/**
+ * Props for SheetClose component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SheetCloseDocsProps = {
+  /** When true, merges props with child element instead of rendering a button @default false */
+  asChild?: boolean;
+  /** Child element to render as the close button. Required when asChild is true */
+  children?: React.ReactNode;
+};
+
+/**
+ * Props for SheetPortal component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SheetPortalDocsProps = {
+  /** Forces mounting when true. Useful for controlling animations with external state */
+  forceMount?: boolean;
+  /** Container element to portal the sheet into @default document.body */
+  container?: HTMLElement | null;
+  /** Child elements to render in the portal */
+  children?: React.ReactNode;
+};
+
+/**
+ * Props for SheetOverlay component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SheetOverlayDocsProps = {
+  /** When true, merges props with child element instead of rendering a div @default false */
+  asChild?: boolean;
+  /** Forces mounting when true. Useful for controlling animations with external state */
+  forceMount?: boolean;
+  /** Additional CSS classes for styling customization */
+  className?: string;
+};
+
+/**
+ * Props for SheetContent component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SheetContentDocsProps = {
+  /** When true, merges props with child element instead of rendering a div @default false */
+  asChild?: boolean;
+  /** Forces mounting when true. Useful for controlling animations with external state */
+  forceMount?: boolean;
+  /** Event handler called when focus moves to the trigger after closing */
+  onCloseAutoFocus?: (event: Event) => void;
+  /** Event handler called when focus moves into the component after opening */
+  onOpenAutoFocus?: (event: Event) => void;
+  /** Event handler called when the escape key is down */
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  /** Event handler called when a pointer down event happens outside the bounds of the component */
+  onPointerDownOutside?: (
+    event: CustomEvent<{ originalEvent: PointerEvent }>,
+  ) => void;
+  /** Event handler called when an interaction (pointer or focus) happens outside the bounds of the component */
+  onInteractOutside?: (
+    event: CustomEvent<{ originalEvent: PointerEvent | FocusEvent }>,
+  ) => void;
+  /** Which side of the screen the sheet slides in from @default "right" */
+  side?: "top" | "right" | "bottom" | "left";
+  /** Additional CSS classes for styling customization */
+  className?: string;
+  /** Content to display inside the sheet */
+  children?: React.ReactNode;
+};
+
+/**
+ * Props for SheetHeader component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace HTML element types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SheetHeaderDocsProps = {
+  /** Additional CSS classes for styling customization */
+  className?: string;
+  /** Header content (typically SheetTitle and SheetDescription) */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for SheetFooter component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace HTML element types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SheetFooterDocsProps = {
+  /** Additional CSS classes for styling customization */
+  className?: string;
+  /** Footer content (typically action buttons) */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for SheetTitle component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SheetTitleDocsProps = {
+  /** When true, merges props with child element instead of rendering an h2 @default false */
+  asChild?: boolean;
+  /** Additional CSS classes for styling customization */
+  className?: string;
+  /** Title text content */
+  children?: React.ReactNode;
+};
+
+/**
+ * Props for SheetDescription component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SheetDescriptionDocsProps = {
+  /** When true, merges props with child element instead of rendering a p element @default false */
+  asChild?: boolean;
+  /** Additional CSS classes for styling customization */
+  className?: string;
+  /** Description text content */
+  children?: React.ReactNode;
+};
+
 /**
  * Sheet - A slide-out panel that displays supplementary content
  *
@@ -120,7 +274,8 @@ function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) {
  *
  * 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.
+ * maintaining the trigger functionality. When clicked, opens the
+ * sheet and manages focus appropriately.
  *
  * @component
  * @example
@@ -141,7 +296,16 @@ function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) {
  * </SheetTrigger>
  * ```
  *
- * @param asChild - When true, merges props with the child element instead of rendering a button
+ * @param asChild - When true, merges props with child element instead of rendering a button @default false
+ * @param children - Child element to render as the trigger. Required when asChild is true
+ *
+ * @accessibility
+ * - Automatically receives appropriate ARIA attributes
+ * - Manages focus when sheet opens and closes
+ * - Supports keyboard activation (Space and Enter)
+ *
+ * @see {@link SheetContent} For the content that this trigger opens
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/dialog#trigger} Radix UI Dialog Trigger
  */
 function SheetTrigger({
   ...props
@@ -155,6 +319,7 @@ function SheetTrigger({
  * 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.
+ * Multiple close buttons can be used throughout the sheet content.
  *
  * @component
  * @example
@@ -178,7 +343,16 @@ function SheetTrigger({
  * </SheetClose>
  * ```
  *
- * @param asChild - When true, merges props with the child element instead of rendering a button
+ * @param asChild - When true, merges props with child element instead of rendering a button @default false
+ * @param children - Child element to render as the close button. Required when asChild is true
+ *
+ * @accessibility
+ * - Automatically receives appropriate ARIA attributes
+ * - Supports keyboard activation (Space and Enter)
+ * - Focus returns to trigger element after closing
+ *
+ * @see {@link SheetTrigger} For the element that opens the sheet
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/dialog#close} Radix UI Dialog Close
  */
 function SheetClose({
   ...props
@@ -192,9 +366,38 @@ function SheetClose({
  * 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.
+ * Essential for proper layering and focus management.
  *
  * @component
- * @param container - Optional container element to portal into
+ * @example
+ * ```tsx
+ * // Custom portal container
+ * <SheetPortal container={customContainer}>
+ *   <SheetOverlay />
+ *   <SheetPrimitive.Content>
+ *     Sheet content here
+ *   </SheetPrimitive.Content>
+ * </SheetPortal>
+ *
+ * // Force mounted portal for animation control
+ * <SheetPortal forceMount={shouldShow}>
+ *   <SheetOverlay />
+ *   <SheetPrimitive.Content>
+ *     Content with custom mounting logic
+ *   </SheetPrimitive.Content>
+ * </SheetPortal>
+ * ```
+ *
+ * @param forceMount - Forces mounting when true. Useful for controlling animations with external state
+ * @param container - Container element to portal the sheet into @default document.body
+ * @param children - Child elements to render in the portal (overlay and content)
+ *
+ * @accessibility
+ * - Ensures sheet content is properly layered for screen readers
+ * - Maintains proper document flow for accessibility tree
+ *
+ * @see {@link SheetContent} For the main content component that uses this portal
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/dialog#portal} Radix UI Dialog Portal
  */
 function SheetPortal({
   ...props
@@ -206,17 +409,34 @@ function SheetPortal({
  * 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.
+ * Clicking the overlay closes the sheet (when modal is true). Includes smooth
+ * fade animations and prevents interaction with content behind the sheet.
  * 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" />
+ *
+ * // Overlay with custom animation timing
+ * <SheetOverlay className="bg-black/60 duration-200" />
+ *
+ * // Force mounted overlay for external animation control
+ * <SheetOverlay forceMount={isAnimating} />
  * ```
+ *
+ * @param asChild - When true, merges props with child element instead of rendering a div @default false
+ * @param forceMount - Forces mounting when true. Useful for controlling animations with external state
+ * @param className - Additional CSS classes for styling customization
+ *
+ * @accessibility
+ * - Prevents interaction with content behind the sheet
+ * - Clicking overlay closes the sheet (respects modal behavior)
+ * - Proper z-index layering for screen readers
+ *
+ * @see {@link SheetContent} For the content component that uses this overlay
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/dialog#overlay} Radix UI Dialog Overlay
  */
 function SheetOverlay({
   className,
@@ -239,13 +459,13 @@ function SheetOverlay({
  *
  * 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.
+ * slide animations with responsive sizing and proper focus management.
  *
- * @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
+ * Features automatic positioning based on the side prop:
+ * - Right/Left: Full height, responsive width (3/4 on mobile, max 384px on desktop)
+ * - Top/Bottom: Full width, auto height based on content
  *
+ * @component
  * @example
  * ```tsx
  * // Default right-side sheet
@@ -282,10 +502,28 @@ function SheetOverlay({
  * </SheetContent>
  * ```
  *
+ * @param asChild - When true, merges props with child element instead of rendering a div @default false
+ * @param forceMount - Forces mounting when true. Useful for controlling animations with external state
+ * @param onCloseAutoFocus - Event handler called when focus moves to the trigger after closing
+ * @param onOpenAutoFocus - Event handler called when focus moves into the component after opening
+ * @param onEscapeKeyDown - Event handler called when the escape key is down. Can prevent default to disable escape key closing
+ * @param onPointerDownOutside - Event handler called when a pointer down event happens outside the component bounds
+ * @param onInteractOutside - Event handler called when an interaction happens outside the component bounds
+ * @param side - Which side of the screen the sheet slides in from @default "right"
+ * @param className - Additional CSS classes for styling customization
+ * @param children - Content to display inside the sheet
+ *
  * @accessibility
- * - Includes built-in close button with proper ARIA labels
- * - Focus trapped within content when open
- * - Supports all keyboard interactions
+ * - Includes built-in close button with proper ARIA labels and screen reader text
+ * - Focus automatically trapped within content when open
+ * - Escape key closes the sheet (can be prevented with onEscapeKeyDown)
+ * - Background overlay prevents interaction with page content
+ * - Focus returns to trigger element when closed
+ * - Supports all standard keyboard interactions
+ *
+ * @see {@link SheetHeader} For structured header content
+ * @see {@link SheetFooter} For action buttons
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/dialog#content} Radix UI Dialog Content
  */
 function SheetContent({
   className,
@@ -329,12 +567,13 @@ function SheetContent({
  *
  * 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.
+ * Should contain SheetTitle and optionally SheetDescription for proper
+ * accessibility and semantic structure.
  *
  * @component
- * @param className - Additional CSS classes for styling customization
- *
  * @example
  * ```tsx
+ * // Complete header with title and description
  * <SheetHeader>
  *   <SheetTitle>Edit Profile</SheetTitle>
  *   <SheetDescription>
@@ -342,11 +581,30 @@ function SheetContent({
  *   </SheetDescription>
  * </SheetHeader>
  *
- * // With custom styling
- * <SheetHeader className="border-b pb-4">
- *   <SheetTitle>Settings</SheetTitle>
+ * // Header with title only
+ * <SheetHeader>
+ *   <SheetTitle>Quick Actions</SheetTitle>
+ * </SheetHeader>
+ *
+ * // With custom styling and border
+ * <SheetHeader className="border-b pb-4 mb-4">
+ *   <SheetTitle>Advanced Settings</SheetTitle>
+ *   <SheetDescription>
+ *     Configure advanced options for your account.
+ *   </SheetDescription>
  * </SheetHeader>
  * ```
+ *
+ * @param className - Additional CSS classes for styling customization
+ * @param children - Header content (typically SheetTitle and SheetDescription)
+ *
+ * @accessibility
+ * - Provides semantic structure for sheet content
+ * - Works with SheetTitle to properly label the sheet
+ * - Maintains proper heading hierarchy
+ *
+ * @see {@link SheetTitle} For the main sheet heading
+ * @see {@link SheetDescription} For additional context text
  */
 function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
   return (
@@ -363,12 +621,12 @@ function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
  *
  * 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.
+ * Ideal for primary and secondary actions like Save/Cancel button pairs.
  *
  * @component
- * @param className - Additional CSS classes for styling customization
- *
  * @example
  * ```tsx
+ * // Standard save/cancel footer
  * <SheetFooter>
  *   <SheetClose asChild>
  *     <Button variant="outline">Cancel</Button>
@@ -383,7 +641,7 @@ function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
  *   </SheetClose>
  * </SheetFooter>
  *
- * // Custom layout
+ * // Custom layout with multiple action groups
  * <SheetFooter className="flex-row justify-between">
  *   <Button variant="ghost">Reset</Button>
  *   <div className="flex gap-2">
@@ -393,7 +651,25 @@ function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
  *     <Button>Save</Button>
  *   </div>
  * </SheetFooter>
+ *
+ * // Footer with destructive action
+ * <SheetFooter>
+ *   <Button variant="destructive">Delete Account</Button>
+ *   <SheetClose asChild>
+ *     <Button variant="outline">Keep Account</Button>
+ *   </SheetClose>
+ * </SheetFooter>
  * ```
+ *
+ * @param className - Additional CSS classes for styling customization
+ * @param children - Footer content (typically action buttons)
+ *
+ * @accessibility
+ * - Provides semantic footer structure
+ * - Supports proper tab order for action buttons
+ * - Works with form submission patterns
+ *
+ * @see {@link SheetClose} For buttons that close the sheet
  */
 function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
   return (
@@ -410,12 +686,12 @@ function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
  *
  * The main heading for the sheet content. Provides proper semantic heading
  * and accessibility labeling for screen readers. Should be used within SheetHeader.
+ * This component is required for proper accessibility - every sheet must have a title.
  *
  * @component
- * @param className - Additional CSS classes for styling customization
- *
  * @example
  * ```tsx
+ * // Standard usage in header
  * <SheetHeader>
  *   <SheetTitle>Edit Profile</SheetTitle>
  *   <SheetDescription>Update your profile information.</SheetDescription>
@@ -423,11 +699,29 @@ function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
  *
  * // With custom styling
  * <SheetTitle className="text-lg text-blue-600">Settings</SheetTitle>
+ *
+ * // As a custom heading level
+ * <SheetTitle asChild>
+ *   <h1 className="text-2xl font-bold">Important Notice</h1>
+ * </SheetTitle>
+ *
+ * // Dynamic title content
+ * <SheetTitle>Edit {selectedUser?.name || 'User'}</SheetTitle>
  * ```
  *
+ * @param asChild - When true, merges props with child element instead of rendering an h2 @default false
+ * @param className - Additional CSS classes for styling customization
+ * @param children - Title text content
+ *
  * @accessibility
- * - Automatically provides ARIA labeling for the sheet
- * - Renders as proper heading element
+ * - Required for proper sheet accessibility
+ * - Automatically provides ARIA labeling for the entire sheet
+ * - Renders as semantic heading element (h2 by default)
+ * - Screen readers announce this title when sheet opens
+ *
+ * @see {@link SheetHeader} For proper title placement
+ * @see {@link SheetDescription} For additional context
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/dialog#title} Radix UI Dialog Title
  */
 function SheetTitle({
   className,
@@ -447,12 +741,12 @@ function SheetTitle({
  *
  * Provides additional context about the sheet's purpose or instructions.
  * Appears below the title with muted styling. Should be used within SheetHeader.
+ * While optional, it's recommended for better accessibility and user understanding.
  *
  * @component
- * @param className - Additional CSS classes for styling customization
- *
  * @example
  * ```tsx
+ * // Standard usage with instructional text
  * <SheetHeader>
  *   <SheetTitle>Edit Profile</SheetTitle>
  *   <SheetDescription>
@@ -460,15 +754,38 @@ function SheetTitle({
  *   </SheetDescription>
  * </SheetHeader>
  *
- * // Optional description
+ * // Warning or important information
  * <SheetDescription className="text-orange-600">
  *   This action cannot be undone.
  * </SheetDescription>
+ *
+ * // Custom styled description
+ * <SheetDescription asChild>
+ *   <p className="text-sm text-gray-600 italic">
+ *     Changes will be saved automatically.
+ *   </p>
+ * </SheetDescription>
+ *
+ * // Contextual help description
+ * <SheetDescription>
+ *   Use this form to update your notification preferences.
+ *   Changes take effect immediately.
+ * </SheetDescription>
  * ```
  *
+ * @param asChild - When true, merges props with child element instead of rendering a p element @default false
+ * @param className - Additional CSS classes for styling customization
+ * @param children - Description text content
+ *
  * @accessibility
  * - Provides additional context for screen readers
- * - Linked to the sheet via ARIA attributes
+ * - Automatically linked to the sheet via ARIA attributes
+ * - Announced by screen readers when sheet opens
+ * - Helps users understand the sheet's purpose
+ *
+ * @see {@link SheetTitle} For the main sheet heading
+ * @see {@link SheetHeader} For proper description placement
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/dialog#description} Radix UI Dialog Description
  */
 function SheetDescription({
   className,