@neynar/ui 0.4.0 → 0.5.0

package/src/components/ui/dialog.tsx

@@ -1,438 +1,61 @@
+"use client";
+
 import * as React from "react";
-import * as DialogPrimitive from "@radix-ui/react-dialog";
-import { XIcon } from "lucide-react";
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
 
 import { cn } from "@/lib/utils";
+import { Button } from "@/components/ui/button";
+import { XIcon } from "lucide-react";
 
-/**
- * Props for Dialog 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 DialogDocsProps = {
-  /** The controlled open state of the dialog. Must be used in conjunction with onOpenChange */
-  open?: boolean;
-  /** The open state of the dialog when it is initially rendered. Use when you do not need to control its open state @default false */
-  defaultOpen?: boolean;
-  /** Event handler called when the open state of the dialog changes */
-  onOpenChange?: (open: boolean) => void;
-  /** The modality of the dialog. When set to true, interaction with outside elements will be disabled and only dialog content will be visible to screen readers @default true */
-  modal?: boolean;
-  /** Child components including DialogTrigger and DialogContent */
-  children?: React.ReactNode;
-};
-
-/**
- * Props for DialogTrigger 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 DialogTriggerDocsProps = {
-  /** Render the trigger as its child element when true, merging their props and behavior @default false */
-  asChild?: boolean;
-  /** Additional CSS classes for styling */
-  className?: string;
-  /** Content to display in the trigger (typically a button or interactive element) */
-  children?: React.ReactNode;
-} & React.ButtonHTMLAttributes<HTMLButtonElement>;
-
-/**
- * Props for DialogPortal 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 DialogPortalDocsProps = {
-  /** Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries */
-  forceMount?: boolean;
-  /** Specify a container element to portal the content into @default document.body */
-  container?: HTMLElement;
-  /** Child components to portal (typically DialogOverlay and DialogContent) */
-  children?: React.ReactNode;
-};
-
-/**
- * Props for DialogClose 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 DialogCloseDocsProps = {
-  /** Render the close button as its child element when true, merging their props and behavior @default false */
-  asChild?: boolean;
-  /** Additional CSS classes for styling */
-  className?: string;
-  /** Content to display in the close button */
-  children?: React.ReactNode;
-} & React.ButtonHTMLAttributes<HTMLButtonElement>;
-
-/**
- * Props for DialogOverlay 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 DialogOverlayDocsProps = {
-  /** Render the overlay as its child element when true, merging their props and behavior @default false */
-  asChild?: boolean;
-  /** Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries */
-  forceMount?: boolean;
-  /** Additional CSS classes for custom styling */
-  className?: string;
-  /** Child components (rarely used for overlays) */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLDivElement>;
-
-/**
- * Props for DialogContent 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 DialogContentDocsProps = {
-  /** Render the content as its child element when true, merging their props and behavior @default false */
-  asChild?: boolean;
-  /** Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries */
-  forceMount?: boolean;
-  /** Event handler called when focus moves into the component after opening. It can be prevented by calling event.preventDefault */
-  onOpenAutoFocus?: (event: Event) => void;
-  /** Event handler called when focus moves to the trigger after closing. It can be prevented by calling event.preventDefault */
-  onCloseAutoFocus?: (event: Event) => void;
-  /** Event handler called when the escape key is down. It can be prevented by calling event.preventDefault */
-  onEscapeKeyDown?: (event: KeyboardEvent) => void;
-  /** Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling event.preventDefault */
-  onPointerDownOutside?: (event: PointerEvent) => void;
-  /** Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling event.preventDefault */
-  onInteractOutside?: (
-    event: React.FocusEvent | MouseEvent | TouchEvent,
-  ) => void;
-  /** Whether to show the X close button in top-right corner @default true */
-  showCloseButton?: boolean;
-  /** Additional CSS classes for styling the content container */
-  className?: string;
-  /** Dialog content including header, body, and footer elements */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLDivElement>;
-
-/**
- * Props for DialogHeader 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 DialogHeaderDocsProps = {
-  /** Additional CSS classes for styling */
-  className?: string;
-  /** Header content including DialogTitle and DialogDescription */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLDivElement>;
-
-/**
- * Props for DialogFooter 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 DialogFooterDocsProps = {
-  /** Additional CSS classes for styling */
-  className?: string;
-  /** Footer content typically containing action buttons */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLDivElement>;
-
-/**
- * Props for DialogTitle 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 DialogTitleDocsProps = {
-  /** Render the title as its child element when true, merging their props and behavior @default false */
-  asChild?: boolean;
-  /** Additional CSS classes for styling */
-  className?: string;
-  /** Title content (text or components) */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLHeadingElement>;
-
-/**
- * Props for DialogDescription 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 DialogDescriptionDocsProps = {
-  /** Render the description as its child element when true, merging their props and behavior @default false */
-  asChild?: boolean;
-  /** Additional CSS classes for styling */
-  className?: string;
-  /** Description content (text or components) */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLParagraphElement>;
+type DialogProps = DialogPrimitive.Root.Props;
 
 /**
- * Dialog - A modal dialog component for important content or actions
- *
- * A modal window overlay component built on Radix UI Dialog primitives that interrupts
- * the user's workflow to capture their attention for important interactions. Dialogs render
- * content in a layer above the main application with proper focus management and accessibility.
- *
- * Use dialogs for critical interactions, confirmations, forms, or detailed information that
- * requires user focus and prevents interaction with the background content.
- *
- * @example
- * ```tsx
- * // Basic confirmation dialog
- * <Dialog>
- *   <DialogTrigger asChild>
- *     <Button>Open Dialog</Button>
- *   </DialogTrigger>
- *   <DialogContent>
- *     <DialogHeader>
- *       <DialogTitle>Are you sure?</DialogTitle>
- *       <DialogDescription>
- *         This action cannot be undone.
- *       </DialogDescription>
- *     </DialogHeader>
- *     <DialogFooter>
- *       <Button variant="outline">Cancel</Button>
- *       <Button>Continue</Button>
- *     </DialogFooter>
- *   </DialogContent>
- * </Dialog>
- * ```
- *
- * @example
- * ```tsx
- * // Controlled dialog with form handling
- * const [open, setOpen] = useState(false);
- *
- * <Dialog open={open} onOpenChange={setOpen}>
- *   <DialogTrigger asChild>
- *     <Button>Edit Profile</Button>
- *   </DialogTrigger>
- *   <DialogContent className="sm:max-w-[425px]">
- *     <DialogHeader>
- *       <DialogTitle>Edit profile</DialogTitle>
- *       <DialogDescription>
- *         Make changes to your profile here. Click save when you're done.
- *       </DialogDescription>
- *     </DialogHeader>
- *     <form onSubmit={handleSubmit}>
- *       <div className="grid gap-4 py-4">
- *         <Input label="Name" defaultValue="John Doe" />
- *         <Input label="Username" defaultValue="@johndoe" />
- *       </div>
- *       <DialogFooter>
- *         <Button type="submit">Save changes</Button>
- *       </DialogFooter>
- *     </form>
- *   </DialogContent>
- * </Dialog>
- * ```
- *
- * @example
- * ```tsx
- * // Custom close behavior
- * <Dialog>
- *   <DialogTrigger asChild>
- *     <Button>Share Link</Button>
- *   </DialogTrigger>
- *   <DialogContent showCloseButton={false}>
- *     <DialogHeader>
- *       <DialogTitle>Share this link</DialogTitle>
- *     </DialogHeader>
- *     <div className="flex items-center space-x-2">
- *       <Input value="https://example.com" readOnly />
- *       <Button size="sm"><Copy className="h-4 w-4" /></Button>
- *     </div>
- *     <DialogFooter>
- *       <DialogClose asChild>
- *         <Button variant="secondary">Done</Button>
- *       </DialogClose>
- *     </DialogFooter>
- *   </DialogContent>
- * </Dialog>
- * ```
- *
- * @accessibility
- * - Focus trapped within dialog when open using Radix UI focus management
- * - Escape key closes the dialog (can be disabled with `modal={false}`)
- * - Background scroll locked when dialog is open
- * - Proper ARIA attributes including aria-labelledby and aria-describedby
- * - Screen reader announcements when dialog opens/closes
- * - Focus returns to trigger element when dialog closes
- * - Background content becomes inert (non-interactive)
- * - Keyboard navigation between focusable elements
- * - Space/Enter keys open and close dialog
- * - Tab/Shift+Tab moves focus between interactive elements
- *
- * @see {@link https://ui.shadcn.com/docs/components/dialog} shadcn/ui Dialog documentation
- * @see {@link https://www.radix-ui.com/primitives/docs/components/dialog} Radix UI Dialog primitives
- * @see {@link DialogTrigger} Button that opens the dialog
- * @see {@link DialogContent} Main content container with overlay and portal
- * @see {@link DialogHeader} Container for title and description
- * @see {@link DialogFooter} Container for action buttons
- * @since 1.0.0
+ * Root dialog component. Groups all parts of the dialog and manages open state.
+ * Use with controlled (`open`/`onOpenChange`) or uncontrolled (`defaultOpen`) state.
  */
-function Dialog(props: React.ComponentProps<typeof DialogPrimitive.Root>) {
+function Dialog({ ...props }: DialogProps) {
   return <DialogPrimitive.Root data-slot="dialog" {...props} />;
 }
 
+type DialogTriggerProps = DialogPrimitive.Trigger.Props;
+
 /**
- * DialogTrigger - The element that opens the dialog when clicked
- *
- * Typically wraps a button or other interactive element. Use asChild
- * prop to render as the child element instead of a button. The trigger
- * automatically receives focus management and ARIA attributes.
- *
- * @example
- * ```tsx
- * <DialogTrigger asChild>
- *   <Button>Open Dialog</Button>
- * </DialogTrigger>
- * ```
- *
- * @example
- * ```tsx
- * // Direct button without asChild
- * <DialogTrigger className="custom-trigger-style">
- *   Click to open
- * </DialogTrigger>
- * ```
- *
- * @accessibility
- * - Automatically receives aria-expanded attribute based on dialog state
- * - Keyboard activation with Space and Enter keys
- * - Focus returns here when dialog closes
- * - Screen reader compatible with role="button" when used as direct element
- *
- * @see {@link Dialog} The root dialog container
- * @see {@link DialogContent} The content opened by this trigger
- * @since 1.0.0
+ * Button that opens the dialog. Use `render` prop to customize the trigger element.
  */
-function DialogTrigger(
-  props: React.ComponentProps<typeof DialogPrimitive.Trigger>,
-) {
+function DialogTrigger({ ...props }: DialogTriggerProps) {
   return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />;
 }
 
+type DialogPortalProps = DialogPrimitive.Portal.Props;
+
 /**
- * DialogPortal - Portal container for dialog content
- *
- * Renders dialog content in a React portal at the end of the document body.
- * This ensures proper stacking context and prevents z-index issues. Rarely
- * used directly - typically included automatically by DialogContent.
- *
- * @example
- * ```tsx
- * // Custom portal container
- * const [container, setContainer] = useState(null);
- *
- * <DialogPortal container={container}>
- *   <DialogOverlay />
- *   <DialogContent>Portal content</DialogContent>
- * </DialogPortal>
- * <div ref={setContainer} />
- * ```
- *
- * @accessibility
- * - Ensures dialog renders outside normal DOM flow for proper focus management
- * - Maintains proper stacking order for screen readers
- * - Portal location doesn't affect ARIA relationships
- *
- * @see {@link DialogContent} Component that typically includes this portal
- * @since 1.0.0
+ * Portal component that renders dialog content at document root.
+ * Automatically used by DialogContent - rarely needed directly.
  */
-function DialogPortal(
-  props: React.ComponentProps<typeof DialogPrimitive.Portal>,
-) {
+function DialogPortal({ ...props }: DialogPortalProps) {
   return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />;
 }
 
+type DialogCloseProps = DialogPrimitive.Close.Props;
+
 /**
- * DialogClose - A close button that dismisses the dialog
- *
- * Can be placed anywhere within DialogContent to provide a close action.
- * Typically used for custom close buttons in addition to the default X button.
- * Automatically closes the dialog when activated and returns focus to the trigger.
- *
- * @example
- * ```tsx
- * <DialogClose asChild>
- *   <Button variant="outline">Cancel</Button>
- * </DialogClose>
- * ```
- *
- * @example
- * ```tsx
- * // Direct button without asChild
- * <DialogClose className="close-button">
- *   Close Dialog
- * </DialogClose>
- * ```
- *
- * @example
- * ```tsx
- * // In footer with multiple actions
- * <DialogFooter>
- *   <DialogClose asChild>
- *     <Button variant="outline">Cancel</Button>
- *   </DialogClose>
- *   <Button type="submit">Save</Button>
- * </DialogFooter>
- * ```
- *
- * @accessibility
- * - Keyboard activation with Space and Enter keys
- * - Screen reader compatible with proper labeling
- * - Focus management returns to dialog trigger
- * - Can be used as implicit cancel action
- *
- * @see {@link DialogContent} Container that includes the default close button
- * @see {@link Dialog} Root component for controlling open state
- * @since 1.0.0
+ * Button that closes the dialog. Can be styled using the `render` prop.
  */
-function DialogClose(
-  props: React.ComponentProps<typeof DialogPrimitive.Close>,
-) {
+function DialogClose({ ...props }: DialogCloseProps) {
   return <DialogPrimitive.Close data-slot="dialog-close" {...props} />;
 }
 
+type DialogOverlayProps = DialogPrimitive.Backdrop.Props;
+
 /**
- * DialogOverlay - The backdrop overlay behind the dialog
- *
- * Provides a semi-transparent background that covers the main content.
- * Clicking the overlay will close the dialog by default. Features smooth
- * fade animations using Tailwind CSS and proper z-index stacking.
- *
- * @example
- * ```tsx
- * // Custom overlay styling
- * <DialogOverlay className="bg-red-500/20 backdrop-blur-sm" />
- * ```
- *
- * @example
- * ```tsx
- * // Typically used automatically within DialogContent
- * <DialogContent>
- *   // DialogOverlay is included automatically
- *   <DialogTitle>Dialog content</DialogTitle>
- * </DialogContent>
- * ```
- *
- * @accessibility
- * - Prevents interaction with background content (makes it inert)
- * - Can be clicked to dismiss dialog (respects modal prop)
- * - Proper z-index ensures overlay appears above page content
- * - Fade animations respect prefers-reduced-motion settings
- * - Background becomes non-focusable when dialog is open
- *
- * @see {@link DialogContent} Component that typically includes this overlay
- * @see {@link DialogPortal} Portal container for rendering overlay
- * @since 1.0.0
+ * Backdrop overlay that appears behind the dialog with blur effect.
  */
-function DialogOverlay({
-  className,
-  ...props
-}: React.ComponentProps<typeof DialogPrimitive.Overlay>) {
+function DialogOverlay({ className, ...props }: DialogOverlayProps) {
   return (
-    <DialogPrimitive.Overlay
+    <DialogPrimitive.Backdrop
       data-slot="dialog-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",
+        "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs fixed inset-0 isolate z-50",
         className,
       )}
       {...props}
@@ -440,93 +63,31 @@ function DialogOverlay({
   );
 }
 
+type DialogContentProps = DialogPrimitive.Popup.Props & {
+  /**
+   * Show close button (X) in top-right corner.
+   * @default true
+   */
+  showCloseButton?: boolean;
+};
+
 /**
- * DialogContent - The main content container for the dialog
- *
- * The primary container for dialog content that automatically includes the overlay and portal.
- * Provides the visual dialog box with animations, positioning, and focus management.
- * Includes a close button (X) by default which can be hidden using the showCloseButton prop.
- *
- * @component
- * @example
- * ```tsx
- * // Standard content with header and footer
- * <DialogContent>
- *   <DialogHeader>
- *     <DialogTitle>Dialog Title</DialogTitle>
- *     <DialogDescription>
- *       Detailed description of the dialog's purpose
- *     </DialogDescription>
- *   </DialogHeader>
- *   <div className="py-4">
- *     Main dialog content goes here
- *   </div>
- *   <DialogFooter>
- *     <Button variant="outline">Cancel</Button>
- *     <Button>Confirm</Button>
- *   </DialogFooter>
- * </DialogContent>
- * ```
- *
- * @example
- * ```tsx
- * // Custom sizing and scrollable content
- * <DialogContent className="sm:max-w-[425px] max-h-[80vh] overflow-y-auto">
- *   <DialogHeader>
- *     <DialogTitle>Long Content</DialogTitle>
- *   </DialogHeader>
- *   <div className="space-y-4">
- *     // Long scrollable content
- *   </div>
- * </DialogContent>
- * ```
- *
- * @example
- * ```tsx
- * // Without default close button
- * <DialogContent showCloseButton={false}>
- *   <DialogHeader>
- *     <DialogTitle>Custom Close</DialogTitle>
- *   </DialogHeader>
- *   <div>Content without X button</div>
- *   <DialogFooter>
- *     <DialogClose asChild>
- *       <Button>Close</Button>
- *     </DialogClose>
- *   </DialogFooter>
- * </DialogContent>
- * ```
- *
- * @accessibility
- * - Automatically focuses first focusable element on open
- * - Traps focus within the dialog using Radix UI focus management
- * - Includes accessible close button with screen reader text ("Close")
- * - Proper ARIA labeling automatically applied via DialogTitle and DialogDescription
- * - ESC key support for closing (when modal={true})
- * - Click outside to close (when modal={true})
- *
- * @param className - Additional CSS classes to apply to the content container
- * @param children - Dialog content including header, body, and footer elements
- * @param showCloseButton - Whether to show the X close button in top-right corner (default: true)
- * @param ...props - All other props from Radix UI Dialog.Content including positioning and animation props
- *
- * @since 1.0.0
+ * Main dialog content container with automatic portal and backdrop overlay.
+ * Centered on screen with fade and zoom animations.
  */
 function DialogContent({
   className,
   children,
   showCloseButton = true,
   ...props
-}: React.ComponentProps<typeof DialogPrimitive.Content> & {
-  showCloseButton?: boolean;
-}) {
+}: DialogContentProps) {
   return (
-    <DialogPortal data-slot="dialog-portal">
+    <DialogPortal>
       <DialogOverlay />
-      <DialogPrimitive.Content
+      <DialogPrimitive.Popup
         data-slot="dialog-content"
         className={cn(
-          "bg-background data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6 shadow-lg duration-200 sm:max-w-lg",
+          "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 ring-border grid max-w-[calc(100%-2rem)] gap-6 rounded-xl p-6 text-sm ring-1 duration-100 sm:max-w-md fixed top-1/2 left-1/2 z-50 w-full -translate-x-1/2 -translate-y-1/2 outline-none",
           className,
         )}
         {...props}
@@ -535,136 +96,102 @@ function DialogContent({
         {showCloseButton && (
           <DialogPrimitive.Close
             data-slot="dialog-close"
-            className="ring-offset-background focus:ring-ring data-[state=open]:bg-accent data-[state=open]:text-muted-foreground 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 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4"
+            render={
+              <Button
+                variant="ghost"
+                className="absolute top-4 right-4"
+                size="icon-sm"
+              />
+            }
           >
             <XIcon />
             <span className="sr-only">Close</span>
           </DialogPrimitive.Close>
         )}
-      </DialogPrimitive.Content>
+      </DialogPrimitive.Popup>
     </DialogPortal>
   );
 }
 
+type DialogHeaderProps = React.ComponentProps<"div">;
+
 /**
- * DialogHeader - Container for dialog title and description
- *
- * Groups the dialog's title and description at the top of the dialog content.
- * Provides consistent spacing and alignment for header elements.
- *
- * @component
- * @example
- * ```tsx
- * <DialogHeader>
- *   <DialogTitle>Edit profile</DialogTitle>
- *   <DialogDescription>
- *     Make changes to your profile here. Click save when you're done.
- *   </DialogDescription>
- * </DialogHeader>
- * ```
- * @since 1.0.0
+ * Container for dialog title and description. Provides consistent spacing.
  */
-function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
+function DialogHeader({ className, ...props }: DialogHeaderProps) {
   return (
     <div
       data-slot="dialog-header"
-      className={cn("flex flex-col gap-2 text-center sm:text-left", className)}
+      className={cn("gap-2 flex flex-col", className)}
       {...props}
     />
   );
 }
 
+type DialogFooterProps = React.ComponentProps<"div"> & {
+  /**
+   * Show a "Close" button in the footer.
+   * @default false
+   */
+  showCloseButton?: boolean;
+};
+
 /**
- * DialogFooter - Container for dialog action buttons
- *
- * Typically contains action buttons like Save, Cancel, or Submit.
- * Automatically handles responsive layout with proper button alignment.
- *
- * @component
- * @example
- * ```tsx
- * <DialogFooter>
- *   <Button variant="outline">Cancel</Button>
- *   <Button type="submit">Save changes</Button>
- * </DialogFooter>
- * ```
- *
- * @accessibility
- * - Buttons are arranged in logical order for keyboard navigation
- * - Mobile-responsive layout
- * @since 1.0.0
+ * Container for dialog actions. Stacks vertically on mobile, horizontal on desktop.
  */
-function DialogFooter({ className, ...props }: React.ComponentProps<"div">) {
+function DialogFooter({
+  className,
+  showCloseButton = false,
+  children,
+  ...props
+}: DialogFooterProps) {
   return (
     <div
       data-slot="dialog-footer"
       className={cn(
-        "flex flex-col-reverse gap-2 sm:flex-row sm:justify-end",
+        "gap-2 flex flex-col-reverse gap-2 sm:flex-row sm:justify-end",
         className,
       )}
       {...props}
-    />
+    >
+      {children}
+      {showCloseButton && (
+        <DialogPrimitive.Close render={<Button variant="outline" />}>
+          Close
+        </DialogPrimitive.Close>
+      )}
+    </div>
   );
 }
 
+type DialogTitleProps = DialogPrimitive.Title.Props;
+
 /**
- * DialogTitle - The main heading of the dialog
- *
- * Provides the accessible name for the dialog. Should clearly describe
- * the dialog's purpose or the action being performed.
- *
- * @component
- * @example
- * ```tsx
- * <DialogTitle>Delete Account</DialogTitle>
- * ```
- *
- * @accessibility
- * - Automatically sets aria-labelledby on the dialog
- * - Should be descriptive and concise
- * @since 1.0.0
+ * Dialog title with accessible heading semantics. Required for screen readers.
  */
-function DialogTitle({
-  className,
-  ...props
-}: React.ComponentProps<typeof DialogPrimitive.Title>) {
+function DialogTitle({ className, ...props }: DialogTitleProps) {
   return (
     <DialogPrimitive.Title
       data-slot="dialog-title"
-      className={cn("text-lg leading-none font-semibold", className)}
+      className={cn("leading-none font-medium", className)}
       {...props}
     />
   );
 }
 
+type DialogDescriptionProps = DialogPrimitive.Description.Props;
+
 /**
- * DialogDescription - Supplementary description for the dialog
- *
- * Provides additional context or instructions for the dialog content.
- * Helps users understand what action they're about to take.
- *
- * @component
- * @example
- * ```tsx
- * <DialogDescription>
- *   This action cannot be undone. This will permanently delete your
- *   account and remove your data from our servers.
- * </DialogDescription>
- * ```
- *
- * @accessibility
- * - Automatically sets aria-describedby on the dialog
- * - Important for screen reader users to understand context
- * @since 1.0.0
+ * Dialog description providing additional context. Supports inline links with hover effects.
  */
-function DialogDescription({
-  className,
-  ...props
-}: React.ComponentProps<typeof DialogPrimitive.Description>) {
+function DialogDescription({ className, ...props }: DialogDescriptionProps) {
   return (
     <DialogPrimitive.Description
       data-slot="dialog-description"
-      className={cn("text-muted-foreground text-sm", className)}
+      className={cn(
+        "text-muted-foreground *:[a]:hover:text-foreground text-sm *:[a]:underline *:[a]:underline-offset-3",
+        className,
+      )}
       {...props}
     />
   );
@@ -681,4 +208,14 @@ export {
   DialogPortal,
   DialogTitle,
   DialogTrigger,
+  type DialogProps,
+  type DialogCloseProps,
+  type DialogContentProps,
+  type DialogDescriptionProps,
+  type DialogFooterProps,
+  type DialogHeaderProps,
+  type DialogOverlayProps,
+  type DialogPortalProps,
+  type DialogTitleProps,
+  type DialogTriggerProps,
 };