@neynar/ui 0.1.1

package/src/components/ui/progress.tsx

@@ -0,0 +1,88 @@
+import * as React from "react";
+import * as ProgressPrimitive from "@radix-ui/react-progress";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Progress component displays completion progress of tasks and operations
+ *
+ * A visual progress indicator built on Radix UI primitives that shows the
+ * completion state of tasks, file uploads, multi-step processes, and other
+ * operations requiring user feedback about progress status.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Progress value={60} />
+ * ```
+ *
+ * @example With label and percentage
+ * ```tsx
+ * <div className="space-y-2">
+ *   <div className="flex justify-between text-sm">
+ *     <span>Loading data...</span>
+ *     <span>{progress}%</span>
+ *   </div>
+ *   <Progress value={progress} />
+ * </div>
+ * ```
+ *
+ * @example File upload progress
+ * ```tsx
+ * <div className="space-y-2">
+ *   <Progress value={uploadProgress} />
+ *   <p className="text-sm text-muted-foreground">
+ *     {uploadProgress}% of 2.4 MB uploaded
+ *   </p>
+ * </div>
+ * ```
+ *
+ * @example Custom height and colors
+ * ```tsx
+ * <Progress
+ *   value={85}
+ *   className="h-4 [&>div]:bg-green-500"
+ * />
+ * ```
+ *
+ * @example Multi-step process
+ * ```tsx
+ * const stepProgress = (currentStep / totalSteps) * 100;
+ * <Progress value={stepProgress} />
+ * ```
+ *
+ * @param value - Progress value from 0 to 100. Undefined shows no progress.
+ * @param className - Additional CSS classes for styling customization
+ *
+ * @accessibility
+ * - Built on Radix UI Progress primitive with proper ARIA attributes
+ * - Announces progress changes to screen readers
+ * - Supports custom aria-label and aria-valuetext for enhanced descriptions
+ * - Smooth visual transitions provide clear feedback
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/progress} for design patterns
+ * @since 1.0.0
+ */
+function Progress({
+  className,
+  value,
+  ...props
+}: React.ComponentProps<typeof ProgressPrimitive.Root>) {
+  return (
+    <ProgressPrimitive.Root
+      data-slot="progress"
+      className={cn(
+        "bg-primary/20 relative h-2 w-full overflow-hidden rounded-full",
+        className,
+      )}
+      {...props}
+    >
+      <ProgressPrimitive.Indicator
+        data-slot="progress-indicator"
+        className="bg-primary h-full w-full flex-1 transition-all"
+        style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
+      />
+    </ProgressPrimitive.Root>
+  );
+}
+
+export { Progress };

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

@@ -0,0 +1,183 @@
+"use client";
+
+import * as React from "react";
+import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
+import { CircleIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * A radio group component for single selection from multiple options
+ *
+ * RadioGroup allows users to select exactly one option from a set of mutually exclusive choices.
+ * Built on Radix UI primitives with custom styling that follows shadcn/ui design patterns.
+ * Each radio group should contain RadioGroupItem components paired with Labels for accessibility.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <RadioGroup defaultValue="option-one">
+ *   <div className="flex items-center space-x-2">
+ *     <RadioGroupItem value="option-one" id="option-one" />
+ *     <Label htmlFor="option-one">Option One</Label>
+ *   </div>
+ *   <div className="flex items-center space-x-2">
+ *     <RadioGroupItem value="option-two" id="option-two" />
+ *     <Label htmlFor="option-two">Option Two</Label>
+ *   </div>
+ * </RadioGroup>
+ * ```
+ *
+ * @example Controlled radio group
+ * ```tsx
+ * function SizeSelector() {
+ *   const [size, setSize] = useState("medium");
+ *
+ *   return (
+ *     <RadioGroup value={size} onValueChange={setSize}>
+ *       <div className="flex items-center space-x-2">
+ *         <RadioGroupItem value="small" id="size-small" />
+ *         <Label htmlFor="size-small">Small</Label>
+ *       </div>
+ *       <div className="flex items-center space-x-2">
+ *         <RadioGroupItem value="medium" id="size-medium" />
+ *         <Label htmlFor="size-medium">Medium</Label>
+ *       </div>
+ *       <div className="flex items-center space-x-2">
+ *         <RadioGroupItem value="large" id="size-large" />
+ *         <Label htmlFor="size-large">Large</Label>
+ *       </div>
+ *     </RadioGroup>
+ *   );
+ * }
+ * ```
+ *
+ * @example Horizontal layout
+ * ```tsx
+ * <RadioGroup defaultValue="option-one" className="flex gap-4">
+ *   <div className="flex items-center space-x-2">
+ *     <RadioGroupItem value="option-one" id="r1" />
+ *     <Label htmlFor="r1">Option One</Label>
+ *   </div>
+ *   <div className="flex items-center space-x-2">
+ *     <RadioGroupItem value="option-two" id="r2" />
+ *     <Label htmlFor="r2">Option Two</Label>
+ *   </div>
+ * </RadioGroup>
+ * ```
+ *
+ * @example With descriptions
+ * ```tsx
+ * <RadioGroup defaultValue="card">
+ *   <div className="flex items-start space-x-2">
+ *     <RadioGroupItem value="card" id="card" className="mt-1" />
+ *     <div className="grid gap-1">
+ *       <Label htmlFor="card">Credit Card</Label>
+ *       <p className="text-sm text-muted-foreground">
+ *         Pay with your credit or debit card
+ *       </p>
+ *     </div>
+ *   </div>
+ * </RadioGroup>
+ * ```
+ *
+ * @param defaultValue - The default selected value when uncontrolled
+ * @param value - The controlled value of the radio group
+ * @param onValueChange - Callback fired when the value changes
+ * @param disabled - Whether the entire radio group is disabled
+ * @param required - Whether the radio group is required for form validation
+ * @param orientation - The orientation of the radio group (defaults to vertical)
+ * @param className - Additional CSS classes to apply to the radio group
+ * @param children - RadioGroupItem components and their associated labels
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/radio-group} for design patterns
+ * @since 1.0.0
+ * @see {@link RadioGroupItem} for individual radio options
+ * @see {@link Checkbox} for multiple selection use cases
+ * @see {@link Select} for dropdown-style single selection
+ */
+function RadioGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof RadioGroupPrimitive.Root>) {
+  return (
+    <RadioGroupPrimitive.Root
+      data-slot="radio-group"
+      className={cn("grid gap-3", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Individual radio button item for use within RadioGroup
+ *
+ * RadioGroupItem represents a single selectable option in a radio group.
+ * Must be used within a RadioGroup component and paired with a Label for accessibility.
+ * The component automatically handles visual states including checked, unchecked, focused, and disabled.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <RadioGroupItem value="option-one" id="option-one" />
+ * <Label htmlFor="option-one">Option One</Label>
+ * ```
+ *
+ * @example With custom styling
+ * ```tsx
+ * <RadioGroupItem
+ *   value="premium"
+ *   id="premium"
+ *   className="border-purple-500 text-purple-500"
+ * />
+ * <Label htmlFor="premium">Premium Plan</Label>
+ * ```
+ *
+ * @example Disabled state
+ * ```tsx
+ * <RadioGroupItem value="unavailable" id="unavailable" disabled />
+ * <Label htmlFor="unavailable" className="opacity-50">
+ *   Unavailable Option
+ * </Label>
+ * ```
+ *
+ * @param value - The unique value for this radio option
+ * @param id - The id attribute for accessibility (should match Label's htmlFor)
+ * @param disabled - Whether this specific radio option is disabled
+ * @param className - Additional CSS classes for custom styling
+ * @param ref - React ref forwarded to the underlying input element
+ *
+ * @accessibility
+ * - Automatically receives focus management from parent RadioGroup
+ * - Arrow keys navigate between radio options
+ * - Space key toggles selection
+ * - Screen readers announce checked/unchecked state
+ * - Focus visible indicator for keyboard navigation
+ * - Proper ARIA attributes and roles
+ *
+ * @see {@link RadioGroup} for the parent container component
+ * @see {@link https://ui.shadcn.com/docs/components/radio-group} for usage patterns
+ * @since 1.0.0
+ */
+function RadioGroupItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof RadioGroupPrimitive.Item>) {
+  return (
+    <RadioGroupPrimitive.Item
+      data-slot="radio-group-item"
+      className={cn(
+        "border-input text-primary focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 aspect-square size-4 shrink-0 rounded-full border shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50",
+        className,
+      )}
+      {...props}
+    >
+      <RadioGroupPrimitive.Indicator
+        data-slot="radio-group-indicator"
+        className="relative flex items-center justify-center"
+      >
+        <CircleIcon className="fill-primary absolute top-1/2 left-1/2 size-2 -translate-x-1/2 -translate-y-1/2" />
+      </RadioGroupPrimitive.Indicator>
+    </RadioGroupPrimitive.Item>
+  );
+}
+
+export { RadioGroup, RadioGroupItem };

package/src/components/ui/resizable.tsx

@@ -0,0 +1,209 @@
+import * as React from "react";
+import { GripVerticalIcon } from "lucide-react";
+import * as ResizablePrimitive from "react-resizable-panels";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Container for creating resizable panel groups with keyboard accessibility
+ *
+ * ResizablePanelGroup provides a flexible container for organizing multiple resizable panels.
+ * Panels can be resized by dragging handles between them, with full keyboard support.
+ * Built on top of react-resizable-panels with enhanced styling and accessibility features.
+ *
+ * @example
+ * ```tsx
+ * // Basic horizontal layout
+ * <ResizablePanelGroup direction="horizontal" className="h-full">
+ *   <ResizablePanel defaultSize={50}>
+ *     <div className="p-4">Left panel</div>
+ *   </ResizablePanel>
+ *   <ResizableHandle />
+ *   <ResizablePanel defaultSize={50}>
+ *     <div className="p-4">Right panel</div>
+ *   </ResizablePanel>
+ * </ResizablePanelGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Vertical layout with handle
+ * <ResizablePanelGroup direction="vertical" className="min-h-[400px]">
+ *   <ResizablePanel defaultSize={30}>
+ *     <header>Header content</header>
+ *   </ResizablePanel>
+ *   <ResizableHandle withHandle />
+ *   <ResizablePanel defaultSize={70}>
+ *     <main>Main content</main>
+ *   </ResizablePanel>
+ * </ResizablePanelGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex layout with size constraints
+ * <ResizablePanelGroup direction="horizontal">
+ *   <ResizablePanel defaultSize={25} minSize={20} maxSize={40}>
+ *     <nav>Sidebar (20-40%)</nav>
+ *   </ResizablePanel>
+ *   <ResizableHandle withHandle />
+ *   <ResizablePanel defaultSize={75} minSize={60}>
+ *     <main>Content (min 60%)</main>
+ *   </ResizablePanel>
+ * </ResizablePanelGroup>
+ * ```
+ *
+ * @param direction - Layout direction: "horizontal" or "vertical"
+ * @param className - Additional CSS classes
+ * @param children - ResizablePanel and ResizableHandle components
+ *
+ * @accessibility
+ * - Full keyboard navigation with arrow keys when handles are focused
+ * - Screen reader support with proper ARIA labels
+ * - Respects prefers-reduced-motion for users with motion sensitivity
+ * - Maintains focus management during resize operations
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/resizable} for design patterns
+ * @since 1.0.0
+ * @see {@link ResizablePanel} for individual panel configuration
+ * @see {@link ResizableHandle} for handle customization options
+ */
+function ResizablePanelGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof ResizablePrimitive.PanelGroup>) {
+  return (
+    <ResizablePrimitive.PanelGroup
+      data-slot="resizable-panel-group"
+      className={cn(
+        "flex h-full w-full data-[panel-group-direction=vertical]:flex-col",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Individual resizable panel within a panel group
+ *
+ * ResizablePanel represents a single section that can be resized within a ResizablePanelGroup.
+ * Supports size constraints, default sizing, and programmatic control. Each panel automatically
+ * handles overflow and maintains content accessibility during resize operations.
+ *
+ * @example
+ * ```tsx
+ * // Basic panel with default size
+ * <ResizablePanel defaultSize={50}>
+ *   <div className="p-4">Panel content</div>
+ * </ResizablePanel>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Panel with size constraints
+ * <ResizablePanel
+ *   defaultSize={30}
+ *   minSize={20}
+ *   maxSize={60}
+ *   collapsible
+ * >
+ *   <aside>Collapsible sidebar</aside>
+ * </ResizablePanel>
+ * ```
+ *
+ * @param defaultSize - Initial size as percentage (0-100)
+ * @param minSize - Minimum size as percentage
+ * @param maxSize - Maximum size as percentage
+ * @param collapsible - Whether panel can be collapsed to zero size
+ * @param order - Display order within the group
+ * @param id - Unique identifier for programmatic control
+ * @param onCollapse - Callback when panel is collapsed
+ * @param onExpand - Callback when panel is expanded
+ * @param onResize - Callback when panel size changes
+ *
+ * @accessibility
+ * - Maintains focus within panel during resize
+ * - Preserves scroll position when possible
+ * - Announces size changes to screen readers when significant
+ */
+function ResizablePanel({
+  ...props
+}: React.ComponentProps<typeof ResizablePrimitive.Panel>) {
+  return <ResizablePrimitive.Panel data-slot="resizable-panel" {...props} />;
+}
+
+/**
+ * Draggable handle for resizing panels with optional visual indicator
+ *
+ * ResizableHandle provides the interactive area between panels that allows users to
+ * resize them via mouse, touch, or keyboard. The handle can display an optional
+ * visual grip indicator for improved usability and accessibility.
+ *
+ * @example
+ * ```tsx
+ * // Basic invisible handle
+ * <ResizableHandle />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Handle with visual grip indicator
+ * <ResizableHandle withHandle />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styled handle
+ * <ResizableHandle
+ *   withHandle
+ *   className="bg-blue-200 hover:bg-blue-300"
+ * />
+ * ```
+ *
+ * @param withHandle - Whether to display visual grip indicator
+ * @param className - Additional CSS classes for styling
+ * @param disabled - Whether the handle is disabled
+ * @param hitAreaMargins - Margins around the hit area for easier interaction
+ * @param onDragging - Callback during drag operations
+ *
+ * @accessibility
+ * - Keyboard resizable using arrow keys when focused
+ * - Proper ARIA roles and labels for screen readers
+ * - Focus indicators that meet WCAG contrast requirements
+ * - Touch-friendly hit area of at least 44x44px
+ * - Announces resize actions and current sizes to assistive technology
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/resizable} for usage examples
+ * @since 1.0.0
+ */
+function ResizableHandle({
+  withHandle,
+  className,
+  ...props
+}: React.ComponentProps<typeof ResizablePrimitive.PanelResizeHandle> & {
+  /**
+   * Whether to show a visual grip handle
+   * @default false
+   */
+  withHandle?: boolean;
+}) {
+  return (
+    <ResizablePrimitive.PanelResizeHandle
+      data-slot="resizable-handle"
+      className={cn(
+        "bg-border focus-visible:ring-ring relative flex w-px items-center justify-center after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-visible:ring-1 focus-visible:ring-offset-1 focus-visible:outline-hidden data-[panel-group-direction=vertical]:h-px data-[panel-group-direction=vertical]:w-full data-[panel-group-direction=vertical]:after:left-0 data-[panel-group-direction=vertical]:after:h-1 data-[panel-group-direction=vertical]:after:w-full data-[panel-group-direction=vertical]:after:translate-x-0 data-[panel-group-direction=vertical]:after:-translate-y-1/2 [&[data-panel-group-direction=vertical]>div]:rotate-90",
+        className,
+      )}
+      {...props}
+    >
+      {withHandle && (
+        <div className="bg-border z-10 flex h-4 w-3 items-center justify-center rounded-xs border">
+          <GripVerticalIcon className="size-2.5" />
+        </div>
+      )}
+    </ResizablePrimitive.PanelResizeHandle>
+  );
+}
+
+export { ResizablePanelGroup, ResizablePanel, ResizableHandle };

package/src/components/ui/scroll-area.tsx

@@ -0,0 +1,132 @@
+import * as React from "react";
+import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * ScrollArea component provides cross-browser custom scrollbar styling
+ *
+ * Augments native scroll functionality for custom, cross-browser styling with enhanced
+ * scrolling experience. Built on Radix UI's ScrollArea primitive for accessibility
+ * and keyboard navigation support. Provides consistent scrollbar appearance across
+ * different browsers while maintaining native scroll behavior.
+ *
+ * @example
+ * ```tsx
+ * // Basic vertical scrollable area
+ * <ScrollArea className="h-72 w-48 rounded-md border">
+ *   <div className="p-4">
+ *     {items.map((item) => (
+ *       <div key={item.id} className="mb-4">
+ *         {item.content}
+ *       </div>
+ *     ))}
+ *   </div>
+ * </ScrollArea>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Horizontal scrolling with custom scrollbar
+ * <ScrollArea className="w-full whitespace-nowrap rounded-md border">
+ *   <div className="flex gap-4 p-4">
+ *     {cards.map((card) => (
+ *       <div key={card.id} className="w-64 flex-none">
+ *         {card.content}
+ *       </div>
+ *     ))}
+ *   </div>
+ *   <ScrollBar orientation="horizontal" />
+ * </ScrollArea>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Both scrollbars for large content
+ * <ScrollArea className="h-96 w-80 rounded-md border">
+ *   <div className="w-[600px] p-4">
+ *     // Wide content with vertical overflow
+ *   </div>
+ *   <ScrollBar orientation="horizontal" />
+ * </ScrollArea>
+ * ```
+ *
+ * @param className - Additional CSS classes for styling
+ * @param children - Content to be rendered inside the scrollable area
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/scroll-area} - shadcn/ui ScrollArea documentation
+ * @since 1.0.0
+ * @see {@link ScrollBar} - Companion scrollbar component for horizontal scrolling
+ */
+function ScrollArea({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof ScrollAreaPrimitive.Root>) {
+  return (
+    <ScrollAreaPrimitive.Root
+      data-slot="scroll-area"
+      className={cn("relative", className)}
+      {...props}
+    >
+      <ScrollAreaPrimitive.Viewport
+        data-slot="scroll-area-viewport"
+        className="focus-visible:ring-ring/50 size-full rounded-[inherit] transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:outline-1"
+      >
+        {children}
+      </ScrollAreaPrimitive.Viewport>
+      <ScrollBar />
+      <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+  );
+}
+
+/**
+ * ScrollBar component for custom scrollbar styling
+ *
+ * Companion component to ScrollArea that renders styled scrollbars with
+ * support for both vertical and horizontal orientations. Usually used
+ * when explicit horizontal scrolling is needed.
+ *
+ * @param className - Additional CSS classes for scrollbar styling
+ * @param orientation - Scrollbar orientation, defaults to "vertical"
+ *
+ * @example
+ * ```tsx
+ * // Horizontal scrollbar (vertical is automatic)
+ * <ScrollArea className="w-full">
+ *   <div className="flex gap-4 p-4">
+ *     // Wide content
+ *   </div>
+ *   <ScrollBar orientation="horizontal" />
+ * </ScrollArea>
+ * ```
+ */
+function ScrollBar({
+  className,
+  orientation = "vertical",
+  ...props
+}: React.ComponentProps<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>) {
+  return (
+    <ScrollAreaPrimitive.ScrollAreaScrollbar
+      data-slot="scroll-area-scrollbar"
+      orientation={orientation}
+      className={cn(
+        "flex touch-none p-px transition-colors select-none",
+        orientation === "vertical" &&
+          "h-full w-2.5 border-l border-l-transparent",
+        orientation === "horizontal" &&
+          "h-2.5 flex-col border-t border-t-transparent",
+        className,
+      )}
+      {...props}
+    >
+      <ScrollAreaPrimitive.ScrollAreaThumb
+        data-slot="scroll-area-thumb"
+        className="bg-border relative flex-1 rounded-full"
+      />
+    </ScrollAreaPrimitive.ScrollAreaScrollbar>
+  );
+}
+
+export { ScrollArea, ScrollBar };