@neynar/ui 0.1.1

package/src/components/ui/table.tsx

@@ -0,0 +1,424 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Table - A responsive data table component for displaying structured information
+ *
+ * Built on semantic HTML table elements with responsive scrolling and proper accessibility.
+ * Follows shadcn/ui patterns for data presentation and can be enhanced with TanStack Table
+ * for sorting, filtering, and pagination. Perfect for dashboards, data management, and
+ * structured content display.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic table with Farcaster user data
+ * <Table>
+ *   <TableCaption>Recent casts from your network</TableCaption>
+ *   <TableHeader>
+ *     <TableRow>
+ *       <TableHead>User</TableHead>
+ *       <TableHead>Channel</TableHead>
+ *       <TableHead>Content</TableHead>
+ *       <TableHead className="text-right">Reactions</TableHead>
+ *     </TableRow>
+ *   </TableHeader>
+ *   <TableBody>
+ *     <TableRow>
+ *       <TableCell className="font-medium">@dwr.eth</TableCell>
+ *       <TableCell>/farcaster</TableCell>
+ *       <TableCell>Announcing Farcaster v2...</TableCell>
+ *       <TableCell className="text-right">1,234</TableCell>
+ *     </TableRow>
+ *   </TableBody>
+ * </Table>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Table with selection and actions
+ * <Table>
+ *   <TableHeader>
+ *     <TableRow>
+ *       <TableHead className="w-[50px]">
+ *         <Checkbox />
+ *       </TableHead>
+ *       <TableHead>User</TableHead>
+ *       <TableHead>FID</TableHead>
+ *       <TableHead className="text-right">Actions</TableHead>
+ *     </TableRow>
+ *   </TableHeader>
+ *   <TableBody>
+ *     <TableRow data-state="selected">
+ *       <TableCell><Checkbox checked /></TableCell>
+ *       <TableCell>@vitalik.eth</TableCell>
+ *       <TableCell>5650</TableCell>
+ *       <TableCell className="text-right">
+ *         <Button variant="ghost" size="sm">Edit</Button>
+ *       </TableCell>
+ *     </TableRow>
+ *   </TableBody>
+ * </Table>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Table with footer totals
+ * <Table>
+ *   <TableBody>
+ *     <TableRow>
+ *       <TableCell>/farcaster</TableCell>
+ *       <TableCell className="text-right">5,234</TableCell>
+ *     </TableRow>
+ *   </TableBody>
+ *   <TableFooter>
+ *     <TableRow>
+ *       <TableCell>Total</TableCell>
+ *       <TableCell className="text-right">15,767</TableCell>
+ *     </TableRow>
+ *   </TableFooter>
+ * </Table>
+ * ```
+ *
+ * @accessibility
+ * - Semantic HTML table structure with thead, tbody, tfoot elements
+ * - Screen reader navigation with proper table headers and data relationships
+ * - Responsive horizontal scrolling container for mobile devices
+ * - Caption support for table descriptions and context
+ * - Selection states communicated via data-state attributes
+ * - Keyboard navigation support for interactive elements
+ *
+ * @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 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
+ * @since 1.0.0
+ */
+function Table({ className, ...props }: React.ComponentProps<"table">) {
+  return (
+    <div
+      data-slot="table-container"
+      className="relative w-full overflow-x-auto"
+    >
+      <table
+        data-slot="table"
+        className={cn("w-full caption-bottom text-sm", className)}
+        {...props}
+      />
+    </div>
+  );
+}
+
+/**
+ * TableHeader - Container for table header rows
+ *
+ * Groups header rows and applies consistent styling with bottom borders.
+ * Contains TableRow components with TableHead cells for column definitions.
+ * Essential for accessibility and proper table structure.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <TableHeader>
+ *   <TableRow>
+ *     <TableHead>Username</TableHead>
+ *     <TableHead>FID</TableHead>
+ *     <TableHead className="text-right">Actions</TableHead>
+ *   </TableRow>
+ * </TableHeader>
+ * ```
+ *
+ * @accessibility
+ * - Semantic thead element for proper table structure
+ * - Screen readers identify this as the table header section
+ * - Provides context for data columns below
+ * @since 1.0.0
+ */
+function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
+  return (
+    <thead
+      data-slot="table-header"
+      className={cn("[&_tr]:border-b", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * TableBody - Container for table data rows
+ *
+ * Main content area of the table containing all data rows.
+ * Applies border styling where the last row has no bottom border.
+ * Contains TableRow components with TableCell elements.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <TableBody>
+ *   <TableRow>
+ *     <TableCell>@dwr.eth</TableCell>
+ *     <TableCell>3</TableCell>
+ *     <TableCell>45.2k followers</TableCell>
+ *   </TableRow>
+ *   <TableRow>
+ *     <TableCell>@vitalik.eth</TableCell>
+ *     <TableCell>5650</TableCell>
+ *     <TableCell>112.3k followers</TableCell>
+ *   </TableRow>
+ * </TableBody>
+ * ```
+ *
+ * @accessibility
+ * - Semantic tbody element for data rows
+ * - Supports keyboard navigation through rows
+ * - Screen readers navigate row by row through content
+ * @since 1.0.0
+ */
+function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
+  return (
+    <tbody
+      data-slot="table-body"
+      className={cn("[&_tr:last-child]:border-0", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * TableFooter - Container for table footer rows
+ *
+ * Used for summary rows, totals, or additional table information.
+ * Styled with a muted background and top border to distinguish from data rows.
+ * Typically contains aggregated data or table-wide information.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <TableFooter>
+ *   <TableRow>
+ *     <TableCell>Total Users</TableCell>
+ *     <TableCell>15,767</TableCell>
+ *     <TableCell className="text-right">+9.25%</TableCell>
+ *   </TableRow>
+ * </TableFooter>
+ * ```
+ *
+ * @accessibility
+ * - Semantic tfoot element for summary data
+ * - Screen readers announce as table footer section
+ * - Distinguished visually and semantically from body content
+ * @since 1.0.0
+ */
+function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
+  return (
+    <tfoot
+      data-slot="table-footer"
+      className={cn(
+        "bg-muted/50 border-t font-medium [&>tr]:last:border-b-0",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * TableRow - A table row component with interactive states
+ *
+ * Represents a single row in the table with hover effects and selection support.
+ * Supports data-state attributes for visual feedback and proper border styling.
+ * Essential building block for all table content areas.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic row
+ * <TableRow>
+ *   <TableCell>@dwr.eth</TableCell>
+ *   <TableCell>/farcaster</TableCell>
+ * </TableRow>
+ *
+ * // Selected row
+ * <TableRow data-state="selected">
+ *   <TableCell>@vitalik.eth</TableCell>
+ *   <TableCell>/ethereum</TableCell>
+ * </TableRow>
+ * ```
+ *
+ * @accessibility
+ * - Supports data-state="selected" for selection indication
+ * - Hover state enhances interactivity and focus
+ * - Semantic tr element maintains table structure
+ * - Visual feedback for user interactions
+ * @since 1.0.0
+ */
+function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
+  return (
+    <tr
+      data-slot="table-row"
+      className={cn(
+        "hover:bg-muted/50 data-[state=selected]:bg-muted border-b transition-colors",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * TableHead - Table header cell component for column definitions
+ *
+ * Used for column headers with medium font weight and proper text alignment.
+ * Includes special styling for checkbox columns and interactive elements.
+ * Essential for screen reader navigation and table accessibility.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Text headers
+ * <TableHead>Username</TableHead>
+ * <TableHead className="text-right">Followers</TableHead>
+ *
+ * // Checkbox header
+ * <TableHead className="w-[50px]">
+ *   <Checkbox />
+ * </TableHead>
+ *
+ * // Sortable header
+ * <TableHead>
+ *   <Button variant="ghost">FID ↕</Button>
+ * </TableHead>
+ * ```
+ *
+ * @accessibility
+ * - Semantic th element for column headers
+ * - Screen readers announce as column headers for navigation
+ * - Supports scope attribute for complex table relationships
+ * - Special checkbox styling maintains proper alignment
+ * @since 1.0.0
+ */
+function TableHead({ className, ...props }: React.ComponentProps<"th">) {
+  return (
+    <th
+      data-slot="table-head"
+      className={cn(
+        "text-foreground h-10 px-2 text-left align-middle font-medium whitespace-nowrap [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * TableCell - Table data cell component for content display
+ *
+ * Used for data cells within table rows with consistent padding and alignment.
+ * Supports custom styling, truncation, and special handling for interactive elements
+ * like checkboxes and buttons.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic data cells
+ * <TableCell>@dwr.eth</TableCell>
+ * <TableCell className="text-right">1,234</TableCell>
+ * <TableCell className="font-medium">Active</TableCell>
+ *
+ * // Cell with checkbox
+ * <TableCell>
+ *   <Checkbox checked />
+ * </TableCell>
+ *
+ * // Cell with truncated content
+ * <TableCell className="max-w-[200px] truncate">
+ *   This is a very long piece of content...
+ * </TableCell>
+ *
+ * // Cell spanning multiple columns
+ * <TableCell colSpan={3} className="text-center">
+ *   No data available
+ * </TableCell>
+ * ```
+ *
+ * @accessibility
+ * - Semantic td element for data cells
+ * - Supports checkbox cells with proper alignment adjustments
+ * - Screen readers navigate cell by cell for data comprehension
+ * - ColSpan support for empty states and grouped content
+ * @since 1.0.0
+ */
+function TableCell({ className, ...props }: React.ComponentProps<"td">) {
+  return (
+    <td
+      data-slot="table-cell"
+      className={cn(
+        "p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * TableCaption - Table caption for describing table content and context
+ *
+ * Provides a description, title, or additional context for the table.
+ * Displayed with muted styling and proper spacing. Essential for accessibility
+ * as screen readers announce the caption to provide table context.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Table>
+ *   <TableCaption>Recent casts from your network</TableCaption>
+ *   <TableHeader>...</TableHeader>
+ *   <TableBody>...</TableBody>
+ * </Table>
+ *
+ * // Caption with additional context
+ * <Table>
+ *   <TableCaption>
+ *     Channel analytics for the last 30 days.
+ *     Data updated every hour.
+ *   </TableCaption>
+ *   <TableHeader>...</TableHeader>
+ *   <TableBody>...</TableBody>
+ * </Table>
+ * ```
+ *
+ * @accessibility
+ * - Semantic caption element positioned according to HTML standards
+ * - Screen readers announce caption before table content
+ * - Provides essential context for understanding table data
+ * - Helps users understand table purpose and scope
+ * @since 1.0.0
+ */
+function TableCaption({
+  className,
+  ...props
+}: React.ComponentProps<"caption">) {
+  return (
+    <caption
+      data-slot="table-caption"
+      className={cn("text-muted-foreground mt-4 text-sm", className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
+};