@neynar/ui 0.1.1 → 0.1.2

package/dist/components/ui/switch.d.ts

@@ -1,27 +1,30 @@
 import * as React from "react";
 import * as SwitchPrimitive from "@radix-ui/react-switch";
 /**
- * Switch component for binary toggle controls
+ * Switch - Binary toggle control for on/off states
  *
- * A versatile toggle switch component built on Radix UI primitives that provides
+ * A versatile toggle switch component built on Radix UI Switch primitive that provides
  * an accessible way to toggle between on/off states. Commonly used for settings,
  * preferences, and feature toggles that have immediate effects.
  *
  * Built with Radix UI Switch primitive and styled with Tailwind CSS to ensure
- * consistent visual appearance across light and dark themes.
+ * consistent visual appearance across light and dark themes. The component
+ * automatically handles state management, accessibility, keyboard navigation,
+ * and form integration.
  *
- * @example
+ * @example Basic usage with label
  * ```tsx
- * // Basic usage with label
+ * import { Switch } from "@/components/ui/switch";
+ * import { Label } from "@/components/ui/label";
+ *
  * <div className="flex items-center space-x-2">
  *   <Switch id="airplane-mode" />
  *   <Label htmlFor="airplane-mode">Airplane Mode</Label>
  * </div>
  * ```
  *
- * @example
+ * @example Controlled switch with state
  * ```tsx
- * // Controlled switch with state
  * const [enabled, setEnabled] = useState(false);
  *
  * <Switch
@@ -31,9 +34,8 @@ import * as SwitchPrimitive from "@radix-ui/react-switch";
  * />
  * ```
  *
- * @example
+ * @example Switch with custom handler
  * ```tsx
- * // Switch with custom handler
  * <Switch
  *   checked={isDarkMode}
  *   onCheckedChange={(checked) => {
@@ -43,42 +45,46 @@ import * as SwitchPrimitive from "@radix-ui/react-switch";
  * />
  * ```
  *
- * @example
+ * @example Disabled states
+ * ```tsx
+ * <Switch disabled /> // Disabled unchecked
+ * <Switch disabled defaultChecked /> // Disabled checked
+ * ```
+ *
+ * @example Form integration with validation
+ * ```tsx
+ * <form>
+ *   <Switch
+ *     name="notifications"
+ *     value="enabled"
+ *     required
+ *     onCheckedChange={(checked) => console.log('Notifications:', checked)}
+ *   />
+ * </form>
+ * ```
+ *
+ * @example Uncontrolled with default state
  * ```tsx
- * // Disabled switch
- * <Switch disabled />
- * <Switch disabled defaultChecked />
+ * <Switch defaultChecked onCheckedChange={(checked) => {
+ *   // Handle state changes without controlling the value
+ *   analytics.track('switch_toggled', { checked });
+ * }} />
  * ```
  *
  * @accessibility
- * - Fully keyboard accessible with Space and Enter key support
- * - ARIA attributes automatically managed by Radix UI
- * - Screen reader announcements for state changes
- * - Focus indicator with visible ring
- * - Associates with labels via htmlFor/id pairing
- * - Disabled state properly communicated to assistive technology
- * - Follows WAI-ARIA Switch pattern
+ * - **Keyboard Navigation**: Space and Enter keys toggle the switch
+ * - **Focus Management**: Clear focus ring indicator with keyboard navigation
+ * - **Screen Readers**: Announces current state ("on" or "off") and changes
+ * - **ARIA Compliance**: Follows WAI-ARIA Switch pattern with proper role and attributes
+ * - **Label Association**: Works with labels via htmlFor/id pairing for proper announcements
+ * - **Form Integration**: Properly participates in form submission and validation
+ * - **Disabled State**: Clearly communicated to assistive technology with proper attributes
+ * - **State Attributes**: Uses data-state for styling and accessibility context
  *
  * @see {@link https://ui.shadcn.com/docs/components/switch} shadcn/ui Switch documentation
- * @since 1.0.0
  * @see {@link https://www.radix-ui.com/primitives/docs/components/switch} Radix UI Switch primitive
+ * @since 1.0.0
  */
-/**
- * Switch component props
- *
- * Extends all props from Radix UI Switch Root primitive, including:
- * - `checked` - The controlled checked state of the switch
- * - `defaultChecked` - The default checked state when uncontrolled
- * - `onCheckedChange` - Event handler called when the checked state changes
- * - `disabled` - Whether the switch is disabled
- * - `required` - Whether the switch is required in forms
- * - `name` - Name attribute for form submission
- * - `value` - Value attribute for form submission
- *
- * @param className - Additional CSS classes to apply to the switch
- * @param props - All other props from Radix UI Switch Root
- */
-type SwitchProps = React.ComponentProps<typeof SwitchPrimitive.Root>;
-declare function Switch({ className, ...props }: SwitchProps): import("react/jsx-runtime").JSX.Element;
+declare function Switch({ className, ...props }: React.ComponentProps<typeof SwitchPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
 export { Switch };
 //# sourceMappingURL=switch.d.ts.map

package/dist/components/ui/switch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"switch.d.ts","sourceRoot":"","sources":["../../../src/components/ui/switch.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,eAAe,MAAM,wBAAwB,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH;;;;;;;;;;;;;;GAcG;AACH,KAAK,WAAW,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;AAErE,iBAAS,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,WAAW,2CAkBnD;AAED,OAAO,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"switch.d.ts","sourceRoot":"","sources":["../../../src/components/ui/switch.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,eAAe,MAAM,wBAAwB,CAAC;AAmC1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AACH,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,IAAI,CAAC,2CAkBnD;AAED,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/components/ui/table.d.ts

@@ -78,6 +78,28 @@ import * as React from "react";
  * </Table>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Table with custom attributes for data integration
+ * <Table role="table" aria-label="User analytics dashboard">
+ *   <TableCaption>Showing 1-10 of 50 users</TableCaption>
+ *   <TableHeader>
+ *     <TableRow>
+ *       <TableHead scope="col">User</TableHead>
+ *       <TableHead scope="col">FID</TableHead>
+ *       <TableHead scope="col" className="text-right">Casts</TableHead>
+ *     </TableRow>
+ *   </TableHeader>
+ *   <TableBody>
+ *     <TableRow data-user-id="3">
+ *       <TableCell>@dwr.eth</TableCell>
+ *       <TableCell>3</TableCell>
+ *       <TableCell className="text-right">1,234</TableCell>
+ *     </TableRow>
+ *   </TableBody>
+ * </Table>
+ * ```
+ *
  * @accessibility
  * - Semantic HTML table structure with thead, tbody, tfoot elements
  * - Screen reader navigation with proper table headers and data relationships
@@ -85,14 +107,19 @@ import * as React from "react";
  * - Caption support for table descriptions and context
  * - Selection states communicated via data-state attributes
  * - Keyboard navigation support for interactive elements
+ * - TableHead components automatically provide column context for screen readers
+ * - Table container ensures content remains accessible during horizontal scroll
  *
  * @see {@link https://ui.shadcn.com/docs/components/table} shadcn/ui Table documentation
  * @see {@link https://ui.shadcn.com/docs/components/data-table} TanStack Table integration
+ * @see {@link https://tanstack.com/table} TanStack Table library for advanced features
  * @see {@link TableHeader} Table header container component
  * @see {@link TableBody} Table body container component
  * @see {@link TableRow} Table row component with hover and selection states
  * @see {@link TableCell} Table data cell component
  * @see {@link TableHead} Table header cell component
+ * @see {@link TableFooter} Table footer container for summary data
+ * @see {@link TableCaption} Table caption component for descriptions
  * @since 1.0.0
  */
 declare function Table({ className, ...props }: React.ComponentProps<"table">): import("react/jsx-runtime").JSX.Element;
@@ -207,6 +234,9 @@ declare function TableFooter({ className, ...props }: React.ComponentProps<"tfoo
  * - Hover state enhances interactivity and focus
  * - Semantic tr element maintains table structure
  * - Visual feedback for user interactions
+ * - Compatible with keyboard navigation patterns
+ * - Selection state changes are announced to screen readers
+ * - Transition animations provide smooth visual feedback
  * @since 1.0.0
  */
 declare function TableRow({ className, ...props }: React.ComponentProps<"tr">): import("react/jsx-runtime").JSX.Element;
@@ -240,6 +270,9 @@ declare function TableRow({ className, ...props }: React.ComponentProps<"tr">):
  * - Screen readers announce as column headers for navigation
  * - Supports scope attribute for complex table relationships
  * - Special checkbox styling maintains proper alignment
+ * - Automatically provides column context for data cells
+ * - Works with sorting and filtering interaction patterns
+ * - Maintains proper focus order for keyboard navigation
  * @since 1.0.0
  */
 declare function TableHead({ className, ...props }: React.ComponentProps<"th">): import("react/jsx-runtime").JSX.Element;

package/dist/components/ui/table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../src/components/ui/table.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+FG;AACH,iBAAS,KAAK,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,2CAapE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,2CAQ1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,2CAQxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,2CAW1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,iBAAS,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,2CAWpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,2CAWrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,2CAWrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,iBAAS,YAAY,CAAC,EACpB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC,2CAQjC;AAED,OAAO,EACL,KAAK,EACL,WAAW,EACX,SAAS,EACT,WAAW,EACX,SAAS,EACT,QAAQ,EACR,SAAS,EACT,YAAY,GACb,CAAC"}
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../src/components/ui/table.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA4I/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0HG;AACH,iBAAS,KAAK,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,2CAapE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,2CAQ1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,2CAQxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,2CAW1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,iBAAS,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,2CAWpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,2CAWrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,2CAWrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,iBAAS,YAAY,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC,2CAQ7E;AAED,OAAO,EACL,KAAK,EACL,WAAW,EACX,SAAS,EACT,WAAW,EACX,SAAS,EACT,QAAQ,EACR,SAAS,EACT,YAAY,GACb,CAAC"}

package/dist/components/ui/tabs.d.ts

@@ -84,21 +84,13 @@ import * as TabsPrimitive from "@radix-ui/react-tabs";
  * </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
+ * - **Activation Modes**: Automatic (focus) or manual (click/enter) activation patterns
  *
  * @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
@@ -145,13 +137,11 @@ declare function Tabs({ className, ...props }: React.ComponentProps<typeof TabsP
  * </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
+ * - Loop navigation when enabled (default: true)
  *
  * @since 1.0.0
  */
@@ -183,17 +173,13 @@ declare function TabsList({ className, ...props }: React.ComponentProps<typeof T
  * </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
+ * - Data attributes: [data-state], [data-disabled], [data-orientation]
  *
  * @since 1.0.0
  */
@@ -242,16 +228,12 @@ declare function TabsTrigger({ className, ...props }: React.ComponentProps<typeo
  * </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
+ * - Supports forceMount for animation control
  *
  * @since 1.0.0
  */

package/dist/components/ui/tabs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tabs.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,aAAa,MAAM,sBAAsB,CAAC;AAItD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0GG;AACH,iBAAS,IAAI,CAAC,EACZ,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,aAAa,CAAC,IAAI,CAAC,2CAQjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,iBAAS,QAAQ,CAAC,EAChB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,aAAa,CAAC,IAAI,CAAC,2CAWjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,iBAAS,WAAW,CAAC,EACnB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,aAAa,CAAC,OAAO,CAAC,2CAWpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,iBAAS,WAAW,CAAC,EACnB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,aAAa,CAAC,OAAO,CAAC,2CAQpD;AAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tabs.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,aAAa,MAAM,sBAAsB,CAAC;AA4GtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkGG;AACH,iBAAS,IAAI,CAAC,EACZ,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,aAAa,CAAC,IAAI,CAAC,2CAQjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,iBAAS,QAAQ,CAAC,EAChB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,aAAa,CAAC,IAAI,CAAC,2CAWjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,iBAAS,WAAW,CAAC,EACnB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,aAAa,CAAC,OAAO,CAAC,2CAWpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,iBAAS,WAAW,CAAC,EACnB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,aAAa,CAAC,OAAO,CAAC,2CAQpD;AAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC"}

package/dist/components/ui/text-field.d.ts

@@ -1,100 +1,75 @@
 import * as React from "react";
-/**
- * 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.
-     */
+import { Input } from "./input";
+type TextFieldProps = {
     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;
-};
+    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("");
  *   }
@@ -108,50 +83,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
+ * ```tsx
+ * // Number input with constraints
+ * <TextField
+ *   label="Age"
+ *   type="number"
+ *   min={0}
+ *   max={120}
+ *   step={1}
+ *   helperText="Enter your age in years"
+ *   placeholder="25"
  * />
  * ```
  *
- * @example Form integration
+ * @example
  * ```tsx
- * <form onSubmit={handleSubmit}>
+ * // 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
+ * />
+ * ```
  *
- * - **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
+ * @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
  *
- * ## Styling & Variants
+ * @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
  *
- * 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
+ * ## Component Composition
  *
- * @see {@link Input} The underlying input component
- * @see {@link Label} The label component used for field labels
- * @since 1.0.0 */
+ * 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
+ *
+ * ## Input Type Support
+ *
+ * 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
+ */
 declare const TextField: React.ForwardRefExoticComponent<Omit<TextFieldProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
 export { TextField };
 //# sourceMappingURL=text-field.d.ts.map

package/dist/components/ui/text-field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text-field.d.ts","sourceRoot":"","sources":["../../../src/components/ui/text-field.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,GAAG;IACvE;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA0GkB;AAClB,QAAA,MAAM,SAAS,sGA0Cd,CAAC;AAIF,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"text-field.d.ts","sourceRoot":"","sources":["../../../src/components/ui/text-field.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AA+DhC,KAAK,cAAc,GAAG;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,KAAK,CAAC,EAAE,WAAW,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsOG;AACH,QAAA,MAAM,SAAS,sGA0Cd,CAAC;AAIF,OAAO,EAAE,SAAS,EAAE,CAAC"}