@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/alert-dialog.tsx

@@ -4,6 +4,167 @@ import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog";
 import { cn } from "@/lib/utils";
 import { buttonVariants } from "@/components/ui/button";
 
+/**
+ * Props for AlertDialog (Documentation only - NOT used in component implementation)
+ *
+ * Controls the overall state and behavior of the alert dialog. Alert dialogs are
+ * specifically designed for critical confirmations that require user attention
+ * and cannot be dismissed by clicking outside.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDialogDocsProps = {
+  /** Whether the dialog is open by default (uncontrolled mode) @default undefined */
+  defaultOpen?: boolean;
+  /** Whether the dialog is open (controlled mode) @default undefined */
+  open?: boolean;
+  /** Callback fired when the open state changes @param open - The new open state */
+  onOpenChange?: (open: boolean) => void;
+} & React.ComponentProps<typeof AlertDialogPrimitive.Root>;
+
+/**
+ * Props for AlertDialogTrigger (Documentation only - NOT used in component implementation)
+ *
+ * The element that opens the alert dialog when activated. Usually a button,
+ * but can be any interactive element through composition.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDialogTriggerDocsProps = {
+  /** Render as child element, merging props and behavior @default false */
+  asChild?: boolean;
+} & React.ComponentProps<typeof AlertDialogPrimitive.Trigger>;
+
+/**
+ * Props for AlertDialogPortal (Documentation only - NOT used in component implementation)
+ *
+ * Controls where the dialog content is rendered in the DOM tree.
+ * Used internally by AlertDialogContent.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDialogPortalDocsProps = {
+  /** Force mount the component even when not open @default undefined */
+  forceMount?: boolean;
+  /** Container element to portal into @default document.body */
+  container?: HTMLElement;
+} & React.ComponentProps<typeof AlertDialogPrimitive.Portal>;
+
+/**
+ * Props for AlertDialogOverlay (Documentation only - NOT used in component implementation)
+ *
+ * The semi-transparent backdrop that prevents interaction with background content.
+ * Includes fade animations and proper z-index stacking.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDialogOverlayDocsProps = {
+  /** Render as child element, merging props and behavior @default false */
+  asChild?: boolean;
+  /** Force mount the component even when not open @default undefined */
+  forceMount?: boolean;
+  /** Additional CSS classes for styling */
+  className?: string;
+} & React.ComponentProps<typeof AlertDialogPrimitive.Overlay>;
+
+/**
+ * Props for AlertDialogContent (Documentation only - NOT used in component implementation)
+ *
+ * The main container for alert dialog content. Automatically handles portal
+ * rendering, overlay backdrop, and focus management.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDialogContentDocsProps = {
+  /** Render as child element, merging props and behavior @default false */
+  asChild?: boolean;
+  /** Force mount the component even when not open @default undefined */
+  forceMount?: boolean;
+  /** Callback fired when focus moves to the trigger after opening @param event - Focus event */
+  onOpenAutoFocus?: (event: Event) => void;
+  /** Callback fired when focus moves to the trigger after closing @param event - Focus event */
+  onCloseAutoFocus?: (event: Event) => void;
+  /** Callback fired when Escape key is pressed @param event - Keyboard event */
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  /** Additional CSS classes for styling */
+  className?: string;
+} & React.ComponentProps<typeof AlertDialogPrimitive.Content>;
+
+/**
+ * Props for AlertDialogHeader (Documentation only - NOT used in component implementation)
+ *
+ * Container for the dialog title and description with consistent spacing
+ * and responsive alignment.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDialogHeaderDocsProps = {
+  /** Additional CSS classes for styling */
+  className?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for AlertDialogFooter (Documentation only - NOT used in component implementation)
+ *
+ * Container for action buttons with responsive layout. Uses reverse column
+ * layout on mobile (cancel on top) and row layout on larger screens.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDialogFooterDocsProps = {
+  /** Additional CSS classes for styling */
+  className?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for AlertDialogTitle (Documentation only - NOT used in component implementation)
+ *
+ * The main heading that describes what the alert dialog is asking.
+ * Provides proper ARIA labeling for accessibility.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDialogTitleDocsProps = {
+  /** Render as child element, merging props and behavior @default false */
+  asChild?: boolean;
+  /** Additional CSS classes for styling */
+  className?: string;
+} & React.ComponentProps<typeof AlertDialogPrimitive.Title>;
+
+/**
+ * Props for AlertDialogDescription (Documentation only - NOT used in component implementation)
+ *
+ * Additional context and explanation for the alert dialog action.
+ * Provides proper ARIA description for accessibility.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDialogDescriptionDocsProps = {
+  /** Render as child element, merging props and behavior @default false */
+  asChild?: boolean;
+  /** Additional CSS classes for styling */
+  className?: string;
+} & React.ComponentProps<typeof AlertDialogPrimitive.Description>;
+
+/**
+ * Props for AlertDialogAction (Documentation only - NOT used in component implementation)
+ *
+ * The primary action button that confirms or executes the alerted action.
+ * Receives focus automatically when dialog opens. Styled with button variants.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDialogActionDocsProps = {
+  /** Render as child element, merging props and behavior @default false */
+  asChild?: boolean;
+  /** Additional CSS classes for styling (useful for destructive actions) */
+  className?: string;
+} & React.ComponentProps<typeof AlertDialogPrimitive.Action>;
+
+/**
+ * Props for AlertDialogCancel (Documentation only - NOT used in component implementation)
+ *
+ * The cancel button that dismisses the dialog without performing the action.
+ * Styled as outline variant by default to de-emphasize compared to action.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AlertDialogCancelDocsProps = {
+  /** Render as child element, merging props and behavior @default false */
+  asChild?: boolean;
+  /** Additional CSS classes for styling */
+  className?: string;
+} & React.ComponentProps<typeof AlertDialogPrimitive.Cancel>;
+
 /**
  * Alert dialog component for critical confirmations and destructive actions
  *
@@ -81,9 +242,27 @@ import { buttonVariants } from "@/components/ui/button";
  * Root component of the alert dialog
  *
  * Provides the context and state management for the entire alert dialog.
- * Controls the open/closed state and manages focus behavior.
+ * Controls the open/closed state and manages focus behavior. Alert dialogs
+ * are specifically designed for critical actions that require user attention
+ * and cannot be dismissed by clicking outside.
+ *
+ * @param defaultOpen - Whether the dialog is open initially (uncontrolled)
+ * @param open - Whether the dialog is open (controlled)
+ * @param onOpenChange - Callback when open state changes
+ * @param props - All other props forwarded to Radix AlertDialog.Root
  *
- * @param props - All props are forwarded to the underlying Radix AlertDialog.Root
+ * @example
+ * ```tsx
+ * // Uncontrolled
+ * <AlertDialog defaultOpen={false}>
+ *   // dialog content
+ * </AlertDialog>
+ *
+ * // Controlled
+ * <AlertDialog open={isOpen} onOpenChange={setIsOpen}>
+ *   // dialog content
+ * </AlertDialog>
+ * ```
  */
 function AlertDialog({
   ...props
@@ -95,15 +274,27 @@ function AlertDialog({
  * Trigger element that opens the alert dialog
  *
  * The element that opens the alert dialog when activated. Usually a button,
- * but can be any interactive element. Use the `asChild` prop to compose
- * with other components.
+ * but can be any interactive element through composition. When opened, the dialog
+ * will trap focus and require user interaction before continuing.
  *
- * @param props - All props are forwarded to the underlying Radix AlertDialog.Trigger
+ * @param asChild - Render as child element, merging props and behavior
+ * @param props - All other props forwarded to Radix AlertDialog.Trigger
  *
  * @example
  * ```tsx
+ * // Direct usage
+ * <AlertDialogTrigger>
+ *   Delete Account
+ * </AlertDialogTrigger>
+ *
+ * // Composition with Button component
+ * <AlertDialogTrigger asChild>
+ *   <Button variant="destructive">Delete Account</Button>
+ * </AlertDialogTrigger>
+ *
+ * // Composition with custom element
  * <AlertDialogTrigger asChild>
- *   <Button variant="destructive">Delete</Button>
+ *   <button className="custom-trigger">Custom Trigger</button>
  * </AlertDialogTrigger>
  * ```
  */
@@ -122,7 +313,20 @@ function AlertDialogTrigger({
  * This ensures the dialog appears above other content and is properly accessible.
  * Usually not used directly - AlertDialogContent includes this automatically.
  *
- * @param props - All props are forwarded to the underlying Radix AlertDialog.Portal
+ * @param forceMount - Force mount the component even when dialog is closed
+ * @param container - Container element to portal into (defaults to document.body)
+ * @param props - All other props forwarded to Radix AlertDialog.Portal
+ *
+ * @example
+ * ```tsx
+ * // Custom portal container
+ * <AlertDialogPortal container={customContainer}>
+ *   <AlertDialogOverlay />
+ *   <AlertDialogPrimitive.Content>
+ *     // content
+ *   </AlertDialogPrimitive.Content>
+ * </AlertDialogPortal>
+ * ```
  */
 function AlertDialogPortal({
   ...props
@@ -137,15 +341,28 @@ function AlertDialogPortal({
  *
  * A semi-transparent backdrop that covers the entire viewport when the dialog is open.
  * Provides visual separation and prevents interaction with background content.
- * Includes fade in/out animations using data-state attributes.
+ * Includes smooth fade in/out animations and proper z-index stacking.
+ *
+ * @param asChild - Render as child element, merging props and behavior
+ * @param forceMount - Force mount the component even when dialog is closed
+ * @param className - Additional CSS classes for custom styling
+ * @param props - All other props forwarded to Radix AlertDialog.Overlay
  *
- * @param className - Additional CSS classes to apply
- * @param props - All other props are forwarded to the underlying Radix AlertDialog.Overlay
+ * @example
+ * ```tsx
+ * // Custom overlay styling
+ * <AlertDialogOverlay className="bg-black/80" />
+ *
+ * // Force mounted overlay
+ * <AlertDialogOverlay forceMount className="custom-backdrop" />
+ * ```
  */
 function AlertDialogOverlay({
   className,
   ...props
-}: React.ComponentProps<typeof AlertDialogPrimitive.Overlay>) {
+}: React.ComponentProps<typeof AlertDialogPrimitive.Overlay> & {
+  className?: string;
+}) {
   return (
     <AlertDialogPrimitive.Overlay
       data-slot="alert-dialog-overlay"
@@ -163,13 +380,20 @@ function AlertDialogOverlay({
  *
  * The primary container that holds all alert dialog content. Automatically includes
  * the portal and overlay, and provides default styling with responsive design.
- * Centered on screen with fade and zoom animations.
+ * Centered on screen with smooth fade and zoom animations. Manages focus trapping
+ * and keyboard navigation automatically.
  *
- * @param className - Additional CSS classes to apply to the content container
- * @param props - All other props are forwarded to the underlying Radix AlertDialog.Content
+ * @param asChild - Render as child element, merging props and behavior
+ * @param forceMount - Force mount the component even when dialog is closed
+ * @param onOpenAutoFocus - Callback when dialog opens and focus moves to content
+ * @param onCloseAutoFocus - Callback when dialog closes and focus returns to trigger
+ * @param onEscapeKeyDown - Callback when Escape key is pressed (can preventDefault)
+ * @param className - Additional CSS classes for custom styling
+ * @param props - All other props forwarded to Radix AlertDialog.Content
  *
  * @example
  * ```tsx
+ * // Basic usage
  * <AlertDialogContent>
  *   <AlertDialogHeader>
  *     <AlertDialogTitle>Confirm Action</AlertDialogTitle>
@@ -180,12 +404,35 @@ function AlertDialogOverlay({
  *     <AlertDialogAction>Continue</AlertDialogAction>
  *   </AlertDialogFooter>
  * </AlertDialogContent>
+ *
+ * // Custom focus handling
+ * <AlertDialogContent
+ *   onOpenAutoFocus={(e) => {
+ *     e.preventDefault();
+ *     customFocusTarget.focus();
+ *   }}
+ *   onEscapeKeyDown={(e) => {
+ *     if (hasUnsavedChanges) {
+ *       e.preventDefault();
+ *       showUnsavedWarning();
+ *     }
+ *   }}
+ * >
+ *   // content
+ * </AlertDialogContent>
+ *
+ * // Custom styling
+ * <AlertDialogContent className="max-w-md">
+ *   // smaller dialog
+ * </AlertDialogContent>
  * ```
  */
 function AlertDialogContent({
   className,
   ...props
-}: React.ComponentProps<typeof AlertDialogPrimitive.Content>) {
+}: React.ComponentProps<typeof AlertDialogPrimitive.Content> & {
+  className?: string;
+}) {
   return (
     <AlertDialogPortal>
       <AlertDialogOverlay />
@@ -206,15 +453,32 @@ function AlertDialogContent({
  *
  * Contains the title and description of the alert dialog. Provides consistent
  * spacing and alignment, with responsive text alignment (centered on mobile,
- * left-aligned on larger screens).
+ * left-aligned on larger screens). Should contain AlertDialogTitle and
+ * optionally AlertDialogDescription for proper accessibility.
+ *
+ * @param className - Additional CSS classes for custom styling
+ * @param props - All other props forwarded to the underlying div element
  *
- * @param className - Additional CSS classes to apply
- * @param props - All other props are forwarded to the underlying div element
+ * @example
+ * ```tsx
+ * <AlertDialogHeader>
+ *   <AlertDialogTitle>Delete Account</AlertDialogTitle>
+ *   <AlertDialogDescription>
+ *     This will permanently delete your account and all associated data.
+ *     This action cannot be undone.
+ *   </AlertDialogDescription>
+ * </AlertDialogHeader>
+ *
+ * // Custom styling
+ * <AlertDialogHeader className="text-left">
+ *   <AlertDialogTitle>Custom Header</AlertDialogTitle>
+ * </AlertDialogHeader>
+ * ```
  */
 function AlertDialogHeader({
   className,
   ...props
-}: React.ComponentProps<"div">) {
+}: React.HTMLAttributes<HTMLDivElement>) {
   return (
     <div
       data-slot="alert-dialog-header"
@@ -229,15 +493,35 @@ function AlertDialogHeader({
  *
  * Contains the action buttons (cancel and confirm). Uses responsive layout
  * with stacked buttons on mobile (cancel on top) and horizontal layout
- * on larger screens (cancel on left, action on right).
+ * on larger screens (cancel on left, action on right). Should contain
+ * AlertDialogCancel and AlertDialogAction for proper UX.
  *
- * @param className - Additional CSS classes to apply
- * @param props - All other props are forwarded to the underlying div element
+ * @param className - Additional CSS classes for custom styling
+ * @param props - All other props forwarded to the underlying div element
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogFooter>
+ *   <AlertDialogCancel>Cancel</AlertDialogCancel>
+ *   <AlertDialogAction>Delete Account</AlertDialogAction>
+ * </AlertDialogFooter>
+ *
+ * // Custom button order
+ * <AlertDialogFooter className="flex-row">
+ *   <AlertDialogAction>Continue</AlertDialogAction>
+ *   <AlertDialogCancel>Go Back</AlertDialogCancel>
+ * </AlertDialogFooter>
+ *
+ * // Single action footer
+ * <AlertDialogFooter>
+ *   <AlertDialogAction>I Understand</AlertDialogAction>
+ * </AlertDialogFooter>
+ * ```
  */
 function AlertDialogFooter({
   className,
   ...props
-}: React.ComponentProps<"div">) {
+}: React.HTMLAttributes<HTMLDivElement>) {
   return (
     <div
       data-slot="alert-dialog-footer"
@@ -254,22 +538,37 @@ function AlertDialogFooter({
  * Title heading of the alert dialog
  *
  * The main heading that describes the alert or action being confirmed.
- * Automatically provides proper ARIA labeling for screen readers.
- * Should be concise and clearly state what the dialog is asking.
+ * Automatically provides proper ARIA labeling for screen readers via
+ * aria-labelledby. Should be concise and clearly state what the dialog is asking.
  *
- * @param className - Additional CSS classes to apply
- * @param props - All other props are forwarded to the underlying Radix AlertDialog.Title
+ * @param asChild - Render as child element, merging props and behavior
+ * @param className - Additional CSS classes for custom styling
+ * @param props - All other props forwarded to Radix AlertDialog.Title
  *
  * @example
  * ```tsx
+ * // Standard titles
  * <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
  * <AlertDialogTitle>Delete Account</AlertDialogTitle>
+ * <AlertDialogTitle>Confirm Sign Out</AlertDialogTitle>
+ *
+ * // Custom styling
+ * <AlertDialogTitle className="text-red-600 text-xl">
+ *   Destructive Action
+ * </AlertDialogTitle>
+ *
+ * // Composition with custom element
+ * <AlertDialogTitle asChild>
+ *   <h1 className="custom-title">Custom Title Element</h1>
+ * </AlertDialogTitle>
  * ```
  */
 function AlertDialogTitle({
   className,
   ...props
-}: React.ComponentProps<typeof AlertDialogPrimitive.Title>) {
+}: React.ComponentProps<typeof AlertDialogPrimitive.Title> & {
+  className?: string;
+}) {
   return (
     <AlertDialogPrimitive.Title
       data-slot="alert-dialog-title"
@@ -284,23 +583,45 @@ function AlertDialogTitle({
  *
  * Provides additional context and explanation for the alert or action.
  * Should clearly explain the consequences of the action being confirmed.
- * Automatically provides proper ARIA description for screen readers.
+ * Automatically provides proper ARIA description via aria-describedby for
+ * screen readers. Can be omitted if aria-describedby is provided to Content.
  *
- * @param className - Additional CSS classes to apply
- * @param props - All other props are forwarded to the underlying Radix AlertDialog.Description
+ * @param asChild - Render as child element, merging props and behavior
+ * @param className - Additional CSS classes for custom styling
+ * @param props - All other props forwarded to Radix AlertDialog.Description
  *
  * @example
  * ```tsx
+ * // Standard descriptions
  * <AlertDialogDescription>
  *   This action cannot be undone. This will permanently delete your
  *   account and remove your data from our servers.
  * </AlertDialogDescription>
+ *
+ * <AlertDialogDescription>
+ *   You will be signed out of all devices and will need to sign in again
+ *   to access your account.
+ * </AlertDialogDescription>
+ *
+ * // Custom styling
+ * <AlertDialogDescription className="text-center text-lg">
+ *   Are you sure you want to continue?
+ * </AlertDialogDescription>
+ *
+ * // Composition with custom element
+ * <AlertDialogDescription asChild>
+ *   <p className="custom-description">
+ *     Custom description element
+ *   </p>
+ * </AlertDialogDescription>
  * ```
  */
 function AlertDialogDescription({
   className,
   ...props
-}: React.ComponentProps<typeof AlertDialogPrimitive.Description>) {
+}: React.ComponentProps<typeof AlertDialogPrimitive.Description> & {
+  className?: string;
+}) {
   return (
     <AlertDialogPrimitive.Description
       data-slot="alert-dialog-description"
@@ -314,28 +635,44 @@ function AlertDialogDescription({
  * Primary action button of the alert dialog
  *
  * The button that confirms or executes the action being alerted about.
- * Automatically receives focus when the dialog opens. Styled as a primary
- * button by default, but can be customized for destructive actions.
- * Closes the dialog when clicked.
+ * Automatically receives focus when the dialog opens (unless overridden).
+ * Styled using buttonVariants() by default, but can be customized for
+ * destructive actions. Closes the dialog when clicked.
  *
- * @param className - Additional CSS classes to apply (useful for destructive styling)
- * @param props - All other props are forwarded to the underlying Radix AlertDialog.Action
+ * @param asChild - Render as child element, merging props and behavior
+ * @param className - Additional CSS classes (useful for destructive styling)
+ * @param props - All other props forwarded to Radix AlertDialog.Action
  *
  * @example
  * ```tsx
- * // Default action
+ * // Default action (primary button style)
  * <AlertDialogAction>Continue</AlertDialogAction>
+ * <AlertDialogAction>Save Changes</AlertDialogAction>
  *
- * // Destructive action
- * <AlertDialogAction className="bg-red-600 hover:bg-red-700">
+ * // Destructive action with red styling
+ * <AlertDialogAction className={buttonVariants({ variant: "destructive" })}>
  *   Delete Account
  * </AlertDialogAction>
+ *
+ * // Custom styled action
+ * <AlertDialogAction className="bg-green-600 hover:bg-green-700">
+ *   Confirm Action
+ * </AlertDialogAction>
+ *
+ * // Composition with custom button
+ * <AlertDialogAction asChild>
+ *   <Button variant="destructive" size="lg">
+ *     Delete Forever
+ *   </Button>
+ * </AlertDialogAction>
  * ```
  */
 function AlertDialogAction({
   className,
   ...props
-}: React.ComponentProps<typeof AlertDialogPrimitive.Action>) {
+}: React.ComponentProps<typeof AlertDialogPrimitive.Action> & {
+  className?: string;
+}) {
   return (
     <AlertDialogPrimitive.Action
       className={cn(buttonVariants(), className)}
@@ -348,22 +685,40 @@ function AlertDialogAction({
  * Cancel button of the alert dialog
  *
  * The button that dismisses the dialog without performing the action.
- * Styled as an outline button by default to de-emphasize compared to
- * the primary action. Closes the dialog when clicked.
+ * Styled using outline variant by default to de-emphasize compared to
+ * the primary action. Closes the dialog when clicked without triggering
+ * the main action.
  *
- * @param className - Additional CSS classes to apply
- * @param props - All other props are forwarded to the underlying Radix AlertDialog.Cancel
+ * @param asChild - Render as child element, merging props and behavior
+ * @param className - Additional CSS classes for custom styling
+ * @param props - All other props forwarded to Radix AlertDialog.Cancel
  *
  * @example
  * ```tsx
+ * // Standard cancel buttons
  * <AlertDialogCancel>Cancel</AlertDialogCancel>
  * <AlertDialogCancel>No, keep it</AlertDialogCancel>
+ * <AlertDialogCancel>Go Back</AlertDialogCancel>
+ *
+ * // Custom styled cancel
+ * <AlertDialogCancel className="text-red-600">
+ *   Don't Delete
+ * </AlertDialogCancel>
+ *
+ * // Composition with custom button
+ * <AlertDialogCancel asChild>
+ *   <Button variant="ghost" size="sm">
+ *     Maybe Later
+ *   </Button>
+ * </AlertDialogCancel>
  * ```
  */
 function AlertDialogCancel({
   className,
   ...props
-}: React.ComponentProps<typeof AlertDialogPrimitive.Cancel>) {
+}: React.ComponentProps<typeof AlertDialogPrimitive.Cancel> & {
+  className?: string;
+}) {
   return (
     <AlertDialogPrimitive.Cancel
       className={cn(buttonVariants({ variant: "outline" }), className)}