@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/switch.tsx

@@ -4,27 +4,61 @@ import * as SwitchPrimitive from "@radix-ui/react-switch";
 import { cn } from "@/lib/utils";
 
 /**
- * Switch component for binary toggle controls
+ * Props for Switch (Documentation only - NOT used in component implementation)
  *
- * A versatile toggle switch component built on Radix UI primitives that provides
+ * A comprehensive interface documenting all available props for the Switch component.
+ * Built on Radix UI Switch primitive, providing binary toggle functionality with
+ * full form integration, accessibility support, and state management capabilities.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SwitchDocsProps = {
+  /** Whether the switch is currently checked (controlled state) @default undefined */
+  checked?: boolean;
+  /** The initial checked state when uncontrolled @default false */
+  defaultChecked?: boolean;
+  /** Event handler called when the checked state changes @param checked - The new checked state */
+  onCheckedChange?: (checked: boolean) => void;
+  /** Whether the switch is disabled and cannot be interacted with @default false */
+  disabled?: boolean;
+  /** Whether the switch is required in form validation @default false */
+  required?: boolean;
+  /** The name attribute for form submission @default undefined */
+  name?: string;
+  /** The value attribute for form submission @default "on" */
+  value?: string;
+  /** The HTML id attribute for associating with labels @default undefined */
+  id?: string;
+  /** Render as child element, merging props and behavior @default false */
+  asChild?: boolean;
+  /** Additional CSS classes to apply to the switch */
+  className?: string;
+} & React.ComponentProps<typeof SwitchPrimitive.Root>;
+
+/**
+ * Switch - Binary toggle control for on/off states
+ *
+ * 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
@@ -34,9 +68,8 @@ import { cn } from "@/lib/utils";
  * />
  * ```
  *
- * @example
+ * @example Switch with custom handler
  * ```tsx
- * // Switch with custom handler
  * <Switch
  *   checked={isDarkMode}
  *   onCheckedChange={(checked) => {
@@ -46,44 +79,50 @@ import { cn } from "@/lib/utils";
  * />
  * ```
  *
- * @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>;
-
-function Switch({ className, ...props }: SwitchProps) {
+function Switch({
+  className,
+  ...props
+}: React.ComponentProps<typeof SwitchPrimitive.Root>) {
   return (
     <SwitchPrimitive.Root
       data-slot="switch"

package/src/components/ui/table.tsx

@@ -2,6 +2,142 @@ import * as React from "react";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * Props for Table component (Documentation only - NOT used in component implementation)
+ *
+ * Main container for table data with responsive horizontal scrolling.
+ * Built on semantic HTML table element with accessibility features.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TableDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Table content including headers, body, and footer */
+  children?: React.ReactNode;
+  /** Table summary for accessibility @default undefined */
+  summary?: string;
+  /** ARIA label for the table @default undefined */
+  "aria-label"?: string;
+  /** ARIA described by reference @default undefined */
+  "aria-describedby"?: string;
+  /** Role override for table semantics @default "table" */
+  role?: string;
+} & React.ComponentProps<"table">;
+
+/**
+ * Props for TableHeader component (Documentation only - NOT used in component implementation)
+ *
+ * Container for table header rows with proper semantic structure.
+ * Groups column headers for screen reader navigation.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TableHeaderDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Header rows containing TableHead cells */
+  children?: React.ReactNode;
+} & React.ComponentProps<"thead">;
+
+/**
+ * Props for TableBody component (Documentation only - NOT used in component implementation)
+ *
+ * Main content container for table data rows. Contains all data content
+ * with proper border styling and row management.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TableBodyDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Data rows containing TableCell elements */
+  children?: React.ReactNode;
+} & React.ComponentProps<"tbody">;
+
+/**
+ * Props for TableFooter component (Documentation only - NOT used in component implementation)
+ *
+ * Container for table footer rows containing summary information, totals,
+ * or additional context. Visually distinct from body content.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TableFooterDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Footer rows containing summary or total information */
+  children?: React.ReactNode;
+} & React.ComponentProps<"tfoot">;
+
+/**
+ * Props for TableRow component (Documentation only - NOT used in component implementation)
+ *
+ * Individual row container with interactive states. Supports selection
+ * and hover effects with smooth transitions.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TableRowDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Table cells or header cells */
+  children?: React.ReactNode;
+  /** Selection state for visual feedback @default undefined */
+  "data-state"?: "selected" | "unselected";
+} & React.ComponentProps<"tr">;
+
+/**
+ * Props for TableHead component (Documentation only - NOT used in component implementation)
+ *
+ * Column header cell with proper accessibility attributes. Provides
+ * context for screen reader navigation and sortable interactions.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TableHeadDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Column header content, can include text, buttons, or interactive elements */
+  children?: React.ReactNode;
+  /** Defines header scope for accessibility @default undefined */
+  scope?: "col" | "row" | "colgroup" | "rowgroup";
+  /** Column span for grouped headers @default 1 */
+  colSpan?: number;
+  /** Row span for multi-level headers @default 1 */
+  rowSpan?: number;
+  /** Sort direction indicator for sortable columns @default undefined */
+  "aria-sort"?: "ascending" | "descending" | "none" | "other";
+} & React.ComponentProps<"th">;
+
+/**
+ * Props for TableCell component (Documentation only - NOT used in component implementation)
+ *
+ * Data cell component with flexible content support and spanning capabilities.
+ * Handles text, components, and interactive elements with proper alignment.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TableCellDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Cell content including text, components, or interactive elements */
+  children?: React.ReactNode;
+  /** Number of columns this cell should span @default 1 */
+  colSpan?: number;
+  /** Number of rows this cell should span @default 1 */
+  rowSpan?: number;
+  /** Header association for complex tables @default undefined */
+  headers?: string;
+} & React.ComponentProps<"td">;
+
+/**
+ * Props for TableCaption component (Documentation only - NOT used in component implementation)
+ *
+ * Descriptive caption for table content and context. Essential for
+ * accessibility and provides overview of table purpose.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TableCaptionDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Caption text or content describing the table */
+  children?: React.ReactNode;
+} & React.ComponentProps<"caption">;
+
 /**
  * Table - A responsive data table component for displaying structured information
  *
@@ -81,6 +217,28 @@ import { cn } from "@/lib/utils";
  * </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
@@ -88,14 +246,19 @@ import { cn } from "@/lib/utils";
  * - 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
  */
 function Table({ className, ...props }: React.ComponentProps<"table">) {
@@ -254,6 +417,9 @@ function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
  * - 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
  */
 function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
@@ -299,6 +465,9 @@ 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
  */
 function TableHead({ className, ...props }: React.ComponentProps<"th">) {
@@ -399,10 +568,7 @@ function TableCell({ className, ...props }: React.ComponentProps<"td">) {
  * - Helps users understand table purpose and scope
  * @since 1.0.0
  */
-function TableCaption({
-  className,
-  ...props
-}: React.ComponentProps<"caption">) {
+function TableCaption({ className, ...props }: React.ComponentProps<"caption">) {
   return (
     <caption
       data-slot="table-caption"

package/src/components/ui/tabs.tsx

@@ -3,6 +3,110 @@ import * as TabsPrimitive from "@radix-ui/react-tabs";
 
 import { cn } from "@/lib/utils";
 
+// ============================================================================
+// DOCUMENTATION-ONLY PROP TYPES (Internal - Not exported)
+// ============================================================================
+
+/**
+ * Props for Tabs (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 TabsDocsProps = {
+  /** The initial active tab value (uncontrolled usage). Use when you do not need to control the state of the tabs */
+  defaultValue?: string;
+  /** The currently active tab value (controlled usage). Should be used in conjunction with onValueChange */
+  value?: string;
+  /** Callback fired when the active tab changes
+   * @param value - The new active tab value
+   */
+  onValueChange?: (value: string) => void;
+  /** Layout direction of the tabs
+   * @default "horizontal"
+   */
+  orientation?: "horizontal" | "vertical";
+  /** Text direction for RTL support. If omitted, inherits globally from DirectionProvider or assumes LTR
+   * @default "ltr"
+   */
+  dir?: "ltr" | "rtl";
+  /** When tabs activate: "automatic" (on focus) or "manual" (on click/enter)
+   * @default "automatic"
+   */
+  activationMode?: "automatic" | "manual";
+  /** Additional CSS classes for styling */
+  className?: string;
+  /** Tab list, content panels, and other child elements */
+  children?: React.ReactNode;
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior
+   * @default false
+   */
+  asChild?: boolean;
+} & React.ComponentProps<typeof TabsPrimitive.Root>;
+
+/**
+ * Props for TabsList (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 TabsListDocsProps = {
+  /** When true, keyboard navigation will loop from last tab to first, and vice versa
+   * @default true
+   */
+  loop?: boolean;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** TabsTrigger components to be grouped */
+  children?: React.ReactNode;
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior
+   * @default false
+   */
+  asChild?: boolean;
+} & React.ComponentProps<typeof TabsPrimitive.List>;
+
+/**
+ * Props for TabsTrigger (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 TabsTriggerDocsProps = {
+  /** Unique identifier that associates this trigger with its content panel */
+  value: string;
+  /** When true, prevents interaction and shows disabled styling
+   * @default false
+   */
+  disabled?: boolean;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Content to display within the trigger (text, icons, etc.) */
+  children?: React.ReactNode;
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior
+   * @default false
+   */
+  asChild?: boolean;
+} & React.ComponentProps<typeof TabsPrimitive.Trigger>;
+
+/**
+ * Props for TabsContent (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 TabsContentDocsProps = {
+  /** Unique identifier that associates this content with its trigger */
+  value: string;
+  /** When true, content stays mounted even when inactive (useful for preserving state)
+   * @default false
+   */
+  forceMount?: boolean;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** The content to display when this tab is active */
+  children?: React.ReactNode;
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior
+   * @default false
+   */
+  asChild?: boolean;
+} & React.ComponentProps<typeof TabsPrimitive.Content>;
+
 /**
  * A tabbed interface component for organizing content into multiple sections.
  *
@@ -87,21 +191,13 @@ import { cn } from "@/lib/utils";
  * </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
@@ -160,13 +256,11 @@ function Tabs({
  * </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
  */
@@ -213,17 +307,13 @@ function TabsList({
  * </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
  */
@@ -287,16 +377,12 @@ function TabsTrigger({
  * </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
  */