@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/dialog.tsx

@@ -4,6 +4,164 @@ import { XIcon } from "lucide-react";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * 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>;
+
 /**
  * Dialog - A modal dialog component for important content or actions
  *
@@ -14,7 +172,6 @@ import { cn } from "@/lib/utils";
  * Use dialogs for critical interactions, confirmations, forms, or detailed information that
  * requires user focus and prevents interaction with the background content.
  *
- * @component
  * @example
  * ```tsx
  * // Basic confirmation dialog
@@ -99,22 +256,18 @@ import { cn } from "@/lib/utils";
  * - Focus returns to trigger element when dialog closes
  * - Background content becomes inert (non-interactive)
  * - Keyboard navigation between focusable elements
- *
- * @param open - Controlled open state of the dialog
- * @param onOpenChange - Callback fired when open state changes
- * @param modal - Whether dialog is modal (default: true). Non-modal allows background interaction
- * @param defaultOpen - Default open state for uncontrolled usage
- *
- * @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 AlertDialog} - For confirmation dialogs with specific alert semantics
- * @see {@link Sheet} - For side panel overlays
- * @see {@link Drawer} - For mobile-friendly bottom overlays
+ * - 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
  */
-function Dialog({
-  ...props
-}: React.ComponentProps<typeof DialogPrimitive.Root>) {
+function Dialog(props: React.ComponentProps<typeof DialogPrimitive.Root>) {
   return <DialogPrimitive.Root data-slot="dialog" {...props} />;
 }
 
@@ -122,20 +275,37 @@ function Dialog({
  * 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.
+ * prop to render as the child element instead of a button. The trigger
+ * automatically receives focus management and ARIA attributes.
  *
- * @component
  * @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
  */
-function DialogTrigger({
-  ...props
-}: React.ComponentProps<typeof DialogPrimitive.Trigger>) {
+function DialogTrigger(
+  props: React.ComponentProps<typeof DialogPrimitive.Trigger>,
+) {
   return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />;
 }
 
@@ -143,14 +313,32 @@ function DialogTrigger({
  * 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.
+ * This ensures proper stacking context and prevents z-index issues. Rarely
+ * used directly - typically included automatically by DialogContent.
  *
- * @component
+ * @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
  */
-function DialogPortal({
-  ...props
-}: React.ComponentProps<typeof DialogPrimitive.Portal>) {
+function DialogPortal(
+  props: React.ComponentProps<typeof DialogPrimitive.Portal>,
+) {
   return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />;
 }
 
@@ -159,19 +347,47 @@ function DialogPortal({
  *
  * 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.
  *
- * @component
  * @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
  */
-function DialogClose({
-  ...props
-}: React.ComponentProps<typeof DialogPrimitive.Close>) {
+function DialogClose(
+  props: React.ComponentProps<typeof DialogPrimitive.Close>,
+) {
   return <DialogPrimitive.Close data-slot="dialog-close" {...props} />;
 }
 
@@ -179,12 +395,33 @@ function DialogClose({
  * 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.
+ * 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>
+ * ```
  *
- * @component
  * @accessibility
- * - Prevents interaction with background content
- * - Can be clicked to dismiss dialog (configurable)
+ * - 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
  */
 function DialogOverlay({