@neynar/ui 0.1.1 → 0.1.2

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

@@ -4,102 +4,136 @@ 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.
+ * Props for TextField component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
  */
-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.
-   */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TextFieldDocsProps = {
+  /** Label text displayed above the input field @example "Email Address" */
   label?: string;
-  /**
-   * Helper text displayed below the input
-   *
-   * Provides additional context or instructions to help users
-   * understand the expected input format or purpose.
-   */
+  /** Helper text displayed below the input field for additional context */
   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 message displayed below the input field, takes precedence over helperText */
   error?: string;
-  /**
-   * Whether the field is required
-   *
-   * Adds a visual asterisk (*) indicator to the label
-   * and semantic meaning for form validation.
-   *
-   * @default false
-   */
+  /** Whether the form field is required for 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.
-   */
+  /** Custom identifier for the input element (auto-generated if not provided) */
   id?: string;
-};
+  /** The type of input field to render @default "text" */
+  type?: React.HTMLInputTypeAttribute;
+  /** Placeholder text displayed when the input is empty */
+  placeholder?: string;
+  /** Current value of the input field (controlled component) */
+  value?: string | ReadonlyArray<string> | number;
+  /** Default value for uncontrolled input usage */
+  defaultValue?: string | ReadonlyArray<string> | number;
+  /** Whether the input field is disabled and non-interactive @default false */
+  disabled?: boolean;
+  /** Whether the input field is read-only @default false */
+  readOnly?: boolean;
+  /** Name attribute for form submission and validation */
+  name?: string;
+  /** Auto-complete hint for browsers */
+  autoComplete?: string;
+  /** Whether to automatically focus this input when mounted @default false */
+  autoFocus?: boolean;
+  /** Maximum number of characters allowed in text inputs */
+  maxLength?: number;
+  /** Minimum number of characters required for text inputs */
+  minLength?: number;
+  /** Regular expression pattern for client-side validation */
+  pattern?: string;
+  /** Minimum value for numeric input types */
+  min?: string | number;
+  /** Maximum value for numeric input types */
+  max?: string | number;
+  /** Step value for numeric inputs */
+  step?: string | number;
+  /** Callback fired when the input value changes */
+  onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+  /** Callback fired when the input receives focus */
+  onFocus?: (event: React.FocusEvent<HTMLInputElement>) => void;
+  /** Callback fired when the input loses focus */
+  onBlur?: (event: React.FocusEvent<HTMLInputElement>) => void;
+  /** Callback fired when a key is pressed down */
+  onKeyDown?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+  /** Callback fired when a key is released */
+  onKeyUp?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+} & React.InputHTMLAttributes<HTMLInputElement>;
+
+type TextFieldProps = {
+  label?: string;
+  helperText?: string;
+  error?: string;
+  required?: boolean;
+  className?: string;
+} & Omit<React.ComponentProps<typeof Input>, "className">;
 
 /**
- * A complete form field component combining input, label, and descriptive text
+ * TextField - Complete form field with label, input, 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.
+ * A comprehensive form field component that combines Input and Label components with
+ * additional helper text and error handling capabilities. 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.
+ * Built on top of the Input and Label primitives, TextField provides a complete
+ * form field solution with consistent styling, proper semantic markup, and enhanced
+ * UX features. Supports all HTML input types while adding form validation states,
+ * descriptive text, and automatic accessibility compliance.
  *
- * @example Basic usage
+ * @example
  * ```tsx
+ * // Basic text input with label
  * <TextField
  *   label="Email Address"
  *   type="email"
  *   placeholder="Enter your email"
+ *   name="email"
  * />
  * ```
  *
- * @example With helper text
+ * @example
  * ```tsx
+ * // Required field with helper text
  * <TextField
  *   label="Username"
  *   placeholder="@username"
- *   helperText="Choose a unique username (3-20 characters)"
+ *   helperText="Choose a unique username (3-20 characters, letters and numbers only)"
+ *   required
+ *   minLength={3}
+ *   maxLength={20}
+ *   pattern="[a-zA-Z0-9]+"
  * />
  * ```
  *
- * @example Error state
+ * @example
  * ```tsx
+ * // Password field with validation error
  * <TextField
  *   label="Password"
  *   type="password"
  *   required
- *   error="Password must be at least 8 characters"
+ *   error="Password must be at least 8 characters long"
  *   value={password}
  *   onChange={(e) => setPassword(e.target.value)}
+ *   minLength={8}
+ *   autoComplete="new-password"
  * />
  * ```
  *
- * @example Controlled component with validation
+ * @example
  * ```tsx
+ * // Controlled component with real-time validation
  * const [email, setEmail] = useState("");
  * const [error, setError] = useState("");
  *
  * const validateEmail = (value: string) => {
- *   if (!value.includes("@")) {
- *     setError("Please enter a valid email");
+ *   const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+ *   if (!emailRegex.test(value)) {
+ *     setError("Please enter a valid email address");
  *   } else {
  *     setError("");
  *   }
@@ -113,50 +147,161 @@ export type TextFieldProps = Omit<React.ComponentProps<"input">, "id"> & {
  *     setEmail(e.target.value);
  *     validateEmail(e.target.value);
  *   }}
+ *   onBlur={(e) => validateEmail(e.target.value)}
  *   error={error}
  *   required
+ *   autoComplete="email"
  * />
  * ```
  *
- * @example Form integration
+ * @example
  * ```tsx
- * <form onSubmit={handleSubmit}>
+ * // Number input with constraints
+ * <TextField
+ *   label="Age"
+ *   type="number"
+ *   min={0}
+ *   max={120}
+ *   step={1}
+ *   helperText="Enter your age in years"
+ *   placeholder="25"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Search input with custom styling
+ * <TextField
+ *   label="Search"
+ *   type="search"
+ *   placeholder="Search products..."
+ *   className="max-w-md"
+ *   onKeyDown={(e) => {
+ *     if (e.key === 'Enter') {
+ *       handleSearch(e.currentTarget.value);
+ *     }
+ *   }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Form integration with React Hook Form
+ * const { register, formState: { errors } } = useForm();
+ *
+ * <form onSubmit={handleSubmit(onSubmit)}>
  *   <TextField
  *     label="Full Name"
- *     name="fullName"
- *     required
- *     helperText="First and last name"
+ *     {...register("fullName", { required: "Full name is required" })}
+ *     error={errors.fullName?.message}
+ *     helperText="Enter your first and last name"
  *   />
+ *
  *   <TextField
- *     label="API Key"
- *     type="password"
- *     name="apiKey"
- *     required
- *     helperText="Get your key from the Neynar dashboard"
+ *     label="Phone Number"
+ *     type="tel"
+ *     {...register("phone", {
+ *       pattern: {
+ *         value: /^[\+]?[1-9][\d]{0,15}$/,
+ *         message: "Please enter a valid phone number"
+ *       }
+ *     })}
+ *     error={errors.phone?.message}
+ *     autoComplete="tel"
  *   />
  * </form>
  * ```
  *
- * ## Accessibility Features
+ * @example
+ * ```tsx
+ * // File input with custom validation
+ * <TextField
+ *   label="Profile Picture"
+ *   type="file"
+ *   accept="image/*"
+ *   helperText="Upload a PNG, JPG or GIF (max 5MB)"
+ *   onChange={(e) => {
+ *     const file = e.target.files?.[0];
+ *     if (file && file.size > 5 * 1024 * 1024) {
+ *       setError("File size must be less than 5MB");
+ *     } else {
+ *       setError("");
+ *       handleFileUpload(file);
+ *     }
+ *   }}
+ *   error={fileError}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Date input with range constraints
+ * <TextField
+ *   label="Birth Date"
+ *   type="date"
+ *   min="1900-01-01"
+ *   max={new Date().toISOString().split('T')[0]}
+ *   helperText="You must be 18 or older to register"
+ *   required
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled field with explanation
+ * <TextField
+ *   label="Account ID"
+ *   value="ACC-12345"
+ *   disabled
+ *   helperText="This value is automatically generated and cannot be changed"
+ * />
+ * ```
+ *
+ * @accessibility
+ * - **Semantic Association**: Proper label-input relationship via `htmlFor` and `id` attributes
+ * - **ARIA Support**: Implements `aria-invalid`, `aria-describedby`, and `aria-required` attributes
+ * - **Focus Management**: Keyboard navigation with visible focus indicators and proper tab order
+ * - **Screen Reader Support**: Helper text and error messages are properly announced via `aria-describedby`
+ * - **Required Fields**: Visual asterisk indicator and semantic `aria-required` for screen readers
+ * - **Error States**: Clear visual styling and programmatic error indication with `aria-invalid`
+ * - **Automatic ID Generation**: Uses `React.useId()` to prevent conflicts and ensure accessibility
+ * - **Click-to-Focus**: Clicking the label automatically focuses the input field
+ * - **Disabled State**: Proper disabled styling and screen reader announcements
+ * - **Validation Support**: Works with native HTML5 validation and custom validation libraries
+ *
+ * @remarks
+ * The TextField component automatically handles:
+ * - ID generation and label-input association for accessibility compliance
+ * - ARIA attribute management based on component state (error, required, helper text)
+ * - Error state precedence over helper text display
+ * - Focus management and keyboard navigation patterns
+ * - Consistent styling inheritance from Input and Label components
+ * - Screen reader compatibility with proper announcements
  *
- * - **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
+ * ## Component Composition
  *
- * ## Styling & Variants
+ * TextField is composed of:
+ * - **Root Container**: `div` with `space-y-2` for consistent spacing
+ * - **Label**: Radix UI Label primitive with proper association and styling
+ * - **Input**: Enhanced HTML input with design system styling and validation states
+ * - **Helper/Error Text**: Conditional paragraph elements with proper ARIA linking
  *
- * 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
+ * ## Input Type Support
  *
- * @see {@link Input} The underlying input component
- * @see {@link Label} The label component used for field labels
- * @since 1.0.0 */
+ * Supports all HTML input types including:
+ * - **Text Types**: `text`, `email`, `password`, `tel`, `url`, `search`
+ * - **Numeric Types**: `number`, `range` (with min/max/step support)
+ * - **Date/Time Types**: `date`, `datetime-local`, `month`, `time`, `week`
+ * - **Other Types**: `file`, `hidden`, `color`, `checkbox`, `radio`
+ *
+ * @see {@link Input} The underlying input component with styling and validation
+ * @see {@link Label} The label component used for accessible field labels
+ * @see {@link https://ui.shadcn.com/docs/components/input} shadcn/ui Input documentation
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/label} Radix UI Label primitive
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input} MDN Input element reference
+ * @see {@link https://www.w3.org/WAI/tutorials/forms/} W3C Forms accessibility tutorial
+ * @since 1.0.0
+ */
 const TextField = React.forwardRef<HTMLInputElement, TextFieldProps>(
   ({ label, helperText, error, required, className, id, ...props }, ref) => {
     const idIfNeeded = React.useId();

package/src/components/ui/textarea.tsx

@@ -3,20 +3,95 @@ import * as React from "react";
 import { cn } from "@/lib/utils";
 
 /**
- * A multi-line text input control built on the native HTML textarea element
+ * Props for Textarea (Documentation only - NOT used in component implementation)
  *
- * 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.
+ * Multi-line text input for extended content entry. Built on the native HTML
+ * textarea element with enhanced styling and accessibility features.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TextareaDocsProps = {
+  /** Additional CSS classes for styling customization */
+  className?: string;
+  /** Placeholder text displayed when the textarea is empty */
+  placeholder?: string;
+  /** Whether the textarea is disabled and non-interactive @default false */
+  disabled?: boolean;
+  /** Whether the textarea is read-only (non-editable) @default false */
+  readOnly?: boolean;
+  /** Number of visible text lines for initial height @default 2 */
+  rows?: number;
+  /** Number of visible character columns for initial width */
+  cols?: number;
+  /** Maximum number of characters allowed (UTF-16 code units) */
+  maxLength?: number;
+  /** Minimum number of characters required */
+  minLength?: number;
+  /** Whether the textarea is required for form submission @default false */
+  required?: boolean;
+  /** Form element ID that this textarea belongs to */
+  form?: string;
+  /** Name attribute for form submission */
+  name?: string;
+  /** Unique identifier for this textarea element */
+  id?: string;
+  /** Current value of the textarea (for controlled components) */
+  value?: string;
+  /** Initial value for uncontrolled components */
+  defaultValue?: string;
+  /** How text wrapping should be handled @default "soft" */
+  wrap?: "soft" | "hard" | "off";
+  /** Enable automatic focusing when component mounts @default false */
+  autoFocus?: boolean;
+  /** Hint for form autofill feature */
+  autoComplete?: string;
+  /** Control automatic capitalization behavior */
+  autoCapitalize?: "none" | "sentences" | "words" | "characters";
+  /** Enable spell checking @default true */
+  spellCheck?: boolean;
+  /** Callback fired when the value changes @param event - The change event */
+  onChange?: (event: React.ChangeEvent<HTMLTextAreaElement>) => void;
+  /** Callback fired when the textarea gains focus @param event - The focus event */
+  onFocus?: (event: React.FocusEvent<HTMLTextAreaElement>) => void;
+  /** Callback fired when the textarea loses focus @param event - The blur event */
+  onBlur?: (event: React.FocusEvent<HTMLTextAreaElement>) => void;
+  /** Callback fired on keydown events @param event - The keyboard event */
+  onKeyDown?: (event: React.KeyboardEvent<HTMLTextAreaElement>) => void;
+  /** Callback fired on keyup events @param event - The keyboard event */
+  onKeyUp?: (event: React.KeyboardEvent<HTMLTextAreaElement>) => void;
+  /** Callback fired on keypress events @param event - The keyboard event */
+  onKeyPress?: (event: React.KeyboardEvent<HTMLTextAreaElement>) => void;
+  /** Indicates if the input fails validation @default false */
+  "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling";
+  /** References element(s) that describe this textarea */
+  "aria-describedby"?: string;
+  /** References element that labels this textarea */
+  "aria-labelledby"?: string;
+  /** Accessible label when no visible label is present */
+  "aria-label"?: string;
+  /** Tab index for keyboard navigation order */
+  tabIndex?: number;
+  /** CSS resize behavior control */
+  style?: React.CSSProperties & {
+    resize?: "none" | "both" | "horizontal" | "vertical";
+  };
+} & React.TextareaHTMLAttributes<HTMLTextAreaElement>;
+
+/**
+ * Textarea - Multi-line text input control for extended content entry
+ *
+ * A styled textarea component built on the native HTML textarea element for entering
+ * longer pieces of text that span multiple lines, such as comments, descriptions,
+ * messages, or any content that requires multiple lines of input. 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.
+ * across form elements. Inherits all native HTML textarea functionality while
+ * providing enhanced visual design and better accessibility patterns.
  *
  * @example
  * ```tsx
  * // Basic usage
- * <Textarea placeholder="Type your message here." />
+ * <Textarea placeholder="Type your message here..." />
  * ```
  *
  * @example
@@ -28,14 +103,16 @@ import { cn } from "@/lib/utils";
  *     id="description"
  *     placeholder="Enter a description..."
  *     rows={4}
+ *     required
  *   />
  * </div>
  * ```
  *
  * @example
  * ```tsx
- * // Controlled with character limit
+ * // Controlled with character limit and validation
  * const [bio, setBio] = useState("");
+ * const [error, setError] = useState("");
  * const maxLength = 160;
  *
  * <div className="space-y-2">
@@ -43,43 +120,117 @@ import { cn } from "@/lib/utils";
  *   <Textarea
  *     id="bio"
  *     value={bio}
- *     onChange={(e) => setBio(e.target.value)}
+ *     onChange={(e) => {
+ *       setBio(e.target.value);
+ *       if (e.target.value.length > maxLength) {
+ *         setError("Bio is too long");
+ *       } else {
+ *         setError("");
+ *       }
+ *     }}
  *     placeholder="Tell us about yourself..."
  *     maxLength={maxLength}
+ *     aria-invalid={!!error}
+ *     aria-describedby={error ? "bio-error" : "bio-count"}
  *   />
- *   <p className="text-sm text-muted-foreground">
- *     {bio.length}/{maxLength} characters
- *   </p>
+ *   <div className="flex justify-between items-center">
+ *     <p id="bio-count" className="text-sm text-muted-foreground">
+ *       {bio.length}/{maxLength} characters
+ *     </p>
+ *     {error && (
+ *       <p id="bio-error" className="text-sm text-destructive">
+ *         {error}
+ *       </p>
+ *     )}
+ *   </div>
  * </div>
  * ```
  *
  * @example
  * ```tsx
- * // With error state
+ * // Auto-resizing with minimum height
  * <Textarea
- *   placeholder="Enter your feedback"
- *   aria-invalid="true"
- *   aria-describedby="feedback-error"
- *   className="border-destructive"
+ *   placeholder="This textarea grows with content"
+ *   className="min-h-[100px] max-h-[300px]"
+ *   style={{ resize: "vertical" }}
  * />
- * <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
+ * @example
+ * ```tsx
+ * // Form integration with validation
+ * <form onSubmit={handleSubmit}>
+ *   <div className="space-y-2">
+ *     <Label htmlFor="feedback">Feedback</Label>
+ *     <Textarea
+ *       id="feedback"
+ *       name="feedback"
+ *       placeholder="Share your thoughts..."
+ *       required
+ *       minLength={10}
+ *       maxLength={500}
+ *       rows={3}
+ *     />
+ *   </div>
+ *   <Button type="submit">Submit Feedback</Button>
+ * </form>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Different wrap behaviors for code/text
+ * <div className="space-y-4">
+ *   <div>
+ *     <Label>Code (no wrapping)</Label>
+ *     <Textarea
+ *       wrap="off"
+ *       placeholder="Enter code here..."
+ *       className="font-mono text-sm"
+ *       style={{ resize: "both" }}
+ *     />
+ *   </div>
+ *   <div>
+ *     <Label>Text (soft wrapping)</Label>
+ *     <Textarea
+ *       wrap="soft"
+ *       placeholder="Enter text content..."
+ *     />
+ *   </div>
+ * </div>
+ * ```
  *
  * @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
+ * - Full keyboard navigation with Tab to focus and Shift+Tab to unfocus
+ * - Screen reader compatible with proper labeling support
+ * - ARIA state management for validation (aria-invalid, aria-describedby)
+ * - Supports assistive technology form field recognition
+ * - Visible focus indicators with ring outline for keyboard users
+ * - Respects disabled and read-only states for interaction prevention
+ * - Automatic association with Label components via htmlFor/id pattern
+ * - Auto-resizing maintains proper focus and scroll position
+ * - Character limits announced to screen readers when using aria-describedby
+ * - Spell checking integration with assistive technologies
+ *
+ * @behavior
+ * - Auto-resizing based on content using CSS field-sizing property
+ * - Smooth transitions for focus states and validation changes
+ * - Native browser resize handle (unless overridden with CSS resize property)
+ * - Form validation integration with HTML5 constraint validation API
+ * - Clipboard operations (cut, copy, paste) work as expected
+ * - Text selection and manipulation using standard keyboard shortcuts
+ *
+ * @styling
+ * - Base styles provide consistent appearance across form elements
+ * - Focus-visible styles with ring and border color changes
+ * - Error state styling via aria-invalid attribute with destructive colors
+ * - Dark mode support with appropriate background and text colors
+ * - Shadow and border transitions for interactive feedback
+ * - Disabled state with reduced opacity and pointer-events disabled
  *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea} MDN textarea documentation
  * @see {@link https://ui.shadcn.com/docs/components/textarea} shadcn/ui Textarea documentation
+ * @see {@link Label} For proper labeling and accessibility association
+ * @see {@link Input} Single-line text input alternative
  * @since 1.0.0
  */
 function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {