@neynar/ui 0.1.1

package/src/components/ui/tabs.tsx

@@ -0,0 +1,316 @@
+import * as React from "react";
+import * as TabsPrimitive from "@radix-ui/react-tabs";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * A tabbed interface component for organizing content into multiple sections.
+ *
+ * Tabs provide an intuitive way to organize and display content in separate panels,
+ * with only one panel visible at a time. Built on Radix UI's robust accessibility
+ * foundation with full keyboard navigation, focus management, and screen reader support.
+ *
+ * The component supports both controlled and uncontrolled usage patterns, allowing
+ * for flexible integration in various application contexts. Each tab consists of a
+ * trigger (button) that activates its corresponding content panel.
+ *
+ * @example Basic uncontrolled tabs
+ * ```tsx
+ * <Tabs defaultValue="account" className="w-[400px]">
+ *   <TabsList>
+ *     <TabsTrigger value="account">Account</TabsTrigger>
+ *     <TabsTrigger value="password">Password</TabsTrigger>
+ *   </TabsList>
+ *   <TabsContent value="account">
+ *     <Card>
+ *       <CardContent>
+ *         <p>Manage your account settings here.</p>
+ *       </CardContent>
+ *     </Card>
+ *   </TabsContent>
+ *   <TabsContent value="password">
+ *     <Card>
+ *       <CardContent>
+ *         <p>Change your password here.</p>
+ *       </CardContent>
+ *     </Card>
+ *   </TabsContent>
+ * </Tabs>
+ * ```
+ *
+ * @example Controlled tabs with external state management
+ * ```tsx
+ * const [activeTab, setActiveTab] = useState("overview");
+ *
+ * // External controls can change the active tab
+ * const handleQuickNav = (tab: string) => {
+ *   setActiveTab(tab);
+ * };
+ *
+ * <Tabs value={activeTab} onValueChange={setActiveTab}>
+ *   <TabsList>
+ *     <TabsTrigger value="overview">Overview</TabsTrigger>
+ *     <TabsTrigger value="analytics">Analytics</TabsTrigger>
+ *     <TabsTrigger value="reports">Reports</TabsTrigger>
+ *   </TabsList>
+ *   <TabsContent value="overview">
+ *     <DashboardOverview />
+ *   </TabsContent>
+ *   <TabsContent value="analytics">
+ *     <AnalyticsPanel />
+ *   </TabsContent>
+ *   <TabsContent value="reports">
+ *     <ReportsPanel />
+ *   </TabsContent>
+ * </Tabs>
+ * ```
+ *
+ * @example Vertical orientation
+ * ```tsx
+ * <Tabs defaultValue="general" orientation="vertical" className="flex gap-4">
+ *   <TabsList className="flex-col h-auto">
+ *     <TabsTrigger value="general">General</TabsTrigger>
+ *     <TabsTrigger value="security">Security</TabsTrigger>
+ *     <TabsTrigger value="notifications">Notifications</TabsTrigger>
+ *   </TabsList>
+ *   <div className="flex-1">
+ *     <TabsContent value="general">
+ *       <SettingsGeneral />
+ *     </TabsContent>
+ *     <TabsContent value="security">
+ *       <SettingsSecurity />
+ *     </TabsContent>
+ *     <TabsContent value="notifications">
+ *       <SettingsNotifications />
+ *     </TabsContent>
+ *   </div>
+ * </Tabs>
+ * ```
+ *
+ * @param defaultValue - The initial active tab (uncontrolled usage)
+ * @param value - The currently active tab (controlled usage)
+ * @param onValueChange - Callback fired when the active tab changes
+ * @param orientation - Layout direction: "horizontal" (default) or "vertical"
+ * @param dir - Text direction for RTL support: "ltr" or "rtl"
+ * @param activationMode - When tabs activate: "automatic" (on focus) or "manual" (on click/enter)
+ * @param className - Additional CSS classes to apply
+ * @param children - Tab list, content panels, and other child elements
+ *
+ * @accessibility
+ * - **Keyboard Navigation**: Arrow keys navigate between tabs, Tab/Shift+Tab moves focus into/out of tab list
+ * - **Focus Management**: Home/End keys jump to first/last tab, proper focus visible indicators
+ * - **Screen Readers**: Proper ARIA roles (tablist, tab, tabpanel), labels, and state announcements
+ * - **Touch Support**: Touch-friendly trigger areas with appropriate spacing
+ * - **RTL Support**: Respects text direction for proper layout in right-to-left languages
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/tabs} shadcn/ui tabs documentation
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/tabs} Radix UI tabs primitive
+ * @see {@link TabsList} - Container component for tab triggers
+ * @see {@link TabsTrigger} - Individual clickable tab button
+ * @see {@link TabsContent} - Content panel associated with each tab
+ * @since 1.0.0
+ */
+function Tabs({
+  className,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Root>) {
+  return (
+    <TabsPrimitive.Root
+      data-slot="tabs"
+      className={cn("flex flex-col gap-2", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Container component that groups all tab trigger buttons together.
+ *
+ * Provides consistent styling and layout for tab triggers with a unified
+ * background and proper spacing. The list maintains the tab order and
+ * handles focus management within the tabbed interface.
+ *
+ * @example Standard horizontal layout
+ * ```tsx
+ * <TabsList>
+ *   <TabsTrigger value="home">Home</TabsTrigger>
+ *   <TabsTrigger value="about">About</TabsTrigger>
+ *   <TabsTrigger value="contact">Contact</TabsTrigger>
+ * </TabsList>
+ * ```
+ *
+ * @example Grid layout for equal-width tabs
+ * ```tsx
+ * <TabsList className="grid w-full grid-cols-3">
+ *   <TabsTrigger value="tab1">Tab 1</TabsTrigger>
+ *   <TabsTrigger value="tab2">Tab 2</TabsTrigger>
+ *   <TabsTrigger value="tab3">Tab 3</TabsTrigger>
+ * </TabsList>
+ * ```
+ *
+ * @example Vertical orientation
+ * ```tsx
+ * <TabsList className="flex-col h-auto w-[200px]">
+ *   <TabsTrigger value="settings" className="w-full justify-start">
+ *     Settings
+ *   </TabsTrigger>
+ *   <TabsTrigger value="profile" className="w-full justify-start">
+ *     Profile
+ *   </TabsTrigger>
+ * </TabsList>
+ * ```
+ *
+ * @param className - Additional CSS classes for custom styling
+ * @param children - TabsTrigger components to be grouped
+ *
+ * @accessibility
+ * - Implements ARIA tablist role for screen readers
+ * - Maintains proper tab order and focus management
+ * - Supports keyboard navigation between triggers
+ *
+ * @since 1.0.0
+ */
+function TabsList({
+  className,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.List>) {
+  return (
+    <TabsPrimitive.List
+      data-slot="tabs-list"
+      className={cn(
+        "bg-muted text-muted-foreground inline-flex h-9 w-fit items-center justify-center rounded-lg p-[3px]",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Individual clickable button that activates its associated tab content.
+ *
+ * Each trigger is associated with a specific tab panel via the `value` prop.
+ * The component automatically handles active states, focus management, and
+ * accessibility attributes. Supports icons, text, and custom content.
+ *
+ * @example Basic text trigger
+ * ```tsx
+ * <TabsTrigger value="dashboard">Dashboard</TabsTrigger>
+ * ```
+ *
+ * @example Trigger with icon
+ * ```tsx
+ * <TabsTrigger value="settings">
+ *   <Settings className="h-4 w-4" />
+ *   Settings
+ * </TabsTrigger>
+ * ```
+ *
+ * @example Disabled trigger
+ * ```tsx
+ * <TabsTrigger value="premium" disabled>
+ *   Premium Features
+ * </TabsTrigger>
+ * ```
+ *
+ * @param value - Unique identifier that associates this trigger with its content panel
+ * @param disabled - When true, prevents interaction and shows disabled styling
+ * @param className - Additional CSS classes for custom styling
+ * @param children - Content to display within the trigger (text, icons, etc.)
+ *
+ * @accessibility
+ * - Implements ARIA tab role with proper attributes
+ * - Announces selected state to screen readers
+ * - Supports keyboard activation (Space, Enter)
+ * - Shows focus visible indicators for keyboard users
+ * - Respects disabled state for assistive technology
+ *
+ * @since 1.0.0
+ */
+function TabsTrigger({
+  className,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Trigger>) {
+  return (
+    <TabsPrimitive.Trigger
+      data-slot="tabs-trigger"
+      className={cn(
+        "data-[state=active]:bg-background dark:data-[state=active]:text-foreground focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:outline-ring dark:data-[state=active]:border-input dark:data-[state=active]:bg-input/30 text-foreground dark:text-muted-foreground inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-2 py-1 text-sm font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:ring-[3px] focus-visible:outline-1 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:shadow-sm [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Content panel that displays when its associated tab trigger is active.
+ *
+ * Each content panel is linked to a specific trigger via the `value` prop.
+ * Only one content panel is visible at a time, creating a clean tabbed
+ * interface. The component handles enter/exit animations and proper
+ * focus management when tabs change.
+ *
+ * @example Basic content panel
+ * ```tsx
+ * <TabsContent value="profile">
+ *   <Card>
+ *     <CardHeader>
+ *       <CardTitle>Profile Settings</CardTitle>
+ *     </CardHeader>
+ *     <CardContent>
+ *       <ProfileForm />
+ *     </CardContent>
+ *   </Card>
+ * </TabsContent>
+ * ```
+ *
+ * @example Content with loading state
+ * ```tsx
+ * <TabsContent value="analytics">
+ *   {isLoading ? (
+ *     <div className="flex items-center justify-center p-8">
+ *       <Spinner className="h-6 w-6" />
+ *     </div>
+ *   ) : (
+ *     <AnalyticsCharts data={analyticsData} />
+ *   )}
+ * </TabsContent>
+ * ```
+ *
+ * @example Lazy-loaded content
+ * ```tsx
+ * <TabsContent value="reports" className="space-y-4">
+ *   <Suspense fallback={<ReportsSkeleton />}>
+ *     <ReportsPanel />
+ *   </Suspense>
+ * </TabsContent>
+ * ```
+ *
+ * @param value - Unique identifier that associates this content with its trigger
+ * @param forceMount - When true, content stays mounted even when inactive (useful for preserving state)
+ * @param className - Additional CSS classes for custom styling
+ * @param children - The content to display when this tab is active
+ *
+ * @accessibility
+ * - Implements ARIA tabpanel role with proper labeling
+ * - Hidden from screen readers when inactive
+ * - Receives focus when tab is activated via keyboard
+ * - Maintains focus within panel content
+ *
+ * @since 1.0.0
+ */
+function TabsContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Content>) {
+  return (
+    <TabsPrimitive.Content
+      data-slot="tabs-content"
+      className={cn("flex-1 outline-none", className)}
+      {...props}
+    />
+  );
+}
+
+export { Tabs, TabsList, TabsTrigger, TabsContent };

package/src/components/ui/text-field.tsx

@@ -0,0 +1,206 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+import { Input } from "./input";
+import { Label } from "./label";
+
+/**
+ * Props for the TextField component
+ *
+ * Extends standard HTML input properties while omitting 'id' to allow
+ * automatic ID generation for accessibility.
+ */
+export type TextFieldProps = Omit<React.ComponentProps<"input">, "id"> & {
+  /**
+   * Label text displayed above the input
+   *
+   * When provided, creates a semantic label-input relationship
+   * for improved accessibility and user experience.
+   */
+  label?: string;
+  /**
+   * Helper text displayed below the input
+   *
+   * Provides additional context or instructions to help users
+   * understand the expected input format or purpose.
+   */
+  helperText?: string;
+  /**
+   * Error message displayed below the input
+   *
+   * When provided, sets the input to an error state with
+   * destructive styling and proper ARIA attributes.
+   * Takes precedence over helperText when both are present.
+   */
+  error?: string;
+  /**
+   * Whether the field is required
+   *
+   * Adds a visual asterisk (*) indicator to the label
+   * and semantic meaning for form validation.
+   *
+   * @default false
+   */
+  required?: boolean;
+  /**
+   * Custom ID for the input field
+   *
+   * If not provided, an automatic ID will be generated
+   * using React.useId() for accessibility compliance.
+   */
+  id?: string;
+};
+
+/**
+ * A complete form field component combining input, label, and descriptive text
+ *
+ * TextField provides a complete form field solution by composing the base Input
+ * and Label components with additional helper text and error handling. It automatically
+ * manages accessibility attributes, ID generation, and ARIA relationships to ensure
+ * forms are usable by all users including those using assistive technologies.
+ *
+ * This component follows form design patterns similar to those found in modern UI
+ * libraries while providing Neynar-specific styling and behavior. It supports all
+ * standard HTML input types and attributes while adding enhanced UX features.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <TextField
+ *   label="Email Address"
+ *   type="email"
+ *   placeholder="Enter your email"
+ * />
+ * ```
+ *
+ * @example With helper text
+ * ```tsx
+ * <TextField
+ *   label="Username"
+ *   placeholder="@username"
+ *   helperText="Choose a unique username (3-20 characters)"
+ * />
+ * ```
+ *
+ * @example Error state
+ * ```tsx
+ * <TextField
+ *   label="Password"
+ *   type="password"
+ *   required
+ *   error="Password must be at least 8 characters"
+ *   value={password}
+ *   onChange={(e) => setPassword(e.target.value)}
+ * />
+ * ```
+ *
+ * @example Controlled component with validation
+ * ```tsx
+ * const [email, setEmail] = useState("");
+ * const [error, setError] = useState("");
+ *
+ * const validateEmail = (value: string) => {
+ *   if (!value.includes("@")) {
+ *     setError("Please enter a valid email");
+ *   } else {
+ *     setError("");
+ *   }
+ * };
+ *
+ * <TextField
+ *   label="Email"
+ *   type="email"
+ *   value={email}
+ *   onChange={(e) => {
+ *     setEmail(e.target.value);
+ *     validateEmail(e.target.value);
+ *   }}
+ *   error={error}
+ *   required
+ * />
+ * ```
+ *
+ * @example Form integration
+ * ```tsx
+ * <form onSubmit={handleSubmit}>
+ *   <TextField
+ *     label="Full Name"
+ *     name="fullName"
+ *     required
+ *     helperText="First and last name"
+ *   />
+ *   <TextField
+ *     label="API Key"
+ *     type="password"
+ *     name="apiKey"
+ *     required
+ *     helperText="Get your key from the Neynar dashboard"
+ *   />
+ * </form>
+ * ```
+ *
+ * ## Accessibility Features
+ *
+ * - **Semantic HTML**: Uses proper label-input association via `htmlFor` attribute
+ * - **ARIA Support**: Implements `aria-invalid`, `aria-describedby`, and `aria-required`
+ * - **Focus Management**: Keyboard navigation and focus indicators work correctly
+ * - **Screen Readers**: Helper text and error messages are properly announced
+ * - **Required Fields**: Visual and semantic indication with asterisk and ARIA attributes
+ * - **Error States**: Clear visual and programmatic error indication
+ *
+ * ## Styling & Variants
+ *
+ * The component inherits styling from the base Input component and adds:
+ * - Error state styling with destructive colors
+ * - Consistent spacing with `space-y-2` utility
+ * - Muted foreground color for helper text
+ * - Required field indicator styling
+ *
+ * @see {@link Input} The underlying input component
+ * @see {@link Label} The label component used for field labels
+ * @since 1.0.0 */
+const TextField = React.forwardRef<HTMLInputElement, TextFieldProps>(
+  ({ label, helperText, error, required, className, id, ...props }, ref) => {
+    const idIfNeeded = React.useId();
+    const fieldId = id || idIfNeeded;
+
+    return (
+      <div className={cn("space-y-2", className)}>
+        {label && (
+          <Label htmlFor={fieldId} className={error ? "text-destructive" : ""}>
+            {label}
+            {required && <span className="text-destructive ml-1">*</span>}
+          </Label>
+        )}
+        <Input
+          id={fieldId}
+          ref={ref}
+          className={
+            error ? "border-destructive focus-visible:ring-destructive" : ""
+          }
+          aria-invalid={!!error}
+          aria-describedby={
+            error
+              ? `${fieldId}-error`
+              : helperText
+                ? `${fieldId}-helper`
+                : undefined
+          }
+          {...props}
+        />
+        {error && (
+          <p id={`${fieldId}-error`} className="text-sm text-destructive">
+            {error}
+          </p>
+        )}
+        {helperText && !error && (
+          <p id={`${fieldId}-helper`} className="text-sm text-muted-foreground">
+            {helperText}
+          </p>
+        )}
+      </div>
+    );
+  },
+);
+
+TextField.displayName = "TextField";
+
+export { TextField };

package/src/components/ui/textarea.tsx

@@ -0,0 +1,98 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * A multi-line text input control built on the native HTML textarea element
+ *
+ * The Textarea component provides a styled textarea for entering longer pieces
+ * of text that span multiple lines, such as comments, descriptions, or messages.
+ * Features automatic content-based resizing using CSS field-sizing when supported
+ * by the browser.
+ *
+ * Built following shadcn/ui design patterns with consistent styling and behavior
+ * across form elements.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Textarea placeholder="Type your message here." />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With label and validation
+ * <div className="space-y-2">
+ *   <Label htmlFor="description">Description</Label>
+ *   <Textarea
+ *     id="description"
+ *     placeholder="Enter a description..."
+ *     rows={4}
+ *   />
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled with character limit
+ * const [bio, setBio] = useState("");
+ * const maxLength = 160;
+ *
+ * <div className="space-y-2">
+ *   <Label htmlFor="bio">Bio</Label>
+ *   <Textarea
+ *     id="bio"
+ *     value={bio}
+ *     onChange={(e) => setBio(e.target.value)}
+ *     placeholder="Tell us about yourself..."
+ *     maxLength={maxLength}
+ *   />
+ *   <p className="text-sm text-muted-foreground">
+ *     {bio.length}/{maxLength} characters
+ *   </p>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With error state
+ * <Textarea
+ *   placeholder="Enter your feedback"
+ *   aria-invalid="true"
+ *   aria-describedby="feedback-error"
+ *   className="border-destructive"
+ * />
+ * <p id="feedback-error" className="text-sm text-destructive">
+ *   This field is required
+ * </p>
+ * ```
+ *
+ * @param className - Additional CSS classes to apply
+ * @param ...props - All standard HTML textarea attributes are supported
+ *
+ * @accessibility
+ * - Inherits all native textarea accessibility features
+ * - Supports keyboard navigation with visible focus indicators
+ * - Compatible with screen readers and assistive technologies
+ * - Properly handles aria-invalid for validation states
+ * - Works seamlessly with Label components via htmlFor/id association
+ * - Respects disabled and readonly states
+ * - Auto-resizing maintains proper focus and scroll behavior
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/textarea} shadcn/ui Textarea documentation
+ * @since 1.0.0
+ */
+function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
+  return (
+    <textarea
+      data-slot="textarea"
+      className={cn(
+        "border-input placeholder:text-muted-foreground 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 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Textarea };