@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/input.tsx

@@ -3,88 +3,251 @@ import * as React from "react";
 import { cn } from "@/lib/utils";
 
 /**
- * A form input field component that displays text input or input-like elements
+ * Props for Input component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace HTML input inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type InputDocsProps = {
+  /** The type of input field to render - supports all HTML input types @default "text" */
+  type?: React.HTMLInputTypeAttribute;
+  /** Placeholder text displayed when the input is empty */
+  placeholder?: string;
+  /** Current value of the input (controlled component) */
+  value?: string | ReadonlyArray<string> | number;
+  /** Default value for uncontrolled usage */
+  defaultValue?: string | ReadonlyArray<string> | number;
+  /** Whether the input is disabled and non-interactive @default false */
+  disabled?: boolean;
+  /** Whether the input is required for form validation @default false */
+  required?: boolean;
+  /** Whether the input is read-only (visible but not editable) @default false */
+  readOnly?: boolean;
+  /** Unique identifier for the input element (important for accessibility) */
+  id?: string;
+  /** Name attribute for form submission and validation */
+  name?: string;
+  /** Auto-complete hint for browsers to improve form filling experience */
+  autoComplete?: string;
+  /** Whether to focus this input when the component mounts @default false */
+  autoFocus?: boolean;
+  /** Maximum number of characters allowed in text inputs */
+  maxLength?: number;
+  /** Minimum number of characters required in text inputs */
+  minLength?: number;
+  /** Pattern attribute for client-side validation using regular expressions */
+  pattern?: string;
+  /** Minimum value for numeric input types (number, range, date, etc.) */
+  min?: string | number;
+  /** Maximum value for numeric input types (number, range, date, etc.) */
+  max?: string | number;
+  /** Step value for numeric inputs (affects increment/decrement behavior) */
+  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 pressed up */
+  onKeyUp?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+  /** Indicates whether the input has a validation error @default false */
+  "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling";
+  /** Describes the input for screen readers and assistive technology */
+  "aria-describedby"?: string;
+  /** Labels the input for screen readers (use with Label component's htmlFor) */
+  "aria-labelledby"?: string;
+  /** Provides an accessible label when no visible label is present */
+  "aria-label"?: string;
+  /** Whether the input is required (for screen readers) */
+  "aria-required"?: boolean | "false" | "true";
+  /** Additional CSS classes for custom styling */
+  className?: string;
+} & React.InputHTMLAttributes<HTMLInputElement>;
+
+/**
+ * Input - Versatile form input component for text, email, password, and other input types
  *
- * 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.
+ * A flexible and accessible input component built on native HTML input elements with enhanced
+ * styling and form integration capabilities. Supports all HTML input types including text, email,
+ * password, number, file, date, and more. Features consistent design tokens, error states, focus
+ * management, and seamless integration with form libraries like React Hook Form.
  *
  * @example
  * ```tsx
- * // Basic email input
- * <Input type="email" placeholder="Email" />
+ * // Basic text input
+ * <Input type="text" placeholder="Enter your name" />
  * ```
  *
  * @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" />
+ * // Email input with validation
+ * <Input
+ *   type="email"
+ *   placeholder="your@email.com"
+ *   required
+ *   aria-describedby="email-error"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Password input with toggle visibility
+ * <div className="relative">
+ *   <Input
+ *     type="password"
+ *     placeholder="Enter password"
+ *     autoComplete="current-password"
+ *   />
+ *   <Button
+ *     type="button"
+ *     variant="ghost"
+ *     size="sm"
+ *     className="absolute right-0 top-0 h-full px-3"
+ *   >
+ *     <Eye className="h-4 w-4" />
+ *   </Button>
  * </div>
  * ```
  *
  * @example
  * ```tsx
+ * // Number input with min/max constraints
+ * <Input
+ *   type="number"
+ *   placeholder="Age"
+ *   min={0}
+ *   max={120}
+ *   step={1}
+ * />
+ * ```
+ *
+ * @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" />
+ *   <Label htmlFor="picture">Profile Picture</Label>
+ *   <Input
+ *     id="picture"
+ *     type="file"
+ *     accept="image/*"
+ *     aria-describedby="file-help"
+ *   />
+ *   <p id="file-help" className="text-sm text-muted-foreground">
+ *     Upload a PNG, JPG or GIF (max 5MB)
+ *   </p>
  * </div>
  * ```
  *
  * @example
  * ```tsx
- * // Disabled input state
- * <Input disabled type="email" placeholder="Email" />
+ * // Search input with icon
+ * <div className="relative">
+ *   <Search className="absolute left-2 top-1/2 h-4 w-4 -translate-y-1/2 transform text-muted-foreground" />
+ *   <Input
+ *     type="search"
+ *     placeholder="Search..."
+ *     className="pl-8"
+ *   />
+ * </div>
  * ```
  *
  * @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>
+ * // Input with error state
+ * <div className="space-y-2">
+ *   <Label htmlFor="email">Email</Label>
+ *   <Input
+ *     id="email"
+ *     type="email"
+ *     aria-invalid={true}
+ *     aria-describedby="email-error"
+ *   />
+ *   <p id="email-error" className="text-sm text-destructive">
+ *     Please enter a valid email address
+ *   </p>
  * </div>
  * ```
  *
  * @example
  * ```tsx
  * // Form integration with React Hook Form
- * const form = useForm();
+ * const { register, formState: { errors } } = useForm();
  *
- * <Form>
- *   <FormField
- *     control={form.control}
- *     name="email"
- *     render={({ field }) => (
- *       <FormItem>
- *         <FormLabel>Email</FormLabel>
- *         <FormControl>
- *           <Input placeholder="shadcn" {...field} />
- *         </FormControl>
- *         <FormMessage />
- *       </FormItem>
- *     )}
+ * <div className="space-y-2">
+ *   <Label htmlFor="username">Username</Label>
+ *   <Input
+ *     id="username"
+ *     {...register("username", { required: "Username is required" })}
+ *     aria-invalid={!!errors.username}
+ *     aria-describedby={errors.username ? "username-error" : undefined}
  *   />
- * </Form>
+ *   {errors.username && (
+ *     <p id="username-error" className="text-sm text-destructive">
+ *       {errors.username.message}
+ *     </p>
+ *   )}
+ * </div>
  * ```
  *
- * @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
+ * @example
+ * ```tsx
+ * // Input with button (subscription form)
+ * <div className="flex w-full max-w-sm items-center space-x-2">
+ *   <Input
+ *     type="email"
+ *     placeholder="Enter your email"
+ *     aria-label="Email for newsletter"
+ *   />
+ *   <Button type="submit">Subscribe</Button>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled input with explanation
+ * <div className="space-y-2">
+ *   <Label htmlFor="readonly-field">System Generated ID</Label>
+ *   <Input
+ *     id="readonly-field"
+ *     value="SYS-12345"
+ *     disabled
+ *     aria-describedby="readonly-help"
+ *   />
+ *   <p id="readonly-help" className="text-sm text-muted-foreground">
+ *     This value is automatically generated and cannot be edited
+ *   </p>
+ * </div>
+ * ```
  *
  * @accessibility
- * - Supports all ARIA attributes including aria-invalid for error states
- * - Focus visible ring with proper contrast for keyboard navigation
+ * - Provides proper focus management with visible focus ring (focus-visible:ring-ring/50)
+ * - Supports all ARIA attributes including aria-invalid for error state indication
  * - Compatible with screen readers and assistive technologies
- * - Proper semantic markup for form fields
- * - Disabled state prevents interaction and indicates unavailability
+ * - Maintains proper tab order and keyboard navigation patterns
+ * - Disabled state prevents interaction and is announced to screen readers
+ * - File inputs provide accessible file selection with proper labeling
+ * - Error states are properly associated with inputs via aria-describedby
+ * - Required fields can be marked with aria-required for screen reader users
+ * - Placeholder text provides input guidance but doesn't replace proper labels
+ * - Text selection has optimized contrast with custom selection colors
+ *
+ * @styling
+ * - Uses consistent design tokens from the design system
+ * - Adaptive height (h-9) with responsive text sizing (md:text-sm)
+ * - Smooth transitions for focus states and interactions
+ * - Custom file input styling that matches the design system
+ * - Error state styling with destructive border and focus ring colors
+ * - Dark mode support with semi-transparent background (dark:bg-input/30)
+ * - Proper spacing and typography hierarchy for form layouts
  *
- * @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
+ * @see {@link https://ui.shadcn.com/docs/components/input} shadcn/ui Input documentation
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input} MDN Input element reference
+ * @see {@link Label} For accessible input labels and proper association
+ * @see {@link Button} Often used alongside inputs in forms and search interfaces
+ * @see {@link Form} Complete form integration with validation and error handling
+ * @see {@link Textarea} For multi-line text input needs
  * @since 1.0.0
  */
 function Input({ className, type, ...props }: React.ComponentProps<"input">) {

package/src/components/ui/label.tsx

@@ -3,6 +3,104 @@ import * as LabelPrimitive from "@radix-ui/react-label";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * Props for Label (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type LabelDocsProps = {
+  /**
+   * Additional CSS classes to apply to the label element.
+   * Merged with default styling using cn() utility.
+   * @example className="text-lg font-bold"
+   */
+  className?: string;
+
+  /**
+   * The id of the form control this label is associated with.
+   * Creates semantic association between label and control for accessibility.
+   * When clicked, will focus the associated form element.
+   * @example htmlFor="email-input"
+   */
+  htmlFor?: string;
+
+  /**
+   * The content to display inside the label.
+   * Can be text, React elements, or other components.
+   * @example children="Email Address"
+   */
+  children?: React.ReactNode;
+
+  /**
+   * When true, merges props and behavior with the child element instead of rendering a label.
+   * Useful for composition with other components while maintaining label semantics.
+   * @default false
+   * @example <Label asChild><Text>Custom Label</Text></Label>
+   */
+  asChild?: boolean;
+
+  /**
+   * Event handler called when the label is clicked.
+   * The associated form control will also receive focus automatically.
+   * @param event - The mouse event
+   */
+  onClick?: React.MouseEventHandler<HTMLLabelElement>;
+
+  /**
+   * Event handler called when a key is pressed while the label has focus.
+   * @param event - The keyboard event
+   */
+  onKeyDown?: React.KeyboardEventHandler<HTMLLabelElement>;
+
+  /**
+   * Unique identifier for the label element.
+   * Different from htmlFor, which references the associated control's id.
+   * @example id="username-label"
+   */
+  id?: string;
+
+  /**
+   * Inline styles to apply to the label element.
+   * @example style={{ color: 'red', fontWeight: 'bold' }}
+   */
+  style?: React.CSSProperties;
+
+  /**
+   * The tab index of the label element.
+   * Generally not needed as labels are not typically focusable.
+   * @default undefined
+   */
+  tabIndex?: number;
+
+  /**
+   * ARIA label for the element when the content is not descriptive enough.
+   * Provides accessible name when children contain only icons or symbols.
+   * @example aria-label="Required field"
+   */
+  "aria-label"?: string;
+
+  /**
+   * References to other elements that describe this label.
+   * Space-separated list of element IDs.
+   * @example aria-describedby="help-text error-message"
+   */
+  "aria-describedby"?: string;
+
+  /**
+   * Indicates if the associated form control has an error.
+   * Used by screen readers to announce validation state.
+   * @example aria-invalid={hasError}
+   */
+  "aria-invalid"?: boolean;
+
+  /**
+   * Indicates if the associated form control is required.
+   * Announces to screen readers that the field must be filled.
+   * @example aria-required={true}
+   */
+  "aria-required"?: boolean;
+} & React.HTMLAttributes<HTMLLabelElement>;
+
 /**
  * Label component for form controls with full accessibility support
  *
@@ -83,14 +181,6 @@ import { cn } from "@/lib/utils";
  * @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