@neynar/ui 0.1.1

package/src/components/ui/accordion.tsx

@@ -0,0 +1,285 @@
+import * as React from "react";
+import * as AccordionPrimitive from "@radix-ui/react-accordion";
+import { ChevronDownIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Accordion - Collapsible content panels for organizing information
+ *
+ * A vertically stacked set of interactive headings that each reveal a section of content.
+ * Built on Radix UI Accordion primitives with optimized animations and accessibility.
+ * Supports both single and multiple expanded items simultaneously based on the type prop.
+ *
+ * @example
+ * ```tsx
+ * // Basic single accordion (only one item can be open)
+ * <Accordion type="single" collapsible>
+ *   <AccordionItem value="item-1">
+ *     <AccordionTrigger>Is it accessible?</AccordionTrigger>
+ *     <AccordionContent>
+ *       Yes. It adheres to the WAI-ARIA design pattern.
+ *     </AccordionContent>
+ *   </AccordionItem>
+ * </Accordion>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple accordion (multiple items can be open)
+ * <Accordion type="multiple">
+ *   <AccordionItem value="item-1">
+ *     <AccordionTrigger>Section 1</AccordionTrigger>
+ *     <AccordionContent>Content for section 1</AccordionContent>
+ *   </AccordionItem>
+ *   <AccordionItem value="item-2">
+ *     <AccordionTrigger>Section 2</AccordionTrigger>
+ *     <AccordionContent>Content for section 2</AccordionContent>
+ *   </AccordionItem>
+ * </Accordion>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // FAQ-style accordion with default open state
+ * <Accordion type="single" collapsible defaultValue="faq-1">
+ *   <AccordionItem value="faq-1">
+ *     <AccordionTrigger>How do I get started?</AccordionTrigger>
+ *     <AccordionContent>
+ *       Follow our quick start guide to set up your first project.
+ *     </AccordionContent>
+ *   </AccordionItem>
+ * </Accordion>
+ * ```
+ *
+ * @param type - "single" allows one item open, "multiple" allows multiple items open
+ * @param collapsible - When type="single", allows closing the open item (optional)
+ * @param defaultValue - Initial value(s) for open items
+ * @param value - Controlled value(s) for open items
+ * @param onValueChange - Callback when accordion state changes
+ * @param className - Additional CSS classes for styling
+ * @param orientation - "horizontal" or "vertical" (default: "vertical")
+ * @param dir - Text direction "ltr" or "rtl" for internationalization
+ * @param disabled - Disables all accordion interactions
+ *
+ * @accessibility
+ * - Full keyboard navigation support (Arrow keys, Space, Enter, Home, End)
+ * - ARIA expanded/collapsed states automatically managed
+ * - Screen reader announcements for state changes
+ * - Focus management with visible focus indicators
+ * - Properly labeled regions with aria-labelledby
+ * - Meets WCAG 2.1 AA standards for interactive elements
+ *
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/accordion/} WAI-ARIA Accordion Pattern
+ * @see {@link https://ui.shadcn.com/docs/components/accordion} shadcn/ui Accordion Documentation
+ * @see {@link AccordionItem} Individual accordion panel container
+ * @see {@link AccordionTrigger} Clickable header to expand/collapse content
+ * @see {@link AccordionContent} Collapsible content area with smooth animations
+ * @since 1.0.0
+ */
+function Accordion({
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Root>) {
+  return <AccordionPrimitive.Root data-slot="accordion" {...props} />;
+}
+
+/**
+ * AccordionItem - Individual collapsible panel within an accordion
+ *
+ * A container component that wraps a single accordion section consisting of a trigger
+ * and collapsible content. Each item requires a unique value prop for identification
+ * and state management. Provides consistent spacing and border styling.
+ *
+ * @example
+ * ```tsx
+ * <AccordionItem value="settings">
+ *   <AccordionTrigger>Account Settings</AccordionTrigger>
+ *   <AccordionContent>
+ *     <p>Manage your account preferences and security settings.</p>
+ *   </AccordionContent>
+ * </AccordionItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom styling
+ * <AccordionItem value="custom" className="border-l-4 border-blue-500">
+ *   <AccordionTrigger>Custom Styled Item</AccordionTrigger>
+ *   <AccordionContent>Content with custom left border</AccordionContent>
+ * </AccordionItem>
+ * ```
+ *
+ * @param value - Unique identifier for this accordion item (required)
+ * @param className - Additional CSS classes for custom styling
+ * @param disabled - Disables this specific accordion item
+ * @param children - Should contain AccordionTrigger and AccordionContent
+ *
+ * @accessibility
+ * - Manages expanded/collapsed state via ARIA attributes
+ * - Associates trigger with content using aria-controls and aria-labelledby
+ * - Provides proper focus management between items
+ * - Supports keyboard navigation within the accordion group
+ *
+ * @see {@link AccordionTrigger} The clickable header for this item
+ * @see {@link AccordionContent} The collapsible content for this item
+ */
+function AccordionItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Item>) {
+  return (
+    <AccordionPrimitive.Item
+      data-slot="accordion-item"
+      className={cn("border-b last:border-b-0", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * AccordionTrigger - Clickable header that toggles accordion content visibility
+ *
+ * An interactive button element that users click or activate via keyboard to expand
+ * or collapse the associated accordion content. Features a rotating chevron icon
+ * for visual state indication and supports both text and custom content.
+ *
+ * @example
+ * ```tsx
+ * // Simple text trigger
+ * <AccordionTrigger>
+ *   Click to expand this section
+ * </AccordionTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With icon and custom styling
+ * <AccordionTrigger className="text-lg font-semibold">
+ *   <User className="mr-2 h-4 w-4" />
+ *   User Profile Settings
+ * </AccordionTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With complex content
+ * <AccordionTrigger>
+ *   <div className="flex items-center justify-between w-full">
+ *     <span>Section Title</span>
+ *     <Badge variant="secondary">5 items</Badge>
+ *   </div>
+ * </AccordionTrigger>
+ * ```
+ *
+ * @param className - Additional CSS classes for custom styling
+ * @param children - Content to display in the trigger (text, icons, or components)
+ * @param disabled - Disables the trigger interaction
+ * @param asChild - Renders the trigger as its child element when true
+ *
+ * @accessibility
+ * - Keyboard activated with Space, Enter, or Arrow keys
+ * - aria-expanded automatically indicates current expanded/collapsed state
+ * - Focus visible ring for keyboard navigation with proper contrast
+ * - Chevron icon rotation provides visual state feedback
+ * - Screen reader support with proper labeling and state announcements
+ * - Meets WCAG 2.1 AA interactive element requirements
+ *
+ * @see {@link AccordionContent} The content area controlled by this trigger
+ */
+function AccordionTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Trigger>) {
+  return (
+    <AccordionPrimitive.Header className="flex">
+      <AccordionPrimitive.Trigger
+        data-slot="accordion-trigger"
+        className={cn(
+          "focus-visible:border-ring focus-visible:ring-ring/50 flex flex-1 items-start justify-between gap-4 rounded-md py-4 text-left text-sm font-medium transition-all outline-none hover:underline focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 [&[data-state=open]>svg]:rotate-180",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+        <ChevronDownIcon className="text-muted-foreground pointer-events-none size-4 shrink-0 translate-y-0.5 transition-transform duration-200" />
+      </AccordionPrimitive.Trigger>
+    </AccordionPrimitive.Header>
+  );
+}
+
+/**
+ * AccordionContent - Collapsible content area of an accordion item
+ *
+ * The expandable content section that is revealed or hidden when the associated
+ * AccordionTrigger is activated. Features smooth height-based animations using
+ * Tailwind CSS keyframes and supports any React content including complex layouts.
+ *
+ * @example
+ * ```tsx
+ * // Simple text content
+ * <AccordionContent>
+ *   <p>This content is revealed when the accordion is expanded.</p>
+ *   <p>It can contain any React components or HTML elements.</p>
+ * </AccordionContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Rich content with components
+ * <AccordionContent>
+ *   <div className="space-y-4">
+ *     <Alert>
+ *       <InfoIcon className="h-4 w-4" />
+ *       <AlertTitle>Important Note</AlertTitle>
+ *       <AlertDescription>This is highlighted information.</AlertDescription>
+ *     </Alert>
+ *     <Button variant="outline">Take Action</Button>
+ *   </div>
+ * </AccordionContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Content with custom padding
+ * <AccordionContent className="pt-6 pb-6">
+ *   Content with extra vertical padding for better spacing.
+ * </AccordionContent>
+ * ```
+ *
+ * @param className - Additional CSS classes for custom styling (applied to inner div)
+ * @param children - Any React content to display when expanded
+ * @param forceMount - Forces content to remain mounted when collapsed (for animations)
+ *
+ * @accessibility
+ * - Hidden content is not focusable or accessible when collapsed
+ * - Smooth height animations enhance user experience without motion issues
+ * - Properly associated with trigger via ARIA attributes (aria-controls, aria-labelledby)
+ * - Content respects prefers-reduced-motion user preference
+ * - Focus moves naturally to content when expanded via keyboard
+ *
+ * @animation
+ * - Uses data-[state=open]:animate-accordion-down for expand animation
+ * - Uses data-[state=closed]:animate-accordion-up for collapse animation
+ * - Animations respect user's motion preferences
+ * - Smooth height transitions using Radix UI's --radix-accordion-content-height variable
+ *
+ * @see {@link AccordionTrigger} The trigger that controls this content's visibility
+ */
+function AccordionContent({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Content>) {
+  return (
+    <AccordionPrimitive.Content
+      data-slot="accordion-content"
+      className="data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down overflow-hidden text-sm"
+      {...props}
+    >
+      <div className={cn("pt-0 pb-4", className)}>{children}</div>
+    </AccordionPrimitive.Content>
+  );
+}
+
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent };

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

@@ -0,0 +1,387 @@
+import * as React from "react";
+import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog";
+
+import { cn } from "@/lib/utils";
+import { buttonVariants } from "@/components/ui/button";
+
+/**
+ * Alert dialog component for critical confirmations and destructive actions
+ *
+ * A specialized modal dialog built on Radix UI Alert Dialog primitives that interrupts
+ * users with important information requiring immediate acknowledgment or decision.
+ * Unlike regular dialogs, alert dialogs cannot be dismissed by clicking outside and
+ * focus the action button by default for critical decisions.
+ *
+ * Based on the WAI-ARIA Alert Dialog design pattern, this component is specifically
+ * designed for destructive actions, confirmations, or critical warnings that need
+ * immediate attention before the user can continue.
+ *
+ * @example
+ * ```tsx
+ * // Basic destructive confirmation
+ * <AlertDialog>
+ *   <AlertDialogTrigger asChild>
+ *     <Button variant="destructive">Delete Account</Button>
+ *   </AlertDialogTrigger>
+ *   <AlertDialogContent>
+ *     <AlertDialogHeader>
+ *       <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+ *       <AlertDialogDescription>
+ *         This action cannot be undone. This will permanently delete
+ *         your account and remove your data from our servers.
+ *       </AlertDialogDescription>
+ *     </AlertDialogHeader>
+ *     <AlertDialogFooter>
+ *       <AlertDialogCancel>Cancel</AlertDialogCancel>
+ *       <AlertDialogAction>Delete Account</AlertDialogAction>
+ *     </AlertDialogFooter>
+ *   </AlertDialogContent>
+ * </AlertDialog>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Simple confirmation
+ * <AlertDialog>
+ *   <AlertDialogTrigger asChild>
+ *     <Button variant="outline">Sign Out</Button>
+ *   </AlertDialogTrigger>
+ *   <AlertDialogContent>
+ *     <AlertDialogHeader>
+ *       <AlertDialogTitle>Sign Out</AlertDialogTitle>
+ *       <AlertDialogDescription>
+ *         Are you sure you want to sign out of your account?
+ *       </AlertDialogDescription>
+ *     </AlertDialogHeader>
+ *     <AlertDialogFooter>
+ *       <AlertDialogCancel>Cancel</AlertDialogCancel>
+ *       <AlertDialogAction>Sign Out</AlertDialogAction>
+ *     </AlertDialogFooter>
+ *   </AlertDialogContent>
+ * </AlertDialog>
+ * ```
+ *
+ * @accessibility
+ * - Follows WAI-ARIA Alert Dialog design pattern
+ * - Focus is trapped within the dialog when open
+ * - Cannot be dismissed by clicking outside (intentional for alerts)
+ * - Escape key closes the dialog (unless preventDefault is called)
+ * - Proper ARIA roles and attributes for screen readers
+ * - Focus returns to trigger element when closed
+ * - Action button receives initial focus by default
+ * - Supports keyboard navigation between focusable elements
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/alert-dialog} shadcn/ui Alert Dialog docs
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/alert-dialog} Radix UI Alert Dialog
+ * @see {@link Dialog} For general modal content that can be dismissed
+ * @see {@link Sheet} For side panel overlays
+ * @since 1.0.0
+ */
+/**
+ * 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.
+ *
+ * @param props - All props are forwarded to the underlying Radix AlertDialog.Root
+ */
+function AlertDialog({
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Root>) {
+  return <AlertDialogPrimitive.Root data-slot="alert-dialog" {...props} />;
+}
+
+/**
+ * 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.
+ *
+ * @param props - All props are forwarded to the underlying Radix AlertDialog.Trigger
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogTrigger asChild>
+ *   <Button variant="destructive">Delete</Button>
+ * </AlertDialogTrigger>
+ * ```
+ */
+function AlertDialogTrigger({
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Trigger>) {
+  return (
+    <AlertDialogPrimitive.Trigger data-slot="alert-dialog-trigger" {...props} />
+  );
+}
+
+/**
+ * Portal component for rendering dialog outside normal DOM tree
+ *
+ * Renders the alert dialog content into a portal, typically at the end of the document body.
+ * 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
+ */
+function AlertDialogPortal({
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Portal>) {
+  return (
+    <AlertDialogPrimitive.Portal data-slot="alert-dialog-portal" {...props} />
+  );
+}
+
+/**
+ * Overlay backdrop behind the alert dialog
+ *
+ * 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.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All other props are forwarded to the underlying Radix AlertDialog.Overlay
+ */
+function AlertDialogOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Overlay>) {
+  return (
+    <AlertDialogPrimitive.Overlay
+      data-slot="alert-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}
+    />
+  );
+}
+
+/**
+ * Main content container for the alert dialog
+ *
+ * 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.
+ *
+ * @param className - Additional CSS classes to apply to the content container
+ * @param props - All other props are forwarded to the underlying Radix AlertDialog.Content
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogContent>
+ *   <AlertDialogHeader>
+ *     <AlertDialogTitle>Confirm Action</AlertDialogTitle>
+ *     <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+ *   </AlertDialogHeader>
+ *   <AlertDialogFooter>
+ *     <AlertDialogCancel>Cancel</AlertDialogCancel>
+ *     <AlertDialogAction>Continue</AlertDialogAction>
+ *   </AlertDialogFooter>
+ * </AlertDialogContent>
+ * ```
+ */
+function AlertDialogContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Content>) {
+  return (
+    <AlertDialogPortal>
+      <AlertDialogOverlay />
+      <AlertDialogPrimitive.Content
+        data-slot="alert-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}
+      />
+    </AlertDialogPortal>
+  );
+}
+
+/**
+ * Header section of the alert dialog
+ *
+ * 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).
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All other props are forwarded to the underlying div element
+ */
+function AlertDialogHeader({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-dialog-header"
+      className={cn("flex flex-col gap-2 text-center sm:text-left", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Footer section of the alert dialog
+ *
+ * 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).
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All other props are forwarded to the underlying div element
+ */
+function AlertDialogFooter({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-dialog-footer"
+      className={cn(
+        "flex flex-col-reverse gap-2 sm:flex-row sm:justify-end",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All other props are forwarded to the underlying Radix AlertDialog.Title
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+ * <AlertDialogTitle>Delete Account</AlertDialogTitle>
+ * ```
+ */
+function AlertDialogTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Title>) {
+  return (
+    <AlertDialogPrimitive.Title
+      data-slot="alert-dialog-title"
+      className={cn("text-lg font-semibold", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Description text of the alert dialog
+ *
+ * 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.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All other props are forwarded to the underlying Radix AlertDialog.Description
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogDescription>
+ *   This action cannot be undone. This will permanently delete your
+ *   account and remove your data from our servers.
+ * </AlertDialogDescription>
+ * ```
+ */
+function AlertDialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Description>) {
+  return (
+    <AlertDialogPrimitive.Description
+      data-slot="alert-dialog-description"
+      className={cn("text-muted-foreground text-sm", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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.
+ *
+ * @param className - Additional CSS classes to apply (useful for destructive styling)
+ * @param props - All other props are forwarded to the underlying Radix AlertDialog.Action
+ *
+ * @example
+ * ```tsx
+ * // Default action
+ * <AlertDialogAction>Continue</AlertDialogAction>
+ *
+ * // Destructive action
+ * <AlertDialogAction className="bg-red-600 hover:bg-red-700">
+ *   Delete Account
+ * </AlertDialogAction>
+ * ```
+ */
+function AlertDialogAction({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Action>) {
+  return (
+    <AlertDialogPrimitive.Action
+      className={cn(buttonVariants(), className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All other props are forwarded to the underlying Radix AlertDialog.Cancel
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogCancel>Cancel</AlertDialogCancel>
+ * <AlertDialogCancel>No, keep it</AlertDialogCancel>
+ * ```
+ */
+function AlertDialogCancel({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Cancel>) {
+  return (
+    <AlertDialogPrimitive.Cancel
+      className={cn(buttonVariants({ variant: "outline" }), className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  AlertDialog,
+  AlertDialogPortal,
+  AlertDialogOverlay,
+  AlertDialogTrigger,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogFooter,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogAction,
+  AlertDialogCancel,
+};