@neynar/ui 0.1.1

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

@@ -0,0 +1,145 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+import { Button } from "./button";
+
+/**
+ * Props for the EmptyState component
+ *
+ * Extends standard HTML div attributes to support all native div functionality
+ * while providing specific props for empty state content and behavior.
+ *
+ * @type EmptyStateProps
+ * @extends {React.HTMLAttributes<HTMLDivElement>}
+ */
+export type EmptyStateProps = React.HTMLAttributes<HTMLDivElement> & {
+  /** Main title text displayed prominently in the empty state */
+  title: string;
+  /** Optional descriptive text providing additional context or guidance */
+  description?: string;
+  /** Optional icon, illustration, or React element displayed above the title */
+  icon?: React.ReactNode;
+  /** Optional action button configuration for primary user action */
+  action?: {
+    /** Text label for the action button */
+    label: string;
+    /** Click handler function executed when the action button is pressed */
+    onClick: () => void;
+  };
+};
+
+/**
+ * EmptyState component for displaying empty or no-data states
+ *
+ * A versatile component that provides a consistent way to show empty states when there's
+ * no content to display. Commonly used in lists, tables, search results, dashboards,
+ * or any area where data might be absent. Follows standard empty state UX patterns
+ * with support for icons, descriptions, and call-to-action buttons to guide users.
+ *
+ * @example
+ * ```tsx
+ * // Basic empty state with title and description
+ * <EmptyState
+ *   title="No results found"
+ *   description="Try adjusting your search or filters to find what you're looking for"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Empty state with icon and action button
+ * import { Search } from 'lucide-react';
+ *
+ * <EmptyState
+ *   icon={<Search className="w-12 h-12" />}
+ *   title="No search results"
+ *   description="We couldn't find anything matching your search criteria"
+ *   action={{
+ *     label: "Clear search",
+ *     onClick: () => handleClearSearch()
+ *   }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Inbox empty state with contextual messaging
+ * import { Inbox } from 'lucide-react';
+ *
+ * <EmptyState
+ *   icon={<Inbox className="w-16 h-16" />}
+ *   title="Your inbox is empty"
+ *   description="When you receive new messages, they'll appear here"
+ *   action={{
+ *     label: "Compose message",
+ *     onClick: () => openComposer()
+ *   }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styled empty state for data visualization
+ * import { Database } from 'lucide-react';
+ *
+ * <EmptyState
+ *   className="min-h-[400px] bg-muted/30 rounded-lg"
+ *   icon={<Database className="w-14 h-14 opacity-50" />}
+ *   title="No data available"
+ *   description="Import data or connect a data source to get started"
+ *   action={{
+ *     label: "Import data",
+ *     onClick: () => showImportDialog()
+ *   }}
+ * />
+ * ```
+ *
+ * @param props - Component props extending HTMLDivElement attributes
+ * @param props.title - Main title text displayed prominently (required)
+ * @param props.description - Optional descriptive text providing context
+ * @param props.icon - Optional icon or React element displayed above title
+ * @param props.action - Optional action button configuration
+ * @param props.className - Additional CSS classes for styling
+ * @param ref - Forwarded ref to the container div element
+ *
+ * @remarks
+ * **Accessibility Features:**
+ * - Uses semantic HTML structure with proper heading hierarchy
+ * - Title rendered as h3 element for screen reader navigation
+ * - Action button follows Button component accessibility patterns
+ * - Supports keyboard navigation and focus management
+ * - Screen reader friendly text content structure
+ *
+ * **Design Guidelines:**
+ * - Icon should be 48-64px (w-12 h-12 to w-16 h-16) for optimal visual balance
+ * - Keep titles concise and action-oriented
+ * - Use descriptions to provide helpful context or next steps
+ * - Action buttons should have clear, specific labels
+ *
+ * @see {@link Button} for action button styling and behavior
+ * @since 1.0.0
+ */
+const EmptyState = React.forwardRef<HTMLDivElement, EmptyStateProps>(
+  ({ className, title, description, icon, action, ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "flex flex-col items-center justify-center text-center py-12 px-4",
+          className,
+        )}
+        {...props}
+      >
+        {icon && <div className="mb-4 text-muted-foreground">{icon}</div>}
+        <h3 className="text-lg font-semibold text-foreground mb-2">{title}</h3>
+        {description && (
+          <p className="text-muted-foreground mb-6 max-w-sm">{description}</p>
+        )}
+        {action && <Button onClick={action.onClick}>{action.label}</Button>}
+      </div>
+    );
+  },
+);
+
+EmptyState.displayName = "EmptyState";
+
+export { EmptyState };

package/src/components/ui/hover-card.tsx

@@ -0,0 +1,144 @@
+import * as React from "react";
+import * as HoverCardPrimitive from "@radix-ui/react-hover-card";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * HoverCard component for previewing content available behind a link
+ *
+ * For sighted users to preview content available behind a link. Displays rich content
+ * when users hover over a trigger element. Ideal for showing previews, user profiles,
+ * repository information, or contextual details without requiring navigation.
+ *
+ * Built on Radix UI Hover Card primitive with custom styling and animations.
+ *
+ * @example
+ * ```tsx
+ * // Basic user profile hover card
+ * <HoverCard>
+ *   <HoverCardTrigger asChild>
+ *     <Button variant="link">@nextjs</Button>
+ *   </HoverCardTrigger>
+ *   <HoverCardContent className="w-80">
+ *     <div className="flex justify-between gap-4">
+ *       <Avatar>
+ *         <AvatarImage src="https://github.com/vercel.png" />
+ *         <AvatarFallback>VC</AvatarFallback>
+ *       </Avatar>
+ *       <div className="space-y-1">
+ *         <h4 className="text-sm font-semibold">@nextjs</h4>
+ *         <p className="text-sm">
+ *           The React Framework – created and maintained by @vercel.
+ *         </p>
+ *         <div className="text-muted-foreground text-xs">
+ *           Joined December 2021
+ *         </div>
+ *       </div>
+ *     </div>
+ *   </HoverCardContent>
+ * </HoverCard>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom positioning and delays
+ * <HoverCard openDelay={500} closeDelay={200}>
+ *   <HoverCardTrigger asChild>
+ *     <Button>Hover me</Button>
+ *   </HoverCardTrigger>
+ *   <HoverCardContent side="top" align="start">
+ *     Content appears above with custom alignment
+ *   </HoverCardContent>
+ * </HoverCard>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Interactive content
+ * <HoverCard>
+ *   <HoverCardTrigger asChild>
+ *     <Button>Settings</Button>
+ *   </HoverCardTrigger>
+ *   <HoverCardContent>
+ *     <div className="space-y-2">
+ *       <h4 className="font-semibold">Quick Actions</h4>
+ *       <Button size="sm">Manage Team</Button>
+ *       <Button size="sm">View Reports</Button>
+ *     </div>
+ *   </HoverCardContent>
+ * </HoverCard>
+ * ```
+ *
+ * @accessibility
+ * **Important**: Hover cards are intended for sighted users only. The content will be
+ * inaccessible to keyboard users. Consider providing alternative access methods.
+ *
+ * - Opens on hover with configurable `openDelay`
+ * - Stays open when hovering over content
+ * - Closes with configurable `closeDelay`
+ * - Auto-positions to avoid viewport overflow
+ * - Supports focus-based interactions for some accessibility
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/hover-card} shadcn/ui documentation
+ * @since 1.0.0
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/hover-card} Radix UI Hover Card
+ */
+/**
+ * Root container for the hover card component
+ *
+ * @param openDelay - Delay in milliseconds before the hover card opens (default: 700)
+ * @param closeDelay - Delay in milliseconds before the hover card closes (default: 300)
+ * @param open - Controlled open state
+ * @param onOpenChange - Callback when open state changes
+ */
+function HoverCard({
+  ...props
+}: React.ComponentProps<typeof HoverCardPrimitive.Root>) {
+  return <HoverCardPrimitive.Root data-slot="hover-card" {...props} />;
+}
+
+/**
+ * Trigger element that opens the hover card on hover
+ *
+ * @param asChild - When true, merges props with immediate child element
+ */
+function HoverCardTrigger({
+  ...props
+}: React.ComponentProps<typeof HoverCardPrimitive.Trigger>) {
+  return (
+    <HoverCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />
+  );
+}
+
+/**
+ * Content container with built-in styling and animations
+ *
+ * @param side - Side of the trigger to position content ("top" | "right" | "bottom" | "left")
+ * @param align - Alignment relative to trigger ("start" | "center" | "end")
+ * @param sideOffset - Distance in pixels from the trigger (default: 4)
+ * @param alignOffset - Offset in pixels from the alignment axis
+ * @param className - Additional CSS classes
+ */
+function HoverCardContent({
+  className,
+  align = "center",
+  sideOffset = 4,
+  ...props
+}: React.ComponentProps<typeof HoverCardPrimitive.Content>) {
+  return (
+    <HoverCardPrimitive.Portal data-slot="hover-card-portal">
+      <HoverCardPrimitive.Content
+        data-slot="hover-card-content"
+        align={align}
+        sideOffset={sideOffset}
+        className={cn(
+          "bg-popover text-popover-foreground 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 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-64 origin-(--radix-hover-card-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden",
+          className,
+        )}
+        {...props}
+      />
+    </HoverCardPrimitive.Portal>
+  );
+}
+
+export { HoverCard, HoverCardTrigger, HoverCardContent };

package/src/components/ui/input.tsx

@@ -0,0 +1,106 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * A form input field component that displays text input or input-like elements
+ *
+ * A flexible input component based on shadcn/ui patterns that supports all native HTML input types
+ * and integrates seamlessly with form libraries like React Hook Form. Provides consistent styling,
+ * accessibility features, and error states across different input types.
+ *
+ * @example
+ * ```tsx
+ * // Basic email input
+ * <Input type="email" placeholder="Email" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Input with label for accessibility
+ * <div className="space-y-2">
+ *   <Label htmlFor="email">Email</Label>
+ *   <Input id="email" type="email" placeholder="Enter your email" />
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // File input with proper labeling
+ * <div className="grid w-full max-w-sm items-center gap-1.5">
+ *   <Label htmlFor="picture">Picture</Label>
+ *   <Input id="picture" type="file" />
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled input state
+ * <Input disabled type="email" placeholder="Email" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Input with button for subscription forms
+ * <div className="flex w-full max-w-sm items-center space-x-2">
+ *   <Input type="email" placeholder="Email" />
+ *   <Button type="submit">Subscribe</Button>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Form integration with React Hook Form
+ * const form = useForm();
+ *
+ * <Form>
+ *   <FormField
+ *     control={form.control}
+ *     name="email"
+ *     render={({ field }) => (
+ *       <FormItem>
+ *         <FormLabel>Email</FormLabel>
+ *         <FormControl>
+ *           <Input placeholder="shadcn" {...field} />
+ *         </FormControl>
+ *         <FormMessage />
+ *       </FormItem>
+ *     )}
+ *   />
+ * </Form>
+ * ```
+ *
+ * @param className - Additional CSS classes to apply to the input
+ * @param type - The input type (text, email, password, file, etc.)
+ * @param props - All other standard HTML input attributes
+ *
+ * @accessibility
+ * - Supports all ARIA attributes including aria-invalid for error states
+ * - Focus visible ring with proper contrast for keyboard navigation
+ * - Compatible with screen readers and assistive technologies
+ * - Proper semantic markup for form fields
+ * - Disabled state prevents interaction and indicates unavailability
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/input} - shadcn/ui Input documentation
+ * @see {@link Label} - For accessible input labels
+ * @see {@link Button} - Often used alongside inputs in forms
+ * @see {@link Form} - For complete form integration with validation
+ * @since 1.0.0
+ */
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-input flex h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
+        "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Input };

package/src/components/ui/label.tsx

@@ -0,0 +1,110 @@
+import * as React from "react";
+import * as LabelPrimitive from "@radix-ui/react-label";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Label component for form controls with full accessibility support
+ *
+ * A fundamental form component that provides accessible text labels for form controls.
+ * Built on Radix UI Label primitive, it automatically associates with form elements
+ * and expands their clickable area for improved usability and accessibility.
+ * Essential for creating accessible forms that meet WCAG guidelines.
+ *
+ * @example
+ * ```tsx
+ * // Basic label with input
+ * <div className="space-y-2">
+ *   <Label htmlFor="email">Email address</Label>
+ *   <Input id="email" type="email" placeholder="Enter your email" />
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Required field with indicator
+ * <Label htmlFor="username">
+ *   Username <span className="text-destructive">*</span>
+ * </Label>
+ * <Input id="username" required />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Checkbox with label
+ * <div className="flex items-center space-x-2">
+ *   <Checkbox id="terms" />
+ *   <Label htmlFor="terms" className="text-sm font-normal">
+ *     I agree to the terms and conditions
+ *   </Label>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Label with helper text
+ * <div className="space-y-1">
+ *   <Label htmlFor="password">Password</Label>
+ *   <Input id="password" type="password" />
+ *   <p className="text-sm text-muted-foreground">
+ *     Must be at least 8 characters long
+ *   </p>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex label with nested content
+ * <Label htmlFor="plan" className="flex flex-col space-y-1 cursor-pointer">
+ *   <span className="font-semibold">Choose your plan</span>
+ *   <span className="text-sm text-muted-foreground">
+ *     You can upgrade or downgrade anytime
+ *   </span>
+ * </Label>
+ * ```
+ *
+ * @remarks
+ * The Label component automatically handles:
+ * - Form control association via htmlFor/id pairing
+ * - Click-to-focus behavior for associated controls
+ * - Disabled state styling when associated control is disabled
+ * - Screen reader accessibility announcements
+ * - Proper semantic markup for form structures
+ *
+ * @accessibility
+ * - **ARIA Labelling**: Provides accessible names for form controls
+ * - **Focus Management**: Clicking label focuses associated control
+ * - **Disabled State**: Inherits and displays disabled styling from peer controls
+ * - **Screen Reader**: Announced with associated control for context
+ * - **Keyboard Navigation**: Supports standard label interaction patterns
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/label} - shadcn/ui Label documentation
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/label} - Radix UI Label primitive
+ * @see {@link https://www.w3.org/WAI/tutorials/forms/labels/} - W3C Label best practices
+ * @since 1.0.0
+ */
+/**
+ * Label component props extending Radix UI Label Root props
+ *
+ * @param className - Additional CSS classes to apply to the label
+ * @param htmlFor - The id of the form element this label is associated with
+ * @param children - The label content (text, elements, or components)
+ * @param ...props - All other props are forwarded to the underlying Radix Label component
+ */
+function Label({
+  className,
+  ...props
+}: React.ComponentProps<typeof LabelPrimitive.Root>) {
+  return (
+    <LabelPrimitive.Root
+      data-slot="label"
+      className={cn(
+        "flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Label };