@neynar/ui 0.2.1 → 0.3.1

package/src/components/ui/button-group.tsx

@@ -0,0 +1,525 @@
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { Separator } from "@/components/ui/separator"
+
+/**
+ * Button group variant configuration using class-variance-authority
+ *
+ * Defines layout orientations and styling for the ButtonGroup container.
+ * Manages button borders, border-radius, and spacing to create seamless
+ * button group appearances where buttons visually connect together.
+ *
+ * @variant horizontal - Buttons arranged side-by-side with connected left/right borders
+ * @variant vertical - Buttons stacked vertically with connected top/bottom borders
+ *
+ * @see {@link https://cva.style/docs} CVA documentation
+ * @see {@link https://ui.shadcn.com/docs/components/button-group} shadcn/ui button-group documentation
+ * @since 1.0.0
+ */
+const buttonGroupVariants = cva(
+  "flex w-fit items-stretch [&>*]:focus-visible:z-10 [&>*]:focus-visible:relative [&>[data-slot=select-trigger]:not([class*='w-'])]:w-fit [&>input]:flex-1 has-[select[aria-hidden=true]:last-child]:[&>[data-slot=select-trigger]:last-of-type]:rounded-r-md has-[>[data-slot=button-group]]:gap-2",
+  {
+    variants: {
+      orientation: {
+        horizontal:
+          "[&>*:not(:first-child)]:rounded-l-none [&>*:not(:first-child)]:border-l-0 [&>*:not(:last-child)]:rounded-r-none",
+        vertical:
+          "flex-col [&>*:not(:first-child)]:rounded-t-none [&>*:not(:first-child)]:border-t-0 [&>*:not(:last-child)]:rounded-b-none",
+      },
+    },
+    defaultVariants: {
+      orientation: "horizontal",
+    },
+  }
+)
+
+/**
+ * Props for ButtonGroup component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CVA inferred types
+ */
+type ButtonGroupDocsProps = {
+  /**
+   * Layout orientation of the button group
+   *
+   * - "horizontal": Buttons arranged side-by-side with connected borders (default)
+   * - "vertical": Buttons stacked vertically with connected borders
+   *
+   * @default "horizontal"
+   */
+  orientation?: "horizontal" | "vertical"
+  /** Additional CSS classes to apply to the button group container */
+  className?: string
+  /** Button components to group together (typically Button components) */
+  children?: React.ReactNode
+  /** Accessible label describing the button group's purpose (recommended for screen readers) */
+  "aria-label"?: string
+  /** ID of element that labels this button group */
+  "aria-labelledby"?: string
+  /** ID of element that describes this button group */
+  "aria-describedby"?: string
+} & React.HTMLAttributes<HTMLDivElement>
+
+/**
+ * Props for ButtonGroupText component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+type ButtonGroupTextDocsProps = {
+  /**
+   * Render as a different element instead of a div
+   *
+   * When true, renders the text container as its child element via Radix UI Slot.
+   * Useful for semantic HTML or custom component composition.
+   *
+   * @default false
+   */
+  asChild?: boolean
+  /** Additional CSS classes to apply to the text container */
+  className?: string
+  /** Text content or React nodes to display in the group */
+  children?: React.ReactNode
+} & React.HTMLAttributes<HTMLDivElement>
+
+/**
+ * Props for ButtonGroupSeparator component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Separator inferred types
+ */
+type ButtonGroupSeparatorDocsProps = {
+  /**
+   * Orientation of the separator line
+   *
+   * - "vertical": Vertical separator for horizontal button groups (default)
+   * - "horizontal": Horizontal separator for vertical button groups
+   *
+   * Note: Typically use vertical separators in horizontal groups and horizontal separators in vertical groups
+   *
+   * @default "vertical"
+   */
+  orientation?: "horizontal" | "vertical"
+  /** Additional CSS classes to apply to the separator */
+  className?: string
+  /**
+   * Whether the separator is purely decorative
+   *
+   * When true, separator is hidden from assistive technologies
+   *
+   * @default true
+   */
+  decorative?: boolean
+} & React.ComponentProps<typeof Separator>
+
+/**
+ * ButtonGroup - Container for grouping related buttons with consistent styling
+ *
+ * A flexible container component that groups related action buttons together with seamless
+ * visual connection. Built for toolbars, pagination controls, action menus, and navigation
+ * interfaces. Supports both horizontal and vertical layouts with intelligent border and
+ * border-radius management to create cohesive button groups.
+ *
+ * The component automatically handles:
+ * - Border collapsing between adjacent buttons for seamless appearance
+ * - Focus state z-index management to ensure proper focus ring visibility
+ * - Integration with Button, Input, and Select components
+ * - Nested button group support for complex layouts
+ * - Responsive sizing that adapts to button content
+ *
+ * @example
+ * ```tsx
+ * // Basic horizontal button group (most common usage)
+ * import { Button, ButtonGroup } from "@neynar/ui"
+ *
+ * <ButtonGroup>
+ *   <Button variant="outline">Copy</Button>
+ *   <Button variant="outline">Paste</Button>
+ *   <Button variant="outline">Cut</Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Vertical button group for navigation menus
+ * import { Button, ButtonGroup } from "@neynar/ui"
+ *
+ * <ButtonGroup orientation="vertical" aria-label="Navigation menu">
+ *   <Button variant="outline" className="justify-start">Dashboard</Button>
+ *   <Button variant="outline" className="justify-start">Projects</Button>
+ *   <Button variant="outline" className="justify-start">Team</Button>
+ *   <Button variant="outline" className="justify-start">Settings</Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Button group with icons and separators
+ * import { Copy, Download, Share2 } from "lucide-react"
+ * import { Button, ButtonGroup, ButtonGroupSeparator } from "@neynar/ui"
+ *
+ * <ButtonGroup aria-label="Content actions">
+ *   <Button variant="outline">
+ *     <Copy className="size-4" />
+ *     Copy
+ *   </Button>
+ *   <ButtonGroupSeparator />
+ *   <Button variant="outline">
+ *     <Download className="size-4" />
+ *     Download
+ *   </Button>
+ *   <ButtonGroupSeparator />
+ *   <Button variant="outline">
+ *     <Share2 className="size-4" />
+ *     Share
+ *   </Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Pagination controls with text element
+ * import { Button, ButtonGroup, ButtonGroupText } from "@neynar/ui"
+ *
+ * <ButtonGroup aria-label="Pagination controls">
+ *   <Button variant="outline" disabled={currentPage === 1}>
+ *     Previous
+ *   </Button>
+ *   <ButtonGroupText>Page {currentPage} of {totalPages}</ButtonGroupText>
+ *   <Button variant="outline" disabled={currentPage === totalPages}>
+ *     Next
+ *   </Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Toolbar with multiple grouped sections
+ * import { Button, ButtonGroup, ButtonGroupSeparator } from "@neynar/ui"
+ *
+ * <div className="flex gap-2" role="toolbar" aria-label="Editor toolbar">
+ *   <ButtonGroup>
+ *     <Button variant="outline" size="sm">Bold</Button>
+ *     <Button variant="outline" size="sm">Italic</Button>
+ *     <Button variant="outline" size="sm">Underline</Button>
+ *   </ButtonGroup>
+ *
+ *   <ButtonGroupSeparator orientation="vertical" className="h-8" />
+ *
+ *   <ButtonGroup>
+ *     <Button variant="outline" size="sm">Left</Button>
+ *     <Button variant="outline" size="sm">Center</Button>
+ *     <Button variant="outline" size="sm">Right</Button>
+ *   </ButtonGroup>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Different button sizes in groups
+ * import { Button, ButtonGroup } from "@neynar/ui"
+ *
+ * // Small buttons for compact interfaces
+ * <ButtonGroup>
+ *   <Button variant="outline" size="sm">Small</Button>
+ *   <Button variant="outline" size="sm">Size</Button>
+ *   <Button variant="outline" size="sm">Buttons</Button>
+ * </ButtonGroup>
+ *
+ * // Large buttons for prominent actions
+ * <ButtonGroup>
+ *   <Button variant="outline" size="lg">Large</Button>
+ *   <Button variant="outline" size="lg">Size</Button>
+ *   <Button variant="outline" size="lg">Buttons</Button>
+ * </ButtonGroup>
+ *
+ * // Icon buttons in group
+ * <ButtonGroup>
+ *   <Button variant="outline" size="icon" aria-label="Bold">
+ *     <Bold className="size-4" />
+ *   </Button>
+ *   <Button variant="outline" size="icon" aria-label="Italic">
+ *     <Italic className="size-4" />
+ *   </Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @accessibility
+ * - Container has role="group" for semantic grouping
+ * - Use Tab key to navigate between buttons in the group
+ * - Each button maintains full keyboard support (Enter/Space activation)
+ * - Focus states properly layered with z-index management
+ * - Add aria-label to describe the button group's purpose
+ * - Icon-only buttons in groups require individual aria-label attributes
+ * - Use ButtonGroupText for informative text that shouldn't be actionable
+ * - For toolbar layouts, wrap ButtonGroup in element with role="toolbar"
+ * - When used for navigation, consider aria-label="Navigation menu"
+ *
+ * @variant horizontal - Buttons arranged side-by-side with connected left/right borders
+ * @variant vertical - Buttons stacked vertically with connected top/bottom borders
+ *
+ * @see {@link Button} Base button component used within groups
+ * @see {@link ButtonGroupSeparator} Visual separator between grouped buttons
+ * @see {@link ButtonGroupText} Text element for labels and info within groups
+ * @see {@link https://ui.shadcn.com/docs/components/button-group} shadcn/ui button-group documentation
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/} WAI-ARIA Toolbar Pattern
+ * @since 1.0.0
+ */
+function ButtonGroup({
+  className,
+  orientation,
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof buttonGroupVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="button-group"
+      data-orientation={orientation}
+      className={cn(buttonGroupVariants({ orientation }), className)}
+      {...props}
+    />
+  )
+}
+
+/**
+ * ButtonGroupText - Text display element for labels and information within button groups
+ *
+ * A styled text container designed to display non-interactive content within button groups,
+ * such as labels, pagination information, or contextual text. Maintains visual consistency
+ * with grouped buttons through matching height, border, and styling while being clearly
+ * non-interactive with a muted background.
+ *
+ * Common use cases:
+ * - Pagination counters ("Page 1 of 10")
+ * - Section labels ("Actions:", "Tools:")
+ * - Status indicators or counts
+ * - Contextual information between action buttons
+ *
+ * The component automatically:
+ * - Matches button group styling with appropriate borders and spacing
+ * - Sizes icons consistently at 16px (size-4)
+ * - Maintains visual hierarchy with muted background
+ * - Prevents pointer events on icons to avoid interaction confusion
+ *
+ * @example
+ * ```tsx
+ * // Pagination with page count display
+ * import { Button, ButtonGroup, ButtonGroupText } from "@neynar/ui"
+ *
+ * <ButtonGroup aria-label="Pagination">
+ *   <Button variant="outline" onClick={goToPrevious}>
+ *     Previous
+ *   </Button>
+ *   <ButtonGroupText>
+ *     Page {currentPage} of {totalPages}
+ *   </ButtonGroupText>
+ *   <Button variant="outline" onClick={goToNext}>
+ *     Next
+ *   </Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Section label with action buttons
+ * import { Copy, Download } from "lucide-react"
+ * import { Button, ButtonGroup, ButtonGroupText, ButtonGroupSeparator } from "@neynar/ui"
+ *
+ * <ButtonGroup>
+ *   <ButtonGroupText>Actions:</ButtonGroupText>
+ *   <ButtonGroupSeparator />
+ *   <Button variant="outline">
+ *     <Copy className="size-4" />
+ *     Copy
+ *   </Button>
+ *   <Button variant="outline">
+ *     <Download className="size-4" />
+ *     Download
+ *   </Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Status indicator with icon
+ * import { CheckCircle2 } from "lucide-react"
+ * import { ButtonGroup, ButtonGroupText } from "@neynar/ui"
+ *
+ * <ButtonGroup>
+ *   <ButtonGroupText>
+ *     <CheckCircle2 className="text-green-500" />
+ *     3 items selected
+ *   </ButtonGroupText>
+ *   <Button variant="outline" onClick={clearSelection}>
+ *     Clear
+ *   </Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom composition with asChild
+ * import { ButtonGroup, ButtonGroupText } from "@neynar/ui"
+ *
+ * <ButtonGroup>
+ *   <Button variant="outline">Action 1</Button>
+ *   <ButtonGroupText asChild>
+ *     <span role="status" aria-live="polite">
+ *       Processing: {progress}%
+ *     </span>
+ *   </ButtonGroupText>
+ *   <Button variant="outline">Action 2</Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @accessibility
+ * - Not focusable or interactive (use Button for clickable elements)
+ * - Text content automatically accessible to screen readers
+ * - Use semantic HTML with asChild for status indicators (role="status", aria-live)
+ * - Icons are decorative by default (pointer-events-none)
+ * - Maintains sufficient color contrast in muted background
+ * - For dynamic content like pagination, consider aria-live regions
+ *
+ * @see {@link ButtonGroup} Parent container for button groups
+ * @see {@link ButtonGroupSeparator} Visual divider between group elements
+ * @see {@link Button} Interactive button component for actions
+ * @see {@link https://ui.shadcn.com/docs/components/button-group} shadcn/ui button-group documentation
+ * @since 1.0.0
+ */
+function ButtonGroupText({
+  className,
+  asChild = false,
+  ...props
+}: React.ComponentProps<"div"> & {
+  asChild?: boolean
+}) {
+  const Comp = asChild ? Slot : "div"
+
+  return (
+    <Comp
+      className={cn(
+        "bg-muted flex items-center gap-2 rounded-md border px-4 text-sm font-medium shadow-xs [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+/**
+ * ButtonGroupSeparator - Visual divider for buttons within a button group
+ *
+ * A specialized separator component that creates visual divisions between buttons or elements
+ * within a ButtonGroup. Built on the Separator primitive with automatic sizing and styling
+ * to match button group layouts. The separator orientation typically matches the button group
+ * orientation (vertical separators in horizontal groups, horizontal separators in vertical groups).
+ *
+ * Key behaviors:
+ * - Self-stretches to match parent height/width automatically
+ * - Uses input border color for subtle visual division
+ * - Removes margins for seamless integration
+ * - Decorative by default (hidden from screen readers)
+ *
+ * Note: Separators are typically unnecessary for outline variant buttons since they
+ * already have visible borders. Use separators with ghost, default, or other variants
+ * where the visual separation is needed.
+ *
+ * @example
+ * ```tsx
+ * // Horizontal button group with vertical separators
+ * import { Button, ButtonGroup, ButtonGroupSeparator } from "@neynar/ui"
+ *
+ * <ButtonGroup>
+ *   <Button variant="outline">Copy</Button>
+ *   <ButtonGroupSeparator />
+ *   <Button variant="outline">Paste</Button>
+ *   <ButtonGroupSeparator />
+ *   <Button variant="outline">Cut</Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Vertical button group with horizontal separators
+ * import { Button, ButtonGroup, ButtonGroupSeparator } from "@neynar/ui"
+ *
+ * <ButtonGroup orientation="vertical">
+ *   <Button variant="outline">Item 1</Button>
+ *   <ButtonGroupSeparator orientation="horizontal" />
+ *   <Button variant="outline">Item 2</Button>
+ *   <ButtonGroupSeparator orientation="horizontal" />
+ *   <Button variant="outline">Item 3</Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Separating button group sections in toolbar
+ * import { Button, ButtonGroup, ButtonGroupSeparator } from "@neynar/ui"
+ *
+ * <div className="flex gap-2" role="toolbar">
+ *   <ButtonGroup>
+ *     <Button variant="outline" size="sm">Bold</Button>
+ *     <Button variant="outline" size="sm">Italic</Button>
+ *   </ButtonGroup>
+ *
+ *   <ButtonGroupSeparator orientation="vertical" className="h-8" />
+ *
+ *   <ButtonGroup>
+ *     <Button variant="outline" size="sm">Left</Button>
+ *     <Button variant="outline" size="sm">Center</Button>
+ *     <Button variant="outline" size="sm">Right</Button>
+ *   </ButtonGroup>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Separator with custom height for specific layouts
+ * import { Button, ButtonGroup, ButtonGroupSeparator } from "@neynar/ui"
+ *
+ * <ButtonGroup>
+ *   <Button variant="ghost">Action 1</Button>
+ *   <ButtonGroupSeparator className="h-6" />
+ *   <Button variant="ghost">Action 2</Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @accessibility
+ * - Purely decorative by default (hidden from assistive technologies)
+ * - Does not receive keyboard focus
+ * - Provides visual separation only
+ * - No ARIA attributes needed for typical button group usage
+ * - Screen reader users navigate between buttons using Tab key
+ *
+ * @see {@link ButtonGroup} Parent container for button groups
+ * @see {@link ButtonGroupText} Text display element within groups
+ * @see {@link Separator} Base separator primitive component
+ * @see {@link https://ui.shadcn.com/docs/components/button-group} shadcn/ui button-group documentation
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/separator} Radix UI Separator primitive
+ * @since 1.0.0
+ */
+function ButtonGroupSeparator({
+  className,
+  orientation = "vertical",
+  ...props
+}: React.ComponentProps<typeof Separator>) {
+  return (
+    <Separator
+      data-slot="button-group-separator"
+      orientation={orientation}
+      className={cn(
+        "bg-input relative !m-0 self-stretch data-[orientation=vertical]:h-auto",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  ButtonGroup,
+  ButtonGroupSeparator,
+  ButtonGroupText,
+  buttonGroupVariants,
+  type ButtonGroupDocsProps,
+  type ButtonGroupSeparatorDocsProps,
+  type ButtonGroupTextDocsProps,
+}

package/src/components/ui/button.tsx

@@ -32,16 +32,13 @@ const buttonVariants = cva(
   {
     variants: {
       variant: {
-        default:
-          "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
         destructive:
-          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
-        outline:
-          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
+          "bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
+        outline: "border border-border hover:bg-card",
         secondary:
-          "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",
-        ghost:
-          "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
+          "bg-secondary/80 text-secondary-foreground hover:bg-secondary",
+        ghost: "hover:bg-card",
         link: "text-primary underline-offset-4 hover:underline",
       },
       size: {
@@ -114,7 +111,7 @@ type ButtonDocsProps = {
   /** Indicates invalid state for form validation */
   "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling";
   /** Indicates expanded state for disclosure buttons */
-  "aria-expanded"?: React.AriaAttributes['aria-expanded'];
+  "aria-expanded"?: React.AriaAttributes["aria-expanded"];
   /** Associates button with elements it controls */
   "aria-controls"?: string;
   /** Indicates pressed state for toggle buttons */
@@ -140,9 +137,9 @@ type ButtonDocsProps = {
   /** Button value for form submission */
   value?: string | ReadonlyArray<string> | number;
 } & React.ButtonHTMLAttributes<HTMLButtonElement> & {
-  /** Ref to access the button element */
-  ref?: React.Ref<HTMLButtonElement>;
-};
+    /** Ref to access the button element */
+    ref?: React.Ref<HTMLButtonElement>;
+  };
 
 /**
  * Button - A versatile, accessible button component with multiple style variants

package/src/components/ui/empty-state.tsx

@@ -267,6 +267,7 @@ type EmptyStateDocsProps = {
  * @see {@link https://ui.patterns.build/empty-states} Empty state design patterns
  * @see {@link https://www.nngroup.com/articles/empty-state-interface-design/} Nielsen Norman Group empty state guidelines
  * @since 1.0.0
+ * @deprecated Use @neynar/ui Empty component instead
  */
 const EmptyState = React.forwardRef<
   HTMLDivElement,