@neynar/ui 0.1.1

package/src/components/ui/date-picker.tsx

@@ -0,0 +1,213 @@
+import * as React from "react";
+import { format } from "date-fns";
+import { CalendarIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+import { Button } from "./button";
+import { Calendar } from "./calendar";
+import { Popover, PopoverContent, PopoverTrigger } from "./popover";
+
+/**
+ * Properties for the DatePicker component
+ *
+ * @type DatePickerProps
+ * @since 1.0.0
+ */
+type DatePickerProps = {
+  /**
+   * The currently selected date value. When undefined, no date is selected.
+   *
+   * @example
+   * ```tsx
+   * const [selectedDate, setSelectedDate] = useState<Date>();
+   * <DatePicker date={selectedDate} onDateChange={setSelectedDate} />
+   * ```
+   */
+  date?: Date;
+
+  /**
+   * Callback function invoked when the user selects or clears a date.
+   * Receives the selected date or undefined when cleared.
+   *
+   * @param date - The newly selected date or undefined if cleared
+   *
+   * @example
+   * ```tsx
+   * <DatePicker onDateChange={(date) => console.log('Selected:', date)} />
+   * ```
+   */
+  onDateChange?: (date: Date | undefined) => void;
+
+  /**
+   * Placeholder text displayed in the trigger button when no date is selected.
+   * Provides context about what kind of date selection is expected.
+   *
+   * @default "Pick a date"
+   *
+   * @example
+   * ```tsx
+   * <DatePicker placeholder="Select your birthday" />
+   * ```
+   */
+  placeholder?: string;
+
+  /**
+   * When true, disables the date picker preventing user interaction.
+   * The trigger button will appear disabled and the popover cannot be opened.
+   *
+   * @default false
+   *
+   * @example
+   * ```tsx
+   * <DatePicker disabled={true} placeholder="Date locked" />
+   * ```
+   */
+  disabled?: boolean;
+
+  /**
+   * Additional CSS classes to apply to the trigger button.
+   * Useful for customizing width, spacing, or other styling.
+   *
+   * @example
+   * ```tsx
+   * <DatePicker className="w-full" /> // Full width
+   * <DatePicker className="w-[300px]" /> // Fixed width
+   * ```
+   */
+  className?: string;
+};
+
+/**
+ * A comprehensive date selection component that combines an accessible button trigger
+ * with a full-featured calendar popover for intuitive date picking.
+ *
+ * Built on shadcn/ui design principles, this component provides a polished interface
+ * for date selection with proper accessibility, keyboard navigation, and visual feedback.
+ * The selected date is displayed using date-fns formatting for consistent presentation.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic controlled date picker
+ * const [date, setDate] = useState<Date>();
+ *
+ * <DatePicker
+ *   date={date}
+ *   onDateChange={setDate}
+ *   placeholder="Select date"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Date picker for forms with validation
+ * const [birthDate, setBirthDate] = useState<Date>();
+ *
+ * <DatePicker
+ *   date={birthDate}
+ *   onDateChange={setBirthDate}
+ *   placeholder="Select birth date"
+ *   className="w-[280px]"
+ *   disabled={isSubmitting}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Date range start/end picker
+ * <div className="flex gap-2 items-center">
+ *   <DatePicker
+ *     date={startDate}
+ *     onDateChange={setStartDate}
+ *     placeholder="Start date"
+ *     className="w-[180px]"
+ *   />
+ *   <span>to</span>
+ *   <DatePicker
+ *     date={endDate}
+ *     onDateChange={setEndDate}
+ *     placeholder="End date"
+ *     className="w-[180px]"
+ *   />
+ * </div>
+ * ```
+ *
+ * @accessibility
+ * - **Keyboard Navigation**: Full keyboard support with Tab, Enter, Escape, and arrow keys
+ * - **Screen Reader Support**: Proper ARIA labels and live announcements for date changes
+ * - **Focus Management**: Focus returns to trigger button when popover closes
+ * - **Visual Indicators**: Clear visual states for disabled, selected, and focused elements
+ * - **Date Formatting**: Consistent date presentation using localized formatting
+ *
+ * @features
+ * - Single date selection with visual confirmation
+ * - Popover-based calendar that doesn't interfere with page layout
+ * - Automatic popover positioning and collision detection
+ * - Internal state management with optional external control
+ * - Customizable trigger button styling and width
+ * - Date formatting using date-fns for internationalization support
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/date-picker} shadcn/ui Date Picker patterns
+ * @see {@link Calendar} - The underlying calendar component
+ * @see {@link Popover} - The popover container component
+ * @see {@link Button} - The trigger button component
+ *
+ * @since 1.0.0
+ */
+function DatePicker({
+  date,
+  onDateChange,
+  placeholder = "Pick a date",
+  disabled = false,
+  className,
+}: DatePickerProps) {
+  // Internal state for uncontrolled usage and popover open/close
+  const [internalDate, setInternalDate] = React.useState<Date | undefined>(
+    date,
+  );
+  const [open, setOpen] = React.useState(false);
+
+  // Sync internal state when controlled date prop changes
+  React.useEffect(() => {
+    setInternalDate(date);
+  }, [date]);
+
+  /**
+   * Handles date selection from the calendar.
+   * Updates internal state, calls the onChange callback, and closes the popover.
+   */
+  const handleDateSelect = (selectedDate: Date | undefined) => {
+    setInternalDate(selectedDate);
+    onDateChange?.(selectedDate);
+    setOpen(false);
+  };
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          variant="outline"
+          className={cn(
+            "w-[240px] justify-start text-left font-normal",
+            !internalDate && "text-muted-foreground",
+            className,
+          )}
+          disabled={disabled}
+        >
+          <CalendarIcon className="mr-2 h-4 w-4" />
+          {internalDate ? format(internalDate, "PPP") : placeholder}
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-auto p-0" align="start">
+        <Calendar
+          mode="single"
+          selected={internalDate}
+          onSelect={handleDateSelect}
+          initialFocus
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+export { DatePicker };

package/src/components/ui/dialog.tsx

@@ -0,0 +1,447 @@
+import * as React from "react";
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+import { XIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * 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.
+ *
+ * @component
+ * @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
+ *
+ * @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
+ * @since 1.0.0
+ */
+function Dialog({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Root>) {
+  return <DialogPrimitive.Root data-slot="dialog" {...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.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <DialogTrigger asChild>
+ *   <Button>Open Dialog</Button>
+ * </DialogTrigger>
+ * ```
+ * @since 1.0.0
+ */
+function DialogTrigger({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Trigger>) {
+  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...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.
+ *
+ * @component
+ * @since 1.0.0
+ */
+function DialogPortal({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Portal>) {
+  return <DialogPrimitive.Portal data-slot="dialog-portal" {...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.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <DialogClose asChild>
+ *   <Button variant="outline">Cancel</Button>
+ * </DialogClose>
+ * ```
+ * @since 1.0.0
+ */
+function DialogClose({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Close>) {
+  return <DialogPrimitive.Close data-slot="dialog-close" {...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.
+ *
+ * @component
+ * @accessibility
+ * - Prevents interaction with background content
+ * - Can be clicked to dismiss dialog (configurable)
+ * @since 1.0.0
+ */
+function DialogOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Overlay>) {
+  return (
+    <DialogPrimitive.Overlay
+      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",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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
+ */
+function DialogContent({
+  className,
+  children,
+  showCloseButton = true,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Content> & {
+  showCloseButton?: boolean;
+}) {
+  return (
+    <DialogPortal data-slot="dialog-portal">
+      <DialogOverlay />
+      <DialogPrimitive.Content
+        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",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+        {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"
+          >
+            <XIcon />
+            <span className="sr-only">Close</span>
+          </DialogPrimitive.Close>
+        )}
+      </DialogPrimitive.Content>
+    </DialogPortal>
+  );
+}
+
+/**
+ * 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
+ */
+function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="dialog-header"
+      className={cn("flex flex-col gap-2 text-center sm:text-left", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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
+ */
+function DialogFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="dialog-footer"
+      className={cn(
+        "flex flex-col-reverse gap-2 sm:flex-row sm:justify-end",
+        className,
+      )}
+      {...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
+ */
+function DialogTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Title>) {
+  return (
+    <DialogPrimitive.Title
+      data-slot="dialog-title"
+      className={cn("text-lg leading-none font-semibold", className)}
+      {...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
+ */
+function DialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Description>) {
+  return (
+    <DialogPrimitive.Description
+      data-slot="dialog-description"
+      className={cn("text-muted-foreground text-sm", className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+};